#include <metal/io.h>
#include <metal/mutex.h>
#include <metal/compiler.h>

Data Structures
struct	resource_table
	Resource table header. More...

struct	fw_rsc_hdr
	Resource table entry header. More...

struct	fw_rsc_carveout
	Resource table physically contiguous memory request entry. More...

struct	fw_rsc_devmem
	Resource table IOMMU mapping request entry. More...

struct	fw_rsc_trace
	Resource table trace buffer declaration entry. More...

struct	fw_rsc_vdev_vring
	Resource table vring descriptor entry. More...

struct	fw_rsc_vdev
	Resource table virtio device entry. More...

struct	fw_rsc_vendor
	Resource table remote processor vendor specific entry. More...

struct	remoteproc_mem
	Memory used by the remote processor. More...

struct	remoteproc
	A remote processor instance. More...

struct	remoteproc_ops
	Remoteproc operations to manage a remoteproc instance. More...

Macros
#define	RSC_NOTIFY_ID_ANY 0xFFFFFFFFU

#define	RPROC_MAX_NAME_LEN 32

#define	FW_RSC_U64_ADDR_ANY 0xFFFFFFFFFFFFFFFFUL

#define	FW_RSC_U32_ADDR_ANY 0xFFFFFFFFUL

#define	RPROC_EBASE 0

#define	RPROC_ENOMEM (RPROC_EBASE + 1)

#define	RPROC_EINVAL (RPROC_EBASE + 2)

#define	RPROC_ENODEV (RPROC_EBASE + 3)

#define	RPROC_EAGAIN (RPROC_EBASE + 4)

#define	RPROC_ERR_RSC_TAB_TRUNC (RPROC_EBASE + 5)

#define	RPROC_ERR_RSC_TAB_VER (RPROC_EBASE + 6)

#define	RPROC_ERR_RSC_TAB_RSVD (RPROC_EBASE + 7)

#define	RPROC_ERR_RSC_TAB_VDEV_NRINGS (RPROC_EBASE + 9)

#define	RPROC_ERR_RSC_TAB_NP (RPROC_EBASE + 10)

#define	RPROC_ERR_RSC_TAB_NS (RPROC_EBASE + 11)

#define	RPROC_ERR_LOADER_STATE (RPROC_EBASE + 12)

#define	RPROC_EMAX (RPROC_EBASE + 16)

#define	RPROC_EPTR (void *)(-1)

#define	RPROC_EOF (void *)(-1)

Enumerations
enum	fw_resource_type { RSC_CARVEOUT = 0 , RSC_DEVMEM = 1 , RSC_TRACE = 2 , RSC_VDEV = 3 , RSC_LAST = 4 , RSC_VENDOR_START = 128 , RSC_VENDOR_END = 512 }
	Types of resource entries. More...

enum	remoteproc_state { RPROC_OFFLINE = 0 , RPROC_CONFIGURED = 1 , RPROC_READY = 2 , RPROC_RUNNING = 3 , RPROC_SUSPENDED = 4 , RPROC_ERROR = 5 , RPROC_STOPPED = 6 , RPROC_LAST = 7 }
	Remote processor states. More...

Functions
static long	RPROC_PTR_ERR (const void *ptr)

static int	RPROC_IS_ERR (const void *ptr)

static void *	RPROC_ERR_PTR (long error)

struct remoteproc *	remoteproc_init (struct remoteproc rproc, const struct remoteproc_ops ops, void *priv)
	Initializes remoteproc resource. More...

int	remoteproc_remove (struct remoteproc *rproc)
	Remove remoteproc resource. More...

void	remoteproc_init_mem (struct remoteproc_mem mem, const char name, metal_phys_addr_t pa, metal_phys_addr_t da, size_t size, struct metal_io_region *io)
	Initialize remoteproc memory. More...

void	remoteproc_add_mem (struct remoteproc rproc, struct remoteproc_mem mem)
	Add remoteproc memory. More...

struct metal_io_region *	remoteproc_get_io_with_name (struct remoteproc rproc, const char name)
	Get remoteproc memory I/O region with name. More...

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. More...

struct metal_io_region *	remoteproc_get_io_with_da (struct remoteproc rproc, metal_phys_addr_t da, unsigned long offset)
	Get remoteproc memory I/O region with device address. More...

struct metal_io_region *	remoteproc_get_io_with_va (struct remoteproc rproc, void va)
	Get remoteproc memory I/O region with virtual address. More...

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. More...

int	remoteproc_set_rsc_table (struct remoteproc rproc, struct resource_table rsc_table, size_t rsc_size)
	Parse and set resource table of remoteproc. More...

int	remoteproc_config (struct remoteproc rproc, void data)
	This function configures the remote processor to get it ready to load and run executable. More...

int	remoteproc_start (struct remoteproc *rproc)
	This function starts the remote processor. More...

int	remoteproc_stop (struct remoteproc *rproc)
	This function stops the remote processor but it will not release its resource. More...

int	remoteproc_shutdown (struct remoteproc *rproc)
	This function shuts down the remote processor and releases its resources. More...

int	remoteproc_load (struct remoteproc rproc, const char path, void store, const struct image_store_ops store_ops, void **img_info)
	Loads the executable. More...

int	remoteproc_load_noblock (struct remoteproc rproc, const void img_data, size_t offset, size_t len, void *img_info, metal_phys_addr_t pa, struct metal_io_region *io, size_t noffset, size_t nlen, size_t nmlen, unsigned char *padding)
	Loads the executable. More...

unsigned int	remoteproc_allocate_id (struct remoteproc *rproc, unsigned int start, unsigned int end)
	Allocate notifyid for resource. More...

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. More...

void	remoteproc_remove_virtio (struct remoteproc rproc, struct virtio_device vdev)
	Remove virtio device. More...

int	remoteproc_get_notification (struct remoteproc *rproc, uint32_t notifyid)
	remoteproc is got notified, it will check its subdevices for the notification More...

Variables
METAL_PACKED_BEGIN struct resource_table	METAL_PACKED_END

Macro Definition Documentation

◆ FW_RSC_U32_ADDR_ANY

#define FW_RSC_U32_ADDR_ANY 0xFFFFFFFFUL

◆ FW_RSC_U64_ADDR_ANY

#define FW_RSC_U64_ADDR_ANY 0xFFFFFFFFFFFFFFFFUL

◆ RPROC_EAGAIN

#define RPROC_EAGAIN (RPROC_EBASE + 4)

◆ RPROC_EBASE

#define RPROC_EBASE 0

◆ RPROC_EINVAL

#define RPROC_EINVAL (RPROC_EBASE + 2)

◆ RPROC_EMAX

#define RPROC_EMAX (RPROC_EBASE + 16)

◆ RPROC_ENODEV

#define RPROC_ENODEV (RPROC_EBASE + 3)

◆ RPROC_ENOMEM

#define RPROC_ENOMEM (RPROC_EBASE + 1)

◆ RPROC_EOF

#define RPROC_EOF (void *)(-1)

◆ RPROC_EPTR

#define RPROC_EPTR (void *)(-1)

◆ RPROC_ERR_LOADER_STATE

#define RPROC_ERR_LOADER_STATE (RPROC_EBASE + 12)

◆ RPROC_ERR_RSC_TAB_NP

#define RPROC_ERR_RSC_TAB_NP (RPROC_EBASE + 10)

◆ RPROC_ERR_RSC_TAB_NS

#define RPROC_ERR_RSC_TAB_NS (RPROC_EBASE + 11)

◆ RPROC_ERR_RSC_TAB_RSVD

#define RPROC_ERR_RSC_TAB_RSVD (RPROC_EBASE + 7)

◆ RPROC_ERR_RSC_TAB_TRUNC

#define RPROC_ERR_RSC_TAB_TRUNC (RPROC_EBASE + 5)

◆ RPROC_ERR_RSC_TAB_VDEV_NRINGS

#define RPROC_ERR_RSC_TAB_VDEV_NRINGS (RPROC_EBASE + 9)

◆ RPROC_ERR_RSC_TAB_VER

#define RPROC_ERR_RSC_TAB_VER (RPROC_EBASE + 6)

◆ RPROC_MAX_NAME_LEN

#define RPROC_MAX_NAME_LEN 32

◆ RSC_NOTIFY_ID_ANY

#define RSC_NOTIFY_ID_ANY 0xFFFFFFFFU

Enumeration Type Documentation

◆ fw_resource_type

enum fw_resource_type

Types of resource entries.

For more details regarding a specific resource type, please see its dedicated structure below.

Please note that these values are used as indices to the rproc_handle_rsc lookup table, so please keep them sane. Moreover, RSC_LAST is used to check the validity of an index before the lookup table is accessed, so please update it as needed.

Enumerator
RSC_CARVEOUT	carveout resource Request for allocation of a physically contiguous memory region.
RSC_DEVMEM	device memory resource Request to iommu_map a memory-based peripheral.
RSC_TRACE	trace resource Announces the availability of a trace buffer into which the remote remoteproc will be writing logs.
RSC_VDEV	virtio device resource Declare support for a virtio device, and serve as its virtio header.
RSC_LAST	end of the generic resources
RSC_VENDOR_START	Start of the vendor specific resource types range.
RSC_VENDOR_END	End of the vendor specific resource types range.

◆ remoteproc_state

enum remoteproc_state

Remote processor states.

Enumerator
RPROC_OFFLINE	Remote is offline.
RPROC_CONFIGURED	Remote is configured.
RPROC_READY	Remote is ready to start.
RPROC_RUNNING	Remote is up and running.
RPROC_SUSPENDED	Remote is suspended.
RPROC_ERROR	Remote is has error; need to recover.
RPROC_STOPPED	Remote is stopped.
RPROC_LAST	Just keep this one at the end.

Function Documentation

◆ remoteproc_add_mem()

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

Add remoteproc memory.

Parameters

rproc	Pointer to remoteproc
mem	Pointer to remoteproc memory

◆ remoteproc_allocate_id()

unsigned int remoteproc_allocate_id	(	struct remoteproc *	rproc,
		unsigned int	start,
		unsigned int	end
	)

Allocate notifyid for resource.

Parameters

rproc	Pointer to the remoteproc instance
start	Start of the id range
end	End of the id range

Returns: Allocated notify id

◆ remoteproc_config()

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

◆ remoteproc_create_virtio()

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

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.

◆ remoteproc_get_io_with_da()

struct metal_io_region* remoteproc_get_io_with_da	(	struct remoteproc *	rproc,
		metal_phys_addr_t	da,
		unsigned long *	offset
	)

Get remoteproc memory I/O region with device address.

Parameters

rproc	Pointer to the remote processor
da	Device address
offset	I/O region offset of the device address

Returns: Metal I/O region pointer, NULL for failure

◆ remoteproc_get_io_with_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

◆ remoteproc_get_io_with_pa()

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

◆ remoteproc_get_io_with_va()

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

◆ remoteproc_get_notification()

int remoteproc_get_notification	(	struct remoteproc *	rproc,
		uint32_t	notifyid
	)

remoteproc is got notified, it will check its subdevices for the notification

Parameters

rproc	Pointer to the remoteproc instance
notifyid	Notification id

Returns: 0 for succeed, negative value for failure

◆ remoteproc_init()

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

◆ remoteproc_init_mem()

void remoteproc_init_mem	(	struct remoteproc_mem *	mem,
		const char *	name,
		metal_phys_addr_t	pa,
		metal_phys_addr_t	da,
		size_t	size,
		struct metal_io_region *	io
	)

Initialize remoteproc memory.

Parameters

mem	Pointer to remoteproc memory
name	Memory name (max string size RPROC_MAX_NAME_LEN)
pa	Physical address
da	Device address
size	Memory size
io	Pointer to the I/O region

◆ remoteproc_load()

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

◆ remoteproc_load_noblock()

int remoteproc_load_noblock	(	struct remoteproc *	rproc,
		const void *	img_data,
		size_t	offset,
		size_t	len,
		void **	img_info,
		metal_phys_addr_t *	pa,
		struct metal_io_region **	io,
		size_t *	noffset,
		size_t *	nlen,
		size_t *	nmlen,
		unsigned char *	padding
	)

Loads the executable.

Expects the caller has loaded image data to local memory and passed to the this function. If the function needs more image data it will return the next expected image data offset and the next expected image data length. If the function requires the caller to download image data to the target memory, it will also return the target physical address besides the offset and length. This function can be used to load firmware in stream mode. In this mode, you cannot do seek to the executable file. If the executable is ELF, it cannot get the resource table section before it loads the full ELF file. Furthermore, application usually don't store the data which is loaded to local memory in streaming mode, and thus, in this mode, it will load the binary to the target memory before it gets the resource table. And thus, when calling this function don't put the target executable memory in the resource table, as this function will parse the resource table after it loads the binary to target memory.

Parameters

rproc	Pointer to the remoteproc instance
img_data	Pointer to image data for remoteproc loader to parse
offset	Image data offset to the beginning of the image file
len	Image data length
img_info	Pointer to memory which stores image information used by remoteproc loader
pa	Pointer to the target memory physical address. If the next expected data doesn't need to load to the target memory, the function will set it to ANY.
io	Pointer to the io region. If the next expected data doesn't need to load to the target memory, the function will set it to NULL.
noffset	Pointer to the next image data offset to the beginning of the image file needs to load to local or to the target memory.
nlen	Pointer to the next image data length needs to load to local or to the target memory.
nmlen	Pointer to the memory size. It is only used when the next expected data is going to be loaded to the target memory. E.g. in ELF, it is possible that loadable segment in memory is larger that the segment data in the ELF file. In this case, application will need to pad the rest of the memory with padding.
padding	Pointer to the padding value. It is only used when the next expected data is going to be loaded to the target memory and the target memory size is larger than the segment data in the executable file.

Returns: 0 for success and negative value for failure

◆ remoteproc_mmap()

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

◆ remoteproc_remove()

int remoteproc_remove ( struct remoteproc * rproc )

Remove remoteproc resource.

Parameters

rproc Pointer to remoteproc instance

Returns: 0 for success, negative value for failure

◆ remoteproc_remove_virtio()

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

◆ remoteproc_set_rsc_table()

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

◆ remoteproc_shutdown()

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

◆ remoteproc_start()

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

◆ remoteproc_stop()

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

◆ RPROC_ERR_PTR()

static void* RPROC_ERR_PTR ( long error )

inlinestatic

◆ RPROC_IS_ERR()

static int RPROC_IS_ERR ( const void * ptr )

inlinestatic

◆ RPROC_PTR_ERR()

static long RPROC_PTR_ERR ( const void * ptr )

inlinestatic

Variable Documentation

◆ METAL_PACKED_END

METAL_PACKED_BEGIN struct rpmsg_ns_msg METAL_PACKED_END

Data Structures

Macros

Enumerations

Functions

Variables

Macro Definition Documentation

◆ FW_RSC_U32_ADDR_ANY

◆ FW_RSC_U64_ADDR_ANY

◆ RPROC_EAGAIN

◆ RPROC_EBASE

◆ RPROC_EINVAL

◆ RPROC_EMAX

◆ RPROC_ENODEV

◆ RPROC_ENOMEM

◆ RPROC_EOF

◆ RPROC_EPTR

◆ RPROC_ERR_LOADER_STATE

◆ RPROC_ERR_RSC_TAB_NP

◆ RPROC_ERR_RSC_TAB_NS

◆ RPROC_ERR_RSC_TAB_RSVD

◆ RPROC_ERR_RSC_TAB_TRUNC

◆ RPROC_ERR_RSC_TAB_VDEV_NRINGS

◆ RPROC_ERR_RSC_TAB_VER

◆ RPROC_MAX_NAME_LEN

◆ RSC_NOTIFY_ID_ANY

Enumeration Type Documentation

◆ fw_resource_type

◆ remoteproc_state

Function Documentation

◆ remoteproc_add_mem()

◆ remoteproc_allocate_id()

◆ remoteproc_config()

◆ remoteproc_create_virtio()

◆ remoteproc_get_io_with_da()

◆ remoteproc_get_io_with_name()

◆ remoteproc_get_io_with_pa()

◆ remoteproc_get_io_with_va()

◆ remoteproc_get_notification()

◆ remoteproc_init()

◆ remoteproc_init_mem()

◆ remoteproc_load()

◆ remoteproc_load_noblock()

◆ remoteproc_mmap()

◆ remoteproc_remove()

◆ remoteproc_remove_virtio()

◆ remoteproc_set_rsc_table()

◆ remoteproc_shutdown()

◆ remoteproc_start()

◆ remoteproc_stop()

◆ RPROC_ERR_PTR()

◆ RPROC_IS_ERR()

◆ RPROC_PTR_ERR()

Variable Documentation

◆ METAL_PACKED_END