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 */ 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 */ 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 */ 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