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   Grant access to the page Frame to the domain DomainId.
 203
 204   @param This       A pointer to XENBUS_PROTOCOL instance.
 205   @param DomainId   ID of the domain to grant acces to.
 206   @param Frame      Frame Number of the page to grant access to.
 207   @param ReadOnly   Provide read-only or read-write access.
 208   @param RefPtr     Reference number of the grant will be writen to this pointer.
 209 **/
 210 typedef
 211 EFI_STATUS
 212 (EFIAPI *XENBUS_GRANT_ACCESS)(
 213   IN  XENBUS_PROTOCOL *This,
 214   IN  domid_t         DomainId,
 215   IN  UINTN           Frame,
 216   IN  BOOLEAN         ReadOnly,
 217   OUT grant_ref_t     *refp
 218   );
 219
 220 /**
 221   End access to grant Ref, previously return by XenBusGrantAccess.
 222
 223   @param This       A pointer to XENBUS_PROTOCOL instance.
 224   @param Ref        Reference numeber of a grant previously returned by
 225                     XenBusGrantAccess.
 226 **/
 227 typedef
 228 EFI_STATUS
 229 (EFIAPI *XENBUS_GRANT_END_ACCESS)(
 230   IN XENBUS_PROTOCOL  *This,
 231   IN grant_ref_t      Ref
 232   );
 233
 234 /**
 235   Register a XenStore watch.
 236
 237   XenStore watches allow a client to wait for changes to an object in the
 238   XenStore.
 239
 240   @param This       A pointer to the XENBUS_PROTOCOL.
 241   @param Node       The basename of the path to watch.
 242   @param Token      A token.
 243
 244   @return  On success, XENSTORE_STATUS_SUCCESS. Otherwise an errno value
 245            indicating the type of write failure.  EEXIST errors from the
 246            XenStore are supressed, allowing multiple, physically different,
 247            xenbus_watch objects, to watch the same path in the XenStore.
 248 **/
 249 typedef
 250 XENSTORE_STATUS
 251 (EFIAPI *XENBUS_REGISTER_WATCH) (
 252   IN  XENBUS_PROTOCOL *This,
 253   IN  CONST CHAR8     *Node,
 254   OUT VOID            **Token
 255   );
 256
 257 /**
 258   Register a XenStore watch on a backend's node.
 259
 260   XenStore watches allow a client to wait for changes to an object in the
 261   XenStore.
 262
 263   @param This       A pointer to the XENBUS_PROTOCOL.
 264   @param Node       The basename of the path to watch.
 265   @param Token      A token.
 266
 267   @return  On success, XENSTORE_STATUS_SUCCESS. Otherwise an errno value
 268            indicating the type of write failure.  EEXIST errors from the
 269            XenStore are supressed, allowing multiple, physically different,
 270            xenbus_watch objects, to watch the same path in the XenStore.
 271 **/
 272 typedef
 273 XENSTORE_STATUS
 274 (EFIAPI *XENBUS_REGISTER_WATCH_BACKEND) (
 275   IN  XENBUS_PROTOCOL *This,
 276   IN  CONST CHAR8     *Node,
 277   OUT VOID            **Token
 278   );
 279
 280 /**
 281   Unregister a XenStore watch.
 282
 283   @param This   A pointer to the XENBUS_PROTOCOL.
 284   @param Token  An token previously returned by a successful
 285                 call to RegisterWatch ().
 286 **/
 287 typedef
 288 VOID
 289 (EFIAPI *XENBUS_UNREGISTER_WATCH) (
 290   IN XENBUS_PROTOCOL  *This,
 291   IN VOID             *Token
 292   );
 293
 294 /**
 295   Block until the node watch by Token change.
 296
 297   @param This   A pointer to the XENBUS_PROTOCOL.
 298   @param Token  An token previously returned by a successful
 299                 call to RegisterWatch or RegisterWatchBackend.
 300
 301   @return  On success, XENSTORE_STATUS_SUCCESS. Otherwise an errno value
 302            indicating the type of failure.
 303 **/
 304 typedef
 305 XENSTORE_STATUS
 306 (EFIAPI *XENBUS_WAIT_FOR_WATCH) (
 307   IN XENBUS_PROTOCOL  *This,
 308   IN VOID             *Token
 309   );
 310
 311
 312 ///
 313 /// Protocol structure
 314 ///
 315 /// DISCLAIMER: the XENBUS_PROTOCOL introduced here is a work in progress, and
 316 /// should not be used outside of the EDK II tree.
 317 ///
 318 struct _XENBUS_PROTOCOL {
 319   XENBUS_XS_READ                XsRead;
 320   XENBUS_XS_BACKEND_READ        XsBackendRead;
 321   XENBUS_XS_PRINTF              XsPrintf;
 322   XENBUS_XS_REMOVE              XsRemove;
 323   XENBUS_XS_TRANSACTION_START   XsTransactionStart;
 324   XENBUS_XS_TRANSACTION_END     XsTransactionEnd;
 325
 326   XENBUS_GRANT_ACCESS           GrantAccess;
 327   XENBUS_GRANT_END_ACCESS       GrantEndAccess;
 328
 329   XENBUS_REGISTER_WATCH         RegisterWatch;
 330   XENBUS_REGISTER_WATCH_BACKEND RegisterWatchBackend;
 331   XENBUS_UNREGISTER_WATCH       UnregisterWatch;
 332   XENBUS_WAIT_FOR_WATCH         WaitForWatch;
 333   //
 334   // Protocol data fields
 335   //
 336   CONST CHAR8                   *Type;
 337   UINT16                        DeviceId;
 338   CONST CHAR8                   *Node;
 339   CONST CHAR8                   *Backend;
 340 };
 341
 342 extern EFI_GUID gXenBusProtocolGuid;
 343
 344 #endif