contrib/ofed/management/opensm/include/opensm/osm_node.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_node_t.
  39  *      This object represents an IBA node.
  40  *      This object is part of the OpenSM family of objects.
  41  */
  42
  43 #ifndef _OSM_NODE_H_
  44 #define _OSM_NODE_H_
  45
  46 #include <complib/cl_qmap.h>
  47 #include <iba/ib_types.h>
  48 #include <opensm/osm_base.h>
  49 #include <opensm/osm_port.h>
  50 #include <opensm/osm_path.h>
  51 #include <opensm/osm_madw.h>
  52
  53 #ifdef __cplusplus
  54 #  define BEGIN_C_DECLS extern "C" {
  55 #  define END_C_DECLS   }
  56 #else                           /* !__cplusplus */
  57 #  define BEGIN_C_DECLS
  58 #  define END_C_DECLS
  59 #endif                          /* __cplusplus */
  60
  61 BEGIN_C_DECLS
  62
  63 struct osm_switch;
  64
  65 /****h* OpenSM/Node
  66 * NAME
  67 *       Node
  68 *
  69 * DESCRIPTION
  70 *       The Node object encapsulates the information needed by the
  71 *       OpenSM to manage nodes.  The OpenSM allocates one Node object
  72 *       per node in the IBA subnet.
  73 *
  74 *       The Node object 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
  85 /****s* OpenSM: Node/osm_node_t
  86 * NAME
  87 *       osm_node_t
  88 *
  89 * DESCRIPTION
  90 *       Node structure.
  91 *
  92 *       This object should be treated as opaque and should
  93 *       be manipulated only through the provided functions.
  94 *
  95 * SYNOPSIS
  96 */
  97 typedef struct osm_node {
  98         cl_map_item_t map_item;
  99         struct osm_switch *sw;
 100         ib_node_info_t node_info;
 101         ib_node_desc_t node_desc;
 102         uint32_t discovery_count;
 103         uint32_t physp_tbl_size;
 104         char *print_desc;
 105         osm_physp_t physp_table[1];
 106 } osm_node_t;
 107 /*
 108 * FIELDS
 109 *       map_item
 110 *               Linkage structure for cl_qmap.  MUST BE FIRST MEMBER!
 111 *
 112 *       sw
 113 *               For switch node contains pointer to appropriate osm_switch
 114 *               structure. NULL for non-switch nodes. Can be used for fast
 115 *               access to switch object and for simple node type detection
 116 *
 117 *       node_info
 118 *               The IBA defined NodeInfo data for this node.
 119 *
 120 *       node_desc
 121 *               The IBA defined NodeDescription data for this node.
 122 *
 123 *       discovery_count
 124 *               The number of times this node has been discovered
 125 *               during the current fabric sweep.  This number is reset
 126 *               to zero at the start of a sweep.
 127 *
 128 *       phsyp_tbl_size
 129 *               The size of the physp_table array.  This value is one greater
 130 *               than the number of ports in the node, since port numbers
 131 *               start with 1 for some bizzare reason.
 132 *
 133 *       print_desc
 134 *               A printable version of the node description.
 135 *
 136 *       phsyp_table
 137 *               Array of physical port objects belonging to this node.
 138 *               Index is contiguous by local port number.
 139 *               For switches, port 0 is the always the management port (14.2.5.6).
 140 *               MUST BE LAST MEMBER! - Since it grows !!!!
 141 *
 142 * SEE ALSO
 143 *       Node object
 144 *********/
 145
 146 /****f* OpenSM: Node/osm_node_delete
 147 * NAME
 148 *       osm_node_delete
 149 *
 150 * DESCRIPTION
 151 *       The osm_node_delete function destroys a node, releasing
 152 *       all resources.
 153 *
 154 * SYNOPSIS
 155 */
 156 void osm_node_delete(IN OUT osm_node_t ** const p_node);
 157 /*
 158 * PARAMETERS
 159 *       p_node
 160 *               [in][out] Pointer to a Pointer a Node object to destroy.
 161 *               On return, the pointer to set to NULL.
 162 *
 163 * RETURN VALUE
 164 *       This function does not return a value.
 165 *
 166 * NOTES
 167 *       Performs any necessary cleanup of the specified Node object.
 168 *       This function should only be called after a call to osm_node_new.
 169 *
 170 * SEE ALSO
 171 *       Node object, osm_node_new
 172 *********/
 173
 174 /****f* OpenSM: Node/osm_node_new
 175 * NAME
 176 *       osm_node_new
 177 *
 178 * DESCRIPTION
 179 *       The osm_node_new function initializes a Node object for use.
 180 *
 181 * SYNOPSIS
 182 */
 183 osm_node_t *osm_node_new(IN const osm_madw_t * const p_madw);
 184 /*
 185 * PARAMETERS
 186 *       p_madw
 187 *               [in] Pointer to a osm_madw_t object containing a mad with
 188 *               the node's NodeInfo attribute.  The caller may discard the
 189 *               osm_madw_t structure after calling osm_node_new.
 190 *
 191 * RETURN VALUES
 192 *       On success, a pointer to the new initialized osm_node_t structure.
 193 *       NULL otherwise.
 194 *
 195 * NOTES
 196 *
 197 * SEE ALSO
 198 *       Node object
 199 *********/
 200
 201 /****f* OpenSM: Node/osm_node_get_physp_ptr
 202 * NAME
 203 *       osm_node_get_physp_ptr
 204 *
 205 * DESCRIPTION
 206 *       Returns a pointer to the physical port object at the
 207 *       specified local port number.
 208 *
 209 * SYNOPSIS
 210 */
 211 static inline osm_physp_t *osm_node_get_physp_ptr(IN osm_node_t * const p_node,
 212                                                   IN const uint32_t port_num)
 213 {
 214
 215         CL_ASSERT(port_num < p_node->physp_tbl_size);
 216         return osm_physp_is_valid(&p_node->physp_table[port_num]) ?
 217                 &p_node->physp_table[port_num] : NULL;
 218 }
 219
 220 /*
 221 * PARAMETERS
 222 *       p_node
 223 *               [in] Pointer to an osm_node_t object.
 224 *
 225 *       port_num
 226 *               [in] Local port number.
 227 *
 228 * RETURN VALUES
 229 *       Returns a pointer to the physical port object at the
 230 *       specified local port number.
 231 *       A return value of zero means the port number was out of range.
 232 *
 233 * NOTES
 234 *
 235 * SEE ALSO
 236 *       Node object
 237 *********/
 238
 239 /****f* OpenSM: Node/osm_node_get_type
 240 * NAME
 241 *       osm_node_get_type
 242 *
 243 * DESCRIPTION
 244 *       Returns the type of this node.
 245 *
 246 * SYNOPSIS
 247 */
 248 static inline uint8_t osm_node_get_type(IN const osm_node_t * const p_node)
 249 {
 250         return (p_node->node_info.node_type);
 251 }
 252
 253 /*
 254 * PARAMETERS
 255 *       p_node
 256 *               [in] Pointer to an osm_node_t object.
 257 *
 258 * RETURN VALUES
 259 *       Returns the IBA defined type of this node.
 260 *
 261 * NOTES
 262 *
 263 * SEE ALSO
 264 *       Node object
 265 *********/
 266
 267 /****f* OpenSM: Node/osm_node_get_num_physp
 268 * NAME
 269 *       osm_node_get_num_physp
 270 *
 271 * DESCRIPTION
 272 *       Returns the type of this node.
 273 *
 274 * SYNOPSIS
 275 */
 276 static inline uint8_t osm_node_get_num_physp(IN const osm_node_t * const p_node)
 277 {
 278         return ((uint8_t) p_node->physp_tbl_size);
 279 }
 280
 281 /*
 282 * PARAMETERS
 283 *       p_node
 284 *               [in] Pointer to an osm_node_t object.
 285 *
 286 * RETURN VALUES
 287 *       Returns the IBA defined type of this node.
 288 *
 289 * NOTES
 290 *
 291 * SEE ALSO
 292 *       Node object
 293 *********/
 294
 295 /****f* OpenSM: Node/osm_node_get_remote_node
 296 * NAME
 297 *       osm_node_get_remote_node
 298 *
 299 * DESCRIPTION
 300 *       Returns a pointer to the node on the other end of the
 301 *       specified port.
 302 *       Returns NULL if no remote node exists.
 303 *
 304 * SYNOPSIS
 305 */
 306 osm_node_t *osm_node_get_remote_node(IN osm_node_t * const p_node,
 307                                      IN const uint8_t port_num,
 308                                      OUT uint8_t * p_remote_port_num);
 309 /*
 310 * PARAMETERS
 311 *       p_node
 312 *               [in] Pointer to an osm_node_t object.
 313 *
 314 *       port_num
 315 *               [in] Port number in p_node through which to get the remote node.
 316 *
 317 *       p_remote_port_num
 318 *               [out] Port number in the remote's node through which this
 319 *               link exists.  The caller may specify NULL for this pointer
 320 *               if the port number isn't needed.
 321 *
 322 * RETURN VALUES
 323 *       Returns a pointer to the node on the other end of the
 324 *       specified port.
 325 *       Returns NULL if no remote node exists.
 326 *
 327 * NOTES
 328 *
 329 * SEE ALSO
 330 *       Node object
 331 *********/
 332
 333 /****f* OpenSM: Node/osm_node_get_base_lid
 334 * NAME
 335 *       osm_node_get_base_lid
 336 *
 337 * DESCRIPTION
 338 *       Returns the LID value of the specified port on this node.
 339 *
 340 * SYNOPSIS
 341 */
 342 static inline ib_net16_t
 343 osm_node_get_base_lid(IN const osm_node_t * const p_node,
 344                       IN const uint32_t port_num)
 345 {
 346         CL_ASSERT(port_num < p_node->physp_tbl_size);
 347         return (osm_physp_get_base_lid(&p_node->physp_table[port_num]));
 348 }
 349
 350 /*
 351 * PARAMETERS
 352 *       p_node
 353 *               [in] Pointer to an osm_node_t object.
 354 *
 355 *       port_num
 356 *               [in] Local port number.
 357 *
 358 * RETURN VALUES
 359 *       Returns a pointer to the physical port object at the
 360 *       specified local port number.
 361 *       A return value of zero means the port number was out of range.
 362 *
 363 * NOTES
 364 *
 365 * SEE ALSO
 366 *       Node object
 367 *********/
 368
 369 /****f* OpenSM: Node/osm_node_get_remote_base_lid
 370 * NAME
 371 *       osm_node_get_remote_base_lid
 372 *
 373 * DESCRIPTION
 374 *       Returns the base LID value of the port on the other side
 375 *       of the wire from the specified port on this node.
 376 *
 377 * SYNOPSIS
 378 */
 379 ib_net16_t
 380 osm_node_get_remote_base_lid(IN osm_node_t * const p_node,
 381                              IN const uint32_t port_num);
 382 /*
 383 * PARAMETERS
 384 *       p_node
 385 *               [in] Pointer to an osm_node_t object.
 386 *
 387 *       port_num
 388 *               [in] Local port number.
 389 *
 390 * RETURN VALUES
 391 *       Returns a pointer to the physical port object at the
 392 *       specified local port number.
 393 *       A return value of zero means the port number was out of range.
 394 *
 395 * NOTES
 396 *
 397 * SEE ALSO
 398 *       Node object
 399 *********/
 400
 401 /****f* OpenSM: Node/osm_node_get_lmc
 402 * NAME
 403 *       osm_node_get_lmc
 404 *
 405 * DESCRIPTION
 406 *       Returns the LMC value of the specified port on this node.
 407 *
 408 * SYNOPSIS
 409 */
 410 static inline uint8_t
 411 osm_node_get_lmc(IN const osm_node_t * const p_node, IN const uint32_t port_num)
 412 {
 413         CL_ASSERT(port_num < p_node->physp_tbl_size);
 414         return (osm_physp_get_lmc(&p_node->physp_table[port_num]));
 415 }
 416
 417 /*
 418 * PARAMETERS
 419 *       p_node
 420 *               [in] Pointer to an osm_node_t object.
 421 *
 422 *       port_num
 423 *               [in] Local port number.
 424 *
 425 * RETURN VALUES
 426 *       Returns the LMC value of the specified port on this node.
 427 *
 428 * NOTES
 429 *
 430 * SEE ALSO
 431 *       Node object
 432 *********/
 433
 434 /****f* OpenSM: Node/osm_node_init_physp
 435 * NAME
 436 *       osm_node_init_physp
 437 *
 438 * DESCRIPTION
 439 *       Initializes a physical port for the given node.
 440 *
 441 * SYNOPSIS
 442 */
 443 void
 444 osm_node_init_physp(IN osm_node_t * const p_node,
 445                     IN const osm_madw_t * const p_madw);
 446 /*
 447 * PARAMETERS
 448 *       p_node
 449 *               [in] Pointer to an osm_node_t object.
 450 *
 451 *       p_madw
 452 *               [in] Pointer to a osm_madw_t object containing a mad with
 453 *               the node's NodeInfo attribute as discovered through the
 454 *               Physical Port to add to the node.  The caller may discard the
 455 *               osm_madw_t structure after calling osm_node_new.
 456 *
 457 * RETURN VALUES
 458 *       None.
 459 *
 460 * NOTES
 461 *
 462 * SEE ALSO
 463 *       Node object, Physical Port object.
 464 *********/
 465
 466 /****f* OpenSM: Node/osm_node_get_node_guid
 467 * NAME
 468 *       osm_node_get_node_guid
 469 *
 470 * DESCRIPTION
 471 *       Returns the node GUID of this node.
 472 *
 473 * SYNOPSIS
 474 */
 475 static inline ib_net64_t
 476 osm_node_get_node_guid(IN const osm_node_t * const p_node)
 477 {
 478         return (p_node->node_info.node_guid);
 479 }
 480
 481 /*
 482 * PARAMETERS
 483 *       p_node
 484 *               [in] Pointer to an osm_node_t object.
 485 *
 486 * RETURN VALUES
 487 *       Returns the node GUID of this node.
 488 *
 489 * NOTES
 490 *
 491 * SEE ALSO
 492 *       Node object
 493 *********/
 494
 495 /****f* OpenSM: Node/osm_node_link
 496 * NAME
 497 *       osm_node_link
 498 *
 499 * DESCRIPTION
 500 *       Logically connects a node to another node through the specified port.
 501 *
 502 * SYNOPSIS
 503 */
 504 void
 505 osm_node_link(IN osm_node_t * const p_node,
 506               IN const uint8_t port_num,
 507               IN osm_node_t * const p_remote_node,
 508               IN const uint8_t remote_port_num);
 509 /*
 510 * PARAMETERS
 511 *       p_node
 512 *               [in] Pointer to an osm_node_t object.
 513 *
 514 *       port_num
 515 *               [in] Port number in p_node through which to create the link.
 516 *
 517 *       p_remote_node
 518 *               [in] Pointer to the remote port object.
 519 *
 520 *       remote_port_num
 521 *               [in] Port number in the remote's node through which to
 522 *               create this link.
 523 *
 524 * RETURN VALUES
 525 *       None.
 526 *
 527 * NOTES
 528 *
 529 * SEE ALSO
 530 *       Node object
 531 *********/
 532
 533 /****f* OpenSM: Node/osm_node_unlink
 534 * NAME
 535 *       osm_node_unlink
 536 *
 537 * DESCRIPTION
 538 *       Logically disconnects a node from another node through
 539 *       the specified port.
 540 *
 541 * SYNOPSIS
 542 */
 543 void
 544 osm_node_unlink(IN osm_node_t * const p_node,
 545                 IN const uint8_t port_num,
 546                 IN osm_node_t * const p_remote_node,
 547                 IN const uint8_t remote_port_num);
 548 /*
 549 * PARAMETERS
 550 *       p_node
 551 *               [in] Pointer to an osm_node_t object.
 552 *
 553 *       port_num
 554 *               [in] Port number in p_node through which to unlink.
 555 *
 556 *       p_remote_node
 557 *               [in] Pointer to the remote port object.
 558 *
 559 *       remote_port_num
 560 *               [in] Port number in the remote's node through which to unlink.
 561 *
 562 * RETURN VALUES
 563 *       None.
 564 *
 565 * NOTES
 566 *
 567 * SEE ALSO
 568 *       Node object
 569 *********/
 570
 571 /****f* OpenSM: Node/osm_node_link_exists
 572 * NAME
 573 *       osm_node_link_exists
 574 *
 575 * DESCRIPTION
 576 *       Return TRUE if a link exists between the specified nodes on
 577 *       the specified ports.
 578 *       Returns FALSE otherwise.
 579 *
 580 * SYNOPSIS
 581 */
 582 boolean_t
 583 osm_node_link_exists(IN osm_node_t * const p_node,
 584                      IN const uint8_t port_num,
 585                      IN osm_node_t * const p_remote_node,
 586                      IN const uint8_t remote_port_num);
 587 /*
 588 * PARAMETERS
 589 *       p_node
 590 *               [in] Pointer to an osm_node_t object.
 591 *
 592 *       port_num
 593 *               [in] Port number in p_node through which to check the link.
 594 *
 595 *       p_remote_node
 596 *               [in] Pointer to the remote port object.
 597 *
 598 *       remote_port_num
 599 *               [in] Port number in the remote's node through which to
 600 *               check this link.
 601 *
 602 * RETURN VALUES
 603 *       Return TRUE if a link exists between the specified nodes on
 604 *       the specified ports.
 605 *       Returns FALSE otherwise.
 606 *
 607 * NOTES
 608 *
 609 * SEE ALSO
 610 *       Node object
 611 *********/
 612
 613 /****f* OpenSM: Node/osm_node_has_any_link
 614 * NAME
 615 *       osm_node_has_any_link
 616 *
 617 * DESCRIPTION
 618 *       Return TRUE if a any link exists from the specified nodes on
 619 *       the specified port.
 620 *       Returns FALSE otherwise.
 621 *
 622 * SYNOPSIS
 623 */
 624 boolean_t
 625 osm_node_has_any_link(IN osm_node_t * const p_node, IN const uint8_t port_num);
 626 /*
 627 * PARAMETERS
 628 *       p_node
 629 *               [in] Pointer to an osm_node_t object.
 630 *
 631 *       port_num
 632 *               [in] Port number in p_node through which to check the link.
 633 *
 634 * RETURN VALUES
 635 *       Return TRUE if a any link exists from the specified nodes on
 636 *       the specified port.
 637 *       Returns FALSE otherwise.
 638 *
 639 * NOTES
 640 *
 641 * SEE ALSO
 642 *       Node object
 643 *********/
 644
 645 /****f* OpenSM: Node/osm_node_link_has_valid_ports
 646 * NAME
 647 *       osm_node_link_has_valid_ports
 648 *
 649 * DESCRIPTION
 650 *       Return TRUE if both ports in the link are valid (initialized).
 651 *       Returns FALSE otherwise.
 652 *
 653 * SYNOPSIS
 654 */
 655 boolean_t
 656 osm_node_link_has_valid_ports(IN osm_node_t * const p_node,
 657                               IN const uint8_t port_num,
 658                               IN osm_node_t * const p_remote_node,
 659                               IN const uint8_t remote_port_num);
 660 /*
 661 * PARAMETERS
 662 *       p_node
 663 *               [in] Pointer to an osm_node_t object.
 664 *
 665 *       port_num
 666 *               [in] Port number in p_node through which to check the link.
 667 *
 668 * RETURN VALUES
 669 *       Return TRUE if both ports in the link are valid (initialized).
 670 *       Returns FALSE otherwise.
 671 *
 672 * NOTES
 673 *
 674 * SEE ALSO
 675 *       Node object
 676 *********/
 677
 678 END_C_DECLS
 679 #endif                          /* _OSM_NODE_H_ */