xref: /illumos-gate/usr/src/uts/common/sys/ib/clients/of/rdma/rdma_cm.h (revision 588575c88d134c8f25f645542bcf36d61ac43a82)
1 /*
2  * This file contains definitions used in OFED defined user/kernel
3  * interfaces. These are imported from the OFED header rdma_cm.h. Oracle
4  * elects to have and use the contents of rdma_cm.h under and governed
5  * by the OpenIB.org BSD license (see below for details). However,
6  * the following notice accompanied the original version of this file:
7  */
8 
9 /*
10  * Copyright (c) 2005 Voltaire Inc.  All rights reserved.
11  * Copyright (c) 2005 Intel Corporation.  All rights reserved.
12  *
13  * This Software is licensed under one of the following licenses:
14  *
15  * 1) under the terms of the "Common Public License 1.0" a copy of which is
16  *    available from the Open Source Initiative, see
17  *    http://www.opensource.org/licenses/cpl.php.
18  *
19  * 2) under the terms of the "The BSD License" a copy of which is
20  *    available from the Open Source Initiative, see
21  *    http://www.opensource.org/licenses/bsd-license.php.
22  *
23  * 3) under the terms of the "GNU General Public License (GPL) Version 2" a
24  *    copy of which is available from the Open Source Initiative, see
25  *    http://www.opensource.org/licenses/gpl-license.php.
26  *
27  * Licensee has the right to choose one of the above licenses.
28  *
29  * Redistributions of source code must retain the above copyright
30  * notice and one of the license notices.
31  *
32  * Redistributions in binary form must reproduce both the above copyright
33  * notice, one of the license notices in the documentation
34  * and/or other materials provided with the distribution.
35  *
36  */
37 
38 #ifndef _SYS_IB_CLIENTS_OF_RDMA_RDMA_CM_H
39 #define	_SYS_IB_CLIENTS_OF_RDMA_RDMA_CM_H
40 
41 #ifdef __cplusplus
42 extern "C" {
43 #endif
44 
45 #include <sys/socket.h>
46 
47 /*
48  * Upon receiving a device removal event, users must destroy the associated
49  * RDMA identifier and release all resources allocated with the device.
50  */
51 enum rdma_cm_event_type {
52 	RDMA_CM_EVENT_ADDR_RESOLVED,
53 	RDMA_CM_EVENT_ADDR_ERROR,
54 	RDMA_CM_EVENT_ROUTE_RESOLVED,
55 	RDMA_CM_EVENT_ROUTE_ERROR,
56 	RDMA_CM_EVENT_CONNECT_REQUEST,
57 	RDMA_CM_EVENT_CONNECT_RESPONSE,
58 	RDMA_CM_EVENT_CONNECT_ERROR,
59 	RDMA_CM_EVENT_UNREACHABLE,
60 	RDMA_CM_EVENT_REJECTED,
61 	RDMA_CM_EVENT_ESTABLISHED,
62 	RDMA_CM_EVENT_DISCONNECTED,
63 	RDMA_CM_EVENT_DEVICE_REMOVAL,
64 	RDMA_CM_EVENT_MULTICAST_JOIN,
65 	RDMA_CM_EVENT_MULTICAST_ERROR,
66 	RDMA_CM_EVENT_ADDR_CHANGE
67 };
68 
69 enum rdma_port_space {
70 	RDMA_PS_SDP  = 0x0001,
71 	RDMA_PS_IPOIB = 0x0002,
72 	RDMA_PS_TCP  = 0x0106,
73 	RDMA_PS_UDP  = 0x0111,
74 	RDMA_PS_SCTP = 0x0183
75 };
76 
77 struct rdma_addr {
78 	struct sockaddr src_addr;
79 	uint8_t		src_pad[sizeof (struct sockaddr_in6) -
80 				sizeof (struct sockaddr)];
81 	struct sockaddr dst_addr;
82 	uint8_t		dst_pad[sizeof (struct sockaddr_in6) -
83 				sizeof (struct sockaddr)];
84 	struct rdma_dev_addr dev_addr;
85 };
86 
87 struct rdma_route {
88 	struct rdma_addr addr;
89 	struct ib_sa_path_rec *path_rec;
90 	int num_paths;
91 };
92 
93 struct rdma_conn_param {
94 	const void *private_data;
95 	uint8_t private_data_len;
96 	uint8_t responder_resources;
97 	uint8_t initiator_depth;
98 	uint8_t flow_control;
99 	uint8_t retry_count;		/* ignored when accepting */
100 	uint8_t rnr_retry_count;
101 	/* Fields below ignored if a QP is created on the rdma_cm_id. */
102 	uint8_t srq;
103 	uint32_t qp_num;
104 };
105 
106 struct rdma_ud_param {
107 	const void *private_data;
108 	uint8_t private_data_len;
109 	struct ib_ah_attr ah_attr;
110 	uint32_t qp_num;
111 	uint32_t qkey;
112 };
113 
114 struct rdma_cm_event {
115 	enum rdma_cm_event_type	 event;
116 	int			 status;
117 	union {
118 		struct rdma_conn_param	conn;
119 		struct rdma_ud_param	ud;
120 	} param;
121 };
122 
123 struct rdma_cm_id;
124 
125 /*
126  * rdma_cm_event_handler - Callback used to report user events.
127  *
128  * Notes: Users may not call rdma_destroy_id from this callback to destroy
129  *   the passed in id, or a corresponding listen id.  Returning a
130  *   non-zero value from the callback will destroy the passed in id.
131  */
132 typedef int (*rdma_cm_event_handler)(struct rdma_cm_id *id,
133 						struct rdma_cm_event *event);
134 
135 struct rdma_cm_id {
136 	struct ib_device	*device;
137 	void			*context;
138 	struct ib_qp		*qp;
139 	rdma_cm_event_handler	 event_handler;
140 	struct rdma_route	 route;
141 	enum rdma_port_space	 ps;
142 	uint8_t			 port_num;
143 };
144 
145 /*
146  * rdma_create_id - Create an RDMA identifier.
147  *
148  * @event_handler: User callback invoked to report events associated with the
149  *   returned rdma_id.
150  * @context: User specified context associated with the id.
151  * @ps: RDMA port space.
152  */
153 struct rdma_cm_id *rdma_create_id(rdma_cm_event_handler event_handler,
154     void *context, enum rdma_port_space ps);
155 
156 /*
157  * rdma_map_id2clnthdl -
158  * 	Maps RDMA identifier with IBTF and / or ROF client handles. Either
159  *	of the handles can be NULL, but both should not be NULL. This API
160  *	is called just after calling rdma_create_id() on the passive side.
161  *
162  * rdma_map_id2qphdl -
163  *	This is used to map RDMA-CM ID to IBTF or ROF client handle and
164  *	the QP handle. This is called by the passive side just after
165  *	rdma_create_id() and on the active side just before rdma_accept()
166  *	in the CONNECTION_REQUEST event handler.
167  */
168 void rdma_map_id2clnthdl(struct rdma_cm_id *id, void *ib_client_hdl,
169     void *iw_client_hdl);
170 void rdma_map_id2qphdl(struct rdma_cm_id *id, void *qp_hdl);
171 
172 /*
173  * rdma_destroy_id - Destroys an RDMA identifier.
174  *
175  * @id: RDMA identifier.
176  *
177  * Note: calling this function has the effect of canceling in-flight
178  * asynchronous operations associated with the id.
179  */
180 void rdma_destroy_id(struct rdma_cm_id *id);
181 
182 /*
183  * rdma_bind_addr - Bind an RDMA identifier to a source address and
184  *   associated RDMA device, if needed.
185  *
186  * @id: RDMA identifier.
187  * @addr: Local address information.  Wildcard values are permitted.
188  *
189  * This associates a source address with the RDMA identifier before calling
190  * rdma_listen.  If a specific local address is given, the RDMA identifier will
191  * be bound to a local RDMA device.
192  */
193 int rdma_bind_addr(struct rdma_cm_id *id, struct sockaddr *addr);
194 
195 /*
196  * rdma_resolve_addr - Resolve destination and optional source addresses
197  *   from IP addresses to an RDMA address.  If successful, the specified
198  *   rdma_cm_id will be bound to a local device.
199  *
200  * @id: RDMA identifier.
201  * @src_addr: Source address information.  This parameter may be NULL.
202  * @dst_addr: Destination address information.
203  * @timeout_ms: Time to wait for resolution to complete.
204  */
205 int rdma_resolve_addr(struct rdma_cm_id *id, struct sockaddr *src_addr,
206 				struct sockaddr *dst_addr, int timeout_ms);
207 
208 /*
209  * rdma_resolve_route - Resolve the RDMA address bound to the RDMA identifier
210  *   into route information needed to establish a connection.
211  *
212  * This is called on the client side of a connection.
213  * Users must have first called rdma_resolve_addr to resolve a dst_addr
214  * into an RDMA address before calling this routine.
215  */
216 int rdma_resolve_route(struct rdma_cm_id *id, int timeout_ms);
217 
218 
219 /*
220  * rdma_init_qp_attr - Initializes the QP attributes for use in transitioning
221  *   to a specified QP state.
222  * @id: Communication identifier associated with the QP attributes to
223  *   initialize.
224  * @qp_attr: On input, specifies the desired QP state.  On output, the
225  *   mandatory and desired optional attributes will be set in order to
226  *   modify the QP to the specified state.
227  * @qp_attr_mask: The QP attribute mask that may be used to transition the
228  *   QP to the specified state.
229  *
230  * Users must set the @qp_attr->qp_state to the desired QP state.  This call
231  * will set all required attributes for the given transition, along with
232  * known optional attributes.  Users may override the attributes returned from
233  * this call before calling ib_modify_qp.
234  *
235  * Users that wish to have their QP automatically transitioned through its
236  * states can associate a QP with the rdma_cm_id by calling rdma_create_qp().
237  */
238 int rdma_init_qp_attr(struct rdma_cm_id *id, struct ib_qp_attr *qp_attr,
239 							int *qp_attr_mask);
240 /*
241  * rdma_connect - Initiate an active connection request.
242  * @id: Connection identifier to connect.
243  * @conn_param: Connection information used for connected QPs.
244  *
245  * Users must have resolved a route for the rdma_cm_id to connect with
246  * by having called rdma_resolve_route before calling this routine.
247  *
248  * This call will either connect to a remote QP or obtain remote QP
249  * information for unconnected rdma_cm_id's.  The actual operation is
250  * based on the rdma_cm_id's port space.
251  */
252 int rdma_connect(struct rdma_cm_id *id, struct rdma_conn_param *conn_param);
253 
254 /*
255  * rdma_listen - This function is called by the passive side to
256  *   listen for incoming connection requests.
257  *
258  * Users must have bound the rdma_cm_id to a local address by calling
259  * rdma_bind_addr before calling this routine.
260  */
261 int rdma_listen(struct rdma_cm_id *id, int backlog);
262 
263 /*
264  * rdma_accept - Called to accept a connection request or response.
265  * @id: Connection identifier associated with the request.
266  * @conn_param: Information needed to establish the connection.  This must be
267  *   provided if accepting a connection request.  If accepting a connection
268  *   response, this parameter must be NULL.
269  *
270  * Typically, this routine is only called by the listener to accept a connection
271  * request.  It must also be called on the active side of a connection if the
272  * user is performing their own QP transitions.
273  *
274  * In the case of error, a reject message is sent to the remote side and the
275  * state of the qp associated with the id is modified to error, such that any
276  * previously posted receive buffers would be flushed.
277  */
278 int rdma_accept(struct rdma_cm_id *id, struct rdma_conn_param *conn_param);
279 
280 /*
281  * rdma_notify - Notifies the RDMA CM of an asynchronous event that has
282  * occurred on the connection.
283  * @id: Connection identifier to transition to established.
284  * @event: Asynchronous event.
285  *
286  * This routine should be invoked by users to notify the CM of relevant
287  * communication events.  Events that should be reported to the CM and
288  * when to report them are:
289  *
290  * IB_EVENT_COMM_EST - Used when a message is received on a connected
291  *    QP before an RTU has been received.
292  */
293 int rdma_notify(struct rdma_cm_id *id, enum ib_event_type event);
294 
295 /*
296  * rdma_reject - Called to reject a connection request or response.
297  */
298 int rdma_reject(struct rdma_cm_id *id, const void *private_data,
299 		uint8_t private_data_len);
300 
301 /*
302  * rdma_disconnect - This function disconnects the associated QP and
303  *   transitions it into the error state.
304  */
305 int rdma_disconnect(struct rdma_cm_id *id);
306 
307 /*
308  * rdma_join_multicast - Join the multicast group specified by the given
309  *   address.
310  * @id: Communication identifier associated with the request.
311  * @addr: Multicast address identifying the group to join.
312  * @context: User-defined context associated with the join request, returned
313  * to the user through the private_data pointer in multicast events.
314  */
315 int rdma_join_multicast(struct rdma_cm_id *id, struct sockaddr *addr,
316 			void *context);
317 
318 /*
319  * rdma_leave_multicast - Leave the multicast group specified by the given
320  *   address.
321  */
322 void rdma_leave_multicast(struct rdma_cm_id *id, struct sockaddr *addr);
323 
324 /*
325  * rdma_set_service_type - Set the type of service associated with a
326  *   connection identifier.
327  * @id: Communication identifier to associated with service type.
328  * @tos: Type of service.
329  *
330  * The type of service is interpretted as a differentiated service
331  * field (RFC 2474).  The service type should be specified before
332  * performing route resolution, as existing communication on the
333  * connection identifier may be unaffected.  The type of service
334  * requested may not be supported by the network to all destinations.
335  */
336 void rdma_set_service_type(struct rdma_cm_id *id, int tos);
337 
338 
339 /*
340  * rdma_create_qp - Allocate a QP and associate it with the specified RDMA
341  * identifier.
342  *
343  * QPs allocated to an rdma_cm_id will automatically be transitioned by the CMA
344  * through their states.
345  */
346 int rdma_create_qp(struct rdma_cm_id *id, struct ib_pd *pd,
347     struct ib_qp_init_attr *qp_init_attr);
348 
349 /*
350  * rdma_destroy_qp - Deallocate the QP associated with the specified RDMA
351  * identifier.
352  *
353  * Users must destroy any QP associated with an RDMA identifier before
354  * destroying the RDMA ID.
355  */
356 void rdma_destroy_qp(struct rdma_cm_id *id);
357 
358 #ifdef __cplusplus
359 }
360 #endif
361 #endif /* _SYS_IB_CLIENTS_OF_RDMA_RDMA_CM_H */
362