share/man/man9/csf.9

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