OvmfPkg/Virtio: take RingBaseShift in SetQueueAddress()
[mirror_edk2.git] / OvmfPkg / Include / Protocol / VirtioDevice.h
CommitLineData
fc4d1ce5
OM
1/** @file\r
2 Virtio Device\r
3\r
4 DISCLAIMER: the VIRTIO_DEVICE_PROTOCOL introduced here is a work in progress,\r
5 and should not be used outside of the EDK II tree.\r
6\r
7 Copyright (c) 2013, ARM Ltd. All rights reserved.<BR>\r
87811526 8 Copyright (c) 2017, AMD Inc, All rights reserved.<BR>\r
fc4d1ce5
OM
9\r
10 This program and the accompanying materials are licensed and made available\r
11 under the terms and conditions of the BSD License which accompanies this\r
12 distribution. The full text of the license may be found at\r
13 http://opensource.org/licenses/bsd-license.php\r
14\r
15 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, WITHOUT\r
16 WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.\r
17\r
18**/\r
19\r
20#ifndef __VIRTIO_DEVICE_H__\r
21#define __VIRTIO_DEVICE_H__\r
22\r
07af4eee
LE
23#include <IndustryStandard/Virtio.h>\r
24\r
a136bc3c
BS
25//\r
26// VirtIo Specification Revision: Major[31:24].Minor[23:16].Revision[15:0]\r
27//\r
fc4d1ce5
OM
28#define VIRTIO_SPEC_REVISION(major,minor,revision) \\r
29 ((((major) & 0xFF) << 24) | (((minor) & 0xFF) << 16) | ((revision) & 0xFFFF))\r
30\r
31#define VIRTIO_DEVICE_PROTOCOL_GUID { \\r
32 0xfa920010, 0x6785, 0x4941, {0xb6, 0xec, 0x49, 0x8c, 0x57, 0x9f, 0x16, 0x0a }\\r
33 }\r
34\r
35typedef struct _VIRTIO_DEVICE_PROTOCOL VIRTIO_DEVICE_PROTOCOL;\r
36\r
87811526
BS
37//\r
38// VIRTIO Operation for VIRTIO_MAP_SHARED\r
39//\r
40typedef enum {\r
41 //\r
42 // A read operation from system memory by a bus master\r
43 //\r
44 VirtioOperationBusMasterRead,\r
45 //\r
46 // A write operation to system memory by a bus master\r
47 //\r
48 VirtioOperationBusMasterWrite,\r
49 //\r
50 // Provides both read and write access to system memory by both the\r
51 // processor and a bus master\r
52 //\r
53 VirtioOperationBusMasterCommonBuffer,\r
54} VIRTIO_MAP_OPERATION;\r
55\r
fc4d1ce5
OM
56/**\r
57\r
58 Read a word from the device-specific I/O region of the Virtio Header.\r
59\r
60 @param[in] This This instance of VIRTIO_DEVICE_PROTOCOL\r
61\r
62 @param[in] FieldOffset Source offset.\r
63\r
64 @param[in] FieldSize Source field size in bytes, must be in {1, 2, 4, 8}.\r
65\r
66 @param[in] BufferSize Number of bytes available in the target buffer. Must\r
67 equal FieldSize.\r
68\r
69 @param[out] Buffer Target buffer.\r
70\r
71 @retval EFI_SUCCESS The data was read successfully.\r
72 @retval EFI_UNSUPPORTED The underlying IO device doesn't support the\r
73 provided address offset and read size.\r
74 @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a\r
75 lack of resources.\r
76 @retval EFI_INVALID_PARAMETER One or more parameters are invalid.\r
77\r
78**/\r
79typedef\r
80EFI_STATUS\r
81(EFIAPI *VIRTIO_DEVICE_READ) (\r
82 IN VIRTIO_DEVICE_PROTOCOL *This,\r
83 IN UINTN FieldOffset,\r
84 IN UINTN FieldSize,\r
85 IN UINTN BufferSize,\r
86 OUT VOID *Buffer\r
87 );\r
88\r
89/**\r
90\r
91 Write a word to the device-specific I/O region of the Virtio Header.\r
92\r
93 @param[in] This This instance of VIRTIO_DEVICE_PROTOCOL\r
94\r
95 @param[in] FieldOffset Destination offset.\r
96\r
97 @param[in] FieldSize Destination field size in bytes,\r
98 must be in {1, 2, 4, 8}.\r
99\r
100 @param[out] Value Value to write.\r
101\r
102 @retval EFI_SUCCESS The data was written successfully.\r
103 @retval EFI_UNSUPPORTED The underlying IO device doesn't support the\r
104 provided address offset and write size.\r
105 @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a\r
106 lack of resources.\r
107 @retval EFI_INVALID_PARAMETER One or more parameters are invalid.\r
108\r
109**/\r
110typedef\r
111EFI_STATUS\r
112(EFIAPI *VIRTIO_DEVICE_WRITE) (\r
113 IN VIRTIO_DEVICE_PROTOCOL *This,\r
114 IN UINTN FieldOffset,\r
115 IN UINTN FieldSize,\r
116 IN UINT64 Value\r
117 );\r
118\r
119/**\r
120 Read the device features field from the Virtio Header.\r
121\r
122 @param[in] This This instance of VIRTIO_DEVICE_PROTOCOL\r
123\r
bc8fde6f 124 @param[out] DeviceFeatures The device features field.\r
fc4d1ce5
OM
125\r
126 @retval EFI_SUCCESS The data was read successfully.\r
127 @retval EFI_UNSUPPORTED The underlying IO device doesn't support the\r
128 provided address offset and read size.\r
129 @retval EFI_INVALID_PARAMETER DeviceFeatures is NULL\r
130**/\r
131typedef\r
132EFI_STATUS\r
133(EFIAPI *VIRTIO_GET_DEVICE_FEATURES) (\r
134 IN VIRTIO_DEVICE_PROTOCOL *This,\r
bc8fde6f 135 OUT UINT64 *DeviceFeatures\r
fc4d1ce5
OM
136 );\r
137\r
138/**\r
139 Write the guest features field in the Virtio Header.\r
140\r
141 @param[in] This This instance of VIRTIO_DEVICE_PROTOCOL\r
142\r
bc8fde6f 143 @param[in] Features The guest features field\r
fc4d1ce5
OM
144\r
145**/\r
146typedef\r
147EFI_STATUS\r
148(EFIAPI *VIRTIO_SET_GUEST_FEATURES) (\r
149 IN VIRTIO_DEVICE_PROTOCOL *This,\r
bc8fde6f 150 IN UINT64 Features\r
fc4d1ce5
OM
151 );\r
152\r
fc4d1ce5 153/**\r
07af4eee 154 Write the queue address field(s) in the Virtio Header.\r
fc4d1ce5
OM
155\r
156 @param[in] This This instance of VIRTIO_DEVICE_PROTOCOL\r
157\r
07af4eee 158 @param[in] Ring The initialized VRING object to take the\r
53a4c604
BS
159 addresses from. The caller is responsible for\r
160 ensuring that on input, all Ring->NumPages pages,\r
161 starting at Ring->Base, have been successfully\r
162 mapped with a single call to\r
163 This->MapSharedBuffer() for CommonBuffer bus\r
164 master operation.\r
165\r
166 @param[in] RingBaseShift Adding this value using UINT64 arithmetic to the\r
167 addresses found in Ring translates them from\r
168 system memory to bus addresses. The caller shall\r
169 calculate RingBaseShift as\r
170 (DeviceAddress - (UINT64)(UINTN)HostAddress),\r
171 where DeviceAddress and HostAddress (i.e.,\r
172 Ring->Base) were output and input parameters of\r
173 This->MapSharedBuffer(), respectively.\r
fc4d1ce5
OM
174\r
175 @retval EFI_SUCCESS The data was written successfully.\r
176 @retval EFI_UNSUPPORTED The underlying IO device doesn't support the\r
177 provided address offset and write size.\r
178**/\r
179typedef\r
180EFI_STATUS\r
181(EFIAPI *VIRTIO_SET_QUEUE_ADDRESS) (\r
182 IN VIRTIO_DEVICE_PROTOCOL *This,\r
53a4c604
BS
183 IN VRING *Ring,\r
184 IN UINT64 RingBaseShift\r
fc4d1ce5
OM
185 );\r
186\r
187/**\r
188\r
189 Write the queue select field in the Virtio Header.\r
190\r
191 Writing to the queue select field sets the index of the queue to which\r
192 operations such as SetQueueAlign and GetQueueNumMax apply.\r
193\r
194 @param[in] This This instance of VIRTIO_DEVICE_PROTOCOL\r
195\r
196 @param[in] Index The index of the queue to select\r
197\r
198 @retval EFI_SUCCESS The data was written successfully.\r
199 @retval EFI_UNSUPPORTED The underlying IO device doesn't support the\r
200 provided address offset and write size.\r
201**/\r
202typedef\r
203EFI_STATUS\r
204(EFIAPI *VIRTIO_SET_QUEUE_SEL) (\r
205 IN VIRTIO_DEVICE_PROTOCOL *This,\r
206 IN UINT16 Index\r
207 );\r
208\r
209/**\r
210\r
211 Write the queue notify field in the Virtio Header.\r
212\r
213 @param[in] This This instance of VIRTIO_DEVICE_PROTOCOL\r
214\r
215 @param[in] Address The 32-bit Queue Notify field\r
216\r
217 @retval EFI_SUCCESS The data was written successfully.\r
218 @retval EFI_UNSUPPORTED The underlying IO device doesn't support the\r
219 provided address offset and write size.\r
220**/\r
221typedef\r
222EFI_STATUS\r
223(EFIAPI *VIRTIO_SET_QUEUE_NOTIFY) (\r
224 IN VIRTIO_DEVICE_PROTOCOL *This,\r
225 IN UINT16 Index\r
226 );\r
227\r
228/**\r
229 Write the queue alignment field in the Virtio Header.\r
230\r
231 The queue to which the alignment applies is selected by the Queue Select\r
232 field.\r
233\r
234 Note: This operation is not implemented by the VirtIo over PCI. The PCI\r
235 implementation of this protocol returns EFI_SUCCESS.\r
236\r
237 @param[in] This This instance of VIRTIO_DEVICE_PROTOCOL\r
238\r
239 @param[in] Alignment The alignment boundary of the Used Ring in bytes.\r
240 Must be a power of 2.\r
241\r
242 @retval EFI_SUCCESS The data was written successfully.\r
243 @retval EFI_UNSUPPORTED The underlying IO device doesn't support the\r
244 provided address offset and write size.\r
245**/\r
246typedef\r
247EFI_STATUS\r
248(EFIAPI *VIRTIO_SET_QUEUE_ALIGN) (\r
249 IN VIRTIO_DEVICE_PROTOCOL *This,\r
250 IN UINT32 Alignment\r
251 );\r
252\r
253/**\r
254 Write the guest page size.\r
255\r
256 Note: This operation is not implemented by the VirtIo over PCI. The PCI\r
257 implementation of this protocol returns EFI_SUCCESS.\r
258\r
259 @param[in] This This instance of VIRTIO_DEVICE_PROTOCOL\r
260\r
261 @param[in] PageSize Size of the Guest page in bytes.\r
262 Must be a power of 2.\r
263\r
264 @retval EFI_SUCCESS The data was written successfully.\r
265 @retval EFI_UNSUPPORTED The underlying IO device doesn't support the\r
266 provided address offset and write size.\r
267**/\r
268typedef\r
269EFI_STATUS\r
270(EFIAPI *VIRTIO_SET_PAGE_SIZE) (\r
271 IN VIRTIO_DEVICE_PROTOCOL *This,\r
272 IN UINT32 PageSize\r
273 );\r
274\r
275/**\r
276\r
277 Get the size of the virtqueue selected by the queue select field.\r
278\r
279 See Virtio spec Section 2.3\r
280\r
281 @param[in] This This instance of VIRTIO_DEVICE_PROTOCOL\r
282\r
283 @param[out] QueueNumMax The size of the virtqueue in bytes.\r
284 Always a power of 2.\r
285\r
286 @retval EFI_SUCCESS The data was read successfully.\r
287 @retval EFI_UNSUPPORTED The underlying IO device doesn't support the\r
288 provided address offset and read size.\r
289 @retval EFI_INVALID_PARAMETER QueueNumMax is NULL\r
290**/\r
291typedef\r
292EFI_STATUS\r
293(EFIAPI *VIRTIO_GET_QUEUE_NUM_MAX) (\r
294 IN VIRTIO_DEVICE_PROTOCOL *This,\r
295 OUT UINT16 *QueueNumMax\r
296 );\r
297\r
298/**\r
299\r
300 Write to the QueueNum field in the Virtio Header.\r
301\r
302 This function only applies to Virtio-MMIO and may be a stub for other\r
303 implementations. See Virtio Spec appendix X.\r
304\r
305 @param[in] This This instance of VIRTIO_DEVICE_PROTOCOL\r
306\r
307 @param[in] QueueSize The number of elements in the queue.\r
308\r
309 @retval EFI_SUCCESS The data was written successfully.\r
310 @retval EFI_UNSUPPORTED The underlying IO device doesn't support the\r
311 provided address offset and write size.\r
312**/\r
313typedef\r
314EFI_STATUS\r
315(EFIAPI *VIRTIO_SET_QUEUE_NUM) (\r
316 IN VIRTIO_DEVICE_PROTOCOL *This,\r
317 IN UINT16 QueueSize\r
318 );\r
319\r
320/**\r
321\r
322 Get the DeviceStatus field from the Virtio Header.\r
323\r
324 @param[in] This This instance of VIRTIO_DEVICE_PROTOCOL\r
325\r
326 @param[out] DeviceStatus The 8-bit value for the Device status field\r
327\r
328 @retval EFI_SUCCESS The data was read successfully.\r
329 @retval EFI_UNSUPPORTED The underlying IO device doesn't support the\r
330 provided address offset and read size.\r
331 @retval EFI_INVALID_PARAMETER DeviceStatus is NULL\r
332**/\r
333typedef\r
334EFI_STATUS\r
335(EFIAPI *VIRTIO_GET_DEVICE_STATUS) (\r
336 IN VIRTIO_DEVICE_PROTOCOL *This,\r
337 OUT UINT8 *DeviceStatus\r
338 );\r
339\r
340/**\r
341\r
342 Write the DeviceStatus field in the Virtio Header.\r
343\r
344 @param[in] This This instance of VIRTIO_DEVICE_PROTOCOL\r
345\r
346 @param[in] DeviceStatus The 8-bit value for the Device status field\r
347\r
348 @retval EFI_SUCCESS The data was written successfully.\r
349 @retval EFI_UNSUPPORTED The underlying IO device doesn't support the\r
350 provided address offset and write size.\r
351**/\r
352typedef\r
353EFI_STATUS\r
354(EFIAPI *VIRTIO_SET_DEVICE_STATUS) (\r
355 IN VIRTIO_DEVICE_PROTOCOL *This,\r
356 IN UINT8 DeviceStatus\r
357 );\r
358\r
87811526
BS
359/**\r
360\r
361 Allocates pages that are suitable for an VirtioOperationBusMasterCommonBuffer\r
362 mapping. This means that the buffer allocated by this function supports\r
363 simultaneous access by both the processor and the bus master. The device\r
364 address that the bus master uses to access the buffer must be retrieved with\r
365 a call to VIRTIO_MAP_SHARED.\r
366\r
367 @param[in] This The protocol instance pointer.\r
368\r
369 @param[in] Pages The number of pages to allocate.\r
370\r
371 @param[in,out] HostAddress A pointer to store the system memory base\r
372 address of the allocated range.\r
373\r
374 @retval EFI_SUCCESS The requested memory pages were allocated.\r
375 @retval EFI_OUT_OF_RESOURCES The memory pages could not be allocated.\r
376\r
377**/\r
378typedef\r
379EFI_STATUS\r
380(EFIAPI *VIRTIO_ALLOCATE_SHARED)(\r
381 IN VIRTIO_DEVICE_PROTOCOL *This,\r
382 IN UINTN Pages,\r
383 IN OUT VOID **HostAddress\r
384 );\r
385\r
386/**\r
387 Frees memory that was allocated with VIRTIO_ALLOCATE_SHARED.\r
388\r
389 @param[in] This The protocol instance pointer.\r
390\r
391 @param[in] Pages The number of pages to free.\r
392\r
393 @param[in] HostAddress The system memory base address of the allocated\r
394 range.\r
395\r
396**/\r
397typedef\r
398VOID\r
399(EFIAPI *VIRTIO_FREE_SHARED)(\r
400 IN VIRTIO_DEVICE_PROTOCOL *This,\r
401 IN UINTN Pages,\r
402 IN VOID *HostAddress\r
403 );\r
404\r
405/**\r
406 Provides the virtio device address required to access system memory from a\r
407 DMA bus master.\r
408\r
409 The interface follows the same usage pattern as defined in UEFI spec 2.6\r
410 (Section 13.2 PCI Root Bridge I/O Protocol)\r
411\r
412 @param[in] This The protocol instance pointer.\r
413\r
414 @param[in] Operation Indicates if the bus master is going to\r
415 read or write to system memory.\r
416\r
417 @param[in] HostAddress The system memory address to map to shared\r
418 buffer address.\r
419\r
420 @param[in,out] NumberOfBytes On input the number of bytes to map.\r
421 On output the number of bytes that were\r
422 mapped.\r
423\r
424 @param[out] DeviceAddress The resulting shared map address for the\r
425 bus master to access the hosts HostAddress.\r
426\r
427 @param[out] Mapping A resulting token to pass to\r
428 VIRTIO_UNMAP_SHARED.\r
429\r
430 @retval EFI_SUCCESS The range was mapped for the returned\r
431 NumberOfBytes.\r
432 @retval EFI_UNSUPPORTED The HostAddress cannot be mapped as a\r
433 common buffer.\r
434 @retval EFI_INVALID_PARAMETER One or more parameters are invalid.\r
435 @retval EFI_OUT_OF_RESOURCES The request could not be completed due to\r
436 a lack of resources.\r
437 @retval EFI_DEVICE_ERROR The system hardware could not map the\r
438 requested address.\r
439**/\r
440\r
441typedef\r
442EFI_STATUS\r
443(EFIAPI *VIRTIO_MAP_SHARED) (\r
444 IN VIRTIO_DEVICE_PROTOCOL *This,\r
445 IN VIRTIO_MAP_OPERATION Operation,\r
446 IN VOID *HostAddress,\r
447 IN OUT UINTN *NumberOfBytes,\r
448 OUT EFI_PHYSICAL_ADDRESS *DeviceAddress,\r
449 OUT VOID **Mapping\r
450 );\r
451\r
452/**\r
453 Completes the VIRTIO_MAP_SHARED operation and releases any corresponding\r
454 resources.\r
455\r
456 @param[in] This The protocol instance pointer.\r
457\r
458 @param[in] Mapping The mapping token returned from\r
459 VIRTIO_MAP_SHARED.\r
460\r
461 @retval EFI_SUCCESS The range was unmapped.\r
462 @retval EFI_INVALID_PARAMETER Mapping is not a value that was returned by\r
463 VIRTIO_MAP_SHARED. Passing an invalid Mapping\r
464 token can cause undefined behavior.\r
465 @retval EFI_DEVICE_ERROR The data was not committed to the target\r
466 system memory.\r
467**/\r
468typedef\r
469EFI_STATUS\r
470(EFIAPI *VIRTIO_UNMAP_SHARED)(\r
471 IN VIRTIO_DEVICE_PROTOCOL *This,\r
472 IN VOID *Mapping\r
473 );\r
fc4d1ce5
OM
474\r
475///\r
476/// This protocol provides an abstraction over the VirtIo transport layer\r
477///\r
478/// DISCLAIMER: this protocol is a work in progress, and should not be used\r
479/// outside of the EDK II tree.\r
480///\r
481struct _VIRTIO_DEVICE_PROTOCOL {\r
a136bc3c
BS
482 //\r
483 // VirtIo Specification Revision encoded with VIRTIO_SPEC_REVISION()\r
484 //\r
fc4d1ce5 485 UINT32 Revision;\r
a136bc3c
BS
486 //\r
487 // From the Virtio Spec\r
488 //\r
fc4d1ce5
OM
489 INT32 SubSystemDeviceId;\r
490\r
491 VIRTIO_GET_DEVICE_FEATURES GetDeviceFeatures;\r
492 VIRTIO_SET_GUEST_FEATURES SetGuestFeatures;\r
493\r
fc4d1ce5
OM
494 VIRTIO_SET_QUEUE_ADDRESS SetQueueAddress;\r
495\r
496 VIRTIO_SET_QUEUE_SEL SetQueueSel;\r
497\r
498 VIRTIO_SET_QUEUE_NOTIFY SetQueueNotify;\r
499\r
500 VIRTIO_SET_QUEUE_ALIGN SetQueueAlign;\r
501 VIRTIO_SET_PAGE_SIZE SetPageSize;\r
502\r
503 VIRTIO_GET_QUEUE_NUM_MAX GetQueueNumMax;\r
504 VIRTIO_SET_QUEUE_NUM SetQueueNum;\r
505\r
506 VIRTIO_GET_DEVICE_STATUS GetDeviceStatus;\r
507 VIRTIO_SET_DEVICE_STATUS SetDeviceStatus;\r
508\r
a136bc3c 509 //\r
fc4d1ce5 510 // Functions to read/write Device Specific headers\r
a136bc3c 511 //\r
fc4d1ce5
OM
512 VIRTIO_DEVICE_WRITE WriteDevice;\r
513 VIRTIO_DEVICE_READ ReadDevice;\r
87811526
BS
514\r
515 //\r
516 // Functions to allocate, free, map and unmap shared buffer\r
517 //\r
518 VIRTIO_ALLOCATE_SHARED AllocateSharedPages;\r
519 VIRTIO_FREE_SHARED FreeSharedPages;\r
520 VIRTIO_MAP_SHARED MapSharedBuffer;\r
521 VIRTIO_UNMAP_SHARED UnmapSharedBuffer;\r
fc4d1ce5
OM
522};\r
523\r
524extern EFI_GUID gVirtioDeviceProtocolGuid;\r
525\r
526#endif\r