pw_symbolizer

Pigweed AI summary: The pw_symbolizer module is a tool for symbolizing addresses emitted by on-device firmware. It provides an interface for translating addresses to human-readable source locations, with different implementations for different architectures and operating systems. The module includes a Symbolizer abstract base class, a FakeSymbolizer utility class for testing, and an LlvmSymbolizer that wraps llvm-symbolizer to produce symbols from provided addresses. The module is still under construction and may not be ready for use.

Warning

This module is under construction and may not be ready for use.

pw_symbolizer provides python-based tooling for symbolizing addresses emitted by on-device firmware.

Usage

Pigweed AI summary: The "Symbolizer" abstract base class is an interface for translating addresses to human-readable source locations, allowing Pigweed tooling to symbolize addresses without requiring Pigweed to provide explicit support for all possible implementations. It also provides a helper function for producing nicely formatted stack trace style dumps. The "FakeSymbolizer" is a utility class that implements the "Symbolizer" interface with a fixed database of address to symbol mappings, useful for testing or as a no-op "Symbolizer". The "L

Symbolizer

Pigweed AI summary: The Symbolizer abstract base class is used to translate addresses to human-readable source locations, allowing Pigweed tooling to symbolize addresses without requiring explicit support for all possible implementations. It also provides a helper function for producing nicely formatted stack trace style dumps. The provided code example shows how to use the LlvmSymbolizer to produce a stack trace output.

The Symbolizer abstract base class is an interface for translating addresses to human-readable source locations. Different architectures and operating systems can require vastly different implementations, so this interface is provided to allow Pigweed tooling to symbolize addresses without requiring Pigweed to provide explicit support for all possible implementations.

Symbolizer Also provides a helper function for producing nicely formatted stack trace style dumps.

import pw_symbolizer

symbolizer = pw_symbolizer.LlvmSymbolizer(Path('device_fw.elf'))
print(symbolizer.dump_stack_trace(backtrace_addresses))

Which produces output like this:

Stack Trace (most recent call first):
   1: at device::system::logging_thread_context (0x08004BE0)
      in threads.cc:0
   2: at device::system::logging_thread (0x0800B508)
      in ??:?
   3: at device::system::logging_thread_context (0x08004CB8)
      in threads.cc:0
   4: at device::system::logging_thread (0x0800B3C0)
      in ??:?
   5: at device::system::logging_thread (0x0800B508)
      in ??:?
   6: at (0x0800BAF7)
      in ??:?
   7: at common::log::LoggingThread::Run() (0x0800BAD1)
      in out/common/log/logging_thread.cc:26
   8: at pw::thread::threadx::Context::ThreadEntryPoint(unsigned long) (0x0800539D)
      in out/pigweed/pw_thread_threadx/thread.cc:41
   9: at device::system::logging_thread_context (0x08004CB8)
      in threads.cc:0
  10: at device::system::logging_thread_context (0x08004BE0)
      in threads.cc:0

FakeSymbolizer

Pigweed AI summary: The FakeSymbolizer is a utility class that implements the Symbolizer interface with a fixed database of address to Symbol mappings. It is useful for testing or as a no-op Symbolizer. The code example provided imports pw_symbolizer, defines known symbols, creates a FakeSymbolizer with the known symbols, symbolizes an address, and prints the result.

The FakeSymbolizer is utility class that implements the Symbolizer interface with a fixed database of address to Symbol mappings. This is useful for testing, or as a no-op Symbolizer.

import pw_symbolizer

known_symbols = (
    pw_symbolizer.Symbol(0x0800A200, 'foo()', 'src/foo.c', 41),
    pw_symbolizer.Symbol(0x08000004, 'boot_entry()', 'src/vector_table.c', 5),
)
symbolizer = pw_symbolizer.FakeSymbolizer(known_symbols)
sym = symbolizer.symbolize(0x0800A200)
print(f'This fake symbolizer knows about: {sym}')

LlvmSymbolizer

Pigweed AI summary: The LlvmSymbolizer is a python module that uses llvm-symbolizer to produce symbols from provided addresses. It requires llvm-symbolizer to be available on the system PATH. The code example shows how to use the module to symbolize a specific address in an ELF file.

The LlvmSymbolizer is a python layer that wraps llvm-symbolizer to produce symbols from provided addresses. This module will only work if llvm-symbolizer is available on the system PATH.

import pw_symbolizer

symbolizer = pw_symbolizer.LlvmSymbolizer(Path('device_fw.elf'))
sym = symbolizer.symbolize(0x2000ac21)
print(f'You have a bug here: {sym}')