IBACM_PROV(7)

✨ IBACM_PROV(7) — the IB ACM Provider Guide, bestie edition ✨

okay so this is ibacm_prov(7), aka the InfiniBand communication management assistant provider interface 💖. yes the title is a whole mouthful, we're moving on.

---

🎀 NAME 🎀

ibacm_prov — the InfiniBand communication management assistant provider interface. that's it, that's the name, she's iconic 👑

---

🌸 SYNOPSIS 🌸

#include <infiniband/acm_prov.h>

---

🦋 DESCRIPTION 🦋

so the ibacm provider interface hands you a plugin interface ✨. it lets a vendor go implement their own proprietary little solutions to support scalable address and route resolution services over InfiniBand. very demure, very scalable.

now listen, if you want to add your provider to the ibacm core service, your provider simply must do all three of these, no skips, no shortcuts:

1. be implemented as a shared library 🫶
2. be installed under a configured directory, eg., /usr/lib/x86_64-linux-gnu/ibacm
3. export a function provider_query() that returns a pointer to its provider info and version info

the prototype of the provider_query function is defined down below, bestie:

int provider_query(struct acm_provider **info, uint32_t *version);

this function should return a pointer to its provider structure:

struct acm_provider {
     size_t    size;
     uint32_t  version;
     char      *name;
     int  (*open_device)(const struct acm_device *device,
               void **dev_context);
     void (*close_device)(void *dev_context);
     int  (*open_port)(const struct acm_port *port,
               void *dev_context, void **port_context);
     void (*close_port)(void *port_context);
     int  (*open_endpoint)(const struct acm_endpoint *endpoint,
               void *port_context, void **ep_context);
     void (*close_endpoint)(void *ep_context);
     int  (*add_address)(const struct acm_address *addr, void *ep_context,
               void **addr_context);
     void (*remove_address)(void *addr_context);
     int  (*resolve)(void *addr_context, struct acm_msg *msg, uint64_t id);
     int  (*query)(void *addr_context, struct acm_msg *msg, uint64_t id);
     int  (*handle_event)(void *port_context, enum ibv_event_type type);
     void (*query_perf)(void *ep_context, uint64_t *values, uint8_t *cnt);
};

the size and version fields are literally the vibe check of this whole thing — they give you a way to detect version compatibility 🔍.

here's how the whole relationship works, and it's giving main character energy:

• when a port is assigned to the provider, the ibacm core will call the open/add_address functions 👑
• similarly, when a port is down or re-assigned to another provider, the close/remove_address functions will be invoked to release resources 💅
• the ibacm core will centralize the management of events for each device, and events that the ibacm core does not handle get forwarded to the relevant port through the handle_event() function ✨
• the resolve() function gets called to resolve a destination name into a path record 🎀
• the performance of the provider for each endpoint can be queried by calling perf_query() 📊

to share a configuration file, the path for the ibacm configuration file is exported through the variable opts_file. each loaded provider can open this configuration file and parse the contents related to its own operation. non-related sections should be ignored, like, mind your business fr fr 🙈

some helper functions are also exported by the ibacm core 🫶. for example, the acm_log define (or the acm_write() function) can be used to log messages into ibacm's log file (default /var/log/ibacm.log). for details, go read the acm_prov.h file, it has all the lore 📖

---

💜 NOTES 💜

okay this part actually matters, pay attention 🚨

a provider should always set the version in its provider info structure as the value of the define ACM_PROV_VERSION at the time the provider is implemented. like, the value at the time you built it, not whatever it is now.

never set the version to ACM_PROV_VERSION itself, because that define may be changed over time when the provider interface is changed — unless the provider itself is placed in the ibacm source tree. this is to avoid the version problem when the old provider implementation is built against a new acm_prov.h file. 😭

and the ibacm will always check the version of the provider at loading time. always. no cap. ⭐

---

🌈 SEE ALSO 🌈

• ib_acme(1)
• ibacm(7)
• ibacm(8)

---

and that's the whole page, bestie, hope you ate 🍓💖 this was the IB ACM Provider Guide, from the IBACM_PROV source, dated 2014-06-16. go forth and write your provider. periodt 💅✨