Protocols

The J-Link has multiple ways of communicating with a target: Serial Wire Debug (SWD), Serial Wire Output (SWO), Memory, Coresight, Registers, etc. For some of these communication methods, there is a specific protocol that defines how the communication takes place.

This module provides definitions to facilate communicating over the different protocols. All the methods use a JLink instance, but take care of the housekeeping work involved with each protocol.

Serial Wire Debug (SWD)

This subsection defines the classes and methods needed to use the SWD protocol.

class pylink.protocols.swd.ReadRequest(address, ap)

Bases: pylink.protocols.swd.Request

Definition for a SWD (Serial Wire Debug) Read Request.

send(jlink)

Starts the SWD transaction.

Steps for a Read Transaction:
  1. First phase in which the request is sent.
  2. Second phase in which an ACK is received. This phase consists of three bits. An OK response has the value 1.
  3. Once the ACK is received, the data phase can begin. Consists of 32 data bits followed by 1 parity bit calclulated based on all 32 data bits.
  4. After the data phase, the interface must be clocked for at least eight cycles to clock the transaction through the SW-DP; this is done by reading an additional eight bits (eight clocks).
Parameters:
  • self (ReadRequest) – the ReadRequest instance
  • jlink (JLink) – the JLink instance to use for write/read
Returns:

An Response instance.

class pylink.protocols.swd.Request(address, ap, data=None)

Bases: _ctypes.Union

Definition of a SWD (Serial Wire Debug) Request.

An SWD Request is composed of 8 bits.

start

the start bit is always one

ap_dp

indicates whether the transaction is DP (0) or AP (1).

read_write

indicates if the transaction is a read-access (1) or a write-access (0).

address
parity

the parity bit, the bit is used by the target to verify the integrity of the request. Should be 1 if bits 1-4 contain an odd number of 1``s, otherwise ``0.

stop

the stop bit, should always be zero.

park

the park bit, should always be one.

value

the overall value of the request.

addr2

Structure/Union member

addr3

Structure/Union member

ap_dp

Structure/Union member

bit

Structure/Union member

parity

Structure/Union member

park

Structure/Union member

read_write

Structure/Union member

send(jlink)

Starts the SWD transaction.

Sends the request and recieves an ACK for the request.

Parameters:
  • self (Request) – the Request instance
  • jlink (JLink) – the JLink instance to use for write/read
Returns:

The bit position of the ACK response.

start

Structure/Union member

stop

Structure/Union member

value

Structure/Union member

class pylink.protocols.swd.RequestBits

Bases: _ctypes.Structure

SWD request bits.

addr2

Structure/Union member

addr3

Structure/Union member

ap_dp

Structure/Union member

parity

Structure/Union member

park

Structure/Union member

read_write

Structure/Union member

start

Structure/Union member

stop

Structure/Union member

class pylink.protocols.swd.Response(status, data=None)

Bases: object

Response class to hold the response from the send of a SWD request.

STATUS_ACK = 1
STATUS_FAULT = 4
STATUS_INVALID = -1
STATUS_WAIT = 2
ack()

Returns whether the response was ACK’d.

Parameters:self (Response) – the Response instance
Returns:True if response was ACK’d, otherwise False.
fault()

Returns whether the response exited with fault.

Parameters:self (Response) – the Response instance
Returns:True if response exited with a fault, otherwise False.
invalid()

Returns whether the response exited with a bad result.

This occurs when the parity is invalid.

Parameters:self (Response) – the Response instance
Returns:True if the parity checked failed, otherwise False.
wait()

Returns whether the response was a wait.

Parameters:self (Response) – the Response instance
Returns:True if response exited with wait, otherwise False.
class pylink.protocols.swd.WriteRequest(address, ap, data)

Bases: pylink.protocols.swd.Request

Definition for a SWD (Serial Wire Debug) Write Request.

send(jlink)

Starts the SWD transaction.

Steps for a Write Transaction:
  1. First phase in which the request is sent.
  2. Second phase in which an ACK is received. This phase consists of three bits. An OK response has the value 1.
  3. Everytime the SWD IO may change directions, a turnaround phase is inserted. For reads, this happens after the data phase, while for writes this happens after between the acknowledge and data phase, so we have to do the turnaround before writing data. This phase consists of two bits.
  4. Write the data and parity bits.
Parameters:
  • self (WriteRequest) – the WriteRequest instance
  • jlink (JLink) – the JLink instance to use for write/read
Returns:

An Response instance.