OvmfPkg/MemEncryptSevLib: find pages of initial SMRAM save state map
[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. The caller is responsible for
160 ensuring that on input, all Ring->NumPages pages,
161 starting at Ring->Base, have been successfully
162 mapped with a single call to
163 This->MapSharedBuffer() for CommonBuffer bus
164 master operation.
165
166 @param[in] RingBaseShift Adding this value using UINT64 arithmetic to the
167 addresses found in Ring translates them from
168 system memory to bus addresses. The caller shall
169 calculate RingBaseShift as
170 (DeviceAddress - (UINT64)(UINTN)HostAddress),
171 where DeviceAddress and HostAddress (i.e.,
172 Ring->Base) were output and input parameters of
173 This->MapSharedBuffer(), respectively.
174
175 @retval EFI_SUCCESS The data was written successfully.
176 @retval EFI_UNSUPPORTED The underlying IO device doesn't support the
177 provided address offset and write size.
178 **/
179 typedef
180 EFI_STATUS
181 (EFIAPI *VIRTIO_SET_QUEUE_ADDRESS) (
182 IN VIRTIO_DEVICE_PROTOCOL *This,
183 IN VRING *Ring,
184 IN UINT64 RingBaseShift
185 );
186
187 /**
188
189 Write the queue select field in the Virtio Header.
190
191 Writing to the queue select field sets the index of the queue to which
192 operations such as SetQueueAlign and GetQueueNumMax apply.
193
194 @param[in] This This instance of VIRTIO_DEVICE_PROTOCOL
195
196 @param[in] Index The index of the queue to select
197
198 @retval EFI_SUCCESS The data was written successfully.
199 @retval EFI_UNSUPPORTED The underlying IO device doesn't support the
200 provided address offset and write size.
201 **/
202 typedef
203 EFI_STATUS
204 (EFIAPI *VIRTIO_SET_QUEUE_SEL) (
205 IN VIRTIO_DEVICE_PROTOCOL *This,
206 IN UINT16 Index
207 );
208
209 /**
210
211 Write the queue notify field in the Virtio Header.
212
213 @param[in] This This instance of VIRTIO_DEVICE_PROTOCOL
214
215 @param[in] Address The 32-bit Queue Notify field
216
217 @retval EFI_SUCCESS The data was written successfully.
218 @retval EFI_UNSUPPORTED The underlying IO device doesn't support the
219 provided address offset and write size.
220 **/
221 typedef
222 EFI_STATUS
223 (EFIAPI *VIRTIO_SET_QUEUE_NOTIFY) (
224 IN VIRTIO_DEVICE_PROTOCOL *This,
225 IN UINT16 Index
226 );
227
228 /**
229 Write the queue alignment field in the Virtio Header.
230
231 The queue to which the alignment applies is selected by the Queue Select
232 field.
233
234 Note: This operation is not implemented by the VirtIo over PCI. The PCI
235 implementation of this protocol returns EFI_SUCCESS.
236
237 @param[in] This This instance of VIRTIO_DEVICE_PROTOCOL
238
239 @param[in] Alignment The alignment boundary of the Used Ring in bytes.
240 Must be a power of 2.
241
242 @retval EFI_SUCCESS The data was written successfully.
243 @retval EFI_UNSUPPORTED The underlying IO device doesn't support the
244 provided address offset and write size.
245 **/
246 typedef
247 EFI_STATUS
248 (EFIAPI *VIRTIO_SET_QUEUE_ALIGN) (
249 IN VIRTIO_DEVICE_PROTOCOL *This,
250 IN UINT32 Alignment
251 );
252
253 /**
254 Write the guest page size.
255
256 Note: This operation is not implemented by the VirtIo over PCI. The PCI
257 implementation of this protocol returns EFI_SUCCESS.
258
259 @param[in] This This instance of VIRTIO_DEVICE_PROTOCOL
260
261 @param[in] PageSize Size of the Guest page in bytes.
262 Must be a power of 2.
263
264 @retval EFI_SUCCESS The data was written successfully.
265 @retval EFI_UNSUPPORTED The underlying IO device doesn't support the
266 provided address offset and write size.
267 **/
268 typedef
269 EFI_STATUS
270 (EFIAPI *VIRTIO_SET_PAGE_SIZE) (
271 IN VIRTIO_DEVICE_PROTOCOL *This,
272 IN UINT32 PageSize
273 );
274
275 /**
276
277 Get the size of the virtqueue selected by the queue select field.
278
279 See Virtio spec Section 2.3
280
281 @param[in] This This instance of VIRTIO_DEVICE_PROTOCOL
282
283 @param[out] QueueNumMax The size of the virtqueue in bytes.
284 Always a power of 2.
285
286 @retval EFI_SUCCESS The data was read successfully.
287 @retval EFI_UNSUPPORTED The underlying IO device doesn't support the
288 provided address offset and read size.
289 @retval EFI_INVALID_PARAMETER QueueNumMax is NULL
290 **/
291 typedef
292 EFI_STATUS
293 (EFIAPI *VIRTIO_GET_QUEUE_NUM_MAX) (
294 IN VIRTIO_DEVICE_PROTOCOL *This,
295 OUT UINT16 *QueueNumMax
296 );
297
298 /**
299
300 Write to the QueueNum field in the Virtio Header.
301
302 This function only applies to Virtio-MMIO and may be a stub for other
303 implementations. See Virtio Spec appendix X.
304
305 @param[in] This This instance of VIRTIO_DEVICE_PROTOCOL
306
307 @param[in] QueueSize The number of elements in the queue.
308
309 @retval EFI_SUCCESS The data was written successfully.
310 @retval EFI_UNSUPPORTED The underlying IO device doesn't support the
311 provided address offset and write size.
312 **/
313 typedef
314 EFI_STATUS
315 (EFIAPI *VIRTIO_SET_QUEUE_NUM) (
316 IN VIRTIO_DEVICE_PROTOCOL *This,
317 IN UINT16 QueueSize
318 );
319
320 /**
321
322 Get the DeviceStatus field from the Virtio Header.
323
324 @param[in] This This instance of VIRTIO_DEVICE_PROTOCOL
325
326 @param[out] DeviceStatus The 8-bit value for the Device status field
327
328 @retval EFI_SUCCESS The data was read successfully.
329 @retval EFI_UNSUPPORTED The underlying IO device doesn't support the
330 provided address offset and read size.
331 @retval EFI_INVALID_PARAMETER DeviceStatus is NULL
332 **/
333 typedef
334 EFI_STATUS
335 (EFIAPI *VIRTIO_GET_DEVICE_STATUS) (
336 IN VIRTIO_DEVICE_PROTOCOL *This,
337 OUT UINT8 *DeviceStatus
338 );
339
340 /**
341
342 Write the DeviceStatus field in the Virtio Header.
343
344 @param[in] This This instance of VIRTIO_DEVICE_PROTOCOL
345
346 @param[in] DeviceStatus The 8-bit value for the Device status field
347
348 @retval EFI_SUCCESS The data was written successfully.
349 @retval EFI_UNSUPPORTED The underlying IO device doesn't support the
350 provided address offset and write size.
351 **/
352 typedef
353 EFI_STATUS
354 (EFIAPI *VIRTIO_SET_DEVICE_STATUS) (
355 IN VIRTIO_DEVICE_PROTOCOL *This,
356 IN UINT8 DeviceStatus
357 );
358
359 /**
360
361 Allocates pages that are suitable for an VirtioOperationBusMasterCommonBuffer
362 mapping. This means that the buffer allocated by this function supports
363 simultaneous access by both the processor and the bus master. The device
364 address that the bus master uses to access the buffer must be retrieved with
365 a call to VIRTIO_MAP_SHARED.
366
367 @param[in] This The protocol instance pointer.
368
369 @param[in] Pages The number of pages to allocate.
370
371 @param[in,out] HostAddress A pointer to store the system memory base
372 address of the allocated range.
373
374 @retval EFI_SUCCESS The requested memory pages were allocated.
375 @retval EFI_OUT_OF_RESOURCES The memory pages could not be allocated.
376
377 **/
378 typedef
379 EFI_STATUS
380 (EFIAPI *VIRTIO_ALLOCATE_SHARED)(
381 IN VIRTIO_DEVICE_PROTOCOL *This,
382 IN UINTN Pages,
383 IN OUT VOID **HostAddress
384 );
385
386 /**
387 Frees memory that was allocated with VIRTIO_ALLOCATE_SHARED.
388
389 @param[in] This The protocol instance pointer.
390
391 @param[in] Pages The number of pages to free.
392
393 @param[in] HostAddress The system memory base address of the allocated
394 range.
395
396 **/
397 typedef
398 VOID
399 (EFIAPI *VIRTIO_FREE_SHARED)(
400 IN VIRTIO_DEVICE_PROTOCOL *This,
401 IN UINTN Pages,
402 IN VOID *HostAddress
403 );
404
405 /**
406 Provides the virtio device address required to access system memory from a
407 DMA bus master.
408
409 The interface follows the same usage pattern as defined in UEFI spec 2.6
410 (Section 13.2 PCI Root Bridge I/O Protocol)
411
412 @param[in] This The protocol instance pointer.
413
414 @param[in] Operation Indicates if the bus master is going to
415 read or write to system memory.
416
417 @param[in] HostAddress The system memory address to map to shared
418 buffer address.
419
420 @param[in,out] NumberOfBytes On input the number of bytes to map.
421 On output the number of bytes that were
422 mapped.
423
424 @param[out] DeviceAddress The resulting shared map address for the
425 bus master to access the hosts HostAddress.
426
427 @param[out] Mapping A resulting token to pass to
428 VIRTIO_UNMAP_SHARED.
429
430 @retval EFI_SUCCESS The range was mapped for the returned
431 NumberOfBytes.
432 @retval EFI_UNSUPPORTED The HostAddress cannot be mapped as a
433 common buffer.
434 @retval EFI_INVALID_PARAMETER One or more parameters are invalid.
435 @retval EFI_OUT_OF_RESOURCES The request could not be completed due to
436 a lack of resources.
437 @retval EFI_DEVICE_ERROR The system hardware could not map the
438 requested address.
439 **/
440
441 typedef
442 EFI_STATUS
443 (EFIAPI *VIRTIO_MAP_SHARED) (
444 IN VIRTIO_DEVICE_PROTOCOL *This,
445 IN VIRTIO_MAP_OPERATION Operation,
446 IN VOID *HostAddress,
447 IN OUT UINTN *NumberOfBytes,
448 OUT EFI_PHYSICAL_ADDRESS *DeviceAddress,
449 OUT VOID **Mapping
450 );
451
452 /**
453 Completes the VIRTIO_MAP_SHARED operation and releases any corresponding
454 resources.
455
456 @param[in] This The protocol instance pointer.
457
458 @param[in] Mapping The mapping token returned from
459 VIRTIO_MAP_SHARED.
460
461 @retval EFI_SUCCESS The range was unmapped.
462 @retval EFI_INVALID_PARAMETER Mapping is not a value that was returned by
463 VIRTIO_MAP_SHARED. Passing an invalid Mapping
464 token can cause undefined behavior.
465 @retval EFI_DEVICE_ERROR The data was not committed to the target
466 system memory.
467 **/
468 typedef
469 EFI_STATUS
470 (EFIAPI *VIRTIO_UNMAP_SHARED)(
471 IN VIRTIO_DEVICE_PROTOCOL *This,
472 IN VOID *Mapping
473 );
474
475 ///
476 /// This protocol provides an abstraction over the VirtIo transport layer
477 ///
478 /// DISCLAIMER: this protocol is a work in progress, and should not be used
479 /// outside of the EDK II tree.
480 ///
481 struct _VIRTIO_DEVICE_PROTOCOL {
482 //
483 // VirtIo Specification Revision encoded with VIRTIO_SPEC_REVISION()
484 //
485 UINT32 Revision;
486 //
487 // From the Virtio Spec
488 //
489 INT32 SubSystemDeviceId;
490
491 VIRTIO_GET_DEVICE_FEATURES GetDeviceFeatures;
492 VIRTIO_SET_GUEST_FEATURES SetGuestFeatures;
493
494 VIRTIO_SET_QUEUE_ADDRESS SetQueueAddress;
495
496 VIRTIO_SET_QUEUE_SEL SetQueueSel;
497
498 VIRTIO_SET_QUEUE_NOTIFY SetQueueNotify;
499
500 VIRTIO_SET_QUEUE_ALIGN SetQueueAlign;
501 VIRTIO_SET_PAGE_SIZE SetPageSize;
502
503 VIRTIO_GET_QUEUE_NUM_MAX GetQueueNumMax;
504 VIRTIO_SET_QUEUE_NUM SetQueueNum;
505
506 VIRTIO_GET_DEVICE_STATUS GetDeviceStatus;
507 VIRTIO_SET_DEVICE_STATUS SetDeviceStatus;
508
509 //
510 // Functions to read/write Device Specific headers
511 //
512 VIRTIO_DEVICE_WRITE WriteDevice;
513 VIRTIO_DEVICE_READ ReadDevice;
514
515 //
516 // Functions to allocate, free, map and unmap shared buffer
517 //
518 VIRTIO_ALLOCATE_SHARED AllocateSharedPages;
519 VIRTIO_FREE_SHARED FreeSharedPages;
520 VIRTIO_MAP_SHARED MapSharedBuffer;
521 VIRTIO_UNMAP_SHARED UnmapSharedBuffer;
522 };
523
524 extern EFI_GUID gVirtioDeviceProtocolGuid;
525
526 #endif