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) { 0 })
  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
  67 ///
  68 /// Function prototypes
  69 ///
  70
  71 /**
  72   Get the contents of the node Node of the PV device. Returns the contents in
  73   *Result which should be freed after use.
  74
  75   @param This           A pointer to XENBUS_PROTOCOL instance.
  76   @param Transaction    The XenStore transaction covering this request.
  77   @param Node           The basename of the file to read.
  78   @param Result         The returned contents from this file.
  79
  80   @return  On success, XENSTORE_STATUS_SUCCESS. Otherwise an errno value
  81            indicating the type of failure.
  82
  83   @note The results buffer is malloced and should be free'd by the
  84         caller.
  85 **/
  86 typedef
  87 XENSTORE_STATUS
  88 (EFIAPI *XENBUS_XS_READ)(
  89   IN  XENBUS_PROTOCOL       *This,
  90   IN  XENSTORE_TRANSACTION  Transaction,
  91   IN  CONST CHAR8           *Node,
  92   OUT VOID                  **Result
  93   );
  94
  95 /**
  96   Get the contents of the node Node of the PV device's backend. Returns the
  97   contents in *Result which should be freed after use.
  98
  99   @param This           A pointer to XENBUS_PROTOCOL instance.
 100   @param Transaction    The XenStore transaction covering this request.
 101   @param Node           The basename of the file to read.
 102   @param Result         The returned contents from this file.
 103
 104   @return  On success, XENSTORE_STATUS_SUCCESS. Otherwise an errno value
 105            indicating the type of failure.
 106
 107   @note The results buffer is malloced and should be free'd by the
 108         caller.
 109 **/
 110 typedef
 111 XENSTORE_STATUS
 112 (EFIAPI *XENBUS_XS_BACKEND_READ)(
 113   IN  XENBUS_PROTOCOL       *This,
 114   IN  XENSTORE_TRANSACTION  Transaction,
 115   IN  CONST CHAR8           *Node,
 116   OUT VOID                  **Result
 117   );
 118
 119 /**
 120   Print formatted write to a XenStore node.
 121
 122   @param This             A pointer to XENBUS_PROTOCOL instance.
 123   @param Transaction      The XenStore transaction covering this request.
 124   @param Directory        The dirname of the path to read.
 125   @param Node             The basename of the path to read.
 126   @param Format           AsciiSPrint format string followed by a variable number
 127                           of arguments.
 128
 129   @return  On success, XENSTORE_STATUS_SUCCESS. Otherwise an errno value
 130            indicating the type of write failure.
 131 **/
 132 typedef
 133 XENSTORE_STATUS
 134 (EFIAPI *XENBUS_XS_PRINTF) (
 135   IN XENBUS_PROTOCOL        *This,
 136   IN XENSTORE_TRANSACTION   Transaction,
 137   IN CONST CHAR8            *Directory,
 138   IN CONST CHAR8            *Node,
 139   IN CONST CHAR8            *Format,
 140   ...
 141   );
 142
 143 /**
 144   Remove a node or directory (directories must be empty) of the PV driver's
 145   subdirectory.
 146
 147   @param This           A pointer to XENBUS_PROTOCOL instance.
 148   @param Transaction    The XenStore transaction covering this request.
 149   @param Node           The basename of the node to remove.
 150
 151   @return  On success, XENSTORE_STATUS_SUCCESS. Otherwise an errno value
 152            indicating the type of failure.
 153 **/
 154 typedef
 155 XENSTORE_STATUS
 156 (EFIAPI *XENBUS_XS_REMOVE) (
 157   IN XENBUS_PROTOCOL        *This,
 158   IN XENSTORE_TRANSACTION   Transaction,
 159   IN CONST CHAR8            *Node
 160   );
 161
 162 /**
 163   Start a transaction.
 164
 165   Changes by others will not be seen during the lifetime of this
 166   transaction, and changes will not be visible to others until it
 167   is committed (XsTransactionEnd).
 168
 169   @param This         A pointer to XENBUS_PROTOCOL instance.
 170   @param Transaction  The returned transaction.
 171
 172   @return  On success, XENSTORE_STATUS_SUCCESS. Otherwise an errno value
 173            indicating the type of failure.
 174 **/
 175 typedef
 176 XENSTORE_STATUS
 177 (EFIAPI *XENBUS_XS_TRANSACTION_START)(
 178   IN  XENBUS_PROTOCOL       *This,
 179   OUT XENSTORE_TRANSACTION  *Transaction
 180   );
 181
 182 /**
 183   End a transaction.
 184
 185   @param This         A pointer to XENBUS_PROTOCOL instance.
 186   @param Transaction  The transaction to end/commit.
 187   @param Abort        If TRUE, the transaction is discarded
 188                       instead of committed.
 189
 190   @return  On success, XENSTORE_STATUS_SUCCESS. Otherwise an errno value
 191            indicating the type of failure.
 192 **/
 193 typedef
 194 XENSTORE_STATUS
 195 (EFIAPI *XENBUS_XS_TRANSACTION_END) (
 196   IN XENBUS_PROTOCOL        *This,
 197   IN XENSTORE_TRANSACTION   Transaction,
 198   IN BOOLEAN                Abort
 199   );
 200
 201 /**
 202   Set a new state for the frontend of the PV driver.
 203
 204   @param This         A pointer to XENBUS_PROTOCOL instance.
 205   @param Transaction  The transaction to end/commit.
 206   @param State        The new state to apply.
 207
 208   @return  On success, XENSTORE_STATUS_SUCCESS. Otherwise an errno value
 209            indicating the type of failure.
 210 **/
 211 typedef
 212 XENSTORE_STATUS
 213 (EFIAPI *XENBUS_SET_STATE)(
 214   IN XENBUS_PROTOCOL        *This,
 215   IN XENSTORE_TRANSACTION   Transaction,
 216   IN XenBusState            State
 217   );
 218
 219 /**
 220   Grant access to the page Frame to the domain DomainId.
 221
 222   @param This       A pointer to XENBUS_PROTOCOL instance.
 223   @param DomainId   ID of the domain to grant acces to.
 224   @param Frame      Frame Number of the page to grant access to.
 225   @param ReadOnly   Provide read-only or read-write access.
 226   @param RefPtr     Reference number of the grant will be writen to this pointer.
 227 **/
 228 typedef
 229 EFI_STATUS
 230 (EFIAPI *XENBUS_GRANT_ACCESS)(
 231   IN  XENBUS_PROTOCOL *This,
 232   IN  domid_t         DomainId,
 233   IN  UINTN           Frame,
 234   IN  BOOLEAN         ReadOnly,
 235   OUT grant_ref_t     *refp
 236   );
 237
 238 /**
 239   End access to grant Ref, previously return by XenBusGrantAccess.
 240
 241   @param This       A pointer to XENBUS_PROTOCOL instance.
 242   @param Ref        Reference numeber of a grant previously returned by
 243                     XenBusGrantAccess.
 244 **/
 245 typedef
 246 EFI_STATUS
 247 (EFIAPI *XENBUS_GRANT_END_ACCESS)(
 248   IN XENBUS_PROTOCOL  *This,
 249   IN grant_ref_t      Ref
 250   );
 251
 252 /**
 253   Register a XenStore watch.
 254
 255   XenStore watches allow a client to wait for changes to an object in the
 256   XenStore.
 257
 258   @param This       A pointer to the XENBUS_PROTOCOL.
 259   @param Node       The basename of the path to watch.
 260   @param Token      A token.
 261
 262   @return  On success, XENSTORE_STATUS_SUCCESS. Otherwise an errno value
 263            indicating the type of write failure.  EEXIST errors from the
 264            XenStore are supressed, allowing multiple, physically different,
 265            xenbus_watch objects, to watch the same path in the XenStore.
 266 **/
 267 typedef
 268 XENSTORE_STATUS
 269 (EFIAPI *XENBUS_REGISTER_WATCH) (
 270   IN  XENBUS_PROTOCOL *This,
 271   IN  CONST CHAR8     *Node,
 272   OUT VOID            **Token
 273   );
 274
 275 /**
 276   Register a XenStore watch on a backend's node.
 277
 278   XenStore watches allow a client to wait for changes to an object in the
 279   XenStore.
 280
 281   @param This       A pointer to the XENBUS_PROTOCOL.
 282   @param Node       The basename of the path to watch.
 283   @param Token      A token.
 284
 285   @return  On success, XENSTORE_STATUS_SUCCESS. Otherwise an errno value
 286            indicating the type of write failure.  EEXIST errors from the
 287            XenStore are supressed, allowing multiple, physically different,
 288            xenbus_watch objects, to watch the same path in the XenStore.
 289 **/
 290 typedef
 291 XENSTORE_STATUS
 292 (EFIAPI *XENBUS_REGISTER_WATCH_BACKEND) (
 293   IN  XENBUS_PROTOCOL *This,
 294   IN  CONST CHAR8     *Node,
 295   OUT VOID            **Token
 296   );
 297
 298 /**
 299   Unregister a XenStore watch.
 300
 301   @param This   A pointer to the XENBUS_PROTOCOL.
 302   @param Token  An token previously returned by a successful
 303                 call to RegisterWatch ().
 304 **/
 305 typedef
 306 VOID
 307 (EFIAPI *XENBUS_UNREGISTER_WATCH) (
 308   IN XENBUS_PROTOCOL  *This,
 309   IN VOID             *Token
 310   );
 311
 312 /**
 313   Block until the node watch by Token change.
 314
 315   @param This   A pointer to the XENBUS_PROTOCOL.
 316   @param Token  An token previously returned by a successful
 317                 call to RegisterWatch or RegisterWatchBackend.
 318
 319   @return  On success, XENSTORE_STATUS_SUCCESS. Otherwise an errno value
 320            indicating the type of failure.
 321 **/
 322 typedef
 323 XENSTORE_STATUS
 324 (EFIAPI *XENBUS_WAIT_FOR_WATCH) (
 325   IN XENBUS_PROTOCOL  *This,
 326   IN VOID             *Token
 327   );
 328
 329
 330 ///
 331 /// Protocol structure
 332 ///
 333 /// DISCLAIMER: the XENBUS_PROTOCOL introduced here is a work in progress, and
 334 /// should not be used outside of the EDK II tree.
 335 ///
 336 struct _XENBUS_PROTOCOL {
 337   XENBUS_XS_READ                XsRead;
 338   XENBUS_XS_BACKEND_READ        XsBackendRead;
 339   XENBUS_XS_PRINTF              XsPrintf;
 340   XENBUS_XS_REMOVE              XsRemove;
 341   XENBUS_XS_TRANSACTION_START   XsTransactionStart;
 342   XENBUS_XS_TRANSACTION_END     XsTransactionEnd;
 343   XENBUS_SET_STATE              SetState;
 344
 345   XENBUS_GRANT_ACCESS           GrantAccess;
 346   XENBUS_GRANT_END_ACCESS       GrantEndAccess;
 347
 348   XENBUS_REGISTER_WATCH         RegisterWatch;
 349   XENBUS_REGISTER_WATCH_BACKEND RegisterWatchBackend;
 350   XENBUS_UNREGISTER_WATCH       UnregisterWatch;
 351   XENBUS_WAIT_FOR_WATCH         WaitForWatch;
 352   //
 353   // Protocol data fields
 354   //
 355   CONST CHAR8                   *Type;
 356   UINT16                        DeviceId;
 357   CONST CHAR8                   *Node;
 358   CONST CHAR8                   *Backend;
 359 };
 360
 361 extern EFI_GUID gXenBusProtocolGuid;
 362
 363 #endif