contrib/ofed/management/opensm/include/opensm/osm_mad_pool.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_mad_pool_t.
  39  *      This object represents a pool of management datagram (MAD) objects.
  40  *      This object is part of the OpenSM family of objects.
  41  */
  42
  43 #ifndef _OSM_MAD_POOL_H_
  44 #define _OSM_MAD_POOL_H_
  45
  46 #include <iba/ib_types.h>
  47 #include <complib/cl_atomic.h>
  48 #include <opensm/osm_base.h>
  49 #include <opensm/osm_madw.h>
  50 #include <vendor/osm_vendor.h>
  51
  52 #ifdef __cplusplus
  53 #  define BEGIN_C_DECLS extern "C" {
  54 #  define END_C_DECLS   }
  55 #else                           /* !__cplusplus */
  56 #  define BEGIN_C_DECLS
  57 #  define END_C_DECLS
  58 #endif                          /* __cplusplus */
  59
  60 BEGIN_C_DECLS
  61 /****h* OpenSM/MAD Pool
  62 * NAME
  63 *       MAD Pool
  64 *
  65 * DESCRIPTION
  66 *       The MAD Pool encapsulates the information needed by the
  67 *       OpenSM to manage a pool of MAD objects.  The OpenSM allocates
  68 *       one MAD Pool per IBA subnet.
  69 *
  70 *       The MAD Pool is thread safe.
  71 *
  72 *       This object should be treated as opaque and should be
  73 *       manipulated only through the provided functions.
  74 *
  75 * AUTHOR
  76 *       Steve King, Intel
  77 *
  78 *********/
  79 /****s* OpenSM: MAD Pool/osm_mad_pool_t
  80 * NAME
  81 *       osm_mad_pool_t
  82 *
  83 * DESCRIPTION
  84 *       MAD Pool structure.
  85 *
  86 *       This object should be treated as opaque and should
  87 *       be manipulated only through the provided functions.
  88 *
  89 * SYNOPSIS
  90 */
  91 typedef struct osm_mad_pool {
  92         atomic32_t mads_out;
  93 } osm_mad_pool_t;
  94 /*
  95 * FIELDS
  96 *       mads_out
  97 *               Running total of the number of MADs outstanding.
  98 *
  99 * SEE ALSO
 100 *       MAD Pool
 101 *********/
 102
 103 /****f* OpenSM: MAD Pool/osm_mad_pool_construct
 104 * NAME
 105 *       osm_mad_pool_construct
 106 *
 107 * DESCRIPTION
 108 *       This function constructs a MAD Pool.
 109 *
 110 * SYNOPSIS
 111 */
 112 void osm_mad_pool_construct(IN osm_mad_pool_t * const p_pool);
 113 /*
 114 * PARAMETERS
 115 *       p_pool
 116 *               [in] Pointer to a MAD Pool to construct.
 117 *
 118 * RETURN VALUE
 119 *       This function does not return a value.
 120 *
 121 * NOTES
 122 *       Allows calling osm_mad_pool_init, osm_mad_pool_destroy
 123 *
 124 *       Calling osm_mad_pool_construct is a prerequisite to calling any other
 125 *       method except osm_mad_pool_init.
 126 *
 127 * SEE ALSO
 128 *       MAD Pool, osm_mad_pool_init, osm_mad_pool_destroy
 129 *********/
 130
 131 /****f* OpenSM: MAD Pool/osm_mad_pool_destroy
 132 * NAME
 133 *       osm_mad_pool_destroy
 134 *
 135 * DESCRIPTION
 136 *       The osm_mad_pool_destroy function destroys a node, releasing
 137 *       all resources.
 138 *
 139 * SYNOPSIS
 140 */
 141 void osm_mad_pool_destroy(IN osm_mad_pool_t * const p_pool);
 142 /*
 143 * PARAMETERS
 144 *       p_pool
 145 *               [in] Pointer to a MAD Pool to destroy.
 146 *
 147 * RETURN VALUE
 148 *       This function does not return a value.
 149 *
 150 * NOTES
 151 *       Performs any necessary cleanup of the specified MAD Pool.
 152 *       Further operations should not be attempted on the destroyed object.
 153 *       This function should only be called after a call to osm_mad_pool_construct or
 154 *       osm_mad_pool_init.
 155 *
 156 * SEE ALSO
 157 *       MAD Pool, osm_mad_pool_construct, osm_mad_pool_init
 158 *********/
 159
 160 /****f* OpenSM: MAD Pool/osm_mad_pool_init
 161 * NAME
 162 *       osm_mad_pool_init
 163 *
 164 * DESCRIPTION
 165 *       The osm_mad_pool_init function initializes a MAD Pool for use.
 166 *
 167 * SYNOPSIS
 168 */
 169 ib_api_status_t osm_mad_pool_init(IN osm_mad_pool_t * const p_pool);
 170 /*
 171 * PARAMETERS
 172 *       p_pool
 173 *               [in] Pointer to an osm_mad_pool_t object to initialize.
 174 *
 175 * RETURN VALUES
 176 *       CL_SUCCESS if the MAD Pool was initialized successfully.
 177 *
 178 * NOTES
 179 *       Allows calling other MAD Pool methods.
 180 *
 181 * SEE ALSO
 182 *       MAD Pool, osm_mad_pool_construct, osm_mad_pool_destroy
 183 *********/
 184
 185 /****f* OpenSM: MAD Pool/osm_mad_pool_get
 186 * NAME
 187 *       osm_mad_pool_get
 188 *
 189 * DESCRIPTION
 190 *       Gets a MAD wrapper and wire MAD from the pool.
 191 *
 192 * SYNOPSIS
 193 */
 194 osm_madw_t *osm_mad_pool_get(IN osm_mad_pool_t * const p_pool,
 195                              IN osm_bind_handle_t h_bind,
 196                              IN const uint32_t total_size,
 197                              IN const osm_mad_addr_t * const p_mad_addr);
 198 /*
 199 * PARAMETERS
 200 *       p_pool
 201 *               [in] Pointer to an osm_mad_pool_t object.
 202 *
 203 *       h_bind
 204 *               [in] Handle returned from osm_vendor_bind() call to the
 205 *               port over which this mad will be sent.
 206 *
 207 *       total_size
 208 *               [in] Total size, including MAD header of the requested MAD.
 209 *
 210 *       p_mad_addr
 211 *               [in] Pointer to the MAD address structure.  This parameter
 212 *               may be NULL for directed route MADs.
 213 *
 214 * RETURN VALUES
 215 *       Returns a pointer to a MAD wrapper containing the MAD.
 216 *       A return value of NULL means no MADs are available.
 217 *
 218 * NOTES
 219 *       The MAD must eventually be returned to the pool with a call to
 220 *       osm_mad_pool_put.
 221 *
 222 *       The osm_mad_pool_construct or osm_mad_pool_init must be called before
 223 *       using this function.
 224 *
 225 * SEE ALSO
 226 *       MAD Pool, osm_mad_pool_put
 227 *********/
 228
 229 /****f* OpenSM: MAD Pool/osm_mad_pool_put
 230 * NAME
 231 *       osm_mad_pool_put
 232 *
 233 * DESCRIPTION
 234 *       Returns a MAD to the pool.
 235 *
 236 * SYNOPSIS
 237 */
 238 void osm_mad_pool_put(IN osm_mad_pool_t * const p_pool,
 239                       IN osm_madw_t * const p_madw);
 240 /*
 241 * PARAMETERS
 242 *       p_pool
 243 *               [in] Pointer to an osm_mad_pool_t object.
 244 *
 245 *       p_madw
 246 *               [in] Pointer to a MAD Wrapper for a MAD that was previously
 247 *               retrieved from the pool.
 248 *
 249 * RETURN VALUES
 250 *       This function does not return a value.
 251 *
 252 * NOTES
 253 *       The osm_mad_pool_construct or osm_mad_pool_init must be called before
 254 *       using this function.
 255 *
 256 * SEE ALSO
 257 *       MAD Pool, osm_mad_pool_get
 258 *********/
 259
 260 /****f* OpenSM: MAD Pool/osm_mad_pool_get_wrapper
 261 * NAME
 262 *       osm_mad_pool_get_wrapper
 263 *
 264 * DESCRIPTION
 265 *       Gets a only MAD wrapper from the pool (no wire MAD).
 266 *
 267 * SYNOPSIS
 268 */
 269 osm_madw_t *osm_mad_pool_get_wrapper(IN osm_mad_pool_t * const p_pool,
 270                                      IN osm_bind_handle_t h_bind,
 271                                      IN const uint32_t total_size,
 272                                      IN const ib_mad_t * const p_mad,
 273                                      IN const osm_mad_addr_t *
 274                                      const p_mad_addr);
 275 /*
 276 * PARAMETERS
 277 *       p_pool
 278 *               [in] Pointer to an osm_mad_pool_t object.
 279 *
 280 *       h_bind
 281 *               [in] Handle returned from osm_vendor_bind() call to the
 282 *               port for which this mad wrapper will be used.
 283 *
 284 *       total_size
 285 *               [in] Total size, including MAD header of the MAD that will
 286 *               be attached to this wrapper.
 287 *
 288 *       p_mad
 289 *               [in] Pointer to the MAD to attach to this wrapper.
 290 *
 291 *       p_mad_addr
 292 *               [in] Pointer to the MAD address structure.  This parameter
 293 *               may be NULL for directed route MADs.
 294 *
 295 * RETURN VALUES
 296 *       Returns a pointer to a MAD wrapper.
 297 *       A return value of NULL means no MAD wrappers are available.
 298 *
 299 * NOTES
 300 *       The MAD must eventually be returned to the pool with a call to
 301 *       osm_mad_pool_put.
 302 *
 303 *       The osm_mad_pool_construct or osm_mad_pool_init must be called before
 304 *       using this function.
 305 *
 306 * SEE ALSO
 307 *       MAD Pool, osm_mad_pool_put
 308 *********/
 309
 310 /****f* OpenSM: MAD Pool/osm_mad_pool_get_wrapper_raw
 311 * NAME
 312 *       osm_mad_pool_get_wrapper_raw
 313 *
 314 * DESCRIPTION
 315 *       Gets a only an uninitialized MAD wrapper from the pool (no wire MAD).
 316 *
 317 * SYNOPSIS
 318 */
 319 osm_madw_t *osm_mad_pool_get_wrapper_raw(IN osm_mad_pool_t * const p_pool);
 320 /*
 321 * PARAMETERS
 322 *       p_pool
 323 *               [in] Pointer to an osm_mad_pool_t object.
 324 *
 325 * RETURN VALUES
 326 *       Returns a pointer to a MAD wrapper.
 327 *       A return value of NULL means no MAD wrappers are available.
 328 *
 329 * NOTES
 330 *       The MAD must eventually be returned to the pool with a call to
 331 *       osm_mad_pool_put.
 332 *
 333 *       The osm_mad_pool_construct or osm_mad_pool_init must be called before
 334 *       using this function.
 335 *
 336 * SEE ALSO
 337 *       MAD Pool, osm_mad_pool_put
 338 *********/
 339
 340 /****f* OpenSM: MAD Pool/osm_mad_pool_get_outstanding
 341 * NAME
 342 *       osm_mad_pool_get_count
 343 *
 344 * DESCRIPTION
 345 *       Returns the running count of MADs currently outstanding from the pool.
 346 *
 347 * SYNOPSIS
 348 */
 349 static inline uint32_t
 350 osm_mad_pool_get_outstanding(IN const osm_mad_pool_t * const p_pool)
 351 {
 352         return (p_pool->mads_out);
 353 }
 354
 355 /*
 356 * PARAMETERS
 357 *       p_pool
 358 *               [in] Pointer to an osm_mad_pool_t object.
 359 *
 360 * RETURN VALUES
 361 *       Returns the running count of MADs currently outstanding from the pool.
 362 *
 363 * NOTES
 364 *       The osm_mad_pool_construct or osm_mad_pool_init must be called before
 365 *       using this function.
 366 *
 367 * SEE ALSO
 368 *       MAD Pool, osm_mad_pool_get
 369 *********/
 370
 371 END_C_DECLS
 372 #endif                          /* _OSM_MAD_POOL_H_ */