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

   1 /*
   2  * Copyright (c) 2004-2008 Voltaire, Inc. All rights reserved.
   3  * Copyright (c) 2002-2008 Mellanox Technologies LTD. All rights reserved.
   4  * Copyright (c) 1996-2003 Intel Corporation. All rights reserved.
   5  * Copyright (c) 2008 Xsigo Systems Inc.  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_subn_t.
  40  *      This object represents an IBA subnet.
  41  *      This object is part of the OpenSM family of objects.
  42  */
  43
  44 #ifndef _OSM_SUBNET_H_
  45 #define _OSM_SUBNET_H_
  46
  47 #include <iba/ib_types.h>
  48 #include <complib/cl_qmap.h>
  49 #include <complib/cl_map.h>
  50 #include <complib/cl_ptr_vector.h>
  51 #include <complib/cl_list.h>
  52 #include <opensm/osm_base.h>
  53 #include <opensm/osm_prefix_route.h>
  54 #include <stdio.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 #define OSM_SUBNET_VECTOR_MIN_SIZE                      0
  66 #define OSM_SUBNET_VECTOR_GROW_SIZE                     1
  67 #define OSM_SUBNET_VECTOR_CAPACITY                      256
  68 struct osm_opensm;
  69 struct osm_qos_policy;
  70
  71 /****h* OpenSM/Subnet
  72 * NAME
  73 *       Subnet
  74 *
  75 * DESCRIPTION
  76 *       The Subnet object encapsulates the information needed by the
  77 *       OpenSM to manage a subnet.  The OpenSM allocates one Subnet object
  78 *       per IBA subnet.
  79 *
  80 *       The Subnet object is not thread safe, thus callers must provide
  81 *       serialization.
  82 *
  83 *       This object is essentially a container for the various components
  84 *       of a subnet.  Callers may directly access the member variables.
  85 *
  86 * AUTHOR
  87 *       Steve King, Intel
  88 *
  89 *********/
  90
  91 /****s* OpenSM: Subnet/osm_qos_options_t
  92 * NAME
  93 *       osm_qos_options_t
  94 *
  95 * DESCRIPTION
  96 *       Subnet QoS options structure.  This structure contains the various
  97 *       QoS specific configuration parameters for the subnet.
  98 *
  99 * SYNOPSIS
 100 */
 101 typedef struct osm_qos_options {
 102         unsigned max_vls;
 103         int high_limit;
 104         char *vlarb_high;
 105         char *vlarb_low;
 106         char *sl2vl;
 107 } osm_qos_options_t;
 108 /*
 109 * FIELDS
 110 *
 111 *       max_vls
 112 *               The number of maximum VLs on the Subnet (0 == use default)
 113 *
 114 *       high_limit
 115 *               The limit of High Priority component of VL Arbitration
 116 *               table (IBA 7.6.9) (-1 == use default)
 117 *
 118 *       vlarb_high
 119 *               High priority VL Arbitration table template. (NULL == use default)
 120 *
 121 *       vlarb_low
 122 *               Low priority VL Arbitration table template. (NULL == use default)
 123 *
 124 *       sl2vl
 125 *               SL2VL Mapping table (IBA 7.6.6) template. (NULL == use default)
 126 *
 127 *********/
 128
 129 /****s* OpenSM: Subnet/osm_subn_opt_t
 130 * NAME
 131 *       osm_subn_opt_t
 132 *
 133 * DESCRIPTION
 134 *       Subnet options structure.  This structure contains the various
 135 *       site specific configuration parameters for the subnet.
 136 *
 137 * SYNOPSIS
 138 */
 139 typedef struct osm_subn_opt {
 140         char *config_file;
 141         ib_net64_t guid;
 142         ib_net64_t m_key;
 143         ib_net64_t sm_key;
 144         ib_net64_t sa_key;
 145         ib_net64_t subnet_prefix;
 146         ib_net16_t m_key_lease_period;
 147         uint32_t sweep_interval;
 148         uint32_t max_wire_smps;
 149         uint32_t transaction_timeout;
 150         uint8_t sm_priority;
 151         uint8_t lmc;
 152         boolean_t lmc_esp0;
 153         uint8_t max_op_vls;
 154         uint8_t force_link_speed;
 155         boolean_t reassign_lids;
 156         boolean_t ignore_other_sm;
 157         boolean_t single_thread;
 158         boolean_t disable_multicast;
 159         boolean_t force_log_flush;
 160         uint8_t subnet_timeout;
 161         uint8_t packet_life_time;
 162         uint8_t vl_stall_count;
 163         uint8_t leaf_vl_stall_count;
 164         uint8_t head_of_queue_lifetime;
 165         uint8_t leaf_head_of_queue_lifetime;
 166         uint8_t local_phy_errors_threshold;
 167         uint8_t overrun_errors_threshold;
 168         uint32_t sminfo_polling_timeout;
 169         uint32_t polling_retry_number;
 170         uint32_t max_msg_fifo_timeout;
 171         boolean_t force_heavy_sweep;
 172         uint8_t log_flags;
 173         char *dump_files_dir;
 174         char *log_file;
 175         unsigned long log_max_size;
 176         char *partition_config_file;
 177         boolean_t no_partition_enforcement;
 178         boolean_t qos;
 179         char *qos_policy_file;
 180         boolean_t accum_log_file;
 181         char *console;
 182         uint16_t console_port;
 183         char *port_prof_ignore_file;
 184         boolean_t port_profile_switch_nodes;
 185         boolean_t sweep_on_trap;
 186         char *routing_engine_names;
 187         boolean_t use_ucast_cache;
 188         boolean_t connect_roots;
 189         char *lid_matrix_dump_file;
 190         char *lfts_file;
 191         char *root_guid_file;
 192         char *cn_guid_file;
 193         char *ids_guid_file;
 194         char *guid_routing_order_file;
 195         char *sa_db_file;
 196         boolean_t exit_on_fatal;
 197         boolean_t honor_guid2lid_file;
 198         boolean_t daemon;
 199         boolean_t sm_inactive;
 200         boolean_t babbling_port_policy;
 201         osm_qos_options_t qos_options;
 202         osm_qos_options_t qos_ca_options;
 203         osm_qos_options_t qos_sw0_options;
 204         osm_qos_options_t qos_swe_options;
 205         osm_qos_options_t qos_rtr_options;
 206         boolean_t enable_quirks;
 207         boolean_t no_clients_rereg;
 208 #ifdef ENABLE_OSM_PERF_MGR
 209         boolean_t perfmgr;
 210         boolean_t perfmgr_redir;
 211         uint16_t perfmgr_sweep_time_s;
 212         uint32_t perfmgr_max_outstanding_queries;
 213         char *event_db_dump_file;
 214 #endif                          /* ENABLE_OSM_PERF_MGR */
 215         char *event_plugin_name;
 216         char *node_name_map_name;
 217         char *prefix_routes_file;
 218         boolean_t consolidate_ipv6_snm_req;
 219 } osm_subn_opt_t;
 220 /*
 221 * FIELDS
 222 *
 223 *       config_file
 224 *               The name of the config file.
 225 *
 226 *       guid
 227 *               The port guid that the SM is binding to.
 228 *
 229 *       m_key
 230 *               M_Key value sent to all ports qualifying all Set(PortInfo).
 231 *
 232 *       sm_key
 233 *               SM_Key value of the SM used for SM authentication.
 234 *
 235 *       sa_key
 236 *               SM_Key value to qualify rcv SA queries as "trusted".
 237 *
 238 *       subnet_prefix
 239 *               Subnet prefix used on this subnet.
 240 *
 241 *       m_key_lease_period
 242 *               The lease period used for the M_Key on this subnet.
 243 *
 244 *       sweep_interval
 245 *               The number of seconds between subnet sweeps.  A value of 0
 246 *               disables sweeping.
 247 *
 248 *       max_wire_smps
 249 *               The maximum number of SMPs sent in parallel.  Default is 4.
 250 *
 251 *       transaction_timeout
 252 *               The maximum time in milliseconds allowed for a transaction
 253 *               to complete.  Default is 200.
 254 *
 255 *       sm_priority
 256 *               The priority of this SM as specified by the user.  This
 257 *               value is made available in the SMInfo attribute.
 258 *
 259 *       lmc
 260 *               The LMC value used on this subnet.
 261 *
 262 *       lmc_esp0
 263 *               Whether LMC value used on subnet should be used for
 264 *               enhanced switch port 0 or not.  If TRUE, it is used.
 265 *               Otherwise (the default), LMC is set to 0 for ESP0.
 266 *
 267 *       max_op_vls
 268 *               Limit the maximal operational VLs. default is 1.
 269 *
 270 *       reassign_lids
 271 *               If TRUE cause all lids to be re-assigend.
 272 *               Otherwise (the default),
 273 *               OpenSM always tries to preserve as LIDs as much as possible.
 274 *
 275 *       ignore_other_sm_option
 276 *               This flag is TRUE if other SMs on the subnet should be ignored.
 277 *
 278 *       disable_multicast
 279 *               This flag is TRUE if OpenSM should disable multicast support.
 280 *
 281 *       max_msg_fifo_timeout
 282 *               The maximal time a message can stay in the incoming message
 283 *               queue. If there is more than one message in the queue and the
 284 *               last message stayed in the queue more than this value the SA
 285 *               request will be immediately returned with a BUSY status.
 286 *
 287 *       subnet_timeout
 288 *               The subnet_timeout that will be set for all the ports in the
 289 *               design SubnSet(PortInfo.vl_stall_life))
 290 *
 291 *       vl_stall_count
 292 *               The number of sequential packets dropped that cause the port
 293 *               to enter the VLStalled state.
 294 *
 295 *       leaf_vl_stall_count
 296 *               The number of sequential packets dropped that cause the port
 297 *               to enter the VLStalled state. This is for switch ports driving
 298 *               a CA or router port.
 299 *
 300 *       head_of_queue_lifetime
 301 *               The maximal time a packet can live at the head of a VL queue
 302 *               on any port not driving a CA or router port.
 303 *
 304 *       leaf_head_of_queue_lifetime
 305 *               The maximal time a packet can live at the head of a VL queue
 306 *               on switch ports driving a CA or router.
 307 *
 308 *       local_phy_errors_threshold
 309 *               Threshold of local phy errors for sending Trap 129
 310 *
 311 *       overrun_errors_threshold
 312 *               Threshold of credits overrun errors for sending Trap 129
 313 *
 314 *       sminfo_polling_timeout
 315 *               Specifies the polling timeout (in milliseconds) - the timeout
 316 *               between one poll to another.
 317 *
 318 *       packet_life_time
 319 *               The maximal time a packet can stay in a switch.
 320 *               The value is send to all switches as
 321 *               SubnSet(SwitchInfo.life_state)
 322 *
 323 *       dump_files_dir
 324 *               The directory to be used for opensm-subnet.lst, opensm.fdbs,
 325 *               opensm.mcfdbs, and default log file (the latter for Windows,
 326 *               not Linux).
 327 *
 328 *       log_file
 329 *               Name of the log file (or NULL) for stdout.
 330 *
 331 *       log_max_size
 332 *               This option defines maximal log file size in MB. When
 333 *               specified the log file will be truncated upon reaching
 334 *               this limit.
 335 *
 336 *       qos
 337 *               Boolean that specifies whether the OpenSM QoS functionality
 338 *               should be off or on.
 339 *
 340 *       qos_policy_file
 341 *               Name of the QoS policy file.
 342 *
 343 *       accum_log_file
 344 *               If TRUE (default) - the log file will be accumulated.
 345 *               If FALSE - the log file will be erased before starting
 346 *               current opensm run.
 347 *
 348 *       port_prof_ignore_file
 349 *               Name of file with port guids to be ignored by port profiling.
 350 *
 351 *       port_profile_switch_nodes
 352 *               If TRUE will count the number of switch nodes routed through
 353 *               the link. If FALSE - only CA/RT nodes are counted.
 354 *
 355 *       sweep_on_trap
 356 *               Received traps will initiate a new sweep.
 357 *
 358 *       routing_engine_names
 359 *               Name of routing engine(s) to use.
 360 *
 361 *       connect_roots
 362 *               The option which will enforce root to root connectivity with
 363 *               up/down routing engine (even if this violates "pure" deadlock
 364 *               free up/down algorithm)
 365 *
 366 *       use_ucast_cache
 367 *               When TRUE enables unicast routing cache.
 368 *
 369 *       lid_matrix_dump_file
 370 *               Name of the lid matrix dump file from where switch
 371 *               lid matrices (min hops tables) will be loaded
 372 *
 373 *       lfts_file
 374 *               Name of the unicast LFTs routing file from where switch
 375 *               forwarding tables will be loaded
 376 *
 377 *       root_guid_file
 378 *               Name of the file that contains list of root guids that
 379 *               will be used by fat-tree or up/dn routing (provided by User)
 380 *
 381 *       cn_guid_file
 382 *               Name of the file that contains list of compute node guids that
 383 *               will be used by fat-tree routing (provided by User)
 384 *
 385 *       ids_guid_file
 386 *               Name of the file that contains list of ids which should be
 387 *               used by Up/Down algorithm instead of node GUIDs
 388 *
 389 *       guid_routing_order_file
 390 *               Name of the file that contains list of guids for routing order
 391 *               that will be used by minhop and up/dn routing (provided by User).
 392 *
 393 *       sa_db_file
 394 *               Name of the SA database file.
 395 *
 396 *       exit_on_fatal
 397 *               If TRUE (default) - SM will exit on fatal subnet initialization
 398 *               issues.
 399 *               If FALSE - SM will not exit.
 400 *               Fatal initialization issues:
 401 *               a. SM recognizes 2 different nodes with the same guid, or
 402 *                  12x link with lane reversal badly configured.
 403 *
 404 *       honor_guid2lid_file
 405 *               Always honor the guid2lid file if it exists and is valid. This
 406 *               means that the file will be honored when SM is coming out of
 407 *               STANDBY. By default this is FALSE.
 408 *
 409 *       daemon
 410 *               OpenSM will run in daemon mode.
 411 *
 412 *       sm_inactive
 413 *               OpenSM will start with SM in not active state.
 414 *
 415 *       babbling_port_policy
 416 *               OpenSM will enforce its "babbling" port policy.
 417 *
 418 *       perfmgr
 419 *               Enable or disable the performance manager
 420 *
 421 *       perfmgr_redir
 422 *               Enable or disable the saving of redirection by PerfMgr
 423 *
 424 *       perfmgr_sweep_time_s
 425 *               Define the period (in seconds) of PerfMgr sweeps
 426 *
 427 *       event_db_dump_file
 428 *               File to dump the event database to
 429 *
 430 *       event_db_plugin
 431 *               Specify the name of the event plugin
 432 *
 433 *       qos_options
 434 *               Default set of QoS options
 435 *
 436 *       qos_ca_options
 437 *               QoS options for CA ports
 438 *
 439 *       qos_sw0_options
 440 *               QoS options for switches' port 0
 441 *
 442 *       qos_swe_options
 443 *               QoS options for switches' external ports
 444 *
 445 *       qos_rtr_options
 446 *               QoS options for router ports
 447 *
 448 *       enable_quirks
 449 *               Enable high risk new features and not fully qualified
 450 *               hardware specific work arounds
 451 *
 452 *       no_clients_rereg
 453 *               When TRUE disables clients reregistration request.
 454 *
 455 * SEE ALSO
 456 *       Subnet object
 457 *********/
 458
 459 /****s* OpenSM: Subnet/osm_subn_t
 460 * NAME
 461 *       osm_subn_t
 462 *
 463 * DESCRIPTION
 464 *       Subnet structure.  Callers may directly access member components,
 465 *       after grabbing a lock.
 466 *
 467 * TO DO
 468 *       This structure should probably be volatile.
 469 *
 470 * SYNOPSIS
 471 */
 472 typedef struct osm_subn {
 473         struct osm_opensm *p_osm;
 474         cl_qmap_t sw_guid_tbl;
 475         cl_qmap_t node_guid_tbl;
 476         cl_qmap_t port_guid_tbl;
 477         cl_qmap_t rtr_guid_tbl;
 478         cl_qlist_t prefix_routes_list;
 479         cl_qmap_t prtn_pkey_tbl;
 480         cl_qmap_t sm_guid_tbl;
 481         cl_qlist_t sa_sr_list;
 482         cl_qlist_t sa_infr_list;
 483         cl_ptr_vector_t port_lid_tbl;
 484         ib_net16_t master_sm_base_lid;
 485         ib_net16_t sm_base_lid;
 486         ib_net64_t sm_port_guid;
 487         uint8_t sm_state;
 488         osm_subn_opt_t opt;
 489         struct osm_qos_policy *p_qos_policy;
 490         uint16_t max_ucast_lid_ho;
 491         uint16_t max_mcast_lid_ho;
 492         uint8_t min_ca_mtu;
 493         uint8_t min_ca_rate;
 494         boolean_t ignore_existing_lfts;
 495         boolean_t subnet_initialization_error;
 496         boolean_t force_heavy_sweep;
 497         boolean_t force_reroute;
 498         boolean_t in_sweep_hop_0;
 499         boolean_t first_time_master_sweep;
 500         boolean_t coming_out_of_standby;
 501         unsigned need_update;
 502         void *mgroups[IB_LID_MCAST_END_HO - IB_LID_MCAST_START_HO + 1];
 503 } osm_subn_t;
 504 /*
 505 * FIELDS
 506 *       sw_guid_tbl
 507 *               Container of pointers to all Switch objects in the subent.
 508 *               Indexed by node GUID.
 509 *
 510 *       node_guid_tbl
 511 *               Container of pointers to all Node objects in the subent.
 512 *               Indexed by node GUID.
 513 *
 514 *       port_guid_tbl
 515 *               Container of pointers to all Port objects in the subent.
 516 *               Indexed by port GUID - network order!
 517 *
 518 *       rtr_guid_tbl
 519 *               Container of pointers to all Router objects in the subent.
 520 *               Indexed by node GUID.
 521 *
 522 *       prtn_pkey_tbl
 523 *               Container of pointers to all Partition objects in the subnet.
 524 *               Indexed by P_KEY.
 525 *
 526 *       sm_guid_tbl
 527 *               Container of pointers to SM objects representing other SMs
 528 *               on the subnet.
 529 *
 530 *       port_lid_tbl
 531 *               Container of pointers to all Port objects in the subent.
 532 *               Indexed by port LID.
 533 *
 534 *       master_sm_base_lid
 535 *               The base LID owned by the subnet's master SM.
 536 *
 537 *       sm_base_lid
 538 *               The base LID of the local port where the SM is.
 539 *
 540 *       sm_port_guid
 541 *               This SM's own port GUID.
 542 *
 543 *       sm_state
 544 *               The high-level state of the SM.  This value is made available
 545 *               in the SMInfo attribute.
 546 *
 547 *       opt
 548 *               Subnet options structure contains site specific configuration.
 549 *
 550 *       p_qos_policy
 551 *               Subnet QoS policy structure.
 552 *
 553 *       max_ucast_lid_ho
 554 *               The minimal max unicast lid reported by all switches
 555 *
 556 *       max_mcast_lid_ho
 557 *               The minimal max multicast lid reported by all switches
 558 *
 559 *       min_ca_mtu
 560 *               The minimal MTU reported by all CAs ports on the subnet
 561 *
 562 *       min_ca_rate
 563 *               The minimal rate reported by all CA ports on the subnet
 564 *
 565 *       ignore_existing_lfts
 566 *               This flag is a dynamic flag to instruct the LFT assignment to
 567 *               ignore existing legal LFT settings.
 568 *               The value will be set according to :
 569 *               - Any change to the list of switches will set it to high
 570 *               - Coming out of STANDBY it will be cleared (other SM worked)
 571 *               - Set to FALSE upon end of all lft assignments.
 572 *
 573 *       subnet_initalization_error
 574 *               Similar to the force_heavy_sweep flag. If TRUE - means that
 575 *               we had errors during initialization (due to SubnSet requests
 576 *               that failed). We want to declare the subnet as unhealthy, and
 577 *               force another heavy sweep.
 578 *
 579 *       force_heavy_sweep
 580 *               If TRUE - we want to force a heavy sweep. This can be done
 581 *               either due to receiving of trap - meaning there is some change
 582 *               on the subnet, or we received a handover from a remote sm.
 583 *               In this case we want to sweep and reconfigure the entire
 584 *               subnet. This will cause another heavy sweep to occure when
 585 *               the current sweep is done.
 586 *
 587 *       force_reroute
 588 *               If TRUE - we want to force switches in the fabric to be
 589 *               rerouted.
 590 *
 591 *       in_sweep_hop_0
 592 *               When in_sweep_hop_0 flag is set to TRUE - this means we are
 593 *               in sweep_hop_0 - meaning we do not want to continue beyond
 594 *               the current node.
 595 *               This is relevant for the case of SM on switch, since in the
 596 *               switch info we need to signal somehow not to continue
 597 *               the sweeping.
 598 *
 599 *       first_time_master_sweep
 600 *               This flag is used for the PortInfo setting. On the first
 601 *               sweep as master (meaning after moving from Standby|Discovering
 602 *               state), the SM must send a PortInfoSet to all ports. After
 603 *               that - we want to minimize the number of PortInfoSet requests
 604 *               sent, and to send only requests that change the value from
 605 *               what is updated in the port (or send a first request if this
 606 *               is a new port). We will set this flag to TRUE when entering
 607 *               the master state, and set it back to FALSE at the end of the
 608 *               drop manager. This is done since at the end of the drop manager
 609 *               we have updated all the ports that are reachable, and from now
 610 *               on these are the only ports we have data of. We don't want
 611 *               to send extra set requests to these ports anymore.
 612 *
 613 *       coming_out_of_standby
 614 *               TRUE on the first sweep after the SM was in standby.
 615 *               Used for nulling any cache of LID and Routing.
 616 *               The flag is set true if the SM state was standby and now
 617 *               changed to MASTER it is reset at the end of the sweep.
 618 *
 619 *       need_update
 620 *               This flag should be on during first non-master heavy
 621 *               (including pre-master discovery stage)
 622 *
 623 *       mgroups
 624 *               Array of pointers to all Multicast Group objects in the subnet.
 625 *               Indexed by MLID offset from base MLID.
 626 *
 627 * SEE ALSO
 628 *       Subnet object
 629 *********/
 630
 631 /****f* OpenSM: Subnet/osm_subn_construct
 632 * NAME
 633 *       osm_subn_construct
 634 *
 635 * DESCRIPTION
 636 *       This function constructs a Subnet object.
 637 *
 638 * SYNOPSIS
 639 */
 640 void osm_subn_construct(IN osm_subn_t * const p_subn);
 641 /*
 642 * PARAMETERS
 643 *       p_subn
 644 *               [in] Pointer to a Subnet object to construct.
 645 *
 646 * RETURN VALUE
 647 *       This function does not return a value.
 648 *
 649 * NOTES
 650 *       Allows calling osm_subn_init, and osm_subn_destroy.
 651 *
 652 *       Calling osm_subn_construct is a prerequisite to calling any other
 653 *       method except osm_subn_init.
 654 *
 655 * SEE ALSO
 656 *       Subnet object, osm_subn_init, osm_subn_destroy
 657 *********/
 658
 659 /****f* OpenSM: Subnet/osm_subn_destroy
 660 * NAME
 661 *       osm_subn_destroy
 662 *
 663 * DESCRIPTION
 664 *       The osm_subn_destroy function destroys a subnet, releasing
 665 *       all resources.
 666 *
 667 * SYNOPSIS
 668 */
 669 void osm_subn_destroy(IN osm_subn_t * const p_subn);
 670 /*
 671 * PARAMETERS
 672 *       p_subn
 673 *               [in] Pointer to a Subnet object to destroy.
 674 *
 675 * RETURN VALUE
 676 *       This function does not return a value.
 677 *
 678 * NOTES
 679 *       Performs any necessary cleanup of the specified Subnet object.
 680 *       Further operations should not be attempted on the destroyed object.
 681 *       This function should only be called after a call to osm_subn_construct
 682 *       or osm_subn_init.
 683 *
 684 * SEE ALSO
 685 *       Subnet object, osm_subn_construct, osm_subn_init
 686 *********/
 687
 688 /****f* OpenSM: Subnet/osm_subn_init
 689 * NAME
 690 *       osm_subn_init
 691 *
 692 * DESCRIPTION
 693 *       The osm_subn_init function initializes a Subnet object for use.
 694 *
 695 * SYNOPSIS
 696 */
 697 ib_api_status_t
 698 osm_subn_init(IN osm_subn_t * const p_subn,
 699               IN struct osm_opensm *const p_osm,
 700               IN const osm_subn_opt_t * const p_opt);
 701 /*
 702 * PARAMETERS
 703 *       p_subn
 704 *               [in] Pointer to an osm_subn_t object to initialize.
 705 *
 706 *       p_opt
 707 *               [in] Pointer to the subnet options structure.
 708 *
 709 * RETURN VALUES
 710 *       IB_SUCCESS if the Subnet object was initialized successfully.
 711 *
 712 * NOTES
 713 *       Allows calling other Subnet methods.
 714 *
 715 * SEE ALSO
 716 *       Subnet object, osm_subn_construct, osm_subn_destroy
 717 *********/
 718
 719 /*
 720   Forward references.
 721 */
 722 struct osm_mad_addr;
 723 struct osm_log;
 724 struct osm_switch;
 725 struct osm_physp;
 726 struct osm_port;
 727 struct osm_mgrp;
 728
 729 /****f* OpenSM: Helper/osm_get_gid_by_mad_addr
 730 * NAME
 731 *       osm_get_gid_by_mad_addr
 732 *
 733 * DESCRIPTION
 734 *       Looks for the requester gid in the mad address.
 735 *
 736 * Note: This code is not thread safe. Need to grab the lock before
 737 * calling it.
 738 *
 739 * SYNOPSIS
 740 */
 741 ib_api_status_t
 742 osm_get_gid_by_mad_addr(IN struct osm_log *p_log,
 743                         IN const osm_subn_t * p_subn,
 744                         IN const struct osm_mad_addr *p_mad_addr,
 745                         OUT ib_gid_t * p_gid);
 746 /*
 747 * PARAMETERS
 748 *       p_log
 749 *               [in] Pointer to a log object.
 750 *
 751 *       p_subn
 752 *               [in] Pointer to subnet object.
 753 *
 754 *       p_mad_addr
 755 *               [in] Pointer to mad address object.
 756 *
 757 *       p_gid
 758 *               [out] Pointer to the GID structure to fill in.
 759 *
 760 * RETURN VALUES
 761 *     IB_SUCCESS if able to find the GID by address given.
 762 *
 763 * NOTES
 764 *
 765 * SEE ALSO
 766 *********/
 767
 768 /****f* OpenSM: Helper/osm_get_physp_by_mad_addr
 769 * NAME
 770 *       osm_get_physp_by_mad_addr
 771 *
 772 * DESCRIPTION
 773 *       Looks for the requester physical port in the mad address.
 774 *
 775 * Note: This code is not thread safe. Need to grab the lock before
 776 * calling it.
 777 *
 778 * SYNOPSIS
 779 */
 780 struct osm_physp *osm_get_physp_by_mad_addr(IN struct osm_log *p_log,
 781                                              IN const osm_subn_t * p_subn,
 782                                              IN struct osm_mad_addr
 783                                              *p_mad_addr);
 784 /*
 785 * PARAMETERS
 786 *       p_log
 787 *               [in] Pointer to a log object.
 788 *
 789 *       p_subn
 790 *               [in] Pointer to subnet object.
 791 *
 792 *       p_mad_addr
 793 *               [in] Pointer to mad address object.
 794 *
 795 * RETURN VALUES
 796 *       Pointer to requester physical port object if found. Null otherwise.
 797 *
 798 * NOTES
 799 *
 800 * SEE ALSO
 801 *********/
 802
 803 /****f* OpenSM: Helper/osm_get_port_by_mad_addr
 804 * NAME
 805 *       osm_get_port_by_mad_addr
 806 *
 807 * DESCRIPTION
 808 *       Looks for the requester port in the mad address.
 809 *
 810 * Note: This code is not thread safe. Need to grab the lock before
 811 * calling it.
 812 *
 813 * SYNOPSIS
 814 */
 815 struct osm_port *osm_get_port_by_mad_addr(IN struct osm_log *p_log,
 816                                            IN const osm_subn_t * p_subn,
 817                                            IN struct osm_mad_addr *p_mad_addr);
 818 /*
 819 * PARAMETERS
 820 *       p_log
 821 *               [in] Pointer to a log object.
 822 *
 823 *       p_subn
 824 *               [in] Pointer to subnet object.
 825 *
 826 *       p_mad_addr
 827 *               [in] Pointer to mad address object.
 828 *
 829 * RETURN VALUES
 830 *       Pointer to requester port object if found. Null otherwise.
 831 *
 832 * NOTES
 833 *
 834 * SEE ALSO
 835 *********/
 836
 837 /****f* OpenSM: Subnet/osm_get_switch_by_guid
 838 * NAME
 839 *       osm_get_switch_by_guid
 840 *
 841 * DESCRIPTION
 842 *       Looks for the given switch guid in the subnet table of switches by guid.
 843 *  NOTE: this code is not thread safe. Need to grab the lock before
 844 *  calling it.
 845 *
 846 * SYNOPSIS
 847 */
 848 struct osm_switch *osm_get_switch_by_guid(IN const osm_subn_t * p_subn,
 849                                            IN uint64_t guid);
 850 /*
 851 * PARAMETERS
 852 *       p_subn
 853 *               [in] Pointer to an osm_subn_t object
 854 *
 855 *       guid
 856 *               [in] The node guid in host order
 857 *
 858 * RETURN VALUES
 859 *       The switch structure pointer if found. NULL otherwise.
 860 *
 861 * SEE ALSO
 862 *       Subnet object, osm_subn_construct, osm_subn_destroy,
 863 *       osm_switch_t
 864 *********/
 865
 866 /****f* OpenSM: Subnet/osm_get_node_by_guid
 867 * NAME
 868 *       osm_get_node_by_guid
 869 *
 870 * DESCRIPTION
 871 *       The looks for the given node giud in the subnet table of nodes by guid.
 872 *  NOTE: this code is not thread safe. Need to grab the lock before
 873 *  calling it.
 874 *
 875 * SYNOPSIS
 876 */
 877 struct osm_node *osm_get_node_by_guid(IN osm_subn_t const *p_subn,
 878                                        IN uint64_t guid);
 879 /*
 880 * PARAMETERS
 881 *       p_subn
 882 *               [in] Pointer to an osm_subn_t object
 883 *
 884 *       guid
 885 *               [in] The node guid in host order
 886 *
 887 * RETURN VALUES
 888 *       The node structure pointer if found. NULL otherwise.
 889 *
 890 * SEE ALSO
 891 *       Subnet object, osm_subn_construct, osm_subn_destroy,
 892 *       osm_node_t
 893 *********/
 894
 895 /****f* OpenSM: Subnet/osm_get_port_by_guid
 896 * NAME
 897 *       osm_get_port_by_guid
 898 *
 899 * DESCRIPTION
 900 *       The looks for the given port guid in the subnet table of ports by guid.
 901 *  NOTE: this code is not thread safe. Need to grab the lock before
 902 *  calling it.
 903 *
 904 * SYNOPSIS
 905 */
 906 struct osm_port *osm_get_port_by_guid(IN osm_subn_t const *p_subn,
 907                                        IN ib_net64_t guid);
 908 /*
 909 * PARAMETERS
 910 *       p_subn
 911 *               [in] Pointer to an osm_subn_t object
 912 *
 913 *       guid
 914 *               [in] The port guid in network order
 915 *
 916 * RETURN VALUES
 917 *       The port structure pointer if found. NULL otherwise.
 918 *
 919 * SEE ALSO
 920 *       Subnet object, osm_subn_construct, osm_subn_destroy,
 921 *       osm_port_t
 922 *********/
 923
 924 /****f* OpenSM: Subnet/osm_get_mgrp_by_mlid
 925 * NAME
 926 *       osm_get_mgrp_by_mlid
 927 *
 928 * DESCRIPTION
 929 *       The looks for the given multicast group in the subnet table by mlid.
 930 *       NOTE: this code is not thread safe. Need to grab the lock before
 931 *       calling it.
 932 *
 933 * SYNOPSIS
 934 */
 935 static inline
 936 struct osm_mgrp *osm_get_mgrp_by_mlid(osm_subn_t const *p_subn, ib_net16_t mlid)
 937 {
 938         return p_subn->mgroups[cl_ntoh16(mlid) - IB_LID_MCAST_START_HO];
 939 }
 940 /*
 941 * PARAMETERS
 942 *       p_subn
 943 *               [in] Pointer to an osm_subn_t object
 944 *
 945 *       mlid
 946 *               [in] The multicast group mlid in network order
 947 *
 948 * RETURN VALUES
 949 *       The multicast group structure pointer if found. NULL otherwise.
 950 *********/
 951
 952 /****f* OpenSM: Helper/osm_get_physp_by_mad_addr
 953 * NAME
 954 *       osm_get_physp_by_mad_addr
 955 *
 956 * DESCRIPTION
 957 *       Looks for the requester physical port in the mad address.
 958 *
 959 * Note: This code is not thread safe. Need to grab the lock before
 960 * calling it.
 961 *
 962 * SYNOPSIS
 963 */
 964 struct osm_physp *osm_get_physp_by_mad_addr(IN struct osm_log *p_log,
 965                                              IN const osm_subn_t * p_subn,
 966                                              IN struct osm_mad_addr
 967                                              *p_mad_addr);
 968 /*
 969 * PARAMETERS
 970 *       p_log
 971 *               [in] Pointer to a log object.
 972 *
 973 *       p_subn
 974 *               [in] Pointer to subnet object.
 975 *
 976 *       p_mad_addr
 977 *               [in] Pointer to mad address object.
 978 *
 979 * RETURN VALUES
 980 *       Pointer to requester physical port object if found. Null otherwise.
 981 *
 982 * NOTES
 983 *
 984 * SEE ALSO
 985 *********/
 986
 987 /****f* OpenSM: Subnet/osm_subn_set_default_opt
 988 * NAME
 989 *       osm_subn_set_default_opt
 990 *
 991 * DESCRIPTION
 992 *       The osm_subn_set_default_opt function sets the default options.
 993 *
 994 * SYNOPSIS
 995 */
 996 void osm_subn_set_default_opt(IN osm_subn_opt_t * const p_opt);
 997 /*
 998 * PARAMETERS
 999 *
1000 *       p_opt
1001 *               [in] Pointer to the subnet options structure.
1002 *
1003 * RETURN VALUES
1004 *       None
1005 *
1006 * NOTES
1007 *
1008 * SEE ALSO
1009 *       Subnet object, osm_subn_construct, osm_subn_destroy
1010 *********/
1011
1012 /****f* OpenSM: Subnet/osm_subn_parse_conf_file
1013 * NAME
1014 *       osm_subn_parse_conf_file
1015 *
1016 * DESCRIPTION
1017 *       The osm_subn_parse_conf_file function parses the configuration file
1018 *       and sets the defaults accordingly.
1019 *
1020 * SYNOPSIS
1021 */
1022 int osm_subn_parse_conf_file(char *conf_file, osm_subn_opt_t * const p_opt);
1023 /*
1024 * PARAMETERS
1025 *
1026 *       p_opt
1027 *               [in] Pointer to the subnet options structure.
1028 *
1029 * RETURN VALUES
1030 *       0 on success, positive value if file doesn't exist,
1031 *       negative value otherwise
1032 *********/
1033
1034 /****f* OpenSM: Subnet/osm_subn_rescan_conf_files
1035 * NAME
1036 *       osm_subn_rescan_conf_files
1037 *
1038 * DESCRIPTION
1039 *       The osm_subn_rescan_conf_files function parses the configuration
1040 *       files and update selected subnet options
1041 *
1042 * SYNOPSIS
1043 */
1044 int osm_subn_rescan_conf_files(IN osm_subn_t * const p_subn);
1045 /*
1046 * PARAMETERS
1047 *
1048 *       p_subn
1049 *               [in] Pointer to the subnet structure.
1050 *
1051 * RETURN VALUES
1052 *       0 on success, positive value if file doesn't exist,
1053 *       negative value otherwise
1054 *
1055 *********/
1056
1057 /****f* OpenSM: Subnet/osm_subn_output_conf
1058 * NAME
1059 *       osm_subn_output_conf
1060 *
1061 * DESCRIPTION
1062 *       Output configuration info
1063 *
1064 * SYNOPSIS
1065 */
1066 int osm_subn_output_conf(FILE *out, IN osm_subn_opt_t * const p_opt);
1067 /*
1068 * PARAMETERS
1069 *
1070 *       out
1071 *               [in] File stream to output to.
1072 *
1073 *       p_opt
1074 *               [in] Pointer to the subnet options structure.
1075 *
1076 * RETURN VALUES
1077 *       0 on success, negative value otherwise
1078 *********/
1079
1080 /****f* OpenSM: Subnet/osm_subn_write_conf_file
1081 * NAME
1082 *       osm_subn_write_conf_file
1083 *
1084 * DESCRIPTION
1085 *       Write the configuration file into the cache
1086 *
1087 * SYNOPSIS
1088 */
1089 int osm_subn_write_conf_file(char *file_name, IN osm_subn_opt_t * const p_opt);
1090 /*
1091 * PARAMETERS
1092 *
1093 *       p_opt
1094 *               [in] Pointer to the subnet options structure.
1095 *
1096 * RETURN VALUES
1097 *       0 on success, negative value otherwise
1098 *
1099 * NOTES
1100 *       Assumes the conf file is part of the cache dir which defaults to
1101 *       OSM_DEFAULT_CACHE_DIR or OSM_CACHE_DIR the name is opensm.opts
1102 *********/
1103 int osm_subn_verify_config(osm_subn_opt_t * const p_opt);
1104
1105 END_C_DECLS
1106 #endif                          /* _OSM_SUBNET_H_ */