xref: /aosp_15_r20/external/pigweed/pw_symbolizer/docs.rst (revision 61c4878ac05f98d0ceed94b57d316916de578985) 
1.. _module-pw_symbolizer:
2
3=============
4pw_symbolizer
5=============
6
7.. warning::
8  This module is under construction and may not be ready for use.
9
10pw_symbolizer provides python-based tooling for symbolizing addresses emitted by
11on-device firmware.
12
13-----
14Usage
15-----
16Symbolizer
17==========
18The ``Symbolizer`` abstract base class is an interface for translating addresses
19to human-readable source locations. Different architectures and operating
20systems can require vastly different implementations, so this interface is
21provided to allow Pigweed tooling to symbolize addresses without requiring
22Pigweed to provide explicit support for all possible implementations.
23
24``Symbolizer`` Also provides a helper function for producing nicely formatted
25stack trace style dumps.
26
27.. code-block:: py
28
29   import pw_symbolizer
30
31   symbolizer = pw_symbolizer.LlvmSymbolizer(Path('device_fw.elf'))
32   print(symbolizer.dump_stack_trace(backtrace_addresses))
33
34Which produces output like this:
35
36.. code-block:: none
37
38   Stack Trace (most recent call first):
39      1: at device::system::logging_thread_context (0x08004BE0)
40         in threads.cc:0
41      2: at device::system::logging_thread (0x0800B508)
42         in ??:?
43      3: at device::system::logging_thread_context (0x08004CB8)
44         in threads.cc:0
45      4: at device::system::logging_thread (0x0800B3C0)
46         in ??:?
47      5: at device::system::logging_thread (0x0800B508)
48         in ??:?
49      6: at (0x0800BAF7)
50         in ??:?
51      7: at common::log::LoggingThread::Run() (0x0800BAD1)
52         in out/common/log/logging_thread.cc:26
53      8: at pw::thread::threadx::Context::ThreadEntryPoint(unsigned long) (0x0800539D)
54         in out/pigweed/pw_thread_threadx/thread.cc:41
55      9: at device::system::logging_thread_context (0x08004CB8)
56         in threads.cc:0
57     10: at device::system::logging_thread_context (0x08004BE0)
58         in threads.cc:0
59
60FakeSymbolizer
61==============
62The ``FakeSymbolizer`` is utility class that implements the ``Symbolizer``
63interface with a fixed database of address to ``Symbol`` mappings. This is
64useful for testing, or as a no-op ``Symbolizer``.
65
66.. code-block:: py
67
68   import pw_symbolizer
69
70   known_symbols = (
71       pw_symbolizer.Symbol(0x0800A200, 'foo()', 'src/foo.c', 41),
72       pw_symbolizer.Symbol(0x08000004, 'boot_entry()', 'src/vector_table.c', 5),
73   )
74   symbolizer = pw_symbolizer.FakeSymbolizer(known_symbols)
75   sym = symbolizer.symbolize(0x0800A200)
76   print(f'This fake symbolizer knows about: {sym}')
77
78LlvmSymbolizer
79==============
80The ``LlvmSymbolizer`` is a python layer that wraps ``llvm-symbolizer`` to
81produce symbols from provided addresses. This module requires either:
82
83* ``llvm-symbolizer`` is available on the system ``PATH``.
84* ``llvm_symbolizer_binary`` argument is specified and points to the executable.
85
86This object also defines a ``close`` to ensure the background process is
87cleaned up deterministically.
88
89.. code-block:: py
90
91   import pw_symbolizer
92
93   symbolizer = pw_symbolizer.LlvmSymbolizer(Path('device_fw.elf'))
94   sym = symbolizer.symbolize(0x2000ac21)
95   print(f'You have a bug here: {sym}')
96