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