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

   1 /*
   2  * Copyright (c) 2004, 2005 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_mcast_tbl_t.
  39  *      This object represents a multicast forwarding table.
  40  *      This object is part of the OpenSM family of objects.
  41  */
  42
  43 #ifndef _OSM_MCAST_TBL_H_
  44 #define _OSM_MCAST_TBL_H_
  45
  46 #include <iba/ib_types.h>
  47 #include <complib/cl_qmap.h>
  48 #include <opensm/osm_base.h>
  49
  50 #ifdef __cplusplus
  51 #  define BEGIN_C_DECLS extern "C" {
  52 #  define END_C_DECLS   }
  53 #else                           /* !__cplusplus */
  54 #  define BEGIN_C_DECLS
  55 #  define END_C_DECLS
  56 #endif                          /* __cplusplus */
  57
  58 BEGIN_C_DECLS
  59 /****s* OpenSM: Forwarding Table/osm_mcast_tbl_t
  60 * NAME
  61 *       osm_mcast_tbl_t
  62 *
  63 * DESCRIPTION
  64 *       Multicast Forwarding Table structure.
  65 *
  66 *       Callers may directly access this object.
  67 *
  68 * SYNOPSIS
  69 */
  70 typedef struct osm_mcast_fwdbl {
  71         uint8_t num_ports;
  72         uint8_t max_position;
  73         uint16_t max_block;
  74         int16_t max_block_in_use;
  75         uint16_t num_entries;
  76         uint16_t max_mlid_ho;
  77         uint16_t(*p_mask_tbl)[][IB_MCAST_POSITION_MAX];
  78 } osm_mcast_tbl_t;
  79 /*
  80 * FIELDS
  81 *       num_ports
  82 *               The number of ports in the port mask.  This value
  83 *               is the same as the number of ports on the switch
  84 *
  85 *       max_position
  86 *               Maximum bit mask position for this table.  This value
  87 *               is computed from the number of ports on the switch.
  88 *
  89 *       max_block
  90 *               Maximum block number supported in the table.  This value
  91 *               is approximately the number of MLID entries divided by the
  92 *               number of MLIDs per block
  93 *
  94 *       num_entries
  95 *               Number of entries in the table (aka number of MLIDs supported).
  96 *
  97 *       max_mlid_ho
  98 *               Maximum MLID value (host order).
  99 *
 100 *       pp_mask_tbl
 101 *               Pointer to a two dimensional array of port_masks for this switch.
 102 *               The first dimension is MLID, the second dimension is mask position.
 103 *               This pointer is null for switches that do not support multicast.
 104 *
 105 * SEE ALSO
 106 *********/
 107
 108 /****f* OpenSM: Forwarding Table/osm_mcast_tbl_init
 109 * NAME
 110 *       osm_mcast_tbl_init
 111 *
 112 * DESCRIPTION
 113 *       This function initializes a Multicast Forwarding Table object.
 114 *
 115 * SYNOPSIS
 116 */
 117 ib_api_status_t
 118 osm_mcast_tbl_init(IN osm_mcast_tbl_t * const p_tbl,
 119                    IN uint8_t const num_ports, IN uint16_t const capacity);
 120 /*
 121 * PARAMETERS
 122 *       num_ports
 123 *               [in] Number of ports in the switch owning this table.
 124 *
 125 *       capacity
 126 *               [in] The number of MLID entries (starting at 0xC000) supported
 127 *               by this switch.
 128 *
 129 * RETURN VALUE
 130 *       IB_SUCCESS on success.
 131 *
 132 * NOTES
 133 *
 134 * SEE ALSO
 135 *********/
 136
 137 /****f* OpenSM: Forwarding Table/osm_mcast_tbl_delete
 138 * NAME
 139 *       osm_mcast_tbl_delete
 140 *
 141 * DESCRIPTION
 142 *       This destroys and deallocates a Multicast Forwarding Table object.
 143 *
 144 * SYNOPSIS
 145 */
 146 void osm_mcast_tbl_delete(IN osm_mcast_tbl_t ** const pp_tbl);
 147 /*
 148 * PARAMETERS
 149 *       pp_tbl
 150 *               [in] Pointer a Pointer to the Multicast Forwarding Table object.
 151 *
 152 * RETURN VALUE
 153 *       On success, returns a pointer to a new Multicast Forwarding Table object
 154 *       of the specified size.
 155 *       NULL otherwise.
 156 *
 157 * NOTES
 158 *
 159 * SEE ALSO
 160 *********/
 161
 162 /****f* OpenSM: Forwarding Table/osm_mcast_tbl_destroy
 163 * NAME
 164 *       osm_mcast_tbl_destroy
 165 *
 166 * DESCRIPTION
 167 *       This destroys and deallocates a Multicast Forwarding Table object.
 168 *
 169 * SYNOPSIS
 170 */
 171 void osm_mcast_tbl_destroy(IN osm_mcast_tbl_t * const p_tbl);
 172 /*
 173 * PARAMETERS
 174 *       p_tbl
 175 *               [in] Pointer to the Multicast Forwarding Table object.
 176 *
 177 * RETURN VALUE
 178 *    None
 179 *
 180 * NOTES
 181 *
 182 * SEE ALSO
 183 *********/
 184
 185 /****f* OpenSM: Forwarding Table/osm_mcast_tbl_set
 186 * NAME
 187 *       osm_mcast_tbl_set
 188 *
 189 * DESCRIPTION
 190 *       Adds the port to the multicast group.
 191 *
 192 * SYNOPSIS
 193 */
 194 void
 195 osm_mcast_tbl_set(IN osm_mcast_tbl_t * const p_tbl,
 196                   IN const uint16_t mlid_ho, IN const uint8_t port_num);
 197 /*
 198 * PARAMETERS
 199 *       p_tbl
 200 *               [in] Pointer to the Multicast Forwarding Table object.
 201 *
 202 *       mlid_ho
 203 *               [in] MLID value (host order) for which to set the route.
 204 *
 205 *       port_num
 206 *               [in] Port to add to the multicast group.
 207 *
 208 * RETURN VALUE
 209 *       None.
 210 *
 211 * NOTES
 212 *
 213 * SEE ALSO
 214 *********/
 215
 216 /****f* OpenSM: Forwarding Table/osm_mcast_tbl_clear_mlid
 217 * NAME
 218 *       osm_mcast_tbl_clear_mlid
 219 *
 220 * DESCRIPTION
 221 *       Removes all multicast paths for the specified MLID.
 222 *
 223 * SYNOPSIS
 224 */
 225 void
 226 osm_mcast_tbl_clear_mlid(IN osm_mcast_tbl_t * const p_tbl,
 227                          IN const uint16_t mlid_ho);
 228 /*
 229 * PARAMETERS
 230 *       p_tbl
 231 *               [in] Pointer to the Multicast Forwarding Table object.
 232 *
 233 *       mlid_ho
 234 *               [in] MLID value (host order) for which to clear.
 235 *
 236 * RETURN VALUE
 237 *       None.
 238 *
 239 * NOTES
 240 *
 241 * SEE ALSO
 242 *********/
 243
 244 /****f* OpenSM: Forwarding Table/osm_mcast_tbl_is_port
 245 * NAME
 246 *       osm_mcast_tbl_is_port
 247 *
 248 * DESCRIPTION
 249 *       Returns TRUE if the port is in the multicast group.
 250 *
 251 * SYNOPSIS
 252 */
 253 boolean_t
 254 osm_mcast_tbl_is_port(IN const osm_mcast_tbl_t * const p_tbl,
 255                       IN const uint16_t mlid_ho, IN const uint8_t port_num);
 256 /*
 257 * PARAMETERS
 258 *       p_tbl
 259 *               [in] Pointer to the Multicast Forwarding Table object.
 260 *
 261 *       mlid_ho
 262 *               [in] MLID value (host order).
 263 *
 264 *       port_num
 265 *               [in] Port number on the switch
 266 *
 267 * RETURN VALUE
 268 *       Returns the port that routes the specified LID.
 269 *
 270 * NOTES
 271 *
 272 * SEE ALSO
 273 *********/
 274
 275 /****f* OpenSM: Forwarding Table/osm_mcast_tbl_is_any_port
 276 * NAME
 277 *       osm_mcast_tbl_is_any_port
 278 *
 279 * DESCRIPTION
 280 *       Returns TRUE if any port is in the multicast group.
 281 *
 282 * SYNOPSIS
 283 */
 284 boolean_t
 285 osm_mcast_tbl_is_any_port(IN const osm_mcast_tbl_t * const p_tbl,
 286                           IN const uint16_t mlid_ho);
 287 /*
 288 * PARAMETERS
 289 *       p_tbl
 290 *               [in] Pointer to the Multicast Forwarding Table object.
 291 *
 292 *       mlid_ho
 293 *               [in] MLID value (host order).
 294 *
 295 * RETURN VALUE
 296 *       Returns TRUE if any port is in the multicast group.
 297 *
 298 * NOTES
 299 *
 300 * SEE ALSO
 301 *********/
 302
 303 /****f* OpenSM: Forwarding Table/osm_mcast_tbl_set_block
 304 * NAME
 305 *       osm_mcast_tbl_set_block
 306 *
 307 * DESCRIPTION
 308 *       Copies the specified block into the Multicast Forwarding Table.
 309 *
 310 * SYNOPSIS
 311 */
 312 ib_api_status_t
 313 osm_mcast_tbl_set_block(IN osm_mcast_tbl_t * const p_tbl,
 314                         IN const ib_net16_t * const p_block,
 315                         IN const int16_t block_num, IN const uint8_t position);
 316 /*
 317 * PARAMETERS
 318 *       p_tbl
 319 *               [in] Pointer to the Multicast Forwarding Table object.
 320 *
 321 *       p_block
 322 *               [in] Pointer to the Forwarding Table block.
 323 *
 324 *       block_num
 325 *               [in] Block number of this block.
 326 *
 327 * RETURN VALUE
 328 *       None.
 329 *
 330 * NOTES
 331 *
 332 * SEE ALSO
 333 *********/
 334
 335 /****f* OpenSM: Forwarding Table/osm_mcast_get_tbl_block
 336 * NAME
 337 *       osm_mcast_get_tbl_block
 338 *
 339 * DESCRIPTION
 340 *       Retrieve a multicast forwarding table block.
 341 *
 342 * SYNOPSIS
 343 */
 344 boolean_t
 345 osm_mcast_tbl_get_block(IN osm_mcast_tbl_t * const p_tbl,
 346                         IN const int16_t block_num,
 347                         IN const uint8_t position,
 348                         OUT ib_net16_t * const p_block);
 349 /*
 350 * PARAMETERS
 351 *       p_tbl
 352 *               [in] Pointer to an osm_mcast_tbl_t object.
 353 *
 354 *       p_block
 355 *               [in] Pointer to the Forwarding Table block.
 356 *
 357 *       block_num
 358 *               [in] Block number of this block.
 359 *
 360 *       p_block
 361 *               [out] Pointer to the 32 entry array to store the
 362 *               forwarding table clock specified by block_id.
 363 *
 364 * RETURN VALUES
 365 *       Returns true if there are more blocks necessary to
 366 *       configure all the MLIDs reachable from this switch.
 367 *       FALSE otherwise.
 368 *
 369 * NOTES
 370 *
 371 * SEE ALSO
 372 *********/
 373
 374 /****f* OpenSM: Forwarding Table/osm_mcast_tbl_get_max_block
 375 * NAME
 376 *       osm_mcast_tbl_get_max_block
 377 *
 378 * DESCRIPTION
 379 *       Returns the maximum block ID in this table.
 380 *
 381 * SYNOPSIS
 382 */
 383 static inline uint16_t
 384 osm_mcast_tbl_get_max_block(IN osm_mcast_tbl_t * const p_tbl)
 385 {
 386         return (p_tbl->max_block);
 387 }
 388
 389 /*
 390 * PARAMETERS
 391 *       p_tbl
 392 *               [in] Pointer to an osm_mcast_tbl_t object.
 393 *
 394 * RETURN VALUES
 395 *       Returns the maximum block ID in this table.
 396 *
 397 * NOTES
 398 *
 399 * SEE ALSO
 400 *********/
 401
 402 /****f* OpenSM: Forwarding Table/osm_mcast_tbl_get_max_block_in_use
 403 * NAME
 404 *       osm_mcast_tbl_get_max_block_in_use
 405 *
 406 * DESCRIPTION
 407 *       Returns the maximum block ID in use in this table.
 408 *       A value of -1 indicates no blocks are in use.
 409 *
 410 * SYNOPSIS
 411 */
 412 static inline int16_t
 413 osm_mcast_tbl_get_max_block_in_use(IN osm_mcast_tbl_t * const p_tbl)
 414 {
 415         return (p_tbl->max_block_in_use);
 416 }
 417
 418 /*
 419 * PARAMETERS
 420 *       p_tbl
 421 *               [in] Pointer to an osm_mcast_tbl_t object.
 422 *
 423 * RETURN VALUES
 424 *       Returns the maximum block ID in use in this table.
 425 *       A value of -1 indicates no blocks are in use.
 426 *
 427 * NOTES
 428 *
 429 * SEE ALSO
 430 *********/
 431
 432 /****f* OpenSM: Forwarding Table/osm_mcast_tbl_get_max_position
 433 * NAME
 434 *       osm_mcast_tbl_get_max_position
 435 *
 436 * DESCRIPTION
 437 *       Returns the maximum position in this table.
 438 *
 439 * SYNOPSIS
 440 */
 441 static inline uint8_t
 442 osm_mcast_tbl_get_max_position(IN osm_mcast_tbl_t * const p_tbl)
 443 {
 444         return (p_tbl->max_position);
 445 }
 446
 447 /*
 448 * PARAMETERS
 449 *       p_tbl
 450 *               [in] Pointer to an osm_mcast_tbl_t object.
 451 *
 452 * RETURN VALUES
 453 *       Returns the maximum position in this table.
 454 *
 455 * NOTES
 456 *
 457 * SEE ALSO
 458 *********/
 459
 460 END_C_DECLS
 461 #endif                          /* _OSM_MCAST_TBL_H_ */