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.

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_args args;
             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(&args);
             args.memattr = VM_MEMATTR_WRITE_COMBINING;
             bus_map_resource(dev, SYS_RES_MEMORY, r, &args, &map);
             val = bus_read_4(&map, 0);

RETURN VALUES

     Zero is returned on success, otherwise an error is returned.

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 <jhb@FreeBSD.org>.