UMAD_GET_PORT(3)

💅 UMAD_GET_PORT — open and close an InfiniBand port

okay bestie, gather round, because this is a manual page from the OpenIB Programmer's Manual (that's the manual name, keep it in your notes 📓) and it's about two little functions that open and close an InfiniBand port. yes, umad_get_port and umad_release_port. iconic duo. they come as a pair, like you and your emotional support water bottle 🫶

✨ NAME ✨

umad_get_port, umad_release_port — open and close an InfiniBand port

lowkey the most self-explanatory NAME section of all time, and honestly? we love a function that knows what it is.

🌸 SYNOPSIS 🌸

#include <infiniband/umad.h>

int umad_get_port(char *ca_name, int portnum, umad_port_t *port);

int umad_release_port(umad_port_t *port);

two functions, both returning int. no cap. 💖

🦋 DESCRIPTION 🦋

so here's the tea ☕

umad_get_port() fills the port structure with the IB port attributes specified by ca_name and portnum, or the default port if ca_name is NULL and portnum is zero.

and here's the cute part — if you only specify one of ca_name and portnum, the other one gets used as a filter. for example: passing a NULL ca_name and 2 for the portnum means "get me a port from any of the local IB devices, as long as it is the second port". it's giving ✨ picky but flexible ✨

not me being dramatic but LISTEN: the library may use some reference scheme to support port caching, so umad_release_port() should be called before the port structure can be deallocated. do not just free it and walk away, bestie, that's a red flag 🚩

the argument port is an umad_port_t struct, as specified in <infiniband/umad.h>.

and here's that struct in all its glory, verbatim, because we do NOT mess with source code around here 👑

typedef struct umad_port {
        char ca_name[UMAD_CA_NAME_LEN];                 /* Name of the device */
        int portnum;                                    /* Physical port number */
        uint base_lid;                                  /* Base port LID */
        uint lmc;                                       /* LMC of LID */
        uint sm_lid;                                    /* SM LID */
        uint sm_sl;                                     /* SM service level */
        uint state;                                     /* Logical port state */
        uint phys_state;                                /* Physical port state */
        uint rate;                                      /* Port link bit rate */
        uint64_t capmask;                               /* Port capabilities */
        uint64_t gid_prefix;                            /* Gid prefix of this port */
        uint64_t port_guid;                             /* GUID of this port */
} umad_port_t;

look at all those fields. ca_name, portnum, base_lid, lmc, sm_lid, sm_sl, state, phys_state, rate, capmask, gid_prefix, port_guid. twelve fields of pure information. she's thorough 💅

umad_release_port() releases the resources that were allocated by the umad_get_port() function for the specified IB port. it's the cleanup bestie. the "okay we're done here, thank you next" function. 🌈

🎀 RETURN VALUE 🎀

both umad_get_port() and umad_release_port() return 0 on success, and a negative value on error.

so like, 0 = slay, negative = not slay. simple as that. 😭

👑 AUTHORS 👑

the legends who made this happen:

• Hal Rosenstock <halr@voltaire.com>
• Dotan Barak <dotanb@mellanox.co.il>

periodt. absolute icons. 🫶

🌟 SEE ALSO 🌟

nothing listed here bestie, but like… check <infiniband/umad.h> obviously. iykyk.

and that's the whole page!! this one came from the OpenIB folks, dated May 21, 2007, and it lives at section 3 of the manual — so when you're lost, just yell man 3 umad_get_port and it'll come running 🧚✨