Loading...
Searching...
No Matches
L4 VIRTIO Transport Layer
L4 VIRTIO Interface

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_I2C = 34 , L4VIRTIO_ID_GPIO = 41 , 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

L4_BEGIN_DECLS 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 119 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 110 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 52 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_I2C | I2C device.
L4VIRTIO_ID_GPIO | Gpio device.
L4VIRTIO_ID_SOCK | Unofficial socket device.

Definition at line 62 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 87 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 98 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.

References L4_CV, and L4_NOTHROW.

## l4virtio_config_queues()

L4_BEGIN_DECLS 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 252 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 263 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.

References L4_CV, and L4_NOTHROW.

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

References L4_END_DECLS, and L4_NOTHROW.

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

References L4_CV, and L4_NOTHROW.

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

References L4_CV, and L4_NOTHROW.