Blame include/vendor/osm_vendor_api.h

Packit 13e616
/*
Packit 13e616
 * Copyright (c) 2004, 2005 Voltaire, Inc. All rights reserved.
Packit 13e616
 * Copyright (c) 2002-2005 Mellanox Technologies LTD. All rights reserved.
Packit 13e616
 * Copyright (c) 1996-2003 Intel Corporation. All rights reserved.
Packit 13e616
 *
Packit 13e616
 * This software is available to you under a choice of one of two
Packit 13e616
 * licenses.  You may choose to be licensed under the terms of the GNU
Packit 13e616
 * General Public License (GPL) Version 2, available from the file
Packit 13e616
 * COPYING in the main directory of this source tree, or the
Packit 13e616
 * OpenIB.org BSD license below:
Packit 13e616
 *
Packit 13e616
 *     Redistribution and use in source and binary forms, with or
Packit 13e616
 *     without modification, are permitted provided that the following
Packit 13e616
 *     conditions are met:
Packit 13e616
 *
Packit 13e616
 *      - Redistributions of source code must retain the above
Packit 13e616
 *        copyright notice, this list of conditions and the following
Packit 13e616
 *        disclaimer.
Packit 13e616
 *
Packit 13e616
 *      - Redistributions in binary form must reproduce the above
Packit 13e616
 *        copyright notice, this list of conditions and the following
Packit 13e616
 *        disclaimer in the documentation and/or other materials
Packit 13e616
 *        provided with the distribution.
Packit 13e616
 *
Packit 13e616
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
Packit 13e616
 * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
Packit 13e616
 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
Packit 13e616
 * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
Packit 13e616
 * BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
Packit 13e616
 * ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
Packit 13e616
 * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
Packit 13e616
 * SOFTWARE.
Packit 13e616
 *
Packit 13e616
 */
Packit 13e616
Packit 13e616
/*
Packit 13e616
 * Abstract:
Packit 13e616
 *  Specification of the OpenSM transport API. This API is OpenSM's view
Packit 13e616
 *  of the Infiniband transport.
Packit 13e616
 */
Packit 13e616
Packit 13e616
#ifndef _OSM_VENDOR_API_H_
Packit 13e616
#define _OSM_VENDOR_API_H_
Packit 13e616
Packit 13e616
#include <opensm/osm_madw.h>
Packit 13e616
#include <opensm/osm_mad_pool.h>
Packit 13e616
#include <vendor/osm_vendor.h>
Packit 13e616
Packit 13e616
#ifdef __cplusplus
Packit 13e616
#  define BEGIN_C_DECLS extern "C" {
Packit 13e616
#  define END_C_DECLS   }
Packit 13e616
#else				/* !__cplusplus */
Packit 13e616
#  define BEGIN_C_DECLS
Packit 13e616
#  define END_C_DECLS
Packit 13e616
#endif				/* __cplusplus */
Packit 13e616
Packit 13e616
BEGIN_C_DECLS
Packit 13e616
/****s* OpenSM Vendor API/osm_vend_mad_recv_callback_t
Packit 13e616
* NAME
Packit 13e616
*  osm_vend_mad_recv_callback_t
Packit 13e616
*
Packit 13e616
* DESCRIPTION
Packit 13e616
*  Function prototype for the vendor MAD receive callback.
Packit 13e616
*  The vendor layer calls this function for MAD receives.
Packit 13e616
*
Packit 13e616
* SYNOPSIS
Packit 13e616
*/
Packit 13e616
typedef void (*osm_vend_mad_recv_callback_t) (IN osm_madw_t * p_madw,
Packit 13e616
					      IN void *bind_context,
Packit 13e616
					      IN osm_madw_t * p_req_madw);
Packit 13e616
/*
Packit 13e616
* PARAMETERS
Packit 13e616
*  p_madw
Packit 13e616
*     [in] The received MAD wrapper.
Packit 13e616
*
Packit 13e616
*  bind_context
Packit 13e616
*     [in] User context supplied during the bind call.
Packit 13e616
*
Packit 13e616
*  p_req_madw
Packit 13e616
*     [in] Pointer to the request mad wrapper that generated this response.
Packit 13e616
*     If the inbound MAD is not a response, this field is NULL.
Packit 13e616
*
Packit 13e616
* RETURN VALUES
Packit 13e616
*  None.
Packit 13e616
*
Packit 13e616
* NOTES
Packit 13e616
*
Packit 13e616
* SEE ALSO
Packit 13e616
*********/
Packit 13e616
Packit 13e616
/****s* OpenSM Vendor API/osm_vend_mad_send_err_callback_t
Packit 13e616
* NAME
Packit 13e616
*  osm_vend_mad_send_err_callback_t
Packit 13e616
*
Packit 13e616
* DESCRIPTION
Packit 13e616
*  Function prototype for the vendor send failure callback.
Packit 13e616
*  The vendor layer calls this function when MADs expecting
Packit 13e616
*  a response are completed in error, most likely due to a
Packit 13e616
*  timeout.
Packit 13e616
*
Packit 13e616
* SYNOPSIS
Packit 13e616
*/
Packit 13e616
typedef void (*osm_vend_mad_send_err_callback_t) (IN void *bind_context,
Packit 13e616
						  IN osm_madw_t * p_madw);
Packit 13e616
/*
Packit 13e616
* PARAMETERS
Packit 13e616
*  bind_context
Packit 13e616
*     [in] User context supplied during the bind call.
Packit 13e616
*
Packit 13e616
*  p_madw
Packit 13e616
*     [in] Pointer to the request mad that failed.
Packit 13e616
*
Packit 13e616
* RETURN VALUES
Packit 13e616
*  None.
Packit 13e616
*
Packit 13e616
* NOTES
Packit 13e616
*  The vendor layer does not call this function (or any other)
Packit 13e616
*  for MADs that were not expecting a response.
Packit 13e616
*
Packit 13e616
* SEE ALSO
Packit 13e616
*********/
Packit 13e616
Packit 13e616
/****f* OpenSM Vendor API/osm_vendor_new
Packit 13e616
* NAME
Packit 13e616
*  osm_vendor_new
Packit 13e616
*
Packit 13e616
* DESCRIPTION
Packit 13e616
*  Allocates and initializes a new osm_vendor_t object.
Packit 13e616
*  OpenSM calls this function before any other in the vendor API.
Packit 13e616
*  This object is passed as a parameter to all other vendor functions.
Packit 13e616
*
Packit 13e616
* SYNOPSIS
Packit 13e616
*/
Packit 13e616
osm_vendor_t *osm_vendor_new(IN osm_log_t * const p_log,
Packit 13e616
			     IN const uint32_t timeout);
Packit 13e616
/*
Packit 13e616
* PARAMETERS
Packit 13e616
*  p_log
Packit 13e616
*     [in] Pointer to the log object to use.
Packit 13e616
*
Packit 13e616
*  timeout
Packit 13e616
*     [in] transaction timeout
Packit 13e616
*
Packit 13e616
* RETURN VALUES
Packit 13e616
*  Returns a pointer to the vendor object.
Packit 13e616
*
Packit 13e616
* NOTES
Packit 13e616
*
Packit 13e616
* SEE ALSO
Packit 13e616
*********/
Packit 13e616
Packit 13e616
/****s* OpenSM Vendor API/osm_vendor_delete
Packit 13e616
* NAME
Packit 13e616
*  osm_vendor_delete
Packit 13e616
*
Packit 13e616
* DESCRIPTION
Packit 13e616
*  Dealocate the vendor object.
Packit 13e616
*
Packit 13e616
* SYNOPSIS
Packit 13e616
*/
Packit 13e616
void osm_vendor_delete(IN osm_vendor_t ** const pp_vend);
Packit 13e616
/*
Packit 13e616
* PARAMETERS
Packit 13e616
*  pp_vend
Packit 13e616
*     [in/out] pointer to pointer to vendor objcet to be deleted
Packit 13e616
*
Packit 13e616
* RETURN VALUES
Packit 13e616
*  None
Packit 13e616
*
Packit 13e616
* NOTES
Packit 13e616
*
Packit 13e616
* SEE ALSO
Packit 13e616
*********/
Packit 13e616
Packit 13e616
/****f* OpenSM Vendor API/osm_vendor_get_all_port_attr
Packit 13e616
* NAME
Packit 13e616
*  osm_vendor_get_all_port_attr
Packit 13e616
*
Packit 13e616
* DESCRIPTION
Packit 13e616
*  Returns an array of available port attribute structures.
Packit 13e616
*
Packit 13e616
* SYNOPSIS
Packit 13e616
*/
Packit 13e616
ib_api_status_t
Packit 13e616
osm_vendor_get_all_port_attr(IN osm_vendor_t * const p_vend,
Packit 13e616
			     IN ib_port_attr_t * const p_attr_array,
Packit 13e616
			     IN uint32_t * const p_num_ports);
Packit 13e616
/*
Packit 13e616
* PARAMETERS
Packit 13e616
*  p_vend
Packit 13e616
*     [in] Pointer to the vendor object to initialize.
Packit 13e616
*
Packit 13e616
*  p_attr_array
Packit 13e616
*     [in/out] Pointer to pre-allocated array of port attributes.
Packit 13e616
*     If it is NULL - then the command only updates the p_num_ports,
Packit 13e616
*     and return IB_INSUFFICIENT_MEMORY.
Packit 13e616
*
Packit 13e616
*  p_num_ports
Packit 13e616
*     [in/out] Pointer to a variable to hold the total number of ports
Packit 13e616
*     available on the local machine.
Packit 13e616
*
Packit 13e616
* RETURN VALUES
Packit 13e616
*  IB_SUCCESS on success.
Packit 13e616
*  IB_INSUFFICIENT_MEMORY if the attribute array was not large enough.
Packit 13e616
*  The number of attributes needed is returned in num_guids.
Packit 13e616
*
Packit 13e616
* NOTES
Packit 13e616
*
Packit 13e616
* SEE ALSO
Packit 13e616
*********/
Packit 13e616
Packit 13e616
/****f* OpenSM Vendor API/osm_vendor_init
Packit 13e616
* NAME
Packit 13e616
*  osm_vendor_init
Packit 13e616
*
Packit 13e616
* DESCRIPTION
Packit 13e616
*  The osm_vendor_init function initializes the vendor transport layer.
Packit 13e616
*
Packit 13e616
* SYNOPSIS
Packit 13e616
*/
Packit 13e616
ib_api_status_t
Packit 13e616
osm_vendor_init(IN osm_vendor_t * const p_vend, IN osm_log_t * const p_log,
Packit 13e616
		IN const uint32_t timeout);
Packit 13e616
/*
Packit 13e616
* PARAMETERS
Packit 13e616
*  p_vend
Packit 13e616
*     [in] Pointer to the vendor object to initialize.
Packit 13e616
*
Packit 13e616
*  p_log
Packit 13e616
*     [in] Pointer to OpenSM's log object.  Vendor code may
Packit 13e616
*     use the log object to send messages to OpenSM's log.
Packit 13e616
*
Packit 13e616
*  timeout
Packit 13e616
*     [in] Transaction timeout value in milliseconds.
Packit 13e616
*     A value of 0 disables timeouts.
Packit 13e616
*
Packit 13e616
* RETURN VALUE
Packit 13e616
*
Packit 13e616
* NOTES
Packit 13e616
*
Packit 13e616
* SEE ALSO
Packit 13e616
*********/
Packit 13e616
Packit 13e616
/****f* OpenSM Vendor API/osm_vendor_bind
Packit 13e616
* NAME
Packit 13e616
*   osm_vendor_bind
Packit 13e616
*
Packit 13e616
* DESCRIPTION
Packit 13e616
*   The osm_vendor_bind function registers with the vendor transport layer
Packit 13e616
*   per Mad Class per PortGuid for mad transport capability.
Packit 13e616
*
Packit 13e616
* SYNOPSIS
Packit 13e616
*/
Packit 13e616
osm_bind_handle_t
Packit 13e616
osm_vendor_bind(IN osm_vendor_t * const p_vend,
Packit 13e616
		IN osm_bind_info_t * const p_bind_info,
Packit 13e616
		IN osm_mad_pool_t * const p_mad_pool,
Packit 13e616
		IN osm_vend_mad_recv_callback_t mad_recv_callback,
Packit 13e616
		IN osm_vend_mad_send_err_callback_t send_err_callback,
Packit 13e616
		IN void *context);
Packit 13e616
/*
Packit 13e616
* PARAMETERS
Packit 13e616
*  p_vend
Packit 13e616
*    [in] pointer to the vendor object
Packit 13e616
*
Packit 13e616
*  p_osm_bind_info
Packit 13e616
*    [in] pointer to a struct defining the type of bind to perform.
Packit 13e616
*
Packit 13e616
*  p_mad_pool
Packit 13e616
*    [in] pointer to a mad wrappers pool to be used for allocating
Packit 13e616
*    mad wrappers on send and receive.
Packit 13e616
*
Packit 13e616
*  mad_recv_callback
Packit 13e616
*    [in] the callback function to be invoked on mad receive.
Packit 13e616
*
Packit 13e616
*  send_err_callback
Packit 13e616
*    [in] the callback function to be invoked on mad transaction errors.
Packit 13e616
*
Packit 13e616
*  context
Packit 13e616
*    [in] the context to be provided to the callbacks as bind_ctx.
Packit 13e616
*
Packit 13e616
* RETURN VALUE
Packit 13e616
*  On success, a valid bind handle.
Packit 13e616
*  OSM_BIND_INVALID_HANDLE otherwise.
Packit 13e616
*
Packit 13e616
* NOTES
Packit 13e616
*
Packit 13e616
* SEE ALSO
Packit 13e616
*********/
Packit 13e616
Packit 13e616
/****f* OpenSM Vendor API/osm_vendor_unbind
Packit 13e616
* NAME
Packit 13e616
*   osm_vendor_unbind
Packit 13e616
*
Packit 13e616
* DESCRIPTION
Packit 13e616
*   Unbind the given bind handle (obtained by osm_vendor_bind).
Packit 13e616
*
Packit 13e616
* SYNOPSIS
Packit 13e616
*/
Packit 13e616
void osm_vendor_unbind(IN osm_bind_handle_t h_bind);
Packit 13e616
/*
Packit 13e616
* PARAMETERS
Packit 13e616
*  h_bind
Packit 13e616
*    [in] the bind handle to release.
Packit 13e616
*
Packit 13e616
* RETURN VALUE
Packit 13e616
*    NONE.
Packit 13e616
*
Packit 13e616
* NOTES
Packit 13e616
*
Packit 13e616
* SEE ALSO
Packit 13e616
*********/
Packit 13e616
Packit 13e616
/****f* OpenSM Vendor API/osm_vendor_get
Packit 13e616
* NAME
Packit 13e616
*   osm_vendor_get
Packit 13e616
*
Packit 13e616
* DESCRIPTION
Packit 13e616
*   Obtain a mad wrapper holding actual mad buffer to be sent via
Packit 13e616
*   the transport.
Packit 13e616
*
Packit 13e616
* SYNOPSIS
Packit 13e616
*/
Packit 13e616
ib_mad_t *osm_vendor_get(IN osm_bind_handle_t h_bind,
Packit 13e616
			 IN const uint32_t mad_size,
Packit 13e616
			 IN osm_vend_wrap_t * const p_vend_wrap);
Packit 13e616
/*
Packit 13e616
* PARAMETERS
Packit 13e616
*   h_bind
Packit 13e616
*      [in] the bind handle obtained by calling osm_vendor_bind
Packit 13e616
*
Packit 13e616
*   mad_size
Packit 13e616
*      [in] the actual mad size required
Packit 13e616
*
Packit 13e616
*   p_vend_wrap
Packit 13e616
*      [out] the returned mad vendor wrapper
Packit 13e616
*
Packit 13e616
* RETURN VALUE
Packit 13e616
*   IB_SUCCESS on succesful completion.
Packit 13e616
*
Packit 13e616
* NOTES
Packit 13e616
*
Packit 13e616
* SEE ALSO
Packit 13e616
*********/
Packit 13e616
Packit 13e616
/****f* OpenSM Vendor API/osm_vendor_send
Packit 13e616
* NAME
Packit 13e616
*   osm_vendor_send
Packit 13e616
*
Packit 13e616
* DESCRIPTION
Packit 13e616
*
Packit 13e616
* SYNOPSIS
Packit 13e616
*/
Packit 13e616
ib_api_status_t
Packit 13e616
osm_vendor_send(IN osm_bind_handle_t h_bind,
Packit 13e616
		IN osm_madw_t * const p_madw, IN boolean_t const resp_expected);
Packit 13e616
/*
Packit 13e616
* PARAMETERS
Packit 13e616
*   h_bind
Packit 13e616
*      [in] the bind handle obtained by calling osm_vendor_bind
Packit 13e616
*
Packit 13e616
*   p_madw
Packit 13e616
*      [in] pointer to the Mad Wrapper structure for the MAD to be sent.
Packit 13e616
*
Packit 13e616
*   resp_expected
Packit 13e616
*      [in] boolean value declaring the mad as a request (expecting a response).
Packit 13e616
*
Packit 13e616
* RETURN VALUE
Packit 13e616
*   IB_SUCCESS on succesful completion.
Packit 13e616
*
Packit 13e616
* NOTES
Packit 13e616
*   1. Only mads that expect a response are tracked for transaction competion.
Packit 13e616
*   2. A mad that does not expect a response is being put back immediately
Packit 13e616
*      after being sent.
Packit 13e616
*
Packit 13e616
* SEE ALSO
Packit 13e616
*********/
Packit 13e616
Packit 13e616
/****f* OpenSM Vendor API/osm_vendor_put
Packit 13e616
* NAME
Packit 13e616
*   osm_vendor_put
Packit 13e616
*
Packit 13e616
* DESCRIPTION
Packit 13e616
*   Return a mad vendor wrapper to the mad pool. It also means that the
Packit 13e616
*   mad buffer is returned to the transport.
Packit 13e616
*
Packit 13e616
* SYNOPSIS
Packit 13e616
*/
Packit 13e616
void
Packit 13e616
osm_vendor_put(IN osm_bind_handle_t h_bind,
Packit 13e616
	       IN osm_vend_wrap_t * const p_vend_wrap);
Packit 13e616
/*
Packit 13e616
* PARAMETERS
Packit 13e616
*   h_bind
Packit 13e616
*      [in] the bind handle obtained by calling osm_vendor_bind
Packit 13e616
*
Packit 13e616
*   p_vend_wrap
Packit 13e616
*      [in] pointer to the mad vendor wrapper to put back into the pool.
Packit 13e616
*
Packit 13e616
* RETURN VALUE
Packit 13e616
*   None.
Packit 13e616
*
Packit 13e616
* NOTES
Packit 13e616
*
Packit 13e616
* SEE ALSO
Packit 13e616
*********/
Packit 13e616
Packit 13e616
/****i* OpenSM Vendor API/osm_vendor_local_lid_change
Packit 13e616
* NAME
Packit 13e616
*   osm_vendor_local_lid_change
Packit 13e616
*
Packit 13e616
* DESCRIPTION
Packit 13e616
*  Notifies the vendor transport layer that the local address
Packit 13e616
*  has changed.  This allows the vendor layer to perform housekeeping
Packit 13e616
*  functions such as address vector updates.
Packit 13e616
*
Packit 13e616
* SYNOPSIS
Packit 13e616
*/
Packit 13e616
ib_api_status_t osm_vendor_local_lid_change(IN osm_bind_handle_t h_bind);
Packit 13e616
/*
Packit 13e616
* PARAMETERS
Packit 13e616
*   h_bind
Packit 13e616
*      [in] the bind handle obtained by calling osm_vendor_bind
Packit 13e616
*
Packit 13e616
* RETURN VALUE
Packit 13e616
*
Packit 13e616
* NOTES
Packit 13e616
*
Packit 13e616
* SEE ALSO
Packit 13e616
*********/
Packit 13e616
Packit 13e616
/****f* OpenSM Vendor API/osm_vendor_set_sm
Packit 13e616
* NAME
Packit 13e616
*   osm_vendor_set_sm
Packit 13e616
*
Packit 13e616
* DESCRIPTION
Packit 13e616
*  Modifies the port info for the bound port to set the "IS_SM" bit
Packit 13e616
*  according to the value given (TRUE or FALSE).
Packit 13e616
*
Packit 13e616
* SYNOPSIS
Packit 13e616
*/
Packit 13e616
void osm_vendor_set_sm(IN osm_bind_handle_t h_bind, IN boolean_t is_sm_val);
Packit 13e616
/*
Packit 13e616
* PARAMETERS
Packit 13e616
*   h_bind
Packit 13e616
*     [in] bind handle for this port.
Packit 13e616
*
Packit 13e616
*   is_sm_val
Packit 13e616
*     [in] If TRUE - will set the is_sm to TRUE, if FALSE - will set the
Packit 13e616
*          the is_sm to FALSE.
Packit 13e616
*
Packit 13e616
* RETURN VALUE
Packit 13e616
*  None.
Packit 13e616
*
Packit 13e616
* NOTES
Packit 13e616
*
Packit 13e616
* SEE ALSO
Packit 13e616
*********/
Packit 13e616
Packit 13e616
/****f* OpenSM Vendor API/osm_vendor_set_debug
Packit 13e616
* NAME
Packit 13e616
*   osm_vendor_set_debug
Packit 13e616
*
Packit 13e616
* DESCRIPTION
Packit 13e616
*  Modifies the vendor specific debug level.
Packit 13e616
*
Packit 13e616
* SYNOPSIS
Packit 13e616
*/
Packit 13e616
void osm_vendor_set_debug(IN osm_vendor_t * const p_vend, IN int32_t level);
Packit 13e616
/*
Packit 13e616
* PARAMETERS
Packit 13e616
*   p_vend
Packit 13e616
*     [in] vendor handle.
Packit 13e616
*
Packit 13e616
*   level
Packit 13e616
*     [in] vendor specific debug level.
Packit 13e616
*
Packit 13e616
* RETURN VALUE
Packit 13e616
*  None.
Packit 13e616
*
Packit 13e616
* NOTES
Packit 13e616
*
Packit 13e616
* SEE ALSO
Packit 13e616
*********/
Packit 13e616
Packit 13e616
END_C_DECLS
Packit 13e616
#endif				/* _OSM_VENDOR_API_H_ */