IBV_CREATE_AH(3)

💖 ibv_create_ah(3) — the libibverbs programmer's manual, bestie edition 💖

okay so this is a page from the Libibverbs Programmer's Manual, and today we're talking about ibv_create_ah(3) — that's ibv_create_ah and ibv_destroy_ah, the two functions that make and unmake an address handle, aka an AH. yes bestie, you're gonna be creating and destroying address handles and it's gonna be iconic. 🦋

---

✨ NAME ✨

ibv_create_ah, ibv_destroy_ah — create or destroy an address handle (AH). periodt. 💅

---

🌸 SYNOPSIS 🌸

#include <infiniband/verbs.h>

struct ibv_ah *ibv_create_ah(struct ibv_pd *pd,
                             struct ibv_ah_attr *attr);

int ibv_destroy_ah(struct ibv_ah *ah);

like, that's the whole vibe. two functions. one makes, one breaks. 🎀

---

💜 DESCRIPTION 💜

okay so ibv_create_ah() creates an address handle (AH) that's associated with the protection domain pd. and the attr argument? it's an ibv_ah_attr struct, which is defined in <infiniband/verbs.h>. not me knowing the header by heart 😭

here's what ibv_ah_attr looks like, literally verbatim:

struct ibv_ah_attr {
        struct ibv_global_route grh;            /* Global Routing Header (GRH) attributes */
        uint16_t                dlid;           /* Destination LID */
        uint8_t                 sl;             /* Service Level */
        uint8_t                 src_path_bits;  /* Source path bits */
        uint8_t                 static_rate;    /* Maximum static rate */
        uint8_t                 is_global;      /* GRH attributes are valid */
        uint8_t                 port_num;       /* Physical port number */
};

and the grh field is itself a struct ibv_global_route, which goes like this:

struct ibv_global_route {
        union ibv_gid           dgid;           /* Destination GID or MGID */
        uint32_t                flow_label;     /* Flow label */
        uint8_t                 sgid_index;     /* Source GID index */
        uint8_t                 hop_limit;      /* Hop limit */
        uint8_t                 traffic_class;  /* Traffic class */
};

and then ibv_destroy_ah() destroys the AH ah. that's it. that's the whole function. she's simple, she's efficient, she ate. 🔥

---

⭐ RETURN VALUE ⭐

ibv_create_ah() returns a pointer to the created AH. 🫶 and if the request fails? she returns NULL. no AH for you bestie. 💀

---

👑 NOTES 👑

okay this part matters, don't skip it:

If port flag IBV_QPF_GRH_REQUIRED is set then ibv_create_ah() must be created with definition of 'struct ibv_ah_attr { .is_global = 1; .grh = {...}; }'.

like literally, copy that exactly, don't freestyle it. .is_global = 1 and .grh = {...} or it's not happening. 🚨

ibv_destroy_ah() returns 0 on success, or the value of errno on failure — and that errno value tells you the failure reason. so when it's not 0, go read your errno, she's trying to tell you something. 🧚

---

🌈 SEE ALSO 🌈

• ibv_alloc_pd(3)
• ibv_init_ah_from_wc(3)
• ibv_create_ah_from_wc(3)

(the holy trinity of AH-adjacent lore, iykyk ✨)

---

💖 AUTHORS 💖

Dotan Barak <dotanba@gmail.com> — thank you for your service king 🫡

---

and that's the whole page bestie!! this came out of libibverbs and it's dated 2006-10-31 — yeah she's been iconic since 2006, main character energy fr fr. go forth and create (and destroy) your address handles responsibly 💅🎀🌸