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 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 
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