5.20.9 Instance registry, instance discovery, and interface discovery functions

Describes the following functions:

instanceRegistry_getInstanceInfoByInstId()

Gets the instance name for an instance id.

Arguments

aInstId

Type: NumberU64

Instance id of the instance to look up. This argument is intentionally not called instId because this function is not targeted at the instance identified by this argument, but is targeted at the instance registry.

Return value

InstanceInfo

InstanceInfo object containing the name and instId of an instance.

Errors

  • E_unknown_instance_id.

instanceRegistry_getInstanceInfoByName()

Gets the instance Id for a named instance.

Arguments

instName

Type: String

Instance name of the instance to look up.

Return value

InstanceInfo

InstanceInfo object containing the name and instId of an instance.

Errors

  • E_unknown_instance_name.

instanceRegistry_getList()

Gets a list of all instances, optionally filtered by a specific prefix.

Arguments

prefix

Type: String

Optional. Only return instances whose hierarchical instance name starts exactly with prefix or is exactly prefix. Only complete parts of the hierarchical names are matched, that is, prefix="component.root.ram" does not match "component.root.ramdevice", but does match "component.root.ram.bank0" and also matches "component.root.ram".

The primary use case of prefix is to conveniently query only a specific class of instances, for example all components of a simulation using prefix="component".

If this is missing or empty, all instances are returned. If no matching instance is found, an empty list is returned, rather than an error.

Return value

InstanceInfo[]

InstanceInfo Objects describing the instances matching prefix.

instanceRegistry_registerInstance()

Registers a new instance in the global instance registry and assigns an instance id (instId) to it.

Arguments

instName

Type: String

Hierarchical instance name. Hierarchy levels are separated by dots ('.'). The first hierarchy level defines the class this instance belongs to, namely component, client, or framework. Instance names must not start or end with a dot and must not contain two adjacent dots. The instance name elements that are separated by dots must be C identifiers. For invalid instance names, E_invalid_instName is returned.

channelId

Type: NumberU64

Optional. For in-process instances, this is mandatory. It indicates the IrisInterface communication of the caller of this function. For out-of-process instances, for example ones that are connected using TCP, this is ignored and must be omitted.

uniquify

Type: Boolean

Default: False

Optional. Iff True, uniquify name if instName already exists, by appending a suffix to instName such that instance + suffix is a unique instance name. This must only be used by client instances, for example debuggers and plug-ins, not by component instances, which must choose a unique name based on the system hierarchy. Instances must use a meaningful stem as instName, for example the name of a debugger or a plug-in instance name.

Return value

InstanceInfo

Object containing the instId and the instName of the registered instance. The opaque instance id uniquely and globally identifies the instance in the simulation until it is unregistered using instanceRegistry_unregisterInstance(). See InstanceInfo.

Errors

  • E_invalid_instName.
  • E_instance_already_registered.

instanceRegistry_unregisterInstance()

Unregisters an instance from the instance registry.

Arguments

aInstId

Type: NumberU64

Opaque number uniquely identifying the instance to be unregistered. This argument is intentionally not called instId because this function is not targeted at the instance identified by this argument, but is targeted at the instance registry.

Return value

Function has no return value.

Errors

  • E_unknown_instance_id.

instance_checkFunctionSupport()

Checks whether a specific instance supports a specific set of functions and, optionally, function arguments. If a Boolean result is not sufficient, use instance_getFunctionInfo() to retrieve a list of all supported functions and their arguments. This function does not return errors for unknown functions or arguments listed in functions.

Arguments

functions

Type: FunctionSupportRequest[]

List of function names with optional argument list per function.

instId

Type: NumberU64

Opaque number uniquely identifying the instance.

Return value

Boolean

True: Instance supports all functions and all their arguments that are specified in functions. The instance might support functions not specified in functions and might also support more arguments than are specified in functions. False: Instance either does not support at least one of the specified functions or it does not support at least one of the specified function arguments.

Errors

  • E_unknown_instance_id.

instance_getCppInterfaceIrisInstance()

Get a host pointer to the C++ interface of the target instance.

This function is only supported by instances that use the C++ IrisSupportLib class iris::IrisInstance. If this function is present it always returns a non-null pointer.

The caller of this function must make sure that the caller and callee use the same C++ interface class layout and run in the same process. This effectively means that they both must be compiled using the same compiler and using the same header files. The returned pointer is only meaningful if the caller and callee run in the same process.

The meta-information provided alongside the returned pointer in CppInterfacePointer can (and must) be used to do minimal compatibility checking between caller and callee.

Note:

  • Instances do not have to be implemented using iris::IrisInstance, thus not all instances will support this function.
  • This function must only be used by instances that are tightly coupled because the use of this function creates a binary dependency between the instances.
  • Using this function is very exotic and must be avoided if possible. Normal Iris function calls must always be preferred over direct C++ communication between instances.

Arguments

instId

Type: NumberU64

Opaque number uniquely identifying the target instance.

Return value

CppInterfacePointer

Pointer to the C++ iris::IrisInstance instance (and associated meta-information) that implements the Iris interface of this instance. See CppInterfacePointer.

Errors

  • E_unknown_instance_id.

instance_getFunctionInfo()

Returns a list of all functions supported by a specific instance and their meta information, for example the description, the mandatory and optional arguments, and the type of the return value.

Arguments

instId

Type: NumberU64

Opaque number uniquely identifying the instance to query. Specifying the value 0 queries the list of functions supported by the global instance, for example instanceRegistry_registerInstance().

prefix

Type: String

Optional. Get FunctionInfo only for functions whose name starts with prefix. If this argument is missing or empty, all supported functions are returned.

Return value

Map[String]FunctionInfo

Object that maps function names onto FunctionInfo Objects. The map might be empty, for example if prefix does not match any function.

Errors

  • E_unknown_instance_id.

instance_getProperties()

Gets detailed information about an instance. This information is inherent to the instance and does not change, for example the type of a component or whether certain features are supported or not.

Arguments

instId

Type: NumberU64

Opaque number uniquely identifying the instance.

Return value

Map[String]Value

Object containing all properties and their values. Numeric values can be stored as a number or as a String in this object.

Errors

  • E_unknown_instance_id.

instance_ping()

This function has no effect on the instance. It is intended to be a no-op.

Arguments

instId

Type: NumberU64

Opaque number uniquely identifying the target instance.

payload

Type: Value

Optional. If present, this value is returned. If not present, Null is returned.

Return value

Value

If payload is present, it is returned, else Null is returned.

Errors

  • E_unknown_instance_id.
Non-ConfidentialPDF file icon PDF version101196_0100_03_en
Copyright © 2018, 2019 Arm Limited or its affiliates. All rights reserved.