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