document the various bus_space_*_stream_? functions...

1 files changed, 299 insertions, 5 deletions

diff --git a/share/man/man9/bus_space.9 b/share/man/man9/bus_space.9
index c51a6f8700d1..7f224491af06 100644
--- a/share/man/man9/bus_space.9
+++ b/share/man/man9/bus_space.9
@@ -68,6 +68,10 @@
 .Nm bus_space_copy_region_2 ,
 .Nm bus_space_copy_region_4 ,
 .Nm bus_space_copy_region_8 ,
+.Nm bus_space_copy_region_stream_1 ,
+.Nm bus_space_copy_region_stream_2 ,
+.Nm bus_space_copy_region_stream_4 ,
+.Nm bus_space_copy_region_stream_8 ,
 .Nm bus_space_free ,
 .Nm bus_space_map ,
 .Nm bus_space_read_1 ,
@@ -78,20 +82,40 @@
 .Nm bus_space_read_multi_2 ,
 .Nm bus_space_read_multi_4 ,
 .Nm bus_space_read_multi_8 ,
+.Nm bus_space_read_multi_stream_1 ,
+.Nm bus_space_read_multi_stream_2 ,
+.Nm bus_space_read_multi_stream_4 ,
+.Nm bus_space_read_multi_stream_8 ,
 .Nm bus_space_read_region_1 ,
 .Nm bus_space_read_region_2 ,
 .Nm bus_space_read_region_4 ,
 .Nm bus_space_read_region_8 ,
+.Nm bus_space_read_region_stream_1 ,
+.Nm bus_space_read_region_stream_2 ,
+.Nm bus_space_read_region_stream_4 ,
+.Nm bus_space_read_region_stream_8 ,
+.Nm bus_space_read_stream_1 ,
+.Nm bus_space_read_stream_2 ,
+.Nm bus_space_read_stream_4 ,
+.Nm bus_space_read_stream_8 ,
+.Nm bus_space_set_multi_1 ,
+.Nm bus_space_set_multi_2 ,
+.Nm bus_space_set_multi_4 ,
+.Nm bus_space_set_multi_8 ,
+.Nm bus_space_set_multi_stream_1 ,
+.Nm bus_space_set_multi_stream_2 ,
+.Nm bus_space_set_multi_stream_4 ,
+.Nm bus_space_set_multi_stream_8 ,
 .Nm bus_space_set_region_1 ,
 .Nm bus_space_set_region_2 ,
 .Nm bus_space_set_region_4 ,
 .Nm bus_space_set_region_8 ,
+.Nm bus_space_set_region_stream_1 ,
+.Nm bus_space_set_region_stream_2 ,
+.Nm bus_space_set_region_stream_4 ,
+.Nm bus_space_set_region_stream_8 ,
 .Nm bus_space_subregion ,
 .Nm bus_space_unmap ,
-.Nm bus_space_set_multi_1 ,
-.Nm bus_space_set_multi_2 ,
-.Nm bus_space_set_multi_4 ,
-.Nm bus_space_set_multi_8 ,
 .Nm bus_space_write_1 ,
 .Nm bus_space_write_2 ,
 .Nm bus_space_write_4 ,
@@ -100,10 +124,22 @@
 .Nm bus_space_write_multi_2 ,
 .Nm bus_space_write_multi_4 ,
 .Nm bus_space_write_multi_8 ,
+.Nm bus_space_write_multi_stream_1 ,
+.Nm bus_space_write_multi_stream_2 ,
+.Nm bus_space_write_multi_stream_4 ,
+.Nm bus_space_write_multi_stream_8 ,
 .Nm bus_space_write_region_1 ,
 .Nm bus_space_write_region_2 ,
 .Nm bus_space_write_region_4 ,
-.Nm bus_space_write_region_8
+.Nm bus_space_write_region_8 ,
+.Nm bus_space_write_region_stream_1 ,
+.Nm bus_space_write_region_stream_2 ,
+.Nm bus_space_write_region_stream_4 ,
+.Nm bus_space_write_region_stream_8 ,
+.Nm bus_space_write_stream_1 ,
+.Nm bus_space_write_stream_2 ,
+.Nm bus_space_write_stream_4 ,
+.Nm bus_space_write_stream_8
 .Nd "bus space manipulation functions"
 .Sh SYNOPSIS
 .In machine/bus.h
@@ -147,6 +183,22 @@
 .Fo bus_space_read_8
 .Fa "bus_space_tag_t space" "bus_space_handle_t handle" "bus_size_t offset"
 .Fc
+.Ft u_int8_t
+.Fo bus_space_read_stream_1
+.Fa "bus_space_tag_t space" "bus_space_handle_t handle" "bus_size_t offset"
+.Fc
+.Ft u_int16_t
+.Fo bus_space_read_stream_2
+.Fa "bus_space_tag_t space" "bus_space_handle_t handle" "bus_size_t offset"
+.Fc
+.Ft u_int32_t
+.Fo bus_space_read_stream_4
+.Fa "bus_space_tag_t space" "bus_space_handle_t handle" "bus_size_t offset"
+.Fc
+.Ft u_int64_t
+.Fo bus_space_read_stream_8
+.Fa "bus_space_tag_t space" "bus_space_handle_t handle" "bus_size_t offset"
+.Fc
 .Ft void
 .Fo bus_space_write_1
 .Fa "bus_space_tag_t space" "bus_space_handle_t handle"
@@ -168,6 +220,26 @@
 .Fa "bus_size_t offset" "u_int64_t value"
 .Fc
 .Ft void
+.Fo bus_space_write_stream_1
+.Fa "bus_space_tag_t space" "bus_space_handle_t handle"
+.Fa "bus_size_t offset" "u_int8_t value"
+.Fc
+.Ft void
+.Fo bus_space_write_stream_2
+.Fa "bus_space_tag_t space" "bus_space_handle_t handle"
+.Fa "bus_size_t offset" "u_int16_t value"
+.Fc
+.Ft void
+.Fo bus_space_write_stream_4
+.Fa "bus_space_tag_t space" "bus_space_handle_t handle"
+.Fa "bus_size_t offset" "u_int32_t value"
+.Fc
+.Ft void
+.Fo bus_space_write_stream_8
+.Fa "bus_space_tag_t space" "bus_space_handle_t handle"
+.Fa "bus_size_t offset" "u_int64_t value"
+.Fc
+.Ft void
 .Fo bus_space_barrier
 .Fa "bus_space_tag_t space" "bus_space_handle_t handle"
 .Fa "bus_size_t offset" "bus_size_t length" "int flags"
@@ -197,6 +269,30 @@
 .Fa "bus_size_t count"
 .Fc
 .Ft void
+.Fo bus_space_read_region_stream_1
+.Fa "bus_space_tag_t space"
+.Fa "bus_space_handle_t handle" "bus_size_t offset" "u_int8_t *datap"
+.Fa "bus_size_t count"
+.Fc
+.Ft void
+.Fo bus_space_read_region_stream_2
+.Fa "bus_space_tag_t space"
+.Fa "bus_space_handle_t handle" "bus_size_t offset" "u_int16_t *datap"
+.Fa "bus_size_t count"
+.Fc
+.Ft void
+.Fo bus_space_read_region_stream_4
+.Fa "bus_space_tag_t space"
+.Fa "bus_space_handle_t handle" "bus_size_t offset" "u_int32_t *datap"
+.Fa "bus_size_t count"
+.Fc
+.Ft void
+.Fo bus_space_read_region_stream_8
+.Fa "bus_space_tag_t space"
+.Fa "bus_space_handle_t handle" "bus_size_t offset" "u_int64_t *datap"
+.Fa "bus_size_t count"
+.Fc
+.Ft void
 .Fo bus_space_write_region_1
 .Fa "bus_space_tag_t space"
 .Fa "bus_space_handle_t handle" "bus_size_t offset" "u_int8_t *datap"
@@ -221,6 +317,30 @@
 .Fa "bus_size_t count"
 .Fc
 .Ft void
+.Fo bus_space_write_region_stream_1
+.Fa "bus_space_tag_t space"
+.Fa "bus_space_handle_t handle" "bus_size_t offset" "u_int8_t *datap"
+.Fa "bus_size_t count"
+.Fc
+.Ft void
+.Fo bus_space_write_region_stream_2
+.Fa "bus_space_tag_t space"
+.Fa "bus_space_handle_t handle" "bus_size_t offset" "u_int16_t *datap"
+.Fa "bus_size_t count"
+.Fc
+.Ft void
+.Fo bus_space_write_region_stream_4
+.Fa "bus_space_tag_t space"
+.Fa "bus_space_handle_t handle" "bus_size_t offset" "u_int32_t *datap"
+.Fa "bus_size_t count"
+.Fc
+.Ft void
+.Fo bus_space_write_region_stream_8
+.Fa "bus_space_tag_t space"
+.Fa "bus_space_handle_t handle" "bus_size_t offset" "u_int64_t *datap"
+.Fa "bus_size_t count"
+.Fc
+.Ft void
 .Fo bus_space_copy_region_1
 .Fa "bus_space_tag_t space"
 .Fa "bus_space_handle_t srchandle" "bus_size_t srcoffset"
@@ -245,6 +365,30 @@
 .Fa "bus_space_handle_t dsthandle" "bus_size_t dstoffset" "bus_size_t count"
 .Fc
 .Ft void
+.Fo bus_space_copy_region_stream_1
+.Fa "bus_space_tag_t space"
+.Fa "bus_space_handle_t srchandle" "bus_size_t srcoffset"
+.Fa "bus_space_handle_t dsthandle" "bus_size_t dstoffset" "bus_size_t count"
+.Fc
+.Ft void
+.Fo bus_space_copy_region_stream_2
+.Fa "bus_space_tag_t space"
+.Fa "bus_space_handle_t srchandle" "bus_size_t srcoffset"
+.Fa "bus_space_handle_t dsthandle" "bus_size_t dstoffset" "bus_size_t count"
+.Fc
+.Ft void
+.Fo bus_space_copy_region_stream_4
+.Fa "bus_space_tag_t space"
+.Fa "bus_space_handle_t srchandle" "bus_size_t srcoffset"
+.Fa "bus_space_handle_t dsthandle" "bus_size_t dstoffset" "bus_size_t count"
+.Fc
+.Ft void
+.Fo bus_space_copy_region_stream_8
+.Fa "bus_space_tag_t space"
+.Fa "bus_space_handle_t srchandle" "bus_size_t srcoffset"
+.Fa "bus_space_handle_t dsthandle" "bus_size_t dstoffset" "bus_size_t count"
+.Fc
+.Ft void
 .Fo bus_space_set_region_1
 .Fa "bus_space_tag_t space"
 .Fa "bus_space_handle_t handle" "bus_size_t offset" "u_int8_t value"
@@ -269,6 +413,30 @@
 .Fa "bus_size_t count"
 .Fc
 .Ft void
+.Fo bus_space_set_region_stream_1
+.Fa "bus_space_tag_t space"
+.Fa "bus_space_handle_t handle" "bus_size_t offset" "u_int8_t value"
+.Fa "bus_size_t count"
+.Fc
+.Ft void
+.Fo bus_space_set_region_stream_2
+.Fa "bus_space_tag_t space"
+.Fa "bus_space_handle_t handle" "bus_size_t offset" "u_int16_t value"
+.Fa "bus_size_t count"
+.Fc
+.Ft void
+.Fo bus_space_set_region_stream_4
+.Fa "bus_space_tag_t space"
+.Fa "bus_space_handle_t handle" "bus_size_t offset" "u_int32_t value"
+.Fa "bus_size_t count"
+.Fc
+.Ft void
+.Fo bus_space_set_region_stream_8
+.Fa "bus_space_tag_t space"
+.Fa "bus_space_handle_t handle" "bus_size_t offset" "u_int64_t value"
+.Fa "bus_size_t count"
+.Fc
+.Ft void
 .Fo bus_space_read_multi_1
 .Fa "bus_space_tag_t space"
 .Fa "bus_space_handle_t handle" "bus_size_t offset" "u_int8_t *datap"
@@ -293,6 +461,30 @@
 .Fa "bus_size_t count"
 .Fc
 .Ft void
+.Fo bus_space_read_multi_stream_1
+.Fa "bus_space_tag_t space"
+.Fa "bus_space_handle_t handle" "bus_size_t offset" "u_int8_t *datap"
+.Fa "bus_size_t count"
+.Fc
+.Ft void
+.Fo bus_space_read_multi_stream_2
+.Fa "bus_space_tag_t space"
+.Fa "bus_space_handle_t handle" "bus_size_t offset" "u_int16_t *datap"
+.Fa "bus_size_t count"
+.Fc
+.Ft void
+.Fo bus_space_read_multi_stream_4
+.Fa "bus_space_tag_t space"
+.Fa "bus_space_handle_t handle" "bus_size_t offset" "u_int32_t *datap"
+.Fa "bus_size_t count"
+.Fc
+.Ft void
+.Fo bus_space_read_multi_stream_8
+.Fa "bus_space_tag_t space"
+.Fa "bus_space_handle_t handle" "bus_size_t offset" "u_int64_t *datap"
+.Fa "bus_size_t count"
+.Fc
+.Ft void
 .Fo bus_space_write_multi_1
 .Fa "bus_space_tag_t space"
 .Fa "bus_space_handle_t handle" "bus_size_t offset" "u_int8_t *datap"
@@ -317,6 +509,30 @@
 .Fa "bus_size_t count"
 .Fc
 .Ft void
+.Fo bus_space_write_multi_stream_1
+.Fa "bus_space_tag_t space"
+.Fa "bus_space_handle_t handle" "bus_size_t offset" "u_int8_t *datap"
+.Fa "bus_size_t count"
+.Fc
+.Ft void
+.Fo bus_space_write_multi_stream_2
+.Fa "bus_space_tag_t space"
+.Fa "bus_space_handle_t handle" "bus_size_t offset" "u_int16_t *datap"
+.Fa "bus_size_t count"
+.Fc
+.Ft void
+.Fo bus_space_write_multi_stream_4
+.Fa "bus_space_tag_t space"
+.Fa "bus_space_handle_t handle" "bus_size_t offset" "u_int32_t *datap"
+.Fa "bus_size_t count"
+.Fc
+.Ft void
+.Fo bus_space_write_multi_stream_8
+.Fa "bus_space_tag_t space"
+.Fa "bus_space_handle_t handle" "bus_size_t offset" "u_int64_t *datap"
+.Fa "bus_size_t count"
+.Fc
+.Ft void
 .Fo bus_space_set_multi_1
 .Fa "bus_space_tag_t space"
 .Fa "bus_space_handle_t handle" "bus_size_t offset" "u_int8_t value"
@@ -340,6 +556,30 @@
 .Fa "bus_space_handle_t handle" "bus_size_t offset" "u_int64_t value"
 .Fa "bus_size_t count"
 .Fc
+.Ft void
+.Fo bus_space_set_multi_stream_1
+.Fa "bus_space_tag_t space"
+.Fa "bus_space_handle_t handle" "bus_size_t offset" "u_int8_t value"
+.Fa "bus_size_t count"
+.Fc
+.Ft void
+.Fo bus_space_set_multi_stream_2
+.Fa "bus_space_tag_t space"
+.Fa "bus_space_handle_t handle" "bus_size_t offset" "u_int16_t value"
+.Fa "bus_size_t count"
+.Fc
+.Ft void
+.Fo bus_space_set_multi_stream_4
+.Fa "bus_space_tag_t space"
+.Fa "bus_space_handle_t handle" "bus_size_t offset" "u_int32_t value"
+.Fa "bus_size_t count"
+.Fc
+.Ft void
+.Fo bus_space_set_multi_stream_8
+.Fa "bus_space_tag_t space"
+.Fa "bus_space_handle_t handle" "bus_size_t offset" "u_int64_t value"
+.Fa "bus_size_t count"
+.Fc
 .Sh DESCRIPTION
 The
 .Nm
@@ -1356,6 +1596,60 @@ If they would fail (e.g.\& because of an
 argument error), that indicates a software bug which should cause a
 panic.
 In that case, they will never return.
+.Sh STREAM FUNCTIONS
+Most of the
+.Nm
+functions imply a host byte-order and a bus byte-order and take care of
+any translation for the caller.
+In some cases, however, hardware may map a FIFO or some other memory region
+for which the caller may want to use multi-word, yet untranslated access.
+Access to these types of memory regions should be with the
+.Fn bus_space_*_stream_N
+functions.
+.Pp
+.Bl -ohang -compact
+.Nm bus_space_set_multi_stream_1 ,
+.Nm bus_space_set_region_stream_1 ,
+.It Fn bus_space_copy_region_1 "space" "handle" "srcoffset" "dsthandle" "dstoffset" "count"
+.It Fn bus_space_copy_region_2 "space" "handle" "srcoffset" "dsthandle" "dstoffset" "count"
+.It Fn bus_space_copy_region_4 "space" "handle" "srcoffset" "dsthandle" "dstoffset" "count"
+.It Fn bus_space_copy_region_8 "space" "handle" "srcoffset" "dsthandle" "dstoffset" "count"
+.It Fn bus_space_read_stream_1 "space" "handle" "offset"
+.It Fn bus_space_read_stream_2 "space" "handle" "offset"
+.It Fn bus_space_read_stream_4 "space" "handle" "offset"
+.It Fn bus_space_read_stream_8 "space" "handle" "offset"
+.It Fn bus_space_read_multi_stream_1 "space" "handle" "offset" "datap" "count"
+.It Fn bus_space_read_multi_stream_2 "space" "handle" "offset" "datap" "count"
+.It Fn bus_space_read_multi_stream_4 "space" "handle" "offset" "datap" "count"
+.It Fn bus_space_read_multi_stream_8 "space" "handle" "offset" "datap" "count"
+.It Fn bus_space_read_region_stream_1 "space" "handle" "offset" "datap" "count"
+.It Fn bus_space_read_region_stream_2 "space" "handle" "offset" "datap" "count"
+.It Fn bus_space_read_region_stream_4 "space" "handle" "offset" "datap" "count"
+.It Fn bus_space_read_region_stream_8 "space" "handle" "offset" "datap" "count"
+.It Fn bus_space_set_multi_1 "space" "handle" "offset" "value" "count"
+.It Fn bus_space_set_multi_2 "space" "handle" "offset" "value" "count"
+.It Fn bus_space_set_multi_4 "space" "handle" "offset" "value" "count"
+.It Fn bus_space_set_multi_8 "space" "handle" "offset" "value" "count"
+.It Fn bus_space_set_region_1 "space" "handle" "offset" "value" "count"
+.It Fn bus_space_set_region_2 "space" "handle" "offset" "value" "count"
+.It Fn bus_space_set_region_4 "space" "handle" "offset" "value" "count"
+.It Fn bus_space_set_region_8 "space" "handle" "offset" "value" "count"
+.It Fn bus_space_write_stream_1 "space" "handle" "offset" "value"
+.It Fn bus_space_write_stream_2 "space" "handle" "offset" "value"
+.It Fn bus_space_write_stream_4 "space" "handle" "offset" "value"
+.It Fn bus_space_write_stream_8 "space" "handle" "offset" "value"
+.It Fn bus_space_write_multi_stream_1 "space" "handle" "offset" "datap" "count"
+.It Fn bus_space_write_multi_stream_2 "space" "handle" "offset" "datap" "count"
+.It Fn bus_space_write_multi_stream_4 "space" "handle" "offset" "datap" "count"
+.It Fn bus_space_write_multi_stream_8 "space" "handle" "offset" "datap" "count"
+.It Fn bus_space_write_region_stream_1 "space" "handle" "offset" "datap" "count"
+.It Fn bus_space_write_region_stream_2 "space" "handle" "offset" "datap" "count"
+.It Fn bus_space_write_region_stream_4 "space" "handle" "offset" "datap" "count"
+.It Fn bus_space_write_region_stream_8 "space" "handle" "offset" "datap" "count"
+.El
+.Pp
+These functions are defined just as their non-stream counterparts,
+except that they provide no byte-order translation.
 .Sh COMPATIBILITY
 The current
 .Nx