docs(core/debug): documentation on debugging with SystemView/RTT

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)

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