contrib/ofed/management/opensm/include/vendor/osm_vendor_sa_api.h

   1 /*
   2  * Copyright (c) 2004-2006 Voltaire, Inc. All rights reserved.
   3  * Copyright (c) 2002-2005 Mellanox Technologies LTD. All rights reserved.
   4  * Copyright (c) 1996-2003 Intel Corporation. All rights reserved.
   5  *
   6  * This software is available to you under a choice of one of two
   7  * licenses.  You may choose to be licensed under the terms of the GNU
   8  * General Public License (GPL) Version 2, available from the file
   9  * COPYING in the main directory of this source tree, or the
  10  * OpenIB.org BSD license below:
  11  *
  12  *     Redistribution and use in source and binary forms, with or
  13  *     without modification, are permitted provided that the following
  14  *     conditions are met:
  15  *
  16  *      - Redistributions of source code must retain the above
  17  *        copyright notice, this list of conditions and the following
  18  *        disclaimer.
  19  *
  20  *      - Redistributions in binary form must reproduce the above
  21  *        copyright notice, this list of conditions and the following
  22  *        disclaimer in the documentation and/or other materials
  23  *        provided with the distribution.
  24  *
  25  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
  26  * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
  27  * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
  28  * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
  29  * BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
  30  * ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
  31  * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
  32  * SOFTWARE.
  33  *
  34  */
  35
  36 /*
  37  * Abstract:
  38  *      Specification of the OpenSM SA Client API. This API uses the basic osm
  39  *    vendor API to provide SA Client interface.
  40  */
  41
  42 #ifndef _OSM_VENDOR_SA_API_H_
  43 #define _OSM_VENDOR_SA_API_H_
  44
  45 #include <iba/ib_types.h>
  46
  47 #ifdef __cplusplus
  48 #  define BEGIN_C_DECLS extern "C" {
  49 #  define END_C_DECLS   }
  50 #else                           /* !__cplusplus */
  51 #  define BEGIN_C_DECLS
  52 #  define END_C_DECLS
  53 #endif                          /* __cplusplus */
  54
  55 BEGIN_C_DECLS
  56 /****d* OpenSM Vendor SA Client/osmv_flags_t
  57 * NAME
  58 *       osmv_flags_t
  59 *
  60 * DESCRIPTION
  61 *       Access layer flags used to direct the operation of various calls.
  62 *
  63 * SYNOPSIS
  64 */
  65 typedef uint32_t osmv_flags_t;
  66 #define OSM_SA_FLAGS_SYNC                               0x00000001
  67 /*
  68 * VALUES
  69 *       OSM_SA_FLAGS_SYNC
  70 *               Indicates that the given operation should be performed synchronously.
  71 *               The call will block until it completes.  Callbacks will still be
  72 *               invoked.
  73 *
  74 * SEE ALSO
  75 *  osmv_query_sa
  76 *****/
  77
  78 /****d* OpenSM Vendor SA Client/osmv_query_type_t
  79 * NAME
  80 *       osmv_query_type_t
  81 *
  82 * DESCRIPTION
  83 *       Abstracted queries supported by the access layer.
  84 *
  85 * SYNOPSIS
  86 */
  87 typedef enum _osmv_query_type {
  88         OSMV_QUERY_USER_DEFINED,
  89
  90         OSMV_QUERY_ALL_SVC_RECS,
  91         OSMV_QUERY_SVC_REC_BY_NAME,
  92         OSMV_QUERY_SVC_REC_BY_ID,
  93
  94         OSMV_QUERY_CLASS_PORT_INFO,
  95
  96         OSMV_QUERY_NODE_REC_BY_NODE_GUID,
  97         OSMV_QUERY_PORT_REC_BY_LID,
  98         OSMV_QUERY_PORT_REC_BY_LID_AND_NUM,
  99
 100         OSMV_QUERY_VLARB_BY_LID_PORT_BLOCK,
 101         OSMV_QUERY_SLVL_BY_LID_AND_PORTS,
 102
 103         OSMV_QUERY_PATH_REC_BY_PORT_GUIDS,
 104         OSMV_QUERY_PATH_REC_BY_GIDS,
 105         OSMV_QUERY_PATH_REC_BY_LIDS,
 106
 107         OSMV_QUERY_UD_MULTICAST_SET,
 108         OSMV_QUERY_UD_MULTICAST_DELETE,
 109
 110         OSMV_QUERY_MULTIPATH_REC,
 111
 112 } osmv_query_type_t;
 113 /*
 114 * VALUES
 115 *       OSMV_QUERY_USER_DEFINED
 116 *               Query the SA based on user-defined input.  Queries of this type
 117 *               should reference an osmv_user_query_t structure as input to the
 118 *               query.
 119 *
 120 *       OSMV_QUERY_SVC_REC_BY_NAME
 121 *               Query for service records based on the service name.  Queries of
 122 *               this type should reference an ib_svc_name_t structure as input
 123 *               to the query.
 124 *
 125 *       OSMV_QUERY_SVC_REC_BY_ID
 126 *               Query for service records based on the service ID.  Queries of
 127 *               this type should reference an ib_net64_t value that indicates
 128 *               the ID of the service being requested.
 129 *
 130 *       OSMV_QUERY_NODE_REC_BY_NODE_GUID
 131 *               Query for node information based on the node's GUID.  Queries of
 132 *               this type should reference an ib_net64_t value that indicates
 133 *               the GUID of the node being requested.
 134 *
 135 *       OSMV_QUERY_PORT_REC_BY_LID
 136 *               Query for port information based on the port's base LID. Queries
 137 *               of this type should reference an ib_net16_t value that indicates
 138 *               the base LID of the port being requested.
 139 *
 140 *       OSMV_QUERY_PORT_REC_BY_LID_AND_NUM
 141 *               Query for port information based on the port's LID and port num.
 142 *               Queries of this type should reference an osmv_user_query_t
 143 *               structure as input to the query. The port num and lid should
 144 *               be provided by it.
 145 *
 146 *       OSMV_QUERY_PATH_REC_BY_PORT_GUIDS
 147 *               Query for path records between the specified pair of port GUIDs.
 148 *               Queries of this type should reference an osmv_guid_pair_t
 149 *               structure that indicates the GUIDs of the path being requested.
 150 *
 151 *       OSMV_QUERY_PATH_REC_BY_GIDS
 152 *               Query for path records between the specified pair of port GIDs.
 153 *               Queries of this type should reference an osmv_gid_pair_t
 154 *               structure that indicates the GIDs of the path being requested.
 155 *
 156 *       OSMV_QUERY_PATH_REC_BY_LIDS
 157 *               Query for path records between the specified pair of port LIDs.
 158 *               Queries of this type should reference an osmv_lid_pair_t
 159 *               structure that indicates the LIDs of the path being requested.
 160 *
 161 * NOTES
 162 *       This enum is used to define abstracted queries provided by the access
 163 *       layer.  Users may issue queries not listed here by sending MADs directly
 164 *       to subnet administration or a class manager.  These queries are
 165 *       intended to represent those most often used by clients.
 166 *
 167 * SEE ALSO
 168 *       osmv_query, osmv_query_req_t, osmv_user_query_t, osmv_gid_pair_t,
 169 *       osmv_lid_pair_t osmv_guid_pair_t
 170 *****/
 171
 172 /****s* OpenSM Vendor SA Client/osmv_user_query_t
 173 * NAME
 174 *       osmv_user_query_t
 175 *
 176 * DESCRIPTION
 177 *       User-defined query information.
 178 *
 179 * SYNOPSIS
 180 */
 181 typedef struct _osmv_user_query {
 182         uint8_t method;
 183         ib_net16_t attr_id;
 184         ib_net16_t attr_offset;
 185         ib_net32_t attr_mod;
 186         ib_net64_t comp_mask;
 187         void *p_attr;
 188 } osmv_user_query_t;
 189 /*
 190 * FIELDS
 191 *
 192 *       method
 193 *               Method to be used
 194 *
 195 *       attr_id
 196 *               Attribute identifier of query data.
 197 *
 198 *       attr_offset
 199 *               Size of the query attribute, in 8-byte words.  Users can set
 200 *               this value by passing in the sizeof( attribute ) into the
 201 *               ib_get_attr_offset() routine.
 202 *
 203 *       attr_mod
 204 *               Attribute modifier for query request.
 205 *
 206 *       comp_mask
 207 *               Indicates the attribute components that are specified for the
 208 *               query.
 209 *
 210 *       p_attr
 211 *               References the attribute structure used as input into the query.
 212 *               This field is ignored if comp_mask is set to 0.
 213 *
 214 * NOTES
 215 *       This structure is used to describe a user-defined query.  The attribute
 216 *       ID, attribute offset, component mask, and attribute structure must match
 217 *       those defined by the IBA specification.  Users should refer to chapter
 218 *       15 of the IBA specification for additional details.
 219 *
 220 * SEE ALSO
 221 *       osmv_query_type_t, ib_get_attr_offset, ib_get_attr_size, osmv_query_sa
 222 *****/
 223
 224 /****s* OpenSM Vendor SA Client/osmv_gid_pair_t
 225 * NAME
 226 *       osmv_gid_pair_t
 227 *
 228 * DESCRIPTION
 229 *       Source and destination GIDs.
 230 *
 231 * SYNOPSIS
 232 */
 233 typedef struct _osmv_gid_pair {
 234         ib_gid_t src_gid;
 235         ib_gid_t dest_gid;
 236 } osmv_gid_pair_t;
 237 /*
 238 * FIELDS
 239 *       src_gid
 240 *               Source GID of a path.
 241 *
 242 *       dest_gid
 243 *               Destination GID of a path.
 244 *
 245 * NOTES
 246 *       This structure is used to describe the endpoints of a path.
 247 *
 248 * SEE ALSO
 249 *       ib_gid_t
 250 *****/
 251
 252 /****s* OpenSM Vendor SA Client/osmv_lid_pair_t
 253 * NAME
 254 *       osmv_lid_pair_t
 255 *
 256 * DESCRIPTION
 257 *       Source and destination LIDs.
 258 *
 259 * SYNOPSIS
 260 */
 261 typedef struct _osmv_lid_pair {
 262         ib_net16_t src_lid;
 263         ib_net16_t dest_lid;
 264 } osmv_lid_pair_t;
 265 /*
 266 * FIELDS
 267 *       src_lid
 268 *               Source LID of a path.
 269 *
 270 *       dest_lid
 271 *               Destination LID of a path.
 272 *
 273 * NOTES
 274 *       This structure is used to describe the endpoints of a path.
 275 *****/
 276
 277 /****s* OpenSM Vendor SA Client/osmv_guid_pair_t
 278 * NAME
 279 *       osmv_guid_pair_t
 280 *
 281 * DESCRIPTION
 282 *       Source and destination GUIDs.  These may be port or channel adapter
 283 *       GUIDs, depending on the context in which this structure is used.
 284 *
 285 * SYNOPSIS
 286 */
 287 typedef struct _osmv_guid_pair {
 288         ib_net64_t src_guid;
 289         ib_net64_t dest_guid;
 290 } osmv_guid_pair_t;
 291 /*
 292 * FIELDS
 293 *       src_guid
 294 *               Source GUID of a path.
 295 *
 296 *       dest_guid
 297 *               Destination GUID of a path.
 298 *
 299 * NOTES
 300 *       This structure is used to describe the endpoints of a path.  The given
 301 *       GUID pair may belong to either ports or channel adapters.
 302 *
 303 * SEE ALSO
 304 *       ib_guid_t
 305 *****/
 306
 307 /****s* OpenSM Vendor SA Client/osmv_multipath_req_t
 308 * NAME
 309 *       osmv_multipath_req_t
 310 *
 311 * DESCRIPTION
 312 *       Fields from which to generate a MultiPathRecord request.
 313 *
 314 * SYNOPSIS
 315 */
 316 typedef struct _osmv_multipath_req_t {
 317         ib_net64_t comp_mask;
 318         uint16_t pkey;
 319         boolean_t reversible;
 320         uint8_t num_path;
 321         uint8_t sl;
 322         uint8_t independence;
 323         uint8_t sgid_count;
 324         uint8_t dgid_count;
 325         ib_gid_t gids[IB_MULTIPATH_MAX_GIDS];
 326 } osmv_multipath_req_t;
 327 /*
 328 * FIELDS
 329 *
 330 * NOTES
 331 *       This structure is used to describe a multipath request.
 332 *
 333 * SEE ALSO
 334 *****/
 335
 336 /****s* OpenSM Vendor SA Client/osmv_query_res_t
 337 * NAME
 338 *       osmv_query_res_t
 339 *
 340 * DESCRIPTION
 341 *       Contains the results of a subnet administration query.
 342 *
 343 * SYNOPSIS
 344 */
 345 typedef struct _osmv_query_res {
 346         const void *query_context;
 347         ib_api_status_t status;
 348         osmv_query_type_t query_type;
 349         uint32_t result_cnt;
 350         osm_madw_t *p_result_madw;
 351 } osmv_query_res_t;
 352 /*
 353 * FIELDS
 354 *       query_context
 355 *               User-defined context information associated with the query
 356 *               through the osm_vendor_query_sa call.
 357 *
 358 *       status
 359 *               Indicates the success of the query operation.
 360 *
 361 *       query_type
 362 *               Indicates the type of query for which the results are being
 363 *               returned.  This matches the query_type specified through the
 364 *               osm_vendor_query_sa call.
 365 *
 366 *       result_cnt
 367 *               The number of result structures that were returned by the query.
 368 *
 369 *       p_result_madw
 370 *               For queries returning IB_SUCCESS or IB_REMOTE_ERROR, this
 371 *               references the MAD wrapper returned by subnet administration
 372 *               containing the list of results or the returned error code.
 373 *
 374 * NOTES
 375 *       A query result structure is returned to a client through their
 376 *       osmv_pfn_query_cb_t routine to notify them of the results of a subnet
 377 *       administration query.  If the query was successful or received an error
 378 *       from subnet administration, p_result_madw will reference a MAD wrapper
 379 *       containing the results.  The MAD referenced by p_result_madw is owned by
 380 *       the user and remains available even after their callback returns.  Users
 381 *       must call osm_mad_pool_put() to return the MAD wrapper back to the
 382 *       mad pool when they are done accessing the results.
 383 *
 384 *       To retrieve individual result structures from the p_result_madw, users
 385 *       may call osmv_get_query_result().
 386 *
 387 * SEE ALSO
 388 *       osmv_query_sa, osmv_pfn_query_cb_t, ib_api_status_t,
 389 *       osmv_query_status_t, osmv_query_type_t,
 390 *       osmv_get_query_result
 391 *****/
 392
 393 /****f* OpenSM Vendor SA Client/osmv_get_query_result
 394 * NAME
 395 *       osmv_get_query_result
 396 *
 397 * DESCRIPTION
 398 *       Retrieves a result structure from a MADW returned by a call to
 399 *       osmv_query_sa().
 400 *
 401 * SYNOPSIS
 402 */
 403 static inline void *osmv_get_query_result(IN osm_madw_t * p_result_madw,
 404                                           IN uint32_t result_index)
 405 {
 406         ib_sa_mad_t *p_sa_mad;
 407
 408         CL_ASSERT(p_result_madw);
 409         p_sa_mad = (ib_sa_mad_t *) osm_madw_get_mad_ptr(p_result_madw);
 410         CL_ASSERT(p_sa_mad);
 411         CL_ASSERT(ib_get_attr_size(p_sa_mad->attr_offset) * (result_index + 1) +
 412                   IB_SA_MAD_HDR_SIZE <= p_result_madw->mad_size);
 413
 414         return (p_sa_mad->data +
 415                 (ib_get_attr_size(p_sa_mad->attr_offset) * result_index));
 416 }
 417
 418 /*
 419 * PARAMETERS
 420 *       p_result_madw
 421 *               [in] This is a reference to the MAD returned as a result of the
 422 *               query.
 423 *
 424 *       result_index
 425 *               [in] A zero-based index indicating which result to return.
 426 *
 427 * NOTES
 428 *       This call returns a pointer to the start of a result structure from a
 429 *       call to osmv_query_sa().  The type of result structure must be known to
 430 *       the user either through the user's context or the query_type returned as
 431 *       part of the osmv_query_res_t structure.
 432 *
 433 * SEE ALSO
 434 *       osmv_query_res_t, osm_madw_t
 435 *****/
 436
 437 /****f* OpenSM Vendor SA Client/osmv_get_query_path_rec
 438 * NAME
 439 *       osmv_get_query_path_rec
 440 *
 441 * DESCRIPTION
 442 *       Retrieves a path record result from a MAD returned by a call to
 443 *       osmv_query_sa().
 444 *
 445 * SYNOPSIS
 446 */
 447 static inline ib_path_rec_t *osmv_get_query_path_rec(IN osm_madw_t *
 448                                                      p_result_madw,
 449                                                      IN uint32_t result_index)
 450 {
 451         ib_sa_mad_t *p_sa_mad;
 452
 453         CL_ASSERT(p_result_madw);
 454         p_sa_mad = (ib_sa_mad_t *) osm_madw_get_mad_ptr(p_result_madw);
 455         CL_ASSERT(p_sa_mad && p_sa_mad->attr_id == IB_MAD_ATTR_PATH_RECORD);
 456
 457         return ((ib_path_rec_t *)
 458                 osmv_get_query_result(p_result_madw, result_index));
 459 }
 460
 461 /*
 462 * PARAMETERS
 463 *       p_result_madw
 464 *               [in] This is a reference to the MAD returned as a result of the
 465 *               query.
 466 *
 467 *       result_index
 468 *               [in] A zero-based index indicating which result to return.
 469 *
 470 * NOTES
 471 *       This call returns a pointer to the start of a path record result from
 472 *       a call to osmv_query_sa().
 473 *
 474 * SEE ALSO
 475 *       osmv_query_res_t, osm_madw_t, osmv_get_query_result, ib_path_rec_t
 476 *****/
 477
 478 /****f* OpenSM Vendor SA Client/osmv_get_query_portinfo_rec
 479 * NAME
 480 *       osmv_get_query_portinfo_rec
 481 *
 482 * DESCRIPTION
 483 *       Retrieves a port info record result from a MAD returned by a call to
 484 *       osmv_query_sa().
 485 *
 486 * SYNOPSIS
 487 */
 488 static inline ib_portinfo_record_t *osmv_get_query_portinfo_rec(IN osm_madw_t *
 489                                                                 p_result_madw,
 490                                                                 IN uint32_t
 491                                                                 result_index)
 492 {
 493         ib_sa_mad_t *p_sa_mad;
 494
 495         CL_ASSERT(p_result_madw);
 496         p_sa_mad = (ib_sa_mad_t *) osm_madw_get_mad_ptr(p_result_madw);
 497         CL_ASSERT(p_sa_mad && p_sa_mad->attr_id == IB_MAD_ATTR_PORTINFO_RECORD);
 498
 499         return ((ib_portinfo_record_t *) osmv_get_query_result(p_result_madw,
 500                                                                result_index));
 501 }
 502
 503 /*
 504 * PARAMETERS
 505 *       p_result_madw
 506 *               [in] This is a reference to the MAD returned as a result of the
 507 *               query.
 508 *
 509 *       result_index
 510 *               [in] A zero-based index indicating which result to return.
 511 *
 512 * NOTES
 513 *       This call returns a pointer to the start of a port info record result
 514 *       from a call to osmv_query_sa().
 515 *
 516 * SEE ALSO
 517 *       osmv_query_res_t, osm_madw_t, osmv_get_query_result, ib_portinfo_record_t
 518 *****/
 519
 520 /****f* OpenSM Vendor SA Client/osmv_get_query_node_rec
 521 * NAME
 522 *       osmv_get_query_node_rec
 523 *
 524 * DESCRIPTION
 525 *       Retrieves a node record result from a MAD returned by a call to
 526 *       osmv_query_sa().
 527 *
 528 * SYNOPSIS
 529 */
 530 static inline ib_node_record_t *osmv_get_query_node_rec(IN osm_madw_t *
 531                                                         p_result_madw,
 532                                                         IN uint32_t
 533                                                         result_index)
 534 {
 535         ib_sa_mad_t *p_sa_mad;
 536
 537         CL_ASSERT(p_result_madw);
 538         p_sa_mad = (ib_sa_mad_t *) osm_madw_get_mad_ptr(p_result_madw);
 539         CL_ASSERT(p_sa_mad && p_sa_mad->attr_id == IB_MAD_ATTR_NODE_RECORD);
 540
 541         return ((ib_node_record_t *) osmv_get_query_result(p_result_madw,
 542                                                            result_index));
 543 }
 544
 545 /*
 546 * PARAMETERS
 547 *       p_result_madw
 548 *               [in] This is a reference to the MAD returned as a result of the
 549 *               query.
 550 *
 551 *       result_index
 552 *               [in] A zero-based index indicating which result to return.
 553 *
 554 * NOTES
 555 *       This call returns a pointer to the start of a node record result from
 556 *       a call to osmv_query_sa().
 557 *
 558 * SEE ALSO
 559 *       osmv_query_res_t, osm_madw_t, osmv_get_query_result, ib_node_record_t
 560 *****/
 561
 562 /****f* OpenSM Vendor SA Client/osmv_get_query_svc_rec
 563 * NAME
 564 *       osmv_get_query_svc_rec
 565 *
 566 * DESCRIPTION
 567 *       Retrieves a service record result from a MAD returned by a call to
 568 *       osmv_query_sa().
 569 *
 570 * SYNOPSIS
 571 */
 572 static inline ib_service_record_t *osmv_get_query_svc_rec(IN osm_madw_t *
 573                                                           p_result_madw,
 574                                                           IN uint32_t
 575                                                           result_index)
 576 {
 577         ib_sa_mad_t *p_sa_mad;
 578
 579         CL_ASSERT(p_result_madw);
 580         p_sa_mad = (ib_sa_mad_t *) osm_madw_get_mad_ptr(p_result_madw);
 581         CL_ASSERT(p_sa_mad && p_sa_mad->attr_id == IB_MAD_ATTR_SERVICE_RECORD);
 582
 583         return ((ib_service_record_t *) osmv_get_query_result(p_result_madw,
 584                                                               result_index));
 585 }
 586
 587 /*
 588 * PARAMETERS
 589 *       p_result_madw
 590 *               [in] This is a reference to the MAD returned as a result of the
 591 *               query.
 592 *
 593 *       result_index
 594 *               [in] A zero-based index indicating which result to return.
 595 *
 596 * NOTES
 597 *       This call returns a pointer to the start of a service record result from
 598 *       a call to osmv_query_sa().
 599 *
 600 * SEE ALSO
 601 *       osmv_query_res_t, osm_madw_t, osmv_get_query_result, ib_service_record_t
 602 *****/
 603
 604 /****f* OpenSM Vendor SA Client/osmv_get_query_mc_rec
 605 * NAME
 606 *       osmv_get_query_mc_rec
 607 *
 608 * DESCRIPTION
 609 *       Retrieves a multicast record result from a MAD returned by a call to
 610 *       osmv_query_sa().
 611 *
 612 * SYNOPSIS
 613 */
 614 static inline ib_member_rec_t *osmv_get_query_mc_rec(IN osm_madw_t *
 615                                                      p_result_madw,
 616                                                      IN uint32_t result_index)
 617 {
 618         ib_sa_mad_t *p_sa_mad;
 619
 620         CL_ASSERT(p_result_madw);
 621         p_sa_mad = (ib_sa_mad_t *) osm_madw_get_mad_ptr(p_result_madw);
 622         CL_ASSERT(p_sa_mad && p_sa_mad->attr_id == IB_MAD_ATTR_MCMEMBER_RECORD);
 623
 624         return ((ib_member_rec_t *) osmv_get_query_result(p_result_madw,
 625                                                           result_index));
 626 }
 627
 628 /*
 629 * PARAMETERS
 630 *       p_result_madw
 631 *               [in] This is a reference to the MAD returned as a result of the
 632 *               query.
 633 *
 634 *       result_index
 635 *               [in] A zero-based index indicating which result to return.
 636 *
 637 * NOTES
 638 *       This call returns a pointer to the start of a service record result from
 639 *       a call to osmv_query_sa().
 640 *
 641 * SEE ALSO
 642 *       osmv_query_res_t, osm_madw_t, osmv_get_query_result, ib_member_rec_t
 643 *****/
 644
 645 /****f* OpenSM Vendor SA Client/osmv_get_query_inform_info_rec
 646 * NAME
 647 *       osmv_get_query_inform_info_rec
 648 *
 649 * DESCRIPTION
 650 *       Retrieves an InformInfo record result from a MAD returned by
 651 *       a call to osmv_query_sa().
 652 *
 653 * SYNOPSIS
 654 */
 655 static inline ib_inform_info_record_t *osmv_get_query_inform_info_rec(IN
 656                                                                       osm_madw_t
 657                                                                       *
 658                                                                       p_result_madw,
 659                                                                       IN
 660                                                                       uint32_t
 661                                                                       result_index)
 662 {
 663         ib_sa_mad_t *p_sa_mad;
 664
 665         CL_ASSERT(p_result_madw);
 666         p_sa_mad = (ib_sa_mad_t *) osm_madw_get_mad_ptr(p_result_madw);
 667         CL_ASSERT(p_sa_mad
 668                   && p_sa_mad->attr_id == IB_MAD_ATTR_INFORM_INFO_RECORD);
 669
 670         return ((ib_inform_info_record_t *) osmv_get_query_result(p_result_madw,
 671                                                                   result_index));
 672 }
 673
 674 /*
 675 * PARAMETERS
 676 *       p_result_madw
 677 *               [in] This is a reference to the MAD returned as a result of the
 678 *               query.
 679 *
 680 *       result_index
 681 *               [in] A zero-based index indicating which result to return.
 682 *
 683 * NOTES
 684 *       This call returns a pointer to the start of a service record result from
 685 *       a call to osmv_query_sa().
 686 *
 687 * SEE ALSO
 688 *       osmv_query_res_t, osm_madw_t, osmv_get_query_result, ib_inform_info_record_t
 689 *****/
 690
 691 /****f* OpenSM Vendor SA Client/osmv_pfn_query_cb_t
 692 * NAME
 693 *       osmv_pfn_query_cb_t
 694 *
 695 * DESCRIPTION
 696 *       User-defined callback invoked on completion of subnet administration
 697 *       query.
 698 *
 699 * SYNOPSIS
 700 */
 701 typedef void
 702  (*osmv_pfn_query_cb_t) (IN osmv_query_res_t * p_query_res);
 703 /*
 704 * PARAMETERS
 705 *       p_query_res
 706 *               [in] This is a reference to a structure containing the result of
 707 *               the query.
 708 *
 709 * NOTES
 710 *       This routine is invoked to notify a client of the result of a subnet
 711 *       administration query.  The p_query_rec parameter references the result
 712 *       of the query and, in the case of a successful query, any information
 713 *       returned by subnet administration.
 714 *
 715 *       In the kernel, this callback is usually invoked using a tasklet,
 716 *       dependent on the implementation of the underlying verbs provider driver.
 717 *
 718 * SEE ALSO
 719 *       osmv_query_res_t
 720 *****/
 721
 722 /****s* OpenSM Vendor SA Client/osmv_query_req_t
 723 * NAME
 724 *       osmv_query_req_t
 725 *
 726 * DESCRIPTION
 727 *       Information used to request an access layer provided query of subnet
 728 *       administration.
 729 *
 730 * SYNOPSIS
 731 */
 732 typedef struct _osmv_query_req {
 733         osmv_query_type_t query_type;
 734         const void *p_query_input;
 735         ib_net64_t sm_key;
 736
 737         uint32_t timeout_ms;
 738         uint32_t retry_cnt;
 739         osmv_flags_t flags;
 740
 741         const void *query_context;
 742         osmv_pfn_query_cb_t pfn_query_cb;
 743 } osmv_query_req_t;
 744 /*
 745 * FIELDS
 746 *       query_type
 747 *               Indicates the type of query that the access layer should
 748 *               perform.
 749 *
 750 *       p_query_input
 751 *               A pointer to the input for the query.  The data referenced by
 752 *               this structure is dependent on the type of query being requested
 753 *               and is determined by the specified query_type.
 754 *
 755 *       sm_key
 756 *               The M_Key to be provided with the SA MAD for authentication.
 757 *               Normally 0 is used.
 758 *
 759 *       timeout_ms
 760 *               Specifies the number of milliseconds to wait for a response for
 761 *               this query until retrying or timing out the request.
 762 *
 763 *       retry_cnt
 764 *               Specifies the number of times that the query will be retried
 765 *               before failing the request.
 766 *
 767 *       flags
 768 *               Used to describe the mode of operation.  Set to IB_FLAGS_SYNC to
 769 *               process the called routine synchronously.
 770 *
 771 *       query_context
 772 *               User-defined context information associated with this query.
 773 *               The context data is returned to the user as a part of their
 774 *               query callback.
 775 *
 776 *       pfn_query_cb
 777 *               A user-defined callback that is invoked upon completion of the
 778 *               query.
 779 *
 780 * NOTES
 781 *       This structure is used when requesting an osm vendor provided query
 782 *       of subnet administration.  Clients specify the type of query through
 783 *       the query_type field.  Based on the type of query, the p_query_input
 784 *       field is set to reference the appropriate data structure.
 785 *
 786 *       The information referenced by the p_query_input field is one of the
 787 *       following:
 788 *
 789 *               -- a NULL terminated service name
 790 *               -- a service id
 791 *               -- a single GUID
 792 *               -- a pair of GUIDs specified through an osmv_guid_pair_t structure
 793 *               -- a pair of GIDs specified through an osmv_gid_pair_t structure
 794 *
 795 * SEE ALSO
 796 *       osmv_query_type_t, osmv_pfn_query_cb_t, osmv_guid_pair_t,
 797 *       osmv_gid_pair_t
 798 *****/
 799
 800 /****f* OpenSM Vendor SA Client/osmv_bind_sa
 801 * NAME
 802 *   osmv_bind_sa
 803 *
 804 * DESCRIPTION
 805 *       Bind to the SA service and return a handle to be used for later
 806 *  queries.
 807 *
 808 *
 809 * SYNOPSIS
 810 */
 811 osm_bind_handle_t
 812 osmv_bind_sa(IN osm_vendor_t * const p_vend,
 813              IN osm_mad_pool_t * const p_mad_pool, IN ib_net64_t port_guid);
 814 /*
 815 * PARAMETERS
 816 *   p_vend
 817 *       [in] an osm_vendor object to work with
 818 *
 819 *   p_mad_pool
 820 *       [in] mad pool to obtain madw from
 821 *
 822 *   port_guid
 823 *       [in] the port guid to attach to.
 824 *
 825 * RETURN VALUE
 826 *       Bind handle to be used for later SA queries or OSM_BIND_INVALID_HANDLE
 827 *
 828 * NOTES
 829 *
 830 * SEE ALSO
 831 * osmv_query_sa
 832 *********/
 833
 834 /****f* OpenSM Vendor SA Client/osmv_query_sa
 835 * NAME
 836 *   osmv_query_sa
 837 *
 838 * DESCRIPTION
 839 *   Query the SA given an SA query request (similar to IBAL ib_query).
 840 *
 841 * SYNOPSIS
 842 */
 843 ib_api_status_t
 844 osmv_query_sa(IN osm_bind_handle_t h_bind,
 845               IN const osmv_query_req_t * const p_query_req);
 846 /*
 847 * PARAMETERS
 848 *   h_bind
 849 *       [in] bind handle for this port. Should be previously
 850 *       obtained by calling osmv_bind_sa
 851 *
 852 *   p_query_req
 853 *       [in] an SA query request structure.
 854 *
 855 * RETURN VALUE
 856 *       IB_SUCCESS if completed successfuly (or in ASYNC mode
 857 *       if the request was sent).
 858 *
 859 * NOTES
 860 *
 861 * SEE ALSO
 862 * osmv_bind_sa
 863 *********/
 864
 865 END_C_DECLS
 866 #endif                          /* _OSM_VENDOR_SA_API_H_ */