ras(9) [netbsd man page]

RAS(9)							   BSD Kernel Developer's Manual						    RAS(9)

NAME

     ras_lookup, ras_fork, ras_purgeall -- restartable atomic sequences

SYNOPSIS

     #include <sys/types.h>
     #include <sys/proc.h>
     #include <sys/ras.h>

     void *
     ras_lookup(struct proc *p, void *addr);

     int
     ras_fork(struct proc *p1, struct proc *p2);

     int
     ras_purgeall(struct proc *p);

DESCRIPTION

     Restartable atomic sequences are user code sequences which are guaranteed to execute without preemption.  This property is assured by check-
     ing the set of restartable atomic sequences registered for a process during 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 (PCB).

     The RAS functionality is provided by a combination of the machine-independent routines discussed in this page and a machine-dependent compo-
     nent in cpu_switchto(9).  A port which supports restartable atomic sequences will define __HAVE_RAS in <machine/types.h> for machine-indepen-
     dent code to conditionally provide RAS support.

     A complicated side-effect of restartable atomic sequences is their interaction with the machine-dependent 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.

FUNCTIONS

     The functions which operate on restartable atomic sequences are:

     ras_lookup(p, addr)
	      This function searches the registered restartable atomic sequences for process p which contain the user address addr.  If the
	      address addr is found within a RAS, then the restart address of the RAS is returned, otherwise -1 is returned.

     ras_fork(p1, p2)
	      This function is used to copy all registered restartable atomic sequences for process p1 to process p2.  It is primarily called from
	      fork1(9) when the sequences are inherited from the parent by the child.

     ras_purgeall(p)
	      This function is used to remove all registered restartable atomic sequences for process p.  It is primarily used to remove all reg-
	      istered restartable atomic sequences for a process during exec(3) and by rasctl(2).

CODE REFERENCES

     The RAS framework itself is implemented within the file sys/kern/kern_ras.c.  Data structures and function prototypes for the framework are
     located in <sys/ras.h>.  Machine-dependent portions are implemented within cpu_switchto(9) in the machine-dependent file
     sys/arch/<arch>/<arch>/locore.S.

SEE ALSO

     rasctl(2), cpu_switchto(9), fork1(9)

     Gregory McGarry, "An Implementation of User-level Restartable Atomic Sequences on the NetBSD Operating System", Proceedings of the FREENIX
     Track: 2003 USENIX Annual Technical Conference, USENIX Association,
     http://www.usenix.org/publications/library/proceedings/usenix03/tech/freenix03/full_papers/mcgarry/mcgarry.pdf, 311-322, June 9-14, 2003.

HISTORY

     The RAS functionality first appeared in NetBSD 2.0.

BSD
								  April 17, 2010							       BSD

Check Out this Related Man Page

CPU_SWITCHTO(9) 					   BSD Kernel Developer's Manual					   CPU_SWITCHTO(9)

NAME

     cpu_switchto -- machine-dependent LWP context switching interface

SYNOPSIS

     #include <sys/cpu.h>

     lwp_t *
     cpu_switchto(lwp_t *oldlwp, lwp_t *newlwp, bool returning);

DESCRIPTION

     The cpu_switchto() function saves the context of the LWP which is currently running on the processor, and restores the context of the LWP
     specified by newlwp.

     Remarks:

	   1.	cpu_switchto() does not switch address spaces.

	   2.	cpu_switchto() sets curlwp(9) to newlwp.  If the architecture does non-interlocked adaptive mutex release, cpu_switchto() does an
		equivalent of membar_producer(3), before and after the modification of curlwp(9).

	   3.	cpu_switchto() should be called at IPL_SCHED.  When the function returns, the caller should lower the priority level as soon as
		possible.

	   4.	cpu_switchto() might be called with spin mutexes held.

     The function takes the following arguments.

	   oldlwp      Specify the LWP from which the switch is going to be made, i.e., the calling LWP.  If it was NULL, the context of the LWP
		       currently running on this processor is not saved.

	   newlwp      Specify the LWP to which to switch.  It must not be NULL.

	   returning   Only meaningful if the architecture implements fast software interrupts.  If true, it indicates that oldlwp is a soft
		       interrupt LWP that is blocking.	It is a good indication that any kind of address space or user activity can be completely
		       ignored.  For example: ras_lookup(9), cache flushes, TLB wirings, adjusting lazy FPU state.  All that is required is to
		       restore the register state and stack, and return to the interrupted LWP.

RETURN VALUES

     The cpu_switchto() function does not return until another LWP calls cpu_switchto().  It returns the oldlwp argument of the cpu_switchto()
     which is called to switch back to our LWP.  It is either a LWP which called cpu_switchto() to switch to us or NULL in case the LWP was exit-
     ing.

SEE ALSO

     membar_producer(3), swapcontext(3), intro(9), mutex(9), spl(9)

BSD
								   June 2, 2011 							       BSD

Linux and UNIX Man Pages

ras(9) [netbsd man page]

Check Out this Related Man Page