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.
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:
12 * Redistribution and use in source and binary forms, with or
13 * without modification, are permitted provided that the following
16 * - Redistributions of source code must retain the above
17 * copyright notice, this list of conditions and the following
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.
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
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.
43 #ifndef _OSM_MAD_POOL_H_
44 #define _OSM_MAD_POOL_H_
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>
53 # define BEGIN_C_DECLS extern "C" {
54 # define END_C_DECLS }
55 #else /* !__cplusplus */
56 # define BEGIN_C_DECLS
58 #endif /* __cplusplus */
61 /****h* OpenSM/MAD Pool
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.
70 * The MAD Pool is thread safe.
72 * This object should be treated as opaque and should be
73 * manipulated only through the provided functions.
79 /****s* OpenSM: MAD Pool/osm_mad_pool_t
86 * This object should be treated as opaque and should
87 * be manipulated only through the provided functions.
91 typedef struct osm_mad_pool {
97 * Running total of the number of MADs outstanding.
103 /****f* OpenSM: MAD Pool/osm_mad_pool_construct
105 * osm_mad_pool_construct
108 * This function constructs a MAD Pool.
112 void osm_mad_pool_construct(IN osm_mad_pool_t * const p_pool);
116 * [in] Pointer to a MAD Pool to construct.
119 * This function does not return a value.
122 * Allows calling osm_mad_pool_init, osm_mad_pool_destroy
124 * Calling osm_mad_pool_construct is a prerequisite to calling any other
125 * method except osm_mad_pool_init.
128 * MAD Pool, osm_mad_pool_init, osm_mad_pool_destroy
131 /****f* OpenSM: MAD Pool/osm_mad_pool_destroy
133 * osm_mad_pool_destroy
136 * The osm_mad_pool_destroy function destroys a node, releasing
141 void osm_mad_pool_destroy(IN osm_mad_pool_t * const p_pool);
145 * [in] Pointer to a MAD Pool to destroy.
148 * This function does not return a value.
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
157 * MAD Pool, osm_mad_pool_construct, osm_mad_pool_init
160 /****f* OpenSM: MAD Pool/osm_mad_pool_init
165 * The osm_mad_pool_init function initializes a MAD Pool for use.
169 ib_api_status_t osm_mad_pool_init(IN osm_mad_pool_t * const p_pool);
173 * [in] Pointer to an osm_mad_pool_t object to initialize.
176 * CL_SUCCESS if the MAD Pool was initialized successfully.
179 * Allows calling other MAD Pool methods.
182 * MAD Pool, osm_mad_pool_construct, osm_mad_pool_destroy
185 /****f* OpenSM: MAD Pool/osm_mad_pool_get
190 * Gets a MAD wrapper and wire MAD from the pool.
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);
201 * [in] Pointer to an osm_mad_pool_t object.
204 * [in] Handle returned from osm_vendor_bind() call to the
205 * port over which this mad will be sent.
208 * [in] Total size, including MAD header of the requested MAD.
211 * [in] Pointer to the MAD address structure. This parameter
212 * may be NULL for directed route MADs.
215 * Returns a pointer to a MAD wrapper containing the MAD.
216 * A return value of NULL means no MADs are available.
219 * The MAD must eventually be returned to the pool with a call to
222 * The osm_mad_pool_construct or osm_mad_pool_init must be called before
223 * using this function.
226 * MAD Pool, osm_mad_pool_put
229 /****f* OpenSM: MAD Pool/osm_mad_pool_put
234 * Returns a MAD to the pool.
238 void osm_mad_pool_put(IN osm_mad_pool_t * const p_pool,
239 IN osm_madw_t * const p_madw);
243 * [in] Pointer to an osm_mad_pool_t object.
246 * [in] Pointer to a MAD Wrapper for a MAD that was previously
247 * retrieved from the pool.
250 * This function does not return a value.
253 * The osm_mad_pool_construct or osm_mad_pool_init must be called before
254 * using this function.
257 * MAD Pool, osm_mad_pool_get
260 /****f* OpenSM: MAD Pool/osm_mad_pool_get_wrapper
262 * osm_mad_pool_get_wrapper
265 * Gets a only MAD wrapper from the pool (no wire MAD).
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 *
278 * [in] Pointer to an osm_mad_pool_t object.
281 * [in] Handle returned from osm_vendor_bind() call to the
282 * port for which this mad wrapper will be used.
285 * [in] Total size, including MAD header of the MAD that will
286 * be attached to this wrapper.
289 * [in] Pointer to the MAD to attach to this wrapper.
292 * [in] Pointer to the MAD address structure. This parameter
293 * may be NULL for directed route MADs.
296 * Returns a pointer to a MAD wrapper.
297 * A return value of NULL means no MAD wrappers are available.
300 * The MAD must eventually be returned to the pool with a call to
303 * The osm_mad_pool_construct or osm_mad_pool_init must be called before
304 * using this function.
307 * MAD Pool, osm_mad_pool_put
310 /****f* OpenSM: MAD Pool/osm_mad_pool_get_wrapper_raw
312 * osm_mad_pool_get_wrapper_raw
315 * Gets a only an uninitialized MAD wrapper from the pool (no wire MAD).
319 osm_madw_t *osm_mad_pool_get_wrapper_raw(IN osm_mad_pool_t * const p_pool);
323 * [in] Pointer to an osm_mad_pool_t object.
326 * Returns a pointer to a MAD wrapper.
327 * A return value of NULL means no MAD wrappers are available.
330 * The MAD must eventually be returned to the pool with a call to
333 * The osm_mad_pool_construct or osm_mad_pool_init must be called before
334 * using this function.
337 * MAD Pool, osm_mad_pool_put
340 /****f* OpenSM: MAD Pool/osm_mad_pool_get_outstanding
342 * osm_mad_pool_get_count
345 * Returns the running count of MADs currently outstanding from the pool.
349 static inline uint32_t
350 osm_mad_pool_get_outstanding(IN const osm_mad_pool_t * const p_pool)
352 return (p_pool->mads_out);
358 * [in] Pointer to an osm_mad_pool_t object.
361 * Returns the running count of MADs currently outstanding from the pool.
364 * The osm_mad_pool_construct or osm_mad_pool_init must be called before
365 * using this function.
368 * MAD Pool, osm_mad_pool_get
372 #endif /* _OSM_MAD_POOL_H_ */