* [PATCH v3 1/7] docs: dt: convert booting-without-of.txt to ReST format
[not found] <cover.1592918949.git.mchehab+huawei@kernel.org>
@ 2020-06-23 13:31 ` Mauro Carvalho Chehab
2020-06-23 13:31 ` [PATCH v3 2/7] docs: trace: ring-buffer-design.txt: convert " Mauro Carvalho Chehab
` (5 subsequent siblings)
6 siblings, 0 replies; 7+ messages in thread
From: Mauro Carvalho Chehab @ 2020-06-23 13:31 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, linux-kernel, Jonathan Corbet,
Rob Herring, Harry Wei, Alex Shi, devicetree
- Add a SPDX header;
- Adjust document title;
- Adjust document and section titles;
- Some whitespace fixes and new line breaks;
- Mark literal blocks as such;
- Add table markups;
- Add it to devicetree/index.rst.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
Documentation/arm/booting.rst | 2 +-
...-without-of.txt => booting-without-of.rst} | 298 ++++++++++--------
Documentation/devicetree/index.rst | 1 +
Documentation/translations/zh_CN/arm/Booting | 2 +-
4 files changed, 168 insertions(+), 135 deletions(-)
rename Documentation/devicetree/{booting-without-of.txt => booting-without-of.rst} (90%)
diff --git a/Documentation/arm/booting.rst b/Documentation/arm/booting.rst
index 4babb6c6ae1e..a2263451dc2c 100644
--- a/Documentation/arm/booting.rst
+++ b/Documentation/arm/booting.rst
@@ -128,7 +128,7 @@ it. The recommended placement is in the first 16KiB of RAM.
The boot loader must load a device tree image (dtb) into system ram
at a 64bit aligned address and initialize it with the boot data. The
-dtb format is documented in Documentation/devicetree/booting-without-of.txt.
+dtb format is documented in Documentation/devicetree/booting-without-of.rst.
The kernel will look for the dtb magic value of 0xd00dfeed at the dtb
physical address to determine if a dtb has been passed instead of a
tagged list.
diff --git a/Documentation/devicetree/booting-without-of.txt b/Documentation/devicetree/booting-without-of.rst
similarity index 90%
rename from Documentation/devicetree/booting-without-of.txt
rename to Documentation/devicetree/booting-without-of.rst
index 4660ccee35a3..e9433350a20f 100644
--- a/Documentation/devicetree/booting-without-of.txt
+++ b/Documentation/devicetree/booting-without-of.rst
@@ -1,15 +1,19 @@
- Booting the Linux/ppc kernel without Open Firmware
- --------------------------------------------------
-
-(c) 2005 Benjamin Herrenschmidt <benh at kernel.crashing.org>,
- IBM Corp.
-(c) 2005 Becky Bruce <becky.bruce at freescale.com>,
- Freescale Semiconductor, FSL SOC and 32-bit additions
-(c) 2006 MontaVista Software, Inc.
- Flash chip node definition
-
-Table of Contents
-=================
+.. SPDX-License-Identifier: GPL-2.0
+
+==================================================
+Booting the Linux/ppc kernel without Open Firmware
+==================================================
+
+Copyright (c) 2005 Benjamin Herrenschmidt <benh at kernel.crashing.org>,
+IBM Corp.
+
+Copyright (c) 2005 Becky Bruce <becky.bruce at freescale.com>,
+Freescale Semiconductor, FSL SOC and 32-bit additions
+
+Copyright (c) 2006 MontaVista Software, Inc.
+Flash chip node definition
+
+.. Table of Contents
I - Introduction
1) Entry point for arch/arm
@@ -61,15 +65,18 @@ Table of Contents
Revision Information
====================
- May 18, 2005: Rev 0.1 - Initial draft, no chapter III yet.
+ May 18, 2005: Rev 0.1
+ - Initial draft, no chapter III yet.
- May 19, 2005: Rev 0.2 - Add chapter III and bits & pieces here or
+ May 19, 2005: Rev 0.2
+ - Add chapter III and bits & pieces here or
clarifies the fact that a lot of things are
optional, the kernel only requires a very
small device tree, though it is encouraged
to provide an as complete one as possible.
- May 24, 2005: Rev 0.3 - Precise that DT block has to be in RAM
+ May 24, 2005: Rev 0.3
+ - Precise that DT block has to be in RAM
- Misc fixes
- Define version 3 and new format version 16
for the DT block (version 16 needs kernel
@@ -82,7 +89,8 @@ Revision Information
"name" property is now automatically
deduced from the unit name
- June 1, 2005: Rev 0.4 - Correct confusion between OF_DT_END and
+ June 1, 2005: Rev 0.4
+ - Correct confusion between OF_DT_END and
OF_DT_END_NODE in structure definition.
- Change version 16 format to always align
property data to 4 bytes. Since tokens are
@@ -115,7 +123,7 @@ Revision Information
- Compare FSL SOC use of PCI to standard and make sure no new
node definition required.
- Add more information about node definitions for SOC devices
- that currently have no standard, like the FSL CPM.
+ that currently have no standard, like the FSL CPM.
I - Introduction
@@ -260,7 +268,7 @@ it with special cases.
b) create your main platform file as
"arch/powerpc/platforms/myplatform/myboard_setup.c" and add it
- to the Makefile under the condition of your CONFIG_
+ to the Makefile under the condition of your ``CONFIG_``
option. This file will define a structure of type "ppc_md"
containing the various callbacks that the generic code will
use to get to your platform specific code
@@ -271,7 +279,7 @@ it with special cases.
with classic Powerpc architectures.
3) Entry point for arch/x86
--------------------------------
+---------------------------
There is one single 32bit entry point to the kernel at code32_start,
the decompressor (the real mode entry point goes to the same 32bit
@@ -280,9 +288,9 @@ it with special cases.
Documentation/x86/boot.rst
The physical pointer to the device-tree block (defined in chapter II)
is passed via setup_data which requires at least boot protocol 2.09.
- The type filed is defined as
+ The type filed is defined as::
- #define SETUP_DTB 2
+ #define SETUP_DTB 2
This device-tree is used as an extension to the "boot page". As such it
does not parse / consider data which is already covered by the boot
@@ -354,9 +362,9 @@ the block to RAM before passing it to the kernel.
The kernel is passed the physical address pointing to an area of memory
that is roughly described in include/linux/of_fdt.h by the structure
- boot_param_header:
+ boot_param_header:::
-struct boot_param_header {
+ struct boot_param_header {
u32 magic; /* magic word OF_DT_HEADER */
u32 totalsize; /* total size of DT block */
u32 off_dt_struct; /* offset to structure */
@@ -374,19 +382,19 @@ struct boot_param_header {
/* version 17 fields below */
u32 size_dt_struct; /* size of the DT structure block */
-};
+ };
- Along with the constants:
+ Along with the constants::
-/* Definitions used by the flattened device tree */
-#define OF_DT_HEADER 0xd00dfeed /* 4: version,
- 4: total size */
-#define OF_DT_BEGIN_NODE 0x1 /* Start node: full name
- */
-#define OF_DT_END_NODE 0x2 /* End node */
-#define OF_DT_PROP 0x3 /* Property: name off,
- size, content */
-#define OF_DT_END 0x9
+ /* Definitions used by the flattened device tree */
+ #define OF_DT_HEADER 0xd00dfeed /* 4: version,
+ 4: total size */
+ #define OF_DT_BEGIN_NODE 0x1 /* Start node: full name
+ */
+ #define OF_DT_END_NODE 0x2 /* End node */
+ #define OF_DT_PROP 0x3 /* Property: name off,
+ size, content */
+ #define OF_DT_END 0x9
All values in this header are in big endian format, the various
fields in this header are defined more precisely below. All
@@ -430,7 +438,7 @@ struct boot_param_header {
way to avoid overriding critical things like, on Open Firmware
capable machines, the RTAS instance, or on some pSeries, the TCE
tables used for the iommu. Typically, the reserve map should
- contain _at least_ this DT block itself (header,total_size). If
+ contain **at least** this DT block itself (header,total_size). If
you are passing an initrd to the kernel, you should reserve it as
well. You do not need to reserve the kernel image itself. The map
should be 64-bit aligned.
@@ -485,7 +493,7 @@ struct boot_param_header {
So the typical layout of a DT block (though the various parts don't
need to be in that order) looks like this (addresses go from top to
- bottom):
+ bottom)::
------------------------------
@@ -511,9 +519,9 @@ struct boot_param_header {
|
--- (base + totalsize)
- (*) The alignment gaps are not necessarily present; their presence
- and size are dependent on the various alignment requirements of
- the individual data blocks.
+ (*) The alignment gaps are not necessarily present; their presence
+ and size are dependent on the various alignment requirements of
+ the individual data blocks.
2) Device tree generalities
@@ -600,7 +608,7 @@ discussed in a later chapter. At this point, it is only meant to give
you a idea of what a device-tree looks like. I have purposefully kept
the "name" and "linux,phandle" properties which aren't necessary in
order to give you a better idea of what the tree looks like in
-practice.
+practice::
/ o device-tree
|- name = "device-tree"
@@ -650,6 +658,7 @@ properties and their content.
3) Device tree "structure" block
+--------------------------------
The structure of the device tree is a linearized tree structure. The
"OF_DT_BEGIN_NODE" token starts a new node, and the "OF_DT_END_NODE"
@@ -666,12 +675,14 @@ Here's the basic structure of a single node:
root node)
* [align gap to next 4 bytes boundary]
* for each property:
+
* token OF_DT_PROP (that is 0x00000003)
* 32-bit value of property value size in bytes (or 0 if no
value)
* 32-bit value of offset in string block of property name
* property value data if any
* [align gap to next 4 bytes boundary]
+
* [child nodes if any]
* token OF_DT_END_NODE (that is 0x00000002)
@@ -688,6 +699,7 @@ manipulating a flattened tree must take care to preserve this
constraint.
4) Device tree "strings" block
+------------------------------
In order to save space, property names, which are generally redundant,
are stored separately in the "strings" block. This block is simply the
@@ -700,15 +712,17 @@ strings block.
III - Required content of the device tree
=========================================
-WARNING: All "linux,*" properties defined in this document apply only
-to a flattened device-tree. If your platform uses a real
-implementation of Open Firmware or an implementation compatible with
-the Open Firmware client interface, those properties will be created
-by the trampoline code in the kernel's prom_init() file. For example,
-that's where you'll have to add code to detect your board model and
-set the platform number. However, when using the flattened device-tree
-entry point, there is no prom_init() pass, and thus you have to
-provide those properties yourself.
+.. Warning::
+
+ All ``linux,*`` properties defined in this document apply only
+ to a flattened device-tree. If your platform uses a real
+ implementation of Open Firmware or an implementation compatible with
+ the Open Firmware client interface, those properties will be created
+ by the trampoline code in the kernel's prom_init() file. For example,
+ that's where you'll have to add code to detect your board model and
+ set the platform number. However, when using the flattened device-tree
+ entry point, there is no prom_init() pass, and thus you have to
+ provide those properties yourself.
1) Note about cells and address representation
@@ -769,7 +783,7 @@ addresses), all buses must contain a "ranges" property. If the
"ranges" property is missing at a given level, it's assumed that
translation isn't possible, i.e., the registers are not visible on the
parent bus. The format of the "ranges" property for a bus is a list
-of:
+of::
bus address, parent bus address, size
@@ -877,7 +891,7 @@ address which can extend beyond that limit.
This node is the parent of all individual CPU nodes. It doesn't
have any specific requirements, though it's generally good practice
- to have at least:
+ to have at least::
#address-cells = <00000001>
#size-cells = <00000000>
@@ -887,7 +901,7 @@ address which can extend beyond that limit.
that format when reading the "reg" properties of a CPU node, see
below
- c) The /cpus/* nodes
+ c) The ``/cpus/*`` nodes
So under /cpus, you are supposed to create a node for every CPU on
the machine. There is no specific restriction on the name of the
@@ -903,21 +917,23 @@ address which can extend beyond that limit.
- reg : This is the physical CPU number, it's a single 32-bit cell
and is also used as-is as the unit number for constructing the
unit name in the full path. For example, with 2 CPUs, you would
- have the full path:
+ have the full path::
+
/cpus/PowerPC,970FX@0
/cpus/PowerPC,970FX@1
+
(unit addresses do not require leading zeroes)
- - d-cache-block-size : one cell, L1 data cache block size in bytes (*)
+ - d-cache-block-size : one cell, L1 data cache block size in bytes [#]_
- i-cache-block-size : one cell, L1 instruction cache block size in
bytes
- d-cache-size : one cell, size of L1 data cache in bytes
- i-cache-size : one cell, size of L1 instruction cache in bytes
-(*) The cache "block" size is the size on which the cache management
-instructions operate. Historically, this document used the cache
-"line" size here which is incorrect. The kernel will prefer the cache
-block size and will fallback to cache line size for backward
-compatibility.
+ .. [#] The cache "block" size is the size on which the cache management
+ instructions operate. Historically, this document used the cache
+ "line" size here which is incorrect. The kernel will prefer the cache
+ block size and will fallback to cache line size for backward
+ compatibility.
Recommended properties:
@@ -963,10 +979,10 @@ compatibility.
#address-cells and #size-cells of the root node. For example,
with both of these properties being 2 like in the example given
earlier, a 970 based machine with 6Gb of RAM could typically
- have a "reg" property here that looks like:
+ have a "reg" property here that looks like::
- 00000000 00000000 00000000 80000000
- 00000001 00000000 00000001 00000000
+ 00000000 00000000 00000000 80000000
+ 00000001 00000000 00000001 00000000
That is a range starting at 0 of 0x80000000 bytes and a range
starting at 0x100000000 and of 0x100000000 bytes. You can see
@@ -1047,18 +1063,18 @@ compatibility.
See 1) above for more details on defining #address-cells.
- #size-cells : Size representation for "soc" devices
- #interrupt-cells : Defines the width of cells used to represent
- interrupts. Typically this value is <2>, which includes a
- 32-bit number that represents the interrupt number, and a
- 32-bit number that represents the interrupt sense and level.
- This field is only needed if the SOC contains an interrupt
- controller.
+ interrupts. Typically this value is <2>, which includes a
+ 32-bit number that represents the interrupt number, and a
+ 32-bit number that represents the interrupt sense and level.
+ This field is only needed if the SOC contains an interrupt
+ controller.
The SOC node may contain child nodes for each SOC device that the
platform uses. Nodes should not be created for devices which exist
on the SOC but are not used by a particular platform. See chapter VI
for more information on how to specify devices that are part of a SOC.
- Example SOC node for the MPC8540:
+ Example SOC node for the MPC8540::
soc8540@e0000000 {
#address-cells = <1>;
@@ -1079,31 +1095,33 @@ IV - "dtc", the device tree compiler
dtc source code can be found at
<http://git.jdl.com/gitweb/?p=dtc.git>
-WARNING: This version is still in early development stage; the
-resulting device-tree "blobs" have not yet been validated with the
-kernel. The current generated block lacks a useful reserve map (it will
-be fixed to generate an empty one, it's up to the bootloader to fill
-it up) among others. The error handling needs work, bugs are lurking,
-etc...
+.. Warning::
+
+ This version is still in early development stage; the
+ resulting device-tree "blobs" have not yet been validated with the
+ kernel. The current generated block lacks a useful reserve map (it will
+ be fixed to generate an empty one, it's up to the bootloader to fill
+ it up) among others. The error handling needs work, bugs are lurking,
+ etc...
dtc basically takes a device-tree in a given format and outputs a
device-tree in another format. The currently supported formats are:
- Input formats:
- -------------
+Input formats
+-------------
- "dtb": "blob" format, that is a flattened device-tree block
with
- header all in a binary blob.
+ header all in a binary blob.
- "dts": "source" format. This is a text file containing a
"source" for a device-tree. The format is defined later in this
- chapter.
+ chapter.
- "fs" format. This is a representation equivalent to the
- output of /proc/device-tree, that is nodes are directories and
- properties are files
+ output of /proc/device-tree, that is nodes are directories and
+ properties are files
- Output formats:
- ---------------
+Output formats
+--------------
- "dtb": "blob" format
- "dts": "source" format
@@ -1113,7 +1131,7 @@ device-tree in another format. The currently supported formats are:
assembly file exports some symbols that can be used.
-The syntax of the dtc tool is
+The syntax of the dtc tool is::
dtc [-I <input-format>] [-O <output-format>]
[-o output-filename] [-V output_version] input_filename
@@ -1127,43 +1145,45 @@ Additionally, dtc performs various sanity checks on the tree, like the
uniqueness of linux, phandle properties, validity of strings, etc...
The format of the .dts "source" file is "C" like, supports C and C++
-style comments.
+style comments::
-/ {
-}
+ / {
+ }
The above is the "device-tree" definition. It's the only statement
supported currently at the toplevel.
-/ {
- property1 = "string_value"; /* define a property containing a 0
- * terminated string
- */
+::
- property2 = <0x1234abcd>; /* define a property containing a
- * numerical 32-bit value (hexadecimal)
- */
+ / {
+ property1 = "string_value"; /* define a property containing a 0
+ * terminated string
+ */
- property3 = <0x12345678 0x12345678 0xdeadbeef>;
- /* define a property containing 3
- * numerical 32-bit values (cells) in
- * hexadecimal
- */
- property4 = [0x0a 0x0b 0x0c 0x0d 0xde 0xea 0xad 0xbe 0xef];
- /* define a property whose content is
- * an arbitrary array of bytes
- */
+ property2 = <0x1234abcd>; /* define a property containing a
+ * numerical 32-bit value (hexadecimal)
+ */
- childnode@address { /* define a child node named "childnode"
- * whose unit name is "childnode at
- * address"
- */
+ property3 = <0x12345678 0x12345678 0xdeadbeef>;
+ /* define a property containing 3
+ * numerical 32-bit values (cells) in
+ * hexadecimal
+ */
+ property4 = [0x0a 0x0b 0x0c 0x0d 0xde 0xea 0xad 0xbe 0xef];
+ /* define a property whose content is
+ * an arbitrary array of bytes
+ */
- childprop = "hello\n"; /* define a property "childprop" of
- * childnode (in this case, a string)
- */
- };
-};
+ childnode@address { /* define a child node named "childnode"
+ * whose unit name is "childnode at
+ * address"
+ */
+
+ childprop = "hello\n"; /* define a property "childprop" of
+ * childnode (in this case, a string)
+ */
+ };
+ };
Nodes can contain other nodes etc... thus defining the hierarchical
structure of the tree.
@@ -1322,7 +1342,7 @@ phandle of the parent node.
If the interrupt-parent property is not defined for a node, its
interrupt parent is assumed to be an ancestor in the node's
-_device tree_ hierarchy.
+*device tree* hierarchy.
3) OpenPIC Interrupt Controllers
--------------------------------
@@ -1334,10 +1354,12 @@ information.
Sense and level information should be encoded as follows:
- 0 = low to high edge sensitive type enabled
- 1 = active low level sensitive type enabled
- 2 = active high level sensitive type enabled
- 3 = high to low edge sensitive type enabled
+ == ========================================
+ 0 low to high edge sensitive type enabled
+ 1 active low level sensitive type enabled
+ 2 active high level sensitive type enabled
+ 3 high to low edge sensitive type enabled
+ == ========================================
4) ISA Interrupt Controllers
----------------------------
@@ -1350,13 +1372,15 @@ information.
ISA PIC interrupt controllers should adhere to the ISA PIC
encodings listed below:
- 0 = active low level sensitive type enabled
- 1 = active high level sensitive type enabled
- 2 = high to low edge sensitive type enabled
- 3 = low to high edge sensitive type enabled
+ == ========================================
+ 0 active low level sensitive type enabled
+ 1 active high level sensitive type enabled
+ 2 high to low edge sensitive type enabled
+ 3 low to high edge sensitive type enabled
+ == ========================================
VIII - Specifying Device Power Management Information (sleep property)
-===================================================================
+======================================================================
Devices on SOCs often have mechanisms for placing devices into low-power
states that are decoupled from the devices' own register blocks. Sometimes,
@@ -1387,6 +1411,7 @@ reasonably grouped in this manner, then create a virtual sleep controller
sleep-map should wait until its necessity is demonstrated).
IX - Specifying dma bus information
+===================================
Some devices may have DMA memory range shifted relatively to the beginning of
RAM, or even placed outside of kernel RAM. For example, the Keystone 2 SoC
@@ -1404,25 +1429,30 @@ coherent DMA operations. The "dma-coherent" property is intended to be used
for identifying devices supported coherent DMA operations in DT.
* DMA Bus master
+
Optional property:
+
- dma-ranges: <prop-encoded-array> encoded as arbitrary number of triplets of
- (child-bus-address, parent-bus-address, length). Each triplet specified
- describes a contiguous DMA address range.
- The dma-ranges property is used to describe the direct memory access (DMA)
- structure of a memory-mapped bus whose device tree parent can be accessed
- from DMA operations originating from the bus. It provides a means of
- defining a mapping or translation between the physical address space of
- the bus and the physical address space of the parent of the bus.
- (for more information see the Devicetree Specification)
+ (child-bus-address, parent-bus-address, length). Each triplet specified
+ describes a contiguous DMA address range.
+ The dma-ranges property is used to describe the direct memory access (DMA)
+ structure of a memory-mapped bus whose device tree parent can be accessed
+ from DMA operations originating from the bus. It provides a means of
+ defining a mapping or translation between the physical address space of
+ the bus and the physical address space of the parent of the bus.
+ (for more information see the Devicetree Specification)
* DMA Bus child
+
Optional property:
+
- dma-ranges: <empty> value. if present - It means that DMA addresses
- translation has to be enabled for this device.
+ translation has to be enabled for this device.
- dma-coherent: Present if dma operations are coherent
-Example:
-soc {
+Example::
+
+ soc {
compatible = "ti,keystone","simple-bus";
ranges = <0x0 0x0 0x0 0xc0000000>;
dma-ranges = <0x80000000 0x8 0x00000000 0x80000000>;
@@ -1435,11 +1465,13 @@ soc {
[...]
dma-coherent;
};
-};
+ };
Appendix A - Sample SOC node for MPC8540
========================================
+::
+
soc@e0000000 {
#address-cells = <1>;
#size-cells = <1>;
diff --git a/Documentation/devicetree/index.rst b/Documentation/devicetree/index.rst
index 54026763916d..d2a96e1af23e 100644
--- a/Documentation/devicetree/index.rst
+++ b/Documentation/devicetree/index.rst
@@ -15,3 +15,4 @@ Open Firmware and Device Tree
overlay-notes
bindings/index
+ booting-without-of
diff --git a/Documentation/translations/zh_CN/arm/Booting b/Documentation/translations/zh_CN/arm/Booting
index 562e9a2957e6..c3d26ce5f6de 100644
--- a/Documentation/translations/zh_CN/arm/Booting
+++ b/Documentation/translations/zh_CN/arm/Booting
@@ -124,7 +124,7 @@ bootloader 必须传递一个系统内存的位置和最小值，以及根文件
bootloader 必须以 64bit 地址对齐的形式加载一个设备树映像(dtb)到系统
RAM 中，并用启动数据初始化它。dtb 格式在文档
-Documentation/devicetree/booting-without-of.txt 中。内核将会在
+Documentation/devicetree/booting-without-of.rst 中。内核将会在
dtb 物理地址处查找 dtb 魔数值（0xd00dfeed），以确定 dtb 是否已经代替
标签列表被传递进来。
--
2.26.2
^ permalink raw reply related [flat|nested] 7+ messages in thread* [PATCH v3 2/7] docs: trace: ring-buffer-design.txt: convert to ReST format
[not found] <cover.1592918949.git.mchehab+huawei@kernel.org>
2020-06-23 13:31 ` [PATCH v3 1/7] docs: dt: convert booting-without-of.txt to ReST format Mauro Carvalho Chehab
@ 2020-06-23 13:31 ` Mauro Carvalho Chehab
2020-06-23 13:31 ` [PATCH v3 3/7] docs: move nommu-mmap.txt to admin-guide and rename to ReST Mauro Carvalho Chehab
` (4 subsequent siblings)
6 siblings, 0 replies; 7+ messages in thread
From: Mauro Carvalho Chehab @ 2020-06-23 13:31 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, linux-kernel, Jonathan Corbet,
Mathieu Poirier, Phong Tran, Mike Leach, Masami Hiramatsu,
Frank A. Cancio Bello, Steven Rostedt (VMware),
Joel Fernandes (Google)
- Just like some media documents, this file is dual licensed
with GPL and GFDL. As right now the GFDL SPDX definition is
bogus (as it doesn't tell anything about invariant parts),
let's not use SPDX here. Let's use, instead, the same test
as we have on media.
- Convert title to ReST format;
- use :field: markup;
- Proper mark literal blocks as such;
- Add it to trace/index.rst file.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
Documentation/trace/index.rst | 1 +
...ffer-design.txt => ring-buffer-design.rst} | 802 ++++++++++--------
2 files changed, 428 insertions(+), 375 deletions(-)
rename Documentation/trace/{ring-buffer-design.txt => ring-buffer-design.rst} (55%)
diff --git a/Documentation/trace/index.rst b/Documentation/trace/index.rst
index fa9e1c730f6a..7d83156c9ac1 100644
--- a/Documentation/trace/index.rst
+++ b/Documentation/trace/index.rst
@@ -22,6 +22,7 @@ Linux Tracing Technologies
boottime-trace
hwlat_detector
intel_th
+ ring-buffer-design
stm
sys-t
coresight/index
diff --git a/Documentation/trace/ring-buffer-design.txt b/Documentation/trace/ring-buffer-design.rst
similarity index 55%
rename from Documentation/trace/ring-buffer-design.txt
rename to Documentation/trace/ring-buffer-design.rst
index 2d53c6f25b91..9c8d22a53d6c 100644
--- a/Documentation/trace/ring-buffer-design.txt
+++ b/Documentation/trace/ring-buffer-design.rst
@@ -1,11 +1,39 @@
- Lockless Ring Buffer Design
- ===========================
+.. This file is dual-licensed: you can use it either under the terms
+.. of the GPL 2.0 or the GFDL 1.2 license, at your option. Note that this
+.. dual licensing only applies to this file, and not this project as a
+.. whole.
+..
+.. a) This file is free software; you can redistribute it and/or
+.. modify it under the terms of the GNU General Public License as
+.. published by the Free Software Foundation version 2 of
+.. the License.
+..
+.. This file is distributed in the hope that it will be useful,
+.. but WITHOUT ANY WARRANTY; without even the implied warranty of
+.. MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+.. GNU General Public License for more details.
+..
+.. Or, alternatively,
+..
+.. b) Permission is granted to copy, distribute and/or modify this
+.. document under the terms of the GNU Free Documentation License,
+.. Version 1.2 version published by the Free Software
+.. Foundation, with no Invariant Sections, no Front-Cover Texts
+.. and no Back-Cover Texts. A copy of the license is included at
+.. Documentation/userspace-api/media/fdl-appendix.rst.
+..
+.. TODO: replace it to GPL-2.0 OR GFDL-1.2 WITH no-invariant-sections
+
+===========================
+Lockless Ring Buffer Design
+===========================
Copyright 2009 Red Hat Inc.
- Author: Steven Rostedt <srostedt@redhat.com>
- License: The GNU Free Documentation License, Version 1.2
- (dual licensed under the GPL v2)
-Reviewers: Mathieu Desnoyers, Huang Ying, Hidetoshi Seto,
+
+:Author: Steven Rostedt <srostedt@redhat.com>
+:License: The GNU Free Documentation License, Version 1.2
+ (dual licensed under the GPL v2)
+:Reviewers: Mathieu Desnoyers, Huang Ying, Hidetoshi Seto,
and Frederic Weisbecker.
@@ -14,37 +42,50 @@ Written for: 2.6.31
Terminology used in this Document
---------------------------------
-tail - where new writes happen in the ring buffer.
+tail
+ - where new writes happen in the ring buffer.
-head - where new reads happen in the ring buffer.
+head
+ - where new reads happen in the ring buffer.
-producer - the task that writes into the ring buffer (same as writer)
+producer
+ - the task that writes into the ring buffer (same as writer)
-writer - same as producer
+writer
+ - same as producer
-consumer - the task that reads from the buffer (same as reader)
+consumer
+ - the task that reads from the buffer (same as reader)
-reader - same as consumer.
+reader
+ - same as consumer.
-reader_page - A page outside the ring buffer used solely (for the most part)
- by the reader.
+reader_page
+ - A page outside the ring buffer used solely (for the most part)
+ by the reader.
-head_page - a pointer to the page that the reader will use next
+head_page
+ - a pointer to the page that the reader will use next
-tail_page - a pointer to the page that will be written to next
+tail_page
+ - a pointer to the page that will be written to next
-commit_page - a pointer to the page with the last finished non-nested write.
+commit_page
+ - a pointer to the page with the last finished non-nested write.
-cmpxchg - hardware-assisted atomic transaction that performs the following:
+cmpxchg
+ - hardware-assisted atomic transaction that performs the following::
- A = B if previous A == C
+ A = B if previous A == C
- R = cmpxchg(A, C, B) is saying that we replace A with B if and only if
- current A is equal to C, and we put the old (current) A into R
+ R = cmpxchg(A, C, B) is saying that we replace A with B if and only
+ if current A is equal to C, and we put the old (current)
+ A into R
- R gets the previous A regardless if A is updated with B or not.
+ R gets the previous A regardless if A is updated with B or not.
- To see if the update was successful a compare of R == C may be used.
+ To see if the update was successful a compare of ``R == C``
+ may be used.
The Generic Ring Buffer
-----------------------
@@ -64,7 +105,7 @@ No two writers can write at the same time (on the same per-cpu buffer),
but a writer may interrupt another writer, but it must finish writing
before the previous writer may continue. This is very important to the
algorithm. The writers act like a "stack". The way interrupts works
-enforces this behavior.
+enforces this behavior::
writer1 start
@@ -115,6 +156,8 @@ A sample of how the reader page is swapped: Note this does not
show the head page in the buffer, it is for demonstrating a swap
only.
+::
+
+------+
|reader| RING BUFFER
|page |
@@ -172,21 +215,22 @@ only.
It is possible that the page swapped is the commit page and the tail page,
if what is in the ring buffer is less than what is held in a buffer page.
+::
- reader page commit page tail page
- | | |
- v | |
- +---+ | |
- | |<----------+ |
- | |<------------------------+
- | |------+
- +---+ |
- |
- v
- +---+ +---+ +---+ +---+
-<---| |--->| |--->| |--->| |--->
---->| |<---| |<---| |<---| |<---
- +---+ +---+ +---+ +---+
+ reader page commit page tail page
+ | | |
+ v | |
+ +---+ | |
+ | |<----------+ |
+ | |<------------------------+
+ | |------+
+ +---+ |
+ |
+ v
+ +---+ +---+ +---+ +---+
+ <---| |--->| |--->| |--->| |--->
+ --->| |<---| |<---| |<---| |<---
+ +---+ +---+ +---+ +---+
This case is still valid for this algorithm.
When the writer leaves the page, it simply goes into the ring buffer
@@ -196,15 +240,19 @@ buffer.
The main pointers:
- reader page - The page used solely by the reader and is not part
- of the ring buffer (may be swapped in)
+ reader page
+ - The page used solely by the reader and is not part
+ of the ring buffer (may be swapped in)
- head page - the next page in the ring buffer that will be swapped
+ head page
+ - the next page in the ring buffer that will be swapped
with the reader page.
- tail page - the page where the next write will take place.
+ tail page
+ - the page where the next write will take place.
- commit page - the page that last finished a write.
+ commit page
+ - the page that last finished a write.
The commit page only is updated by the outermost writer in the
writer stack. A writer that preempts another writer will not move the
@@ -219,7 +267,7 @@ transaction. If another write happens it must finish before continuing
with the previous write.
- Write reserve:
+ Write reserve::
Buffer page
+---------+
@@ -230,7 +278,7 @@ with the previous write.
| empty |
+---------+
- Write commit:
+ Write commit::
Buffer page
+---------+
@@ -242,7 +290,7 @@ with the previous write.
+---------+
- If a write happens after the first reserve:
+ If a write happens after the first reserve::
Buffer page
+---------+
@@ -253,7 +301,7 @@ with the previous write.
|reserved |
+---------+ <--- tail pointer
- After second writer commits:
+ After second writer commits::
Buffer page
@@ -266,7 +314,7 @@ with the previous write.
|commit |
+---------+ <--- tail pointer
- When the first writer commits:
+ When the first writer commits::
Buffer page
+---------+
@@ -292,21 +340,22 @@ be several pages ahead. If the tail page catches up to the commit
page then no more writes may take place (regardless of the mode
of the ring buffer: overwrite and produce/consumer).
-The order of pages is:
+The order of pages is::
head page
commit page
tail page
-Possible scenario:
- tail page
- head page commit page |
- | | |
- v v v
- +---+ +---+ +---+ +---+
-<---| |--->| |--->| |--->| |--->
---->| |<---| |<---| |<---| |<---
- +---+ +---+ +---+ +---+
+Possible scenario::
+
+ tail page
+ head page commit page |
+ | | |
+ v v v
+ +---+ +---+ +---+ +---+
+ <---| |--->| |--->| |--->| |--->
+ --->| |<---| |<---| |<---| |<---
+ +---+ +---+ +---+ +---+
There is a special case that the head page is after either the commit page
and possibly the tail page. That is when the commit (and tail) page has been
@@ -315,24 +364,25 @@ part of the ring buffer, but the reader page is not. Whenever there
has been less than a full page that has been committed inside the ring buffer,
and a reader swaps out a page, it will be swapping out the commit page.
+::
- reader page commit page tail page
- | | |
- v | |
- +---+ | |
- | |<----------+ |
- | |<------------------------+
- | |------+
- +---+ |
- |
- v
- +---+ +---+ +---+ +---+
-<---| |--->| |--->| |--->| |--->
---->| |<---| |<---| |<---| |<---
- +---+ +---+ +---+ +---+
- ^
- |
- head page
+ reader page commit page tail page
+ | | |
+ v | |
+ +---+ | |
+ | |<----------+ |
+ | |<------------------------+
+ | |------+
+ +---+ |
+ |
+ v
+ +---+ +---+ +---+ +---+
+ <---| |--->| |--->| |--->| |--->
+ --->| |<---| |<---| |<---| |<---
+ +---+ +---+ +---+ +---+
+ ^
+ |
+ head page
In this case, the head page will not move when the tail and commit
@@ -347,42 +397,42 @@ When the tail meets the head page, if the buffer is in overwrite mode,
the head page will be pushed ahead one. If the buffer is in producer/consumer
mode, the write will fail.
-Overwrite mode:
+Overwrite mode::
- tail page
- |
- v
- +---+ +---+ +---+ +---+
-<---| |--->| |--->| |--->| |--->
---->| |<---| |<---| |<---| |<---
- +---+ +---+ +---+ +---+
- ^
- |
- head page
+ tail page
+ |
+ v
+ +---+ +---+ +---+ +---+
+ <---| |--->| |--->| |--->| |--->
+ --->| |<---| |<---| |<---| |<---
+ +---+ +---+ +---+ +---+
+ ^
+ |
+ head page
- tail page
- |
- v
- +---+ +---+ +---+ +---+
-<---| |--->| |--->| |--->| |--->
---->| |<---| |<---| |<---| |<---
- +---+ +---+ +---+ +---+
- ^
- |
- head page
+ tail page
+ |
+ v
+ +---+ +---+ +---+ +---+
+ <---| |--->| |--->| |--->| |--->
+ --->| |<---| |<---| |<---| |<---
+ +---+ +---+ +---+ +---+
+ ^
+ |
+ head page
- tail page
- |
- v
- +---+ +---+ +---+ +---+
-<---| |--->| |--->| |--->| |--->
---->| |<---| |<---| |<---| |<---
- +---+ +---+ +---+ +---+
- ^
- |
- head page
+ tail page
+ |
+ v
+ +---+ +---+ +---+ +---+
+ <---| |--->| |--->| |--->| |--->
+ --->| |<---| |<---| |<---| |<---
+ +---+ +---+ +---+ +---+
+ ^
+ |
+ head page
Note, the reader page will still point to the previous head page.
But when a swap takes place, it will use the most recent head page.
@@ -397,7 +447,7 @@ State flags are placed inside the pointer to the page. To do this,
each page must be aligned in memory by 4 bytes. This will allow the 2
least significant bits of the address to be used as flags, since
they will always be zero for the address. To get the address,
-simply mask out the flags.
+simply mask out the flags::
MASK = ~3
@@ -405,24 +455,27 @@ simply mask out the flags.
Two flags will be kept by these two bits:
- HEADER - the page being pointed to is a head page
+ HEADER
+ - the page being pointed to is a head page
- UPDATE - the page being pointed to is being updated by a writer
+ UPDATE
+ - the page being pointed to is being updated by a writer
and was or is about to be a head page.
+::
- reader page
- |
- v
- +---+
- | |------+
- +---+ |
- |
- v
- +---+ +---+ +---+ +---+
-<---| |--->| |-H->| |--->| |--->
---->| |<---| |<---| |<---| |<---
- +---+ +---+ +---+ +---+
+ reader page
+ |
+ v
+ +---+
+ | |------+
+ +---+ |
+ |
+ v
+ +---+ +---+ +---+ +---+
+ <---| |--->| |-H->| |--->| |--->
+ --->| |<---| |<---| |<---| |<---
+ +---+ +---+ +---+ +---+
The above pointer "-H->" would have the HEADER flag set. That is
@@ -430,24 +483,24 @@ the next page is the next page to be swapped out by the reader.
This pointer means the next page is the head page.
When the tail page meets the head pointer, it will use cmpxchg to
-change the pointer to the UPDATE state:
+change the pointer to the UPDATE state::
- tail page
- |
- v
- +---+ +---+ +---+ +---+
-<---| |--->| |-H->| |--->| |--->
---->| |<---| |<---| |<---| |<---
- +---+ +---+ +---+ +---+
+ tail page
+ |
+ v
+ +---+ +---+ +---+ +---+
+ <---| |--->| |-H->| |--->| |--->
+ --->| |<---| |<---| |<---| |<---
+ +---+ +---+ +---+ +---+
- tail page
- |
- v
- +---+ +---+ +---+ +---+
-<---| |--->| |-U->| |--->| |--->
---->| |<---| |<---| |<---| |<---
- +---+ +---+ +---+ +---+
+ tail page
+ |
+ v
+ +---+ +---+ +---+ +---+
+ <---| |--->| |-U->| |--->| |--->
+ --->| |<---| |<---| |<---| |<---
+ +---+ +---+ +---+ +---+
"-U->" represents a pointer in the UPDATE state.
@@ -462,7 +515,7 @@ head page does not have the HEADER flag set, the compare will fail
and the reader will need to look for the new head page and try again.
Note, the flags UPDATE and HEADER are never set at the same time.
-The reader swaps the reader page as follows:
+The reader swaps the reader page as follows::
+------+
|reader| RING BUFFER
@@ -477,7 +530,7 @@ The reader swaps the reader page as follows:
+-----H-------------+
The reader sets the reader page next pointer as HEADER to the page after
-the head page.
+the head page::
+------+
@@ -495,7 +548,7 @@ the head page.
It does a cmpxchg with the pointer to the previous head page to make it
point to the reader page. Note that the new pointer does not have the HEADER
-flag set. This action atomically moves the head page forward.
+flag set. This action atomically moves the head page forward::
+------+
|reader| RING BUFFER
@@ -511,7 +564,7 @@ flag set. This action atomically moves the head page forward.
+------------------------------------+
After the new head page is set, the previous pointer of the head page is
-updated to the reader page.
+updated to the reader page::
+------+
|reader| RING BUFFER
@@ -548,7 +601,7 @@ prev pointers may not.
Note, the way to determine a reader page is simply by examining the previous
pointer of the page. If the next pointer of the previous page does not
-point back to the original page, then the original page is a reader page:
+point back to the original page, then the original page is a reader page::
+--------+
@@ -572,54 +625,54 @@ not be able to swap the head page from the buffer, nor will it be able to
move the head page, until the writer is finished with the move.
This eliminates any races that the reader can have on the writer. The reader
-must spin, and this is why the reader cannot preempt the writer.
+must spin, and this is why the reader cannot preempt the writer::
- tail page
- |
- v
- +---+ +---+ +---+ +---+
-<---| |--->| |-H->| |--->| |--->
---->| |<---| |<---| |<---| |<---
- +---+ +---+ +---+ +---+
+ tail page
+ |
+ v
+ +---+ +---+ +---+ +---+
+ <---| |--->| |-H->| |--->| |--->
+ --->| |<---| |<---| |<---| |<---
+ +---+ +---+ +---+ +---+
- tail page
- |
- v
- +---+ +---+ +---+ +---+
-<---| |--->| |-U->| |--->| |--->
---->| |<---| |<---| |<---| |<---
- +---+ +---+ +---+ +---+
+ tail page
+ |
+ v
+ +---+ +---+ +---+ +---+
+ <---| |--->| |-U->| |--->| |--->
+ --->| |<---| |<---| |<---| |<---
+ +---+ +---+ +---+ +---+
-The following page will be made into the new head page.
+The following page will be made into the new head page::
- tail page
- |
- v
- +---+ +---+ +---+ +---+
-<---| |--->| |-U->| |-H->| |--->
---->| |<---| |<---| |<---| |<---
- +---+ +---+ +---+ +---+
+ tail page
+ |
+ v
+ +---+ +---+ +---+ +---+
+ <---| |--->| |-U->| |-H->| |--->
+ --->| |<---| |<---| |<---| |<---
+ +---+ +---+ +---+ +---+
After the new head page has been set, we can set the old head page
-pointer back to NORMAL.
+pointer back to NORMAL::
- tail page
- |
- v
- +---+ +---+ +---+ +---+
-<---| |--->| |--->| |-H->| |--->
---->| |<---| |<---| |<---| |<---
- +---+ +---+ +---+ +---+
+ tail page
+ |
+ v
+ +---+ +---+ +---+ +---+
+ <---| |--->| |--->| |-H->| |--->
+ --->| |<---| |<---| |<---| |<---
+ +---+ +---+ +---+ +---+
-After the head page has been moved, the tail page may now move forward.
+After the head page has been moved, the tail page may now move forward::
- tail page
- |
- v
- +---+ +---+ +---+ +---+
-<---| |--->| |--->| |-H->| |--->
---->| |<---| |<---| |<---| |<---
- +---+ +---+ +---+ +---+
+ tail page
+ |
+ v
+ +---+ +---+ +---+ +---+
+ <---| |--->| |--->| |-H->| |--->
+ --->| |<---| |<---| |<---| |<---
+ +---+ +---+ +---+ +---+
The above are the trivial updates. Now for the more complex scenarios.
@@ -630,26 +683,26 @@ tail page may make it all the way around the buffer and meet the commit
page. At this time, we must start dropping writes (usually with some kind
of warning to the user). But what happens if the commit was still on the
reader page? The commit page is not part of the ring buffer. The tail page
-must account for this.
+must account for this::
- reader page commit page
- | |
- v |
- +---+ |
- | |<----------+
- | |
- | |------+
- +---+ |
- |
- v
- +---+ +---+ +---+ +---+
-<---| |--->| |-H->| |--->| |--->
---->| |<---| |<---| |<---| |<---
- +---+ +---+ +---+ +---+
- ^
- |
- tail page
+ reader page commit page
+ | |
+ v |
+ +---+ |
+ | |<----------+
+ | |
+ | |------+
+ +---+ |
+ |
+ v
+ +---+ +---+ +---+ +---+
+ <---| |--->| |-H->| |--->| |--->
+ --->| |<---| |<---| |<---| |<---
+ +---+ +---+ +---+ +---+
+ ^
+ |
+ tail page
If the tail page were to simply push the head page forward, the commit when
leaving the reader page would not be pointing to the correct page.
@@ -676,7 +729,7 @@ the head page if the head page is the next page. If the head page
is not the next page, the tail page is simply updated with a cmpxchg.
Only writers move the tail page. This must be done atomically to protect
-against nested writers.
+against nested writers::
temp_page = tail_page
next_page = temp_page->next
@@ -684,54 +737,54 @@ against nested writers.
The above will update the tail page if it is still pointing to the expected
page. If this fails, a nested write pushed it forward, the current write
-does not need to push it.
+does not need to push it::
- temp page
- |
- v
- tail page
- |
- v
- +---+ +---+ +---+ +---+
-<---| |--->| |--->| |--->| |--->
---->| |<---| |<---| |<---| |<---
- +---+ +---+ +---+ +---+
+ temp page
+ |
+ v
+ tail page
+ |
+ v
+ +---+ +---+ +---+ +---+
+ <---| |--->| |--->| |--->| |--->
+ --->| |<---| |<---| |<---| |<---
+ +---+ +---+ +---+ +---+
-Nested write comes in and moves the tail page forward:
+Nested write comes in and moves the tail page forward::
- tail page (moved by nested writer)
- temp page |
- | |
- v v
- +---+ +---+ +---+ +---+
-<---| |--->| |--->| |--->| |--->
---->| |<---| |<---| |<---| |<---
- +---+ +---+ +---+ +---+
+ tail page (moved by nested writer)
+ temp page |
+ | |
+ v v
+ +---+ +---+ +---+ +---+
+ <---| |--->| |--->| |--->| |--->
+ --->| |<---| |<---| |<---| |<---
+ +---+ +---+ +---+ +---+
The above would fail the cmpxchg, but since the tail page has already
been moved forward, the writer will just try again to reserve storage
on the new tail page.
-But the moving of the head page is a bit more complex.
+But the moving of the head page is a bit more complex::
- tail page
- |
- v
- +---+ +---+ +---+ +---+
-<---| |--->| |-H->| |--->| |--->
---->| |<---| |<---| |<---| |<---
- +---+ +---+ +---+ +---+
+ tail page
+ |
+ v
+ +---+ +---+ +---+ +---+
+ <---| |--->| |-H->| |--->| |--->
+ --->| |<---| |<---| |<---| |<---
+ +---+ +---+ +---+ +---+
-The write converts the head page pointer to UPDATE.
+The write converts the head page pointer to UPDATE::
- tail page
- |
- v
- +---+ +---+ +---+ +---+
-<---| |--->| |-U->| |--->| |--->
---->| |<---| |<---| |<---| |<---
- +---+ +---+ +---+ +---+
+ tail page
+ |
+ v
+ +---+ +---+ +---+ +---+
+ <---| |--->| |-U->| |--->| |--->
+ --->| |<---| |<---| |<---| |<---
+ +---+ +---+ +---+ +---+
But if a nested writer preempts here, it will see that the next
page is a head page, but it is also nested. It will detect that
@@ -739,217 +792,216 @@ it is nested and will save that information. The detection is the
fact that it sees the UPDATE flag instead of a HEADER or NORMAL
pointer.
-The nested writer will set the new head page pointer.
+The nested writer will set the new head page pointer::
- tail page
- |
- v
- +---+ +---+ +---+ +---+
-<---| |--->| |-U->| |-H->| |--->
---->| |<---| |<---| |<---| |<---
- +---+ +---+ +---+ +---+
+ tail page
+ |
+ v
+ +---+ +---+ +---+ +---+
+ <---| |--->| |-U->| |-H->| |--->
+ --->| |<---| |<---| |<---| |<---
+ +---+ +---+ +---+ +---+
But it will not reset the update back to normal. Only the writer
that converted a pointer from HEAD to UPDATE will convert it back
-to NORMAL.
+to NORMAL::
- tail page
- |
- v
- +---+ +---+ +---+ +---+
-<---| |--->| |-U->| |-H->| |--->
---->| |<---| |<---| |<---| |<---
- +---+ +---+ +---+ +---+
+ tail page
+ |
+ v
+ +---+ +---+ +---+ +---+
+ <---| |--->| |-U->| |-H->| |--->
+ --->| |<---| |<---| |<---| |<---
+ +---+ +---+ +---+ +---+
After the nested writer finishes, the outermost writer will convert
-the UPDATE pointer to NORMAL.
+the UPDATE pointer to NORMAL::
- tail page
- |
- v
- +---+ +---+ +---+ +---+
-<---| |--->| |--->| |-H->| |--->
---->| |<---| |<---| |<---| |<---
- +---+ +---+ +---+ +---+
+ tail page
+ |
+ v
+ +---+ +---+ +---+ +---+
+ <---| |--->| |--->| |-H->| |--->
+ --->| |<---| |<---| |<---| |<---
+ +---+ +---+ +---+ +---+
It can be even more complex if several nested writes came in and moved
-the tail page ahead several pages:
+the tail page ahead several pages::
-(first writer)
+ (first writer)
- tail page
- |
- v
- +---+ +---+ +---+ +---+
-<---| |--->| |-H->| |--->| |--->
---->| |<---| |<---| |<---| |<---
- +---+ +---+ +---+ +---+
+ tail page
+ |
+ v
+ +---+ +---+ +---+ +---+
+ <---| |--->| |-H->| |--->| |--->
+ --->| |<---| |<---| |<---| |<---
+ +---+ +---+ +---+ +---+
-The write converts the head page pointer to UPDATE.
+The write converts the head page pointer to UPDATE::
- tail page
- |
- v
- +---+ +---+ +---+ +---+
-<---| |--->| |-U->| |--->| |--->
---->| |<---| |<---| |<---| |<---
- +---+ +---+ +---+ +---+
+ tail page
+ |
+ v
+ +---+ +---+ +---+ +---+
+ <---| |--->| |-U->| |--->| |--->
+ --->| |<---| |<---| |<---| |<---
+ +---+ +---+ +---+ +---+
Next writer comes in, and sees the update and sets up the new
-head page.
+head page::
-(second writer)
+ (second writer)
- tail page
- |
- v
- +---+ +---+ +---+ +---+
-<---| |--->| |-U->| |-H->| |--->
---->| |<---| |<---| |<---| |<---
- +---+ +---+ +---+ +---+
+ tail page
+ |
+ v
+ +---+ +---+ +---+ +---+
+ <---| |--->| |-U->| |-H->| |--->
+ --->| |<---| |<---| |<---| |<---
+ +---+ +---+ +---+ +---+
The nested writer moves the tail page forward. But does not set the old
-update page to NORMAL because it is not the outermost writer.
+update page to NORMAL because it is not the outermost writer::
- tail page
- |
- v
- +---+ +---+ +---+ +---+
-<---| |--->| |-U->| |-H->| |--->
---->| |<---| |<---| |<---| |<---
- +---+ +---+ +---+ +---+
+ tail page
+ |
+ v
+ +---+ +---+ +---+ +---+
+ <---| |--->| |-U->| |-H->| |--->
+ --->| |<---| |<---| |<---| |<---
+ +---+ +---+ +---+ +---+
Another writer preempts and sees the page after the tail page is a head page.
-It changes it from HEAD to UPDATE.
+It changes it from HEAD to UPDATE::
-(third writer)
+ (third writer)
- tail page
- |
- v
- +---+ +---+ +---+ +---+
-<---| |--->| |-U->| |-U->| |--->
---->| |<---| |<---| |<---| |<---
- +---+ +---+ +---+ +---+
+ tail page
+ |
+ v
+ +---+ +---+ +---+ +---+
+ <---| |--->| |-U->| |-U->| |--->
+ --->| |<---| |<---| |<---| |<---
+ +---+ +---+ +---+ +---+
-The writer will move the head page forward:
+The writer will move the head page forward::
-(third writer)
+ (third writer)
- tail page
- |
- v
- +---+ +---+ +---+ +---+
-<---| |--->| |-U->| |-U->| |-H->
---->| |<---| |<---| |<---| |<---
- +---+ +---+ +---+ +---+
+ tail page
+ |
+ v
+ +---+ +---+ +---+ +---+
+ <---| |--->| |-U->| |-U->| |-H->
+ --->| |<---| |<---| |<---| |<---
+ +---+ +---+ +---+ +---+
But now that the third writer did change the HEAD flag to UPDATE it
-will convert it to normal:
+will convert it to normal::
-(third writer)
+ (third writer)
- tail page
- |
- v
- +---+ +---+ +---+ +---+
-<---| |--->| |-U->| |--->| |-H->
---->| |<---| |<---| |<---| |<---
- +---+ +---+ +---+ +---+
+ tail page
+ |
+ v
+ +---+ +---+ +---+ +---+
+ <---| |--->| |-U->| |--->| |-H->
+ --->| |<---| |<---| |<---| |<---
+ +---+ +---+ +---+ +---+
-Then it will move the tail page, and return back to the second writer.
+Then it will move the tail page, and return back to the second writer::
-(second writer)
+ (second writer)
- tail page
- |
- v
- +---+ +---+ +---+ +---+
-<---| |--->| |-U->| |--->| |-H->
---->| |<---| |<---| |<---| |<---
- +---+ +---+ +---+ +---+
+ tail page
+ |
+ v
+ +---+ +---+ +---+ +---+
+ <---| |--->| |-U->| |--->| |-H->
+ --->| |<---| |<---| |<---| |<---
+ +---+ +---+ +---+ +---+
The second writer will fail to move the tail page because it was already
moved, so it will try again and add its data to the new tail page.
-It will return to the first writer.
+It will return to the first writer::
-(first writer)
+ (first writer)
- tail page
- |
- v
- +---+ +---+ +---+ +---+
-<---| |--->| |-U->| |--->| |-H->
---->| |<---| |<---| |<---| |<---
- +---+ +---+ +---+ +---+
+ tail page
+ |
+ v
+ +---+ +---+ +---+ +---+
+ <---| |--->| |-U->| |--->| |-H->
+ --->| |<---| |<---| |<---| |<---
+ +---+ +---+ +---+ +---+
The first writer cannot know atomically if the tail page moved
while it updates the HEAD page. It will then update the head page to
-what it thinks is the new head page.
+what it thinks is the new head page::
-(first writer)
+ (first writer)
- tail page
- |
- v
- +---+ +---+ +---+ +---+
-<---| |--->| |-U->| |-H->| |-H->
---->| |<---| |<---| |<---| |<---
- +---+ +---+ +---+ +---+
+ tail page
+ |
+ v
+ +---+ +---+ +---+ +---+
+ <---| |--->| |-U->| |-H->| |-H->
+ --->| |<---| |<---| |<---| |<---
+ +---+ +---+ +---+ +---+
Since the cmpxchg returns the old value of the pointer the first writer
will see it succeeded in updating the pointer from NORMAL to HEAD.
But as we can see, this is not good enough. It must also check to see
-if the tail page is either where it use to be or on the next page:
+if the tail page is either where it use to be or on the next page::
-(first writer)
+ (first writer)
- A B tail page
- | | |
- v v v
- +---+ +---+ +---+ +---+
-<---| |--->| |-U->| |-H->| |-H->
---->| |<---| |<---| |<---| |<---
- +---+ +---+ +---+ +---+
+ A B tail page
+ | | |
+ v v v
+ +---+ +---+ +---+ +---+
+ <---| |--->| |-U->| |-H->| |-H->
+ --->| |<---| |<---| |<---| |<---
+ +---+ +---+ +---+ +---+
If tail page != A and tail page != B, then it must reset the pointer
back to NORMAL. The fact that it only needs to worry about nested
-writers means that it only needs to check this after setting the HEAD page.
+writers means that it only needs to check this after setting the HEAD page::
-(first writer)
+ (first writer)
- A B tail page
- | | |
- v v v
- +---+ +---+ +---+ +---+
-<---| |--->| |-U->| |--->| |-H->
---->| |<---| |<---| |<---| |<---
- +---+ +---+ +---+ +---+
+ A B tail page
+ | | |
+ v v v
+ +---+ +---+ +---+ +---+
+ <---| |--->| |-U->| |--->| |-H->
+ --->| |<---| |<---| |<---| |<---
+ +---+ +---+ +---+ +---+
Now the writer can update the head page. This is also why the head page must
remain in UPDATE and only reset by the outermost writer. This prevents
-the reader from seeing the incorrect head page.
+the reader from seeing the incorrect head page::
-(first writer)
-
- A B tail page
- | | |
- v v v
- +---+ +---+ +---+ +---+
-<---| |--->| |--->| |--->| |-H->
---->| |<---| |<---| |<---| |<---
- +---+ +---+ +---+ +---+
+ (first writer)
+ A B tail page
+ | | |
+ v v v
+ +---+ +---+ +---+ +---+
+ <---| |--->| |--->| |--->| |-H->
+ --->| |<---| |<---| |<---| |<---
+ +---+ +---+ +---+ +---+
--
2.26.2
^ permalink raw reply related [flat|nested] 7+ messages in thread* [PATCH v3 3/7] docs: move nommu-mmap.txt to admin-guide and rename to ReST
[not found] <cover.1592918949.git.mchehab+huawei@kernel.org>
2020-06-23 13:31 ` [PATCH v3 1/7] docs: dt: convert booting-without-of.txt to ReST format Mauro Carvalho Chehab
2020-06-23 13:31 ` [PATCH v3 2/7] docs: trace: ring-buffer-design.txt: convert " Mauro Carvalho Chehab
@ 2020-06-23 13:31 ` Mauro Carvalho Chehab
2020-06-23 13:31 ` [PATCH v3 4/7] docs: move mailbox.txt to driver-api and rename it Mauro Carvalho Chehab
` (3 subsequent siblings)
6 siblings, 0 replies; 7+ messages in thread
From: Mauro Carvalho Chehab @ 2020-06-23 13:31 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, linux-kernel, Jonathan Corbet,
Maarten Lankhorst, Maxime Ripard, Thomas Zimmermann,
David Airlie, Daniel Vetter, Andrew Morton, Alexandre Belloni,
Bartlomiej Zolnierkiewicz, Andy Shevchenko, Vlastimil Babka,
Sebastian Andrzej Siewior, Johannes Weiner, Nitin Gupta,
Masahiro Yamada, Masami Hiramatsu, Steven Rostedt (VMware),
Will Deacon, Patrick Bellasi, Krzysztof Kozlowski,
Eric W. Biederman, dri-devel, linux-mm, Mike Rapoport
The nommu-mmap.txt file provides description of user visible
behaviuour. So, move it to the admin-guide.
As it is already at the ReST, also rename it.
Suggested-by: Mike Rapoport <rppt@linux.ibm.com>
Suggested-by: Jonathan Corbet <corbet@lwn.net>
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
Documentation/admin-guide/mm/index.rst | 1 +
Documentation/{nommu-mmap.txt => admin-guide/mm/nommu-mmap.rst} | 0
Documentation/admin-guide/sysctl/vm.rst | 2 +-
Documentation/gpu/drm-mm.rst | 2 +-
init/Kconfig | 2 +-
mm/Kconfig | 2 +-
mm/nommu.c | 2 +-
7 files changed, 6 insertions(+), 5 deletions(-)
rename Documentation/{nommu-mmap.txt => admin-guide/mm/nommu-mmap.rst} (100%)
diff --git a/Documentation/admin-guide/mm/index.rst b/Documentation/admin-guide/mm/index.rst
index 11db46448354..774dad6d3d29 100644
--- a/Documentation/admin-guide/mm/index.rst
+++ b/Documentation/admin-guide/mm/index.rst
@@ -31,6 +31,7 @@ the Linux memory management.
idle_page_tracking
ksm
memory-hotplug
+ nommu-map
numa_memory_policy
numaperf
pagemap
diff --git a/Documentation/nommu-mmap.txt b/Documentation/admin-guide/mm/nommu-mmap.rst
similarity index 100%
rename from Documentation/nommu-mmap.txt
rename to Documentation/admin-guide/mm/nommu-mmap.rst
diff --git a/Documentation/admin-guide/sysctl/vm.rst b/Documentation/admin-guide/sysctl/vm.rst
index 4b7c496199ca..4b9d2e8e9142 100644
--- a/Documentation/admin-guide/sysctl/vm.rst
+++ b/Documentation/admin-guide/sysctl/vm.rst
@@ -598,7 +598,7 @@ trimming of allocations is initiated.
The default value is 1.
-See Documentation/nommu-mmap.txt for more information.
+See Documentation/admin-guide/mm/nommu-mmap.rst for more information.
numa_zonelist_order
diff --git a/Documentation/gpu/drm-mm.rst b/Documentation/gpu/drm-mm.rst
index 8d10e6b38918..9abee1589c1e 100644
--- a/Documentation/gpu/drm-mm.rst
+++ b/Documentation/gpu/drm-mm.rst
@@ -311,7 +311,7 @@ To use drm_gem_cma_get_unmapped_area(), drivers must fill the struct
a pointer on drm_gem_cma_get_unmapped_area().
More detailed information about get_unmapped_area can be found in
-Documentation/nommu-mmap.txt
+Documentation/admin-guide/mm/nommu-mmap.rst
Memory Coherency
----------------
diff --git a/init/Kconfig b/init/Kconfig
index a46aa8f3174d..2dd5531dae98 100644
--- a/init/Kconfig
+++ b/init/Kconfig
@@ -1957,7 +1957,7 @@ config MMAP_ALLOW_UNINITIALIZED
userspace. Since that isn't generally a problem on no-MMU systems,
it is normally safe to say Y here.
- See Documentation/nommu-mmap.txt for more information.
+ See Documentation/mm/nommu-mmap.rst for more information.
config SYSTEM_DATA_VERIFICATION
def_bool n
diff --git a/mm/Kconfig b/mm/Kconfig
index f2104cc0d35c..d41f3fa7e923 100644
--- a/mm/Kconfig
+++ b/mm/Kconfig
@@ -387,7 +387,7 @@ config NOMMU_INITIAL_TRIM_EXCESS
This option specifies the initial value of this option. The default
of 1 says that all excess pages should be trimmed.
- See Documentation/nommu-mmap.txt for more information.
+ See Documentation/mm/nommu-mmap.rst for more information.
config TRANSPARENT_HUGEPAGE
bool "Transparent Hugepage Support"
diff --git a/mm/nommu.c b/mm/nommu.c
index f32a69095d50..314174817b04 100644
--- a/mm/nommu.c
+++ b/mm/nommu.c
@@ -5,7 +5,7 @@
* Replacement code for mm functions to support CPU's that don't
* have any form of memory management unit (thus no virtual memory).
*
- * See Documentation/nommu-mmap.txt
+ * See Documentation/mm/nommu-mmap.rst
*
* Copyright (c) 2004-2008 David Howells <dhowells@redhat.com>
* Copyright (c) 2000-2003 David McCullough <davidm@snapgear.com>
--
2.26.2
^ permalink raw reply related [flat|nested] 7+ messages in thread* [PATCH v3 4/7] docs: move mailbox.txt to driver-api and rename it
[not found] <cover.1592918949.git.mchehab+huawei@kernel.org>
` (2 preceding siblings ...)
2020-06-23 13:31 ` [PATCH v3 3/7] docs: move nommu-mmap.txt to admin-guide and rename to ReST Mauro Carvalho Chehab
@ 2020-06-23 13:31 ` Mauro Carvalho Chehab
2020-06-23 13:31 ` [PATCH v3 5/7] docs: move other kAPI documents to core-api Mauro Carvalho Chehab
` (2 subsequent siblings)
6 siblings, 0 replies; 7+ messages in thread
From: Mauro Carvalho Chehab @ 2020-06-23 13:31 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, linux-kernel, Jonathan Corbet,
Jonathan Neuschäfer, Pragat Pandya, Jason Gunthorpe,
Harald Seiler
This file is already at the ReST format. Move it to
driver-api and rename it.
Suggested-by: Jonathan Corbet <corbet@lwn.net>
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
Documentation/driver-api/index.rst | 1 +
Documentation/{mailbox.txt => driver-api/mailbox.rst} | 0
2 files changed, 1 insertion(+)
rename Documentation/{mailbox.txt => driver-api/mailbox.rst} (100%)
diff --git a/Documentation/driver-api/index.rst b/Documentation/driver-api/index.rst
index 6567187e7687..3eb0085d5e42 100644
--- a/Documentation/driver-api/index.rst
+++ b/Documentation/driver-api/index.rst
@@ -48,6 +48,7 @@ available subsections can be seen below.
scsi
libata
target
+ mailbox
mtdnand
miscellaneous
mei/index
diff --git a/Documentation/mailbox.txt b/Documentation/driver-api/mailbox.rst
similarity index 100%
rename from Documentation/mailbox.txt
rename to Documentation/driver-api/mailbox.rst
--
2.26.2
^ permalink raw reply related [flat|nested] 7+ messages in thread* [PATCH v3 5/7] docs: move other kAPI documents to core-api
[not found] <cover.1592918949.git.mchehab+huawei@kernel.org>
` (3 preceding siblings ...)
2020-06-23 13:31 ` [PATCH v3 4/7] docs: move mailbox.txt to driver-api and rename it Mauro Carvalho Chehab
@ 2020-06-23 13:31 ` Mauro Carvalho Chehab
2020-06-23 13:31 ` [PATCH v3 6/7] docs: Add remaining Documentation/*.txt at staging/index.rst Mauro Carvalho Chehab
2020-06-23 13:31 ` [PATCH v3 7/7] docs: staging: use small font for literal includes Mauro Carvalho Chehab
6 siblings, 0 replies; 7+ messages in thread
From: Mauro Carvalho Chehab @ 2020-06-23 13:31 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, linux-kernel, Jonathan Corbet,
Mike Rapoport, Masahiro Yamada, Daniel Jordan,
Matthew Wilcox (Oracle),
Ricardo Cañuelo, Stephen Kitt, Andrew Morton,
Peter Zijlstra, Aneesh Kumar K.V, Kees Cook, Will Deacon,
Alexandre Ghiti, Thomas Gleixner, Arnd Bergmann, Sami Tolvanen,
Peter Collingbourne, Krzysztof Kozlowski, Stephen Boyd
There are a number of random documents that seem to be
describing some aspects of the core-api. Move them to such
directory, adding them at the core-api/index.rst file.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
.../bus-virt-phys-mapping.rst} | 0
Documentation/core-api/index.rst | 3 +++
Documentation/{this_cpu_ops.txt => core-api/this_cpu_ops.rst} | 0
.../{process => core-api}/unaligned-memory-access.rst | 0
arch/Kconfig | 2 +-
5 files changed, 4 insertions(+), 1 deletion(-)
rename Documentation/{bus-virt-phys-mapping.txt => core-api/bus-virt-phys-mapping.rst} (100%)
rename Documentation/{this_cpu_ops.txt => core-api/this_cpu_ops.rst} (100%)
rename Documentation/{process => core-api}/unaligned-memory-access.rst (100%)
diff --git a/Documentation/bus-virt-phys-mapping.txt b/Documentation/core-api/bus-virt-phys-mapping.rst
similarity index 100%
rename from Documentation/bus-virt-phys-mapping.txt
rename to Documentation/core-api/bus-virt-phys-mapping.rst
diff --git a/Documentation/core-api/index.rst b/Documentation/core-api/index.rst
index 15ab86112627..69171b1799f2 100644
--- a/Documentation/core-api/index.rst
+++ b/Documentation/core-api/index.rst
@@ -39,6 +39,8 @@ Library functionality that is used throughout the kernel.
rbtree
generic-radix-tree
packing
+ bus-virt-phys-mapping
+ this_cpu_ops
timekeeping
errseq
@@ -82,6 +84,7 @@ more memory-management documentation in :doc:`/vm/index`.
:maxdepth: 1
memory-allocation
+ unaligned-memory-access
dma-api
dma-api-howto
dma-attributes
diff --git a/Documentation/this_cpu_ops.txt b/Documentation/core-api/this_cpu_ops.rst
similarity index 100%
rename from Documentation/this_cpu_ops.txt
rename to Documentation/core-api/this_cpu_ops.rst
diff --git a/Documentation/process/unaligned-memory-access.rst b/Documentation/core-api/unaligned-memory-access.rst
similarity index 100%
rename from Documentation/process/unaligned-memory-access.rst
rename to Documentation/core-api/unaligned-memory-access.rst
diff --git a/arch/Kconfig b/arch/Kconfig
index 8cc35dc556c7..2a439fb8069e 100644
--- a/arch/Kconfig
+++ b/arch/Kconfig
@@ -147,7 +147,7 @@ config HAVE_EFFICIENT_UNALIGNED_ACCESS
problems with received packets if doing so would not help
much.
- See Documentation/unaligned-memory-access.txt for more
+ See Documentation/core-api/unaligned-memory-access.rst for more
information on the topic of unaligned memory accesses.
config ARCH_USE_BUILTIN_BSWAP
--
2.26.2
^ permalink raw reply related [flat|nested] 7+ messages in thread* [PATCH v3 6/7] docs: Add remaining Documentation/*.txt at staging/index.rst
[not found] <cover.1592918949.git.mchehab+huawei@kernel.org>
` (4 preceding siblings ...)
2020-06-23 13:31 ` [PATCH v3 5/7] docs: move other kAPI documents to core-api Mauro Carvalho Chehab
@ 2020-06-23 13:31 ` Mauro Carvalho Chehab
2020-06-23 13:31 ` [PATCH v3 7/7] docs: staging: use small font for literal includes Mauro Carvalho Chehab
6 siblings, 0 replies; 7+ messages in thread
From: Mauro Carvalho Chehab @ 2020-06-23 13:31 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, linux-kernel, Jonathan Corbet
There are a few text files that aren't yet at the docs building
system.
Add those to the staging/index.rst.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
Documentation/staging/index.rst | 9 +++------
1 file changed, 3 insertions(+), 6 deletions(-)
diff --git a/Documentation/staging/index.rst b/Documentation/staging/index.rst
index 8cc9d94b0a13..8e98517675ca 100644
--- a/Documentation/staging/index.rst
+++ b/Documentation/staging/index.rst
@@ -19,17 +19,14 @@ Unsorted Documentation
Atomic Types
============
-.. include:: ../atomic_t.txt
- :literal:
+.. literalinclude:: ../atomic_t.txt
Atomic bitops
=============
-.. include:: ../atomic_bitops.txt
- :literal:
+.. literalinclude:: ../atomic_bitops.txt
Memory Barriers
===============
-.. include:: ../memory-barriers.txt
- :literal:
+.. literalinclude:: ../memory-barriers.txt
--
2.26.2
^ permalink raw reply related [flat|nested] 7+ messages in thread* [PATCH v3 7/7] docs: staging: use small font for literal includes
[not found] <cover.1592918949.git.mchehab+huawei@kernel.org>
` (5 preceding siblings ...)
2020-06-23 13:31 ` [PATCH v3 6/7] docs: Add remaining Documentation/*.txt at staging/index.rst Mauro Carvalho Chehab
@ 2020-06-23 13:31 ` Mauro Carvalho Chehab
6 siblings, 0 replies; 7+ messages in thread
From: Mauro Carvalho Chehab @ 2020-06-23 13:31 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, linux-kernel, Jonathan Corbet
The normal font is too big to display 80 columns, causing extra
breaks to be added at weird places.
change to the footnotesize, as this would fit a little bit
better.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
Documentation/staging/index.rst | 33 ++++++++++++++++++++++++++++++---
1 file changed, 30 insertions(+), 3 deletions(-)
diff --git a/Documentation/staging/index.rst b/Documentation/staging/index.rst
index 8e98517675ca..184e6aece0a7 100644
--- a/Documentation/staging/index.rst
+++ b/Documentation/staging/index.rst
@@ -19,14 +19,41 @@ Unsorted Documentation
Atomic Types
============
-.. literalinclude:: ../atomic_t.txt
+.. raw:: latex
+
+ \footnotesize
+
+.. include:: ../atomic_t.txt
+ :literal:
+
+.. raw:: latex
+
+ \normalsize
Atomic bitops
=============
-.. literalinclude:: ../atomic_bitops.txt
+.. raw:: latex
+
+ \footnotesize
+
+.. include:: ../atomic_bitops.txt
+ :literal:
+
+.. raw:: latex
+
+ \normalsize
Memory Barriers
===============
-.. literalinclude:: ../memory-barriers.txt
+.. raw:: latex
+
+ \footnotesize
+
+.. include:: ../memory-barriers.txt
+ :literal:
+
+.. raw:: latex
+
+ \normalsize
--
2.26.2
^ permalink raw reply related [flat|nested] 7+ messages in thread