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