xref: /minix3/lib/libc/sys/rasctl.2 (revision 2fe8fb192fe7e8720e3e7a77f928da545e872a6a)
1*2fe8fb19SBen Gras.\"     $NetBSD: rasctl.2,v 1.13 2008/04/29 21:06:28 scw Exp $
2*2fe8fb19SBen Gras.\"
3*2fe8fb19SBen Gras.\" Copyright (c) 2002 The NetBSD Foundation, Inc.
4*2fe8fb19SBen Gras.\" All rights reserved.
5*2fe8fb19SBen Gras.\"
6*2fe8fb19SBen Gras.\" This code is derived from software contributed to The NetBSD Foundation
7*2fe8fb19SBen Gras.\" by Gregory McGarry.
8*2fe8fb19SBen Gras.\"
9*2fe8fb19SBen Gras.\" Redistribution and use in source and binary forms, with or without
10*2fe8fb19SBen Gras.\" modification, are permitted provided that the following conditions
11*2fe8fb19SBen Gras.\" are met:
12*2fe8fb19SBen Gras.\" 1. Redistributions of source code must retain the above copyright
13*2fe8fb19SBen Gras.\"    notice, this list of conditions and the following disclaimer.
14*2fe8fb19SBen Gras.\" 2. Redistributions in binary form must reproduce the above copyright
15*2fe8fb19SBen Gras.\"    notice, this list of conditions and the following disclaimer in the
16*2fe8fb19SBen Gras.\"    documentation and/or other materials provided with the distribution.
17*2fe8fb19SBen Gras.\"
18*2fe8fb19SBen Gras.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
19*2fe8fb19SBen Gras.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
20*2fe8fb19SBen Gras.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
21*2fe8fb19SBen Gras.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
22*2fe8fb19SBen Gras.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
23*2fe8fb19SBen Gras.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
24*2fe8fb19SBen Gras.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
25*2fe8fb19SBen Gras.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
26*2fe8fb19SBen Gras.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
27*2fe8fb19SBen Gras.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
28*2fe8fb19SBen Gras.\" POSSIBILITY OF SUCH DAMAGE.
29*2fe8fb19SBen Gras.\"
30*2fe8fb19SBen Gras.Dd April 29, 2008
31*2fe8fb19SBen Gras.Dt RASCTL 2
32*2fe8fb19SBen Gras.Os
33*2fe8fb19SBen Gras.Sh NAME
34*2fe8fb19SBen Gras.Nm rasctl
35*2fe8fb19SBen Gras.Nd restartable atomic sequences
36*2fe8fb19SBen Gras.Sh LIBRARY
37*2fe8fb19SBen Gras.Lb libc
38*2fe8fb19SBen Gras.Sh SYNOPSIS
39*2fe8fb19SBen Gras.In sys/types.h
40*2fe8fb19SBen Gras.In sys/ras.h
41*2fe8fb19SBen Gras.Ft int
42*2fe8fb19SBen Gras.Fn rasctl "void *addr" "size_t len" "int op"
43*2fe8fb19SBen Gras.Sh DESCRIPTION
44*2fe8fb19SBen GrasRestartable atomic sequences are code sequences which are guaranteed
45*2fe8fb19SBen Grasto execute without preemption.
46*2fe8fb19SBen GrasThis property is assured by the kernel
47*2fe8fb19SBen Grasby re-executing a preempted sequence from the start.
48*2fe8fb19SBen GrasThis functionality enables applications to build atomic sequences which,
49*2fe8fb19SBen Graswhen executed to completion, will have executed atomically.
50*2fe8fb19SBen GrasRestartable atomic sequences are intended to be used on systems that
51*2fe8fb19SBen Grasdo not have hardware support for low-overhead atomic primitives.
52*2fe8fb19SBen Gras.Pp
53*2fe8fb19SBen GrasThe
54*2fe8fb19SBen Gras.Nm
55*2fe8fb19SBen Grasfunction manipulates a process's set of restartable atomic sequences.
56*2fe8fb19SBen GrasIf a restartable atomic sequence is registered and the process is
57*2fe8fb19SBen Graspreempted within the range
58*2fe8fb19SBen Gras.Fa addr
59*2fe8fb19SBen Grasand
60*2fe8fb19SBen Gras.Fa addr Ns + Ns Fa len ,
61*2fe8fb19SBen Grasthen the process is resumed at
62*2fe8fb19SBen Gras.Fa addr .
63*2fe8fb19SBen Gras.Pp
64*2fe8fb19SBen GrasAs the process execution can be rolled-back, the code in the sequence
65*2fe8fb19SBen Grasshould have no side effects other than a final store at
66*2fe8fb19SBen Gras.Fa addr Ns + Ns Fa len Ns \-1 .
67*2fe8fb19SBen GrasThe kernel does not guarantee that the sequences are successfully
68*2fe8fb19SBen Grasrestartable.
69*2fe8fb19SBen GrasIt assumes that the application knows what it is doing.
70*2fe8fb19SBen GrasRestartable atomic sequences should adhere to the following guidelines:
71*2fe8fb19SBen Gras.Pp
72*2fe8fb19SBen Gras.Bl -bullet -compact
73*2fe8fb19SBen Gras.It
74*2fe8fb19SBen Grashave a single entry point and a single exit point;
75*2fe8fb19SBen Gras.It
76*2fe8fb19SBen Grasnot execute emulated instructions; and
77*2fe8fb19SBen Gras.It
78*2fe8fb19SBen Grasnot invoke any functions or system calls.
79*2fe8fb19SBen Gras.El
80*2fe8fb19SBen Gras.Pp
81*2fe8fb19SBen GrasRestartable atomic sequences are inherited from the parent by the
82*2fe8fb19SBen Graschild during the
83*2fe8fb19SBen Gras.Xr fork 2
84*2fe8fb19SBen Grasoperation.
85*2fe8fb19SBen GrasRestartable atomic sequences for a process are removed during
86*2fe8fb19SBen Gras.Xr exec 3 .
87*2fe8fb19SBen Gras.Pp
88*2fe8fb19SBen GrasThe operations that can be applied to a restartable atomic sequence
89*2fe8fb19SBen Grasare specified by the
90*2fe8fb19SBen Gras.Fa op
91*2fe8fb19SBen Grasargument.
92*2fe8fb19SBen GrasPossible operations are:
93*2fe8fb19SBen Gras.Pp
94*2fe8fb19SBen Gras.Bl -tag -compact -width RAS_PURGE_ALLXXX
95*2fe8fb19SBen Gras.It Dv RAS_INSTALL
96*2fe8fb19SBen GrasInstall this sequence.
97*2fe8fb19SBen Gras.It Dv RAS_PURGE
98*2fe8fb19SBen GrasRemove the specified registered sequence for this process.
99*2fe8fb19SBen Gras.It Dv RAS_PURGE_ALL
100*2fe8fb19SBen GrasRemove all registered sequences for this process.
101*2fe8fb19SBen Gras.El
102*2fe8fb19SBen Gras.Pp
103*2fe8fb19SBen GrasThe
104*2fe8fb19SBen Gras.Dv RAS_PURGE
105*2fe8fb19SBen Grasand
106*2fe8fb19SBen Gras.Dv RAS_PURGE_ALL
107*2fe8fb19SBen Grasoperations should be considered to have
108*2fe8fb19SBen Grasundefined behaviour if there are any other runnable threads in the
109*2fe8fb19SBen Grasaddress space which might be executing within the restartable atomic
110*2fe8fb19SBen Grassequence(s) at the time of the purge.
111*2fe8fb19SBen GrasThe caller must be responsible for ensuring that there is some form of
112*2fe8fb19SBen Grascoordination with other threads to prevent unexpected behaviour.
113*2fe8fb19SBen Gras.Pp
114*2fe8fb19SBen GrasTo preserve the atomicity of sequences, the kernel attempts to protect
115*2fe8fb19SBen Grasthe sequences from alteration by the
116*2fe8fb19SBen Gras.Xr ptrace 2
117*2fe8fb19SBen Grasfacility.
118*2fe8fb19SBen Gras.Sh RETURN VALUES
119*2fe8fb19SBen GrasUpon successful completion,
120*2fe8fb19SBen Gras.Fn rasctl
121*2fe8fb19SBen Grasreturns zero.
122*2fe8fb19SBen GrasOtherwise, \-1 is returned and
123*2fe8fb19SBen Gras.Va errno
124*2fe8fb19SBen Grasis set to indicate the error.
125*2fe8fb19SBen Gras.Sh ERRORS
126*2fe8fb19SBen GrasThe
127*2fe8fb19SBen Gras.Nm
128*2fe8fb19SBen Grasfunction will fail if:
129*2fe8fb19SBen Gras.Bl -tag -width Er
130*2fe8fb19SBen Gras.It Bq Er EINVAL
131*2fe8fb19SBen GrasInvalid input was supplied, such as an invalid operation, an invalid
132*2fe8fb19SBen Grasaddress, or an invalid length.
133*2fe8fb19SBen GrasA process may have a finite number of
134*2fe8fb19SBen Grasatomic sequences that is defined at compile time.
135*2fe8fb19SBen Gras.It Bq Er EOPNOTSUPP
136*2fe8fb19SBen GrasRestartable atomic sequences are not supported by the kernel.
137*2fe8fb19SBen Gras.It Bq Er ESRCH
138*2fe8fb19SBen GrasRestartable atomic sequence not registered.
139*2fe8fb19SBen Gras.El
140*2fe8fb19SBen Gras.Sh SEE ALSO
141*2fe8fb19SBen Gras.Xr ptrace 2
142*2fe8fb19SBen Gras.\" .Xr lock 9
143*2fe8fb19SBen Gras.Sh HISTORY
144*2fe8fb19SBen GrasThe
145*2fe8fb19SBen Gras.Nm
146*2fe8fb19SBen Grasfunctionality first appeared in
147*2fe8fb19SBen Gras.Nx 2.0
148*2fe8fb19SBen Grasbased on a similar interface that appeared in Mach 2.5.
149*2fe8fb19SBen Gras.Sh CAVEATS
150*2fe8fb19SBen GrasModern compilers reorder instruction sequences to optimize speed.
151*2fe8fb19SBen GrasThe start address and size of a
152*2fe8fb19SBen Gras.Nm RAS
153*2fe8fb19SBen Grasneed to be protected against this.
154*2fe8fb19SBen GrasOne level of protection is created by compiler dependent instructions,
155*2fe8fb19SBen Grasabstracted from user level code via the following macros:
156*2fe8fb19SBen Gras.Bl -tag -width RAS_START(name)
157*2fe8fb19SBen Gras.It Dv RAS_DECL(name)
158*2fe8fb19SBen GrasDeclares the start and end labels used internally by the
159*2fe8fb19SBen Grasother macros to mark a
160*2fe8fb19SBen Gras.Nm RAS .
161*2fe8fb19SBen GrasThe name uniquely identifies the
162*2fe8fb19SBen Gras.Nm RAS .
163*2fe8fb19SBen Gras.It Dv RAS_START(name)
164*2fe8fb19SBen GrasMarks the start of the code.
165*2fe8fb19SBen GrasEach restart returns to the instruction following this macro.
166*2fe8fb19SBen Gras.It Dv RAS_END(name)
167*2fe8fb19SBen GrasMarks the end of the restartable code.
168*2fe8fb19SBen Gras.It Dv RAS_ADDR(name)
169*2fe8fb19SBen GrasReturns the start address of a
170*2fe8fb19SBen Gras.Nm RAS
171*2fe8fb19SBen Grasand is used to create the first argument to
172*2fe8fb19SBen Gras.Nm .
173*2fe8fb19SBen Gras.It Dv RAS_SIZE(name)
174*2fe8fb19SBen GrasReturns the size of a
175*2fe8fb19SBen Gras.Nm RAS
176*2fe8fb19SBen Grasand is used as second argument to
177*2fe8fb19SBen Gras.Nm .
178*2fe8fb19SBen Gras.El
179*2fe8fb19SBen GrasRecent versions of
180*2fe8fb19SBen Gras.Xr gcc 1
181*2fe8fb19SBen Grasrequire the
182*2fe8fb19SBen Gras.Fl fno-reorder-blocks
183*2fe8fb19SBen Grasflag to prevent blocks of code wrapped with
184*2fe8fb19SBen Gras.Dv RAS_START Ns / Ns Dv RAS_END
185*2fe8fb19SBen Grasbeing moved outside these labels.
186*2fe8fb19SBen GrasHowever, be aware that this may not always be sufficient to prevent
187*2fe8fb19SBen Gras.Xr gcc 1
188*2fe8fb19SBen Grasfrom generating non-restartable code within the
189*2fe8fb19SBen Gras.Nm RAS
190*2fe8fb19SBen Grasdue to register clobbers.
191*2fe8fb19SBen GrasIt is, therefore, strongly recommended that restartable atomic sequences
192*2fe8fb19SBen Grasare coded in assembly.
193*2fe8fb19SBen Gras.Nm RAS
194*2fe8fb19SBen Grasblocks within assembly code can be specified by using the following macros:
195*2fe8fb19SBen Gras.Bl -tag -width RAS_START_ASM_HIDDEN(name)
196*2fe8fb19SBen Gras.It Dv RAS_START_ASM(name)
197*2fe8fb19SBen GrasSimilar to
198*2fe8fb19SBen Gras.Nm RAS_START
199*2fe8fb19SBen Grasbut for use in assembly source code.
200*2fe8fb19SBen Gras.It Dv RAS_END_ASM(name)
201*2fe8fb19SBen GrasSimilar to
202*2fe8fb19SBen Gras.Nm RAS_END
203*2fe8fb19SBen Grasbut for use in assembly source code.
204*2fe8fb19SBen Gras.It Dv RAS_START_ASM_HIDDEN(name)
205*2fe8fb19SBen GrasSimilar to
206*2fe8fb19SBen Gras.Nm RAS_START_ASM
207*2fe8fb19SBen Grasexcept that the symbol will not be placed in the dynamic symbol table.
208*2fe8fb19SBen Gras.It Dv RAS_END_ASM_HIDDEN(name)
209*2fe8fb19SBen GrasSimilar to
210*2fe8fb19SBen Gras.Nm RAS_END_ASM
211*2fe8fb19SBen Grasexcept that the symbol will not be placed in the dynamic symbol table.
212*2fe8fb19SBen Gras.El
213