1 /** 2 * Copyright (C) Mellanox Technologies Ltd. 2001-2019. ALL RIGHTS RESERVED. 3 * 4 * See file LICENSE for terms. 5 */ 6 7 #ifndef UCT_DEF_H_ 8 #define UCT_DEF_H_ 9 10 #include <ucs/config/types.h> 11 #include <ucs/type/status.h> 12 13 #include <stddef.h> 14 #include <stdint.h> 15 #include <sys/types.h> 16 17 18 #define UCT_COMPONENT_NAME_MAX 16 19 #define UCT_TL_NAME_MAX 10 20 #define UCT_MD_NAME_MAX 16 21 #define UCT_DEVICE_NAME_MAX 32 22 #define UCT_PENDING_REQ_PRIV_LEN 40 23 #define UCT_TAG_PRIV_LEN 32 24 #define UCT_AM_ID_BITS 5 25 #define UCT_AM_ID_MAX UCS_BIT(UCT_AM_ID_BITS) 26 #define UCT_MEM_HANDLE_NULL NULL 27 #define UCT_INVALID_RKEY ((uintptr_t)(-1)) 28 #define UCT_INLINE_API static UCS_F_ALWAYS_INLINE 29 30 31 /** 32 * @ingroup UCT_AM 33 * @brief Trace types for active message tracer. 34 */ 35 enum uct_am_trace_type { 36 UCT_AM_TRACE_TYPE_SEND, 37 UCT_AM_TRACE_TYPE_RECV, 38 UCT_AM_TRACE_TYPE_SEND_DROP, 39 UCT_AM_TRACE_TYPE_RECV_DROP, 40 UCT_AM_TRACE_TYPE_LAST 41 }; 42 43 44 /** 45 * @ingroup UCT_RESOURCE 46 * @brief Flags for active message and tag-matching offload callbacks (callback's parameters). 47 * 48 * If UCT_CB_PARAM_FLAG_DESC flag is enabled, then data is part of a descriptor 49 * which includes the user-defined rx_headroom, and the callback may return 50 * UCS_INPROGRESS and hold on to that descriptor. Otherwise, the data can't be 51 * used outside the callback. If needed, the data must be copied-out. 52 * 53 @verbatim 54 descriptor data 55 | | 56 +-------------+-------------------------+ 57 | rx_headroom | payload | 58 +-------------+-------------------------+ 59 @endverbatim 60 * 61 * UCT_CB_PARAM_FLAG_FIRST and UCT_CB_PARAM_FLAG_MORE flags are relevant for 62 * @ref uct_tag_unexp_eager_cb_t callback only. The former value indicates that 63 * the data is the first fragment of the message. The latter value means that 64 * more fragments of the message yet to be delivered. 65 */ 66 enum uct_cb_param_flags { 67 UCT_CB_PARAM_FLAG_DESC = UCS_BIT(0), 68 UCT_CB_PARAM_FLAG_FIRST = UCS_BIT(1), 69 UCT_CB_PARAM_FLAG_MORE = UCS_BIT(2) 70 }; 71 72 /** 73 * @addtogroup UCT_RESOURCE 74 * @{ 75 */ 76 typedef struct uct_component *uct_component_h; 77 typedef struct uct_iface *uct_iface_h; 78 typedef struct uct_iface_config uct_iface_config_t; 79 typedef struct uct_md_config uct_md_config_t; 80 typedef struct uct_cm_config uct_cm_config_t; 81 typedef struct uct_ep *uct_ep_h; 82 typedef void * uct_mem_h; 83 typedef uintptr_t uct_rkey_t; 84 typedef struct uct_md *uct_md_h; /**< @brief Memory domain handler */ 85 typedef struct uct_md_ops uct_md_ops_t; 86 typedef void *uct_rkey_ctx_h; 87 typedef struct uct_iface_attr uct_iface_attr_t; 88 typedef struct uct_iface_params uct_iface_params_t; 89 typedef struct uct_md_attr uct_md_attr_t; 90 typedef struct uct_completion uct_completion_t; 91 typedef struct uct_pending_req uct_pending_req_t; 92 typedef struct uct_worker *uct_worker_h; 93 typedef struct uct_md uct_md_t; 94 typedef enum uct_am_trace_type uct_am_trace_type_t; 95 typedef struct uct_device_addr uct_device_addr_t; 96 typedef struct uct_iface_addr uct_iface_addr_t; 97 typedef struct uct_ep_addr uct_ep_addr_t; 98 typedef struct uct_ep_params uct_ep_params_t; 99 typedef struct uct_cm_attr uct_cm_attr_t; 100 typedef struct uct_cm uct_cm_t; 101 typedef uct_cm_t *uct_cm_h; 102 typedef struct uct_listener_attr uct_listener_attr_t; 103 typedef struct uct_listener *uct_listener_h; 104 typedef struct uct_listener_params uct_listener_params_t; 105 typedef struct uct_tag_context uct_tag_context_t; 106 typedef uint64_t uct_tag_t; /* tag type - 64 bit */ 107 typedef int uct_worker_cb_id_t; 108 typedef void* uct_conn_request_h; 109 110 /** 111 * @} 112 */ 113 114 115 /** 116 * @ingroup UCT_RESOURCE 117 * @brief Structure for scatter-gather I/O. 118 * 119 * Specifies a list of buffers which can be used within a single data transfer 120 * function call. 121 * 122 @verbatim 123 buffer 124 | 125 +-----------+-------+-----------+-------+-----------+ 126 | payload | empty | payload | empty | payload | 127 +-----------+-------+-----------+-------+-----------+ 128 |<-length-->| |<-length-->| |<-length-->| 129 |<---- stride ----->|<---- stride ----->| 130 @endverbatim 131 * 132 * @note The sum of lengths in all iov list must be less or equal to max_zcopy 133 * of the respective communication operation. 134 * @note If @a length or @a count are zero, the memory pointed to by @a buffer 135 * will not be accessed. Otherwise, @a buffer must point to valid memory. 136 * 137 * @note If @a count is one, every iov entry specifies a single contiguous data block 138 * 139 * @note If @a count > 1, each iov entry specifies a strided block of @a count 140 * elements and distance of @a stride byte between consecutive elements 141 * 142 */ 143 typedef struct uct_iov { 144 void *buffer; /**< Data buffer */ 145 size_t length; /**< Length of the payload in bytes */ 146 uct_mem_h memh; /**< Local memory key descriptor for the data */ 147 size_t stride; /**< Stride between beginnings of payload elements in 148 the buffer in bytes */ 149 unsigned count; /**< Number of payload elements in the buffer */ 150 } uct_iov_t; 151 152 153 /** 154 * @ingroup UCT_CLIENT_SERVER 155 * @brief Client-Server private data pack callback arguments field mask. 156 * 157 * The enumeration allows specifying which fields in 158 * @ref uct_cm_ep_priv_data_pack_args are present, for backward compatibility support. 159 */ 160 enum uct_cm_ep_priv_data_pack_args_field { 161 /** Enables @ref uct_cm_ep_priv_data_pack_args::dev_name 162 * Indicates that dev_name field in uct_cm_ep_priv_data_pack_args_t is valid. 163 */ 164 UCT_CM_EP_PRIV_DATA_PACK_ARGS_FIELD_DEVICE_NAME = UCS_BIT(0) 165 }; 166 167 168 /** 169 * @ingroup UCT_CLIENT_SERVER 170 * @brief Arguments to the client-server private data pack callback. 171 * 172 * Used with the client-server API on a connection manager. 173 */ 174 typedef struct uct_cm_ep_priv_data_pack_args { 175 /** 176 * Mask of valid fields in this structure, using bits from 177 * @ref uct_cm_ep_priv_data_pack_args_field. 178 * Fields not specified by this mask should not be accessed by the callback. 179 */ 180 uint64_t field_mask; 181 182 /** 183 * Device name. This routine may fill the user's private data according to 184 * the given device name. The device name that is passed to this routine, 185 * corresponds to @ref uct_tl_resource_desc_t::dev_name as returned from 186 * @ref uct_md_query_tl_resources. 187 */ 188 char dev_name[UCT_DEVICE_NAME_MAX]; 189 } uct_cm_ep_priv_data_pack_args_t; 190 191 192 /** 193 * @ingroup UCT_CLIENT_SERVER 194 * @brief Remote data attributes field mask. 195 * 196 * The enumeration allows specifying which fields in @ref uct_cm_remote_data are 197 * present, for backward compatibility support. 198 */ 199 enum uct_cm_remote_data_field { 200 /** Enables @ref uct_cm_remote_data::dev_addr */ 201 UCT_CM_REMOTE_DATA_FIELD_DEV_ADDR = UCS_BIT(0), 202 203 /** Enables @ref uct_cm_remote_data::dev_addr_length */ 204 UCT_CM_REMOTE_DATA_FIELD_DEV_ADDR_LENGTH = UCS_BIT(1), 205 206 /** Enables @ref uct_cm_remote_data::conn_priv_data */ 207 UCT_CM_REMOTE_DATA_FIELD_CONN_PRIV_DATA = UCS_BIT(2), 208 209 /** Enables @ref uct_cm_remote_data::conn_priv_data_length */ 210 UCT_CM_REMOTE_DATA_FIELD_CONN_PRIV_DATA_LENGTH = UCS_BIT(3) 211 }; 212 213 214 /** 215 * @ingroup UCT_CLIENT_SERVER 216 * @brief Data received from the remote peer. 217 * 218 * The remote peer's device address, the data received from it and their lengths. 219 * Used with the client-server API on a connection manager. 220 */ 221 typedef struct uct_cm_remote_data { 222 /** 223 * Mask of valid fields in this structure, using bits from 224 * @ref uct_cm_remote_data_field. Fields not specified by this mask 225 * will be ignored. 226 */ 227 uint64_t field_mask; 228 229 /** 230 * Device address of the remote peer. 231 */ 232 const uct_device_addr_t *dev_addr; 233 234 /** 235 * Length of the remote device address. 236 */ 237 size_t dev_addr_length; 238 239 /** 240 * Pointer to the received data. This is the private data that was passed to 241 * @ref uct_ep_params_t::sockaddr_pack_cb. 242 */ 243 const void *conn_priv_data; 244 245 /** 246 * Length of the received data from the peer. 247 */ 248 size_t conn_priv_data_length; 249 } uct_cm_remote_data_t; 250 251 252 /** 253 * @ingroup UCT_CLIENT_SERVER 254 * @brief Listener's connection request callback arguments field mask. 255 * 256 * The enumeration allows specifying which fields in 257 * @ref uct_cm_listener_conn_request_args are present, for backward compatibility 258 * support. 259 */ 260 enum uct_cm_listener_conn_request_args_field { 261 /** Enables @ref uct_cm_listener_conn_request_args::dev_name 262 * Indicates that dev_name field in uct_cm_listener_conn_request_args_t is 263 * valid. 264 */ 265 UCT_CM_LISTENER_CONN_REQUEST_ARGS_FIELD_DEV_NAME = UCS_BIT(0), 266 267 /** Enables @ref uct_cm_listener_conn_request_args::conn_request 268 * Indicates that conn_request field in uct_cm_listener_conn_request_args_t 269 * is valid. 270 */ 271 UCT_CM_LISTENER_CONN_REQUEST_ARGS_FIELD_CONN_REQUEST = UCS_BIT(1), 272 273 /** Enables @ref uct_cm_listener_conn_request_args::remote_data 274 * Indicates that remote_data field in uct_cm_listener_conn_request_args_t 275 * is valid. 276 */ 277 UCT_CM_LISTENER_CONN_REQUEST_ARGS_FIELD_REMOTE_DATA = UCS_BIT(2), 278 279 /** Enables @ref uct_cm_listener_conn_request_args::client_address 280 * Indicates that client_address field in uct_cm_listener_conn_request_args_t 281 * is valid. 282 */ 283 UCT_CM_LISTENER_CONN_REQUEST_ARGS_FIELD_CLIENT_ADDR = UCS_BIT(3) 284 }; 285 286 287 /** 288 * @ingroup UCT_CLIENT_SERVER 289 * @brief Arguments to the listener's connection request callback. 290 * 291 * The local device name, connection request handle and the data the client sent. 292 * Used with the client-server API on a connection manager. 293 */ 294 typedef struct uct_cm_listener_conn_request_args { 295 /** 296 * Mask of valid fields in this structure, using bits from 297 * @ref uct_cm_listener_conn_request_args_field. 298 * Fields not specified by this mask should not be acceessed by the callback. 299 */ 300 uint64_t field_mask; 301 302 /** 303 * Local device name which handles the incoming connection request. 304 */ 305 char dev_name[UCT_DEVICE_NAME_MAX]; 306 307 /** 308 * Connection request handle. Can be passed to this callback from the 309 * transport and will be used by it to accept or reject the connection 310 * request from the client. 311 */ 312 uct_conn_request_h conn_request; 313 314 /** 315 * Remote data from the client. 316 */ 317 const uct_cm_remote_data_t *remote_data; 318 319 /** 320 * Client's address. 321 */ 322 ucs_sock_addr_t client_address; 323 } uct_cm_listener_conn_request_args_t; 324 325 326 /** 327 * @ingroup UCT_CLIENT_SERVER 328 * @brief Field mask flags for client-side connection established callback. 329 * 330 * The enumeration allows specifying which fields in 331 * @ref uct_cm_ep_client_connect_args are present, for backward compatibility 332 * support. 333 */ 334 enum uct_cm_ep_client_connect_args_field { 335 /** Enables @ref uct_cm_ep_client_connect_args::remote_data */ 336 UCT_CM_EP_CLIENT_CONNECT_ARGS_FIELD_REMOTE_DATA = UCS_BIT(0), 337 338 /** Enables @ref uct_cm_ep_client_connect_args::status */ 339 UCT_CM_EP_CLIENT_CONNECT_ARGS_FIELD_STATUS = UCS_BIT(1) 340 }; 341 342 343 /** 344 * @ingroup UCT_CLIENT_SERVER 345 * @brief Arguments to the client's connect callback. 346 * 347 * Used with the client-server API on a connection manager. 348 */ 349 typedef struct uct_cm_ep_client_connect_args { 350 /** 351 * Mask of valid fields in this structure, using bits from 352 * @ref uct_cm_ep_client_connect_args_field. 353 * Fields not specified by this mask should not be accessed by the callback. 354 */ 355 uint64_t field_mask; 356 357 /** 358 * Remote data from the server. 359 */ 360 const uct_cm_remote_data_t *remote_data; 361 362 /** 363 * Indicates the connection establishment response from the remote server: 364 * UCS_OK - the remote server accepted the connection request. 365 * UCS_ERR_REJECTED - the remote server rejected the connection request. 366 * UCS_ERR_CONNECTION_RESET - the server's connection was reset during 367 * the connection establishment to the client. 368 * Otherwise - indicates an internal connection establishment 369 * error on the local (client) side. 370 */ 371 ucs_status_t status; 372 } uct_cm_ep_client_connect_args_t; 373 374 375 /** 376 * @ingroup UCT_CLIENT_SERVER 377 * @brief Field mask flags for server-side connection established notification 378 * callback. 379 * 380 * The enumeration allows specifying which fields in 381 * @ref uct_cm_ep_server_conn_notify_args are present, for backward compatibility 382 * support. 383 */ 384 enum uct_cm_ep_server_conn_notify_args_field { 385 /** Enables @ref uct_cm_ep_server_conn_notify_args::status 386 * Indicates that status field in uct_cm_ep_server_conn_notify_args_t is valid. 387 */ 388 UCT_CM_EP_SERVER_CONN_NOTIFY_ARGS_FIELD_STATUS = UCS_BIT(0) 389 }; 390 391 392 /** 393 * @ingroup UCT_CLIENT_SERVER 394 * @brief Arguments to the server's notify callback. 395 * 396 * Used with the client-server API on a connection manager. 397 */ 398 typedef struct uct_cm_ep_server_conn_notify_args { 399 /** 400 * Mask of valid fields in this structure, using bits from 401 * @ref uct_cm_ep_server_conn_notify_args_field. 402 * Fields not specified by this mask should not be accessed by the callback. 403 */ 404 uint64_t field_mask; 405 406 /** 407 * Indicates the client's @ref ucs_status_t status: 408 * UCS_OK - the client completed its connection 409 * establishment and called 410 * @ref uct_cm_client_ep_conn_notify 411 * UCS_ERR_CONNECTION_RESET - the client's connection was reset during 412 * the connection establishment to the server. 413 * Otherwise - indicates an internal connection establishment 414 * error on the local (server) side. 415 */ 416 ucs_status_t status; 417 } uct_cm_ep_server_conn_notify_args_t; 418 419 420 /** 421 * @ingroup UCT_AM 422 * @brief Callback to process incoming active message 423 * 424 * When the callback is called, @a flags indicates how @a data should be handled. 425 * If @a flags contain @ref UCT_CB_PARAM_FLAG_DESC value, it means @a data is part of 426 * a descriptor which must be released later by @ref uct_iface_release_desc by 427 * the user if the callback returns @ref UCS_INPROGRESS. 428 * 429 * @param [in] arg User-defined argument. 430 * @param [in] data Points to the received data. This may be a part of 431 * a descriptor which may be released later. 432 * @param [in] length Length of data. 433 * @param [in] flags Mask with @ref uct_cb_param_flags 434 * 435 * @note This callback could be set and released 436 * by @ref uct_iface_set_am_handler function. 437 * 438 * @retval UCS_OK - descriptor was consumed, and can be released 439 * by the caller. 440 * @retval UCS_INPROGRESS - descriptor is owned by the callee, and would be 441 * released later. Supported only if @a flags contain 442 * @ref UCT_CB_PARAM_FLAG_DESC value. Otherwise, this is 443 * an error. 444 * 445 */ 446 typedef ucs_status_t (*uct_am_callback_t)(void *arg, void *data, size_t length, 447 unsigned flags); 448 449 450 /** 451 * @ingroup UCT_AM 452 * @brief Callback to trace active messages. 453 * 454 * Writes a string which represents active message contents into 'buffer'. 455 * 456 * @param [in] arg User-defined argument. 457 * @param [in] type Message type. 458 * @param [in] id Active message id. 459 * @param [in] data Points to the received data. 460 * @param [in] length Length of data. 461 * @param [out] buffer Filled with a debug information string. 462 * @param [in] max Maximal length of the string. 463 */ 464 typedef void (*uct_am_tracer_t)(void *arg, uct_am_trace_type_t type, uint8_t id, 465 const void *data, size_t length, char *buffer, 466 size_t max); 467 468 469 /** 470 * @ingroup UCT_RESOURCE 471 * @brief Callback to process send completion. 472 * 473 * @param [in] self Pointer to relevant completion structure, which was 474 * initially passed to the operation. 475 * @param [in] status Status of send action, possibly indicating an error. 476 */ 477 typedef void (*uct_completion_callback_t)(uct_completion_t *self, 478 ucs_status_t status); 479 480 481 /** 482 * @ingroup UCT_RESOURCE 483 * @brief Callback to process pending requests. 484 * 485 * @param [in] self Pointer to relevant pending structure, which was 486 * initially passed to the operation. 487 * 488 * @return @ref UCS_OK - This pending request has completed and 489 * should be removed. 490 * @ref UCS_INPROGRESS - Some progress was made, but not completed. 491 * Keep this request and keep processing the queue. 492 * Otherwise - Could not make any progress. Keep this pending 493 * request on the queue, and stop processing the queue. 494 */ 495 typedef ucs_status_t (*uct_pending_callback_t)(uct_pending_req_t *self); 496 497 498 /** 499 * @ingroup UCT_RESOURCE 500 * @brief Callback to process peer failure. 501 * 502 * @param [in] arg User argument to be passed to the callback. 503 * @param [in] ep Endpoint which has failed. Upon return from the callback, 504 * this @a ep is no longer usable and all subsequent 505 * operations on this @a ep will fail with the error code 506 * passed in @a status. 507 * @param [in] status Status indicating error. 508 * 509 * @return @ref UCS_OK - The error was handled successfully. 510 * Otherwise - The error was not handled and is returned back to 511 * the transport. 512 */ 513 typedef ucs_status_t (*uct_error_handler_t)(void *arg, uct_ep_h ep, 514 ucs_status_t status); 515 516 517 /** 518 * @ingroup UCT_RESOURCE 519 * @brief Callback to purge pending requests. 520 * 521 * @param [in] self Pointer to relevant pending structure, which was 522 * initially passed to the operation. 523 * @param [in] arg User argument to be passed to the callback. 524 */ 525 typedef void (*uct_pending_purge_callback_t)(uct_pending_req_t *self, 526 void *arg); 527 528 /** 529 * @ingroup UCT_RESOURCE 530 * @brief Callback for producing data. 531 * 532 * @param [in] dest Memory buffer to pack the data to. 533 * @param [in] arg Custom user-argument. 534 * 535 * @return Size of the data was actually produced. 536 */ 537 typedef size_t (*uct_pack_callback_t)(void *dest, void *arg); 538 539 540 /** 541 * @ingroup UCT_RESOURCE 542 * @brief Callback for consuming data. 543 * 544 * @param [in] arg Custom user-argument. 545 * @param [in] data Memory buffer to unpack the data from. 546 * @param [in] length How much data to consume (size of "data") 547 * 548 * @note The arguments for this callback are in the same order as libc's memcpy(). 549 */ 550 typedef void (*uct_unpack_callback_t)(void *arg, const void *data, size_t length); 551 552 553 /** 554 * @ingroup UCT_CLIENT_SERVER 555 * @brief Callback to process an incoming connection request on the server side. 556 * 557 * This callback routine will be invoked on the server side upon receiving an 558 * incoming connection request. It should be set by the server side while 559 * initializing an interface. 560 * Incoming data is placed inside the conn_priv_data buffer. 561 * This callback has to be thread safe. 562 * Other than communication progress routines, it is allowed to call other UCT 563 * communication routines from this callback. 564 * 565 * @param [in] iface Transport interface. 566 * @param [in] arg User defined argument for this callback. 567 * @param [in] conn_request Transport level connection request. The user 568 * should accept or reject the request by calling 569 * @ref uct_iface_accept or @ref uct_iface_reject 570 * routines respectively. 571 * conn_request should not be used outside the 572 * scope of this callback. 573 * @param [in] conn_priv_data Points to the received data. 574 * This is the private data that was passed to the 575 * @ref uct_ep_params_t::sockaddr_pack_cb on the 576 * client side. 577 * @param [in] length Length of the received data. 578 * 579 */ 580 typedef void 581 (*uct_sockaddr_conn_request_callback_t)(uct_iface_h iface, void *arg, 582 uct_conn_request_h conn_request, 583 const void *conn_priv_data, 584 size_t length); 585 586 587 /** 588 * @ingroup UCT_CLIENT_SERVER 589 * @brief Callback to process an incoming connection request on the server side 590 * listener in a connection manager. 591 * 592 * This callback routine will be invoked on the server side upon receiving an 593 * incoming connection request. It should be set by the server side while 594 * initializing a listener in a connection manager. 595 * This callback has to be thread safe. 596 * Other than communication progress routines, it is allowed to call other UCT 597 * communication routines from this callback. 598 * 599 * @param [in] listener Transport listener. 600 * @param [in] arg User argument for this callback as defined in 601 * @ref uct_listener_params_t::user_data 602 * @param [in] conn_req_args Listener's arguments to handle the connection 603 * request from the client. 604 */ 605 typedef void 606 (*uct_cm_listener_conn_request_callback_t)(uct_listener_h listener, void *arg, 607 const uct_cm_listener_conn_request_args_t 608 *conn_req_args); 609 610 611 /** 612 * @ingroup UCT_CLIENT_SERVER 613 * @brief Callback to process an incoming connection establishment acknowledgment 614 * on the server side listener, from the client, which indicates that the 615 * client side is connected. 616 * The callback also notifies the server side of a local error on a 617 * not-yet-connected endpoint. 618 * 619 * This callback routine will be invoked on the server side upon receiving an 620 * incoming connection establishment acknowledgment from the client, which is sent 621 * from it once the client is connected to the server. Used to connect the server 622 * side to the client or handle an error from it - depending on the status field. 623 * This callback will also be invoked in the event of an internal local error 624 * with a failed @ref uct_cm_ep_server_conn_notify_args::status if the endpoint 625 * was not connected yet. 626 * This callback has to be thread safe. 627 * Other than communication progress routines, it is permissible to call other UCT 628 * communication routines from this callback. 629 * 630 * @param [in] ep Transport endpoint. 631 * @param [in] arg User argument for this callback as defined in 632 * @ref uct_ep_params_t::user_data 633 * @param [in] connect_args Server's connect callback arguments. 634 */ 635 typedef void (*uct_cm_ep_server_conn_notify_callback_t) 636 (uct_ep_h ep, void *arg, 637 const uct_cm_ep_server_conn_notify_args_t *connect_args); 638 639 640 /** 641 * @ingroup UCT_CLIENT_SERVER 642 * @brief Callback to process an incoming connection response on the client side 643 * from the server or handle a local error on a not-yet-connected endpoint. 644 * 645 * This callback routine will be invoked on the client side upon receiving an 646 * incoming connection response from the server. Used to connect the client side 647 * to the server or handle an error from it - depending on the status field. 648 * This callback will also be invoked in the event of an internal local error 649 * with a failed @ref uct_cm_ep_client_connect_args::status if the endpoint was 650 * not connected yet. 651 * This callback has to be thread safe. 652 * Other than communication progress routines, it is permissible to call other UCT 653 * communication routines from this callback. 654 * 655 * @param [in] ep Transport endpoint. 656 * @param [in] arg User argument for this callback as defined in 657 * @ref uct_ep_params_t::user_data. 658 * @param [in] connect_args Client's connect callback arguments 659 */ 660 typedef void (*uct_cm_ep_client_connect_callback_t)(uct_ep_h ep, void *arg, 661 const uct_cm_ep_client_connect_args_t 662 *connect_args); 663 664 665 /** 666 * @ingroup UCT_CLIENT_SERVER 667 * @brief Callback to handle the disconnection of the remote peer. 668 * 669 * This callback routine will be invoked on the client and server sides upon 670 * a disconnect of the remote peer. It will disconnect the given endpoint from 671 * the remote peer. 672 * This callback won't be invoked if the endpoint was not connected to the remote 673 * peer yet. 674 * This callback has to be thread safe. 675 * Other than communication progress routines, it is permissible to call other UCT 676 * communication routines from this callback. 677 * 678 * @param [in] ep Transport endpoint to disconnect. 679 * @param [in] arg User argument for this callback as defined in 680 * @ref uct_ep_params_t::user_data. 681 */ 682 typedef void (*uct_ep_disconnect_cb_t)(uct_ep_h ep, void *arg); 683 684 685 /** 686 * @ingroup UCT_CLIENT_SERVER 687 * @brief Callback to fill the user's private data in a client-server flow. 688 * 689 * This callback routine will be invoked on the client side, before sending the 690 * transport's connection request to the server, or on the server side before 691 * sending a connection response to the client. 692 * The callback routine must be set when creating an endpoint. 693 * The user's private data should be placed inside the priv_data buffer to be 694 * sent to the remote side. 695 * The maximal allowed length of the private data is indicated by the field 696 * max_conn_priv inside @ref uct_iface_attr or inside @ref uct_cm_attr when using a 697 * connection manager. 698 * Communication progress routines should not be called from this callback. 699 * It is allowed to call other UCT communication routines from this callback. 700 * 701 * @param [in] arg User defined argument for this callback. 702 * @param [in] pack_args Handle for the the private data packing. 703 * @param [out] priv_data User's private data to be passed to the remote side. 704 * 705 * @return Negative value indicates an error according to @ref ucs_status_t. 706 * On success, a non-negative value indicates actual number of 707 * bytes written to the @a priv_data buffer. 708 */ 709 typedef ssize_t 710 (*uct_cm_ep_priv_data_pack_callback_t)(void *arg, 711 const uct_cm_ep_priv_data_pack_args_t 712 *pack_args, void *priv_data); 713 714 715 /** 716 * @ingroup UCT_TAG 717 * @brief Callback to process unexpected eager tagged message. 718 * 719 * This callback is invoked when tagged message sent by eager protocol has 720 * arrived and no corresponding tag has been posted. 721 * 722 * @note The callback is always invoked from the context (thread, process) 723 * that called @a uct_iface_progress(). 724 * 725 * @note It is allowed to call other communication routines from the callback. 726 * 727 * @param [in] arg User-defined argument 728 * @param [in] data Points to the received unexpected data. 729 * @param [in] length Length of data. 730 * @param [in] flags Mask with @ref uct_cb_param_flags flags. If it 731 * contains @ref UCT_CB_PARAM_FLAG_DESC value, this means 732 * @a data is part of a descriptor which must be released 733 * later using @ref uct_iface_release_desc by the user if 734 * the callback returns @ref UCS_INPROGRESS. 735 * @param [in] stag Tag from sender. 736 * @param [in] imm Immediate data from sender. 737 * 738 * @param [inout] context Storage for a per-message user-defined context. In 739 * this context, the message is defined by the sender 740 * side as a single call to uct_ep_tag_eager_short/bcopy/zcopy. 741 * On the transport level the message can be fragmented 742 * and delivered to the target over multiple fragments. 743 * The fragments will preserve the original order of the 744 * message. Each fragment will result in invocation of 745 * the above callback. The user can use 746 * UCT_CB_PARAM_FLAG_FIRST to identify the first fragment, 747 * allocate the context object and use the context as a 748 * token that is set by the user and passed to subsequent 749 * callbacks of the same message. The user is responsible 750 * for allocation and release of the context. 751 * 752 * @note No need to allocate the context in the case of a single fragment message 753 * (i.e. @a flags contains @ref UCT_CB_PARAM_FLAG_FIRST, but does not 754 * contain @ref UCT_CB_PARAM_FLAG_MORE). 755 * 756 * @retval UCS_OK - data descriptor was consumed, and can be released 757 * by the caller. 758 * @retval UCS_INPROGRESS - data descriptor is owned by the callee, and will be 759 * released later. 760 */ 761 typedef ucs_status_t (*uct_tag_unexp_eager_cb_t)(void *arg, void *data, 762 size_t length, unsigned flags, 763 uct_tag_t stag, uint64_t imm, 764 void **context); 765 766 767 /** 768 * @ingroup UCT_TAG 769 * @brief Callback to process unexpected rendezvous tagged message. 770 * 771 * This callback is invoked when rendezvous send notification has arrived 772 * and no corresponding tag has been posted. 773 * 774 * @note The callback is always invoked from the context (thread, process) 775 * that called @a uct_iface_progress(). 776 * 777 * @note It is allowed to call other communication routines from the callback. 778 * 779 * @param [in] arg User-defined argument 780 * @param [in] flags Mask with @ref uct_cb_param_flags 781 * @param [in] stag Tag from sender. 782 * @param [in] header User defined header. 783 * @param [in] header_length User defined header length in bytes. 784 * @param [in] remote_addr Sender's buffer virtual address. 785 * @param [in] length Sender's buffer length. 786 * @param [in] rkey_buf Sender's buffer packed remote key. It can be 787 * passed to uct_rkey_unpack() to create uct_rkey_t. 788 * 789 * @warning If the user became the owner of the @a desc (by returning 790 * @ref UCS_INPROGRESS) the descriptor must be released later by 791 * @ref uct_iface_release_desc by the user. 792 * 793 * @retval UCS_OK - descriptor was consumed, and can be released 794 * by the caller. 795 * @retval UCS_INPROGRESS - descriptor is owned by the callee, and would be 796 * released later. 797 */ 798 typedef ucs_status_t (*uct_tag_unexp_rndv_cb_t)(void *arg, unsigned flags, 799 uint64_t stag, const void *header, 800 unsigned header_length, 801 uint64_t remote_addr, size_t length, 802 const void *rkey_buf); 803 804 805 /** 806 * @ingroup UCT_RESOURCE 807 * @brief Callback to process asynchronous events. 808 * 809 * @param [in] arg User argument to be passed to the callback. 810 * @param [in] flags Flags to be passed to the callback (reserved for 811 * future use). 812 */ 813 typedef void (*uct_async_event_cb_t)(void *arg, unsigned flags); 814 815 816 #endif 817