contrib/ofed/management/opensm/include/opensm/osm_lid_mgr.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_lid_mgr_t.
  39  *      This object represents the LID Manager object.
  40  *      This object is part of the OpenSM family of objects.
  41  */
  42
  43 #ifndef _OSM_LID_MGR_H_
  44 #define _OSM_LID_MGR_H_
  45
  46 #include <complib/cl_passivelock.h>
  47 #include <opensm/osm_base.h>
  48 #include <opensm/osm_madw.h>
  49 #include <opensm/osm_subnet.h>
  50 #include <opensm/osm_db.h>
  51 #include <opensm/osm_log.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 #define OSM_LID_MGR_LIST_SIZE_MIN 256
  63 /****h* OpenSM/LID Manager
  64 * NAME
  65 *       LID Manager
  66 *
  67 * DESCRIPTION
  68 *       The LID Manager object encapsulates the information
  69 *       needed to control LID assignments on the subnet.
  70 *
  71 *       The LID 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: LID Manager/osm_lid_mgr_t
  82 * NAME
  83 *       osm_lid_mgr_t
  84 *
  85 * DESCRIPTION
  86 *       LID 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_lid_mgr {
  94         struct osm_sm *sm;
  95         osm_subn_t *p_subn;
  96         osm_db_t *p_db;
  97         osm_log_t *p_log;
  98         cl_plock_t *p_lock;
  99         boolean_t send_set_reqs;
 100         osm_db_domain_t *p_g2l;
 101         cl_ptr_vector_t used_lids;
 102         cl_qlist_t free_ranges;
 103 } osm_lid_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_db
 113 *               Pointer to the database (persistency) object
 114 *
 115 *       p_log
 116 *               Pointer to the log object.
 117 *
 118 *       p_lock
 119 *               Pointer to the serializing lock.
 120 *
 121 *       send_set_reqs
 122 *               Boolean to indicate whether any set requests sent.
 123 *
 124 *       p_g2l
 125 *               Pointer to the database domain storing guid to lid mapping.
 126 *
 127 *       used_lids
 128 *               A vector the maps from the lid to its guid. keeps track of
 129 *               existing and non existing mapping of guid->lid
 130 *
 131 *       free_ranges
 132 *               A list of available free lid ranges. The list is initialized
 133 *               by the code that initializes the lid assignment and is consumed
 134 *               by the procedure that finds a free range. It holds elements of
 135 *               type osm_lid_mgr_range_t
 136 *
 137 * SEE ALSO
 138 *       LID Manager object
 139 *********/
 140
 141 /****f* OpenSM: LID Manager/osm_lid_mgr_construct
 142 * NAME
 143 *       osm_lid_mgr_construct
 144 *
 145 * DESCRIPTION
 146 *       This function constructs a LID Manager object.
 147 *
 148 * SYNOPSIS
 149 */
 150 void osm_lid_mgr_construct(IN osm_lid_mgr_t * const p_mgr);
 151 /*
 152 * PARAMETERS
 153 *       p_mgr
 154 *               [in] Pointer to a LID Manager object to construct.
 155 *
 156 * RETURN VALUE
 157 *       This function does not return a value.
 158 *
 159 * NOTES
 160 *       Allows osm_lid_mgr_destroy
 161 *
 162 *       Calling osm_lid_mgr_construct is a prerequisite to calling any other
 163 *       method except osm_lid_mgr_init.
 164 *
 165 * SEE ALSO
 166 *       LID Manager object, osm_lid_mgr_init,
 167 *       osm_lid_mgr_destroy
 168 *********/
 169
 170 /****f* OpenSM: LID Manager/osm_lid_mgr_destroy
 171 * NAME
 172 *       osm_lid_mgr_destroy
 173 *
 174 * DESCRIPTION
 175 *       The osm_lid_mgr_destroy function destroys the object, releasing
 176 *       all resources.
 177 *
 178 * SYNOPSIS
 179 */
 180 void osm_lid_mgr_destroy(IN osm_lid_mgr_t * const p_mgr);
 181 /*
 182 * PARAMETERS
 183 *       p_mgr
 184 *               [in] Pointer to the object to destroy.
 185 *
 186 * RETURN VALUE
 187 *       This function does not return a value.
 188 *
 189 * NOTES
 190 *       Performs any necessary cleanup of the specified
 191 *       LID Manager object.
 192 *       Further operations should not be attempted on the destroyed object.
 193 *       This function should only be called after a call to
 194 *       osm_lid_mgr_construct or osm_lid_mgr_init.
 195 *
 196 * SEE ALSO
 197 *       LID Manager object, osm_lid_mgr_construct,
 198 *       osm_lid_mgr_init
 199 *********/
 200
 201 /****f* OpenSM: LID Manager/osm_lid_mgr_init
 202 * NAME
 203 *       osm_lid_mgr_init
 204 *
 205 * DESCRIPTION
 206 *       The osm_lid_mgr_init function initializes a
 207 *       LID Manager object for use.
 208 *
 209 * SYNOPSIS
 210 */
 211 ib_api_status_t
 212 osm_lid_mgr_init(IN osm_lid_mgr_t * const p_mgr, IN struct osm_sm * sm);
 213 /*
 214 * PARAMETERS
 215 *       p_mgr
 216 *               [in] Pointer to an osm_lid_mgr_t object to initialize.
 217 *
 218 *       sm
 219 *               [in] Pointer to the SM object for this subnet.
 220 *
 221 * RETURN VALUES
 222 *       CL_SUCCESS if the LID Manager object was initialized
 223 *       successfully.
 224 *
 225 * NOTES
 226 *       Allows calling other LID Manager methods.
 227 *
 228 * SEE ALSO
 229 *       LID Manager object, osm_lid_mgr_construct,
 230 *       osm_lid_mgr_destroy
 231 *********/
 232
 233 /****f* OpenSM: LID Manager/osm_lid_mgr_process_sm
 234 * NAME
 235 *       osm_lid_mgr_process_sm
 236 *
 237 * DESCRIPTION
 238 *       Configures the SM's port with its designated LID values.
 239 *
 240 * SYNOPSIS
 241 */
 242 osm_signal_t osm_lid_mgr_process_sm(IN osm_lid_mgr_t * const p_mgr);
 243 /*
 244 * PARAMETERS
 245 *       p_mgr
 246 *               [in] Pointer to an osm_lid_mgr_t object.
 247 *
 248 * RETURN VALUES
 249 *       Returns the appropriate signal to the caller:
 250 *               OSM_SIGNAL_DONE - operation is complete
 251 *               OSM_SIGNAL_DONE_PENDING - local operations are complete, but
 252 *                       transactions are still pending on the wire.
 253 *
 254 * NOTES
 255 *
 256 * SEE ALSO
 257 *       LID Manager
 258 *********/
 259
 260 /****f* OpenSM: LID Manager/osm_lid_mgr_process_subnet
 261 * NAME
 262 *       osm_lid_mgr_process_subnet
 263 *
 264 * DESCRIPTION
 265 *       Configures subnet ports (except the SM port itself) with their
 266 *       designated LID values.
 267 *
 268 * SYNOPSIS
 269 */
 270 osm_signal_t osm_lid_mgr_process_subnet(IN osm_lid_mgr_t * const p_mgr);
 271 /*
 272 * PARAMETERS
 273 *       p_mgr
 274 *               [in] Pointer to an osm_lid_mgr_t object.
 275 *
 276 * RETURN VALUES
 277 *       Returns the appropriate signal to the caller:
 278 *               OSM_SIGNAL_DONE - operation is complete
 279 *               OSM_SIGNAL_DONE_PENDING - local operations are complete, but
 280 *                       transactions are still pending on the wire.
 281 *
 282 * NOTES
 283 *
 284 * SEE ALSO
 285 *       LID Manager
 286 *********/
 287
 288 END_C_DECLS
 289 #endif                          /* _OSM_LID_MGR_H_ */