SerialWireOutput

Serial Wire Output library for STM32duino ARM Arduinos

With Serial Wire Output (SWO) an stm32duino can write tracing and logging to a pc at high speed. For SWO to work, you need a debugger probe to connect the program on your arduino to the debugger on your pc. SWO only runs on systems with arm processors, sorry.

Installation

• install the arduino IDE
• install STM32duino library
• install SerialWireOutput (this library)
• connect a debugger probe with SWO support, e.g. a segger or a black magic probe. Connect the SWO output of the target with the SWO input of the probe.
• start tool to view the SWO stream.
• run example File→Examples→SerialWireOutput→HelloWorld

Connection Diagram

This is one way to connect a STM32F103 Blue Pill with a Black Magic Probe. This allows downloading firmware and debugging using SWD. At the same time, SWO provides high speed debugging output.

Take care to connect only one power source to a Blue Pill board; feeding power through usb and a power pin at the same time may cause short circuit.

Arduino Use

Use SWOStream where you would use Serial:

#include <SWOStream.h>
SWOStream s;
void setup() {
}
void loop() {
  s.print("hello world! ");
}

In the Arduino IDE, choose Tools→Upload Method→BMP (Black Magic Probe) and Tools→Optimize→Debug (-g).

When using e.g. Black Magic Probe you typically would use commands like:

koen@raspberrypi:~ $ gdb -q
(gdb) target extended-remote /dev/ttyBmpGdb
(gdb) monitor swdp_scan
Available Targets:
No. Att Driver
 1      STM32F1 medium density M3/M4
(gdb) attach 1
(gdb) file /tmp/arduino_build_195867/HelloWorld.ino.elf
(gdb) load
(gdb) monitor traceswo 2250000
(gdb) set mem inaccessible-by-default off
(gdb) run

Capturing the SWO stream

Your typical debugger comes with tool a tool to capture the SWO stream.

The commercial Jlink comes with SWO viewer.

The open source Black Magic Probe has the bmtrace SWO viewer:

Companion utilities are the bmdebug debugger and the bmflash flashing tool. These tools are open source, like the Black Magic Probe itself. Download the tools and the manual.

Instead of using an external viewer to do the decoding, Black Magic Probe can also output a decoded SWO stream. In the device manager, Black Magic Probe shows up as two COM ports. On Windows , connect PuTTY to the second of the two COM ports, labeled "Black Magic UART Port". On linux, type cat /dev/ttyBmpTarg. In another window, at the gdb prompt, type

(gdb) monitor traceswo 2250000 decode

to decode a 2250000 baud SWO stream. The decoded SWO stream is sent to the serial port and displayed by PuTTY.

SWOStream

The SWOStream Arduino class allows you to write tracing and logging to the PC where the debugger is running. Setup parameters are:

baudRate Set baud rate.

If the baud rate is zero, the SWOStream class will not set up the SWO pin. This can be used if the debugger, SWO viewer, or another SWOStream has already set up SWO.

On a STM32F103-based Black Magic Probe, baud rate has to be 4500000 divided by an integer: 4500000, 2250000, 1500000, 1125000, 900000, 750000, ... . On a bmp clone, 2250000 is a safe choice.

There is no default value. Check what baud rates your debugger supports.

swoProtocol Protocol is SWO_Manchester or SWO_Async (asynchronous). Default value is SWO_Async .

swoChannel a number between 0 and 31, used to distinguish different SWO streams. The default is 0, a safe choice.

swoEnable set this to false to instantiate with SWO disabled. Default value is true.

cpuClockFrequency Set this if your board has a non-standard crystal.

SWO without debugger

Some processors hang at power-up if you print to SWO and there is no debugger attached. As a workaround, boot with SWO disabled, and enable SWO from the debugger. To disable SWO at boot, instantiate with the fourth argument of SWOStream false, like this:

#include <SWOStream.h>
SWOStream s(2250000, SWO_Async, 0, false); // swoEnable=false
int n=0;
void setup() {
  pinMode(LED_BUILTIN, OUTPUT);
}

void loop() {
  digitalWrite(LED_BUILTIN, HIGH);
  delay(100);
  digitalWrite(LED_BUILTIN, LOW);
  delay(100);
  s.print(n++);
  s.print(" hello, world! \n");
  s.flush();
}

The program will start up with SWO disabled. To enable SWO from gdb, type:

(gdb) target extended-remote /dev/ttyBmpGdb
(gdb) monitor swd
(gdb) attach 1
(gdb) monitor traceswo decode
(gdb) set mem inaccessible-by-default off
(gdb) run

Interrupt with ctrl-C:

^C
Program received signal SIGINT, Interrupt.

Set Trace Enable Register all ones and continue execution:

(gdb) set {int}0xE0000E00=-1
(gdb) continue

To disable SWO from the gdb command prompt, interrupt with ctrl-C and type:

^C
Program received signal SIGINT, Interrupt.
(gdb) set {int}0xE0000E00=0
(gdb) continue

Acks

Thanks to orbuculum, Black Magic Probe book, and Stephen P. WIlliams.

If you find errors, omissions, or have additional data, feel free to open an issue.