source: vbox/trunk/src/VBox/Devices/EFI/Firmware/OvmfPkg/Include/Protocol/VirtioDevice.h

/** @file
  Virtio Device

  DISCLAIMER: the VIRTIO_DEVICE_PROTOCOL introduced here is a work in progress,
  and should not be used outside of the EDK II tree.

  Copyright (c) 2013, ARM Ltd. All rights reserved.<BR>
  Copyright (c) 2017, AMD Inc, All rights reserved.<BR>

  SPDX-License-Identifier: BSD-2-Clause-Patent

**/

#ifndef __VIRTIO_DEVICE_H__
#define __VIRTIO_DEVICE_H__

#include <IndustryStandard/Virtio.h>

//
// VirtIo Specification Revision: Major[31:24].Minor[23:16].Revision[15:0]
//
#define VIRTIO_SPEC_REVISION(major, minor, revision) \
  ((((major) & 0xFF) << 24) | (((minor) & 0xFF) << 16) | ((revision) & 0xFFFF))

#define VIRTIO_DEVICE_PROTOCOL_GUID  {\
  0xfa920010, 0x6785, 0x4941, {0xb6, 0xec, 0x49, 0x8c, 0x57, 0x9f, 0x16, 0x0a }\
  }

typedef struct _VIRTIO_DEVICE_PROTOCOL VIRTIO_DEVICE_PROTOCOL;

//
// VIRTIO Operation for VIRTIO_MAP_SHARED
//
typedef enum {
  //
  // A read operation from system memory by a bus master
  //
  VirtioOperationBusMasterRead,
  //
  // A write operation to system memory by a bus master
  //
  VirtioOperationBusMasterWrite,
  //
  // Provides both read and write access to system memory by both the
  // processor and a bus master
  //
  VirtioOperationBusMasterCommonBuffer,
} VIRTIO_MAP_OPERATION;

/**

  Read a word from the device-specific I/O region of the Virtio Header.

  @param[in] This         This instance of VIRTIO_DEVICE_PROTOCOL

  @param[in] FieldOffset  Source offset.

  @param[in] FieldSize    Source field size in bytes, must be in {1, 2, 4, 8}.

  @param[in] BufferSize   Number of bytes available in the target buffer. Must
                          equal FieldSize.

  @param[out] Buffer      Target buffer.

  @retval EFI_SUCCESS           The data was read successfully.
  @retval EFI_UNSUPPORTED       The underlying IO device doesn't support the
                                provided address offset and read size.
  @retval EFI_OUT_OF_RESOURCES  The request could not be completed due to a
                                lack of resources.
  @retval EFI_INVALID_PARAMETER One or more parameters are invalid.

**/
typedef
EFI_STATUS
(EFIAPI *VIRTIO_DEVICE_READ)(
  IN  VIRTIO_DEVICE_PROTOCOL *This,
  IN  UINTN                  FieldOffset,
  IN  UINTN                  FieldSize,
  IN  UINTN                  BufferSize,
  OUT VOID                   *Buffer
  );

/**

  Write a word to the device-specific I/O region of the Virtio Header.

  @param[in] This         This instance of VIRTIO_DEVICE_PROTOCOL

  @param[in] FieldOffset  Destination offset.

  @param[in] FieldSize    Destination field size in bytes,
                          must be in {1, 2, 4, 8}.

  @param[out] Value       Value to write.

  @retval EFI_SUCCESS           The data was written successfully.
  @retval EFI_UNSUPPORTED       The underlying IO device doesn't support the
                                provided address offset and write size.
  @retval EFI_OUT_OF_RESOURCES  The request could not be completed due to a
                                lack of resources.
  @retval EFI_INVALID_PARAMETER One or more parameters are invalid.

**/
typedef
EFI_STATUS
(EFIAPI *VIRTIO_DEVICE_WRITE)(
  IN VIRTIO_DEVICE_PROTOCOL *This,
  IN UINTN                  FieldOffset,
  IN UINTN                  FieldSize,
  IN UINT64                 Value
  );

/**
  Read the device features field from the Virtio Header.

  @param[in] This                 This instance of VIRTIO_DEVICE_PROTOCOL

  @param[out] DeviceFeatures      The device features field.

  @retval EFI_SUCCESS             The data was read successfully.
  @retval EFI_UNSUPPORTED         The underlying IO device doesn't support the
                                  provided address offset and read size.
  @retval EFI_INVALID_PARAMETER   DeviceFeatures is NULL
**/
typedef
EFI_STATUS
(EFIAPI *VIRTIO_GET_DEVICE_FEATURES)(
  IN VIRTIO_DEVICE_PROTOCOL *This,
  OUT UINT64                *DeviceFeatures
  );

/**
  Write the guest features field in the Virtio Header.

  @param[in] This         This instance of VIRTIO_DEVICE_PROTOCOL

  @param[in] Features     The guest features field

**/
typedef
EFI_STATUS
(EFIAPI *VIRTIO_SET_GUEST_FEATURES)(
  IN VIRTIO_DEVICE_PROTOCOL  *This,
  IN UINT64                   Features
  );

/**
  Write the queue address field(s) in the Virtio Header.

  @param[in] This             This instance of VIRTIO_DEVICE_PROTOCOL

  @param[in] Ring             The initialized VRING object to take the
                              addresses from. The caller is responsible for
                              ensuring that on input, all Ring->NumPages pages,
                              starting at Ring->Base, have been successfully
                              mapped with a single call to
                              This->MapSharedBuffer() for CommonBuffer bus
                              master operation.

  @param[in] RingBaseShift    Adding this value using UINT64 arithmetic to the
                              addresses found in Ring translates them from
                              system memory to bus addresses. The caller shall
                              calculate RingBaseShift as
                              (DeviceAddress - (UINT64)(UINTN)HostAddress),
                              where DeviceAddress and HostAddress (i.e.,
                              Ring->Base) were output and input parameters of
                              This->MapSharedBuffer(), respectively.

  @retval EFI_SUCCESS         The data was written successfully.
  @retval EFI_UNSUPPORTED     The underlying IO device doesn't support the
                              provided address offset and write size.
**/
typedef
EFI_STATUS
(EFIAPI *VIRTIO_SET_QUEUE_ADDRESS)(
  IN VIRTIO_DEVICE_PROTOCOL  *This,
  IN VRING                   *Ring,
  IN UINT64                  RingBaseShift
  );

/**

  Write the queue select field in the Virtio Header.

  Writing to the queue select field sets the index of the queue to which
  operations such as SetQueueAlign and GetQueueNumMax apply.

  @param[in] This         This instance of VIRTIO_DEVICE_PROTOCOL

  @param[in] Index        The index of the queue to select

  @retval EFI_SUCCESS         The data was written successfully.
  @retval EFI_UNSUPPORTED     The underlying IO device doesn't support the
                              provided address offset and write size.
**/
typedef
EFI_STATUS
(EFIAPI *VIRTIO_SET_QUEUE_SEL)(
  IN VIRTIO_DEVICE_PROTOCOL  *This,
  IN UINT16                   Index
  );

/**

  Write the queue notify field in the Virtio Header.

  @param[in] This         This instance of VIRTIO_DEVICE_PROTOCOL

  @param[in] Address      The 32-bit Queue Notify field

  @retval EFI_SUCCESS         The data was written successfully.
  @retval EFI_UNSUPPORTED     The underlying IO device doesn't support the
                              provided address offset and write size.
**/
typedef
EFI_STATUS
(EFIAPI *VIRTIO_SET_QUEUE_NOTIFY)(
  IN VIRTIO_DEVICE_PROTOCOL  *This,
  IN UINT16                   Index
  );

/**
  Write the queue alignment field in the Virtio Header.

  The queue to which the alignment applies is selected by the Queue Select
  field.

  Note: This operation is not implemented by the VirtIo over PCI. The PCI
  implementation of this protocol returns EFI_SUCCESS.

  @param[in] This         This instance of VIRTIO_DEVICE_PROTOCOL

  @param[in] Alignment    The alignment boundary of the Used Ring in bytes.
                          Must be a power of 2.

  @retval EFI_SUCCESS         The data was written successfully.
  @retval EFI_UNSUPPORTED     The underlying IO device doesn't support the
                              provided address offset and write size.
**/
typedef
EFI_STATUS
(EFIAPI *VIRTIO_SET_QUEUE_ALIGN)(
  IN VIRTIO_DEVICE_PROTOCOL  *This,
  IN UINT32                   Alignment
  );

/**
  Write the guest page size.

  Note: This operation is not implemented by the VirtIo over PCI. The PCI
  implementation of this protocol returns EFI_SUCCESS.

  @param[in] This             This instance of VIRTIO_DEVICE_PROTOCOL

  @param[in] PageSize         Size of the Guest page in bytes.
                              Must be a power of 2.

  @retval EFI_SUCCESS         The data was written successfully.
  @retval EFI_UNSUPPORTED     The underlying IO device doesn't support the
                              provided address offset and write size.
**/
typedef
EFI_STATUS
(EFIAPI *VIRTIO_SET_PAGE_SIZE)(
  IN VIRTIO_DEVICE_PROTOCOL  *This,
  IN UINT32                   PageSize
  );

/**

  Get the size of the virtqueue selected by the queue select field.

  See Virtio spec Section 2.3

  @param[in] This                 This instance of VIRTIO_DEVICE_PROTOCOL

  @param[out] QueueNumMax         The size of the virtqueue in bytes.
                                  Always a power of 2.

  @retval EFI_SUCCESS             The data was read successfully.
  @retval EFI_UNSUPPORTED         The underlying IO device doesn't support the
                                  provided address offset and read size.
  @retval EFI_INVALID_PARAMETER   QueueNumMax is NULL
**/
typedef
EFI_STATUS
(EFIAPI *VIRTIO_GET_QUEUE_NUM_MAX)(
  IN  VIRTIO_DEVICE_PROTOCOL  *This,
  OUT UINT16                  *QueueNumMax
  );

/**

  Write to the QueueNum field in the Virtio Header.

  This function only applies to Virtio-MMIO and may be a stub for other
  implementations. See Virtio Spec appendix X.

  @param[in] This         This instance of VIRTIO_DEVICE_PROTOCOL

  @param[in] QueueSize    The number of elements in the queue.

  @retval EFI_SUCCESS         The data was written successfully.
  @retval EFI_UNSUPPORTED     The underlying IO device doesn't support the
                              provided address offset and write size.
**/
typedef
EFI_STATUS
(EFIAPI *VIRTIO_SET_QUEUE_NUM)(
  IN VIRTIO_DEVICE_PROTOCOL  *This,
  IN UINT16                   QueueSize
  );

/**

  Get the DeviceStatus field from the Virtio Header.

  @param[in] This                 This instance of VIRTIO_DEVICE_PROTOCOL

  @param[out] DeviceStatus        The 8-bit value for the Device status field

  @retval EFI_SUCCESS             The data was read successfully.
  @retval EFI_UNSUPPORTED         The underlying IO device doesn't support the
                                  provided address offset and read size.
  @retval EFI_INVALID_PARAMETER   DeviceStatus is NULL
**/
typedef
EFI_STATUS
(EFIAPI *VIRTIO_GET_DEVICE_STATUS)(
  IN  VIRTIO_DEVICE_PROTOCOL  *This,
  OUT UINT8                   *DeviceStatus
  );

/**

  Write the DeviceStatus field in the Virtio Header.

  @param[in] This         This instance of VIRTIO_DEVICE_PROTOCOL

  @param[in] DeviceStatus The 8-bit value for the Device status field

  @retval EFI_SUCCESS         The data was written successfully.
  @retval EFI_UNSUPPORTED     The underlying IO device doesn't support the
                              provided address offset and write size.
**/
typedef
EFI_STATUS
(EFIAPI *VIRTIO_SET_DEVICE_STATUS)(
  IN VIRTIO_DEVICE_PROTOCOL  *This,
  IN UINT8                   DeviceStatus
  );

/**

  Allocates pages that are suitable for an VirtioOperationBusMasterCommonBuffer
  mapping. This means that the buffer allocated by this function supports
  simultaneous access by both the processor and the bus master. The device
  address that the bus master uses to access the buffer must be retrieved with
  a call to VIRTIO_MAP_SHARED.

  @param[in]      This              The protocol instance pointer.

  @param[in]      Pages             The number of pages to allocate.

  @param[in,out]  HostAddress       A pointer to store the system memory base
                                    address of the allocated range.

  @retval EFI_SUCCESS               The requested memory pages were allocated.
  @retval EFI_OUT_OF_RESOURCES      The memory pages could not be allocated.

**/
typedef
EFI_STATUS
(EFIAPI *VIRTIO_ALLOCATE_SHARED)(
  IN     VIRTIO_DEVICE_PROTOCOL                   *This,
  IN     UINTN                                    Pages,
  IN OUT VOID                                     **HostAddress
  );

/**
  Frees memory that was allocated with VIRTIO_ALLOCATE_SHARED.

  @param[in]  This           The protocol instance pointer.

  @param[in]  Pages          The number of pages to free.

  @param[in]  HostAddress    The system memory base address of the allocated
                             range.

**/
typedef
VOID
(EFIAPI *VIRTIO_FREE_SHARED)(
  IN  VIRTIO_DEVICE_PROTOCOL                   *This,
  IN  UINTN                                    Pages,
  IN  VOID                                     *HostAddress
  );

/**
  Provides the virtio device address required to access system memory from a
  DMA bus master.

  The interface follows the same usage pattern as defined in UEFI spec 2.6
  (Section 13.2 PCI Root Bridge I/O Protocol)

  @param[in]     This             The protocol instance pointer.

  @param[in]     Operation        Indicates if the bus master is going to
                                  read or write to system memory.

  @param[in]     HostAddress      The system memory address to map to shared
                                  buffer address.

  @param[in,out] NumberOfBytes    On input the number of bytes to map.
                                  On output the number of bytes that were
                                  mapped.

  @param[out]    DeviceAddress    The resulting shared map address for the
                                  bus master to access the hosts HostAddress.

  @param[out]    Mapping          A resulting token to pass to
                                  VIRTIO_UNMAP_SHARED.

  @retval EFI_SUCCESS             The range was mapped for the returned
                                  NumberOfBytes.
  @retval EFI_UNSUPPORTED         The HostAddress cannot be mapped as a
                                  common buffer.
  @retval EFI_INVALID_PARAMETER   One or more parameters are invalid.
  @retval EFI_OUT_OF_RESOURCES    The request could not be completed due to
                                  a lack of resources.
  @retval EFI_DEVICE_ERROR        The system hardware could not map the
                                  requested address.
**/

typedef
EFI_STATUS
(EFIAPI *VIRTIO_MAP_SHARED)(
  IN     VIRTIO_DEVICE_PROTOCOL       *This,
  IN     VIRTIO_MAP_OPERATION         Operation,
  IN     VOID                         *HostAddress,
  IN OUT UINTN                        *NumberOfBytes,
  OUT    EFI_PHYSICAL_ADDRESS         *DeviceAddress,
  OUT    VOID                         **Mapping
  );

/**
  Completes the VIRTIO_MAP_SHARED operation and releases any corresponding
  resources.

  @param[in]  This               The protocol instance pointer.

  @param[in]  Mapping            The mapping token returned from
                                 VIRTIO_MAP_SHARED.

  @retval EFI_SUCCESS            The range was unmapped.
  @retval EFI_INVALID_PARAMETER  Mapping is not a value that was returned by
                                 VIRTIO_MAP_SHARED. Passing an invalid Mapping
                                 token can cause undefined behavior.
  @retval EFI_DEVICE_ERROR       The data was not committed to the target
                                 system memory.
**/
typedef
EFI_STATUS
(EFIAPI *VIRTIO_UNMAP_SHARED)(
  IN  VIRTIO_DEVICE_PROTOCOL    *This,
  IN  VOID                      *Mapping
  );

///
///  This protocol provides an abstraction over the VirtIo transport layer
///
///  DISCLAIMER: this protocol is a work in progress, and should not be used
///  outside of the EDK II tree.
///
struct _VIRTIO_DEVICE_PROTOCOL {
  //
  // VirtIo Specification Revision encoded with VIRTIO_SPEC_REVISION()
  //
  UINT32                        Revision;
  //
  // From the Virtio Spec
  //
  INT32                         SubSystemDeviceId;

  VIRTIO_GET_DEVICE_FEATURES    GetDeviceFeatures;
  VIRTIO_SET_GUEST_FEATURES     SetGuestFeatures;

  VIRTIO_SET_QUEUE_ADDRESS      SetQueueAddress;

  VIRTIO_SET_QUEUE_SEL          SetQueueSel;

  VIRTIO_SET_QUEUE_NOTIFY       SetQueueNotify;

  VIRTIO_SET_QUEUE_ALIGN        SetQueueAlign;
  VIRTIO_SET_PAGE_SIZE          SetPageSize;

  VIRTIO_GET_QUEUE_NUM_MAX      GetQueueNumMax;
  VIRTIO_SET_QUEUE_NUM          SetQueueNum;

  VIRTIO_GET_DEVICE_STATUS      GetDeviceStatus;
  VIRTIO_SET_DEVICE_STATUS      SetDeviceStatus;

  //
  // Functions to read/write Device Specific headers
  //
  VIRTIO_DEVICE_WRITE           WriteDevice;
  VIRTIO_DEVICE_READ            ReadDevice;

  //
  // Functions to allocate, free, map and unmap shared buffer
  //
  VIRTIO_ALLOCATE_SHARED        AllocateSharedPages;
  VIRTIO_FREE_SHARED            FreeSharedPages;
  VIRTIO_MAP_SHARED             MapSharedBuffer;
  VIRTIO_UNMAP_SHARED           UnmapSharedBuffer;
};

extern EFI_GUID  gVirtioDeviceProtocolGuid;

#endif