[src/trunk]: src/share/man/man9 Document the bus_space_peek_N() and bus_space...

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

details:   https://anonhg.NetBSD.org/src/rev/22caa84941ba
branches:  trunk
changeset: 499571:22caa84941ba
user:      scw <scw%NetBSD.org@localhost>
date:      Thu Nov 23 22:56:53 2000 +0000

description:
Document the bus_space_peek_N() and bus_space_poke_N() families
of functions, as proposed on tech-kern.

These provide a way to safely access bus space without crashing
the system if nothing responds on the bus.  c.f. `badaddr()'.

diffstat:

 share/man/man9/bus_space.9 |  134 ++++++++++++++++++++++++++++++++++++++++++++-
 1 files changed, 133 insertions(+), 1 deletions(-)

diffs (162 lines):

diff -r d0b13b8e796b -r 22caa84941ba share/man/man9/bus_space.9
--- a/share/man/man9/bus_space.9        Thu Nov 23 21:58:54 2000 +0000
+++ b/share/man/man9/bus_space.9        Thu Nov 23 22:56:53 2000 +0000
@@ -1,4 +1,4 @@
-.\" $NetBSD: bus_space.9,v 1.15 2000/08/09 03:11:00 tv Exp $
+.\" $NetBSD: bus_space.9,v 1.16 2000/11/23 22:56:53 scw Exp $
 .\"
 .\" Copyright (c) 1997 The NetBSD Foundation, Inc.
 .\" All rights reserved.
@@ -46,6 +46,14 @@
 .Nm bus_space_copy_region_8 ,
 .Nm bus_space_free ,
 .Nm bus_space_map ,
+.Nm bus_space_peek_1 ,
+.Nm bus_space_peek_2 ,
+.Nm bus_space_peek_4 ,
+.Nm bus_space_peek_8 ,
+.Nm bus_space_poke_1 ,
+.Nm bus_space_poke_2 ,
+.Nm bus_space_poke_4 ,
+.Nm bus_space_poke_8 ,
 .Nm bus_space_read_1 ,
 .Nm bus_space_read_2 ,
 .Nm bus_space_read_4 ,
@@ -124,6 +132,30 @@
 "bus_size_t size"
 .Ft void *
 .Fn bus_space_vaddr "bus_space_tag_t space" "bus_space_handle_t handle"
+.Ft int
+.Fn bus_space_peek_1 "bus_space_tag_t space" "bus_space_handle_t handle" \
+"bus_size_t offset" "u_int8_t *datap"
+.Ft int
+.Fn bus_space_peek_2 "bus_space_tag_t space" "bus_space_handle_t handle" \
+"bus_size_t offset" "u_int16_t *datap"
+.Ft int
+.Fn bus_space_peek_4 "bus_space_tag_t space" "bus_space_handle_t handle" \
+"bus_size_t offset" "u_int32_t *datap"
+.Ft int
+.Fn bus_space_peek_8 "bus_space_tag_t space" "bus_space_handle_t handle" \
+"bus_size_t offset" "u_int64_t *datap"
+.Ft int
+.Fn bus_space_poke_1 "bus_space_tag_t space" "bus_space_handle_t handle" \
+"bus_size_t offset" "u_int8_t data"
+.Ft int
+.Fn bus_space_poke_2 "bus_space_tag_t space" "bus_space_handle_t handle" \
+"bus_size_t offset" "u_int16_t data"
+.Ft int
+.Fn bus_space_poke_4 "bus_space_tag_t space" "bus_space_handle_t handle" \
+"bus_size_t offset" "u_int32_t data"
+.Ft int
+.Fn bus_space_poke_8 "bus_space_tag_t space" "bus_space_handle_t handle" \
+"bus_size_t offset" "u_int64_t data"
 .Ft u_int8_t
 .Fn bus_space_read_1 "bus_space_tag_t space" "bus_space_handle_t handle" \
 "bus_size_t offset"
@@ -854,6 +886,106 @@
 panic.  In that case, they will never return.
 .El
 .Pp
+
+
+.Sh PROBING BUS SPACE FOR HARDWARE WHICH MAY NOT RESPOND
+.Pp
+One problem with the
+.Fn bus_space_read_N
+and
+.Fn bus_space_write_N
+family of functions is that they provide no protection against
+exceptions which can occur when no physical hardware or
+device responds to the read or write cycles. In such a situation,
+the system typically would panic due to a kernel-mode bus error. The
+.Fn bus_space_peek_N
+and
+.Fn bus_space_poke_N
+family of functions provide a mechanism to handle these exceptions
+gracefully without the risk of crashing the system.
+.Pp
+As with
+.Fn bus_space_read_N
+and
+.Fn bus_space_write_N ,
+the peek and poke functions provide the ability to read and
+write 1, 2, 4, and 8 byte data items on busses which support those
+access sizes. All of the constraints specified in the descriptions of
+the
+.Fn bus_space_read_N
+and
+.Fn bus_space_write_N
+functions also apply to
+.Fn bus_space_peek_N
+and
+.Fn bus_space_poke_N .
+.Pp
+In addition, explicit calls to the
+.Fn bus_space_barrier
+function are not required as the implementation will ensure all
+pending operations complete before the peek or poke operation starts.
+The implementation will also ensure that the peek or poke operations
+complete before returning.
+.Pp
+The return value indicates the outcome of the peek or poke operation.
+A return value of zero implies that a hardware device is
+responding to the operation at the specified offset in the bus space.
+A non-zero return value indicates that the kernel intercepted a
+hardware exception (e.g. bus error) when the peek or poke operation
+was attempted.
+Note that some busses are incapable of generating exceptions when
+non-existant hardware is accessed. In such cases, these functions
+will always return zero and the value of the data read by
+.Fn bus_space_peek_N
+will be unspecified.
+.Pp
+Finally, it should be noted that at this time the
+.Fn bus_space_peek_N
+and
+.Fn bus_space_poke_N
+functions are not re-entrant and should not, therefore, be used
+from within an interrupt service routine.
+This constraint may be removed at some point in the future.
+.Pp
+.Bl -ohang -compact
+.It Fn bus_space_peek_1 "space" "handle" "offset" "datap"
+.It Fn bus_space_peek_2 "space" "handle" "offset" "datap"
+.It Fn bus_space_peek_4 "space" "handle" "offset" "datap"
+.It Fn bus_space_peek_8 "space" "handle" "offset" "datap"
+.Pp
+The
+.Fn bus_space_peek_N
+family of functions cautiously read a 1, 2, 4, or 8 byte data item from
+the offset specified by
+.Fa offset
+in the region specified by 
+.Fa handle
+of the bus space specified by 
+.Fa space .
+The data item read is stored in the location pointed to by
+.Fa datap .
+It is permissible for
+.Fa datap
+to be NULL, in which case the data item will be discared after being read.
+.Pp
+.It Fn bus_space_poke_1 "space" "handle" "offset" "value"
+.It Fn bus_space_poke_2 "space" "handle" "offset" "value"
+.It Fn bus_space_poke_4 "space" "handle" "offset" "value"
+.It Fn bus_space_poke_8 "space" "handle" "offset" "value"
+.Pp
+The
+.Fn bus_space_poke_N
+family of functions cautiously write a 1, 2, 4, or 8 byte data item
+specified by
+.Fa value
+to the offset specified by
+.Fa offset
+in the region specified by
+.Fa handle
+of the bus space specified by 
+.Fa space .
+.El
+.Pp
 .Sh BARRIERS
 .Pp
 In order to allow high-performance buffering implementations to avoid bus