.\"     $NetBSD: ras.9,v 1.15 2010/12/02 12:54:13 wiz Exp $
.\"
.\" Copyright (c) 2002 The NetBSD Foundation, Inc.
.\" All rights reserved.
.\"
.\" This code is derived from software contributed to The NetBSD Foundation
.\" by Gregory McGarry.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
.\" POSSIBILITY OF SUCH DAMAGE.
.\"
.Dd April 17, 2010
.Dt RAS 9
.Os
.Sh NAME
.Nm ras_lookup ,
.Nm ras_fork ,
.Nm ras_purgeall
.Nd restartable atomic sequences
.Sh SYNOPSIS
.In sys/types.h
.In sys/proc.h
.In sys/ras.h
.Ft void *
.Fn ras_lookup "struct proc *p" "void *addr"
.Ft int
.Fn ras_fork "struct proc *p1" "struct proc *p2"
.Ft int
.Fn ras_purgeall "struct proc *p"
.Sh DESCRIPTION
Restartable atomic sequences are user code sequences which are
guaranteed to execute without preemption.
This property is assured by checking the set of restartable atomic
sequences registered for a process during
.Xr cpu_switchto 9 .
If a process is found to have been preempted during a restartable
sequence, then its execution is rolled-back to the start of the
sequence by resetting its program counter saved in its process control block
.Pq Tn PCB .
.Pp
The
.Tn RAS
functionality is provided by a combination of the
machine-independent routines discussed in this page and
a machine-dependent component in
.Xr cpu_switchto 9 .
A port which supports restartable atomic sequences will define
.Dv __HAVE_RAS
in
.In machine/types.h
for machine-independent code to conditionally provide RAS support.
.Pp
A complicated side-effect of restartable atomic sequences is their
interaction with the machine-dependent
.Xr ptrace 2
support.
Specifically, single-step traps and/or the emulation of single-stepping
must carefully consider the effect on restartable atomic sequences.
A general solution is to ignore these traps or disable them within
restartable atomic sequences.
.Sh FUNCTIONS
The functions which operate on restartable atomic sequences are:
.Pp
.Bl -tag -width compact
.It Fn ras_lookup "p" "addr"
This function searches the registered restartable atomic sequences for
process
.Fa p
which contain the user address
.Fa addr .
If the address
.Fa addr
is found within a
.Tn RAS ,
then the restart address of the
.Tn RAS
is returned, otherwise \-1 is returned.
.It Fn ras_fork "p1" "p2"
This function is used to copy all registered restartable atomic
sequences for process
.Fa p1
to process
.Fa p2 .
It is primarily called from
.Xr fork1 9
when the sequences are inherited from the parent by the child.
.It Fn ras_purgeall "p"
This function is used to remove all registered restartable atomic
sequences for process
.Fa p .
It is primarily used to remove all registered restartable atomic
sequences for a process during
.Xr exec 3
and by
.Xr rasctl 2 .
.El
.Sh CODE REFERENCES
The RAS framework itself is implemented within the file
.Pa sys/kern/kern_ras.c .
Data structures and function prototypes for the framework are located
in
.In sys/ras.h .
Machine-dependent portions are implemented within
.Xr cpu_switchto 9
in the machine-dependent file
.Pa sys/arch/\*[Lt]arch\*[Gt]/\*[Lt]arch\*[Gt]/locore.S .
.Sh SEE ALSO
.Xr rasctl 2 ,
.Xr cpu_switchto 9 ,
.Xr fork1 9
.Rs
.%A Gregory McGarry
.%T "An Implementation of User-level Restartable \
Atomic Sequences on the NetBSD Operating System"
.%I USENIX Association
.%B Proceedings of the FREENIX Track: 2003 USENIX Annual Technical Conference
.%P 311-322
.%D June 9-14, 2003
.%U http://www.usenix.org/publications/library/proceedings/usenix03/tech/freenix03/full_papers/mcgarry/mcgarry.pdf
.Re
.Sh HISTORY
The RAS functionality first appeared in
.Nx 2.0 .