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.
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:
12 * Redistribution and use in source and binary forms, with or
13 * without modification, are permitted provided that the following
16 * - Redistributions of source code must retain the above
17 * copyright notice, this list of conditions and the following
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.
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
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.
43 #ifndef _OSM_MULTICAST_H_
44 #define _OSM_MULTICAST_H_
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>
57 # define BEGIN_C_DECLS extern "C" {
58 # define END_C_DECLS }
59 #else /* !__cplusplus */
60 # define BEGIN_C_DECLS
62 #endif /* __cplusplus */
65 /****h* OpenSM/Multicast Group
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.
74 * The Multicast Group is not thread safe, thus callers must provide
77 * This object should be treated as opaque and should be
78 * manipulated only through the provided functions.
84 /****s* OpenSM: Multicast Group/osm_mcast_mgr_ctxt_t
86 * osm_mcast_mgr_ctxt_t
89 * Struct for passing context arguments to the multicast manager.
91 * The osm_mcast_mgr_ctxt_t object should be treated as opaque and should
92 * be manipulated only through the provided functions.
96 typedef struct osm_mcast_mgr_ctxt {
97 cl_list_item_t list_item;
99 osm_mcast_req_type_t req_type;
100 ib_net64_t port_guid;
101 } osm_mcast_mgr_ctxt_t;
106 * The network ordered LID of this Multicast Group
107 * (must be >= 0xC000).
110 * The type of the request that caused this call
111 * (multicast create/join/leave).
114 * The port guid of the port that is being added/removed from
115 * the multicast group due to this call.
120 /****s* OpenSM: Multicast Group/osm_mgrp_t
125 * Multicast Group structure.
127 * The osm_mgrp_t object should be treated as opaque and should
128 * be manipulated only through the provided functions.
132 typedef struct osm_mgrp {
133 cl_map_item_t map_item;
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;
147 * Map Item for qmap linkage. Must be first element!!
150 * The network ordered LID of this Multicast Group (must be
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.
159 * Table (sorted by port GUID) of osm_mcm_port_t objects
160 * representing the member ports of this multicast group.
163 * Holds the parameters of the Multicast Group.
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
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.
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.
181 * the last change id used for building the current tree.
186 /****f* OpenSM: Vendor API/osm_mgrp_func_t
191 * Callback for the osm_mgrp_apply_func function.
192 * The callback function must not modify the tree linkage.
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,
202 * [in] Pointer to the multicast group object.
205 * [in] Pointer to the multicast tree node.
218 /****f* OpenSM: Multicast Group/osm_mgrp_new
223 * Allocates and initializes a Multicast Group for use.
227 osm_mgrp_t *osm_mgrp_new(IN const ib_net16_t mlid);
231 * [in] Multicast LID for this multicast group.
234 * IB_SUCCESS if initialization was successful.
237 * Allows calling other Multicast Group methods.
240 * Multicast Group, osm_mgrp_delete
243 /****f* OpenSM: Multicast Group/osm_mgrp_delete
248 * Destroys and deallocates a Multicast Group.
252 void osm_mgrp_delete(IN osm_mgrp_t * const p_mgrp);
256 * [in] Pointer to an osm_mgrp_t object.
264 * Multicast Group, osm_mgrp_new
267 /****f* OpenSM: Multicast Group/osm_mgrp_is_guid
272 * Indicates if the specified port GUID is a member of the Multicast Group.
276 static inline boolean_t
277 osm_mgrp_is_guid(IN const osm_mgrp_t * const p_mgrp,
278 IN const ib_net64_t port_guid)
280 return (cl_qmap_get(&p_mgrp->mcm_port_tbl, port_guid) !=
281 cl_qmap_end(&p_mgrp->mcm_port_tbl));
287 * [in] Pointer to an osm_mgrp_t object.
293 * TRUE if the port GUID is a member of the group,
302 /****f* OpenSM: Multicast Group/osm_mgrp_is_empty
307 * Indicates if the multicast group has any member ports.
311 static inline boolean_t osm_mgrp_is_empty(IN const osm_mgrp_t * const p_mgrp)
313 return (cl_qmap_count(&p_mgrp->mcm_port_tbl) == 0);
319 * [in] Pointer to an osm_mgrp_t object.
322 * TRUE if there are no ports in the multicast group.
331 /****f* OpenSM: Multicast Group/osm_mgrp_get_mlid
336 * The osm_mgrp_get_mlid function returns the multicast LID of this group.
340 static inline ib_net16_t osm_mgrp_get_mlid(IN const osm_mgrp_t * const p_mgrp)
342 return (p_mgrp->mlid);
348 * [in] Pointer to an osm_mgrp_t object.
351 * MLID of the Multicast Group.
359 /****f* OpenSM: Multicast Group/osm_mgrp_add_port
364 * Adds a port to the multicast group.
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);
376 * [in] Pointer to an osm_mgrp_t object to initialize.
379 * [in] Pointer to the GID of the port to add to the multicast group.
382 * [in] The join state for this port in the group.
386 * IB_INSUFFICIENT_MEMORY
393 /****f* OpenSM: Multicast Group/osm_mgrp_is_port_present
395 * osm_mgrp_is_port_present
398 * checks a port from the multicast group.
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);
410 * [in] Pointer to an osm_mgrp_t object.
413 * [in] Port guid of the departing port.
416 * [out] Pointer to a pointer to osm_mcm_port_t
417 * Updated to the member on success or NULLed
420 * TRUE if port present
421 * FALSE if port is not present.
428 /****f* OpenSM: Multicast Group/osm_mgrp_remove_port
430 * osm_mgrp_remove_port
433 * Removes a port from the multicast group.
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);
446 * [in] Pointer to the subnet object
449 * [in] The log object pointer
452 * [in] Pointer to an osm_mgrp_t object.
455 * [in] Port guid of the departing port.
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);
468 /****f* OpenSM: Multicast Group/osm_mgrp_apply_func
470 * osm_mgrp_apply_func
473 * Calls the specified function for each element in the tree.
474 * Elements are passed to the callback function in no particular order.
479 osm_mgrp_apply_func(const osm_mgrp_t * const p_mgrp,
480 osm_mgrp_func_t p_func, void *context);
484 * [in] Pointer to an osm_mgrp_t object.
487 * [in] Pointer to the users callback function.
490 * [in] User context passed to the callback function.
503 #endif /* _OSM_MULTICAST_H_ */