1219820Sjeff/* 2219820Sjeff * Copyright (c) 2004, 2005 Voltaire, Inc. All rights reserved. 3219820Sjeff * Copyright (c) 2002-2005 Mellanox Technologies LTD. All rights reserved. 4219820Sjeff * Copyright (c) 1996-2003 Intel Corporation. All rights reserved. 5219820Sjeff * 6219820Sjeff * This software is available to you under a choice of one of two 7219820Sjeff * licenses. You may choose to be licensed under the terms of the GNU 8219820Sjeff * General Public License (GPL) Version 2, available from the file 9219820Sjeff * COPYING in the main directory of this source tree, or the 10219820Sjeff * OpenIB.org BSD license below: 11219820Sjeff * 12219820Sjeff * Redistribution and use in source and binary forms, with or 13219820Sjeff * without modification, are permitted provided that the following 14219820Sjeff * conditions are met: 15219820Sjeff * 16219820Sjeff * - Redistributions of source code must retain the above 17219820Sjeff * copyright notice, this list of conditions and the following 18219820Sjeff * disclaimer. 19219820Sjeff * 20219820Sjeff * - Redistributions in binary form must reproduce the above 21219820Sjeff * copyright notice, this list of conditions and the following 22219820Sjeff * disclaimer in the documentation and/or other materials 23219820Sjeff * provided with the distribution. 24219820Sjeff * 25219820Sjeff * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, 26219820Sjeff * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF 27219820Sjeff * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND 28219820Sjeff * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS 29219820Sjeff * BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN 30219820Sjeff * ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN 31219820Sjeff * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 32219820Sjeff * SOFTWARE. 33219820Sjeff * 34219820Sjeff */ 35219820Sjeff 36219820Sjeff/* 37219820Sjeff * Abstract: 38219820Sjeff * Specification of the OpenSM transport API. This API is OpenSM's view 39219820Sjeff * of the Infiniband transport. 40219820Sjeff */ 41219820Sjeff 42219820Sjeff#ifndef _OSM_VENDOR_API_H_ 43219820Sjeff#define _OSM_VENDOR_API_H_ 44219820Sjeff 45219820Sjeff#include <opensm/osm_madw.h> 46219820Sjeff#include <opensm/osm_mad_pool.h> 47219820Sjeff#include <vendor/osm_vendor.h> 48219820Sjeff 49219820Sjeff#ifdef __cplusplus 50219820Sjeff# define BEGIN_C_DECLS extern "C" { 51219820Sjeff# define END_C_DECLS } 52219820Sjeff#else /* !__cplusplus */ 53219820Sjeff# define BEGIN_C_DECLS 54219820Sjeff# define END_C_DECLS 55219820Sjeff#endif /* __cplusplus */ 56219820Sjeff 57219820SjeffBEGIN_C_DECLS 58219820Sjeff/****s* OpenSM Vendor API/osm_vend_mad_recv_callback_t 59219820Sjeff* NAME 60219820Sjeff* osm_vend_mad_recv_callback_t 61219820Sjeff* 62219820Sjeff* DESCRIPTION 63219820Sjeff* Function prototype for the vendor MAD receive callback. 64219820Sjeff* The vendor layer calls this function for MAD receives. 65219820Sjeff* 66219820Sjeff* SYNOPSIS 67219820Sjeff*/ 68219820Sjefftypedef void (*osm_vend_mad_recv_callback_t) (IN osm_madw_t * p_madw, 69219820Sjeff IN void *bind_context, 70219820Sjeff IN osm_madw_t * p_req_madw); 71219820Sjeff/* 72219820Sjeff* PARAMETERS 73219820Sjeff* p_madw 74219820Sjeff* [in] The received MAD wrapper. 75219820Sjeff* 76219820Sjeff* bind_context 77219820Sjeff* [in] User context supplied during the bind call. 78219820Sjeff* 79219820Sjeff* p_req_madw 80219820Sjeff* [in] Pointer to the request mad wrapper that generated this response. 81219820Sjeff* If the inbound MAD is not a response, this field is NULL. 82219820Sjeff* 83219820Sjeff* RETURN VALUES 84219820Sjeff* None. 85219820Sjeff* 86219820Sjeff* NOTES 87219820Sjeff* 88219820Sjeff* SEE ALSO 89219820Sjeff*********/ 90219820Sjeff 91219820Sjeff/****s* OpenSM Vendor API/osm_vend_mad_send_err_callback_t 92219820Sjeff* NAME 93219820Sjeff* osm_vend_mad_send_err_callback_t 94219820Sjeff* 95219820Sjeff* DESCRIPTION 96219820Sjeff* Function prototype for the vendor send failure callback. 97219820Sjeff* The vendor layer calls this function when MADs expecting 98219820Sjeff* a response are completed in error, most likely due to a 99219820Sjeff* timeout. 100219820Sjeff* 101219820Sjeff* SYNOPSIS 102219820Sjeff*/ 103219820Sjefftypedef void (*osm_vend_mad_send_err_callback_t) (IN void *bind_context, 104219820Sjeff IN osm_madw_t * p_madw); 105219820Sjeff/* 106219820Sjeff* PARAMETERS 107219820Sjeff* bind_context 108219820Sjeff* [in] User context supplied during the bind call. 109219820Sjeff* 110219820Sjeff* p_madw 111219820Sjeff* [in] Pointer to the request mad that failed. 112219820Sjeff* 113219820Sjeff* RETURN VALUES 114219820Sjeff* None. 115219820Sjeff* 116219820Sjeff* NOTES 117219820Sjeff* The vendor layer does not call this function (or any other) 118219820Sjeff* for MADs that were not expecting a response. 119219820Sjeff* 120219820Sjeff* SEE ALSO 121219820Sjeff*********/ 122219820Sjeff 123219820Sjeff/****f* OpenSM Vendor API/osm_vendor_new 124219820Sjeff* NAME 125219820Sjeff* osm_vendor_new 126219820Sjeff* 127219820Sjeff* DESCRIPTION 128219820Sjeff* Allocates and initializes a new osm_vendor_t object. 129219820Sjeff* OpenSM calls this function before any other in the vendor API. 130219820Sjeff* This object is passed as a parameter to all other vendor functions. 131219820Sjeff* 132219820Sjeff* SYNOPSIS 133219820Sjeff*/ 134219820Sjeffosm_vendor_t *osm_vendor_new(IN osm_log_t * const p_log, 135219820Sjeff IN const uint32_t timeout); 136219820Sjeff/* 137219820Sjeff* PARAMETERS 138219820Sjeff* p_log 139219820Sjeff* [in] Pointer to the log object to use. 140219820Sjeff* 141219820Sjeff* timeout 142219820Sjeff* [in] transaction timeout 143219820Sjeff* 144219820Sjeff* RETURN VALUES 145219820Sjeff* Returns a pointer to the vendor object. 146219820Sjeff* 147219820Sjeff* NOTES 148219820Sjeff* 149219820Sjeff* SEE ALSO 150219820Sjeff*********/ 151219820Sjeff 152219820Sjeff/****s* OpenSM Vendor API/osm_vendor_delete 153219820Sjeff* NAME 154219820Sjeff* osm_vendor_delete 155219820Sjeff* 156219820Sjeff* DESCRIPTION 157219820Sjeff* Dealocate the vendor object. 158219820Sjeff* 159219820Sjeff* SYNOPSIS 160219820Sjeff*/ 161219820Sjeffvoid osm_vendor_delete(IN osm_vendor_t ** const pp_vend); 162219820Sjeff/* 163219820Sjeff* PARAMETERS 164219820Sjeff* pp_vend 165219820Sjeff* [in/out] pointer to pointer to vendor objcet to be deleted 166219820Sjeff* 167219820Sjeff* RETURN VALUES 168219820Sjeff* None 169219820Sjeff* 170219820Sjeff* NOTES 171219820Sjeff* 172219820Sjeff* SEE ALSO 173219820Sjeff*********/ 174219820Sjeff 175219820Sjeff/****f* OpenSM Vendor API/osm_vendor_get_ports 176219820Sjeff* NAME 177219820Sjeff* osm_vendor_get_ports 178219820Sjeff* 179219820Sjeff* DESCRIPTION 180219820Sjeff* Returns an array of available port attribute structures. 181219820Sjeff* 182219820Sjeff* SYNOPSIS 183219820Sjeff*/ 184219820Sjeffib_api_status_t 185219820Sjeffosm_vendor_get_all_port_attr(IN osm_vendor_t * const p_vend, 186219820Sjeff IN ib_port_attr_t * const p_attr_array, 187219820Sjeff IN uint32_t * const p_num_ports); 188219820Sjeff/* 189219820Sjeff* PARAMETERS 190219820Sjeff* p_vend 191219820Sjeff* [in] Pointer to the vendor object to initialize. 192219820Sjeff* 193219820Sjeff* p_attr_array 194219820Sjeff* [in/out] Pointer to pre-allocated array of port attributes. 195219820Sjeff* If it is NULL - then the command only updates the p_num_ports, 196219820Sjeff* and return IB_INSUFFICIENT_MEMORY. 197219820Sjeff* 198219820Sjeff* p_num_ports 199219820Sjeff* [in/out] Pointer to a variable to hold the total number of ports 200219820Sjeff* available on the local machine.. 201219820Sjeff* 202219820Sjeff* RETURN VALUES 203219820Sjeff* IB_SUCCESS on success. 204219820Sjeff* IB_INSUFFICIENT_MEMORY if the attribute array was not large enough. 205219820Sjeff* The number of attributes needed is returned in num_guids. 206219820Sjeff* 207219820Sjeff* NOTES 208219820Sjeff* 209219820Sjeff* SEE ALSO 210219820Sjeff*********/ 211219820Sjeff 212219820Sjeff/****f* OpenSM Vendor API/osm_vendor_init 213219820Sjeff* NAME 214219820Sjeff* osm_vendor_init 215219820Sjeff* 216219820Sjeff* DESCRIPTION 217219820Sjeff* The osm_vendor_init function initializes the vendor transport layer. 218219820Sjeff* 219219820Sjeff* SYNOPSIS 220219820Sjeff*/ 221219820Sjeffib_api_status_t 222219820Sjeffosm_vendor_init(IN osm_vendor_t * const p_vend, 223219820Sjeff IN osm_log_t * const p_log, IN const uint32_t timeout); 224219820Sjeff/* 225219820Sjeff* PARAMETERS 226219820Sjeff* p_vend 227219820Sjeff* [in] Pointer to the vendor object to initialize. 228219820Sjeff* 229219820Sjeff* p_log 230219820Sjeff* [in] Pointer to OpenSM's log object. Vendor code may 231219820Sjeff* use the log object to send messages to OpenSM's log. 232219820Sjeff* 233219820Sjeff* timeout 234219820Sjeff* [in] Transaction timeout value in milliseconds. 235219820Sjeff* A value of 0 disables timeouts. 236219820Sjeff* 237219820Sjeff* RETURN VALUE 238219820Sjeff* 239219820Sjeff* NOTES 240219820Sjeff* 241219820Sjeff* SEE ALSO 242219820Sjeff*********/ 243219820Sjeff 244219820Sjeff/****f* OpenSM Vendor API/osm_vendor_bind 245219820Sjeff* NAME 246219820Sjeff* osm_vendor_bind 247219820Sjeff* 248219820Sjeff* DESCRIPTION 249219820Sjeff* The osm_vendor_bind function registers with the vendor transport layer 250219820Sjeff* per Mad Class per PortGuid for mad transport capability. 251219820Sjeff* 252219820Sjeff* SYNOPSIS 253219820Sjeff*/ 254219820Sjeffosm_bind_handle_t 255219820Sjeffosm_vendor_bind(IN osm_vendor_t * const p_vend, 256219820Sjeff IN osm_bind_info_t * const p_bind_info, 257219820Sjeff IN osm_mad_pool_t * const p_mad_pool, 258219820Sjeff IN osm_vend_mad_recv_callback_t mad_recv_callback, 259219820Sjeff IN osm_vend_mad_send_err_callback_t send_err_callback, 260219820Sjeff IN void *context); 261219820Sjeff/* 262219820Sjeff* PARAMETERS 263219820Sjeff* p_vend 264219820Sjeff* [in] pointer to the vendor object 265219820Sjeff* 266219820Sjeff* p_osm_bind_info 267219820Sjeff* [in] pointer to a struct defining the type of bind to perform. 268219820Sjeff* 269219820Sjeff* p_mad_pool 270219820Sjeff* [in] pointer to a mad wrappers pool to be used for allocating 271219820Sjeff* mad wrappers on send and receive. 272219820Sjeff* 273219820Sjeff* mad_recv_callback 274219820Sjeff* [in] the callback function to be invoked on mad receive. 275219820Sjeff* 276219820Sjeff* send_err_callback 277219820Sjeff* [in] the callback function to be invoked on mad transaction errors. 278219820Sjeff* 279219820Sjeff* context 280219820Sjeff* [in] the context to be provided to the callbacks as bind_ctx. 281219820Sjeff* 282219820Sjeff* RETURN VALUE 283219820Sjeff* On success, a valid bind handle. 284219820Sjeff* OSM_BIND_INVALID_HANDLE otherwise. 285219820Sjeff* 286219820Sjeff* NOTES 287219820Sjeff* 288219820Sjeff* SEE ALSO 289219820Sjeff*********/ 290219820Sjeff 291219820Sjeff/****f* OpenSM Vendor API/osm_vendor_unbind 292219820Sjeff* NAME 293219820Sjeff* osm_vendor_unbind 294219820Sjeff* 295219820Sjeff* DESCRIPTION 296219820Sjeff* Unbind the given bind handle (obtained by osm_vendor_bind). 297219820Sjeff* 298219820Sjeff* SYNOPSIS 299219820Sjeff*/ 300219820Sjeffvoid osm_vendor_unbind(IN osm_bind_handle_t h_bind); 301219820Sjeff/* 302219820Sjeff* PARAMETERS 303219820Sjeff* h_bind 304219820Sjeff* [in] the bind handle to release. 305219820Sjeff* 306219820Sjeff* RETURN VALUE 307219820Sjeff* NONE. 308219820Sjeff* 309219820Sjeff* NOTES 310219820Sjeff* 311219820Sjeff* SEE ALSO 312219820Sjeff*********/ 313219820Sjeff 314219820Sjeff/****f* OpenSM Vendor API/osm_vendor_get 315219820Sjeff* NAME 316219820Sjeff* osm_vendor_get 317219820Sjeff* 318219820Sjeff* DESCRIPTION 319219820Sjeff* Obtain a mad wrapper holding actual mad buffer to be sent via 320219820Sjeff* the transport. 321219820Sjeff* 322219820Sjeff* SYNOPSIS 323219820Sjeff*/ 324219820Sjeffib_mad_t *osm_vendor_get(IN osm_bind_handle_t h_bind, 325219820Sjeff IN const uint32_t mad_size, 326219820Sjeff IN osm_vend_wrap_t * const p_vend_wrap); 327219820Sjeff/* 328219820Sjeff* PARAMETERS 329219820Sjeff* h_bind 330219820Sjeff* [in] the bind handle obtained by calling osm_vendor_bind 331219820Sjeff* 332219820Sjeff* mad_size 333219820Sjeff* [in] the actual mad size required 334219820Sjeff* 335219820Sjeff* p_vend_wrap 336219820Sjeff* [out] the returned mad vendor wrapper 337219820Sjeff* 338219820Sjeff* RETURN VALUE 339219820Sjeff* IB_SUCCESS on succesful completion. 340219820Sjeff* 341219820Sjeff* NOTES 342219820Sjeff* 343219820Sjeff* SEE ALSO 344219820Sjeff*********/ 345219820Sjeff 346219820Sjeff/****f* OpenSM Vendor API/osm_vendor_send 347219820Sjeff* NAME 348219820Sjeff* osm_vendor_send 349219820Sjeff* 350219820Sjeff* DESCRIPTION 351219820Sjeff* 352219820Sjeff* SYNOPSIS 353219820Sjeff*/ 354219820Sjeffib_api_status_t 355219820Sjeffosm_vendor_send(IN osm_bind_handle_t h_bind, 356219820Sjeff IN osm_madw_t * const p_madw, IN boolean_t const resp_expected); 357219820Sjeff/* 358219820Sjeff* PARAMETERS 359219820Sjeff* h_bind 360219820Sjeff* [in] the bind handle obtained by calling osm_vendor_bind 361219820Sjeff* 362219820Sjeff* p_madw 363219820Sjeff* [in] pointer to the Mad Wrapper structure for the MAD to be sent. 364219820Sjeff* 365219820Sjeff* resp_expected 366219820Sjeff* [in] boolean value declaring the mad as a request (expecting a response). 367219820Sjeff* 368219820Sjeff* RETURN VALUE 369219820Sjeff* IB_SUCCESS on succesful completion. 370219820Sjeff* 371219820Sjeff* NOTES 372219820Sjeff* 1. Only mads that expect a response are tracked for transaction competion. 373219820Sjeff* 2. A mad that does not expect a response is being put back immediatly after 374219820Sjeff* being sent. 375219820Sjeff* 376219820Sjeff* SEE ALSO 377219820Sjeff*********/ 378219820Sjeff 379219820Sjeff/****f* OpenSM Vendor API/osm_vendor_put 380219820Sjeff* NAME 381219820Sjeff* osm_vendor_put 382219820Sjeff* 383219820Sjeff* DESCRIPTION 384219820Sjeff* Return a mad vendor wrapper to the mad pool. It also means that the 385219820Sjeff* mad buffer is returned to the transport. 386219820Sjeff* 387219820Sjeff* SYNOPSIS 388219820Sjeff*/ 389219820Sjeffvoid 390219820Sjeffosm_vendor_put(IN osm_bind_handle_t h_bind, 391219820Sjeff IN osm_vend_wrap_t * const p_vend_wrap); 392219820Sjeff/* 393219820Sjeff* PARAMETERS 394219820Sjeff* h_bind 395219820Sjeff* [in] the bind handle obtained by calling osm_vendor_bind 396219820Sjeff* 397219820Sjeff* p_vend_wrap 398219820Sjeff* [in] pointer to the mad vendor wrapper to put back into the pool. 399219820Sjeff* 400219820Sjeff* RETURN VALUE 401219820Sjeff* None. 402219820Sjeff* 403219820Sjeff* NOTES 404219820Sjeff* 405219820Sjeff* SEE ALSO 406219820Sjeff*********/ 407219820Sjeff 408219820Sjeff/****i* OpenSM Vendor API/osm_vendor_local_lid_change 409219820Sjeff* NAME 410219820Sjeff* osm_vendor_local_lid_change 411219820Sjeff* 412219820Sjeff* DESCRIPTION 413219820Sjeff* Notifies the vendor transport layer that the local address 414219820Sjeff* has changed. This allows the vendor layer to perform housekeeping 415219820Sjeff* functions such as address vector updates. 416219820Sjeff* 417219820Sjeff* SYNOPSIS 418219820Sjeff*/ 419219820Sjeffib_api_status_t osm_vendor_local_lid_change(IN osm_bind_handle_t h_bind); 420219820Sjeff/* 421219820Sjeff* PARAMETERS 422219820Sjeff* h_bind 423219820Sjeff* [in] the bind handle obtained by calling osm_vendor_bind 424219820Sjeff* 425219820Sjeff* RETURN VALUE 426219820Sjeff* 427219820Sjeff* NOTES 428219820Sjeff* 429219820Sjeff* SEE ALSO 430219820Sjeff*********/ 431219820Sjeff 432219820Sjeff/****f* OpenSM Vendor API/osm_vendor_set_sm 433219820Sjeff* NAME 434219820Sjeff* osm_vendor_set_sm 435219820Sjeff* 436219820Sjeff* DESCRIPTION 437219820Sjeff* Modifies the port info for the bound port to set the "IS_SM" bit 438219820Sjeff* according to the value given (TRUE or FALSE). 439219820Sjeff* 440219820Sjeff* SYNOPSIS 441219820Sjeff*/ 442219820Sjeffvoid osm_vendor_set_sm(IN osm_bind_handle_t h_bind, IN boolean_t is_sm_val); 443219820Sjeff/* 444219820Sjeff* PARAMETERS 445219820Sjeff* h_bind 446219820Sjeff* [in] bind handle for this port. 447219820Sjeff* 448219820Sjeff* is_sm_val 449219820Sjeff* [in] If TRUE - will set the is_sm to TRUE, if FALSE - will set the 450219820Sjeff* the is_sm to FALSE. 451219820Sjeff* 452219820Sjeff* RETURN VALUE 453219820Sjeff* None. 454219820Sjeff* 455219820Sjeff* NOTES 456219820Sjeff* 457219820Sjeff* SEE ALSO 458219820Sjeff*********/ 459219820Sjeff 460219820Sjeff/****f* OpenSM Vendor API/osm_vendor_set_debug 461219820Sjeff* NAME 462219820Sjeff* osm_vendor_set_debug 463219820Sjeff* 464219820Sjeff* DESCRIPTION 465219820Sjeff* Modifies the vendor specific debug level. 466219820Sjeff* 467219820Sjeff* SYNOPSIS 468219820Sjeff*/ 469219820Sjeffvoid osm_vendor_set_debug(IN osm_vendor_t * const p_vend, IN int32_t level); 470219820Sjeff/* 471219820Sjeff* PARAMETERS 472219820Sjeff* p_vend 473219820Sjeff* [in] vendor handle. 474219820Sjeff* 475219820Sjeff* level 476219820Sjeff* [in] vendor specific debug level. 477219820Sjeff* 478219820Sjeff* RETURN VALUE 479219820Sjeff* None. 480219820Sjeff* 481219820Sjeff* NOTES 482219820Sjeff* 483219820Sjeff* SEE ALSO 484219820Sjeff*********/ 485219820Sjeff 486219820SjeffEND_C_DECLS 487219820Sjeff#endif /* _OSM_VENDOR_API_H_ */ 488