Data Structures
struct	_VIRTIO_DEVICE_PROTOCOL

Macros
#define	VIRTIO_SPEC_REVISION(major, minor, revision) ((((major) & 0xFF) << 24) \| (((minor) & 0xFF) << 16) \| ((revision) & 0xFFFF))

#define	VIRTIO_DEVICE_PROTOCOL_GUID

Typedefs
typedef struct _VIRTIO_DEVICE_PROTOCOL	VIRTIO_DEVICE_PROTOCOL

typedef IN UINTN	FieldOffset

typedef IN UINTN IN UINTN	FieldSize

typedef IN UINTN IN UINTN IN UINTN	BufferSize

typedef IN UINTN IN UINTN IN UINTN OUT VOID *	Buffer

typedef IN UINTN IN UINTN IN UINT64	Value

typedef OUT UINT64 *	DeviceFeatures

typedef IN UINT64	Features

typedef IN VRING *	Ring

typedef IN VRING IN UINT64	RingBaseShift

typedef IN UINT16	Index

typedef IN UINT32	Alignment

typedef IN UINT32	PageSize

typedef OUT UINT16 *	QueueNumMax

typedef IN UINT16	QueueSize

typedef OUT UINT8 *	DeviceStatus

typedef EFI_STATUS(EFIAPI *	VIRTIO_ALLOCATE_SHARED )(IN VIRTIO_DEVICE_PROTOCOL This, IN UINTN Pages, IN OUT VOID *HostAddress)

typedef VOID(EFIAPI *	VIRTIO_FREE_SHARED )(IN VIRTIO_DEVICE_PROTOCOL This, IN UINTN Pages, IN VOID HostAddress)

typedef IN VIRTIO_MAP_OPERATION	Operation

typedef IN VIRTIO_MAP_OPERATION IN VOID *	HostAddress

typedef IN VIRTIO_MAP_OPERATION IN VOID IN OUT UINTN *	NumberOfBytes

typedef IN VIRTIO_MAP_OPERATION IN VOID IN OUT UINTN OUT EFI_PHYSICAL_ADDRESS *	DeviceAddress

typedef IN VIRTIO_MAP_OPERATION IN VOID IN OUT UINTN OUT EFI_PHYSICAL_ADDRESS OUT VOID **	Mapping

typedef EFI_STATUS(EFIAPI *	VIRTIO_UNMAP_SHARED )(IN VIRTIO_DEVICE_PROTOCOL This, IN VOID Mapping)

Enumerations
enum	VIRTIO_MAP_OPERATION { VirtioOperationBusMasterRead, VirtioOperationBusMasterWrite, VirtioOperationBusMasterCommonBuffer }

Functions
typedef	EFI_STATUS (EFIAPI VIRTIO_DEVICE_READ)(IN VIRTIO_DEVICE_PROTOCOL This

Variables
EFI_GUID	gVirtioDeviceProtocolGuid

Detailed Description

Virtio Device

DISCLAIMER: the VIRTIO_DEVICE_PROTOCOL introduced here is a work in progress, and should not be used outside of the EDK II tree.

SPDX-License-Identifier: BSD-2-Clause-Patent

Macro Definition Documentation

#define VIRTIO_DEVICE_PROTOCOL_GUID

Value:

{ \
  0xfa920010, 0x6785, 0x4941, {0xb6, 0xec, 0x49, 0x8c, 0x57, 0x9f, 0x16, 0x0a }\
  }

#define VIRTIO_SPEC_REVISION	(	major,
		minor,
		revision
	)	((((major) & 0xFF) << 24) \| (((minor) & 0xFF) << 16) \| ((revision) & 0xFFFF))

Typedef Documentation

typedef IN UINT32 Alignment

typedef IN UINTN IN UINTN IN UINTN OUT VOID* Buffer

typedef IN UINTN IN UINTN IN UINTN BufferSize

typedef IN VIRTIO_MAP_OPERATION IN VOID IN OUT UINTN OUT EFI_PHYSICAL_ADDRESS* DeviceAddress

typedef OUT UINT64* DeviceFeatures

typedef IN UINT8 DeviceStatus

typedef IN UINT64 Features

typedef IN UINTN FieldOffset

typedef IN UINTN IN UINTN FieldSize

typedef IN VIRTIO_MAP_OPERATION IN VOID* HostAddress

typedef IN UINT16 Index

typedef IN VIRTIO_MAP_OPERATION IN VOID IN OUT UINTN OUT EFI_PHYSICAL_ADDRESS OUT VOID** Mapping

typedef IN VIRTIO_MAP_OPERATION IN VOID IN OUT UINTN* NumberOfBytes

typedef IN VIRTIO_MAP_OPERATION Operation

typedef IN UINT32 PageSize

typedef OUT UINT16* QueueNumMax

typedef IN UINT16 QueueSize

typedef IN VRING* Ring

typedef IN VRING IN UINT64 RingBaseShift

typedef IN UINTN IN UINTN IN UINT64 Value

typedef EFI_STATUS(EFIAPI * VIRTIO_ALLOCATE_SHARED)(IN VIRTIO_DEVICE_PROTOCOL *This, IN UINTN Pages, IN OUT VOID **HostAddress)

Allocates pages that are suitable for an VirtioOperationBusMasterCommonBuffer mapping. This means that the buffer allocated by this function supports simultaneous access by both the processor and the bus master. The device address that the bus master uses to access the buffer must be retrieved with a call to VIRTIO_MAP_SHARED.

Parameters

[in]	This	The protocol instance pointer.
[in]	Pages	The number of pages to allocate.
[in,out]	HostAddress	A pointer to store the system memory base address of the allocated range.

Return values

EFI_SUCCESS	The requested memory pages were allocated.
EFI_OUT_OF_RESOURCES	The memory pages could not be allocated.

typedef struct _VIRTIO_DEVICE_PROTOCOL VIRTIO_DEVICE_PROTOCOL

typedef VOID(EFIAPI * VIRTIO_FREE_SHARED)(IN VIRTIO_DEVICE_PROTOCOL *This, IN UINTN Pages, IN VOID *HostAddress)

Frees memory that was allocated with VIRTIO_ALLOCATE_SHARED.

Parameters

[in]	This	The protocol instance pointer.
[in]	Pages	The number of pages to free.
[in]	HostAddress	The system memory base address of the allocated range.

typedef EFI_STATUS(EFIAPI * VIRTIO_UNMAP_SHARED)(IN VIRTIO_DEVICE_PROTOCOL *This, IN VOID *Mapping)

Completes the VIRTIO_MAP_SHARED operation and releases any corresponding resources.

Parameters

[in]	This	The protocol instance pointer.
[in]	Mapping	The mapping token returned from VIRTIO_MAP_SHARED.

Return values

EFI_SUCCESS	The range was unmapped.
EFI_INVALID_PARAMETER	Mapping is not a value that was returned by VIRTIO_MAP_SHARED. Passing an invalid Mapping token can cause undefined behavior.
EFI_DEVICE_ERROR	The data was not committed to the target system memory.

Enumeration Type Documentation

enum VIRTIO_MAP_OPERATION

Enumerator
VirtioOperationBusMasterRead
VirtioOperationBusMasterWrite
VirtioOperationBusMasterCommonBuffer

Function Documentation

typedef EFI_STATUS ( EFIAPI * VIRTIO_MAP_SHARED )

Read a word from the device-specific I/O region of the Virtio Header.

Parameters

[in]	This	This instance of VIRTIO_DEVICE_PROTOCOL
[in]	FieldOffset	Source offset.
[in]	FieldSize	Source field size in bytes, must be in {1, 2, 4, 8}.
[in]	BufferSize	Number of bytes available in the target buffer. Must equal FieldSize.
[out]	Buffer	Target buffer.

Return values

EFI_SUCCESS	The data was read successfully.
EFI_UNSUPPORTED	The underlying IO device doesn't support the provided address offset and read size.
EFI_OUT_OF_RESOURCES	The request could not be completed due to a lack of resources.
EFI_INVALID_PARAMETER	One or more parameters are invalid.

Write a word to the device-specific I/O region of the Virtio Header.

Parameters

[in]	This	This instance of VIRTIO_DEVICE_PROTOCOL
[in]	FieldOffset	Destination offset.
[in]	FieldSize	Destination field size in bytes, must be in {1, 2, 4, 8}.
[out]	Value	Value to write.

Return values

EFI_SUCCESS	The data was written successfully.
EFI_UNSUPPORTED	The underlying IO device doesn't support the provided address offset and write size.
EFI_OUT_OF_RESOURCES	The request could not be completed due to a lack of resources.
EFI_INVALID_PARAMETER	One or more parameters are invalid.

Read the device features field from the Virtio Header.

Parameters

[in]	This	This instance of VIRTIO_DEVICE_PROTOCOL
[out]	DeviceFeatures	The device features field.

Return values

EFI_SUCCESS	The data was read successfully.
EFI_UNSUPPORTED	The underlying IO device doesn't support the provided address offset and read size.
EFI_INVALID_PARAMETER	DeviceFeatures is NULL

Write the guest features field in the Virtio Header.

Parameters

[in]	This	This instance of VIRTIO_DEVICE_PROTOCOL
[in]	Features	The guest features field

Write the queue address field(s) in the Virtio Header.

Parameters

[in]	This	This instance of VIRTIO_DEVICE_PROTOCOL
[in]	Ring	The initialized VRING object to take the addresses from. The caller is responsible for ensuring that on input, all Ring->NumPages pages, starting at Ring->Base, have been successfully mapped with a single call to This->MapSharedBuffer() for CommonBuffer bus master operation.
[in]	RingBaseShift	Adding this value using UINT64 arithmetic to the addresses found in Ring translates them from system memory to bus addresses. The caller shall calculate RingBaseShift as (DeviceAddress - (UINT64)(UINTN)HostAddress), where DeviceAddress and HostAddress (i.e., Ring->Base) were output and input parameters of This->MapSharedBuffer(), respectively.

Return values

EFI_SUCCESS	The data was written successfully.
EFI_UNSUPPORTED	The underlying IO device doesn't support the provided address offset and write size.

Write the queue select field in the Virtio Header.

Writing to the queue select field sets the index of the queue to which operations such as SetQueueAlign and GetQueueNumMax apply.

Parameters

[in]	This	This instance of VIRTIO_DEVICE_PROTOCOL
[in]	Index	The index of the queue to select

Return values

EFI_SUCCESS	The data was written successfully.
EFI_UNSUPPORTED	The underlying IO device doesn't support the provided address offset and write size.

Write the queue notify field in the Virtio Header.

Parameters

[in]	This	This instance of VIRTIO_DEVICE_PROTOCOL
[in]	Address	The 32-bit Queue Notify field

Return values

EFI_SUCCESS	The data was written successfully.
EFI_UNSUPPORTED	The underlying IO device doesn't support the provided address offset and write size.

Write the queue alignment field in the Virtio Header.

The queue to which the alignment applies is selected by the Queue Select field.

Note: This operation is not implemented by the VirtIo over PCI. The PCI implementation of this protocol returns EFI_SUCCESS.

Parameters

[in]	This	This instance of VIRTIO_DEVICE_PROTOCOL
[in]	Alignment	The alignment boundary of the Used Ring in bytes. Must be a power of 2.

Return values

EFI_SUCCESS	The data was written successfully.
EFI_UNSUPPORTED	The underlying IO device doesn't support the provided address offset and write size.

Write the guest page size.

Note: This operation is not implemented by the VirtIo over PCI. The PCI implementation of this protocol returns EFI_SUCCESS.

Parameters

[in]	This	This instance of VIRTIO_DEVICE_PROTOCOL
[in]	PageSize	Size of the Guest page in bytes. Must be a power of 2.

Return values

EFI_SUCCESS	The data was written successfully.
EFI_UNSUPPORTED	The underlying IO device doesn't support the provided address offset and write size.

Get the size of the virtqueue selected by the queue select field.

See Virtio spec Section 2.3

Parameters

[in]	This	This instance of VIRTIO_DEVICE_PROTOCOL
[out]	QueueNumMax	The size of the virtqueue in bytes. Always a power of 2.

Return values

EFI_SUCCESS	The data was read successfully.
EFI_UNSUPPORTED	The underlying IO device doesn't support the provided address offset and read size.
EFI_INVALID_PARAMETER	QueueNumMax is NULL

Write to the QueueNum field in the Virtio Header.

This function only applies to Virtio-MMIO and may be a stub for other implementations. See Virtio Spec appendix X.

Parameters

[in]	This	This instance of VIRTIO_DEVICE_PROTOCOL
[in]	QueueSize	The number of elements in the queue.

Return values

EFI_SUCCESS	The data was written successfully.
EFI_UNSUPPORTED	The underlying IO device doesn't support the provided address offset and write size.

Get the DeviceStatus field from the Virtio Header.

Parameters

[in]	This	This instance of VIRTIO_DEVICE_PROTOCOL
[out]	DeviceStatus	The 8-bit value for the Device status field

Return values

EFI_SUCCESS	The data was read successfully.
EFI_UNSUPPORTED	The underlying IO device doesn't support the provided address offset and read size.
EFI_INVALID_PARAMETER	DeviceStatus is NULL

Write the DeviceStatus field in the Virtio Header.

Parameters

[in]	This	This instance of VIRTIO_DEVICE_PROTOCOL
[in]	DeviceStatus	The 8-bit value for the Device status field

Return values

EFI_SUCCESS	The data was written successfully.
EFI_UNSUPPORTED	The underlying IO device doesn't support the provided address offset and write size.

Provides the virtio device address required to access system memory from a DMA bus master.

The interface follows the same usage pattern as defined in UEFI spec 2.6 (Section 13.2 PCI Root Bridge I/O Protocol)

Parameters

[in]	This	The protocol instance pointer.
[in]	Operation	Indicates if the bus master is going to read or write to system memory.
[in]	HostAddress	The system memory address to map to shared buffer address.
[in,out]	NumberOfBytes	On input the number of bytes to map. On output the number of bytes that were mapped.
[out]	DeviceAddress	The resulting shared map address for the bus master to access the hosts HostAddress.
[out]	Mapping	A resulting token to pass to VIRTIO_UNMAP_SHARED.

Return values

EFI_SUCCESS	The range was mapped for the returned NumberOfBytes.
EFI_UNSUPPORTED	The HostAddress cannot be mapped as a common buffer.
EFI_INVALID_PARAMETER	One or more parameters are invalid.
EFI_OUT_OF_RESOURCES	The request could not be completed due to a lack of resources.
EFI_DEVICE_ERROR	The system hardware could not map the requested address.

Variable Documentation

EFI_GUID gVirtioDeviceProtocolGuid

Data Structures

Macros

Typedefs

Enumerations

Functions

Variables

Detailed Description

Macro Definition Documentation

Typedef Documentation

Enumeration Type Documentation

Function Documentation

Variable Documentation