UMAD_SEND(3)

💌 UMAD_SEND(3) — the OpenIB Programmer's Manual, bestie edition ✨

okay so like. this is umad_send, from the OpenIB Programmer's Manual, and it's genuinely one of the most useful little functions in the whole infiniband/umad.h cinematic universe. sit down, hydrate, let's get into it 🫶

🌸 NAME 🌸

umad_send — send umad 💅

✨ SYNOPSIS ✨

#include <infiniband/umad.h>

int umad_send(int portid, int agentid, void *umad, int length, int timeout_ms, int retries);

like. that's it. that's the whole signature. iconic of her tbh 🎀

🦋 DESCRIPTION 🦋

So what does umad_send() actually do, you ask? She sends length bytes from the umad buffer you handed her 💖 — out of the port that portid points at, and using the agent that agentid says. that's the whole vibe. port, agent, bytes, go.

Now here's the tea ☕ — that buffer can hold an RMPP transmission, which is bigger than a single MAD packet. when does that happen? when agentid specifies a class that utilizes RMPP and the header flags indicate RMPP is active. both things. not one. both. 👑

NOTE: right now, only RMPPFlags.Active is actually meaningful in the header in user space. every other RMPP field? ignored. not looked at. not even a little. 💀

But the glow-up is real: the data section of your buffer gets sent in multiple RMPP MAD packets, and the headers get built for you. you don't build them. she builds them. you're welcome 🧚

Now, timeout_ms — this one controls the solicited MADs behavior, and it's lowkey doing three different jobs depending on what you feed it:

• zero value — not solicited. that's it, that's the whole meaning.
• positive value — makes the kernel indicate a timeout in milliseconds. if the reply isn't received within the value you specified, the original buffer comes back at you in the read channel with the status field set (to non zero). so like, you will know. 😭
• negative timeout_ms — makes the kernel wait forever for the reply. no timeout. no escape. she's patient. 🕰️

And retries? that's the number of times the MAD will be retried before giving up. simple as. 🔥

💅 RETURN VALUE 💅

umad_send() returns 0 on success 🎉 — and on error, errno gets set and a negative value comes back, like so:

• -EINVAL — invalid port handle or agentid 🙈
• -EIO — send operation failed 💀

so like, if you get a negative number back, check errno, and if it's one of those two, you already know what went wrong. no cap.

👑 AUTHOR 👑

Hal Rosenstock <halr@voltaire.com> — the actual main character who wrote this. respect. 🫶

and that's the page, bestie!! from the OpenIB crew, dated May 11, 2007 — yeah she's been serving since 2007 and she's still eating ⭐✨ go send some MADs, you got this 🦋💜