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