1.\" $NetBSD: rasctl.2,v 1.12 2006/09/19 19:54:43 wiz Exp $ 2.\" 3.\" Copyright (c) 2002 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" This code is derived from software contributed to The NetBSD Foundation 7.\" by Gregory McGarry. 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 3. All advertising materials mentioning features or use of this software 18.\" must display the following acknowledgement: 19.\" This product includes software developed by the NetBSD 20.\" Foundation, Inc. and its contributors. 21.\" 4. Neither the name of The NetBSD Foundation nor the names of its 22.\" contributors may be used to endorse or promote products derived 23.\" from this software without specific prior written permission. 24.\" 25.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 26.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 27.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 28.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 29.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 30.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 31.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 32.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 33.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 34.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 35.\" POSSIBILITY OF SUCH DAMAGE. 36.\" 37.Dd September 19, 2006 38.Dt RASCTL 2 39.Os 40.Sh NAME 41.Nm rasctl 42.Nd restartable atomic sequences 43.Sh LIBRARY 44.Lb libc 45.Sh SYNOPSIS 46.In sys/types.h 47.In sys/ras.h 48.Ft int 49.Fn rasctl "void *addr" "size_t len" "int op" 50.Sh DESCRIPTION 51Restartable atomic sequences are code sequences which are guaranteed 52to execute without preemption. 53This property is assured by the kernel 54by re-executing a preempted sequence from the start. 55This functionality enables applications to build atomic sequences which, 56when executed to completion, will have executed atomically. 57Restartable atomic sequences are intended to be used on systems that 58do not have hardware support for low-overhead atomic primitives. 59.Pp 60The 61.Nm 62function manipulates a process's set of restartable atomic sequences. 63If a restartable atomic sequence is registered and the process is 64preempted within the range 65.Fa addr 66and 67.Fa addr Ns + Ns Fa len , 68then the process is resumed at 69.Fa addr . 70.Pp 71As the process execution can be rolled-back, the code in the sequence 72should have no side effects other than a final store at 73.Fa addr Ns + Ns Fa len Ns \-1 . 74The kernel does not guarantee that the sequences are successfully 75restartable. 76It assumes that the application knows what it is doing. 77Restartable atomic sequences should adhere to the following guidelines: 78.Pp 79.Bl -bullet -compact 80.It 81have a single entry point and a single exit point; 82.It 83not execute emulated instructions; and 84.It 85not invoke any functions or system calls. 86.El 87.Pp 88Restartable atomic sequences are inherited from the parent by the 89child during the 90.Xr fork 2 91operation. 92Restartable atomic sequences for a process are removed during 93.Xr exec 3 . 94.Pp 95The operations that can be applied to a restartable atomic sequence 96are specified by the 97.Fa op 98argument. 99Possible operations are: 100.Pp 101.Bl -tag -compact -width RAS_PURGE_ALLXXX 102.It Dv RAS_INSTALL 103Install this sequence. 104.It Dv RAS_PURGE 105Remove the specified registered sequence for this process. 106.It Dv RAS_PURGE_ALL 107Remove all registered sequences for this process. 108.El 109.Pp 110The 111.Dv RAS_PURGE 112and 113.Dv RAS_PURGE_ALL 114operations should be considered to have 115undefined behaviour if there are any other runnable threads in the 116address space which might be executing within the restartable atomic 117sequence(s) at the time of the purge. 118The caller must be responsible for ensuring that there is some form of 119coordination with other threads to prevent unexpected behaviour. 120.Pp 121To preserve the atomicity of sequences, the kernel attempts to protect 122the sequences from alteration by the 123.Xr ptrace 2 124facility. 125.Sh RETURN VALUES 126Upon successful completion, 127.Fn rasctl 128returns zero. 129Otherwise, \-1 is returned and 130.Va errno 131is set to indicate the error. 132.Sh ERRORS 133The 134.Nm 135function will fail if: 136.Bl -tag -width Er 137.It Bq Er EINVAL 138Invalid input was supplied, such as an invalid operation, an invalid 139address, or an invalid length. 140A process may have a finite number of 141atomic sequences that is defined at compile time. 142.It Bq Er EOPNOTSUPP 143Restartable atomic sequences are not supported by the kernel. 144.It Bq Er ESRCH 145Restartable atomic sequence not registered. 146.El 147.Sh SEE ALSO 148.Xr ptrace 2 149.\" .Xr lock 9 150.Sh HISTORY 151The 152.Nm 153functionality first appeared in 154.Nx 2.0 155based on a similar interface that appeared in Mach 2.5. 156.Sh CAVEATS 157Modern compilers reorder instruction sequences to optimize speed. 158The start address and size of a 159.Nm RAS 160need to be protected against this. 161One level of protection is created by compiler dependent instructions, 162abstracted from user level code via the following macros: 163.Bl -tag -width RAS_START(name) 164.It Dv RAS_DECL(name) 165Declares the start and end labels used internally by the 166other macros to mark a 167.Nm RAS . 168The name uniquely identifies the 169.Nm RAS . 170.It Dv RAS_START(name) 171Marks the start of the code. 172Each restart returns to the instruction following this macro. 173.It Dv RAS_END(name) 174Marks the end of the restartable code. 175.It Dv RAS_ADDR(name) 176Returns the start address of a 177.Nm RAS 178and is used to create the first argument to 179.Nm . 180.It Dv RAS_SIZE(name) 181Returns the size of a 182.Nm RAS 183and is used as second argument to 184.Nm . 185.El 186Recent versions of 187.Xr gcc 1 188require the 189.Fl fno-reorder-blocks 190flag to prevent blocks of code wrapped with 191.Dv RAS_START Ns / Ns Dv RAS_END 192being moved outside these labels. 193