.. index:: swdcom: readme,copyright,swdcom: advantages,swdcom: binaries,swd2: pkill,swd2: upload files .. _swdcom-install: SWDCOM Install ============== .. warning:: SWDCOM is ALPHA software, beware of sharp corners! .. seealso:: :ref:`SWDCOM` .. seealso:: :ref:`Swdcom Premade Binaries` For those who don't want to modify the kernel and compile their own. Has been tested under Debian-10.6-xfce and FreeBSD plus MAC OSX so it should work for you on those platforms. 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 STAGE 1 ------- .. _building-swd2: Building SWD2 ^^^^^^^^^^^^^ 1. Get SWDCOM from https://github.com/Crest/swdcom.git :: git clone https://github.com/Crest/swdcom.git 2. Enter the directory and type :: make 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. You should now have a SWD2 binary which you can install in your path and run on your PC. STAGE 2 ------- Modifying your Mecrisp-Stellaris Kernel ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Almost all Mecrisp-Stellaris releases come with serial terminal communication, so you will need to change yours to use SWDCOM instead. To do this, **four operations MUST be done**. 1. Swap SWDCOM for the terminal.s in your MCU source directory. 2. Transpose 'bl uart_init' in the 'system.s' file in your MCU source directory. 3. Recompile your MCU source directory. 4. Flash the new binary to your MCU. Cortex-M7 Example ^^^^^^^^^^^^^^^^^ stm32f746-ra is used as an example. 'system.s' is only a generic name, in reality it is the type of Mecrisp-Stellaris kernel and the model of MCU. For instance in this case 'system.s' is actually 'mecrisp-stellaris-stm32f746.s' Swap SWDCOM for the terminal.s ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Replace mecrisp-stellaris-X.X.X/mecrisp-stellaris-source/stm32f746-ra/terminal.s with swdcom/terminal.s Transpose 'bl uart_init' ^^^^^^^^^^^^^^^^^^^^^^^^ Edit mecrisp-stellaris-X.X.X/mecrisp-stellaris-source/stm32f746-ra/mecrisp-stellaris-stm32f746.s like so :: Edit file: mecrisp-stellaris-X.X.X/mecrisp-stellaris-source/stm32f746-ra/mecrisp-stellaris-stm32f746.s '-' means remove this line and '+' means add this line. @ Initialisierungen der Hardware, habe und brauche noch keinen Datenstack dafür @ Initialisations for Terminal hardware, without Datastack. - bl uart_init + @ bl uart_init @ transposed for SWDCOM @ Catch the pointers for Flash dictionary .include "../common/catchflashpointers.s" + bl uart_init .. warning:: It may appear that this step is not required but IT IS ESSENTIAL or you will have garbled characters, if not now, after a reboot etc. Recompile your MCU ^^^^^^^^^^^^^^^^^^ In mecrisp-stellaris-X.X.X/mecrisp-stellaris-source/stm32f746-ra/ type "make clean" then "make". If there is no binary generated, you have a error preventing the build completing. Check the date of the binary to confirm it is brand new. Flash the new binary ^^^^^^^^^^^^^^^^^^^^ Flash the new binary to your MCU. Using SWDCOM ------------ You must have built the *swd2* executable FOR YOUR SYSTEM as in :ref:`Building SWD2` above. **Copy YOUR swd2 executable to your working project directory or your path** 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' ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. warning:: 'upload.fs' is HARDWIRED into SWD2, you cannot use any other filename. :: (ctrl)+$ To upload files via a script ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. warning:: swd2 uploads from the CURRENT WORKING DIRECTORY :: cat anyname.fs >upload.fs && pkill -QUIT swd2 To RESET the MCU ---------------- :: (ctrl)+c To KILL swd2 in a xterm ----------------------- CTRL + D Notes ----- All uploaded files will terminate with a visible SWDCOM control character of '$19 emi', this is normal, just ignore it. Swd2 Special Commands --------------------- :: (ctrl)+c Reset the Board (ctrl)+$ Upload "upload.fs" Kill Swd2 To upload a file named ‘upload.fs’--------- kill the running swd2 (in a FreeBSD Xterm) :: pkill swd2 Why do we transpose bl uart_init? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Interview with the creator of SWDCOM (Jan Bramkamp): :: the default (usart) uart_init function just initialises and writes to a bunch of memory mapped registers and enables the uart and all the GPIO's. swdcom works differently there is no USART peripheral to configure instead there is a pair of buffers in sram to minimize the change I call the allocate word from uart_init and allocate requires the dictionary pointers to be initialized 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 * Contact us via irc if you run into trouble getting swdcom working for stm32 chips on freebsd, macos or linux * If someone wants to port Swdcom to windows they'll have to send Crest a pull request that doesn't add too much technical debt to the other platforms * CLOCKS: the clock difference is limited you can't run the swd interface a lot faster than the mcu core because at some point bits shifted in via swd have to be handed to the clocked parts of the arm core. E.g. don't try to run a 24MHz SWD link from an ST-LINK v3 to a STM32H7xx running at 32kHz of the LSE xtal Summary ------- Swdcom should now work for your MCU, providing a vastly superior system to the old serial USARTs.