1 /*
2 * Copyright (c) 2004, 2005 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 * const 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 * const 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
213 osm_sm_mad_ctrl_init(IN osm_sm_mad_ctrl_t * const p_ctrl,
214 IN osm_subn_t * const p_subn,
215 IN osm_mad_pool_t * const p_mad_pool,
216 IN osm_vl15_t * const p_vl15,
217 IN osm_vendor_t * const p_vendor,
218 IN osm_log_t * const p_log,
219 IN osm_stats_t * const p_stats,
220 IN cl_plock_t * const p_lock,
221 IN cl_dispatcher_t * const p_disp);
222 /*
223 * PARAMETERS
224 * p_ctrl
225 * [in] Pointer to an osm_sm_mad_ctrl_t object to initialize.
226 *
227 * p_mad_pool
228 * [in] Pointer to the MAD pool.
229 *
230 * p_vl15
231 * [in] Pointer to the VL15 interface object.
232 *
233 * p_vendor
234 * [in] Pointer to the vendor specific interfaces object.
235 *
236 * p_log
237 * [in] Pointer to the log object.
238 *
239 * p_stats
240 * [in] Pointer to the OpenSM stastics block.
241 *
242 * p_lock
243 * [in] Pointer to the OpenSM serializing lock.
244 *
245 * p_disp
246 * [in] Pointer to the OpenSM central Dispatcher.
247 *
248 * RETURN VALUES
249 * IB_SUCCESS if the SM MAD Controller object was initialized
250 * successfully.
251 *
252 * NOTES
253 * Allows calling other SM MAD Controller methods.
254 *
255 * SEE ALSO
256 * SM MAD Controller object, osm_sm_mad_ctrl_construct,
257 * osm_sm_mad_ctrl_destroy
258 *********/
259
260 /****f* OpenSM: SM/osm_sm_mad_ctrl_bind
261 * NAME
262 * osm_sm_mad_ctrl_bind
263 *
264 * DESCRIPTION
265 * Binds the SM MAD Controller object to a port guid.
266 *
267 * SYNOPSIS
268 */
269 ib_api_status_t
270 osm_sm_mad_ctrl_bind(IN osm_sm_mad_ctrl_t * const p_ctrl,
271 IN const ib_net64_t port_guid);
272 /*
273 * PARAMETERS
274 * p_ctrl
275 * [in] Pointer to an osm_sm_mad_ctrl_t object to initialize.
276 *
277 * port_guid
278 * [in] Local port GUID with which to bind.
279 *
280 *
281 * RETURN VALUES
282 * None
283 *
284 * NOTES
285 * A given SM MAD Controller object can only be bound to one
286 * port at a time.
287 *
288 * SEE ALSO
289 *********/
290
291 /****f* OpenSM: SM/osm_sm_mad_ctrl_get_bind_handle
292 * NAME
293 * osm_sm_mad_ctrl_get_bind_handle
294 *
295 * DESCRIPTION
296 * Returns the bind handle.
297 *
298 * SYNOPSIS
299 */
300 static inline osm_bind_handle_t
osm_sm_mad_ctrl_get_bind_handle(IN const osm_sm_mad_ctrl_t * const p_ctrl)301 osm_sm_mad_ctrl_get_bind_handle(IN const osm_sm_mad_ctrl_t * const p_ctrl)
302 {
303 return (p_ctrl->h_bind);
304 }
305
306 /*
307 * PARAMETERS
308 * p_ctrl
309 * [in] Pointer to an osm_sm_mad_ctrl_t object.
310 *
311 * RETURN VALUES
312 * Returns the bind handle, which may be OSM_BIND_INVALID_HANDLE
313 * if no port has been bound.
314 *
315 * NOTES
316 * A given SM MAD Controller object can only be bound to one
317 * port at a time.
318 *
319 * SEE ALSO
320 *********/
321
322 END_C_DECLS
323 #endif /* _OSM_SM_MAD_CTRL_H_ */
324