summaryrefslogtreecommitdiff
path: root/OvmfPkg/Include/Protocol/VirtioDevice.h
blob: 48fca2e14c256e1c29ba193f24c13dc26e38a7c2 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
/** @file
  Virtio Device

  DISCLAIMER: the VIRTIO_DEVICE_PROTOCOL introduced here is a work in progress,
  and should not be used outside of the EDK II tree.

  Copyright (c) 2013, ARM Ltd. All rights reserved.<BR>

  This program and the accompanying materials are licensed and made available
  under the terms and conditions of the BSD License which accompanies this
  distribution. The full text of the license may be found at
  http://opensource.org/licenses/bsd-license.php

  THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, WITHOUT
  WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.

**/

#ifndef __VIRTIO_DEVICE_H__
#define __VIRTIO_DEVICE_H__

// VirtIo Specification Revision: Major[31:24].Minor[23:16].Revision[15:0
#define VIRTIO_SPEC_REVISION(major,minor,revision) \
  ((((major) & 0xFF) << 24) | (((minor) & 0xFF) << 16) | ((revision) & 0xFFFF))

#define VIRTIO_DEVICE_PROTOCOL_GUID { \
  0xfa920010, 0x6785, 0x4941, {0xb6, 0xec, 0x49, 0x8c, 0x57, 0x9f, 0x16, 0x0a }\
  }

typedef struct _VIRTIO_DEVICE_PROTOCOL  VIRTIO_DEVICE_PROTOCOL;

/**

  Read a word from the device-specific I/O region of the Virtio Header.

  @param[in] This         This instance of VIRTIO_DEVICE_PROTOCOL

  @param[in] FieldOffset  Source offset.

  @param[in] FieldSize    Source field size in bytes, must be in {1, 2, 4, 8}.

  @param[in] BufferSize   Number of bytes available in the target buffer. Must
                          equal FieldSize.

  @param[out] Buffer      Target buffer.

  @retval EFI_SUCCESS           The data was read successfully.
  @retval EFI_UNSUPPORTED       The underlying IO device doesn't support the
                                provided address offset and read size.
  @retval EFI_OUT_OF_RESOURCES  The request could not be completed due to a
                                lack of resources.
  @retval EFI_INVALID_PARAMETER One or more parameters are invalid.

**/
typedef
EFI_STATUS
(EFIAPI *VIRTIO_DEVICE_READ) (
  IN  VIRTIO_DEVICE_PROTOCOL *This,
  IN  UINTN                  FieldOffset,
  IN  UINTN                  FieldSize,
  IN  UINTN                  BufferSize,
  OUT VOID                   *Buffer
  );

/**

  Write a word to the device-specific I/O region of the Virtio Header.

  @param[in] This         This instance of VIRTIO_DEVICE_PROTOCOL

  @param[in] FieldOffset  Destination offset.

  @param[in] FieldSize    Destination field size in bytes,
                          must be in {1, 2, 4, 8}.

  @param[out] Value       Value to write.

  @retval EFI_SUCCESS           The data was written successfully.
  @retval EFI_UNSUPPORTED       The underlying IO device doesn't support the
                                provided address offset and write size.
  @retval EFI_OUT_OF_RESOURCES  The request could not be completed due to a
                                lack of resources.
  @retval EFI_INVALID_PARAMETER One or more parameters are invalid.

**/
typedef
EFI_STATUS
(EFIAPI *VIRTIO_DEVICE_WRITE) (
  IN VIRTIO_DEVICE_PROTOCOL *This,
  IN UINTN                  FieldOffset,
  IN UINTN                  FieldSize,
  IN UINT64                 Value
  );

/**
  Read the device features field from the Virtio Header.

  @param[in] This                 This instance of VIRTIO_DEVICE_PROTOCOL

  @param[out] DeviceFeatures      The 32-bit device features field.

  @retval EFI_SUCCESS             The data was read successfully.
  @retval EFI_UNSUPPORTED         The underlying IO device doesn't support the
                                  provided address offset and read size.
  @retval EFI_INVALID_PARAMETER   DeviceFeatures is NULL
**/
typedef
EFI_STATUS
(EFIAPI *VIRTIO_GET_DEVICE_FEATURES) (
  IN VIRTIO_DEVICE_PROTOCOL *This,
  OUT UINT32                *DeviceFeatures
  );

/**
  Write the guest features field in the Virtio Header.

  @param[in] This         This instance of VIRTIO_DEVICE_PROTOCOL

  @param[in] Features     The 32-bit guest guest features field

**/
typedef
EFI_STATUS
(EFIAPI *VIRTIO_SET_GUEST_FEATURES) (
  IN VIRTIO_DEVICE_PROTOCOL  *This,
  IN UINT32                   Features
  );

/**
  Read the queue address field from the Virtio Header.

  QueueAddress is the address of the virtqueue divided by 4096.

  @param[in] This                 This instance of VIRTIO_DEVICE_PROTOCOL

  @param[out] QueueAddress        The 32-bit queue address field.

  @retval EFI_SUCCESS             The data was read successfully.
  @retval EFI_UNSUPPORTED         The underlying IO device doesn't support the
                                  provided address offset and read size.
  @retval EFI_INVALID_PARAMETER   QueueAddress is NULL
**/
typedef
EFI_STATUS
(EFIAPI *VIRTIO_GET_QUEUE_ADDRESS) (
  IN  VIRTIO_DEVICE_PROTOCOL *This,
  OUT UINT32                 *QueueAddress
  );

/**
  Write the queue address field in the Virtio Header.

  The parameter Address must be the base address of the virtqueue divided
  by 4096.

  @param[in] This             This instance of VIRTIO_DEVICE_PROTOCOL

  @param[in] Address          The 32-bit Queue Address field

  @retval EFI_SUCCESS         The data was written successfully.
  @retval EFI_UNSUPPORTED     The underlying IO device doesn't support the
                              provided address offset and write size.
**/
typedef
EFI_STATUS
(EFIAPI *VIRTIO_SET_QUEUE_ADDRESS) (
  IN VIRTIO_DEVICE_PROTOCOL  *This,
  IN UINT32                   Address
  );

/**

  Write the queue select field in the Virtio Header.

  Writing to the queue select field sets the index of the queue to which
  operations such as SetQueueAlign and GetQueueNumMax apply.

  @param[in] This         This instance of VIRTIO_DEVICE_PROTOCOL

  @param[in] Index        The index of the queue to select

  @retval EFI_SUCCESS         The data was written successfully.
  @retval EFI_UNSUPPORTED     The underlying IO device doesn't support the
                              provided address offset and write size.
**/
typedef
EFI_STATUS
(EFIAPI *VIRTIO_SET_QUEUE_SEL) (
  IN VIRTIO_DEVICE_PROTOCOL  *This,
  IN UINT16                   Index
  );

/**

  Write the queue notify field in the Virtio Header.

  @param[in] This         This instance of VIRTIO_DEVICE_PROTOCOL

  @param[in] Address      The 32-bit Queue Notify field

  @retval EFI_SUCCESS         The data was written successfully.
  @retval EFI_UNSUPPORTED     The underlying IO device doesn't support the
                              provided address offset and write size.
**/
typedef
EFI_STATUS
(EFIAPI *VIRTIO_SET_QUEUE_NOTIFY) (
  IN VIRTIO_DEVICE_PROTOCOL  *This,
  IN UINT16                   Index
  );

/**
  Write the queue alignment field in the Virtio Header.

  The queue to which the alignment applies is selected by the Queue Select
  field.

  Note: This operation is not implemented by the VirtIo over PCI. The PCI
  implementation of this protocol returns EFI_SUCCESS.

  @param[in] This         This instance of VIRTIO_DEVICE_PROTOCOL

  @param[in] Alignment    The alignment boundary of the Used Ring in bytes.
                          Must be a power of 2.

  @retval EFI_SUCCESS         The data was written successfully.
  @retval EFI_UNSUPPORTED     The underlying IO device doesn't support the
                              provided address offset and write size.
**/
typedef
EFI_STATUS
(EFIAPI *VIRTIO_SET_QUEUE_ALIGN) (
  IN VIRTIO_DEVICE_PROTOCOL  *This,
  IN UINT32                   Alignment
  );

/**
  Write the guest page size.

  Note: This operation is not implemented by the VirtIo over PCI. The PCI
  implementation of this protocol returns EFI_SUCCESS.

  @param[in] This             This instance of VIRTIO_DEVICE_PROTOCOL

  @param[in] PageSize         Size of the Guest page in bytes.
                              Must be a power of 2.

  @retval EFI_SUCCESS         The data was written successfully.
  @retval EFI_UNSUPPORTED     The underlying IO device doesn't support the
                              provided address offset and write size.
**/
typedef
EFI_STATUS
(EFIAPI *VIRTIO_SET_PAGE_SIZE) (
  IN VIRTIO_DEVICE_PROTOCOL  *This,
  IN UINT32                   PageSize
  );

/**

  Get the size of the virtqueue selected by the queue select field.

  See Virtio spec Section 2.3

  @param[in] This                 This instance of VIRTIO_DEVICE_PROTOCOL

  @param[out] QueueNumMax         The size of the virtqueue in bytes.
                                  Always a power of 2.

  @retval EFI_SUCCESS             The data was read successfully.
  @retval EFI_UNSUPPORTED         The underlying IO device doesn't support the
                                  provided address offset and read size.
  @retval EFI_INVALID_PARAMETER   QueueNumMax is NULL
**/
typedef
EFI_STATUS
(EFIAPI *VIRTIO_GET_QUEUE_NUM_MAX) (
  IN  VIRTIO_DEVICE_PROTOCOL  *This,
  OUT UINT16                  *QueueNumMax
  );

/**

  Write to the QueueNum field in the Virtio Header.

  This function only applies to Virtio-MMIO and may be a stub for other
  implementations. See Virtio Spec appendix X.

  @param[in] This         This instance of VIRTIO_DEVICE_PROTOCOL

  @param[in] QueueSize    The number of elements in the queue.

  @retval EFI_SUCCESS         The data was written successfully.
  @retval EFI_UNSUPPORTED     The underlying IO device doesn't support the
                              provided address offset and write size.
**/
typedef
EFI_STATUS
(EFIAPI *VIRTIO_SET_QUEUE_NUM) (
  IN VIRTIO_DEVICE_PROTOCOL  *This,
  IN UINT16                   QueueSize
  );

/**

  Get the DeviceStatus field from the Virtio Header.

  @param[in] This                 This instance of VIRTIO_DEVICE_PROTOCOL

  @param[out] DeviceStatus        The 8-bit value for the Device status field

  @retval EFI_SUCCESS             The data was read successfully.
  @retval EFI_UNSUPPORTED         The underlying IO device doesn't support the
                                  provided address offset and read size.
  @retval EFI_INVALID_PARAMETER   DeviceStatus is NULL
**/
typedef
EFI_STATUS
(EFIAPI *VIRTIO_GET_DEVICE_STATUS) (
  IN  VIRTIO_DEVICE_PROTOCOL  *This,
  OUT UINT8                   *DeviceStatus
  );

/**

  Write the DeviceStatus field in the Virtio Header.

  @param[in] This         This instance of VIRTIO_DEVICE_PROTOCOL

  @param[in] DeviceStatus The 8-bit value for the Device status field

  @retval EFI_SUCCESS         The data was written successfully.
  @retval EFI_UNSUPPORTED     The underlying IO device doesn't support the
                              provided address offset and write size.
**/
typedef
EFI_STATUS
(EFIAPI *VIRTIO_SET_DEVICE_STATUS) (
  IN VIRTIO_DEVICE_PROTOCOL  *This,
  IN UINT8                   DeviceStatus
  );


///
///  This protocol provides an abstraction over the VirtIo transport layer
///
///  DISCLAIMER: this protocol is a work in progress, and should not be used
///  outside of the EDK II tree.
///
struct _VIRTIO_DEVICE_PROTOCOL {
  /// VirtIo Specification Revision encoded with VIRTIO_SPEC_REVISION()
  UINT32                      Revision;
  /// From the Virtio Spec
  INT32                       SubSystemDeviceId;

  VIRTIO_GET_DEVICE_FEATURES  GetDeviceFeatures;
  VIRTIO_SET_GUEST_FEATURES   SetGuestFeatures;

  VIRTIO_GET_QUEUE_ADDRESS    GetQueueAddress;
  VIRTIO_SET_QUEUE_ADDRESS    SetQueueAddress;

  VIRTIO_SET_QUEUE_SEL        SetQueueSel;

  VIRTIO_SET_QUEUE_NOTIFY     SetQueueNotify;

  VIRTIO_SET_QUEUE_ALIGN      SetQueueAlign;
  VIRTIO_SET_PAGE_SIZE        SetPageSize;

  VIRTIO_GET_QUEUE_NUM_MAX    GetQueueNumMax;
  VIRTIO_SET_QUEUE_NUM        SetQueueNum;

  VIRTIO_GET_DEVICE_STATUS    GetDeviceStatus;
  VIRTIO_SET_DEVICE_STATUS    SetDeviceStatus;

  // Functions to read/write Device Specific headers
  VIRTIO_DEVICE_WRITE         WriteDevice;
  VIRTIO_DEVICE_READ          ReadDevice;
};

extern EFI_GUID gVirtioDeviceProtocolGuid;

#endif