4 DISCLAIMER: the VIRTIO_DEVICE_PROTOCOL introduced here is a work in progress,
5 and should not be used outside of the EDK II tree.
7 Copyright (c) 2013, ARM Ltd. All rights reserved.<BR>
8 Copyright (c) 2017, AMD Inc, All rights reserved.<BR>
10 This program and the accompanying materials are licensed and made available
11 under the terms and conditions of the BSD License which accompanies this
12 distribution. The full text of the license may be found at
13 http://opensource.org/licenses/bsd-license.php
15 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, WITHOUT
16 WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
20 #ifndef __VIRTIO_DEVICE_H__
21 #define __VIRTIO_DEVICE_H__
23 #include <IndustryStandard/Virtio.h>
26 // VirtIo Specification Revision: Major[31:24].Minor[23:16].Revision[15:0]
28 #define VIRTIO_SPEC_REVISION(major,minor,revision) \
29 ((((major) & 0xFF) << 24) | (((minor) & 0xFF) << 16) | ((revision) & 0xFFFF))
31 #define VIRTIO_DEVICE_PROTOCOL_GUID { \
32 0xfa920010, 0x6785, 0x4941, {0xb6, 0xec, 0x49, 0x8c, 0x57, 0x9f, 0x16, 0x0a }\
35 typedef struct _VIRTIO_DEVICE_PROTOCOL VIRTIO_DEVICE_PROTOCOL
;
38 // VIRTIO Operation for VIRTIO_MAP_SHARED
42 // A read operation from system memory by a bus master
44 VirtioOperationBusMasterRead
,
46 // A write operation to system memory by a bus master
48 VirtioOperationBusMasterWrite
,
50 // Provides both read and write access to system memory by both the
51 // processor and a bus master
53 VirtioOperationBusMasterCommonBuffer
,
54 } VIRTIO_MAP_OPERATION
;
58 Read a word from the device-specific I/O region of the Virtio Header.
60 @param[in] This This instance of VIRTIO_DEVICE_PROTOCOL
62 @param[in] FieldOffset Source offset.
64 @param[in] FieldSize Source field size in bytes, 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.
71 @retval EFI_SUCCESS The data was read successfully.
72 @retval EFI_UNSUPPORTED The underlying IO device doesn't support the
73 provided address offset and read size.
74 @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a
76 @retval EFI_INVALID_PARAMETER One or more parameters are invalid.
81 (EFIAPI
*VIRTIO_DEVICE_READ
) (
82 IN VIRTIO_DEVICE_PROTOCOL
*This
,
91 Write a word to the device-specific I/O region of the Virtio Header.
93 @param[in] This This instance of VIRTIO_DEVICE_PROTOCOL
95 @param[in] FieldOffset Destination offset.
97 @param[in] FieldSize Destination field size in bytes,
98 must be in {1, 2, 4, 8}.
100 @param[out] Value Value to write.
102 @retval EFI_SUCCESS The data was written successfully.
103 @retval EFI_UNSUPPORTED The underlying IO device doesn't support the
104 provided address offset and write size.
105 @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a
107 @retval EFI_INVALID_PARAMETER One or more parameters are invalid.
112 (EFIAPI
*VIRTIO_DEVICE_WRITE
) (
113 IN VIRTIO_DEVICE_PROTOCOL
*This
,
114 IN UINTN FieldOffset
,
120 Read the device features field from the Virtio Header.
122 @param[in] This This instance of VIRTIO_DEVICE_PROTOCOL
124 @param[out] DeviceFeatures The device features field.
126 @retval EFI_SUCCESS The data was read successfully.
127 @retval EFI_UNSUPPORTED The underlying IO device doesn't support the
128 provided address offset and read size.
129 @retval EFI_INVALID_PARAMETER DeviceFeatures is NULL
133 (EFIAPI
*VIRTIO_GET_DEVICE_FEATURES
) (
134 IN VIRTIO_DEVICE_PROTOCOL
*This
,
135 OUT UINT64
*DeviceFeatures
139 Write the guest features field in the Virtio Header.
141 @param[in] This This instance of VIRTIO_DEVICE_PROTOCOL
143 @param[in] Features The guest features field
148 (EFIAPI
*VIRTIO_SET_GUEST_FEATURES
) (
149 IN VIRTIO_DEVICE_PROTOCOL
*This
,
154 Write the queue address field(s) in the Virtio Header.
156 @param[in] This This instance of VIRTIO_DEVICE_PROTOCOL
158 @param[in] Ring The initialized VRING object to take the
161 @retval EFI_SUCCESS The data was written successfully.
162 @retval EFI_UNSUPPORTED The underlying IO device doesn't support the
163 provided address offset and write size.
167 (EFIAPI
*VIRTIO_SET_QUEUE_ADDRESS
) (
168 IN VIRTIO_DEVICE_PROTOCOL
*This
,
174 Write the queue select field in the Virtio Header.
176 Writing to the queue select field sets the index of the queue to which
177 operations such as SetQueueAlign and GetQueueNumMax apply.
179 @param[in] This This instance of VIRTIO_DEVICE_PROTOCOL
181 @param[in] Index The index of the queue to select
183 @retval EFI_SUCCESS The data was written successfully.
184 @retval EFI_UNSUPPORTED The underlying IO device doesn't support the
185 provided address offset and write size.
189 (EFIAPI
*VIRTIO_SET_QUEUE_SEL
) (
190 IN VIRTIO_DEVICE_PROTOCOL
*This
,
196 Write the queue notify field in the Virtio Header.
198 @param[in] This This instance of VIRTIO_DEVICE_PROTOCOL
200 @param[in] Address The 32-bit Queue Notify field
202 @retval EFI_SUCCESS The data was written successfully.
203 @retval EFI_UNSUPPORTED The underlying IO device doesn't support the
204 provided address offset and write size.
208 (EFIAPI
*VIRTIO_SET_QUEUE_NOTIFY
) (
209 IN VIRTIO_DEVICE_PROTOCOL
*This
,
214 Write the queue alignment field in the Virtio Header.
216 The queue to which the alignment applies is selected by the Queue Select
219 Note: This operation is not implemented by the VirtIo over PCI. The PCI
220 implementation of this protocol returns EFI_SUCCESS.
222 @param[in] This This instance of VIRTIO_DEVICE_PROTOCOL
224 @param[in] Alignment The alignment boundary of the Used Ring in bytes.
225 Must be a power of 2.
227 @retval EFI_SUCCESS The data was written successfully.
228 @retval EFI_UNSUPPORTED The underlying IO device doesn't support the
229 provided address offset and write size.
233 (EFIAPI
*VIRTIO_SET_QUEUE_ALIGN
) (
234 IN VIRTIO_DEVICE_PROTOCOL
*This
,
239 Write the guest page size.
241 Note: This operation is not implemented by the VirtIo over PCI. The PCI
242 implementation of this protocol returns EFI_SUCCESS.
244 @param[in] This This instance of VIRTIO_DEVICE_PROTOCOL
246 @param[in] PageSize Size of the Guest page in bytes.
247 Must be a power of 2.
249 @retval EFI_SUCCESS The data was written successfully.
250 @retval EFI_UNSUPPORTED The underlying IO device doesn't support the
251 provided address offset and write size.
255 (EFIAPI
*VIRTIO_SET_PAGE_SIZE
) (
256 IN VIRTIO_DEVICE_PROTOCOL
*This
,
262 Get the size of the virtqueue selected by the queue select field.
264 See Virtio spec Section 2.3
266 @param[in] This This instance of VIRTIO_DEVICE_PROTOCOL
268 @param[out] QueueNumMax The size of the virtqueue in bytes.
271 @retval EFI_SUCCESS The data was read successfully.
272 @retval EFI_UNSUPPORTED The underlying IO device doesn't support the
273 provided address offset and read size.
274 @retval EFI_INVALID_PARAMETER QueueNumMax is NULL
278 (EFIAPI
*VIRTIO_GET_QUEUE_NUM_MAX
) (
279 IN VIRTIO_DEVICE_PROTOCOL
*This
,
280 OUT UINT16
*QueueNumMax
285 Write to the QueueNum field in the Virtio Header.
287 This function only applies to Virtio-MMIO and may be a stub for other
288 implementations. See Virtio Spec appendix X.
290 @param[in] This This instance of VIRTIO_DEVICE_PROTOCOL
292 @param[in] QueueSize The number of elements in the queue.
294 @retval EFI_SUCCESS The data was written successfully.
295 @retval EFI_UNSUPPORTED The underlying IO device doesn't support the
296 provided address offset and write size.
300 (EFIAPI
*VIRTIO_SET_QUEUE_NUM
) (
301 IN VIRTIO_DEVICE_PROTOCOL
*This
,
307 Get the DeviceStatus field from the Virtio Header.
309 @param[in] This This instance of VIRTIO_DEVICE_PROTOCOL
311 @param[out] DeviceStatus The 8-bit value for the Device status field
313 @retval EFI_SUCCESS The data was read successfully.
314 @retval EFI_UNSUPPORTED The underlying IO device doesn't support the
315 provided address offset and read size.
316 @retval EFI_INVALID_PARAMETER DeviceStatus is NULL
320 (EFIAPI
*VIRTIO_GET_DEVICE_STATUS
) (
321 IN VIRTIO_DEVICE_PROTOCOL
*This
,
322 OUT UINT8
*DeviceStatus
327 Write the DeviceStatus field in the Virtio Header.
329 @param[in] This This instance of VIRTIO_DEVICE_PROTOCOL
331 @param[in] DeviceStatus The 8-bit value for the Device status field
333 @retval EFI_SUCCESS The data was written successfully.
334 @retval EFI_UNSUPPORTED The underlying IO device doesn't support the
335 provided address offset and write size.
339 (EFIAPI
*VIRTIO_SET_DEVICE_STATUS
) (
340 IN VIRTIO_DEVICE_PROTOCOL
*This
,
341 IN UINT8 DeviceStatus
346 Allocates pages that are suitable for an VirtioOperationBusMasterCommonBuffer
347 mapping. This means that the buffer allocated by this function supports
348 simultaneous access by both the processor and the bus master. The device
349 address that the bus master uses to access the buffer must be retrieved with
350 a call to VIRTIO_MAP_SHARED.
352 @param[in] This The protocol instance pointer.
354 @param[in] Pages The number of pages to allocate.
356 @param[in,out] HostAddress A pointer to store the system memory base
357 address of the allocated range.
359 @retval EFI_SUCCESS The requested memory pages were allocated.
360 @retval EFI_OUT_OF_RESOURCES The memory pages could not be allocated.
365 (EFIAPI
*VIRTIO_ALLOCATE_SHARED
)(
366 IN VIRTIO_DEVICE_PROTOCOL
*This
,
368 IN OUT VOID
**HostAddress
372 Frees memory that was allocated with VIRTIO_ALLOCATE_SHARED.
374 @param[in] This The protocol instance pointer.
376 @param[in] Pages The number of pages to free.
378 @param[in] HostAddress The system memory base address of the allocated
384 (EFIAPI
*VIRTIO_FREE_SHARED
)(
385 IN VIRTIO_DEVICE_PROTOCOL
*This
,
391 Provides the virtio device address required to access system memory from a
394 The interface follows the same usage pattern as defined in UEFI spec 2.6
395 (Section 13.2 PCI Root Bridge I/O Protocol)
397 @param[in] This The protocol instance pointer.
399 @param[in] Operation Indicates if the bus master is going to
400 read or write to system memory.
402 @param[in] HostAddress The system memory address to map to shared
405 @param[in,out] NumberOfBytes On input the number of bytes to map.
406 On output the number of bytes that were
409 @param[out] DeviceAddress The resulting shared map address for the
410 bus master to access the hosts HostAddress.
412 @param[out] Mapping A resulting token to pass to
415 @retval EFI_SUCCESS The range was mapped for the returned
417 @retval EFI_UNSUPPORTED The HostAddress cannot be mapped as a
419 @retval EFI_INVALID_PARAMETER One or more parameters are invalid.
420 @retval EFI_OUT_OF_RESOURCES The request could not be completed due to
422 @retval EFI_DEVICE_ERROR The system hardware could not map the
428 (EFIAPI
*VIRTIO_MAP_SHARED
) (
429 IN VIRTIO_DEVICE_PROTOCOL
*This
,
430 IN VIRTIO_MAP_OPERATION Operation
,
431 IN VOID
*HostAddress
,
432 IN OUT UINTN
*NumberOfBytes
,
433 OUT EFI_PHYSICAL_ADDRESS
*DeviceAddress
,
438 Completes the VIRTIO_MAP_SHARED operation and releases any corresponding
441 @param[in] This The protocol instance pointer.
443 @param[in] Mapping The mapping token returned from
446 @retval EFI_SUCCESS The range was unmapped.
447 @retval EFI_INVALID_PARAMETER Mapping is not a value that was returned by
448 VIRTIO_MAP_SHARED. Passing an invalid Mapping
449 token can cause undefined behavior.
450 @retval EFI_DEVICE_ERROR The data was not committed to the target
455 (EFIAPI
*VIRTIO_UNMAP_SHARED
)(
456 IN VIRTIO_DEVICE_PROTOCOL
*This
,
461 /// This protocol provides an abstraction over the VirtIo transport layer
463 /// DISCLAIMER: this protocol is a work in progress, and should not be used
464 /// outside of the EDK II tree.
466 struct _VIRTIO_DEVICE_PROTOCOL
{
468 // VirtIo Specification Revision encoded with VIRTIO_SPEC_REVISION()
472 // From the Virtio Spec
474 INT32 SubSystemDeviceId
;
476 VIRTIO_GET_DEVICE_FEATURES GetDeviceFeatures
;
477 VIRTIO_SET_GUEST_FEATURES SetGuestFeatures
;
479 VIRTIO_SET_QUEUE_ADDRESS SetQueueAddress
;
481 VIRTIO_SET_QUEUE_SEL SetQueueSel
;
483 VIRTIO_SET_QUEUE_NOTIFY SetQueueNotify
;
485 VIRTIO_SET_QUEUE_ALIGN SetQueueAlign
;
486 VIRTIO_SET_PAGE_SIZE SetPageSize
;
488 VIRTIO_GET_QUEUE_NUM_MAX GetQueueNumMax
;
489 VIRTIO_SET_QUEUE_NUM SetQueueNum
;
491 VIRTIO_GET_DEVICE_STATUS GetDeviceStatus
;
492 VIRTIO_SET_DEVICE_STATUS SetDeviceStatus
;
495 // Functions to read/write Device Specific headers
497 VIRTIO_DEVICE_WRITE WriteDevice
;
498 VIRTIO_DEVICE_READ ReadDevice
;
501 // Functions to allocate, free, map and unmap shared buffer
503 VIRTIO_ALLOCATE_SHARED AllocateSharedPages
;
504 VIRTIO_FREE_SHARED FreeSharedPages
;
505 VIRTIO_MAP_SHARED MapSharedBuffer
;
506 VIRTIO_UNMAP_SHARED UnmapSharedBuffer
;
509 extern EFI_GUID gVirtioDeviceProtocolGuid
;