harvey/sys/man/3/realtime

.TH REALTIME 3 
.EQ
delim $$
.EN
.SH NAME
realtime \- real time scheduling
.SH SYNOPSIS
.EX
.ta 4n +11n +7
.B bind -a #R /dev
.ift .sp 0.5
.ifn .sp
/proc/\fIn\fP/ctl
.EE
.SH DESCRIPTION
The Plan 9 real-time scheduler allows mixing real-time processes and best-effort
processes on a single system.  The scheduler is intended for real-time loads well
under 100% CPU utilization with minimum periods in the order of a hundred thousand
instruction times.  The precision of the scheduler depends on the precision of the
machine's programmable real-time clock.
.PP
Real-time processes are scheduled using Earliest-Deadline First (EDF).  Each process
has three primary scheduling parameters, a period $T$, a deadline $D$
and a cost $C$, expressed in nanoseconds.
Every $T$ nanoseconds, the process is
.I released
— i.e., it becomes schedulable — and it receives a
.I slice
of $C$ nsec.
When the process is released, its
.I "release time"
$r$ is set to the current time.
The process's
.I "absolute deadline"
$d$ is set to $r + D$.
(Note the use of capital letters to indicate intervals and lower-case
letters to indicate `points in time'.)
Between release and deadline, the process must be scheduled often enough
to be able to consume its slice of $C$ nsec of CPU time.
So, to be schedulable, $C <= D <= T$ must hold.
If $D < T$, processes are not real-time schedulable (runnable) between their
deadline and the next release, but they may run as best-effort processes and compete with
other processes for the CPU.
Processes are scheduled according to the EDF rule
from the moment of release until their deadline or their slice runs
out, whichever happens first.  Additionally, processes can voluntarily
declare the slice for the current period empty, allowing other
real-time processes or best-effort processes to use the CPU time remaining in their
slice.
.PP
Before they are released for the first time, processes have to be
.IR admitted
into the system.  Before admission, a test is conducted to determine
whether the process, plus the already admitted processes, given their
scheduling parameters, can all meet their deadlines.  When a process
changes its scheduling parameters, it is temporarily
.I expelled
and will be readmitted only if the new scheduling parameters allow all
processes to continue to meet their deadlines.
.PP
The EDF scheduler schedules the released process with the earliest
deadline.  When a process is released it can, therefore, preempt a process
that has a later deadline, but was released earlier.
.\" .PP
.\" Real-time processes sharing resources, however, may need to be prevented
.\" from preempting each other.  They must do this by declaring their shared
.\" resources.  The scheduler will not preempt one process with another that
.\" shares a common resource.  To do this, processes can name resources they use
.\" and the scheduler will not allow preemption of a process by another that
.\" has named the same resource.
.\" .PP
.\" Note that, if all processes share a common resource, the scheduler reduces to
.\" non-preemptive EDF scheduling.  Note also that resources in this context
.\" are just named placeholders for the actual resources shared by the processes.
.\" It is up to the programmer to define the relationship between actual
.\" shared resources (data structures, for example) and the named resources
.\" used by the scheduler.
.\" .PP
.\" During the admission test, information about resource sharing is used
.\" to calculate
.\" .IR "inherited deadlines" ,
.\" for each process.  A resource's
.\" .IR "inherited deadline" ,
.\" $Δ$, is the minimum of the deadlines $D$ of each of the processes
.\" that shares that resource.  A process's $Δ$ is the minimum of the
.\" resource $Δ$s of all resources held by the process.
.\" .PP
.\" The scheduler allows a released process $T$ to preempt running process $T'$
.\" iff $d < d' ^ D < Δ'$; the first half of the condition says that the
.\" released process's deadline must be earlier, the second implies that the
.\" released process may not share resources with the running one (after all,
.\" if $T'$ had acquired a resource that $T$ uses, its $Δ'$ would, by the
.\" definition of inherited deadlines, be less than or equal to $D$).
.\" .PP
.\" The admission test takes these limitations into account.  Note that,
.\" in practice, processes rarely share resources.
.PP
Normally, processes can block (when all their processes are blocked on
system calls) during their release.  The time spent blocking may be
accounted against the current slice, because blocked processes may stop
other processes from getting the processor (due to shared resources).
Processes can tell the scheduler that they no longer require the CPU until the next
release, by
.I yielding
(see below).
.PP
Processes can also run in another mode where blocking automatically
implies immediate yielding.  This mode truly guarantees that deadlines
will be made, but programmers must know more about the (blocking)
nature of system calls used in order to use this mode.
.sp
.LP
The real-time scheduler is controlled through
.BR /proc/\fPpid\fP/ctl .
See
.IR proc (3).
.PP
The process' parameters are set or modified by writing one of these files and they
can be examined by reading it.
A parameter is presented in the form
\f2name\fP \f2value\fP, \f2name\fP +\f2value\fP, or \f2name\fP -\f2value\fP.
A command is presented in the form
.IR commandname .
Parameters and commands are separated by semicolons.
The settable parameters are
.TP
.B period
Sets the period.  The value must be given as a number with or without decimal point
and directly followed (no white space) by one of
.I s
for seconds,
.I ms
for milliseconds,
.I µs
or
.I us
for microseconds,
.I ns
or
nothing
for nanoseconds.
If the value is signed, it is taken as an increment (decrement) of the value
perviously set.
.TP
.B deadline
Sets the deadline.  Value specified as above.
.TP
.B cost
Sets the cost.  Value specified as above.
.TP
.B yieldonblock
When the (integer) value is non-zero or absent, the process is placed in
.I yield-on-block
mode: when the process is blocked on a system call, the process automatically
declares the current deadline reached and will be released again in the next period or when the process
becomes runnable again, whichever occurs last.
When the value is zero, the process can block without forfeiting the current release.
The default value is zero.
.TP
.B sporadic
When the (integer) value is non-zero or absent, the process is placed in
.I sporadic
mode.  This mode resembles
.IR yield-on-block .
When the process unblocks and the time elapsed since last release is more than the period, it
is released immediately, rather than at the next period boundary.  Sporadic scheduling is
useful for processes that are interrupt driven.  The period merely specifies the maximum
invocation rate.  The default value is zero.
.TP
.B admit
This initiates an admission test.  If the test fails, the write containing the
.B admit
command will fail.  If the test succeeds the process is admitted and will be released.
.TP
.B expel
Expels the process by turning it back into a regular best-effort process.
.LP
.BR Sleep(0)
will yield (i.e., giveup the processor until the next release time).  In non-real-time
processes,
.B sleep(0)
will invoke the scheduler, allowing higher priority processes to run.
.TP
.SH EXAMPLE
.EX
.ta 4n +4n +4n +4n +4n +4n +4n
char *ctl[128];

void
processvideo(){
	int fd;

	snprint(ctl, sizeof ctl, "/proc/%ld/ctl", getpid());
	if ((fd = open(ctl, ORDWR)) < 0) 
		sysfatal("%s: %r", ctl);
	if (fprint(fd, "period 33ms;deadline 20ms;cost 8ms;admit") < 0)
		sysfatal("%s: admit: %r", ctl);
	close(fd);
	for (;;){
		processframe();
		sleep(0);
	}
}
.EE
.SH "SEE ALSO
.IR trace (1)
.LP
.SH SOURCE
.B /sys/src/9/port/edf.c
.SH BUGS
The admission test does not take multiprocessors into account.  The total
real-time load cannot exceed a single-\s-2CPU\s0 load.