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