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 2003 Sun Microsystems, Inc. All rights reserved. 24 * Use is subject to license terms. 25 */ 26 27 #ifndef _SYS_IB_MGT_IBMF_IBMF_SAA_H 28 #define _SYS_IB_MGT_IBMF_IBMF_SAA_H 29 30 #pragma ident "%Z%%M% %I% %E% SMI" 31 32 #ifdef __cplusplus 33 extern "C" { 34 #endif 35 36 #include <sys/ib/ib_types.h> 37 #include <sys/ib/mgt/sa_recs.h> 38 39 /* 40 * SA Access Interface: Interfaces to enable access to the SA 41 */ 42 43 #define IBMF_SAA_PKEY_WC 0 /* partition key wildcard */ 44 #define IBMF_SAA_MTU_WC 0 /* mtu wilcard for gid_to_pathrecords */ 45 46 typedef enum _ibmf_saa_access_type_t { 47 IBMF_SAA_RETRIEVE, 48 IBMF_SAA_UPDATE, 49 IBMF_SAA_DELETE 50 } ibmf_saa_access_type_t; 51 52 /* 53 * ibmf_saa_handle 54 * Opaque handle to identify the consumer 55 */ 56 typedef struct ibmf_saa_handle *ibmf_saa_handle_t; 57 58 /* 59 * ibmf_saa_cb_t 60 * ibmf_saa's callback to clients to inform them that the response to an 61 * asynchronous request has arrived or that the request timed out. 62 * 63 * Input Arguments 64 * clnt_private - opaque handle to client specific data (sq_callback_arg) 65 * length - size of response returned 66 * result - pointer to buffer of response. Data will be in host-endian format 67 * and unpacked. Client can just cast to a pointer to the structure 68 * status - ibmf status. Status can be any of the values returned by a 69 * synchronous ibmf_sa_access() call. 70 * 71 * Output Arguments 72 * none 73 * 74 * Returns 75 * none 76 */ 77 typedef void (*ibmf_saa_cb_t) ( 78 void *callback_arg, 79 size_t length, 80 char *result, 81 int status); 82 83 /* 84 * structure to provide parameters to ibmf_sa_access call 85 */ 86 typedef struct ibmf_saa_access_args_s { 87 /* MAD attribute ID */ 88 uint16_t sq_attr_id; 89 90 /* retrieve, update, or delete */ 91 ibmf_saa_access_type_t sq_access_type; 92 93 /* SA MAD component mask indicating fields in template to query on */ 94 uint64_t sq_component_mask; 95 96 /* pointer to template */ 97 void *sq_template; 98 99 /* 100 * length, in bytes, of template size for attributes which ibmf does 101 * not know about; ignored for known attribute id's. length should be 102 * wire length and template for unknown attributes should be in wire 103 * format as ibmf will not be able to pack data. 104 */ 105 size_t sq_template_length; 106 107 /* callback and argument when asynchronous request returns */ 108 ibmf_saa_cb_t sq_callback; 109 void *sq_callback_arg; 110 } ibmf_saa_access_args_t; 111 112 /* 113 * enumeration of subnet events 114 * 115 * IBMF_SAA_EVENT_GID_AVAILABLE 116 * the identified gid is available 117 * IBMF_SAA_EVENT_GID_UNAVAILABLE 118 * the identified gid is unavailable 119 * IBMF_SAA_EVENT_MCG_CREATED 120 * MC group identified by mgid is created 121 * IBMF_SAA_EVENT_MCG_DELETED 122 * MC group identified by mgid is deleted 123 * IBMF_SAA_EVENT_CAP_MASK_CHG 124 * Portinfo.CapabilityMask changed 125 * IBMF_SAA_EVENT_SYS_IMG_GUID_CHG 126 * System Image GUID changed 127 * IBMF_SAA_EVENT_SUBSCRIBER_STATUS_CHG 128 * Status of ibmf subscriptions changed 129 */ 130 typedef enum ibmf_saa_subnet_event_e { 131 132 IBMF_SAA_EVENT_GID_AVAILABLE, 133 IBMF_SAA_EVENT_GID_UNAVAILABLE, 134 IBMF_SAA_EVENT_MCG_CREATED, 135 IBMF_SAA_EVENT_MCG_DELETED, 136 IBMF_SAA_EVENT_CAP_MASK_CHG, 137 IBMF_SAA_EVENT_SYS_IMG_GUID_CHG, 138 IBMF_SAA_EVENT_SUBSCRIBER_STATUS_CHG 139 140 } ibmf_saa_subnet_event_t; 141 142 /* 143 * ibmf must subscribe with the Subnet Administrator to provide the subnet 144 * events for its clients. It registers for the four trap producer types: CA, 145 * switch, router, and subnet management. If any of these registrations fails 146 * the ibmf will notify each client that registered for events. Clients are 147 * notified by ibmf through their registered callback and the 148 * SUBSCRIBER_STATUS_CHG event. 149 * 150 * For this event, the event_details producer_type_status_mask will be set. 151 * Each bit in the mask corresponds to a different producer type. When the bit 152 * is on the ibmf was able to successfully subscribe for events from that 153 * producer. When the bit is off, ibmf was unable to subscribe and clients may 154 * not receive events from that producer type. 155 * 156 * For example, if the status_mask is 0xb then events will be received that 157 * correspond to CA's, switches, and subnet management traps. However, traps 158 * generated by routers may not be received. 159 * 160 * The ibmf re-registers for events when the port transitions to active. If the 161 * event status mask changes the ibmf will generate another 162 * SUBSCRIBER_STATUS_CHG event with the new producer type status mask. When 163 * clients register they should only expect to receive a SUBSCRIBER_STATUS_CHG 164 * event if one of the registrations failed. If all four registrations 165 * succeeded no event will be generated. 166 * 167 * If the port goes down, a SUBSCRIBER_STATUS_CHG event is not generated. 168 * Clients should realize that events will not be forwarded. If the port 169 * transitions back to active ibmf_saa will resubscribe on behalf of the client. 170 * If this subscription fails a SUBSCRIBER_STATUS_CHG event will be generated. 171 * 172 */ 173 174 #define IBMF_SAA_EVENT_STATUS_MASK_PRODUCER_CA (1 << 0) 175 #define IBMF_SAA_EVENT_STATUS_MASK_PRODUCER_SWITCH (1 << 1) 176 #define IBMF_SAA_EVENT_STATUS_MASK_PRODUCER_ROUTER (1 << 2) 177 #define IBMF_SAA_EVENT_STATUS_MASK_PRODUCER_SM (1 << 3) 178 179 /* 180 * structure passed as event_details argument of ibmf_saa subnet event 181 * callback. 182 * 183 * Only some of the structure members are valid for a given event as given 184 * below: 185 * 186 * member event type 187 * ------ ---------- 188 * ie_gid IBMF_SAA_EVENT_GID_AVAILABLE, 189 * IBMF_SAA_EVENT_GID_UNAVAILABLE, 190 * IBMF_SAA_EVENT_MCG_CREATED, and 191 * IBMF_SAA_EVENT_MCG_DELETED 192 * ie_lid IBMF_SAA_EVENT_CAP_MASK_CHG and 193 * IBMF_SAA_EVENT_SYS_IMG_GUID_CHG 194 * ie_capability_mask IBMF_SAA_EVENT_CAP_MASK_CHG 195 * ie_sysimg_guid IBMF_SAA_EVENT_SYS_IMG_GUID_CHG 196 * ie_producer_type_status_mask IBMF_SAA_EVENT_SUBSCRIBER_STATUS_CHG 197 * 198 */ 199 typedef struct ibmf_saa_event_details_s { 200 ib_gid_t ie_gid; 201 ib_guid_t ie_sysimg_guid; 202 uint32_t ie_capability_mask; /* values defined in sm_attr.h */ 203 ib_lid_t ie_lid; 204 uint8_t ie_producer_event_status_mask; 205 } ibmf_saa_event_details_t; 206 207 /* 208 * Callback invoked when one of the events the client subscribed for 209 * at ibmf_sa_session_open() time happens. 210 * 211 * This callback can occur before ibmf_sa_session_open() returns. 212 * 213 * Each callback is on a separate thread. ibmf clients may block in the event 214 * callback. However, under heavy system load ibmf may not be able to generate 215 * event callbacks. Also, event callbacks, including SUBSCRIBER_STATUS_CHG, 216 * could be dispatched out-of-order. 217 * 218 * Arguments: 219 * ibmf_saa_handle - Client's ibmf_saa_handle 220 * ibmf_saa_event - event that caused the callback 221 * event_details - additional data for the event 222 * callback_arg - event_callback_arg member of 223 * ibmf_saa_subnet_event_args_t 224 */ 225 typedef void (*ibmf_saa_subnet_event_cb_t)( 226 ibmf_saa_handle_t ibmf_saa_handle, 227 ibmf_saa_subnet_event_t ibmf_saa_event, 228 ibmf_saa_event_details_t *event_details, 229 void *callback_arg); 230 231 typedef struct ibmf_saa_subnet_event_args_s { 232 233 /* func to be called when a subnet event happens */ 234 ibmf_saa_subnet_event_cb_t is_event_callback; 235 236 /* call back arg */ 237 void *is_event_callback_arg; 238 239 } ibmf_saa_subnet_event_args_t; 240 241 /* 242 * ibmf_sa_session_open(): 243 * 244 * Before using the ibmf_saa interface, consumers should register with the 245 * ibmf_saa interface by calling ibmf_sa_session_open(). Upon a successful 246 * registration, a handle is returned for use in subsequent interaction with the 247 * ibmf_saa interface; this handle is also provided as an argument to subnet 248 * event notification function. 249 * 250 * Consumers can register to be notified of subnet events such as GID 251 * being available/unavailable. Clients which provide a non-NULL event args 252 * structure will have the is_event_callback function called when an event is 253 * received or there is a failure in subscribing for events. This callback may 254 * be generated before the ibmf_sa_session_open() call returns. 255 * 256 * This interface blocks allocating memory, but not waiting for any packet 257 * responses. 258 * 259 * Arguments: 260 * port_guid - GUID of the port. 261 * event_args - subnet event registration details 262 * sm_key - only filled in if the consumer is an SM 263 * ibmf_version - version of the interface (IBMF_VERSION) 264 * flags - unused 265 * 266 * Return values: 267 * IBMF_SUCCESS - registration succeeded 268 * IBMF_BAD_PORT - registration failed; active port not found 269 * IBMF_BAD_PORT_STATE - registration failed; port found but not active or 270 * previous registration failed 271 * IBMF_NO_MEMORY - registration failed; could not allocate memory 272 * IBMF_NO_RESOURCES - registration failed due to a resource issue 273 * IBMF_BUSY - registration failed; too many clients registered 274 * for this port 275 * IBMF_TRANSPORT_FAILURE - failure with underlying transport framework 276 * IBMF_INVALID_ARG - ibmf_saa_handle arg was NULL 277 */ 278 int ibmf_sa_session_open( 279 ib_guid_t port_guid, 280 ib_smkey_t sm_key, 281 ibmf_saa_subnet_event_args_t *event_args, 282 uint_t ibmf_version, 283 uint_t flags, 284 ibmf_saa_handle_t *ibmf_saa_handle); 285 286 /* 287 * ibmf_sa_session_close() 288 * 289 * Unregister a consumer of the SA_Access interface 290 * 291 * This interface blocks. 292 * 293 * Arguments: 294 * ibmf_saa_handle - handle returned from sa_session_open() 295 * flags - unused 296 * 297 * Return values: 298 * IBMF_SUCCESS - unregistration succeeded 299 * IBMF_BAD_HANDLE - unregistration failed; handle is not valid or 300 * session_close has already been called 301 * IBMF_INVALID_ARG - ibmf_saa_handle arg was NULL 302 * 303 * All outstanding callbacks will be canceled before this function returns. 304 */ 305 int ibmf_sa_session_close( 306 ibmf_saa_handle_t *ibmf_saa_handle, 307 uint_t flags); 308 309 /* 310 * ibmf_sa_access 311 * 312 * Retrieve records from the SA given an AttributeID, ComponentMask, 313 * and a template 314 * 315 * This interface blocks if the callback parameter is NULL. 316 * 317 * Input Arguments: 318 * ibmf_saa_handle - handle returned from ibmf_sa_session_open() 319 * access_args - structure containing various parameters for the query 320 * flags - unsused 321 * 322 * Output Arguments: 323 * length - size of buffer returned 324 * result - pointer to buffer of records returned in response. 325 * Buffer is host-endian, unpacked can be cast to one of 326 * the record types in sa_recs.h 327 * 328 * Return values: 329 * IBMF_SUCCESS - query succeeded 330 * IBMF_BAD_HANDLE - sa session handle is invalid 331 * IBMF_BAD_PORT_STATE - port in incorrect state 332 * IBMF_INVALID_ARG - one of the pointer parameters was NULL 333 * IBMF_NO_RESOURCES - ibmf could not allocate ib resources or SA returned 334 * ERR_NO_RESOURCES 335 * IBMF_TRANS_TIMEOUT - transaction timed out 336 * IBMF_TRANS_FAILURE - transaction failure 337 * IBMF_NO_MEMORY - ibmf could not allocate memory 338 * IBMF_REQ_INVALID - send and recv buffer the same for a sequenced 339 * transaction or the SA returned an ERR_REQ_INVALID 340 * IBMF_NO_RECORDS - no records matched query 341 * IBMF_TOO_MANY_RECORDS- SA returned SA_ERR_TOO_MANY_RECORDS 342 * IBMF_INVALID_GID - SA returned SA_INVALID_GID 343 * IBMF_INSUFF_COMPS - SA returned SA_ERR_INSUFFICIENT_COMPS 344 * IBMF_UNSUPP_METHOD - SA returned MAD_STATUS_UNSUPP_METHOD 345 * IBMF_UNSUPP_METHOD_ATTR - SA returned MAD_STATUS_UNSUPP_METHOD_ATTR 346 * IBMF_INVALID_FIELD - SA returned MAD_STATUS_INVALID_FIELD 347 * IBMF_NO_ACTIVE_PORTS - no active ports found 348 * 349 * Upon successful completion, result points to a buffer containing the records. 350 * length is the size in bytes of the buffer returned in result. If there are 351 * no records or the call failed the length is 0. 352 * 353 * The consumer is responsible for freeing the memory associated with result. 354 */ 355 int ibmf_sa_access( 356 ibmf_saa_handle_t ibmf_saa_handle, 357 ibmf_saa_access_args_t *access_args, 358 uint_t flags, 359 size_t *length, 360 void **result); 361 362 /* 363 * Helper Functions. 364 * Ease of use functions so that the consumer doesn't 365 * have to do the overhead of calling ibmf_sa_access() for 366 * commonly used queries 367 */ 368 369 /* 370 * ibmf_saa_gid_to_pathrecords 371 * Given a source gid and a destination gid, return paths 372 * between the gids. 373 * 374 * This interface blocks. 375 * 376 * Input Arguments: 377 * ibmf_saa_handle - handle returned from ibmf_sa_session_open() 378 * sgid - source gid of path 379 * dgid - destination gid of path 380 * p_key - partition of path. This value may be wildcarded with 381 * IBMF_SAA_PKEY_WC. 382 * mtu - preferred MTU of the path. This argument may be 383 * wildcarded with IBMF_SAA_MTU_WC. 384 * reversible - if B_TRUE, ibmf will query only reversible paths 385 * see Infiniband Specification table 171 386 * num_paths - maximum number of paths to return 387 * numpaths should be checked for the actual number of 388 * records returned. 389 * flags - unused 390 * 391 * Output Arguments: 392 * num_paths - actual number of paths returned 393 * length - size of buffer returned 394 * result - pointer to buffer of path records returned in response 395 * 396 * Return values: 397 * Error codes are the same as ibmf_sa_access() return values 398 * 399 * Upon successful completion, result points to a buffer containing the records. 400 * length is the size in bytes of the buffer returned in result. If there are 401 * no records or the call failed the length is 0. 402 * 403 * The consumer is responsible for freeing the memory associated with result. 404 */ 405 int ibmf_saa_gid_to_pathrecords( 406 ibmf_saa_handle_t ibmf_saa_handle, 407 ib_gid_t sgid, 408 ib_gid_t dgid, 409 ib_pkey_t p_key, 410 ib_mtu_t mtu, 411 boolean_t reversible, 412 uint8_t *num_paths, 413 uint_t flags, 414 size_t *length, 415 sa_path_record_t **result); 416 /* 417 * ibmf_saa_paths_from_gid 418 * Given a source GID, return a path from the source gid 419 * to every other port on the subnet. It is assumed that the 420 * subnet is fully connected. Only one path per port on the subnet 421 * is returned. 422 * 423 * This interface blocks. 424 * 425 * Arguments: 426 * ibmf_saa_handle - handle returned from ibmf_sa_session_open() 427 * sgid - source gid of path 428 * pkey - paritition of path. This value may be wildcarded with 429 * IBMF_SAA_PKEY_WC. 430 * reversible - if B_TRUE, ibmf will query only reversible paths; 431 * see Infiniband Specification table 171 432 * flags - unused 433 * 434 * Output Arguments: 435 * num_paths - number of paths returned 436 * length - size of buffer returned 437 * result - pointer to buffer of path records returned in response 438 * 439 * Return values: 440 * Error codes are the same as ibmf_sa_access() return values 441 * 442 * Upon successful completion, result points to a buffer containing the records. 443 * and num_paths is the number of path records returned. length is the size 444 * in bytes of the buffer returned in result. If there are no records or the 445 * call failed the length is 0. 446 * 447 * The consumer is responsible for freeing the memory associated with result. 448 */ 449 int ibmf_saa_paths_from_gid( 450 ibmf_saa_handle_t ibmf_saa_handle, 451 ib_gid_t sgid, 452 ib_pkey_t pkey, 453 boolean_t reversible, 454 uint_t flags, 455 uint_t *num_paths, 456 size_t *length, 457 sa_path_record_t **result); 458 459 /* 460 * ibmf_saa_name_to_service_record: 461 * Given a service name, return the service records associated 462 * with it. 463 * 464 * This interface blocks. 465 * 466 * Input Arguments: 467 * ibmf_saa_handle - handle returned from ibmf_sa_session_open() 468 * name - service name, a null terminated string 469 * p_key - partition that the service is requested on. This 470 * value may be wildcarded with IBMF_SAA_PKEY_WC. 471 * flags - unused 472 * 473 * Output Arguments: 474 * num_records - number of service records returned 475 * length - size of buffer returned 476 * result - pointer to buffer of service records returned in 477 * response 478 * 479 * Return values: 480 * Error codes are the same as ibmf_sa_access() return values 481 * 482 * Upon successful completion, result points to a buffer containing the records. 483 * and num_records is the number of service records returned. length is the 484 * size in bytes of the buffer returned in result. If there are no records or 485 * the call failed the length is 0. 486 * 487 * The consumer is responsible for freeing the memory associated with result. 488 */ 489 int ibmf_saa_name_to_service_record( 490 ibmf_saa_handle_t ibmf_saa_handle, 491 char *service_name, 492 ib_pkey_t p_key, 493 uint_t flags, 494 uint_t *num_records, 495 size_t *length, 496 sa_service_record_t **result); 497 498 /* 499 * ibmf_saa_id_to_service_record: 500 * Given a service id, return the service records associated 501 * with it. 502 * 503 * This interface blocks. 504 * 505 * Input Arguments: 506 * ibmf_saa_handle - handle returned from ibmf_sa_session_open() 507 * id - service id 508 * p_key - partition that the service is requested on. This 509 * value may be wildcarded with IBMF_SAA_PKEY_WC. 510 * flags - unused 511 * 512 * Output Arguments: 513 * num_records - number of service records returned 514 * length - size of buffer returned 515 * result - pointer to buffer of service records returned in 516 * response 517 * 518 * Return values: 519 * Error codes are the same as ibmf_sa_access() return values 520 * 521 * Upon successful completion, result points to a buffer containing the records. 522 * and num_records is the number of service records returned. length is the 523 * size in bytes of the buffer returned in result. If there are no records or 524 * the call failed the length is 0. 525 * 526 * The consumer is responsible for freeing the memory associated with result. 527 */ 528 int ibmf_saa_id_to_service_record( 529 ibmf_saa_handle_t ibmf_saa_handle, 530 ib_svc_id_t service_id, 531 ib_pkey_t p_key, 532 uint_t flags, 533 uint_t *num_records, 534 size_t *length, 535 sa_service_record_t **result); 536 537 /* 538 * ibmf_saa_update_service_record 539 * Given a pointer to a service record, either insert or delete it 540 * 541 * This interface blocks. 542 * 543 * Input Arguments: 544 * ibmf_saa_handle - handle returned from ibmf_sa_session_open() 545 * service_record - service record is to be inserted or deleted. To 546 * delete a service record the GID, ID, P_Key, and 547 * Service Key must match what is in the SA. 548 * access_type - indicates whether this is an insertion or deletion. 549 * valid values are IBMF_SAA_UPDATE or IBMF_SAA_DELETE 550 * flags - unused 551 * 552 * Ouptut Arguments 553 * none 554 * 555 * Return values: 556 * Error codes are the same as ibmf_sa_access() return values 557 */ 558 int ibmf_saa_update_service_record( 559 ibmf_saa_handle_t ibmf_saa_handle, 560 sa_service_record_t *service_record, 561 ibmf_saa_access_type_t access_type, 562 uint_t flags); 563 564 #ifdef __cplusplus 565 } 566 #endif 567 568 #endif /* _SYS_IB_MGT_IBMF_IBMF_SAA_H */ 569