---
name: "bus_map_resource"
section: "9"
platform: "freebsd"
package: "base"
version: "16.0-CURRENT-20261027-61c70dc16a79"
release: "FreeBSD 16.0-CURRENT (2026-10-27)"
platforms: ["freebsd"]
url: "https://new.carta.tech/bus_map_resource"
---

# bus\_map\_resource(9)

map or unmap an active resource

## 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

These functions create or destroy a mapping of a previously activated resource. Mappings permit CPU access to the resource via the [bus\_space(9)](/bus_space/9.md) API.

The arguments are as follows:

- *dev*

  The device that owns the resource.

- *r*

  A pointer to the *struct resource* returned by [bus\_alloc\_resource(9)](/bus_alloc_resource/9.md).

- *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)](/bus_space/9.md) 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)](/bus_activate_resource/9.md) 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.

### 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.

## 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_activate_resource/9.md), [bus\_alloc\_resource(9)](/bus_alloc_resource/9.md), [bus\_space(9)](/bus_space/9.md), [device(9)](/device/9.md), [driver(9)](/driver/9.md)

## AUTHORS

This manual page was written by John Baldwin ⟨*jhb@FreeBSD.org*⟩.