1.\" $NetBSD: ras.9,v 1.3 2002/10/14 13:43:30 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. 58This property is assured by checking the set of restartable atomic 59sequences registered for a process 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. 79Specifically, single-step traps and/or the emulation of single-stepping 80must carefully consider the effect on restartable atomic sequences. 81A general solution is to ignore these traps or disable them within 82restartable atomic sequences. 83.Sh FUNCTIONS 84The functions which operate on restartable atomic sequences are: 85.Pp 86.Bl -tag -width compact 87.It Fn ras_lookup "p" "addr" 88This function searches the registered restartable atomic sequences for 89process 90.Fa p 91which contain the user address 92.Fa addr . 93If the address 94.Fa addr 95is found within a RAS, then the restart address of the RAS is 96returned, otherwise \-1 is returned. 97.It Fn ras_fork "p1" "p2" 98This function is used to copy all registered restartable atomic 99sequences for process 100.Fa p1 101to process 102.Fa p2 . 103It is primarily called from 104.Xr fork1 9 105when the sequences are inherited from the parent by the child. 106.It Fn ras_purgeall "p" 107This function is used to remove all registered restartable atomic 108sequences for process 109.Fa p . 110It is primarily used to remove all registered restartable atomic 111sequences for a process during 112.Xr exec 3 113and by 114.Xr rasctl 2 . 115.El 116.Sh CODE REFERENCES 117This section describes places within the 118.Nx 119source tree where actual code implementing or utilising the RAS 120functionality can be found. 121All pathnames are relative to 122.Pa /usr/src . 123.Pp 124The RAS framework itself is implemented within the file 125.Pa sys/kern/kern_ras.c . 126Data structures and function prototypes for the framework are located 127in 128.Pa sys/sys/ras.h . 129Machine-dependent portions are implemented within 130.Xr cpu_switch 9 131in the machine-dependent file 132.Pa sys/arch/\*[Lt]arch\*[Gt]/\*[Lt]arch\*[Gt]/locore.S . 133.Sh SEE ALSO 134.Xr rasctl 2 , 135.Xr cpu_switch 9 , 136.Xr fork1 9 137.Sh HISTORY 138The RAS functionality first appeared in 139.Nx 2.0 . 140