1.\" $NetBSD: ras.9,v 1.2 2002/08/29 11:27:03 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 August 12, 2002 38.Dt RAS 9 39.Os 40.Sh NAME 41.Nm ras_lookup , 42.Nm ras_fork , 43.Nm ras_purgeall 44.Nd restartable atomic sequences 45.Sh SYNOPSIS 46.Fd #include \*[Lt]sys/types.h\*[Gt] 47.Fd #include \*[Lt]sys/proc.h\*[Gt] 48.Fd #include \*[Lt]sys/ras.h\*[Gt] 49.Ft caddr_t 50.Fn ras_lookup "struct proc *p" "caddr_t addr" 51.Ft int 52.Fn ras_fork "struct proc *p1" "struct proc *p2" 53.Ft int 54.Fn ras_purgeall "struct proc *p" 55.Sh DESCRIPTION 56Restartable atomic sequences are user code sequences which are 57guaranteed to execute without preemption. This property is assured by 58checking the set of restartable atomic sequences registered for a 59process during 60.Xr cpu_switch 9 . 61If a process is found to have been preempted during a restartable 62sequence, then its execution is rolled-back to the start of the 63sequence by resetting its program counter saved in its process control 64block (PCB). 65.Pp 66The RAS functionality is provided by a combination of the 67machine-independent routines discussed in this page and 68a machine-dependent component in 69.Xr cpu_switch 9 . 70A port which supports restartable atomic sequences will define 71__HAVE_RAS in 72.Pa machine/types.h 73for machine-independent code to conditionally provide RAS support. 74.Pp 75A complicated side-effect of restartable atomic sequences is their 76interaction with the machine-dependent 77.Xr ptrace 2 78support. Specifically, single-step traps and/or the emulation of 79single-stepping must carefully consider the effect on restartable 80atomic sequences. A general solution is to ignore these traps or 81disable them within restartable atomic sequences. 82.Sh FUNCTIONS 83The functions which operate on restartable atomic sequences are: 84.Pp 85.Bl -tag -width compact 86.It Fn ras_lookup "p" "addr" 87This function searches the registered restartable atomic sequences for 88process 89.Fa p 90which contain the user address 91.Fa addr . 92If the address 93.Fa addr 94is found within a RAS, then the restart address of the RAS is 95returned, otherwise \-1 is returned. 96.It Fn ras_fork "p1" "p2" 97This function is used to copy all registered restartable atomic 98sequences for process 99.Fa p1 100to process 101.Fa p2 . 102It is primarily called from 103.Xr fork1 9 104when the sequences are inherited from the parent by the child. 105.It Fn ras_purgeall "p" 106This function is used to remove all registered restartable atomic 107sequences for process 108.Fa p . 109It is primarily used to remove all registered restartable atomic 110sequences for a process during 111.Xr exec 3 112and by 113.Xr rasctl 2 . 114.El 115.Sh CODE REFERENCES 116This section describes places within the 117.Nx 118source tree where actual code implementing or utilising the RAS 119functionality can be found. All pathnames are relative to 120.Pa /usr/src . 121.Pp 122The RAS framework itself is implemented within the file 123.Pa sys/kern/kern_ras.c . 124Data structures and function prototypes for the framework are located 125in 126.Pa sys/sys/ras.h . 127Machine-dependent portions are implemented within 128.Xr cpu_switch 9 129in the machine-dependent file 130.Pa sys/arch/\*[Lt]arch\*[Gt]/\*[Lt]arch\*[Gt]/locore.S . 131.Sh SEE ALSO 132.Xr rasctl 2 , 133.Xr cpu_switch 9 , 134.Xr fork1 9 135.Sh HISTORY 136The RAS functionality first appeared in 137.Nx 2.0 . 138