1 /* 2 * This library is free software; you can redistribute it and/or 3 * modify it under the terms of the GNU Lesser General Public 4 * License as published by the Free Software Foundation; 5 * version 2.1 of the License. 6 * 7 * This library is distributed in the hope that it will be useful, 8 * but WITHOUT ANY WARRANTY; without even the implied warranty of 9 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 10 * Lesser General Public License for more details. 11 * 12 * You should have received a copy of the GNU Lesser General Public 13 * License along with this library; If not, see <http://www.gnu.org/licenses/>. 14 * 15 * Split off from: 16 * xenctrl.h 17 * 18 * A library for low-level access to the Xen control interfaces. 19 * 20 * Copyright (c) 2007-2008, D G Murray <Derek.Murray@cl.cam.ac.uk> 21 * Copyright (c) 2018, Oleksandr Andrushchenko, EPAM Systems Inc. 22 */ 23 #ifndef XENGNTTAB_H 24 #define XENGNTTAB_H 25 26 #include <stdint.h> 27 28 #include <xen/grant_table.h> 29 #include <xen/event_channel.h> 30 31 /* Callers who don't care don't need to #include <xentoollog.h> */ 32 struct xentoollog_logger; 33 34 /* 35 * PRODUCING AND CONSUMING GRANT REFERENCES 36 * ======================================== 37 * 38 * The xengnttab library contains two distinct interfaces, each with 39 * their own distinct handle type and entry points. The represent the 40 * two sides of the grant table interface, producer (gntshr) and 41 * consumer (gnttab). 42 * 43 * The xengnttab_* interfaces take a xengnttab_handle and provide 44 * mechanisms for consuming (i.e. mapping or copying to/from) grant 45 * references provided by a peer. 46 * 47 * The xengntshr_* interfaces take a xengntshr_handle and provide a 48 * mechanism to produce grantable memory and grant references to that 49 * memory, which can be handed to some peer. 50 * 51 * UNMAP NOTIFICATION 52 * ================== 53 * 54 * The xengnt{tab,shr}_*_notify interfaces implement a cooperative 55 * interface which is intended to allow the underlying kernel 56 * interfaces to attempt to notify the peer to perform graceful 57 * teardown upon failure (i.e. crash or exit) of the process on their 58 * end. 59 * 60 * These interfaces operate on a single page only and are intended for 61 * use on the main shared-ring page of a protocol. It is assumed that 62 * on teardown both ends would automatically teardown all grants 63 * associated with the protocol in addition to the shared ring itself. 64 * 65 * Each end is able to optionally nominate a byte offset within the 66 * shared page or an event channel or both. On exit of the process the 67 * underlying kernel driver will zero the byte at the given offset and 68 * signal the event channel. 69 * 70 * The event channel can be the same event channel used for regular 71 * ring progress notifications, or may be a dedicated event channel. 72 * 73 * Both ends may share the same notification byte offset within the 74 * shared page, or may have dedicated "client" and "server" status 75 * bytes. 76 * 77 * Since the byte is cleared on shutdown the protocol must use 0 as 78 * the "closed/dead" status, but is permitted to use any other non-0 79 * values to indicate various other "live" states (waiting for 80 * connection, connected, etc). 81 * 82 * Both ends are permitted to modify (including clear) their 83 * respective status bytes and to signal the event channel themselves 84 * from userspace. 85 * 86 * Depending on the mechanisms which have been registered an 87 * the peer may receive a shutdown notification as: 88 * 89 * - An event channel notification on a dedicated event channel 90 * - Observation of the other ends's status byte being cleared 91 * (whether in response to an explicit notification or in the 92 * course of normal operation). 93 * 94 * The mechanism should be defined as part of the specific ring 95 * protocol. 96 * 97 * Upon receiving notification of the peer is expected to teardown any 98 * resources (and in particular any grant mappings) in a timely 99 * manner. 100 * 101 * NOTE: this protocol is intended to allow for better error behaviour 102 * and recovery between two cooperating peers. It does not cover the 103 * case of a malicious peer who may continue to hold resources open. 104 */ 105 106 /* 107 * Grant Table Interface (making use of grants from other domains) 108 */ 109 110 typedef struct xengntdev_handle xengnttab_handle; 111 112 /* 113 * Returns a handle onto the grant table driver. Logs errors. 114 * 115 * Note: After fork(2) a child process must not use any opened gnttab 116 * handle inherited from their parent, nor access any grant mapped 117 * areas associated with that handle. 118 * 119 * The child must open a new handle if they want to interact with 120 * gnttab. 121 * 122 * Calling exec(2) in a child will safely (and reliably) reclaim any 123 * resources which were allocated via a xengnttab_handle in the parent. 124 * 125 * A child which does not call exec(2) may safely call 126 * xengnttab_close() on a xengnttab_handle inherited from their 127 * parent. This will attempt to reclaim any resources associated with 128 * that handle. Note that in some implementations this reclamation may 129 * not be completely effective, in this case any affected resources 130 * remain allocated. 131 * 132 * Calling xengnttab_close() is the only safe operation on a 133 * xengnttab_handle which has been inherited. xengnttab_unmap() must 134 * not be called under such circumstances. 135 */ 136 xengnttab_handle *xengnttab_open(struct xentoollog_logger *logger, 137 unsigned open_flags); 138 139 /* 140 * Close a handle previously allocated with xengnttab_open(), 141 * including unmaping any current grant maps. Never logs errors. 142 * 143 * Under normal circumstances (i.e. not in the child after a fork) 144 * xengnttab_unmap() should be used on all mappings allocated through 145 * a xengnttab_handle prior to closing the handle in order to free up 146 * resources associated with those mappings. 147 * 148 * This is the only function which may be safely called on a 149 * xengnttab_handle in a child after a fork. 150 */ 151 int xengnttab_close(xengnttab_handle *xgt); 152 153 154 /* 155 * Return the fd used internally by xengnttab. selecting on it is not 156 * useful. But it could be useful for unusual use cases; perhaps, 157 * passing to other programs, calling ioctls on directly, or maybe 158 * calling fcntl. 159 */ 160 int xengnttab_fd(xengnttab_handle *xgt); 161 162 /** 163 * Memory maps a grant reference from one domain to a local address range. 164 * Mappings should be unmapped with xengnttab_unmap. Logs errors. 165 * 166 * @parm xgt a handle on an open grant table interface 167 * @parm domid the domain to map memory from 168 * @parm ref the grant reference ID to map 169 * @parm prot same flag as in mmap() 170 */ 171 void *xengnttab_map_grant_ref(xengnttab_handle *xgt, 172 uint32_t domid, 173 uint32_t ref, 174 int prot); 175 176 /** 177 * Memory maps one or more grant references from one or more domains to a 178 * contiguous local address range. Mappings should be unmapped with 179 * xengnttab_unmap. Logs errors. 180 * 181 * On failure (including partial failure) sets errno and returns 182 * NULL. On partial failure no mappings are established (any partial 183 * work is undone). 184 * 185 * @parm xgt a handle on an open grant table interface 186 * @parm count the number of grant references to be mapped 187 * @parm domids an array of @count domain IDs by which the corresponding @refs 188 * were granted 189 * @parm refs an array of @count grant references to be mapped 190 * @parm prot same flag as in mmap() 191 */ 192 void *xengnttab_map_grant_refs(xengnttab_handle *xgt, 193 uint32_t count, 194 uint32_t *domids, 195 uint32_t *refs, 196 int prot); 197 198 /** 199 * Memory maps one or more grant references from one domain to a 200 * contiguous local address range. Mappings should be unmapped with 201 * xengnttab_unmap. Logs errors. 202 * 203 * This call is equivalent to calling @xengnttab_map_grant_refs with a 204 * @domids array with every entry set to @domid. 205 * 206 * @parm xgt a handle on an open grant table interface 207 * @parm count the number of grant references to be mapped 208 * @parm domid the domain to map memory from 209 * @parm refs an array of @count grant references to be mapped 210 * @parm prot same flag as in mmap() 211 */ 212 void *xengnttab_map_domain_grant_refs(xengnttab_handle *xgt, 213 uint32_t count, 214 uint32_t domid, 215 uint32_t *refs, 216 int prot); 217 218 /** 219 * Memory maps a grant reference from one domain to a local address range. 220 * Mappings should be unmapped with xengnttab_unmap. If notify_offset or 221 * notify_port are not -1, this version will attempt to set up an unmap 222 * notification at the given offset and event channel. When the page is 223 * unmapped, the byte at the given offset will be zeroed and a wakeup will be 224 * sent to the given event channel. Logs errors. 225 * 226 * On failure sets errno and returns NULL. 227 * 228 * If notify_offset or notify_port are requested and cannot be set up 229 * an error will be returned and no mapping will be made. 230 * 231 * @parm xgt a handle on an open grant table interface 232 * @parm domid the domain to map memory from 233 * @parm ref the grant reference ID to map 234 * @parm prot same flag as in mmap() 235 * @parm notify_offset The byte offset in the page to use for unmap 236 * notification; -1 for none. 237 * @parm notify_port The event channel port to use for unmap notify, or -1 238 */ 239 void *xengnttab_map_grant_ref_notify(xengnttab_handle *xgt, 240 uint32_t domid, 241 uint32_t ref, 242 int prot, 243 uint32_t notify_offset, 244 evtchn_port_t notify_port); 245 246 /** 247 * Unmaps the @count pages starting at @start_address, which were 248 * mapped by a call to xengnttab_map_grant_ref, 249 * xengnttab_map_grant_refs or xengnttab_map_grant_ref_notify. Never 250 * logs. 251 * 252 * If the mapping was made using xengnttab_map_grant_ref_notify() with 253 * either notify_offset or notify_port then the peer will be notified. 254 */ 255 int xengnttab_unmap(xengnttab_handle *xgt, void *start_address, uint32_t count); 256 257 /** 258 * Sets the maximum number of grants that may be mapped by the given 259 * instance to @count. Never logs. 260 * 261 * N.B. This function must be called after opening the handle, and before any 262 * other functions are invoked on it. 263 * 264 * N.B. When variable-length grants are mapped, fragmentation may be observed, 265 * and it may not be possible to satisfy requests up to the maximum number 266 * of grants. 267 */ 268 int xengnttab_set_max_grants(xengnttab_handle *xgt, 269 uint32_t nr_grants); 270 271 struct xengnttab_grant_copy_segment { 272 union xengnttab_copy_ptr { 273 void *virt; 274 struct { 275 uint32_t ref; 276 uint16_t offset; 277 uint16_t domid; 278 } foreign; 279 } source, dest; 280 uint16_t len; 281 uint16_t flags; 282 int16_t status; 283 }; 284 285 typedef struct xengnttab_grant_copy_segment xengnttab_grant_copy_segment_t; 286 287 /** 288 * Copy memory from or to grant references. The information of each operations 289 * are contained in 'xengnttab_grant_copy_segment_t'. The @flag value indicate 290 * the direction of an operation (GNTCOPY_source_gref\GNTCOPY_dest_gref). 291 * 292 * For each segment, @virt may cross a page boundary but @offset + @len 293 * must not exceed XEN_PAGE_SIZE. 294 */ 295 int xengnttab_grant_copy(xengnttab_handle *xgt, 296 uint32_t count, 297 xengnttab_grant_copy_segment_t *segs); 298 299 /* 300 * Flags to be used while requesting memory mapping's backing storage 301 * to be allocated with DMA API. 302 */ 303 304 /* 305 * The buffer is backed with memory allocated with dma_alloc_wc. 306 */ 307 #define GNTDEV_DMA_FLAG_WC (1 << 0) 308 309 /* 310 * The buffer is backed with memory allocated with dma_alloc_coherent. 311 */ 312 #define GNTDEV_DMA_FLAG_COHERENT (1 << 1) 313 314 /** 315 * Create a dma-buf [1] from grant references @refs of count @count provided 316 * by the foreign domain @domid with flags @flags. 317 * 318 * By default dma-buf is backed by system memory pages, but by providing 319 * one of the GNTDEV_DMA_FLAG_XXX flags it can also be created as 320 * a DMA write-combine or coherent buffer. 321 * 322 * Returns 0 if dma-buf was successfully created and the corresponding 323 * dma-buf's file descriptor is returned in @fd. 324 * 325 * [1] https://elixir.bootlin.com/linux/latest/source/Documentation/driver-api/dma-buf.rst 326 */ 327 int xengnttab_dmabuf_exp_from_refs(xengnttab_handle *xgt, uint32_t domid, 328 uint32_t flags, uint32_t count, 329 const uint32_t *refs, uint32_t *fd); 330 331 /* 332 * This will block until the dma-buf with the file descriptor @fd is 333 * released. This is only valid for buffers created with 334 * IOCTL_GNTDEV_DMABUF_EXP_FROM_REFS. 335 * 336 * If withing @wait_to_ms milliseconds the buffer is not released 337 * then -ETIMEDOUT error is returned. 338 * If the buffer with file descriptor @fd does not exist or has already 339 * been released, then -ENOENT is returned. For valid file descriptors 340 * this must not be treated as error. 341 */ 342 int xengnttab_dmabuf_exp_wait_released(xengnttab_handle *xgt, uint32_t fd, 343 uint32_t wait_to_ms); 344 345 /* 346 * Import a dma-buf with file descriptor @fd and export granted references 347 * to the pages of that dma-buf into array @refs of size @count. 348 */ 349 int xengnttab_dmabuf_imp_to_refs(xengnttab_handle *xgt, uint32_t domid, 350 uint32_t fd, uint32_t count, uint32_t *refs); 351 352 /* 353 * This will close all references to an imported buffer, so it can be 354 * released by the owner. This is only valid for buffers created with 355 * IOCTL_GNTDEV_DMABUF_IMP_TO_REFS. 356 */ 357 int xengnttab_dmabuf_imp_release(xengnttab_handle *xgt, uint32_t fd); 358 359 /* 360 * Grant Sharing Interface (allocating and granting pages to others) 361 */ 362 363 typedef struct xengntdev_handle xengntshr_handle; 364 365 /* 366 * Returns a handle onto the grant sharing driver. Logs errors. 367 * 368 * Note: After fork(2) a child process must not use any opened gntshr 369 * handle inherited from their parent, nor access any grant mapped 370 * areas associated with that handle. 371 * 372 * The child must open a new handle if they want to interact with 373 * gntshr. 374 * 375 * Calling exec(2) in a child will safely (and reliably) reclaim any 376 * resources which were allocated via a xengntshr_handle in the 377 * parent. 378 * 379 * A child which does not call exec(2) may safely call 380 * xengntshr_close() on a xengntshr_handle inherited from their 381 * parent. This will attempt to reclaim any resources associated with 382 * that handle. Note that in some implementations this reclamation may 383 * not be completely effective, in this case any affected resources 384 * remain allocated. 385 * 386 * Calling xengntshr_close() is the only safe operation on a 387 * xengntshr_handle which has been inherited. 388 */ 389 xengntshr_handle *xengntshr_open(struct xentoollog_logger *logger, 390 unsigned open_flags); 391 392 /* 393 * Close a handle previously allocated with xengntshr_open(). 394 * Never logs errors. 395 * 396 * Under normal circumstances (i.e. not in the child after a fork) 397 * xengntshr_unmap() should be used on all mappings allocated through 398 * a xengnttab_handle prior to closing the handle in order to free up 399 * resources associated with those mappings. 400 * 401 * xengntshr_close() is the only function which may be safely called 402 * on a xengntshr_handle in a child after a fork. xengntshr_unshare() 403 * must not be called under such circumstances. 404 */ 405 int xengntshr_close(xengntshr_handle *xgs); 406 407 /* 408 * Return the fd used internally by xengntshr. selecting on it is not 409 * useful. But it could be useful for unusual use cases; perhaps, 410 * passing to other programs, calling ioctls on directly, or maybe 411 * calling fcntl. 412 */ 413 int xengntshr_fd(xengntshr_handle *xgs); 414 415 /** 416 * Allocates and shares pages with another domain. 417 * 418 * On failure sets errno and returns NULL. No allocations will be made. 419 * 420 * This library only provides functionality for sharing memory 421 * allocated via this call, memory from elsewhere (malloc, mmap etc) 422 * cannot be shared here. 423 * 424 * @parm xgs a handle to an open grant sharing instance 425 * @parm domid the domain to share memory with 426 * @parm count the number of pages to share 427 * @parm refs the grant references of the pages (output) 428 * @parm writable true if the other domain can write to the pages 429 * @return local mapping of the pages 430 */ 431 void *xengntshr_share_pages(xengntshr_handle *xgs, uint32_t domid, 432 int count, uint32_t *refs, int writable); 433 434 /** 435 * Creates and shares a page with another domain, with unmap notification. 436 * 437 * @parm xgs a handle to an open grant sharing instance 438 * @parm domid the domain to share memory with 439 * @parm refs the grant reference of the pages (output) 440 * @parm writable true if the other domain can write to the page 441 * @parm notify_offset The byte offset in the page to use for unmap 442 * notification; -1 for none. 443 * @parm notify_port The event channel port to use for unmap notify, or -1 444 * @return local mapping of the page 445 */ 446 void *xengntshr_share_page_notify(xengntshr_handle *xgs, uint32_t domid, 447 uint32_t *ref, int writable, 448 uint32_t notify_offset, 449 evtchn_port_t notify_port); 450 451 /** 452 * Unmaps the @count pages starting at @start_address, which were 453 * mapped by a call to xengntshr_share_*. Never logs. 454 * 455 * If the mapping was made using xengntshr_share_page_notify() with 456 * either notify_offset or notify_port then the peer will be notified. 457 */ 458 int xengntshr_unshare(xengntshr_handle *xgs, void *start_address, uint32_t count); 459 460 #endif 461 462 /* 463 * Local variables: 464 * mode: C 465 * c-file-style: "BSD" 466 * c-basic-offset: 4 467 * tab-width: 4 468 * indent-tabs-mode: nil 469 * End: 470 */ 471