[src/trunk]: src/share/man/man9 -document the BUS_SPACE_MAP_PREFETCHABLE flag...

[drochner <drochner%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/3bd12e69e82d
branches:  trunk
changeset: 485043:3bd12e69e82d
user:      drochner <drochner%NetBSD.org@localhost>
date:      Mon Apr 17 09:52:21 2000 +0000

description:
-document the BUS_SPACE_MAP_PREFETCHABLE flag introduced a while ago
-add a missing link: bus_space_vaddr() to get a pointer from a handle;
 needed to make the BUS_SPACE_MAP_LINEAR flag useful

diffstat:

 share/man/man9/bus_space.9 |  46 ++++++++++++++++++++++++++++++++++++++--------
 1 files changed, 38 insertions(+), 8 deletions(-)

diffs (106 lines):

diff -r 9512afb91e4d -r 3bd12e69e82d share/man/man9/bus_space.9
--- a/share/man/man9/bus_space.9        Mon Apr 17 09:21:59 2000 +0000
+++ b/share/man/man9/bus_space.9        Mon Apr 17 09:52:21 2000 +0000
@@ -1,4 +1,4 @@
-.\" $NetBSD: bus_space.9,v 1.10 1999/03/16 00:40:47 garbled Exp $
+.\" $NetBSD: bus_space.9,v 1.11 2000/04/17 09:52:21 drochner Exp $
 .\"
 .\" Copyright (c) 1997 The NetBSD Foundation, Inc.
 .\" All rights reserved.
@@ -64,6 +64,7 @@
 .Nm bus_space_set_region_8 ,
 .Nm bus_space_subregion ,
 .Nm bus_space_unmap ,
+.Nm bus_space_vaddr ,
 .Nm bus_space_write_1 ,
 .Nm bus_space_write_2 ,
 .Nm bus_space_write_4 ,
@@ -97,6 +98,8 @@
 .Ft void
 .Fn bus_space_free "bus_space_tag_t space" "bus_space_handle_t handle" \
 "bus_size_t size"
+.Ft void *
+.Fn bus_space_vaddr "bus_space_tag_t space" "bus_space_handle_t handle"
 .Ft u_int8_t
 .Fn bus_space_read_1 "bus_space_tag_t space" "bus_space_handle_t handle" \
 "bus_size_t offset"
@@ -424,17 +427,28 @@
 argument controls how the space is to be mapped.  Supported flags include:
 .Bl -tag -width BUS_SPACE_MAP_CACHEABLE -offset indent
 .It Dv BUS_SPACE_MAP_CACHEABLE
-Try to map the space so that accesses can be cached and/or
-prefetched by the system.  If this flag is not specified, the
-implementation should map the space so that it will not be cached or
-prefetched.
+Try to map the space so that accesses can be cached
+by the system cache. If this flag is not specified, the
+implementation should map the space so that it will not be cached.
+This mapping method will only be useful in very rare occasions.
 .Pp
 This flag must have a value of 1 on all implementations for backward
 compatibility.
+.It Dv BUS_SPACE_MAP_PREFETCHABLE
+Try to map the space so that accesses can be prefetched by the system,
+and writes can be buffered.
+This means, accesses should be side effect free (idempotent). The
+.Fn bus_space_barrier
+methods will flush the write buffer or force actual read accesses.
+If this flag is not specified, the
+implementation should map the space so that it will not be prefetched
+or delayed.
 .It Dv BUS_SPACE_MAP_LINEAR
 Try to map the space so that its contents can be accessed linearly via
 normal memory access methods (e.g. pointer dereferencing and structure
-accesses).
+accesses). The
+.Fn bus_space_vaddr
+method can be used to obtain the kernel virtual address of the mapped range.
 This is useful when software wants to do direct access to a memory
 device, e.g. a frame buffer.  If this flag is specified and linear
 mapping is not possible, the
@@ -442,6 +456,10 @@
 call should fail.  If this
 flag is not specified, the system may map the space in whatever way is
 most convenient.
+Use of this mapping method is not encouraged for normal device access;
+where linear access is not essential, use of the
+.Fn bus_space_read/write
+methods is strongly recommended.
 .El
 .Pp
 Not all combinations of flags make sense or are supported with all
@@ -451,13 +469,13 @@
 used on many systems' I/O port spaces, and on some systems
 .Dv BUS_SPACE_MAP_LINEAR
 without
-.Dv BUS_SPACE_MAP_CACHEABLE
+.Dv BUS_SPACE_MAP_PREFETCHABLE
 may never work.
 When the system hardware or firmware provides hints as to how spaces should be
 mapped (e.g. the PCI memory mapping registers' "prefetchable" bit), those
 hints should be followed for maximum compatibility.  On some systems,
 requesting a mapping that cannot be satisfied (e.g. requesting a
-non-cacheable mapping when the system can only provide a cacheable one)
+non-prefetchable mapping when the system can only provide a prefetchable one)
 will cause the request to fail.
 .Pp
 Some implementations may keep track of use of bus space for some or all
@@ -534,6 +552,18 @@
 or
 .Fn bus_space_free
 is called on a handle, all subregions of that handle become invalid.
+.Pp
+.It Fn bus_space_vaddr "tag" "handle"
+.Pp
+This method returns the kernel virtual address of a mapped bus space if and
+only if it was mapped with the
+.Dv BUS_SPACE_MAP_LINEAR
+flag. The range can be accessed by normal (volatile) pointer dereferences.
+If mapped with the
+.Dv BUS_SPACE_MAP_PREFETCHABLE
+flag, the
+.Fn bus_space_barrier
+method must be used to force a particular access order.
 .El
 .Pp
 .Sh ALLOCATING AND FREEING BUS SPACE