[mirror_edk2.git] / OvmfPkg / Library / VirtioLib / VirtioLib.c

/** @file\r
\r
  Utility functions used by virtio device drivers.\r
\r
  Copyright (C) 2012-2016, Red Hat, Inc.\r
  Portion of Copyright (C) 2013, ARM Ltd.\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
#include <Library/BaseLib.h>\r
#include <Library/BaseMemoryLib.h>\r
#include <Library/DebugLib.h>\r
#include <Library/MemoryAllocationLib.h>\r
#include <Library/UefiBootServicesTableLib.h>\r
\r
#include <Library/VirtioLib.h>\r
\r
\r
/**\r
\r
  Configure a virtio ring.\r
\r
  This function sets up internal storage (the guest-host communication area)\r
  and lays out several "navigation" (ie. no-ownership) pointers to parts of\r
  that storage.\r
\r
  Relevant sections from the virtio-0.9.5 spec:\r
  - 1.1 Virtqueues,\r
  - 2.3 Virtqueue Configuration.\r
\r
  @param[in]                    The number of descriptors to allocate for the\r
                                virtio ring, as requested by the host.\r
\r
  @param[out] Ring              The virtio ring to set up.\r
\r
  @retval EFI_OUT_OF_RESOURCES  AllocatePages() failed to allocate contiguous\r
                                pages for the requested QueueSize. Fields of\r
                                Ring have indeterminate value.\r
\r
  @retval EFI_SUCCESS           Allocation and setup successful. Ring->Base\r
                                (and nothing else) is responsible for\r
                                deallocation.\r
\r
**/\r
EFI_STATUS\r
EFIAPI\r
VirtioRingInit (\r
  IN  UINT16 QueueSize,\r
  OUT VRING  *Ring\r
  )\r
{\r
  UINTN          RingSize;\r
  volatile UINT8 *RingPagesPtr;\r
\r
  RingSize = ALIGN_VALUE (\r
               sizeof *Ring->Desc            * QueueSize +\r
               sizeof *Ring->Avail.Flags                 +\r
               sizeof *Ring->Avail.Idx                   +\r
               sizeof *Ring->Avail.Ring      * QueueSize +\r
               sizeof *Ring->Avail.UsedEvent,\r
               EFI_PAGE_SIZE);\r
\r
  RingSize += ALIGN_VALUE (\r
                sizeof *Ring->Used.Flags                  +\r
                sizeof *Ring->Used.Idx                    +\r
                sizeof *Ring->Used.UsedElem   * QueueSize +\r
                sizeof *Ring->Used.AvailEvent,\r
                EFI_PAGE_SIZE);\r
\r
  Ring->NumPages = EFI_SIZE_TO_PAGES (RingSize);\r
  Ring->Base = AllocatePages (Ring->NumPages);\r
  if (Ring->Base == NULL) {\r
    return EFI_OUT_OF_RESOURCES;\r
  }\r
  SetMem (Ring->Base, RingSize, 0x00);\r
  RingPagesPtr = Ring->Base;\r
\r
  Ring->Desc = (volatile VOID *) RingPagesPtr;\r
  RingPagesPtr += sizeof *Ring->Desc * QueueSize;\r
\r
  Ring->Avail.Flags = (volatile VOID *) RingPagesPtr;\r
  RingPagesPtr += sizeof *Ring->Avail.Flags;\r
\r
  Ring->Avail.Idx = (volatile VOID *) RingPagesPtr;\r
  RingPagesPtr += sizeof *Ring->Avail.Idx;\r
\r
  Ring->Avail.Ring = (volatile VOID *) RingPagesPtr;\r
  RingPagesPtr += sizeof *Ring->Avail.Ring * QueueSize;\r
\r
  Ring->Avail.UsedEvent = (volatile VOID *) RingPagesPtr;\r
  RingPagesPtr += sizeof *Ring->Avail.UsedEvent;\r
\r
  RingPagesPtr = (volatile UINT8 *) Ring->Base +\r
                 ALIGN_VALUE (RingPagesPtr - (volatile UINT8 *) Ring->Base,\r
                   EFI_PAGE_SIZE);\r
\r
  Ring->Used.Flags = (volatile VOID *) RingPagesPtr;\r
  RingPagesPtr += sizeof *Ring->Used.Flags;\r
\r
  Ring->Used.Idx = (volatile VOID *) RingPagesPtr;\r
  RingPagesPtr += sizeof *Ring->Used.Idx;\r
\r
  Ring->Used.UsedElem = (volatile VOID *) RingPagesPtr;\r
  RingPagesPtr += sizeof *Ring->Used.UsedElem * QueueSize;\r
\r
  Ring->Used.AvailEvent = (volatile VOID *) RingPagesPtr;\r
  RingPagesPtr += sizeof *Ring->Used.AvailEvent;\r
\r
  Ring->QueueSize = QueueSize;\r
  return EFI_SUCCESS;\r
}\r
\r
\r
/**\r
\r
  Tear down the internal resources of a configured virtio ring.\r
\r
  The caller is responsible to stop the host from using this ring before\r
  invoking this function: the VSTAT_DRIVER_OK bit must be clear in\r
  VhdrDeviceStatus.\r
\r
  @param[out] Ring  The virtio ring to clean up.\r
\r
**/\r
VOID\r
EFIAPI\r
VirtioRingUninit (\r
  IN OUT VRING *Ring\r
  )\r
{\r
  FreePages (Ring->Base, Ring->NumPages);\r
  SetMem (Ring, sizeof *Ring, 0x00);\r
}\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
  // Prepare for virtio-0.9.5, 2.4.2 Receiving Used Buffers From the Device.\r
  // We're going to poll the answer, the host should not send an interrupt.\r
  //\r
  *Ring->Avail.Flags = (UINT16) VRING_AVAIL_F_NO_INTERRUPT;\r
\r
  //\r
  // Prepare for virtio-0.9.5, 2.4.1 Supplying Buffers to the Device.\r
  //\r
  // Since we support only one in-flight descriptor chain, we can always build\r
  // that chain starting at entry #0 of the descriptor table.\r
  //\r
  Indices->HeadDescIdx = 0;\r
  Indices->NextDescIdx = Indices->HeadDescIdx;\r
}\r
\r
\r
/**\r
\r
  Append a contiguous buffer for transmission / reception via the virtio ring.\r
\r
  This function implements the following section from virtio-0.9.5:\r
  - 2.4.1.1 Placing Buffers into the Descriptor Table\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
  The caller is responsible for initializing *Indices with VirtioPrepare()\r
  first.\r
\r
  @param[in,out] Ring        The virtio ring to append the buffer to, as a\r
                             descriptor.\r
\r
  @param[in] BufferPhysAddr  (Guest pseudo-physical) start address of the\r
                             transmit / receive buffer.\r
\r
  @param[in] BufferSize      Number of bytes to transmit or receive.\r
\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] 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
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
  volatile VRING_DESC *Desc;\r
\r
  Desc        = &Ring->Desc[Indices->NextDescIdx++ % Ring->QueueSize];\r
  Desc->Addr  = BufferPhysAddr;\r
  Desc->Len   = BufferSize;\r
  Desc->Flags = Flags;\r
  Desc->Next  = Indices->NextDescIdx % Ring->QueueSize;\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
  UINT16     NextAvailIdx;\r
  UINT16     LastUsedIdx;\r
  EFI_STATUS Status;\r
  UINTN      PollPeriodUsecs;\r
\r
  //\r
  // virtio-0.9.5, 2.4.1.2 Updating the Available Ring\r
  //\r
  // It is not exactly clear from the wording of the virtio-0.9.5\r
  // specification, but each entry in the Available Ring references only the\r
  // head descriptor of any given descriptor chain.\r
  //\r
  NextAvailIdx = *Ring->Avail.Idx;\r
  //\r
  // (Due to our lock-step progress, this is where the host will produce the\r
  // used element with the head descriptor's index in it.)\r
  //\r
  LastUsedIdx = NextAvailIdx;\r
  Ring->Avail.Ring[NextAvailIdx++ % Ring->QueueSize] =\r
    Indices->HeadDescIdx % Ring->QueueSize;\r
\r
  //\r
  // virtio-0.9.5, 2.4.1.3 Updating the Index Field\r
  //\r
  MemoryFence();\r
  *Ring->Avail.Idx = NextAvailIdx;\r
\r
  //\r
  // virtio-0.9.5, 2.4.1.4 Notifying the Device -- gratuitous notifications are\r
  // OK.\r
  //\r
  MemoryFence();\r
  Status = VirtIo->SetQueueNotify (VirtIo, VirtQueueId);\r
  if (EFI_ERROR (Status)) {\r
    return Status;\r
  }\r
\r
  //\r
  // virtio-0.9.5, 2.4.2 Receiving Used Buffers From the Device\r
  // Wait until the host processes and acknowledges our descriptor chain. The\r
  // condition we use for polling is greatly simplified and relies on the\r
  // synchronous, lock-step progress.\r
  //\r
  // Keep slowing down until we reach a poll period of slightly above 1 ms.\r
  //\r
  PollPeriodUsecs = 1;\r
  MemoryFence();\r
  while (*Ring->Used.Idx != NextAvailIdx) {\r
    gBS->Stall (PollPeriodUsecs); // calls AcpiTimerLib::MicroSecondDelay\r
\r
    if (PollPeriodUsecs < 1024) {\r
      PollPeriodUsecs *= 2;\r
    }\r
    MemoryFence();\r
  }\r
\r
  MemoryFence();\r
\r
  if (UsedLen != NULL) {\r
    volatile CONST VRING_USED_ELEM *UsedElem;\r
\r
    UsedElem = &Ring->Used.UsedElem[LastUsedIdx % Ring->QueueSize];\r
    ASSERT (UsedElem->Id == Indices->HeadDescIdx);\r
    *UsedLen = UsedElem->Len;\r
  }\r
\r
  return EFI_SUCCESS;\r
}\r
Commit	Line	Data
263559b8	1	/** @file\r
	2	\r
	3	Utility functions used by virtio device drivers.\r
	4	\r
8bc951a2	5	Copyright (C) 2012-2016, Red Hat, Inc.\r
56f65ed8	6	Portion of Copyright (C) 2013, ARM Ltd.\r
263559b8	7	\r
	8	This program and the accompanying materials are licensed and made available\r
	9	under the terms and conditions of the BSD License which accompanies this\r
	10	distribution. The full text of the license may be found at\r
	11	http://opensource.org/licenses/bsd-license.php\r
	12	\r
	13	THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, WITHOUT\r
	14	WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.\r
	15	\r
	16	**/\r
	17	\r
e371e7e5	18	#include <Library/BaseLib.h>\r
263559b8	19	#include <Library/BaseMemoryLib.h>\r
	20	#include <Library/DebugLib.h>\r
	21	#include <Library/MemoryAllocationLib.h>\r
e371e7e5	22	#include <Library/UefiBootServicesTableLib.h>\r
263559b8	23	\r
	24	#include <Library/VirtioLib.h>\r
	25	\r
	26	\r
263559b8	27	/**\r
	28	\r
	29	Configure a virtio ring.\r
	30	\r
	31	This function sets up internal storage (the guest-host communication area)\r
	32	and lays out several "navigation" (ie. no-ownership) pointers to parts of\r
	33	that storage.\r
	34	\r
	35	Relevant sections from the virtio-0.9.5 spec:\r
	36	- 1.1 Virtqueues,\r
	37	- 2.3 Virtqueue Configuration.\r
	38	\r
	39	@param[in] The number of descriptors to allocate for the\r
	40	virtio ring, as requested by the host.\r
	41	\r
	42	@param[out] Ring The virtio ring to set up.\r
	43	\r
	44	@retval EFI_OUT_OF_RESOURCES AllocatePages() failed to allocate contiguous\r
	45	pages for the requested QueueSize. Fields of\r
	46	Ring have indeterminate value.\r
	47	\r
	48	@retval EFI_SUCCESS Allocation and setup successful. Ring->Base\r
	49	(and nothing else) is responsible for\r
	50	deallocation.\r
	51	\r
	52	**/\r
	53	EFI_STATUS\r
	54	EFIAPI\r
	55	VirtioRingInit (\r
	56	IN UINT16 QueueSize,\r
	57	OUT VRING *Ring\r
	58	)\r
	59	{\r
	60	UINTN RingSize;\r
	61	volatile UINT8 *RingPagesPtr;\r
	62	\r
	63	RingSize = ALIGN_VALUE (\r
	64	sizeof Ring->Desc QueueSize +\r
	65	sizeof *Ring->Avail.Flags +\r
	66	sizeof *Ring->Avail.Idx +\r
	67	sizeof Ring->Avail.Ring QueueSize +\r
	68	sizeof *Ring->Avail.UsedEvent,\r
	69	EFI_PAGE_SIZE);\r
	70	\r
	71	RingSize += ALIGN_VALUE (\r
	72	sizeof *Ring->Used.Flags +\r
	73	sizeof *Ring->Used.Idx +\r
	74	sizeof Ring->Used.UsedElem QueueSize +\r
	75	sizeof *Ring->Used.AvailEvent,\r
	76	EFI_PAGE_SIZE);\r
	77	\r
	78	Ring->NumPages = EFI_SIZE_TO_PAGES (RingSize);\r
	79	Ring->Base = AllocatePages (Ring->NumPages);\r
	80	if (Ring->Base == NULL) {\r
	81	return EFI_OUT_OF_RESOURCES;\r
	82	}\r
	83	SetMem (Ring->Base, RingSize, 0x00);\r
	84	RingPagesPtr = Ring->Base;\r
	85	\r
	86	Ring->Desc = (volatile VOID *) RingPagesPtr;\r
	87	RingPagesPtr += sizeof Ring->Desc QueueSize;\r
	88	\r
	89	Ring->Avail.Flags = (volatile VOID *) RingPagesPtr;\r
	90	RingPagesPtr += sizeof *Ring->Avail.Flags;\r
91	\r
92	Ring->Avail.Idx = (volatile VOID *) RingPagesPtr;\r
93	RingPagesPtr += sizeof *Ring->Avail.Idx;\r
94	\r
95	Ring->Avail.Ring = (volatile VOID *) RingPagesPtr;\r
96	RingPagesPtr += sizeof Ring->Avail.Ring QueueSize;\r
97	\r
98	Ring->Avail.UsedEvent = (volatile VOID *) RingPagesPtr;\r
99	RingPagesPtr += sizeof *Ring->Avail.UsedEvent;\r
100	\r
101	RingPagesPtr = (volatile UINT8 *) Ring->Base +\r
102	ALIGN_VALUE (RingPagesPtr - (volatile UINT8 *) Ring->Base,\r
103	EFI_PAGE_SIZE);\r
104	\r
105	Ring->Used.Flags = (volatile VOID *) RingPagesPtr;\r
106	RingPagesPtr += sizeof *Ring->Used.Flags;\r
107	\r
108	Ring->Used.Idx = (volatile VOID *) RingPagesPtr;\r
109	RingPagesPtr += sizeof *Ring->Used.Idx;\r
110	\r
111	Ring->Used.UsedElem = (volatile VOID *) RingPagesPtr;\r
112	RingPagesPtr += sizeof Ring->Used.UsedElem QueueSize;\r
113	\r
114	Ring->Used.AvailEvent = (volatile VOID *) RingPagesPtr;\r
115	RingPagesPtr += sizeof *Ring->Used.AvailEvent;\r
116	\r
117	Ring->QueueSize = QueueSize;\r
118	return EFI_SUCCESS;\r
119	}\r
120	\r
121	\r
122	/**\r
123	\r
124	Tear down the internal resources of a configured virtio ring.\r
125	\r
126	The caller is responsible to stop the host from using this ring before\r
127	invoking this function: the VSTAT_DRIVER_OK bit must be clear in\r
128	VhdrDeviceStatus.\r
129	\r
130	@param[out] Ring The virtio ring to clean up.\r
131	\r
132	**/\r
133	VOID\r
134	EFIAPI\r
135	VirtioRingUninit (\r
136	IN OUT VRING *Ring\r
137	)\r
138	{\r
139	FreePages (Ring->Base, Ring->NumPages);\r
140	SetMem (Ring, sizeof *Ring, 0x00);\r
141	}\r
142	\r
143	\r
e371e7e5	144	/**\r
	145	\r
	146	Turn off interrupt notifications from the host, and prepare for appending\r
	147	multiple descriptors to the virtio ring.\r
	148	\r
	149	The calling driver must be in VSTAT_DRIVER_OK state.\r
	150	\r
f2965f4e	151	@param[in,out] Ring The virtio ring we intend to append descriptors to.\r
e371e7e5	152	\r
	153	@param[out] Indices The DESC_INDICES structure to initialize.\r
	154	\r
	155	**/\r
	156	VOID\r
	157	EFIAPI\r
	158	VirtioPrepare (\r
	159	IN OUT VRING *Ring,\r
	160	OUT DESC_INDICES *Indices\r
	161	)\r
	162	{\r
	163	//\r
	164	// Prepare for virtio-0.9.5, 2.4.2 Receiving Used Buffers From the Device.\r
	165	// We're going to poll the answer, the host should not send an interrupt.\r
	166	//\r
	167	*Ring->Avail.Flags = (UINT16) VRING_AVAIL_F_NO_INTERRUPT;\r
	168	\r
	169	//\r
	170	// Prepare for virtio-0.9.5, 2.4.1 Supplying Buffers to the Device.\r
	171	//\r
635a3ca2	172	// Since we support only one in-flight descriptor chain, we can always build\r
	173	// that chain starting at entry #0 of the descriptor table.\r
	174	//\r
	175	Indices->HeadDescIdx = 0;\r
	176	Indices->NextDescIdx = Indices->HeadDescIdx;\r
e371e7e5	177	}\r
	178	\r
	179	\r
263559b8	180	/**\r
	181	\r
	182	Append a contiguous buffer for transmission / reception via the virtio ring.\r
	183	\r
635a3ca2	184	This function implements the following section from virtio-0.9.5:\r
263559b8	185	- 2.4.1.1 Placing Buffers into the Descriptor Table\r
263559b8	186	\r
	187	Free space is taken as granted, since the individual drivers support only\r
	188	synchronous requests and host side status is processed in lock-step with\r
	189	request submission. It is the calling driver's responsibility to verify the\r
	190	ring size in advance.\r
	191	\r
e371e7e5	192	The caller is responsible for initializing *Indices with VirtioPrepare()\r
	193	first.\r
	194	\r
11a5fdf4	195	@param[in,out] Ring The virtio ring to append the buffer to, as a\r
	196	descriptor.\r
	197	\r
	198	@param[in] BufferPhysAddr (Guest pseudo-physical) start address of the\r
	199	transmit / receive buffer.\r
	200	\r
	201	@param[in] BufferSize Number of bytes to transmit or receive.\r
	202	\r
	203	@param[in] Flags A bitmask of VRING_DESC_F_* flags. The caller\r
	204	computes this mask dependent on further buffers to\r
	205	append and transfer direction.\r
	206	VRING_DESC_F_INDIRECT is unsupported. The\r
	207	VRING_DESC.Next field is always set, but the host\r
	208	only interprets it dependent on VRING_DESC_F_NEXT.\r
	209	\r
	210	@param[in,out] Indices Indices->HeadDescIdx is not accessed.\r
	211	On input, Indices->NextDescIdx identifies the next\r
	212	descriptor to carry the buffer. On output,\r
	213	Indices->NextDescIdx is incremented by one, modulo\r
	214	2^16.\r
263559b8	215	\r
	216	**/\r
	217	VOID\r
	218	EFIAPI\r
7fcacd6c	219	VirtioAppendDesc (\r
e371e7e5	220	IN OUT VRING *Ring,\r
	221	IN UINTN BufferPhysAddr,\r
	222	IN UINT32 BufferSize,\r
	223	IN UINT16 Flags,\r
	224	IN OUT DESC_INDICES *Indices\r
263559b8	225	)\r
	226	{\r
	227	volatile VRING_DESC *Desc;\r
	228	\r
635a3ca2	229	Desc = &Ring->Desc[Indices->NextDescIdx++ % Ring->QueueSize];\r
263559b8	230	Desc->Addr = BufferPhysAddr;\r
	231	Desc->Len = BufferSize;\r
	232	Desc->Flags = Flags;\r
635a3ca2	233	Desc->Next = Indices->NextDescIdx % Ring->QueueSize;\r
e371e7e5	234	}\r
	235	\r
	236	\r
	237	/**\r
	238	\r
635a3ca2	239	Notify the host about the descriptor chain just built, and wait until the\r
635a3ca2	240	host processes it.\r
e371e7e5	241	\r
56f65ed8	242	@param[in] VirtIo The target virtio device to notify.\r
e371e7e5	243	\r
	244	@param[in] VirtQueueId Identifies the queue for the target device.\r
	245	\r
a7615fa8	246	@param[in,out] Ring The virtio ring with descriptors to submit.\r
e371e7e5	247	\r
a7615fa8	248	@param[in] Indices Indices->NextDescIdx is not accessed.\r
	249	Indices->HeadDescIdx identifies the head descriptor\r
	250	of the descriptor chain.\r
e371e7e5	251	\r
8bc951a2 LE	252	@param[out] UsedLen On success, the total number of bytes, consecutively\r
	253	across the buffers linked by the descriptor chain,\r
	254	that the host wrote. May be NULL if the caller\r
	255	doesn't care, or can compute the same information\r
	256	from device-specific request structures linked by the\r
	257	descriptor chain.\r
e371e7e5	258	\r
56f65ed8	259	@return Error code from VirtIo->SetQueueNotify() if it fails.\r
e371e7e5	260	\r
	261	@retval EFI_SUCCESS Otherwise, the host processed all descriptors.\r
	262	\r
	263	**/\r
	264	EFI_STATUS\r
	265	EFIAPI\r
	266	VirtioFlush (\r
56f65ed8 OM	267	IN VIRTIO_DEVICE_PROTOCOL *VirtIo,\r
	268	IN UINT16 VirtQueueId,\r
	269	IN OUT VRING *Ring,\r
8bc951a2 LE	270	IN DESC_INDICES *Indices,\r
8bc951a2 LE	271	OUT UINT32 *UsedLen OPTIONAL\r
e371e7e5	272	)\r
e371e7e5	273	{\r
635a3ca2	274	UINT16 NextAvailIdx;\r
8bc951a2	275	UINT16 LastUsedIdx;\r
e371e7e5	276	EFI_STATUS Status;\r
	277	UINTN PollPeriodUsecs;\r
	278	\r
635a3ca2	279	//\r
	280	// virtio-0.9.5, 2.4.1.2 Updating the Available Ring\r
	281	//\r
	282	// It is not exactly clear from the wording of the virtio-0.9.5\r
	283	// specification, but each entry in the Available Ring references only the\r
	284	// head descriptor of any given descriptor chain.\r
	285	//\r
	286	NextAvailIdx = *Ring->Avail.Idx;\r
8bc951a2 LE	287	//\r
	288	// (Due to our lock-step progress, this is where the host will produce the\r
	289	// used element with the head descriptor's index in it.)\r
	290	//\r
	291	LastUsedIdx = NextAvailIdx;\r
635a3ca2	292	Ring->Avail.Ring[NextAvailIdx++ % Ring->QueueSize] =\r
	293	Indices->HeadDescIdx % Ring->QueueSize;\r
	294	\r
e371e7e5	295	//\r
	296	// virtio-0.9.5, 2.4.1.3 Updating the Index Field\r
	297	//\r
	298	MemoryFence();\r
635a3ca2	299	*Ring->Avail.Idx = NextAvailIdx;\r
e371e7e5	300	\r
	301	//\r
	302	// virtio-0.9.5, 2.4.1.4 Notifying the Device -- gratuitous notifications are\r
	303	// OK.\r
	304	//\r
	305	MemoryFence();\r
56f65ed8	306	Status = VirtIo->SetQueueNotify (VirtIo, VirtQueueId);\r
e371e7e5	307	if (EFI_ERROR (Status)) {\r
	308	return Status;\r
	309	}\r
	310	\r
	311	//\r
	312	// virtio-0.9.5, 2.4.2 Receiving Used Buffers From the Device\r
	313	// Wait until the host processes and acknowledges our descriptor chain. The\r
	314	// condition we use for polling is greatly simplified and relies on the\r
	315	// synchronous, lock-step progress.\r
	316	//\r
	317	// Keep slowing down until we reach a poll period of slightly above 1 ms.\r
	318	//\r
	319	PollPeriodUsecs = 1;\r
	320	MemoryFence();\r
635a3ca2	321	while (*Ring->Used.Idx != NextAvailIdx) {\r
e371e7e5	322	gBS->Stall (PollPeriodUsecs); // calls AcpiTimerLib::MicroSecondDelay\r
	323	\r
	324	if (PollPeriodUsecs < 1024) {\r
	325	PollPeriodUsecs *= 2;\r
	326	}\r
	327	MemoryFence();\r
	328	}\r
	329	\r
dc9447bd	330	MemoryFence();\r
8bc951a2 LE	331	\r
	332	if (UsedLen != NULL) {\r
	333	volatile CONST VRING_USED_ELEM *UsedElem;\r
	334	\r
	335	UsedElem = &Ring->Used.UsedElem[LastUsedIdx % Ring->QueueSize];\r
	336	ASSERT (UsedElem->Id == Indices->HeadDescIdx);\r
	337	*UsedLen = UsedElem->Len;\r
	338	}\r
	339	\r
e371e7e5	340	return EFI_SUCCESS;\r
263559b8	341	}\r