DEVINFO(3)

💅 DEVINFO(3) — like, the whole devinfo manual, bestie 💅

okay so this is the page for DEVINFO(3) from the Library Functions Manual — yes, that manual, section 3, the "library functions" one. Sit down, grab a strawberry drink 🍓, and let me tell you about the little library that lets you peek at your kernel's device tree and I/O resource manager. it's giving backstage pass energy fr fr.

✨ NAME ✨

devinfo, devinfo_init, devinfo_free, devinfo_handle_to_device, devinfo_handle_to_resource, devinfo_handle_to_rman, devinfo_foreach_device_child, devinfo_foreach_device_resource, devinfo_foreach_rman_resource, devinfo_foreach_rman — the device and resource information utility library 🎀

📚 LIBRARY 📚

Device and Resource Information Utility Library (libdevinfo, -ldevinfo)

🦋 SYNOPSIS 🦋

#include <devinfo.h>

int
devinfo_init(void);

void
devinfo_free(void);

struct devinfo_dev *
devinfo_handle_to_device(devinfo_handle_t handle);

struct devinfo_res *
devinfo_handle_to_resource(devinfo_handle_t handle);

struct devinfo_rman *
devinfo_handle_to_rman(devinfo_handle_t handle);

int
devinfo_foreach_device_child(struct devinfo_dev *parent,
    int (*fn)(struct devinfo_dev *child, void *arg), void *arg);

int
devinfo_foreach_device_resource(struct devinfo_dev *dev,
    int (*fn)(struct devinfo_dev *dev,
    struct devinfo_res *res, void *arg), void *arg);

int
devinfo_foreach_rman_resource(struct devinfo_rman *rman,
    int (*fn)(struct devinfo_res *res, void *arg), void *arg);

int
devinfo_foreach_rman(int (*fn)(struct devinfo_rman *rman, void *arg),
    void *arg);

🌸 DESCRIPTION 🌸

The devinfo library is your hookup to the kernel's internal device hierarchy and to the I/O resource manager. iconic. it does the whole thing through a sysctl(3) interface — it grabs a snapshot of the kernel's state and then hands that snapshot to your application. no cap, that's the entire trick ✨

and here's the vibe: because this information can logically be arranged in like a million different ways, the library does not try to force any structure onto the data. it's not gonna tell you how to feel about it. it just gives you the raw material and lets you, the main character, organize it however you want 💅

Device, resource, and resource manager info comes back in data structures defined in <devinfo.h>, and they look exactly like this:

struct devinfo_dev {
    devinfo_handle_t    dd_handle;      /* device handle */
    devinfo_handle_t    dd_parent;      /* parent handle */
    char                *dd_name;       /* name of device */
    char                *dd_desc;       /* device description */
    char                *dd_drivername; /* name of attached driver */
    char                *dd_pnpinfo;    /* pnp info from parent bus */
    char                *dd_location;   /* Where bus thinks dev at */
    uint32_t            dd_devflags;    /* API flags */
    uint16_t            dd_flags;       /* internal dev flags */
    device_state_t      dd_state;       /* attachment state of dev */
};

struct devinfo_rman {
    devinfo_handle_t    dm_handle;      /* resource manager handle */
    rman_res_t          dm_start;       /* resource start */
    rman_res_t          dm_size;        /* resource size */
    char                *dm_desc;       /* resource description */
};

struct devinfo_res {
    devinfo_handle_t    dr_handle;      /* resource handle */
    devinfo_handle_t    dr_rman;        /* resource manager handle */
    devinfo_handle_t    dr_device;      /* owning device */
    rman_res_t          dr_start;       /* region start */
    rman_res_t          dr_size;        /* region size */
};

The devinfo_handle_t values are your lil lookup keys — you use them to find the correspondingly referenced structures. iykyk 🔑

• devinfo_init() — takes a snapshot of the kernel's internal device and resource state. it returns nonzero if, after a bunch of retries, it just can't get a consistent snapshot. and listen: you must call devinfo_init() before you can use any of the other functions. it's the entry fee, bestie 🎟️
• devinfo_free() — releases the memory associated with the snapshot. and it's lowkey brutal about it: any pointers returned by the other functions get invalidated by this, and you have to call devinfo_init() again before using any other functions. so don't be out here using stale pointers, that's not the vibe 😭
• devinfo_handle_to_device(), devinfo_handle_to_resource(), and devinfo_handle_to_rman() — these return pointers to devinfo_dev, devinfo_res, and devinfo_rman structures respectively, based on the devinfo_handle_t you hand them. you can use them to traverse the tree from any node to any other node. and a fun one: if you pass the constant DEVINFO_ROOT_DEVICE to devinfo_handle_to_device(), it returns the handle to the root of the device tree. the origin story 🌱
• devinfo_foreach_device_child() — invokes its callback argument fn on every device that's an immediate child of device. fn also gets passed arg, so you can sneak state into the callback. and if fn returns a nonzero error value? boom, traversal halts, and devinfo_foreach_device_child() returns that error value right back to the caller. early exit slay 💀
• devinfo_foreach_device_resource() — invokes its callback argument fn on every resource owned by device. fn also gets device and arg, so state travels with you. if fn returns a nonzero error value the traversal halts and devinfo_foreach_device_resource() returns the error value to its caller. same energy 🫶
• devinfo_foreach_rman_resource() — invokes its callback argument fn on every resource within the resource manager rman. fn also gets arg. nonzero from fn → traversal halts → devinfo_foreach_rman_resource() returns that error value to its caller. periodt ⭐
• devinfo_foreach_rman() — invokes its callback argument fn on every resource manager. fn also gets arg, bestie, state travels. if fn returns a nonzero error value the traversal halts and devinfo_foreach_rman() returns the error value to its caller. consistent queen 👑

---

👀 SEE ALSO 👀

devstat(3) — go look at that one too, it's friends with this one 🦋

🧚 HISTORY 🧚

The devinfo library first appeared in FreeBSD 5.0. a legend from day one, honestly 🌈

💖 AUTHORS 💖

Michael Smith <msmith@FreeBSD.org> — thank you for your service, king 👑

🙈 BUGS 🙈

• okay so this is the first implementation of the library, and ngl the interface is still subject to refinement. it's a work in progress, we love a growing girl 💅
• also: the interface does not report device classes or drivers, which makes it hard to sort by class or driver. yeah. that's the whole bug. it's giving "organized chaos" 😭

---

and that's the page, bestie! 🎀 this one came from Debian, dated April 19, 2001 — like, a vintage. wear it with pride, and remember: call devinfo_init() first, always 🫶✨