9a01932958a2901bc0e45e068dcc558ef463b3d1
[mirror_edk2.git] / OvmfPkg / Include / Protocol / VirtioDevice.h
1 /** @file
2 Virtio Device
3
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.
6
7 Copyright (c) 2013, ARM Ltd. All rights reserved.<BR>
8 Copyright (c) 2017, AMD Inc, All rights reserved.<BR>
9
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
14
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.
17
18 **/
19
20 #ifndef __VIRTIO_DEVICE_H__
21 #define __VIRTIO_DEVICE_H__
22
23 #include <IndustryStandard/Virtio.h>
24
25 //
26 // VirtIo Specification Revision: Major[31:24].Minor[23:16].Revision[15:0]
27 //
28 #define VIRTIO_SPEC_REVISION(major,minor,revision) \
29 ((((major) & 0xFF) << 24) | (((minor) & 0xFF) << 16) | ((revision) & 0xFFFF))
30
31 #define VIRTIO_DEVICE_PROTOCOL_GUID { \
32 0xfa920010, 0x6785, 0x4941, {0xb6, 0xec, 0x49, 0x8c, 0x57, 0x9f, 0x16, 0x0a }\
33 }
34
35 typedef struct _VIRTIO_DEVICE_PROTOCOL VIRTIO_DEVICE_PROTOCOL;
36
37 //
38 // VIRTIO Operation for VIRTIO_MAP_SHARED
39 //
40 typedef enum {
41 //
42 // A read operation from system memory by a bus master
43 //
44 VirtioOperationBusMasterRead,
45 //
46 // A write operation to system memory by a bus master
47 //
48 VirtioOperationBusMasterWrite,
49 //
50 // Provides both read and write access to system memory by both the
51 // processor and a bus master
52 //
53 VirtioOperationBusMasterCommonBuffer,
54 } VIRTIO_MAP_OPERATION;
55
56 /**
57
58 Read a word from the device-specific I/O region of the Virtio Header.
59
60 @param[in] This This instance of VIRTIO_DEVICE_PROTOCOL
61
62 @param[in] FieldOffset Source offset.
63
64 @param[in] FieldSize Source field size in bytes, 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 @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
75 lack of resources.
76 @retval EFI_INVALID_PARAMETER One or more parameters are invalid.
77
78 **/
79 typedef
80 EFI_STATUS
81 (EFIAPI *VIRTIO_DEVICE_READ) (
82 IN VIRTIO_DEVICE_PROTOCOL *This,
83 IN UINTN FieldOffset,
84 IN UINTN FieldSize,
85 IN UINTN BufferSize,
86 OUT VOID *Buffer
87 );
88
89 /**
90
91 Write a word to the device-specific I/O region of the Virtio Header.
92
93 @param[in] This This instance of VIRTIO_DEVICE_PROTOCOL
94
95 @param[in] FieldOffset Destination offset.
96
97 @param[in] FieldSize Destination field size in bytes,
98 must be in {1, 2, 4, 8}.
99
100 @param[out] Value Value to write.
101
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
106 lack of resources.
107 @retval EFI_INVALID_PARAMETER One or more parameters are invalid.
108
109 **/
110 typedef
111 EFI_STATUS
112 (EFIAPI *VIRTIO_DEVICE_WRITE) (
113 IN VIRTIO_DEVICE_PROTOCOL *This,
114 IN UINTN FieldOffset,
115 IN UINTN FieldSize,
116 IN UINT64 Value
117 );
118
119 /**
120 Read the device features field from the Virtio Header.
121
122 @param[in] This This instance of VIRTIO_DEVICE_PROTOCOL
123
124 @param[out] DeviceFeatures The device features field.
125
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
130 **/
131 typedef
132 EFI_STATUS
133 (EFIAPI *VIRTIO_GET_DEVICE_FEATURES) (
134 IN VIRTIO_DEVICE_PROTOCOL *This,
135 OUT UINT64 *DeviceFeatures
136 );
137
138 /**
139 Write the guest features field in the Virtio Header.
140
141 @param[in] This This instance of VIRTIO_DEVICE_PROTOCOL
142
143 @param[in] Features The guest features field
144
145 **/
146 typedef
147 EFI_STATUS
148 (EFIAPI *VIRTIO_SET_GUEST_FEATURES) (
149 IN VIRTIO_DEVICE_PROTOCOL *This,
150 IN UINT64 Features
151 );
152
153 /**
154 Write the queue address field(s) in the Virtio Header.
155
156 @param[in] This This instance of VIRTIO_DEVICE_PROTOCOL
157
158 @param[in] Ring The initialized VRING object to take the
159 addresses from.
160
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.
164 **/
165 typedef
166 EFI_STATUS
167 (EFIAPI *VIRTIO_SET_QUEUE_ADDRESS) (
168 IN VIRTIO_DEVICE_PROTOCOL *This,
169 IN VRING *Ring
170 );
171
172 /**
173
174 Write the queue select field in the Virtio Header.
175
176 Writing to the queue select field sets the index of the queue to which
177 operations such as SetQueueAlign and GetQueueNumMax apply.
178
179 @param[in] This This instance of VIRTIO_DEVICE_PROTOCOL
180
181 @param[in] Index The index of the queue to select
182
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.
186 **/
187 typedef
188 EFI_STATUS
189 (EFIAPI *VIRTIO_SET_QUEUE_SEL) (
190 IN VIRTIO_DEVICE_PROTOCOL *This,
191 IN UINT16 Index
192 );
193
194 /**
195
196 Write the queue notify field in the Virtio Header.
197
198 @param[in] This This instance of VIRTIO_DEVICE_PROTOCOL
199
200 @param[in] Address The 32-bit Queue Notify field
201
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.
205 **/
206 typedef
207 EFI_STATUS
208 (EFIAPI *VIRTIO_SET_QUEUE_NOTIFY) (
209 IN VIRTIO_DEVICE_PROTOCOL *This,
210 IN UINT16 Index
211 );
212
213 /**
214 Write the queue alignment field in the Virtio Header.
215
216 The queue to which the alignment applies is selected by the Queue Select
217 field.
218
219 Note: This operation is not implemented by the VirtIo over PCI. The PCI
220 implementation of this protocol returns EFI_SUCCESS.
221
222 @param[in] This This instance of VIRTIO_DEVICE_PROTOCOL
223
224 @param[in] Alignment The alignment boundary of the Used Ring in bytes.
225 Must be a power of 2.
226
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.
230 **/
231 typedef
232 EFI_STATUS
233 (EFIAPI *VIRTIO_SET_QUEUE_ALIGN) (
234 IN VIRTIO_DEVICE_PROTOCOL *This,
235 IN UINT32 Alignment
236 );
237
238 /**
239 Write the guest page size.
240
241 Note: This operation is not implemented by the VirtIo over PCI. The PCI
242 implementation of this protocol returns EFI_SUCCESS.
243
244 @param[in] This This instance of VIRTIO_DEVICE_PROTOCOL
245
246 @param[in] PageSize Size of the Guest page in bytes.
247 Must be a power of 2.
248
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.
252 **/
253 typedef
254 EFI_STATUS
255 (EFIAPI *VIRTIO_SET_PAGE_SIZE) (
256 IN VIRTIO_DEVICE_PROTOCOL *This,
257 IN UINT32 PageSize
258 );
259
260 /**
261
262 Get the size of the virtqueue selected by the queue select field.
263
264 See Virtio spec Section 2.3
265
266 @param[in] This This instance of VIRTIO_DEVICE_PROTOCOL
267
268 @param[out] QueueNumMax The size of the virtqueue in bytes.
269 Always a power of 2.
270
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
275 **/
276 typedef
277 EFI_STATUS
278 (EFIAPI *VIRTIO_GET_QUEUE_NUM_MAX) (
279 IN VIRTIO_DEVICE_PROTOCOL *This,
280 OUT UINT16 *QueueNumMax
281 );
282
283 /**
284
285 Write to the QueueNum field in the Virtio Header.
286
287 This function only applies to Virtio-MMIO and may be a stub for other
288 implementations. See Virtio Spec appendix X.
289
290 @param[in] This This instance of VIRTIO_DEVICE_PROTOCOL
291
292 @param[in] QueueSize The number of elements in the queue.
293
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.
297 **/
298 typedef
299 EFI_STATUS
300 (EFIAPI *VIRTIO_SET_QUEUE_NUM) (
301 IN VIRTIO_DEVICE_PROTOCOL *This,
302 IN UINT16 QueueSize
303 );
304
305 /**
306
307 Get the DeviceStatus field from the Virtio Header.
308
309 @param[in] This This instance of VIRTIO_DEVICE_PROTOCOL
310
311 @param[out] DeviceStatus The 8-bit value for the Device status field
312
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
317 **/
318 typedef
319 EFI_STATUS
320 (EFIAPI *VIRTIO_GET_DEVICE_STATUS) (
321 IN VIRTIO_DEVICE_PROTOCOL *This,
322 OUT UINT8 *DeviceStatus
323 );
324
325 /**
326
327 Write the DeviceStatus field in the Virtio Header.
328
329 @param[in] This This instance of VIRTIO_DEVICE_PROTOCOL
330
331 @param[in] DeviceStatus The 8-bit value for the Device status field
332
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.
336 **/
337 typedef
338 EFI_STATUS
339 (EFIAPI *VIRTIO_SET_DEVICE_STATUS) (
340 IN VIRTIO_DEVICE_PROTOCOL *This,
341 IN UINT8 DeviceStatus
342 );
343
344 /**
345
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.
351
352 @param[in] This The protocol instance pointer.
353
354 @param[in] Pages The number of pages to allocate.
355
356 @param[in,out] HostAddress A pointer to store the system memory base
357 address of the allocated range.
358
359 @retval EFI_SUCCESS The requested memory pages were allocated.
360 @retval EFI_OUT_OF_RESOURCES The memory pages could not be allocated.
361
362 **/
363 typedef
364 EFI_STATUS
365 (EFIAPI *VIRTIO_ALLOCATE_SHARED)(
366 IN VIRTIO_DEVICE_PROTOCOL *This,
367 IN UINTN Pages,
368 IN OUT VOID **HostAddress
369 );
370
371 /**
372 Frees memory that was allocated with VIRTIO_ALLOCATE_SHARED.
373
374 @param[in] This The protocol instance pointer.
375
376 @param[in] Pages The number of pages to free.
377
378 @param[in] HostAddress The system memory base address of the allocated
379 range.
380
381 **/
382 typedef
383 VOID
384 (EFIAPI *VIRTIO_FREE_SHARED)(
385 IN VIRTIO_DEVICE_PROTOCOL *This,
386 IN UINTN Pages,
387 IN VOID *HostAddress
388 );
389
390 /**
391 Provides the virtio device address required to access system memory from a
392 DMA bus master.
393
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)
396
397 @param[in] This The protocol instance pointer.
398
399 @param[in] Operation Indicates if the bus master is going to
400 read or write to system memory.
401
402 @param[in] HostAddress The system memory address to map to shared
403 buffer address.
404
405 @param[in,out] NumberOfBytes On input the number of bytes to map.
406 On output the number of bytes that were
407 mapped.
408
409 @param[out] DeviceAddress The resulting shared map address for the
410 bus master to access the hosts HostAddress.
411
412 @param[out] Mapping A resulting token to pass to
413 VIRTIO_UNMAP_SHARED.
414
415 @retval EFI_SUCCESS The range was mapped for the returned
416 NumberOfBytes.
417 @retval EFI_UNSUPPORTED The HostAddress cannot be mapped as a
418 common buffer.
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
421 a lack of resources.
422 @retval EFI_DEVICE_ERROR The system hardware could not map the
423 requested address.
424 **/
425
426 typedef
427 EFI_STATUS
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,
434 OUT VOID **Mapping
435 );
436
437 /**
438 Completes the VIRTIO_MAP_SHARED operation and releases any corresponding
439 resources.
440
441 @param[in] This The protocol instance pointer.
442
443 @param[in] Mapping The mapping token returned from
444 VIRTIO_MAP_SHARED.
445
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
451 system memory.
452 **/
453 typedef
454 EFI_STATUS
455 (EFIAPI *VIRTIO_UNMAP_SHARED)(
456 IN VIRTIO_DEVICE_PROTOCOL *This,
457 IN VOID *Mapping
458 );
459
460 ///
461 /// This protocol provides an abstraction over the VirtIo transport layer
462 ///
463 /// DISCLAIMER: this protocol is a work in progress, and should not be used
464 /// outside of the EDK II tree.
465 ///
466 struct _VIRTIO_DEVICE_PROTOCOL {
467 //
468 // VirtIo Specification Revision encoded with VIRTIO_SPEC_REVISION()
469 //
470 UINT32 Revision;
471 //
472 // From the Virtio Spec
473 //
474 INT32 SubSystemDeviceId;
475
476 VIRTIO_GET_DEVICE_FEATURES GetDeviceFeatures;
477 VIRTIO_SET_GUEST_FEATURES SetGuestFeatures;
478
479 VIRTIO_SET_QUEUE_ADDRESS SetQueueAddress;
480
481 VIRTIO_SET_QUEUE_SEL SetQueueSel;
482
483 VIRTIO_SET_QUEUE_NOTIFY SetQueueNotify;
484
485 VIRTIO_SET_QUEUE_ALIGN SetQueueAlign;
486 VIRTIO_SET_PAGE_SIZE SetPageSize;
487
488 VIRTIO_GET_QUEUE_NUM_MAX GetQueueNumMax;
489 VIRTIO_SET_QUEUE_NUM SetQueueNum;
490
491 VIRTIO_GET_DEVICE_STATUS GetDeviceStatus;
492 VIRTIO_SET_DEVICE_STATUS SetDeviceStatus;
493
494 //
495 // Functions to read/write Device Specific headers
496 //
497 VIRTIO_DEVICE_WRITE WriteDevice;
498 VIRTIO_DEVICE_READ ReadDevice;
499
500 //
501 // Functions to allocate, free, map and unmap shared buffer
502 //
503 VIRTIO_ALLOCATE_SHARED AllocateSharedPages;
504 VIRTIO_FREE_SHARED FreeSharedPages;
505 VIRTIO_MAP_SHARED MapSharedBuffer;
506 VIRTIO_UNMAP_SHARED UnmapSharedBuffer;
507 };
508
509 extern EFI_GUID gVirtioDeviceProtocolGuid;
510
511 #endif