bus_map_resource

[John Baldwin]

Yet another extension I've long wanted to make to new-bus is to split out the
part of bus_activate_resource() that establishes a valid mapping for use with
bus_space_* (or the bus_* wrappers) from activating / detactivating. In
particular, making a resource "active" is orthogonal to having a mapping (e.g.
for a PCI BAR, a resource is "active" if the appropriate IO or mem decoding
bit is set in the device's command register. Whether or not the CPU has a
valid mapping for that range doesn't matter).

Secondly, there is a need to be able to specify optional parameters of
mappings. Some drivers may wish to only map a portion of a resource instead
of all of it (e.g. the AGP driver wishes to only map the first page of the
aperture instead of all of the aperture to avoid wasting a lot of KVA on 32-
bit systems). Some drivers may wish to map a memory resource with non-default
memory attributes (e.g. WC).

I have a strawman with an implementation on x86 to permit this.

In this model, a new RF_UNMAPPED flag is added that asks
bus_activate_resource() to not setup the implicit mapping in 'struct
resource'. Instead, a driver requests explicit mappings via
bus_map_resource() and is responsible for calling bus_unmap_resource() to tear
them down. A driver should allocate a 'struct resource_map' for each mapping
(probably by putting it in its softc) and then passing a pointer to that
object to both routines. This structure's members are named so that you can
use the bus_* convenience API on it the same way you can with 'struct
resource' for the implicit mapping.

bus_map_resource() accepts an optional 'args' argument that defines optional
properties of the mapping request. A driver can request a mapping of a subset
of a resource or a specific memory attribute. The 'args' argument is defined
as a structure headed by a size similar to the scheme Konstantin recently used
for make_dev_s().

One use case for this is that I'd like to fix the NEW_PCIB bits in the PCI-PCI
bridge driver to request a mapping in the subset of the resource on the
"parent" bus for the mapping window used by a resource for a child device
instead of passing up that child resource directly to the nexus. The idea is
that any bus driver that creates its own rman and resources should not be
passing those resources up to any of its parents.

Another use case that would benefit from this are bridges that do address
translations (such as the ThunderX Host-PCI bridge driver recently committed).
It can allocate a resource from its parent representing the "parent" side of
its resource window and request mappings for regions of that window
corresponding to child resources when creating mappings of child resources.

What I'd like feedback on now is the API. If we decide to go forward I would
also like help fixing bus drivers to use this.

Some sample code for mapping a resource that uses a WC mapping:

struct foo_softc {
...
struct resource *sc_regs_res;
struct resource_map sc_regs;
...
};

foo_attach(device_t dev)
{
struct resource_map_request args;
...

sc->sc_regs_res = bus_alloc_resource(dev, ..., RF_ACTIVE |
RF_UNMAPPED);
resource_init_map_request(&args, sizeof(args));
args.memattr = VM_MEMATTR_WRITE_COMBINING;
error = bus_map_resource(dev, SYS_RES_MEMORY, sc->regs_res,
&args, &sc->sc_regs);
...
}

foo_something(struct foo_softc *sc)
{
x = bus_read_4(&sc->sc_regs, MY_CSR);
}

foo_detach(device_t dev)
{

bus_unmap_resource(dev, SYS_RES_MEMORY, sc->regs_res, &sc->sc_regs);
bus_release_resource(dev, SYS_RES_MEMORY, rman_get_rid(sc->regs_res),
sc->regs_res);
}

There is a review with the current WIP code that includes the API and an
implementation for x86. It does not yet have manual page updates.

https://reviews.freebsd.org/D5237