Armando Montanez | 10f3beb | 2020-12-22 17:48:57 -0800 | [diff] [blame] | 1 | .. _module-pw_symbolizer: |
| 2 | |
| 3 | ------------- |
| 4 | pw_symbolizer |
| 5 | ------------- |
| 6 | |
| 7 | .. warning:: |
| 8 | This module is under construction and may not be ready for use. |
| 9 | |
| 10 | pw_symbolizer provides python-based tooling for symbolizing addresses emitted by |
| 11 | on-device firmware. |
| 12 | |
| 13 | LlvmSymbolizer |
| 14 | ============== |
| 15 | The ``LlvmSymbolizer`` is a python layer that wraps ``llvm-symbolizer`` to |
| 16 | produce symbols from provided addresses. |
| 17 | |
| 18 | .. code:: py |
| 19 | |
| 20 | import pw_symbolizer |
| 21 | |
| 22 | symbolizer = pw_symbolizer.LlvmSymbolizer(Path('device_fw.elf')) |
| 23 | sym = symbolizer.symbolize(0x2000ac21) |
| 24 | print(f'You have a bug here: {sym}') |
| 25 | |
| 26 | It can also be used to create nicely formatted symbolized stack traces. |
| 27 | |
| 28 | .. code:: py |
| 29 | |
| 30 | import pw_symbolizer |
| 31 | |
| 32 | symbolizer = pw_symbolizer.LlvmSymbolizer(Path('device_fw.elf')) |
| 33 | print(symbolizer.dump_stack_trace(backtrace_addresses)) |
| 34 | |
| 35 | Which produces output like this: |
| 36 | |
| 37 | .. code-block:: none |
| 38 | |
| 39 | Stack Trace (most recent call first): |
| 40 | 1: at device::system::logging_thread_context (0x08004BE0) |
| 41 | in threads.cc:0 |
| 42 | 2: at device::system::logging_thread (0x0800B508) |
| 43 | in ??:? |
| 44 | 3: at device::system::logging_thread_context (0x08004CB8) |
| 45 | in threads.cc:0 |
| 46 | 4: at device::system::logging_thread (0x0800B3C0) |
| 47 | in ??:? |
| 48 | 5: at device::system::logging_thread (0x0800B508) |
| 49 | in ??:? |
| 50 | 6: at (0x0800BAF7) |
| 51 | in ??:? |
| 52 | 7: at common::log::LoggingThread::Run() (0x0800BAD1) |
| 53 | in out/common/log/logging_thread.cc:26 |
| 54 | 8: at pw::thread::threadx::Context::ThreadEntryPoint(unsigned long) (0x0800539D) |
| 55 | in out/pigweed/pw_thread_threadx/thread.cc:41 |
| 56 | 9: at device::system::logging_thread_context (0x08004CB8) |
| 57 | in threads.cc:0 |
| 58 | 10: at device::system::logging_thread_context (0x08004BE0) |
| 59 | in threads.cc:0 |