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
 140   Append a contiguous buffer for transmission / reception via the virtio ring.
 141
 142   This function implements the following sections from virtio-0.9.5:
 143   - 2.4.1.1 Placing Buffers into the Descriptor Table
 144   - 2.4.1.2 Updating the Available Ring
 145
 146   Free space is taken as granted, since the individual drivers support only
 147   synchronous requests and host side status is processed in lock-step with
 148   request submission. It is the calling driver's responsibility to verify the
 149   ring size in advance.
 150
 151   @param[in out] Ring           The virtio ring to append the buffer to, as a
 152                                 descriptor.
 153
 154   @param [in] BufferPhysAddr    (Guest pseudo-physical) start address of the
 155                                 transmit / receive buffer.
 156
 157   @param [in] BufferSize        Number of bytes to transmit or receive.
 158
 159   @param [in] Flags             A bitmask of VRING_DESC_F_* flags. The caller
 160                                 computes this mask dependent on further buffers
 161                                 to append and transfer direction.
 162                                 VRING_DESC_F_INDIRECT is unsupported. The
 163                                 VRING_DESC.Next field is always set, but the
 164                                 host only interprets it dependent on
 165                                 VRING_DESC_F_NEXT.
 166
 167   @param [in] HeadIdx           The index identifying the head buffer (first
 168                                 buffer appended) belonging to this same
 169                                 request.
 170
 171   @param [in out] NextAvailIdx  On input, the index identifying the next
 172                                 descriptor available to carry the buffer. On
 173                                 output, incremented by one, modulo 2^16.
 174
 175 **/
 176 VOID
 177 EFIAPI
 178 VirtioAppendDesc (
 179   IN OUT VRING  *Ring,
 180   IN     UINTN  BufferPhysAddr,
 181   IN     UINT32 BufferSize,
 182   IN     UINT16 Flags,
 183   IN     UINT16 HeadIdx,
 184   IN OUT UINT16 *NextAvailIdx
 185   );
 186
 187 #endif // _VIRTIO_LIB_H_