/*
 * Copyright (c) 2004-2008 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_node_t.
 *	This object represents an IBA node.
 *	This object is part of the OpenSM family of objects.
 */

#ifndef _OSM_NODE_H_
#define _OSM_NODE_H_

#include <complib/cl_qmap.h>
#include <iba/ib_types.h>
#include <opensm/osm_base.h>
#include <opensm/osm_port.h>
#include <opensm/osm_path.h>
#include <opensm/osm_madw.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

struct osm_switch;

/****h* OpenSM/Node
* NAME
*	Node
*
* DESCRIPTION
*	The Node object encapsulates the information needed by the
*	OpenSM to manage nodes.  The OpenSM allocates one Node object
*	per node in the IBA subnet.
*
*	The 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.
*
* AUTHOR
*	Steve King, Intel
*
*********/

/****s* OpenSM: Node/osm_node_t
* NAME
*	osm_node_t
*
* DESCRIPTION
*	Node structure.
*
*	This object should be treated as opaque and should
*	be manipulated only through the provided functions.
*
* SYNOPSIS
*/
typedef struct osm_node {
	cl_map_item_t map_item;
	struct osm_switch *sw;
	ib_node_info_t node_info;
	ib_node_desc_t node_desc;
	uint32_t discovery_count;
	uint32_t physp_tbl_size;
	char *print_desc;
	osm_physp_t physp_table[1];
} osm_node_t;
/*
* FIELDS
*	map_item
*		Linkage structure for cl_qmap.  MUST BE FIRST MEMBER!
*
*	sw
*		For switch node contains pointer to appropriate osm_switch
*		structure. NULL for non-switch nodes. Can be used for fast
*		access to switch object and for simple node type detection
*
*	node_info
*		The IBA defined NodeInfo data for this node.
*
*	node_desc
*		The IBA defined NodeDescription data for this node.
*
*	discovery_count
*		The number of times this node has been discovered
*		during the current fabric sweep.  This number is reset
*		to zero at the start of a sweep.
*
*	phsyp_tbl_size
*		The size of the physp_table array.  This value is one greater
*		than the number of ports in the node, since port numbers
*		start with 1 for some bizzare reason.
*
*	print_desc
*		A printable version of the node description.
*
*	phsyp_table
*		Array of physical port objects belonging to this node.
*		Index is contiguous by local port number.
*		For switches, port 0 is the always the management port (14.2.5.6).
*		MUST BE LAST MEMBER! - Since it grows !!!!
*
* SEE ALSO
*	Node object
*********/

/****f* OpenSM: Node/osm_node_delete
* NAME
*	osm_node_delete
*
* DESCRIPTION
*	The osm_node_delete function destroys a node, releasing
*	all resources.
*
* SYNOPSIS
*/
void osm_node_delete(IN OUT osm_node_t ** const p_node);
/*
* PARAMETERS
*	p_node
*		[in][out] Pointer to a Pointer a Node object to destroy.
*		On return, the pointer to set to NULL.
*
* RETURN VALUE
*	This function does not return a value.
*
* NOTES
*	Performs any necessary cleanup of the specified Node object.
*	This function should only be called after a call to osm_node_new.
*
* SEE ALSO
*	Node object, osm_node_new
*********/

/****f* OpenSM: Node/osm_node_new
* NAME
*	osm_node_new
*
* DESCRIPTION
*	The osm_node_new function initializes a Node object for use.
*
* SYNOPSIS
*/
osm_node_t *osm_node_new(IN const osm_madw_t * const p_madw);
/*
* PARAMETERS
*	p_madw
*		[in] Pointer to a osm_madw_t object containing a mad with
*		the node's NodeInfo attribute.  The caller may discard the
*		osm_madw_t structure after calling osm_node_new.
*
* RETURN VALUES
*	On success, a pointer to the new initialized osm_node_t structure.
*	NULL otherwise.
*
* NOTES
*
* SEE ALSO
*	Node object
*********/

/****f* OpenSM: Node/osm_node_get_physp_ptr
* NAME
*	osm_node_get_physp_ptr
*
* DESCRIPTION
*	Returns a pointer to the physical port object at the
*	specified local port number.
*
* SYNOPSIS
*/
static inline osm_physp_t *osm_node_get_physp_ptr(IN osm_node_t * const p_node,
						  IN const uint32_t port_num)
{

	CL_ASSERT(port_num < p_node->physp_tbl_size);
	return osm_physp_is_valid(&p_node->physp_table[port_num]) ?
		&p_node->physp_table[port_num] : NULL;
}

/*
* PARAMETERS
*	p_node
*		[in] Pointer to an osm_node_t object.
*
*	port_num
*		[in] Local port number.
*
* RETURN VALUES
*	Returns a pointer to the physical port object at the
*	specified local port number.
*	A return value of zero means the port number was out of range.
*
* NOTES
*
* SEE ALSO
*	Node object
*********/

/****f* OpenSM: Node/osm_node_get_type
* NAME
*	osm_node_get_type
*
* DESCRIPTION
*	Returns the type of this node.
*
* SYNOPSIS
*/
static inline uint8_t osm_node_get_type(IN const osm_node_t * const p_node)
{
	return (p_node->node_info.node_type);
}

/*
* PARAMETERS
*	p_node
*		[in] Pointer to an osm_node_t object.
*
* RETURN VALUES
*	Returns the IBA defined type of this node.
*
* NOTES
*
* SEE ALSO
*	Node object
*********/

/****f* OpenSM: Node/osm_node_get_num_physp
* NAME
*	osm_node_get_num_physp
*
* DESCRIPTION
*	Returns the type of this node.
*
* SYNOPSIS
*/
static inline uint8_t osm_node_get_num_physp(IN const osm_node_t * const p_node)
{
	return ((uint8_t) p_node->physp_tbl_size);
}

/*
* PARAMETERS
*	p_node
*		[in] Pointer to an osm_node_t object.
*
* RETURN VALUES
*	Returns the IBA defined type of this node.
*
* NOTES
*
* SEE ALSO
*	Node object
*********/

/****f* OpenSM: Node/osm_node_get_remote_node
* NAME
*	osm_node_get_remote_node
*
* DESCRIPTION
*	Returns a pointer to the node on the other end of the
*	specified port.
*	Returns NULL if no remote node exists.
*
* SYNOPSIS
*/
osm_node_t *osm_node_get_remote_node(IN osm_node_t * const p_node,
				     IN const uint8_t port_num,
				     OUT uint8_t * p_remote_port_num);
/*
* PARAMETERS
*	p_node
*		[in] Pointer to an osm_node_t object.
*
*	port_num
*		[in] Port number in p_node through which to get the remote node.
*
*	p_remote_port_num
*		[out] Port number in the remote's node through which this
*		link exists.  The caller may specify NULL for this pointer
*		if the port number isn't needed.
*
* RETURN VALUES
*	Returns a pointer to the node on the other end of the
*	specified port.
*	Returns NULL if no remote node exists.
*
* NOTES
*
* SEE ALSO
*	Node object
*********/

/****f* OpenSM: Node/osm_node_get_base_lid
* NAME
*	osm_node_get_base_lid
*
* DESCRIPTION
*	Returns the LID value of the specified port on this node.
*
* SYNOPSIS
*/
static inline ib_net16_t
osm_node_get_base_lid(IN const osm_node_t * const p_node,
		      IN const uint32_t port_num)
{
	CL_ASSERT(port_num < p_node->physp_tbl_size);
	return (osm_physp_get_base_lid(&p_node->physp_table[port_num]));
}

/*
* PARAMETERS
*	p_node
*		[in] Pointer to an osm_node_t object.
*
*	port_num
*		[in] Local port number.
*
* RETURN VALUES
*	Returns a pointer to the physical port object at the
*	specified local port number.
*	A return value of zero means the port number was out of range.
*
* NOTES
*
* SEE ALSO
*	Node object
*********/

/****f* OpenSM: Node/osm_node_get_remote_base_lid
* NAME
*	osm_node_get_remote_base_lid
*
* DESCRIPTION
*	Returns the base LID value of the port on the other side
*	of the wire from the specified port on this node.
*
* SYNOPSIS
*/
ib_net16_t
osm_node_get_remote_base_lid(IN osm_node_t * const p_node,
			     IN const uint32_t port_num);
/*
* PARAMETERS
*	p_node
*		[in] Pointer to an osm_node_t object.
*
*	port_num
*		[in] Local port number.
*
* RETURN VALUES
*	Returns a pointer to the physical port object at the
*	specified local port number.
*	A return value of zero means the port number was out of range.
*
* NOTES
*
* SEE ALSO
*	Node object
*********/

/****f* OpenSM: Node/osm_node_get_lmc
* NAME
*	osm_node_get_lmc
*
* DESCRIPTION
*	Returns the LMC value of the specified port on this node.
*
* SYNOPSIS
*/
static inline uint8_t
osm_node_get_lmc(IN const osm_node_t * const p_node, IN const uint32_t port_num)
{
	CL_ASSERT(port_num < p_node->physp_tbl_size);
	return (osm_physp_get_lmc(&p_node->physp_table[port_num]));
}

/*
* PARAMETERS
*	p_node
*		[in] Pointer to an osm_node_t object.
*
*	port_num
*		[in] Local port number.
*
* RETURN VALUES
*	Returns the LMC value of the specified port on this node.
*
* NOTES
*
* SEE ALSO
*	Node object
*********/

/****f* OpenSM: Node/osm_node_init_physp
* NAME
*	osm_node_init_physp
*
* DESCRIPTION
*	Initializes a physical port for the given node.
*
* SYNOPSIS
*/
void
osm_node_init_physp(IN osm_node_t * const p_node,
		    IN const osm_madw_t * const p_madw);
/*
* PARAMETERS
*	p_node
*		[in] Pointer to an osm_node_t object.
*
*	p_madw
*		[in] Pointer to a osm_madw_t object containing a mad with
*		the node's NodeInfo attribute as discovered through the
*		Physical Port to add to the node.  The caller may discard the
*		osm_madw_t structure after calling osm_node_new.
*
* RETURN VALUES
*	None.
*
* NOTES
*
* SEE ALSO
*	Node object, Physical Port object.
*********/

/****f* OpenSM: Node/osm_node_get_node_guid
* NAME
*	osm_node_get_node_guid
*
* DESCRIPTION
*	Returns the node GUID of this node.
*
* SYNOPSIS
*/
static inline ib_net64_t
osm_node_get_node_guid(IN const osm_node_t * const p_node)
{
	return (p_node->node_info.node_guid);
}

/*
* PARAMETERS
*	p_node
*		[in] Pointer to an osm_node_t object.
*
* RETURN VALUES
*	Returns the node GUID of this node.
*
* NOTES
*
* SEE ALSO
*	Node object
*********/

/****f* OpenSM: Node/osm_node_link
* NAME
*	osm_node_link
*
* DESCRIPTION
*	Logically connects a node to another node through the specified port.
*
* SYNOPSIS
*/
void
osm_node_link(IN osm_node_t * const p_node,
	      IN const uint8_t port_num,
	      IN osm_node_t * const p_remote_node,
	      IN const uint8_t remote_port_num);
/*
* PARAMETERS
*	p_node
*		[in] Pointer to an osm_node_t object.
*
*	port_num
*		[in] Port number in p_node through which to create the link.
*
*	p_remote_node
*		[in] Pointer to the remote port object.
*
*	remote_port_num
*		[in] Port number in the remote's node through which to
*		create this link.
*
* RETURN VALUES
*	None.
*
* NOTES
*
* SEE ALSO
*	Node object
*********/

/****f* OpenSM: Node/osm_node_unlink
* NAME
*	osm_node_unlink
*
* DESCRIPTION
*	Logically disconnects a node from another node through
*	the specified port.
*
* SYNOPSIS
*/
void
osm_node_unlink(IN osm_node_t * const p_node,
		IN const uint8_t port_num,
		IN osm_node_t * const p_remote_node,
		IN const uint8_t remote_port_num);
/*
* PARAMETERS
*	p_node
*		[in] Pointer to an osm_node_t object.
*
*	port_num
*		[in] Port number in p_node through which to unlink.
*
*	p_remote_node
*		[in] Pointer to the remote port object.
*
*	remote_port_num
*		[in] Port number in the remote's node through which to unlink.
*
* RETURN VALUES
*	None.
*
* NOTES
*
* SEE ALSO
*	Node object
*********/

/****f* OpenSM: Node/osm_node_link_exists
* NAME
*	osm_node_link_exists
*
* DESCRIPTION
*	Return TRUE if a link exists between the specified nodes on
*	the specified ports.
*	Returns FALSE otherwise.
*
* SYNOPSIS
*/
boolean_t
osm_node_link_exists(IN osm_node_t * const p_node,
		     IN const uint8_t port_num,
		     IN osm_node_t * const p_remote_node,
		     IN const uint8_t remote_port_num);
/*
* PARAMETERS
*	p_node
*		[in] Pointer to an osm_node_t object.
*
*	port_num
*		[in] Port number in p_node through which to check the link.
*
*	p_remote_node
*		[in] Pointer to the remote port object.
*
*	remote_port_num
*		[in] Port number in the remote's node through which to
*		check this link.
*
* RETURN VALUES
*	Return TRUE if a link exists between the specified nodes on
*	the specified ports.
*	Returns FALSE otherwise.
*
* NOTES
*
* SEE ALSO
*	Node object
*********/

/****f* OpenSM: Node/osm_node_has_any_link
* NAME
*	osm_node_has_any_link
*
* DESCRIPTION
*	Return TRUE if a any link exists from the specified nodes on
*	the specified port.
*	Returns FALSE otherwise.
*
* SYNOPSIS
*/
boolean_t
osm_node_has_any_link(IN osm_node_t * const p_node, IN const uint8_t port_num);
/*
* PARAMETERS
*	p_node
*		[in] Pointer to an osm_node_t object.
*
*	port_num
*		[in] Port number in p_node through which to check the link.
*
* RETURN VALUES
*	Return TRUE if a any link exists from the specified nodes on
*	the specified port.
*	Returns FALSE otherwise.
*
* NOTES
*
* SEE ALSO
*	Node object
*********/

/****f* OpenSM: Node/osm_node_link_has_valid_ports
* NAME
*	osm_node_link_has_valid_ports
*
* DESCRIPTION
*	Return TRUE if both ports in the link are valid (initialized).
*	Returns FALSE otherwise.
*
* SYNOPSIS
*/
boolean_t
osm_node_link_has_valid_ports(IN osm_node_t * const p_node,
			      IN const uint8_t port_num,
			      IN osm_node_t * const p_remote_node,
			      IN const uint8_t remote_port_num);
/*
* PARAMETERS
*	p_node
*		[in] Pointer to an osm_node_t object.
*
*	port_num
*		[in] Port number in p_node through which to check the link.
*
* RETURN VALUES
*	Return TRUE if both ports in the link are valid (initialized).
*	Returns FALSE otherwise.
*
* NOTES
*
* SEE ALSO
*	Node object
*********/

END_C_DECLS
#endif				/* _OSM_NODE_H_ */