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