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  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 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  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 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 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 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 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 XenStoreVSPrint (
 213   IN XENSTORE_TRANSACTION  Transaction,
 214   IN CONST CHAR8           *DirectoryPath,
 215   IN CONST CHAR8           *Node,
 216   IN CONST CHAR8           *FormatString,
 217   IN VA_LIST               Marker
 218   );
 219
 220 /**
 221   Register a XenStore watch.
 222
 223   XenStore watches allow a client to be notified via a callback (embedded
 224   within the watch object) of changes to an object in the XenStore.
 225
 226   @param DirectoryPath  The dirname of the path to watch.
 227   @param Node           The basename of the path to watch.
 228   @param WatchPtr       A returned XENSTORE_WATCH pointer.
 229
 230   @return  On success, XENSTORE_STATUS_SUCCESS. Otherwise an errno value
 231            indicating the type of write failure.  EEXIST errors from the
 232            XenStore are supressed, allowing multiple, physically different,
 233            xenbus_watch objects, to watch the same path in the XenStore.
 234 **/
 235 XENSTORE_STATUS
 236 XenStoreRegisterWatch (
 237   IN  CONST CHAR8     *DirectoryPath,
 238   IN  CONST CHAR8     *Node,
 239   OUT XENSTORE_WATCH  **WatchPtr
 240   );
 241
 242 /**
 243   Unregister a XenStore watch.
 244
 245   @param Watch  An XENSTORE_WATCH object previously returned by a successful
 246                 call to XenStoreRegisterWatch ().
 247 **/
 248 VOID
 249 XenStoreUnregisterWatch (
 250   IN XENSTORE_WATCH *Watch
 251   );
 252
 253 /**
 254   Allocate and return the XenStore path string <DirectoryPath>/<Node>.  If name
 255   is the NUL string, the returned value contains the path string
 256   <DirectoryPath>.
 257
 258   @param DirectoryPath  The NUL terminated directory prefix for new path.
 259   @param Node           The NUL terminated basename for the new path.
 260
 261   @return  A buffer containing the joined path.
 262  */
 263 CHAR8 *
 264 XenStoreJoin (
 265   IN CONST CHAR8 *DirectoryPath,
 266   IN CONST CHAR8 *Node
 267   );
 268
 269
 270 /**
 271   Initialize the XenStore states and rings.
 272
 273   @param Dev  A pointer to a XENBUS_DEVICE instance.
 274
 275   @return     EFI_SUCCESS if everything went smoothly.
 276 **/
 277 EFI_STATUS
 278 XenStoreInit (
 279   XENBUS_DEVICE *Dev
 280   );
 281
 282 /**
 283   Deinitialize the XenStore states and rings.
 284
 285   @param Dev  A pointer to a XENBUS_DEVICE instance.
 286 **/
 287 VOID
 288 XenStoreDeinit (
 289   IN XENBUS_DEVICE *Dev
 290   );
 291
 292 #endif /* _XEN_XENSTORE_XENSTOREVAR_H */