3 XenBus protocol to be used between the XenBus bus driver and Xen PV devices.
5 DISCLAIMER: the XENBUS_PROTOCOL introduced here is a work in progress, and
6 should not be used outside of the EDK II tree.
8 This protocol provide the necessary for a Xen PV driver frontend to
9 communicate with the bus driver, and perform several task to
10 initialize/shutdown a PV device and perform IO with a PV backend.
12 Copyright (C) 2014, Citrix Ltd.
14 This program and the accompanying materials
15 are licensed and made available under the terms and conditions of the BSD License
16 which accompanies this distribution. The full text of the license may be found at
17 http://opensource.org/licenses/bsd-license.php
19 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
20 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
24 #ifndef __PROTOCOL_XENBUS_H__
25 #define __PROTOCOL_XENBUS_H__
27 #define XENBUS_PROTOCOL_GUID \
28 {0x3d3ca290, 0xb9a5, 0x11e3, {0xb7, 0x5d, 0xb8, 0xac, 0x6f, 0x7d, 0x65, 0xe6}}
31 /// Forward declaration
33 typedef struct _XENBUS_PROTOCOL XENBUS_PROTOCOL
;
35 typedef enum xenbus_state XenBusState
;
40 } XENSTORE_TRANSACTION
;
42 #define XST_NIL ((XENSTORE_TRANSACTION) { 0 })
45 XENSTORE_STATUS_SUCCESS
= 0,
47 XENSTORE_STATUS_EINVAL
,
48 XENSTORE_STATUS_EACCES
,
49 XENSTORE_STATUS_EEXIST
,
50 XENSTORE_STATUS_EISDIR
,
51 XENSTORE_STATUS_ENOENT
,
52 XENSTORE_STATUS_ENOMEM
,
53 XENSTORE_STATUS_ENOSPC
,
55 XENSTORE_STATUS_ENOTEMPTY
,
56 XENSTORE_STATUS_ENOSYS
,
57 XENSTORE_STATUS_EROFS
,
58 XENSTORE_STATUS_EBUSY
,
59 XENSTORE_STATUS_EAGAIN
,
60 XENSTORE_STATUS_EISCONN
,
65 #include <IndustryStandard/Xen/grant_table.h>
68 /// Function prototypes
72 Get the contents of the node Node of the PV device. Returns the contents in
73 *Result which should be freed after use.
75 @param This A pointer to XENBUS_PROTOCOL instance.
76 @param Transaction The XenStore transaction covering this request.
77 @param Node The basename of the file to read.
78 @param Result The returned contents from this file.
80 @return On success, XENSTORE_STATUS_SUCCESS. Otherwise an errno value
81 indicating the type of failure.
83 @note The results buffer is malloced and should be free'd by the
88 (EFIAPI
*XENBUS_XS_READ
)(
89 IN XENBUS_PROTOCOL
*This
,
90 IN XENSTORE_TRANSACTION Transaction
,
96 Get the contents of the node Node of the PV device's backend. Returns the
97 contents in *Result which should be freed after use.
99 @param This A pointer to XENBUS_PROTOCOL instance.
100 @param Transaction The XenStore transaction covering this request.
101 @param Node The basename of the file to read.
102 @param Result The returned contents from this file.
104 @return On success, XENSTORE_STATUS_SUCCESS. Otherwise an errno value
105 indicating the type of failure.
107 @note The results buffer is malloced and should be free'd by the
112 (EFIAPI
*XENBUS_XS_BACKEND_READ
)(
113 IN XENBUS_PROTOCOL
*This
,
114 IN XENSTORE_TRANSACTION Transaction
,
115 IN CONST CHAR8
*Node
,
120 Print formatted write to a XenStore node.
122 @param This A pointer to XENBUS_PROTOCOL instance.
123 @param Transaction The XenStore transaction covering this request.
124 @param Directory The dirname of the path to read.
125 @param Node The basename of the path to read.
126 @param Format AsciiSPrint format string followed by a variable number
129 @return On success, XENSTORE_STATUS_SUCCESS. Otherwise an errno value
130 indicating the type of write failure.
134 (EFIAPI
*XENBUS_XS_PRINTF
) (
135 IN XENBUS_PROTOCOL
*This
,
136 IN XENSTORE_TRANSACTION Transaction
,
137 IN CONST CHAR8
*Directory
,
138 IN CONST CHAR8
*Node
,
139 IN CONST CHAR8
*Format
,
144 Remove a node or directory (directories must be empty) of the PV driver's
147 @param This A pointer to XENBUS_PROTOCOL instance.
148 @param Transaction The XenStore transaction covering this request.
149 @param Node The basename of the node to remove.
151 @return On success, XENSTORE_STATUS_SUCCESS. Otherwise an errno value
152 indicating the type of failure.
156 (EFIAPI
*XENBUS_XS_REMOVE
) (
157 IN XENBUS_PROTOCOL
*This
,
158 IN XENSTORE_TRANSACTION Transaction
,
165 Changes by others will not be seen during the lifetime of this
166 transaction, and changes will not be visible to others until it
167 is committed (XsTransactionEnd).
169 @param This A pointer to XENBUS_PROTOCOL instance.
170 @param Transaction The returned transaction.
172 @return On success, XENSTORE_STATUS_SUCCESS. Otherwise an errno value
173 indicating the type of failure.
177 (EFIAPI
*XENBUS_XS_TRANSACTION_START
)(
178 IN XENBUS_PROTOCOL
*This
,
179 OUT XENSTORE_TRANSACTION
*Transaction
185 @param This A pointer to XENBUS_PROTOCOL instance.
186 @param Transaction The transaction to end/commit.
187 @param Abort If TRUE, the transaction is discarded
188 instead of committed.
190 @return On success, XENSTORE_STATUS_SUCCESS. Otherwise an errno value
191 indicating the type of failure.
195 (EFIAPI
*XENBUS_XS_TRANSACTION_END
) (
196 IN XENBUS_PROTOCOL
*This
,
197 IN XENSTORE_TRANSACTION Transaction
,
202 Set a new state for the frontend of the PV driver.
204 @param This A pointer to XENBUS_PROTOCOL instance.
205 @param Transaction The transaction to end/commit.
206 @param State The new state to apply.
208 @return On success, XENSTORE_STATUS_SUCCESS. Otherwise an errno value
209 indicating the type of failure.
213 (EFIAPI
*XENBUS_SET_STATE
)(
214 IN XENBUS_PROTOCOL
*This
,
215 IN XENSTORE_TRANSACTION Transaction
,
220 Grant access to the page Frame to the domain DomainId.
222 @param This A pointer to XENBUS_PROTOCOL instance.
223 @param DomainId ID of the domain to grant acces to.
224 @param Frame Frame Number of the page to grant access to.
225 @param ReadOnly Provide read-only or read-write access.
226 @param RefPtr Reference number of the grant will be writen to this pointer.
230 (EFIAPI
*XENBUS_GRANT_ACCESS
)(
231 IN XENBUS_PROTOCOL
*This
,
235 OUT grant_ref_t
*refp
239 End access to grant Ref, previously return by XenBusGrantAccess.
241 @param This A pointer to XENBUS_PROTOCOL instance.
242 @param Ref Reference numeber of a grant previously returned by
247 (EFIAPI
*XENBUS_GRANT_END_ACCESS
)(
248 IN XENBUS_PROTOCOL
*This
,
253 Register a XenStore watch.
255 XenStore watches allow a client to wait for changes to an object in the
258 @param This A pointer to the XENBUS_PROTOCOL.
259 @param Node The basename of the path to watch.
260 @param Token A token.
262 @return On success, XENSTORE_STATUS_SUCCESS. Otherwise an errno value
263 indicating the type of write failure. EEXIST errors from the
264 XenStore are supressed, allowing multiple, physically different,
265 xenbus_watch objects, to watch the same path in the XenStore.
269 (EFIAPI
*XENBUS_REGISTER_WATCH
) (
270 IN XENBUS_PROTOCOL
*This
,
271 IN CONST CHAR8
*Node
,
276 Register a XenStore watch on a backend's node.
278 XenStore watches allow a client to wait for changes to an object in the
281 @param This A pointer to the XENBUS_PROTOCOL.
282 @param Node The basename of the path to watch.
283 @param Token A token.
285 @return On success, XENSTORE_STATUS_SUCCESS. Otherwise an errno value
286 indicating the type of write failure. EEXIST errors from the
287 XenStore are supressed, allowing multiple, physically different,
288 xenbus_watch objects, to watch the same path in the XenStore.
292 (EFIAPI
*XENBUS_REGISTER_WATCH_BACKEND
) (
293 IN XENBUS_PROTOCOL
*This
,
294 IN CONST CHAR8
*Node
,
299 Unregister a XenStore watch.
301 @param This A pointer to the XENBUS_PROTOCOL.
302 @param Token An token previously returned by a successful
303 call to RegisterWatch ().
307 (EFIAPI
*XENBUS_UNREGISTER_WATCH
) (
308 IN XENBUS_PROTOCOL
*This
,
313 Block until the node watch by Token change.
315 @param This A pointer to the XENBUS_PROTOCOL.
316 @param Token An token previously returned by a successful
317 call to RegisterWatch or RegisterWatchBackend.
319 @return On success, XENSTORE_STATUS_SUCCESS. Otherwise an errno value
320 indicating the type of failure.
324 (EFIAPI
*XENBUS_WAIT_FOR_WATCH
) (
325 IN XENBUS_PROTOCOL
*This
,
331 /// Protocol structure
333 /// DISCLAIMER: the XENBUS_PROTOCOL introduced here is a work in progress, and
334 /// should not be used outside of the EDK II tree.
336 struct _XENBUS_PROTOCOL
{
337 XENBUS_XS_READ XsRead
;
338 XENBUS_XS_BACKEND_READ XsBackendRead
;
339 XENBUS_XS_PRINTF XsPrintf
;
340 XENBUS_XS_REMOVE XsRemove
;
341 XENBUS_XS_TRANSACTION_START XsTransactionStart
;
342 XENBUS_XS_TRANSACTION_END XsTransactionEnd
;
343 XENBUS_SET_STATE SetState
;
345 XENBUS_GRANT_ACCESS GrantAccess
;
346 XENBUS_GRANT_END_ACCESS GrantEndAccess
;
348 XENBUS_REGISTER_WATCH RegisterWatch
;
349 XENBUS_REGISTER_WATCH_BACKEND RegisterWatchBackend
;
350 XENBUS_UNREGISTER_WATCH UnregisterWatch
;
351 XENBUS_WAIT_FOR_WATCH WaitForWatch
;
353 // Protocol data fields
358 CONST CHAR8
*Backend
;
361 extern EFI_GUID gXenBusProtocolGuid
;