1 /*
2 * Copyright (c) 2004-2009 Voltaire, Inc. All rights reserved.
3 * Copyright (c) 2002-2012 Mellanox Technologies LTD. All rights reserved.
4 * Copyright (c) 1996-2003 Intel Corporation. All rights reserved.
5 * Copyright (c) 2013 Oracle and/or its affiliates. All rights reserved.
6 *
7 * This software is available to you under a choice of one of two
8 * licenses. You may choose to be licensed under the terms of the GNU
9 * General Public License (GPL) Version 2, available from the file
10 * COPYING in the main directory of this source tree, or the
11 * OpenIB.org BSD license below:
12 *
13 * Redistribution and use in source and binary forms, with or
14 * without modification, are permitted provided that the following
15 * conditions are met:
16 *
17 * - Redistributions of source code must retain the above
18 * copyright notice, this list of conditions and the following
19 * disclaimer.
20 *
21 * - Redistributions in binary form must reproduce the above
22 * copyright notice, this list of conditions and the following
23 * disclaimer in the documentation and/or other materials
24 * provided with the distribution.
25 *
26 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
27 * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
28 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
29 * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
30 * BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
31 * ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
32 * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
33 * SOFTWARE.
34 *
35 */
36
37 /*
38 * Abstract:
39 * Declaration of osm_mgrp_t.
40 * This object represents an IBA Multicast Group.
41 * This object is part of the OpenSM family of objects.
42 */
43
44 #ifndef _OSM_MULTICAST_H_
45 #define _OSM_MULTICAST_H_
46
47 #include <iba/ib_types.h>
48 #include <complib/cl_qmap.h>
49 #include <complib/cl_fleximap.h>
50 #include <complib/cl_qlist.h>
51 #include <complib/cl_spinlock.h>
52 #include <opensm/osm_base.h>
53 #include <opensm/osm_mtree.h>
54 #include <opensm/osm_mcm_port.h>
55 #include <opensm/osm_subnet.h>
56 #include <opensm/osm_log.h>
57 #include <opensm/osm_sm.h>
58
59 #ifdef __cplusplus
60 # define BEGIN_C_DECLS extern "C" {
61 # define END_C_DECLS }
62 #else /* !__cplusplus */
63 # define BEGIN_C_DECLS
64 # define END_C_DECLS
65 #endif /* __cplusplus */
66
67 BEGIN_C_DECLS
68 /****h* OpenSM/Multicast Group
69 * NAME
70 * Multicast Group
71 *
72 * DESCRIPTION
73 * The Multicast Group encapsulates the information needed by the
74 * OpenSM to manage Multicast Groups. The OpenSM allocates one
75 * Multicast Group object per Multicast Group in the IBA subnet.
76 *
77 * The Multicast Group is not thread safe, thus callers must provide
78 * serialization.
79 *
80 * This object should be treated as opaque and should be
81 * manipulated only through the provided functions.
82 *
83 * AUTHOR
84 * Steve King, Intel
85 *
86 *********/
87
88 /****s* OpenSM: Multicast Group/osm_mgrp_t
89 * NAME
90 * osm_mgrp_t
91 *
92 * DESCRIPTION
93 * Multicast Group structure.
94 *
95 * The osm_mgrp_t object should be treated as opaque and should
96 * be manipulated only through the provided functions.
97 *
98 * SYNOPSIS
99 */
100 typedef struct osm_mgrp {
101 cl_fmap_item_t map_item;
102 cl_list_item_t list_item;
103 ib_net16_t mlid;
104 cl_qmap_t mcm_port_tbl;
105 cl_qmap_t mcm_alias_port_tbl;
106 ib_member_rec_t mcmember_rec;
107 boolean_t well_known;
108 unsigned full_members;
109 } osm_mgrp_t;
110 /*
111 * FIELDS
112 * map_item
113 * Map Item for fmap linkage. Must be first element!!
114 *
115 * list_item
116 * List item for linkage in osm_mgrp_box's mgrp_list qlist.
117 *
118 * mlid
119 * The network ordered LID of this Multicast Group (must be
120 * >= 0xC000).
121 *
122 * mcm_port_tbl
123 * Table (sorted by port GUID) of osm_mcm_port_t objects
124 * representing the member ports of this multicast group.
125 *
126 * mcm_alias_port_tbl
127 * Table (sorted by port alias GUID) of osm_mcm_port_t
128 * objects representing the member ports of this multicast
129 * group.
130 *
131 * mcmember_rec
132 * Holds the parameters of the Multicast Group.
133 *
134 * well_known
135 * Indicates that this is the wellknown multicast group which
136 * is created during the initialization of SM/SA and will be
137 * present even if there are no ports for this group
138 *
139 * SEE ALSO
140 *********/
141
142 /****s* OpenSM: Multicast Group/osm_mgrp_box_t
143 * NAME
144 * osm_mgrp_box_t
145 *
146 * DESCRIPTION
147 * Multicast structure which holds all multicast groups with same MLID.
148 *
149 * SYNOPSIS
150 */
151 typedef struct osm_mgrp_box {
152 uint16_t mlid;
153 cl_qlist_t mgrp_list;
154 osm_mtree_node_t *root;
155 } osm_mgrp_box_t;
156 /*
157 * FIELDS
158 * mlid
159 * The host ordered LID of this Multicast Group (must be
160 * >= 0xC000).
161 *
162 * p_root
163 * Pointer to the root "tree node" in the single spanning tree
164 * for this multicast group. The nodes of the tree represent
165 * switches. Member ports are not represented in the tree.
166 *
167 * mgrp_list
168 * List of multicast groups (mpgr object) having same MLID value.
169 *
170 * SEE ALSO
171 *********/
172
173 /****f* OpenSM: Multicast Group/osm_mgrp_new
174 * NAME
175 * osm_mgrp_new
176 *
177 * DESCRIPTION
178 * Allocates and initializes a Multicast Group for use.
179 *
180 * SYNOPSIS
181 */
182 osm_mgrp_t *osm_mgrp_new(IN osm_subn_t * subn, IN ib_net16_t mlid,
183 IN ib_member_rec_t * mcmr);
184 /*
185 * PARAMETERS
186 * subn
187 * [in] Pointer to osm_subn_t object.
188 *
189 * mlid
190 * [in] Multicast LID for this multicast group.
191 *
192 * mcmr
193 * [in] MCMember Record for this multicast group.
194 *
195 * RETURN VALUES
196 * IB_SUCCESS if initialization was successful.
197 *
198 * NOTES
199 * Allows calling other Multicast Group methods.
200 *
201 * SEE ALSO
202 * Multicast Group, osm_mgrp_delete
203 *********/
204
205 /*
206 * Need a forward declaration to work around include loop:
207 * osm_sm.h <- osm_multicast.h
208 */
209 struct osm_sm;
210
211 /****f* OpenSM: Multicast Tree/osm_purge_mtree
212 * NAME
213 * osm_purge_mtree
214 *
215 * DESCRIPTION
216 * Frees all the nodes in a multicast spanning tree
217 *
218 * SYNOPSIS
219 */
220 void osm_purge_mtree(IN struct osm_sm * sm, IN osm_mgrp_box_t * mgb);
221 /*
222 * PARAMETERS
223 * sm
224 * [in] Pointer to osm_sm_t object.
225 * mgb
226 * [in] Pointer to an osm_mgrp_box_t object.
227 *
228 * RETURN VALUES
229 * None.
230 *
231 *
232 * NOTES
233 *
234 * SEE ALSO
235 *********/
236
237 /****f* OpenSM: Multicast Group/osm_mgrp_is_guid
238 * NAME
239 * osm_mgrp_is_guid
240 *
241 * DESCRIPTION
242 * Indicates if the specified port GUID is a member of the Multicast Group.
243 *
244 * SYNOPSIS
245 */
osm_mgrp_is_guid(IN const osm_mgrp_t * p_mgrp,IN ib_net64_t port_guid)246 static inline boolean_t osm_mgrp_is_guid(IN const osm_mgrp_t * p_mgrp,
247 IN ib_net64_t port_guid)
248 {
249 return (cl_qmap_get(&p_mgrp->mcm_port_tbl, port_guid) !=
250 cl_qmap_end(&p_mgrp->mcm_port_tbl));
251 }
252
253 /*
254 * PARAMETERS
255 * p_mgrp
256 * [in] Pointer to an osm_mgrp_t object.
257 *
258 * port_guid
259 * [in] Port GUID.
260 *
261 * RETURN VALUES
262 * TRUE if the port GUID is a member of the group,
263 * FALSE otherwise.
264 *
265 * NOTES
266 *
267 * SEE ALSO
268 * Multicast Group
269 *********/
270
271 /****f* OpenSM: Multicast Group/osm_mgrp_is_empty
272 * NAME
273 * osm_mgrp_is_empty
274 *
275 * DESCRIPTION
276 * Indicates if the multicast group has any member ports.
277 *
278 * SYNOPSIS
279 */
osm_mgrp_is_empty(IN const osm_mgrp_t * p_mgrp)280 static inline boolean_t osm_mgrp_is_empty(IN const osm_mgrp_t * p_mgrp)
281 {
282 return (cl_qmap_count(&p_mgrp->mcm_port_tbl) == 0);
283 }
284
285 /*
286 * PARAMETERS
287 * p_mgrp
288 * [in] Pointer to an osm_mgrp_t object.
289 *
290 * RETURN VALUES
291 * TRUE if there are no ports in the multicast group.
292 * FALSE otherwise.
293 *
294 * NOTES
295 *
296 * SEE ALSO
297 * Multicast Group
298 *********/
299
300 /****f* OpenSM: Multicast Group/osm_mgrp_get_mlid
301 * NAME
302 * osm_mgrp_get_mlid
303 *
304 * DESCRIPTION
305 * The osm_mgrp_get_mlid function returns the multicast LID of this group.
306 *
307 * SYNOPSIS
308 */
osm_mgrp_get_mlid(IN const osm_mgrp_t * p_mgrp)309 static inline ib_net16_t osm_mgrp_get_mlid(IN const osm_mgrp_t * p_mgrp)
310 {
311 return p_mgrp->mlid;
312 }
313
314 /*
315 * PARAMETERS
316 * p_mgrp
317 * [in] Pointer to an osm_mgrp_t object.
318 *
319 * RETURN VALUES
320 * MLID of the Multicast Group.
321 *
322 * NOTES
323 *
324 * SEE ALSO
325 * Multicast Group
326 *********/
327
328 /****f* OpenSM: Multicast Group/osm_mgrp_add_port
329 * NAME
330 * osm_mgrp_add_port
331 *
332 * DESCRIPTION
333 * Adds a port to the multicast group.
334 *
335 * SYNOPSIS
336 */
337 osm_mcm_port_t *osm_mgrp_add_port(osm_subn_t *subn, osm_log_t *log,
338 IN osm_mgrp_t * mgrp, IN osm_port_t *port,
339 IN ib_member_rec_t *mcmr, IN boolean_t proxy);
340 /*
341 * PARAMETERS
342 * mgrp
343 * [in] Pointer to an osm_mgrp_t object to initialize.
344 *
345 * port
346 * [in] Pointer to an osm_port_t object
347 *
348 * mcmr
349 * [in] Pointer to MCMember record received for the join
350 *
351 * proxy
352 * [in] The proxy join state for this port in the group.
353 *
354 * RETURN VALUES
355 * IB_SUCCESS
356 * IB_INSUFFICIENT_MEMORY
357 *
358 * NOTES
359 *
360 * SEE ALSO
361 *********/
362
363 /****f* OpenSM: Multicast Group/osm_mgrp_get_mcm_port
364 * NAME
365 * osm_mgrp_get_mcm_port
366 *
367 * DESCRIPTION
368 * Finds a port in the multicast group.
369 *
370 * SYNOPSIS
371 */
372 osm_mcm_port_t *osm_mgrp_get_mcm_port(IN const osm_mgrp_t * p_mgrp,
373 IN ib_net64_t port_guid);
374 /*
375 * PARAMETERS
376 * p_mgrp
377 * [in] Pointer to an osm_mgrp_t object.
378 *
379 * port_guid
380 * [in] Port guid.
381 *
382 * RETURN VALUES
383 * Pointer to the mcm port object when present or NULL otherwise.
384 *
385 * NOTES
386 *
387 * SEE ALSO
388 *********/
389
390 /****f* OpenSM: Multicast Group/osm_mgrp_get_mcm_alias_guid
391 * NAME
392 * osm_mgrp_get_mcm_alias_guid
393 *
394 * DESCRIPTION
395 * Finds an mcm alias GUID in the multicast group based on an alias GUID.
396 *
397 * SYNOPSIS
398 */
399 osm_mcm_alias_guid_t *osm_mgrp_get_mcm_alias_guid(IN const osm_mgrp_t * p_mgrp,
400 IN ib_net64_t port_guid);
401 /*
402 * PARAMETERS
403 * p_mgrp
404 * [in] Pointer to an osm_mgrp_t object.
405 *
406 * port_guid
407 * [in] Alias port guid.
408 *
409 * RETURN VALUES
410 * Pointer to the mcm alias GUID object when present or NULL otherwise.
411 *
412 * NOTES
413 *
414 * SEE ALSO
415 *********/
416
417 /****f* OpenSM: Multicast Group/osm_mgrp_delete_port
418 * NAME
419 * osm_mgrp_delete_port
420 *
421 * DESCRIPTION
422 * Removes a port from the multicast group.
423 *
424 * SYNOPSIS
425 */
426 void osm_mgrp_delete_port(IN osm_subn_t * subn, IN osm_log_t * log,
427 IN osm_mgrp_t * mgrp, IN osm_port_t * port);
428 /*
429 * PARAMETERS
430 *
431 * subn
432 * [in] Pointer to the subnet object
433 *
434 * log
435 * [in] The log object pointer
436 *
437 * mgrp
438 * [in] Pointer to an osm_mgrp_t object.
439 *
440 * port
441 * [in] Pointer to an osm_port_t object for the the departing port.
442 *
443 * RETURN VALUES
444 * None.
445 *
446 * NOTES
447 *
448 * SEE ALSO
449 *********/
450
451 boolean_t osm_mgrp_remove_port(osm_subn_t * subn, osm_log_t * log, osm_mgrp_t * mgrp,
452 osm_mcm_alias_guid_t * mcm_alias_guid,
453 ib_member_rec_t * mcmr);
454 void osm_mgrp_cleanup(osm_subn_t * subn, osm_mgrp_t * mpgr);
455 void osm_mgrp_box_delete(osm_mgrp_box_t *mbox);
456
457 END_C_DECLS
458 #endif /* _OSM_MULTICAST_H_ */
459