diff --git a/docs/core/systemview/Ozone_ETM_trace_code_profiling.png b/docs/core/systemview/Ozone_ETM_trace_code_profiling.png new file mode 100644 index 000000000..1b0164f29 Binary files /dev/null and b/docs/core/systemview/Ozone_ETM_trace_code_profiling.png differ diff --git a/docs/core/systemview/RTTViewer_20201215_165241.png b/docs/core/systemview/RTTViewer_20201215_165241.png new file mode 100644 index 000000000..0a0e72e21 Binary files /dev/null and b/docs/core/systemview/RTTViewer_20201215_165241.png differ diff --git a/docs/core/systemview/SystemView_debug_interrupts.png b/docs/core/systemview/SystemView_debug_interrupts.png new file mode 100644 index 000000000..f335fd517 Binary files /dev/null and b/docs/core/systemview/SystemView_debug_interrupts.png differ diff --git a/docs/core/systemview/index.md b/docs/core/systemview/index.md new file mode 100644 index 000000000..9154c4673 --- /dev/null +++ b/docs/core/systemview/index.md @@ -0,0 +1,91 @@ +# Debugging events with SystemView and Real-time Terminal (Trezor T only) + +Systemview is an utility to debug interrupts or other events, counters, logs +which does not require any extra pin (except the SWD pins attached to CPU). + +An example showing two interrupts, and debug log passed via memory instead of UART. + +![SystemView](SystemView_debug_interrupts.png) + +Second example is RTT with color logging (kind of subset what SystemView can do, +sans the colors). + +![Realtime Terminal](RTTViewer_20201215_165241.png) + +Compared to UART the speed of counters or messages is enormously faster as SystemView +does trick where it stores all in a small location in RAM (cyclic buffer) + +This requires JLink/JTrace adapter and [SystemView](https://www.segger.com/products/development-tools/systemview/) +installed. SystemView is available as free/educational or commercial licensed. + +## Building with SystemView enabled + +Clean build in `core`: + + make clean + +### Enable SYSTEM_VIEW + +Change in `SConscript.firmware`: `PYOPT` to `0` (not strictly necessary, but you won't see +debug messages otherwise, though this enables to use it also on non-debug build). + +Then it's suggested to change `OPTIMIZE` to `-Og` instead of `-Os` which will still +does optimizations, but only a subset that does hinder debug by reordering +instructions. + + PYOPT = ARGUMENTS.get('PYOPT', '0') + COPT=os.getenv('OPTIMIZE', '-Og') + +Then enable the SYSTEM_VIEW feature in `FEATURE_FLAGS`: + + FEATURE_FLAGS = { + "RDI": True, + "SECP256K1_ZKP": False, + "SYSTEM_VIEW": True, + } + + +Then in `core/src/trezor/log.py` change color to False, SystemView does not support +colorful messages (lines will be garbled), but if you want colors you can also use +Real-time terminal (RTT, see below) + + set color = False + +Then build with (change PYOPT or BITCOIN_ONLY as needed): + + V=1 VERBOSE=1 PYOPT=0 BITCOIN_ONLY=1 SYSTEM_VIEW=1 make build_embed + +After flashing with: + + make flash_firmware_jlink + +You should be able to conect with SystemView or RTT and collect the data and analyze +them. + +### Sending data to RTT instead of SystemView + +There are two mutually exclusive macros, first one is turned on by default and sends +data to SystemView. Changing data sending to RTT is just undefining first and defining +second (in theory it could be able to send to both destinations, but never tried it.) + + * `SYSTEMVIEW_DEST_SYSTEMVIEW` + * `SYSTEMVIEW_DEST_RTT` + +Now when you run `JLinkRTTViewerExe` you should see data in the terminal: + +![Realtime Terminal](RTTViewer_20201215_165241.png) + +It is possible to extend this mechanism to include multiple streams/terminals. +Terminals work like a usual terminal, so you can use it in debugging also for +user input. + +## Combining SystemView/RTT with other debug tools + +In general you can use SystemView along with GDB/CLion/Ozone or other debugger at the +same time, it's just advised that you keep all connections at the same frequency, +otherwise it may lead to unexpected behavior, weird resets, etc. + +So e.g. you can profile the interrupts, DMA in SystemView while also profiling it on +instruction-level scale in Ozone: + +![Ozone ETM trace with code profile](Ozone_ETM_trace_code_profiling.png) diff --git a/docs/index.md b/docs/index.md index ecedafe4f..df2514f45 100644 --- a/docs/index.md +++ b/docs/index.md @@ -11,6 +11,7 @@ Welcome to the Trezor Firmware repository. This repository is so called _monorep * **[`common/protob`](https://github.com/trezor/trezor-firmware/tree/master/common/protob/)**: Common protobuf definitions for the Trezor protocol * **[`common/tools`](https://github.com/trezor/trezor-firmware/tree/master/common/tools/)**: Tools for managing coin definitions and related data * **[`core`](https://github.com/trezor/trezor-firmware/tree/master/core/)**: Trezor Core, firmware implementation for Trezor T +* **[`core/systemview`](https://github.com/trezor/trezor-firmware/tree/master/core/systemview)**: Hardware instrumentation and debugging with SystemView for Trezor T * **[`crypto`](https://github.com/trezor/trezor-firmware/tree/master/crypto/)**: Stand-alone cryptography library used by both Trezor Core and the Trezor One firmware * **[`docs`](https://github.com/trezor/trezor-firmware/tree/master/docs/)**: Assorted documentation * **[`legacy`](https://github.com/trezor/trezor-firmware/tree/master/legacy/)**: Trezor One firmware implementation