1*2fe8fb19SBen Gras.\" $NetBSD: rasctl.2,v 1.13 2008/04/29 21:06:28 scw Exp $ 2*2fe8fb19SBen Gras.\" 3*2fe8fb19SBen Gras.\" Copyright (c) 2002 The NetBSD Foundation, Inc. 4*2fe8fb19SBen Gras.\" All rights reserved. 5*2fe8fb19SBen Gras.\" 6*2fe8fb19SBen Gras.\" This code is derived from software contributed to The NetBSD Foundation 7*2fe8fb19SBen Gras.\" by Gregory McGarry. 8*2fe8fb19SBen Gras.\" 9*2fe8fb19SBen Gras.\" Redistribution and use in source and binary forms, with or without 10*2fe8fb19SBen Gras.\" modification, are permitted provided that the following conditions 11*2fe8fb19SBen Gras.\" are met: 12*2fe8fb19SBen Gras.\" 1. Redistributions of source code must retain the above copyright 13*2fe8fb19SBen Gras.\" notice, this list of conditions and the following disclaimer. 14*2fe8fb19SBen Gras.\" 2. Redistributions in binary form must reproduce the above copyright 15*2fe8fb19SBen Gras.\" notice, this list of conditions and the following disclaimer in the 16*2fe8fb19SBen Gras.\" documentation and/or other materials provided with the distribution. 17*2fe8fb19SBen Gras.\" 18*2fe8fb19SBen Gras.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 19*2fe8fb19SBen Gras.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 20*2fe8fb19SBen Gras.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 21*2fe8fb19SBen Gras.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 22*2fe8fb19SBen Gras.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 23*2fe8fb19SBen Gras.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 24*2fe8fb19SBen Gras.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 25*2fe8fb19SBen Gras.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 26*2fe8fb19SBen Gras.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 27*2fe8fb19SBen Gras.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 28*2fe8fb19SBen Gras.\" POSSIBILITY OF SUCH DAMAGE. 29*2fe8fb19SBen Gras.\" 30*2fe8fb19SBen Gras.Dd April 29, 2008 31*2fe8fb19SBen Gras.Dt RASCTL 2 32*2fe8fb19SBen Gras.Os 33*2fe8fb19SBen Gras.Sh NAME 34*2fe8fb19SBen Gras.Nm rasctl 35*2fe8fb19SBen Gras.Nd restartable atomic sequences 36*2fe8fb19SBen Gras.Sh LIBRARY 37*2fe8fb19SBen Gras.Lb libc 38*2fe8fb19SBen Gras.Sh SYNOPSIS 39*2fe8fb19SBen Gras.In sys/types.h 40*2fe8fb19SBen Gras.In sys/ras.h 41*2fe8fb19SBen Gras.Ft int 42*2fe8fb19SBen Gras.Fn rasctl "void *addr" "size_t len" "int op" 43*2fe8fb19SBen Gras.Sh DESCRIPTION 44*2fe8fb19SBen GrasRestartable atomic sequences are code sequences which are guaranteed 45*2fe8fb19SBen Grasto execute without preemption. 46*2fe8fb19SBen GrasThis property is assured by the kernel 47*2fe8fb19SBen Grasby re-executing a preempted sequence from the start. 48*2fe8fb19SBen GrasThis functionality enables applications to build atomic sequences which, 49*2fe8fb19SBen Graswhen executed to completion, will have executed atomically. 50*2fe8fb19SBen GrasRestartable atomic sequences are intended to be used on systems that 51*2fe8fb19SBen Grasdo not have hardware support for low-overhead atomic primitives. 52*2fe8fb19SBen Gras.Pp 53*2fe8fb19SBen GrasThe 54*2fe8fb19SBen Gras.Nm 55*2fe8fb19SBen Grasfunction manipulates a process's set of restartable atomic sequences. 56*2fe8fb19SBen GrasIf a restartable atomic sequence is registered and the process is 57*2fe8fb19SBen Graspreempted within the range 58*2fe8fb19SBen Gras.Fa addr 59*2fe8fb19SBen Grasand 60*2fe8fb19SBen Gras.Fa addr Ns + Ns Fa len , 61*2fe8fb19SBen Grasthen the process is resumed at 62*2fe8fb19SBen Gras.Fa addr . 63*2fe8fb19SBen Gras.Pp 64*2fe8fb19SBen GrasAs the process execution can be rolled-back, the code in the sequence 65*2fe8fb19SBen Grasshould have no side effects other than a final store at 66*2fe8fb19SBen Gras.Fa addr Ns + Ns Fa len Ns \-1 . 67*2fe8fb19SBen GrasThe kernel does not guarantee that the sequences are successfully 68*2fe8fb19SBen Grasrestartable. 69*2fe8fb19SBen GrasIt assumes that the application knows what it is doing. 70*2fe8fb19SBen GrasRestartable atomic sequences should adhere to the following guidelines: 71*2fe8fb19SBen Gras.Pp 72*2fe8fb19SBen Gras.Bl -bullet -compact 73*2fe8fb19SBen Gras.It 74*2fe8fb19SBen Grashave a single entry point and a single exit point; 75*2fe8fb19SBen Gras.It 76*2fe8fb19SBen Grasnot execute emulated instructions; and 77*2fe8fb19SBen Gras.It 78*2fe8fb19SBen Grasnot invoke any functions or system calls. 79*2fe8fb19SBen Gras.El 80*2fe8fb19SBen Gras.Pp 81*2fe8fb19SBen GrasRestartable atomic sequences are inherited from the parent by the 82*2fe8fb19SBen Graschild during the 83*2fe8fb19SBen Gras.Xr fork 2 84*2fe8fb19SBen Grasoperation. 85*2fe8fb19SBen GrasRestartable atomic sequences for a process are removed during 86*2fe8fb19SBen Gras.Xr exec 3 . 87*2fe8fb19SBen Gras.Pp 88*2fe8fb19SBen GrasThe operations that can be applied to a restartable atomic sequence 89*2fe8fb19SBen Grasare specified by the 90*2fe8fb19SBen Gras.Fa op 91*2fe8fb19SBen Grasargument. 92*2fe8fb19SBen GrasPossible operations are: 93*2fe8fb19SBen Gras.Pp 94*2fe8fb19SBen Gras.Bl -tag -compact -width RAS_PURGE_ALLXXX 95*2fe8fb19SBen Gras.It Dv RAS_INSTALL 96*2fe8fb19SBen GrasInstall this sequence. 97*2fe8fb19SBen Gras.It Dv RAS_PURGE 98*2fe8fb19SBen GrasRemove the specified registered sequence for this process. 99*2fe8fb19SBen Gras.It Dv RAS_PURGE_ALL 100*2fe8fb19SBen GrasRemove all registered sequences for this process. 101*2fe8fb19SBen Gras.El 102*2fe8fb19SBen Gras.Pp 103*2fe8fb19SBen GrasThe 104*2fe8fb19SBen Gras.Dv RAS_PURGE 105*2fe8fb19SBen Grasand 106*2fe8fb19SBen Gras.Dv RAS_PURGE_ALL 107*2fe8fb19SBen Grasoperations should be considered to have 108*2fe8fb19SBen Grasundefined behaviour if there are any other runnable threads in the 109*2fe8fb19SBen Grasaddress space which might be executing within the restartable atomic 110*2fe8fb19SBen Grassequence(s) at the time of the purge. 111*2fe8fb19SBen GrasThe caller must be responsible for ensuring that there is some form of 112*2fe8fb19SBen Grascoordination with other threads to prevent unexpected behaviour. 113*2fe8fb19SBen Gras.Pp 114*2fe8fb19SBen GrasTo preserve the atomicity of sequences, the kernel attempts to protect 115*2fe8fb19SBen Grasthe sequences from alteration by the 116*2fe8fb19SBen Gras.Xr ptrace 2 117*2fe8fb19SBen Grasfacility. 118*2fe8fb19SBen Gras.Sh RETURN VALUES 119*2fe8fb19SBen GrasUpon successful completion, 120*2fe8fb19SBen Gras.Fn rasctl 121*2fe8fb19SBen Grasreturns zero. 122*2fe8fb19SBen GrasOtherwise, \-1 is returned and 123*2fe8fb19SBen Gras.Va errno 124*2fe8fb19SBen Grasis set to indicate the error. 125*2fe8fb19SBen Gras.Sh ERRORS 126*2fe8fb19SBen GrasThe 127*2fe8fb19SBen Gras.Nm 128*2fe8fb19SBen Grasfunction will fail if: 129*2fe8fb19SBen Gras.Bl -tag -width Er 130*2fe8fb19SBen Gras.It Bq Er EINVAL 131*2fe8fb19SBen GrasInvalid input was supplied, such as an invalid operation, an invalid 132*2fe8fb19SBen Grasaddress, or an invalid length. 133*2fe8fb19SBen GrasA process may have a finite number of 134*2fe8fb19SBen Grasatomic sequences that is defined at compile time. 135*2fe8fb19SBen Gras.It Bq Er EOPNOTSUPP 136*2fe8fb19SBen GrasRestartable atomic sequences are not supported by the kernel. 137*2fe8fb19SBen Gras.It Bq Er ESRCH 138*2fe8fb19SBen GrasRestartable atomic sequence not registered. 139*2fe8fb19SBen Gras.El 140*2fe8fb19SBen Gras.Sh SEE ALSO 141*2fe8fb19SBen Gras.Xr ptrace 2 142*2fe8fb19SBen Gras.\" .Xr lock 9 143*2fe8fb19SBen Gras.Sh HISTORY 144*2fe8fb19SBen GrasThe 145*2fe8fb19SBen Gras.Nm 146*2fe8fb19SBen Grasfunctionality first appeared in 147*2fe8fb19SBen Gras.Nx 2.0 148*2fe8fb19SBen Grasbased on a similar interface that appeared in Mach 2.5. 149*2fe8fb19SBen Gras.Sh CAVEATS 150*2fe8fb19SBen GrasModern compilers reorder instruction sequences to optimize speed. 151*2fe8fb19SBen GrasThe start address and size of a 152*2fe8fb19SBen Gras.Nm RAS 153*2fe8fb19SBen Grasneed to be protected against this. 154*2fe8fb19SBen GrasOne level of protection is created by compiler dependent instructions, 155*2fe8fb19SBen Grasabstracted from user level code via the following macros: 156*2fe8fb19SBen Gras.Bl -tag -width RAS_START(name) 157*2fe8fb19SBen Gras.It Dv RAS_DECL(name) 158*2fe8fb19SBen GrasDeclares the start and end labels used internally by the 159*2fe8fb19SBen Grasother macros to mark a 160*2fe8fb19SBen Gras.Nm RAS . 161*2fe8fb19SBen GrasThe name uniquely identifies the 162*2fe8fb19SBen Gras.Nm RAS . 163*2fe8fb19SBen Gras.It Dv RAS_START(name) 164*2fe8fb19SBen GrasMarks the start of the code. 165*2fe8fb19SBen GrasEach restart returns to the instruction following this macro. 166*2fe8fb19SBen Gras.It Dv RAS_END(name) 167*2fe8fb19SBen GrasMarks the end of the restartable code. 168*2fe8fb19SBen Gras.It Dv RAS_ADDR(name) 169*2fe8fb19SBen GrasReturns the start address of a 170*2fe8fb19SBen Gras.Nm RAS 171*2fe8fb19SBen Grasand is used to create the first argument to 172*2fe8fb19SBen Gras.Nm . 173*2fe8fb19SBen Gras.It Dv RAS_SIZE(name) 174*2fe8fb19SBen GrasReturns the size of a 175*2fe8fb19SBen Gras.Nm RAS 176*2fe8fb19SBen Grasand is used as second argument to 177*2fe8fb19SBen Gras.Nm . 178*2fe8fb19SBen Gras.El 179*2fe8fb19SBen GrasRecent versions of 180*2fe8fb19SBen Gras.Xr gcc 1 181*2fe8fb19SBen Grasrequire the 182*2fe8fb19SBen Gras.Fl fno-reorder-blocks 183*2fe8fb19SBen Grasflag to prevent blocks of code wrapped with 184*2fe8fb19SBen Gras.Dv RAS_START Ns / Ns Dv RAS_END 185*2fe8fb19SBen Grasbeing moved outside these labels. 186*2fe8fb19SBen GrasHowever, be aware that this may not always be sufficient to prevent 187*2fe8fb19SBen Gras.Xr gcc 1 188*2fe8fb19SBen Grasfrom generating non-restartable code within the 189*2fe8fb19SBen Gras.Nm RAS 190*2fe8fb19SBen Grasdue to register clobbers. 191*2fe8fb19SBen GrasIt is, therefore, strongly recommended that restartable atomic sequences 192*2fe8fb19SBen Grasare coded in assembly. 193*2fe8fb19SBen Gras.Nm RAS 194*2fe8fb19SBen Grasblocks within assembly code can be specified by using the following macros: 195*2fe8fb19SBen Gras.Bl -tag -width RAS_START_ASM_HIDDEN(name) 196*2fe8fb19SBen Gras.It Dv RAS_START_ASM(name) 197*2fe8fb19SBen GrasSimilar to 198*2fe8fb19SBen Gras.Nm RAS_START 199*2fe8fb19SBen Grasbut for use in assembly source code. 200*2fe8fb19SBen Gras.It Dv RAS_END_ASM(name) 201*2fe8fb19SBen GrasSimilar to 202*2fe8fb19SBen Gras.Nm RAS_END 203*2fe8fb19SBen Grasbut for use in assembly source code. 204*2fe8fb19SBen Gras.It Dv RAS_START_ASM_HIDDEN(name) 205*2fe8fb19SBen GrasSimilar to 206*2fe8fb19SBen Gras.Nm RAS_START_ASM 207*2fe8fb19SBen Grasexcept that the symbol will not be placed in the dynamic symbol table. 208*2fe8fb19SBen Gras.It Dv RAS_END_ASM_HIDDEN(name) 209*2fe8fb19SBen GrasSimilar to 210*2fe8fb19SBen Gras.Nm RAS_END_ASM 211*2fe8fb19SBen Grasexcept that the symbol will not be placed in the dynamic symbol table. 212*2fe8fb19SBen Gras.El 213