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