1 /* 2 * Copyright (c) 2004-2009 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 const 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 * 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 * 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 p_mtn, 219 IN 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 const osm_switch_t *osm_mtree_node_get_switch_ptr(IN const 251 osm_mtree_node_t * 252 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_ */ 275