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, as a
 155                              descriptor.
 156
 157   @param[in] BufferPhysAddr  (Guest pseudo-physical) 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 caller
 163                              computes this mask dependent on further buffers to
 164                              append and transfer direction.
 165                              VRING_DESC_F_INDIRECT is unsupported. The
 166                              VRING_DESC.Next field is always set, but the host
 167                              only interprets it dependent on VRING_DESC_F_NEXT.
 168
 169   @param[in,out] Indices     Indices->HeadDescIdx is not accessed.
 170                              On input, Indices->NextDescIdx identifies the next
 171                              descriptor to carry the buffer. On output,
 172                              Indices->NextDescIdx is incremented by one, modulo
 173                              2^16.
 174
 175 **/
 176 VOID
 177 EFIAPI
 178 VirtioAppendDesc (
 179   IN OUT VRING        *Ring,
 180   IN     UINTN        BufferPhysAddr,
 181   IN     UINT32       BufferSize,
 182   IN     UINT16       Flags,
 183   IN OUT DESC_INDICES *Indices
 184   );
 185
 186
 187 /**
 188
 189   Notify the host about the descriptor chain just built, and wait until the
 190   host processes it.
 191
 192   @param[in] VirtIo       The target virtio device to notify.
 193
 194   @param[in] VirtQueueId  Identifies the queue for the target device.
 195
 196   @param[in,out] Ring     The virtio ring with descriptors to submit.
 197
 198   @param[in] Indices      Indices->NextDescIdx is not accessed.
 199                           Indices->HeadDescIdx identifies the head descriptor
 200                           of the descriptor chain.
 201
 202   @param[out] UsedLen     On success, the total number of bytes, consecutively
 203                           across the buffers linked by the descriptor chain,
 204                           that the host wrote. May be NULL if the caller
 205                           doesn't care, or can compute the same information
 206                           from device-specific request structures linked by the
 207                           descriptor chain.
 208
 209   @return              Error code from VirtIo->SetQueueNotify() if it fails.
 210
 211   @retval EFI_SUCCESS  Otherwise, the host processed all descriptors.
 212
 213 **/
 214 EFI_STATUS
 215 EFIAPI
 216 VirtioFlush (
 217   IN     VIRTIO_DEVICE_PROTOCOL *VirtIo,
 218   IN     UINT16                 VirtQueueId,
 219   IN OUT VRING                  *Ring,
 220   IN     DESC_INDICES           *Indices,
 221   OUT    UINT32                 *UsedLen    OPTIONAL
 222   );
 223
 224
 225 /**
 226
 227   Report the feature bits to the VirtIo 1.0 device that the VirtIo 1.0 driver
 228   understands.
 229
 230   In VirtIo 1.0, a device can reject a self-inconsistent feature bitmap through
 231   the new VSTAT_FEATURES_OK status bit. (For example if the driver requests a
 232   higher level feature but clears a prerequisite feature.) This function is a
 233   small wrapper around VIRTIO_DEVICE_PROTOCOL.SetGuestFeatures() that also
 234   verifies if the VirtIo 1.0 device accepts the feature bitmap.
 235
 236   @param[in]     VirtIo        Report feature bits to this device.
 237
 238   @param[in]     Features      The set of feature bits that the driver wishes
 239                                to report. The caller is responsible to perform
 240                                any masking before calling this function; the
 241                                value is directly written with
 242                                VIRTIO_DEVICE_PROTOCOL.SetGuestFeatures().
 243
 244   @param[in,out] DeviceStatus  On input, the status byte most recently written
 245                                to the device's status register. On output (even
 246                                on error), DeviceStatus will be updated so that
 247                                it is suitable for further status bit
 248                                manipulation and writing to the device's status
 249                                register.
 250
 251   @retval  EFI_SUCCESS      The device accepted the configuration in Features.
 252
 253   @return  EFI_UNSUPPORTED  The device rejected the configuration in Features.
 254
 255   @retval  EFI_UNSUPPORTED  VirtIo->Revision is smaller than 1.0.0.
 256
 257   @return                   Error codes from the SetGuestFeatures(),
 258                             SetDeviceStatus(), GetDeviceStatus() member
 259                             functions.
 260
 261 **/
 262 EFI_STATUS
 263 EFIAPI
 264 Virtio10WriteFeatures (
 265   IN     VIRTIO_DEVICE_PROTOCOL *VirtIo,
 266   IN     UINT64                 Features,
 267   IN OUT UINT8                  *DeviceStatus
 268   );
 269
 270 /**
 271   Provides the virtio device address required to access system memory from a
 272   DMA bus master.
 273
 274   The interface follows the same usage pattern as defined in UEFI spec 2.6
 275   (Section 13.2 PCI Root Bridge I/O Protocol)
 276
 277   The VirtioMapAllBytesInSharedBuffer() is similar to VIRTIO_MAP_SHARED
 278   with exception that NumberOfBytes is IN-only parameter. The function
 279   maps all the bytes specified in NumberOfBytes param in one consecutive
 280   range.
 281
 282   @param[in]     VirtIo           The virtio device for which the mapping is
 283                                   requested.
 284
 285   @param[in]     Operation        Indicates if the bus master is going to
 286                                   read or write to system memory.
 287
 288   @param[in]     HostAddress      The system memory address to map to shared
 289                                   buffer address.
 290
 291   @param[in]     NumberOfBytes    Number of bytes to map.
 292
 293   @param[out]    DeviceAddress    The resulting shared map address for the
 294                                   bus master to access the hosts HostAddress.
 295
 296   @param[out]    Mapping          A resulting token to pass to
 297                                   VIRTIO_UNMAP_SHARED.
 298
 299
 300   @retval EFI_SUCCESS             The NumberOfBytes is succesfully mapped.
 301   @retval EFI_UNSUPPORTED         The HostAddress cannot be mapped as a
 302                                   common buffer.
 303   @retval EFI_INVALID_PARAMETER   One or more parameters are invalid.
 304   @retval EFI_OUT_OF_RESOURCES    The request could not be completed due to
 305                                   a lack of resources. This includes the case
 306                                   when NumberOfBytes bytes cannot be mapped
 307                                   in one consecutive range.
 308   @retval EFI_DEVICE_ERROR        The system hardware could not map the
 309                                   requested address.
 310 **/
 311 EFI_STATUS
 312 EFIAPI
 313 VirtioMapAllBytesInSharedBuffer (
 314   IN  VIRTIO_DEVICE_PROTOCOL  *VirtIo,
 315   IN  VIRTIO_MAP_OPERATION    Operation,
 316   IN  VOID                    *HostAddress,
 317   IN  UINTN                   NumberOfBytes,
 318   OUT EFI_PHYSICAL_ADDRESS    *DeviceAddress,
 319   OUT VOID                    **Mapping
 320   );
 321 #endif // _VIRTIO_LIB_H_