[src/trunk]: src/share/man/man9 document ucas

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

details:   https://anonhg.NetBSD.org/src/rev/29815f4872a6
branches:  trunk
changeset: 770579:29815f4872a6
user:      yamt <yamt%NetBSD.org@localhost>
date:      Mon Oct 24 07:31:31 2011 +0000

description:
document ucas

diffstat:

 share/man/man9/Makefile |   4 +-
 share/man/man9/ucas.9   |  88 +++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 90 insertions(+), 2 deletions(-)

diffs (110 lines):

diff -r 212a382abafb -r 29815f4872a6 share/man/man9/Makefile
--- a/share/man/man9/Makefile   Mon Oct 24 07:30:29 2011 +0000
+++ b/share/man/man9/Makefile   Mon Oct 24 07:31:31 2011 +0000
@@ -1,4 +1,4 @@
-#       $NetBSD: Makefile,v 1.354 2011/10/06 05:23:41 jruoho Exp $
+#       $NetBSD: Makefile,v 1.355 2011/10/24 07:31:31 yamt Exp $
 
 #      Makefile for section 9 (kernel function and variable) manual pages.
 
@@ -50,7 +50,7 @@
        store.9 suspendsched.9 \
        sysctl.9 sysmon_envsys.9 sysmon_pswitch.9 sysmon_taskq.9 tc.9 \
        tcp_congctl.9 timecounter.9 time_second.9 todr.9 tvtohz.9 \
-       uiomove.9 ucom.9 userret.9 \
+       ucas.9 uiomove.9 ucom.9 userret.9 \
        vattr.9 veriexec.9 vcons.9 vfs.9 vfs_hooks.9 vfsops.9 vfssubr.9 \
        video.9 vme.9 \
        vnfileops.9 vnode.9 vnodeops.9 vnsubr.9 \
diff -r 212a382abafb -r 29815f4872a6 share/man/man9/ucas.9
--- /dev/null   Thu Jan 01 00:00:00 1970 +0000
+++ b/share/man/man9/ucas.9     Mon Oct 24 07:31:31 2011 +0000
@@ -0,0 +1,88 @@
+.\"    $NetBSD: ucas.9,v 1.1 2011/10/24 07:31:31 yamt Exp $
+.\"
+.\" Copyright (c)2011 YAMAMOTO Takashi,
+.\" All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
+.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
+.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+.\" SUCH DAMAGE.
+.\"
+.\" ------------------------------------------------------------
+.Dd October 24, 2011
+.Dt UCAS 9
+.Os
+.\" ------------------------------------------------------------
+.Sh NAME
+.Nm ucas
+.Nd atomic memory operations on user-space address
+.\" ------------------------------------------------------------
+.Sh SYNOPSIS
+.In sys/systm.h
+.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+.Ft int
+.Fn ucas_ptr \
+"volatile void *uptr" "void *old" "void *new" "void *retp"
+.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+.Ft int
+.Fn ucas_int \
+"volatile int *uptr" "int old" "int new" "int *retp"
+.\" ------------------------------------------------------------
+.Sh DESCRIPTION
+These functions provide compare-and-swap (CAS) functionality on
+user-space address.
+.Pp
+Except that they can be safely used for the kernel to access user-space
+address, they are semantically equivalents of
+.Xr atomic_cas 3 .
+.Pp
+.Bl -tag -width uptr
+.It Fa uptr
+The pointer to the variable.
+This should be a user-space pointer.
+.It Fa old
+The value to compare with the variable.
+.It Fa new
+The value to store to the variable.
+.It Fa retp
+The pointer to the memory to store the old value of the variable.
+.El
+.\" ------------------------------------------------------------
+.Sh RETURN VALUES
+On success, these functions return 0.
+In that case, the caller can consult the value returned via
+.Fa retp
+to check the result of the CAS operation.
+Otherwise, these functions return an appropriate
+.Xr errno 9
+error code, typically
+.Dv EFAULT .
+.\" ------------------------------------------------------------
+.Sh SEE ALSO
+.Xr intro 9 ,
+.Xr atomic_cas 3
+.\" ------------------------------------------------------------
+.Sh BUGS
+Conceptually, the
+.Fa retp
+argument of
+.Fn ucas_ptr
+would be of
+.Dv void ** .
+The current prototype is a compromise for usability.