Document bus_space_mmap(9) from NetBSD with some tweaks by jmc@.

2 files changed, 42 insertions, 3 deletions

diff --git a/share/man/man9/Makefile b/share/man/man9/Makefile
index ba413cd7987..fb025c6a86d 100644
--- a/share/man/man9/Makefile
+++ b/share/man/man9/Makefile
@@ -1,4 +1,4 @@
-#	$OpenBSD: Makefile,v 1.173 2012/09/27 16:15:00 jmc Exp $
+#	$OpenBSD: Makefile,v 1.174 2012/12/10 13:03:54 mpi Exp $
 #	$NetBSD: Makefile,v 1.4 1996/01/09 03:23:01 thorpej Exp $
 
 #	Makefile for section 9 (kernel function and variable) manual pages.
@@ -59,6 +59,7 @@ MLINKS+=bus_space.9 bus_space_alloc.9 bus_space.9 bus_space_barrier.9 \
 	bus_space.9 bus_space_copy_1.9 bus_space.9 bus_space_copy_2.9 \
 	bus_space.9 bus_space_copy_4.9 bus_space.9 bus_space_copy_8.9 \
 	bus_space.9 bus_space_free.9 bus_space.9 bus_space_map.9 \
+	bus_space.9 bus_space_mmap.9 \
 	bus_space.9 bus_space_read_1.9 bus_space.9 bus_space_read_2.9 \
 	bus_space.9 bus_space_read_4.9 bus_space.9 bus_space_read_8.9 \
 	bus_space.9 bus_space_read_multi_1.9 \
diff --git a/share/man/man9/bus_space.9 b/share/man/man9/bus_space.9
index bbc2d871e56..5e8b1a4d1fe 100644
--- a/share/man/man9/bus_space.9
+++ b/share/man/man9/bus_space.9
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: bus_space.9,v 1.20 2009/07/26 18:48:53 miod Exp $
+.\"	$OpenBSD: bus_space.9,v 1.21 2012/12/10 13:03:54 mpi Exp $
 .\" $NetBSD: bus_space.9,v 1.15 2000/08/09 03:11:00 tv Exp $
 .\"
 .\" Copyright (c) 1997 The NetBSD Foundation, Inc.
@@ -28,7 +28,7 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 .\" POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: July 26 2009 $
+.Dd $Mdocdate: December 10 2012 $
 .Dt BUS_SPACE 9
 .Os
 .Sh NAME
@@ -41,6 +41,7 @@
 .Nm bus_space_copy_8 ,
 .Nm bus_space_free ,
 .Nm bus_space_map ,
+.Nm bus_space_mmap ,
 .Nm bus_space_read_1 ,
 .Nm bus_space_read_2 ,
 .Nm bus_space_read_4 ,
@@ -123,6 +124,9 @@
 "bus_size_t size"
 .Ft void *
 .Fn bus_space_vaddr "bus_space_tag_t space" "bus_space_handle_t handle"
+.Ft paddr_t
+.Fn bus_space_mmap "bus_space_tag_t space" "bus_addr_t addr" "off_t off" \
+"int prot" "int flags"
 .Ft u_int8_t
 .Fn bus_space_read_1 "bus_space_tag_t space" "bus_space_handle_t handle" \
 "bus_size_t offset"
@@ -684,6 +688,40 @@ If mapped with the
 flag, the
 .Fn bus_space_barrier
 method must be used to force a particular access order.
+.Pp
+.It Fn bus_space_mmap "tag" "addr" "off" "prot" "flags"
+.Pp
+This method is used to provide support for memory mapping bus space
+into user applications.
+If an address space is addressable via volatile pointer dereferences,
+.Fn bus_space_mmap
+will return the physical address (possibly encoded as a machine-dependent
+cookie) of the bus space indicated by
+.Fa addr
+and
+.Fa off .
+.Fa addr
+is the base address of the device or device region, and
+.Fa off
+is the offset into that region that is being requested.
+If the region cannot be mapped (either the address does not exist,
+or the constraints cannot be met),
+.Fn bus_space_mmap
+returns \-1 to indicate failure.
+.Pp
+Note that it is not necessary that the region being requested by a
+.Fn bus_space_mmap
+call be mapped into a
+.Fa bus_space_handle_t .
+.Pp
+.Fn bus_space_mmap
+is called once per
+.Dv PAGE_SIZE
+page in the range.
+The
+.Fa prot
+argument indicates the memory protection requested by the user application
+for the range.
 .El
 .Sh ALLOCATING AND FREEING BUS SPACE
 Some devices require or allow bus space to be allocated by the operating