[src/uebayasi-xip]: src/share/man/man9 Improvements to wording and markup.

[jruoho <jruoho%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/04ea1610fe3c
branches:  uebayasi-xip
changeset: 751654:04ea1610fe3c
user:      jruoho <jruoho%NetBSD.org@localhost>
date:      Tue Apr 13 06:05:57 2010 +0000

description:
Improvements to wording and markup.

diffstat:

 share/man/man9/cpu_switchto.9 |  142 ++++++++++++++++++++++++++++++++++++++++++
 1 files changed, 142 insertions(+), 0 deletions(-)

diffs (146 lines):

diff -r d6d892b25ebb -r 04ea1610fe3c share/man/man9/cpu_switchto.9
--- /dev/null   Thu Jan 01 00:00:00 1970 +0000
+++ b/share/man/man9/cpu_switchto.9     Tue Apr 13 06:05:57 2010 +0000
@@ -0,0 +1,142 @@
+.\"    $NetBSD: cpu_switchto.9,v 1.11.2.2 2010/04/13 06:05:57 jruoho Exp $
+.\"
+.\" Copyright (c)2007 YAMAMOTO Takashi,
+.\" All rights reserved.
+.\"
+.\" 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.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR 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 AUTHOR 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 April 13, 2010
+.Dt CPU_SWITCHTO 9
+.Os
+.\" ------------------------------------------------------------
+.Sh NAME
+.Nm cpu_switchto
+.Nd machine-dependent
+.Tn LWP
+context switching interface
+.\" ------------------------------------------------------------
+.Sh SYNOPSIS
+.In sys/cpu.h
+.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+.Ft lwp_t *
+.Fn cpu_switchto \
+"lwp_t *oldlwp" "lwp_t *newlwp" "bool returning"
+.\" ------------------------------------------------------------
+.Sh DESCRIPTION
+The
+.Fn cpu_switchto
+function saves the context of the
+.Tn LWP
+which is currently running on the processor,
+and restores the context of the
+.Tn LWP
+specified by
+.Fa newlwp .
+.Pp
+Remarks:
+.Bl -enum -offset indent
+.It
+.Fn cpu_switchto
+does not switch address spaces.
+.It
+.Fn cpu_switchto
+sets
+.Xr curlwp 9
+to
+.Fa newlwp .
+.It
+.Fn cpu_switchto
+should be called at
+.Dv IPL_SCHED .
+When the function returns, the caller should lower
+the priority level as soon as possible.
+.It
+.Fn cpu_switchto
+might be called with spin mutexes held.
+.El
+.Pp
+The function takes the following arguments.
+.Bl -tag -width "returning " -offset indent
+.It Fa oldlwp
+Specify the
+.Tn LWP
+from which the switch is going to be made, i.e., the calling
+.Tn LWP .
+If it was
+.Dv NULL ,
+the context of the
+.Tn LWP
+currently running on this processor is not saved.
+.It Fa newlwp
+Specify the
+.Tn LWP
+to which to switch.
+It must not be
+.Dv NULL .
+.It Fa returning
+Only meaningful if the architecture implements fast software interrupts.
+If true, it indicates that
+.Fa oldlwp
+is a soft interrupt
+.Tn LWP
+that is blocking.
+It is a good indication that any kind of address space or user activity
+can be completely ignored.
+For example:
+.Xr ras_lookup 9 ,
+cache flushes, TLB wirings, adjusting lazy
+.Tn FPU
+state.
+All that is required is to restore the register state and stack, and
+return to the interrupted
+.Tn LWP .
+.El
+.\" ------------------------------------------------------------
+.Sh RETURN VALUES
+The
+.Fn cpu_switchto
+function does not return until another
+.Tn LWP
+calls
+.Fn cpu_switchto .
+It returns the
+.Vt oldlwp
+argument of the
+.Fn cpu_switchto
+which is called to switch back to our
+.Tn LWP .
+It is either a
+.Tn LWP
+which called
+.Fn cpu_switchto
+to switch to us or
+.Dv NULL
+in case the
+.Tn LWP
+was exiting.
+.\" ------------------------------------------------------------
+.Sh SEE ALSO
+.Xr swapcontext 3 ,
+.Xr intro 9 ,
+.Xr mutex 9 ,
+.Xr spl 9