1 /*
2 * Copyright (c) 2004-2008 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_mgrp_t.
39 * This object represents an IBA Multicast Group.
40 * This object is part of the OpenSM family of objects.
41 */
42
43 #ifndef _OSM_MULTICAST_H_
44 #define _OSM_MULTICAST_H_
45
46 #include <iba/ib_types.h>
47 #include <complib/cl_qmap.h>
48 #include <complib/cl_qlist.h>
49 #include <complib/cl_spinlock.h>
50 #include <opensm/osm_base.h>
51 #include <opensm/osm_mtree.h>
52 #include <opensm/osm_mcm_port.h>
53 #include <opensm/osm_subnet.h>
54 #include <opensm/osm_log.h>
55
56 #ifdef __cplusplus
57 # define BEGIN_C_DECLS extern "C" {
58 # define END_C_DECLS }
59 #else /* !__cplusplus */
60 # define BEGIN_C_DECLS
61 # define END_C_DECLS
62 #endif /* __cplusplus */
63
64 BEGIN_C_DECLS
65 /****h* OpenSM/Multicast Group
66 * NAME
67 * Multicast Group
68 *
69 * DESCRIPTION
70 * The Multicast Group encapsulates the information needed by the
71 * OpenSM to manage Multicast Groups. The OpenSM allocates one
72 * Multicast Group object per Multicast Group in the IBA subnet.
73 *
74 * The Multicast Group is not thread safe, thus callers must provide
75 * serialization.
76 *
77 * This object should be treated as opaque and should be
78 * manipulated only through the provided functions.
79 *
80 * AUTHOR
81 * Steve King, Intel
82 *
83 *********/
84 /****s* OpenSM: Multicast Group/osm_mcast_mgr_ctxt_t
85 * NAME
86 * osm_mcast_mgr_ctxt_t
87 *
88 * DESCRIPTION
89 * Struct for passing context arguments to the multicast manager.
90 *
91 * The osm_mcast_mgr_ctxt_t object should be treated as opaque and should
92 * be manipulated only through the provided functions.
93 *
94 * SYNOPSIS
95 */
96 typedef struct osm_mcast_mgr_ctxt {
97 cl_list_item_t list_item;
98 ib_net16_t mlid;
99 osm_mcast_req_type_t req_type;
100 ib_net64_t port_guid;
101 } osm_mcast_mgr_ctxt_t;
102 /*
103 * FIELDS
104 *
105 * mlid
106 * The network ordered LID of this Multicast Group
107 * (must be >= 0xC000).
108 *
109 * req_type
110 * The type of the request that caused this call
111 * (multicast create/join/leave).
112 *
113 * port_guid
114 * The port guid of the port that is being added/removed from
115 * the multicast group due to this call.
116 *
117 * SEE ALSO
118 *********/
119
120 /****s* OpenSM: Multicast Group/osm_mgrp_t
121 * NAME
122 * osm_mgrp_t
123 *
124 * DESCRIPTION
125 * Multicast Group structure.
126 *
127 * The osm_mgrp_t object should be treated as opaque and should
128 * be manipulated only through the provided functions.
129 *
130 * SYNOPSIS
131 */
132 typedef struct osm_mgrp {
133 cl_map_item_t map_item;
134 ib_net16_t mlid;
135 osm_mtree_node_t *p_root;
136 cl_qmap_t mcm_port_tbl;
137 ib_member_rec_t mcmember_rec;
138 boolean_t well_known;
139 boolean_t to_be_deleted;
140 uint32_t last_change_id;
141 uint32_t last_tree_id;
142 unsigned full_members;
143 } osm_mgrp_t;
144 /*
145 * FIELDS
146 * map_item
147 * Map Item for qmap linkage. Must be first element!!
148 *
149 * mlid
150 * The network ordered LID of this Multicast Group (must be
151 * >= 0xC000).
152 *
153 * p_root
154 * Pointer to the root "tree node" in the single spanning tree
155 * for this multicast group. The nodes of the tree represent
156 * switches. Member ports are not represented in the tree.
157 *
158 * mcm_port_tbl
159 * Table (sorted by port GUID) of osm_mcm_port_t objects
160 * representing the member ports of this multicast group.
161 *
162 * mcmember_rec
163 * Holds the parameters of the Multicast Group.
164 *
165 * well_known
166 * Indicates that this is the wellknown multicast group which
167 * is created during the initialization of SM/SA and will be
168 * present even if there are no ports for this group
169 *
170 * to_be_deleted
171 * Since groups are deleted only after re-route we need to
172 * track the fact the group is about to be deleted so we can
173 * track the fact a new join is actually a create request.
174 *
175 * last_change_id
176 * a counter for the number of changes applied to the group.
177 * This counter shuold be incremented on any modification
178 * to the group: joining or leaving of ports.
179 *
180 * last_tree_id
181 * the last change id used for building the current tree.
182 *
183 * SEE ALSO
184 *********/
185
186 /****f* OpenSM: Vendor API/osm_mgrp_func_t
187 * NAME
188 * osm_mgrp_func_t
189 *
190 * DESCRIPTION
191 * Callback for the osm_mgrp_apply_func function.
192 * The callback function must not modify the tree linkage.
193 *
194 * SYNOPSIS
195 */
196 typedef void (*osm_mgrp_func_t) (IN const osm_mgrp_t * const p_mgrp,
197 IN const osm_mtree_node_t * const p_mtn,
198 IN void *context);
199 /*
200 * PARAMETERS
201 * p_mgrp
202 * [in] Pointer to the multicast group object.
203 *
204 * p_mtn
205 * [in] Pointer to the multicast tree node.
206 *
207 * context
208 * [in] User context.
209 *
210 * RETURN VALUES
211 * None.
212 *
213 * NOTES
214 *
215 * SEE ALSO
216 *********/
217
218 /****f* OpenSM: Multicast Group/osm_mgrp_new
219 * NAME
220 * osm_mgrp_new
221 *
222 * DESCRIPTION
223 * Allocates and initializes a Multicast Group for use.
224 *
225 * SYNOPSIS
226 */
227 osm_mgrp_t *osm_mgrp_new(IN const ib_net16_t mlid);
228 /*
229 * PARAMETERS
230 * mlid
231 * [in] Multicast LID for this multicast group.
232 *
233 * RETURN VALUES
234 * IB_SUCCESS if initialization was successful.
235 *
236 * NOTES
237 * Allows calling other Multicast Group methods.
238 *
239 * SEE ALSO
240 * Multicast Group, osm_mgrp_delete
241 *********/
242
243 /****f* OpenSM: Multicast Group/osm_mgrp_delete
244 * NAME
245 * osm_mgrp_delete
246 *
247 * DESCRIPTION
248 * Destroys and deallocates a Multicast Group.
249 *
250 * SYNOPSIS
251 */
252 void osm_mgrp_delete(IN osm_mgrp_t * const p_mgrp);
253 /*
254 * PARAMETERS
255 * p_mgrp
256 * [in] Pointer to an osm_mgrp_t object.
257 *
258 * RETURN VALUES
259 * None.
260 *
261 * NOTES
262 *
263 * SEE ALSO
264 * Multicast Group, osm_mgrp_new
265 *********/
266
267 /****f* OpenSM: Multicast Group/osm_mgrp_is_guid
268 * NAME
269 * osm_mgrp_is_guid
270 *
271 * DESCRIPTION
272 * Indicates if the specified port GUID is a member of the Multicast Group.
273 *
274 * SYNOPSIS
275 */
276 static inline boolean_t
osm_mgrp_is_guid(IN const osm_mgrp_t * const p_mgrp,IN const ib_net64_t port_guid)277 osm_mgrp_is_guid(IN const osm_mgrp_t * const p_mgrp,
278 IN const ib_net64_t port_guid)
279 {
280 return (cl_qmap_get(&p_mgrp->mcm_port_tbl, port_guid) !=
281 cl_qmap_end(&p_mgrp->mcm_port_tbl));
282 }
283
284 /*
285 * PARAMETERS
286 * p_mgrp
287 * [in] Pointer to an osm_mgrp_t object.
288 *
289 * port_guid
290 * [in] Port GUID.
291 *
292 * RETURN VALUES
293 * TRUE if the port GUID is a member of the group,
294 * FALSE otherwise.
295 *
296 * NOTES
297 *
298 * SEE ALSO
299 * Multicast Group
300 *********/
301
302 /****f* OpenSM: Multicast Group/osm_mgrp_is_empty
303 * NAME
304 * osm_mgrp_is_empty
305 *
306 * DESCRIPTION
307 * Indicates if the multicast group has any member ports.
308 *
309 * SYNOPSIS
310 */
osm_mgrp_is_empty(IN const osm_mgrp_t * const p_mgrp)311 static inline boolean_t osm_mgrp_is_empty(IN const osm_mgrp_t * const p_mgrp)
312 {
313 return (cl_qmap_count(&p_mgrp->mcm_port_tbl) == 0);
314 }
315
316 /*
317 * PARAMETERS
318 * p_mgrp
319 * [in] Pointer to an osm_mgrp_t object.
320 *
321 * RETURN VALUES
322 * TRUE if there are no ports in the multicast group.
323 * FALSE otherwise.
324 *
325 * NOTES
326 *
327 * SEE ALSO
328 * Multicast Group
329 *********/
330
331 /****f* OpenSM: Multicast Group/osm_mgrp_get_mlid
332 * NAME
333 * osm_mgrp_get_mlid
334 *
335 * DESCRIPTION
336 * The osm_mgrp_get_mlid function returns the multicast LID of this group.
337 *
338 * SYNOPSIS
339 */
osm_mgrp_get_mlid(IN const osm_mgrp_t * const p_mgrp)340 static inline ib_net16_t osm_mgrp_get_mlid(IN const osm_mgrp_t * const p_mgrp)
341 {
342 return (p_mgrp->mlid);
343 }
344
345 /*
346 * PARAMETERS
347 * p_mgrp
348 * [in] Pointer to an osm_mgrp_t object.
349 *
350 * RETURN VALUES
351 * MLID of the Multicast Group.
352 *
353 * NOTES
354 *
355 * SEE ALSO
356 * Multicast Group
357 *********/
358
359 /****f* OpenSM: Multicast Group/osm_mgrp_add_port
360 * NAME
361 * osm_mgrp_add_port
362 *
363 * DESCRIPTION
364 * Adds a port to the multicast group.
365 *
366 * SYNOPSIS
367 */
368 osm_mcm_port_t *osm_mgrp_add_port(osm_subn_t *subn, osm_log_t *log,
369 IN osm_mgrp_t * const p_mgrp,
370 IN const ib_gid_t * const p_port_gid,
371 IN const uint8_t join_state,
372 IN boolean_t proxy_join);
373 /*
374 * PARAMETERS
375 * p_mgrp
376 * [in] Pointer to an osm_mgrp_t object to initialize.
377 *
378 * p_port_gid
379 * [in] Pointer to the GID of the port to add to the multicast group.
380 *
381 * join_state
382 * [in] The join state for this port in the group.
383 *
384 * RETURN VALUES
385 * IB_SUCCESS
386 * IB_INSUFFICIENT_MEMORY
387 *
388 * NOTES
389 *
390 * SEE ALSO
391 *********/
392
393 /****f* OpenSM: Multicast Group/osm_mgrp_is_port_present
394 * NAME
395 * osm_mgrp_is_port_present
396 *
397 * DESCRIPTION
398 * checks a port from the multicast group.
399 *
400 * SYNOPSIS
401 */
402
403 boolean_t
404 osm_mgrp_is_port_present(IN const osm_mgrp_t * const p_mgrp,
405 IN const ib_net64_t port_guid,
406 OUT osm_mcm_port_t ** const pp_mcm_port);
407 /*
408 * PARAMETERS
409 * p_mgrp
410 * [in] Pointer to an osm_mgrp_t object.
411 *
412 * port_guid
413 * [in] Port guid of the departing port.
414 *
415 * pp_mcm_port
416 * [out] Pointer to a pointer to osm_mcm_port_t
417 * Updated to the member on success or NULLed
418 *
419 * RETURN VALUES
420 * TRUE if port present
421 * FALSE if port is not present.
422 *
423 * NOTES
424 *
425 * SEE ALSO
426 *********/
427
428 /****f* OpenSM: Multicast Group/osm_mgrp_remove_port
429 * NAME
430 * osm_mgrp_remove_port
431 *
432 * DESCRIPTION
433 * Removes a port from the multicast group.
434 *
435 * SYNOPSIS
436 */
437 void
438 osm_mgrp_delete_port(IN osm_subn_t * const p_subn,
439 IN osm_log_t * const p_log,
440 IN osm_mgrp_t * const p_mgrp,
441 IN const ib_net64_t port_guid);
442 /*
443 * PARAMETERS
444 *
445 * p_subn
446 * [in] Pointer to the subnet object
447 *
448 * p_log
449 * [in] The log object pointer
450 *
451 * p_mgrp
452 * [in] Pointer to an osm_mgrp_t object.
453 *
454 * port_guid
455 * [in] Port guid of the departing port.
456 *
457 * RETURN VALUES
458 * None.
459 *
460 * NOTES
461 *
462 * SEE ALSO
463 *********/
464
465 int osm_mgrp_remove_port(osm_subn_t *subn, osm_log_t *log, osm_mgrp_t *mgrp,
466 osm_mcm_port_t *mcm, uint8_t join_state);
467
468 /****f* OpenSM: Multicast Group/osm_mgrp_apply_func
469 * NAME
470 * osm_mgrp_apply_func
471 *
472 * DESCRIPTION
473 * Calls the specified function for each element in the tree.
474 * Elements are passed to the callback function in no particular order.
475 *
476 * SYNOPSIS
477 */
478 void
479 osm_mgrp_apply_func(const osm_mgrp_t * const p_mgrp,
480 osm_mgrp_func_t p_func, void *context);
481 /*
482 * PARAMETERS
483 * p_mgrp
484 * [in] Pointer to an osm_mgrp_t object.
485 *
486 * p_func
487 * [in] Pointer to the users callback function.
488 *
489 * context
490 * [in] User context passed to the callback function.
491 *
492 *
493 * RETURN VALUES
494 * None.
495 *
496 * NOTES
497 *
498 * SEE ALSO
499 * Multicast Group
500 *********/
501
502 END_C_DECLS
503 #endif /* _OSM_MULTICAST_H_ */
504