QTools  6.3.7
QSPY UDP Interface

This section describes the structure of the UDP packets exchanged between the QSPY Back-End and the various front-ends, such as QUTest and QSpyView (blue arrows in the sequence diagram below). The UDP interface is implemented in the qspy.tcl script.

qspy_comm.gif
Communication between Target, QSPY, and QSpyView


Note
For better readability, the qspy.tcl script uses a convention in which UDP packets to and from the Target (red arrows) are called Records, while the word Packets is used for communication to and from the QSPY Back-End (blue arrows). For consistency, the following sections apply the same naming convention: Records for Target communication and Packets for QSPY communication.

General UDP Packet Structure

qspy_udp.gif
UDP packet structure

The UDP packets exchanged between the QSPY Back-End and the QSpyView 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 QSpyView 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 (1) is used by the QSpyView GUI front-end, while the text-channel (2) is used by the QUTest Unit Testing front-end.

Programming Interface

The qspy.tcl script provides the Tcl procedure ::qspy::sendPkt for sending a UDP packet to the QSPY Back-End. The procedure takes one parameter pkt, which contains the Record-ID byte followed by the optional Data Payload. For example, here is how to send a packet to Set Local AO Filter in the Target (AO_FILTER) for Active Object with priority 5:

::qspy::sendPkt [binary format cc $::qspy::QS_RX(AO_FILTER) 5]

Records to the Target

Note
To understand the following detailed UDP packet descriptions, it is highly recommended to read the Tcl documentation for the binary Tcl command.

Query Target Info (INFO)

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

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 c command number
Command-Par i command parameter

Code Example:

::qspy::sendPkt [binary format cci $::qspy::QS_RX(COMMAND) 12 0x11223344]

Reset the Target (RESET)

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

Code Example:

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

Call QF_TICK_X() in the Target (TICK)

Data item binary format description
Tick-rate c system tick rate number

Code Example:

::qspy::sendPkt [binary format cc $::qspy::QS_RX(TICK) 0]

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 c Number of bytes to peek

Code Example:

::qspy::sendPkt [binary format c$::qspy::theFmt(objPtr)c \
$::qspy::QS_RX(PEEK) 0x20000123 16]

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 c 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.

Code Example:

::qspy::sendPkt [binary format c$::qspy::theFmt(objPtr)cccs \
$::qspy::QS_RX(POKE) 0x20000123 0x11 0x22 0x1122]

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 c Number of bytes sent (currently 16)
Filters b128 128 bits, each bit corresponding to Global Filter

Code Example:

::qspy::sendPkt \
[binary format ccb128 $::qspy::QS_RX(GLB_FILTER) 16 $theGlbFilter]

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 # c 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)

  1. Active Object Local Filter (AO)
  2. Memory Pool Local Filter (MP)
  3. Event Queue Local Filter (EQ)
  4. Time Event Local Filter (TE)
  5. Application-Specific Local Filter (AP)

Code Example:

::qspy::sendPkt [binary format cc$::qspy::theFmt(objPtr) \
$::qspy::QS_RX(LOC_FILTER) 0 $theLocFilter(SM)]

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 c Priority of the AO to filter (0 to disable the AO filter)

Code Example:

::qspy::sendPkt [binary format cc $::qspy::QS_RX(AO_FILTER) 5]

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 c Priority of the recipient AO (0 to publish the event)
signal Target-dependent
Typically s
signal of the event
parameters user-defined Binary data corresponding to all event parameters

The Event signal and 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 event signal sig must be formatted according to the Target configuration (see Q_SIGNAL_SIZE)

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 (exampl
par1: c 0x11
par2: c 0x00
par3: s 0x1122
par4: i 0x11223344

As you can see, you need to use "padding" (par2) after the first byte. You also use little endian encoding (s, i, format specification as opposed to S, I).

With this information, you can generate the packet programmatically.

Code Example:

::qspy::sendEvent 7 5 [binary format ccsi 0x11 0x00 0x1122 0x11223344]
Note
The qspy.tcl module provides specialized procedure ::qspy::sendEvent prio sig par for injecting events to the Target.

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 c Binary bitmask of QSPY channels to attach to

Code Example:

::qspy::sendPkt [binary format cc $QSPY(ATTACH) $channels]

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 MscGen Output to a File in QSPY (MSCGEN_OUT)

This packet has Record-ID==MSCGEN_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.

Note
This packet is handled internally by the qspy.tcl script (see the ::qspy::pkt128 procedure)

Detach Request from the QSPY Back-End (DETACH)

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

Note
This packet is handled internally by the qspy.tcl script (see the ::qspy::pkt129 procedure)

Next: QSPY MATLAB Support