Module Name: src
Committed By: uebayasi
Date: Thu Jul 29 04:44:34 UTC 2010
Modified Files:
src/share/man/man9 [uebayasi-xip]: bus_space.9
Log Message:
Document bus_space_physload(9), bus_space_physunload(9),
bus_space_physload_device(9), and bus_space_physunload_device(9).
To generate a diff of this commit:
cvs rdiff -u -r1.40 -r1.40.2.1 src/share/man/man9/bus_space.9
Please note that diffs are not public domain; they are subject to the
copyright notices on the relevant files.
Modified files:
Index: src/share/man/man9/bus_space.9
diff -u src/share/man/man9/bus_space.9:1.40 src/share/man/man9/bus_space.9:1.40.2.1
--- src/share/man/man9/bus_space.9:1.40 Fri Apr 16 20:05:37 2010
+++ src/share/man/man9/bus_space.9 Thu Jul 29 04:44:34 2010
@@ -1,4 +1,4 @@
-.\" $NetBSD: bus_space.9,v 1.40 2010/04/16 20:05:37 dyoung Exp $
+.\" $NetBSD: bus_space.9,v 1.40.2.1 2010/07/29 04:44:34 uebayasi Exp $
.\"
.\" Copyright (c) 1997 The NetBSD Foundation, Inc.
.\" All rights reserved.
@@ -27,7 +27,7 @@
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
.\" POSSIBILITY OF SUCH DAMAGE.
.\"
-.Dd April 16, 2010
+.Dd July 29, 2010
.Dt BUS_SPACE 9
.Os
.Sh NAME
@@ -45,6 +45,10 @@
.Nm bus_space_peek_2 ,
.Nm bus_space_peek_4 ,
.Nm bus_space_peek_8 ,
+.Nm bus_space_physload ,
+.Nm bus_space_physload_device ,
+.Nm bus_space_physunload ,
+.Nm bus_space_physunload_device ,
.Nm bus_space_poke_1 ,
.Nm bus_space_poke_2 ,
.Nm bus_space_poke_4 ,
@@ -144,6 +148,16 @@
.Ft int
.Fn bus_space_peek_8 "bus_space_tag_t space" "bus_space_handle_t handle" \
"bus_size_t offset" "uint64_t *datap"
+.Ft void *
+.Fn bus_space_physload "bus_space_tag_t space" "bus_addr_t addr" "bus_size_t size" \
+"int freelist"
+.Ft void
+.Fn bus_space_physunload "bus_space_tag_t space" "void *phys"
+.Ft void *
+.Fn bus_space_physload_device "bus_space_tag_t space" "bus_addr_t addr" "bus_size_t size" \
+"int prot" "int flags"
+.Ft void
+.Fn bus_space_physunload_device "bus_space_tag_t space" "void *phys"
.Ft int
.Fn bus_space_poke_1 "bus_space_tag_t space" "bus_space_handle_t handle" \
"bus_size_t offset" "uint8_t data"
@@ -732,7 +746,7 @@
.Fn bus_space_free
is called on a handle, all subregions of that handle become invalid.
.Pp
-.It Fn bus_space_vaddr "tag" "handle"
+.It Fn bus_space_vaddr "space" "handle"
.Pp
This method returns the kernel virtual address of a mapped bus space if and
only if it was mapped with the
@@ -745,7 +759,7 @@
.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"
+.It Fn bus_space_mmap "space" "addr" "off" "prot" "flags"
.Pp
This method is used to provide support for memory mapping bus space
into user applications.
@@ -783,6 +797,91 @@
.Fa prot
argument indicates the memory protection requested by the user application
for the range.
+.Pp
+.It Fn bus_space_physload "space" "addr" "size" "freelist"
+.Pp
+This method is used to register a bus space range as part of general purpose
+memory.
+The
+.Xr uvm 9
+internally allocates a single segment object,
+.Fa struct vm_physseg ,
+with per-page objects,
+.Fa struct vm_page ,
+to manage the corresponding physical address region indicated by
+.Fa addr
+and
+.Fa size .
+.Fa addr
+is the base address of the device memory region, and
+.Fa size
+is the size of that region.
+The added pages are queued in the freelist specified by
+.Fa freelist
+in the
+.Xr uvm 9 .
+.Pp
+If the registered memory is meant to be truely general purpose, users would
+want to add those pages to a pre-defined freelist.
+In other cases where device's memory needs special treatment, its platform has
+to define a dedicated freelist.
+The actual usage of such a special freelist and its pages is up to respective
+users.
+.Pp
+If successful,
+.Fn bus_space_physload
+returns an opaque handle to the allocated segment object.
+It returns NULL to indicate failure.
+.Pp
+.It Fn bus_space_physunload "space" "phys"
+.Pp
+This method frees the memory segment returned by
+.Fn bus_space_physload ,
+and specified by
+.Fa phys .
+This function will never fail.
+.Pp
+.It Fn bus_space_physload_device "space" "addr" "size" "prot" "flags"
+.Pp
+This method is used to register a bus space range as part of managed memory
+indicated by
+.Fa addr
+and
+.Fa size .
+.Fa addr
+is the base address of the device memory region, and
+.Fa size
+is the size of that region.
+.Fa prot
+is the device's capable access protection of the region, in cases where some
+devices allow read-only or write-only access.
+This information is referencial.
+.Fa flags
+is reserved for future use.
+.Pp
+Unlike
+.Fn bus_space_physload
+which registers pages as general purpose memory, this function only allocates
+a segment object and per-page objects.
+The registered pages can be accessed only by
+.Xr mmap 2
+interface from userland, or XIP, where pages are implicitly mapped into user
+address space by
+.Xr uvm 9
+and the vnode pager.
+.Pp
+If successful,
+.Fn bus_space_physload_device
+returns an opaque handle to the allocated segment object.
+It returns NULL to indicate failure.
+.Pp
+.It Fn bus_space_physunload_device "space" "phys"
+.Pp
+This method frees the memory segment returned by
+.Fn bus_space_physload_device ,
+and specified by
+.Fa phys .
+This function will never fail.
.El
.Sh ALLOCATING AND FREEING BUS SPACE
Some devices require or allow bus space to be allocated by the operating
