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
osm_mad_pool_get_outstanding(IN const osm_mad_pool_t * p_pool)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