RDMA_CONNECT(3)

🌸 rdma_connect(3) — the Librdmacm Programmer's Manual glow-up 🌸

okay bestie, welcome to the librdmacm programmer's manual 💖 this is rdma_connect, and yes, it's exactly as iconic as it sounds.

✨ NAME ✨

rdma_connect — Initiate an active connection request. like, you're the one reaching out first. main character energy fr fr 👑

✨ SYNOPSIS ✨

#include <rdma/rdma_cma.h>

int rdma_connect (struct rdma_cm_id *id, struct rdma_conn_param
*conn_param);

that's it. two args. you got this 💅

✨ ARGUMENTS ✨

• id — the RDMA identifier. your lil handle on the whole situation 🪪
• conn_param — the connection parameters. wanna know what's in there? scroll down to CONNECTION PROPERTIES, it's all laid out for you 🎀

✨ DESCRIPTION ✨

so here's the tea ☕ if your rdma_cm_id is type RDMA_PS_TCP, this call initiates a connection request to a remote destination. and if your rdma_cm_id is type RDMA_PS_UDP, it initiates a lookup of the remote QP providing the datagram service. two vibes, one function. versatile queen 💅

✨ RETURN VALUE ✨

• Returns 0 on success 🎉
• Returns -1 on error 😭

and if there's an error, errno gets set to tell you why it went wrong. read your errno, bestie, it's literally trying to communicate with you.

✨ NOTES ✨

⚠️ okay important: you must have resolved a route to the destination address first. that means you already called rdma_resolve_route or rdma_create_ep before calling this routine. no route, no connect. periodt.

✨ CONNECTION PROPERTIES ✨

these are the properties that configure the communication, and they're specified by the conn_param parameter when you're connecting or establishing datagram communication. let's go one by one, no skipping 🫶

• private_data — references a user-controlled data buffer. the contents get copied and transparently passed to the remote side as part of the communication request. can be NULL if you don't need private_data at all. no pressure 🌸
• private_data_len — the size of that user-controlled data buffer. but heads up 👀 the actual amount of data transferred to the remote side is transport dependent and may be larger than that requested. so like, it can over-deliver. relatable.
• 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. this value must be less than or equal to the local RDMA device attribute max_qp_rd_atom and the remote RDMA device attribute max_qp_init_rd_atom. also the remote endpoint can adjust this value when accepting the connection. so it's a suggestion, not a decree 💅
• 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. this value must be less than or equal to the local RDMA device attribute max_qp_init_rd_atom and the remote RDMA device attribute max_qp_rd_atom. and yeah, the remote endpoint can adjust this one too when accepting the connection.
• flow_control — specifies if hardware flow control is available. this value gets exchanged with the remote peer and is not used to configure the QP. applies only to RDMA_PS_TCP.
• 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 how many times to retry send, RDMA, and atomic operations when timeouts occur. applies only to RDMA_PS_TCP.
• rnr_retry_count — the maximum number of times that a send operation from the remote peer should be retried on a connection after receiving a receiver not ready (RNR) error. RNR errors happen when a send request arrives before a buffer has been posted to receive the incoming data. applies only to RDMA_PS_TCP. (imagine showing up and nobody's home 😭)
• 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.
• qp_num — specifies the QP number associated with the connection. this field is also ignored by the library if a QP has been created on the rdma_cm_id. applies only to RDMA_PS_TCP.

✨ INFINIBAND SPECIFIC ✨

okay so on top of all the connection properties above, InfiniBand QPs get configured with a minimum RNR NAK timer and local ACK timeout value. here's the deal:

• The minimum RNR NAK timer value is set to 0, for a delay of 655 ms.
• The local ACK timeout is calculated based on the packet lifetime and the local HCA ACK delay.
• The packet lifetime is determined by the InfiniBand Subnet Administrator and is part of the resolved route (path record) information.
• The HCA ACK delay is a property of the locally used HCA.

also, retry count and RNR retry count values are 3-bit values. tiny little numbers. precious.

and the length of the private data provided by the user is limited to 56 bytes for RDMA_PS_TCP, or 180 bytes for RDMA_PS_UDP. so keep it cute and keep it short 🌸

✨ IWARP SPECIFIC ✨

connections established over iWarp RDMA devices currently require that the active side of the connection send the first message. yes, you have to text first. it's giving situationship but okay, that's just how iWarp works 🦋

✨ SEE ALSO ✨

go read these next, they're all part of the friend group:

• rdma_cm(7)
• rdma_create_id(3)
• rdma_resolve_route(3)
• rdma_disconnect(3)
• rdma_listen(3)
• rdma_get_cm_event(3)

okay that's the whole page bestie, you absolutely ate this 💅✨ this was the librdmacm programmer's manual, RDMA_CONNECT(3), dated 2010-07-19 — vintage but still serving 👑 bye love u, go connect something 🫶💖