SWDCOM README¶
See also
This project:¶
A STM32 technology demonstrator showcasing the advantages of using the SWD (Serial Wire Debugging) interface as a Forth Terminal instead of the legacy serial USART. Typically a STMicro Discovery/nucleo board is used but can use a SWD-USB Programmer and a STM32F0xx mcu instead.
Credits¶
- SWDcom by Jan Bramkamp <https://github.com/Crest/swdcom>
- Mecrisp-Stellaris by Matthias Koch https://sourceforge.net/projects/mecrisp/
Serial communications¶
Forth is one of the oldest programming languages in existence having been developed in the early 70’s. In those days a computer running Forth usually communicated with a serial device, perhaps a Teletype or later a Wyse dedicated electronic terminal to allow interactive development and program uploading.
The availability of the IBM PC in the early 80’s (and other readily available portable computers) allowed the use of terminal emulators such as Picocom, Minicom etc running on the PC itself instead of dedicated terminals.
Legacy USART serial communications issues¶
| Issue | Description |
|---|---|
| Slow Uploads | Most Forths don’t go above 115200 Baud |
| No Handshaking | Require ‘end of line delays’ to prevent the Forth compiler ‘choking’ on uploaded source code |
| Dependencies | USARTS are dependent on the MCU system clock speed |
| Dongle | An external ‘USB to 3.3v Serial Dongle’ is required for most ‘development boards’ |
| Reset | Requires entering ‘reset’ into the Forth console |
Making Forth developer friendly in 2020¶
Swdcom, provides a SWD based usart replacement along with a PC based terminal client that works with Linux and FreeBSD plus offers upload times equal to or faster than the equivalent GCC with Stlink on the same PC. Forth realtime interactivity also further reduces project development time.
Swdcom advantages¶
| Feature | Description |
|---|---|
| Common Driver | Two sizes fits all; works across a range of the same class of mcu free from usart/pin dependencies. M0 or > M0 |
| Fast Comms | faster than a equivalent 460800 Baud serial terminal. |
| Fast Upload | STM32F407 @ 168 MHz with ART-5WS, uploads = 239,4 Words per second |
| Pasting | of multiple line source into the Terminal is problem free. |
| 256 chr Buffer | print 428 loops of the “The quick brown fox jumps over the lazy dog” to the terminal in under 10 uS on a STM32F051 |
| Handshaking | Inbuilt ACK flow control, no compiler ‘choking’ issues. |
| Clock | Independent of System Clock Speed. Comms doesnt stop when the clock is changed. |
| USB | Uses a single USB cable from the PC to most development boards or a usb/swd programmer for standalone mcus. |
| Reset | Resetting the target MCU is easily done by hitting CTRL+C on the PC keyboard. |
| GPIO’s | Enabling is NOT required for SWDCOM to work, so they are NOT pre-enabled as the Mecrisp-Stellaris default. |
Swdcom is very fast¶
Due to its inbuilt flow control and large 256 character buffer.
---------------------------
Library Upload Speed Stats:
---------------------------
Stats for the last 'make lib' source upload
Number of uploaded Words: 395
Source upload time : 8,89 seconds
Source upload/compile rate: 44,4 Words per second
Hardware: STM32F051
Upload method: SWD2 <https://github.com/Crest/swdcom>
Running SWDCOM¶
Has been tested under Debian-10.6-xfce and FreeBSD plus MAC OSX so it should work for you on those platforms.
Swdcom poribably won’t work on Microsoft Windows and MAC is untried.
FreeBSD¶
Needs the following: git, cmake, pkg-config
Debian-10.6-xfce¶
Needs the following items and you will need to be root to access the USB devices unless you have those permissions organised on your system:
git, cmake, pkg-config,libusb-1.0-0-dev, bc
Apple Mac OSX¶
Needs the following: git, cmake, usblib, pkg_config
Building SWDCOM¶
- Get SWDCOM
Official Repo¶
git clone https://github.com/Crest/swdcom.git, then type make etc.
Swdcom with stlink will be downloaded by Git and built in the swdom directory only, nothing is installed outside this directory on your system. It will not interfere with stlink if you have it on your system already.
Using SWDCOM¶
With a prepared Mecrisp-Binary¶
- You have a STM32 Disco or Nucleo or some form of programmer running stlink connected to a STM32 MCU
- The above is connected by a USB cable to your PC
- The above micro is running a SWDCOM modified Mecrisp-stellaris binary.
Premade Binary Downloads¶
Supported Hardware Families¶
These binaries may run on any chip within the same family, flash the binary and see if it can talk. Please email terry AT tjporter.com.au with the chip number if it does and I’ll add it to the supported list.
Warning
GPIO’s are NOT enabled as per the default USART kernels above. You need to enable them in your application code. Clock is the RC default usually 8 or 16 Mhz, again it’s up to you to change that as required in your application code.
Note
Some URL’s may have -xxxx.zip as it’s not known at the time of writing, kust look in the directory https://sourceforge.net/projects/mecrisp-stellaris-folkdoc/files to find what it is when you download. Use the latest one.
| MCU | Kernel Options | Binary URL |
|---|---|---|
| STM32L432 | 1,2,4,6,7 | https://sourceforge.net/projects/mecrisp-stellaris-folkdoc/files/STM32L432-SWDCOM-xxxx.zip |
| STM32F0xx | 1,2,3,4,5,6,7 | https://sourceforge.net/projects/mecrisp-stellaris-folkdoc/files/mecrisp-stellaris-2.5.4a-stm32f051-swdcom.bin |
| STM32F1xx | ||
| STM32F4xx | 1,3,4,6,7 | https://sourceforge.net/projects/mecrisp-stellaris-folkdoc/files/mecrisp-stellaris-stm32f407-swdcom.bin |
| patch | 1,3,4,6,7 | https://sourceforge.net/projects/mecrisp-stellaris-folkdoc/files/mecrisp-stellaris-stm32f407-swdcom.patch/download |
| STM32F7xx | 1,2,6,7 | https://sourceforge.net/projects/mecrisp-stellaris-folkdoc/files/mecrisp-stellaris-stm32f746-swdcom.bin |
| patch | 1,2,6,7 | https://sourceforge.net/projects/mecrisp-stellaris-folkdoc/files/mecrisp-stellaris-stm32f746-swdcom.patch |
Kernel Options¶
| Kernel Options | Description |
|---|---|
| 1 | context sensitive color prompt |
| 2 | all errors in red and beep terminal bell. Enter “;” at the terminal to test them. |
| 3 | “redefine” warning in red |
| 4 | Halts source file uploads on (or about) the first error, all errors in red and sound bell. Swdcom uploads are too fast to see! |
| 5 | Simplified stack print. “.s Stack: [0 ] 42 ok.” |
| 6 | Swdcom instead of usart user terminal |
| 7 | catchflashpointers.s/bl uart_init transposition. Essential for swdcom to work properly. |
Making your own Mecrisp-Stellaris-SWDCOM binary¶
> Cortex-M0¶
stm32f746-ra is used as an example.
- Replace mecrisp-stellaris-2.5.5/mecrisp-stellaris-source/stm32f746-ra/terminal.s with swdcom/terminal.s
- Edit mecrisp-stellaris-2.5.5/mecrisp-stellaris-source/stm32f746-ra/mecrisp-stellaris-stm32f746.s like so
Index: mecrisp-stellaris-2.5.5/mecrisp-stellaris-source/stm32f746-ra/mecrisp-stellaris-stm32f746.s
==================================================================
--- mecrisp-stellaris-2.5.5/mecrisp-stellaris-source/stm32f746-ra/mecrisp-stellaris-stm32f746.s
+++ mecrisp-stellaris-2.5.5/mecrisp-stellaris-source/stm32f746-ra/mecrisp-stellaris-stm32f746.s
@@ -68,14 +68,15 @@
@ -----------------------------------------------------------------------------
Reset: @ Einsprung zu Beginn
@ -----------------------------------------------------------------------------
@ Initialisierungen der Hardware, habe und brauche noch keinen Datenstack dafür
@ Initialisations for Terminal hardware, without Datastack.
- bl uart_init
+ @ bl uart_init @ moved by tp to suit SWDCOM
@ Catch the pointers for Flash dictionary
.include "../common/catchflashpointers.s"
+ bl uart_init
welcome " for STM32F746 by Matthias Koch"
@ Ready to fly !
.include "../common/boot.s"
- in mecrisp-stellaris-2.5.5/mecrisp-stellaris-source/stm32f746-ra/ type “make clean” then “make” and use the resultant binary in your MCU. If there is no binary generated, you have a error preventing the build completing.
Warning
when you perform step 3. make sure the compilation completes with no errors. If you get a error and need help, just email me with the details.
SWDCOM Console Commands¶
You must have built the swd2 executable FOR YOUR SYSTEM as in “Building SWDCOM” above.
Copy YOUR swd2 executable to your working project directory
Run the following to get a live Forth terminal to your mcu.
xterm -e ./swd2 &
The console will look and behave exactly like a USART connected terminal but with the SWDCOM advantages listed above
Uploading Files¶
To upload a file named “upload.fs” file via a control key¶
(ctrl)+$
To upload files via a script¶
- ::
- cat anyname.fs >upload.fs && pkill -QUIT swd2
To RESET the MCU¶
(ctrl)+c
Notes¶
All uploaded files will terminate with a visible SWDCOM control character, this is normal.
Swd2 Special Commands¶
(ctrl)+c Reset the Board
(ctrl)+$ Upload "upload.fs"
Kill Swd2¶
kill the running swd2 (in a FreeBSD Xterm)
pkill swd2
Why do we do the changes in step 2. above ?¶
Interview with the creator of SWDCOM (Jan Bramkamp):
<Jan Bramkamp> the normal uart_init function just initialises and writes to a bunch of memory mapped registers
<Jan Bramkamp> and enables the uart and all the GPIO's.
<Jan Bramkamp> swdcom works differently
<Jan Bramkamp> there is no peripheral to configure
<Jan Bramkamp> instead there is a pair of buffers in sram
<Jan Bramkamp> the first version of terminal.s required the kernel to define this statically
<Jan Bramkamp> but this requires a change outside the per chip port which Matthias doesn't like
<Jan Bramkamp> to minimize the change I call the allocate word from uart_init
<Jan Bramkamp> and allocate requires the dictionary pointers to be initialized
<Jan Bramkamp> which happens in the included catch pointers file
<me> thank you Jan, I'll add this to the swdcom page
Swdcom data corruption issues¶
If there is instability due to long cables etc the speed of swdcom can be reduced
to reduce the frequency?¶
search for STLINK_SWDCLK_4MHZ_DIVISOR in swd2.c
try STLINK_SWDCLK_240KHZ_DIVISOR instead
or even STLINK_SWDCLK_100KHZ_DIVISOR
possible values:
#define STLINK_SWDCLK_4MHZ_DIVISOR 0
#define STLINK_SWDCLK_1P8MHZ_DIVISOR 1
#define STLINK_SWDCLK_1P2MHZ_DIVISOR 2
#define STLINK_SWDCLK_950KHZ_DIVISOR 3
#define STLINK_SWDCLK_480KHZ_DIVISOR 7
#define STLINK_SWDCLK_240KHZ_DIVISOR 15
#define STLINK_SWDCLK_125KHZ_DIVISOR 31
#define STLINK_SWDCLK_100KHZ_DIVISOR 40
#define STLINK_SWDCLK_50KHZ_DIVISOR 79
#define STLINK_SWDCLK_25KHZ_DIVISOR 158
#define STLINK_SWDCLK_15KHZ_DIVISOR 265
#define STLINK_SWDCLK_5KHZ_DIVISOR 798
from stlink.h
