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_all_port_attr 176 * NAME 177 * osm_vendor_get_all_port_attr 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, IN osm_log_t * const p_log, 223 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 immediately 374 * after 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_ */ 488