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 SPDX-License-Identifier: BSD-2-Clause-Patent
18 #ifndef __PROTOCOL_XENBUS_H__
19 #define __PROTOCOL_XENBUS_H__
21 #define XENBUS_PROTOCOL_GUID \
22 {0x3d3ca290, 0xb9a5, 0x11e3, {0xb7, 0x5d, 0xb8, 0xac, 0x6f, 0x7d, 0x65, 0xe6}}
25 /// Forward declaration
27 typedef struct _XENBUS_PROTOCOL XENBUS_PROTOCOL
;
29 typedef enum xenbus_state XenBusState
;
34 } XENSTORE_TRANSACTION
;
36 #define XST_NIL ((XENSTORE_TRANSACTION *) NULL)
39 XENSTORE_STATUS_SUCCESS
= 0,
41 XENSTORE_STATUS_EINVAL
,
42 XENSTORE_STATUS_EACCES
,
43 XENSTORE_STATUS_EEXIST
,
44 XENSTORE_STATUS_EISDIR
,
45 XENSTORE_STATUS_ENOENT
,
46 XENSTORE_STATUS_ENOMEM
,
47 XENSTORE_STATUS_ENOSPC
,
49 XENSTORE_STATUS_ENOTEMPTY
,
50 XENSTORE_STATUS_ENOSYS
,
51 XENSTORE_STATUS_EROFS
,
52 XENSTORE_STATUS_EBUSY
,
53 XENSTORE_STATUS_EAGAIN
,
54 XENSTORE_STATUS_EISCONN
,
59 #include <IndustryStandard/Xen/grant_table.h>
60 #include <IndustryStandard/Xen/event_channel.h>
63 /// Function prototypes
67 Get the contents of the node Node of the PV device. Returns the contents in
68 *Result which should be freed after use.
70 @param This A pointer to XENBUS_PROTOCOL instance.
71 @param Transaction The XenStore transaction covering this request.
72 @param Node The basename of the file to read.
73 @param Result The returned contents from this file.
75 @return On success, XENSTORE_STATUS_SUCCESS. Otherwise an errno value
76 indicating the type of failure.
78 @note The results buffer is malloced and should be free'd by the
83 (EFIAPI
*XENBUS_XS_READ
)(
84 IN XENBUS_PROTOCOL
*This
,
85 IN CONST XENSTORE_TRANSACTION
*Transaction
,
91 Get the contents of the node Node of the PV device's backend. Returns the
92 contents in *Result which should be freed after use.
94 @param This A pointer to XENBUS_PROTOCOL instance.
95 @param Transaction The XenStore transaction covering this request.
96 @param Node The basename of the file to read.
97 @param Result The returned contents from this file.
99 @return On success, XENSTORE_STATUS_SUCCESS. Otherwise an errno value
100 indicating the type of failure.
102 @note The results buffer is malloced and should be free'd by the
107 (EFIAPI
*XENBUS_XS_BACKEND_READ
)(
108 IN XENBUS_PROTOCOL
*This
,
109 IN CONST XENSTORE_TRANSACTION
*Transaction
,
110 IN CONST CHAR8
*Node
,
115 Print formatted write to a XenStore node.
117 @param This A pointer to XENBUS_PROTOCOL instance.
118 @param Transaction The XenStore transaction covering this request.
119 @param Directory The dirname of the path to read.
120 @param Node The basename of the path to read.
121 @param Format AsciiSPrint format string followed by a variable number
124 @return On success, XENSTORE_STATUS_SUCCESS. Otherwise an errno value
125 indicating the type of write failure.
129 (EFIAPI
*XENBUS_XS_PRINTF
) (
130 IN XENBUS_PROTOCOL
*This
,
131 IN CONST XENSTORE_TRANSACTION
*Transaction
,
132 IN CONST CHAR8
*Directory
,
133 IN CONST CHAR8
*Node
,
134 IN CONST CHAR8
*Format
,
139 Remove a node or directory (directories must be empty) of the PV driver's
142 @param This A pointer to XENBUS_PROTOCOL instance.
143 @param Transaction The XenStore transaction covering this request.
144 @param Node The basename of the node to remove.
146 @return On success, XENSTORE_STATUS_SUCCESS. Otherwise an errno value
147 indicating the type of failure.
151 (EFIAPI
*XENBUS_XS_REMOVE
) (
152 IN XENBUS_PROTOCOL
*This
,
153 IN CONST XENSTORE_TRANSACTION
*Transaction
,
160 Changes by others will not be seen during the lifetime of this
161 transaction, and changes will not be visible to others until it
162 is committed (XsTransactionEnd).
164 @param This A pointer to XENBUS_PROTOCOL instance.
165 @param Transaction The returned transaction.
167 @return On success, XENSTORE_STATUS_SUCCESS. Otherwise an errno value
168 indicating the type of failure.
172 (EFIAPI
*XENBUS_XS_TRANSACTION_START
)(
173 IN XENBUS_PROTOCOL
*This
,
174 OUT XENSTORE_TRANSACTION
*Transaction
180 @param This A pointer to XENBUS_PROTOCOL instance.
181 @param Transaction The transaction to end/commit.
182 @param Abort If TRUE, the transaction is discarded
183 instead of committed.
185 @return On success, XENSTORE_STATUS_SUCCESS. Otherwise an errno value
186 indicating the type of failure.
190 (EFIAPI
*XENBUS_XS_TRANSACTION_END
) (
191 IN XENBUS_PROTOCOL
*This
,
192 IN CONST XENSTORE_TRANSACTION
*Transaction
,
197 Set a new state for the frontend of the PV driver.
199 @param This A pointer to XENBUS_PROTOCOL instance.
200 @param Transaction The transaction to end/commit.
201 @param State The new state to apply.
203 @return On success, XENSTORE_STATUS_SUCCESS. Otherwise an errno value
204 indicating the type of failure.
208 (EFIAPI
*XENBUS_SET_STATE
)(
209 IN XENBUS_PROTOCOL
*This
,
210 IN CONST XENSTORE_TRANSACTION
*Transaction
,
215 Grant access to the page Frame to the domain DomainId.
217 @param This A pointer to XENBUS_PROTOCOL instance.
218 @param DomainId ID of the domain to grant acces to.
219 @param Frame Frame Number of the page to grant access to.
220 @param ReadOnly Provide read-only or read-write access.
221 @param RefPtr Reference number of the grant will be written to this pointer.
225 (EFIAPI
*XENBUS_GRANT_ACCESS
)(
226 IN XENBUS_PROTOCOL
*This
,
230 OUT grant_ref_t
*refp
234 End access to grant Ref, previously return by XenBusGrantAccess.
236 @param This A pointer to XENBUS_PROTOCOL instance.
237 @param Ref Reference numeber of a grant previously returned by
242 (EFIAPI
*XENBUS_GRANT_END_ACCESS
)(
243 IN XENBUS_PROTOCOL
*This
,
248 Allocate a port that can be bind from domain DomainId.
250 @param This A pointer to the XENBUS_PROTOCOL.
251 @param DomainId The domain ID that can bind the newly allocated port.
252 @param Port A pointer to a evtchn_port_t that will contain the newly
255 @retval UINT32 The return value from the hypercall, 0 if success.
259 (EFIAPI
*XENBUS_EVENT_CHANNEL_ALLOCATE
) (
260 IN XENBUS_PROTOCOL
*This
,
262 OUT evtchn_port_t
*Port
266 Send an event to the remote end of the channel whose local endpoint is Port.
268 @param This A pointer to the XENBUS_PROTOCOL.
269 @param Port Local port to the the event from.
271 @retval UINT32 The return value from the hypercall, 0 if success.
275 (EFIAPI
*XENBUS_EVENT_CHANNEL_NOTIFY
) (
276 IN XENBUS_PROTOCOL
*This
,
277 IN evtchn_port_t Port
281 Close a local event channel Port.
283 @param This A pointer to the XENBUS_PROTOCOL.
284 @param Port The event channel to close.
286 @retval UINT32 The return value from the hypercall, 0 if success.
290 (EFIAPI
*XENBUS_EVENT_CHANNEL_CLOSE
) (
291 IN XENBUS_PROTOCOL
*This
,
292 IN evtchn_port_t Port
296 Register a XenStore watch.
298 XenStore watches allow a client to wait for changes to an object in the
301 @param This A pointer to the XENBUS_PROTOCOL.
302 @param Node The basename of the path to watch.
303 @param Token A token.
305 @return On success, XENSTORE_STATUS_SUCCESS. Otherwise an errno value
306 indicating the type of write failure. EEXIST errors from the
307 XenStore are suppressed, allowing multiple, physically different,
308 xenbus_watch objects, to watch the same path in the XenStore.
312 (EFIAPI
*XENBUS_REGISTER_WATCH
) (
313 IN XENBUS_PROTOCOL
*This
,
314 IN CONST CHAR8
*Node
,
319 Register a XenStore watch on a backend's node.
321 XenStore watches allow a client to wait for changes to an object in the
324 @param This A pointer to the XENBUS_PROTOCOL.
325 @param Node The basename of the path to watch.
326 @param Token A token.
328 @return On success, XENSTORE_STATUS_SUCCESS. Otherwise an errno value
329 indicating the type of write failure. EEXIST errors from the
330 XenStore are suppressed, allowing multiple, physically different,
331 xenbus_watch objects, to watch the same path in the XenStore.
335 (EFIAPI
*XENBUS_REGISTER_WATCH_BACKEND
) (
336 IN XENBUS_PROTOCOL
*This
,
337 IN CONST CHAR8
*Node
,
342 Unregister a XenStore watch.
344 @param This A pointer to the XENBUS_PROTOCOL.
345 @param Token An token previously returned by a successful
346 call to RegisterWatch ().
350 (EFIAPI
*XENBUS_UNREGISTER_WATCH
) (
351 IN XENBUS_PROTOCOL
*This
,
356 Block until the node watch by Token change.
358 @param This A pointer to the XENBUS_PROTOCOL.
359 @param Token An token previously returned by a successful
360 call to RegisterWatch or RegisterWatchBackend.
362 @return On success, XENSTORE_STATUS_SUCCESS. Otherwise an errno value
363 indicating the type of failure.
367 (EFIAPI
*XENBUS_WAIT_FOR_WATCH
) (
368 IN XENBUS_PROTOCOL
*This
,
374 /// Protocol structure
376 /// DISCLAIMER: the XENBUS_PROTOCOL introduced here is a work in progress, and
377 /// should not be used outside of the EDK II tree.
379 struct _XENBUS_PROTOCOL
{
380 XENBUS_XS_READ XsRead
;
381 XENBUS_XS_BACKEND_READ XsBackendRead
;
382 XENBUS_XS_PRINTF XsPrintf
;
383 XENBUS_XS_REMOVE XsRemove
;
384 XENBUS_XS_TRANSACTION_START XsTransactionStart
;
385 XENBUS_XS_TRANSACTION_END XsTransactionEnd
;
386 XENBUS_SET_STATE SetState
;
388 XENBUS_GRANT_ACCESS GrantAccess
;
389 XENBUS_GRANT_END_ACCESS GrantEndAccess
;
391 XENBUS_EVENT_CHANNEL_ALLOCATE EventChannelAllocate
;
392 XENBUS_EVENT_CHANNEL_NOTIFY EventChannelNotify
;
393 XENBUS_EVENT_CHANNEL_CLOSE EventChannelClose
;
395 XENBUS_REGISTER_WATCH RegisterWatch
;
396 XENBUS_REGISTER_WATCH_BACKEND RegisterWatchBackend
;
397 XENBUS_UNREGISTER_WATCH UnregisterWatch
;
398 XENBUS_WAIT_FOR_WATCH WaitForWatch
;
400 // Protocol data fields
405 CONST CHAR8
*Backend
;
408 extern EFI_GUID gXenBusProtocolGuid
;