1.\" $NetBSD: rasctl.2,v 1.6 2002/10/23 09:44:37 jdolecek 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 August 12, 2002 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.Fd #include \*[Lt]sys/types.h\*[Gt] 47.Fd #include \*[Lt]sys/ras.h\*[Gt] 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 RAS_INSTALL 103Install this sequence. 104.It RAS_PURGE 105Remove the specified registered sequences for this process. 106.It RAS_PURGE_ALL 107Remove all registers sequences for this process. 108.El 109.Pp 110The RAS_PURGE and RAS_PURGE_ALL operations should be considered to have 111undefined behaviour if there are any other runnable threads in the 112address space which might be executing within the restartable atomic 113sequence(s) at the time of the purge. 114The caller must be responsible for ensuring that there is some form of 115coordination with other threads to prevent unexpected behaviour. 116.Pp 117To preserve the atomicity of sequences, the kernel attempts to protect 118the sequences from alteration by the 119.Xr ptrace 2 120facility. 121.Sh RETURN VALUES 122Upon successful completion, 123.Fn rasctl 124returns zero. 125Otherwise, \-1 is returned and 126.Va errno 127is set to indicate the error. 128.Sh ERRORS 129The 130.Nm 131function will fail if: 132.Bl -tag -width Er 133.It Bq Er EINVAL 134Invalid input was supplied, such as an invalid operation, an invalid 135address, or an invalid length. 136A process may have a finite number of 137atomic sequences that is defined at compile time. 138.It Bq Er EOPNOTSUPP 139Restartable atomic sequences are not supported by the kernel. 140.It Bq Er ESRCH 141Restartable atomic sequence not registered. 142.El 143.Sh SEE ALSO 144.Xr ptrace 2 145.\" .Xr lock 9 146.Sh HISTORY 147The 148.Nm 149functionality first appeared in 150.\" NEXTRELEASE 151.Nx 2.0 152based on a similar interface that appeared in Mach 2.5. 153