Creating a Linux Kernel User’s Manual

This article is part of a series on improvements being made to Linux kernel documentation:

This article will discuss the efforts that are underway for kernel 4.10 to produce a Linux User’s Manual that groups the existing user-focused documents.

What Defines a Linux Kernel User?

It’s not an easy task to identify the documents that contain useful information for Linux kernel users because there are a large number of documentation files inside the kernel tree and these documents are mixed with development documents.

Furthermore, who exactly are the Linux kernel tree users? Are they the end users who run various Linux distributions, the distribution packagers that package the kernel tree, or the advanced Linux users and system administrators that opt to compile the kernel themselves? In other words, depending on what definition of users we use, the contents of a Linux user’s manual varies.

For the scope of this work, we tried to use a broader definition of users:

  • end users of the Linux kernel, interested in the bug report procedures and kernel arguments,
  • advanced users that want to build the kernel themselves,
  • distribution packagers,
  • kernel support teams that need to know how to identify and address kernel bugs (called OOPS).

In the future, it might make sense to split this book into sub-books.

Identifying Relevant Documents for Linux Kernel Users

Once we have a definition for the users, I had to dig into the files under Documentation/ to identify the ones that match the criteria:

  • Documentation/bad_memory.txt – describes bad memory detection, using memcheck86 and what to do when something bad happens. It would make sense to add some information about EDAC here in the future,
  • Documentation/basic_profiling.txt – describes procedures for performance profiling using readprofile and oprofile,
  • Documentation/binfmt_misc.txt – describes support for generic exec files,
  • Documentation/braille-console.txt – describes the usage of a braille console,
  • Documentation/BUG-HUNTING – describes the procedures to identify patches that cause kernel bugs,
  • Documentation/devices.txt – lists the major and minor magic numbers for devices that scripts like MAKEDEV make use of. This sort of information is meant for kernel packagers and system administrators,
  • Documentation/dynamic-debug-howto.txt – describes the procedure used to enable the kernel dynamic debug messages. Such procedures can be useful for normal users that need to provide more information to someone who is helping them discover the root cause of a bug,
  • Documentation/initrd.txt – Describes the initial application the kernel runs (process ID 1),
  • Documentation/init.txt – Explains what happens when the kernel can’t start the process ID 1 (the init program) and the potential cause for such a bug,
  • Documentation/java.txt – describes how to run a java exec program directly, using binfmt_misc support,
  • Documentation/kernel-parameters.txt – describes the kernel parameters that could be used when it starts,
  • Documentation/md.txt – describes the kernel support for RAID volumes,
  • Documentation/module-signing.txt – describes the Linux kernel module sign aspects,
  • Documentation/mono.txt – describes how to run a mono-based .NET exec program directly, using binfmt_misc support;
  • Documentation/oops-tracing.txt – describes how to trace a kernel OOPS,
  • Documentation/parport.txt – describes the kernel parallel port support,
  • Documentation/ramoops.txt – describes the RAM OOPS error messages,
  • /README – contains a description of the Linux kernel, its release, and how to install, configure and build. This is the main user’s documentation,
  • /REPORTING-BUGS – describes the process of reporting a kernel bug,
  • Documentation/SecurityBugs – describes the process of reporting a kernel security bug,
  • Documentation/serial-console.txt – describes how to setup a console via a serial port,
  • Documentation/sysfs-rules.txt – describes the kernel sysfs interface, where it should be located, the main properties, etc,
  • Documentation/sysrq.txt – describes the keystrokes and commands to use the kernel SYSRQ requests. These are useful when handling a kernel issue,
  • Documentation/unicode.txt – describes the Linux kernel unicode support,
  • Documentation/VGA-softcursor.txt – describes the VGA software cursor implementation on Linux.

However, it should be noticed that some of these files also contain some development-specific information. I also decided to keep some other files that contained information that didn’t seem to be relevant on kernel 4.x (like Documentation/svga.txt) out of this book, and I excluded other files that mentioned too much development stuff or had too much subsystem-specific information (like Documentation/rfkill.txt).

The Path Forward

The community will need to take another look at the remaining files found under Documentation/ to check if some of the leftovers belong in the user’s manual, or if some files should be split into two files: one with the user’s documentation, the other one with the development data. This is a very important topic for the future of the Linux kernel community, and it’s likely to be a topic area that receives some attention at the Linux Kernel Summit in Santa Fe, New Mexico at the end of this month. If you’re going to be there, it would be great to hear your thoughts!

Author: Mauro Carvalho Chehab

Mauro is the maintainer of the Linux kernel media and EDAC subsystems and Tizen on Yocto. He's also a major contributor to the Reliability Availability and Serviceability (RAS) subsystems.