Add mi_switch.9. It documents the kernel mi_switch() and cpu_switch()

context switching functions.

Obtained from: NetBSD (renamed from ctxsw.9)

1 files changed, 141 insertions, 0 deletions

diff --git a/share/man/man9/mi_switch.9 b/share/man/man9/mi_switch.9
new file mode 100644
index 0000000..2fc23c6
--- /dev/null
+++ b/share/man/man9/mi_switch.9
@@ -0,0 +1,141 @@
+.\"	$NetBSD: ctxsw.9,v 1.2 1996/12/02 00:11:31 tls Exp $
+.\"
+.\" Copyright (c) 1996 The NetBSD Foundation, Inc.
+.\" All rights reserved.
+.\"
+.\" This code is derived from software contributed to The NetBSD Foundation
+.\" by Paul Kranenburg.
+.\"
+.\" 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.
+.\" 3. All advertising materials mentioning features or use of this software
+.\"    must display the following acknowledgement:
+.\"        This product includes software developed by the NetBSD
+.\"        Foundation, Inc. and its contributors.
+.\" 4. Neither the name of The NetBSD Foundation nor the names of its
+.\"    contributors may be used to endorse or promote products derived
+.\"    from this software without specific prior written permission.
+.\"
+.\" 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
+.\" 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 Nov 24, 1996
+.Dt mi_switch 9
+.Os FreeBSD
+.Sh NAME
+.Nm mi_switch ,
+.Nm cpu_switch
+.Nd switch to another process context
+.Sh SYNOPSIS
+.Ft void
+.Fn mi_switch "void"
+.Ft void
+.Fn cpu_switch "void"
+.Sh DESCRIPTION
+The
+.Fn mi_switch
+function implements the machine independent prelude to a process context
+switch. It is called from only a few distinguished places in the kernel
+code as a result of the principle of non-preemtable kernel mode execution.
+The three major uses of
+.Nm
+can be enumerated as follows:
+.Bl -enum -offset indent
+.It
+from within
+.Xr sleep 9 , and
+.Xr tsleep 9
+when the current process
+voluntarily relinquishes the CPU to wait for some resource to become
+available.
+.It
+after handling a trap
+.Pq 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
+of a change in the signal disposition of the current process, or when a
+higher priority process might be available to run. The latter event is
+communicated by the machine independent scheduling routines by calling
+the machine defined
+.Fn need_resched "void" .
+.It
+in the signal handling code
+.Pq see Xr issignal 9
+if a signal is delivered that causes a process to stop.
+.El
+.Pp
+.Fn mi_switch
+records the amount of time the current process has been running in the
+process structure and checks this value against the CPU time limits
+allocated to the process
+.Pq see Xr getrlimit 2 .
+Exceeding the soft limit results in a
+.Dv SIGXCPU
+signal to be posted to the process, while exceeding the hard limit will
+cause a
+.Dv SIGKILL .
+After these administrative tasks are done,
+.Fn mi_switch
+hands over control to the machine dependent routine
+.Fn cpu_switch "void" ,
+which will perform the actual process context switch.
+.Pp
+.Fn cpu_switch
+will make a choice amongst the processes which are ready to run from a
+priority queue data-structure. The priority queue consists of an array
+.Va qs[NQS]
+of queue header structures each of which identifies a list of runnable
+processes of equal priority
+.Pq see Fa <sys/proc.h> .
+A single word
+.Va whichqs
+containing a bit mask identifying non-empty queues assists in selecting
+a process quickly.
+.Fn cpu_switch
+must remove the first process from the list on the queue
+with the highest priority
+.Po lower indices in Va sq
+indicate higher priority
+.Pc ,
+and assign the address of its process structure to the global variable
+.Dv curproc .
+If no processes are available on the run queues,
+.Fn cpu_switch
+shall go into an
+.Dq idle
+loop. The idle loop must allow interrupts to be taken that will eventually
+cause processes to appear again on the run queues. The variable
+.Va curproc
+should be
+.Dv NULL
+while
+.Fn cpu_switch
+waits for this to happen.
+.Pp
+Note that
+.Fn mi_switch
+and thus
+.Fn cpu_switch
+should be called at splhigh().
+.Pp
+.Sh SEE ALSO
+.Xr issignal 9 ,
+.Xr spl 9 ,
+.Xr tsleep 9 ,
+.Xr wakeup 9
+.Pp