152 lines
5.2 KiB
Groff
152 lines
5.2 KiB
Groff
.\" $NetBSD: rasctl.2,v 1.5 2002/10/01 18:10:45 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.
|
|
.\" 3. All advertising materials mentioning features or use of this software
|
|
.\" must display the following acknowledgement:
|
|
.\" This product includes software developed by the NetBSD
|
|
.\" Foundation, Inc. and its contributors.
|
|
.\" 4. Neither the name of The NetBSD Foundation nor the names of its
|
|
.\" contributors may be used to endorse or promote products derived
|
|
.\" from this software without specific prior written permission.
|
|
.\"
|
|
.\" 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 August 12, 2002
|
|
.Dt RASCTL 2
|
|
.Os
|
|
.Sh NAME
|
|
.Nm rasctl
|
|
.Nd restartable atomic sequences
|
|
.Sh LIBRARY
|
|
.Lb libc
|
|
.Sh SYNOPSIS
|
|
.Fd #include \*[Lt]sys/types.h\*[Gt]
|
|
.Fd #include \*[Lt]sys/ras.h\*[Gt]
|
|
.Ft int
|
|
.Fn rasctl "void *addr" "size_t len" "int op"
|
|
.Sh DESCRIPTION
|
|
Restartable atomic sequences are code sequences which are guaranteed
|
|
to execute without preemption.
|
|
This property is assured by the kernel
|
|
by re-executing a preempted sequence from the start.
|
|
This functionality enables applications to build atomic sequences which,
|
|
when executed to completion, will have executed atomically.
|
|
Restartable atomic sequences are intended to be used on systems that
|
|
do not have hardware support for low-overhead atomic primitives.
|
|
.Pp
|
|
The
|
|
.Nm
|
|
function manipulates a process's set of restartable atomic sequences.
|
|
If a restartable atomic sequence is registered and the process is
|
|
preempted within the range
|
|
.Fa addr
|
|
and
|
|
.Fa addr Ns + Ns Fa len ,
|
|
then the process is resumed at
|
|
.Fa addr .
|
|
.Pp
|
|
As the process execution can be rolled-back, the code in the sequence
|
|
should have no side effects other than a final store at
|
|
.Fa addr Ns + Ns Fa len Ns \-1 .
|
|
The kernel does not guarantee that the sequences are successfully
|
|
restartable.
|
|
It assumes that the application knows what it is doing.
|
|
Restartable atomic sequences should adhere to the following guidelines:
|
|
.Pp
|
|
.Bl -bullet -compact
|
|
.It
|
|
have a single entry point and a single exit point;
|
|
.It
|
|
not execute emulated instructions; and
|
|
.It
|
|
not invoke any functions or system calls.
|
|
.El
|
|
.Pp
|
|
Restartable atomic sequences are inherited from the parent by the
|
|
child during the
|
|
.Xr fork 2
|
|
operation.
|
|
Restartable atomic sequences for a process are removed during
|
|
.Xr exec 3 .
|
|
.Pp
|
|
The operations that can be applied to a restartable atomic sequence
|
|
are specified by the
|
|
.Fa op
|
|
argument.
|
|
Possible operations are:
|
|
.Pp
|
|
.Bl -tag -compact -width RAS_PURGE_ALLXXX
|
|
.It RAS_INSTALL
|
|
Install this sequence.
|
|
.It RAS_PURGE
|
|
Remove the specified registered sequences for this process.
|
|
.It RAS_PURGE_ALL
|
|
Remove all registers sequences for this process.
|
|
.El
|
|
.Pp
|
|
The RAS_PURGE and RAS_PURGE_ALL operations should be considered to have
|
|
undefined behaviour if there are any other runnable threads in the
|
|
address space which might be executing within the restartable atomic
|
|
sequence(s) at the time of the purge.
|
|
The caller must be responsible for ensuring that there is some form of
|
|
coordination with other threads to prevent unexpected behaviour.
|
|
.Pp
|
|
To preserve the atomicity of sequences, the kernel attempts to protect
|
|
the sequences from alteration by the
|
|
.Xr ptrace 2
|
|
facility.
|
|
.Sh RETURN VALUES
|
|
Upon successful completion,
|
|
.Fn rasctl
|
|
returns zero.
|
|
Otherwise, \-1 is returned and
|
|
.Va errno
|
|
is set to indicate the error.
|
|
.Sh ERRORS
|
|
The
|
|
.Nm
|
|
function will fail if:
|
|
.Bl -tag -width Er
|
|
.It Bq Er EINVAL
|
|
Invalid input was supplied, such as an invalid operation, an invalid
|
|
address, or an invalid length.
|
|
A process may have a finite number of
|
|
atomic sequences that is defined at compile time.
|
|
.It Bq Er EOPNOTSUPP
|
|
Restartable atomic sequences are not supported by the kernel.
|
|
.It Bq Er ESRCH
|
|
Restartable atomic sequence not registered.
|
|
.El
|
|
.Sh SEE ALSO
|
|
.Xr ptrace 2
|
|
.\" .Xr lock 9
|
|
.Sh HISTORY
|
|
The
|
|
.Nm
|
|
functionality first appeared in
|
|
.Nx 2.0
|
|
based on a similar interface that appeared in Mach 2.5.
|