OvmfPkg, ArmVirtPkg: clean up SetBootOrderFromQemu() parameter list

[mirror_edk2.git] / OvmfPkg / Include / Library / VirtioLib.h

diff --git a/OvmfPkg/Include/Library/VirtioLib.h b/OvmfPkg/Include/Library/VirtioLib.h
index 95657a7111efeb1a9c6762fe3dc00db5fab054b1..5badfb32917fab75f85a8eedb647adb22ee0463b 100644 (file)
--- a/OvmfPkg/Include/Library/VirtioLib.h
+++ b/OvmfPkg/Include/Library/VirtioLib.h
@@ -2,7 +2,7 @@
 \r
   Declarations of utility functions used by virtio device drivers.\r
 \r
 \r
   Declarations of utility functions used by virtio device drivers.\r
 \r

-  Copyright (C) 2012, Red Hat, Inc.\r
+  Copyright (C) 2012-2016, Red Hat, Inc.\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


@@ -17,70 +17,9 @@
 #ifndef _VIRTIO_LIB_H_\r
 #define _VIRTIO_LIB_H_\r
 \r
 #ifndef _VIRTIO_LIB_H_\r
 #define _VIRTIO_LIB_H_\r
 \r

-#include <Protocol/PciIo.h>\r
-#include <IndustryStandard/Virtio.h>\r
-\r
-/**\r
-\r
-  Write a word into Region 0 of the device specified by PciIo.\r
-\r
-  Region 0 must be an iomem region. This is an internal function for the\r
-  driver-specific VIRTIO_CFG_WRITE() macros.\r
-\r
-  @param[in] PciIo        Target PCI device.\r
-\r
-  @param[in] FieldOffset  Destination offset.\r
-\r
-  @param[in] FieldSize    Destination field size, must be in { 1, 2, 4, 8 }.\r
-\r
-  @param[in] Value        Little endian value to write, converted to UINT64.\r
-                          The least significant FieldSize bytes will be used.\r
-\r
-\r
-  @return  Status code returned by PciIo->Io.Write().\r
-\r
-**/\r
-EFIAPI\r
-EFI_STATUS\r
-VirtioWrite (\r
-  IN EFI_PCI_IO_PROTOCOL *PciIo,\r
-  IN UINTN               FieldOffset,\r
-  IN UINTN               FieldSize,\r
-  IN UINT64              Value\r
-  );\r
-\r
-\r
-/**\r
-\r
-  Read a word from Region 0 of the device specified by PciIo.\r
+#include <Protocol/VirtioDevice.h>\r

 \r
 \r

-  Region 0 must be an iomem region. This is an internal function for the\r
-  driver-specific VIRTIO_CFG_READ() macros.\r
-\r
-  @param[in] PciIo        Source PCI device.\r
-\r
-  @param[in] FieldOffset  Source offset.\r
-\r
-  @param[in] FieldSize    Source field size, 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
-\r
-  @return  Status code returned by PciIo->Io.Read().\r
-\r
-**/\r
-EFIAPI\r
-EFI_STATUS\r
-VirtioRead (\r
-  IN  EFI_PCI_IO_PROTOCOL *PciIo,\r
-  IN  UINTN               FieldOffset,\r
-  IN  UINTN               FieldSize,\r
-  IN  UINTN               BufferSize,\r
-  OUT VOID                *Buffer\r
-  );\r
+#include <IndustryStandard/Virtio.h>\r

 \r
 \r
 /**\r
 \r
 \r
 /**\r


@@ -135,53 +74,165 @@ VirtioRingUninit (
   );\r
 \r
 \r
   );\r
 \r
 \r

+//\r
+// Internal use structure for tracking the submission of a multi-descriptor\r
+// request.\r
+//\r
+typedef struct {\r
+  UINT16 HeadDescIdx;\r
+  UINT16 NextDescIdx;\r
+} DESC_INDICES;\r
+\r
+\r
+/**\r
+\r
+  Turn off interrupt notifications from the host, and prepare for appending\r
+  multiple descriptors to the virtio ring.\r
+\r
+  The calling driver must be in VSTAT_DRIVER_OK state.\r
+\r
+  @param[in,out] Ring  The virtio ring we intend to append descriptors to.\r
+\r
+  @param[out] Indices  The DESC_INDICES structure to initialize.\r
+\r
+**/\r
+VOID\r
+EFIAPI\r
+VirtioPrepare (\r
+  IN OUT VRING        *Ring,\r
+  OUT    DESC_INDICES *Indices\r
+  );\r
+\r
+\r

 /**\r
 \r
   Append a contiguous buffer for transmission / reception via the virtio ring.\r
 \r
 /**\r
 \r
   Append a contiguous buffer for transmission / reception via the virtio ring.\r
 \r

-  This function implements the following sections from virtio-0.9.5:\r
+  This function implements the following section from virtio-0.9.5:\r

   - 2.4.1.1 Placing Buffers into the Descriptor Table\r
   - 2.4.1.1 Placing Buffers into the Descriptor Table\r

-  - 2.4.1.2 Updating the Available Ring\r

 \r
   Free space is taken as granted, since the individual drivers support only\r
   synchronous requests and host side status is processed in lock-step with\r
   request submission. It is the calling driver's responsibility to verify the\r
   ring size in advance.\r
 \r
 \r
   Free space is taken as granted, since the individual drivers support only\r
   synchronous requests and host side status is processed in lock-step with\r
   request submission. It is the calling driver's responsibility to verify the\r
   ring size in advance.\r
 \r

-  @param[in out] Ring           The virtio ring to append the buffer to, as a\r
-                                descriptor.\r
+  The caller is responsible for initializing *Indices with VirtioPrepare()\r
+  first.\r

 \r
 \r

-  @param [in] BufferPhysAddr    (Guest pseudo-physical) start address of the\r
-                                transmit / receive buffer.\r
+  @param[in,out] Ring        The virtio ring to append the buffer to, as a\r
+                             descriptor.\r

 \r
 \r

-  @param [in] BufferSize        Number of bytes to transmit or receive.\r
+  @param[in] BufferPhysAddr  (Guest pseudo-physical) start address of the\r
+                             transmit / receive buffer.\r

 \r
 \r

-  @param [in] Flags             A bitmask of VRING_DESC_F_* flags. The caller\r
-                                computes this mask dependent on further buffers\r
-                                to append and transfer direction.\r
-                                VRING_DESC_F_INDIRECT is unsupported. The\r
-                                VRING_DESC.Next field is always set, but the\r
-                                host only interprets it dependent on\r
-                                VRING_DESC_F_NEXT.\r
+  @param[in] BufferSize      Number of bytes to transmit or receive.\r

 \r
 \r

-  @param [in] HeadIdx           The index identifying the head buffer (first\r
-                                buffer appended) belonging to this same\r
-                                request.\r
+  @param[in] Flags           A bitmask of VRING_DESC_F_* flags. The caller\r
+                             computes this mask dependent on further buffers to\r
+                             append and transfer direction.\r
+                             VRING_DESC_F_INDIRECT is unsupported. The\r
+                             VRING_DESC.Next field is always set, but the host\r
+                             only interprets it dependent on VRING_DESC_F_NEXT.\r

 \r
 \r

-  @param [in out] NextAvailIdx  On input, the index identifying the next\r
-                                descriptor available to carry the buffer. On\r
-                                output, incremented by one, modulo 2^16.\r
+  @param[in,out] Indices     Indices->HeadDescIdx is not accessed.\r
+                             On input, Indices->NextDescIdx identifies the next\r
+                             descriptor to carry the buffer. On output,\r
+                             Indices->NextDescIdx is incremented by one, modulo\r
+                             2^16.\r

 \r
 **/\r
 VOID\r
 EFIAPI\r
 \r
 **/\r
 VOID\r
 EFIAPI\r

-AppendDesc (\r
-  IN OUT VRING  *Ring,\r
-  IN     UINTN  BufferPhysAddr,\r
-  IN     UINT32 BufferSize,\r
-  IN     UINT16 Flags,\r
-  IN     UINT16 HeadIdx,\r
-  IN OUT UINT16 *NextAvailIdx\r
+VirtioAppendDesc (\r
+  IN OUT VRING        *Ring,\r
+  IN     UINTN        BufferPhysAddr,\r
+  IN     UINT32       BufferSize,\r
+  IN     UINT16       Flags,\r
+  IN OUT DESC_INDICES *Indices\r
+  );\r
+\r
+\r
+/**\r
+\r
+  Notify the host about the descriptor chain just built, and wait until the\r
+  host processes it.\r
+\r
+  @param[in] VirtIo       The target virtio device to notify.\r
+\r
+  @param[in] VirtQueueId  Identifies the queue for the target device.\r
+\r
+  @param[in,out] Ring     The virtio ring with descriptors to submit.\r
+\r
+  @param[in] Indices      Indices->NextDescIdx is not accessed.\r
+                          Indices->HeadDescIdx identifies the head descriptor\r
+                          of the descriptor chain.\r
+\r
+  @param[out] UsedLen     On success, the total number of bytes, consecutively\r
+                          across the buffers linked by the descriptor chain,\r
+                          that the host wrote. May be NULL if the caller\r
+                          doesn't care, or can compute the same information\r
+                          from device-specific request structures linked by the\r
+                          descriptor chain.\r
+\r
+  @return              Error code from VirtIo->SetQueueNotify() if it fails.\r
+\r
+  @retval EFI_SUCCESS  Otherwise, the host processed all descriptors.\r
+\r
+**/\r
+EFI_STATUS\r
+EFIAPI\r
+VirtioFlush (\r
+  IN     VIRTIO_DEVICE_PROTOCOL *VirtIo,\r
+  IN     UINT16                 VirtQueueId,\r
+  IN OUT VRING                  *Ring,\r
+  IN     DESC_INDICES           *Indices,\r
+  OUT    UINT32                 *UsedLen    OPTIONAL\r
+  );\r
+\r
+\r
+/**\r
+\r
+  Report the feature bits to the VirtIo 1.0 device that the VirtIo 1.0 driver\r
+  understands.\r
+\r
+  In VirtIo 1.0, a device can reject a self-inconsistent feature bitmap through\r
+  the new VSTAT_FEATURES_OK status bit. (For example if the driver requests a\r
+  higher level feature but clears a prerequisite feature.) This function is a\r
+  small wrapper around VIRTIO_DEVICE_PROTOCOL.SetGuestFeatures() that also\r
+  verifies if the VirtIo 1.0 device accepts the feature bitmap.\r
+\r
+  @param[in]     VirtIo        Report feature bits to this device.\r
+\r
+  @param[in]     Features      The set of feature bits that the driver wishes\r
+                               to report. The caller is responsible to perform\r
+                               any masking before calling this function; the\r
+                               value is directly written with\r
+                               VIRTIO_DEVICE_PROTOCOL.SetGuestFeatures().\r
+\r
+  @param[in,out] DeviceStatus  On input, the status byte most recently written\r
+                               to the device's status register. On output (even\r
+                               on error), DeviceStatus will be updated so that\r
+                               it is suitable for further status bit\r
+                               manipulation and writing to the device's status\r
+                               register.\r
+\r
+  @retval  EFI_SUCCESS      The device accepted the configuration in Features.\r
+\r
+  @return  EFI_UNSUPPORTED  The device rejected the configuration in Features.\r
+\r
+  @retval  EFI_UNSUPPORTED  VirtIo->Revision is smaller than 1.0.0.\r
+\r
+  @return                   Error codes from the SetGuestFeatures(),\r
+                            SetDeviceStatus(), GetDeviceStatus() member\r
+                            functions.\r
+\r
+**/\r
+EFI_STATUS\r
+EFIAPI\r
+Virtio10WriteFeatures (\r
+  IN     VIRTIO_DEVICE_PROTOCOL *VirtIo,\r
+  IN     UINT64                 Features,\r
+  IN OUT UINT8                  *DeviceStatus\r

   );\r
 \r
 #endif // _VIRTIO_LIB_H_\r
   );\r
 \r
 #endif // _VIRTIO_LIB_H_\r