lib/libc/sys/rasctl.2

   1 .\"     $NetBSD: rasctl.2,v 1.13 2008/04/29 21:06:28 scw 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 April 29, 2008
  31 .Dt RASCTL 2
  32 .Os
  33 .Sh NAME
  34 .Nm rasctl
  35 .Nd restartable atomic sequences
  36 .Sh LIBRARY
  37 .Lb libc
  38 .Sh SYNOPSIS
  39 .In sys/types.h
  40 .In sys/ras.h
  41 .Ft int
  42 .Fn rasctl "void *addr" "size_t len" "int op"
  43 .Sh DESCRIPTION
  44 Restartable atomic sequences are code sequences which are guaranteed
  45 to execute without preemption.
  46 This property is assured by the kernel
  47 by re-executing a preempted sequence from the start.
  48 This functionality enables applications to build atomic sequences which,
  49 when executed to completion, will have executed atomically.
  50 Restartable atomic sequences are intended to be used on systems that
  51 do not have hardware support for low-overhead atomic primitives.
  52 .Pp
  53 The
  54 .Nm
  55 function manipulates a process's set of restartable atomic sequences.
  56 If a restartable atomic sequence is registered and the process is
  57 preempted within the range
  58 .Fa addr
  59 and
  60 .Fa addr Ns + Ns Fa len ,
  61 then the process is resumed at
  62 .Fa addr .
  63 .Pp
  64 As the process execution can be rolled-back, the code in the sequence
  65 should have no side effects other than a final store at
  66 .Fa addr Ns + Ns Fa len Ns \-1 .
  67 The kernel does not guarantee that the sequences are successfully
  68 restartable.
  69 It assumes that the application knows what it is doing.
  70 Restartable atomic sequences should adhere to the following guidelines:
  71 .Pp
  72 .Bl -bullet -compact
  73 .It
  74 have a single entry point and a single exit point;
  75 .It
  76 not execute emulated instructions; and
  77 .It
  78 not invoke any functions or system calls.
  79 .El
  80 .Pp
  81 Restartable atomic sequences are inherited from the parent by the
  82 child during the
  83 .Xr fork 2
  84 operation.
  85 Restartable atomic sequences for a process are removed during
  86 .Xr exec 3 .
  87 .Pp
  88 The operations that can be applied to a restartable atomic sequence
  89 are specified by the
  90 .Fa op
  91 argument.
  92 Possible operations are:
  93 .Pp
  94 .Bl -tag -compact -width RAS_PURGE_ALLXXX
  95 .It Dv RAS_INSTALL
  96 Install this sequence.
  97 .It Dv RAS_PURGE
  98 Remove the specified registered sequence for this process.
  99 .It Dv RAS_PURGE_ALL
 100 Remove all registered sequences for this process.
 101 .El
 102 .Pp
 103 The
 104 .Dv RAS_PURGE
 105 and
 106 .Dv RAS_PURGE_ALL
 107 operations should be considered to have
 108 undefined behaviour if there are any other runnable threads in the
 109 address space which might be executing within the restartable atomic
 110 sequence(s) at the time of the purge.
 111 The caller must be responsible for ensuring that there is some form of
 112 coordination with other threads to prevent unexpected behaviour.
 113 .Pp
 114 To preserve the atomicity of sequences, the kernel attempts to protect
 115 the sequences from alteration by the
 116 .Xr ptrace 2
 117 facility.
 118 .Sh RETURN VALUES
 119 Upon successful completion,
 120 .Fn rasctl
 121 returns zero.
 122 Otherwise, \-1 is returned and
 123 .Va errno
 124 is set to indicate the error.
 125 .Sh ERRORS
 126 The
 127 .Nm
 128 function will fail if:
 129 .Bl -tag -width Er
 130 .It Bq Er EINVAL
 131 Invalid input was supplied, such as an invalid operation, an invalid
 132 address, or an invalid length.
 133 A process may have a finite number of
 134 atomic sequences that is defined at compile time.
 135 .It Bq Er EOPNOTSUPP
 136 Restartable atomic sequences are not supported by the kernel.
 137 .It Bq Er ESRCH
 138 Restartable atomic sequence not registered.
 139 .El
 140 .Sh SEE ALSO
 141 .Xr ptrace 2
 142 .\" .Xr lock 9
 143 .Sh HISTORY
 144 The
 145 .Nm
 146 functionality first appeared in
 147 .Nx 2.0
 148 based on a similar interface that appeared in Mach 2.5.
 149 .Sh CAVEATS
 150 Modern compilers reorder instruction sequences to optimize speed.
 151 The start address and size of a
 152 .Nm RAS
 153 need to be protected against this.
 154 One level of protection is created by compiler dependent instructions,
 155 abstracted from user level code via the following macros:
 156 .Bl -tag -width RAS_START(name)
 157 .It Dv RAS_DECL(name)
 158 Declares the start and end labels used internally by the
 159 other macros to mark a
 160 .Nm RAS .
 161 The name uniquely identifies the
 162 .Nm RAS .
 163 .It Dv RAS_START(name)
 164 Marks the start of the code.
 165 Each restart returns to the instruction following this macro.
 166 .It Dv RAS_END(name)
 167 Marks the end of the restartable code.
 168 .It Dv RAS_ADDR(name)
 169 Returns the start address of a
 170 .Nm RAS
 171 and is used to create the first argument to
 172 .Nm .
 173 .It Dv RAS_SIZE(name)
 174 Returns the size of a
 175 .Nm RAS
 176 and is used as second argument to
 177 .Nm .
 178 .El
 179 Recent versions of
 180 .Xr gcc 1
 181 require the
 182 .Fl fno-reorder-blocks
 183 flag to prevent blocks of code wrapped with
 184 .Dv RAS_START Ns / Ns Dv RAS_END
 185 being moved outside these labels.
 186 However, be aware that this may not always be sufficient to prevent
 187 .Xr gcc 1
 188 from generating non-restartable code within the
 189 .Nm RAS
 190 due to register clobbers.
 191 It is, therefore, strongly recommended that restartable atomic sequences
 192 are coded in assembly.
 193 .Nm RAS
 194 blocks within assembly code can be specified by using the following macros:
 195 .Bl -tag -width RAS_START_ASM_HIDDEN(name)
 196 .It Dv RAS_START_ASM(name)
 197 Similar to
 198 .Nm RAS_START
 199 but for use in assembly source code.
 200 .It Dv RAS_END_ASM(name)
 201 Similar to
 202 .Nm RAS_END
 203 but for use in assembly source code.
 204 .It Dv RAS_START_ASM_HIDDEN(name)
 205 Similar to
 206 .Nm RAS_START_ASM
 207 except that the symbol will not be placed in the dynamic symbol table.
 208 .It Dv RAS_END_ASM_HIDDEN(name)
 209 Similar to
 210 .Nm RAS_END_ASM
 211 except that the symbol will not be placed in the dynamic symbol table.
 212 .El