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: Request

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

send(jlink)¶

Starts the SWD transaction.

Steps for a Read Transaction:

First phase in which the request is sent.
Second phase in which an ACK is received. This phase consists of three bits. An OK response has the value 1.
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.
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: 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: 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: Request

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

send(jlink)¶

Starts the SWD transaction.

Steps for a Write Transaction:

First phase in which the request is sent.
Second phase in which an ACK is received. This phase consists of three bits. An OK response has the value 1.
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.
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.