XenStore.h 10 KB

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