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