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 data structures

Remoteproc

struct remoteproc

A remote processor instance.

This structure is maintained by the remoteproc to represent the remote processor instance. This structure acts as a prime parameter to use the remoteproc APIs.

Public Members

metal_mutex_t lock: Mutex lock.

void *rsc_table: Pointer to the resource table.

size_t rsc_len: Length of the resource table.

struct metal_io_region *rsc_io: Metal I/O region of the resource table.

struct metal_list mems: Remoteproc memories.

struct metal_list vdevs: Remoteproc virtio devices.

unsigned long bitmap: Bitmap for notify IDs for remoteproc subdevices.

const struct remoteproc_ops *ops: Remoteproc operations.

metal_phys_addr_t bootaddr: Boot address.

const struct loader_ops *loader: Executable loader.

unsigned int state: Remote processor state.

void *priv: Private data.

Refer also remoteproc documentation and remoteproc code implementation.

Virtio Structure for Remoteproc

struct remoteproc_virtio

Virtio structure for remoteproc instance.

Public Members

void *priv: Pointer to private data.

void *vdev_rsc: Address of vdev resource.

struct metal_io_region *vdev_rsc_io: Metal I/O region of vdev_info, can be NULL.

rpvdev_notify_func notify: Notification function.

struct virtio_device vdev: Virtio device.

struct metal_list node: List node.

Refer also remoteproc_virtio documentation and remoteproc code implementation.

Virtio Data Structures

Virtio Device

struct virtio_device

Structure definition for virtio devices for use by the applications/drivers.

Public Members

uint32_t notifyid: Unique position on the virtio bus.

struct virtio_device_id id: The device type identification used to match it with a driver.

uint64_t features: The features supported by both ends.

unsigned int role: If it is virtio backend or front end.

virtio_dev_reset_cb reset_cb: User-registered device callback.

const struct virtio_dispatch *func

Virtio dispatch table.

Virtio device memory operations

void *priv: Private data.

unsigned int vrings_num: Number of vrings.

struct virtio_vring_info *vrings_info: Pointer to the virtio vring structure.

Refer also virtio_device documentation and virtio_device code implementation.

Virtqueue local context

struct virtqueue

Local virtio queue to manage a virtio ring for sending or receiving.

Public Members

struct virtio_device *vq_dev: Associated virtio device.

const char *vq_name: Name of the virtio queue.

uint16_t vq_queue_index: Index of the virtio queue.

uint16_t vq_nentries: Max number of buffers in the virtio queue.

void (*callback)(struct virtqueue *vq): Function to invoke, when message is available on the virtio queue.

void *priv: Private data associated to the virtio queue.

void (*notify)(struct virtqueue *vq): Function to invoke, to inform the other side about an update in the virtio queue.

struct vring vq_ring: Associated virtio ring.

uint16_t vq_free_cnt: Number of free descriptor in the virtio ring.

uint16_t vq_queued_cnt: Number of queued buffer in the virtio ring.

struct metal_io_region *shm_io

Metal I/O region of the buffers.

This structure is used for conversion between virtual and physical addresses.

uint16_t vq_desc_head_idx

Head of the free chain in the descriptor table.

If there are no free descriptors, this will be set to VQ_RING_DESC_CHAIN_END.

uint16_t vq_used_cons_idx: Last consumed descriptor in the used table, trails vq_ring.used->idx.

uint16_t vq_available_idx: Last consumed descriptor in the available table, used by the consumer side.

struct vq_desc_extra vq_descx[0]

Used by the host side during callback.

Cookie holds the address of buffer received from other side. Other fields in this structure are not used currently.

Refer also virtqueue documentation and virtqueue code implementation.

Shared virtqueue structure

Representation of a shared virtqueue structure defined in Virtual I/O Device (VIRTIO) Standard virtqueue.

struct vring

The virtqueue layout structure.

Each virtqueue consists of; descriptor table, available ring, used ring, where each part is physically contiguous in guest memory, referenced by the pointers in this structure.

When the driver wants to send a buffer to the device, it fills in a slot in the descriptor table (or chains several together), and writes the descriptor index into the available ring. It then notifies the device. When the device has finished a buffer, it writes the descriptor index into the used ring, and sends an interrupt.

The standard layout for the ring, referenced by this structure, is a continuous chunk of memory exemplified by this table. The maximum number of buffer descriptors, num, is a power of 2.

vring	definition	description
desc	struct vring_desc desc[num]	All num descriptors
avail	uint16_t avail_flags	Device notification flags
	uint16_t avail_idx	Driver’s next descriptor location
	uint16_t available[num]	The ring of descriptors
	uint16_t used_event_idx	Free running index
pad	char pad[]	Padding for memory alignment
used	uint16_t used_flags	Device notification flags
	uint16_t used_idx	Driver’s next descriptor location
	struct vring_used_elem used[num]	The ring of descriptors
	uint16_t avail_event_idx	Free running index

Padding for alignment requirements:

Some architectures require strict alignment for atomic operations or DMA transfer. The pad item should be inserted between avail and used memory sections to ensure that the used ring is aligned, as the available ring size is not necessarily a multiple of 4 or 8 bytes.

The alignment may also be necessary for CPU cache line utilization, as padding can avoid crossing cache lines or memory pages in the shared memory.

NOTE: for VirtIO PCI, align is 4096.

Public Members

unsigned int num

The maximum number of buffer descriptors in the virtqueue.

The value is always a power of 2.

struct vring_desc *desc: The actual buffer descriptors, 16 bytes each.

struct vring_avail *avail: A ring of available descriptor heads with free-running index.

struct vring_used *used: A ring of used descriptor heads with free-running index.

Refer also vring documentation and vring code implementation.

RPMsg virtio Data struct

struct rpmsg_virtio_device

Representation of a RPMsg device based on virtio.

Public Members

struct rpmsg_device rdev: RPMsg device.

struct rpmsg_virtio_config config: Structure containing virtio configuration.

struct virtio_device *vdev: Pointer to the virtio device.

struct virtqueue *rvq: Pointer to receive virtqueue.

struct virtqueue *svq: Pointer to send virtqueue.

struct metal_io_region *shbuf_io: Pointer to the shared buffer I/O region.

struct rpmsg_virtio_shm_pool *shpool: Pointer to the shared buffers pool.

struct metal_list reclaimer: RPMsg buffer reclaimer that contains buffers released by the rpmsg_virtio_release_tx_buffer function.

rpmsg_virtio_notify_wait_cb notify_wait_cb: Callback handler for rpmsg virtio service, called when service can’t get tx buffer.

Refer also rpmsg_virtio_device documentation and rpmsg_virtio_device code implementation.

RPMsg Data struct

struct rpmsg_device

Representation of a RPMsg device.

Public Members

struct metal_list endpoints: List of endpoints.

struct rpmsg_endpoint ns_ept: Name service endpoint.

unsigned long bitmap[metal_bitmap_longs(RPMSG_ADDR_BMP_SIZE)]: Table endpoint address allocation.

metal_mutex_t lock: Mutex lock for RPMsg management.

rpmsg_ns_bind_cb ns_bind_cb: Callback handler for name service announcement without local epts waiting to bind.

rpmsg_ns_bind_cb ns_unbind_cb: Callback handler for name service announcement, called when remote ept is destroyed.

struct rpmsg_device_ops ops: RPMsg device operations.

bool support_ns: Create/destroy namespace message.

Refer also rpmsg_device documentation and rpmsg_device code implementation.

Local RPMsg Endpoint

struct rpmsg_endpoint

Structure that binds a local RPMsg address to its user.

In essence, an RPMsg endpoint represents a listener on the RPMsg bus, as it binds an RPMsg address with an rx callback handler.

Public Members

char name[RPMSG_NAME_SIZE]: Name of the service supported.

struct rpmsg_device *rdev: Pointer to the RPMsg device.

uint32_t addr: Local address of the endpoint.

uint32_t dest_addr: Address of the default remote endpoint binded.

uint32_t refcnt: Reference count for determining whether the endpoint can be deallocated.

rpmsg_ept_release_cb release_cb: Callback to inform the user that the endpoint allocation can be safely removed.

rpmsg_ept_cb cb: User rx callback, return value of this callback is reserved for future use, for now, only allow RPMSG_SUCCESS as return value.

rpmsg_ns_unbind_cb ns_unbind_cb: Endpoint service unbind callback, called when remote ept is destroyed.

struct metal_list node: Endpoint node.

void *priv: Private data for the driver’s use.

Refer also rpmsg_endpoint documentation and rpmsg_endpoint code implementation.