5.7.12 Memory functions

Describes the following functions:

memory_getMemorySpaces()

Gets a list of all memory spaces and their static information.

Arguments

instId

Type: NumberU64

Opaque number uniquely identifying the target instance.

Return value

MemorySpaceInfo[]

List of MemorySpaceInfo Objects. Can be empty. If so, no memory can be read or written on this instance.

Errors

  • E_unknown_instance_id.

memory_getSidebandInfo()

Gets sideband information for a specific memory address of a specific memory space.

Arguments

address

Type: NumberU64

Addresses to get sideband information for.

attrib

Type: Map[String]Value

Optional. Transaction attributes for the memory access. See memory_read() for details. The attributes might or might not be relevant to the returned sideband information.

instId

Type: NumberU64

Opaque number uniquely identifying the target instance.

request

Type: String[]

Optional. If present, this specifies which sideband information fields must be filled in the return value. It can contain any subset of the field names. This can be used to suppress filling in members that are expensive to produce. The instance is free to fill in more members than were requested. Unknown members are silently ignored and are not present in the result. If this is missing, all supported sideband information must be returned.

spaceId

Type: NumberU64

Opaque number uniquely identifying the memory space.

Return value

Map[String]Value

Object that contains the sideband information for the specified address.

Errors

  • E_unknown_instance_id.
  • E_unknown_memory_space_id.
  • E_address_out_of_range.
  • E_unaligned_access.
  • E_unsupported_attribute_name.
  • E_unsupported_attribute_value.
  • E_unsupported_attribute_combination.

memory_getUsefulAddressTranslations()

Returns a list of useful address translations that are supported by memory_translateAddress(). It does not necessarily return all supported translations, but all returned translations are guaranteed to be supported by memory_translateAddress().

Arguments

instId

Type: NumberU64

Opaque number uniquely identifying the target instance.

Return value

MemorySupportedAddressTranslationResult[]

List of useful and supported address translations. See MemorySupportedAddressTranslationResult.

Errors

  • E_unknown_instance_id.

memory_read()

Reads data from the target's memory view of a given memory space. The semantics are peek rather than bus read.

Arguments

address

Type: NumberU64

Start reading at this address. Must be within the range minAddr to maxAddr inclusive in the specified memory space, else E_address_out_of_range is returned. Must be naturally aligned according to byteWidth.

attrib

Type: Map[String]Value

Optional. Transaction attributes for the memory access. The attributes are represented as key/value pairs as members in the Object. All specified attributes override the respective default attributes of the selected memory space. A subset of all supported attributes can be specified, in which case only the specified attributes are overridden.

Specifying an empty object or omitting the attrib argument causes the default attributes of the selected memory space to be used. Specifying an unsupported or unknown attribute name results in an E_unsupported_attribute_name error. Specifying an unsupported or invalid value for a valid attribute name results in an E_unsupported_attribute_value error. Specifying an invalid combination of attributes (also with respect to default attributes that were not overridden) can result in E_unsupported_attribute_combination, but target instances are not obliged to detect all invalid attribute combinations.

The set of attributes supported by a memory space depends on the memory space and the target instance. The MemorySpaceInfo publishes all attributes and their default values in the attrib and attribDefaults fields.

byteWidth

Type: NumberU64

Access width in bytes. Must be a power of two (1, 2, 4, 8 ...), else E_data_size_error is returned. Accesses that fail because of a valid but unsupported access width record the error address in the error member of the result.

count

Type: NumberU64

Number of elements of byteWidth to read, starting at address and increasing the address for each element by byteWidth. Must be > 0, else E_data_size_error is returned. Models can transport accesses as bursts or individually, depending on the capabilities of the bus that is used internally.

instId

Type: NumberU64

Opaque number uniquely identifying the target instance.

spaceId

Type: NumberU64

Opaque number uniquely identifying the memory space.

Return value

MemoryReadResult

Object that contains the data and optional error indication for each element that was read. See MemoryReadResult.

Errors

  • E_unknown_instance_id.
  • E_unknown_memory_space_id.
  • E_data_size_error.
  • E_address_out_of_range.
  • E_unaligned_access.
  • E_unsupported_attribute_name.
  • E_unsupported_attribute_value.
  • E_unsupported_attribute_combination.

memory_translateAddress()

Translates an address of one memory space into an address of another memory space. This function is useful if the two memory spaces are associated with two different translation regimes, for example virtual and physical memory. A common example is to convert a virtual address into a physical address.

Arguments

instId

Type: NumberU64

Opaque number uniquely identifying the target instance.

address

Type: NumberU64

Input address.

outSpaceId

Type: NumberU64

Desired output memory space. The address is translated from spaceId to outSpaceId.

spaceId

Type: NumberU64

Opaque number uniquely identifying the memory space of the input address.

Return value

MemoryAddressTranslationResult

Object that contains the result of the address translation. This is either the output address or an error. See MemoryAddressTranslationResult.

Errors

  • E_unknown_instance_id.
  • E_unknown_memory_space_id.
  • E_address_out_of_range.
  • E_unsupported_translation.

memory_write()

Writes data into the target's memory view of a given memory space. The semantics are poke rather than bus write.

Arguments

address

Type: NumberU64

Start writing bytes at this address. Must be within minAddr and maxAddr of the memory space.

attrib

Type: Map[String]Value

Optional. Transaction attributes for the memory access. The attributes are represented as key/value pairs as members in the object. All specified attributes override the respective default attributes of the selected memory space. A subset of all supported attributes can be specified, in which case only the specified attributes are overridden.

Specifying an empty object or omitting the attrib argument causes the default attributes of the selected memory space to be used. Specifying an unsupported or unknown attribute name results in an E_unsupported_attribute_name error. Specifying an unsupported or invalid value for a valid attribute name results in an E_unsupported_attribute_value error. Specifying an invalid combination of attributes (also with respect to default attributes that were not overridden) can result in E_unsupported_attribute_combination, but target instances are not obliged to detect all invalid attribute combinations.

The set of attributes supported by a memory space depends on the memory space and the target instance. The MemorySpaceInfo publishes all attributes and their default values in the attrib and attribDefaults fields.

byteWidth

Type: NumberU64

Access width in bytes. Must be 1, 2, 4, or 8, else E_data_size_error is returned. Accesses that fail because of a valid but unsupported access width record the error address in the error member of the result.

count

Type: NumberU64

Number of elements of byteWidth to write, starting at address and increasing the address for each element by byteWidth. Must be > 0, else E_data_size_error is returned. Models can transport accesses as bursts or individually, depending on the capabilities of the bus that is used internally.

data

Type: NumberU64[]

Data elements written to ascending addresses, packed into NumberU64 types such that the lowest address is in the lowest bits:

byteWidth=1
8 bytes per NumberU64, lowest address in bits[7:0].
byteWidth=2
4 x 16-bit values per NumberU64, lowest address in bits[15:0].
byteWidth=4
2 x 32-bit values per NumberU64, lowest address in bits[31:0].
byteWidth=8
1 NumberU64 per address.
byteWidth=16
2 NumberU64 per address, lowest bits in the first one.
byteWidth=N
N/8 NumberU64 per address, lowest bits in the first one. Elements of byteWidth >= 2 are read with the endianness of the memory space inside each element, but elements are stored with the lowest bits inside each NumberU64 (for byteWidth < 8) and with the lowest bits first in sequences of NumberU64 (for byteWidth > 8).

Elements that caused an error while writing record the error address in the error member in the result. Padding bytes (unused high bits) must be set to zero. The array must have exactly N = floor((byteWidth*count+7) / 8) NumberU64 elements (N is always >= 1).

instId

Type: NumberU64

Opaque number uniquely identifying the target instance.

spaceId

Type: NumberU64

Opaque number uniquely identifying the memory space.

Return value

MemoryWriteResult

Object that contains error information. See MemoryWriteResult for details.

Errors

  • E_unknown_instance_id.
  • E_unknown_memory_space_id.
  • E_data_size_error.
  • E_address_out_of_range.
  • E_unaligned_access.
  • E_unsupported_attribute_name.
  • E_unsupported_attribute_value.
  • E_unsupported_attribute_combination.
Non-ConfidentialPDF file icon PDF version101196_0100_03_en
Copyright © 2018, 2019 Arm Limited or its affiliates. All rights reserved.