]>
git.proxmox.com Git - mirror_edk2.git/blob - OvmfPkg/Include/Library/VirtioLib.h
3 Declarations of utility functions used by virtio device drivers.
5 Copyright (C) 2012, Red Hat, Inc.
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
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.
17 #ifndef _VIRTIO_LIB_H_
18 #define _VIRTIO_LIB_H_
20 #include <Protocol/PciIo.h>
21 #include <IndustryStandard/Virtio.h>
25 Write a word into Region 0 of the device specified by PciIo.
27 Region 0 must be an iomem region. This is an internal function for the
28 driver-specific VIRTIO_CFG_WRITE() macros.
30 @param[in] PciIo Target PCI device.
32 @param[in] FieldOffset Destination offset.
34 @param[in] FieldSize Destination field size, must be in { 1, 2, 4, 8 }.
36 @param[in] Value Little endian value to write, converted to UINT64.
37 The least significant FieldSize bytes will be used.
40 @return Status code returned by PciIo->Io.Write().
46 IN EFI_PCI_IO_PROTOCOL
*PciIo
,
55 Read a word from Region 0 of the device specified by PciIo.
57 Region 0 must be an iomem region. This is an internal function for the
58 driver-specific VIRTIO_CFG_READ() macros.
60 @param[in] PciIo Source PCI device.
62 @param[in] FieldOffset Source offset.
64 @param[in] FieldSize Source field size, must be in { 1, 2, 4, 8 }.
66 @param[in] BufferSize Number of bytes available in the target buffer. Must
69 @param[out] Buffer Target buffer.
72 @return Status code returned by PciIo->Io.Read().
78 IN EFI_PCI_IO_PROTOCOL
*PciIo
,
88 Configure a virtio ring.
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
94 Relevant sections from the virtio-0.9.5 spec:
96 - 2.3 Virtqueue Configuration.
98 @param[in] The number of descriptors to allocate for the
99 virtio ring, as requested by the host.
101 @param[out] Ring The virtio ring to set up.
103 @retval EFI_OUT_OF_RESOURCES AllocatePages() failed to allocate contiguous
104 pages for the requested QueueSize. Fields of
105 Ring have indeterminate value.
107 @retval EFI_SUCCESS Allocation and setup successful. Ring->Base
108 (and nothing else) is responsible for
122 Tear down the internal resources of a configured virtio ring.
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
128 @param[out] Ring The virtio ring to clean up.
139 // Internal use structure for tracking the submission of a multi-descriptor
150 Turn off interrupt notifications from the host, and prepare for appending
151 multiple descriptors to the virtio ring.
153 The calling driver must be in VSTAT_DRIVER_OK state.
155 @param[in,out] Ring The virtio ring we intend to append descriptors to.
157 @param[out] Indices The DESC_INDICES structure to initialize.
164 OUT DESC_INDICES
*Indices
170 Append a contiguous buffer for transmission / reception via the virtio ring.
172 This function implements the following section from virtio-0.9.5:
173 - 2.4.1.1 Placing Buffers into the Descriptor Table
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.
180 The caller is responsible for initializing *Indices with VirtioPrepare()
183 @param[in out] Ring The virtio ring to append the buffer to, as a
186 @param [in] BufferPhysAddr (Guest pseudo-physical) start address of the
187 transmit / receive buffer.
189 @param [in] BufferSize Number of bytes to transmit or receive.
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
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.
210 IN UINTN BufferPhysAddr
,
211 IN UINT32 BufferSize
,
213 IN OUT DESC_INDICES
*Indices
219 Notify the host about the descriptor chain just built, and wait until the
222 @param[in] PciIo The target virtio PCI device to notify.
224 @param[in] VirtQueueId Identifies the queue for the target device.
226 @param[in out] Ring The virtio ring with descriptors to submit.
230 @param[in] HeadDescIdx Identifies the head descriptor of the descriptor
234 @return Error code from VirtioWrite() if it fails.
236 @retval EFI_SUCCESS Otherwise, the host processed all descriptors.
242 IN EFI_PCI_IO_PROTOCOL
*PciIo
,
243 IN UINT16 VirtQueueId
,
245 IN DESC_INDICES
*Indices
248 #endif // _VIRTIO_LIB_H_