From e4e680370906bc0c33227b6004aa666bee75e693 Mon Sep 17 00:00:00 2001
From: Joshua Phillips <jp.sittingduck@gmail.com>
Date: Sun, 8 Feb 2009 18:38:30 +0000
Subject: [PATCH] [doc] Documented the module system.

---
 doc/SConscript  | 11 ++++++++---
 doc/index.txt   |  5 +++++
 doc/modules.txt | 55 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 68 insertions(+), 3 deletions(-)
 create mode 100644 doc/modules.txt

diff --git a/doc/SConscript b/doc/SConscript
index c6b7a8f..43b9da0 100644
--- a/doc/SConscript
+++ b/doc/SConscript
@@ -1,7 +1,12 @@
+files = [
+'index.txt',
+'mm.txt',
+'build.txt',
+'modules.txt',
+]
+
 Import(['env'])
 
 if env.build_doc:
-    for i in ['index.txt',
-              'mm.txt',
-              'build.txt']:
+    for i in files:
         env.AsciiDoc(i)
diff --git a/doc/index.txt b/doc/index.txt
index 2be2f9e..29da24a 100644
--- a/doc/index.txt
+++ b/doc/index.txt
@@ -27,3 +27,8 @@ Building
 --------
 
 See link:build.html[building]
+
+Modules
+-------
+
+See link:modules.html[modules]
diff --git a/doc/modules.txt b/doc/modules.txt
new file mode 100644
index 0000000..5ef2d13
--- /dev/null
+++ b/doc/modules.txt
@@ -0,0 +1,55 @@
+Modules
+=======
+
+Concepts
+--------
+
+A kernel module is an object file which can be loaded into the kernel at
+run-time, rather than being compiled into the kernel directly.
+
+Each kernel module has an entry point (`_start`) and can reference symbols in
+the kernel, as well as symbols in other modules.
+
+Modules are *trusted*. They run with full kernel privileges.
+
+The Module Loader
+-----------------
+
+The module loader loads a kernel module and patches up the relocations for
+execution. It also resolves references to kernel symbols, and symbols in other
+modules.
+
+When the module is ready to run, it calls the `_start` function of the module.
+Note that the `_start` function is not given its own thread! It is expected to
+call various kernel functions to install itself, and then return.
+
+The `modinit` section
+---------------------
+
+Kernel modules have a section called `modinit`. This section contains an array
+of function pointers to initialisation functions. If you're familiar with the
+`.ctors` sections of C++, `modinit` works in exactly the same way.
+
+If a module is actually built as a kernel module, it is linked with
+`kernel/module-entry.c`, which provides the entry point `_start` and calls each
+function in the `modinit` section in turn.
+
+This produces some desirable effects:
+
+- Modules can be linked together into a supermodule, with no code changes. This
+  will merge .text, .data and .bss sections of the modules together and will
+  save memory that would otherwise be wasted due to alignment. For example, it
+  may be useful for a user to link together all the modules they know they need.
+
+- Modules can even be linked statically into the kernel! The kernel can look in
+  its own `modinit` section for the module initialisation functions. This means
+  that modules can be compiled into the kernel, or compiled as separate modules,
+  very easily.
+
+Problems
+~~~~~~~~
+
+The `modinit` section does not take into account module dependencies. For
+example, if module A uses module B, module B would have to be initialised before
+A, although currently the initialisation order would depend on the order of the
+linker arguments!
-- 
2.11.4.GIT