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