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 57BEGIN_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*/ 68typedef 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*/ 103typedef 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*/ 134osm_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*/ 161void 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*/ 184ib_api_status_t 185osm_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*/ 221ib_api_status_t 222osm_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*/ 254osm_bind_handle_t 255osm_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*/ 300void 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*/ 324ib_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*/ 354ib_api_status_t 355osm_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*/ 389void 390osm_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*/ 419ib_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*/ 442void 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*/ 469void 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 486END_C_DECLS 487#endif /* _OSM_VENDOR_API_H_ */ 488