Base: Describe kernel modules, syscalls, and programs

Author: https://github.com/deoxxa
Commit: https://github.com/SerenityOS/serenity/commit/033de7efe27
Pull-request: https://github.com/SerenityOS/serenity/pull/908
Reviewed-by: https://github.com/bugaevc

Base/usr/share/man/man1/modload.md

@@ -0,0 +1,25 @@
+## Name
+
+modload - load a kernel module
+
+## Synopsis
+
+```**sh
+$ modload <path>
+```
+
+## Description
+
+Load a kernel module specified by *path*.
+
+## Examples
+
+```sh
+$ modload /mod/TestModule.o
+```
+
+## See also
+
+* [`modunload`(1)](modunload.md)
+* [`module_load`(2)](../man2/module_load.md)
+* [`kernel_modules`(7)](../man7/kernel_modules.md)

Base/usr/share/man/man1/modunload.md

@@ -0,0 +1,25 @@
+## Name
+
+modunload - unload a kernel module
+
+## Synopsis
+
+```**sh
+$ modunload <name>
+```
+
+## Description
+
+Unload a kernel module specified by *name*.
+
+## Examples
+
+```sh
+$ modunload TestModule
+```
+
+## See also
+
+* [`modload`(1)](modload.md)
+* [`module_unload`(2)](../man2/module_unload.md)
+* [`kernel_modules`(7)](../man7/kernel_modules.md)

Base/usr/share/man/man2/module_load.md

@@ -0,0 +1,35 @@
+## Name
+
+module\_load - load a kernel module
+
+## Synopsis
+
+```**c++
+#include <serenity.h>
+
+int module_load(const char* path, size_t path_length);
+```
+
+## Description
+
+`module_load()` will load a kernel module from an ELF object file given its
+path in the filesystem.
+
+## Return value
+
+If the module is successfully loaded, `module_load()` returns 0. Otherwise, it
+returns -1 and sets `errno` to describe the error.
+
+## Errors
+
+* `EFAULT`: `path` pointed to memory that was not accessible for the caller.
+* `ENOEXEC`: The specified file could not be parsed as an ELF object.
+* `ENOENT`: One or more symbols referred to by the module could not be resolved.
+* `EINVAL`: The module had no `.text` section, or didn't export a `module_init` function.
+* `EEXIST`: A module with the same name was already loaded.
+
+## See also
+
+* [`module_unload`(2)](module_unload.md)
+* [`modload`(1)](../man1/modload.md)
+* [`kernel_modules`(7)](../man7/kernel_modules.md)

Base/usr/share/man/man2/module_unload.md

@@ -0,0 +1,31 @@
+## Name
+
+module\_unload - unload a kernel module
+
+## Synopsis
+
+```**c++
+#include <serenity.h>
+
+int module_unload(const char* name, size_t name_length);
+```
+
+## Description
+
+`module_unload()` will unload a kernel module by name.
+
+## Return value
+
+If the module is successfully unloaded, `module_unload()` returns 0.
+Otherwise, it returns -1 and sets `errno` to describe the error.
+
+## Errors
+
+* `EFAULT`: `path` pointed to memory that was not accessible for the caller.
+* `ENOENT`: There was no module loaded with the specified name.
+
+## See also
+
+* [`module_load`(2)](module_load.md)
+* [`modunload`(1)](../man1/modunload.md)
+* [`kernel_modules`(7)](../man7/kernel_modules.md)

Base/usr/share/man/man7/kernel_modules.md

@@ -0,0 +1,65 @@
+## Name
+
+Kernel Modules - runtime code loading for the kernel
+
+## Description
+
+Serenity's kernel supports loading modules at runtime. This functionality can
+be used to implement optional features (e.g. drivers), and speed up your
+development cycle.
+
+## Module format
+
+A kernel module is a regular ELF object file which must export several
+symbols. Any symbols it refers to will be resolved when it is loaded.
+
+### `module_name`
+
+This should be a string like `const char module_name[]` containing the name of
+the module. This is used to give the module a name in any informational
+contexts, but also to ensure that the module is not loaded twice by accident,
+and also used as a reference to unload the module later.
+
+### `module_init`
+
+This should be a function with the following signature: `void module_init()`.
+It will be called when the module is loaded.
+
+### `module_fini`
+
+This is optional, but if defined it should be a function with the following
+signature: `void module_fini()`. It will be called when the module is
+unloaded.
+
+## Example:
+
+```c++
+#include <Kernel/kstdio.h>
+#include <Kernel/Process.h>
+
+extern "C" const char module_name[] = "ExampleModule";
+
+extern "C" void module_init()
+{
+    kprintf("ExampleModule has booted!\n");
+
+    for (int i = 0; i < 3; ++i) {
+        kprintf("i is now %d\n", i);
+    }
+
+    kprintf("current pid: %d\n", current->process().sys$getpid());
+    kprintf("current process name: %s\n", current->process().name().characters());
+}
+
+extern "C" void module_fini()
+{
+    kprintf("ExampleModule is being removed!\n");
+}
+```
+
+## See also
+
+* [`modload`(1)](../man1/modload.md)
+* [`modunload`(1)](../man1/modunload.md)
+* [`module_load`(2)](../man2/module_load.md)
+* [`module_unload`(2)](../man2/module_unload.md)