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   Copyright (C) 2017, AMD Inc, All rights reserved.<BR>
   8
   9   This program and the accompanying materials are licensed and made available
  10   under the terms and conditions of the BSD License which accompanies this
  11   distribution. The full text of the license may be found at
  12   http://opensource.org/licenses/bsd-license.php
  13
  14   THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, WITHOUT
  15   WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  16
  17 **/
  18
  19 #include <Library/BaseLib.h>
  20 #include <Library/BaseMemoryLib.h>
  21 #include <Library/DebugLib.h>
  22 #include <Library/MemoryAllocationLib.h>
  23 #include <Library/UefiBootServicesTableLib.h>
  24
  25 #include <Library/VirtioLib.h>
  26
  27
  28 /**
  29
  30   Configure a virtio ring.
  31
  32   This function sets up internal storage (the guest-host communication area)
  33   and lays out several "navigation" (ie. no-ownership) pointers to parts of
  34   that storage.
  35
  36   Relevant sections from the virtio-0.9.5 spec:
  37   - 1.1 Virtqueues,
  38   - 2.3 Virtqueue Configuration.
  39
  40   @param[in]                    The number of descriptors to allocate for the
  41                                 virtio ring, as requested by the host.
  42
  43   @param[out] Ring              The virtio ring to set up.
  44
  45   @retval EFI_OUT_OF_RESOURCES  AllocatePages() failed to allocate contiguous
  46                                 pages for the requested QueueSize. Fields of
  47                                 Ring have indeterminate value.
  48
  49   @retval EFI_SUCCESS           Allocation and setup successful. Ring->Base
  50                                 (and nothing else) is responsible for
  51                                 deallocation.
  52
  53 **/
  54 EFI_STATUS
  55 EFIAPI
  56 VirtioRingInit (
  57   IN  UINT16 QueueSize,
  58   OUT VRING  *Ring
  59   )
  60 {
  61   UINTN          RingSize;
  62   volatile UINT8 *RingPagesPtr;
  63
  64   RingSize = ALIGN_VALUE (
  65                sizeof *Ring->Desc            * QueueSize +
  66                sizeof *Ring->Avail.Flags                 +
  67                sizeof *Ring->Avail.Idx                   +
  68                sizeof *Ring->Avail.Ring      * QueueSize +
  69                sizeof *Ring->Avail.UsedEvent,
  70                EFI_PAGE_SIZE);
  71
  72   RingSize += ALIGN_VALUE (
  73                 sizeof *Ring->Used.Flags                  +
  74                 sizeof *Ring->Used.Idx                    +
  75                 sizeof *Ring->Used.UsedElem   * QueueSize +
  76                 sizeof *Ring->Used.AvailEvent,
  77                 EFI_PAGE_SIZE);
  78
  79   Ring->NumPages = EFI_SIZE_TO_PAGES (RingSize);
  80   Ring->Base = AllocatePages (Ring->NumPages);
  81   if (Ring->Base == NULL) {
  82     return EFI_OUT_OF_RESOURCES;
  83   }
  84   SetMem (Ring->Base, RingSize, 0x00);
  85   RingPagesPtr = Ring->Base;
  86
  87   Ring->Desc = (volatile VOID *) RingPagesPtr;
  88   RingPagesPtr += sizeof *Ring->Desc * QueueSize;
  89
  90   Ring->Avail.Flags = (volatile VOID *) RingPagesPtr;
  91   RingPagesPtr += sizeof *Ring->Avail.Flags;
  92
  93   Ring->Avail.Idx = (volatile VOID *) RingPagesPtr;
  94   RingPagesPtr += sizeof *Ring->Avail.Idx;
  95
  96   Ring->Avail.Ring = (volatile VOID *) RingPagesPtr;
  97   RingPagesPtr += sizeof *Ring->Avail.Ring * QueueSize;
  98
  99   Ring->Avail.UsedEvent = (volatile VOID *) RingPagesPtr;
 100   RingPagesPtr += sizeof *Ring->Avail.UsedEvent;
 101
 102   RingPagesPtr = (volatile UINT8 *) Ring->Base +
 103                  ALIGN_VALUE (RingPagesPtr - (volatile UINT8 *) Ring->Base,
 104                    EFI_PAGE_SIZE);
 105
 106   Ring->Used.Flags = (volatile VOID *) RingPagesPtr;
 107   RingPagesPtr += sizeof *Ring->Used.Flags;
 108
 109   Ring->Used.Idx = (volatile VOID *) RingPagesPtr;
 110   RingPagesPtr += sizeof *Ring->Used.Idx;
 111
 112   Ring->Used.UsedElem = (volatile VOID *) RingPagesPtr;
 113   RingPagesPtr += sizeof *Ring->Used.UsedElem * QueueSize;
 114
 115   Ring->Used.AvailEvent = (volatile VOID *) RingPagesPtr;
 116   RingPagesPtr += sizeof *Ring->Used.AvailEvent;
 117
 118   Ring->QueueSize = QueueSize;
 119   return EFI_SUCCESS;
 120 }
 121
 122
 123 /**
 124
 125   Tear down the internal resources of a configured virtio ring.
 126
 127   The caller is responsible to stop the host from using this ring before
 128   invoking this function: the VSTAT_DRIVER_OK bit must be clear in
 129   VhdrDeviceStatus.
 130
 131   @param[out] Ring  The virtio ring to clean up.
 132
 133 **/
 134 VOID
 135 EFIAPI
 136 VirtioRingUninit (
 137   IN OUT VRING *Ring
 138   )
 139 {
 140   FreePages (Ring->Base, Ring->NumPages);
 141   SetMem (Ring, sizeof *Ring, 0x00);
 142 }
 143
 144
 145 /**
 146
 147   Turn off interrupt notifications from the host, and prepare for appending
 148   multiple descriptors to the virtio ring.
 149
 150   The calling driver must be in VSTAT_DRIVER_OK state.
 151
 152   @param[in,out] Ring  The virtio ring we intend to append descriptors to.
 153
 154   @param[out] Indices  The DESC_INDICES structure to initialize.
 155
 156 **/
 157 VOID
 158 EFIAPI
 159 VirtioPrepare (
 160   IN OUT VRING        *Ring,
 161   OUT    DESC_INDICES *Indices
 162   )
 163 {
 164   //
 165   // Prepare for virtio-0.9.5, 2.4.2 Receiving Used Buffers From the Device.
 166   // We're going to poll the answer, the host should not send an interrupt.
 167   //
 168   *Ring->Avail.Flags = (UINT16) VRING_AVAIL_F_NO_INTERRUPT;
 169
 170   //
 171   // Prepare for virtio-0.9.5, 2.4.1 Supplying Buffers to the Device.
 172   //
 173   // Since we support only one in-flight descriptor chain, we can always build
 174   // that chain starting at entry #0 of the descriptor table.
 175   //
 176   Indices->HeadDescIdx = 0;
 177   Indices->NextDescIdx = Indices->HeadDescIdx;
 178 }
 179
 180
 181 /**
 182
 183   Append a contiguous buffer for transmission / reception via the virtio ring.
 184
 185   This function implements the following section from virtio-0.9.5:
 186   - 2.4.1.1 Placing Buffers into the Descriptor Table
 187
 188   Free space is taken as granted, since the individual drivers support only
 189   synchronous requests and host side status is processed in lock-step with
 190   request submission. It is the calling driver's responsibility to verify the
 191   ring size in advance.
 192
 193   The caller is responsible for initializing *Indices with VirtioPrepare()
 194   first.
 195
 196   @param[in,out] Ring        The virtio ring to append the buffer to, as a
 197                              descriptor.
 198
 199   @param[in] BufferPhysAddr  (Guest pseudo-physical) start address of the
 200                              transmit / receive buffer.
 201
 202   @param[in] BufferSize      Number of bytes to transmit or receive.
 203
 204   @param[in] Flags           A bitmask of VRING_DESC_F_* flags. The caller
 205                              computes this mask dependent on further buffers to
 206                              append and transfer direction.
 207                              VRING_DESC_F_INDIRECT is unsupported. The
 208                              VRING_DESC.Next field is always set, but the host
 209                              only interprets it dependent on VRING_DESC_F_NEXT.
 210
 211   @param[in,out] Indices     Indices->HeadDescIdx is not accessed.
 212                              On input, Indices->NextDescIdx identifies the next
 213                              descriptor to carry the buffer. On output,
 214                              Indices->NextDescIdx is incremented by one, modulo
 215                              2^16.
 216
 217 **/
 218 VOID
 219 EFIAPI
 220 VirtioAppendDesc (
 221   IN OUT VRING        *Ring,
 222   IN     UINTN        BufferPhysAddr,
 223   IN     UINT32       BufferSize,
 224   IN     UINT16       Flags,
 225   IN OUT DESC_INDICES *Indices
 226   )
 227 {
 228   volatile VRING_DESC *Desc;
 229
 230   Desc        = &Ring->Desc[Indices->NextDescIdx++ % Ring->QueueSize];
 231   Desc->Addr  = BufferPhysAddr;
 232   Desc->Len   = BufferSize;
 233   Desc->Flags = Flags;
 234   Desc->Next  = Indices->NextDescIdx % Ring->QueueSize;
 235 }
 236
 237
 238 /**
 239
 240   Notify the host about the descriptor chain just built, and wait until the
 241   host processes it.
 242
 243   @param[in] VirtIo       The target virtio device to notify.
 244
 245   @param[in] VirtQueueId  Identifies the queue for the target device.
 246
 247   @param[in,out] Ring     The virtio ring with descriptors to submit.
 248
 249   @param[in] Indices      Indices->NextDescIdx is not accessed.
 250                           Indices->HeadDescIdx identifies the head descriptor
 251                           of the descriptor chain.
 252
 253   @param[out] UsedLen     On success, the total number of bytes, consecutively
 254                           across the buffers linked by the descriptor chain,
 255                           that the host wrote. May be NULL if the caller
 256                           doesn't care, or can compute the same information
 257                           from device-specific request structures linked by the
 258                           descriptor chain.
 259
 260   @return              Error code from VirtIo->SetQueueNotify() if it fails.
 261
 262   @retval EFI_SUCCESS  Otherwise, the host processed all descriptors.
 263
 264 **/
 265 EFI_STATUS
 266 EFIAPI
 267 VirtioFlush (
 268   IN     VIRTIO_DEVICE_PROTOCOL *VirtIo,
 269   IN     UINT16                 VirtQueueId,
 270   IN OUT VRING                  *Ring,
 271   IN     DESC_INDICES           *Indices,
 272   OUT    UINT32                 *UsedLen    OPTIONAL
 273   )
 274 {
 275   UINT16     NextAvailIdx;
 276   UINT16     LastUsedIdx;
 277   EFI_STATUS Status;
 278   UINTN      PollPeriodUsecs;
 279
 280   //
 281   // virtio-0.9.5, 2.4.1.2 Updating the Available Ring
 282   //
 283   // It is not exactly clear from the wording of the virtio-0.9.5
 284   // specification, but each entry in the Available Ring references only the
 285   // head descriptor of any given descriptor chain.
 286   //
 287   NextAvailIdx = *Ring->Avail.Idx;
 288   //
 289   // (Due to our lock-step progress, this is where the host will produce the
 290   // used element with the head descriptor's index in it.)
 291   //
 292   LastUsedIdx = NextAvailIdx;
 293   Ring->Avail.Ring[NextAvailIdx++ % Ring->QueueSize] =
 294     Indices->HeadDescIdx % Ring->QueueSize;
 295
 296   //
 297   // virtio-0.9.5, 2.4.1.3 Updating the Index Field
 298   //
 299   MemoryFence();
 300   *Ring->Avail.Idx = NextAvailIdx;
 301
 302   //
 303   // virtio-0.9.5, 2.4.1.4 Notifying the Device -- gratuitous notifications are
 304   // OK.
 305   //
 306   MemoryFence();
 307   Status = VirtIo->SetQueueNotify (VirtIo, VirtQueueId);
 308   if (EFI_ERROR (Status)) {
 309     return Status;
 310   }
 311
 312   //
 313   // virtio-0.9.5, 2.4.2 Receiving Used Buffers From the Device
 314   // Wait until the host processes and acknowledges our descriptor chain. The
 315   // condition we use for polling is greatly simplified and relies on the
 316   // synchronous, lock-step progress.
 317   //
 318   // Keep slowing down until we reach a poll period of slightly above 1 ms.
 319   //
 320   PollPeriodUsecs = 1;
 321   MemoryFence();
 322   while (*Ring->Used.Idx != NextAvailIdx) {
 323     gBS->Stall (PollPeriodUsecs); // calls AcpiTimerLib::MicroSecondDelay
 324
 325     if (PollPeriodUsecs < 1024) {
 326       PollPeriodUsecs *= 2;
 327     }
 328     MemoryFence();
 329   }
 330
 331   MemoryFence();
 332
 333   if (UsedLen != NULL) {
 334     volatile CONST VRING_USED_ELEM *UsedElem;
 335
 336     UsedElem = &Ring->Used.UsedElem[LastUsedIdx % Ring->QueueSize];
 337     ASSERT (UsedElem->Id == Indices->HeadDescIdx);
 338     *UsedLen = UsedElem->Len;
 339   }
 340
 341   return EFI_SUCCESS;
 342 }
 343
 344
 345 /**
 346
 347   Report the feature bits to the VirtIo 1.0 device that the VirtIo 1.0 driver
 348   understands.
 349
 350   In VirtIo 1.0, a device can reject a self-inconsistent feature bitmap through
 351   the new VSTAT_FEATURES_OK status bit. (For example if the driver requests a
 352   higher level feature but clears a prerequisite feature.) This function is a
 353   small wrapper around VIRTIO_DEVICE_PROTOCOL.SetGuestFeatures() that also
 354   verifies if the VirtIo 1.0 device accepts the feature bitmap.
 355
 356   @param[in]     VirtIo        Report feature bits to this device.
 357
 358   @param[in]     Features      The set of feature bits that the driver wishes
 359                                to report. The caller is responsible to perform
 360                                any masking before calling this function; the
 361                                value is directly written with
 362                                VIRTIO_DEVICE_PROTOCOL.SetGuestFeatures().
 363
 364   @param[in,out] DeviceStatus  On input, the status byte most recently written
 365                                to the device's status register. On output (even
 366                                on error), DeviceStatus will be updated so that
 367                                it is suitable for further status bit
 368                                manipulation and writing to the device's status
 369                                register.
 370
 371   @retval  EFI_SUCCESS      The device accepted the configuration in Features.
 372
 373   @return  EFI_UNSUPPORTED  The device rejected the configuration in Features.
 374
 375   @retval  EFI_UNSUPPORTED  VirtIo->Revision is smaller than 1.0.0.
 376
 377   @return                   Error codes from the SetGuestFeatures(),
 378                             SetDeviceStatus(), GetDeviceStatus() member
 379                             functions.
 380
 381 **/
 382 EFI_STATUS
 383 EFIAPI
 384 Virtio10WriteFeatures (
 385   IN     VIRTIO_DEVICE_PROTOCOL *VirtIo,
 386   IN     UINT64                 Features,
 387   IN OUT UINT8                  *DeviceStatus
 388   )
 389 {
 390   EFI_STATUS Status;
 391
 392   if (VirtIo->Revision < VIRTIO_SPEC_REVISION (1, 0, 0)) {
 393     return EFI_UNSUPPORTED;
 394   }
 395
 396   Status = VirtIo->SetGuestFeatures (VirtIo, Features);
 397   if (EFI_ERROR (Status)) {
 398     return Status;
 399   }
 400
 401   *DeviceStatus |= VSTAT_FEATURES_OK;
 402   Status = VirtIo->SetDeviceStatus (VirtIo, *DeviceStatus);
 403   if (EFI_ERROR (Status)) {
 404     return Status;
 405   }
 406
 407   Status = VirtIo->GetDeviceStatus (VirtIo, DeviceStatus);
 408   if (EFI_ERROR (Status)) {
 409     return Status;
 410   }
 411
 412   if ((*DeviceStatus & VSTAT_FEATURES_OK) == 0) {
 413     Status = EFI_UNSUPPORTED;
 414   }
 415
 416   return Status;
 417 }
 418
 419 /**
 420   Provides the virtio device address required to access system memory from a
 421   DMA bus master.
 422
 423   The interface follows the same usage pattern as defined in UEFI spec 2.6
 424   (Section 13.2 PCI Root Bridge I/O Protocol)
 425
 426   The VirtioMapAllBytesInSharedBuffer() is similar to VIRTIO_MAP_SHARED
 427   with exception that NumberOfBytes is IN-only parameter. The function
 428   maps all the bytes specified in NumberOfBytes param in one consecutive
 429   range.
 430
 431   @param[in]     VirtIo           The virtio device for which the mapping is
 432                                   requested.
 433
 434   @param[in]     Operation        Indicates if the bus master is going to
 435                                   read or write to system memory.
 436
 437   @param[in]     HostAddress      The system memory address to map to shared
 438                                   buffer address.
 439
 440   @param[in]     NumberOfBytes    Number of bytes to map.
 441
 442   @param[out]    DeviceAddress    The resulting shared map address for the
 443                                   bus master to access the hosts HostAddress.
 444
 445   @param[out]    Mapping          A resulting token to pass to
 446                                   VIRTIO_UNMAP_SHARED.
 447
 448
 449   @retval EFI_SUCCESS             The NumberOfBytes is succesfully mapped.
 450   @retval EFI_UNSUPPORTED         The HostAddress cannot be mapped as a
 451                                   common buffer.
 452   @retval EFI_INVALID_PARAMETER   One or more parameters are invalid.
 453   @retval EFI_OUT_OF_RESOURCES    The request could not be completed due to
 454                                   a lack of resources. This includes the case
 455                                   when NumberOfBytes bytes cannot be mapped
 456                                   in one consecutive range.
 457   @retval EFI_DEVICE_ERROR        The system hardware could not map the
 458                                   requested address.
 459 **/
 460 EFI_STATUS
 461 EFIAPI
 462 VirtioMapAllBytesInSharedBuffer (
 463   IN  VIRTIO_DEVICE_PROTOCOL  *VirtIo,
 464   IN  VIRTIO_MAP_OPERATION    Operation,
 465   IN  VOID                    *HostAddress,
 466   IN  UINTN                   NumberOfBytes,
 467   OUT EFI_PHYSICAL_ADDRESS    *DeviceAddress,
 468   OUT VOID                    **Mapping
 469   )
 470 {
 471   EFI_STATUS            Status;
 472   VOID                  *MapInfo;
 473   UINTN                 Size;
 474   EFI_PHYSICAL_ADDRESS  PhysicalAddress;
 475
 476   Size = NumberOfBytes;
 477   Status = VirtIo->MapSharedBuffer (
 478                      VirtIo,
 479                      Operation,
 480                      HostAddress,
 481                      &Size,
 482                      &PhysicalAddress,
 483                      &MapInfo
 484                      );
 485   if (EFI_ERROR (Status)) {
 486     return Status;
 487   }
 488
 489   if (Size < NumberOfBytes) {
 490     goto Failed;
 491   }
 492
 493   *Mapping = MapInfo;
 494   *DeviceAddress = PhysicalAddress;
 495
 496   return EFI_SUCCESS;
 497
 498 Failed:
 499   VirtIo->UnmapSharedBuffer (VirtIo, MapInfo);
 500   return EFI_OUT_OF_RESOURCES;
 501 }