contrib/ofed/management/opensm/include/opensm/osm_multicast.h

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