1 /* 2 * CDDL HEADER START 3 * 4 * The contents of this file are subject to the terms of the 5 * Common Development and Distribution License, Version 1.0 only 6 * (the "License"). You may not use this file except in compliance 7 * with the License. 8 * 9 * You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE 10 * or http://www.opensolaris.org/os/licensing. 11 * See the License for the specific language governing permissions 12 * and limitations under the License. 13 * 14 * When distributing Covered Code, include this CDDL HEADER in each 15 * file and include the License file at usr/src/OPENSOLARIS.LICENSE. 16 * If applicable, add the following below this CDDL HEADER, with the 17 * fields enclosed by brackets "[]" replaced with your own identifying 18 * information: Portions Copyright [yyyy] [name of copyright owner] 19 * 20 * CDDL HEADER END 21 */ 22 /* 23 * Copyright 2004 Sun Microsystems, Inc. All rights reserved. 24 * Use is subject to license terms. 25 */ 26 27 #ifndef _SYS_IB_MGT_IBMF_IBMF_H 28 #define _SYS_IB_MGT_IBMF_IBMF_H 29 30 /* 31 * This file defines the IBMF client interface. 32 */ 33 34 #ifdef __cplusplus 35 extern "C" { 36 #endif 37 38 #include <sys/note.h> 39 #include <sys/ib/ib_types.h> 40 #include <sys/ib/ib_pkt_hdrs.h> 41 #include <sys/ib/mgt/ib_mad.h> 42 #include <sys/ib/mgt/ibmf/ibmf_msg.h> 43 #include <sys/ib/mgt/ibmf/ibmf_saa.h> 44 #include <sys/ib/mgt/ibmf/ibmf_utils.h> 45 46 /* IBMF API function return values */ 47 #define IBMF_SUCCESS 0 /* successful call */ 48 #define IBMF_FAILURE -1 /* ibmf internal error */ 49 #define IBMF_PORT_IN_USE -2 /* class already registered */ 50 #define IBMF_BAD_CLASS -3 /* bad class specified */ 51 #define IBMF_BAD_HANDLE -4 /* bad ibmf handle */ 52 #define IBMF_BAD_QP_HANDLE -5 /* bad QP handle */ 53 #define IBMF_BAD_NODE -6 /* bad node specified to reg */ 54 #define IBMF_BAD_PORT -7 /* bad port specified to reg */ 55 #define IBMF_BAD_PORT_STATE -8 /* port in incorrect state */ 56 #define IBMF_BAD_VERSION -9 /* bad IBMF version */ 57 #define IBMF_BAD_FLAGS -10 /* bad IBMF flags */ 58 #define IBMF_BAD_SIZE -11 /* bad data size in message */ 59 #define IBMF_BAD_RMPP_OPT -12 /* more than one class used */ 60 #define IBMF_BUSY -13 /* resources held by client */ 61 #define IBMF_NO_RESOURCES -14 /* no resources */ 62 #define IBMF_NOT_SUPPORTED -15 /* function not supported */ 63 #define IBMF_PARTIAL_TRANSFER -16 /* excess response data */ 64 #define IBMF_UNEXP_TRANS_RECVD -17 /* unexpected trans received */ 65 #define IBMF_TRANS_TIMEOUT -18 /* transaction timed out */ 66 #define IBMF_TRANS_FAILURE -19 /* transaction failure */ 67 #define IBMF_NO_MEMORY -20 /* could not alloc memory */ 68 #define IBMF_REQ_INVALID -21 /* request was invalid */ 69 #define IBMF_NO_RECORDS -22 /* no records match query */ 70 #define IBMF_TOO_MANY_RECORDS -23 /* too many recs match query */ 71 #define IBMF_INVALID_GID -24 /* invalid gid in sa request */ 72 #define IBMF_INSUFF_COMPS -25 /* insufficient components */ 73 #define IBMF_UNSUPP_METHOD -26 /* unsupported method */ 74 #define IBMF_UNSUPP_METHOD_ATTR -27 /* unsupp. method/attrbute */ 75 #define IBMF_INVALID_FIELD -28 /* invalid field in MAD */ 76 #define IBMF_INVALID_ARG -29 /* invalid function argument */ 77 #define IBMF_CB_REGISTERED -30 /* callback already regd */ 78 #define IBMF_CB_NOT_REGISTERED -31 /* callback not registered */ 79 #define IBMF_TRANSPORT_FAILURE -32 /* a transport call failed */ 80 #define IBMF_TID_IN_USE -33 /* client's TID in use */ 81 82 /* flags to ibmf_alloc_msg() */ 83 #define IBMF_ALLOC_SLEEP 0 84 #define IBMF_ALLOC_NOSLEEP 1 85 86 /* 87 * IBMF version 88 */ 89 #define IBMF_VERSION 1 90 91 typedef struct _ibmf_handle_dummy *ibmf_handle_t; 92 93 typedef struct _ibmf_qp_dummy *ibmf_qp_handle_t; 94 95 /* 96 * IBMF default QP handles 97 */ 98 #define IBMF_QP_HANDLE_DEFAULT (ibmf_qp_handle_t)0 99 100 /* 101 * ir_client_type 102 */ 103 typedef enum _ibmf_client_type_t { 104 SUBN_AGENT = 0x00010001, 105 SUBN_MANAGER = 0x00020001, 106 SUBN_ADM_AGENT = 0x00010003, 107 SUBN_ADM_MANAGER = 0x00020003, 108 PERF_AGENT = 0x00010004, 109 PERF_MANAGER = 0x00020004, 110 BM_AGENT = 0x00010005, 111 BM_MANAGER = 0x00020005, 112 DEV_MGT_AGENT = 0x00010006, 113 DEV_MGT_MANAGER = 0x00020006, 114 COMM_MGT_MANAGER_AGENT = 0x00030007, 115 SNMP_MANAGER_AGENT = 0x00030008, 116 VENDOR_09_MANAGER_AGENT = 0x00030009, 117 VENDOR_0A_MANAGER_AGENT = 0x0003000A, 118 VENDOR_0B_MANAGER_AGENT = 0x0003000B, 119 VENDOR_0C_MANAGER_AGENT = 0x0003000C, 120 VENDOR_0D_MANAGER_AGENT = 0x0003000D, 121 VENDOR_0E_MANAGER_AGENT = 0x0003000E, 122 VENDOR_0F_MANAGER_AGENT = 0x0003000F, 123 VENDOR_30_MANAGER_AGENT = 0x00030030, 124 VENDOR_31_MANAGER_AGENT = 0x00030031, 125 VENDOR_32_MANAGER_AGENT = 0x00030032, 126 VENDOR_33_MANAGER_AGENT = 0x00030033, 127 VENDOR_34_MANAGER_AGENT = 0x00030034, 128 VENDOR_35_MANAGER_AGENT = 0x00030035, 129 VENDOR_36_MANAGER_AGENT = 0x00030036, 130 VENDOR_37_MANAGER_AGENT = 0x00030037, 131 VENDOR_38_MANAGER_AGENT = 0x00030038, 132 VENDOR_39_MANAGER_AGENT = 0x00030039, 133 VENDOR_3A_MANAGER_AGENT = 0x0003003A, 134 VENDOR_3B_MANAGER_AGENT = 0x0003003B, 135 VENDOR_3C_MANAGER_AGENT = 0x0003003C, 136 VENDOR_3D_MANAGER_AGENT = 0x0003003D, 137 VENDOR_3E_MANAGER_AGENT = 0x0003003E, 138 VENDOR_3F_MANAGER_AGENT = 0x0003003F, 139 VENDOR_40_MANAGER_AGENT = 0x00030040, 140 VENDOR_41_MANAGER_AGENT = 0x00030041, 141 VENDOR_42_MANAGER_AGENT = 0x00030042, 142 VENDOR_43_MANAGER_AGENT = 0x00030043, 143 VENDOR_44_MANAGER_AGENT = 0x00030044, 144 VENDOR_45_MANAGER_AGENT = 0x00030045, 145 VENDOR_46_MANAGER_AGENT = 0x00030046, 146 VENDOR_47_MANAGER_AGENT = 0x00030047, 147 VENDOR_48_MANAGER_AGENT = 0x00030048, 148 VENDOR_49_MANAGER_AGENT = 0x00030049, 149 VENDOR_4A_MANAGER_AGENT = 0x0003004A, 150 VENDOR_4B_MANAGER_AGENT = 0x0003004B, 151 VENDOR_4C_MANAGER_AGENT = 0x0003004C, 152 VENDOR_4D_MANAGER_AGENT = 0x0003004D, 153 VENDOR_4E_MANAGER_AGENT = 0x0003004E, 154 VENDOR_4F_MANAGER_AGENT = 0x0003004F, 155 APPLICATION_10_MANAGER_AGENT = 0x00030010, 156 APPLICATION_11_MANAGER_AGENT = 0x00030011, 157 APPLICATION_12_MANAGER_AGENT = 0x00030012, 158 APPLICATION_13_MANAGER_AGENT = 0x00030013, 159 APPLICATION_14_MANAGER_AGENT = 0x00030014, 160 APPLICATION_15_MANAGER_AGENT = 0x00030015, 161 APPLICATION_16_MANAGER_AGENT = 0x00030016, 162 APPLICATION_17_MANAGER_AGENT = 0x00030017, 163 APPLICATION_18_MANAGER_AGENT = 0x00030018, 164 APPLICATION_19_MANAGER_AGENT = 0x00030019, 165 APPLICATION_1A_MANAGER_AGENT = 0x0003001A, 166 APPLICATION_1B_MANAGER_AGENT = 0x0003001B, 167 APPLICATION_1C_MANAGER_AGENT = 0x0003001C, 168 APPLICATION_1D_MANAGER_AGENT = 0x0003001D, 169 APPLICATION_1E_MANAGER_AGENT = 0x0003001E, 170 APPLICATION_1F_MANAGER_AGENT = 0x0003001F, 171 APPLICATION_20_MANAGER_AGENT = 0x00030020, 172 APPLICATION_21_MANAGER_AGENT = 0x00030021, 173 APPLICATION_22_MANAGER_AGENT = 0x00030022, 174 APPLICATION_23_MANAGER_AGENT = 0x00030023, 175 APPLICATION_24_MANAGER_AGENT = 0x00030024, 176 APPLICATION_25_MANAGER_AGENT = 0x00030025, 177 APPLICATION_26_MANAGER_AGENT = 0x00030026, 178 APPLICATION_27_MANAGER_AGENT = 0x00030027, 179 APPLICATION_28_MANAGER_AGENT = 0x00030028, 180 APPLICATION_29_MANAGER_AGENT = 0x00030029, 181 APPLICATION_2A_MANAGER_AGENT = 0x0003002A, 182 APPLICATION_2B_MANAGER_AGENT = 0x0003002B, 183 APPLICATION_2C_MANAGER_AGENT = 0x0003002C, 184 APPLICATION_2D_MANAGER_AGENT = 0x0003002D, 185 APPLICATION_2E_MANAGER_AGENT = 0x0003002E, 186 APPLICATION_2F_MANAGER_AGENT = 0x0003002F, 187 UNIVERSAL_CLASS = 0x00040001 188 } ibmf_client_type_t; 189 190 /* 191 * ibmf_retrans_t data type is used to specify the maximum values 192 * of the retransmission parameters, number of retries, 193 * response time value, round trip travel time, and transaction timeout. 194 * 195 * The retries value must be provided by the client 196 * for all the transaction types enumerated by ibmf_trans_t. 197 * The retries value will be used to retry any section of 198 * the underlying transmission and reception protocol that 199 * are time bound by timers. 200 * 201 * The response time value must be specified for all transaction types except an 202 * unsequenced, non-RMPP send (see the table below). 203 * The response time value is the length of processing time for the 204 * responder to process the requested transaction, from the point of receiving 205 * the last request packet, to the point of returning the first response packet. 206 * This value is interpreted in microseconds. 207 * If the response time value is zero, an implementation default is used. 208 * 209 * The round trip time must be specified for all transaction types except an 210 * unsequenced, non-RMPP send (see the table below). 211 * The round trip travel time is the maximum time it should take a packet 212 * to travel from the requester to the responder and back to the requester. 213 * This value does not include the processing time at the responder. 214 * This value is interpreted in microseconds. 215 * If the round trip time value is zero, an implementation default is used. 216 * 217 * The transaction timeout should be specified for all transactions 218 * using RMPP to receive a message. 219 * Since, it is not possible for the client to know the size of the 220 * response, IBMF will calculate a reasonable transaction timeout after 221 * receiving the first RMPP data packet of the response at which time the 222 * size of the message will be known. If this value is greater than the 223 * client's transaction timeout parameter the client's value will be used. 224 * If the client's transaction timeout parameter is 0 the calculated value will 225 * be used. 226 * This value is interpreted in microseconds. 227 * If the transaction timeout value is zero, an implementation default is used. 228 * 229 * See Section 13.6.3.1, of the InfiniBand Architecture Specification, 230 * Volume 1, Release 1.1 for details on how to deduce this value. 231 * 232 * The following table describes the retrans parameters needed for 233 * the various ibmf_msg_transport() flag combinations. 234 * 235 * ibmf_msg_transport() flags retries rtv/rttv trans_to 236 * No Flags ignored ignored ignored 237 * Sequenced Flag required required required 238 * RMPP Flag required required ignored 239 * RMPP + Sequenced Flags required required optional 240 */ 241 typedef struct _ibmf_retrans_t { 242 uint32_t retrans_retries; /* number of retries */ 243 uint32_t retrans_rtv; /* response time value */ 244 uint32_t retrans_rttv; /* round trip travel time */ 245 uint32_t retrans_trans_to; /* transaction timeout */ 246 } ibmf_retrans_t; 247 248 typedef struct _ibmf_register_info { 249 ib_guid_t ir_ci_guid; 250 uint_t ir_port_num; 251 ibmf_client_type_t ir_client_class; 252 } ibmf_register_info_t; 253 254 typedef enum _ibmf_impl_caps { 255 IBMF_DEF_QP_HDL_P_KEY_ANY = 0x0001, 256 IBMF_DEF_QP_HDL_Q_KEY_ANY = 0x0002, 257 IBMF_NON_DEF_QP_HDL_P_KEY_ANY = 0x0004, 258 IBMF_NON_DEF_QP_HDL_Q_KEY_ANY = 0x0008 259 } ibmf_impl_caps_t; 260 261 262 /* 263 * Defines for channel interface events. 264 * IBMF_CI_OFFLINE : 265 * Indication to the client that it must cease all ibmf activity 266 * (after any current activity has terminated). The client must 267 * release all ibmf resources and unregister from ibmf prior to 268 * returning from the callback. 269 * 270 * NOTE1: It is expected that there will exist some higher level 271 * management entity that will "wake up" the ibmf client once 272 * the CI is available. The ibmf client may then register with the 273 * available CI's nodeguid and portnumber. 274 * 275 * NOTE2: callback implementors must handle the case where the 276 * callback is invoked AFTER the ibmf resources have been freed by 277 * another thread. 278 */ 279 typedef enum ibmf_async_event_e { 280 IBMF_CI_OFFLINE = 0x1 281 } ibmf_async_event_t; 282 283 /* 284 * ibmf_async_event_cb_t(): 285 * IBMF's callback to clients to inform them of events such as 286 * the ibmf services temporarily suspending or resuming. 287 * This notification mechanism covers all asynchronous events 288 * of interest that are not related to IB messages. 289 * 290 * NOTE: 291 * It is possible for the callback function to be called before 292 * ibmf_register() returns. When this happens, the entity doing the 293 * ibmf_register() may see an ibmf_handle being passed to the 294 * callback function that it does not recognize. 295 * 296 * Input arguments: 297 * ibmf_handle - Handle to the IBMF interface 298 * clnt_private - is an opaque handle to client specific data 299 * event_type - specifies the event type the client is being notified of 300 * 301 * Output arguments: 302 * None 303 * 304 * Return values: 305 * None 306 */ 307 typedef void (*ibmf_async_event_cb_t)( 308 ibmf_handle_t ibmf_handle, 309 void *clnt_private, 310 ibmf_async_event_t event_type); 311 312 /* 313 * ibmf_msg_cb_t(): 314 * 315 * This routine type is called by IBMF when an unsolicited message that 316 * corresponds to one of the class registrants is received. An unsolicited 317 * message is one that was not allocated by this client for the purpose 318 * of executing a transaction using the ibmf_msg_transport() call. 319 * Examples of unsolicited messages are traps, and requests from other 320 * management entities. 321 * 322 * This routine type is also called by IBMF at the end of a transaction 323 * specified in a call to ibmf_msg_transport(). 324 * 325 * When it is called as result of an incoming message: 326 * 327 * The recipient is expected to free the ibmf_msg_t passed in by 328 * calling ibmf_free_msg(); this freeing should be done before the 329 * client unregisters. 330 * 331 * The recipient is expected to not call any routines in the callback 332 * that may block. 333 * 334 * Blocking within the callback is not allowed, but ibmf doesn't enforce 335 * this. 336 * 337 * This routine may be called before ibmf_setup_async_cb() returns. 338 * 339 * 340 * Input arguments: 341 * Handle to the IBMF interface 342 * Pointer to the Message sent or received 343 * Callback arguments, specified at registration time (for async callbacks) 344 * or specified to ibmf_msg_transport() 345 * 346 * Output arguments: 347 * None 348 * 349 * Return values: 350 * None 351 */ 352 typedef void (*ibmf_msg_cb_t)( 353 ibmf_handle_t ibmf_handle, 354 ibmf_msg_t *msgp, 355 void *args); 356 357 /* defines for im_msg_flags */ 358 #define IBMF_MSG_FLAGS_GLOBAL_ADDRESS 0x00000010 /* has global addr */ 359 360 /* 361 * ibmf_register(): 362 * 363 * An agent needs to register before it can receive any management packets 364 * and a manager needs to register before it can send/receive any management 365 * packets. The registration is on a per port of the node basis. 366 * 367 * A client can register for one class per call to ibmf_register(). 368 * The client should set ir_client_class component of the client_info argument 369 * to the class it wants to register for. 370 * ibmf_register() will fail if the class is already registered for, 371 * with the error code IBMF_PORT_IN_USE. 372 * 373 * Note that for some classes, the client can register as agent or manager only 374 * and agent+manager only. An exception to this rule is the UNIVERSAL_CLASS 375 * described below. 376 * 377 * Clients that require to send/receive general UD traffic, 378 * not limited to MADs, over a UD QP may do so by registering 379 * with the UNIVERSAL_CLASS client type. 380 * Unlike the other IBMF client types, any number of clients may 381 * be simultaneously registered for the UNIVERSAL_CLASS on a port. 382 * When registered with the UNIVERSAL_CLASS, a client should only use the 383 * alternate QPs, and never use the default QP handle. 384 * However, a client registered for any other client type may also use 385 * the alternate QPs in addition to using the default QP handle. 386 * IBMF implementations that do not support registration for the UNIVERSAL class 387 * will return IBMF_NOT_SUPPORTED. 388 * 389 * NOTE on usage of qp handles: 390 * 391 * Some implementations support specifying any Q_Key and P_Key 392 * combination when ibmf_qp_handle_t arg is set to IBMF_QP_HANDLE_DEFAULT 393 * in the call to ibmf_msg_transport() and some implementations allow only 394 * the default values of Q_Key (0x8001_0000) and P_Key (0xFFFF/0x7FFFF) 395 * when ibmf_qp_handle_t arg is IBMF_QP_HANDLE_DEFAULT. The client can know 396 * the behavior supported via ibmf_impl_caps_t arg on successful return from 397 * ibmf_register(). ibmf_impl_caps_t arg points to a bit mask of the 398 * capabilities of the platform. If the implementation supports any 399 * P_Key and/or Q_Key value with IBMF_QP_HANDLE_DEFAULT, then 400 * IBMF_DEF_QP_HDL_P_KEY_ANY and/or IBMF_DEF_QP_HDL_Q_KEY_ANY will be set in 401 * ibmf_impl_caps_t. 402 * 403 * Some implementations support specifying any P_Key and Q_Key combination on 404 * a per-request basis when ibmf_qp_handle_t is set to an explicitly allocated 405 * qp handle (the client specifies the P_Key/Q_Key value in ibmf_addr_info_t 406 * argument). IBMA indicates this behavior by setting 407 * IBMF_NON_DEF_QP_HDL_P_KEY_ANY and/or IBMF_NON_DEF_QP_HDL_Q_KEY_ANY in the 408 * ibmf_impl_caps_t arg. In such an implementation, ibmf_modify_qp() does not 409 * change anything in the transport and always returns IBMF_SUCCESS. 410 * 411 * When the implementation supports IBMF_DEF_QP_HDL_P_KEY_ANY and/or 412 * IBMF_DEF_QP_HDL_Q_KEY_ANY, it may map IBMF_QP_HANDLE_DEFAULT to any qp 413 * number(s) supported by the 414 * underlying transport. The client can not not make any assumptions on this 415 * mapping nor can it query ibmf for the qp num being used with 416 * IBMF_QP_HANDLE_DEFAULT. There are cases where the client needs to have 417 * explicit control over the qp number being used by ibmf (eg., agent 418 * redirection). The client should explicitly allocate a qp using 419 * ibmf_alloc_qp() in such cases. 420 * 421 * Also, IBMF_QP_HANDLE_DEFAULT can only be used when the class of the MAD 422 * being sent using ibmf_msg_transport() is the same as the class the client 423 * registered for. If a client wishes to send a MAD class other than the 424 * one it registered for, it should explicitly allocate a qp and use that 425 * qp while sending MADs. 426 * 427 * If the implementation supports 428 * IBMF_DEF_QP_HDL_P_KEY_ANY/IBMF_DEF_QP_HDL_Q_KEY_ANY and/or 429 * IBMF_NON_DEF_QP_HDL_P_KEY_ANY/IBMF_NON_DEF_QP_HDL_Q_KEY_ANY, it is the 430 * implementation's responsibility to ensure that the 431 * requested P_Key and Q_Key can be used by, with in resource limitations, 432 * concurrent sends. 433 * 434 * Clients registering for classes that include an RMPP header in their 435 * MADs must set the IBMF_REG_FLAG_RMPP flag when registering with IBMF. 436 * This must be done regardless of whether the client intends to use 437 * the RMPP protocol or not. The flag is an indicator to IBMF of the 438 * presence of the RMPP header in the MAD. 439 * 440 * IBMF will always insure that receive buffer pointers are offsets into a 441 * single contiguous buffer of memory. The im_msgbufs_recv.im_bufs_mad_hdr, 442 * points to the start of the buffer. The other two pointers, 443 * im_msgbufs_recv.im_bufs_cl_hdr, and im_msgbufs_recv.im_bufs_cl_data, 444 * will point to class specific offsets within the buffer. 445 * 446 * Clients may provide a pointer to a callback function in the client_cb 447 * argument. Implementations of ibmf that require the client_cb to 448 * be specified should return IBMF_INVALID_ARG if the client_cb argument 449 * is NULL. 450 * 451 * This interface may block 452 * 453 * Input arguments: 454 * Pointer to client registration information 455 * Version of the interface (IBMF_VERSION) 456 * flags - set IBMF_REG_FLAG_RMPP if client supports RMPP MAD 457 * set IBMF_REG_FLAG_NO_OFFLOAD for requiring that processing 458 * not be offloaded onto a non-interrupt context thread 459 * on send completions and receive completions. 460 * (Processsing will be done in the interrupt context) 461 * The default is to offload the processing to a 462 * non-interrupt context thread(s). 463 * set IBMF_REG_FLAG_SINGLE_OFFLOAD for requiring single 464 * threaded processing if IBMF_REG_FLAG_NO_OFFLOAD 465 * is not specified. The default is multi-threaded 466 * processing. It is an error to set this flag if 467 * IBMF_REG_FLAG_NO_OFFLOAD is set. 468 * client_cb - callback to be called for asynchronous events that 469 * are not related to IB messages 470 * client_cb_args - opaque pointer to client private data area 471 * 472 * Output arguments: 473 * Handle to the IBMF interface; used in subsequent interactions 474 * Pointer to ibmf_impl_caps_t; gives capabilities of the platform 475 * 476 * Return values: 477 * IBMF_SUCCESS - registration successful 478 * IBMF_BAD_VERSION - registration failed due to invalid version 479 * IBMF_PORT_IN_USE - registration failed - some entity already 480 * registered for the class on the node/port 481 * specified. 482 * IBMF_BAD_CLASS - registration failed - invalid class 483 * IBMF_BAD_PORT - registration failed - non existent port 484 * IBMF_BAD_NODE - registration failed - non existent node 485 * IBMF_BAD_FLAGS - IBMF_REG_FLAG_NO_OFFLOAD is specified with 486 * IBMF_REG_FLAG_SINGLE_OFFLOAD 487 * IBMF_INVALID_ARG - registration failed - invalid argument 488 * IBMF_FAILURE - registration failed - ibmf internal error 489 * IBMF_NO_RESOURCES - registration failed - not enough resources 490 * IBMF_TRANSPORT_FAILURE - registration failed - transport call failed 491 * 492 */ 493 int ibmf_register( 494 ibmf_register_info_t *client_info, 495 uint_t ibmf_version, 496 uint_t flags, 497 ibmf_async_event_cb_t client_cb, 498 void *client_cb_args, 499 ibmf_handle_t *ibmf_handle, 500 ibmf_impl_caps_t *ibmf_impl_features); 501 502 #define IBMF_REG_FLAG_RMPP 0x1 503 #define IBMF_REG_FLAG_NO_OFFLOAD 0x2 504 #define IBMF_REG_FLAG_SINGLE_OFFLOAD 0x4 505 506 /* 507 * ibmf_unregister(): 508 * 509 * Unregister a previously established registration. 510 * 511 * This interface may block. 512 * 513 * The client should free any and all ibmf_msg_t's passed in all 514 * "receive msg callbacks" before unregistering. Also, the client should 515 * ensure that it is not trying to send any messages before calling this 516 * routine. 517 * 518 * After successfully returning from this call, ibmf_handle should not be used 519 * for any further interactions with the IBMF. 520 * 521 * Input arguments: 522 * Handle to the IBMF interface 523 * flags - unused (should be 0) 524 * 525 * Output arguments: 526 * Handle to the IBMF interface; will be invalidated following 527 * this call. 528 * 529 * Return values: 530 * IBMF_SUCCESS - unregistration successful 531 * IBMF_BAD_HANDLE - unregistration failed - invalid handle 532 * passed in. 533 * IBMF_BUSY - unregistration failed - client has not 534 * freed all the resources (ibmf_msg_t's etc) 535 * allocated by the IBMF, the client 536 * has not removed all recv callbacks. 537 * IBMF_INVALID_ARG - invalid argument 538 * IBMF_FAILURE - ibmf internal error 539 * IBMF_NO_RESOURCES - not enough resources 540 * IBMF_TRANSPORT_FAILURE - transport call failed 541 */ 542 int ibmf_unregister( 543 ibmf_handle_t *ibmf_handle, 544 uint_t flags); 545 546 /* 547 * ibmf_setup_async_cb(): 548 * 549 * This routine establishes a callback that the IBMF invokes when a message 550 * corresponding to the class corresponding to ibmf_handle is received. 551 * It is an error to call this routine twice without an intervening 552 * call to ibmf_tear_down_async_cb() for the same ibmf_qp_handle/ibmf_handle 553 * combination. Only unsolicited message reception will result in this 554 * callback being invoked. 555 * 556 * This interface may block. 557 * 558 * The callback routine could be invoked before this function returns. 559 * 560 * Input arguments: 561 * Handle to the IBMF interface 562 * IBMF QP handle (either allocated via ibmf_alloc_qp() or 563 * IBMF_QP_HANDLE_DEFAULT) 564 * Callback routine 565 * Argument to be passed when the callback is invoked 566 * flags - unused (should be 0) 567 * 568 * Output arguments: 569 * None 570 * 571 * Return values: 572 * IBMF_SUCCESS - Callback established successfully 573 * IBMF_BAD_HANDLE - failure - invalid handle 574 * IBMF_BAD_QP_HANDLE - failure - invalid qp handle 575 * IBMF_CB_REGISTERED - failure - callback is already established 576 * IBMF_INVALID_ARG - failure - invalid argument 577 */ 578 int ibmf_setup_async_cb( 579 ibmf_handle_t ibmf_handle, 580 ibmf_qp_handle_t ibmf_qp_handle, 581 ibmf_msg_cb_t async_msg_cb, 582 void *async_msg_cb_args, 583 uint_t flags); 584 585 /* 586 * ibmf_tear_down_async_cb(): 587 * 588 * This routine removes the callback set up using ibmf_setup_async_cb. 589 * There will not be any callbacks if messages are received after successful 590 * return from this routine. There could be message received callbacks during 591 * the execution of this routine. 592 * 593 * This interface may block. 594 * 595 * Input arguments: 596 * Handle to the IBMF interface 597 * IBMF QP handle (either allocated via ibmf_alloc_qp() or 598 * IBMF_QP_HANDLE_DEFAULT) 599 * flags - unused (should be 0) 600 * 601 * Output arguments: 602 * None 603 * 604 * Return values: 605 * IBMF_SUCCESS - call successful 606 * IBMF_BAD_HANDLE - failure - invalid ibmf handle or qp handle 607 * IBMF_BAD_QP_HANDLE - failure - invalid qp handle 608 * IBMF_CB_NOT_REGISTERED - No callback currently registered 609 * IBMF_INVALID_ARG - failure - invalid argument 610 */ 611 int ibmf_tear_down_async_cb( 612 ibmf_handle_t ibmf_handle, 613 ibmf_qp_handle_t ibmf_qp_handle, 614 uint_t flags); 615 616 /* 617 * ibmf_msg_transport(): 618 * 619 * This interface does not block if a callback is specified. 620 * 621 * IBMF makes some preliminary checks and returns failure if the 622 * checks fail. The callback, if any, is not called in this case. If the 623 * checks pass, the message specified in msgp->im_msgbufs_send is relayed 624 * down into the transport layer over as many MAD packets as necessary 625 * to accommodate the entire message. The IBMF_MSG_TRANS_FLAG_RMPP flag is set 626 * when the RMPP protocol should be used when sending out the message. 627 * The IBMF_MSG_TRANS_FLAG_SEQ is set when the the transaction is a 628 * sequenced transaction (send and receive) where the client expects a reply. 629 * The transaction completion callback will be invoked when IBMF 630 * is done processing the send operation and after having received the 631 * complete response if one is due, with or without errors. 632 * If no callback is specified, the routine blocks till the underlying 633 * transport is done processing the send request and received the complete 634 * response, with or without errors 635 * 636 * When sending non-MAD traffic over the alternate QPs, 637 * if the message data exceeds the maximum MTU supported, the call will fail 638 * with the status IBMF_BAD_SIZE. 639 * 640 * NOTE: If the call is asynchronous, the callback may be invoked before 641 * the call returns. The client should be prepared to handle this possibility. 642 * 643 * The message is sent to the address specified by msgp->im_local_addr and 644 * msgp->im_global_addr (global address invalid for SMPs and is ignored). 645 * Note that the desired Q_Key and P_Key can be specified via 646 * msgp->im_local_addr. If the ibmf implementation does not support any 647 * value of Q_Key/P_Key with IBMF_QP_HANDLE_DEFAULT, it is an error to specify 648 * a Q_Key other than 0x8001_0000 and a P_Key other than 0xFFFF/0x7FFF when 649 * ibmf_qp_handle_t arg is set IBMF_QP_HANDLE_DEFAULT. (See the NOTE in 650 * ibmf_register() on what the platform supports.) In this case, when a q_key 651 * value other than 0x8001_0000 and/or P_Key value other than 652 * 0xFFFF/0x7FFF is desired, the client should allocate its own qp handle 653 * with the desired values and use that in the ibmf_msg_transport() call. 654 * ibmf_msg_transport() returns IBMF_BAD_HANDLE to flag the error. 655 * 656 * NOTE: If the qp handle is not the default handle (ie., not 657 * IBMF_QP_HANDLE_DEFAULT), it is possible for some other thread to modify 658 * P_Key and Q_Key value associated with the qp_handle while this function 659 * is executing; this routine may return IBMF_BAD_HANDLE if that 660 * happens. It is possible that the modification happens after this routine 661 * validates the values, in which case no error may be flagged. 662 * 663 * NOTE: if the class of the MAD being sent is not the same as what the 664 * ibmf_handle (obtained via ibmf_register()) corresponds to, ibmf_qp_handle 665 * can not be set to IBMF_QP_HANDLE_DEFAULT. 666 * 667 * NOTE on notation: A message structure allocated by an ibmf_alloc_msg() 668 * call or one returned in an unsolicted callback will be referred to as 669 * "Message". When referring to a message in the general sense of the word, 670 * it will be referred to as "message". 671 * NOTE: Rules for reusing an IBMF Message: 672 * Clients may reuse a Message, either provided by IBMF in an unsolicited 673 * request, or one obtained through the ibmf_alloc_msg() call, for a 674 * subsequent request from the client itself. The client may reuse a Message 675 * to avoid the overhead of allocating a new Message and new send buffers. 676 * To safely reuse Messages, the client must follow the rules listed below. 677 * 1) Using the receive buffers to send the message header and data: 678 * If the Message has been provided by IBMF in an unsolicited request, 679 * it will have its receive buffers already allocated and pointed to by 680 * im_msgbufs_recv pointers by IBMF. In such a case, a client may set 681 * the im_msgbufs_send pointers to the values in the im_msgbufs_recv 682 * thus reusing the buffer allocated by IBMF for the incoming Message. 683 * However, this may be done only when the request from the client is 684 * a non-sequenced operation i.e. IBMF_MSG_TRANS_FLAG_SEQ flag is not set. 685 * An attempt to reuse the receive buffer for any other operation will 686 * result in the failure of the ibmf_msg_transport() call with the error 687 * status IBMF_REQ_INVALID. 688 * 2) Providing send buffers to send the message header and data: 689 * If the client provides its own send buffers for the message header and data, 690 * the IBMF Message may be reused for both sequenced and non-sequenced 691 * transactions. Any receive buffers that were allocated by IBMF from a 692 * previous transaction, will be freed up once the Message is reused in an 693 * ibmf_msg_transport() call. New receive buffers will be provided by IBMF 694 * if the new transaction is a sequenced transaction. 695 * 696 * Input arguments: 697 * Handle to the IBMF interface 698 * IBMF QP handle (either allocated via ibmf_alloc_qp() or 699 * IBMF_QP_HANDLE_DEFAULT [see the NOTE above regarding MAD class]) 700 * Pointer to ibmf_msg_t to be sent 701 * A pointer to ibmf_retrans_t to specify retries and timeout 702 * values to use during the transaction. 703 * Function to be called when the operation is done. 704 * (the routine is blocking if this function is NULL). 705 * Argument to be passed when the callback is invoked 706 * flags - set IBMF_MSG_TRANS_FLAG_RMPP if send should use RMPP 707 * set IBMF_MSG_TRANS_FLAG_SEQ if transaction is sequenced 708 * 709 * Output arguments: 710 * None 711 * 712 * Return values: 713 * IBMF_SUCCESS - If blocking call, the operation was 714 * completed by the transport. For 715 * non blocking call, the request passed basic 716 * checks and the callback should be expected. 717 * IBMF_BAD_HANDLE - operation failure - invalid ibmf handle 718 * IBMF_BAD_QP_HANDLE - operation failure - invalid qp handle or 719 * q_key/p_key in msgp->ip_local_addr is 720 * inconsistent with ibmf_qp_handle (for eg., 721 * handle is IBMF_QP_HANDLE_DEFAULT and 722 * Q_Key/P_Key is non-default and platform 723 * doesn't support non-default keys on this 724 * qp_handle or handle is IBMF_QP_HANDLE_DEFAULT 725 * but MAD class is not the one specified to 726 * ibmf_register()) 727 * IBMF_BAD_PORT_STATE - operation failure - port in incorrect state 728 * for packet transmission 729 * IBMF_NO_RESOURCES - operation failure - temporarily out of 730 * resources and call may succeed on a retry 731 * IBMF_FAILURE - operation failure - unspecified error 732 * IBMF_BAD_SIZE - data size in message to long for single UD pkt 733 * IBMF_BAD_RMPP_OPT - the class or QP does not support RMPP 734 * IBMF_PARTIAL_TRANSFER - only part of the received data was returned 735 * to the client up to the message size limit. 736 * IBMF_TRANS_TIMEOUT - transaction timed out 737 * IBMF_TRANS_FAILURE - transaction failure 738 * IBMF_REQ_INVALID - tried to reuse receive buffer for sending 739 * message data in a sequenced operation. 740 * IBMF_BUSY - message already being processed 741 * IBMF_INVALID_ARG - invalid argument 742 * IBMF_FAILURE - ibmf internal error 743 * IBMF_NO_RESOURCES - not enough resources 744 * IBMF_TRANSPORT_FAILURE - transport call failed 745 * IBMF_BAD_SIZE - if msgp->im_msgbufs_send.im_bufs_mad_hdr 746 * is NULL when ibmf_qp_handle is the default 747 * QP handle, OR, if 748 * msgp->im_msgbufs_send.im_bufs_mad_hdr 749 * is NULL when ibmf_qp_handle is not the default 750 * QP handle and the alternate QP is not being 751 * used for RAW data traffic. 752 */ 753 int ibmf_msg_transport( 754 ibmf_handle_t ibmf_handle, 755 ibmf_qp_handle_t ibmf_qp_handle, 756 ibmf_msg_t *msgp, 757 ibmf_retrans_t *retrans, 758 ibmf_msg_cb_t msg_cb, 759 void *msg_cb_args, 760 uint_t flags); 761 762 #define IBMF_MSG_TRANS_FLAG_RMPP 0x1 763 #define IBMF_MSG_TRANS_FLAG_SEQ 0x2 764 765 /* 766 * ibmf_alloc_msg(): 767 * 768 * Alloc memory to hold the message being sent out or being received. 769 * The IBMF client must provide the buffers in im_msgbufs_send before 770 * calling ibmf_msg_transport(). If this message is used in a sequenced 771 * transaction response or an unsolicited transaction, IBMF will provide 772 * the buffers in im_msgbufs_recv with the response, once the 773 * transaction is complete. 774 * The client is responsible for freeing the buffers pointed to in 775 * im_msgbufs_send when they are no longer needed. IBMF will free the buffers 776 * in im_msgbufs_send once ibmf_free_msg() is called by the client. 777 * 778 * This interface may block if IBMF_ALLOC_SLEEP is specified. 779 * 780 * Input arguments: 781 * Handle to the IBMF interface 782 * sleep flag - IBMF_ALLOC_SLEEP/IBMF_ALLOC_NOSLEEP 783 * 784 * Output arguments: 785 * Pointer to the buffer allocated; may be NULL if system runs out 786 * of memory and IBMF_ALLOC_NOSLEEP is specified. 787 * 788 * Return values: 789 * IBMF_SUCCESS - allocation successful 790 * IBMF_BAD_HANDLE - alloc failed - Invalid IBMF handle passed in 791 * IBMF_BAD_FLAGS - allocation failed - invalid flags 792 * IBMF_INVALID_ARG - allocation failed - invalid argument 793 * IBMF_FAILURE - ibmf internal error 794 * IBMF_NO_RESOURCES - not enough resources 795 * IBMF_TRANSPORT_FAILURE - transport call failed 796 */ 797 int ibmf_alloc_msg( 798 ibmf_handle_t ibmf_handle, 799 int flag, 800 ibmf_msg_t **ibmf_msgpp); 801 802 803 /* 804 * ibmf_free_msg(): 805 * 806 * Free message context. This message context is either allocated when 807 * the client calls ibmf_alloc_msg() or is allocated by IBMF automatically in 808 * response to incoming unsolicited messages. For all incoming messages, 809 * solicited or unsolicited, IBMF will provide the buffers pointed to 810 * in im_msgbufs_recv. In addition to freeing the message context, 811 * IBMF is responsible for freeing any buffers allocated by itself, 812 * and pointed to in im_msgbufs_recv when the client calls ibmf_free_msg(). 813 * 814 * This interface does not block 815 * 816 * Input arguments: 817 * Handle to the IBMF interface 818 * Pointer to the buffer to be freed 819 * 820 * Output arguments: 821 * None 822 * 823 * Return values: 824 * IBMF_SUCCESS - free successful 825 * IBMF_BAD_HANDLE - free failed - Invalid IBMF handle passed in 826 * IBMF_BUSY - free failed - message in use 827 * IBMF_INVALID_ARG - free failed - invalid argument 828 * IBMF_FAILURE - ibmf internal error 829 * IBMF_NO_RESOURCES - not enough resources 830 * IBMF_TRANSPORT_FAILURE - transport call failed 831 */ 832 int ibmf_free_msg( 833 ibmf_handle_t ibmf_handle, 834 ibmf_msg_t **ibmf_msgpp); 835 836 837 /* 838 * ibmf_alloc_qp(): 839 * 840 * Alloc a qp with the specified P_key and Q_key values. A pointer to 841 * ibmf_qp_handle_t is returned if the call is successful. The qp is 842 * associated with the port that ibmf_handle corresponds to. 843 * 844 * Non-special QPs may be tagged to send and receive 845 * one of the three types of traffic, either non-MAD UD, or MADs with 846 * RMPP or MADs without RMPP. 847 * The tagging should be done when calling ibmf_alloc_qp() 848 * by setting the flags argument in the ibmf_alloc_qp() interface 849 * function call to specifically defined values. 850 * Only one, and at least one, of these flags must be specified. 851 * 852 * A client may specify the IBMF_ALT_QP_RAW_ONLY flag to limit 853 * the QP to non-MAD UD traffic. If this flag is specified, and the 854 * IBMF implementation supports this flag, the client may send 855 * and receive MADs up to the maximum MTU supported on the link 856 * connected to the chosen port. 857 * 858 * If any of the flag options are not supported by the IBMF implementation, 859 * IBMF will return IBMF_NOT_SUPPORTED. 860 * 861 * This interface may block 862 * 863 * Input arguments: 864 * Handle to the IBMF interface 865 * P_Key 866 * Q_Key 867 * flags - IBMF_ALT_QP_MAD_NO_RMPP = MAD traffic only, 868 * IBMF_ALT_QP_MAD_RMPP = RMPP MADs only, 869 * IBMF_ALT_QP_RAW_ONLY = Non-MAD UD traffic only 870 * 871 * Output arguments: 872 * Pointer to the qp handle 873 * 874 * Return values: 875 * IBMF_SUCCESS - allocation successful 876 * IBMF_BAD_HANDLE - alloc failed - Invalid IBMF handle passed in 877 * IBMF_NO_RESOURCES - alloc failed - no resources for qp allocation 878 * IBMF_BAD_FLAGS - allocation failed - bad flag combination 879 * IBMF_NOT_SUPPORTED - allocation failed - unsupported traffic 880 * IBMF_INVALID_ARG - allocation failed - invalid argument 881 * IBMF_NO_RESOURCES - not enough resources 882 * IBMF_TRANSPORT_FAILURE - transport call failed 883 * 884 */ 885 int ibmf_alloc_qp( 886 ibmf_handle_t ibmf_handle, 887 ib_pkey_t p_key, 888 ib_qkey_t q_key, 889 uint_t flags, 890 ibmf_qp_handle_t *ibmf_qp_handlep); 891 892 /* Flags values for ibmf_alloc_qp() flags argument */ 893 #define IBMF_ALT_QP_MAD_NO_RMPP 0x1 894 #define IBMF_ALT_QP_MAD_RMPP 0x2 895 #define IBMF_ALT_QP_RAW_ONLY 0x4 896 897 /* 898 * ibmf_query_qp(): 899 * 900 * This function returns the P_Key, Q_Key, qp num and the port num that the 901 * qp_handle corresponds to. It is possible that some other thread is 902 * modifying the p_key and q_key for the qp_handle while this function is 903 * executing or some other thread modifies the p_key/q_key values after the 904 * function returns. 905 * It is the callers responsibility to deal with these cases. 906 * 907 * This interface does not block. 908 * 909 * Input arguments: 910 * Handle to the IBMF interface 911 * IBMF qp handle (this can not be IBMF_QP_HANDLE_DEFAULT) 912 * flags - unused (should be 0) 913 * 914 * Output arguments: 915 * Pointer to QP num 916 * Pointer to P_key 917 * Pointer to Q_key 918 * Pointer to the port num 919 * 920 * Return values: 921 * IBMF_SUCCESS - call successful 922 * IBMF_BAD_HANDLE - failure - Invalid IBMF handle 923 * IBMF_BAD_QP_HANDLE - failure - Invalid qp handle 924 * IBMF_INVALID_ARG - failure - invalid argument 925 * IBMF_TRANSPORT_FAILURE - transport call failed 926 */ 927 int ibmf_query_qp( 928 ibmf_handle_t ibmf_handle, 929 ibmf_qp_handle_t ibmf_qp_handle, 930 uint_t *qp_num, 931 ib_pkey_t *p_key, 932 ib_qkey_t *q_key, 933 uint8_t *portnum, 934 uint_t flags); 935 936 /* 937 * ibmf_modify_qp(): 938 * 939 * This function sets the p_key and q_key associated with the qp handle to the 940 * values specified. 941 * 942 * This interface may block. 943 * 944 * Input arguments: 945 * Handle to the IBMF interface 946 * IBMF qp handle (this can not be IBMF_QP_HANDLE_DEFAULT) 947 * P_key 948 * Q_key 949 * flags - unused (should be 0) 950 * 951 * Output arguments: 952 * None 953 * 954 * Return values: 955 * IBMF_SUCCESS - call successful 956 * IBMF_BAD_HANDLE - failure - Invalid IBMF handle or qp handle 957 * IBMF_BAD_QP_HANDLE - failure - Invalid qp handle 958 * IBMF_INVALID_ARG - failure - invalid argument 959 * IBMF_TRANSPORT_FAILURE - transport call failed 960 */ 961 int ibmf_modify_qp( 962 ibmf_handle_t ibmf_handle, 963 ibmf_qp_handle_t ibmf_qp_handle, 964 ib_pkey_t p_key, 965 ib_qkey_t q_key, 966 uint_t flags); 967 968 /* 969 * ibmf_free_qp(): 970 * 971 * This function frees a qp allocated by ibmf_alloc_qp(). 972 * The ibmf handle argument must be the same ibmf handle used in the 973 * corresponding ibmf_alloc_qp() call. ibmf_unregister() for the ibmf 974 * handle will not be allowed until all associated qps are freed. 975 * The client must have already invoked ibmf_tear_down_recv_cb() 976 * for this qp handle prior to calling ibmf_free_qp(), else IBMF_BUSY 977 * will be returned. 978 * 979 * This interface may block. 980 * 981 * Input arguments: 982 * Handle to the IBMF interface 983 * IBMF qp handle pointer (this can not be IBMF_QP_HANDLE_DEFAULT) 984 * flags - unused (should be 0) 985 * 986 * Output arguments: 987 * IBMF qp handle; will be invalidated following successful return from 988 * this call 989 * 990 * Return values: 991 * IBMF_SUCCESS - call successful 992 * IBMF_BAD_HANDLE - failure - Invalid IBMF handle or qp handle 993 * IBMF_BAD_QP_HANDLE - failure - Invalid qp handle 994 * IBMF_BUSY - failure - callback is active 995 * IBMF_INVALID_ARG - failure - invalid argument 996 * IBMF_TRANSPORT_FAILURE - transport call failed 997 */ 998 int ibmf_free_qp( 999 ibmf_handle_t ibmf_handle, 1000 ibmf_qp_handle_t *ibmf_qp_handle, 1001 uint_t flags); 1002 1003 #ifdef __cplusplus 1004 } 1005 #endif 1006 1007 #endif /* _SYS_IB_MGT_IBMF_IBMF_H */ 1008