OvmfPkg/Include/Library/VirtioLib.h

   1 /** @file
   2
   3   Declarations of utility functions used by virtio device drivers.
   4
   5   Copyright (C) 2012-2016, Red Hat, Inc.
   6   Copyright (C) 2017, AMD Inc, All rights reserved.<BR>
   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 #ifndef _VIRTIO_LIB_H_
  19 #define _VIRTIO_LIB_H_
  20
  21 #include <Protocol/VirtioDevice.h>
  22
  23 #include <IndustryStandard/Virtio.h>
  24
  25
  26 /**
  27
  28   Configure a virtio ring.
  29
  30   This function sets up internal storage (the guest-host communication area)
  31   and lays out several "navigation" (ie. no-ownership) pointers to parts of
  32   that storage.
  33
  34   Relevant sections from the virtio-0.9.5 spec:
  35   - 1.1 Virtqueues,
  36   - 2.3 Virtqueue Configuration.
  37
  38   @param[in]                    The number of descriptors to allocate for the
  39                                 virtio ring, as requested by the host.
  40
  41   @param[out] Ring              The virtio ring to set up.
  42
  43   @retval EFI_OUT_OF_RESOURCES  AllocatePages() failed to allocate contiguous
  44                                 pages for the requested QueueSize. Fields of
  45                                 Ring have indeterminate value.
  46
  47   @retval EFI_SUCCESS           Allocation and setup successful. Ring->Base
  48                                 (and nothing else) is responsible for
  49                                 deallocation.
  50
  51 **/
  52 EFI_STATUS
  53 EFIAPI
  54 VirtioRingInit (
  55   IN  UINT16 QueueSize,
  56   OUT VRING  *Ring
  57   );
  58
  59
  60 /**
  61
  62   Tear down the internal resources of a configured virtio ring.
  63
  64   The caller is responsible to stop the host from using this ring before
  65   invoking this function: the VSTAT_DRIVER_OK bit must be clear in
  66   VhdrDeviceStatus.
  67
  68   @param[out] Ring  The virtio ring to clean up.
  69
  70 **/
  71 VOID
  72 EFIAPI
  73 VirtioRingUninit (
  74   IN OUT VRING *Ring
  75   );
  76
  77
  78 //
  79 // Internal use structure for tracking the submission of a multi-descriptor
  80 // request.
  81 //
  82 typedef struct {
  83   UINT16 HeadDescIdx;
  84   UINT16 NextDescIdx;
  85 } DESC_INDICES;
  86
  87
  88 /**
  89
  90   Turn off interrupt notifications from the host, and prepare for appending
  91   multiple descriptors to the virtio ring.
  92
  93   The calling driver must be in VSTAT_DRIVER_OK state.
  94
  95   @param[in,out] Ring  The virtio ring we intend to append descriptors to.
  96
  97   @param[out] Indices  The DESC_INDICES structure to initialize.
  98
  99 **/
 100 VOID
 101 EFIAPI
 102 VirtioPrepare (
 103   IN OUT VRING        *Ring,
 104   OUT    DESC_INDICES *Indices
 105   );
 106
 107
 108 /**
 109
 110   Append a contiguous buffer for transmission / reception via the virtio ring.
 111
 112   This function implements the following section from virtio-0.9.5:
 113   - 2.4.1.1 Placing Buffers into the Descriptor Table
 114
 115   Free space is taken as granted, since the individual drivers support only
 116   synchronous requests and host side status is processed in lock-step with
 117   request submission. It is the calling driver's responsibility to verify the
 118   ring size in advance.
 119
 120   The caller is responsible for initializing *Indices with VirtioPrepare()
 121   first.
 122
 123   @param[in,out] Ring        The virtio ring to append the buffer to, as a
 124                              descriptor.
 125
 126   @param[in] BufferPhysAddr  (Guest pseudo-physical) start address of the
 127                              transmit / receive buffer.
 128
 129   @param[in] BufferSize      Number of bytes to transmit or receive.
 130
 131   @param[in] Flags           A bitmask of VRING_DESC_F_* flags. The caller
 132                              computes this mask dependent on further buffers to
 133                              append and transfer direction.
 134                              VRING_DESC_F_INDIRECT is unsupported. The
 135                              VRING_DESC.Next field is always set, but the host
 136                              only interprets it dependent on VRING_DESC_F_NEXT.
 137
 138   @param[in,out] Indices     Indices->HeadDescIdx is not accessed.
 139                              On input, Indices->NextDescIdx identifies the next
 140                              descriptor to carry the buffer. On output,
 141                              Indices->NextDescIdx is incremented by one, modulo
 142                              2^16.
 143
 144 **/
 145 VOID
 146 EFIAPI
 147 VirtioAppendDesc (
 148   IN OUT VRING        *Ring,
 149   IN     UINTN        BufferPhysAddr,
 150   IN     UINT32       BufferSize,
 151   IN     UINT16       Flags,
 152   IN OUT DESC_INDICES *Indices
 153   );
 154
 155
 156 /**
 157
 158   Notify the host about the descriptor chain just built, and wait until the
 159   host processes it.
 160
 161   @param[in] VirtIo       The target virtio device to notify.
 162
 163   @param[in] VirtQueueId  Identifies the queue for the target device.
 164
 165   @param[in,out] Ring     The virtio ring with descriptors to submit.
 166
 167   @param[in] Indices      Indices->NextDescIdx is not accessed.
 168                           Indices->HeadDescIdx identifies the head descriptor
 169                           of the descriptor chain.
 170
 171   @param[out] UsedLen     On success, the total number of bytes, consecutively
 172                           across the buffers linked by the descriptor chain,
 173                           that the host wrote. May be NULL if the caller
 174                           doesn't care, or can compute the same information
 175                           from device-specific request structures linked by the
 176                           descriptor chain.
 177
 178   @return              Error code from VirtIo->SetQueueNotify() if it fails.
 179
 180   @retval EFI_SUCCESS  Otherwise, the host processed all descriptors.
 181
 182 **/
 183 EFI_STATUS
 184 EFIAPI
 185 VirtioFlush (
 186   IN     VIRTIO_DEVICE_PROTOCOL *VirtIo,
 187   IN     UINT16                 VirtQueueId,
 188   IN OUT VRING                  *Ring,
 189   IN     DESC_INDICES           *Indices,
 190   OUT    UINT32                 *UsedLen    OPTIONAL
 191   );
 192
 193
 194 /**
 195
 196   Report the feature bits to the VirtIo 1.0 device that the VirtIo 1.0 driver
 197   understands.
 198
 199   In VirtIo 1.0, a device can reject a self-inconsistent feature bitmap through
 200   the new VSTAT_FEATURES_OK status bit. (For example if the driver requests a
 201   higher level feature but clears a prerequisite feature.) This function is a
 202   small wrapper around VIRTIO_DEVICE_PROTOCOL.SetGuestFeatures() that also
 203   verifies if the VirtIo 1.0 device accepts the feature bitmap.
 204
 205   @param[in]     VirtIo        Report feature bits to this device.
 206
 207   @param[in]     Features      The set of feature bits that the driver wishes
 208                                to report. The caller is responsible to perform
 209                                any masking before calling this function; the
 210                                value is directly written with
 211                                VIRTIO_DEVICE_PROTOCOL.SetGuestFeatures().
 212
 213   @param[in,out] DeviceStatus  On input, the status byte most recently written
 214                                to the device's status register. On output (even
 215                                on error), DeviceStatus will be updated so that
 216                                it is suitable for further status bit
 217                                manipulation and writing to the device's status
 218                                register.
 219
 220   @retval  EFI_SUCCESS      The device accepted the configuration in Features.
 221
 222   @return  EFI_UNSUPPORTED  The device rejected the configuration in Features.
 223
 224   @retval  EFI_UNSUPPORTED  VirtIo->Revision is smaller than 1.0.0.
 225
 226   @return                   Error codes from the SetGuestFeatures(),
 227                             SetDeviceStatus(), GetDeviceStatus() member
 228                             functions.
 229
 230 **/
 231 EFI_STATUS
 232 EFIAPI
 233 Virtio10WriteFeatures (
 234   IN     VIRTIO_DEVICE_PROTOCOL *VirtIo,
 235   IN     UINT64                 Features,
 236   IN OUT UINT8                  *DeviceStatus
 237   );
 238
 239 /**
 240   Provides the virtio device address required to access system memory from a
 241   DMA bus master.
 242
 243   The interface follows the same usage pattern as defined in UEFI spec 2.6
 244   (Section 13.2 PCI Root Bridge I/O Protocol)
 245
 246   The VirtioMapAllBytesInSharedBuffer() is similar to VIRTIO_MAP_SHARED
 247   with exception that NumberOfBytes is IN-only parameter. The function
 248   maps all the bytes specified in NumberOfBytes param in one consecutive
 249   range.
 250
 251   @param[in]     VirtIo           The virtio device for which the mapping is
 252                                   requested.
 253
 254   @param[in]     Operation        Indicates if the bus master is going to
 255                                   read or write to system memory.
 256
 257   @param[in]     HostAddress      The system memory address to map to shared
 258                                   buffer address.
 259
 260   @param[in]     NumberOfBytes    Number of bytes to map.
 261
 262   @param[out]    DeviceAddress    The resulting shared map address for the
 263                                   bus master to access the hosts HostAddress.
 264
 265   @param[out]    Mapping          A resulting token to pass to
 266                                   VIRTIO_UNMAP_SHARED.
 267
 268
 269   @retval EFI_SUCCESS             The NumberOfBytes is succesfully mapped.
 270   @retval EFI_UNSUPPORTED         The HostAddress cannot be mapped as a
 271                                   common buffer.
 272   @retval EFI_INVALID_PARAMETER   One or more parameters are invalid.
 273   @retval EFI_OUT_OF_RESOURCES    The request could not be completed due to
 274                                   a lack of resources. This includes the case
 275                                   when NumberOfBytes bytes cannot be mapped
 276                                   in one consecutive range.
 277   @retval EFI_DEVICE_ERROR        The system hardware could not map the
 278                                   requested address.
 279 **/
 280 EFI_STATUS
 281 EFIAPI
 282 VirtioMapAllBytesInSharedBuffer (
 283   IN  VIRTIO_DEVICE_PROTOCOL  *VirtIo,
 284   IN  VIRTIO_MAP_OPERATION    Operation,
 285   IN  VOID                    *HostAddress,
 286   IN  UINTN                   NumberOfBytes,
 287   OUT EFI_PHYSICAL_ADDRESS    *DeviceAddress,
 288   OUT VOID                    **Mapping
 289   );
 290 #endif // _VIRTIO_LIB_H_