/*
 * Copyright (c) 2004-2009 Voltaire, Inc. All rights reserved.
 * Copyright (c) 2002-2009 Mellanox Technologies LTD. All rights reserved.
 * Copyright (c) 1996-2003 Intel Corporation. All rights reserved.
 * Copyright (c) 2009 HNR Consulting. 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:
 * 	Declaration of osm_mcast_tbl_t.
 *	This object represents a multicast forwarding table.
 *	This object is part of the OpenSM family of objects.
 */

#ifndef _OSM_MCAST_TBL_H_
#define _OSM_MCAST_TBL_H_

#include <iba/ib_types.h>
#include <complib/cl_qmap.h>
#include <opensm/osm_base.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: Forwarding Table/osm_mcast_tbl_t
* NAME
*	osm_mcast_tbl_t
*
* DESCRIPTION
*	Multicast Forwarding Table structure.
*
*	Callers may directly access this object.
*
* SYNOPSIS
*/
typedef struct osm_mcast_fwdbl {
	uint8_t num_ports;
	uint8_t max_position;
	uint16_t max_block;
	int16_t max_block_in_use;
	uint16_t num_entries;
	uint16_t max_mlid_ho;
	uint16_t mft_depth;
	uint16_t(*p_mask_tbl)[][IB_MCAST_POSITION_MAX + 1];
} osm_mcast_tbl_t;
/*
* FIELDS
*	num_ports
*		The number of ports in the port mask.  This value
*		is the same as the number of ports on the switch
*
*	max_position
*		Maximum bit mask position for this table.  This value
*		is computed from the number of ports on the switch.
*
*	max_block
*		Maximum block number supported in the table.  This value
*		is approximately the number of MLID entries divided by the
*		number of MLIDs per block
*
*	num_entries
*		Number of entries in the table (aka number of MLIDs supported).
*
*	max_mlid_ho
*		Maximum MLID (host order) for the currently allocated multicast
*		port mask table.
*
*	mft_depth
*		Number of MLIDs in the currently allocated multicast port mask
*		table.
*
*	p_mask_tbl
*		Pointer to a two dimensional array of port_masks for this switch.
*		The first dimension is MLID offset, second dimension is mask position.
*		This pointer is null for switches that do not support multicast.
*
* SEE ALSO
*********/

/****f* OpenSM: Forwarding Table/osm_mcast_tbl_init
* NAME
*	osm_mcast_tbl_init
*
* DESCRIPTION
*	This function initializes a Multicast Forwarding Table object.
*
* SYNOPSIS
*/
void osm_mcast_tbl_init(IN osm_mcast_tbl_t * p_tbl, IN uint8_t num_ports,
			IN uint16_t capacity);
/*
* PARAMETERS
*	num_ports
*		[in] Number of ports in the switch owning this table.
*
*	capacity
*		[in] The number of MLID entries (starting at 0xC000) supported
*		by this switch.
*
* RETURN VALUE
*	None.
*
* NOTES
*
* SEE ALSO
*********/

/****f* OpenSM: Forwarding Table/osm_mcast_tbl_delete
* NAME
*	osm_mcast_tbl_delete
*
* DESCRIPTION
*	This destroys and deallocates a Multicast Forwarding Table object.
*
* SYNOPSIS
*/
void osm_mcast_tbl_delete(IN osm_mcast_tbl_t ** pp_tbl);
/*
* PARAMETERS
*	pp_tbl
*		[in] Pointer a Pointer to the Multicast Forwarding Table object.
*
* RETURN VALUE
*	On success, returns a pointer to a new Multicast Forwarding Table object
*	of the specified size.
*	NULL otherwise.
*
* NOTES
*
* SEE ALSO
*********/

/****f* OpenSM: Forwarding Table/osm_mcast_tbl_realloc
* NAME
*	osm_mcast_tbl_realloc
*
* DESCRIPTION
*	This function reallocates the multicast port mask table if necessary.
*
* SYNOPSIS
*/
int osm_mcast_tbl_realloc(IN osm_mcast_tbl_t * p_tbl, IN unsigned mlid_offset);
/*
* PARAMETERS
*
*	p_tbl
*		[in] Pointer to the Multicast Forwarding Table object.
*
*	mlid_offset
*		[in] Offset of MLID being accessed.
*
* RETURN VALUE
*	Returns 0 on success and non-zero value otherwise.
*
* NOTES
*
* SEE ALSO
*/

/****f* OpenSM: Forwarding Table/osm_mcast_tbl_destroy
* NAME
*	osm_mcast_tbl_destroy
*
* DESCRIPTION
*	This destroys and deallocates a Multicast Forwarding Table object.
*
* SYNOPSIS
*/
void osm_mcast_tbl_destroy(IN osm_mcast_tbl_t * p_tbl);
/*
* PARAMETERS
*	p_tbl
*		[in] Pointer to the Multicast Forwarding Table object.
*
* RETURN VALUE
*    None
*
* NOTES
*
* SEE ALSO
*********/

/****f* OpenSM: Forwarding Table/osm_mcast_tbl_set
* NAME
*	osm_mcast_tbl_set
*
* DESCRIPTION
*	Adds the port to the multicast group.
*
* SYNOPSIS
*/
void osm_mcast_tbl_set(IN osm_mcast_tbl_t * p_tbl, IN uint16_t mlid_ho,
		       IN uint8_t port_num);
/*
* PARAMETERS
*	p_tbl
*		[in] Pointer to the Multicast Forwarding Table object.
*
*	mlid_ho
*		[in] MLID value (host order) for which to set the route.
*
*	port_num
*		[in] Port to add to the multicast group.
*
* RETURN VALUE
*	None.
*
* NOTES
*
* SEE ALSO
*********/

/****f* OpenSM: Forwarding Table/osm_mcast_tbl_clear_mlid
* NAME
*	osm_mcast_tbl_clear_mlid
*
* DESCRIPTION
*	Removes all multicast paths for the specified MLID.
*
* SYNOPSIS
*/
void osm_mcast_tbl_clear_mlid(IN osm_mcast_tbl_t * p_tbl, IN uint16_t mlid_ho);
/*
* PARAMETERS
*	p_tbl
*		[in] Pointer to the Multicast Forwarding Table object.
*
*	mlid_ho
*		[in] MLID value (host order) for which to clear.
*
* RETURN VALUE
*	None.
*
* NOTES
*
* SEE ALSO
*********/

/****f* OpenSM: Forwarding Table/osm_mcast_tbl_is_port
* NAME
*	osm_mcast_tbl_is_port
*
* DESCRIPTION
*	Returns TRUE if the port is in the multicast group.
*
* SYNOPSIS
*/
boolean_t osm_mcast_tbl_is_port(IN const osm_mcast_tbl_t * p_tbl,
				IN uint16_t mlid_ho, IN uint8_t port_num);
/*
* PARAMETERS
*	p_tbl
*		[in] Pointer to the Multicast Forwarding Table object.
*
*	mlid_ho
*		[in] MLID value (host order).
*
*	port_num
*		[in] Port number on the switch
*
* RETURN VALUE
*	Returns the port that routes the specified LID.
*
* NOTES
*
* SEE ALSO
*********/

/****f* OpenSM: Forwarding Table/osm_mcast_tbl_is_any_port
* NAME
*	osm_mcast_tbl_is_any_port
*
* DESCRIPTION
*	Returns TRUE if any port is in the multicast group.
*
* SYNOPSIS
*/
boolean_t osm_mcast_tbl_is_any_port(IN const osm_mcast_tbl_t * p_tbl,
				    IN uint16_t mlid_ho);
/*
* PARAMETERS
*	p_tbl
*		[in] Pointer to the Multicast Forwarding Table object.
*
*	mlid_ho
*		[in] MLID value (host order).
*
* RETURN VALUE
*	Returns TRUE if any port is in the multicast group.
*
* NOTES
*
* SEE ALSO
*********/

/****f* OpenSM: Forwarding Table/osm_mcast_tbl_set_block
* NAME
*	osm_mcast_tbl_set_block
*
* DESCRIPTION
*	Copies the specified block into the Multicast Forwarding Table.
*
* SYNOPSIS
*/
ib_api_status_t osm_mcast_tbl_set_block(IN osm_mcast_tbl_t * p_tbl,
					IN const ib_net16_t * p_block,
					IN int16_t block_num,
					IN uint8_t position);
/*
* PARAMETERS
*	p_tbl
*		[in] Pointer to the Multicast Forwarding Table object.
*
*	p_block
*		[in] Pointer to the Forwarding Table block.
*
*	block_num
*		[in] Block number of this block.
*
* RETURN VALUE
*	None.
*
* NOTES
*
* SEE ALSO
*********/

/****f* OpenSM: Forwarding Table/osm_mcast_get_tbl_block
* NAME
*	osm_mcast_get_tbl_block
*
* DESCRIPTION
*	Retrieve a multicast forwarding table block.
*
* SYNOPSIS
*/
boolean_t osm_mcast_tbl_get_block(IN osm_mcast_tbl_t * p_tbl,
				  IN int16_t block_num, IN uint8_t position,
				  OUT ib_net16_t * p_block);
/*
* PARAMETERS
*	p_tbl
*		[in] Pointer to an osm_mcast_tbl_t object.
*
*	p_block
*		[in] Pointer to the Forwarding Table block.
*
*	block_num
*		[in] Block number of this block.
*
*	p_block
*		[out] Pointer to the 32 entry array to store the
*		forwarding table clock specified by block_id.
*
* RETURN VALUES
*	Returns true if there are more blocks necessary to
*	configure all the MLIDs reachable from this switch.
*	FALSE otherwise.
*
* NOTES
*
* SEE ALSO
*********/

/****f* OpenSM: Forwarding Table/osm_mcast_tbl_get_max_block
* NAME
*	osm_mcast_tbl_get_max_block
*
* DESCRIPTION
*	Returns the maximum block ID in this table.
*
* SYNOPSIS
*/
static inline uint16_t osm_mcast_tbl_get_max_block(IN osm_mcast_tbl_t * p_tbl)
{
	return p_tbl->max_block;
}

/*
* PARAMETERS
*	p_tbl
*		[in] Pointer to an osm_mcast_tbl_t object.
*
* RETURN VALUES
*	Returns the maximum block ID in this table.
*
* NOTES
*
* SEE ALSO
*********/

/****f* OpenSM: Forwarding Table/osm_mcast_tbl_get_max_block_in_use
* NAME
*	osm_mcast_tbl_get_max_block_in_use
*
* DESCRIPTION
*	Returns the maximum block ID in use in this table.
*	A value of -1 indicates no blocks are in use.
*
* SYNOPSIS
*/
static inline int16_t
osm_mcast_tbl_get_max_block_in_use(IN osm_mcast_tbl_t * p_tbl)
{
	return (p_tbl->max_block_in_use);
}

/*
* PARAMETERS
*	p_tbl
*		[in] Pointer to an osm_mcast_tbl_t object.
*
* RETURN VALUES
*	Returns the maximum block ID in use in this table.
*	A value of -1 indicates no blocks are in use.
*
* NOTES
*
* SEE ALSO
*********/

/****f* OpenSM: Forwarding Table/osm_mcast_tbl_get_max_position
* NAME
*	osm_mcast_tbl_get_max_position
*
* DESCRIPTION
*	Returns the maximum position in this table.
*
* SYNOPSIS
*/
static inline uint8_t
osm_mcast_tbl_get_max_position(IN osm_mcast_tbl_t * p_tbl)
{
	return (p_tbl->max_position);
}

/*
* PARAMETERS
*	p_tbl
*		[in] Pointer to an osm_mcast_tbl_t object.
*
* RETURN VALUES
*	Returns the maximum position in this table.
*
* NOTES
*
* SEE ALSO
*********/

END_C_DECLS
#endif				/* _OSM_MCAST_TBL_H_ */