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   SPDX-License-Identifier: MIT
  13 **/
  14
  15 #ifndef _XEN_XENSTORE_XENSTOREVAR_H
  16 #define _XEN_XENSTORE_XENSTOREVAR_H
  17
  18 #include "XenBusDxe.h"
  19
  20 #include <IndustryStandard/Xen/io/xs_wire.h>
  21
  22 typedef struct _XENSTORE_WATCH XENSTORE_WATCH;
  23
  24 /**
  25   Fetch the contents of a directory in the XenStore.
  26
  27   @param Transaction        The XenStore transaction covering this request.
  28   @param DirectoryPath      The dirname of the path to read.
  29   @param Node               The basename of the path to read.
  30   @param DirectoryCountPtr  The returned number of directory entries.
  31   @param DirectoryListPtr   An array of directory entry strings.
  32
  33   @return  On success, XENSTORE_STATUS_SUCCESS. Otherwise an errno value
  34            indicating the type of failure.
  35
  36   @note The results buffer is alloced and should be free'd by the
  37         caller.
  38 **/
  39 XENSTORE_STATUS
  40 XenStoreListDirectory (
  41   IN  CONST XENSTORE_TRANSACTION  *Transaction,
  42   IN  CONST CHAR8                 *DirectoryPath,
  43   IN  CONST CHAR8                 *Node,
  44   OUT UINT32                      *DirectoryCountPtr,
  45   OUT CONST CHAR8                 ***DirectoryListPtr
  46   );
  47
  48 /**
  49   Determine if a path exists in the XenStore.
  50
  51   @param Transaction  The XenStore transaction covering this request.
  52   @param Directory    The dirname of the path to read.
  53   @param Node         The basename of the path to read.
  54
  55   @retval TRUE  The path exists.
  56   @retval FALSE The path does not exist or an error occurred attempting
  57                 to make that determination.
  58 **/
  59 BOOLEAN
  60 XenStorePathExists (
  61   IN CONST XENSTORE_TRANSACTION  *Transaction,
  62   IN CONST CHAR8                 *Directory,
  63   IN CONST CHAR8                 *Node
  64   );
  65
  66 /**
  67   Get the contents of a single "file".  Returns the contents in *Result which
  68   should be freed after use.  The length of the value in bytes is returned in
  69   *LenPtr.
  70
  71   @param Transaction    The XenStore transaction covering this request.
  72   @param DirectoryPath  The dirname of the file to read.
  73   @param Node           The basename of the file to read.
  74   @param LenPtr         The amount of data read.
  75   @param Result         The returned contents from this file.
  76
  77   @return  On success, XENSTORE_STATUS_SUCCESS. Otherwise an errno value
  78            indicating the type of failure.
  79
  80   @note The results buffer is malloced and should be free'd by the
  81         caller.
  82 **/
  83 XENSTORE_STATUS
  84 XenStoreRead (
  85   IN  CONST XENSTORE_TRANSACTION  *Transaction,
  86   IN  CONST CHAR8                 *DirectoryPath,
  87   IN  CONST CHAR8                 *Node,
  88   OUT UINT32                      *LenPtr OPTIONAL,
  89   OUT VOID                        **Result
  90   );
  91
  92 /**
  93   Write to a single file.
  94
  95   @param Transaction    The XenStore transaction covering this request.
  96   @param DirectoryPath  The dirname of the file to write.
  97   @param Node           The basename of the file to write.
  98   @param Str            The NUL terminated string of data to write.
  99
 100   @return  On success, XENSTORE_STATUS_SUCCESS. Otherwise an errno value
 101            indicating the type of failure.
 102 **/
 103 XENSTORE_STATUS
 104 XenStoreWrite (
 105   IN CONST XENSTORE_TRANSACTION  *Transaction,
 106   IN CONST CHAR8                 *DirectoryPath,
 107   IN CONST CHAR8                 *Node,
 108   IN CONST CHAR8                 *Str
 109   );
 110
 111 /**
 112   Remove a file or directory (directories must be empty).
 113
 114   @param Transaction    The XenStore transaction covering this request.
 115   @param DirectoryPath  The dirname of the directory to remove.
 116   @param Node           The basename of the directory to remove.
 117
 118   @return  On success, XENSTORE_STATUS_SUCCESS. Otherwise an errno value
 119            indicating the type of failure.
 120 **/
 121 XENSTORE_STATUS
 122 XenStoreRemove (
 123   IN CONST XENSTORE_TRANSACTION  *Transaction,
 124   IN CONST CHAR8                 *DirectoryPath,
 125   IN CONST CHAR8                 *Node
 126   );
 127
 128 /**
 129   Start a transaction.
 130
 131   Changes by others will not be seen during the lifetime of this
 132   transaction, and changes will not be visible to others until it
 133   is committed (XenStoreTransactionEnd).
 134
 135   @param Transaction  The returned transaction.
 136
 137   @return  On success, XENSTORE_STATUS_SUCCESS. Otherwise an errno value
 138            indicating the type of failure.
 139 **/
 140 XENSTORE_STATUS
 141 XenStoreTransactionStart (
 142   OUT XENSTORE_TRANSACTION  *Transaction
 143   );
 144
 145 /**
 146   End a transaction.
 147
 148   @param Transaction  The transaction to end/commit.
 149   @param Abort        If TRUE, the transaction is discarded
 150                       instead of committed.
 151
 152   @return  On success, XENSTORE_STATUS_SUCCESS. Otherwise an errno value
 153            indicating the type of failure.
 154 **/
 155 XENSTORE_STATUS
 156 XenStoreTransactionEnd (
 157   IN CONST XENSTORE_TRANSACTION  *Transaction,
 158   IN BOOLEAN                     Abort
 159   );
 160
 161 /**
 162   Printf formatted write to a XenStore file.
 163
 164   @param Transaction      The XenStore transaction covering this request.
 165   @param DirectoryPath    The dirname of the path to read.
 166   @param Node             The basename of the path to read.
 167   @param FormatString     AsciiSPrint format string followed by a variable number
 168                           of arguments.
 169
 170   @return  On success, XENSTORE_STATUS_SUCCESS. Otherwise an errno value
 171            indicating the type of write failure.
 172 **/
 173 XENSTORE_STATUS
 174 EFIAPI
 175 XenStoreSPrint (
 176   IN CONST XENSTORE_TRANSACTION  *Transaction,
 177   IN CONST CHAR8                 *DirectoryPath,
 178   IN CONST CHAR8                 *Node,
 179   IN CONST CHAR8                 *FormatString,
 180   ...
 181   );
 182
 183 /**
 184   VA_LIST version of XenStoreSPrint().
 185
 186   @param Transaction    The XenStore transaction covering this request.
 187   @param DirectoryPath  The dirname of the path to read.
 188   @param Node           The basename of the path to read.
 189   @param FormatString   Printf format string.
 190   @param Marker         VA_LIST of printf arguments.
 191
 192   @return  On success, XENSTORE_STATUS_SUCCESS. Otherwise an errno value
 193            indicating the type of write failure.
 194 **/
 195 XENSTORE_STATUS
 196 EFIAPI
 197 XenStoreVSPrint (
 198   IN CONST XENSTORE_TRANSACTION  *Transaction,
 199   IN CONST CHAR8                 *DirectoryPath,
 200   IN CONST CHAR8                 *Node,
 201   IN CONST CHAR8                 *FormatString,
 202   IN VA_LIST                     Marker
 203   );
 204
 205 /**
 206   Register a XenStore watch.
 207
 208   XenStore watches allow a client to be notified via a callback (embedded
 209   within the watch object) of changes to an object in the XenStore.
 210
 211   @param DirectoryPath  The dirname of the path to watch.
 212   @param Node           The basename of the path to watch.
 213   @param WatchPtr       A returned XENSTORE_WATCH pointer.
 214
 215   @return  On success, XENSTORE_STATUS_SUCCESS. Otherwise an errno value
 216            indicating the type of write failure.  EEXIST errors from the
 217            XenStore are suppressed, allowing multiple, physically different,
 218            xenbus_watch objects, to watch the same path in the XenStore.
 219 **/
 220 XENSTORE_STATUS
 221 XenStoreRegisterWatch (
 222   IN  CONST CHAR8     *DirectoryPath,
 223   IN  CONST CHAR8     *Node,
 224   OUT XENSTORE_WATCH  **WatchPtr
 225   );
 226
 227 /**
 228   Unregister a XenStore watch.
 229
 230   @param Watch  An XENSTORE_WATCH object previously returned by a successful
 231                 call to XenStoreRegisterWatch ().
 232 **/
 233 VOID
 234 XenStoreUnregisterWatch (
 235   IN XENSTORE_WATCH  *Watch
 236   );
 237
 238 /**
 239   Allocate and return the XenStore path string <DirectoryPath>/<Node>.  If name
 240   is the NUL string, the returned value contains the path string
 241   <DirectoryPath>.
 242
 243   @param DirectoryPath  The NUL terminated directory prefix for new path.
 244   @param Node           The NUL terminated basename for the new path.
 245
 246   @return  A buffer containing the joined path.
 247  */
 248 CHAR8 *
 249 XenStoreJoin (
 250   IN CONST CHAR8  *DirectoryPath,
 251   IN CONST CHAR8  *Node
 252   );
 253
 254 /**
 255   Initialize the XenStore states and rings.
 256
 257   @param Dev  A pointer to a XENBUS_DEVICE instance.
 258
 259   @return     EFI_SUCCESS if everything went smoothly.
 260 **/
 261 EFI_STATUS
 262 XenStoreInit (
 263   XENBUS_DEVICE  *Dev
 264   );
 265
 266 /**
 267   Deinitialize the XenStore states and rings.
 268
 269   @param Dev  A pointer to a XENBUS_DEVICE instance.
 270 **/
 271 VOID
 272 XenStoreDeinit (
 273   IN XENBUS_DEVICE  *Dev
 274   );
 275
 276 //
 277 // XENBUS protocol
 278 //
 279
 280 XENSTORE_STATUS
 281 EFIAPI
 282 XenBusWaitForWatch (
 283   IN XENBUS_PROTOCOL  *This,
 284   IN VOID             *Token
 285   );
 286
 287 XENSTORE_STATUS
 288 EFIAPI
 289 XenBusXenStoreRead (
 290   IN  XENBUS_PROTOCOL             *This,
 291   IN  CONST XENSTORE_TRANSACTION  *Transaction,
 292   IN  CONST CHAR8                 *Node,
 293   OUT VOID                        **Value
 294   );
 295
 296 XENSTORE_STATUS
 297 EFIAPI
 298 XenBusXenStoreBackendRead (
 299   IN  XENBUS_PROTOCOL             *This,
 300   IN  CONST XENSTORE_TRANSACTION  *Transaction,
 301   IN  CONST CHAR8                 *Node,
 302   OUT VOID                        **Value
 303   );
 304
 305 XENSTORE_STATUS
 306 EFIAPI
 307 XenBusXenStoreRemove (
 308   IN XENBUS_PROTOCOL             *This,
 309   IN CONST XENSTORE_TRANSACTION  *Transaction,
 310   IN CONST CHAR8                 *Node
 311   );
 312
 313 XENSTORE_STATUS
 314 EFIAPI
 315 XenBusXenStoreTransactionStart (
 316   IN  XENBUS_PROTOCOL       *This,
 317   OUT XENSTORE_TRANSACTION  *Transaction
 318   );
 319
 320 XENSTORE_STATUS
 321 EFIAPI
 322 XenBusXenStoreTransactionEnd (
 323   IN XENBUS_PROTOCOL             *This,
 324   IN CONST XENSTORE_TRANSACTION  *Transaction,
 325   IN BOOLEAN                     Abort
 326   );
 327
 328 XENSTORE_STATUS
 329 EFIAPI
 330 XenBusXenStoreSPrint (
 331   IN XENBUS_PROTOCOL             *This,
 332   IN CONST XENSTORE_TRANSACTION  *Transaction,
 333   IN CONST CHAR8                 *DirectoryPath,
 334   IN CONST CHAR8                 *Node,
 335   IN CONST CHAR8                 *FormatString,
 336   ...
 337   );
 338
 339 XENSTORE_STATUS
 340 EFIAPI
 341 XenBusRegisterWatch (
 342   IN  XENBUS_PROTOCOL  *This,
 343   IN  CONST CHAR8      *Node,
 344   OUT VOID             **Token
 345   );
 346
 347 XENSTORE_STATUS
 348 EFIAPI
 349 XenBusRegisterWatchBackend (
 350   IN  XENBUS_PROTOCOL  *This,
 351   IN  CONST CHAR8      *Node,
 352   OUT VOID             **Token
 353   );
 354
 355 VOID
 356 EFIAPI
 357 XenBusUnregisterWatch (
 358   IN XENBUS_PROTOCOL  *This,
 359   IN VOID             *Token
 360   );
 361
 362 #endif /* _XEN_XENSTORE_XENSTOREVAR_H */