BUS_MAP_RESOURCE(9)

💖 BUS_MAP_RESOURCE(9) 💖

okay bestie, so this is a page from the Kernel Developer's Manual and it's all about bus_map_resource, bus_unmap_resource, and resource_init_map_request — aka the glow-up that lets your CPU actually touch a resource. slay.

---

✨ NAME ✨

bus_map_resource, bus_unmap_resource, resource_init_map_request — map or unmap an active resource 🗺️

---

🌸 SYNOPSIS 🌸

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

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

int
bus_map_resource(device_t dev, int type, struct resource *r,
    struct resource_map_request *args, struct resource_map *map);

int
bus_unmap_resource(device_t dev, int type, struct resource *r,
    struct resource_map *map);

void
resource_init_map_request(struct resource_map_request *args);

---

🦋 DESCRIPTION 🦋

so these functions either create or destroy a mapping of a resource that you already activated earlier. no cap. and like, what even is a mapping? it's the thing that lets the CPU get in there via the bus_space(9) API. it's giving backstage pass energy. 🎀

the arguments, bestie, are as follows:

• dev — the device that owns the resource. it's the main character here honestly.
• type — the type of resource to map. it's one of:
  • SYS_RES_IOPORT — for I/O ports
  • SYS_RES_MEMORY — for I/O memory
• r — a pointer to the struct resource that bus_alloc_resource(9) handed you.
• args — a lil set of optional properties to apply when you create a mapping. you can set this to NULL if you want a mapping of the entire resource with the default properties. no thoughts, just vibes.
• map — the resource mapping you're creating or destroying.

🫶 Resource Mappings

resource mappings are described by a struct resource_map object. this structure contains a bus_space(9) tag and handle in the r_bustag and r_bushandle members, and those are what you use for CPU access to the mapping. it also contains a r_vaddr member, which holds the virtual address of the mapping if one even exists. 💅

the wrapper API for struct resource objects described in bus_activate_resource(9) can also be used with struct resource_map. for example, you can pass a pointer to a mapping object as the first argument to bus_read_4(). and honestly? that wrapper API is preferred over poking r_bustag and r_bushandle directly. periodt. 👑

🌈 Optional Mapping Properties

the struct resource_map_request object you pass in args is how you specify optional properties of a mapping. you must initialize the structure first by invoking resource_init_map_request(). after that, you set one or more of these members:

• offset, length — these two members specify a region of the resource to map. by default a mapping gets created for the entire resource. the offset is relative to the start of the resource. 🎯
• memattr — specifies a memory attribute to use when mapping the resource. by default, memory mappings use the VM_MEMATTR_UNCACHEABLE attribute. iykyk.

---

⭐ RETURN VALUES ⭐

zero is returned on success. otherwise an error is returned. that's it, that's the tea. 🍓

---

🔥 EXAMPLES 🔥

this maps a PCI memory BAR with the write-combining memory attribute and reads the first 32-bit word. iconic behaviour, honestly:

struct resource *r;
struct resource_map map;
struct resource_map_request req;
uint32_t val;
int rid;

rid = PCIR_BAR(0);
r = bus_alloc_resource_any(dev, SYS_RES_MEMORY, &rid, RF_ACTIVE |
    RF_UNMAPPED);
resource_init_map_request(&req);
req.memattr = VM_MEMATTR_WRITE_COMBINING;
bus_map_resource(dev, SYS_RES_MEMORY, r, &req, &map);
val = bus_read_4(&map, 0);

---

👀 SEE ALSO 👀

bus_activate_resource(9), bus_alloc_resource(9), bus_space(9), device(9), driver(9)

go read those next bestie, fr fr. 📚✨

---

💜 AUTHORS 💜

this manual page was written by John Baldwin <jhb@FreeBSD.org>. thank you king 🙇‍♀️👑

---

and that's the whole page, bestie!! this one came from Debian, dated February 5, 2018, and it lives under the name BUS_MAP_RESOURCE(9). mwah, go map some resources responsibly 💅💖✨