BUS_ACTIVATE_RESOURCE(9)

💅 BUS_ACTIVATE_RESOURCE(9) — the kernel dev manual, bestie edition

okay so this is a page from the Kernel Developer's Manual, and we're talking about bus_activate_resource(9) — the whole glow-up of a resource from "allocated" to "actually usable." buckle up 🎀

---

✨ NAME ✨

bus_activate_resource, bus_deactivate_resource — activate or deactivate a resource. that's it, that's the vibe. on and off. the light switch of kernel resources 💡

---

🌸 SYNOPSIS 🌸

#include <sys/param.h>
#include <sys/bus.h>

#include <machine/bus.h>
#include <sys/rman.h>
#include <machine/resource.h>

int
bus_activate_resource(device_t dev, struct resource *r);

int
bus_deactivate_resource(device_t dev, struct resource *r);

yes bestie, all five includes. every single one. they're all invited to the function signature party 🫶

---

💖 DESCRIPTION 💖

so these two functions activate or deactivate a resource you already allocated earlier. lowkey the important part: in general, resources must be activated before they can be accessed by the driver. like, no activation, no access. that's the rule, fr fr.

bus drivers may do extra little side quests to make sure the resource is genuinely ready to be accessed. iconic example: the PCI bus driver enables memory decoding in a PCI device's command register when it activates a memory resource. slay 💅

the arguments, bestie — respect them:

• dev — the device that's requesting ownership of the resource. and note this: before allocation, the resource is owned by the parent bus. so it's a whole custody situation 👑
• r — a pointer to the struct resource returned by bus_alloc_resource(9). that's where you got it, that's who you thank.

🦋 Resource Mapping 🦋

okay this part is kind of the main character. resources that can be mapped for CPU access by a bus_space(9) tag and handle will create a mapping of the entire resource when activated. the whole thing. no crumbs 😌

the tag and handle for this mapping live inside r, and you can retrieve them via rman_get_bustag(9) and rman_get_bushandle(9). then you can use them with the bus_space(9) API to access device registers or memory described by r. and if the mapping is associated with a virtual address, you get that virtual address via rman_get_virtual(9). it's giving full access package ✨

not feeling the implicit mapping? totally valid. you can disable it by passing the RF_UNMAPPED flag to bus_alloc_resource(9). a driver might do this if it wants to allocate its own mappings of a resource using bus_map_resource(9). DIY energy, we respect it 🛠️

there's also a wrapper API for bus_space(9) that takes the associated resource as the first argument instead of the bus_space(9) tag and handle. the functions in this wrapper API are named similarly to the bus_space(9) API, except that “_space” is removed from their name. so for example, bus_read_4() can be used in place of bus_space_read_4(). and listen — the wrapper API is preferred in new drivers. new drivers, take notes 📝

these two statements both read a 32-bit register at the start of a resource, no cap:

bus_space_read_4(rman_get_bustag(res), rman_get_bushandle(res), 0);
bus_read_4(res, 0);

same result, but one of them is the aesthetic choice 💅

---

🔥 RETURN VALUES 🔥

zero is returned on success. otherwise, an error is returned. that's it. 0 = slay, anything else = not slay 😭

---

🌈 SEE ALSO 🌈

• bus_alloc_resource(9)
• bus_map_resource(9)
• bus_space(9)
• device(9)
• driver(9)

the whole friend group, honestly 🫶

---

👑 AUTHORS 👑

this manual page was written by Warner Losh <imp@FreeBSD.org>. king behavior, thank you for your service 🎀

---

💀 friendly reminder bestie: activate before you access. the manpage said it, not me.

---

and that's the page!! this edition came from Debian, dated March 13, 2024 — mwah, bye bestie, go activate some resources 💜✨