\r
Declarations of utility functions used by virtio device drivers.\r
\r
- Copyright (C) 2012, Red Hat, Inc.\r
+ Copyright (C) 2012-2016, Red Hat, Inc.\r
+ Copyright (C) 2017, AMD Inc, All rights reserved.<BR>\r
\r
This program and the accompanying materials are licensed and made available\r
under the terms and conditions of the BSD License which accompanies this\r
#ifndef _VIRTIO_LIB_H_\r
#define _VIRTIO_LIB_H_\r
\r
-#include <Protocol/PciIo.h>\r
+#include <Protocol/VirtioDevice.h>\r
+\r
#include <IndustryStandard/Virtio.h>\r
\r
+\r
/**\r
\r
- Write a word into Region 0 of the device specified by PciIo.\r
+ Configure a virtio ring.\r
\r
- Region 0 must be an iomem region. This is an internal function for the\r
- driver-specific VIRTIO_CFG_WRITE() macros.\r
+ This function sets up internal storage (the guest-host communication area)\r
+ and lays out several "navigation" (ie. no-ownership) pointers to parts of\r
+ that storage.\r
\r
- @param[in] PciIo Target PCI device.\r
+ Relevant sections from the virtio-0.9.5 spec:\r
+ - 1.1 Virtqueues,\r
+ - 2.3 Virtqueue Configuration.\r
\r
- @param[in] FieldOffset Destination offset.\r
+ @param[in] VirtIo The virtio device which will use the ring.\r
\r
- @param[in] FieldSize Destination field size, must be in { 1, 2, 4, 8 }.\r
+ @param[in] The number of descriptors to allocate for the\r
+ virtio ring, as requested by the host.\r
\r
- @param[in] Value Little endian value to write, converted to UINT64.\r
- The least significant FieldSize bytes will be used.\r
+ @param[out] Ring The virtio ring to set up.\r
\r
+ @return Status codes propagated from\r
+ VirtIo->AllocateSharedPages().\r
\r
- @return Status code returned by PciIo->Io.Write().\r
+ @retval EFI_SUCCESS Allocation and setup successful. Ring->Base\r
+ (and nothing else) is responsible for\r
+ deallocation.\r
\r
**/\r
-EFIAPI\r
EFI_STATUS\r
-VirtioWrite (\r
- IN EFI_PCI_IO_PROTOCOL *PciIo,\r
- IN UINTN FieldOffset,\r
- IN UINTN FieldSize,\r
- IN UINT64 Value\r
+EFIAPI\r
+VirtioRingInit (\r
+ IN VIRTIO_DEVICE_PROTOCOL *VirtIo,\r
+ IN UINT16 QueueSize,\r
+ OUT VRING *Ring\r
);\r
\r
\r
/**\r
\r
- Read a word from Region 0 of the device specified by PciIo.\r
-\r
- Region 0 must be an iomem region. This is an internal function for the\r
- driver-specific VIRTIO_CFG_READ() macros.\r
-\r
- @param[in] PciIo Source PCI device.\r
-\r
- @param[in] FieldOffset Source offset.\r
+ Map the ring buffer so that it can be accessed equally by both guest\r
+ and hypervisor.\r
\r
- @param[in] FieldSize Source field size, must be in { 1, 2, 4, 8 }.\r
+ @param[in] VirtIo The virtio device instance.\r
\r
- @param[in] BufferSize Number of bytes available in the target buffer. Must\r
- equal FieldSize.\r
+ @param[in] Ring The virtio ring to map.\r
\r
- @param[out] Buffer Target buffer.\r
+ @param[out] RingBaseShift A resulting translation offset, to be\r
+ passed to VirtIo->SetQueueAddress().\r
\r
+ @param[out] Mapping A resulting token to pass to\r
+ VirtIo->UnmapSharedBuffer().\r
\r
- @return Status code returned by PciIo->Io.Read().\r
-\r
+ @return Status code from VirtIo->MapSharedBuffer()\r
**/\r
-EFIAPI\r
EFI_STATUS\r
-VirtioRead (\r
- IN EFI_PCI_IO_PROTOCOL *PciIo,\r
- IN UINTN FieldOffset,\r
- IN UINTN FieldSize,\r
- IN UINTN BufferSize,\r
- OUT VOID *Buffer\r
+EFIAPI\r
+VirtioRingMap (\r
+ IN VIRTIO_DEVICE_PROTOCOL *VirtIo,\r
+ IN VRING *Ring,\r
+ OUT UINT64 *RingBaseShift,\r
+ OUT VOID **Mapping\r
);\r
\r
-\r
/**\r
\r
- Configure a virtio ring.\r
-\r
- This function sets up internal storage (the guest-host communication area)\r
- and lays out several "navigation" (ie. no-ownership) pointers to parts of\r
- that storage.\r
-\r
- Relevant sections from the virtio-0.9.5 spec:\r
- - 1.1 Virtqueues,\r
- - 2.3 Virtqueue Configuration.\r
-\r
- @param[in] The number of descriptors to allocate for the\r
- virtio ring, as requested by the host.\r
+ Tear down the internal resources of a configured virtio ring.\r
\r
- @param[out] Ring The virtio ring to set up.\r
+ The caller is responsible to stop the host from using this ring before\r
+ invoking this function: the VSTAT_DRIVER_OK bit must be clear in\r
+ VhdrDeviceStatus.\r
\r
- @retval EFI_OUT_OF_RESOURCES AllocatePages() failed to allocate contiguous\r
- pages for the requested QueueSize. Fields of\r
- Ring have indeterminate value.\r
+ @param[in] VirtIo The virtio device which was using the ring.\r
\r
- @retval EFI_SUCCESS Allocation and setup successful. Ring->Base\r
- (and nothing else) is responsible for\r
- deallocation.\r
+ @param[out] Ring The virtio ring to clean up.\r
\r
**/\r
-EFI_STATUS\r
+VOID\r
EFIAPI\r
-VirtioRingInit (\r
- IN UINT16 QueueSize,\r
- OUT VRING *Ring\r
+VirtioRingUninit (\r
+ IN VIRTIO_DEVICE_PROTOCOL *VirtIo,\r
+ IN OUT VRING *Ring\r
);\r
\r
\r
+//\r
+// Internal use structure for tracking the submission of a multi-descriptor\r
+// request.\r
+//\r
+typedef struct {\r
+ UINT16 HeadDescIdx;\r
+ UINT16 NextDescIdx;\r
+} DESC_INDICES;\r
+\r
+\r
/**\r
\r
- Tear down the internal resources of a configured virtio ring.\r
+ Turn off interrupt notifications from the host, and prepare for appending\r
+ multiple descriptors to the virtio ring.\r
\r
- The caller is responsible to stop the host from using this ring before\r
- invoking this function: the VSTAT_DRIVER_OK bit must be clear in\r
- VhdrDeviceStatus.\r
+ The calling driver must be in VSTAT_DRIVER_OK state.\r
\r
- @param[out] Ring The virtio ring to clean up.\r
+ @param[in,out] Ring The virtio ring we intend to append descriptors to.\r
+\r
+ @param[out] Indices The DESC_INDICES structure to initialize.\r
\r
**/\r
VOID\r
EFIAPI\r
-VirtioRingUninit (\r
- IN OUT VRING *Ring\r
+VirtioPrepare (\r
+ IN OUT VRING *Ring,\r
+ OUT DESC_INDICES *Indices\r
);\r
\r
\r
\r
Append a contiguous buffer for transmission / reception via the virtio ring.\r
\r
- This function implements the following sections from virtio-0.9.5:\r
+ This function implements the following section from virtio-0.9.5:\r
- 2.4.1.1 Placing Buffers into the Descriptor Table\r
- - 2.4.1.2 Updating the Available Ring\r
\r
Free space is taken as granted, since the individual drivers support only\r
synchronous requests and host side status is processed in lock-step with\r
request submission. It is the calling driver's responsibility to verify the\r
ring size in advance.\r
\r
- @param[in out] Ring The virtio ring to append the buffer to, as a\r
- descriptor.\r
+ The caller is responsible for initializing *Indices with VirtioPrepare()\r
+ first.\r
\r
- @param [in] BufferPhysAddr (Guest pseudo-physical) start address of the\r
- transmit / receive buffer.\r
+ @param[in,out] Ring The virtio ring to append the buffer to,\r
+ as a descriptor.\r
\r
- @param [in] BufferSize Number of bytes to transmit or receive.\r
+ @param[in] BufferDeviceAddress (Bus master device) start address of the\r
+ transmit / receive buffer.\r
\r
- @param [in] Flags A bitmask of VRING_DESC_F_* flags. The caller\r
- computes this mask dependent on further buffers\r
- to append and transfer direction.\r
- VRING_DESC_F_INDIRECT is unsupported. The\r
- VRING_DESC.Next field is always set, but the\r
- host only interprets it dependent on\r
- VRING_DESC_F_NEXT.\r
+ @param[in] BufferSize Number of bytes to transmit or receive.\r
\r
- @param [in] HeadIdx The index identifying the head buffer (first\r
- buffer appended) belonging to this same\r
- request.\r
+ @param[in] Flags A bitmask of VRING_DESC_F_* flags. The\r
+ caller computes this mask dependent on\r
+ further buffers to append and transfer\r
+ direction. VRING_DESC_F_INDIRECT is\r
+ unsupported. The VRING_DESC.Next field is\r
+ always set, but the host only interprets\r
+ it dependent on VRING_DESC_F_NEXT.\r
\r
- @param [in out] NextAvailIdx On input, the index identifying the next\r
- descriptor available to carry the buffer. On\r
- output, incremented by one, modulo 2^16.\r
+ @param[in,out] Indices Indices->HeadDescIdx is not accessed.\r
+ On input, Indices->NextDescIdx identifies\r
+ the next descriptor to carry the buffer.\r
+ On output, Indices->NextDescIdx is\r
+ incremented by one, modulo 2^16.\r
\r
**/\r
VOID\r
EFIAPI\r
-AppendDesc (\r
- IN OUT VRING *Ring,\r
- IN UINTN BufferPhysAddr,\r
- IN UINT32 BufferSize,\r
- IN UINT16 Flags,\r
- IN UINT16 HeadIdx,\r
- IN OUT UINT16 *NextAvailIdx\r
+VirtioAppendDesc (\r
+ IN OUT VRING *Ring,\r
+ IN UINT64 BufferDeviceAddress,\r
+ IN UINT32 BufferSize,\r
+ IN UINT16 Flags,\r
+ IN OUT DESC_INDICES *Indices\r
+ );\r
+\r
+\r
+/**\r
+\r
+ Notify the host about the descriptor chain just built, and wait until the\r
+ host processes it.\r
+\r
+ @param[in] VirtIo The target virtio device to notify.\r
+\r
+ @param[in] VirtQueueId Identifies the queue for the target device.\r
+\r
+ @param[in,out] Ring The virtio ring with descriptors to submit.\r
+\r
+ @param[in] Indices Indices->NextDescIdx is not accessed.\r
+ Indices->HeadDescIdx identifies the head descriptor\r
+ of the descriptor chain.\r
+\r
+ @param[out] UsedLen On success, the total number of bytes, consecutively\r
+ across the buffers linked by the descriptor chain,\r
+ that the host wrote. May be NULL if the caller\r
+ doesn't care, or can compute the same information\r
+ from device-specific request structures linked by the\r
+ descriptor chain.\r
+\r
+ @return Error code from VirtIo->SetQueueNotify() if it fails.\r
+\r
+ @retval EFI_SUCCESS Otherwise, the host processed all descriptors.\r
+\r
+**/\r
+EFI_STATUS\r
+EFIAPI\r
+VirtioFlush (\r
+ IN VIRTIO_DEVICE_PROTOCOL *VirtIo,\r
+ IN UINT16 VirtQueueId,\r
+ IN OUT VRING *Ring,\r
+ IN DESC_INDICES *Indices,\r
+ OUT UINT32 *UsedLen OPTIONAL\r
+ );\r
+\r
+\r
+/**\r
+\r
+ Report the feature bits to the VirtIo 1.0 device that the VirtIo 1.0 driver\r
+ understands.\r
+\r
+ In VirtIo 1.0, a device can reject a self-inconsistent feature bitmap through\r
+ the new VSTAT_FEATURES_OK status bit. (For example if the driver requests a\r
+ higher level feature but clears a prerequisite feature.) This function is a\r
+ small wrapper around VIRTIO_DEVICE_PROTOCOL.SetGuestFeatures() that also\r
+ verifies if the VirtIo 1.0 device accepts the feature bitmap.\r
+\r
+ @param[in] VirtIo Report feature bits to this device.\r
+\r
+ @param[in] Features The set of feature bits that the driver wishes\r
+ to report. The caller is responsible to perform\r
+ any masking before calling this function; the\r
+ value is directly written with\r
+ VIRTIO_DEVICE_PROTOCOL.SetGuestFeatures().\r
+\r
+ @param[in,out] DeviceStatus On input, the status byte most recently written\r
+ to the device's status register. On output (even\r
+ on error), DeviceStatus will be updated so that\r
+ it is suitable for further status bit\r
+ manipulation and writing to the device's status\r
+ register.\r
+\r
+ @retval EFI_SUCCESS The device accepted the configuration in Features.\r
+\r
+ @return EFI_UNSUPPORTED The device rejected the configuration in Features.\r
+\r
+ @retval EFI_UNSUPPORTED VirtIo->Revision is smaller than 1.0.0.\r
+\r
+ @return Error codes from the SetGuestFeatures(),\r
+ SetDeviceStatus(), GetDeviceStatus() member\r
+ functions.\r
+\r
+**/\r
+EFI_STATUS\r
+EFIAPI\r
+Virtio10WriteFeatures (\r
+ IN VIRTIO_DEVICE_PROTOCOL *VirtIo,\r
+ IN UINT64 Features,\r
+ IN OUT UINT8 *DeviceStatus\r
);\r
\r
+/**\r
+ Provides the virtio device address required to access system memory from a\r
+ DMA bus master.\r
+\r
+ The interface follows the same usage pattern as defined in UEFI spec 2.6\r
+ (Section 13.2 PCI Root Bridge I/O Protocol)\r
+\r
+ The VirtioMapAllBytesInSharedBuffer() is similar to VIRTIO_MAP_SHARED\r
+ with exception that NumberOfBytes is IN-only parameter. The function\r
+ maps all the bytes specified in NumberOfBytes param in one consecutive\r
+ range.\r
+\r
+ @param[in] VirtIo The virtio device for which the mapping is\r
+ requested.\r
+\r
+ @param[in] Operation Indicates if the bus master is going to\r
+ read or write to system memory.\r
+\r
+ @param[in] HostAddress The system memory address to map to shared\r
+ buffer address.\r
+\r
+ @param[in] NumberOfBytes Number of bytes to map.\r
+\r
+ @param[out] DeviceAddress The resulting shared map address for the\r
+ bus master to access the hosts HostAddress.\r
+\r
+ @param[out] Mapping A resulting token to pass to\r
+ VIRTIO_UNMAP_SHARED.\r
+\r
+\r
+ @retval EFI_SUCCESS The NumberOfBytes is succesfully mapped.\r
+ @retval EFI_UNSUPPORTED The HostAddress cannot be mapped as a\r
+ common buffer.\r
+ @retval EFI_INVALID_PARAMETER One or more parameters are invalid.\r
+ @retval EFI_OUT_OF_RESOURCES The request could not be completed due to\r
+ a lack of resources. This includes the case\r
+ when NumberOfBytes bytes cannot be mapped\r
+ in one consecutive range.\r
+ @retval EFI_DEVICE_ERROR The system hardware could not map the\r
+ requested address.\r
+**/\r
+EFI_STATUS\r
+EFIAPI\r
+VirtioMapAllBytesInSharedBuffer (\r
+ IN VIRTIO_DEVICE_PROTOCOL *VirtIo,\r
+ IN VIRTIO_MAP_OPERATION Operation,\r
+ IN VOID *HostAddress,\r
+ IN UINTN NumberOfBytes,\r
+ OUT EFI_PHYSICAL_ADDRESS *DeviceAddress,\r
+ OUT VOID **Mapping\r
+ );\r
#endif // _VIRTIO_LIB_H_\r
projects / mirror_edk2.git / blobdiff