In osm_ucast_mgr, where osm_req_set is called for SwitchInfo,
[mirror/winof/.git] / ulp / opensm / user / include / opensm / osm_req.h
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 the OpenIB.org BSD license
7  * below:
8  *
9  *     Redistribution and use in source and binary forms, with or
10  *     without modification, are permitted provided that the following
11  *     conditions are met:
12  *
13  *      - Redistributions of source code must retain the above
14  *        copyright notice, this list of conditions and the following
15  *        disclaimer.
16  *
17  *      - Redistributions in binary form must reproduce the above
18  *        copyright notice, this list of conditions and the following
19  *        disclaimer in the documentation and/or other materials
20  *        provided with the distribution.
21  *
22  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
23  * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
24  * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
25  * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
26  * BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
27  * ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
28  * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
29  * SOFTWARE.
30  *
31  * $Id$
32  */
33
34
35 /*
36  * Abstract:
37  *      Declaration of osm_req_t.
38  *      This object represents an object that genericly requests
39  *      attributes from a node.
40  *      This object is part of the OpenSM family of objects.
41  *
42  * Environment:
43  *      Linux User Mode
44  *
45  * $Revision: 1.4 $
46  */
47
48
49 #ifndef _OSM_REQ_H_
50 #define _OSM_REQ_H_
51
52 #include <complib/cl_atomic.h>
53 #include <opensm/cl_dispatcher.h>
54 #include <opensm/osm_base.h>
55 #include <opensm/osm_log.h>
56 #include <opensm/osm_path.h>
57 #include <opensm/osm_subnet.h>
58 #include <opensm/osm_vl15intf.h>
59 #include <opensm/osm_madw.h>
60 #include <opensm/osm_mad_pool.h>
61
62 #ifdef __cplusplus
63 #  define BEGIN_C_DECLS extern "C" {
64 #  define END_C_DECLS   }
65 #else /* !__cplusplus */
66 #  define BEGIN_C_DECLS
67 #  define END_C_DECLS
68 #endif /* __cplusplus */
69
70 BEGIN_C_DECLS
71
72 /****h* OpenSM/Generic Requester
73 * NAME
74 *       Generic Requester
75 *
76 * DESCRIPTION
77 *       The Generic Requester object encapsulates the information
78 *       needed to request an attribute from a node.
79 *
80 *       The Generic Requester object is thread safe.
81 *
82 *       This object should be treated as opaque and should be
83 *       manipulated only through the provided functions.
84 *
85 * AUTHOR
86 *       Steve King, Intel
87 *
88 *********/
89 /****s* OpenSM: Generic Requester/osm_req_t
90 * NAME
91 *       osm_req_t
92 *
93 * DESCRIPTION
94 *       Generic Requester structure.
95 *
96 *       This object should be treated as opaque and should
97 *       be manipulated only through the provided functions.
98 *
99 * SYNOPSIS
100 */
101 typedef struct _osm_req
102 {
103         osm_mad_pool_t                          *p_pool;
104         osm_vl15_t                                      *p_vl15;
105         osm_log_t                                       *p_log;
106         osm_subn_t                                      *p_subn;
107         atomic32_t                                      *p_sm_trans_id;
108
109 } osm_req_t;
110 /*
111 * FIELDS
112 *       p_pool
113 *               Pointer to the MAD pool.
114 *
115 *       p_vl15
116 *               Pointer to the VL15 interface.
117 *
118 *       p_log
119 *               Pointer to the log object.
120 *
121 *       p_subn
122 *               Pointer to the subnet object.
123 *
124 * SEE ALSO
125 *       Generic Requester object
126 *********/
127
128 /****f* OpenSM: Generic Requester/osm_req_construct
129 * NAME
130 *       osm_req_construct
131 *
132 * DESCRIPTION
133 *       This function constructs a Generic Requester object.
134 *
135 * SYNOPSIS
136 */
137 void
138 osm_req_construct(
139         IN osm_req_t* const p_req );
140 /*
141 * PARAMETERS
142 *       p_req
143 *               [in] Pointer to a Generic Requester object to construct.
144 *
145 * RETURN VALUE
146 *       This function does not return a value.
147 *
148 * NOTES
149 *       Allows calling osm_req_init, osm_req_destroy,
150 *       and osm_req_is_inited.
151 *
152 *       Calling osm_req_construct is a prerequisite to calling any other
153 *       method except osm_req_init.
154 *
155 * SEE ALSO
156 *       Generic Requester object, osm_req_init,
157 *       osm_req_destroy, osm_req_is_inited
158 *********/
159
160 /****f* OpenSM: Generic Requester/osm_req_destroy
161 * NAME
162 *       osm_req_destroy
163 *
164 * DESCRIPTION
165 *       The osm_req_destroy function destroys the object, releasing
166 *       all resources.
167 *
168 * SYNOPSIS
169 */
170 void
171 osm_req_destroy(
172         IN osm_req_t* const p_req );
173 /*
174 * PARAMETERS
175 *       p_req
176 *               [in] Pointer to the object to destroy.
177 *
178 * RETURN VALUE
179 *       This function does not return a value.
180 *
181 * NOTES
182 *       Performs any necessary cleanup of the specified
183 *       Generic Requester object.
184 *       Further operations should not be attempted on the destroyed object.
185 *       This function should only be called after a call to
186 *       osm_req_construct or osm_req_init.
187 *
188 * SEE ALSO
189 *       Generic Requester object, osm_req_construct,
190 *       osm_req_init
191 *********/
192
193 /****f* OpenSM: Generic Requester/osm_req_init
194 * NAME
195 *       osm_req_init
196 *
197 * DESCRIPTION
198 *       The osm_req_init function initializes a
199 *       Generic Requester object for use.
200 *
201 * SYNOPSIS
202 */
203 ib_api_status_t
204 osm_req_init(
205         IN osm_req_t*                           const p_req,
206         IN osm_mad_pool_t*                      const p_pool,
207         IN osm_vl15_t*                          const p_vl15,
208         IN osm_subn_t*                          const p_subn,
209         IN osm_log_t*                           const p_log,
210         IN atomic32_t*                          const p_sm_trans_id );
211 /*
212 * PARAMETERS
213 *       p_req
214 *               [in] Pointer to an osm_req_t object to initialize.
215 *
216 *       p_mad_pool
217 *               [in] Pointer to the MAD pool.
218 *
219 *       p_vl15
220 *               [in] Pointer to the VL15 interface.
221 *
222 *       p_subn
223 *               [in] Pointer to the subnet object.
224 *
225 *       p_log
226 *               [in] Pointer to the log object.
227 *
228 *       p_sm_trans_id
229 *               [in] Pointer to the atomic SM transaction ID.
230 *
231 * RETURN VALUES
232 *       IB_SUCCESS if the Generic Requester object was initialized
233 *       successfully.
234 *
235 * NOTES
236 *       Allows calling other Generic Requester methods.
237 *
238 * SEE ALSO
239 *       Generic Requester object, osm_req_construct,
240 *       osm_req_destroy, osm_req_is_inited
241 *********/
242
243 /****f* OpenSM: Generic Requester/osm_req_get
244 * NAME
245 *       osm_req_get
246 *
247 * DESCRIPTION
248 *       Starts the process to transmit a directed route request for
249 *       the attribute.
250 *
251 * SYNOPSIS
252 */
253 ib_api_status_t
254 osm_req_get(
255         IN const osm_req_t* const p_req,
256         IN const osm_dr_path_t* const p_path,
257         IN const uint16_t attr_id,
258         IN const uint32_t attr_mod,
259         IN const cl_disp_msgid_t err_msg,
260         IN const osm_madw_context_t* const p_context );
261 /*
262 * PARAMETERS
263 *       p_req
264 *               [in] Pointer to an osm_req_t object.
265 *
266 *       p_path
267 *               [in] Pointer to the directed route path to the node
268 *               from which to retrieve the attribute.
269 *
270 *       attr_id
271 *               [in] Attribute ID to request.
272 *
273 *       attr_mod
274 *               [in] Attribute modifier for this request.
275 *
276 *       err_msg
277 *               [in] Message id with which to post this MAD if an error occurs.
278 *
279 *       p_context
280 *               [in] Mad wrapper context structure to be copied into the wrapper
281 *               context, and thus visible to the recipient of the response.
282 *
283 * RETURN VALUES
284 *       IB_SUCCESS if the request was successful.
285 *
286 * NOTES
287 *       This function asynchronously requests the specified attribute.
288 *       The response from the node will be routed through the Dispatcher
289 *       to the appropriate receive controller object.
290 *
291 * SEE ALSO
292 *       Generic Requester
293 *********/
294 /****f* OpenSM: Generic Requester/osm_req_set
295 * NAME
296 *       osm_req_set
297 *
298 * DESCRIPTION
299 *       Starts the process to transmit a directed route Set() request.
300 *
301 * SYNOPSIS
302 */
303 ib_api_status_t
304 osm_req_set(
305         IN const osm_req_t* const p_req,
306         IN const osm_dr_path_t* const p_path,
307         IN const uint8_t* const p_payload,
308    IN const size_t payload_size,
309         IN const uint16_t attr_id,
310         IN const uint32_t attr_mod,
311         IN const cl_disp_msgid_t err_msg,
312         IN const osm_madw_context_t* const p_context );
313 /*
314 * PARAMETERS
315 *       p_req
316 *               [in] Pointer to an osm_req_t object.
317 *
318 *       p_path
319 *               [in] Pointer to the directed route path of the recipient.
320 *
321 *       p_payload
322 *               [in] Pointer to the SMP payload to send.
323 *
324 *  payload_size
325 *               [in] The size of the payload to be copied to the SMP data field.
326 *
327 *       attr_id
328 *               [in] Attribute ID to request.
329 *
330 *       attr_mod
331 *               [in] Attribute modifier for this request.
332 *
333 *       err_msg
334 *               [in] Message id with which to post this MAD if an error occurs.
335 *
336 *       p_context
337 *               [in] Mad wrapper context structure to be copied into the wrapper
338 *               context, and thus visible to the recipient of the response.
339 *
340 * RETURN VALUES
341 *       IB_SUCCESS if the request was successful.
342 *
343 * NOTES
344 *       This function asynchronously requests the specified attribute.
345 *       The response from the node will be routed through the Dispatcher
346 *       to the appropriate receive controller object.
347 *
348 * SEE ALSO
349 *       Generic Requester
350 *********/
351
352 END_C_DECLS
353
354 #endif  /* _OSM_REQ_H_ */