sys64738
/
blackmagic
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

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.
This commit is contained in:
Piotr Esden-Tempski 2022-08-22 16:25:43 -07:00 committed by Rachel Mant
parent 5cc2ff0f3a
commit 470f66f387
2 changed files with 112 additions and 61 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

152
UsingRTT.md
View File

@ -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.

21
driver/README.md
View File

@ -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