From RTSC-Pedia

[printable version]

offline version generated on 04-Aug-2010 21:08 UTC

ROV Module Writers Guide/Fundamentals

The basics of creating an ROV view

ROV Fundamentals

Each module that contributes to ROV defines an instance and / or a module "view structure" which defines the data to be displayed in ROV. Each module also defines a set of "view initialization" functions which process the module and instance state data from the target to populate these view structures.

ROV manages the complexity of retrieving and decoding data from the target, so the module writer's responsibility is merely to shape and organize the data to make it suitable to display.

Since ROV can be used to debug a broken system, another role of ROV is to validate the target data, identifying any errors with it and conveying those errors to the ROV user. This validation is done as part of the view initialization functions.

There are essentially three steps to creating an ROV view for a module:

1. Define a view structure in Mod.xdc which indicates the fields that will be displayed.
2. Define the name of the view tab in Mod.xdc, specifying what view structure to use and what view initialization function to call.
3. Write the view initialization function in Mod.xs.

Defining The Views

The view structures, which define what to display in ROV, are defined in the module specification file (e.g., Mod.xdc) for each module. The field names of these structures will be the column headers in the GUI. The column headers will also be in the same order as the fields in the structure.

The view structures may have any name. By convention, they are named after their view tab. For example, "BasicView", "DetailedView", and "ModuleView".

Below are some example view structures.

metaonly struct BasicView {
    String  label;
    Int     priority;
    String  mode;
    SizeT   stackSize;
    Ptr     stack; 
    String  fxn[];
    UArg    arg0; 
    UArg    arg1; 
    SizeT   stackPeak;
}

metaonly struct ModuleView {
    Bool    schedulerLocked;
    Bits32  readyQStatesMask;
    Bool    workPending;
    UInt    numVitalTasks;
    Ptr     currentTask;
}

Because the ROV GUI displays data in tables, the fields of these structures must be primitive types (integers, strings, pointers, booleans). They cannot be structures, because the GUI cannot display hierarchical data in table form. Arrays of primitive types are allowed, however. Arrays are displayed in the GUI as drop down menus.

All views automatically have an "address" field, which will appear as the first field in the display, so "address" should not be included as a field in these view structures.

When you use the ROV GUI and click on a module on the left hand side, you'll notice that a number of tabs appear on the right hand side, such as "Basic", "Detailed", "Module", and "Raw".

These tabs help to organize the data and separate the instance views, module views, and raw data. They also provide a way of managing the performance of ROV. Data can be divided across the tabs based on how long it takes to retrieve and process, so that some tabs may be accessed quicker than others.

ROV communicates with the target through CCS and reading and decoding memory from the target can be slow. For a module that needs to read a large amount of data from the target, you might create two separate instance views. The "Basic" tab could just read the state structures and provide basic information, while a "Detailed" tab could read more data and present more information. This way, if a user is only interested in the "Basic" data, then this data will be returned to them quickly -- the user only has to pay the penalty of the large memory reads if they are interested in the extra data.

The "Raw" tab is provided automatically by ROV, and will appear automatically for any module, even those that do not specify anything to display in ROV. All other tabs are specified in the module specification file by configuring the module's ROV facet configuration parameter.

import xdc.rov.ViewInfo
 
...
 
@Facet
metaonly config ViewInfo.Instance rovViewInfo = 
    ViewInfo.create({
        viewMap: [
            ['Basic',    {type: ViewInfo.INSTANCE, viewInitFxn: 'viewInitBasic',    structName: 'BasicView'}],
            ['Detailed', {type: ViewInfo.INSTANCE, viewInitFxn: 'viewInitDetailed', structName: 'DetailedView'}],
            ['Module',   {type: ViewInfo.MODULE,   viewInitFxn: 'viewInitModule',   structName: 'ModuleView'}],
        ]
    });

The ROV facet is an instance of the module xdc.rov.ViewInfo . The instance's viewMap property defines the views that are displayed in ROV for this module.

The tabs will appear in the order they are specified in the ROV facet. The "Raw" tab should not be on this list; ROV adds it automatically and it will always be the last tab displayed.

Each tab in the facet defines three properties:

• type -- The type of the view (instance, module, etc.), defined by xdc.rov.ViewInfo.ViewType.
• viewInitFxn -- Specifies the XDC script function to run in order to populate the view structure for this tab.
• structName -- The name of the view structure to use for this tab.

Tabs may have any name you choose, and can include spaces and special characters. For consistency with other modules, however, it is recommended to begin with the terms "Basic", "Detailed", and "Module".

View Function Basics

The view initialization functions belong in your module's XS script (e.g., Mod.xs). They may have any name you choose, since the name is specified in the 'viewFxn' field in the module's ROV facet.

The view function parameters depend on the view type. For an instance view, the function takes two parameters, 'view' and 'obj'. The first parameter is an instance of the view structure to be populated for display. The second parameter is an instance state object from the target which contains the target data.

Initializing most of the fields is often as easy as copying a value from the target state structure to the view structure.

/*
 * ======== viewInitBasic ========
 * Initialize the 'Basic' instance view.
 */
function viewInitBasic(view, obj)
{
    view.priority = obj.priority; 
    view.stackSize = obj.stackSize;
    ...
}

The obj parameter only contains simple scalar data. ROV does not follow any pointers automatically--any pointers in the target structure will appear as addresses, not the data they point to. Retrieving data from pointers is covered later.