FreeBSD Manual Pages
RDMA_GET_CM_EVENT(3) Librdmacm Programmer's Manual RDMA_GET_CM_EVENT(3) NAME rdma_get_cm_event - Retrieves the next pending communication event. SYNOPSIS #include <rdma/rdma_cma.h> int rdma_get_cm_event (struct rdma_event_channel *channel, struct rdma_cm_event **event); ARGUMENTS channel Event channel to check for events. event Allocated information about the next communication event. DESCRIPTION Retrieves a communication event. If no events are pending, by default, the call will block until an event is received. RETURN VALUE Returns 0 on success, or -1 on error. If an error occurs, errno will be set to indicate the failure reason. NOTES The default synchronous behavior of this routine can be changed by mod- ifying the file descriptor associated with the given channel. All events that are reported must be acknowledged by calling rdma_ack_cm_event. Destruction of an rdma_cm_id will block until re- lated events have been acknowledged. EVENT DATA Communication event details are returned in the rdma_cm_event struc- ture. This structure is allocated by the rdma_cm and released by the rdma_ack_cm_event routine. Details of the rdma_cm_event structure are given below. id The rdma_cm identifier associated with the event. If the event type is RDMA_CM_EVENT_CONNECT_REQUEST, then this ref- erences a new id for that communication. listen_id For RDMA_CM_EVENT_CONNECT_REQUEST event types, this refer- ences the corresponding listening request identifier. event Specifies the type of communication event which occurred. See EVENT TYPES below. status Returns any asynchronous error information associated with an event. The status is zero if the operation was success- ful, otherwise the status value is non-zero and is either set to an errno or a transport specific value. For details on transport specific status values, see the event type in- formation below. param Provides additional details based on the type of event. Users should select the conn or ud subfields based on the rdma_port_space of the rdma_cm_id associated with the event. See UD EVENT DATA and CONN EVENT DATA below. UD EVENT DATA Event parameters related to unreliable datagram (UD) services: RDMA_PS_UDP and RDMA_PS_IPOIB. The UD event data is valid for RDMA_CM_EVENT_ESTABLISHED and RDMA_CM_EVENT_MULTICAST_JOIN events, un- less stated otherwise. private_data References any user-specified data associated with RDMA_CM_EVENT_CONNECT_REQUEST or RDMA_CM_EVENT_ESTABLISHED events. The data referenced by this field matches that specified by the remote side when calling rdma_connect or rdma_accept. This field is NULL if the event does not in- clude private data. The buffer referenced by this pointer is deallocated when calling rdma_ack_cm_event. private_data_len The size of the private data buffer. Users should note that the size of the private data buffer may be larger than the amount of private data sent by the remote side. Any additional space in the buffer will be zeroed out. ah_attr Address information needed to send data to the remote end- point(s). Users should use this structure when allocating their address handle. qp_num QP number of the remote endpoint or multicast group. qkey QKey needed to send data to the remote endpoint(s). CONN EVENT DATA Event parameters related to connected QP services: RDMA_PS_TCP. The connection related event data is valid for RDMA_CM_EVENT_CONNECT_RE- QUEST and RDMA_CM_EVENT_ESTABLISHED events, unless stated otherwise. private_data References any user-specified data associated with the event. The data referenced by this field matches that specified by the remote side when calling rdma_connect or rdma_accept. This field is NULL if the event does not in- clude private data. The buffer referenced by this pointer is deallocated when calling rdma_ack_cm_event. private_data_len The size of the private data buffer. Users should note that the size of the private data buffer may be larger than the amount of private data sent by the remote side. Any additional space in the buffer will be zeroed out. responder_resources The number of responder resources requested of the recipi- ent. This field matches the initiator depth specified by the remote node when calling rdma_connect and rdma_accept. initiator_depth The maximum number of outstanding RDMA read/atomic opera- tions that the recipient may have outstanding. This field matches the responder resources specified by the remote node when calling rdma_connect and rdma_accept. flow_control Indicates if hardware level flow control is provided by the sender. retry_count For RDMA_CM_EVENT_CONNECT_REQUEST events only, indicates the number of times that the recipient should retry send operations. rnr_retry_count The number of times that the recipient should retry re- ceiver not ready (RNR) NACK errors. srq Specifies if the sender is using a shared-receive queue. qp_num Indicates the remote QP number for the connection. EVENT TYPES The following types of communication events may be reported. RDMA_CM_EVENT_ADDR_RESOLVED Address resolution (rdma_resolve_addr) completed successfully. RDMA_CM_EVENT_ADDR_ERROR Address resolution (rdma_resolve_addr) failed. RDMA_CM_EVENT_ROUTE_RESOLVED Route resolution (rdma_resolve_route) completed successfully. RDMA_CM_EVENT_ROUTE_ERROR Route resolution (rdma_resolve_route) failed. RDMA_CM_EVENT_CONNECT_REQUEST Generated on the passive side to notify the user of a new con- nection request. RDMA_CM_EVENT_CONNECT_RESPONSE Generated on the active side to notify the user of a successful response to a connection request. It is only generated on rdma_cm_id's that do not have a QP associated with them. RDMA_CM_EVENT_CONNECT_ERROR Indicates that an error has occurred trying to establish or a connection. May be generated on the active or passive side of a connection. RDMA_CM_EVENT_UNREACHABLE Generated on the active side to notify the user that the remote server is not reachable or unable to respond to a connection re- quest. If this event is generated in response to a UD QP reso- lution request over InfiniBand, the event status field will con- tain an errno, if negative, or the status result carried in the IB CM SIDR REP message. RDMA_CM_EVENT_REJECTED Indicates that a connection request or response was rejected by the remote end point. The event status field will contain the transport specific reject reason if available. Under Infini- Band, this is the reject reason carried in the IB CM REJ mes- sage. RDMA_CM_EVENT_ESTABLISHED Indicates that a connection has been established with the remote end point. RDMA_CM_EVENT_DISCONNECTED The connection has been disconnected. RDMA_CM_EVENT_DEVICE_REMOVAL The local RDMA device associated with the rdma_cm_id has been removed. Upon receiving this event, the user must destroy the related rdma_cm_id. RDMA_CM_EVENT_MULTICAST_JOIN The multicast join operation (rdma_join_multicast) completed successfully. RDMA_CM_EVENT_MULTICAST_ERROR An error either occurred joining a multicast group, or, if the group had already been joined, on an existing group. The speci- fied multicast group is no longer accessible and should be re- joined, if desired. RDMA_CM_EVENT_ADDR_CHANGE The network device associated with this ID through address reso- lution changed its HW address, eg following of bonding failover. This event can serve as a hint for applications who want the links used for their RDMA sessions to align with the network stack. RDMA_CM_EVENT_TIMEWAIT_EXIT The QP associated with a connection has exited its timewait state and is now ready to be re-used. After a QP has been dis- connected, it is maintained in a timewait state to allow any in flight packets to exit the network. After the timewait state has completed, the rdma_cm will report this event. SEE ALSO rdma_ack_cm_event(3), rdma_create_event_channel(3), rdma_re- solve_addr(3), rdma_resolve_route(3), rdma_connect(3), rdma_listen(3), rdma_join_multicast(3), rdma_destroy_id(3), rdma_event_str(3) librdmacm 2007-10-31 RDMA_GET_CM_EVENT(3)
NAME | SYNOPSIS | ARGUMENTS | DESCRIPTION | RETURN VALUE | NOTES | EVENT DATA | UD EVENT DATA | CONN EVENT DATA | EVENT TYPES | SEE ALSO
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=rdma_get_cm_event&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>