Serial Wire Debug¶

Serial Wire Output (SWO) alongside Serial Wire Debug (SWD) allows for the CPU to emit real-time trace data. In particular, when used with an Instrumentation Trace Macrocell (ITM), it can be used to form a Serial Wire Viewer (SWV). The ITM ports are provided by the ARM controller. The SWV typically implements a form of printf style debugging for embedded systems.

Getting Started¶

First, get your J-Link set up by instantiating an instance of a JLink and connecting to your target device. Once that is established, you want to call either swo_start():

speed = 9600
jlink.swo_start(swo_speed=speed)

or call swo_enable():

swo_speed = 9600
cpu_speed = 72000000 # 72 MHz
port_mask = 0x01
jlink.swo_enable(cpu_speed, swo_speed, port_mask)

Once enabled, you can begin reading data from the target.

Serial Wire Methods¶

class pylink.jlink.JLink(lib=None, log=None, detailed_log=None, error=None, warn=None, unsecure_hook=None, serial_no=None, ip_addr=None, open_tunnel=False, use_tmpcpy=None)

Python interface for the SEGGER J-Link.

This is a wrapper around the J-Link C SDK to provide a Python interface to it. The shared library is loaded and used to call the SDK methods.

swd_read16(offset)

Gets a unit of 16 bits from the input buffer.

Parameters:

self (JLink) – the JLink instance
offset (int) – the offset (in bits) from which to start reading

Returns:

The integer read from the input buffer.

swd_read32(offset)

Gets a unit of 32 bits from the input buffer.

Parameters:

self (JLink) – the JLink instance
offset (int) – the offset (in bits) from which to start reading

Returns:

The integer read from the input buffer.

swd_read8(offset)

Gets a unit of 8 bits from the input buffer.

Parameters:

self (JLink) – the JLink instance
offset (int) – the offset (in bits) from which to start reading

Returns:

The integer read from the input buffer.

swd_sync(pad=False)

Causes a flush to write all data remaining in output buffers to SWD device.

Parameters:

self (JLink) – the JLink instance
pad (bool) – True if should pad the data to full byte size

Returns:

None

swd_write(output, value, nbits)

Writes bytes over SWD (Serial Wire Debug).

Parameters:

self (JLink) – the JLink instance
output (int) – the output buffer offset to write to
value (int) – the value to write to the output buffer
nbits (int) – the number of bits needed to represent the output and value

Returns:

The bit position of the response in the input buffer.

swd_write16(output, value)

Writes two bytes over SWD (Serial Wire Debug).

Parameters:

self (JLink) – the JLink instance
output (int) – the output buffer offset to write to
value (int) – the value to write to the output buffer

Returns:

The bit position of the response in the input buffer.

swd_write32(output, value)

Writes four bytes over SWD (Serial Wire Debug).

Parameters:

self (JLink) – the JLink instance
output (int) – the output buffer offset to write to
value (int) – the value to write to the output buffer

Returns:

The bit position of the response in the input buffer.

swd_write8(output, value)

Writes one byte over SWD (Serial Wire Debug).

Parameters:

self (JLink) – the JLink instance
output (int) – the output buffer offset to write to
value (int) – the value to write to the output buffer

Returns:

The bit position of the response in the input buffer.

swo_enable(cpu_speed, swo_speed=9600, port_mask=1)

Enables SWO output on the target device.

Configures the output protocol, the SWO output speed, and enables any ITM & stimulus ports.

This is equivalent to calling .swo_start().

Note

If SWO is already enabled, it will first stop SWO before enabling it again.

Parameters:

self (JLink) – the JLink instance
cpu_speed (int) – the target CPU frequency in Hz
swo_speed (int) – the frequency in Hz used by the target to communicate
port_mask (int) – port mask specifying which stimulus ports to enable

Returns:

None

Raises:

JLinkException – on error

swo_flush(num_bytes=None)

Flushes data from the SWO buffer.

After this method is called, the flushed part of the SWO buffer is empty.

If num_bytes is not present, flushes all data currently in the SWO buffer.

Parameters:

self (JLink) – the JLink instance
num_bytes (int) – the number of bytes to flush

Returns:

None

Raises:

JLinkException – on error

swo_num_bytes()

Retrives the number of bytes in the SWO buffer.

Parameters:: self (JLink) – the JLink instance
Returns:: Number of bytes in the SWO buffer.
Raises:: JLinkException – on error

swo_read(offset, num_bytes, remove=False)

Reads data from the SWO buffer.

The data read is not automatically removed from the SWO buffer after reading unless remove is True. Otherwise the callee must explicitly remove the data by calling .swo_flush().

Parameters:

self (JLink) – the JLink instance
offset (int) – offset of first byte to be retrieved
num_bytes (int) – number of bytes to read
remove (bool) – if data should be removed from buffer after read

Returns:

A list of bytes read from the SWO buffer.

swo_read_stimulus(port, num_bytes)

Reads the printable data via SWO.

This method reads SWO for one stimulus port, which is all printable data.

Note

Stimulus port 0 is used for printf debugging.

Parameters:

self (JLink) – the JLink instance
port (int) – the stimulus port to read from, 0 - 31
num_bytes (int) – number of bytes to read

Returns:

A list of bytes read via SWO.

Raises:

ValueError – if port < 0 or port > 31

swo_set_emu_buffer_size(buf_size)

Sets the size of the buffer used by the J-Link to collect SWO data.

Parameters:

self (JLink) – the JLink instance
buf_size (int) – the new size of the emulator buffer

Returns:

None

Raises:

JLinkException – on error

swo_set_host_buffer_size(buf_size)

Sets the size of the buffer used by the host to collect SWO data.

Parameters:

self (JLink) – the JLink instance
buf_size (int) – the new size of the host buffer

Returns:

None

Raises:

JLinkException – on error

swo_speed_info()

Retrieves information about the supported SWO speeds.

Parameters:: self (JLink) – the JLink instance
Returns:: A JLinkSWOSpeedInfo instance describing the target’s supported SWO speeds.
Raises:: JLinkException – on error

swo_start(swo_speed=9600)

Starts collecting SWO data.

Note

If SWO is already enabled, it will first stop SWO before enabling it again.

Parameters:

self (JLink) – the JLink instance
swo_speed (int) – the frequency in Hz used by the target to communicate

Returns:

None

Raises:

JLinkException – on error

swo_stop()

Stops collecting SWO data.

Parameters:: self (JLink) – the JLink instance
Returns:: None
Raises:: JLinkException – on error

swo_supported_speeds(cpu_speed, num_speeds=3)

Retrives a list of SWO speeds supported by both the target and the connected J-Link.

The supported speeds are returned in order from highest to lowest.

Parameters:

self (JLink) – the JLink instance
cpu_speed (int) – the target’s CPU speed in Hz
num_speeds (int) – the number of compatible speeds to return

Returns:

A list of compatible SWO speeds in Hz in order from highest to lowest.

Serial Wire Debug¶

Getting Started¶

Serial Wire Methods¶

Examples¶

Serial Wire Viewer¶