This is the documentation for the latest (main) development branch. If you are looking for the documentation of previous releases, use the drop-down menu on the left and select the desired version.

Remoteproc Design Document

Remoteproc provides abstraction to manage the life cycle of a remote application. For now, it only provides APIs on bringing up and tearing down the remote application, and parsing resource table. It will extend to crash detection, suspend and resume.

Remoteproc LCM States

State	State Description
Offline	Initial state of a remoteproc instance. The remote presented by the remoteproc instance and its resource has been powered off.
Configured	The remote presented by the remoteproc instance has been configured. And ready to load application.
Ready	The remote presented by the remoteproc instance has application loaded, and ready to run.
Stopped	The remote presented by the remoteproc instance has stopped from running. But the remote is still powered on. And the remote’s resource hasn’t been released.

State Transition

State Transition	Transition Trigger
Offline -> Configured	Configure the remote to make it able to load application remoteproc_config
Configured -> Ready	load firmware remoteproc_load
Ready -> Running	start the processor remoteproc_start
Ready -> Stopped	stop the processor remoteproc_stop, remoteproc_shutdown (Stopped is the intermediate state of shutdown operation)
Running -> Stopped	stop the processor remoteproc_stop, remoteproc_shutdown
Stopped -> Offline	shutdown the processor remoteproc_shutdown

Remote User APIs

Configure remote

int remoteproc_config(struct remoteproc *rproc, void *data)

This function configures the remote processor to get it ready to load and run executable.

Parameters:

rproc – Pointer to remoteproc instance to start
data – Configuration data

Returns:

0 for success and negative value for errors

Initialize remoteproc instance

struct remoteproc *remoteproc_init(struct remoteproc *rproc, const struct remoteproc_ops *ops, void *priv)

Initializes remoteproc resource.

Parameters:

rproc – Pointer to remoteproc instance
ops – Pointer to remoteproc operations
priv – Pointer to private data

Returns:

Created remoteproc pointer

Release remoteproc instance

int remoteproc_remove(struct remoteproc *rproc)

Remove remoteproc resource.

Parameters:: rproc – Pointer to remoteproc instance
Returns:: 0 for success, negative value for failure

Add memory to remoteproc

void remoteproc_add_mem(struct remoteproc *rproc, struct remoteproc_mem *mem)

Add remoteproc memory.

Parameters:

rproc – Pointer to remoteproc
mem – Pointer to remoteproc memory

Get memory libmetal I/O region from remoteproc specifying memory name

struct metal_io_region *remoteproc_get_io_with_name(struct remoteproc *rproc, const char *name)

Get remoteproc memory I/O region with name.

Parameters:

rproc – Pointer to the remote processor
name – Name of the shared memory

Returns:

Metal I/O region pointer, NULL for failure

Get memory libmetal I/O region from remoteproc specifying physical address

struct metal_io_region *remoteproc_get_io_with_pa(struct remoteproc *rproc, metal_phys_addr_t pa)

Get remoteproc memory I/O region with physical address.

Parameters:

rproc – Pointer to the remote processor
pa – Physical address

Returns:

Metal I/O region pointer, NULL for failure

Get memory libmetal I/O region from remoteproc specifying virtual address

struct metal_io_region *remoteproc_get_io_with_va(struct remoteproc *rproc, void *va)

Get remoteproc memory I/O region with virtual address.

Parameters:

rproc – Pointer to the remote processor
va – Virtual address

Returns:

Metal I/O region pointer, NULL for failure

Map memory and add the memory to the remoteproc instance

void *remoteproc_mmap(struct remoteproc *rproc, metal_phys_addr_t *pa, metal_phys_addr_t *da, size_t size, unsigned int attribute, struct metal_io_region **io)

Remoteproc mmap memory.

Parameters:

rproc – Pointer to the remote processor
pa – Physical address pointer
da – Device address pointer
size – Size of the memory
attribute – Memory attribute
io – Pointer to the I/O region

Returns:

Pointer to the memory

Set resource table to remoteproc

int remoteproc_set_rsc_table(struct remoteproc *rproc, struct resource_table *rsc_table, size_t rsc_size)

Parse and set resource table of remoteproc.

Parameters:

rproc – Pointer to remoteproc instance
rsc_table – Pointer to resource table
rsc_size – Resource table size

Returns:

0 for success and negative value for errors

Configure the remote presented by the remoteproc instance to make it able to load application

int remoteproc_config(struct remoteproc *rproc, void *data)

This function configures the remote processor to get it ready to load and run executable.

Parameters:

rproc – Pointer to remoteproc instance to start
data – Configuration data

Returns:

0 for success and negative value for errors

Load application to the remote presented by the remoteproc instance to make it ready to run

int remoteproc_load(struct remoteproc *rproc, const char *path, void *store, const struct image_store_ops *store_ops, void **img_info)

Loads the executable.

Expects the user application defines how to open the executable file and how to get data from the executable file and how to load data to the target memory.

Parameters:

rproc – Pointer to the remoteproc instance
path – Optional path to the image file
store – Pointer to user defined image store argument
store_ops – Pointer to image store operations
img_info – Pointer to memory which stores image information used by remoteproc loader

Returns:

0 for success and negative value for failure

Run application on the remote presented by the remoteproc instance

int remoteproc_start(struct remoteproc *rproc)

This function starts the remote processor.

It assumes the firmware is already loaded.

Parameters:: rproc – Pointer to remoteproc instance to start
Returns:: 0 for success and negative value for errors

Stop application on remote presented by the remoteproc instance

int remoteproc_stop(struct remoteproc *rproc)

This function stops the remote processor but it will not release its resource.

Parameters:: rproc – Pointer to remoteproc instance
Returns:: 0 for success and negative value for errors

Shutdown the remote presented by the remoteproc instance

int remoteproc_shutdown(struct remoteproc *rproc)

This function shuts down the remote processor and releases its resources.

Parameters:: rproc – Pointer to remoteproc instance
Returns:: 0 for success and negative value for errors

Create virtio device from the resource table vdev resource, and add it to the remoteproc instance

struct virtio_device *remoteproc_create_virtio(struct remoteproc *rproc, int vdev_id, unsigned int role, void (*rst_cb)(struct virtio_device *vdev))

Create virtio device, it returns pointer to the created virtio device.

Parameters:

rproc – Pointer to the remoteproc instance
vdev_id – virtio device ID
role – virtio device role
rst_cb – virtio device reset callback

Returns:

Pointer to the created virtio device, NULL for failure.

Remove virtio device from the remoteproc instance

void remoteproc_remove_virtio(struct remoteproc *rproc, struct virtio_device *vdev)

Remove virtio device.

Parameters:

rproc – Pointer to the remoteproc instance
vdev – Pointer to the virtio device