summaryrefslogtreecommitdiffstats
path: root/share
diff options
context:
space:
mode:
Diffstat (limited to 'share')
-rw-r--r--share/man/man9/Makefile5
-rw-r--r--share/man/man9/bus_activate_resource.911
-rw-r--r--share/man/man9/bus_alloc_resource.96
-rw-r--r--share/man/man9/bus_map_resource.9167
-rw-r--r--share/man/man9/rman.931
5 files changed, 217 insertions, 3 deletions
diff --git a/share/man/man9/Makefile b/share/man/man9/Makefile
index 3d4cab2..355a17d 100644
--- a/share/man/man9/Makefile
+++ b/share/man/man9/Makefile
@@ -44,6 +44,7 @@ MAN= accept_filter.9 \
bus_generic_shutdown.9 \
BUS_GET_CPUS.9 \
bus_get_resource.9 \
+ bus_map_resource.9 \
BUS_NEW_PASS.9 \
BUS_PRINT_CHILD.9 \
BUS_READ_IVAR.9 \
@@ -504,6 +505,8 @@ MLINKS+=bus_dma.9 busdma.9 \
bus_dma.9 bus_dma_tag_destroy.9
MLINKS+=bus_generic_read_ivar.9 bus_generic_write_ivar.9
MLINKS+=BUS_GET_CPUS.9 bus_get_cpus.9
+MLINKS+=bus_map_resource.9 bus_unmap_resource.9 \
+ bus_map_resource.9 resource_init_map_request.9
MLINKS+=BUS_READ_IVAR.9 BUS_WRITE_IVAR.9
MLINKS+=BUS_SETUP_INTR.9 bus_setup_intr.9 \
BUS_SETUP_INTR.9 BUS_TEARDOWN_INTR.9 \
@@ -1381,6 +1384,7 @@ MLINKS+=rman.9 rman_activate_resource.9 \
rman.9 rman_get_device.9 \
rman.9 rman_get_end.9 \
rman.9 rman_get_flags.9 \
+ rman.9 rman_get_mapping.9 \
rman.9 rman_get_rid.9 \
rman.9 rman_get_size.9 \
rman.9 rman_get_start.9 \
@@ -1396,6 +1400,7 @@ MLINKS+=rman.9 rman_activate_resource.9 \
rman.9 rman_reserve_resource_bound.9 \
rman.9 rman_set_bushandle.9 \
rman.9 rman_set_bustag.9 \
+ rman.9 rman_set_mapping.9 \
rman.9 rman_set_rid.9 \
rman.9 rman_set_virtual.9
MLINKS+=rmlock.9 rm_assert.9 \
diff --git a/share/man/man9/bus_activate_resource.9 b/share/man/man9/bus_activate_resource.9
index f7664e6..144ae07 100644
--- a/share/man/man9/bus_activate_resource.9
+++ b/share/man/man9/bus_activate_resource.9
@@ -28,7 +28,7 @@
.\"
.\" $FreeBSD$
.\"
-.Dd May 10, 2016
+.Dd May 20, 2016
.Dt BUS_ACTIVATE_RESOURCE 9
.Os
.Sh NAME
@@ -106,6 +106,14 @@ If the mapping is associated with a virtual address,
the virtual address can be retrieved via
.Xr rman_get_virtual 9 .
.Pp
+This implicit mapping can be disabled by passing the
+.Dv RF_UNMAPPED
+flag to
+.Xr bus_alloc_resource 9 .
+A driver may use this if it wishes to allocate its own mappings of a resource
+using
+.Xr bus_map_resource 9 .
+.Pp
A wrapper API for
.Xr bus_space 9
is also provided that accepts the associated resource as the first argument
@@ -133,6 +141,7 @@ resource:
Zero is returned on success, otherwise an error is returned.
.Sh SEE ALSO
.Xr bus_alloc_resource 9 ,
+.Xr bus_map_resource 9 ,
.Xr bus_space 9 ,
.Xr device 9 ,
.Xr driver 9
diff --git a/share/man/man9/bus_alloc_resource.9 b/share/man/man9/bus_alloc_resource.9
index ccb7117..cdc6e21 100644
--- a/share/man/man9/bus_alloc_resource.9
+++ b/share/man/man9/bus_alloc_resource.9
@@ -28,7 +28,7 @@
.\"
.\" $FreeBSD$
.\"
-.Dd April 28, 2016
+.Dd May 20, 2016
.Dt BUS_ALLOC_RESOURCE 9
.Os
.Sh NAME
@@ -166,6 +166,9 @@ For example,
cannot share IRQs while
.Xr cardbus 4
can.
+.It Dv RF_UNMAPPED
+do not establish implicit mapping when activated via
+.Xr bus_activate_resource 9 .
.El
.El
.Sh RETURN VALUES
@@ -193,6 +196,7 @@ should be saved in the softc of the device after these calls.
.Sh SEE ALSO
.Xr bus_activate_resource 9 ,
.Xr bus_adjust_resource 9 ,
+.Xr bus_map_resource 9 ,
.Xr bus_release_resource 9 ,
.Xr device 9 ,
.Xr driver 9
diff --git a/share/man/man9/bus_map_resource.9 b/share/man/man9/bus_map_resource.9
new file mode 100644
index 0000000..c8ca9a1
--- /dev/null
+++ b/share/man/man9/bus_map_resource.9
@@ -0,0 +1,167 @@
+.\" -*- nroff -*-
+.\"
+.\" Copyright (c) 2016 John H. Baldwin <jhb@FreeBSD.org>
+.\" All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\" notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\" notice, this list of conditions and the following disclaimer in the
+.\" documentation and/or other materials provided with the distribution.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
+.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
+.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+.\" SUCH DAMAGE.
+.\"
+.\" $FreeBSD$
+.\"
+.Dd May 20, 2016
+.Dt BUS_MAP_RESOURCE 9
+.Os
+.Sh NAME
+.Nm bus_map_resource , bus_unmap_resource , resource_init_map_request
+.Nd map or unmap an active resource
+.Sh SYNOPSIS
+.In sys/param.h
+.In sys/bus.h
+.Pp
+.In machine/bus.h
+.In sys/rman.h
+.In machine/resource.h
+.Ft int
+.Fo bus_map_resource
+.Fa "device_t dev" "int type" "struct resource *r"
+.Fa "struct resource_map_request *args" "struct resource_map *map"
+.Fc
+.Ft int
+.Fo bus_unmap_resource
+.Fa "device_t dev" "int type" "struct resource *r" "struct resource_map *map"
+.Fc
+.Ft void
+.Fn resource_init_map_request "struct resource_map_request *args"
+.Sh DESCRIPTION
+These functions create or destroy a mapping of a previously activated
+resource.
+Mappings permit CPU access to the resource via the
+.Xr bus_space 9
+API.
+.Pp
+The arguments are as follows:
+.Bl -tag -width indent
+.It Fa dev
+The device that owns the resource.
+.It Fa type
+The type of resource to map.
+It is one of:
+.Pp
+.Bl -tag -width ".Dv SYS_RES_MEMORY" -compact
+.It Dv SYS_RES_IOPORT
+for I/O ports
+.It Dv SYS_RES_MEMORY
+for I/O memory
+.El
+.It Fa r
+A pointer to the
+.Vt "struct resource"
+returned by
+.Xr bus_alloc_resource 9 .
+.It Fa args
+A set of optional properties to apply when creating a mapping.
+This argument can be set to
+.Dv NULL
+to request a mapping of the entire resource with the default properties.
+.It Fa map
+The resource mapping to create or destroy.
+.El
+.Ss Resource Mappings
+Resource mappings are described by a
+.Vt "struct resource_map"
+object.
+This structure contains a
+.Xr bus_space 9
+tag and handle in the
+.Va r_bustag
+and
+.Va r_bushandle
+members that can be used for CPU access to the mapping.
+The structure also contains a
+.Va r_vaddr
+member which contains the virtual address of the mapping if one exists.
+.Pp
+The wrapper API for
+.Vt "struct resource"
+objects described in
+.Xr bus_activate_resource 9
+can also be used with
+.Vt "struct resource_map" .
+For example,
+a pointer to a mapping object can be passed as the first argument to
+.Fn bus_read_4 .
+This wrapper API is preferred over using the
+.Va r_bustag
+and
+.Va r_bushandle
+members directly.
+.Ss Optional Mapping Properties
+The
+.Vt "struct resource_map_request"
+object passed in
+.Fa args
+can be used to specify optional properties of a mapping.
+The structure must be initialized by invoking
+.Fn resource_init_map_request .
+Properties are then specified by setting one or more of these members:
+.Bl -tag -width indent
+.It Va offset , length
+These two members specify a region of the resource to map.
+By default a mapping is created for the entire resource.
+The
+.Va offset
+is relative to the start of the resource.
+.It Va memattr
+Specifies a memory attribute to use when mapping the resource.
+By default memory mappings use the
+.Dv VM_MEMATTR_UNCACHEABLE
+attribute.
+.El
+.Sh EXAMPLES
+This maps a PCI memory BAR with the write-combining memory attribute and
+reads the first 32-bit word:
+.Bd -literal
+ 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);
+.Ed
+.Pp
+.Sh RETURN VALUES
+Zero is returned on success, otherwise an error is returned.
+.Sh SEE ALSO
+.Xr bus_activate_resource 9 ,
+.Xr bus_alloc_resource 9 ,
+.Xr bus_space 9 ,
+.Xr device 9 ,
+.Xr driver 9
+.Sh AUTHORS
+This manual page was written by
+.An John Baldwin Aq Mt jhb@FreeBSD.org .
diff --git a/share/man/man9/rman.9 b/share/man/man9/rman.9
index 9b9e84f..6da8321 100644
--- a/share/man/man9/rman.9
+++ b/share/man/man9/rman.9
@@ -25,7 +25,7 @@
.\"
.\" $FreeBSD$
.\"
-.Dd May 19, 2016
+.Dd May 20, 2016
.Dt RMAN 9
.Os
.Sh NAME
@@ -49,6 +49,8 @@
.Nm rman_get_device ,
.Nm rman_get_size ,
.Nm rman_get_flags ,
+.Nm rman_set_mapping ,
+.Nm rman_get_mapping ,
.Nm rman_set_virtual ,
.Nm rman_get_virtual ,
.Nm rman_set_bustag ,
@@ -106,6 +108,10 @@
.Ft u_int
.Fn rman_get_flags "struct resource *r"
.Ft void
+.Fn rman_set_mapping "struct resource *r" "struct resource_map *map"
+.Ft void
+.Fn rman_get_mapping "struct resource *r" "struct resource_map *map"
+.Ft void
.Fn rman_set_virtual "struct resource *r" "void *v"
.Ft "void *"
.Fn rman_get_virtual "struct resource *r"
@@ -140,6 +146,7 @@ represented by a 16-bit flag register, as follows.
#define RF_SHAREABLE 0x0004 /* resource permits contemporaneous sharing */
#define RF_FIRSTSHARE 0x0020 /* first in sharing list */
#define RF_PREFETCHABLE 0x0040 /* resource is prefetchable */
+#define RF_UNMAPPED 0x0100 /* don't map resource when activating */
.Ed
.Pp
Bits 15:10 of the flag register are used to represent the desired alignment
@@ -424,6 +431,26 @@ The
function can be used to retrieve the KVA once set.
.Pp
The
+.Fn rman_set_mapping
+function is used to associate a resource mapping with a resource
+.Fa r .
+The mapping must cover the entire resource.
+Setting a mapping sets the associated
+.Xr bus_space 9
+handle and tag for
+.Fa r
+as well as the kernel virtual address if the mapping contains one.
+These individual values can be retrieved via
+.Fn rman_get_bushandle ,
+.Fn rman_get_bustag ,
+and
+.Fn rman_get_virtual .
+.Pp
+The
+.Fn rman_get_mapping
+function can be used to retrieve the associated resource mapping once set.
+.Pp
+The
.Fn rman_set_rid
function associates a resource identifier with a resource
.Fa r .
@@ -439,7 +466,9 @@ function returns a pointer to the device which reserved the resource
.Xr bus_activate_resource 9 ,
.Xr bus_adjust_resource 9 ,
.Xr bus_alloc_resource 9 ,
+.Xr bus_map_resource 9 ,
.Xr bus_release_resource 9 ,
+.Xr bus_space 9 ,
.Xr bus_set_resource 9 ,
.Xr mutex 9
.Sh AUTHORS
OpenPOWER on IntegriCloud