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 EFI_STATUS
  44 EFIAPI
  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 EFI_STATUS
  76 EFIAPI
  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 HeadDescIdx;
 144   UINT16 NextDescIdx;
 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 section from virtio-0.9.5:
 173   - 2.4.1.1 Placing Buffers into the Descriptor Table
 174
 175   Free space is taken as granted, since the individual drivers support only
 176   synchronous requests and host side status is processed in lock-step with
 177   request submission. It is the calling driver's responsibility to verify the
 178   ring size in advance.
 179
 180   The caller is responsible for initializing *Indices with VirtioPrepare()
 181   first.
 182
 183   @param[in out] Ring           The virtio ring to append the buffer to, as a
 184                                 descriptor.
 185
 186   @param [in] BufferPhysAddr    (Guest pseudo-physical) start address of the
 187                                 transmit / receive buffer.
 188
 189   @param [in] BufferSize        Number of bytes to transmit or receive.
 190
 191   @param [in] Flags             A bitmask of VRING_DESC_F_* flags. The caller
 192                                 computes this mask dependent on further buffers
 193                                 to append and transfer direction.
 194                                 VRING_DESC_F_INDIRECT is unsupported. The
 195                                 VRING_DESC.Next field is always set, but the
 196                                 host only interprets it dependent on
 197                                 VRING_DESC_F_NEXT.
 198
 199   In *Indices:
 200
 201   @param [in out] NextDescIdx  On input, the index identifying the next
 202                                descriptor to carry the buffer. On output,
 203                                incremented by one, modulo 2^16.
 204
 205 **/
 206 VOID
 207 EFIAPI
 208 VirtioAppendDesc (
 209   IN OUT VRING        *Ring,
 210   IN     UINTN        BufferPhysAddr,
 211   IN     UINT32       BufferSize,
 212   IN     UINT16       Flags,
 213   IN OUT DESC_INDICES *Indices
 214   );
 215
 216
 217 /**
 218
 219   Notify the host about the descriptor chain just built, and wait until the
 220   host processes it.
 221
 222   @param[in] PciIo        The target virtio PCI device to notify.
 223
 224   @param[in] VirtQueueId  Identifies the queue for the target device.
 225
 226   @param[in out] Ring     The virtio ring with descriptors to submit.
 227
 228   In *Indices:
 229
 230   @param[in] HeadDescIdx  Identifies the head descriptor of the descriptor
 231                           chain.
 232
 233
 234   @return              Error code from VirtioWrite() if it fails.
 235
 236   @retval EFI_SUCCESS  Otherwise, the host processed all descriptors.
 237
 238 **/
 239 EFI_STATUS
 240 EFIAPI
 241 VirtioFlush (
 242   IN     EFI_PCI_IO_PROTOCOL *PciIo,
 243   IN     UINT16              VirtQueueId,
 244   IN OUT VRING               *Ring,
 245   IN     DESC_INDICES        *Indices
 246   );
 247
 248 #endif // _VIRTIO_LIB_H_