.. _module-pw_symbolizer:

=============
pw_symbolizer
=============

.. 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
-----
Symbolizer
==========
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.

.. code-block:: py

   import pw_symbolizer

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

Which produces output like this:

.. code-block:: none

   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
==============
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``.

.. code-block:: py

   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
==============
The ``LlvmSymbolizer`` is a python layer that wraps ``llvm-symbolizer`` to
produce symbols from provided addresses. This module requires either:

* ``llvm-symbolizer`` is available on the system ``PATH``.
* ``llvm_symbolizer_binary`` argument is specified and points to the executable.

This object also defines a ``close`` to ensure the background process is
cleaned up deterministically.

.. code-block:: py

   import pw_symbolizer

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