aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorMurray Stokely <murray@FreeBSD.org>2001-09-02 21:19:03 +0000
committerMurray Stokely <murray@FreeBSD.org>2001-09-02 21:19:03 +0000
commitf1979ede58acfd640f7ee8c8a58fb46cf3a3546b (patch)
tree106afc36e047b1d28cbb8bf7f8e21128af8343e6
parentc19663404276b25503303ad6230f91ef2792d9aa (diff)
downloaddoc-f1979ede58acfd640f7ee8c8a58fb46cf3a3546b.tar.gz
doc-f1979ede58acfd640f7ee8c8a58fb46cf3a3546b.zip
Add a small chapter on the sysinit framework, linker sets, etc..
PR: docs/30265 Submitted by: Jason Smethers <jason@smethers.net>
Notes
Notes: svn path=/head/; revision=10545
-rw-r--r--en_US.ISO8859-1/books/arch-handbook/book.sgml3
-rw-r--r--en_US.ISO8859-1/books/arch-handbook/chapters.ent3
-rw-r--r--en_US.ISO8859-1/books/arch-handbook/sysinit/chapter.sgml161
-rw-r--r--en_US.ISO8859-1/books/developers-handbook/book.sgml3
-rw-r--r--en_US.ISO8859-1/books/developers-handbook/chapters.ent3
-rw-r--r--en_US.ISO8859-1/books/developers-handbook/sysinit/chapter.sgml161
6 files changed, 330 insertions, 4 deletions
diff --git a/en_US.ISO8859-1/books/arch-handbook/book.sgml b/en_US.ISO8859-1/books/arch-handbook/book.sgml
index c2d91f80a6..6f625557bd 100644
--- a/en_US.ISO8859-1/books/arch-handbook/book.sgml
+++ b/en_US.ISO8859-1/books/arch-handbook/book.sgml
@@ -1,7 +1,7 @@
<!--
The FreeBSD Documentation Project
- $FreeBSD: doc/en_US.ISO8859-1/books/developers-handbook/book.sgml,v 1.25 2001/08/16 03:34:59 dd Exp $
+ $FreeBSD: doc/en_US.ISO8859-1/books/developers-handbook/book.sgml,v 1.26 2001/09/02 03:11:08 murray Exp $
-->
<!DOCTYPE BOOK PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN" [
@@ -88,6 +88,7 @@
&chap.locking;
&chap.kobj;
+ &chap.sysinit;
&chap.vm;
&chap.dma;
&chap.kerneldebug;
diff --git a/en_US.ISO8859-1/books/arch-handbook/chapters.ent b/en_US.ISO8859-1/books/arch-handbook/chapters.ent
index 2430788825..1ef9ebe938 100644
--- a/en_US.ISO8859-1/books/arch-handbook/chapters.ent
+++ b/en_US.ISO8859-1/books/arch-handbook/chapters.ent
@@ -6,7 +6,7 @@
Chapters should be listed in the order in which they are referenced.
- $FreeBSD: doc/en_US.ISO8859-1/books/developers-handbook/chapters.ent,v 1.10 2001/07/19 22:06:06 murray Exp $
+ $FreeBSD: doc/en_US.ISO8859-1/books/developers-handbook/chapters.ent,v 1.11 2001/09/02 03:11:08 murray Exp $
-->
<!-- Part one -->
@@ -16,6 +16,7 @@
<!-- Part two -->
<!ENTITY chap.kobj SYSTEM "kobj/chapter.sgml">
+<!ENTITY chap.sysinit SYSTEM "sysinit/chapter.sgml">
<!ENTITY chap.locking SYSTEM "locking/chapter.sgml">
<!-- Part three -->
diff --git a/en_US.ISO8859-1/books/arch-handbook/sysinit/chapter.sgml b/en_US.ISO8859-1/books/arch-handbook/sysinit/chapter.sgml
new file mode 100644
index 0000000000..468e739d12
--- /dev/null
+++ b/en_US.ISO8859-1/books/arch-handbook/sysinit/chapter.sgml
@@ -0,0 +1,161 @@
+<!--
+ The FreeBSD Documentation Project
+
+ $FreeBSD: $
+-->
+
+<chapter id="sysinit">
+ <title>The Sysinit Framework</title>
+
+ <para>Sysinit is the framework for a generic call sort and dispatch
+ mechanisim. FreeBSD currently uses it for the dynamic
+ initialization of the kernel. Sysinit allows FreeBSD's kernel
+ subsystems to be reordered, and added, removed, and replaced at
+ kernel link time when the kernel or one of its modules is loaded
+ without having to edit a staticly ordered initilization routing
+ and recompile the kernel. This system also allows kernel modules,
+ currently called <firstterm>KLD's</firstterm>, to be seperatly
+ compiled, linked, and initilized at boot time and loaded even
+ later while the system is already running. This is accomplished
+ using the <quote>kernel linker</quote> and <quote>linker
+ sets</quote>.</para>
+
+ <sect1>
+ <title>Terminology</title>
+
+ <variablelist>
+ <varlistentry>
+ <term>Linker Set</term>
+ <listitem>
+ <para>A linker technique in which the linker gathers
+ staticly declared data throughout a program's source files
+ into a single contagiously addressable unit of
+ data.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </sect1>
+
+ <sect1>
+ <title>Sysinit Operation</title>
+
+ <para>Sysinit relies on the ability of the linker to take static
+ data declared at multiple locations throughout a program's
+ source and group it together as a single contagious chunk of
+ data. This linker technique is called a <quote>linker
+ set</quote>. Sysinit uses two linker sets to maintain two data
+ sets containing each consumer's call order, function, and a
+ pointer to the data to pass to taht function.</para>
+
+ <para>Sysinit uses two priorites when ordering the functions for
+ execution. The first priority is a subsystem ID giving an
+ overall order Sysinit's dispatch of funtions. Current predeclard
+ ID's are in <filename>&lt;sys/kernel.h></filename> in the enum
+ list <literal>sysinit_sub_id</literal>. The second priority used
+ is an element order within the subsystem. Current predeclard
+ subsystem element orders are in
+ <filename>&lt;sys/kernel.h></filename> in the enum list
+ <literal>sysinit_elem_order</literal>.</para>
+
+ <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>
+ </sect1>
+
+
+ <sect1>
+ <title>Using Sysinit</title>
+
+ <sect2>
+ <title>Interface</title>
+
+ <sect3>
+ <title>Headers</title>
+
+ <programlisting>&lt;sys/kernel.h></programlisting>
+ </sect3>
+
+ <sect3>
+ <title>Macros</title>
+
+ <programlisting>SYSINIT(uniquifier, subsystem, order, func, ident)
+ SYSUNINIT(uniquifier, subsystem, order, func, ident)</programlisting>
+ </sect3>
+ </sect2>
+
+ <sect2>
+ <title>Startup</title>
+
+ <para>The <literal>SYSINIT()</literal> macro creates the
+ 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
+ data, the subsystem order, the subsystem element order, the
+ function to call, and the data to pass the fuction. All
+ functions must take a constant pointer argument.
+ </para>
+
+ <para>For example:</para>
+
+ <programlisting>#include &lt;sys/kernel.h>
+
+void foo_null(void *unused)
+{
+ foo_doo();
+}
+SYSINIT(foo_null, SI_SUB_FOO, SI_ORDER_FOO, NULL);
+
+struct foo foo_voodoo = {
+ FOO_VOODOO;
+}
+
+void foo_arg(void *vdata)
+{
+ struct foo *foo = (struct foo *)vdata;
+ foo_data(foo);
+}
+SYSINIT(foo_arg, SI_SUB_FOO, SI_ORDER_FOO, foo_voodoo);
+ </programlisting>
+ </sect2>
+
+ <sect2>
+ <title>Shutdown</title>
+
+ <para>The <literal>SYSUNINIT()</literal> macro behaves similarly
+ to the <literal>SYSINIT()</literal> macro except that it adds
+ the Sysinit data to Sysinit's shutdown data set.</para>
+
+ <para>For example:</para>
+
+ <programlisting>#include &lt;sys/kernel.h>
+
+void foo_cleanup(void *unused)
+{
+ foo_kill();
+}
+SYSUNINIT(foo_cleanup, SI_SUB_FOO, SI_ORDER_FOO, NULL);
+
+struct foo_stack foo_stack = {
+ FOO_STACK_VOODOO;
+}
+
+void foo_flush(void *vdata)
+{
+}
+SYSUNINIT(foo_flush, SI_SUB_FOO, SI_ORDER_FOO, foo_stack);
+ </programlisting>
+ </sect2>
+ </sect1>
+</chapter>
+
+<!--
+ Local Variables:
+ mode: sgml
+ sgml-declaration: "../chapter.decl"
+ sgml-indent-data: t
+ sgml-omittag: nil
+ sgml-always-quote-attributes: t
+ sgml-parent-document: ("../book.sgml" "part" "chapter")
+ End:
+-->
diff --git a/en_US.ISO8859-1/books/developers-handbook/book.sgml b/en_US.ISO8859-1/books/developers-handbook/book.sgml
index c2d91f80a6..6f625557bd 100644
--- a/en_US.ISO8859-1/books/developers-handbook/book.sgml
+++ b/en_US.ISO8859-1/books/developers-handbook/book.sgml
@@ -1,7 +1,7 @@
<!--
The FreeBSD Documentation Project
- $FreeBSD: doc/en_US.ISO8859-1/books/developers-handbook/book.sgml,v 1.25 2001/08/16 03:34:59 dd Exp $
+ $FreeBSD: doc/en_US.ISO8859-1/books/developers-handbook/book.sgml,v 1.26 2001/09/02 03:11:08 murray Exp $
-->
<!DOCTYPE BOOK PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN" [
@@ -88,6 +88,7 @@
&chap.locking;
&chap.kobj;
+ &chap.sysinit;
&chap.vm;
&chap.dma;
&chap.kerneldebug;
diff --git a/en_US.ISO8859-1/books/developers-handbook/chapters.ent b/en_US.ISO8859-1/books/developers-handbook/chapters.ent
index 2430788825..1ef9ebe938 100644
--- a/en_US.ISO8859-1/books/developers-handbook/chapters.ent
+++ b/en_US.ISO8859-1/books/developers-handbook/chapters.ent
@@ -6,7 +6,7 @@
Chapters should be listed in the order in which they are referenced.
- $FreeBSD: doc/en_US.ISO8859-1/books/developers-handbook/chapters.ent,v 1.10 2001/07/19 22:06:06 murray Exp $
+ $FreeBSD: doc/en_US.ISO8859-1/books/developers-handbook/chapters.ent,v 1.11 2001/09/02 03:11:08 murray Exp $
-->
<!-- Part one -->
@@ -16,6 +16,7 @@
<!-- Part two -->
<!ENTITY chap.kobj SYSTEM "kobj/chapter.sgml">
+<!ENTITY chap.sysinit SYSTEM "sysinit/chapter.sgml">
<!ENTITY chap.locking SYSTEM "locking/chapter.sgml">
<!-- Part three -->
diff --git a/en_US.ISO8859-1/books/developers-handbook/sysinit/chapter.sgml b/en_US.ISO8859-1/books/developers-handbook/sysinit/chapter.sgml
new file mode 100644
index 0000000000..468e739d12
--- /dev/null
+++ b/en_US.ISO8859-1/books/developers-handbook/sysinit/chapter.sgml
@@ -0,0 +1,161 @@
+<!--
+ The FreeBSD Documentation Project
+
+ $FreeBSD: $
+-->
+
+<chapter id="sysinit">
+ <title>The Sysinit Framework</title>
+
+ <para>Sysinit is the framework for a generic call sort and dispatch
+ mechanisim. FreeBSD currently uses it for the dynamic
+ initialization of the kernel. Sysinit allows FreeBSD's kernel
+ subsystems to be reordered, and added, removed, and replaced at
+ kernel link time when the kernel or one of its modules is loaded
+ without having to edit a staticly ordered initilization routing
+ and recompile the kernel. This system also allows kernel modules,
+ currently called <firstterm>KLD's</firstterm>, to be seperatly
+ compiled, linked, and initilized at boot time and loaded even
+ later while the system is already running. This is accomplished
+ using the <quote>kernel linker</quote> and <quote>linker
+ sets</quote>.</para>
+
+ <sect1>
+ <title>Terminology</title>
+
+ <variablelist>
+ <varlistentry>
+ <term>Linker Set</term>
+ <listitem>
+ <para>A linker technique in which the linker gathers
+ staticly declared data throughout a program's source files
+ into a single contagiously addressable unit of
+ data.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </sect1>
+
+ <sect1>
+ <title>Sysinit Operation</title>
+
+ <para>Sysinit relies on the ability of the linker to take static
+ data declared at multiple locations throughout a program's
+ source and group it together as a single contagious chunk of
+ data. This linker technique is called a <quote>linker
+ set</quote>. Sysinit uses two linker sets to maintain two data
+ sets containing each consumer's call order, function, and a
+ pointer to the data to pass to taht function.</para>
+
+ <para>Sysinit uses two priorites when ordering the functions for
+ execution. The first priority is a subsystem ID giving an
+ overall order Sysinit's dispatch of funtions. Current predeclard
+ ID's are in <filename>&lt;sys/kernel.h></filename> in the enum
+ list <literal>sysinit_sub_id</literal>. The second priority used
+ is an element order within the subsystem. Current predeclard
+ subsystem element orders are in
+ <filename>&lt;sys/kernel.h></filename> in the enum list
+ <literal>sysinit_elem_order</literal>.</para>
+
+ <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>
+ </sect1>
+
+
+ <sect1>
+ <title>Using Sysinit</title>
+
+ <sect2>
+ <title>Interface</title>
+
+ <sect3>
+ <title>Headers</title>
+
+ <programlisting>&lt;sys/kernel.h></programlisting>
+ </sect3>
+
+ <sect3>
+ <title>Macros</title>
+
+ <programlisting>SYSINIT(uniquifier, subsystem, order, func, ident)
+ SYSUNINIT(uniquifier, subsystem, order, func, ident)</programlisting>
+ </sect3>
+ </sect2>
+
+ <sect2>
+ <title>Startup</title>
+
+ <para>The <literal>SYSINIT()</literal> macro creates the
+ 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
+ data, the subsystem order, the subsystem element order, the
+ function to call, and the data to pass the fuction. All
+ functions must take a constant pointer argument.
+ </para>
+
+ <para>For example:</para>
+
+ <programlisting>#include &lt;sys/kernel.h>
+
+void foo_null(void *unused)
+{
+ foo_doo();
+}
+SYSINIT(foo_null, SI_SUB_FOO, SI_ORDER_FOO, NULL);
+
+struct foo foo_voodoo = {
+ FOO_VOODOO;
+}
+
+void foo_arg(void *vdata)
+{
+ struct foo *foo = (struct foo *)vdata;
+ foo_data(foo);
+}
+SYSINIT(foo_arg, SI_SUB_FOO, SI_ORDER_FOO, foo_voodoo);
+ </programlisting>
+ </sect2>
+
+ <sect2>
+ <title>Shutdown</title>
+
+ <para>The <literal>SYSUNINIT()</literal> macro behaves similarly
+ to the <literal>SYSINIT()</literal> macro except that it adds
+ the Sysinit data to Sysinit's shutdown data set.</para>
+
+ <para>For example:</para>
+
+ <programlisting>#include &lt;sys/kernel.h>
+
+void foo_cleanup(void *unused)
+{
+ foo_kill();
+}
+SYSUNINIT(foo_cleanup, SI_SUB_FOO, SI_ORDER_FOO, NULL);
+
+struct foo_stack foo_stack = {
+ FOO_STACK_VOODOO;
+}
+
+void foo_flush(void *vdata)
+{
+}
+SYSUNINIT(foo_flush, SI_SUB_FOO, SI_ORDER_FOO, foo_stack);
+ </programlisting>
+ </sect2>
+ </sect1>
+</chapter>
+
+<!--
+ Local Variables:
+ mode: sgml
+ sgml-declaration: "../chapter.decl"
+ sgml-indent-data: t
+ sgml-omittag: nil
+ sgml-always-quote-attributes: t
+ sgml-parent-document: ("../book.sgml" "part" "chapter")
+ End:
+-->