1 /*
2 * Copyright (c) 2004-2006 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 * Specification of the OpenSM SA Client API. This API uses the basic osm
39 * vendor API to provide SA Client interface.
40 */
41
42 #ifndef _OSM_VENDOR_SA_API_H_
43 #define _OSM_VENDOR_SA_API_H_
44
45 #include <iba/ib_types.h>
46
47 #ifdef __cplusplus
48 # define BEGIN_C_DECLS extern "C" {
49 # define END_C_DECLS }
50 #else /* !__cplusplus */
51 # define BEGIN_C_DECLS
52 # define END_C_DECLS
53 #endif /* __cplusplus */
54
55 BEGIN_C_DECLS
56 /****d* OpenSM Vendor SA Client/osmv_flags_t
57 * NAME
58 * osmv_flags_t
59 *
60 * DESCRIPTION
61 * Access layer flags used to direct the operation of various calls.
62 *
63 * SYNOPSIS
64 */
65 typedef uint32_t osmv_flags_t;
66 #define OSM_SA_FLAGS_SYNC 0x00000001
67 /*
68 * VALUES
69 * OSM_SA_FLAGS_SYNC
70 * Indicates that the given operation should be performed synchronously.
71 * The call will block until it completes. Callbacks will still be
72 * invoked.
73 *
74 * SEE ALSO
75 * osmv_query_sa
76 *****/
77
78 /****d* OpenSM Vendor SA Client/osmv_query_type_t
79 * NAME
80 * osmv_query_type_t
81 *
82 * DESCRIPTION
83 * Abstracted queries supported by the access layer.
84 *
85 * SYNOPSIS
86 */
87 typedef enum _osmv_query_type {
88 OSMV_QUERY_USER_DEFINED,
89
90 OSMV_QUERY_ALL_SVC_RECS,
91 OSMV_QUERY_SVC_REC_BY_NAME,
92 OSMV_QUERY_SVC_REC_BY_ID,
93
94 OSMV_QUERY_CLASS_PORT_INFO,
95
96 OSMV_QUERY_NODE_REC_BY_NODE_GUID,
97 OSMV_QUERY_PORT_REC_BY_LID,
98 OSMV_QUERY_PORT_REC_BY_LID_AND_NUM,
99
100 OSMV_QUERY_VLARB_BY_LID_PORT_BLOCK,
101 OSMV_QUERY_SLVL_BY_LID_AND_PORTS,
102
103 OSMV_QUERY_PATH_REC_BY_PORT_GUIDS,
104 OSMV_QUERY_PATH_REC_BY_GIDS,
105 OSMV_QUERY_PATH_REC_BY_LIDS,
106
107 OSMV_QUERY_UD_MULTICAST_SET,
108 OSMV_QUERY_UD_MULTICAST_DELETE,
109
110 OSMV_QUERY_MULTIPATH_REC,
111
112 } osmv_query_type_t;
113 /*
114 * VALUES
115 * OSMV_QUERY_USER_DEFINED
116 * Query the SA based on user-defined input. Queries of this type
117 * should reference an osmv_user_query_t structure as input to the
118 * query.
119 *
120 * OSMV_QUERY_SVC_REC_BY_NAME
121 * Query for service records based on the service name. Queries of
122 * this type should reference an ib_svc_name_t structure as input
123 * to the query.
124 *
125 * OSMV_QUERY_SVC_REC_BY_ID
126 * Query for service records based on the service ID. Queries of
127 * this type should reference an ib_net64_t value that indicates
128 * the ID of the service being requested.
129 *
130 * OSMV_QUERY_NODE_REC_BY_NODE_GUID
131 * Query for node information based on the node's GUID. Queries of
132 * this type should reference an ib_net64_t value that indicates
133 * the GUID of the node being requested.
134 *
135 * OSMV_QUERY_PORT_REC_BY_LID
136 * Query for port information based on the port's base LID. Queries
137 * of this type should reference an ib_net16_t value that indicates
138 * the base LID of the port being requested.
139 *
140 * OSMV_QUERY_PORT_REC_BY_LID_AND_NUM
141 * Query for port information based on the port's LID and port num.
142 * Queries of this type should reference an osmv_user_query_t
143 * structure as input to the query. The port num and lid should
144 * be provided by it.
145 *
146 * OSMV_QUERY_PATH_REC_BY_PORT_GUIDS
147 * Query for path records between the specified pair of port GUIDs.
148 * Queries of this type should reference an osmv_guid_pair_t
149 * structure that indicates the GUIDs of the path being requested.
150 *
151 * OSMV_QUERY_PATH_REC_BY_GIDS
152 * Query for path records between the specified pair of port GIDs.
153 * Queries of this type should reference an osmv_gid_pair_t
154 * structure that indicates the GIDs of the path being requested.
155 *
156 * OSMV_QUERY_PATH_REC_BY_LIDS
157 * Query for path records between the specified pair of port LIDs.
158 * Queries of this type should reference an osmv_lid_pair_t
159 * structure that indicates the LIDs of the path being requested.
160 *
161 * NOTES
162 * This enum is used to define abstracted queries provided by the access
163 * layer. Users may issue queries not listed here by sending MADs directly
164 * to subnet administration or a class manager. These queries are
165 * intended to represent those most often used by clients.
166 *
167 * SEE ALSO
168 * osmv_query, osmv_query_req_t, osmv_user_query_t, osmv_gid_pair_t,
169 * osmv_lid_pair_t osmv_guid_pair_t
170 *****/
171
172 /****s* OpenSM Vendor SA Client/osmv_user_query_t
173 * NAME
174 * osmv_user_query_t
175 *
176 * DESCRIPTION
177 * User-defined query information.
178 *
179 * SYNOPSIS
180 */
181 typedef struct _osmv_user_query {
182 uint8_t method;
183 ib_net16_t attr_id;
184 ib_net16_t attr_offset;
185 ib_net32_t attr_mod;
186 ib_net64_t comp_mask;
187 void *p_attr;
188 } osmv_user_query_t;
189 /*
190 * FIELDS
191 *
192 * method
193 * Method to be used
194 *
195 * attr_id
196 * Attribute identifier of query data.
197 *
198 * attr_offset
199 * Size of the query attribute, in 8-byte words. Users can set
200 * this value by passing in the sizeof( attribute ) into the
201 * ib_get_attr_offset() routine.
202 *
203 * attr_mod
204 * Attribute modifier for query request.
205 *
206 * comp_mask
207 * Indicates the attribute components that are specified for the
208 * query.
209 *
210 * p_attr
211 * References the attribute structure used as input into the query.
212 * This field is ignored if comp_mask is set to 0.
213 *
214 * NOTES
215 * This structure is used to describe a user-defined query. The attribute
216 * ID, attribute offset, component mask, and attribute structure must match
217 * those defined by the IBA specification. Users should refer to chapter
218 * 15 of the IBA specification for additional details.
219 *
220 * SEE ALSO
221 * osmv_query_type_t, ib_get_attr_offset, ib_get_attr_size, osmv_query_sa
222 *****/
223
224 /****s* OpenSM Vendor SA Client/osmv_gid_pair_t
225 * NAME
226 * osmv_gid_pair_t
227 *
228 * DESCRIPTION
229 * Source and destination GIDs.
230 *
231 * SYNOPSIS
232 */
233 typedef struct _osmv_gid_pair {
234 ib_gid_t src_gid;
235 ib_gid_t dest_gid;
236 } osmv_gid_pair_t;
237 /*
238 * FIELDS
239 * src_gid
240 * Source GID of a path.
241 *
242 * dest_gid
243 * Destination GID of a path.
244 *
245 * NOTES
246 * This structure is used to describe the endpoints of a path.
247 *
248 * SEE ALSO
249 * ib_gid_t
250 *****/
251
252 /****s* OpenSM Vendor SA Client/osmv_lid_pair_t
253 * NAME
254 * osmv_lid_pair_t
255 *
256 * DESCRIPTION
257 * Source and destination LIDs.
258 *
259 * SYNOPSIS
260 */
261 typedef struct _osmv_lid_pair {
262 ib_net16_t src_lid;
263 ib_net16_t dest_lid;
264 } osmv_lid_pair_t;
265 /*
266 * FIELDS
267 * src_lid
268 * Source LID of a path.
269 *
270 * dest_lid
271 * Destination LID of a path.
272 *
273 * NOTES
274 * This structure is used to describe the endpoints of a path.
275 *****/
276
277 /****s* OpenSM Vendor SA Client/osmv_guid_pair_t
278 * NAME
279 * osmv_guid_pair_t
280 *
281 * DESCRIPTION
282 * Source and destination GUIDs. These may be port or channel adapter
283 * GUIDs, depending on the context in which this structure is used.
284 *
285 * SYNOPSIS
286 */
287 typedef struct _osmv_guid_pair {
288 ib_net64_t src_guid;
289 ib_net64_t dest_guid;
290 } osmv_guid_pair_t;
291 /*
292 * FIELDS
293 * src_guid
294 * Source GUID of a path.
295 *
296 * dest_guid
297 * Destination GUID of a path.
298 *
299 * NOTES
300 * This structure is used to describe the endpoints of a path. The given
301 * GUID pair may belong to either ports or channel adapters.
302 *
303 * SEE ALSO
304 * ib_guid_t
305 *****/
306
307 /****s* OpenSM Vendor SA Client/osmv_multipath_req_t
308 * NAME
309 * osmv_multipath_req_t
310 *
311 * DESCRIPTION
312 * Fields from which to generate a MultiPathRecord request.
313 *
314 * SYNOPSIS
315 */
316 typedef struct _osmv_multipath_req_t {
317 ib_net64_t comp_mask;
318 uint16_t pkey;
319 boolean_t reversible;
320 uint8_t num_path;
321 uint8_t sl;
322 uint8_t independence;
323 uint8_t sgid_count;
324 uint8_t dgid_count;
325 ib_gid_t gids[IB_MULTIPATH_MAX_GIDS];
326 } osmv_multipath_req_t;
327 /*
328 * FIELDS
329 *
330 * NOTES
331 * This structure is used to describe a multipath request.
332 *
333 * SEE ALSO
334 *****/
335
336 /****s* OpenSM Vendor SA Client/osmv_query_res_t
337 * NAME
338 * osmv_query_res_t
339 *
340 * DESCRIPTION
341 * Contains the results of a subnet administration query.
342 *
343 * SYNOPSIS
344 */
345 typedef struct _osmv_query_res {
346 const void *query_context;
347 ib_api_status_t status;
348 osmv_query_type_t query_type;
349 uint32_t result_cnt;
350 osm_madw_t *p_result_madw;
351 } osmv_query_res_t;
352 /*
353 * FIELDS
354 * query_context
355 * User-defined context information associated with the query
356 * through the osm_vendor_query_sa call.
357 *
358 * status
359 * Indicates the success of the query operation.
360 *
361 * query_type
362 * Indicates the type of query for which the results are being
363 * returned. This matches the query_type specified through the
364 * osm_vendor_query_sa call.
365 *
366 * result_cnt
367 * The number of result structures that were returned by the query.
368 *
369 * p_result_madw
370 * For queries returning IB_SUCCESS or IB_REMOTE_ERROR, this
371 * references the MAD wrapper returned by subnet administration
372 * containing the list of results or the returned error code.
373 *
374 * NOTES
375 * A query result structure is returned to a client through their
376 * osmv_pfn_query_cb_t routine to notify them of the results of a subnet
377 * administration query. If the query was successful or received an error
378 * from subnet administration, p_result_madw will reference a MAD wrapper
379 * containing the results. The MAD referenced by p_result_madw is owned by
380 * the user and remains available even after their callback returns. Users
381 * must call osm_mad_pool_put() to return the MAD wrapper back to the
382 * mad pool when they are done accessing the results.
383 *
384 * To retrieve individual result structures from the p_result_madw, users
385 * may call osmv_get_query_result().
386 *
387 * SEE ALSO
388 * osmv_query_sa, osmv_pfn_query_cb_t, ib_api_status_t,
389 * osmv_query_status_t, osmv_query_type_t,
390 * osmv_get_query_result
391 *****/
392
393 /****f* OpenSM Vendor SA Client/osmv_get_query_result
394 * NAME
395 * osmv_get_query_result
396 *
397 * DESCRIPTION
398 * Retrieves a result structure from a MADW returned by a call to
399 * osmv_query_sa().
400 *
401 * SYNOPSIS
402 */
osmv_get_query_result(IN osm_madw_t * p_result_madw,IN uint32_t result_index)403 static inline void *osmv_get_query_result(IN osm_madw_t * p_result_madw,
404 IN uint32_t result_index)
405 {
406 ib_sa_mad_t *p_sa_mad;
407
408 CL_ASSERT(p_result_madw);
409 p_sa_mad = (ib_sa_mad_t *) osm_madw_get_mad_ptr(p_result_madw);
410 CL_ASSERT(p_sa_mad);
411 CL_ASSERT(ib_get_attr_size(p_sa_mad->attr_offset) * (result_index + 1) +
412 IB_SA_MAD_HDR_SIZE <= p_result_madw->mad_size);
413
414 return (p_sa_mad->data +
415 (ib_get_attr_size(p_sa_mad->attr_offset) * result_index));
416 }
417
418 /*
419 * PARAMETERS
420 * p_result_madw
421 * [in] This is a reference to the MAD returned as a result of the
422 * query.
423 *
424 * result_index
425 * [in] A zero-based index indicating which result to return.
426 *
427 * NOTES
428 * This call returns a pointer to the start of a result structure from a
429 * call to osmv_query_sa(). The type of result structure must be known to
430 * the user either through the user's context or the query_type returned as
431 * part of the osmv_query_res_t structure.
432 *
433 * SEE ALSO
434 * osmv_query_res_t, osm_madw_t
435 *****/
436
437 /****f* OpenSM Vendor SA Client/osmv_get_query_path_rec
438 * NAME
439 * osmv_get_query_path_rec
440 *
441 * DESCRIPTION
442 * Retrieves a path record result from a MAD returned by a call to
443 * osmv_query_sa().
444 *
445 * SYNOPSIS
446 */
osmv_get_query_path_rec(IN osm_madw_t * p_result_madw,IN uint32_t result_index)447 static inline ib_path_rec_t *osmv_get_query_path_rec(IN osm_madw_t *
448 p_result_madw,
449 IN uint32_t result_index)
450 {
451 ib_sa_mad_t __attribute__((__unused__)) *p_sa_mad;
452
453 CL_ASSERT(p_result_madw);
454 p_sa_mad = (ib_sa_mad_t *) osm_madw_get_mad_ptr(p_result_madw);
455 CL_ASSERT(p_sa_mad && p_sa_mad->attr_id == IB_MAD_ATTR_PATH_RECORD);
456
457 return ((ib_path_rec_t *)
458 osmv_get_query_result(p_result_madw, result_index));
459 }
460
461 /*
462 * PARAMETERS
463 * p_result_madw
464 * [in] This is a reference to the MAD returned as a result of the
465 * query.
466 *
467 * result_index
468 * [in] A zero-based index indicating which result to return.
469 *
470 * NOTES
471 * This call returns a pointer to the start of a path record result from
472 * a call to osmv_query_sa().
473 *
474 * SEE ALSO
475 * osmv_query_res_t, osm_madw_t, osmv_get_query_result, ib_path_rec_t
476 *****/
477
478 /****f* OpenSM Vendor SA Client/osmv_get_query_portinfo_rec
479 * NAME
480 * osmv_get_query_portinfo_rec
481 *
482 * DESCRIPTION
483 * Retrieves a port info record result from a MAD returned by a call to
484 * osmv_query_sa().
485 *
486 * SYNOPSIS
487 */
osmv_get_query_portinfo_rec(IN osm_madw_t * p_result_madw,IN uint32_t result_index)488 static inline ib_portinfo_record_t *osmv_get_query_portinfo_rec(IN osm_madw_t *
489 p_result_madw,
490 IN uint32_t
491 result_index)
492 {
493 ib_sa_mad_t __attribute__((__unused__)) *p_sa_mad;
494
495 CL_ASSERT(p_result_madw);
496 p_sa_mad = (ib_sa_mad_t *) osm_madw_get_mad_ptr(p_result_madw);
497 CL_ASSERT(p_sa_mad && p_sa_mad->attr_id == IB_MAD_ATTR_PORTINFO_RECORD);
498
499 return ((ib_portinfo_record_t *) osmv_get_query_result(p_result_madw,
500 result_index));
501 }
502
503 /*
504 * PARAMETERS
505 * p_result_madw
506 * [in] This is a reference to the MAD returned as a result of the
507 * query.
508 *
509 * result_index
510 * [in] A zero-based index indicating which result to return.
511 *
512 * NOTES
513 * This call returns a pointer to the start of a port info record result
514 * from a call to osmv_query_sa().
515 *
516 * SEE ALSO
517 * osmv_query_res_t, osm_madw_t, osmv_get_query_result, ib_portinfo_record_t
518 *****/
519
520 /****f* OpenSM Vendor SA Client/osmv_get_query_node_rec
521 * NAME
522 * osmv_get_query_node_rec
523 *
524 * DESCRIPTION
525 * Retrieves a node record result from a MAD returned by a call to
526 * osmv_query_sa().
527 *
528 * SYNOPSIS
529 */
osmv_get_query_node_rec(IN osm_madw_t * p_result_madw,IN uint32_t result_index)530 static inline ib_node_record_t *osmv_get_query_node_rec(IN osm_madw_t *
531 p_result_madw,
532 IN uint32_t
533 result_index)
534 {
535 ib_sa_mad_t __attribute__((__unused__)) *p_sa_mad;
536
537 CL_ASSERT(p_result_madw);
538 p_sa_mad = (ib_sa_mad_t *) osm_madw_get_mad_ptr(p_result_madw);
539 CL_ASSERT(p_sa_mad && p_sa_mad->attr_id == IB_MAD_ATTR_NODE_RECORD);
540
541 return ((ib_node_record_t *) osmv_get_query_result(p_result_madw,
542 result_index));
543 }
544
545 /*
546 * PARAMETERS
547 * p_result_madw
548 * [in] This is a reference to the MAD returned as a result of the
549 * query.
550 *
551 * result_index
552 * [in] A zero-based index indicating which result to return.
553 *
554 * NOTES
555 * This call returns a pointer to the start of a node record result from
556 * a call to osmv_query_sa().
557 *
558 * SEE ALSO
559 * osmv_query_res_t, osm_madw_t, osmv_get_query_result, ib_node_record_t
560 *****/
561
562 /****f* OpenSM Vendor SA Client/osmv_get_query_svc_rec
563 * NAME
564 * osmv_get_query_svc_rec
565 *
566 * DESCRIPTION
567 * Retrieves a service record result from a MAD returned by a call to
568 * osmv_query_sa().
569 *
570 * SYNOPSIS
571 */
osmv_get_query_svc_rec(IN osm_madw_t * p_result_madw,IN uint32_t result_index)572 static inline ib_service_record_t *osmv_get_query_svc_rec(IN osm_madw_t *
573 p_result_madw,
574 IN uint32_t
575 result_index)
576 {
577 ib_sa_mad_t __attribute__((__unused__)) *p_sa_mad;
578
579 CL_ASSERT(p_result_madw);
580 p_sa_mad = (ib_sa_mad_t *) osm_madw_get_mad_ptr(p_result_madw);
581 CL_ASSERT(p_sa_mad && p_sa_mad->attr_id == IB_MAD_ATTR_SERVICE_RECORD);
582
583 return ((ib_service_record_t *) osmv_get_query_result(p_result_madw,
584 result_index));
585 }
586
587 /*
588 * PARAMETERS
589 * p_result_madw
590 * [in] This is a reference to the MAD returned as a result of the
591 * query.
592 *
593 * result_index
594 * [in] A zero-based index indicating which result to return.
595 *
596 * NOTES
597 * This call returns a pointer to the start of a service record result from
598 * a call to osmv_query_sa().
599 *
600 * SEE ALSO
601 * osmv_query_res_t, osm_madw_t, osmv_get_query_result, ib_service_record_t
602 *****/
603
604 /****f* OpenSM Vendor SA Client/osmv_get_query_mc_rec
605 * NAME
606 * osmv_get_query_mc_rec
607 *
608 * DESCRIPTION
609 * Retrieves a multicast record result from a MAD returned by a call to
610 * osmv_query_sa().
611 *
612 * SYNOPSIS
613 */
osmv_get_query_mc_rec(IN osm_madw_t * p_result_madw,IN uint32_t result_index)614 static inline ib_member_rec_t *osmv_get_query_mc_rec(IN osm_madw_t *
615 p_result_madw,
616 IN uint32_t result_index)
617 {
618 ib_sa_mad_t __attribute__((__unused__)) *p_sa_mad;
619
620 CL_ASSERT(p_result_madw);
621 p_sa_mad = (ib_sa_mad_t *) osm_madw_get_mad_ptr(p_result_madw);
622 CL_ASSERT(p_sa_mad && p_sa_mad->attr_id == IB_MAD_ATTR_MCMEMBER_RECORD);
623
624 return ((ib_member_rec_t *) osmv_get_query_result(p_result_madw,
625 result_index));
626 }
627
628 /*
629 * PARAMETERS
630 * p_result_madw
631 * [in] This is a reference to the MAD returned as a result of the
632 * query.
633 *
634 * result_index
635 * [in] A zero-based index indicating which result to return.
636 *
637 * NOTES
638 * This call returns a pointer to the start of a service record result from
639 * a call to osmv_query_sa().
640 *
641 * SEE ALSO
642 * osmv_query_res_t, osm_madw_t, osmv_get_query_result, ib_member_rec_t
643 *****/
644
645 /****f* OpenSM Vendor SA Client/osmv_get_query_inform_info_rec
646 * NAME
647 * osmv_get_query_inform_info_rec
648 *
649 * DESCRIPTION
650 * Retrieves an InformInfo record result from a MAD returned by
651 * a call to osmv_query_sa().
652 *
653 * SYNOPSIS
654 */
osmv_get_query_inform_info_rec(IN osm_madw_t * p_result_madw,IN uint32_t result_index)655 static inline ib_inform_info_record_t *osmv_get_query_inform_info_rec(IN
656 osm_madw_t
657 *
658 p_result_madw,
659 IN
660 uint32_t
661 result_index)
662 {
663 ib_sa_mad_t __attribute__((__unused__)) *p_sa_mad;
664
665 CL_ASSERT(p_result_madw);
666 p_sa_mad = (ib_sa_mad_t *) osm_madw_get_mad_ptr(p_result_madw);
667 CL_ASSERT(p_sa_mad
668 && p_sa_mad->attr_id == IB_MAD_ATTR_INFORM_INFO_RECORD);
669
670 return ((ib_inform_info_record_t *) osmv_get_query_result(p_result_madw,
671 result_index));
672 }
673
674 /*
675 * PARAMETERS
676 * p_result_madw
677 * [in] This is a reference to the MAD returned as a result of the
678 * query.
679 *
680 * result_index
681 * [in] A zero-based index indicating which result to return.
682 *
683 * NOTES
684 * This call returns a pointer to the start of a service record result from
685 * a call to osmv_query_sa().
686 *
687 * SEE ALSO
688 * osmv_query_res_t, osm_madw_t, osmv_get_query_result, ib_inform_info_record_t
689 *****/
690
691 /****f* OpenSM Vendor SA Client/osmv_pfn_query_cb_t
692 * NAME
693 * osmv_pfn_query_cb_t
694 *
695 * DESCRIPTION
696 * User-defined callback invoked on completion of subnet administration
697 * query.
698 *
699 * SYNOPSIS
700 */
701 typedef void
702 (*osmv_pfn_query_cb_t) (IN osmv_query_res_t * p_query_res);
703 /*
704 * PARAMETERS
705 * p_query_res
706 * [in] This is a reference to a structure containing the result of
707 * the query.
708 *
709 * NOTES
710 * This routine is invoked to notify a client of the result of a subnet
711 * administration query. The p_query_rec parameter references the result
712 * of the query and, in the case of a successful query, any information
713 * returned by subnet administration.
714 *
715 * In the kernel, this callback is usually invoked using a tasklet,
716 * dependent on the implementation of the underlying verbs provider driver.
717 *
718 * SEE ALSO
719 * osmv_query_res_t
720 *****/
721
722 /****s* OpenSM Vendor SA Client/osmv_query_req_t
723 * NAME
724 * osmv_query_req_t
725 *
726 * DESCRIPTION
727 * Information used to request an access layer provided query of subnet
728 * administration.
729 *
730 * SYNOPSIS
731 */
732 typedef struct _osmv_query_req {
733 osmv_query_type_t query_type;
734 const void *p_query_input;
735 ib_net64_t sm_key;
736
737 uint32_t timeout_ms;
738 uint32_t retry_cnt;
739 osmv_flags_t flags;
740
741 const void *query_context;
742 osmv_pfn_query_cb_t pfn_query_cb;
743 int with_grh;
744 ib_gid_t gid;
745 } osmv_query_req_t;
746 /*
747 * FIELDS
748 * query_type
749 * Indicates the type of query that the access layer should
750 * perform.
751 *
752 * p_query_input
753 * A pointer to the input for the query. The data referenced by
754 * this structure is dependent on the type of query being requested
755 * and is determined by the specified query_type.
756 *
757 * sm_key
758 * The SM_Key to be provided with the SA MAD for authentication.
759 * Normally 0 is used.
760 *
761 * timeout_ms
762 * Specifies the number of milliseconds to wait for a response for
763 * this query until retrying or timing out the request.
764 *
765 * retry_cnt
766 * Specifies the number of times that the query will be retried
767 * before failing the request.
768 *
769 * flags
770 * Used to describe the mode of operation. Set to IB_FLAGS_SYNC to
771 * process the called routine synchronously.
772 *
773 * query_context
774 * User-defined context information associated with this query.
775 * The context data is returned to the user as a part of their
776 * query callback.
777 *
778 * pfn_query_cb
779 * A user-defined callback that is invoked upon completion of the
780 * query.
781 *
782 * with_grh
783 * Indicates that SA queries should be sent with GRH.
784 *
785 * gid
786 * Used to store the SM/SA GID.
787 *
788 * NOTES
789 * This structure is used when requesting an osm vendor provided query
790 * of subnet administration. Clients specify the type of query through
791 * the query_type field. Based on the type of query, the p_query_input
792 * field is set to reference the appropriate data structure.
793 *
794 * The information referenced by the p_query_input field is one of the
795 * following:
796 *
797 * -- a NULL terminated service name
798 * -- a service id
799 * -- a single GUID
800 * -- a pair of GUIDs specified through an osmv_guid_pair_t structure
801 * -- a pair of GIDs specified through an osmv_gid_pair_t structure
802 *
803 * SEE ALSO
804 * osmv_query_type_t, osmv_pfn_query_cb_t, osmv_guid_pair_t,
805 * osmv_gid_pair_t
806 *****/
807
808 /****f* OpenSM Vendor SA Client/osmv_bind_sa
809 * NAME
810 * osmv_bind_sa
811 *
812 * DESCRIPTION
813 * Bind to the SA service and return a handle to be used for later
814 * queries.
815 *
816 *
817 * SYNOPSIS
818 */
819 osm_bind_handle_t
820 osmv_bind_sa(IN osm_vendor_t * const p_vend,
821 IN osm_mad_pool_t * const p_mad_pool, IN ib_net64_t port_guid);
822 /*
823 * PARAMETERS
824 * p_vend
825 * [in] an osm_vendor object to work with
826 *
827 * p_mad_pool
828 * [in] mad pool to obtain madw from
829 *
830 * port_guid
831 * [in] the port guid to attach to.
832 *
833 * RETURN VALUE
834 * Bind handle to be used for later SA queries or OSM_BIND_INVALID_HANDLE
835 *
836 * NOTES
837 *
838 * SEE ALSO
839 * osmv_query_sa
840 *********/
841
842 /****f* OpenSM Vendor SA Client/osmv_query_sa
843 * NAME
844 * osmv_query_sa
845 *
846 * DESCRIPTION
847 * Query the SA given an SA query request (similar to IBAL ib_query).
848 *
849 * SYNOPSIS
850 */
851 ib_api_status_t
852 osmv_query_sa(IN osm_bind_handle_t h_bind,
853 IN const osmv_query_req_t * const p_query_req);
854 /*
855 * PARAMETERS
856 * h_bind
857 * [in] bind handle for this port. Should be previously
858 * obtained by calling osmv_bind_sa
859 *
860 * p_query_req
861 * [in] an SA query request structure.
862 *
863 * RETURN VALUE
864 * IB_SUCCESS if completed successfuly (or in ASYNC mode
865 * if the request was sent).
866 *
867 * NOTES
868 *
869 * SEE ALSO
870 * osmv_bind_sa
871 *********/
872
873 END_C_DECLS
874 #endif /* _OSM_VENDOR_SA_API_H_ */
875