/* * Copyright (c) 2004-2009 Voltaire, Inc. All rights reserved. * Copyright (c) 2002-2006 Mellanox Technologies LTD. All rights reserved. * Copyright (c) 1996-2003 Intel Corporation. All rights reserved. * Copyright (c) 2009-2011 ZIH, TU Dresden, Federal Republic of Germany. All rights reserved. * Copyright (C) 2012-2017 Tokyo Institute of Technology. All rights reserved. * Copyright (c) 2019 Fabriscale Technologies AS. All rights reserved. * * This software is available to you under a choice of one of two * licenses. You may choose to be licensed under the terms of the GNU * General Public License (GPL) Version 2, available from the file * COPYING in the main directory of this source tree, or the * OpenIB.org BSD license below: * * Redistribution and use in source and binary forms, with or * without modification, are permitted provided that the following * conditions are met: * * - Redistributions of source code must retain the above * copyright notice, this list of conditions and the following * disclaimer. * * - Redistributions in binary form must reproduce the above * copyright notice, this list of conditions and the following * disclaimer in the documentation and/or other materials * provided with the distribution. * * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS * BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN * ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE * SOFTWARE. * */ /* * Abstract: * Declaration of osm_opensm_t. * This object represents the OpenSM super object. * This object is part of the OpenSM family of objects. */ #ifndef _OSM_OPENSM_H_ #define _OSM_OPENSM_H_ #include #include #include #include #include #include #include #include #include #include #include #include #include #include #include #include #include #include #ifdef __cplusplus # define BEGIN_C_DECLS extern "C" { # define END_C_DECLS } #else /* !__cplusplus */ # define BEGIN_C_DECLS # define END_C_DECLS #endif /* __cplusplus */ BEGIN_C_DECLS /****h* OpenSM/OpenSM * NAME * OpenSM * * DESCRIPTION * The OpenSM object encapsulates the information needed by the * OpenSM to govern itself. The OpenSM is one OpenSM object. * * The OpenSM object is thread safe. * * This object should be treated as opaque and should * be manipulated only through the provided functions. * * AUTHOR * Steve King, Intel * *********/ /****d* OpenSM: OpenSM/osm_routing_engine_type_t * NAME * osm_routing_engine_type_t * * DESCRIPTION * Enumerates the possible routing engines that * could be used to route a subnet. * * SYNOPSIS */ typedef enum _osm_routing_engine_type { OSM_ROUTING_ENGINE_TYPE_NONE = 0, OSM_ROUTING_ENGINE_TYPE_MINHOP, OSM_ROUTING_ENGINE_TYPE_UPDN, OSM_ROUTING_ENGINE_TYPE_DNUP, OSM_ROUTING_ENGINE_TYPE_FILE, OSM_ROUTING_ENGINE_TYPE_FTREE, OSM_ROUTING_ENGINE_TYPE_LASH, OSM_ROUTING_ENGINE_TYPE_DOR, OSM_ROUTING_ENGINE_TYPE_TORUS_2QOS, OSM_ROUTING_ENGINE_TYPE_NUE, OSM_ROUTING_ENGINE_TYPE_SSSP, OSM_ROUTING_ENGINE_TYPE_DFSSSP, OSM_ROUTING_ENGINE_TYPE_UNKNOWN, OSM_ROUTING_ENGINE_TYPE_EXTERNAL } osm_routing_engine_type_t; /***********/ /****s* OpenSM: OpenSM/osm_routing_engine * NAME * struct osm_routing_engine * * DESCRIPTION * OpenSM routing engine module definition. * NOTES * routing engine structure - multicast callbacks may be * added later. */ typedef struct osm_routing_engine { osm_routing_engine_type_t type; const char *name; void *context; int (*build_lid_matrices) (void *context); int (*ucast_build_fwd_tables) (void *context); void (*ucast_dump_tables) (void *context); void (*update_sl2vl)(void *context, IN osm_physp_t *port, IN uint8_t in_port_num, IN uint8_t out_port_num, IN OUT ib_slvl_table_t *t); void (*update_vlarb)(void *context, IN osm_physp_t *port, IN uint8_t port_num, IN OUT ib_vl_arb_table_t *block, unsigned block_length, unsigned block_num); uint8_t (*path_sl)(void *context, IN uint8_t path_sl_hint, IN const ib_net16_t slid, IN const ib_net16_t dlid); ib_api_status_t (*mcast_build_stree)(void *context, IN OUT osm_mgrp_box_t *mgb); void (*destroy) (void *context); struct osm_routing_engine *next; } osm_routing_engine_t; /* * FIELDS * name * The routing engine name (will be used in logs). * * context * The routing engine context. Will be passed as parameter * to the callback functions. * * build_lid_matrices * The callback for lid matrices generation. * * ucast_build_fwd_tables * The callback for unicast forwarding table generation. * * ucast_dump_tables * The callback for dumping unicast routing tables. * * update_sl2vl(void *context, IN osm_physp_t *port, * IN uint8_t in_port_num, IN uint8_t out_port_num, * OUT ib_slvl_table_t *t) * The callback to allow routing engine input for SL2VL maps. * *port is the physical port for which the SL2VL map is to be * updated. For switches, in_port_num/out_port_num identify * which part of the SL2VL map to update. For router/HCA ports, * in_port_num/out_port_num should be ignored. * * update_vlarb(void *context, IN osm_physp_t *port, * IN uint8_t port_num, * IN OUT ib_vl_arb_table_t *block, * unsigned block_length, unsigned block_num) * The callback to allow routing engine input for VLArbitration. * *port is the physical port for which the VLArb table is to be * updated. * * path_sl * The callback for computing path SL. * * mcast_build_stree * The callback for building the spanning tree for multicast * forwarding, called per MLID. * * destroy * The destroy method, may be used for routing engine * internals cleanup. * * next * Pointer to next routing engine in the list. */ /****s* OpenSM: OpenSM/external_routing_engine_module_t * NAME * external_routing_engine_module_t * * DESCRIPTION * External routing engine module structure. * * This structure is used to register a new external routing engine * * SYNOPSIS */ typedef struct external_routing_engine_module { const char *name; int (*setup)(struct osm_routing_engine *re, struct osm_opensm *osm); void *context; } external_routing_engine_module_t; /* * FIELDS * name * Name of the external routing engine * * setup * function to setup the external routing engine's callbacks * * context * User defined context * * SEE ALSO * osm_register_external_routing_engine *********/ /****s* OpenSM: OpenSM/osm_opensm_t * NAME * osm_opensm_t * * DESCRIPTION * OpenSM structure. * * This object should be treated as opaque and should * be manipulated only through the provided functions. * * SYNOPSIS */ typedef struct osm_opensm { const char *osm_version; osm_subn_t subn; osm_sm_t sm; osm_sa_t sa; #ifdef ENABLE_OSM_PERF_MGR osm_perfmgr_t perfmgr; #endif /* ENABLE_OSM_PERF_MGR */ osm_congestion_control_t cc; cl_qlist_t plugin_list; osm_db_t db; boolean_t mad_pool_constructed; osm_mad_pool_t mad_pool; osm_vendor_t *p_vendor; boolean_t vl15_constructed; osm_vl15_t vl15; osm_log_t log; cl_dispatcher_t disp; cl_dispatcher_t sa_set_disp; boolean_t sa_set_disp_initialized; cl_plock_t lock; struct osm_routing_engine *routing_engine_list; struct osm_routing_engine *routing_engine_used; struct osm_routing_engine *default_routing_engine; boolean_t no_fallback_routing_engine; osm_stats_t stats; osm_console_t console; nn_map_t *node_name_map; } osm_opensm_t; /* * FIELDS * osm_version * OpenSM version (as generated in osm_version.h) * * subn * Subnet object for this subnet. * * sm * The Subnet Manager (SM) object for this subnet. * * sa * The Subnet Administration (SA) object for this subnet. * * db * Persistant storage of some data required between sessions. * * mad_pool * Pool of Management Datagram (MAD) objects. * * p_vendor * Pointer to the Vendor specific adapter for various * transport interfaces, such as UMADT, AL, etc. The * particular interface is set at compile time. * * vl15 * The VL15 interface. * * log * Log facility used by all OpenSM components. * * disp * Central dispatcher containing the OpenSM worker threads. * * sa_set_disp * Dispatcher for SA Set and Delete requests. * * sa_set_disp_initialized. * Indicator that sa_set_disp dispatcher was initialized. * * lock * Shared lock guarding most OpenSM structures. * * routing_engine_list * List of routing engines that should be tried for use. * * routing_engine_used * Indicates which routing engine was used to route a subnet. * * no_fallback_routing_engine * Indicates if default routing engine should not be used. * * stats * Open SM statistics block * * SEE ALSO *********/ /****f* OpenSM: OpenSM/osm_opensm_construct * NAME * osm_opensm_construct * * DESCRIPTION * This function constructs an OpenSM object. * * SYNOPSIS */ void osm_opensm_construct(IN osm_opensm_t * p_osm); /* * PARAMETERS * p_osm * [in] Pointer to a OpenSM object to construct. * * RETURN VALUE * This function does not return a value. * * NOTES * Allows calling osm_opensm_init, osm_opensm_destroy * * Calling osm_opensm_construct is a prerequisite to calling any other * method except osm_opensm_init. * * SEE ALSO * SM object, osm_opensm_init, osm_opensm_destroy *********/ /****f* OpenSM: OpenSM/osm_opensm_construct_finish * NAME * osm_opensm_construct_finish * * DESCRIPTION * The osm_opensm_construct_finish function completes * the second phase of constucting an OpenSM object. * * SYNOPSIS */ void osm_opensm_construct_finish(IN osm_opensm_t * p_osm); /* * PARAMETERS * p_osm * [in] Pointer to a OpenSM object to construct. * * RETURN VALUE * This function does not return a value. * * NOTES * Calling osm_opensm_construct/osm_construct_finish is a prerequisite * to calling any other method except osm_opensm_init/osm_opensm_init_finish. * * SEE ALSO * SM object, osm_opensm_init, osm_opensm_construct_finish, * osm_opensm_destroy, osm_opensm_destroy_finish *********/ /****f* OpenSM: OpenSM/osm_opensm_destroy * NAME * osm_opensm_destroy * * DESCRIPTION * The osm_opensm_destroy function destroys an SM, releasing * all resources. * * SYNOPSIS */ void osm_opensm_destroy(IN osm_opensm_t * p_osm); /* * PARAMETERS * p_osm * [in] Pointer to a OpenSM object to destroy. * * RETURN VALUE * This function does not return a value. * * NOTES * Performs any necessary cleanup of the specified OpenSM object. * Further operations should not be attempted on the destroyed object. * This function should only be called after a call to osm_opensm_construct or * osm_opensm_init. * * SEE ALSO * SM object, osm_opensm_construct, osm_opensm_init *********/ /****f* OpenSM: OpenSM/osm_opensm_destroy_finish * NAME * osm_opensm_destroy_finish * * DESCRIPTION * The osm_opensm_destroy_finish function handles the second phase * of destroying an SM, releasing all resources. * * SYNOPSIS */ void osm_opensm_destroy_finish(IN osm_opensm_t * p_osm); /* * PARAMETERS * p_osm * [in] Pointer to a OpenSM object to destroy. * * RETURN VALUE * This function does not return a value. * * NOTES * Performs second phase of any necessary cleanup of the specified OpenSM object. * Further operations should not be attempted on the destroyed object. * This function should only be called after a call to * osm_opensm_construct_finish or osm_opensm_init_finish. * * SEE ALSO * SM object, osm_opensm_construct, osm_opensm_construct_finish, * osm_opensm_init, osm_opensm_init_finish *********/ /****f* OpenSM: OpenSM/osm_opensm_init * NAME * osm_opensm_init * * DESCRIPTION * The osm_opensm_init function initializes a OpenSM object for use. * * SYNOPSIS */ ib_api_status_t osm_opensm_init(IN osm_opensm_t * p_osm, IN const osm_subn_opt_t * p_opt); /* * PARAMETERS * p_osm * [in] Pointer to an osm_opensm_t object to initialize. * * p_opt * [in] Pointer to the subnet options structure. * * RETURN VALUES * IB_SUCCESS if the OpenSM object was initialized successfully. * * NOTES * Allows calling other OpenSM methods. * * SEE ALSO * SM object, osm_opensm_construct, osm_opensm_destroy *********/ /****f* OpenSM: OpenSM/osm_opensm_init_finish * NAME * osm_opensm_init_finish * * DESCRIPTION * The osm_opensm_init_finish function performs the second phase * of initialization of an OpenSM object. * * SYNOPSIS */ ib_api_status_t osm_opensm_init_finish(IN osm_opensm_t * p_osm, IN const osm_subn_opt_t * p_opt); /* * PARAMETERS * p_osm * [in] Pointer to an osm_opensm_t object to initialize. * * p_opt * [in] Pointer to the subnet options structure. * * RETURN VALUES * IB_SUCCESS if the OpenSM object was initialized successfully. * * NOTES * Allows calling other OpenSM methods. * * SEE ALSO * SM object, osm_opensm_construct, osm_opensm_construct_finish, * osm_opensm_destroy, osm_opensm_destroy_finish *********/ /****f* OpenSM: OpenSM/osm_opensm_sweep * NAME * osm_opensm_sweep * * DESCRIPTION * Initiates a subnet sweep. * * SYNOPSIS */ static inline void osm_opensm_sweep(IN osm_opensm_t * p_osm) { osm_sm_sweep(&p_osm->sm); } /* * PARAMETERS * p_osm * [in] Pointer to an osm_opensm_t object on which to * initiate a sweep. * * RETURN VALUES * None * * NOTES * If the OpenSM object is not bound to a port, this function * does nothing. * * SEE ALSO *********/ /****f* OpenSM: OpenSM/osm_opensm_set_log_flags * NAME * osm_opensm_set_log_flags * * DESCRIPTION * Sets the log level. * * SYNOPSIS */ static inline void osm_opensm_set_log_flags(IN osm_opensm_t * p_osm, IN osm_log_level_t log_flags) { osm_log_set_level(&p_osm->log, log_flags); } /* * PARAMETERS * p_osm * [in] Pointer to an osm_opensm_t object. * * log_flags * [in] Log level flags to set. * * RETURN VALUES * None * * NOTES * * SEE ALSO *********/ /****f* OpenSM: OpenSM/osm_opensm_bind * NAME * osm_opensm_bind * * DESCRIPTION * Binds the opensm object to a port guid. * * SYNOPSIS */ ib_api_status_t osm_opensm_bind(IN osm_opensm_t * p_osm, IN ib_net64_t guid); /* * PARAMETERS * p_osm * [in] Pointer to an osm_opensm_t object to bind. * * guid * [in] Local port GUID with which to bind. * * RETURN VALUES * None * * NOTES * A given opensm object can only be bound to one port at a time. * * SEE ALSO *********/ /****f* OpenSM: OpenSM/osm_opensm_wait_for_subnet_up * NAME * osm_opensm_wait_for_subnet_up * * DESCRIPTION * Blocks the calling thread until the subnet is up. * * SYNOPSIS */ static inline cl_status_t osm_opensm_wait_for_subnet_up(IN osm_opensm_t * p_osm, IN uint32_t wait_us, IN boolean_t interruptible) { return osm_sm_wait_for_subnet_up(&p_osm->sm, wait_us, interruptible); } /* * PARAMETERS * p_osm * [in] Pointer to an osm_opensm_t object. * * wait_us * [in] Number of microseconds to wait. * * interruptible * [in] Indicates whether the wait operation can be interrupted * by external signals. * * RETURN VALUES * CL_SUCCESS if the wait operation succeeded in response to the event * being set. * * CL_TIMEOUT if the specified time period elapses. * * CL_NOT_DONE if the wait was interrupted by an external signal. * * CL_ERROR if the wait operation failed. * * NOTES * * SEE ALSO *********/ /****f* OpenSM: OpenSM/osm_register_external_routing_engine * NAME * osm_register_external_routing_engine * * DESCRIPTION * Register a new external routing engine. * * SYNOPSIS */ cl_status_t osm_register_external_routing_engine( IN osm_opensm_t *osm, IN const external_routing_engine_module_t *module, IN void *context); /* * PARAMETERS * type * [in] Pointer to a osm_opensm_t object * [in] Pointer to a external_routing_engine_module_t object to be registered. * [in] Pointer to a user context that will be set in osm_routing_engine_t * * RETURN VALUES * CL_SUCCESS if the routing engine was registered successfully. * CL_DUPLICATE if a routing engine with the same name * or type was already registered. * * NOTES * * SEE ALSO * external_routing_engine_module_t *********/ /****f* OpenSM: OpenSM/osm_routing_engine_type_str * NAME * osm_routing_engine_type_str * * DESCRIPTION * Returns a string for the specified routing engine type. * * SYNOPSIS */ const char *osm_routing_engine_type_str(IN osm_routing_engine_type_t type); /* * PARAMETERS * type * [in] routing engine type. * * RETURN VALUES * Pointer to routing engine name. * * NOTES * * SEE ALSO *********/ /****f* OpenSM: OpenSM/osm_routing_engine_type * NAME * osm_routing_engine_type * * DESCRIPTION * Returns a routing engine type specified routing engine name string. * * SYNOPSIS */ osm_routing_engine_type_t osm_routing_engine_type(IN const char *str); /* * PARAMETERS * str * [in] routing engine name string. * * RETURN VALUES * Routing engine type. * * NOTES * * SEE ALSO *********/ void osm_opensm_report_event(osm_opensm_t *osm, osm_epi_event_id_t event_id, void *event_data); /* dump helpers */ void osm_dump_mcast_routes(osm_opensm_t * osm); void osm_dump_all(osm_opensm_t * osm); void osm_dump_qmap_to_file(osm_opensm_t * p_osm, const char *file_name, cl_qmap_t * map, void (*func) (cl_map_item_t *, FILE *, void *), void *cxt); /****v* OpenSM/osm_exit_flag */ extern volatile unsigned int osm_exit_flag; /* * DESCRIPTION * Set to one to cause all threads to leave *********/ END_C_DECLS #endif /* _OSM_OPENSM_H_ */