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