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