xref: /titanic_51/usr/src/uts/common/sys/ib/mgt/ibmf/ibmf_saa.h (revision 7c478bd95313f5f23a4c958a745db2134aa03244)
1 /*
2  * CDDL HEADER START
3  *
4  * The contents of this file are subject to the terms of the
5  * Common Development and Distribution License, Version 1.0 only
6  * (the "License").  You may not use this file except in compliance
7  * with the License.
8  *
9  * You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
10  * or http://www.opensolaris.org/os/licensing.
11  * See the License for the specific language governing permissions
12  * and limitations under the License.
13  *
14  * When distributing Covered Code, include this CDDL HEADER in each
15  * file and include the License file at usr/src/OPENSOLARIS.LICENSE.
16  * If applicable, add the following below this CDDL HEADER, with the
17  * fields enclosed by brackets "[]" replaced with your own identifying
18  * information: Portions Copyright [yyyy] [name of copyright owner]
19  *
20  * CDDL HEADER END
21  */
22 /*
23  * Copyright 2003 Sun Microsystems, Inc.  All rights reserved.
24  * Use is subject to license terms.
25  */
26 
27 #ifndef	_SYS_IB_MGT_IBMF_IBMF_SAA_H
28 #define	_SYS_IB_MGT_IBMF_IBMF_SAA_H
29 
30 #pragma ident	"%Z%%M%	%I%	%E% SMI"
31 
32 #ifdef	__cplusplus
33 extern "C" {
34 #endif
35 
36 #include <sys/ib/ib_types.h>
37 #include <sys/ib/mgt/sa_recs.h>
38 
39 /*
40  * SA Access Interface: Interfaces to enable access to the SA
41  */
42 
43 #define	IBMF_SAA_PKEY_WC	0	/* partition key wildcard */
44 #define	IBMF_SAA_MTU_WC		0	/* mtu wilcard for gid_to_pathrecords */
45 
46 typedef enum _ibmf_saa_access_type_t {
47 	IBMF_SAA_RETRIEVE,
48 	IBMF_SAA_UPDATE,
49 	IBMF_SAA_DELETE
50 } ibmf_saa_access_type_t;
51 
52 /*
53  * ibmf_saa_handle
54  *	Opaque handle to identify the consumer
55  */
56 typedef struct ibmf_saa_handle *ibmf_saa_handle_t;
57 
58 /*
59  * ibmf_saa_cb_t
60  * ibmf_saa's callback to clients to inform them that the response to an
61  * asynchronous request has arrived or that the request timed out.
62  *
63  * Input Arguments
64  * clnt_private - opaque handle to client specific data (sq_callback_arg)
65  * length - size of response returned
66  * result - pointer to buffer of response.  Data will be in host-endian format
67  * and unpacked.  Client can just cast to a pointer to the structure
68  * status - ibmf status.  Status can be any of the values returned by a
69  * synchronous ibmf_sa_access() call.
70  *
71  * Output Arguments
72  * none
73  *
74  * Returns
75  * none
76  */
77 typedef void (*ibmf_saa_cb_t) (
78     void 	*callback_arg,
79     size_t	length,
80     char	*result,
81     int		status);
82 
83 /*
84  * structure to provide parameters to ibmf_sa_access call
85  */
86 typedef struct ibmf_saa_access_args_s {
87 	/* MAD attribute ID */
88 	uint16_t		sq_attr_id;
89 
90 	/* retrieve, update, or delete */
91 	ibmf_saa_access_type_t 	sq_access_type;
92 
93 	/* SA MAD component mask indicating fields in template to query on */
94 	uint64_t		sq_component_mask;
95 
96 	/* pointer to template */
97 	void			*sq_template;
98 
99 	/*
100 	 * length, in bytes, of template size for attributes which ibmf does
101 	 * not know about; ignored for known attribute id's.  length should be
102 	 * wire length and template for unknown attributes should be in wire
103 	 * format as ibmf will not be able to pack data.
104 	 */
105 	size_t			sq_template_length;
106 
107 	/* callback and argument when asynchronous request returns */
108 	ibmf_saa_cb_t		sq_callback;
109 	void			*sq_callback_arg;
110 } ibmf_saa_access_args_t;
111 
112 /*
113  * enumeration of subnet events
114  *
115  * IBMF_SAA_EVENT_GID_AVAILABLE
116  *              the identified gid is available
117  * IBMF_SAA_EVENT_GID_UNAVAILABLE
118  *              the identified gid is unavailable
119  * IBMF_SAA_EVENT_MCG_CREATED
120  *              MC group identified by mgid is created
121  * IBMF_SAA_EVENT_MCG_DELETED
122  *              MC group identified by mgid is deleted
123  * IBMF_SAA_EVENT_CAP_MASK_CHG
124  *              Portinfo.CapabilityMask changed
125  * IBMF_SAA_EVENT_SYS_IMG_GUID_CHG
126  *              System Image GUID changed
127  * IBMF_SAA_EVENT_SUBSCRIBER_STATUS_CHG
128  *		Status of ibmf subscriptions changed
129  */
130 typedef enum ibmf_saa_subnet_event_e {
131 
132 	IBMF_SAA_EVENT_GID_AVAILABLE,
133 	IBMF_SAA_EVENT_GID_UNAVAILABLE,
134 	IBMF_SAA_EVENT_MCG_CREATED,
135 	IBMF_SAA_EVENT_MCG_DELETED,
136 	IBMF_SAA_EVENT_CAP_MASK_CHG,
137 	IBMF_SAA_EVENT_SYS_IMG_GUID_CHG,
138 	IBMF_SAA_EVENT_SUBSCRIBER_STATUS_CHG
139 
140 } ibmf_saa_subnet_event_t;
141 
142 /*
143  * ibmf must subscribe with the Subnet Administrator to provide the subnet
144  * events for its clients.  It registers for the four trap producer types: CA,
145  * switch, router, and subnet management.  If any of these registrations fails
146  * the ibmf will notify each client that registered for events.  Clients are
147  * notified by ibmf through their registered callback and the
148  * SUBSCRIBER_STATUS_CHG event.
149  *
150  * For this event, the event_details producer_type_status_mask will be set.
151  * Each bit in the mask corresponds to a different producer type.  When the bit
152  * is on the ibmf was able to successfully subscribe for events from that
153  * producer.  When the bit is off, ibmf was unable to subscribe and clients may
154  * not receive events from that producer type.
155  *
156  * For example, if the status_mask is 0xb then events will be received that
157  * correspond to CA's, switches, and subnet management traps.  However, traps
158  * generated by routers may not be received.
159  *
160  * The ibmf re-registers for events when the port transitions to active.  If the
161  * event status mask changes the ibmf will generate another
162  * SUBSCRIBER_STATUS_CHG event with the new producer type status mask.  When
163  * clients register they should only expect to receive a SUBSCRIBER_STATUS_CHG
164  * event if one of the registrations failed.  If all four registrations
165  * succeeded no event will be generated.
166  *
167  * If the port goes down, a SUBSCRIBER_STATUS_CHG event is not generated.
168  * Clients should realize that events will not be forwarded.  If the port
169  * transitions back to active ibmf_saa will resubscribe on behalf of the client.
170  * If this subscription fails a SUBSCRIBER_STATUS_CHG event will be generated.
171  *
172  */
173 
174 #define	IBMF_SAA_EVENT_STATUS_MASK_PRODUCER_CA		(1 << 0)
175 #define	IBMF_SAA_EVENT_STATUS_MASK_PRODUCER_SWITCH	(1 << 1)
176 #define	IBMF_SAA_EVENT_STATUS_MASK_PRODUCER_ROUTER	(1 << 2)
177 #define	IBMF_SAA_EVENT_STATUS_MASK_PRODUCER_SM		(1 << 3)
178 
179 /*
180  * structure passed as event_details argument of ibmf_saa subnet event
181  * callback.
182  *
183  * Only some of the structure members are valid for a given event as given
184  * below:
185  *
186  * member              		event type
187  * ------              		----------
188  * ie_gid               	IBMF_SAA_EVENT_GID_AVAILABLE,
189  *					IBMF_SAA_EVENT_GID_UNAVAILABLE,
190  *                              	IBMF_SAA_EVENT_MCG_CREATED, and
191  *                              	IBMF_SAA_EVENT_MCG_DELETED
192  * ie_lid               	IBMF_SAA_EVENT_CAP_MASK_CHG and
193  *                              	IBMF_SAA_EVENT_SYS_IMG_GUID_CHG
194  * ie_capability_mask   	IBMF_SAA_EVENT_CAP_MASK_CHG
195  * ie_sysimg_guid       	IBMF_SAA_EVENT_SYS_IMG_GUID_CHG
196  * ie_producer_type_status_mask	IBMF_SAA_EVENT_SUBSCRIBER_STATUS_CHG
197  *
198  */
199 typedef struct ibmf_saa_event_details_s {
200 	ib_gid_t	ie_gid;
201 	ib_guid_t	ie_sysimg_guid;
202 	uint32_t	ie_capability_mask; /* values defined in sm_attr.h */
203 	ib_lid_t	ie_lid;
204 	uint8_t		ie_producer_event_status_mask;
205 } ibmf_saa_event_details_t;
206 
207 /*
208  * Callback invoked when one of the events the client subscribed for
209  * at ibmf_sa_session_open() time happens.
210  *
211  * This callback can occur before ibmf_sa_session_open() returns.
212  *
213  * Each callback is on a separate thread.  ibmf clients may block in the event
214  * callback.  However, under heavy system load ibmf may not be able to generate
215  * event callbacks.  Also, event callbacks, including SUBSCRIBER_STATUS_CHG,
216  * could be dispatched out-of-order.
217  *
218  * Arguments:
219  * ibmf_saa_handle              - Client's ibmf_saa_handle
220  * ibmf_saa_event               - event that caused the callback
221  * event_details                - additional data for the event
222  * callback_arg                 - event_callback_arg member of
223  *                                ibmf_saa_subnet_event_args_t
224  */
225 typedef void (*ibmf_saa_subnet_event_cb_t)(
226 	ibmf_saa_handle_t		ibmf_saa_handle,
227 	ibmf_saa_subnet_event_t		ibmf_saa_event,
228 	ibmf_saa_event_details_t	*event_details,
229 	void				*callback_arg);
230 
231 typedef struct ibmf_saa_subnet_event_args_s {
232 
233 	/* func to be called when a subnet event happens */
234 	ibmf_saa_subnet_event_cb_t	is_event_callback;
235 
236 	/* call back arg */
237 	void				*is_event_callback_arg;
238 
239 } ibmf_saa_subnet_event_args_t;
240 
241 /*
242  * ibmf_sa_session_open():
243  *
244  * Before using the ibmf_saa interface, consumers should register with the
245  * ibmf_saa interface by calling ibmf_sa_session_open(). Upon a successful
246  * registration, a handle is returned for use in subsequent interaction with the
247  * ibmf_saa interface; this handle is also provided as an argument to subnet
248  * event notification function.
249  *
250  * Consumers can register to be notified of subnet events such as GID
251  * being available/unavailable.  Clients which provide a non-NULL event args
252  * structure will have the is_event_callback function called when an event is
253  * received or there is a failure in subscribing for events.  This callback may
254  * be generated before the ibmf_sa_session_open() call returns.
255  *
256  * This interface blocks allocating memory, but not waiting for any packet
257  * responses.
258  *
259  * Arguments:
260  * port_guid            - GUID of the port.
261  * event_args		- subnet event registration details
262  * sm_key               - only filled in if the consumer is an SM
263  * ibmf_version         - version of the interface (IBMF_VERSION)
264  * flags                - unused
265  *
266  * Return values:
267  * IBMF_SUCCESS         - registration succeeded
268  * IBMF_BAD_PORT	- registration failed; active port not found
269  * IBMF_BAD_PORT_STATE  - registration failed; port found but not active or
270  * 			previous registration failed
271  * IBMF_NO_MEMORY	- registration failed; could not allocate memory
272  * IBMF_NO_RESOURCES    - registration failed due to a resource issue
273  * IBMF_BUSY            - registration failed; too many clients registered
274  *                      for this port
275  * IBMF_TRANSPORT_FAILURE - failure with underlying transport framework
276  * IBMF_INVALID_ARG     - ibmf_saa_handle arg was NULL
277  */
278 int ibmf_sa_session_open(
279 		ib_guid_t			port_guid,
280 		ib_smkey_t			sm_key,
281 		ibmf_saa_subnet_event_args_t	*event_args,
282 		uint_t				ibmf_version,
283 		uint_t				flags,
284 		ibmf_saa_handle_t		*ibmf_saa_handle);
285 
286 /*
287  * ibmf_sa_session_close()
288  *
289  * Unregister a consumer of the SA_Access interface
290  *
291  * This interface blocks.
292  *
293  * Arguments:
294  * ibmf_saa_handle	- handle returned from sa_session_open()
295  * flags		- unused
296  *
297  * Return values:
298  * IBMF_SUCCESS		- unregistration succeeded
299  * IBMF_BAD_HANDLE	- unregistration failed; handle is not valid or
300  *			  session_close has already been called
301  * IBMF_INVALID_ARG	- ibmf_saa_handle arg was NULL
302  *
303  * All outstanding callbacks will be canceled before this function returns.
304  */
305 int	ibmf_sa_session_close(
306 		ibmf_saa_handle_t	*ibmf_saa_handle,
307 		uint_t			flags);
308 
309 /*
310  * ibmf_sa_access
311  *
312  * Retrieve records from the SA given an AttributeID, ComponentMask,
313  * and a template
314  *
315  * This interface blocks if the callback parameter is NULL.
316  *
317  * Input Arguments:
318  * ibmf_saa_handle	- handle returned from ibmf_sa_session_open()
319  * access_args 		- structure containing various parameters for the query
320  * flags 		- unsused
321  *
322  * Output Arguments:
323  * length		- size of buffer returned
324  * result		- pointer to buffer of records returned in response.
325  *			  Buffer is host-endian, unpacked can be cast to one of
326  *			  the record types in sa_recs.h
327  *
328  * Return values:
329  * IBMF_SUCCESS 	- query succeeded
330  * IBMF_BAD_HANDLE	- sa session handle is invalid
331  * IBMF_BAD_PORT_STATE	- port in incorrect state
332  * IBMF_INVALID_ARG	- one of the pointer parameters was NULL
333  * IBMF_NO_RESOURCES	- ibmf could not allocate ib resources or SA returned
334  *			  ERR_NO_RESOURCES
335  * IBMF_TRANS_TIMEOUT	- transaction timed out
336  * IBMF_TRANS_FAILURE	- transaction failure
337  * IBMF_NO_MEMORY	- ibmf could not allocate memory
338  * IBMF_REQ_INVALID	- send and recv buffer the same for a sequenced
339  *			  transaction or the SA returned an ERR_REQ_INVALID
340  * IBMF_NO_RECORDS	- no records matched query
341  * IBMF_TOO_MANY_RECORDS- SA returned SA_ERR_TOO_MANY_RECORDS
342  * IBMF_INVALID_GID	- SA returned SA_INVALID_GID
343  * IBMF_INSUFF_COMPS	- SA returned SA_ERR_INSUFFICIENT_COMPS
344  * IBMF_UNSUPP_METHOD	- SA returned MAD_STATUS_UNSUPP_METHOD
345  * IBMF_UNSUPP_METHOD_ATTR - SA returned MAD_STATUS_UNSUPP_METHOD_ATTR
346  * IBMF_INVALID_FIELD	- SA returned MAD_STATUS_INVALID_FIELD
347  * IBMF_NO_ACTIVE_PORTS - no active ports found
348  *
349  * Upon successful completion, result points to a buffer containing the records.
350  * length is the size in bytes of the buffer returned in result.  If there are
351  * no records or the call failed the length is 0.
352  *
353  * The consumer is responsible for freeing the memory associated with result.
354  */
355 int	ibmf_sa_access(
356 		ibmf_saa_handle_t	ibmf_saa_handle,
357 		ibmf_saa_access_args_t	*access_args,
358 		uint_t			flags,
359 		size_t			*length,
360 		void			**result);
361 
362 /*
363  * Helper Functions.
364  *	Ease of use functions so that the consumer doesn't
365  * 	have to do the overhead of calling ibmf_sa_access() for
366  *	commonly used queries
367  */
368 
369 /*
370  * ibmf_saa_gid_to_pathrecords
371  * 	Given a source gid and a destination gid, return paths
372  *	between the gids.
373  *
374  * This interface blocks.
375  *
376  * Input Arguments:
377  * ibmf_saa_handle	- handle returned from ibmf_sa_session_open()
378  * sgid 		- source gid of path
379  * dgid			- destination gid of path
380  * p_key		- partition of path.  This value may be wildcarded with
381  *			  IBMF_SAA_PKEY_WC.
382  * mtu 			- preferred MTU of the path.  This argument may be
383  *			  wildcarded with IBMF_SAA_MTU_WC.
384  * reversible		- if B_TRUE, ibmf will query only reversible paths
385  *			  see Infiniband Specification table 171
386  * num_paths		- maximum number of paths to return
387  *			  numpaths should be checked for the actual number of
388  *			  records returned.
389  * flags		- unused
390  *
391  * Output Arguments:
392  * num_paths		- actual number of paths returned
393  * length		- size of buffer returned
394  * result		- pointer to buffer of path records returned in response
395  *
396  * Return values:
397  * Error codes are the same as ibmf_sa_access() return values
398  *
399  * Upon successful completion, result points to a buffer containing the records.
400  * length is the size in bytes of the buffer returned in result.  If there are
401  * no records or the call failed the length is 0.
402  *
403  * The consumer is responsible for freeing the memory associated with result.
404  */
405 int	ibmf_saa_gid_to_pathrecords(
406 		ibmf_saa_handle_t	ibmf_saa_handle,
407 		ib_gid_t		sgid,
408 		ib_gid_t		dgid,
409 		ib_pkey_t		p_key,
410 		ib_mtu_t		mtu,
411 		boolean_t		reversible,
412 		uint8_t			*num_paths,
413 		uint_t			flags,
414 		size_t			*length,
415 		sa_path_record_t	**result);
416 /*
417  * ibmf_saa_paths_from_gid
418  *      Given a source GID, return a path from the source gid
419  *	to every other port on the subnet.  It is assumed that the
420  *	subnet is fully connected.  Only one path per port on the subnet
421  *	is returned.
422  *
423  * This interface blocks.
424  *
425  * Arguments:
426  * ibmf_saa_handle	- handle returned from ibmf_sa_session_open()
427  * sgid 		- source gid of path
428  * pkey			- paritition of path.  This value may be wildcarded with
429  *			  IBMF_SAA_PKEY_WC.
430  * reversible		- if B_TRUE, ibmf will query only reversible paths;
431  *			  see Infiniband Specification table 171
432  * flags		- unused
433  *
434  * Output Arguments:
435  * num_paths		- number of paths returned
436  * length		- size of buffer returned
437  * result		- pointer to buffer of path records returned in response
438  *
439  * Return values:
440  * Error codes are the same as ibmf_sa_access() return values
441  *
442  * Upon successful completion, result points to a buffer containing the records.
443  * and num_paths is the number of path records returned.  length is the size
444  * in bytes of the buffer returned in result.  If there are no records or the
445  * call failed the length is 0.
446  *
447  * The consumer is responsible for freeing the memory associated with result.
448  */
449 int	ibmf_saa_paths_from_gid(
450 		ibmf_saa_handle_t	ibmf_saa_handle,
451 		ib_gid_t		sgid,
452 		ib_pkey_t		pkey,
453 		boolean_t		reversible,
454 		uint_t			flags,
455 		uint_t			*num_paths,
456 		size_t			*length,
457 		sa_path_record_t	**result);
458 
459 /*
460  * ibmf_saa_name_to_service_record:
461  *	Given a service name, return the service records associated
462  *	with it.
463  *
464  * This interface blocks.
465  *
466  * Input Arguments:
467  * ibmf_saa_handle	- handle returned from ibmf_sa_session_open()
468  * name			- service name, a null terminated string
469  * p_key		- partition that the service is requested on.  This
470  *			  value may be wildcarded with IBMF_SAA_PKEY_WC.
471  * flags		- unused
472  *
473  * Output Arguments:
474  * num_records		- number of service records returned
475  * length		- size of buffer returned
476  * result		- pointer to buffer of service records returned in
477  *			  response
478  *
479  * Return values:
480  * Error codes are the same as ibmf_sa_access() return values
481  *
482  * Upon successful completion, result points to a buffer containing the records.
483  * and num_records is the number of service records returned.  length is the
484  * size in bytes of the buffer returned in result.  If there are no records or
485  * the call failed the length is 0.
486  *
487  * The consumer is responsible for freeing the memory associated with result.
488  */
489 int	ibmf_saa_name_to_service_record(
490 		ibmf_saa_handle_t	ibmf_saa_handle,
491 		char			*service_name,
492 		ib_pkey_t		p_key,
493 		uint_t			flags,
494 		uint_t			*num_records,
495 		size_t			*length,
496 		sa_service_record_t	**result);
497 
498 /*
499  * ibmf_saa_id_to_service_record:
500  *      Given a service id, return the service records associated
501  *      with it.
502  *
503  * This interface blocks.
504  *
505  * Input Arguments:
506  * ibmf_saa_handle	- handle returned from ibmf_sa_session_open()
507  * id			- service id
508  * p_key		- partition that the service is requested on.  This
509  *			  value may be wildcarded with IBMF_SAA_PKEY_WC.
510  * flags		- unused
511  *
512  * Output Arguments:
513  * num_records		- number of service records returned
514  * length		- size of buffer returned
515  * result		- pointer to buffer of service records returned in
516  *			  response
517  *
518  * Return values:
519  * Error codes are the same as ibmf_sa_access() return values
520  *
521  * Upon successful completion, result points to a buffer containing the records.
522  * and num_records is the number of service records returned.  length is the
523  * size in bytes of the buffer returned in result.  If there are no records or
524  * the call failed the length is 0.
525  *
526  * The consumer is responsible for freeing the memory associated with result.
527  */
528 int	ibmf_saa_id_to_service_record(
529 		ibmf_saa_handle_t	ibmf_saa_handle,
530 		ib_svc_id_t		service_id,
531 		ib_pkey_t		p_key,
532 		uint_t			flags,
533 		uint_t			*num_records,
534 		size_t			*length,
535 		sa_service_record_t	**result);
536 
537 /*
538  * ibmf_saa_update_service_record
539  *	Given a pointer to a service record, either insert or delete it
540  *
541  * This interface blocks.
542  *
543  * Input Arguments:
544  * ibmf_saa_handle	- handle returned from ibmf_sa_session_open()
545  * service_record	- service record is to be inserted or deleted.  To
546  *			  delete a service record the GID, ID, P_Key, and
547  *			  Service Key must match what is in the SA.
548  * access_type		- indicates whether this is an insertion or deletion.
549  *			  valid values are IBMF_SAA_UPDATE or IBMF_SAA_DELETE
550  * flags		- unused
551  *
552  * Ouptut Arguments
553  * none
554  *
555  * Return values:
556  * Error codes are the same as ibmf_sa_access() return values
557  */
558 int	ibmf_saa_update_service_record(
559 		ibmf_saa_handle_t	ibmf_saa_handle,
560 		sa_service_record_t	*service_record,
561 		ibmf_saa_access_type_t	access_type,
562 		uint_t			flags);
563 
564 #ifdef __cplusplus
565 }
566 #endif
567 
568 #endif	/* _SYS_IB_MGT_IBMF_IBMF_SAA_H */
569