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 to
 193                              append and transfer direction.
 194                              VRING_DESC_F_INDIRECT is unsupported. The
 195                              VRING_DESC.Next field is always set, but the host
 196                              only interprets it dependent on VRING_DESC_F_NEXT.
 197
 198   @param[in,out] Indices     Indices->HeadDescIdx is not accessed.
 199                              On input, Indices->NextDescIdx identifies the next
 200                              descriptor to carry the buffer. On output,
 201                              Indices->NextDescIdx is incremented by one, modulo
 202                              2^16.
 203
 204 **/
 205 VOID
 206 EFIAPI
 207 VirtioAppendDesc (
 208   IN OUT VRING        *Ring,
 209   IN     UINTN        BufferPhysAddr,
 210   IN     UINT32       BufferSize,
 211   IN     UINT16       Flags,
 212   IN OUT DESC_INDICES *Indices
 213   );
 214
 215
 216 /**
 217
 218   Notify the host about the descriptor chain just built, and wait until the
 219   host processes it.
 220
 221   @param[in] PciIo        The target virtio PCI device to notify.
 222
 223   @param[in] VirtQueueId  Identifies the queue for the target device.
 224
 225   @param[in,out] Ring     The virtio ring with descriptors to submit.
 226
 227   @param[in] Indices      Indices->NextDescIdx is not accessed.
 228                           Indices->HeadDescIdx identifies the head descriptor
 229                           of the descriptor chain.
 230
 231
 232   @return              Error code from VirtioWrite() if it fails.
 233
 234   @retval EFI_SUCCESS  Otherwise, the host processed all descriptors.
 235
 236 **/
 237 EFI_STATUS
 238 EFIAPI
 239 VirtioFlush (
 240   IN     EFI_PCI_IO_PROTOCOL *PciIo,
 241   IN     UINT16              VirtQueueId,
 242   IN OUT VRING               *Ring,
 243   IN     DESC_INDICES        *Indices
 244   );
 245
 246 #endif // _VIRTIO_LIB_H_