1 /* 2 * Copyright (c) 2004-2009 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 * 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 * 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 * 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 * p_pool, 195 IN osm_bind_handle_t h_bind, 196 IN uint32_t total_size, 197 IN const osm_mad_addr_t * 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 * p_pool, IN osm_madw_t * p_madw); 239 /* 240 * PARAMETERS 241 * p_pool 242 * [in] Pointer to an osm_mad_pool_t object. 243 * 244 * p_madw 245 * [in] Pointer to a MAD Wrapper for a MAD that was previously 246 * retrieved from the pool. 247 * 248 * RETURN VALUES 249 * This function does not return a value. 250 * 251 * NOTES 252 * The osm_mad_pool_construct or osm_mad_pool_init must be called before 253 * using this function. 254 * 255 * SEE ALSO 256 * MAD Pool, osm_mad_pool_get 257 *********/ 258 259 /****f* OpenSM: MAD Pool/osm_mad_pool_get_wrapper 260 * NAME 261 * osm_mad_pool_get_wrapper 262 * 263 * DESCRIPTION 264 * Gets a only MAD wrapper from the pool (no wire MAD). 265 * 266 * SYNOPSIS 267 */ 268 osm_madw_t *osm_mad_pool_get_wrapper(IN osm_mad_pool_t * p_pool, 269 IN osm_bind_handle_t h_bind, 270 IN uint32_t total_size, 271 IN const ib_mad_t * p_mad, 272 IN const osm_mad_addr_t * p_mad_addr); 273 /* 274 * PARAMETERS 275 * p_pool 276 * [in] Pointer to an osm_mad_pool_t object. 277 * 278 * h_bind 279 * [in] Handle returned from osm_vendor_bind() call to the 280 * port for which this mad wrapper will be used. 281 * 282 * total_size 283 * [in] Total size, including MAD header of the MAD that will 284 * be attached to this wrapper. 285 * 286 * p_mad 287 * [in] Pointer to the MAD to attach to this wrapper. 288 * 289 * p_mad_addr 290 * [in] Pointer to the MAD address structure. This parameter 291 * may be NULL for directed route MADs. 292 * 293 * RETURN VALUES 294 * Returns a pointer to a MAD wrapper. 295 * A return value of NULL means no MAD wrappers are available. 296 * 297 * NOTES 298 * The MAD must eventually be returned to the pool with a call to 299 * osm_mad_pool_put. 300 * 301 * The osm_mad_pool_construct or osm_mad_pool_init must be called before 302 * using this function. 303 * 304 * SEE ALSO 305 * MAD Pool, osm_mad_pool_put 306 *********/ 307 308 /****f* OpenSM: MAD Pool/osm_mad_pool_get_wrapper_raw 309 * NAME 310 * osm_mad_pool_get_wrapper_raw 311 * 312 * DESCRIPTION 313 * Gets a only an uninitialized MAD wrapper from the pool (no wire MAD). 314 * 315 * SYNOPSIS 316 */ 317 osm_madw_t *osm_mad_pool_get_wrapper_raw(IN osm_mad_pool_t * p_pool); 318 /* 319 * PARAMETERS 320 * p_pool 321 * [in] Pointer to an osm_mad_pool_t object. 322 * 323 * RETURN VALUES 324 * Returns a pointer to a MAD wrapper. 325 * A return value of NULL means no MAD wrappers are available. 326 * 327 * NOTES 328 * The MAD must eventually be returned to the pool with a call to 329 * osm_mad_pool_put. 330 * 331 * The osm_mad_pool_construct or osm_mad_pool_init must be called before 332 * using this function. 333 * 334 * SEE ALSO 335 * MAD Pool, osm_mad_pool_put 336 *********/ 337 338 /****f* OpenSM: MAD Pool/osm_mad_pool_get_outstanding 339 * NAME 340 * osm_mad_pool_get_count 341 * 342 * DESCRIPTION 343 * Returns the running count of MADs currently outstanding from the pool. 344 * 345 * SYNOPSIS 346 */ 347 static inline uint32_t 348 osm_mad_pool_get_outstanding(IN const osm_mad_pool_t * p_pool) 349 { 350 return p_pool->mads_out; 351 } 352 353 /* 354 * PARAMETERS 355 * p_pool 356 * [in] Pointer to an osm_mad_pool_t object. 357 * 358 * RETURN VALUES 359 * Returns the running count of MADs currently outstanding from the pool. 360 * 361 * NOTES 362 * The osm_mad_pool_construct or osm_mad_pool_init must be called before 363 * using this function. 364 * 365 * SEE ALSO 366 * MAD Pool, osm_mad_pool_get 367 *********/ 368 369 END_C_DECLS 370 #endif /* _OSM_MAD_POOL_H_ */ 371