OvmfPkg/Include/Protocol/XenBus.h

   1
   2 /** @file
   3   XenBus protocol to be used between the XenBus bus driver and Xen PV devices.
   4
   5   DISCLAIMER: the XENBUS_PROTOCOL introduced here is a work in progress, and
   6   should not be used outside of the EDK II tree.
   7
   8   This protocol provide the necessary for a Xen PV driver frontend to
   9   communicate with the bus driver, and perform several task to
  10   initialize/shutdown a PV device and perform IO with a PV backend.
  11
  12   Copyright (C) 2014, Citrix Ltd.
  13
  14   SPDX-License-Identifier: BSD-2-Clause-Patent
  15
  16 **/
  17
  18 #ifndef __PROTOCOL_XENBUS_H__
  19 #define __PROTOCOL_XENBUS_H__
  20
  21 #define XENBUS_PROTOCOL_GUID \
  22   {0x3d3ca290, 0xb9a5, 0x11e3, {0xb7, 0x5d, 0xb8, 0xac, 0x6f, 0x7d, 0x65, 0xe6}}
  23
  24 ///
  25 /// Forward declaration
  26 ///
  27 typedef struct _XENBUS_PROTOCOL XENBUS_PROTOCOL;
  28
  29 typedef enum xenbus_state XenBusState;
  30
  31 typedef struct
  32 {
  33   UINT32 Id;
  34 } XENSTORE_TRANSACTION;
  35
  36 #define XST_NIL ((XENSTORE_TRANSACTION *) NULL)
  37
  38 typedef enum {
  39   XENSTORE_STATUS_SUCCESS = 0,
  40   XENSTORE_STATUS_FAIL,
  41   XENSTORE_STATUS_EINVAL,
  42   XENSTORE_STATUS_EACCES,
  43   XENSTORE_STATUS_EEXIST,
  44   XENSTORE_STATUS_EISDIR,
  45   XENSTORE_STATUS_ENOENT,
  46   XENSTORE_STATUS_ENOMEM,
  47   XENSTORE_STATUS_ENOSPC,
  48   XENSTORE_STATUS_EIO,
  49   XENSTORE_STATUS_ENOTEMPTY,
  50   XENSTORE_STATUS_ENOSYS,
  51   XENSTORE_STATUS_EROFS,
  52   XENSTORE_STATUS_EBUSY,
  53   XENSTORE_STATUS_EAGAIN,
  54   XENSTORE_STATUS_EISCONN,
  55   XENSTORE_STATUS_E2BIG
  56 } XENSTORE_STATUS;
  57
  58
  59 #include <IndustryStandard/Xen/grant_table.h>
  60 #include <IndustryStandard/Xen/event_channel.h>
  61
  62 ///
  63 /// Function prototypes
  64 ///
  65
  66 /**
  67   Get the contents of the node Node of the PV device. Returns the contents in
  68   *Result which should be freed after use.
  69
  70   @param This           A pointer to XENBUS_PROTOCOL instance.
  71   @param Transaction    The XenStore transaction covering this request.
  72   @param Node           The basename of the file to read.
  73   @param Result         The returned contents from this file.
  74
  75   @return  On success, XENSTORE_STATUS_SUCCESS. Otherwise an errno value
  76            indicating the type of failure.
  77
  78   @note The results buffer is malloced and should be free'd by the
  79         caller.
  80 **/
  81 typedef
  82 XENSTORE_STATUS
  83 (EFIAPI *XENBUS_XS_READ)(
  84   IN  XENBUS_PROTOCOL       *This,
  85   IN  CONST XENSTORE_TRANSACTION *Transaction,
  86   IN  CONST CHAR8           *Node,
  87   OUT VOID                  **Result
  88   );
  89
  90 /**
  91   Get the contents of the node Node of the PV device's backend. Returns the
  92   contents in *Result which should be freed after use.
  93
  94   @param This           A pointer to XENBUS_PROTOCOL instance.
  95   @param Transaction    The XenStore transaction covering this request.
  96   @param Node           The basename of the file to read.
  97   @param Result         The returned contents from this file.
  98
  99   @return  On success, XENSTORE_STATUS_SUCCESS. Otherwise an errno value
 100            indicating the type of failure.
 101
 102   @note The results buffer is malloced and should be free'd by the
 103         caller.
 104 **/
 105 typedef
 106 XENSTORE_STATUS
 107 (EFIAPI *XENBUS_XS_BACKEND_READ)(
 108   IN  XENBUS_PROTOCOL       *This,
 109   IN  CONST XENSTORE_TRANSACTION *Transaction,
 110   IN  CONST CHAR8           *Node,
 111   OUT VOID                  **Result
 112   );
 113
 114 /**
 115   Print formatted write to a XenStore node.
 116
 117   @param This             A pointer to XENBUS_PROTOCOL instance.
 118   @param Transaction      The XenStore transaction covering this request.
 119   @param Directory        The dirname of the path to read.
 120   @param Node             The basename of the path to read.
 121   @param Format           AsciiSPrint format string followed by a variable number
 122                           of arguments.
 123
 124   @return  On success, XENSTORE_STATUS_SUCCESS. Otherwise an errno value
 125            indicating the type of write failure.
 126 **/
 127 typedef
 128 XENSTORE_STATUS
 129 (EFIAPI *XENBUS_XS_PRINTF) (
 130   IN XENBUS_PROTOCOL        *This,
 131   IN CONST XENSTORE_TRANSACTION *Transaction,
 132   IN CONST CHAR8            *Directory,
 133   IN CONST CHAR8            *Node,
 134   IN CONST CHAR8            *Format,
 135   ...
 136   );
 137
 138 /**
 139   Remove a node or directory (directories must be empty) of the PV driver's
 140   subdirectory.
 141
 142   @param This           A pointer to XENBUS_PROTOCOL instance.
 143   @param Transaction    The XenStore transaction covering this request.
 144   @param Node           The basename of the node to remove.
 145
 146   @return  On success, XENSTORE_STATUS_SUCCESS. Otherwise an errno value
 147            indicating the type of failure.
 148 **/
 149 typedef
 150 XENSTORE_STATUS
 151 (EFIAPI *XENBUS_XS_REMOVE) (
 152   IN XENBUS_PROTOCOL        *This,
 153   IN CONST XENSTORE_TRANSACTION *Transaction,
 154   IN CONST CHAR8            *Node
 155   );
 156
 157 /**
 158   Start a transaction.
 159
 160   Changes by others will not be seen during the lifetime of this
 161   transaction, and changes will not be visible to others until it
 162   is committed (XsTransactionEnd).
 163
 164   @param This         A pointer to XENBUS_PROTOCOL instance.
 165   @param Transaction  The returned transaction.
 166
 167   @return  On success, XENSTORE_STATUS_SUCCESS. Otherwise an errno value
 168            indicating the type of failure.
 169 **/
 170 typedef
 171 XENSTORE_STATUS
 172 (EFIAPI *XENBUS_XS_TRANSACTION_START)(
 173   IN  XENBUS_PROTOCOL       *This,
 174   OUT XENSTORE_TRANSACTION  *Transaction
 175   );
 176
 177 /**
 178   End a transaction.
 179
 180   @param This         A pointer to XENBUS_PROTOCOL instance.
 181   @param Transaction  The transaction to end/commit.
 182   @param Abort        If TRUE, the transaction is discarded
 183                       instead of committed.
 184
 185   @return  On success, XENSTORE_STATUS_SUCCESS. Otherwise an errno value
 186            indicating the type of failure.
 187 **/
 188 typedef
 189 XENSTORE_STATUS
 190 (EFIAPI *XENBUS_XS_TRANSACTION_END) (
 191   IN XENBUS_PROTOCOL        *This,
 192   IN CONST XENSTORE_TRANSACTION *Transaction,
 193   IN BOOLEAN                Abort
 194   );
 195
 196 /**
 197   Set a new state for the frontend of the PV driver.
 198
 199   @param This         A pointer to XENBUS_PROTOCOL instance.
 200   @param Transaction  The transaction to end/commit.
 201   @param State        The new state to apply.
 202
 203   @return  On success, XENSTORE_STATUS_SUCCESS. Otherwise an errno value
 204            indicating the type of failure.
 205 **/
 206 typedef
 207 XENSTORE_STATUS
 208 (EFIAPI *XENBUS_SET_STATE)(
 209   IN XENBUS_PROTOCOL        *This,
 210   IN CONST XENSTORE_TRANSACTION *Transaction,
 211   IN XenBusState            State
 212   );
 213
 214 /**
 215   Grant access to the page Frame to the domain DomainId.
 216
 217   @param This       A pointer to XENBUS_PROTOCOL instance.
 218   @param DomainId   ID of the domain to grant access to.
 219   @param Frame      Frame Number of the page to grant access to.
 220   @param ReadOnly   Provide read-only or read-write access.
 221   @param RefPtr     Reference number of the grant will be written to this pointer.
 222 **/
 223 typedef
 224 EFI_STATUS
 225 (EFIAPI *XENBUS_GRANT_ACCESS)(
 226   IN  XENBUS_PROTOCOL *This,
 227   IN  domid_t         DomainId,
 228   IN  UINTN           Frame,
 229   IN  BOOLEAN         ReadOnly,
 230   OUT grant_ref_t     *refp
 231   );
 232
 233 /**
 234   End access to grant Ref, previously return by XenBusGrantAccess.
 235
 236   @param This       A pointer to XENBUS_PROTOCOL instance.
 237   @param Ref        Reference numeber of a grant previously returned by
 238                     XenBusGrantAccess.
 239 **/
 240 typedef
 241 EFI_STATUS
 242 (EFIAPI *XENBUS_GRANT_END_ACCESS)(
 243   IN XENBUS_PROTOCOL  *This,
 244   IN grant_ref_t      Ref
 245   );
 246
 247 /**
 248   Allocate a port that can be bind from domain DomainId.
 249
 250   @param This       A pointer to the XENBUS_PROTOCOL.
 251   @param DomainId   The domain ID that can bind the newly allocated port.
 252   @param Port       A pointer to a evtchn_port_t that will contain the newly
 253                     allocated port.
 254
 255   @retval UINT32    The return value from the hypercall, 0 if success.
 256 **/
 257 typedef
 258 UINT32
 259 (EFIAPI *XENBUS_EVENT_CHANNEL_ALLOCATE) (
 260   IN  XENBUS_PROTOCOL *This,
 261   IN  domid_t         DomainId,
 262   OUT evtchn_port_t   *Port
 263   );
 264
 265 /**
 266   Send an event to the remote end of the channel whose local endpoint is Port.
 267
 268   @param This       A pointer to the XENBUS_PROTOCOL.
 269   @param Port       Local port to the event from.
 270
 271   @retval UINT32    The return value from the hypercall, 0 if success.
 272 **/
 273 typedef
 274 UINT32
 275 (EFIAPI *XENBUS_EVENT_CHANNEL_NOTIFY) (
 276   IN XENBUS_PROTOCOL  *This,
 277   IN evtchn_port_t    Port
 278   );
 279
 280 /**
 281   Close a local event channel Port.
 282
 283   @param This       A pointer to the XENBUS_PROTOCOL.
 284   @param Port       The event channel to close.
 285
 286   @retval UINT32    The return value from the hypercall, 0 if success.
 287 **/
 288 typedef
 289 UINT32
 290 (EFIAPI *XENBUS_EVENT_CHANNEL_CLOSE) (
 291   IN XENBUS_PROTOCOL  *This,
 292   IN evtchn_port_t    Port
 293   );
 294
 295 /**
 296   Register a XenStore watch.
 297
 298   XenStore watches allow a client to wait for changes to an object in the
 299   XenStore.
 300
 301   @param This       A pointer to the XENBUS_PROTOCOL.
 302   @param Node       The basename of the path to watch.
 303   @param Token      A token.
 304
 305   @return  On success, XENSTORE_STATUS_SUCCESS. Otherwise an errno value
 306            indicating the type of write failure.  EEXIST errors from the
 307            XenStore are suppressed, allowing multiple, physically different,
 308            xenbus_watch objects, to watch the same path in the XenStore.
 309 **/
 310 typedef
 311 XENSTORE_STATUS
 312 (EFIAPI *XENBUS_REGISTER_WATCH) (
 313   IN  XENBUS_PROTOCOL *This,
 314   IN  CONST CHAR8     *Node,
 315   OUT VOID            **Token
 316   );
 317
 318 /**
 319   Register a XenStore watch on a backend's node.
 320
 321   XenStore watches allow a client to wait for changes to an object in the
 322   XenStore.
 323
 324   @param This       A pointer to the XENBUS_PROTOCOL.
 325   @param Node       The basename of the path to watch.
 326   @param Token      A token.
 327
 328   @return  On success, XENSTORE_STATUS_SUCCESS. Otherwise an errno value
 329            indicating the type of write failure.  EEXIST errors from the
 330            XenStore are suppressed, allowing multiple, physically different,
 331            xenbus_watch objects, to watch the same path in the XenStore.
 332 **/
 333 typedef
 334 XENSTORE_STATUS
 335 (EFIAPI *XENBUS_REGISTER_WATCH_BACKEND) (
 336   IN  XENBUS_PROTOCOL *This,
 337   IN  CONST CHAR8     *Node,
 338   OUT VOID            **Token
 339   );
 340
 341 /**
 342   Unregister a XenStore watch.
 343
 344   @param This   A pointer to the XENBUS_PROTOCOL.
 345   @param Token  An token previously returned by a successful
 346                 call to RegisterWatch ().
 347 **/
 348 typedef
 349 VOID
 350 (EFIAPI *XENBUS_UNREGISTER_WATCH) (
 351   IN XENBUS_PROTOCOL  *This,
 352   IN VOID             *Token
 353   );
 354
 355 /**
 356   Block until the node watch by Token change.
 357
 358   @param This   A pointer to the XENBUS_PROTOCOL.
 359   @param Token  An token previously returned by a successful
 360                 call to RegisterWatch or RegisterWatchBackend.
 361
 362   @return  On success, XENSTORE_STATUS_SUCCESS. Otherwise an errno value
 363            indicating the type of failure.
 364 **/
 365 typedef
 366 XENSTORE_STATUS
 367 (EFIAPI *XENBUS_WAIT_FOR_WATCH) (
 368   IN XENBUS_PROTOCOL  *This,
 369   IN VOID             *Token
 370   );
 371
 372
 373 ///
 374 /// Protocol structure
 375 ///
 376 /// DISCLAIMER: the XENBUS_PROTOCOL introduced here is a work in progress, and
 377 /// should not be used outside of the EDK II tree.
 378 ///
 379 struct _XENBUS_PROTOCOL {
 380   XENBUS_XS_READ                XsRead;
 381   XENBUS_XS_BACKEND_READ        XsBackendRead;
 382   XENBUS_XS_PRINTF              XsPrintf;
 383   XENBUS_XS_REMOVE              XsRemove;
 384   XENBUS_XS_TRANSACTION_START   XsTransactionStart;
 385   XENBUS_XS_TRANSACTION_END     XsTransactionEnd;
 386   XENBUS_SET_STATE              SetState;
 387
 388   XENBUS_GRANT_ACCESS           GrantAccess;
 389   XENBUS_GRANT_END_ACCESS       GrantEndAccess;
 390
 391   XENBUS_EVENT_CHANNEL_ALLOCATE EventChannelAllocate;
 392   XENBUS_EVENT_CHANNEL_NOTIFY   EventChannelNotify;
 393   XENBUS_EVENT_CHANNEL_CLOSE    EventChannelClose;
 394
 395   XENBUS_REGISTER_WATCH         RegisterWatch;
 396   XENBUS_REGISTER_WATCH_BACKEND RegisterWatchBackend;
 397   XENBUS_UNREGISTER_WATCH       UnregisterWatch;
 398   XENBUS_WAIT_FOR_WATCH         WaitForWatch;
 399   //
 400   // Protocol data fields
 401   //
 402   CONST CHAR8                   *Type;
 403   UINT16                        DeviceId;
 404   CONST CHAR8                   *Node;
 405   CONST CHAR8                   *Backend;
 406 };
 407
 408 extern EFI_GUID gXenBusProtocolGuid;
 409
 410 #endif