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 SPDX-License-Identifier: BSD-2-Clause-Patent 15 16 **/ 17 18 #ifndef __PROTOCOL_XENBUS_H__ 19 #define __PROTOCOL_XENBUS_H__ 20 21 #define XENBUS_PROTOCOL_GUID \ 22 {0x3d3ca290, 0xb9a5, 0x11e3, {0xb7, 0x5d, 0xb8, 0xac, 0x6f, 0x7d, 0x65, 0xe6}} 23 24 /// 25 /// Forward declaration 26 /// 27 typedef struct _XENBUS_PROTOCOL XENBUS_PROTOCOL; 28 29 typedef enum xenbus_state XenBusState; 30 31 typedef struct 32 { 33 UINT32 Id; 34 } XENSTORE_TRANSACTION; 35 36 #define XST_NIL ((XENSTORE_TRANSACTION *) NULL) 37 38 typedef enum { 39 XENSTORE_STATUS_SUCCESS = 0, 40 XENSTORE_STATUS_FAIL, 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, 48 XENSTORE_STATUS_EIO, 49 XENSTORE_STATUS_ENOTEMPTY, 50 XENSTORE_STATUS_ENOSYS, 51 XENSTORE_STATUS_EROFS, 52 XENSTORE_STATUS_EBUSY, 53 XENSTORE_STATUS_EAGAIN, 54 XENSTORE_STATUS_EISCONN, 55 XENSTORE_STATUS_E2BIG 56 } XENSTORE_STATUS; 57 58 59 #include <IndustryStandard/Xen/grant_table.h> 60 #include <IndustryStandard/Xen/event_channel.h> 61 62 /// 63 /// Function prototypes 64 /// 65 66 /** 67 Get the contents of the node Node of the PV device. Returns the contents in 68 *Result which should be freed after use. 69 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. 74 75 @return On success, XENSTORE_STATUS_SUCCESS. Otherwise an errno value 76 indicating the type of failure. 77 78 @note The results buffer is malloced and should be free'd by the 79 caller. 80 **/ 81 typedef 82 XENSTORE_STATUS 83 (EFIAPI *XENBUS_XS_READ)( 84 IN XENBUS_PROTOCOL *This, 85 IN CONST XENSTORE_TRANSACTION *Transaction, 86 IN CONST CHAR8 *Node, 87 OUT VOID **Result 88 ); 89 90 /** 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. 93 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. 98 99 @return On success, XENSTORE_STATUS_SUCCESS. Otherwise an errno value 100 indicating the type of failure. 101 102 @note The results buffer is malloced and should be free'd by the 103 caller. 104 **/ 105 typedef 106 XENSTORE_STATUS 107 (EFIAPI *XENBUS_XS_BACKEND_READ)( 108 IN XENBUS_PROTOCOL *This, 109 IN CONST XENSTORE_TRANSACTION *Transaction, 110 IN CONST CHAR8 *Node, 111 OUT VOID **Result 112 ); 113 114 /** 115 Print formatted write to a XenStore node. 116 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 122 of arguments. 123 124 @return On success, XENSTORE_STATUS_SUCCESS. Otherwise an errno value 125 indicating the type of write failure. 126 **/ 127 typedef 128 XENSTORE_STATUS 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, 135 ... 136 ); 137 138 /** 139 Remove a node or directory (directories must be empty) of the PV driver's 140 subdirectory. 141 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. 145 146 @return On success, XENSTORE_STATUS_SUCCESS. Otherwise an errno value 147 indicating the type of failure. 148 **/ 149 typedef 150 XENSTORE_STATUS 151 (EFIAPI *XENBUS_XS_REMOVE) ( 152 IN XENBUS_PROTOCOL *This, 153 IN CONST XENSTORE_TRANSACTION *Transaction, 154 IN CONST CHAR8 *Node 155 ); 156 157 /** 158 Start a transaction. 159 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). 163 164 @param This A pointer to XENBUS_PROTOCOL instance. 165 @param Transaction The returned transaction. 166 167 @return On success, XENSTORE_STATUS_SUCCESS. Otherwise an errno value 168 indicating the type of failure. 169 **/ 170 typedef 171 XENSTORE_STATUS 172 (EFIAPI *XENBUS_XS_TRANSACTION_START)( 173 IN XENBUS_PROTOCOL *This, 174 OUT XENSTORE_TRANSACTION *Transaction 175 ); 176 177 /** 178 End a transaction. 179 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. 184 185 @return On success, XENSTORE_STATUS_SUCCESS. Otherwise an errno value 186 indicating the type of failure. 187 **/ 188 typedef 189 XENSTORE_STATUS 190 (EFIAPI *XENBUS_XS_TRANSACTION_END) ( 191 IN XENBUS_PROTOCOL *This, 192 IN CONST XENSTORE_TRANSACTION *Transaction, 193 IN BOOLEAN Abort 194 ); 195 196 /** 197 Set a new state for the frontend of the PV driver. 198 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. 202 203 @return On success, XENSTORE_STATUS_SUCCESS. Otherwise an errno value 204 indicating the type of failure. 205 **/ 206 typedef 207 XENSTORE_STATUS 208 (EFIAPI *XENBUS_SET_STATE)( 209 IN XENBUS_PROTOCOL *This, 210 IN CONST XENSTORE_TRANSACTION *Transaction, 211 IN XenBusState State 212 ); 213 214 /** 215 Grant access to the page Frame to the domain DomainId. 216 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. 222 **/ 223 typedef 224 EFI_STATUS 225 (EFIAPI *XENBUS_GRANT_ACCESS)( 226 IN XENBUS_PROTOCOL *This, 227 IN domid_t DomainId, 228 IN UINTN Frame, 229 IN BOOLEAN ReadOnly, 230 OUT grant_ref_t *refp 231 ); 232 233 /** 234 End access to grant Ref, previously return by XenBusGrantAccess. 235 236 @param This A pointer to XENBUS_PROTOCOL instance. 237 @param Ref Reference numeber of a grant previously returned by 238 XenBusGrantAccess. 239 **/ 240 typedef 241 EFI_STATUS 242 (EFIAPI *XENBUS_GRANT_END_ACCESS)( 243 IN XENBUS_PROTOCOL *This, 244 IN grant_ref_t Ref 245 ); 246 247 /** 248 Allocate a port that can be bind from domain DomainId. 249 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 253 allocated port. 254 255 @retval UINT32 The return value from the hypercall, 0 if success. 256 **/ 257 typedef 258 UINT32 259 (EFIAPI *XENBUS_EVENT_CHANNEL_ALLOCATE) ( 260 IN XENBUS_PROTOCOL *This, 261 IN domid_t DomainId, 262 OUT evtchn_port_t *Port 263 ); 264 265 /** 266 Send an event to the remote end of the channel whose local endpoint is Port. 267 268 @param This A pointer to the XENBUS_PROTOCOL. 269 @param Port Local port to the the event from. 270 271 @retval UINT32 The return value from the hypercall, 0 if success. 272 **/ 273 typedef 274 UINT32 275 (EFIAPI *XENBUS_EVENT_CHANNEL_NOTIFY) ( 276 IN XENBUS_PROTOCOL *This, 277 IN evtchn_port_t Port 278 ); 279 280 /** 281 Close a local event channel Port. 282 283 @param This A pointer to the XENBUS_PROTOCOL. 284 @param Port The event channel to close. 285 286 @retval UINT32 The return value from the hypercall, 0 if success. 287 **/ 288 typedef 289 UINT32 290 (EFIAPI *XENBUS_EVENT_CHANNEL_CLOSE) ( 291 IN XENBUS_PROTOCOL *This, 292 IN evtchn_port_t Port 293 ); 294 295 /** 296 Register a XenStore watch. 297 298 XenStore watches allow a client to wait for changes to an object in the 299 XenStore. 300 301 @param This A pointer to the XENBUS_PROTOCOL. 302 @param Node The basename of the path to watch. 303 @param Token A token. 304 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. 309 **/ 310 typedef 311 XENSTORE_STATUS 312 (EFIAPI *XENBUS_REGISTER_WATCH) ( 313 IN XENBUS_PROTOCOL *This, 314 IN CONST CHAR8 *Node, 315 OUT VOID **Token 316 ); 317 318 /** 319 Register a XenStore watch on a backend's node. 320 321 XenStore watches allow a client to wait for changes to an object in the 322 XenStore. 323 324 @param This A pointer to the XENBUS_PROTOCOL. 325 @param Node The basename of the path to watch. 326 @param Token A token. 327 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. 332 **/ 333 typedef 334 XENSTORE_STATUS 335 (EFIAPI *XENBUS_REGISTER_WATCH_BACKEND) ( 336 IN XENBUS_PROTOCOL *This, 337 IN CONST CHAR8 *Node, 338 OUT VOID **Token 339 ); 340 341 /** 342 Unregister a XenStore watch. 343 344 @param This A pointer to the XENBUS_PROTOCOL. 345 @param Token An token previously returned by a successful 346 call to RegisterWatch (). 347 **/ 348 typedef 349 VOID 350 (EFIAPI *XENBUS_UNREGISTER_WATCH) ( 351 IN XENBUS_PROTOCOL *This, 352 IN VOID *Token 353 ); 354 355 /** 356 Block until the node watch by Token change. 357 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. 361 362 @return On success, XENSTORE_STATUS_SUCCESS. Otherwise an errno value 363 indicating the type of failure. 364 **/ 365 typedef 366 XENSTORE_STATUS 367 (EFIAPI *XENBUS_WAIT_FOR_WATCH) ( 368 IN XENBUS_PROTOCOL *This, 369 IN VOID *Token 370 ); 371 372 373 /// 374 /// Protocol structure 375 /// 376 /// DISCLAIMER: the XENBUS_PROTOCOL introduced here is a work in progress, and 377 /// should not be used outside of the EDK II tree. 378 /// 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; 387 388 XENBUS_GRANT_ACCESS GrantAccess; 389 XENBUS_GRANT_END_ACCESS GrantEndAccess; 390 391 XENBUS_EVENT_CHANNEL_ALLOCATE EventChannelAllocate; 392 XENBUS_EVENT_CHANNEL_NOTIFY EventChannelNotify; 393 XENBUS_EVENT_CHANNEL_CLOSE EventChannelClose; 394 395 XENBUS_REGISTER_WATCH RegisterWatch; 396 XENBUS_REGISTER_WATCH_BACKEND RegisterWatchBackend; 397 XENBUS_UNREGISTER_WATCH UnregisterWatch; 398 XENBUS_WAIT_FOR_WATCH WaitForWatch; 399 // 400 // Protocol data fields 401 // 402 CONST CHAR8 *Type; 403 UINT16 DeviceId; 404 CONST CHAR8 *Node; 405 CONST CHAR8 *Backend; 406 }; 407 408 extern EFI_GUID gXenBusProtocolGuid; 409 410 #endif 411