Sun Mar 15 14:05:18 2009 UTC ()
Consistently provide -width for tag lists.


(joerg)
diff -r1.4 -r1.5 src/share/man/man9/csf.9
cvs diff -r1.4 -r1.5 src/share/man/man9/csf.9 (switch to unified diff)

--- src/share/man/man9/csf.9 2008/04/30 13:10:58 1.4
+++ src/share/man/man9/csf.9 2009/03/15 14:05:18 1.5
@@ -1,216 +1,216 @@ @@ -1,216 +1,216 @@
1.\" $NetBSD: csf.9,v 1.4 2008/04/30 13:10:58 martin Exp $ 1.\" $NetBSD: csf.9,v 1.5 2009/03/15 14:05:18 joerg Exp $
2.\" 2.\"
3.\" Copyright (c) 2002 The NetBSD Foundation, Inc. 3.\" Copyright (c) 2002 The NetBSD Foundation, Inc.
4.\" All rights reserved. 4.\" All rights reserved.
5.\" 5.\"
6.\" This code is derived from software contributed to The NetBSD Foundation 6.\" This code is derived from software contributed to The NetBSD Foundation
7.\" by Daniel Sieger. 7.\" by Daniel Sieger.
8.\" 8.\"
9.\" Redistribution and use in source and binary forms, with or without 9.\" Redistribution and use in source and binary forms, with or without
10.\" modification, are permitted provided that the following conditions 10.\" modification, are permitted provided that the following conditions
11.\" are met: 11.\" are met:
12.\" 1. Redistributions of source code must retain the above copyright 12.\" 1. Redistributions of source code must retain the above copyright
13.\" notice, this list of conditions and the following disclaimer. 13.\" notice, this list of conditions and the following disclaimer.
14.\" 2. Redistributions in binary form must reproduce the above copyright 14.\" 2. Redistributions in binary form must reproduce the above copyright
15.\" notice, this list of conditions and the following disclaimer in the 15.\" notice, this list of conditions and the following disclaimer in the
16.\" documentation and/or other materials provided with the distribution. 16.\" documentation and/or other materials provided with the distribution.
17.\" 17.\"
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 FOUNDATION OR CONTRIBUTORS 21.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
22.\" BE 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
26.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 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 27.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
28.\" POSSIBILITY OF SUCH DAMAGE. 28.\" POSSIBILITY OF SUCH DAMAGE.
29.\" 29.\"
30.Dd July 14, 2007 30.Dd July 14, 2007
31.Dt CSF 9 31.Dt CSF 9
32.Os 32.Os
33.Sh NAME 33.Sh NAME
34.Nm CSF 34.Nm CSF
35.Nd The 35.Nd The
36.Nx 36.Nx
37common scheduler framework 37common scheduler framework
38.Sh SYNOPSIS 38.Sh SYNOPSIS
39.In sys/sched.h 39.In sys/sched.h
40.Ft void 40.Ft void
41.Fn sched_rqinit "void" 41.Fn sched_rqinit "void"
42.Ft void 42.Ft void
43.Fn sched_setup "void" 43.Fn sched_setup "void"
44.Ft void 44.Ft void
45.Fn sched_cpuattach "struct cpu_info *" 45.Fn sched_cpuattach "struct cpu_info *"
46.Ft void 46.Ft void
47.Fn sched_tick "struct cpu_info *" 47.Fn sched_tick "struct cpu_info *"
48.Ft void 48.Ft void
49.Fn sched_schedclock "lwp_t *" 49.Fn sched_schedclock "lwp_t *"
50.Ft bool 50.Ft bool
51.Fn sched_curcpu_runnable_p "void" 51.Fn sched_curcpu_runnable_p "void"
52.Ft lwp_t * 52.Ft lwp_t *
53.Fn sched_nextlwp "void" 53.Fn sched_nextlwp "void"
54.Ft void 54.Ft void
55.Fn sched_enqueue "lwp_t *" "bool" 55.Fn sched_enqueue "lwp_t *" "bool"
56.Ft void 56.Ft void
57.Fn sched_dequeue "lwp_t *" 57.Fn sched_dequeue "lwp_t *"
58.Ft void 58.Ft void
59.Fn sched_nice "struct proc *" "int" 59.Fn sched_nice "struct proc *" "int"
60.Ft void 60.Ft void
61.Fn sched_proc_fork "struct proc *" "struct proc *" 61.Fn sched_proc_fork "struct proc *" "struct proc *"
62.Ft void 62.Ft void
63.Fn sched_proc_exit "struct proc *" "struct proc *" 63.Fn sched_proc_exit "struct proc *" "struct proc *"
64.Ft void 64.Ft void
65.Fn sched_lwp_fork "lwp_t *" 65.Fn sched_lwp_fork "lwp_t *"
66.Ft void 66.Ft void
67.Fn sched_lwp_exit "lwp_t *" 67.Fn sched_lwp_exit "lwp_t *"
68.Ft void 68.Ft void
69.Fn sched_setrunnable "lwp_t *" 69.Fn sched_setrunnable "lwp_t *"
70.Ft void 70.Ft void
71.Fn sched_print_runqueue "void (*pr)(const char *, ...)" 71.Fn sched_print_runqueue "void (*pr)(const char *, ...)"
72.Ft void 72.Ft void
73.Fn sched_pstats_hook "struct proc *" "int" 73.Fn sched_pstats_hook "struct proc *" "int"
74.Ft void 74.Ft void
75.Fn sched_pstats "void *arg" 75.Fn sched_pstats "void *arg"
76.Ft pri_t 76.Ft pri_t
77.Fn sched_kpri "lwp_t *" 77.Fn sched_kpri "lwp_t *"
78.Ft void 78.Ft void
79.Fn resched_cpu "lwp_t *" 79.Fn resched_cpu "lwp_t *"
80.Ft void 80.Ft void
81.Fn setrunnable 81.Fn setrunnable
82.Ft void 82.Ft void
83.Fn schedclock "lwp_t *" 83.Fn schedclock "lwp_t *"
84.Ft void 84.Ft void
85.Fn sched_init "void" 85.Fn sched_init "void"
86.Sh DESCRIPTION 86.Sh DESCRIPTION
87.Nm 87.Nm
88provides a modular and self-contained interface for 88provides a modular and self-contained interface for
89implementing different thread scheduling algorithms. 89implementing different thread scheduling algorithms.
90The different schedulers can be selected at compile-time. 90The different schedulers can be selected at compile-time.
91Currently, the only scheduler available is 91Currently, the only scheduler available is
92.Xr sched_4bsd 9 , 92.Xr sched_4bsd 9 ,
93the traditional 4.4BSD thread scheduler. 93the traditional 4.4BSD thread scheduler.
94.Pp 94.Pp
95The interface is divided into two parts: A set of functions each 95The interface is divided into two parts: A set of functions each
96scheduler needs to implement and common functions used by all 96scheduler needs to implement and common functions used by all
97schedulers. 97schedulers.
98.Sh Scheduler-specific functions 98.Sh Scheduler-specific functions
99The following functions have to be implemented by the individual 99The following functions have to be implemented by the individual
100scheduler. 100scheduler.
101.Ss Scheduler initialization 101.Ss Scheduler initialization
102.Bl -tag 102.Bl -tag -width compact
103.It Ft void Fn sched_cpuattach "struct cpu_info *" 103.It Ft void Fn sched_cpuattach "struct cpu_info *"
104Per-CPU scheduler initialization routine. 104Per-CPU scheduler initialization routine.
105.It Ft void Fn sched_rqinit "void" 105.It Ft void Fn sched_rqinit "void"
106Initialize the scheduler's runqueue data structures. 106Initialize the scheduler's runqueue data structures.
107.It Ft void Fn sched_setup "void" 107.It Ft void Fn sched_setup "void"
108Setup initial scheduling parameters and kick off timeout driven 108Setup initial scheduling parameters and kick off timeout driven
109events. 109events.
110.El 110.El
111.Ss Runqueue handling 111.Ss Runqueue handling
112Runqueue handling is completely internal to the scheduler. 112Runqueue handling is completely internal to the scheduler.
113Other parts of the kernel should access runqueues only through the 113Other parts of the kernel should access runqueues only through the
114following functions: 114following functions:
115.Bl -tag 115.Bl -tag -width compact
116.It Ft void Fn sched_enqueue "lwp_t *" "bool" 116.It Ft void Fn sched_enqueue "lwp_t *" "bool"
117Place an LWP within the scheduler's runqueue structures. 117Place an LWP within the scheduler's runqueue structures.
118.It Ft void Fn sched_dequeue "lwp_t *" 118.It Ft void Fn sched_dequeue "lwp_t *"
119Remove an LWP from the scheduler's runqueue structures. 119Remove an LWP from the scheduler's runqueue structures.
120.It Ft lwp_t * Fn sched_nextlwp "void" 120.It Ft lwp_t * Fn sched_nextlwp "void"
121Return the LWP that should run the CPU next. 121Return the LWP that should run the CPU next.
122.It Ft bool Fn sched_curcpu_runnable_p "void" 122.It Ft bool Fn sched_curcpu_runnable_p "void"
123Indicate if there is a runnable LWP for the current CPU. 123Indicate if there is a runnable LWP for the current CPU.
124.It Ft void Fn sched_print_runqueue "void (*pr)(const char *, ...)" 124.It Ft void Fn sched_print_runqueue "void (*pr)(const char *, ...)"
125Print runqueues in DDB. 125Print runqueues in DDB.
126.El 126.El
127.Ss Core scheduler functions 127.Ss Core scheduler functions
128.Bl -tag 128.Bl -tag -width compact
129.It Ft void Fn sched_tick "struct cpu_info *" 129.It Ft void Fn sched_tick "struct cpu_info *"
130Periodically called from 130Periodically called from
131.Xr hardclock 9 . 131.Xr hardclock 9 .
132Determines if a reschedule is necessary, if the running LWP has 132Determines if a reschedule is necessary, if the running LWP has
133used up its quantum. 133used up its quantum.
134.It Ft void Fn sched_schedclock "lwp_t *" 134.It Ft void Fn sched_schedclock "lwp_t *"
135Periodically called from 135Periodically called from
136.Fn schedclock 136.Fn schedclock
137in order to handle priority adjustment. 137in order to handle priority adjustment.
138.El 138.El
139.Ss Priority adjustment 139.Ss Priority adjustment
140.Bl -tag 140.Bl -tag -width compact
141.It Ft void Fn sched_nice "struct proc *, int" 141.It Ft void Fn sched_nice "struct proc *, int"
142Recalculate the process priority according to its nice value. 142Recalculate the process priority according to its nice value.
143.El 143.El
144.Ss General helper functions 144.Ss General helper functions
145.Bl -tag 145.Bl -tag -width compact
146.It Ft void Fn sched_proc_fork "struct proc *" "struct proc *" 146.It Ft void Fn sched_proc_fork "struct proc *" "struct proc *"
147Inherit the scheduling history of the parent process after 147Inherit the scheduling history of the parent process after
148.Fn fork . 148.Fn fork .
149.It Ft void Fn sched_proc_exit "struct proc *" "struct proc *" 149.It Ft void Fn sched_proc_exit "struct proc *" "struct proc *"
150Charge back a processes parent for its resource usage. 150Charge back a processes parent for its resource usage.
151.It Ft void Fn sched_lwp_fork "lwp_t *" 151.It Ft void Fn sched_lwp_fork "lwp_t *"
152LWP-specific version of the above 152LWP-specific version of the above
153.It Ft void Fn sched_lwp_exit "lwp_t *" 153.It Ft void Fn sched_lwp_exit "lwp_t *"
154LWP-specific version of the above 154LWP-specific version of the above
155.It Ft void Fn sched_setrunnable "lwp_t *" 155.It Ft void Fn sched_setrunnable "lwp_t *"
156Scheduler-specific actions for 156Scheduler-specific actions for
157.Fn setrunnable . 157.Fn setrunnable .
158.It Ft void Fn sched_pstats_hook "struct proc *" "int" 158.It Ft void Fn sched_pstats_hook "struct proc *" "int"
159Scheduler-specific actions for 159Scheduler-specific actions for
160.Fn sched_pstats . 160.Fn sched_pstats .
161.El 161.El
162.Sh Common scheduler functions 162.Sh Common scheduler functions
163.Bl -tag 163.Bl -tag -width compact
164.It Ft pri_t Fn sched_kpri "lwp_t *" 164.It Ft pri_t Fn sched_kpri "lwp_t *"
165Scale a priority level to a kernel priority level, usually for an LWP 165Scale a priority level to a kernel priority level, usually for an LWP
166that is about to sleep. 166that is about to sleep.
167.It Ft void Fn sched_pstats "void *" 167.It Ft void Fn sched_pstats "void *"
168Update process statistics and check CPU resource allocation. 168Update process statistics and check CPU resource allocation.
169.It Ft inline void Fn resched_cpu "lwp_t *" 169.It Ft inline void Fn resched_cpu "lwp_t *"
170Arrange for a reschedule. 170Arrange for a reschedule.
171.It Ft void Fn setrunnable "lwp_t *" 171.It Ft void Fn setrunnable "lwp_t *"
172Change process state to be runnable, placing it on a runqueue if it 172Change process state to be runnable, placing it on a runqueue if it
173is in memory, awakening the swapper otherwise. 173is in memory, awakening the swapper otherwise.
174.It Ft void Fn schedclock "lwp_t *" 174.It Ft void Fn schedclock "lwp_t *"
175Scheduler clock. 175Scheduler clock.
176Periodically called from 176Periodically called from
177.Fn statclock . 177.Fn statclock .
178.It Ft void Fn sched_init "void" 178.It Ft void Fn sched_init "void"
179Initialize callout for 179Initialize callout for
180.Fn sched_pstats 180.Fn sched_pstats
181and call 181and call
182.Fn sched_setup 182.Fn sched_setup
183to initialize any other scheduler-specific data. 183to initialize any other scheduler-specific data.
184.El 184.El
185.Sh CODE REFERENCES 185.Sh CODE REFERENCES
186This section describes places within the 186This section describes places within the
187.Nx 187.Nx
188source tree where actual code implementing the scheduler can be found. 188source tree where actual code implementing the scheduler can be found.
189All pathnames are relative to 189All pathnames are relative to
190.Pa /usr/src . 190.Pa /usr/src .
191.Pp 191.Pp
192The 192The
193.Nm 193.Nm
194programming interface is defined within the file 194programming interface is defined within the file
195.Pa sys/sys/sched.h . 195.Pa sys/sys/sched.h .
196.Pp 196.Pp
197Functions common to all scheduler implementations are in 197Functions common to all scheduler implementations are in
198.Pa sys/kern/kern_synch.c . 198.Pa sys/kern/kern_synch.c .
199.Pp 199.Pp
200The traditional 4.4BSD scheduler is implemented in 200The traditional 4.4BSD scheduler is implemented in
201.Pa sys/kern/sched_4bsd.c . 201.Pa sys/kern/sched_4bsd.c .
202.Sh SEE ALSO 202.Sh SEE ALSO
203.Xr mi_switch 9 , 203.Xr mi_switch 9 ,
204.Xr preempt 9 , 204.Xr preempt 9 ,
205.Xr sched_4bsd 9 205.Xr sched_4bsd 9
206.Sh HISTORY 206.Sh HISTORY
207The 207The
208.Nm 208.Nm
209appeared in 209appeared in
210.Nx 5.0 . 210.Nx 5.0 .
211.Sh AUTHORS 211.Sh AUTHORS
212The 212The
213.Nm 213.Nm
214was written by 214was written by
215.An Daniel Sieger 215.An Daniel Sieger
216.Aq dsieger@NetBSD.org . 216.Aq dsieger@NetBSD.org .