Project History

THIS IS A HISTORICAL COPY OF WEBSITE DATED 2010..2013 THAT DOCUMENTS FROM SCRATCH RESEARCH AND DEVELOPMENT OF LIBSWD PROJECT TO SHOW HOW MUCH WORK IT REQUIRED

Table of Contents Introduction Software LibSWD UrJTAG KT-LINK driver for UrJTAG SWD implementation scratchpad Screenshots Default JTAG driver Transport Selection Detecting SWD Target OpenOCD SWD implementation scratchpad + LibSWD integration Screenshots Transport Infrastructure Interface Signal and Bitbang Infrastructure Interface configuration file and device specific scripting Transport initialization and IDCODE read First steps of SWD Target Hardware Strm32Primer Stm32Primer2 KT-LINK (FT2232H based, SWD ready) RLink Debug Access Port (DAP) Model / Design / Theory Introduction JTAG-DP Description JTAG-DP Registers JTAG Instruction Register (IR) JTAG Data Register (DR) ABORT (IR: b1111, DR: 1bit) IDCODE (IR:b1110, DR: 32bit) DPACC / APACC (DPAC_IR:b1010, APAC_IR:b1011, DR: 35bit) SW-DP Description Interface Reset and Synchronization SWD Packet Construction Successful Write Operation Successful Read Operation WAIT response to Read or Write operation request FAULT response to Read or Write operation request Protocol Error Sequence SW-DP Registers ABORT IDCODE, Identification Code Register CTRL/STAT, Control/Status Register SELECT, AP Select Register RDBUFF, Read Buffer WCR, Wire Control Register RESEND, Read Resend Register AHB-AP AHB-Lite master ports AHB-AP registers CSW, 0x00, AHB-AP Control/Status Word Register TAR, 0x04, AHB-AP Transfer Address Register DRW, 0x0C, AHB-AP Data Read/Write Register BD0-BD03, 0x10-Ox1C, AHB-AP Banked Data Registers ROM, 0xF8, ROM Address Register IDR, 0xFC, AHB-AP Identification Register AHB-AP clocks and resets Supported AHB protocol features HPROT encodings HRESP AHB-AP transfer types and bursts Packed transfers External and Memory Interfaces External interface Write buffer Memory attributes Memory interfaces = Common SWJ-DP Features Read and write errors Overrun detection Protocol errors, SW-DP only Pushed compare and pushed verify operations Example use of pushed verify operation on a AHB-AP Example use of pushed find operation on a AHB-AP Resources

Introduction

150px

This project was started by Tomek Cedro to create and document Free and Open-Source SWD (Serial Wire Debug) access to new ARM-Cortex cores. SWD is an alternative to JTAG method for accessing the TAP (Test Access Port) that allows low-level access to system resources such as system bus, memory, IO, even single stepping the code execution - a must-have for an embedded systems developer. Because Stm32Primer Development Kits designed by Raisonance are relatively cheap and freely accessible, they became my target hardware for this project. Please note that SWD will also work on more advanced devices from the ARM Cortex family. Some parts of this research are conducted as a cooperation between Orange Labs Warsaw and Orange Labs Paris, and some additionally by Cybernetic Research Student Group from Warsaw Univeristy of Technology in Poland that I am founder and member.

By default Cortex-design CPU or FPGA'a IP Core is both JTAG and SWD capable, so the common name for this access is SWJ (Serial Wire and JTAG). It is the application requirement and designer choice if a final product supports JTAG, SWD, or both (SWJ). Here you can read short and interesting article on how SWD overcomes JTAG limitations.

Software

Target software that allows JTAG access is OpenOCD (memory access + debug) and UrJTAG (low level operations). When this project started there was no SWD support in neither of these nice utilities, so it had to be created from scratch. Because UrJTAG is a bit simpler (no debug) I will start from this program to test low level operations on SWD, then move to OpenOCD and try the debug functionality.

Work in progress... meanwhile you can take a look at:

LibSWD

I have created LibSWD, open, flexible and platform independent Serial Wire Debug Open Framework, to provide universal API for SWD transport layer. LibSWD can be standalone or incorporated into existing low-level access utilities such as UrJTAG and OpenOCD extending their functionality and making use of existing components, such as drivers, but it also can become an integral part of the dedicated hardware firmware. There has been some releases of the LibSWD already, please take a look at the project website. Initial integration with UrJTAG is complete, but its implemented as standalone source code for now, after work on OpenOCD integration is complete I will come back to UrJTAG and implement it just as in OpenOCD. The OpenOCD integration is almost done and the source code is available on the dedicated git repository - it required substantial effort and extension of the OpenOCD code, but it also uncovered very elegant method of integration in bigger project using git submodules. For more details please visit project webstibe at http://libswd.sf.net.

UrJTAG

Note: The UrJTAG SWD implementation was based on LibSWD before initial release just to test if the communication with the DAP is working, since then there were some bugfixes implemented during following releases and integration with OpenOCD, therefore everything presented below can be considered as backlog but is already outdated, also the screenshorts have bits swapped etc. I will update this description below after LibSWD+OpenOCD integration is finished and I will get back to the proper LibSWD+UrJTAG integration :-)

KT-LINK driver for UrJTAG

A driver for KT-LINK interface working in JTAG mode had to be first created to test JTAG functionality on target Stm32Primer and Stm32Primer2. Because it is FT2232H based device not embedded into Primer, it also gives access to other targets. Driver code is ready and available on SVN since trunk #1683, GIT commit 6402fdd84a409cdd27de50de908b45d8f0a30099, see code section at project website.

SWD implementation scratchpad

Below is the work in progress description of the SWD implementation in UrJTAG. It will evolve and may change. Comments and suggestions are welcome on how to implement it better. I want to expand the software and keep the features as much as they were before, but some things do work different in SWD and JTAG therefore some minor changes are necessary. Below are the main points I have already decided to implement and keep as the implementation rules:

All of the functions should stay as they are for backward compatibility. They may be implemented by different functions for different transports. Wrappers will decide what and how these functions can be called. New functions will provide new functionalities, old functions should behave just as before from the user perspective.
Because neither JTAG nor SWD are the only transports available for embedded tracing, I have decided not to implement SWD as an alternative or even in place of JTAG (as I wanted at first), but introduced TRANSPORT layer that will allow accessing the target's DAP (Debug Access Port).
- Probably the same thing must happen to the DP (Debug Port) residing inside DAP as it can be specific to SWD, JTAG, and probably others. Unfortunately I did not manage to wrap the SWD operations within the JTAG calls, but this might avoid huge mess in future, when each TRANSPORT and DAP will have its own set of functions called similarly from one commandline function.
- This way other ICE/DAP transport layers can be introduced in future, or even simple direct buses such as SPI, I2C, etc can expand functionality of the software.
- This is now true - transport layer separates functionalities that can use existing drivers, use wrapped version of existing functions or their own commands.
Because the first thing to be done after launching UrJTAG is the cable selection ("cable" command), this will be also the good place to select TRANSPORT as an optional commandline parameter.
- "cable" data structure is expanded with "int transport" property that will hold the information about the transport to be used for communication.
- Other data structures such as "chain" and "part" also are expanded with the "transport" property to know if they support selected transport (to be done). This could also allow to have different transport-capable-devices on one interface in future.
- When "cable" data structure is being created "transport" property is initalized with URJ_TRANSPORT_UNKNOWN value.
  - This will not matter for old drivers, but new drivers will know if user selected some specific transport mode or not.
  - User can know if the cable supports additional modes, if the property's value has changed after "connect" call.
- A new driver-specific "connect" function wrapper must be introduced to set the transport mode and then call the generic connect function.
- Cable/Interface driver function "connect" is used to set logic cable working mode as it is aware of the commandline parameters (and "init" is not).
  - If no transport mode is selected on the commandline, the default mode if selected (driver specific) by the new "connect" function.
  - If selected mode is unsupported, "connect" function returns URJ_ERROR_UNSUPPORTED so the cable cannot be used.
- Apropriate hardware initialization is then made inside "init" function based upon "transport" parameter value.
- If the "cable" command is invoked with old syntax it will work in JTAG mode, calling old "connect" function that will not change the cable's "transport" value.
- The new "cable" command syntax requires additional (optional) parameter that will tell the driver what transport to be used. All initialization is being done inside cable-specific "connect" function - it will also check for (un)supported modes (bitmask) that were selected by the user, or switch the default transport mode.
After cable is initialized, "detect" command must be issued to create swd context and detect debug access port.
- Debug and logging messages are now supported, libswd will inherit log level from target application using swd_log_level_inherit for best tranlation of application log levels into swd log levels (that may differ). Debug level can be changed even before "detect" command. Debug level will be automatically inherited at "detect" command invocation.
New interfaces may require to switch output buffers between Transmit and Receive mode. To maintain backward compatibility with existing drivers I have created another control signal URJ_POD_CS_RnW, just as the nTRST and nSRST, that can be deferred and queued to switch the physical interface transceivers during Turnaround period.
- URJ_POD_CS_RnW is a bitmask for aCbus and aDbus of the FT2232 chip stored within "cable->params->bitmask_RnW" and "cable->params->bitmask_nRnW" so any pin can be set high or low this way at one clock cycle. bitmask_RnW is being set low to transmit data, while bitmask_nRnW is being set high to transmit data - this way when RnW=0 or RnW=1 both bitmasks are applied to provide proper signalling.
- Drivers are now functional - it is possible to drive swd interface pins with "pod" command.

Screenshots

Default JTAG driver

 UrJTAG 0.10 #1864
 Copyright (C) 2002, 2003 ETC s.r.o.
 Copyright (C) 2007, 2008, 2009 Kolja Waschk and the respective authors
 UrJTAG is free software, covered by the GNU General Public License, and you are
 welcome to change it and/or distribute copies of it under certain conditions.
 There is absolutely no warranty for UrJTAG.
 jtag.c:518 main() Warning: UrJTAG may damage your hardware!
 Type "quit" to exit, "help" for help.
 jtag> cable kt-link
 Transport not selected or unsupported. Default transport is: JTAG
 Connected to libftdi driver.
 nSRST pin state is high...
 KT-LINK JTAG Mode Initialization OK!
 jtag> pod reset=0
 jtag> frequency 10000
 Setting TCK frequency to 10000 Hz
 jtag> detect
 IR length: 9
 Chain length: 2
 Device Id: 00111011101000000000010001110111 (0x3BA00477)
  Unknown manufacturer! (01000111011) (/mnt/stuff/tmp/swd/target/share/urjtag/MANUFACTURERS)
 Device Id: 00000110010000010100000001000001 (0x06414041)
  Unknown manufacturer! (00000100000) (/mnt/stuff/tmp/swd/target/share/urjtag/MANUFACTURERS)

Transport Selection

 jtag> cable kt-link
 Transport not selected or unsupported. Default transport is: JTAG
 Connected to libftdi driver.
 nSRST pin state is high...
 KT-LINK JTAG Mode Initialization OK!

 jtag> cable kt-link jtag
 Connected to libftdi driver.
 nSRST pin state is high...
 KT-LINK JTAG Mode Initialization OK!

 jtag> cable kt-link swd
 Connected to libftdi driver.
 nSRST pin state is high...
 KT-LINK SWD Mode Initialization OK!

 jtag> cable kt-link help
 Usage: cable KT-LINK [vid=VID] [pid=PID] [desc=DESC] [TRANSPORT]
 VID        USB Device Vendor ID (hex, e.g. 0abc)
 PID        USB Device Product ID (hex, e.g. 0abc)
 DESC       Some string to match in description or serial no.
 TRANSPORT  Setup cable transport mode (jtag, swd, ...).
 Default:   vid=403 pid=bbe2 driver=ftdi-mpsse

Detecting SWD Target

Before we start we need to select and initialize the interface and its swd mode with cable <name></name> swd command:

 jtag> cable kt-link swd
 Connected to libftdi driver.
 nSRST pin state is high...
 KT-LINK SWD Mode Initialization OK!

Standard detect invocation with successful connection (no target reset necessary, but it is possible with pod reset=0):

 jtag> detect
 IDCODE=0x0EE2805D8 (11101110001010000000010111011000)

Device is powered off - libswd returns SWD_ERROR_ACK error to the master application (UrJTAG) and produces error string with problem description:

 jtag> detect
 Error: detect.c:566 urj_tap_detect_swd() Cable<->DAP transport error: swd_dap_detect() failed ([SWD_ERROR_ACK] acknowledge error).

We want some more information - debug level set to detail using UrJTAG's command debug detial - target application's verbosity log-level is then inherited and translated into apropriate swd-log-level by swd_log_level_inherit() function (you can see the message on debug level):

 jtag> debug detail
 jtag> detect
 Detecting SWD devices...
 SWD_I: Executing swd_dap_activate(0x2833ccc0, SWD_OPERATION_EXECUTE)
 SWD_I: Executing swd_dap_reset(0x2833ccc0, SWD_OPERATION_EXECUTE)
 SWD_I: Executing swd_dp_read_idcode(0x2833ccc0, SWD_OPERATION_EXECUTE)
 SWD_I: swd_dp_read_idcode() succeeds, IDCODE=EE2805D8 (11101110001010000000010111011000)
 IDCODE=0x0EE2805D8 (11101110001010000000010111011000)

We want to see full debug output to trace potential errors - with debug debug command - we get the swd context memory location, queue root location, each of the command's location, type and bistream/payload:

 jtag> debug debug
 swd_log_level_inherit(): SWD Context not (yet) initialized...
 Return in urj_parse_line r=0
 jtag> detect
 Detecting SWD devices...
 swd_init() OK
 SWD_I: Executing swd_dap_activate(0x2833cb40, SWD_OPERATION_EXECUTE)
 SWD_D: swd_drv_transmit(0x2833cb40, 0x2832b920) bits=0  cmdtype=UNDEFINED    returns=0   payload=0x00000000 (00000000)
 SWD_D: swd_drv_transmit(0x2833cb40, 0x2832b960) bits=1  cmdtype=MOSI_TRN     returns=1   payload=0x00000000 (00000000)
 SWD_D: swd_drv_transmit(0x2833cb40, 0x2832bc00) bits=8  cmdtype=MOSI_CONTROL returns=8   payload=0xffffffff (11111111)
 SWD_D: swd_drv_transmit(0x2833cb40, 0x2832bc20) bits=8  cmdtype=MOSI_CONTROL returns=8   payload=0xffffffff (11111111)
 SWD_D: swd_drv_transmit(0x2833cb40, 0x2832bc40) bits=8  cmdtype=MOSI_CONTROL returns=8   payload=0xffffffff (11111111)
 SWD_D: swd_drv_transmit(0x2833cb40, 0x2832bc60) bits=8  cmdtype=MOSI_CONTROL returns=8   payload=0xffffffff (11111111)
 SWD_D: swd_drv_transmit(0x2833cb40, 0x2832bc80) bits=8  cmdtype=MOSI_CONTROL returns=8   payload=0xffffffff (11111111)
 SWD_D: swd_drv_transmit(0x2833cb40, 0x2832bca0) bits=8  cmdtype=MOSI_CONTROL returns=8   payload=0xffffffff (11111111)
 SWD_D: swd_drv_transmit(0x2833cb40, 0x2832bcc0) bits=8  cmdtype=MOSI_CONTROL returns=8   payload=0xffffffff (11111111)
 SWD_D: swd_drv_transmit(0x2833cb40, 0x2832bce0) bits=8  cmdtype=MOSI_CONTROL returns=8   payload=0xffffffff (11111111)
 SWD_D: swd_drv_transmit(0x2833cb40, 0x2832bd00) bits=8  cmdtype=MOSI_CONTROL returns=8   payload=0x00000079 (01111001)
 SWD_D: swd_drv_transmit(0x2833cb40, 0x2832bd20) bits=8  cmdtype=MOSI_CONTROL returns=8   payload=0xffffffe7 (11100111)
 SWD_I: Executing swd_dap_reset(0x2833cb40, SWD_OPERATION_EXECUTE)
 SWD_D: swd_drv_transmit(0x2833cb40, 0x2832bd40) bits=8  cmdtype=MOSI_CONTROL returns=8   payload=0xffffffff (11111111)
 SWD_D: swd_drv_transmit(0x2833cb40, 0x2832bd60) bits=8  cmdtype=MOSI_CONTROL returns=8   payload=0xffffffff (11111111)
 SWD_D: swd_drv_transmit(0x2833cb40, 0x2832bd80) bits=8  cmdtype=MOSI_CONTROL returns=8   payload=0xffffffff (11111111)
 SWD_D: swd_drv_transmit(0x2833cb40, 0x2832bda0) bits=8  cmdtype=MOSI_CONTROL returns=8   payload=0xffffffff (11111111)
 SWD_D: swd_drv_transmit(0x2833cb40, 0x2832bdc0) bits=8  cmdtype=MOSI_CONTROL returns=8   payload=0xffffffff (11111111)
 SWD_D: swd_drv_transmit(0x2833cb40, 0x2832bde0) bits=8  cmdtype=MOSI_CONTROL returns=8   payload=0xffffffff (11111111)
 SWD_D: swd_drv_transmit(0x2833cb40, 0x2832be00) bits=8  cmdtype=MOSI_CONTROL returns=8   payload=0xffffffff (11111111)
 SWD_D: swd_drv_transmit(0x2833cb40, 0x2832be20) bits=8  cmdtype=MOSI_CONTROL returns=8   payload=0xffffffff (11111111)
 SWD_D: swd_drv_transmit(0x2833cb40, 0x2832be40) bits=8  cmdtype=MOSI_CONTROL returns=8   payload=0x00000000 (00000000)
 SWD_I: Executing swd_dp_read_idcode(0x2833cb40, SWD_OPERATION_EXECUTE)
 SWD_D: swd_drv_transmit(0x2833cb40, 0x2832be60) bits=8  cmdtype=MOSI_REQUEST returns=8   payload=0xffffffa5 (10100101)
 SWD_D: swd_drv_transmit(0x2833cb40, 0x2832be80) bits=1  cmdtype=MISO_TRN     returns=1   payload=0x00000001 (00000001)
 SWD_D: swd_drv_transmit(0x2833cb40, 0x2832bea0) bits=3  cmdtype=MISO_ACK     returns=3   payload=0x00000004 (00000100)
 SWD_D: swd_drv_transmit(0x2833cb40, 0x2832bec0) bits=32 cmdtype=MISO_DATA    returns=32  payload=0xee2805d8 (11101110001010000000010111011000)
 SWD_D: swd_drv_transmit(0x2833cb40, 0x2832bee0) bits=1  cmdtype=MISO_PARITY  returns=1   payload=0x00000000 (00000000)
 SWD_I: swd_dp_read_idcode() succeeds, IDCODE=EE2805D8 (11101110001010000000010111011000)
 swd_dap_detect() OK
 IDCODE=0x0EE2805D8 (11101110001010000000010111011000)
 Return in urj_parse_line r=0

Note that memory locations of the data structures can be used to inspect data, ie. p *(swd_ctx_t *)0x2833cd80 in gdb after symbols are loaded :-)

As you can see on the debug level, there are few basic operations on the bus (control, trn, request, ack, data, parity) chained into more complex operations on the target, ie. swd_dp_read_idcode() functions consists of request, trn, ack, data and parity, where trn is being automatically by libswd depending on the pervious/next command direction (MOSI stands for Master Output Slave Input, that is Write, while MISO stands for Master Input Slave Output, that is Read operation).

OpenOCD

OpenOCD is relatively young open-source project that provides flash memory access and gdb-remote debug bridge with use of JTAG Test Access Port. It supports many different target CPU families, common flash memory type (NOR and NAND) and jtag interfaces - all can be extended with higher level TCL scripting. The software is jtag-centric and there is no good division of the functionalities. In 2010 David Brownell proposed idea to create yet another layer that will represent transport system between interface and the target access port that was joined with external LibSWD library for low-level SWD implementation created by Tomek Cedro. This is brilliant idea that should be standardized and implemented during SWD implementation/integration. OpenOCD has however somehow ugly undocumented internal organization with global structures, void parameters, uncentralized information organization and unclear program flow (mixed calls of C functions and TCL commands), therefore soon it needs general reorganization to become more developer-friendly and fully integrate new functionalities ;-)

SWD implementation scratchpad + LibSWD integration

The source tree clearly needs reorganization and unamiguous division into functionalities with compatibile interfaces between each of the layers below. However I have dropped this task as for now the most important is to finish the transport infrastructure, integrate with libswd and make swd transport work, so other developers can make use of it and extend its functionality, maybe add some other transports...

- interface: dongle drivers - this will allow to flush the queue and in general transfer bits over the wire.
- transport: jtag, swd, spi, ... - this will convert commands into bitstream and bistream into results.
- Access Port or Board: TAP (JTAG), DAP (SWD), ... - this will allow some basic operations on target such as detect, reset and others that does not fir neirther into transport nor target.
- target: arm*, cortex, mips, ... - this will allow to access target registers and memory and create bridge between higher layers (flash, rtos, ...) and the physical target.
- flash - this will allow to access flash memory of the target device.
- rtos - this will allow to access various operating system internals such as process list, kernel modules and internals, programs execution, etc.
- smp - this will allow to control multiple processors on the multicore devices.
- ...

I have created working copy of the source tree that is managed with GIT at http://repo.or.cz/w/openocd/libswd.git

Below I will place information on what is already done:

jtag centric drivers based on struct jtag_interface was extended with transfer_bits and signal_operate to create common API for interface signals manipulation (before each interface had its own device specific procedure to flush jtag queue).
interface driver (struct jtag_interface) has now dynamic list field that can contain both transport and interface independent signals to implement necessary transport layer operations (ie. output buffers switch for TRN operation).
SWD DP and AP procedures for OpenOCD using LibSWD are now ready and compatibile with existing arm_adi_v5 infrastructure (change between JTAG and SWD should not affect higher layers of existing works, maybe transport specific differences will have to be wrapped somehow).
Driver bridge between OpenOCD and LibSWD is now ready, not yet verified.
SWD driver for KT-LINK interface is ready.
struct jtag_interface ft2232_swd_interface is now ready based on existing ft2232 drivers pool and additional crafted methods to work with interface signalls and bitsream.
Program builds successfully ;-)
Program runs as expected for JTAG transport - changes did not break existing functionality (there was a hidden bug in setting transport clock, but it is already fixed in current source tree).
For interface having only one transport the transport is selected correctly (ie. jtag for ft2232_interface, swd for ft2232_swd_interface).
LibSWD build system is now integrated with OpenOCD build system. By default LibSWD will be fetched from git repository into OpenOCD source tree and built/installed together. It is possible to disable internal libswd build with --disable-internal-libswd and use some other libswd already installed on the system.
interface initialization now work for jtag and swd transport
tcl interface has now frontend to inetrface signals (interface_signal command that can list, add, delete signals) management and bitbang (bitbang that supports many signals read and write operations at one invocation). These operations can now be used to operate specified signals by hand or with automation scripts.
verify crafted interface methods to work on interface signals and bitstream - done!
verify driver bridge between openocd drivers and libswd - done! i had to create generic driver architecture for transports other than jtag :-)
verify interface operation, bitsream, etc - done!
read out the idcode using swd transport - done!
swd command set and tcl interface basics - done!
separation of loglevels in openocd and libswd to improve debug - done!
swd transport infrastructure - verified!
remove jtag-specific code pieces from arm target - a wrapper has been created to provide jtag and swd specific functions based on the selected transport.
make arm target work with swd transport - already done.
implement transport independent error handling as jtag and swd use different error handling mechanisms - it was implemented inside libswd_dap functions.
access internal bus - done.
access flash in read/write mode - done flash write.

Current tasks to solve:

make debug work - to be verified but can work soon.

Screenshots

Transport Infrastructure

In order to allow access to non-JTAG devices, transport layer has been created by David Brownell to abstract operations on the bus interconnecting interface and target system. Implementation for SWD transport in OpenOCD based on LibSWD was created by Tomasz Cedro. A new interface ft2232_swd has been created reusing existing code for FT2232 devices. The code was developed and tested on KT-LINK interface, a first on the market inexpensive FT2232H-based design by Krzysztof Kajstura supporting both JTAG and SWD. Everything created around SWD is backward compatible and make (re)use of existing code and design, so it should be fairly easy to add new inetrfaces and transports now. It should be also possible to use existing FT2232 based devices with SWD transport with small buffer/interface between interface pins and the target. Accomplishing this goal was quite a challenge, but it turned out to be possible :-)

Interface Signal and Bitbang Infrastructure

OpenOCD had only jtag-specific flush_queue() function to transfer logical data into interface hardware that was not usable for transfering bitstream for other transports. In order to implement transports other than jtag at interface level it was necessary to create bit-bang functionality allowing free control over read/write access to the interface electrical signals. Because OpenOCD has integrated TCL interpreter I have created interface_signal and bitbang frontend for mentioned underlying interface signal operations. Example bitbanging is presented below, it can be also used for full interface configuration at script/configuration level, so there is no need to hard-code complex routines anymore for new interfaces or transports:

 %telnet localhost 4444
 Trying 127.0.0.1...
 Connected to localhost.
 Escape character is '^]'.
 Open On-Chip Debugger
 > interface_signal list
       Interface Signal Name      |    Mask    |   Value   
 ----------------------------------------------------------
                              RnW | 0x00001000 | 0x00001000
                              LED | 0x00008000 | 0x00008000
                             srst | 0x00000A00 | 0x00000A00
 > bitbang led=hi
 LED=0x00008000
 > bitbang led=lo
 LED=0x00000000
 > bitbang led=hi
 LED=0x00008000
 > interface_signal list
       Interface Signal Name      |    Mask    |   Value   
 ----------------------------------------------------------
                              RnW | 0x00001000 | 0x00001000
                              LED | 0x00008000 | 0x00008000
                             srst | 0x00000A00 | 0x00000A00
 > bitbang led=lo       
 LED=0x00000000
 > interface_signal list
       Interface Signal Name      |    Mask    |   Value   
 ----------------------------------------------------------
                              RnW | 0x00001000 | 0x00001000
                              LED | 0x00008000 | 0x00000000
                             srst | 0x00000A00 | 0x00000A00
 > interface_signal     
 Bad syntax!
 interface_signal (add|del|list) signal_name [mask]
 in procedure 'interface_signal'
 >

No need to mention that such commands can be grouped in functions and then called for some target-specific operations (i.e. SPI memory access). This wont be as fast as built-in transport but definitely will come handy for testing :-)

Interface configuration file and device specific scripting

interface_signal and bitbang brings new possibilities to interface scripting. Signals can be added dynamically at runtime with no need to hardcode them or recompile program. Signals can be driven read or write with selected values and masks allowing unlimited control over interface pinout. It is now possible to easily write external scripts for additional interface hardware, such as ADC or DAC, that was not possible before. Below is an example configuration file for KT-LINK interface (...and its example usage presented above):

 interface ft2232_swd
 ft2232_device_desc "KT-LINK"
 ft2232_layout ktlink_swd
 ft2232_vid_pid 0x0403 0xBBE2
 interface_signal add RnW 0x1000
 interface_signal add LED 0x8000
 interface_signal add SRST 0x0a00

Later on I have also added some additional signals that comes handy in SWD transport and general driver/target testing:

 interface_signal add SRSTin 0x0040 
 interface_signal add CLK 0x01
 interface_signal add MOSI 0x02
 interface_signal add MISO 0x04
 interface_signal add nSWDsel 0x20

Transport initialization and IDCODE read

At the moment transport initialization requires defined target, so it it not possible to work on a target when no target is defined inside openocd - this is the existing openocd organization - but it can change if necessary.

First steps of SWD Target

Current work is aimed at making existing Target infrastructure work using SWD transport. The example configuration for use with Stm32Primer2 and KT-LINK-SWD can be following (please note flash driver change stm32x -> stm32f1x change during last year):

 if { [info] } {
    set  _CHIPNAME $CHIPNAME
 } else {
    set  _CHIPNAME stm32
 }
 
 if { [info] } {
    set  _ENDIAN $ENDIAN
 } else {
    set  _ENDIAN little
 } 
 
 # Work-area is a space in RAM used for flash programming
 # By default use 16kB
 if { [info] } {
    set  _WORKAREASIZE $WORKAREASIZE
 } else {
    set  _WORKAREASIZE 0x4000
 } 
 
 # JTAG speed should be <= F_CPU/6. F_CPU after reset is 8MHz, so use F_JTAG = 1MHz
 adapter_khz 10000
 if { [info] } {
    set _CPUTAPID $CPUTAPID
 } else {
   # See STM Document RM0008
   # Section 26.6.3
    set _CPUTAPID 0x3ba00477
 }
 swd newtap $_CHIPNAME cpu -irlen 4 -ircapture 0x1 -irmask 0xf -expected-id $_CPUTAPID  
 
 set _TARGETNAME $_CHIPNAME.cpu
 target create $_TARGETNAME cortex_m3 -endian $_ENDIAN -chain-position $_TARGETNAME 
 
 $_TARGETNAME configure -work-area-phys 0x20000000 -work-area-size $_WORKAREASIZE -work-area-backup 0 
 
 # flash size will be probed
 set _FLASHNAME $_CHIPNAME.flash
 flash bank $_FLASHNAME stm32f1x 0x08000000 0 0 0 $_TARGETNAME
 
 # if srst is not fitted use SYSRESETREQ to
 # perform a soft reset
 cortex_m3 reset_config sysresetreq

First the interface (and so the transport) is set up, then the interface/adapter speed that is board-specific, then the SWD TAP and Target is created (using existing JTAG infrastructure a.t.m.) using SWD command set selected by swd transport select call. Later on targets is detected and commands are accepted on the telnet commandline - halt and flash memory access is now possible.

Below a fresh screenshots of integration between LibSWD (0.5 devel) and OpenOCD (0.7 devel) is being made on top of the openocd's git head from November 2012 - this is the code that will be included into main OpenOCD branch..

The Interface infrastructure is now done. Interface Bitbang, Transfer, Feature is now done. ft2232_swd driver is now done. Transport for swd and swd_libswd is now done. There are still some jtag-dependent code in mem-ap sections, but the target can be detected...

What happens if target is powered down or not connected? We get error message and LibSWD explains what is the problem.

 % ./openocd -f stm32swd.cfg
 Open On-Chip Debugger 0.7.0-dev-gc1e217b-dirty (2012-11-15-21:21)
 Licensed under GNU GPL v2
 For bug reports, read
        http://openocd.sourceforge.net/doc/doxygen/bugs.html
 Info : only one transport option; autoselect 'swd'
 Info : Selected LibSWD as SWD transport mechanism, adding driver features...
 Info : Interface signal - 'RnW' added.
 Info : Interface signal - 'LED' added.
 Info : Interface signal - 'SRST' added.
 Info : Interface signal - 'SRSTin' added.
 Info : Interface signal - 'CLK' added.
 Info : Interface signal - 'MOSI' added.
 Info : Interface signal - 'MISO' added.
 Info : Interface signal - 'nSWDsel' added.
 adapter speed: 1000 kHz
 adapter_nsrst_delay: 100
 cortex_m3 reset_config sysresetreq
 Info : KT-LINK SWD-Mode initialization complete...
 Info : max TCK change to: 30000 kHz
 Info : clock speed 1000 kHz
 LIBSWD_N: Using libswd master-GIT-devel (http://libswd.sf.net)
 LIBSWD_N: (c) Tomasz Boleslaw CEDRO (http://www.tomek.cedro.info)
 Info : New SWD context initialized at 0x0x801423400
 LIBSWD_I: Executing libswd_dap_activate(libswdctx=@0x801423400, operation=LIBSWD_OPERATION_EXECUTE)
 LIBSWD_I: Executing libswd_dap_reset(libswdctx=@0x801423400, operation=LIBSWD_OPERATION_EXECUTE)
 LIBSWD_I: Executing libswd_dp_read_idcode(libswdctx=@0x801423400, operation=LIBSWD_OPERATION_EXECUTE)
 LIBSWD_E: libswd_drv_transmit(libswdctx=@0x801423400, cmd=@0x801440f70): Unknown ACK detected / Protocol Error Sequence! DAP Stalled or Target Power Off?
 Error: libswd_dap_detect() error -19 ([LIBSWD_ERROR_ACKUNKNOWN] got unknown acknowledge)
 in procedure 'transport'
 in procedure 'init'

Interface selection works fine, transport selection works fine, executing operations from Interface Feature provided by LibSWD Transport works fine, target detection (Transport Init) works fine. Still hardcoded jtag parts in mem-ap support in current openocd code needs to be developed/fixed:

 % ./openocd -f stm32swd.cfg
 Open On-Chip Debugger 0.7.0-dev-gcf35ed5-dirty (2012-11-16-02:03)
 Licensed under GNU GPL v2
 For bug reports, read
         http://openocd.sourceforge.net/doc/doxygen/bugs.html
 Info : only one transport option; autoselect 'swd'
 Info : Interface 'ft2232_swd' defines its own 'oocd_feature_arm_dap' features.
 Info : Interface signal - 'RnW' added.
 Info : Interface signal - 'LED' added.
 Info : Interface signal - 'SRST' added.
 Info : Interface signal - 'SRSTin' added.
 Info : Interface signal - 'CLK' added.
 Info : Interface signal - 'MOSI' added.
 Info : Interface signal - 'MISO' added.
 Info : Interface signal - 'nSWDsel' added.
 adapter speed: 1000 kHz
 adapter_nsrst_delay: 100
 Info : KT-LINK SWD-Mode initialization complete...
 Info : max TCK change to: 30000 kHz
 Info : clock speed 1000 kHz
 LIBSWD_N: Using libswd master-GIT-devel (http://libswd.sf.net)
 LIBSWD_N: (c) Tomasz Boleslaw CEDRO (http://www.tomek.cedro.info)
 Info : New SWD context initialized at 0x0x801423340
 LIBSWD_I: Executing libswd_dap_activate(libswdctx=@0x801423340, operation=LIBSWD_OPERATION_EXECUTE)
 LIBSWD_I: Executing libswd_dap_reset(libswdctx=@0x801423340, operation=LIBSWD_OPERATION_EXECUTE)
 LIBSWD_I: Executing libswd_dp_read_idcode(libswdctx=@0x801423340, operation=LIBSWD_OPERATION_EXECUTE)
 LIBSWD_I: libswd_dp_read_idcode(libswdctx=@0x801423340, operation=LIBSWD_OPERATION_EXECUTE, **idcode=0x1BA01477/00011011101000000001010001110111).
 Info : SWD transport initialization complete. Found IDCODE=0x1BA01477.
 LIBSWD_I: libswd_dp_read(libswdctx=@0x801423340, operation=LIBSWD_OPERATION_EXECUTE, addr=0x4, **data=0x0/00000000000000000000000000000000).
 LIBSWD_I: libswd_dp_write(libswdctx=@0x801423340, operation=LIBSWD_OPERATION_EXECUTE, addr=0x4, *data=0x20/00000000000000000000000000100000).
 LIBSWD_I: libswd_dp_read(libswdctx=@0x801423340, operation=LIBSWD_OPERATION_EXECUTE, addr=0x4, **data=0x0/00000000000000000000000000000000).
 LIBSWD_I: libswd_dp_write(libswdctx=@0x801423340, operation=LIBSWD_OPERATION_EXECUTE, addr=0x4, *data=0x50000000/01010000000000000000000000000000).
 LIBSWD_I: libswd_dp_read(libswdctx=@0x801423340, operation=LIBSWD_OPERATION_EXECUTE, addr=0x4, **data=0xF0000000/11110000000000000000000000000000).
 LIBSWD_I: libswd_dp_read(libswdctx=@0x801423340, operation=LIBSWD_OPERATION_EXECUTE, addr=0x4, **data=0xF0000000/11110000000000000000000000000000).
 LIBSWD_I: libswd_dp_write(libswdctx=@0x801423340, operation=LIBSWD_OPERATION_EXECUTE, addr=0x4, *data=0x50000001/01010000000000000000000000000001).
 LIBSWD_I: libswd_dp_read(libswdctx=@0x801423340, operation=LIBSWD_OPERATION_EXECUTE, addr=0x4, **data=0xF0000001/11110000000000000000000000000001).
 LIBSWD_I: libswd_ap_write(libswdctx=@0x801423340, operation=LIBSWD_OPERATION_EXECUTE, addr=0x0, *data=0xA2000012/10100010000000000000000000010010).
 LIBSWD_I: libswd_ap_write(libswdctx=@0x801423340, operation=LIBSWD_OPERATION_EXECUTE, addr=0x4, *data=0xE000ED00/11100000000000001110110100000000).
 Assertion failed: (jtag_trst == 0), function jtag_checks, file core.c, line 339.
  Abort (core dumped)

What happens if we choose an interface that does not provide features necessary for a given transport? Default LibSWD features are tried, and if that fils program quits because there are no features required to run swd transport...

 % ./openocd -f stm32swd.cfg
 Open On-Chip Debugger 0.7.0-dev-gbdd0f79-dirty (2012-11-16-00:35)
 Licensed under GNU GPL v2
 For bug reports, read
         http://openocd.sourceforge.net/doc/doxygen/bugs.html
 Info : only one transport option; autoselect 'swd'
 Error: Invalid features list selected (no features)!
 Info : Trying to select LibSWD as SWD transport mechanism, adding driver features...
 Error: Invalid features list selected (no features)!
 Warn : Transport features 'oocd_feature_arm_dap' failed to attach to interface 'ft2232_swd'!
 Error: Interface 'ft2232_swd' does not provide/accept features required by transport 'swd'!
 Runtime Error: /tmp/openocd/target/share/openocd/scripts/interface/kt-link-swd.cfg:4:

Hardware

Both Stm32Primer and Stm32Primer2, except some fancy user interface devices onboard, consist of the CPU and RLink interface - both have their own USB connectors. RLink allows code memory access and program execution trace with no additional hardware, but it is a proprietary device with proprietary protocol, so using Stm32Primer development kits with non-Raisonance software is made difficult.

Stm32Primer use JTAG mode for programming and is already supported by OpenOCD and UrJTAG, Stm32Primer2 use SWD and need some additional work documented in this project. I want to make JTAG+SWD modes work on both RLink interfaces, but also make SWD working with more generic FT2232H based device - KT-LINK seems just perfect for this purpose.

Also it is important to remember not to use both RLink and other interface simultaneously as this may damage both interfaces and the CPU. When device is going to be used with an external inerface, internal one must be disconnected by desoltering the resistors or simply cutting the wires on the PCB. It is also necessary to connect ground and reference voltage pins for the logic buffers to work properly on the external interface.

Strm32Primer

Device: Stm32Primer
CPU: STM32F103RBT6
Programming: Onboard USB RLink JTAG

To access the SWJ pins on the Stm32Primer you need to connect external interface to signal points shown on the pictures below. I have made a simple socket connector for easier connect/disconnect. Here you can get a high quality pdf file.

200px 200px 300px

Stm32Primer2

Device: Stm32Primer2
CPU: STM32F103VET6
Programming: Onboard USB RLink SWD

To access the SWJ pins on the Stm32Primer2 you need to connect external interface to signal points shown on the pictures below. Here you can get a high quality pdf file.

400px 250px 250px

To have ability to test JTAG and SWD on the same device, also the ability to switch to and from one of the modes, full JTAG connector must be first created. There are some problems however with a brand new Primer2 taken out of the box - it is only SWD aware so no JTAG connection is available between the CPU and builtin RLink, also the remaining JTAG pins are set as outputs driving the audio codec chip onboard (I have physically cut off this connection). Because TRST signal behavior can be also obtained with toggling the TCK/TMS and this signal should reset the TAP, in most cases this is enough to reset device and zero the port registers setting their function to default - but not this time. A separate SRST signal needs to hold device after power up and before the program starts and lock out the pins. In case of KT-LINK SRST signal has to high impedance to reset target at command (urjtag command "pod reset=0"), so I had to apply low state on reset line and then power on the device - below is the result:

 %./jtag 
 UrJTAG 0.10 #1862
 Copyright (C) 2002, 2003 ETC s.r.o.
 Copyright (C) 2007, 2008, 2009 Kolja Waschk and the respective authors
 UrJTAG is free software, covered by the GNU General Public License, and you are
 welcome to change it and/or distribute copies of it under certain conditions.
 There is absolutely no warranty for UrJTAG.
 jtag.c:518 main() Warning: UrJTAG may damage your hardware!
 Type "quit" to exit, "help" for help.
 jtag> cable  kt-link
 Connected to libftdi driver.
 SRST pin state is high...
 KT-LINK JTAG Mode Initialization OK!
 jtag> pod reset=0
 jtag> detect
 Error: parse.c:208 urj_parse_file() no error: Cannot open file '~/.jtag/rc' to parse
 jtag> detect
 IR length: 9
 Chain length: 2
 Device Id: 00111011101000000000010001110111 (0x3BA00477)
  Unknown manufacturer! (01000111011) (/mnt/stuff/tmp/swd/target/share/urjtag/MANUFACTURERS)
 Device Id: 00000110010000010100000001000001 (0x06414041)
  Unknown manufacturer! (00000100000) (/mnt/stuff/tmp/swd/target/share/urjtag/MANUFACTURERS)

SWD transport is now ready using UrJTAG and KT-LINK external interface:

 %./jtag
 UrJTAG 0.10 #1864
 Copyright (C) 2002, 2003 ETC s.r.o.
 Copyright (C) 2007, 2008, 2009 Kolja Waschk and the respective authors
 UrJTAG is free software, covered by the GNU General Public License, and you are
 welcome to change it and/or distribute copies of it under certain conditions.
 There is absolutely no warranty for UrJTAG.
 jtag.c:518 main() Warning: UrJTAG may damage your hardware!
 Type "quit" to exit, "help" for help.
 jtag> cable kt-link swd
 Connected to libftdi driver.
 nSRST pin state is high...
 KT-LINK SWD Mode Initialization OK!
 jtag> detect
 IDCODE=0x0EE2805D8 (11101110001010000000010111011000)

KT-LINK (FT2232H based, SWD ready)

Device: KT-LINK
Chipset: FT2232H
JTAG+SWD Capable Programmer Interface

Because SWD is a bidirectional bus, more advanced buffering is required than in case of JTAG where one pin was used for input and another for output signal. Therefore not all dongles supporting JTAG will support SWD, or at least in their default configuration, please keep that in mind. Here you can get the KT-LINK specification. Also note that different interfaces might have slightly different pinout (especially the VCC pin).

There is an Open-Source libftdi library that allows multiplatform communication with FT2232 devices. There is also a free but proprietary libftd2xx library released by the Future Technology Devices International (FT2232 manufacturer), however audience is limited I will not use this one in this project.

Older JTAG interfaces use FT2232D silicon, that is Full-Speed USB version (12MBit/s max. throughput). Newer devices, such as KT-LINK, use already Hi-Speed FT2232H version (480MBit/s max. throughput), that became supported by libftdi release 0.16 - if you have this chip remember to use up-to-date library!

The UrJTAG's driver for KT-LINK working both in JTAG and SWD mode is now ready. The OpenOCD's driver is also ready and the work on SWD framework using libswd is almost finished :-)

Buffers Organization Buffers Organization

RLink

RLink interface can be found as OEM standalone or embedded programming interface. Stm32Primer device family has this interface embedded on one board with the CPU, so I will concentrate only on this version. In this section I will place any information usable to make it work with Open-Source utilities. Several transmission dumps using swd transport are available here to download and work on.

If you want to support this work, please help reverse engineering the protocol to write open source driver for this device.

Debug Access Port (DAP) Model / Design / Theory

Introduction

In this section I will provide essential information on the components that are used to access ARM Cortex system bus and debug unit with SWJ and will be helpful for developers and testers. Information here is also an input for LibSWD that I am working on based on ADIv5 (5.0) specification - that unfortunately contains some bugs and misleading information, but it is already updated with ADIv5.1 that clarifies some things and brings new functionalities. When ADIv5 is fully supported by libswd, works will move to support ADIv5.1. All information presented here can be found on the ARM Website, specifically in their ARM Info Center. If you prefer PDF documentation search for "Arm Debug Interface ADIv5". ARM holds copyright to this materials according to their policy specified on the website and within the documents. If you have any comments, questions or find a bug - please let me know :-)

Note: Information presented below was taken from buggy "Cortex-M series processors Cortex-M1 Revision: r0p1 specification". This caused confusion and implementation troubles at some points. For more unabiguous information please use ADIv5 PDF + Errata as it contains updated and more correct information.

Before we start with the general DAP description lets take a look at the STM32F103VE microcontroller block diagram (picture copyrighted by the STM Microelectronics) - this will give a good perspective on how the components are interconnected and dependent on each other, making it easier to understand the specific block registers, their function and meaning in terms of being a part of bigger system:

HPROT[3]	HPROT[2]	HPROT[1]	HPROT[0]	Description
0	0	0	0	Invalid
0	0	0	1	Invalid
0	0	1	0	Instruction fetch
0	0	1	1	Data fetch
0	1	X	X	Invalid
1	X	X	X	Invalid

CFGITCMSZE or CFGDTCMSZE	TCM size
4'h0	0KB
4'h1	1KB
4'h2	2KB
4'h3	4KB
4'h4	8KB
4'h5	16KB
4'h6	32KB
4'h7	64KB
4'h8	128KB
4'h9	256KB
4'hA	512KB
4'hB	1MB

Project History

Table of Contents

Introduction

Software

LibSWD

UrJTAG

KT-LINK driver for UrJTAG

SWD implementation scratchpad

Screenshots

Default JTAG driver

Transport Selection

Detecting SWD Target

OpenOCD

SWD implementation scratchpad + LibSWD integration

Screenshots

Transport Infrastructure

Interface Signal and Bitbang Infrastructure

Interface configuration file and device specific scripting

Transport initialization and IDCODE read

First steps of SWD Target

Hardware

Strm32Primer

Stm32Primer2

KT-LINK (FT2232H based, SWD ready)

RLink

Debug Access Port (DAP) Model / Design / Theory

Introduction

JTAG-DP

Description

JTAG-DP Registers

JTAG Instruction Register (IR)

JTAG Data Register (DR)

ABORT (IR: b1111, DR: 1bit)

IDCODE (IR:b1110, DR: 32bit)

DPACC / APACC (DPAC_IR:b1010, APAC_IR:b1011, DR: 35bit)

SW-DP

Description

Interface Reset and Synchronization

SWD Packet Construction

Successful Write Operation

Successful Read Operation

WAIT response to Read or Write operation request

FAULT response to Read or Write operation request

Protocol Error Sequence

SW-DP Registers

ABORT

IDCODE, Identification Code Register

CTRL/STAT, Control/Status Register

SELECT, AP Select Register

RDBUFF, Read Buffer

WCR, Wire Control Register

RESEND, Read Resend Register

AHB-AP

AHB-Lite master ports

AHB-AP registers

CSW, 0x00, AHB-AP Control/Status Word Register

TAR, 0x04, AHB-AP Transfer Address Register

DRW, 0x0C, AHB-AP Data Read/Write Register

BD0-BD03, 0x10-Ox1C, AHB-AP Banked Data Registers

ROM, 0xF8, ROM Address Register

IDR, 0xFC, AHB-AP Identification Register

AHB-AP clocks and resets

Supported AHB protocol features

HPROT encodings

HRESP

AHB-AP transfer types and bursts

Packed transfers

External and Memory Interfaces

External interface

Write buffer

Memory attributes

Memory interfaces =

Common SWJ-DP Features

Read and write errors

Overrun detection

Protocol errors, SW-DP only

Pushed compare and pushed verify operations

Example use of pushed verify operation on a AHB-AP

Example use of pushed find operation on a AHB-AP

Resources