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