4.7.1 Loading and saving an image

Use the following functions to load and save images.

Loading an image

image_loadFile()
Loads an image into a target instance from a file. Loading an image might cause some state to be modified, for example the start address in the PC register. The file must be accessible under path on the host that runs the target instance. If the file is only guaranteed to be accessible on the host that runs the client, clients should use image_loadData() instead, and load the file in the client.
image_loadData()
Loads image data into a target instance. The data can come from a file that is accessible to the client instance, for example, but not necessarily accessible to the target instance. image_loadData() is semantically equivalent to image_loadFile() except that this function does not open a file. Instead, it expects the image contents to be passed as an argument. Clients can use this function to push an image into an instance with a single function call. This function is intended for images that are small enough to be transferred as one uninterruptible chunk, typically up to a few megabytes. To load an image from the client side that is larger than that, use image_loadDataPull().
image_loadDataPull()
Loads image data into a target instance. This is semantically equivalent to image_loadData(), except that the image data is not provided as an argument but is pulled by the target instance from the client by calling the callback function image_loadDataRead(). This interface enables:
  • Interruptible transfers of large images.
  • Format loaders, for example an ELF loader, to only read specific parts of images, or to skip some data, for example debug information.
  • Format loaders to read data whose size is unknown or hard to determine.
memory_write()
This is the primary method of writing raw byte data into memory at a specific address.

Note:

  • The image_load*() functions can optionally load arbitrary raw binary data, which is unformatted and without a header, into memory, by specifying the rawAddr and rawSpaceId arguments.
  • Target instances that do not support all image_load*() functions must return E_function_not_supported_by_instance for the functions that they do not support.

Saving an image

  • memory_read() and resource_read() inspect the state of the target instance. The client is responsible for formatting this data into the required image format and writing it to a file.
  • It is not possible to use the image_*() interface to write an image into a file that is accessible to the target instance. In other words, there is no image_saveFile() functionality.

In a typical implementation:

  • Only target instances that have the executesSoftware=1 property support the image_*() functions.
  • Cores and CPUs support the image_*() functions.
  • Memory components, for example RAMDevice, only support the memory_*() functions, not the image_*() functions.
Non-ConfidentialPDF file icon PDF version101196_0100_00_en
Copyright © 2018 Arm Limited or its affiliates. All rights reserved.