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-preemptable kernel mode execution. 63The various major uses of 64.Nm 65can be enumerated as follows: 66.Bl -enum -offset indent 67.It 68From within a function such as 69.Xr cv_wait 9 , 70.Xr mtx_lock , 71or 72.Xr tsleep 9 73when the current thread 74voluntarily relinquishes the CPU to wait for some resource or lock to become 75available. 76.It 77After handling a trap 78(e.g.\& a system call, device interrupt) 79when the kernel prepares a return to user-mode execution. 80This case is 81typically handled by machine dependent trap-handling code after detection 82of a change in the signal disposition of the current process, or when a 83higher priority thread might be available to run. 84The latter event is 85communicated by the machine independent scheduling routines by calling 86the machine defined 87.Fn need_resched . 88.It 89In the signal handling code 90(see 91.Xr issignal 9 ) 92if a signal is delivered that causes a process to stop. 93.It 94When a thread dies in 95.Xr thread_exit 9 96and control of the processor can be passed to the next runnable thread. 97.It 98In 99.Xr thread_suspend_check 9 100where a thread needs to stop execution due to the suspension state of 101the process as a whole. 102.El 103.Pp 104.Fn mi_switch 105records the amount of time the current thread has been running in the 106process structures and checks this value against the CPU time limits 107allocated to the process 108(see 109.Xr getrlimit 2 ) . 110Exceeding the soft limit results in a 111.Dv SIGXCPU 112signal to be posted to the process, while exceeding the hard limit will 113cause a 114.Dv SIGKILL . 115.Pp 116If the thread is still in the 117.Dv TDS_RUNNING 118state, 119.Fn mi_switch 120will put it back onto the run queue, assuming that 121it will want to run again soon. 122If it is in one of the other 123states and KSE threading is enabled, the associated 124.Em KSE 125will be made available to any higher priority threads from the same 126group, to allow them to be scheduled next. 127.Pp 128After these administrative tasks are done, 129.Fn mi_switch 130hands over control to the machine dependent routine 131.Fn cpu_switch , 132which will perform the actual thread context switch. 133.Pp 134.Fn cpu_switch 135first saves the context of the current thread. 136Next, it calls 137.Fn choosethread 138to determine which thread to run next. 139Finally, it reads in the saved context of the new thread and starts to 140execute the new thread. 141.Pp 142.Fn cpu_throw 143is similar to 144.Fn cpu_switch 145except that it does not save the context of the old thread. 146This function is useful when the kernel does not have an old thread 147context to save, such as when CPUs other than the boot CPU perform their 148first task switch, or when the kernel does not care about the state of the 149old thread, such as in 150.Fn thread_exit 151when the kernel terminates the current thread and switches into a new 152thread. 153.Pp 154To protect the 155.Xr runqueue 9 , 156all of these functions must be called with the 157.Va sched_lock 158mutex held. 159.Sh SEE ALSO 160.Xr cv_wait 9 , 161.Xr issignal 9 , 162.Xr mutex 9 , 163.Xr runqueue 9 , 164.Xr tsleep 9 , 165.Xr wakeup 9 166