5.21.5 Simulation instantiation and discovery functions

Describes the following functions:

simulation_getInstantiationParameterInfo()

Gets the meta information of all instantiation parameters of a not-yet-instantiated simulation.

Calling this function is optional. If a pre-instantiation client already knows which parameters exist, it can instantiate the simulation without first getting the meta information using this function, for example when reading parameter values from a config file. This function has no side effects.

Arguments

instId

Type: NumberU64

Opaque number uniquely identifying the target instance. Typically this is the instance framework.SimulationEngine.

prefix

Type: String

Optional. Only return parameters whose hierarchical 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". If this is missing or empty, all parameters are returned. If no matching parameter is found, an empty list is returned rather than an error.

Return value

ResourceInfo[]

List of meta information for instantiation parameters as an array of ResourceInfo objects. The semantics of these ResourceInfo entries differ slightly from instance-specific ResourceInfo entries:

  • The list of instantiation parameters is global and an association with a specific future instance is only implied by its hierarchical name.
  • ResourceInfo.rscId is missing. (Instantiation parameters are identified by their hierarchical name.).
  • ResourceInfo.name contains the hierarchical name of the instantiation parameter, with the format <instance_path>.<parameter_name>.
  • ResourceInfo.cname is missing. Instantiation parameters do not have valid C identifiers and are always identified by their name string.

simulation_instantiate()

Pre-instantiation clients use this function to instantiate the simulation. It implicitly uses the parameter state that was set up by simulation_setInstantiationParameterValues().

Arguments

instId

Type: NumberU64

Opaque number uniquely identifying the target instance. Typically this is the instance framework.SimulationEngine.

Return value

InstantiationResult

List of errors and warnings that occurred during instantiation. This includes invalid parameter values and license checking errors. See InstantiationResult.

simulation_requestShutdown()

Requests that the simulation destroys itself cleanly. The shutdown might be delayed and is likely to happen after this function returns. Receiving a response to this function call does not mark any special event and does not mean the simulation has been shut down.

Arguments

instId

Type: NumberU64

Opaque number uniquely identifying the target instance. Typically this is the instance framework.SimulationEngine.

Return value

Function has no return value.

simulation_reset()

Resets the simulation to exactly the same state it had after instantiation, see simulation_instantiate().

Some simulations might require simulation time to be stopped before they can be reset. These simulations respond with the error code E_simulation_running if simulation_reset() is called while simulation time is progressing. For simulations that can be reset while simulation time is progressing, the simulation is stopped automatically before resetting the system. Simulation time is not resumed after the reset is done. After simulation_reset() completes, the simulation is always stopped.

Arguments

instId

Type: NumberU64

Opaque number uniquely identifying the target instance. Typically this is the instance framework.SimulationEngine.

allowPartialReset

Type: Boolean

Default: False

Optional. If present and true, perform a partial simulation reset for simulations that do not support a full reset. This might be because some components in a simulation do not support reset functionality. By setting allowPartialReset to true, a client acknowledges that it accepts the consequences of not resetting the whole simulation.

Return value

Function has no return value.

Errors

  • E_full_reset_not_supported.
  • E_simulation_running.

simulation_setInstantiationParameterValues()

Sets the instantiation parameter values. These values are used to initialize all init-time and run-time parameters of all instances during the instantiation of the simulation. This function modifies a state that exists before the simulation is instantiated. It does not instantiate the simulation.

Arguments

instId

Type: NumberU64

Opaque number uniquely identifying the target instance. Typically this is the instance framework.SimulationEngine.

data

Type: InstantiationParameterValue[]

List of instantiation parameter values.

Return value

Function has no return value.

Errors

  • E_unknown_parameter_name.
  • E_type_mismatch.

simulation_waitForInstantiation()

This function can be used by clients that connect to a simulation to make sure that the simulation has been instantiated and all components have been initialized.

It can be called at any time during the simulation. If called before the simulation has been instantiated the response will only be sent after the simulation has been instantiated. If called after instantiation it will return immediately.

Arguments

instId

Type: NumberU64

Opaque number uniquely identifying the target instance. Typically this is the instance framework.SimulationEngine.

Return value

Function has no return value.

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