1*01869ca4Swiz.\" $NetBSD: ras.9,v 1.16 2017/07/03 21:28:48 wiz Exp $ 2fa0313caSgmcgarry.\" 3fa0313caSgmcgarry.\" Copyright (c) 2002 The NetBSD Foundation, Inc. 4fa0313caSgmcgarry.\" All rights reserved. 5fa0313caSgmcgarry.\" 6fa0313caSgmcgarry.\" This code is derived from software contributed to The NetBSD Foundation 7fa0313caSgmcgarry.\" by Gregory McGarry. 8fa0313caSgmcgarry.\" 9fa0313caSgmcgarry.\" Redistribution and use in source and binary forms, with or without 10fa0313caSgmcgarry.\" modification, are permitted provided that the following conditions 11fa0313caSgmcgarry.\" are met: 12fa0313caSgmcgarry.\" 1. Redistributions of source code must retain the above copyright 13fa0313caSgmcgarry.\" notice, this list of conditions and the following disclaimer. 14fa0313caSgmcgarry.\" 2. Redistributions in binary form must reproduce the above copyright 15fa0313caSgmcgarry.\" notice, this list of conditions and the following disclaimer in the 16fa0313caSgmcgarry.\" documentation and/or other materials provided with the distribution. 17fa0313caSgmcgarry.\" 18fa0313caSgmcgarry.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 19fa0313caSgmcgarry.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 20fa0313caSgmcgarry.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 21fa0313caSgmcgarry.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 22fa0313caSgmcgarry.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 23fa0313caSgmcgarry.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 24fa0313caSgmcgarry.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 25fa0313caSgmcgarry.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 26fa0313caSgmcgarry.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 27fa0313caSgmcgarry.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 28fa0313caSgmcgarry.\" POSSIBILITY OF SUCH DAMAGE. 29fa0313caSgmcgarry.\" 303d285a96Sjruoho.Dd April 17, 2010 31fa0313caSgmcgarry.Dt RAS 9 32fa0313caSgmcgarry.Os 33fa0313caSgmcgarry.Sh NAME 34fa0313caSgmcgarry.Nm ras_lookup , 35fa0313caSgmcgarry.Nm ras_fork , 36fa0313caSgmcgarry.Nm ras_purgeall 37fa0313caSgmcgarry.Nd restartable atomic sequences 38fa0313caSgmcgarry.Sh SYNOPSIS 39472351e1Swiz.In sys/types.h 40472351e1Swiz.In sys/proc.h 41472351e1Swiz.In sys/ras.h 42e2598a32Swiz.Ft void * 43e2598a32Swiz.Fn ras_lookup "struct proc *p" "void *addr" 44fa0313caSgmcgarry.Ft int 45461bb7e2Srpaulo.Fn ras_fork "struct proc *p1" "struct proc *p2" 46fa0313caSgmcgarry.Ft int 47461bb7e2Srpaulo.Fn ras_purgeall "struct proc *p" 48fa0313caSgmcgarry.Sh DESCRIPTION 49fa0313caSgmcgarryRestartable atomic sequences are user code sequences which are 50770eef21Swizguaranteed to execute without preemption. 51770eef21SwizThis property is assured by checking the set of restartable atomic 52770eef21Swizsequences registered for a process during 530cb92fb7Sjruoho.Xr cpu_switchto 9 . 54fa0313caSgmcgarryIf a process is found to have been preempted during a restartable 55fa0313caSgmcgarrysequence, then its execution is rolled-back to the start of the 560cb92fb7Sjruohosequence by resetting its program counter saved in its process control block 570cb92fb7Sjruoho.Pq Tn PCB . 58fa0313caSgmcgarry.Pp 590cb92fb7SjruohoThe 600cb92fb7Sjruoho.Tn RAS 610cb92fb7Sjruohofunctionality is provided by a combination of the 62fa0313caSgmcgarrymachine-independent routines discussed in this page and 63fa0313caSgmcgarrya machine-dependent component in 640cb92fb7Sjruoho.Xr cpu_switchto 9 . 65fa0313caSgmcgarryA port which supports restartable atomic sequences will define 660cb92fb7Sjruoho.Dv __HAVE_RAS 670cb92fb7Sjruohoin 680cb92fb7Sjruoho.In machine/types.h 69fa0313caSgmcgarryfor machine-independent code to conditionally provide RAS support. 70fa0313caSgmcgarry.Pp 71fa0313caSgmcgarryA complicated side-effect of restartable atomic sequences is their 72fa0313caSgmcgarryinteraction with the machine-dependent 73fa0313caSgmcgarry.Xr ptrace 2 74770eef21Swizsupport. 75770eef21SwizSpecifically, single-step traps and/or the emulation of single-stepping 76770eef21Swizmust carefully consider the effect on restartable atomic sequences. 77770eef21SwizA general solution is to ignore these traps or disable them within 78770eef21Swizrestartable atomic sequences. 79fa0313caSgmcgarry.Sh FUNCTIONS 80fa0313caSgmcgarryThe functions which operate on restartable atomic sequences are: 81fa0313caSgmcgarry.Pp 82fa0313caSgmcgarry.Bl -tag -width compact 83fa0313caSgmcgarry.It Fn ras_lookup "p" "addr" 84fa0313caSgmcgarryThis function searches the registered restartable atomic sequences for 85fa0313caSgmcgarryprocess 86fa0313caSgmcgarry.Fa p 87fa0313caSgmcgarrywhich contain the user address 88fa0313caSgmcgarry.Fa addr . 89fa0313caSgmcgarryIf the address 90fa0313caSgmcgarry.Fa addr 910cb92fb7Sjruohois found within a 920cb92fb7Sjruoho.Tn RAS , 930cb92fb7Sjruohothen the restart address of the 940cb92fb7Sjruoho.Tn RAS 950cb92fb7Sjruohois returned, otherwise \-1 is returned. 96fa0313caSgmcgarry.It Fn ras_fork "p1" "p2" 97fa0313caSgmcgarryThis function is used to copy all registered restartable atomic 98fa0313caSgmcgarrysequences for process 99fa0313caSgmcgarry.Fa p1 100fa0313caSgmcgarryto process 101fa0313caSgmcgarry.Fa p2 . 102fa0313caSgmcgarryIt is primarily called from 103fa0313caSgmcgarry.Xr fork1 9 104fa0313caSgmcgarrywhen the sequences are inherited from the parent by the child. 105fa0313caSgmcgarry.It Fn ras_purgeall "p" 106fa0313caSgmcgarryThis function is used to remove all registered restartable atomic 107fa0313caSgmcgarrysequences for process 108fa0313caSgmcgarry.Fa p . 109fa0313caSgmcgarryIt is primarily used to remove all registered restartable atomic 110fa0313caSgmcgarrysequences for a process during 111fa0313caSgmcgarry.Xr exec 3 112fa0313caSgmcgarryand by 113fa0313caSgmcgarry.Xr rasctl 2 . 114fa0313caSgmcgarry.El 115fa0313caSgmcgarry.Sh CODE REFERENCES 116fa0313caSgmcgarryThe RAS framework itself is implemented within the file 117fa0313caSgmcgarry.Pa sys/kern/kern_ras.c . 118fa0313caSgmcgarryData structures and function prototypes for the framework are located 119fa0313caSgmcgarryin 1203d285a96Sjruoho.In sys/ras.h . 121fa0313caSgmcgarryMachine-dependent portions are implemented within 1220cb92fb7Sjruoho.Xr cpu_switchto 9 123fa0313caSgmcgarryin the machine-dependent file 124*01869ca4Swiz.Pa sys/arch/<arch>/<arch>/locore.S . 125fa0313caSgmcgarry.Sh SEE ALSO 126fa0313caSgmcgarry.Xr rasctl 2 , 1270cb92fb7Sjruoho.Xr cpu_switchto 9 , 128fa0313caSgmcgarry.Xr fork1 9 129f4291020Sjruoho.Rs 130f4291020Sjruoho.%A Gregory McGarry 131f4291020Sjruoho.%T "An Implementation of User-level Restartable \ 132f4291020SjruohoAtomic Sequences on the NetBSD Operating System" 133f4291020Sjruoho.%I USENIX Association 134f4291020Sjruoho.%B Proceedings of the FREENIX Track: 2003 USENIX Annual Technical Conference 135f4291020Sjruoho.%P 311-322 136f4291020Sjruoho.%D June 9-14, 2003 1376f1249aaSwiz.%U http://www.usenix.org/publications/library/proceedings/usenix03/tech/freenix03/full_papers/mcgarry/mcgarry.pdf 138f4291020Sjruoho.Re 139fa0313caSgmcgarry.Sh HISTORY 140fa0313caSgmcgarryThe RAS functionality first appeared in 141fa0313caSgmcgarry.Nx 2.0 . 142