Merge tag 'docs-4.19' of git://git.lwn.net/linux

.. _readme:

Linux kernel release 4.x <http://kernel.org/>

=============================================

			This parameter controls whether the Speculative Store

			Bypass optimization is used.

			On x86 the options are:

			on      - Unconditionally disable Speculative Store Bypass

			off     - Unconditionally enable Speculative Store Bypass

			auto    - Kernel detects whether the CPU model contains an

			seccomp - Same as "prctl" above, but all seccomp threads

				  will disable SSB unless they explicitly opt out.

			Not specifying this option is equivalent to

			spec_store_bypass_disable=auto.

			Default mitigations:

			X86:	If CONFIG_SECCOMP=y "seccomp", otherwise "prctl"

			On powerpc the options are:

			on,auto - On Power8 and Power9 insert a store-forwarding

				  barrier on kernel entry and exit. On Power7

				  perform a software flush on kernel entry and

				  exit.

			off	- No action.

			Not specifying this option is equivalent to

			spec_store_bypass_disable=auto.

	spia_io_base=	[HW,MTD]

	spia_fio_base=

	spia_pedr=

Console Drivers

===============

The linux kernel has 2 general types of console drivers.  The first type is

The Linux kernel has 2 general types of console drivers.  The first type is

assigned by the kernel to all the virtual consoles during the boot process.

This type will be called 'system driver', and only one system driver is allowed

to exist. The system driver is persistent and it can never be unloaded, though

occupied by the system driver. In the same token, if the modular driver is

released by the console, the system driver will take over.

Modular drivers, from the programmer's point of view, has to call:

Modular drivers, from the programmer's point of view, have to call:

	 do_take_over_console() - load and bind driver to console layer

	 give_up_console() - unload driver, it will only work if driver is fully unbond

	 give_up_console() - unload driver; it will only work if driver

			     is fully unbound

In newer kernels, the following are also available:

	cat /sys/class/vtconsole/vtcon0/name

	(S) VGA+

	    '(S)' stands for a (S)ystem driver, ie, it cannot be directly

	    '(S)' stands for a (S)ystem driver, i.e., it cannot be directly

	    commanded to bind or unbind

	    'VGA+' is the name of the driver

for rebooting the kernel. For regular users who may want to switch from

framebuffer console to VGA console and vice versa, this feature also makes

this possible. (NOTE NOTE NOTE: Please read fbcon.txt under Documentation/fb

for more details).

for more details.)

Notes for developers:

=====================

console drivers must follow these guidelines:

1. All drivers, except system drivers, must call either do_register_con_driver()

   or do_take_over_console(). do_register_con_driver() will just add the driver to

   the console's internal list. It won't take over the

   or do_take_over_console(). do_register_con_driver() will just add the driver

   to the console's internal list. It won't take over the

   console. do_take_over_console(), as it name implies, will also take over (or

   bind to) the console.

===========================

Boot time memory management

===========================

Early system initialization cannot use "normal" memory management

simply because it is not set up yet. But there is still need to

allocate memory for various data structures, for instance for the

physical page allocator. To address this, a specialized allocator

called the :ref:`Boot Memory Allocator <bootmem>`, or bootmem, was

introduced. Several years later PowerPC developers added a "Logical

Memory Blocks" allocator, which was later adopted by other

architectures and renamed to :ref:`memblock <memblock>`. There is also

a compatibility layer called `nobootmem` that translates bootmem

allocation interfaces to memblock calls.

The selection of the early allocator is done using

``CONFIG_NO_BOOTMEM`` and ``CONFIG_HAVE_MEMBLOCK`` kernel

configuration options. These options are enabled or disabled

statically by the architectures' Kconfig files.

* Architectures that rely only on bootmem select

  ``CONFIG_NO_BOOTMEM=n && CONFIG_HAVE_MEMBLOCK=n``.

* The users of memblock with the nobootmem compatibility layer set

  ``CONFIG_NO_BOOTMEM=y && CONFIG_HAVE_MEMBLOCK=y``.

* And for those that use both memblock and bootmem the configuration

  includes ``CONFIG_NO_BOOTMEM=n && CONFIG_HAVE_MEMBLOCK=y``.

Whichever allocator is used, it is the responsibility of the

architecture specific initialization to set it up in

:c:func:`setup_arch` and tear it down in :c:func:`mem_init` functions.

Once the early memory management is available it offers a variety of

functions and macros for memory allocations. The allocation request

may be directed to the first (and probably the only) node or to a

particular node in a NUMA system. There are API variants that panic

when an allocation fails and those that don't. And more recent and

advanced memblock even allows controlling its own behaviour.

.. _bootmem:

Bootmem

=======

(mostly stolen from Mel Gorman's "Understanding the Linux Virtual

Memory Manager" `book`_)

.. _book: https://www.kernel.org/doc/gorman/

.. kernel-doc:: mm/bootmem.c

   :doc: bootmem overview

.. _memblock:

Memblock

========

.. kernel-doc:: mm/memblock.c

   :doc: memblock overview

Functions and structures

========================

Common API

----------

The functions that are described in this section are available

regardless of what early memory manager is enabled.

.. kernel-doc:: mm/nobootmem.c

Bootmem specific API

--------------------

These interfaces available only with bootmem, i.e when ``CONFIG_NO_BOOTMEM=n``

.. kernel-doc:: include/linux/bootmem.h

.. kernel-doc:: mm/bootmem.c

   :nodocs:

Memblock specific API

---------------------

Here is the description of memblock data structures, functions and

macros. Some of them are actually internal, but since they are

documented it would be silly to omit them. Besides, reading the

descriptions for the internal functions can help to understand what

really happens under the hood.

.. kernel-doc:: include/linux/memblock.h

.. kernel-doc:: mm/memblock.c

   :nodocs:

========================

.. kernel-doc:: include/linux/idr.h

   :functions:

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

   :functions: