Data Exchange Formats

Introduction

Interaction between components in OSD requires that a common “language” is spoken. The data exchange formats described in this chapter are this “language,” they are employed between OSD modules, as well as between the host and the OSD-enabled target.

General Considerations

In Open SoC Debug, the native word width is 16 bit. The byte ordering is big endian. Exceptions are mentioned explicitly in the specification.

The Debug Packet

The main data exchange format in OSD is the Debug Packet (DP). A Debug Packet is a routable and typed piece of information, consisting of

• a destination address
• a source address
• a type
• a payload

The payload format depends on the type of the packet. For some types the payload format is strictly specified, while other types can be used to transfer data which is not specified in this specification.

Length Limitations

Each debug packet consists of at least three 16 bit wide words. A packet MUST NOT consist of more than \(2^{16}-1 = 65535 \text{ words}\), including all headers. Implementations MAY impose a lower limit, but the limit may not be less than 12 words.

The maximum packet length within a subnet can be determined by reading the MAX_PKT_LEN register from the SCM module.

Debug Packet Structure

A Debug Packet consists of a multiple words as described in the table below.

Table 1 Debug Packet (DP) Structure

Word	Name	Description
0	DEST	Packet destination address
1	SRC	Packet source address
2	FLAGS	Packet flags
3 .. packet size	PAYLOAD	Payload (content) of the Debug Packet

Table 2 Field Reference: FLAGS

Bit(s)	Field	Description
15:14	TYPE	Packet Type 0b00: REG (Register Access) Access to a register in a debug module. Register accesses are synchronous read and write operations on a debug module. 0b01: RESERVED for future use Implementations MUST discard packets of this type. 0b10: EVENT (Debug Event) Unsolicited debug event generated by any of the debug modules. The payload of Debug Packets of this type is module-specific. 0b11: RESERVED for future use Implementations MUST discard packets of this type.
13:10	TYPE_SUB	Packet Subtype The packet subtype refines the packet type (TYPE). Allowed values depend on the TYPE field.
9:0	RESERVED	Reserved Reserved space for future extensions. Senders must set this field to zero, receivers must ignore its contents.

Register access (TYPE == REG)

Register accesses are Debug Packets which access a single register in a debug module. All accesses are synchronous: read requests trigger a read response, write requests are acknowledged.

All register accesses must set the TYPE field of a Debug Packet to REG. The field TYPE_SUB describes the type of register access, allowed values are listed in the following table.

Table 3 Reference of Debug Packet subtypes for register accesses

Field Name	TYPE_SUB Value	Description
REQ_READ_REG_16	0b0000	16 bit register read request
REQ_READ_REG_32	0b0001	32 bit register read request
REQ_READ_REG_64	0b0010	64 bit register read request
REQ_READ_REG_128	0b0011	128 bit register read request
RESP_READ_REG_SUCCESS_16	0b1000	16 bit register read response
RESP_READ_REG_SUCCESS_32	0b1001	32 bit register read response
RESP_READ_REG_SUCCESS_64	0b1010	64 bit register read response
RESP_READ_REG_SUCCESS_128	0b1011	128 bit register read response
RESP_READ_REG_ERROR	0b1100	register read failure
REQ_WRITE_REG_16	0b0100	16 bit register write request
REQ_WRITE_REG_32	0b0101	32 bit register write request
REQ_WRITE_REG_64	0b0110	64 bit register write request
REQ_WRITE_REG_128	0b0111	128 bit register write request
RESP_WRITE_REG_SUCCESS	0b1110	the preceding write request was successful
RESP_WRITE_REG_ERROR	0b1111	the preceding write request failed

Register read request (TYPE_SUB ==  REQ_READ_REG_*)

Read from a single register. Reads from 16, 32, 64 and 128 bit wide registers are supported, the appropriate DP Subtype (TYPE_SUB) must be used to select the register width. The address ADDR must be 16 bit wide. ADDR addresses 16 bit and must be aligned to the register size.

A debug module MUST respond with a RESP_READ_REG_SUCCESS_* of the same size as the read in case of a successful read, or a RESP_READ_REG_ERROR Debug Packet in case of an error.

Table 4 Debug Packet payload for register read requests (TYPE == REG && TYPE_SUB == REQ_READ_REG_*)

Payload word	Field name	Description
0	ADDR	Register address to read from

Register read response (TYPE_SUB == RESP_READ_REG_SUCCESS_*)

The preceding register read request (TYPE_SUB == REQ_READ_REG_*) was successful, the payload is the data read from the address given in the request.

Table 5 Debug Packet payload for a response to a 16 bit register read request (TYPE_SUB == RESP_READ_REG_SUCCESS_16)

Payload word	Field name	Description
0	DATA[15:0]	data word read from the register

Table 6 Debug Packet payload for a response to a 32 bit register read request (TYPE_SUB == RESP_READ_REG_SUCCESS_32)

Payload word	Field name	Description
0	DATA[31:16]	bits 31 to 16 of the data read from the register (most significant word)
1	DATA[15:0]	bits 15 to 0 of the data read from the register (least significant word)

Table 7 Debug Packet payload for a response to a 64 bit register read request (TYPE_SUB == RESP_READ_REG_SUCCESS_64)

Payload word	Field name	Description
0	DATA[63:48]	bits 63 to 48 of the data read from the register (most significant word)
1	DATA[47:32]	bits 47 to 32 of the data read from the register
2	DATA[31:16]	bits 31 to 16 of the data read from the register
3	DATA[15:0]	bits 15 to 0 of the data read from the register (least significant word)

Table 8 Debug Packet payload for a response to a 128 bit register read request (TYPE_SUB == RESP_READ_REG_SUCCESS_128)

Payload word	Field name	Description
0	DATA[127:112]	bits 127 to 112 of the data read from the register (most significant word)
1	DATA[111:96]	bits 111 to 96 of the data read from the register
2	DATA[95:80]	bits 95 to 80 of the data read from the register
3	DATA[79:64]	bits 79 to 64 of the data read from the register
4	DATA[63:48]	bits 63 to 48 of the data read from the register
5	DATA[47:32]	bits 47 to 32 of the data read from the register
6	DATA[31:16]	bits 31 to 16 of the data read from the register
7	DATA[15:0]	bits 15 to 0 of the data read from the register (least significant word)

Register error read response (TYPE_SUB == RESP_READ_REG_ERROR)

The preceding register read request to this module failed for some reason.

Register write request (TYPE_SUB == REQ_WRITE_REG_*)

Writes to a register. Writes to 16, 32, 64 and 128 bit wide registers are supported, the appropriate DP Subtype (TYPE_SUB) must be used to select the register width. The address ADDR must be 16 bit wide. ADDR addresses 16 bit and must be aligned to the register size.

A debug module MUST respond with a RESP_WRITE_REG_SUCCESS Debug Packet in case the write was executed successfully, or a RESP_WRITE_REG_ERROR Debug Packet if the write failed.

Table 9 Debug Packet payload for 16 bit register write requests (TYPE == REG && TYPE_SUB == REQ_WRITE_REG_16)

Payload word	Field name	Description
0	ADDR	Register address to write to
1	DATA[15:0]	data word to be written to the register

Table 10 Debug Packet payload for 32 bit register write requests (TYPE == REG && TYPE_SUB == REQ_WRITE_REG_32)

Payload word	Field name	Description
0	ADDR	Register address to write to
1	DATA[31:16]	bits 31 to 16 of the data to be written to the register (most significant word)
2	DATA[15:0]	bits 15 to 0 of the data to be written to the register (least significant word)

Table 11 Debug Packet payload for 64 bit register write requests (TYPE == REG && TYPE_SUB == REQ_WRITE_REG_64)

Payload word	Field name	Description
0	ADDR	Register address to write to
1	DATA[63:48]	bits 63 to 48 of the data to be written to the register (most significant word)
2	DATA[47:32]	bits 47 to 32 of the data to be written to the register
3	DATA[31:16]	bits 31 to 16 of the data to be written to the register
4	DATA[15:0]	bits 15 to 0 of the data to be written to the register (least significant word)

Table 12 Debug Packet payload for 128 bit register write requests (TYPE == REG && TYPE_SUB == REQ_WRITE_REG_128)

Payload word	Field name	Description
0	ADDR	Register address to write to
1	DATA[127:112]	bits 127 to 112 of the data to be written to the register (most significant word)
2	DATA[111:96]	bits 111 to 96 of the data to be written to the register
3	DATA[95:80]	bits 95 to 80 of the data to be written to the register
4	DATA[79:64]	bits 79 to 64 of the data to be written to the register
5	DATA[63:48]	bits 63 to 48 of the data to be written to the register
6	DATA[47:32]	bits 47 to 32 of the data to be written to the register
7	DATA[31:16]	bits 31 to 16 of the data to be written to the register
8	DATA[15:0]	bits 15 to 0 of the data to be written to the register (least significant word)

Register write response: successful (TYPE_SUB == RESP_WRITE_REG_SUCCESS)

The preceding register write request to the module was successful (write acknowledgement).

Unless explicitly documented in the module documentation, the RESP_WRITE_REG_SUCCESS implies that all actions triggered by the corresponding register write have been executed fully.

Register write response: error (TYPE_SUB == RESP_WRITE_REG_ERROR)

The preceding register write request to the module was not successful.

Event Debug Packets (EVENT)

Debug Events are Debug Packets sent by a debug module without being explicitly triggered by the host or by another module. The main purpose of Debug Events is to transport trace data, but they can also be used for other purposes. Hence this specification does not attempt to specify the payload of event packets strictly.

Table 13 Reference of Debug Packet subtypes for event packets

Field Name	TYPE_SUB Value	Description
EV_LAST	0b0000	Standalone event packet, or in split event transmissions, the last packet in the transmission
EV_CONT	0b0001	A non-last event packet in a split event transmission
EV_OVERFLOW	0b0005	An overflow happened

Split Event Transmissions

All event packets must set the TYPE field of a Debug Packet to EVENT. Event packets must be not larger then the maximum packet length, which can be obtained from the SCM module. If payload should be transmitted which is larger than the maximum DI packet size the payload can be “split” into two or more packets. In this case, all but the last event packets set TYPE_SUB to 1,

For the TYPE_SUB The field TYPE_SUB and the packet payload are defined by the debug module itself.

Overflows

If the debug system is overloaded, events may be dropped by the producer. If this happens, the producer counts the dropped packet and sents an overflow packet once it is able to transmit again. The overflow packet contains the number of dropped packets as only data word. Overflow packets have TYPE_SUB set to OVERFLOW.