878115261a
The patch extends VIRTIO_DEVICE_PROTOCOL to provide the following new member functions: - AllocateSharedPages : allocate a memory region suitable for sharing between guest and hypervisor (e.g ring buffer). - FreeSharedPages: free the memory allocated using AllocateSharedPages (). - MapSharedBuffer: map a host address to device address suitable to share with device for bus master operations. - UnmapSharedBuffer: unmap the device address obtained through the MapSharedBuffer(). We're free to extend the protocol structure without changing the protocol GUID, or bumping any protocol version fields (of which we currently have none), because VIRTIO_DEVICE_PROTOCOL is internal to edk2 by design -- see the disclaimers in "VirtioDevice.h". The patch implements Laszlo's recommendation [1]. [1] http://mid.mail-archive.com/841bec5f-6f6e-8b1f-25ba-0fd37a915b72@redhat.com Suggested-by: Laszlo Ersek <lersek@redhat.com> Cc: Ard Biesheuvel <ard.biesheuvel@linaro.org> Cc: Jordan Justen <jordan.l.justen@intel.com> Cc: Tom Lendacky <thomas.lendacky@amd.com> Cc: Laszlo Ersek <lersek@redhat.com> Contributed-under: TianoCore Contribution Agreement 1.1 Signed-off-by: Brijesh Singh <brijesh.singh@amd.com> Reviewed-by: Laszlo Ersek <lersek@redhat.com> Regression-tested-by: Laszlo Ersek <lersek@redhat.com>
512 lines
16 KiB
C
512 lines
16 KiB
C
/** @file
|
|
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.
|
|
|
|
Copyright (c) 2013, ARM Ltd. All rights reserved.<BR>
|
|
Copyright (c) 2017, AMD Inc, All rights reserved.<BR>
|
|
|
|
This program and the accompanying materials are licensed and made available
|
|
under the terms and conditions of the BSD License which accompanies this
|
|
distribution. The full text of the license may be found at
|
|
http://opensource.org/licenses/bsd-license.php
|
|
|
|
THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, WITHOUT
|
|
WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
|
|
|
|
**/
|
|
|
|
#ifndef __VIRTIO_DEVICE_H__
|
|
#define __VIRTIO_DEVICE_H__
|
|
|
|
#include <IndustryStandard/Virtio.h>
|
|
|
|
//
|
|
// VirtIo Specification Revision: Major[31:24].Minor[23:16].Revision[15:0]
|
|
//
|
|
#define VIRTIO_SPEC_REVISION(major,minor,revision) \
|
|
((((major) & 0xFF) << 24) | (((minor) & 0xFF) << 16) | ((revision) & 0xFFFF))
|
|
|
|
#define VIRTIO_DEVICE_PROTOCOL_GUID { \
|
|
0xfa920010, 0x6785, 0x4941, {0xb6, 0xec, 0x49, 0x8c, 0x57, 0x9f, 0x16, 0x0a }\
|
|
}
|
|
|
|
typedef struct _VIRTIO_DEVICE_PROTOCOL VIRTIO_DEVICE_PROTOCOL;
|
|
|
|
//
|
|
// VIRTIO Operation for VIRTIO_MAP_SHARED
|
|
//
|
|
typedef enum {
|
|
//
|
|
// A read operation from system memory by a bus master
|
|
//
|
|
VirtioOperationBusMasterRead,
|
|
//
|
|
// A write operation to system memory by a bus master
|
|
//
|
|
VirtioOperationBusMasterWrite,
|
|
//
|
|
// Provides both read and write access to system memory by both the
|
|
// processor and a bus master
|
|
//
|
|
VirtioOperationBusMasterCommonBuffer,
|
|
} VIRTIO_MAP_OPERATION;
|
|
|
|
/**
|
|
|
|
Read a word from the device-specific I/O region of the Virtio Header.
|
|
|
|
@param[in] This This instance of VIRTIO_DEVICE_PROTOCOL
|
|
|
|
@param[in] FieldOffset Source offset.
|
|
|
|
@param[in] FieldSize Source field size in bytes, must be in {1, 2, 4, 8}.
|
|
|
|
@param[in] BufferSize Number of bytes available in the target buffer. Must
|
|
equal FieldSize.
|
|
|
|
@param[out] Buffer Target buffer.
|
|
|
|
@retval EFI_SUCCESS The data was read successfully.
|
|
@retval EFI_UNSUPPORTED The underlying IO device doesn't support the
|
|
provided address offset and read size.
|
|
@retval EFI_OUT_OF_RESOURCES The request could not be completed due to a
|
|
lack of resources.
|
|
@retval EFI_INVALID_PARAMETER One or more parameters are invalid.
|
|
|
|
**/
|
|
typedef
|
|
EFI_STATUS
|
|
(EFIAPI *VIRTIO_DEVICE_READ) (
|
|
IN VIRTIO_DEVICE_PROTOCOL *This,
|
|
IN UINTN FieldOffset,
|
|
IN UINTN FieldSize,
|
|
IN UINTN BufferSize,
|
|
OUT VOID *Buffer
|
|
);
|
|
|
|
/**
|
|
|
|
Write a word to the device-specific I/O region of the Virtio Header.
|
|
|
|
@param[in] This This instance of VIRTIO_DEVICE_PROTOCOL
|
|
|
|
@param[in] FieldOffset Destination offset.
|
|
|
|
@param[in] FieldSize Destination field size in bytes,
|
|
must be in {1, 2, 4, 8}.
|
|
|
|
@param[out] Value Value to write.
|
|
|
|
@retval EFI_SUCCESS The data was written successfully.
|
|
@retval EFI_UNSUPPORTED The underlying IO device doesn't support the
|
|
provided address offset and write size.
|
|
@retval EFI_OUT_OF_RESOURCES The request could not be completed due to a
|
|
lack of resources.
|
|
@retval EFI_INVALID_PARAMETER One or more parameters are invalid.
|
|
|
|
**/
|
|
typedef
|
|
EFI_STATUS
|
|
(EFIAPI *VIRTIO_DEVICE_WRITE) (
|
|
IN VIRTIO_DEVICE_PROTOCOL *This,
|
|
IN UINTN FieldOffset,
|
|
IN UINTN FieldSize,
|
|
IN UINT64 Value
|
|
);
|
|
|
|
/**
|
|
Read the device features field from the Virtio Header.
|
|
|
|
@param[in] This This instance of VIRTIO_DEVICE_PROTOCOL
|
|
|
|
@param[out] DeviceFeatures The device features field.
|
|
|
|
@retval EFI_SUCCESS The data was read successfully.
|
|
@retval EFI_UNSUPPORTED The underlying IO device doesn't support the
|
|
provided address offset and read size.
|
|
@retval EFI_INVALID_PARAMETER DeviceFeatures is NULL
|
|
**/
|
|
typedef
|
|
EFI_STATUS
|
|
(EFIAPI *VIRTIO_GET_DEVICE_FEATURES) (
|
|
IN VIRTIO_DEVICE_PROTOCOL *This,
|
|
OUT UINT64 *DeviceFeatures
|
|
);
|
|
|
|
/**
|
|
Write the guest features field in the Virtio Header.
|
|
|
|
@param[in] This This instance of VIRTIO_DEVICE_PROTOCOL
|
|
|
|
@param[in] Features The guest features field
|
|
|
|
**/
|
|
typedef
|
|
EFI_STATUS
|
|
(EFIAPI *VIRTIO_SET_GUEST_FEATURES) (
|
|
IN VIRTIO_DEVICE_PROTOCOL *This,
|
|
IN UINT64 Features
|
|
);
|
|
|
|
/**
|
|
Write the queue address field(s) in the Virtio Header.
|
|
|
|
@param[in] This This instance of VIRTIO_DEVICE_PROTOCOL
|
|
|
|
@param[in] Ring The initialized VRING object to take the
|
|
addresses from.
|
|
|
|
@retval EFI_SUCCESS The data was written successfully.
|
|
@retval EFI_UNSUPPORTED The underlying IO device doesn't support the
|
|
provided address offset and write size.
|
|
**/
|
|
typedef
|
|
EFI_STATUS
|
|
(EFIAPI *VIRTIO_SET_QUEUE_ADDRESS) (
|
|
IN VIRTIO_DEVICE_PROTOCOL *This,
|
|
IN VRING *Ring
|
|
);
|
|
|
|
/**
|
|
|
|
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.
|
|
|
|
@param[in] This This instance of VIRTIO_DEVICE_PROTOCOL
|
|
|
|
@param[in] Index The index of the queue to select
|
|
|
|
@retval EFI_SUCCESS The data was written successfully.
|
|
@retval EFI_UNSUPPORTED The underlying IO device doesn't support the
|
|
provided address offset and write size.
|
|
**/
|
|
typedef
|
|
EFI_STATUS
|
|
(EFIAPI *VIRTIO_SET_QUEUE_SEL) (
|
|
IN VIRTIO_DEVICE_PROTOCOL *This,
|
|
IN UINT16 Index
|
|
);
|
|
|
|
/**
|
|
|
|
Write the queue notify field in the Virtio Header.
|
|
|
|
@param[in] This This instance of VIRTIO_DEVICE_PROTOCOL
|
|
|
|
@param[in] Address The 32-bit Queue Notify field
|
|
|
|
@retval EFI_SUCCESS The data was written successfully.
|
|
@retval EFI_UNSUPPORTED The underlying IO device doesn't support the
|
|
provided address offset and write size.
|
|
**/
|
|
typedef
|
|
EFI_STATUS
|
|
(EFIAPI *VIRTIO_SET_QUEUE_NOTIFY) (
|
|
IN VIRTIO_DEVICE_PROTOCOL *This,
|
|
IN UINT16 Index
|
|
);
|
|
|
|
/**
|
|
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.
|
|
|
|
@param[in] This This instance of VIRTIO_DEVICE_PROTOCOL
|
|
|
|
@param[in] Alignment The alignment boundary of the Used Ring in bytes.
|
|
Must be a power of 2.
|
|
|
|
@retval EFI_SUCCESS The data was written successfully.
|
|
@retval EFI_UNSUPPORTED The underlying IO device doesn't support the
|
|
provided address offset and write size.
|
|
**/
|
|
typedef
|
|
EFI_STATUS
|
|
(EFIAPI *VIRTIO_SET_QUEUE_ALIGN) (
|
|
IN VIRTIO_DEVICE_PROTOCOL *This,
|
|
IN UINT32 Alignment
|
|
);
|
|
|
|
/**
|
|
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.
|
|
|
|
@param[in] This This instance of VIRTIO_DEVICE_PROTOCOL
|
|
|
|
@param[in] PageSize Size of the Guest page in bytes.
|
|
Must be a power of 2.
|
|
|
|
@retval EFI_SUCCESS The data was written successfully.
|
|
@retval EFI_UNSUPPORTED The underlying IO device doesn't support the
|
|
provided address offset and write size.
|
|
**/
|
|
typedef
|
|
EFI_STATUS
|
|
(EFIAPI *VIRTIO_SET_PAGE_SIZE) (
|
|
IN VIRTIO_DEVICE_PROTOCOL *This,
|
|
IN UINT32 PageSize
|
|
);
|
|
|
|
/**
|
|
|
|
Get the size of the virtqueue selected by the queue select field.
|
|
|
|
See Virtio spec Section 2.3
|
|
|
|
@param[in] This This instance of VIRTIO_DEVICE_PROTOCOL
|
|
|
|
@param[out] QueueNumMax The size of the virtqueue in bytes.
|
|
Always a power of 2.
|
|
|
|
@retval EFI_SUCCESS The data was read successfully.
|
|
@retval EFI_UNSUPPORTED The underlying IO device doesn't support the
|
|
provided address offset and read size.
|
|
@retval EFI_INVALID_PARAMETER QueueNumMax is NULL
|
|
**/
|
|
typedef
|
|
EFI_STATUS
|
|
(EFIAPI *VIRTIO_GET_QUEUE_NUM_MAX) (
|
|
IN VIRTIO_DEVICE_PROTOCOL *This,
|
|
OUT UINT16 *QueueNumMax
|
|
);
|
|
|
|
/**
|
|
|
|
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.
|
|
|
|
@param[in] This This instance of VIRTIO_DEVICE_PROTOCOL
|
|
|
|
@param[in] QueueSize The number of elements in the queue.
|
|
|
|
@retval EFI_SUCCESS The data was written successfully.
|
|
@retval EFI_UNSUPPORTED The underlying IO device doesn't support the
|
|
provided address offset and write size.
|
|
**/
|
|
typedef
|
|
EFI_STATUS
|
|
(EFIAPI *VIRTIO_SET_QUEUE_NUM) (
|
|
IN VIRTIO_DEVICE_PROTOCOL *This,
|
|
IN UINT16 QueueSize
|
|
);
|
|
|
|
/**
|
|
|
|
Get the DeviceStatus field from the Virtio Header.
|
|
|
|
@param[in] This This instance of VIRTIO_DEVICE_PROTOCOL
|
|
|
|
@param[out] DeviceStatus The 8-bit value for the Device status field
|
|
|
|
@retval EFI_SUCCESS The data was read successfully.
|
|
@retval EFI_UNSUPPORTED The underlying IO device doesn't support the
|
|
provided address offset and read size.
|
|
@retval EFI_INVALID_PARAMETER DeviceStatus is NULL
|
|
**/
|
|
typedef
|
|
EFI_STATUS
|
|
(EFIAPI *VIRTIO_GET_DEVICE_STATUS) (
|
|
IN VIRTIO_DEVICE_PROTOCOL *This,
|
|
OUT UINT8 *DeviceStatus
|
|
);
|
|
|
|
/**
|
|
|
|
Write the DeviceStatus field in the Virtio Header.
|
|
|
|
@param[in] This This instance of VIRTIO_DEVICE_PROTOCOL
|
|
|
|
@param[in] DeviceStatus The 8-bit value for the Device status field
|
|
|
|
@retval EFI_SUCCESS The data was written successfully.
|
|
@retval EFI_UNSUPPORTED The underlying IO device doesn't support the
|
|
provided address offset and write size.
|
|
**/
|
|
typedef
|
|
EFI_STATUS
|
|
(EFIAPI *VIRTIO_SET_DEVICE_STATUS) (
|
|
IN VIRTIO_DEVICE_PROTOCOL *This,
|
|
IN UINT8 DeviceStatus
|
|
);
|
|
|
|
/**
|
|
|
|
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.
|
|
|
|
@param[in] This The protocol instance pointer.
|
|
|
|
@param[in] Pages The number of pages to allocate.
|
|
|
|
@param[in,out] HostAddress A pointer to store the system memory base
|
|
address of the allocated range.
|
|
|
|
@retval EFI_SUCCESS The requested memory pages were allocated.
|
|
@retval EFI_OUT_OF_RESOURCES The memory pages could not be allocated.
|
|
|
|
**/
|
|
typedef
|
|
EFI_STATUS
|
|
(EFIAPI *VIRTIO_ALLOCATE_SHARED)(
|
|
IN VIRTIO_DEVICE_PROTOCOL *This,
|
|
IN UINTN Pages,
|
|
IN OUT VOID **HostAddress
|
|
);
|
|
|
|
/**
|
|
Frees memory that was allocated with VIRTIO_ALLOCATE_SHARED.
|
|
|
|
@param[in] This The protocol instance pointer.
|
|
|
|
@param[in] Pages The number of pages to free.
|
|
|
|
@param[in] HostAddress The system memory base address of the allocated
|
|
range.
|
|
|
|
**/
|
|
typedef
|
|
VOID
|
|
(EFIAPI *VIRTIO_FREE_SHARED)(
|
|
IN VIRTIO_DEVICE_PROTOCOL *This,
|
|
IN UINTN Pages,
|
|
IN VOID *HostAddress
|
|
);
|
|
|
|
/**
|
|
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)
|
|
|
|
@param[in] This The protocol instance pointer.
|
|
|
|
@param[in] Operation Indicates if the bus master is going to
|
|
read or write to system memory.
|
|
|
|
@param[in] HostAddress The system memory address to map to shared
|
|
buffer address.
|
|
|
|
@param[in,out] NumberOfBytes On input the number of bytes to map.
|
|
On output the number of bytes that were
|
|
mapped.
|
|
|
|
@param[out] DeviceAddress The resulting shared map address for the
|
|
bus master to access the hosts HostAddress.
|
|
|
|
@param[out] Mapping A resulting token to pass to
|
|
VIRTIO_UNMAP_SHARED.
|
|
|
|
@retval EFI_SUCCESS The range was mapped for the returned
|
|
NumberOfBytes.
|
|
@retval EFI_UNSUPPORTED The HostAddress cannot be mapped as a
|
|
common buffer.
|
|
@retval EFI_INVALID_PARAMETER One or more parameters are invalid.
|
|
@retval EFI_OUT_OF_RESOURCES The request could not be completed due to
|
|
a lack of resources.
|
|
@retval EFI_DEVICE_ERROR The system hardware could not map the
|
|
requested address.
|
|
**/
|
|
|
|
typedef
|
|
EFI_STATUS
|
|
(EFIAPI *VIRTIO_MAP_SHARED) (
|
|
IN VIRTIO_DEVICE_PROTOCOL *This,
|
|
IN VIRTIO_MAP_OPERATION Operation,
|
|
IN VOID *HostAddress,
|
|
IN OUT UINTN *NumberOfBytes,
|
|
OUT EFI_PHYSICAL_ADDRESS *DeviceAddress,
|
|
OUT VOID **Mapping
|
|
);
|
|
|
|
/**
|
|
Completes the VIRTIO_MAP_SHARED operation and releases any corresponding
|
|
resources.
|
|
|
|
@param[in] This The protocol instance pointer.
|
|
|
|
@param[in] Mapping The mapping token returned from
|
|
VIRTIO_MAP_SHARED.
|
|
|
|
@retval EFI_SUCCESS The range was unmapped.
|
|
@retval EFI_INVALID_PARAMETER Mapping is not a value that was returned by
|
|
VIRTIO_MAP_SHARED. Passing an invalid Mapping
|
|
token can cause undefined behavior.
|
|
@retval EFI_DEVICE_ERROR The data was not committed to the target
|
|
system memory.
|
|
**/
|
|
typedef
|
|
EFI_STATUS
|
|
(EFIAPI *VIRTIO_UNMAP_SHARED)(
|
|
IN VIRTIO_DEVICE_PROTOCOL *This,
|
|
IN VOID *Mapping
|
|
);
|
|
|
|
///
|
|
/// This protocol provides an abstraction over the VirtIo transport layer
|
|
///
|
|
/// DISCLAIMER: this protocol is a work in progress, and should not be used
|
|
/// outside of the EDK II tree.
|
|
///
|
|
struct _VIRTIO_DEVICE_PROTOCOL {
|
|
//
|
|
// VirtIo Specification Revision encoded with VIRTIO_SPEC_REVISION()
|
|
//
|
|
UINT32 Revision;
|
|
//
|
|
// From the Virtio Spec
|
|
//
|
|
INT32 SubSystemDeviceId;
|
|
|
|
VIRTIO_GET_DEVICE_FEATURES GetDeviceFeatures;
|
|
VIRTIO_SET_GUEST_FEATURES SetGuestFeatures;
|
|
|
|
VIRTIO_SET_QUEUE_ADDRESS SetQueueAddress;
|
|
|
|
VIRTIO_SET_QUEUE_SEL SetQueueSel;
|
|
|
|
VIRTIO_SET_QUEUE_NOTIFY SetQueueNotify;
|
|
|
|
VIRTIO_SET_QUEUE_ALIGN SetQueueAlign;
|
|
VIRTIO_SET_PAGE_SIZE SetPageSize;
|
|
|
|
VIRTIO_GET_QUEUE_NUM_MAX GetQueueNumMax;
|
|
VIRTIO_SET_QUEUE_NUM SetQueueNum;
|
|
|
|
VIRTIO_GET_DEVICE_STATUS GetDeviceStatus;
|
|
VIRTIO_SET_DEVICE_STATUS SetDeviceStatus;
|
|
|
|
//
|
|
// Functions to read/write Device Specific headers
|
|
//
|
|
VIRTIO_DEVICE_WRITE WriteDevice;
|
|
VIRTIO_DEVICE_READ ReadDevice;
|
|
|
|
//
|
|
// Functions to allocate, free, map and unmap shared buffer
|
|
//
|
|
VIRTIO_ALLOCATE_SHARED AllocateSharedPages;
|
|
VIRTIO_FREE_SHARED FreeSharedPages;
|
|
VIRTIO_MAP_SHARED MapSharedBuffer;
|
|
VIRTIO_UNMAP_SHARED UnmapSharedBuffer;
|
|
};
|
|
|
|
extern EFI_GUID gVirtioDeviceProtocolGuid;
|
|
|
|
#endif
|