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 /**
 256   Initialize the XenStore states and rings.
 257
 258   @param Dev  A pointer to a XENBUS_DEVICE instance.
 259
 260   @return     EFI_SUCCESS if everything went smoothly.
 261 **/
 262 EFI_STATUS
 263 XenStoreInit (
 264   XENBUS_DEVICE *Dev
 265   );
 266
 267 /**
 268   Deinitialize the XenStore states and rings.
 269
 270   @param Dev  A pointer to a XENBUS_DEVICE instance.
 271 **/
 272 VOID
 273 XenStoreDeinit (
 274   IN XENBUS_DEVICE *Dev
 275   );
 276
 277
 278 //
 279 // XENBUS protocol
 280 //
 281
 282 XENSTORE_STATUS
 283 EFIAPI
 284 XenBusWaitForWatch (
 285   IN XENBUS_PROTOCOL *This,
 286   IN VOID *Token
 287   );
 288
 289 XENSTORE_STATUS
 290 EFIAPI
 291 XenBusXenStoreRead (
 292   IN  XENBUS_PROTOCOL       *This,
 293   IN  CONST XENSTORE_TRANSACTION *Transaction,
 294   IN  CONST CHAR8           *Node,
 295   OUT VOID                  **Value
 296   );
 297
 298 XENSTORE_STATUS
 299 EFIAPI
 300 XenBusXenStoreBackendRead (
 301   IN  XENBUS_PROTOCOL       *This,
 302   IN  CONST XENSTORE_TRANSACTION *Transaction,
 303   IN  CONST CHAR8           *Node,
 304   OUT VOID                  **Value
 305   );
 306
 307 XENSTORE_STATUS
 308 EFIAPI
 309 XenBusXenStoreRemove (
 310   IN XENBUS_PROTOCOL        *This,
 311   IN CONST XENSTORE_TRANSACTION *Transaction,
 312   IN CONST CHAR8            *Node
 313   );
 314
 315 XENSTORE_STATUS
 316 EFIAPI
 317 XenBusXenStoreTransactionStart (
 318   IN  XENBUS_PROTOCOL       *This,
 319   OUT XENSTORE_TRANSACTION  *Transaction
 320   );
 321
 322 XENSTORE_STATUS
 323 EFIAPI
 324 XenBusXenStoreTransactionEnd (
 325   IN XENBUS_PROTOCOL        *This,
 326   IN CONST XENSTORE_TRANSACTION *Transaction,
 327   IN BOOLEAN                Abort
 328   );
 329
 330 XENSTORE_STATUS
 331 EFIAPI
 332 XenBusXenStoreSPrint (
 333   IN XENBUS_PROTOCOL        *This,
 334   IN CONST XENSTORE_TRANSACTION *Transaction,
 335   IN CONST CHAR8            *DirectoryPath,
 336   IN CONST CHAR8            *Node,
 337   IN CONST CHAR8            *FormatString,
 338   ...
 339   );
 340
 341 XENSTORE_STATUS
 342 EFIAPI
 343 XenBusRegisterWatch (
 344   IN  XENBUS_PROTOCOL *This,
 345   IN  CONST CHAR8     *Node,
 346   OUT VOID            **Token
 347   );
 348
 349 XENSTORE_STATUS
 350 EFIAPI
 351 XenBusRegisterWatchBackend (
 352   IN  XENBUS_PROTOCOL *This,
 353   IN  CONST CHAR8     *Node,
 354   OUT VOID            **Token
 355   );
 356
 357 VOID
 358 EFIAPI
 359 XenBusUnregisterWatch (
 360   IN XENBUS_PROTOCOL  *This,
 361   IN VOID             *Token
 362   );
 363
 364 #endif /* _XEN_XENSTORE_XENSTOREVAR_H */