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_sa_mad_ctrl_t.
39 * This object represents a controller that receives the IBA SA
40 * attributes from a node.
41 * This object is part of the OpenSM family of objects.
42 */
43
44 #ifndef _OSM_SA_MAD_CTRL_H_
45 #define _OSM_SA_MAD_CTRL_H_
46
47 #include <complib/cl_dispatcher.h>
48 #include <opensm/osm_stats.h>
49 #include <opensm/osm_subnet.h>
50 #include <opensm/osm_madw.h>
51 #include <opensm/osm_mad_pool.h>
52 #include <opensm/osm_log.h>
53
54 #ifdef __cplusplus
55 # define BEGIN_C_DECLS extern "C" {
56 # define END_C_DECLS }
57 #else /* !__cplusplus */
58 # define BEGIN_C_DECLS
59 # define END_C_DECLS
60 #endif /* __cplusplus */
61
62 BEGIN_C_DECLS
63 /****h* OpenSM/SA MAD Controller
64 * NAME
65 * SA MAD Controller
66 *
67 * DESCRIPTION
68 * The SA MAD Controller object encapsulates
69 * the information needed to receive MADs from the transport layer.
70 *
71 * The SA MAD Controller object is thread safe.
72 *
73 * This object should be treated as opaque and should be
74 * manipulated only through the provided functions.
75 *
76 * AUTHOR
77 * Ranjit Pandit, Intel
78 *
79 *********/
80
81 struct osm_sa;
82 /****s* OpenSM: SA MAD Controller/osm_sa_mad_ctrl_t
83 * NAME
84 * osm_sa_mad_ctrl_t
85 *
86 * DESCRIPTION
87 * SA MAD Controller structure.
88 *
89 * This object should be treated as opaque and should
90 * be manipulated only through the provided functions.
91 *
92 * SYNOPSIS
93 */
94 typedef struct osm_sa_mad_ctrl {
95 struct osm_sa *sa;
96 osm_log_t *p_log;
97 osm_mad_pool_t *p_mad_pool;
98 osm_vendor_t *p_vendor;
99 osm_bind_handle_t h_bind;
100 cl_dispatcher_t *p_disp;
101 cl_dispatcher_t *p_set_disp;
102 cl_disp_reg_handle_t h_disp;
103 cl_disp_reg_handle_t h_set_disp;
104 osm_stats_t *p_stats;
105 osm_subn_t *p_subn;
106 } osm_sa_mad_ctrl_t;
107 /*
108 * FIELDS
109 * sa
110 * Pointer to the SA object.
111 *
112 * p_log
113 * Pointer to the log object.
114 *
115 * p_mad_pool
116 * Pointer to the MAD pool.
117 *
118 * p_vendor
119 * Pointer to the vendor specific interfaces object.
120 *
121 * h_bind
122 * Bind handle returned by the transport layer.
123 *
124 * p_disp
125 * Pointer to the Dispatcher.
126 *
127 * p_set_disp
128 * Pointer to the Dispatcher for Set requests.
129 *
130 * h_disp
131 * Handle returned from dispatcher registration.
132 *
133 * h_set_disp
134 * Handle returned from Set requests dispatcher registration.
135 *
136 * p_stats
137 * Pointer to the OpenSM statistics block.
138 *
139 * SEE ALSO
140 * SA MAD Controller object
141 * SA MADr object
142 *********/
143
144 /****f* OpenSM: SA MAD Controller/osm_sa_mad_ctrl_construct
145 * NAME
146 * osm_sa_mad_ctrl_construct
147 *
148 * DESCRIPTION
149 * This function constructs a SA MAD Controller object.
150 *
151 * SYNOPSIS
152 */
153 void osm_sa_mad_ctrl_construct(IN osm_sa_mad_ctrl_t * p_ctrl);
154 /*
155 * PARAMETERS
156 * p_ctrl
157 * [in] Pointer to a SA MAD Controller
158 * object to construct.
159 *
160 * RETURN VALUE
161 * This function does not return a value.
162 *
163 * NOTES
164 * Allows calling osm_sa_mad_ctrl_init, and osm_sa_mad_ctrl_destroy.
165 *
166 * Calling osm_sa_mad_ctrl_construct is a prerequisite to calling any other
167 * method except osm_sa_mad_ctrl_init.
168 *
169 * SEE ALSO
170 * SA MAD Controller object, osm_sa_mad_ctrl_init,
171 * osm_sa_mad_ctrl_destroy
172 *********/
173
174 /****f* OpenSM: SA MAD Controller/osm_sa_mad_ctrl_destroy
175 * NAME
176 * osm_sa_mad_ctrl_destroy
177 *
178 * DESCRIPTION
179 * The osm_sa_mad_ctrl_destroy function destroys the object, releasing
180 * all resources.
181 *
182 * SYNOPSIS
183 */
184 void osm_sa_mad_ctrl_destroy(IN osm_sa_mad_ctrl_t * p_ctrl);
185 /*
186 * PARAMETERS
187 * p_ctrl
188 * [in] Pointer to the object to destroy.
189 *
190 * RETURN VALUE
191 * This function does not return a value.
192 *
193 * NOTES
194 * Performs any necessary cleanup of the specified
195 * SA MAD Controller object.
196 * Further operations should not be attempted on the destroyed object.
197 * This function should only be called after a call to
198 * osm_sa_mad_ctrl_construct or osm_sa_mad_ctrl_init.
199 *
200 * SEE ALSO
201 * SA MAD Controller object, osm_sa_mad_ctrl_construct,
202 * osm_sa_mad_ctrl_init
203 *********/
204
205 /****f* OpenSM: SA MAD Controller/osm_sa_mad_ctrl_init
206 * NAME
207 * osm_sa_mad_ctrl_init
208 *
209 * DESCRIPTION
210 * The osm_sa_mad_ctrl_init function initializes a
211 * SA MAD Controller object for use.
212 *
213 * SYNOPSIS
214 */
215 ib_api_status_t osm_sa_mad_ctrl_init(IN osm_sa_mad_ctrl_t * p_ctrl,
216 IN struct osm_sa * sa,
217 IN osm_mad_pool_t * p_mad_pool,
218 IN osm_vendor_t * p_vendor,
219 IN osm_subn_t * p_subn,
220 IN osm_log_t * p_log,
221 IN osm_stats_t * p_stats,
222 IN cl_dispatcher_t * p_disp,
223 IN cl_dispatcher_t * p_set_disp);
224 /*
225 * PARAMETERS
226 * p_ctrl
227 * [in] Pointer to an osm_sa_mad_ctrl_t object to initialize.
228 *
229 * sa
230 * [in] Pointer to the SA object.
231 *
232 * p_mad_pool
233 * [in] Pointer to the MAD pool.
234 *
235 * p_vendor
236 * [in] Pointer to the vendor specific interfaces object.
237 *
238 * p_log
239 * [in] Pointer to the log object.
240 *
241 * p_stats
242 * [in] Pointer to the OpenSM stastics block.
243 *
244 * p_disp
245 * [in] Pointer to the OpenSM central Dispatcher.
246 *
247 * p_set_disp
248 * [in] Pointer to the OpenSM Dispatcher for Set requests.
249 *
250 * RETURN VALUES
251 * IB_SUCCESS if the SA MAD Controller object was initialized
252 * successfully.
253 *
254 * NOTES
255 * Allows calling other SA MAD Controller methods.
256 *
257 * SEE ALSO
258 * SA MAD Controller object, osm_sa_mad_ctrl_construct,
259 * osm_sa_mad_ctrl_destroy
260 *********/
261
262 /****f* OpenSM: SA/osm_sa_mad_ctrl_bind
263 * NAME
264 * osm_sa_mad_ctrl_bind
265 *
266 * DESCRIPTION
267 * Binds the SA MAD Controller object to a port guid.
268 *
269 * SYNOPSIS
270 */
271 ib_api_status_t osm_sa_mad_ctrl_bind(IN osm_sa_mad_ctrl_t * p_ctrl,
272 IN ib_net64_t port_guid);
273 /*
274 * PARAMETERS
275 * p_ctrl
276 * [in] Pointer to an osm_sa_mad_ctrl_t object to initialize.
277 *
278 * port_guid
279 * [in] Local port GUID with which to bind.
280 *
281 *
282 * RETURN VALUES
283 * None
284 *
285 * NOTES
286 * A given SA MAD Controller object can only be bound to one
287 * port at a time.
288 *
289 * SEE ALSO
290 *********/
291
292 /****f* OpenSM: SA/osm_sa_mad_ctrl_unbind
293 * NAME
294 * osm_sa_mad_ctrl_unbind
295 *
296 * DESCRIPTION
297 * Un-Binds the SA MAD Controller object from the IB port
298 *
299 * SYNOPSIS
300 */
301 ib_api_status_t osm_sa_mad_ctrl_unbind(IN osm_sa_mad_ctrl_t * p_ctrl);
302 /*
303 * PARAMETERS
304 * p_ctrl
305 * [in] Pointer to an osm_sa_mad_ctrl_t object to initialize.
306 *
307 * RETURN VALUES
308 * None
309 *
310 * NOTES
311 * A given SA MAD Controller should be previously bound to IB
312 * port.
313 *
314 * SEE ALSO
315 *********/
316
317 /****f* OpenSM: SA/osm_sa_mad_ctrl_get_bind_handle
318 * NAME
319 * osm_sa_mad_ctrl_get_bind_handle
320 *
321 * DESCRIPTION
322 * Returns the bind handle.
323 *
324 * SYNOPSIS
325 */
326 static inline osm_bind_handle_t
osm_sa_mad_ctrl_get_bind_handle(IN const osm_sa_mad_ctrl_t * p_ctrl)327 osm_sa_mad_ctrl_get_bind_handle(IN const osm_sa_mad_ctrl_t * p_ctrl)
328 {
329 return p_ctrl->h_bind;
330 }
331
332 /*
333 * PARAMETERS
334 * p_ctrl
335 * [in] Pointer to an osm_sa_mad_ctrl_t object.
336 *
337 * RETURN VALUES
338 * Returns the bind handle, which may be OSM_BIND_INVALID_HANDLE
339 * if no port has been bound.
340 *
341 * NOTES
342 * A given SA MAD Controller object can only be bound to one
343 * port at a time.
344 *
345 * SEE ALSO
346 *********/
347
348 END_C_DECLS
349 #endif /* _OSM_SA_MAD_CTRL_H_ */
350