SWD

Introduction

SWD (Serial Wire Debug) is a two-wire debugging interface for ARM based processors, similar to the two-wire version of JTAG.

SWD Tutorial

This tutorial is based on third-party content available at

• https://www.lpcware.com/content/blog/introduction-cortex-serial-wire-debugging-part-one
• https://www.lpcware.com/content/blog/introduction-cortex-serial-wire-debugging-part-two
• https://www.lpcware.com/content/blog/introduction-cortex-serial-wire-debugging-part-three

Part 1 - SWD Fundamentals

The SWD interface has two signal wires: SWCLK (Serial Wire Clock) and SWDIO (Serial Wire Data Input/Output). SWCLK is driven by the master and synchronizes the SWD data transfer. SWDIO is driven by either the master or the target. Every SWD transaction starts with the master driving SWDIO but switches to having the target drive SWDIO at some point. I/O levels and thresholds on SWCLK and SWDIO should be set to match the I/O voltage of the target. In the simplistic hardware design given in this document, we assume that the target voltage is 3.3V and no provisions are made to adjust to lower target voltages.

SWD Levels and Edges

Since SWD is a bi-directional communications standard with only one data line, data needs to be written to the bus by both the master and the slave. Every SWD transaction begins with the master controlling SWDIO. After a turnaround period, the slave controls SWDIO, then control switches back to the master. Whenever the bus is idle, the clock should be high and the master controls the bus. When the master is in control of SWDIO, it clocks data out on the falling edge of SWCLK and the slave latches the data on the rising edge of SWCLK. When the slave takes over SWDIO, it presents data to SWDIO on the rising edge of SWCLK and the master latches the incoming data on the falling edge of SWCLK. In both cases, SWCLK is driven by the master. The ½ and 1½ period 1 values on SWDIO are called “turnaround periods” in the SWD specification. They need to be driven by the host to prevent the bus from being dragged low by coupling of transitions on the SWDCLK. If the SWD target detects that SWDIO is not 1 during the turnaround period, it will go into an error state and not respond to any further transactions.

SWD Protocol

The SWD protocol consists of read and write transactions. Both types of transactions have three phases. These phases are the request phase, the acknowledge phase, and the data phase. All of the data sent over SWD is sent in little-endian order and is sent least-significant-bit first. During the request phase the host requests a read or write operation on the target and indicates whether the Debug Port or Access Port is being accessed. The Debug Port is a set of four important registers within the Cortex debug port that perform very basic operations. The Access Port is a larger address space of 64 registers which are useful for accessing the microcontroller’s main bus. The request phase consists of eight bits of data, some of which are constant. The acknowledge phase consists of three bits where the SWD target indicates status to the host. The data phase is where data is sent from the host to the target during a write operation. Data is sent from the target to the master during a read operation. The data phase consists of 33 bits- 32 bits of data (lsb first) followed by 1 bit of parity.

Request Phase Data

bit	numberbit	valuebit	description
0 (lsb)	always	1	start bit
11 for Access Port	SWD Port select	-	selects Access Port or Debug Port
2 (1 for Read)	read select	-	selects whether this is a read or a write transaction
3	address bit	2	bit 2 of read or write address (bits 0 and 1 are 0)
4	address bit	3	bit 3 of read or write address (bits 0 and 1 are 0)
5	parity1 if sum of request phase bits	1-4	is odd
6	always	0	stop bit
7 (msb)	always	1	park bit

Acknowledge Phase Data

bit	numberbit	valuebit	description
0-2	acknowledge value 1	-	means acknowledge, no error
2	-	means wait, target not ready
4	-	means fault or error
7	-	typically means the target is disconnected

SWD Read and Write Details

The SWD port supports reading and writing to the Debug Port and the Access Port. The Cortex Debug Port consists of 4 32-bit registers. When executing an SWD transaction, a Debug Port transaction is specified by leaving bit 1 (port select) set to zero during the request phase of the SWD transaction. The address is specified by bits 3 and 4. Read is specified by setting bit 2 as 1, writes by clearing bit 2 to 0. Writes do not actually complete until after the following SWD command or until receiving a “flush” which is simply eight 0s clocked out onto SWDIO. The Cortex Access Port address space has 64 32-bit registers. Because only two bits of address are specified in the SWD request phase, four more bits of address need to be set by using the AP Select register at address 8 on the Debug Port. To execute a transaction on the Access Port, typically the Debug Port AP Select register must be written first before the Access Port is written. When executing a read on the Access Port, the result returned will be that of the previous read. Therefore when executing a read operation, a 2nd dummy read must be done to get the results. If executing a sequence of reads, only one dummy read is needed to get the first result. There is no need for a dummy read between every read in a sequence.

Please note that both the Debug Port and the Access Port are NOT part of the Cortex CPU core’s general address space. These ports and their registers only exist inside the SWD debug port. For details on these registers and their uses please see the ARM Debug Interface v5 Architecture Specification documentation and errata.

Initializing SWD

The SWD protocol allows full control of an LPC microcontroller. Because of this, it is critical that the port be insensitive to noise under a wide range of design conditions. To make the SWD port insensitive to noise, an unlock or connection sequence must be executed before the port can be used. The unlock sequence consists of several different steps.

SWD Unlock Sequence Steps

1. The Host needs to switch the target from JTAG to SWD mode by clocking 0xE79E onto SWDCLK/SWDIO
2. SWD connection sequence- clock out more than 50 binary 1s
3. Must read the Debug Port IDCODE register (address 0)
4. Turn on Debug Port by settings bits 28 and 30 at DP address 4
5. Write AP select (debug port address 8) to 0xF0 (to prep for AP read of 0xFC)
6. Unlock Access Port by reading AP ID register (AP address 0xFC)

Part 2 - Common SWD Operations

This text is intended as a quick summary of common debug operations and how to do them with SWD. For full documentation, see ARM’s Debug Interface v5 Architecture Specification as well as the Cortex-M0 Technical Reference Manual.

Reading and Writing target memories

A common requirement is a need to read and write to registers or memories on the target chip. This can be done using the Access Port Transfer Address Register (AP-TAR) at address 4 and Access Port Data Read/Write Register (AP-DRW) at 0xC. The steps are as follows:

1. Write AP-TAR with the address to be read or written.
   This address is as the Cortex CPU core would see it if running code on the target.
2. Write AP-DRW with the data to be written, to write the address on the target.
3. Read AP-DRW to read the address on the target.

Please remember that when accessing the Access Port, the Debug Port AP Select register needs to be set up first. Also, when reading from the AP, first a dummy read is needed before the actual data can be read. Finally, a write will not take effect until after the next SWD command is executed, or a flush sequence of 8 0 bits is written to SWD.

Resetting the target

To reset a Cortex target, the Application Interrupt and Reset Control Register (AIRCR) can be used. This register exists in the target’s CPU address space at address 0xE000ED0C. Writing 0x05FA0004 will reset the LPC controller. For details on how to write a register on the target, see section 3.1. Upon initiating a reset, all of the hardware on the chip will be reset to the hardware reset state. The hardware reset state is normally not seen by customers and precedes the reset state described in the part User’s Manual. True “reset” state is only achieved after the boot rom has executed and initialized hardware to the UM reset state. Code execution will then continue through to the code in flash. Because the boot ROM performs many important system initializations and calibration tasks including trimming the IRC frequency, the boot ROM should always be run after reset before the chip is used for anything. In the event that AIRCR is not supported on a particular microcontroller, reset can generally be achieved using the hardware reset pin or a proprietary reset register.

Reading and Writing CPU Core Registers

To read and write CPU core registers, two registers are used. These are the Debug Core Register Selector Register (DCRSR) and the Debug Core Register Data Register (DCRDR). These two registers are implemented in the CPU’s address space at addresses 0xE000EDF4 and 0xE000EDF8. They can be written using the steps to write target memory in section 3.1.

Reading a CPU Core Register

1. Write register number to DCRSR at 0xE000EDF4
2. Read the register data from DCRDR at 0xE000EDF8

Writing a CPU Core Register

1. Write register data to DCRDR at 0xE000EDF8
2. Write the register number to DCRSR at 0xE000EDF4

To read or write a core register, you will need to know the register IDs for the Cortex-Mx core registers. Here they are for the Cortex-M0:

Cortex-M0 Register Numbers

Register ID	1	2	3	4	5	6	7	8	9	10	11	12	13	14	15	16	17
Register Name	R0	R1	R2	R3	R4	R5	R6	R7	R8	R9	R10	R11	R12	SP	LR	PC	XPSR

Run Control

A common SWD need is to stop and restart the running of code, or to single step. This can all be done using the Debug Halting Control and Status Register, or DHCSR at address 0xE000EDF0 in the main memory space.

Run Control Operations

Operation	run	stop	step
Value to Write to DHCSR	0xA05F0001	0xA05F0003	0xA05F0005

Making IAP Calls

On NXP parts, in-Application Programming (IAP) is typically accessed through a single function called Invoke which is entered at 0x1FFF1FF1, however this entry point can change depending on the part being used. The parameters to Invoke are Invoke(unsigned long *Command, unsigned long *Response). The Command parameter is used to specify the IAP function and its parameters. The Response parameter is used to retrieve the IAP function status and its return values.
To complete an IAP call, a branch instruction can be written into RAM followed by a debug break instruction. The program counter can be set to the address of the branch instruction and the target can be told to run. The target status can be polled and when it has stopped running, the IAP call is complete. Key to this process is setting up a good run environment including a stack (up to 256 bytes can be used by ISP), reserving space for the command and response arrays, and initializing the registers to point to the command and response arrays (see the ARM EABI documentation).

Boot ROM Execution at Reset

Many ARM Microcontrollers include a boot ROM that executes at reset before the user flash code. This boot ROM must be allowed to execute before IAP calls can be used. After an LPC part is hardware reset, vectors are mapped to ROM or the vector portion of the boot ROM is mapped to address 0. Often, the final action of the boot ROM before calling user code is to remap Flash to address 0 or move the vectors to 0. This can be trapped using a Coresight watchpoint at the SYSMEMREMAP register on Cortex-M0 parts. This register is usually at 0x40048000 but please confirm in your device User’s Manual.

Handling Failsafe Watchdog Timers (LPC1200 series)

The LPC1200 series has a watchdog timer that is enabled out of reset and has an approximately 4 mS timeout. This creates a special case that must be addressed to implement a debugger or flash programmer for this product family. Whenever the LPC1200 is reset, the debugger must disable the WDT. This is done by enabling the WDT register clock, requesting to disable the WDT, then executing a feed sequence.

Sequence to Disable LPC1200 WDT

1. Reset part
2. Read SYSAHBCLKCTRL at 0x40048080
3. Turn on clock to WDT register bank by setting bit 15 in SYSAHBCLKCTRL at 0x40048080
4. Request to disable WDT by writing 0 to 0x40004000
5. WDT feed sequence- write 0xAA to 0x40004008 then write 0x55 to 0x40004008
6. These steps should occur in less than 3 ms total.

Part 3 - USB Protocol

I've created an LPCXpresso project that implements a USB to SWD bridge. This project and code can be reused to create a debugger or flash programmer and consumes about 9K of Flash. I can probably release this code but haven't posted it yet. This chapter describes the USB protocol between the host and the LPC11U14 device.

USB Device Type

The USB device is a USB 2.0 Full Speed HID peripheral. Its descriptor sets up the host PC to poll for status at 1 mS intervals. Each USB transfer is 64 bytes long.

General Command Format

All of the commands have a similar format. The basic sequence of operations is that the PC is constantly polling the LPC11U14 and receiving In reports. If there is no status to report then the In reports from the LPC11U14 will indicate 0xFF in the Status field. Eventually, the PC writes an Out Report with an Opcode set to a non-zero value. The LPC11U14 software processes the Out Report and executes the command. The results of the command are queued up to be sent to the PC the next time it polls and requests an In report.

The Opcode field in the Out Reports indicates what action the LPC11C14 should perform when the command is received. The Address field is used to specify which DP or AP register address the action should be performed on. The Count field is used to specify a number of times that an action should be performed. Finally, a sequence number is present in the Out report layout. When a command is processed, the sequence number will be copied into Sequence field in the In report containing the command results. This sequence number is to allow the PC host to manage multiple outstanding transactions being queued in the LPC11U14 firmware.

In the In Report, Status indicates the result of the operation. It should be 1 (ACK) if there was no failure. Count indicates the number of times the operation occurred and/or the number of words returned in ReadData[0-14]. Sequence matches the Sequence value sent in the original operation Out Report request.

USB Protocol Status Values

Status Value	Status Description
1	Acknowledge- generally means no error
2	Wait- generally means to retry the transaction. Most of the USB commands trap this response and poll the target until it returns a different status.
4	Fault- this means the SWD target is reporting an error. There are sticky error bits which cause any AP transaction to return Fault until cleared.
8	Parity- this means the SWD engine in the LPC11U14 has detected a parity error in an SWD read transaction. This probably indicates a signal integrity issue such as a cable that is too long.
0xFF	This is a “null” status. It means that this In Report does not contain status or data for anything. If you have requested an operation via an Out Report, this status value means the operation has not completed yet.

USB SWD Commands

Name	ID	Command Function
Nothing	0	This command has no function and is ignored. No status will be generated in response to this command. Use this command if something must be written to the LPC11U14 and the no action is desired.
Connect	1	This command causes the LPC11U14 to attempt to connect to an SWD device. Address, Count, and WriteData[0-14] are ignored.
Read DP	2	This command reads the SWD Debug Port. The DP address is passed in Address. The Count field can range from 1 to 15 and specifies how many times to perform the read. The results are returned in ReadData[0-14] in the next In Report read by the PC. WriteData[0-14] are ignored.
Write DP	3	This command writes to the SWD Debug Port. The DP address is passed in Address. The Count field can range from 1 to 15 and specifies how many times to perform the write. The values to be written are passed in WriteData[0-14].
Read AP	4	This command reads the SWD Access Port. The AP address is passed in Address. The Count field can range from 1 to 15 and specifies how many times to perform the read. The results are returned in ReadData[0-14] in the next In Report read by the PC. WriteData[0-14] are ignored. The ability to read the same register repeatedly is useful with the Coresight capability to automatically increment the Transfer Address Register (TAR) and speeds up bulk memory reads. This command takes care of setting up the AP Select register but it does not automatically attempt to skip the dummy read words.
Write AP	5	This command writes to the SWD Access Port. The AP address is passed in Address. The Count field can range from 1 to 15 and specifies how many times to perform the write. The values to be written are passed in WriteData[0-14]. The ability to write to the same register repeatedly is useful with the Coresight capability to automatically increment the Transfer Address Register (TAR) and speeds up bulk memory writes. This command takes care of setting up the AP Select register however it does not complete the flush operation that is needed to make a write take effect immediately.
Flush	6	This command clocks eight 0s out the SWD port. This is used to flush a write to memory. See section 2.4. Address, Count, and WriteData[0-14] are all ignored.
LED	7	This command controls the LED on the LPCXpresso board. Address and Count are ignored. WriteData[0] == 0 will turn off the LED. WriteData[0]==1 will turn on the LED.
Read Mem	8	This command reads one or more values from the normal memory address space in the SWD target. The Address field is ignored. The Count field contains a value from 1 to 15 indicating how many values will be read from memory. The addresses of the values to be read from memory are passed in WriteData[0-14]. The data read from memory will be returned in ReadData[0-14] during the next In report after completion. This command handles all of the SWD idiosyncrasies such as dummy reads.
Write Mem	9	This command writes one or more values to the normal memory address space in the SWD target. The Address field is ignored. The Count field contains an even value from 2 to 14 that is 2x the number of memory addresses to be written to. Even elements in WriteData[0-13] contain the addresses to be written. Odd elements in WriteData[0-13] contain the values to be written. This command handles SWD idiosyncrasies such as the requirement to do a flush after a write to make sure a value is actually written to memory.
Run	10	This command starts the target running if it had been previously stopped. Address, Count, and WriteData[0-14] are ignored.
Stop	11	This command stops the target from running. It can be restarted with Run. Address, Count, and WriteData[0-14] are ignored.
Reset	12	This command resets the target and executes through the bootrom. To do this requires making several assumptions about the target including the location of the ROM mapping register. It sets a watchpoint on two addresses, one contains the ROM remap register typically used on the LPC1100 family and the other contains the address typically used on the LPC1700 family. It then calls Run and waits for the code to hit the breakpoint. In addition, the LPC1200 family watchdog is disabled. This command will almost certainly need some work to support a wider range of parts and will probably need to be modified to accept as a parameter the type of part being used.
Disable WDT	13	This command was added to handle the LPC1200 family’s ultra-reliable watchdog timer. This WDT comes enabled out of reset at a 4mS timeout. Calling this command should disable it.
ReadCore	14	This command reads from a CPU core register. The core registers must be specified in WriteData[0-14]. Pass the register count in Count.
WriteCore	15	This command writes to a CPU core register. The core registers are specified in the even elements of WriteData[0-13]. The data to be written is specified in the odd elements of WriteData[0-13].
Setup Invoke	16	This command stops code execution on the target and initializes a memory map in RAM that allows calling ROM IAP calls. The memory map is: Address Size in Bytes Description 0x1000000016 Used to store code to make IAP calls 0x10000010512 Buffer used when programming flash 0x1000021020 Stores IAP opcode and up to 4 parameters 0x1000021A20 Stores IAP result and up to 4 return values 0x10000250256 Stack Please note that this command is disruptive. It stops code from executing on the target and modifies RAM contents and CPU core registers. Execution cannot be resumed after calling SetupInvoke.
Invoke	17	This command makes a ROM IAP call. The parameters passed to the Invoke entrypoint are WriteData[0-4] where WriteData[0] is the function number. The data retrieved from the Invoke call is sent up in the next In Report as ReadData[0-4]. A timeout in mS is passed in WriteData[5].