BUS_MAP_RESOURCE(9)

💖 BUS_MAP_RESOURCE(9) — from the Kernel Developer's Manual, but make it group-chat 💖

okay bestie, welcome to the BUS_MAP_RESOURCE(9) page from the Kernel Developer's Manual — kernel-dev brain, group-chat delivery, no cap ✨

🌸 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, struct resource *r,
    struct resource_map_request *args, struct resource_map *map);

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

void
resource_init_map_request(struct resource_map_request *args);

🦋 DESCRIPTION 🦋

okay so these functions literally create or destroy a mapping of a previously activated resource. Mappings permit CPU access to the resource via the bus_space(9) API — that's the whole vibe 🔥

The arguments are as follows, bestie:

• dev — the device that owns the resource 💖
• r — a pointer to the struct resource returned by bus_alloc_resource(9)
• args — a set of optional properties to apply when creating a mapping. This argument can be set to NULL to request a mapping of the entire resource with the default properties ✨
• map — the resource mapping to create or destroy 🎀

🌈 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 that can be used for CPU access to the mapping. The structure also contains a r_vaddr member which contains the virtual address of the mapping if one exists 👑

The wrapper API for struct resource objects described in bus_activate_resource(9) can also be used with struct resource_map. For example, a pointer to a mapping object can be passed as the first argument to bus_read_4(). This wrapper API is preferred over using the r_bustag and r_bushandle members directly — highkey the move 💅

🧚 Optional Mapping Properties 🧚

The struct resource_map_request object passed in args can be used to specify optional properties of a mapping. The structure must be initialized by invoking resource_init_map_request(). Properties are then specified by setting one or more of these members:

• offset, length — these two members specify a region of the resource to map. By default a mapping is 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 💜

⭐ RETURN VALUES ⭐

Zero is returned on success, otherwise an error is returned. So yeah: 0 = slay, anything else = bestie, something went wrong 😭

🍓 EXAMPLES 🍓

This maps a PCI memory BAR with the write-combining memory attribute and reads the first 32-bit word:

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 these next, iykyk 📚✨

🎀 AUTHORS 🎀

This manual page was written by John Baldwin <jhb@FreeBSD.org>. Iconic behavior, honestly 👑

---

xoxo, your Debian baddie 💖 — this page is dated March 13, 2024, the footer source/version vibe is Debian, and the manual stamp is BUS_MAP_RESOURCE(9) ✨ periodt