QTools  6.6.0
QSpyView User Interface

The qspyview.tcl script provides a simple Graphical User Interface (GUI) consisting of the main menu, the text view, the canvas view, and the status bar.

QSpyView user interface

The main menu includes several useful commands, which are quickly reviewed and the following sections. The main menu might subsequently be augmented in your own customizations.

File Menu

The File menu provides interface to the QSPY saving files feature. This menu allows you to trigger QSPY to save dictionaries, as well as to open/close all other file formats supported by QSPY.

View Menu

The View menu allows you to toggle (show/hide) the two main views: the Text view and the Canvas view.

Text-view and Canvas-view menus
Canvas-view enabled
Text-view disabled
The provided screen shots of the Text-view and the Canvas-view are specific to the DPP example application (see Customizing and Extending QSpyView).

Filters Menu

The Filters menu opens dialog boxes through which you can set the QSPY filters.

Setting Global Filters

The Q-SPY Global Filter dialog box allows you to turn each individual global trace record on and off. The Global Filter has two main components: the standard Q-SPY trace records (see QSpyRecords), and the User-specific trace records (starting with the offset QS_USER). The User QS Records are visible when you scroll down the "Global Filters" dialog box.

The "Global Filter" dialog box does not show the "Miscellaneous" QS trace records (such as QS_OBJ_DICT, QS_TARGET_INFO, etc.), because these trace records are "not maskable", meaning that they are always enabled and cannot be turned off by the Global Filter.

Setting Local Filters

The Q-SPY Local Filter dialog box allows you to set each individual local filter.

The dialog box accepts the addresses of the objects in decimal and in hexadecimal (with the 0x prefix), as shown in the screen-shot above.

Setting Active Object Filter

The "Active Object" filter is a shortcut to setting the Q-SPY local filter for a given active object in the Target. Specifically, the "Active Object" filter sets the two local filters QS_FILTER_AO_OBJ and QS_FILTER_SM_OBJ to the same Active Object with the specified priority (NOTE: Each Active Object has a unique priority in QP).

setting Active Object filter to AO with priority 6

Commands Menu

The Commands menu allows you to execute simple commands (without parameters) in the Target, such as Reset the Target, Query the Target, and clock Tick at rate 0 and rate 1. Also, this menu allows you to execute commands with parameters, which are quickly discussed below

Executing User Command

The "User Command..." menu allows you to invoke a command in the Target and pass up to three parameters to this command. (NOTE: a command is an application-specific callback function that the QS-RX component executes in the Target).

The following screen shot shows how to execute User Command number 21 with the parameters: 111, 0x222 and 333. Both the command number and the parameters can be specified in hexadecimal (with the 0x prefix).

Peek Command

The Peek Obj/Addr... command opens a dialog box, in which you can provide the Target object or address (RAM or ROM) (NOTE: You can provide either the object name, which must be known by its object-dictionary, or numerical address, which must be a valid RAM/ROM address, or the Target might crash.)

As shown in the screen shot below, the PEEK command takes additionally the offset into the object [bytes], the size of the item [1/2/4 bytes] and the number of units (1..255) you wish to "peek".

The Target responds with a QS_PEEK_DATA trace record, which you can view in QSPY human-readable output (the packet is also sent to QSpyView, where you can react to it in your customization.)

           Trg-Ack  QS_RX_CURR_OBJ
3558939043 Trg-Peek Offs=0,Size=4,Num=10,Data=<00012345,00000000,00000000,00000000,0000000
The Peek Command can be used to view any readable address, such as ROM, RAM, and also peripheral registers in your Target.

Poke Command

The "Poke Obj/Addr..." command allows you to write data to the specified object or address in Target's RAM (NOTE: You can provide either the object name, which must be known by its object-dictionary, or numerical address, which must be a valid RAM address, or the Target might crash.)

As shown in the screen shot below, the POKE command takes additionally the offset into the object [bytes], the format of the data (c for byte, s for little-endian uint16_t, S for big-endian uint16_t, i for little-endian uint32_t and I for big-endian uint32_t) and the data (might be in hex).

The Target responds with Trg-Ack QS_RX_CURR_OBJ and Trg-Ack QS_RX_POKE. The qspy output below shows additionally an output generated by the PEEK command that verifies that the value 0xDEAD has been poked into the object.

           Trg-Ack  QS_RX_CURR_OBJ
           Trg-Ack  QS_RX_POKE
           Trg-Ack  QS_RX_CURR_OBJ
3953414540 Trg-Peek Offs=0,Size=4,Num=10,Data=<00012345,0000DEAD,00000000,00000000,0000000
The Poke Command can be used to change any writable address, such as RAM, but also peripheral registers in your Target.

Events Menu

The "Generate Event..." menu allows you to send an arbitrary event (with up to 10 different parameters) to the Target. The event will be either posted directly to the specified Active Object, or it will be published.

As shown in the screen-shot below, you need to provide the prio of the recipient active object. (If prio is greater than zero, the event will be posted directly to the AO with that priority, otherwise the event will be published). You also need to specify the numerical value of the event signal (sig).

The optional "Event Parameters" section allows you to specify up to 10 arbitrary parameters. Each parameter is specified as a pair of format followed by data. The format is any valid specification of the format for the binary format Tcl command. For example, here the format c means a byte, while the format i means that the data should be encoded as 32-bit integer in little-endian byte order. (NOTE: The endianness you specify in the format field must match the endianness of the Target.

All the specified parameters are appended to the event packet for the target in the exact order and the specified binary format. If the event structure is represented in the Target memory with some padding, you need to provide such padding explicitly (as one of the parameters).
The main purpose of the "Generate Event..." menu is to allow you to determine experimentally the correct format of events that you wish to inject into the Target. Once the correct format has been confirmed, you can generate the events programmatically in your customization.

Custom Menu

This top-level menu is provided for your customization. It's intent is to let you add your own commands in your script.

Help Menu

This menu allows you to access the online Q-SPY help in HTML, and also allows you to open the "About" dialog box.

Next: Customizing and Extending QSpyView