kern/149574: [patch] update mi_switch(9) man page

Thu Aug 12 13:40:04 UTC 2010

>Number:         149574
>Category:       kern
>Synopsis:       [patch] update mi_switch(9) man page
>Confidential:   no
>Severity:       non-critical
>Priority:       medium
>Responsible:    freebsd-bugs
>State:          open
>Quarter:        
>Keywords:       
>Date-Required:
>Class:          doc-bug
>Submitter-Id:   current-users
>Arrival-Date:   Thu Aug 12 13:40:04 UTC 2010
>Closed-Date:
>Last-Modified:
>Originator:     pluknet
>Release:        9-CURRENT as of August '10
>Organization:
>Environment:
>Description:
The mi_switch(9) manual page in tree is much outdated.
- sync with ctxsw.9, v1.3 (license) and partially with 1.5 (minor grammar)
- update subject signatures in SYNOPSYS to current source, add description of the 
newly added function arguments.
- use <the .Nm function> convention
- reword of now non-existing need_resched(9)
- remove sentence about KSE threading impl. details
- list the possible mi_switch flags values
- remove the mention of choosethread(9) call from cpu_switch() in the 
cpu_switch() paragraph as that's not true, and choosethread() is mainly called 
from sched_switch(), not cpu_switch
- remove a paragraph about runqueue(9) locking as it's long outdated
- xref thread_exit(9) and choosethread(9)
>How-To-Repeat:

>Fix:


Patch attached with submission follows:

Index: share/man/man9/mi_switch.9
===================================================================

--- share/man/man9/mi_switch.9	(revision 209664)
+++ share/man/man9/mi_switch.9	(working copy)
@@ -1,4 +1,4 @@
-.\"	$NetBSD: ctxsw.9,v 1.2 1996/12/02 00:11:31 tls Exp $
+.\"	$NetBSD: ctxsw.9,v 1.3 1997/10/08 22:00:23 jtc Exp $
 .\"
 .\" Copyright (c) 1996 The NetBSD Foundation, Inc.
 .\" All rights reserved.
@@ -18,8 +18,8 @@
 .\" 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 REGENTS OR CONTRIBUTORS BE
-.\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+.\" 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
@@ -29,7 +29,7 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd November 24, 1996
+.Dd August 12, 2010
 .Dt MI_SWITCH 9
 .Os
 .Sh NAME
@@ -41,21 +41,21 @@
 .In sys/param.h
 .In sys/proc.h
 .Ft void
-.Fn mi_switch "void"
+.Fn mi_switch "int flags" "struct thread *newtd"
 .Ft void
-.Fn cpu_switch "void"
+.Fn cpu_switch "struct thread *td" "struct thread *newtd" "struct mtx *td_lock"
 .Ft void
-.Fn cpu_throw "void"
+.Fn cpu_throw "struct thread *td" "struct thread *newtd"
 .Sh DESCRIPTION
 The
 .Fn mi_switch
-function implements the machine independent prelude to a thread context
+function implements the machine-independent prelude to a thread context
 switch.
 It is called from only a few distinguished places in the kernel
 code as a result of the principle of non-preemptable kernel mode execution.
-The various major uses of
-.Nm
-can be enumerated as follows:
+The various major uses of the
+.Fn mi_switch
+function can be enumerated as follows:
 .Bl -enum -offset indent
 .It
 From within a function such as
@@ -71,13 +71,12 @@
 (e.g.\& a system call, device interrupt)
 when the kernel prepares a return to user-mode execution.
 This case is
-typically handled by machine dependent trap-handling code after detection
+typically handled by machine-dependent trap-handling code after detection
 of a change in the signal disposition of the current process, or when a
 higher priority thread might be available to run.
 The latter event is
-communicated by the machine independent scheduling routines by calling
-the machine defined
-.Fn need_resched .
+communicated by the machine-independent scheduling routines by setting
+the needresched thread state.
 .It
 In the signal handling code
 (see
@@ -94,7 +93,9 @@
 the process as a whole.
 .El
 .Pp
+The
 .Fn mi_switch
+function
 records the amount of time the current thread has been running in the
 process structures and checks this value against the CPU time limits
 allocated to the process
@@ -108,51 +109,89 @@
 .Pp
 If the thread is still in the
 .Dv TDS_RUNNING
-state,
+state, the
 .Fn mi_switch
+function
 will put it back onto the run queue, assuming that
 it will want to run again soon.
-If it is in one of the other
-states and KSE threading is enabled, the associated
-.Em KSE
-will be made available to any higher priority threads from the same
-group, to allow them to be scheduled next.
 .Pp
-After these administrative tasks are done,
+If a
+.Fa newtd
+thread is
+.Dv NULL ,
+the
 .Fn mi_switch
-hands over control to the machine dependent routine
-.Fn cpu_switch ,
-which will perform the actual thread context switch.
+function will hand over control to the machine-dependent
+.Fn cpu_switch
+function to select a new thread from the system run queue.
+If a new thread is specified, then the CPU will switch to that thread
+directly rather than calling
+.Xr choosethread 9
+to pick a thread to choose to.
+The
+.Fa flags
+argument specifies a conjunction of the types and flags for the
+.Fn mi_switch
+function.
+The currently understood flags are:
 .Pp
+.Bd -literal -offset indent -compact
+SW_VOL		Voluntary switch,
+SW_INVOL	Involuntary switch,
+SW_PREEMPT	Involuntary switch is a preemption
+.Ed
+.Pp
+Currently defined types are:
+.Pp
+.Bd -literal -offset indent -compact
+SW_TYPE_MASK		First 8 bits are switch type,
+SWT_NONE		Unspecified switch,
+SWT_PREEMPT		Switching due to preemption,
+SWT_OWEPREEMPT		Switching due to opepreempt,
+SWT_TURNSTILE		Turnstile contention,
+SWT_SLEEPQ		Sleepq wait,
+SWT_SLEEPQTIMO		Sleepq timeout wait,
+SWT_RELINQUISH		yield call,
+SWT_NEEDRESCHED		NEEDRESCHED was set,
+SWT_IDLE		Switching from the idle thread,
+SWT_IWAIT		Waiting for interrupts,
+SWT_SUSPEND		Thread suspended,
+SWT_REMOTEPREEMPT	Remote processor preempted,
+SWT_REMOTEWAKEIDLE	Remote processor preempted idle
+.Ed
+.Pp
+The
 .Fn cpu_switch
-first saves the context of the current thread.
-Next, it calls
-.Fn choosethread
-to determine which thread to run next.
-Finally, it reads in the saved context of the new thread and starts to
-execute the new thread.
+function first saves the context of the current thread
+.Fa td .
+Then it reads in the saved context of the new thread
+.Fa newtd
+and starts to execute the new thread with the switchout
+.Fa td_lock
+mutex held.
 .Pp
+The
 .Fn cpu_throw
-is similar to
+function is similar to the
 .Fn cpu_switch
-except that it does not save the context of the old thread.
+function
+except that the former does not save the context of the old
+.Fa td
+thread.
 This function is useful when the kernel does not have an old thread
 context to save, such as when CPUs other than the boot CPU perform their
 first task switch, or when the kernel does not care about the state of the
 old thread, such as in
-.Fn thread_exit
+.Xr thread_exit 9
 when the kernel terminates the current thread and switches into a new
+.Fa newtd
 thread.
-.Pp
-To protect the
-.Xr runqueue 9 ,
-all of these functions must be called with the
-.Va sched_lock
-mutex held.
 .Sh SEE ALSO
+.Xr choosethread 9 ,
 .Xr cv_wait 9 ,
 .Xr issignal 9 ,
 .Xr mutex 9 ,
 .Xr runqueue 9 ,
 .Xr tsleep 9 ,
+.Xr thread_exit 9 ,
 .Xr wakeup 9


>Release-Note:
>Audit-Trail:
>Unformatted:
