| blob | 5b38d9c71ad37df06c9f106c0be44b4976f4c0bb |
1 .\" $NetBSD: mi_switch.9,v 1.2 2008/04/30 13:10:58 martin Exp $
2 .\"
3 .\" Copyright (c) 1996, 2002 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 FOUNDATION OR CONTRIBUTORS
22 .\" BE 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 .Dd July 21, 2007
31 .Dt MI_SWITCH 9
32 .Os
33 .Sh NAME
34 .Nm mi_switch
35 .Nd machine independent context switch prelude
36 .Sh SYNOPSIS
37 .Ft int
38 .Fn mi_switch "struct lwp *l"
39 .Sh DESCRIPTION
40 The
41 .Fn mi_switch
42 function implements the machine-independent prelude to an LWP context
43 switch.
44 It is called from only a few distinguished places in the kernel
45 code as a result of the principle of non-preemptable kernel mode
46 execution.
47 The three major uses of
48 .Fn mi_switch
49 can be enumerated as follows:
50 .Bl -enum -offset indent
51 .It
52 From within
53 .Xr cv_wait 9
54 and associated methods
55 when the current LWP voluntarily relinquishes the CPU to wait for
56 some resource to become available.
57 .It
58 From within
59 .Xr preempt 9
60 when the current LWP voluntarily relinquishes the CPU or when the
61 kernel prepares a return to user-mode execution.
62 .It
63 In the signal handling code
64 if a signal is delivered that causes an LWP to stop
65 .Pq see Xr issignal 9 .
66 .El
67 .Pp
68 .Fn mi_switch
69 records the amount of time the current LWP has been running in the
70 LWP structure and checks this value against the CPU time limits
71 allocated to the LWP
72 .Pq see Xr getrlimit 2 .
73 Exceeding the soft limit results in a
74 .Dv SIGXCPU
75 signal to be posted to the LWP, while exceeding the hard limit will
76 cause a
77 .Dv SIGKILL .
78 .Pp
79 Unless
80 .Fa l-\*[Gt]l_switchto
81 is not
82 .Dv NULL ,
83 .Fn mi_switch
84 will call
85 .Fn sched_nextlwp
86 to select a new LWP from the scheduler's runqueue structures.
87 If no runnable LWP is found, the idle LWP is used.
88 If the new LWP is not equal to the current one,
89 .Fn mi_switch
90 will hand over control to the machine-dependent function
91 .Xr cpu_switchto 9
92 to switch to the new LWP.
93 .Pp
94 .Fn mi_switch
95 has to be called with the LWP lock held
96 (through calling
97 .Fn lwp_lock
98 first) and at the
99 .Xr splsched 9
100 interrupt protection level.
101 It returns with the LWP lock released.
102 .Sh RETURN VALUES
103 .Fn mi_switch
104 returns 1 if a context switch was performed to a
105 different LWP, 0 otherwise.
106 .Sh SEE ALSO
107 .Xr condvar 9 ,
108 .Xr cpu_switchto 9 ,
109 .Xr csf 9 ,
110 .Xr pmap 9 ,
111 .Xr ras 9 ,
112 .Xr sched_4bsd 9 ,
113 .Xr splsched 9