contrib/ofed/management/opensm/include/opensm/osm_ucast_mgr.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  *
   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_ucast_mgr_t.
  39  *      This object represents the Unicast Manager object.
  40  *      This object is part of the OpenSM family of objects.
  41  */
  42
  43 #ifndef _OSM_UCAST_MGR_H_
  44 #define _OSM_UCAST_MGR_H_
  45
  46 #include <complib/cl_passivelock.h>
  47 #include <complib/cl_qlist.h>
  48 #include <opensm/osm_madw.h>
  49 #include <opensm/osm_subnet.h>
  50 #include <opensm/osm_switch.h>
  51 #include <opensm/osm_log.h>
  52 #include <opensm/osm_ucast_cache.h>
  53
  54 #ifdef __cplusplus
  55 #  define BEGIN_C_DECLS extern "C" {
  56 #  define END_C_DECLS   }
  57 #else                           /* !__cplusplus */
  58 #  define BEGIN_C_DECLS
  59 #  define END_C_DECLS
  60 #endif                          /* __cplusplus */
  61
  62 BEGIN_C_DECLS
  63 /****h* OpenSM/Unicast Manager
  64 * NAME
  65 *       Unicast Manager
  66 *
  67 * DESCRIPTION
  68 *       The Unicast Manager object encapsulates the information
  69 *       needed to control unicast LID forwarding on the subnet.
  70 *
  71 *       The Unicast Manager object is thread safe.
  72 *
  73 *       This object should be treated as opaque and should be
  74 *       manipulated only through the provided functions.
  75 *
  76 * AUTHOR
  77 *       Steve King, Intel
  78 *
  79 *********/
  80 struct osm_sm;
  81 /****s* OpenSM: Unicast Manager/osm_ucast_mgr_t
  82 * NAME
  83 *       osm_ucast_mgr_t
  84 *
  85 * DESCRIPTION
  86 *       Unicast Manager structure.
  87 *
  88 *       This object should be treated as opaque and should
  89 *       be manipulated only through the provided functions.
  90 *
  91 * SYNOPSIS
  92 */
  93 typedef struct osm_ucast_mgr {
  94         struct osm_sm *sm;
  95         osm_subn_t *p_subn;
  96         osm_log_t *p_log;
  97         cl_plock_t *p_lock;
  98         cl_qlist_t port_order_list;
  99         boolean_t is_dor;
 100         boolean_t some_hop_count_set;
 101         cl_qmap_t cache_sw_tbl;
 102         boolean_t cache_valid;
 103 } osm_ucast_mgr_t;
 104 /*
 105 * FIELDS
 106 *       sm
 107 *               Pointer to the SM object.
 108 *
 109 *       p_subn
 110 *               Pointer to the Subnet object for this subnet.
 111 *
 112 *       p_log
 113 *               Pointer to the log object.
 114 *
 115 *       p_lock
 116 *               Pointer to the serializing lock.
 117 *
 118 *       is_dor
 119 *               Dimension Order Routing (DOR) will be done
 120 *
 121 *       port_order_list
 122 *               List of ports ordered for routing.
 123 *
 124 *       any_change
 125 *               Initialized to FALSE at the beginning of the algorithm,
 126 *               set to TRUE by osm_ucast_mgr_set_fwd_table() if any mad
 127 *               was sent.
 128 *
 129 *       some_hop_count_set
 130 *               Initialized to FALSE at the beginning of each the min hop
 131 *               tables calculation iteration cycle, set to TRUE to indicate
 132 *               that some hop count changes were done.
 133 *
 134 *       cache_sw_tbl
 135 *               Cached switches table.
 136 *
 137 *       cache_valid
 138 *               TRUE if the unicast cache is valid.
 139 *
 140 * SEE ALSO
 141 *       Unicast Manager object
 142 *********/
 143
 144 /****f* OpenSM: Unicast Manager/osm_ucast_mgr_construct
 145 * NAME
 146 *       osm_ucast_mgr_construct
 147 *
 148 * DESCRIPTION
 149 *       This function constructs a Unicast Manager object.
 150 *
 151 * SYNOPSIS
 152 */
 153 void osm_ucast_mgr_construct(IN osm_ucast_mgr_t * const p_mgr);
 154 /*
 155 * PARAMETERS
 156 *       p_mgr
 157 *               [in] Pointer to a Unicast Manager object to construct.
 158 *
 159 * RETURN VALUE
 160 *       This function does not return a value.
 161 *
 162 * NOTES
 163 *       Allows osm_ucast_mgr_destroy
 164 *
 165 *       Calling osm_ucast_mgr_construct is a prerequisite to calling any other
 166 *       method except osm_ucast_mgr_init.
 167 *
 168 * SEE ALSO
 169 *       Unicast Manager object, osm_ucast_mgr_init,
 170 *       osm_ucast_mgr_destroy
 171 *********/
 172
 173 /****f* OpenSM: Unicast Manager/osm_ucast_mgr_destroy
 174 * NAME
 175 *       osm_ucast_mgr_destroy
 176 *
 177 * DESCRIPTION
 178 *       The osm_ucast_mgr_destroy function destroys the object, releasing
 179 *       all resources.
 180 *
 181 * SYNOPSIS
 182 */
 183 void osm_ucast_mgr_destroy(IN osm_ucast_mgr_t * const p_mgr);
 184 /*
 185 * PARAMETERS
 186 *       p_mgr
 187 *               [in] Pointer to the object to destroy.
 188 *
 189 * RETURN VALUE
 190 *       This function does not return a value.
 191 *
 192 * NOTES
 193 *       Performs any necessary cleanup of the specified
 194 *       Unicast Manager object.
 195 *       Further operations should not be attempted on the destroyed object.
 196 *       This function should only be called after a call to
 197 *       osm_ucast_mgr_construct or osm_ucast_mgr_init.
 198 *
 199 * SEE ALSO
 200 *       Unicast Manager object, osm_ucast_mgr_construct,
 201 *       osm_ucast_mgr_init
 202 *********/
 203
 204 /****f* OpenSM: Unicast Manager/osm_ucast_mgr_init
 205 * NAME
 206 *       osm_ucast_mgr_init
 207 *
 208 * DESCRIPTION
 209 *       The osm_ucast_mgr_init function initializes a
 210 *       Unicast Manager object for use.
 211 *
 212 * SYNOPSIS
 213 */
 214 ib_api_status_t
 215 osm_ucast_mgr_init(IN osm_ucast_mgr_t * const p_mgr, IN struct osm_sm * sm);
 216 /*
 217 * PARAMETERS
 218 *       p_mgr
 219 *               [in] Pointer to an osm_ucast_mgr_t object to initialize.
 220 *
 221 *       sm
 222 *               [in] Pointer to the SM object.
 223 *
 224 * RETURN VALUES
 225 *       IB_SUCCESS if the Unicast Manager object was initialized
 226 *       successfully.
 227 *
 228 * NOTES
 229 *       Allows calling other Unicast Manager methods.
 230 *
 231 * SEE ALSO
 232 *       Unicast Manager object, osm_ucast_mgr_construct,
 233 *       osm_ucast_mgr_destroy
 234 *********/
 235
 236 /****f* OpenSM: Unicast Manager/osm_ucast_mgr_set_fwd_table
 237 * NAME
 238 *       osm_ucast_mgr_set_fwd_table
 239 *
 240 * DESCRIPTION
 241 *       Setup forwarding table for the switch (from prepared new_lft).
 242 *
 243 * SYNOPSIS
 244 */
 245 int osm_ucast_mgr_set_fwd_table(IN osm_ucast_mgr_t * const p_mgr,
 246                                 IN osm_switch_t * const p_sw);
 247 /*
 248 * PARAMETERS
 249 *       p_mgr
 250 *               [in] Pointer to an osm_ucast_mgr_t object.
 251 *
 252 *       p_mgr
 253 *               [in] Pointer to an osm_switch_t object.
 254 *
 255 * SEE ALSO
 256 *       Unicast Manager
 257 *********/
 258
 259 /****f* OpenSM: Unicast Manager/osm_ucast_mgr_build_lid_matrices
 260 * NAME
 261 *       osm_ucast_mgr_build_lid_matrices
 262 *
 263 * DESCRIPTION
 264 *       Build switches's lid matrices.
 265 *
 266 * SYNOPSIS
 267 */
 268 int osm_ucast_mgr_build_lid_matrices(IN osm_ucast_mgr_t * const p_mgr);
 269 /*
 270 * PARAMETERS
 271 *       p_mgr
 272 *               [in] Pointer to an osm_ucast_mgr_t object.
 273 *
 274 * NOTES
 275 *       This function processes the subnet, configuring switches'
 276 *       min hops tables (aka lid matrices).
 277 *
 278 * SEE ALSO
 279 *       Unicast Manager
 280 *********/
 281
 282 /****f* OpenSM: Unicast Manager/osm_ucast_mgr_process
 283 * NAME
 284 *       osm_ucast_mgr_process
 285 *
 286 * DESCRIPTION
 287 *       Process and configure the subnet's unicast forwarding tables.
 288 *
 289 * SYNOPSIS
 290 */
 291 int osm_ucast_mgr_process(IN osm_ucast_mgr_t * const p_mgr);
 292 /*
 293 * PARAMETERS
 294 *       p_mgr
 295 *               [in] Pointer to an osm_ucast_mgr_t object.
 296 *
 297 * RETURN VALUES
 298 *       Returns zero on success and negative value on failure.
 299 *
 300 * NOTES
 301 *       This function processes the subnet, configuring switch
 302 *       unicast forwarding tables.
 303 *
 304 * SEE ALSO
 305 *       Unicast Manager, Node Info Response Controller
 306 *********/
 307 END_C_DECLS
 308 #endif                          /* _OSM_UCAST_MGR_H_ */