OvmfPkg/VirtioDevice.h: Introduced VIRTIO_DEVICE_PROTOCOL protocol
authorOlivier Martin <olivier.martin@arm.com>
Wed, 11 Dec 2013 16:57:40 +0000 (16:57 +0000)
committerjljusten <jljusten@6f19259b-4bc3-4df7-8a09-765794883524>
Wed, 11 Dec 2013 16:57:40 +0000 (16:57 +0000)
This protocol introduces an abstraction to access the VirtIo
Configuration and Device spaces.
The registers in these spaces are located at a different offset and have
a different width whether the transport layer is either PCI or MMIO. This
protocol would also allow to support VirtIo PCI devices with MSI-X
capability in a transparent way (Device space is at a different offset
when a PCIe device has MSI-X capability).

Contributed-under: TianoCore Contribution Agreement 1.0
Signed-off-by: Olivier Martin <olivier.martin@arm.com>
v5:
- add disclaimer (two instances) about the protocol being work in progress

Contributed-under: TianoCore Contribution Agreement 1.0
Signed-off-by: Laszlo Ersek <lersek@redhat.com>
Reviewed-by: Jordan Justen <jordan.l.justen@intel.com>
git-svn-id: https://svn.code.sf.net/p/edk2/code/trunk/edk2@14963 6f19259b-4bc3-4df7-8a09-765794883524

OvmfPkg/Include/Protocol/VirtioDevice.h [new file with mode: 0644]
OvmfPkg/OvmfPkg.dec

diff --git a/OvmfPkg/Include/Protocol/VirtioDevice.h b/OvmfPkg/Include/Protocol/VirtioDevice.h
new file mode 100644 (file)
index 0000000..48fca2e
--- /dev/null
@@ -0,0 +1,382 @@
+/** @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
+\r
+  This program and the accompanying materials are licensed and made available\r
+  under the terms and conditions of the BSD License which accompanies this\r
+  distribution. The full text of the license may be found at\r
+  http://opensource.org/licenses/bsd-license.php\r
+\r
+  THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, WITHOUT\r
+  WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.\r
+\r
+**/\r
+\r
+#ifndef __VIRTIO_DEVICE_H__\r
+#define __VIRTIO_DEVICE_H__\r
+\r
+// VirtIo Specification Revision: Major[31:24].Minor[23:16].Revision[15:0\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
+\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 32-bit 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 UINT32                *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 32-bit guest guest features field\r
+\r
+**/\r
+typedef\r
+EFI_STATUS\r
+(EFIAPI *VIRTIO_SET_GUEST_FEATURES) (\r
+  IN VIRTIO_DEVICE_PROTOCOL  *This,\r
+  IN UINT32                   Features\r
+  );\r
+\r
+/**\r
+  Read the queue address field from the Virtio Header.\r
+\r
+  QueueAddress is the address of the virtqueue divided by 4096.\r
+\r
+  @param[in] This                 This instance of VIRTIO_DEVICE_PROTOCOL\r
+\r
+  @param[out] QueueAddress        The 32-bit queue address 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   QueueAddress is NULL\r
+**/\r
+typedef\r
+EFI_STATUS\r
+(EFIAPI *VIRTIO_GET_QUEUE_ADDRESS) (\r
+  IN  VIRTIO_DEVICE_PROTOCOL *This,\r
+  OUT UINT32                 *QueueAddress\r
+  );\r
+\r
+/**\r
+  Write the queue address field in the Virtio Header.\r
+\r
+  The parameter Address must be the base address of the virtqueue divided\r
+  by 4096.\r
+\r
+  @param[in] This             This instance of VIRTIO_DEVICE_PROTOCOL\r
+\r
+  @param[in] Address          The 32-bit Queue Address 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_ADDRESS) (\r
+  IN VIRTIO_DEVICE_PROTOCOL  *This,\r
+  IN UINT32                   Address\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
+///  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
+  /// VirtIo Specification Revision encoded with VIRTIO_SPEC_REVISION()\r
+  UINT32                      Revision;\r
+  /// From the Virtio Spec\r
+  INT32                       SubSystemDeviceId;\r
+\r
+  VIRTIO_GET_DEVICE_FEATURES  GetDeviceFeatures;\r
+  VIRTIO_SET_GUEST_FEATURES   SetGuestFeatures;\r
+\r
+  VIRTIO_GET_QUEUE_ADDRESS    GetQueueAddress;\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
+  // Functions to read/write Device Specific headers\r
+  VIRTIO_DEVICE_WRITE         WriteDevice;\r
+  VIRTIO_DEVICE_READ          ReadDevice;\r
+};\r
+\r
+extern EFI_GUID gVirtioDeviceProtocolGuid;\r
+\r
+#endif\r
index 7bfd5c31ae60170111907a26faf4ecc9cc54b803..9d7fedf4df48053988793c51bbbd3a23c21ee619 100644 (file)
@@ -44,6 +44,7 @@
   gEfiXenInfoGuid                 = {0xd3b46f3b, 0xd441, 0x1244, {0x9a, 0x12, 0x0, 0x12, 0x27, 0x3f, 0xc1, 0x4d}}\r
 \r
 [Protocols]\r
+  gVirtioDeviceProtocolGuid       = {0xfa920010, 0x6785, 0x4941, {0xb6, 0xec, 0x49, 0x8c, 0x57, 0x9f, 0x16, 0x0a}}\r
   gBlockMmioProtocolGuid          = {0x6b558ce3, 0x69e5, 0x4c67, {0xa6, 0x34, 0xf7, 0xfe, 0x72, 0xad, 0xbe, 0x84}}\r
 \r
 [PcdsFixedAtBuild]\r