kern/149574: [patch] update mi_switch(9) man page
pluknet at gmail.com
Thu Aug 12 13:40:04 UTC 2010
>Synopsis: [patch] update mi_switch(9) man page
>Arrival-Date: Thu Aug 12 13:40:04 UTC 2010
>Release: 9-CURRENT as of August '10
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)
Patch attached with submission follows:
--- 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 @@
-.Dd November 24, 1996
+.Dd August 12, 2010
.Dt MI_SWITCH 9
@@ -41,21 +41,21 @@
-.Fn mi_switch "void"
+.Fn mi_switch "int flags" "struct thread *newtd"
-.Fn cpu_switch "void"
+.Fn cpu_switch "struct thread *td" "struct thread *newtd" "struct mtx *td_lock"
-.Fn cpu_throw "void"
+.Fn cpu_throw "struct thread *td" "struct thread *newtd"
-function implements the machine independent prelude to a thread context
+function implements the machine-independent prelude to a thread context
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
-can be enumerated as follows:
+The various major uses of the
+function can be enumerated as follows:
.Bl -enum -offset indent
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.
In the signal handling code
@@ -94,7 +93,9 @@
the process as a whole.
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 @@
If the thread is still in the
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
-will be made available to any higher priority threads from the same
-group, to allow them to be scheduled next.
-After these administrative tasks are done,
+.Dv NULL ,
-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
+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.
+argument specifies a conjunction of the types and flags for the
+The currently understood flags are:
+.Bd -literal -offset indent -compact
+SW_VOL Voluntary switch,
+SW_INVOL Involuntary switch,
+SW_PREEMPT Involuntary switch is a preemption
+Currently defined types are:
+.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
-first saves the context of the current thread.
-Next, it calls
-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
+and starts to execute the new thread with the switchout
-is similar to
+function is similar to the
-except that it does not save the context of the old thread.
+except that the former does not save the context of the old
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
+.Xr thread_exit 9
when the kernel terminates the current thread and switches into a new
-To protect the
-.Xr runqueue 9 ,
-all of these functions must be called with the
.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
More information about the freebsd-bugs