1.\" $NetBSD: ras.9,v 1.14 2010/05/13 23:31:34 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.\" 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 17, 2010 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_switchto 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 block 57.Pq Tn PCB . 58.Pp 59The 60.Tn RAS 61functionality is provided by a combination of the 62machine-independent routines discussed in this page and 63a machine-dependent component in 64.Xr cpu_switchto 9 . 65A port which supports restartable atomic sequences will define 66.Dv __HAVE_RAS 67in 68.In machine/types.h 69for machine-independent code to conditionally provide RAS support. 70.Pp 71A complicated side-effect of restartable atomic sequences is their 72interaction with the machine-dependent 73.Xr ptrace 2 74support. 75Specifically, single-step traps and/or the emulation of single-stepping 76must carefully consider the effect on restartable atomic sequences. 77A general solution is to ignore these traps or disable them within 78restartable atomic sequences. 79.Sh FUNCTIONS 80The functions which operate on restartable atomic sequences are: 81.Pp 82.Bl -tag -width compact 83.It Fn ras_lookup "p" "addr" 84This function searches the registered restartable atomic sequences for 85process 86.Fa p 87which contain the user address 88.Fa addr . 89If the address 90.Fa addr 91is found within a 92.Tn RAS , 93then the restart address of the 94.Tn RAS 95is returned, 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 using the RAS 119functionality can be found. 120All pathnames are relative to 121.Pa /usr/src . 122.Pp 123The RAS framework itself is implemented within the file 124.Pa sys/kern/kern_ras.c . 125Data structures and function prototypes for the framework are located 126in 127.In sys/ras.h . 128Machine-dependent portions are implemented within 129.Xr cpu_switchto 9 130in the machine-dependent file 131.Pa sys/arch/\*[Lt]arch\*[Gt]/\*[Lt]arch\*[Gt]/locore.S . 132.Sh SEE ALSO 133.Xr rasctl 2 , 134.Xr cpu_switchto 9 , 135.Xr fork1 9 136.Rs 137.%A Gregory McGarry 138.%T "An Implementation of User-level Restartable \ 139Atomic Sequences on the NetBSD Operating System" 140.%I USENIX Association 141.%B Proceedings of the FREENIX Track: 2003 USENIX Annual Technical Conference 142.%P 311-322 143.%D June 9-14, 2003 144.%U http://www.usenix.org/publications/library/proceedings/usenix03/tech/freenix03/full_papers/mcgarry/mcgarry.pdf 145.Re 146.Sh HISTORY 147The RAS functionality first appeared in 148.Nx 2.0 . 149