Debugging

GDB

Start a debug session with:

pbl debug

On QEMU boards this attaches GDB to the emulator through a proxy (tools/qemu/qemu_gdb_proxy.py) that walks the kernel’s thread list, so info threads and per-thread backtraces work. On real hardware, pbl debug is available on boards whose runner is OpenOCD (e.g. asterix, configured by boards/asterix/support/openocd.cfg); boards flashed via sftool do not support it.

PebbleOS GDB commands

tools/gdb_scripts/gdb_tintin.py extends GDB with a pbl command set. Load it inside GDB with:

(gdb) source tools/gdb_scripts/gdb_tintin.py
(gdb) pbl

Highlights (run pbl for the full list):

pbl heap / pbl heapstats: parse and profile the heaps
pbl sbt: stack backtrace and stack usage statistics
pbl layer-tree: dump the UI layer hierarchy
pbl app_symbols / pbl worker_symbols: load symbols for the currently running app or worker, so app crashes can be symbolicated
pbl fault_wizard: after a hard fault, restore the faulting $sp/$lr/ $pc so bt shows the crashing stack
pbl reboot_reason: decode the reboot reason from the RTC registers
pbl log-buffer: dump log messages still buffered in RAM
pbl to_png: render the framebuffer or a GBitmap to a PNG file

Console and logs

Attach to the firmware console with pbl console (add --tty for real hardware; see QEMU for the emulator ports). Firmware log messages are hashed at compile time — the binary only contains a hash and the arguments — and the console dehashes them on the fly using the dictionary generated by the build at build/fw/loghash_dict.json (build/prf/fw/loghash_dict.json for PRF builds). The dehashing code lives in tools/log_hashing/ and tools/libs/pebble-loghash/.

Logs are also persisted to a circular buffer in flash; tools/dehash_flash_logs.py parses and dehashes a dump of that region.

Coredumps

When the firmware crashes, it writes a coredump to SPI flash (see the architecture overview for the on-flash format).

tools/analyze_coredump.py <symbols.elf> <coredump> runs GDB in batch mode and prints a full report: backtraces for all threads, registers, heap and lock statistics, and build metadata.

You can also open a coredump interactively with arm-none-eabi-gdb-py <symbols.elf> -ex "core-file <coredump>" and use the pbl commands above.

Memory usage analysis

tools/ contains several ELF analyzers for RAM and flash footprint work, e.g. analyze_fw_static_memory_usage.py and analyze_mcu_flash_usage_treemap.py (renders an interactive treemap of flash usage).