xref: /netbsd-src/share/man/man9/ras.9 (revision 01869ca4d24a86379a68731bf9706a9f0820fe4e)
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