contrib/ofed/management/opensm/include/opensm/osm_mtree.h

   1 /*
   2  * Copyright (c) 2004-2006 Voltaire, Inc. All rights reserved.
   3  * Copyright (c) 2002-2005 Mellanox Technologies LTD. All rights reserved.
   4  * Copyright (c) 1996-2003 Intel Corporation. All rights reserved.
   5  *
   6  * This software is available to you under a choice of one of two
   7  * licenses.  You may choose to be licensed under the terms of the GNU
   8  * General Public License (GPL) Version 2, available from the file
   9  * COPYING in the main directory of this source tree, or the
  10  * OpenIB.org BSD license below:
  11  *
  12  *     Redistribution and use in source and binary forms, with or
  13  *     without modification, are permitted provided that the following
  14  *     conditions are met:
  15  *
  16  *      - Redistributions of source code must retain the above
  17  *        copyright notice, this list of conditions and the following
  18  *        disclaimer.
  19  *
  20  *      - Redistributions in binary form must reproduce the above
  21  *        copyright notice, this list of conditions and the following
  22  *        disclaimer in the documentation and/or other materials
  23  *        provided with the distribution.
  24  *
  25  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
  26  * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
  27  * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
  28  * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
  29  * BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
  30  * ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
  31  * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
  32  * SOFTWARE.
  33  *
  34  */
  35
  36 /*
  37  * Abstract:
  38  *      Declaration of osm_mtree_t.
  39  *      This object represents multicast spanning tree.
  40  *      This object is part of the OpenSM family of objects.
  41  */
  42
  43 #ifndef _OSM_MTREE_H_
  44 #define _OSM_MTREE_H_
  45
  46 #include <iba/ib_types.h>
  47 #include <complib/cl_qmap.h>
  48 #include <opensm/osm_base.h>
  49 #include <opensm/osm_switch.h>
  50
  51 #ifdef __cplusplus
  52 #  define BEGIN_C_DECLS extern "C" {
  53 #  define END_C_DECLS   }
  54 #else                           /* !__cplusplus */
  55 #  define BEGIN_C_DECLS
  56 #  define END_C_DECLS
  57 #endif                          /* __cplusplus */
  58
  59 BEGIN_C_DECLS
  60 #define OSM_MTREE_LEAF ((void*)-1)
  61 /****h* OpenSM/Multicast Tree
  62 * NAME
  63 *       Multicast Tree
  64 *
  65 * DESCRIPTION
  66 *       The Multicast Tree object encapsulates the information needed by the
  67 *       OpenSM to manage multicast fabric routes.  It is a tree structure
  68 *       in which each node in the tree represents a switch, and may have a
  69 *       varying number of children.
  70 *
  71 *       Multicast trees do not contain loops.
  72 *
  73 *       The Multicast Tree is not thread safe, thus callers must provide
  74 *       serialization.
  75 *
  76 *       This object should be treated as opaque and should be
  77 *       manipulated only through the provided functions.
  78 *
  79 * AUTHOR
  80 *       Steve King, Intel
  81 *
  82 *********/
  83 /****s* OpenSM: Multicast Tree/osm_mtree_node_t
  84 * NAME
  85 *       osm_mtree_node_t
  86 *
  87 * DESCRIPTION
  88 *       The MTree Node object encapsulates the information needed by the
  89 *       OpenSM for a particular switch in the multicast tree.
  90 *
  91 *       The MTree Node object is not thread safe, thus callers must provide
  92 *       serialization.
  93 *
  94 *       This object should be treated as opaque and should be
  95 *       manipulated only through the provided functions.
  96 *
  97 * SYNOPSIS
  98 */
  99 typedef struct osm_mtree_node {
 100         cl_map_item_t map_item;
 101         osm_switch_t *p_sw;
 102         uint8_t max_children;
 103         struct osm_mtree_node *p_up;
 104         struct osm_mtree_node *child_array[1];
 105 } osm_mtree_node_t;
 106 /*
 107 * FIELDS
 108 *       map_item
 109 *               Linkage for quick map.  MUST BE FIRST ELEMENT!!!
 110 *
 111 *       p_sw
 112 *               Pointer to the switch represented by this tree node.
 113 *
 114 *       max_children
 115 *               Maximum number of child nodes of this node.  Equal to the
 116 *               the number of ports on the switch if the switch supports
 117 *               multicast.  Equal to 1 (default route) if the switch does
 118 *               not support multicast.
 119 *
 120 *       p_up
 121 *               Pointer to the parent of this node.  If this pointer is
 122 *               NULL, the node is at the root of the tree.
 123 *
 124 *       child_array
 125 *               Array (indexed by port number) of pointers to the
 126 *               child osm_mtree_node_t objects of this tree node, if any.
 127 *
 128 * SEE ALSO
 129 *********/
 130
 131 /****f* OpenSM: Multicast Tree/osm_mtree_node_new
 132 * NAME
 133 *       osm_mtree_node_new
 134 *
 135 * DESCRIPTION
 136 *       Returns an initialized a Multicast Tree object for use.
 137 *
 138 * SYNOPSIS
 139 */
 140 osm_mtree_node_t *osm_mtree_node_new(IN const osm_switch_t * const p_sw);
 141 /*
 142 * PARAMETERS
 143 *       p_sw
 144 *               [in] Pointer to the switch represented by this node.
 145 *
 146 * RETURN VALUES
 147 *       Pointer to an initialized tree node.
 148 *
 149 * NOTES
 150 *
 151 * SEE ALSO
 152 *********/
 153
 154 /****f* OpenSM: Multicast Tree/osm_mtree_destroy
 155 * NAME
 156 *       osm_mtree_destroy
 157 *
 158 * DESCRIPTION
 159 *       Destroys a Multicast Tree object given by the p_mtn
 160 *
 161 * SYNOPSIS
 162 */
 163 void osm_mtree_destroy(IN osm_mtree_node_t * p_mtn);
 164 /*
 165 * PARAMETERS
 166 *       p_mtn
 167 *               [in] Pointer to an osm_mtree_node_t object to destroy.
 168 *
 169 * RETURN VALUES
 170 *       None.
 171 *
 172 * NOTES
 173 *
 174 * SEE ALSO
 175 *********/
 176
 177 /****f* OpenSM: Multicast Tree/osm_mtree_node_get_max_children
 178 * NAME
 179 *       osm_mtree_node_get_max_children
 180 *
 181 * DESCRIPTION
 182 *       Returns the number maximum number of children of this node.
 183 *       The return value is 1 greater than the highest valid port
 184 *       number on the switch.
 185 *
 186 *
 187 * SYNOPSIS
 188 */
 189 static inline uint8_t
 190 osm_mtree_node_get_max_children(IN const osm_mtree_node_t * const p_mtn)
 191 {
 192         return (p_mtn->max_children);
 193 }
 194 /*
 195 * PARAMETERS
 196 *       p_mtn
 197 *               [in] Pointer to the multicast tree node.
 198 *
 199 * RETURN VALUES
 200 *       See description.
 201 *
 202 * NOTES
 203 *
 204 * SEE ALSO
 205 *********/
 206
 207 /****f* OpenSM: Multicast Tree/osm_mtree_node_get_child
 208 * NAME
 209 *       osm_mtree_node_get_child
 210 *
 211 * DESCRIPTION
 212 *       Returns the specified child node of this node.
 213 *
 214 * SYNOPSIS
 215 */
 216 static inline osm_mtree_node_t *osm_mtree_node_get_child(IN const
 217                                                          osm_mtree_node_t *
 218                                                          const p_mtn,
 219                                                          IN const uint8_t child)
 220 {
 221         CL_ASSERT(child < p_mtn->max_children);
 222         return (p_mtn->child_array[child]);
 223 }
 224 /*
 225 * PARAMETERS
 226 *       p_mtn
 227 *               [in] Pointer to the multicast tree node.
 228 *
 229 *       child
 230 *               [in] Index of the child to retrieve.
 231 *
 232 * RETURN VALUES
 233 *       Returns the specified child node of this node.
 234 *
 235 *
 236 * NOTES
 237 *
 238 * SEE ALSO
 239 *********/
 240
 241 /****f* OpenSM: Multicast Tree/osm_mtree_node_get_switch_ptr
 242 * NAME
 243 *       osm_mtree_node_get_switch_ptr
 244 *
 245 * DESCRIPTION
 246 *       Returns a pointer to the switch object represented by this tree node.
 247 *
 248 * SYNOPSIS
 249 */
 250 static inline osm_switch_t *osm_mtree_node_get_switch_ptr(IN const
 251                                                           osm_mtree_node_t *
 252                                                           const p_mtn)
 253 {
 254         return (p_mtn->p_sw);
 255 }
 256 /*
 257 * PARAMETERS
 258 *       p_mtn
 259 *               [in] Pointer to the multicast tree node.
 260 *
 261 *       child
 262 *               [in] Index of the child to retrieve.
 263 *
 264 * RETURN VALUES
 265 *       Returns a pointer to the switch object represented by this tree node.
 266 *
 267 *
 268 * NOTES
 269 *
 270 * SEE ALSO
 271 *********/
 272
 273 END_C_DECLS
 274 #endif                          /* _OSM_MTREE_H_ */