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 Grant access to the page Frame to the domain DomainId.
204 @param This A pointer to XENBUS_PROTOCOL instance.
205 @param DomainId ID of the domain to grant acces to.
206 @param Frame Frame Number of the page to grant access to.
207 @param ReadOnly Provide read-only or read-write access.
208 @param RefPtr Reference number of the grant will be writen to this pointer.
212 (EFIAPI
*XENBUS_GRANT_ACCESS
)(
213 IN XENBUS_PROTOCOL
*This
,
217 OUT grant_ref_t
*refp
221 End access to grant Ref, previously return by XenBusGrantAccess.
223 @param This A pointer to XENBUS_PROTOCOL instance.
224 @param Ref Reference numeber of a grant previously returned by
229 (EFIAPI
*XENBUS_GRANT_END_ACCESS
)(
230 IN XENBUS_PROTOCOL
*This
,
235 Register a XenStore watch.
237 XenStore watches allow a client to wait for changes to an object in the
240 @param This A pointer to the XENBUS_PROTOCOL.
241 @param Node The basename of the path to watch.
242 @param Token A token.
244 @return On success, XENSTORE_STATUS_SUCCESS. Otherwise an errno value
245 indicating the type of write failure. EEXIST errors from the
246 XenStore are supressed, allowing multiple, physically different,
247 xenbus_watch objects, to watch the same path in the XenStore.
251 (EFIAPI
*XENBUS_REGISTER_WATCH
) (
252 IN XENBUS_PROTOCOL
*This
,
253 IN CONST CHAR8
*Node
,
258 Register a XenStore watch on a backend's node.
260 XenStore watches allow a client to wait for changes to an object in the
263 @param This A pointer to the XENBUS_PROTOCOL.
264 @param Node The basename of the path to watch.
265 @param Token A token.
267 @return On success, XENSTORE_STATUS_SUCCESS. Otherwise an errno value
268 indicating the type of write failure. EEXIST errors from the
269 XenStore are supressed, allowing multiple, physically different,
270 xenbus_watch objects, to watch the same path in the XenStore.
274 (EFIAPI
*XENBUS_REGISTER_WATCH_BACKEND
) (
275 IN XENBUS_PROTOCOL
*This
,
276 IN CONST CHAR8
*Node
,
281 Unregister a XenStore watch.
283 @param This A pointer to the XENBUS_PROTOCOL.
284 @param Token An token previously returned by a successful
285 call to RegisterWatch ().
289 (EFIAPI
*XENBUS_UNREGISTER_WATCH
) (
290 IN XENBUS_PROTOCOL
*This
,
295 Block until the node watch by Token change.
297 @param This A pointer to the XENBUS_PROTOCOL.
298 @param Token An token previously returned by a successful
299 call to RegisterWatch or RegisterWatchBackend.
301 @return On success, XENSTORE_STATUS_SUCCESS. Otherwise an errno value
302 indicating the type of failure.
306 (EFIAPI
*XENBUS_WAIT_FOR_WATCH
) (
307 IN XENBUS_PROTOCOL
*This
,
313 /// Protocol structure
315 /// DISCLAIMER: the XENBUS_PROTOCOL introduced here is a work in progress, and
316 /// should not be used outside of the EDK II tree.
318 struct _XENBUS_PROTOCOL
{
319 XENBUS_XS_READ XsRead
;
320 XENBUS_XS_BACKEND_READ XsBackendRead
;
321 XENBUS_XS_PRINTF XsPrintf
;
322 XENBUS_XS_REMOVE XsRemove
;
323 XENBUS_XS_TRANSACTION_START XsTransactionStart
;
324 XENBUS_XS_TRANSACTION_END XsTransactionEnd
;
326 XENBUS_GRANT_ACCESS GrantAccess
;
327 XENBUS_GRANT_END_ACCESS GrantEndAccess
;
329 XENBUS_REGISTER_WATCH RegisterWatch
;
330 XENBUS_REGISTER_WATCH_BACKEND RegisterWatchBackend
;
331 XENBUS_UNREGISTER_WATCH UnregisterWatch
;
332 XENBUS_WAIT_FOR_WATCH WaitForWatch
;
334 // Protocol data fields
339 CONST CHAR8
*Backend
;
342 extern EFI_GUID gXenBusProtocolGuid
;