/*

 * Copyright (c) 2004-2009 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:

 * 	Declaration of osm_mtree_t.

 *	This object represents multicast spanning tree.

 *	This object is part of the OpenSM family of objects.

 */

#ifndef _OSM_MTREE_H_

#define _OSM_MTREE_H_

#include <iba/ib_types.h>

#include <complib/cl_qmap.h>

#include <opensm/osm_base.h>

#include <opensm/osm_switch.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

#define OSM_MTREE_LEAF ((void*)-1)

/****h* OpenSM/Multicast Tree

* NAME

*	Multicast Tree

*

* DESCRIPTION

*	The Multicast Tree object encapsulates the information needed by the

*	OpenSM to manage multicast fabric routes.  It is a tree structure

*	in which each node in the tree represents a switch, and may have a

*	varying number of children.

*

*	Multicast trees do not contain loops.

*

*	The Multicast Tree is not thread safe, thus callers must provide

*	serialization.

*

*	This object should be treated as opaque and should be

*	manipulated only through the provided functions.

*

* AUTHOR

*	Steve King, Intel

*

*********/

/****s* OpenSM: Multicast Tree/osm_mtree_node_t

* NAME

*	osm_mtree_node_t

*

* DESCRIPTION

*	The MTree Node object encapsulates the information needed by the

*	OpenSM for a particular switch in the multicast tree.

*

*	The MTree Node object is not thread safe, thus callers must provide

*	serialization.

*

*	This object should be treated as opaque and should be

*	manipulated only through the provided functions.

*

* SYNOPSIS

*/

typedef struct osm_mtree_node {

	cl_map_item_t map_item;

	const osm_switch_t *p_sw;

	uint8_t max_children;

	struct osm_mtree_node *p_up;

	struct osm_mtree_node *child_array[1];

} osm_mtree_node_t;

/*

* FIELDS

*	map_item

*		Linkage for quick map.  MUST BE FIRST ELEMENT!!!

*

*	p_sw

*		Pointer to the switch represented by this tree node.

*

*	max_children

*		Maximum number of child nodes of this node.  Equal to the

*		the number of ports on the switch if the switch supports

*		multicast.  Equal to 1 (default route) if the switch does

*		not support multicast.

*

*	p_up

*		Pointer to the parent of this node.  If this pointer is

*		NULL, the node is at the root of the tree.

*

*	child_array

*		Array (indexed by port number) of pointers to the

*		child osm_mtree_node_t objects of this tree node, if any.

*		MUST BE LAST ELEMENT!!!

*

* SEE ALSO

*********/

/****f* OpenSM: Multicast Tree/osm_mtree_node_new

* NAME

*	osm_mtree_node_new

*

* DESCRIPTION

*	Returns an initialized Multicast Tree object for use.

*

* SYNOPSIS

*/

osm_mtree_node_t *osm_mtree_node_new(IN const osm_switch_t * p_sw);

/*

* PARAMETERS

*	p_sw

*		[in] Pointer to the switch represented by this node.

*

* RETURN VALUES

*	Pointer to an initialized tree node.

*

* NOTES

*

* SEE ALSO

*********/

/****f* OpenSM: Multicast Tree/osm_mtree_destroy

* NAME

*	osm_mtree_destroy

*

* DESCRIPTION

*	Destroys a Multicast Tree object given by the p_mtn

*

* SYNOPSIS

*/

void osm_mtree_destroy(IN osm_mtree_node_t * p_mtn);

/*

* PARAMETERS

*	p_mtn

*		[in] Pointer to an osm_mtree_node_t object to destroy.

*

* RETURN VALUES

*	None.

*

* NOTES

*

* SEE ALSO

*********/

/****f* OpenSM: Multicast Tree/osm_mtree_node_get_max_children

* NAME

*	osm_mtree_node_get_max_children

*

* DESCRIPTION

*	Returns the number maximum number of children of this node.

*	The return value is 1 greater than the highest valid port

*	number on the switch.

*

*

* SYNOPSIS

*/

static inline uint8_t

osm_mtree_node_get_max_children(IN const osm_mtree_node_t * p_mtn)

{

	return (p_mtn->max_children);

}

/*

* PARAMETERS

*	p_mtn

*		[in] Pointer to the multicast tree node.

*

* RETURN VALUES

*	See description.

*

* NOTES

*

* SEE ALSO

*********/

/****f* OpenSM: Multicast Tree/osm_mtree_node_get_child

* NAME

*	osm_mtree_node_get_child

*

* DESCRIPTION

*	Returns the specified child node of this node.

*

* SYNOPSIS

*/

static inline osm_mtree_node_t *osm_mtree_node_get_child(IN const

							 osm_mtree_node_t *

							 p_mtn,

							 IN uint8_t child)

{

	CL_ASSERT(child < p_mtn->max_children);

	return (p_mtn->child_array[child]);

}

/*

* PARAMETERS

*	p_mtn

*		[in] Pointer to the multicast tree node.

*

*	child

*		[in] Index of the child to retrieve.

*

* RETURN VALUES

*	Returns the specified child node of this node.

*

*

* NOTES

*

* SEE ALSO

*********/

/****f* OpenSM: Multicast Tree/osm_mtree_node_get_switch_ptr

* NAME

*	osm_mtree_node_get_switch_ptr

*

* DESCRIPTION

*	Returns a pointer to the switch object represented by this tree node.

*

* SYNOPSIS

*/

static inline const osm_switch_t *osm_mtree_node_get_switch_ptr(IN const

							  osm_mtree_node_t *

							  p_mtn)

{

	return p_mtn->p_sw;

}

/*

* PARAMETERS

*	p_mtn

*		[in] Pointer to the multicast tree node.

*

* RETURN VALUES

*	Returns a pointer to the switch object represented by this tree node.

*

*

* NOTES

*

* SEE ALSO

*********/

END_C_DECLS

#endif				/* _OSM_MTREE_H_ */