Attachment #108689 for bug #149574

View | Details | Raw Unified | Return to bug 149574
Collapse All | Expand All




.\"	$NetBSD: ctxsw.9,v 1.3 1997/10/08 22:00:23 jtc Exp $
.\"
.\" Copyright (c) 1996 The NetBSD Foundation, Inc.
.\" All rights reserved.

.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN

.\"
.\" $FreeBSD$
.\"
.Dd August 12, 2010
.Dt MI_SWITCH 9
.Os
.Sh NAME

.In sys/param.h
.In sys/proc.h
.Ft void
.Fn mi_switch "int flags" "struct thread *newtd"
.Ft void
.Fn cpu_switch "struct thread *td" "struct thread *newtd" "struct mtx *td_lock"
.Ft void
.Fn cpu_throw "struct thread *td" "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.
The various major uses of the
.Fn mi_switch
function can be enumerated as follows:
.Bl -enum -offset indent
.It
From within a function such as

(e.g.\& a system call, device interrupt)
when the kernel prepares a return to user-mode execution.
This case is
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 setting
the needresched thread state.
.Fn need_resched .
.It
In the signal handling code
(see

the process as a whole.
.El
.Pp
The
.Fn mi_switch
function
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

.Pp
If the thread is still in the
.Dv TDS_RUNNING
state, the
.Fn mi_switch
function
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.
.Pp
If a
.Fa newtd
thread is
.Dv NULL ,
the
.Fn mi_switch
function will hand over control to the machine-dependent
.Fn cpu_switch
function to select a new thread from the system run queue.
If a new thread is specified, then the CPU will switch to that thread
directly rather than calling
.Xr choosethread 9
to pick a thread to choose to.
The
.Fa flags
argument specifies a conjunction of the types and flags for the
.Fn mi_switch
function.
The currently understood flags are:
.Pp
.Bd -literal -offset indent -compact
SW_VOL		Voluntary switch,
SW_INVOL	Involuntary switch,
SW_PREEMPT	Involuntary switch is a preemption
.Ed
.Pp
Currently defined types are:
.Pp
.Bd -literal -offset indent -compact
SW_TYPE_MASK		First 8 bits are switch type,
SWT_NONE		Unspecified switch,
SWT_PREEMPT		Switching due to preemption,
SWT_OWEPREEMPT		Switching due to opepreempt,
SWT_TURNSTILE		Turnstile contention,
SWT_SLEEPQ		Sleepq wait,
SWT_SLEEPQTIMO		Sleepq timeout wait,
SWT_RELINQUISH		yield call,
SWT_NEEDRESCHED		NEEDRESCHED was set,
SWT_IDLE		Switching from the idle thread,
SWT_IWAIT		Waiting for interrupts,
SWT_SUSPEND		Thread suspended,
SWT_REMOTEPREEMPT	Remote processor preempted,
SWT_REMOTEWAKEIDLE	Remote processor preempted idle
.Ed
.Pp
The
.Fn cpu_switch
function first saves the context of the current thread
.Fa td .
Then it reads in the saved context of the new thread
.Fa newtd
and starts to execute the new thread with the switchout
.Fa td_lock
mutex held.
.Pp
The
.Fn cpu_throw
function is similar to the
.Fn cpu_switch
function
except that the former does not save the context of the old
.Fa td
thread.
This function is useful when the kernel does not have an old thread
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
.Xr thread_exit 9
when the kernel terminates the current thread and switches into a new
.Fa newtd
thread.
.Pp
To protect the
.Xr runqueue 9 ,
all of these functions must be called with the
.Va sched_lock
mutex held.
.Sh SEE ALSO
.Xr choosethread 9 ,
.Xr cv_wait 9 ,
.Xr issignal 9 ,
.Xr mutex 9 ,
.Xr runqueue 9 ,
.Xr tsleep 9 ,
.Xr thread_exit 9 ,
.Xr wakeup 9

Return to bug 149574

Lines 1-4 Link Here

(-)share/man/man9/mi_switch.9 (-40 / +79 lines)
1	.\" $NetBSD: ctxsw.9,v 1.2 1996/12/02 00:11:31 tls Exp $	1	.\" $NetBSD: ctxsw.9,v 1.3 1997/10/08 22:00:23 jtc Exp $
2	.\"	2	.\"
3	.\" Copyright (c) 1996 The NetBSD Foundation, Inc.	3	.\" Copyright (c) 1996 The NetBSD Foundation, Inc.
4	.\" All rights reserved.	4	.\" All rights reserved.
Lines 18-25 Link Here
18	.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS	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	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	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	21	.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
22	.\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR	22	.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
23	.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF	23	.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
24	.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS	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	25	.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
Lines 29-35 Link Here
29	.\"	29	.\"
30	.\" $FreeBSD$	30	.\" $FreeBSD$
31	.\"	31	.\"
32	.Dd November 24, 1996	32	.Dd August 12, 2010
33	.Dt MI_SWITCH 9	33	.Dt MI_SWITCH 9
34	.Os	34	.Os
35	.Sh NAME	35	.Sh NAME
Lines 41-61 Link Here
41	.In sys/param.h	41	.In sys/param.h
42	.In sys/proc.h	42	.In sys/proc.h
43	.Ft void	43	.Ft void
44	.Fn mi_switch "void"	44	.Fn mi_switch "int flags" "struct thread *newtd"
45	.Ft void	45	.Ft void
46	.Fn cpu_switch "void"	46	.Fn cpu_switch "struct thread td" "struct thread newtd" "struct mtx *td_lock"
47	.Ft void	47	.Ft void
48	.Fn cpu_throw "void"	48	.Fn cpu_throw "struct thread td" "struct thread newtd"
49	.Sh DESCRIPTION	49	.Sh DESCRIPTION
50	The	50	The
51	.Fn mi_switch	51	.Fn mi_switch
52	function implements the machine independent prelude to a thread context	52	function implements the machine-independent prelude to a thread context
53	switch.	53	switch.
54	It is called from only a few distinguished places in the kernel	54	It is called from only a few distinguished places in the kernel
55	code as a result of the principle of non-preemptable kernel mode execution.	55	code as a result of the principle of non-preemptable kernel mode execution.
56	The various major uses of	56	The various major uses of the
57	.Nm	57	.Fn mi_switch
58	can be enumerated as follows:	58	function can be enumerated as follows:
59	.Bl -enum -offset indent	59	.Bl -enum -offset indent
60	.It	60	.It
61	From within a function such as	61	From within a function such as
Lines 71-83 Link Here
71	(e.g.\& a system call, device interrupt)	71	(e.g.\& a system call, device interrupt)
72	when the kernel prepares a return to user-mode execution.	72	when the kernel prepares a return to user-mode execution.
73	This case is	73	This case is
74	typically handled by machine dependent trap-handling code after detection	74	typically handled by machine-dependent trap-handling code after detection
75	of a change in the signal disposition of the current process, or when a	75	of a change in the signal disposition of the current process, or when a
76	higher priority thread might be available to run.	76	higher priority thread might be available to run.
77	The latter event is	77	The latter event is
78	communicated by the machine independent scheduling routines by calling	78	communicated by the machine-independent scheduling routines by setting
79	the machine defined	79	the needresched thread state.
80	.Fn need_resched .
81	.It	80	.It
82	In the signal handling code	81	In the signal handling code
83	(see	82	(see
Lines 94-100 Link Here
94	the process as a whole.	93	the process as a whole.
95	.El	94	.El
96	.Pp	95	.Pp
		96	The
97	.Fn mi_switch	97	.Fn mi_switch
		98	function
98	records the amount of time the current thread has been running in the	99	records the amount of time the current thread has been running in the
99	process structures and checks this value against the CPU time limits	100	process structures and checks this value against the CPU time limits
100	allocated to the process	101	allocated to the process
Lines 108-158 Link Here
108	.Pp	109	.Pp
109	If the thread is still in the	110	If the thread is still in the
110	.Dv TDS_RUNNING	111	.Dv TDS_RUNNING
111	state,	112	state, the
112	.Fn mi_switch	113	.Fn mi_switch
		114	function
113	will put it back onto the run queue, assuming that	115	will put it back onto the run queue, assuming that
114	it will want to run again soon.	116	it will want to run again soon.
115	If it is in one of the other
116	states and KSE threading is enabled, the associated
117	.Em KSE
118	will be made available to any higher priority threads from the same
119	group, to allow them to be scheduled next.
120	.Pp	117	.Pp
121	After these administrative tasks are done,	118	If a
		119	.Fa newtd
		120	thread is
		121	.Dv NULL ,
		122	the
122	.Fn mi_switch	123	.Fn mi_switch
123	hands over control to the machine dependent routine	124	function will hand over control to the machine-dependent
124	.Fn cpu_switch ,	125	.Fn cpu_switch
125	which will perform the actual thread context switch.	126	function to select a new thread from the system run queue.
		127	If a new thread is specified, then the CPU will switch to that thread
		128	directly rather than calling
		129	.Xr choosethread 9
		130	to pick a thread to choose to.
		131	The
		132	.Fa flags
		133	argument specifies a conjunction of the types and flags for the
		134	.Fn mi_switch
		135	function.
		136	The currently understood flags are:
126	.Pp	137	.Pp
		138	.Bd -literal -offset indent -compact
		139	SW_VOL Voluntary switch,
		140	SW_INVOL Involuntary switch,
		141	SW_PREEMPT Involuntary switch is a preemption
		142	.Ed
		143	.Pp
		144	Currently defined types are:
		145	.Pp
		146	.Bd -literal -offset indent -compact
		147	SW_TYPE_MASK First 8 bits are switch type,
		148	SWT_NONE Unspecified switch,
		149	SWT_PREEMPT Switching due to preemption,
		150	SWT_OWEPREEMPT Switching due to opepreempt,
		151	SWT_TURNSTILE Turnstile contention,
		152	SWT_SLEEPQ Sleepq wait,
		153	SWT_SLEEPQTIMO Sleepq timeout wait,
		154	SWT_RELINQUISH yield call,
		155	SWT_NEEDRESCHED NEEDRESCHED was set,
		156	SWT_IDLE Switching from the idle thread,
		157	SWT_IWAIT Waiting for interrupts,
		158	SWT_SUSPEND Thread suspended,
		159	SWT_REMOTEPREEMPT Remote processor preempted,
		160	SWT_REMOTEWAKEIDLE Remote processor preempted idle
		161	.Ed
		162	.Pp
		163	The
127	.Fn cpu_switch	164	.Fn cpu_switch
128	first saves the context of the current thread.	165	function first saves the context of the current thread
129	Next, it calls	166	.Fa td .
130	.Fn choosethread	167	Then it reads in the saved context of the new thread
131	to determine which thread to run next.	168	.Fa newtd
132	Finally, it reads in the saved context of the new thread and starts to	169	and starts to execute the new thread with the switchout
133	execute the new thread.	170	.Fa td_lock
		171	mutex held.
134	.Pp	172	.Pp
		173	The
135	.Fn cpu_throw	174	.Fn cpu_throw
136	is similar to	175	function is similar to the
137	.Fn cpu_switch	176	.Fn cpu_switch
138	except that it does not save the context of the old thread.	177	function
		178	except that the former does not save the context of the old
		179	.Fa td
		180	thread.
139	This function is useful when the kernel does not have an old thread	181	This function is useful when the kernel does not have an old thread
140	context to save, such as when CPUs other than the boot CPU perform their	182	context to save, such as when CPUs other than the boot CPU perform their
141	first task switch, or when the kernel does not care about the state of the	183	first task switch, or when the kernel does not care about the state of the
142	old thread, such as in	184	old thread, such as in
143	.Fn thread_exit	185	.Xr thread_exit 9
144	when the kernel terminates the current thread and switches into a new	186	when the kernel terminates the current thread and switches into a new
		187	.Fa newtd
145	thread.	188	thread.
146	.Pp
147	To protect the
148	.Xr runqueue 9 ,
149	all of these functions must be called with the
150	.Va sched_lock
151	mutex held.
152	.Sh SEE ALSO	189	.Sh SEE ALSO
		190	.Xr choosethread 9 ,
153	.Xr cv_wait 9 ,	191	.Xr cv_wait 9 ,
154	.Xr issignal 9 ,	192	.Xr issignal 9 ,
155	.Xr mutex 9 ,	193	.Xr mutex 9 ,
156	.Xr runqueue 9 ,	194	.Xr runqueue 9 ,
157	.Xr tsleep 9 ,	195	.Xr tsleep 9 ,
		196	.Xr thread_exit 9 ,
158	.Xr wakeup 9	197	.Xr wakeup 9