OvmfPkg/XenBusDxe: Add XenStore function into the XenBus protocol
[mirror_edk2.git] / OvmfPkg / Include / Protocol / XenBus.h
CommitLineData
12a16f2d
AP
1\r
2/** @file\r
3 XenBus protocol to be used between the XenBus bus driver and Xen PV devices.\r
4\r
5 DISCLAIMER: the XENBUS_PROTOCOL introduced here is a work in progress, and\r
6 should not be used outside of the EDK II tree.\r
7\r
8 This protocol provide the necessary for a Xen PV driver frontend to\r
9 communicate with the bus driver, and perform several task to\r
10 initialize/shutdown a PV device and perform IO with a PV backend.\r
11\r
12 Copyright (C) 2014, Citrix Ltd.\r
13\r
14 This program and the accompanying materials\r
15 are licensed and made available under the terms and conditions of the BSD License\r
16 which accompanies this distribution. The full text of the license may be found at\r
17 http://opensource.org/licenses/bsd-license.php\r
18\r
19 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,\r
20 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.\r
21\r
22**/\r
23\r
24#ifndef __PROTOCOL_XENBUS_H__\r
25#define __PROTOCOL_XENBUS_H__\r
26\r
27#define XENBUS_PROTOCOL_GUID \\r
28 {0x3d3ca290, 0xb9a5, 0x11e3, {0xb7, 0x5d, 0xb8, 0xac, 0x6f, 0x7d, 0x65, 0xe6}}\r
29\r
30///\r
31/// Forward declaration\r
32///\r
33typedef struct _XENBUS_PROTOCOL XENBUS_PROTOCOL;\r
34\r
a9090a94
AP
35typedef enum xenbus_state XenBusState;\r
36\r
37typedef struct\r
38{\r
39 UINT32 Id;\r
40} XENSTORE_TRANSACTION;\r
41\r
42#define XST_NIL ((XENSTORE_TRANSACTION) { 0 })\r
43\r
44typedef enum {\r
45 XENSTORE_STATUS_SUCCESS = 0,\r
46 XENSTORE_STATUS_FAIL,\r
47 XENSTORE_STATUS_EINVAL,\r
48 XENSTORE_STATUS_EACCES,\r
49 XENSTORE_STATUS_EEXIST,\r
50 XENSTORE_STATUS_EISDIR,\r
51 XENSTORE_STATUS_ENOENT,\r
52 XENSTORE_STATUS_ENOMEM,\r
53 XENSTORE_STATUS_ENOSPC,\r
54 XENSTORE_STATUS_EIO,\r
55 XENSTORE_STATUS_ENOTEMPTY,\r
56 XENSTORE_STATUS_ENOSYS,\r
57 XENSTORE_STATUS_EROFS,\r
58 XENSTORE_STATUS_EBUSY,\r
59 XENSTORE_STATUS_EAGAIN,\r
60 XENSTORE_STATUS_EISCONN,\r
61 XENSTORE_STATUS_E2BIG\r
62} XENSTORE_STATUS;\r
63\r
12a16f2d
AP
64\r
65#include <IndustryStandard/Xen/grant_table.h>\r
66\r
67///\r
68/// Function prototypes\r
69///\r
70\r
c23c037f
AP
71/**\r
72 Get the contents of the node Node of the PV device. Returns the contents in\r
73 *Result which should be freed after use.\r
74\r
75 @param This A pointer to XENBUS_PROTOCOL instance.\r
76 @param Transaction The XenStore transaction covering this request.\r
77 @param Node The basename of the file to read.\r
78 @param Result The returned contents from this file.\r
79\r
80 @return On success, XENSTORE_STATUS_SUCCESS. Otherwise an errno value\r
81 indicating the type of failure.\r
82\r
83 @note The results buffer is malloced and should be free'd by the\r
84 caller.\r
85**/\r
86typedef\r
87XENSTORE_STATUS\r
88(EFIAPI *XENBUS_XS_READ)(\r
89 IN XENBUS_PROTOCOL *This,\r
90 IN XENSTORE_TRANSACTION Transaction,\r
91 IN CONST CHAR8 *Node,\r
92 OUT VOID **Result\r
93 );\r
94\r
95/**\r
96 Get the contents of the node Node of the PV device's backend. Returns the\r
97 contents in *Result which should be freed after use.\r
98\r
99 @param This A pointer to XENBUS_PROTOCOL instance.\r
100 @param Transaction The XenStore transaction covering this request.\r
101 @param Node The basename of the file to read.\r
102 @param Result The returned contents from this file.\r
103\r
104 @return On success, XENSTORE_STATUS_SUCCESS. Otherwise an errno value\r
105 indicating the type of failure.\r
106\r
107 @note The results buffer is malloced and should be free'd by the\r
108 caller.\r
109**/\r
110typedef\r
111XENSTORE_STATUS\r
112(EFIAPI *XENBUS_XS_BACKEND_READ)(\r
113 IN XENBUS_PROTOCOL *This,\r
114 IN XENSTORE_TRANSACTION Transaction,\r
115 IN CONST CHAR8 *Node,\r
116 OUT VOID **Result\r
117 );\r
118\r
119/**\r
120 Print formatted write to a XenStore node.\r
121\r
122 @param This A pointer to XENBUS_PROTOCOL instance.\r
123 @param Transaction The XenStore transaction covering this request.\r
124 @param Directory The dirname of the path to read.\r
125 @param Node The basename of the path to read.\r
126 @param Format AsciiSPrint format string followed by a variable number\r
127 of arguments.\r
128\r
129 @return On success, XENSTORE_STATUS_SUCCESS. Otherwise an errno value\r
130 indicating the type of write failure.\r
131**/\r
132typedef\r
133XENSTORE_STATUS\r
134(EFIAPI *XENBUS_XS_PRINTF) (\r
135 IN XENBUS_PROTOCOL *This,\r
136 IN XENSTORE_TRANSACTION Transaction,\r
137 IN CONST CHAR8 *Directory,\r
138 IN CONST CHAR8 *Node,\r
139 IN CONST CHAR8 *Format,\r
140 ...\r
141 );\r
142\r
143/**\r
144 Remove a node or directory (directories must be empty) of the PV driver's\r
145 subdirectory.\r
146\r
147 @param This A pointer to XENBUS_PROTOCOL instance.\r
148 @param Transaction The XenStore transaction covering this request.\r
149 @param Node The basename of the node to remove.\r
150\r
151 @return On success, XENSTORE_STATUS_SUCCESS. Otherwise an errno value\r
152 indicating the type of failure.\r
153**/\r
154typedef\r
155XENSTORE_STATUS\r
156(EFIAPI *XENBUS_XS_REMOVE) (\r
157 IN XENBUS_PROTOCOL *This,\r
158 IN XENSTORE_TRANSACTION Transaction,\r
159 IN CONST CHAR8 *Node\r
160 );\r
161\r
162/**\r
163 Start a transaction.\r
164\r
165 Changes by others will not be seen during the lifetime of this\r
166 transaction, and changes will not be visible to others until it\r
167 is committed (XsTransactionEnd).\r
168\r
169 @param This A pointer to XENBUS_PROTOCOL instance.\r
170 @param Transaction The returned transaction.\r
171\r
172 @return On success, XENSTORE_STATUS_SUCCESS. Otherwise an errno value\r
173 indicating the type of failure.\r
174**/\r
175typedef\r
176XENSTORE_STATUS\r
177(EFIAPI *XENBUS_XS_TRANSACTION_START)(\r
178 IN XENBUS_PROTOCOL *This,\r
179 OUT XENSTORE_TRANSACTION *Transaction\r
180 );\r
181\r
182/**\r
183 End a transaction.\r
184\r
185 @param This A pointer to XENBUS_PROTOCOL instance.\r
186 @param Transaction The transaction to end/commit.\r
187 @param Abort If TRUE, the transaction is discarded\r
188 instead of committed.\r
189\r
190 @return On success, XENSTORE_STATUS_SUCCESS. Otherwise an errno value\r
191 indicating the type of failure.\r
192**/\r
193typedef\r
194XENSTORE_STATUS\r
195(EFIAPI *XENBUS_XS_TRANSACTION_END) (\r
196 IN XENBUS_PROTOCOL *This,\r
197 IN XENSTORE_TRANSACTION Transaction,\r
198 IN BOOLEAN Abort\r
199 );\r
200\r
12a16f2d
AP
201/**\r
202 Grant access to the page Frame to the domain DomainId.\r
203\r
204 @param This A pointer to XENBUS_PROTOCOL instance.\r
205 @param DomainId ID of the domain to grant acces to.\r
206 @param Frame Frame Number of the page to grant access to.\r
207 @param ReadOnly Provide read-only or read-write access.\r
208 @param RefPtr Reference number of the grant will be writen to this pointer.\r
209**/\r
210typedef\r
211EFI_STATUS\r
212(EFIAPI *XENBUS_GRANT_ACCESS)(\r
213 IN XENBUS_PROTOCOL *This,\r
214 IN domid_t DomainId,\r
215 IN UINTN Frame,\r
216 IN BOOLEAN ReadOnly,\r
217 OUT grant_ref_t *refp\r
218 );\r
219\r
220/**\r
221 End access to grant Ref, previously return by XenBusGrantAccess.\r
222\r
223 @param This A pointer to XENBUS_PROTOCOL instance.\r
224 @param Ref Reference numeber of a grant previously returned by\r
225 XenBusGrantAccess.\r
226**/\r
227typedef\r
228EFI_STATUS\r
229(EFIAPI *XENBUS_GRANT_END_ACCESS)(\r
230 IN XENBUS_PROTOCOL *This,\r
231 IN grant_ref_t Ref\r
232 );\r
233\r
c23c037f
AP
234/**\r
235 Register a XenStore watch.\r
236\r
237 XenStore watches allow a client to wait for changes to an object in the\r
238 XenStore.\r
239\r
240 @param This A pointer to the XENBUS_PROTOCOL.\r
241 @param Node The basename of the path to watch.\r
242 @param Token A token.\r
243\r
244 @return On success, XENSTORE_STATUS_SUCCESS. Otherwise an errno value\r
245 indicating the type of write failure. EEXIST errors from the\r
246 XenStore are supressed, allowing multiple, physically different,\r
247 xenbus_watch objects, to watch the same path in the XenStore.\r
248**/\r
249typedef\r
250XENSTORE_STATUS\r
251(EFIAPI *XENBUS_REGISTER_WATCH) (\r
252 IN XENBUS_PROTOCOL *This,\r
253 IN CONST CHAR8 *Node,\r
254 OUT VOID **Token\r
255 );\r
256\r
257/**\r
258 Register a XenStore watch on a backend's node.\r
259\r
260 XenStore watches allow a client to wait for changes to an object in the\r
261 XenStore.\r
262\r
263 @param This A pointer to the XENBUS_PROTOCOL.\r
264 @param Node The basename of the path to watch.\r
265 @param Token A token.\r
266\r
267 @return On success, XENSTORE_STATUS_SUCCESS. Otherwise an errno value\r
268 indicating the type of write failure. EEXIST errors from the\r
269 XenStore are supressed, allowing multiple, physically different,\r
270 xenbus_watch objects, to watch the same path in the XenStore.\r
271**/\r
272typedef\r
273XENSTORE_STATUS\r
274(EFIAPI *XENBUS_REGISTER_WATCH_BACKEND) (\r
275 IN XENBUS_PROTOCOL *This,\r
276 IN CONST CHAR8 *Node,\r
277 OUT VOID **Token\r
278 );\r
279\r
280/**\r
281 Unregister a XenStore watch.\r
282\r
283 @param This A pointer to the XENBUS_PROTOCOL.\r
284 @param Token An token previously returned by a successful\r
285 call to RegisterWatch ().\r
286**/\r
287typedef\r
288VOID\r
289(EFIAPI *XENBUS_UNREGISTER_WATCH) (\r
290 IN XENBUS_PROTOCOL *This,\r
291 IN VOID *Token\r
292 );\r
293\r
294/**\r
295 Block until the node watch by Token change.\r
296\r
297 @param This A pointer to the XENBUS_PROTOCOL.\r
298 @param Token An token previously returned by a successful\r
299 call to RegisterWatch or RegisterWatchBackend.\r
300\r
301 @return On success, XENSTORE_STATUS_SUCCESS. Otherwise an errno value\r
302 indicating the type of failure.\r
303**/\r
304typedef\r
305XENSTORE_STATUS\r
306(EFIAPI *XENBUS_WAIT_FOR_WATCH) (\r
307 IN XENBUS_PROTOCOL *This,\r
308 IN VOID *Token\r
309 );\r
310\r
12a16f2d
AP
311\r
312///\r
313/// Protocol structure\r
314///\r
315/// DISCLAIMER: the XENBUS_PROTOCOL introduced here is a work in progress, and\r
316/// should not be used outside of the EDK II tree.\r
317///\r
318struct _XENBUS_PROTOCOL {\r
c23c037f
AP
319 XENBUS_XS_READ XsRead;\r
320 XENBUS_XS_BACKEND_READ XsBackendRead;\r
321 XENBUS_XS_PRINTF XsPrintf;\r
322 XENBUS_XS_REMOVE XsRemove;\r
323 XENBUS_XS_TRANSACTION_START XsTransactionStart;\r
324 XENBUS_XS_TRANSACTION_END XsTransactionEnd;\r
325\r
12a16f2d
AP
326 XENBUS_GRANT_ACCESS GrantAccess;\r
327 XENBUS_GRANT_END_ACCESS GrantEndAccess;\r
c23c037f
AP
328\r
329 XENBUS_REGISTER_WATCH RegisterWatch;\r
330 XENBUS_REGISTER_WATCH_BACKEND RegisterWatchBackend;\r
331 XENBUS_UNREGISTER_WATCH UnregisterWatch;\r
332 XENBUS_WAIT_FOR_WATCH WaitForWatch;\r
12a16f2d
AP
333 //\r
334 // Protocol data fields\r
335 //\r
c23c037f
AP
336 CONST CHAR8 *Type;\r
337 UINT16 DeviceId;\r
338 CONST CHAR8 *Node;\r
339 CONST CHAR8 *Backend;\r
12a16f2d
AP
340};\r
341\r
342extern EFI_GUID gXenBusProtocolGuid;\r
343\r
344#endif\r