From 470f66f387ba9c733b711269267bd6bb45d701b9 Mon Sep 17 00:00:00 2001 From: Piotr Esden-Tempski Date: Mon, 22 Aug 2022 16:25:43 -0700 Subject: [PATCH] rtt: Cleaned up updated and improved the RTT usage documentation. This resulted in a small addition to the drivers readme adding some basic udev rule installation instructions. --- UsingRTT.md | 152 ++++++++++++++++++++++++++++++----------------- driver/README.md | 21 +++++-- 2 files changed, 112 insertions(+), 61 deletions(-) diff --git a/UsingRTT.md b/UsingRTT.md index ef3fb88..0afdc69 100644 --- a/UsingRTT.md +++ b/UsingRTT.md @@ -1,17 +1,24 @@ # Using RTT -When debugging arm processors, there are three ways for the target to print debug messages on the host: Semihosting, Serial Wire Output SWO, and Real-Time Transfer RTT. +When debugging ARM processors, there are multiple ways for the target to print debug messages on +the host: a dedicated UART port (USB to Serial) aka. AUX Serial, Semihosting, Serial Wire Output SWO, and Real-Time Transfer RTT. -[Black Magic Probe](https://github.com/blacksphere/blackmagic) (BMP) is an open source debugger probe that already implements Semihosting and Single Wire Output. This patch adds Real-Time Transfer RTT output to usb serial port. +This RTT implementation replaces the AUX USB serial port with RTT. To enable RTT in [Black +Magic Debug](https://black-magic.org) (BMD) Firmware the `ENABLE_RTT=1` flag has to be set +during compilation. RTT is not compiled in by default into the release binaries as it replaces +the AUX USB to Serial conversion capability. For more details refer to the [Build +Instructions](#build-instructions) section. -- RTT is implemented, not as a user program, but as a serial port device. To read RTT output, use a terminal emulator and connect to the serial port. +The RTT solution implemented in BMD is using a novel way to detect RTT automatically, making +the use fast and convenient. -- A novel way to detect RTT automatically, fast and convenient. +## Usage -## Use -This example uses linux as operating system. For Windows and MacOS see the *Operating Systems* section. +This example uses Linux as operating system. For Windows and MacOS see the *Operating Systems* +section. -In one window open a terminal emulator (minicom, putty) and connect to the usb uart: +In one window open a terminal emulator (minicom, putty) and connect to the USB +UART: ``` $ minicom -c on -D /dev/ttyBmpTarg ``` @@ -30,11 +37,11 @@ rtt: on found: yes ident: off halt: off channels: auto 0 1 3 max poll ms: 256 min poll ms: 8 max errs: 10 ``` -The terminal emulator displays RTT output from the target, -and characters typed in the terminal emulator are sent via RTT to the target. +The terminal emulator displays RTT output from the target, and characters typed +in the terminal emulator are sent via RTT to the target. -## gdb commands +## GDB Commands The following new gdb commands are available: @@ -52,7 +59,10 @@ The following new gdb commands are available: - ``monitor rtt poll `` max_poll_ms min_poll_ms max_errs - sets maximum time between polls, minimum time between polls, and the maximum number of errors before RTT disconnects from the target. Times in milliseconds. It is best if max_poll_ms/min_poll_ms is a power of two. As an example, if you wish to check for RTT output between once per second to eight times per second: ``monitor rtt poll 1000 125 10``. + sets maximum time between polls, minimum time between polls, and the maximum number of + errors before RTT disconnects from the target. Times in milliseconds. It is best if + max_poll_ms/min_poll_ms is a power of two. As an example, if you wish to check for RTT + output between once per second to eight times per second: ``monitor rtt poll 1000 125 10``. - ``monitor rtt status`` @@ -65,7 +75,9 @@ rtt: on|found: no|searching for rtt control block rtt: on|found: yes|rtt active rtt: off|found: yes|corrupt rtt control block, or target memory access error -A status of `rtt: on found: no` indicates bmp is still searching for the rtt control block in target ram, but has not found anything yet. A status of `rtt: on found: yes` indicates the control block has been found and rtt is active. +A status of `rtt: on found: no` indicates bmp is still searching for the rtt control block in +target ram, but has not found anything yet. A status of `rtt: on found: yes` indicates the +control block has been found and rtt is active. - ``monitor rtt channel`` @@ -73,11 +85,13 @@ A status of `rtt: on found: no` indicates bmp is still searching for the rtt con - ``monitor rtt channel number...`` - enables the given RTT channel numbers. Channels are numbers from 0 to 15, inclusive. Eg. ``monitor rtt channel 0 1 4`` to enable channels 0, 1, and 4. + enables the given RTT channel numbers. Channels are numbers from 0 to 15, inclusive. + Eg. ``monitor rtt channel 0 1 4`` to enable channels 0, 1, and 4. - ``monitor rtt ident string`` - sets RTT ident to *string*. If *string* contains a space, replace the space with an underscore _. Setting ident string is optional, RTT works fine without. + sets RTT ident to *string*. If *string* contains a space, replace the space with an + underscore _. Setting ident string is optional, RTT works fine without. - ``monitor rtt ident`` @@ -85,8 +99,9 @@ A status of `rtt: on found: no` indicates bmp is still searching for the rtt con - ``monitor rtt cblock`` - shows rtt control block data, and which channels are enabled. This is an example control block: - + shows rtt control block data, and which channels are enabled. This is an example + control block: + ``` (gdb) mon rtt cb cbaddr: 0x200000a0 @@ -109,19 +124,27 @@ ch ena cfg i/o buf@ size head@ tail@ flg 15 n n in 0x00000000 0 0x00000000 0x00000000 0 ``` -Channels are listed, one channel per line. The columns are: channel, enabled, configured, input/output, buffer address, buffer size, address of head pointer, address of tail pointer, flag. Each channel is a circular buffer with head and tail pointer. - +Channels are listed, one channel per line. The columns are: channel, enabled, configured, +input/output, buffer address, buffer size, address of head pointer, address of tail pointer, +flag. Each channel is a circular buffer with head and tail pointer. + Note the columns `ena` for enabled, `cfg` for configured. - -Configured channels have a non-zero buffer address and non-zero size. Configured channels are marked yes `y` in the column `cfg` . What channels are configured depends upon target software. - -Channels the user wants to see are marked yes `y` in the column enabled `ena`. The user can change which channels are shown with the `monitor rtt channel` command. -Output channels are displayed, and Input channels receive keyboard input, if they are marked yes in both *enabled* and *configured*. +Configured channels have a non-zero buffer address and non-zero size. Configured channels are +marked yes `y` in the column `cfg` . What channels are configured depends upon target +software. -The control block is cached for speed. In an interrupted program, `monitor rtt` will force a reload of the control block when the program continues. +Channels the user wants to see are marked yes `y` in the column enabled `ena`. The user can +change which channels are shown with the `monitor rtt channel` command. + +Output channels are displayed, and Input channels receive keyboard input, if they are marked +yes in both *enabled* and *configured*. + +The control block is cached for speed. In an interrupted program, `monitor rtt` will force a +reload of the control block when the program continues. + +## Identifier String -## Identifier string It is possible to set an RTT identifier string. As an example, if the RTT identifier is "IDENT STR": ``` @@ -139,17 +162,19 @@ max poll ms: 256 min poll ms: 8 max errs: 10 ``` Note replacing space with underscore _ in *monitor rtt ident*. -Setting an identifier string is optional. RTT gives the same output at the same speed, with or without specifying identifier string. +Setting an identifier string is optional. RTT gives the same output at the same speed, with or +without specifying identifier string. -## Operating systems +## Operating Systems -[Configuration](https://black-magic.org/getting-started.html) instructions for windows, linux and macos. +[Configuration](https://black-magic.org/getting-started.html) instructions for Windows, Linux and MacOS. ### Windows After configuration, Black Magic Probe shows up in Windows as two _USB Serial (CDC)_ ports. -Connect arm-none-eabi-gdb, the gnu debugger for arm processors, to the lower numbered of the two COM ports. Connect an ansi terminal emulator to the higher numbered of the two COM ports. +Connect arm-none-eabi-gdb, the gnu debugger for arm processors, to the lower numbered of the +two COM ports. Connect an ansi terminal emulator to the higher numbered of the two COM ports. Sample gdb session: ``` @@ -165,10 +190,14 @@ For COM port COM10 and higher, add the prefix `\\.\`, e.g. target extended-remote \\.\COM10 ``` -Target RTT output will appear in the terminal, and what you type in the terminal will be sent to the RTT input of the target. +Target RTT output will appear in the terminal, and what you type in the terminal will be sent +to the RTT input of the target. -### linux -On linux, install [udev rules](https://github.com/blacksphere/blackmagic/blob/master/driver/99-blackmagic.rules). Disconnect and re-connect the BMP. Check the device shows up in /dev/ : +### Linux + +On Linux, install udev rules as described in the [driver +documentation](https://github.com/blackmagic-debug/blackmagic/blob/main/driver/README.md). +Disconnect and re-connect the BMP. Check the device shows up in /dev/ : ``` $ ls -l /dev/ttyBmp* lrwxrwxrwx 1 root root 7 Dec 13 07:29 /dev/ttyBmpGdb -> ttyACM0 @@ -192,7 +221,10 @@ gdb ### MacOS -On MacOS the tty devices have different names than on linux. On connecting blackmagic to the computer 4 devices are created, 2 'tty' and 2 'cu' devices. Gdb connects to the first cu device (e.g.: `target extended-remote /dev/cu.usbmodemDDCEC9EC1`), while RTT is connected to the second tty device (`minicom -c on -D /dev/tty.usbmodemDDCEC9EC3`). In full: +On MacOS the tty devices have different names than on linux. On connecting blackmagic to the +computer 4 devices are created, 2 'tty' and 2 'cu' devices. Gdb connects to the first cu device +(e.g.: `target extended-remote /dev/cu.usbmodemDDCEC9EC1`), while RTT is connected to the +second tty device (`minicom -c on -D /dev/tty.usbmodemDDCEC9EC3`). In full: In one Terminal window, connect a terminal emulator to /dev/tty.usbmodemDDCEC9EC3 : @@ -214,19 +246,26 @@ RTT input/output is in the window running _minicom_. - Design goal was smallest, simplest implementation that has good practical use. -- RTT code size is 3.5 kbyte - the whole debugger 110 kbyte. +- RTT code size is ~3.5 kbytes. -- Because RTT is implemented as a serial port device, there is no need to write and maintain software for different host operating systems. A serial port works everywhere - linux, windows and mac. You can even use an Android mobile phone as RTT terminal. +- Because RTT is implemented as a serial port device, there is no need to write and maintain + software for different host operating systems. A serial port works everywhere - Linux, +Windows and MacOS. You can even use an Android mobile phone as RTT terminal. -- Because polling occurs between debugger probe and target, the load on the host is small. There is no constant usb traffic, there are no real-time requirements on the host. +- Because polling occurs between debugger probe and target, the load on the host is small. + There is no constant usb traffic, there are no real-time requirements on the host. -- RTT polling frequency is adaptive and goes up and down with RTT activity. Use *monitor rtt poll* to balance response speed and target load for your use. +- RTT polling frequency is adaptive and goes up and down with RTT activity. Use *monitor rtt + poll* to balance response speed and target load for your use. - Detects RTT automatically, very convenient. -- When using RTT as a terminal, sending data from host to target, you may need to change local echo, carriage return and/or line feed settings in your terminal emulator. +- When using RTT as a terminal, sending data from host to target, you may need to change local + echo, carriage return and/or line feed settings in your terminal emulator. -- Architectures such as risc-v may not allow the debugger access to target memory while the target is running. As a workaround, on these architectures RTT briefly halts the target during polling. If the target is halted during polling, `monitor rtt status` shows `halt: on`. +- Architectures such as risc-v may not allow the debugger access to target memory while the + target is running. As a workaround, on these architectures RTT briefly halts the target +during polling. If the target is halted during polling, `monitor rtt status` shows `halt: on`. - Measured RTT speed. @@ -236,34 +275,35 @@ RTT input/output is in the window running _minicom_. | bmp stm32f411 black pill | 50073 | | bmp stm32f103 blue pill | 50142 | -This is the speed at which characters can be sent from target to debugger probe, in reasonable circumstances. Test target is an stm32f103 blue pill running an [Arduino sketch](https://github.com/koendv/Arduino-RTTStream/blob/main/examples/SpeedTest/SpeedTest.ino). Default *monitor rtt poll* settings on debugger. Default RTT buffer size in target and debugger. Overhead for printf() calls included. +This is the speed at which characters can be sent from target to debugger probe, in reasonable +circumstances. Test target is an stm32f103 blue pill running an [Arduino +sketch](https://github.com/koendv/Arduino-RTTStream/blob/main/examples/SpeedTest/SpeedTest.ino). +Default *monitor rtt poll* settings on debugger. Default RTT buffer size in target and +debugger. Overhead for printf() calls included. + +## Build instructions -## Compiling firmware To compile with RTT support, add *ENABLE_RTT=1*. -Eg. for STM32F103 blue pill: +Eg. for Black Magic Probe (native) hardware: ``` make clean -make PROBE_HOST=stlink ENABLE_RTT=1 +make ENABLE_RTT=1 ``` -or for the STM32F411 *[Black Pill](https://www.aliexpress.com/item/1005001456186625.html)*: + +Setting an ident string is optional. But if you wish, you can set the default RTT ident at +compile time. + +Eg. for Black Magic Probe (native) hardware: ``` make clean -make PROBE_HOST=blackpillv2 ENABLE_RTT=1 -``` -Setting an ident string is optional. But if you wish, you can set the default RTT ident at compile time. -For STM32F103 *Blue Pill*: -``` -make clean -make PROBE_HOST=stlink ENABLE_RTT=1 "RTT_IDENT=IDENT\ STR" -``` -or for STM32F411 *Black Pill*: -``` -make clean -make PROBE_HOST=blackpillv2 ENABLE_RTT=1 "RTT_IDENT=IDENT\ STR" +make ENABLE_RTT=1 "RTT_IDENT=IDENT\ STR" ``` Note the backslash \\ before the space. +When compiling for other targets like bluepill, blackpill or stlink, the `PROBE_HOST` variable +has to be also set appropriately, selecting the correct host target. + ## Links - [OpenOCD](https://openocd.org/doc/html/General-Commands.html#Real-Time-Transfer-_0028RTT_0029) - [probe-rs](https://probe.rs/) and [rtt-target](https://github.com/mvirkkunen/rtt-target) for the _rust_ programming language. diff --git a/driver/README.md b/driver/README.md index 10a15f4..1aba649 100644 --- a/driver/README.md +++ b/driver/README.md @@ -7,6 +7,17 @@ This directory contains a few different important files described in the section * [blackmagic.inf](#blackmagicinf) * [blackmagic_upgrade.inf](#blackmagic_upgradeinf) +## udev rules installation + +Depending on the specific distribution you can choose either the `plugdev` or `uucp` versions +of udev rules. For more information about the distributions and what the differences are refer +to the following sections. + +Independent of which udev rule file is used, the selected file has to be copied into +`/etc/udev/rules.d` directory. The udev rules can then be reloaded with `sudo udevadm control +--reload-rules`. After that the Black Magic Probe can be connected to the system and the new +rules should apply to the connected device. + ## 99-blackmagic-plugdev.rules This file contains [udev](https://www.freedesktop.org/wiki/Software/systemd) rules for Linux @@ -23,9 +34,9 @@ Distros that use 'plugdev' for this purpose include: ## 99-blackmagic-uucp.rules This file contains [udev](https://www.freedesktop.org/wiki/Software/systemd) rules for Linux -systems that use 'uucp' as the access group for plug-in devices. This allows GDB, dfu-util, -and other utilities access to your Black Magic Probe hardware without needing `sudo` / root on -the computer you're trying to access the hardware from. +systems that use 'uucp' as the access group for plug-in devices. This allows GDB, dfu-util, and +other utilities access to your Black Magic Probe hardware without needing `sudo` / root on the +computer you're trying to access the hardware from. Distros that use 'uucp' for this purpose include: @@ -35,8 +46,8 @@ Distros that use 'uucp' for this purpose include: ## Notes about udev rules Our udev rules include use of the 'uaccess' tag which means either rules file should just work -on any modern distro that uses systemd. The specific user access group only matters when not using -systemd, or on older distros that predate the user access tag. +on any modern distro that uses systemd. The specific user access group only matters when not +using systemd, or on older distros that predate the user access tag. ## blackmagic.inf