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.
 160
 161   @retval EFI_SUCCESS         The data was written successfully.
 162   @retval EFI_UNSUPPORTED     The underlying IO device doesn't support the
 163                               provided address offset and write size.
 164 **/
 165 typedef
 166 EFI_STATUS
 167 (EFIAPI *VIRTIO_SET_QUEUE_ADDRESS) (
 168   IN VIRTIO_DEVICE_PROTOCOL  *This,
 169   IN VRING                   *Ring
 170   );
 171
 172 /**
 173
 174   Write the queue select field in the Virtio Header.
 175
 176   Writing to the queue select field sets the index of the queue to which
 177   operations such as SetQueueAlign and GetQueueNumMax apply.
 178
 179   @param[in] This         This instance of VIRTIO_DEVICE_PROTOCOL
 180
 181   @param[in] Index        The index of the queue to select
 182
 183   @retval EFI_SUCCESS         The data was written successfully.
 184   @retval EFI_UNSUPPORTED     The underlying IO device doesn't support the
 185                               provided address offset and write size.
 186 **/
 187 typedef
 188 EFI_STATUS
 189 (EFIAPI *VIRTIO_SET_QUEUE_SEL) (
 190   IN VIRTIO_DEVICE_PROTOCOL  *This,
 191   IN UINT16                   Index
 192   );
 193
 194 /**
 195
 196   Write the queue notify field in the Virtio Header.
 197
 198   @param[in] This         This instance of VIRTIO_DEVICE_PROTOCOL
 199
 200   @param[in] Address      The 32-bit Queue Notify field
 201
 202   @retval EFI_SUCCESS         The data was written successfully.
 203   @retval EFI_UNSUPPORTED     The underlying IO device doesn't support the
 204                               provided address offset and write size.
 205 **/
 206 typedef
 207 EFI_STATUS
 208 (EFIAPI *VIRTIO_SET_QUEUE_NOTIFY) (
 209   IN VIRTIO_DEVICE_PROTOCOL  *This,
 210   IN UINT16                   Index
 211   );
 212
 213 /**
 214   Write the queue alignment field in the Virtio Header.
 215
 216   The queue to which the alignment applies is selected by the Queue Select
 217   field.
 218
 219   Note: This operation is not implemented by the VirtIo over PCI. The PCI
 220   implementation of this protocol returns EFI_SUCCESS.
 221
 222   @param[in] This         This instance of VIRTIO_DEVICE_PROTOCOL
 223
 224   @param[in] Alignment    The alignment boundary of the Used Ring in bytes.
 225                           Must be a power of 2.
 226
 227   @retval EFI_SUCCESS         The data was written successfully.
 228   @retval EFI_UNSUPPORTED     The underlying IO device doesn't support the
 229                               provided address offset and write size.
 230 **/
 231 typedef
 232 EFI_STATUS
 233 (EFIAPI *VIRTIO_SET_QUEUE_ALIGN) (
 234   IN VIRTIO_DEVICE_PROTOCOL  *This,
 235   IN UINT32                   Alignment
 236   );
 237
 238 /**
 239   Write the guest page size.
 240
 241   Note: This operation is not implemented by the VirtIo over PCI. The PCI
 242   implementation of this protocol returns EFI_SUCCESS.
 243
 244   @param[in] This             This instance of VIRTIO_DEVICE_PROTOCOL
 245
 246   @param[in] PageSize         Size of the Guest page in bytes.
 247                               Must be a power of 2.
 248
 249   @retval EFI_SUCCESS         The data was written successfully.
 250   @retval EFI_UNSUPPORTED     The underlying IO device doesn't support the
 251                               provided address offset and write size.
 252 **/
 253 typedef
 254 EFI_STATUS
 255 (EFIAPI *VIRTIO_SET_PAGE_SIZE) (
 256   IN VIRTIO_DEVICE_PROTOCOL  *This,
 257   IN UINT32                   PageSize
 258   );
 259
 260 /**
 261
 262   Get the size of the virtqueue selected by the queue select field.
 263
 264   See Virtio spec Section 2.3
 265
 266   @param[in] This                 This instance of VIRTIO_DEVICE_PROTOCOL
 267
 268   @param[out] QueueNumMax         The size of the virtqueue in bytes.
 269                                   Always a power of 2.
 270
 271   @retval EFI_SUCCESS             The data was read successfully.
 272   @retval EFI_UNSUPPORTED         The underlying IO device doesn't support the
 273                                   provided address offset and read size.
 274   @retval EFI_INVALID_PARAMETER   QueueNumMax is NULL
 275 **/
 276 typedef
 277 EFI_STATUS
 278 (EFIAPI *VIRTIO_GET_QUEUE_NUM_MAX) (
 279   IN  VIRTIO_DEVICE_PROTOCOL  *This,
 280   OUT UINT16                  *QueueNumMax
 281   );
 282
 283 /**
 284
 285   Write to the QueueNum field in the Virtio Header.
 286
 287   This function only applies to Virtio-MMIO and may be a stub for other
 288   implementations. See Virtio Spec appendix X.
 289
 290   @param[in] This         This instance of VIRTIO_DEVICE_PROTOCOL
 291
 292   @param[in] QueueSize    The number of elements in the queue.
 293
 294   @retval EFI_SUCCESS         The data was written successfully.
 295   @retval EFI_UNSUPPORTED     The underlying IO device doesn't support the
 296                               provided address offset and write size.
 297 **/
 298 typedef
 299 EFI_STATUS
 300 (EFIAPI *VIRTIO_SET_QUEUE_NUM) (
 301   IN VIRTIO_DEVICE_PROTOCOL  *This,
 302   IN UINT16                   QueueSize
 303   );
 304
 305 /**
 306
 307   Get the DeviceStatus field from the Virtio Header.
 308
 309   @param[in] This                 This instance of VIRTIO_DEVICE_PROTOCOL
 310
 311   @param[out] DeviceStatus        The 8-bit value for the Device status field
 312
 313   @retval EFI_SUCCESS             The data was read successfully.
 314   @retval EFI_UNSUPPORTED         The underlying IO device doesn't support the
 315                                   provided address offset and read size.
 316   @retval EFI_INVALID_PARAMETER   DeviceStatus is NULL
 317 **/
 318 typedef
 319 EFI_STATUS
 320 (EFIAPI *VIRTIO_GET_DEVICE_STATUS) (
 321   IN  VIRTIO_DEVICE_PROTOCOL  *This,
 322   OUT UINT8                   *DeviceStatus
 323   );
 324
 325 /**
 326
 327   Write the DeviceStatus field in the Virtio Header.
 328
 329   @param[in] This         This instance of VIRTIO_DEVICE_PROTOCOL
 330
 331   @param[in] DeviceStatus The 8-bit value for the Device status field
 332
 333   @retval EFI_SUCCESS         The data was written successfully.
 334   @retval EFI_UNSUPPORTED     The underlying IO device doesn't support the
 335                               provided address offset and write size.
 336 **/
 337 typedef
 338 EFI_STATUS
 339 (EFIAPI *VIRTIO_SET_DEVICE_STATUS) (
 340   IN VIRTIO_DEVICE_PROTOCOL  *This,
 341   IN UINT8                   DeviceStatus
 342   );
 343
 344 /**
 345
 346   Allocates pages that are suitable for an VirtioOperationBusMasterCommonBuffer
 347   mapping. This means that the buffer allocated by this function supports
 348   simultaneous access by both the processor and the bus master. The device
 349   address that the bus master uses to access the buffer must be retrieved with
 350   a call to VIRTIO_MAP_SHARED.
 351
 352   @param[in]      This              The protocol instance pointer.
 353
 354   @param[in]      Pages             The number of pages to allocate.
 355
 356   @param[in,out]  HostAddress       A pointer to store the system memory base
 357                                     address of the allocated range.
 358
 359   @retval EFI_SUCCESS               The requested memory pages were allocated.
 360   @retval EFI_OUT_OF_RESOURCES      The memory pages could not be allocated.
 361
 362 **/
 363 typedef
 364 EFI_STATUS
 365 (EFIAPI *VIRTIO_ALLOCATE_SHARED)(
 366   IN     VIRTIO_DEVICE_PROTOCOL                   *This,
 367   IN     UINTN                                    Pages,
 368   IN OUT VOID                                     **HostAddress
 369   );
 370
 371 /**
 372   Frees memory that was allocated with VIRTIO_ALLOCATE_SHARED.
 373
 374   @param[in]  This           The protocol instance pointer.
 375
 376   @param[in]  Pages          The number of pages to free.
 377
 378   @param[in]  HostAddress    The system memory base address of the allocated
 379                              range.
 380
 381 **/
 382 typedef
 383 VOID
 384 (EFIAPI *VIRTIO_FREE_SHARED)(
 385   IN  VIRTIO_DEVICE_PROTOCOL                   *This,
 386   IN  UINTN                                    Pages,
 387   IN  VOID                                     *HostAddress
 388   );
 389
 390 /**
 391   Provides the virtio device address required to access system memory from a
 392   DMA bus master.
 393
 394   The interface follows the same usage pattern as defined in UEFI spec 2.6
 395   (Section 13.2 PCI Root Bridge I/O Protocol)
 396
 397   @param[in]     This             The protocol instance pointer.
 398
 399   @param[in]     Operation        Indicates if the bus master is going to
 400                                   read or write to system memory.
 401
 402   @param[in]     HostAddress      The system memory address to map to shared
 403                                   buffer address.
 404
 405   @param[in,out] NumberOfBytes    On input the number of bytes to map.
 406                                   On output the number of bytes that were
 407                                   mapped.
 408
 409   @param[out]    DeviceAddress    The resulting shared map address for the
 410                                   bus master to access the hosts HostAddress.
 411
 412   @param[out]    Mapping          A resulting token to pass to
 413                                   VIRTIO_UNMAP_SHARED.
 414
 415   @retval EFI_SUCCESS             The range was mapped for the returned
 416                                   NumberOfBytes.
 417   @retval EFI_UNSUPPORTED         The HostAddress cannot be mapped as a
 418                                   common buffer.
 419   @retval EFI_INVALID_PARAMETER   One or more parameters are invalid.
 420   @retval EFI_OUT_OF_RESOURCES    The request could not be completed due to
 421                                   a lack of resources.
 422   @retval EFI_DEVICE_ERROR        The system hardware could not map the
 423                                   requested address.
 424 **/
 425
 426 typedef
 427 EFI_STATUS
 428 (EFIAPI *VIRTIO_MAP_SHARED) (
 429   IN     VIRTIO_DEVICE_PROTOCOL       *This,
 430   IN     VIRTIO_MAP_OPERATION         Operation,
 431   IN     VOID                         *HostAddress,
 432   IN OUT UINTN                        *NumberOfBytes,
 433   OUT    EFI_PHYSICAL_ADDRESS         *DeviceAddress,
 434   OUT    VOID                         **Mapping
 435   );
 436
 437 /**
 438   Completes the VIRTIO_MAP_SHARED operation and releases any corresponding
 439   resources.
 440
 441   @param[in]  This               The protocol instance pointer.
 442
 443   @param[in]  Mapping            The mapping token returned from
 444                                  VIRTIO_MAP_SHARED.
 445
 446   @retval EFI_SUCCESS            The range was unmapped.
 447   @retval EFI_INVALID_PARAMETER  Mapping is not a value that was returned by
 448                                  VIRTIO_MAP_SHARED. Passing an invalid Mapping
 449                                  token can cause undefined behavior.
 450   @retval EFI_DEVICE_ERROR       The data was not committed to the target
 451                                  system memory.
 452 **/
 453 typedef
 454 EFI_STATUS
 455 (EFIAPI *VIRTIO_UNMAP_SHARED)(
 456   IN  VIRTIO_DEVICE_PROTOCOL    *This,
 457   IN  VOID                      *Mapping
 458   );
 459
 460 ///
 461 ///  This protocol provides an abstraction over the VirtIo transport layer
 462 ///
 463 ///  DISCLAIMER: this protocol is a work in progress, and should not be used
 464 ///  outside of the EDK II tree.
 465 ///
 466 struct _VIRTIO_DEVICE_PROTOCOL {
 467   //
 468   // VirtIo Specification Revision encoded with VIRTIO_SPEC_REVISION()
 469   //
 470   UINT32                      Revision;
 471   //
 472   // From the Virtio Spec
 473   //
 474   INT32                       SubSystemDeviceId;
 475
 476   VIRTIO_GET_DEVICE_FEATURES  GetDeviceFeatures;
 477   VIRTIO_SET_GUEST_FEATURES   SetGuestFeatures;
 478
 479   VIRTIO_SET_QUEUE_ADDRESS    SetQueueAddress;
 480
 481   VIRTIO_SET_QUEUE_SEL        SetQueueSel;
 482
 483   VIRTIO_SET_QUEUE_NOTIFY     SetQueueNotify;
 484
 485   VIRTIO_SET_QUEUE_ALIGN      SetQueueAlign;
 486   VIRTIO_SET_PAGE_SIZE        SetPageSize;
 487
 488   VIRTIO_GET_QUEUE_NUM_MAX    GetQueueNumMax;
 489   VIRTIO_SET_QUEUE_NUM        SetQueueNum;
 490
 491   VIRTIO_GET_DEVICE_STATUS    GetDeviceStatus;
 492   VIRTIO_SET_DEVICE_STATUS    SetDeviceStatus;
 493
 494   //
 495   // Functions to read/write Device Specific headers
 496   //
 497   VIRTIO_DEVICE_WRITE         WriteDevice;
 498   VIRTIO_DEVICE_READ          ReadDevice;
 499
 500   //
 501   // Functions to allocate, free, map and unmap shared buffer
 502   //
 503   VIRTIO_ALLOCATE_SHARED      AllocateSharedPages;
 504   VIRTIO_FREE_SHARED          FreeSharedPages;
 505   VIRTIO_MAP_SHARED           MapSharedBuffer;
 506   VIRTIO_UNMAP_SHARED         UnmapSharedBuffer;
 507 };
 508
 509 extern EFI_GUID gVirtioDeviceProtocolGuid;
 510
 511 #endif