From 033de7efe279930b0cfa0b7d4ae09b11aca0974b Mon Sep 17 00:00:00 2001 From: Conrad Pankoff Date: Tue, 24 Dec 2019 14:10:39 +1100 Subject: [PATCH] Base: Describe kernel modules, syscalls, and programs --- Base/usr/share/man/man1/modload.md | 25 +++++++++ Base/usr/share/man/man1/modunload.md | 25 +++++++++ Base/usr/share/man/man2/module_load.md | 35 ++++++++++++ Base/usr/share/man/man2/module_unload.md | 31 +++++++++++ Base/usr/share/man/man7/kernel_modules.md | 65 +++++++++++++++++++++++ 5 files changed, 181 insertions(+) create mode 100644 Base/usr/share/man/man1/modload.md create mode 100644 Base/usr/share/man/man1/modunload.md create mode 100644 Base/usr/share/man/man2/module_load.md create mode 100644 Base/usr/share/man/man2/module_unload.md create mode 100644 Base/usr/share/man/man7/kernel_modules.md diff --git a/Base/usr/share/man/man1/modload.md b/Base/usr/share/man/man1/modload.md new file mode 100644 index 00000000000..16bcc24dac5 --- /dev/null +++ b/Base/usr/share/man/man1/modload.md @@ -0,0 +1,25 @@ +## Name + +modload - load a kernel module + +## Synopsis + +```**sh +$ modload +``` + +## 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) diff --git a/Base/usr/share/man/man1/modunload.md b/Base/usr/share/man/man1/modunload.md new file mode 100644 index 00000000000..3c7e15ed1f8 --- /dev/null +++ b/Base/usr/share/man/man1/modunload.md @@ -0,0 +1,25 @@ +## Name + +modunload - unload a kernel module + +## Synopsis + +```**sh +$ modunload +``` + +## 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) diff --git a/Base/usr/share/man/man2/module_load.md b/Base/usr/share/man/man2/module_load.md new file mode 100644 index 00000000000..07b596c7efd --- /dev/null +++ b/Base/usr/share/man/man2/module_load.md @@ -0,0 +1,35 @@ +## Name + +module\_load - load a kernel module + +## Synopsis + +```**c++ +#include + +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) diff --git a/Base/usr/share/man/man2/module_unload.md b/Base/usr/share/man/man2/module_unload.md new file mode 100644 index 00000000000..05e35d6bed1 --- /dev/null +++ b/Base/usr/share/man/man2/module_unload.md @@ -0,0 +1,31 @@ +## Name + +module\_unload - unload a kernel module + +## Synopsis + +```**c++ +#include + +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) diff --git a/Base/usr/share/man/man7/kernel_modules.md b/Base/usr/share/man/man7/kernel_modules.md new file mode 100644 index 00000000000..068ef8dcf82 --- /dev/null +++ b/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 +#include + +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)