.\"     $NetBSD: csf.9,v 1.9 2015/05/25 21:02:37 prlw1 Exp $
.\"
.\" Copyright (c) 2002 The NetBSD Foundation, Inc.
.\" All rights reserved.
.\"
.\" This code is derived from software contributed to The NetBSD Foundation
.\" by Daniel Sieger.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
.\" POSSIBILITY OF SUCH DAMAGE.
.\"
.Dd October 27, 2014
.Dt CSF 9
.Os
.Sh NAME
.Nm CSF
.Nd The
.Nx
common scheduler framework
.Sh SYNOPSIS
.In sys/sched.h
.Ft void
.Fn sched_rqinit "void"
.Ft void
.Fn sched_setup "void"
.Ft void
.Fn sched_cpuattach "struct cpu_info *"
.Ft void
.Fn sched_tick "struct cpu_info *"
.Ft void
.Fn sched_schedclock "lwp_t *"
.Ft bool
.Fn sched_curcpu_runnable_p "void"
.Ft lwp_t *
.Fn sched_nextlwp "void"
.Ft void
.Fn sched_enqueue "lwp_t *" "bool"
.Ft void
.Fn sched_dequeue "lwp_t *"
.Ft void
.Fn sched_nice "struct proc *" "int"
.Ft void
.Fn sched_proc_fork "struct proc *" "struct proc *"
.Ft void
.Fn sched_proc_exit "struct proc *" "struct proc *"
.Ft void
.Fn sched_lwp_fork "lwp_t *"
.Ft void
.Fn sched_lwp_exit "lwp_t *"
.Ft void
.Fn sched_setrunnable "lwp_t *"
.Ft void
.Fn sched_print_runqueue "void (*pr)(const char *, ...)"
.Ft void
.Fn sched_pstats_hook "struct proc *" "int"
.Ft void
.Fn sched_pstats "void *arg"
.Ft pri_t
.Fn sched_kpri "lwp_t *"
.Ft void
.Fn resched_cpu "lwp_t *"
.Ft void
.Fn setrunnable
.Ft void
.Fn schedclock "lwp_t *"
.Ft void
.Fn sched_init "void"
.Sh DESCRIPTION
.Nm
provides a modular and self-contained interface for
implementing different thread scheduling algorithms.
The different schedulers can be selected at compile-time.
Currently, the schedulers available are
.Xr sched_4bsd 9 ,
the traditional 4.4BSD thread scheduler, and
.Xr sched_m2 9
which implements a SVR4/Solaris like approach.
.Pp
The interface is divided into two parts: A set of functions each
scheduler needs to implement and common functions used by all
schedulers.
.Sh Scheduler-specific functions
The following functions have to be implemented by the individual
scheduler.
.Ss Scheduler initialization
.Bl -tag -width compact
.It Ft void Fn sched_cpuattach "struct cpu_info *"
Per-CPU scheduler initialization routine.
.It Ft void Fn sched_rqinit "void"
Initialize the scheduler's runqueue data structures.
.It Ft void Fn sched_setup "void"
Setup initial scheduling parameters and kick off timeout driven
events.
.El
.Ss Runqueue handling
Runqueue handling is completely internal to the scheduler.
Other parts of the kernel should access runqueues only through the
following functions:
.Bl -tag -width compact
.It Ft void Fn sched_enqueue "lwp_t *" "bool"
Place an LWP within the scheduler's runqueue structures.
.It Ft void Fn sched_dequeue "lwp_t *"
Remove an LWP from the scheduler's runqueue structures.
.It Ft lwp_t * Fn sched_nextlwp "void"
Return the LWP that should run the CPU next.
.It Ft bool Fn sched_curcpu_runnable_p "void"
Indicate if there is a runnable LWP for the current CPU.
.It Ft void Fn sched_print_runqueue "void (*pr)(const char *, ...)"
Print runqueues in DDB.
.El
.Ss Core scheduler functions
.Bl -tag -width compact
.It Ft void Fn sched_tick "struct cpu_info *"
Periodically called from
.Xr hardclock 9 .
Determines if a reschedule is necessary, if the running LWP has
used up its quantum.
.It Ft void Fn sched_schedclock "lwp_t *"
Periodically called from
.Fn schedclock
in order to handle priority adjustment.
.El
.Ss Priority adjustment
.Bl -tag -width compact
.It Ft void Fn sched_nice "struct proc *" "int"
Recalculate the process priority according to its nice value.
.El
.Ss General helper functions
.Bl -tag -width compact
.It Ft void Fn sched_proc_fork "struct proc *" "struct proc *"
Inherit the scheduling history of the parent process after
.Fn fork .
.It Ft void Fn sched_proc_exit "struct proc *" "struct proc *"
Charge back a processes parent for its resource usage.
.It Ft void Fn sched_lwp_fork "lwp_t *"
LWP-specific version of the above
.It Ft void Fn sched_lwp_exit "lwp_t *"
LWP-specific version of the above
.It Ft void Fn sched_setrunnable "lwp_t *"
Scheduler-specific actions for
.Fn setrunnable .
.It Ft void Fn sched_pstats_hook "struct proc *" "int"
Scheduler-specific actions for
.Fn sched_pstats .
.El
.Sh Common scheduler functions
.Bl -tag -width compact
.It Ft pri_t Fn sched_kpri "lwp_t *"
Scale a priority level to a kernel priority level, usually for an LWP
that is about to sleep.
.It Ft void Fn sched_pstats "void *"
Update process statistics and check CPU resource allocation.
.It Ft inline void Fn resched_cpu "lwp_t *"
Arrange for a reschedule.
.It Ft void Fn setrunnable "lwp_t *"
Change process state to be runnable, placing it on a runqueue if it
is in memory, awakening the swapper otherwise.
.It Ft void Fn schedclock "lwp_t *"
Scheduler clock.
Periodically called from
.Fn statclock .
.It Ft void Fn sched_init "void"
Initialize callout for
.Fn sched_pstats
and call
.Fn sched_setup
to initialize any other scheduler-specific data.
.El
.Sh CODE REFERENCES
The
.Nm
programming interface is defined within the file
.Pa sys/sys/sched.h .
.Pp
Functions common to all scheduler implementations are in
.Pa sys/kern/kern_synch.c .
.Pp
The traditional 4.4BSD scheduler is implemented in
.Pa sys/kern/sched_4bsd.c .
.Pp
The M2 scheduler is implemented in
.Pa sys/kern/sched_m2.c .
.Sh SEE ALSO
.Xr mi_switch 9 ,
.Xr preempt 9 ,
.Xr sched_4bsd 9 ,
.Xr sched_m2 9
.Sh HISTORY
The
.Nm
appeared in
.Nx 5.0 .
.Sh AUTHORS
The
.Nm
was written by
.An Daniel Sieger
.Aq dsieger@NetBSD.org .