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

   1 /*
   2  * Copyright (c) 2004, 2005 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 transport API. This API is OpenSM's view
  39  *  of the Infiniband transport.
  40  */
  41
  42 #ifndef _OSM_VENDOR_API_H_
  43 #define _OSM_VENDOR_API_H_
  44
  45 #include <opensm/osm_madw.h>
  46 #include <opensm/osm_mad_pool.h>
  47 #include <vendor/osm_vendor.h>
  48
  49 #ifdef __cplusplus
  50 #  define BEGIN_C_DECLS extern "C" {
  51 #  define END_C_DECLS   }
  52 #else                           /* !__cplusplus */
  53 #  define BEGIN_C_DECLS
  54 #  define END_C_DECLS
  55 #endif                          /* __cplusplus */
  56
  57 BEGIN_C_DECLS
  58 /****s* OpenSM Vendor API/osm_vend_mad_recv_callback_t
  59 * NAME
  60 *  osm_vend_mad_recv_callback_t
  61 *
  62 * DESCRIPTION
  63 *  Function prototype for the vendor MAD receive callback.
  64 *  The vendor layer calls this function for MAD receives.
  65 *
  66 * SYNOPSIS
  67 */
  68 typedef void (*osm_vend_mad_recv_callback_t) (IN osm_madw_t * p_madw,
  69                                               IN void *bind_context,
  70                                               IN osm_madw_t * p_req_madw);
  71 /*
  72 * PARAMETERS
  73 *  p_madw
  74 *     [in] The received MAD wrapper.
  75 *
  76 *  bind_context
  77 *     [in] User context supplied during the bind call.
  78 *
  79 *  p_req_madw
  80 *     [in] Pointer to the request mad wrapper that generated this response.
  81 *     If the inbound MAD is not a response, this field is NULL.
  82 *
  83 * RETURN VALUES
  84 *  None.
  85 *
  86 * NOTES
  87 *
  88 * SEE ALSO
  89 *********/
  90
  91 /****s* OpenSM Vendor API/osm_vend_mad_send_err_callback_t
  92 * NAME
  93 *  osm_vend_mad_send_err_callback_t
  94 *
  95 * DESCRIPTION
  96 *  Function prototype for the vendor send failure callback.
  97 *  The vendor layer calls this function when MADs expecting
  98 *  a response are completed in error, most likely due to a
  99 *  timeout.
 100 *
 101 * SYNOPSIS
 102 */
 103 typedef void (*osm_vend_mad_send_err_callback_t) (IN void *bind_context,
 104                                                   IN osm_madw_t * p_madw);
 105 /*
 106 * PARAMETERS
 107 *  bind_context
 108 *     [in] User context supplied during the bind call.
 109 *
 110 *  p_madw
 111 *     [in] Pointer to the request mad that failed.
 112 *
 113 * RETURN VALUES
 114 *  None.
 115 *
 116 * NOTES
 117 *  The vendor layer does not call this function (or any other)
 118 *  for MADs that were not expecting a response.
 119 *
 120 * SEE ALSO
 121 *********/
 122
 123 /****f* OpenSM Vendor API/osm_vendor_new
 124 * NAME
 125 *  osm_vendor_new
 126 *
 127 * DESCRIPTION
 128 *  Allocates and initializes a new osm_vendor_t object.
 129 *  OpenSM calls this function before any other in the vendor API.
 130 *  This object is passed as a parameter to all other vendor functions.
 131 *
 132 * SYNOPSIS
 133 */
 134 osm_vendor_t *osm_vendor_new(IN osm_log_t * const p_log,
 135                              IN const uint32_t timeout);
 136 /*
 137 * PARAMETERS
 138 *  p_log
 139 *     [in] Pointer to the log object to use.
 140 *
 141 *  timeout
 142 *     [in] transaction timeout
 143 *
 144 * RETURN VALUES
 145 *  Returns a pointer to the vendor object.
 146 *
 147 * NOTES
 148 *
 149 * SEE ALSO
 150 *********/
 151
 152 /****s* OpenSM Vendor API/osm_vendor_delete
 153 * NAME
 154 *  osm_vendor_delete
 155 *
 156 * DESCRIPTION
 157 *  Dealocate the vendor object.
 158 *
 159 * SYNOPSIS
 160 */
 161 void osm_vendor_delete(IN osm_vendor_t ** const pp_vend);
 162 /*
 163 * PARAMETERS
 164 *  pp_vend
 165 *     [in/out] pointer to pointer to vendor objcet to be deleted
 166 *
 167 * RETURN VALUES
 168 *  None
 169 *
 170 * NOTES
 171 *
 172 * SEE ALSO
 173 *********/
 174
 175 /****f* OpenSM Vendor API/osm_vendor_get_ports
 176 * NAME
 177 *  osm_vendor_get_ports
 178 *
 179 * DESCRIPTION
 180 *  Returns an array of available port attribute structures.
 181 *
 182 * SYNOPSIS
 183 */
 184 ib_api_status_t
 185 osm_vendor_get_all_port_attr(IN osm_vendor_t * const p_vend,
 186                              IN ib_port_attr_t * const p_attr_array,
 187                              IN uint32_t * const p_num_ports);
 188 /*
 189 * PARAMETERS
 190 *  p_vend
 191 *     [in] Pointer to the vendor object to initialize.
 192 *
 193 *  p_attr_array
 194 *     [in/out] Pointer to pre-allocated array of port attributes.
 195 *     If it is NULL - then the command only updates the p_num_ports,
 196 *     and return IB_INSUFFICIENT_MEMORY.
 197 *
 198 *  p_num_ports
 199 *     [in/out] Pointer to a variable to hold the total number of ports
 200 *     available on the local machine..
 201 *
 202 * RETURN VALUES
 203 *  IB_SUCCESS on success.
 204 *  IB_INSUFFICIENT_MEMORY if the attribute array was not large enough.
 205 *  The number of attributes needed is returned in num_guids.
 206 *
 207 * NOTES
 208 *
 209 * SEE ALSO
 210 *********/
 211
 212 /****f* OpenSM Vendor API/osm_vendor_init
 213 * NAME
 214 *  osm_vendor_init
 215 *
 216 * DESCRIPTION
 217 *  The osm_vendor_init function initializes the vendor transport layer.
 218 *
 219 * SYNOPSIS
 220 */
 221 ib_api_status_t
 222 osm_vendor_init(IN osm_vendor_t * const p_vend,
 223                 IN osm_log_t * const p_log, IN const uint32_t timeout);
 224 /*
 225 * PARAMETERS
 226 *  p_vend
 227 *     [in] Pointer to the vendor object to initialize.
 228 *
 229 *  p_log
 230 *     [in] Pointer to OpenSM's log object.  Vendor code may
 231 *     use the log object to send messages to OpenSM's log.
 232 *
 233 *  timeout
 234 *     [in] Transaction timeout value in milliseconds.
 235 *     A value of 0 disables timeouts.
 236 *
 237 * RETURN VALUE
 238 *
 239 * NOTES
 240 *
 241 * SEE ALSO
 242 *********/
 243
 244 /****f* OpenSM Vendor API/osm_vendor_bind
 245 * NAME
 246 *   osm_vendor_bind
 247 *
 248 * DESCRIPTION
 249 *   The osm_vendor_bind function registers with the vendor transport layer
 250 *   per Mad Class per PortGuid for mad transport capability.
 251 *
 252 * SYNOPSIS
 253 */
 254 osm_bind_handle_t
 255 osm_vendor_bind(IN osm_vendor_t * const p_vend,
 256                 IN osm_bind_info_t * const p_bind_info,
 257                 IN osm_mad_pool_t * const p_mad_pool,
 258                 IN osm_vend_mad_recv_callback_t mad_recv_callback,
 259                 IN osm_vend_mad_send_err_callback_t send_err_callback,
 260                 IN void *context);
 261 /*
 262 * PARAMETERS
 263 *  p_vend
 264 *    [in] pointer to the vendor object
 265 *
 266 *  p_osm_bind_info
 267 *    [in] pointer to a struct defining the type of bind to perform.
 268 *
 269 *  p_mad_pool
 270 *    [in] pointer to a mad wrappers pool to be used for allocating
 271 *    mad wrappers on send and receive.
 272 *
 273 *  mad_recv_callback
 274 *    [in] the callback function to be invoked on mad receive.
 275 *
 276 *  send_err_callback
 277 *    [in] the callback function to be invoked on mad transaction errors.
 278 *
 279 *  context
 280 *    [in] the context to be provided to the callbacks as bind_ctx.
 281 *
 282 * RETURN VALUE
 283 *  On success, a valid bind handle.
 284 *  OSM_BIND_INVALID_HANDLE otherwise.
 285 *
 286 * NOTES
 287 *
 288 * SEE ALSO
 289 *********/
 290
 291 /****f* OpenSM Vendor API/osm_vendor_unbind
 292 * NAME
 293 *   osm_vendor_unbind
 294 *
 295 * DESCRIPTION
 296 *   Unbind the given bind handle (obtained by osm_vendor_bind).
 297 *
 298 * SYNOPSIS
 299 */
 300 void osm_vendor_unbind(IN osm_bind_handle_t h_bind);
 301 /*
 302 * PARAMETERS
 303 *  h_bind
 304 *    [in] the bind handle to release.
 305 *
 306 * RETURN VALUE
 307 *    NONE.
 308 *
 309 * NOTES
 310 *
 311 * SEE ALSO
 312 *********/
 313
 314 /****f* OpenSM Vendor API/osm_vendor_get
 315 * NAME
 316 *   osm_vendor_get
 317 *
 318 * DESCRIPTION
 319 *   Obtain a mad wrapper holding actual mad buffer to be sent via
 320 *   the transport.
 321 *
 322 * SYNOPSIS
 323 */
 324 ib_mad_t *osm_vendor_get(IN osm_bind_handle_t h_bind,
 325                          IN const uint32_t mad_size,
 326                          IN osm_vend_wrap_t * const p_vend_wrap);
 327 /*
 328 * PARAMETERS
 329 *   h_bind
 330 *      [in] the bind handle obtained by calling osm_vendor_bind
 331 *
 332 *   mad_size
 333 *      [in] the actual mad size required
 334 *
 335 *   p_vend_wrap
 336 *      [out] the returned mad vendor wrapper
 337 *
 338 * RETURN VALUE
 339 *   IB_SUCCESS on succesful completion.
 340 *
 341 * NOTES
 342 *
 343 * SEE ALSO
 344 *********/
 345
 346 /****f* OpenSM Vendor API/osm_vendor_send
 347 * NAME
 348 *   osm_vendor_send
 349 *
 350 * DESCRIPTION
 351 *
 352 * SYNOPSIS
 353 */
 354 ib_api_status_t
 355 osm_vendor_send(IN osm_bind_handle_t h_bind,
 356                 IN osm_madw_t * const p_madw, IN boolean_t const resp_expected);
 357 /*
 358 * PARAMETERS
 359 *   h_bind
 360 *      [in] the bind handle obtained by calling osm_vendor_bind
 361 *
 362 *   p_madw
 363 *      [in] pointer to the Mad Wrapper structure for the MAD to be sent.
 364 *
 365 *   resp_expected
 366 *      [in] boolean value declaring the mad as a request (expecting a response).
 367 *
 368 * RETURN VALUE
 369 *   IB_SUCCESS on succesful completion.
 370 *
 371 * NOTES
 372 *   1. Only mads that expect a response are tracked for transaction competion.
 373 *   2. A mad that does not expect a response is being put back immediatly after
 374 *      being sent.
 375 *
 376 * SEE ALSO
 377 *********/
 378
 379 /****f* OpenSM Vendor API/osm_vendor_put
 380 * NAME
 381 *   osm_vendor_put
 382 *
 383 * DESCRIPTION
 384 *   Return a mad vendor wrapper to the mad pool. It also means that the
 385 *   mad buffer is returned to the transport.
 386 *
 387 * SYNOPSIS
 388 */
 389 void
 390 osm_vendor_put(IN osm_bind_handle_t h_bind,
 391                IN osm_vend_wrap_t * const p_vend_wrap);
 392 /*
 393 * PARAMETERS
 394 *   h_bind
 395 *      [in] the bind handle obtained by calling osm_vendor_bind
 396 *
 397 *   p_vend_wrap
 398 *      [in] pointer to the mad vendor wrapper to put back into the pool.
 399 *
 400 * RETURN VALUE
 401 *   None.
 402 *
 403 * NOTES
 404 *
 405 * SEE ALSO
 406 *********/
 407
 408 /****i* OpenSM Vendor API/osm_vendor_local_lid_change
 409 * NAME
 410 *   osm_vendor_local_lid_change
 411 *
 412 * DESCRIPTION
 413 *  Notifies the vendor transport layer that the local address
 414 *  has changed.  This allows the vendor layer to perform housekeeping
 415 *  functions such as address vector updates.
 416 *
 417 * SYNOPSIS
 418 */
 419 ib_api_status_t osm_vendor_local_lid_change(IN osm_bind_handle_t h_bind);
 420 /*
 421 * PARAMETERS
 422 *   h_bind
 423 *      [in] the bind handle obtained by calling osm_vendor_bind
 424 *
 425 * RETURN VALUE
 426 *
 427 * NOTES
 428 *
 429 * SEE ALSO
 430 *********/
 431
 432 /****f* OpenSM Vendor API/osm_vendor_set_sm
 433 * NAME
 434 *   osm_vendor_set_sm
 435 *
 436 * DESCRIPTION
 437 *  Modifies the port info for the bound port to set the "IS_SM" bit
 438 *  according to the value given (TRUE or FALSE).
 439 *
 440 * SYNOPSIS
 441 */
 442 void osm_vendor_set_sm(IN osm_bind_handle_t h_bind, IN boolean_t is_sm_val);
 443 /*
 444 * PARAMETERS
 445 *   h_bind
 446 *     [in] bind handle for this port.
 447 *
 448 *   is_sm_val
 449 *     [in] If TRUE - will set the is_sm to TRUE, if FALSE - will set the
 450 *          the is_sm to FALSE.
 451 *
 452 * RETURN VALUE
 453 *  None.
 454 *
 455 * NOTES
 456 *
 457 * SEE ALSO
 458 *********/
 459
 460 /****f* OpenSM Vendor API/osm_vendor_set_debug
 461 * NAME
 462 *   osm_vendor_set_debug
 463 *
 464 * DESCRIPTION
 465 *  Modifies the vendor specific debug level.
 466 *
 467 * SYNOPSIS
 468 */
 469 void osm_vendor_set_debug(IN osm_vendor_t * const p_vend, IN int32_t level);
 470 /*
 471 * PARAMETERS
 472 *   p_vend
 473 *     [in] vendor handle.
 474 *
 475 *   level
 476 *     [in] vendor specific debug level.
 477 *
 478 * RETURN VALUE
 479 *  None.
 480 *
 481 * NOTES
 482 *
 483 * SEE ALSO
 484 *********/
 485
 486 END_C_DECLS
 487 #endif                          /* _OSM_VENDOR_API_H_ */