1 /* 2 * Intel MIC Platform Software Stack (MPSS) 3 * 4 * This file is provided under a dual BSD/GPLv2 license. When using or 5 * redistributing this file, you may do so under either license. 6 * 7 * GPL LICENSE SUMMARY 8 * 9 * Copyright(c) 2014 Intel Corporation. 10 * 11 * This program is free software; you can redistribute it and/or modify 12 * it under the terms of version 2 of the GNU General Public License as 13 * published by the Free Software Foundation. 14 * 15 * This program is distributed in the hope that it will be useful, but 16 * WITHOUT ANY WARRANTY; without even the implied warranty of 17 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 18 * General Public License for more details. 19 * 20 * BSD LICENSE 21 * 22 * Copyright(c) 2014 Intel Corporation. 23 * 24 * Redistribution and use in source and binary forms, with or without 25 * modification, are permitted provided that the following conditions 26 * are met: 27 * 28 * * Redistributions of source code must retain the above copyright 29 * notice, this list of conditions and the following disclaimer. 30 * * Redistributions in binary form must reproduce the above copyright 31 * notice, this list of conditions and the following disclaimer in 32 * the documentation and/or other materials provided with the 33 * distribution. 34 * * Neither the name of Intel Corporation nor the names of its 35 * contributors may be used to endorse or promote products derived 36 * from this software without specific prior written permission. 37 * 38 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 39 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 40 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 41 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT 42 * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 43 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 44 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 45 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 46 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 47 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 48 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 49 * 50 * Intel SCIF driver. 51 * 52 */ 53 #ifndef __SCIF_H__ 54 #define __SCIF_H__ 55 56 #include <linux/types.h> 57 #include <linux/poll.h> 58 #include <linux/device.h> 59 #include <linux/scif_ioctl.h> 60 61 #define SCIF_ACCEPT_SYNC 1 62 #define SCIF_SEND_BLOCK 1 63 #define SCIF_RECV_BLOCK 1 64 65 enum { 66 SCIF_PROT_READ = (1 << 0), 67 SCIF_PROT_WRITE = (1 << 1) 68 }; 69 70 enum { 71 SCIF_MAP_FIXED = 0x10, 72 SCIF_MAP_KERNEL = 0x20, 73 }; 74 75 enum { 76 SCIF_FENCE_INIT_SELF = (1 << 0), 77 SCIF_FENCE_INIT_PEER = (1 << 1), 78 SCIF_SIGNAL_LOCAL = (1 << 4), 79 SCIF_SIGNAL_REMOTE = (1 << 5) 80 }; 81 82 enum { 83 SCIF_RMA_USECPU = (1 << 0), 84 SCIF_RMA_USECACHE = (1 << 1), 85 SCIF_RMA_SYNC = (1 << 2), 86 SCIF_RMA_ORDERED = (1 << 3) 87 }; 88 89 /* End of SCIF Admin Reserved Ports */ 90 #define SCIF_ADMIN_PORT_END 1024 91 92 /* End of SCIF Reserved Ports */ 93 #define SCIF_PORT_RSVD 1088 94 95 typedef struct scif_endpt *scif_epd_t; 96 typedef struct scif_pinned_pages *scif_pinned_pages_t; 97 98 /** 99 * struct scif_range - SCIF registered range used in kernel mode 100 * @cookie: cookie used internally by SCIF 101 * @nr_pages: number of pages of PAGE_SIZE 102 * @prot_flags: R/W protection 103 * @phys_addr: Array of bus addresses 104 * @va: Array of kernel virtual addresses backed by the pages in the phys_addr 105 * array. The va is populated only when called on the host for a remote 106 * SCIF connection on MIC. This is required to support the use case of DMA 107 * between MIC and another device which is not a SCIF node e.g., an IB or 108 * ethernet NIC. 109 */ 110 struct scif_range { 111 void *cookie; 112 int nr_pages; 113 int prot_flags; 114 dma_addr_t *phys_addr; 115 void __iomem **va; 116 }; 117 118 /** 119 * struct scif_pollepd - SCIF endpoint to be monitored via scif_poll 120 * @epd: SCIF endpoint 121 * @events: requested events 122 * @revents: returned events 123 */ 124 struct scif_pollepd { 125 scif_epd_t epd; 126 short events; 127 short revents; 128 }; 129 130 /** 131 * scif_peer_dev - representation of a peer SCIF device 132 * 133 * Peer devices show up as PCIe devices for the mgmt node but not the cards. 134 * The mgmt node discovers all the cards on the PCIe bus and informs the other 135 * cards about their peers. Upon notification of a peer a node adds a peer 136 * device to the peer bus to maintain symmetry in the way devices are 137 * discovered across all nodes in the SCIF network. 138 * 139 * @dev: underlying device 140 * @dnode - The destination node which this device will communicate with. 141 */ 142 struct scif_peer_dev { 143 struct device dev; 144 u8 dnode; 145 }; 146 147 /** 148 * scif_client - representation of a SCIF client 149 * @name: client name 150 * @probe - client method called when a peer device is registered 151 * @remove - client method called when a peer device is unregistered 152 * @si - subsys_interface used internally for implementing SCIF clients 153 */ 154 struct scif_client { 155 const char *name; 156 void (*probe)(struct scif_peer_dev *spdev); 157 void (*remove)(struct scif_peer_dev *spdev); 158 struct subsys_interface si; 159 }; 160 161 #define SCIF_OPEN_FAILED ((scif_epd_t)-1) 162 #define SCIF_REGISTER_FAILED ((off_t)-1) 163 #define SCIF_MMAP_FAILED ((void *)-1) 164 165 /** 166 * scif_open() - Create an endpoint 167 * 168 * Return: 169 * Upon successful completion, scif_open() returns an endpoint descriptor to 170 * be used in subsequent SCIF functions calls to refer to that endpoint; 171 * otherwise in user mode SCIF_OPEN_FAILED (that is ((scif_epd_t)-1)) is 172 * returned and errno is set to indicate the error; in kernel mode a NULL 173 * scif_epd_t is returned. 174 * 175 * Errors: 176 * ENOMEM - Insufficient kernel memory was available 177 */ 178 scif_epd_t scif_open(void); 179 180 /** 181 * scif_bind() - Bind an endpoint to a port 182 * @epd: endpoint descriptor 183 * @pn: port number 184 * 185 * scif_bind() binds endpoint epd to port pn, where pn is a port number on the 186 * local node. If pn is zero, a port number greater than or equal to 187 * SCIF_PORT_RSVD is assigned and returned. Each endpoint may be bound to 188 * exactly one local port. Ports less than 1024 when requested can only be bound 189 * by system (or root) processes or by processes executed by privileged users. 190 * 191 * Return: 192 * Upon successful completion, scif_bind() returns the port number to which epd 193 * is bound; otherwise in user mode -1 is returned and errno is set to 194 * indicate the error; in kernel mode the negative of one of the following 195 * errors is returned. 196 * 197 * Errors: 198 * EBADF, ENOTTY - epd is not a valid endpoint descriptor 199 * EINVAL - the endpoint or the port is already bound 200 * EISCONN - The endpoint is already connected 201 * ENOSPC - No port number available for assignment 202 * EACCES - The port requested is protected and the user is not the superuser 203 */ 204 int scif_bind(scif_epd_t epd, u16 pn); 205 206 /** 207 * scif_listen() - Listen for connections on an endpoint 208 * @epd: endpoint descriptor 209 * @backlog: maximum pending connection requests 210 * 211 * scif_listen() marks the endpoint epd as a listening endpoint - that is, as 212 * an endpoint that will be used to accept incoming connection requests. Once 213 * so marked, the endpoint is said to be in the listening state and may not be 214 * used as the endpoint of a connection. 215 * 216 * The endpoint, epd, must have been bound to a port. 217 * 218 * The backlog argument defines the maximum length to which the queue of 219 * pending connections for epd may grow. If a connection request arrives when 220 * the queue is full, the client may receive an error with an indication that 221 * the connection was refused. 222 * 223 * Return: 224 * Upon successful completion, scif_listen() returns 0; otherwise in user mode 225 * -1 is returned and errno is set to indicate the error; in kernel mode the 226 * negative of one of the following errors is returned. 227 * 228 * Errors: 229 * EBADF, ENOTTY - epd is not a valid endpoint descriptor 230 * EINVAL - the endpoint is not bound to a port 231 * EISCONN - The endpoint is already connected or listening 232 */ 233 int scif_listen(scif_epd_t epd, int backlog); 234 235 /** 236 * scif_connect() - Initiate a connection on a port 237 * @epd: endpoint descriptor 238 * @dst: global id of port to which to connect 239 * 240 * The scif_connect() function requests the connection of endpoint epd to remote 241 * port dst. If the connection is successful, a peer endpoint, bound to dst, is 242 * created on node dst.node. On successful return, the connection is complete. 243 * 244 * If the endpoint epd has not already been bound to a port, scif_connect() 245 * will bind it to an unused local port. 246 * 247 * A connection is terminated when an endpoint of the connection is closed, 248 * either explicitly by scif_close(), or when a process that owns one of the 249 * endpoints of the connection is terminated. 250 * 251 * In user space, scif_connect() supports an asynchronous connection mode 252 * if the application has set the O_NONBLOCK flag on the endpoint via the 253 * fcntl() system call. Setting this flag will result in the calling process 254 * not to wait during scif_connect(). 255 * 256 * Return: 257 * Upon successful completion, scif_connect() returns the port ID to which the 258 * endpoint, epd, is bound; otherwise in user mode -1 is returned and errno is 259 * set to indicate the error; in kernel mode the negative of one of the 260 * following errors is returned. 261 * 262 * Errors: 263 * EBADF, ENOTTY - epd is not a valid endpoint descriptor 264 * ECONNREFUSED - The destination was not listening for connections or refused 265 * the connection request 266 * EINVAL - dst.port is not a valid port ID 267 * EISCONN - The endpoint is already connected 268 * ENOMEM - No buffer space is available 269 * ENODEV - The destination node does not exist, or the node is lost or existed, 270 * but is not currently in the network since it may have crashed 271 * ENOSPC - No port number available for assignment 272 * EOPNOTSUPP - The endpoint is listening and cannot be connected 273 */ 274 int scif_connect(scif_epd_t epd, struct scif_port_id *dst); 275 276 /** 277 * scif_accept() - Accept a connection on an endpoint 278 * @epd: endpoint descriptor 279 * @peer: global id of port to which connected 280 * @newepd: new connected endpoint descriptor 281 * @flags: flags 282 * 283 * The scif_accept() call extracts the first connection request from the queue 284 * of pending connections for the port on which epd is listening. scif_accept() 285 * creates a new endpoint, bound to the same port as epd, and allocates a new 286 * SCIF endpoint descriptor, returned in newepd, for the endpoint. The new 287 * endpoint is connected to the endpoint through which the connection was 288 * requested. epd is unaffected by this call, and remains in the listening 289 * state. 290 * 291 * On successful return, peer holds the global port identifier (node id and 292 * local port number) of the port which requested the connection. 293 * 294 * A connection is terminated when an endpoint of the connection is closed, 295 * either explicitly by scif_close(), or when a process that owns one of the 296 * endpoints of the connection is terminated. 297 * 298 * The number of connections that can (subsequently) be accepted on epd is only 299 * limited by system resources (memory). 300 * 301 * The flags argument is formed by OR'ing together zero or more of the 302 * following values. 303 * SCIF_ACCEPT_SYNC - block until a connection request is presented. If 304 * SCIF_ACCEPT_SYNC is not in flags, and no pending 305 * connections are present on the queue, scif_accept() 306 * fails with an EAGAIN error 307 * 308 * In user mode, the select() and poll() functions can be used to determine 309 * when there is a connection request. In kernel mode, the scif_poll() 310 * function may be used for this purpose. A readable event will be delivered 311 * when a connection is requested. 312 * 313 * Return: 314 * Upon successful completion, scif_accept() returns 0; otherwise in user mode 315 * -1 is returned and errno is set to indicate the error; in kernel mode the 316 * negative of one of the following errors is returned. 317 * 318 * Errors: 319 * EAGAIN - SCIF_ACCEPT_SYNC is not set and no connections are present to be 320 * accepted or SCIF_ACCEPT_SYNC is not set and remote node failed to complete 321 * its connection request 322 * EBADF, ENOTTY - epd is not a valid endpoint descriptor 323 * EINTR - Interrupted function 324 * EINVAL - epd is not a listening endpoint, or flags is invalid, or peer is 325 * NULL, or newepd is NULL 326 * ENODEV - The requesting node is lost or existed, but is not currently in the 327 * network since it may have crashed 328 * ENOMEM - Not enough space 329 * ENOENT - Secondary part of epd registration failed 330 */ 331 int scif_accept(scif_epd_t epd, struct scif_port_id *peer, scif_epd_t 332 *newepd, int flags); 333 334 /** 335 * scif_close() - Close an endpoint 336 * @epd: endpoint descriptor 337 * 338 * scif_close() closes an endpoint and performs necessary teardown of 339 * facilities associated with that endpoint. 340 * 341 * If epd is a listening endpoint then it will no longer accept connection 342 * requests on the port to which it is bound. Any pending connection requests 343 * are rejected. 344 * 345 * If epd is a connected endpoint, then its peer endpoint is also closed. RMAs 346 * which are in-process through epd or its peer endpoint will complete before 347 * scif_close() returns. Registered windows of the local and peer endpoints are 348 * released as if scif_unregister() was called against each window. 349 * 350 * Closing a SCIF endpoint does not affect local registered memory mapped by 351 * a SCIF endpoint on a remote node. The local memory remains mapped by the peer 352 * SCIF endpoint explicitly removed by calling munmap(..) by the peer. 353 * 354 * If the peer endpoint's receive queue is not empty at the time that epd is 355 * closed, then the peer endpoint can be passed as the endpoint parameter to 356 * scif_recv() until the receive queue is empty. 357 * 358 * epd is freed and may no longer be accessed. 359 * 360 * Return: 361 * Upon successful completion, scif_close() returns 0; otherwise in user mode 362 * -1 is returned and errno is set to indicate the error; in kernel mode the 363 * negative of one of the following errors is returned. 364 * 365 * Errors: 366 * EBADF, ENOTTY - epd is not a valid endpoint descriptor 367 */ 368 int scif_close(scif_epd_t epd); 369 370 /** 371 * scif_send() - Send a message 372 * @epd: endpoint descriptor 373 * @msg: message buffer address 374 * @len: message length 375 * @flags: blocking mode flags 376 * 377 * scif_send() sends data to the peer of endpoint epd. Up to len bytes of data 378 * are copied from memory starting at address msg. On successful execution the 379 * return value of scif_send() is the number of bytes that were sent, and is 380 * zero if no bytes were sent because len was zero. scif_send() may be called 381 * only when the endpoint is in a connected state. 382 * 383 * If a scif_send() call is non-blocking, then it sends only those bytes which 384 * can be sent without waiting, up to a maximum of len bytes. 385 * 386 * If a scif_send() call is blocking, then it normally returns after sending 387 * all len bytes. If a blocking call is interrupted or the connection is 388 * reset, the call is considered successful if some bytes were sent or len is 389 * zero, otherwise the call is considered unsuccessful. 390 * 391 * In user mode, the select() and poll() functions can be used to determine 392 * when the send queue is not full. In kernel mode, the scif_poll() function 393 * may be used for this purpose. 394 * 395 * It is recommended that scif_send()/scif_recv() only be used for short 396 * control-type message communication between SCIF endpoints. The SCIF RMA 397 * APIs are expected to provide better performance for transfer sizes of 398 * 1024 bytes or longer for the current MIC hardware and software 399 * implementation. 400 * 401 * scif_send() will block until the entire message is sent if SCIF_SEND_BLOCK 402 * is passed as the flags argument. 403 * 404 * Return: 405 * Upon successful completion, scif_send() returns the number of bytes sent; 406 * otherwise in user mode -1 is returned and errno is set to indicate the 407 * error; in kernel mode the negative of one of the following errors is 408 * returned. 409 * 410 * Errors: 411 * EBADF, ENOTTY - epd is not a valid endpoint descriptor 412 * ECONNRESET - Connection reset by peer 413 * EINVAL - flags is invalid, or len is negative 414 * ENODEV - The remote node is lost or existed, but is not currently in the 415 * network since it may have crashed 416 * ENOMEM - Not enough space 417 * ENOTCONN - The endpoint is not connected 418 */ 419 int scif_send(scif_epd_t epd, void *msg, int len, int flags); 420 421 /** 422 * scif_recv() - Receive a message 423 * @epd: endpoint descriptor 424 * @msg: message buffer address 425 * @len: message buffer length 426 * @flags: blocking mode flags 427 * 428 * scif_recv() receives data from the peer of endpoint epd. Up to len bytes of 429 * data are copied to memory starting at address msg. On successful execution 430 * the return value of scif_recv() is the number of bytes that were received, 431 * and is zero if no bytes were received because len was zero. scif_recv() may 432 * be called only when the endpoint is in a connected state. 433 * 434 * If a scif_recv() call is non-blocking, then it receives only those bytes 435 * which can be received without waiting, up to a maximum of len bytes. 436 * 437 * If a scif_recv() call is blocking, then it normally returns after receiving 438 * all len bytes. If the blocking call was interrupted due to a disconnection, 439 * subsequent calls to scif_recv() will copy all bytes received upto the point 440 * of disconnection. 441 * 442 * In user mode, the select() and poll() functions can be used to determine 443 * when data is available to be received. In kernel mode, the scif_poll() 444 * function may be used for this purpose. 445 * 446 * It is recommended that scif_send()/scif_recv() only be used for short 447 * control-type message communication between SCIF endpoints. The SCIF RMA 448 * APIs are expected to provide better performance for transfer sizes of 449 * 1024 bytes or longer for the current MIC hardware and software 450 * implementation. 451 * 452 * scif_recv() will block until the entire message is received if 453 * SCIF_RECV_BLOCK is passed as the flags argument. 454 * 455 * Return: 456 * Upon successful completion, scif_recv() returns the number of bytes 457 * received; otherwise in user mode -1 is returned and errno is set to 458 * indicate the error; in kernel mode the negative of one of the following 459 * errors is returned. 460 * 461 * Errors: 462 * EAGAIN - The destination node is returning from a low power state 463 * EBADF, ENOTTY - epd is not a valid endpoint descriptor 464 * ECONNRESET - Connection reset by peer 465 * EINVAL - flags is invalid, or len is negative 466 * ENODEV - The remote node is lost or existed, but is not currently in the 467 * network since it may have crashed 468 * ENOMEM - Not enough space 469 * ENOTCONN - The endpoint is not connected 470 */ 471 int scif_recv(scif_epd_t epd, void *msg, int len, int flags); 472 473 /** 474 * scif_register() - Mark a memory region for remote access. 475 * @epd: endpoint descriptor 476 * @addr: starting virtual address 477 * @len: length of range 478 * @offset: offset of window 479 * @prot_flags: read/write protection flags 480 * @map_flags: mapping flags 481 * 482 * The scif_register() function opens a window, a range of whole pages of the 483 * registered address space of the endpoint epd, starting at offset po and 484 * continuing for len bytes. The value of po, further described below, is a 485 * function of the parameters offset and len, and the value of map_flags. Each 486 * page of the window represents the physical memory page which backs the 487 * corresponding page of the range of virtual address pages starting at addr 488 * and continuing for len bytes. addr and len are constrained to be multiples 489 * of the page size. A successful scif_register() call returns po. 490 * 491 * When SCIF_MAP_FIXED is set in the map_flags argument, po will be offset 492 * exactly, and offset is constrained to be a multiple of the page size. The 493 * mapping established by scif_register() will not replace any existing 494 * registration; an error is returned if any page within the range [offset, 495 * offset + len - 1] intersects an existing window. 496 * 497 * When SCIF_MAP_FIXED is not set, the implementation uses offset in an 498 * implementation-defined manner to arrive at po. The po value so chosen will 499 * be an area of the registered address space that the implementation deems 500 * suitable for a mapping of len bytes. An offset value of 0 is interpreted as 501 * granting the implementation complete freedom in selecting po, subject to 502 * constraints described below. A non-zero value of offset is taken to be a 503 * suggestion of an offset near which the mapping should be placed. When the 504 * implementation selects a value for po, it does not replace any extant 505 * window. In all cases, po will be a multiple of the page size. 506 * 507 * The physical pages which are so represented by a window are available for 508 * access in calls to mmap(), scif_readfrom(), scif_writeto(), 509 * scif_vreadfrom(), and scif_vwriteto(). While a window is registered, the 510 * physical pages represented by the window will not be reused by the memory 511 * subsystem for any other purpose. Note that the same physical page may be 512 * represented by multiple windows. 513 * 514 * Subsequent operations which change the memory pages to which virtual 515 * addresses are mapped (such as mmap(), munmap()) have no effect on 516 * existing window. 517 * 518 * If the process will fork(), it is recommended that the registered 519 * virtual address range be marked with MADV_DONTFORK. Doing so will prevent 520 * problems due to copy-on-write semantics. 521 * 522 * The prot_flags argument is formed by OR'ing together one or more of the 523 * following values. 524 * SCIF_PROT_READ - allow read operations from the window 525 * SCIF_PROT_WRITE - allow write operations to the window 526 * 527 * Return: 528 * Upon successful completion, scif_register() returns the offset at which the 529 * mapping was placed (po); otherwise in user mode SCIF_REGISTER_FAILED (that 530 * is (off_t *)-1) is returned and errno is set to indicate the error; in 531 * kernel mode the negative of one of the following errors is returned. 532 * 533 * Errors: 534 * EADDRINUSE - SCIF_MAP_FIXED is set in map_flags, and pages in the range 535 * [offset, offset + len -1] are already registered 536 * EAGAIN - The mapping could not be performed due to lack of resources 537 * EBADF, ENOTTY - epd is not a valid endpoint descriptor 538 * ECONNRESET - Connection reset by peer 539 * EINVAL - map_flags is invalid, or prot_flags is invalid, or SCIF_MAP_FIXED is 540 * set in flags, and offset is not a multiple of the page size, or addr is not a 541 * multiple of the page size, or len is not a multiple of the page size, or is 542 * 0, or offset is negative 543 * ENODEV - The remote node is lost or existed, but is not currently in the 544 * network since it may have crashed 545 * ENOMEM - Not enough space 546 * ENOTCONN -The endpoint is not connected 547 */ 548 off_t scif_register(scif_epd_t epd, void *addr, size_t len, off_t offset, 549 int prot_flags, int map_flags); 550 551 /** 552 * scif_unregister() - Mark a memory region for remote access. 553 * @epd: endpoint descriptor 554 * @offset: start of range to unregister 555 * @len: length of range to unregister 556 * 557 * The scif_unregister() function closes those previously registered windows 558 * which are entirely within the range [offset, offset + len - 1]. It is an 559 * error to specify a range which intersects only a subrange of a window. 560 * 561 * On a successful return, pages within the window may no longer be specified 562 * in calls to mmap(), scif_readfrom(), scif_writeto(), scif_vreadfrom(), 563 * scif_vwriteto(), scif_get_pages, and scif_fence_signal(). The window, 564 * however, continues to exist until all previous references against it are 565 * removed. A window is referenced if there is a mapping to it created by 566 * mmap(), or if scif_get_pages() was called against the window 567 * (and the pages have not been returned via scif_put_pages()). A window is 568 * also referenced while an RMA, in which some range of the window is a source 569 * or destination, is in progress. Finally a window is referenced while some 570 * offset in that window was specified to scif_fence_signal(), and the RMAs 571 * marked by that call to scif_fence_signal() have not completed. While a 572 * window is in this state, its registered address space pages are not 573 * available for use in a new registered window. 574 * 575 * When all such references to the window have been removed, its references to 576 * all the physical pages which it represents are removed. Similarly, the 577 * registered address space pages of the window become available for 578 * registration in a new window. 579 * 580 * Return: 581 * Upon successful completion, scif_unregister() returns 0; otherwise in user 582 * mode -1 is returned and errno is set to indicate the error; in kernel mode 583 * the negative of one of the following errors is returned. In the event of an 584 * error, no windows are unregistered. 585 * 586 * Errors: 587 * EBADF, ENOTTY - epd is not a valid endpoint descriptor 588 * ECONNRESET - Connection reset by peer 589 * EINVAL - the range [offset, offset + len - 1] intersects a subrange of a 590 * window, or offset is negative 591 * ENODEV - The remote node is lost or existed, but is not currently in the 592 * network since it may have crashed 593 * ENOTCONN - The endpoint is not connected 594 * ENXIO - Offsets in the range [offset, offset + len - 1] are invalid for the 595 * registered address space of epd 596 */ 597 int scif_unregister(scif_epd_t epd, off_t offset, size_t len); 598 599 /** 600 * scif_readfrom() - Copy from a remote address space 601 * @epd: endpoint descriptor 602 * @loffset: offset in local registered address space to 603 * which to copy 604 * @len: length of range to copy 605 * @roffset: offset in remote registered address space 606 * from which to copy 607 * @rma_flags: transfer mode flags 608 * 609 * scif_readfrom() copies len bytes from the remote registered address space of 610 * the peer of endpoint epd, starting at the offset roffset to the local 611 * registered address space of epd, starting at the offset loffset. 612 * 613 * Each of the specified ranges [loffset, loffset + len - 1] and [roffset, 614 * roffset + len - 1] must be within some registered window or windows of the 615 * local and remote nodes. A range may intersect multiple registered windows, 616 * but only if those windows are contiguous in the registered address space. 617 * 618 * If rma_flags includes SCIF_RMA_USECPU, then the data is copied using 619 * programmed read/writes. Otherwise the data is copied using DMA. If rma_- 620 * flags includes SCIF_RMA_SYNC, then scif_readfrom() will return after the 621 * transfer is complete. Otherwise, the transfer may be performed asynchron- 622 * ously. The order in which any two asynchronous RMA operations complete 623 * is non-deterministic. The synchronization functions, scif_fence_mark()/ 624 * scif_fence_wait() and scif_fence_signal(), can be used to synchronize to 625 * the completion of asynchronous RMA operations on the same endpoint. 626 * 627 * The DMA transfer of individual bytes is not guaranteed to complete in 628 * address order. If rma_flags includes SCIF_RMA_ORDERED, then the last 629 * cacheline or partial cacheline of the source range will become visible on 630 * the destination node after all other transferred data in the source 631 * range has become visible on the destination node. 632 * 633 * The optimal DMA performance will likely be realized if both 634 * loffset and roffset are cacheline aligned (are a multiple of 64). Lower 635 * performance will likely be realized if loffset and roffset are not 636 * cacheline aligned but are separated by some multiple of 64. The lowest level 637 * of performance is likely if loffset and roffset are not separated by a 638 * multiple of 64. 639 * 640 * The rma_flags argument is formed by ORing together zero or more of the 641 * following values. 642 * SCIF_RMA_USECPU - perform the transfer using the CPU, otherwise use the DMA 643 * engine. 644 * SCIF_RMA_SYNC - perform the transfer synchronously, returning after the 645 * transfer has completed. Passing this flag results in the 646 * current implementation busy waiting and consuming CPU cycles 647 * while the DMA transfer is in progress for best performance by 648 * avoiding the interrupt latency. 649 * SCIF_RMA_ORDERED - ensure that the last cacheline or partial cacheline of 650 * the source range becomes visible on the destination node 651 * after all other transferred data in the source range has 652 * become visible on the destination 653 * 654 * Return: 655 * Upon successful completion, scif_readfrom() returns 0; otherwise in user 656 * mode -1 is returned and errno is set to indicate the error; in kernel mode 657 * the negative of one of the following errors is returned. 658 * 659 * Errors: 660 * EACCESS - Attempt to write to a read-only range 661 * EBADF, ENOTTY - epd is not a valid endpoint descriptor 662 * ECONNRESET - Connection reset by peer 663 * EINVAL - rma_flags is invalid 664 * ENODEV - The remote node is lost or existed, but is not currently in the 665 * network since it may have crashed 666 * ENOTCONN - The endpoint is not connected 667 * ENXIO - The range [loffset, loffset + len - 1] is invalid for the registered 668 * address space of epd, or, The range [roffset, roffset + len - 1] is invalid 669 * for the registered address space of the peer of epd, or loffset or roffset 670 * is negative 671 */ 672 int scif_readfrom(scif_epd_t epd, off_t loffset, size_t len, off_t 673 roffset, int rma_flags); 674 675 /** 676 * scif_writeto() - Copy to a remote address space 677 * @epd: endpoint descriptor 678 * @loffset: offset in local registered address space 679 * from which to copy 680 * @len: length of range to copy 681 * @roffset: offset in remote registered address space to 682 * which to copy 683 * @rma_flags: transfer mode flags 684 * 685 * scif_writeto() copies len bytes from the local registered address space of 686 * epd, starting at the offset loffset to the remote registered address space 687 * of the peer of endpoint epd, starting at the offset roffset. 688 * 689 * Each of the specified ranges [loffset, loffset + len - 1] and [roffset, 690 * roffset + len - 1] must be within some registered window or windows of the 691 * local and remote nodes. A range may intersect multiple registered windows, 692 * but only if those windows are contiguous in the registered address space. 693 * 694 * If rma_flags includes SCIF_RMA_USECPU, then the data is copied using 695 * programmed read/writes. Otherwise the data is copied using DMA. If rma_- 696 * flags includes SCIF_RMA_SYNC, then scif_writeto() will return after the 697 * transfer is complete. Otherwise, the transfer may be performed asynchron- 698 * ously. The order in which any two asynchronous RMA operations complete 699 * is non-deterministic. The synchronization functions, scif_fence_mark()/ 700 * scif_fence_wait() and scif_fence_signal(), can be used to synchronize to 701 * the completion of asynchronous RMA operations on the same endpoint. 702 * 703 * The DMA transfer of individual bytes is not guaranteed to complete in 704 * address order. If rma_flags includes SCIF_RMA_ORDERED, then the last 705 * cacheline or partial cacheline of the source range will become visible on 706 * the destination node after all other transferred data in the source 707 * range has become visible on the destination node. 708 * 709 * The optimal DMA performance will likely be realized if both 710 * loffset and roffset are cacheline aligned (are a multiple of 64). Lower 711 * performance will likely be realized if loffset and roffset are not cacheline 712 * aligned but are separated by some multiple of 64. The lowest level of 713 * performance is likely if loffset and roffset are not separated by a multiple 714 * of 64. 715 * 716 * The rma_flags argument is formed by ORing together zero or more of the 717 * following values. 718 * SCIF_RMA_USECPU - perform the transfer using the CPU, otherwise use the DMA 719 * engine. 720 * SCIF_RMA_SYNC - perform the transfer synchronously, returning after the 721 * transfer has completed. Passing this flag results in the 722 * current implementation busy waiting and consuming CPU cycles 723 * while the DMA transfer is in progress for best performance by 724 * avoiding the interrupt latency. 725 * SCIF_RMA_ORDERED - ensure that the last cacheline or partial cacheline of 726 * the source range becomes visible on the destination node 727 * after all other transferred data in the source range has 728 * become visible on the destination 729 * 730 * Return: 731 * Upon successful completion, scif_readfrom() returns 0; otherwise in user 732 * mode -1 is returned and errno is set to indicate the error; in kernel mode 733 * the negative of one of the following errors is returned. 734 * 735 * Errors: 736 * EACCESS - Attempt to write to a read-only range 737 * EBADF, ENOTTY - epd is not a valid endpoint descriptor 738 * ECONNRESET - Connection reset by peer 739 * EINVAL - rma_flags is invalid 740 * ENODEV - The remote node is lost or existed, but is not currently in the 741 * network since it may have crashed 742 * ENOTCONN - The endpoint is not connected 743 * ENXIO - The range [loffset, loffset + len - 1] is invalid for the registered 744 * address space of epd, or, The range [roffset , roffset + len -1] is invalid 745 * for the registered address space of the peer of epd, or loffset or roffset 746 * is negative 747 */ 748 int scif_writeto(scif_epd_t epd, off_t loffset, size_t len, off_t 749 roffset, int rma_flags); 750 751 /** 752 * scif_vreadfrom() - Copy from a remote address space 753 * @epd: endpoint descriptor 754 * @addr: address to which to copy 755 * @len: length of range to copy 756 * @roffset: offset in remote registered address space 757 * from which to copy 758 * @rma_flags: transfer mode flags 759 * 760 * scif_vreadfrom() copies len bytes from the remote registered address 761 * space of the peer of endpoint epd, starting at the offset roffset, to local 762 * memory, starting at addr. 763 * 764 * The specified range [roffset, roffset + len - 1] must be within some 765 * registered window or windows of the remote nodes. The range may 766 * intersect multiple registered windows, but only if those windows are 767 * contiguous in the registered address space. 768 * 769 * If rma_flags includes SCIF_RMA_USECPU, then the data is copied using 770 * programmed read/writes. Otherwise the data is copied using DMA. If rma_- 771 * flags includes SCIF_RMA_SYNC, then scif_vreadfrom() will return after the 772 * transfer is complete. Otherwise, the transfer may be performed asynchron- 773 * ously. The order in which any two asynchronous RMA operations complete 774 * is non-deterministic. The synchronization functions, scif_fence_mark()/ 775 * scif_fence_wait() and scif_fence_signal(), can be used to synchronize to 776 * the completion of asynchronous RMA operations on the same endpoint. 777 * 778 * The DMA transfer of individual bytes is not guaranteed to complete in 779 * address order. If rma_flags includes SCIF_RMA_ORDERED, then the last 780 * cacheline or partial cacheline of the source range will become visible on 781 * the destination node after all other transferred data in the source 782 * range has become visible on the destination node. 783 * 784 * If rma_flags includes SCIF_RMA_USECACHE, then the physical pages which back 785 * the specified local memory range may be remain in a pinned state even after 786 * the specified transfer completes. This may reduce overhead if some or all of 787 * the same virtual address range is referenced in a subsequent call of 788 * scif_vreadfrom() or scif_vwriteto(). 789 * 790 * The optimal DMA performance will likely be realized if both 791 * addr and roffset are cacheline aligned (are a multiple of 64). Lower 792 * performance will likely be realized if addr and roffset are not 793 * cacheline aligned but are separated by some multiple of 64. The lowest level 794 * of performance is likely if addr and roffset are not separated by a 795 * multiple of 64. 796 * 797 * The rma_flags argument is formed by ORing together zero or more of the 798 * following values. 799 * SCIF_RMA_USECPU - perform the transfer using the CPU, otherwise use the DMA 800 * engine. 801 * SCIF_RMA_USECACHE - enable registration caching 802 * SCIF_RMA_SYNC - perform the transfer synchronously, returning after the 803 * transfer has completed. Passing this flag results in the 804 * current implementation busy waiting and consuming CPU cycles 805 * while the DMA transfer is in progress for best performance by 806 * avoiding the interrupt latency. 807 * SCIF_RMA_ORDERED - ensure that the last cacheline or partial cacheline of 808 * the source range becomes visible on the destination node 809 * after all other transferred data in the source range has 810 * become visible on the destination 811 * 812 * Return: 813 * Upon successful completion, scif_vreadfrom() returns 0; otherwise in user 814 * mode -1 is returned and errno is set to indicate the error; in kernel mode 815 * the negative of one of the following errors is returned. 816 * 817 * Errors: 818 * EACCESS - Attempt to write to a read-only range 819 * EBADF, ENOTTY - epd is not a valid endpoint descriptor 820 * ECONNRESET - Connection reset by peer 821 * EINVAL - rma_flags is invalid 822 * ENODEV - The remote node is lost or existed, but is not currently in the 823 * network since it may have crashed 824 * ENOTCONN - The endpoint is not connected 825 * ENXIO - Offsets in the range [roffset, roffset + len - 1] are invalid for the 826 * registered address space of epd 827 */ 828 int scif_vreadfrom(scif_epd_t epd, void *addr, size_t len, off_t roffset, 829 int rma_flags); 830 831 /** 832 * scif_vwriteto() - Copy to a remote address space 833 * @epd: endpoint descriptor 834 * @addr: address from which to copy 835 * @len: length of range to copy 836 * @roffset: offset in remote registered address space to 837 * which to copy 838 * @rma_flags: transfer mode flags 839 * 840 * scif_vwriteto() copies len bytes from the local memory, starting at addr, to 841 * the remote registered address space of the peer of endpoint epd, starting at 842 * the offset roffset. 843 * 844 * The specified range [roffset, roffset + len - 1] must be within some 845 * registered window or windows of the remote nodes. The range may intersect 846 * multiple registered windows, but only if those windows are contiguous in the 847 * registered address space. 848 * 849 * If rma_flags includes SCIF_RMA_USECPU, then the data is copied using 850 * programmed read/writes. Otherwise the data is copied using DMA. If rma_- 851 * flags includes SCIF_RMA_SYNC, then scif_vwriteto() will return after the 852 * transfer is complete. Otherwise, the transfer may be performed asynchron- 853 * ously. The order in which any two asynchronous RMA operations complete 854 * is non-deterministic. The synchronization functions, scif_fence_mark()/ 855 * scif_fence_wait() and scif_fence_signal(), can be used to synchronize to 856 * the completion of asynchronous RMA operations on the same endpoint. 857 * 858 * The DMA transfer of individual bytes is not guaranteed to complete in 859 * address order. If rma_flags includes SCIF_RMA_ORDERED, then the last 860 * cacheline or partial cacheline of the source range will become visible on 861 * the destination node after all other transferred data in the source 862 * range has become visible on the destination node. 863 * 864 * If rma_flags includes SCIF_RMA_USECACHE, then the physical pages which back 865 * the specified local memory range may be remain in a pinned state even after 866 * the specified transfer completes. This may reduce overhead if some or all of 867 * the same virtual address range is referenced in a subsequent call of 868 * scif_vreadfrom() or scif_vwriteto(). 869 * 870 * The optimal DMA performance will likely be realized if both 871 * addr and offset are cacheline aligned (are a multiple of 64). Lower 872 * performance will likely be realized if addr and offset are not cacheline 873 * aligned but are separated by some multiple of 64. The lowest level of 874 * performance is likely if addr and offset are not separated by a multiple of 875 * 64. 876 * 877 * The rma_flags argument is formed by ORing together zero or more of the 878 * following values. 879 * SCIF_RMA_USECPU - perform the transfer using the CPU, otherwise use the DMA 880 * engine. 881 * SCIF_RMA_USECACHE - allow registration caching 882 * SCIF_RMA_SYNC - perform the transfer synchronously, returning after the 883 * transfer has completed. Passing this flag results in the 884 * current implementation busy waiting and consuming CPU cycles 885 * while the DMA transfer is in progress for best performance by 886 * avoiding the interrupt latency. 887 * SCIF_RMA_ORDERED - ensure that the last cacheline or partial cacheline of 888 * the source range becomes visible on the destination node 889 * after all other transferred data in the source range has 890 * become visible on the destination 891 * 892 * Return: 893 * Upon successful completion, scif_vwriteto() returns 0; otherwise in user 894 * mode -1 is returned and errno is set to indicate the error; in kernel mode 895 * the negative of one of the following errors is returned. 896 * 897 * Errors: 898 * EACCESS - Attempt to write to a read-only range 899 * EBADF, ENOTTY - epd is not a valid endpoint descriptor 900 * ECONNRESET - Connection reset by peer 901 * EINVAL - rma_flags is invalid 902 * ENODEV - The remote node is lost or existed, but is not currently in the 903 * network since it may have crashed 904 * ENOTCONN - The endpoint is not connected 905 * ENXIO - Offsets in the range [roffset, roffset + len - 1] are invalid for the 906 * registered address space of epd 907 */ 908 int scif_vwriteto(scif_epd_t epd, void *addr, size_t len, off_t roffset, 909 int rma_flags); 910 911 /** 912 * scif_fence_mark() - Mark previously issued RMAs 913 * @epd: endpoint descriptor 914 * @flags: control flags 915 * @mark: marked value returned as output. 916 * 917 * scif_fence_mark() returns after marking the current set of all uncompleted 918 * RMAs initiated through the endpoint epd or the current set of all 919 * uncompleted RMAs initiated through the peer of endpoint epd. The RMAs are 920 * marked with a value returned at mark. The application may subsequently call 921 * scif_fence_wait(), passing the value returned at mark, to await completion 922 * of all RMAs so marked. 923 * 924 * The flags argument has exactly one of the following values. 925 * SCIF_FENCE_INIT_SELF - RMA operations initiated through endpoint 926 * epd are marked 927 * SCIF_FENCE_INIT_PEER - RMA operations initiated through the peer 928 * of endpoint epd are marked 929 * 930 * Return: 931 * Upon successful completion, scif_fence_mark() returns 0; otherwise in user 932 * mode -1 is returned and errno is set to indicate the error; in kernel mode 933 * the negative of one of the following errors is returned. 934 * 935 * Errors: 936 * EBADF, ENOTTY - epd is not a valid endpoint descriptor 937 * ECONNRESET - Connection reset by peer 938 * EINVAL - flags is invalid 939 * ENODEV - The remote node is lost or existed, but is not currently in the 940 * network since it may have crashed 941 * ENOTCONN - The endpoint is not connected 942 * ENOMEM - Insufficient kernel memory was available 943 */ 944 int scif_fence_mark(scif_epd_t epd, int flags, int *mark); 945 946 /** 947 * scif_fence_wait() - Wait for completion of marked RMAs 948 * @epd: endpoint descriptor 949 * @mark: mark request 950 * 951 * scif_fence_wait() returns after all RMAs marked with mark have completed. 952 * The value passed in mark must have been obtained in a previous call to 953 * scif_fence_mark(). 954 * 955 * Return: 956 * Upon successful completion, scif_fence_wait() returns 0; otherwise in user 957 * mode -1 is returned and errno is set to indicate the error; in kernel mode 958 * the negative of one of the following errors is returned. 959 * 960 * Errors: 961 * EBADF, ENOTTY - epd is not a valid endpoint descriptor 962 * ECONNRESET - Connection reset by peer 963 * ENODEV - The remote node is lost or existed, but is not currently in the 964 * network since it may have crashed 965 * ENOTCONN - The endpoint is not connected 966 * ENOMEM - Insufficient kernel memory was available 967 */ 968 int scif_fence_wait(scif_epd_t epd, int mark); 969 970 /** 971 * scif_fence_signal() - Request a memory update on completion of RMAs 972 * @epd: endpoint descriptor 973 * @loff: local offset 974 * @lval: local value to write to loffset 975 * @roff: remote offset 976 * @rval: remote value to write to roffset 977 * @flags: flags 978 * 979 * scif_fence_signal() returns after marking the current set of all uncompleted 980 * RMAs initiated through the endpoint epd or marking the current set of all 981 * uncompleted RMAs initiated through the peer of endpoint epd. 982 * 983 * If flags includes SCIF_SIGNAL_LOCAL, then on completion of the RMAs in the 984 * marked set, lval is written to memory at the address corresponding to offset 985 * loff in the local registered address space of epd. loff must be within a 986 * registered window. If flags includes SCIF_SIGNAL_REMOTE, then on completion 987 * of the RMAs in the marked set, rval is written to memory at the address 988 * corresponding to offset roff in the remote registered address space of epd. 989 * roff must be within a remote registered window of the peer of epd. Note 990 * that any specified offset must be DWORD (4 byte / 32 bit) aligned. 991 * 992 * The flags argument is formed by OR'ing together the following. 993 * Exactly one of the following values. 994 * SCIF_FENCE_INIT_SELF - RMA operations initiated through endpoint 995 * epd are marked 996 * SCIF_FENCE_INIT_PEER - RMA operations initiated through the peer 997 * of endpoint epd are marked 998 * One or more of the following values. 999 * SCIF_SIGNAL_LOCAL - On completion of the marked set of RMAs, write lval to 1000 * memory at the address corresponding to offset loff in the local 1001 * registered address space of epd. 1002 * SCIF_SIGNAL_REMOTE - On completion of the marked set of RMAs, write rval to 1003 * memory at the address corresponding to offset roff in the remote 1004 * registered address space of epd. 1005 * 1006 * Return: 1007 * Upon successful completion, scif_fence_signal() returns 0; otherwise in 1008 * user mode -1 is returned and errno is set to indicate the error; in kernel 1009 * mode the negative of one of the following errors is returned. 1010 * 1011 * Errors: 1012 * EBADF, ENOTTY - epd is not a valid endpoint descriptor 1013 * ECONNRESET - Connection reset by peer 1014 * EINVAL - flags is invalid, or loff or roff are not DWORD aligned 1015 * ENODEV - The remote node is lost or existed, but is not currently in the 1016 * network since it may have crashed 1017 * ENOTCONN - The endpoint is not connected 1018 * ENXIO - loff is invalid for the registered address of epd, or roff is invalid 1019 * for the registered address space, of the peer of epd 1020 */ 1021 int scif_fence_signal(scif_epd_t epd, off_t loff, u64 lval, off_t roff, 1022 u64 rval, int flags); 1023 1024 /** 1025 * scif_get_node_ids() - Return information about online nodes 1026 * @nodes: array in which to return online node IDs 1027 * @len: number of entries in the nodes array 1028 * @self: address to place the node ID of the local node 1029 * 1030 * scif_get_node_ids() fills in the nodes array with up to len node IDs of the 1031 * nodes in the SCIF network. If there is not enough space in nodes, as 1032 * indicated by the len parameter, only len node IDs are returned in nodes. The 1033 * return value of scif_get_node_ids() is the total number of nodes currently in 1034 * the SCIF network. By checking the return value against the len parameter, 1035 * the user may determine if enough space for nodes was allocated. 1036 * 1037 * The node ID of the local node is returned at self. 1038 * 1039 * Return: 1040 * Upon successful completion, scif_get_node_ids() returns the actual number of 1041 * online nodes in the SCIF network including 'self'; otherwise in user mode 1042 * -1 is returned and errno is set to indicate the error; in kernel mode no 1043 * errors are returned. 1044 */ 1045 int scif_get_node_ids(u16 *nodes, int len, u16 *self); 1046 1047 /** 1048 * scif_pin_pages() - Pin a set of pages 1049 * @addr: Virtual address of range to pin 1050 * @len: Length of range to pin 1051 * @prot_flags: Page protection flags 1052 * @map_flags: Page classification flags 1053 * @pinned_pages: Handle to pinned pages 1054 * 1055 * scif_pin_pages() pins (locks in physical memory) the physical pages which 1056 * back the range of virtual address pages starting at addr and continuing for 1057 * len bytes. addr and len are constrained to be multiples of the page size. A 1058 * successful scif_pin_pages() call returns a handle to pinned_pages which may 1059 * be used in subsequent calls to scif_register_pinned_pages(). 1060 * 1061 * The pages will remain pinned as long as there is a reference against the 1062 * scif_pinned_pages_t value returned by scif_pin_pages() and until 1063 * scif_unpin_pages() is called, passing the scif_pinned_pages_t value. A 1064 * reference is added to a scif_pinned_pages_t value each time a window is 1065 * created by calling scif_register_pinned_pages() and passing the 1066 * scif_pinned_pages_t value. A reference is removed from a 1067 * scif_pinned_pages_t value each time such a window is deleted. 1068 * 1069 * Subsequent operations which change the memory pages to which virtual 1070 * addresses are mapped (such as mmap(), munmap()) have no effect on the 1071 * scif_pinned_pages_t value or windows created against it. 1072 * 1073 * If the process will fork(), it is recommended that the registered 1074 * virtual address range be marked with MADV_DONTFORK. Doing so will prevent 1075 * problems due to copy-on-write semantics. 1076 * 1077 * The prot_flags argument is formed by OR'ing together one or more of the 1078 * following values. 1079 * SCIF_PROT_READ - allow read operations against the pages 1080 * SCIF_PROT_WRITE - allow write operations against the pages 1081 * The map_flags argument can be set as SCIF_MAP_KERNEL to interpret addr as a 1082 * kernel space address. By default, addr is interpreted as a user space 1083 * address. 1084 * 1085 * Return: 1086 * Upon successful completion, scif_pin_pages() returns 0; otherwise the 1087 * negative of one of the following errors is returned. 1088 * 1089 * Errors: 1090 * EINVAL - prot_flags is invalid, map_flags is invalid, or offset is negative 1091 * ENOMEM - Not enough space 1092 */ 1093 int scif_pin_pages(void *addr, size_t len, int prot_flags, int map_flags, 1094 scif_pinned_pages_t *pinned_pages); 1095 1096 /** 1097 * scif_unpin_pages() - Unpin a set of pages 1098 * @pinned_pages: Handle to pinned pages to be unpinned 1099 * 1100 * scif_unpin_pages() prevents scif_register_pinned_pages() from registering new 1101 * windows against pinned_pages. The physical pages represented by pinned_pages 1102 * will remain pinned until all windows previously registered against 1103 * pinned_pages are deleted (the window is scif_unregister()'d and all 1104 * references to the window are removed (see scif_unregister()). 1105 * 1106 * pinned_pages must have been obtain from a previous call to scif_pin_pages(). 1107 * After calling scif_unpin_pages(), it is an error to pass pinned_pages to 1108 * scif_register_pinned_pages(). 1109 * 1110 * Return: 1111 * Upon successful completion, scif_unpin_pages() returns 0; otherwise the 1112 * negative of one of the following errors is returned. 1113 * 1114 * Errors: 1115 * EINVAL - pinned_pages is not valid 1116 */ 1117 int scif_unpin_pages(scif_pinned_pages_t pinned_pages); 1118 1119 /** 1120 * scif_register_pinned_pages() - Mark a memory region for remote access. 1121 * @epd: endpoint descriptor 1122 * @pinned_pages: Handle to pinned pages 1123 * @offset: Registered address space offset 1124 * @map_flags: Flags which control where pages are mapped 1125 * 1126 * The scif_register_pinned_pages() function opens a window, a range of whole 1127 * pages of the registered address space of the endpoint epd, starting at 1128 * offset po. The value of po, further described below, is a function of the 1129 * parameters offset and pinned_pages, and the value of map_flags. Each page of 1130 * the window represents a corresponding physical memory page of the range 1131 * represented by pinned_pages; the length of the window is the same as the 1132 * length of range represented by pinned_pages. A successful 1133 * scif_register_pinned_pages() call returns po as the return value. 1134 * 1135 * When SCIF_MAP_FIXED is set in the map_flags argument, po will be offset 1136 * exactly, and offset is constrained to be a multiple of the page size. The 1137 * mapping established by scif_register_pinned_pages() will not replace any 1138 * existing registration; an error is returned if any page of the new window 1139 * would intersect an existing window. 1140 * 1141 * When SCIF_MAP_FIXED is not set, the implementation uses offset in an 1142 * implementation-defined manner to arrive at po. The po so chosen will be an 1143 * area of the registered address space that the implementation deems suitable 1144 * for a mapping of the required size. An offset value of 0 is interpreted as 1145 * granting the implementation complete freedom in selecting po, subject to 1146 * constraints described below. A non-zero value of offset is taken to be a 1147 * suggestion of an offset near which the mapping should be placed. When the 1148 * implementation selects a value for po, it does not replace any extant 1149 * window. In all cases, po will be a multiple of the page size. 1150 * 1151 * The physical pages which are so represented by a window are available for 1152 * access in calls to scif_get_pages(), scif_readfrom(), scif_writeto(), 1153 * scif_vreadfrom(), and scif_vwriteto(). While a window is registered, the 1154 * physical pages represented by the window will not be reused by the memory 1155 * subsystem for any other purpose. Note that the same physical page may be 1156 * represented by multiple windows. 1157 * 1158 * Windows created by scif_register_pinned_pages() are unregistered by 1159 * scif_unregister(). 1160 * 1161 * The map_flags argument can be set to SCIF_MAP_FIXED which interprets a 1162 * fixed offset. 1163 * 1164 * Return: 1165 * Upon successful completion, scif_register_pinned_pages() returns the offset 1166 * at which the mapping was placed (po); otherwise the negative of one of the 1167 * following errors is returned. 1168 * 1169 * Errors: 1170 * EADDRINUSE - SCIF_MAP_FIXED is set in map_flags and pages in the new window 1171 * would intersect an existing window 1172 * EAGAIN - The mapping could not be performed due to lack of resources 1173 * ECONNRESET - Connection reset by peer 1174 * EINVAL - map_flags is invalid, or SCIF_MAP_FIXED is set in map_flags, and 1175 * offset is not a multiple of the page size, or offset is negative 1176 * ENODEV - The remote node is lost or existed, but is not currently in the 1177 * network since it may have crashed 1178 * ENOMEM - Not enough space 1179 * ENOTCONN - The endpoint is not connected 1180 */ 1181 off_t scif_register_pinned_pages(scif_epd_t epd, 1182 scif_pinned_pages_t pinned_pages, 1183 off_t offset, int map_flags); 1184 1185 /** 1186 * scif_get_pages() - Add references to remote registered pages 1187 * @epd: endpoint descriptor 1188 * @offset: remote registered offset 1189 * @len: length of range of pages 1190 * @pages: returned scif_range structure 1191 * 1192 * scif_get_pages() returns the addresses of the physical pages represented by 1193 * those pages of the registered address space of the peer of epd, starting at 1194 * offset and continuing for len bytes. offset and len are constrained to be 1195 * multiples of the page size. 1196 * 1197 * All of the pages in the specified range [offset, offset + len - 1] must be 1198 * within a single window of the registered address space of the peer of epd. 1199 * 1200 * The addresses are returned as a virtually contiguous array pointed to by the 1201 * phys_addr component of the scif_range structure whose address is returned in 1202 * pages. The nr_pages component of scif_range is the length of the array. The 1203 * prot_flags component of scif_range holds the protection flag value passed 1204 * when the pages were registered. 1205 * 1206 * Each physical page whose address is returned by scif_get_pages() remains 1207 * available and will not be released for reuse until the scif_range structure 1208 * is returned in a call to scif_put_pages(). The scif_range structure returned 1209 * by scif_get_pages() must be unmodified. 1210 * 1211 * It is an error to call scif_close() on an endpoint on which a scif_range 1212 * structure of that endpoint has not been returned to scif_put_pages(). 1213 * 1214 * Return: 1215 * Upon successful completion, scif_get_pages() returns 0; otherwise the 1216 * negative of one of the following errors is returned. 1217 * Errors: 1218 * ECONNRESET - Connection reset by peer. 1219 * EINVAL - offset is not a multiple of the page size, or offset is negative, or 1220 * len is not a multiple of the page size 1221 * ENODEV - The remote node is lost or existed, but is not currently in the 1222 * network since it may have crashed 1223 * ENOTCONN - The endpoint is not connected 1224 * ENXIO - Offsets in the range [offset, offset + len - 1] are invalid 1225 * for the registered address space of the peer epd 1226 */ 1227 int scif_get_pages(scif_epd_t epd, off_t offset, size_t len, 1228 struct scif_range **pages); 1229 1230 /** 1231 * scif_put_pages() - Remove references from remote registered pages 1232 * @pages: pages to be returned 1233 * 1234 * scif_put_pages() releases a scif_range structure previously obtained by 1235 * calling scif_get_pages(). The physical pages represented by pages may 1236 * be reused when the window which represented those pages is unregistered. 1237 * Therefore, those pages must not be accessed after calling scif_put_pages(). 1238 * 1239 * Return: 1240 * Upon successful completion, scif_put_pages() returns 0; otherwise the 1241 * negative of one of the following errors is returned. 1242 * Errors: 1243 * EINVAL - pages does not point to a valid scif_range structure, or 1244 * the scif_range structure pointed to by pages was already returned 1245 * ENODEV - The remote node is lost or existed, but is not currently in the 1246 * network since it may have crashed 1247 * ENOTCONN - The endpoint is not connected 1248 */ 1249 int scif_put_pages(struct scif_range *pages); 1250 1251 /** 1252 * scif_poll() - Wait for some event on an endpoint 1253 * @epds: Array of endpoint descriptors 1254 * @nepds: Length of epds 1255 * @timeout: Upper limit on time for which scif_poll() will block 1256 * 1257 * scif_poll() waits for one of a set of endpoints to become ready to perform 1258 * an I/O operation. 1259 * 1260 * The epds argument specifies the endpoint descriptors to be examined and the 1261 * events of interest for each endpoint descriptor. epds is a pointer to an 1262 * array with one member for each open endpoint descriptor of interest. 1263 * 1264 * The number of items in the epds array is specified in nepds. The epd field 1265 * of scif_pollepd is an endpoint descriptor of an open endpoint. The field 1266 * events is a bitmask specifying the events which the application is 1267 * interested in. The field revents is an output parameter, filled by the 1268 * kernel with the events that actually occurred. The bits returned in revents 1269 * can include any of those specified in events, or one of the values POLLERR, 1270 * POLLHUP, or POLLNVAL. (These three bits are meaningless in the events 1271 * field, and will be set in the revents field whenever the corresponding 1272 * condition is true.) 1273 * 1274 * If none of the events requested (and no error) has occurred for any of the 1275 * endpoint descriptors, then scif_poll() blocks until one of the events occurs. 1276 * 1277 * The timeout argument specifies an upper limit on the time for which 1278 * scif_poll() will block, in milliseconds. Specifying a negative value in 1279 * timeout means an infinite timeout. 1280 * 1281 * The following bits may be set in events and returned in revents. 1282 * POLLIN - Data may be received without blocking. For a connected 1283 * endpoint, this means that scif_recv() may be called without blocking. For a 1284 * listening endpoint, this means that scif_accept() may be called without 1285 * blocking. 1286 * POLLOUT - Data may be sent without blocking. For a connected endpoint, this 1287 * means that scif_send() may be called without blocking. POLLOUT may also be 1288 * used to block waiting for a non-blocking connect to complete. This bit value 1289 * has no meaning for a listening endpoint and is ignored if specified. 1290 * 1291 * The following bits are only returned in revents, and are ignored if set in 1292 * events. 1293 * POLLERR - An error occurred on the endpoint 1294 * POLLHUP - The connection to the peer endpoint was disconnected 1295 * POLLNVAL - The specified endpoint descriptor is invalid. 1296 * 1297 * Return: 1298 * Upon successful completion, scif_poll() returns a non-negative value. A 1299 * positive value indicates the total number of endpoint descriptors that have 1300 * been selected (that is, endpoint descriptors for which the revents member is 1301 * non-zero). A value of 0 indicates that the call timed out and no endpoint 1302 * descriptors have been selected. Otherwise in user mode -1 is returned and 1303 * errno is set to indicate the error; in kernel mode the negative of one of 1304 * the following errors is returned. 1305 * 1306 * Errors: 1307 * EINTR - A signal occurred before any requested event 1308 * EINVAL - The nepds argument is greater than {OPEN_MAX} 1309 * ENOMEM - There was no space to allocate file descriptor tables 1310 */ 1311 int scif_poll(struct scif_pollepd *epds, unsigned int nepds, long timeout); 1312 1313 /** 1314 * scif_client_register() - Register a SCIF client 1315 * @client: client to be registered 1316 * 1317 * scif_client_register() registers a SCIF client. The probe() method 1318 * of the client is called when SCIF peer devices come online and the 1319 * remove() method is called when the peer devices disappear. 1320 * 1321 * Return: 1322 * Upon successful completion, scif_client_register() returns a non-negative 1323 * value. Otherwise the return value is the same as subsys_interface_register() 1324 * in the kernel. 1325 */ 1326 int scif_client_register(struct scif_client *client); 1327 1328 /** 1329 * scif_client_unregister() - Unregister a SCIF client 1330 * @client: client to be unregistered 1331 * 1332 * scif_client_unregister() unregisters a SCIF client. 1333 * 1334 * Return: 1335 * None 1336 */ 1337 void scif_client_unregister(struct scif_client *client); 1338 1339 #endif /* __SCIF_H__ */ 1340