/*
* 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_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;
uint8_t *physp_discovered;
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.
*
* physp_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 bizarre reason.
*
* print_desc
* A printable version of the node description.
*
* physp_discovered
* Array of physp_discovered objects for all ports of this node.
* Each object indiactes whether the port has been discovered
* during the sweep or not. 1 means that the port had been discovered.
*
* physp_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 ** 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 * 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 * p_node,
IN 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 NULL 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 * 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 number of osm_physp ports allocated for this node.
* For switches, it is the number of external physical ports plus
* port 0. For CAs and routers, it is the number of external physical
* ports plus 1.
*
* SYNOPSIS
*/
static inline uint8_t osm_node_get_num_physp(IN const osm_node_t * 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 * p_node,
IN 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 * p_node,
IN 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 * p_node,
IN 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 * p_node,
IN 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 * p_node, uint8_t port_num,
IN const osm_madw_t * p_madw);
/*
* PARAMETERS
* p_node
* [in] Pointer to an osm_node_t object.
*
* port_num
* [in] Local port number.
*
* 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 * 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 * p_node, IN uint8_t port_num,
IN osm_node_t * p_remote_node, IN 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 node 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 * p_node, IN uint8_t port_num,
IN osm_node_t * p_remote_node, IN 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 node 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 * p_node, IN uint8_t port_num,
IN osm_node_t * p_remote_node,
IN 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 node 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 * p_node, IN 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 * p_node,
IN uint8_t port_num,
IN osm_node_t * p_remote_node,
IN 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 node object.
*
* remote_port_num
* [in] Port number in the remote's node through which to
* check this 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_ */