librdmacminclude_HEADERS = include/rdma/rdma_cma_abi.h \
include/rdma/rdma_cma.h
+man_MANS = \
+ man/rdma_accept.3 \
+ man/rdma_ack_cm_event.3 \
+ man/rdma_bind_addr.3 \
+ man/rdma_connect.3 \
+ man/rdma_create_event_channel.3 \
+ man/rdma_create_id.3 \
+ man/rdma_create_qp.3 \
+ man/rdma_destroy_event_channel.3 \
+ man/rdma_destroy_id.3 \
+ man/rdma_destroy_qp.3 \
+ man/rdma_disconnect.3 \
+ man/rdma_free_devices.3 \
+ man/rdma_get_cm_event.3 \
+ man/rdma_get_devices.3 \
+ man/rdma_get_src_port.3 \
+ man/rdma_get_dst_port.3 \
+ man/rdma_join_multicast.3 \
+ man/rdma_leave_multicast.3 \
+ man/rdma_listen.3 \
+ man/rdma_notify.3 \
+ man/rdma_reject.3 \
+ man/rdma_resolve_addr.3 \
+ man/rdma_resolve_route.3 \
+ man/ucmatose.1 \
+ man/udaddy.1 \
+ man/mckey.1 \
+ man/rping.1 \
+ man/rdma_cm.7
+
EXTRA_DIST = include/rdma/rdma_cma_abi.h include/rdma/rdma_cma.h \
- src/librdmacm.map librdmacm.spec.in
+ src/librdmacm.map librdmacm.spec.in $(man_MANS)
dist-hook: librdmacm.spec
cp librdmacm.spec $(distdir)
%{_libdir}/lib*.so
%{_libdir}/*.a
%{_includedir}/*
+%{_mandir}/man3/*
%files utils
%defattr(-,root,root,-)
--- /dev/null
+.TH "mckey" 1 "mckey" "May 2007" "librdmacm" librdmacm
+.SH NAME
+mckey \- RDMA CM multicast setup and simple data transfer test.
+.SH SYNOPSIS
+.sp
+.nf
+\fImckey\fR -m multicast_address [-s] [-b bind_address] [-c connections]
+ [-C message_count] [-S message_size] [-p port_space]
+\fImckey\fR -m multicast_address -s [-b bind_address] [-c connections]
+ [-C message_count] [-S message_size] [-p port_space]
+\fImckey\fR -M unmapped_multicast_address -b bind_address [-s] [-c connections]
+ [-C message_count] [-S message_size] [-p port_space]
+.fi
+.SH "DESCRIPTION"
+Establishes a set of RDMA multicast communication paths between nodes
+using the librdmacm, optionally transfers datagrams to receiving nodes,
+then tears down the communication.
+.SH "OPTIONS"
+.TP
+\-m multicast_address
+IP multicast address to join.
+.TP
+\-M unmapped_multicast_address
+RDMA transport specific multicast address to join.
+.TP
+\-s
+Send datagrams to the multicast group.
+.TP
+\-b bind_address
+The local network address to bind to.
+.TP
+\-c connections
+The number of QPs to join the multicast group. (default 1)
+.TP
+\-C message_count
+The number of messages to transfer over each connection. (default 10)
+.TP
+\-S message_size
+The size of each message transferred, in bytes. This value must be smaller
+than the MTU of the underlying RDMA transport, or an error will occur.
+(default 100)
+.TP
+\-p port_space
+The port space of the datagram communication. May be either the RDMA
+UDP (0x0111) or IPoIB (0x0002) port space. (default RDMA_PS_UDP)
+.SH "NOTES"
+Basic usage is to start mckey -m multicast_address on a server system,
+then run mckey -m multicast_address -s on a client system.
+.P
+Because this test maps RDMA resources to userspace, users must ensure
+that they have available system resources and permissions. See the
+libibverbs README file for additional details.
+.SH "SEE ALSO"
+rdma_cm, ucmatose, udaddy, rping
--- /dev/null
+.TH "rdma_accept" 3 "rdma_accept" "May 2007" "Librdmacm Programmer's Manual" librdmacm
+.SH NAME
+rdma_accept \- Called to accept a connection request.
+.SH SYNOPSIS
+.B "#include <rdma/rdma_cma.h>"
+.P
+.B "int" rdma_accept
+.BI "(struct rdma_cm_id *" id ","
+.BI "struct rdma_conn_param *" conn_param ");"
+.SH ARGUMENTS
+.IP "id" 12
+Connection identifier associated with the request.
+.IP "conn_param" 12
+Information needed to establish the connection.
+.SH "DESCRIPTION"
+Called from the listening side to accept a connection or datagram
+service lookup request.
+.SH "NOTES"
+Unlike the socket accept routine, rdma_accept is not called on a
+listening rdma_cm_id. Instead, after calling rdma_listen, the user
+waits for an RDMA_CM_EVENT_CONNECT_REQUEST event to occur. Connection request
+events give the user a newly created rdma_cm_id, similar to a new
+socket, but the rdma_cm_id is bound to a specific RDMA device.
+rdma_accept is called on the new rdma_cm_id.
+.SH "CONNECTION PROPERTIES"
+The following properties are used to configure the communication and specified
+by the conn_param parameter when accepting a connection or datagram
+communication request. Users should use the conn_param values reported in
+the connection request event to determine appropriate values for these fields
+when accepting.
+.IP private_data
+References a user-controlled data buffer. The contents of the buffer are
+transparently passed to the remote side as part of the communication request.
+May be NULL if private_data is not required.
+.IP private_data_len
+Specifies the size of the user-controlled data buffer.
+.IP responder_resources
+The maximum number of outstanding RDMA read and atomic operations that the
+local side will accept from the remote side. Applies only to RDMA_PS_TCP.
+.IP initiator_depth
+The maximum number of outstanding RDMA read and atomic operations that the
+local side will have to the remote side. Applies only to RDMA_PS_TCP.
+.IP flow_control
+Specifies if hardware flow control should be used. Applies only to RDMA_PS_TCP.
+.IP retry_count
+The maximum number of times that a data transfer operation should be retried
+on the connection when an error occurs. This setting controls the number of
+times to retry send, RDMA, and atomic operations when timeouts occur.
+Applies only to RDMA_PS_TCP.
+.IP rnr_retry_count
+The maximum number of times that a send operation should be retried on a
+connection after receiving a receiver not ready (RNR) error. RNR errors are
+generated when a send request arrives before a buffer has been posted to
+receive the incoming data. Applies only to RDMA_PS_TCP.
+.IP srq
+Specifies if the QP associated with the connection is using a shared receive
+queue. This field is ignored by the library if a QP has been created on the
+rdma_cm_id. Applies only to RDMA_PS_TCP.
+.IP qp_num
+Specifies the QP number associated with the connection. This field is ignored
+by the library if a QP has been created on the rdma_cm_id.
+.SH "SEE ALSO"
+rdma_listen, rdma_reject, rdma_get_cm_event
--- /dev/null
+.TH "rdma_ack_cm_event" 3 "rdma_ack_cm_event" "May 2007" "Librdmacm Programmer's Manual" librdmacm
+.SH NAME
+rdma_ack_cm_event \- Free a communication event.
+.SH SYNOPSIS
+.B "#include <rdma/rdma_cma.h>"
+.P
+.B "int" rdma_ack_cm_event
+.BI "(struct rdma_cm_event *" event ");"
+.SH ARGUMENTS
+.IP "event" 12
+Event to be released.
+.SH "DESCRIPTION"
+All events which are allocated by rdma_get_cm_event must be released,
+there should be a one-to-one correspondence between successful gets
+and acks.
+.SH "SEE ALSO"
+rdma_get_cm_event, rdma_destroy_id
--- /dev/null
+.TH "rdma_bind_addr" 3 "rdma_bind_addr" "May 2007" "Librdmacm Programmer's Manual" librdmacm
+.SH NAME
+rdma_bind_addr \- Bind an RDMA identifier to a source address.
+.SH SYNOPSIS
+.B "#include <rdma/rdma_cma.h>"
+.P
+.B "int" rdma_bind_addr
+.BI "(struct rdma_cm_id *" id ","
+.BI "struct sockaddr *" addr ");"
+.SH ARGUMENTS
+.IP "id" 12
+RDMA identifier.
+.IP "addr" 12
+Local address information. Wildcard values are permitted.
+.SH "DESCRIPTION"
+Associates a source address with an rdma_cm_id. The address may be
+wildcarded. If binding to a specific local address, the rdma_cm_id
+will also be bound to a local RDMA device.
+.SH "NOTES"
+Typically, this routine is called before calling rdma_listen to bind
+to a specific port number, but it may also be called on the active side
+of a connection before calling rdma_resolve_addr to bind to a specific
+address.
+.P
+If used to bind to port 0, the rdma_cm will select an available port
+and return it to the user.
+.SH "SEE ALSO"
+rdma_create_id, rdma_listen, rdma_resolve_addr, rdma_create_qp
--- /dev/null
+.TH "rdma_cm" 7 "rdma_cm" "May 2007" "Librdmacm Programmer's Manual" librdmacm
+.SH NAME
+rdma_cm \- RDMA communication manager.
+.SH SYNOPSIS
+.B "#include <rdma/rdma_cma.h>"
+.SH "DESCRIPTION"
+Used to establish communication over RDMA transports.
+.SH "NOTES"
+The RDMA CM is a communication manager used to setup reliable, connected
+and unreliable datagram data transfers. It provides an RDMA transport
+neutral interface for establishing connections. The API is based on sockets,
+but adapted for queue pair (QP) based semantics: communication must be
+over a specific RDMA device, and data transfers are message based.
+.P
+The RDMA CM only provides the communication management (connection setup /
+teardown) portion of an RDMA API. It works in conjunction with the verbs
+API defined by the libibverbs library. The libibverbs library provides the
+interfaces needed to send and receive data.
+.SH "CLIENT OPERATION"
+This section provides a general overview of the basic operation for the active,
+or client, side of communication. A general connection flow would be:
+.IP rdma_create_event_channel
+create channel to receive events
+.IP rdma_create_id
+allocate an rdma_cm_id, this is conceptually similar to a socket
+.IP rdma_resolve_addr
+obtain a local RDMA device to reach the remote address
+.IP rdma_get_cm_event
+wait for RDMA_CM_EVENT_ADDR_RESOLVED event
+.IP rdma_ack_cm_event
+ack event
+.IP rdma_create_qp
+allocate a QP for the communication
+.IP rdma_resolve_route
+determine the route to the remote address
+.IP rdma_get_cm_event
+wait for RDMA_CM_EVENT_ROUTE_RESOLVED event
+.IP rdma_ack_cm_event
+ack event
+.IP rdma_connect
+connect to the remote server
+.IP rdma_get_cm_event
+wait for RDMA_CM_EVENT_ESTABLISHED event
+.IP rdma_ack_cm_event
+ack event
+.P
+Perform data transfers over connection
+.IP rdma_disconnect
+tear-down connection
+.IP rdma_get_cm_event
+wait for RDMA_CM_EVENT_DISCONNECTED event
+.IP rdma_ack_cm_event
+ack event
+.IP rdma_destroy_qp
+destroy the QP
+.IP rdma_destroy_id
+release the rdma_cm_id
+.IP rdma_destroy_event_channel
+release the event channel
+.P
+An almost identical process is used to setup unreliable datagram (UD)
+communication between nodes. No actual connection is formed between QPs
+however, so disconnection is not needed.
+.P
+Although this example shows the client initiating the disconnect, either side
+of a connection may initiate the disconnect.
+.SH "SERVER OPERATION"
+This section provides a general overview of the basic operation for the passive,
+or server, side of communication. A general connection flow would be:
+.IP rdma_create_event_channel
+create channel to receive events
+.IP rdma_create_id
+allocate an rdma_cm_id, this is conceptually similar to a socket
+.IP rdma_bind_addr
+set the local port number to listen on
+.IP rdma_listen
+begin listening for connection requests
+.IP rdma_get_cm_event
+wait for RDMA_CM_EVENT_CONNECT_REQUEST event with a new rdma_cm_id
+.IP rdma_create_qp
+allocate a QP for the communication on the new rdma_cm_id
+.IP rdma_accept
+accept the connection request
+.IP rdma_ack_cm_event
+ack event
+.IP rdma_get_cm_event
+wait for RDMA_CM_EVENT_ESTABLISHED event
+.IP rdma_ack_cm_event
+ack event
+.P
+Perform data transfers over connection
+.IP rdma_get_cm_event
+wait for RDMA_CM_EVENT_DISCONNECTED event
+.IP rdma_ack_cm_event
+ack event
+.IP rdma_disconnect
+tear-down connection
+.IP rdma_destroy_qp
+destroy the QP
+.IP rdma_destroy_id
+release the connected rdma_cm_id
+.IP rdma_destroy_id
+release the listening rdma_cm_id
+.IP rdma_destroy_event_channel
+release the event channel
+.SH "SEE ALSO"
+rdma_create_event_channel, rdma_get_cm_event, rdma_create_id,
+rdma_resolve_addr, rdma_bind_addr, rdma_create_qp,
+rdma_resolve_route, rdma_connect, rdma_listen, rdma_accept, rdma_reject,
+rdma_join_multicast, rdma_leave_multicast, rdma_notify,
+rdma_ack_cm_event, rdma_disconnect, rdma_destroy_qp, rdma_destroy_id,
+rdma_destroy_event_channel, rdma_get_devices, rdma_free_devices,
+ucmatose, udaddy, mckey, rping
--- /dev/null
+.TH "rdma_connect" 3 "rdma_connect" "May 2007" "Librdmacm Programmer's Manual" librdmacm
+.SH NAME
+rdma_connect \- Initiate an active connection request.
+.SH SYNOPSIS
+.B "#include <rdma/rdma_cma.h>"
+.P
+.B "int" rdma_connect
+.BI "(struct rdma_cm_id *" id ","
+.BI "struct rdma_conn_param *" conn_param ");"
+.SH ARGUMENTS
+.IP "id" 12
+RDMA identifier.
+.IP "conn_param" 12
+connection parameters.
+.SH "DESCRIPTION"
+For an rdma_cm_id of type RDMA_PS_TCP, this call initiates a connection request
+to a remote destination. For an rdma_cm_id of type RDMA_PS_UDP, it initiates
+a lookup of the remote QP providing the datagram service.
+.SH "NOTES"
+Users must have resolved a route to the destination address
+by having called rdma_resolve_route before calling this routine.
+.SH "CONNECTION PROPERTIES"
+The following properties are used to configure the communication and specified
+by the conn_param parameter when connecting or establishing datagram
+communication.
+.IP private_data
+References a user-controlled data buffer. The contents of the buffer are
+transparently passed to the remote side as part of the communication request.
+May be NULL if private_data is not required.
+.IP private_data_len
+Specifies the size of the user-controlled data buffer.
+.IP responder_resources
+The maximum number of outstanding RDMA read and atomic operations that the
+local side will accept from the remote side. Applies only to RDMA_PS_TCP.
+.IP initiator_depth
+The maximum number of outstanding RDMA read and atomic operations that the
+local side will have to the remote side. Applies only to RDMA_PS_TCP.
+.IP flow_control
+Specifies if hardware flow control should be used. Applies only to RDMA_PS_TCP.
+.IP retry_count
+The maximum number of times that a data transfer operation should be retried
+on the connection when an error occurs. This setting controls the number of
+times to retry send, RDMA, and atomic operations when timeouts occur.
+Applies only to RDMA_PS_TCP.
+.IP rnr_retry_count
+The maximum number of times that a send operation should be retried on a
+connection after receiving a receiver not ready (RNR) error. RNR errors are
+generated when a send request arrives before a buffer has been posted to
+receive the incoming data. Applies only to RDMA_PS_TCP.
+.IP srq
+Specifies if the QP associated with the connection is using a shared receive
+queue. This field is ignored by the library if a QP has been created on the
+rdma_cm_id. Applies only to RDMA_PS_TCP.
+.IP qp_num
+Specifies the QP number associated with the connection. This field is ignored
+by the library if a QP has been created on the rdma_cm_id. Applies only to
+RDMA_PS_TCP.
+.SH "SEE ALSO"
+rdma_cm, rdma_create_id, rdma_resolve_route, rdma_disconnect, rdma_listen,
+rdma_get_cm_event
--- /dev/null
+.TH "rdma_create_event_channel" 3 "rdma_create_event_channel" "May 2007" "Librdmacm Programmer's Manual" librdmacm
+.SH NAME
+rdma_create_event_channel \- Open a channel used to report communication events.
+.SH SYNOPSIS
+.B "#include <rdma/rdma_cma.h>"
+.P
+.B "struct rdma_event_channel *" rdma_create_event_channel
+.BI "(" void ");"
+.SH ARGUMENTS
+.IP "void" 12
+no arguments
+.SH "DESCRIPTION"
+Asynchronous events are reported to users through event channels.
+.SH "NOTES"
+Event channels are used to direct all events on an rdma_cm_id. For many
+clients, a single event channel may be sufficient, however, when managing
+a large number of connections or cm_id's, users may find it useful to direct
+events for different cm_id's to different channels for processing.
+.P
+All created event channels must be destroyed by calling
+rdma_destroy_event_channel. Users should call rdma_get_cm_event to
+retrieve events on an event channel.
+.P
+Each event channel is mapped to a file descriptor. The associated file
+descriptor can be used and manipulated like any other fd to change its
+behavior. Users may make the fd non-blocking, poll or select the fd, etc.
+.SH "SEE ALSO"
+rdma_cm, rdma_get_cm_event, rdma_destroy_event_channel
--- /dev/null
+.TH "rdma_create_id" 3 "rdma_create_id" "May 2007" "Librdmacm Programmer's Manual" librdmacm
+.SH NAME
+rdma_create_id \- Allocate a communication identifier.
+.SH SYNOPSIS
+.B "#include <rdma/rdma_cma.h>"
+.P
+.B "int" rdma_create_id
+.BI "(struct rdma_event_channel *" channel ","
+.BI "struct rdma_cm_id **" id ","
+.BI "void *" context ","
+.BI "enum rdma_port_space " ps ");"
+.SH ARGUMENTS
+.IP "channel" 12
+The communication channel that events associated with the
+allocated rdma_cm_id will be reported on.
+.IP "id" 12
+A reference where the allocated communication identifier will be
+returned.
+.IP "context" 12
+User specified context associated with the rdma_cm_id.
+.IP "ps" 12
+RDMA port space.
+.SH "DESCRIPTION"
+Creates an identifier that is used to track communication information.
+.SH "NOTES"
+Rdma_cm_id's are conceptually equivalent to a socket for RDMA
+communication. The difference is that RDMA communication requires
+explicitly binding to a specified RDMA device before communication
+can occur, and most operations are asynchronous in nature. Communication
+events on an rdma_cm_id are reported through the associated event
+channel. Users must release the rdma_cm_id by calling rdma_destroy_id.
+.SH "PORT SPACE"
+Details of the services provided by the different port spaces are outlined
+below.
+.IP RDMA_PS_TCP
+Provides reliable, connection-oriented QP communication. Unlike TCP, the RDMA
+port space provides message, not stream, based communication.
+.IP RDMA_PS_UDP
+Provides unreliable, connectionless QP communication. Supports both datagram
+and multicast communication.
+.SH "SEE ALSO"
+rdma_cm, rdma_create_event_channel, rdma_destroy_id, rdma_get_devices,
+rdma_bind_addr, rdma_resolve_addr, rdma_connect, rdma_listen,
--- /dev/null
+.TH "rdma_create_qp" 3 "rdma_create_qp" "May 2007" "Librdmacm Programmer's Manual" librdmacm
+.SH NAME
+rdma_create_qp \- Allocate a QP.
+.SH SYNOPSIS
+.B "#include <rdma/rdma_cma.h>"
+.P
+.B "int" rdma_create_qp
+.BI "(struct rdma_cm_id *" id ","
+.BI "struct ibv_pd *" pd ","
+.BI "struct ibv_qp_init_attr *" qp_init_attr ");"
+.SH ARGUMENTS
+.IP "id" 12
+RDMA identifier.
+.IP "pd" 12
+protection domain for the QP.
+.IP "qp_init_attr" 12
+initial QP attributes.
+.SH "DESCRIPTION"
+Allocate a QP associated with the specified rdma_cm_id and transition it
+for sending and receiving.
+.SH "NOTES"
+The rdma_cm_id must be bound to a local RDMA device before calling this
+function, and the protection domain must be for that same device.
+QPs allocated to an rdma_cm_id are automatically transitioned by the
+librdmacm through their states. After being allocated, the QP will be
+ready to handle posting of receives. If the QP is unconnected, it will
+be ready to post sends.
+.SH "SEE ALSO"
+rdma_bind_addr, rdma_resolve_addr, rdma_destroy_qp, ibv_create_qp,
+ibv_modify_qp
--- /dev/null
+.TH "rdma_destroy_event_channel" 3 "rdma_destroy_event_channel" "May 2007" "Librdmacm Programmer's Manual" librdmacm
+.SH NAME
+rdma_destroy_event_channel \- Close an event communication channel.
+.SH SYNOPSIS
+.B "#include <rdma/rdma_cma.h>"
+.P
+.B "void" rdma_destroy_event_channel
+.BI "(struct rdma_event_channel *" channel ");"
+.SH ARGUMENTS
+.IP "channel" 12
+The communication channel to destroy.
+.SH "DESCRIPTION"
+Release all resources associated with an event channel and closes the
+associated file descriptor.
+.SH "NOTES"
+All rdma_cm_id's associated with the event channel must be destroyed,
+and all returned events must be acked before calling this function.
+.SH "SEE ALSO"
+rdma_create_event_channel, rdma_get_cm_event, rdma_ack_cm_event
--- /dev/null
+.TH "rdma_destroy_id" 3 "rdma_destroy_id" "May 2007" "Librdmacm Programmer's Manual" librdmacm
+.SH NAME
+rdma_destroy_id \- Release a communication identifier.
+.SH SYNOPSIS
+.B "#include <rdma/rdma_cma.h>"
+.P
+.B "int" rdma_destroy_id
+.BI "(struct rdma_cm_id *" id ");"
+.SH ARGUMENTS
+.IP "id" 12
+The communication identifier to destroy.
+.SH "DESCRIPTION"
+Destroys the specified rdma_cm_id and cancels any outstanding
+asynchronous operation.
+.SH "NOTES"
+Users must free any associated QP with the rdma_cm_id before
+calling this routine and ack an related events.
+.SH "SEE ALSO"
+rdma_create_id, rdma_destroy_qp, rdma_ack_cm_event
--- /dev/null
+.TH "rdma_destroy_qp" 3 "rdma_destroy_qp" "May 2007" "Librdmacm Programmer's Manual" librdmacm
+.SH NAME
+rdma_destroy_qp \- Deallocate a QP.
+.SH SYNOPSIS
+.B "#include <rdma/rdma_cma.h>"
+.P
+.B "void" rdma_destroy_qp
+.BI "(struct rdma_cm_id *" id ");"
+.SH ARGUMENTS
+.IP "id" 12
+RDMA identifier.
+.SH "DESCRIPTION"
+Destroy a QP allocated on the rdma_cm_id.
+.SH "NOTES"
+Users must destroy any QP associated with an rdma_cm_id before
+destroying the ID.
+.SH "SEE ALSO"
+rdma_create_qp, rdma_destroy_id, ibv_destroy_qp
--- /dev/null
+.TH "rdma_disconnect" 3 "rdma_disconnect" "May 2007" "Librdmacm Programmer's Manual" librdmacm
+.SH NAME
+rdma_disconnect \- This function disconnects a connection.
+.SH SYNOPSIS
+.B "#include <rdma/rdma_cma.h>"
+.P
+.B "int" rdma_disconnect
+.BI "(struct rdma_cm_id *" id ");"
+.SH ARGUMENTS
+.IP "id" 12
+RDMA identifier.
+.SH "DESCRIPTION"
+Disconnects a connection and transitions any associated QP to the error state.
+This routing may be called by both the client and server side of a connection.
+.SH "SEE ALSO"
+rdma_connect, rdma_listen, rdma_accept
--- /dev/null
+.TH "rdma_free_devices" 3 "rdma_free_devices" "May 2007" "Librdmacm Programmer's Manual" librdmacm
+.SH NAME
+rdma_free_devices \- Frees the list of devices returned by rdma_get_devices.
+.SH SYNOPSIS
+.B "#include <rdma/rdma_cma.h>"
+.P
+.B "void" rdma_free_devices
+.BI "(struct ibv_context **" list ");"
+.SH ARGUMENTS
+.IP "list" 12
+List of devices returned from rdma_get_devices.
+.SH "DESCRIPTION"
+Frees the device array returned by rdma_get_devices.
+.SH "SEE ALSO"
+rdma_get_devices
--- /dev/null
+.TH "rdma_get_cm_event" 3 "rdma_get_cm_event" "May 2007" "Librdmacm Programmer's Manual" librdmacm
+.SH NAME
+rdma_get_cm_event \- Retrieves the next pending communication event.
+.SH SYNOPSIS
+.B "#include <rdma/rdma_cma.h>"
+.P
+.B "int" rdma_get_cm_event
+.BI "(struct rdma_event_channel *" channel ","
+.BI "struct rdma_cm_event **" event ");"
+.SH ARGUMENTS
+.IP "channel" 12
+Event channel to check for events.
+.IP "event" 12
+Allocated information about the next communication event.
+.SH "DESCRIPTION"
+Retrieves a communication event. If no events are pending, by default,
+the call will block until an event is received.
+.SH "NOTES"
+The default synchronous behavior of this routine can be changed by
+modifying 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 related events have been
+acknowledged.
+.SH "EVENTS"
+The following types of communication events may be reported.
+.IP RDMA_CM_EVENT_ADDR_RESOLVED
+Address resolution (rdma_resolve_addr) completed successfully.
+.IP RDMA_CM_EVENT_ADDR_ERROR
+Address resolution (rdma_resolve_addr) failed.
+.IP RDMA_CM_EVENT_ROUTE_RESOLVED
+Route resolution (rdma_resolve_route) completed successfully.
+.IP RDMA_CM_EVENT_ROUTE_ERROR
+Route resolution (rdma_resolve_route) failed.
+.IP RDMA_CM_EVENT_CONNECT_REQUEST
+Generated on the passive side to notify the user of a new connection request.
+.IP 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.
+.IP 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.
+.IP 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 request.
+.IP RDMA_CM_EVENT_REJECTED
+Indicates that a connection request or response was rejected by the remote
+end point.
+.IP RDMA_CM_EVENT_ESTABLISHED
+Indicates that a connection has been established with the remote end point.
+.IP RDMA_CM_EVENT_DISCONNECTED
+The connection has been disconnected.
+.IP 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.
+.IP RDMA_CM_EVENT_MULTICAST_JOIN
+The multicast join operation (rdma_join_multicast) completed successfully.
+.IP 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 specified multicast group is
+no longer accessible and should be rejoined, if desired.
+.SH "SEE ALSO"
+rdma_ack_cm_event, rdma_create_event_channel, rdma_resolve_addr,
+rdma_resolve_route, rdma_connect, rdma_listen, rdma_join_multicast,
+rdma_destroy_id
--- /dev/null
+.TH "rdma_get_devices" 3 "rdma_get_devices" "May 2007" "Librdmacm Programmer's Manual" librdmacm
+.SH NAME
+rdma_get_devices \- Get a list of RDMA devices currently available.
+.SH SYNOPSIS
+.B "#include <rdma/rdma_cma.h>"
+.P
+.B "struct ibv_context **" rdma_get_devices
+.BI "(int *" num_devices ");"
+.SH ARGUMENTS
+.IP "num_devices" 12
+If non-NULL, set to the number of devices returned.
+.SH "DESCRIPTION"
+Return a NULL-terminated array of opened RDMA devices. Callers can use
+this routine to allocate resources on specific RDMA devices that will be
+shared across multiple rdma_cm_id's.
+.SH "NOTES"
+The returned array must be released by calling rdma_free_devices. Devices
+remain opened while the librdmacm is loaded.
+.SH "SEE ALSO"
+rdma_free_devices
--- /dev/null
+.TH "rdma_get_dst_port" 3 "rdma_get_dst_port" "May 2007" "Librdmacm Programmer's Manual" librdmacm
+.SH NAME
+rdma_get_dst_port \- Returns the remote port number of a bound rdma_cm_id.
+.SH SYNOPSIS
+.B "#include <rdma/rdma_cma.h>"
+.P
+.B "uint16_t" rdma_get_dst_port
+.BI "(struct rdma_cm_id *" id ");"
+.SH ARGUMENTS
+.IP "id" 12
+RDMA identifier.
+.SH "DESCRIPTION"
+Returns the remote port number for an rdma_cm_id that has been bound to
+a remote address.
+.SH "SEE ALSO"
+rdma_connect, rdma_accept, rdma_get_cm_event
--- /dev/null
+.TH "rdma_get_src_port" 3 "rdma_get_src_port" "May 2007" "Librdmacm Programmer's Manual" librdmacm
+.SH NAME
+rdma_get_src_port \- Returns the local port number of a bound rdma_cm_id.
+.SH SYNOPSIS
+.B "#include <rdma/rdma_cma.h>"
+.P
+.B "uint16_t" rdma_get_src_port
+.BI "(struct rdma_cm_id *" id ");"
+.SH ARGUMENTS
+.IP "id" 12
+RDMA identifier.
+.SH "DESCRIPTION"
+Returns the local port number for an rdma_cm_id that has been bound to
+a local address.
+.SH "SEE ALSO"
+rdma_bind_addr, rdma_resolve_addr
--- /dev/null
+.TH "rdma_join_multicast" 3 "rdma_join_multicast" "May 2007" "Librdmacm Programmer's Manual" librdmacm
+.SH NAME
+rdma_join_multicast \- Joins a multicast group.
+.SH SYNOPSIS
+.B "#include <rdma/rdma_cma.h>"
+.P
+.B "int" rdma_join_multicast
+.BI "(struct rdma_cm_id *" id ","
+.BI "struct sockaddr *" addr ","
+.BI "void *" context ");"
+.SH ARGUMENTS
+.IP "id" 12
+Communication identifier associated with the request.
+.IP "addr" 12
+Multicast address identifying the group to join.
+.IP "context" 12
+User-defined context associated with the join request.
+.SH "DESCRIPTION"
+Joins a multicast group and attaches an associated QP to the group.
+.SH "NOTES"
+Before joining a multicast group, the rdma_cm_id must be bound to
+an RDMA device by calling rdma_bind_addr or rdma_resolve_addr. Use of
+rdma_resolve_addr requires the local routing tables to resolve the
+multicast address to an RDMA device. The user must call
+rdma_leave_multicast to leave the multicast group and release any
+multicast resources. The context is returned to the user through
+the private_data field in the rdma_cm_event.
+.SH "SEE ALSO"
+rdma_leave_multicast, rdma_bind_addr, rdma_resolve_addr, rdma_create_qp
--- /dev/null
+.TH "rdma_leave_multicast" 3 "rdma_leave_multicast" "May 2007" "Librdmacm Programmer's Manual" librdmacm
+.SH NAME
+rdma_leave_multicast \- Leaves a multicast group.
+.SH SYNOPSIS
+.B "#include <rdma/rdma_cma.h>"
+.P
+.B "int" rdma_leave_multicast
+.BI "(struct rdma_cm_id *" id ","
+.BI "struct sockaddr *" addr ");"
+.SH ARGUMENTS
+.IP "id" 12
+Communication identifier associated with the request.
+.IP "addr" 12
+Multicast address identifying the group to leave.
+.SH "DESCRIPTION"
+Leaves a multicast group and detaches an associated QP from the group.
+.SH "NOTES"
+Calling this function before a group has been fully joined results in
+canceling the join operation. Users should be aware that messages
+received from the multicast group may stilled be queued for
+completion processing immediately after leaving a multicast group.
+Destroying an rdma_cm_id will automatically leave all multicast groups.
+.SH "SEE ALSO"
+rdma_join_multicast, rdma_destroy_qp
--- /dev/null
+.TH "rdma_listen" 3 "rdma_listen" "May 2007" "Librdmacm Programmer's Manual" librdmacm
+.SH NAME
+rdma_listen \- Listen for incoming connection requests.
+.SH SYNOPSIS
+.B "#include <rdma/rdma_cma.h>"
+.P
+.B "int" rdma_listen
+.BI "(struct rdma_cm_id *" id ","
+.BI "int " backlog ");"
+.SH ARGUMENTS
+.IP "id" 12
+RDMA identifier.
+.IP "backlog" 12
+backlog of incoming connection requests.
+.SH "DESCRIPTION"
+Initiates a listen for incoming connection requests or datagram service
+lookup. The listen will be restricted to the locally bound source
+address.
+.SH "NOTES"
+Users must have bound the rdma_cm_id to a local address by calling
+rdma_bind_addr before calling this routine. If the rdma_cm_id is
+bound to a specific IP address, the listen will be restricted to that
+address and the associated RDMA device. If the rdma_cm_id is bound
+to an RDMA port number only, the listen will occur across all RDMA
+devices.
+.SH "SEE ALSO"
+rdma_cm, rdma_bind_addr, rdma_connect, rdma_accept, rdma_reject,
+rdma_get_cm_event
--- /dev/null
+.TH "rdma_notify" 3 "rdma_notify" "May 2007" "Librdmacm Programmer's Manual" librdmacm
+.SH NAME
+rdma_notify \- Notifies the librdmacm of an asynchronous event.
+.SH SYNOPSIS
+.B "#include <rdma/rdma_cma.h>"
+.P
+.B "int" rdma_notify
+.BI "(struct rdma_cm_id *" id ","
+.BI "enum ibv_event_type " event ");"
+.SH ARGUMENTS
+.IP "id" 12
+RDMA identifier.
+.IP "event" 12
+Asynchronous event.
+.SH "DESCRIPTION"
+Used to notify the librdmacm of asynchronous events that have occurred
+on a QP associated with the rdma_cm_id.
+.SH "NOTES"
+Asynchronous events that occur on a QP are reported through the user's
+device event handler. This routine is used to notify the librdmacm of
+communication events. In most cases, use of this routine is not
+necessary, however if connection establishment is done out of band
+(such as done through Infiniband), it's possible to receive data on a
+QP that is not yet considered connected. This routine forces the
+connection into an established state in this case in order to handle
+the rare situation where the connection never forms on its own.
+Events that should be reported to the CM are: IB_EVENT_COMM_EST.
+.SH "SEE ALSO"
+rdma_connect, rdma_accept, rdma_listen
--- /dev/null
+.TH "rdma_reject" 3 "rdma_reject" "May 2007" "Librdmacm Programmer's Manual" librdmacm
+.SH NAME
+rdma_reject \- Called to reject a connection request.
+.SH SYNOPSIS
+.B "#include <rdma/rdma_cma.h>"
+.P
+.B "int" rdma_reject
+.BI "(struct rdma_cm_id *" id ","
+.BI "const void *" private_data ","
+.BI "uint8_t " private_data_len ");"
+.SH ARGUMENTS
+.IP "id" 12
+Connection identifier associated with the request.
+.IP "private_data" 12
+Optional private data to send with the reject message.
+.IP "private_data_len" 12
+Size of the private_data to send, in bytes.
+.SH "DESCRIPTION"
+Called from the listening side to reject a connection or datagram
+service lookup request.
+.SH "NOTES"
+After receiving a connection request event, a user may call rdma_reject
+to reject the request. If the underlying RDMA transport supports
+private data in the reject message, the specified data will be passed to
+the remote side.
+.SH "SEE ALSO"
+rdma_listen, rdma_accept, rdma_get_cm_event
--- /dev/null
+.TH "rdma_resolve_addr" 3 "rdma_resolve_addr" "May 2007" "Librdmacm Programmer's Manual" librdmacm
+.SH NAME
+rdma_resolve_addr \- Resolve destination and optional source addresses.
+.SH SYNOPSIS
+.B "#include <rdma/rdma_cma.h>"
+.P
+.B "int" rdma_resolve_addr
+.BI "(struct rdma_cm_id *" id ","
+.BI "struct sockaddr *" src_addr ","
+.BI "struct sockaddr *" dst_addr ","
+.BI "int " timeout_ms ");"
+.SH ARGUMENTS
+.IP "id" 12
+RDMA identifier.
+.IP "src_addr" 12
+Source address information. This parameter may be NULL.
+.IP "dst_addr" 12
+Destination address information.
+.IP "timeout_ms" 12
+Time to wait for resolution to complete.
+.SH "DESCRIPTION"
+Resolve destination and optional source addresses from IP addresses
+to an RDMA address. If successful, the specified rdma_cm_id will
+be bound to a local device.
+.SH "NOTES"
+This call is used to map a given destination IP address to a usable RDMA
+address. If a source address is given, the rdma_cm_id is bound to that
+address, the same as if rdma_bind_addr were called. If no source
+address is given, and the rdma_cm_id has not yet been bound to a device,
+then the rdma_cm_id will be bound to a source address based on the
+local routing tables. After this call, the rdma_cm_id will be bound to
+an RDMA device. This call is typically made from the active side of a
+connection before calling rdma_resolve_route and rdma_connect.
+.SH "SEE ALSO"
+rdma_create_id, rdma_resolve_route, rdma_connect, rdma_create_qp,
+rdma_get_cm_event, rdma_bind_addr
--- /dev/null
+.TH "rdma_resolve_route" 3 "rdma_resolve_route" "May 2007" "Librdmacm Programmer's Manual" librdmacm
+.SH NAME
+rdma_resolve_route \- Resolve the route information needed to establish a connection.
+.SH SYNOPSIS
+.B "#include <rdma/rdma_cma.h>"
+.P
+.B "int" rdma_resolve_route
+.BI "(struct rdma_cm_id *" id ","
+.BI "int " timeout_ms ");"
+.SH ARGUMENTS
+.IP "id" 12
+RDMA identifier.
+.IP "timeout_ms" 12
+Time to wait for resolution to complete.
+.SH "DESCRIPTION"
+Resolves an RDMA route to the destination address in order to establish
+a connection. The destination address must have already been resolved
+by calling rdma_resolve_addr.
+.SH "NOTES"
+This is called on the client side of a connection after calling
+rdma_resolve_addr, but before calling rdma_connect.
+.SH "SEE ALSO"
+rdma_resolve_addr, rdma_connect, rdma_get_cm_event
--- /dev/null
+.TH "rping" 1 "rping" "May 2007" "librdmacm" librdmacm
+.SH NAME
+rping \- RDMA CM connection and RDMA ping-pong test.
+.SH SYNOPSIS
+.sp
+.nf
+\fIrping\fR -s [-v] [-V] [-d] -a address -p port
+ [-C message_count] [-S message_size]
+\fIrping\fR -c [-v] [-V] [-d] -a address -p port
+ [-C message_count] [-S message_size]
+.fi
+.SH "DESCRIPTION"
+Establishes a reliable RDMA connection between two nodes using the
+librdmacm, optionally performs RDMA transfers between the nodes,
+then disconnects.
+.SH "OPTIONS"
+.TP
+\-s
+Run as the server.
+.TP
+\-c
+Run as the client.
+.TP
+\-a address
+On the server, specifies the network address to bind the connection to.
+On the client, specifies the server address to connect to.
+.TP
+\-p
+Port number for listening server.
+.TP
+\-v
+Display ping data.
+.TP
+\-V
+Validate ping data.
+.TP
+\-d
+Display debug information.
+.TP
+\-C message_count
+The number of messages to transfer over each connection. (default infinite)
+.TP
+\-S message_size
+The size of each message transferred, in bytes. (default 100)
+.SH "NOTES"
+Because this test maps RDMA resources to userspace, users must ensure
+that they have available system resources and permissions. See the
+libibverbs README file for additional details.
+.SH "SEE ALSO"
+rdma_cm, ucmatose, udaddy, mckey
--- /dev/null
+.TH "ucmatose" 1 "ucmatose" "May 2007" "librdmacm" librdmacm
+.SH NAME
+ucmatose \- RDMA CM connection and simple ping-pong test.
+.SH SYNOPSIS
+.sp
+.nf
+\fIucmatose\fR [-s server_address] [-b bind_address] [-c connections]
+ [-C message_count] [-S message_size]
+\fIucmatose\fR -s server_address [-b bind_address] [-c connections]
+ [-C message_count] [-S message_size]
+.fi
+.SH "DESCRIPTION"
+Establishes a set of reliable RDMA connections between two nodes using the
+librdmacm, optionally transfers data between the nodes, then disconnects.
+.SH "OPTIONS"
+.TP
+\-s server_address
+The network name or IP address of the server system listening for
+connections. The used name or address must route over an RDMA device.
+This option must be specified by the client.
+.TP
+\-b bind_address
+The local network address to bind to.
+.TP
+\-c connections
+The number of connections to establish between the client and server.
+(default 1)
+.TP
+\-C message_count
+The number of messages to transfer over each connection. (default 10)
+.TP
+\-S message_size
+The size of each message transferred, in bytes. (default 100)
+.SH "NOTES"
+Basic usage is to start ucmatose on a server system, then run
+ucmatose -s server_name on a client system.
+.P
+Because this test maps RDMA resources to userspace, users must ensure
+that they have available system resources and permissions. See the
+libibverbs README file for additional details.
+.SH "SEE ALSO"
+rdma_cm, udaddy, mckey, rping
--- /dev/null
+.TH "udaddy" 1 "udaddy" "May 2007" "librdmacm" librdmacm
+.SH NAME
+udaddy \- RDMA CM datagram setup and simple ping-pong test.
+.SH SYNOPSIS
+.sp
+.nf
+\fIudaddy\fR [-s server_address] [-b bind_address] [-c connections]
+ [-C message_count] [-S message_size] [-p port_space]
+\fIudaddy\fR -s server_address [-b bind_address] [-c connections]
+ [-C message_count] [-S message_size] [-p port_space]
+.fi
+.SH "DESCRIPTION"
+Establishes a set of unreliable RDMA datagram communication paths between two
+nodes using the librdmacm, optionally transfers datagrams between the nodes,
+then tears down the communication.
+.SH "OPTIONS"
+.TP
+\-s server_address
+The network name or IP address of the server system listening for
+communication. The used name or address must route over an RDMA device.
+This option must be specified by the client.
+.TP
+\-b bind_address
+The local network address to bind to.
+.TP
+\-c connections
+The number of communication paths to establish between the client and server.
+The test uses unreliable datagram communication, so no actual connections are
+formed. (default 1)
+.TP
+\-C message_count
+The number of messages to transfer over each connection. (default 10)
+.TP
+\-S message_size
+The size of each message transferred, in bytes. This value must be smaller
+than the MTU of the underlying RDMA transport, or an error will occur.
+(default 100)
+.TP
+\-p port_space
+The port space of the datagram communication. May be either the RDMA
+UDP (0x0111) or IPoIB (0x0002) port space. (default RDMA_PS_UDP)
+.SH "NOTES"
+Basic usage is to start udaddy on a server system, then run
+udaddy -s server_name on a client system.
+.P
+Because this test maps RDMA resources to userspace, users must ensure
+that they have available system resources and permissions. See the
+libibverbs README file for additional details.
+.SH "SEE ALSO"
+rdma_cm, ucmatose, mckey, rping
projects / ~shefty / librdmacm.git / commitdiff