L4 specific VIRTIO Transport layer. More...

Collaboration diagram for L4 VIRTIO Transport Layer:

Namespaces
namespace	L4virtio
	L4-VIRTIO Transport C++ API.

Data Structures
struct	l4virtio_config_hdr_t
	L4-VIRTIO config header, provided in shared data space. More...

struct	l4virtio_config_queue_t
	Queue configuration entry. More...

Typedefs
typedef struct l4virtio_config_hdr_t	l4virtio_config_hdr_t
	L4-VIRTIO config header, provided in shared data space.

typedef struct l4virtio_config_queue_t	l4virtio_config_queue_t
	Queue configuration entry.

Enumerations
enum	L4_virtio_protocol
	L4-VIRTIO protocol number.

enum	L4_virtio_opcodes { L4VIRTIO_OP_SET_STATUS = 0 , L4VIRTIO_OP_CONFIG_QUEUE = 1 , L4VIRTIO_OP_REGISTER_DS = 3 , L4VIRTIO_OP_DEVICE_CONFIG = 4 , L4VIRTIO_OP_GET_DEVICE_IRQ = 5 }
	Opcodes to setup and configure a device. More...

enum	L4virtio_device_ids { L4VIRTIO_ID_NET = 1 , L4VIRTIO_ID_BLOCK = 2 , L4VIRTIO_ID_CONSOLE = 3 , L4VIRTIO_ID_RNG = 4 , L4VIRTIO_ID_BALLOON = 5 , L4VIRTIO_ID_RPMSG = 7 , L4VIRTIO_ID_SCSI = 8 , L4VIRTIO_ID_9P = 9 , L4VIRTIO_ID_RPROC_SERIAL = 11 , L4VIRTIO_ID_CAIF = 12 , L4VIRTIO_ID_GPU = 16 , L4VIRTIO_ID_INPUT = 18 , L4VIRTIO_ID_VSOCK = 19 , L4VIRTIO_ID_CRYPTO = 20 , L4VIRTIO_ID_FS = 26 , L4VIRTIO_ID_SCMI = 32 , L4VIRTIO_ID_SOCK = 0x9999 }
	Virtio device IDs as reported in the driver's config space. More...

enum	L4virtio_device_status { L4VIRTIO_STATUS_ACKNOWLEDGE = 1 , L4VIRTIO_STATUS_DRIVER = 2 , L4VIRTIO_STATUS_DRIVER_OK = 4 , L4VIRTIO_STATUS_FEATURES_OK = 8 , L4VIRTIO_STATUS_DEVICE_NEEDS_RESET = 0x40 , L4VIRTIO_STATUS_FAILED = 0x80 }
	Virtio device status bits. More...

enum	L4virtio_feature_bits { L4VIRTIO_FEATURE_VERSION_1 = 32 , L4VIRTIO_FEATURE_CMD_CONFIG = 160 }
	L4virtio-specific feature bits. More...

enum	L4_virtio_irq_status { L4VIRTIO_IRQ_STATUS_VRING = 1 , L4VIRTIO_IRQ_STATUS_CONFIG = 2 }
	VIRTIO IRQ status codes (l4virtio_config_hdr_t::irq_status). More...

enum	L4_virtio_cmd { L4VIRTIO_CMD_NONE = 0x00000000 , L4VIRTIO_CMD_SET_STATUS = 0x01000000 , L4VIRTIO_CMD_CFG_QUEUE = 0x02000000 , L4VIRTIO_CMD_CFG_CHANGED = 0x04000000 , L4VIRTIO_CMD_NOTIFY_QUEUE = 0x08000000 , L4VIRTIO_CMD_MASK = 0xff000000 }
	Virtio commands for device configuration. More...

Functions
l4virtio_config_queue_t *	l4virtio_config_queues (l4virtio_config_hdr_t const *cfg)
	Get the pointer to the first queue config.

void *	l4virtio_device_config (l4virtio_config_hdr_t const *cfg)
	Get the pointer to the device configuration.

void	l4virtio_set_feature (l4_uint32_t *feature_map, unsigned feat)
	Set the given feature bit in a feature map.

void	l4virtio_clear_feature (l4_uint32_t *feature_map, unsigned feat)
	Clear the given feature bit in a feature map.

unsigned	l4virtio_get_feature (l4_uint32_t *feature_map, unsigned feat)
	Check if the given bit in a feature map is set.

int	l4virtio_set_status (l4_cap_idx_t cap, unsigned status) L4_NOTHROW

int	l4virtio_config_queue (l4_cap_idx_t cap, unsigned queue) L4_NOTHROW

int	l4virtio_register_ds (l4_cap_idx_t cap, l4_cap_idx_t ds_cap, l4_uint64_t base, l4_umword_t offset, l4_umword_t size) L4_NOTHROW

int	l4virtio_device_config_ds (l4_cap_idx_t cap, l4_cap_idx_t config_ds, l4_addr_t *ds_offset) L4_NOTHROW

int	l4virtio_device_notification_irq (l4_cap_idx_t cap, unsigned index, l4_cap_idx_t irq) L4_NOTHROW

Detailed Description

L4 specific VIRTIO Transport layer.

The L4 specific VIRTIO Transport layer is based on L4Re::Dataspace as shared memory and L4::Irq for signaling. The VIRTIO configuration space is mostly based on a shared memory implementation too and accompanied by two IPC functions to synchronize the configuration between device and driver.

Typedef Documentation

◆ l4virtio_config_queue_t

typedef struct l4virtio_config_queue_t l4virtio_config_queue_t

Queue configuration entry.

An array of such entries is available at the l4virtio_config_hdr_t::queues_offset in the config data space.

Consistency rules for the queue config are:

A driver might read num_max at any time.
A driver must write to num, desc_addr, avail_addr, and used_addr only when ready is zero (0). Values in these fields are validated and used by the device only after successfully setting ready to one (1), either by the IPC or by L4VIRTIO_CMD_CFG_QUEUE.
The value of device_notify_index is valid only when ready is one.
The driver might write to device_notify_index at any time, however the change is guaranteed to take effect after a successful L4VIRTIO_CMD_CFG_QUEUE or after a config_queue IPC. Note, the change might also have immediate effect, depending on the device implementation.

Enumeration Type Documentation

◆ L4_virtio_cmd

enum L4_virtio_cmd

Virtio commands for device configuration.

Enumerator
L4VIRTIO_CMD_NONE	No command pending.
L4VIRTIO_CMD_SET_STATUS	Set the status register.
L4VIRTIO_CMD_CFG_QUEUE	Configure a queue.
L4VIRTIO_CMD_CFG_CHANGED	Device config changed.
L4VIRTIO_CMD_NOTIFY_QUEUE	Configure a queue.
L4VIRTIO_CMD_MASK	Mask to get command bits.

Definition at line 116 of file virtio.h.

◆ L4_virtio_irq_status

enum L4_virtio_irq_status

VIRTIO IRQ status codes (l4virtio_config_hdr_t::irq_status).

Note: l4virtio_config_hdr_t::irq_status is currently unused.

Enumerator
L4VIRTIO_IRQ_STATUS_VRING	VRING IRQ pending flag.
L4VIRTIO_IRQ_STATUS_CONFIG	CONFIG IRQ pending flag.

Definition at line 107 of file virtio.h.

◆ L4_virtio_opcodes

enum L4_virtio_opcodes

Opcodes to setup and configure a device.

Enumerator
L4VIRTIO_OP_SET_STATUS	Write device status register.
L4VIRTIO_OP_CONFIG_QUEUE	Configure queue.
L4VIRTIO_OP_REGISTER_DS	Register shared memory with device.
L4VIRTIO_OP_DEVICE_CONFIG	Get device config page.
L4VIRTIO_OP_GET_DEVICE_IRQ	Retrieve device notification IRQ.

Definition at line 51 of file virtio.h.

◆ L4virtio_device_ids

enum L4virtio_device_ids

Virtio device IDs as reported in the driver's config space.

Enumerator
L4VIRTIO_ID_NET	Virtual ethernet card.
L4VIRTIO_ID_BLOCK	General block device.
L4VIRTIO_ID_CONSOLE	Simple device for data IO via ports.
L4VIRTIO_ID_RNG	Entropy source.
L4VIRTIO_ID_BALLOON	Memory ballooning device.
L4VIRTIO_ID_RPMSG	Device using rpmsg protocol.
L4VIRTIO_ID_SCSI	SCSI host device.
L4VIRTIO_ID_9P	Device using 9P transport protocol.
L4VIRTIO_ID_RPROC_SERIAL	Rproc serial device.
L4VIRTIO_ID_CAIF	Device using CAIF network protocol.
L4VIRTIO_ID_GPU	GPU.
L4VIRTIO_ID_INPUT	Input.
L4VIRTIO_ID_VSOCK	Vsock transport.
L4VIRTIO_ID_CRYPTO	Crypto.
L4VIRTIO_ID_FS	FS.
L4VIRTIO_ID_SCMI	Scmi device.
L4VIRTIO_ID_SOCK	Unofficial socket device.

Definition at line 61 of file virtio.h.

◆ L4virtio_device_status

enum L4virtio_device_status

Virtio device status bits.

Enumerator
L4VIRTIO_STATUS_ACKNOWLEDGE	Guest OS has found device.
L4VIRTIO_STATUS_DRIVER	Guest OS knows how to drive device.
L4VIRTIO_STATUS_DRIVER_OK	Driver is set up.
L4VIRTIO_STATUS_FEATURES_OK	Driver has acknowledged feature set.
L4VIRTIO_STATUS_DEVICE_NEEDS_RESET	Device detected fatal error.
L4VIRTIO_STATUS_FAILED	Driver detected fatal error.

Definition at line 84 of file virtio.h.

◆ L4virtio_feature_bits

enum L4virtio_feature_bits

L4virtio-specific feature bits.

Enumerator
L4VIRTIO_FEATURE_VERSION_1	Virtio protocol version 1 supported. Must be 1 for L4virtio.
L4VIRTIO_FEATURE_CMD_CONFIG	Status and queue config are set via cmd field instead of via IPC.

Definition at line 95 of file virtio.h.

Function Documentation

◆ l4virtio_config_queue()

int l4virtio_config_queue	(	l4_cap_idx_t	cap,
		unsigned	queue
	)

Parameters

cap	Capability to the VIRTIO host.

Trigger queue configuration of the given queue.

Usually all queues are configured when the status is written to running. However, in some cases queues shall be disabled or enabled dynamically, in this case this function triggers a reconfiguration from the shared memory register of the queue config.

Parameters

queue Queue index for the queue to be configured.

Return values

0	on success.
-L4_EIO	The queue's status is invalid.
-L4_ERANGE	The queue index exceeds the number of queues.
-L4_EINVAL	Otherwise.

◆ l4virtio_config_queues()

l4virtio_config_queue_t * l4virtio_config_queues ( l4virtio_config_hdr_t const * cfg )

inline

Get the pointer to the first queue config.

Parameters

cfg	Pointer to the config header.

Returns: pointer to queue config of queue 0.

Definition at line 249 of file virtio.h.

References l4virtio_config_hdr_t::queues_offset.

◆ l4virtio_device_config()

void * l4virtio_device_config ( l4virtio_config_hdr_t const * cfg )

inline

Get the pointer to the device configuration.

Parameters

cfg	Pointer to the config header.

Returns: pointer to device configuration structure.

Definition at line 260 of file virtio.h.

◆ l4virtio_device_config_ds()

int l4virtio_device_config_ds	(	l4_cap_idx_t	cap,
		l4_cap_idx_t	config_ds,
		l4_addr_t *	ds_offset
	)

Parameters

cap	Capability to the L4-VIRTIO host

Get the dataspace with the L4virtio configuration page.

Parameters

config_ds	Capability for receiving the dataspace capability for the shared L4-VIRTIO config data space.
ds_offset	Offset into the dataspace where the device configuration structure starts.

◆ l4virtio_device_notification_irq()

int l4virtio_device_notification_irq	(	l4_cap_idx_t	cap,
		unsigned	index,
		l4_cap_idx_t	irq
	)

Parameters

cap	Capability to the L4-VIRTIO host

Get the notification interrupt corresponding to the given index.

Parameters

	index	Index of the interrupt.
[out]	irq	Triggerable for the given index.

Return values

L4_EOK	Success.
L4_ENOSYS	IRQ notification not supported by device.
<0	Other error.

An index is only guaranteed to return an IRQ object when the index is set in one of the device notify index fields. The device must return the same interrupt for a given index as long as the index is in use. If an index disappears as a result of a configuration change and then is reused later, the interrupt is not guaranteed to be the same.

Interrupts must always be rerequested after a device reset.

◆ l4virtio_register_ds()

int l4virtio_register_ds	(	l4_cap_idx_t	cap,
		l4_cap_idx_t	ds_cap,
		l4_uint64_t	base,
		l4_umword_t	offset,
		l4_umword_t	size
	)

Parameters

cap	Capability to the VIRTIO host

Register a shared data space with VIRTIO host.

Parameters

ds_cap	Dataspace capability to register. The lower 8 bits determine the rights mask with which the guest's rights are masked during the registration of the dataspace at the VIRTIO host.
base	VIRTIO guest physical start address of shared memory region
offset	Offset within the data space that is attached to the given `base` in the guest physical memory.
size	Size of the memory region in the guest

Return values

L4_EOK	Operation successful.
-L4_EINVAL	The `ds_cap` capability is invalid, does not refer to a valid dataspace, is not a trusted dataspace if trusted dataspace validation is enabled, or `size` and `offset` specify an invalid region.
-L4_ENOMEM	The limit of dataspaces that can be registered has been reached or no capability slot could be allocated.
-L4_ERANGE	`offset` is lager than the size of the dataspace.
<0	Any error returned by the dataspace when queried for information during setup or any error returned by the region manager from attaching the dataspace.

◆ l4virtio_set_status()

int l4virtio_set_status	(	l4_cap_idx_t	cap,
		unsigned	status
	)

Parameters

cap	Capability to the VIRTIO host

Write the VIRTIO status register.

Parameters

status Status word to write to the VIRTIO status.

Return values

0	on success.

Note: All other registers are accessed via shared memory.

Namespaces

Data Structures

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ l4virtio_config_queue_t

Enumeration Type Documentation

◆ L4_virtio_cmd

◆ L4_virtio_irq_status

◆ L4_virtio_opcodes

◆ L4virtio_device_ids

◆ L4virtio_device_status

◆ L4virtio_feature_bits

Function Documentation

◆ l4virtio_config_queue()

◆ l4virtio_config_queues()

◆ l4virtio_device_config()

◆ l4virtio_device_config_ds()

◆ l4virtio_device_notification_irq()

◆ l4virtio_register_ds()

◆ l4virtio_set_status()