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 SPDX-License-Identifier: BSD-2-Clause-Patent
14 #ifndef __VIRTIO_DEVICE_H__
15 #define __VIRTIO_DEVICE_H__
17 #include <IndustryStandard/Virtio.h>
20 // VirtIo Specification Revision: Major[31:24].Minor[23:16].Revision[15:0]
22 #define VIRTIO_SPEC_REVISION(major,minor,revision) \
23 ((((major) & 0xFF) << 24) | (((minor) & 0xFF) << 16) | ((revision) & 0xFFFF))
25 #define VIRTIO_DEVICE_PROTOCOL_GUID { \
26 0xfa920010, 0x6785, 0x4941, {0xb6, 0xec, 0x49, 0x8c, 0x57, 0x9f, 0x16, 0x0a }\
29 typedef struct _VIRTIO_DEVICE_PROTOCOL VIRTIO_DEVICE_PROTOCOL
;
32 // VIRTIO Operation for VIRTIO_MAP_SHARED
36 // A read operation from system memory by a bus master
38 VirtioOperationBusMasterRead
,
40 // A write operation to system memory by a bus master
42 VirtioOperationBusMasterWrite
,
44 // Provides both read and write access to system memory by both the
45 // processor and a bus master
47 VirtioOperationBusMasterCommonBuffer
,
48 } VIRTIO_MAP_OPERATION
;
52 Read a word from the device-specific I/O region of the Virtio Header.
54 @param[in] This This instance of VIRTIO_DEVICE_PROTOCOL
56 @param[in] FieldOffset Source offset.
58 @param[in] FieldSize Source field size in bytes, must be in {1, 2, 4, 8}.
60 @param[in] BufferSize Number of bytes available in the target buffer. Must
63 @param[out] Buffer Target buffer.
65 @retval EFI_SUCCESS The data was read successfully.
66 @retval EFI_UNSUPPORTED The underlying IO device doesn't support the
67 provided address offset and read size.
68 @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a
70 @retval EFI_INVALID_PARAMETER One or more parameters are invalid.
75 (EFIAPI
*VIRTIO_DEVICE_READ
) (
76 IN VIRTIO_DEVICE_PROTOCOL
*This
,
85 Write a word to the device-specific I/O region of the Virtio Header.
87 @param[in] This This instance of VIRTIO_DEVICE_PROTOCOL
89 @param[in] FieldOffset Destination offset.
91 @param[in] FieldSize Destination field size in bytes,
92 must be in {1, 2, 4, 8}.
94 @param[out] Value Value to write.
96 @retval EFI_SUCCESS The data was written successfully.
97 @retval EFI_UNSUPPORTED The underlying IO device doesn't support the
98 provided address offset and write size.
99 @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a
101 @retval EFI_INVALID_PARAMETER One or more parameters are invalid.
106 (EFIAPI
*VIRTIO_DEVICE_WRITE
) (
107 IN VIRTIO_DEVICE_PROTOCOL
*This
,
108 IN UINTN FieldOffset
,
114 Read the device features field from the Virtio Header.
116 @param[in] This This instance of VIRTIO_DEVICE_PROTOCOL
118 @param[out] DeviceFeatures The device features field.
120 @retval EFI_SUCCESS The data was read successfully.
121 @retval EFI_UNSUPPORTED The underlying IO device doesn't support the
122 provided address offset and read size.
123 @retval EFI_INVALID_PARAMETER DeviceFeatures is NULL
127 (EFIAPI
*VIRTIO_GET_DEVICE_FEATURES
) (
128 IN VIRTIO_DEVICE_PROTOCOL
*This
,
129 OUT UINT64
*DeviceFeatures
133 Write the guest features field in the Virtio Header.
135 @param[in] This This instance of VIRTIO_DEVICE_PROTOCOL
137 @param[in] Features The guest features field
142 (EFIAPI
*VIRTIO_SET_GUEST_FEATURES
) (
143 IN VIRTIO_DEVICE_PROTOCOL
*This
,
148 Write the queue address field(s) in the Virtio Header.
150 @param[in] This This instance of VIRTIO_DEVICE_PROTOCOL
152 @param[in] Ring The initialized VRING object to take the
153 addresses from. The caller is responsible for
154 ensuring that on input, all Ring->NumPages pages,
155 starting at Ring->Base, have been successfully
156 mapped with a single call to
157 This->MapSharedBuffer() for CommonBuffer bus
160 @param[in] RingBaseShift Adding this value using UINT64 arithmetic to the
161 addresses found in Ring translates them from
162 system memory to bus addresses. The caller shall
163 calculate RingBaseShift as
164 (DeviceAddress - (UINT64)(UINTN)HostAddress),
165 where DeviceAddress and HostAddress (i.e.,
166 Ring->Base) were output and input parameters of
167 This->MapSharedBuffer(), respectively.
169 @retval EFI_SUCCESS The data was written successfully.
170 @retval EFI_UNSUPPORTED The underlying IO device doesn't support the
171 provided address offset and write size.
175 (EFIAPI
*VIRTIO_SET_QUEUE_ADDRESS
) (
176 IN VIRTIO_DEVICE_PROTOCOL
*This
,
178 IN UINT64 RingBaseShift
183 Write the queue select field in the Virtio Header.
185 Writing to the queue select field sets the index of the queue to which
186 operations such as SetQueueAlign and GetQueueNumMax apply.
188 @param[in] This This instance of VIRTIO_DEVICE_PROTOCOL
190 @param[in] Index The index of the queue to select
192 @retval EFI_SUCCESS The data was written successfully.
193 @retval EFI_UNSUPPORTED The underlying IO device doesn't support the
194 provided address offset and write size.
198 (EFIAPI
*VIRTIO_SET_QUEUE_SEL
) (
199 IN VIRTIO_DEVICE_PROTOCOL
*This
,
205 Write the queue notify field in the Virtio Header.
207 @param[in] This This instance of VIRTIO_DEVICE_PROTOCOL
209 @param[in] Address The 32-bit Queue Notify field
211 @retval EFI_SUCCESS The data was written successfully.
212 @retval EFI_UNSUPPORTED The underlying IO device doesn't support the
213 provided address offset and write size.
217 (EFIAPI
*VIRTIO_SET_QUEUE_NOTIFY
) (
218 IN VIRTIO_DEVICE_PROTOCOL
*This
,
223 Write the queue alignment field in the Virtio Header.
225 The queue to which the alignment applies is selected by the Queue Select
228 Note: This operation is not implemented by the VirtIo over PCI. The PCI
229 implementation of this protocol returns EFI_SUCCESS.
231 @param[in] This This instance of VIRTIO_DEVICE_PROTOCOL
233 @param[in] Alignment The alignment boundary of the Used Ring in bytes.
234 Must be a power of 2.
236 @retval EFI_SUCCESS The data was written successfully.
237 @retval EFI_UNSUPPORTED The underlying IO device doesn't support the
238 provided address offset and write size.
242 (EFIAPI
*VIRTIO_SET_QUEUE_ALIGN
) (
243 IN VIRTIO_DEVICE_PROTOCOL
*This
,
248 Write the guest page size.
250 Note: This operation is not implemented by the VirtIo over PCI. The PCI
251 implementation of this protocol returns EFI_SUCCESS.
253 @param[in] This This instance of VIRTIO_DEVICE_PROTOCOL
255 @param[in] PageSize Size of the Guest page in bytes.
256 Must be a power of 2.
258 @retval EFI_SUCCESS The data was written successfully.
259 @retval EFI_UNSUPPORTED The underlying IO device doesn't support the
260 provided address offset and write size.
264 (EFIAPI
*VIRTIO_SET_PAGE_SIZE
) (
265 IN VIRTIO_DEVICE_PROTOCOL
*This
,
271 Get the size of the virtqueue selected by the queue select field.
273 See Virtio spec Section 2.3
275 @param[in] This This instance of VIRTIO_DEVICE_PROTOCOL
277 @param[out] QueueNumMax The size of the virtqueue in bytes.
280 @retval EFI_SUCCESS The data was read successfully.
281 @retval EFI_UNSUPPORTED The underlying IO device doesn't support the
282 provided address offset and read size.
283 @retval EFI_INVALID_PARAMETER QueueNumMax is NULL
287 (EFIAPI
*VIRTIO_GET_QUEUE_NUM_MAX
) (
288 IN VIRTIO_DEVICE_PROTOCOL
*This
,
289 OUT UINT16
*QueueNumMax
294 Write to the QueueNum field in the Virtio Header.
296 This function only applies to Virtio-MMIO and may be a stub for other
297 implementations. See Virtio Spec appendix X.
299 @param[in] This This instance of VIRTIO_DEVICE_PROTOCOL
301 @param[in] QueueSize The number of elements in the queue.
303 @retval EFI_SUCCESS The data was written successfully.
304 @retval EFI_UNSUPPORTED The underlying IO device doesn't support the
305 provided address offset and write size.
309 (EFIAPI
*VIRTIO_SET_QUEUE_NUM
) (
310 IN VIRTIO_DEVICE_PROTOCOL
*This
,
316 Get the DeviceStatus field from the Virtio Header.
318 @param[in] This This instance of VIRTIO_DEVICE_PROTOCOL
320 @param[out] DeviceStatus The 8-bit value for the Device status field
322 @retval EFI_SUCCESS The data was read successfully.
323 @retval EFI_UNSUPPORTED The underlying IO device doesn't support the
324 provided address offset and read size.
325 @retval EFI_INVALID_PARAMETER DeviceStatus is NULL
329 (EFIAPI
*VIRTIO_GET_DEVICE_STATUS
) (
330 IN VIRTIO_DEVICE_PROTOCOL
*This
,
331 OUT UINT8
*DeviceStatus
336 Write the DeviceStatus field in the Virtio Header.
338 @param[in] This This instance of VIRTIO_DEVICE_PROTOCOL
340 @param[in] DeviceStatus The 8-bit value for the Device status field
342 @retval EFI_SUCCESS The data was written successfully.
343 @retval EFI_UNSUPPORTED The underlying IO device doesn't support the
344 provided address offset and write size.
348 (EFIAPI
*VIRTIO_SET_DEVICE_STATUS
) (
349 IN VIRTIO_DEVICE_PROTOCOL
*This
,
350 IN UINT8 DeviceStatus
355 Allocates pages that are suitable for an VirtioOperationBusMasterCommonBuffer
356 mapping. This means that the buffer allocated by this function supports
357 simultaneous access by both the processor and the bus master. The device
358 address that the bus master uses to access the buffer must be retrieved with
359 a call to VIRTIO_MAP_SHARED.
361 @param[in] This The protocol instance pointer.
363 @param[in] Pages The number of pages to allocate.
365 @param[in,out] HostAddress A pointer to store the system memory base
366 address of the allocated range.
368 @retval EFI_SUCCESS The requested memory pages were allocated.
369 @retval EFI_OUT_OF_RESOURCES The memory pages could not be allocated.
374 (EFIAPI
*VIRTIO_ALLOCATE_SHARED
)(
375 IN VIRTIO_DEVICE_PROTOCOL
*This
,
377 IN OUT VOID
**HostAddress
381 Frees memory that was allocated with VIRTIO_ALLOCATE_SHARED.
383 @param[in] This The protocol instance pointer.
385 @param[in] Pages The number of pages to free.
387 @param[in] HostAddress The system memory base address of the allocated
393 (EFIAPI
*VIRTIO_FREE_SHARED
)(
394 IN VIRTIO_DEVICE_PROTOCOL
*This
,
400 Provides the virtio device address required to access system memory from a
403 The interface follows the same usage pattern as defined in UEFI spec 2.6
404 (Section 13.2 PCI Root Bridge I/O Protocol)
406 @param[in] This The protocol instance pointer.
408 @param[in] Operation Indicates if the bus master is going to
409 read or write to system memory.
411 @param[in] HostAddress The system memory address to map to shared
414 @param[in,out] NumberOfBytes On input the number of bytes to map.
415 On output the number of bytes that were
418 @param[out] DeviceAddress The resulting shared map address for the
419 bus master to access the hosts HostAddress.
421 @param[out] Mapping A resulting token to pass to
424 @retval EFI_SUCCESS The range was mapped for the returned
426 @retval EFI_UNSUPPORTED The HostAddress cannot be mapped as a
428 @retval EFI_INVALID_PARAMETER One or more parameters are invalid.
429 @retval EFI_OUT_OF_RESOURCES The request could not be completed due to
431 @retval EFI_DEVICE_ERROR The system hardware could not map the
437 (EFIAPI
*VIRTIO_MAP_SHARED
) (
438 IN VIRTIO_DEVICE_PROTOCOL
*This
,
439 IN VIRTIO_MAP_OPERATION Operation
,
440 IN VOID
*HostAddress
,
441 IN OUT UINTN
*NumberOfBytes
,
442 OUT EFI_PHYSICAL_ADDRESS
*DeviceAddress
,
447 Completes the VIRTIO_MAP_SHARED operation and releases any corresponding
450 @param[in] This The protocol instance pointer.
452 @param[in] Mapping The mapping token returned from
455 @retval EFI_SUCCESS The range was unmapped.
456 @retval EFI_INVALID_PARAMETER Mapping is not a value that was returned by
457 VIRTIO_MAP_SHARED. Passing an invalid Mapping
458 token can cause undefined behavior.
459 @retval EFI_DEVICE_ERROR The data was not committed to the target
464 (EFIAPI
*VIRTIO_UNMAP_SHARED
)(
465 IN VIRTIO_DEVICE_PROTOCOL
*This
,
470 /// This protocol provides an abstraction over the VirtIo transport layer
472 /// DISCLAIMER: this protocol is a work in progress, and should not be used
473 /// outside of the EDK II tree.
475 struct _VIRTIO_DEVICE_PROTOCOL
{
477 // VirtIo Specification Revision encoded with VIRTIO_SPEC_REVISION()
481 // From the Virtio Spec
483 INT32 SubSystemDeviceId
;
485 VIRTIO_GET_DEVICE_FEATURES GetDeviceFeatures
;
486 VIRTIO_SET_GUEST_FEATURES SetGuestFeatures
;
488 VIRTIO_SET_QUEUE_ADDRESS SetQueueAddress
;
490 VIRTIO_SET_QUEUE_SEL SetQueueSel
;
492 VIRTIO_SET_QUEUE_NOTIFY SetQueueNotify
;
494 VIRTIO_SET_QUEUE_ALIGN SetQueueAlign
;
495 VIRTIO_SET_PAGE_SIZE SetPageSize
;
497 VIRTIO_GET_QUEUE_NUM_MAX GetQueueNumMax
;
498 VIRTIO_SET_QUEUE_NUM SetQueueNum
;
500 VIRTIO_GET_DEVICE_STATUS GetDeviceStatus
;
501 VIRTIO_SET_DEVICE_STATUS SetDeviceStatus
;
504 // Functions to read/write Device Specific headers
506 VIRTIO_DEVICE_WRITE WriteDevice
;
507 VIRTIO_DEVICE_READ ReadDevice
;
510 // Functions to allocate, free, map and unmap shared buffer
512 VIRTIO_ALLOCATE_SHARED AllocateSharedPages
;
513 VIRTIO_FREE_SHARED FreeSharedPages
;
514 VIRTIO_MAP_SHARED MapSharedBuffer
;
515 VIRTIO_UNMAP_SHARED UnmapSharedBuffer
;
518 extern EFI_GUID gVirtioDeviceProtocolGuid
;