metaonly module xdc.rov.Program

Root object for the ROV model

This module is the main access point for all ROV operations. The Program APIs are used to retrieve the views for the requested modules.
Configuration settings sourced in xdc/rov/Program.xdc
var Program = xdc.useModule('xdc.rov.Program');
module-wide constants & types
        obj.type = String  ...
        obj.isScalar = Bool  ...
 
        obj.label = String  ...
        obj.elements = Any[]  ...
 
        obj.elements = Any[]  ...
 
    var obj = new Program.RawView// Raw module view;
        obj.modState = Any  ...
        obj.instStates = Any[]  ...
        obj.modCfg = Any  ...
 
        obj.mod = String  ...
        obj.tab = String  ...
        obj.inst = String  ...
        obj.field = String  ...
        obj.message = String  ...
 
        obj.label = String  ...
        obj.children = Program.TreeNode[]  ...
        obj.properties = Any[]  ...
module-wide functions
    Program.displayError// (Any view, String fieldName, String errorMsg) returns Void
    Program.fetchArray// Retrieve the specified array from the target(Program.FetchDesc desc, Ptr addr, Int len, Bool addrCheck) returns Any
    Program.fetchString// Retrieve a string from the target(Ptr addr, Bool addrCheck) returns String
    Program.scanHandleView// Scan single instance of a module(String modName, Ptr instAddr, String tabName) returns Any
    Program.scanInstanceView// Retrieve the instance-type views for a module(String modName, String tabName) returns Any
    Program.scanModuleView// Retrieve module-type view for a module(String modName, String tabName) returns Any
    Program.scanObjectView// Scan view for an embedded object(String modName, Any obj, String tabName) returns Any
    Program.scanTreeTableView// (String modName, String tabName) returns Program.TreeNode[]
    Program.scanTreeView// (String modName, String tabName) returns Any
 
 
struct Program.FetchDesc

Description of data to fetch

Configuration settings
var obj = new Program.FetchDesc;
 
    obj.type = String  ...
    obj.isScalar = Bool  ...
 
FIELDS
type — the fully qualified name of a specified type; i.e., a type declared in some .xdc file. For example, "xdc.runtime.Types.Timestamp64".
isScalar — if fetching an array, are the elements of the array really just one of the "scalar structs" defined by xdc.rov.support.ScalarStructs.
DETAILS
A FetchDesc object is required as the first argument of the fetchStruct and fetchArray methods. The FetchDesc tells ROV the type of the data to be fetched so it knows how much data to read and how to decode it.
Every reference-type field in a state structure has a FetchDesc generated for it, with the name <field name>$fetchDesc.
For example, the instance structure
      struct Instance_State {
          Char stack[];
      ];
will have defined obj.stack$fetchDesc, which can be used to fetch the array:
      var data = Program.fetchArray(obj.stack$fetchDesc, obj.stack, len);
SEE
 
struct Program.InstDataView

Instance view data returned from a scan

Configuration settings
var obj = new Program.InstDataView;
 
    obj.label = String  ...
    obj.elements = Any[]  ...
 
SEE
 
struct Program.ModDataView

Module view data returned from a scan

Configuration settings
var obj = new Program.ModDataView;
 
    obj.elements = Any[]  ...
 
SEE
 
struct Program.RawView

Raw module view

Configuration settings
var obj = new Program.RawView;
 
    obj.modState = Any  ...
    obj.instStates = Any[]  ...
    obj.modCfg = Any  ...
 
DETAILS
This is the structure returned by the scanRawView method. It contains the module's state, the instance states, and the module configuration fields and values.
 
struct Program.StatusEntry

Single entry in the ROV status table

Configuration settings
var obj = new Program.StatusEntry;
 
    obj.mod = String  ...
    obj.tab = String  ...
    obj.inst = String  ...
    obj.field = String  ...
    obj.message = String  ...
 
DETAILS
ROV maintains a table of all errors, warnings, etc. encountered while processing views. This table is cleared on each call to clear cache (e.g., at each breakpoint).
 
struct Program.TreeNode

Node for a generic "tree table" view

Configuration settings
var obj = new Program.TreeNode;
 
    obj.label = String  ...
    obj.children = Program.TreeNode[]  ...
    obj.properties = Any[]  ...
 
SEE
 
Program.debugPrint()  // module-wide

Print API which will only print the message if debug printing is enabled

Configuration settings
Program.debugPrint(String msg) returns Void
 
 
Program.displayError()  // module-wide
Configuration settings
Program.displayError(Any view, String fieldName, String errorMsg) returns Void
 
 
Program.exToString()  // module-wide

Helper function for formatting exceptions into strings with filename and line number

Configuration settings
Program.exToString(Any e) returns String
 
 
Program.fetchArray()  // module-wide

Retrieve the specified array from the target

Configuration settings
Program.fetchArray(Program.FetchDesc desc, Ptr addr, Int len, Bool addrCheck) returns Any
 
ARGUMENTS
desc — Fetch descriptor for the array, indicating the type of data in the array.
addr — Address of the array to fetch.
len — The number of arrray elements to fetch.
addrCheck — Optional, defaults to true. Indicates whether the memory image should validate the read by comparing the address to section information.
RETURNS
Returns a JavaScript array with the data in it.
THROWS
Throws an exception in the event that addr is not in the program's memory map, some error occurs that prevents memory from being read, or if len = 0.
 
Program.fetchStaticString()  // module-wide

Retrieves a static string from the executable

Configuration settings
Program.fetchStaticString(Ptr addr) returns String
 
ARGUMENTS
addr — Address of the string
DETAILS
This API makes use of an object file reader to improve the string reading performance--it reads the string from the file rather than performing a target memory read. For this reason, it should only be used on static strings and not dynamic ones.
RETURNS
Requested string or null if it can't be found.
 
Program.fetchString()  // module-wide

Retrieve a string from the target

Configuration settings
Program.fetchString(Ptr addr, Bool addrCheck) returns String
 
ARGUMENTS
addr — Address of the string.
addrCheck — Optional, defaults to true. Indicates whether the memory image should validate the read by comparing the address to section information.
RETURNS
Requested string.
THROWS
Throws an exception in the event that addr is not in the program's memory map or some error occurs that prevents memory from being read.
 
Program.fetchStruct()  // module-wide

Retrieve the specified structure from the target

Configuration settings
Program.fetchStruct(Program.FetchDesc desc, Ptr addr, Bool addrCheck) returns Any
 
ARGUMENTS
desc — Fetch descriptor for the structure, indicating the type of the structure.
addr — Address of the structure to fetch.
addrCheck — Optional, defaults to true. Indicates whether the memory image should validate the read by comparing the address to section information.
RETURNS
Returns the requested structure as a javascript object.
THROWS
Throws an exception in the event that addr is not in the program's memory map or some error occurs that prevents memory from being read.
 
Program.getModuleConfig()  // module-wide

Get a module's configuration state

Configuration settings
Program.getModuleConfig(String modName) returns Any
 
ARGUMENTS
modName — Full module name to get the configs for.
DETAILS
Returns an object with all of the module configuration values used in configuring the application.
This object includes the common$ config params.
RETURNS
Object containing all of the module configs and their values.
 
Program.getPrivateData()  // module-wide

Retrieves module's private ROV data

Configuration settings
Program.getPrivateData(String modName) returns Any
 
DETAILS
This API returns an object which can be used to store private data across different ROV API calls. The object is reset at every breakpoint.
This object is also passed as the context to all view init functions, so it can also be accessed using 'this'. However, the context changes when you call other APIs in your module; that is when you will need this API. It can also be used to support metaonly APIs which are called by other modules.
 
Program.getShortName()  // module-wide

Convert canonical instance names to a short name

Configuration settings
Program.getShortName(String name) returns String
 
ARGUMENTS
name — Full canonical instance name.
DETAILS
Parses the full canonical instance name for the shorter name given by the user. If there is no shorter name, then it returns an empty string "".
RETURNS
The short name, if the user specified one. Empty string otherwise.
 
Program.getStatusTable()  // module-wide

Returns the current table of all encountered status messages

Configuration settings
Program.getStatusTable() returns Any
 
DETAILS
This table is reset with every call to 'resetMods'. (e.g., at every breakpoint).
 
Program.getSymbolValue()  // module-wide

Returns the value for the given symbol

Configuration settings
Program.getSymbolValue(String symName) returns Int
 
ARGUMENTS
symName — Name of symbol
DETAILS
Returns -1 if the symbol does not exist.
RETURNS
Address or value of symbol, or -1 if symbol does not exist
 
Program.lookupDataSymbol()  // module-wide

Lookup symbolic names for an address

Configuration settings
Program.lookupDataSymbol(Int addr) returns Any
 
ARGUMENTS
addr — Address of symbols
DETAILS
Uses the ISymbolTable to look up the symbols at the given address.
This API is separate from lookupFuncName to address paging concerns. Use lookupFuncName to get function names (or any symbols in PROGRAM memory) and use lookupDataSymbol to get data symbols (for symbols in DATA memory).
RETURNS
Array of symbols at the requested address.
 
Program.lookupFuncName()  // module-wide

Lookup function names for an address

Configuration settings
Program.lookupFuncName(Int addr) returns Any
 
ARGUMENTS
addr — Address of symbols
DETAILS
Uses the ISymbolTable to look up the symbols at the given address.
This API is separate from lookupDataSymbol to address paging concerns. Use lookupFuncName to get function names (or any symbols in PROGRAM memory) and use lookupDataSymbol to get data symbols (for symbols in DATA memory).
RETURNS
Array of symbols at the requested address.
 
Program.newViewStruct()  // module-wide

Creates a new instance of the view structure for the specified view

Configuration settings
Program.newViewStruct(String modName, String tabName) returns Any
 
DETAILS
This API is called for views where the view structure is not already passed in as an argument to the view init function.
It is necessary to instantiate a view structure in this way so that ROV is given an opportunity to initialize the status-reporting mechanisms of the view structure (to support, e.g., Program.displayError).
 
Program.ptrToHex()  // module-wide

Convert pointer representation to hex string

Configuration settings
Program.ptrToHex(Any ptr) returns String
 
DETAILS
Convenience function for converting the 'at' symbol representation of a pointer to the form 0x80005846.
 
Program.scanHandleView()  // module-wide

Scan single instance of a module

Configuration settings
Program.scanHandleView(String modName, Ptr instAddr, String tabName) returns Any
 
ARGUMENTS
modName — Full module name to return the raw view for.
instAddr — Address of instance to scan.
tabName — Name of the tab to retrieve the view for.
DETAILS
Used from a view$init function to scan a single instance of a different module given that instance's address.
RETURNS
An Instance_View object for the requested view.
THROWS
Throws an exception in the event that a memory read of the specified instance view fails, the specified tabName isn't recognized, the specified modName doesn't support instances, or the module modName is not configured into the current program.
 
Program.scanInstanceDataView()  // module-wide

Retrieve a module's specified INSTANCE_DATA type view

Configuration settings
Program.scanInstanceDataView(String modName, String tabName) returns Program.InstDataView[]
 
THROWS
Throws an exception in the event that a memory read of the module's Raw view or any instance fails, the specified tabName isn't recognized, the specified modName doesn't support instances, or the module modName is not configured into the current program.
 
Program.scanInstanceView()  // module-wide

Retrieve the instance-type views for a module

Configuration settings
Program.scanInstanceView(String modName, String tabName) returns Any
 
ARGUMENTS
modName — Full module name to return the views for.
tabName — Name of the tab to retrieve the views for.
DETAILS
Returns an array of Instance_View structures, each structure representing an instance of the module.
RETURNS
Array of Instance_View structures, one for each isntance.
THROWS
Throws an exception in the event that a memory read of the specified instance view fails, the specified tabName isn't recognized, the specified modName doesn't support instances, or the module modName is not configured into the current program.
 
Program.scanModuleDataView()  // module-wide

Retrieve a module's specified MODULE_DATA type view

Configuration settings
Program.scanModuleDataView(String modName, String tabName) returns Program.ModDataView
 
THROWS
Throws an exception in the event that a memory read of the specified module view fails, the specified tabName isn't recognized, or the module modName is not configured into the current program.
 
Program.scanModuleView()  // module-wide

Retrieve module-type view for a module

Configuration settings
Program.scanModuleView(String modName, String tabName) returns Any
 
ARGUMENTS
modName — Full module name to return the view for.
tabName — Name of the tab to retreive the view for.
@(Returns) Module_View structure.
THROWS
Throws an exception in the event that a memory read of the specified module view fails, the specified tabName isn't recognized, or the module modName is not configured into the current program.
 
Program.scanObjectView()  // module-wide

Scan view for an embedded object

Configuration settings
Program.scanObjectView(String modName, Any obj, String tabName) returns Any
 
ARGUMENTS
modName — Full module name to return the view for.
obj — Actual object to retrieve the view for.
tabName — Name of the tab to retrieve the view for.
DETAILS
Called from a view$init function to retrieve the specified view for an embedded object.
Since XDC has no way of knowing what embedded objects are present in a system, embedded objects do not appear in the list of a module's instances until they have been scanned in this way.
Calling Program.scanObjectView will not read any additional data from the target, since the state structure was already read as part of reading it's parent structure.
RETURNS
An Instance_View object for the requested view.
THROWS
Throws an exception in the event that the specified tabName isn't recognized, the specified modName doesn't support instances, or the module modName is not configured into the current program.
 
Program.scanRawView()  // module-wide

Retrieve the raw view for a module

Configuration settings
Program.scanRawView(String modName) returns Program.RawView
 
ARGUMENTS
modName — Full module name to return the raw view for.
@(Returns) A RawView structure which contains the raw data.
THROWS
Throws an exception in the event that a memory read of the specified instance view fails, the specified tabName isn't recognized, the specified modName doesn't support instances, or the module modName is not configured into the current program.
Throws an exception in the event that a memory read of the module's Raw view fails, or the module modName is not configured into the current program.
 
Program.scanTreeTableView()  // module-wide
Configuration settings
Program.scanTreeTableView(String modName, String tabName) returns Program.TreeNode[]
 
 
Program.scanTreeView()  // module-wide
Configuration settings
Program.scanTreeView(String modName, String tabName) returns Any
 
 
Program.setTimestampFunc()  // module-wide

Sets API to be used for printing timestamp

Configuration settings
Program.setTimestampFunc(Any func) returns Void
 
 
Program.timestamp()  // module-wide

API for printing timestamp messages for performance analysis

Configuration settings
Program.timestamp(String msg) returns Void
 
generated on Wed, 09 Aug 2017 16:38:11 GMT