1 2 /** @file 3 XenBus protocol to be used between the XenBus bus driver and Xen PV devices. 4 5 DISCLAIMER: the XENBUS_PROTOCOL introduced here is a work in progress, and 6 should not be used outside of the EDK II tree. 7 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. 11 12 Copyright (C) 2014, Citrix Ltd. 13 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 18 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. 21 22 **/ 23 24 #ifndef __PROTOCOL_XENBUS_H__ 25 #define __PROTOCOL_XENBUS_H__ 26 27 #define XENBUS_PROTOCOL_GUID \ 28 {0x3d3ca290, 0xb9a5, 0x11e3, {0xb7, 0x5d, 0xb8, 0xac, 0x6f, 0x7d, 0x65, 0xe6}} 29 30 /// 31 /// Forward declaration 32 /// 33 typedef struct _XENBUS_PROTOCOL XENBUS_PROTOCOL; 34 35 typedef enum xenbus_state XenBusState; 36 37 typedef struct 38 { 39 UINT32 Id; 40 } XENSTORE_TRANSACTION; 41 42 #define XST_NIL ((XENSTORE_TRANSACTION *) NULL) 43 44 typedef enum { 45 XENSTORE_STATUS_SUCCESS = 0, 46 XENSTORE_STATUS_FAIL, 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, 54 XENSTORE_STATUS_EIO, 55 XENSTORE_STATUS_ENOTEMPTY, 56 XENSTORE_STATUS_ENOSYS, 57 XENSTORE_STATUS_EROFS, 58 XENSTORE_STATUS_EBUSY, 59 XENSTORE_STATUS_EAGAIN, 60 XENSTORE_STATUS_EISCONN, 61 XENSTORE_STATUS_E2BIG 62 } XENSTORE_STATUS; 63 64 65 #include <IndustryStandard/Xen/grant_table.h> 66 #include <IndustryStandard/Xen/event_channel.h> 67 68 /// 69 /// Function prototypes 70 /// 71 72 /** 73 Get the contents of the node Node of the PV device. Returns the contents in 74 *Result which should be freed after use. 75 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. 80 81 @return On success, XENSTORE_STATUS_SUCCESS. Otherwise an errno value 82 indicating the type of failure. 83 84 @note The results buffer is malloced and should be free'd by the 85 caller. 86 **/ 87 typedef 88 XENSTORE_STATUS 89 (EFIAPI *XENBUS_XS_READ)( 90 IN XENBUS_PROTOCOL *This, 91 IN CONST XENSTORE_TRANSACTION *Transaction, 92 IN CONST CHAR8 *Node, 93 OUT VOID **Result 94 ); 95 96 /** 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. 99 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. 104 105 @return On success, XENSTORE_STATUS_SUCCESS. Otherwise an errno value 106 indicating the type of failure. 107 108 @note The results buffer is malloced and should be free'd by the 109 caller. 110 **/ 111 typedef 112 XENSTORE_STATUS 113 (EFIAPI *XENBUS_XS_BACKEND_READ)( 114 IN XENBUS_PROTOCOL *This, 115 IN CONST XENSTORE_TRANSACTION *Transaction, 116 IN CONST CHAR8 *Node, 117 OUT VOID **Result 118 ); 119 120 /** 121 Print formatted write to a XenStore node. 122 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 128 of arguments. 129 130 @return On success, XENSTORE_STATUS_SUCCESS. Otherwise an errno value 131 indicating the type of write failure. 132 **/ 133 typedef 134 XENSTORE_STATUS 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, 141 ... 142 ); 143 144 /** 145 Remove a node or directory (directories must be empty) of the PV driver's 146 subdirectory. 147 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. 151 152 @return On success, XENSTORE_STATUS_SUCCESS. Otherwise an errno value 153 indicating the type of failure. 154 **/ 155 typedef 156 XENSTORE_STATUS 157 (EFIAPI *XENBUS_XS_REMOVE) ( 158 IN XENBUS_PROTOCOL *This, 159 IN CONST XENSTORE_TRANSACTION *Transaction, 160 IN CONST CHAR8 *Node 161 ); 162 163 /** 164 Start a transaction. 165 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). 169 170 @param This A pointer to XENBUS_PROTOCOL instance. 171 @param Transaction The returned transaction. 172 173 @return On success, XENSTORE_STATUS_SUCCESS. Otherwise an errno value 174 indicating the type of failure. 175 **/ 176 typedef 177 XENSTORE_STATUS 178 (EFIAPI *XENBUS_XS_TRANSACTION_START)( 179 IN XENBUS_PROTOCOL *This, 180 OUT XENSTORE_TRANSACTION *Transaction 181 ); 182 183 /** 184 End a transaction. 185 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. 190 191 @return On success, XENSTORE_STATUS_SUCCESS. Otherwise an errno value 192 indicating the type of failure. 193 **/ 194 typedef 195 XENSTORE_STATUS 196 (EFIAPI *XENBUS_XS_TRANSACTION_END) ( 197 IN XENBUS_PROTOCOL *This, 198 IN CONST XENSTORE_TRANSACTION *Transaction, 199 IN BOOLEAN Abort 200 ); 201 202 /** 203 Set a new state for the frontend of the PV driver. 204 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. 208 209 @return On success, XENSTORE_STATUS_SUCCESS. Otherwise an errno value 210 indicating the type of failure. 211 **/ 212 typedef 213 XENSTORE_STATUS 214 (EFIAPI *XENBUS_SET_STATE)( 215 IN XENBUS_PROTOCOL *This, 216 IN CONST XENSTORE_TRANSACTION *Transaction, 217 IN XenBusState State 218 ); 219 220 /** 221 Grant access to the page Frame to the domain DomainId. 222 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 written to this pointer. 228 **/ 229 typedef 230 EFI_STATUS 231 (EFIAPI *XENBUS_GRANT_ACCESS)( 232 IN XENBUS_PROTOCOL *This, 233 IN domid_t DomainId, 234 IN UINTN Frame, 235 IN BOOLEAN ReadOnly, 236 OUT grant_ref_t *refp 237 ); 238 239 /** 240 End access to grant Ref, previously return by XenBusGrantAccess. 241 242 @param This A pointer to XENBUS_PROTOCOL instance. 243 @param Ref Reference numeber of a grant previously returned by 244 XenBusGrantAccess. 245 **/ 246 typedef 247 EFI_STATUS 248 (EFIAPI *XENBUS_GRANT_END_ACCESS)( 249 IN XENBUS_PROTOCOL *This, 250 IN grant_ref_t Ref 251 ); 252 253 /** 254 Allocate a port that can be bind from domain DomainId. 255 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 259 allocated port. 260 261 @retval UINT32 The return value from the hypercall, 0 if success. 262 **/ 263 typedef 264 UINT32 265 (EFIAPI *XENBUS_EVENT_CHANNEL_ALLOCATE) ( 266 IN XENBUS_PROTOCOL *This, 267 IN domid_t DomainId, 268 OUT evtchn_port_t *Port 269 ); 270 271 /** 272 Send an event to the remote end of the channel whose local endpoint is Port. 273 274 @param This A pointer to the XENBUS_PROTOCOL. 275 @param Port Local port to the the event from. 276 277 @retval UINT32 The return value from the hypercall, 0 if success. 278 **/ 279 typedef 280 UINT32 281 (EFIAPI *XENBUS_EVENT_CHANNEL_NOTIFY) ( 282 IN XENBUS_PROTOCOL *This, 283 IN evtchn_port_t Port 284 ); 285 286 /** 287 Close a local event channel Port. 288 289 @param This A pointer to the XENBUS_PROTOCOL. 290 @param Port The event channel to close. 291 292 @retval UINT32 The return value from the hypercall, 0 if success. 293 **/ 294 typedef 295 UINT32 296 (EFIAPI *XENBUS_EVENT_CHANNEL_CLOSE) ( 297 IN XENBUS_PROTOCOL *This, 298 IN evtchn_port_t Port 299 ); 300 301 /** 302 Register a XenStore watch. 303 304 XenStore watches allow a client to wait for changes to an object in the 305 XenStore. 306 307 @param This A pointer to the XENBUS_PROTOCOL. 308 @param Node The basename of the path to watch. 309 @param Token A token. 310 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 suppressed, allowing multiple, physically different, 314 xenbus_watch objects, to watch the same path in the XenStore. 315 **/ 316 typedef 317 XENSTORE_STATUS 318 (EFIAPI *XENBUS_REGISTER_WATCH) ( 319 IN XENBUS_PROTOCOL *This, 320 IN CONST CHAR8 *Node, 321 OUT VOID **Token 322 ); 323 324 /** 325 Register a XenStore watch on a backend's node. 326 327 XenStore watches allow a client to wait for changes to an object in the 328 XenStore. 329 330 @param This A pointer to the XENBUS_PROTOCOL. 331 @param Node The basename of the path to watch. 332 @param Token A token. 333 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 suppressed, allowing multiple, physically different, 337 xenbus_watch objects, to watch the same path in the XenStore. 338 **/ 339 typedef 340 XENSTORE_STATUS 341 (EFIAPI *XENBUS_REGISTER_WATCH_BACKEND) ( 342 IN XENBUS_PROTOCOL *This, 343 IN CONST CHAR8 *Node, 344 OUT VOID **Token 345 ); 346 347 /** 348 Unregister a XenStore watch. 349 350 @param This A pointer to the XENBUS_PROTOCOL. 351 @param Token An token previously returned by a successful 352 call to RegisterWatch (). 353 **/ 354 typedef 355 VOID 356 (EFIAPI *XENBUS_UNREGISTER_WATCH) ( 357 IN XENBUS_PROTOCOL *This, 358 IN VOID *Token 359 ); 360 361 /** 362 Block until the node watch by Token change. 363 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. 367 368 @return On success, XENSTORE_STATUS_SUCCESS. Otherwise an errno value 369 indicating the type of failure. 370 **/ 371 typedef 372 XENSTORE_STATUS 373 (EFIAPI *XENBUS_WAIT_FOR_WATCH) ( 374 IN XENBUS_PROTOCOL *This, 375 IN VOID *Token 376 ); 377 378 379 /// 380 /// Protocol structure 381 /// 382 /// DISCLAIMER: the XENBUS_PROTOCOL introduced here is a work in progress, and 383 /// should not be used outside of the EDK II tree. 384 /// 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; 393 394 XENBUS_GRANT_ACCESS GrantAccess; 395 XENBUS_GRANT_END_ACCESS GrantEndAccess; 396 397 XENBUS_EVENT_CHANNEL_ALLOCATE EventChannelAllocate; 398 XENBUS_EVENT_CHANNEL_NOTIFY EventChannelNotify; 399 XENBUS_EVENT_CHANNEL_CLOSE EventChannelClose; 400 401 XENBUS_REGISTER_WATCH RegisterWatch; 402 XENBUS_REGISTER_WATCH_BACKEND RegisterWatchBackend; 403 XENBUS_UNREGISTER_WATCH UnregisterWatch; 404 XENBUS_WAIT_FOR_WATCH WaitForWatch; 405 // 406 // Protocol data fields 407 // 408 CONST CHAR8 *Type; 409 UINT16 DeviceId; 410 CONST CHAR8 *Node; 411 CONST CHAR8 *Backend; 412 }; 413 414 extern EFI_GUID gXenBusProtocolGuid; 415 416 #endif 417