Protocols

libevpl has built-in support for multiple network protocols. Each protocol has a unique identifier used when creating connections or listeners.

Protocol Types

Stream Protocols

Stream protocols provide reliable, ordered byte streams:

Protocol ID	Description
`EVPL_STREAM_SOCKET_TCP`	Standard TCP sockets via the kernel
`EVPL_STREAM_SOCKET_TLS`	TLS-encrypted TCP connections
`EVPL_STREAM_IO_URING_TCP`	TCP using io_uring for improved performance
`EVPL_STREAM_LIBFABRIC_MSG`	Connected stream over a libfabric MSG provider
`EVPL_STREAM_RDMACM_RC`	RDMA Reliable Connection (RC) via RDMACM

Datagram Protocols

Datagram protocols provide message-oriented communication:

Protocol ID	Description
`EVPL_DATAGRAM_LIBFABRIC_MSG`	Connected messages over libfabric MSG
`EVPL_DATAGRAM_LIBFABRIC_RDM`	Reliable datagrams over libfabric RDM
`EVPL_DATAGRAM_SOCKET_UDP`	Standard UDP datagrams
`EVPL_DATAGRAM_RDMACM_UD`	RDMA Unreliable Datagram (UD)
`EVPL_DATAGRAM_TCP_RDMA`	RDMA emulation over TCP (see below)

TCP-RDMA Protocol

The EVPL_DATAGRAM_TCP_RDMA protocol provides RDMA semantics over standard TCP sockets. This enables development and testing of RDMA-based applications without requiring RDMA hardware.

Despite being implemented over TCP (a stream protocol), TCP-RDMA presents a datagram-style message interface because it emulates RDMA operations which are inherently message-based.

Use cases:

Development without RDMA hardware
CI/CD testing in virtualized environments
Debugging RDMA protocols with standard network tools
Cross-platform RDMA application support

See the RDMA API documentation for details on using TCP-RDMA.

Frameworks

Frameworks are the underlying I/O implementations that protocols use:

Framework ID	Description
`EVPL_FRAMEWORK_SOCKET`	Standard kernel sockets (epoll/kqueue)
`EVPL_FRAMEWORK_RDMACM`	RDMA Connection Manager
`EVPL_FRAMEWORK_IO_URING`	Linux io_uring
`EVPL_FRAMEWORK_VFIO`	VFIO for userspace device access
`EVPL_FRAMEWORK_TLS`	TLS/SSL via OpenSSL
`EVPL_FRAMEWORK_TCP_RDMA`	TCP-based RDMA emulation

Protocol Selection

Use evpl_protocol_lookup to convert a protocol name string to its ID:

enum evpl_protocol_id proto;
int rc = evpl_protocol_lookup(&proto, "STREAM_SOCKET_TCP");
if (rc == 0) {
    /* proto now contains EVPL_STREAM_SOCKET_TCP */
}

Common protocol name strings:

"STREAM_SOCKET_TCP" - TCP
"STREAM_SOCKET_TLS" - TLS over TCP
"DATAGRAM_SOCKET_UDP" - UDP
"STREAM_RDMACM_RC" - RDMA RC
"DATAGRAM_TCP_RDMA" - TCP-RDMA emulation

Libfabric RDM addressing and wire format

MSG and RDM providers are discovered independently. For example, FI_PROVIDER='tcp;ofi_rxm' can supply RDM without supplying MSG. The backend currently uses IPv4 addresses. Bind to the local interface you intend to use; a wildcard bind selects one provider domain and does not span all interfaces or HCAs. Port zero obtains an ephemeral listening port.

RDM callbacks supply a borrowed notify.recv_msg.addr. Pass it to evpl_sendto or evpl_sendtov to reply; those calls retain the reference needed by queued sends after the callback returns. This is a peer-advertised reply endpoint, not an authenticated source identity.

Libevpl RDM messages have a 12-byte source-address envelope followed by the application payload. This works with providers such as TCP and RxM that cannot recover an unknown source through FI_SOURCE_ERR. The envelope has four fields, all in network byte order: a 32-bit version marker 0x45565001, a 32-bit IPv4 listening address, a 16-bit listening port, and 16 reserved bits set to zero. It contains no native sockaddr layout, so Linux and macOS use the same wire representation. Malformed or unsupported envelopes are dropped.

Both peers must use this wire format; it is incompatible with the earlier unframed implementation in this draft PR and with raw libfabric messages. The application payload limit is unchanged. Receive buffers include the additional 12 bytes. Sends normally prepend one registered iovec without copying the payload; when that would exceed the provider’s iovec limit, the header and payload are coalesced into one registered buffer.