[src/trunk]: src/share/man/man9 Describe bus_space_tag_create(9) and bus_spac...

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

details:   https://anonhg.NetBSD.org/src/rev/2f9bc118f706
branches:  trunk
changeset: 767005:2f9bc118f706
user:      dyoung <dyoung%NetBSD.org@localhost>
date:      Wed Jul 06 21:36:16 2011 +0000

description:
Describe bus_space_tag_create(9) and bus_space_tag_destroy(9) for
implementing bus spaces in MI code.

(This documentation may be several hours ahead of the implementation,
sorry.)

diffstat:

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

diffs (134 lines):

diff -r b3e05d9dbcf5 -r 2f9bc118f706 share/man/man9/bus_space.9
--- a/share/man/man9/bus_space.9        Wed Jul 06 20:47:05 2011 +0000
+++ b/share/man/man9/bus_space.9        Wed Jul 06 21:36:16 2011 +0000
@@ -1,4 +1,4 @@
-.\" $NetBSD: bus_space.9,v 1.43 2011/07/06 18:27:31 dyoung Exp $
+.\" $NetBSD: bus_space.9,v 1.44 2011/07/06 21:36:16 dyoung Exp $
 .\"
 .\" Copyright (c) 1997 The NetBSD Foundation, Inc.
 .\" All rights reserved.
@@ -87,6 +87,8 @@
 .Nm bus_space_set_region_4 ,
 .Nm bus_space_set_region_8 ,
 .Nm bus_space_subregion ,
+.Nm bus_space_tag_create ,
+.Nm bus_space_tag_destroy ,
 .Nm bus_space_unmap ,
 .Nm bus_space_vaddr ,
 .Nm bus_space_write_1 ,
@@ -166,6 +168,12 @@
 .Fn bus_space_mmap "bus_space_tag_t space" "bus_addr_t addr" "off_t off" \
 "int prot" "int flags"
 .Ft int
+.Fn bus_space_tag_create "bus_space_tag_t obst" "uint64_t present" \
+    "uint64_t extpresent" "const struct bus_space_overrides *ov" "void *ctx" \
+    "bus_space_tag_t *bstp"
+.Ft void
+.Fn bus_space_tag_destroy "bus_space_tag_t bst"
+.Ft int
 .Fn bus_space_peek_1 "bus_space_tag_t space" "bus_space_handle_t handle" \
 "bus_size_t offset" "uint8_t *datap"
 .Ft int
@@ -1801,6 +1809,102 @@
 .Pp
 These functions are defined just as their non-stream counterparts,
 except that they provide no byte-order translation.
+.Sh IMPLEMENTING BUS SPACES IN MACHINE-INDEPENDENT CODE
+.Bl -ohang -compact
+.It Fn bus_space_tag_create "obst" "present" "extpresent" "ov" "ctx" "bstp"
+Create a copy of the tag
+.Fa obst
+at
+.Fa *bstp .
+Except for the behavior
+overridden by
+.Fa ov ,
+.Fa *bstp
+inherits the behavior of
+.Fa obst
+under
+.Nm
+calls.
+.Pp
+.Fa ov
+contains function pointers corresponding to
+.Nm
+routines.
+Each function pointer has a corresponding bit in
+.Fa present
+or
+.Fa extpresent ,
+and if that bit is 1, the function pointer overrides the corresponding
+.Nm
+call for the new tag.
+Any combination of these bits may be set in
+.Fa present :
+.Pp
+.Bl -tag -width BUS_SPACE_OVERRIDE_RESERVE_SUBREGION -compact
+.It Dv BUS_SPACE_OVERRIDE_MAP
+.It Dv BUS_SPACE_OVERRIDE_UNMAP
+.It Dv BUS_SPACE_OVERRIDE_ALLOC
+.It Dv BUS_SPACE_OVERRIDE_FREE
+.It Dv BUS_SPACE_OVERRIDE_RESERVE
+.It Dv BUS_SPACE_OVERRIDE_RELEASE
+.It Dv BUS_SPACE_OVERRIDE_RESERVATION_MAP
+.It Dv BUS_SPACE_OVERRIDE_RESERVATION_UNMAP
+.It Dv BUS_SPACE_OVERRIDE_RESERVE_SUBREGION
+.El
+.Pp
+.Fn bus_space_tag_create
+does not copy
+.Fa ov .
+After a new tag is created by
+.Fn bus_space_tag_create ,
+.Fa ov
+must not be destroyed until after the
+tag is destroyed by
+.Fn bus_space_tag_destroy .
+.Pp
+The first argument of every override-function is a
+.Vt "void *" ,
+and
+.Fa ctx
+is passed in that argument.
+.Pp
+Return 0 if the call succeeds.
+Return
+.Dv EOPNOTSUPP
+if the architecture does not support overrides.
+Return
+.Dv EINVAL
+if
+.Fa present
+is 0, if
+.Fa ov
+is
+.Dv NULL ,
+or if
+.Fa present
+indicates that an override is present, but the corresponding override
+in
+.Fa ov
+is
+.Dv NULL .
+.Pp
+If the call does not succeed,
+.Fa *bstp
+is undefined.
+.It Fn bus_space_tag_destroy "bst"
+Destroy a tag,
+.Fa bst ,
+created by a prior call to
+.Fn bus_space_tag_create .
+If
+.Fa bst
+was not created by
+.Fn bus_space_tag_create ,
+results are undefined.
+If
+.Fa bst
+was already destroyed, results are undefined.
+.El
 .Sh EXPECTED CHANGES TO THE BUS_SPACE FUNCTIONS
 The definition of the
 .Nm