/*
 * Copyright (c) 2004, 2005 Voltaire, Inc. All rights reserved.
 * Copyright (c) 2002-2005 Mellanox Technologies LTD. All rights reserved.
 * Copyright (c) 1996-2003 Intel Corporation. All rights reserved.
 *
 * This software is available to you under a choice of one of two
 * licenses.  You may choose to be licensed under the terms of the GNU
 * General Public License (GPL) Version 2, available from the file
 * COPYING in the main directory of this source tree, or the
 * OpenIB.org BSD license below:
 *
 *     Redistribution and use in source and binary forms, with or
 *     without modification, are permitted provided that the following
 *     conditions are met:
 *
 *      - Redistributions of source code must retain the above
 *        copyright notice, this list of conditions and the following
 *        disclaimer.
 *
 *      - Redistributions in binary form must reproduce the above
 *        copyright notice, this list of conditions and the following
 *        disclaimer in the documentation and/or other materials
 *        provided with the distribution.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
 * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
 * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
 * BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
 * ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
 * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 * SOFTWARE.
 *
 */

/*
 * Abstract:
 *  Specification of the OpenSM transport API. This API is OpenSM's view
 *  of the Infiniband transport.
 */

#ifndef _OSM_VENDOR_API_H_
#define _OSM_VENDOR_API_H_

#include <opensm/osm_madw.h>
#include <opensm/osm_mad_pool.h>
#include <vendor/osm_vendor.h>

#ifdef __cplusplus
#  define BEGIN_C_DECLS extern "C" {
#  define END_C_DECLS   }
#else				/* !__cplusplus */
#  define BEGIN_C_DECLS
#  define END_C_DECLS
#endif				/* __cplusplus */

BEGIN_C_DECLS
/****s* OpenSM Vendor API/osm_vend_mad_recv_callback_t
* NAME
*  osm_vend_mad_recv_callback_t
*
* DESCRIPTION
*  Function prototype for the vendor MAD receive callback.
*  The vendor layer calls this function for MAD receives.
*
* SYNOPSIS
*/
typedef void (*osm_vend_mad_recv_callback_t) (IN osm_madw_t * p_madw,
					      IN void *bind_context,
					      IN osm_madw_t * p_req_madw);
/*
* PARAMETERS
*  p_madw
*     [in] The received MAD wrapper.
*
*  bind_context
*     [in] User context supplied during the bind call.
*
*  p_req_madw
*     [in] Pointer to the request mad wrapper that generated this response.
*     If the inbound MAD is not a response, this field is NULL.
*
* RETURN VALUES
*  None.
*
* NOTES
*
* SEE ALSO
*********/

/****s* OpenSM Vendor API/osm_vend_mad_send_err_callback_t
* NAME
*  osm_vend_mad_send_err_callback_t
*
* DESCRIPTION
*  Function prototype for the vendor send failure callback.
*  The vendor layer calls this function when MADs expecting
*  a response are completed in error, most likely due to a
*  timeout.
*
* SYNOPSIS
*/
typedef void (*osm_vend_mad_send_err_callback_t) (IN void *bind_context,
						  IN osm_madw_t * p_madw);
/*
* PARAMETERS
*  bind_context
*     [in] User context supplied during the bind call.
*
*  p_madw
*     [in] Pointer to the request mad that failed.
*
* RETURN VALUES
*  None.
*
* NOTES
*  The vendor layer does not call this function (or any other)
*  for MADs that were not expecting a response.
*
* SEE ALSO
*********/

/****f* OpenSM Vendor API/osm_vendor_new
* NAME
*  osm_vendor_new
*
* DESCRIPTION
*  Allocates and initializes a new osm_vendor_t object.
*  OpenSM calls this function before any other in the vendor API.
*  This object is passed as a parameter to all other vendor functions.
*
* SYNOPSIS
*/
osm_vendor_t *osm_vendor_new(IN osm_log_t * const p_log,
			     IN const uint32_t timeout);
/*
* PARAMETERS
*  p_log
*     [in] Pointer to the log object to use.
*
*  timeout
*     [in] transaction timeout
*
* RETURN VALUES
*  Returns a pointer to the vendor object.
*
* NOTES
*
* SEE ALSO
*********/

/****s* OpenSM Vendor API/osm_vendor_delete
* NAME
*  osm_vendor_delete
*
* DESCRIPTION
*  Dealocate the vendor object.
*
* SYNOPSIS
*/
void osm_vendor_delete(IN osm_vendor_t ** const pp_vend);
/*
* PARAMETERS
*  pp_vend
*     [in/out] pointer to pointer to vendor objcet to be deleted
*
* RETURN VALUES
*  None
*
* NOTES
*
* SEE ALSO
*********/

/****f* OpenSM Vendor API/osm_vendor_get_all_port_attr
* NAME
*  osm_vendor_get_all_port_attr
*
* DESCRIPTION
*  Returns an array of available port attribute structures.
*
* SYNOPSIS
*/
ib_api_status_t
osm_vendor_get_all_port_attr(IN osm_vendor_t * const p_vend,
			     IN ib_port_attr_t * const p_attr_array,
			     IN uint32_t * const p_num_ports);
/*
* PARAMETERS
*  p_vend
*     [in] Pointer to the vendor object to initialize.
*
*  p_attr_array
*     [in/out] Pointer to pre-allocated array of port attributes.
*     If it is NULL - then the command only updates the p_num_ports,
*     and return IB_INSUFFICIENT_MEMORY.
*
*  p_num_ports
*     [in/out] Pointer to a variable to hold the total number of ports
*     available on the local machine.
*
* RETURN VALUES
*  IB_SUCCESS on success.
*  IB_INSUFFICIENT_MEMORY if the attribute array was not large enough.
*  The number of attributes needed is returned in num_guids.
*
* NOTES
*
* SEE ALSO
*********/

/****f* OpenSM Vendor API/osm_vendor_init
* NAME
*  osm_vendor_init
*
* DESCRIPTION
*  The osm_vendor_init function initializes the vendor transport layer.
*
* SYNOPSIS
*/
ib_api_status_t
osm_vendor_init(IN osm_vendor_t * const p_vend, IN osm_log_t * const p_log,
		IN const uint32_t timeout);
/*
* PARAMETERS
*  p_vend
*     [in] Pointer to the vendor object to initialize.
*
*  p_log
*     [in] Pointer to OpenSM's log object.  Vendor code may
*     use the log object to send messages to OpenSM's log.
*
*  timeout
*     [in] Transaction timeout value in milliseconds.
*     A value of 0 disables timeouts.
*
* RETURN VALUE
*
* NOTES
*
* SEE ALSO
*********/

/****f* OpenSM Vendor API/osm_vendor_bind
* NAME
*   osm_vendor_bind
*
* DESCRIPTION
*   The osm_vendor_bind function registers with the vendor transport layer
*   per Mad Class per PortGuid for mad transport capability.
*
* SYNOPSIS
*/
osm_bind_handle_t
osm_vendor_bind(IN osm_vendor_t * const p_vend,
		IN osm_bind_info_t * const p_bind_info,
		IN osm_mad_pool_t * const p_mad_pool,
		IN osm_vend_mad_recv_callback_t mad_recv_callback,
		IN osm_vend_mad_send_err_callback_t send_err_callback,
		IN void *context);
/*
* PARAMETERS
*  p_vend
*    [in] pointer to the vendor object
*
*  p_osm_bind_info
*    [in] pointer to a struct defining the type of bind to perform.
*
*  p_mad_pool
*    [in] pointer to a mad wrappers pool to be used for allocating
*    mad wrappers on send and receive.
*
*  mad_recv_callback
*    [in] the callback function to be invoked on mad receive.
*
*  send_err_callback
*    [in] the callback function to be invoked on mad transaction errors.
*
*  context
*    [in] the context to be provided to the callbacks as bind_ctx.
*
* RETURN VALUE
*  On success, a valid bind handle.
*  OSM_BIND_INVALID_HANDLE otherwise.
*
* NOTES
*
* SEE ALSO
*********/

/****f* OpenSM Vendor API/osm_vendor_unbind
* NAME
*   osm_vendor_unbind
*
* DESCRIPTION
*   Unbind the given bind handle (obtained by osm_vendor_bind).
*
* SYNOPSIS
*/
void osm_vendor_unbind(IN osm_bind_handle_t h_bind);
/*
* PARAMETERS
*  h_bind
*    [in] the bind handle to release.
*
* RETURN VALUE
*    NONE.
*
* NOTES
*
* SEE ALSO
*********/

/****f* OpenSM Vendor API/osm_vendor_get
* NAME
*   osm_vendor_get
*
* DESCRIPTION
*   Obtain a mad wrapper holding actual mad buffer to be sent via
*   the transport.
*
* SYNOPSIS
*/
ib_mad_t *osm_vendor_get(IN osm_bind_handle_t h_bind,
			 IN const uint32_t mad_size,
			 IN osm_vend_wrap_t * const p_vend_wrap);
/*
* PARAMETERS
*   h_bind
*      [in] the bind handle obtained by calling osm_vendor_bind
*
*   mad_size
*      [in] the actual mad size required
*
*   p_vend_wrap
*      [out] the returned mad vendor wrapper
*
* RETURN VALUE
*   IB_SUCCESS on succesful completion.
*
* NOTES
*
* SEE ALSO
*********/

/****f* OpenSM Vendor API/osm_vendor_send
* NAME
*   osm_vendor_send
*
* DESCRIPTION
*
* SYNOPSIS
*/
ib_api_status_t
osm_vendor_send(IN osm_bind_handle_t h_bind,
		IN osm_madw_t * const p_madw, IN boolean_t const resp_expected);
/*
* PARAMETERS
*   h_bind
*      [in] the bind handle obtained by calling osm_vendor_bind
*
*   p_madw
*      [in] pointer to the Mad Wrapper structure for the MAD to be sent.
*
*   resp_expected
*      [in] boolean value declaring the mad as a request (expecting a response).
*
* RETURN VALUE
*   IB_SUCCESS on succesful completion.
*
* NOTES
*   1. Only mads that expect a response are tracked for transaction competion.
*   2. A mad that does not expect a response is being put back immediately
*      after being sent.
*
* SEE ALSO
*********/

/****f* OpenSM Vendor API/osm_vendor_put
* NAME
*   osm_vendor_put
*
* DESCRIPTION
*   Return a mad vendor wrapper to the mad pool. It also means that the
*   mad buffer is returned to the transport.
*
* SYNOPSIS
*/
void
osm_vendor_put(IN osm_bind_handle_t h_bind,
	       IN osm_vend_wrap_t * const p_vend_wrap);
/*
* PARAMETERS
*   h_bind
*      [in] the bind handle obtained by calling osm_vendor_bind
*
*   p_vend_wrap
*      [in] pointer to the mad vendor wrapper to put back into the pool.
*
* RETURN VALUE
*   None.
*
* NOTES
*
* SEE ALSO
*********/

/****i* OpenSM Vendor API/osm_vendor_local_lid_change
* NAME
*   osm_vendor_local_lid_change
*
* DESCRIPTION
*  Notifies the vendor transport layer that the local address
*  has changed.  This allows the vendor layer to perform housekeeping
*  functions such as address vector updates.
*
* SYNOPSIS
*/
ib_api_status_t osm_vendor_local_lid_change(IN osm_bind_handle_t h_bind);
/*
* PARAMETERS
*   h_bind
*      [in] the bind handle obtained by calling osm_vendor_bind
*
* RETURN VALUE
*
* NOTES
*
* SEE ALSO
*********/

/****f* OpenSM Vendor API/osm_vendor_set_sm
* NAME
*   osm_vendor_set_sm
*
* DESCRIPTION
*  Modifies the port info for the bound port to set the "IS_SM" bit
*  according to the value given (TRUE or FALSE).
*
* SYNOPSIS
*/
void osm_vendor_set_sm(IN osm_bind_handle_t h_bind, IN boolean_t is_sm_val);
/*
* PARAMETERS
*   h_bind
*     [in] bind handle for this port.
*
*   is_sm_val
*     [in] If TRUE - will set the is_sm to TRUE, if FALSE - will set the
*          the is_sm to FALSE.
*
* RETURN VALUE
*  None.
*
* NOTES
*
* SEE ALSO
*********/

/****f* OpenSM Vendor API/osm_vendor_set_debug
* NAME
*   osm_vendor_set_debug
*
* DESCRIPTION
*  Modifies the vendor specific debug level.
*
* SYNOPSIS
*/
void osm_vendor_set_debug(IN osm_vendor_t * const p_vend, IN int32_t level);
/*
* PARAMETERS
*   p_vend
*     [in] vendor handle.
*
*   level
*     [in] vendor specific debug level.
*
* RETURN VALUE
*  None.
*
* NOTES
*
* SEE ALSO
*********/

END_C_DECLS
#endif				/* _OSM_VENDOR_API_H_ */