d/freebsd-skq
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Add some notes about the implicit resource mapping for activated resources.

Browse Source 
Specifically, mention that rman_get_bustag/handle/virtual are valid after
a resource is activated.  Also, mention the wrapper API that accepts a
struct resource instead of a bus tag and handle.
This commit is contained in:
jhb 2016-04-28 18:23:18 +00:00
parent eb165bdc54
commit 9021956875
1 changed files with 47 additions and 2 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

49
share/man/man9/bus_activate_resource.9
View File

@ -52,8 +52,12 @@
.Sh DESCRIPTION .Sh DESCRIPTION
These functions activate or deactivate a previously allocated resource. These functions activate or deactivate a previously allocated resource.
In general, resources must be activated before they can be accessed by In general, resources must be activated before they can be accessed by
the driver so that the bus driver can map the resource into the the driver.
devices space. Bus drivers may perform additional actions to ensure that the resource is
ready to be accessed.
For example,
the PCI bus driver enables memory decoding in a PCI device's command register
when activating a memory resource.
.Pp .Pp
The arguments are as follows: The arguments are as follows:
.Bl -tag -width indent .Bl -tag -width indent
@ -84,6 +88,47 @@ A pointer to the
returned by returned by
.Xr bus_alloc_resource 9 . .Xr bus_alloc_resource 9 .
.El .El
.Ss Resource Mapping
Resources which can be mapped for CPU access by a
.Xr bus_space
tag and handle will create a mapping of the entire resource when activated.
The tag and handle for this mapping are stored in
.Fa r
and can be retrieved via
.Xr rman_get_bustag 9
and
.Xr rman_get_bushandle 9 .
These can be used with the
.Xr bus_space 9
API to access device registers or memory described by
.Fa r .
If the mapping is associated with a virtual address,
the virtual address can be retrieved via
.Xr rman_get_virtual 9 .
.Pp
A wrapper API for
.Xr bus_space 9
is also provided that accepts the associated resource as the first argument
in place of the
.Xr bus_space 9
tag and handle.
The functions in this wrapper API are named similarly to the
.Xr bus_space 9
API except that
.Dq _space
is removed from their name.
For example,
.Fn bus_read_4
can be used in place of
.Fn bus_space_read_4 .
The wrapper API is preferred in new drivers.
.Pp
These two statements both read a 32-bit register at the start of a
resource:
.Bd -literal
bus_space_read_4(rman_get_bustag(res), rman_get_bushandle(res), 0);
bus_read_4(res, 0);
.Ed
.Sh RETURN VALUES .Sh RETURN VALUES
Zero is returned on success, otherwise an error is returned. Zero is returned on success, otherwise an error is returned.
.Sh SEE ALSO .Sh SEE ALSO