1.\" $NetBSD: ucas.9,v 1.7 2021/10/04 20:25:20 andvar Exp $ 2.\" 3.\" Copyright (c) 2019 Jason R. Thorpe. 4.\" Copyright (c) 2011 YAMAMOTO Takashi, 5.\" All rights reserved. 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 10.\" 1. Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" 2. Redistributions in binary form must reproduce the above copyright 13.\" notice, this list of conditions and the following disclaimer in the 14.\" documentation and/or other materials provided with the distribution. 15.\" 16.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 17.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 18.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 19.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 20.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 21.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 22.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 23.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 24.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 25.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 26.\" SUCH DAMAGE. 27.\" 28.\" ------------------------------------------------------------ 29.Dd March 31, 2019 30.Dt UCAS 9 31.Os 32.\" ------------------------------------------------------------ 33.Sh NAME 34.Nm ucas 35.Nd atomic memory operations on user-space address 36.\" ------------------------------------------------------------ 37.Sh SYNOPSIS 38.In sys/systm.h 39.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 40.Ft int 41.Fn ucas_ptr \ 42"volatile void *uptr" "void *old" "void *new" "void *retp" 43.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 44.Ft int 45.Fn ucas_int \ 46"volatile int *uptr" "int old" "int new" "int *retp" 47.\" ------------------------------------------------------------ 48.Sh DESCRIPTION 49These functions provide compare-and-swap (CAS) functionality on 50user-space address. 51.Pp 52Except that they can be safely used for the kernel to access user-space 53address, they are semantically equivalents of 54.Xr atomic_cas 3 . 55.Bl -tag -width uptr 56.It Fa uptr 57The pointer to the variable. 58This should be a user-space pointer. 59.It Fa old 60The value to compare with the variable. 61.It Fa new 62The value to store to the variable. 63.It Fa retp 64The pointer to the memory to store the old value of the variable. 65.El 66.\" ------------------------------------------------------------ 67.Sh IMPLEMENTATION NOTES 68The 69.Nm ucas 70functions are implemented in machine-independent code, but rely on 71machine-dependent code to implement optimized primitives, if possible. 72.Pp 73The basic 74.Nm ucas 75primitives have the following signatures and are considered private to 76the implementation and are not to be called by consumers of the 77.Nm ucas 78API: 79.Bl -tag -width _ucas_32 80.It Ft int Fn _ucas_32 \ 81"volatile uint32_t *uptr" "uint32_t old" "uint32_t new" "uint32_t *retp" ; 82.It Ft int Fn _ucas_64 \ 83"volatile uint64_t *uptr" "uint64_t old" "uint64_t new" "uint64_t *retp" ; 84.El 85.Pp 86If a platform is able to provide a CAS operation that meets the following 87criteria, it should define 88.Dv __HAVE_UCAS_FULL 89in 90.In machine/types.h 91and provide complete machine-dependent implementations of 92.Fn _ucas_32 93.Po 94and 95.Fn _ucas_64 , 96if an 97.Dv _LP64 98platform 99.Pc : 100.Pp 101.Bl -hyphen -compact 102.It 103Can be implemented using either native compare-and-swap operations or 104load-locked / store-conditional code sequences. 105.It 106Can be used on uniprocessor and multiprocessor systems. 107.It 108Can operate across the kernel-userspace boundary. 109.El 110.Pp 111If 112.Dv __HAVE_UCAS_FULL 113is not defined, then a generic implementation will be provided by 114machine-dependent code. 115This generic implementation is suitable for uniprocessor and multiprocessor 116systems, but works on a 117.Dq least-common denominator 118principle. 119In particular, kernel preemption is disabled during the critical section 120.Po 121which is comprised of 122.Xr ufetch 9 123and 124.Xr ustore 9 125operations 126.Pc , 127and the multiprocessor implementation synchronizes with other CPUs using 128interprocessor interrupts. 129.Pp 130If a particular platform wishes to use the generic implementation on 131uniprocessors but an optimized implementation on multiprocessors, the 132platform should define 133.Dv __HAVE_UCAS_MP 134in 135.In machine/types.h 136and provide 137.Fn _ucas_32_mp 138.Po 139and 140.Fn _ucas_64_mp , 141if an 142.Dv _LP64 143platform 144.Pc . 145.\" ------------------------------------------------------------ 146.Sh RETURN VALUES 147On success, these functions return 0. 148In that case, the caller can consult the value returned via 149.Fa retp 150to check the result of the CAS operation. 151Otherwise, these functions return an appropriate 152.Xr errno 9 153error code, typically 154.Dv EFAULT . 155.\" ------------------------------------------------------------ 156.Sh SEE ALSO 157.Xr atomic_cas 3 , 158.Xr intro 9 159.\" ------------------------------------------------------------ 160.Sh BUGS 161Conceptually, the 162.Fa retp 163argument of 164.Fn ucas_ptr 165would be of 166.Dv void ** . 167The current prototype is a compromise for usability. 168