xref: /netbsd-src/share/man/man9/ras.9 (revision 08c81a9c2dc8c7300e893321eb65c0925d60871c)
1.\"     $NetBSD: ras.9,v 1.2 2002/08/29 11:27:03 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.  This property is assured by
58checking the set of restartable atomic sequences registered for a
59process 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.  Specifically, single-step traps and/or the emulation of
79single-stepping must carefully consider the effect on restartable
80atomic sequences.  A general solution is to ignore these traps or
81disable them within restartable atomic sequences.
82.Sh FUNCTIONS
83The functions which operate on restartable atomic sequences are:
84.Pp
85.Bl -tag -width compact
86.It Fn ras_lookup "p" "addr"
87This function searches the registered restartable atomic sequences for
88process
89.Fa p
90which contain the user address
91.Fa addr .
92If the address
93.Fa addr
94is found within a RAS, then the restart address of the RAS is
95returned, 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 utilising the RAS
119functionality can be found.  All pathnames are relative to
120.Pa /usr/src .
121.Pp
122The RAS framework itself is implemented within the file
123.Pa sys/kern/kern_ras.c .
124Data structures and function prototypes for the framework are located
125in
126.Pa sys/sys/ras.h .
127Machine-dependent portions are implemented within
128.Xr cpu_switch 9
129in the machine-dependent file
130.Pa sys/arch/\*[Lt]arch\*[Gt]/\*[Lt]arch\*[Gt]/locore.S .
131.Sh SEE ALSO
132.Xr rasctl 2 ,
133.Xr cpu_switch 9 ,
134.Xr fork1 9
135.Sh HISTORY
136The RAS functionality first appeared in
137.Nx 2.0 .
138