OvmfPkg: adapt VirtioAppendDesc()'s leading comment to the coding style

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

diff --git a/OvmfPkg/Include/Library/VirtioLib.h b/OvmfPkg/Include/Library/VirtioLib.h
index 95657a7111efeb1a9c6762fe3dc00db5fab054b1..990219cca13cec3e0e64113fb897255e06ac77b1 100644 (file)
--- a/OvmfPkg/Include/Library/VirtioLib.h
+++ b/OvmfPkg/Include/Library/VirtioLib.h
@@ -40,8 +40,8 @@
   @return  Status code returned by PciIo->Io.Write().\r
 \r
 **/\r
-EFIAPI\r
 EFI_STATUS\r
+EFIAPI\r
 VirtioWrite (\r
   IN EFI_PCI_IO_PROTOCOL *PciIo,\r
   IN UINTN               FieldOffset,\r
@@ -72,8 +72,8 @@ VirtioWrite (
   @return  Status code returned by PciIo->Io.Read().\r
 \r
 **/\r
-EFIAPI\r
 EFI_STATUS\r
+EFIAPI\r
 VirtioRead (\r
   IN  EFI_PCI_IO_PROTOCOL *PciIo,\r
   IN  UINTN               FieldOffset,\r
@@ -135,53 +135,113 @@ VirtioRingUninit (
   );\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
-  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.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
-  @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
-  @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
-  @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
-  @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
-  @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
-  @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
-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] PciIo        The target virtio PCI 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
+  In *Indices:\r
+\r
+  @param[in] HeadDescIdx  Identifies the head descriptor of the descriptor\r
+                          chain.\r
+\r
+\r
+  @return              Error code from VirtioWrite() 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     EFI_PCI_IO_PROTOCOL *PciIo,\r
+  IN     UINT16              VirtQueueId,\r
+  IN OUT VRING               *Ring,\r
+  IN     DESC_INDICES        *Indices\r
   );\r
 \r
 #endif // _VIRTIO_LIB_H_\r