OvmfPkg/VirtioDevice.h: Introduced VIRTIO_DEVICE_PROTOCOL protocol
[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
8\r
9 This program and the accompanying materials are licensed and made available\r
10 under the terms and conditions of the BSD License which accompanies this\r
11 distribution. The full text of the license may be found at\r
12 http://opensource.org/licenses/bsd-license.php\r
13\r
14 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, WITHOUT\r
15 WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.\r
16\r
17**/\r
18\r
19#ifndef __VIRTIO_DEVICE_H__\r
20#define __VIRTIO_DEVICE_H__\r
21\r
22// VirtIo Specification Revision: Major[31:24].Minor[23:16].Revision[15:0\r
23#define VIRTIO_SPEC_REVISION(major,minor,revision) \\r
24 ((((major) & 0xFF) << 24) | (((minor) & 0xFF) << 16) | ((revision) & 0xFFFF))\r
25\r
26#define VIRTIO_DEVICE_PROTOCOL_GUID { \\r
27 0xfa920010, 0x6785, 0x4941, {0xb6, 0xec, 0x49, 0x8c, 0x57, 0x9f, 0x16, 0x0a }\\r
28 }\r
29\r
30typedef struct _VIRTIO_DEVICE_PROTOCOL VIRTIO_DEVICE_PROTOCOL;\r
31\r
32/**\r
33\r
34 Read a word from the device-specific I/O region of the Virtio Header.\r
35\r
36 @param[in] This This instance of VIRTIO_DEVICE_PROTOCOL\r
37\r
38 @param[in] FieldOffset Source offset.\r
39\r
40 @param[in] FieldSize Source field size in bytes, must be in {1, 2, 4, 8}.\r
41\r
42 @param[in] BufferSize Number of bytes available in the target buffer. Must\r
43 equal FieldSize.\r
44\r
45 @param[out] Buffer Target buffer.\r
46\r
47 @retval EFI_SUCCESS The data was read successfully.\r
48 @retval EFI_UNSUPPORTED The underlying IO device doesn't support the\r
49 provided address offset and read size.\r
50 @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a\r
51 lack of resources.\r
52 @retval EFI_INVALID_PARAMETER One or more parameters are invalid.\r
53\r
54**/\r
55typedef\r
56EFI_STATUS\r
57(EFIAPI *VIRTIO_DEVICE_READ) (\r
58 IN VIRTIO_DEVICE_PROTOCOL *This,\r
59 IN UINTN FieldOffset,\r
60 IN UINTN FieldSize,\r
61 IN UINTN BufferSize,\r
62 OUT VOID *Buffer\r
63 );\r
64\r
65/**\r
66\r
67 Write a word to the device-specific I/O region of the Virtio Header.\r
68\r
69 @param[in] This This instance of VIRTIO_DEVICE_PROTOCOL\r
70\r
71 @param[in] FieldOffset Destination offset.\r
72\r
73 @param[in] FieldSize Destination field size in bytes,\r
74 must be in {1, 2, 4, 8}.\r
75\r
76 @param[out] Value Value to write.\r
77\r
78 @retval EFI_SUCCESS The data was written successfully.\r
79 @retval EFI_UNSUPPORTED The underlying IO device doesn't support the\r
80 provided address offset and write size.\r
81 @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a\r
82 lack of resources.\r
83 @retval EFI_INVALID_PARAMETER One or more parameters are invalid.\r
84\r
85**/\r
86typedef\r
87EFI_STATUS\r
88(EFIAPI *VIRTIO_DEVICE_WRITE) (\r
89 IN VIRTIO_DEVICE_PROTOCOL *This,\r
90 IN UINTN FieldOffset,\r
91 IN UINTN FieldSize,\r
92 IN UINT64 Value\r
93 );\r
94\r
95/**\r
96 Read the device features field from the Virtio Header.\r
97\r
98 @param[in] This This instance of VIRTIO_DEVICE_PROTOCOL\r
99\r
100 @param[out] DeviceFeatures The 32-bit device features field.\r
101\r
102 @retval EFI_SUCCESS The data was read successfully.\r
103 @retval EFI_UNSUPPORTED The underlying IO device doesn't support the\r
104 provided address offset and read size.\r
105 @retval EFI_INVALID_PARAMETER DeviceFeatures is NULL\r
106**/\r
107typedef\r
108EFI_STATUS\r
109(EFIAPI *VIRTIO_GET_DEVICE_FEATURES) (\r
110 IN VIRTIO_DEVICE_PROTOCOL *This,\r
111 OUT UINT32 *DeviceFeatures\r
112 );\r
113\r
114/**\r
115 Write the guest features field in the Virtio Header.\r
116\r
117 @param[in] This This instance of VIRTIO_DEVICE_PROTOCOL\r
118\r
119 @param[in] Features The 32-bit guest guest features field\r
120\r
121**/\r
122typedef\r
123EFI_STATUS\r
124(EFIAPI *VIRTIO_SET_GUEST_FEATURES) (\r
125 IN VIRTIO_DEVICE_PROTOCOL *This,\r
126 IN UINT32 Features\r
127 );\r
128\r
129/**\r
130 Read the queue address field from the Virtio Header.\r
131\r
132 QueueAddress is the address of the virtqueue divided by 4096.\r
133\r
134 @param[in] This This instance of VIRTIO_DEVICE_PROTOCOL\r
135\r
136 @param[out] QueueAddress The 32-bit queue address field.\r
137\r
138 @retval EFI_SUCCESS The data was read successfully.\r
139 @retval EFI_UNSUPPORTED The underlying IO device doesn't support the\r
140 provided address offset and read size.\r
141 @retval EFI_INVALID_PARAMETER QueueAddress is NULL\r
142**/\r
143typedef\r
144EFI_STATUS\r
145(EFIAPI *VIRTIO_GET_QUEUE_ADDRESS) (\r
146 IN VIRTIO_DEVICE_PROTOCOL *This,\r
147 OUT UINT32 *QueueAddress\r
148 );\r
149\r
150/**\r
151 Write the queue address field in the Virtio Header.\r
152\r
153 The parameter Address must be the base address of the virtqueue divided\r
154 by 4096.\r
155\r
156 @param[in] This This instance of VIRTIO_DEVICE_PROTOCOL\r
157\r
158 @param[in] Address The 32-bit Queue Address field\r
159\r
160 @retval EFI_SUCCESS The data was written successfully.\r
161 @retval EFI_UNSUPPORTED The underlying IO device doesn't support the\r
162 provided address offset and write size.\r
163**/\r
164typedef\r
165EFI_STATUS\r
166(EFIAPI *VIRTIO_SET_QUEUE_ADDRESS) (\r
167 IN VIRTIO_DEVICE_PROTOCOL *This,\r
168 IN UINT32 Address\r
169 );\r
170\r
171/**\r
172\r
173 Write the queue select field in the Virtio Header.\r
174\r
175 Writing to the queue select field sets the index of the queue to which\r
176 operations such as SetQueueAlign and GetQueueNumMax apply.\r
177\r
178 @param[in] This This instance of VIRTIO_DEVICE_PROTOCOL\r
179\r
180 @param[in] Index The index of the queue to select\r
181\r
182 @retval EFI_SUCCESS The data was written successfully.\r
183 @retval EFI_UNSUPPORTED The underlying IO device doesn't support the\r
184 provided address offset and write size.\r
185**/\r
186typedef\r
187EFI_STATUS\r
188(EFIAPI *VIRTIO_SET_QUEUE_SEL) (\r
189 IN VIRTIO_DEVICE_PROTOCOL *This,\r
190 IN UINT16 Index\r
191 );\r
192\r
193/**\r
194\r
195 Write the queue notify field in the Virtio Header.\r
196\r
197 @param[in] This This instance of VIRTIO_DEVICE_PROTOCOL\r
198\r
199 @param[in] Address The 32-bit Queue Notify field\r
200\r
201 @retval EFI_SUCCESS The data was written successfully.\r
202 @retval EFI_UNSUPPORTED The underlying IO device doesn't support the\r
203 provided address offset and write size.\r
204**/\r
205typedef\r
206EFI_STATUS\r
207(EFIAPI *VIRTIO_SET_QUEUE_NOTIFY) (\r
208 IN VIRTIO_DEVICE_PROTOCOL *This,\r
209 IN UINT16 Index\r
210 );\r
211\r
212/**\r
213 Write the queue alignment field in the Virtio Header.\r
214\r
215 The queue to which the alignment applies is selected by the Queue Select\r
216 field.\r
217\r
218 Note: This operation is not implemented by the VirtIo over PCI. The PCI\r
219 implementation of this protocol returns EFI_SUCCESS.\r
220\r
221 @param[in] This This instance of VIRTIO_DEVICE_PROTOCOL\r
222\r
223 @param[in] Alignment The alignment boundary of the Used Ring in bytes.\r
224 Must be a power of 2.\r
225\r
226 @retval EFI_SUCCESS The data was written successfully.\r
227 @retval EFI_UNSUPPORTED The underlying IO device doesn't support the\r
228 provided address offset and write size.\r
229**/\r
230typedef\r
231EFI_STATUS\r
232(EFIAPI *VIRTIO_SET_QUEUE_ALIGN) (\r
233 IN VIRTIO_DEVICE_PROTOCOL *This,\r
234 IN UINT32 Alignment\r
235 );\r
236\r
237/**\r
238 Write the guest page size.\r
239\r
240 Note: This operation is not implemented by the VirtIo over PCI. The PCI\r
241 implementation of this protocol returns EFI_SUCCESS.\r
242\r
243 @param[in] This This instance of VIRTIO_DEVICE_PROTOCOL\r
244\r
245 @param[in] PageSize Size of the Guest page in bytes.\r
246 Must be a power of 2.\r
247\r
248 @retval EFI_SUCCESS The data was written successfully.\r
249 @retval EFI_UNSUPPORTED The underlying IO device doesn't support the\r
250 provided address offset and write size.\r
251**/\r
252typedef\r
253EFI_STATUS\r
254(EFIAPI *VIRTIO_SET_PAGE_SIZE) (\r
255 IN VIRTIO_DEVICE_PROTOCOL *This,\r
256 IN UINT32 PageSize\r
257 );\r
258\r
259/**\r
260\r
261 Get the size of the virtqueue selected by the queue select field.\r
262\r
263 See Virtio spec Section 2.3\r
264\r
265 @param[in] This This instance of VIRTIO_DEVICE_PROTOCOL\r
266\r
267 @param[out] QueueNumMax The size of the virtqueue in bytes.\r
268 Always a power of 2.\r
269\r
270 @retval EFI_SUCCESS The data was read successfully.\r
271 @retval EFI_UNSUPPORTED The underlying IO device doesn't support the\r
272 provided address offset and read size.\r
273 @retval EFI_INVALID_PARAMETER QueueNumMax is NULL\r
274**/\r
275typedef\r
276EFI_STATUS\r
277(EFIAPI *VIRTIO_GET_QUEUE_NUM_MAX) (\r
278 IN VIRTIO_DEVICE_PROTOCOL *This,\r
279 OUT UINT16 *QueueNumMax\r
280 );\r
281\r
282/**\r
283\r
284 Write to the QueueNum field in the Virtio Header.\r
285\r
286 This function only applies to Virtio-MMIO and may be a stub for other\r
287 implementations. See Virtio Spec appendix X.\r
288\r
289 @param[in] This This instance of VIRTIO_DEVICE_PROTOCOL\r
290\r
291 @param[in] QueueSize The number of elements in the queue.\r
292\r
293 @retval EFI_SUCCESS The data was written successfully.\r
294 @retval EFI_UNSUPPORTED The underlying IO device doesn't support the\r
295 provided address offset and write size.\r
296**/\r
297typedef\r
298EFI_STATUS\r
299(EFIAPI *VIRTIO_SET_QUEUE_NUM) (\r
300 IN VIRTIO_DEVICE_PROTOCOL *This,\r
301 IN UINT16 QueueSize\r
302 );\r
303\r
304/**\r
305\r
306 Get the DeviceStatus field from the Virtio Header.\r
307\r
308 @param[in] This This instance of VIRTIO_DEVICE_PROTOCOL\r
309\r
310 @param[out] DeviceStatus The 8-bit value for the Device status field\r
311\r
312 @retval EFI_SUCCESS The data was read successfully.\r
313 @retval EFI_UNSUPPORTED The underlying IO device doesn't support the\r
314 provided address offset and read size.\r
315 @retval EFI_INVALID_PARAMETER DeviceStatus is NULL\r
316**/\r
317typedef\r
318EFI_STATUS\r
319(EFIAPI *VIRTIO_GET_DEVICE_STATUS) (\r
320 IN VIRTIO_DEVICE_PROTOCOL *This,\r
321 OUT UINT8 *DeviceStatus\r
322 );\r
323\r
324/**\r
325\r
326 Write the DeviceStatus field in the Virtio Header.\r
327\r
328 @param[in] This This instance of VIRTIO_DEVICE_PROTOCOL\r
329\r
330 @param[in] DeviceStatus The 8-bit value for the Device status field\r
331\r
332 @retval EFI_SUCCESS The data was written successfully.\r
333 @retval EFI_UNSUPPORTED The underlying IO device doesn't support the\r
334 provided address offset and write size.\r
335**/\r
336typedef\r
337EFI_STATUS\r
338(EFIAPI *VIRTIO_SET_DEVICE_STATUS) (\r
339 IN VIRTIO_DEVICE_PROTOCOL *This,\r
340 IN UINT8 DeviceStatus\r
341 );\r
342\r
343\r
344///\r
345/// This protocol provides an abstraction over the VirtIo transport layer\r
346///\r
347/// DISCLAIMER: this protocol is a work in progress, and should not be used\r
348/// outside of the EDK II tree.\r
349///\r
350struct _VIRTIO_DEVICE_PROTOCOL {\r
351 /// VirtIo Specification Revision encoded with VIRTIO_SPEC_REVISION()\r
352 UINT32 Revision;\r
353 /// From the Virtio Spec\r
354 INT32 SubSystemDeviceId;\r
355\r
356 VIRTIO_GET_DEVICE_FEATURES GetDeviceFeatures;\r
357 VIRTIO_SET_GUEST_FEATURES SetGuestFeatures;\r
358\r
359 VIRTIO_GET_QUEUE_ADDRESS GetQueueAddress;\r
360 VIRTIO_SET_QUEUE_ADDRESS SetQueueAddress;\r
361\r
362 VIRTIO_SET_QUEUE_SEL SetQueueSel;\r
363\r
364 VIRTIO_SET_QUEUE_NOTIFY SetQueueNotify;\r
365\r
366 VIRTIO_SET_QUEUE_ALIGN SetQueueAlign;\r
367 VIRTIO_SET_PAGE_SIZE SetPageSize;\r
368\r
369 VIRTIO_GET_QUEUE_NUM_MAX GetQueueNumMax;\r
370 VIRTIO_SET_QUEUE_NUM SetQueueNum;\r
371\r
372 VIRTIO_GET_DEVICE_STATUS GetDeviceStatus;\r
373 VIRTIO_SET_DEVICE_STATUS SetDeviceStatus;\r
374\r
375 // Functions to read/write Device Specific headers\r
376 VIRTIO_DEVICE_WRITE WriteDevice;\r
377 VIRTIO_DEVICE_READ ReadDevice;\r
378};\r
379\r
380extern EFI_GUID gVirtioDeviceProtocolGuid;\r
381\r
382#endif\r