OvmfPkg/XenBusDxe/XenStore.h

   1 /** @file
   2   Method declarations and structures for accessing the XenStore
   3
   4   Copyright (C) 2005 Rusty Russell, IBM Corporation
   5   Copyright (C) 2005 XenSource Ltd.
   6   Copyright (C) 2009,2010 Spectra Logic Corporation
   7   Copyright (C) 2014, Citrix Ltd.
   8
   9   This file may be distributed separately from the Linux kernel, or
  10   incorporated into other software packages, subject to the following license:
  11
  12   Permission is hereby granted, free of charge, to any person obtaining a copy
  13   of this source file (the "Software"), to deal in the Software without
  14   restriction, including without limitation the rights to use, copy, modify,
  15   merge, publish, distribute, sublicense, and/or sell copies of the Software,
  16   and to permit persons to whom the Software is furnished to do so, subject to
  17   the following conditions:
  18
  19   The above copyright notice and this permission notice shall be included in
  20   all copies or substantial portions of the Software.
  21
  22   THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  23   IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  24   FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
  25   AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
  26   LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
  27   FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
  28   IN THE SOFTWARE.
  29 **/
  30
  31 #ifndef _XEN_XENSTORE_XENSTOREVAR_H
  32 #define _XEN_XENSTORE_XENSTOREVAR_H
  33
  34 #include "XenBusDxe.h"
  35
  36 #include <IndustryStandard/Xen/io/xs_wire.h>
  37
  38 typedef struct _XENSTORE_WATCH XENSTORE_WATCH;
  39
  40 /**
  41   Fetch the contents of a directory in the XenStore.
  42
  43   @param Transaction        The XenStore transaction covering this request.
  44   @param DirectoryPath      The dirname of the path to read.
  45   @param Node               The basename of the path to read.
  46   @param DirectoryCountPtr  The returned number of directory entries.
  47   @param DirectoryListPtr   An array of directory entry strings.
  48
  49   @return  On success, XENSTORE_STATUS_SUCCESS. Otherwise an errno value
  50            indicating the type of failure.
  51
  52   @note The results buffer is alloced and should be free'd by the
  53         caller.
  54 **/
  55 XENSTORE_STATUS
  56 XenStoreListDirectory (
  57   IN  CONST XENSTORE_TRANSACTION *Transaction,
  58   IN  CONST CHAR8           *DirectoryPath,
  59   IN  CONST CHAR8           *Node,
  60   OUT UINT32                *DirectoryCountPtr,
  61   OUT CONST CHAR8           ***DirectoryListPtr
  62   );
  63
  64 /**
  65   Determine if a path exists in the XenStore.
  66
  67   @param Transaction  The XenStore transaction covering this request.
  68   @param Directory    The dirname of the path to read.
  69   @param Node         The basename of the path to read.
  70
  71   @retval TRUE  The path exists.
  72   @retval FALSE The path does not exist or an error occurred attempting
  73                 to make that determination.
  74 **/
  75 BOOLEAN
  76 XenStorePathExists (
  77   IN CONST XENSTORE_TRANSACTION *Transaction,
  78   IN CONST CHAR8 *Directory,
  79   IN CONST CHAR8 *Node
  80   );
  81
  82 /**
  83   Get the contents of a single "file".  Returns the contents in *Result which
  84   should be freed after use.  The length of the value in bytes is returned in
  85   *LenPtr.
  86
  87   @param Transaction    The XenStore transaction covering this request.
  88   @param DirectoryPath  The dirname of the file to read.
  89   @param Node           The basename of the file to read.
  90   @param LenPtr         The amount of data read.
  91   @param Result         The returned contents from this file.
  92
  93   @return  On success, XENSTORE_STATUS_SUCCESS. Otherwise an errno value
  94            indicating the type of failure.
  95
  96   @note The results buffer is malloced and should be free'd by the
  97         caller.
  98 **/
  99 XENSTORE_STATUS
 100 XenStoreRead (
 101   IN  CONST XENSTORE_TRANSACTION *Transaction,
 102   IN  CONST CHAR8             *DirectoryPath,
 103   IN  CONST CHAR8             *Node,
 104   OUT UINT32                  *LenPtr OPTIONAL,
 105   OUT VOID                    **Result
 106   );
 107
 108 /**
 109   Write to a single file.
 110
 111   @param Transaction    The XenStore transaction covering this request.
 112   @param DirectoryPath  The dirname of the file to write.
 113   @param Node           The basename of the file to write.
 114   @param Str            The NUL terminated string of data to write.
 115
 116   @return  On success, XENSTORE_STATUS_SUCCESS. Otherwise an errno value
 117            indicating the type of failure.
 118 **/
 119 XENSTORE_STATUS
 120 XenStoreWrite (
 121   IN CONST XENSTORE_TRANSACTION *Transaction,
 122   IN CONST CHAR8           *DirectoryPath,
 123   IN CONST CHAR8           *Node,
 124   IN CONST CHAR8           *Str
 125   );
 126
 127 /**
 128   Remove a file or directory (directories must be empty).
 129
 130   @param Transaction    The XenStore transaction covering this request.
 131   @param DirectoryPath  The dirname of the directory to remove.
 132   @param Node           The basename of the directory to remove.
 133
 134   @return  On success, XENSTORE_STATUS_SUCCESS. Otherwise an errno value
 135            indicating the type of failure.
 136 **/
 137 XENSTORE_STATUS
 138 XenStoreRemove (
 139   IN CONST XENSTORE_TRANSACTION *Transaction,
 140   IN CONST CHAR8            *DirectoryPath,
 141   IN CONST CHAR8            *Node
 142   );
 143
 144 /**
 145   Start a transaction.
 146
 147   Changes by others will not be seen during the lifetime of this
 148   transaction, and changes will not be visible to others until it
 149   is committed (XenStoreTransactionEnd).
 150
 151   @param Transaction  The returned transaction.
 152
 153   @return  On success, XENSTORE_STATUS_SUCCESS. Otherwise an errno value
 154            indicating the type of failure.
 155 **/
 156 XENSTORE_STATUS
 157 XenStoreTransactionStart (
 158   OUT XENSTORE_TRANSACTION *Transaction
 159   );
 160
 161 /**
 162   End a transaction.
 163
 164   @param Transaction  The transaction to end/commit.
 165   @param Abort        If TRUE, the transaction is discarded
 166                       instead of committed.
 167
 168   @return  On success, XENSTORE_STATUS_SUCCESS. Otherwise an errno value
 169            indicating the type of failure.
 170 **/
 171 XENSTORE_STATUS
 172 XenStoreTransactionEnd (
 173   IN CONST XENSTORE_TRANSACTION *Transaction,
 174   IN BOOLEAN                Abort
 175   );
 176
 177 /**
 178   Printf formatted write to a XenStore file.
 179
 180   @param Transaction      The XenStore transaction covering this request.
 181   @param DirectoryPath    The dirname of the path to read.
 182   @param Node             The basename of the path to read.
 183   @param FormatString     AsciiSPrint format string followed by a variable number
 184                           of arguments.
 185
 186   @return  On success, XENSTORE_STATUS_SUCCESS. Otherwise an errno value
 187            indicating the type of write failure.
 188 **/
 189 XENSTORE_STATUS
 190 EFIAPI
 191 XenStoreSPrint (
 192   IN CONST XENSTORE_TRANSACTION *Transaction,
 193   IN CONST CHAR8            *DirectoryPath,
 194   IN CONST CHAR8            *Node,
 195   IN CONST CHAR8            *FormatString,
 196   ...
 197   );
 198
 199 /**
 200   VA_LIST version of XenStoreSPrint().
 201
 202   @param Transaction    The XenStore transaction covering this request.
 203   @param DirectoryPath  The dirname of the path to read.
 204   @param Node           The basename of the path to read.
 205   @param FormatString   Printf format string.
 206   @param Marker         VA_LIST of printf arguments.
 207
 208   @return  On success, XENSTORE_STATUS_SUCCESS. Otherwise an errno value
 209            indicating the type of write failure.
 210 **/
 211 XENSTORE_STATUS
 212 EFIAPI
 213 XenStoreVSPrint (
 214   IN CONST XENSTORE_TRANSACTION *Transaction,
 215   IN CONST CHAR8           *DirectoryPath,
 216   IN CONST CHAR8           *Node,
 217   IN CONST CHAR8           *FormatString,
 218   IN VA_LIST               Marker
 219   );
 220
 221 /**
 222   Register a XenStore watch.
 223
 224   XenStore watches allow a client to be notified via a callback (embedded
 225   within the watch object) of changes to an object in the XenStore.
 226
 227   @param DirectoryPath  The dirname of the path to watch.
 228   @param Node           The basename of the path to watch.
 229   @param WatchPtr       A returned XENSTORE_WATCH pointer.
 230
 231   @return  On success, XENSTORE_STATUS_SUCCESS. Otherwise an errno value
 232            indicating the type of write failure.  EEXIST errors from the
 233            XenStore are suppressed, allowing multiple, physically different,
 234            xenbus_watch objects, to watch the same path in the XenStore.
 235 **/
 236 XENSTORE_STATUS
 237 XenStoreRegisterWatch (
 238   IN  CONST CHAR8     *DirectoryPath,
 239   IN  CONST CHAR8     *Node,
 240   OUT XENSTORE_WATCH  **WatchPtr
 241   );
 242
 243 /**
 244   Unregister a XenStore watch.
 245
 246   @param Watch  An XENSTORE_WATCH object previously returned by a successful
 247                 call to XenStoreRegisterWatch ().
 248 **/
 249 VOID
 250 XenStoreUnregisterWatch (
 251   IN XENSTORE_WATCH *Watch
 252   );
 253
 254 /**
 255   Allocate and return the XenStore path string <DirectoryPath>/<Node>.  If name
 256   is the NUL string, the returned value contains the path string
 257   <DirectoryPath>.
 258
 259   @param DirectoryPath  The NUL terminated directory prefix for new path.
 260   @param Node           The NUL terminated basename for the new path.
 261
 262   @return  A buffer containing the joined path.
 263  */
 264 CHAR8 *
 265 XenStoreJoin (
 266   IN CONST CHAR8 *DirectoryPath,
 267   IN CONST CHAR8 *Node
 268   );
 269
 270
 271 /**
 272   Initialize the XenStore states and rings.
 273
 274   @param Dev  A pointer to a XENBUS_DEVICE instance.
 275
 276   @return     EFI_SUCCESS if everything went smoothly.
 277 **/
 278 EFI_STATUS
 279 XenStoreInit (
 280   XENBUS_DEVICE *Dev
 281   );
 282
 283 /**
 284   Deinitialize the XenStore states and rings.
 285
 286   @param Dev  A pointer to a XENBUS_DEVICE instance.
 287 **/
 288 VOID
 289 XenStoreDeinit (
 290   IN XENBUS_DEVICE *Dev
 291   );
 292
 293
 294 //
 295 // XENBUS protocol
 296 //
 297
 298 XENSTORE_STATUS
 299 EFIAPI
 300 XenBusWaitForWatch (
 301   IN XENBUS_PROTOCOL *This,
 302   IN VOID *Token
 303   );
 304
 305 XENSTORE_STATUS
 306 EFIAPI
 307 XenBusXenStoreRead (
 308   IN  XENBUS_PROTOCOL       *This,
 309   IN  CONST XENSTORE_TRANSACTION *Transaction,
 310   IN  CONST CHAR8           *Node,
 311   OUT VOID                  **Value
 312   );
 313
 314 XENSTORE_STATUS
 315 EFIAPI
 316 XenBusXenStoreBackendRead (
 317   IN  XENBUS_PROTOCOL       *This,
 318   IN  CONST XENSTORE_TRANSACTION *Transaction,
 319   IN  CONST CHAR8           *Node,
 320   OUT VOID                  **Value
 321   );
 322
 323 XENSTORE_STATUS
 324 EFIAPI
 325 XenBusXenStoreRemove (
 326   IN XENBUS_PROTOCOL        *This,
 327   IN CONST XENSTORE_TRANSACTION *Transaction,
 328   IN CONST CHAR8            *Node
 329   );
 330
 331 XENSTORE_STATUS
 332 EFIAPI
 333 XenBusXenStoreTransactionStart (
 334   IN  XENBUS_PROTOCOL       *This,
 335   OUT XENSTORE_TRANSACTION  *Transaction
 336   );
 337
 338 XENSTORE_STATUS
 339 EFIAPI
 340 XenBusXenStoreTransactionEnd (
 341   IN XENBUS_PROTOCOL        *This,
 342   IN CONST XENSTORE_TRANSACTION *Transaction,
 343   IN BOOLEAN                Abort
 344   );
 345
 346 XENSTORE_STATUS
 347 EFIAPI
 348 XenBusXenStoreSPrint (
 349   IN XENBUS_PROTOCOL        *This,
 350   IN CONST XENSTORE_TRANSACTION *Transaction,
 351   IN CONST CHAR8            *DirectoryPath,
 352   IN CONST CHAR8            *Node,
 353   IN CONST CHAR8            *FormatString,
 354   ...
 355   );
 356
 357 XENSTORE_STATUS
 358 EFIAPI
 359 XenBusRegisterWatch (
 360   IN  XENBUS_PROTOCOL *This,
 361   IN  CONST CHAR8     *Node,
 362   OUT VOID            **Token
 363   );
 364
 365 XENSTORE_STATUS
 366 EFIAPI
 367 XenBusRegisterWatchBackend (
 368   IN  XENBUS_PROTOCOL *This,
 369   IN  CONST CHAR8     *Node,
 370   OUT VOID            **Token
 371   );
 372
 373 VOID
 374 EFIAPI
 375 XenBusUnregisterWatch (
 376   IN XENBUS_PROTOCOL  *This,
 377   IN VOID             *Token
 378   );
 379
 380 #endif /* _XEN_XENSTORE_XENSTOREVAR_H */