OvmfPkg/Include/Protocol/XenBus.h

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