BUS_MAP_RESOURCE(9) FreeBSD Kernel Developer's Manual BUS_MAP_RESOURCE(9)
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
These functions create or destroy a mapping of a previously activated
resource. Mappings permit CPU access to the resource via the
bus_space(9) API.
The arguments are as follows:
dev The device that owns the resource.
type The type of resource to map. It is one of:
SYS_RES_IOPORT for I/O ports
SYS_RES_MEMORY for I/O memory
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.
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_alloc_resource(9), bus_space(9), device(9),
driver(9)
AUTHORS
This manual page was written by John Baldwin <
[email protected]>.
FreeBSD 14.1-RELEASE-p8 February 5, 2018 FreeBSD 14.1-RELEASE-p8