5.10.4 Image loading and saving functions

Describes the following functions:

image_clearMetaInfoList()

Clears the list of meta information for the loaded images in the target instance.

Arguments

instId

Type: NumberU64

Opaque number uniquely identifying the target instance.

Return value

Function has no return value.

Errors

  • E_unknown_instance_id.

image_getMetaInfoList()

Gets image filenames and other meta information as loaded by the client using image_loadData(), or by the target instance using image_loadFile(), since the list of meta information was last reset using image_clearMetaInfoList().

Arguments

instId

Type: NumberU64

Opaque number uniquely identifying the target instance.

Return value

ImageMetaInfo[]

List of image meta information records of images loaded since the last call to image_clearMetaInfoList(). See ImageMetaInfo.

Errors

  • E_unknown_instance_id.

image_loadData()

Loads an image from a data buffer.

Loading an image might cause some state to be modified, for example the start address in the PC register, or the symbol table. This function is semantically equivalent to image_loadFile() except that this function does not open a file. Instead, it expects the image contents as an argument.

Arguments

data

Type: NumberU64[]

Image data to be pushed into the target instance. If rawAddr is not specified, this byte sequence is the complete image, for example a complete ELF file. The bytes are stored in little-endian format in the NumberU64 values. The last element in the array can contain 1-8 valid bytes. Unused bytes must be set to 0 by the callee. The length of this array is floor((size+7)/8), else E_data_size_error is returned.

Only the first size bytes in data are interpreted. The remaining 0-7 unused bytes are ignored. A non-raw image file, for example an ELF file, cannot be pushed into the target in multiple chunks using this function. Use image_loadDataPull() instead to achieve a chunked read of huge ELF files. Multiple ELF files can, of course, be loaded by calling image_loadData() multiple times.

instId

Type: NumberU64

Opaque number uniquely identifying the target instance.

path

Type: String

Optional. Hint to the target instance about the original client-side filename. The target instance must not use this filename to open a file. The path only makes sense on the host of the client. It might still be useful to show this path to the user, with a note that this is a path on the client side.

rawAddr

Type: NumberU64

Optional. If specified, treat the data as a contiguous chunk that starts at byte position 0 and load it to rawAddr and rawSpaceId. A format-specific loader, for example an ELF loader, is not used to load the data, even if it has a valid format signature. If not specified, the data is loaded according to its format signature, see the path argument to image_loadFile().

rawSpaceId

Type: NumberU64

Optional. Memory space id to load raw data into. This must be present iff rawAddr is present, otherwise E_unknown_memory_space_id is returned.

size

Type: NumberU64

Exact size of the image. The size of the data array is insufficient as it has a granularity of 8 bytes. The length of the data array is floor((pushDataSize+7)/8), else E_data_size_error is returned.

Return value

Function has no return value.

Errors

  • E_unknown_instance_id.
  • E_unknown_image_format.
  • E_image_format_error.
  • E_unsupported_argument_name.
  • E_data_size_error.

image_loadDataPull()

Loads an image from a data buffer.

Loading an image might cause some state to be modified, for example the start address in the PC register, or the symbol table. This function is semantically equivalent to image_loadData() except that the image data is not provided as an argument. Instead, the target instance pulls the image data from the client by calling the callback function image_loadDataRead().

Arguments

instId

Type: NumberU64

Opaque number uniquely identifying the target instance.

path

Type: String

Optional. Hint to the target instance about the original client-side filename. The target instance must not use this filename to open a file. The path only makes sense on the host of the client. It might still be useful to show this path to the user, with a note that this is a path on the client side.

rawAddr

Type: NumberU64

Optional. If specified, treat the data as a contiguous chunk that starts at byte position 0 and load it to rawAddr and rawSpaceId. A format-specific loader, for example an ELF loader, is not used to load the data, even if it has a valid format signature. If not specified, the data is loaded according to its format signature, see the path argument to image_loadFile().

rawSpaceId

Type: NumberU64

Optional. Memory space id to load raw data into. This must be present iff rawAddr is present, otherwise E_unknown_memory_space_id is returned.

tag

Type: NumberU64

Opaque tag provided by the caller which is passed back to the callback function image_loadDataRead() so the caller can match the callbacks to the correct call, like a stream id. The instance id of the caller is in the top 32 bits of the request "id" (for all function calls).

Return value

Function has no return value.

Errors

  • E_unknown_instance_id.
  • E_unknown_image_format.
  • E_image_format_error.
  • E_unsupported_argument_name.
  • E_data_size_error.
  • E_operation_interrupted.

image_loadDataRead()

Reads and returns a chunk of data. This is the callback function of image_loadDataPull().

Arguments

end

Type: Boolean

Optional. If this is present and true, this is the last callback for this tag. The client will not be called back again for this tag/image. The client must still return data if size > 0.

instId

Type: NumberU64

Opaque number uniquely identifying the target instance. This is the instance id of the caller of image_loadDataPull().

position

Type: NumberU64

Absolute read position in bytes, relative to the start of the image. Consumers might read the data in any order, might skip data and might read data again. This might be any byte position and is not guaranteed to be aligned to any boundary, in particular not an 8-byte boundary. position might be equal to or exceed the image size. Neither are an error and an empty ImageReadResult is returned in this case.

size

Type: NumberU64

Size of the chunk to read in bytes. This might be 0 and the position + size might exceed the image size (which is unknown to the caller).

tag

Type: NumberU64

This is the value of the tag argument of the image_loadDataPull() call for which this is a callback. It allows clients to match image_loadDataRead() callbacks to the original image_loadDataPull() calls.

Return value

ImageReadResult

An object containing the chunk of data that was read. See ImageReadResult.

Errors

  • E_unknown_instance_id.
  • E_io_error.
  • E_operation_interrupted.

image_loadFile()

Loads an image from a file. Loading an image might cause some state to be modified, for example the start address in the PC register, or the symbol table. The file must be accessible under path on the host that runs the target instance.

Arguments

instId

Type: NumberU64

Opaque number uniquely identifying the target instance.

path

Type: String

Path of the image file to load. It can be absolute or relative to the current working directory. This path must be on a filesystem that is accessible to the callee, but is not necessarily accessible to the client that calls the function.

Multiple image file formats are usually supported. The image file format is auto-detected, based on the content of the file. If the image format is unknown, E_unknown_image_format is returned. If the image format is known but the image could not be loaded because of unsupported content or a malformatted image, E_image_format_error is returned. The instance property loadfileExtension provides a hint to clients about which filename extensions are supported.

rawAddr

Type: NumberU64

Optional. If specified, treat the file content as a contiguous chunk of data, ignoring any format signature, and load it to rawAddr and rawSpaceId. A format-specific loader, for example an ELF loader, is not used to load the data, even if it has a valid format signature. If not specified, the file is loaded according to its format signature, see path.

rawSpaceId

Type: NumberU64

Optional. Memory space id to load raw data into. This must be present iff rawAddr is present, otherwise E_unknown_memory_space_id is returned.

Return value

Function has no return value.

Errors

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