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

eeee3149 · Linus Torvalds <[email protected]> · 2018-06-04 12:34:27 -07:00

Pull documentation updates from Jonathan Corbet:
 "There's been a fair amount of work in the docs tree this time around,
  including:

   - Extensive RST conversions and organizational work in the
     memory-management docs thanks to Mike Rapoport.

   - An update of Documentation/features from Andrea Parri and a script
     to keep it updated.

   - Various LICENSES updates from Thomas, along with a script to check
     SPDX tags.

   - Work to fix dangling references to documentation files; this
     involved a fair number of one-liner comment changes outside of
     Documentation/

  ... and the usual list of documentation improvements, typo fixes, etc"

* tag 'docs-4.18' of git://git.lwn.net/linux: (103 commits)
  Documentation: document hung_task_panic kernel parameter
  docs/admin-guide/mm: add high level concepts overview
  docs/vm: move ksm and transhuge from "user" to "internals" section.
  docs: Use the kerneldoc comments for memalloc_no*()
  doc: document scope NOFS, NOIO APIs
  docs: update kernel versions and dates in tables
  docs/vm: transhuge: split userspace bits to admin-guide/mm/transhuge
  docs/vm: transhuge: minor updates
  docs/vm: transhuge: change sections order
  Documentation: arm: clean up Marvell Berlin family info
  Documentation: gpio: driver: Fix a typo and some odd grammar
  docs: ranoops.rst: fix location of ramoops.txt
  scripts/documentation-file-ref-check: rewrite it in perl with auto-fix mode
  docs: uio-howto.rst: use a code block to solve a warning
  mm, THP, doc: Add document for thp_swpout/thp_swpout_fallback
  w1: w1_io.c: fix a kernel-doc warning
  Documentation/process/posting: wrap text at 80 cols
  docs: admin-guide: add cgroup-v2 documentation
  Revert "Documentation/features/vm: Remove arch support status file for 'pte_special'"
  Documentation: refcount-vs-atomic: Update reference to LKMM doc.
  ...

Commit: eeee3149aaa022145b2659e3b0601dc705d69402
Parents: c5e7a7ea · a49d9c0a

Merge commit. Changes below are compared with the first parent: c5e7a7ea.

Changes

163 files changed · +5320 −2705

File	Status	Add	Del	Content
Documentation/00-INDEX	modified	+0	−10	View file
Documentation/ABI/stable/sysfs-devices-node	modified	+1	−1	View file
Documentation/ABI/testing/sysfs-kernel-mm-hugepages	modified	+1	−1	View file
Documentation/ABI/testing/sysfs-kernel-mm-ksm	modified	+1	−1	View file
Documentation/ABI/testing/sysfs-kernel-slab	modified	+2	−2	View file
Documentation/bcache.txt → Documentation/admin-guide/bcache.rst	renamed	+0	−0	View file
Documentation/cgroup-v2.txt → Documentation/admin-guide/cgroup-v2.rst	renamed	+0	−0	View file
Documentation/admin-guide/index.rst	modified	+3	−0	View file
Documentation/admin-guide/kernel-parameters.txt	modified	+85	−75	View file
Documentation/admin-guide/mm/concepts.rst	added	+222	−0	View file
Documentation/vm/hugetlbpage.txt → Documentation/admin-guide/mm/hugetlbpage.rst	renamed	+147	−116	View file
Documentation/vm/idle_page_tracking.txt → Documentation/admin-guide/mm/idle_page_tracking.rst	renamed	+37	−19	View file
Documentation/admin-guide/mm/index.rst	added	+36	−0	View file
Documentation/admin-guide/mm/ksm.rst	added	+189	−0	View file
Documentation/admin-guide/mm/numa_memory_policy.rst	added	+495	−0	View file
Documentation/vm/pagemap.txt → Documentation/admin-guide/mm/pagemap.rst	renamed	+101	−83	View file
Documentation/vm/soft-dirty.txt → Documentation/admin-guide/mm/soft-dirty.rst	renamed	+12	−8	View file
Documentation/admin-guide/mm/transhuge.rst	added	+418	−0	View file
Documentation/vm/userfaultfd.txt → Documentation/admin-guide/mm/userfaultfd.rst	renamed	+39	−27	View file
Documentation/admin-guide/ramoops.rst	modified	+1	−1	View file
Documentation/arm/Marvell/README	modified	+7	−8	View file
Documentation/block/cmdline-partition.txt	modified	+14	−7	View file
Documentation/cachetlb.txt → Documentation/core-api/cachetlb.rst	renamed	+0	−0	View file
Documentation/circular-buffers.txt → Documentation/core-api/circular-buffers.rst	renamed	+0	−0	View file
Documentation/core-api/gfp_mask-from-fs-io.rst	added	+66	−0	View file
Documentation/core-api/index.rst	modified	+3	−0	View file
Documentation/core-api/kernel-api.rst	modified	+30	−30	View file
Documentation/core-api/refcount-vs-atomic.rst	modified	+1	−1	View file
Documentation/crypto/index.rst	modified	+1	−0	View file
Documentation/dev-tools/kasan.rst	modified	+1	−1	View file
Documentation/dev-tools/kselftest.rst	modified	+5	−0	View file
Documentation/clk.txt → Documentation/driver-api/clk.rst	renamed	+0	−0	View file
Documentation/driver-api/device_connection.rst	modified	+1	−1	View file
Documentation/driver-api/gpio/driver.rst	modified	+3	−3	View file
Documentation/driver-api/index.rst	modified	+2	−0	View file
Documentation/driver-api/uio-howto.rst	modified	+2	−1	View file
Documentation/features/lib/strncasecmp/arch-support.txt → Documentation/features/core/cBPF-JIT/arch-support.txt	renamed	+8	−6	View file
Documentation/features/core/BPF-JIT/arch-support.txt → Documentation/features/core/eBPF-JIT/arch-support.txt	renamed	+5	−3	View file
Documentation/features/core/generic-idle-thread/arch-support.txt	modified	+3	−1	View file
Documentation/features/core/jump-labels/arch-support.txt	modified	+2	−0	View file
Documentation/features/core/tracehook/arch-support.txt	modified	+2	−0	View file
Documentation/features/debug/KASAN/arch-support.txt	modified	+3	−1	View file
Documentation/features/debug/gcov-profile-all/arch-support.txt	modified	+2	−0	View file
Documentation/features/debug/kgdb/arch-support.txt	modified	+3	−1	View file
Documentation/features/debug/kprobes-on-ftrace/arch-support.txt	modified	+2	−0	View file
Documentation/features/debug/kprobes/arch-support.txt	modified	+3	−1	View file
Documentation/features/debug/kretprobes/arch-support.txt	modified	+3	−1	View file
Documentation/features/debug/optprobes/arch-support.txt	modified	+3	−1	View file
Documentation/features/debug/stackprotector/arch-support.txt	modified	+2	−0	View file
Documentation/features/debug/uprobes/arch-support.txt	modified	+4	−2	View file
Documentation/features/debug/user-ret-profiler/arch-support.txt	modified	+2	−0	View file
Documentation/features/io/dma-contiguous/arch-support.txt	modified	+3	−1	View file
Documentation/features/io/sg-chain/arch-support.txt	modified	+2	−0	View file
Documentation/features/locking/cmpxchg-local/arch-support.txt	modified	+3	−1	View file
Documentation/features/locking/lockdep/arch-support.txt	modified	+3	−1	View file
Documentation/features/locking/queued-rwlocks/arch-support.txt	modified	+6	−4	View file
Documentation/features/locking/queued-spinlocks/arch-support.txt	modified	+5	−3	View file
Documentation/features/locking/rwsem-optimized/arch-support.txt	modified	+6	−4	View file
Documentation/features/perf/kprobes-event/arch-support.txt	modified	+4	−2	View file
Documentation/features/perf/perf-regs/arch-support.txt	modified	+3	−1	View file
Documentation/features/perf/perf-stackdump/arch-support.txt	modified	+3	−1	View file
Documentation/features/sched/membarrier-sync-core/arch-support.txt	modified	+2	−0	View file
Documentation/features/sched/numa-balancing/arch-support.txt	modified	+4	−2	View file
Documentation/features/scripts/features-refresh.sh	added	+98	−0	View file
Documentation/features/seccomp/seccomp-filter/arch-support.txt	modified	+4	−2	View file
Documentation/features/time/arch-tick-broadcast/arch-support.txt	modified	+3	−1	View file
Documentation/features/time/clockevents/arch-support.txt	modified	+3	−1	View file
Documentation/features/time/context-tracking/arch-support.txt	modified	+2	−0	View file
Documentation/features/time/irq-time-acct/arch-support.txt	modified	+3	−1	View file
Documentation/features/time/modern-timekeeping/arch-support.txt	modified	+2	−0	View file
Documentation/features/time/virt-cpuacct/arch-support.txt	modified	+2	−0	View file
Documentation/features/vm/ELF-ASLR/arch-support.txt	modified	+3	−1	View file
Documentation/features/vm/PG_uncached/arch-support.txt	modified	+2	−0	View file
Documentation/features/vm/THP/arch-support.txt	modified	+2	−0	View file
Documentation/features/vm/TLB/arch-support.txt	modified	+2	−0	View file
Documentation/features/vm/huge-vmap/arch-support.txt	modified	+2	−0	View file
Documentation/features/vm/ioremap_prot/arch-support.txt	modified	+2	−0	View file
Documentation/features/vm/numa-memblock/arch-support.txt	modified	+3	−1	View file
Documentation/features/vm/pte_special/arch-support.txt	modified	+2	−0	View file
Documentation/filesystems/proc.txt	modified	+5	−3	View file
Documentation/filesystems/tmpfs.txt	modified	+3	−2	View file
Documentation/index.rst	modified	+2	−1	View file
Documentation/ioctl/botching-up-ioctls.txt	modified	+3	−1	View file
Documentation/memory-barriers.txt	modified	+2	−2	View file
Documentation/process/2.Process.rst	modified	+38	−34	View file
Documentation/process/5.Posting.rst	modified	+8	−8	View file
Documentation/process/index.rst	modified	+1	−0	View file
Documentation/process/maintainer-pgp-guide.rst	modified	+37	−2	View file
Documentation/process/submitting-patches.rst	modified	+1	−1	View file
Documentation/security/index.rst	modified	+2	−0	View file
Documentation/sound/alsa-configuration.rst	modified	+2	−2	View file
Documentation/sound/soc/codec.rst	modified	+1	−1	View file
Documentation/sound/soc/platform.rst	modified	+1	−1	View file
Documentation/sysctl/vm.txt	modified	+3	−3	View file
Documentation/trace/coresight.txt	modified	+75	−28	View file
Documentation/trace/ftrace-uses.rst	modified	+2	−2	View file
Documentation/trace/ftrace.rst	modified	+6	−1	View file
Documentation/translations/ko_KR/memory-barriers.txt	modified	+2	−2	View file
Documentation/vfio.txt	modified	+2	−3	View file
Documentation/vm/00-INDEX	modified	+23	−35	View file
Documentation/vm/active_mm.txt → Documentation/vm/active_mm.rst	renamed	+91	−83	View file
Documentation/vm/balance → Documentation/vm/balance.rst	renamed	+11	−4	View file
Documentation/vm/cleancache.txt → Documentation/vm/cleancache.rst	renamed	+62	−43	View file
Documentation/vm/conf.py	added	+10	−0	View file
Documentation/vm/frontswap.txt → Documentation/vm/frontswap.rst	renamed	+37	−22	View file
Documentation/vm/highmem.txt → Documentation/vm/highmem.rst	renamed	+36	−51	View file
Documentation/vm/hmm.txt → Documentation/vm/hmm.rst	renamed	+34	−44	View file
Documentation/vm/hugetlbfs_reserv.txt → Documentation/vm/hugetlbfs_reserv.rst	renamed	+143	−77	View file
Documentation/vm/hwpoison.txt → Documentation/vm/hwpoison.rst	renamed	+70	−71	View file
Documentation/vm/index.rst	added	+50	−0	View file
Documentation/vm/ksm.rst	added	+87	−0	View file
Documentation/vm/ksm.txt	deleted	+0	−178	View before deletion
Documentation/vm/mmu_notifier.txt → Documentation/vm/mmu_notifier.rst	renamed	+57	−51	View file
Documentation/vm/numa → Documentation/vm/numa.rst	renamed	+5	−1	View file
Documentation/vm/numa_memory_policy.txt	deleted	+0	−452	View before deletion
Documentation/vm/overcommit-accounting	deleted	+0	−80	View before deletion
Documentation/vm/overcommit-accounting.rst	added	+87	−0	View file
Documentation/vm/page_frags → Documentation/vm/page_frags.rst	renamed	+4	−1	View file
Documentation/vm/page_migration → Documentation/vm/page_migration.rst	renamed	+77	−72	View file
Documentation/vm/page_owner.txt → Documentation/vm/page_owner.rst	renamed	+21	−13	View file
Documentation/vm/remap_file_pages.txt → Documentation/vm/remap_file_pages.rst	renamed	+6	−0	View file
Documentation/vm/slub.txt → Documentation/vm/slub.rst	renamed	+188	−169	View file
Documentation/vm/split_page_table_lock → Documentation/vm/split_page_table_lock.rst	renamed	+9	−3	View file
Documentation/vm/swap_numa.txt → Documentation/vm/swap_numa.rst	renamed	+33	−22	View file
Documentation/vm/transhuge.rst	added	+197	−0	View file
Documentation/vm/transhuge.txt	deleted	+0	−527	View before deletion
Documentation/vm/unevictable-lru.txt → Documentation/vm/unevictable-lru.rst	renamed	+49	−68	View file
Documentation/vm/z3fold.txt → Documentation/vm/z3fold.rst	renamed	+5	−1	View file
Documentation/vm/zsmalloc.txt → Documentation/vm/zsmalloc.rst	renamed	+36	−24	View file
Documentation/vm/zswap.txt → Documentation/vm/zswap.rst	renamed	+42	−29	View file
LICENSES/exceptions/Linux-syscall-note	modified	+1	−1	View file
LICENSES/other/Apache-2.0	added	+183	−0	View file
LICENSES/other/CC-BY-SA-4.0	added	+397	−0	View file
LICENSES/other/CDDL-1.0	added	+364	−0	View file
LICENSES/other/Linux-OpenIB	added	+26	−0	View file
LICENSES/other/X11	added	+37	−0	View file
LICENSES/preferred/GPL-2.0	modified	+6	−0	View file
MAINTAINERS	modified	+1	−1	View file
arch/alpha/Kconfig	modified	+1	−1	View file
arch/ia64/Kconfig	modified	+1	−1	View file
arch/mips/Kconfig	modified	+1	−1	View file
arch/powerpc/Kconfig	modified	+1	−1	View file
drivers/w1/w1_io.c	modified	+1	−0	View file
fs/Kconfig	modified	+1	−1	View file
fs/dax.c	modified	+1	−1	View file
fs/proc/task_mmu.c	modified	+2	−2	View file
include/linux/hmm.h	modified	+1	−1	View file
include/linux/memremap.h	modified	+2	−2	View file
include/linux/mmu_notifier.h	modified	+1	−1	View file
include/linux/sched/mm.h	modified	+40	−2	View file
include/linux/swap.h	modified	+1	−1	View file
mm/Kconfig	modified	+4	−3	View file
mm/cleancache.c	modified	+1	−1	View file
mm/frontswap.c	modified	+1	−1	View file
mm/hmm.c	modified	+1	−1	View file
mm/huge_memory.c	modified	+2	−2	View file
mm/hugetlb.c	modified	+2	−2	View file
mm/ksm.c	modified	+20	−3	View file
mm/mmap.c	modified	+1	−1	View file
mm/rmap.c	modified	+3	−3	View file
mm/util.c	modified	+1	−1	View file
scripts/documentation-file-ref-check	modified	+113	−12	View file
scripts/spdxcheck.py	added	+284	−0	View file

Only the first 600 diff lines are shown. Download the complete patch.

Documentation/00-INDEX

View file

diff --git a/Documentation/00-INDEX b/Documentation/00-INDEX
index 708dc4c..2754fe8 100644
--- a/Documentation/00-INDEX
+++ b/Documentation/00-INDEX
@@ -64,8 +64,6 @@ auxdisplay/
 	- misc. LCD driver documentation (cfag12864b, ks0108).
 backlight/
 	- directory with info on controlling backlights in flat panel displays
-bcache.txt
-	- Block-layer cache on fast SSDs to improve slow (raid) I/O performance.
 block/
 	- info on the Block I/O (BIO) layer.
 blockdev/
@@ -78,18 +76,10 @@ bus-devices/
 	- directory with info on TI GPMC (General Purpose Memory Controller)
 bus-virt-phys-mapping.txt
 	- how to access I/O mapped memory from within device drivers.
-cachetlb.txt
-	- describes the cache/TLB flushing interfaces Linux uses.
 cdrom/
 	- directory with information on the CD-ROM drivers that Linux has.
 cgroup-v1/
 	- cgroups v1 features, including cpusets and memory controller.
-cgroup-v2.txt
-	- cgroups v2 features, including cpusets and memory controller.
-circular-buffers.txt
-	- how to make use of the existing circular buffer infrastructure
-clk.txt
-	- info on the common clock framework
 cma/
 	- Continuous Memory Area (CMA) debugfs interface.
 conf.py

Documentation/ABI/stable/sysfs-devices-node

View file

diff --git a/Documentation/ABI/stable/sysfs-devices-node b/Documentation/ABI/stable/sysfs-devices-node
index 5b2d0f0..3e90e1f 100644
--- a/Documentation/ABI/stable/sysfs-devices-node
+++ b/Documentation/ABI/stable/sysfs-devices-node
@@ -90,4 +90,4 @@ Date:		December 2009
 Contact:	Lee Schermerhorn <[email protected]>
 Description:
 		The node's huge page size control/query attributes.
-		See Documentation/vm/hugetlbpage.txt
\ No newline at end of file
+		See Documentation/admin-guide/mm/hugetlbpage.rst
\ No newline at end of file

Documentation/ABI/testing/sysfs-kernel-mm-hugepages

View file

diff --git a/Documentation/ABI/testing/sysfs-kernel-mm-hugepages b/Documentation/ABI/testing/sysfs-kernel-mm-hugepages
index e21c005..fdaa216 100644
--- a/Documentation/ABI/testing/sysfs-kernel-mm-hugepages
+++ b/Documentation/ABI/testing/sysfs-kernel-mm-hugepages
@@ -12,4 +12,4 @@ Description:
 			free_hugepages
 			surplus_hugepages
 			resv_hugepages
-		See Documentation/vm/hugetlbpage.txt for details.
+		See Documentation/admin-guide/mm/hugetlbpage.rst for details.

Documentation/ABI/testing/sysfs-kernel-mm-ksm

View file

diff --git a/Documentation/ABI/testing/sysfs-kernel-mm-ksm b/Documentation/ABI/testing/sysfs-kernel-mm-ksm
index 73e653e..dfc1324 100644
--- a/Documentation/ABI/testing/sysfs-kernel-mm-ksm
+++ b/Documentation/ABI/testing/sysfs-kernel-mm-ksm
@@ -40,7 +40,7 @@ Description:	Kernel Samepage Merging daemon sysfs interface
 		sleep_millisecs: how many milliseconds ksm should sleep between
 		scans.
 
-		See Documentation/vm/ksm.txt for more information.
+		See Documentation/vm/ksm.rst for more information.
 
 What:		/sys/kernel/mm/ksm/merge_across_nodes
 Date:		January 2013

Documentation/ABI/testing/sysfs-kernel-slab

View file

diff --git a/Documentation/ABI/testing/sysfs-kernel-slab b/Documentation/ABI/testing/sysfs-kernel-slab
index 2cc0a72..29601d9 100644
--- a/Documentation/ABI/testing/sysfs-kernel-slab
+++ b/Documentation/ABI/testing/sysfs-kernel-slab
@@ -37,7 +37,7 @@ Description:
 		The alloc_calls file is read-only and lists the kernel code
 		locations from which allocations for this cache were performed.
 		The alloc_calls file only contains information if debugging is
-		enabled for that cache (see Documentation/vm/slub.txt).
+		enabled for that cache (see Documentation/vm/slub.rst).
 
 What:		/sys/kernel/slab/cache/alloc_fastpath
 Date:		February 2008
@@ -219,7 +219,7 @@ Contact:	Pekka Enberg <[email protected]>,
 Description:
 		The free_calls file is read-only and lists the locations of
 		object frees if slab debugging is enabled (see
-		Documentation/vm/slub.txt).
+		Documentation/vm/slub.rst).
 
 What:		/sys/kernel/slab/cache/free_fastpath
 Date:		February 2008

Documentation/admin-guide/bcache.rst

View file

diff --git a/Documentation/bcache.txt b/Documentation/admin-guide/bcache.rst
similarity index 100%
rename from Documentation/bcache.txt
rename to Documentation/admin-guide/bcache.rst

Documentation/admin-guide/cgroup-v2.rst

View file

diff --git a/Documentation/cgroup-v2.txt b/Documentation/admin-guide/cgroup-v2.rst
similarity index 100%
rename from Documentation/cgroup-v2.txt
rename to Documentation/admin-guide/cgroup-v2.rst

Documentation/admin-guide/index.rst

View file

diff --git a/Documentation/admin-guide/index.rst b/Documentation/admin-guide/index.rst
index 5bb9161..48d70af 100644
--- a/Documentation/admin-guide/index.rst
+++ b/Documentation/admin-guide/index.rst
@@ -48,6 +48,7 @@ configure specific aspects of kernel behavior to your liking.
    :maxdepth: 1
 
    initrd
+   cgroup-v2
    serial-console
    braille-console
    parport
@@ -60,9 +61,11 @@ configure specific aspects of kernel behavior to your liking.
    mono
    java
    ras
+   bcache
    pm/index
    thunderbolt
    LSM/index
+   mm/index
 
 .. only::  subproject and html
 

Documentation/admin-guide/kernel-parameters.txt

View file

diff --git a/Documentation/admin-guide/kernel-parameters.txt b/Documentation/admin-guide/kernel-parameters.txt
index cc0ac03..b0a42f3 100644
--- a/Documentation/admin-guide/kernel-parameters.txt
+++ b/Documentation/admin-guide/kernel-parameters.txt
@@ -106,11 +106,11 @@
 			use by PCI
 			Format: <irq>,<irq>...
 
-	acpi_mask_gpe=  [HW,ACPI]
+	acpi_mask_gpe=	[HW,ACPI]
 			Due to the existence of _Lxx/_Exx, some GPEs triggered
 			by unsupported hardware/firmware features can result in
-                        GPE floodings that cannot be automatically disabled by
-                        the GPE dispatcher.
+			GPE floodings that cannot be automatically disabled by
+			the GPE dispatcher.
 			This facility can be used to prevent such uncontrolled
 			GPE floodings.
 			Format: <int>
@@ -472,10 +472,10 @@
 			for platform specific values (SB1, Loongson3 and
 			others).
 
-	ccw_timeout_log [S390]
+	ccw_timeout_log	[S390]
 			See Documentation/s390/CommonIO for details.
 
-	cgroup_disable= [KNL] Disable a particular controller
+	cgroup_disable=	[KNL] Disable a particular controller
 			Format: {name of the controller(s) to disable}
 			The effects of cgroup_disable=foo are:
 			- foo isn't auto-mounted if you mount all cgroups in
@@ -518,7 +518,7 @@
 			those clocks in any way. This parameter is useful for
 			debug and development, but should not be needed on a
 			platform with proper driver support.  For more
-			information, see Documentation/clk.txt.
+			information, see Documentation/driver-api/clk.rst.
 
 	clock=		[BUGS=X86-32, HW] gettimeofday clocksource override.
 			[Deprecated]
@@ -641,8 +641,8 @@
 		hvc<n>	Use the hypervisor console device <n>. This is for
 			both Xen and PowerPC hypervisors.
 
-                If the device connected to the port is not a TTY but a braille
-                device, prepend "brl," before the device type, for instance
+		If the device connected to the port is not a TTY but a braille
+		device, prepend "brl," before the device type, for instance
 			console=brl,ttyS0
 		For now, only VisioBraille is supported.
 
@@ -662,7 +662,7 @@
 
 	consoleblank=	[KNL] The console blank (screen saver) timeout in
 			seconds. A value of 0 disables the blank timer.
-                       Defaults to 0.
+			Defaults to 0.
 
 	coredump_filter=
 			[KNL] Change the default value for
@@ -730,7 +730,7 @@
 			or memory reserved is below 4G.
 
 	cryptomgr.notests
-                        [KNL] Disable crypto self-tests
+			[KNL] Disable crypto self-tests
 
 	cs89x0_dma=	[HW,NET]
 			Format: <dma>
@@ -746,7 +746,7 @@
 			Format: <port#>,<type>
 			See also Documentation/input/devices/joystick-parport.rst
 
-	ddebug_query=   [KNL,DYNAMIC_DEBUG] Enable debug messages at early boot
+	ddebug_query=	[KNL,DYNAMIC_DEBUG] Enable debug messages at early boot
 			time. See
 			Documentation/admin-guide/dynamic-debug-howto.rst for
 			details.  Deprecated, see dyndbg.
@@ -833,7 +833,7 @@
 			causing system reset or hang due to sending
 			INIT from AP to BSP.
 
-	disable_ddw     [PPC/PSERIES]
+	disable_ddw	[PPC/PSERIES]
 			Disable Dynamic DMA Window support. Use this if
 			to workaround buggy firmware.
 
@@ -1188,7 +1188,7 @@
 			parameter will force ia64_sal_cache_flush to call
 			ia64_pal_cache_flush instead of SAL_CACHE_FLUSH.
 
-	forcepae [X86-32]
+	forcepae	[X86-32]
 			Forcefully enable Physical Address Extension (PAE).
 			Many Pentium M systems disable PAE but may have a
 			functionally usable PAE implementation.
@@ -1247,7 +1247,7 @@
 
 	gamma=		[HW,DRM]
 
-	gart_fix_e820=  [X86_64] disable the fix e820 for K8 GART
+	gart_fix_e820=	[X86_64] disable the fix e820 for K8 GART
 			Format: off | on
 			default: on
 
@@ -1341,23 +1341,32 @@
 			x86-64 are 2M (when the CPU supports "pse") and 1G
 			(when the CPU supports the "pdpe1gb" cpuinfo flag).
 
-	hvc_iucv=	[S390] Number of z/VM IUCV hypervisor console (HVC)
-			       terminal devices. Valid values: 0..8
-	hvc_iucv_allow=	[S390] Comma-separated list of z/VM user IDs.
-			       If specified, z/VM IUCV HVC accepts connections
-			       from listed z/VM user IDs only.
+	hung_task_panic=
+			[KNL] Should the hung task detector generate panics.
+			Format: <integer>
 
+			A nonzero value instructs the kernel to panic when a
+			hung task is detected. The default value is controlled
+			by the CONFIG_BOOTPARAM_HUNG_TASK_PANIC build-time
+			option. The value selected by this boot parameter can
+			be changed later by the kernel.hung_task_panic sysctl.
+
+	hvc_iucv=	[S390]	Number of z/VM IUCV hypervisor console (HVC)
+				terminal devices. Valid values: 0..8
+	hvc_iucv_allow=	[S390]	Comma-separated list of z/VM user IDs.
+				If specified, z/VM IUCV HVC accepts connections
+				from listed z/VM user IDs only.
 	keep_bootcon	[KNL]
 			Do not unregister boot console at start. This is only
 			useful for debugging when something happens in the window
 			between unregistering the boot console and initializing
 			the real console.
 
-	i2c_bus=	[HW] Override the default board specific I2C bus speed
-			     or register an additional I2C bus that is not
-			     registered from board initialization code.
-			     Format:
-			     <bus_id>,<clkrate>
+	i2c_bus=	[HW]	Override the default board specific I2C bus speed
+				or register an additional I2C bus that is not
+				registered from board initialization code.
+				Format:
+				<bus_id>,<clkrate>
 
 	i8042.debug	[HW] Toggle i8042 debug mode
 	i8042.unmask_kbd_data
@@ -1386,7 +1395,7 @@
 			Default: only on s2r transitions on x86; most other
 			architectures force reset to be always executed
 	i8042.unlock	[HW] Unlock (ignore) the keylock
-	i8042.kbdreset  [HW] Reset device connected to KBD port
+	i8042.kbdreset	[HW] Reset device connected to KBD port
 
 	i810=		[HW,DRM]
 
@@ -1548,13 +1557,13 @@
 			programs exec'd, files mmap'd for exec, and all files
 			opened for read by uid=0.
 
-	ima_template=   [IMA]
+	ima_template=	[IMA]
 			Select one of defined IMA measurements template formats.
 			Formats: { "ima" | "ima-ng" | "ima-sig" }
 			Default: "ima-ng"
 
 	ima_template_fmt=
-	                [IMA] Define a custom template format.
+			[IMA] Define a custom template format.
 			Format: { "field1|...|fieldN" }
 
 	ima.ahash_minsize= [IMA] Minimum file size for asynchronous hash usage
@@ -1597,7 +1606,7 @@
 	inport.irq=	[HW] Inport (ATI XL and Microsoft) busmouse driver
 			Format: <irq>
 
-	int_pln_enable  [x86] Enable power limit notification interrupt
+	int_pln_enable	[x86] Enable power limit notification interrupt
 
 	integrity_audit=[IMA]
 			Format: { "0" | "1" }
@@ -1650,39 +1659,39 @@
 			0	disables intel_idle and fall back on acpi_idle.
 			1 to 9	specify maximum depth of C-state.
 
-	intel_pstate=  [X86]
-		       disable
-		         Do not enable intel_pstate as the default
-		         scaling driver for the supported processors
-		       passive
-			 Use intel_pstate as a scaling driver, but configure it
-			 to work with generic cpufreq governors (instead of
-			 enabling its internal governor).  This mode cannot be
-			 used along with the hardware-managed P-states (HWP)
-			 feature.
-		       force
-			 Enable intel_pstate on systems that prohibit it by default
-			 in favor of acpi-cpufreq. Forcing the intel_pstate driver
-			 instead of acpi-cpufreq may disable platform features, such
-			 as thermal controls and power capping, that rely on ACPI
-			 P-States information being indicated to OSPM and therefore
-			 should be used with caution. This option does not work with
-			 processors that aren't supported by the intel_pstate driver
-			 or on platforms that use pcc-cpufreq instead of acpi-cpufreq.
-		       no_hwp
-		         Do not enable hardware P state control (HWP)
-			 if available.
-		hwp_only
-			Only load intel_pstate on systems which support
-			hardware P state control (HWP) if available.
-		support_acpi_ppc
-			Enforce ACPI _PPC performance limits. If the Fixed ACPI
-			Description Table, specifies preferred power management
-			profile as "Enterprise Server" or "Performance Server",
-			then this feature is turned on by default.
-		per_cpu_perf_limits
-			Allow per-logical-CPU P-State performance control limits using
-			cpufreq sysfs interface
+	intel_pstate=	[X86]
+			disable
+			  Do not enable intel_pstate as the default
+			  scaling driver for the supported processors
+			passive
+			  Use intel_pstate as a scaling driver, but configure it
+			  to work with generic cpufreq governors (instead of
+			  enabling its internal governor).  This mode cannot be
+			  used along with the hardware-managed P-states (HWP)
+			  feature.
+			force
+			  Enable intel_pstate on systems that prohibit it by default
+			  in favor of acpi-cpufreq. Forcing the intel_pstate driver
+			  instead of acpi-cpufreq may disable platform features, such
+			  as thermal controls and power capping, that rely on ACPI
+			  P-States information being indicated to OSPM and therefore
+			  should be used with caution. This option does not work with
+			  processors that aren't supported by the intel_pstate driver
+			  or on platforms that use pcc-cpufreq instead of acpi-cpufreq.
+			no_hwp
+			  Do not enable hardware P state control (HWP)
+			  if available.
+			hwp_only
+			  Only load intel_pstate on systems which support
+			  hardware P state control (HWP) if available.
+			support_acpi_ppc
+			  Enforce ACPI _PPC performance limits. If the Fixed ACPI
+			  Description Table, specifies preferred power management
+			  profile as "Enterprise Server" or "Performance Server",
+			  then this feature is turned on by default.
+			per_cpu_perf_limits
+			  Allow per-logical-CPU P-State performance control limits using
+			  cpufreq sysfs interface
 
 	intremap=	[X86-64, Intel-IOMMU]
 			on	enable Interrupt Remapping (default)
@@ -2026,7 +2035,7 @@
 			* [no]ncqtrim: Turn off queued DSM TRIM.
 
 			* nohrst, nosrst, norst: suppress hard, soft
-                          and both resets.
+			  and both resets.
 
 			* rstonce: only attempt one reset during
 			  hot-unplug link recovery
@@ -2214,7 +2223,7 @@
 			[KNL,SH] Allow user to override the default size for
 			per-device physically contiguous DMA buffers.
 
-        memhp_default_state=online/offline
+	memhp_default_state=online/offline
 			[KNL] Set the initial state for the memory hotplug
 			onlining policy. If not specified, the default value is
 			set according to the
@@ -2764,7 +2773,7 @@
 			[X86,PV_OPS] Disable paravirtualized VMware scheduler
 			clock and use the default one.
 
-	no-steal-acc    [X86,KVM] Disable paravirtualized steal time accounting.
+	no-steal-acc	[X86,KVM] Disable paravirtualized steal time accounting.
 			steal time is computed, but won't influence scheduler
 			behaviour
 
@@ -2825,7 +2834,7 @@
 	notsc		[BUGS=X86-32] Disable Time Stamp Counter
 
 	nowatchdog	[KNL] Disable both lockup detectors, i.e.
-                        soft-lockup and NMI watchdog (hard-lockup).
+			soft-lockup and NMI watchdog (hard-lockup).
 
 	nowb		[ARM]
 
@@ -2845,7 +2854,7 @@
 			If the dependencies are under your control, you can
 			turn on cpu0_hotplug.
 
-	nps_mtm_hs_ctr= [KNL,ARC]
+	nps_mtm_hs_ctr=	[KNL,ARC]
 			This parameter sets the maximum duration, in
 			cycles, each HW thread of the CTOP can run
 			without interruptions, before HW switches it.
@@ -2986,7 +2995,7 @@
 
 	pci=option[,option...]	[PCI] various PCI subsystem options:
 		earlydump	[X86] dump PCI config space before the kernel
-			        changes anything
+				changes anything
 		off		[X86] don't probe for the PCI bus
 		bios		[X86-32] force use of PCI BIOS, don't access
 				the hardware directly. Use this if your machine
@@ -3074,7 +3083,7 @@
 				is enabled by default.  If you need to use this,
 				please report a bug.
 		nocrs		[X86] Ignore PCI host bridge windows from ACPI.
-			        If you need to use this, please report a bug.
+				If you need to use this, please report a bug.
 		routeirq	Do IRQ routing for all PCI devices.
 				This is normally done in pci_enable_device(),
 				so this option is a temporary workaround
@@ -3917,7 +3926,7 @@
 			cache (risks via metadata attacks are mostly
 			unchanged). Debug options disable merging on their
 			own.
-			For more information see Documentation/vm/slub.txt.
+			For more information see Documentation/vm/slub.rst.
 
 	slab_max_order=	[MM, SLAB]
 			Determines the maximum allowed order for slabs.
@@ -3931,7 +3940,7 @@
 			slub_debug can create guard zones around objects and
 			may poison objects when not in use. Also tracks the
 			last alloc / free. For more information see
-			Documentation/vm/slub.txt.
+			Documentation/vm/slub.rst.
 
 	slub_memcg_sysfs=	[MM, SLUB]
 			Determines whether to enable sysfs directories for
@@ -3945,7 +3954,7 @@
 			Determines the maximum allowed order for slabs.
 			A high setting may cause OOMs due to memory
 			fragmentation. For more information see
-			Documentation/vm/slub.txt.
+			Documentation/vm/slub.rst.
 
 	slub_min_objects=	[MM, SLUB]
 			The minimum number of objects per slab. SLUB will
@@ -3954,12 +3963,12 @@
 			the number of objects indicated. The higher the number
 			of objects the smaller the overhead of tracking slabs
 			and the less frequently locks need to be acquired.
-			For more information see Documentation/vm/slub.txt.
+			For more information see Documentation/vm/slub.rst.
 
 	slub_min_order=	[MM, SLUB]
 			Determines the minimum page order for slabs. Must be
 			lower than slub_max_order.
-			For more information see Documentation/vm/slub.txt.
+			For more information see Documentation/vm/slub.rst.
 
 	slub_nomerge	[MM, SLUB]
 			Same with slab_nomerge. This is supported for legacy.
@@ -4357,7 +4366,8 @@
 			Format: [always|madvise|never]
 			Can be used to control the default behavior of the system
 			with respect to transparent hugepages.
-			See Documentation/vm/transhuge.txt for more details.
+			See Documentation/admin-guide/mm/transhuge.rst
+			for more details.
 
 	tsc=		Disable clocksource stability checks for TSC.
 			Format: <string>
@@ -4435,7 +4445,7 @@
 
 	usbcore.initial_descriptor_timeout=
 			[USB] Specifies timeout for the initial 64-byte
-                        USB_REQ_GET_DESCRIPTOR request in milliseconds
+			USB_REQ_GET_DESCRIPTOR request in milliseconds
 			(default 5000 = 5.0 seconds).
 
 	usbcore.nousb	[USB] Disable the USB subsystem

Documentation/admin-guide/mm/concepts.rst

View file

diff --git a/Documentation/admin-guide/mm/concepts.rst b/Documentation/admin-guide/mm/concepts.rst
new file mode 100644
index 0000000..291699c
--- /dev/null
+++ b/Documentation/admin-guide/mm/concepts.rst
@@ -0,0 +1,222 @@
+.. _mm_concepts:
+
+=================
+Concepts overview
+=================
+
+The memory management in Linux is complex system that evolved over the
+years and included more and more functionality to support variety of
+systems from MMU-less microcontrollers to supercomputers. The memory
+management for systems without MMU is called ``nommu`` and it
+definitely deserves a dedicated document, which hopefully will be
+eventually written. Yet, although some of the concepts are the same,
+here we assume that MMU is available and CPU can translate a virtual
+address to a physical address.
+
+.. contents:: :local:
+
+Virtual Memory Primer
+=====================
+
+The physical memory in a computer system is a limited resource and
+even for systems that support memory hotplug there is a hard limit on
+the amount of memory that can be installed. The physical memory is not
+necessary contiguous, it might be accessible as a set of distinct
+address ranges. Besides, different CPU architectures, and even
+different implementations of the same architecture have different view
+how these address ranges defined.
+
+All this makes dealing directly with physical memory quite complex and
+to avoid this complexity a concept of virtual memory was developed.
+
+The virtual memory abstracts the details of physical memory from the
+application software, allows to keep only needed information in the
+physical memory (demand paging) and provides a mechanism for the
+protection and controlled sharing of data between processes.
+
+With virtual memory, each and every memory access uses a virtual
+address. When the CPU decodes the an instruction that reads (or
+writes) from (or to) the system memory, it translates the `virtual`
+address encoded in that instruction to a `physical` address that the
+memory controller can understand.
+
+The physical system memory is divided into page frames, or pages. The
+size of each page is architecture specific. Some architectures allow
+selection of the page size from several supported values; this
+selection is performed at the kernel build time by setting an
+appropriate kernel configuration option.
+
+Each physical memory page can be mapped as one or more virtual
+pages. These mappings are described by page tables that allow
+translation from virtual address used by programs to real address in
+the physical memory. The page tables organized hierarchically.
+
+The tables at the lowest level of the hierarchy contain physical
+addresses of actual pages used by the software. The tables at higher
+levels contain physical addresses of the pages belonging to the lower
+levels. The pointer to the top level page table resides in a
+register. When the CPU performs the address translation, it uses this
+register to access the top level page table. The high bits of the
+virtual address are used to index an entry in the top level page
+table. That entry is then used to access the next level in the
+hierarchy with the next bits of the virtual address as the index to
+that level page table. The lowest bits in the virtual address define
+the offset inside the actual page.
+
+Huge Pages
+==========
+
+The address translation requires several memory accesses and memory
+accesses are slow relatively to CPU speed. To avoid spending precious
+processor cycles on the address translation, CPUs maintain a cache of
+such translations called Translation Lookaside Buffer (or
+TLB). Usually TLB is pretty scarce resource and applications with
+large memory working set will experience performance hit because of
+TLB misses.
+
+Many modern CPU architectures allow mapping of the memory pages
+directly by the higher levels in the page table. For instance, on x86,
+it is possible to map 2M and even 1G pages using entries in the second
+and the third level page tables. In Linux such pages are called
+`huge`. Usage of huge pages significantly reduces pressure on TLB,
+improves TLB hit-rate and thus improves overall system performance.
+
+There are two mechanisms in Linux that enable mapping of the physical
+memory with the huge pages. The first one is `HugeTLB filesystem`, or
+hugetlbfs. It is a pseudo filesystem that uses RAM as its backing
+store. For the files created in this filesystem the data resides in
+the memory and mapped using huge pages. The hugetlbfs is described at
+:ref:`Documentation/admin-guide/mm/hugetlbpage.rst <hugetlbpage>`.
+
+Another, more recent, mechanism that enables use of the huge pages is
+called `Transparent HugePages`, or THP. Unlike the hugetlbfs that
+requires users and/or system administrators to configure what parts of