OvmfPkg/Virtio: take RingBaseShift in SetQueueAddress()

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

diff --git a/OvmfPkg/Include/Protocol/VirtioDevice.h b/OvmfPkg/Include/Protocol/VirtioDevice.h
index 910a4866e7ac996b9bb99b026d0694c7bc5fdb58..afc27e54a863e2dba4038e53dc4fc2362acb564d 100644 (file)
--- a/OvmfPkg/Include/Protocol/VirtioDevice.h
+++ b/OvmfPkg/Include/Protocol/VirtioDevice.h
@@ -5,6 +5,7 @@
   and should not be used outside of the EDK II tree.\r
 \r
   Copyright (c) 2013, ARM Ltd. All rights reserved.<BR>\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
   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
 \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


@@ -21,7 +22,9 @@
 \r
 #include <IndustryStandard/Virtio.h>\r
 \r
 \r
 #include <IndustryStandard/Virtio.h>\r
 \r

-// VirtIo Specification Revision: Major[31:24].Minor[23:16].Revision[15:0\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_SPEC_REVISION(major,minor,revision) \\r
   ((((major) & 0xFF) << 24) | (((minor) & 0xFF) << 16) | ((revision) & 0xFFFF))\r
 \r


@@ -31,6 +34,25 @@
 \r
 typedef struct _VIRTIO_DEVICE_PROTOCOL  VIRTIO_DEVICE_PROTOCOL;\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
 \r
   Read a word from the device-specific I/O region of the Virtio Header.\r


@@ -134,7 +156,21 @@ EFI_STATUS
   @param[in] This             This instance of VIRTIO_DEVICE_PROTOCOL\r
 \r
   @param[in] Ring             The initialized VRING object to take the\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.\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
 \r
   @retval EFI_SUCCESS         The data was written successfully.\r
   @retval EFI_UNSUPPORTED     The underlying IO device doesn't support the\r


@@ -144,7 +180,8 @@ typedef
 EFI_STATUS\r
 (EFIAPI *VIRTIO_SET_QUEUE_ADDRESS) (\r
   IN VIRTIO_DEVICE_PROTOCOL  *This,\r
 EFI_STATUS\r
 (EFIAPI *VIRTIO_SET_QUEUE_ADDRESS) (\r
   IN VIRTIO_DEVICE_PROTOCOL  *This,\r

-  IN VRING                   *Ring\r
+  IN VRING                   *Ring,\r
+  IN UINT64                  RingBaseShift\r

   );\r
 \r
 /**\r
   );\r
 \r
 /**\r


@@ -319,6 +356,121 @@ EFI_STATUS
   IN UINT8                   DeviceStatus\r
   );\r
 \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
 ///\r
 ///  This protocol provides an abstraction over the VirtIo transport layer\r


@@ -327,9 +479,13 @@ EFI_STATUS
 ///  outside of the EDK II tree.\r
 ///\r
 struct _VIRTIO_DEVICE_PROTOCOL {\r
 ///  outside of the EDK II tree.\r
 ///\r
 struct _VIRTIO_DEVICE_PROTOCOL {\r

-  /// VirtIo Specification Revision encoded with VIRTIO_SPEC_REVISION()\r
+  //\r
+  // VirtIo Specification Revision encoded with VIRTIO_SPEC_REVISION()\r
+  //\r

   UINT32                      Revision;\r
   UINT32                      Revision;\r

-  /// From the Virtio Spec\r
+  //\r
+  // From the Virtio Spec\r
+  //\r

   INT32                       SubSystemDeviceId;\r
 \r
   VIRTIO_GET_DEVICE_FEATURES  GetDeviceFeatures;\r
   INT32                       SubSystemDeviceId;\r
 \r
   VIRTIO_GET_DEVICE_FEATURES  GetDeviceFeatures;\r


@@ -350,9 +506,19 @@ struct _VIRTIO_DEVICE_PROTOCOL {
   VIRTIO_GET_DEVICE_STATUS    GetDeviceStatus;\r
   VIRTIO_SET_DEVICE_STATUS    SetDeviceStatus;\r
 \r
   VIRTIO_GET_DEVICE_STATUS    GetDeviceStatus;\r
   VIRTIO_SET_DEVICE_STATUS    SetDeviceStatus;\r
 \r

+  //\r

   // Functions to read/write Device Specific headers\r
   // Functions to read/write Device Specific headers\r

+  //\r

   VIRTIO_DEVICE_WRITE         WriteDevice;\r
   VIRTIO_DEVICE_READ          ReadDevice;\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
 \r
 extern EFI_GUID gVirtioDeviceProtocolGuid;\r