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

   1 /*
   2  * Copyright (c) 2004-2008 Voltaire, Inc. All rights reserved.
   3  * Copyright (c) 2002-2006 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_opensm_t.
  39  *      This object represents the OpenSM super object.
  40  *      This object is part of the OpenSM family of objects.
  41  */
  42
  43 #ifndef _OSM_OPENSM_H_
  44 #define _OSM_OPENSM_H_
  45
  46 #include <stdio.h>
  47 #include <complib/cl_qlist.h>
  48 #include <complib/cl_dispatcher.h>
  49 #include <complib/cl_passivelock.h>
  50 #include <complib/cl_atomic.h>
  51 #include <complib/cl_nodenamemap.h>
  52 #include <opensm/osm_console_io.h>
  53 #include <opensm/osm_stats.h>
  54 #include <opensm/osm_log.h>
  55 #include <opensm/osm_sm.h>
  56 #include <opensm/osm_sa.h>
  57 #include <opensm/osm_perfmgr.h>
  58 #include <opensm/osm_event_plugin.h>
  59 #include <opensm/osm_db.h>
  60 #include <opensm/osm_subnet.h>
  61 #include <opensm/osm_mad_pool.h>
  62 #include <opensm/osm_vl15intf.h>
  63
  64 #ifdef __cplusplus
  65 #  define BEGIN_C_DECLS extern "C" {
  66 #  define END_C_DECLS   }
  67 #else                           /* !__cplusplus */
  68 #  define BEGIN_C_DECLS
  69 #  define END_C_DECLS
  70 #endif                          /* __cplusplus */
  71
  72 BEGIN_C_DECLS
  73 /****h* OpenSM/OpenSM
  74 * NAME
  75 *       OpenSM
  76 *
  77 * DESCRIPTION
  78 *       The OpenSM object encapsulates the information needed by the
  79 *       OpenSM to govern itself.  The OpenSM is one OpenSM object.
  80 *
  81 *       The OpenSM object is thread safe.
  82 *
  83 *       This object should be treated as opaque and should
  84 *       be manipulated only through the provided functions.
  85 *
  86 * AUTHOR
  87 *       Steve King, Intel
  88 *
  89 *********/
  90 /****d* OpenSM: OpenSM/osm_routing_engine_type_t
  91 * NAME
  92 *       osm_routing_engine_type_t
  93 *
  94 * DESCRIPTION
  95 *       Enumerates the possible routing engines that
  96 *       could be used to route a subnet.
  97 *
  98 * SYNOPSIS
  99 */
 100 typedef enum _osm_routing_engine_type {
 101         OSM_ROUTING_ENGINE_TYPE_NONE = 0,
 102         OSM_ROUTING_ENGINE_TYPE_MINHOP,
 103         OSM_ROUTING_ENGINE_TYPE_UPDN,
 104         OSM_ROUTING_ENGINE_TYPE_FILE,
 105         OSM_ROUTING_ENGINE_TYPE_FTREE,
 106         OSM_ROUTING_ENGINE_TYPE_LASH,
 107         OSM_ROUTING_ENGINE_TYPE_DOR,
 108         OSM_ROUTING_ENGINE_TYPE_UNKNOWN
 109 } osm_routing_engine_type_t;
 110 /***********/
 111
 112 /****s* OpenSM: OpenSM/osm_routing_engine
 113 * NAME
 114 *       struct osm_routing_engine
 115 *
 116 * DESCRIPTION
 117 *       OpenSM routing engine module definition.
 118 * NOTES
 119 *       routing engine structure - multicast callbacks may be
 120 *       added later.
 121 */
 122 struct osm_routing_engine {
 123         const char *name;
 124         void *context;
 125         int (*build_lid_matrices) (void *context);
 126         int (*ucast_build_fwd_tables) (void *context);
 127         void (*ucast_dump_tables) (void *context);
 128         void (*delete) (void *context);
 129         struct osm_routing_engine *next;
 130 };
 131 /*
 132 * FIELDS
 133 *       name
 134 *               The routing engine name (will be used in logs).
 135 *
 136 *       context
 137 *               The routing engine context. Will be passed as parameter
 138 *               to the callback functions.
 139 *
 140 *       build_lid_matrices
 141 *               The callback for lid matrices generation.
 142 *
 143 *       ucast_build_fwd_tables
 144 *               The callback for unicast forwarding table generation.
 145 *
 146 *       ucast_dump_tables
 147 *               The callback for dumping unicast routing tables.
 148 *
 149 *       delete
 150 *               The delete method, may be used for routing engine
 151 *               internals cleanup.
 152 *
 153 *       next
 154 *               Pointer to next routing engine in the list.
 155 */
 156
 157 /****s* OpenSM: OpenSM/osm_opensm_t
 158 * NAME
 159 *       osm_opensm_t
 160 *
 161 * DESCRIPTION
 162 *       OpenSM structure.
 163 *
 164 *       This object should be treated as opaque and should
 165 *       be manipulated only through the provided functions.
 166 *
 167 * SYNOPSIS
 168 */
 169 typedef struct osm_opensm {
 170         const char *osm_version;
 171         osm_subn_t subn;
 172         osm_sm_t sm;
 173         osm_sa_t sa;
 174 #ifdef ENABLE_OSM_PERF_MGR
 175         osm_perfmgr_t perfmgr;
 176 #endif                          /* ENABLE_OSM_PERF_MGR */
 177         cl_qlist_t plugin_list;
 178         osm_db_t db;
 179         osm_mad_pool_t mad_pool;
 180         osm_vendor_t *p_vendor;
 181         osm_vl15_t vl15;
 182         osm_log_t log;
 183         cl_dispatcher_t disp;
 184         cl_plock_t lock;
 185         struct osm_routing_engine *routing_engine_list;
 186         osm_routing_engine_type_t routing_engine_used;
 187         osm_stats_t stats;
 188         osm_console_t console;
 189         nn_map_t *node_name_map;
 190 } osm_opensm_t;
 191 /*
 192 * FIELDS
 193 *       osm_version
 194 *               OpenSM version (as generated in osm_version.h)
 195 *
 196 *       subn
 197 *               Subnet object for this subnet.
 198 *
 199 *       sm
 200 *               The Subnet Manager (SM) object for this subnet.
 201 *
 202 *       sa
 203 *               The Subnet Administration (SA) object for this subnet.
 204 *
 205 *       db
 206 *               Persistant storage of some data required between sessions.
 207 *
 208 *       mad_pool
 209 *               Pool of Management Datagram (MAD) objects.
 210 *
 211 *       p_vendor
 212 *               Pointer to the Vendor specific adapter for various
 213 *               transport interfaces, such as UMADT, AL, etc.  The
 214 *               particular interface is set at compile time.
 215 *
 216 *       vl15
 217 *               The VL15 interface.
 218 *
 219 *       log
 220 *               Log facility used by all OpenSM components.
 221 *
 222 *       disp
 223 *               Central dispatcher containing the OpenSM worker threads.
 224 *
 225 *       lock
 226 *               Shared lock guarding most OpenSM structures.
 227 *
 228 *       routing_engine_list
 229 *               List of routing engines that should be tried for use.
 230 *
 231 *       routing_engine_used
 232 *               Indicates which routing engine was used to route a subnet.
 233 *
 234 *       stats
 235 *               Open SM statistics block
 236 *
 237 * SEE ALSO
 238 *********/
 239
 240 /****f* OpenSM: OpenSM/osm_opensm_construct
 241 * NAME
 242 *       osm_opensm_construct
 243 *
 244 * DESCRIPTION
 245 *       This function constructs an OpenSM object.
 246 *
 247 * SYNOPSIS
 248 */
 249 void osm_opensm_construct(IN osm_opensm_t * const p_osm);
 250 /*
 251 * PARAMETERS
 252 *       p_osm
 253 *               [in] Pointer to a OpenSM object to construct.
 254 *
 255 * RETURN VALUE
 256 *       This function does not return a value.
 257 *
 258 * NOTES
 259 *       Allows calling osm_opensm_init, osm_opensm_destroy
 260 *
 261 *       Calling osm_opensm_construct is a prerequisite to calling any other
 262 *       method except osm_opensm_init.
 263 *
 264 * SEE ALSO
 265 *       SM object, osm_opensm_init, osm_opensm_destroy
 266 *********/
 267
 268 /****f* OpenSM: OpenSM/osm_opensm_destroy
 269 * NAME
 270 *       osm_opensm_destroy
 271 *
 272 * DESCRIPTION
 273 *       The osm_opensm_destroy function destroys an SM, releasing
 274 *       all resources.
 275 *
 276 * SYNOPSIS
 277 */
 278 void osm_opensm_destroy(IN osm_opensm_t * const p_osm);
 279 /*
 280 * PARAMETERS
 281 *       p_osm
 282 *               [in] Pointer to a OpenSM object to destroy.
 283 *
 284 * RETURN VALUE
 285 *       This function does not return a value.
 286 *
 287 * NOTES
 288 *       Performs any necessary cleanup of the specified OpenSM object.
 289 *       Further operations should not be attempted on the destroyed object.
 290 *       This function should only be called after a call to osm_opensm_construct or
 291 *       osm_opensm_init.
 292 *
 293 * SEE ALSO
 294 *       SM object, osm_opensm_construct, osm_opensm_init
 295 *********/
 296
 297 /****f* OpenSM: OpenSM/osm_opensm_init
 298 * NAME
 299 *       osm_opensm_init
 300 *
 301 * DESCRIPTION
 302 *       The osm_opensm_init function initializes a OpenSM object for use.
 303 *
 304 * SYNOPSIS
 305 */
 306 ib_api_status_t
 307 osm_opensm_init(IN osm_opensm_t * const p_osm,
 308                 IN const osm_subn_opt_t * const p_opt);
 309 /*
 310 * PARAMETERS
 311 *       p_osm
 312 *               [in] Pointer to an osm_opensm_t object to initialize.
 313 *
 314 *       p_opt
 315 *               [in] Pointer to the subnet options structure.
 316 *
 317 * RETURN VALUES
 318 *       IB_SUCCESS if the OpenSM object was initialized successfully.
 319 *
 320 * NOTES
 321 *       Allows calling other OpenSM methods.
 322 *
 323 * SEE ALSO
 324 *       SM object, osm_opensm_construct, osm_opensm_destroy
 325 *********/
 326
 327 /****f* OpenSM: OpenSM/osm_opensm_sweep
 328 * NAME
 329 *       osm_opensm_sweep
 330 *
 331 * DESCRIPTION
 332 *       Initiates a subnet sweep.
 333 *
 334 * SYNOPSIS
 335 */
 336 static inline void osm_opensm_sweep(IN osm_opensm_t * const p_osm)
 337 {
 338         osm_sm_sweep(&p_osm->sm);
 339 }
 340
 341 /*
 342 * PARAMETERS
 343 *       p_osm
 344 *               [in] Pointer to an osm_opensm_t object on which to
 345 *               initiate a sweep.
 346 *
 347 * RETURN VALUES
 348 *       None
 349 *
 350 * NOTES
 351 *       If the OpenSM object is not bound to a port, this function
 352 *       does nothing.
 353 *
 354 * SEE ALSO
 355 *********/
 356
 357 /****f* OpenSM: OpenSM/osm_opensm_set_log_flags
 358 * NAME
 359 *       osm_opensm_set_log_flags
 360 *
 361 * DESCRIPTION
 362 *       Sets the log level.
 363 *
 364 * SYNOPSIS
 365 */
 366 static inline void
 367 osm_opensm_set_log_flags(IN osm_opensm_t * const p_osm,
 368                          IN const osm_log_level_t log_flags)
 369 {
 370         osm_log_set_level(&p_osm->log, log_flags);
 371 }
 372
 373 /*
 374 * PARAMETERS
 375 *       p_osm
 376 *               [in] Pointer to an osm_opensm_t object.
 377 *
 378 *       log_flags
 379 *               [in] Log level flags to set.
 380 *
 381 * RETURN VALUES
 382 *       None
 383 *
 384 * NOTES
 385 *
 386 * SEE ALSO
 387 *********/
 388
 389 /****f* OpenSM: OpenSM/osm_opensm_bind
 390 * NAME
 391 *       osm_opensm_bind
 392 *
 393 * DESCRIPTION
 394 *       Binds the opensm object to a port guid.
 395 *
 396 * SYNOPSIS
 397 */
 398 ib_api_status_t
 399 osm_opensm_bind(IN osm_opensm_t * const p_osm, IN const ib_net64_t guid);
 400 /*
 401 * PARAMETERS
 402 *       p_osm
 403 *               [in] Pointer to an osm_opensm_t object to bind.
 404 *
 405 *       guid
 406 *               [in] Local port GUID with which to bind.
 407 *
 408 * RETURN VALUES
 409 *       None
 410 *
 411 * NOTES
 412 *       A given opensm object can only be bound to one port at a time.
 413 *
 414 * SEE ALSO
 415 *********/
 416
 417 /****f* OpenSM: OpenSM/osm_opensm_wait_for_subnet_up
 418 * NAME
 419 *       osm_opensm_wait_for_subnet_up
 420 *
 421 * DESCRIPTION
 422 *       Blocks the calling thread until the subnet is up.
 423 *
 424 * SYNOPSIS
 425 */
 426 static inline cl_status_t
 427 osm_opensm_wait_for_subnet_up(IN osm_opensm_t * const p_osm,
 428                               IN uint32_t const wait_us,
 429                               IN boolean_t const interruptible)
 430 {
 431         return (osm_sm_wait_for_subnet_up(&p_osm->sm, wait_us, interruptible));
 432 }
 433
 434 /*
 435 * PARAMETERS
 436 *       p_osm
 437 *               [in] Pointer to an osm_opensm_t object.
 438 *
 439 *       wait_us
 440 *               [in] Number of microseconds to wait.
 441 *
 442 *       interruptible
 443 *               [in] Indicates whether the wait operation can be interrupted
 444 *               by external signals.
 445 *
 446 * RETURN VALUES
 447 *       CL_SUCCESS if the wait operation succeeded in response to the event
 448 *       being set.
 449 *
 450 *       CL_TIMEOUT if the specified time period elapses.
 451 *
 452 *       CL_NOT_DONE if the wait was interrupted by an external signal.
 453 *
 454 *       CL_ERROR if the wait operation failed.
 455 *
 456 * NOTES
 457 *
 458 * SEE ALSO
 459 *********/
 460
 461 /****f* OpenSM: OpenSM/osm_routing_engine_type_str
 462 * NAME
 463 *       osm_routing_engine_type_str
 464 *
 465 * DESCRIPTION
 466 *       Returns a string for the specified routing engine type.
 467 *
 468 * SYNOPSIS
 469 */
 470 const char *osm_routing_engine_type_str(IN osm_routing_engine_type_t type);
 471 /*
 472 * PARAMETERS
 473 *       type
 474 *               [in] routing engine type.
 475 *
 476 * RETURN VALUES
 477 *       Pointer to routing engine name.
 478 *
 479 * NOTES
 480 *
 481 * SEE ALSO
 482 *********/
 483
 484 /****f* OpenSM: OpenSM/osm_routing_engine_type
 485 * NAME
 486 *       osm_routing_engine_type
 487 *
 488 * DESCRIPTION
 489 *       Returns a routing engine type specified routing engine name string.
 490 *
 491 * SYNOPSIS
 492 */
 493 osm_routing_engine_type_t osm_routing_engine_type(IN const char *str);
 494 /*
 495 * PARAMETERS
 496 *       str
 497 *               [in] routing engine name string.
 498 *
 499 * RETURN VALUES
 500 *       Routing engine type.
 501 *
 502 * NOTES
 503 *
 504 * SEE ALSO
 505 *********/
 506
 507 void osm_opensm_report_event(osm_opensm_t *osm, osm_epi_event_id_t event_id,
 508                              void *event_data);
 509
 510 /* dump helpers */
 511 void osm_dump_mcast_routes(osm_opensm_t * osm);
 512 void osm_dump_all(osm_opensm_t * osm);
 513 void osm_dump_qmap_to_file(osm_opensm_t * p_osm, const char *file_name,
 514                            cl_qmap_t * map,
 515                            void (*func) (cl_map_item_t *, FILE *, void *),
 516                            void *cxt);
 517
 518 /****v* OpenSM/osm_exit_flag
 519 */
 520 extern volatile unsigned int osm_exit_flag;
 521 /*
 522 * DESCRIPTION
 523 *  Set to one to cause all threads to leave
 524 *********/
 525
 526 END_C_DECLS
 527 #endif                          /* _OSM_OPENSM_H_ */