OvmfPkg/Include/Library/VirtioLib.h

   1 /** @file
   2
   3   Declarations of utility functions used by virtio device drivers.
   4
   5   Copyright (C) 2012, Red Hat, Inc.
   6
   7   This program and the accompanying materials are licensed and made available
   8   under the terms and conditions of the BSD License which accompanies this
   9   distribution. The full text of the license may be found at
  10   http://opensource.org/licenses/bsd-license.php
  11
  12   THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, WITHOUT
  13   WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  14
  15 **/
  16
  17 #ifndef _VIRTIO_LIB_H_
  18 #define _VIRTIO_LIB_H_
  19
  20 #include <Protocol/PciIo.h>
  21 #include <IndustryStandard/Virtio.h>
  22
  23 /**
  24
  25   Write a word into Region 0 of the device specified by PciIo.
  26
  27   Region 0 must be an iomem region. This is an internal function for the
  28   driver-specific VIRTIO_CFG_WRITE() macros.
  29
  30   @param[in] PciIo        Target PCI device.
  31
  32   @param[in] FieldOffset  Destination offset.
  33
  34   @param[in] FieldSize    Destination field size, must be in { 1, 2, 4, 8 }.
  35
  36   @param[in] Value        Little endian value to write, converted to UINT64.
  37                           The least significant FieldSize bytes will be used.
  38
  39
  40   @return  Status code returned by PciIo->Io.Write().
  41
  42 **/
  43 EFIAPI
  44 EFI_STATUS
  45 VirtioWrite (
  46   IN EFI_PCI_IO_PROTOCOL *PciIo,
  47   IN UINTN               FieldOffset,
  48   IN UINTN               FieldSize,
  49   IN UINT64              Value
  50   );
  51
  52
  53 /**
  54
  55   Read a word from Region 0 of the device specified by PciIo.
  56
  57   Region 0 must be an iomem region. This is an internal function for the
  58   driver-specific VIRTIO_CFG_READ() macros.
  59
  60   @param[in] PciIo        Source PCI device.
  61
  62   @param[in] FieldOffset  Source offset.
  63
  64   @param[in] FieldSize    Source field size, must be in { 1, 2, 4, 8 }.
  65
  66   @param[in] BufferSize   Number of bytes available in the target buffer. Must
  67                           equal FieldSize.
  68
  69   @param[out] Buffer      Target buffer.
  70
  71
  72   @return  Status code returned by PciIo->Io.Read().
  73
  74 **/
  75 EFIAPI
  76 EFI_STATUS
  77 VirtioRead (
  78   IN  EFI_PCI_IO_PROTOCOL *PciIo,
  79   IN  UINTN               FieldOffset,
  80   IN  UINTN               FieldSize,
  81   IN  UINTN               BufferSize,
  82   OUT VOID                *Buffer
  83   );
  84
  85
  86 /**
  87
  88   Configure a virtio ring.
  89
  90   This function sets up internal storage (the guest-host communication area)
  91   and lays out several "navigation" (ie. no-ownership) pointers to parts of
  92   that storage.
  93
  94   Relevant sections from the virtio-0.9.5 spec:
  95   - 1.1 Virtqueues,
  96   - 2.3 Virtqueue Configuration.
  97
  98   @param[in]                    The number of descriptors to allocate for the
  99                                 virtio ring, as requested by the host.
 100
 101   @param[out] Ring              The virtio ring to set up.
 102
 103   @retval EFI_OUT_OF_RESOURCES  AllocatePages() failed to allocate contiguous
 104                                 pages for the requested QueueSize. Fields of
 105                                 Ring have indeterminate value.
 106
 107   @retval EFI_SUCCESS           Allocation and setup successful. Ring->Base
 108                                 (and nothing else) is responsible for
 109                                 deallocation.
 110
 111 **/
 112 EFI_STATUS
 113 EFIAPI
 114 VirtioRingInit (
 115   IN  UINT16 QueueSize,
 116   OUT VRING  *Ring
 117   );
 118
 119
 120 /**
 121
 122   Tear down the internal resources of a configured virtio ring.
 123
 124   The caller is responsible to stop the host from using this ring before
 125   invoking this function: the VSTAT_DRIVER_OK bit must be clear in
 126   VhdrDeviceStatus.
 127
 128   @param[out] Ring  The virtio ring to clean up.
 129
 130 **/
 131 VOID
 132 EFIAPI
 133 VirtioRingUninit (
 134   IN OUT VRING *Ring
 135   );
 136
 137
 138 //
 139 // Internal use structure for tracking the submission of a multi-descriptor
 140 // request.
 141 //
 142 typedef struct {
 143   UINT16 HeadIdx;
 144   UINT16 NextAvailIdx;
 145 } DESC_INDICES;
 146
 147
 148 /**
 149
 150   Turn off interrupt notifications from the host, and prepare for appending
 151   multiple descriptors to the virtio ring.
 152
 153   The calling driver must be in VSTAT_DRIVER_OK state.
 154
 155   @param[in out] Ring  The virtio ring we intend to append descriptors to.
 156
 157   @param[out] Indices  The DESC_INDICES structure to initialize.
 158
 159 **/
 160 VOID
 161 EFIAPI
 162 VirtioPrepare (
 163   IN OUT VRING        *Ring,
 164   OUT    DESC_INDICES *Indices
 165   );
 166
 167
 168 /**
 169
 170   Append a contiguous buffer for transmission / reception via the virtio ring.
 171
 172   This function implements the following sections from virtio-0.9.5:
 173   - 2.4.1.1 Placing Buffers into the Descriptor Table
 174   - 2.4.1.2 Updating the Available Ring
 175
 176   Free space is taken as granted, since the individual drivers support only
 177   synchronous requests and host side status is processed in lock-step with
 178   request submission. It is the calling driver's responsibility to verify the
 179   ring size in advance.
 180
 181   The caller is responsible for initializing *Indices with VirtioPrepare()
 182   first.
 183
 184   @param[in out] Ring           The virtio ring to append the buffer to, as a
 185                                 descriptor.
 186
 187   @param [in] BufferPhysAddr    (Guest pseudo-physical) start address of the
 188                                 transmit / receive buffer.
 189
 190   @param [in] BufferSize        Number of bytes to transmit or receive.
 191
 192   @param [in] Flags             A bitmask of VRING_DESC_F_* flags. The caller
 193                                 computes this mask dependent on further buffers
 194                                 to append and transfer direction.
 195                                 VRING_DESC_F_INDIRECT is unsupported. The
 196                                 VRING_DESC.Next field is always set, but the
 197                                 host only interprets it dependent on
 198                                 VRING_DESC_F_NEXT.
 199
 200   In *Indices:
 201
 202   @param [in] HeadIdx           The index identifying the head buffer (first
 203                                 buffer appended) belonging to this same
 204                                 request.
 205
 206   @param [in out] NextAvailIdx  On input, the index identifying the next
 207                                 descriptor available to carry the buffer. On
 208                                 output, incremented by one, modulo 2^16.
 209
 210 **/
 211 VOID
 212 EFIAPI
 213 VirtioAppendDesc (
 214   IN OUT VRING        *Ring,
 215   IN     UINTN        BufferPhysAddr,
 216   IN     UINT32       BufferSize,
 217   IN     UINT16       Flags,
 218   IN OUT DESC_INDICES *Indices
 219   );
 220
 221
 222 /**
 223
 224   Notify the host about appended descriptors and wait until it processes the
 225   last one (ie. all of them).
 226
 227   @param[in] PciIo        The target virtio PCI device to notify.
 228
 229   @param[in] VirtQueueId  Identifies the queue for the target device.
 230
 231   @param[in out] Ring     The virtio ring with descriptors to submit.
 232
 233   @param[in] Indices      The function waits until the host processes
 234                           descriptors up to Indices->NextAvailIdx.
 235
 236
 237   @return              Error code from VirtioWrite() if it fails.
 238
 239   @retval EFI_SUCCESS  Otherwise, the host processed all descriptors.
 240
 241 **/
 242 EFI_STATUS
 243 EFIAPI
 244 VirtioFlush (
 245   IN     EFI_PCI_IO_PROTOCOL *PciIo,
 246   IN     UINT16              VirtQueueId,
 247   IN OUT VRING               *Ring,
 248   IN     DESC_INDICES        *Indices
 249   );
 250
 251 #endif // _VIRTIO_LIB_H_