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