metaonly module xdc.rov.StructureDecoder

Module for retrieving and decoding target structures

The StructureDecoder is responsible for decoding target data given the raw target bytes and the data's type as defined in XDC. It also contains APIs for retrieving data from the target given the data's address. [ more ... ]
Configuration settings sourced in xdc/rov/StructureDecoder.xdc
var StructureDecoder = xdc.useModule('xdc.rov.StructureDecoder');
module-wide constants & types
        obj.buffer = Any  ...
        obj.addr = Int  ...
        obj.off = Int  ...
per-instance config parameters
    var params = new StructureDecoder.Params// Instance config-params object;
per-instance creation
    var inst = StructureDecoder.create// Create an instance-object(Any mem, Any targConfig, params);
per-instance functions
    inst.decodeStructArray// Decode an array of structures(Any structType, StructureDecoder.Buffer buffer, Int len) returns Any
    inst.fetchArray// Retrieve and decode an array of structures from the target(Any structType, Int addr, Int len, Bool isScalar, Bool addrCheck) returns Any
    inst.fetchStruct// Retrieve and decode a structure from the target(Any structType, Int addr, Bool addrCheck) returns Any
 
DETAILS
The StructureDecoder is responsible for decoding target data given the raw target bytes and the data's type as defined in XDC. It also contains APIs for retrieving data from the target given the data's address.
The StructureDecoder relies on the TargetDecoder to decode the raw target bytes, but is itself responsible for decoding the structure layout. The decodeStruct API takes as an argument the structure's type representation in the XDC object model, and refers to this object to determine the size and offsets of the structure's fields.
The object returned by decodeStruct is not the typed Java representation of the structure, but rather a typeless JavaScript object which simply contains all of the same fields. This allows ROV to control the type of the fields, and specifically to represent arrays as addresses rather than as objects.
All of the 'decode' methods are essentially private methods. The intended interface to the StructureDecoder is through the 'fetch' APIs.
 
struct StructureDecoder.Buffer

Target buffer

Configuration settings
var obj = new StructureDecoder.Buffer;
 
    obj.buffer = Any  ...
    obj.addr = Int  ...
    obj.off = Int  ...
 
DETAILS
This structure encapsulates a buffer of target memory (buffer), the buffer's original target address (addr), and a running offset into that buffer (off).
Decoding a structure is a recursive process, since the structure may include fields which are also structures. As StructureDecoder decodes each field, it updates the off field to move to the next field.
The original address of the buffer is stored as well so that each structure field can be given a $addr property with its target address.
Instance Config Parameters

Configuration settings
var params = new StructureDecoder.Params;
// Instance config-params object
Static Instance Creation

Configuration settings
var params = new StructureDecoder.Params;
// Allocate instance config-params
params.config =   ...
// Assign individual configs
 
var inst = StructureDecoder.create(Any mem, Any targConfig, params);
// Create an instance-object
DETAILS
The StructureDecoder requires a MemoryImage instance and the target configuration object from the ROV recap file; i.e., recap.build.target.
 
StructureDecoder.decodeStruct()  // instance

Decode an entire structure by decoding each of the structure's fields

Configuration settings
inst.decodeStruct(Any structType, StructureDecoder.Buffer buffer, Any inStr) returns Any
 
DETAILS
structType
Structure type. Not just a string, it is the XDC object model representation of the type.
buffer
Buffer of target memory containing raw data.
inStr
Optional structure to fill in. Otherwise decodeStruct will create a new one.
 
StructureDecoder.decodeStructArray()  // instance

Decode an array of structures

Configuration settings
inst.decodeStructArray(Any structType, StructureDecoder.Buffer buffer, Int len) returns Any
 
DETAILS
This API exists to perform some optimizations when decoding an array of a single type of object.
structType
Structure type of the elements in the array. Not just a string, it is the XDC object model representation of the type.
buffer
Buffer of target memory containing raw data.
len
Number of elements in the array.
 
StructureDecoder.fetchArray()  // instance

Retrieve and decode an array of structures from the target

Configuration settings
inst.fetchArray(Any structType, Int addr, Int len, Bool isScalar, Bool addrCheck) returns Any
 
DETAILS
structType
Structure type. Not just a string, it is the XDC object model representation of the type.
addr
Target address of the structure to retrieve.
len
Number of entries in the array.
isScalar
Whether it is an array of scalars.
addrCheck
Whether to check the memory read against the section map.
 
StructureDecoder.fetchStruct()  // instance

Retrieve and decode a structure from the target

Configuration settings
inst.fetchStruct(Any structType, Int addr, Bool addrCheck) returns Any
 
DETAILS
This method retrieves and decodes a structure of the given type at the given address from the target.
structType
Structure type. Not just a string, it is the XDC object model representation of the type.
addr
Target address of the structure to retrieve.
addrCheck
Whether to check the memory read against the section map.
generated on Fri, 22 Feb 2019 01:33:20 GMT