1.\" $NetBSD: ctxsw.9,v 1.2 1996/12/02 00:11:31 tls Exp $ 2.\" 3.\" Copyright (c) 1996 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" This code is derived from software contributed to The NetBSD Foundation 7.\" by Paul Kranenburg. 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 3. All advertising materials mentioning features or use of this software 18.\" must display the following acknowledgement: 19.\" This product includes software developed by the NetBSD 20.\" Foundation, Inc. and its contributors. 21.\" 4. Neither the name of The NetBSD Foundation nor the names of its 22.\" contributors may be used to endorse or promote products derived 23.\" from this software without specific prior written permission. 24.\" 25.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 26.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 27.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 28.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE 29.\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 30.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 31.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 32.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 33.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 34.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 35.\" POSSIBILITY OF SUCH DAMAGE. 36.\" 37.\" $FreeBSD$ 38.\" 39.Dd November 24, 1996 40.Dt MI_SWITCH 9 41.Os 42.Sh NAME 43.Nm mi_switch , 44.Nm cpu_switch , 45.Nm cpu_throw 46.Nd switch to another thread context 47.Sh SYNOPSIS 48.In sys/param.h 49.In sys/proc.h 50.Ft void 51.Fn mi_switch "void" 52.Ft void 53.Fn cpu_switch "void" 54.Ft void 55.Fn cpu_throw "void" 56.Sh DESCRIPTION 57The 58.Fn mi_switch 59function implements the machine independent prelude to a thread context 60switch. 61It is called from only a few distinguished places in the kernel 62code as a result of the principle of non-preemtable kernel mode execution. 63The various major uses of 64.Nm 65can be enumerated as follows: 66.Bl -enum -offset indent 67.It 68from within 69.Xr sleep 9 70, 71.Xr tsleep 9 72and 73.Xr msleep 9 74when the current thread 75voluntarily relinquishes the CPU to wait for some resource to become 76available. 77.It 78after handling a trap 79(e.g. a system call, device interrupt) 80when the kernel prepares a return to user-mode execution. 81This case is 82typically handled by machine dependent trap-handling code after detection 83of a change in the signal disposition of the current process, or when a 84higher priority thread might be available to run. 85The latter event is 86communicated by the machine independent scheduling routines by calling 87the machine defined 88.Fn need_resched . 89.It 90in the signal handling code 91(see 92.Xr issignal 9 ) 93if a signal is delivered that causes a process to stop. 94.It 95When a thread dies in 96.Xr thread_exit 9 97and control of the processor can be passed to the next runnable thread. 98.It 99In 100.Xr thread_suspend_check 9 101where a thread needs to stop execution due to the suspension state of 102the process as a whole. 103.El 104.Pp 105.Fn mi_switch 106records the amount of time the current thread has been running in the 107process structures and checks this value against the CPU time limits 108allocated to the process 109(see 110.Xr getrlimit 2 ) . 111Exceeding the soft limit results in a 112.Dv SIGXCPU 113signal to be posted to the process, while exceeding the hard limit will 114cause a 115.Dv SIGKILL . 116.Pp 117If the thread is still in 118.Em TDS_RUNNING 119state mi_switch will put it back onto the run queue, assuming that 120it will want to run again soon. If it is in one of the other 121states and KSE threading is enabled, the associated 122.Em KSE 123will be made available to to any higher priority threads from the same 124group, to allow them to be scheduled next. 125.Pp 126After these administrative tasks are done, 127.Fn mi_switch 128hands over control to the machine dependent routine 129.Fn cpu_switch , 130which will perform the actual thread context switch. 131.Pp 132.Fn cpu_switch 133first saves the context of the current thread. 134Next, it calls 135.Fn choosethread 136to determine which thread to run next. 137Finally, it reads in the saved context of the new thread and starts to 138execute the new thread. 139.Pp 140.Fn cpu_throw 141is similar to 142.Fn cpu_switch 143except that it does not save the context of the old thread. 144This function is useful when the kernel does not have an old thread 145context to save, such as when CPUs other than the boot CPU perform their 146first task switch, or when the kernel does not care about the state of the 147old thread, such as in 148.Fn thread_exit 149when the kernel terminates the current thread and switches into a new 150thread. 151.Pp 152To protect the 153.Xr runqueue 9 , 154all of these functions must be called with the 155.Va sched_lock 156mutex held. 157.Sh SEE ALSO 158.Xr issignal 9 , 159.Xr mutex 9 , 160.Xr runqueue 9 , 161.Xr tsleep 9 , 162.Xr wakeup 9 163