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.\" Copyright (c) 2023 The FreeBSD Foundation 6.\" 7.\" This code is derived from software contributed to The NetBSD Foundation 8.\" by Paul Kranenburg. 9.\" 10.\" Portions of this documentation were written by Mitchell Horne 11.\" under sponsorship from the FreeBSD Foundation. 12.\" 13.\" Redistribution and use in source and binary forms, with or without 14.\" modification, are permitted provided that the following conditions 15.\" are met: 16.\" 1. Redistributions of source code must retain the above copyright 17.\" notice, this list of conditions and the following disclaimer. 18.\" 2. Redistributions in binary form must reproduce the above copyright 19.\" notice, this list of conditions and the following disclaimer in the 20.\" documentation and/or other materials provided with the distribution. 21.\" 22.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 23.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 24.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 25.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE 26.\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 27.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 28.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 29.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 30.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 31.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 32.\" POSSIBILITY OF SUCH DAMAGE. 33.\" 34.Dd January 7, 2025 35.Dt MI_SWITCH 9 36.Os 37.Sh NAME 38.Nm mi_switch 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 "int flags" 45.Sh DESCRIPTION 46The 47.Fn mi_switch 48function implements the machine-independent prelude to a thread context 49switch. 50It is the single entry point for every context switch and is called from only 51a few distinguished places in the kernel. 52The context switch is, by necessity, always performed by the switched thread, 53even when the switch is initiated from elsewhere; e.g. preemption requested via 54Inter-Processor Interrupt (IPI). 55.Pp 56The various major uses of 57.Fn mi_switch 58can be enumerated as follows: 59.Bl -enum -offset indent 60.It 61From within a function such as 62.Xr sleepq_wait 9 63or 64.Fn turnstile_wait 65when the current thread 66voluntarily relinquishes the CPU to wait for some resource or lock to become 67available. 68.It 69Involuntary preemption due to arrival of a higher-priority thread. 70.It 71At the tail end of 72.Xr critical_exit 9 , 73if preemption was deferred due to the critical section. 74.It 75Within the TDA_SCHED AST handler, when rescheduling before the return to 76usermode was requested. 77There are several reasons for this, a notable one coming from 78.Fn sched_clock 79when the running thread has exceeded its time slice. 80.It 81In the signal handling code 82(see 83.Xr issignal 9 ) 84if a signal is delivered that causes a process to stop. 85.It 86In 87.Fn thread_suspend_check 88where a thread needs to stop execution due to the suspension state of 89the process as a whole. 90.It 91In 92.Xr kern_yield 9 93when a thread wants to voluntarily relinquish the processor. 94.El 95.Pp 96The 97.Va flags 98argument to 99.Fn mi_switch 100indicates the context switch type. 101One of the following must be passed: 102.Bl -tag -offset indent -width "SWT_REMOTEWAKEIDLE" 103.It Dv SWT_OWEPREEMPT 104Switch due to delayed preemption after exiting a critical section. 105.It Dv SWT_TURNSTILE 106Switch after propagating scheduling priority to the owner of a resource. 107.It Dv SWT_SLEEPQ 108Begin waiting on a 109.Xr sleepqueue 9 . 110.It Dv SWT_RELINQUISH 111Yield call. 112.It Dv SWT_NEEDRESCHED 113Rescheduling was requested. 114.It Dv SWT_IDLE 115Switch from the idle thread. 116.It Dv SWT_IWAIT 117A kernel thread which handles interrupts has finished work and must wait for 118interrupts to schedule additional work. 119.It Dv SWT_SUSPEND 120Thread suspended. 121.It Dv SWT_REMOTEPREEMPT 122Preemption by a higher-priority thread, initiated by a remote processor. 123.It Dv SWT_REMOTEWAKEIDLE 124Idle thread preempted, initiated by a remote processor. 125.It Dv SWT_BIND 126The running thread has been bound to another processor and must be switched 127out. 128.El 129.Pp 130In addition to the switch type, callers must specify the nature of the 131switch by performing a bitwise OR with one of the 132.Dv SW_VOL 133or 134.Dv SW_INVOL 135flags, but not both. 136Respectively, these flags denote whether the context switch is voluntary or 137involuntary on the part of the current thread. 138For an involuntary context switch in which the running thread is 139being preempted, the caller should also pass the 140.Dv SW_PREEMPT 141flag. 142.Pp 143Upon entry to 144.Fn mi_switch , 145the current thread must be holding its assigned thread lock. 146It may be unlocked as part of the context switch. 147After they have been rescheduled and execution resumes, threads will exit 148.Fn mi_switch 149with their thread lock unlocked. 150.Pp 151.Fn mi_switch 152records the amount of time the current thread has been running before handing 153control over to the scheduler, via 154.Fn sched_switch . 155After selecting a new thread to run, the scheduler will call 156.Fn cpu_switch 157to perform the low-level context switch. 158.Pp 159.Fn cpu_switch 160is the machine-dependent function that performs the actual switch from the 161running thread 162.Fa oldtd 163to the chosen thread 164.Fa newtd . 165.Sh SEE ALSO 166.Xr cpu_switch 9 , 167.Xr cpu_throw 9 , 168.Xr critical_exit 9 , 169.Xr issignal 9 , 170.Xr kern_yield 9 , 171.Xr mutex 9 , 172.Xr pmap 9 , 173.Xr sleepqueue 9 , 174.Xr thread_exit 9 175