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

   1 /*
   2  * Copyright (c) 2004, 2005 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_vl15_t.
  39  *      This object represents an IBA subnet.
  40  *      This object is part of the OpenSM family of objects.
  41  */
  42
  43 #ifndef _OSM_VL15INTF_H_
  44 #define _OSM_VL15INTF_H_
  45
  46 #include <iba/ib_types.h>
  47 #include <complib/cl_spinlock.h>
  48 #include <complib/cl_event.h>
  49 #include <complib/cl_thread.h>
  50 #include <complib/cl_qlist.h>
  51 #include <opensm/osm_stats.h>
  52 #include <opensm/osm_log.h>
  53 #include <opensm/osm_madw.h>
  54 #include <opensm/osm_mad_pool.h>
  55 #include <vendor/osm_vendor_api.h>
  56
  57 #ifdef __cplusplus
  58 #  define BEGIN_C_DECLS extern "C" {
  59 #  define END_C_DECLS   }
  60 #else                           /* !__cplusplus */
  61 #  define BEGIN_C_DECLS
  62 #  define END_C_DECLS
  63 #endif                          /* __cplusplus */
  64
  65 BEGIN_C_DECLS
  66 /****h* OpenSM/VL15
  67 * NAME
  68 *       VL15
  69 *
  70 * DESCRIPTION
  71 *       The VL15 object encapsulates the information needed by the
  72 *       OpenSM to instantiate the VL15 interface.  The OpenSM allocates
  73 *       one VL15 object per subnet.
  74 *
  75 *       The VL15 object transmits MADs to the wire at a throttled rate,
  76 *       so as to not overload the VL15 buffering of subnet components.
  77 *       OpenSM modules may post VL15 MADs to the VL15 interface as fast
  78 *       as possible.
  79 *
  80 *       The VL15 object is thread safe.
  81 *
  82 *       This object should be treated as opaque and should
  83 *       be manipulated only through the provided functions.
  84 *
  85 * AUTHOR
  86 *       Steve King, Intel
  87 *
  88 *********/
  89 /****d* OpenSM: SM/osm_vl15_state_t
  90 * NAME
  91 *       osm_vl15_state_t
  92 *
  93 * DESCRIPTION
  94 *       Enumerates the possible states of SM object.
  95 *
  96 * SYNOPSIS
  97 */
  98 typedef enum _osm_vl15_state {
  99         OSM_VL15_STATE_INIT = 0,
 100         OSM_VL15_STATE_READY
 101 } osm_vl15_state_t;
 102 /***********/
 103
 104 /****s* OpenSM: VL15/osm_vl15_t
 105 * NAME
 106 *       osm_vl15_t
 107 *
 108 * DESCRIPTION
 109 *       VL15 structure.
 110 *
 111 *       This object should be treated as opaque and should
 112 *       be manipulated only through the provided functions.
 113 *
 114 * SYNOPSIS
 115 */
 116 typedef struct osm_vl15 {
 117         osm_thread_state_t thread_state;
 118         osm_vl15_state_t state;
 119         uint32_t max_wire_smps;
 120         cl_event_t signal;
 121         cl_thread_t poller;
 122         cl_qlist_t rfifo;
 123         cl_qlist_t ufifo;
 124         cl_spinlock_t lock;
 125         osm_vendor_t *p_vend;
 126         osm_log_t *p_log;
 127         osm_stats_t *p_stats;
 128 } osm_vl15_t;
 129 /*
 130 * FIELDS
 131 *       thread_state
 132 *               Tracks the thread state of the poller thread.
 133 *
 134 *       state
 135 *               Tracks the state of the VL15 interface itself.
 136 *
 137 *       max_wire_smps
 138 *               Maximum number of VL15 MADs allowed on the wire at one time.
 139 *
 140 *       signal
 141 *               Event on which the poller sleeps.
 142 *
 143 *       rfifo
 144 *               First-in First-out queue for outbound VL15 MADs for which
 145 *               a response is expected, aka the "response fifo"
 146 *
 147 *       ufifo
 148 *               First-in First-out queue for outbound VL15 MADs for which
 149 *               no response is expected, aka the "unicast fifo".
 150 *
 151 *       poller
 152 *               Worker thread pool that services the fifo to transmit VL15 MADs
 153 *
 154 *       lock
 155 *               Spinlock guarding the FIFO.
 156 *
 157 *       p_vend
 158 *               Pointer to the vendor transport object.
 159 *
 160 *       p_log
 161 *               Pointer to the log object.
 162 *
 163 *       p_stats
 164 *               Pointer to the OpenSM statistics block.
 165 *
 166 * SEE ALSO
 167 *       VL15 object
 168 *********/
 169
 170 /****f* OpenSM: VL15/osm_vl15_construct
 171 * NAME
 172 *       osm_vl15_construct
 173 *
 174 * DESCRIPTION
 175 *       This function constructs an VL15 object.
 176 *
 177 * SYNOPSIS
 178 */
 179 void osm_vl15_construct(IN osm_vl15_t * const p_vl15);
 180 /*
 181 * PARAMETERS
 182 *       p_vl15
 183 *               [in] Pointer to a VL15 object to construct.
 184 *
 185 * RETURN VALUE
 186 *       This function does not return a value.
 187 *
 188 * NOTES
 189 *       Allows calling osm_vl15_destroy.
 190 *
 191 *       Calling osm_vl15_construct is a prerequisite to calling any other
 192 *       method except osm_vl15_init.
 193 *
 194 * SEE ALSO
 195 *       VL15 object, osm_vl15_init, osm_vl15_destroy
 196 *********/
 197
 198 /****f* OpenSM: VL15/osm_vl15_destroy
 199 * NAME
 200 *       osm_vl15_destroy
 201 *
 202 * DESCRIPTION
 203 *       The osm_vl15_destroy function destroys the object, releasing
 204 *       all resources.
 205 *
 206 * SYNOPSIS
 207 */
 208 void
 209 osm_vl15_destroy(IN osm_vl15_t * const p_vl15, IN struct osm_mad_pool *p_pool);
 210 /*
 211 * PARAMETERS
 212 *       p_vl15
 213 *               [in] Pointer to a VL15 object to destroy.
 214 *
 215 *  p_pool
 216 *     [in] The pointer to the mad pool to return outstanding mads to
 217 *
 218 * RETURN VALUE
 219 *       This function does not return a value.
 220 *
 221 * NOTES
 222 *       Performs any necessary cleanup of the specified VL15 object.
 223 *       Further operations should not be attempted on the destroyed object.
 224 *       This function should only be called after a call to osm_vl15_construct or
 225 *       osm_vl15_init.
 226 *
 227 * SEE ALSO
 228 *       VL15 object, osm_vl15_construct, osm_vl15_init
 229 *********/
 230
 231 /*
 232         Initialization.
 233         Rate specifies the minimum number of microseconds between transmissions
 234         on VL15.
 235 */
 236 /****f* OpenSM: VL15/osm_vl15_init
 237 * NAME
 238 *       osm_vl15_init
 239 *
 240 * DESCRIPTION
 241 *       The osm_vl15_init function initializes a VL15 object for use.
 242 *
 243 * SYNOPSIS
 244 */
 245 ib_api_status_t
 246 osm_vl15_init(IN osm_vl15_t * const p_vl15,
 247               IN osm_vendor_t * const p_vend,
 248               IN osm_log_t * const p_log,
 249               IN osm_stats_t * const p_stats,
 250               IN const int32_t max_wire_smps);
 251 /*
 252 * PARAMETERS
 253 *       p_vl15
 254 *               [in] Pointer to an osm_vl15_t object to initialize.
 255 *
 256 *       p_vend
 257 *               [in] Pointer to the vendor transport object.
 258 *
 259 *       p_log
 260 *               [in] Pointer to the log object.
 261 *
 262 *       p_stats
 263 *               [in] Pointer to the OpenSM stastics block.
 264 *
 265 *       max_wire_smps
 266 *               [in] Maximum number of MADs allowed on the wire at one time.
 267 *
 268 * RETURN VALUES
 269 *       IB_SUCCESS if the VL15 object was initialized successfully.
 270 *
 271 * NOTES
 272 *       Allows calling other VL15 methods.
 273 *
 274 * SEE ALSO
 275 *       VL15 object, osm_vl15_construct, osm_vl15_destroy
 276 *********/
 277
 278 /****f* OpenSM: VL15/osm_vl15_post
 279 * NAME
 280 *       osm_vl15_post
 281 *
 282 * DESCRIPTION
 283 *       Posts a MAD to the VL15 interface for transmission.
 284 *
 285 * SYNOPSIS
 286 */
 287 void osm_vl15_post(IN osm_vl15_t * const p_vl15, IN osm_madw_t * const p_madw);
 288 /*
 289 * PARAMETERS
 290 *       p_vl15
 291 *               [in] Pointer to an osm_vl15_t object.
 292 *
 293 *       p_madw
 294 *               [in] Pointer to a MAD wrapper structure containing the MAD.
 295 *
 296 * RETURN VALUES
 297 *       This function does not return a value.
 298 *
 299 * NOTES
 300 *       The osm_vl15_construct or osm_vl15_init must be called before using
 301 *       this function.
 302 *
 303 * SEE ALSO
 304 *       VL15 object, osm_vl15_construct, osm_vl15_init
 305 *********/
 306
 307 /****f* OpenSM: VL15/osm_vl15_poll
 308 * NAME
 309 *       osm_vl15_poll
 310 *
 311 * DESCRIPTION
 312 *       Causes the VL15 Interface to consider sending another QP0 MAD.
 313 *
 314 * SYNOPSIS
 315 */
 316 void osm_vl15_poll(IN osm_vl15_t * const p_vl);
 317 /*
 318 * PARAMETERS
 319 *       p_vl15
 320 *               [in] Pointer to an osm_vl15_t object.
 321 *
 322 * RETURN VALUES
 323 *       None.
 324 *
 325 * NOTES
 326 *       This function signals the VL15 that it may be possible to send
 327 *       a SMP.  This function checks three criteria before sending a SMP:
 328 *       1) The VL15 worker is IDLE
 329 *       2) There are no QP0 SMPs currently outstanding
 330 *       3) There is something on the VL15 FIFO to send
 331 *
 332 * SEE ALSO
 333 *       VL15 object, osm_vl15_construct, osm_vl15_init
 334 *********/
 335
 336 /****f* OpenSM: VL15/osm_vl15_shutdown
 337 * NAME
 338 *       osm_vl15_shutdown
 339 *
 340 * DESCRIPTION
 341 *       Cleanup all outstanding MADs on both fifo's.
 342 *  This is required to return all outstanding MAD resources.
 343 *
 344 * SYNOPSIS
 345 */
 346 void
 347 osm_vl15_shutdown(IN osm_vl15_t * const p_vl,
 348                   IN osm_mad_pool_t * const p_mad_pool);
 349 /*
 350 * PARAMETERS
 351 *       p_vl15
 352 *               [in] Pointer to an osm_vl15_t object.
 353 *
 354 *  p_mad_pool
 355 *     [in] The MAD pool owning the mads.
 356 *
 357 * RETURN VALUES
 358 *       None.
 359 *
 360 * NOTES
 361 *
 362 * SEE ALSO
 363 *       VL15 object, osm_vl15_construct, osm_vl15_init
 364 *********/
 365
 366 END_C_DECLS
 367 #endif                          /* _OSM_VL15INTF_H_ */