1 .\" $NetBSD: ctxsw.9,v 1.2 1996/12/02 00:11:31 tls Exp $
3 .\" Copyright (c) 1996 The NetBSD Foundation, Inc.
4 .\" All rights reserved.
5 .\" Copyright (c) 2023 The FreeBSD Foundation
7 .\" This code is derived from software contributed to The NetBSD Foundation
8 .\" by Paul Kranenburg.
10 .\" Portions of this documentation were written by Mitchell Horne
11 .\" under sponsorship from the FreeBSD Foundation.
13 .\" Redistribution and use in source and binary forms, with or without
14 .\" modification, are permitted provided that the following conditions
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.
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.
41 .Nd switch to another thread context
46 .Fn mi_switch "int flags"
48 .Fn cpu_switch "struct thread *oldtd" "struct thread *newtd" "struct mtx *lock"
50 .Fn cpu_throw "struct thread *oldtd" "struct thread *newtd"
54 function implements the machine-independent prelude to a thread context
56 It is the single entry point for every context switch and is called from only
57 a few distinguished places in the kernel.
58 The context switch is, by necessity, always performed by the switched thread,
59 even when the switch is initiated from elsewhere; e.g. preemption requested via
60 Inter-Processor Interrupt (IPI).
62 The various major uses of
64 can be enumerated as follows:
65 .Bl -enum -offset indent
67 From within a function such as
71 when the current thread
72 voluntarily relinquishes the CPU to wait for some resource or lock to become
75 Involuntary preemption due to arrival of a higher-priority thread.
79 if preemption was deferred due to the critical section.
81 Within the TDA_SCHED AST handler, when rescheduling before the return to
82 usermode was requested.
83 There are several reasons for this, a notable one coming from
85 when the running thread has exceeded its time slice.
87 In the signal handling code
90 if a signal is delivered that causes a process to stop.
93 .Fn thread_suspend_check
94 where a thread needs to stop execution due to the suspension state of
95 the process as a whole.
99 when a thread wants to voluntarily relinquish the processor.
106 indicates the context switch type.
107 One of the following must be passed:
108 .Bl -tag -offset indent -width "SWT_REMOTEWAKEIDLE"
109 .It Dv SWT_OWEPREEMPT
110 Switch due to delayed preemption after exiting a critical section.
112 Switch after propagating scheduling priority to the owner of a resource.
116 .It Dv SWT_RELINQUISH
118 .It Dv SWT_NEEDRESCHED
119 Rescheduling was requested.
121 Switch from the idle thread.
123 A kernel thread which handles interrupts has finished work and must wait for
124 interrupts to schedule additional work.
127 .It Dv SWT_REMOTEPREEMPT
128 Preemption by a higher-priority thread, initiated by a remote processor.
129 .It Dv SWT_REMOTEWAKEIDLE
130 Idle thread preempted, initiated by a remote processor.
132 The running thread has been bound to another processor and must be switched
136 In addition to the switch type, callers must specify the nature of the
137 switch by performing a bitwise OR with one of the
142 Respectively, these flags denote whether the context switch is voluntary or
143 involuntary on the part of the current thread.
144 For an involuntary context switch in which the running thread is
145 being preempted, the caller should also pass the
151 the current thread must be holding its assigned thread lock.
152 It may be unlocked as part of the context switch.
153 After they have been rescheduled and execution resumes, threads will exit
155 with their thread lock unlocked.
158 records the amount of time the current thread has been running before handing
159 control over to the scheduler, via
161 After selecting a new thread to run, the scheduler will call
163 to perform the low-level context switch.
166 is the machine-dependent function that performs the actual switch from the
171 First, it saves the context of
173 to its Process Control Block
180 The function then updates important per-CPU state such as the
182 variable, and activates
184 virtual address space using its associated
187 Finally, it reads in the saved context from
190 CPU instruction flow continues in the new thread context, on
195 can be understood as a completion of the function call initiated by
197 when it was previously switched out, at some point in the distant (relative to
204 is used to pass the mutex which will be stored as
206 thread lock at the moment that
208 is completely switched out.
209 This is an implementation detail of
215 except that it does not save the context of the old thread.
216 This function is useful when the kernel does not have an old thread
217 context to save, such as when CPUs other than the boot CPU perform their
218 first task switch, or when the kernel does not care about the state of the
219 old thread, such as in
221 when the kernel terminates the current thread and switches into a new
228 .Xr critical_exit 9 ,