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 XenStoreVSPrint ( 213 IN CONST 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 suppressed, 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 293 // 294 // XENBUS protocol 295 // 296 297 XENSTORE_STATUS 298 EFIAPI 299 XenBusWaitForWatch ( 300 IN XENBUS_PROTOCOL *This, 301 IN VOID *Token 302 ); 303 304 XENSTORE_STATUS 305 EFIAPI 306 XenBusXenStoreRead ( 307 IN XENBUS_PROTOCOL *This, 308 IN CONST XENSTORE_TRANSACTION *Transaction, 309 IN CONST CHAR8 *Node, 310 OUT VOID **Value 311 ); 312 313 XENSTORE_STATUS 314 EFIAPI 315 XenBusXenStoreBackendRead ( 316 IN XENBUS_PROTOCOL *This, 317 IN CONST XENSTORE_TRANSACTION *Transaction, 318 IN CONST CHAR8 *Node, 319 OUT VOID **Value 320 ); 321 322 XENSTORE_STATUS 323 EFIAPI 324 XenBusXenStoreRemove ( 325 IN XENBUS_PROTOCOL *This, 326 IN CONST XENSTORE_TRANSACTION *Transaction, 327 IN CONST CHAR8 *Node 328 ); 329 330 XENSTORE_STATUS 331 EFIAPI 332 XenBusXenStoreTransactionStart ( 333 IN XENBUS_PROTOCOL *This, 334 OUT XENSTORE_TRANSACTION *Transaction 335 ); 336 337 XENSTORE_STATUS 338 EFIAPI 339 XenBusXenStoreTransactionEnd ( 340 IN XENBUS_PROTOCOL *This, 341 IN CONST XENSTORE_TRANSACTION *Transaction, 342 IN BOOLEAN Abort 343 ); 344 345 XENSTORE_STATUS 346 EFIAPI 347 XenBusXenStoreSPrint ( 348 IN XENBUS_PROTOCOL *This, 349 IN CONST XENSTORE_TRANSACTION *Transaction, 350 IN CONST CHAR8 *DirectoryPath, 351 IN CONST CHAR8 *Node, 352 IN CONST CHAR8 *FormatString, 353 ... 354 ); 355 356 XENSTORE_STATUS 357 EFIAPI 358 XenBusRegisterWatch ( 359 IN XENBUS_PROTOCOL *This, 360 IN CONST CHAR8 *Node, 361 OUT VOID **Token 362 ); 363 364 XENSTORE_STATUS 365 EFIAPI 366 XenBusRegisterWatchBackend ( 367 IN XENBUS_PROTOCOL *This, 368 IN CONST CHAR8 *Node, 369 OUT VOID **Token 370 ); 371 372 VOID 373 EFIAPI 374 XenBusUnregisterWatch ( 375 IN XENBUS_PROTOCOL *This, 376 IN VOID *Token 377 ); 378 379 #endif /* _XEN_XENSTORE_XENSTOREVAR_H */ 380