Add kern(1) and kernfrag(7) manuals

1 files changed, 134 insertions, 0 deletions

diff --git a/kernfrag.7 b/kernfrag.7
new file mode 100644
index 0000000..60eb4d5
--- /dev/null
+++ b/kernfrag.7
@@ -0,0 +1,134 @@
+.Dd May 4, 2020
+.Dt KERNFRAG 7
+.Os
+.Sh NAME
+.Nm kernfrag
+.Nd compose Linux kernel configurations
+.Sh DESCRIPTION
+.Nm
+is a framework for arranging and composing Linux kernel configurations.
+It is comprised of two distinct types of files,
+.Em fragments
+and
+.Em templates ,
+which are organized within a specific directory structure.
+.Pp
+Utilities such as
+.Xr kern 1
+then use the kernel's
+.Em merge_config.sh
+script to compose a complete configuration file from a given template
+and all fragments referenced within it.
+.Pp
+Note that by default,
+.Em merge_config.sh
+will merge fragments with the
+kernel's default configuration as generated by
+.Sq make alldefconfig .
+In other words, configuration symbols that are enabled (or disabled) by
+default need not be included explicitly.
+.Pp
+This manual requires a basic understanding of the kernel build system.
+For more information, refer to the resources linked in the
+.Sx SEE ALSO
+section of this manual.
+.Sh FRAGMENTS
+A
+.Em fragment
+is a text file containing a set of configuration symbols and
+their respective values.
+.Pp
+The format of this file is analogous to the one used by the kernel
+configuration file.
+For example:
+.Bd -literal -offset indent
+# We only really care about standard PC systems
+# CONFIG_X86_EXTENDED_PLATFORM is not set
+
+# We want to support transparent hugepages, though applications
+# should ask for them specifically with madvise
+CONFIG_TRANSPARENT_HUGEPAGE=y
+CONFIG_TRANSPARENT_HUGEPAGE_MADVISE=y
+.Ed
+.Sh TEMPLATES
+A
+.Em template
+is a text file containing a list of
+.Em fragment
+paths.
+.Pp
+One such path is given per line, relative to the
+.Pa fragments/
+directory in the root
+.Nm
+structure.
+Empty lines or comments are not allowed.
+For example:
+.Bd -literal -offset indent
+devices/input/xpad
+devices/net/r8169
+devices/usb/sound
+.Ed
+.Sh DIRECTORY STRUCTURE
+The canonical root directory for the
+.Nm
+structure is
+.Pa /etc/kernfrag .
+Contained within are two directories,
+.Pa fragments/
+and
+.Pa templates/ .
+.Pp
+The
+.Pa fragments/
+directory contains an arbitrarily nested tree of fragments.
+It is recommended to group fragments according to the nature of the
+configuration symbols they contain.
+For example, a group for device drivers can be arranged like this:
+.Bd -literal -offset indent
+fragments/devices/
+├── input
+│   └── xpad
+├── net
+│   ├── r8169
+│   └── tigon3
+└── usb
+    ├── bluetooth
+    └── sound
+.Ed
+.Pp
+The
+.Pa templates/
+directory contains all templates.
+Usually there is one template for each host managed by the user.
+A special
+.Qq base
+template is used by
+.Xr kern 1
+to determine which fragments are always included.
+.Pp
+For example, the following listing contains templates for two hosts
+and the previously mentioned
+.Qq base
+template.
+.Bd -literal -offset indent
+templates/
+├── aphrodite
+├── base
+└── hephaestus
+.Ed
+.Sh FILES
+.Bl -tag -width Ds
+.It Pa /etc/kernfrag
+The canonical root directory for the
+.Nm
+structure.
+.El
+.Sh SEE ALSO
+.Xr kern 1
+.Bl -tag -width Ds
+.It The Kernel Build System:
+https://www.kernel.org/doc/html/latest/kbuild/index.html
+.It The kernel's merge_config shell script
+.Pa /usr/src/linux/scripts/kconfig/merge_config.sh
+.El