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 *) NULL)
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>
66 #include <IndustryStandard/Xen/event_channel.h>
69 /// Function prototypes
73 Get the contents of the node Node of the PV device. Returns the contents in
74 *Result which should be freed after use.
76 @param This A pointer to XENBUS_PROTOCOL instance.
77 @param Transaction The XenStore transaction covering this request.
78 @param Node The basename of the file to read.
79 @param Result The returned contents from this file.
81 @return On success, XENSTORE_STATUS_SUCCESS. Otherwise an errno value
82 indicating the type of failure.
84 @note The results buffer is malloced and should be free'd by the
89 (EFIAPI
*XENBUS_XS_READ
)(
90 IN XENBUS_PROTOCOL
*This
,
91 IN CONST XENSTORE_TRANSACTION
*Transaction
,
97 Get the contents of the node Node of the PV device's backend. Returns the
98 contents in *Result which should be freed after use.
100 @param This A pointer to XENBUS_PROTOCOL instance.
101 @param Transaction The XenStore transaction covering this request.
102 @param Node The basename of the file to read.
103 @param Result The returned contents from this file.
105 @return On success, XENSTORE_STATUS_SUCCESS. Otherwise an errno value
106 indicating the type of failure.
108 @note The results buffer is malloced and should be free'd by the
113 (EFIAPI
*XENBUS_XS_BACKEND_READ
)(
114 IN XENBUS_PROTOCOL
*This
,
115 IN CONST XENSTORE_TRANSACTION
*Transaction
,
116 IN CONST CHAR8
*Node
,
121 Print formatted write to a XenStore node.
123 @param This A pointer to XENBUS_PROTOCOL instance.
124 @param Transaction The XenStore transaction covering this request.
125 @param Directory The dirname of the path to read.
126 @param Node The basename of the path to read.
127 @param Format AsciiSPrint format string followed by a variable number
130 @return On success, XENSTORE_STATUS_SUCCESS. Otherwise an errno value
131 indicating the type of write failure.
135 (EFIAPI
*XENBUS_XS_PRINTF
) (
136 IN XENBUS_PROTOCOL
*This
,
137 IN CONST XENSTORE_TRANSACTION
*Transaction
,
138 IN CONST CHAR8
*Directory
,
139 IN CONST CHAR8
*Node
,
140 IN CONST CHAR8
*Format
,
145 Remove a node or directory (directories must be empty) of the PV driver's
148 @param This A pointer to XENBUS_PROTOCOL instance.
149 @param Transaction The XenStore transaction covering this request.
150 @param Node The basename of the node to remove.
152 @return On success, XENSTORE_STATUS_SUCCESS. Otherwise an errno value
153 indicating the type of failure.
157 (EFIAPI
*XENBUS_XS_REMOVE
) (
158 IN XENBUS_PROTOCOL
*This
,
159 IN CONST XENSTORE_TRANSACTION
*Transaction
,
166 Changes by others will not be seen during the lifetime of this
167 transaction, and changes will not be visible to others until it
168 is committed (XsTransactionEnd).
170 @param This A pointer to XENBUS_PROTOCOL instance.
171 @param Transaction The returned transaction.
173 @return On success, XENSTORE_STATUS_SUCCESS. Otherwise an errno value
174 indicating the type of failure.
178 (EFIAPI
*XENBUS_XS_TRANSACTION_START
)(
179 IN XENBUS_PROTOCOL
*This
,
180 OUT XENSTORE_TRANSACTION
*Transaction
186 @param This A pointer to XENBUS_PROTOCOL instance.
187 @param Transaction The transaction to end/commit.
188 @param Abort If TRUE, the transaction is discarded
189 instead of committed.
191 @return On success, XENSTORE_STATUS_SUCCESS. Otherwise an errno value
192 indicating the type of failure.
196 (EFIAPI
*XENBUS_XS_TRANSACTION_END
) (
197 IN XENBUS_PROTOCOL
*This
,
198 IN CONST XENSTORE_TRANSACTION
*Transaction
,
203 Set a new state for the frontend of the PV driver.
205 @param This A pointer to XENBUS_PROTOCOL instance.
206 @param Transaction The transaction to end/commit.
207 @param State The new state to apply.
209 @return On success, XENSTORE_STATUS_SUCCESS. Otherwise an errno value
210 indicating the type of failure.
214 (EFIAPI
*XENBUS_SET_STATE
)(
215 IN XENBUS_PROTOCOL
*This
,
216 IN CONST XENSTORE_TRANSACTION
*Transaction
,
221 Grant access to the page Frame to the domain DomainId.
223 @param This A pointer to XENBUS_PROTOCOL instance.
224 @param DomainId ID of the domain to grant acces to.
225 @param Frame Frame Number of the page to grant access to.
226 @param ReadOnly Provide read-only or read-write access.
227 @param RefPtr Reference number of the grant will be writen to this pointer.
231 (EFIAPI
*XENBUS_GRANT_ACCESS
)(
232 IN XENBUS_PROTOCOL
*This
,
236 OUT grant_ref_t
*refp
240 End access to grant Ref, previously return by XenBusGrantAccess.
242 @param This A pointer to XENBUS_PROTOCOL instance.
243 @param Ref Reference numeber of a grant previously returned by
248 (EFIAPI
*XENBUS_GRANT_END_ACCESS
)(
249 IN XENBUS_PROTOCOL
*This
,
254 Allocate a port that can be bind from domain DomainId.
256 @param This A pointer to the XENBUS_PROTOCOL.
257 @param DomainId The domain ID that can bind the newly allocated port.
258 @param Port A pointer to a evtchn_port_t that will contain the newly
261 @retval UINT32 The return value from the hypercall, 0 if success.
265 (EFIAPI
*XENBUS_EVENT_CHANNEL_ALLOCATE
) (
266 IN XENBUS_PROTOCOL
*This
,
268 OUT evtchn_port_t
*Port
272 Send an event to the remote end of the channel whose local endpoint is Port.
274 @param This A pointer to the XENBUS_PROTOCOL.
275 @param Port Local port to the the event from.
277 @retval UINT32 The return value from the hypercall, 0 if success.
281 (EFIAPI
*XENBUS_EVENT_CHANNEL_NOTIFY
) (
282 IN XENBUS_PROTOCOL
*This
,
283 IN evtchn_port_t Port
287 Close a local event channel Port.
289 @param This A pointer to the XENBUS_PROTOCOL.
290 @param Port The event channel to close.
292 @retval UINT32 The return value from the hypercall, 0 if success.
296 (EFIAPI
*XENBUS_EVENT_CHANNEL_CLOSE
) (
297 IN XENBUS_PROTOCOL
*This
,
298 IN evtchn_port_t Port
302 Register a XenStore watch.
304 XenStore watches allow a client to wait for changes to an object in the
307 @param This A pointer to the XENBUS_PROTOCOL.
308 @param Node The basename of the path to watch.
309 @param Token A token.
311 @return On success, XENSTORE_STATUS_SUCCESS. Otherwise an errno value
312 indicating the type of write failure. EEXIST errors from the
313 XenStore are supressed, allowing multiple, physically different,
314 xenbus_watch objects, to watch the same path in the XenStore.
318 (EFIAPI
*XENBUS_REGISTER_WATCH
) (
319 IN XENBUS_PROTOCOL
*This
,
320 IN CONST CHAR8
*Node
,
325 Register a XenStore watch on a backend's node.
327 XenStore watches allow a client to wait for changes to an object in the
330 @param This A pointer to the XENBUS_PROTOCOL.
331 @param Node The basename of the path to watch.
332 @param Token A token.
334 @return On success, XENSTORE_STATUS_SUCCESS. Otherwise an errno value
335 indicating the type of write failure. EEXIST errors from the
336 XenStore are supressed, allowing multiple, physically different,
337 xenbus_watch objects, to watch the same path in the XenStore.
341 (EFIAPI
*XENBUS_REGISTER_WATCH_BACKEND
) (
342 IN XENBUS_PROTOCOL
*This
,
343 IN CONST CHAR8
*Node
,
348 Unregister a XenStore watch.
350 @param This A pointer to the XENBUS_PROTOCOL.
351 @param Token An token previously returned by a successful
352 call to RegisterWatch ().
356 (EFIAPI
*XENBUS_UNREGISTER_WATCH
) (
357 IN XENBUS_PROTOCOL
*This
,
362 Block until the node watch by Token change.
364 @param This A pointer to the XENBUS_PROTOCOL.
365 @param Token An token previously returned by a successful
366 call to RegisterWatch or RegisterWatchBackend.
368 @return On success, XENSTORE_STATUS_SUCCESS. Otherwise an errno value
369 indicating the type of failure.
373 (EFIAPI
*XENBUS_WAIT_FOR_WATCH
) (
374 IN XENBUS_PROTOCOL
*This
,
380 /// Protocol structure
382 /// DISCLAIMER: the XENBUS_PROTOCOL introduced here is a work in progress, and
383 /// should not be used outside of the EDK II tree.
385 struct _XENBUS_PROTOCOL
{
386 XENBUS_XS_READ XsRead
;
387 XENBUS_XS_BACKEND_READ XsBackendRead
;
388 XENBUS_XS_PRINTF XsPrintf
;
389 XENBUS_XS_REMOVE XsRemove
;
390 XENBUS_XS_TRANSACTION_START XsTransactionStart
;
391 XENBUS_XS_TRANSACTION_END XsTransactionEnd
;
392 XENBUS_SET_STATE SetState
;
394 XENBUS_GRANT_ACCESS GrantAccess
;
395 XENBUS_GRANT_END_ACCESS GrantEndAccess
;
397 XENBUS_EVENT_CHANNEL_ALLOCATE EventChannelAllocate
;
398 XENBUS_EVENT_CHANNEL_NOTIFY EventChannelNotify
;
399 XENBUS_EVENT_CHANNEL_CLOSE EventChannelClose
;
401 XENBUS_REGISTER_WATCH RegisterWatch
;
402 XENBUS_REGISTER_WATCH_BACKEND RegisterWatchBackend
;
403 XENBUS_UNREGISTER_WATCH UnregisterWatch
;
404 XENBUS_WAIT_FOR_WATCH WaitForWatch
;
406 // Protocol data fields
411 CONST CHAR8
*Backend
;
414 extern EFI_GUID gXenBusProtocolGuid
;