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