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   @retval EFI_OUT_OF_RESOURCES  AllocatePages() failed to allocate contiguous
  46                                 pages for the requested QueueSize. Fields of
  47                                 Ring have indeterminate value.
  48
  49   @retval EFI_SUCCESS           Allocation and setup successful. Ring->Base
  50                                 (and nothing else) is responsible for
  51                                 deallocation.
  52
  53 **/
  54 EFI_STATUS
  55 EFIAPI
  56 VirtioRingInit (
  57   IN  VIRTIO_DEVICE_PROTOCOL *VirtIo,
  58   IN  UINT16                 QueueSize,
  59   OUT VRING                  *Ring
  60   );
  61
  62
  63 /**
  64
  65   Map the ring buffer so that it can be accessed equally by both guest
  66   and hypervisor.
  67
  68   @param[in]      VirtIo          The virtio device instance.
  69
  70   @param[in]      Ring            The virtio ring to map.
  71
  72   @param[out]     RingBaseShift   A resulting translation offset, to be
  73                                   passed to VirtIo->SetQueueAddress().
  74
  75   @param[out]     Mapping         A resulting token to pass to
  76                                   VirtIo->UnmapSharedBuffer().
  77
  78   @return         Status code from VirtIo->MapSharedBuffer()
  79 **/
  80 EFI_STATUS
  81 EFIAPI
  82 VirtioRingMap (
  83   IN  VIRTIO_DEVICE_PROTOCOL *VirtIo,
  84   IN  VRING                  *Ring,
  85   OUT UINT64                 *RingBaseShift,
  86   OUT VOID                   **Mapping
  87   );
  88
  89 /**
  90
  91   Tear down the internal resources of a configured virtio ring.
  92
  93   The caller is responsible to stop the host from using this ring before
  94   invoking this function: the VSTAT_DRIVER_OK bit must be clear in
  95   VhdrDeviceStatus.
  96
  97   @param[in]  VirtIo  The virtio device which was using the ring.
  98
  99   @param[out] Ring    The virtio ring to clean up.
 100
 101 **/
 102 VOID
 103 EFIAPI
 104 VirtioRingUninit (
 105   IN     VIRTIO_DEVICE_PROTOCOL *VirtIo,
 106   IN OUT VRING                  *Ring
 107   );
 108
 109
 110 //
 111 // Internal use structure for tracking the submission of a multi-descriptor
 112 // request.
 113 //
 114 typedef struct {
 115   UINT16 HeadDescIdx;
 116   UINT16 NextDescIdx;
 117 } DESC_INDICES;
 118
 119
 120 /**
 121
 122   Turn off interrupt notifications from the host, and prepare for appending
 123   multiple descriptors to the virtio ring.
 124
 125   The calling driver must be in VSTAT_DRIVER_OK state.
 126
 127   @param[in,out] Ring  The virtio ring we intend to append descriptors to.
 128
 129   @param[out] Indices  The DESC_INDICES structure to initialize.
 130
 131 **/
 132 VOID
 133 EFIAPI
 134 VirtioPrepare (
 135   IN OUT VRING        *Ring,
 136   OUT    DESC_INDICES *Indices
 137   );
 138
 139
 140 /**
 141
 142   Append a contiguous buffer for transmission / reception via the virtio ring.
 143
 144   This function implements the following section from virtio-0.9.5:
 145   - 2.4.1.1 Placing Buffers into the Descriptor Table
 146
 147   Free space is taken as granted, since the individual drivers support only
 148   synchronous requests and host side status is processed in lock-step with
 149   request submission. It is the calling driver's responsibility to verify the
 150   ring size in advance.
 151
 152   The caller is responsible for initializing *Indices with VirtioPrepare()
 153   first.
 154
 155   @param[in,out] Ring        The virtio ring to append the buffer to, as a
 156                              descriptor.
 157
 158   @param[in] BufferPhysAddr  (Guest pseudo-physical) start address of the
 159                              transmit / receive buffer.
 160
 161   @param[in] BufferSize      Number of bytes to transmit or receive.
 162
 163   @param[in] Flags           A bitmask of VRING_DESC_F_* flags. The caller
 164                              computes this mask dependent on further buffers to
 165                              append and transfer direction.
 166                              VRING_DESC_F_INDIRECT is unsupported. The
 167                              VRING_DESC.Next field is always set, but the host
 168                              only interprets it dependent on VRING_DESC_F_NEXT.
 169
 170   @param[in,out] Indices     Indices->HeadDescIdx is not accessed.
 171                              On input, Indices->NextDescIdx identifies the next
 172                              descriptor to carry the buffer. On output,
 173                              Indices->NextDescIdx is incremented by one, modulo
 174                              2^16.
 175
 176 **/
 177 VOID
 178 EFIAPI
 179 VirtioAppendDesc (
 180   IN OUT VRING        *Ring,
 181   IN     UINTN        BufferPhysAddr,
 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_