Patch for chap-processes.xml (scheduling)

Hi,
attached is a diff that adds some information about
scheduling to 
NetBSD Internals. The content is taken from scheduler(9). Of
course it
would be nice to have more information than just the
man-page in the
future, but in the meantime this is better than just a
"XXX write me".

Regards,
Daniel

-- 
Daniel Sieger
Faculty of Technology
Bielefeld University
wwwhomes.uni-bielefeld.de/dsieger
Index: chap-processes.xml
============================================================
=======
RCS file:
/cvsroot/htdocs/Documentation/internals/en/chap-processes.xm
l,v
retrieving revision 1.9
diff -b -u -r1.9 chap-processes.xml
--- chap-processes.xml	21 Nov 2006 22:17:06 -0000	1.9
+++ chap-processes.xml	23 Nov 2006 09:47:23 -0000
 -1203,8
+1203,69 
   <!--
============================================================
==== -->
 
   <sect1 id="scheduling">
-    <title>Threads scheduling</title>
-    <para>XXX write me</para>
+    <title>Thread scheduling</title>
+    <sect2 id="overview">
+    <title>Overview</title>
+    <para>
+    NetBSD's scheduler algorithm is based on ``multilevel
feedback
+    queues''.  All processes that are runnable are assigned
a
+    scheduling priority that determines in which run queue
they are
+    placed.  The currently running process does not exist
on a run
+    queue.  In selecting a new process to run, the system
scans the
+    run queues from highest to lowest priority and chooses
the first
+    process on the first non-empty queue.  If multiple
processes
+    reside on a queue, the system runs them round robin in
the order
+    found on the queue.  If a process uses up the time
slice
+    allocated to it, it is placed at the end of the queue
from which
+    it came, and the process at the front of the queue is
selected to
+    run.
+    </para>
+    <para>
+    The system adjusts the scheduling priority of a process
+    dynamically to reflect resource requirements (being
blocked) and
+    the CPU utilization consumed by the process.  Processes
are moved
+    between run queues based on changes in their scheduling
priority
+    (hence the word feedback in the name).
+    </para>
+    <para>
+    The process CPU utilization is incremented in
+    <function>hardclock</function> each time
that the system clock
+    ticks and the process is found to be executing.  CPU
utilization
+    is adjusted once per second in
<function>schedcpu</function> via
+    a digital decay filter.  Each time a process
accumulates four
+    ticks in its CPU utilization,
<function>schedclock</function>
+    invokes <function>resetpriority</function>
to recalculate the
+    process's scheduling priority.
+    </para>
+    <para>
+    When a process other than the currently running process
attains a
+    higher scheduling priority, the system notices this in
+    <function>resetpriority</function> and
schedules a context switch
+    to the higher-priority process to occur on return to
user mode.
+    </para>
+    <para>
+    A blocked process exists on the sleep queue and is not
affected
+    by the scheduling behaviour discussed above.  However,
each
+    second schedcpu() updates the time each process has
been on the
+    sleep queue.  The system recomputes a process's CPU
utilization
+    estimate in <function>updatepri</function>
when it is awakened
+    and has been sleeping for longer than 1 second.  When
the process
+    is placed on the run queue by
<function>setrunnable</function>,
+    <function>resetpriority</function> is
invoked to recalculate the
+    process's scheduling priority.
+    </para>
+    <para>
+    The system tailors this short-term scheduling algorithm
to favor
+    interactive jobs by raising the scheduling priority of
+    processes that are blocked waiting for I/O for one or
more
+    seconds, and by lowering the priority of processes that
+    accumulate significant amounts of CPU time.
+    </para>
+    <para>
+    The scheduler subsystem is implemented within the file
+    <filename>sys/kern/kern_synch.c.</filename>
+    </para>
+   </sect2>
   </sect1>
 
   <!--
============================================================
==== -->

On Thu, 23 Nov 2006, Daniel Sieger wrote:

> attached is a diff that adds some information about
scheduling to 
> NetBSD Internals. The content is taken from
scheduler(9). Of course it
> would be nice to have more information than just the
man-page in the
> future, but in the meantime this is better than just a
"XXX write me".

Also include the license of the original doc (in comments).

When I had suggested some docs for the book before I was
told just to use 
man pages instead. Maybe duplicating information is not good
as now we 
have two places to edit. Somehow need a procedure to
generate direct from 
nroff source for this so doesn't have to manually be done.

On Thu, Nov 23, 2006 at 11:43:19AM -0600, Jeremy C. Reed
wrote:
> On Thu, 23 Nov 2006, Daniel Sieger wrote:
> 
> > attached is a diff that adds some information
about scheduling to 
> > NetBSD Internals. The content is taken from
scheduler(9). Of course it
> > would be nice to have more information than just
the man-page in the
> > future, but in the meantime this is better than
just a "XXX write me".
> 
> Also include the license of the original doc (in
comments).

Ok, I'll add that. Thanks for the hint.

> When I had suggested some docs for the book before I
was told just to use 
> man pages instead. Maybe duplicating information is not
good as now we 
> have two places to edit. Somehow need a procedure to
generate direct from 
> nroff source for this so doesn't have to manually be
done.

Hubert also noted that to me. But my intention is to write
more about
scheduling in the future and I'd like to use the content
from the
man-page only as a starting point.

Regards,
Daniel

-- 
Daniel Sieger
Faculty of Technology
Bielefeld University
wwwhomes.uni-bielefeld.de/dsieger

On Thu, Nov 23, 2006 at 11:43:19AM -0600, Jeremy C. Reed
wrote:
> 
> Also include the license of the original doc (in
comments).

Mmh, the man-page has a default TNF copyright and
BSD-licence. So I ask
myself if it is really needed to include this information.
Opinions?

Regards,
Daniel

-- 
Daniel Sieger
Faculty of Technology
Bielefeld University
wwwhomes.uni-bielefeld.de/dsieger

On Thu, 23 Nov 2006, Daniel Sieger wrote:
> Mmh, the man-page has a default TNF copyright and
BSD-licence. So I ask
> myself if it is really needed to include this
information. Opinions?

IIUC you wanted to just refer to the manpage and add your
own text.
In that case I don't see why you'd have to include copyright
text of the 
manpage.


  - hubert

On Thu, Nov 23, 2006 at 07:30:23PM +0100, Hubert Feyrer
wrote:
> 
> On Thu, 23 Nov 2006, Daniel Sieger wrote:
> >Mmh, the man-page has a default TNF copyright and
BSD-licence. So I ask
> >myself if it is really needed to include this
information. Opinions?
> 
> IIUC you wanted to just refer to the manpage and add
your own text.
> In that case I don't see why you'd have to include
copyright text of the 
> manpage.

No, I want to use the content from the man-page and add more
content step
by step.

- Daniel

-- 
Daniel Sieger
Faculty of Technology
Bielefeld University
wwwhomes.uni-bielefeld.de/dsieger

On Thu, Nov 23, 2006 at 06:58:49PM +0100, Daniel Sieger
wrote:
> Hubert also noted that to me. But my intention is to
write more about
> scheduling in the future and I'd like to use the
content from the
> man-page only as a starting point.

A man page describes the API, while the
"internals" book should describe the
implementation. There is some overlap (as clearly evident in
this case), but
I don't think we are duplicating too much. Probably
scheduler(9) is a very
untypical man page, even for section 9.

Martin