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
osm_mtree_node_get_max_children(IN const osm_mtree_node_t * p_mtn)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 */
osm_mtree_node_get_child(IN const osm_mtree_node_t * p_mtn,IN uint8_t child)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 */
osm_mtree_node_get_switch_ptr(IN const osm_mtree_node_t * p_mtn)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