General UDP Packet Structure

UDP packet structure

The UDP packets exchanged between the QSPY Back-End and the QView Front-End consists of:

1-byte Sequence-No, which increments by 1 for every packet and wraps naturally from 0xFF to 0. The sequence number allows QView to detect any data discontinuities.
1-byte Record-ID. The Record-IDs are divided into two categories:
- Records to and from the Target have Record-IDs in the range 0..127. Specifically, QS records originated from the Target are enumerated in QSpyRecords. Records destined to the Target are enumerated in QSpyRxRecords.
- Records to and from the QSPY Back-End have record-IDs in the range 128..255. Specifically, records destined to QSPY are enumerated in QSpyCommands.
optional Data Payload, which can be either text or binary, depending on the UDP Channel to which the front-end attaches. The various Data Payloads for different packets are described in the separate sections below.

UDP Data Channels

The QSPY UDP socket supports two "channels":

binary channel (channel 1), in which the Data Payload is sent in binary, but after removing escaping and checksum;
text channel (channel 2), in which the Data Payload is sent in the QSPY Textual Format;

A Front-End can choose the "data channels" when "attaching" to the QSPY host application (see qspy::attach()). The data channels are not exclusive, meaning that a front-end can "attach" simultaneously to both binary and text channels. In this case, the front-end would receive each packet as both binary and text formats.

Remarks: The binary-channel (0x01) is used by the QView GUI front-end, while the text-channel (0x02) is used by the QUTest Unit Testing front-end.

Records to the Target

Query Target Info (INFO)

This packet has Record-ID==INFO and has no Data Payload.

Note: To understand the following detailed UDP packet descriptions, it is highly recommended to read the Python documentation for the Python struct.pack() command.

All data to and from the Target are sent according to the QP/Spy™ Data Protocol in little endian.

Code Example:

::qspy::sendPkt [binary format c $::qspy::QS_RX(INFO)]

Execute a User-Defined Command in the Target (COMMAND)

This packet has Record-ID==COMMAND and Data Payload of the form:

Data item	binary format	description
Command-ID	B (byte)	command number
Command-Par	I (unsigned 4-byte integer)	command parameter

Reset the Target (RESET)

This packet has Record-ID==RESET and has no Data Payload.

Call QF_TICK_X() in the Target (TICK)

Data item	binary format	description
Tick-rate	B (byte)	system tick rate number

Peek Target Memory (PEEK)

This packet has Record-ID==PEEK and Data Payload of the form:

Data item	binary format	description
Peek-addr	Target-dependent Typically I	Address of the data in the Target
Peek-length	B (byte)	Number of bytes to peek

Poke Target Memory (POKE)

This packet has Record-ID==POKE and Data Payload of the form:

Data item	binary format	description
Poke-addr	Target-dependent Typically I	Address of the data in the Target
Poke-length	B (byte)	Number of bytes to poke (<= 8)
Poke-data	user-defined	Binary data to poke to the Target (8 bytes maximum)

Note: The Poke-data part of the Data Payload must be formatted with the particular endianness of the Target and with any padding required for proper alignment of objects in the Target memory.

Set Global Filters in the Target (GLB_FILTER)

This packet has Record-ID==GLB_FILTER and Data Payload of the form:

Data item	binary format	description
Data Len	B (byte)	Number of bytes sent (currently 16)
Filters	16B	8-bytes (128-bits), each bit corresponding to Global Filter

Set Local Filters in the Target (LOC_FILTER)

This packet has Record-ID==LOC_FILTER and Data Payload of the form:

Data item	binary format	description
Local filter #	B (byte)	The Number of the Local Filter
Object-addr	Target-dependent Typically I	Address of the object in the Target

The Local filters are numbered as follows:

0. State Machine Local Filter (SM)

Active Object Local Filter (AO)
Memory Pool Local Filter (MP)
Event Queue Local Filter (EQ)
Time Event Local Filter (TE)
Application-Specific Local Filter (AP)

Set Local AO Filter in the Target (AO_FILTER)

This packet provides a shortcut for setting the Active Object Local Filter by providing just the unique priority of the AO. The packet has Record-ID==AO_FILTER and Data Payload of the form:

Data item	binary format	description
AO prio	B (byte)	Priority of the AO to filter (0 to disable the AO filter)

Inject an Event to the Target (EVENT)

This packet has Record-ID==EVENT and Data Payload of the form:

Data item	binary format	description
AO prio	B (byte)	Priority of the recipient AO (0 to publish the event)
signal	Target-dependent Typically H	signal of the event
parameters	user-defined	Binary data corresponding to all event parameters

The Event signal sig must be formatted according to the Target configuration (see Q_SIGNAL_SIZE)

The Event parameters must be formatted with the particular endianness of the Target and with any padding required for proper alignment of objects in the Target memory.

The parameters need to match exactly the event memory layout in your Target, including the endianness and any padding that the Target compiler might be using. (To test the right binary format and padding, you can use the Generate Event... command).

For example, let's assume that the parameters of your event are: a byte, followed by a 2-byte integer, followed by a 4-byte integer. Also, let's assume that your Target is little endian. From the Generate Event... command you discover that to format this event correctly you need to use the following event parameters:

Par #	format	data (example)
par1:	B	0x11
par2:	B	0x00
par3:	H	0x1122
par4:	I	0x11223344

Packets to the QSPY Back-End

Attach to the QSPY Back-End (ATTACH)

This packet has Record-ID==ATTACH and Data Payload of the form:

Data item	binary format	description
channels	B (byte)	Binary bitmask of QSPY channels to attach to

Detach from the QSPY Back-End (DETACH)

This packet has Record-ID==DETACH and has no Data Payload.

Save Dictionaries to a File in QSPY (SAVE_DIC)

This packet has Record-ID==SAVE_DIC and has no Data Payload.

Toggle Screen Output to a File in QSPY (SCREEN_OUT)

This packet has Record-ID==SCREEN_OUT and has no Data Payload.

Toggle Binary Output to a File in QSPY (BIN_OUT)

This packet has Record-ID==BIN_OUT and has no Data Payload.

Toggle MATLAB Output to a File in QSPY (MATLAB_OUT)

This packet has Record-ID==MATLAB_OUT and has no Data Payload.

Toggle Sequence Output to a File in QSPY (SEQUENCE_OUT)

This packet has Record-ID==SEQUENCE_OUT and has no Data Payload.

Packets from the QSPY Back-End

Attach Response from the QSPY Back-End (ATTACH)

This packet has Record-ID==ATTACH and has no Data Payload.

Detach Request from the QSPY Back-End (DETACH)