[src/trunk]: src/share/man/man9 Improvements to wording and markup.

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

details:   https://anonhg.NetBSD.org/src/rev/d6f28fadcb17
branches:  trunk
changeset: 753876:d6f28fadcb17
user:      jruoho <jruoho%NetBSD.org@localhost>
date:      Tue Apr 13 06:05:56 2010 +0000

description:
Improvements to wording and markup.

diffstat:

 share/man/man9/cpu_switchto.9 |  91 +++++++++++++++++++++++++++---------------
 1 files changed, 59 insertions(+), 32 deletions(-)

diffs (154 lines):

diff -r ae7eeeb0002c -r d6f28fadcb17 share/man/man9/cpu_switchto.9
--- a/share/man/man9/cpu_switchto.9     Tue Apr 13 05:41:53 2010 +0000
+++ b/share/man/man9/cpu_switchto.9     Tue Apr 13 06:05:56 2010 +0000
@@ -1,4 +1,4 @@
-.\"    $NetBSD: cpu_switchto.9,v 1.10 2008/05/25 20:00:30 wiz Exp $
+.\"    $NetBSD: cpu_switchto.9,v 1.11 2010/04/13 06:05:56 jruoho Exp $
 .\"
 .\" Copyright (c)2007 YAMAMOTO Takashi,
 .\" All rights reserved.
@@ -25,13 +25,15 @@
 .\" SUCH DAMAGE.
 .\"
 .\" ------------------------------------------------------------
-.Dd May 21, 2007
+.Dd April 13, 2010
 .Dt CPU_SWITCHTO 9
 .Os
 .\" ------------------------------------------------------------
 .Sh NAME
 .Nm cpu_switchto
-.Nd machine-dependent LWP context switching interface
+.Nd machine-dependent
+.Tn LWP
+context switching interface
 .\" ------------------------------------------------------------
 .Sh SYNOPSIS
 .In sys/cpu.h
@@ -41,72 +43,97 @@
 "lwp_t *oldlwp" "lwp_t *newlwp" "bool returning"
 .\" ------------------------------------------------------------
 .Sh DESCRIPTION
+The
 .Fn cpu_switchto
-saves the context of the LWP which is currently running on the processor,
-and restores the context of the LWP specified by
+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
-doesn't switch address spaces.
-.Pp
+does not switch address spaces.
+.It
 .Fn cpu_switchto
 sets
-.Dv curlwp
+.Xr curlwp 9
 to
 .Fa newlwp .
-.Pp
+.It
 .Fn cpu_switchto
 should be called at
 .Dv IPL_SCHED .
-When
-.Fn cpu_switchto
-returns, the caller should lower the priority level as soon as possible.
-.Pp
+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
-It takes the following arguments.
-.Bl -tag -width oldlwp
+The function takes the following arguments.
+.Bl -tag -width "returning " -offset indent
 .It Fa oldlwp
-Specify the lwp from which we are going to switch, i.e.,
-the calling LWP.
+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 LWP currently running on this processor is not saved.
+the context of the
+.Tn LWP
+currently running on this processor is not saved.
 .It Fa newlwp
-Specify the lwp to which we are going to switch.
+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 LWP that is blocking.
-It's a good indication that any kind of address space or user activity
+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:
-.Fn ras_lookup ,
-cache flushes, TLB wirings, adjusting lazy FPU
+.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 LWP.
+return to the interrupted
+.Tn LWP .
 .El
 .\" ------------------------------------------------------------
 .Sh RETURN VALUES
-.Fn cpu_switchto
-does not return until another LWP calls
+The
 .Fn cpu_switchto
-to switch to us.
+function does not return until another
+.Tn LWP
+calls
+.Fn cpu_switchto .
 It returns the
-.Dv oldlwp
+.Vt oldlwp
 argument of the
 .Fn cpu_switchto
-which is called to switch back to our LWP.
-It's either an LWP which called
-.Fa 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 the case that the LWP was exiting.
+in case the
+.Tn LWP
+was exiting.
 .\" ------------------------------------------------------------
 .Sh SEE ALSO
 .Xr swapcontext 3 ,