[mirror_edk2.git] / OvmfPkg / Include / Protocol / VirtioDevice.h

/** @file\r
  Virtio Device\r
\r
  DISCLAIMER: the VIRTIO_DEVICE_PROTOCOL introduced here is a work in progress,\r
  and should not be used outside of the EDK II tree.\r
\r
  Copyright (c) 2013, ARM Ltd. All rights reserved.<BR>\r
  Copyright (c) 2017, AMD Inc, All rights reserved.<BR>\r
\r
  SPDX-License-Identifier: BSD-2-Clause-Patent\r
\r
**/\r
\r
#ifndef __VIRTIO_DEVICE_H__\r
#define __VIRTIO_DEVICE_H__\r
\r
#include <IndustryStandard/Virtio.h>\r
\r
//\r
// VirtIo Specification Revision: Major[31:24].Minor[23:16].Revision[15:0]\r
//\r
#define VIRTIO_SPEC_REVISION(major, minor, revision) \\r
  ((((major) & 0xFF) << 24) | (((minor) & 0xFF) << 16) | ((revision) & 0xFFFF))\r
\r
#define VIRTIO_DEVICE_PROTOCOL_GUID  {\\r
  0xfa920010, 0x6785, 0x4941, {0xb6, 0xec, 0x49, 0x8c, 0x57, 0x9f, 0x16, 0x0a }\\r
  }\r
\r
typedef struct _VIRTIO_DEVICE_PROTOCOL VIRTIO_DEVICE_PROTOCOL;\r
\r
//\r
// VIRTIO Operation for VIRTIO_MAP_SHARED\r
//\r
typedef enum {\r
  //\r
  // A read operation from system memory by a bus master\r
  //\r
  VirtioOperationBusMasterRead,\r
  //\r
  // A write operation to system memory by a bus master\r
  //\r
  VirtioOperationBusMasterWrite,\r
  //\r
  // Provides both read and write access to system memory by both the\r
  // processor and a bus master\r
  //\r
  VirtioOperationBusMasterCommonBuffer,\r
} VIRTIO_MAP_OPERATION;\r
\r
/**\r
\r
  Read a word from the device-specific I/O region of the Virtio Header.\r
\r
  @param[in] This         This instance of VIRTIO_DEVICE_PROTOCOL\r
\r
  @param[in] FieldOffset  Source offset.\r
\r
  @param[in] FieldSize    Source field size in bytes, must be in {1, 2, 4, 8}.\r
\r
  @param[in] BufferSize   Number of bytes available in the target buffer. Must\r
                          equal FieldSize.\r
\r
  @param[out] Buffer      Target buffer.\r
\r
  @retval EFI_SUCCESS           The data was read successfully.\r
  @retval EFI_UNSUPPORTED       The underlying IO device doesn't support the\r
                                provided address offset and read size.\r
  @retval EFI_OUT_OF_RESOURCES  The request could not be completed due to a\r
                                lack of resources.\r
  @retval EFI_INVALID_PARAMETER One or more parameters are invalid.\r
\r
**/\r
typedef\r
EFI_STATUS\r
(EFIAPI *VIRTIO_DEVICE_READ)(\r
  IN  VIRTIO_DEVICE_PROTOCOL *This,\r
  IN  UINTN                  FieldOffset,\r
  IN  UINTN                  FieldSize,\r
  IN  UINTN                  BufferSize,\r
  OUT VOID                   *Buffer\r
  );\r
\r
/**\r
\r
  Write a word to the device-specific I/O region of the Virtio Header.\r
\r
  @param[in] This         This instance of VIRTIO_DEVICE_PROTOCOL\r
\r
  @param[in] FieldOffset  Destination offset.\r
\r
  @param[in] FieldSize    Destination field size in bytes,\r
                          must be in {1, 2, 4, 8}.\r
\r
  @param[out] Value       Value to write.\r
\r
  @retval EFI_SUCCESS           The data was written successfully.\r
  @retval EFI_UNSUPPORTED       The underlying IO device doesn't support the\r
                                provided address offset and write size.\r
  @retval EFI_OUT_OF_RESOURCES  The request could not be completed due to a\r
                                lack of resources.\r
  @retval EFI_INVALID_PARAMETER One or more parameters are invalid.\r
\r
**/\r
typedef\r
EFI_STATUS\r
(EFIAPI *VIRTIO_DEVICE_WRITE)(\r
  IN VIRTIO_DEVICE_PROTOCOL *This,\r
  IN UINTN                  FieldOffset,\r
  IN UINTN                  FieldSize,\r
  IN UINT64                 Value\r
  );\r
\r
/**\r
  Read the device features field from the Virtio Header.\r
\r
  @param[in] This                 This instance of VIRTIO_DEVICE_PROTOCOL\r
\r
  @param[out] DeviceFeatures      The device features field.\r
\r
  @retval EFI_SUCCESS             The data was read successfully.\r
  @retval EFI_UNSUPPORTED         The underlying IO device doesn't support the\r
                                  provided address offset and read size.\r
  @retval EFI_INVALID_PARAMETER   DeviceFeatures is NULL\r
**/\r
typedef\r
EFI_STATUS\r
(EFIAPI *VIRTIO_GET_DEVICE_FEATURES)(\r
  IN VIRTIO_DEVICE_PROTOCOL *This,\r
  OUT UINT64                *DeviceFeatures\r
  );\r
\r
/**\r
  Write the guest features field in the Virtio Header.\r
\r
  @param[in] This         This instance of VIRTIO_DEVICE_PROTOCOL\r
\r
  @param[in] Features     The guest features field\r
\r
**/\r
typedef\r
EFI_STATUS\r
(EFIAPI *VIRTIO_SET_GUEST_FEATURES)(\r
  IN VIRTIO_DEVICE_PROTOCOL  *This,\r
  IN UINT64                   Features\r
  );\r
\r
/**\r
  Write the queue address field(s) in the Virtio Header.\r
\r
  @param[in] This             This instance of VIRTIO_DEVICE_PROTOCOL\r
\r
  @param[in] Ring             The initialized VRING object to take the\r
                              addresses from. The caller is responsible for\r
                              ensuring that on input, all Ring->NumPages pages,\r
                              starting at Ring->Base, have been successfully\r
                              mapped with a single call to\r
                              This->MapSharedBuffer() for CommonBuffer bus\r
                              master operation.\r
\r
  @param[in] RingBaseShift    Adding this value using UINT64 arithmetic to the\r
                              addresses found in Ring translates them from\r
                              system memory to bus addresses. The caller shall\r
                              calculate RingBaseShift as\r
                              (DeviceAddress - (UINT64)(UINTN)HostAddress),\r
                              where DeviceAddress and HostAddress (i.e.,\r
                              Ring->Base) were output and input parameters of\r
                              This->MapSharedBuffer(), respectively.\r
\r
  @retval EFI_SUCCESS         The data was written successfully.\r
  @retval EFI_UNSUPPORTED     The underlying IO device doesn't support the\r
                              provided address offset and write size.\r
**/\r
typedef\r
EFI_STATUS\r
(EFIAPI *VIRTIO_SET_QUEUE_ADDRESS)(\r
  IN VIRTIO_DEVICE_PROTOCOL  *This,\r
  IN VRING                   *Ring,\r
  IN UINT64                  RingBaseShift\r
  );\r
\r
/**\r
\r
  Write the queue select field in the Virtio Header.\r
\r
  Writing to the queue select field sets the index of the queue to which\r
  operations such as SetQueueAlign and GetQueueNumMax apply.\r
\r
  @param[in] This         This instance of VIRTIO_DEVICE_PROTOCOL\r
\r
  @param[in] Index        The index of the queue to select\r
\r
  @retval EFI_SUCCESS         The data was written successfully.\r
  @retval EFI_UNSUPPORTED     The underlying IO device doesn't support the\r
                              provided address offset and write size.\r
**/\r
typedef\r
EFI_STATUS\r
(EFIAPI *VIRTIO_SET_QUEUE_SEL)(\r
  IN VIRTIO_DEVICE_PROTOCOL  *This,\r
  IN UINT16                   Index\r
  );\r
\r
/**\r
\r
  Write the queue notify field in the Virtio Header.\r
\r
  @param[in] This         This instance of VIRTIO_DEVICE_PROTOCOL\r
\r
  @param[in] Address      The 32-bit Queue Notify field\r
\r
  @retval EFI_SUCCESS         The data was written successfully.\r
  @retval EFI_UNSUPPORTED     The underlying IO device doesn't support the\r
                              provided address offset and write size.\r
**/\r
typedef\r
EFI_STATUS\r
(EFIAPI *VIRTIO_SET_QUEUE_NOTIFY)(\r
  IN VIRTIO_DEVICE_PROTOCOL  *This,\r
  IN UINT16                   Index\r
  );\r
\r
/**\r
  Write the queue alignment field in the Virtio Header.\r
\r
  The queue to which the alignment applies is selected by the Queue Select\r
  field.\r
\r
  Note: This operation is not implemented by the VirtIo over PCI. The PCI\r
  implementation of this protocol returns EFI_SUCCESS.\r
\r
  @param[in] This         This instance of VIRTIO_DEVICE_PROTOCOL\r
\r
  @param[in] Alignment    The alignment boundary of the Used Ring in bytes.\r
                          Must be a power of 2.\r
\r
  @retval EFI_SUCCESS         The data was written successfully.\r
  @retval EFI_UNSUPPORTED     The underlying IO device doesn't support the\r
                              provided address offset and write size.\r
**/\r
typedef\r
EFI_STATUS\r
(EFIAPI *VIRTIO_SET_QUEUE_ALIGN)(\r
  IN VIRTIO_DEVICE_PROTOCOL  *This,\r
  IN UINT32                   Alignment\r
  );\r
\r
/**\r
  Write the guest page size.\r
\r
  Note: This operation is not implemented by the VirtIo over PCI. The PCI\r
  implementation of this protocol returns EFI_SUCCESS.\r
\r
  @param[in] This             This instance of VIRTIO_DEVICE_PROTOCOL\r
\r
  @param[in] PageSize         Size of the Guest page in bytes.\r
                              Must be a power of 2.\r
\r
  @retval EFI_SUCCESS         The data was written successfully.\r
  @retval EFI_UNSUPPORTED     The underlying IO device doesn't support the\r
                              provided address offset and write size.\r
**/\r
typedef\r
EFI_STATUS\r
(EFIAPI *VIRTIO_SET_PAGE_SIZE)(\r
  IN VIRTIO_DEVICE_PROTOCOL  *This,\r
  IN UINT32                   PageSize\r
  );\r
\r
/**\r
\r
  Get the size of the virtqueue selected by the queue select field.\r
\r
  See Virtio spec Section 2.3\r
\r
  @param[in] This                 This instance of VIRTIO_DEVICE_PROTOCOL\r
\r
  @param[out] QueueNumMax         The size of the virtqueue in bytes.\r
                                  Always a power of 2.\r
\r
  @retval EFI_SUCCESS             The data was read successfully.\r
  @retval EFI_UNSUPPORTED         The underlying IO device doesn't support the\r
                                  provided address offset and read size.\r
  @retval EFI_INVALID_PARAMETER   QueueNumMax is NULL\r
**/\r
typedef\r
EFI_STATUS\r
(EFIAPI *VIRTIO_GET_QUEUE_NUM_MAX)(\r
  IN  VIRTIO_DEVICE_PROTOCOL  *This,\r
  OUT UINT16                  *QueueNumMax\r
  );\r
\r
/**\r
\r
  Write to the QueueNum field in the Virtio Header.\r
\r
  This function only applies to Virtio-MMIO and may be a stub for other\r
  implementations. See Virtio Spec appendix X.\r
\r
  @param[in] This         This instance of VIRTIO_DEVICE_PROTOCOL\r
\r
  @param[in] QueueSize    The number of elements in the queue.\r
\r
  @retval EFI_SUCCESS         The data was written successfully.\r
  @retval EFI_UNSUPPORTED     The underlying IO device doesn't support the\r
                              provided address offset and write size.\r
**/\r
typedef\r
EFI_STATUS\r
(EFIAPI *VIRTIO_SET_QUEUE_NUM)(\r
  IN VIRTIO_DEVICE_PROTOCOL  *This,\r
  IN UINT16                   QueueSize\r
  );\r
\r
/**\r
\r
  Get the DeviceStatus field from the Virtio Header.\r
\r
  @param[in] This                 This instance of VIRTIO_DEVICE_PROTOCOL\r
\r
  @param[out] DeviceStatus        The 8-bit value for the Device status field\r
\r
  @retval EFI_SUCCESS             The data was read successfully.\r
  @retval EFI_UNSUPPORTED         The underlying IO device doesn't support the\r
                                  provided address offset and read size.\r
  @retval EFI_INVALID_PARAMETER   DeviceStatus is NULL\r
**/\r
typedef\r
EFI_STATUS\r
(EFIAPI *VIRTIO_GET_DEVICE_STATUS)(\r
  IN  VIRTIO_DEVICE_PROTOCOL  *This,\r
  OUT UINT8                   *DeviceStatus\r
  );\r
\r
/**\r
\r
  Write the DeviceStatus field in the Virtio Header.\r
\r
  @param[in] This         This instance of VIRTIO_DEVICE_PROTOCOL\r
\r
  @param[in] DeviceStatus The 8-bit value for the Device status field\r
\r
  @retval EFI_SUCCESS         The data was written successfully.\r
  @retval EFI_UNSUPPORTED     The underlying IO device doesn't support the\r
                              provided address offset and write size.\r
**/\r
typedef\r
EFI_STATUS\r
(EFIAPI *VIRTIO_SET_DEVICE_STATUS)(\r
  IN VIRTIO_DEVICE_PROTOCOL  *This,\r
  IN UINT8                   DeviceStatus\r
  );\r
\r
/**\r
\r
  Allocates pages that are suitable for an VirtioOperationBusMasterCommonBuffer\r
  mapping. This means that the buffer allocated by this function supports\r
  simultaneous access by both the processor and the bus master. The device\r
  address that the bus master uses to access the buffer must be retrieved with\r
  a call to VIRTIO_MAP_SHARED.\r
\r
  @param[in]      This              The protocol instance pointer.\r
\r
  @param[in]      Pages             The number of pages to allocate.\r
\r
  @param[in,out]  HostAddress       A pointer to store the system memory base\r
                                    address of the allocated range.\r
\r
  @retval EFI_SUCCESS               The requested memory pages were allocated.\r
  @retval EFI_OUT_OF_RESOURCES      The memory pages could not be allocated.\r
\r
**/\r
typedef\r
EFI_STATUS\r
(EFIAPI *VIRTIO_ALLOCATE_SHARED)(\r
  IN     VIRTIO_DEVICE_PROTOCOL                   *This,\r
  IN     UINTN                                    Pages,\r
  IN OUT VOID                                     **HostAddress\r
  );\r
\r
/**\r
  Frees memory that was allocated with VIRTIO_ALLOCATE_SHARED.\r
\r
  @param[in]  This           The protocol instance pointer.\r
\r
  @param[in]  Pages          The number of pages to free.\r
\r
  @param[in]  HostAddress    The system memory base address of the allocated\r
                             range.\r
\r
**/\r
typedef\r
VOID\r
(EFIAPI *VIRTIO_FREE_SHARED)(\r
  IN  VIRTIO_DEVICE_PROTOCOL                   *This,\r
  IN  UINTN                                    Pages,\r
  IN  VOID                                     *HostAddress\r
  );\r
\r
/**\r
  Provides the virtio device address required to access system memory from a\r
  DMA bus master.\r
\r
  The interface follows the same usage pattern as defined in UEFI spec 2.6\r
  (Section 13.2 PCI Root Bridge I/O Protocol)\r
\r
  @param[in]     This             The protocol instance pointer.\r
\r
  @param[in]     Operation        Indicates if the bus master is going to\r
                                  read or write to system memory.\r
\r
  @param[in]     HostAddress      The system memory address to map to shared\r
                                  buffer address.\r
\r
  @param[in,out] NumberOfBytes    On input the number of bytes to map.\r
                                  On output the number of bytes that were\r
                                  mapped.\r
\r
  @param[out]    DeviceAddress    The resulting shared map address for the\r
                                  bus master to access the hosts HostAddress.\r
\r
  @param[out]    Mapping          A resulting token to pass to\r
                                  VIRTIO_UNMAP_SHARED.\r
\r
  @retval EFI_SUCCESS             The range was mapped for the returned\r
                                  NumberOfBytes.\r
  @retval EFI_UNSUPPORTED         The HostAddress cannot be mapped as a\r
                                  common buffer.\r
  @retval EFI_INVALID_PARAMETER   One or more parameters are invalid.\r
  @retval EFI_OUT_OF_RESOURCES    The request could not be completed due to\r
                                  a lack of resources.\r
  @retval EFI_DEVICE_ERROR        The system hardware could not map the\r
                                  requested address.\r
**/\r
\r
typedef\r
EFI_STATUS\r
(EFIAPI *VIRTIO_MAP_SHARED)(\r
  IN     VIRTIO_DEVICE_PROTOCOL       *This,\r
  IN     VIRTIO_MAP_OPERATION         Operation,\r
  IN     VOID                         *HostAddress,\r
  IN OUT UINTN                        *NumberOfBytes,\r
  OUT    EFI_PHYSICAL_ADDRESS         *DeviceAddress,\r
  OUT    VOID                         **Mapping\r
  );\r
\r
/**\r
  Completes the VIRTIO_MAP_SHARED operation and releases any corresponding\r
  resources.\r
\r
  @param[in]  This               The protocol instance pointer.\r
\r
  @param[in]  Mapping            The mapping token returned from\r
                                 VIRTIO_MAP_SHARED.\r
\r
  @retval EFI_SUCCESS            The range was unmapped.\r
  @retval EFI_INVALID_PARAMETER  Mapping is not a value that was returned by\r
                                 VIRTIO_MAP_SHARED. Passing an invalid Mapping\r
                                 token can cause undefined behavior.\r
  @retval EFI_DEVICE_ERROR       The data was not committed to the target\r
                                 system memory.\r
**/\r
typedef\r
EFI_STATUS\r
(EFIAPI *VIRTIO_UNMAP_SHARED)(\r
  IN  VIRTIO_DEVICE_PROTOCOL    *This,\r
  IN  VOID                      *Mapping\r
  );\r
\r
///\r
///  This protocol provides an abstraction over the VirtIo transport layer\r
///\r
///  DISCLAIMER: this protocol is a work in progress, and should not be used\r
///  outside of the EDK II tree.\r
///\r
struct _VIRTIO_DEVICE_PROTOCOL {\r
  //\r
  // VirtIo Specification Revision encoded with VIRTIO_SPEC_REVISION()\r
  //\r
  UINT32                        Revision;\r
  //\r
  // From the Virtio Spec\r
  //\r
  INT32                         SubSystemDeviceId;\r
\r
  VIRTIO_GET_DEVICE_FEATURES    GetDeviceFeatures;\r
  VIRTIO_SET_GUEST_FEATURES     SetGuestFeatures;\r
\r
  VIRTIO_SET_QUEUE_ADDRESS      SetQueueAddress;\r
\r
  VIRTIO_SET_QUEUE_SEL          SetQueueSel;\r
\r
  VIRTIO_SET_QUEUE_NOTIFY       SetQueueNotify;\r
\r
  VIRTIO_SET_QUEUE_ALIGN        SetQueueAlign;\r
  VIRTIO_SET_PAGE_SIZE          SetPageSize;\r
\r
  VIRTIO_GET_QUEUE_NUM_MAX      GetQueueNumMax;\r
  VIRTIO_SET_QUEUE_NUM          SetQueueNum;\r
\r
  VIRTIO_GET_DEVICE_STATUS      GetDeviceStatus;\r
  VIRTIO_SET_DEVICE_STATUS      SetDeviceStatus;\r
\r
  //\r
  // Functions to read/write Device Specific headers\r
  //\r
  VIRTIO_DEVICE_WRITE           WriteDevice;\r
  VIRTIO_DEVICE_READ            ReadDevice;\r
\r
  //\r
  // Functions to allocate, free, map and unmap shared buffer\r
  //\r
  VIRTIO_ALLOCATE_SHARED        AllocateSharedPages;\r
  VIRTIO_FREE_SHARED            FreeSharedPages;\r
  VIRTIO_MAP_SHARED             MapSharedBuffer;\r
  VIRTIO_UNMAP_SHARED           UnmapSharedBuffer;\r
};\r
\r
extern EFI_GUID  gVirtioDeviceProtocolGuid;\r
\r
#endif\r
Commit	Line	Data
fc4d1ce5 OM	1	/** @file\r
	2	Virtio Device\r
	3	\r
	4	DISCLAIMER: the VIRTIO_DEVICE_PROTOCOL introduced here is a work in progress,\r
	5	and should not be used outside of the EDK II tree.\r
	6	\r
	7	Copyright (c) 2013, ARM Ltd. All rights reserved.<BR>\r
87811526	8	Copyright (c) 2017, AMD Inc, All rights reserved.<BR>\r
fc4d1ce5	9	\r
b26f0cf9	10	SPDX-License-Identifier: BSD-2-Clause-Patent\r
fc4d1ce5 OM	11	\r
	12	**/\r
	13	\r
	14	#ifndef __VIRTIO_DEVICE_H__\r
	15	#define __VIRTIO_DEVICE_H__\r
	16	\r
07af4eee LE	17	#include <IndustryStandard/Virtio.h>\r
07af4eee LE	18	\r
a136bc3c BS	19	//\r
	20	// VirtIo Specification Revision: Major[31:24].Minor[23:16].Revision[15:0]\r
	21	//\r
ac0a286f	22	#define VIRTIO_SPEC_REVISION(major, minor, revision) \\r
fc4d1ce5 OM	23	((((major) & 0xFF) << 24) \| (((minor) & 0xFF) << 16) \| ((revision) & 0xFFFF))\r
fc4d1ce5 OM	24	\r
ac0a286f	25	#define VIRTIO_DEVICE_PROTOCOL_GUID {\\r
fc4d1ce5 OM	26	0xfa920010, 0x6785, 0x4941, {0xb6, 0xec, 0x49, 0x8c, 0x57, 0x9f, 0x16, 0x0a }\\r
	27	}\r
	28	\r
ac0a286f	29	typedef struct _VIRTIO_DEVICE_PROTOCOL VIRTIO_DEVICE_PROTOCOL;\r
fc4d1ce5	30	\r
87811526 BS	31	//\r
	32	// VIRTIO Operation for VIRTIO_MAP_SHARED\r
	33	//\r
	34	typedef enum {\r
	35	//\r
	36	// A read operation from system memory by a bus master\r
	37	//\r
	38	VirtioOperationBusMasterRead,\r
	39	//\r
	40	// A write operation to system memory by a bus master\r
	41	//\r
	42	VirtioOperationBusMasterWrite,\r
	43	//\r
	44	// Provides both read and write access to system memory by both the\r
	45	// processor and a bus master\r
	46	//\r
	47	VirtioOperationBusMasterCommonBuffer,\r
	48	} VIRTIO_MAP_OPERATION;\r
	49	\r
fc4d1ce5 OM	50	/**\r
	51	\r
	52	Read a word from the device-specific I/O region of the Virtio Header.\r
	53	\r
	54	@param[in] This This instance of VIRTIO_DEVICE_PROTOCOL\r
	55	\r
	56	@param[in] FieldOffset Source offset.\r
	57	\r
	58	@param[in] FieldSize Source field size in bytes, must be in {1, 2, 4, 8}.\r
	59	\r
	60	@param[in] BufferSize Number of bytes available in the target buffer. Must\r
	61	equal FieldSize.\r
	62	\r
	63	@param[out] Buffer Target buffer.\r
	64	\r
	65	@retval EFI_SUCCESS The data was read successfully.\r
	66	@retval EFI_UNSUPPORTED The underlying IO device doesn't support the\r
	67	provided address offset and read size.\r
	68	@retval EFI_OUT_OF_RESOURCES The request could not be completed due to a\r
	69	lack of resources.\r
	70	@retval EFI_INVALID_PARAMETER One or more parameters are invalid.\r
	71	\r
	72	**/\r
	73	typedef\r
	74	EFI_STATUS\r
ac0a286f	75	(EFIAPI *VIRTIO_DEVICE_READ)(\r
fc4d1ce5 OM	76	IN VIRTIO_DEVICE_PROTOCOL *This,\r
	77	IN UINTN FieldOffset,\r
	78	IN UINTN FieldSize,\r
	79	IN UINTN BufferSize,\r
	80	OUT VOID *Buffer\r
	81	);\r
	82	\r
	83	/**\r
	84	\r
	85	Write a word to the device-specific I/O region of the Virtio Header.\r
	86	\r
	87	@param[in] This This instance of VIRTIO_DEVICE_PROTOCOL\r
	88	\r
	89	@param[in] FieldOffset Destination offset.\r
	90	\r
	91	@param[in] FieldSize Destination field size in bytes,\r
	92	must be in {1, 2, 4, 8}.\r
	93	\r
	94	@param[out] Value Value to write.\r
	95	\r
	96	@retval EFI_SUCCESS The data was written successfully.\r
	97	@retval EFI_UNSUPPORTED The underlying IO device doesn't support the\r
	98	provided address offset and write size.\r
	99	@retval EFI_OUT_OF_RESOURCES The request could not be completed due to a\r
	100	lack of resources.\r
	101	@retval EFI_INVALID_PARAMETER One or more parameters are invalid.\r
	102	\r
	103	**/\r
	104	typedef\r
	105	EFI_STATUS\r
ac0a286f	106	(EFIAPI *VIRTIO_DEVICE_WRITE)(\r
fc4d1ce5 OM	107	IN VIRTIO_DEVICE_PROTOCOL *This,\r
	108	IN UINTN FieldOffset,\r
	109	IN UINTN FieldSize,\r
	110	IN UINT64 Value\r
	111	);\r
	112	\r
	113	/**\r
	114	Read the device features field from the Virtio Header.\r
	115	\r
	116	@param[in] This This instance of VIRTIO_DEVICE_PROTOCOL\r
	117	\r
bc8fde6f	118	@param[out] DeviceFeatures The device features field.\r
fc4d1ce5 OM	119	\r
	120	@retval EFI_SUCCESS The data was read successfully.\r
	121	@retval EFI_UNSUPPORTED The underlying IO device doesn't support the\r
	122	provided address offset and read size.\r
	123	@retval EFI_INVALID_PARAMETER DeviceFeatures is NULL\r
	124	**/\r
	125	typedef\r
	126	EFI_STATUS\r
ac0a286f	127	(EFIAPI *VIRTIO_GET_DEVICE_FEATURES)(\r
fc4d1ce5	128	IN VIRTIO_DEVICE_PROTOCOL *This,\r
bc8fde6f	129	OUT UINT64 *DeviceFeatures\r
fc4d1ce5 OM	130	);\r
	131	\r
	132	/**\r
	133	Write the guest features field in the Virtio Header.\r
	134	\r
	135	@param[in] This This instance of VIRTIO_DEVICE_PROTOCOL\r
	136	\r
bc8fde6f	137	@param[in] Features The guest features field\r
fc4d1ce5 OM	138	\r
	139	**/\r
	140	typedef\r
	141	EFI_STATUS\r
ac0a286f	142	(EFIAPI *VIRTIO_SET_GUEST_FEATURES)(\r
fc4d1ce5	143	IN VIRTIO_DEVICE_PROTOCOL *This,\r
bc8fde6f	144	IN UINT64 Features\r
fc4d1ce5 OM	145	);\r
fc4d1ce5 OM	146	\r
fc4d1ce5	147	/**\r
07af4eee	148	Write the queue address field(s) in the Virtio Header.\r
fc4d1ce5 OM	149	\r
	150	@param[in] This This instance of VIRTIO_DEVICE_PROTOCOL\r
	151	\r
07af4eee	152	@param[in] Ring The initialized VRING object to take the\r
53a4c604 BS	153	addresses from. The caller is responsible for\r
	154	ensuring that on input, all Ring->NumPages pages,\r
	155	starting at Ring->Base, have been successfully\r
	156	mapped with a single call to\r
	157	This->MapSharedBuffer() for CommonBuffer bus\r
	158	master operation.\r
	159	\r
	160	@param[in] RingBaseShift Adding this value using UINT64 arithmetic to the\r
	161	addresses found in Ring translates them from\r
	162	system memory to bus addresses. The caller shall\r
	163	calculate RingBaseShift as\r
	164	(DeviceAddress - (UINT64)(UINTN)HostAddress),\r
	165	where DeviceAddress and HostAddress (i.e.,\r
	166	Ring->Base) were output and input parameters of\r
	167	This->MapSharedBuffer(), respectively.\r
fc4d1ce5 OM	168	\r
	169	@retval EFI_SUCCESS The data was written successfully.\r
	170	@retval EFI_UNSUPPORTED The underlying IO device doesn't support the\r
	171	provided address offset and write size.\r
	172	**/\r
	173	typedef\r
	174	EFI_STATUS\r
ac0a286f	175	(EFIAPI *VIRTIO_SET_QUEUE_ADDRESS)(\r
fc4d1ce5	176	IN VIRTIO_DEVICE_PROTOCOL *This,\r
53a4c604 BS	177	IN VRING *Ring,\r
53a4c604 BS	178	IN UINT64 RingBaseShift\r
fc4d1ce5 OM	179	);\r
	180	\r
	181	/**\r
	182	\r
	183	Write the queue select field in the Virtio Header.\r
	184	\r
	185	Writing to the queue select field sets the index of the queue to which\r
	186	operations such as SetQueueAlign and GetQueueNumMax apply.\r
	187	\r
	188	@param[in] This This instance of VIRTIO_DEVICE_PROTOCOL\r
	189	\r
	190	@param[in] Index The index of the queue to select\r
	191	\r
	192	@retval EFI_SUCCESS The data was written successfully.\r
	193	@retval EFI_UNSUPPORTED The underlying IO device doesn't support the\r
	194	provided address offset and write size.\r
	195	**/\r
	196	typedef\r
	197	EFI_STATUS\r
ac0a286f	198	(EFIAPI *VIRTIO_SET_QUEUE_SEL)(\r
fc4d1ce5 OM	199	IN VIRTIO_DEVICE_PROTOCOL *This,\r
	200	IN UINT16 Index\r
	201	);\r
	202	\r
	203	/**\r
	204	\r
	205	Write the queue notify field in the Virtio Header.\r
	206	\r
	207	@param[in] This This instance of VIRTIO_DEVICE_PROTOCOL\r
	208	\r
	209	@param[in] Address The 32-bit Queue Notify field\r
	210	\r
	211	@retval EFI_SUCCESS The data was written successfully.\r
	212	@retval EFI_UNSUPPORTED The underlying IO device doesn't support the\r
	213	provided address offset and write size.\r
	214	**/\r
	215	typedef\r
	216	EFI_STATUS\r
ac0a286f	217	(EFIAPI *VIRTIO_SET_QUEUE_NOTIFY)(\r
fc4d1ce5 OM	218	IN VIRTIO_DEVICE_PROTOCOL *This,\r
	219	IN UINT16 Index\r
	220	);\r
	221	\r
	222	/**\r
	223	Write the queue alignment field in the Virtio Header.\r
	224	\r
	225	The queue to which the alignment applies is selected by the Queue Select\r
	226	field.\r
	227	\r
	228	Note: This operation is not implemented by the VirtIo over PCI. The PCI\r
	229	implementation of this protocol returns EFI_SUCCESS.\r
	230	\r
	231	@param[in] This This instance of VIRTIO_DEVICE_PROTOCOL\r
	232	\r
	233	@param[in] Alignment The alignment boundary of the Used Ring in bytes.\r
	234	Must be a power of 2.\r
	235	\r
	236	@retval EFI_SUCCESS The data was written successfully.\r
	237	@retval EFI_UNSUPPORTED The underlying IO device doesn't support the\r
	238	provided address offset and write size.\r
	239	**/\r
	240	typedef\r
	241	EFI_STATUS\r
ac0a286f	242	(EFIAPI *VIRTIO_SET_QUEUE_ALIGN)(\r
fc4d1ce5 OM	243	IN VIRTIO_DEVICE_PROTOCOL *This,\r
	244	IN UINT32 Alignment\r
	245	);\r
	246	\r
	247	/**\r
	248	Write the guest page size.\r
	249	\r
	250	Note: This operation is not implemented by the VirtIo over PCI. The PCI\r
	251	implementation of this protocol returns EFI_SUCCESS.\r
	252	\r
	253	@param[in] This This instance of VIRTIO_DEVICE_PROTOCOL\r
	254	\r
	255	@param[in] PageSize Size of the Guest page in bytes.\r
	256	Must be a power of 2.\r
	257	\r
	258	@retval EFI_SUCCESS The data was written successfully.\r
	259	@retval EFI_UNSUPPORTED The underlying IO device doesn't support the\r
	260	provided address offset and write size.\r
	261	**/\r
	262	typedef\r
	263	EFI_STATUS\r
ac0a286f	264	(EFIAPI *VIRTIO_SET_PAGE_SIZE)(\r
fc4d1ce5 OM	265	IN VIRTIO_DEVICE_PROTOCOL *This,\r
	266	IN UINT32 PageSize\r
	267	);\r
	268	\r
	269	/**\r
	270	\r
	271	Get the size of the virtqueue selected by the queue select field.\r
	272	\r
	273	See Virtio spec Section 2.3\r
	274	\r
	275	@param[in] This This instance of VIRTIO_DEVICE_PROTOCOL\r
	276	\r
	277	@param[out] QueueNumMax The size of the virtqueue in bytes.\r
	278	Always a power of 2.\r
	279	\r
	280	@retval EFI_SUCCESS The data was read successfully.\r
	281	@retval EFI_UNSUPPORTED The underlying IO device doesn't support the\r
	282	provided address offset and read size.\r
	283	@retval EFI_INVALID_PARAMETER QueueNumMax is NULL\r
	284	**/\r
	285	typedef\r
	286	EFI_STATUS\r
ac0a286f	287	(EFIAPI *VIRTIO_GET_QUEUE_NUM_MAX)(\r
fc4d1ce5 OM	288	IN VIRTIO_DEVICE_PROTOCOL *This,\r
	289	OUT UINT16 *QueueNumMax\r
	290	);\r
	291	\r
	292	/**\r
	293	\r
	294	Write to the QueueNum field in the Virtio Header.\r
	295	\r
	296	This function only applies to Virtio-MMIO and may be a stub for other\r
	297	implementations. See Virtio Spec appendix X.\r
	298	\r
	299	@param[in] This This instance of VIRTIO_DEVICE_PROTOCOL\r
	300	\r
	301	@param[in] QueueSize The number of elements in the queue.\r
	302	\r
	303	@retval EFI_SUCCESS The data was written successfully.\r
	304	@retval EFI_UNSUPPORTED The underlying IO device doesn't support the\r
	305	provided address offset and write size.\r
	306	**/\r
	307	typedef\r
	308	EFI_STATUS\r
ac0a286f	309	(EFIAPI *VIRTIO_SET_QUEUE_NUM)(\r
fc4d1ce5 OM	310	IN VIRTIO_DEVICE_PROTOCOL *This,\r
	311	IN UINT16 QueueSize\r
	312	);\r
	313	\r
	314	/**\r
	315	\r
	316	Get the DeviceStatus field from the Virtio Header.\r
	317	\r
	318	@param[in] This This instance of VIRTIO_DEVICE_PROTOCOL\r
	319	\r
	320	@param[out] DeviceStatus The 8-bit value for the Device status field\r
	321	\r
	322	@retval EFI_SUCCESS The data was read successfully.\r
	323	@retval EFI_UNSUPPORTED The underlying IO device doesn't support the\r
	324	provided address offset and read size.\r
	325	@retval EFI_INVALID_PARAMETER DeviceStatus is NULL\r
	326	**/\r
	327	typedef\r
	328	EFI_STATUS\r
ac0a286f	329	(EFIAPI *VIRTIO_GET_DEVICE_STATUS)(\r
fc4d1ce5 OM	330	IN VIRTIO_DEVICE_PROTOCOL *This,\r
	331	OUT UINT8 *DeviceStatus\r
	332	);\r
	333	\r
	334	/**\r
	335	\r
	336	Write the DeviceStatus field in the Virtio Header.\r
	337	\r
	338	@param[in] This This instance of VIRTIO_DEVICE_PROTOCOL\r
	339	\r
	340	@param[in] DeviceStatus The 8-bit value for the Device status field\r
	341	\r
	342	@retval EFI_SUCCESS The data was written successfully.\r
	343	@retval EFI_UNSUPPORTED The underlying IO device doesn't support the\r
	344	provided address offset and write size.\r
	345	**/\r
	346	typedef\r
	347	EFI_STATUS\r
ac0a286f	348	(EFIAPI *VIRTIO_SET_DEVICE_STATUS)(\r
fc4d1ce5 OM	349	IN VIRTIO_DEVICE_PROTOCOL *This,\r
	350	IN UINT8 DeviceStatus\r
	351	);\r
	352	\r
87811526 BS	353	/**\r
	354	\r
	355	Allocates pages that are suitable for an VirtioOperationBusMasterCommonBuffer\r
	356	mapping. This means that the buffer allocated by this function supports\r
	357	simultaneous access by both the processor and the bus master. The device\r
	358	address that the bus master uses to access the buffer must be retrieved with\r
	359	a call to VIRTIO_MAP_SHARED.\r
	360	\r
	361	@param[in] This The protocol instance pointer.\r
	362	\r
	363	@param[in] Pages The number of pages to allocate.\r
	364	\r
	365	@param[in,out] HostAddress A pointer to store the system memory base\r
	366	address of the allocated range.\r
	367	\r
	368	@retval EFI_SUCCESS The requested memory pages were allocated.\r
	369	@retval EFI_OUT_OF_RESOURCES The memory pages could not be allocated.\r
	370	\r
	371	**/\r
	372	typedef\r
	373	EFI_STATUS\r
	374	(EFIAPI *VIRTIO_ALLOCATE_SHARED)(\r
	375	IN VIRTIO_DEVICE_PROTOCOL *This,\r
	376	IN UINTN Pages,\r
	377	IN OUT VOID **HostAddress\r
	378	);\r
	379	\r
	380	/**\r
	381	Frees memory that was allocated with VIRTIO_ALLOCATE_SHARED.\r
	382	\r
	383	@param[in] This The protocol instance pointer.\r
	384	\r
	385	@param[in] Pages The number of pages to free.\r
	386	\r
	387	@param[in] HostAddress The system memory base address of the allocated\r
	388	range.\r
	389	\r
	390	**/\r
	391	typedef\r
	392	VOID\r
	393	(EFIAPI *VIRTIO_FREE_SHARED)(\r
	394	IN VIRTIO_DEVICE_PROTOCOL *This,\r
	395	IN UINTN Pages,\r
	396	IN VOID *HostAddress\r
	397	);\r
	398	\r
	399	/**\r
	400	Provides the virtio device address required to access system memory from a\r
	401	DMA bus master.\r
	402	\r
	403	The interface follows the same usage pattern as defined in UEFI spec 2.6\r
	404	(Section 13.2 PCI Root Bridge I/O Protocol)\r
	405	\r
	406	@param[in] This The protocol instance pointer.\r
	407	\r
	408	@param[in] Operation Indicates if the bus master is going to\r
	409	read or write to system memory.\r
	410	\r
	411	@param[in] HostAddress The system memory address to map to shared\r
	412	buffer address.\r
	413	\r
	414	@param[in,out] NumberOfBytes On input the number of bytes to map.\r
	415	On output the number of bytes that were\r
	416	mapped.\r
417	\r
418	@param[out] DeviceAddress The resulting shared map address for the\r
419	bus master to access the hosts HostAddress.\r
420	\r
421	@param[out] Mapping A resulting token to pass to\r
422	VIRTIO_UNMAP_SHARED.\r
423	\r
424	@retval EFI_SUCCESS The range was mapped for the returned\r
425	NumberOfBytes.\r
426	@retval EFI_UNSUPPORTED The HostAddress cannot be mapped as a\r
427	common buffer.\r
428	@retval EFI_INVALID_PARAMETER One or more parameters are invalid.\r
429	@retval EFI_OUT_OF_RESOURCES The request could not be completed due to\r
430	a lack of resources.\r
431	@retval EFI_DEVICE_ERROR The system hardware could not map the\r
432	requested address.\r
433	**/\r
434	\r
435	typedef\r
436	EFI_STATUS\r
ac0a286f	437	(EFIAPI *VIRTIO_MAP_SHARED)(\r
87811526 BS	438	IN VIRTIO_DEVICE_PROTOCOL *This,\r
	439	IN VIRTIO_MAP_OPERATION Operation,\r
	440	IN VOID *HostAddress,\r
	441	IN OUT UINTN *NumberOfBytes,\r
	442	OUT EFI_PHYSICAL_ADDRESS *DeviceAddress,\r
	443	OUT VOID **Mapping\r
	444	);\r
	445	\r
	446	/**\r
	447	Completes the VIRTIO_MAP_SHARED operation and releases any corresponding\r
	448	resources.\r
	449	\r
	450	@param[in] This The protocol instance pointer.\r
	451	\r
	452	@param[in] Mapping The mapping token returned from\r
	453	VIRTIO_MAP_SHARED.\r
	454	\r
	455	@retval EFI_SUCCESS The range was unmapped.\r
	456	@retval EFI_INVALID_PARAMETER Mapping is not a value that was returned by\r
	457	VIRTIO_MAP_SHARED. Passing an invalid Mapping\r
	458	token can cause undefined behavior.\r
	459	@retval EFI_DEVICE_ERROR The data was not committed to the target\r
	460	system memory.\r
	461	**/\r
	462	typedef\r
	463	EFI_STATUS\r
	464	(EFIAPI *VIRTIO_UNMAP_SHARED)(\r
	465	IN VIRTIO_DEVICE_PROTOCOL *This,\r
	466	IN VOID *Mapping\r
	467	);\r
fc4d1ce5 OM	468	\r
	469	///\r
	470	/// This protocol provides an abstraction over the VirtIo transport layer\r
	471	///\r
	472	/// DISCLAIMER: this protocol is a work in progress, and should not be used\r
	473	/// outside of the EDK II tree.\r
	474	///\r
	475	struct _VIRTIO_DEVICE_PROTOCOL {\r
a136bc3c BS	476	//\r
	477	// VirtIo Specification Revision encoded with VIRTIO_SPEC_REVISION()\r
	478	//\r
ac0a286f	479	UINT32 Revision;\r
a136bc3c BS	480	//\r
	481	// From the Virtio Spec\r
	482	//\r
ac0a286f	483	INT32 SubSystemDeviceId;\r
fc4d1ce5	484	\r
ac0a286f MK	485	VIRTIO_GET_DEVICE_FEATURES GetDeviceFeatures;\r
ac0a286f MK	486	VIRTIO_SET_GUEST_FEATURES SetGuestFeatures;\r
fc4d1ce5	487	\r
ac0a286f	488	VIRTIO_SET_QUEUE_ADDRESS SetQueueAddress;\r
fc4d1ce5	489	\r
ac0a286f	490	VIRTIO_SET_QUEUE_SEL SetQueueSel;\r
fc4d1ce5	491	\r
ac0a286f	492	VIRTIO_SET_QUEUE_NOTIFY SetQueueNotify;\r
fc4d1ce5	493	\r
ac0a286f MK	494	VIRTIO_SET_QUEUE_ALIGN SetQueueAlign;\r
ac0a286f MK	495	VIRTIO_SET_PAGE_SIZE SetPageSize;\r
fc4d1ce5	496	\r
ac0a286f MK	497	VIRTIO_GET_QUEUE_NUM_MAX GetQueueNumMax;\r
ac0a286f MK	498	VIRTIO_SET_QUEUE_NUM SetQueueNum;\r
fc4d1ce5	499	\r
ac0a286f MK	500	VIRTIO_GET_DEVICE_STATUS GetDeviceStatus;\r
ac0a286f MK	501	VIRTIO_SET_DEVICE_STATUS SetDeviceStatus;\r
fc4d1ce5	502	\r
a136bc3c	503	//\r
fc4d1ce5	504	// Functions to read/write Device Specific headers\r
a136bc3c	505	//\r
ac0a286f MK	506	VIRTIO_DEVICE_WRITE WriteDevice;\r
ac0a286f MK	507	VIRTIO_DEVICE_READ ReadDevice;\r
87811526 BS	508	\r
	509	//\r
	510	// Functions to allocate, free, map and unmap shared buffer\r
	511	//\r
ac0a286f MK	512	VIRTIO_ALLOCATE_SHARED AllocateSharedPages;\r
	513	VIRTIO_FREE_SHARED FreeSharedPages;\r
	514	VIRTIO_MAP_SHARED MapSharedBuffer;\r
	515	VIRTIO_UNMAP_SHARED UnmapSharedBuffer;\r
fc4d1ce5 OM	516	};\r
fc4d1ce5 OM	517	\r
ac0a286f	518	extern EFI_GUID gVirtioDeviceProtocolGuid;\r
fc4d1ce5 OM	519	\r
fc4d1ce5 OM	520	#endif\r