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