ROV Module Writers Guide/View Types

From RTSC-Pedia

Jump to: navigation, search

revision tip

—— LANDSCAPE orientation

[printable version]

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

ROV Module Writers Guide/View Types

Different ways to display data in the ROV GUI

1 View Types

View Types

There are five types of ROV views, defined by xdc.rov.ViewInfo.ViewType. The 'RAW' ViewType is reserved for ROV; modules can only define one of the first four views.

metaonly enum ViewType {
    INSTANCE,
    MODULE,
    INSTANCE_DATA,
    MODULE_DATA,
    RAW
}

The type of the ROV view determines how the data is displayed in the ROV GUI as well as how the view function is run.

Instance View

An instance view is displayed in the ROV GUI as a table where each instance is a separate row in the table. The below screenshot is an example.

The view initialization function for an instance view is run once per instance of the module. For example, if there are five instances of ModA in an application, then the view init function will be run five times.

XDC maintains lists of all of the dynamically and statically created instances of each module, and ROV uses these to automatically detect all of the module instances in the system.

Advanced: ROV does not automatically find embedded instances, however. Embedded instances are instances which have been allocated within another structure, and are created using the 'construct' API. ROV only discovers these instances as they are found by the views of modules containing these embedded instances. The list of embedded instances is refreshed at each breakpoint.

An instance view function is passed two arguments: (1) an instance of the view structure, and (2) an instance state structure of one of the module's instances. For example:

function viewInitBasic(view, obj)

Module View

A module view is displayed in the ROV GUI as a table with a single row. Each column is a property of the module. The below screenshot is an example.

A module view function is called only once per module. It takes two arguments: (1) the view structure, and (2) the module state structure from the target.

Instance Data View

The instance data view type is intended for displaying tables of data per instance. Good examples are displaying a list of the free memory blocks in a memory manager, or all of the records in a log buffer.

An instance data view is displayed in the ROV GUI as a combination of a tree and a table. The tree on the left side of the view contains a node for each of the instances of the module. Selecting a node from the tree on the left brings up a table of data on the right.

The view structure you define for an instance data view has a different purpose than the ones you define for an instance or module view. Rather than represent the entire instance, an instance data view structure merely represents a single element of data. Each row of an instance's data table is represented by an instance of the view structure.

An instance data view function is called once per instance. It takes two arguments: (1) An instance of the xdc.rov.Program.InstDataView structure, and (2) an instance state structure for one of the module's instances. The xdc.rov.Program.InstDataView structure contains two fields: a label and an array of elements.

metaonly struct InstDataView {
    String     label;
    Any        elements[];
}

The label field is the label you want associated with this instance which will appear as a node in the tree in the GUI.

The array of elements is the array of data elements you want to display. When you create the ROV facet for your module the 'structName' you specify for an instance data view should be a structure containing the fields you want to display in the table.

An instance data view requires that you use a special API to create instances of your view structure (the data element) to populate. Use the Program.newViewStruct(modNam, tabName) API to create each new data element.

The following example demonstrates these concepts.

ModA.xdc

import xdc.rov.ViewInfo;
 
module ModA {
 
    metaonly struct DataView {
        UInt32     val;
    }
 
    @Facet
    metaonly config ViewInfo.Instance rovViewInfo = 
        ViewInfo.create({
            viewMap: [
                ['Data', {type: ViewInfo.INSTANCE_DATA, viewInitFxn: 'viewInitData', structName: 'DataView'}],
            ]
        }); 
 
instance:
 
    create();
 
internal:
 
    struct Instance_State {
        UInt32    buffer[10];
    }
 
}

ModA.xs

/*  
 * ======== instance$static$init ======== 
 * Initialize static instance.
 */
function instance$static$init(obj, params)
{
    /* Initialize the buffer to values 0-10. */
    for (var i = 0; i < 10; i++) {
        obj.buffer[i] = i;
    }
}
 
/*
 *  ======== viewInitData ========
 *  Instance data view.
 */
function viewInitData(view, obj)
{
    var Program = xdc.useModule('xdc.rov.Program');
 
    /* Display the instance label in the tree */
    view.label = Program.getShortName(obj.$label);
 
    /* For each element of the buffer... */
    for (var i = 0; i < obj.buffer.length; i++) {
        /* Create a new data element to display the value. */
        var elem = Program.newViewStruct('rovtests.ModA', 'Data');
 
        elem.val = obj.buffer[i];
 
        /* Add the element to the list. */
        view.elements.$add(elem);
    }
}

Module Data View

The module data view type is intended for displaying a table of data which is global to the module. An example is the output buffer of the xdc.runtime.SysMin module which holds printf strings.

The view structure you define for a module data view has a different purpose than the ones you define for an instance or module view. Rather than represent the entire instance, a module data view structure merely represents a single element of data. Each row of a module data table is represented by an instance of the view structure.

A module data view function is called once per module. It takes one argument, a Program.ModDataView structure.

metaonly struct ModDataView {
    Any        elements[];
}

This structure has one field which is the array of data elements to be displayed. When you create the ROV facet for your module the 'structName' you specify for an instance data view should be a structure containing the fields you want to display in the table.

The following example demonstrates these concepts.

ModB.xdc

import xdc.rov.ViewInfo;
 
module ModB {
 
    metaonly struct DataView {
        UInt32     val;
    }
 
    @Facet
    metaonly config ViewInfo.Instance rovViewInfo = 
        ViewInfo.create({
            viewMap: [
                ['Data', {type: ViewInfo.MODULE_DATA, viewInitFxn: 'viewInitData', structName: 'DataView'}],
            ]
        }); 
 
internal:
 
    struct Module_State {
        UInt32    buffer[10];
    }
 
}

ModB.xs

/*  
* ======== module$static$init ======== 
* Initialize module state.
*/
function module$static$init(mod, params)
{
    /* Initialize the buffer to values 0-10. */
    for (var i = 0; i < 10; i++) {
        mod.buffer[i] = i;
    }
}
 
 /*
 *  ======== viewInitData ========
 *  Instance data view.
 */
function viewInitData(view)
{
    var Program = xdc.useModule('xdc.rov.Program');
 
    /* Retrieve the module's module state structure */
    var rawView = Program.scanRawView('rovtests.ModB');
    var mod = rawView.modState;
 
    /* For each element of the buffer... */
    for (var i = 0; i < mod.buffer.length; i++) {
        /* Create a new data element to display the value. */
        var elem = Program.newViewStruct('rovtests.ModB', 'Data');
 
        elem.val = mod.buffer[i];
 
        /* Add the element to the list. */
        view.elements.$add(elem);
    }
}