From fc0d213322f8f98bdc23aa509d0123929a61efa3 Mon Sep 17 00:00:00 2001
From: Ken Smith <kensmith@FreeBSD.org>
Date: Thu, 23 Oct 2003 19:21:13 +0000
Subject: [PATCH] 	- minor grammar fix 	- add some new content with
 additional explanation of SYSINIT 	  and related things

Approved:	blackend (mentor)
Reviewed:	jhb
---
 .../books/arch-handbook/sysinit/chapter.sgml  | 41 +++++++++++++++++--
 1 file changed, 38 insertions(+), 3 deletions(-)

diff --git a/en_US.ISO8859-1/books/arch-handbook/sysinit/chapter.sgml b/en_US.ISO8859-1/books/arch-handbook/sysinit/chapter.sgml
index d92429853c..44e7c99a04 100644
--- a/en_US.ISO8859-1/books/arch-handbook/sysinit/chapter.sgml
+++ b/en_US.ISO8859-1/books/arch-handbook/sysinit/chapter.sgml
@@ -49,7 +49,7 @@
 
     <para>SYSINIT uses two priorities when ordering the functions for
       execution.  The first priority is a subsystem ID giving an
-      overall order SYSINIT's dispatch of functions. Current predeclared
+      overall order for SYSINIT's dispatch of functions. Current predeclared
       ID's are in <filename>&lt;sys/kernel.h&gt;</filename> in the enum
       list <literal>sysinit_sub_id</literal>. The second priority used
       is an element order within the subsystem. Current predeclared
@@ -59,7 +59,18 @@
 
     <para>There are currently two uses for SYSINIT. Function dispatch
       at system startup and kernel module loads, and function dispatch
-      at system shutdown and kernel module unload.</para>
+      at system shutdown and kernel module unload.  Kernel subsystems
+      often use system startup SYSINIT's to initialize data
+      structures, for example the process scheduling subsystem
+      uses a SYSINIT to initialize the run queue data structure.
+      Device drivers should avoid using <literal>SYSINIT()</literal>
+      directly.  Instead drivers for real devices that are part of a
+      bus structure should use <literal>DRIVER_MODULE()</literal> to
+      provide a function that detects the device and, if it is present,
+      initializes the device.  It will do a few things specific to
+      devices and then call <literal>SYSINIT()</literal> itself.
+      For pseudo-devices, which are not part of a bus structure,
+      use <literal>DEV_MODULE()</literal>.</para>
   </sect1>
 
 
@@ -90,7 +101,7 @@ SYSUNINIT(uniquifier, subsystem, order, func, ident)</programlisting>
         necessary SYSINIT data in SYSINIT's startup data set for
         SYSINIT to sort and dispatch a function at system startup and
         module load.  <literal>SYSINIT()</literal> takes a uniquifier
-        that SYSINIT uses identify the particular function dispatch
+        that SYSINIT uses to identify the particular function dispatch
         data, the subsystem order, the subsystem element order, the
         function to call, and the data to pass the function. All
         functions must take a constant pointer argument.
@@ -119,6 +130,30 @@ void foo_arg(void *vdata)
 SYSINIT(bar, SI_SUB_FOO, SI_ORDER_FOO, foo_arg, foo_voodoo);
 	</programlisting>
       </example>
+
+      <para>Note that <literal>SI_SUB_FOO</literal> and
+	<literal>SI_ORDER_FOO</literal> need to be in the
+	<literal>sysinit_sub_id</literal> and
+	<literal>sysinit_elem_order</literal> enum's as mentioned
+	above.  Either use existing ones or add your own to the
+	enum's.  You can also use math for fine-tuning the order
+	a SYSINIT will run in.  This example shows a SYSINIT that
+	needs to be run just barely before the SYSINIT's that
+	handle tuning kernel parameters.</para>
+
+      <example>
+	<title>Example of Adjusting <literal>SYSINIT()</literal> Order</title>
+
+	<programlisting>static void
+mptable_register(void *dummy __unused)
+{
+
+	apic_register_enumerator(&mptable_enumerator);
+}
+
+SYSINIT(mptable_register, SI_SUB_TUNABLES - 1, SI_ORDER_FIRST,
+    mptable_register, NULL);</programlisting>
+      </example>
     </sect2>
 
     <sect2>