5.6.12 Resources objects

Describes the following objects:

ParameterInfo

ParameterInfo members:

defaultData

Type: NumberU64[]

Optional. Default value of the numeric parameter. Parameters for which no specific value was specified at init-time have this value. If this is not specified, a default value of 0 is used. This is only present for numeric parameters. Signed numeric values have the (unsigned) bit pattern in the default value. numericFp resources have floating-point bit patterns in the default value.

Numeric values are encoded right-aligned into the NumberU64 elements and little-endian in the array (the same encoding when reading or writing resources). Instances must guarantee that the default value is consistent with the min and max values, but clients must not rely on this guarantee.

defaultString

Type: String

Optional. Default value of a string parameter. Parameters for which no specific value was specified at init-time have this value. If this is not specified, by default an empty string is used.

initOnly

Type: Boolean

Optional. Specifies when a parameter value can be set or written:

True
Init-time parameter
False
Run-time parameter. Default is false (run-time parameter).

Init-time parameter: The parameter can only ever be set before instantiation. The parameter is only settable through the function simulation_setInstantiationParameterValues(). It is not settable at run-time through the function resource_write(), which is only available after instantiation. The parameter behaves like a read-only resource after instantiation. After instantiation, it can be read through resource_read() like any other resource. The value of init-time parameters must be constant at run-time. Typical examples of init-time parameters are cache sizes or number of sub-units.

Run-time parameter: The parameter can be set at init-time and it can also be set at run-time. The parameter mostly behaves like a generic resource. As a guideline, the value of a run-time parameter must not change spontaneously at run-time other than through explicit resource_write() calls or equivalent explicit mechanisms, for example re-reading a config file. If it does change spontaneously at run-time, it is likely to be better modeled as a non-parameter resource.

Note:

Even if a parameter is only modifiable at run-time under very restricted circumstances, it must be a run-time parameter. Run-time parameters are not guaranteed to be modifiable at run-time, but init-time parameters are guaranteed to be constant at run-time.

Note:

All parameters, regardless of the value of initOnly:

max

Type: NumberU64[]

Optional. Maximum numeric value accepted (inclusive). Only used for numeric types.

min

Type: NumberU64[]

Optional. Minimum numeric value accepted (inclusive). Only used for numeric types.

RegisterInfo

RegisterInfo members:

addressOffset

Type: NumberU64

Optional. Address offset of a memory-mapped register, relative to the physical base address of the instance, for example a peripheral. This is informational only. A lot of factors affect the memory map of a system. Clients can safely ignore the value of addressOffset and usually just treat it as part of the register description.

canonicalRn

Type: NumberU64

Optional. Canonical register number. This number adheres to the scheme described by the register. canonicalRnScheme property returned by 'instance_getProperties()'.

If register. canonicalRnScheme is ElfDwarf then bits[15:0] specify the DWARF register number for the architecture that is specified by bits[47:32]. The architectures are as defined in the ELF header field 'e_machine'. See section "ElfDwarf scheme for canonical register numbers" for details.

lsbOffset

Type: NumberU64

Optional. LSB offset of this register in its parent register specified by parentRscId. Together with bitWidth this describes the bit range covered by this register field in its parent register. If lsbOffset is present, parentRscId must also be set. For logical child registers, on the other hand, it is valid to have just parentRscId set and lsbOffset not present. This indicates that this register is a logical child register of its parent, not covering a simple consecutive bit range. This can be used to cleanly expose child registers that are distributed across several bit ranges in the parent registers, reordering and splitting bits arbitrarily. It can also be used to expose logical parts of a parent register that do not appear in the bits of the parent register at all.

The special value '264-1' can be used synonymously to a missing value. This is for cases where not specifying lsboffset is not possible, for example arrays of the same object signature or C++.

Clients can safely ignore the value of lsbOffset and usually just treat it as part of the register description. Clients do not need to interpret lsbOffset in any way to read and/or write register values. The target instance takes care of putting the right bits into the right location.

resetData

Type: NumberU64[]

Optional. Reset value for a numeric register. This is the value to which the resource is set at hardware reset. This is informational only. It is up to the instance implementation to implement a correct reset behavior. Registers that do not have a defined reset value must not have a resetData field. The value is encoded right-aligned inside each NumberU64 and little-endian in the array, the same format that is used for resource values used by 'resource_read()' and 'resource_write()'. Clients can safely ignore the value of resetData and usually just treat it as part of the register description.

resetString

Type: String

Optional. Reset value for string resource. See resetData.

writeMask

Type: NumberU64[]

Optional. Write mask. Bits set in this mask can be written. Other bits cannot be modified. This is informational only. It is up to the instance implementation to enforce the write mask and is not guaranteed by the interface. Clients must not enforce the write mask when writing the resource. The value is encoded right-aligned inside each NumberU64 and little-endian in the array, the same format that is used for resource values used by 'resource_read()' and 'resource_write()'. Clients can safely ignore the value of writeMask and usually just treat it as part of the register description.

ResourceGroupInfo

ResourceGroupInfo members:

cname

Type: String

Name of the resource group in the context of expressions and in scripts. This is a valid C identifier that is unique within this instance and that also does not overlap with resource cname fields. Both name and cname are primary keys to identify groups. Instance implementations derive the cname from name according to the rules specified for ResourceInfo.cname if it is not explicitly specified when defining a resource. Clients must handle violations of these rules gracefully, converting cname to a C identifier according to the rules specfified in ResourceInfo.cname (which leaves all valid C identifiers untouched). In case of conflicts with other groups cnames only the first group within the array returned by 'resource_getListOfResourceGroups()' with a specific cname must be accessible. In case of a conflict with resource cnames the group cname must always take precedence.

descr

Type: String

Optional. Description of the resource group. Can contain linefeeds.

name

Type: String

Short string identifying the resource group. This is unique within this instance and must not overlap with resource name fields. Both name and cname are primary keys to identify groups.

resourceList

Type: NumberU64[]

List of resource ids of the resources that belong to this group. Must not be empty. Each resource must be in at least one group, and can be in more than one group. The array defines the order of the resources in each group that clients must use when displaying the resources of a group.

ResourceInfo

ResourceInfo members:

bitWidth

Type: NumberU64

Size of the resource in bits. Must be 0 for type="string" and type="noValue" resources. Must be > 0 for all other types of resources.

cname

Type: String

Name of the resource in the context of expressions and in scripts. This is a valid C identifier. For top-level resources this must be unique within each resource group this resource belongs to. For child resources this must be unique within the parent resource. Instance implementations derive the cname from name according to the following rules if no explicit cname is specified when defining a resource:

  • All non-C identifier chars are replaced with underscores.
  • If the first char is a digit, an underscore is prepended.

Clients must handle violations of these rules gracefully, by converting cname to a C identifier according to the rules specified above (which leaves all valid C identifiers untouched). In case of conflicts with other resource cnames only the first resource within the array returned by 'resource_getList()' with a specific cname must be accessible.

Child registers do not contain the cnames of their parents in their cname. Clients that need a hierarchical C identifier for a child register must prepend the cnames of all parent registers, separated with an underscore (for instance 'FLAGS_X'), to create a hierarchical cname. See also name.

descr

Type: String

Optional. Description of the semantics of the resource. Might contain linefeeds.

enums

Type: EnumElementInfo[]

Optional. Array of EnumElementInfo objects which describe symbols for numeric resource values. Debuggers can display these symbols (and potentially their description) in addition to the numeric value.

format

Type: String

Optional. Iris-text-format. This allows a client to format the value of this resource and the values of other resources in this instance (regardless of hierarchy) in a specific way. The value of this resource is referred to by the value variable in the Iris-text-format string. The values of other resources in this instance are referred to by their cname, optionally prefixed by their group cname and a dot (resource name without group name has priority).

Clients must allow the user to select whether the format must be used (if present at all) or whether the plain numeric value must be displayed. Clients must prefer the format if present. Resources that only pull together information from other resources and do not have any value on their own can set type="noValue" to make this clear. This can for example be used to format bitfields in a descriptive way. Cache line tag: "Addr=%{value[31:12]}000 %{value[11]:(clean|dirty)}". Conditional formatting is also possible.

name

Type: String

Display name of the resource. For registers, this must be the architectural register name if available. For top-level resources this must be unique within each resource group this resource belongs to. For child resources this must be unique within the parent resource. Clients must handle non-unique register names gracefully. They must always use the first resource in the array returned by resource_getList() in case of a conflict.

The resource group name is not part of this resource name.

Child resources (which have a parentRscId field) specify only their own name in the name and cname fields, not including the names of their parents. Clients that need a hierarchical name for a child register must prepend the names of all parent registers, separated with a dot, to get a hierarchical name (for instance 'FLAGS.X').

See also cname which is used in expressions and scripts.

parameterInfo

Type: ParameterInfo

Optional. Iff this is present, this resource represents a parameter. Parameters generally behave like normal resources and have some additional semantics attached to them, like being settable at init-time. This ParameterInfo object contains parameter specific meta information. It also acts as the isParameter switch.

parentRscId

Type: NumberU64

Optional. If this is present, this is a child resource (for instance a field in a register) and this field contains the resource id of its parent resource. The name and cname fields of child resources only contain the names of the child resources, not of the parent resources.

Child resources might, in turn, have child resources. The nesting depth is not limited, but instances are encouraged to expose only shallow hierarchies (usually only one level). Instances must not expose loops in the parent graph. Clients must handle the situation where an instance exposes a loop in the parent graph gracefully, for instance by ignoring any parent pointer that points to a child. Clients must display child resources in the order they appear in the array returned by resource_getList() underneath a parent.

If parentRscId is missing this means that this is a top-level resource (which might or might not have children). All children of a specific parent resource must be in the same group as the parent resource.

registerInfo

Type: RegisterInfo

Optional. Iff this is present, this resource represents a register. Registers typically correspond to architectural or device registers in the component and have some additional metadata found in the registerInfo object.

rscId

Type: NumberU64

Opaque resource id uniquely identifying the resource within the target instance. Used to read/write the resource. This is the primary key to identify a resource. The value 264-1 is defined to be an invalid rscId.

rwMode

Type: String

Optional. Either "r", "w", or "rw" for read-only, write-only, or read-write (default). This is a hint for the debugger or user about which accesses on this resource are supported architecturally. However, it is always allowed to issue resource_read() and resource_write() calls on all resources, regardless of their rwMode. This must not cause an error in the resource_read() or resource_write() return value. This might or might not cause errors in the 'ResourceReadResult.error' array (E_error_reading_write_only_resource, E_error_writing_read_only_resource, E_error_reading_resource, E_error_writing_resource).

Ultimately, the instance implementation decides what happens for a read or a write. Writes to read-only resources can be silently ignored or can return E_error_writing_read_only_resource and reads of write-only resources must return a useful value, for example the value of an internal latch, or can return E_error_reading_write_only_resource.

subRscId

Type: NumberU64

Optional. Additional resource id according to an instance-specific scheme defined by the instance. This is not required to be unique within an instance, nor is it required to be present for every resource of an instance. This is usually just used internally in an instance to identify registers in register access functions and is rarely useful for clients.

Note:

For register resources, address offsets and canonical register numbers, which both are also suitable to identify registers, must go into the RegisterInfo addressOffset or canonicalRn fields, respectively. subRscId uses a scheme that is private to an instance.
tags

Type: ResourceTags

Optional. Object containing extra meta information about a resource, for example whether a register is the PC or stack pointer, see the ResourceTags object. If this is missing, this has the same semantics as specifying an empty ResourceTags object. This means the resource is not tagged with anything, which is usually the case for most resources of an instance.

type

Type: String

Optional. Either "numeric", "numericSigned", "numericFp", "string" or "noValue". Default is "numeric".

"numeric": The resource contains a bit-pattern of "bitWidth" bits. Clients must display this as hex by default and allow users to explicitly switch to other formats, for example decimal or floating point. This is the usual type for most resources. All other resource types are exotic.

"numericSigned": Exotic: Same as "numeric" but in addition this gives a hint to the client that this resource always contains a signed integer. This is usually used for parameters that represent a signed integer value.

"numericFp": Exotic: Same as "numeric" but in addition this gives a hint to the client that this resource always contains an IEEE 754 floating-point value. This is usually only useful for pure floating-point resources. Clients must display this as a floating-point number by default and allow users to switch explicitly to hex and other formats. This must only be used for bitWidth 32 (float) and bitWidth 64 (double). Clients must treat other bitWidths as "numeric".

"string": Exotic: The resource contains an ASCII string. Targets can use this type as a fallback to display arbitrary information in the debugger, or as parameters that have a string value, like filenames. bitwidth must be 0 for string resources. This must not be used to expose arbitrary length binary data. To expose arbitrary length binary data consider using a memory space or a table if the data is structured.

"noValue": Exotic: No numeric or string value is associated with this resource. If this resource has a format then clients must display this format, usually by pulling together numeric information from other resources. bitwidth must be 0. Reading a noValue resource always delivers zero NumberU64 units in ResourceReadResult.data and ResourceReadResult.undefinedBits. Writing a noValue resource is always silently ignored. Clients might or might not allow editing of noValue resources that have a format string. Resource breakpoints can be supported for noValue resources.

ResourceReadResult

ResourceReadResult members:

data

Type: NumberU64[]

List of numeric resource values read, in the order they were specified in the rscIds argument of the resource_read() function. The encoding of the value depends on the type:

numeric, 0<bitWidth<=64
NumberU64, value right-aligned in the lowest bits, zero-extended to 64 bits.
numeric, bitWidth>64
Sequence of N*NumberU64 in little-endian, last element right-aligned in the lowest bits, zero-extended to N*64 bits, N = floor((bitWidth+63)/64).
numericSigned
Same as numeric except that the value is sign-extended instead of zero-extended.
numericFp
Same as numeric.
string
Not present in this array. Occupies zero elements in this array.
noValue
Not present in this array. Occupies zero elements in this array. All numeric resources read have a value in this array (potentially a dummy value), regardless of whether the read operation failed or succeeded (regardless of whether there is an entry for a resource in the error array). The layout of the data array can be interpreted in the same way, just based on the layout of the rscIds array in the resource_read(), regardless of the contents of errors.

The length of this array depends on the number and width of all numeric resources read.

error

Type: NumberU64[]

Optional. List of resource ids and E_* error codes for existing resources that could not be read. Each entry in the list occupies two array elements: rscId and errorCode. This only returns errors that happen because the callee is unable to provide the resource value of an existing resource, for example architectural errors. This does not return errors caused by the caller doing something wrong, for example E_unknown_resource_id. These errors are returned by resource_read() instead. The errors that are most likely to occur in this list are:

E_approximation
The resource value could be read but is only an approximation in some sense, for example because the instance is not in a debuggable-state.
E_value_not_available
The resource value is currently not available and cannot even be approximated, for example because the instance is not in a debuggable-state.
"E_error_reading_write_only_resource", "E_error_reading_resource" (catch all)
These errors must be shown as information to the user (similar to undefined bits), not as a user or implementation error.

Note:

The error codes E_unknown_instance_id and E_unknown_resource_id are never returned in this array, but are instead returned by the resource_read() function. This array is either missing, in case of no such error, or non-empty, in case of errors.
strings

Type: String[]

Optional. List of string resource values read, in the order they were specified in the rscIds argument of the resource_read() function. If no string resources were read, this array is missing. All string resources have a string value in this array, regardless of whether the read operation failed or not. See "data".

undefinedBits

Type: NumberU64[]

Optional. List of resource masks that indicate undefined bits. This array has the same layout and length as data, even if only a subset of the read resources support undefined bits. A 1-bit means that the value is undefined, in which case the corresponding bit in data is 0 and must be ignored by clients. Undefined bits are only reported by instances that support it and only for resources that support it. A missing array is equivalent to an array containing all zeros (all bits defined).

ResourceTags

ResourceTags members:

isPc

Type: Boolean

Optional. If present and True, this is the register that represents the address that is executed next of a CPU or code-executing component. At most one register must have this set to True. Debuggers use this to find out which instruction or line is to be executed next. The isPc and the isPcSpaceId resources together describe the next execution location.

isSp

Type: Boolean

Optional. If present and True, this is the stack pointer of a CPU. At most one register must have this set to True.

isLr

Type: Boolean

Optional. If present and True, this is the link register of a CPU. At most one register must have this set to True.

isFramePointer

Type: Boolean

Optional. If present and True, this is the frame pointer register of a CPU. At most one register must have this set to True.

isPcSpaceId

Type: Boolean

Optional. If present and True, this resource contains the memory space id for the PC and for the link register. At most one resource must have this set to True. The isPc and the isPcSpaceId resources together describe the next execution location.

isSpSpaceId

Type: Boolean

Optional. If present and True, this resource contains the memory space id for the stack pointer and frame pointer. At most one resource must have this set to True.

isInstructionCounter

Type: Boolean

Optional. If present and True, this resource is the instruction counter. The instruction counter counts executed instructions linearly from 0. This is not the PC.

isArchitectural

Type: Boolean

Optional. If present and True, this resource is an architectural register. An architectural register is a register that is mentioned in the architecture reference manual for an instance. Architectural registers must use their architectural name.

Examples of architectural registers are the general purpose registers, the PC, and the flags register of a core. Examples of non-architectural register resources are artificial resources of simulation components that enable or disable certain features, count simulation events, or allow access to internal state, and registers that represent architectural information in a (potentially more convenient) non-architectural format. There is however no hard line between architectural and non-architectural registers, for example for internal shadow registers present in hardware and mentioned in the technical reference manual if an architecture reference manual is missing.

This flag is informational and clients can use it to extract the subset of architectural registers of an instance. It must be treated like a part of the description of a resource.

ResourceWriteResult

ResourceWriteResult members:

error

Type: NumberU64[]

Optional. List of resource ids and E_* error codes for existing resources that could not be written. This only returns errors that happen because the callee is unable to write the resource value of an existing resource, for example architectural errors. This does not return errors caused by the caller doing something wrong, for example E_unknown_resource_id. These errors are returned by resource_write() instead. Each entry in the list occupies two array elements: rscId and errorCode. The errors that are most likely to occur in this list are E_error_writing_read_only_resource, E_writing_init_time_parameter (when trying to write an init-time parameter), and E_error_writing_resource (catch-all error if reading failed). These errors must be shown as information to the user (similar to undefined bits), not as a user or implementation error.

Note:

The error codes E_unknown_instance_id and E_unknown_resource_id are never returned in this array, but are instead returned by the resource_write() function. This array is either missing, in case of no such error, or non-empty, in case of errors.
Non-ConfidentialPDF file icon PDF version101196_0100_03_en
Copyright © 2018, 2019 Arm Limited or its affiliates. All rights reserved.