* [PATCH v4 51/63] Documentation: x86: convert pti.txt to reST
From: Changbin Du @ 2019-04-23 16:29 UTC (permalink / raw)
To: Jonathan Corbet
Cc: fenghua.yu, mchehab+samsung, linux-doc, linux-pci, linux-gpio,
x86, rjw, linux-kernel, linux-acpi, mingo, Bjorn Helgaas, tglx,
linuxppc-dev, Changbin Du
In-Reply-To: <20190423162932.21428-1-changbin.du@gmail.com>
This converts the plain text documentation to reStructuredText format and
add it to Sphinx TOC tree. No essential content change.
Signed-off-by: Changbin Du <changbin.du@gmail.com>
---
Documentation/x86/index.rst | 1 +
Documentation/x86/{pti.txt => pti.rst} | 19 ++++++++++++++-----
2 files changed, 15 insertions(+), 5 deletions(-)
rename Documentation/x86/{pti.txt => pti.rst} (95%)
diff --git a/Documentation/x86/index.rst b/Documentation/x86/index.rst
index a0426ab156bd..1c675cef14d7 100644
--- a/Documentation/x86/index.rst
+++ b/Documentation/x86/index.rst
@@ -21,3 +21,4 @@ Linux x86 Support
protection-keys
intel_mpx
amd-memory-encryption
+ pti
diff --git a/Documentation/x86/pti.txt b/Documentation/x86/pti.rst
similarity index 95%
rename from Documentation/x86/pti.txt
rename to Documentation/x86/pti.rst
index 5cd58439ad2d..44b98f99ca8a 100644
--- a/Documentation/x86/pti.txt
+++ b/Documentation/x86/pti.rst
@@ -1,9 +1,15 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+==========================
+Page Table Isolation (PTI)
+==========================
+
Overview
========
-Page Table Isolation (pti, previously known as KAISER[1]) is a
+Page Table Isolation (pti, previously known as KAISER [1]_) is a
countermeasure against attacks on the shared user/kernel address
-space such as the "Meltdown" approach[2].
+space such as the "Meltdown" approach [2]_.
To mitigate this class of attacks, we create an independent set of
page tables for use only when running userspace applications. When
@@ -60,6 +66,7 @@ Protection against side-channel attacks is important. But,
this protection comes at a cost:
1. Increased Memory Use
+
a. Each process now needs an order-1 PGD instead of order-0.
(Consumes an additional 4k per process).
b. The 'cpu_entry_area' structure must be 2MB in size and 2MB
@@ -68,6 +75,7 @@ this protection comes at a cost:
is decompressed, but no space in the kernel image itself.
2. Runtime Cost
+
a. CR3 manipulation to switch between the page table copies
must be done at interrupt, syscall, and exception entry
and exit (it can be skipped when the kernel is interrupted,
@@ -142,8 +150,9 @@ ideally doing all of these in parallel:
interrupted, including nested NMIs. Using "-c" boosts the rate of
NMIs, and using two -c with separate counters encourages nested NMIs
and less deterministic behavior.
+ ::
- while true; do perf record -c 10000 -e instructions,cycles -a sleep 10; done
+ while true; do perf record -c 10000 -e instructions,cycles -a sleep 10; done
4. Launch a KVM virtual machine.
5. Run 32-bit binaries on systems supporting the SYSCALL instruction.
@@ -182,5 +191,5 @@ that are worth noting here.
tended to be TLB invalidation issues. Usually invalidating
the wrong PCID, or otherwise missing an invalidation.
-1. https://gruss.cc/files/kaiser.pdf
-2. https://meltdownattack.com/meltdown.pdf
+.. [1] https://gruss.cc/files/kaiser.pdf
+.. [2] https://meltdownattack.com/meltdown.pdf
--
2.20.1
^ permalink raw reply related
* [PATCH v4 52/63] Documentation: x86: convert microcode.txt to reST
From: Changbin Du @ 2019-04-23 16:29 UTC (permalink / raw)
To: Jonathan Corbet
Cc: fenghua.yu, mchehab+samsung, linux-doc, linux-pci, linux-gpio,
x86, rjw, linux-kernel, linux-acpi, mingo, Bjorn Helgaas, tglx,
linuxppc-dev, Changbin Du
In-Reply-To: <20190423162932.21428-1-changbin.du@gmail.com>
This converts the plain text documentation to reStructuredText format and
add it to Sphinx TOC tree. No essential content change.
Signed-off-by: Changbin Du <changbin.du@gmail.com>
---
Documentation/x86/index.rst | 1 +
.../x86/{microcode.txt => microcode.rst} | 62 ++++++++++---------
2 files changed, 35 insertions(+), 28 deletions(-)
rename Documentation/x86/{microcode.txt => microcode.rst} (81%)
diff --git a/Documentation/x86/index.rst b/Documentation/x86/index.rst
index 1c675cef14d7..2fcd10f29b87 100644
--- a/Documentation/x86/index.rst
+++ b/Documentation/x86/index.rst
@@ -22,3 +22,4 @@ Linux x86 Support
intel_mpx
amd-memory-encryption
pti
+ microcode
diff --git a/Documentation/x86/microcode.txt b/Documentation/x86/microcode.rst
similarity index 81%
rename from Documentation/x86/microcode.txt
rename to Documentation/x86/microcode.rst
index 79fdb4a8148a..a320d37982ed 100644
--- a/Documentation/x86/microcode.txt
+++ b/Documentation/x86/microcode.rst
@@ -1,7 +1,11 @@
- The Linux Microcode Loader
+.. SPDX-License-Identifier: GPL-2.0
-Authors: Fenghua Yu <fenghua.yu@intel.com>
- Borislav Petkov <bp@suse.de>
+==========================
+The Linux Microcode Loader
+==========================
+
+:Authors: - Fenghua Yu <fenghua.yu@intel.com>
+ - Borislav Petkov <bp@suse.de>
The kernel has a x86 microcode loading facility which is supposed to
provide microcode loading methods in the OS. Potential use cases are
@@ -10,8 +14,8 @@ and updating the microcode on long-running systems without rebooting.
The loader supports three loading methods:
-1. Early load microcode
-=======================
+Early load microcode
+====================
The kernel can update microcode very early during boot. Loading
microcode early can fix CPU issues before they are observed during
@@ -26,8 +30,10 @@ loader parses the combined initrd image during boot.
The microcode files in cpio name space are:
-on Intel: kernel/x86/microcode/GenuineIntel.bin
-on AMD : kernel/x86/microcode/AuthenticAMD.bin
+on Intel:
+ kernel/x86/microcode/GenuineIntel.bin
+on AMD :
+ kernel/x86/microcode/AuthenticAMD.bin
During BSP (BootStrapping Processor) boot (pre-SMP), the kernel
scans the microcode file in the initrd. If microcode matching the
@@ -42,8 +48,8 @@ Here's a crude example how to prepare an initrd with microcode (this is
normally done automatically by the distribution, when recreating the
initrd, so you don't really have to do it yourself. It is documented
here for future reference only).
+::
----
#!/bin/bash
if [ -z "$1" ]; then
@@ -76,15 +82,15 @@ here for future reference only).
cat ucode.cpio $INITRD.orig > $INITRD
rm -rf $TMPDIR
----
+
The system needs to have the microcode packages installed into
/lib/firmware or you need to fixup the paths above if yours are
somewhere else and/or you've downloaded them directly from the processor
vendor's site.
-2. Late loading
-===============
+Late loading
+============
There are two legacy user space interfaces to load microcode, either through
/dev/cpu/microcode or through /sys/devices/system/cpu/microcode/reload file
@@ -94,9 +100,9 @@ The /dev/cpu/microcode method is deprecated because it needs a special
userspace tool for that.
The easier method is simply installing the microcode packages your distro
-supplies and running:
+supplies and running::
-# echo 1 > /sys/devices/system/cpu/microcode/reload
+ # echo 1 > /sys/devices/system/cpu/microcode/reload
as root.
@@ -104,29 +110,29 @@ The loading mechanism looks for microcode blobs in
/lib/firmware/{intel-ucode,amd-ucode}. The default distro installation
packages already put them there.
-3. Builtin microcode
-====================
+Builtin microcode
+=================
The loader supports also loading of a builtin microcode supplied through
the regular builtin firmware method CONFIG_EXTRA_FIRMWARE. Only 64-bit is
currently supported.
-Here's an example:
+Here's an example::
-CONFIG_EXTRA_FIRMWARE="intel-ucode/06-3a-09 amd-ucode/microcode_amd_fam15h.bin"
-CONFIG_EXTRA_FIRMWARE_DIR="/lib/firmware"
+ CONFIG_EXTRA_FIRMWARE="intel-ucode/06-3a-09 amd-ucode/microcode_amd_fam15h.bin"
+ CONFIG_EXTRA_FIRMWARE_DIR="/lib/firmware"
-This basically means, you have the following tree structure locally:
+This basically means, you have the following tree structure locally::
-/lib/firmware/
-|-- amd-ucode
-...
-| |-- microcode_amd_fam15h.bin
-...
-|-- intel-ucode
-...
-| |-- 06-3a-09
-...
+ /lib/firmware/
+ |-- amd-ucode
+ ...
+ | |-- microcode_amd_fam15h.bin
+ ...
+ |-- intel-ucode
+ ...
+ | |-- 06-3a-09
+ ...
so that the build system can find those files and integrate them into
the final kernel image. The early loader finds them and applies them.
--
2.20.1
^ permalink raw reply related
* [PATCH v4 53/63] Documentation: x86: convert resctrl_ui.txt to reST
From: Changbin Du @ 2019-04-23 16:29 UTC (permalink / raw)
To: Jonathan Corbet
Cc: fenghua.yu, mchehab+samsung, linux-doc, linux-pci, linux-gpio,
x86, rjw, linux-kernel, linux-acpi, mingo, Bjorn Helgaas, tglx,
linuxppc-dev, Changbin Du
In-Reply-To: <20190423162932.21428-1-changbin.du@gmail.com>
This converts the plain text documentation to reStructuredText format and
add it to Sphinx TOC tree. No essential content change.
Signed-off-by: Changbin Du <changbin.du@gmail.com>
---
Documentation/x86/index.rst | 1 +
.../x86/{resctrl_ui.txt => resctrl_ui.rst} | 913 ++++++++++--------
2 files changed, 490 insertions(+), 424 deletions(-)
rename Documentation/x86/{resctrl_ui.txt => resctrl_ui.rst} (68%)
diff --git a/Documentation/x86/index.rst b/Documentation/x86/index.rst
index 2fcd10f29b87..4e9fa2b046df 100644
--- a/Documentation/x86/index.rst
+++ b/Documentation/x86/index.rst
@@ -23,3 +23,4 @@ Linux x86 Support
amd-memory-encryption
pti
microcode
+ resctrl_ui
diff --git a/Documentation/x86/resctrl_ui.txt b/Documentation/x86/resctrl_ui.rst
similarity index 68%
rename from Documentation/x86/resctrl_ui.txt
rename to Documentation/x86/resctrl_ui.rst
index c1f95b59e14d..81aaa271d5ea 100644
--- a/Documentation/x86/resctrl_ui.txt
+++ b/Documentation/x86/resctrl_ui.rst
@@ -1,33 +1,39 @@
+.. SPDX-License-Identifier: GPL-2.0
+.. include:: <isonum.txt>
+
+===========================================
User Interface for Resource Control feature
+===========================================
-Intel refers to this feature as Intel Resource Director Technology(Intel(R) RDT).
-AMD refers to this feature as AMD Platform Quality of Service(AMD QoS).
+:Copyright: |copy| 2016 Intel Corporation
+:Authors: - Fenghua Yu <fenghua.yu@intel.com>
+ - Tony Luck <tony.luck@intel.com>
+ - Vikas Shivappa <vikas.shivappa@intel.com>
-Copyright (C) 2016 Intel Corporation
-Fenghua Yu <fenghua.yu@intel.com>
-Tony Luck <tony.luck@intel.com>
-Vikas Shivappa <vikas.shivappa@intel.com>
+Intel refers to this feature as Intel Resource Director Technology(Intel(R) RDT).
+AMD refers to this feature as AMD Platform Quality of Service(AMD QoS).
This feature is enabled by the CONFIG_X86_CPU_RESCTRL and the x86 /proc/cpuinfo
-flag bits:
-RDT (Resource Director Technology) Allocation - "rdt_a"
-CAT (Cache Allocation Technology) - "cat_l3", "cat_l2"
-CDP (Code and Data Prioritization ) - "cdp_l3", "cdp_l2"
-CQM (Cache QoS Monitoring) - "cqm_llc", "cqm_occup_llc"
-MBM (Memory Bandwidth Monitoring) - "cqm_mbm_total", "cqm_mbm_local"
-MBA (Memory Bandwidth Allocation) - "mba"
+flag bits::
+
+ RDT (Resource Director Technology) Allocation - "rdt_a"
+ CAT (Cache Allocation Technology) - "cat_l3", "cat_l2"
+ CDP (Code and Data Prioritization ) - "cdp_l3", "cdp_l2"
+ CQM (Cache QoS Monitoring) - "cqm_llc", "cqm_occup_llc"
+ MBM (Memory Bandwidth Monitoring) - "cqm_mbm_total", "cqm_mbm_local"
+ MBA (Memory Bandwidth Allocation) - "mba"
-To use the feature mount the file system:
+To use the feature mount the file system::
# mount -t resctrl resctrl [-o cdp[,cdpl2][,mba_MBps]] /sys/fs/resctrl
mount options are:
-"cdp": Enable code/data prioritization in L3 cache allocations.
-"cdpl2": Enable code/data prioritization in L2 cache allocations.
-"mba_MBps": Enable the MBA Software Controller(mba_sc) to specify MBA
- bandwidth in MBps
+* "cdp": Enable code/data prioritization in L3 cache allocations.
+* "cdpl2": Enable code/data prioritization in L2 cache allocations.
+* "mba_MBps": Enable the MBA Software Controller(mba_sc) to specify MBA
+ bandwidth in MBps
L2 and L3 CDP are controlled seperately.
@@ -44,7 +50,7 @@ For more details on the behavior of the interface during monitoring
and allocation, see the "Resource alloc and monitor groups" section.
Info directory
---------------
+==============
The 'info' directory contains information about the enabled
resources. Each resource has its own subdirectory. The subdirectory
@@ -56,77 +62,93 @@ allocation:
Cache resource(L3/L2) subdirectory contains the following files
related to allocation:
-"num_closids": The number of CLOSIDs which are valid for this
- resource. The kernel uses the smallest number of
- CLOSIDs of all enabled resources as limit.
-
-"cbm_mask": The bitmask which is valid for this resource.
- This mask is equivalent to 100%.
-
-"min_cbm_bits": The minimum number of consecutive bits which
- must be set when writing a mask.
-
-"shareable_bits": Bitmask of shareable resource with other executing
- entities (e.g. I/O). User can use this when
- setting up exclusive cache partitions. Note that
- some platforms support devices that have their
- own settings for cache use which can over-ride
- these bits.
-"bit_usage": Annotated capacity bitmasks showing how all
- instances of the resource are used. The legend is:
- "0" - Corresponding region is unused. When the system's
+"num_closids":
+ The number of CLOSIDs which are valid for this
+ resource. The kernel uses the smallest number of
+ CLOSIDs of all enabled resources as limit.
+"cbm_mask":
+ The bitmask which is valid for this resource.
+ This mask is equivalent to 100%.
+"min_cbm_bits":
+ The minimum number of consecutive bits which
+ must be set when writing a mask.
+
+"shareable_bits":
+ Bitmask of shareable resource with other executing
+ entities (e.g. I/O). User can use this when
+ setting up exclusive cache partitions. Note that
+ some platforms support devices that have their
+ own settings for cache use which can over-ride
+ these bits.
+"bit_usage":
+ Annotated capacity bitmasks showing how all
+ instances of the resource are used. The legend is:
+
+ "0":
+ Corresponding region is unused. When the system's
resources have been allocated and a "0" is found
in "bit_usage" it is a sign that resources are
wasted.
- "H" - Corresponding region is used by hardware only
+
+ "H":
+ Corresponding region is used by hardware only
but available for software use. If a resource
has bits set in "shareable_bits" but not all
of these bits appear in the resource groups'
schematas then the bits appearing in
"shareable_bits" but no resource group will
be marked as "H".
- "X" - Corresponding region is available for sharing and
+ "X":
+ Corresponding region is available for sharing and
used by hardware and software. These are the
bits that appear in "shareable_bits" as
well as a resource group's allocation.
- "S" - Corresponding region is used by software
+ "S":
+ Corresponding region is used by software
and available for sharing.
- "E" - Corresponding region is used exclusively by
+ "E":
+ Corresponding region is used exclusively by
one resource group. No sharing allowed.
- "P" - Corresponding region is pseudo-locked. No
+ "P":
+ Corresponding region is pseudo-locked. No
sharing allowed.
Memory bandwitdh(MB) subdirectory contains the following files
with respect to allocation:
-"min_bandwidth": The minimum memory bandwidth percentage which
- user can request.
+"min_bandwidth":
+ The minimum memory bandwidth percentage which
+ user can request.
-"bandwidth_gran": The granularity in which the memory bandwidth
- percentage is allocated. The allocated
- b/w percentage is rounded off to the next
- control step available on the hardware. The
- available bandwidth control steps are:
- min_bandwidth + N * bandwidth_gran.
+"bandwidth_gran":
+ The granularity in which the memory bandwidth
+ percentage is allocated. The allocated
+ b/w percentage is rounded off to the next
+ control step available on the hardware. The
+ available bandwidth control steps are:
+ min_bandwidth + N * bandwidth_gran.
-"delay_linear": Indicates if the delay scale is linear or
- non-linear. This field is purely informational
- only.
+"delay_linear":
+ Indicates if the delay scale is linear or
+ non-linear. This field is purely informational
+ only.
If RDT monitoring is available there will be an "L3_MON" directory
with the following files:
-"num_rmids": The number of RMIDs available. This is the
- upper bound for how many "CTRL_MON" + "MON"
- groups can be created.
+"num_rmids":
+ The number of RMIDs available. This is the
+ upper bound for how many "CTRL_MON" + "MON"
+ groups can be created.
-"mon_features": Lists the monitoring events if
- monitoring is enabled for the resource.
+"mon_features":
+ Lists the monitoring events if
+ monitoring is enabled for the resource.
"max_threshold_occupancy":
- Read/write file provides the largest value (in
- bytes) at which a previously used LLC_occupancy
- counter can be considered for re-use.
+ Read/write file provides the largest value (in
+ bytes) at which a previously used LLC_occupancy
+ counter can be considered for re-use.
Finally, in the top level of the "info" directory there is a file
named "last_cmd_status". This is reset with every "command" issued
@@ -134,6 +156,7 @@ via the file system (making new directories or writing to any of the
control files). If the command was successful, it will read as "ok".
If the command failed, it will provide more information that can be
conveyed in the error returns from file operations. E.g.
+::
# echo L3:0=f7 > schemata
bash: echo: write error: Invalid argument
@@ -141,7 +164,7 @@ conveyed in the error returns from file operations. E.g.
mask f7 has non-consecutive 1-bits
Resource alloc and monitor groups
----------------------------------
+=================================
Resource groups are represented as directories in the resctrl file
system. The default group is the root directory which, immediately
@@ -226,6 +249,7 @@ When monitoring is enabled all MON groups will also contain:
Resource allocation rules
-------------------------
+
When a task is running the following rules define which resources are
available to it:
@@ -252,7 +276,7 @@ Resource monitoring rules
Notes on cache occupancy monitoring and control
------------------------------------------------
+===============================================
When moving a task from one group to another you should remember that
this only affects *new* cache allocations by the task. E.g. you may have
a task in a monitor group showing 3 MB of cache occupancy. If you move
@@ -321,7 +345,7 @@ of the capacity of the cache. You could partition the cache into four
equal parts with masks: 0x1f, 0x3e0, 0x7c00, 0xf8000.
Memory bandwidth Allocation and monitoring
-------------------------------------------
+==========================================
For Memory bandwidth resource, by default the user controls the resource
by indicating the percentage of total memory bandwidth.
@@ -369,7 +393,7 @@ In order to mitigate this and make the interface more user friendly,
resctrl added support for specifying the bandwidth in MBps as well. The
kernel underneath would use a software feedback mechanism or a "Software
Controller(mba_sc)" which reads the actual bandwidth using MBM counters
-and adjust the memowy bandwidth percentages to ensure
+and adjust the memowy bandwidth percentages to ensure::
"actual bandwidth < user specified bandwidth".
@@ -380,14 +404,14 @@ sections.
L3 schemata file details (code and data prioritization disabled)
----------------------------------------------------------------
-With CDP disabled the L3 schemata format is:
+With CDP disabled the L3 schemata format is::
L3:<cache_id0>=<cbm>;<cache_id1>=<cbm>;...
L3 schemata file details (CDP enabled via mount option to resctrl)
------------------------------------------------------------------
When CDP is enabled L3 control is split into two separate resources
-so you can specify independent masks for code and data like this:
+so you can specify independent masks for code and data like this::
L3data:<cache_id0>=<cbm>;<cache_id1>=<cbm>;...
L3code:<cache_id0>=<cbm>;<cache_id1>=<cbm>;...
@@ -395,7 +419,7 @@ so you can specify independent masks for code and data like this:
L2 schemata file details
------------------------
L2 cache does not support code and data prioritization, so the
-schemata format is always:
+schemata format is always::
L2:<cache_id0>=<cbm>;<cache_id1>=<cbm>;...
@@ -403,6 +427,7 @@ Memory bandwidth Allocation (default mode)
------------------------------------------
Memory b/w domain is L3 cache.
+::
MB:<cache_id0>=bandwidth0;<cache_id1>=bandwidth1;...
@@ -410,6 +435,7 @@ Memory bandwidth Allocation specified in MBps
---------------------------------------------
Memory bandwidth domain is L3 cache.
+::
MB:<cache_id0>=bw_MBps0;<cache_id1>=bw_MBps1;...
@@ -418,17 +444,18 @@ Reading/writing the schemata file
Reading the schemata file will show the state of all resources
on all domains. When writing you only need to specify those values
which you wish to change. E.g.
+::
-# cat schemata
-L3DATA:0=fffff;1=fffff;2=fffff;3=fffff
-L3CODE:0=fffff;1=fffff;2=fffff;3=fffff
-# echo "L3DATA:2=3c0;" > schemata
-# cat schemata
-L3DATA:0=fffff;1=fffff;2=3c0;3=fffff
-L3CODE:0=fffff;1=fffff;2=fffff;3=fffff
+ # cat schemata
+ L3DATA:0=fffff;1=fffff;2=fffff;3=fffff
+ L3CODE:0=fffff;1=fffff;2=fffff;3=fffff
+ # echo "L3DATA:2=3c0;" > schemata
+ # cat schemata
+ L3DATA:0=fffff;1=fffff;2=3c0;3=fffff
+ L3CODE:0=fffff;1=fffff;2=fffff;3=fffff
Cache Pseudo-Locking
---------------------
+====================
CAT enables a user to specify the amount of cache space that an
application can fill. Cache pseudo-locking builds on the fact that a
CPU can still read and write data pre-allocated outside its current
@@ -442,6 +469,7 @@ a region of memory with reduced average read latency.
The creation of a cache pseudo-locked region is triggered by a request
from the user to do so that is accompanied by a schemata of the region
to be pseudo-locked. The cache pseudo-locked region is created as follows:
+
- Create a CAT allocation CLOSNEW with a CBM matching the schemata
from the user of the cache region that will contain the pseudo-locked
memory. This region must not overlap with any current CAT allocation/CLOS
@@ -480,6 +508,7 @@ initial mmap() handling, there is no enforcement afterwards and the
application self needs to ensure it remains affine to the correct cores.
Pseudo-locking is accomplished in two stages:
+
1) During the first stage the system administrator allocates a portion
of cache that should be dedicated to pseudo-locking. At this time an
equivalent portion of memory is allocated, loaded into allocated
@@ -506,7 +535,7 @@ by user space in order to obtain access to the pseudo-locked memory region.
An example of cache pseudo-locked region creation and usage can be found below.
Cache Pseudo-Locking Debugging Interface
----------------------------------------
+----------------------------------------
The pseudo-locking debugging interface is enabled by default (if
CONFIG_DEBUG_FS is enabled) and can be found in /sys/kernel/debug/resctrl.
@@ -514,6 +543,7 @@ There is no explicit way for the kernel to test if a provided memory
location is present in the cache. The pseudo-locking debugging interface uses
the tracing infrastructure to provide two ways to measure cache residency of
the pseudo-locked region:
+
1) Memory access latency using the pseudo_lock_mem_latency tracepoint. Data
from these measurements are best visualized using a hist trigger (see
example below). In this test the pseudo-locked region is traversed at
@@ -529,87 +559,97 @@ it in debugfs as /sys/kernel/debug/resctrl/<newdir>. A single
write-only file, pseudo_lock_measure, is present in this directory. The
measurement of the pseudo-locked region depends on the number written to this
debugfs file:
-1 - writing "1" to the pseudo_lock_measure file will trigger the latency
+
+1:
+ writing "1" to the pseudo_lock_measure file will trigger the latency
measurement captured in the pseudo_lock_mem_latency tracepoint. See
example below.
-2 - writing "2" to the pseudo_lock_measure file will trigger the L2 cache
+2:
+ writing "2" to the pseudo_lock_measure file will trigger the L2 cache
residency (cache hits and misses) measurement captured in the
pseudo_lock_l2 tracepoint. See example below.
-3 - writing "3" to the pseudo_lock_measure file will trigger the L3 cache
+3:
+ writing "3" to the pseudo_lock_measure file will trigger the L3 cache
residency (cache hits and misses) measurement captured in the
pseudo_lock_l3 tracepoint.
All measurements are recorded with the tracing infrastructure. This requires
the relevant tracepoints to be enabled before the measurement is triggered.
-Example of latency debugging interface:
+Example of latency debugging interface
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
In this example a pseudo-locked region named "newlock" was created. Here is
how we can measure the latency in cycles of reading from this region and
visualize this data with a histogram that is available if CONFIG_HIST_TRIGGERS
-is set:
-# :> /sys/kernel/debug/tracing/trace
-# echo 'hist:keys=latency' > /sys/kernel/debug/tracing/events/resctrl/pseudo_lock_mem_latency/trigger
-# echo 1 > /sys/kernel/debug/tracing/events/resctrl/pseudo_lock_mem_latency/enable
-# echo 1 > /sys/kernel/debug/resctrl/newlock/pseudo_lock_measure
-# echo 0 > /sys/kernel/debug/tracing/events/resctrl/pseudo_lock_mem_latency/enable
-# cat /sys/kernel/debug/tracing/events/resctrl/pseudo_lock_mem_latency/hist
-
-# event histogram
-#
-# trigger info: hist:keys=latency:vals=hitcount:sort=hitcount:size=2048 [active]
-#
-
-{ latency: 456 } hitcount: 1
-{ latency: 50 } hitcount: 83
-{ latency: 36 } hitcount: 96
-{ latency: 44 } hitcount: 174
-{ latency: 48 } hitcount: 195
-{ latency: 46 } hitcount: 262
-{ latency: 42 } hitcount: 693
-{ latency: 40 } hitcount: 3204
-{ latency: 38 } hitcount: 3484
-
-Totals:
- Hits: 8192
- Entries: 9
- Dropped: 0
-
-Example of cache hits/misses debugging:
+is set::
+
+ # :> /sys/kernel/debug/tracing/trace
+ # echo 'hist:keys=latency' > /sys/kernel/debug/tracing/events/resctrl/pseudo_lock_mem_latency/trigger
+ # echo 1 > /sys/kernel/debug/tracing/events/resctrl/pseudo_lock_mem_latency/enable
+ # echo 1 > /sys/kernel/debug/resctrl/newlock/pseudo_lock_measure
+ # echo 0 > /sys/kernel/debug/tracing/events/resctrl/pseudo_lock_mem_latency/enable
+ # cat /sys/kernel/debug/tracing/events/resctrl/pseudo_lock_mem_latency/hist
+
+ # event histogram
+ #
+ # trigger info: hist:keys=latency:vals=hitcount:sort=hitcount:size=2048 [active]
+ #
+
+ { latency: 456 } hitcount: 1
+ { latency: 50 } hitcount: 83
+ { latency: 36 } hitcount: 96
+ { latency: 44 } hitcount: 174
+ { latency: 48 } hitcount: 195
+ { latency: 46 } hitcount: 262
+ { latency: 42 } hitcount: 693
+ { latency: 40 } hitcount: 3204
+ { latency: 38 } hitcount: 3484
+
+ Totals:
+ Hits: 8192
+ Entries: 9
+ Dropped: 0
+
+Example of cache hits/misses debugging
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
In this example a pseudo-locked region named "newlock" was created on the L2
cache of a platform. Here is how we can obtain details of the cache hits
and misses using the platform's precision counters.
+::
-# :> /sys/kernel/debug/tracing/trace
-# echo 1 > /sys/kernel/debug/tracing/events/resctrl/pseudo_lock_l2/enable
-# echo 2 > /sys/kernel/debug/resctrl/newlock/pseudo_lock_measure
-# echo 0 > /sys/kernel/debug/tracing/events/resctrl/pseudo_lock_l2/enable
-# cat /sys/kernel/debug/tracing/trace
+ # :> /sys/kernel/debug/tracing/trace
+ # echo 1 > /sys/kernel/debug/tracing/events/resctrl/pseudo_lock_l2/enable
+ # echo 2 > /sys/kernel/debug/resctrl/newlock/pseudo_lock_measure
+ # echo 0 > /sys/kernel/debug/tracing/events/resctrl/pseudo_lock_l2/enable
+ # cat /sys/kernel/debug/tracing/trace
-# tracer: nop
-#
-# _-----=> irqs-off
-# / _----=> need-resched
-# | / _---=> hardirq/softirq
-# || / _--=> preempt-depth
-# ||| / delay
-# TASK-PID CPU# |||| TIMESTAMP FUNCTION
-# | | | |||| | |
- pseudo_lock_mea-1672 [002] .... 3132.860500: pseudo_lock_l2: hits=4097 miss=0
+ # tracer: nop
+ #
+ # _-----=> irqs-off
+ # / _----=> need-resched
+ # | / _---=> hardirq/softirq
+ # || / _--=> preempt-depth
+ # ||| / delay
+ # TASK-PID CPU# |||| TIMESTAMP FUNCTION
+ # | | | |||| | |
+ pseudo_lock_mea-1672 [002] .... 3132.860500: pseudo_lock_l2: hits=4097 miss=0
-Examples for RDT allocation usage:
+Examples for RDT allocation usage
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+1) Example 1
-Example 1
----------
On a two socket machine (one L3 cache per socket) with just four bits
for cache bit masks, minimum b/w of 10% with a memory bandwidth
-granularity of 10%
+granularity of 10%.
+::
-# mount -t resctrl resctrl /sys/fs/resctrl
-# cd /sys/fs/resctrl
-# mkdir p0 p1
-# echo "L3:0=3;1=c\nMB:0=50;1=50" > /sys/fs/resctrl/p0/schemata
-# echo "L3:0=3;1=3\nMB:0=50;1=50" > /sys/fs/resctrl/p1/schemata
+ # mount -t resctrl resctrl /sys/fs/resctrl
+ # cd /sys/fs/resctrl
+ # mkdir p0 p1
+ # echo "L3:0=3;1=c\nMB:0=50;1=50" > /sys/fs/resctrl/p0/schemata
+ # echo "L3:0=3;1=3\nMB:0=50;1=50" > /sys/fs/resctrl/p1/schemata
The default resource group is unmodified, so we have access to all parts
of all caches (its schemata file reads "L3:0=f;1=f").
@@ -628,100 +668,106 @@ the b/w accordingly.
If the MBA is specified in MB(megabytes) then user can enter the max b/w in MB
rather than the percentage values.
+::
-# echo "L3:0=3;1=c\nMB:0=1024;1=500" > /sys/fs/resctrl/p0/schemata
-# echo "L3:0=3;1=3\nMB:0=1024;1=500" > /sys/fs/resctrl/p1/schemata
+ # echo "L3:0=3;1=c\nMB:0=1024;1=500" > /sys/fs/resctrl/p0/schemata
+ # echo "L3:0=3;1=3\nMB:0=1024;1=500" > /sys/fs/resctrl/p1/schemata
In the above example the tasks in "p1" and "p0" on socket 0 would use a max b/w
of 1024MB where as on socket 1 they would use 500MB.
-Example 2
----------
+2) Example 2
+
Again two sockets, but this time with a more realistic 20-bit mask.
Two real time tasks pid=1234 running on processor 0 and pid=5678 running on
processor 1 on socket 0 on a 2-socket and dual core machine. To avoid noisy
neighbors, each of the two real-time tasks exclusively occupies one quarter
of L3 cache on socket 0.
+::
-# mount -t resctrl resctrl /sys/fs/resctrl
-# cd /sys/fs/resctrl
+ # mount -t resctrl resctrl /sys/fs/resctrl
+ # cd /sys/fs/resctrl
First we reset the schemata for the default group so that the "upper"
50% of the L3 cache on socket 0 and 50% of memory b/w cannot be used by
-ordinary tasks:
+ordinary tasks::
-# echo "L3:0=3ff;1=fffff\nMB:0=50;1=100" > schemata
+ # echo "L3:0=3ff;1=fffff\nMB:0=50;1=100" > schemata
Next we make a resource group for our first real time task and give
it access to the "top" 25% of the cache on socket 0.
+::
-# mkdir p0
-# echo "L3:0=f8000;1=fffff" > p0/schemata
+ # mkdir p0
+ # echo "L3:0=f8000;1=fffff" > p0/schemata
Finally we move our first real time task into this resource group. We
also use taskset(1) to ensure the task always runs on a dedicated CPU
on socket 0. Most uses of resource groups will also constrain which
processors tasks run on.
+::
-# echo 1234 > p0/tasks
-# taskset -cp 1 1234
+ # echo 1234 > p0/tasks
+ # taskset -cp 1 1234
-Ditto for the second real time task (with the remaining 25% of cache):
+Ditto for the second real time task (with the remaining 25% of cache)::
-# mkdir p1
-# echo "L3:0=7c00;1=fffff" > p1/schemata
-# echo 5678 > p1/tasks
-# taskset -cp 2 5678
+ # mkdir p1
+ # echo "L3:0=7c00;1=fffff" > p1/schemata
+ # echo 5678 > p1/tasks
+ # taskset -cp 2 5678
For the same 2 socket system with memory b/w resource and CAT L3 the
schemata would look like(Assume min_bandwidth 10 and bandwidth_gran is
10):
-For our first real time task this would request 20% memory b/w on socket
-0.
+For our first real time task this would request 20% memory b/w on socket 0.
+::
-# echo -e "L3:0=f8000;1=fffff\nMB:0=20;1=100" > p0/schemata
+ # echo -e "L3:0=f8000;1=fffff\nMB:0=20;1=100" > p0/schemata
For our second real time task this would request an other 20% memory b/w
on socket 0.
+::
-# echo -e "L3:0=f8000;1=fffff\nMB:0=20;1=100" > p0/schemata
+ # echo -e "L3:0=f8000;1=fffff\nMB:0=20;1=100" > p0/schemata
-Example 3
----------
+3) Example 3
A single socket system which has real-time tasks running on core 4-7 and
non real-time workload assigned to core 0-3. The real-time tasks share text
and data, so a per task association is not required and due to interaction
with the kernel it's desired that the kernel on these cores shares L3 with
the tasks.
+::
-# mount -t resctrl resctrl /sys/fs/resctrl
-# cd /sys/fs/resctrl
+ # mount -t resctrl resctrl /sys/fs/resctrl
+ # cd /sys/fs/resctrl
First we reset the schemata for the default group so that the "upper"
50% of the L3 cache on socket 0, and 50% of memory bandwidth on socket 0
-cannot be used by ordinary tasks:
+cannot be used by ordinary tasks::
-# echo "L3:0=3ff\nMB:0=50" > schemata
+ # echo "L3:0=3ff\nMB:0=50" > schemata
Next we make a resource group for our real time cores and give it access
to the "top" 50% of the cache on socket 0 and 50% of memory bandwidth on
socket 0.
+::
-# mkdir p0
-# echo "L3:0=ffc00\nMB:0=50" > p0/schemata
+ # mkdir p0
+ # echo "L3:0=ffc00\nMB:0=50" > p0/schemata
Finally we move core 4-7 over to the new group and make sure that the
kernel and the tasks running there get 50% of the cache. They should
also get 50% of memory bandwidth assuming that the cores 4-7 are SMT
siblings and only the real time threads are scheduled on the cores 4-7.
+::
-# echo F0 > p0/cpus
+ # echo F0 > p0/cpus
-Example 4
----------
+4) Example 4
The resource groups in previous examples were all in the default "shareable"
mode allowing sharing of their cache allocations. If one resource group
@@ -732,157 +778,168 @@ In this example a new exclusive resource group will be created on a L2 CAT
system with two L2 cache instances that can be configured with an 8-bit
capacity bitmask. The new exclusive resource group will be configured to use
25% of each cache instance.
+::
-# mount -t resctrl resctrl /sys/fs/resctrl/
-# cd /sys/fs/resctrl
+ # mount -t resctrl resctrl /sys/fs/resctrl/
+ # cd /sys/fs/resctrl
First, we observe that the default group is configured to allocate to all L2
-cache:
+cache::
-# cat schemata
-L2:0=ff;1=ff
+ # cat schemata
+ L2:0=ff;1=ff
We could attempt to create the new resource group at this point, but it will
-fail because of the overlap with the schemata of the default group:
-# mkdir p0
-# echo 'L2:0=0x3;1=0x3' > p0/schemata
-# cat p0/mode
-shareable
-# echo exclusive > p0/mode
--sh: echo: write error: Invalid argument
-# cat info/last_cmd_status
-schemata overlaps
+fail because of the overlap with the schemata of the default group::
+
+ # mkdir p0
+ # echo 'L2:0=0x3;1=0x3' > p0/schemata
+ # cat p0/mode
+ shareable
+ # echo exclusive > p0/mode
+ -sh: echo: write error: Invalid argument
+ # cat info/last_cmd_status
+ schemata overlaps
To ensure that there is no overlap with another resource group the default
resource group's schemata has to change, making it possible for the new
resource group to become exclusive.
-# echo 'L2:0=0xfc;1=0xfc' > schemata
-# echo exclusive > p0/mode
-# grep . p0/*
-p0/cpus:0
-p0/mode:exclusive
-p0/schemata:L2:0=03;1=03
-p0/size:L2:0=262144;1=262144
+::
+
+ # echo 'L2:0=0xfc;1=0xfc' > schemata
+ # echo exclusive > p0/mode
+ # grep . p0/*
+ p0/cpus:0
+ p0/mode:exclusive
+ p0/schemata:L2:0=03;1=03
+ p0/size:L2:0=262144;1=262144
A new resource group will on creation not overlap with an exclusive resource
-group:
-# mkdir p1
-# grep . p1/*
-p1/cpus:0
-p1/mode:shareable
-p1/schemata:L2:0=fc;1=fc
-p1/size:L2:0=786432;1=786432
-
-The bit_usage will reflect how the cache is used:
-# cat info/L2/bit_usage
-0=SSSSSSEE;1=SSSSSSEE
-
-A resource group cannot be forced to overlap with an exclusive resource group:
-# echo 'L2:0=0x1;1=0x1' > p1/schemata
--sh: echo: write error: Invalid argument
-# cat info/last_cmd_status
-overlaps with exclusive group
+group::
+
+ # mkdir p1
+ # grep . p1/*
+ p1/cpus:0
+ p1/mode:shareable
+ p1/schemata:L2:0=fc;1=fc
+ p1/size:L2:0=786432;1=786432
+
+The bit_usage will reflect how the cache is used::
+
+ # cat info/L2/bit_usage
+ 0=SSSSSSEE;1=SSSSSSEE
+
+A resource group cannot be forced to overlap with an exclusive resource group::
+
+ # echo 'L2:0=0x1;1=0x1' > p1/schemata
+ -sh: echo: write error: Invalid argument
+ # cat info/last_cmd_status
+ overlaps with exclusive group
Example of Cache Pseudo-Locking
--------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Lock portion of L2 cache from cache id 1 using CBM 0x3. Pseudo-locked
region is exposed at /dev/pseudo_lock/newlock that can be provided to
application for argument to mmap().
+::
-# mount -t resctrl resctrl /sys/fs/resctrl/
-# cd /sys/fs/resctrl
+ # mount -t resctrl resctrl /sys/fs/resctrl/
+ # cd /sys/fs/resctrl
Ensure that there are bits available that can be pseudo-locked, since only
unused bits can be pseudo-locked the bits to be pseudo-locked needs to be
-removed from the default resource group's schemata:
-# cat info/L2/bit_usage
-0=SSSSSSSS;1=SSSSSSSS
-# echo 'L2:1=0xfc' > schemata
-# cat info/L2/bit_usage
-0=SSSSSSSS;1=SSSSSS00
+removed from the default resource group's schemata::
+
+ # cat info/L2/bit_usage
+ 0=SSSSSSSS;1=SSSSSSSS
+ # echo 'L2:1=0xfc' > schemata
+ # cat info/L2/bit_usage
+ 0=SSSSSSSS;1=SSSSSS00
Create a new resource group that will be associated with the pseudo-locked
region, indicate that it will be used for a pseudo-locked region, and
-configure the requested pseudo-locked region capacity bitmask:
+configure the requested pseudo-locked region capacity bitmask::
-# mkdir newlock
-# echo pseudo-locksetup > newlock/mode
-# echo 'L2:1=0x3' > newlock/schemata
+ # mkdir newlock
+ # echo pseudo-locksetup > newlock/mode
+ # echo 'L2:1=0x3' > newlock/schemata
On success the resource group's mode will change to pseudo-locked, the
bit_usage will reflect the pseudo-locked region, and the character device
-exposing the pseudo-locked region will exist:
-
-# cat newlock/mode
-pseudo-locked
-# cat info/L2/bit_usage
-0=SSSSSSSS;1=SSSSSSPP
-# ls -l /dev/pseudo_lock/newlock
-crw------- 1 root root 243, 0 Apr 3 05:01 /dev/pseudo_lock/newlock
-
-/*
- * Example code to access one page of pseudo-locked cache region
- * from user space.
- */
-#define _GNU_SOURCE
-#include <fcntl.h>
-#include <sched.h>
-#include <stdio.h>
-#include <stdlib.h>
-#include <unistd.h>
-#include <sys/mman.h>
-
-/*
- * It is required that the application runs with affinity to only
- * cores associated with the pseudo-locked region. Here the cpu
- * is hardcoded for convenience of example.
- */
-static int cpuid = 2;
-
-int main(int argc, char *argv[])
-{
- cpu_set_t cpuset;
- long page_size;
- void *mapping;
- int dev_fd;
- int ret;
-
- page_size = sysconf(_SC_PAGESIZE);
-
- CPU_ZERO(&cpuset);
- CPU_SET(cpuid, &cpuset);
- ret = sched_setaffinity(0, sizeof(cpuset), &cpuset);
- if (ret < 0) {
- perror("sched_setaffinity");
- exit(EXIT_FAILURE);
- }
-
- dev_fd = open("/dev/pseudo_lock/newlock", O_RDWR);
- if (dev_fd < 0) {
- perror("open");
- exit(EXIT_FAILURE);
- }
-
- mapping = mmap(0, page_size, PROT_READ | PROT_WRITE, MAP_SHARED,
- dev_fd, 0);
- if (mapping == MAP_FAILED) {
- perror("mmap");
- close(dev_fd);
- exit(EXIT_FAILURE);
- }
-
- /* Application interacts with pseudo-locked memory @mapping */
-
- ret = munmap(mapping, page_size);
- if (ret < 0) {
- perror("munmap");
- close(dev_fd);
- exit(EXIT_FAILURE);
- }
-
- close(dev_fd);
- exit(EXIT_SUCCESS);
-}
+exposing the pseudo-locked region will exist::
+
+ # cat newlock/mode
+ pseudo-locked
+ # cat info/L2/bit_usage
+ 0=SSSSSSSS;1=SSSSSSPP
+ # ls -l /dev/pseudo_lock/newlock
+ crw------- 1 root root 243, 0 Apr 3 05:01 /dev/pseudo_lock/newlock
+
+::
+
+ /*
+ * Example code to access one page of pseudo-locked cache region
+ * from user space.
+ */
+ #define _GNU_SOURCE
+ #include <fcntl.h>
+ #include <sched.h>
+ #include <stdio.h>
+ #include <stdlib.h>
+ #include <unistd.h>
+ #include <sys/mman.h>
+
+ /*
+ * It is required that the application runs with affinity to only
+ * cores associated with the pseudo-locked region. Here the cpu
+ * is hardcoded for convenience of example.
+ */
+ static int cpuid = 2;
+
+ int main(int argc, char *argv[])
+ {
+ cpu_set_t cpuset;
+ long page_size;
+ void *mapping;
+ int dev_fd;
+ int ret;
+
+ page_size = sysconf(_SC_PAGESIZE);
+
+ CPU_ZERO(&cpuset);
+ CPU_SET(cpuid, &cpuset);
+ ret = sched_setaffinity(0, sizeof(cpuset), &cpuset);
+ if (ret < 0) {
+ perror("sched_setaffinity");
+ exit(EXIT_FAILURE);
+ }
+
+ dev_fd = open("/dev/pseudo_lock/newlock", O_RDWR);
+ if (dev_fd < 0) {
+ perror("open");
+ exit(EXIT_FAILURE);
+ }
+
+ mapping = mmap(0, page_size, PROT_READ | PROT_WRITE, MAP_SHARED,
+ dev_fd, 0);
+ if (mapping == MAP_FAILED) {
+ perror("mmap");
+ close(dev_fd);
+ exit(EXIT_FAILURE);
+ }
+
+ /* Application interacts with pseudo-locked memory @mapping */
+
+ ret = munmap(mapping, page_size);
+ if (ret < 0) {
+ perror("munmap");
+ close(dev_fd);
+ exit(EXIT_FAILURE);
+ }
+
+ close(dev_fd);
+ exit(EXIT_SUCCESS);
+ }
Locking between applications
----------------------------
@@ -921,86 +978,86 @@ Read lock:
B) If success read the directory structure.
C) funlock
-Example with bash:
-
-# Atomically read directory structure
-$ flock -s /sys/fs/resctrl/ find /sys/fs/resctrl
-
-# Read directory contents and create new subdirectory
-
-$ cat create-dir.sh
-find /sys/fs/resctrl/ > output.txt
-mask = function-of(output.txt)
-mkdir /sys/fs/resctrl/newres/
-echo mask > /sys/fs/resctrl/newres/schemata
-
-$ flock /sys/fs/resctrl/ ./create-dir.sh
-
-Example with C:
-
-/*
- * Example code do take advisory locks
- * before accessing resctrl filesystem
- */
-#include <sys/file.h>
-#include <stdlib.h>
-
-void resctrl_take_shared_lock(int fd)
-{
- int ret;
-
- /* take shared lock on resctrl filesystem */
- ret = flock(fd, LOCK_SH);
- if (ret) {
- perror("flock");
- exit(-1);
- }
-}
-
-void resctrl_take_exclusive_lock(int fd)
-{
- int ret;
-
- /* release lock on resctrl filesystem */
- ret = flock(fd, LOCK_EX);
- if (ret) {
- perror("flock");
- exit(-1);
- }
-}
-
-void resctrl_release_lock(int fd)
-{
- int ret;
-
- /* take shared lock on resctrl filesystem */
- ret = flock(fd, LOCK_UN);
- if (ret) {
- perror("flock");
- exit(-1);
- }
-}
-
-void main(void)
-{
- int fd, ret;
-
- fd = open("/sys/fs/resctrl", O_DIRECTORY);
- if (fd == -1) {
- perror("open");
- exit(-1);
- }
- resctrl_take_shared_lock(fd);
- /* code to read directory contents */
- resctrl_release_lock(fd);
-
- resctrl_take_exclusive_lock(fd);
- /* code to read and write directory contents */
- resctrl_release_lock(fd);
-}
-
-Examples for RDT Monitoring along with allocation usage:
-
+Example with bash::
+
+ # Atomically read directory structure
+ $ flock -s /sys/fs/resctrl/ find /sys/fs/resctrl
+
+ # Read directory contents and create new subdirectory
+
+ $ cat create-dir.sh
+ find /sys/fs/resctrl/ > output.txt
+ mask = function-of(output.txt)
+ mkdir /sys/fs/resctrl/newres/
+ echo mask > /sys/fs/resctrl/newres/schemata
+
+ $ flock /sys/fs/resctrl/ ./create-dir.sh
+
+Example with C::
+
+ /*
+ * Example code do take advisory locks
+ * before accessing resctrl filesystem
+ */
+ #include <sys/file.h>
+ #include <stdlib.h>
+
+ void resctrl_take_shared_lock(int fd)
+ {
+ int ret;
+
+ /* take shared lock on resctrl filesystem */
+ ret = flock(fd, LOCK_SH);
+ if (ret) {
+ perror("flock");
+ exit(-1);
+ }
+ }
+
+ void resctrl_take_exclusive_lock(int fd)
+ {
+ int ret;
+
+ /* release lock on resctrl filesystem */
+ ret = flock(fd, LOCK_EX);
+ if (ret) {
+ perror("flock");
+ exit(-1);
+ }
+ }
+
+ void resctrl_release_lock(int fd)
+ {
+ int ret;
+
+ /* take shared lock on resctrl filesystem */
+ ret = flock(fd, LOCK_UN);
+ if (ret) {
+ perror("flock");
+ exit(-1);
+ }
+ }
+
+ void main(void)
+ {
+ int fd, ret;
+
+ fd = open("/sys/fs/resctrl", O_DIRECTORY);
+ if (fd == -1) {
+ perror("open");
+ exit(-1);
+ }
+ resctrl_take_shared_lock(fd);
+ /* code to read directory contents */
+ resctrl_release_lock(fd);
+
+ resctrl_take_exclusive_lock(fd);
+ /* code to read and write directory contents */
+ resctrl_release_lock(fd);
+ }
+
+Examples for RDT Monitoring along with allocation usage
+=======================================================
Reading monitored data
----------------------
Reading an event file (for ex: mon_data/mon_L3_00/llc_occupancy) would
@@ -1009,17 +1066,17 @@ group or CTRL_MON group.
Example 1 (Monitor CTRL_MON group and subset of tasks in CTRL_MON group)
----------
+------------------------------------------------------------------------
On a two socket machine (one L3 cache per socket) with just four bits
-for cache bit masks
+for cache bit masks::
-# mount -t resctrl resctrl /sys/fs/resctrl
-# cd /sys/fs/resctrl
-# mkdir p0 p1
-# echo "L3:0=3;1=c" > /sys/fs/resctrl/p0/schemata
-# echo "L3:0=3;1=3" > /sys/fs/resctrl/p1/schemata
-# echo 5678 > p1/tasks
-# echo 5679 > p1/tasks
+ # mount -t resctrl resctrl /sys/fs/resctrl
+ # cd /sys/fs/resctrl
+ # mkdir p0 p1
+ # echo "L3:0=3;1=c" > /sys/fs/resctrl/p0/schemata
+ # echo "L3:0=3;1=3" > /sys/fs/resctrl/p1/schemata
+ # echo 5678 > p1/tasks
+ # echo 5679 > p1/tasks
The default resource group is unmodified, so we have access to all parts
of all caches (its schemata file reads "L3:0=f;1=f").
@@ -1029,47 +1086,51 @@ Tasks that are under the control of group "p0" may only allocate from the
Tasks in group "p1" use the "lower" 50% of cache on both sockets.
Create monitor groups and assign a subset of tasks to each monitor group.
+::
-# cd /sys/fs/resctrl/p1/mon_groups
-# mkdir m11 m12
-# echo 5678 > m11/tasks
-# echo 5679 > m12/tasks
+ # cd /sys/fs/resctrl/p1/mon_groups
+ # mkdir m11 m12
+ # echo 5678 > m11/tasks
+ # echo 5679 > m12/tasks
fetch data (data shown in bytes)
+::
-# cat m11/mon_data/mon_L3_00/llc_occupancy
-16234000
-# cat m11/mon_data/mon_L3_01/llc_occupancy
-14789000
-# cat m12/mon_data/mon_L3_00/llc_occupancy
-16789000
+ # cat m11/mon_data/mon_L3_00/llc_occupancy
+ 16234000
+ # cat m11/mon_data/mon_L3_01/llc_occupancy
+ 14789000
+ # cat m12/mon_data/mon_L3_00/llc_occupancy
+ 16789000
The parent ctrl_mon group shows the aggregated data.
+::
-# cat /sys/fs/resctrl/p1/mon_data/mon_l3_00/llc_occupancy
-31234000
+ # cat /sys/fs/resctrl/p1/mon_data/mon_l3_00/llc_occupancy
+ 31234000
Example 2 (Monitor a task from its creation)
----------
-On a two socket machine (one L3 cache per socket)
+--------------------------------------------
+On a two socket machine (one L3 cache per socket)::
-# mount -t resctrl resctrl /sys/fs/resctrl
-# cd /sys/fs/resctrl
-# mkdir p0 p1
+ # mount -t resctrl resctrl /sys/fs/resctrl
+ # cd /sys/fs/resctrl
+ # mkdir p0 p1
An RMID is allocated to the group once its created and hence the <cmd>
below is monitored from its creation.
+::
-# echo $$ > /sys/fs/resctrl/p1/tasks
-# <cmd>
+ # echo $$ > /sys/fs/resctrl/p1/tasks
+ # <cmd>
-Fetch the data
+Fetch the data::
-# cat /sys/fs/resctrl/p1/mon_data/mon_l3_00/llc_occupancy
-31789000
+ # cat /sys/fs/resctrl/p1/mon_data/mon_l3_00/llc_occupancy
+ 31789000
Example 3 (Monitor without CAT support or before creating CAT groups)
----------
+---------------------------------------------------------------------
Assume a system like HSW has only CQM and no CAT support. In this case
the resctrl will still mount but cannot create CTRL_MON directories.
@@ -1078,27 +1139,29 @@ able to monitor all tasks including kernel threads.
This can also be used to profile jobs cache size footprint before being
able to allocate them to different allocation groups.
+::
-# mount -t resctrl resctrl /sys/fs/resctrl
-# cd /sys/fs/resctrl
-# mkdir mon_groups/m01
-# mkdir mon_groups/m02
+ # mount -t resctrl resctrl /sys/fs/resctrl
+ # cd /sys/fs/resctrl
+ # mkdir mon_groups/m01
+ # mkdir mon_groups/m02
-# echo 3478 > /sys/fs/resctrl/mon_groups/m01/tasks
-# echo 2467 > /sys/fs/resctrl/mon_groups/m02/tasks
+ # echo 3478 > /sys/fs/resctrl/mon_groups/m01/tasks
+ # echo 2467 > /sys/fs/resctrl/mon_groups/m02/tasks
Monitor the groups separately and also get per domain data. From the
below its apparent that the tasks are mostly doing work on
domain(socket) 0.
+::
-# cat /sys/fs/resctrl/mon_groups/m01/mon_L3_00/llc_occupancy
-31234000
-# cat /sys/fs/resctrl/mon_groups/m01/mon_L3_01/llc_occupancy
-34555
-# cat /sys/fs/resctrl/mon_groups/m02/mon_L3_00/llc_occupancy
-31234000
-# cat /sys/fs/resctrl/mon_groups/m02/mon_L3_01/llc_occupancy
-32789
+ # cat /sys/fs/resctrl/mon_groups/m01/mon_L3_00/llc_occupancy
+ 31234000
+ # cat /sys/fs/resctrl/mon_groups/m01/mon_L3_01/llc_occupancy
+ 34555
+ # cat /sys/fs/resctrl/mon_groups/m02/mon_L3_00/llc_occupancy
+ 31234000
+ # cat /sys/fs/resctrl/mon_groups/m02/mon_L3_01/llc_occupancy
+ 32789
Example 4 (Monitor real time tasks)
@@ -1107,15 +1170,17 @@ Example 4 (Monitor real time tasks)
A single socket system which has real time tasks running on cores 4-7
and non real time tasks on other cpus. We want to monitor the cache
occupancy of the real time threads on these cores.
+::
-# mount -t resctrl resctrl /sys/fs/resctrl
-# cd /sys/fs/resctrl
-# mkdir p1
+ # mount -t resctrl resctrl /sys/fs/resctrl
+ # cd /sys/fs/resctrl
+ # mkdir p1
-Move the cpus 4-7 over to p1
-# echo f0 > p1/cpus
+Move the cpus 4-7 over to p1::
+
+ # echo f0 > p1/cpus
-View the llc occupancy snapshot
+View the llc occupancy snapshot::
-# cat /sys/fs/resctrl/p1/mon_data/mon_L3_00/llc_occupancy
-11234000
+ # cat /sys/fs/resctrl/p1/mon_data/mon_L3_00/llc_occupancy
+ 11234000
--
2.20.1
^ permalink raw reply related
* [PATCH v4 54/63] Documentation: x86: convert orc-unwinder.txt to reST
From: Changbin Du @ 2019-04-23 16:29 UTC (permalink / raw)
To: Jonathan Corbet
Cc: fenghua.yu, mchehab+samsung, linux-doc, linux-pci, linux-gpio,
x86, rjw, linux-kernel, linux-acpi, mingo, Bjorn Helgaas, tglx,
linuxppc-dev, Changbin Du
In-Reply-To: <20190423162932.21428-1-changbin.du@gmail.com>
This converts the plain text documentation to reStructuredText format and
add it to Sphinx TOC tree. No essential content change.
Signed-off-by: Changbin Du <changbin.du@gmail.com>
---
Documentation/x86/index.rst | 1 +
.../{orc-unwinder.txt => orc-unwinder.rst} | 27 ++++++++++---------
2 files changed, 16 insertions(+), 12 deletions(-)
rename Documentation/x86/{orc-unwinder.txt => orc-unwinder.rst} (93%)
diff --git a/Documentation/x86/index.rst b/Documentation/x86/index.rst
index 4e9fa2b046df..c41c17906b6d 100644
--- a/Documentation/x86/index.rst
+++ b/Documentation/x86/index.rst
@@ -14,6 +14,7 @@ Linux x86 Support
kernel-stacks
entry_64
earlyprintk
+ orc-unwinder
zero-page
tlb
mtrr
diff --git a/Documentation/x86/orc-unwinder.txt b/Documentation/x86/orc-unwinder.rst
similarity index 93%
rename from Documentation/x86/orc-unwinder.txt
rename to Documentation/x86/orc-unwinder.rst
index cd4b29be29af..d811576c1f3e 100644
--- a/Documentation/x86/orc-unwinder.txt
+++ b/Documentation/x86/orc-unwinder.rst
@@ -1,8 +1,11 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+============
ORC unwinder
============
Overview
---------
+========
The kernel CONFIG_UNWINDER_ORC option enables the ORC unwinder, which is
similar in concept to a DWARF unwinder. The difference is that the
@@ -23,12 +26,12 @@ correlate instruction addresses with their stack states at run time.
ORC vs frame pointers
----------------------
+=====================
With frame pointers enabled, GCC adds instrumentation code to every
function in the kernel. The kernel's .text size increases by about
3.2%, resulting in a broad kernel-wide slowdown. Measurements by Mel
-Gorman [1] have shown a slowdown of 5-10% for some workloads.
+Gorman [1]_ have shown a slowdown of 5-10% for some workloads.
In contrast, the ORC unwinder has no effect on text size or runtime
performance, because the debuginfo is out of band. So if you disable
@@ -55,7 +58,7 @@ depending on the kernel config.
ORC vs DWARF
-------------
+============
ORC debuginfo's advantage over DWARF itself is that it's much simpler.
It gets rid of the complex DWARF CFI state machine and also gets rid of
@@ -65,7 +68,7 @@ mission critical oops code.
The simpler debuginfo format also enables the unwinder to be much faster
than DWARF, which is important for perf and lockdep. In a basic
-performance test by Jiri Slaby [2], the ORC unwinder was about 20x
+performance test by Jiri Slaby [2]_, the ORC unwinder was about 20x
faster than an out-of-tree DWARF unwinder. (Note: That measurement was
taken before some performance tweaks were added, which doubled
performance, so the speedup over DWARF may be closer to 40x.)
@@ -85,7 +88,7 @@ still be able to control the format, e.g. no complex state machines.
ORC unwind table generation
----------------------------
+===========================
The ORC data is generated by objtool. With the existing compile-time
stack metadata validation feature, objtool already follows all code
@@ -133,7 +136,7 @@ objtool follows GCC code quite well.
Unwinder implementation details
--------------------------------
+===============================
Objtool generates the ORC data by integrating with the compile-time
stack metadata validation feature, which is described in detail in
@@ -154,7 +157,7 @@ subset of the table needs to be searched.
Etymology
----------
+=========
Orcs, fearsome creatures of medieval folklore, are the Dwarves' natural
enemies. Similarly, the ORC unwinder was created in opposition to the
@@ -162,7 +165,7 @@ complexity and slowness of DWARF.
"Although Orcs rarely consider multiple solutions to a problem, they do
excel at getting things done because they are creatures of action, not
-thought." [3] Similarly, unlike the esoteric DWARF unwinder, the
+thought." [3]_ Similarly, unlike the esoteric DWARF unwinder, the
veracious ORC unwinder wastes no time or siloconic effort decoding
variable-length zero-extended unsigned-integer byte-coded
state-machine-based debug information entries.
@@ -174,6 +177,6 @@ brutal, unyielding efficiency.
ORC stands for Oops Rewind Capability.
-[1] https://lkml.kernel.org/r/20170602104048.jkkzssljsompjdwy@suse.de
-[2] https://lkml.kernel.org/r/d2ca5435-6386-29b8-db87-7f227c2b713a@suse.cz
-[3] http://dustin.wikidot.com/half-orcs-and-orcs
+.. [1] https://lkml.kernel.org/r/20170602104048.jkkzssljsompjdwy@suse.de
+.. [2] https://lkml.kernel.org/r/d2ca5435-6386-29b8-db87-7f227c2b713a@suse.cz
+.. [3] http://dustin.wikidot.com/half-orcs-and-orcs
--
2.20.1
^ permalink raw reply related
* [PATCH v4 55/63] Documentation: x86: convert usb-legacy-support.txt to reST
From: Changbin Du @ 2019-04-23 16:29 UTC (permalink / raw)
To: Jonathan Corbet
Cc: fenghua.yu, mchehab+samsung, linux-doc, linux-pci, linux-gpio,
x86, rjw, linux-kernel, linux-acpi, mingo, Bjorn Helgaas, tglx,
linuxppc-dev, Changbin Du
In-Reply-To: <20190423162932.21428-1-changbin.du@gmail.com>
This converts the plain text documentation to reStructuredText format and
add it to Sphinx TOC tree. No essential content change.
Signed-off-by: Changbin Du <changbin.du@gmail.com>
---
Documentation/x86/index.rst | 1 +
.../{usb-legacy-support.txt => usb-legacy-support.rst} | 8 ++++++--
2 files changed, 7 insertions(+), 2 deletions(-)
rename Documentation/x86/{usb-legacy-support.txt => usb-legacy-support.rst} (92%)
diff --git a/Documentation/x86/index.rst b/Documentation/x86/index.rst
index c41c17906b6d..526f7a008b8e 100644
--- a/Documentation/x86/index.rst
+++ b/Documentation/x86/index.rst
@@ -25,3 +25,4 @@ Linux x86 Support
pti
microcode
resctrl_ui
+ usb-legacy-support
diff --git a/Documentation/x86/usb-legacy-support.txt b/Documentation/x86/usb-legacy-support.rst
similarity index 92%
rename from Documentation/x86/usb-legacy-support.txt
rename to Documentation/x86/usb-legacy-support.rst
index 1894cdfc69d9..19abead7f1a8 100644
--- a/Documentation/x86/usb-legacy-support.txt
+++ b/Documentation/x86/usb-legacy-support.rst
@@ -1,7 +1,11 @@
+
+.. SPDX-License-Identifier: GPL-2.0
+
+==================
USB Legacy support
-~~~~~~~~~~~~~~~~~~
+==================
-Vojtech Pavlik <vojtech@suse.cz>, January 2004
+:Author: Vojtech Pavlik <vojtech@suse.cz>, January 2004
Also known as "USB Keyboard" or "USB Mouse support" in the BIOS Setup is a
--
2.20.1
^ permalink raw reply related
* [PATCH v4 56/63] Documentation: x86: convert i386/IO-APIC.txt to reST
From: Changbin Du @ 2019-04-23 16:29 UTC (permalink / raw)
To: Jonathan Corbet
Cc: fenghua.yu, mchehab+samsung, linux-doc, linux-pci, linux-gpio,
x86, rjw, linux-kernel, linux-acpi, mingo, Bjorn Helgaas, tglx,
linuxppc-dev, Changbin Du
In-Reply-To: <20190423162932.21428-1-changbin.du@gmail.com>
This converts the plain text documentation to reStructuredText format and
add it to Sphinx TOC tree. No essential content change.
Signed-off-by: Changbin Du <changbin.du@gmail.com>
---
.../x86/i386/{IO-APIC.txt => IO-APIC.rst} | 26 ++++++++++++-------
Documentation/x86/i386/index.rst | 10 +++++++
Documentation/x86/index.rst | 1 +
3 files changed, 27 insertions(+), 10 deletions(-)
rename Documentation/x86/i386/{IO-APIC.txt => IO-APIC.rst} (93%)
create mode 100644 Documentation/x86/i386/index.rst
diff --git a/Documentation/x86/i386/IO-APIC.txt b/Documentation/x86/i386/IO-APIC.rst
similarity index 93%
rename from Documentation/x86/i386/IO-APIC.txt
rename to Documentation/x86/i386/IO-APIC.rst
index 15f5baf7e1b6..aec98f742763 100644
--- a/Documentation/x86/i386/IO-APIC.txt
+++ b/Documentation/x86/i386/IO-APIC.rst
@@ -1,3 +1,11 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+=======
+IO-APIC
+=======
+
+:Author: Ingo Molnar <mingo@kernel.org>
+
Most (all) Intel-MP compliant SMP boards have the so-called 'IO-APIC',
which is an enhanced interrupt controller. It enables us to route
hardware interrupts to multiple CPUs, or to CPU groups. Without an
@@ -13,7 +21,7 @@ usually worked around by the kernel. If your MP-compliant SMP board does
not boot Linux, then consult the linux-smp mailing list archives first.
If your box boots fine with enabled IO-APIC IRQs, then your
-/proc/interrupts will look like this one:
+/proc/interrupts will look like this one::
---------------------------->
hell:~> cat /proc/interrupts
@@ -37,14 +45,14 @@ none of those IRQ sources is performance-critical.
In the unlikely case that your board does not create a working mp-table,
you can use the pirq= boot parameter to 'hand-construct' IRQ entries. This
is non-trivial though and cannot be automated. One sample /etc/lilo.conf
-entry:
+entry::
append="pirq=15,11,10"
The actual numbers depend on your system, on your PCI cards and on their
PCI slot position. Usually PCI slots are 'daisy chained' before they are
connected to the PCI chipset IRQ routing facility (the incoming PIRQ1-4
-lines):
+lines)::
,-. ,-. ,-. ,-. ,-.
PIRQ4 ----| |-. ,-| |-. ,-| |-. ,-| |--------| |
@@ -56,7 +64,7 @@ lines):
PIRQ1 ----| |- `----| |- `----| |- `----| |--------| |
`-' `-' `-' `-' `-'
-Every PCI card emits a PCI IRQ, which can be INTA, INTB, INTC or INTD:
+Every PCI card emits a PCI IRQ, which can be INTA, INTB, INTC or INTD::
,-.
INTD--| |
@@ -78,19 +86,19 @@ to have non shared interrupts). Slot5 should be used for videocards, they
do not use interrupts normally, thus they are not daisy chained either.
so if you have your SCSI card (IRQ11) in Slot1, Tulip card (IRQ9) in
-Slot2, then you'll have to specify this pirq= line:
+Slot2, then you'll have to specify this pirq= line::
append="pirq=11,9"
the following script tries to figure out such a default pirq= line from
-your PCI configuration:
+your PCI configuration::
echo -n pirq=; echo `scanpci | grep T_L | cut -c56-` | sed 's/ /,/g'
note that this script won't work if you have skipped a few slots or if your
board does not do default daisy-chaining. (or the IO-APIC has the PIRQ pins
connected in some strange way). E.g. if in the above case you have your SCSI
-card (IRQ11) in Slot3, and have Slot1 empty:
+card (IRQ11) in Slot3, and have Slot1 empty::
append="pirq=0,9,11"
@@ -105,7 +113,7 @@ won't function properly (e.g. if it's inserted as a module).
If you have 2 PCI buses, then you can use up to 8 pirq values, although such
boards tend to have a good configuration.
-Be prepared that it might happen that you need some strange pirq line:
+Be prepared that it might happen that you need some strange pirq line::
append="pirq=0,0,0,0,0,0,9,11"
@@ -115,5 +123,3 @@ Good luck and mail to linux-smp@vger.kernel.org or
linux-kernel@vger.kernel.org if you have any problems that are not covered
by this document.
--- mingo
-
diff --git a/Documentation/x86/i386/index.rst b/Documentation/x86/i386/index.rst
new file mode 100644
index 000000000000..8747cf5bbd49
--- /dev/null
+++ b/Documentation/x86/i386/index.rst
@@ -0,0 +1,10 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+============
+i386 Support
+============
+
+.. toctree::
+ :maxdepth: 2
+
+ IO-APIC
diff --git a/Documentation/x86/index.rst b/Documentation/x86/index.rst
index 526f7a008b8e..19323c5b89ce 100644
--- a/Documentation/x86/index.rst
+++ b/Documentation/x86/index.rst
@@ -26,3 +26,4 @@ Linux x86 Support
microcode
resctrl_ui
usb-legacy-support
+ i386/index
--
2.20.1
^ permalink raw reply related
* [PATCH v4 57/63] Documentation: x86: convert x86_64/boot-options.txt to reST
From: Changbin Du @ 2019-04-23 16:29 UTC (permalink / raw)
To: Jonathan Corbet
Cc: fenghua.yu, mchehab+samsung, linux-doc, linux-pci, linux-gpio,
x86, rjw, linux-kernel, linux-acpi, mingo, Bjorn Helgaas, tglx,
linuxppc-dev, Changbin Du
In-Reply-To: <20190423162932.21428-1-changbin.du@gmail.com>
This converts the plain text documentation to reStructuredText format and
add it to Sphinx TOC tree. No essential content change.
Signed-off-by: Changbin Du <changbin.du@gmail.com>
---
Documentation/x86/index.rst | 1 +
Documentation/x86/x86_64/boot-options.rst | 327 ++++++++++++++++++++++
Documentation/x86/x86_64/boot-options.txt | 278 ------------------
Documentation/x86/x86_64/index.rst | 10 +
4 files changed, 338 insertions(+), 278 deletions(-)
create mode 100644 Documentation/x86/x86_64/boot-options.rst
delete mode 100644 Documentation/x86/x86_64/boot-options.txt
create mode 100644 Documentation/x86/x86_64/index.rst
diff --git a/Documentation/x86/index.rst b/Documentation/x86/index.rst
index 19323c5b89ce..e7becb146c30 100644
--- a/Documentation/x86/index.rst
+++ b/Documentation/x86/index.rst
@@ -27,3 +27,4 @@ Linux x86 Support
resctrl_ui
usb-legacy-support
i386/index
+ x86_64/index
diff --git a/Documentation/x86/x86_64/boot-options.rst b/Documentation/x86/x86_64/boot-options.rst
new file mode 100644
index 000000000000..44aa8b878b16
--- /dev/null
+++ b/Documentation/x86/x86_64/boot-options.rst
@@ -0,0 +1,327 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+===========================
+AMD64 Specific Boot Options
+===========================
+
+There are many others (usually documented in driver documentation), but
+only the AMD64 specific ones are listed here.
+
+Machine check
+=============
+Please see Documentation/x86/x86_64/machinecheck for sysfs runtime tunables.
+
+ mce=off
+ Disable machine check
+ mce=no_cmci
+ Disable CMCI(Corrected Machine Check Interrupt) that
+ Intel processor supports. Usually this disablement is
+ not recommended, but it might be handy if your hardware
+ is misbehaving.
+ Note that you'll get more problems without CMCI than with
+ due to the shared banks, i.e. you might get duplicated
+ error logs.
+ mce=dont_log_ce
+ Don't make logs for corrected errors. All events reported
+ as corrected are silently cleared by OS.
+ This option will be useful if you have no interest in any
+ of corrected errors.
+ mce=ignore_ce
+ Disable features for corrected errors, e.g. polling timer
+ and CMCI. All events reported as corrected are not cleared
+ by OS and remained in its error banks.
+ Usually this disablement is not recommended, however if
+ there is an agent checking/clearing corrected errors
+ (e.g. BIOS or hardware monitoring applications), conflicting
+ with OS's error handling, and you cannot deactivate the agent,
+ then this option will be a help.
+ mce=no_lmce
+ Do not opt-in to Local MCE delivery. Use legacy method
+ to broadcast MCEs.
+ mce=bootlog
+ Enable logging of machine checks left over from booting.
+ Disabled by default on AMD Fam10h and older because some BIOS
+ leave bogus ones.
+ If your BIOS doesn't do that it's a good idea to enable though
+ to make sure you log even machine check events that result
+ in a reboot. On Intel systems it is enabled by default.
+ mce=nobootlog
+ Disable boot machine check logging.
+ mce=tolerancelevel[,monarchtimeout] (number,number)
+ tolerance levels:
+ 0: always panic on uncorrected errors, log corrected errors
+ 1: panic or SIGBUS on uncorrected errors, log corrected errors
+ 2: SIGBUS or log uncorrected errors, log corrected errors
+ 3: never panic or SIGBUS, log all errors (for testing only)
+ Default is 1
+ Can be also set using sysfs which is preferable.
+ monarchtimeout:
+ Sets the time in us to wait for other CPUs on machine checks. 0
+ to disable.
+ mce=bios_cmci_threshold
+ Don't overwrite the bios-set CMCI threshold. This boot option
+ prevents Linux from overwriting the CMCI threshold set by the
+ bios. Without this option, Linux always sets the CMCI
+ threshold to 1. Enabling this may make memory predictive failure
+ analysis less effective if the bios sets thresholds for memory
+ errors since we will not see details for all errors.
+ mce=recovery
+ Force-enable recoverable machine check code paths
+
+ nomce (for compatibility with i386)
+ same as mce=off
+
+ Everything else is in sysfs now.
+
+APICs
+=====
+
+ apic
+ Use IO-APIC. Default
+
+ noapic
+ Don't use the IO-APIC.
+
+ disableapic
+ Don't use the local APIC
+
+ nolapic
+ Don't use the local APIC (alias for i386 compatibility)
+
+ pirq=...
+ See Documentation/x86/i386/IO-APIC.txt
+
+ noapictimer
+ Don't set up the APIC timer
+
+ no_timer_check
+ Don't check the IO-APIC timer. This can work around
+ problems with incorrect timer initialization on some boards.
+
+ apicpmtimer
+ Do APIC timer calibration using the pmtimer. Implies
+ apicmaintimer. Useful when your PIT timer is totally
+ broken.
+
+Timing
+======
+
+ notsc
+ Deprecated, use tsc=unstable instead.
+
+ nohpet
+ Don't use the HPET timer.
+
+Idle loop
+=========
+
+ idle=poll
+ Don't do power saving in the idle loop using HLT, but poll for rescheduling
+ event. This will make the CPUs eat a lot more power, but may be useful
+ to get slightly better performance in multiprocessor benchmarks. It also
+ makes some profiling using performance counters more accurate.
+ Please note that on systems with MONITOR/MWAIT support (like Intel EM64T
+ CPUs) this option has no performance advantage over the normal idle loop.
+ It may also interact badly with hyperthreading.
+
+Rebooting
+=========
+
+ reboot=b[ios] | t[riple] | k[bd] | a[cpi] | e[fi] [, [w]arm | [c]old]
+ * bios - Use the CPU reboot vector for warm reset
+ * warm - Don't set the cold reboot flag
+ * cold - Set the cold reboot flag
+ * triple - Force a triple fault (init)
+ * kbd - Use the keyboard controller. cold reset (default)
+ * acpi - Use the ACPI RESET_REG in the FADT. If ACPI is not configured or
+ the ACPI reset does not work, the reboot path attempts the reset
+ using the keyboard controller.
+ * efi - Use efi reset_system runtime service. If EFI is not configured or
+ the EFI reset does not work, the reboot path attempts the reset using
+ the keyboard controller.
+
+ Using warm reset will be much faster especially on big memory
+ systems because the BIOS will not go through the memory check.
+ Disadvantage is that not all hardware will be completely reinitialized
+ on reboot so there may be boot problems on some systems.
+
+ reboot=force
+ Don't stop other CPUs on reboot. This can make reboot more reliable
+ in some cases.
+
+Non Executable Mappings
+=======================
+
+ noexec=on|off
+ * on - Enable(default)
+ * off - Disable
+
+NUMA
+====
+
+ numa=off
+ Only set up a single NUMA node spanning all memory.
+
+ numa=noacpi
+ Don't parse the SRAT table for NUMA setup
+
+ numa=fake=<size>[MG]
+ If given as a memory unit, fills all system RAM with nodes of
+ size interleaved over physical nodes.
+
+ numa=fake=<N>
+ If given as an integer, fills all system RAM with N fake nodes
+ interleaved over physical nodes.
+
+ numa=fake=<N>U
+ If given as an integer followed by 'U', it will divide each
+ physical node into N emulated nodes.
+
+ACPI
+====
+
+ acpi=off
+ Don't enable ACPI
+ acpi=ht
+ Use ACPI boot table parsing, but don't enable ACPI interpreter
+ acpi=force
+ Force ACPI on (currently not needed)
+ acpi=strict
+ Disable out of spec ACPI workarounds.
+ acpi_sci={edge,level,high,low}
+ Set up ACPI SCI interrupt.
+ acpi=noirq
+ Don't route interrupts
+ acpi=nocmcff
+ Disable firmware first mode for corrected errors. This
+ disables parsing the HEST CMC error source to check if
+ firmware has set the FF flag. This may result in
+ duplicate corrected error reports.
+
+PCI
+===
+
+ pci=off
+ Don't use PCI
+ pci=conf1
+ Use conf1 access.
+ pci=conf2
+ Use conf2 access.
+ pci=rom
+ Assign ROMs.
+ pci=assign-busses
+ Assign busses
+ pci=irqmask=MASK
+ Set PCI interrupt mask to MASK
+ pci=lastbus=NUMBER
+ Scan up to NUMBER busses, no matter what the mptable says.
+ pci=noacpi
+ Don't use ACPI to set up PCI interrupt routing.
+
+IOMMU (input/output memory management unit)
+===========================================
+Multiple x86-64 PCI-DMA mapping implementations exist, for example:
+
+ 1. <lib/dma-direct.c>: use no hardware/software IOMMU at all
+ (e.g. because you have < 3 GB memory).
+ Kernel boot message: "PCI-DMA: Disabling IOMMU"
+
+ 2. <arch/x86/kernel/amd_gart_64.c>: AMD GART based hardware IOMMU.
+ Kernel boot message: "PCI-DMA: using GART IOMMU"
+
+ 3. <arch/x86_64/kernel/pci-swiotlb.c> : Software IOMMU implementation. Used
+ e.g. if there is no hardware IOMMU in the system and it is need because
+ you have >3GB memory or told the kernel to us it (iommu=soft))
+ Kernel boot message: "PCI-DMA: Using software bounce buffering
+ for IO (SWIOTLB)"
+
+ 4. <arch/x86_64/pci-calgary.c> : IBM Calgary hardware IOMMU. Used in IBM
+ pSeries and xSeries servers. This hardware IOMMU supports DMA address
+ mapping with memory protection, etc.
+ Kernel boot message: "PCI-DMA: Using Calgary IOMMU"
+
+::
+
+ iommu=[<size>][,noagp][,off][,force][,noforce]
+ [,memaper[=<order>]][,merge][,fullflush][,nomerge]
+ [,noaperture][,calgary]
+
+General iommu options:
+
+ off
+ Don't initialize and use any kind of IOMMU.
+ noforce
+ Don't force hardware IOMMU usage when it is not needed. (default).
+ force
+ Force the use of the hardware IOMMU even when it is
+ not actually needed (e.g. because < 3 GB memory).
+ soft
+ Use software bounce buffering (SWIOTLB) (default for
+ Intel machines). This can be used to prevent the usage
+ of an available hardware IOMMU.
+
+iommu options only relevant to the AMD GART hardware IOMMU:
+
+ <size>
+ Set the size of the remapping area in bytes.
+ allowed
+ Overwrite iommu off workarounds for specific chipsets.
+ fullflush
+ Flush IOMMU on each allocation (default).
+ nofullflush
+ Don't use IOMMU fullflush.
+ memaper[=<order>]
+ Allocate an own aperture over RAM with size 32MB<<order.
+ (default: order=1, i.e. 64MB)
+ merge
+ Do scatter-gather (SG) merging. Implies "force" (experimental).
+ nomerge
+ Don't do scatter-gather (SG) merging.
+ noaperture
+ Ask the IOMMU not to touch the aperture for AGP.
+ noagp
+ Don't initialize the AGP driver and use full aperture.
+ panic
+ Always panic when IOMMU overflows.
+ calgary
+ Use the Calgary IOMMU if it is available
+
+iommu options only relevant to the software bounce buffering (SWIOTLB) IOMMU
+implementation:
+
+ swiotlb=<pages>[,force]
+ <pages>
+ Prereserve that many 128K pages for the software IO bounce buffering.
+ force
+ Force all IO through the software TLB.
+
+Settings for the IBM Calgary hardware IOMMU currently found in IBM
+pSeries and xSeries machines
+
+ calgary=[64k,128k,256k,512k,1M,2M,4M,8M]
+ Set the size of each PCI slot's translation table when using the
+ Calgary IOMMU. This is the size of the translation table itself
+ in main memory. The smallest table, 64k, covers an IO space of
+ 32MB; the largest, 8MB table, can cover an IO space of 4GB.
+ Normally the kernel will make the right choice by itself.
+ calgary=[translate_empty_slots]
+ Enable translation even on slots that have no devices attached to
+ them, in case a device will be hotplugged in the future.
+ calgary=[disable=<PCI bus number>]
+ Disable translation on a given PHB. For
+ example, the built-in graphics adapter resides on the first bridge
+ (PCI bus number 0); if translation (isolation) is enabled on this
+ bridge, X servers that access the hardware directly from user
+ space might stop working. Use this option if you have devices that
+ are accessed from userspace directly on some PCI host bridge.
+ panic
+ Always panic when IOMMU overflows
+
+
+Miscellaneous
+=============
+
+ nogbpages
+ Do not use GB pages for kernel direct mappings.
+ gbpages
+ Use GB pages for kernel direct mappings.
diff --git a/Documentation/x86/x86_64/boot-options.txt b/Documentation/x86/x86_64/boot-options.txt
deleted file mode 100644
index abc53886655e..000000000000
--- a/Documentation/x86/x86_64/boot-options.txt
+++ /dev/null
@@ -1,278 +0,0 @@
-AMD64 specific boot options
-
-There are many others (usually documented in driver documentation), but
-only the AMD64 specific ones are listed here.
-
-Machine check
-
- Please see Documentation/x86/x86_64/machinecheck for sysfs runtime tunables.
-
- mce=off
- Disable machine check
- mce=no_cmci
- Disable CMCI(Corrected Machine Check Interrupt) that
- Intel processor supports. Usually this disablement is
- not recommended, but it might be handy if your hardware
- is misbehaving.
- Note that you'll get more problems without CMCI than with
- due to the shared banks, i.e. you might get duplicated
- error logs.
- mce=dont_log_ce
- Don't make logs for corrected errors. All events reported
- as corrected are silently cleared by OS.
- This option will be useful if you have no interest in any
- of corrected errors.
- mce=ignore_ce
- Disable features for corrected errors, e.g. polling timer
- and CMCI. All events reported as corrected are not cleared
- by OS and remained in its error banks.
- Usually this disablement is not recommended, however if
- there is an agent checking/clearing corrected errors
- (e.g. BIOS or hardware monitoring applications), conflicting
- with OS's error handling, and you cannot deactivate the agent,
- then this option will be a help.
- mce=no_lmce
- Do not opt-in to Local MCE delivery. Use legacy method
- to broadcast MCEs.
- mce=bootlog
- Enable logging of machine checks left over from booting.
- Disabled by default on AMD Fam10h and older because some BIOS
- leave bogus ones.
- If your BIOS doesn't do that it's a good idea to enable though
- to make sure you log even machine check events that result
- in a reboot. On Intel systems it is enabled by default.
- mce=nobootlog
- Disable boot machine check logging.
- mce=tolerancelevel[,monarchtimeout] (number,number)
- tolerance levels:
- 0: always panic on uncorrected errors, log corrected errors
- 1: panic or SIGBUS on uncorrected errors, log corrected errors
- 2: SIGBUS or log uncorrected errors, log corrected errors
- 3: never panic or SIGBUS, log all errors (for testing only)
- Default is 1
- Can be also set using sysfs which is preferable.
- monarchtimeout:
- Sets the time in us to wait for other CPUs on machine checks. 0
- to disable.
- mce=bios_cmci_threshold
- Don't overwrite the bios-set CMCI threshold. This boot option
- prevents Linux from overwriting the CMCI threshold set by the
- bios. Without this option, Linux always sets the CMCI
- threshold to 1. Enabling this may make memory predictive failure
- analysis less effective if the bios sets thresholds for memory
- errors since we will not see details for all errors.
- mce=recovery
- Force-enable recoverable machine check code paths
-
- nomce (for compatibility with i386): same as mce=off
-
- Everything else is in sysfs now.
-
-APICs
-
- apic Use IO-APIC. Default
-
- noapic Don't use the IO-APIC.
-
- disableapic Don't use the local APIC
-
- nolapic Don't use the local APIC (alias for i386 compatibility)
-
- pirq=... See Documentation/x86/i386/IO-APIC.txt
-
- noapictimer Don't set up the APIC timer
-
- no_timer_check Don't check the IO-APIC timer. This can work around
- problems with incorrect timer initialization on some boards.
- apicpmtimer
- Do APIC timer calibration using the pmtimer. Implies
- apicmaintimer. Useful when your PIT timer is totally
- broken.
-
-Timing
-
- notsc
- Deprecated, use tsc=unstable instead.
-
- nohpet
- Don't use the HPET timer.
-
-Idle loop
-
- idle=poll
- Don't do power saving in the idle loop using HLT, but poll for rescheduling
- event. This will make the CPUs eat a lot more power, but may be useful
- to get slightly better performance in multiprocessor benchmarks. It also
- makes some profiling using performance counters more accurate.
- Please note that on systems with MONITOR/MWAIT support (like Intel EM64T
- CPUs) this option has no performance advantage over the normal idle loop.
- It may also interact badly with hyperthreading.
-
-Rebooting
-
- reboot=b[ios] | t[riple] | k[bd] | a[cpi] | e[fi] [, [w]arm | [c]old]
- bios Use the CPU reboot vector for warm reset
- warm Don't set the cold reboot flag
- cold Set the cold reboot flag
- triple Force a triple fault (init)
- kbd Use the keyboard controller. cold reset (default)
- acpi Use the ACPI RESET_REG in the FADT. If ACPI is not configured or the
- ACPI reset does not work, the reboot path attempts the reset using
- the keyboard controller.
- efi Use efi reset_system runtime service. If EFI is not configured or the
- EFI reset does not work, the reboot path attempts the reset using
- the keyboard controller.
-
- Using warm reset will be much faster especially on big memory
- systems because the BIOS will not go through the memory check.
- Disadvantage is that not all hardware will be completely reinitialized
- on reboot so there may be boot problems on some systems.
-
- reboot=force
-
- Don't stop other CPUs on reboot. This can make reboot more reliable
- in some cases.
-
-Non Executable Mappings
-
- noexec=on|off
-
- on Enable(default)
- off Disable
-
-NUMA
-
- numa=off Only set up a single NUMA node spanning all memory.
-
- numa=noacpi Don't parse the SRAT table for NUMA setup
-
- numa=fake=<size>[MG]
- If given as a memory unit, fills all system RAM with nodes of
- size interleaved over physical nodes.
-
- numa=fake=<N>
- If given as an integer, fills all system RAM with N fake nodes
- interleaved over physical nodes.
-
- numa=fake=<N>U
- If given as an integer followed by 'U', it will divide each
- physical node into N emulated nodes.
-
-ACPI
-
- acpi=off Don't enable ACPI
- acpi=ht Use ACPI boot table parsing, but don't enable ACPI
- interpreter
- acpi=force Force ACPI on (currently not needed)
-
- acpi=strict Disable out of spec ACPI workarounds.
-
- acpi_sci={edge,level,high,low} Set up ACPI SCI interrupt.
-
- acpi=noirq Don't route interrupts
-
- acpi=nocmcff Disable firmware first mode for corrected errors. This
- disables parsing the HEST CMC error source to check if
- firmware has set the FF flag. This may result in
- duplicate corrected error reports.
-
-PCI
-
- pci=off Don't use PCI
- pci=conf1 Use conf1 access.
- pci=conf2 Use conf2 access.
- pci=rom Assign ROMs.
- pci=assign-busses Assign busses
- pci=irqmask=MASK Set PCI interrupt mask to MASK
- pci=lastbus=NUMBER Scan up to NUMBER busses, no matter what the mptable says.
- pci=noacpi Don't use ACPI to set up PCI interrupt routing.
-
-IOMMU (input/output memory management unit)
-
- Multiple x86-64 PCI-DMA mapping implementations exist, for example:
-
- 1. <lib/dma-direct.c>: use no hardware/software IOMMU at all
- (e.g. because you have < 3 GB memory).
- Kernel boot message: "PCI-DMA: Disabling IOMMU"
-
- 2. <arch/x86/kernel/amd_gart_64.c>: AMD GART based hardware IOMMU.
- Kernel boot message: "PCI-DMA: using GART IOMMU"
-
- 3. <arch/x86_64/kernel/pci-swiotlb.c> : Software IOMMU implementation. Used
- e.g. if there is no hardware IOMMU in the system and it is need because
- you have >3GB memory or told the kernel to us it (iommu=soft))
- Kernel boot message: "PCI-DMA: Using software bounce buffering
- for IO (SWIOTLB)"
-
- 4. <arch/x86_64/pci-calgary.c> : IBM Calgary hardware IOMMU. Used in IBM
- pSeries and xSeries servers. This hardware IOMMU supports DMA address
- mapping with memory protection, etc.
- Kernel boot message: "PCI-DMA: Using Calgary IOMMU"
-
- iommu=[<size>][,noagp][,off][,force][,noforce]
- [,memaper[=<order>]][,merge][,fullflush][,nomerge]
- [,noaperture][,calgary]
-
- General iommu options:
- off Don't initialize and use any kind of IOMMU.
- noforce Don't force hardware IOMMU usage when it is not needed.
- (default).
- force Force the use of the hardware IOMMU even when it is
- not actually needed (e.g. because < 3 GB memory).
- soft Use software bounce buffering (SWIOTLB) (default for
- Intel machines). This can be used to prevent the usage
- of an available hardware IOMMU.
-
- iommu options only relevant to the AMD GART hardware IOMMU:
- <size> Set the size of the remapping area in bytes.
- allowed Overwrite iommu off workarounds for specific chipsets.
- fullflush Flush IOMMU on each allocation (default).
- nofullflush Don't use IOMMU fullflush.
- memaper[=<order>] Allocate an own aperture over RAM with size 32MB<<order.
- (default: order=1, i.e. 64MB)
- merge Do scatter-gather (SG) merging. Implies "force"
- (experimental).
- nomerge Don't do scatter-gather (SG) merging.
- noaperture Ask the IOMMU not to touch the aperture for AGP.
- noagp Don't initialize the AGP driver and use full aperture.
- panic Always panic when IOMMU overflows.
- calgary Use the Calgary IOMMU if it is available
-
- iommu options only relevant to the software bounce buffering (SWIOTLB) IOMMU
- implementation:
- swiotlb=<pages>[,force]
- <pages> Prereserve that many 128K pages for the software IO
- bounce buffering.
- force Force all IO through the software TLB.
-
- Settings for the IBM Calgary hardware IOMMU currently found in IBM
- pSeries and xSeries machines:
-
- calgary=[64k,128k,256k,512k,1M,2M,4M,8M]
- calgary=[translate_empty_slots]
- calgary=[disable=<PCI bus number>]
- panic Always panic when IOMMU overflows
-
- 64k,...,8M - Set the size of each PCI slot's translation table
- when using the Calgary IOMMU. This is the size of the translation
- table itself in main memory. The smallest table, 64k, covers an IO
- space of 32MB; the largest, 8MB table, can cover an IO space of
- 4GB. Normally the kernel will make the right choice by itself.
-
- translate_empty_slots - Enable translation even on slots that have
- no devices attached to them, in case a device will be hotplugged
- in the future.
-
- disable=<PCI bus number> - Disable translation on a given PHB. For
- example, the built-in graphics adapter resides on the first bridge
- (PCI bus number 0); if translation (isolation) is enabled on this
- bridge, X servers that access the hardware directly from user
- space might stop working. Use this option if you have devices that
- are accessed from userspace directly on some PCI host bridge.
-
-Miscellaneous
-
- nogbpages
- Do not use GB pages for kernel direct mappings.
- gbpages
- Use GB pages for kernel direct mappings.
diff --git a/Documentation/x86/x86_64/index.rst b/Documentation/x86/x86_64/index.rst
new file mode 100644
index 000000000000..a8cf7713cac9
--- /dev/null
+++ b/Documentation/x86/x86_64/index.rst
@@ -0,0 +1,10 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+==============
+x86_64 Support
+==============
+
+.. toctree::
+ :maxdepth: 2
+
+ boot-options
--
2.20.1
^ permalink raw reply related
* [PATCH v4 58/63] Documentation: x86: convert x86_64/uefi.txt to reST
From: Changbin Du @ 2019-04-23 16:29 UTC (permalink / raw)
To: Jonathan Corbet
Cc: fenghua.yu, mchehab+samsung, linux-doc, linux-pci, linux-gpio,
x86, rjw, linux-kernel, linux-acpi, mingo, Bjorn Helgaas, tglx,
linuxppc-dev, Changbin Du
In-Reply-To: <20190423162932.21428-1-changbin.du@gmail.com>
This converts the plain text documentation to reStructuredText format and
add it to Sphinx TOC tree. No essential content change.
Signed-off-by: Changbin Du <changbin.du@gmail.com>
---
Documentation/x86/x86_64/index.rst | 1 +
.../x86/x86_64/{uefi.txt => uefi.rst} | 30 ++++++++++++++-----
2 files changed, 24 insertions(+), 7 deletions(-)
rename Documentation/x86/x86_64/{uefi.txt => uefi.rst} (79%)
diff --git a/Documentation/x86/x86_64/index.rst b/Documentation/x86/x86_64/index.rst
index a8cf7713cac9..ddfa1f9d4193 100644
--- a/Documentation/x86/x86_64/index.rst
+++ b/Documentation/x86/x86_64/index.rst
@@ -8,3 +8,4 @@ x86_64 Support
:maxdepth: 2
boot-options
+ uefi
diff --git a/Documentation/x86/x86_64/uefi.txt b/Documentation/x86/x86_64/uefi.rst
similarity index 79%
rename from Documentation/x86/x86_64/uefi.txt
rename to Documentation/x86/x86_64/uefi.rst
index a5e2b4fdb170..88c3ba32546f 100644
--- a/Documentation/x86/x86_64/uefi.txt
+++ b/Documentation/x86/x86_64/uefi.rst
@@ -1,5 +1,8 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+=====================================
General note on [U]EFI x86_64 support
--------------------------------------
+=====================================
The nomenclature EFI and UEFI are used interchangeably in this document.
@@ -14,29 +17,42 @@ with EFI firmware and specifications are listed below.
3. x86_64 platform with EFI/UEFI firmware.
-Mechanics:
+Mechanics
---------
-- Build the kernel with the following configuration.
+
+- Build the kernel with the following configuration::
+
CONFIG_FB_EFI=y
CONFIG_FRAMEBUFFER_CONSOLE=y
+
If EFI runtime services are expected, the following configuration should
- be selected.
+ be selected::
+
CONFIG_EFI=y
CONFIG_EFI_VARS=y or m # optional
+
- Create a VFAT partition on the disk
- Copy the following to the VFAT partition:
+
elilo bootloader with x86_64 support, elilo configuration file,
kernel image built in first step and corresponding
initrd. Instructions on building elilo and its dependencies
can be found in the elilo sourceforge project.
+
- Boot to EFI shell and invoke elilo choosing the kernel image built
in first step.
- If some or all EFI runtime services don't work, you can try following
kernel command line parameters to turn off some or all EFI runtime
services.
- noefi turn off all EFI runtime services
- reboot_type=k turn off EFI reboot runtime service
+
+ noefi
+ turn off all EFI runtime services
+ reboot_type=k
+ turn off EFI reboot runtime service
+
- If the EFI memory map has additional entries not in the E820 map,
you can include those entries in the kernels memory map of available
physical RAM by using the following kernel command line parameter.
- add_efi_memmap include EFI memory map of available physical RAM
+
+ add_efi_memmap
+ include EFI memory map of available physical RAM
--
2.20.1
^ permalink raw reply related
* [PATCH v4 59/63] Documentation: x86: convert x86_64/mm.txt to reST
From: Changbin Du @ 2019-04-23 16:29 UTC (permalink / raw)
To: Jonathan Corbet
Cc: fenghua.yu, mchehab+samsung, linux-doc, linux-pci, linux-gpio,
x86, rjw, linux-kernel, linux-acpi, mingo, Bjorn Helgaas, tglx,
linuxppc-dev, Changbin Du
In-Reply-To: <20190423162932.21428-1-changbin.du@gmail.com>
This converts the plain text documentation to reStructuredText format and
add it to Sphinx TOC tree. No essential content change.
Signed-off-by: Changbin Du <changbin.du@gmail.com>
---
Documentation/x86/x86_64/index.rst | 1 +
Documentation/x86/x86_64/mm.rst | 161 +++++++++++++++++++++++++++++
Documentation/x86/x86_64/mm.txt | 153 ---------------------------
3 files changed, 162 insertions(+), 153 deletions(-)
create mode 100644 Documentation/x86/x86_64/mm.rst
delete mode 100644 Documentation/x86/x86_64/mm.txt
diff --git a/Documentation/x86/x86_64/index.rst b/Documentation/x86/x86_64/index.rst
index ddfa1f9d4193..4b65d29ef459 100644
--- a/Documentation/x86/x86_64/index.rst
+++ b/Documentation/x86/x86_64/index.rst
@@ -9,3 +9,4 @@ x86_64 Support
boot-options
uefi
+ mm
diff --git a/Documentation/x86/x86_64/mm.rst b/Documentation/x86/x86_64/mm.rst
new file mode 100644
index 000000000000..4a29441c9e25
--- /dev/null
+++ b/Documentation/x86/x86_64/mm.rst
@@ -0,0 +1,161 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+================
+Memory Managment
+================
+
+Complete virtual memory map with 4-level page tables
+====================================================
+
+.. note::
+
+ - Negative addresses such as "-23 TB" are absolute addresses in bytes, counted down
+ from the top of the 64-bit address space. It's easier to understand the layout
+ when seen both in absolute addresses and in distance-from-top notation.
+
+ For example 0xffffe90000000000 == -23 TB, it's 23 TB lower than the top of the
+ 64-bit address space (ffffffffffffffff).
+
+ Note that as we get closer to the top of the address space, the notation changes
+ from TB to GB and then MB/KB.
+
+ - "16M TB" might look weird at first sight, but it's an easier to visualize size
+ notation than "16 EB", which few will recognize at first sight as 16 exabytes.
+ It also shows it nicely how incredibly large 64-bit address space is.
+
+::
+
+ ========================================================================================================================
+ Start addr | Offset | End addr | Size | VM area description
+ ========================================================================================================================
+ | | | |
+ 0000000000000000 | 0 | 00007fffffffffff | 128 TB | user-space virtual memory, different per mm
+ __________________|____________|__________________|_________|___________________________________________________________
+ | | | |
+ 0000800000000000 | +128 TB | ffff7fffffffffff | ~16M TB | ... huge, almost 64 bits wide hole of non-canonical
+ | | | | virtual memory addresses up to the -128 TB
+ | | | | starting offset of kernel mappings.
+ __________________|____________|__________________|_________|___________________________________________________________
+ |
+ | Kernel-space virtual memory, shared between all processes:
+ ____________________________________________________________|___________________________________________________________
+ | | | |
+ ffff800000000000 | -128 TB | ffff87ffffffffff | 8 TB | ... guard hole, also reserved for hypervisor
+ ffff880000000000 | -120 TB | ffff887fffffffff | 0.5 TB | LDT remap for PTI
+ ffff888000000000 | -119.5 TB | ffffc87fffffffff | 64 TB | direct mapping of all physical memory (page_offset_base)
+ ffffc88000000000 | -55.5 TB | ffffc8ffffffffff | 0.5 TB | ... unused hole
+ ffffc90000000000 | -55 TB | ffffe8ffffffffff | 32 TB | vmalloc/ioremap space (vmalloc_base)
+ ffffe90000000000 | -23 TB | ffffe9ffffffffff | 1 TB | ... unused hole
+ ffffea0000000000 | -22 TB | ffffeaffffffffff | 1 TB | virtual memory map (vmemmap_base)
+ ffffeb0000000000 | -21 TB | ffffebffffffffff | 1 TB | ... unused hole
+ ffffec0000000000 | -20 TB | fffffbffffffffff | 16 TB | KASAN shadow memory
+ __________________|____________|__________________|_________|____________________________________________________________
+ |
+ | Identical layout to the 56-bit one from here on:
+ ____________________________________________________________|____________________________________________________________
+ | | | |
+ fffffc0000000000 | -4 TB | fffffdffffffffff | 2 TB | ... unused hole
+ | | | | vaddr_end for KASLR
+ fffffe0000000000 | -2 TB | fffffe7fffffffff | 0.5 TB | cpu_entry_area mapping
+ fffffe8000000000 | -1.5 TB | fffffeffffffffff | 0.5 TB | ... unused hole
+ ffffff0000000000 | -1 TB | ffffff7fffffffff | 0.5 TB | %esp fixup stacks
+ ffffff8000000000 | -512 GB | ffffffeeffffffff | 444 GB | ... unused hole
+ ffffffef00000000 | -68 GB | fffffffeffffffff | 64 GB | EFI region mapping space
+ ffffffff00000000 | -4 GB | ffffffff7fffffff | 2 GB | ... unused hole
+ ffffffff80000000 | -2 GB | ffffffff9fffffff | 512 MB | kernel text mapping, mapped to physical address 0
+ ffffffff80000000 |-2048 MB | | |
+ ffffffffa0000000 |-1536 MB | fffffffffeffffff | 1520 MB | module mapping space
+ ffffffffff000000 | -16 MB | | |
+ FIXADDR_START | ~-11 MB | ffffffffff5fffff | ~0.5 MB | kernel-internal fixmap range, variable size and offset
+ ffffffffff600000 | -10 MB | ffffffffff600fff | 4 kB | legacy vsyscall ABI
+ ffffffffffe00000 | -2 MB | ffffffffffffffff | 2 MB | ... unused hole
+ __________________|____________|__________________|_________|___________________________________________________________
+
+
+Complete virtual memory map with 5-level page tables
+====================================================
+
+.. note::
+
+ - With 56-bit addresses, user-space memory gets expanded by a factor of 512x,
+ from 0.125 PB to 64 PB. All kernel mappings shift down to the -64 PT starting
+ offset and many of the regions expand to support the much larger physical
+ memory supported.
+
+::
+
+ ========================================================================================================================
+ Start addr | Offset | End addr | Size | VM area description
+ ========================================================================================================================
+ | | | |
+ 0000000000000000 | 0 | 00ffffffffffffff | 64 PB | user-space virtual memory, different per mm
+ __________________|____________|__________________|_________|___________________________________________________________
+ | | | |
+ 0000800000000000 | +64 PB | ffff7fffffffffff | ~16K PB | ... huge, still almost 64 bits wide hole of non-canonical
+ | | | | virtual memory addresses up to the -64 PB
+ | | | | starting offset of kernel mappings.
+ __________________|____________|__________________|_________|___________________________________________________________
+ |
+ | Kernel-space virtual memory, shared between all processes:
+ ____________________________________________________________|___________________________________________________________
+ | | | |
+ ff00000000000000 | -64 PB | ff0fffffffffffff | 4 PB | ... guard hole, also reserved for hypervisor
+ ff10000000000000 | -60 PB | ff10ffffffffffff | 0.25 PB | LDT remap for PTI
+ ff11000000000000 | -59.75 PB | ff90ffffffffffff | 32 PB | direct mapping of all physical memory (page_offset_base)
+ ff91000000000000 | -27.75 PB | ff9fffffffffffff | 3.75 PB | ... unused hole
+ ffa0000000000000 | -24 PB | ffd1ffffffffffff | 12.5 PB | vmalloc/ioremap space (vmalloc_base)
+ ffd2000000000000 | -11.5 PB | ffd3ffffffffffff | 0.5 PB | ... unused hole
+ ffd4000000000000 | -11 PB | ffd5ffffffffffff | 0.5 PB | virtual memory map (vmemmap_base)
+ ffd6000000000000 | -10.5 PB | ffdeffffffffffff | 2.25 PB | ... unused hole
+ ffdf000000000000 | -8.25 PB | fffffdffffffffff | ~8 PB | KASAN shadow memory
+ __________________|____________|__________________|_________|____________________________________________________________
+ |
+ | Identical layout to the 47-bit one from here on:
+ ____________________________________________________________|____________________________________________________________
+ | | | |
+ fffffc0000000000 | -4 TB | fffffdffffffffff | 2 TB | ... unused hole
+ | | | | vaddr_end for KASLR
+ fffffe0000000000 | -2 TB | fffffe7fffffffff | 0.5 TB | cpu_entry_area mapping
+ fffffe8000000000 | -1.5 TB | fffffeffffffffff | 0.5 TB | ... unused hole
+ ffffff0000000000 | -1 TB | ffffff7fffffffff | 0.5 TB | %esp fixup stacks
+ ffffff8000000000 | -512 GB | ffffffeeffffffff | 444 GB | ... unused hole
+ ffffffef00000000 | -68 GB | fffffffeffffffff | 64 GB | EFI region mapping space
+ ffffffff00000000 | -4 GB | ffffffff7fffffff | 2 GB | ... unused hole
+ ffffffff80000000 | -2 GB | ffffffff9fffffff | 512 MB | kernel text mapping, mapped to physical address 0
+ ffffffff80000000 |-2048 MB | | |
+ ffffffffa0000000 |-1536 MB | fffffffffeffffff | 1520 MB | module mapping space
+ ffffffffff000000 | -16 MB | | |
+ FIXADDR_START | ~-11 MB | ffffffffff5fffff | ~0.5 MB | kernel-internal fixmap range, variable size and offset
+ ffffffffff600000 | -10 MB | ffffffffff600fff | 4 kB | legacy vsyscall ABI
+ ffffffffffe00000 | -2 MB | ffffffffffffffff | 2 MB | ... unused hole
+ __________________|____________|__________________|_________|___________________________________________________________
+
+Architecture defines a 64-bit virtual address. Implementations can support
+less. Currently supported are 48- and 57-bit virtual addresses. Bits 63
+through to the most-significant implemented bit are sign extended.
+This causes hole between user space and kernel addresses if you interpret them
+as unsigned.
+
+The direct mapping covers all memory in the system up to the highest
+memory address (this means in some cases it can also include PCI memory
+holes).
+
+vmalloc space is lazily synchronized into the different PML4/PML5 pages of
+the processes using the page fault handler, with init_top_pgt as
+reference.
+
+We map EFI runtime services in the 'efi_pgd' PGD in a 64Gb large virtual
+memory window (this size is arbitrary, it can be raised later if needed).
+The mappings are not part of any other kernel PGD and are only available
+during EFI runtime calls.
+
+Note that if CONFIG_RANDOMIZE_MEMORY is enabled, the direct mapping of all
+physical memory, vmalloc/ioremap space and virtual memory map are randomized.
+Their order is preserved but their base will be offset early at boot time.
+
+Be very careful vs. KASLR when changing anything here. The KASLR address
+range must not overlap with anything except the KASAN shadow area, which is
+correct as KASAN disables KASLR.
+
+For both 4- and 5-level layouts, the STACKLEAK_POISON value in the last 2MB
+hole: ffffffffffff4111
diff --git a/Documentation/x86/x86_64/mm.txt b/Documentation/x86/x86_64/mm.txt
deleted file mode 100644
index 804f9426ed17..000000000000
--- a/Documentation/x86/x86_64/mm.txt
+++ /dev/null
@@ -1,153 +0,0 @@
-====================================================
-Complete virtual memory map with 4-level page tables
-====================================================
-
-Notes:
-
- - Negative addresses such as "-23 TB" are absolute addresses in bytes, counted down
- from the top of the 64-bit address space. It's easier to understand the layout
- when seen both in absolute addresses and in distance-from-top notation.
-
- For example 0xffffe90000000000 == -23 TB, it's 23 TB lower than the top of the
- 64-bit address space (ffffffffffffffff).
-
- Note that as we get closer to the top of the address space, the notation changes
- from TB to GB and then MB/KB.
-
- - "16M TB" might look weird at first sight, but it's an easier to visualize size
- notation than "16 EB", which few will recognize at first sight as 16 exabytes.
- It also shows it nicely how incredibly large 64-bit address space is.
-
-========================================================================================================================
- Start addr | Offset | End addr | Size | VM area description
-========================================================================================================================
- | | | |
- 0000000000000000 | 0 | 00007fffffffffff | 128 TB | user-space virtual memory, different per mm
-__________________|____________|__________________|_________|___________________________________________________________
- | | | |
- 0000800000000000 | +128 TB | ffff7fffffffffff | ~16M TB | ... huge, almost 64 bits wide hole of non-canonical
- | | | | virtual memory addresses up to the -128 TB
- | | | | starting offset of kernel mappings.
-__________________|____________|__________________|_________|___________________________________________________________
- |
- | Kernel-space virtual memory, shared between all processes:
-____________________________________________________________|___________________________________________________________
- | | | |
- ffff800000000000 | -128 TB | ffff87ffffffffff | 8 TB | ... guard hole, also reserved for hypervisor
- ffff880000000000 | -120 TB | ffff887fffffffff | 0.5 TB | LDT remap for PTI
- ffff888000000000 | -119.5 TB | ffffc87fffffffff | 64 TB | direct mapping of all physical memory (page_offset_base)
- ffffc88000000000 | -55.5 TB | ffffc8ffffffffff | 0.5 TB | ... unused hole
- ffffc90000000000 | -55 TB | ffffe8ffffffffff | 32 TB | vmalloc/ioremap space (vmalloc_base)
- ffffe90000000000 | -23 TB | ffffe9ffffffffff | 1 TB | ... unused hole
- ffffea0000000000 | -22 TB | ffffeaffffffffff | 1 TB | virtual memory map (vmemmap_base)
- ffffeb0000000000 | -21 TB | ffffebffffffffff | 1 TB | ... unused hole
- ffffec0000000000 | -20 TB | fffffbffffffffff | 16 TB | KASAN shadow memory
-__________________|____________|__________________|_________|____________________________________________________________
- |
- | Identical layout to the 56-bit one from here on:
-____________________________________________________________|____________________________________________________________
- | | | |
- fffffc0000000000 | -4 TB | fffffdffffffffff | 2 TB | ... unused hole
- | | | | vaddr_end for KASLR
- fffffe0000000000 | -2 TB | fffffe7fffffffff | 0.5 TB | cpu_entry_area mapping
- fffffe8000000000 | -1.5 TB | fffffeffffffffff | 0.5 TB | ... unused hole
- ffffff0000000000 | -1 TB | ffffff7fffffffff | 0.5 TB | %esp fixup stacks
- ffffff8000000000 | -512 GB | ffffffeeffffffff | 444 GB | ... unused hole
- ffffffef00000000 | -68 GB | fffffffeffffffff | 64 GB | EFI region mapping space
- ffffffff00000000 | -4 GB | ffffffff7fffffff | 2 GB | ... unused hole
- ffffffff80000000 | -2 GB | ffffffff9fffffff | 512 MB | kernel text mapping, mapped to physical address 0
- ffffffff80000000 |-2048 MB | | |
- ffffffffa0000000 |-1536 MB | fffffffffeffffff | 1520 MB | module mapping space
- ffffffffff000000 | -16 MB | | |
- FIXADDR_START | ~-11 MB | ffffffffff5fffff | ~0.5 MB | kernel-internal fixmap range, variable size and offset
- ffffffffff600000 | -10 MB | ffffffffff600fff | 4 kB | legacy vsyscall ABI
- ffffffffffe00000 | -2 MB | ffffffffffffffff | 2 MB | ... unused hole
-__________________|____________|__________________|_________|___________________________________________________________
-
-
-====================================================
-Complete virtual memory map with 5-level page tables
-====================================================
-
-Notes:
-
- - With 56-bit addresses, user-space memory gets expanded by a factor of 512x,
- from 0.125 PB to 64 PB. All kernel mappings shift down to the -64 PT starting
- offset and many of the regions expand to support the much larger physical
- memory supported.
-
-========================================================================================================================
- Start addr | Offset | End addr | Size | VM area description
-========================================================================================================================
- | | | |
- 0000000000000000 | 0 | 00ffffffffffffff | 64 PB | user-space virtual memory, different per mm
-__________________|____________|__________________|_________|___________________________________________________________
- | | | |
- 0000800000000000 | +64 PB | ffff7fffffffffff | ~16K PB | ... huge, still almost 64 bits wide hole of non-canonical
- | | | | virtual memory addresses up to the -64 PB
- | | | | starting offset of kernel mappings.
-__________________|____________|__________________|_________|___________________________________________________________
- |
- | Kernel-space virtual memory, shared between all processes:
-____________________________________________________________|___________________________________________________________
- | | | |
- ff00000000000000 | -64 PB | ff0fffffffffffff | 4 PB | ... guard hole, also reserved for hypervisor
- ff10000000000000 | -60 PB | ff10ffffffffffff | 0.25 PB | LDT remap for PTI
- ff11000000000000 | -59.75 PB | ff90ffffffffffff | 32 PB | direct mapping of all physical memory (page_offset_base)
- ff91000000000000 | -27.75 PB | ff9fffffffffffff | 3.75 PB | ... unused hole
- ffa0000000000000 | -24 PB | ffd1ffffffffffff | 12.5 PB | vmalloc/ioremap space (vmalloc_base)
- ffd2000000000000 | -11.5 PB | ffd3ffffffffffff | 0.5 PB | ... unused hole
- ffd4000000000000 | -11 PB | ffd5ffffffffffff | 0.5 PB | virtual memory map (vmemmap_base)
- ffd6000000000000 | -10.5 PB | ffdeffffffffffff | 2.25 PB | ... unused hole
- ffdf000000000000 | -8.25 PB | fffffdffffffffff | ~8 PB | KASAN shadow memory
-__________________|____________|__________________|_________|____________________________________________________________
- |
- | Identical layout to the 47-bit one from here on:
-____________________________________________________________|____________________________________________________________
- | | | |
- fffffc0000000000 | -4 TB | fffffdffffffffff | 2 TB | ... unused hole
- | | | | vaddr_end for KASLR
- fffffe0000000000 | -2 TB | fffffe7fffffffff | 0.5 TB | cpu_entry_area mapping
- fffffe8000000000 | -1.5 TB | fffffeffffffffff | 0.5 TB | ... unused hole
- ffffff0000000000 | -1 TB | ffffff7fffffffff | 0.5 TB | %esp fixup stacks
- ffffff8000000000 | -512 GB | ffffffeeffffffff | 444 GB | ... unused hole
- ffffffef00000000 | -68 GB | fffffffeffffffff | 64 GB | EFI region mapping space
- ffffffff00000000 | -4 GB | ffffffff7fffffff | 2 GB | ... unused hole
- ffffffff80000000 | -2 GB | ffffffff9fffffff | 512 MB | kernel text mapping, mapped to physical address 0
- ffffffff80000000 |-2048 MB | | |
- ffffffffa0000000 |-1536 MB | fffffffffeffffff | 1520 MB | module mapping space
- ffffffffff000000 | -16 MB | | |
- FIXADDR_START | ~-11 MB | ffffffffff5fffff | ~0.5 MB | kernel-internal fixmap range, variable size and offset
- ffffffffff600000 | -10 MB | ffffffffff600fff | 4 kB | legacy vsyscall ABI
- ffffffffffe00000 | -2 MB | ffffffffffffffff | 2 MB | ... unused hole
-__________________|____________|__________________|_________|___________________________________________________________
-
-Architecture defines a 64-bit virtual address. Implementations can support
-less. Currently supported are 48- and 57-bit virtual addresses. Bits 63
-through to the most-significant implemented bit are sign extended.
-This causes hole between user space and kernel addresses if you interpret them
-as unsigned.
-
-The direct mapping covers all memory in the system up to the highest
-memory address (this means in some cases it can also include PCI memory
-holes).
-
-vmalloc space is lazily synchronized into the different PML4/PML5 pages of
-the processes using the page fault handler, with init_top_pgt as
-reference.
-
-We map EFI runtime services in the 'efi_pgd' PGD in a 64Gb large virtual
-memory window (this size is arbitrary, it can be raised later if needed).
-The mappings are not part of any other kernel PGD and are only available
-during EFI runtime calls.
-
-Note that if CONFIG_RANDOMIZE_MEMORY is enabled, the direct mapping of all
-physical memory, vmalloc/ioremap space and virtual memory map are randomized.
-Their order is preserved but their base will be offset early at boot time.
-
-Be very careful vs. KASLR when changing anything here. The KASLR address
-range must not overlap with anything except the KASAN shadow area, which is
-correct as KASAN disables KASLR.
-
-For both 4- and 5-level layouts, the STACKLEAK_POISON value in the last 2MB
-hole: ffffffffffff4111
--
2.20.1
^ permalink raw reply related
* [PATCH v4 60/63] Documentation: x86: convert x86_64/5level-paging.txt to reST
From: Changbin Du @ 2019-04-23 16:29 UTC (permalink / raw)
To: Jonathan Corbet
Cc: fenghua.yu, mchehab+samsung, linux-doc, linux-pci, linux-gpio,
x86, rjw, linux-kernel, linux-acpi, mingo, Bjorn Helgaas, tglx,
linuxppc-dev, Changbin Du
In-Reply-To: <20190423162932.21428-1-changbin.du@gmail.com>
This converts the plain text documentation to reStructuredText format and
add it to Sphinx TOC tree. No essential content change.
Signed-off-by: Changbin Du <changbin.du@gmail.com>
---
.../{5level-paging.txt => 5level-paging.rst} | 16 +++++++++++-----
Documentation/x86/x86_64/index.rst | 1 +
2 files changed, 12 insertions(+), 5 deletions(-)
rename Documentation/x86/x86_64/{5level-paging.txt => 5level-paging.rst} (91%)
diff --git a/Documentation/x86/x86_64/5level-paging.txt b/Documentation/x86/x86_64/5level-paging.rst
similarity index 91%
rename from Documentation/x86/x86_64/5level-paging.txt
rename to Documentation/x86/x86_64/5level-paging.rst
index 2432a5ef86d9..ab88a4514163 100644
--- a/Documentation/x86/x86_64/5level-paging.txt
+++ b/Documentation/x86/x86_64/5level-paging.rst
@@ -1,5 +1,11 @@
-== Overview ==
+.. SPDX-License-Identifier: GPL-2.0
+==============
+5-level paging
+==============
+
+Overview
+========
Original x86-64 was limited by 4-level paing to 256 TiB of virtual address
space and 64 TiB of physical address space. We are already bumping into
this limit: some vendors offers servers with 64 TiB of memory today.
@@ -16,16 +22,17 @@ QEMU 2.9 and later support 5-level paging.
Virtual memory layout for 5-level paging is described in
Documentation/x86/x86_64/mm.txt
-== Enabling 5-level paging ==
+Enabling 5-level paging
+=======================
CONFIG_X86_5LEVEL=y enables the feature.
Kernel with CONFIG_X86_5LEVEL=y still able to boot on 4-level hardware.
In this case additional page table level -- p4d -- will be folded at
runtime.
-== User-space and large virtual address space ==
-
+User-space and large virtual address space
+==========================================
On x86, 5-level paging enables 56-bit userspace virtual address space.
Not all user space is ready to handle wide addresses. It's known that
at least some JIT compilers use higher bits in pointers to encode their
@@ -58,4 +65,3 @@ One important case we need to handle here is interaction with MPX.
MPX (without MAWA extension) cannot handle addresses above 47-bit, so we
need to make sure that MPX cannot be enabled we already have VMA above
the boundary and forbid creating such VMAs once MPX is enabled.
-
diff --git a/Documentation/x86/x86_64/index.rst b/Documentation/x86/x86_64/index.rst
index 4b65d29ef459..7b8c82151358 100644
--- a/Documentation/x86/x86_64/index.rst
+++ b/Documentation/x86/x86_64/index.rst
@@ -10,3 +10,4 @@ x86_64 Support
boot-options
uefi
mm
+ 5level-paging
--
2.20.1
^ permalink raw reply related
* [PATCH v4 61/63] Documentation: x86: convert x86_64/fake-numa-for-cpusets to reST
From: Changbin Du @ 2019-04-23 16:29 UTC (permalink / raw)
To: Jonathan Corbet
Cc: fenghua.yu, mchehab+samsung, linux-doc, linux-pci, linux-gpio,
x86, rjw, linux-kernel, linux-acpi, mingo, Bjorn Helgaas, tglx,
linuxppc-dev, Changbin Du
In-Reply-To: <20190423162932.21428-1-changbin.du@gmail.com>
This converts the plain text documentation to reStructuredText format and
add it to Sphinx TOC tree. No essential content change.
Signed-off-by: Changbin Du <changbin.du@gmail.com>
---
...a-for-cpusets => fake-numa-for-cpusets.rst} | 18 +++++++++++++-----
Documentation/x86/x86_64/index.rst | 1 +
2 files changed, 14 insertions(+), 5 deletions(-)
rename Documentation/x86/x86_64/{fake-numa-for-cpusets => fake-numa-for-cpusets.rst} (90%)
diff --git a/Documentation/x86/x86_64/fake-numa-for-cpusets b/Documentation/x86/x86_64/fake-numa-for-cpusets.rst
similarity index 90%
rename from Documentation/x86/x86_64/fake-numa-for-cpusets
rename to Documentation/x86/x86_64/fake-numa-for-cpusets.rst
index 4b09f18831f8..3c23f45d38f6 100644
--- a/Documentation/x86/x86_64/fake-numa-for-cpusets
+++ b/Documentation/x86/x86_64/fake-numa-for-cpusets.rst
@@ -1,5 +1,12 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+=====================
+Fake NUMA For CPUSets
+=====================
+
+:Author: David Rientjes <rientjes@cs.washington.edu>
+
Using numa=fake and CPUSets for Resource Management
-Written by David Rientjes <rientjes@cs.washington.edu>
This document describes how the numa=fake x86_64 command-line option can be used
in conjunction with cpusets for coarse memory management. Using this feature,
@@ -20,7 +27,7 @@ you become more familiar with using this combination for resource control,
you'll determine a better setup to minimize the number of nodes you have to deal
with.
-A machine may be split as follows with "numa=fake=4*512," as reported by dmesg:
+A machine may be split as follows with "numa=fake=4*512," as reported by dmesg::
Faking node 0 at 0000000000000000-0000000020000000 (512MB)
Faking node 1 at 0000000020000000-0000000040000000 (512MB)
@@ -34,7 +41,7 @@ A machine may be split as follows with "numa=fake=4*512," as reported by dmesg:
Now following the instructions for mounting the cpusets filesystem from
Documentation/cgroup-v1/cpusets.txt, you can assign fake nodes (i.e. contiguous memory
-address spaces) to individual cpusets:
+address spaces) to individual cpusets::
[root@xroads /]# mkdir exampleset
[root@xroads /]# mount -t cpuset none exampleset
@@ -47,7 +54,7 @@ Now this cpuset, 'ddset', will only allowed access to fake nodes 0 and 1 for
memory allocations (1G).
You can now assign tasks to these cpusets to limit the memory resources
-available to them according to the fake nodes assigned as mems:
+available to them according to the fake nodes assigned as mems::
[root@xroads /exampleset/ddset]# echo $$ > tasks
[root@xroads /exampleset/ddset]# dd if=/dev/zero of=tmp bs=1024 count=1G
@@ -56,7 +63,8 @@ available to them according to the fake nodes assigned as mems:
Notice the difference between the system memory usage as reported by
/proc/meminfo between the restricted cpuset case above and the unrestricted
case (i.e. running the same 'dd' command without assigning it to a fake NUMA
-cpuset):
+cpuset)::
+
Unrestricted Restricted
MemTotal: 3091900 kB 3091900 kB
MemFree: 42113 kB 1513236 kB
diff --git a/Documentation/x86/x86_64/index.rst b/Documentation/x86/x86_64/index.rst
index 7b8c82151358..e2a324cde671 100644
--- a/Documentation/x86/x86_64/index.rst
+++ b/Documentation/x86/x86_64/index.rst
@@ -11,3 +11,4 @@ x86_64 Support
uefi
mm
5level-paging
+ fake-numa-for-cpusets
--
2.20.1
^ permalink raw reply related
* [PATCH v4 62/63] Documentation: x86: convert x86_64/cpu-hotplug-spec to reST
From: Changbin Du @ 2019-04-23 16:29 UTC (permalink / raw)
To: Jonathan Corbet
Cc: fenghua.yu, mchehab+samsung, linux-doc, linux-pci, linux-gpio,
x86, rjw, linux-kernel, linux-acpi, mingo, Bjorn Helgaas, tglx,
linuxppc-dev, Changbin Du
In-Reply-To: <20190423162932.21428-1-changbin.du@gmail.com>
This converts the plain text documentation to reStructuredText format and
add it to Sphinx TOC tree. No essential content change.
Signed-off-by: Changbin Du <changbin.du@gmail.com>
---
.../x86/x86_64/{cpu-hotplug-spec => cpu-hotplug-spec.rst} | 5 ++++-
Documentation/x86/x86_64/index.rst | 1 +
2 files changed, 5 insertions(+), 1 deletion(-)
rename Documentation/x86/x86_64/{cpu-hotplug-spec => cpu-hotplug-spec.rst} (88%)
diff --git a/Documentation/x86/x86_64/cpu-hotplug-spec b/Documentation/x86/x86_64/cpu-hotplug-spec.rst
similarity index 88%
rename from Documentation/x86/x86_64/cpu-hotplug-spec
rename to Documentation/x86/x86_64/cpu-hotplug-spec.rst
index 3c23e0587db3..8d1c91f0c880 100644
--- a/Documentation/x86/x86_64/cpu-hotplug-spec
+++ b/Documentation/x86/x86_64/cpu-hotplug-spec.rst
@@ -1,5 +1,8 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+===================================================
Firmware support for CPU hotplug under Linux/x86-64
----------------------------------------------------
+===================================================
Linux/x86-64 supports CPU hotplug now. For various reasons Linux wants to
know in advance of boot time the maximum number of CPUs that could be plugged
diff --git a/Documentation/x86/x86_64/index.rst b/Documentation/x86/x86_64/index.rst
index e2a324cde671..c04b6eab3c76 100644
--- a/Documentation/x86/x86_64/index.rst
+++ b/Documentation/x86/x86_64/index.rst
@@ -12,3 +12,4 @@ x86_64 Support
mm
5level-paging
fake-numa-for-cpusets
+ cpu-hotplug-spec
--
2.20.1
^ permalink raw reply related
* [PATCH v4 63/63] Documentation: x86: convert x86_64/machinecheck to reST
From: Changbin Du @ 2019-04-23 16:29 UTC (permalink / raw)
To: Jonathan Corbet
Cc: fenghua.yu, mchehab+samsung, linux-doc, linux-pci, linux-gpio,
x86, rjw, linux-kernel, linux-acpi, mingo, Bjorn Helgaas, tglx,
linuxppc-dev, Changbin Du
In-Reply-To: <20190423162932.21428-1-changbin.du@gmail.com>
This converts the plain text documentation to reStructuredText format and
add it to Sphinx TOC tree. No essential content change.
Signed-off-by: Changbin Du <changbin.du@gmail.com>
---
Documentation/x86/x86_64/index.rst | 1 +
.../x86/x86_64/{machinecheck => machinecheck.rst} | 11 ++++++-----
2 files changed, 7 insertions(+), 5 deletions(-)
rename Documentation/x86/x86_64/{machinecheck => machinecheck.rst} (92%)
diff --git a/Documentation/x86/x86_64/index.rst b/Documentation/x86/x86_64/index.rst
index c04b6eab3c76..d6eaaa5a35fc 100644
--- a/Documentation/x86/x86_64/index.rst
+++ b/Documentation/x86/x86_64/index.rst
@@ -13,3 +13,4 @@ x86_64 Support
5level-paging
fake-numa-for-cpusets
cpu-hotplug-spec
+ machinecheck
diff --git a/Documentation/x86/x86_64/machinecheck b/Documentation/x86/x86_64/machinecheck.rst
similarity index 92%
rename from Documentation/x86/x86_64/machinecheck
rename to Documentation/x86/x86_64/machinecheck.rst
index d0648a74fceb..8e9d2d529a8d 100644
--- a/Documentation/x86/x86_64/machinecheck
+++ b/Documentation/x86/x86_64/machinecheck.rst
@@ -1,5 +1,8 @@
+.. SPDX-License-Identifier: GPL-2.0
-Configurable sysfs parameters for the x86-64 machine check code.
+===============================================================
+Configurable sysfs parameters for the x86-64 machine check code
+===============================================================
Machine checks report internal hardware error conditions detected
by the CPU. Uncorrected errors typically cause a machine check
@@ -16,14 +19,12 @@ log then mcelog should run to collect and decode machine check entries
from /dev/mcelog. Normally mcelog should be run regularly from a cronjob.
Each CPU has a directory in /sys/devices/system/machinecheck/machinecheckN
-(N = CPU number)
+(N = CPU number).
The directory contains some configurable entries:
-Entries:
-
bankNctl
-(N bank number)
+ (N bank number)
64bit Hex bitmask enabling/disabling specific subevents for bank N
When a bit in the bitmask is zero then the respective
subevent will not be reported.
--
2.20.1
^ permalink raw reply related
* Re: [PATCH v4 02/63] Documentation: ACPI: move namespace.txt to firmware-guide/acpi and convert to reST
From: Mauro Carvalho Chehab @ 2019-04-23 20:38 UTC (permalink / raw)
To: Changbin Du
Cc: fenghua.yu, x86, linux-doc, linux-pci, linux-gpio,
Jonathan Corbet, rjw, linux-kernel, linux-acpi, mingo,
Bjorn Helgaas, tglx, linuxppc-dev
In-Reply-To: <20190423162932.21428-3-changbin.du@gmail.com>
Em Wed, 24 Apr 2019 00:28:31 +0800
Changbin Du <changbin.du@gmail.com> escreveu:
> This converts the plain text documentation to reStructuredText format and
> add it to Sphinx TOC tree. No essential content change.
>
> Signed-off-by: Changbin Du <changbin.du@gmail.com>
> ---
> Documentation/firmware-guide/acpi/index.rst | 1 +
> .../acpi/namespace.rst} | 310 +++++++++---------
> 2 files changed, 161 insertions(+), 150 deletions(-)
> rename Documentation/{acpi/namespace.txt => firmware-guide/acpi/namespace.rst} (54%)
>
> diff --git a/Documentation/firmware-guide/acpi/index.rst b/Documentation/firmware-guide/acpi/index.rst
> index 0ec7d072ba22..210ad8acd6df 100644
> --- a/Documentation/firmware-guide/acpi/index.rst
> +++ b/Documentation/firmware-guide/acpi/index.rst
> @@ -7,3 +7,4 @@ ACPI Support
> .. toctree::
> :maxdepth: 1
>
> + namespace
> diff --git a/Documentation/acpi/namespace.txt b/Documentation/firmware-guide/acpi/namespace.rst
> similarity index 54%
> rename from Documentation/acpi/namespace.txt
> rename to Documentation/firmware-guide/acpi/namespace.rst
> index 1860cb3865c6..443f0e5d0617 100644
> --- a/Documentation/acpi/namespace.txt
> +++ b/Documentation/firmware-guide/acpi/namespace.rst
> @@ -1,85 +1,88 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +.. include:: <isonum.txt>
> +
> +===================================================
> ACPI Device Tree - Representation of ACPI Namespace
> +===================================================
> +
> +:Copyright: |copy| 2013, Intel Corporation
> +
> +:Author: Lv Zheng <lv.zheng@intel.com>
> +
> +:Abstract: The Linux ACPI subsystem converts ACPI namespace objects into a Linux
> + device tree under the /sys/devices/LNXSYSTEM:00 and updates it upon
> + receiving ACPI hotplug notification events. For each device object
> + in this hierarchy there is a corresponding symbolic link in the
> + /sys/bus/acpi/devices.
> + This document illustrates the structure of the ACPI device tree.
Well, this is a matter of preference. I would add Abstract as a chapter,
as this would make it part of the top index, with can be useful.
In any case:
Reviewed-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
> +
> +:Credit: Thanks for the help from Zhang Rui <rui.zhang@intel.com> and
> + Rafael J.Wysocki <rafael.j.wysocki@intel.com>.
> +
> +
> +ACPI Definition Blocks
> +======================
> +
> +The ACPI firmware sets up RSDP (Root System Description Pointer) in the
> +system memory address space pointing to the XSDT (Extended System
> +Description Table). The XSDT always points to the FADT (Fixed ACPI
> +Description Table) using its first entry, the data within the FADT
> +includes various fixed-length entries that describe fixed ACPI features
> +of the hardware. The FADT contains a pointer to the DSDT
> +(Differentiated System Descripition Table). The XSDT also contains
> +entries pointing to possibly multiple SSDTs (Secondary System
> +Description Table).
> +
> +The DSDT and SSDT data is organized in data structures called definition
> +blocks that contain definitions of various objects, including ACPI
> +control methods, encoded in AML (ACPI Machine Language). The data block
> +of the DSDT along with the contents of SSDTs represents a hierarchical
> +data structure called the ACPI namespace whose topology reflects the
> +structure of the underlying hardware platform.
> +
> +The relationships between ACPI System Definition Tables described above
> +are illustrated in the following diagram::
> +
> + +---------+ +-------+ +--------+ +------------------------+
> + | RSDP | +->| XSDT | +->| FADT | | +-------------------+ |
> + +---------+ | +-------+ | +--------+ +-|->| DSDT | |
> + | Pointer | | | Entry |-+ | ...... | | | +-------------------+ |
> + +---------+ | +-------+ | X_DSDT |--+ | | Definition Blocks | |
> + | Pointer |-+ | ..... | | ...... | | +-------------------+ |
> + +---------+ +-------+ +--------+ | +-------------------+ |
> + | Entry |------------------|->| SSDT | |
> + +- - - -+ | +-------------------| |
> + | Entry | - - - - - - - -+ | | Definition Blocks | |
> + +- - - -+ | | +-------------------+ |
> + | | +- - - - - - - - - -+ |
> + +-|->| SSDT | |
> + | +-------------------+ |
> + | | Definition Blocks | |
> + | +- - - - - - - - - -+ |
> + +------------------------+
> + |
> + OSPM Loading |
> + \|/
> + +----------------+
> + | ACPI Namespace |
> + +----------------+
> +
> + Figure 1. ACPI Definition Blocks
> +
> +.. note:: RSDP can also contain a pointer to the RSDT (Root System
> + Description Table). Platforms provide RSDT to enable
> + compatibility with ACPI 1.0 operating systems. The OS is expected
> + to use XSDT, if present.
> +
> +
> +Example ACPI Namespace
> +======================
> +
> +All definition blocks are loaded into a single namespace. The namespace
> +is a hierarchy of objects identified by names and paths.
> +The following naming conventions apply to object names in the ACPI
> +namespace:
>
> -Copyright (C) 2013, Intel Corporation
> -Author: Lv Zheng <lv.zheng@intel.com>
> -
> -
> -Abstract:
> -
> -The Linux ACPI subsystem converts ACPI namespace objects into a Linux
> -device tree under the /sys/devices/LNXSYSTEM:00 and updates it upon
> -receiving ACPI hotplug notification events. For each device object in this
> -hierarchy there is a corresponding symbolic link in the
> -/sys/bus/acpi/devices.
> -This document illustrates the structure of the ACPI device tree.
> -
> -
> -Credit:
> -
> -Thanks for the help from Zhang Rui <rui.zhang@intel.com> and Rafael J.
> -Wysocki <rafael.j.wysocki@intel.com>.
> -
> -
> -1. ACPI Definition Blocks
> -
> - The ACPI firmware sets up RSDP (Root System Description Pointer) in the
> - system memory address space pointing to the XSDT (Extended System
> - Description Table). The XSDT always points to the FADT (Fixed ACPI
> - Description Table) using its first entry, the data within the FADT
> - includes various fixed-length entries that describe fixed ACPI features
> - of the hardware. The FADT contains a pointer to the DSDT
> - (Differentiated System Descripition Table). The XSDT also contains
> - entries pointing to possibly multiple SSDTs (Secondary System
> - Description Table).
> -
> - The DSDT and SSDT data is organized in data structures called definition
> - blocks that contain definitions of various objects, including ACPI
> - control methods, encoded in AML (ACPI Machine Language). The data block
> - of the DSDT along with the contents of SSDTs represents a hierarchical
> - data structure called the ACPI namespace whose topology reflects the
> - structure of the underlying hardware platform.
> -
> - The relationships between ACPI System Definition Tables described above
> - are illustrated in the following diagram.
> -
> - +---------+ +-------+ +--------+ +------------------------+
> - | RSDP | +->| XSDT | +->| FADT | | +-------------------+ |
> - +---------+ | +-------+ | +--------+ +-|->| DSDT | |
> - | Pointer | | | Entry |-+ | ...... | | | +-------------------+ |
> - +---------+ | +-------+ | X_DSDT |--+ | | Definition Blocks | |
> - | Pointer |-+ | ..... | | ...... | | +-------------------+ |
> - +---------+ +-------+ +--------+ | +-------------------+ |
> - | Entry |------------------|->| SSDT | |
> - +- - - -+ | +-------------------| |
> - | Entry | - - - - - - - -+ | | Definition Blocks | |
> - +- - - -+ | | +-------------------+ |
> - | | +- - - - - - - - - -+ |
> - +-|->| SSDT | |
> - | +-------------------+ |
> - | | Definition Blocks | |
> - | +- - - - - - - - - -+ |
> - +------------------------+
> - |
> - OSPM Loading |
> - \|/
> - +----------------+
> - | ACPI Namespace |
> - +----------------+
> -
> - Figure 1. ACPI Definition Blocks
> -
> - NOTE: RSDP can also contain a pointer to the RSDT (Root System
> - Description Table). Platforms provide RSDT to enable
> - compatibility with ACPI 1.0 operating systems. The OS is expected
> - to use XSDT, if present.
> -
> -
> -2. Example ACPI Namespace
> -
> - All definition blocks are loaded into a single namespace. The namespace
> - is a hierarchy of objects identified by names and paths.
> - The following naming conventions apply to object names in the ACPI
> - namespace:
> 1. All names are 32 bits long.
> 2. The first byte of a name must be one of 'A' - 'Z', '_'.
> 3. Each of the remaining bytes of a name must be one of 'A' - 'Z', '0'
> @@ -91,7 +94,7 @@ Wysocki <rafael.j.wysocki@intel.com>.
> (i.e. names prepended with '^' are relative to the parent of the
> current namespace node).
>
> - The figure below shows an example ACPI namespace.
> +The figure below shows an example ACPI namespace::
>
> +------+
> | \ | Root
> @@ -184,19 +187,20 @@ Wysocki <rafael.j.wysocki@intel.com>.
> Figure 2. Example ACPI Namespace
>
>
> -3. Linux ACPI Device Objects
> +Linux ACPI Device Objects
> +=========================
>
> - The Linux kernel's core ACPI subsystem creates struct acpi_device
> - objects for ACPI namespace objects representing devices, power resources
> - processors, thermal zones. Those objects are exported to user space via
> - sysfs as directories in the subtree under /sys/devices/LNXSYSTM:00. The
> - format of their names is <bus_id:instance>, where 'bus_id' refers to the
> - ACPI namespace representation of the given object and 'instance' is used
> - for distinguishing different object of the same 'bus_id' (it is
> - two-digit decimal representation of an unsigned integer).
> +The Linux kernel's core ACPI subsystem creates struct acpi_device
> +objects for ACPI namespace objects representing devices, power resources
> +processors, thermal zones. Those objects are exported to user space via
> +sysfs as directories in the subtree under /sys/devices/LNXSYSTM:00. The
> +format of their names is <bus_id:instance>, where 'bus_id' refers to the
> +ACPI namespace representation of the given object and 'instance' is used
> +for distinguishing different object of the same 'bus_id' (it is
> +two-digit decimal representation of an unsigned integer).
>
> - The value of 'bus_id' depends on the type of the object whose name it is
> - part of as listed in the table below.
> +The value of 'bus_id' depends on the type of the object whose name it is
> +part of as listed in the table below::
>
> +---+-----------------+-------+----------+
> | | Object/Feature | Table | bus_id |
> @@ -226,10 +230,11 @@ Wysocki <rafael.j.wysocki@intel.com>.
>
> Table 1. ACPI Namespace Objects Mapping
>
> - The following rules apply when creating struct acpi_device objects on
> - the basis of the contents of ACPI System Description Tables (as
> - indicated by the letter in the first column and the notation in the
> - second column of the table above):
> +The following rules apply when creating struct acpi_device objects on
> +the basis of the contents of ACPI System Description Tables (as
> +indicated by the letter in the first column and the notation in the
> +second column of the table above):
> +
> N:
> The object's source is an ACPI namespace node (as indicated by the
> named object's type in the second column). In that case the object's
> @@ -249,13 +254,14 @@ Wysocki <rafael.j.wysocki@intel.com>.
> struct acpi_device object with LNXVIDEO 'bus_id' will be created for
> it.
>
> - The third column of the above table indicates which ACPI System
> - Description Tables contain information used for the creation of the
> - struct acpi_device objects represented by the given row (xSDT means DSDT
> - or SSDT).
> +The third column of the above table indicates which ACPI System
> +Description Tables contain information used for the creation of the
> +struct acpi_device objects represented by the given row (xSDT means DSDT
> +or SSDT).
> +
> +The forth column of the above table indicates the 'bus_id' generation
> +rule of the struct acpi_device object:
>
> - The forth column of the above table indicates the 'bus_id' generation
> - rule of the struct acpi_device object:
> _HID:
> _HID in the last column of the table means that the object's bus_id
> is derived from the _HID/_CID identification objects present under
> @@ -275,45 +281,47 @@ Wysocki <rafael.j.wysocki@intel.com>.
> object's bus_id.
>
>
> -4. Linux ACPI Physical Device Glue
> -
> - ACPI device (i.e. struct acpi_device) objects may be linked to other
> - objects in the Linux' device hierarchy that represent "physical" devices
> - (for example, devices on the PCI bus). If that happens, it means that
> - the ACPI device object is a "companion" of a device otherwise
> - represented in a different way and is used (1) to provide configuration
> - information on that device which cannot be obtained by other means and
> - (2) to do specific things to the device with the help of its ACPI
> - control methods. One ACPI device object may be linked this way to
> - multiple "physical" devices.
> -
> - If an ACPI device object is linked to a "physical" device, its sysfs
> - directory contains the "physical_node" symbolic link to the sysfs
> - directory of the target device object. In turn, the target device's
> - sysfs directory will then contain the "firmware_node" symbolic link to
> - the sysfs directory of the companion ACPI device object.
> - The linking mechanism relies on device identification provided by the
> - ACPI namespace. For example, if there's an ACPI namespace object
> - representing a PCI device (i.e. a device object under an ACPI namespace
> - object representing a PCI bridge) whose _ADR returns 0x00020000 and the
> - bus number of the parent PCI bridge is 0, the sysfs directory
> - representing the struct acpi_device object created for that ACPI
> - namespace object will contain the 'physical_node' symbolic link to the
> - /sys/devices/pci0000:00/0000:00:02:0/ sysfs directory of the
> - corresponding PCI device.
> -
> - The linking mechanism is generally bus-specific. The core of its
> - implementation is located in the drivers/acpi/glue.c file, but there are
> - complementary parts depending on the bus types in question located
> - elsewhere. For example, the PCI-specific part of it is located in
> - drivers/pci/pci-acpi.c.
> -
> -
> -5. Example Linux ACPI Device Tree
> -
> - The sysfs hierarchy of struct acpi_device objects corresponding to the
> - example ACPI namespace illustrated in Figure 2 with the addition of
> - fixed PWR_BUTTON/SLP_BUTTON devices is shown below.
> +Linux ACPI Physical Device Glue
> +===============================
> +
> +ACPI device (i.e. struct acpi_device) objects may be linked to other
> +objects in the Linux' device hierarchy that represent "physical" devices
> +(for example, devices on the PCI bus). If that happens, it means that
> +the ACPI device object is a "companion" of a device otherwise
> +represented in a different way and is used (1) to provide configuration
> +information on that device which cannot be obtained by other means and
> +(2) to do specific things to the device with the help of its ACPI
> +control methods. One ACPI device object may be linked this way to
> +multiple "physical" devices.
> +
> +If an ACPI device object is linked to a "physical" device, its sysfs
> +directory contains the "physical_node" symbolic link to the sysfs
> +directory of the target device object. In turn, the target device's
> +sysfs directory will then contain the "firmware_node" symbolic link to
> +the sysfs directory of the companion ACPI device object.
> +The linking mechanism relies on device identification provided by the
> +ACPI namespace. For example, if there's an ACPI namespace object
> +representing a PCI device (i.e. a device object under an ACPI namespace
> +object representing a PCI bridge) whose _ADR returns 0x00020000 and the
> +bus number of the parent PCI bridge is 0, the sysfs directory
> +representing the struct acpi_device object created for that ACPI
> +namespace object will contain the 'physical_node' symbolic link to the
> +/sys/devices/pci0000:00/0000:00:02:0/ sysfs directory of the
> +corresponding PCI device.
> +
> +The linking mechanism is generally bus-specific. The core of its
> +implementation is located in the drivers/acpi/glue.c file, but there are
> +complementary parts depending on the bus types in question located
> +elsewhere. For example, the PCI-specific part of it is located in
> +drivers/pci/pci-acpi.c.
> +
> +
> +Example Linux ACPI Device Tree
> +=================================
> +
> +The sysfs hierarchy of struct acpi_device objects corresponding to the
> +example ACPI namespace illustrated in Figure 2 with the addition of
> +fixed PWR_BUTTON/SLP_BUTTON devices is shown below::
>
> +--------------+---+-----------------+
> | LNXSYSTEM:00 | \ | acpi:LNXSYSTEM: |
> @@ -377,12 +385,14 @@ Wysocki <rafael.j.wysocki@intel.com>.
>
> Figure 3. Example Linux ACPI Device Tree
>
> - NOTE: Each node is represented as "object/path/modalias", where:
> - 1. 'object' is the name of the object's directory in sysfs.
> - 2. 'path' is the ACPI namespace path of the corresponding
> - ACPI namespace object, as returned by the object's 'path'
> - sysfs attribute.
> - 3. 'modalias' is the value of the object's 'modalias' sysfs
> - attribute (as described earlier in this document).
> - NOTE: N/A indicates the device object does not have the 'path' or the
> - 'modalias' attribute.
> +.. note:: Each node is represented as "object/path/modalias", where:
> +
> + 1. 'object' is the name of the object's directory in sysfs.
> + 2. 'path' is the ACPI namespace path of the corresponding
> + ACPI namespace object, as returned by the object's 'path'
> + sysfs attribute.
> + 3. 'modalias' is the value of the object's 'modalias' sysfs
> + attribute (as described earlier in this document).
> +
> +.. note:: N/A indicates the device object does not have the 'path' or the
> + 'modalias' attribute.
Thanks,
Mauro
^ permalink raw reply
* Re: [PATCH v4 01/63] Documentation: add Linux ACPI to Sphinx TOC tree
From: Mauro Carvalho Chehab @ 2019-04-23 20:39 UTC (permalink / raw)
To: Changbin Du
Cc: fenghua.yu, x86, linux-doc, linux-pci, linux-gpio,
Jonathan Corbet, rjw, linux-kernel, linux-acpi, mingo,
Bjorn Helgaas, tglx, linuxppc-dev
In-Reply-To: <20190423162932.21428-2-changbin.du@gmail.com>
Em Wed, 24 Apr 2019 00:28:30 +0800
Changbin Du <changbin.du@gmail.com> escreveu:
> Add below index.rst files for ACPI subsystem. More docs will be added later.
> o admin-guide/acpi/index.rst
> o driver-api/acpi/index.rst
> o firmware-guide/index.rst
Nice! you split it by usage.
Reviewed-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
>
> Signed-off-by: Changbin Du <changbin.du@gmail.com>
> ---
> Documentation/admin-guide/acpi/index.rst | 10 ++++++++++
> Documentation/admin-guide/index.rst | 1 +
> Documentation/driver-api/acpi/index.rst | 7 +++++++
> Documentation/driver-api/index.rst | 1 +
> Documentation/firmware-guide/acpi/index.rst | 9 +++++++++
> Documentation/firmware-guide/index.rst | 13 +++++++++++++
> Documentation/index.rst | 10 ++++++++++
> 7 files changed, 51 insertions(+)
> create mode 100644 Documentation/admin-guide/acpi/index.rst
> create mode 100644 Documentation/driver-api/acpi/index.rst
> create mode 100644 Documentation/firmware-guide/acpi/index.rst
> create mode 100644 Documentation/firmware-guide/index.rst
>
> diff --git a/Documentation/admin-guide/acpi/index.rst b/Documentation/admin-guide/acpi/index.rst
> new file mode 100644
> index 000000000000..3e041206089d
> --- /dev/null
> +++ b/Documentation/admin-guide/acpi/index.rst
> @@ -0,0 +1,10 @@
> +============
> +ACPI Support
> +============
> +
> +Here we document in detail how to interact with various mechanisms in
> +the Linux ACPI support.
> +
> +.. toctree::
> + :maxdepth: 1
> +
> diff --git a/Documentation/admin-guide/index.rst b/Documentation/admin-guide/index.rst
> index 0a491676685e..5b8286fdd91b 100644
> --- a/Documentation/admin-guide/index.rst
> +++ b/Documentation/admin-guide/index.rst
> @@ -77,6 +77,7 @@ configure specific aspects of kernel behavior to your liking.
> LSM/index
> mm/index
> perf-security
> + acpi/index
>
> .. only:: subproject and html
>
> diff --git a/Documentation/driver-api/acpi/index.rst b/Documentation/driver-api/acpi/index.rst
> new file mode 100644
> index 000000000000..898b0c60671a
> --- /dev/null
> +++ b/Documentation/driver-api/acpi/index.rst
> @@ -0,0 +1,7 @@
> +============
> +ACPI Support
> +============
> +
> +.. toctree::
> + :maxdepth: 2
> +
> diff --git a/Documentation/driver-api/index.rst b/Documentation/driver-api/index.rst
> index c0b600ed9961..aa87075c7846 100644
> --- a/Documentation/driver-api/index.rst
> +++ b/Documentation/driver-api/index.rst
> @@ -56,6 +56,7 @@ available subsections can be seen below.
> slimbus
> soundwire/index
> fpga/index
> + acpi/index
>
> .. only:: subproject and html
>
> diff --git a/Documentation/firmware-guide/acpi/index.rst b/Documentation/firmware-guide/acpi/index.rst
> new file mode 100644
> index 000000000000..0ec7d072ba22
> --- /dev/null
> +++ b/Documentation/firmware-guide/acpi/index.rst
> @@ -0,0 +1,9 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +
> +============
> +ACPI Support
> +============
> +
> +.. toctree::
> + :maxdepth: 1
> +
> diff --git a/Documentation/firmware-guide/index.rst b/Documentation/firmware-guide/index.rst
> new file mode 100644
> index 000000000000..5355784ca0a2
> --- /dev/null
> +++ b/Documentation/firmware-guide/index.rst
> @@ -0,0 +1,13 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +
> +===============================
> +The Linux kernel firmware guide
> +===============================
> +
> +This section describes the ACPI subsystem in Linux from firmware perspective.
> +
> +.. toctree::
> + :maxdepth: 1
> +
> + acpi/index
> +
> diff --git a/Documentation/index.rst b/Documentation/index.rst
> index 80a421cb935e..fdfa85c56a50 100644
> --- a/Documentation/index.rst
> +++ b/Documentation/index.rst
> @@ -35,6 +35,16 @@ trying to get it to work optimally on a given system.
>
> admin-guide/index
>
> +Firmware-related documentation
> +------------------------------
> +The following holds information on the kernel's expectations regarding the
> +platform firmwares.
> +
> +.. toctree::
> + :maxdepth: 2
> +
> + firmware-guide/index
> +
> Application-developer documentation
> -----------------------------------
>
Thanks,
Mauro
^ permalink raw reply
* Re: [PATCH v4 03/63] Documentation: ACPI: move enumeration.txt to firmware-guide/acpi and convert to reST
From: Mauro Carvalho Chehab @ 2019-04-23 20:42 UTC (permalink / raw)
To: Changbin Du
Cc: fenghua.yu, x86, linux-doc, linux-pci, linux-gpio,
Jonathan Corbet, rjw, linux-kernel, linux-acpi, mingo,
Bjorn Helgaas, tglx, linuxppc-dev
In-Reply-To: <20190423162932.21428-4-changbin.du@gmail.com>
Em Wed, 24 Apr 2019 00:28:32 +0800
Changbin Du <changbin.du@gmail.com> escreveu:
> This converts the plain text documentation to reStructuredText format and
> add it to Sphinx TOC tree. No essential content change.
Just looking at the conversion itself, it looks good to me.
Reviewed-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
>
> Signed-off-by: Changbin Du <changbin.du@gmail.com>
> ---
> .../acpi/enumeration.rst} | 135 ++++++++++--------
> Documentation/firmware-guide/acpi/index.rst | 1 +
> 2 files changed, 74 insertions(+), 62 deletions(-)
> rename Documentation/{acpi/enumeration.txt => firmware-guide/acpi/enumeration.rst} (87%)
>
> diff --git a/Documentation/acpi/enumeration.txt b/Documentation/firmware-guide/acpi/enumeration.rst
> similarity index 87%
> rename from Documentation/acpi/enumeration.txt
> rename to Documentation/firmware-guide/acpi/enumeration.rst
> index 7bcf9c3d9fbe..ce755e963714 100644
> --- a/Documentation/acpi/enumeration.txt
> +++ b/Documentation/firmware-guide/acpi/enumeration.rst
> @@ -1,5 +1,9 @@
> -ACPI based device enumeration
> -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +.. SPDX-License-Identifier: GPL-2.0
> +
> +=============================
> +ACPI Based Device Enumeration
> +=============================
> +
> ACPI 5 introduced a set of new resources (UartTSerialBus, I2cSerialBus,
> SpiSerialBus, GpioIo and GpioInt) which can be used in enumerating slave
> devices behind serial bus controllers.
> @@ -11,12 +15,12 @@ that are accessed through memory-mapped registers.
> In order to support this and re-use the existing drivers as much as
> possible we decided to do following:
>
> - o Devices that have no bus connector resource are represented as
> - platform devices.
> + - Devices that have no bus connector resource are represented as
> + platform devices.
>
> - o Devices behind real busses where there is a connector resource
> - are represented as struct spi_device or struct i2c_device
> - (standard UARTs are not busses so there is no struct uart_device).
> + - Devices behind real busses where there is a connector resource
> + are represented as struct spi_device or struct i2c_device
> + (standard UARTs are not busses so there is no struct uart_device).
>
> As both ACPI and Device Tree represent a tree of devices (and their
> resources) this implementation follows the Device Tree way as much as
> @@ -31,7 +35,8 @@ enumerated from ACPI namespace. This handle can be used to extract other
> device-specific configuration. There is an example of this below.
>
> Platform bus support
> -~~~~~~~~~~~~~~~~~~~~
> +====================
> +
> Since we are using platform devices to represent devices that are not
> connected to any physical bus we only need to implement a platform driver
> for the device and add supported ACPI IDs. If this same IP-block is used on
> @@ -39,7 +44,7 @@ some other non-ACPI platform, the driver might work out of the box or needs
> some minor changes.
>
> Adding ACPI support for an existing driver should be pretty
> -straightforward. Here is the simplest example:
> +straightforward. Here is the simplest example::
>
> #ifdef CONFIG_ACPI
> static const struct acpi_device_id mydrv_acpi_match[] = {
> @@ -61,12 +66,13 @@ configuring GPIOs it can get its ACPI handle and extract this information
> from ACPI tables.
>
> DMA support
> -~~~~~~~~~~~
> +===========
> +
> DMA controllers enumerated via ACPI should be registered in the system to
> provide generic access to their resources. For example, a driver that would
> like to be accessible to slave devices via generic API call
> dma_request_slave_channel() must register itself at the end of the probe
> -function like this:
> +function like this::
>
> err = devm_acpi_dma_controller_register(dev, xlate_func, dw);
> /* Handle the error if it's not a case of !CONFIG_ACPI */
> @@ -74,7 +80,7 @@ function like this:
> and implement custom xlate function if needed (usually acpi_dma_simple_xlate()
> is enough) which converts the FixedDMA resource provided by struct
> acpi_dma_spec into the corresponding DMA channel. A piece of code for that case
> -could look like:
> +could look like::
>
> #ifdef CONFIG_ACPI
> struct filter_args {
> @@ -114,7 +120,7 @@ provided by struct acpi_dma.
> Clients must call dma_request_slave_channel() with the string parameter that
> corresponds to a specific FixedDMA resource. By default "tx" means the first
> entry of the FixedDMA resource array, "rx" means the second entry. The table
> -below shows a layout:
> +below shows a layout::
>
> Device (I2C0)
> {
> @@ -138,12 +144,13 @@ acpi_dma_request_slave_chan_by_index() directly and therefore choose the
> specific FixedDMA resource by its index.
>
> SPI serial bus support
> -~~~~~~~~~~~~~~~~~~~~~~
> +======================
> +
> Slave devices behind SPI bus have SpiSerialBus resource attached to them.
> This is extracted automatically by the SPI core and the slave devices are
> enumerated once spi_register_master() is called by the bus driver.
>
> -Here is what the ACPI namespace for a SPI slave might look like:
> +Here is what the ACPI namespace for a SPI slave might look like::
>
> Device (EEP0)
> {
> @@ -163,7 +170,7 @@ Here is what the ACPI namespace for a SPI slave might look like:
>
> The SPI device drivers only need to add ACPI IDs in a similar way than with
> the platform device drivers. Below is an example where we add ACPI support
> -to at25 SPI eeprom driver (this is meant for the above ACPI snippet):
> +to at25 SPI eeprom driver (this is meant for the above ACPI snippet)::
>
> #ifdef CONFIG_ACPI
> static const struct acpi_device_id at25_acpi_match[] = {
> @@ -182,7 +189,7 @@ to at25 SPI eeprom driver (this is meant for the above ACPI snippet):
>
> Note that this driver actually needs more information like page size of the
> eeprom etc. but at the time writing this there is no standard way of
> -passing those. One idea is to return this in _DSM method like:
> +passing those. One idea is to return this in _DSM method like::
>
> Device (EEP0)
> {
> @@ -202,7 +209,7 @@ passing those. One idea is to return this in _DSM method like:
> }
>
> Then the at25 SPI driver can get this configuration by calling _DSM on its
> -ACPI handle like:
> +ACPI handle like::
>
> struct acpi_buffer output = { ACPI_ALLOCATE_BUFFER, NULL };
> struct acpi_object_list input;
> @@ -220,14 +227,15 @@ ACPI handle like:
> kfree(output.pointer);
>
> I2C serial bus support
> -~~~~~~~~~~~~~~~~~~~~~~
> +======================
> +
> The slaves behind I2C bus controller only need to add the ACPI IDs like
> with the platform and SPI drivers. The I2C core automatically enumerates
> any slave devices behind the controller device once the adapter is
> registered.
>
> Below is an example of how to add ACPI support to the existing mpu3050
> -input driver:
> +input driver::
>
> #ifdef CONFIG_ACPI
> static const struct acpi_device_id mpu3050_acpi_match[] = {
> @@ -251,56 +259,57 @@ input driver:
> };
>
> GPIO support
> -~~~~~~~~~~~~
> +============
> +
> ACPI 5 introduced two new resources to describe GPIO connections: GpioIo
> and GpioInt. These resources can be used to pass GPIO numbers used by
> the device to the driver. ACPI 5.1 extended this with _DSD (Device
> Specific Data) which made it possible to name the GPIOs among other things.
>
> -For example:
> +For example::
>
> -Device (DEV)
> -{
> - Method (_CRS, 0, NotSerialized)
> + Device (DEV)
> {
> - Name (SBUF, ResourceTemplate()
> + Method (_CRS, 0, NotSerialized)
> {
> - ...
> - // Used to power on/off the device
> - GpioIo (Exclusive, PullDefault, 0x0000, 0x0000,
> - IoRestrictionOutputOnly, "\\_SB.PCI0.GPI0",
> - 0x00, ResourceConsumer,,)
> + Name (SBUF, ResourceTemplate()
> {
> - // Pin List
> - 0x0055
> - }
> + ...
> + // Used to power on/off the device
> + GpioIo (Exclusive, PullDefault, 0x0000, 0x0000,
> + IoRestrictionOutputOnly, "\\_SB.PCI0.GPI0",
> + 0x00, ResourceConsumer,,)
> + {
> + // Pin List
> + 0x0055
> + }
> +
> + // Interrupt for the device
> + GpioInt (Edge, ActiveHigh, ExclusiveAndWake, PullNone,
> + 0x0000, "\\_SB.PCI0.GPI0", 0x00, ResourceConsumer,,)
> + {
> + // Pin list
> + 0x0058
> + }
> +
> + ...
>
> - // Interrupt for the device
> - GpioInt (Edge, ActiveHigh, ExclusiveAndWake, PullNone,
> - 0x0000, "\\_SB.PCI0.GPI0", 0x00, ResourceConsumer,,)
> - {
> - // Pin list
> - 0x0058
> }
>
> - ...
> -
> + Return (SBUF)
> }
>
> - Return (SBUF)
> - }
> -
> - // ACPI 5.1 _DSD used for naming the GPIOs
> - Name (_DSD, Package ()
> - {
> - ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
> - Package ()
> + // ACPI 5.1 _DSD used for naming the GPIOs
> + Name (_DSD, Package ()
> {
> - Package () {"power-gpios", Package() {^DEV, 0, 0, 0 }},
> - Package () {"irq-gpios", Package() {^DEV, 1, 0, 0 }},
> - }
> - })
> - ...
> + ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
> + Package ()
> + {
> + Package () {"power-gpios", Package() {^DEV, 0, 0, 0 }},
> + Package () {"irq-gpios", Package() {^DEV, 1, 0, 0 }},
> + }
> + })
> + ...
>
> These GPIO numbers are controller relative and path "\\_SB.PCI0.GPI0"
> specifies the path to the controller. In order to use these GPIOs in Linux
> @@ -310,7 +319,7 @@ There is a standard GPIO API for that and is documented in
> Documentation/gpio/.
>
> In the above example we can get the corresponding two GPIO descriptors with
> -a code like this:
> +a code like this::
>
> #include <linux/gpio/consumer.h>
> ...
> @@ -334,21 +343,22 @@ See Documentation/acpi/gpio-properties.txt for more information about the
> _DSD binding related to GPIOs.
>
> MFD devices
> -~~~~~~~~~~~
> +===========
> +
> The MFD devices register their children as platform devices. For the child
> devices there needs to be an ACPI handle that they can use to reference
> parts of the ACPI namespace that relate to them. In the Linux MFD subsystem
> we provide two ways:
>
> - o The children share the parent ACPI handle.
> - o The MFD cell can specify the ACPI id of the device.
> + - The children share the parent ACPI handle.
> + - The MFD cell can specify the ACPI id of the device.
>
> For the first case, the MFD drivers do not need to do anything. The
> resulting child platform device will have its ACPI_COMPANION() set to point
> to the parent device.
>
> If the ACPI namespace has a device that we can match using an ACPI id or ACPI
> -adr, the cell should be set like:
> +adr, the cell should be set like::
>
> static struct mfd_cell_acpi_match my_subdevice_cell_acpi_match = {
> .pnpid = "XYZ0001",
> @@ -366,7 +376,8 @@ the MFD device and if found, that ACPI companion device is bound to the
> resulting child platform device.
>
> Device Tree namespace link device ID
> -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +====================================
> +
> The Device Tree protocol uses device identification based on the "compatible"
> property whose value is a string or an array of strings recognized as device
> identifiers by drivers and the driver core. The set of all those strings may be
> @@ -423,4 +434,4 @@ the _DSD of the device object itself or the _DSD of its ancestor in the
> Otherwise, the _DSD itself is regarded as invalid and therefore the "compatible"
> property returned by it is meaningless.
>
> -Refer to DSD-properties-rules.txt for more information.
> +Refer to :doc:`DSD-properties-rules` for more information.
> diff --git a/Documentation/firmware-guide/acpi/index.rst b/Documentation/firmware-guide/acpi/index.rst
> index 210ad8acd6df..99677c73f1fb 100644
> --- a/Documentation/firmware-guide/acpi/index.rst
> +++ b/Documentation/firmware-guide/acpi/index.rst
> @@ -8,3 +8,4 @@ ACPI Support
> :maxdepth: 1
>
> namespace
> + enumeration
Thanks,
Mauro
^ permalink raw reply
* Re: [PATCH v4 04/63] Documentation: ACPI: move osi.txt to firmware-guide/acpi and convert to reST
From: Mauro Carvalho Chehab @ 2019-04-23 20:44 UTC (permalink / raw)
To: Changbin Du
Cc: fenghua.yu, x86, linux-doc, linux-pci, linux-gpio,
Jonathan Corbet, rjw, linux-kernel, linux-acpi, mingo,
Bjorn Helgaas, tglx, linuxppc-dev
In-Reply-To: <20190423162932.21428-5-changbin.du@gmail.com>
Em Wed, 24 Apr 2019 00:28:33 +0800
Changbin Du <changbin.du@gmail.com> escreveu:
> This converts the plain text documentation to reStructuredText format and
> add it to Sphinx TOC tree. No essential content change.
>
> Signed-off-by: Changbin Du <changbin.du@gmail.com>
> ---
> Documentation/firmware-guide/acpi/index.rst | 1 +
> .../{acpi/osi.txt => firmware-guide/acpi/osi.rst} | 15 +++++++++------
> 2 files changed, 10 insertions(+), 6 deletions(-)
> rename Documentation/{acpi/osi.txt => firmware-guide/acpi/osi.rst} (97%)
>
> diff --git a/Documentation/firmware-guide/acpi/index.rst b/Documentation/firmware-guide/acpi/index.rst
> index 99677c73f1fb..868bd25a3398 100644
> --- a/Documentation/firmware-guide/acpi/index.rst
> +++ b/Documentation/firmware-guide/acpi/index.rst
> @@ -9,3 +9,4 @@ ACPI Support
>
> namespace
> enumeration
> + osi
> diff --git a/Documentation/acpi/osi.txt b/Documentation/firmware-guide/acpi/osi.rst
> similarity index 97%
> rename from Documentation/acpi/osi.txt
> rename to Documentation/firmware-guide/acpi/osi.rst
> index 50cde0ceb9b0..29e9ef79ebc0 100644
> --- a/Documentation/acpi/osi.txt
> +++ b/Documentation/firmware-guide/acpi/osi.rst
> @@ -1,5 +1,8 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +
> +==========================
> ACPI _OSI and _REV methods
> ---------------------------
> +==========================
You could probably do just the above, but changing the title
markups on the other files has the advantage of using the
same standard on all acpi files.
Either way, just looking at the conversion itself:
Reviewed-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
>
> An ACPI BIOS can use the "Operating System Interfaces" method (_OSI)
> to find out what the operating system supports. Eg. If BIOS
> @@ -14,7 +17,7 @@ This document explains how and why the BIOS and Linux should use these methods.
> It also explains how and why they are widely misused.
>
> How to use _OSI
> ----------------
> +===============
>
> Linux runs on two groups of machines -- those that are tested by the OEM
> to be compatible with Linux, and those that were never tested with Linux,
> @@ -62,7 +65,7 @@ the string when that support is added to the kernel.
> That was easy. Read on, to find out how to do it wrong.
>
> Before _OSI, there was _OS
> ---------------------------
> +==========================
>
> ACPI 1.0 specified "_OS" as an
> "object that evaluates to a string that identifies the operating system."
> @@ -96,7 +99,7 @@ That is the *only* viable strategy, as that is what modern Windows does,
> and so doing otherwise could steer the BIOS down an untested path.
>
> _OSI is born, and immediately misused
> ---------------------------------------
> +=====================================
>
> With _OSI, the *BIOS* provides the string describing an interface,
> and asks the OS: "YES/NO, are you compatible with this interface?"
> @@ -144,7 +147,7 @@ catastrophic failure resulting from the BIOS taking paths that
> were never validated under *any* OS.
>
> Do not use _REV
> ----------------
> +===============
>
> Since _OSI("Linux") went away, some BIOS writers used _REV
> to support Linux and Windows differences in the same BIOS.
> @@ -164,7 +167,7 @@ from mid-2015 onward. The ACPI specification will also be updated
> to reflect that _REV is deprecated, and always returns 2.
>
> Apple Mac and _OSI("Darwin")
> -----------------------------
> +============================
>
> On Apple's Mac platforms, the ACPI BIOS invokes _OSI("Darwin")
> to determine if the machine is running Apple OSX.
Thanks,
Mauro
^ permalink raw reply
* Re: [PATCH v4 05/63] Documentation: ACPI: move linuxized-acpica.txt to driver-api/acpi and convert to reST
From: Mauro Carvalho Chehab @ 2019-04-23 20:50 UTC (permalink / raw)
To: Changbin Du
Cc: fenghua.yu, x86, linux-doc, linux-pci, linux-gpio,
Jonathan Corbet, rjw, linux-kernel, linux-acpi, mingo,
Bjorn Helgaas, tglx, linuxppc-dev
In-Reply-To: <20190423162932.21428-6-changbin.du@gmail.com>
Em Wed, 24 Apr 2019 00:28:34 +0800
Changbin Du <changbin.du@gmail.com> escreveu:
> This converts the plain text documentation to reStructuredText format and
> add it to Sphinx TOC tree. No essential content change.
>
> Signed-off-by: Changbin Du <changbin.du@gmail.com>
> ---
> Documentation/driver-api/acpi/index.rst | 1 +
> .../acpi/linuxized-acpica.rst} | 115 ++++++++++--------
> 2 files changed, 66 insertions(+), 50 deletions(-)
> rename Documentation/{acpi/linuxized-acpica.txt => driver-api/acpi/linuxized-acpica.rst} (78%)
>
> diff --git a/Documentation/driver-api/acpi/index.rst b/Documentation/driver-api/acpi/index.rst
> index 898b0c60671a..12649947b19b 100644
> --- a/Documentation/driver-api/acpi/index.rst
> +++ b/Documentation/driver-api/acpi/index.rst
> @@ -5,3 +5,4 @@ ACPI Support
> .. toctree::
> :maxdepth: 2
>
> + linuxized-acpica
> diff --git a/Documentation/acpi/linuxized-acpica.txt b/Documentation/driver-api/acpi/linuxized-acpica.rst
> similarity index 78%
> rename from Documentation/acpi/linuxized-acpica.txt
> rename to Documentation/driver-api/acpi/linuxized-acpica.rst
> index 3ad7b0dfb083..f8aaea668e41 100644
> --- a/Documentation/acpi/linuxized-acpica.txt
> +++ b/Documentation/driver-api/acpi/linuxized-acpica.rst
> @@ -1,31 +1,35 @@
> -Linuxized ACPICA - Introduction to ACPICA Release Automation
> +.. SPDX-License-Identifier: GPL-2.0
> +.. include:: <isonum.txt>
>
> -Copyright (C) 2013-2016, Intel Corporation
> -Author: Lv Zheng <lv.zheng@intel.com>
> +============================================================
> +Linuxized ACPICA - Introduction to ACPICA Release Automation
> +============================================================
>
> +:Copyright: |copy| 2013-2016, Intel Corporation
>
> -Abstract:
> +:Author: Lv Zheng <lv.zheng@intel.com>
>
> -This document describes the ACPICA project and the relationship between
> -ACPICA and Linux. It also describes how ACPICA code in drivers/acpi/acpica,
> -include/acpi and tools/power/acpi is automatically updated to follow the
> -upstream.
> +:Abstract: This document describes the ACPICA project and the relationship
> + between ACPICA and Linux. It also describes how ACPICA code in
> + drivers/acpi/acpica, include/acpi and tools/power/acpi is
> + automatically updated to follow the upstream.
>
Same comment as on patch 02: I would keep the abstracts as a chapter,
in order to make them visible at the index, as this may help readers
to quickly look at the document's contents.
I'm sure other APCI documents also have abstracts. So, please consider
this comment also for the other docs.
Anyway, this is just a suggestion. I'm also fine with the above.
Either way, for the conversion itself:
Reviewed-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
>
> -1. ACPICA Project
> +ACPICA Project
> +==============
>
> - The ACPI Component Architecture (ACPICA) project provides an operating
> - system (OS)-independent reference implementation of the Advanced
> - Configuration and Power Interface Specification (ACPI). It has been
> - adapted by various host OSes. By directly integrating ACPICA, Linux can
> - also benefit from the application experiences of ACPICA from other host
> - OSes.
> +The ACPI Component Architecture (ACPICA) project provides an operating
> +system (OS)-independent reference implementation of the Advanced
> +Configuration and Power Interface Specification (ACPI). It has been
> +adapted by various host OSes. By directly integrating ACPICA, Linux can
> +also benefit from the application experiences of ACPICA from other host
> +OSes.
>
> - The homepage of ACPICA project is: www.acpica.org, it is maintained and
> - supported by Intel Corporation.
> +The homepage of ACPICA project is: www.acpica.org, it is maintained and
> +supported by Intel Corporation.
>
> - The following figure depicts the Linux ACPI subsystem where the ACPICA
> - adaptation is included:
> +The following figure depicts the Linux ACPI subsystem where the ACPICA
> +adaptation is included::
>
> +---------------------------------------------------------+
> | |
> @@ -71,21 +75,27 @@ upstream.
>
> Figure 1. Linux ACPI Software Components
>
> - NOTE:
> +.. note::
> A. OS Service Layer - Provided by Linux to offer OS dependent
> implementation of the predefined ACPICA interfaces (acpi_os_*).
> + ::
> +
> include/acpi/acpiosxf.h
> drivers/acpi/osl.c
> include/acpi/platform
> include/asm/acenv.h
> B. ACPICA Functionality - Released from ACPICA code base to offer
> OS independent implementation of the ACPICA interfaces (acpi_*).
> + ::
> +
> drivers/acpi/acpica
> include/acpi/ac*.h
> tools/power/acpi
> C. Linux/ACPI Functionality - Providing Linux specific ACPI
> functionality to the other Linux kernel subsystems and user space
> programs.
> + ::
> +
> drivers/acpi
> include/linux/acpi.h
> include/linux/acpi*.h
> @@ -95,24 +105,27 @@ upstream.
> ACPI subsystem to offer architecture specific implementation of the
> ACPI interfaces. They are Linux specific components and are out of
> the scope of this document.
> + ::
> +
> include/asm/acpi.h
> include/asm/acpi*.h
> arch/*/acpi
>
> -2. ACPICA Release
> +ACPICA Release
> +==============
>
> - The ACPICA project maintains its code base at the following repository URL:
> - https://github.com/acpica/acpica.git. As a rule, a release is made every
> - month.
> +The ACPICA project maintains its code base at the following repository URL:
> +https://github.com/acpica/acpica.git. As a rule, a release is made every
> +month.
>
> - As the coding style adopted by the ACPICA project is not acceptable by
> - Linux, there is a release process to convert the ACPICA git commits into
> - Linux patches. The patches generated by this process are referred to as
> - "linuxized ACPICA patches". The release process is carried out on a local
> - copy the ACPICA git repository. Each commit in the monthly release is
> - converted into a linuxized ACPICA patch. Together, they form the monthly
> - ACPICA release patchset for the Linux ACPI community. This process is
> - illustrated in the following figure:
> +As the coding style adopted by the ACPICA project is not acceptable by
> +Linux, there is a release process to convert the ACPICA git commits into
> +Linux patches. The patches generated by this process are referred to as
> +"linuxized ACPICA patches". The release process is carried out on a local
> +copy the ACPICA git repository. Each commit in the monthly release is
> +converted into a linuxized ACPICA patch. Together, they form the monthly
> +ACPICA release patchset for the Linux ACPI community. This process is
> +illustrated in the following figure::
>
> +-----------------------------+
> | acpica / master (-) commits |
> @@ -153,7 +166,7 @@ upstream.
>
> Figure 2. ACPICA -> Linux Upstream Process
>
> - NOTE:
> +.. note::
> A. Linuxize Utilities - Provided by the ACPICA repository, including a
> utility located in source/tools/acpisrc folder and a number of
> scripts located in generate/linux folder.
> @@ -170,19 +183,20 @@ upstream.
> following kernel configuration options:
> CONFIG_ACPI/CONFIG_ACPI_DEBUG/CONFIG_ACPI_DEBUGGER
>
> -3. ACPICA Divergences
> +ACPICA Divergences
> +==================
>
> - Ideally, all of the ACPICA commits should be converted into Linux patches
> - automatically without manual modifications, the "linux / master" tree should
> - contain the ACPICA code that exactly corresponds to the ACPICA code
> - contained in "new linuxized acpica" tree and it should be possible to run
> - the release process fully automatically.
> +Ideally, all of the ACPICA commits should be converted into Linux patches
> +automatically without manual modifications, the "linux / master" tree should
> +contain the ACPICA code that exactly corresponds to the ACPICA code
> +contained in "new linuxized acpica" tree and it should be possible to run
> +the release process fully automatically.
>
> - As a matter of fact, however, there are source code differences between
> - the ACPICA code in Linux and the upstream ACPICA code, referred to as
> - "ACPICA Divergences".
> +As a matter of fact, however, there are source code differences between
> +the ACPICA code in Linux and the upstream ACPICA code, referred to as
> +"ACPICA Divergences".
>
> - The various sources of ACPICA divergences include:
> +The various sources of ACPICA divergences include:
> 1. Legacy divergences - Before the current ACPICA release process was
> established, there already had been divergences between Linux and
> ACPICA. Over the past several years those divergences have been greatly
> @@ -213,11 +227,12 @@ upstream.
> rebased on the ACPICA side in order to offer better solutions, new ACPICA
> divergences are generated.
>
> -4. ACPICA Development
> +ACPICA Development
> +==================
>
> - This paragraph guides Linux developers to use the ACPICA upstream release
> - utilities to obtain Linux patches corresponding to upstream ACPICA commits
> - before they become available from the ACPICA release process.
> +This paragraph guides Linux developers to use the ACPICA upstream release
> +utilities to obtain Linux patches corresponding to upstream ACPICA commits
> +before they become available from the ACPICA release process.
>
> 1. Cherry-pick an ACPICA commit
>
> @@ -225,7 +240,7 @@ upstream.
> you want to cherry pick must be committed into the local repository.
>
> Then the gen-patch.sh command can help to cherry-pick an ACPICA commit
> - from the ACPICA local repository:
> + from the ACPICA local repository::
>
> $ git clone https://github.com/acpica/acpica
> $ cd acpica
> @@ -240,7 +255,7 @@ upstream.
> changes that haven't been applied to Linux yet.
>
> You can generate the ACPICA release series yourself and rebase your code on
> - top of the generated ACPICA release patches:
> + top of the generated ACPICA release patches::
>
> $ git clone https://github.com/acpica/acpica
> $ cd acpica
> @@ -254,7 +269,7 @@ upstream.
> 3. Inspect the current divergences
>
> If you have local copies of both Linux and upstream ACPICA, you can generate
> - a diff file indicating the state of the current divergences:
> + a diff file indicating the state of the current divergences::
>
> # git clone https://github.com/acpica/acpica
> # git clone http://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
Thanks,
Mauro
^ permalink raw reply
* Re: [PATCH v4 06/63] Documentation: ACPI: move scan_handlers.txt to driver-api/acpi and convert to reST
From: Mauro Carvalho Chehab @ 2019-04-23 20:51 UTC (permalink / raw)
To: Changbin Du
Cc: fenghua.yu, x86, linux-doc, linux-pci, linux-gpio,
Jonathan Corbet, rjw, linux-kernel, linux-acpi, mingo,
Bjorn Helgaas, tglx, linuxppc-dev
In-Reply-To: <20190423162932.21428-7-changbin.du@gmail.com>
Em Wed, 24 Apr 2019 00:28:35 +0800
Changbin Du <changbin.du@gmail.com> escreveu:
> This converts the plain text documentation to reStructuredText format and
> add it to Sphinx TOC tree. No essential content change.
>
> Signed-off-by: Changbin Du <changbin.du@gmail.com>
For the conversion itself:
Reviewed-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
> ---
> Documentation/driver-api/acpi/index.rst | 1 +
> .../acpi/scan_handlers.rst} | 24 ++++++++++++-------
> 2 files changed, 16 insertions(+), 9 deletions(-)
> rename Documentation/{acpi/scan_handlers.txt => driver-api/acpi/scan_handlers.rst} (90%)
>
> diff --git a/Documentation/driver-api/acpi/index.rst b/Documentation/driver-api/acpi/index.rst
> index 12649947b19b..ace0008e54c2 100644
> --- a/Documentation/driver-api/acpi/index.rst
> +++ b/Documentation/driver-api/acpi/index.rst
> @@ -6,3 +6,4 @@ ACPI Support
> :maxdepth: 2
>
> linuxized-acpica
> + scan_handlers
> diff --git a/Documentation/acpi/scan_handlers.txt b/Documentation/driver-api/acpi/scan_handlers.rst
> similarity index 90%
> rename from Documentation/acpi/scan_handlers.txt
> rename to Documentation/driver-api/acpi/scan_handlers.rst
> index 3246ccf15992..7a197b3a33fc 100644
> --- a/Documentation/acpi/scan_handlers.txt
> +++ b/Documentation/driver-api/acpi/scan_handlers.rst
> @@ -1,7 +1,13 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +.. include:: <isonum.txt>
> +
> +==================
> ACPI Scan Handlers
> +==================
> +
> +:Copyright: |copy| 2012, Intel Corporation
>
> -Copyright (C) 2012, Intel Corporation
> -Author: Rafael J. Wysocki <rafael.j.wysocki@intel.com>
> +:Author: Rafael J. Wysocki <rafael.j.wysocki@intel.com>
>
> During system initialization and ACPI-based device hot-add, the ACPI namespace
> is scanned in search of device objects that generally represent various pieces
> @@ -30,14 +36,14 @@ to configure that link so that the kernel can use it.
> Those additional configuration tasks usually depend on the type of the hardware
> component represented by the given device node which can be determined on the
> basis of the device node's hardware ID (HID). They are performed by objects
> -called ACPI scan handlers represented by the following structure:
> +called ACPI scan handlers represented by the following structure::
>
> -struct acpi_scan_handler {
> - const struct acpi_device_id *ids;
> - struct list_head list_node;
> - int (*attach)(struct acpi_device *dev, const struct acpi_device_id *id);
> - void (*detach)(struct acpi_device *dev);
> -};
> + struct acpi_scan_handler {
> + const struct acpi_device_id *ids;
> + struct list_head list_node;
> + int (*attach)(struct acpi_device *dev, const struct acpi_device_id *id);
> + void (*detach)(struct acpi_device *dev);
> + };
>
> where ids is the list of IDs of device nodes the given handler is supposed to
> take care of, list_node is the hook to the global list of ACPI scan handlers
Thanks,
Mauro
^ permalink raw reply
* Re: [PATCH v4 07/63] Documentation: ACPI: move DSD-properties-rules.txt to firmware-guide/acpi and covert to reST
From: Mauro Carvalho Chehab @ 2019-04-23 20:52 UTC (permalink / raw)
To: Changbin Du, mingo, x86, fenghua.yu, linuxppc-dev, linux-acpi
Cc: linux-doc, linux-pci, Jonathan Corbet, rjw, linux-kernel,
linux-gpio, Bjorn Helgaas, tglx
In-Reply-To: <20190423162932.21428-8-changbin.du@gmail.com>
Em Wed, 24 Apr 2019 00:28:36 +0800
Changbin Du <changbin.du@gmail.com> escreveu:
> This converts the plain text documentation to reStructuredText format and
> add it to Sphinx TOC tree. No essential content change.
>
> Signed-off-by: Changbin Du <changbin.du@gmail.com>
For the conversion itself:
Reviewed-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
> ---
> .../acpi/DSD-properties-rules.rst} | 21 +++++++++++--------
> Documentation/firmware-guide/acpi/index.rst | 1 +
> 2 files changed, 13 insertions(+), 9 deletions(-)
> rename Documentation/{acpi/DSD-properties-rules.txt => firmware-guide/acpi/DSD-properties-rules.rst} (88%)
>
> diff --git a/Documentation/acpi/DSD-properties-rules.txt b/Documentation/firmware-guide/acpi/DSD-properties-rules.rst
> similarity index 88%
> rename from Documentation/acpi/DSD-properties-rules.txt
> rename to Documentation/firmware-guide/acpi/DSD-properties-rules.rst
> index 3e4862bdad98..4306f29b6103 100644
> --- a/Documentation/acpi/DSD-properties-rules.txt
> +++ b/Documentation/firmware-guide/acpi/DSD-properties-rules.rst
> @@ -1,8 +1,11 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +
> +==================================
> _DSD Device Properties Usage Rules
> -----------------------------------
> +==================================
>
> Properties, Property Sets and Property Subsets
> -----------------------------------------------
> +==============================================
>
> The _DSD (Device Specific Data) configuration object, introduced in ACPI 5.1,
> allows any type of device configuration data to be provided via the ACPI
> @@ -18,7 +21,7 @@ specific type) associated with it.
>
> In the ACPI _DSD context it is an element of the sub-package following the
> generic Device Properties UUID in the _DSD return package as specified in the
> -Device Properties UUID definition document [1].
> +Device Properties UUID definition document [1]_.
>
> It also may be regarded as the definition of a key and the associated data type
> that can be returned by _DSD in the Device Properties UUID sub-package for a
> @@ -33,14 +36,14 @@ Property subsets are nested collections of properties. Each of them is
> associated with an additional key (name) allowing the subset to be referred
> to as a whole (and to be treated as a separate entity). The canonical
> representation of property subsets is via the mechanism specified in the
> -Hierarchical Properties Extension UUID definition document [2].
> +Hierarchical Properties Extension UUID definition document [2]_.
>
> Property sets may be hierarchical. That is, a property set may contain
> multiple property subsets that each may contain property subsets of its
> own and so on.
>
> General Validity Rule for Property Sets
> ----------------------------------------
> +=======================================
>
> Valid property sets must follow the guidance given by the Device Properties UUID
> definition document [1].
> @@ -73,7 +76,7 @@ suitable for the ACPI environment and consequently they cannot belong to a valid
> property set.
>
> Property Sets and Device Tree Bindings
> ---------------------------------------
> +======================================
>
> It often is useful to make _DSD return property sets that follow Device Tree
> bindings.
> @@ -91,7 +94,7 @@ expected to automatically work in the ACPI environment regardless of their
> contents.
>
> References
> -----------
> +==========
>
> -[1] http://www.uefi.org/sites/default/files/resources/_DSD-device-properties-UUID.pdf
> -[2] http://www.uefi.org/sites/default/files/resources/_DSD-hierarchical-data-extension-UUID-v1.1.pdf
> +.. [1] http://www.uefi.org/sites/default/files/resources/_DSD-device-properties-UUID.pdf
> +.. [2] http://www.uefi.org/sites/default/files/resources/_DSD-hierarchical-data-extension-UUID-v1.1.pdf
> diff --git a/Documentation/firmware-guide/acpi/index.rst b/Documentation/firmware-guide/acpi/index.rst
> index 868bd25a3398..0e05b843521c 100644
> --- a/Documentation/firmware-guide/acpi/index.rst
> +++ b/Documentation/firmware-guide/acpi/index.rst
> @@ -10,3 +10,4 @@ ACPI Support
> namespace
> enumeration
> osi
> + DSD-properties-rules
Thanks,
Mauro
^ permalink raw reply
* Re: [PATCH v4 08/63] Documentation: ACPI: move gpio-properties.txt to firmware-guide/acpi and convert to reST
From: Mauro Carvalho Chehab @ 2019-04-23 20:55 UTC (permalink / raw)
To: Changbin Du
Cc: fenghua.yu, x86, linux-doc, linux-pci, linux-gpio,
Jonathan Corbet, rjw, linux-kernel, linux-acpi, mingo,
Bjorn Helgaas, tglx, linuxppc-dev
In-Reply-To: <20190423162932.21428-9-changbin.du@gmail.com>
Em Wed, 24 Apr 2019 00:28:37 +0800
Changbin Du <changbin.du@gmail.com> escreveu:
> This converts the plain text documentation to reStructuredText format and
> add it to Sphinx TOC tree. No essential content change.
>
> Signed-off-by: Changbin Du <changbin.du@gmail.com>
> ---
> .../acpi/gpio-properties.rst} | 78 +++++++++++--------
> Documentation/firmware-guide/acpi/index.rst | 1 +
> MAINTAINERS | 2 +-
> 3 files changed, 46 insertions(+), 35 deletions(-)
> rename Documentation/{acpi/gpio-properties.txt => firmware-guide/acpi/gpio-properties.rst} (81%)
>
> diff --git a/Documentation/acpi/gpio-properties.txt b/Documentation/firmware-guide/acpi/gpio-properties.rst
> similarity index 81%
> rename from Documentation/acpi/gpio-properties.txt
> rename to Documentation/firmware-guide/acpi/gpio-properties.rst
> index 88c65cb5bf0a..89c636963544 100644
> --- a/Documentation/acpi/gpio-properties.txt
> +++ b/Documentation/firmware-guide/acpi/gpio-properties.rst
> @@ -1,5 +1,8 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +
> +======================================
> _DSD Device Properties Related to GPIO
> ---------------------------------------
> +======================================
>
> With the release of ACPI 5.1, the _DSD configuration object finally
> allows names to be given to GPIOs (and other things as well) returned
> @@ -8,7 +11,7 @@ the corresponding GPIO, which is pretty error prone (it depends on
> the _CRS output ordering, for example).
>
> With _DSD we can now query GPIOs using a name instead of an integer
> -index, like the ASL example below shows:
> +index, like the ASL example below shows::
>
> // Bluetooth device with reset and shutdown GPIOs
> Device (BTH)
> @@ -34,15 +37,19 @@ index, like the ASL example below shows:
> })
> }
>
> -The format of the supported GPIO property is:
> +The format of the supported GPIO property is::
>
> Package () { "name", Package () { ref, index, pin, active_low }}
>
> - ref - The device that has _CRS containing GpioIo()/GpioInt() resources,
> - typically this is the device itself (BTH in our case).
> - index - Index of the GpioIo()/GpioInt() resource in _CRS starting from zero.
> - pin - Pin in the GpioIo()/GpioInt() resource. Typically this is zero.
> - active_low - If 1 the GPIO is marked as active_low.
> +ref
> + The device that has _CRS containing GpioIo()/GpioInt() resources,
> + typically this is the device itself (BTH in our case).
> +index
> + Index of the GpioIo()/GpioInt() resource in _CRS starting from zero.
> +pin
> + Pin in the GpioIo()/GpioInt() resource. Typically this is zero.
> +active_low
> + If 1 the GPIO is marked as active_low.
>
> Since ACPI GpioIo() resource does not have a field saying whether it is
> active low or high, the "active_low" argument can be used here. Setting
> @@ -55,7 +62,7 @@ It is possible to leave holes in the array of GPIOs. This is useful in
> cases like with SPI host controllers where some chip selects may be
> implemented as GPIOs and some as native signals. For example a SPI host
> controller can have chip selects 0 and 2 implemented as GPIOs and 1 as
> -native:
> +native::
>
> Package () {
> "cs-gpios",
> @@ -67,7 +74,7 @@ native:
> }
>
> Other supported properties
> ---------------------------
> +==========================
>
> Following Device Tree compatible device properties are also supported by
> _DSD device properties for GPIO controllers:
> @@ -78,7 +85,7 @@ _DSD device properties for GPIO controllers:
> - input
> - line-name
>
> -Example:
> +Example::
>
> Name (_DSD, Package () {
> // _DSD Hierarchical Properties Extension UUID
> @@ -100,7 +107,7 @@ Example:
>
> - gpio-line-names
>
> -Example:
> +Example::
>
> Package () {
> "gpio-line-names",
> @@ -114,7 +121,7 @@ See Documentation/devicetree/bindings/gpio/gpio.txt for more information
> about these properties.
>
> ACPI GPIO Mappings Provided by Drivers
> ---------------------------------------
> +======================================
>
> There are systems in which the ACPI tables do not contain _DSD but provide _CRS
> with GpioIo()/GpioInt() resources and device drivers still need to work with
> @@ -139,16 +146,16 @@ line in that resource starting from zero, and the active-low flag for that line,
> respectively, in analogy with the _DSD GPIO property format specified above.
>
> For the example Bluetooth device discussed previously the data structures in
> -question would look like this:
> +question would look like this::
>
> -static const struct acpi_gpio_params reset_gpio = { 1, 1, false };
> -static const struct acpi_gpio_params shutdown_gpio = { 0, 0, false };
> + static const struct acpi_gpio_params reset_gpio = { 1, 1, false };
> + static const struct acpi_gpio_params shutdown_gpio = { 0, 0, false };
>
> -static const struct acpi_gpio_mapping bluetooth_acpi_gpios[] = {
> - { "reset-gpios", &reset_gpio, 1 },
> - { "shutdown-gpios", &shutdown_gpio, 1 },
> - { },
> -};
> + static const struct acpi_gpio_mapping bluetooth_acpi_gpios[] = {
> + { "reset-gpios", &reset_gpio, 1 },
> + { "shutdown-gpios", &shutdown_gpio, 1 },
> + { },
> + };
>
> Next, the mapping table needs to be passed as the second argument to
> acpi_dev_add_driver_gpios() that will register it with the ACPI device object
> @@ -158,12 +165,12 @@ calling acpi_dev_remove_driver_gpios() on the ACPI device object where that
> table was previously registered.
>
> Using the _CRS fallback
> ------------------------
> +=======================
>
> If a device does not have _DSD or the driver does not create ACPI GPIO
> mapping, the Linux GPIO framework refuses to return any GPIOs. This is
> because the driver does not know what it actually gets. For example if we
> -have a device like below:
> +have a device like below::
>
> Device (BTH)
> {
> @@ -177,7 +184,7 @@ have a device like below:
> })
> }
>
> -The driver might expect to get the right GPIO when it does:
> +The driver might expect to get the right GPIO when it does:：
Hmm... there is a small typo here:
": :" -> "::"
For the conversion itself, after correcting the above typo:
Reviewed-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
>
> desc = gpiod_get(dev, "reset", GPIOD_OUT_LOW);
>
> @@ -193,22 +200,25 @@ the ACPI GPIO mapping tables are hardly linked to ACPI ID and certain
> objects, as listed in the above chapter, of the device in question.
>
> Getting GPIO descriptor
> ------------------------
> +=======================
> +
> +There are two main approaches to get GPIO resource from ACPI::
>
> -There are two main approaches to get GPIO resource from ACPI:
> - desc = gpiod_get(dev, connection_id, flags);
> - desc = gpiod_get_index(dev, connection_id, index, flags);
> + desc = gpiod_get(dev, connection_id, flags);
> + desc = gpiod_get_index(dev, connection_id, index, flags);
>
> We may consider two different cases here, i.e. when connection ID is
> provided and otherwise.
>
> -Case 1:
> - desc = gpiod_get(dev, "non-null-connection-id", flags);
> - desc = gpiod_get_index(dev, "non-null-connection-id", index, flags);
> +Case 1::
> +
> + desc = gpiod_get(dev, "non-null-connection-id", flags);
> + desc = gpiod_get_index(dev, "non-null-connection-id", index, flags);
> +
> +Case 2::
>
> -Case 2:
> - desc = gpiod_get(dev, NULL, flags);
> - desc = gpiod_get_index(dev, NULL, index, flags);
> + desc = gpiod_get(dev, NULL, flags);
> + desc = gpiod_get_index(dev, NULL, index, flags);
>
> Case 1 assumes that corresponding ACPI device description must have
> defined device properties and will prevent to getting any GPIO resources
> diff --git a/Documentation/firmware-guide/acpi/index.rst b/Documentation/firmware-guide/acpi/index.rst
> index 0e05b843521c..61d67763851b 100644
> --- a/Documentation/firmware-guide/acpi/index.rst
> +++ b/Documentation/firmware-guide/acpi/index.rst
> @@ -11,3 +11,4 @@ ACPI Support
> enumeration
> osi
> DSD-properties-rules
> + gpio-properties
> diff --git a/MAINTAINERS b/MAINTAINERS
> index 09f43f1bdd15..87f930bf32ad 100644
> --- a/MAINTAINERS
> +++ b/MAINTAINERS
> @@ -6593,7 +6593,7 @@ M: Andy Shevchenko <andriy.shevchenko@linux.intel.com>
> L: linux-gpio@vger.kernel.org
> L: linux-acpi@vger.kernel.org
> S: Maintained
> -F: Documentation/acpi/gpio-properties.txt
> +F: Documentation/firmware-guide/acpi/gpio-properties.rst
> F: drivers/gpio/gpiolib-acpi.c
>
> GPIO IR Transmitter
Thanks,
Mauro
^ permalink raw reply
* Re: [PATCH v4 09/63] Documentation: ACPI: move method-customizing.txt to firmware-guide/acpi and convert to reST
From: Mauro Carvalho Chehab @ 2019-04-23 21:03 UTC (permalink / raw)
To: Changbin Du
Cc: fenghua.yu, x86, linux-doc, linux-pci, linux-gpio,
Jonathan Corbet, rjw, linux-kernel, linux-acpi, mingo,
Bjorn Helgaas, tglx, linuxppc-dev
In-Reply-To: <20190423162932.21428-10-changbin.du@gmail.com>
Em Wed, 24 Apr 2019 00:28:38 +0800
Changbin Du <changbin.du@gmail.com> escreveu:
> This converts the plain text documentation to reStructuredText format and
> add it to Sphinx TOC tree. No essential content change.
>
> Signed-off-by: Changbin Du <changbin.du@gmail.com>
> ---
> Documentation/acpi/method-customizing.txt | 73 -----------------
> Documentation/firmware-guide/acpi/index.rst | 3 +-
> .../acpi/method-customizing.rst | 82 +++++++++++++++++++
> 3 files changed, 84 insertions(+), 74 deletions(-)
> delete mode 100644 Documentation/acpi/method-customizing.txt
> create mode 100644 Documentation/firmware-guide/acpi/method-customizing.rst
>
> diff --git a/Documentation/acpi/method-customizing.txt b/Documentation/acpi/method-customizing.txt
> deleted file mode 100644
> index 7235da975f23..000000000000
> --- a/Documentation/acpi/method-customizing.txt
> +++ /dev/null
> @@ -1,73 +0,0 @@
> -Linux ACPI Custom Control Method How To
> -=======================================
> -
> -Written by Zhang Rui <rui.zhang@intel.com>
> -
> -
> -Linux supports customizing ACPI control methods at runtime.
> -
> -Users can use this to
> -1. override an existing method which may not work correctly,
> - or just for debugging purposes.
> -2. insert a completely new method in order to create a missing
> - method such as _OFF, _ON, _STA, _INI, etc.
> -For these cases, it is far simpler to dynamically install a single
> -control method rather than override the entire DSDT, because kernel
> -rebuild/reboot is not needed and test result can be got in minutes.
> -
> -Note: Only ACPI METHOD can be overridden, any other object types like
> - "Device", "OperationRegion", are not recognized. Methods
> - declared inside scope operators are also not supported.
> -Note: The same ACPI control method can be overridden for many times,
> - and it's always the latest one that used by Linux/kernel.
> -Note: To get the ACPI debug object output (Store (AAAA, Debug)),
> - please run "echo 1 > /sys/module/acpi/parameters/aml_debug_output".
> -
> -1. override an existing method
> - a) get the ACPI table via ACPI sysfs I/F. e.g. to get the DSDT,
> - just run "cat /sys/firmware/acpi/tables/DSDT > /tmp/dsdt.dat"
> - b) disassemble the table by running "iasl -d dsdt.dat".
> - c) rewrite the ASL code of the method and save it in a new file,
> - d) package the new file (psr.asl) to an ACPI table format.
> - Here is an example of a customized \_SB._AC._PSR method,
> -
> - DefinitionBlock ("", "SSDT", 1, "", "", 0x20080715)
> - {
> - Method (\_SB_.AC._PSR, 0, NotSerialized)
> - {
> - Store ("In AC _PSR", Debug)
> - Return (ACON)
> - }
> - }
> - Note that the full pathname of the method in ACPI namespace
> - should be used.
> - e) assemble the file to generate the AML code of the method.
> - e.g. "iasl -vw 6084 psr.asl" (psr.aml is generated as a result)
> - If parameter "-vw 6084" is not supported by your iASL compiler,
> - please try a newer version.
> - f) mount debugfs by "mount -t debugfs none /sys/kernel/debug"
> - g) override the old method via the debugfs by running
> - "cat /tmp/psr.aml > /sys/kernel/debug/acpi/custom_method"
> -
> -2. insert a new method
> - This is easier than overriding an existing method.
> - We just need to create the ASL code of the method we want to
> - insert and then follow the step c) ~ g) in section 1.
> -
> -3. undo your changes
> - The "undo" operation is not supported for a new inserted method
> - right now, i.e. we can not remove a method currently.
> - For an overridden method, in order to undo your changes, please
> - save a copy of the method original ASL code in step c) section 1,
> - and redo step c) ~ g) to override the method with the original one.
> -
> -
> -Note: We can use a kernel with multiple custom ACPI method running,
> - But each individual write to debugfs can implement a SINGLE
> - method override. i.e. if we want to insert/override multiple
> - ACPI methods, we need to redo step c) ~ g) for multiple times.
> -
> -Note: Be aware that root can mis-use this driver to modify arbitrary
> - memory and gain additional rights, if root's privileges got
> - restricted (for example if root is not allowed to load additional
> - modules after boot).
> diff --git a/Documentation/firmware-guide/acpi/index.rst b/Documentation/firmware-guide/acpi/index.rst
> index 61d67763851b..d1d069b26bbc 100644
> --- a/Documentation/firmware-guide/acpi/index.rst
> +++ b/Documentation/firmware-guide/acpi/index.rst
> @@ -10,5 +10,6 @@ ACPI Support
> namespace
> enumeration
> osi
> + method-customizing
> DSD-properties-rules
> - gpio-properties
> + gpio-properties
> \ No newline at end of file
> diff --git a/Documentation/firmware-guide/acpi/method-customizing.rst b/Documentation/firmware-guide/acpi/method-customizing.rst
> new file mode 100644
> index 000000000000..32eb1cdc1549
> --- /dev/null
> +++ b/Documentation/firmware-guide/acpi/method-customizing.rst
> @@ -0,0 +1,82 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +
> +=======================================
> +Linux ACPI Custom Control Method How To
> +=======================================
> +
> +:Author: Zhang Rui <rui.zhang@intel.com>
> +
> +
> +Linux supports customizing ACPI control methods at runtime.
> +
> +Users can use this to:
> +
> +1. override an existing method which may not work correctly,
> + or just for debugging purposes.
> +2. insert a completely new method in order to create a missing
> + method such as _OFF, _ON, _STA, _INI, etc.
> +
> +For these cases, it is far simpler to dynamically install a single
> +control method rather than override the entire DSDT, because kernel
> +rebuild/reboot is not needed and test result can be got in minutes.
> +
> +.. note:: Only ACPI METHOD can be overridden, any other object types like
> + "Device", "OperationRegion", are not recognized. Methods
> + declared inside scope operators are also not supported.
> +.. note:: The same ACPI control method can be overridden for many times,
> + and it's always the latest one that used by Linux/kernel.
> +.. note:: To get the ACPI debug object output (Store (AAAA, Debug)),
> + please run "echo 1 > /sys/module/acpi/parameters/aml_debug_output".
Hmm... this may work (not sure if Sphinx would warn or not), but it
is visually bad on text mode. I would code it, instead, with something
like:
.. note::
- Only ACPI METHOD can be overridden, any other object types like
"Device", "OperationRegion", are not recognized. Methods
declared inside scope operators are also not supported.
- The same ACPI control method can be overridden for many times,
and it's always the latest one that used by Linux/kernel.
- To get the ACPI debug object output (Store (AAAA, Debug)),
please run::
echo 1 > /sys/module/acpi/parameters/aml_debug_output
As this would make it visually better on both text and html formats.
> +
> +1. override an existing method
> +==============================
> +a) get the ACPI table via ACPI sysfs I/F. e.g. to get the DSDT,
> + just run "cat /sys/firmware/acpi/tables/DSDT > /tmp/dsdt.dat"
> +b) disassemble the table by running "iasl -d dsdt.dat".
> +c) rewrite the ASL code of the method and save it in a new file,
> +d) package the new file (psr.asl) to an ACPI table format.
> + Here is an example of a customized \_SB._AC._PSR method::
> +
> + DefinitionBlock ("", "SSDT", 1, "", "", 0x20080715)
> + {
> + Method (\_SB_.AC._PSR, 0, NotSerialized)
> + {
> + Store ("In AC _PSR", Debug)
> + Return (ACON)
> + }
> + }
> +
> + Note that the full pathname of the method in ACPI namespace
> + should be used.
> +e) assemble the file to generate the AML code of the method.
> + e.g. "iasl -vw 6084 psr.asl" (psr.aml is generated as a result)
> + If parameter "-vw 6084" is not supported by your iASL compiler,
> + please try a newer version.
I would use ``iasl -vw 6084 psr.asl`` and ``-vw 6084``.
> +f) mount debugfs by "mount -t debugfs none /sys/kernel/debug"
I would do:
f) mount debugfs by running::
mount -t debugfs none /sys/kernel/debug
As it makes a better html document. I believe that the focus here is
sysadmins. Doing the above makes easier for them to cut and paste
commands.
> +g) override the old method via the debugfs by running
> + "cat /tmp/psr.aml > /sys/kernel/debug/acpi/custom_method"
Same applies here: I would also place the "cat" command on a literal
block.
> +
> +2. insert a new method
> +======================
> +This is easier than overriding an existing method.
> +We just need to create the ASL code of the method we want to
> +insert and then follow the step c) ~ g) in section 1.
> +
> +3. undo your changes
> +====================
> +The "undo" operation is not supported for a new inserted method
> +right now, i.e. we can not remove a method currently.
> +For an overridden method, in order to undo your changes, please
> +save a copy of the method original ASL code in step c) section 1,
> +and redo step c) ~ g) to override the method with the original one.
> +
> +
> +.. note:: We can use a kernel with multiple custom ACPI method running,
> + But each individual write to debugfs can implement a SINGLE
> + method override. i.e. if we want to insert/override multiple
> + ACPI methods, we need to redo step c) ~ g) for multiple times.
> +
> +.. note:: Be aware that root can mis-use this driver to modify arbitrary
> + memory and gain additional rights, if root's privileges got
> + restricted (for example if root is not allowed to load additional
> + modules after boot).
Same comment as above: IMHO, having a single note block with the two
notes would be better.
Thanks,
Mauro
^ permalink raw reply
* Re: [PATCH v4 10/63] Documentation: ACPI: move initrd_table_override.txt to admin-guide/acpi and convert to reST
From: Mauro Carvalho Chehab @ 2019-04-23 21:07 UTC (permalink / raw)
To: Changbin Du
Cc: fenghua.yu, x86, linux-doc, linux-pci, linux-gpio,
Jonathan Corbet, rjw, linux-kernel, linux-acpi, mingo,
Bjorn Helgaas, tglx, linuxppc-dev
In-Reply-To: <20190423162932.21428-11-changbin.du@gmail.com>
Em Wed, 24 Apr 2019 00:28:39 +0800
Changbin Du <changbin.du@gmail.com> escreveu:
> This converts the plain text documentation to reStructuredText format and
> add it to Sphinx TOC tree. No essential content change.
>
> Signed-off-by: Changbin Du <changbin.du@gmail.com>
> ---
> Documentation/acpi/initrd_table_override.txt | 111 ----------------
> Documentation/admin-guide/acpi/index.rst | 1 +
> .../acpi/initrd_table_override.rst | 120 ++++++++++++++++++
> 3 files changed, 121 insertions(+), 111 deletions(-)
> delete mode 100644 Documentation/acpi/initrd_table_override.txt
> create mode 100644 Documentation/admin-guide/acpi/initrd_table_override.rst
>
> diff --git a/Documentation/acpi/initrd_table_override.txt b/Documentation/acpi/initrd_table_override.txt
> deleted file mode 100644
> index 30437a6db373..000000000000
> --- a/Documentation/acpi/initrd_table_override.txt
> +++ /dev/null
> @@ -1,111 +0,0 @@
> -Upgrading ACPI tables via initrd
> -================================
> -
> -1) Introduction (What is this about)
> -2) What is this for
> -3) How does it work
> -4) References (Where to retrieve userspace tools)
> -
> -1) What is this about
> ----------------------
> -
> -If the ACPI_TABLE_UPGRADE compile option is true, it is possible to
> -upgrade the ACPI execution environment that is defined by the ACPI tables
> -via upgrading the ACPI tables provided by the BIOS with an instrumented,
> -modified, more recent version one, or installing brand new ACPI tables.
> -
> -When building initrd with kernel in a single image, option
> -ACPI_TABLE_OVERRIDE_VIA_BUILTIN_INITRD should also be true for this
> -feature to work.
> -
> -For a full list of ACPI tables that can be upgraded/installed, take a look
> -at the char *table_sigs[MAX_ACPI_SIGNATURE]; definition in
> -drivers/acpi/tables.c.
> -All ACPI tables iasl (Intel's ACPI compiler and disassembler) knows should
> -be overridable, except:
> - - ACPI_SIG_RSDP (has a signature of 6 bytes)
> - - ACPI_SIG_FACS (does not have an ordinary ACPI table header)
> -Both could get implemented as well.
> -
> -
> -2) What is this for
> --------------------
> -
> -Complain to your platform/BIOS vendor if you find a bug which is so severe
> -that a workaround is not accepted in the Linux kernel. And this facility
> -allows you to upgrade the buggy tables before your platform/BIOS vendor
> -releases an upgraded BIOS binary.
> -
> -This facility can be used by platform/BIOS vendors to provide a Linux
> -compatible environment without modifying the underlying platform firmware.
> -
> -This facility also provides a powerful feature to easily debug and test
> -ACPI BIOS table compatibility with the Linux kernel by modifying old
> -platform provided ACPI tables or inserting new ACPI tables.
> -
> -It can and should be enabled in any kernel because there is no functional
> -change with not instrumented initrds.
> -
> -
> -3) How does it work
> --------------------
> -
> -# Extract the machine's ACPI tables:
> -cd /tmp
> -acpidump >acpidump
> -acpixtract -a acpidump
> -# Disassemble, modify and recompile them:
> -iasl -d *.dat
> -# For example add this statement into a _PRT (PCI Routing Table) function
> -# of the DSDT:
> -Store("HELLO WORLD", debug)
> -# And increase the OEM Revision. For example, before modification:
> -DefinitionBlock ("DSDT.aml", "DSDT", 2, "INTEL ", "TEMPLATE", 0x00000000)
> -# After modification:
> -DefinitionBlock ("DSDT.aml", "DSDT", 2, "INTEL ", "TEMPLATE", 0x00000001)
> -iasl -sa dsdt.dsl
> -# Add the raw ACPI tables to an uncompressed cpio archive.
> -# They must be put into a /kernel/firmware/acpi directory inside the cpio
> -# archive. Note that if the table put here matches a platform table
> -# (similar Table Signature, and similar OEMID, and similar OEM Table ID)
> -# with a more recent OEM Revision, the platform table will be upgraded by
> -# this table. If the table put here doesn't match a platform table
> -# (dissimilar Table Signature, or dissimilar OEMID, or dissimilar OEM Table
> -# ID), this table will be appended.
> -mkdir -p kernel/firmware/acpi
> -cp dsdt.aml kernel/firmware/acpi
> -# A maximum of "NR_ACPI_INITRD_TABLES (64)" tables are currently allowed
> -# (see osl.c):
> -iasl -sa facp.dsl
> -iasl -sa ssdt1.dsl
> -cp facp.aml kernel/firmware/acpi
> -cp ssdt1.aml kernel/firmware/acpi
> -# The uncompressed cpio archive must be the first. Other, typically
> -# compressed cpio archives, must be concatenated on top of the uncompressed
> -# one. Following command creates the uncompressed cpio archive and
> -# concatenates the original initrd on top:
> -find kernel | cpio -H newc --create > /boot/instrumented_initrd
> -cat /boot/initrd >>/boot/instrumented_initrd
> -# reboot with increased acpi debug level, e.g. boot params:
> -acpi.debug_level=0x2 acpi.debug_layer=0xFFFFFFFF
> -# and check your syslog:
> -[ 1.268089] ACPI: PCI Interrupt Routing Table [\_SB_.PCI0._PRT]
> -[ 1.272091] [ACPI Debug] String [0x0B] "HELLO WORLD"
> -
> -iasl is able to disassemble and recompile quite a lot different,
> -also static ACPI tables.
> -
> -
> -4) Where to retrieve userspace tools
> -------------------------------------
> -
> -iasl and acpixtract are part of Intel's ACPICA project:
> -http://acpica.org/
> -and should be packaged by distributions (for example in the acpica package
> -on SUSE).
> -
> -acpidump can be found in Len Browns pmtools:
> -ftp://kernel.org/pub/linux/kernel/people/lenb/acpi/utils/pmtools/acpidump
> -This tool is also part of the acpica package on SUSE.
> -Alternatively, used ACPI tables can be retrieved via sysfs in latest kernels:
> -/sys/firmware/acpi/tables
> diff --git a/Documentation/admin-guide/acpi/index.rst b/Documentation/admin-guide/acpi/index.rst
> index 3e041206089d..09e4e81e4fb7 100644
> --- a/Documentation/admin-guide/acpi/index.rst
> +++ b/Documentation/admin-guide/acpi/index.rst
> @@ -8,3 +8,4 @@ the Linux ACPI support.
> .. toctree::
> :maxdepth: 1
>
> + initrd_table_override
> diff --git a/Documentation/admin-guide/acpi/initrd_table_override.rst b/Documentation/admin-guide/acpi/initrd_table_override.rst
> new file mode 100644
> index 000000000000..0787b2b91ded
> --- /dev/null
> +++ b/Documentation/admin-guide/acpi/initrd_table_override.rst
> @@ -0,0 +1,120 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +
> +================================
> +Upgrading ACPI tables via initrd
> +================================
> +
> +1) Introduction (What is this about)
> +2) What is this for
> +3) How does it work
> +4) References (Where to retrieve userspace tools)
Hmm... I did the same on my conversion, but IMO, the best would be to
hide (or remove, if ACPI maintainers agree) the contents, as this may
conflict with the body as people may add new stuff and forget to
update it.
So, if ACPI maintainers insist on keeping it, I would code this as:
.. Contents
1) Introduction (What is this about)
2) What is this for
3) How does it work
4) References (Where to retrieve userspace tools)
as this will make this invisible on html/pdf/epub output.
Anyway, with or without the above change:
Reviewed-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
> +
> +1) What is this about
> +=====================
> +
> +If the ACPI_TABLE_UPGRADE compile option is true, it is possible to
> +upgrade the ACPI execution environment that is defined by the ACPI tables
> +via upgrading the ACPI tables provided by the BIOS with an instrumented,
> +modified, more recent version one, or installing brand new ACPI tables.
> +
> +When building initrd with kernel in a single image, option
> +ACPI_TABLE_OVERRIDE_VIA_BUILTIN_INITRD should also be true for this
> +feature to work.
> +
> +For a full list of ACPI tables that can be upgraded/installed, take a look
> +at the char `*table_sigs[MAX_ACPI_SIGNATURE];` definition in
> +drivers/acpi/tables.c.
> +
> +All ACPI tables iasl (Intel's ACPI compiler and disassembler) knows should
> +be overridable, except:
> +
> + - ACPI_SIG_RSDP (has a signature of 6 bytes)
> + - ACPI_SIG_FACS (does not have an ordinary ACPI table header)
> +
> +Both could get implemented as well.
> +
> +
> +2) What is this for
> +===================
> +
> +Complain to your platform/BIOS vendor if you find a bug which is so severe
> +that a workaround is not accepted in the Linux kernel. And this facility
> +allows you to upgrade the buggy tables before your platform/BIOS vendor
> +releases an upgraded BIOS binary.
> +
> +This facility can be used by platform/BIOS vendors to provide a Linux
> +compatible environment without modifying the underlying platform firmware.
> +
> +This facility also provides a powerful feature to easily debug and test
> +ACPI BIOS table compatibility with the Linux kernel by modifying old
> +platform provided ACPI tables or inserting new ACPI tables.
> +
> +It can and should be enabled in any kernel because there is no functional
> +change with not instrumented initrds.
> +
> +
> +3) How does it work
> +===================
> +::
> +
> + # Extract the machine's ACPI tables:
> + cd /tmp
> + acpidump >acpidump
> + acpixtract -a acpidump
> + # Disassemble, modify and recompile them:
> + iasl -d *.dat
> + # For example add this statement into a _PRT (PCI Routing Table) function
> + # of the DSDT:
> + Store("HELLO WORLD", debug)
> + # And increase the OEM Revision. For example, before modification:
> + DefinitionBlock ("DSDT.aml", "DSDT", 2, "INTEL ", "TEMPLATE", 0x00000000)
> + # After modification:
> + DefinitionBlock ("DSDT.aml", "DSDT", 2, "INTEL ", "TEMPLATE", 0x00000001)
> + iasl -sa dsdt.dsl
> + # Add the raw ACPI tables to an uncompressed cpio archive.
> + # They must be put into a /kernel/firmware/acpi directory inside the cpio
> + # archive. Note that if the table put here matches a platform table
> + # (similar Table Signature, and similar OEMID, and similar OEM Table ID)
> + # with a more recent OEM Revision, the platform table will be upgraded by
> + # this table. If the table put here doesn't match a platform table
> + # (dissimilar Table Signature, or dissimilar OEMID, or dissimilar OEM Table
> + # ID), this table will be appended.
> + mkdir -p kernel/firmware/acpi
> + cp dsdt.aml kernel/firmware/acpi
> + # A maximum of "NR_ACPI_INITRD_TABLES (64)" tables are currently allowed
> + # (see osl.c):
> + iasl -sa facp.dsl
> + iasl -sa ssdt1.dsl
> + cp facp.aml kernel/firmware/acpi
> + cp ssdt1.aml kernel/firmware/acpi
> + # The uncompressed cpio archive must be the first. Other, typically
> + # compressed cpio archives, must be concatenated on top of the uncompressed
> + # one. Following command creates the uncompressed cpio archive and
> + # concatenates the original initrd on top:
> + find kernel | cpio -H newc --create > /boot/instrumented_initrd
> + cat /boot/initrd >>/boot/instrumented_initrd
> + # reboot with increased acpi debug level, e.g. boot params:
> + acpi.debug_level=0x2 acpi.debug_layer=0xFFFFFFFF
> + # and check your syslog:
> + [ 1.268089] ACPI: PCI Interrupt Routing Table [\_SB_.PCI0._PRT]
> + [ 1.272091] [ACPI Debug] String [0x0B] "HELLO WORLD"
> +
> +iasl is able to disassemble and recompile quite a lot different,
> +also static ACPI tables.
> +
> +
> +4) Where to retrieve userspace tools
> +====================================
> +
> +iasl and acpixtract are part of Intel's ACPICA project:
> +http://acpica.org/
> +
> +and should be packaged by distributions (for example in the acpica package
> +on SUSE).
> +
> +acpidump can be found in Len Browns pmtools:
> +ftp://kernel.org/pub/linux/kernel/people/lenb/acpi/utils/pmtools/acpidump
> +
> +This tool is also part of the acpica package on SUSE.
> +Alternatively, used ACPI tables can be retrieved via sysfs in latest kernels:
> +/sys/firmware/acpi/tables
Thanks,
Mauro
^ permalink raw reply
* Re: [PATCH v4 11/63] Documentation: ACPI: move dsdt-override.txt to admin-guide/acpi and convert to reST
From: Mauro Carvalho Chehab @ 2019-04-23 21:08 UTC (permalink / raw)
To: Changbin Du
Cc: fenghua.yu, x86, linux-doc, linux-pci, linux-gpio,
Jonathan Corbet, rjw, linux-kernel, linux-acpi, mingo,
Bjorn Helgaas, tglx, linuxppc-dev
In-Reply-To: <20190423162932.21428-12-changbin.du@gmail.com>
Em Wed, 24 Apr 2019 00:28:40 +0800
Changbin Du <changbin.du@gmail.com> escreveu:
> This converts the plain text documentation to reStructuredText format and
> add it to Sphinx TOC tree. No essential content change.
>
> Signed-off-by: Changbin Du <changbin.du@gmail.com>
Reviewed-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
> ---
> .../acpi/dsdt-override.rst} | 8 +++++++-
> Documentation/admin-guide/acpi/index.rst | 1 +
> 2 files changed, 8 insertions(+), 1 deletion(-)
> rename Documentation/{acpi/dsdt-override.txt => admin-guide/acpi/dsdt-override.rst} (56%)
>
> diff --git a/Documentation/acpi/dsdt-override.txt b/Documentation/admin-guide/acpi/dsdt-override.rst
> similarity index 56%
> rename from Documentation/acpi/dsdt-override.txt
> rename to Documentation/admin-guide/acpi/dsdt-override.rst
> index 784841caa6e6..50bd7f194bf4 100644
> --- a/Documentation/acpi/dsdt-override.txt
> +++ b/Documentation/admin-guide/acpi/dsdt-override.rst
> @@ -1,6 +1,12 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +
> +===============
> +Overriding DSDT
> +===============
> +
> Linux supports a method of overriding the BIOS DSDT:
>
> -CONFIG_ACPI_CUSTOM_DSDT builds the image into the kernel.
> +CONFIG_ACPI_CUSTOM_DSDT - builds the image into the kernel.
>
> When to use this method is described in detail on the
> Linux/ACPI home page:
> diff --git a/Documentation/admin-guide/acpi/index.rst b/Documentation/admin-guide/acpi/index.rst
> index 09e4e81e4fb7..d68e9914c5ff 100644
> --- a/Documentation/admin-guide/acpi/index.rst
> +++ b/Documentation/admin-guide/acpi/index.rst
> @@ -9,3 +9,4 @@ the Linux ACPI support.
> :maxdepth: 1
>
> initrd_table_override
> + dsdt-override
Thanks,
Mauro
^ permalink raw reply
* Re: [PATCH v4 12/63] Documentation: ACPI: move i2c-muxes.txt to firmware-guide/acpi and convert to reST
From: Mauro Carvalho Chehab @ 2019-04-23 21:09 UTC (permalink / raw)
To: Changbin Du
Cc: fenghua.yu, x86, linux-doc, linux-pci, linux-gpio,
Jonathan Corbet, rjw, linux-kernel, linux-acpi, mingo,
Bjorn Helgaas, tglx, linuxppc-dev
In-Reply-To: <20190423162932.21428-13-changbin.du@gmail.com>
Em Wed, 24 Apr 2019 00:28:41 +0800
Changbin Du <changbin.du@gmail.com> escreveu:
> This converts the plain text documentation to reStructuredText format and
> add it to Sphinx TOC tree. No essential content change.
>
> Signed-off-by: Changbin Du <changbin.du@gmail.com>
For the conversion itself:
Reviewed-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
> ---
> Documentation/acpi/i2c-muxes.txt | 58 ------------------
> .../firmware-guide/acpi/i2c-muxes.rst | 61 +++++++++++++++++++
> Documentation/firmware-guide/acpi/index.rst | 3 +-
> 3 files changed, 63 insertions(+), 59 deletions(-)
> delete mode 100644 Documentation/acpi/i2c-muxes.txt
> create mode 100644 Documentation/firmware-guide/acpi/i2c-muxes.rst
>
> diff --git a/Documentation/acpi/i2c-muxes.txt b/Documentation/acpi/i2c-muxes.txt
> deleted file mode 100644
> index 9fcc4f0b885e..000000000000
> --- a/Documentation/acpi/i2c-muxes.txt
> +++ /dev/null
> @@ -1,58 +0,0 @@
> -ACPI I2C Muxes
> ---------------
> -
> -Describing an I2C device hierarchy that includes I2C muxes requires an ACPI
> -Device () scope per mux channel.
> -
> -Consider this topology:
> -
> -+------+ +------+
> -| SMB1 |-->| MUX0 |--CH00--> i2c client A (0x50)
> -| | | 0x70 |--CH01--> i2c client B (0x50)
> -+------+ +------+
> -
> -which corresponds to the following ASL:
> -
> -Device (SMB1)
> -{
> - Name (_HID, ...)
> - Device (MUX0)
> - {
> - Name (_HID, ...)
> - Name (_CRS, ResourceTemplate () {
> - I2cSerialBus (0x70, ControllerInitiated, I2C_SPEED,
> - AddressingMode7Bit, "^SMB1", 0x00,
> - ResourceConsumer,,)
> - }
> -
> - Device (CH00)
> - {
> - Name (_ADR, 0)
> -
> - Device (CLIA)
> - {
> - Name (_HID, ...)
> - Name (_CRS, ResourceTemplate () {
> - I2cSerialBus (0x50, ControllerInitiated, I2C_SPEED,
> - AddressingMode7Bit, "^CH00", 0x00,
> - ResourceConsumer,,)
> - }
> - }
> - }
> -
> - Device (CH01)
> - {
> - Name (_ADR, 1)
> -
> - Device (CLIB)
> - {
> - Name (_HID, ...)
> - Name (_CRS, ResourceTemplate () {
> - I2cSerialBus (0x50, ControllerInitiated, I2C_SPEED,
> - AddressingMode7Bit, "^CH01", 0x00,
> - ResourceConsumer,,)
> - }
> - }
> - }
> - }
> -}
> diff --git a/Documentation/firmware-guide/acpi/i2c-muxes.rst b/Documentation/firmware-guide/acpi/i2c-muxes.rst
> new file mode 100644
> index 000000000000..3a8997ccd7c4
> --- /dev/null
> +++ b/Documentation/firmware-guide/acpi/i2c-muxes.rst
> @@ -0,0 +1,61 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +
> +==============
> +ACPI I2C Muxes
> +==============
> +
> +Describing an I2C device hierarchy that includes I2C muxes requires an ACPI
> +Device () scope per mux channel.
> +
> +Consider this topology::
> +
> + +------+ +------+
> + | SMB1 |-->| MUX0 |--CH00--> i2c client A (0x50)
> + | | | 0x70 |--CH01--> i2c client B (0x50)
> + +------+ +------+
> +
> +which corresponds to the following ASL::
> +
> + Device (SMB1)
> + {
> + Name (_HID, ...)
> + Device (MUX0)
> + {
> + Name (_HID, ...)
> + Name (_CRS, ResourceTemplate () {
> + I2cSerialBus (0x70, ControllerInitiated, I2C_SPEED,
> + AddressingMode7Bit, "^SMB1", 0x00,
> + ResourceConsumer,,)
> + }
> +
> + Device (CH00)
> + {
> + Name (_ADR, 0)
> +
> + Device (CLIA)
> + {
> + Name (_HID, ...)
> + Name (_CRS, ResourceTemplate () {
> + I2cSerialBus (0x50, ControllerInitiated, I2C_SPEED,
> + AddressingMode7Bit, "^CH00", 0x00,
> + ResourceConsumer,,)
> + }
> + }
> + }
> +
> + Device (CH01)
> + {
> + Name (_ADR, 1)
> +
> + Device (CLIB)
> + {
> + Name (_HID, ...)
> + Name (_CRS, ResourceTemplate () {
> + I2cSerialBus (0x50, ControllerInitiated, I2C_SPEED,
> + AddressingMode7Bit, "^CH01", 0x00,
> + ResourceConsumer,,)
> + }
> + }
> + }
> + }
> + }
> diff --git a/Documentation/firmware-guide/acpi/index.rst b/Documentation/firmware-guide/acpi/index.rst
> index d1d069b26bbc..1c89888f6ee8 100644
> --- a/Documentation/firmware-guide/acpi/index.rst
> +++ b/Documentation/firmware-guide/acpi/index.rst
> @@ -12,4 +12,5 @@ ACPI Support
> osi
> method-customizing
> DSD-properties-rules
> - gpio-properties
> \ No newline at end of file
> + gpio-properties
> + i2c-muxes
Thanks,
Mauro
^ permalink raw reply
page: next (older) | prev (newer) | latest
- recent:[subjects (threaded)|topics (new)|topics (active)]
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox