share/man/man9/ras.9

   1 .\"     $NetBSD: ras.9,v 1.9 2007/05/19 14:28:42 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 August 12, 2002
  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
  49 Restartable atomic sequences are user code sequences which are
  50 guaranteed to execute without preemption.
  51 This property is assured by checking the set of restartable atomic
  52 sequences registered for a process during
  53 .Xr cpu_switch 9 .
  54 If a process is found to have been preempted during a restartable
  55 sequence, then its execution is rolled-back to the start of the
  56 sequence by resetting its program counter saved in its process control
  57 block (PCB).
  58 .Pp
  59 The RAS functionality is provided by a combination of the
  60 machine-independent routines discussed in this page and
  61 a machine-dependent component in
  62 .Xr cpu_switch 9 .
  63 A port which supports restartable atomic sequences will define
  64 __HAVE_RAS in
  65 .Pa machine/types.h
  66 for machine-independent code to conditionally provide RAS support.
  67 .Pp
  68 A complicated side-effect of restartable atomic sequences is their
  69 interaction with the machine-dependent
  70 .Xr ptrace 2
  71 support.
  72 Specifically, single-step traps and/or the emulation of single-stepping
  73 must carefully consider the effect on restartable atomic sequences.
  74 A general solution is to ignore these traps or disable them within
  75 restartable atomic sequences.
  76 .Sh FUNCTIONS
  77 The functions which operate on restartable atomic sequences are:
  78 .Pp
  79 .Bl -tag -width compact
  80 .It Fn ras_lookup "p" "addr"
  81 This function searches the registered restartable atomic sequences for
  82 process
  83 .Fa p
  84 which contain the user address
  85 .Fa addr .
  86 If the address
  87 .Fa addr
  88 is found within a RAS, then the restart address of the RAS is
  89 returned, otherwise \-1 is returned.
  90 .It Fn ras_fork "p1" "p2"
  91 This function is used to copy all registered restartable atomic
  92 sequences for process
  93 .Fa p1
  94 to process
  95 .Fa p2 .
  96 It is primarily called from
  97 .Xr fork1 9
  98 when the sequences are inherited from the parent by the child.
  99 .It Fn ras_purgeall "p"
 100 This function is used to remove all registered restartable atomic
 101 sequences for process
 102 .Fa p .
 103 It is primarily used to remove all registered restartable atomic
 104 sequences for a process during
 105 .Xr exec 3
 106 and by
 107 .Xr rasctl 2 .
 108 .El
 109 .Sh CODE REFERENCES
 110 This section describes places within the
 111 .Nx
 112 source tree where actual code implementing or using the RAS
 113 functionality can be found.
 114 All pathnames are relative to
 115 .Pa /usr/src .
 116 .Pp
 117 The RAS framework itself is implemented within the file
 118 .Pa sys/kern/kern_ras.c .
 119 Data structures and function prototypes for the framework are located
 120 in
 121 .Pa sys/sys/ras.h .
 122 Machine-dependent portions are implemented within
 123 .Xr cpu_switch 9
 124 in the machine-dependent file
 125 .Pa sys/arch/\*[Lt]arch\*[Gt]/\*[Lt]arch\*[Gt]/locore.S .
 126 .Sh SEE ALSO
 127 .Xr rasctl 2 ,
 128 .Xr cpu_switch 9 ,
 129 .Xr fork1 9
 130 .Sh HISTORY
 131 The RAS functionality first appeared in
 132 .Nx 2.0 .