code:
.. SPDX-License-Identifier: GPL-2.0

========================
Linux and the Devicetree
========================

The Linux usage model for device tree data

:Author: Grant Likely <grant.likely@secretlab.ca>

This article describes how Linux uses the device tree.  An overview of
the device tree data format can be found on the device tree usage page
at devicetree.org\ [1]_.

.. [1] https://www.devicetree.org/specifications/

The "Open Firmware Device Tree", or simply Devicetree (DT), is a data
structure and language for describing hardware.  More specifically, it
is a description of hardware that is readable by an operating system
so that the operating system doesn't need to hard code details of the
machine.

Structurally, the DT is a tree, or acyclic graph with named nodes, and
nodes may have an arbitrary number of named properties encapsulating
arbitrary data.  A mechanism also exists to create arbitrary
links from one node to another outside of the natural tree structure.

Conceptually, a common set of usage conventions, called 'bindings',
is defined for how data should appear in the tree to describe typical
hardware characteristics including data busses, interrupt lines, GPIO
connections, and peripheral devices.

As much as possible, hardware is described using existing bindings to
maximize use of existing support code, but since property and node
names are simply text strings, it is easy to extend existing bindings
or create new ones by defining new nodes and properties.  Be wary,
however, of creating a new binding without first doing some homework
about what already exists.  There are currently two different,
incompatible, bindings for i2c busses that came about because the new
binding was created without first investigating how i2c devices were
already being enumerated in existing systems.

1. History
----------
The DT was originally created by Open Firmware as part of the
communication method for passing data from Open Firmware to a client
program (like to an operating system).  An operating system used the
Device Tree to discover the topology of the hardware at runtime, and
thereby support a majority of available hardware without hard coded
information (assuming drivers were available for all devices).

Since Open Firmware is commonly used on PowerPC and SPARC platforms,
the Linux support for those architectures has for a long time used the
Device Tree.

In 2005, when PowerPC Linux began a major cleanup and to merge 32-bit
and 64-bit support, the decision was made to require DT support on all
powerpc platforms, regardless of whether or not they used Open
Firmware.  To do this, a DT representation called the Flattened Device
Tree (FDT) was created which could be passed to the kernel as a binary
blob without requiring a real Open Firmware implementation.  U-Boot,
kexec, and other bootloaders were modified to support both passing a
Device Tree Binary (dtb) and to modify a dtb at boot time.  DT was
also added to the PowerPC boot wrapper (``arch/powerpc/boot/*``) so that
a dtb could be wrapped up with the kernel image to support booting
existing non-DT aware firmware.

Some time later, FDT infrastructure was generalized to be usable by
all architectures.  At the time of this writing, 6 mainlined
architectures (arm, microblaze, mips, powerpc, sparc, and x86) and 1
out of mainline (nios) have some level of DT support.

2. Data Model
-------------
If you haven't already read the Device Tree Usage\ [1]_ page,
then go read it now.  It's okay, I'll wait....

2.1 High Level View
-------------------
The most important thing to understand is that the DT is simply a data
structure that describes the hardware.  There is nothing magical about
it, and it doesn't magically make all hardware configuration problems
go away.  What it does do is provide a language for decoupling the
hardware configuration from the board and device driver support in the
Linux kernel (or any other operating system for that matter).  Using
it allows board and device support to become data driven; to make
setup decisions based on data passed into the kernel instead of on
per-machine hard coded selections.

Ideally, data driven platform setup should result in less code
duplication and make it easier to support a wide range of hardware
with a single kernel image.

Linux uses DT data for three major purposes:

1) platform identification,
2) runtime configuration, and
3) device population.

2.2 Platform Identification
---------------------------
First and foremost, the kernel will use data in the DT to identify the
specific machine.  In a perfect world, the specific platform shouldn't
matter to the kernel because all platform details would be described
perfectly by the device tree in a consistent and reliable manner.
Hardware is not perfect though, and so the kernel must identify the
machine during early boot so that it has the opportunity to run
machine-specific fixups.

In the majority of cases, the machine identity is irrelevant, and the
kernel will instead select setup code based on the machine's core
CPU or SoC.  On ARM for example, setup_arch() in
arch/arm/kernel/setup.c will call setup_machine_fdt() in
arch/arm/kernel/devtree.c which searches through the machine_desc
table and selects the machine_desc which best matches the device tree
data.  It determines the best match by looking at the 'compatible'
property in the root device tree node, and comparing it with the
dt_compat list in struct machine_desc (which is defined in
arch/arm/include/asm/mach/arch.h if you're curious).

The 'compatible' property contains a sorted list of strings starting
with the exact name of the machine, followed by an optional list of
boards it is compatible with sorted from most compatible to least.  For
example, the root compatible properties for the TI BeagleBoard and its
successor, the BeagleBoard xM board might look like, respectively::

	compatible = "ti,omap3-beagleboard", "ti,omap3450", "ti,omap3";
	compatible = "ti,omap3-beagleboard-xm", "ti,omap3450", "ti,omap3";

Where "ti,omap3-beagleboard-xm" specifies the exact model, it also
claims that it compatible with the OMAP 3450 SoC, and the omap3 family
of SoCs in general.  You'll notice that the list is sorted from most
specific (exact board) to least specific (SoC family).

Astute readers might point out that the Beagle xM could also claim
compatibility with the original Beagle board.  However, one should be
cautioned about doing so at the board level since there is typically a
high level of change from one board to another, even within the same
product line, and it is hard to nail down exactly what is meant when one
board claims to be compatible with another.  For the top level, it is
better to err on the side of caution and not claim one board is
compatible with another.  The notable exception would be when one
board is a carrier for another, such as a CPU module attached to a
carrier board.

One more note on compatible values.  Any string used in a compatible
property must be documented as to what it indicates.  Add
documentation for compatible strings in Documentation/devicetree/bindings.

Again on ARM, for each machine_desc, the kernel looks to see if
any of the dt_compat list entries appear in the compatible property.
If one does, then that machine_desc is a candidate for driving the
machine.  After searching the entire table of machine_descs,
setup_machine_fdt() returns the 'most compatible' machine_desc based
on which entry in the compatible property each machine_desc matches
against.  If no matching machine_desc is found, then it returns NULL.

The reasoning behind this scheme is the observation that in the majority
of cases, a single machine_desc can support a large number of boards
if they all use the same SoC, or same family of SoCs.  However,
invariably there will be some exceptions where a specific board will
require special setup code that is not useful in the generic case.
Special cases could be handled by explicitly checking for the
troublesome board(s) in generic setup code, but doing so very quickly
becomes ugly and/or unmaintainable if it is more than just a couple of
cases.

Instead, the compatible list allows a generic machine_desc to provide
support for a wide common set of boards by specifying "less
compatible" values in the dt_compat list.  In the example above,
generic board support can claim compatibility with "ti,omap3" or
"ti,omap3450".  If a bug was discovered on the original beagleboard
that required special workaround code during early boot, then a new
machine_desc could be added which implements the workarounds and only
matches on "ti,omap3-beagleboard".

PowerPC uses a slightly different scheme where it calls the .probe()
hook from each machine_desc, and the first one returning TRUE is used.
However, this approach does not take into account the priority of the
compatible list, and probably should be avoided for new architecture
support.

2.3 Runtime configuration
-------------------------
In most cases, a DT will be the sole method of communicating data from
firmware to the kernel, so also gets used to pass in runtime and
configuration data like the kernel parameters string and the location
of an initrd image.

Most of this data is contained in the /chosen node, and when booting
Linux it will look something like this::

	chosen {
		bootargs = "console=ttyS0,115200 loglevel=8";
		initrd-start = <0xc8000000>;
		initrd-end = <0xc8200000>;
	};

The bootargs property contains the kernel arguments, and the initrd-*
properties define the address and size of an initrd blob.  Note that
initrd-end is the first address after the initrd image, so this doesn't
match the usual semantic of struct resource.  The chosen node may also
optionally contain an arbitrary number of additional properties for
platform-specific configuration data.

During early boot, the architecture setup code calls of_scan_flat_dt()
several times with different helper callbacks to parse device tree
data before paging is setup.  The of_scan_flat_dt() code scans through
the device tree and uses the helpers to extract information required
during early boot.  Typically the early_init_dt_scan_chosen() helper
is used to parse the chosen node including kernel parameters,
early_init_dt_scan_root() to initialize the DT address space model,
and early_init_dt_scan_memory() to determine the size and
location of usable RAM.

On ARM, the function setup_machine_fdt() is responsible for early
scanning of the device tree after selecting the correct machine_desc
that supports the board.

2.4 Device population
---------------------
After the board has been identified, and after the early configuration data
has been parsed, then kernel initialization can proceed in the normal
way.  At some point in this process, unflatten_device_tree() is called
to convert the data into a more efficient runtime representation.
This is also when machine-specific setup hooks will get called, like
the machine_desc .init_early(), .init_irq() and .init_machine() hooks
on ARM.  The remainder of this section uses examples from the ARM
implementation, but all architectures will do pretty much the same
thing when using a DT.

As can be guessed by the names, .init_early() is used for any machine-
specific setup that needs to be executed early in the boot process,
and .init_irq() is used to set up interrupt handling.  Using a DT
doesn't materially change the behaviour of either of these functions.
If a DT is provided, then both .init_early() and .init_irq() are able
to call any of the DT query functions (of_* in include/linux/of*.h) to
get additional data about the platform.

The most interesting hook in the DT context is .init_machine() which
is primarily responsible for populating the Linux device model with
data about the platform.  Historically this has been implemented on
embedded platforms by defining a set of static clock structures,
platform_devices, and other data in the board support .c file, and
registering it en-masse in .init_machine().  When DT is used, then
instead of hard coding static devices for each platform, the list of
devices can be obtained by parsing the DT, and allocating device
structures dynamically.

The simplest case is when .init_machine() is only responsible for
registering a block of platform_devices.  A platform_device is a concept
used by Linux for memory or I/O mapped devices which cannot be detected
by hardware, and for 'composite' or 'virtual' devices (more on those
later).  While there is no 'platform device' terminology for the DT,
platform devices roughly correspond to device nodes at the root of the
tree and children of simple memory mapped bus nodes.

About now is a good time to lay out an example.  Here is part of the
device tree for the NVIDIA Tegra board::

  /{
	compatible = "nvidia,harmony", "nvidia,tegra20";
	#address-cells = <1>;
	#size-cells = <1>;
	interrupt-parent = <&intc>;

	chosen { };
	aliases { };

	memory {
		device_type = "memory";
		reg = <0x00000000 0x40000000>;
	};

	soc {
		compatible = "nvidia,tegra20-soc", "simple-bus";
		#address-cells = <1>;
		#size-cells = <1>;
		ranges;

		intc: interrupt-controller@50041000 {
			compatible = "nvidia,tegra20-gic";
			interrupt-controller;
			#interrupt-cells = <1>;
			reg = <0x50041000 0x1000>, < 0x50040100 0x0100 >;
		};

		serial@70006300 {
			compatible = "nvidia,tegra20-uart";
			reg = <0x70006300 0x100>;
			interrupts = <122>;
		};

		i2s1: i2s@70002800 {
			compatible = "nvidia,tegra20-i2s";
			reg = <0x70002800 0x100>;
			interrupts = <77>;
			codec = <&wm8903>;
		};

		i2c@7000c000 {
			compatible = "nvidia,tegra20-i2c";
			#address-cells = <1>;
			#size-cells = <0>;
			reg = <0x7000c000 0x100>;
			interrupts = <70>;

			wm8903: codec@1a {
				compatible = "wlf,wm8903";
				reg = <0x1a>;
				interrupts = <347>;
			};
		};
	};

	sound {
		compatible = "nvidia,harmony-sound";
		i2s-controller = <&i2s1>;
		i2s-codec = <&wm8903>;
	};
  };

At .init_machine() time, Tegra board support code will need to look at
this DT and decide which nodes to create platform_devices for.
However, looking at the tree, it is not immediately obvious what kind
of device each node represents, or even if a node represents a device
at all.  The /chosen, /aliases, and /memory nodes are informational
nodes that don't describe devices (although arguably memory could be
considered a device).  The children of the /soc node are memory mapped
devices, but the codec@1a is an i2c device, and the sound node
represents not a device, but rather how other devices are connected
together to create the audio subsystem.  I know what each device is
because I'm familiar with the board design, but how does the kernel
know what to do with each node?

The trick is that the kernel starts at the root of the tree and looks
for nodes that have a 'compatible' property.  First, it is generally
assumed that any node with a 'compatible' property represents a device
of some kind, and second, it can be assumed that any node at the root
of the tree is either directly attached to the processor bus, or is a
miscellaneous system device that cannot be described any other way.
For each of these nodes, Linux allocates and registers a
platform_device, which in turn may get bound to a platform_driver.

Why is using a platform_device for these nodes a safe assumption?
Well, for the way that Linux models devices, just about all bus_types
assume that its devices are children of a bus controller.  For
example, each i2c_client is a child of an i2c_master.  Each spi_device
is a child of an SPI bus.  Similarly for USB, PCI, MDIO, etc.  The
same hierarchy is also found in the DT, where I2C device nodes only
ever appear as children of an I2C bus node.  Ditto for SPI, MDIO, USB,
etc.  The only devices which do not require a specific type of parent
device are platform_devices (and amba_devices, but more on that
later), which will happily live at the base of the Linux /sys/devices
tree.  Therefore, if a DT node is at the root of the tree, then it
really probably is best registered as a platform_device.

Linux board support code calls of_platform_populate(NULL, NULL, NULL, NULL)
to kick off discovery of devices at the root of the tree.  The
parameters are all NULL because when starting from the root of the
tree, there is no need to provide a starting node (the first NULL), a
parent struct device (the last NULL), and we're not using a match
table (yet).  For a board that only needs to register devices,
.init_machine() can be completely empty except for the
of_platform_populate() call.

In the Tegra example, this accounts for the /soc and /sound nodes, but
what about the children of the SoC node?  Shouldn't they be registered
as platform devices too?  For Linux DT support, the generic behaviour
is for child devices to be registered by the parent's device driver at
driver .probe() time.  So, an i2c bus device driver will register a
i2c_client for each child node, an SPI bus driver will register
its spi_device children, and similarly for other bus_types.
According to that model, a driver could be written that binds to the
SoC node and simply registers platform_devices for each of its
children.  The board support code would allocate and register an SoC
device, a (theoretical) SoC device driver could bind to the SoC device,
and register platform_devices for /soc/interrupt-controller, /soc/serial,
/soc/i2s, and /soc/i2c in its .probe() hook.  Easy, right?

Actually, it turns out that registering children of some
platform_devices as more platform_devices is a common pattern, and the
device tree support code reflects that and makes the above example
simpler.  The second argument to of_platform_populate() is an
of_device_id table, and any node that matches an entry in that table
will also get its child nodes registered.  In the Tegra case, the code
can look something like this::

  static void __init harmony_init_machine(void)
  {
	/* ... */
	of_platform_populate(NULL, of_default_bus_match_table, NULL, NULL);
  }

"simple-bus" is defined in the Devicetree Specification as a property
meaning a simple memory mapped bus, so the of_platform_populate() code
could be written to just assume simple-bus compatible nodes will
always be traversed.  However, we pass it in as an argument so that
board support code can always override the default behaviour.

[Need to add discussion of adding i2c/spi/etc child devices]

Appendix A: AMBA devices
------------------------

ARM Primecells are a certain kind of device attached to the ARM AMBA
bus which include some support for hardware detection and power
management.  In Linux, struct amba_device and the amba_bus_type is
used to represent Primecell devices.  However, the fiddly bit is that
not all devices on an AMBA bus are Primecells, and for Linux it is
typical for both amba_device and platform_device instances to be
siblings of the same bus segment.

When using the DT, this creates problems for of_platform_populate()
because it must decide whether to register each node as either a
platform_device or an amba_device.  This unfortunately complicates the
device creation model a little bit, but the solution turns out not to
be too invasive.  If a node is compatible with "arm,amba-primecell", then
of_platform_populate() will register it as an amba_device instead of a
platform_device.


code:
.. SPDX-License-Identifier: GPL-2.0

How to help improve kernel documentation
========================================

Documentation is an important part of any software-development project.
Good documentation helps to bring new developers in and helps established
developers work more effectively.  Without top-quality documentation, a lot
of time is wasted in reverse-engineering the code and making avoidable
mistakes.

Unfortunately, the kernel's documentation currently falls far short of what
it needs to be to support a project of this size and importance.

This guide is for contributors who would like to improve that situation.
Kernel documentation improvements can be made by developers at a variety of
skill levels; they are a relatively easy way to learn the kernel process in
general and find a place in the community.  The bulk of what follows is the
documentation maintainer's list of tasks that most urgently need to be
done.

The documentation TODO list
---------------------------

There is an endless list of tasks that need to be carried out to get our
documentation to where it should be.  This list contains a number of
important items, but is far from exhaustive; if you see a different way to
improve the documentation, please do not hold back!

Addressing warnings
~~~~~~~~~~~~~~~~~~~

The documentation build currently spews out an unbelievable number of
warnings.  When you have that many, you might as well have none at all;
people ignore them, and they will never notice when their work adds new
ones.  For this reason, eliminating warnings is one of the highest-priority
tasks on the documentation TODO list.  The task itself is reasonably
straightforward, but it must be approached in the right way to be
successful.

Warnings issued by a compiler for C code can often be dismissed as false
positives, leading to patches aimed at simply shutting the compiler up.
Warnings from the documentation build almost always point at a real
problem; making those warnings go away requires understanding the problem
and fixing it at its source.  For this reason, patches fixing documentation
warnings should probably not say "fix a warning" in the changelog title;
they should indicate the real problem that has been fixed.

Another important point is that documentation warnings are often created by
problems in kerneldoc comments in C code.  While the documentation
maintainer appreciates being copied on fixes for these warnings, the
documentation tree is often not the right one to actually carry those
fixes; they should go to the maintainer of the subsystem in question.

For example, in a documentation build I grabbed a pair of warnings nearly
at random::

  ./drivers/devfreq/devfreq.c:1818: warning: bad line:
  	- Resource-managed devfreq_register_notifier()
  ./drivers/devfreq/devfreq.c:1854: warning: bad line:
	- Resource-managed devfreq_unregister_notifier()

(The lines were split for readability).

A quick look at the source file named above turned up a couple of kerneldoc
comments that look like this::

  /**
   * devm_devfreq_register_notifier()
	  - Resource-managed devfreq_register_notifier()
   * @dev:	The devfreq user device. (parent of devfreq)
   * @devfreq:	The devfreq object.
   * @nb:		The notifier block to be unregistered.
   * @list:	DEVFREQ_TRANSITION_NOTIFIER.
   */

The problem is the missing "*", which confuses the build system's
simplistic idea of what C comment blocks look like.  This problem had been
present since that comment was added in 2016 — a full four years.  Fixing
it was a matter of adding the missing asterisks.  A quick look at the
history for that file showed what the normal format for subject lines is,
and ``scripts/get_maintainer.pl`` told me who should receive it (pass paths to
your patches as arguments to scripts/get_maintainer.pl).  The resulting patch
looked like this::

  [PATCH] PM / devfreq: Fix two malformed kerneldoc comments

  Two kerneldoc comments in devfreq.c fail to adhere to the required format,
  resulting in these doc-build warnings:

    ./drivers/devfreq/devfreq.c:1818: warning: bad line:
  	  - Resource-managed devfreq_register_notifier()
    ./drivers/devfreq/devfreq.c:1854: warning: bad line:
	  - Resource-managed devfreq_unregister_notifier()

  Add a couple of missing asterisks and make kerneldoc a little happier.

  Signed-off-by: Jonathan Corbet <corbet@lwn.net>
  ---
   drivers/devfreq/devfreq.c | 4 ++--
   1 file changed, 2 insertions(+), 2 deletions(-)

  diff --git a/drivers/devfreq/devfreq.c b/drivers/devfreq/devfreq.c
  index 57f6944d65a6..00c9b80b3d33 100644
  --- a/drivers/devfreq/devfreq.c
  +++ b/drivers/devfreq/devfreq.c
  @@ -1814,7 +1814,7 @@ static void devm_devfreq_notifier_release(struct device *dev, void *res)

   /**
    * devm_devfreq_register_notifier()
  -	- Resource-managed devfreq_register_notifier()
  + *	- Resource-managed devfreq_register_notifier()
    * @dev:	The devfreq user device. (parent of devfreq)
    * @devfreq:	The devfreq object.
    * @nb:		The notifier block to be unregistered.
  @@ -1850,7 +1850,7 @@ EXPORT_SYMBOL(devm_devfreq_register_notifier);

   /**
    * devm_devfreq_unregister_notifier()
  -	- Resource-managed devfreq_unregister_notifier()
  + *	- Resource-managed devfreq_unregister_notifier()
    * @dev:	The devfreq user device. (parent of devfreq)
    * @devfreq:	The devfreq object.
    * @nb:		The notifier block to be unregistered.
  --
  2.24.1

The entire process only took a few minutes.  Of course, I then found that
somebody else had fixed it in a separate tree, highlighting another lesson:
always check linux-next to see if a problem has been fixed before you dig
into it.

Other fixes will take longer, especially those relating to structure
members or function parameters that lack documentation.  In such cases, it
is necessary to work out what the role of those members or parameters is
and describe them correctly.  Overall, this task gets a little tedious at
times, but it's highly important.  If we can actually eliminate warnings
from the documentation build, then we can start expecting developers to
avoid adding new ones.

Languishing kerneldoc comments
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Developers are encouraged to write kerneldoc comments for their code, but
many of those comments are never pulled into the docs build.  That makes
this information harder to find and, for example, makes Sphinx unable to
generate links to that documentation.  Adding ``kernel-doc`` directives to
the documentation to bring those comments in can help the community derive
the full value of the work that has gone into creating them.

The ``scripts/find-unused-docs.sh`` tool can be used to find these
overlooked comments.

Note that the most value comes from pulling in the documentation for
exported functions and data structures.  Many subsystems also have
kerneldoc comments for internal use; those should not be pulled into the
documentation build unless they are placed in a document that is
specifically aimed at developers working within the relevant subsystem.

Typo fixes
~~~~~~~~~~

Fixing typographical or formatting errors in the documentation is a quick
way to figure out how to create and send patches, and it is a useful
service.  I am always willing to accept such patches.  That said, once you
have fixed a few, please consider moving on to more advanced tasks, leaving
some typos for the next beginner to address.

Please note that some things are *not* typos and should not be "fixed":

 - Both American and British English spellings are allowed within the
   kernel documentation.  There is no need to fix one by replacing it with
   the other.

 - The question of whether a period should be followed by one or two spaces
   is not to be debated in the context of kernel documentation.  Other
   areas of rational disagreement, such as the "Oxford comma", are also
   off-topic here.

As with any patch to any project, please consider whether your change is
really making things better.

Ancient documentation
~~~~~~~~~~~~~~~~~~~~~

Some kernel documentation is current, maintained, and useful.  Some
documentation is ... not.  Dusty, old, and inaccurate documentation can
mislead readers and casts doubt on our documentation as a whole.  Anything
that can be done to address such problems is more than welcome.

Whenever you are working with a document, please consider whether it is
current, whether it needs updating, or whether it should perhaps be removed
altogether.  There are a number of warning signs that you can pay attention
to here:

 - References to 2.x kernels
 - Pointers to SourceForge repositories
 - Nothing but typo fixes in the history for several years
 - Discussion of pre-Git workflows

The best thing to do, of course, would be to bring the documentation
current, adding whatever information is needed.  Such work often requires
the cooperation of developers familiar with the subsystem in question, of
course.  Developers are often more than willing to cooperate with people
working to improve the documentation when asked nicely, and when their
answers are listened to and acted upon.

Some documentation is beyond hope; we occasionally find documents that
refer to code that was removed from the kernel long ago, for example.
There is surprising resistance to removing obsolete documentation, but we
should do that anyway.  Extra cruft in our documentation helps nobody.

In cases where there is perhaps some useful information in a badly outdated
document, and you are unable to update it, the best thing to do may be to
add a warning at the beginning.  The following text is recommended::

  .. warning ::
  	This document is outdated and in need of attention.  Please use
	this information with caution, and please consider sending patches
	to update it.

That way, at least our long-suffering readers have been warned that the
document may lead them astray.

Documentation coherency
~~~~~~~~~~~~~~~~~~~~~~~

The old-timers around here will remember the Linux books that showed up on
the shelves in the 1990s.  They were simply collections of documentation
files scrounged from various locations on the net.  The books have (mostly)
improved since then, but the kernel's documentation is still mostly built
on that model.  It is thousands of files, almost each of which was written
in isolation from all of the others.  We don't have a coherent body of
kernel documentation; we have thousands of individual documents.

We have been trying to improve the situation through the creation of
a set of "books" that group documentation for specific readers.  These
include:

 - Documentation/admin-guide/index.rst
 - Documentation/core-api/index.rst
 - Documentation/driver-api/index.rst
 - Documentation/userspace-api/index.rst

As well as this book on documentation itself.

Moving documents into the appropriate books is an important task and needs
to continue.  There are a couple of challenges associated with this work,
though.  Moving documentation files creates short-term pain for the people
who work with those files; they are understandably unenthusiastic about
such changes.  Usually the case can be made to move a document once; we
really don't want to keep shifting them around, though.

Even when all documents are in the right place, though, we have only
managed to turn a big pile into a group of smaller piles.  The work of
trying to knit all of those documents together into a single whole has not
yet begun.  If you have bright ideas on how we could proceed on that front,
we would be more than happy to hear them.

Stylesheet improvements
~~~~~~~~~~~~~~~~~~~~~~~

With the adoption of Sphinx we have much nicer-looking HTML output than we
once did.  But it could still use a lot of improvement; Donald Knuth and
Edward Tufte would be unimpressed.  That requires tweaking our stylesheets
to create more typographically sound, accessible, and readable output.

Be warned: if you take on this task you are heading into classic bikeshed
territory.  Expect a lot of opinions and discussion for even relatively
obvious changes.  That is, alas, the nature of the world we live in.

Non-LaTeX PDF build
~~~~~~~~~~~~~~~~~~~

This is a decidedly nontrivial task for somebody with a lot of time and
Python skills.  The Sphinx toolchain is relatively small and well
contained; it is easy to add to a development system.  But building PDF or
EPUB output requires installing LaTeX, which is anything but small or well
contained.  That would be a nice thing to eliminate.

The original hope had been to use the rst2pdf tool (https://rst2pdf.org/)
for PDF generation, but it turned out to not be up to the task.
Development work on rst2pdf seems to have picked up again in recent times,
though, which is a hopeful sign.  If a suitably motivated developer were to
work with that project to make rst2pdf work with the kernel documentation
build, the world would be eternally grateful.

Write more documentation
~~~~~~~~~~~~~~~~~~~~~~~~

Naturally, there are massive parts of the kernel that are severely
underdocumented.  If you have the knowledge to document a specific kernel
subsystem and the desire to do so, please do not hesitate to do some
writing and contribute the result to the kernel.  Untold numbers of kernel
developers and users will thank you.

repo_name: angery/linux


code:
.. _doc_guide:

=================================
How to write kernel documentation
=================================

.. toctree::
   :maxdepth: 1

   sphinx
   kernel-doc
   parse-headers
   contributing
   maintainer-profile

.. only::  subproject and html

   Indices
   =======

   * :ref:`genindex`


code:
.. title:: Kernel-doc comments

===========================
Writing kernel-doc comments
===========================

The Linux kernel source files may contain structured documentation
comments in the kernel-doc format to describe the functions, types
and design of the code. It is easier to keep documentation up-to-date
when it is embedded in source files.

.. note:: The kernel-doc format is deceptively similar to javadoc,
   gtk-doc or Doxygen, yet distinctively different, for historical
   reasons. The kernel source contains tens of thousands of kernel-doc
   comments. Please stick to the style described here.

.. note:: kernel-doc does not cover Rust code: please see
   Documentation/rust/general-information.rst instead.

The kernel-doc structure is extracted from the comments, and proper
`Sphinx C Domain`_ function and type descriptions with anchors are
generated from them. The descriptions are filtered for special kernel-doc
highlights and cross-references. See below for details.

.. _Sphinx C Domain: http://www.sphinx-doc.org/en/stable/domains.html

Every function that is exported to loadable modules using
``EXPORT_SYMBOL`` or ``EXPORT_SYMBOL_GPL`` should have a kernel-doc
comment. Functions and data structures in header files which are intended
to be used by modules should also have kernel-doc comments.

It is good practice to also provide kernel-doc formatted documentation
for functions externally visible to other kernel files (not marked
``static``). We also recommend providing kernel-doc formatted
documentation for private (file ``static``) routines, for consistency of
kernel source code layout. This is lower priority and at the discretion
of the maintainer of that kernel source file.

How to format kernel-doc comments
---------------------------------

The opening comment mark ``/**`` is used for kernel-doc comments. The
``kernel-doc`` tool will extract comments marked this way. The rest of
the comment is formatted like a normal multi-line comment with a column
of asterisks on the left side, closing with ``*/`` on a line by itself.

The function and type kernel-doc comments should be placed just before
the function or type being described in order to maximise the chance
that somebody changing the code will also change the documentation. The
overview kernel-doc comments may be placed anywhere at the top indentation
level.

Running the ``kernel-doc`` tool with increased verbosity and without actual
output generation may be used to verify proper formatting of the
documentation comments. For example::

	scripts/kernel-doc -v -none drivers/foo/bar.c

The documentation format is verified by the kernel build when it is
requested to perform extra gcc checks::

	make W=n

Function documentation
----------------------

The general format of a function and function-like macro kernel-doc comment is::

  /**
   * function_name() - Brief description of function.
   * @arg1: Describe the first argument.
   * @arg2: Describe the second argument.
   *        One can provide multiple line descriptions
   *        for arguments.
   *
   * A longer description, with more discussion of the function function_name()
   * that might be useful to those using or modifying it. Begins with an
   * empty comment line, and may include additional embedded empty
   * comment lines.
   *
   * The longer description may have multiple paragraphs.
   *
   * Context: Describes whether the function can sleep, what locks it takes,
   *          releases, or expects to be held. It can extend over multiple
   *          lines.
   * Return: Describe the return value of function_name.
   *
   * The return value description can also have multiple paragraphs, and should
   * be placed at the end of the comment block.
   */

The brief description following the function name may span multiple lines, and
ends with an argument description, a blank comment line, or the end of the
comment block.

Function parameters
~~~~~~~~~~~~~~~~~~~

Each function argument should be described in order, immediately following
the short function description.  Do not leave a blank line between the
function description and the arguments, nor between the arguments.

Each ``@argument:`` description may span multiple lines.

.. note::

   If the ``@argument`` description has multiple lines, the continuation
   of the description should start at the same column as the previous line::

      * @argument: some long description
      *            that continues on next lines

   or::

      * @argument:
      *		some long description
      *		that continues on next lines

If a function has a variable number of arguments, its description should
be written in kernel-doc notation as::

      * @...: description

Function context
~~~~~~~~~~~~~~~~

The context in which a function can be called should be described in a
section named ``Context``. This should include whether the function
sleeps or can be called from interrupt context, as well as what locks
it takes, releases and expects to be held by its caller.

Examples::

  * Context: Any context.
  * Context: Any context. Takes and releases the RCU lock.
  * Context: Any context. Expects <lock> to be held by caller.
  * Context: Process context. May sleep if @gfp flags permit.
  * Context: Process context. Takes and releases <mutex>.
  * Context: Softirq or process context. Takes and releases <lock>, BH-safe.
  * Context: Interrupt context.

Return values
~~~~~~~~~~~~~

The return value, if any, should be described in a dedicated section
named ``Return``.

.. note::

  #) The multi-line descriptive text you provide does *not* recognize
     line breaks, so if you try to format some text nicely, as in::

	* Return:
	* 0 - OK
	* -EINVAL - invalid argument
	* -ENOMEM - out of memory

     this will all run together and produce::

	Return: 0 - OK -EINVAL - invalid argument -ENOMEM - out of memory

     So, in order to produce the desired line breaks, you need to use a
     ReST list, e. g.::

      * Return:
      * * 0		- OK to runtime suspend the device
      * * -EBUSY	- Device should not be runtime suspended

  #) If the descriptive text you provide has lines that begin with
     some phrase followed by a colon, each of those phrases will be taken
     as a new section heading, which probably won't produce the desired
     effect.

Structure, union, and enumeration documentation
-----------------------------------------------

The general format of a struct, union, and enum kernel-doc comment is::

  /**
   * struct struct_name - Brief description.
   * @member1: Description of member1.
   * @member2: Description of member2.
   *           One can provide multiple line descriptions
   *           for members.
   *
   * Description of the structure.
   */

You can replace the ``struct`` in the above example with ``union`` or
``enum``  to describe unions or enums. ``member`` is used to mean struct
and union member names as well as enumerations in an enum.

The brief description following the structure name may span multiple
lines, and ends with a member description, a blank comment line, or the
end of the comment block.

Members
~~~~~~~

Members of structs, unions and enums should be documented the same way
as function parameters; they immediately succeed the short description
and may be multi-line.

Inside a struct or union description, you can use the ``private:`` and
``public:`` comment tags. Structure fields that are inside a ``private:``
area are not listed in the generated output documentation.

The ``private:`` and ``public:`` tags must begin immediately following a
``/*`` comment marker. They may optionally include comments between the
``:`` and the ending ``*/`` marker.

Example::

  /**
   * struct my_struct - short description
   * @a: first member
   * @b: second member
   * @d: fourth member
   *
   * Longer description
   */
  struct my_struct {
      int a;
      int b;
  /* private: internal use only */
      int c;
  /* public: the next one is public */
      int d;
  };

Nested structs/unions
~~~~~~~~~~~~~~~~~~~~~

It is possible to document nested structs and unions, like::

      /**
       * struct nested_foobar - a struct with nested unions and structs
       * @memb1: first member of anonymous union/anonymous struct
       * @memb2: second member of anonymous union/anonymous struct
       * @memb3: third member of anonymous union/anonymous struct
       * @memb4: fourth member of anonymous union/anonymous struct
       * @bar: non-anonymous union
       * @bar.st1: struct st1 inside @bar
       * @bar.st2: struct st2 inside @bar
       * @bar.st1.memb1: first member of struct st1 on union bar
       * @bar.st1.memb2: second member of struct st1 on union bar
       * @bar.st2.memb1: first member of struct st2 on union bar
       * @bar.st2.memb2: second member of struct st2 on union bar
       */
      struct nested_foobar {
        /* Anonymous union/struct*/
        union {
          struct {
            int memb1;
            int memb2;
          };
          struct {
            void *memb3;
            int memb4;
          };
        };
        union {
          struct {
            int memb1;
            int memb2;
          } st1;
          struct {
            void *memb1;
            int memb2;
          } st2;
        } bar;
      };

.. note::

   #) When documenting nested structs or unions, if the struct/union ``foo``
      is named, the member ``bar`` inside it should be documented as
      ``@foo.bar:``
   #) When the nested struct/union is anonymous, the member ``bar`` in it
      should be documented as ``@bar:``

In-line member documentation comments
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The structure members may also be documented in-line within the definition.
There are two styles, single-line comments where both the opening ``/**`` and
closing ``*/`` are on the same line, and multi-line comments where they are each
on a line of their own, like all other kernel-doc comments::

  /**
   * struct foo - Brief description.
   * @foo: The Foo member.
   */
  struct foo {
        int foo;
        /**
         * @bar: The Bar member.
         */
        int bar;
        /**
         * @baz: The Baz member.
         *
         * Here, the member description may contain several paragraphs.
         */
        int baz;
        union {
                /** @foobar: Single line description. */
                int foobar;
        };
        /** @bar2: Description for struct @bar2 inside @foo */
        struct {
                /**
                 * @bar2.barbar: Description for @barbar inside @foo.bar2
                 */
                int barbar;
        } bar2;
  };

Typedef documentation
---------------------

The general format of a typedef kernel-doc comment is::

  /**
   * typedef type_name - Brief description.
   *
   * Description of the type.
   */

Typedefs with function prototypes can also be documented::

  /**
   * typedef type_name - Brief description.
   * @arg1: description of arg1
   * @arg2: description of arg2
   *
   * Description of the type.
   *
   * Context: Locking context.
   * Return: Meaning of the return value.
   */
   typedef void (*type_name)(struct v4l2_ctrl *arg1, void *arg2);

Highlights and cross-references
-------------------------------

The following special patterns are recognized in the kernel-doc comment
descriptive text and converted to proper reStructuredText markup and `Sphinx C
Domain`_ references.

.. attention:: The below are **only** recognized within kernel-doc comments,
	       **not** within normal reStructuredText documents.

``funcname()``
  Function reference.

``@parameter``
  Name of a function parameter. (No cross-referencing, just formatting.)

``%CONST``
  Name of a constant. (No cross-referencing, just formatting.)

````literal````
  A literal block that should be handled as-is. The output will use a
  ``monospaced font``.

  Useful if you need to use special characters that would otherwise have some
  meaning either by kernel-doc script or by reStructuredText.

  This is particularly useful if you need to use things like ``%ph`` inside
  a function description.

``$ENVVAR``
  Name of an environment variable. (No cross-referencing, just formatting.)

``&struct name``
  Structure reference.

``&enum name``
  Enum reference.

``&typedef name``
  Typedef reference.

``&struct_name->member`` or ``&struct_name.member``
  Structure or union member reference. The cross-reference will be to the struct
  or union definition, not the member directly.

``&name``
  A generic type reference. Prefer using the full reference described above
  instead. This is mostly for legacy comments.

Cross-referencing from reStructuredText
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

No additional syntax is needed to cross-reference the functions and types
defined in the kernel-doc comments from reStructuredText documents.
Just end function names with ``()`` and write ``struct``, ``union``, ``enum``
or ``typedef`` before types.
For example::

  See foo().
  See struct foo.
  See union bar.
  See enum baz.
  See typedef meh.

However, if you want custom text in the cross-reference link, that can be done
through the following syntax::

  See :c:func:`my custom link text for function foo <foo>`.
  See :c:type:`my custom link text for struct bar <bar>`.

For further details, please refer to the `Sphinx C Domain`_ documentation.

Overview documentation comments
-------------------------------

To facilitate having source code and comments close together, you can include
kernel-doc documentation blocks that are free-form comments instead of being
kernel-doc for functions, structures, unions, enums, or typedefs. This could be
used for something like a theory of operation for a driver or library code, for
example.

This is done by using a ``DOC:`` section keyword with a section title.

The general format of an overview or high-level documentation comment is::

  /**
   * DOC: Theory of Operation
   *
   * The whizbang foobar is a dilly of a gizmo. It can do whatever you
   * want it to do, at any time. It reads your mind. Here's how it works.
   *
   * foo bar splat
   *
   * The only drawback to this gizmo is that is can sometimes damage
   * hardware, software, or its subject(s).
   */

The title following ``DOC:`` acts as a heading within the source file, but also
as an identifier for extracting the documentation comment. Thus, the title must
be unique within the file.

=============================
Including kernel-doc comments
=============================

The documentation comments may be included in any of the reStructuredText
documents using a dedicated kernel-doc Sphinx directive extension.

The kernel-doc directive is of the format::

  .. kernel-doc:: source
     :option:

The *source* is the path to a source file, relative to the kernel source
tree. The following directive options are supported:

export: *[source-pattern ...]*
  Include documentation for all functions in *source* that have been exported
  using ``EXPORT_SYMBOL`` or ``EXPORT_SYMBOL_GPL`` either in *source* or in any
  of the files specified by *source-pattern*.

  The *source-pattern* is useful when the kernel-doc comments have been placed
  in header files, while ``EXPORT_SYMBOL`` and ``EXPORT_SYMBOL_GPL`` are next to
  the function definitions.

  Examples::

    .. kernel-doc:: lib/bitmap.c
       :export:

    .. kernel-doc:: include/net/mac80211.h
       :export: net/mac80211/*.c

internal: *[source-pattern ...]*
  Include documentation for all functions and types in *source* that have
  **not** been exported using ``EXPORT_SYMBOL`` or ``EXPORT_SYMBOL_GPL`` either
  in *source* or in any of the files specified by *source-pattern*.

  Example::

    .. kernel-doc:: drivers/gpu/drm/i915/intel_audio.c
       :internal:

identifiers: *[ function/type ...]*
  Include documentation for each *function* and *type* in *source*.
  If no *function* is specified, the documentation for all functions
  and types in the *source* will be included.

  Examples::

    .. kernel-doc:: lib/bitmap.c
       :identifiers: bitmap_parselist bitmap_parselist_user

    .. kernel-doc:: lib/idr.c
       :identifiers:

no-identifiers: *[ function/type ...]*
  Exclude documentation for each *function* and *type* in *source*.

  Example::

    .. kernel-doc:: lib/bitmap.c
       :no-identifiers: bitmap_parselist

functions: *[ function/type ...]*
  This is an alias of the 'identifiers' directive and deprecated.

doc: *title*
  Include documentation for the ``DOC:`` paragraph identified by *title* in
  *source*. Spaces are allowed in *title*; do not quote the *title*. The *title*
  is only used as an identifier for the paragraph, and is not included in the
  output. Please make sure to have an appropriate heading in the enclosing
  reStructuredText document.

  Example::

    .. kernel-doc:: drivers/gpu/drm/i915/intel_audio.c
       :doc: High Definition Audio over HDMI and Display Port

Without options, the kernel-doc directive includes all documentation comments
from the source file.

The kernel-doc extension is included in the kernel source tree, at
``Documentation/sphinx/kerneldoc.py``. Internally, it uses the
``scripts/kernel-doc`` script to extract the documentation comments from the
source.

.. _kernel_doc:

How to use kernel-doc to generate man pages
-------------------------------------------

If you just want to use kernel-doc to generate man pages you can do this
from the kernel git tree::

  $ scripts/kernel-doc -man \
    $(git grep -l '/\*\*' -- :^Documentation :^tools) \
    | scripts/split-man.pl /tmp/man

Some older versions of git do not support some of the variants of syntax for
path exclusion.  One of the following commands may work for those versions::

  $ scripts/kernel-doc -man \
    $(git grep -l '/\*\*' -- . ':!Documentation' ':!tools') \
    | scripts/split-man.pl /tmp/man

  $ scripts/kernel-doc -man \
    $(git grep -l '/\*\*' -- . ":(exclude)Documentation" ":(exclude)tools") \
    | scripts/split-man.pl /tmp/man


code:
.. SPDX-License-Identifier: GPL-2.0

Documentation subsystem maintainer entry profile
================================================

The documentation "subsystem" is the central coordinating point for the
kernel's documentation and associated infrastructure.  It covers the
hierarchy under Documentation/ (with the exception of
Documentation/devicetree), various utilities under scripts/ and, at least
some of the time, LICENSES/.

It's worth noting, though, that the boundaries of this subsystem are rather
fuzzier than normal.  Many other subsystem maintainers like to keep control
of portions of Documentation/, and many more freely apply changes there
when it is convenient.  Beyond that, much of the kernel's documentation is
found in the source as kerneldoc comments; those are usually (but not
always) maintained by the relevant subsystem maintainer.

The mailing list for documentation is linux-doc@vger.kernel.org.  Patches
should be made against the docs-next tree whenever possible.

Submit checklist addendum
-------------------------

When making documentation changes, you should actually build the
documentation and ensure that no new errors or warnings have been
introduced.  Generating HTML documents and looking at the result will help
to avoid unsightly misunderstandings about how things will be rendered.

Key cycle dates
---------------

Patches can be sent anytime, but response will be slower than usual during
the merge window.  The docs tree tends to close late before the merge
window opens, since the risk of regressions from documentation patches is
low.

Review cadence
--------------

I am the sole maintainer for the documentation subsystem, and I am doing
the work on my own time, so the response to patches will occasionally be
slow.  I try to always send out a notification when a patch is merged (or
when I decide that one cannot be).  Do not hesitate to send a ping if you
have not heard back within a week of sending a patch.


code:
===========================
Including uAPI header files
===========================

Sometimes, it is useful to include header files and C example codes in
order to describe the userspace API and to generate cross-references
between the code and the documentation. Adding cross-references for
userspace API files has an additional vantage: Sphinx will generate warnings
if a symbol is not found at the documentation. That helps to keep the
uAPI documentation in sync with the Kernel changes.
The :ref:`parse_headers.pl <parse_headers>` provide a way to generate such
cross-references. It has to be called via Makefile, while building the
documentation. Please see ``Documentation/userspace-api/media/Makefile`` for an example
about how to use it inside the Kernel tree.

.. _parse_headers:

parse_headers.pl
^^^^^^^^^^^^^^^^

NAME
****

parse_headers.pl - parse a C file, in order to identify functions, structs,
enums and defines and create cross-references to a Sphinx book.

SYNOPSIS
********

\ **parse_headers.pl**\  [<options>] <C_FILE> <OUT_FILE> [<EXCEPTIONS_FILE>]

Where <options> can be: --debug, --help or --usage.

OPTIONS
*******

\ **--debug**\

 Put the script in verbose mode, useful for debugging.

\ **--usage**\

 Prints a brief help message and exits.

\ **--help**\

 Prints a more detailed help message and exits.

DESCRIPTION
***********

Convert a C header or source file (C_FILE), into a ReStructured Text
included via ..parsed-literal block with cross-references for the
documentation files that describe the API. It accepts an optional
EXCEPTIONS_FILE with describes what elements will be either ignored or
be pointed to a non-default reference.

The output is written at the (OUT_FILE).

It is capable of identifying defines, functions, structs, typedefs,
enums and enum symbols and create cross-references for all of them.
It is also capable of distinguish #define used for specifying a Linux
ioctl.

The EXCEPTIONS_FILE contain two types of statements: \ **ignore**\  or \ **replace**\ .

The syntax for the ignore tag is:

ignore \ **type**\  \ **name**\

The \ **ignore**\  means that it won't generate cross references for a
\ **name**\  symbol of type \ **type**\ .

The syntax for the replace tag is:

replace \ **type**\  \ **name**\  \ **new_value**\

The \ **replace**\  means that it will generate cross references for a
\ **name**\  symbol of type \ **type**\ , but, instead of using the default
replacement rule, it will use \ **new_value**\ .

For both statements, \ **type**\  can be either one of the following:

\ **ioctl**\

 The ignore or replace statement will apply to ioctl definitions like:

 #define	VIDIOC_DBG_S_REGISTER 	 _IOW('V', 79, struct v4l2_dbg_register)

\ **define**\

 The ignore or replace statement will apply to any other #define found
 at C_FILE.

\ **typedef**\

 The ignore or replace statement will apply to typedef statements at C_FILE.

\ **struct**\

 The ignore or replace statement will apply to the name of struct statements
 at C_FILE.

\ **enum**\

 The ignore or replace statement will apply to the name of enum statements
 at C_FILE.

\ **symbol**\

 The ignore or replace statement will apply to the name of enum value
 at C_FILE.

 For replace statements, \ **new_value**\  will automatically use :c:type:
 references for \ **typedef**\ , \ **enum**\  and \ **struct**\  types. It will use :ref:
 for \ **ioctl**\ , \ **define**\  and \ **symbol**\  types. The type of reference can
 also be explicitly defined at the replace statement.

EXAMPLES
********

ignore define _VIDEODEV2_H

Ignore a #define _VIDEODEV2_H at the C_FILE.

ignore symbol PRIVATE

On a struct like:

enum foo { BAR1, BAR2, PRIVATE };

It won't generate cross-references for \ **PRIVATE**\ .

replace symbol BAR1 :c:type:\`foo\`
replace symbol BAR2 :c:type:\`foo\`

On a struct like:

enum foo { BAR1, BAR2, PRIVATE };

It will make the BAR1 and BAR2 enum symbols to cross reference the foo
symbol at the C domain.

BUGS
****

Report bugs to Mauro Carvalho Chehab <mchehab@kernel.org>

COPYRIGHT
*********

Copyright (c) 2016 by Mauro Carvalho Chehab <mchehab+samsung@kernel.org>.

License GPLv2: GNU GPL version 2 <https://gnu.org/licenses/gpl.html>.

This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.


code:
.. _sphinxdoc:

=====================================
Using Sphinx for kernel documentation
=====================================

The Linux kernel uses `Sphinx`_ to generate pretty documentation from
`reStructuredText`_ files under ``Documentation``. To build the documentation in
HTML or PDF formats, use ``make htmldocs`` or ``make pdfdocs``. The generated
documentation is placed in ``Documentation/output``.

.. _Sphinx: http://www.sphinx-doc.org/
.. _reStructuredText: http://docutils.sourceforge.net/rst.html

The reStructuredText files may contain directives to include structured
documentation comments, or kernel-doc comments, from source files. Usually these
are used to describe the functions and types and design of the code. The
kernel-doc comments have some special structure and formatting, but beyond that
they are also treated as reStructuredText.

Finally, there are thousands of plain text documentation files scattered around
``Documentation``. Some of these will likely be converted to reStructuredText
over time, but the bulk of them will remain in plain text.

.. _sphinx_install:

Sphinx Install
==============

The ReST markups currently used by the Documentation/ files are meant to be
built with ``Sphinx`` version 1.7 or higher.

There's a script that checks for the Sphinx requirements. Please see
:ref:`sphinx-pre-install` for further details.

Most distributions are shipped with Sphinx, but its toolchain is fragile,
and it is not uncommon that upgrading it or some other Python packages
on your machine would cause the documentation build to break.

A way to avoid that is to use a different version than the one shipped
with your distributions. In order to do so, it is recommended to install
Sphinx inside a virtual environment, using ``virtualenv-3``
or ``virtualenv``, depending on how your distribution packaged Python 3.

.. note::

   #) It is recommended to use the RTD theme for html output. Depending
      on the Sphinx version, it should be installed separately,
      with ``pip install sphinx_rtd_theme``.

In summary, if you want to install Sphinx version 2.4.4, you should do::

       $ virtualenv sphinx_2.4.4
       $ . sphinx_2.4.4/bin/activate
       (sphinx_2.4.4) $ pip install -r Documentation/sphinx/requirements.txt

After running ``. sphinx_2.4.4/bin/activate``, the prompt will change,
in order to indicate that you're using the new environment. If you
open a new shell, you need to rerun this command to enter again at
the virtual environment before building the documentation.

Image output
------------

The kernel documentation build system contains an extension that
handles images on both GraphViz and SVG formats (see
:ref:`sphinx_kfigure`).

For it to work, you need to install both GraphViz and ImageMagick
packages. If those packages are not installed, the build system will
still build the documentation, but won't include any images at the
output.

PDF and LaTeX builds
--------------------

Such builds are currently supported only with Sphinx versions 2.4 and higher.

For PDF and LaTeX output, you'll also need ``XeLaTeX`` version 3.14159265.

Depending on the distribution, you may also need to install a series of
``texlive`` packages that provide the minimal set of functionalities
required for ``XeLaTeX`` to work.

Math Expressions in HTML
------------------------

Some ReST pages contain math expressions. Due to the way Sphinx works,
those expressions are written using LaTeX notation.
There are two options for Sphinx to render math expressions in html output.
One is an extension called `imgmath`_ which converts math expressions into
images and embeds them in html pages.
The other is an extension called `mathjax`_ which delegates math rendering
to JavaScript capable web browsers.
The former was the only option for pre-6.1 kernel documentation and it
requires quite a few texlive packages including amsfonts and amsmath among
others.

Since kernel release 6.1, html pages with math expressions can be built
without installing any texlive packages. See `Choice of Math Renderer`_ for
further info.

.. _imgmath: https://www.sphinx-doc.org/en/master/usage/extensions/math.html#module-sphinx.ext.imgmath
.. _mathjax: https://www.sphinx-doc.org/en/master/usage/extensions/math.html#module-sphinx.ext.mathjax

.. _sphinx-pre-install:

Checking for Sphinx dependencies
--------------------------------

There's a script that automatically check for Sphinx dependencies. If it can
recognize your distribution, it will also give a hint about the install
command line options for your distro::

	$ ./scripts/sphinx-pre-install
	Checking if the needed tools for Fedora release 26 (Twenty Six) are available
	Warning: better to also install "texlive-luatex85".
	You should run:

		sudo dnf install -y texlive-luatex85
		/usr/bin/virtualenv sphinx_2.4.4
		. sphinx_2.4.4/bin/activate
		pip install -r Documentation/sphinx/requirements.txt

	Can't build as 1 mandatory dependency is missing at ./scripts/sphinx-pre-install line 468.

By default, it checks all the requirements for both html and PDF, including
the requirements for images, math expressions and LaTeX build, and assumes
that a virtual Python environment will be used. The ones needed for html
builds are assumed to be mandatory; the others to be optional.

It supports two optional parameters:

``--no-pdf``
	Disable checks for PDF;

``--no-virtualenv``
	Use OS packaging for Sphinx instead of Python virtual environment.

Sphinx Build
============

The usual way to generate the documentation is to run ``make htmldocs`` or
``make pdfdocs``. There are also other formats available: see the documentation
section of ``make help``. The generated documentation is placed in
format-specific subdirectories under ``Documentation/output``.

To generate documentation, Sphinx (``sphinx-build``) must obviously be
installed.  For PDF output you'll also need ``XeLaTeX`` and ``convert(1)``
from ImageMagick (https://www.imagemagick.org).\ [#ink]_ All of these are
widely available and packaged in distributions.

To pass extra options to Sphinx, you can use the ``SPHINXOPTS`` make
variable. For example, use ``make SPHINXOPTS=-v htmldocs`` to get more verbose
output.

It is also possible to pass an extra DOCS_CSS overlay file, in order to customize
the html layout, by using the ``DOCS_CSS`` make variable.

By default, the "Alabaster" theme is used to build the HTML documentation;
this theme is bundled with Sphinx and need not be installed separately.
The Sphinx theme can be overridden by using the ``DOCS_THEME`` make variable.

There is another make variable ``SPHINXDIRS``, which is useful when test
building a subset of documentation.  For example, you can build documents
under ``Documentation/doc-guide`` by running
``make SPHINXDIRS=doc-guide htmldocs``.
The documentation section of ``make help`` will show you the list of
subdirectories you can specify.

To remove the generated documentation, run ``make cleandocs``.

.. [#ink] Having ``inkscape(1)`` from Inkscape (https://inkscape.org)
	  as well would improve the quality of images embedded in PDF
	  documents, especially for kernel releases 5.18 and later.

Choice of Math Renderer
-----------------------

Since kernel release 6.1, mathjax works as a fallback math renderer for
html output.\ [#sph1_8]_

Math renderer is chosen depending on available commands as shown below:

.. table:: Math Renderer Choices for HTML

    ============= ================= ============
    Math renderer Required commands Image format
    ============= ================= ============
    imgmath       latex, dvipng     PNG (raster)
    mathjax
    ============= ================= ============

The choice can be overridden by setting an environment variable
``SPHINX_IMGMATH`` as shown below:

.. table:: Effect of Setting ``SPHINX_IMGMATH``

    ====================== ========
    Setting                Renderer
    ====================== ========
    ``SPHINX_IMGMATH=yes`` imgmath
    ``SPHINX_IMGMATH=no``  mathjax
    ====================== ========

.. [#sph1_8] Fallback of math renderer requires Sphinx >=1.8.

Writing Documentation
=====================

Adding new documentation can be as simple as:

1. Add a new ``.rst`` file somewhere under ``Documentation``.
2. Refer to it from the Sphinx main `TOC tree`_ in ``Documentation/index.rst``.

.. _TOC tree: http://www.sphinx-doc.org/en/stable/markup/toctree.html

This is usually good enough for simple documentation (like the one you're
reading right now), but for larger documents it may be advisable to create a
subdirectory (or use an existing one). For example, the graphics subsystem
documentation is under ``Documentation/gpu``, split to several ``.rst`` files,
and has a separate ``index.rst`` (with a ``toctree`` of its own) referenced from
the main index.

See the documentation for `Sphinx`_ and `reStructuredText`_ on what you can do
with them. In particular, the Sphinx `reStructuredText Primer`_ is a good place
to get started with reStructuredText. There are also some `Sphinx specific
markup constructs`_.

.. _reStructuredText Primer: http://www.sphinx-doc.org/en/stable/rest.html
.. _Sphinx specific markup constructs: http://www.sphinx-doc.org/en/stable/markup/index.html

Specific guidelines for the kernel documentation
------------------------------------------------

Here are some specific guidelines for the kernel documentation:

* Please don't go overboard with reStructuredText markup. Keep it
  simple. For the most part the documentation should be plain text with
  just enough consistency in formatting that it can be converted to
  other formats.

* Please keep the formatting changes minimal when converting existing
  documentation to reStructuredText.

* Also update the content, not just the formatting, when converting
  documentation.

* Please stick to this order of heading adornments:

  1. ``=`` with overline for document title::

       ==============
       Document title
       ==============

  2. ``=`` for chapters::

       Chapters
       ========

  3. ``-`` for sections::

       Section
       -------

  4. ``~`` for subsections::

       Subsection
       ~~~~~~~~~~

  Although RST doesn't mandate a specific order ("Rather than imposing a fixed
  number and order of section title adornment styles, the order enforced will be
  the order as encountered."), having the higher levels the same overall makes
  it easier to follow the documents.

* For inserting fixed width text blocks (for code examples, use case
  examples, etc.), use ``::`` for anything that doesn't really benefit
  from syntax highlighting, especially short snippets. Use
  ``.. code-block:: <language>`` for longer code blocks that benefit
  from highlighting. For a short snippet of code embedded in the text, use \`\`.

the C domain
------------

The **Sphinx C Domain** (name c) is suited for documentation of C API. E.g. a
function prototype:

.. code-block:: rst

    .. c:function:: int ioctl( int fd, int request )

The C domain of the kernel-doc has some additional features. E.g. you can
*rename* the reference name of a function with a common name like ``open`` or
``ioctl``:

.. code-block:: rst

     .. c:function:: int ioctl( int fd, int request )
        :name: VIDIOC_LOG_STATUS

The func-name (e.g. ioctl) remains in the output but the ref-name changed from
``ioctl`` to ``VIDIOC_LOG_STATUS``. The index entry for this function is also
changed to ``VIDIOC_LOG_STATUS``.

Please note that there is no need to use ``c:func:`` to generate cross
references to function documentation.  Due to some Sphinx extension magic,
the documentation build system will automatically turn a reference to
``function()`` into a cross reference if an index entry for the given
function name exists.  If you see ``c:func:`` use in a kernel document,
please feel free to remove it.

list tables
-----------

The list-table formats can be useful for tables that are not easily laid
out in the usual Sphinx ASCII-art formats.  These formats are nearly
impossible for readers of the plain-text documents to understand, though,
and should be avoided in the absence of a strong justification for their
use.

The ``flat-table`` is a double-stage list similar to the ``list-table`` with
some additional features:

* column-span: with the role ``cspan`` a cell can be extended through
  additional columns

* row-span: with the role ``rspan`` a cell can be extended through
  additional rows

* auto span rightmost cell of a table row over the missing cells on the right
  side of that table-row.  With Option ``:fill-cells:`` this behavior can
  changed from *auto span* to *auto fill*, which automatically inserts (empty)
  cells instead of spanning the last cell.

options:

* ``:header-rows:``   [int] count of header rows
* ``:stub-columns:``  [int] count of stub columns
* ``:widths:``        [[int] [int] ... ] widths of columns
* ``:fill-cells:``    instead of auto-spanning missing cells, insert missing cells

roles:

* ``:cspan:`` [int] additional columns (*morecols*)
* ``:rspan:`` [int] additional rows (*morerows*)

The example below shows how to use this markup.  The first level of the staged
list is the *table-row*. In the *table-row* there is only one markup allowed,
the list of the cells in this *table-row*. Exceptions are *comments* ( ``..`` )
and *targets* (e.g. a ref to ``:ref:`last row <last row>``` / :ref:`last row
<last row>`).

.. code-block:: rst

   .. flat-table:: table title
      :widths: 2 1 1 3

      * - head col 1
        - head col 2
        - head col 3
        - head col 4

      * - row 1
        - field 1.1
        - field 1.2 with autospan

      * - row 2
        - field 2.1
        - :rspan:`1` :cspan:`1` field 2.2 - 3.3

      * .. _`last row`:

        - row 3

Rendered as:

   .. flat-table:: table title
      :widths: 2 1 1 3

      * - head col 1
        - head col 2
        - head col 3
        - head col 4

      * - row 1
        - field 1.1
        - field 1.2 with autospan

      * - row 2
        - field 2.1
        - :rspan:`1` :cspan:`1` field 2.2 - 3.3

      * .. _`last row`:

        - row 3

Cross-referencing
-----------------

Cross-referencing from one documentation page to another can be done simply by
writing the path to the document file, no special syntax required. The path can
be either absolute or relative. For absolute paths, start it with
"Documentation/". For example, to cross-reference to this page, all the
following are valid options, depending on the current document's directory (note
that the ``.rst`` extension is required)::

    See Documentation/doc-guide/sphinx.rst. This always works.
    Take a look at sphinx.rst, which is at this same directory.
    Read ../sphinx.rst, which is one directory above.

If you want the link to have a different rendered text other than the document's
title, you need to use Sphinx's ``doc`` role. For example::

    See :doc:`my custom link text for document sphinx <sphinx>`.

For most use cases, the former is preferred, as it is cleaner and more suited
for people reading the source files. If you come across a ``:doc:`` usage that
isn't adding any value, please feel free to convert it to just the document
path.

For information on cross-referencing to kernel-doc functions or types, see
Documentation/doc-guide/kernel-doc.rst.

.. _sphinx_kfigure:

Figures & Images
================

If you want to add an image, you should use the ``kernel-figure`` and
``kernel-image`` directives. E.g. to insert a figure with a scalable
image format, use SVG (:ref:`svg_image_example`)::

    .. kernel-figure::  svg_image.svg
       :alt:    simple SVG image

       SVG image example

.. _svg_image_example:

.. kernel-figure::  svg_image.svg
   :alt:    simple SVG image

   SVG image example

The kernel figure (and image) directive supports **DOT** formatted files, see

* DOT: http://graphviz.org/pdf/dotguide.pdf
* Graphviz: http://www.graphviz.org/content/dot-language

A simple example (:ref:`hello_dot_file`)::

  .. kernel-figure::  hello.dot
     :alt:    hello world

     DOT's hello world example

.. _hello_dot_file:

.. kernel-figure::  hello.dot
   :alt:    hello world

   DOT's hello world example

Embedded *render* markups (or languages) like Graphviz's **DOT** are provided by the
``kernel-render`` directives.::

  .. kernel-render:: DOT
     :alt: foobar digraph
     :caption: Embedded **DOT** (Graphviz) code

     digraph foo {
      "bar" -> "baz";
     }

How this will be rendered depends on the installed tools. If Graphviz is
installed, you will see a vector image. If not, the raw markup is inserted as
*literal-block* (:ref:`hello_dot_render`).

.. _hello_dot_render:

.. kernel-render:: DOT
   :alt: foobar digraph
   :caption: Embedded **DOT** (Graphviz) code

   digraph foo {
      "bar" -> "baz";
   }

The *render* directive has all the options known from the *figure* directive,
plus option ``caption``.  If ``caption`` has a value, a *figure* node is
inserted. If not, an *image* node is inserted. A ``caption`` is also needed, if
you want to refer to it (:ref:`hello_svg_render`).

Embedded **SVG**::

  .. kernel-render:: SVG
     :caption: Embedded **SVG** markup
     :alt: so-nw-arrow

     <?xml version="1.0" encoding="UTF-8"?>
     <svg xmlns="http://www.w3.org/2000/svg" version="1.1" ...>
        ...
     </svg>

.. _hello_svg_render:

.. kernel-render:: SVG
   :caption: Embedded **SVG** markup
   :alt: so-nw-arrow

   <?xml version="1.0" encoding="UTF-8"?>
   <svg xmlns="http://www.w3.org/2000/svg"
     version="1.1" baseProfile="full" width="70px" height="40px" viewBox="0 0 700 400">
   <line x1="180" y1="370" x2="500" y2="50" stroke="black" stroke-width="15px"/>
   <polygon points="585 0 525 25 585 50" transform="rotate(135 525 25)"/>
   </svg>


code:
<?xml version="1.0" encoding="UTF-8"?>
<!-- originate: https://commons.wikimedia.org/wiki/File:Variable_Resistor.svg -->
<svg xmlns="http://www.w3.org/2000/svg"
	version="1.1" baseProfile="full"
	width="70px" height="40px" viewBox="0 0 700 400">
	<line x1="0" y1="200" x2="700" y2="200" stroke="black" stroke-width="20px"/>
	<rect x="100" y="100" width="500" height="200" fill="white" stroke="black" stroke-width="20px"/>
	<line x1="180" y1="370" x2="500" y2="50" stroke="black" stroke-width="15px"/>
	<polygon points="585 0 525 25 585 50" transform="rotate(135 525 25)"/>
</svg>


code:
# -*- coding: utf-8 mode: conf-colon -*-
#
# docutils configuration file
# http://docutils.sourceforge.net/docs/user/config.html

[general]
halt_level: severe


code:
*.a
*.aux
*.bc
*.bin
*.bz2
*.c.[012]*.*
*.cis
*.cpio
*.csp
*.dsp
*.dvi
*.elf
*.eps
*.fw
*.gcno
*.gcov
*.gen.S
*.gif
*.grep
*.grp
*.gz
*.html
*.i
*.jpeg
*.ko
*.ll
*.log
*.lst
*.lzma
*.lzo
*.mo
*.moc
*.mod
*.mod.c
*.o
*.o.*
*.order
*.orig
*.out
*.patch
*.pdf
*.plist
*.png
*.pot
*.ps
*.rej
*.s
*.sgml
*.so
*.so.dbg
*.symtypes
*.tab.c
*.tab.h
*.tex
*.ver
*.xml
*.xz
*.zst
*_MODULES
*_vga16.c
*~
\#*#
*.9
.*
.*.d
.mm
53c700_d.h
CVS
ChangeSet
GPATH
GRTAGS
GSYMS
GTAGS
Image
Module.markers
Module.symvers
PENDING
SCCS
System.map*
TAGS
aconf
af_names.h
aic7*reg.h*
aic7*reg_print.c*
aic7*seq.h*
aicasm
aicdb.h*
altivec*.c
asm-offsets.h
asm_offsets.h
autoconf.h*
av_permissions.h
bbootsect
bin2c
binkernel.spec
bootsect
bounds.h
bsetup
btfixupprep
build
bvmlinux
bzImage*
capability_names.h
capflags.c
classlist.h*
comp*.log
compile.h*
conf
config
config-*
config.mak
config.mak.autogen
conmakehash
consolemap_deftbl.c*
cpustr.h
crc32table.h*
cscope.*
defkeymap.c
devlist.h*
devicetable-offsets.h
dnotify_test
dslm
dtc
elf2ecoff
elfconfig.h*
evergreen_reg_safe.h
fixdep
flask.h
fore200e_mkfirm
fore200e_pca_fw.c*
gconf
gconf-cfg
gen-devlist
gen_crc32table
gen_init_cpio
generated
genheaders
genksyms
*_gray256.c
hpet_example
hugepage-mmap
hugepage-shm
ihex2fw
inat-tables.c
initramfs_list
int16.c
int1.c
int2.c
int32.c
int4.c
int8.c
kallsyms
keywords.c
ksym.c*
ksym.h*
*lex.c
*lex.*.c
linux
logo_*.c
logo_*_clut224.c
logo_*_mono.c
mach-types
mach-types.h
machtypes.h
map
map_hugetlb
mconf
mconf-cfg
miboot*
mk_elfconfig
mkboot
mkbugboot
mkcpustr
mkdep
mkprep
mkregtable
mktables
mktree
mkutf8data
modpost
modules-only.symvers
modules.builtin
modules.builtin.modinfo
modules.nsdeps
modules.order
modversions.h*
nconf
nconf-cfg
ncscope.*
offset.h
oui.c*
page-types
parse.c
parse.h
patches*
pca200e.bin
pca200e_ecd.bin2
perf.data
perf.data.old
perf-archive
piggyback
piggy.gzip
piggy.S
pnmtologo
ppc_defs.h*
pss_boot.h
qconf
qconf-cfg
r100_reg_safe.h
r200_reg_safe.h
r300_reg_safe.h
r420_reg_safe.h
r600_reg_safe.h
randstruct.seed
randomize_layout_hash.h
randomize_layout_seed.h
recordmcount
relocs
rlim_names.h
rn50_reg_safe.h
rs600_reg_safe.h
rv515_reg_safe.h
series
setup
setup.bin
setup.elf
sortextable
sImage
sm_tbl*
split-include
syscalltab.h
tables.c
tags
test_get_len
tftpboot.img
timeconst.h
times.h*
trix_boot.h
utsrelease.h*
vdso-syms.lds
vdso.lds
vdso32-int80-syms.lds
vdso32-syms.lds
vdso32-syscall-syms.lds
vdso32-sysenter-syms.lds
vdso32.lds
vdso32.so.dbg
vdso64.lds
vdso64.so.dbg
version.h*
vmImage
vmlinux
vmlinux-*
vmlinux.aout
vmlinux.bin.all
vmlinux.lds
vmlinux.map
vmlinux.symvers
vmlinuz
voffset.h
vsyscall.lds
vsyscall_32.lds
wanxlfw.inc
uImage
unifdef
utf8data.h
wakeup.bin
wakeup.elf
wakeup.lds
zImage*
zoffset.h

path: Documentation/dontdiff


code:
==================
cfg80211 subsystem
==================

.. kernel-doc:: include/net/cfg80211.h
   :doc: Introduction

Device registration
===================

.. kernel-doc:: include/net/cfg80211.h
   :doc: Device registration

.. kernel-doc:: include/net/cfg80211.h
   :functions:
	ieee80211_channel_flags
	ieee80211_channel
	ieee80211_rate_flags
	ieee80211_rate
	ieee80211_sta_ht_cap
	ieee80211_supported_band
	cfg80211_signal_type
	wiphy_params_flags
	wiphy_flags
	wiphy
	wireless_dev
	wiphy_new
	wiphy_read_of_freq_limits
	wiphy_register
	wiphy_unregister
	wiphy_free
	wiphy_name
	wiphy_dev
	wiphy_priv
	priv_to_wiphy
	set_wiphy_dev
	wdev_priv
	ieee80211_iface_limit
	ieee80211_iface_combination
	cfg80211_check_combinations

Actions and configuration
=========================

.. kernel-doc:: include/net/cfg80211.h
   :doc: Actions and configuration

.. kernel-doc:: include/net/cfg80211.h
   :functions:
	cfg80211_ops
	vif_params
	key_params
	survey_info_flags
	survey_info
	cfg80211_beacon_data
	cfg80211_ap_settings
	station_parameters
	rate_info_flags
	rate_info
	station_info
	monitor_flags
	mpath_info_flags
	mpath_info
	bss_parameters
	ieee80211_txq_params
	cfg80211_crypto_settings
	cfg80211_auth_request
	cfg80211_assoc_request
	cfg80211_deauth_request
	cfg80211_disassoc_request
	cfg80211_ibss_params
	cfg80211_connect_params
	cfg80211_pmksa
	cfg80211_rx_mlme_mgmt
	cfg80211_auth_timeout
	cfg80211_rx_assoc_resp
	cfg80211_assoc_timeout
	cfg80211_tx_mlme_mgmt
	cfg80211_ibss_joined
	cfg80211_connect_resp_params
	cfg80211_connect_done
	cfg80211_connect_result
	cfg80211_connect_bss
	cfg80211_connect_timeout
	cfg80211_roamed
	cfg80211_disconnected
	cfg80211_ready_on_channel
	cfg80211_remain_on_channel_expired
	cfg80211_new_sta
	cfg80211_rx_mgmt
	cfg80211_mgmt_tx_status
	cfg80211_cqm_rssi_notify
	cfg80211_cqm_pktloss_notify
	cfg80211_michael_mic_failure

Scanning and BSS list handling
==============================

.. kernel-doc:: include/net/cfg80211.h
   :doc: Scanning and BSS list handling

.. kernel-doc:: include/net/cfg80211.h
   :functions:
	cfg80211_ssid
	cfg80211_scan_request
	cfg80211_scan_done
	cfg80211_bss
	cfg80211_inform_bss
	cfg80211_inform_bss_frame_data
	cfg80211_inform_bss_data
	cfg80211_unlink_bss
	cfg80211_find_ie
	ieee80211_bss_get_ie

Utility functions
=================

.. kernel-doc:: include/net/cfg80211.h
   :doc: Utility functions

.. kernel-doc:: include/net/cfg80211.h
   :functions:
	ieee80211_channel_to_frequency
	ieee80211_frequency_to_channel
	ieee80211_get_channel
	ieee80211_get_response_rate
	ieee80211_hdrlen
	ieee80211_get_hdrlen_from_skb
	ieee80211_radiotap_iterator

Data path helpers
=================

.. kernel-doc:: include/net/cfg80211.h
   :doc: Data path helpers

.. kernel-doc:: include/net/cfg80211.h
   :functions:
	ieee80211_data_to_8023
	ieee80211_amsdu_to_8023s
	cfg80211_classify8021d

Regulatory enforcement infrastructure
=====================================

.. kernel-doc:: include/net/cfg80211.h
   :doc: Regulatory enforcement infrastructure

.. kernel-doc:: include/net/cfg80211.h
   :functions:
	regulatory_hint
	wiphy_apply_custom_regulatory
	freq_reg_info

RFkill integration
==================

.. kernel-doc:: include/net/cfg80211.h
   :doc: RFkill integration

.. kernel-doc:: include/net/cfg80211.h
   :functions:
	wiphy_rfkill_set_hw_state
	wiphy_rfkill_start_polling
	wiphy_rfkill_stop_polling

Test mode
=========

.. kernel-doc:: include/net/cfg80211.h
   :doc: Test mode

.. kernel-doc:: include/net/cfg80211.h
   :functions:
	cfg80211_testmode_alloc_reply_skb
	cfg80211_testmode_reply
	cfg80211_testmode_alloc_event_skb
	cfg80211_testmode_event


code:
============
Introduction
============

Explaining wireless 802.11 networking in the Linux kernel

Copyright 2007-2009 Johannes Berg

These books attempt to give a description of the various subsystems
that play a role in 802.11 wireless networking in Linux. Since these
books are for kernel developers they attempts to document the
structures and functions used in the kernel as well as giving a
higher-level overview.

The reader is expected to be familiar with the 802.11 standard as
published by the IEEE in 802.11-2007 (or possibly later versions).
References to this standard will be given as "802.11-2007 8.1.5".


code:
=============================
mac80211 subsystem (advanced)
=============================

Information contained within this part of the book is of interest only
for advanced interaction of mac80211 with drivers to exploit more
hardware capabilities and improve performance.

LED support
===========

Mac80211 supports various ways of blinking LEDs. Wherever possible,
device LEDs should be exposed as LED class devices and hooked up to the
appropriate trigger, which will then be triggered appropriately by
mac80211.

.. kernel-doc:: include/net/mac80211.h
   :functions:
	ieee80211_get_tx_led_name
	ieee80211_get_rx_led_name
	ieee80211_get_assoc_led_name
	ieee80211_get_radio_led_name
	ieee80211_tpt_blink
	ieee80211_tpt_led_trigger_flags
	ieee80211_create_tpt_led_trigger

Hardware crypto acceleration
============================

.. kernel-doc:: include/net/mac80211.h
   :doc: Hardware crypto acceleration

.. kernel-doc:: include/net/mac80211.h
   :functions:
	set_key_cmd
	ieee80211_key_conf
	ieee80211_key_flags
	ieee80211_get_tkip_p1k
	ieee80211_get_tkip_p1k_iv
	ieee80211_get_tkip_p2k

Powersave support
=================

.. kernel-doc:: include/net/mac80211.h
   :doc: Powersave support

Beacon filter support
=====================

.. kernel-doc:: include/net/mac80211.h
   :doc: Beacon filter support

.. kernel-doc:: include/net/mac80211.h
   :functions: ieee80211_beacon_loss

Multiple queues and QoS support
===============================

TBD

.. kernel-doc:: include/net/mac80211.h
   :functions: ieee80211_tx_queue_params

Access point mode support
=========================

TBD

Some parts of the if_conf should be discussed here instead

Insert notes about VLAN interfaces with hw crypto here or in the hw
crypto chapter.

support for powersaving clients
-------------------------------

.. kernel-doc:: include/net/mac80211.h
   :doc: AP support for powersaving clients

.. kernel-doc:: include/net/mac80211.h
   :functions:
	ieee80211_get_buffered_bc
	ieee80211_beacon_get
	ieee80211_sta_eosp
	ieee80211_frame_release_type
	ieee80211_sta_ps_transition
	ieee80211_sta_ps_transition_ni
	ieee80211_sta_set_buffered
	ieee80211_sta_block_awake

Supporting multiple virtual interfaces
======================================

TBD

Note: WDS with identical MAC address should almost always be OK

Insert notes about having multiple virtual interfaces with different MAC
addresses here, note which configurations are supported by mac80211, add
notes about supporting hw crypto with it.

.. kernel-doc:: include/net/mac80211.h
   :functions:
	ieee80211_iterate_active_interfaces
	ieee80211_iterate_active_interfaces_atomic

Station handling
================

TODO

.. kernel-doc:: include/net/mac80211.h
   :functions:
	ieee80211_sta
	sta_notify_cmd
	ieee80211_find_sta
	ieee80211_find_sta_by_ifaddr

Hardware scan offload
=====================

TBD

.. kernel-doc:: include/net/mac80211.h
   :functions: ieee80211_scan_completed

Aggregation
===========

TX A-MPDU aggregation
---------------------

.. kernel-doc:: net/mac80211/agg-tx.c
   :doc: TX A-MPDU aggregation

.. WARNING: DOCPROC directive not supported: !Cnet/mac80211/agg-tx.c

RX A-MPDU aggregation
---------------------

.. kernel-doc:: net/mac80211/agg-rx.c
   :doc: RX A-MPDU aggregation

.. WARNING: DOCPROC directive not supported: !Cnet/mac80211/agg-rx.c

.. kernel-doc:: include/net/mac80211.h
   :functions: ieee80211_ampdu_mlme_action

Spatial Multiplexing Powersave (SMPS)
=====================================

.. kernel-doc:: include/net/mac80211.h
   :doc: Spatial multiplexing power save

.. kernel-doc:: include/net/mac80211.h
   :functions:
	ieee80211_request_smps
	ieee80211_smps_mode

TBD

This part of the book describes the rate control algorithm interface and
how it relates to mac80211 and drivers.

Rate Control API
================

TBD

.. kernel-doc:: include/net/mac80211.h
   :functions:
	ieee80211_start_tx_ba_session
	ieee80211_start_tx_ba_cb_irqsafe
	ieee80211_stop_tx_ba_session
	ieee80211_stop_tx_ba_cb_irqsafe
	ieee80211_rate_control_changed
	ieee80211_tx_rate_control

TBD

This part of the book describes mac80211 internals.

Key handling
============

Key handling basics
-------------------

.. kernel-doc:: net/mac80211/key.c
   :doc: Key handling basics

MORE TBD
--------

TBD

Receive processing
==================

TBD

Transmit processing
===================

TBD

Station info handling
=====================

Programming information
-----------------------

.. kernel-doc:: net/mac80211/sta_info.h
   :functions:
	sta_info
	ieee80211_sta_info_flags

STA information lifetime rules
------------------------------

.. kernel-doc:: net/mac80211/sta_info.c
   :doc: STA information lifetime rules

Aggregation Functions
=====================

.. kernel-doc:: net/mac80211/sta_info.h
   :functions:
	sta_ampdu_mlme
	tid_ampdu_tx
	tid_ampdu_rx

Synchronisation Functions
=========================

TBD

Locking, lots of RCU


code:
===========================
mac80211 subsystem (basics)
===========================

You should read and understand the information contained within this
part of the book while implementing a mac80211 driver. In some chapters,
advanced usage is noted, those may be skipped if this isn't needed.

This part of the book only covers station and monitor mode
functionality, additional information required to implement the other
modes is covered in the second part of the book.

Basic hardware handling
=======================

TBD

This chapter shall contain information on getting a hw struct allocated
and registered with mac80211.

Since it is required to allocate rates/modes before registering a hw
struct, this chapter shall also contain information on setting up the
rate/mode structs.

Additionally, some discussion about the callbacks and the general
programming model should be in here, including the definition of
ieee80211_ops which will be referred to a lot.

Finally, a discussion of hardware capabilities should be done with
references to other parts of the book.

.. kernel-doc:: include/net/mac80211.h
   :functions:
	ieee80211_hw
	ieee80211_hw_flags
	SET_IEEE80211_DEV
	SET_IEEE80211_PERM_ADDR
	ieee80211_ops
	ieee80211_alloc_hw
	ieee80211_register_hw
	ieee80211_unregister_hw
	ieee80211_free_hw

PHY configuration
=================

TBD

This chapter should describe PHY handling including start/stop callbacks
and the various structures used.

.. kernel-doc:: include/net/mac80211.h
   :functions:
	ieee80211_conf
	ieee80211_conf_flags

Virtual interfaces
==================

TBD

This chapter should describe virtual interface basics that are relevant
to the driver (VLANs, MGMT etc are not.) It should explain the use of
the add_iface/remove_iface callbacks as well as the interface
configuration callbacks.

Things related to AP mode should be discussed there.

Things related to supporting multiple interfaces should be in the
appropriate chapter, a BIG FAT note should be here about this though and
the recommendation to allow only a single interface in STA mode at
first!

.. kernel-doc:: include/net/mac80211.h
   :functions: ieee80211_vif

Receive and transmit processing
===============================

what should be here
-------------------

TBD

This should describe the receive and transmit paths in mac80211/the
drivers as well as transmit status handling.

Frame format
------------

.. kernel-doc:: include/net/mac80211.h
   :doc: Frame format

Packet alignment
----------------

.. kernel-doc:: net/mac80211/rx.c
   :doc: Packet alignment

Calling into mac80211 from interrupts
-------------------------------------

.. kernel-doc:: include/net/mac80211.h
   :doc: Calling mac80211 from interrupts

functions/definitions
---------------------

.. kernel-doc:: include/net/mac80211.h
   :functions:
	ieee80211_rx_status
	mac80211_rx_encoding_flags
	mac80211_rx_flags
	mac80211_tx_info_flags
	mac80211_tx_control_flags
	mac80211_rate_control_flags
	ieee80211_tx_rate
	ieee80211_tx_info
	ieee80211_tx_info_clear_status
	ieee80211_rx
	ieee80211_rx_ni
	ieee80211_rx_irqsafe
	ieee80211_tx_status
	ieee80211_tx_status_ni
	ieee80211_tx_status_irqsafe
	ieee80211_rts_get
	ieee80211_rts_duration
	ieee80211_ctstoself_get
	ieee80211_ctstoself_duration
	ieee80211_generic_frame_duration
	ieee80211_wake_queue
	ieee80211_stop_queue
	ieee80211_wake_queues
	ieee80211_stop_queues
	ieee80211_queue_stopped

Frame filtering
===============

.. kernel-doc:: include/net/mac80211.h
   :doc: Frame filtering

.. kernel-doc:: include/net/mac80211.h
   :functions: ieee80211_filter_flags

The mac80211 workqueue
======================

.. kernel-doc:: include/net/mac80211.h
   :doc: mac80211 workqueue

.. kernel-doc:: include/net/mac80211.h
   :functions:
	ieee80211_queue_work
	ieee80211_queue_delayed_work


code:
============
ACPI Support
============

.. toctree::
   :maxdepth: 2

   linuxized-acpica
   scan_handlers