Page MenuHomeFreeBSD
Files F108592332

D38185.id115562.diff
No OneTemporary
Actions

D38185.id115562.diff
View Options

diff --git a/share/man/man9/mi_switch.9 b/share/man/man9/mi_switch.9
--- a/share/man/man9/mi_switch.9
+++ b/share/man/man9/mi_switch.9
@@ -2,10 +2,14 @@
.\"
.\" Copyright (c) 1996 The NetBSD Foundation, Inc.
.\" All rights reserved.
+.\" Copyright (c) 2023 The FreeBSD Foundation
.\"
.\" This code is derived from software contributed to The NetBSD Foundation
.\" by Paul Kranenburg.
.\"
+.\" Portions of this documentation were written by Mitchell Horne
+.\" under sponsorship from the FreeBSD Foundation.
+.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
@@ -29,7 +33,7 @@
.\"
.\" $FreeBSD$
.\"
-.Dd November 24, 1996
+.Dd January 9, 2023
.Dt MI_SWITCH 9
.Os
.Sh NAME
@@ -41,32 +45,34 @@
.In sys/param.h
.In sys/proc.h
.Ft void
-.Fn mi_switch "void"
+.Fn mi_switch "int flags"
.Ft void
-.Fn cpu_switch "void"
+.Fn cpu_switch "struct thread *oldtd" "struct thread *newtd" "struct mtx *lock"
.Ft void
-.Fn cpu_throw "void"
+.Fn cpu_throw "struct thread *oldtd" "struct thread *newtd"
.Sh DESCRIPTION
The
.Fn mi_switch
function implements the machine independent prelude to a thread context
switch.
-It is called from only a few distinguished places in the kernel
-code as a result of the principle of non-preemptable kernel mode execution.
+It is called from only a few distinguished places in the kernel.
The various major uses of
-.Nm
+.Fn mi_switch
can be enumerated as follows:
.Bl -enum -offset indent
.It
From within a function such as
-.Xr cv_wait 9 ,
-.Xr mtx_lock 9 ,
+.Xr sleepqueue_wait 9
or
-.Xr tsleep 9
+.Fn turnstile_wait
when the current thread
voluntarily relinquishes the CPU to wait for some resource or lock to become
available.
.It
+At the tail end of
+.Xr critical_exit 9 ,
+if preemption was deferred due to the critical section.
+.It
After handling a trap
(e.g.\& a system call, device interrupt)
when the kernel prepares a return to user-mode execution.
@@ -74,63 +80,106 @@
typically handled by machine dependent trap-handling code after detection
of a change in the signal disposition of the current process, or when a
higher priority thread might be available to run.
-The latter event is
-communicated by the machine independent scheduling routines by calling
-the machine defined
-.Fn need_resched .
.It
In the signal handling code
(see
.Xr issignal 9 )
if a signal is delivered that causes a process to stop.
.It
-When a thread dies in
-.Xr thread_exit 9
-and control of the processor can be passed to the next runnable thread.
-.It
In
-.Xr thread_suspend_check 9
+.Fn thread_suspend_check
where a thread needs to stop execution due to the suspension state of
the process as a whole.
+.It
+In
+.Xr kern_yield 9
+when a thread wants to voluntarily relinquish the processor.
.El
.Pp
+The
+.Va flags
+argument to
.Fn mi_switch
-records the amount of time the current thread has been running in the
-process structures and checks this value against the CPU time limits
-allocated to the process
-(see
-.Xr getrlimit 2 ) .
-Exceeding the soft limit results in a
-.Dv SIGXCPU
-signal to be posted to the process, while exceeding the hard limit will
-cause a
-.Dv SIGKILL .
+indicates the context switch type.
+One of the following should be passed:
+.Bl -tag -offset indent -width "SWT_REMOTEWAKEIDLE"
+.It Dv SWT_NONE
+Unspecified switch.
+.It Dv SWT_OWEPREEMPT
+Switch due to delayed preemption after exiting a critical section.
+.It Dv SWT_TURNSTILE
+Switch due to contention on a turnstile.
+.It Dv SWT_SLEEPQ
+Begin waiting on a
+.Xr sleepqueue 9 .
+.It Dv SWT_RELINQUISH
+Yield call.
+.It Dv SWT_NEEDRESCHED
+Rescheduling was requested.
+.It Dv SWT_IDLE
+Switch from the idle thread.
+.It Dv SWT_IWAIT
+A kernel thread has finished work and must wait for interrupts.
+.It Dv SWT_SUSPEND
+Thread suspended.
+.It Dv SWT_REMOTEPREEMPT
+Preemption by a higher-priority thread, initiated by a remote processor.
+.It Dv SWT_REMOTEWAKEIDLE
+Idle thread preempted, initiated by a remote processor.
+.El
.Pp
-If the thread is still in the
-.Dv TDS_RUNNING
-state,
-.Fn mi_switch
-will put it back onto the run queue, assuming that
-it will want to run again soon.
-If it is in one of the other
-states and KSE threading is enabled, the associated
-.Em KSE
-will be made available to any higher priority threads from the same
-group, to allow them to be scheduled next.
+In addition to the switch type, callers should specify the nature of the
+switch by performing a bitwise OR with one of the
+.Dv SW_VOL
+or
+.Dv SW_INVOL
+flags, but not both.
+Respectively, these flags denote whether the context switch is voluntary or
+involuntary on the part of the current thread.
+For an involuntary context switch in which the running thread is
+being preempted, the caller should also pass the
+.Dv SW_PREEMPT
+flag.
+.Pp
+Upon entry to
+.Fn mi_switch ,
+the current thread must be holding its thread lock.
+Upon return, the thread lock for the newly activated thread will be unlocked.
.Pp
-After these administrative tasks are done,
.Fn mi_switch
-hands over control to the machine dependent routine
+records the amount of time the current thread has been running before handing
+control over to the scheduler, via
+.Fn sched_switch .
+After selecting a new thread to run, the scheduler will call
+.Fn cpu_switch
+to perform the low-level context switch.
+.Pp
+.Fn cpu_switch
+is the machine-dependent function that performs the actual switch from the running thread
+.Fa oldtd
+to the chosen thread
+.Fa newtd .
+First, it saves the context of
+.Fa oldtd
+to its PCB (Process Control Block).
+The function then updates important per-CPU state such as the
+.Dv curthread
+variable, and activates the new thread's virtual address space using its
+associated
+.Xr pmap 9
+structure.
+Finally, it reads in the saved context from the new thread's PCB.
+Upon exit from
.Fn cpu_switch ,
-which will perform the actual thread context switch.
+execution continues in the new thread context.
.Pp
+The
+.Fa mtx
+argument to
.Fn cpu_switch
-first saves the context of the current thread.
-Next, it calls
-.Fn choosethread
-to determine which thread to run next.
-Finally, it reads in the saved context of the new thread and starts to
-execute the new thread.
+is used to pass a
+.Xr mutex 9
+TODO: finish this paragraph.
.Pp
.Fn cpu_throw
is similar to
@@ -140,19 +189,18 @@
context to save, such as when CPUs other than the boot CPU perform their
first task switch, or when the kernel does not care about the state of the
old thread, such as in
-.Fn thread_exit
+.Xr thread_exit 9
when the kernel terminates the current thread and switches into a new
-thread.
-.Pp
-To protect the
-.Xr runqueue 9 ,
-all of these functions must be called with the
-.Va sched_lock
-mutex held.
+thread,
+.Fa newtd .
+The
+.Fa oldtd
+argument is unused.
.Sh SEE ALSO
-.Xr cv_wait 9 ,
+.Xr critical_exit 9 ,
.Xr issignal 9 ,
+.Xr kern_yield 9 ,
.Xr mutex 9 ,
-.Xr runqueue 9 ,
-.Xr tsleep 9 ,
-.Xr wakeup 9
+.Xr pmap 9 ,
+.Xr sleepqueue 9 ,
+.Xr thread_exit 9

File Metadata

Mime Type
text/plain
Expires
Mon, Jan 27, 5:58 PM (4 h, 47 m)
Storage Engine
blob
Storage Format
Raw Data
Storage Handle
16202504
Default Alt Text
D38185.id115562.diff (6 KB)

Event Timeline