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