UefiCpuPkg: Move AsmRelocateApLoopStart from Mpfuncs.nasm to AmdSev.nasm

[mirror_edk2.git] / OvmfPkg / Include / Protocol / XenBus.h

/** @file\r
  XenBus protocol to be used between the XenBus bus driver and Xen PV devices.\r
\r
  DISCLAIMER: the XENBUS_PROTOCOL introduced here is a work in progress, and\r
  should not be used outside of the EDK II tree.\r
\r
  This protocol provide the necessary for a Xen PV driver frontend to\r
  communicate with the bus driver, and perform several task to\r
  initialize/shutdown a PV device and perform IO with a PV backend.\r
\r
  Copyright (C) 2014, Citrix Ltd.\r
\r
  SPDX-License-Identifier: BSD-2-Clause-Patent\r
\r
**/\r
\r
#ifndef __PROTOCOL_XENBUS_H__\r
#define __PROTOCOL_XENBUS_H__\r
\r
#define XENBUS_PROTOCOL_GUID \\r
  {0x3d3ca290, 0xb9a5, 0x11e3, {0xb7, 0x5d, 0xb8, 0xac, 0x6f, 0x7d, 0x65, 0xe6}}\r
\r
///\r
/// Forward declaration\r
///\r
typedef struct _XENBUS_PROTOCOL XENBUS_PROTOCOL;\r
\r
typedef enum xenbus_state XenBusState;\r
\r
typedef struct {\r
  UINT32    Id;\r
} XENSTORE_TRANSACTION;\r
\r
#define XST_NIL  ((XENSTORE_TRANSACTION *) NULL)\r
\r
typedef enum {\r
  XENSTORE_STATUS_SUCCESS = 0,\r
  XENSTORE_STATUS_FAIL,\r
  XENSTORE_STATUS_EINVAL,\r
  XENSTORE_STATUS_EACCES,\r
  XENSTORE_STATUS_EEXIST,\r
  XENSTORE_STATUS_EISDIR,\r
  XENSTORE_STATUS_ENOENT,\r
  XENSTORE_STATUS_ENOMEM,\r
  XENSTORE_STATUS_ENOSPC,\r
  XENSTORE_STATUS_EIO,\r
  XENSTORE_STATUS_ENOTEMPTY,\r
  XENSTORE_STATUS_ENOSYS,\r
  XENSTORE_STATUS_EROFS,\r
  XENSTORE_STATUS_EBUSY,\r
  XENSTORE_STATUS_EAGAIN,\r
  XENSTORE_STATUS_EISCONN,\r
  XENSTORE_STATUS_E2BIG\r
} XENSTORE_STATUS;\r
\r
#include <IndustryStandard/Xen/grant_table.h>\r
#include <IndustryStandard/Xen/event_channel.h>\r
\r
///\r
/// Function prototypes\r
///\r
\r
/**\r
  Get the contents of the node Node of the PV device. Returns the contents in\r
  *Result which should be freed after use.\r
\r
  @param This           A pointer to XENBUS_PROTOCOL instance.\r
  @param Transaction    The XenStore transaction covering this request.\r
  @param Node           The basename of the file to read.\r
  @param Result         The returned contents from this file.\r
\r
  @return  On success, XENSTORE_STATUS_SUCCESS. Otherwise an errno value\r
           indicating the type of failure.\r
\r
  @note The results buffer is malloced and should be free'd by the\r
        caller.\r
**/\r
typedef\r
XENSTORE_STATUS\r
(EFIAPI *XENBUS_XS_READ)(\r
  IN  XENBUS_PROTOCOL       *This,\r
  IN  CONST XENSTORE_TRANSACTION *Transaction,\r
  IN  CONST CHAR8           *Node,\r
  OUT VOID                  **Result\r
  );\r
\r
/**\r
  Get the contents of the node Node of the PV device's backend. Returns the\r
  contents in *Result which should be freed after use.\r
\r
  @param This           A pointer to XENBUS_PROTOCOL instance.\r
  @param Transaction    The XenStore transaction covering this request.\r
  @param Node           The basename of the file to read.\r
  @param Result         The returned contents from this file.\r
\r
  @return  On success, XENSTORE_STATUS_SUCCESS. Otherwise an errno value\r
           indicating the type of failure.\r
\r
  @note The results buffer is malloced and should be free'd by the\r
        caller.\r
**/\r
typedef\r
XENSTORE_STATUS\r
(EFIAPI *XENBUS_XS_BACKEND_READ)(\r
  IN  XENBUS_PROTOCOL       *This,\r
  IN  CONST XENSTORE_TRANSACTION *Transaction,\r
  IN  CONST CHAR8           *Node,\r
  OUT VOID                  **Result\r
  );\r
\r
/**\r
  Print formatted write to a XenStore node.\r
\r
  @param This             A pointer to XENBUS_PROTOCOL instance.\r
  @param Transaction      The XenStore transaction covering this request.\r
  @param Directory        The dirname of the path to read.\r
  @param Node             The basename of the path to read.\r
  @param Format           AsciiSPrint format string followed by a variable number\r
                          of arguments.\r
\r
  @return  On success, XENSTORE_STATUS_SUCCESS. Otherwise an errno value\r
           indicating the type of write failure.\r
**/\r
typedef\r
XENSTORE_STATUS\r
(EFIAPI *XENBUS_XS_PRINTF)(\r
  IN XENBUS_PROTOCOL        *This,\r
  IN CONST XENSTORE_TRANSACTION *Transaction,\r
  IN CONST CHAR8            *Directory,\r
  IN CONST CHAR8            *Node,\r
  IN CONST CHAR8            *Format,\r
  ...\r
  );\r
\r
/**\r
  Remove a node or directory (directories must be empty) of the PV driver's\r
  subdirectory.\r
\r
  @param This           A pointer to XENBUS_PROTOCOL instance.\r
  @param Transaction    The XenStore transaction covering this request.\r
  @param Node           The basename of the node to remove.\r
\r
  @return  On success, XENSTORE_STATUS_SUCCESS. Otherwise an errno value\r
           indicating the type of failure.\r
**/\r
typedef\r
XENSTORE_STATUS\r
(EFIAPI *XENBUS_XS_REMOVE)(\r
  IN XENBUS_PROTOCOL        *This,\r
  IN CONST XENSTORE_TRANSACTION *Transaction,\r
  IN CONST CHAR8            *Node\r
  );\r
\r
/**\r
  Start a transaction.\r
\r
  Changes by others will not be seen during the lifetime of this\r
  transaction, and changes will not be visible to others until it\r
  is committed (XsTransactionEnd).\r
\r
  @param This         A pointer to XENBUS_PROTOCOL instance.\r
  @param Transaction  The returned transaction.\r
\r
  @return  On success, XENSTORE_STATUS_SUCCESS. Otherwise an errno value\r
           indicating the type of failure.\r
**/\r
typedef\r
XENSTORE_STATUS\r
(EFIAPI *XENBUS_XS_TRANSACTION_START)(\r
  IN  XENBUS_PROTOCOL       *This,\r
  OUT XENSTORE_TRANSACTION  *Transaction\r
  );\r
\r
/**\r
  End a transaction.\r
\r
  @param This         A pointer to XENBUS_PROTOCOL instance.\r
  @param Transaction  The transaction to end/commit.\r
  @param Abort        If TRUE, the transaction is discarded\r
                      instead of committed.\r
\r
  @return  On success, XENSTORE_STATUS_SUCCESS. Otherwise an errno value\r
           indicating the type of failure.\r
**/\r
typedef\r
XENSTORE_STATUS\r
(EFIAPI *XENBUS_XS_TRANSACTION_END)(\r
  IN XENBUS_PROTOCOL        *This,\r
  IN CONST XENSTORE_TRANSACTION *Transaction,\r
  IN BOOLEAN                Abort\r
  );\r
\r
/**\r
  Set a new state for the frontend of the PV driver.\r
\r
  @param This         A pointer to XENBUS_PROTOCOL instance.\r
  @param Transaction  The transaction to end/commit.\r
  @param State        The new state to apply.\r
\r
  @return  On success, XENSTORE_STATUS_SUCCESS. Otherwise an errno value\r
           indicating the type of failure.\r
**/\r
typedef\r
XENSTORE_STATUS\r
(EFIAPI *XENBUS_SET_STATE)(\r
  IN XENBUS_PROTOCOL        *This,\r
  IN CONST XENSTORE_TRANSACTION *Transaction,\r
  IN XenBusState            State\r
  );\r
\r
/**\r
  Grant access to the page Frame to the domain DomainId.\r
\r
  @param This       A pointer to XENBUS_PROTOCOL instance.\r
  @param DomainId   ID of the domain to grant access to.\r
  @param Frame      Frame Number of the page to grant access to.\r
  @param ReadOnly   Provide read-only or read-write access.\r
  @param RefPtr     Reference number of the grant will be written to this pointer.\r
**/\r
typedef\r
EFI_STATUS\r
(EFIAPI *XENBUS_GRANT_ACCESS)(\r
  IN  XENBUS_PROTOCOL *This,\r
  IN  domid_t         DomainId,\r
  IN  UINTN           Frame,\r
  IN  BOOLEAN         ReadOnly,\r
  OUT grant_ref_t     *refp\r
  );\r
\r
/**\r
  End access to grant Ref, previously return by XenBusGrantAccess.\r
\r
  @param This       A pointer to XENBUS_PROTOCOL instance.\r
  @param Ref        Reference numeber of a grant previously returned by\r
                    XenBusGrantAccess.\r
**/\r
typedef\r
EFI_STATUS\r
(EFIAPI *XENBUS_GRANT_END_ACCESS)(\r
  IN XENBUS_PROTOCOL  *This,\r
  IN grant_ref_t      Ref\r
  );\r
\r
/**\r
  Allocate a port that can be bind from domain DomainId.\r
\r
  @param This       A pointer to the XENBUS_PROTOCOL.\r
  @param DomainId   The domain ID that can bind the newly allocated port.\r
  @param Port       A pointer to a evtchn_port_t that will contain the newly\r
                    allocated port.\r
\r
  @retval UINT32    The return value from the hypercall, 0 if success.\r
**/\r
typedef\r
UINT32\r
(EFIAPI *XENBUS_EVENT_CHANNEL_ALLOCATE)(\r
  IN  XENBUS_PROTOCOL *This,\r
  IN  domid_t         DomainId,\r
  OUT evtchn_port_t   *Port\r
  );\r
\r
/**\r
  Send an event to the remote end of the channel whose local endpoint is Port.\r
\r
  @param This       A pointer to the XENBUS_PROTOCOL.\r
  @param Port       Local port to the event from.\r
\r
  @retval UINT32    The return value from the hypercall, 0 if success.\r
**/\r
typedef\r
UINT32\r
(EFIAPI *XENBUS_EVENT_CHANNEL_NOTIFY)(\r
  IN XENBUS_PROTOCOL  *This,\r
  IN evtchn_port_t    Port\r
  );\r
\r
/**\r
  Close a local event channel Port.\r
\r
  @param This       A pointer to the XENBUS_PROTOCOL.\r
  @param Port       The event channel to close.\r
\r
  @retval UINT32    The return value from the hypercall, 0 if success.\r
**/\r
typedef\r
UINT32\r
(EFIAPI *XENBUS_EVENT_CHANNEL_CLOSE)(\r
  IN XENBUS_PROTOCOL  *This,\r
  IN evtchn_port_t    Port\r
  );\r
\r
/**\r
  Register a XenStore watch.\r
\r
  XenStore watches allow a client to wait for changes to an object in the\r
  XenStore.\r
\r
  @param This       A pointer to the XENBUS_PROTOCOL.\r
  @param Node       The basename of the path to watch.\r
  @param Token      A token.\r
\r
  @return  On success, XENSTORE_STATUS_SUCCESS. Otherwise an errno value\r
           indicating the type of write failure.  EEXIST errors from the\r
           XenStore are suppressed, allowing multiple, physically different,\r
           xenbus_watch objects, to watch the same path in the XenStore.\r
**/\r
typedef\r
XENSTORE_STATUS\r
(EFIAPI *XENBUS_REGISTER_WATCH)(\r
  IN  XENBUS_PROTOCOL *This,\r
  IN  CONST CHAR8     *Node,\r
  OUT VOID            **Token\r
  );\r
\r
/**\r
  Register a XenStore watch on a backend's node.\r
\r
  XenStore watches allow a client to wait for changes to an object in the\r
  XenStore.\r
\r
  @param This       A pointer to the XENBUS_PROTOCOL.\r
  @param Node       The basename of the path to watch.\r
  @param Token      A token.\r
\r
  @return  On success, XENSTORE_STATUS_SUCCESS. Otherwise an errno value\r
           indicating the type of write failure.  EEXIST errors from the\r
           XenStore are suppressed, allowing multiple, physically different,\r
           xenbus_watch objects, to watch the same path in the XenStore.\r
**/\r
typedef\r
XENSTORE_STATUS\r
(EFIAPI *XENBUS_REGISTER_WATCH_BACKEND)(\r
  IN  XENBUS_PROTOCOL *This,\r
  IN  CONST CHAR8     *Node,\r
  OUT VOID            **Token\r
  );\r
\r
/**\r
  Unregister a XenStore watch.\r
\r
  @param This   A pointer to the XENBUS_PROTOCOL.\r
  @param Token  An token previously returned by a successful\r
                call to RegisterWatch ().\r
**/\r
typedef\r
VOID\r
(EFIAPI *XENBUS_UNREGISTER_WATCH)(\r
  IN XENBUS_PROTOCOL  *This,\r
  IN VOID             *Token\r
  );\r
\r
/**\r
  Block until the node watch by Token change.\r
\r
  @param This   A pointer to the XENBUS_PROTOCOL.\r
  @param Token  An token previously returned by a successful\r
                call to RegisterWatch or RegisterWatchBackend.\r
\r
  @return  On success, XENSTORE_STATUS_SUCCESS. Otherwise an errno value\r
           indicating the type of failure.\r
**/\r
typedef\r
XENSTORE_STATUS\r
(EFIAPI *XENBUS_WAIT_FOR_WATCH)(\r
  IN XENBUS_PROTOCOL  *This,\r
  IN VOID             *Token\r
  );\r
\r
///\r
/// Protocol structure\r
///\r
/// DISCLAIMER: the XENBUS_PROTOCOL introduced here is a work in progress, and\r
/// should not be used outside of the EDK II tree.\r
///\r
struct _XENBUS_PROTOCOL {\r
  XENBUS_XS_READ                   XsRead;\r
  XENBUS_XS_BACKEND_READ           XsBackendRead;\r
  XENBUS_XS_PRINTF                 XsPrintf;\r
  XENBUS_XS_REMOVE                 XsRemove;\r
  XENBUS_XS_TRANSACTION_START      XsTransactionStart;\r
  XENBUS_XS_TRANSACTION_END        XsTransactionEnd;\r
  XENBUS_SET_STATE                 SetState;\r
\r
  XENBUS_GRANT_ACCESS              GrantAccess;\r
  XENBUS_GRANT_END_ACCESS          GrantEndAccess;\r
\r
  XENBUS_EVENT_CHANNEL_ALLOCATE    EventChannelAllocate;\r
  XENBUS_EVENT_CHANNEL_NOTIFY      EventChannelNotify;\r
  XENBUS_EVENT_CHANNEL_CLOSE       EventChannelClose;\r
\r
  XENBUS_REGISTER_WATCH            RegisterWatch;\r
  XENBUS_REGISTER_WATCH_BACKEND    RegisterWatchBackend;\r
  XENBUS_UNREGISTER_WATCH          UnregisterWatch;\r
  XENBUS_WAIT_FOR_WATCH            WaitForWatch;\r
  //\r
  // Protocol data fields\r
  //\r
  CONST CHAR8                      *Type;\r
  UINT16                           DeviceId;\r
  CONST CHAR8                      *Node;\r
  CONST CHAR8                      *Backend;\r
};\r
\r
extern EFI_GUID  gXenBusProtocolGuid;\r
\r
#endif\r