[openib-general] CM header file

Sean Hefty mshefty at ichips.intel.com
Wed Dec 15 16:25:23 PST 2004


Listed below is a start at an updated CM API.  Several details are 
missing, but there should be enough there to evaluate the direction of 
the CM.  Some design notes:

* User's are responsible for destroying "connection identifiers".  This 
was done to ensure that reference counting can be handled properly.
* The CM will allocate connection identifiers for clients upon 
receiving REQ or SIDR_REQ messages.  The new identifiers are returned 
to clients via a callback.  See below.
* QP transitions are expected to be done by the clients.
* The CM handles formatting CM MADs and tracking CM states.

Questions:

* Connection identifiers cannot be destroyed from within a CM callback. 
  I think that we can support this by adding a flag (destroying within 
callback) to the destroy call.  Is this worth adding?
* Should listening clients call an "accept" routine to wait for a 
connection request?  Currently, the API operates asynchronously and 
inokves a CM event handler.
* Should we allow forcing a connection into the established state, 
regardless of its previous state?  This would let the user connect 
without using the CM, and then give control of the connection to the CM.
* Should calls to send the LAP/APR set the QP's alternate path 
information?  Related to this, should the CM support a call to force 
path migration on the QP.

- Sean

/*
  * This software is available to you under a choice of one of two
  * licenses.  You may choose to be licensed under the terms of the GNU
  * General Public License (GPL) Version 2, available at
  * <http://www.fsf.org/copyleft/gpl.html>, or the OpenIB.org BSD
  * license, available in the LICENSE.TXT file accompanying this
  * software.  These details are also available at
  * <http://openib.org/license.html>.
  *
  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
  * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
  * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
  * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
  * BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
  * ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
  * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
  * SOFTWARE.
  *
  * Copyright (c) 2004 Intel Corporation.  All rights reserved.
  * Copyright (c) 2004 Topspin Corporation.  All rights reserved.
  * Copyright (c) 2004 Voltaire Corporation.  All rights reserved.
  *
  * $Id$
  */
#if !defined(IB_CM_H)
#define IB_CM_H

#include <ib_mad.h>

struct ib_path_record; //*** TBD: define me somewhere else (ib_smi.h?)

enum ib_cm_state {
	IB_CM_IDLE,
	IB_CM_LISTEN,
	IB_CM_REQ_SENT,
	IB_CM_REQ_RCVD,
	IB_CM_MRA_REQ_SENT
	IB_CM_MRA_REQ_RCVD,
	IB_CM_REP_SENT,
	IB_CM_REP_RCVD,
	IB_CM_MRA_REP_SENT,
	IB_CM_MRA_REP_RCVD,
	IB_CM_ESTABLISHED,
	IB_CM_LAP_SENT,
	IB_CM_LAP_RCVD,
	IB_CM_MRA_LAP_SENT,
	IB_CM_MRA_LAP_RCVD,
	IB_CM_DREQ_SENT,
	IB_CM_DREQ_RCVD,
	IB_CM_TIMEWAIT,
	IB_CM_SIDR_REQ_SENT,
	IB_CM_SIDR_REQ_RCVD
};

enum ib_cm_event_type {
	IB_CM_REQ_TIMEOUT,
	IB_CM_REQ_RECEIVED,
	IB_CM_REP_TIMEOUT,
	IB_CM_REP_RECEIVED,
	IB_CM_RTU_RECEIVED,
	IB_CM_DREQ_TIMEOUT
	IB_CM_DREQ_RECEIVED,
	IB_CM_DREP_RECEIVED,
	IB_CM_MRA_RECEIVED,
	IB_CM_LAP_TIMEOUT,
	IB_CM_LAP_RECEIVED,
	IB_CM_APR_RECEIVED
};

struct ib_cm_event {
	/* a whole lot more stuff goes here */
	void			*private_data;
	u8			private_data_len;
	enum ib_cm_event_type	event;
};

typedef void (*ib_cm_handler)(struct ib_cm_id *, struct ib_cm_event *);

struct ib_cm_id {
	ib_cm_handler		cm_handler;
	void			*context;
	u64			service_id;
	enum ib_cm_state	state;
};

/**
  * ib_create_cm_id - Allocate a connection identifier.
  * @cm_handler: Callback invoked to notify the user of CM events.
  * @context: User specified context associated with the connection
  *   identifier.
  *
  * Connection identifiers are used to track connection states and
  * listen requests.
  */
struct ib_cm_id *ib_create_cm_id(ib_cm_handler cm_handler,
				 void *context);

/**
  * ib_destroy_cm_id - Destroy a connection identifier.
  * @cm_id: Connection identifier to destroy.
  *
  * This call blocks until the connection identifier is destroyed.
  */
int ib_destroy_cm_id(struct ib_cm_id *cm_id);
//*** TBD : add flags to allow calling routine from CM callback...

/**
  * ib_cm_listen - Initiates listening on the specified service ID for
  *   connection and service ID resolution requests.
  * @cm_id: Connection identifier associated with the listen request.
  * @service_id: Service identifier matched against incoming connection
  *   and service ID resolution requests.
  */
int ib_cm_listen(struct ib_cm_id *cm_id,
		 u64 service_id);

struct ib_cm_req_param {
	struct ib_qp		*qp;
	struct ib_path_record	*primary_path;
	struct ib_path_record	*alternate_path;
	u64			service_id;
	int			timeout_ms;
	void			*private_data;
	u8			private_data_len;
	u8			responder_resources;
	u8			initiator_depth;
	u8			remote_cm_response_timeout;
	u8			flow_control;
	u8			local_cm_response_timeout;
	u8			retry_count;
	u8			rnr_retry_count;
	u8			max_cm_retries;
};

/**
  * ib_send_cm_req - Sends a connection request to the remote node.
  * @cm_id: Connection identifier that will be associated with the
  *   connection request.
  * @param: Connection request information needed to establish the
  *   connection.
  */
int ib_send_cm_req(struct ib_cm_id *cm_id,
		   struct ib_cm_req_param *param);

struct ib_cm_rep_param {
	struct ib_qp	*qp;
	void		*private_data;
	u8		reply_private_data_len;
	u8		responder_resources;
	u8		initiator_depth;
	u8		target_ack_delay;
	u8		failover_accepted;
	u8		flow_control;
	u8		rnr_retry_count;
};

/**
  * ib_send_cm_rep - Sends a connection reply in response to a connection
  *   request.
  * @cm_id: Connection identifier that will be associated with the
  *   connection request.
  * @param: Connection reply information needed to establish the
  *   connection.
  */
int ib_send_cm_rep(struct ib_cm_id *cm_id,
		   struct ib_cm_req_param *param);

/**
  * ib_send_cm_rtu - Sends a connection ready to use message in response
  *   to a connection reply message.
  * @cm_id: Connection identifier associated with the connection request.
  * @private_data: Optional user-defined private data sent with the
  *   ready to use message.
  * @private_data_len: Size of the private data buffer, in bytes.
  */
int ib_send_cm_rtu(struct ib_cm_id *cm_id,
		   void *private_data,
		   u8 private_data_len);

/**
  * ib_send_cm_dreq - Sends a disconnection request for an existing
  *   connection.
  * @cm_id: Connection identifier associated with the connection being
  *   released.
  * @private_data: Optional user-defined private data sent with the
  *   disconnection request message.
  * @private_data_len: Size of the private data buffer, in bytes.
  */
int ib_send_cm_dreq(struct ib_cm_id *cm_id,
		    void *private_data,
		    u8 private_data_len);

/**
  * ib_send_cm_drep - Sends a disconnection reply to a disconnection 
request.
  * @cm_id: Connection identifier associated with the connection being
  *   released.
  * @private_data: Optional user-defined private data sent with the
  *   disconnection reply message.
  * @private_data_len: Size of the private data buffer, in bytes.
  */
int ib_send_cm_drep(struct ib_cm_id *cm_id,
		    void *private_data,
		    u8 private_data_len);

/**
  * ib_cm_establish - Forces a connection state to established.
  * @cm_id: Connection identifier to transition to established.
  *
  * This routine should be invoked by users who receive messages on a
  * connected QP before an RTU has been received.
  */
int ib_cm_establish(struct ib_cm_id *id);
//*** TBD: should we allow a user for force any cm_id to established?

enum ib_cm_rej_reason {
	IB_CM_REJ_NO_QP				= __constant_htons(1)
	IB_CM_REJ_NO_EEC			= __constant_htons(2)
	IB_CM_REJ_NO_RESOURCES			= __constant_htons(3)
	IB_CM_REJ_TIMEOUT			= __constant_htons(4)
	IB_CM_REJ_UNSUPPORTED			= __constant_htons(5)
	IB_CM_REJ_INVALID_COMM_ID		= __constant_htons(6)
	IB_CM_REJ_INVALID_COMM_INSTANCE		= __constant_htons(7)
	IB_CM_REJ_INVALID_SERVICE_ID		= __constant_htons(8)
	IB_CM_REJ_INVALID_TRANSPORT_TYPE	= __constant_htons(9)
	IB_CM_REJ_STALE_CONN			= __constant_htons(10)
	IB_CM_REJ_RDC_NOT_EXIST			= __constant_htons(11)
	IB_CM_REJ_INVALID_GID			= __constant_htons(12)
	IB_CM_REJ_INVALID_LID			= __constant_htons(13)
	IB_CM_REJ_INVALID_SL			= __constant_htons(14)
	IB_CM_REJ_INVALID_TRAFFIC_CLASS		= __constant_htons(15)
	IB_CM_REJ_INVALID_HOP_LIMIT		= __constant_htons(16)
	IB_CM_REJ_INVALID_PACKET_RATE		= __constant_htons(17)
	IB_CM_REJ_INVALID_ALT_GID		= __constant_htons(18)
	IB_CM_REJ_INVALID_ALT_LID		= __constant_htons(19)
	IB_CM_REJ_INVALID_ALT_SL		= __constant_htons(20)
	IB_CM_REJ_INVALID_ALT_TRAFFIC_CLASS	= __constant_htons(21)
	IB_CM_REJ_INVALID_ALT_HOP_LIMIT		= __constant_htons(22)
	IB_CM_REJ_INVALID_ALT_PACKET_RATE	= __constant_htons(23)
	IB_CM_REJ_PORT_REDIRECT			= __constant_htons(24)
	IB_CM_REJ_INVALID_MTU			= __constant_htons(26)
	IB_CM_REJ_INSUFFICIENT_RESP_RESOURCES	= __constant_htons(27)
	IB_CM_REJ_CONSUMER_DEFINED		= __constant_htons(28)
	IB_CM_REJ_INVALID_RNR_RETRY		= __constant_htons(29)
	IB_CM_REJ_DUPLICATE_LOCAL_COMM_ID	= __constant_htons(30)
	IB_CM_REJ_INVALID_CLASS_VERSION		= __constant_htons(31)
	IB_CM_REJ_INVALID_FLOW_LABEL		= __constant_htons(32)
	IB_CM_REJ_INVALID_ALT_FLOW_LABEL	= __constant_htons(33)
};

/**
  * ib_send_cm_rej - Sends a connection rejection message to the
  *   remote node.
  * @cm_id: Connection identifier associated with the connection being
  *   rejected.
  * @reason: Reason for the connection request rejection.
  * @ari: Optional additional rejection information.
  * @ari_length: Size of the additional rejection information, in bytes.
  * @private_data: Optional user-defined private data sent with the
  *   rejection message.
  * @private_data_len: Size of the private data buffer, in bytes.
  */
int ib_send_cm_rej(struct ib_cm_id *cm_id,
		   enum ib_cm_rej_reason reason,
		   void *ari,
		   u8 ari_length,
		   void *private_data,
		   u8 private_data_len);

/**
  * ib_send_cm_mra - Sends a message receipt acknowledgement to a 
connection
  *   message.
  * @cm_id: Connection identifier associated with the connection message.
  * @service_timeout: The maximum time required for the sender to reply to
  *   to the connection message.
  * @private_data: Optional user-defined private data sent with the
  *   message receipt acknowledgement.
  * @private_data_len: Size of the private data buffer, in bytes.
  */
int ib_send_cm_mra(struct ib_cm_id *cm_id,
		   u8 service_timeout,
		   void *private_data,
		   u8 private_data_len);

/**
  * ib_send_cm_lap - Sends a load alternate path request.
  * @cm_id: Connection identifier associated with the load alternate path
  *   message.
  * @alternate_path: A path record that identifies the alternate path to
  *   load.
  * @private_data: Optional user-defined private data sent with the
  *   load alternate path message.
  * @private_data_len: Size of the private data buffer, in bytes.
  */
int ib_send_cm_lap(struct ib_cm_id *cm_id,
		   struct ib_path_record *alternate_path,
		   void *private_data,
		   u8 private_data_len);
//*** TBD: should LAP/APR set the QP's alternate path information...

enum ib_cm_apr_status {
	IB_CM_APR_SUCCESS
	IB_CM_APR_INVALID_COMM_ID
	IB_CM_APR_UNSUPPORTED
	IB_CM_APR_REJECT
	IB_CM_APR_REDIRECT
	IB_CM_APR_IS_CURRENT
	IB_CM_APR_INVALID_QPN_EECN
	IB_CM_APR_INVALID_LID
	IB_CM_APR_INVALID_GID
	IB_CM_APR_INVALID_FLOW_LABEL
	IB_CM_APR_INVALID_TCLASS
	IB_CM_APR_INVALID_HOP_LIMIT
	IB_CM_APR_INVALID_PACKET_RATE
	IB_CM_APR_INVALID_SL
};

/**
  * ib_send_cm_apr - Sends an alternate path response message in 
response to
  *   a load alternate path request.
  * @cm_id: Connection identifier associated with the alternate path 
response.
  * @status: Reply status sent with the alternate path response.
  * @info: Optional additional information sent with the alternate path
  *   response.
  * @info_length: Size of the additional information, in bytes.
  * @private_data: Optional user-defined private data sent with the
  *   alternate path response message.
  * @private_data_len: Size of the private data buffer, in bytes.
  */
int ib_send_cm_apr(struct ib_cm_id *cm_id,
		   enum ib_cm_apr_status status,
		   void *info,
		   u8 info_length,
		   void *private_data,
		   u8 private_data_len);

/**
  * ib_cm_migrate_path - Forces a connected QP to use the loaded alternate
  *   path.
  * @cm_id: Connection identifier associated with the alternate path 
response.
  */
//int ib_cm_migrate_path(struct ib_cm_id *cm_id);
//*** TBD: should this be part of CM, since it only modifies the QP state?

struct ib_cm_sidr_req_param {
	struct ib_path_record	*path;
	u64			service_id;
	int			timeout_ms;
	void			*private_data;
	u8			private_data_len;
	u16			pkey;
};

/**
  * ib_send_cm_sidr_req - Sends a service ID resolution request to the
  *   remote node.
  * @cm_id: Communication identifier that will be associated with the
  *   service ID resolution request.
  * @param: Service ID resolution request information.
  */
int ib_send_cm_sidr_req(struct ib_cm_id *cm_id,
			struct ib_cm_sidr_req_param *param);

enum ib_cm_sidr_status {
	IB_SIDR_SUCCESS,
	IB_SIDR_UNSUPPORTED,
	IB_SIDR_REJECT,
	IB_SIDR_NO_QP,
	IB_SIDR_REDIRECT,
	IB_SIDR_UNSUPPORTED_VERSION
};

struct ib_cm_sidr_rep_param {
	u32			qp_num;
	u32			qkey;
	enum ib_cm_sidr_status	status;
	void			*info;
	u8			info_length;
	void			*private_data;
	u8			private_data_len;
};

/**
  * ib_send_cm_sidr_rep - Sends a service ID resolution request to the
  *   remote node.
  * @cm_id: Communication identifier associated with the received 
service ID
  *   resolution request.
  * @param: Service ID resolution reply information.
  */
int ib_send_cm_sidr_rep(struct ib_cm_id *cm_id,
			struct ib_cm_sidr_rep_param *param);

#endif /* IB_CM_H */




More information about the general mailing list