OvmfPkg/Library/VirtioLib/VirtioLib.c

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