* [PATCH 01/57] docs: trace: fix some Sphinx warnings
2019-04-16 2:55 [PATCH 00/57] Convert files to ReST Mauro Carvalho Chehab
@ 2019-04-16 2:55 ` Mauro Carvalho Chehab
2019-04-16 2:55 ` [PATCH 02/57] docs: acpi: convert text files to ReST Mauro Carvalho Chehab
` (51 subsequent siblings)
52 siblings, 0 replies; 81+ messages in thread
From: Mauro Carvalho Chehab @ 2019-04-16 2:55 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Steven Rostedt, Ingo Molnar
There are some warnings produced when building trace. Fix them.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
Documentation/trace/ftrace.rst | 1 +
Documentation/trace/histogram.rst | 86 ++++++++++++++++---------------
2 files changed, 45 insertions(+), 42 deletions(-)
diff --git a/Documentation/trace/ftrace.rst b/Documentation/trace/ftrace.rst
index 809b39d066ee..f60079259669 100644
--- a/Documentation/trace/ftrace.rst
+++ b/Documentation/trace/ftrace.rst
@@ -1435,6 +1435,7 @@ trace has provided some very helpful debugging information.
If we prefer function graph output instead of function, we can set
display-graph option::
+
with echo 1 > options/display-graph
# tracer: irqsoff
diff --git a/Documentation/trace/histogram.rst b/Documentation/trace/histogram.rst
index 7612c7ad5715..2a6b23f779bb 100644
--- a/Documentation/trace/histogram.rst
+++ b/Documentation/trace/histogram.rst
@@ -2121,33 +2121,33 @@ The following commonly-used handler.action pairs are available:
the end the event that triggered the snapshot (in this case you
can verify the timestamps between the sched_waking and
sched_switch events, which should match the time displayed in the
- global maximum):
+ global maximum)::
- # cat /sys/kernel/debug/tracing/snapshot
+ # cat /sys/kernel/debug/tracing/snapshot
- <...>-2103 [005] d..3 309.873125: sched_switch: prev_comm=cyclictest prev_pid=2103 prev_prio=19 prev_state=D ==> next_comm=swapper/5 next_pid=0 next_prio=120
- <idle>-0 [005] d.h3 309.873611: sched_waking: comm=cyclictest pid=2102 prio=19 target_cpu=005
- <idle>-0 [005] dNh4 309.873613: sched_wakeup: comm=cyclictest pid=2102 prio=19 target_cpu=005
- <idle>-0 [005] d..3 309.873616: sched_switch: prev_comm=swapper/5 prev_pid=0 prev_prio=120 prev_state=S ==> next_comm=cyclictest next_pid=2102 next_prio=19
- <...>-2102 [005] d..3 309.873625: sched_switch: prev_comm=cyclictest prev_pid=2102 prev_prio=19 prev_state=D ==> next_comm=swapper/5 next_pid=0 next_prio=120
- <idle>-0 [005] d.h3 309.874624: sched_waking: comm=cyclictest pid=2102 prio=19 target_cpu=005
- <idle>-0 [005] dNh4 309.874626: sched_wakeup: comm=cyclictest pid=2102 prio=19 target_cpu=005
- <idle>-0 [005] dNh3 309.874628: sched_waking: comm=cyclictest pid=2103 prio=19 target_cpu=005
- <idle>-0 [005] dNh4 309.874630: sched_wakeup: comm=cyclictest pid=2103 prio=19 target_cpu=005
- <idle>-0 [005] d..3 309.874633: sched_switch: prev_comm=swapper/5 prev_pid=0 prev_prio=120 prev_state=S ==> next_comm=cyclictest next_pid=2102 next_prio=19
- <idle>-0 [004] d.h3 309.874757: sched_waking: comm=gnome-terminal- pid=1699 prio=120 target_cpu=004
- <idle>-0 [004] dNh4 309.874762: sched_wakeup: comm=gnome-terminal- pid=1699 prio=120 target_cpu=004
- <idle>-0 [004] d..3 309.874766: sched_switch: prev_comm=swapper/4 prev_pid=0 prev_prio=120 prev_state=S ==> next_comm=gnome-terminal- next_pid=1699 next_prio=120
- gnome-terminal--1699 [004] d.h2 309.874941: sched_stat_runtime: comm=gnome-terminal- pid=1699 runtime=180706 [ns] vruntime=1126870572 [ns]
- <idle>-0 [003] d.s4 309.874956: sched_waking: comm=rcu_sched pid=9 prio=120 target_cpu=007
- <idle>-0 [003] d.s5 309.874960: sched_wake_idle_without_ipi: cpu=7
- <idle>-0 [003] d.s5 309.874961: sched_wakeup: comm=rcu_sched pid=9 prio=120 target_cpu=007
- <idle>-0 [007] d..3 309.874963: sched_switch: prev_comm=swapper/7 prev_pid=0 prev_prio=120 prev_state=S ==> next_comm=rcu_sched next_pid=9 next_prio=120
- rcu_sched-9 [007] d..3 309.874973: sched_stat_runtime: comm=rcu_sched pid=9 runtime=13646 [ns] vruntime=22531430286 [ns]
- rcu_sched-9 [007] d..3 309.874978: sched_switch: prev_comm=rcu_sched prev_pid=9 prev_prio=120 prev_state=R+ ==> next_comm=swapper/7 next_pid=0 next_prio=120
- <...>-2102 [005] d..4 309.874994: sched_migrate_task: comm=cyclictest pid=2103 prio=19 orig_cpu=5 dest_cpu=1
- <...>-2102 [005] d..4 309.875185: sched_wake_idle_without_ipi: cpu=1
- <idle>-0 [001] d..3 309.875200: sched_switch: prev_comm=swapper/1 prev_pid=0 prev_prio=120 prev_state=S ==> next_comm=cyclictest next_pid=2103 next_prio=19
+ <...>-2103 [005] d..3 309.873125: sched_switch: prev_comm=cyclictest prev_pid=2103 prev_prio=19 prev_state=D ==> next_comm=swapper/5 next_pid=0 next_prio=120
+ <idle>-0 [005] d.h3 309.873611: sched_waking: comm=cyclictest pid=2102 prio=19 target_cpu=005
+ <idle>-0 [005] dNh4 309.873613: sched_wakeup: comm=cyclictest pid=2102 prio=19 target_cpu=005
+ <idle>-0 [005] d..3 309.873616: sched_switch: prev_comm=swapper/5 prev_pid=0 prev_prio=120 prev_state=S ==> next_comm=cyclictest next_pid=2102 next_prio=19
+ <...>-2102 [005] d..3 309.873625: sched_switch: prev_comm=cyclictest prev_pid=2102 prev_prio=19 prev_state=D ==> next_comm=swapper/5 next_pid=0 next_prio=120
+ <idle>-0 [005] d.h3 309.874624: sched_waking: comm=cyclictest pid=2102 prio=19 target_cpu=005
+ <idle>-0 [005] dNh4 309.874626: sched_wakeup: comm=cyclictest pid=2102 prio=19 target_cpu=005
+ <idle>-0 [005] dNh3 309.874628: sched_waking: comm=cyclictest pid=2103 prio=19 target_cpu=005
+ <idle>-0 [005] dNh4 309.874630: sched_wakeup: comm=cyclictest pid=2103 prio=19 target_cpu=005
+ <idle>-0 [005] d..3 309.874633: sched_switch: prev_comm=swapper/5 prev_pid=0 prev_prio=120 prev_state=S ==> next_comm=cyclictest next_pid=2102 next_prio=19
+ <idle>-0 [004] d.h3 309.874757: sched_waking: comm=gnome-terminal- pid=1699 prio=120 target_cpu=004
+ <idle>-0 [004] dNh4 309.874762: sched_wakeup: comm=gnome-terminal- pid=1699 prio=120 target_cpu=004
+ <idle>-0 [004] d..3 309.874766: sched_switch: prev_comm=swapper/4 prev_pid=0 prev_prio=120 prev_state=S ==> next_comm=gnome-terminal- next_pid=1699 next_prio=120
+ gnome-terminal--1699 [004] d.h2 309.874941: sched_stat_runtime: comm=gnome-terminal- pid=1699 runtime=180706 [ns] vruntime=1126870572 [ns]
+ <idle>-0 [003] d.s4 309.874956: sched_waking: comm=rcu_sched pid=9 prio=120 target_cpu=007
+ <idle>-0 [003] d.s5 309.874960: sched_wake_idle_without_ipi: cpu=7
+ <idle>-0 [003] d.s5 309.874961: sched_wakeup: comm=rcu_sched pid=9 prio=120 target_cpu=007
+ <idle>-0 [007] d..3 309.874963: sched_switch: prev_comm=swapper/7 prev_pid=0 prev_prio=120 prev_state=S ==> next_comm=rcu_sched next_pid=9 next_prio=120
+ rcu_sched-9 [007] d..3 309.874973: sched_stat_runtime: comm=rcu_sched pid=9 runtime=13646 [ns] vruntime=22531430286 [ns]
+ rcu_sched-9 [007] d..3 309.874978: sched_switch: prev_comm=rcu_sched prev_pid=9 prev_prio=120 prev_state=R+ ==> next_comm=swapper/7 next_pid=0 next_prio=120
+ <...>-2102 [005] d..4 309.874994: sched_migrate_task: comm=cyclictest pid=2103 prio=19 orig_cpu=5 dest_cpu=1
+ <...>-2102 [005] d..4 309.875185: sched_wake_idle_without_ipi: cpu=1
+ <idle>-0 [001] d..3 309.875200: sched_switch: prev_comm=swapper/1 prev_pid=0 prev_prio=120 prev_state=S ==> next_comm=cyclictest next_pid=2103 next_prio=19
- onchange(var).save(field,.. .)
@@ -2201,9 +2201,10 @@ The following commonly-used handler.action pairs are available:
following the rest of the fields.
If a snaphot was taken, there is also a message indicating that,
- along with the value and event that triggered the snapshot:
+ along with the value and event that triggered the snapshot::
+
+ # cat /sys/kernel/debug/tracing/events/tcp/tcp_probe/hist
- # cat /sys/kernel/debug/tracing/events/tcp/tcp_probe/hist
{ dport: 1521 } hitcount: 8
changed: 10 snd_wnd: 35456 srtt: 154262 rcv_wnd: 42112
@@ -2216,14 +2217,15 @@ The following commonly-used handler.action pairs are available:
{ dport: 443 } hitcount: 211
changed: 10 snd_wnd: 26960 srtt: 17379 rcv_wnd: 28800
- Snapshot taken (see tracing/snapshot). Details:
+ Snapshot taken (see tracing/snapshot). Details::
+
triggering value { onchange($cwnd) }: 10
triggered by event with key: { dport: 80 }
- Totals:
- Hits: 414
- Entries: 4
- Dropped: 0
+ Totals:
+ Hits: 414
+ Entries: 4
+ Dropped: 0
In the above case, the event that triggered the snapshot has the
key with dport == 80. If you look at the bucket that has 80 as
@@ -2233,18 +2235,18 @@ The following commonly-used handler.action pairs are available:
the global snapshot).
And finally, looking at the snapshot data should show at or near
- the end the event that triggered the snapshot:
+ the end the event that triggered the snapshot::
- # cat /sys/kernel/debug/tracing/snapshot
+ # cat /sys/kernel/debug/tracing/snapshot
- gnome-shell-1261 [006] dN.3 49.823113: sched_stat_runtime: comm=gnome-shell pid=1261 runtime=49347 [ns] vruntime=1835730389 [ns]
- kworker/u16:4-773 [003] d..3 49.823114: sched_switch: prev_comm=kworker/u16:4 prev_pid=773 prev_prio=120 prev_state=R+ ==> next_comm=kworker/3:2 next_pid=135 next_prio=120
- gnome-shell-1261 [006] d..3 49.823114: sched_switch: prev_comm=gnome-shell prev_pid=1261 prev_prio=120 prev_state=R+ ==> next_comm=kworker/6:2 next_pid=387 next_prio=120
- kworker/3:2-135 [003] d..3 49.823118: sched_stat_runtime: comm=kworker/3:2 pid=135 runtime=5339 [ns] vruntime=17815800388 [ns]
- kworker/6:2-387 [006] d..3 49.823120: sched_stat_runtime: comm=kworker/6:2 pid=387 runtime=9594 [ns] vruntime=14589605367 [ns]
- kworker/6:2-387 [006] d..3 49.823122: sched_switch: prev_comm=kworker/6:2 prev_pid=387 prev_prio=120 prev_state=R+ ==> next_comm=gnome-shell next_pid=1261 next_prio=120
- kworker/3:2-135 [003] d..3 49.823123: sched_switch: prev_comm=kworker/3:2 prev_pid=135 prev_prio=120 prev_state=T ==> next_comm=swapper/3 next_pid=0 next_prio=120
- <idle>-0 [004] ..s7 49.823798: tcp_probe: src=10.0.0.10:54326 dest=23.215.104.193:80 mark=0x0 length=32 snd_nxt=0xe3ae2ff5 snd_una=0xe3ae2ecd snd_cwnd=10 ssthresh=2147483647 snd_wnd=28960 srtt=19604 rcv_wnd=29312
+ gnome-shell-1261 [006] dN.3 49.823113: sched_stat_runtime: comm=gnome-shell pid=1261 runtime=49347 [ns] vruntime=1835730389 [ns]
+ kworker/u16:4-773 [003] d..3 49.823114: sched_switch: prev_comm=kworker/u16:4 prev_pid=773 prev_prio=120 prev_state=R+ ==> next_comm=kworker/3:2 next_pid=135 next_prio=120
+ gnome-shell-1261 [006] d..3 49.823114: sched_switch: prev_comm=gnome-shell prev_pid=1261 prev_prio=120 prev_state=R+ ==> next_comm=kworker/6:2 next_pid=387 next_prio=120
+ kworker/3:2-135 [003] d..3 49.823118: sched_stat_runtime: comm=kworker/3:2 pid=135 runtime=5339 [ns] vruntime=17815800388 [ns]
+ kworker/6:2-387 [006] d..3 49.823120: sched_stat_runtime: comm=kworker/6:2 pid=387 runtime=9594 [ns] vruntime=14589605367 [ns]
+ kworker/6:2-387 [006] d..3 49.823122: sched_switch: prev_comm=kworker/6:2 prev_pid=387 prev_prio=120 prev_state=R+ ==> next_comm=gnome-shell next_pid=1261 next_prio=120
+ kworker/3:2-135 [003] d..3 49.823123: sched_switch: prev_comm=kworker/3:2 prev_pid=135 prev_prio=120 prev_state=T ==> next_comm=swapper/3 next_pid=0 next_prio=120
+ <idle>-0 [004] ..s7 49.823798: tcp_probe: src=10.0.0.10:54326 dest=23.215.104.193:80 mark=0x0 length=32 snd_nxt=0xe3ae2ff5 snd_una=0xe3ae2ecd snd_cwnd=10 ssthresh=2147483647 snd_wnd=28960 srtt=19604 rcv_wnd=29312
3. User space creating a trigger
--------------------------------
--
2.20.1
^ permalink raw reply related [flat|nested] 81+ messages in thread* [PATCH 02/57] docs: acpi: convert text files to ReST
2019-04-16 2:55 [PATCH 00/57] Convert files to ReST Mauro Carvalho Chehab
2019-04-16 2:55 ` [PATCH 01/57] docs: trace: fix some Sphinx warnings Mauro Carvalho Chehab
@ 2019-04-16 2:55 ` Mauro Carvalho Chehab
2019-04-16 8:17 ` Rafael J. Wysocki
2019-04-16 2:55 ` [PATCH 03/57] docs: aoe: " Mauro Carvalho Chehab
` (50 subsequent siblings)
52 siblings, 1 reply; 81+ messages in thread
From: Mauro Carvalho Chehab @ 2019-04-16 2:55 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Rafael J. Wysocki, Len Brown, linux-acpi
Most of the files are already in good shape, making easier to
convert them to ReST by adding proper title markups and
addressing some identation and markups to properly format the
document.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
Documentation/acpi/DSD-properties-rules.txt | 4 +-
Documentation/acpi/acpi-lid.txt | 37 +-
Documentation/acpi/aml-debugger.txt | 31 +-
Documentation/acpi/apei/einj.txt | 59 ++--
Documentation/acpi/apei/output_format.txt | 247 +++++++-------
Documentation/acpi/cppc_sysfs.txt | 52 +--
Documentation/acpi/debug.txt | 20 +-
.../acpi/dsd/data-node-references.txt | 11 +-
Documentation/acpi/dsd/graph.txt | 24 +-
Documentation/acpi/dsd/leds.txt | 18 +-
Documentation/acpi/dsdt-override.txt | 4 +-
Documentation/acpi/enumeration.txt | 42 +--
Documentation/acpi/gpio-properties.txt | 42 +--
Documentation/acpi/i2c-muxes.txt | 21 +-
Documentation/acpi/initrd_table_override.txt | 90 ++---
Documentation/acpi/linuxized-acpica.txt | 58 ++--
Documentation/acpi/lpit.txt | 8 +-
Documentation/acpi/method-customizing.txt | 48 ++-
Documentation/acpi/method-tracing.txt | 132 ++++---
Documentation/acpi/namespace.txt | 323 +++++++++---------
Documentation/acpi/osi.txt | 3 +-
Documentation/acpi/scan_handlers.txt | 9 +-
Documentation/acpi/ssdt-overlays.txt | 128 +++----
Documentation/acpi/video_extension.txt | 16 +-
24 files changed, 794 insertions(+), 633 deletions(-)
diff --git a/Documentation/acpi/DSD-properties-rules.txt b/Documentation/acpi/DSD-properties-rules.txt
index 3e4862bdad98..2b0307a897c1 100644
--- a/Documentation/acpi/DSD-properties-rules.txt
+++ b/Documentation/acpi/DSD-properties-rules.txt
@@ -1,5 +1,6 @@
+==================================
_DSD Device Properties Usage Rules
-----------------------------------
+==================================
Properties, Property Sets and Property Subsets
----------------------------------------------
@@ -94,4 +95,5 @@ 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
diff --git a/Documentation/acpi/acpi-lid.txt b/Documentation/acpi/acpi-lid.txt
index effe7af3a5af..a4bc51ee2db1 100644
--- a/Documentation/acpi/acpi-lid.txt
+++ b/Documentation/acpi/acpi-lid.txt
@@ -1,10 +1,14 @@
+=========================================================
Special Usage Model of the ACPI Control Method Lid Device
+=========================================================
Copyright (C) 2016, Intel Corporation
-Author: Lv Zheng <lv.zheng@intel.com>
+:Author: Lv Zheng <lv.zheng@intel.com>
-Abstract:
+
+Abstract
+========
Platforms containing lids convey lid state (open/close) to OSPMs using a
control method lid device. To implement this, the AML tables issue
@@ -20,6 +24,7 @@ expections of the Linux ACPI lid device driver.
1. Restrictions of the returning value of the _LID control method
+=================================================================
The _LID control method is described to return the "current" lid state.
However the word of "current" has ambiguity, some buggy AML tables return
@@ -31,6 +36,8 @@ with cached value, the initial returning value is likely not reliable.
There are platforms always retun "closed" as initial lid state.
2. Restrictions of the lid state change notifications
+=====================================================
+
There are buggy AML tables never notifying when the lid device state is
changed to "opened". Thus the "opened" notification is not guaranteed. But
@@ -40,26 +47,32 @@ trigger some system power saving operations on Windows. Since it is fully
tested, it is reliable from all AML tables.
3. Expections for the userspace users of the ACPI lid device driver
+===================================================================
The ACPI button driver exports the lid state to the userspace via the
following file:
+
/proc/acpi/button/lid/LID0/state
+
This file actually calls the _LID control method described above. And given
the previous explanation, it is not reliable enough on some platforms. So
it is advised for the userspace program to not to solely rely on this file
to determine the actual lid state.
The ACPI button driver emits the following input event to the userspace:
- SW_LID
-The ACPI lid device driver is implemented to try to deliver the platform
-triggered events to the userspace. However, given the fact that the buggy
-firmware cannot make sure "opened"/"closed" events are paired, the ACPI
-button driver uses the following 3 modes in order not to trigger issues.
+
+SW_LID
+ The ACPI lid device driver is implemented to try to deliver the platform
+ triggered events to the userspace. However, given the fact that the buggy
+ firmware cannot make sure "opened"/"closed" events are paired, the ACPI
+ button driver uses the following 3 modes in order not to trigger issues.
If the userspace hasn't been prepared to ignore the unreliable "opened"
events and the unreliable initial state notification, Linux users can use
the following kernel parameters to handle the possible issues:
-A. button.lid_init_state=method:
+
+A. `button.lid_init_state=method`:
+
When this option is specified, the ACPI button driver reports the
initial lid state using the returning value of the _LID control method
and whether the "opened"/"closed" events are paired fully relies on the
@@ -69,7 +82,9 @@ A. button.lid_init_state=method:
notification is missing.
This option is the default behavior during the period the userspace
isn't ready to handle the buggy AML tables.
-B. button.lid_init_state=open:
+
+B. `button.lid_init_state=open`:
+
When this option is specified, the ACPI button driver always reports the
initial lid state as "opened" and whether the "opened"/"closed" events
are paired fully relies on the firmware implementation.
@@ -80,7 +95,9 @@ B. button.lid_init_state=open:
If the userspace has been prepared to ignore the unreliable "opened" events
and the unreliable initial state notification, Linux users should always
use the following kernel parameter:
-C. button.lid_init_state=ignore:
+
+C. `button.lid_init_state=ignore`:
+
When this option is specified, the ACPI button driver never reports the
initial lid state and there is a compensation mechanism implemented to
ensure that the reliable "closed" notifications can always be delievered
diff --git a/Documentation/acpi/aml-debugger.txt b/Documentation/acpi/aml-debugger.txt
index 75ebeb64ab29..22144e0c496d 100644
--- a/Documentation/acpi/aml-debugger.txt
+++ b/Documentation/acpi/aml-debugger.txt
@@ -1,6 +1,9 @@
+================
The AML Debugger
+================
Copyright (C) 2016, Intel Corporation
+
Author: Lv Zheng <lv.zheng@intel.com>
@@ -10,16 +13,16 @@ kernel.
1. Build the debugger
The following kernel configuration items are required to enable the AML
- debugger interface from the Linux kernel:
+ debugger interface from the Linux kernel::
- CONFIG_ACPI_DEBUGGER=y
- CONFIG_ACPI_DEBUGGER_USER=m
+ CONFIG_ACPI_DEBUGGER=y
+ CONFIG_ACPI_DEBUGGER_USER=m
The userspace utilities can be built from the kernel source tree using
- the following commands:
+ the following commands::
- $ cd tools
- $ make acpi
+ $ cd tools
+ $ make acpi
The resultant userspace tool binary is then located at:
@@ -31,11 +34,11 @@ kernel.
2. Start the userspace debugger interface
After booting the kernel with the debugger built-in, the debugger can be
- started by using the following commands:
+ started by using the following commands::
- # mount -t debugfs none /sys/kernel/debug
- # modprobe acpi_dbg
- # tools/power/acpi/acpidbg
+ # mount -t debugfs none /sys/kernel/debug
+ # modprobe acpi_dbg
+ # tools/power/acpi/acpidbg
That spawns the interactive AML debugger environment where you can execute
debugger commands.
@@ -51,9 +54,9 @@ kernel.
3. Stop the userspace debugger interface
The interactive debugger interface can be closed by pressing Ctrl+C or using
- the "quit" or "exit" commands. When finished, unload the module with:
+ the "quit" or "exit" commands. When finished, unload the module with::
- # rmmod acpi_dbg
+ # rmmod acpi_dbg
The module unloading may fail if there is an acpidbg instance running.
@@ -61,6 +64,6 @@ kernel.
It may be useful to run the AML debugger in a test script. "acpidbg" supports
this in a special "batch" mode. For example, the following command outputs
- the entire ACPI namespace:
+ the entire ACPI namespace::
- # acpidbg -b "namespace"
+ # acpidbg -b "namespace"
diff --git a/Documentation/acpi/apei/einj.txt b/Documentation/acpi/apei/einj.txt
index e550c8b98139..4fe670dd2d4c 100644
--- a/Documentation/acpi/apei/einj.txt
+++ b/Documentation/acpi/apei/einj.txt
@@ -1,13 +1,14 @@
- APEI Error INJection
- ~~~~~~~~~~~~~~~~~~~~
+====================
+APEI Error INJection
+====================
EINJ provides a hardware error injection mechanism. It is very useful
for debugging and testing APEI and RAS features in general.
You need to check whether your BIOS supports EINJ first. For that, look
-for early boot messages similar to this one:
+for early boot messages similar to this one::
-ACPI: EINJ 0x000000007370A000 000150 (v01 INTEL 00000001 INTL 00000001)
+ ACPI: EINJ 0x000000007370A000 000150 (v01 INTEL 00000001 INTL 00000001)
which shows that the BIOS is exposing an EINJ table - it is the
mechanism through which the injection is done.
@@ -23,11 +24,11 @@ order to see the APEI,EINJ,... functionality supported and exposed by
the BIOS menu.
To use EINJ, make sure the following are options enabled in your kernel
-configuration:
+configuration::
-CONFIG_DEBUG_FS
-CONFIG_ACPI_APEI
-CONFIG_ACPI_APEI_EINJ
+ CONFIG_DEBUG_FS
+ CONFIG_ACPI_APEI
+ CONFIG_ACPI_APEI_EINJ
The EINJ user interface is in <debugfs mount point>/apei/einj.
@@ -37,8 +38,9 @@ The following files belong to it:
This file shows which error types are supported:
+ ================ ===================================
Error Type Value Error Description
- ================ =================
+ ================ ===================================
0x00000001 Processor Correctable
0x00000002 Processor Uncorrectable non-fatal
0x00000004 Processor Uncorrectable fatal
@@ -51,6 +53,7 @@ The following files belong to it:
0x00000200 Platform Correctable
0x00000400 Platform Uncorrectable non-fatal
0x00000800 Platform Uncorrectable fatal
+ ================ ===================================
The format of the file contents are as above, except present are only
the available error types.
@@ -121,7 +124,7 @@ BIOS versions based on the ACPI 5.0 specification have more control over
the target of the injection. For processor-related errors (type 0x1, 0x2
and 0x4), you can set flags to 0x3 (param3 for bit 0, and param1 and
param2 for bit 1) so that you have more information added to the error
-signature being injected. The actual data passed is this:
+signature being injected. The actual data passed is this::
memory_address = param1;
memory_address_range = param2;
@@ -131,7 +134,7 @@ signature being injected. The actual data passed is this:
For memory errors (type 0x8, 0x10 and 0x20) the address is set using
param1 with a mask in param2 (0x0 is equivalent to all ones). For PCI
express errors (type 0x40, 0x80 and 0x100) the segment, bus, device and
-function are specified using param1:
+function are specified using param1::
31 24 23 16 15 11 10 8 7 0
+-------------------------------------------------+
@@ -152,26 +155,26 @@ documentation for details (and expect changes to this API if vendors
creativity in using this feature expands beyond our expectations).
-An error injection example:
+An error injection example::
-# cd /sys/kernel/debug/apei/einj
-# cat available_error_type # See which errors can be injected
-0x00000002 Processor Uncorrectable non-fatal
-0x00000008 Memory Correctable
-0x00000010 Memory Uncorrectable non-fatal
-# echo 0x12345000 > param1 # Set memory address for injection
-# echo $((-1 << 12)) > param2 # Mask 0xfffffffffffff000 - anywhere in this page
-# echo 0x8 > error_type # Choose correctable memory error
-# echo 1 > error_inject # Inject now
+ # cd /sys/kernel/debug/apei/einj
+ # cat available_error_type # See which errors can be injected
+ 0x00000002 Processor Uncorrectable non-fatal
+ 0x00000008 Memory Correctable
+ 0x00000010 Memory Uncorrectable non-fatal
+ # echo 0x12345000 > param1 # Set memory address for injection
+ # echo $((-1 << 12)) > param2 # Mask 0xfffffffffffff000 - anywhere in this page
+ # echo 0x8 > error_type # Choose correctable memory error
+ # echo 1 > error_inject # Inject now
-You should see something like this in dmesg:
+You should see something like this in dmesg::
-[22715.830801] EDAC sbridge MC3: HANDLING MCE MEMORY ERROR
-[22715.834759] EDAC sbridge MC3: CPU 0: Machine Check Event: 0 Bank 7: 8c00004000010090
-[22715.834759] EDAC sbridge MC3: TSC 0
-[22715.834759] EDAC sbridge MC3: ADDR 12345000 EDAC sbridge MC3: MISC 144780c86
-[22715.834759] EDAC sbridge MC3: PROCESSOR 0:306e7 TIME 1422553404 SOCKET 0 APIC 0
-[22716.616173] EDAC MC3: 1 CE memory read error on CPU_SrcID#0_Channel#0_DIMM#0 (channel:0 slot:0 page:0x12345 offset:0x0 grain:32 syndrome:0x0 - area:DRAM err_code:0001:0090 socket:0 channel_mask:1 rank:0)
+ [22715.830801] EDAC sbridge MC3: HANDLING MCE MEMORY ERROR
+ [22715.834759] EDAC sbridge MC3: CPU 0: Machine Check Event: 0 Bank 7: 8c00004000010090
+ [22715.834759] EDAC sbridge MC3: TSC 0
+ [22715.834759] EDAC sbridge MC3: ADDR 12345000 EDAC sbridge MC3: MISC 144780c86
+ [22715.834759] EDAC sbridge MC3: PROCESSOR 0:306e7 TIME 1422553404 SOCKET 0 APIC 0
+ [22716.616173] EDAC MC3: 1 CE memory read error on CPU_SrcID#0_Channel#0_DIMM#0 (channel:0 slot:0 page:0x12345 offset:0x0 grain:32 syndrome:0x0 - area:DRAM err_code:0001:0090 socket:0 channel_mask:1 rank:0)
For more information about EINJ, please refer to ACPI specification
version 4.0, section 17.5 and ACPI 5.0, section 18.6.
diff --git a/Documentation/acpi/apei/output_format.txt b/Documentation/acpi/apei/output_format.txt
index 0c49c197c47a..b132bdd950b8 100644
--- a/Documentation/acpi/apei/output_format.txt
+++ b/Documentation/acpi/apei/output_format.txt
@@ -1,128 +1,129 @@
- APEI output format
- ~~~~~~~~~~~~~~~~~~
+==================
+APEI output format
+==================
APEI uses printk as hardware error reporting interface, the output
-format is as follow.
-
-<error record> :=
-APEI generic hardware error status
-severity: <integer>, <severity string>
-section: <integer>, severity: <integer>, <severity string>
-flags: <integer>
-<section flags strings>
-fru_id: <uuid string>
-fru_text: <string>
-section_type: <section type string>
-<section data>
-
-<severity string>* := recoverable | fatal | corrected | info
-
-<section flags strings># :=
-[primary][, containment warning][, reset][, threshold exceeded]\
-[, resource not accessible][, latent error]
-
-<section type string> := generic processor error | memory error | \
-PCIe error | unknown, <uuid string>
-
-<section data> :=
-<generic processor section data> | <memory section data> | \
-<pcie section data> | <null>
-
-<generic processor section data> :=
-[processor_type: <integer>, <proc type string>]
-[processor_isa: <integer>, <proc isa string>]
-[error_type: <integer>
-<proc error type strings>]
-[operation: <integer>, <proc operation string>]
-[flags: <integer>
-<proc flags strings>]
-[level: <integer>]
-[version_info: <integer>]
-[processor_id: <integer>]
-[target_address: <integer>]
-[requestor_id: <integer>]
-[responder_id: <integer>]
-[IP: <integer>]
-
-<proc type string>* := IA32/X64 | IA64
-
-<proc isa string>* := IA32 | IA64 | X64
-
-<processor error type strings># :=
-[cache error][, TLB error][, bus error][, micro-architectural error]
-
-<proc operation string>* := unknown or generic | data read | data write | \
-instruction execution
-
-<proc flags strings># :=
-[restartable][, precise IP][, overflow][, corrected]
-
-<memory section data> :=
-[error_status: <integer>]
-[physical_address: <integer>]
-[physical_address_mask: <integer>]
-[node: <integer>]
-[card: <integer>]
-[module: <integer>]
-[bank: <integer>]
-[device: <integer>]
-[row: <integer>]
-[column: <integer>]
-[bit_position: <integer>]
-[requestor_id: <integer>]
-[responder_id: <integer>]
-[target_id: <integer>]
-[error_type: <integer>, <mem error type string>]
-
-<mem error type string>* :=
-unknown | no error | single-bit ECC | multi-bit ECC | \
-single-symbol chipkill ECC | multi-symbol chipkill ECC | master abort | \
-target abort | parity error | watchdog timeout | invalid address | \
-mirror Broken | memory sparing | scrub corrected error | \
-scrub uncorrected error
-
-<pcie section data> :=
-[port_type: <integer>, <pcie port type string>]
-[version: <integer>.<integer>]
-[command: <integer>, status: <integer>]
-[device_id: <integer>:<integer>:<integer>.<integer>
-slot: <integer>
-secondary_bus: <integer>
-vendor_id: <integer>, device_id: <integer>
-class_code: <integer>]
-[serial number: <integer>, <integer>]
-[bridge: secondary_status: <integer>, control: <integer>]
-[aer_status: <integer>, aer_mask: <integer>
-<aer status string>
-[aer_uncor_severity: <integer>]
-aer_layer=<aer layer string>, aer_agent=<aer agent string>
-aer_tlp_header: <integer> <integer> <integer> <integer>]
-
-<pcie port type string>* := PCIe end point | legacy PCI end point | \
-unknown | unknown | root port | upstream switch port | \
-downstream switch port | PCIe to PCI/PCI-X bridge | \
-PCI/PCI-X to PCIe bridge | root complex integrated endpoint device | \
-root complex event collector
-
-if section severity is fatal or recoverable
-<aer status string># :=
-unknown | unknown | unknown | unknown | Data Link Protocol | \
-unknown | unknown | unknown | unknown | unknown | unknown | unknown | \
-Poisoned TLP | Flow Control Protocol | Completion Timeout | \
-Completer Abort | Unexpected Completion | Receiver Overflow | \
-Malformed TLP | ECRC | Unsupported Request
-else
-<aer status string># :=
-Receiver Error | unknown | unknown | unknown | unknown | unknown | \
-Bad TLP | Bad DLLP | RELAY_NUM Rollover | unknown | unknown | unknown | \
-Replay Timer Timeout | Advisory Non-Fatal
-fi
-
-<aer layer string> :=
-Physical Layer | Data Link Layer | Transaction Layer
-
-<aer agent string> :=
-Receiver ID | Requester ID | Completer ID | Transmitter ID
+format is as follow::
+
+ <error record> :=
+ APEI generic hardware error status
+ severity: <integer>, <severity string>
+ section: <integer>, severity: <integer>, <severity string>
+ flags: <integer>
+ <section flags strings>
+ fru_id: <uuid string>
+ fru_text: <string>
+ section_type: <section type string>
+ <section data>
+
+ <severity string>* := recoverable | fatal | corrected | info
+
+ <section flags strings># :=
+ [primary][, containment warning][, reset][, threshold exceeded]\
+ [, resource not accessible][, latent error]
+
+ <section type string> := generic processor error | memory error | \
+ PCIe error | unknown, <uuid string>
+
+ <section data> :=
+ <generic processor section data> | <memory section data> | \
+ <pcie section data> | <null>
+
+ <generic processor section data> :=
+ [processor_type: <integer>, <proc type string>]
+ [processor_isa: <integer>, <proc isa string>]
+ [error_type: <integer>
+ <proc error type strings>]
+ [operation: <integer>, <proc operation string>]
+ [flags: <integer>
+ <proc flags strings>]
+ [level: <integer>]
+ [version_info: <integer>]
+ [processor_id: <integer>]
+ [target_address: <integer>]
+ [requestor_id: <integer>]
+ [responder_id: <integer>]
+ [IP: <integer>]
+
+ <proc type string>* := IA32/X64 | IA64
+
+ <proc isa string>* := IA32 | IA64 | X64
+
+ <processor error type strings># :=
+ [cache error][, TLB error][, bus error][, micro-architectural error]
+
+ <proc operation string>* := unknown or generic | data read | data write | \
+ instruction execution
+
+ <proc flags strings># :=
+ [restartable][, precise IP][, overflow][, corrected]
+
+ <memory section data> :=
+ [error_status: <integer>]
+ [physical_address: <integer>]
+ [physical_address_mask: <integer>]
+ [node: <integer>]
+ [card: <integer>]
+ [module: <integer>]
+ [bank: <integer>]
+ [device: <integer>]
+ [row: <integer>]
+ [column: <integer>]
+ [bit_position: <integer>]
+ [requestor_id: <integer>]
+ [responder_id: <integer>]
+ [target_id: <integer>]
+ [error_type: <integer>, <mem error type string>]
+
+ <mem error type string>* :=
+ unknown | no error | single-bit ECC | multi-bit ECC | \
+ single-symbol chipkill ECC | multi-symbol chipkill ECC | master abort | \
+ target abort | parity error | watchdog timeout | invalid address | \
+ mirror Broken | memory sparing | scrub corrected error | \
+ scrub uncorrected error
+
+ <pcie section data> :=
+ [port_type: <integer>, <pcie port type string>]
+ [version: <integer>.<integer>]
+ [command: <integer>, status: <integer>]
+ [device_id: <integer>:<integer>:<integer>.<integer>
+ slot: <integer>
+ secondary_bus: <integer>
+ vendor_id: <integer>, device_id: <integer>
+ class_code: <integer>]
+ [serial number: <integer>, <integer>]
+ [bridge: secondary_status: <integer>, control: <integer>]
+ [aer_status: <integer>, aer_mask: <integer>
+ <aer status string>
+ [aer_uncor_severity: <integer>]
+ aer_layer=<aer layer string>, aer_agent=<aer agent string>
+ aer_tlp_header: <integer> <integer> <integer> <integer>]
+
+ <pcie port type string>* := PCIe end point | legacy PCI end point | \
+ unknown | unknown | root port | upstream switch port | \
+ downstream switch port | PCIe to PCI/PCI-X bridge | \
+ PCI/PCI-X to PCIe bridge | root complex integrated endpoint device | \
+ root complex event collector
+
+ if section severity is fatal or recoverable
+ <aer status string># :=
+ unknown | unknown | unknown | unknown | Data Link Protocol | \
+ unknown | unknown | unknown | unknown | unknown | unknown | unknown | \
+ Poisoned TLP | Flow Control Protocol | Completion Timeout | \
+ Completer Abort | Unexpected Completion | Receiver Overflow | \
+ Malformed TLP | ECRC | Unsupported Request
+ else
+ <aer status string># :=
+ Receiver Error | unknown | unknown | unknown | unknown | unknown | \
+ Bad TLP | Bad DLLP | RELAY_NUM Rollover | unknown | unknown | unknown | \
+ Replay Timer Timeout | Advisory Non-Fatal
+ fi
+
+ <aer layer string> :=
+ Physical Layer | Data Link Layer | Transaction Layer
+
+ <aer agent string> :=
+ Receiver ID | Requester ID | Completer ID | Transmitter ID
Where, [] designate corresponding content is optional
diff --git a/Documentation/acpi/cppc_sysfs.txt b/Documentation/acpi/cppc_sysfs.txt
index f20fb445135d..e4c6bb5a3333 100644
--- a/Documentation/acpi/cppc_sysfs.txt
+++ b/Documentation/acpi/cppc_sysfs.txt
@@ -1,5 +1,6 @@
-
- Collaborative Processor Performance Control (CPPC)
+==================================================
+Collaborative Processor Performance Control (CPPC)
+==================================================
CPPC defined in the ACPI spec describes a mechanism for the OS to manage the
performance of a logical processor on a contigious and abstract performance
@@ -8,28 +9,30 @@ to request performance levels and to measure per-cpu delivered performance.
For more details on CPPC please refer to the ACPI specification at:
-http://uefi.org/specifications
+ http://uefi.org/specifications
Some of the CPPC registers are exposed via sysfs under:
-/sys/devices/system/cpu/cpuX/acpi_cppc/
+ /sys/devices/system/cpu/cpuX/acpi_cppc/
for each cpu X
--------------------------------------------------------------------------------
-$ ls -lR /sys/devices/system/cpu/cpu0/acpi_cppc/
-/sys/devices/system/cpu/cpu0/acpi_cppc/:
-total 0
--r--r--r-- 1 root root 65536 Mar 5 19:38 feedback_ctrs
--r--r--r-- 1 root root 65536 Mar 5 19:38 highest_perf
--r--r--r-- 1 root root 65536 Mar 5 19:38 lowest_freq
--r--r--r-- 1 root root 65536 Mar 5 19:38 lowest_nonlinear_perf
--r--r--r-- 1 root root 65536 Mar 5 19:38 lowest_perf
--r--r--r-- 1 root root 65536 Mar 5 19:38 nominal_freq
--r--r--r-- 1 root root 65536 Mar 5 19:38 nominal_perf
--r--r--r-- 1 root root 65536 Mar 5 19:38 reference_perf
--r--r--r-- 1 root root 65536 Mar 5 19:38 wraparound_time
+::
+
+ $ ls -lR /sys/devices/system/cpu/cpu0/acpi_cppc/
+ /sys/devices/system/cpu/cpu0/acpi_cppc/:
+ total 0
+ -r--r--r-- 1 root root 65536 Mar 5 19:38 feedback_ctrs
+ -r--r--r-- 1 root root 65536 Mar 5 19:38 highest_perf
+ -r--r--r-- 1 root root 65536 Mar 5 19:38 lowest_freq
+ -r--r--r-- 1 root root 65536 Mar 5 19:38 lowest_nonlinear_perf
+ -r--r--r-- 1 root root 65536 Mar 5 19:38 lowest_perf
+ -r--r--r-- 1 root root 65536 Mar 5 19:38 nominal_freq
+ -r--r--r-- 1 root root 65536 Mar 5 19:38 nominal_perf
+ -r--r--r-- 1 root root 65536 Mar 5 19:38 reference_perf
+ -r--r--r-- 1 root root 65536 Mar 5 19:38 wraparound_time
--------------------------------------------------------------------------------
@@ -54,16 +57,17 @@ total 0
--------------------------------------------------------------------------------
- Computing Average Delivered Performance
+Computing Average Delivered Performance
+=======================================
Below describes the steps to compute the average performance delivered by taking
-two different snapshots of feedback counters at time T1 and T2.
+two different snapshots of feedback counters at time T1 and T2::
-T1: Read feedback_ctrs as fbc_t1
- Wait or run some workload
-T2: Read feedback_ctrs as fbc_t2
+ T1: Read feedback_ctrs as fbc_t1
+ Wait or run some workload
+ T2: Read feedback_ctrs as fbc_t2
-delivered_counter_delta = fbc_t2[del] - fbc_t1[del]
-reference_counter_delta = fbc_t2[ref] - fbc_t1[ref]
+ delivered_counter_delta = fbc_t2[del] - fbc_t1[del]
+ reference_counter_delta = fbc_t2[ref] - fbc_t1[ref]
-delivered_perf = (refernce_perf x delivered_counter_delta) / reference_counter_delta
+ delivered_perf = (refernce_perf x delivered_counter_delta) / reference_counter_delta
diff --git a/Documentation/acpi/debug.txt b/Documentation/acpi/debug.txt
index 65bf47c46b6d..259a12a1e6a9 100644
--- a/Documentation/acpi/debug.txt
+++ b/Documentation/acpi/debug.txt
@@ -1,4 +1,6 @@
- ACPI Debug Output
+=================
+ACPI Debug Output
+=================
The ACPI CA, the Linux ACPI core, and some ACPI drivers can generate debug
@@ -33,7 +35,7 @@ to /sys/module/acpi/parameters/debug_layer.
The possible components are defined in include/acpi/acoutput.h and
include/acpi/acpi_drivers.h. Reading /sys/module/acpi/parameters/debug_layer
-shows the supported mask values, currently these:
+shows the supported mask values, currently these::
ACPI_UTILITIES 0x00000001
ACPI_HARDWARE 0x00000002
@@ -81,7 +83,7 @@ to /sys/module/acpi/parameters/debug_level.
The possible levels are defined in include/acpi/acoutput.h. Reading
/sys/module/acpi/parameters/debug_level shows the supported mask values,
-currently these:
+currently these::
ACPI_LV_INIT 0x00000001
ACPI_LV_DEBUG_OBJECT 0x00000002
@@ -115,7 +117,7 @@ currently these:
Examples
--------
-For example, drivers/acpi/bus.c contains this:
+For example, drivers/acpi/bus.c contains this::
#define _COMPONENT ACPI_BUS_COMPONENT
...
@@ -127,22 +129,22 @@ statement uses ACPI_DB_INFO, which is macro based on the ACPI_LV_INFO
definition.)
Enable all AML "Debug" output (stores to the Debug object while interpreting
-AML) during boot:
+AML) during boot::
acpi.debug_layer=0xffffffff acpi.debug_level=0x2
-Enable PCI and PCI interrupt routing debug messages:
+Enable PCI and PCI interrupt routing debug messages::
acpi.debug_layer=0x400000 acpi.debug_level=0x4
-Enable all ACPI hardware-related messages:
+Enable all ACPI hardware-related messages::
acpi.debug_layer=0x2 acpi.debug_level=0xffffffff
-Enable all ACPI_DB_INFO messages after boot:
+Enable all ACPI_DB_INFO messages after boot::
# echo 0x4 > /sys/module/acpi/parameters/debug_level
-Show all valid component values:
+Show all valid component values::
# cat /sys/module/acpi/parameters/debug_layer
diff --git a/Documentation/acpi/dsd/data-node-references.txt b/Documentation/acpi/dsd/data-node-references.txt
index c3871565c8cf..9ccd02bf060c 100644
--- a/Documentation/acpi/dsd/data-node-references.txt
+++ b/Documentation/acpi/dsd/data-node-references.txt
@@ -1,4 +1,9 @@
+====================
+Data Node References
+====================
+
Copyright (C) 2018 Intel Corporation
+
Author: Sakari Ailus <sakari.ailus@linux.intel.com>
@@ -30,6 +35,8 @@ extension key.
Example
-------
+::
+
In the ASL snippet below, the "reference" _DSD property [2] contains a
device object reference to DEV0 and under that device object, a
hierarchical data extension key "node@1" referring to the NOD1 object
@@ -81,9 +88,9 @@ References
----------
[1] Hierarchical Data Extension UUID For _DSD.
- <URL:http://www.uefi.org/sites/default/files/resources/_DSD-hierarchical-data-extension-UUID-v1.1.pdf>,
+ http://www.uefi.org/sites/default/files/resources/_DSD-hierarchical-data-extension-UUID-v1.1.pdf,
referenced 2018-07-17.
[2] Device Properties UUID For _DSD.
- <URL:http://www.uefi.org/sites/default/files/resources/_DSD-device-properties-UUID.pdf>,
+ http://www.uefi.org/sites/default/files/resources/_DSD-device-properties-UUID.pdf,
referenced 2016-10-04.
diff --git a/Documentation/acpi/dsd/graph.txt b/Documentation/acpi/dsd/graph.txt
index b9ce910781dc..618deddcf512 100644
--- a/Documentation/acpi/dsd/graph.txt
+++ b/Documentation/acpi/dsd/graph.txt
@@ -1,4 +1,6 @@
+======
Graphs
+======
_DSD
@@ -40,7 +42,7 @@ All port nodes are located under the device's "_DSD" node in the hierarchical
data extension tree. The data extension related to each port node must begin
with "port" and must be followed by the "@" character and the number of the port
as its key. The target object it refers to should be called "PRTX", where "X" is
-the number of the port. An example of such a package would be:
+the number of the port. An example of such a package would be::
Package() { "port@4", PRT4 }
@@ -49,7 +51,7 @@ data extension key of the endpoint nodes must begin with
"endpoint" and must be followed by the "@" character and the number of the
endpoint. The object it refers to should be called "EPXY", where "X" is the
number of the port and "Y" is the number of the endpoint. An example of such a
-package would be:
+package would be::
Package() { "endpoint@0", EP40 }
@@ -65,7 +67,7 @@ The endpoint reference uses property extension with "remote-endpoint" property
name followed by a reference in the same package. Such references consist of the
the remote device reference, the first package entry of the port data extension
reference under the device and finally the first package entry of the endpoint
-data extension reference under the port. Individual references thus appear as:
+data extension reference under the port. Individual references thus appear as::
Package() { device, "port@X", "endpoint@Y" }
@@ -75,7 +77,7 @@ endpoint.
The references to endpoints must be always done both ways, to the
remote endpoint and back from the referred remote endpoint node.
-A simple example of this is show below:
+A simple example of this is show below::
Scope (\_SB.PCI0.I2C2)
{
@@ -151,23 +153,25 @@ References
----------
[1] _DSD (Device Specific Data) Implementation Guide.
- <URL:http://www.uefi.org/sites/default/files/resources/_DSD-implementation-guide-toplevel-1_1.htm>,
+ http://www.uefi.org/sites/default/files/resources/_DSD-implementation-guide-toplevel-1_1.htm,
referenced 2016-10-03.
-[2] Devicetree. <URL:http://www.devicetree.org>, referenced 2016-10-03.
+[2] Devicetree.
+ http://www.devicetree.org, referenced 2016-10-03.
-[3] Documentation/devicetree/bindings/graph.txt
+[3] Linux Kernel device tree graph rules.
+ Documentation/devicetree/bindings/graph.txt
[4] Device Properties UUID For _DSD.
- <URL:http://www.uefi.org/sites/default/files/resources/_DSD-device-properties-UUID.pdf>,
+ http://www.uefi.org/sites/default/files/resources/_DSD-device-properties-UUID.pdf,
referenced 2016-10-04.
[5] Hierarchical Data Extension UUID For _DSD.
- <URL:http://www.uefi.org/sites/default/files/resources/_DSD-hierarchical-data-extension-UUID-v1.1.pdf>,
+ URL:http://www.uefi.org/sites/default/files/resources/_DSD-hierarchical-data-extension-UUID-v1.1.pdf,
referenced 2016-10-04.
[6] Advanced Configuration and Power Interface Specification.
- <URL:http://www.uefi.org/sites/default/files/resources/ACPI_6_1.pdf>,
+ http://www.uefi.org/sites/default/files/resources/ACPI_6_1.pdf,
referenced 2016-10-04.
[7] _DSD Device Properties Usage Rules.
diff --git a/Documentation/acpi/dsd/leds.txt b/Documentation/acpi/dsd/leds.txt
index 81a63af42ed2..82ccd5cfb1fd 100644
--- a/Documentation/acpi/dsd/leds.txt
+++ b/Documentation/acpi/dsd/leds.txt
@@ -1,4 +1,6 @@
+========================================
Describing and referring to LEDs in ACPI
+========================================
Individual LEDs are described by hierarchical data extension [6] nodes under the
device node, the LED driver chip. The "reg" property in the LED specific nodes
@@ -26,7 +28,7 @@ followed by the referred object name. That object shall be named "LED" followed
by the number of the LED.
An ASL example of a camera sensor device and a LED driver device for two LEDs.
-Objects not relevant for LEDs or the references to them have been omitted.
+Objects not relevant for LEDs or the references to them have been omitted::
Device (LED)
{
@@ -72,10 +74,14 @@ Objects not relevant for LEDs or the references to them have been omitted.
where
- LED LED driver device
- LED0 First LED
- LED1 Second LED
- SEN Camera sensor device (or another device the LED is
+ LED
+ LED driver device
+ LED0
+ First LED
+ LED1
+ Second LED
+ SEN
+ Camera sensor device (or another device the LED is
related to)
[1] Device tree. <URL:http://www.devicetree.org>, referenced 2019-02-21.
@@ -96,4 +102,4 @@ where
<URL:http://www.uefi.org/sites/default/files/resources/_DSD-hierarchical-data-extension-UUID-v1.1.pdf>,
referenced 2019-02-21.
-[7] Documentation/acpi/dsd/data-node-reference.txt
+[7] Documentation/acpi/dsd/data-node-references.txt
diff --git a/Documentation/acpi/dsdt-override.txt b/Documentation/acpi/dsdt-override.txt
index 784841caa6e6..d483b1957be1 100644
--- a/Documentation/acpi/dsdt-override.txt
+++ b/Documentation/acpi/dsdt-override.txt
@@ -1,4 +1,6 @@
-Linux supports a method of overriding the BIOS DSDT:
+===================================================
+Linux supports a method of overriding the BIOS DSDT
+===================================================
CONFIG_ACPI_CUSTOM_DSDT builds the image into the kernel.
diff --git a/Documentation/acpi/enumeration.txt b/Documentation/acpi/enumeration.txt
index 1395b844649c..5b740fb9054b 100644
--- a/Documentation/acpi/enumeration.txt
+++ b/Documentation/acpi/enumeration.txt
@@ -1,5 +1,7 @@
+=============================
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,10 +13,10 @@ 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
+ - Devices that have no bus connector resource are represented as
platform devices.
- o Devices behind real busses where there is a connector resource
+ - 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).
@@ -39,7 +41,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[] = {
@@ -66,7 +68,7 @@ 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 +76,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 +116,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)
{
@@ -143,7 +145,7 @@ 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 +165,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 +184,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 +204,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;
@@ -227,7 +229,7 @@ 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[] = {
@@ -257,10 +259,10 @@ 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)
-{
+ Device (DEV)
+ {
Method (_CRS, 0, NotSerialized)
{
Name (SBUF, ResourceTemplate()
@@ -310,7 +312,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>
...
@@ -340,15 +342,15 @@ 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",
@@ -412,7 +414,7 @@ will be enumerated to depends on the device ID returned by _HID.
For example, the following ACPI sample might be used to enumerate an lm75-type
I2C temperature sensor and match it to the driver using the Device Tree
-namespace link:
+namespace link::
Device (TMP0)
{
diff --git a/Documentation/acpi/gpio-properties.txt b/Documentation/acpi/gpio-properties.txt
index 88c65cb5bf0a..d8ba7a06db73 100644
--- a/Documentation/acpi/gpio-properties.txt
+++ b/Documentation/acpi/gpio-properties.txt
@@ -1,5 +1,6 @@
+======================================
_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 +9,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,7 +35,7 @@ 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 }}
@@ -55,7 +56,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",
@@ -78,7 +79,7 @@ _DSD device properties for GPIO controllers:
- input
- line-name
-Example:
+Example::
Name (_DSD, Package () {
// _DSD Hierarchical Properties Extension UUID
@@ -100,7 +101,7 @@ Example:
- gpio-line-names
-Example:
+Example::
Package () {
"gpio-line-names",
@@ -139,16 +140,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
@@ -163,7 +164,7 @@ 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 +178,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::
desc = gpiod_get(dev, "reset", GPIOD_OUT_LOW);
@@ -195,18 +196,21 @@ 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);
We may consider two different cases here, i.e. when connection ID is
provided and otherwise.
-Case 1:
+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);
diff --git a/Documentation/acpi/i2c-muxes.txt b/Documentation/acpi/i2c-muxes.txt
index 9fcc4f0b885e..5481cf1ad272 100644
--- a/Documentation/acpi/i2c-muxes.txt
+++ b/Documentation/acpi/i2c-muxes.txt
@@ -1,20 +1,21 @@
+==============
ACPI I2C Muxes
---------------
+==============
Describing an I2C device hierarchy that includes I2C muxes requires an ACPI
Device () scope per mux channel.
-Consider this topology:
+Consider this topology::
-+------+ +------+
-| SMB1 |-->| MUX0 |--CH00--> i2c client A (0x50)
-| | | 0x70 |--CH01--> i2c client B (0x50)
-+------+ +------+
+ +------+ +------+
+ | SMB1 |-->| MUX0 |--CH00--> i2c client A (0x50)
+ | | | 0x70 |--CH01--> i2c client B (0x50)
+ +------+ +------+
-which corresponds to the following ASL:
+which corresponds to the following ASL::
-Device (SMB1)
-{
+ Device (SMB1)
+ {
Name (_HID, ...)
Device (MUX0)
{
@@ -55,4 +56,4 @@ Device (SMB1)
}
}
}
-}
+ }
diff --git a/Documentation/acpi/initrd_table_override.txt b/Documentation/acpi/initrd_table_override.txt
index 30437a6db373..1b89103f810a 100644
--- a/Documentation/acpi/initrd_table_override.txt
+++ b/Documentation/acpi/initrd_table_override.txt
@@ -1,3 +1,4 @@
+================================
Upgrading ACPI tables via initrd
================================
@@ -19,12 +20,14 @@ 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
+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.
@@ -50,47 +53,48 @@ 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"
+# 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.
@@ -106,6 +110,8 @@ 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/acpi/linuxized-acpica.txt b/Documentation/acpi/linuxized-acpica.txt
index 3ad7b0dfb083..bb5e7e49e175 100644
--- a/Documentation/acpi/linuxized-acpica.txt
+++ b/Documentation/acpi/linuxized-acpica.txt
@@ -1,10 +1,14 @@
+============================================================
Linuxized ACPICA - Introduction to ACPICA Release Automation
+============================================================
Copyright (C) 2013-2016, Intel Corporation
+
Author: Lv Zheng <lv.zheng@intel.com>
-Abstract:
+Abstract
+========
This document describes the ACPICA project and the relationship between
ACPICA and Linux. It also describes how ACPICA code in drivers/acpi/acpica,
@@ -13,6 +17,7 @@ upstream.
1. ACPICA Project
+=================
The ACPI Component Architecture (ACPICA) project provides an operating
system (OS)-independent reference implementation of the Advanced
@@ -25,7 +30,7 @@ upstream.
supported by Intel Corporation.
The following figure depicts the Linux ACPI subsystem where the ACPICA
- adaptation is included:
+ adaptation is included::
+---------------------------------------------------------+
| |
@@ -72,34 +77,43 @@ upstream.
Figure 1. Linux ACPI Software Components
NOTE:
+
A. OS Service Layer - Provided by Linux to offer OS dependent
- implementation of the predefined ACPICA interfaces (acpi_os_*).
+ 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_*).
+ 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.
+ programs::
+
drivers/acpi
include/linux/acpi.h
include/linux/acpi*.h
include/acpi
tools/power/acpi
+
D. Architecture Specific ACPICA/ACPI Functionalities - Provided by the
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.
+ the scope of this document::
+
include/asm/acpi.h
include/asm/acpi*.h
arch/*/acpi
2. 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
@@ -112,7 +126,7 @@ upstream.
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:
+ illustrated in the following figure::
+-----------------------------+
| acpica / master (-) commits |
@@ -154,6 +168,7 @@ upstream.
Figure 2. ACPICA -> Linux Upstream Process
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.
@@ -171,6 +186,7 @@ upstream.
CONFIG_ACPI/CONFIG_ACPI_DEBUG/CONFIG_ACPI_DEBUGGER
3. ACPICA Divergences
+=====================
Ideally, all of the ACPICA commits should be converted into Linux patches
automatically without manual modifications, the "linux / master" tree should
@@ -183,6 +199,7 @@ upstream.
"ACPICA Divergences".
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
@@ -214,6 +231,7 @@ upstream.
divergences are generated.
4. ACPICA Development
+=====================
This paragraph guides Linux developers to use the ACPICA upstream release
utilities to obtain Linux patches corresponding to upstream ACPICA commits
@@ -225,11 +243,11 @@ 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
- $ generate/linux/gen-patch.sh -u [commit ID]
+ $ git clone https://github.com/acpica/acpica
+ $ cd acpica
+ $ generate/linux/gen-patch.sh -u [commit ID]
Here the commit ID is the ACPICA local repository commit ID you want to
cherry pick. It can be omitted if the commit is "HEAD".
@@ -240,11 +258,11 @@ 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
- $ generate/linux/make-patches.sh -u [commit ID]
+ $ git clone https://github.com/acpica/acpica
+ $ cd acpica
+ $ generate/linux/make-patches.sh -u [commit ID]
The commit ID should be the last ACPICA commit accepted by Linux. Usually,
it is the commit modifying ACPI_CA_VERSION. It can be found by executing
@@ -254,9 +272,9 @@ 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
- # cd acpica
- # generate/linux/divergences.sh -s ../linux
+ # git clone https://github.com/acpica/acpica
+ # git clone http://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
+ # cd acpica
+ # generate/linux/divergences.sh -s ../linux
diff --git a/Documentation/acpi/lpit.txt b/Documentation/acpi/lpit.txt
index b426398d2e97..b01c97c6f739 100644
--- a/Documentation/acpi/lpit.txt
+++ b/Documentation/acpi/lpit.txt
@@ -1,3 +1,7 @@
+=====================
+Low Power Idle states
+=====================
+
To enumerate platform Low Power Idle states, Intel platforms are using
“Low Power Idle Table” (LPIT). More details about this table can be
downloaded from:
@@ -8,11 +12,13 @@ Residencies for each low power state can be read via FFH
On platforms supporting S0ix sleep states, there can be two types of
residencies:
+
- CPU PKG C10 (Read via FFH interface)
- Platform Controller Hub (PCH) SLP_S0 (Read via memory mapped interface)
The following attributes are added dynamically to the cpuidle
-sysfs attribute group:
+sysfs attribute group::
+
/sys/devices/system/cpu/cpuidle/low_power_idle_cpu_residency_us
/sys/devices/system/cpu/cpuidle/low_power_idle_system_residency_us
diff --git a/Documentation/acpi/method-customizing.txt b/Documentation/acpi/method-customizing.txt
index 7235da975f23..4a00a52e69f0 100644
--- a/Documentation/acpi/method-customizing.txt
+++ b/Documentation/acpi/method-customizing.txt
@@ -1,3 +1,4 @@
+=======================================
Linux ACPI Custom Control Method How To
=======================================
@@ -7,47 +8,58 @@ 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
+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,
+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)),
+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,
+ Here is an example of a customized \_SB._AC._PSR method::
- DefinitionBlock ("", "SSDT", 1, "", "", 0x20080715)
- {
- Method (\_SB_.AC._PSR, 0, NotSerialized)
- {
+ 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,
+ 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"
+ f) mount debugfs by running::
+
+ 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.
@@ -62,12 +74,14 @@ Note: To get the ACPI debug object output (Store (AAAA, Debug)),
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,
+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
+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/acpi/method-tracing.txt b/Documentation/acpi/method-tracing.txt
index 0aba14c8f459..779475fecefb 100644
--- a/Documentation/acpi/method-tracing.txt
+++ b/Documentation/acpi/method-tracing.txt
@@ -1,15 +1,20 @@
+=====================
ACPICA Trace Facility
+=====================
Copyright (C) 2015, Intel Corporation
+
Author: Lv Zheng <lv.zheng@intel.com>
Abstract:
+=========
This document describes the functions and the interfaces of the method
tracing facility.
1. Functionalities and usage examples:
+======================================
ACPICA provides method tracing capability. And two functions are
currently implemented using this capability.
@@ -31,30 +36,38 @@ tracing facility.
The following command examples illustrate the usage of the "log reducer"
functionality:
+
a. Filter out the debug layer/level matched logs when control methods
- are being evaluated:
- # cd /sys/module/acpi/parameters
- # echo "0xXXXXXXXX" > trace_debug_layer
- # echo "0xYYYYYYYY" > trace_debug_level
- # echo "enable" > trace_state
+ are being evaluated::
+
+ # cd /sys/module/acpi/parameters
+ # echo "0xXXXXXXXX" > trace_debug_layer
+ # echo "0xYYYYYYYY" > trace_debug_level
+ # echo "enable" > trace_state
+
b. Filter out the debug layer/level matched logs when the specified
- control method is being evaluated:
- # cd /sys/module/acpi/parameters
- # echo "0xXXXXXXXX" > trace_debug_layer
- # echo "0xYYYYYYYY" > trace_debug_level
- # echo "\PPPP.AAAA.TTTT.HHHH" > trace_method_name
- # echo "method" > /sys/module/acpi/parameters/trace_state
+ control method is being evaluated::
+
+ # cd /sys/module/acpi/parameters
+ # echo "0xXXXXXXXX" > trace_debug_layer
+ # echo "0xYYYYYYYY" > trace_debug_level
+ # echo "\PPPP.AAAA.TTTT.HHHH" > trace_method_name
+ # echo "method" > /sys/module/acpi/parameters/trace_state
+
c. Filter out the debug layer/level matched logs when the specified
- control method is being evaluated for the first time:
- # cd /sys/module/acpi/parameters
- # echo "0xXXXXXXXX" > trace_debug_layer
- # echo "0xYYYYYYYY" > trace_debug_level
- # echo "\PPPP.AAAA.TTTT.HHHH" > trace_method_name
- # echo "method-once" > /sys/module/acpi/parameters/trace_state
- Where:
- 0xXXXXXXXX/0xYYYYYYYY: Refer to Documentation/acpi/debug.txt for
+ control method is being evaluated for the first time::
+
+ # cd /sys/module/acpi/parameters
+ # echo "0xXXXXXXXX" > trace_debug_layer
+ # echo "0xYYYYYYYY" > trace_debug_level
+ # echo "\PPPP.AAAA.TTTT.HHHH" > trace_method_name
+ # echo "method-once" > /sys/module/acpi/parameters/trace_state
+
+ Where::
+
+ 0xXXXXXXXX/0xYYYYYYYY: Refer to Documentation/acpi/debug.txt for
possible debug layer/level masking values.
- \PPPP.AAAA.TTTT.HHHH: Full path of a control method that can be found
+ \PPPP.AAAA.TTTT.HHHH: Full path of a control method that can be found
in the ACPI namespace. It needn't be an entry
of a control method evaluation.
@@ -63,7 +76,8 @@ tracing facility.
There are special log entries added by the method tracing facility at
the "trace points" the AML interpreter starts/stops to execute a control
method, or an AML opcode. Note that the format of the log entries are
- subject to change:
+ subject to change::
+
[ 0.186427] exdebug-0398 ex_trace_point : Method Begin [0xf58394d8:\_SB.PCI0.LPCB.ECOK] execution.
[ 0.186630] exdebug-0398 ex_trace_point : Opcode Begin [0xf5905c88:If] execution.
[ 0.186820] exdebug-0398 ex_trace_point : Opcode Begin [0xf5905cc0:LEqual] execution.
@@ -87,43 +101,54 @@ tracing facility.
The following command examples illustrate the usage of the "AML tracer"
functionality:
+
a. Filter out the method start/stop "AML tracer" logs when control
- methods are being evaluated:
- # cd /sys/module/acpi/parameters
- # echo "0x80" > trace_debug_layer
- # echo "0x10" > trace_debug_level
- # echo "enable" > trace_state
+ methods are being evaluated::
+
+ # cd /sys/module/acpi/parameters
+ # echo "0x80" > trace_debug_layer
+ # echo "0x10" > trace_debug_level
+ # echo "enable" > trace_state
+
b. Filter out the method start/stop "AML tracer" when the specified
- control method is being evaluated:
- # cd /sys/module/acpi/parameters
- # echo "0x80" > trace_debug_layer
- # echo "0x10" > trace_debug_level
- # echo "\PPPP.AAAA.TTTT.HHHH" > trace_method_name
- # echo "method" > trace_state
+ control method is being evaluated::
+
+ # cd /sys/module/acpi/parameters
+ # echo "0x80" > trace_debug_layer
+ # echo "0x10" > trace_debug_level
+ # echo "\PPPP.AAAA.TTTT.HHHH" > trace_method_name
+ # echo "method" > trace_state
+
c. Filter out the method start/stop "AML tracer" logs when the specified
control method is being evaluated for the first time:
- # cd /sys/module/acpi/parameters
- # echo "0x80" > trace_debug_layer
- # echo "0x10" > trace_debug_level
- # echo "\PPPP.AAAA.TTTT.HHHH" > trace_method_name
- # echo "method-once" > trace_state
+
+ # cd /sys/module/acpi/parameters
+ # echo "0x80" > trace_debug_layer
+ # echo "0x10" > trace_debug_level
+ # echo "\PPPP.AAAA.TTTT.HHHH" > trace_method_name
+ # echo "method-once" > trace_state
+
d. Filter out the method/opcode start/stop "AML tracer" when the
- specified control method is being evaluated:
- # cd /sys/module/acpi/parameters
- # echo "0x80" > trace_debug_layer
- # echo "0x10" > trace_debug_level
- # echo "\PPPP.AAAA.TTTT.HHHH" > trace_method_name
- # echo "opcode" > trace_state
+ specified control method is being evaluated::
+
+ # cd /sys/module/acpi/parameters
+ # echo "0x80" > trace_debug_layer
+ # echo "0x10" > trace_debug_level
+ # echo "\PPPP.AAAA.TTTT.HHHH" > trace_method_name
+ # echo "opcode" > trace_state
+
e. Filter out the method/opcode start/stop "AML tracer" when the
- specified control method is being evaluated for the first time:
- # cd /sys/module/acpi/parameters
- # echo "0x80" > trace_debug_layer
- # echo "0x10" > trace_debug_level
- # echo "\PPPP.AAAA.TTTT.HHHH" > trace_method_name
- # echo "opcode-opcode" > trace_state
+ specified control method is being evaluated for the first time::
+
+ # cd /sys/module/acpi/parameters
+ # echo "0x80" > trace_debug_layer
+ # echo "0x10" > trace_debug_level
+ # echo "\PPPP.AAAA.TTTT.HHHH" > trace_method_name
+ # echo "opcode-opcode" > trace_state
Note that all above method tracing facility related module parameters can
- be used as the boot parameters, for example:
+ be used as the boot parameters, for example::
+
acpi.trace_debug_layer=0x80 acpi.trace_debug_level=0x10 \
acpi.trace_method_name=\_SB.LID0._LID acpi.trace_state=opcode-once
@@ -150,9 +175,12 @@ tracing facility.
trace_state
The status of the tracing feature.
Users can enable/disable this debug tracing feature by executing
- the following command:
+ the following command::
+
# echo string > /sys/module/acpi/parameters/trace_state
+
Where "string" should be one of the following:
+
"disable"
Disable the method tracing feature.
"enable"
@@ -180,8 +208,10 @@ tracing facility.
ACPICA debugging messages matching
"trace_debug_layer/trace_debug_level" during method/opcode
execution of "trace_method_name" will be logged only once.
+
Note that, the difference between the "enable" and other feature
enabling options are:
+
1. When "enable" is specified, since
"trace_debug_layer/trace_debug_level" shall apply to all control
method evaluations, after configuring "trace_state" to "enable",
diff --git a/Documentation/acpi/namespace.txt b/Documentation/acpi/namespace.txt
index 1860cb3865c6..9a6dca683fbc 100644
--- a/Documentation/acpi/namespace.txt
+++ b/Documentation/acpi/namespace.txt
@@ -1,10 +1,14 @@
+===================================================
ACPI Device Tree - Representation of 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
@@ -15,12 +19,14 @@ 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
@@ -40,7 +46,7 @@ Wysocki <rafael.j.wysocki@intel.com>.
structure of the underlying hardware platform.
The relationships between ACPI System Definition Tables described above
- are illustrated in the following diagram.
+ are illustrated in the following diagram::
+---------+ +-------+ +--------+ +------------------------+
| RSDP | +->| XSDT | +->| FADT | | +-------------------+ |
@@ -68,18 +74,21 @@ Wysocki <rafael.j.wysocki@intel.com>.
Figure 1. ACPI Definition Blocks
- NOTE: RSDP can also contain a pointer to the RSDT (Root System
+ 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,100 +100,101 @@ 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
- +------+
- |
- | +------+
- +-| _PR | Scope(_PR): the processor namespace
- | +------+
- | |
- | | +------+
- | +-| CPU0 | Processor(CPU0): the first processor
- | +------+
- |
- | +------+
- +-| _SB | Scope(_SB): the system bus namespace
- | +------+
- | |
- | | +------+
- | +-| LID0 | Device(LID0); the lid device
- | | +------+
- | | |
- | | | +------+
- | | +-| _HID | Name(_HID, "PNP0C0D"): the hardware ID
- | | | +------+
- | | |
- | | | +------+
- | | +-| _STA | Method(_STA): the status control method
- | | +------+
- | |
- | | +------+
- | +-| PCI0 | Device(PCI0); the PCI root bridge
- | +------+
- | |
- | | +------+
- | +-| _HID | Name(_HID, "PNP0A08"): the hardware ID
- | | +------+
- | |
- | | +------+
- | +-| _CID | Name(_CID, "PNP0A03"): the compatible ID
- | | +------+
- | |
- | | +------+
- | +-| RP03 | Scope(RP03): the PCI0 power scope
- | | +------+
- | | |
- | | | +------+
- | | +-| PXP3 | PowerResource(PXP3): the PCI0 power resource
- | | +------+
- | |
- | | +------+
- | +-| GFX0 | Device(GFX0): the graphics adapter
- | +------+
- | |
- | | +------+
- | +-| _ADR | Name(_ADR, 0x00020000): the PCI bus address
- | | +------+
- | |
- | | +------+
- | +-| DD01 | Device(DD01): the LCD output device
- | +------+
- | |
- | | +------+
- | +-| _BCL | Method(_BCL): the backlight control method
- | +------+
- |
- | +------+
- +-| _TZ | Scope(_TZ): the thermal zone namespace
- | +------+
- | |
- | | +------+
- | +-| FN00 | PowerResource(FN00): the FAN0 power resource
- | | +------+
- | |
- | | +------+
- | +-| FAN0 | Device(FAN0): the FAN0 cooling device
- | | +------+
- | | |
- | | | +------+
- | | +-| _HID | Name(_HID, "PNP0A0B"): the hardware ID
- | | +------+
- | |
- | | +------+
- | +-| TZ00 | ThermalZone(TZ00); the FAN thermal zone
- | +------+
- |
- | +------+
- +-| _GPE | Scope(_GPE): the GPE namespace
- +------+
+ +------+
+ | \ | Root
+ +------+
+ |
+ | +------+
+ +-| _PR | Scope(_PR): the processor namespace
+ | +------+
+ | |
+ | | +------+
+ | +-| CPU0 | Processor(CPU0): the first processor
+ | +------+
+ |
+ | +------+
+ +-| _SB | Scope(_SB): the system bus namespace
+ | +------+
+ | |
+ | | +------+
+ | +-| LID0 | Device(LID0); the lid device
+ | | +------+
+ | | |
+ | | | +------+
+ | | +-| _HID | Name(_HID, "PNP0C0D"): the hardware ID
+ | | | +------+
+ | | |
+ | | | +------+
+ | | +-| _STA | Method(_STA): the status control method
+ | | +------+
+ | |
+ | | +------+
+ | +-| PCI0 | Device(PCI0); the PCI root bridge
+ | +------+
+ | |
+ | | +------+
+ | +-| _HID | Name(_HID, "PNP0A08"): the hardware ID
+ | | +------+
+ | |
+ | | +------+
+ | +-| _CID | Name(_CID, "PNP0A03"): the compatible ID
+ | | +------+
+ | |
+ | | +------+
+ | +-| RP03 | Scope(RP03): the PCI0 power scope
+ | | +------+
+ | | |
+ | | | +------+
+ | | +-| PXP3 | PowerResource(PXP3): the PCI0 power resource
+ | | +------+
+ | |
+ | | +------+
+ | +-| GFX0 | Device(GFX0): the graphics adapter
+ | +------+
+ | |
+ | | +------+
+ | +-| _ADR | Name(_ADR, 0x00020000): the PCI bus address
+ | | +------+
+ | |
+ | | +------+
+ | +-| DD01 | Device(DD01): the LCD output device
+ | +------+
+ | |
+ | | +------+
+ | +-| _BCL | Method(_BCL): the backlight control method
+ | +------+
+ |
+ | +------+
+ +-| _TZ | Scope(_TZ): the thermal zone namespace
+ | +------+
+ | |
+ | | +------+
+ | +-| FN00 | PowerResource(FN00): the FAN0 power resource
+ | | +------+
+ | |
+ | | +------+
+ | +-| FAN0 | Device(FAN0): the FAN0 cooling device
+ | | +------+
+ | | |
+ | | | +------+
+ | | +-| _HID | Name(_HID, "PNP0A0B"): the hardware ID
+ | | +------+
+ | |
+ | | +------+
+ | +-| TZ00 | ThermalZone(TZ00); the FAN thermal zone
+ | +------+
+ |
+ | +------+
+ +-| _GPE | Scope(_GPE): the GPE namespace
+ +------+
Figure 2. Example ACPI Namespace
3. Linux ACPI Device Objects
+============================
The Linux kernel's core ACPI subsystem creates struct acpi_device
objects for ACPI namespace objects representing devices, power resources
@@ -230,6 +240,7 @@ Wysocki <rafael.j.wysocki@intel.com>.
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
@@ -256,6 +267,7 @@ Wysocki <rafael.j.wysocki@intel.com>.
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
@@ -276,6 +288,7 @@ Wysocki <rafael.j.wysocki@intel.com>.
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
@@ -310,79 +323,83 @@ Wysocki <rafael.j.wysocki@intel.com>.
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.
+ fixed PWR_BUTTON/SLP_BUTTON devices is shown below::
- +--------------+---+-----------------+
- | LNXSYSTEM:00 | \ | acpi:LNXSYSTEM: |
- +--------------+---+-----------------+
- |
- | +-------------+-----+----------------+
- +-| LNXPWRBN:00 | N/A | acpi:LNXPWRBN: |
- | +-------------+-----+----------------+
- |
- | +-------------+-----+----------------+
- +-| LNXSLPBN:00 | N/A | acpi:LNXSLPBN: |
- | +-------------+-----+----------------+
- |
- | +-----------+------------+--------------+
- +-| LNXCPU:00 | \_PR_.CPU0 | acpi:LNXCPU: |
- | +-----------+------------+--------------+
- |
- | +-------------+-------+----------------+
- +-| LNXSYBUS:00 | \_SB_ | acpi:LNXSYBUS: |
- | +-------------+-------+----------------+
- | |
- | | +- - - - - - - +- - - - - - +- - - - - - - -+
- | +-| PNP0C0D:00 | \_SB_.LID0 | acpi:PNP0C0D: |
- | | +- - - - - - - +- - - - - - +- - - - - - - -+
- | |
- | | +------------+------------+-----------------------+
- | +-| PNP0A08:00 | \_SB_.PCI0 | acpi:PNP0A08:PNP0A03: |
- | +------------+------------+-----------------------+
- | |
- | | +-----------+-----------------+-----+
- | +-| device:00 | \_SB_.PCI0.RP03 | N/A |
- | | +-----------+-----------------+-----+
- | | |
- | | | +-------------+----------------------+----------------+
- | | +-| LNXPOWER:00 | \_SB_.PCI0.RP03.PXP3 | acpi:LNXPOWER: |
- | | +-------------+----------------------+----------------+
- | |
- | | +-------------+-----------------+----------------+
- | +-| LNXVIDEO:00 | \_SB_.PCI0.GFX0 | acpi:LNXVIDEO: |
- | +-------------+-----------------+----------------+
- | |
- | | +-----------+-----------------+-----+
- | +-| device:01 | \_SB_.PCI0.DD01 | N/A |
- | +-----------+-----------------+-----+
- |
- | +-------------+-------+----------------+
- +-| LNXSYBUS:01 | \_TZ_ | acpi:LNXSYBUS: |
- +-------------+-------+----------------+
- |
- | +-------------+------------+----------------+
- +-| LNXPOWER:0a | \_TZ_.FN00 | acpi:LNXPOWER: |
- | +-------------+------------+----------------+
- |
- | +------------+------------+---------------+
- +-| PNP0C0B:00 | \_TZ_.FAN0 | acpi:PNP0C0B: |
- | +------------+------------+---------------+
- |
- | +-------------+------------+----------------+
- +-| LNXTHERM:00 | \_TZ_.TZ00 | acpi:LNXTHERM: |
- +-------------+------------+----------------+
+ +--------------+---+-----------------+
+ | LNXSYSTEM:00 | \ | acpi:LNXSYSTEM: |
+ +--------------+---+-----------------+
+ |
+ | +-------------+-----+----------------+
+ +-| LNXPWRBN:00 | N/A | acpi:LNXPWRBN: |
+ | +-------------+-----+----------------+
+ |
+ | +-------------+-----+----------------+
+ +-| LNXSLPBN:00 | N/A | acpi:LNXSLPBN: |
+ | +-------------+-----+----------------+
+ |
+ | +-----------+------------+--------------+
+ +-| LNXCPU:00 | \_PR_.CPU0 | acpi:LNXCPU: |
+ | +-----------+------------+--------------+
+ |
+ | +-------------+-------+----------------+
+ +-| LNXSYBUS:00 | \_SB_ | acpi:LNXSYBUS: |
+ | +-------------+-------+----------------+
+ | |
+ | | +- - - - - - - +- - - - - - +- - - - - - - -+
+ | +-| PNP0C0D:00 | \_SB_.LID0 | acpi:PNP0C0D: |
+ | | +- - - - - - - +- - - - - - +- - - - - - - -+
+ | |
+ | | +------------+------------+-----------------------+
+ | +-| PNP0A08:00 | \_SB_.PCI0 | acpi:PNP0A08:PNP0A03: |
+ | +------------+------------+-----------------------+
+ | |
+ | | +-----------+-----------------+-----+
+ | +-| device:00 | \_SB_.PCI0.RP03 | N/A |
+ | | +-----------+-----------------+-----+
+ | | |
+ | | | +-------------+----------------------+----------------+
+ | | +-| LNXPOWER:00 | \_SB_.PCI0.RP03.PXP3 | acpi:LNXPOWER: |
+ | | +-------------+----------------------+----------------+
+ | |
+ | | +-------------+-----------------+----------------+
+ | +-| LNXVIDEO:00 | \_SB_.PCI0.GFX0 | acpi:LNXVIDEO: |
+ | +-------------+-----------------+----------------+
+ | |
+ | | +-----------+-----------------+-----+
+ | +-| device:01 | \_SB_.PCI0.DD01 | N/A |
+ | +-----------+-----------------+-----+
+ |
+ | +-------------+-------+----------------+
+ +-| LNXSYBUS:01 | \_TZ_ | acpi:LNXSYBUS: |
+ +-------------+-------+----------------+
+ |
+ | +-------------+------------+----------------+
+ +-| LNXPOWER:0a | \_TZ_.FN00 | acpi:LNXPOWER: |
+ | +-------------+------------+----------------+
+ |
+ | +------------+------------+---------------+
+ +-| PNP0C0B:00 | \_TZ_.FAN0 | acpi:PNP0C0B: |
+ | +------------+------------+---------------+
+ |
+ | +-------------+------------+----------------+
+ +-| LNXTHERM:00 | \_TZ_.TZ00 | acpi:LNXTHERM: |
+ +-------------+------------+----------------+
Figure 3. Example Linux ACPI Device Tree
- NOTE: Each node is represented as "object/path/modalias", where:
+ 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:
+ N/A indicates the device object does not have the 'path' or the
+ 'modalias' attribute.
diff --git a/Documentation/acpi/osi.txt b/Documentation/acpi/osi.txt
index 50cde0ceb9b0..401518ca15cc 100644
--- a/Documentation/acpi/osi.txt
+++ b/Documentation/acpi/osi.txt
@@ -1,5 +1,6 @@
+==========================
ACPI _OSI and _REV methods
---------------------------
+==========================
An ACPI BIOS can use the "Operating System Interfaces" method (_OSI)
to find out what the operating system supports. Eg. If BIOS
diff --git a/Documentation/acpi/scan_handlers.txt b/Documentation/acpi/scan_handlers.txt
index 3246ccf15992..fa8265f272d5 100644
--- a/Documentation/acpi/scan_handlers.txt
+++ b/Documentation/acpi/scan_handlers.txt
@@ -1,6 +1,9 @@
+==================
ACPI Scan Handlers
+==================
Copyright (C) 2012, Intel Corporation
+
Author: Rafael J. Wysocki <rafael.j.wysocki@intel.com>
During system initialization and ACPI-based device hot-add, the ACPI namespace
@@ -30,14 +33,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 {
+ 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
diff --git a/Documentation/acpi/ssdt-overlays.txt b/Documentation/acpi/ssdt-overlays.txt
index 5ae13f161ea2..036ba3bb8613 100644
--- a/Documentation/acpi/ssdt-overlays.txt
+++ b/Documentation/acpi/ssdt-overlays.txt
@@ -1,3 +1,6 @@
+=============
+SSDT Overlays
+=============
In order to support ACPI open-ended hardware configurations (e.g. development
boards) we need a way to augment the ACPI configuration provided by the firmware
@@ -15,10 +18,10 @@ user defined SSDT tables that contain the board specific information.
For example, to enumerate a Bosch BMA222E accelerometer on the I2C bus of the
Minnowboard MAX development board exposed via the LSE connector [1], the
-following ASL code can be used:
+following ASL code can be used::
-DefinitionBlock ("minnowmax.aml", "SSDT", 1, "Vendor", "Accel", 0x00000003)
-{
+ DefinitionBlock ("minnowmax.aml", "SSDT", 1, "Vendor", "Accel", 0x00000003)
+ {
External (\_SB.I2C6, DeviceObj)
Scope (\_SB.I2C6)
@@ -45,25 +48,26 @@ DefinitionBlock ("minnowmax.aml", "SSDT", 1, "Vendor", "Accel", 0x00000003)
}
}
}
-}
+ }
-which can then be compiled to AML binary format:
+which can then be compiled to AML binary format::
-$ iasl minnowmax.asl
+ $ iasl minnowmax.asl
-Intel ACPI Component Architecture
-ASL Optimizing Compiler version 20140214-64 [Mar 29 2014]
-Copyright (c) 2000 - 2014 Intel Corporation
+ Intel ACPI Component Architecture
+ ASL Optimizing Compiler version 20140214-64 [Mar 29 2014]
+ Copyright (c) 2000 - 2014 Intel Corporation
-ASL Input: minnomax.asl - 30 lines, 614 bytes, 7 keywords
-AML Output: minnowmax.aml - 165 bytes, 6 named objects, 1 executable opcodes
+ ASL Input: minnomax.asl - 30 lines, 614 bytes, 7 keywords
+ AML Output: minnowmax.aml - 165 bytes, 6 named objects, 1 executable opcodes
[1] http://wiki.minnowboard.org/MinnowBoard_MAX#Low_Speed_Expansion_Connector_.28Top.29
The resulting AML code can then be loaded by the kernel using one of the methods
below.
-== Loading ACPI SSDTs from initrd ==
+Loading ACPI SSDTs from initrd
+==============================
This option allows loading of user defined SSDTs from initrd and it is useful
when the system does not support EFI or when there is not enough EFI storage.
@@ -74,23 +78,24 @@ aml code must be placed in the first, uncompressed, initrd under the
in loading multiple tables. Only SSDT and OEM tables are allowed. See
initrd_table_override.txt for more details.
-Here is an example:
+Here is an example::
-# Add the raw ACPI tables to an uncompressed cpio archive.
-# They must be put into a /kernel/firmware/acpi directory inside the
-# cpio archive.
-# The uncompressed cpio archive must be the first.
-# Other, typically compressed cpio archives, must be
-# concatenated on top of the uncompressed one.
-mkdir -p kernel/firmware/acpi
-cp ssdt.aml kernel/firmware/acpi
+ # Add the raw ACPI tables to an uncompressed cpio archive.
+ # They must be put into a /kernel/firmware/acpi directory inside the
+ # cpio archive.
+ # The uncompressed cpio archive must be the first.
+ # Other, typically compressed cpio archives, must be
+ # concatenated on top of the uncompressed one.
+ mkdir -p kernel/firmware/acpi
+ cp ssdt.aml kernel/firmware/acpi
-# Create the uncompressed cpio archive and concatenate the original initrd
-# on top:
-find kernel | cpio -H newc --create > /boot/instrumented_initrd
-cat /boot/initrd >>/boot/instrumented_initrd
+ # Create the uncompressed cpio archive and concatenate the original initrd
+ # on top:
+ find kernel | cpio -H newc --create > /boot/instrumented_initrd
+ cat /boot/initrd >>/boot/instrumented_initrd
-== Loading ACPI SSDTs from EFI variables ==
+Loading ACPI SSDTs from EFI variables
+=====================================
This is the preferred method, when EFI is supported on the platform, because it
allows a persistent, OS independent way of storing the user defined SSDTs. There
@@ -116,48 +121,49 @@ include/linux/efi.h). Writing to the file must also be done with one write
operation.
For example, you can use the following bash script to create/update an EFI
-variable with the content from a given file:
+variable with the content from a given file::
-#!/bin/sh -e
+ #!/bin/sh -e
-while ! [ -z "$1" ]; do
- case "$1" in
- "-f") filename="$2"; shift;;
- "-g") guid="$2"; shift;;
- *) name="$1";;
- esac
- shift
-done
+ while ! [ -z "$1" ]; do
+ case "$1" in
+ "-f") filename="$2"; shift;;
+ "-g") guid="$2"; shift;;
+ *) name="$1";;
+ esac
+ shift
+ done
-usage()
-{
- echo "Syntax: ${0##*/} -f filename [ -g guid ] name"
- exit 1
-}
+ usage()
+ {
+ echo "Syntax: ${0##*/} -f filename [ -g guid ] name"
+ exit 1
+ }
-[ -n "$name" -a -f "$filename" ] || usage
+ [ -n "$name" -a -f "$filename" ] || usage
-EFIVARFS="/sys/firmware/efi/efivars"
+ EFIVARFS="/sys/firmware/efi/efivars"
-[ -d "$EFIVARFS" ] || exit 2
+ [ -d "$EFIVARFS" ] || exit 2
-if stat -tf $EFIVARFS | grep -q -v de5e81e4; then
- mount -t efivarfs none $EFIVARFS
-fi
+ if stat -tf $EFIVARFS | grep -q -v de5e81e4; then
+ mount -t efivarfs none $EFIVARFS
+ fi
-# try to pick up an existing GUID
-[ -n "$guid" ] || guid=$(find "$EFIVARFS" -name "$name-*" | head -n1 | cut -f2- -d-)
+ # try to pick up an existing GUID
+ [ -n "$guid" ] || guid=$(find "$EFIVARFS" -name "$name-*" | head -n1 | cut -f2- -d-)
-# use a randomly generated GUID
-[ -n "$guid" ] || guid="$(cat /proc/sys/kernel/random/uuid)"
+ # use a randomly generated GUID
+ [ -n "$guid" ] || guid="$(cat /proc/sys/kernel/random/uuid)"
-# efivarfs expects all of the data in one write
-tmp=$(mktemp)
-/bin/echo -ne "\007\000\000\000" | cat - $filename > $tmp
-dd if=$tmp of="$EFIVARFS/$name-$guid" bs=$(stat -c %s $tmp)
-rm $tmp
+ # efivarfs expects all of the data in one write
+ tmp=$(mktemp)
+ /bin/echo -ne "\007\000\000\000" | cat - $filename > $tmp
+ dd if=$tmp of="$EFIVARFS/$name-$guid" bs=$(stat -c %s $tmp)
+ rm $tmp
-== Loading ACPI SSDTs from configfs ==
+Loading ACPI SSDTs from configfs
+================================
This option allows loading of user defined SSDTs from userspace via the configfs
interface. The CONFIG_ACPI_CONFIGFS option must be select and configfs must be
@@ -165,8 +171,8 @@ mounted. In the following examples, we assume that configfs has been mounted in
/config.
New tables can be loading by creating new directories in /config/acpi/table/ and
-writing the SSDT aml code in the aml attribute:
+writing the SSDT aml code in the aml attribute::
-cd /config/acpi/table
-mkdir my_ssdt
-cat ~/ssdt.aml > my_ssdt/aml
+ cd /config/acpi/table
+ mkdir my_ssdt
+ cat ~/ssdt.aml > my_ssdt/aml
diff --git a/Documentation/acpi/video_extension.txt b/Documentation/acpi/video_extension.txt
index 79bf6a4921be..7a5882a567b9 100644
--- a/Documentation/acpi/video_extension.txt
+++ b/Documentation/acpi/video_extension.txt
@@ -1,5 +1,6 @@
+=====================
ACPI video extensions
-~~~~~~~~~~~~~~~~~~~~~
+=====================
This driver implement the ACPI Extensions For Display Adapters for
integrated graphics devices on motherboard, as specified in ACPI 2.0
@@ -32,10 +33,10 @@ type: firmware
Note that ACPI video backlight driver will always use index for
brightness, actual_brightness and max_brightness. So if we have
-the following _BCL package:
+the following _BCL package::
-Method (_BCL, 0, NotSerialized)
-{
+ Method (_BCL, 0, NotSerialized)
+ {
Return (Package (0x0C)
{
0x64,
@@ -51,7 +52,7 @@ Method (_BCL, 0, NotSerialized)
0x5A,
0x64
})
-}
+ }
The first two levels are for when laptop are on AC or on battery and are
not used by Linux currently. The remaining 10 levels are supported levels
@@ -65,10 +66,11 @@ inclusive.
2 Notify user space about hotkey event
There are generally two cases for hotkey event reporting:
+
i) For some laptops, when user presses the hotkey, a scancode will be
generated and sent to user space through the input device created by
the keyboard driver as a key type input event, with proper remap, the
- following key code will appear to user space:
+ following key code will appear to user space::
EV_KEY, KEY_BRIGHTNESSUP
EV_KEY, KEY_BRIGHTNESSDOWN
@@ -82,7 +84,7 @@ ii) For some laptops, the press of the hotkey will not generate the
about the event. The event value is defined in the ACPI spec. ACPI
video driver will generate an key type input event according to the
notify value it received and send the event to user space through the
- input device it created:
+ input device it created::
event keycode
0x86 KEY_BRIGHTNESSUP
--
2.20.1
^ permalink raw reply related [flat|nested] 81+ messages in thread* Re: [PATCH 02/57] docs: acpi: convert text files to ReST
2019-04-16 2:55 ` [PATCH 02/57] docs: acpi: convert text files to ReST Mauro Carvalho Chehab
@ 2019-04-16 8:17 ` Rafael J. Wysocki
2019-04-16 9:54 ` Mauro Carvalho Chehab
2019-04-16 14:55 ` Changbin Du
0 siblings, 2 replies; 81+ messages in thread
From: Rafael J. Wysocki @ 2019-04-16 8:17 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: Linux Doc Mailing List, Mauro Carvalho Chehab,
Linux Kernel Mailing List, Jonathan Corbet, Rafael J. Wysocki,
Len Brown, ACPI Devel Maling List, Changbin Du
On Tue, Apr 16, 2019 at 5:02 AM Mauro Carvalho Chehab
<mchehab+samsung@kernel.org> wrote:
>
> Most of the files are already in good shape, making easier to
> convert them to ReST by adding proper title markups and
> addressing some identation and markups to properly format the
> document.
There is concurrent work on this under way, please see
https://marc.info/?t=155381845300002&r=2&w=2
I'd prefer that one to continue, honestly.
Thanks,
Rafael
^ permalink raw reply [flat|nested] 81+ messages in thread
* Re: [PATCH 02/57] docs: acpi: convert text files to ReST
2019-04-16 8:17 ` Rafael J. Wysocki
@ 2019-04-16 9:54 ` Mauro Carvalho Chehab
2019-04-16 10:17 ` Rafael J. Wysocki
2019-04-16 14:55 ` Changbin Du
1 sibling, 1 reply; 81+ messages in thread
From: Mauro Carvalho Chehab @ 2019-04-16 9:54 UTC (permalink / raw)
To: Rafael J. Wysocki
Cc: Linux Doc Mailing List, Mauro Carvalho Chehab,
Linux Kernel Mailing List, Jonathan Corbet, Rafael J. Wysocki,
Len Brown, ACPI Devel Maling List, Changbin Du
Em Tue, 16 Apr 2019 10:17:11 +0200
"Rafael J. Wysocki" <rafael@kernel.org> escreveu:
> On Tue, Apr 16, 2019 at 5:02 AM Mauro Carvalho Chehab
> <mchehab+samsung@kernel.org> wrote:
> >
> > Most of the files are already in good shape, making easier to
> > convert them to ReST by adding proper title markups and
> > addressing some identation and markups to properly format the
> > document.
>
> There is concurrent work on this under way, please see
> https://marc.info/?t=155381845300002&r=2&w=2
>
> I'd prefer that one to continue, honestly.
Agreed. I didn't notice the patchset.
Btw, please notice patch 11/57:
Subject: [PATCH 11/57] docs: extcon: move it to acpi dir and convert it to ReST
IMO, it makes sense to move the extcon driver to ACPI, as it sounds
to be just another ACPI driver.
Thanks,
Mauro
^ permalink raw reply [flat|nested] 81+ messages in thread
* Re: [PATCH 02/57] docs: acpi: convert text files to ReST
2019-04-16 9:54 ` Mauro Carvalho Chehab
@ 2019-04-16 10:17 ` Rafael J. Wysocki
0 siblings, 0 replies; 81+ messages in thread
From: Rafael J. Wysocki @ 2019-04-16 10:17 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: Rafael J. Wysocki, Linux Doc Mailing List, Mauro Carvalho Chehab,
Linux Kernel Mailing List, Jonathan Corbet, Rafael J. Wysocki,
Len Brown, ACPI Devel Maling List, Changbin Du
On Tue, Apr 16, 2019 at 11:54 AM Mauro Carvalho Chehab
<mchehab+samsung@kernel.org> wrote:
>
> Em Tue, 16 Apr 2019 10:17:11 +0200
> "Rafael J. Wysocki" <rafael@kernel.org> escreveu:
>
> > On Tue, Apr 16, 2019 at 5:02 AM Mauro Carvalho Chehab
> > <mchehab+samsung@kernel.org> wrote:
> > >
> > > Most of the files are already in good shape, making easier to
> > > convert them to ReST by adding proper title markups and
> > > addressing some identation and markups to properly format the
> > > document.
> >
> > There is concurrent work on this under way, please see
> > https://marc.info/?t=155381845300002&r=2&w=2
> >
> > I'd prefer that one to continue, honestly.
>
> Agreed. I didn't notice the patchset.
>
> Btw, please notice patch 11/57:
>
> Subject: [PATCH 11/57] docs: extcon: move it to acpi dir and convert it to ReST
>
> IMO, it makes sense to move the extcon driver to ACPI, as it sounds
> to be just another ACPI driver.
But that can be done later, on top of the Changbin Du's changes.
Thanks,
Rafael
^ permalink raw reply [flat|nested] 81+ messages in thread
* Re: [PATCH 02/57] docs: acpi: convert text files to ReST
2019-04-16 8:17 ` Rafael J. Wysocki
2019-04-16 9:54 ` Mauro Carvalho Chehab
@ 2019-04-16 14:55 ` Changbin Du
2019-04-22 13:31 ` Mauro Carvalho Chehab
1 sibling, 1 reply; 81+ messages in thread
From: Changbin Du @ 2019-04-16 14:55 UTC (permalink / raw)
To: Rafael J. Wysocki
Cc: Mauro Carvalho Chehab, Linux Doc Mailing List,
Mauro Carvalho Chehab, Linux Kernel Mailing List, Jonathan Corbet,
Rafael J. Wysocki, Len Brown, ACPI Devel Maling List, Changbin Du
On Tue, Apr 16, 2019 at 10:17:11AM +0200, Rafael J. Wysocki wrote:
> On Tue, Apr 16, 2019 at 5:02 AM Mauro Carvalho Chehab
> <mchehab+samsung@kernel.org> wrote:
> >
> > Most of the files are already in good shape, making easier to
> > convert them to ReST by adding proper title markups and
> > addressing some identation and markups to properly format the
> > document.
>
> There is concurrent work on this under way, please see
> https://marc.info/?t=155381845300002&r=2&w=2
>
I will update the serias asap. I am just a little busy these days. My
conversion includes pci, acpi and x86, others are not touched.
> I'd prefer that one to continue, honestly.
>
> Thanks,
> Rafael
--
Cheers,
Changbin Du
^ permalink raw reply [flat|nested] 81+ messages in thread
* Re: [PATCH 02/57] docs: acpi: convert text files to ReST
2019-04-16 14:55 ` Changbin Du
@ 2019-04-22 13:31 ` Mauro Carvalho Chehab
0 siblings, 0 replies; 81+ messages in thread
From: Mauro Carvalho Chehab @ 2019-04-22 13:31 UTC (permalink / raw)
To: Changbin Du
Cc: Rafael J. Wysocki, Linux Doc Mailing List, Mauro Carvalho Chehab,
Linux Kernel Mailing List, Jonathan Corbet, Rafael J. Wysocki,
Len Brown, ACPI Devel Maling List
Em Tue, 16 Apr 2019 14:55:19 +0000
Changbin Du <changbin.du@gmail.com> escreveu:
> On Tue, Apr 16, 2019 at 10:17:11AM +0200, Rafael J. Wysocki wrote:
> > On Tue, Apr 16, 2019 at 5:02 AM Mauro Carvalho Chehab
> > <mchehab+samsung@kernel.org> wrote:
> > >
> > > Most of the files are already in good shape, making easier to
> > > convert them to ReST by adding proper title markups and
> > > addressing some identation and markups to properly format the
> > > document.
> >
> > There is concurrent work on this under way, please see
> > https://marc.info/?t=155381845300002&r=2&w=2
> >
> I will update the serias asap. I am just a little busy these days. My
> conversion includes pci, acpi and x86, others are not touched.
Ok, I sent a new patch series without pci, acpi and x86.
While these aren't merged upstream, I'm keeping my old patches
on my tree:
https://git.linuxtv.org/mchehab/experimental.git/commit/?h=convert_rst_v2&id=805b16dd336dd3c27733f02ec8164b2a182972a3
https://git.linuxtv.org/mchehab/experimental.git/commit/?h=convert_rst_v2&id=c950031ccb87ea14ff4c56f2433072d580db3572
https://git.linuxtv.org/mchehab/experimental.git/commit/?h=convert_rst_v2&id=4f8afce866dcd8067206b3ee493ed0b682694f49
If you find anything there that would be interesting for your
series, feel free to pick from them. Everything is based on
linux-next.
Thanks,
Mauro
^ permalink raw reply [flat|nested] 81+ messages in thread
* [PATCH 03/57] docs: aoe: convert text files to ReST
2019-04-16 2:55 [PATCH 00/57] Convert files to ReST Mauro Carvalho Chehab
2019-04-16 2:55 ` [PATCH 01/57] docs: trace: fix some Sphinx warnings Mauro Carvalho Chehab
2019-04-16 2:55 ` [PATCH 02/57] docs: acpi: convert text files to ReST Mauro Carvalho Chehab
@ 2019-04-16 2:55 ` Mauro Carvalho Chehab
2019-04-16 2:55 ` [PATCH 04/57] docs: arm64: convert documentation to ReST format Mauro Carvalho Chehab
` (49 subsequent siblings)
52 siblings, 0 replies; 81+ messages in thread
From: Mauro Carvalho Chehab @ 2019-04-16 2:55 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet
There are only two files within Documentation/aoe dir that are
documentation. The remaining ones are examples and shell
scripts.
Convert the two AoE files to ReST format.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
Documentation/aoe/aoe.txt | 63 +++++++++++++++++++++-----------------
Documentation/aoe/todo.txt | 3 ++
Documentation/aoe/udev.txt | 2 +-
3 files changed, 39 insertions(+), 29 deletions(-)
diff --git a/Documentation/aoe/aoe.txt b/Documentation/aoe/aoe.txt
index c71487d399d1..58747ecec71d 100644
--- a/Documentation/aoe/aoe.txt
+++ b/Documentation/aoe/aoe.txt
@@ -1,3 +1,6 @@
+Introduction
+============
+
ATA over Ethernet is a network protocol that provides simple access to
block storage on the LAN.
@@ -22,7 +25,8 @@ document the use of the driver and are not necessary if you install
the aoetools.
-CREATING DEVICE NODES
+Creating Device Nodes
+=====================
Users of udev should find the block device nodes created
automatically, but to create all the necessary device nodes, use the
@@ -38,7 +42,8 @@ CREATING DEVICE NODES
confusing when an AoE device is not present the first time the a
command is run but appears a second later.
-USING DEVICE NODES
+Using Device Nodes
+==================
"cat /dev/etherd/err" blocks, waiting for error diagnostic output,
like any retransmitted packets.
@@ -55,7 +60,7 @@ USING DEVICE NODES
by sysfs counterparts. Using the commands in aoetools insulates
users from these implementation details.
- The block devices are named like this:
+ The block devices are named like this::
e{shelf}.{slot}
e{shelf}.{slot}p{part}
@@ -64,7 +69,8 @@ USING DEVICE NODES
first shelf (shelf address zero). That's the whole disk. The first
partition on that disk would be "e0.2p1".
-USING SYSFS
+Using sysfs
+===========
Each aoe block device in /sys/block has the extra attributes of
state, mac, and netif. The state attribute is "up" when the device
@@ -78,29 +84,29 @@ USING SYSFS
There is a script in this directory that formats this information in
a convenient way. Users with aoetools should use the aoe-stat
- command.
+ command::
- root@makki root# sh Documentation/aoe/status.sh
- e10.0 eth3 up
- e10.1 eth3 up
- e10.2 eth3 up
- e10.3 eth3 up
- e10.4 eth3 up
- e10.5 eth3 up
- e10.6 eth3 up
- e10.7 eth3 up
- e10.8 eth3 up
- e10.9 eth3 up
- e4.0 eth1 up
- e4.1 eth1 up
- e4.2 eth1 up
- e4.3 eth1 up
- e4.4 eth1 up
- e4.5 eth1 up
- e4.6 eth1 up
- e4.7 eth1 up
- e4.8 eth1 up
- e4.9 eth1 up
+ root@makki root# sh Documentation/aoe/status.sh
+ e10.0 eth3 up
+ e10.1 eth3 up
+ e10.2 eth3 up
+ e10.3 eth3 up
+ e10.4 eth3 up
+ e10.5 eth3 up
+ e10.6 eth3 up
+ e10.7 eth3 up
+ e10.8 eth3 up
+ e10.9 eth3 up
+ e4.0 eth1 up
+ e4.1 eth1 up
+ e4.2 eth1 up
+ e4.3 eth1 up
+ e4.4 eth1 up
+ e4.5 eth1 up
+ e4.6 eth1 up
+ e4.7 eth1 up
+ e4.8 eth1 up
+ e4.9 eth1 up
Use /sys/module/aoe/parameters/aoe_iflist (or better, the driver
option discussed below) instead of /dev/etherd/interfaces to limit
@@ -113,12 +119,13 @@ USING SYSFS
for this purpose. You can also directly use the
/dev/etherd/discover special file described above.
-DRIVER OPTIONS
+Driver Options
+==============
There is a boot option for the built-in aoe driver and a
corresponding module parameter, aoe_iflist. Without this option,
all network interfaces may be used for ATA over Ethernet. Here is a
- usage example for the module parameter.
+ usage example for the module parameter::
modprobe aoe_iflist="eth1 eth3"
diff --git a/Documentation/aoe/todo.txt b/Documentation/aoe/todo.txt
index c09dfad4aed8..dea8db5a33e1 100644
--- a/Documentation/aoe/todo.txt
+++ b/Documentation/aoe/todo.txt
@@ -1,3 +1,6 @@
+TODO
+====
+
There is a potential for deadlock when allocating a struct sk_buff for
data that needs to be written out to aoe storage. If the data is
being written from a dirty page in order to free that page, and if
diff --git a/Documentation/aoe/udev.txt b/Documentation/aoe/udev.txt
index 1f06daf03f5b..54feda5a0772 100644
--- a/Documentation/aoe/udev.txt
+++ b/Documentation/aoe/udev.txt
@@ -11,7 +11,7 @@
# udev_rules="/etc/udev/rules.d/"
# bash# ls /etc/udev/rules.d/
# 10-wacom.rules 50-udev.rules
-# bash# cp /path/to/linux-2.6.xx/Documentation/aoe/udev.txt \
+# bash# cp /path/to/linux/Documentation/aoe/udev.txt \
# /etc/udev/rules.d/60-aoe.rules
#
--
2.20.1
^ permalink raw reply related [flat|nested] 81+ messages in thread* [PATCH 04/57] docs: arm64: convert documentation to ReST format
2019-04-16 2:55 [PATCH 00/57] Convert files to ReST Mauro Carvalho Chehab
` (2 preceding siblings ...)
2019-04-16 2:55 ` [PATCH 03/57] docs: aoe: " Mauro Carvalho Chehab
@ 2019-04-16 2:55 ` Mauro Carvalho Chehab
2019-04-16 2:55 ` [PATCH 06/57] docs: cdrom: convert remaining files to ReST Mauro Carvalho Chehab
` (48 subsequent siblings)
52 siblings, 0 replies; 81+ messages in thread
From: Mauro Carvalho Chehab @ 2019-04-16 2:55 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Catalin Marinas, Will Deacon, linux-arm-kernel
The documentation is in pretty much ReST format. Just some
small adjustments in order to fix tables and to make Sphinx
to recognize certain format blocks are required.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
Documentation/arm64/acpi_object_usage.txt | 288 ++++++++++++------
Documentation/arm64/arm-acpi.txt | 153 +++++-----
Documentation/arm64/booting.txt | 91 ++++--
Documentation/arm64/cpu-feature-registers.txt | 190 ++++++------
Documentation/arm64/elf_hwcaps.txt | 50 +--
Documentation/arm64/hugetlbpage.txt | 7 +-
Documentation/arm64/legacy_instructions.txt | 43 ++-
Documentation/arm64/memory.txt | 91 +++---
.../arm64/pointer-authentication.txt | 2 +
Documentation/arm64/silicon-errata.txt | 63 +++-
Documentation/arm64/sve.txt | 10 +-
Documentation/arm64/tagged-pointers.txt | 6 +-
arch/arm64/kernel/kexec_image.c | 2 +-
13 files changed, 595 insertions(+), 401 deletions(-)
diff --git a/Documentation/arm64/acpi_object_usage.txt b/Documentation/arm64/acpi_object_usage.txt
index c77010c5c1f0..d51b69dc624d 100644
--- a/Documentation/arm64/acpi_object_usage.txt
+++ b/Documentation/arm64/acpi_object_usage.txt
@@ -1,5 +1,7 @@
+===========
ACPI Tables
------------
+===========
+
The expectations of individual ACPI tables are discussed in the list that
follows.
@@ -11,54 +13,71 @@ outside of the UEFI Forum (see Section 5.2.6 of the specification).
For ACPI on arm64, tables also fall into the following categories:
- -- Required: DSDT, FADT, GTDT, MADT, MCFG, RSDP, SPCR, XSDT
+ - Required: DSDT, FADT, GTDT, MADT, MCFG, RSDP, SPCR, XSDT
- -- Recommended: BERT, EINJ, ERST, HEST, PCCT, SSDT
+ - Recommended: BERT, EINJ, ERST, HEST, PCCT, SSDT
- -- Optional: BGRT, CPEP, CSRT, DBG2, DRTM, ECDT, FACS, FPDT, IORT,
+ - Optional: BGRT, CPEP, CSRT, DBG2, DRTM, ECDT, FACS, FPDT, IORT,
MCHI, MPST, MSCT, NFIT, PMTT, RASF, SBST, SLIT, SPMI, SRAT, STAO,
TCPA, TPM2, UEFI, XENV
- -- Not supported: BOOT, DBGP, DMAR, ETDT, HPET, IBFT, IVRS, LPIT,
+ - Not supported: BOOT, DBGP, DMAR, ETDT, HPET, IBFT, IVRS, LPIT,
MSDM, OEMx, PSDT, RSDT, SLIC, WAET, WDAT, WDRT, WPBT
+====== ========================================================================
Table Usage for ARMv8 Linux
------ ----------------------------------------------------------------
+====== ========================================================================
BERT Section 18.3 (signature == "BERT")
- == Boot Error Record Table ==
+
+ **Boot Error Record Table**
+
Must be supplied if RAS support is provided by the platform. It
is recommended this table be supplied.
BOOT Signature Reserved (signature == "BOOT")
- == simple BOOT flag table ==
+
+ **simple BOOT flag table**
+
Microsoft only table, will not be supported.
BGRT Section 5.2.22 (signature == "BGRT")
- == Boot Graphics Resource Table ==
+
+ **Boot Graphics Resource Table**
+
Optional, not currently supported, with no real use-case for an
ARM server.
CPEP Section 5.2.18 (signature == "CPEP")
- == Corrected Platform Error Polling table ==
+
+ **Corrected Platform Error Polling table**
+
Optional, not currently supported, and not recommended until such
time as ARM-compatible hardware is available, and the specification
suitably modified.
CSRT Signature Reserved (signature == "CSRT")
- == Core System Resources Table ==
+
+ **Core System Resources Table**
+
Optional, not currently supported.
DBG2 Signature Reserved (signature == "DBG2")
- == DeBuG port table 2 ==
+
+ **DeBuG port table 2**
+
License has changed and should be usable. Optional if used instead
of earlycon=<device> on the command line.
DBGP Signature Reserved (signature == "DBGP")
- == DeBuG Port table ==
+
+ **DeBuG Port table**
+
Microsoft only table, will not be supported.
DSDT Section 5.2.11.1 (signature == "DSDT")
- == Differentiated System Description Table ==
+
+ **Differentiated System Description Table**
+
A DSDT is required; see also SSDT.
ACPI tables contain only one DSDT but can contain one or more SSDTs,
@@ -66,22 +85,30 @@ DSDT Section 5.2.11.1 (signature == "DSDT")
but cannot modify or replace anything in the DSDT.
DMAR Signature Reserved (signature == "DMAR")
- == DMA Remapping table ==
+
+ **DMA Remapping table**
+
x86 only table, will not be supported.
DRTM Signature Reserved (signature == "DRTM")
- == Dynamic Root of Trust for Measurement table ==
+
+ **Dynamic Root of Trust for Measurement table**
+
Optional, not currently supported.
ECDT Section 5.2.16 (signature == "ECDT")
- == Embedded Controller Description Table ==
+
+ **Embedded Controller Description Table**
+
Optional, not currently supported, but could be used on ARM if and
only if one uses the GPE_BIT field to represent an IRQ number, since
there are no GPE blocks defined in hardware reduced mode. This would
need to be modified in the ACPI specification.
EINJ Section 18.6 (signature == "EINJ")
- == Error Injection table ==
+
+ **Error Injection table**
+
This table is very useful for testing platform response to error
conditions; it allows one to inject an error into the system as
if it had actually occurred. However, this table should not be
@@ -89,27 +116,35 @@ EINJ Section 18.6 (signature == "EINJ")
and executed with the ACPICA tools only during testing.
ERST Section 18.5 (signature == "ERST")
- == Error Record Serialization Table ==
+
+ **Error Record Serialization Table**
+
On a platform supports RAS, this table must be supplied if it is not
UEFI-based; if it is UEFI-based, this table may be supplied. When this
table is not present, UEFI run time service will be utilized to save
and retrieve hardware error information to and from a persistent store.
ETDT Signature Reserved (signature == "ETDT")
- == Event Timer Description Table ==
+
+ **Event Timer Description Table**
+
Obsolete table, will not be supported.
FACS Section 5.2.10 (signature == "FACS")
- == Firmware ACPI Control Structure ==
+
+ **Firmware ACPI Control Structure**
+
It is unlikely that this table will be terribly useful. If it is
provided, the Global Lock will NOT be used since it is not part of
the hardware reduced profile, and only 64-bit address fields will
be considered valid.
FADT Section 5.2.9 (signature == "FACP")
- == Fixed ACPI Description Table ==
+
+ **Fixed ACPI Description Table**
Required for arm64.
+
The HW_REDUCED_ACPI flag must be set. All of the fields that are
to be ignored when HW_REDUCED_ACPI is set are expected to be set to
zero.
@@ -118,22 +153,28 @@ FADT Section 5.2.9 (signature == "FACP")
used, not FIRMWARE_CTRL.
If PSCI is used (as is recommended), make sure that ARM_BOOT_ARCH is
- filled in properly -- that the PSCI_COMPLIANT flag is set and that
+ filled in properly - that the PSCI_COMPLIANT flag is set and that
PSCI_USE_HVC is set or unset as needed (see table 5-37).
For the DSDT that is also required, the X_DSDT field is to be used,
not the DSDT field.
FPDT Section 5.2.23 (signature == "FPDT")
- == Firmware Performance Data Table ==
+
+ **Firmware Performance Data Table**
+
Optional, not currently supported.
GTDT Section 5.2.24 (signature == "GTDT")
- == Generic Timer Description Table ==
+
+ **Generic Timer Description Table**
+
Required for arm64.
HEST Section 18.3.2 (signature == "HEST")
- == Hardware Error Source Table ==
+
+ **Hardware Error Source Table**
+
ARM-specific error sources have been defined; please use those or the
PCI types such as type 6 (AER Root Port), 7 (AER Endpoint), or 8 (AER
Bridge), or use type 9 (Generic Hardware Error Source). Firmware first
@@ -144,122 +185,174 @@ HEST Section 18.3.2 (signature == "HEST")
is recommended this table be supplied.
HPET Signature Reserved (signature == "HPET")
- == High Precision Event timer Table ==
+
+ **High Precision Event timer Table**
+
x86 only table, will not be supported.
IBFT Signature Reserved (signature == "IBFT")
- == iSCSI Boot Firmware Table ==
+
+ **iSCSI Boot Firmware Table**
+
Microsoft defined table, support TBD.
IORT Signature Reserved (signature == "IORT")
- == Input Output Remapping Table ==
+
+ **Input Output Remapping Table**
+
arm64 only table, required in order to describe IO topology, SMMUs,
and GIC ITSs, and how those various components are connected together,
such as identifying which components are behind which SMMUs/ITSs.
This table will only be required on certain SBSA platforms (e.g.,
- when using GICv3-ITS and an SMMU); on SBSA Level 0 platforms, it
+ when using GICv3-ITS and an SMMU); on SBSA Level 0 platforms, it
remains optional.
IVRS Signature Reserved (signature == "IVRS")
- == I/O Virtualization Reporting Structure ==
+
+ **I/O Virtualization Reporting Structure**
+
x86_64 (AMD) only table, will not be supported.
LPIT Signature Reserved (signature == "LPIT")
- == Low Power Idle Table ==
+
+ **Low Power Idle Table**
+
x86 only table as of ACPI 5.1; starting with ACPI 6.0, processor
descriptions and power states on ARM platforms should use the DSDT
and define processor container devices (_HID ACPI0010, Section 8.4,
and more specifically 8.4.3 and and 8.4.4).
MADT Section 5.2.12 (signature == "APIC")
- == Multiple APIC Description Table ==
+
+ **Multiple APIC Description Table**
+
Required for arm64. Only the GIC interrupt controller structures
should be used (types 0xA - 0xF).
MCFG Signature Reserved (signature == "MCFG")
- == Memory-mapped ConFiGuration space ==
+
+ **Memory-mapped ConFiGuration space**
+
If the platform supports PCI/PCIe, an MCFG table is required.
MCHI Signature Reserved (signature == "MCHI")
- == Management Controller Host Interface table ==
+
+ **Management Controller Host Interface table**
+
Optional, not currently supported.
MPST Section 5.2.21 (signature == "MPST")
- == Memory Power State Table ==
+
+ **Memory Power State Table**
+
Optional, not currently supported.
MSCT Section 5.2.19 (signature == "MSCT")
- == Maximum System Characteristic Table ==
+
+ **Maximum System Characteristic Table**
+
Optional, not currently supported.
MSDM Signature Reserved (signature == "MSDM")
- == Microsoft Data Management table ==
+
+ **Microsoft Data Management table**
+
Microsoft only table, will not be supported.
NFIT Section 5.2.25 (signature == "NFIT")
- == NVDIMM Firmware Interface Table ==
+
+ **NVDIMM Firmware Interface Table**
+
Optional, not currently supported.
OEMx Signature of "OEMx" only
- == OEM Specific Tables ==
+
+ **OEM Specific Tables**
+
All tables starting with a signature of "OEM" are reserved for OEM
use. Since these are not meant to be of general use but are limited
to very specific end users, they are not recommended for use and are
not supported by the kernel for arm64.
PCCT Section 14.1 (signature == "PCCT)
- == Platform Communications Channel Table ==
+
+ **Platform Communications Channel Table**
+
Recommend for use on arm64; use of PCC is recommended when using CPPC
to control performance and power for platform processors.
PMTT Section 5.2.21.12 (signature == "PMTT")
- == Platform Memory Topology Table ==
+
+ **Platform Memory Topology Table**
+
Optional, not currently supported.
PSDT Section 5.2.11.3 (signature == "PSDT")
- == Persistent System Description Table ==
+
+ **Persistent System Description Table**
+
Obsolete table, will not be supported.
RASF Section 5.2.20 (signature == "RASF")
- == RAS Feature table ==
+
+ **RAS Feature table**
+
Optional, not currently supported.
RSDP Section 5.2.5 (signature == "RSD PTR")
- == Root System Description PoinTeR ==
+
+ **Root System Description PoinTeR**
+
Required for arm64.
RSDT Section 5.2.7 (signature == "RSDT")
- == Root System Description Table ==
+
+ **Root System Description Table**
+
Since this table can only provide 32-bit addresses, it is deprecated
on arm64, and will not be used. If provided, it will be ignored.
SBST Section 5.2.14 (signature == "SBST")
- == Smart Battery Subsystem Table ==
+
+ **Smart Battery Subsystem Table**
+
Optional, not currently supported.
SLIC Signature Reserved (signature == "SLIC")
- == Software LIcensing table ==
+
+ **Software LIcensing table**
+
Microsoft only table, will not be supported.
SLIT Section 5.2.17 (signature == "SLIT")
- == System Locality distance Information Table ==
+
+ **System Locality distance Information Table**
+
Optional in general, but required for NUMA systems.
SPCR Signature Reserved (signature == "SPCR")
- == Serial Port Console Redirection table ==
+
+ **Serial Port Console Redirection table**
+
Required for arm64.
SPMI Signature Reserved (signature == "SPMI")
- == Server Platform Management Interface table ==
+
+ **Server Platform Management Interface table**
+
Optional, not currently supported.
SRAT Section 5.2.16 (signature == "SRAT")
- == System Resource Affinity Table ==
+
+ **System Resource Affinity Table**
+
Optional, but if used, only the GICC Affinity structures are read.
To support arm64 NUMA, this table is required.
SSDT Section 5.2.11.2 (signature == "SSDT")
- == Secondary System Description Table ==
+
+ **Secondary System Description Table**
+
These tables are a continuation of the DSDT; these are recommended
for use with devices that can be added to a running system, but can
also serve the purpose of dividing up device descriptions into more
@@ -272,49 +365,69 @@ SSDT Section 5.2.11.2 (signature == "SSDT")
one DSDT but can contain many SSDTs.
STAO Signature Reserved (signature == "STAO")
- == _STA Override table ==
+
+ **_STA Override table**
+
Optional, but only necessary in virtualized environments in order to
hide devices from guest OSs.
TCPA Signature Reserved (signature == "TCPA")
- == Trusted Computing Platform Alliance table ==
+
+ **Trusted Computing Platform Alliance table**
+
Optional, not currently supported, and may need changes to fully
interoperate with arm64.
TPM2 Signature Reserved (signature == "TPM2")
- == Trusted Platform Module 2 table ==
+
+ **Trusted Platform Module 2 table**
+
Optional, not currently supported, and may need changes to fully
interoperate with arm64.
UEFI Signature Reserved (signature == "UEFI")
- == UEFI ACPI data table ==
+
+ **UEFI ACPI data table**
+
Optional, not currently supported. No known use case for arm64,
at present.
WAET Signature Reserved (signature == "WAET")
- == Windows ACPI Emulated devices Table ==
+
+ **Windows ACPI Emulated devices Table**
+
Microsoft only table, will not be supported.
WDAT Signature Reserved (signature == "WDAT")
- == Watch Dog Action Table ==
+
+ **Watch Dog Action Table**
+
Microsoft only table, will not be supported.
WDRT Signature Reserved (signature == "WDRT")
- == Watch Dog Resource Table ==
+
+ **Watch Dog Resource Table**
+
Microsoft only table, will not be supported.
WPBT Signature Reserved (signature == "WPBT")
- == Windows Platform Binary Table ==
+
+ **Windows Platform Binary Table**
+
Microsoft only table, will not be supported.
XENV Signature Reserved (signature == "XENV")
- == Xen project table ==
+
+ **Xen project table**
+
Optional, used only by Xen at present.
XSDT Section 5.2.8 (signature == "XSDT")
- == eXtended System Description Table ==
+
+ **eXtended System Description Table**
+
Required for arm64.
-
+====== ========================================================================
ACPI Objects
------------
@@ -323,10 +436,11 @@ shown in the list that follows; any object not explicitly mentioned below
should be used as needed for a particular platform or particular subsystem,
such as power management or PCI.
+===== ================ ========================================================
Name Section Usage for ARMv8 Linux
----- ------------ -------------------------------------------------
+===== ================ ========================================================
_CCA 6.2.17 This method must be defined for all bus masters
- on arm64 -- there are no assumptions made about
+ on arm64 - there are no assumptions made about
whether such devices are cache coherent or not.
The _CCA value is inherited by all descendants of
these devices so it does not need to be repeated.
@@ -422,8 +536,8 @@ _OSC 6.2.11 This method can be a global method in ACPI (i.e.,
by the kernel community, then register it with the
UEFI Forum.
-\_OSI 5.7.2 Deprecated on ARM64. As far as ACPI firmware is
- concerned, _OSI is not to be used to determine what
+\_OSI 5.7.2 Deprecated on ARM64. As far as ACPI firmware is
+ concerned, _OSI is not to be used to determine what
sort of system is being used or what functionality
is provided. The _OSC method is to be used instead.
@@ -447,7 +561,7 @@ _PSx 7.3.2-5 Use as needed; power management specific. If _PS0 is
usage, change them in these methods.
_RDI 8.4.4.4 Recommended for use with processor definitions (_HID
- ACPI0010) on arm64. This should only be used in
+ ACPI0010) on arm64. This should only be used in
conjunction with _LPI.
\_REV 5.7.4 Always returns the latest version of ACPI supported.
@@ -476,6 +590,7 @@ _SWS 7.4.3 Use as needed; power management specific; this may
_UID 6.1.12 Recommended for distinguishing devices of the same
class; define it if at all possible.
+===== ================ ========================================================
@@ -488,7 +603,7 @@ platforms, ACPI events must be signaled differently.
There are two options: GPIO-signaled interrupts (Section 5.6.5), and
interrupt-signaled events (Section 5.6.9). Interrupt-signaled events are a
-new feature in the ACPI 6.1 specification. Either -- or both -- can be used
+new feature in the ACPI 6.1 specification. Either - or both - can be used
on a given platform, and which to use may be dependent of limitations in any
given SoC. If possible, interrupt-signaled events are recommended.
@@ -564,39 +679,40 @@ supported.
The following classes of objects are not supported:
- -- Section 9.2: ambient light sensor devices
+ - Section 9.2: ambient light sensor devices
- -- Section 9.3: battery devices
+ - Section 9.3: battery devices
- -- Section 9.4: lids (e.g., laptop lids)
+ - Section 9.4: lids (e.g., laptop lids)
- -- Section 9.8.2: IDE controllers
+ - Section 9.8.2: IDE controllers
- -- Section 9.9: floppy controllers
+ - Section 9.9: floppy controllers
- -- Section 9.10: GPE block devices
+ - Section 9.10: GPE block devices
- -- Section 9.15: PC/AT RTC/CMOS devices
+ - Section 9.15: PC/AT RTC/CMOS devices
- -- Section 9.16: user presence detection devices
+ - Section 9.16: user presence detection devices
- -- Section 9.17: I/O APIC devices; all GICs must be enumerable via MADT
+ - Section 9.17: I/O APIC devices; all GICs must be enumerable via MADT
- -- Section 9.18: time and alarm devices (see 9.15)
+ - Section 9.18: time and alarm devices (see 9.15)
- -- Section 10: power source and power meter devices
+ - Section 10: power source and power meter devices
- -- Section 11: thermal management
+ - Section 11: thermal management
- -- Section 12: embedded controllers interface
+ - Section 12: embedded controllers interface
- -- Section 13: SMBus interfaces
+ - Section 13: SMBus interfaces
This also means that there is no support for the following objects:
+==== =========================== ==== ==========
Name Section Name Section
----- ------------ ---- ------------
+==== =========================== ==== ==========
_ALC 9.3.4 _FDM 9.10.3
_ALI 9.3.2 _FIX 6.2.7
_ALP 9.3.6 _GAI 10.4.5
@@ -619,4 +735,4 @@ _DCK 6.5.2 _UPD 9.16.1
_EC 12.12 _UPP 9.16.2
_FDE 9.10.1 _WPC 10.5.2
_FDI 9.10.2 _WPP 10.5.3
-
+==== =========================== ==== ==========
diff --git a/Documentation/arm64/arm-acpi.txt b/Documentation/arm64/arm-acpi.txt
index 1a74a041a443..f9341b71344b 100644
--- a/Documentation/arm64/arm-acpi.txt
+++ b/Documentation/arm64/arm-acpi.txt
@@ -1,5 +1,7 @@
+=====================
ACPI on ARMv8 Servers
----------------------
+=====================
+
ACPI can be used for ARMv8 general purpose servers designed to follow
the ARM SBSA (Server Base System Architecture) [0] and SBBR (Server
Base Boot Requirements) [1] specifications. Please note that the SBBR
@@ -34,28 +36,28 @@ of the summary text almost directly, to be honest.
The short form of the rationale for ACPI on ARM is:
--- ACPI’s byte code (AML) allows the platform to encode hardware behavior,
+- ACPI’s byte code (AML) allows the platform to encode hardware behavior,
while DT explicitly does not support this. For hardware vendors, being
able to encode behavior is a key tool used in supporting operating
system releases on new hardware.
--- ACPI’s OSPM defines a power management model that constrains what the
+- ACPI’s OSPM defines a power management model that constrains what the
platform is allowed to do into a specific model, while still providing
flexibility in hardware design.
--- In the enterprise server environment, ACPI has established bindings (such
+- In the enterprise server environment, ACPI has established bindings (such
as for RAS) which are currently used in production systems. DT does not.
Such bindings could be defined in DT at some point, but doing so means ARM
and x86 would end up using completely different code paths in both firmware
and the kernel.
--- Choosing a single interface to describe the abstraction between a platform
+- Choosing a single interface to describe the abstraction between a platform
and an OS is important. Hardware vendors would not be required to implement
both DT and ACPI if they want to support multiple operating systems. And,
agreeing on a single interface instead of being fragmented into per OS
interfaces makes for better interoperability overall.
--- The new ACPI governance process works well and Linux is now at the same
+- The new ACPI governance process works well and Linux is now at the same
table as hardware vendors and other OS vendors. In fact, there is no
longer any reason to feel that ACPI only belongs to Windows or that
Linux is in any way secondary to Microsoft in this arena. The move of
@@ -169,31 +171,31 @@ For the ACPI core to operate properly, and in turn provide the information
the kernel needs to configure devices, it expects to find the following
tables (all section numbers refer to the ACPI 6.1 specification):
- -- RSDP (Root System Description Pointer), section 5.2.5
+ - RSDP (Root System Description Pointer), section 5.2.5
- -- XSDT (eXtended System Description Table), section 5.2.8
+ - XSDT (eXtended System Description Table), section 5.2.8
- -- FADT (Fixed ACPI Description Table), section 5.2.9
+ - FADT (Fixed ACPI Description Table), section 5.2.9
- -- DSDT (Differentiated System Description Table), section
+ - DSDT (Differentiated System Description Table), section
5.2.11.1
- -- MADT (Multiple APIC Description Table), section 5.2.12
+ - MADT (Multiple APIC Description Table), section 5.2.12
- -- GTDT (Generic Timer Description Table), section 5.2.24
+ - GTDT (Generic Timer Description Table), section 5.2.24
- -- If PCI is supported, the MCFG (Memory mapped ConFiGuration
+ - If PCI is supported, the MCFG (Memory mapped ConFiGuration
Table), section 5.2.6, specifically Table 5-31.
- -- If booting without a console=<device> kernel parameter is
+ - If booting without a console=<device> kernel parameter is
supported, the SPCR (Serial Port Console Redirection table),
section 5.2.6, specifically Table 5-31.
- -- If necessary to describe the I/O topology, SMMUs and GIC ITSs,
+ - If necessary to describe the I/O topology, SMMUs and GIC ITSs,
the IORT (Input Output Remapping Table, section 5.2.6, specifically
Table 5-31).
- -- If NUMA is supported, the SRAT (System Resource Affinity Table)
+ - If NUMA is supported, the SRAT (System Resource Affinity Table)
and SLIT (System Locality distance Information Table), sections
5.2.16 and 5.2.17, respectively.
@@ -269,9 +271,9 @@ describes how to define the structure of an object returned via _DSD, and
how specific data structures are defined by specific UUIDs. Linux should
only use the _DSD Device Properties UUID [5]:
- -- UUID: daffd814-6eba-4d8c-8a91-bc9bbf4aa301
+ - UUID: daffd814-6eba-4d8c-8a91-bc9bbf4aa301
- -- http://www.uefi.org/sites/default/files/resources/_DSD-device-properties-UUID.pdf
+ - http://www.uefi.org/sites/default/files/resources/_DSD-device-properties-UUID.pdf
The UEFI Forum provides a mechanism for registering device properties [4]
so that they may be used across all operating systems supporting ACPI.
@@ -327,10 +329,10 @@ turning a device full off.
There are two options for using those Power Resources. They can:
- -- be managed in a _PSx method which gets called on entry to power
+ - be managed in a _PSx method which gets called on entry to power
state Dx.
- -- be declared separately as power resources with their own _ON and _OFF
+ - be declared separately as power resources with their own _ON and _OFF
methods. They are then tied back to D-states for a particular device
via _PRx which specifies which power resources a device needs to be on
while in Dx. Kernel then tracks number of devices using a power resource
@@ -339,16 +341,16 @@ There are two options for using those Power Resources. They can:
The kernel ACPI code will also assume that the _PSx methods follow the normal
ACPI rules for such methods:
- -- If either _PS0 or _PS3 is implemented, then the other method must also
+ - If either _PS0 or _PS3 is implemented, then the other method must also
be implemented.
- -- If a device requires usage or setup of a power resource when on, the ASL
+ - If a device requires usage or setup of a power resource when on, the ASL
should organize that it is allocated/enabled using the _PS0 method.
- -- Resources allocated or enabled in the _PS0 method should be disabled
+ - Resources allocated or enabled in the _PS0 method should be disabled
or de-allocated in the _PS3 method.
- -- Firmware will leave the resources in a reasonable state before handing
+ - Firmware will leave the resources in a reasonable state before handing
over control to the kernel.
Such code in _PSx methods will of course be very platform specific. But,
@@ -394,52 +396,52 @@ else must be discovered by the driver probe function. Then, have the rest
of the driver operate off of the contents of that struct. Doing so should
allow most divergence between ACPI and DT functionality to be kept local to
the probe function instead of being scattered throughout the driver. For
-example:
+example::
-static int device_probe_dt(struct platform_device *pdev)
-{
- /* DT specific functionality */
- ...
-}
+ static int device_probe_dt(struct platform_device *pdev)
+ {
+ /* DT specific functionality */
+ ...
+ }
-static int device_probe_acpi(struct platform_device *pdev)
-{
- /* ACPI specific functionality */
- ...
-}
+ static int device_probe_acpi(struct platform_device *pdev)
+ {
+ /* ACPI specific functionality */
+ ...
+ }
-static int device_probe(struct platform_device *pdev)
-{
- ...
- struct device_node node = pdev->dev.of_node;
- ...
+ static int device_probe(struct platform_device *pdev)
+ {
+ ...
+ struct device_node node = pdev->dev.of_node;
+ ...
- if (node)
- ret = device_probe_dt(pdev);
- else if (ACPI_HANDLE(&pdev->dev))
- ret = device_probe_acpi(pdev);
- else
- /* other initialization */
- ...
- /* Continue with any generic probe operations */
- ...
-}
+ if (node)
+ ret = device_probe_dt(pdev);
+ else if (ACPI_HANDLE(&pdev->dev))
+ ret = device_probe_acpi(pdev);
+ else
+ /* other initialization */
+ ...
+ /* Continue with any generic probe operations */
+ ...
+ }
DO keep the MODULE_DEVICE_TABLE entries together in the driver to make it
clear the different names the driver is probed for, both from DT and from
-ACPI:
+ACPI::
-static struct of_device_id virtio_mmio_match[] = {
- { .compatible = "virtio,mmio", },
- { }
-};
-MODULE_DEVICE_TABLE(of, virtio_mmio_match);
+ static struct of_device_id virtio_mmio_match[] = {
+ { .compatible = "virtio,mmio", },
+ { }
+ };
+ MODULE_DEVICE_TABLE(of, virtio_mmio_match);
-static const struct acpi_device_id virtio_mmio_acpi_match[] = {
- { "LNRO0005", },
- { }
-};
-MODULE_DEVICE_TABLE(acpi, virtio_mmio_acpi_match);
+ static const struct acpi_device_id virtio_mmio_acpi_match[] = {
+ { "LNRO0005", },
+ { }
+ };
+ MODULE_DEVICE_TABLE(acpi, virtio_mmio_acpi_match);
ASWG
@@ -471,7 +473,8 @@ Linux Code
Individual items specific to Linux on ARM, contained in the the Linux
source code, are in the list that follows:
-ACPI_OS_NAME This macro defines the string to be returned when
+ACPI_OS_NAME
+ This macro defines the string to be returned when
an ACPI method invokes the _OS method. On ARM64
systems, this macro will be "Linux" by default.
The command line parameter acpi_os=<string>
@@ -487,33 +490,39 @@ Documentation/arm64/acpi_object_usage.txt.
References
----------
-[0] http://silver.arm.com -- document ARM-DEN-0029, or newer
+[0] http://silver.arm.com
+ document ARM-DEN-0029, or newer:
"Server Base System Architecture", version 2.3, dated 27 Mar 2014
[1] http://infocenter.arm.com/help/topic/com.arm.doc.den0044a/Server_Base_Boot_Requirements.pdf
Document ARM-DEN-0044A, or newer: "Server Base Boot Requirements, System
Software on ARM Platforms", dated 16 Aug 2014
-[2] http://www.secretlab.ca/archives/151, 10 Jan 2015, Copyright (c) 2015,
+[2] http://www.secretlab.ca/archives/151,
+ 10 Jan 2015, Copyright (c) 2015,
Linaro Ltd., written by Grant Likely.
-[3] AMD ACPI for Seattle platform documentation:
+[3] AMD ACPI for Seattle platform documentation
http://amd-dev.wpengine.netdna-cdn.com/wordpress/media/2012/10/Seattle_ACPI_Guide.pdf
-[4] http://www.uefi.org/acpi -- please see the link for the "ACPI _DSD Device
+
+[4] http://www.uefi.org/acpi
+ please see the link for the "ACPI _DSD Device
Property Registry Instructions"
-[5] http://www.uefi.org/acpi -- please see the link for the "_DSD (Device
+[5] http://www.uefi.org/acpi
+ please see the link for the "_DSD (Device
Specific Data) Implementation Guide"
-[6] Kernel code for the unified device property interface can be found in
+[6] Kernel code for the unified device
+ property interface can be found in
include/linux/property.h and drivers/base/property.c.
Authors
-------
-Al Stone <al.stone@linaro.org>
-Graeme Gregory <graeme.gregory@linaro.org>
-Hanjun Guo <hanjun.guo@linaro.org>
+- Al Stone <al.stone@linaro.org>
+- Graeme Gregory <graeme.gregory@linaro.org>
+- Hanjun Guo <hanjun.guo@linaro.org>
-Grant Likely <grant.likely@linaro.org>, for the "Why ACPI on ARM?" section
+- Grant Likely <grant.likely@linaro.org>, for the "Why ACPI on ARM?" section
diff --git a/Documentation/arm64/booting.txt b/Documentation/arm64/booting.txt
index fbab7e21d116..3d041d0d16e8 100644
--- a/Documentation/arm64/booting.txt
+++ b/Documentation/arm64/booting.txt
@@ -1,7 +1,9 @@
- Booting AArch64 Linux
- =====================
+=====================
+Booting AArch64 Linux
+=====================
Author: Will Deacon <will.deacon@arm.com>
+
Date : 07 September 2012
This document is based on the ARM booting document by Russell King and
@@ -12,7 +14,7 @@ The AArch64 exception model is made up of a number of exception levels
counterpart. EL2 is the hypervisor level and exists only in non-secure
mode. EL3 is the highest priority level and exists only in secure mode.
-For the purposes of this document, we will use the term `boot loader'
+For the purposes of this document, we will use the term `boot loader`
simply to define all software that executes on the CPU(s) before control
is passed to the Linux kernel. This may include secure monitor and
hypervisor code, or it may just be a handful of instructions for
@@ -70,7 +72,7 @@ Image target is available instead.
Requirement: MANDATORY
-The decompressed kernel image contains a 64-byte header as follows:
+The decompressed kernel image contains a 64-byte header as follows::
u32 code0; /* Executable code */
u32 code1; /* Executable code */
@@ -103,19 +105,26 @@ Header notes:
- The flags field (introduced in v3.17) is a little-endian 64-bit field
composed as follows:
- Bit 0: Kernel endianness. 1 if BE, 0 if LE.
- Bit 1-2: Kernel Page size.
- 0 - Unspecified.
- 1 - 4K
- 2 - 16K
- 3 - 64K
- Bit 3: Kernel physical placement
- 0 - 2MB aligned base should be as close as possible
- to the base of DRAM, since memory below it is not
- accessible via the linear mapping
- 1 - 2MB aligned base may be anywhere in physical
- memory
- Bits 4-63: Reserved.
+
+ ============= ===============================================================
+ Bit 0 Kernel endianness. 1 if BE, 0 if LE.
+ Bit 1-2 Kernel Page size.
+
+ * 0 - Unspecified.
+ * 1 - 4K
+ * 2 - 16K
+ * 3 - 64K
+ Bit 3 Kernel physical placement
+
+ 0
+ 2MB aligned base should be as close as possible
+ to the base of DRAM, since memory below it is not
+ accessible via the linear mapping
+ 1
+ 2MB aligned base may be anywhere in physical
+ memory
+ Bits 4-63 Reserved.
+ ============= ===============================================================
- When image_size is zero, a bootloader should attempt to keep as much
memory as possible free for use by the kernel immediately after the
@@ -147,19 +156,22 @@ Before jumping into the kernel, the following conditions must be met:
corrupted by bogus network packets or disk data. This will save
you many hours of debug.
-- Primary CPU general-purpose register settings
- x0 = physical address of device tree blob (dtb) in system RAM.
- x1 = 0 (reserved for future use)
- x2 = 0 (reserved for future use)
- x3 = 0 (reserved for future use)
+- Primary CPU general-purpose register settings:
+
+ - x0 = physical address of device tree blob (dtb) in system RAM.
+ - x1 = 0 (reserved for future use)
+ - x2 = 0 (reserved for future use)
+ - x3 = 0 (reserved for future use)
- CPU mode
+
All forms of interrupts must be masked in PSTATE.DAIF (Debug, SError,
IRQ and FIQ).
The CPU must be in either EL2 (RECOMMENDED in order to have access to
the virtualisation extensions) or non-secure EL1.
- Caches, MMUs
+
The MMU must be off.
Instruction cache may be on or off.
The address range corresponding to the loaded kernel image must be
@@ -172,18 +184,21 @@ Before jumping into the kernel, the following conditions must be met:
operations (not recommended) must be configured and disabled.
- Architected timers
+
CNTFRQ must be programmed with the timer frequency and CNTVOFF must
be programmed with a consistent value on all CPUs. If entering the
kernel at EL1, CNTHCTL_EL2 must have EL1PCTEN (bit 0) set where
available.
- Coherency
+
All CPUs to be booted by the kernel must be part of the same coherency
domain on entry to the kernel. This may require IMPLEMENTATION DEFINED
initialisation to enable the receiving of maintenance operations on
each CPU.
- System registers
+
All writable architected system registers at the exception level where
the kernel image will be entered must be initialised by software at a
higher exception level to prevent execution in an UNKNOWN state.
@@ -195,28 +210,40 @@ Before jumping into the kernel, the following conditions must be met:
For systems with a GICv3 interrupt controller to be used in v3 mode:
- If EL3 is present:
- ICC_SRE_EL3.Enable (bit 3) must be initialiased to 0b1.
- ICC_SRE_EL3.SRE (bit 0) must be initialised to 0b1.
+
+ - ICC_SRE_EL3.Enable (bit 3) must be initialiased to 0b1.
+ - ICC_SRE_EL3.SRE (bit 0) must be initialised to 0b1.
+
- If the kernel is entered at EL1:
- ICC.SRE_EL2.Enable (bit 3) must be initialised to 0b1
- ICC_SRE_EL2.SRE (bit 0) must be initialised to 0b1.
+
+ - ICC.SRE_EL2.Enable (bit 3) must be initialised to 0b1
+ - ICC_SRE_EL2.SRE (bit 0) must be initialised to 0b1.
+
- The DT or ACPI tables must describe a GICv3 interrupt controller.
For systems with a GICv3 interrupt controller to be used in
compatibility (v2) mode:
+
- If EL3 is present:
- ICC_SRE_EL3.SRE (bit 0) must be initialised to 0b0.
+
+ ICC_SRE_EL3.SRE (bit 0) must be initialised to 0b0.
+
- If the kernel is entered at EL1:
- ICC_SRE_EL2.SRE (bit 0) must be initialised to 0b0.
+
+ ICC_SRE_EL2.SRE (bit 0) must be initialised to 0b0.
+
- The DT or ACPI tables must describe a GICv2 interrupt controller.
For CPUs with pointer authentication functionality:
- If EL3 is present:
- SCR_EL3.APK (bit 16) must be initialised to 0b1
- SCR_EL3.API (bit 17) must be initialised to 0b1
+
+ - SCR_EL3.APK (bit 16) must be initialised to 0b1
+ - SCR_EL3.API (bit 17) must be initialised to 0b1
+
- If the kernel is entered at EL1:
- HCR_EL2.APK (bit 40) must be initialised to 0b1
- HCR_EL2.API (bit 41) must be initialised to 0b1
+
+ - HCR_EL2.APK (bit 40) must be initialised to 0b1
+ - HCR_EL2.API (bit 41) must be initialised to 0b1
The requirements described above for CPU mode, caches, MMUs, architected
timers, coherency and system registers apply to all CPUs. All CPUs must
diff --git a/Documentation/arm64/cpu-feature-registers.txt b/Documentation/arm64/cpu-feature-registers.txt
index d4b4dd1fe786..251174aaa8ea 100644
--- a/Documentation/arm64/cpu-feature-registers.txt
+++ b/Documentation/arm64/cpu-feature-registers.txt
@@ -1,5 +1,6 @@
- ARM64 CPU Feature Registers
- ===========================
+===========================
+ARM64 CPU Feature Registers
+===========================
Author: Suzuki K Poulose <suzuki.poulose@arm.com>
@@ -9,7 +10,7 @@ registers to userspace. The availability of this ABI is advertised
via the HWCAP_CPUID in HWCAPs.
1. Motivation
----------------
+-------------
The ARM architecture defines a set of feature registers, which describe
the capabilities of the CPU/system. Access to these system registers is
@@ -33,9 +34,10 @@ there are some issues with their usage.
2. Requirements
------------------
+---------------
+
+ a) Safety:
- a) Safety :
Applications should be able to use the information provided by the
infrastructure to run safely across the system. This has greater
implications on a system with heterogeneous CPUs.
@@ -47,7 +49,8 @@ there are some issues with their usage.
Otherwise an application could crash when scheduled on the CPU
which doesn't support CRC32.
- b) Security :
+ b) Security:
+
Applications should only be able to receive information that is
relevant to the normal operation in userspace. Hence, some of the
fields are masked out(i.e, made invisible) and their values are set to
@@ -58,10 +61,12 @@ there are some issues with their usage.
(even when the CPU provides it).
c) Implementation Defined Features
+
The infrastructure doesn't expose any register which is
IMPLEMENTATION DEFINED as per ARMv8-A Architecture.
- d) CPU Identification :
+ d) CPU Identification:
+
MIDR_EL1 is exposed to help identify the processor. On a
heterogeneous system, this could be racy (just like getcpu()). The
process could be migrated to another CPU by the time it uses the
@@ -70,7 +75,7 @@ there are some issues with their usage.
currently executing on. The REVIDR is not exposed due to this
constraint, as REVIDR makes sense only in conjunction with the
MIDR. Alternately, MIDR_EL1 and REVIDR_EL1 are exposed via sysfs
- at:
+ at::
/sys/devices/system/cpu/cpu$ID/regs/identification/
\- midr
@@ -85,7 +90,8 @@ exception and ends up in SIGILL being delivered to the process.
The infrastructure hooks into the exception handler and emulates the
operation if the source belongs to the supported system register space.
-The infrastructure emulates only the following system register space:
+The infrastructure emulates only the following system register space::
+
Op0=3, Op1=0, CRn=0, CRm=0,4,5,6,7
(See Table C5-6 'System instruction encodings for non-Debug System
@@ -107,73 +113,76 @@ infrastructure:
-------------------------------------------
1) ID_AA64ISAR0_EL1 - Instruction Set Attribute Register 0
- x--------------------------------------------------x
+
+ +------------------------------+---------+---------+
| Name | bits | visible |
- |--------------------------------------------------|
+ +------------------------------+---------+---------+
| TS | [55-52] | y |
- |--------------------------------------------------|
+ +------------------------------+---------+---------+
| FHM | [51-48] | y |
- |--------------------------------------------------|
+ +------------------------------+---------+---------+
| DP | [47-44] | y |
- |--------------------------------------------------|
+ +------------------------------+---------+---------+
| SM4 | [43-40] | y |
- |--------------------------------------------------|
+ +------------------------------+---------+---------+
| SM3 | [39-36] | y |
- |--------------------------------------------------|
+ +------------------------------+---------+---------+
| SHA3 | [35-32] | y |
- |--------------------------------------------------|
+ +------------------------------+---------+---------+
| RDM | [31-28] | y |
- |--------------------------------------------------|
+ +------------------------------+---------+---------+
| ATOMICS | [23-20] | y |
- |--------------------------------------------------|
+ +------------------------------+---------+---------+
| CRC32 | [19-16] | y |
- |--------------------------------------------------|
+ +------------------------------+---------+---------+
| SHA2 | [15-12] | y |
- |--------------------------------------------------|
+ +------------------------------+---------+---------+
| SHA1 | [11-8] | y |
- |--------------------------------------------------|
+ +------------------------------+---------+---------+
| AES | [7-4] | y |
- x--------------------------------------------------x
+ +------------------------------+---------+---------+
2) ID_AA64PFR0_EL1 - Processor Feature Register 0
- x--------------------------------------------------x
+
+ +------------------------------+---------+---------+
| Name | bits | visible |
- |--------------------------------------------------|
+ +------------------------------+---------+---------+
| DIT | [51-48] | y |
- |--------------------------------------------------|
+ +------------------------------+---------+---------+
| SVE | [35-32] | y |
- |--------------------------------------------------|
+ +------------------------------+---------+---------+
| GIC | [27-24] | n |
- |--------------------------------------------------|
+ +------------------------------+---------+---------+
| AdvSIMD | [23-20] | y |
- |--------------------------------------------------|
+ +------------------------------+---------+---------+
| FP | [19-16] | y |
- |--------------------------------------------------|
+ +------------------------------+---------+---------+
| EL3 | [15-12] | n |
- |--------------------------------------------------|
+ +------------------------------+---------+---------+
| EL2 | [11-8] | n |
- |--------------------------------------------------|
+ +------------------------------+---------+---------+
| EL1 | [7-4] | n |
- |--------------------------------------------------|
+ +------------------------------+---------+---------+
| EL0 | [3-0] | n |
- x--------------------------------------------------x
+ +------------------------------+---------+---------+
3) MIDR_EL1 - Main ID Register
- x--------------------------------------------------x
+
+ +------------------------------+---------+---------+
| Name | bits | visible |
- |--------------------------------------------------|
+ +------------------------------+---------+---------+
| Implementer | [31-24] | y |
- |--------------------------------------------------|
+ +------------------------------+---------+---------+
| Variant | [23-20] | y |
- |--------------------------------------------------|
+ +------------------------------+---------+---------+
| Architecture | [19-16] | y |
- |--------------------------------------------------|
+ +------------------------------+---------+---------+
| PartNum | [15-4] | y |
- |--------------------------------------------------|
+ +------------------------------+---------+---------+
| Revision | [3-0] | y |
- x--------------------------------------------------x
+ +------------------------------+---------+---------+
NOTE: The 'visible' fields of MIDR_EL1 will contain the value
as available on the CPU where it is fetched and is not a system
@@ -181,74 +190,76 @@ infrastructure:
4) ID_AA64ISAR1_EL1 - Instruction set attribute register 1
- x--------------------------------------------------x
+ +------------------------------+---------+---------+
| Name | bits | visible |
- |--------------------------------------------------|
+ +------------------------------+---------+---------+
| GPI | [31-28] | y |
- |--------------------------------------------------|
+ +------------------------------+---------+---------+
| GPA | [27-24] | y |
- |--------------------------------------------------|
+ +------------------------------+---------+---------+
| LRCPC | [23-20] | y |
- |--------------------------------------------------|
+ +------------------------------+---------+---------+
| FCMA | [19-16] | y |
- |--------------------------------------------------|
+ +------------------------------+---------+---------+
| JSCVT | [15-12] | y |
- |--------------------------------------------------|
+ +------------------------------+---------+---------+
| API | [11-8] | y |
- |--------------------------------------------------|
+ +------------------------------+---------+---------+
| APA | [7-4] | y |
- |--------------------------------------------------|
+ +------------------------------+---------+---------+
| DPB | [3-0] | y |
- x--------------------------------------------------x
+ +------------------------------+---------+---------+
5) ID_AA64MMFR2_EL1 - Memory model feature register 2
- x--------------------------------------------------x
+ +------------------------------+---------+---------+
| Name | bits | visible |
- |--------------------------------------------------|
+ +------------------------------+---------+---------+
| AT | [35-32] | y |
- x--------------------------------------------------x
+ +------------------------------+---------+---------+
Appendix I: Example
----------------------------
+-------------------
-/*
- * Sample program to demonstrate the MRS emulation ABI.
- *
- * Copyright (C) 2015-2016, ARM Ltd
- *
- * Author: Suzuki K Poulose <suzuki.poulose@arm.com>
- *
- * This program is free software; you can redistribute it and/or modify
- * it under the terms of the GNU General Public License version 2 as
- * published by the Free Software Foundation.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
- * GNU General Public License for more details.
- * This program is free software; you can redistribute it and/or modify
- * it under the terms of the GNU General Public License version 2 as
- * published by the Free Software Foundation.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
- * GNU General Public License for more details.
- */
+::
-#include <asm/hwcap.h>
-#include <stdio.h>
-#include <sys/auxv.h>
+ /*
+ * Sample program to demonstrate the MRS emulation ABI.
+ *
+ * Copyright (C) 2015-2016, ARM Ltd
+ *
+ * Author: Suzuki K Poulose <suzuki.poulose@arm.com>
+ *
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License version 2 as
+ * published by the Free Software Foundation.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU General Public License for more details.
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License version 2 as
+ * published by the Free Software Foundation.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU General Public License for more details.
+ */
-#define get_cpu_ftr(id) ({ \
+ #include <asm/hwcap.h>
+ #include <stdio.h>
+ #include <sys/auxv.h>
+
+ #define get_cpu_ftr(id) ({ \
unsigned long __val; \
asm("mrs %0, "#id : "=r" (__val)); \
printf("%-20s: 0x%016lx\n", #id, __val); \
})
-int main(void)
-{
+ int main(void)
+ {
if (!(getauxval(AT_HWCAP) & HWCAP_CPUID)) {
fputs("CPUID registers unavailable\n", stderr);
@@ -268,13 +279,10 @@ int main(void)
get_cpu_ftr(MPIDR_EL1);
get_cpu_ftr(REVIDR_EL1);
-#if 0
+ #if 0
/* Unexposed register access causes SIGILL */
get_cpu_ftr(ID_MMFR0_EL1);
-#endif
+ #endif
return 0;
-}
-
-
-
+ }
diff --git a/Documentation/arm64/elf_hwcaps.txt b/Documentation/arm64/elf_hwcaps.txt
index 13d6691b37be..e624d6bd89f2 100644
--- a/Documentation/arm64/elf_hwcaps.txt
+++ b/Documentation/arm64/elf_hwcaps.txt
@@ -1,3 +1,4 @@
+================
ARM64 ELF hwcaps
================
@@ -15,16 +16,16 @@ of flags called hwcaps, exposed in the auxilliary vector.
Userspace software can test for features by acquiring the AT_HWCAP entry
of the auxilliary vector, and testing whether the relevant flags are
-set, e.g.
+set, e.g.::
-bool floating_point_is_present(void)
-{
- unsigned long hwcaps = getauxval(AT_HWCAP);
- if (hwcaps & HWCAP_FP)
- return true;
+ bool floating_point_is_present(void)
+ {
+ unsigned long hwcaps = getauxval(AT_HWCAP);
+ if (hwcaps & HWCAP_FP)
+ return true;
- return false;
-}
+ return false;
+ }
Where software relies on a feature described by a hwcap, it should check
the relevant hwcap flag to verify that the feature is present before
@@ -45,7 +46,7 @@ userspace code at EL0. These hwcaps are defined in terms of ID register
fields, and should be interpreted with reference to the definition of
these fields in the ARM Architecture Reference Manual (ARM ARM).
-Such hwcaps are described below in the form:
+Such hwcaps are described below in the form::
Functionality implied by idreg.field == val.
@@ -64,133 +65,102 @@ reference to ID registers, and may refer to other documentation.
---------------------------------
HWCAP_FP
-
Functionality implied by ID_AA64PFR0_EL1.FP == 0b0000.
HWCAP_ASIMD
-
Functionality implied by ID_AA64PFR0_EL1.AdvSIMD == 0b0000.
HWCAP_EVTSTRM
-
The generic timer is configured to generate events at a frequency of
approximately 100KHz.
HWCAP_AES
-
Functionality implied by ID_AA64ISAR0_EL1.AES == 0b0001.
HWCAP_PMULL
-
Functionality implied by ID_AA64ISAR0_EL1.AES == 0b0010.
HWCAP_SHA1
-
Functionality implied by ID_AA64ISAR0_EL1.SHA1 == 0b0001.
HWCAP_SHA2
-
Functionality implied by ID_AA64ISAR0_EL1.SHA2 == 0b0001.
HWCAP_CRC32
-
Functionality implied by ID_AA64ISAR0_EL1.CRC32 == 0b0001.
HWCAP_ATOMICS
-
Functionality implied by ID_AA64ISAR0_EL1.Atomic == 0b0010.
HWCAP_FPHP
-
Functionality implied by ID_AA64PFR0_EL1.FP == 0b0001.
HWCAP_ASIMDHP
-
Functionality implied by ID_AA64PFR0_EL1.AdvSIMD == 0b0001.
HWCAP_CPUID
-
EL0 access to certain ID registers is available, to the extent
described by Documentation/arm64/cpu-feature-registers.txt.
These ID registers may imply the availability of features.
HWCAP_ASIMDRDM
-
Functionality implied by ID_AA64ISAR0_EL1.RDM == 0b0001.
HWCAP_JSCVT
-
Functionality implied by ID_AA64ISAR1_EL1.JSCVT == 0b0001.
HWCAP_FCMA
-
Functionality implied by ID_AA64ISAR1_EL1.FCMA == 0b0001.
HWCAP_LRCPC
-
Functionality implied by ID_AA64ISAR1_EL1.LRCPC == 0b0001.
HWCAP_DCPOP
-
Functionality implied by ID_AA64ISAR1_EL1.DPB == 0b0001.
HWCAP_SHA3
-
Functionality implied by ID_AA64ISAR0_EL1.SHA3 == 0b0001.
HWCAP_SM3
-
Functionality implied by ID_AA64ISAR0_EL1.SM3 == 0b0001.
HWCAP_SM4
-
Functionality implied by ID_AA64ISAR0_EL1.SM4 == 0b0001.
HWCAP_ASIMDDP
-
Functionality implied by ID_AA64ISAR0_EL1.DP == 0b0001.
HWCAP_SHA512
-
Functionality implied by ID_AA64ISAR0_EL1.SHA2 == 0b0010.
HWCAP_SVE
-
Functionality implied by ID_AA64PFR0_EL1.SVE == 0b0001.
HWCAP_ASIMDFHM
-
Functionality implied by ID_AA64ISAR0_EL1.FHM == 0b0001.
HWCAP_DIT
-
Functionality implied by ID_AA64PFR0_EL1.DIT == 0b0001.
HWCAP_USCAT
-
Functionality implied by ID_AA64MMFR2_EL1.AT == 0b0001.
HWCAP_ILRCPC
-
Functionality implied by ID_AA64ISAR1_EL1.LRCPC == 0b0010.
HWCAP_FLAGM
-
Functionality implied by ID_AA64ISAR0_EL1.TS == 0b0001.
HWCAP_SSBS
-
Functionality implied by ID_AA64PFR1_EL1.SSBS == 0b0010.
HWCAP_PACA
-
Functionality implied by ID_AA64ISAR1_EL1.APA == 0b0001 or
ID_AA64ISAR1_EL1.API == 0b0001, as described by
Documentation/arm64/pointer-authentication.txt.
HWCAP_PACG
-
Functionality implied by ID_AA64ISAR1_EL1.GPA == 0b0001 or
ID_AA64ISAR1_EL1.GPI == 0b0001, as described by
Documentation/arm64/pointer-authentication.txt.
diff --git a/Documentation/arm64/hugetlbpage.txt b/Documentation/arm64/hugetlbpage.txt
index cfae87dc653b..b44f939e5210 100644
--- a/Documentation/arm64/hugetlbpage.txt
+++ b/Documentation/arm64/hugetlbpage.txt
@@ -1,3 +1,4 @@
+====================
HugeTLBpage on ARM64
====================
@@ -31,8 +32,10 @@ and level of the page table.
The following hugepage sizes are supported -
- CONT PTE PMD CONT PMD PUD
- -------- --- -------- ---
+ ====== ======== ==== ======== ===
+ - CONT PTE PMD CONT PMD PUD
+ ====== ======== ==== ======== ===
4K: 64K 2M 32M 1G
16K: 2M 32M 1G
64K: 2M 512M 16G
+ ====== ======== ==== ======== ===
diff --git a/Documentation/arm64/legacy_instructions.txt b/Documentation/arm64/legacy_instructions.txt
index 01bf3d9fac85..54401b22cb8f 100644
--- a/Documentation/arm64/legacy_instructions.txt
+++ b/Documentation/arm64/legacy_instructions.txt
@@ -1,3 +1,7 @@
+===================
+Legacy instructions
+===================
+
The arm64 port of the Linux kernel provides infrastructure to support
emulation of instructions which have been deprecated, or obsoleted in
the architecture. The infrastructure code uses undefined instruction
@@ -9,19 +13,22 @@ The emulation mode can be controlled by writing to sysctl nodes
behaviours and the corresponding values of the sysctl nodes -
* Undef
- Value: 0
+ Value: 0
+
Generates undefined instruction abort. Default for instructions that
have been obsoleted in the architecture, e.g., SWP
* Emulate
- Value: 1
+ Value: 1
+
Uses software emulation. To aid migration of software, in this mode
usage of emulated instruction is traced as well as rate limited
warnings are issued. This is the default for deprecated
instructions, .e.g., CP15 barriers
* Hardware Execution
- Value: 2
+ Value: 2
+
Although marked as deprecated, some implementations may support the
enabling/disabling of hardware support for the execution of these
instructions. Using hardware execution generally provides better
@@ -38,20 +45,24 @@ individual instruction notes for further information.
Supported legacy instructions
-----------------------------
* SWP{B}
-Node: /proc/sys/abi/swp
-Status: Obsolete
-Default: Undef (0)
+
+:Node: /proc/sys/abi/swp
+:Status: Obsolete
+:Default: Undef (0)
* CP15 Barriers
-Node: /proc/sys/abi/cp15_barrier
-Status: Deprecated
-Default: Emulate (1)
+
+:Node: /proc/sys/abi/cp15_barrier
+:Status: Deprecated
+:Default: Emulate (1)
* SETEND
-Node: /proc/sys/abi/setend
-Status: Deprecated
-Default: Emulate (1)*
-Note: All the cpus on the system must have mixed endian support at EL0
-for this feature to be enabled. If a new CPU - which doesn't support mixed
-endian - is hotplugged in after this feature has been enabled, there could
-be unexpected results in the application.
+
+:Node: /proc/sys/abi/setend
+:Status: Deprecated
+:Default: Emulate (1)*
+
+ Note: All the cpus on the system must have mixed endian support at EL0
+ for this feature to be enabled. If a new CPU - which doesn't support mixed
+ endian - is hotplugged in after this feature has been enabled, there could
+ be unexpected results in the application.
diff --git a/Documentation/arm64/memory.txt b/Documentation/arm64/memory.txt
index c5dab30d3389..464b880fc4b7 100644
--- a/Documentation/arm64/memory.txt
+++ b/Documentation/arm64/memory.txt
@@ -1,5 +1,6 @@
- Memory Layout on AArch64 Linux
- ==============================
+==============================
+Memory Layout on AArch64 Linux
+==============================
Author: Catalin Marinas <catalin.marinas@arm.com>
@@ -21,69 +22,69 @@ The swapper_pg_dir address is written to TTBR1 and never written to
TTBR0.
-AArch64 Linux memory layout with 4KB pages + 3 levels:
+AArch64 Linux memory layout with 4KB pages + 3 levels::
-Start End Size Use
------------------------------------------------------------------------
-0000000000000000 0000007fffffffff 512GB user
-ffffff8000000000 ffffffffffffffff 512GB kernel
+ Start End Size Use
+ -----------------------------------------------------------------------
+ 0000000000000000 0000007fffffffff 512GB user
+ ffffff8000000000 ffffffffffffffff 512GB kernel
-AArch64 Linux memory layout with 4KB pages + 4 levels:
+AArch64 Linux memory layout with 4KB pages + 4 levels::
-Start End Size Use
------------------------------------------------------------------------
-0000000000000000 0000ffffffffffff 256TB user
-ffff000000000000 ffffffffffffffff 256TB kernel
+ Start End Size Use
+ -----------------------------------------------------------------------
+ 0000000000000000 0000ffffffffffff 256TB user
+ ffff000000000000 ffffffffffffffff 256TB kernel
-AArch64 Linux memory layout with 64KB pages + 2 levels:
+AArch64 Linux memory layout with 64KB pages + 2 levels::
-Start End Size Use
------------------------------------------------------------------------
-0000000000000000 000003ffffffffff 4TB user
-fffffc0000000000 ffffffffffffffff 4TB kernel
+ Start End Size Use
+ -----------------------------------------------------------------------
+ 0000000000000000 000003ffffffffff 4TB user
+ fffffc0000000000 ffffffffffffffff 4TB kernel
-AArch64 Linux memory layout with 64KB pages + 3 levels:
+AArch64 Linux memory layout with 64KB pages + 3 levels::
-Start End Size Use
------------------------------------------------------------------------
-0000000000000000 0000ffffffffffff 256TB user
-ffff000000000000 ffffffffffffffff 256TB kernel
+ Start End Size Use
+ -----------------------------------------------------------------------
+ 0000000000000000 0000ffffffffffff 256TB user
+ ffff000000000000 ffffffffffffffff 256TB kernel
For details of the virtual kernel memory layout please see the kernel
booting log.
-Translation table lookup with 4KB pages:
+Translation table lookup with 4KB pages::
-+--------+--------+--------+--------+--------+--------+--------+--------+
-|63 56|55 48|47 40|39 32|31 24|23 16|15 8|7 0|
-+--------+--------+--------+--------+--------+--------+--------+--------+
- | | | | | |
- | | | | | v
- | | | | | [11:0] in-page offset
- | | | | +-> [20:12] L3 index
- | | | +-----------> [29:21] L2 index
- | | +---------------------> [38:30] L1 index
- | +-------------------------------> [47:39] L0 index
- +-------------------------------------------------> [63] TTBR0/1
+ +--------+--------+--------+--------+--------+--------+--------+--------+
+ |63 56|55 48|47 40|39 32|31 24|23 16|15 8|7 0|
+ +--------+--------+--------+--------+--------+--------+--------+--------+
+ | | | | | |
+ | | | | | v
+ | | | | | [11:0] in-page offset
+ | | | | +-> [20:12] L3 index
+ | | | +-----------> [29:21] L2 index
+ | | +---------------------> [38:30] L1 index
+ | +-------------------------------> [47:39] L0 index
+ +-------------------------------------------------> [63] TTBR0/1
-Translation table lookup with 64KB pages:
+Translation table lookup with 64KB pages::
-+--------+--------+--------+--------+--------+--------+--------+--------+
-|63 56|55 48|47 40|39 32|31 24|23 16|15 8|7 0|
-+--------+--------+--------+--------+--------+--------+--------+--------+
- | | | | |
- | | | | v
- | | | | [15:0] in-page offset
- | | | +----------> [28:16] L3 index
- | | +--------------------------> [41:29] L2 index
- | +-------------------------------> [47:42] L1 index
- +-------------------------------------------------> [63] TTBR0/1
+ +--------+--------+--------+--------+--------+--------+--------+--------+
+ |63 56|55 48|47 40|39 32|31 24|23 16|15 8|7 0|
+ +--------+--------+--------+--------+--------+--------+--------+--------+
+ | | | | |
+ | | | | v
+ | | | | [15:0] in-page offset
+ | | | +----------> [28:16] L3 index
+ | | +--------------------------> [41:29] L2 index
+ | +-------------------------------> [47:42] L1 index
+ +-------------------------------------------------> [63] TTBR0/1
When using KVM without the Virtualization Host Extensions, the
diff --git a/Documentation/arm64/pointer-authentication.txt b/Documentation/arm64/pointer-authentication.txt
index 5baca42ba146..f8b9af8b6490 100644
--- a/Documentation/arm64/pointer-authentication.txt
+++ b/Documentation/arm64/pointer-authentication.txt
@@ -1,7 +1,9 @@
+=======================================
Pointer authentication in AArch64 Linux
=======================================
Author: Mark Rutland <mark.rutland@arm.com>
+
Date: 2017-07-19
This document briefly describes the provision of pointer authentication
diff --git a/Documentation/arm64/silicon-errata.txt b/Documentation/arm64/silicon-errata.txt
index c00efb639e46..926b2ef62cd2 100644
--- a/Documentation/arm64/silicon-errata.txt
+++ b/Documentation/arm64/silicon-errata.txt
@@ -1,7 +1,9 @@
- Silicon Errata and Software Workarounds
- =======================================
+=======================================
+Silicon Errata and Software Workarounds
+=======================================
Author: Will Deacon <will.deacon@arm.com>
+
Date : 27 November 2015
It is an unfortunate fact of life that hardware is often produced with
@@ -9,11 +11,13 @@ so-called "errata", which can cause it to deviate from the architecture
under specific circumstances. For hardware produced by ARM, these
errata are broadly classified into the following categories:
- Category A: A critical error without a viable workaround.
- Category B: A significant or critical error with an acceptable
+ ========== ========================================================
+ Category A A critical error without a viable workaround.
+ Category B A significant or critical error with an acceptable
workaround.
- Category C: A minor error that is not expected to occur under normal
+ Category C A minor error that is not expected to occur under normal
operation.
+ ========== ========================================================
For more information, consult one of the "Software Developers Errata
Notice" documents available on infocenter.arm.com (registration
@@ -42,45 +46,82 @@ file acts as a registry of software workarounds in the Linux Kernel and
will be updated when new workarounds are committed and backported to
stable kernels.
++----------------+-----------------+-----------------+-----------------------------+
| Implementor | Component | Erratum ID | Kconfig |
-+----------------+-----------------+-----------------+-----------------------------+
++================+=================+=================+=============================+
| Allwinner | A64/R18 | UNKNOWN1 | SUN50I_ERRATUM_UNKNOWN1 |
-| | | | |
++----------------+-----------------+-----------------+-----------------------------+
++----------------+-----------------+-----------------+-----------------------------+
| ARM | Cortex-A53 | #826319 | ARM64_ERRATUM_826319 |
++----------------+-----------------+-----------------+-----------------------------+
| ARM | Cortex-A53 | #827319 | ARM64_ERRATUM_827319 |
++----------------+-----------------+-----------------+-----------------------------+
| ARM | Cortex-A53 | #824069 | ARM64_ERRATUM_824069 |
++----------------+-----------------+-----------------+-----------------------------+
| ARM | Cortex-A53 | #819472 | ARM64_ERRATUM_819472 |
++----------------+-----------------+-----------------+-----------------------------+
| ARM | Cortex-A53 | #845719 | ARM64_ERRATUM_845719 |
++----------------+-----------------+-----------------+-----------------------------+
| ARM | Cortex-A53 | #843419 | ARM64_ERRATUM_843419 |
++----------------+-----------------+-----------------+-----------------------------+
| ARM | Cortex-A57 | #832075 | ARM64_ERRATUM_832075 |
++----------------+-----------------+-----------------+-----------------------------+
| ARM | Cortex-A57 | #852523 | N/A |
++----------------+-----------------+-----------------+-----------------------------+
| ARM | Cortex-A57 | #834220 | ARM64_ERRATUM_834220 |
++----------------+-----------------+-----------------+-----------------------------+
| ARM | Cortex-A72 | #853709 | N/A |
++----------------+-----------------+-----------------+-----------------------------+
| ARM | Cortex-A73 | #858921 | ARM64_ERRATUM_858921 |
++----------------+-----------------+-----------------+-----------------------------+
| ARM | Cortex-A55 | #1024718 | ARM64_ERRATUM_1024718 |
++----------------+-----------------+-----------------+-----------------------------+
| ARM | Cortex-A76 | #1188873 | ARM64_ERRATUM_1188873 |
++----------------+-----------------+-----------------+-----------------------------+
| ARM | Cortex-A76 | #1165522 | ARM64_ERRATUM_1165522 |
++----------------+-----------------+-----------------+-----------------------------+
| ARM | Cortex-A76 | #1286807 | ARM64_ERRATUM_1286807 |
++----------------+-----------------+-----------------+-----------------------------+
| ARM | MMU-500 | #841119,#826419 | N/A |
-| | | | |
++----------------+-----------------+-----------------+-----------------------------+
++----------------+-----------------+-----------------+-----------------------------+
| Cavium | ThunderX ITS | #22375, #24313 | CAVIUM_ERRATUM_22375 |
++----------------+-----------------+-----------------+-----------------------------+
| Cavium | ThunderX ITS | #23144 | CAVIUM_ERRATUM_23144 |
++----------------+-----------------+-----------------+-----------------------------+
| Cavium | ThunderX GICv3 | #23154 | CAVIUM_ERRATUM_23154 |
++----------------+-----------------+-----------------+-----------------------------+
| Cavium | ThunderX Core | #27456 | CAVIUM_ERRATUM_27456 |
++----------------+-----------------+-----------------+-----------------------------+
| Cavium | ThunderX Core | #30115 | CAVIUM_ERRATUM_30115 |
++----------------+-----------------+-----------------+-----------------------------+
| Cavium | ThunderX SMMUv2 | #27704 | N/A |
++----------------+-----------------+-----------------+-----------------------------+
| Cavium | ThunderX2 SMMUv3| #74 | N/A |
++----------------+-----------------+-----------------+-----------------------------+
| Cavium | ThunderX2 SMMUv3| #126 | N/A |
-| | | | |
++----------------+-----------------+-----------------+-----------------------------+
++----------------+-----------------+-----------------+-----------------------------+
| Freescale/NXP | LS2080A/LS1043A | A-008585 | FSL_ERRATUM_A008585 |
-| | | | |
++----------------+-----------------+-----------------+-----------------------------+
++----------------+-----------------+-----------------+-----------------------------+
| Hisilicon | Hip0{5,6,7} | #161010101 | HISILICON_ERRATUM_161010101 |
++----------------+-----------------+-----------------+-----------------------------+
| Hisilicon | Hip0{6,7} | #161010701 | N/A |
++----------------+-----------------+-----------------+-----------------------------+
| Hisilicon | Hip07 | #161600802 | HISILICON_ERRATUM_161600802 |
++----------------+-----------------+-----------------+-----------------------------+
| Hisilicon | Hip08 SMMU PMCG | #162001800 | N/A |
-| | | | |
++----------------+-----------------+-----------------+-----------------------------+
++----------------+-----------------+-----------------+-----------------------------+
| Qualcomm Tech. | Kryo/Falkor v1 | E1003 | QCOM_FALKOR_ERRATUM_1003 |
++----------------+-----------------+-----------------+-----------------------------+
| Qualcomm Tech. | Falkor v1 | E1009 | QCOM_FALKOR_ERRATUM_1009 |
++----------------+-----------------+-----------------+-----------------------------+
| Qualcomm Tech. | QDF2400 ITS | E0065 | QCOM_QDF2400_ERRATUM_0065 |
++----------------+-----------------+-----------------+-----------------------------+
| Qualcomm Tech. | Falkor v{1,2} | E1041 | QCOM_FALKOR_ERRATUM_1041 |
++----------------+-----------------+-----------------+-----------------------------+
++----------------+-----------------+-----------------+-----------------------------+
| Fujitsu | A64FX | E#010001 | FUJITSU_ERRATUM_010001 |
++----------------+-----------------+-----------------+-----------------------------+
diff --git a/Documentation/arm64/sve.txt b/Documentation/arm64/sve.txt
index 7169a0ec41d8..d73c8e04b22b 100644
--- a/Documentation/arm64/sve.txt
+++ b/Documentation/arm64/sve.txt
@@ -1,7 +1,9 @@
- Scalable Vector Extension support for AArch64 Linux
- ===================================================
+===================================================
+Scalable Vector Extension support for AArch64 Linux
+===================================================
Author: Dave Martin <Dave.Martin@arm.com>
+
Date: 4 August 2017
This document outlines briefly the interface provided to userspace by Linux in
@@ -409,7 +411,7 @@ In A64 state, SVE adds the following:
* FPSR and FPCR are retained from ARMv8-A, and interact with SVE floating-point
operations in a similar way to the way in which they interact with ARMv8
- floating-point operations.
+ floating-point operations::
8VL-1 128 0 bit index
+---- //// -----------------+
@@ -466,6 +468,8 @@ ARMv8-A defines the following floating-point / SIMD register state:
* 32 128-bit vector registers V0..V31
* 2 32-bit status/control registers FPSR, FPCR
+::
+
127 0 bit index
+---------------+
V0 | |
diff --git a/Documentation/arm64/tagged-pointers.txt b/Documentation/arm64/tagged-pointers.txt
index a25a99e82bb1..2acdec3ebbeb 100644
--- a/Documentation/arm64/tagged-pointers.txt
+++ b/Documentation/arm64/tagged-pointers.txt
@@ -1,7 +1,9 @@
- Tagged virtual addresses in AArch64 Linux
- =========================================
+=========================================
+Tagged virtual addresses in AArch64 Linux
+=========================================
Author: Will Deacon <will.deacon@arm.com>
+
Date : 12 June 2013
This document briefly describes the provision of tagged virtual
diff --git a/arch/arm64/kernel/kexec_image.c b/arch/arm64/kernel/kexec_image.c
index 07bf740bea91..31cc2f423aa8 100644
--- a/arch/arm64/kernel/kexec_image.c
+++ b/arch/arm64/kernel/kexec_image.c
@@ -53,7 +53,7 @@ static void *image_load(struct kimage *image,
/*
* We require a kernel with an unambiguous Image header. Per
- * Documentation/booting.txt, this is the case when image_size
+ * Documentation/arm64/booting.txt, this is the case when image_size
* is non-zero (practically speaking, since v3.17).
*/
h = (struct arm64_image_header *)kernel;
--
2.20.1
^ permalink raw reply related [flat|nested] 81+ messages in thread* [PATCH 06/57] docs: cdrom: convert remaining files to ReST
2019-04-16 2:55 [PATCH 00/57] Convert files to ReST Mauro Carvalho Chehab
` (3 preceding siblings ...)
2019-04-16 2:55 ` [PATCH 04/57] docs: arm64: convert documentation to ReST format Mauro Carvalho Chehab
@ 2019-04-16 2:55 ` Mauro Carvalho Chehab
2019-04-16 2:55 ` [PATCH 08/57] docs: cgroup-v1/blkio-controller.rst: add a note about CFQ scheduler Mauro Carvalho Chehab
` (47 subsequent siblings)
52 siblings, 0 replies; 81+ messages in thread
From: Mauro Carvalho Chehab @ 2019-04-16 2:55 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Jens Axboe
The stuff there is almost already at ReST format. A
conversion for them is trivial: just add a missing titles
and fix some scape codes for them to match ReST syntax.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
Documentation/cdrom/ide-cd | 178 +++++++++++++------------
Documentation/cdrom/packet-writing.txt | 27 ++--
2 files changed, 108 insertions(+), 97 deletions(-)
diff --git a/Documentation/cdrom/ide-cd b/Documentation/cdrom/ide-cd
index a5f2a7f1ff46..dadc94ef6b6c 100644
--- a/Documentation/cdrom/ide-cd
+++ b/Documentation/cdrom/ide-cd
@@ -1,18 +1,20 @@
IDE-CD driver documentation
-Originally by scott snyder <snyder@fnald0.fnal.gov> (19 May 1996)
-Carrying on the torch is: Erik Andersen <andersee@debian.org>
-New maintainers (19 Oct 1998): Jens Axboe <axboe@image.dk>
+===========================
+
+:Originally by: scott snyder <snyder@fnald0.fnal.gov> (19 May 1996)
+:Carrying on the torch is: Erik Andersen <andersee@debian.org>
+:New maintainers (19 Oct 1998): Jens Axboe <axboe@image.dk>
1. Introduction
---------------
-The ide-cd driver should work with all ATAPI ver 1.2 to ATAPI 2.6 compliant
+The ide-cd driver should work with all ATAPI ver 1.2 to ATAPI 2.6 compliant
CDROM drives which attach to an IDE interface. Note that some CDROM vendors
(including Mitsumi, Sony, Creative, Aztech, and Goldstar) have made
both ATAPI-compliant drives and drives which use a proprietary
interface. If your drive uses one of those proprietary interfaces,
this driver will not work with it (but one of the other CDROM drivers
-probably will). This driver will not work with `ATAPI' drives which
+probably will). This driver will not work with `ATAPI` drives which
attach to the parallel port. In addition, there is at least one drive
(CyCDROM CR520ie) which attaches to the IDE port but is not ATAPI;
this driver will not work with drives like that either (but see the
@@ -31,7 +33,7 @@ This driver provides the following features:
from audio tracks. The program cdda2wav can be used for this.
Note, however, that only some drives actually support this.
- - There is now support for CDROM changers which comply with the
+ - There is now support for CDROM changers which comply with the
ATAPI 2.6 draft standard (such as the NEC CDR-251). This additional
functionality includes a function call to query which slot is the
currently selected slot, a function call to query which slots contain
@@ -49,11 +51,11 @@ This driver provides the following features:
driver.
1. Make sure that the ide and ide-cd drivers are compiled into the
- kernel you're using. When configuring the kernel, in the section
- entitled "Floppy, IDE, and other block devices", say either `Y'
- (which will compile the support directly into the kernel) or `M'
+ kernel you're using. When configuring the kernel, in the section
+ entitled "Floppy, IDE, and other block devices", say either `Y`
+ (which will compile the support directly into the kernel) or `M`
(to compile support as a module which can be loaded and unloaded)
- to the options:
+ to the options::
ATA/ATAPI/MFM/RLL support
Include IDE/ATAPI CDROM support
@@ -72,35 +74,35 @@ This driver provides the following features:
address and an IRQ number, the standard assignments being
0x1f0 and 14 for the primary interface and 0x170 and 15 for the
secondary interface. Each interface can control up to two devices,
- where each device can be a hard drive, a CDROM drive, a floppy drive,
- or a tape drive. The two devices on an interface are called `master'
- and `slave'; this is usually selectable via a jumper on the drive.
+ where each device can be a hard drive, a CDROM drive, a floppy drive,
+ or a tape drive. The two devices on an interface are called `master`
+ and `slave`; this is usually selectable via a jumper on the drive.
Linux names these devices as follows. The master and slave devices
- on the primary IDE interface are called `hda' and `hdb',
+ on the primary IDE interface are called `hda` and `hdb`,
respectively. The drives on the secondary interface are called
- `hdc' and `hdd'. (Interfaces at other locations get other letters
+ `hdc` and `hdd`. (Interfaces at other locations get other letters
in the third position; see Documentation/ide/ide.txt.)
If you want your CDROM drive to be found automatically by the
driver, you should make sure your IDE interface uses either the
primary or secondary addresses mentioned above. In addition, if
the CDROM drive is the only device on the IDE interface, it should
- be jumpered as `master'. (If for some reason you cannot configure
+ be jumpered as `master`. (If for some reason you cannot configure
your system in this manner, you can probably still use the driver.
You may have to pass extra configuration information to the kernel
when you boot, however. See Documentation/ide/ide.txt for more
information.)
4. Boot the system. If the drive is recognized, you should see a
- message which looks like
+ message which looks like::
hdb: NEC CD-ROM DRIVE:260, ATAPI CDROM drive
If you do not see this, see section 5 below.
5. You may want to create a symbolic link /dev/cdrom pointing to the
- actual device. You can do this with the command
+ actual device. You can do this with the command::
ln -s /dev/hdX /dev/cdrom
@@ -108,14 +110,14 @@ This driver provides the following features:
drive is installed.
6. You should be able to see any error messages from the driver with
- the `dmesg' command.
+ the `dmesg` command.
3. Basic usage
--------------
-An ISO 9660 CDROM can be mounted by putting the disc in the drive and
-typing (as root)
+An ISO 9660 CDROM can be mounted by putting the disc in the drive and
+typing (as root)::
mount -t iso9660 /dev/cdrom /mnt/cdrom
@@ -123,7 +125,7 @@ where it is assumed that /dev/cdrom is a link pointing to the actual
device (as described in step 5 of the last section) and /mnt/cdrom is
an empty directory. You should now be able to see the contents of the
CDROM under the /mnt/cdrom directory. If you want to eject the CDROM,
-you must first dismount it with a command like
+you must first dismount it with a command like::
umount /mnt/cdrom
@@ -148,7 +150,7 @@ such as cdda2wav. The only types of drive which I've heard support
this are Sony and Toshiba drives. You will get errors if you try to
use this function on a drive which does not support it.
-For supported changers, you can use the `cdchange' program (appended to
+For supported changers, you can use the `cdchange` program (appended to
the end of this file) to switch between changer slots. Note that the
drive should be unmounted before attempting this. The program takes
two arguments: the CDROM device, and the slot number to which you wish
@@ -165,7 +167,7 @@ Documentation/ide/ide.txt for current information about the underlying
IDE support code. Some of these items apply only to earlier versions
of the driver, but are mentioned here for completeness.
-In most cases, you should probably check with `dmesg' for any errors
+In most cases, you should probably check with `dmesg` for any errors
from the driver.
a. Drive is not detected during booting.
@@ -184,9 +186,9 @@ a. Drive is not detected during booting.
- If the autoprobing is not finding your drive, you can tell the
driver to assume that one exists by using a lilo option of the
- form `hdX=cdrom', where X is the drive letter corresponding to
- where your drive is installed. Note that if you do this and you
- see a boot message like
+ form `hdX=cdrom`, where X is the drive letter corresponding to
+ where your drive is installed. Note that if you do this and you
+ see a boot message like::
hdX: ATAPI cdrom (?)
@@ -220,7 +222,7 @@ b. Timeout/IRQ errors.
probably not making it to the host.
- IRQ problems may also be indicated by the message
- `IRQ probe failed (<n>)' while booting. If <n> is zero, that
+ `IRQ probe failed (<n>)` while booting. If <n> is zero, that
means that the system did not see an interrupt from the drive when
it was expecting one (on any feasible IRQ). If <n> is negative,
that means the system saw interrupts on multiple IRQ lines, when
@@ -240,27 +242,27 @@ b. Timeout/IRQ errors.
there are hardware problems with the interrupt setup; they
apparently don't use interrupts.
- - If you own a Pioneer DR-A24X, you _will_ get nasty error messages
+ - If you own a Pioneer DR-A24X, you _will_ get nasty error messages
on boot such as "irq timeout: status=0x50 { DriveReady SeekComplete }"
The Pioneer DR-A24X CDROM drives are fairly popular these days.
Unfortunately, these drives seem to become very confused when we perform
the standard Linux ATA disk drive probe. If you own one of these drives,
- you can bypass the ATA probing which confuses these CDROM drives, by
- adding `append="hdX=noprobe hdX=cdrom"' to your lilo.conf file and running
- lilo (again where X is the drive letter corresponding to where your drive
+ you can bypass the ATA probing which confuses these CDROM drives, by
+ adding `append="hdX=noprobe hdX=cdrom"` to your lilo.conf file and running
+ lilo (again where X is the drive letter corresponding to where your drive
is installed.)
-
+
c. System hangups.
- If the system locks up when you try to access the CDROM, the most
likely cause is that you have a buggy IDE adapter which doesn't
properly handle simultaneous transactions on multiple interfaces.
The most notorious of these is the CMD640B chip. This problem can
- be worked around by specifying the `serialize' option when
+ be worked around by specifying the `serialize` option when
booting. Recent kernels should be able to detect the need for
this automatically in most cases, but the detection is not
foolproof. See Documentation/ide/ide.txt for more information
- about the `serialize' option and the CMD640B.
+ about the `serialize` option and the CMD640B.
- Note that many MS-DOS CDROM drivers will work with such buggy
hardware, apparently because they never attempt to overlap CDROM
@@ -269,14 +271,14 @@ c. System hangups.
d. Can't mount a CDROM.
- - If you get errors from mount, it may help to check `dmesg' to see
+ - If you get errors from mount, it may help to check `dmesg` to see
if there are any more specific errors from the driver or from the
filesystem.
- Make sure there's a CDROM loaded in the drive, and that's it's an
ISO 9660 disc. You can't mount an audio CD.
- - With the CDROM in the drive and unmounted, try something like
+ - With the CDROM in the drive and unmounted, try something like::
cat /dev/cdrom | od | more
@@ -284,9 +286,9 @@ d. Can't mount a CDROM.
OK, and the problem is at the filesystem level (i.e., the CDROM is
not ISO 9660 or has errors in the filesystem structure).
- - If you see `not a block device' errors, check that the definitions
+ - If you see `not a block device` errors, check that the definitions
of the device special files are correct. They should be as
- follows:
+ follows::
brw-rw---- 1 root disk 3, 0 Nov 11 18:48 /dev/hda
brw-rw---- 1 root disk 3, 64 Nov 11 18:48 /dev/hdb
@@ -301,7 +303,7 @@ d. Can't mount a CDROM.
If you have a /dev/cdrom symbolic link, check that it is pointing
to the correct device file.
- If you hear people talking of the devices `hd1a' and `hd1b', these
+ If you hear people talking of the devices `hd1a` and `hd1b`, these
were old names for what are now called hdc and hdd. Those names
should be considered obsolete.
@@ -311,8 +313,8 @@ d. Can't mount a CDROM.
always give meaningful error messages.
-e. Directory listings are unpredictably truncated, and `dmesg' shows
- `buffer botch' error messages from the driver.
+e. Directory listings are unpredictably truncated, and `dmesg` shows
+ `buffer botch` error messages from the driver.
- There was a bug in the version of the driver in 1.2.x kernels
which could cause this. It was fixed in 1.3.0. If you can't
@@ -335,34 +337,36 @@ f. Data corruption.
5. cdchange.c
-------------
-/*
- * cdchange.c [-v] <device> [<slot>]
- *
- * This loads a CDROM from a specified slot in a changer, and displays
- * information about the changer status. The drive should be unmounted before
- * using this program.
- *
- * Changer information is displayed if either the -v flag is specified
- * or no slot was specified.
- *
- * Based on code originally from Gerhard Zuber <zuber@berlin.snafu.de>.
- * Changer status information, and rewrite for the new Uniform CDROM driver
- * interface by Erik Andersen <andersee@debian.org>.
- */
+::
-#include <stdio.h>
-#include <stdlib.h>
-#include <errno.h>
-#include <string.h>
-#include <unistd.h>
-#include <fcntl.h>
-#include <sys/ioctl.h>
-#include <linux/cdrom.h>
+ /*
+ * cdchange.c [-v] <device> [<slot>]
+ *
+ * This loads a CDROM from a specified slot in a changer, and displays
+ * information about the changer status. The drive should be unmounted before
+ * using this program.
+ *
+ * Changer information is displayed if either the -v flag is specified
+ * or no slot was specified.
+ *
+ * Based on code originally from Gerhard Zuber <zuber@berlin.snafu.de>.
+ * Changer status information, and rewrite for the new Uniform CDROM driver
+ * interface by Erik Andersen <andersee@debian.org>.
+ */
+ #include <stdio.h>
+ #include <stdlib.h>
+ #include <errno.h>
+ #include <string.h>
+ #include <unistd.h>
+ #include <fcntl.h>
+ #include <sys/ioctl.h>
+ #include <linux/cdrom.h>
-int
-main (int argc, char **argv)
-{
+
+ int
+ main (int argc, char **argv)
+ {
char *program;
char *device;
int fd; /* file descriptor for CD-ROM device */
@@ -382,30 +386,30 @@ main (int argc, char **argv)
fprintf (stderr, " Slots are numbered 1 -- n.\n");
exit (1);
}
-
+
if (strcmp (argv[0], "-v") == 0) {
verbose = 1;
++argv;
--argc;
}
-
+
device = argv[0];
-
+
if (argc == 2)
slot = atoi (argv[1]) - 1;
- /* open device */
+ /* open device */
fd = open(device, O_RDONLY | O_NONBLOCK);
if (fd < 0) {
- fprintf (stderr, "%s: open failed for `%s': %s\n",
+ fprintf (stderr, "%s: open failed for `%s`: %s\n",
program, device, strerror (errno));
exit (1);
}
- /* Check CD player status */
+ /* Check CD player status */
total_slots_available = ioctl (fd, CDROM_CHANGER_NSLOTS);
if (total_slots_available <= 1 ) {
- fprintf (stderr, "%s: Device `%s' is not an ATAPI "
+ fprintf (stderr, "%s: Device `%s` is not an ATAPI "
"compliant CD changer.\n", program, device);
exit (1);
}
@@ -418,7 +422,7 @@ main (int argc, char **argv)
exit (1);
}
- /* load */
+ /* load */
slot=ioctl (fd, CDROM_SELECT_DISC, slot);
if (slot<0) {
fflush(stdout);
@@ -462,14 +466,14 @@ main (int argc, char **argv)
for (x_slot=0; x_slot<total_slots_available; x_slot++) {
printf ("Slot %2d: ", x_slot+1);
- status = ioctl (fd, CDROM_DRIVE_STATUS, x_slot);
- if (status<0) {
- perror(" CDROM_DRIVE_STATUS");
- } else switch(status) {
+ status = ioctl (fd, CDROM_DRIVE_STATUS, x_slot);
+ if (status<0) {
+ perror(" CDROM_DRIVE_STATUS");
+ } else switch(status) {
case CDS_DISC_OK:
printf ("Disc present.");
break;
- case CDS_NO_DISC:
+ case CDS_NO_DISC:
printf ("Empty slot.");
break;
case CDS_TRAY_OPEN:
@@ -507,11 +511,11 @@ main (int argc, char **argv)
break;
}
}
- status = ioctl (fd, CDROM_MEDIA_CHANGED, x_slot);
- if (status<0) {
+ status = ioctl (fd, CDROM_MEDIA_CHANGED, x_slot);
+ if (status<0) {
perror(" CDROM_MEDIA_CHANGED");
- }
- switch (status) {
+ }
+ switch (status) {
case 1:
printf ("Changed.\n");
break;
@@ -525,10 +529,10 @@ main (int argc, char **argv)
/* close device */
status = close (fd);
if (status != 0) {
- fprintf (stderr, "%s: close failed for `%s': %s\n",
+ fprintf (stderr, "%s: close failed for `%s`: %s\n",
program, device, strerror (errno));
exit (1);
}
-
+
exit (0);
-}
+ }
diff --git a/Documentation/cdrom/packet-writing.txt b/Documentation/cdrom/packet-writing.txt
index 2834170d821e..c5c957195a5a 100644
--- a/Documentation/cdrom/packet-writing.txt
+++ b/Documentation/cdrom/packet-writing.txt
@@ -1,3 +1,7 @@
+==============
+Packet writing
+==============
+
Getting started quick
---------------------
@@ -10,13 +14,16 @@ Getting started quick
Download from http://sourceforge.net/projects/linux-udf/
- Grab a new CD-RW disc and format it (assuming CD-RW is hdc, substitute
- as appropriate):
+ as appropriate)::
+
# cdrwtool -d /dev/hdc -q
-- Setup your writer
+- Setup your writer::
+
# pktsetup dev_name /dev/hdc
-- Now you can mount /dev/pktcdvd/dev_name and copy files to it. Enjoy!
+- Now you can mount /dev/pktcdvd/dev_name and copy files to it. Enjoy::
+
# mount /dev/pktcdvd/dev_name /cdrom -t udf -o rw,noatime
@@ -25,11 +32,11 @@ Packet writing for DVD-RW media
DVD-RW discs can be written to much like CD-RW discs if they are in
the so called "restricted overwrite" mode. To put a disc in restricted
-overwrite mode, run:
+overwrite mode, run::
# dvd+rw-format /dev/hdc
-You can then use the disc the same way you would use a CD-RW disc:
+You can then use the disc the same way you would use a CD-RW disc::
# pktsetup dev_name /dev/hdc
# mount /dev/pktcdvd/dev_name /cdrom -t udf -o rw,noatime
@@ -41,7 +48,7 @@ Packet writing for DVD+RW media
According to the DVD+RW specification, a drive supporting DVD+RW discs
shall implement "true random writes with 2KB granularity", which means
that it should be possible to put any filesystem with a block size >=
-2KB on such a disc. For example, it should be possible to do:
+2KB on such a disc. For example, it should be possible to do::
# dvd+rw-format /dev/hdc (only needed if the disc has never
been formatted)
@@ -54,7 +61,7 @@ follow the specification, but suffer bad performance problems if the
writes are not 32KB aligned.
Both problems can be solved by using the pktcdvd driver, which always
-generates aligned writes.
+generates aligned writes::
# dvd+rw-format /dev/hdc
# pktsetup dev_name /dev/hdc
@@ -83,7 +90,7 @@ Notes
- Since the pktcdvd driver makes the disc appear as a regular block
device with a 2KB block size, you can put any filesystem you like on
- the disc. For example, run:
+ the disc. For example, run::
# /sbin/mke2fs /dev/pktcdvd/dev_name
@@ -97,7 +104,7 @@ Since Linux 2.6.20, the pktcdvd module has a sysfs interface
and can be controlled by it. For example the "pktcdvd" tool uses
this interface. (see http://tom.ist-im-web.de/download/pktcdvd )
-"pktcdvd" works similar to "pktsetup", e.g.:
+"pktcdvd" works similar to "pktsetup", e.g.::
# pktcdvd -a dev_name /dev/hdc
# mkudffs /dev/pktcdvd/dev_name
@@ -115,7 +122,7 @@ For a description of the sysfs interface look into the file:
Using the pktcdvd debugfs interface
-----------------------------------
-To read pktcdvd device infos in human readable form, do:
+To read pktcdvd device infos in human readable form, do::
# cat /sys/kernel/debug/pktcdvd/pktcdvd[0-7]/info
--
2.20.1
^ permalink raw reply related [flat|nested] 81+ messages in thread* [PATCH 08/57] docs: cgroup-v1/blkio-controller.rst: add a note about CFQ scheduler
2019-04-16 2:55 [PATCH 00/57] Convert files to ReST Mauro Carvalho Chehab
` (4 preceding siblings ...)
2019-04-16 2:55 ` [PATCH 06/57] docs: cdrom: convert remaining files to ReST Mauro Carvalho Chehab
@ 2019-04-16 2:55 ` Mauro Carvalho Chehab
2019-04-16 2:55 ` [PATCH 09/57] docs: cpu-freq: convert files to ReST Mauro Carvalho Chehab
` (46 subsequent siblings)
52 siblings, 0 replies; 81+ messages in thread
From: Mauro Carvalho Chehab @ 2019-04-16 2:55 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet
The CFQ scheduler was removed on this changeset:
commit f382fb0bcef4c37dc049e9f6963e3baf204d815c
Author: Jens Axboe <axboe@kernel.dk>
Date: Fri Oct 12 10:14:46 2018 -0600
block: remove legacy IO schedulers
Retain the deadline documentation, as that carries over to mq-deadline
as well.
Tested-by: Ming Lei <ming.lei@redhat.com>
Reviewed-by: Omar Sandoval <osandov@fb.com>
Signed-off-by: Jens Axboe <axboe@kernel.dk>
However, the cgroups-v1 documentation still mentions it and points
to a removed file that used to belong to such scheduler.
Add a note about that, as someone needs to fix the document pointing
to another scheduler, if cgroups-v1 blockio is not dependent of
CFQ scheduler.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
Documentation/cgroup-v1/blkio-controller.txt | 7 +++++++
1 file changed, 7 insertions(+)
diff --git a/Documentation/cgroup-v1/blkio-controller.txt b/Documentation/cgroup-v1/blkio-controller.txt
index 2c1b907afc14..2836c2c31e63 100644
--- a/Documentation/cgroup-v1/blkio-controller.txt
+++ b/Documentation/cgroup-v1/blkio-controller.txt
@@ -17,6 +17,13 @@ one is throttling policy which can be used to specify upper IO rate limits
on devices. This policy is implemented in generic block layer and can be
used on leaf nodes as well as higher level logical devices like device mapper.
+.. note::
+
+ While this document mentions the CFQ scheduler, it got removed at
+ Kernel 4.20, as there are other schedulers that are more efficient.
+
+ Someone needs to update this file in order to reflect such change.
+
HOWTO
=====
Proportional Weight division of bandwidth
--
2.20.1
^ permalink raw reply related [flat|nested] 81+ messages in thread* [PATCH 09/57] docs: cpu-freq: convert files to ReST
2019-04-16 2:55 [PATCH 00/57] Convert files to ReST Mauro Carvalho Chehab
` (5 preceding siblings ...)
2019-04-16 2:55 ` [PATCH 08/57] docs: cgroup-v1/blkio-controller.rst: add a note about CFQ scheduler Mauro Carvalho Chehab
@ 2019-04-16 2:55 ` Mauro Carvalho Chehab
2019-04-16 8:21 ` Rafael J. Wysocki
2019-04-16 2:55 ` [PATCH 11/57] docs: extcon: move it to acpi dir and convert it " Mauro Carvalho Chehab
` (45 subsequent siblings)
52 siblings, 1 reply; 81+ messages in thread
From: Mauro Carvalho Chehab @ 2019-04-16 2:55 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Rafael J. Wysocki, Viresh Kumar, linux-pm
In order to be able to build html and pdf files, convert the
documentation to ReST format.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
Documentation/cpu-freq/amd-powernow.txt | 11 +-
Documentation/cpu-freq/core.txt | 66 +++----
Documentation/cpu-freq/cpu-drivers.txt | 217 +++++++++++----------
Documentation/cpu-freq/cpufreq-nforce2.txt | 12 +-
Documentation/cpu-freq/cpufreq-stats.txt | 141 ++++++-------
Documentation/cpu-freq/pcc-cpufreq.txt | 102 +++++-----
6 files changed, 281 insertions(+), 268 deletions(-)
diff --git a/Documentation/cpu-freq/amd-powernow.txt b/Documentation/cpu-freq/amd-powernow.txt
index 254da155fa47..50b2c45c3a2c 100644
--- a/Documentation/cpu-freq/amd-powernow.txt
+++ b/Documentation/cpu-freq/amd-powernow.txt
@@ -1,3 +1,7 @@
+=============================
+AMD powernow driver specifics
+=============================
+
PowerNow! and Cool'n'Quiet are AMD names for frequency
management capabilities in AMD processors. As the hardware
@@ -23,16 +27,19 @@ not supply these tables.
7th Generation: powernow-k7: Athlon, Duron, Geode.
8th Generation: powernow-k8: Athlon, Athlon 64, Opteron, Sempron.
+
Documentation on this functionality in 8th generation processors
is available in the "BIOS and Kernel Developer's Guide", publication
-26094, in chapter 9, available for download from www.amd.com.
+26094, in chapter 9, available for download from www.amd.com.
BIOS supplied data, for powernow-k7 and for powernow-k8, may be
from either the PSB table or from ACPI objects. The ACPI support
is only available if the kernel config sets CONFIG_ACPI_PROCESSOR.
+
The powernow-k8 driver will attempt to use ACPI if so configured,
and fall back to PST if that fails.
+
The powernow-k7 driver will try to use the PSB support first, and
fall back to ACPI if the PSB support fails. A module parameter,
-acpi_force, is provided to force ACPI support to be used instead
+acpi_force, is provided to force ACPI support to be used instead
of PSB support.
diff --git a/Documentation/cpu-freq/core.txt b/Documentation/cpu-freq/core.txt
index 073f128af5a7..c719e3cb700c 100644
--- a/Documentation/cpu-freq/core.txt
+++ b/Documentation/cpu-freq/core.txt
@@ -1,31 +1,22 @@
- CPU frequency and voltage scaling code in the Linux(TM) kernel
+================================================================
+General description of the CPUFreq core and of CPUFreq notifiers
+================================================================
+Authors:
+ - Dominik Brodowski <linux@brodo.de>
+ - David Kimdon <dwhedon@debian.org>
+ - Rafael J. Wysocki <rafael.j.wysocki@intel.com>
+ - Viresh Kumar <viresh.kumar@linaro.org>
- L i n u x C P U F r e q
- C P U F r e q C o r e
+.. Contents:
-
- Dominik Brodowski <linux@brodo.de>
- David Kimdon <dwhedon@debian.org>
- Rafael J. Wysocki <rafael.j.wysocki@intel.com>
- Viresh Kumar <viresh.kumar@linaro.org>
-
-
-
- Clock scaling allows you to change the clock speed of the CPUs on the
- fly. This is a nice method to save battery power, because the lower
- the clock speed, the less power the CPU consumes.
-
-
-Contents:
----------
-1. CPUFreq core and interfaces
-2. CPUFreq notifiers
-3. CPUFreq Table Generation with Operating Performance Point (OPP)
+ 1. CPUFreq core and interfaces
+ 2. CPUFreq notifiers
+ 3. CPUFreq Table Generation with Operating Performance Point (OPP)
1. General Information
-=======================
+======================
The CPUFreq core code is located in drivers/cpufreq/cpufreq.c. This
cpufreq code offers a standardized interface for the CPUFreq
@@ -60,18 +51,18 @@ transition notifiers.
These are notified when a new policy is intended to be set. Each
CPUFreq policy notifier is called twice for a policy transition:
-1.) During CPUFREQ_ADJUST all CPUFreq notifiers may change the limit if
- they see a need for this - may it be thermal considerations or
- hardware limitations.
+1) During CPUFREQ_ADJUST all CPUFreq notifiers may change the limit if
+ they see a need for this - may it be thermal considerations or
+ hardware limitations.
-2.) And during CPUFREQ_NOTIFY all notifiers are informed of the new policy
- - if two hardware drivers failed to agree on a new policy before this
+2) And during CPUFREQ_NOTIFY all notifiers are informed of the new policy -
+ if two hardware drivers failed to agree on a new policy before this
stage, the incompatible hardware shall be shut down, and the user
informed of this.
The phase is specified in the second argument to the notifier.
-The third argument, a void *pointer, points to a struct cpufreq_policy
+The third argument, a `void *` pointer, points to a struct cpufreq_policy
consisting of several values, including min, max (the lower and upper
frequencies (in kHz) of the new policy).
@@ -88,23 +79,27 @@ CPUFREQ_POSTCHANGE.
The third argument is a struct cpufreq_freqs with the following
values:
-cpu - number of the affected CPU
-old - old frequency
-new - new frequency
-flags - flags of the cpufreq driver
+
+======= ===========================
+cpu number of the affected CPU
+old old frequency
+new new frequency
+flags flags of the cpufreq driver
+======= ===========================
3. CPUFreq Table Generation with Operating Performance Point (OPP)
==================================================================
For details about OPP, see Documentation/power/opp.txt
-dev_pm_opp_init_cpufreq_table -
+dev_pm_opp_init_cpufreq_table
This function provides a ready to use conversion routine to translate
the OPP layer's internal information about the available frequencies
into a format readily providable to cpufreq.
WARNING: Do not use this function in interrupt context.
- Example:
+ Example::
+
soc_pm_init()
{
/* Do things */
@@ -117,4 +112,5 @@ dev_pm_opp_init_cpufreq_table -
NOTE: This function is available only if CONFIG_CPU_FREQ is enabled in
addition to CONFIG_PM_OPP.
-dev_pm_opp_free_cpufreq_table - Free up the table allocated by dev_pm_opp_init_cpufreq_table
+dev_pm_opp_free_cpufreq_table
+ Free up the table allocated by dev_pm_opp_init_cpufreq_table
diff --git a/Documentation/cpu-freq/cpu-drivers.txt b/Documentation/cpu-freq/cpu-drivers.txt
index 6e353d00cdc6..9cc2559bc34b 100644
--- a/Documentation/cpu-freq/cpu-drivers.txt
+++ b/Documentation/cpu-freq/cpu-drivers.txt
@@ -1,35 +1,25 @@
- CPU frequency and voltage scaling code in the Linux(TM) kernel
-
-
- L i n u x C P U F r e q
-
- C P U D r i v e r s
-
- - information for developers -
-
-
- Dominik Brodowski <linux@brodo.de>
- Rafael J. Wysocki <rafael.j.wysocki@intel.com>
- Viresh Kumar <viresh.kumar@linaro.org>
-
-
-
- Clock scaling allows you to change the clock speed of the CPUs on the
- fly. This is a nice method to save battery power, because the lower
- the clock speed, the less power the CPU consumes.
-
-
-Contents:
----------
-1. What To Do?
-1.1 Initialization
-1.2 Per-CPU Initialization
-1.3 verify
-1.4 target/target_index or setpolicy?
-1.5 target/target_index
-1.6 setpolicy
-1.7 get_intermediate and target_intermediate
-2. Frequency Table Helpers
+===============================================
+How to implement a new cpufreq processor driver
+===============================================
+
+.. information for developers
+
+Authors:
+ - Dominik Brodowski <linux@brodo.de>
+ - Rafael J. Wysocki <rafael.j.wysocki@intel.com>
+ - Viresh Kumar <viresh.kumar@linaro.org>
+
+.. Contents:
+
+ 1. What To Do?
+ 1.1 Initialization
+ 1.2 Per-CPU Initialization
+ 1.3 verify
+ 1.4 target/target_index or setpolicy?
+ 1.5 target/target_index
+ 1.6 setpolicy
+ 1.7 get_intermediate and target_intermediate
+ 2. Frequency Table Helpers
@@ -46,59 +36,73 @@ on what is necessary:
First of all, in an __initcall level 7 (module_init()) or later
function check whether this kernel runs on the right CPU and the right
-chipset. If so, register a struct cpufreq_driver with the CPUfreq core
-using cpufreq_register_driver()
+chipset. If so, register a `struct cpufreq_driver` with the CPUfreq core
+using `cpufreq_register_driver()`
-What shall this struct cpufreq_driver contain?
+What shall this `struct cpufreq_driver` contain?
- .name - The name of this driver.
+.name
+ The name of this driver.
- .init - A pointer to the per-policy initialization function.
+.init
+ A pointer to the per-policy initialization function.
- .verify - A pointer to a "verification" function.
+.verify
+ A pointer to a "verification" function.
- .setpolicy _or_ .fast_switch _or_ .target _or_ .target_index - See
- below on the differences.
+.setpolicy **or** .fast_switch **or** .target **or** .target_index
+ See below on the differences.
And optionally
- .flags - Hints for the cpufreq core.
+.flags
+ Hints for the cpufreq core.
- .driver_data - cpufreq driver specific data.
+.driver_data
+ cpufreq driver specific data.
- .resolve_freq - Returns the most appropriate frequency for a target
- frequency. Doesn't change the frequency though.
+.resolve_freq
+ Returns the most appropriate frequency for a target
+ frequency. Doesn't change the frequency though.
- .get_intermediate and target_intermediate - Used to switch to stable
- frequency while changing CPU frequency.
+.get_intermediate and target_intermediate
+ Used to switch to stable frequency while changing CPU frequency.
- .get - Returns current frequency of the CPU.
+.get
+ Returns current frequency of the CPU.
- .bios_limit - Returns HW/BIOS max frequency limitations for the CPU.
+.bios_limit
+ Returns HW/BIOS max frequency limitations for the CPU.
- .exit - A pointer to a per-policy cleanup function called during
- CPU_POST_DEAD phase of cpu hotplug process.
+.exit
+ A pointer to a per-policy cleanup function called during
+ CPU_POST_DEAD phase of cpu hotplug process.
- .stop_cpu - A pointer to a per-policy stop function called during
- CPU_DOWN_PREPARE phase of cpu hotplug process.
+.stop_cpu
+ A pointer to a per-policy stop function called during
+ CPU_DOWN_PREPARE phase of cpu hotplug process.
- .suspend - A pointer to a per-policy suspend function which is called
- with interrupts disabled and _after_ the governor is stopped for the
- policy.
+.suspend
+ A pointer to a per-policy suspend function which is called with
+ interrupts disabled and **after** the governor is stopped for the policy.
- .resume - A pointer to a per-policy resume function which is called
- with interrupts disabled and _before_ the governor is started again.
+.resume
+ A pointer to a per-policy resume function which is called
+ with interrupts disabled and **before** the governor is started again.
- .ready - A pointer to a per-policy ready function which is called after
- the policy is fully initialized.
+.ready
+ A pointer to a per-policy ready function which is called after
+ the policy is fully initialized.
- .attr - A pointer to a NULL-terminated list of "struct freq_attr" which
- allow to export values to sysfs.
+.attr
+ A pointer to a NULL-terminated list of `struct freq_attr` which
+ allow to export values to sysfs.
- .boost_enabled - If set, boost frequencies are enabled.
+.boost_enabled
+ If set, boost frequencies are enabled.
- .set_boost - A pointer to a per-policy function to enable/disable boost
- frequencies.
+.set_boost
+ A pointer to a per-policy function to enable/disable boost frequencies.
1.2 Per-CPU Initialization
@@ -108,37 +112,42 @@ Whenever a new CPU is registered with the device model, or after the
cpufreq driver registers itself, the per-policy initialization function
cpufreq_driver.init is called if no cpufreq policy existed for the CPU.
Note that the .init() and .exit() routines are called only once for the
-policy and not for each CPU managed by the policy. It takes a struct
-cpufreq_policy *policy as argument. What to do now?
+policy and not for each CPU managed by the policy. It takes a `struct
+cpufreq_policy *policy` as argument. What to do now?
If necessary, activate the CPUfreq support on your CPU.
Then, the driver must fill in the following values:
-policy->cpuinfo.min_freq _and_
-policy->cpuinfo.max_freq - the minimum and maximum frequency
- (in kHz) which is supported by
- this CPU
-policy->cpuinfo.transition_latency the time it takes on this CPU to
- switch between two frequencies in
- nanoseconds (if appropriate, else
- specify CPUFREQ_ETERNAL)
-
-policy->cur The current operating frequency of
- this CPU (if appropriate)
-policy->min,
-policy->max,
-policy->policy and, if necessary,
-policy->governor must contain the "default policy" for
- this CPU. A few moments later,
- cpufreq_driver.verify and either
- cpufreq_driver.setpolicy or
- cpufreq_driver.target/target_index is called
- with these values.
-policy->cpus Update this with the masks of the
- (online + offline) CPUs that do DVFS
- along with this CPU (i.e. that share
- clock/voltage rails with it).
++---------------------------------------+--------------------------------------+
+| policy->cpuinfo.min_freq **and** | |
+| policy->cpuinfo.max_freq | the minimum and maximum frequency |
+| | (in kHz) which is supported by |
+| | this CPU |
++---------------------------------------+--------------------------------------+
+| policy->cpuinfo.transition_latency | the time it takes on this CPU to |
+| | switch between two frequencies in |
+| | nanoseconds (if appropriate, else |
+| | specify CPUFREQ_ETERNAL) |
++---------------------------------------+--------------------------------------+
+| policy->cur | The current operating frequency of |
+| | this CPU (if appropriate) |
++---------------------------------------+--------------------------------------+
+| policy->min, | |
+| policy->max, | |
+| policy->policy and, if necessary, | |
+| policy->governor | must contain the "default policy" |
+| | for this CPU. A few moments later, |
+| | cpufreq_driver.verify and either |
+| | cpufreq_driver.setpolicy or |
+| | cpufreq_driver.target/target_index |
+| | is called with these values. |
++---------------------------------------+--------------------------------------+
+| policy->cpus | Update this with the masks of the |
+| | (online + offline) CPUs that do DVFS |
+| | along with this CPU (i.e. that share |
+| | clock/voltage rails with it). |
++---------------------------------------+--------------------------------------+
For setting some of these values (cpuinfo.min[max]_freq, policy->min[max]), the
frequency table helpers might be helpful. See the section 2 for more information
@@ -151,8 +160,8 @@ on them.
When the user decides a new policy (consisting of
"policy,governor,min,max") shall be set, this policy must be validated
so that incompatible values can be corrected. For verifying these
-values cpufreq_verify_within_limits(struct cpufreq_policy *policy,
-unsigned int min_freq, unsigned int max_freq) function might be helpful.
+values `cpufreq_verify_within_limits(struct cpufreq_policy *policy,
+unsigned int min_freq, unsigned int max_freq)` function might be helpful.
See section 2 for details on frequency table helpers.
You need to make sure that at least one valid frequency (or operating
@@ -163,7 +172,7 @@ policy->max first, and only if this is no solution, decrease policy->min.
1.4 target or target_index or setpolicy or fast_switch?
-------------------------------------------------------
-Most cpufreq drivers or even most cpu frequency scaling algorithms
+Most cpufreq drivers or even most cpu frequency scaling algorithms
only allow the CPU frequency to be set to predefined fixed values. For
these, you use the ->target(), ->target_index() or ->fast_switch()
callbacks.
@@ -175,8 +184,8 @@ limits on their own. These shall use the ->setpolicy() callback.
1.5. target/target_index
------------------------
-The target_index call has two arguments: struct cpufreq_policy *policy,
-and unsigned int index (into the exposed frequency table).
+The target_index call has two arguments: `struct cpufreq_policy *policy`,
+and `unsigned int index` (into the exposed frequency table).
The CPUfreq driver must set the new frequency when called here. The
actual frequency must be determined by freq_table[index].frequency.
@@ -184,10 +193,10 @@ actual frequency must be determined by freq_table[index].frequency.
It should always restore to earlier frequency (i.e. policy->restore_freq) in
case of errors, even if we switched to intermediate frequency earlier.
-Deprecated:
+Deprecated
----------
-The target call has three arguments: struct cpufreq_policy *policy,
-unsigned int target_frequency, unsigned int relation.
+The target call has three arguments: `struct cpufreq_policy *policy`,
+`unsigned int target_frequency`, `unsigned int relation`.
The CPUfreq driver must set the new frequency when called here. The
actual frequency must be determined using the following rules:
@@ -210,14 +219,14 @@ Not all drivers are expected to implement it, as sleeping from within
this callback isn't allowed. This callback must be highly optimized to
do switching as fast as possible.
-This function has two arguments: struct cpufreq_policy *policy and
-unsigned int target_frequency.
+This function has two arguments: `struct cpufreq_policy *policy` and
+`unsigned int target_frequency`.
1.7 setpolicy
-------------
-The setpolicy call only takes a struct cpufreq_policy *policy as
+The setpolicy call only takes a `struct cpufreq_policy *policy` as
argument. You need to set the lower limit of the in-processor or
in-chipset dynamic frequency switching to policy->min, the upper limit
to policy->max, and -if supported- select a performance-oriented
@@ -278,10 +287,10 @@ table.
cpufreq_for_each_valid_entry(pos, table) - iterates over all entries,
excluding CPUFREQ_ENTRY_INVALID frequencies.
-Use arguments "pos" - a cpufreq_frequency_table * as a loop cursor and
-"table" - the cpufreq_frequency_table * you want to iterate over.
+Use arguments "pos" - a `cpufreq_frequency_table *` as a loop cursor and
+"table" - the `cpufreq_frequency_table *` you want to iterate over.
-For example:
+For example::
struct cpufreq_frequency_table *pos, *driver_freq_table;
diff --git a/Documentation/cpu-freq/cpufreq-nforce2.txt b/Documentation/cpu-freq/cpufreq-nforce2.txt
index babce1315026..d40700bd5083 100644
--- a/Documentation/cpu-freq/cpufreq-nforce2.txt
+++ b/Documentation/cpu-freq/cpufreq-nforce2.txt
@@ -1,3 +1,6 @@
+=================================
+nVidia nForce2 platform specifics
+=================================
The cpufreq-nforce2 driver changes the FSB on nVidia nForce2 platforms.
@@ -6,14 +9,15 @@ can be controlled independently from the PCI/AGP clock.
The module has two options:
+ ======== ======================================
fid: multiplier * 10 (for example 8.5 = 85)
min_fsb: minimum FSB
+ ======== ======================================
If not set, fid is calculated from the current CPU speed and the FSB.
min_fsb defaults to FSB at boot time - 50 MHz.
-IMPORTANT: The available range is limited downwards!
- Also the minimum available FSB can differ, for systems
+IMPORTANT:
+ The available range is limited downwards!
+ Also the minimum available FSB can differ, for systems
booting with 200 MHz, 150 should always work.
-
-
diff --git a/Documentation/cpu-freq/cpufreq-stats.txt b/Documentation/cpu-freq/cpufreq-stats.txt
index 14378cecb172..3e33712b496e 100644
--- a/Documentation/cpu-freq/cpufreq-stats.txt
+++ b/Documentation/cpu-freq/cpufreq-stats.txt
@@ -1,21 +1,20 @@
+==========================================
+General description of sysfs cpufreq stats
+==========================================
- CPU frequency and voltage scaling statistics in the Linux(TM) kernel
+.. information for users
- L i n u x c p u f r e q - s t a t s d r i v e r
+Author: Venkatesh Pallipadi <venkatesh.pallipadi@intel.com>
- - information for users -
-
-
- Venkatesh Pallipadi <venkatesh.pallipadi@intel.com>
-
-Contents
-1. Introduction
-2. Statistics Provided (with example)
-3. Configuring cpufreq-stats
+.. Contents
+ 1. Introduction
+ 2. Statistics Provided (with example)
+ 3. Configuring cpufreq-stats
1. Introduction
+===============
cpufreq-stats is a driver that provides CPU frequency statistics for each CPU.
These statistics are provided in /sysfs as a bunch of read_only interfaces. This
@@ -28,6 +27,7 @@ that may be running on your CPU. So, it will work with any cpufreq_driver.
2. Statistics Provided (with example)
+=====================================
cpufreq stats provides following statistics (explained in detail below).
- time_in_state
@@ -39,78 +39,79 @@ All the statistics will be from the time the stats driver has been inserted
statistic is done. Obviously, stats driver will not have any information
about the frequency transitions before the stats driver insertion.
---------------------------------------------------------------------------------
-<mysystem>:/sys/devices/system/cpu/cpu0/cpufreq/stats # ls -l
-total 0
-drwxr-xr-x 2 root root 0 May 14 16:06 .
-drwxr-xr-x 3 root root 0 May 14 15:58 ..
---w------- 1 root root 4096 May 14 16:06 reset
--r--r--r-- 1 root root 4096 May 14 16:06 time_in_state
--r--r--r-- 1 root root 4096 May 14 16:06 total_trans
--r--r--r-- 1 root root 4096 May 14 16:06 trans_table
---------------------------------------------------------------------------------
+::
-- reset
-Write-only attribute that can be used to reset the stat counters. This can be
-useful for evaluating system behaviour under different governors without the
-need for a reboot.
+ <mysystem>:/sys/devices/system/cpu/cpu0/cpufreq/stats # ls -l
+ total 0
+ drwxr-xr-x 2 root root 0 May 14 16:06 .
+ drwxr-xr-x 3 root root 0 May 14 15:58 ..
+ --w------- 1 root root 4096 May 14 16:06 reset
+ -r--r--r-- 1 root root 4096 May 14 16:06 time_in_state
+ -r--r--r-- 1 root root 4096 May 14 16:06 total_trans
+ -r--r--r-- 1 root root 4096 May 14 16:06 trans_table
-- time_in_state
-This gives the amount of time spent in each of the frequencies supported by
-this CPU. The cat output will have "<frequency> <time>" pair in each line, which
-will mean this CPU spent <time> usertime units of time at <frequency>. Output
-will have one line for each of the supported frequencies. usertime units here
-is 10mS (similar to other time exported in /proc).
+reset
+ Write-only attribute that can be used to reset the stat counters. This can be
+ useful for evaluating system behaviour under different governors without the
+ need for a reboot.
---------------------------------------------------------------------------------
-<mysystem>:/sys/devices/system/cpu/cpu0/cpufreq/stats # cat time_in_state
-3600000 2089
-3400000 136
-3200000 34
-3000000 67
-2800000 172488
---------------------------------------------------------------------------------
+time_in_state
+ This gives the amount of time spent in each of the frequencies supported by
+ this CPU. The cat output will have "<frequency> <time>" pair in each line,
+ which will mean this CPU spent <time> usertime units of time at <frequency>.
+ Output will have one line for each of the supported frequencies. usertime
+ units here is 10mS (similar to other time exported in /proc).
+::
-- total_trans
-This gives the total number of frequency transitions on this CPU. The cat
-output will have a single count which is the total number of frequency
-transitions.
+ <mysystem>:/sys/devices/system/cpu/cpu0/cpufreq/stats # cat time_in_state
+ 3600000 2089
+ 3400000 136
+ 3200000 34
+ 3000000 67
+ 2800000 172488
---------------------------------------------------------------------------------
-<mysystem>:/sys/devices/system/cpu/cpu0/cpufreq/stats # cat total_trans
-20
---------------------------------------------------------------------------------
-- trans_table
-This will give a fine grained information about all the CPU frequency
-transitions. The cat output here is a two dimensional matrix, where an entry
-<i,j> (row i, column j) represents the count of number of transitions from
-Freq_i to Freq_j. Freq_i rows and Freq_j columns follow the sorting order in
-which the driver has provided the frequency table initially to the cpufreq core
-and so can be sorted (ascending or descending) or unsorted. The output here
-also contains the actual freq values for each row and column for better
-readability.
+total_trans
+ This gives the total number of frequency transitions on this CPU. The cat
+ output will have a single count which is the total number of frequency
+ transitions.
-If the transition table is bigger than PAGE_SIZE, reading this will
-return an -EFBIG error.
+::
---------------------------------------------------------------------------------
-<mysystem>:/sys/devices/system/cpu/cpu0/cpufreq/stats # cat trans_table
- From : To
- : 3600000 3400000 3200000 3000000 2800000
- 3600000: 0 5 0 0 0
- 3400000: 4 0 2 0 0
- 3200000: 0 1 0 2 0
- 3000000: 0 0 1 0 3
- 2800000: 0 0 0 2 0
---------------------------------------------------------------------------------
+ <mysystem>:/sys/devices/system/cpu/cpu0/cpufreq/stats # cat total_trans
+ 20
+trans_table
+ This will give a fine grained information about all the CPU frequency
+ transitions. The cat output here is a two dimensional matrix, where an entry
+ <i,j> (row i, column j) represents the count of number of transitions from
+ Freq_i to Freq_j. Freq_i rows and Freq_j columns follow the sorting order in
+ which the driver has provided the frequency table initially to the cpufreq
+ core and so can be sorted (ascending or descending) or unsorted. The output
+ here also contains the actual freq values for each row and column for better
+ readability.
+
+ If the transition table is bigger than PAGE_SIZE, reading this will
+ return an -EFBIG error.
+
+::
+
+ <mysystem>:/sys/devices/system/cpu/cpu0/cpufreq/stats # cat trans_table
+ From : To
+ : 3600000 3400000 3200000 3000000 2800000
+ 3600000: 0 5 0 0 0
+ 3400000: 4 0 2 0 0
+ 3200000: 0 1 0 2 0
+ 3000000: 0 0 1 0 3
+ 2800000: 0 0 0 2 0
3. Configuring cpufreq-stats
+============================
-To configure cpufreq-stats in your kernel
-Config Main Menu
+To configure cpufreq-stats in your kernel::
+
+ Config Main Menu
Power management options (ACPI, APM) --->
CPU Frequency scaling --->
[*] CPU Frequency scaling
diff --git a/Documentation/cpu-freq/pcc-cpufreq.txt b/Documentation/cpu-freq/pcc-cpufreq.txt
index 9e3c3b33514c..d846a36536e4 100644
--- a/Documentation/cpu-freq/pcc-cpufreq.txt
+++ b/Documentation/cpu-freq/pcc-cpufreq.txt
@@ -1,45 +1,38 @@
-/*
- * pcc-cpufreq.txt - PCC interface documentation
- *
- * Copyright (C) 2009 Red Hat, Matthew Garrett <mjg@redhat.com>
- * Copyright (C) 2009 Hewlett-Packard Development Company, L.P.
- * Nagananda Chumbalkar <nagananda.chumbalkar@hp.com>
- *
- * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- *
- * This program is free software; you can redistribute it and/or modify
- * it under the terms of the GNU General Public License as published by
- * the Free Software Foundation; version 2 of the License.
- *
- * This program is distributed in the hope that it will be useful, but
- * WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE, GOOD TITLE or NON
- * INFRINGEMENT. See the GNU General Public License for more details.
- *
- * You should have received a copy of the GNU General Public License along
- * with this program; if not, write to the Free Software Foundation, Inc.,
- * 675 Mass Ave, Cambridge, MA 02139, USA.
- *
- * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- */
-
-
- Processor Clocking Control Driver
- ---------------------------------
-
-Contents:
----------
-1. Introduction
-1.1 PCC interface
-1.1.1 Get Average Frequency
-1.1.2 Set Desired Frequency
-1.2 Platforms affected
-2. Driver and /sys details
-2.1 scaling_available_frequencies
-2.2 cpuinfo_transition_latency
-2.3 cpuinfo_cur_freq
-2.4 related_cpus
-3. Caveats
+==========================================================
+Processor Clocking Control Driver cpufreq driver specifics
+==========================================================
+
+
+.. pcc-cpufreq.txt - PCC interface documentation
+
+ Copyright (C) 2009 Red Hat, Matthew Garrett <mjg@redhat.com>
+ Copyright (C) 2009 Hewlett-Packard Development Company, L.P.
+ Nagananda Chumbalkar <nagananda.chumbalkar@hp.com>
+
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+ This program is free software; you can redistribute it and/or modify
+ it under the terms of the GNU General Public License as published by
+ the Free Software Foundation; version 2 of the License.
+
+ This program is distributed in the hope that it will be useful, but
+ WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE, GOOD TITLE or NON
+ INFRINGEMENT. See the GNU General Public License for more details.
+
+
+.. Contents:
+ 1. Introduction
+ 1.1 PCC interface
+ 1.1.1 Get Average Frequency
+ 1.1.2 Set Desired Frequency
+ 1.2 Platforms affected
+ 2. Driver and /sys details
+ 2.1 scaling_available_frequencies
+ 2.2 cpuinfo_transition_latency
+ 2.3 cpuinfo_cur_freq
+ 2.4 related_cpus
+ 3. Caveats
1. Introduction:
----------------
@@ -72,6 +65,7 @@ memory region. The shared memory region header contains the "command" and
doorbell.
The following commands are supported by the PCC interface:
+
* Get Average Frequency
* Set Desired Frequency
@@ -140,7 +134,9 @@ Internally, there is no need for the driver to convert the "target" frequency
to a corresponding P-state.
The VERSION number for the driver will be of the format v.xy.ab.
-eg: 1.00.02
+eg::
+
+ 1.00.02
----- --
| |
| -- this will increase with bug fixes/enhancements to the driver
@@ -168,21 +164,21 @@ A) Often cpuinfo_cur_freq will show a value different than what is declared
in the scaling_available_frequencies or scaling_cur_freq, or scaling_max_freq.
This is due to "turbo boost" available on recent Intel processors. If certain
conditions are met the BIOS can achieve a slightly higher speed than requested
-by OSPM. An example:
+by OSPM. An example::
-scaling_cur_freq : 2933000
-cpuinfo_cur_freq : 3196000
+ scaling_cur_freq : 2933000
+ cpuinfo_cur_freq : 3196000
B) There is a round-off error associated with the cpuinfo_cur_freq value.
Since the driver obtains the current frequency as a "percentage" (%) of the
nominal frequency from the BIOS, sometimes, the values displayed by
-scaling_cur_freq and cpuinfo_cur_freq may not match. An example:
+scaling_cur_freq and cpuinfo_cur_freq may not match. An example::
-scaling_cur_freq : 1600000
-cpuinfo_cur_freq : 1583000
+ scaling_cur_freq : 1600000
+ cpuinfo_cur_freq : 1583000
In this example, the nominal frequency is 2933 MHz. The driver obtains the
-current frequency, cpuinfo_cur_freq, as 54% of the nominal frequency:
+current frequency, cpuinfo_cur_freq, as 54% of the nominal frequency::
54% of 2933 MHz = 1583 MHz
@@ -191,10 +187,10 @@ corresponds to the frequency of the P0 P-state.
2.4 related_cpus:
-----------------
-The related_cpus field is identical to affected_cpus.
+The related_cpus field is identical to affected_cpus:
-affected_cpus : 4
-related_cpus : 4
+ affected_cpus : 4
+ related_cpus : 4
Currently, the PCC driver does not evaluate _PSD. The platforms that support
PCC do not implement SW_ALL. So OSPM doesn't need to perform any coordination
--
2.20.1
^ permalink raw reply related [flat|nested] 81+ messages in thread* Re: [PATCH 09/57] docs: cpu-freq: convert files to ReST
2019-04-16 2:55 ` [PATCH 09/57] docs: cpu-freq: convert files to ReST Mauro Carvalho Chehab
@ 2019-04-16 8:21 ` Rafael J. Wysocki
2019-04-16 9:58 ` Mauro Carvalho Chehab
0 siblings, 1 reply; 81+ messages in thread
From: Rafael J. Wysocki @ 2019-04-16 8:21 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: Linux Doc Mailing List, Mauro Carvalho Chehab,
Linux Kernel Mailing List, Jonathan Corbet, Rafael J. Wysocki,
Viresh Kumar, Linux PM
On Tue, Apr 16, 2019 at 4:56 AM Mauro Carvalho Chehab
<mchehab+samsung@kernel.org> wrote:
>
> In order to be able to build html and pdf files, convert the
> documentation to ReST format.
>
> Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
Please don't convert these files.
They need more work than just semi-automatic conversion and the
material in them needs to go under driver-api.
This is quite hight in my TODO list.
Thanks,
Rafael
^ permalink raw reply [flat|nested] 81+ messages in thread
* Re: [PATCH 09/57] docs: cpu-freq: convert files to ReST
2019-04-16 8:21 ` Rafael J. Wysocki
@ 2019-04-16 9:58 ` Mauro Carvalho Chehab
0 siblings, 0 replies; 81+ messages in thread
From: Mauro Carvalho Chehab @ 2019-04-16 9:58 UTC (permalink / raw)
To: Rafael J. Wysocki
Cc: Linux Doc Mailing List, Mauro Carvalho Chehab,
Linux Kernel Mailing List, Jonathan Corbet, Rafael J. Wysocki,
Viresh Kumar, Linux PM
Em Tue, 16 Apr 2019 10:21:31 +0200
"Rafael J. Wysocki" <rafael@kernel.org> escreveu:
> On Tue, Apr 16, 2019 at 4:56 AM Mauro Carvalho Chehab
> <mchehab+samsung@kernel.org> wrote:
> >
> > In order to be able to build html and pdf files, convert the
> > documentation to ReST format.
> >
> > Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
>
> Please don't convert these files.
>
> They need more work than just semi-automatic conversion
Except for one exception (at patch 32/57), the ReST conversion on this
patch set was manually made. I basically renamed the files to
.rst, checked the errors and fixed, trying to preserve the original
document style as much as possible, while providing a good visual
for the html output.
I suspect that trying to write a script for such kind of conversion
is not an easy task, as some documents within the Kernel tree have
their own personal style, (there was even one written in LaTeX at
the CDROM docs), and I suspect that a script would end by adding
extra unwanted markups.
> and the material in them needs to go under driver-api.
Yeah, those documents make sense to be at the driver-api set.
The rationale why I placed the patch with actually renames on a
separate patchset (already on my devel tree, but yet to be submitted)
is that, this way, it should be easy for maintainers to pick the
conversion patch, apply on their trees, and, if they're not ready
yet, postpone the actual rename/move thing.
> This is quite hight in my TODO list.
OK. Feel free to use this patch as a starting point if you
want.
Regards,
Mauro
^ permalink raw reply [flat|nested] 81+ messages in thread
* [PATCH 11/57] docs: extcon: move it to acpi dir and convert it to ReST
2019-04-16 2:55 [PATCH 00/57] Convert files to ReST Mauro Carvalho Chehab
` (6 preceding siblings ...)
2019-04-16 2:55 ` [PATCH 09/57] docs: cpu-freq: convert files to ReST Mauro Carvalho Chehab
@ 2019-04-16 2:55 ` Mauro Carvalho Chehab
2019-04-16 2:55 ` [PATCH 12/57] docs: fault-injection: convert it to ReST format Mauro Carvalho Chehab
` (44 subsequent siblings)
52 siblings, 0 replies; 81+ messages in thread
From: Mauro Carvalho Chehab @ 2019-04-16 2:55 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Rafael J. Wysocki, Len Brown, linux-acpi
The intel-int3496.txt file is a documentation for an ACPI driver.
There's no reason to keep it on a separate directory.
So, instead of keeping it on some random location, move it
to a sub-directory inside the ACPI documentation dir.
For now, keep it with .txt extension, in order to avoid
Sphinx build noise. A later patch should change it to .rst
and movin it to be together with other acpi docs.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
.../drivers/extcon-intel-int3496.txt} | 14 ++++++++++----
MAINTAINERS | 2 +-
2 files changed, 11 insertions(+), 5 deletions(-)
rename Documentation/{extcon/intel-int3496.txt => acpi/drivers/extcon-intel-int3496.txt} (66%)
diff --git a/Documentation/extcon/intel-int3496.txt b/Documentation/acpi/drivers/extcon-intel-int3496.txt
similarity index 66%
rename from Documentation/extcon/intel-int3496.txt
rename to Documentation/acpi/drivers/extcon-intel-int3496.txt
index 8155dbc7fad3..5137ca834b54 100644
--- a/Documentation/extcon/intel-int3496.txt
+++ b/Documentation/acpi/drivers/extcon-intel-int3496.txt
@@ -1,5 +1,6 @@
+=====================================================
Intel INT3496 ACPI device extcon driver documentation
------------------------------------------------------
+=====================================================
The Intel INT3496 ACPI device extcon driver is a driver for ACPI
devices with an acpi-id of INT3496, such as found for example on
@@ -13,15 +14,20 @@ between an USB host and an USB peripheral controller.
The ACPI devices exposes this functionality by returning an array with up
to 3 gpio descriptors from its ACPI _CRS (Current Resource Settings) call:
-Index 0: The input gpio for the id-pin, this is always present and valid
-Index 1: The output gpio for enabling Vbus output from the device to the otg
+======= =====================================================================
+Index 0 The input gpio for the id-pin, this is always present and valid
+Index 1 The output gpio for enabling Vbus output from the device to the otg
port, write 1 to enable the Vbus output (this gpio descriptor may
be absent or invalid)
-Index 2: The output gpio for muxing of the data pins between the USB host and
+Index 2 The output gpio for muxing of the data pins between the USB host and
the USB peripheral controller, write 1 to mux to the peripheral
controller
+======= =====================================================================
There is a mapping between indices and GPIO connection IDs as follows
+
+ ======= =======
id index 0
vbus index 1
mux index 2
+ ======= =======
diff --git a/MAINTAINERS b/MAINTAINERS
index 8de292192227..99822421b447 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -5958,7 +5958,7 @@ S: Maintained
F: drivers/extcon/
F: include/linux/extcon/
F: include/linux/extcon.h
-F: Documentation/extcon/
+F: Documentation/acpi/drivers/extcon-intel-int3496.txt
F: Documentation/devicetree/bindings/extcon/
EXYNOS DP DRIVER
--
2.20.1
^ permalink raw reply related [flat|nested] 81+ messages in thread* [PATCH 12/57] docs: fault-injection: convert it to ReST format
2019-04-16 2:55 [PATCH 00/57] Convert files to ReST Mauro Carvalho Chehab
` (7 preceding siblings ...)
2019-04-16 2:55 ` [PATCH 11/57] docs: extcon: move it to acpi dir and convert it " Mauro Carvalho Chehab
@ 2019-04-16 2:55 ` Mauro Carvalho Chehab
2019-04-16 2:55 ` [PATCH 14/57] docs: fpga: convert it to ReST Mauro Carvalho Chehab
` (43 subsequent siblings)
52 siblings, 0 replies; 81+ messages in thread
From: Mauro Carvalho Chehab @ 2019-04-16 2:55 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Akinobu Mita
Instead of using plain text, convert it to ReST format, in
order for the docs to be parsed and produce html and pdf output.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
.../fault-injection/fault-injection.txt | 265 +++++++++---------
.../fault-injection/notifier-error-inject.txt | 18 +-
.../fault-injection/nvme-fault-injection.txt | 174 ++++++------
.../fault-injection/provoke-crashes.txt | 40 ++-
4 files changed, 263 insertions(+), 234 deletions(-)
diff --git a/Documentation/fault-injection/fault-injection.txt b/Documentation/fault-injection/fault-injection.txt
index a17517a083c3..f51bb21d20e4 100644
--- a/Documentation/fault-injection/fault-injection.txt
+++ b/Documentation/fault-injection/fault-injection.txt
@@ -1,3 +1,4 @@
+===========================================
Fault injection capabilities infrastructure
===========================================
@@ -7,36 +8,36 @@ See also drivers/md/md-faulty.c and "every_nth" module option for scsi_debug.
Available fault injection capabilities
--------------------------------------
-o failslab
+- failslab
injects slab allocation failures. (kmalloc(), kmem_cache_alloc(), ...)
-o fail_page_alloc
+- fail_page_alloc
injects page allocation failures. (alloc_pages(), get_free_pages(), ...)
-o fail_futex
+- fail_futex
injects futex deadlock and uaddr fault errors.
-o fail_make_request
+- fail_make_request
injects disk IO errors on devices permitted by setting
/sys/block/<device>/make-it-fail or
/sys/block/<device>/<partition>/make-it-fail. (generic_make_request())
-o fail_mmc_request
+- fail_mmc_request
injects MMC data errors on devices permitted by setting
debugfs entries under /sys/kernel/debug/mmc0/fail_mmc_request
-o fail_function
+- fail_function
injects error return on specific functions, which are marked by
ALLOW_ERROR_INJECTION() macro, by setting debugfs entries
under /sys/kernel/debug/fail_function. No boot option supported.
-o NVMe fault injection
+- NVMe fault injection
inject NVMe status code and retry flag on devices permitted by setting
debugfs entries under /sys/kernel/debug/nvme*/fault_inject. The default
@@ -47,7 +48,8 @@ o NVMe fault injection
Configure fault-injection capabilities behavior
-----------------------------------------------
-o debugfs entries
+debugfs entries
+^^^^^^^^^^^^^^^
fault-inject-debugfs kernel module provides some debugfs entries for runtime
configuration of fault-injection capabilities.
@@ -55,6 +57,7 @@ configuration of fault-injection capabilities.
- /sys/kernel/debug/fail*/probability:
likelihood of failure injection, in percent.
+
Format: <percent>
Note that one-failure-per-hundred is a very high error rate
@@ -83,6 +86,7 @@ configuration of fault-injection capabilities.
- /sys/kernel/debug/fail*/verbose
Format: { 0 | 1 | 2 }
+
specifies the verbosity of the messages when failure is
injected. '0' means no messages; '1' will print only a single
log line per failure; '2' will print a call trace too -- useful
@@ -91,14 +95,15 @@ configuration of fault-injection capabilities.
- /sys/kernel/debug/fail*/task-filter:
Format: { 'Y' | 'N' }
+
A value of 'N' disables filtering by process (default).
Any positive value limits failures to only processes indicated by
/proc/<pid>/make-it-fail==1.
-- /sys/kernel/debug/fail*/require-start:
-- /sys/kernel/debug/fail*/require-end:
-- /sys/kernel/debug/fail*/reject-start:
-- /sys/kernel/debug/fail*/reject-end:
+- /sys/kernel/debug/fail*/require-start,
+ /sys/kernel/debug/fail*/require-end,
+ /sys/kernel/debug/fail*/reject-start,
+ /sys/kernel/debug/fail*/reject-end:
specifies the range of virtual addresses tested during
stacktrace walking. Failure is injected only if some caller
@@ -116,6 +121,7 @@ configuration of fault-injection capabilities.
- /sys/kernel/debug/fail_page_alloc/ignore-gfp-highmem:
Format: { 'Y' | 'N' }
+
default is 'N', setting it to 'Y' won't inject failures into
highmem/user allocations.
@@ -123,6 +129,7 @@ configuration of fault-injection capabilities.
- /sys/kernel/debug/fail_page_alloc/ignore-gfp-wait:
Format: { 'Y' | 'N' }
+
default is 'N', setting it to 'Y' will inject failures
only into non-sleep allocations (GFP_ATOMIC allocations).
@@ -134,12 +141,14 @@ configuration of fault-injection capabilities.
- /sys/kernel/debug/fail_futex/ignore-private:
Format: { 'Y' | 'N' }
+
default is 'N', setting it to 'Y' will disable failure injections
when dealing with private (address space) futexes.
- /sys/kernel/debug/fail_function/inject:
Format: { 'function-name' | '!function-name' | '' }
+
specifies the target function of error injection by name.
If the function name leads '!' prefix, given function is
removed from injection list. If nothing specified ('')
@@ -160,10 +169,11 @@ configuration of fault-injection capabilities.
function for given function. This will be created when
user specifies new injection entry.
-o Boot option
+Boot option
+^^^^^^^^^^^
In order to inject faults while debugfs is not available (early boot time),
-use the boot option:
+use the boot option::
failslab=
fail_page_alloc=
@@ -171,10 +181,11 @@ use the boot option:
fail_futex=
mmc_core.fail_request=<interval>,<probability>,<space>,<times>
-o proc entries
+proc entries
+^^^^^^^^^^^^
-- /proc/<pid>/fail-nth:
-- /proc/self/task/<tid>/fail-nth:
+- /proc/<pid>/fail-nth,
+ /proc/self/task/<tid>/fail-nth:
Write to this file of integer N makes N-th call in the task fail.
Read from this file returns a integer value. A value of '0' indicates
@@ -191,16 +202,16 @@ o proc entries
How to add new fault injection capability
-----------------------------------------
-o #include <linux/fault-inject.h>
+- #include <linux/fault-inject.h>
-o define the fault attributes
+- define the fault attributes
DECLARE_FAULT_ATTR(name);
Please see the definition of struct fault_attr in fault-inject.h
for details.
-o provide a way to configure fault attributes
+- provide a way to configure fault attributes
- boot option
@@ -222,126 +233,126 @@ o provide a way to configure fault attributes
single kernel module, it is better to provide module parameters to
configure the fault attributes.
-o add a hook to insert failures
+- add a hook to insert failures
- Upon should_fail() returning true, client code should inject a failure.
+ Upon should_fail() returning true, client code should inject a failure:
should_fail(attr, size);
Application Examples
--------------------
-o Inject slab allocation failures into module init/exit code
+- Inject slab allocation failures into module init/exit code::
-#!/bin/bash
+ #!/bin/bash
-FAILTYPE=failslab
-echo Y > /sys/kernel/debug/$FAILTYPE/task-filter
-echo 10 > /sys/kernel/debug/$FAILTYPE/probability
-echo 100 > /sys/kernel/debug/$FAILTYPE/interval
-echo -1 > /sys/kernel/debug/$FAILTYPE/times
-echo 0 > /sys/kernel/debug/$FAILTYPE/space
-echo 2 > /sys/kernel/debug/$FAILTYPE/verbose
-echo 1 > /sys/kernel/debug/$FAILTYPE/ignore-gfp-wait
+ FAILTYPE=failslab
+ echo Y > /sys/kernel/debug/$FAILTYPE/task-filter
+ echo 10 > /sys/kernel/debug/$FAILTYPE/probability
+ echo 100 > /sys/kernel/debug/$FAILTYPE/interval
+ echo -1 > /sys/kernel/debug/$FAILTYPE/times
+ echo 0 > /sys/kernel/debug/$FAILTYPE/space
+ echo 2 > /sys/kernel/debug/$FAILTYPE/verbose
+ echo 1 > /sys/kernel/debug/$FAILTYPE/ignore-gfp-wait
-faulty_system()
-{
+ faulty_system()
+ {
bash -c "echo 1 > /proc/self/make-it-fail && exec $*"
-}
+ }
-if [ $# -eq 0 ]
-then
+ if [ $# -eq 0 ]
+ then
echo "Usage: $0 modulename [ modulename ... ]"
exit 1
-fi
+ fi
-for m in $*
-do
+ for m in $*
+ do
echo inserting $m...
faulty_system modprobe $m
echo removing $m...
faulty_system modprobe -r $m
-done
+ done
------------------------------------------------------------------------------
-o Inject page allocation failures only for a specific module
+- Inject page allocation failures only for a specific module::
-#!/bin/bash
+ #!/bin/bash
-FAILTYPE=fail_page_alloc
-module=$1
+ FAILTYPE=fail_page_alloc
+ module=$1
-if [ -z $module ]
-then
+ if [ -z $module ]
+ then
echo "Usage: $0 <modulename>"
exit 1
-fi
+ fi
-modprobe $module
+ modprobe $module
-if [ ! -d /sys/module/$module/sections ]
-then
+ if [ ! -d /sys/module/$module/sections ]
+ then
echo Module $module is not loaded
exit 1
-fi
+ fi
-cat /sys/module/$module/sections/.text > /sys/kernel/debug/$FAILTYPE/require-start
-cat /sys/module/$module/sections/.data > /sys/kernel/debug/$FAILTYPE/require-end
+ cat /sys/module/$module/sections/.text > /sys/kernel/debug/$FAILTYPE/require-start
+ cat /sys/module/$module/sections/.data > /sys/kernel/debug/$FAILTYPE/require-end
-echo N > /sys/kernel/debug/$FAILTYPE/task-filter
-echo 10 > /sys/kernel/debug/$FAILTYPE/probability
-echo 100 > /sys/kernel/debug/$FAILTYPE/interval
-echo -1 > /sys/kernel/debug/$FAILTYPE/times
-echo 0 > /sys/kernel/debug/$FAILTYPE/space
-echo 2 > /sys/kernel/debug/$FAILTYPE/verbose
-echo 1 > /sys/kernel/debug/$FAILTYPE/ignore-gfp-wait
-echo 1 > /sys/kernel/debug/$FAILTYPE/ignore-gfp-highmem
-echo 10 > /sys/kernel/debug/$FAILTYPE/stacktrace-depth
+ echo N > /sys/kernel/debug/$FAILTYPE/task-filter
+ echo 10 > /sys/kernel/debug/$FAILTYPE/probability
+ echo 100 > /sys/kernel/debug/$FAILTYPE/interval
+ echo -1 > /sys/kernel/debug/$FAILTYPE/times
+ echo 0 > /sys/kernel/debug/$FAILTYPE/space
+ echo 2 > /sys/kernel/debug/$FAILTYPE/verbose
+ echo 1 > /sys/kernel/debug/$FAILTYPE/ignore-gfp-wait
+ echo 1 > /sys/kernel/debug/$FAILTYPE/ignore-gfp-highmem
+ echo 10 > /sys/kernel/debug/$FAILTYPE/stacktrace-depth
-trap "echo 0 > /sys/kernel/debug/$FAILTYPE/probability" SIGINT SIGTERM EXIT
+ trap "echo 0 > /sys/kernel/debug/$FAILTYPE/probability" SIGINT SIGTERM EXIT
-echo "Injecting errors into the module $module... (interrupt to stop)"
-sleep 1000000
+ echo "Injecting errors into the module $module... (interrupt to stop)"
+ sleep 1000000
------------------------------------------------------------------------------
-o Inject open_ctree error while btrfs mount
+- Inject open_ctree error while btrfs mount::
-#!/bin/bash
+ #!/bin/bash
-rm -f testfile.img
-dd if=/dev/zero of=testfile.img bs=1M seek=1000 count=1
-DEVICE=$(losetup --show -f testfile.img)
-mkfs.btrfs -f $DEVICE
-mkdir -p tmpmnt
+ rm -f testfile.img
+ dd if=/dev/zero of=testfile.img bs=1M seek=1000 count=1
+ DEVICE=$(losetup --show -f testfile.img)
+ mkfs.btrfs -f $DEVICE
+ mkdir -p tmpmnt
-FAILTYPE=fail_function
-FAILFUNC=open_ctree
-echo $FAILFUNC > /sys/kernel/debug/$FAILTYPE/inject
-echo -12 > /sys/kernel/debug/$FAILTYPE/$FAILFUNC/retval
-echo N > /sys/kernel/debug/$FAILTYPE/task-filter
-echo 100 > /sys/kernel/debug/$FAILTYPE/probability
-echo 0 > /sys/kernel/debug/$FAILTYPE/interval
-echo -1 > /sys/kernel/debug/$FAILTYPE/times
-echo 0 > /sys/kernel/debug/$FAILTYPE/space
-echo 1 > /sys/kernel/debug/$FAILTYPE/verbose
+ FAILTYPE=fail_function
+ FAILFUNC=open_ctree
+ echo $FAILFUNC > /sys/kernel/debug/$FAILTYPE/inject
+ echo -12 > /sys/kernel/debug/$FAILTYPE/$FAILFUNC/retval
+ echo N > /sys/kernel/debug/$FAILTYPE/task-filter
+ echo 100 > /sys/kernel/debug/$FAILTYPE/probability
+ echo 0 > /sys/kernel/debug/$FAILTYPE/interval
+ echo -1 > /sys/kernel/debug/$FAILTYPE/times
+ echo 0 > /sys/kernel/debug/$FAILTYPE/space
+ echo 1 > /sys/kernel/debug/$FAILTYPE/verbose
-mount -t btrfs $DEVICE tmpmnt
-if [ $? -ne 0 ]
-then
+ mount -t btrfs $DEVICE tmpmnt
+ if [ $? -ne 0 ]
+ then
echo "SUCCESS!"
-else
+ else
echo "FAILED!"
umount tmpmnt
-fi
+ fi
-echo > /sys/kernel/debug/$FAILTYPE/inject
+ echo > /sys/kernel/debug/$FAILTYPE/inject
-rmdir tmpmnt
-losetup -d $DEVICE
-rm testfile.img
+ rmdir tmpmnt
+ losetup -d $DEVICE
+ rm testfile.img
Tool to run command with failslab or fail_page_alloc
@@ -354,43 +365,43 @@ see the following examples.
Examples:
Run a command "make -C tools/testing/selftests/ run_tests" with injecting slab
-allocation failure.
+allocation failure::
# ./tools/testing/fault-injection/failcmd.sh \
-- make -C tools/testing/selftests/ run_tests
Same as above except to specify 100 times failures at most instead of one time
-at most by default.
+at most by default::
# ./tools/testing/fault-injection/failcmd.sh --times=100 \
-- make -C tools/testing/selftests/ run_tests
Same as above except to inject page allocation failure instead of slab
-allocation failure.
+allocation failure::
# env FAILCMD_TYPE=fail_page_alloc \
./tools/testing/fault-injection/failcmd.sh --times=100 \
- -- make -C tools/testing/selftests/ run_tests
+ -- make -C tools/testing/selftests/ run_tests
Systematic faults using fail-nth
---------------------------------
The following code systematically faults 0-th, 1-st, 2-nd and so on
-capabilities in the socketpair() system call.
+capabilities in the socketpair() system call::
-#include <sys/types.h>
-#include <sys/stat.h>
-#include <sys/socket.h>
-#include <sys/syscall.h>
-#include <fcntl.h>
-#include <unistd.h>
-#include <string.h>
-#include <stdlib.h>
-#include <stdio.h>
-#include <errno.h>
+ #include <sys/types.h>
+ #include <sys/stat.h>
+ #include <sys/socket.h>
+ #include <sys/syscall.h>
+ #include <fcntl.h>
+ #include <unistd.h>
+ #include <string.h>
+ #include <stdlib.h>
+ #include <stdio.h>
+ #include <errno.h>
-int main()
-{
+ int main()
+ {
int i, err, res, fail_nth, fds[2];
char buf[128];
@@ -413,23 +424,23 @@ int main()
break;
}
return 0;
-}
+ }
-An example output:
+An example output::
-1-th fault Y: res=-1/23
-2-th fault Y: res=-1/23
-3-th fault Y: res=-1/12
-4-th fault Y: res=-1/12
-5-th fault Y: res=-1/23
-6-th fault Y: res=-1/23
-7-th fault Y: res=-1/23
-8-th fault Y: res=-1/12
-9-th fault Y: res=-1/12
-10-th fault Y: res=-1/12
-11-th fault Y: res=-1/12
-12-th fault Y: res=-1/12
-13-th fault Y: res=-1/12
-14-th fault Y: res=-1/12
-15-th fault Y: res=-1/12
-16-th fault N: res=0/12
+ 1-th fault Y: res=-1/23
+ 2-th fault Y: res=-1/23
+ 3-th fault Y: res=-1/12
+ 4-th fault Y: res=-1/12
+ 5-th fault Y: res=-1/23
+ 6-th fault Y: res=-1/23
+ 7-th fault Y: res=-1/23
+ 8-th fault Y: res=-1/12
+ 9-th fault Y: res=-1/12
+ 10-th fault Y: res=-1/12
+ 11-th fault Y: res=-1/12
+ 12-th fault Y: res=-1/12
+ 13-th fault Y: res=-1/12
+ 14-th fault Y: res=-1/12
+ 15-th fault Y: res=-1/12
+ 16-th fault N: res=0/12
diff --git a/Documentation/fault-injection/notifier-error-inject.txt b/Documentation/fault-injection/notifier-error-inject.txt
index e861d761de24..1668b6e48d3a 100644
--- a/Documentation/fault-injection/notifier-error-inject.txt
+++ b/Documentation/fault-injection/notifier-error-inject.txt
@@ -14,7 +14,8 @@ modules that can be used to test the following notifiers.
PM notifier error injection module
----------------------------------
This feature is controlled through debugfs interface
-/sys/kernel/debug/notifier-error-inject/pm/actions/<notifier event>/error
+
+ /sys/kernel/debug/notifier-error-inject/pm/actions/<notifier event>/error
Possible PM notifier events to be failed are:
@@ -22,7 +23,7 @@ Possible PM notifier events to be failed are:
* PM_SUSPEND_PREPARE
* PM_RESTORE_PREPARE
-Example: Inject PM suspend error (-12 = -ENOMEM)
+Example: Inject PM suspend error (-12 = -ENOMEM)::
# cd /sys/kernel/debug/notifier-error-inject/pm/
# echo -12 > actions/PM_SUSPEND_PREPARE/error
@@ -32,14 +33,15 @@ Example: Inject PM suspend error (-12 = -ENOMEM)
Memory hotplug notifier error injection module
----------------------------------------------
This feature is controlled through debugfs interface
-/sys/kernel/debug/notifier-error-inject/memory/actions/<notifier event>/error
+
+ /sys/kernel/debug/notifier-error-inject/memory/actions/<notifier event>/error
Possible memory notifier events to be failed are:
* MEM_GOING_ONLINE
* MEM_GOING_OFFLINE
-Example: Inject memory hotplug offline error (-12 == -ENOMEM)
+Example: Inject memory hotplug offline error (-12 == -ENOMEM)::
# cd /sys/kernel/debug/notifier-error-inject/memory
# echo -12 > actions/MEM_GOING_OFFLINE/error
@@ -49,7 +51,8 @@ Example: Inject memory hotplug offline error (-12 == -ENOMEM)
powerpc pSeries reconfig notifier error injection module
--------------------------------------------------------
This feature is controlled through debugfs interface
-/sys/kernel/debug/notifier-error-inject/pSeries-reconfig/actions/<notifier event>/error
+
+ /sys/kernel/debug/notifier-error-inject/pSeries-reconfig/actions/<notifier event>/error
Possible pSeries reconfig notifier events to be failed are:
@@ -61,7 +64,8 @@ Possible pSeries reconfig notifier events to be failed are:
Netdevice notifier error injection module
----------------------------------------------
This feature is controlled through debugfs interface
-/sys/kernel/debug/notifier-error-inject/netdev/actions/<notifier event>/error
+
+ /sys/kernel/debug/notifier-error-inject/netdev/actions/<notifier event>/error
Netdevice notifier events which can be failed are:
@@ -75,7 +79,7 @@ Netdevice notifier events which can be failed are:
* NETDEV_PRECHANGEUPPER
* NETDEV_CHANGEUPPER
-Example: Inject netdevice mtu change error (-22 == -EINVAL)
+Example: Inject netdevice mtu change error (-22 == -EINVAL)::
# cd /sys/kernel/debug/notifier-error-inject/netdev
# echo -22 > actions/NETDEV_CHANGEMTU/error
diff --git a/Documentation/fault-injection/nvme-fault-injection.txt b/Documentation/fault-injection/nvme-fault-injection.txt
index 8fbf3bf60b62..bbb1bf3e8650 100644
--- a/Documentation/fault-injection/nvme-fault-injection.txt
+++ b/Documentation/fault-injection/nvme-fault-injection.txt
@@ -16,101 +16,105 @@ following.
Example 1: Inject default status code with no retry
---------------------------------------------------
-mount /dev/nvme0n1 /mnt
-echo 1 > /sys/kernel/debug/nvme0n1/fault_inject/times
-echo 100 > /sys/kernel/debug/nvme0n1/fault_inject/probability
-cp a.file /mnt
+::
-Expected Result:
+ mount /dev/nvme0n1 /mnt
+ echo 1 > /sys/kernel/debug/nvme0n1/fault_inject/times
+ echo 100 > /sys/kernel/debug/nvme0n1/fault_inject/probability
+ cp a.file /mnt
-cp: cannot stat ‘/mnt/a.file’: Input/output error
+Expected Result::
-Message from dmesg:
+ cp: cannot stat ‘/mnt/a.file’: Input/output error
-FAULT_INJECTION: forcing a failure.
-name fault_inject, interval 1, probability 100, space 0, times 1
-CPU: 0 PID: 0 Comm: swapper/0 Not tainted 4.15.0-rc8+ #2
-Hardware name: innotek GmbH VirtualBox/VirtualBox,
-BIOS VirtualBox 12/01/2006
-Call Trace:
- <IRQ>
- dump_stack+0x5c/0x7d
- should_fail+0x148/0x170
- nvme_should_fail+0x2f/0x50 [nvme_core]
- nvme_process_cq+0xe7/0x1d0 [nvme]
- nvme_irq+0x1e/0x40 [nvme]
- __handle_irq_event_percpu+0x3a/0x190
- handle_irq_event_percpu+0x30/0x70
- handle_irq_event+0x36/0x60
- handle_fasteoi_irq+0x78/0x120
- handle_irq+0xa7/0x130
- ? tick_irq_enter+0xa8/0xc0
- do_IRQ+0x43/0xc0
- common_interrupt+0xa2/0xa2
- </IRQ>
-RIP: 0010:native_safe_halt+0x2/0x10
-RSP: 0018:ffffffff82003e90 EFLAGS: 00000246 ORIG_RAX: ffffffffffffffdd
-RAX: ffffffff817a10c0 RBX: ffffffff82012480 RCX: 0000000000000000
-RDX: 0000000000000000 RSI: 0000000000000000 RDI: 0000000000000000
-RBP: 0000000000000000 R08: 000000008e38ce64 R09: 0000000000000000
-R10: 0000000000000000 R11: 0000000000000000 R12: ffffffff82012480
-R13: ffffffff82012480 R14: 0000000000000000 R15: 0000000000000000
- ? __sched_text_end+0x4/0x4
- default_idle+0x18/0xf0
- do_idle+0x150/0x1d0
- cpu_startup_entry+0x6f/0x80
- start_kernel+0x4c4/0x4e4
- ? set_init_arg+0x55/0x55
- secondary_startup_64+0xa5/0xb0
- print_req_error: I/O error, dev nvme0n1, sector 9240
-EXT4-fs error (device nvme0n1): ext4_find_entry:1436:
-inode #2: comm cp: reading directory lblock 0
+Message from dmesg::
+
+ FAULT_INJECTION: forcing a failure.
+ name fault_inject, interval 1, probability 100, space 0, times 1
+ CPU: 0 PID: 0 Comm: swapper/0 Not tainted 4.15.0-rc8+ #2
+ Hardware name: innotek GmbH VirtualBox/VirtualBox,
+ BIOS VirtualBox 12/01/2006
+ Call Trace:
+ <IRQ>
+ dump_stack+0x5c/0x7d
+ should_fail+0x148/0x170
+ nvme_should_fail+0x2f/0x50 [nvme_core]
+ nvme_process_cq+0xe7/0x1d0 [nvme]
+ nvme_irq+0x1e/0x40 [nvme]
+ __handle_irq_event_percpu+0x3a/0x190
+ handle_irq_event_percpu+0x30/0x70
+ handle_irq_event+0x36/0x60
+ handle_fasteoi_irq+0x78/0x120
+ handle_irq+0xa7/0x130
+ ? tick_irq_enter+0xa8/0xc0
+ do_IRQ+0x43/0xc0
+ common_interrupt+0xa2/0xa2
+ </IRQ>
+ RIP: 0010:native_safe_halt+0x2/0x10
+ RSP: 0018:ffffffff82003e90 EFLAGS: 00000246 ORIG_RAX: ffffffffffffffdd
+ RAX: ffffffff817a10c0 RBX: ffffffff82012480 RCX: 0000000000000000
+ RDX: 0000000000000000 RSI: 0000000000000000 RDI: 0000000000000000
+ RBP: 0000000000000000 R08: 000000008e38ce64 R09: 0000000000000000
+ R10: 0000000000000000 R11: 0000000000000000 R12: ffffffff82012480
+ R13: ffffffff82012480 R14: 0000000000000000 R15: 0000000000000000
+ ? __sched_text_end+0x4/0x4
+ default_idle+0x18/0xf0
+ do_idle+0x150/0x1d0
+ cpu_startup_entry+0x6f/0x80
+ start_kernel+0x4c4/0x4e4
+ ? set_init_arg+0x55/0x55
+ secondary_startup_64+0xa5/0xb0
+ print_req_error: I/O error, dev nvme0n1, sector 9240
+ EXT4-fs error (device nvme0n1): ext4_find_entry:1436:
+ inode #2: comm cp: reading directory lblock 0
Example 2: Inject default status code with retry
------------------------------------------------
-mount /dev/nvme0n1 /mnt
-echo 1 > /sys/kernel/debug/nvme0n1/fault_inject/times
-echo 100 > /sys/kernel/debug/nvme0n1/fault_inject/probability
-echo 1 > /sys/kernel/debug/nvme0n1/fault_inject/status
-echo 0 > /sys/kernel/debug/nvme0n1/fault_inject/dont_retry
+::
-cp a.file /mnt
+ mount /dev/nvme0n1 /mnt
+ echo 1 > /sys/kernel/debug/nvme0n1/fault_inject/times
+ echo 100 > /sys/kernel/debug/nvme0n1/fault_inject/probability
+ echo 1 > /sys/kernel/debug/nvme0n1/fault_inject/status
+ echo 0 > /sys/kernel/debug/nvme0n1/fault_inject/dont_retry
-Expected Result:
+ cp a.file /mnt
-command success without error
+Expected Result::
-Message from dmesg:
+ command success without error
-FAULT_INJECTION: forcing a failure.
-name fault_inject, interval 1, probability 100, space 0, times 1
-CPU: 1 PID: 0 Comm: swapper/1 Not tainted 4.15.0-rc8+ #4
-Hardware name: innotek GmbH VirtualBox/VirtualBox, BIOS VirtualBox 12/01/2006
-Call Trace:
- <IRQ>
- dump_stack+0x5c/0x7d
- should_fail+0x148/0x170
- nvme_should_fail+0x30/0x60 [nvme_core]
- nvme_loop_queue_response+0x84/0x110 [nvme_loop]
- nvmet_req_complete+0x11/0x40 [nvmet]
- nvmet_bio_done+0x28/0x40 [nvmet]
- blk_update_request+0xb0/0x310
- blk_mq_end_request+0x18/0x60
- flush_smp_call_function_queue+0x3d/0xf0
- smp_call_function_single_interrupt+0x2c/0xc0
- call_function_single_interrupt+0xa2/0xb0
- </IRQ>
-RIP: 0010:native_safe_halt+0x2/0x10
-RSP: 0018:ffffc9000068bec0 EFLAGS: 00000246 ORIG_RAX: ffffffffffffff04
-RAX: ffffffff817a10c0 RBX: ffff88011a3c9680 RCX: 0000000000000000
-RDX: 0000000000000000 RSI: 0000000000000000 RDI: 0000000000000000
-RBP: 0000000000000001 R08: 000000008e38c131 R09: 0000000000000000
-R10: 0000000000000000 R11: 0000000000000000 R12: ffff88011a3c9680
-R13: ffff88011a3c9680 R14: 0000000000000000 R15: 0000000000000000
- ? __sched_text_end+0x4/0x4
- default_idle+0x18/0xf0
- do_idle+0x150/0x1d0
- cpu_startup_entry+0x6f/0x80
- start_secondary+0x187/0x1e0
- secondary_startup_64+0xa5/0xb0
+Message from dmesg::
+
+ FAULT_INJECTION: forcing a failure.
+ name fault_inject, interval 1, probability 100, space 0, times 1
+ CPU: 1 PID: 0 Comm: swapper/1 Not tainted 4.15.0-rc8+ #4
+ Hardware name: innotek GmbH VirtualBox/VirtualBox, BIOS VirtualBox 12/01/2006
+ Call Trace:
+ <IRQ>
+ dump_stack+0x5c/0x7d
+ should_fail+0x148/0x170
+ nvme_should_fail+0x30/0x60 [nvme_core]
+ nvme_loop_queue_response+0x84/0x110 [nvme_loop]
+ nvmet_req_complete+0x11/0x40 [nvmet]
+ nvmet_bio_done+0x28/0x40 [nvmet]
+ blk_update_request+0xb0/0x310
+ blk_mq_end_request+0x18/0x60
+ flush_smp_call_function_queue+0x3d/0xf0
+ smp_call_function_single_interrupt+0x2c/0xc0
+ call_function_single_interrupt+0xa2/0xb0
+ </IRQ>
+ RIP: 0010:native_safe_halt+0x2/0x10
+ RSP: 0018:ffffc9000068bec0 EFLAGS: 00000246 ORIG_RAX: ffffffffffffff04
+ RAX: ffffffff817a10c0 RBX: ffff88011a3c9680 RCX: 0000000000000000
+ RDX: 0000000000000000 RSI: 0000000000000000 RDI: 0000000000000000
+ RBP: 0000000000000001 R08: 000000008e38c131 R09: 0000000000000000
+ R10: 0000000000000000 R11: 0000000000000000 R12: ffff88011a3c9680
+ R13: ffff88011a3c9680 R14: 0000000000000000 R15: 0000000000000000
+ ? __sched_text_end+0x4/0x4
+ default_idle+0x18/0xf0
+ do_idle+0x150/0x1d0
+ cpu_startup_entry+0x6f/0x80
+ start_secondary+0x187/0x1e0
+ secondary_startup_64+0xa5/0xb0
diff --git a/Documentation/fault-injection/provoke-crashes.txt b/Documentation/fault-injection/provoke-crashes.txt
index 7a9d3d81525b..9279a3e12278 100644
--- a/Documentation/fault-injection/provoke-crashes.txt
+++ b/Documentation/fault-injection/provoke-crashes.txt
@@ -1,3 +1,7 @@
+===============
+Provoke crashes
+===============
+
The lkdtm module provides an interface to crash or injure the kernel at
predefined crashpoints to evaluate the reliability of crash dumps obtained
using different dumping solutions. The module uses KPROBEs to instrument
@@ -8,31 +12,37 @@ support.
You can provide the way either through module arguments when inserting
the module, or through a debugfs interface.
-Usage: insmod lkdtm.ko [recur_count={>0}] cpoint_name=<> cpoint_type=<>
- [cpoint_count={>0}]
+Usage::
- recur_count : Recursion level for the stack overflow test. Default is 10.
+ insmod lkdtm.ko [recur_count={>0}] cpoint_name=<> cpoint_type=<>
+ [cpoint_count={>0}]
- cpoint_name : Crash point where the kernel is to be crashed. It can be
- one of INT_HARDWARE_ENTRY, INT_HW_IRQ_EN, INT_TASKLET_ENTRY,
- FS_DEVRW, MEM_SWAPOUT, TIMERADD, SCSI_DISPATCH_CMD,
- IDE_CORE_CP, DIRECT
+recur_count
+ Recursion level for the stack overflow test. Default is 10.
- cpoint_type : Indicates the action to be taken on hitting the crash point.
- It can be one of PANIC, BUG, EXCEPTION, LOOP, OVERFLOW,
- CORRUPT_STACK, UNALIGNED_LOAD_STORE_WRITE, OVERWRITE_ALLOCATION,
- WRITE_AFTER_FREE,
+cpoint_name
+ Crash point where the kernel is to be crashed. It can be
+ one of INT_HARDWARE_ENTRY, INT_HW_IRQ_EN, INT_TASKLET_ENTRY,
+ FS_DEVRW, MEM_SWAPOUT, TIMERADD, SCSI_DISPATCH_CMD,
+ IDE_CORE_CP, DIRECT
- cpoint_count : Indicates the number of times the crash point is to be hit
- to trigger an action. The default is 10.
+cpoint_type
+ Indicates the action to be taken on hitting the crash point.
+ It can be one of PANIC, BUG, EXCEPTION, LOOP, OVERFLOW,
+ CORRUPT_STACK, UNALIGNED_LOAD_STORE_WRITE, OVERWRITE_ALLOCATION,
+ WRITE_AFTER_FREE,
+
+cpoint_count
+ Indicates the number of times the crash point is to be hit
+ to trigger an action. The default is 10.
You can also induce failures by mounting debugfs and writing the type to
-<mountpoint>/provoke-crash/<crashpoint>. E.g.,
+<mountpoint>/provoke-crash/<crashpoint>. E.g.::
mount -t debugfs debugfs /mnt
echo EXCEPTION > /mnt/provoke-crash/INT_HARDWARE_ENTRY
-A special file is `DIRECT' which will induce the crash directly without
+A special file is `DIRECT` which will induce the crash directly without
KPROBE instrumentation. This mode is the only one available when the module
is built on a kernel without KPROBEs support.
--
2.20.1
^ permalink raw reply related [flat|nested] 81+ messages in thread* [PATCH 14/57] docs: fpga: convert it to ReST
2019-04-16 2:55 [PATCH 00/57] Convert files to ReST Mauro Carvalho Chehab
` (8 preceding siblings ...)
2019-04-16 2:55 ` [PATCH 12/57] docs: fault-injection: convert it to ReST format Mauro Carvalho Chehab
@ 2019-04-16 2:55 ` Mauro Carvalho Chehab
2019-04-16 2:55 ` [PATCH 15/57] docs: gpio: " Mauro Carvalho Chehab
` (42 subsequent siblings)
52 siblings, 0 replies; 81+ messages in thread
From: Mauro Carvalho Chehab @ 2019-04-16 2:55 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Alan Tull, Moritz Fischer, linux-fpga
The dfl.txt file is almost there. It needs just a few
adjustments to be properly parsed.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
Documentation/fpga/dfl.txt | 58 +++++++++++++++++++++-----------------
1 file changed, 32 insertions(+), 26 deletions(-)
diff --git a/Documentation/fpga/dfl.txt b/Documentation/fpga/dfl.txt
index 6df4621c3f2a..2f125abd777f 100644
--- a/Documentation/fpga/dfl.txt
+++ b/Documentation/fpga/dfl.txt
@@ -1,9 +1,12 @@
-===============================================================================
- FPGA Device Feature List (DFL) Framework Overview
--------------------------------------------------------------------------------
- Enno Luebbers <enno.luebbers@intel.com>
- Xiao Guangrong <guangrong.xiao@linux.intel.com>
- Wu Hao <hao.wu@intel.com>
+=================================================
+FPGA Device Feature List (DFL) Framework Overview
+=================================================
+
+Authors:
+
+- Enno Luebbers <enno.luebbers@intel.com>
+- Xiao Guangrong <guangrong.xiao@linux.intel.com>
+- Wu Hao <hao.wu@intel.com>
The Device Feature List (DFL) FPGA framework (and drivers according to this
this framework) hides the very details of low layer hardwares and provides
@@ -19,7 +22,7 @@ Device Feature List (DFL) defines a linked list of feature headers within the
device MMIO space to provide an extensible way of adding features. Software can
walk through these predefined data structures to enumerate FPGA features:
FPGA Interface Unit (FIU), Accelerated Function Unit (AFU) and Private Features,
-as illustrated below:
+as illustrated below::
Header Header Header Header
+----------+ +-->+----------+ +-->+----------+ +-->+----------+
@@ -81,9 +84,9 @@ and release it using close().
The following functions are exposed through ioctls:
- Get driver API version (DFL_FPGA_GET_API_VERSION)
- Check for extensions (DFL_FPGA_CHECK_EXTENSION)
- Program bitstream (DFL_FPGA_FME_PORT_PR)
+- Get driver API version (DFL_FPGA_GET_API_VERSION)
+- Check for extensions (DFL_FPGA_CHECK_EXTENSION)
+- Program bitstream (DFL_FPGA_FME_PORT_PR)
More functions are exposed through sysfs
(/sys/class/fpga_region/regionX/dfl-fme.n/):
@@ -118,18 +121,19 @@ port by using open() on the port device node and release it using close().
The following functions are exposed through ioctls:
- Get driver API version (DFL_FPGA_GET_API_VERSION)
- Check for extensions (DFL_FPGA_CHECK_EXTENSION)
- Get port info (DFL_FPGA_PORT_GET_INFO)
- Get MMIO region info (DFL_FPGA_PORT_GET_REGION_INFO)
- Map DMA buffer (DFL_FPGA_PORT_DMA_MAP)
- Unmap DMA buffer (DFL_FPGA_PORT_DMA_UNMAP)
- Reset AFU (*DFL_FPGA_PORT_RESET)
+- Get driver API version (DFL_FPGA_GET_API_VERSION)
+- Check for extensions (DFL_FPGA_CHECK_EXTENSION)
+- Get port info (DFL_FPGA_PORT_GET_INFO)
+- Get MMIO region info (DFL_FPGA_PORT_GET_REGION_INFO)
+- Map DMA buffer (DFL_FPGA_PORT_DMA_MAP)
+- Unmap DMA buffer (DFL_FPGA_PORT_DMA_UNMAP)
+- Reset AFU (DFL_FPGA_PORT_RESET)
-*DFL_FPGA_PORT_RESET: reset the FPGA Port and its AFU. Userspace can do Port
-reset at any time, e.g. during DMA or Partial Reconfiguration. But it should
-never cause any system level issue, only functional failure (e.g. DMA or PR
-operation failure) and be recoverable from the failure.
+DFL_FPGA_PORT_RESET:
+ reset the FPGA Port and its AFU. Userspace can do Port
+ reset at any time, e.g. during DMA or Partial Reconfiguration. But it should
+ never cause any system level issue, only functional failure (e.g. DMA or PR
+ operation failure) and be recoverable from the failure.
User-space applications can also mmap() accelerator MMIO regions.
@@ -143,6 +147,8 @@ More functions are exposed through sysfs:
DFL Framework Overview
======================
+::
+
+----------+ +--------+ +--------+ +--------+
| FME | | AFU | | AFU | | AFU |
| Module | | Module | | Module | | Module |
@@ -151,7 +157,7 @@ DFL Framework Overview
| FPGA Container Device | Device Feature List
| (FPGA Base Region) | Framework
+-----------------------+
---------------------------------------------------------------------
+ ------------------------------------------------------------------
+----------------------------+
| FPGA DFL Device Module |
| (e.g. PCIE/Platform Device)|
@@ -220,7 +226,7 @@ the sysfs hierarchy under /sys/class/fpga_region.
In the example below, two DFL based FPGA devices are installed in the host. Each
fpga device has one FME and two ports (AFUs).
-FPGA regions are created under /sys/class/fpga_region/
+FPGA regions are created under /sys/class/fpga_region/::
/sys/class/fpga_region/region0
/sys/class/fpga_region/region1
@@ -231,7 +237,7 @@ Application needs to search each regionX folder, if feature device is found,
(e.g. "dfl-port.n" or "dfl-fme.m" is found), then it's the base
fpga region which represents the FPGA device.
-Each base region has one FME and two ports (AFUs) as child devices:
+Each base region has one FME and two ports (AFUs) as child devices::
/sys/class/fpga_region/region0/dfl-fme.0
/sys/class/fpga_region/region0/dfl-port.0
@@ -243,7 +249,7 @@ Each base region has one FME and two ports (AFUs) as child devices:
/sys/class/fpga_region/region3/dfl-port.3
...
-In general, the FME/AFU sysfs interfaces are named as follows:
+In general, the FME/AFU sysfs interfaces are named as follows::
/sys/class/fpga_region/<regionX>/<dfl-fme.n>/
/sys/class/fpga_region/<regionX>/<dfl-port.m>/
@@ -251,7 +257,7 @@ In general, the FME/AFU sysfs interfaces are named as follows:
with 'n' consecutively numbering all FMEs and 'm' consecutively numbering all
ports.
-The device nodes used for ioctl() or mmap() can be referenced through:
+The device nodes used for ioctl() or mmap() can be referenced through::
/sys/class/fpga_region/<regionX>/<dfl-fme.n>/dev
/sys/class/fpga_region/<regionX>/<dfl-port.n>/dev
--
2.20.1
^ permalink raw reply related [flat|nested] 81+ messages in thread* [PATCH 15/57] docs: gpio: convert it to ReST
2019-04-16 2:55 [PATCH 00/57] Convert files to ReST Mauro Carvalho Chehab
` (9 preceding siblings ...)
2019-04-16 2:55 ` [PATCH 14/57] docs: fpga: convert it to ReST Mauro Carvalho Chehab
@ 2019-04-16 2:55 ` Mauro Carvalho Chehab
2019-04-23 10:52 ` Linus Walleij
2019-04-16 2:55 ` [PATCH 16/57] docs: ide: convert it to ReST format Mauro Carvalho Chehab
` (41 subsequent siblings)
52 siblings, 1 reply; 81+ messages in thread
From: Mauro Carvalho Chehab @ 2019-04-16 2:55 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Linus Walleij, Bartosz Golaszewski, linux-gpio
The API described at sysfs.txt is deprecated.
Still, as it is still part of the Kernel (and will likely be
there for some time, as we don't simply remove APIs). So,
it makes sense to keep it there.
The conversion of this file is trivial.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
Documentation/gpio/sysfs.txt | 39 +++++++++++++++++++++++-------------
1 file changed, 25 insertions(+), 14 deletions(-)
diff --git a/Documentation/gpio/sysfs.txt b/Documentation/gpio/sysfs.txt
index 58eeab81f349..ec09ffd983e7 100644
--- a/Documentation/gpio/sysfs.txt
+++ b/Documentation/gpio/sysfs.txt
@@ -1,10 +1,12 @@
GPIO Sysfs Interface for Userspace
==================================
-THIS ABI IS DEPRECATED, THE ABI DOCUMENTATION HAS BEEN MOVED TO
-Documentation/ABI/obsolete/sysfs-gpio AND NEW USERSPACE CONSUMERS
-ARE SUPPOSED TO USE THE CHARACTER DEVICE ABI. THIS OLD SYSFS ABI WILL
-NOT BE DEVELOPED (NO NEW FEATURES), IT WILL JUST BE MAINTAINED.
+.. warning::
+
+ THIS ABI IS DEPRECATED, THE ABI DOCUMENTATION HAS BEEN MOVED TO
+ Documentation/ABI/obsolete/sysfs-gpio AND NEW USERSPACE CONSUMERS
+ ARE SUPPOSED TO USE THE CHARACTER DEVICE ABI. THIS OLD SYSFS ABI WILL
+ NOT BE DEVELOPED (NO NEW FEATURES), IT WILL JUST BE MAINTAINED.
Refer to the examples in tools/gpio/* for an introduction to the new
character device ABI. Also see the userspace header in
@@ -51,13 +53,15 @@ The control interfaces are write-only:
/sys/class/gpio/
- "export" ... Userspace may ask the kernel to export control of
+ "export" ...
+ Userspace may ask the kernel to export control of
a GPIO to userspace by writing its number to this file.
Example: "echo 19 > export" will create a "gpio19" node
for GPIO #19, if that's not requested by kernel code.
- "unexport" ... Reverses the effect of exporting to userspace.
+ "unexport" ...
+ Reverses the effect of exporting to userspace.
Example: "echo 19 > unexport" will remove a "gpio19"
node exported using the "export" file.
@@ -67,7 +71,8 @@ and have the following read/write attributes:
/sys/class/gpio/gpioN/
- "direction" ... reads as either "in" or "out". This value may
+ "direction" ...
+ reads as either "in" or "out". This value may
normally be written. Writing as "out" defaults to
initializing the value as low. To ensure glitch free
operation, values "low" and "high" may be written to
@@ -78,7 +83,8 @@ and have the following read/write attributes:
it was exported by kernel code that didn't explicitly
allow userspace to reconfigure this GPIO's direction.
- "value" ... reads as either 0 (low) or 1 (high). If the GPIO
+ "value" ...
+ reads as either 0 (low) or 1 (high). If the GPIO
is configured as an output, this value may be written;
any nonzero value is treated as high.
@@ -92,14 +98,16 @@ and have the following read/write attributes:
file and read the new value or close the file and re-open it
to read the value.
- "edge" ... reads as either "none", "rising", "falling", or
+ "edge" ...
+ reads as either "none", "rising", "falling", or
"both". Write these strings to select the signal edge(s)
that will make poll(2) on the "value" file return.
This file exists only if the pin can be configured as an
interrupt generating input pin.
- "active_low" ... reads as either 0 (false) or 1 (true). Write
+ "active_low" ...
+ reads as either 0 (false) or 1 (true). Write
any nonzero value to invert the value attribute both
for reading and writing. Existing and subsequent
poll(2) support configuration via the edge attribute
@@ -112,11 +120,14 @@ read-only attributes:
/sys/class/gpio/gpiochipN/
- "base" ... same as N, the first GPIO managed by this chip
+ "base" ...
+ same as N, the first GPIO managed by this chip
- "label" ... provided for diagnostics (not always unique)
+ "label" ...
+ provided for diagnostics (not always unique)
- "ngpio" ... how many GPIOs this manages (N to N + ngpio - 1)
+ "ngpio" ...
+ how many GPIOs this manages (N to N + ngpio - 1)
Board documentation should in most cases cover what GPIOs are used for
what purposes. However, those numbers are not always stable; GPIOs on
@@ -129,7 +140,7 @@ the correct GPIO number to use for a given signal.
Exporting from Kernel code
--------------------------
Kernel code can explicitly manage exports of GPIOs which have already been
-requested using gpio_request():
+requested using gpio_request()::
/* export the GPIO to userspace */
int gpiod_export(struct gpio_desc *desc, bool direction_may_change);
--
2.20.1
^ permalink raw reply related [flat|nested] 81+ messages in thread* Re: [PATCH 15/57] docs: gpio: convert it to ReST
2019-04-16 2:55 ` [PATCH 15/57] docs: gpio: " Mauro Carvalho Chehab
@ 2019-04-23 10:52 ` Linus Walleij
2019-04-23 12:38 ` Mauro Carvalho Chehab
0 siblings, 1 reply; 81+ messages in thread
From: Linus Walleij @ 2019-04-23 10:52 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: Linux Doc Mailing List, Mauro Carvalho Chehab,
linux-kernel@vger.kernel.org, Jonathan Corbet,
Bartosz Golaszewski, open list:GPIO SUBSYSTEM
On Tue, Apr 16, 2019 at 4:56 AM Mauro Carvalho Chehab
<mchehab+samsung@kernel.org> wrote:
> The API described at sysfs.txt is deprecated.
>
> Still, as it is still part of the Kernel (and will likely be
> there for some time, as we don't simply remove APIs). So,
> it makes sense to keep it there.
>
> The conversion of this file is trivial.
>
> Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
Acked-by: Linus Walleij <linus.walleij@linaro.org>
Mauro will you merge this or do you want me to merge it?
Yours,
Linus Walleij
^ permalink raw reply [flat|nested] 81+ messages in thread
* Re: [PATCH 15/57] docs: gpio: convert it to ReST
2019-04-23 10:52 ` Linus Walleij
@ 2019-04-23 12:38 ` Mauro Carvalho Chehab
0 siblings, 0 replies; 81+ messages in thread
From: Mauro Carvalho Chehab @ 2019-04-23 12:38 UTC (permalink / raw)
To: Linus Walleij
Cc: Linux Doc Mailing List, Mauro Carvalho Chehab,
linux-kernel@vger.kernel.org, Jonathan Corbet,
Bartosz Golaszewski, open list:GPIO SUBSYSTEM
Em Tue, 23 Apr 2019 12:52:04 +0200
Linus Walleij <linus.walleij@linaro.org> escreveu:
> On Tue, Apr 16, 2019 at 4:56 AM Mauro Carvalho Chehab
> <mchehab+samsung@kernel.org> wrote:
>
> > The API described at sysfs.txt is deprecated.
> >
> > Still, as it is still part of the Kernel (and will likely be
> > there for some time, as we don't simply remove APIs). So,
> > it makes sense to keep it there.
> >
> > The conversion of this file is trivial.
> >
> > Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
>
> Acked-by: Linus Walleij <linus.walleij@linaro.org>
>
> Mauro will you merge this or do you want me to merge it?
Linus,
Just answered on the other e-mail: better to merge via your
tree. Just notice that this version was superseded by
[PATCH v2 15/79] docs: gpio: convert docs to ReST and rename to *.rst
As it also does the rename to .rst.
Thanks,
Mauro
^ permalink raw reply [flat|nested] 81+ messages in thread
* [PATCH 16/57] docs: ide: convert it to ReST format
2019-04-16 2:55 [PATCH 00/57] Convert files to ReST Mauro Carvalho Chehab
` (10 preceding siblings ...)
2019-04-16 2:55 ` [PATCH 15/57] docs: gpio: " Mauro Carvalho Chehab
@ 2019-04-16 2:55 ` Mauro Carvalho Chehab
2019-04-16 2:55 ` [PATCH 17/57] docs: infiniband: " Mauro Carvalho Chehab
` (40 subsequent siblings)
52 siblings, 0 replies; 81+ messages in thread
From: Mauro Carvalho Chehab @ 2019-04-16 2:55 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, David S. Miller, linux-ide
Convert the IDE documentation to ReST format, in order to prepare
for its addition inside a book.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
Documentation/ide/ide-tape.txt | 23 ++--
Documentation/ide/ide.txt | 147 ++++++++++++++------------
Documentation/ide/warm-plug-howto.txt | 10 +-
3 files changed, 96 insertions(+), 84 deletions(-)
diff --git a/Documentation/ide/ide-tape.txt b/Documentation/ide/ide-tape.txt
index 3f348a0b21d8..3e061d9c0e38 100644
--- a/Documentation/ide/ide-tape.txt
+++ b/Documentation/ide/ide-tape.txt
@@ -1,4 +1,6 @@
-IDE ATAPI streaming tape driver.
+===============================
+IDE ATAPI streaming tape driver
+===============================
This driver is a part of the Linux ide driver.
@@ -10,14 +12,14 @@ to the request-list of the block device, and waits for their completion.
The block device major and minor numbers are determined from the
tape's relative position in the ide interfaces, as explained in ide.c.
-The character device interface consists of the following devices:
+The character device interface consists of the following devices::
-ht0 major 37, minor 0 first IDE tape, rewind on close.
-ht1 major 37, minor 1 second IDE tape, rewind on close.
-...
-nht0 major 37, minor 128 first IDE tape, no rewind on close.
-nht1 major 37, minor 129 second IDE tape, no rewind on close.
-...
+ ht0 major 37, minor 0 first IDE tape, rewind on close.
+ ht1 major 37, minor 1 second IDE tape, rewind on close.
+ ...
+ nht0 major 37, minor 128 first IDE tape, no rewind on close.
+ nht1 major 37, minor 129 second IDE tape, no rewind on close.
+ ...
The general magnetic tape commands compatible interface, as defined by
include/linux/mtio.h, is accessible through the character device.
@@ -40,9 +42,10 @@ Testing was done with a 2 GB CONNER CTMA 4000 IDE ATAPI Streaming Tape Drive.
Here are some words from the first releases of hd.c, which are quoted
in ide.c and apply here as well:
-| Special care is recommended. Have Fun!
+* Special care is recommended. Have Fun!
-Possible improvements:
+Possible improvements
+=====================
1. Support for the ATAPI overlap protocol.
diff --git a/Documentation/ide/ide.txt b/Documentation/ide/ide.txt
index 7aca987c23d9..88bdcba92f7d 100644
--- a/Documentation/ide/ide.txt
+++ b/Documentation/ide/ide.txt
@@ -1,41 +1,43 @@
-
- Information regarding the Enhanced IDE drive in Linux 2.6
-
-==============================================================================
-
+============================================
+Information regarding the Enhanced IDE drive
+============================================
The hdparm utility can be used to control various IDE features on a
running system. It is packaged separately. Please Look for it on popular
linux FTP sites.
+-------------------------------------------------------------------------------
+.. important::
-*** IMPORTANT NOTICES: BUGGY IDE CHIPSETS CAN CORRUPT DATA!!
-*** =================
-*** PCI versions of the CMD640 and RZ1000 interfaces are now detected
-*** automatically at startup when PCI BIOS support is configured.
-***
-*** Linux disables the "prefetch" ("readahead") mode of the RZ1000
-*** to prevent data corruption possible due to hardware design flaws.
-***
-*** For the CMD640, linux disables "IRQ unmasking" (hdparm -u1) on any
-*** drive for which the "prefetch" mode of the CMD640 is turned on.
-*** If "prefetch" is disabled (hdparm -p8), then "IRQ unmasking" can be
-*** used again.
-***
-*** For the CMD640, linux disables "32bit I/O" (hdparm -c1) on any drive
-*** for which the "prefetch" mode of the CMD640 is turned off.
-*** If "prefetch" is enabled (hdparm -p9), then "32bit I/O" can be
-*** used again.
-***
-*** The CMD640 is also used on some Vesa Local Bus (VLB) cards, and is *NOT*
-*** automatically detected by Linux. For safe, reliable operation with such
-*** interfaces, one *MUST* use the "cmd640.probe_vlb" kernel option.
-***
-*** Use of the "serialize" option is no longer necessary.
-
-================================================================================
-Common pitfalls:
+ BUGGY IDE CHIPSETS CAN CORRUPT DATA!!
+
+ PCI versions of the CMD640 and RZ1000 interfaces are now detected
+ automatically at startup when PCI BIOS support is configured.
+
+ Linux disables the "prefetch" ("readahead") mode of the RZ1000
+ to prevent data corruption possible due to hardware design flaws.
+
+ For the CMD640, linux disables "IRQ unmasking" (hdparm -u1) on any
+ drive for which the "prefetch" mode of the CMD640 is turned on.
+ If "prefetch" is disabled (hdparm -p8), then "IRQ unmasking" can be
+ used again.
+
+ For the CMD640, linux disables "32bit I/O" (hdparm -c1) on any drive
+ for which the "prefetch" mode of the CMD640 is turned off.
+ If "prefetch" is enabled (hdparm -p9), then "32bit I/O" can be
+ used again.
+
+ The CMD640 is also used on some Vesa Local Bus (VLB) cards, and is *NOT*
+ automatically detected by Linux. For safe, reliable operation with such
+ interfaces, one *MUST* use the "cmd640.probe_vlb" kernel option.
+
+ Use of the "serialize" option is no longer necessary.
+
+-------------------------------------------------------------------------------
+
+Common pitfalls
+===============
- 40-conductor IDE cables are capable of transferring data in DMA modes up to
udma2, but no faster.
@@ -49,19 +51,18 @@ Common pitfalls:
- Even better try to stick to the same vendor and device type on the same
cable.
-================================================================================
-
-This is the multiple IDE interface driver, as evolved from hd.c.
+This is the multiple IDE interface driver, as evolved from hd.c
+===============================================================
It supports up to 9 IDE interfaces per default, on one or more IRQs (usually
-14 & 15). There can be up to two drives per interface, as per the ATA-6 spec.
+14 & 15). There can be up to two drives per interface, as per the ATA-6 spec.::
-Primary: ide0, port 0x1f0; major=3; hda is minor=0; hdb is minor=64
-Secondary: ide1, port 0x170; major=22; hdc is minor=0; hdd is minor=64
-Tertiary: ide2, port 0x1e8; major=33; hde is minor=0; hdf is minor=64
-Quaternary: ide3, port 0x168; major=34; hdg is minor=0; hdh is minor=64
-fifth.. ide4, usually PCI, probed
-sixth.. ide5, usually PCI, probed
+ Primary: ide0, port 0x1f0; major=3; hda is minor=0; hdb is minor=64
+ Secondary: ide1, port 0x170; major=22; hdc is minor=0; hdd is minor=64
+ Tertiary: ide2, port 0x1e8; major=33; hde is minor=0; hdf is minor=64
+ Quaternary: ide3, port 0x168; major=34; hdg is minor=0; hdh is minor=64
+ fifth.. ide4, usually PCI, probed
+ sixth.. ide5, usually PCI, probed
To access devices on interfaces > ide0, device entries please make sure that
device files for them are present in /dev. If not, please create such
@@ -80,12 +81,15 @@ seldom occurs. Be careful, and if in doubt, don't do it!
Drives are normally found by auto-probing and/or examining the CMOS/BIOS data.
For really weird situations, the apparent (fdisk) geometry can also be specified
-on the kernel "command line" using LILO. The format of such lines is:
+on the kernel "command line" using LILO. The format of such lines is::
ide_core.chs=[interface_number.device_number]:cyls,heads,sects
-or ide_core.cdrom=[interface_number.device_number]
-For example:
+or::
+
+ ide_core.cdrom=[interface_number.device_number]
+
+For example::
ide_core.chs=1.0:1050,32,64 ide_core.cdrom=1.1
@@ -96,10 +100,12 @@ geometry for partitioning purposes (fdisk).
If the auto-probing during boot time confuses a drive (ie. the drive works
with hd.c but not with ide.c), then an command line option may be specified
for each drive for which you'd like the drive to skip the hardware
-probe/identification sequence. For example:
+probe/identification sequence. For example::
ide_core.noprobe=0.1
-or
+
+or::
+
ide_core.chs=1.0:768,16,32
ide_core.noprobe=1.0
@@ -115,22 +121,24 @@ Such drives will be identified at boot time, just like a hard disk.
If for some reason your cdrom drive is *not* found at boot time, you can force
the probe to look harder by supplying a kernel command line parameter
-via LILO, such as:
+via LILO, such as:::
ide_core.cdrom=1.0 /* "master" on second interface (hdc) */
-or
+
+or::
+
ide_core.cdrom=1.1 /* "slave" on second interface (hdd) */
For example, a GW2000 system might have a hard drive on the primary
interface (/dev/hda) and an IDE cdrom drive on the secondary interface
-(/dev/hdc). To mount a CD in the cdrom drive, one would use something like:
+(/dev/hdc). To mount a CD in the cdrom drive, one would use something like::
ln -sf /dev/hdc /dev/cdrom
mkdir /mnt/cdrom
mount /dev/cdrom /mnt/cdrom -t iso9660 -o ro
If, after doing all of the above, mount doesn't work and you see
-errors from the driver (with dmesg) complaining about `status=0xff',
+errors from the driver (with dmesg) complaining about `status=0xff`,
this means that the hardware is not responding to the driver's attempts
to read it. One of the following is probably the problem:
@@ -165,7 +173,7 @@ drivers can always be compiled as loadable modules, the chipset drivers
can only be compiled into the kernel, and the core code (ide.c) can be
compiled as a loadable module provided no chipset support is needed.
-When using ide.c as a module in combination with kmod, add:
+When using ide.c as a module in combination with kmod, add::
alias block-major-3 ide-probe
@@ -176,10 +184,8 @@ driver using the "options=" keyword to insmod, while replacing any ',' with
';'.
-================================================================================
-
Summary of ide driver parameters for kernel command line
---------------------------------------------------------
+========================================================
For legacy IDE VLB host drivers (ali14xx/dtc2278/ht6560b/qd65xx/umc8672)
you need to explicitly enable probing by using "probe" kernel parameter,
@@ -226,28 +232,31 @@ Other kernel parameters for ide_core are:
* "chs=[interface_number.device_number]" to force device as a disk (using CHS)
-================================================================================
Some Terminology
-----------------
-IDE = Integrated Drive Electronics, meaning that each drive has a built-in
-controller, which is why an "IDE interface card" is not a "controller card".
+================
-ATA = AT (the old IBM 286 computer) Attachment Interface, a draft American
-National Standard for connecting hard drives to PCs. This is the official
-name for "IDE".
+IDE
+ Integrated Drive Electronics, meaning that each drive has a built-in
+ controller, which is why an "IDE interface card" is not a "controller card".
-The latest standards define some enhancements, known as the ATA-6 spec,
-which grew out of vendor-specific "Enhanced IDE" (EIDE) implementations.
+ATA
+ AT (the old IBM 286 computer) Attachment Interface, a draft American
+ National Standard for connecting hard drives to PCs. This is the official
+ name for "IDE".
-ATAPI = ATA Packet Interface, a new protocol for controlling the drives,
-similar to SCSI protocols, created at the same time as the ATA2 standard.
-ATAPI is currently used for controlling CDROM, TAPE and FLOPPY (ZIP or
-LS120/240) devices, removable R/W cartridges, and for high capacity hard disk
-drives.
+ The latest standards define some enhancements, known as the ATA-6 spec,
+ which grew out of vendor-specific "Enhanced IDE" (EIDE) implementations.
+
+ATAPI
+ ATA Packet Interface, a new protocol for controlling the drives,
+ similar to SCSI protocols, created at the same time as the ATA2 standard.
+ ATAPI is currently used for controlling CDROM, TAPE and FLOPPY (ZIP or
+ LS120/240) devices, removable R/W cartridges, and for high capacity hard disk
+ drives.
mlord@pobox.com
---
+
Wed Apr 17 22:52:44 CEST 2002 edited by Marcin Dalecki, the current
maintainer.
diff --git a/Documentation/ide/warm-plug-howto.txt b/Documentation/ide/warm-plug-howto.txt
index 98152bcd515a..c245242ef2f1 100644
--- a/Documentation/ide/warm-plug-howto.txt
+++ b/Documentation/ide/warm-plug-howto.txt
@@ -1,14 +1,14 @@
-
+===================
IDE warm-plug HOWTO
===================
-To warm-plug devices on a port 'idex':
+To warm-plug devices on a port 'idex'::
-# echo -n "1" > /sys/class/ide_port/idex/delete_devices
+ # echo -n "1" > /sys/class/ide_port/idex/delete_devices
-unplug old device(s) and plug new device(s)
+unplug old device(s) and plug new device(s)::
-# echo -n "1" > /sys/class/ide_port/idex/scan
+ # echo -n "1" > /sys/class/ide_port/idex/scan
done
--
2.20.1
^ permalink raw reply related [flat|nested] 81+ messages in thread* [PATCH 17/57] docs: infiniband: convert it to ReST format
2019-04-16 2:55 [PATCH 00/57] Convert files to ReST Mauro Carvalho Chehab
` (11 preceding siblings ...)
2019-04-16 2:55 ` [PATCH 16/57] docs: ide: convert it to ReST format Mauro Carvalho Chehab
@ 2019-04-16 2:55 ` Mauro Carvalho Chehab
2019-04-16 2:55 ` [PATCH 19/57] docs: kdump: convert it to ReST Mauro Carvalho Chehab
` (39 subsequent siblings)
52 siblings, 0 replies; 81+ messages in thread
From: Mauro Carvalho Chehab @ 2019-04-16 2:55 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Doug Ledford, Jason Gunthorpe, linux-rdma
The InfiniBand docs are plain text with no markups.
So, all we needed to do were to add the title markups and
some markup sequences in order to properly parse tables,
lists and literal blocks.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
Documentation/infiniband/core_locking.txt | 64 +++++++------
Documentation/infiniband/ipoib.txt | 24 +++--
Documentation/infiniband/opa_vnic.txt | 108 ++++++++++++----------
Documentation/infiniband/sysfs.txt | 4 +-
Documentation/infiniband/tag_matching.txt | 5 +
Documentation/infiniband/user_mad.txt | 33 +++++--
Documentation/infiniband/user_verbs.txt | 12 ++-
7 files changed, 149 insertions(+), 101 deletions(-)
diff --git a/Documentation/infiniband/core_locking.txt b/Documentation/infiniband/core_locking.txt
index 4b1f36b6ada0..f34669beb4fe 100644
--- a/Documentation/infiniband/core_locking.txt
+++ b/Documentation/infiniband/core_locking.txt
@@ -1,4 +1,6 @@
-INFINIBAND MIDLAYER LOCKING
+===========================
+InfiniBand Midlayer Locking
+===========================
This guide is an attempt to make explicit the locking assumptions
made by the InfiniBand midlayer. It describes the requirements on
@@ -6,45 +8,47 @@ INFINIBAND MIDLAYER LOCKING
protocols that use the midlayer.
Sleeping and interrupt context
+==============================
With the following exceptions, a low-level driver implementation of
all of the methods in struct ib_device may sleep. The exceptions
are any methods from the list:
- create_ah
- modify_ah
- query_ah
- destroy_ah
- post_send
- post_recv
- poll_cq
- req_notify_cq
- map_phys_fmr
+ - create_ah
+ - modify_ah
+ - query_ah
+ - destroy_ah
+ - post_send
+ - post_recv
+ - poll_cq
+ - req_notify_cq
+ - map_phys_fmr
which may not sleep and must be callable from any context.
The corresponding functions exported to upper level protocol
consumers:
- ib_create_ah
- ib_modify_ah
- ib_query_ah
- ib_destroy_ah
- ib_post_send
- ib_post_recv
- ib_req_notify_cq
- ib_map_phys_fmr
+ - ib_create_ah
+ - ib_modify_ah
+ - ib_query_ah
+ - ib_destroy_ah
+ - ib_post_send
+ - ib_post_recv
+ - ib_req_notify_cq
+ - ib_map_phys_fmr
are therefore safe to call from any context.
In addition, the function
- ib_dispatch_event
+ - ib_dispatch_event
used by low-level drivers to dispatch asynchronous events through
the midlayer is also safe to call from any context.
Reentrancy
+----------
All of the methods in struct ib_device exported by a low-level
driver must be fully reentrant. The low-level driver is required to
@@ -62,6 +66,7 @@ Reentrancy
information between different calls of ib_poll_cq() is not defined.
Callbacks
+---------
A low-level driver must not perform a callback directly from the
same callchain as an ib_device method call. For example, it is not
@@ -74,18 +79,18 @@ Callbacks
completion event handlers for the same CQ are not called
simultaneously. The driver must guarantee that only one CQ event
handler for a given CQ is running at a time. In other words, the
- following situation is not allowed:
+ following situation is not allowed::
- CPU1 CPU2
+ CPU1 CPU2
- low-level driver ->
- consumer CQ event callback:
- /* ... */
- ib_req_notify_cq(cq, ...);
- low-level driver ->
- /* ... */ consumer CQ event callback:
- /* ... */
- return from CQ event handler
+ low-level driver ->
+ consumer CQ event callback:
+ /* ... */
+ ib_req_notify_cq(cq, ...);
+ low-level driver ->
+ /* ... */ consumer CQ event callback:
+ /* ... */
+ return from CQ event handler
The context in which completion event and asynchronous event
callbacks run is not defined. Depending on the low-level driver, it
@@ -93,6 +98,7 @@ Callbacks
Upper level protocol consumers may not sleep in a callback.
Hot-plug
+--------
A low-level driver announces that a device is ready for use by
consumers when it calls ib_register_device(), all initialization
diff --git a/Documentation/infiniband/ipoib.txt b/Documentation/infiniband/ipoib.txt
index 47c1dd9818f2..0dd36154c0c9 100644
--- a/Documentation/infiniband/ipoib.txt
+++ b/Documentation/infiniband/ipoib.txt
@@ -1,4 +1,6 @@
-IP OVER INFINIBAND
+==================
+IP over InfiniBand
+==================
The ib_ipoib driver is an implementation of the IP over InfiniBand
protocol as specified by RFC 4391 and 4392, issued by the IETF ipoib
@@ -8,16 +10,17 @@ IP OVER INFINIBAND
masqueraded to the kernel as ethernet interfaces).
Partitions and P_Keys
+=====================
When the IPoIB driver is loaded, it creates one interface for each
port using the P_Key at index 0. To create an interface with a
different P_Key, write the desired P_Key into the main interface's
- /sys/class/net/<intf name>/create_child file. For example:
+ /sys/class/net/<intf name>/create_child file. For example::
echo 0x8001 > /sys/class/net/ib0/create_child
This will create an interface named ib0.8001 with P_Key 0x8001. To
- remove a subinterface, use the "delete_child" file:
+ remove a subinterface, use the "delete_child" file::
echo 0x8001 > /sys/class/net/ib0/delete_child
@@ -28,6 +31,7 @@ Partitions and P_Keys
rtnl_link_ops, where children created using either way behave the same.
Datagram vs Connected modes
+===========================
The IPoIB driver supports two modes of operation: datagram and
connected. The mode is set and read through an interface's
@@ -51,6 +55,7 @@ Datagram vs Connected modes
networking stack to use the smaller UD MTU for these neighbours.
Stateless offloads
+==================
If the IB HW supports IPoIB stateless offloads, IPoIB advertises
TCP/IP checksum and/or Large Send (LSO) offloading capability to the
@@ -60,9 +65,10 @@ Stateless offloads
on/off using ethtool calls. Currently LRO is supported only for
checksum offload capable devices.
- Stateless offloads are supported only in datagram mode.
+ Stateless offloads are supported only in datagram mode.
Interrupt moderation
+====================
If the underlying IB device supports CQ event moderation, one can
use ethtool to set interrupt mitigation parameters and thus reduce
@@ -71,6 +77,7 @@ Interrupt moderation
moderation is supported.
Debugging Information
+=====================
By compiling the IPoIB driver with CONFIG_INFINIBAND_IPOIB_DEBUG set
to 'y', tracing messages are compiled into the driver. They are
@@ -79,7 +86,7 @@ Debugging Information
runtime through files in /sys/module/ib_ipoib/.
CONFIG_INFINIBAND_IPOIB_DEBUG also enables files in the debugfs
- virtual filesystem. By mounting this filesystem, for example with
+ virtual filesystem. By mounting this filesystem, for example with::
mount -t debugfs none /sys/kernel/debug
@@ -96,10 +103,13 @@ Debugging Information
performance, because it adds tests to the fast path.
References
+==========
Transmission of IP over InfiniBand (IPoIB) (RFC 4391)
- http://ietf.org/rfc/rfc4391.txt
+ http://ietf.org/rfc/rfc4391.txt
+
IP over InfiniBand (IPoIB) Architecture (RFC 4392)
- http://ietf.org/rfc/rfc4392.txt
+ http://ietf.org/rfc/rfc4392.txt
+
IP over InfiniBand: Connected Mode (RFC 4755)
http://ietf.org/rfc/rfc4755.txt
diff --git a/Documentation/infiniband/opa_vnic.txt b/Documentation/infiniband/opa_vnic.txt
index 282e17be798a..2f888d9ffec0 100644
--- a/Documentation/infiniband/opa_vnic.txt
+++ b/Documentation/infiniband/opa_vnic.txt
@@ -1,3 +1,7 @@
+=================================================================
+Intel Omni-Path (OPA) Virtual Network Interface Controller (VNIC)
+=================================================================
+
Intel Omni-Path (OPA) Virtual Network Interface Controller (VNIC) feature
supports Ethernet functionality over Omni-Path fabric by encapsulating
the Ethernet packets between HFI nodes.
@@ -17,70 +21,72 @@ an independent Ethernet network. The configuration is performed by an
Ethernet Manager (EM) which is part of the trusted Fabric Manager (FM)
application. HFI nodes can have multiple VNICs each connected to a
different virtual Ethernet switch. The below diagram presents a case
-of two virtual Ethernet switches with two HFI nodes.
+of two virtual Ethernet switches with two HFI nodes::
- +-------------------+
- | Subnet/ |
- | Ethernet |
- | Manager |
- +-------------------+
- / /
- / /
- / /
- / /
-+-----------------------------+ +------------------------------+
-| Virtual Ethernet Switch | | Virtual Ethernet Switch |
-| +---------+ +---------+ | | +---------+ +---------+ |
-| | VPORT | | VPORT | | | | VPORT | | VPORT | |
-+--+---------+----+---------+-+ +-+---------+----+---------+---+
- | \ / |
- | \ / |
- | \/ |
- | / \ |
- | / \ |
- +-----------+------------+ +-----------+------------+
- | VNIC | VNIC | | VNIC | VNIC |
- +-----------+------------+ +-----------+------------+
- | HFI | | HFI |
- +------------------------+ +------------------------+
+ +-------------------+
+ | Subnet/ |
+ | Ethernet |
+ | Manager |
+ +-------------------+
+ / /
+ / /
+ / /
+ / /
+ +-----------------------------+ +------------------------------+
+ | Virtual Ethernet Switch | | Virtual Ethernet Switch |
+ | +---------+ +---------+ | | +---------+ +---------+ |
+ | | VPORT | | VPORT | | | | VPORT | | VPORT | |
+ +--+---------+----+---------+-+ +-+---------+----+---------+---+
+ | \ / |
+ | \ / |
+ | \/ |
+ | / \ |
+ | / \ |
+ +-----------+------------+ +-----------+------------+
+ | VNIC | VNIC | | VNIC | VNIC |
+ +-----------+------------+ +-----------+------------+
+ | HFI | | HFI |
+ +------------------------+ +------------------------+
The Omni-Path encapsulated Ethernet packet format is as described below.
-Bits Field
-------------------------------------
+==================== ================================
+Bits Field
+==================== ================================
Quad Word 0:
-0-19 SLID (lower 20 bits)
-20-30 Length (in Quad Words)
-31 BECN bit
-32-51 DLID (lower 20 bits)
-52-56 SC (Service Class)
-57-59 RC (Routing Control)
-60 FECN bit
-61-62 L2 (=10, 16B format)
-63 LT (=1, Link Transfer Head Flit)
+0-19 SLID (lower 20 bits)
+20-30 Length (in Quad Words)
+31 BECN bit
+32-51 DLID (lower 20 bits)
+52-56 SC (Service Class)
+57-59 RC (Routing Control)
+60 FECN bit
+61-62 L2 (=10, 16B format)
+63 LT (=1, Link Transfer Head Flit)
Quad Word 1:
-0-7 L4 type (=0x78 ETHERNET)
-8-11 SLID[23:20]
-12-15 DLID[23:20]
-16-31 PKEY
-32-47 Entropy
-48-63 Reserved
+0-7 L4 type (=0x78 ETHERNET)
+8-11 SLID[23:20]
+12-15 DLID[23:20]
+16-31 PKEY
+32-47 Entropy
+48-63 Reserved
Quad Word 2:
-0-15 Reserved
-16-31 L4 header
-32-63 Ethernet Packet
+0-15 Reserved
+16-31 L4 header
+32-63 Ethernet Packet
Quad Words 3 to N-1:
-0-63 Ethernet packet (pad extended)
+0-63 Ethernet packet (pad extended)
Quad Word N (last):
-0-23 Ethernet packet (pad extended)
-24-55 ICRC
-56-61 Tail
-62-63 LT (=01, Link Transfer Tail Flit)
+0-23 Ethernet packet (pad extended)
+24-55 ICRC
+56-61 Tail
+62-63 LT (=01, Link Transfer Tail Flit)
+==================== ================================
Ethernet packet is padded on the transmit side to ensure that the VNIC OPA
packet is quad word aligned. The 'Tail' field contains the number of bytes
@@ -123,7 +129,7 @@ operation. It also handles the encapsulation of Ethernet packets with an
Omni-Path header in the transmit path. For each VNIC interface, the
information required for encapsulation is configured by the EM via VEMA MAD
interface. It also passes any control information to the HW dependent driver
-by invoking the RDMA netdev control operations.
+by invoking the RDMA netdev control operations::
+-------------------+ +----------------------+
| | | Linux |
diff --git a/Documentation/infiniband/sysfs.txt b/Documentation/infiniband/sysfs.txt
index 9fab5062f84b..f0abd6fa48f4 100644
--- a/Documentation/infiniband/sysfs.txt
+++ b/Documentation/infiniband/sysfs.txt
@@ -1,4 +1,6 @@
-SYSFS FILES
+===========
+Sysfs files
+===========
The sysfs interface has moved to
Documentation/ABI/stable/sysfs-class-infiniband.
diff --git a/Documentation/infiniband/tag_matching.txt b/Documentation/infiniband/tag_matching.txt
index d2a3bf819226..ef56ea585f92 100644
--- a/Documentation/infiniband/tag_matching.txt
+++ b/Documentation/infiniband/tag_matching.txt
@@ -1,12 +1,16 @@
+==================
Tag matching logic
+==================
The MPI standard defines a set of rules, known as tag-matching, for matching
source send operations to destination receives. The following parameters must
match the following source and destination parameters:
+
* Communicator
* User tag - wild card may be specified by the receiver
* Source rank – wild car may be specified by the receiver
* Destination rank – wild
+
The ordering rules require that when more than one pair of send and receive
message envelopes may match, the pair that includes the earliest posted-send
and the earliest posted-receive is the pair that must be used to satisfy the
@@ -35,6 +39,7 @@ the header to initiate an RDMA READ operation directly to the matching buffer.
A fin message needs to be received in order for the buffer to be reused.
Tag matching implementation
+===========================
There are two types of matching objects used, the posted receive list and the
unexpected message list. The application posts receive buffers through calls
diff --git a/Documentation/infiniband/user_mad.txt b/Documentation/infiniband/user_mad.txt
index 7aca13a54a3a..d88abfc0e370 100644
--- a/Documentation/infiniband/user_mad.txt
+++ b/Documentation/infiniband/user_mad.txt
@@ -1,6 +1,9 @@
-USERSPACE MAD ACCESS
+====================
+Userspace MAD access
+====================
Device files
+============
Each port of each InfiniBand device has a "umad" device and an
"issm" device attached. For example, a two-port HCA will have two
@@ -8,12 +11,13 @@ Device files
device of each type (for switch port 0).
Creating MAD agents
+===================
A MAD agent can be created by filling in a struct ib_user_mad_reg_req
and then calling the IB_USER_MAD_REGISTER_AGENT ioctl on a file
descriptor for the appropriate device file. If the registration
request succeeds, a 32-bit id will be returned in the structure.
- For example:
+ For example::
struct ib_user_mad_reg_req req = { /* ... */ };
ret = ioctl(fd, IB_USER_MAD_REGISTER_AGENT, (char *) &req);
@@ -26,12 +30,14 @@ Creating MAD agents
ioctl. Also, all agents registered through a file descriptor will
be unregistered when the descriptor is closed.
- 2014 -- a new registration ioctl is now provided which allows additional
+ 2014
+ a new registration ioctl is now provided which allows additional
fields to be provided during registration.
Users of this registration call are implicitly setting the use of
pkey_index (see below).
Receiving MADs
+==============
MADs are received using read(). The receive side now supports
RMPP. The buffer passed to read() must be at least one
@@ -41,7 +47,8 @@ Receiving MADs
MAD (RMPP), the errno is set to ENOSPC and the length of the
buffer needed is set in mad.length.
- Example for normal MAD (non RMPP) reads:
+ Example for normal MAD (non RMPP) reads::
+
struct ib_user_mad *mad;
mad = malloc(sizeof *mad + 256);
ret = read(fd, mad, sizeof *mad + 256);
@@ -50,7 +57,8 @@ Receiving MADs
free(mad);
}
- Example for RMPP reads:
+ Example for RMPP reads::
+
struct ib_user_mad *mad;
mad = malloc(sizeof *mad + 256);
ret = read(fd, mad, sizeof *mad + 256);
@@ -76,11 +84,12 @@ Receiving MADs
poll()/select() may be used to wait until a MAD can be read.
Sending MADs
+============
MADs are sent using write(). The agent ID for sending should be
filled into the id field of the MAD, the destination LID should be
filled into the lid field, and so on. The send side does support
- RMPP so arbitrary length MAD can be sent. For example:
+ RMPP so arbitrary length MAD can be sent. For example::
struct ib_user_mad *mad;
@@ -97,6 +106,7 @@ Sending MADs
perror("write");
Transaction IDs
+===============
Users of the umad devices can use the lower 32 bits of the
transaction ID field (that is, the least significant half of the
@@ -105,6 +115,7 @@ Transaction IDs
the kernel and will be overwritten before a MAD is sent.
P_Key Index Handling
+====================
The old ib_umad interface did not allow setting the P_Key index for
MADs that are sent and did not provide a way for obtaining the P_Key
@@ -119,6 +130,7 @@ P_Key Index Handling
default, and the IB_USER_MAD_ENABLE_PKEY ioctl will be removed.
Setting IsSM Capability Bit
+===========================
To set the IsSM capability bit for a port, simply open the
corresponding issm device file. If the IsSM bit is already set,
@@ -129,25 +141,26 @@ Setting IsSM Capability Bit
the issm file.
/dev files
+==========
To create the appropriate character device files automatically with
- udev, a rule like
+ udev, a rule like::
KERNEL=="umad*", NAME="infiniband/%k"
KERNEL=="issm*", NAME="infiniband/%k"
- can be used. This will create device nodes named
+ can be used. This will create device nodes named::
/dev/infiniband/umad0
/dev/infiniband/issm0
for the first port, and so on. The InfiniBand device and port
- associated with these devices can be determined from the files
+ associated with these devices can be determined from the files::
/sys/class/infiniband_mad/umad0/ibdev
/sys/class/infiniband_mad/umad0/port
- and
+ and::
/sys/class/infiniband_mad/issm0/ibdev
/sys/class/infiniband_mad/issm0/port
diff --git a/Documentation/infiniband/user_verbs.txt b/Documentation/infiniband/user_verbs.txt
index 47ebf2f80b2b..8ddc4b1cfef2 100644
--- a/Documentation/infiniband/user_verbs.txt
+++ b/Documentation/infiniband/user_verbs.txt
@@ -1,4 +1,6 @@
-USERSPACE VERBS ACCESS
+======================
+Userspace verbs access
+======================
The ib_uverbs module, built by enabling CONFIG_INFINIBAND_USER_VERBS,
enables direct userspace access to IB hardware via "verbs," as
@@ -13,6 +15,7 @@ USERSPACE VERBS ACCESS
libmthca userspace driver be installed.
User-kernel communication
+=========================
Userspace communicates with the kernel for slow path, resource
management operations via the /dev/infiniband/uverbsN character
@@ -28,6 +31,7 @@ User-kernel communication
system call.
Resource management
+===================
Since creation and destruction of all IB resources is done by
commands passed through a file descriptor, the kernel can keep track
@@ -41,6 +45,7 @@ Resource management
prevent one process from touching another process's resources.
Memory pinning
+==============
Direct userspace I/O requires that memory regions that are potential
I/O targets be kept resident at the same physical address. The
@@ -54,13 +59,14 @@ Memory pinning
number of pages pinned by a process.
/dev files
+==========
To create the appropriate character device files automatically with
- udev, a rule like
+ udev, a rule like::
KERNEL=="uverbs*", NAME="infiniband/%k"
- can be used. This will create device nodes named
+ can be used. This will create device nodes named::
/dev/infiniband/uverbs0
--
2.20.1
^ permalink raw reply related [flat|nested] 81+ messages in thread* [PATCH 19/57] docs: kdump: convert it to ReST
2019-04-16 2:55 [PATCH 00/57] Convert files to ReST Mauro Carvalho Chehab
` (12 preceding siblings ...)
2019-04-16 2:55 ` [PATCH 17/57] docs: infiniband: " Mauro Carvalho Chehab
@ 2019-04-16 2:55 ` Mauro Carvalho Chehab
2019-04-16 2:55 ` [PATCH 20/57] docs: livepatch: convert it to ReST format Mauro Carvalho Chehab
` (38 subsequent siblings)
52 siblings, 0 replies; 81+ messages in thread
From: Mauro Carvalho Chehab @ 2019-04-16 2:55 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Dave Young, Baoquan He, Vivek Goyal, kexec
Convert kdump documentation to ReST and add it to the
user faced manual, as the documents are mainly focused on
sysadmins that would be enabling kdump.
Note: the vmcoreinfo.rst has one very long title for
sub-sections. I opted to break this one, in order to make it
easier to display in html.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
Documentation/kdump/kdump.txt | 131 +++++++++++++++++------------
Documentation/kdump/vmcoreinfo.txt | 59 ++++++-------
2 files changed, 104 insertions(+), 86 deletions(-)
diff --git a/Documentation/kdump/kdump.txt b/Documentation/kdump/kdump.txt
index 51814450a7f8..1da2d7b765f6 100644
--- a/Documentation/kdump/kdump.txt
+++ b/Documentation/kdump/kdump.txt
@@ -71,9 +71,8 @@ This is a symlink to the latest version.
The latest kexec-tools git tree is available at:
-git://git.kernel.org/pub/scm/utils/kernel/kexec/kexec-tools.git
-and
-http://www.kernel.org/pub/scm/utils/kernel/kexec/kexec-tools.git
+- git://git.kernel.org/pub/scm/utils/kernel/kexec/kexec-tools.git
+- http://www.kernel.org/pub/scm/utils/kernel/kexec/kexec-tools.git
There is also a gitweb interface available at
http://www.kernel.org/git/?p=utils/kernel/kexec/kexec-tools.git
@@ -81,25 +80,25 @@ http://www.kernel.org/git/?p=utils/kernel/kexec/kexec-tools.git
More information about kexec-tools can be found at
http://horms.net/projects/kexec/
-3) Unpack the tarball with the tar command, as follows:
+3) Unpack the tarball with the tar command, as follows::
- tar xvpzf kexec-tools.tar.gz
+ tar xvpzf kexec-tools.tar.gz
-4) Change to the kexec-tools directory, as follows:
+4) Change to the kexec-tools directory, as follows::
- cd kexec-tools-VERSION
+ cd kexec-tools-VERSION
-5) Configure the package, as follows:
+5) Configure the package, as follows::
- ./configure
+ ./configure
-6) Compile the package, as follows:
+6) Compile the package, as follows::
- make
+ make
-7) Install the package, as follows:
+7) Install the package, as follows::
- make install
+ make install
Build the system and dump-capture kernels
@@ -126,25 +125,25 @@ dump-capture kernels for enabling kdump support.
System kernel config options
----------------------------
-1) Enable "kexec system call" in "Processor type and features."
+1) Enable "kexec system call" in "Processor type and features."::
- CONFIG_KEXEC=y
+ CONFIG_KEXEC=y
2) Enable "sysfs file system support" in "Filesystem" -> "Pseudo
- filesystems." This is usually enabled by default.
+ filesystems." This is usually enabled by default::
- CONFIG_SYSFS=y
+ CONFIG_SYSFS=y
Note that "sysfs file system support" might not appear in the "Pseudo
filesystems" menu if "Configure standard kernel features (for small
systems)" is not enabled in "General Setup." In this case, check the
- .config file itself to ensure that sysfs is turned on, as follows:
+ .config file itself to ensure that sysfs is turned on, as follows::
- grep 'CONFIG_SYSFS' .config
+ grep 'CONFIG_SYSFS' .config
-3) Enable "Compile the kernel with debug info" in "Kernel hacking."
+3) Enable "Compile the kernel with debug info" in "Kernel hacking."::
- CONFIG_DEBUG_INFO=Y
+ CONFIG_DEBUG_INFO=Y
This causes the kernel to be built with debug symbols. The dump
analysis tools require a vmlinux with debug symbols in order to read
@@ -154,29 +153,32 @@ Dump-capture kernel config options (Arch Independent)
-----------------------------------------------------
1) Enable "kernel crash dumps" support under "Processor type and
- features":
+ features"::
- CONFIG_CRASH_DUMP=y
+ CONFIG_CRASH_DUMP=y
-2) Enable "/proc/vmcore support" under "Filesystems" -> "Pseudo filesystems".
+2) Enable "/proc/vmcore support" under "Filesystems" -> "Pseudo filesystems"::
+
+ CONFIG_PROC_VMCORE=y
- CONFIG_PROC_VMCORE=y
(CONFIG_PROC_VMCORE is set by default when CONFIG_CRASH_DUMP is selected.)
Dump-capture kernel config options (Arch Dependent, i386 and x86_64)
--------------------------------------------------------------------
1) On i386, enable high memory support under "Processor type and
- features":
+ features"::
- CONFIG_HIGHMEM64G=y
- or
- CONFIG_HIGHMEM4G
+ CONFIG_HIGHMEM64G=y
+
+ or::
+
+ CONFIG_HIGHMEM4G
2) On i386 and x86_64, disable symmetric multi-processing support
- under "Processor type and features":
+ under "Processor type and features"::
- CONFIG_SMP=n
+ CONFIG_SMP=n
(If CONFIG_SMP=y, then specify maxcpus=1 on the kernel command line
when loading the dump-capture kernel, see section "Load the Dump-capture
@@ -184,9 +186,9 @@ Dump-capture kernel config options (Arch Dependent, i386 and x86_64)
3) If one wants to build and use a relocatable kernel,
Enable "Build a relocatable kernel" support under "Processor type and
- features"
+ features"::
- CONFIG_RELOCATABLE=y
+ CONFIG_RELOCATABLE=y
4) Use a suitable value for "Physical address where the kernel is
loaded" (under "Processor type and features"). This only appears when
@@ -211,13 +213,13 @@ Dump-capture kernel config options (Arch Dependent, i386 and x86_64)
Dump-capture kernel config options (Arch Dependent, ppc64)
----------------------------------------------------------
-1) Enable "Build a kdump crash kernel" support under "Kernel" options:
+1) Enable "Build a kdump crash kernel" support under "Kernel" options::
- CONFIG_CRASH_DUMP=y
+ CONFIG_CRASH_DUMP=y
-2) Enable "Build a relocatable kernel" support
+2) Enable "Build a relocatable kernel" support::
- CONFIG_RELOCATABLE=y
+ CONFIG_RELOCATABLE=y
Make and install the kernel and its modules.
@@ -231,11 +233,13 @@ Dump-capture kernel config options (Arch Dependent, ia64)
The crashkernel region can be automatically placed by the system
kernel at run time. This is done by specifying the base address as 0,
- or omitting it all together.
+ or omitting it all together::
- crashkernel=256M@0
- or
- crashkernel=256M
+ crashkernel=256M@0
+
+ or::
+
+ crashkernel=256M
If the start address is specified, note that the start address of the
kernel will be aligned to 64Mb, so if the start address is not then
@@ -245,9 +249,9 @@ Dump-capture kernel config options (Arch Dependent, arm)
----------------------------------------------------------
- To use a relocatable kernel,
- Enable "AUTO_ZRELADDR" support under "Boot" options:
+ Enable "AUTO_ZRELADDR" support under "Boot" options::
- AUTO_ZRELADDR=y
+ AUTO_ZRELADDR=y
Dump-capture kernel config options (Arch Dependent, arm64)
----------------------------------------------------------
@@ -265,12 +269,12 @@ on the value of System RAM -- that's mostly for distributors that pre-setup
the kernel command line to avoid a unbootable system after some memory has
been removed from the machine.
-The syntax is:
+The syntax is::
crashkernel=<range1>:<size1>[,<range2>:<size2>,...][@offset]
range=start-[end]
-For example:
+For example::
crashkernel=512M-2G:64M,2G-:128M
@@ -326,35 +330,46 @@ can choose to load the uncompressed vmlinux or compressed bzImage/vmlinuz
of dump-capture kernel. Following is the summary.
For i386 and x86_64:
+
- Use vmlinux if kernel is not relocatable.
- Use bzImage/vmlinuz if kernel is relocatable.
+
For ppc64:
+
- Use vmlinux
+
For ia64:
+
- Use vmlinux or vmlinuz.gz
+
For s390x:
+
- Use image or bzImage
+
For arm:
+
- Use zImage
+
For arm64:
+
- Use vmlinux or Image
If you are using an uncompressed vmlinux image then use following command
-to load dump-capture kernel.
+to load dump-capture kernel::
kexec -p <dump-capture-kernel-vmlinux-image> \
--initrd=<initrd-for-dump-capture-kernel> --args-linux \
--append="root=<root-dev> <arch-specific-options>"
If you are using a compressed bzImage/vmlinuz, then use following command
-to load dump-capture kernel.
+to load dump-capture kernel::
kexec -p <dump-capture-kernel-bzImage> \
--initrd=<initrd-for-dump-capture-kernel> \
--append="root=<root-dev> <arch-specific-options>"
If you are using a compressed zImage, then use following command
-to load dump-capture kernel.
+to load dump-capture kernel::
kexec --type zImage -p <dump-capture-kernel-bzImage> \
--initrd=<initrd-for-dump-capture-kernel> \
@@ -362,7 +377,7 @@ to load dump-capture kernel.
--append="root=<root-dev> <arch-specific-options>"
If you are using an uncompressed Image, then use following command
-to load dump-capture kernel.
+to load dump-capture kernel::
kexec -p <dump-capture-kernel-Image> \
--initrd=<initrd-for-dump-capture-kernel> \
@@ -376,18 +391,23 @@ Following are the arch specific command line options to be used while
loading dump-capture kernel.
For i386, x86_64 and ia64:
+
"1 irqpoll maxcpus=1 reset_devices"
For ppc64:
+
"1 maxcpus=1 noirqdistrib reset_devices"
For s390x:
+
"1 maxcpus=1 cgroup_disable=memory"
For arm:
+
"1 maxcpus=1 reset_devices"
For arm64:
+
"1 maxcpus=1 reset_devices"
Notes on loading the dump-capture kernel:
@@ -464,7 +484,7 @@ Write Out the Dump File
=======================
After the dump-capture kernel is booted, write out the dump file with
-the following command:
+the following command::
cp /proc/vmcore <dump-file>
@@ -476,7 +496,7 @@ Before analyzing the dump image, you should reboot into a stable kernel.
You can do limited analysis using GDB on the dump file copied out of
/proc/vmcore. Use the debug vmlinux built with -g and run the following
-command:
+command::
gdb vmlinux <dump-file>
@@ -504,6 +524,11 @@ to achieve the same behaviour.
Contact
=======
-Vivek Goyal (vgoyal@redhat.com)
-Maneesh Soni (maneesh@in.ibm.com)
+- Vivek Goyal (vgoyal@redhat.com)
+- Maneesh Soni (maneesh@in.ibm.com)
+GDB macros
+==========
+
+.. include:: gdbmacros.txt
+ :literal:
diff --git a/Documentation/kdump/vmcoreinfo.txt b/Documentation/kdump/vmcoreinfo.txt
index bb94a4bd597a..007a6b86e0ee 100644
--- a/Documentation/kdump/vmcoreinfo.txt
+++ b/Documentation/kdump/vmcoreinfo.txt
@@ -1,8 +1,7 @@
-================================================================
- VMCOREINFO
-================================================================
+==========
+VMCOREINFO
+==========
-===========
What is it?
===========
@@ -12,7 +11,6 @@ values, field offsets, etc. These data are packed into an ELF note
section and used by user-space tools like crash and makedumpfile to
analyze a kernel's memory layout.
-================
Common variables
================
@@ -49,7 +47,7 @@ in a system, one bit position per node number. Used to keep track of
which nodes are in the system and online.
swapper_pg_dir
--------------
+--------------
The global page directory pointer of the kernel. Used to translate
virtual to physical addresses.
@@ -132,16 +130,14 @@ nodemask_t
The size of a nodemask_t type. Used to compute the number of online
nodes.
-(page, flags|_refcount|mapping|lru|_mapcount|private|compound_dtor|
- compound_order|compound_head)
--------------------------------------------------------------------
+(page, flags|_refcount|mapping|lru|_mapcount|private|compound_dtor|compound_order|compound_head)
+-------------------------------------------------------------------------------------------------
User-space tools compute their values based on the offset of these
variables. The variables are used when excluding unnecessary pages.
-(pglist_data, node_zones|nr_zones|node_mem_map|node_start_pfn|node_
- spanned_pages|node_id)
--------------------------------------------------------------------
+(pglist_data, node_zones|nr_zones|node_mem_map|node_start_pfn|node_spanned_pages|node_id)
+-----------------------------------------------------------------------------------------
On NUMA machines, each NUMA node has a pg_data_t to describe its memory
layout. On UMA machines there is a single pglist_data which describes the
@@ -245,21 +241,25 @@ NR_FREE_PAGES
On linux-2.6.21 or later, the number of free pages is in
vm_stat[NR_FREE_PAGES]. Used to get the number of free pages.
-PG_lru|PG_private|PG_swapcache|PG_swapbacked|PG_slab|PG_hwpoision
-|PG_head_mask|PAGE_BUDDY_MAPCOUNT_VALUE(~PG_buddy)
-|PAGE_OFFLINE_MAPCOUNT_VALUE(~PG_offline)
------------------------------------------------------------------
+PG_lru|PG_private|PG_swapcache|PG_swapbacked|PG_slab|PG_hwpoision|PG_head_mask
+------------------------------------------------------------------------------
Page attributes. These flags are used to filter various unnecessary for
dumping pages.
+PAGE_BUDDY_MAPCOUNT_VALUE(~PG_buddy)|PAGE_OFFLINE_MAPCOUNT_VALUE(~PG_offline)
+-----------------------------------------------------------------------------
+
+More page attributes. These flags are used to filter various unnecessary for
+dumping pages.
+
+
HUGETLB_PAGE_DTOR
-----------------
The HUGETLB_PAGE_DTOR flag denotes hugetlbfs pages. Makedumpfile
excludes these pages.
-======
x86_64
======
@@ -318,12 +318,12 @@ address.
Currently, sme_mask stores the value of the C-bit position. If needed,
additional SME-relevant info can be placed in that variable.
-For example:
-[ misc ][ enc bit ][ other misc SME info ]
-0000_0000_0000_0000_1000_0000_0000_0000_0000_0000_..._0000
-63 59 55 51 47 43 39 35 31 27 ... 3
+For example::
+
+ [ misc ][ enc bit ][ other misc SME info ]
+ 0000_0000_0000_0000_1000_0000_0000_0000_0000_0000_..._0000
+ 63 59 55 51 47 43 39 35 31 27 ... 3
-======
x86_32
======
@@ -335,7 +335,6 @@ of a higher page table lookup overhead, and also consumes more page
table space per process. Used to check whether PAE was enabled in the
crash kernel when converting virtual addresses to physical addresses.
-====
ia64
====
@@ -366,7 +365,6 @@ PGTABLE_3|PGTABLE_4
User-space tools need to know whether the crash kernel was in 3-level or
4-level paging mode. Used to distinguish the page table.
-=====
ARM64
=====
@@ -395,9 +393,8 @@ KERNELOFFSET
The kernel randomization offset. Used to compute the page offset. If
KASLR is disabled, this value is zero.
-====
arm
-====
+===
ARM_LPAE
--------
@@ -405,12 +402,11 @@ ARM_LPAE
It indicates whether the crash kernel supports large physical address
extensions. Used to translate virtual to physical addresses.
-====
s390
====
lowcore_ptr
-----------
+-----------
An array with a pointer to the lowcore of every CPU. Used to print the
psw and all registers information.
@@ -425,7 +421,6 @@ Used to get the vmalloc_start address from the high_memory symbol.
The maximum number of CPUs.
-=======
powerpc
=======
@@ -460,9 +455,8 @@ Page size definitions, i.e. 4k, 64k, or 16M.
Used to make vtop translations.
-vmemmap_backing|(vmemmap_backing, list)|(vmemmap_backing, phys)|
-(vmemmap_backing, virt_addr)
-----------------------------------------------------------------
+vmemmap_backing|(vmemmap_backing, list)|(vmemmap_backing, phys)|(vmemmap_backing, virt_addr)
+--------------------------------------------------------------------------------------------
The vmemmap virtual address space management does not have a traditional
page table to track which virtual struct pages are backed by a physical
@@ -480,7 +474,6 @@ member.
Used in vtop translations.
-==
sh
==
--
2.20.1
^ permalink raw reply related [flat|nested] 81+ messages in thread* [PATCH 20/57] docs: livepatch: convert it to ReST format
2019-04-16 2:55 [PATCH 00/57] Convert files to ReST Mauro Carvalho Chehab
` (13 preceding siblings ...)
2019-04-16 2:55 ` [PATCH 19/57] docs: kdump: convert it to ReST Mauro Carvalho Chehab
@ 2019-04-16 2:55 ` Mauro Carvalho Chehab
2019-04-16 8:43 ` Petr Mladek
2019-04-16 2:55 ` [PATCH 21/57] docs: locking: convert docs " Mauro Carvalho Chehab
` (37 subsequent siblings)
52 siblings, 1 reply; 81+ messages in thread
From: Mauro Carvalho Chehab @ 2019-04-16 2:55 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Josh Poimboeuf, Jiri Kosina, Miroslav Benes,
Petr Mladek, Joe Lawrence, live-patching
Convert livepatch documentation to ReST format. The changes
are mostly trivial, as the documents are already on a good
shape. Just a few markup changes are needed for Sphinx to
properly parse the docs.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
Documentation/livepatch/callbacks.txt | 12 +-
.../livepatch/cumulative-patches.txt | 14 +-
Documentation/livepatch/livepatch.txt | 56 ++---
Documentation/livepatch/module-elf-format.txt | 211 ++++++++++--------
Documentation/livepatch/shadow-vars.txt | 65 ++++--
5 files changed, 199 insertions(+), 159 deletions(-)
diff --git a/Documentation/livepatch/callbacks.txt b/Documentation/livepatch/callbacks.txt
index 182e31d4abce..d76d1f0d9fcf 100644
--- a/Documentation/livepatch/callbacks.txt
+++ b/Documentation/livepatch/callbacks.txt
@@ -30,16 +30,20 @@ be patched, irrespective of the target klp_object's current state.
Callbacks can be registered for the following livepatch actions:
- * Pre-patch - before a klp_object is patched
+ * Pre-patch
+ - before a klp_object is patched
- * Post-patch - after a klp_object has been patched and is active
+ * Post-patch
+ - after a klp_object has been patched and is active
across all tasks
- * Pre-unpatch - before a klp_object is unpatched (ie, patched code is
+ * Pre-unpatch
+ - before a klp_object is unpatched (ie, patched code is
active), used to clean up post-patch callback
resources
- * Post-unpatch - after a klp_object has been patched, all code has
+ * Post-unpatch
+ - after a klp_object has been patched, all code has
been restored and no tasks are running patched code,
used to cleanup pre-patch callback resources
diff --git a/Documentation/livepatch/cumulative-patches.txt b/Documentation/livepatch/cumulative-patches.txt
index 0012808e8d44..1931f318976a 100644
--- a/Documentation/livepatch/cumulative-patches.txt
+++ b/Documentation/livepatch/cumulative-patches.txt
@@ -18,7 +18,7 @@ Usage
-----
The atomic replace can be enabled by setting "replace" flag in struct klp_patch,
-for example:
+for example::
static struct klp_patch patch = {
.mod = THIS_MODULE,
@@ -49,19 +49,19 @@ Features
The atomic replace allows:
- + Atomically revert some functions in a previous patch while
+ - Atomically revert some functions in a previous patch while
upgrading other functions.
- + Remove eventual performance impact caused by core redirection
+ - Remove eventual performance impact caused by core redirection
for functions that are no longer patched.
- + Decrease user confusion about dependencies between livepatches.
+ - Decrease user confusion about dependencies between livepatches.
Limitations:
------------
- + Once the operation finishes, there is no straightforward way
+ - Once the operation finishes, there is no straightforward way
to reverse it and restore the replaced patches atomically.
A good practice is to set .replace flag in any released livepatch.
@@ -74,7 +74,7 @@ Limitations:
only when the transition was not forced.
- + Only the (un)patching callbacks from the _new_ cumulative livepatch are
+ - Only the (un)patching callbacks from the _new_ cumulative livepatch are
executed. Any callbacks from the replaced patches are ignored.
In other words, the cumulative patch is responsible for doing any actions
@@ -93,7 +93,7 @@ Limitations:
enabled patches were called.
- + There is no special handling of shadow variables. Livepatch authors
+ - There is no special handling of shadow variables. Livepatch authors
must create their own rules how to pass them from one cumulative
patch to the other. Especially that they should not blindly remove
them in module_exit() functions.
diff --git a/Documentation/livepatch/livepatch.txt b/Documentation/livepatch/livepatch.txt
index 4627b41ff02e..2a1bb3d34b11 100644
--- a/Documentation/livepatch/livepatch.txt
+++ b/Documentation/livepatch/livepatch.txt
@@ -4,22 +4,22 @@ Livepatch
This document outlines basic information about kernel livepatching.
-Table of Contents:
+.. Table of Contents:
-1. Motivation
-2. Kprobes, Ftrace, Livepatching
-3. Consistency model
-4. Livepatch module
- 4.1. New functions
- 4.2. Metadata
-5. Livepatch life-cycle
- 5.1. Loading
- 5.2. Enabling
- 5.3. Replacing
- 5.4. Disabling
- 5.5. Removing
-6. Sysfs
-7. Limitations
+ 1. Motivation
+ 2. Kprobes, Ftrace, Livepatching
+ 3. Consistency model
+ 4. Livepatch module
+ 4.1. New functions
+ 4.2. Metadata
+ 5. Livepatch life-cycle
+ 5.1. Loading
+ 5.2. Enabling
+ 5.3. Replacing
+ 5.4. Disabling
+ 5.5. Removing
+ 6. Sysfs
+ 7. Limitations
1. Motivation
@@ -40,14 +40,14 @@ There are multiple mechanisms in the Linux kernel that are directly related
to redirection of code execution; namely: kernel probes, function tracing,
and livepatching:
- + The kernel probes are the most generic. The code can be redirected by
+ - The kernel probes are the most generic. The code can be redirected by
putting a breakpoint instruction instead of any instruction.
- + The function tracer calls the code from a predefined location that is
+ - The function tracer calls the code from a predefined location that is
close to the function entry point. This location is generated by the
compiler using the '-pg' gcc option.
- + Livepatching typically needs to redirect the code at the very beginning
+ - Livepatching typically needs to redirect the code at the very beginning
of the function entry before the function parameters or the stack
are in any way modified.
@@ -258,7 +258,7 @@ Documentation/livepatch/module-elf-format.txt for more details.
The patch is described by several structures that split the information
into three levels:
- + struct klp_func is defined for each patched function. It describes
+ - struct klp_func is defined for each patched function. It describes
the relation between the original and the new implementation of a
particular function.
@@ -275,7 +275,7 @@ into three levels:
only for a particular object ( vmlinux or a kernel module ). Note that
kallsyms allows for searching symbols according to the object name.
- + struct klp_object defines an array of patched functions (struct
+ - struct klp_object defines an array of patched functions (struct
klp_func) in the same object. Where the object is either vmlinux
(NULL) or a module name.
@@ -285,7 +285,7 @@ into three levels:
only when they are available.
- + struct klp_patch defines an array of patched objects (struct
+ - struct klp_patch defines an array of patched objects (struct
klp_object).
This structure handles all patched functions consistently and eventually,
@@ -337,14 +337,16 @@ operation fails.
Second, livepatch enters into a transition state where tasks are converging
to the patched state. If an original function is patched for the first
time, a function specific struct klp_ops is created and an universal
-ftrace handler is registered[*]. This stage is indicated by a value of '1'
+ftrace handler is registered\ [#]_. This stage is indicated by a value of '1'
in /sys/kernel/livepatch/<name>/transition. For more information about
this process, see the "Consistency model" section.
Finally, once all tasks have been patched, the 'transition' value changes
to '0'.
-[*] Note that functions might be patched multiple times. The ftrace handler
+.. [#]
+
+ Note that functions might be patched multiple times. The ftrace handler
is registered only once for a given function. Further patches just add
an entry to the list (see field `func_stack`) of the struct klp_ops.
The right implementation is selected by the ftrace handler, see
@@ -421,7 +423,7 @@ See Documentation/ABI/testing/sysfs-kernel-livepatch for more details.
The current Livepatch implementation has several limitations:
- + Only functions that can be traced could be patched.
+ - Only functions that can be traced could be patched.
Livepatch is based on the dynamic ftrace. In particular, functions
implementing ftrace or the livepatch ftrace handler could not be
@@ -431,7 +433,7 @@ The current Livepatch implementation has several limitations:
- + Livepatch works reliably only when the dynamic ftrace is located at
+ - Livepatch works reliably only when the dynamic ftrace is located at
the very beginning of the function.
The function need to be redirected before the stack or the function
@@ -445,7 +447,7 @@ The current Livepatch implementation has several limitations:
this is handled on the ftrace level.
- + Kretprobes using the ftrace framework conflict with the patched
+ - Kretprobes using the ftrace framework conflict with the patched
functions.
Both kretprobes and livepatches use a ftrace handler that modifies
@@ -453,7 +455,7 @@ The current Livepatch implementation has several limitations:
is rejected when the handler is already in use by the other.
- + Kprobes in the original function are ignored when the code is
+ - Kprobes in the original function are ignored when the code is
redirected to the new implementation.
There is a work in progress to add warnings about this situation.
diff --git a/Documentation/livepatch/module-elf-format.txt b/Documentation/livepatch/module-elf-format.txt
index f21a5289a09c..7f557c6f6deb 100644
--- a/Documentation/livepatch/module-elf-format.txt
+++ b/Documentation/livepatch/module-elf-format.txt
@@ -4,29 +4,29 @@ Livepatch module Elf format
This document outlines the Elf format requirements that livepatch modules must follow.
------------------
-Table of Contents
------------------
-0. Background and motivation
-1. Livepatch modinfo field
-2. Livepatch relocation sections
- 2.1 What are livepatch relocation sections?
- 2.2 Livepatch relocation section format
- 2.2.1 Required flags
- 2.2.2 Required name format
- 2.2.3 Example livepatch relocation section names
- 2.2.4 Example `readelf --sections` output
- 2.2.5 Example `readelf --relocs` output
-3. Livepatch symbols
- 3.1 What are livepatch symbols?
- 3.2 A livepatch module's symbol table
- 3.3 Livepatch symbol format
- 3.3.1 Required flags
- 3.3.2 Required name format
- 3.3.3 Example livepatch symbol names
- 3.3.4 Example `readelf --symbols` output
-4. Architecture-specific sections
-5. Symbol table and Elf section access
+
+.. Table of Contents
+
+ 0. Background and motivation
+ 1. Livepatch modinfo field
+ 2. Livepatch relocation sections
+ 2.1 What are livepatch relocation sections?
+ 2.2 Livepatch relocation section format
+ 2.2.1 Required flags
+ 2.2.2 Required name format
+ 2.2.3 Example livepatch relocation section names
+ 2.2.4 Example `readelf --sections` output
+ 2.2.5 Example `readelf --relocs` output
+ 3. Livepatch symbols
+ 3.1 What are livepatch symbols?
+ 3.2 A livepatch module's symbol table
+ 3.3 Livepatch symbol format
+ 3.3.1 Required flags
+ 3.3.2 Required name format
+ 3.3.3 Example livepatch symbol names
+ 3.3.4 Example `readelf --symbols` output
+ 4. Architecture-specific sections
+ 5. Symbol table and Elf section access
----------------------------
0. Background and motivation
@@ -89,12 +89,15 @@ used by the kernel module loader to identify livepatch modules.
Example modinfo output:
-----------------------
-% modinfo livepatch-meminfo.ko
-filename: livepatch-meminfo.ko
-livepatch: Y
-license: GPL
-depends:
-vermagic: 4.3.0+ SMP mod_unload
+
+::
+
+ % modinfo livepatch-meminfo.ko
+ filename: livepatch-meminfo.ko
+ livepatch: Y
+ license: GPL
+ depends:
+ vermagic: 4.3.0+ SMP mod_unload
--------------------------------
2. Livepatch relocation sections
@@ -142,17 +145,18 @@ be copied into memory along with the other SHF_ALLOC sections).
2.2.2 Required name format
--------------------------
-The name of a livepatch relocation section must conform to the following format:
+The name of a livepatch relocation section must conform to the following
+format::
-.klp.rela.objname.section_name
-^ ^^ ^ ^ ^
-|________||_____| |__________|
- [A] [B] [C]
+ .klp.rela.objname.section_name
+ ^ ^^ ^ ^ ^
+ |________||_____| |__________|
+ [A] [B] [C]
-[A] The relocation section name is prefixed with the string ".klp.rela."
-[B] The name of the object (i.e. "vmlinux" or name of module) to
- which the relocation section belongs follows immediately after the prefix.
-[C] The actual name of the section to which this relocation section applies.
+ [A] The relocation section name is prefixed with the string ".klp.rela."
+ [B] The name of the object (i.e. "vmlinux" or name of module) to
+ which the relocation section belongs follows immediately after the prefix.
+ [C] The actual name of the section to which this relocation section applies.
2.2.3 Example livepatch relocation section names:
-------------------------------------------------
@@ -162,6 +166,9 @@ The name of a livepatch relocation section must conform to the following format:
2.2.4 Example `readelf --sections` output for a patch
module that patches vmlinux and modules 9p, btrfs, ext4:
--------------------------------------------------------
+
+::
+
Section Headers:
[Nr] Name Type Address Off Size ES Flg Lk Inf Al
[ snip ]
@@ -175,23 +182,26 @@ module that patches vmlinux and modules 9p, btrfs, ext4:
[ snip ] ^ ^
| |
[*] [*]
-[*] Livepatch relocation sections are SHT_RELA sections but with a few special
-characteristics. Notice that they are marked SHF_ALLOC ("A") so that they will
-not be discarded when the module is loaded into memory, as well as with the
-SHF_RELA_LIVEPATCH flag ("o" - for OS-specific).
+ [*] Livepatch relocation sections are SHT_RELA sections but with a few special
+ characteristics. Notice that they are marked SHF_ALLOC ("A") so that they will
+ not be discarded when the module is loaded into memory, as well as with the
+ SHF_RELA_LIVEPATCH flag ("o" - for OS-specific).
2.2.5 Example `readelf --relocs` output for a patch module:
-----------------------------------------------------------
-Relocation section '.klp.rela.btrfs.text.btrfs_feature_attr_show' at offset 0x2ba0 contains 4 entries:
- Offset Info Type Symbol's Value Symbol's Name + Addend
-000000000000001f 0000005e00000002 R_X86_64_PC32 0000000000000000 .klp.sym.vmlinux.printk,0 - 4
-0000000000000028 0000003d0000000b R_X86_64_32S 0000000000000000 .klp.sym.btrfs.btrfs_ktype,0 + 0
-0000000000000036 0000003b00000002 R_X86_64_PC32 0000000000000000 .klp.sym.btrfs.can_modify_feature.isra.3,0 - 4
-000000000000004c 0000004900000002 R_X86_64_PC32 0000000000000000 .klp.sym.vmlinux.snprintf,0 - 4
-[ snip ] ^
- |
+
+::
+
+ Relocation section '.klp.rela.btrfs.text.btrfs_feature_attr_show' at offset 0x2ba0 contains 4 entries:
+ Offset Info Type Symbol's Value Symbol's Name + Addend
+ 000000000000001f 0000005e00000002 R_X86_64_PC32 0000000000000000 .klp.sym.vmlinux.printk,0 - 4
+ 0000000000000028 0000003d0000000b R_X86_64_32S 0000000000000000 .klp.sym.btrfs.btrfs_ktype,0 + 0
+ 0000000000000036 0000003b00000002 R_X86_64_PC32 0000000000000000 .klp.sym.btrfs.can_modify_feature.isra.3,0 - 4
+ 000000000000004c 0000004900000002 R_X86_64_PC32 0000000000000000 .klp.sym.vmlinux.snprintf,0 - 4
+ [ snip ] ^
+ |
[*]
-[*] Every symbol referenced by a relocation is a livepatch symbol.
+ [*] Every symbol referenced by a relocation is a livepatch symbol.
--------------------
3. Livepatch symbols
@@ -231,18 +241,19 @@ relocation section refer to their respective symbols with their symbol indices,
and the original symbol indices (and thus the symtab ordering) must be
preserved in order for apply_relocate_add() to find the right symbol.
-For example, take this particular rela from a livepatch module:
-Relocation section '.klp.rela.btrfs.text.btrfs_feature_attr_show' at offset 0x2ba0 contains 4 entries:
- Offset Info Type Symbol's Value Symbol's Name + Addend
-000000000000001f 0000005e00000002 R_X86_64_PC32 0000000000000000 .klp.sym.vmlinux.printk,0 - 4
+For example, take this particular rela from a livepatch module:::
-This rela refers to the symbol '.klp.sym.vmlinux.printk,0', and the symbol index is encoded
-in 'Info'. Here its symbol index is 0x5e, which is 94 in decimal, which refers to the
-symbol index 94.
-And in this patch module's corresponding symbol table, symbol index 94 refers to that very symbol:
-[ snip ]
-94: 0000000000000000 0 NOTYPE GLOBAL DEFAULT OS [0xff20] .klp.sym.vmlinux.printk,0
-[ snip ]
+ Relocation section '.klp.rela.btrfs.text.btrfs_feature_attr_show' at offset 0x2ba0 contains 4 entries:
+ Offset Info Type Symbol's Value Symbol's Name + Addend
+ 000000000000001f 0000005e00000002 R_X86_64_PC32 0000000000000000 .klp.sym.vmlinux.printk,0 - 4
+
+ This rela refers to the symbol '.klp.sym.vmlinux.printk,0', and the symbol index is encoded
+ in 'Info'. Here its symbol index is 0x5e, which is 94 in decimal, which refers to the
+ symbol index 94.
+ And in this patch module's corresponding symbol table, symbol index 94 refers to that very symbol:
+ [ snip ]
+ 94: 0000000000000000 0 NOTYPE GLOBAL DEFAULT OS [0xff20] .klp.sym.vmlinux.printk,0
+ [ snip ]
---------------------------
3.3 Livepatch symbol format
@@ -256,42 +267,48 @@ See include/uapi/linux/elf.h for the actual definitions.
3.3.2 Required name format
--------------------------
-Livepatch symbol names must conform to the following format:
+Livepatch symbol names must conform to the following format::
-.klp.sym.objname.symbol_name,sympos
-^ ^^ ^ ^ ^ ^
-|_______||_____| |_________| |
- [A] [B] [C] [D]
+ .klp.sym.objname.symbol_name,sympos
+ ^ ^^ ^ ^ ^ ^
+ |_______||_____| |_________| |
+ [A] [B] [C] [D]
-[A] The symbol name is prefixed with the string ".klp.sym."
-[B] The name of the object (i.e. "vmlinux" or name of module) to
- which the symbol belongs follows immediately after the prefix.
-[C] The actual name of the symbol.
-[D] The position of the symbol in the object (as according to kallsyms)
- This is used to differentiate duplicate symbols within the same
- object. The symbol position is expressed numerically (0, 1, 2...).
- The symbol position of a unique symbol is 0.
+ [A] The symbol name is prefixed with the string ".klp.sym."
+ [B] The name of the object (i.e. "vmlinux" or name of module) to
+ which the symbol belongs follows immediately after the prefix.
+ [C] The actual name of the symbol.
+ [D] The position of the symbol in the object (as according to kallsyms)
+ This is used to differentiate duplicate symbols within the same
+ object. The symbol position is expressed numerically (0, 1, 2...).
+ The symbol position of a unique symbol is 0.
3.3.3 Example livepatch symbol names:
-------------------------------------
-.klp.sym.vmlinux.snprintf,0
-.klp.sym.vmlinux.printk,0
-.klp.sym.btrfs.btrfs_ktype,0
+
+::
+
+ .klp.sym.vmlinux.snprintf,0
+ .klp.sym.vmlinux.printk,0
+ .klp.sym.btrfs.btrfs_ktype,0
3.3.4 Example `readelf --symbols` output for a patch module:
------------------------------------------------------------
-Symbol table '.symtab' contains 127 entries:
- Num: Value Size Type Bind Vis Ndx Name
- [ snip ]
- 73: 0000000000000000 0 NOTYPE GLOBAL DEFAULT OS [0xff20] .klp.sym.vmlinux.snprintf,0
- 74: 0000000000000000 0 NOTYPE GLOBAL DEFAULT OS [0xff20] .klp.sym.vmlinux.capable,0
- 75: 0000000000000000 0 NOTYPE GLOBAL DEFAULT OS [0xff20] .klp.sym.vmlinux.find_next_bit,0
- 76: 0000000000000000 0 NOTYPE GLOBAL DEFAULT OS [0xff20] .klp.sym.vmlinux.si_swapinfo,0
- [ snip ] ^
- |
- [*]
-[*] Note that the 'Ndx' (Section index) for these symbols is SHN_LIVEPATCH (0xff20).
- "OS" means OS-specific.
+
+::
+
+ Symbol table '.symtab' contains 127 entries:
+ Num: Value Size Type Bind Vis Ndx Name
+ [ snip ]
+ 73: 0000000000000000 0 NOTYPE GLOBAL DEFAULT OS [0xff20] .klp.sym.vmlinux.snprintf,0
+ 74: 0000000000000000 0 NOTYPE GLOBAL DEFAULT OS [0xff20] .klp.sym.vmlinux.capable,0
+ 75: 0000000000000000 0 NOTYPE GLOBAL DEFAULT OS [0xff20] .klp.sym.vmlinux.find_next_bit,0
+ 76: 0000000000000000 0 NOTYPE GLOBAL DEFAULT OS [0xff20] .klp.sym.vmlinux.si_swapinfo,0
+ [ snip ] ^
+ |
+ [*]
+ [*] Note that the 'Ndx' (Section index) for these symbols is SHN_LIVEPATCH (0xff20).
+ "OS" means OS-specific.
---------------------------------
4. Architecture-specific sections
@@ -313,11 +330,11 @@ Since apply_relocate_add() requires access to a module's section headers,
symbol table, and relocation section indices, Elf information is preserved for
livepatch modules and is made accessible by the module loader through
module->klp_info, which is a klp_modinfo struct. When a livepatch module loads,
-this struct is filled in by the module loader. Its fields are documented below:
+this struct is filled in by the module loader. Its fields are documented below::
-struct klp_modinfo {
- Elf_Ehdr hdr; /* Elf header */
- Elf_Shdr *sechdrs; /* Section header table */
- char *secstrings; /* String table for the section headers */
- unsigned int symndx; /* The symbol table section index */
-};
+ struct klp_modinfo {
+ Elf_Ehdr hdr; /* Elf header */
+ Elf_Shdr *sechdrs; /* Section header table */
+ char *secstrings; /* String table for the section headers */
+ unsigned int symndx; /* The symbol table section index */
+ };
diff --git a/Documentation/livepatch/shadow-vars.txt b/Documentation/livepatch/shadow-vars.txt
index ecc09a7be5dd..c05715aeafa4 100644
--- a/Documentation/livepatch/shadow-vars.txt
+++ b/Documentation/livepatch/shadow-vars.txt
@@ -27,10 +27,13 @@ A hashtable references all shadow variables. These references are
stored and retrieved through a <obj, id> pair.
* The klp_shadow variable data structure encapsulates both tracking
-meta-data and shadow-data:
+ meta-data and shadow-data:
+
- meta-data
+
- obj - pointer to parent object
- id - data identifier
+
- data[] - storage for shadow data
It is important to note that the klp_shadow_alloc() and
@@ -47,31 +50,43 @@ to do actions that can be done only once when a new variable is allocated.
* klp_shadow_alloc() - allocate and add a new shadow variable
- search hashtable for <obj, id> pair
+
- if exists
+
- WARN and return NULL
+
- if <obj, id> doesn't already exist
+
- allocate a new shadow variable
- initialize the variable using a custom constructor and data when provided
- add <obj, id> to the global hashtable
* klp_shadow_get_or_alloc() - get existing or alloc a new shadow variable
- search hashtable for <obj, id> pair
+
- if exists
+
- return existing shadow variable
+
- if <obj, id> doesn't already exist
+
- allocate a new shadow variable
- initialize the variable using a custom constructor and data when provided
- add <obj, id> pair to the global hashtable
* klp_shadow_free() - detach and free a <obj, id> shadow variable
- find and remove a <obj, id> reference from global hashtable
+
- if found
+
- call destructor function if defined
- free shadow variable
* klp_shadow_free_all() - detach and free all <*, id> shadow variables
- find and remove any <*, id> references from global hashtable
+
- if found
+
- call destructor function if defined
- free shadow variable
@@ -102,12 +117,12 @@ parent "goes live" (ie, any shadow variable get-API requests are made
for this <obj, id> pair.)
For commit 1d147bfa6429, when a parent sta_info structure is allocated,
-allocate a shadow copy of the ps_lock pointer, then initialize it:
+allocate a shadow copy of the ps_lock pointer, then initialize it::
-#define PS_LOCK 1
-struct sta_info *sta_info_alloc(struct ieee80211_sub_if_data *sdata,
- const u8 *addr, gfp_t gfp)
-{
+ #define PS_LOCK 1
+ struct sta_info *sta_info_alloc(struct ieee80211_sub_if_data *sdata,
+ const u8 *addr, gfp_t gfp)
+ {
struct sta_info *sta;
spinlock_t *ps_lock;
@@ -123,10 +138,10 @@ struct sta_info *sta_info_alloc(struct ieee80211_sub_if_data *sdata,
...
When requiring a ps_lock, query the shadow variable API to retrieve one
-for a specific struct sta_info:
+for a specific struct sta_info:::
-void ieee80211_sta_ps_deliver_wakeup(struct sta_info *sta)
-{
+ void ieee80211_sta_ps_deliver_wakeup(struct sta_info *sta)
+ {
spinlock_t *ps_lock;
/* sync with ieee80211_tx_h_unicast_ps_buf */
@@ -136,10 +151,10 @@ void ieee80211_sta_ps_deliver_wakeup(struct sta_info *sta)
...
When the parent sta_info structure is freed, first free the shadow
-variable:
+variable::
-void sta_info_free(struct ieee80211_local *local, struct sta_info *sta)
-{
+ void sta_info_free(struct ieee80211_local *local, struct sta_info *sta)
+ {
klp_shadow_free(sta, PS_LOCK, NULL);
kfree(sta);
...
@@ -155,19 +170,19 @@ these cases, the klp_shadow_get_or_alloc() call can be used to attach
shadow variables to parents already in-flight.
For commit 1d147bfa6429, a good spot to allocate a shadow spinlock is
-inside ieee80211_sta_ps_deliver_wakeup():
+inside ieee80211_sta_ps_deliver_wakeup()::
-int ps_lock_shadow_ctor(void *obj, void *shadow_data, void *ctor_data)
-{
+ int ps_lock_shadow_ctor(void *obj, void *shadow_data, void *ctor_data)
+ {
spinlock_t *lock = shadow_data;
spin_lock_init(lock);
return 0;
-}
+ }
-#define PS_LOCK 1
-void ieee80211_sta_ps_deliver_wakeup(struct sta_info *sta)
-{
+ #define PS_LOCK 1
+ void ieee80211_sta_ps_deliver_wakeup(struct sta_info *sta)
+ {
spinlock_t *ps_lock;
/* sync with ieee80211_tx_h_unicast_ps_buf */
@@ -200,10 +215,12 @@ suggests how to handle the parent object.
=============
* https://github.com/dynup/kpatch
-The livepatch implementation is based on the kpatch version of shadow
-variables.
+
+ The livepatch implementation is based on the kpatch version of shadow
+ variables.
* http://files.mkgnu.net/files/dynamos/doc/papers/dynamos_eurosys_07.pdf
-Dynamic and Adaptive Updates of Non-Quiescent Subsystems in Commodity
-Operating System Kernels (Kritis Makris, Kyung Dong Ryu 2007) presented
-a datatype update technique called "shadow data structures".
+
+ Dynamic and Adaptive Updates of Non-Quiescent Subsystems in Commodity
+ Operating System Kernels (Kritis Makris, Kyung Dong Ryu 2007) presented
+ a datatype update technique called "shadow data structures".
--
2.20.1
^ permalink raw reply related [flat|nested] 81+ messages in thread* Re: [PATCH 20/57] docs: livepatch: convert it to ReST format
2019-04-16 2:55 ` [PATCH 20/57] docs: livepatch: convert it to ReST format Mauro Carvalho Chehab
@ 2019-04-16 8:43 ` Petr Mladek
2019-04-16 11:47 ` Mauro Carvalho Chehab
0 siblings, 1 reply; 81+ messages in thread
From: Petr Mladek @ 2019-04-16 8:43 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: Linux Doc Mailing List, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Josh Poimboeuf, Jiri Kosina, Miroslav Benes,
Joe Lawrence, live-patching
On Mon 2019-04-15 23:55:45, Mauro Carvalho Chehab wrote:
> Convert livepatch documentation to ReST format. The changes
> are mostly trivial, as the documents are already on a good
> shape. Just a few markup changes are needed for Sphinx to
> properly parse the docs.
>
> Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
Thanks a lot for the conversion. I tried html output and
it looks very well.
Just a question. This patch does only the formatting.
The documentation is not really generated because the file
is not renamed to .rst. Also it is not referenced from
any top level documents. Is it by intention?
I am happy even for the conversion, so:
Reviewed-by: Petr Mladek <pmladek@suse.com>
Best Regards,
Petr
^ permalink raw reply [flat|nested] 81+ messages in thread
* Re: [PATCH 20/57] docs: livepatch: convert it to ReST format
2019-04-16 8:43 ` Petr Mladek
@ 2019-04-16 11:47 ` Mauro Carvalho Chehab
0 siblings, 0 replies; 81+ messages in thread
From: Mauro Carvalho Chehab @ 2019-04-16 11:47 UTC (permalink / raw)
To: Petr Mladek
Cc: Linux Doc Mailing List, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Josh Poimboeuf, Jiri Kosina, Miroslav Benes,
Joe Lawrence, live-patching
Em Tue, 16 Apr 2019 10:43:54 +0200
Petr Mladek <pmladek@suse.com> escreveu:
> On Mon 2019-04-15 23:55:45, Mauro Carvalho Chehab wrote:
> > Convert livepatch documentation to ReST format. The changes
> > are mostly trivial, as the documents are already on a good
> > shape. Just a few markup changes are needed for Sphinx to
> > properly parse the docs.
> >
> > Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
>
> Thanks a lot for the conversion. I tried html output and
> it looks very well.
>
> Just a question. This patch does only the formatting.
> The documentation is not really generated because the file
> is not renamed to .rst. Also it is not referenced from
> any top level documents. Is it by intention?
Yes. The rationale is simple: renaming to .rst would require
to add them on an index file (or otherwise build would produce lots
of warnings). As this series is doing a lot of such conversions,
assuming that some of those patches will go through different
trees, that would cause lots of conflicts at the main index files.
So, it sounds better to apply the conversion first and then,
on a better moment (maybe late during the merge window), do the
rename and add to the index files.
>
>
> I am happy even for the conversion, so:
>
> Reviewed-by: Petr Mladek <pmladek@suse.com>
>
> Best Regards,
> Petr
Thanks,
Mauro
^ permalink raw reply [flat|nested] 81+ messages in thread
* [PATCH 21/57] docs: locking: convert docs to ReST format
2019-04-16 2:55 [PATCH 00/57] Convert files to ReST Mauro Carvalho Chehab
` (14 preceding siblings ...)
2019-04-16 2:55 ` [PATCH 20/57] docs: livepatch: convert it to ReST format Mauro Carvalho Chehab
@ 2019-04-16 2:55 ` Mauro Carvalho Chehab
2019-04-16 2:55 ` [PATCH 22/57] docs: mic: convert it " Mauro Carvalho Chehab
` (36 subsequent siblings)
52 siblings, 0 replies; 81+ messages in thread
From: Mauro Carvalho Chehab @ 2019-04-16 2:55 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Peter Zijlstra, Ingo Molnar, Will Deacon
Convert the locking documents to ReST and add them to the
kernel development book where it belongs.
Most of the stuff here is just to make Sphinx to properly
parse the text file, as they're already in good shape,
not requiring massive changes in order to be parsed.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
Documentation/locking/lockdep-design.txt | 41 ++--
Documentation/locking/lockstat.txt | 219 ++++++++++++----------
Documentation/locking/locktorture.txt | 105 +++++++----
Documentation/locking/mutex-design.txt | 26 ++-
Documentation/locking/rt-mutex-design.txt | 135 +++++++------
Documentation/locking/rt-mutex.txt | 30 +--
Documentation/locking/spinlocks.txt | 32 ++--
Documentation/locking/ww-mutex-design.txt | 82 ++++----
8 files changed, 385 insertions(+), 285 deletions(-)
diff --git a/Documentation/locking/lockdep-design.txt b/Documentation/locking/lockdep-design.txt
index 39fae143c9cb..49707a5029c5 100644
--- a/Documentation/locking/lockdep-design.txt
+++ b/Documentation/locking/lockdep-design.txt
@@ -2,6 +2,7 @@ Runtime locking correctness validator
=====================================
started by Ingo Molnar <mingo@redhat.com>
+
additions by Arjan van de Ven <arjan@linux.intel.com>
Lock-class
@@ -42,7 +43,7 @@ Where STATE can be either one of (kernel/locking/lockdep_states.h)
- 'ever used' [ == !unused ]
When locking rules are violated, these state bits are presented in the
-locking error messages, inside curlies. A contrived example:
+locking error messages, inside curlies. A contrived example::
modprobe/2287 is trying to acquire lock:
(&sio_locks[i].lock){-.-.}, at: [<c02867fd>] mutex_lock+0x21/0x24
@@ -54,10 +55,12 @@ locking error messages, inside curlies. A contrived example:
The bit position indicates STATE, STATE-read, for each of the states listed
above, and the character displayed in each indicates:
+ === ===================================================
'.' acquired while irqs disabled and not in irq context
'-' acquired in irq context
'+' acquired with irqs enabled
'?' acquired in irq context with irqs enabled.
+ === ===================================================
Unused mutexes cannot be part of the cause of an error.
@@ -67,7 +70,7 @@ Single-lock state rules:
A softirq-unsafe lock-class is automatically hardirq-unsafe as well. The
following states are exclusive, and only one of them is allowed to be
-set for any lock-class:
+set for any lock-class::
<hardirq-safe> and <hardirq-unsafe>
<softirq-safe> and <softirq-unsafe>
@@ -81,7 +84,7 @@ Multi-lock dependency rules:
The same lock-class must not be acquired twice, because this could lead
to lock recursion deadlocks.
-Furthermore, two locks may not be taken in different order:
+Furthermore, two locks may not be taken in different order::
<L1> -> <L2>
<L2> -> <L1>
@@ -92,7 +95,7 @@ other locking sequence between the acquire-lock operations, the
validator will still track all dependencies between locks.)
Furthermore, the following usage based lock dependencies are not allowed
-between any two lock-classes:
+between any two lock-classes::
<hardirq-safe> -> <hardirq-unsafe>
<softirq-safe> -> <softirq-unsafe>
@@ -148,16 +151,16 @@ the ordering is not static.
In order to teach the validator about this correct usage model, new
versions of the various locking primitives were added that allow you to
specify a "nesting level". An example call, for the block device mutex,
-looks like this:
+looks like this::
-enum bdev_bd_mutex_lock_class
-{
+ enum bdev_bd_mutex_lock_class
+ {
BD_MUTEX_NORMAL,
BD_MUTEX_WHOLE,
BD_MUTEX_PARTITION
-};
+ };
- mutex_lock_nested(&bdev->bd_contains->bd_mutex, BD_MUTEX_PARTITION);
+mutex_lock_nested(&bdev->bd_contains->bd_mutex, BD_MUTEX_PARTITION);
In this case the locking is done on a bdev object that is known to be a
partition.
@@ -178,7 +181,7 @@ must be held: lockdep_assert_held*(&lock) and lockdep_*pin_lock(&lock).
As the name suggests, lockdep_assert_held* family of macros assert that a
particular lock is held at a certain time (and generate a WARN() otherwise).
This annotation is largely used all over the kernel, e.g. kernel/sched/
-core.c
+core.c::
void update_rq_clock(struct rq *rq)
{
@@ -197,7 +200,7 @@ out to be especially helpful to debug code with callbacks, where an upper
layer assumes a lock remains taken, but a lower layer thinks it can maybe drop
and reacquire the lock ("unwittingly" introducing races). lockdep_pin_lock()
returns a 'struct pin_cookie' that is then used by lockdep_unpin_lock() to check
-that nobody tampered with the lock, e.g. kernel/sched/sched.h
+that nobody tampered with the lock, e.g. kernel/sched/sched.h::
static inline void rq_pin_lock(struct rq *rq, struct rq_flags *rf)
{
@@ -224,7 +227,7 @@ correctness) in the sense that for every simple, standalone single-task
locking sequence that occurred at least once during the lifetime of the
kernel, the validator proves it with a 100% certainty that no
combination and timing of these locking sequences can cause any class of
-lock related deadlock. [*]
+lock related deadlock. [1]_
I.e. complex multi-CPU and multi-task locking scenarios do not have to
occur in practice to prove a deadlock: only the simple 'component'
@@ -243,7 +246,9 @@ possible combination of locking interaction between CPUs, combined with
every possible hardirq and softirq nesting scenario (which is impossible
to do in practice).
-[*] assuming that the validator itself is 100% correct, and no other
+.. [1]
+
+ assuming that the validator itself is 100% correct, and no other
part of the system corrupts the state of the validator in any way.
We also assume that all NMI/SMM paths [which could interrupt
even hardirq-disabled codepaths] are correct and do not interfere
@@ -254,7 +259,7 @@ to do in practice).
Performance:
------------
-The above rules require _massive_ amounts of runtime checking. If we did
+The above rules require **massive** amounts of runtime checking. If we did
that for every lock taken and for every irqs-enable event, it would
render the system practically unusably slow. The complexity of checking
is O(N^2), so even with just a few hundred lock-classes we'd have to do
@@ -313,17 +318,17 @@ be harder to do than to say.
Of course, if you do run out of lock classes, the next thing to do is
to find the offending lock classes. First, the following command gives
-you the number of lock classes currently in use along with the maximum:
+you the number of lock classes currently in use along with the maximum::
grep "lock-classes" /proc/lockdep_stats
-This command produces the following output on a modest system:
+This command produces the following output on a modest system::
- lock-classes: 748 [max: 8191]
+ lock-classes: 748 [max: 8191]
If the number allocated (748 above) increases continually over time,
then there is likely a leak. The following command can be used to
-identify the leaking lock classes:
+identify the leaking lock classes::
grep "BD" /proc/lockdep
diff --git a/Documentation/locking/lockstat.txt b/Documentation/locking/lockstat.txt
index fdbeb0c45ef3..d8c1b5858c25 100644
--- a/Documentation/locking/lockstat.txt
+++ b/Documentation/locking/lockstat.txt
@@ -1,20 +1,25 @@
+===============
+Lock Statistics
+===============
-LOCK STATISTICS
-
-- WHAT
+What
+====
As the name suggests, it provides statistics on locks.
-- WHY
+
+Why
+===
Because things like lock contention can severely impact performance.
-- HOW
+How
+===
Lockdep already has hooks in the lock functions and maps lock instances to
lock classes. We build on that (see Documentation/locking/lockdep-design.txt).
The graph below shows the relation between the lock functions and the various
-hooks therein.
+hooks therein::
__acquire
|
@@ -36,24 +41,38 @@ hooks therein.
|
unlock
-lock, unlock - the regular lock functions
-__* - the hooks
-<> - states
+ lock, unlock - the regular lock functions
+ __* - the hooks
+ <> - states
With these hooks we provide the following statistics:
- con-bounces - number of lock contention that involved x-cpu data
- contentions - number of lock acquisitions that had to wait
- wait time min - shortest (non-0) time we ever had to wait for a lock
- max - longest time we ever had to wait for a lock
- total - total time we spend waiting on this lock
- avg - average time spent waiting on this lock
- acq-bounces - number of lock acquisitions that involved x-cpu data
- acquisitions - number of times we took the lock
- hold time min - shortest (non-0) time we ever held the lock
- max - longest time we ever held the lock
- total - total time this lock was held
- avg - average time this lock was held
+ con-bounces
+ - number of lock contention that involved x-cpu data
+ contentions
+ - number of lock acquisitions that had to wait
+ wait time
+ min
+ - shortest (non-0) time we ever had to wait for a lock
+ max
+ - longest time we ever had to wait for a lock
+ total
+ - total time we spend waiting on this lock
+ avg
+ - average time spent waiting on this lock
+ acq-bounces
+ - number of lock acquisitions that involved x-cpu data
+ acquisitions
+ - number of times we took the lock
+ hold time
+ min
+ - shortest (non-0) time we ever held the lock
+ max
+ - longest time we ever held the lock
+ total
+ - total time this lock was held
+ avg
+ - average time this lock was held
These numbers are gathered per lock class, per read/write state (when
applicable).
@@ -61,58 +80,60 @@ applicable).
It also tracks 4 contention points per class. A contention point is a call site
that had to wait on lock acquisition.
- - CONFIGURATION
+Configuration
+-------------
Lock statistics are enabled via CONFIG_LOCK_STAT.
- - USAGE
-
-Enable collection of statistics:
-
-# echo 1 >/proc/sys/kernel/lock_stat
-
-Disable collection of statistics:
-
-# echo 0 >/proc/sys/kernel/lock_stat
-
-Look at the current lock statistics:
-
-( line numbers not part of actual output, done for clarity in the explanation
- below )
-
-# less /proc/lock_stat
-
-01 lock_stat version 0.4
-02-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
-03 class name con-bounces contentions waittime-min waittime-max waittime-total waittime-avg acq-bounces acquisitions holdtime-min holdtime-max holdtime-total holdtime-avg
-04-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
-05
-06 &mm->mmap_sem-W: 46 84 0.26 939.10 16371.53 194.90 47291 2922365 0.16 2220301.69 17464026916.32 5975.99
-07 &mm->mmap_sem-R: 37 100 1.31 299502.61 325629.52 3256.30 212344 34316685 0.10 7744.91 95016910.20 2.77
-08 ---------------
-09 &mm->mmap_sem 1 [<ffffffff811502a7>] khugepaged_scan_mm_slot+0x57/0x280
-10 &mm->mmap_sem 96 [<ffffffff815351c4>] __do_page_fault+0x1d4/0x510
-11 &mm->mmap_sem 34 [<ffffffff81113d77>] vm_mmap_pgoff+0x87/0xd0
-12 &mm->mmap_sem 17 [<ffffffff81127e71>] vm_munmap+0x41/0x80
-13 ---------------
-14 &mm->mmap_sem 1 [<ffffffff81046fda>] dup_mmap+0x2a/0x3f0
-15 &mm->mmap_sem 60 [<ffffffff81129e29>] SyS_mprotect+0xe9/0x250
-16 &mm->mmap_sem 41 [<ffffffff815351c4>] __do_page_fault+0x1d4/0x510
-17 &mm->mmap_sem 68 [<ffffffff81113d77>] vm_mmap_pgoff+0x87/0xd0
-18
-19.............................................................................................................................................................................................................................
-20
-21 unix_table_lock: 110 112 0.21 49.24 163.91 1.46 21094 66312 0.12 624.42 31589.81 0.48
-22 ---------------
-23 unix_table_lock 45 [<ffffffff8150ad8e>] unix_create1+0x16e/0x1b0
-24 unix_table_lock 47 [<ffffffff8150b111>] unix_release_sock+0x31/0x250
-25 unix_table_lock 15 [<ffffffff8150ca37>] unix_find_other+0x117/0x230
-26 unix_table_lock 5 [<ffffffff8150a09f>] unix_autobind+0x11f/0x1b0
-27 ---------------
-28 unix_table_lock 39 [<ffffffff8150b111>] unix_release_sock+0x31/0x250
-29 unix_table_lock 49 [<ffffffff8150ad8e>] unix_create1+0x16e/0x1b0
-30 unix_table_lock 20 [<ffffffff8150ca37>] unix_find_other+0x117/0x230
-31 unix_table_lock 4 [<ffffffff8150a09f>] unix_autobind+0x11f/0x1b0
+Usage
+-----
+
+Enable collection of statistics::
+
+ # echo 1 >/proc/sys/kernel/lock_stat
+
+Disable collection of statistics::
+
+ # echo 0 >/proc/sys/kernel/lock_stat
+
+Look at the current lock statistics::
+
+ ( line numbers not part of actual output, done for clarity in the explanation
+ below )
+
+ # less /proc/lock_stat
+
+ 01 lock_stat version 0.4
+ 02-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
+ 03 class name con-bounces contentions waittime-min waittime-max waittime-total waittime-avg acq-bounces acquisitions holdtime-min holdtime-max holdtime-total holdtime-avg
+ 04-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
+ 05
+ 06 &mm->mmap_sem-W: 46 84 0.26 939.10 16371.53 194.90 47291 2922365 0.16 2220301.69 17464026916.32 5975.99
+ 07 &mm->mmap_sem-R: 37 100 1.31 299502.61 325629.52 3256.30 212344 34316685 0.10 7744.91 95016910.20 2.77
+ 08 ---------------
+ 09 &mm->mmap_sem 1 [<ffffffff811502a7>] khugepaged_scan_mm_slot+0x57/0x280
+ 10 &mm->mmap_sem 96 [<ffffffff815351c4>] __do_page_fault+0x1d4/0x510
+ 11 &mm->mmap_sem 34 [<ffffffff81113d77>] vm_mmap_pgoff+0x87/0xd0
+ 12 &mm->mmap_sem 17 [<ffffffff81127e71>] vm_munmap+0x41/0x80
+ 13 ---------------
+ 14 &mm->mmap_sem 1 [<ffffffff81046fda>] dup_mmap+0x2a/0x3f0
+ 15 &mm->mmap_sem 60 [<ffffffff81129e29>] SyS_mprotect+0xe9/0x250
+ 16 &mm->mmap_sem 41 [<ffffffff815351c4>] __do_page_fault+0x1d4/0x510
+ 17 &mm->mmap_sem 68 [<ffffffff81113d77>] vm_mmap_pgoff+0x87/0xd0
+ 18
+ 19.............................................................................................................................................................................................................................
+ 20
+ 21 unix_table_lock: 110 112 0.21 49.24 163.91 1.46 21094 66312 0.12 624.42 31589.81 0.48
+ 22 ---------------
+ 23 unix_table_lock 45 [<ffffffff8150ad8e>] unix_create1+0x16e/0x1b0
+ 24 unix_table_lock 47 [<ffffffff8150b111>] unix_release_sock+0x31/0x250
+ 25 unix_table_lock 15 [<ffffffff8150ca37>] unix_find_other+0x117/0x230
+ 26 unix_table_lock 5 [<ffffffff8150a09f>] unix_autobind+0x11f/0x1b0
+ 27 ---------------
+ 28 unix_table_lock 39 [<ffffffff8150b111>] unix_release_sock+0x31/0x250
+ 29 unix_table_lock 49 [<ffffffff8150ad8e>] unix_create1+0x16e/0x1b0
+ 30 unix_table_lock 20 [<ffffffff8150ca37>] unix_find_other+0x117/0x230
+ 31 unix_table_lock 4 [<ffffffff8150a09f>] unix_autobind+0x11f/0x1b0
This excerpt shows the first two lock class statistics. Line 01 shows the
@@ -133,40 +154,40 @@ points are the points we're contending with.
The integer part of the time values is in us.
-Dealing with nested locks, subclasses may appear:
+Dealing with nested locks, subclasses may appear::
-32...........................................................................................................................................................................................................................
-33
-34 &rq->lock: 13128 13128 0.43 190.53 103881.26 7.91 97454 3453404 0.00 401.11 13224683.11 3.82
-35 ---------
-36 &rq->lock 645 [<ffffffff8103bfc4>] task_rq_lock+0x43/0x75
-37 &rq->lock 297 [<ffffffff8104ba65>] try_to_wake_up+0x127/0x25a
-38 &rq->lock 360 [<ffffffff8103c4c5>] select_task_rq_fair+0x1f0/0x74a
-39 &rq->lock 428 [<ffffffff81045f98>] scheduler_tick+0x46/0x1fb
-40 ---------
-41 &rq->lock 77 [<ffffffff8103bfc4>] task_rq_lock+0x43/0x75
-42 &rq->lock 174 [<ffffffff8104ba65>] try_to_wake_up+0x127/0x25a
-43 &rq->lock 4715 [<ffffffff8103ed4b>] double_rq_lock+0x42/0x54
-44 &rq->lock 893 [<ffffffff81340524>] schedule+0x157/0x7b8
-45
-46...........................................................................................................................................................................................................................
-47
-48 &rq->lock/1: 1526 11488 0.33 388.73 136294.31 11.86 21461 38404 0.00 37.93 109388.53 2.84
-49 -----------
-50 &rq->lock/1 11526 [<ffffffff8103ed58>] double_rq_lock+0x4f/0x54
-51 -----------
-52 &rq->lock/1 5645 [<ffffffff8103ed4b>] double_rq_lock+0x42/0x54
-53 &rq->lock/1 1224 [<ffffffff81340524>] schedule+0x157/0x7b8
-54 &rq->lock/1 4336 [<ffffffff8103ed58>] double_rq_lock+0x4f/0x54
-55 &rq->lock/1 181 [<ffffffff8104ba65>] try_to_wake_up+0x127/0x25a
+ 32...........................................................................................................................................................................................................................
+ 33
+ 34 &rq->lock: 13128 13128 0.43 190.53 103881.26 7.91 97454 3453404 0.00 401.11 13224683.11 3.82
+ 35 ---------
+ 36 &rq->lock 645 [<ffffffff8103bfc4>] task_rq_lock+0x43/0x75
+ 37 &rq->lock 297 [<ffffffff8104ba65>] try_to_wake_up+0x127/0x25a
+ 38 &rq->lock 360 [<ffffffff8103c4c5>] select_task_rq_fair+0x1f0/0x74a
+ 39 &rq->lock 428 [<ffffffff81045f98>] scheduler_tick+0x46/0x1fb
+ 40 ---------
+ 41 &rq->lock 77 [<ffffffff8103bfc4>] task_rq_lock+0x43/0x75
+ 42 &rq->lock 174 [<ffffffff8104ba65>] try_to_wake_up+0x127/0x25a
+ 43 &rq->lock 4715 [<ffffffff8103ed4b>] double_rq_lock+0x42/0x54
+ 44 &rq->lock 893 [<ffffffff81340524>] schedule+0x157/0x7b8
+ 45
+ 46...........................................................................................................................................................................................................................
+ 47
+ 48 &rq->lock/1: 1526 11488 0.33 388.73 136294.31 11.86 21461 38404 0.00 37.93 109388.53 2.84
+ 49 -----------
+ 50 &rq->lock/1 11526 [<ffffffff8103ed58>] double_rq_lock+0x4f/0x54
+ 51 -----------
+ 52 &rq->lock/1 5645 [<ffffffff8103ed4b>] double_rq_lock+0x42/0x54
+ 53 &rq->lock/1 1224 [<ffffffff81340524>] schedule+0x157/0x7b8
+ 54 &rq->lock/1 4336 [<ffffffff8103ed58>] double_rq_lock+0x4f/0x54
+ 55 &rq->lock/1 181 [<ffffffff8104ba65>] try_to_wake_up+0x127/0x25a
Line 48 shows statistics for the second subclass (/1) of &rq->lock class
(subclass starts from 0), since in this case, as line 50 suggests,
double_rq_lock actually acquires a nested lock of two spinlocks.
-View the top contending locks:
+View the top contending locks::
-# grep : /proc/lock_stat | head
+ # grep : /proc/lock_stat | head
clockevents_lock: 2926159 2947636 0.15 46882.81 1784540466.34 605.41 3381345 3879161 0.00 2260.97 53178395.68 13.71
tick_broadcast_lock: 346460 346717 0.18 2257.43 39364622.71 113.54 3642919 4242696 0.00 2263.79 49173646.60 11.59
&mapping->i_mmap_mutex: 203896 203899 3.36 645530.05 31767507988.39 155800.21 3361776 8893984 0.17 2254.15 14110121.02 1.59
@@ -178,6 +199,6 @@ View the top contending locks:
&(&dentry->d_lockref.lock)->rlock: 39791 40179 0.15 1302.08 88851.96 2.21 2790851 12527025 0.10 1910.75 3379714.27 0.27
rcu_node_0: 29203 30064 0.16 786.55 1555573.00 51.74 88963 244254 0.00 398.87 428872.51 1.76
-Clear the statistics:
+Clear the statistics::
-# echo 0 > /proc/lock_stat
+ # echo 0 > /proc/lock_stat
diff --git a/Documentation/locking/locktorture.txt b/Documentation/locking/locktorture.txt
index 6a8df4cd19bf..e79eeeca3ac6 100644
--- a/Documentation/locking/locktorture.txt
+++ b/Documentation/locking/locktorture.txt
@@ -1,6 +1,9 @@
+==================================
Kernel Lock Torture Test Operation
+==================================
CONFIG_LOCK_TORTURE_TEST
+========================
The CONFIG LOCK_TORTURE_TEST config option provides a kernel module
that runs torture tests on core kernel locking primitives. The kernel
@@ -18,61 +21,77 @@ can be simulated by either enlarging this critical region hold time and/or
creating more kthreads.
-MODULE PARAMETERS
+Module Parameters
+=================
This module has the following parameters:
- ** Locktorture-specific **
+Locktorture-specific
+--------------------
-nwriters_stress Number of kernel threads that will stress exclusive lock
+nwriters_stress
+ Number of kernel threads that will stress exclusive lock
ownership (writers). The default value is twice the number
of online CPUs.
-nreaders_stress Number of kernel threads that will stress shared lock
+nreaders_stress
+ Number of kernel threads that will stress shared lock
ownership (readers). The default is the same amount of writer
locks. If the user did not specify nwriters_stress, then
both readers and writers be the amount of online CPUs.
-torture_type Type of lock to torture. By default, only spinlocks will
+torture_type
+ Type of lock to torture. By default, only spinlocks will
be tortured. This module can torture the following locks,
with string values as follows:
- o "lock_busted": Simulates a buggy lock implementation.
+ - "lock_busted":
+ Simulates a buggy lock implementation.
- o "spin_lock": spin_lock() and spin_unlock() pairs.
+ - "spin_lock":
+ spin_lock() and spin_unlock() pairs.
- o "spin_lock_irq": spin_lock_irq() and spin_unlock_irq()
- pairs.
+ - "spin_lock_irq":
+ spin_lock_irq() and spin_unlock_irq() pairs.
- o "rw_lock": read/write lock() and unlock() rwlock pairs.
+ - "rw_lock":
+ read/write lock() and unlock() rwlock pairs.
- o "rw_lock_irq": read/write lock_irq() and unlock_irq()
- rwlock pairs.
+ - "rw_lock_irq":
+ read/write lock_irq() and unlock_irq()
+ rwlock pairs.
- o "mutex_lock": mutex_lock() and mutex_unlock() pairs.
+ - "mutex_lock":
+ mutex_lock() and mutex_unlock() pairs.
- o "rtmutex_lock": rtmutex_lock() and rtmutex_unlock()
- pairs. Kernel must have CONFIG_RT_MUTEX=y.
+ - "rtmutex_lock":
+ rtmutex_lock() and rtmutex_unlock() pairs.
+ Kernel must have CONFIG_RT_MUTEX=y.
- o "rwsem_lock": read/write down() and up() semaphore pairs.
+ - "rwsem_lock":
+ read/write down() and up() semaphore pairs.
- ** Torture-framework (RCU + locking) **
+Torture-framework (RCU + locking)
+---------------------------------
-shutdown_secs The number of seconds to run the test before terminating
+shutdown_secs
+ The number of seconds to run the test before terminating
the test and powering off the system. The default is
zero, which disables test termination and system shutdown.
This capability is useful for automated testing.
-onoff_interval The number of seconds between each attempt to execute a
+onoff_interval
+ The number of seconds between each attempt to execute a
randomly selected CPU-hotplug operation. Defaults
to zero, which disables CPU hotplugging. In
CONFIG_HOTPLUG_CPU=n kernels, locktorture will silently
refuse to do any CPU-hotplug operations regardless of
what value is specified for onoff_interval.
-onoff_holdoff The number of seconds to wait until starting CPU-hotplug
+onoff_holdoff
+ The number of seconds to wait until starting CPU-hotplug
operations. This would normally only be used when
locktorture was built into the kernel and started
automatically at boot time, in which case it is useful
@@ -80,53 +99,59 @@ onoff_holdoff The number of seconds to wait until starting CPU-hotplug
coming and going. This parameter is only useful if
CONFIG_HOTPLUG_CPU is enabled.
-stat_interval Number of seconds between statistics-related printk()s.
+stat_interval
+ Number of seconds between statistics-related printk()s.
By default, locktorture will report stats every 60 seconds.
Setting the interval to zero causes the statistics to
be printed -only- when the module is unloaded, and this
is the default.
-stutter The length of time to run the test before pausing for this
+stutter
+ The length of time to run the test before pausing for this
same period of time. Defaults to "stutter=5", so as
to run and pause for (roughly) five-second intervals.
Specifying "stutter=0" causes the test to run continuously
without pausing, which is the old default behavior.
-shuffle_interval The number of seconds to keep the test threads affinitied
+shuffle_interval
+ The number of seconds to keep the test threads affinitied
to a particular subset of the CPUs, defaults to 3 seconds.
Used in conjunction with test_no_idle_hz.
-verbose Enable verbose debugging printing, via printk(). Enabled
+verbose
+ Enable verbose debugging printing, via printk(). Enabled
by default. This extra information is mostly related to
high-level errors and reports from the main 'torture'
framework.
-STATISTICS
+Statistics
+==========
-Statistics are printed in the following format:
+Statistics are printed in the following format::
-spin_lock-torture: Writes: Total: 93746064 Max/Min: 0/0 Fail: 0
- (A) (B) (C) (D) (E)
+ spin_lock-torture: Writes: Total: 93746064 Max/Min: 0/0 Fail: 0
+ (A) (B) (C) (D) (E)
-(A): Lock type that is being tortured -- torture_type parameter.
+ (A): Lock type that is being tortured -- torture_type parameter.
-(B): Number of writer lock acquisitions. If dealing with a read/write primitive
- a second "Reads" statistics line is printed.
+ (B): Number of writer lock acquisitions. If dealing with a read/write
+ primitive a second "Reads" statistics line is printed.
-(C): Number of times the lock was acquired.
+ (C): Number of times the lock was acquired.
-(D): Min and max number of times threads failed to acquire the lock.
+ (D): Min and max number of times threads failed to acquire the lock.
-(E): true/false values if there were errors acquiring the lock. This should
- -only- be positive if there is a bug in the locking primitive's
- implementation. Otherwise a lock should never fail (i.e., spin_lock()).
- Of course, the same applies for (C), above. A dummy example of this is
- the "lock_busted" type.
+ (E): true/false values if there were errors acquiring the lock. This should
+ -only- be positive if there is a bug in the locking primitive's
+ implementation. Otherwise a lock should never fail (i.e., spin_lock()).
+ Of course, the same applies for (C), above. A dummy example of this is
+ the "lock_busted" type.
-USAGE
+Usage
+=====
-The following script may be used to torture locks:
+The following script may be used to torture locks::
#!/bin/sh
diff --git a/Documentation/locking/mutex-design.txt b/Documentation/locking/mutex-design.txt
index 818aca19612f..4d8236b81fa5 100644
--- a/Documentation/locking/mutex-design.txt
+++ b/Documentation/locking/mutex-design.txt
@@ -1,6 +1,9 @@
+=======================
Generic Mutex Subsystem
+=======================
started by Ingo Molnar <mingo@redhat.com>
+
updated by Davidlohr Bueso <davidlohr@hp.com>
What are mutexes?
@@ -23,7 +26,7 @@ Implementation
Mutexes are represented by 'struct mutex', defined in include/linux/mutex.h
and implemented in kernel/locking/mutex.c. These locks use an atomic variable
(->owner) to keep track of the lock state during its lifetime. Field owner
-actually contains 'struct task_struct *' to the current lock owner and it is
+actually contains `struct task_struct *` to the current lock owner and it is
therefore NULL if not currently owned. Since task_struct pointers are aligned
at at least L1_CACHE_BYTES, low bits (3) are used to store extra state (e.g.,
if waiter list is non-empty). In its most basic form it also includes a
@@ -101,29 +104,36 @@ features that make lock debugging easier and faster:
Interfaces
----------
-Statically define the mutex:
+Statically define the mutex::
+
DEFINE_MUTEX(name);
-Dynamically initialize the mutex:
+Dynamically initialize the mutex::
+
mutex_init(mutex);
-Acquire the mutex, uninterruptible:
+Acquire the mutex, uninterruptible::
+
void mutex_lock(struct mutex *lock);
void mutex_lock_nested(struct mutex *lock, unsigned int subclass);
int mutex_trylock(struct mutex *lock);
-Acquire the mutex, interruptible:
+Acquire the mutex, interruptible::
+
int mutex_lock_interruptible_nested(struct mutex *lock,
unsigned int subclass);
int mutex_lock_interruptible(struct mutex *lock);
-Acquire the mutex, interruptible, if dec to 0:
+Acquire the mutex, interruptible, if dec to 0::
+
int atomic_dec_and_mutex_lock(atomic_t *cnt, struct mutex *lock);
-Unlock the mutex:
+Unlock the mutex::
+
void mutex_unlock(struct mutex *lock);
-Test if the mutex is taken:
+Test if the mutex is taken::
+
int mutex_is_locked(struct mutex *lock);
Disadvantages
diff --git a/Documentation/locking/rt-mutex-design.txt b/Documentation/locking/rt-mutex-design.txt
index 3d7b865539cc..c8f8b97c87e6 100644
--- a/Documentation/locking/rt-mutex-design.txt
+++ b/Documentation/locking/rt-mutex-design.txt
@@ -1,10 +1,11 @@
-#
-# Copyright (c) 2006 Steven Rostedt
-# Licensed under the GNU Free Documentation License, Version 1.2
-#
-
+==============================
RT-mutex implementation design
-------------------------------
+==============================
+
+Copyright (c) 2006 Steven Rostedt
+
+Licensed under the GNU Free Documentation License, Version 1.2
+
This document tries to describe the design of the rtmutex.c implementation.
It doesn't describe the reasons why rtmutex.c exists. For that please see
@@ -41,17 +42,17 @@ to release the lock, because for all we know, B is a CPU hog and will
never give C a chance to release the lock. This is called unbounded priority
inversion.
-Here's a little ASCII art to show the problem.
+Here's a little ASCII art to show the problem::
- grab lock L1 (owned by C)
- |
-A ---+
- C preempted by B
- |
-C +----+
+ grab lock L1 (owned by C)
+ |
+ A ---+
+ C preempted by B
+ |
+ C +----+
-B +-------->
- B now keeps A from running.
+ B +-------->
+ B now keeps A from running.
Priority Inheritance (PI)
@@ -75,24 +76,29 @@ Terminology
Here I explain some terminology that is used in this document to help describe
the design that is used to implement PI.
-PI chain - The PI chain is an ordered series of locks and processes that cause
+PI chain
+ - The PI chain is an ordered series of locks and processes that cause
processes to inherit priorities from a previous process that is
blocked on one of its locks. This is described in more detail
later in this document.
-mutex - In this document, to differentiate from locks that implement
+mutex
+ - In this document, to differentiate from locks that implement
PI and spin locks that are used in the PI code, from now on
the PI locks will be called a mutex.
-lock - In this document from now on, I will use the term lock when
+lock
+ - In this document from now on, I will use the term lock when
referring to spin locks that are used to protect parts of the PI
algorithm. These locks disable preemption for UP (when
CONFIG_PREEMPT is enabled) and on SMP prevents multiple CPUs from
entering critical sections simultaneously.
-spin lock - Same as lock above.
+spin lock
+ - Same as lock above.
-waiter - A waiter is a struct that is stored on the stack of a blocked
+waiter
+ - A waiter is a struct that is stored on the stack of a blocked
process. Since the scope of the waiter is within the code for
a process being blocked on the mutex, it is fine to allocate
the waiter on the process's stack (local variable). This
@@ -104,14 +110,18 @@ waiter - A waiter is a struct that is stored on the stack of a blocked
waiter is sometimes used in reference to the task that is waiting
on a mutex. This is the same as waiter->task.
-waiters - A list of processes that are blocked on a mutex.
+waiters
+ - A list of processes that are blocked on a mutex.
-top waiter - The highest priority process waiting on a specific mutex.
+top waiter
+ - The highest priority process waiting on a specific mutex.
-top pi waiter - The highest priority process waiting on one of the mutexes
+top pi waiter
+ - The highest priority process waiting on one of the mutexes
that a specific process owns.
-Note: task and process are used interchangeably in this document, mostly to
+Note:
+ task and process are used interchangeably in this document, mostly to
differentiate between two processes that are being described together.
@@ -123,7 +133,7 @@ inheritance to take place. Multiple chains may converge, but a chain
would never diverge, since a process can't be blocked on more than one
mutex at a time.
-Example:
+Example::
Process: A, B, C, D, E
Mutexes: L1, L2, L3, L4
@@ -137,21 +147,21 @@ Example:
D owns L4
E blocked on L4
-The chain would be:
+The chain would be::
E->L4->D->L3->C->L2->B->L1->A
To show where two chains merge, we could add another process F and
another mutex L5 where B owns L5 and F is blocked on mutex L5.
-The chain for F would be:
+The chain for F would be::
F->L5->B->L1->A
Since a process may own more than one mutex, but never be blocked on more than
one, the chains merge.
-Here we show both chains:
+Here we show both chains::
E->L4->D->L3->C->L2-+
|
@@ -165,12 +175,12 @@ than the processes to the left or below in the chain.
Also since a mutex may have more than one process blocked on it, we can
have multiple chains merge at mutexes. If we add another process G that is
-blocked on mutex L2:
+blocked on mutex L2::
G->L2->B->L1->A
And once again, to show how this can grow I will show the merging chains
-again.
+again::
E->L4->D->L3->C-+
+->L2-+
@@ -184,7 +194,7 @@ the chain (A and B in this example), must have their priorities increased
to that of G.
Mutex Waiters Tree
------------------
+------------------
Every mutex keeps track of all the waiters that are blocked on itself. The
mutex has a rbtree to store these waiters by priority. This tree is protected
@@ -219,19 +229,19 @@ defined. But is very complex to figure it out, since it depends on all
the nesting of mutexes. Let's look at the example where we have 3 mutexes,
L1, L2, and L3, and four separate functions func1, func2, func3 and func4.
The following shows a locking order of L1->L2->L3, but may not actually
-be directly nested that way.
+be directly nested that way::
-void func1(void)
-{
+ void func1(void)
+ {
mutex_lock(L1);
/* do anything */
mutex_unlock(L1);
-}
+ }
-void func2(void)
-{
+ void func2(void)
+ {
mutex_lock(L1);
mutex_lock(L2);
@@ -239,10 +249,10 @@ void func2(void)
mutex_unlock(L2);
mutex_unlock(L1);
-}
+ }
-void func3(void)
-{
+ void func3(void)
+ {
mutex_lock(L2);
mutex_lock(L3);
@@ -250,30 +260,30 @@ void func3(void)
mutex_unlock(L3);
mutex_unlock(L2);
-}
+ }
-void func4(void)
-{
+ void func4(void)
+ {
mutex_lock(L3);
/* do something again */
mutex_unlock(L3);
-}
+ }
Now we add 4 processes that run each of these functions separately.
Processes A, B, C, and D which run functions func1, func2, func3 and func4
respectively, and such that D runs first and A last. With D being preempted
-in func4 in the "do something again" area, we have a locking that follows:
+in func4 in the "do something again" area, we have a locking that follows::
-D owns L3
- C blocked on L3
- C owns L2
- B blocked on L2
- B owns L1
- A blocked on L1
+ D owns L3
+ C blocked on L3
+ C owns L2
+ B blocked on L2
+ B owns L1
+ A blocked on L1
-And thus we have the chain A->L1->B->L2->C->L3->D.
+ And thus we have the chain A->L1->B->L2->C->L3->D.
This gives us a PI depth of 4 (four processes), but looking at any of the
functions individually, it seems as though they only have at most a locking
@@ -307,17 +317,17 @@ Some architectures implement an atomic cmpxchg (Compare and Exchange). This
is used (when applicable) to keep the fast path of grabbing and releasing
mutexes short.
-cmpxchg is basically the following function performed atomically:
+cmpxchg is basically the following function performed atomically::
-unsigned long _cmpxchg(unsigned long *A, unsigned long *B, unsigned long *C)
-{
+ unsigned long _cmpxchg(unsigned long *A, unsigned long *B, unsigned long *C)
+ {
unsigned long T = *A;
if (*A == *B) {
*A = *C;
}
return T;
-}
-#define cmpxchg(a,b,c) _cmpxchg(&a,&b,&c)
+ }
+ #define cmpxchg(a,b,c) _cmpxchg(&a,&b,&c)
This is really nice to have, since it allows you to only update a variable
if the variable is what you expect it to be. You know if it succeeded if
@@ -352,9 +362,10 @@ Then rt_mutex_setprio is called to adjust the priority of the task to the
new priority. Note that rt_mutex_setprio is defined in kernel/sched/core.c
to implement the actual change in priority.
-(Note: For the "prio" field in task_struct, the lower the number, the
+Note:
+ For the "prio" field in task_struct, the lower the number, the
higher the priority. A "prio" of 5 is of higher priority than a
- "prio" of 10.)
+ "prio" of 10.
It is interesting to note that rt_mutex_adjust_prio can either increase
or decrease the priority of the task. In the case that a higher priority
@@ -439,6 +450,7 @@ wait_lock, which this code currently holds. So setting the "Has Waiters" flag
forces the current owner to synchronize with this code.
The lock is taken if the following are true:
+
1) The lock has no owner
2) The current task is the highest priority against all other
waiters of the lock
@@ -546,10 +558,13 @@ Credits
-------
Author: Steven Rostedt <rostedt@goodmis.org>
+
Updated: Alex Shi <alex.shi@linaro.org> - 7/6/2017
-Original Reviewers: Ingo Molnar, Thomas Gleixner, Thomas Duetsch, and
+Original Reviewers:
+ Ingo Molnar, Thomas Gleixner, Thomas Duetsch, and
Randy Dunlap
+
Update (7/6/2017) Reviewers: Steven Rostedt and Sebastian Siewior
Updates
diff --git a/Documentation/locking/rt-mutex.txt b/Documentation/locking/rt-mutex.txt
index 35793e003041..c365dc302081 100644
--- a/Documentation/locking/rt-mutex.txt
+++ b/Documentation/locking/rt-mutex.txt
@@ -1,5 +1,6 @@
+==================================
RT-mutex subsystem with PI support
-----------------------------------
+==================================
RT-mutexes with priority inheritance are used to support PI-futexes,
which enable pthread_mutex_t priority inheritance attributes
@@ -46,27 +47,30 @@ The state of the rt-mutex is tracked via the owner field of the rt-mutex
structure:
lock->owner holds the task_struct pointer of the owner. Bit 0 is used to
-keep track of the "lock has waiters" state.
+keep track of the "lock has waiters" state:
- owner bit0
+ ============ ======= ================================================
+ owner bit0 Notes
+ ============ ======= ================================================
NULL 0 lock is free (fast acquire possible)
NULL 1 lock is free and has waiters and the top waiter
- is going to take the lock*
+ is going to take the lock [1]_
taskpointer 0 lock is held (fast release possible)
- taskpointer 1 lock is held and has waiters**
+ taskpointer 1 lock is held and has waiters [2]_
+ ============ ======= ================================================
The fast atomic compare exchange based acquire and release is only
possible when bit 0 of lock->owner is 0.
-(*) It also can be a transitional state when grabbing the lock
-with ->wait_lock is held. To prevent any fast path cmpxchg to the lock,
-we need to set the bit0 before looking at the lock, and the owner may be
-NULL in this small time, hence this can be a transitional state.
+.. [1] It also can be a transitional state when grabbing the lock
+ with ->wait_lock is held. To prevent any fast path cmpxchg to the lock,
+ we need to set the bit0 before looking at the lock, and the owner may
+ be NULL in this small time, hence this can be a transitional state.
-(**) There is a small time when bit 0 is set but there are no
-waiters. This can happen when grabbing the lock in the slow path.
-To prevent a cmpxchg of the owner releasing the lock, we need to
-set this bit before looking at the lock.
+.. [2] There is a small time when bit 0 is set but there are no
+ waiters. This can happen when grabbing the lock in the slow path.
+ To prevent a cmpxchg of the owner releasing the lock, we need to
+ set this bit before looking at the lock.
BTW, there is still technically a "Pending Owner", it's just not called
that anymore. The pending owner happens to be the top_waiter of a lock
diff --git a/Documentation/locking/spinlocks.txt b/Documentation/locking/spinlocks.txt
index ff35e40bdf5b..098107fb7d86 100644
--- a/Documentation/locking/spinlocks.txt
+++ b/Documentation/locking/spinlocks.txt
@@ -1,8 +1,13 @@
+===============
+Locking lessons
+===============
+
Lesson 1: Spin locks
+====================
-The most basic primitive for locking is spinlock.
+The most basic primitive for locking is spinlock::
-static DEFINE_SPINLOCK(xxx_lock);
+ static DEFINE_SPINLOCK(xxx_lock);
unsigned long flags;
@@ -19,23 +24,25 @@ worry about UP vs SMP issues: the spinlocks work correctly under both.
NOTE! Implications of spin_locks for memory are further described in:
Documentation/memory-barriers.txt
+
(5) LOCK operations.
+
(6) UNLOCK operations.
The above is usually pretty simple (you usually need and want only one
spinlock for most things - using more than one spinlock can make things a
lot more complex and even slower and is usually worth it only for
-sequences that you _know_ need to be split up: avoid it at all cost if you
+sequences that you **know** need to be split up: avoid it at all cost if you
aren't sure).
This is really the only really hard part about spinlocks: once you start
using spinlocks they tend to expand to areas you might not have noticed
before, because you have to make sure the spinlocks correctly protect the
-shared data structures _everywhere_ they are used. The spinlocks are most
+shared data structures **everywhere** they are used. The spinlocks are most
easily added to places that are completely independent of other code (for
example, internal driver data structures that nobody else ever touches).
- NOTE! The spin-lock is safe only when you _also_ use the lock itself
+ NOTE! The spin-lock is safe only when you **also** use the lock itself
to do locking across CPU's, which implies that EVERYTHING that
touches a shared variable has to agree about the spinlock they want
to use.
@@ -43,6 +50,7 @@ example, internal driver data structures that nobody else ever touches).
----
Lesson 2: reader-writer spinlocks.
+==================================
If your data accesses have a very natural pattern where you usually tend
to mostly read from the shared variables, the reader-writer locks
@@ -54,7 +62,7 @@ to change the variables it has to get an exclusive write lock.
simple spinlocks. Unless the reader critical section is long, you
are better off just using spinlocks.
-The routines look the same as above:
+The routines look the same as above::
rwlock_t xxx_lock = __RW_LOCK_UNLOCKED(xxx_lock);
@@ -71,7 +79,7 @@ The routines look the same as above:
The above kind of lock may be useful for complex data structures like
linked lists, especially searching for entries without changing the list
itself. The read lock allows many concurrent readers. Anything that
-_changes_ the list will have to get the write lock.
+**changes** the list will have to get the write lock.
NOTE! RCU is better for list traversal, but requires careful
attention to design detail (see Documentation/RCU/listRCU.txt).
@@ -87,10 +95,11 @@ to get the write-lock at the very beginning.
----
Lesson 3: spinlocks revisited.
+==============================
The single spin-lock primitives above are by no means the only ones. They
are the most safe ones, and the ones that work under all circumstances,
-but partly _because_ they are safe they are also fairly slow. They are slower
+but partly **because** they are safe they are also fairly slow. They are slower
than they'd need to be, because they do have to disable interrupts
(which is just a single instruction on a x86, but it's an expensive one -
and on other architectures it can be worse).
@@ -98,7 +107,7 @@ and on other architectures it can be worse).
If you have a case where you have to protect a data structure across
several CPU's and you want to use spinlocks you can potentially use
cheaper versions of the spinlocks. IFF you know that the spinlocks are
-never used in interrupt handlers, you can use the non-irq versions:
+never used in interrupt handlers, you can use the non-irq versions::
spin_lock(&lock);
...
@@ -110,7 +119,7 @@ This is useful if you know that the data in question is only ever
manipulated from a "process context", ie no interrupts involved.
The reasons you mustn't use these versions if you have interrupts that
-play with the spinlock is that you can get deadlocks:
+play with the spinlock is that you can get deadlocks::
spin_lock(&lock);
...
@@ -147,9 +156,10 @@ indeed), while write-locks need to protect themselves against interrupts.
----
Reference information:
+======================
For dynamic initialization, use spin_lock_init() or rwlock_init() as
-appropriate:
+appropriate::
spinlock_t xxx_lock;
rwlock_t xxx_rw_lock;
diff --git a/Documentation/locking/ww-mutex-design.txt b/Documentation/locking/ww-mutex-design.txt
index f0ed7c30e695..1846c199da23 100644
--- a/Documentation/locking/ww-mutex-design.txt
+++ b/Documentation/locking/ww-mutex-design.txt
@@ -1,3 +1,4 @@
+======================================
Wound/Wait Deadlock-Proof Mutex Design
======================================
@@ -85,6 +86,7 @@ Furthermore there are three different class of w/w lock acquire functions:
no deadlock potential and hence the ww_mutex_lock call will block and not
prematurely return -EDEADLK. The advantage of the _slow functions is in
interface safety:
+
- ww_mutex_lock has a __must_check int return type, whereas ww_mutex_lock_slow
has a void return type. Note that since ww mutex code needs loops/retries
anyway the __must_check doesn't result in spurious warnings, even though the
@@ -115,36 +117,36 @@ expect the number of simultaneous competing transactions to be typically small,
and you want to reduce the number of rollbacks.
Three different ways to acquire locks within the same w/w class. Common
-definitions for methods #1 and #2:
+definitions for methods #1 and #2::
-static DEFINE_WW_CLASS(ww_class);
+ static DEFINE_WW_CLASS(ww_class);
-struct obj {
+ struct obj {
struct ww_mutex lock;
/* obj data */
-};
+ };
-struct obj_entry {
+ struct obj_entry {
struct list_head head;
struct obj *obj;
-};
+ };
Method 1, using a list in execbuf->buffers that's not allowed to be reordered.
This is useful if a list of required objects is already tracked somewhere.
Furthermore the lock helper can use propagate the -EALREADY return code back to
the caller as a signal that an object is twice on the list. This is useful if
the list is constructed from userspace input and the ABI requires userspace to
-not have duplicate entries (e.g. for a gpu commandbuffer submission ioctl).
+not have duplicate entries (e.g. for a gpu commandbuffer submission ioctl)::
-int lock_objs(struct list_head *list, struct ww_acquire_ctx *ctx)
-{
+ int lock_objs(struct list_head *list, struct ww_acquire_ctx *ctx)
+ {
struct obj *res_obj = NULL;
struct obj_entry *contended_entry = NULL;
struct obj_entry *entry;
ww_acquire_init(ctx, &ww_class);
-retry:
+ retry:
list_for_each_entry (entry, list, head) {
if (entry->obj == res_obj) {
res_obj = NULL;
@@ -160,7 +162,7 @@ retry:
ww_acquire_done(ctx);
return 0;
-err:
+ err:
list_for_each_entry_continue_reverse (entry, list, head)
ww_mutex_unlock(&entry->obj->lock);
@@ -176,14 +178,14 @@ err:
ww_acquire_fini(ctx);
return ret;
-}
+ }
Method 2, using a list in execbuf->buffers that can be reordered. Same semantics
of duplicate entry detection using -EALREADY as method 1 above. But the
-list-reordering allows for a bit more idiomatic code.
+list-reordering allows for a bit more idiomatic code::
-int lock_objs(struct list_head *list, struct ww_acquire_ctx *ctx)
-{
+ int lock_objs(struct list_head *list, struct ww_acquire_ctx *ctx)
+ {
struct obj_entry *entry, *entry2;
ww_acquire_init(ctx, &ww_class);
@@ -216,24 +218,25 @@ int lock_objs(struct list_head *list, struct ww_acquire_ctx *ctx)
ww_acquire_done(ctx);
return 0;
-}
+ }
-Unlocking works the same way for both methods #1 and #2:
+Unlocking works the same way for both methods #1 and #2::
-void unlock_objs(struct list_head *list, struct ww_acquire_ctx *ctx)
-{
+ void unlock_objs(struct list_head *list, struct ww_acquire_ctx *ctx)
+ {
struct obj_entry *entry;
list_for_each_entry (entry, list, head)
ww_mutex_unlock(&entry->obj->lock);
ww_acquire_fini(ctx);
-}
+ }
Method 3 is useful if the list of objects is constructed ad-hoc and not upfront,
e.g. when adjusting edges in a graph where each node has its own ww_mutex lock,
and edges can only be changed when holding the locks of all involved nodes. w/w
mutexes are a natural fit for such a case for two reasons:
+
- They can handle lock-acquisition in any order which allows us to start walking
a graph from a starting point and then iteratively discovering new edges and
locking down the nodes those edges connect to.
@@ -243,6 +246,7 @@ mutexes are a natural fit for such a case for two reasons:
as a starting point).
Note that this approach differs in two important ways from the above methods:
+
- Since the list of objects is dynamically constructed (and might very well be
different when retrying due to hitting the -EDEADLK die condition) there's
no need to keep any object on a persistent list when it's not locked. We can
@@ -260,17 +264,17 @@ any interface misuse for these cases.
Also, method 3 can't fail the lock acquisition step since it doesn't return
-EALREADY. Of course this would be different when using the _interruptible
-variants, but that's outside of the scope of these examples here.
+variants, but that's outside of the scope of these examples here::
-struct obj {
+ struct obj {
struct ww_mutex ww_mutex;
struct list_head locked_list;
-};
+ };
-static DEFINE_WW_CLASS(ww_class);
+ static DEFINE_WW_CLASS(ww_class);
-void __unlock_objs(struct list_head *list)
-{
+ void __unlock_objs(struct list_head *list)
+ {
struct obj *entry, *temp;
list_for_each_entry_safe (entry, temp, list, locked_list) {
@@ -279,15 +283,15 @@ void __unlock_objs(struct list_head *list)
list_del(&entry->locked_list);
ww_mutex_unlock(entry->ww_mutex)
}
-}
+ }
-void lock_objs(struct list_head *list, struct ww_acquire_ctx *ctx)
-{
+ void lock_objs(struct list_head *list, struct ww_acquire_ctx *ctx)
+ {
struct obj *obj;
ww_acquire_init(ctx, &ww_class);
-retry:
+ retry:
/* re-init loop start state */
loop {
/* magic code which walks over a graph and decides which objects
@@ -312,13 +316,13 @@ retry:
ww_acquire_done(ctx);
return 0;
-}
+ }
-void unlock_objs(struct list_head *list, struct ww_acquire_ctx *ctx)
-{
+ void unlock_objs(struct list_head *list, struct ww_acquire_ctx *ctx)
+ {
__unlock_objs(list);
ww_acquire_fini(ctx);
-}
+ }
Method 4: Only lock one single objects. In that case deadlock detection and
prevention is obviously overkill, since with grabbing just one lock you can't
@@ -329,11 +333,14 @@ Implementation Details
----------------------
Design:
+^^^^^^^
+
ww_mutex currently encapsulates a struct mutex, this means no extra overhead for
normal mutex locks, which are far more common. As such there is only a small
increase in code size if wait/wound mutexes are not used.
We maintain the following invariants for the wait list:
+
(1) Waiters with an acquire context are sorted by stamp order; waiters
without an acquire context are interspersed in FIFO order.
(2) For Wait-Die, among waiters with contexts, only the first one can have
@@ -355,6 +362,8 @@ Design:
therefore be directed towards the uncontended cases.
Lockdep:
+^^^^^^^^
+
Special care has been taken to warn for as many cases of api abuse
as possible. Some common api abuses will be caught with
CONFIG_DEBUG_MUTEXES, but CONFIG_PROVE_LOCKING is recommended.
@@ -379,5 +388,6 @@ Lockdep:
having called ww_acquire_fini on the first.
- 'normal' deadlocks that can occur.
-FIXME: Update this section once we have the TASK_DEADLOCK task state flag magic
-implemented.
+FIXME:
+ Update this section once we have the TASK_DEADLOCK task state flag magic
+ implemented.
--
2.20.1
^ permalink raw reply related [flat|nested] 81+ messages in thread* [PATCH 22/57] docs: mic: convert it to ReST format
2019-04-16 2:55 [PATCH 00/57] Convert files to ReST Mauro Carvalho Chehab
` (15 preceding siblings ...)
2019-04-16 2:55 ` [PATCH 21/57] docs: locking: convert docs " Mauro Carvalho Chehab
@ 2019-04-16 2:55 ` Mauro Carvalho Chehab
2019-04-16 2:55 ` [PATCH 23/57] docs: netlabel: convert it to ReST Mauro Carvalho Chehab
` (35 subsequent siblings)
52 siblings, 0 replies; 81+ messages in thread
From: Mauro Carvalho Chehab @ 2019-04-16 2:55 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Sudeep Dutt, Ashutosh Dixit
Convert Intel Many Integrated Core architecture docs to ReST.
The conversion is trivial: just add title and literal block
markups, and adjust some identation.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
Documentation/mic/mic_overview.txt | 6 ++-
Documentation/mic/scif_overview.txt | 58 +++++++++++++++++------------
2 files changed, 39 insertions(+), 25 deletions(-)
diff --git a/Documentation/mic/mic_overview.txt b/Documentation/mic/mic_overview.txt
index 074adbdf83a4..17d956bdaf7c 100644
--- a/Documentation/mic/mic_overview.txt
+++ b/Documentation/mic/mic_overview.txt
@@ -1,3 +1,7 @@
+======================================================
+Intel Many Integrated Core (MIC) architecture overview
+======================================================
+
An Intel MIC X100 device is a PCIe form factor add-in coprocessor
card based on the Intel Many Integrated Core (MIC) architecture
that runs a Linux OS. It is a PCIe endpoint in a platform and therefore
@@ -45,7 +49,7 @@ Here is a block diagram of the various components described above. The
virtio backends are situated on the host rather than the card given better
single threaded performance for the host compared to MIC, the ability of
the host to initiate DMA's to/from the card using the MIC DMA engine and
-the fact that the virtio block storage backend can only be on the host.
+the fact that the virtio block storage backend can only be on the host::
+----------+ | +----------+
| Card OS | | | Host OS |
diff --git a/Documentation/mic/scif_overview.txt b/Documentation/mic/scif_overview.txt
index 0a280d986731..4c8ad9e43706 100644
--- a/Documentation/mic/scif_overview.txt
+++ b/Documentation/mic/scif_overview.txt
@@ -1,3 +1,7 @@
+========================================
+Symmetric Communication Interface (SCIF)
+========================================
+
The Symmetric Communication Interface (SCIF (pronounced as skiff)) is a low
level communications API across PCIe currently implemented for MIC. Currently
SCIF provides inter-node communication within a single host platform, where a
@@ -8,8 +12,11 @@ is to deliver the maximum possible performance given the communication
abilities of the hardware. SCIF has been used to implement an offload compiler
runtime and OFED support for MPI implementations for MIC coprocessors.
-==== SCIF API Components ====
+SCIF API Components
+===================
+
The SCIF API has the following parts:
+
1. Connection establishment using a client server model
2. Byte stream messaging intended for short messages
3. Node enumeration to determine online nodes
@@ -28,9 +35,12 @@ can also register local memory which is followed by data transfer using either
DMA, CPU copies or remote memory mapping via mmap. SCIF supports both user and
kernel mode clients which are functionally equivalent.
-==== SCIF Performance for MIC ====
+SCIF Performance for MIC
+========================
+
DMA bandwidth comparison between the TCP (over ethernet over PCIe) stack versus
-SCIF shows the performance advantages of SCIF for HPC applications and runtimes.
+SCIF shows the performance advantages of SCIF for HPC applications and
+runtimes::
Comparison of TCP and SCIF based BW
@@ -66,33 +76,33 @@ space API similar to the kernel API in scif.h. The SCIF user space library
is distributed @ https://software.intel.com/en-us/mic-developer
Here is some pseudo code for an example of how two applications on two PCIe
-nodes would typically use the SCIF API:
+nodes would typically use the SCIF API::
-Process A (on node A) Process B (on node B)
+ Process A (on node A) Process B (on node B)
-/* get online node information */
-scif_get_node_ids(..) scif_get_node_ids(..)
-scif_open(..) scif_open(..)
-scif_bind(..) scif_bind(..)
-scif_listen(..)
-scif_accept(..) scif_connect(..)
-/* SCIF connection established */
+ /* get online node information */
+ scif_get_node_ids(..) scif_get_node_ids(..)
+ scif_open(..) scif_open(..)
+ scif_bind(..) scif_bind(..)
+ scif_listen(..)
+ scif_accept(..) scif_connect(..)
+ /* SCIF connection established */
-/* Send and receive short messages */
-scif_send(..)/scif_recv(..) scif_send(..)/scif_recv(..)
+ /* Send and receive short messages */
+ scif_send(..)/scif_recv(..) scif_send(..)/scif_recv(..)
-/* Register memory */
-scif_register(..) scif_register(..)
+ /* Register memory */
+ scif_register(..) scif_register(..)
-/* RDMA */
-scif_readfrom(..)/scif_writeto(..) scif_readfrom(..)/scif_writeto(..)
+ /* RDMA */
+ scif_readfrom(..)/scif_writeto(..) scif_readfrom(..)/scif_writeto(..)
-/* Fence DMAs */
-scif_fence_signal(..) scif_fence_signal(..)
+ /* Fence DMAs */
+ scif_fence_signal(..) scif_fence_signal(..)
-mmap(..) mmap(..)
+ mmap(..) mmap(..)
-/* Access remote registered memory */
+ /* Access remote registered memory */
-/* Close the endpoints */
-scif_close(..) scif_close(..)
+ /* Close the endpoints */
+ scif_close(..) scif_close(..)
--
2.20.1
^ permalink raw reply related [flat|nested] 81+ messages in thread* [PATCH 23/57] docs: netlabel: convert it to ReST
2019-04-16 2:55 [PATCH 00/57] Convert files to ReST Mauro Carvalho Chehab
` (16 preceding siblings ...)
2019-04-16 2:55 ` [PATCH 22/57] docs: mic: convert it " Mauro Carvalho Chehab
@ 2019-04-16 2:55 ` Mauro Carvalho Chehab
2019-04-17 14:36 ` Paul Moore
2019-04-16 2:55 ` [PATCH 24/57] docs: pcmcia: convert it to ReST format Mauro Carvalho Chehab
` (34 subsequent siblings)
52 siblings, 1 reply; 81+ messages in thread
From: Mauro Carvalho Chehab @ 2019-04-16 2:55 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Paul Moore, netdev, linux-security-module
Convert netlabel documentation to ReST.
This was trivial: just add proper title markups.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
Documentation/netlabel/cipso_ipv4.txt | 19 +++++++++++++------
Documentation/netlabel/introduction.txt | 16 +++++++++++-----
Documentation/netlabel/lsm_interface.txt | 16 +++++++++++-----
3 files changed, 35 insertions(+), 16 deletions(-)
diff --git a/Documentation/netlabel/cipso_ipv4.txt b/Documentation/netlabel/cipso_ipv4.txt
index a6075481fd60..cbd3f3231221 100644
--- a/Documentation/netlabel/cipso_ipv4.txt
+++ b/Documentation/netlabel/cipso_ipv4.txt
@@ -1,10 +1,13 @@
+===================================
NetLabel CIPSO/IPv4 Protocol Engine
-==============================================================================
+===================================
+
Paul Moore, paul.moore@hp.com
May 17, 2006
- * Overview
+Overview
+========
The NetLabel CIPSO/IPv4 protocol engine is based on the IETF Commercial
IP Security Option (CIPSO) draft from July 16, 1992. A copy of this
@@ -13,7 +16,8 @@ draft can be found in this directory
it to an RFC standard it has become a de-facto standard for labeled
networking and is used in many trusted operating systems.
- * Outbound Packet Processing
+Outbound Packet Processing
+==========================
The CIPSO/IPv4 protocol engine applies the CIPSO IP option to packets by
adding the CIPSO label to the socket. This causes all packets leaving the
@@ -24,7 +28,8 @@ label by using the NetLabel security module API; if the NetLabel "domain" is
configured to use CIPSO for packet labeling then a CIPSO IP option will be
generated and attached to the socket.
- * Inbound Packet Processing
+Inbound Packet Processing
+=========================
The CIPSO/IPv4 protocol engine validates every CIPSO IP option it finds at the
IP layer without any special handling required by the LSM. However, in order
@@ -33,7 +38,8 @@ NetLabel security module API to extract the security attributes of the packet.
This is typically done at the socket layer using the 'socket_sock_rcv_skb()'
LSM hook.
- * Label Translation
+Label Translation
+=================
The CIPSO/IPv4 protocol engine contains a mechanism to translate CIPSO security
attributes such as sensitivity level and category to values which are
@@ -42,7 +48,8 @@ Domain Of Interpretation (DOI) definition and are configured through the
NetLabel user space communication layer. Each DOI definition can have a
different security attribute mapping table.
- * Label Translation Cache
+Label Translation Cache
+=======================
The NetLabel system provides a framework for caching security attribute
mappings from the network labels to the corresponding LSM identifiers. The
diff --git a/Documentation/netlabel/introduction.txt b/Documentation/netlabel/introduction.txt
index 3caf77bcff0f..9333bbb0adc1 100644
--- a/Documentation/netlabel/introduction.txt
+++ b/Documentation/netlabel/introduction.txt
@@ -1,10 +1,13 @@
+=====================
NetLabel Introduction
-==============================================================================
+=====================
+
Paul Moore, paul.moore@hp.com
August 2, 2006
- * Overview
+Overview
+========
NetLabel is a mechanism which can be used by kernel security modules to attach
security attributes to outgoing network packets generated from user space
@@ -12,7 +15,8 @@ applications and read security attributes from incoming network packets. It
is composed of three main components, the protocol engines, the communication
layer, and the kernel security module API.
- * Protocol Engines
+Protocol Engines
+================
The protocol engines are responsible for both applying and retrieving the
network packet's security attributes. If any translation between the network
@@ -24,7 +28,8 @@ the NetLabel kernel security module API described below.
Detailed information about each NetLabel protocol engine can be found in this
directory.
- * Communication Layer
+Communication Layer
+===================
The communication layer exists to allow NetLabel configuration and monitoring
from user space. The NetLabel communication layer uses a message based
@@ -33,7 +38,8 @@ formatting of these NetLabel messages as well as the Generic NETLINK family
names can be found in the 'net/netlabel/' directory as comments in the
header files as well as in 'include/net/netlabel.h'.
- * Security Module API
+Security Module API
+===================
The purpose of the NetLabel security module API is to provide a protocol
independent interface to the underlying NetLabel protocol engines. In addition
diff --git a/Documentation/netlabel/lsm_interface.txt b/Documentation/netlabel/lsm_interface.txt
index 638c74f7de7f..026fc267f798 100644
--- a/Documentation/netlabel/lsm_interface.txt
+++ b/Documentation/netlabel/lsm_interface.txt
@@ -1,10 +1,13 @@
+========================================
NetLabel Linux Security Module Interface
-==============================================================================
+========================================
+
Paul Moore, paul.moore@hp.com
May 17, 2006
- * Overview
+Overview
+========
NetLabel is a mechanism which can set and retrieve security attributes from
network packets. It is intended to be used by LSM developers who want to make
@@ -12,7 +15,8 @@ use of a common code base for several different packet labeling protocols.
The NetLabel security module API is defined in 'include/net/netlabel.h' but a
brief overview is given below.
- * NetLabel Security Attributes
+NetLabel Security Attributes
+============================
Since NetLabel supports multiple different packet labeling protocols and LSMs
it uses the concept of security attributes to refer to the packet's security
@@ -24,7 +28,8 @@ configuration. It is up to the LSM developer to translate the NetLabel
security attributes into whatever security identifiers are in use for their
particular LSM.
- * NetLabel LSM Protocol Operations
+NetLabel LSM Protocol Operations
+================================
These are the functions which allow the LSM developer to manipulate the labels
on outgoing packets as well as read the labels on incoming packets. Functions
@@ -32,7 +37,8 @@ exist to operate both on sockets as well as the sk_buffs directly. These high
level functions are translated into low level protocol operations based on how
the administrator has configured the NetLabel subsystem.
- * NetLabel Label Mapping Cache Operations
+NetLabel Label Mapping Cache Operations
+=======================================
Depending on the exact configuration, translation between the network packet
label and the internal LSM security identifier can be time consuming. The
--
2.20.1
^ permalink raw reply related [flat|nested] 81+ messages in thread* Re: [PATCH 23/57] docs: netlabel: convert it to ReST
2019-04-16 2:55 ` [PATCH 23/57] docs: netlabel: convert it to ReST Mauro Carvalho Chehab
@ 2019-04-17 14:36 ` Paul Moore
0 siblings, 0 replies; 81+ messages in thread
From: Paul Moore @ 2019-04-17 14:36 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: Linux Doc Mailing List, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, netdev, linux-security-module
On Mon, Apr 15, 2019 at 10:56 PM Mauro Carvalho Chehab
<mchehab+samsung@kernel.org> wrote:
>
> Convert netlabel documentation to ReST.
>
> This was trivial: just add proper title markups.
>
> Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
> ---
> Documentation/netlabel/cipso_ipv4.txt | 19 +++++++++++++------
> Documentation/netlabel/introduction.txt | 16 +++++++++++-----
> Documentation/netlabel/lsm_interface.txt | 16 +++++++++++-----
> 3 files changed, 35 insertions(+), 16 deletions(-)
Thanks for doing this. I should probably revisit these docs to make
sure they are still valid/correct; if nothing else that email address
is from two employers ago (my apologies to the current email address
holder).
Acked-by: Paul Moore <paul@paul-moore.com>
> diff --git a/Documentation/netlabel/cipso_ipv4.txt b/Documentation/netlabel/cipso_ipv4.txt
> index a6075481fd60..cbd3f3231221 100644
> --- a/Documentation/netlabel/cipso_ipv4.txt
> +++ b/Documentation/netlabel/cipso_ipv4.txt
> @@ -1,10 +1,13 @@
> +===================================
> NetLabel CIPSO/IPv4 Protocol Engine
> -==============================================================================
> +===================================
> +
> Paul Moore, paul.moore@hp.com
>
> May 17, 2006
>
> - * Overview
> +Overview
> +========
>
> The NetLabel CIPSO/IPv4 protocol engine is based on the IETF Commercial
> IP Security Option (CIPSO) draft from July 16, 1992. A copy of this
> @@ -13,7 +16,8 @@ draft can be found in this directory
> it to an RFC standard it has become a de-facto standard for labeled
> networking and is used in many trusted operating systems.
>
> - * Outbound Packet Processing
> +Outbound Packet Processing
> +==========================
>
> The CIPSO/IPv4 protocol engine applies the CIPSO IP option to packets by
> adding the CIPSO label to the socket. This causes all packets leaving the
> @@ -24,7 +28,8 @@ label by using the NetLabel security module API; if the NetLabel "domain" is
> configured to use CIPSO for packet labeling then a CIPSO IP option will be
> generated and attached to the socket.
>
> - * Inbound Packet Processing
> +Inbound Packet Processing
> +=========================
>
> The CIPSO/IPv4 protocol engine validates every CIPSO IP option it finds at the
> IP layer without any special handling required by the LSM. However, in order
> @@ -33,7 +38,8 @@ NetLabel security module API to extract the security attributes of the packet.
> This is typically done at the socket layer using the 'socket_sock_rcv_skb()'
> LSM hook.
>
> - * Label Translation
> +Label Translation
> +=================
>
> The CIPSO/IPv4 protocol engine contains a mechanism to translate CIPSO security
> attributes such as sensitivity level and category to values which are
> @@ -42,7 +48,8 @@ Domain Of Interpretation (DOI) definition and are configured through the
> NetLabel user space communication layer. Each DOI definition can have a
> different security attribute mapping table.
>
> - * Label Translation Cache
> +Label Translation Cache
> +=======================
>
> The NetLabel system provides a framework for caching security attribute
> mappings from the network labels to the corresponding LSM identifiers. The
> diff --git a/Documentation/netlabel/introduction.txt b/Documentation/netlabel/introduction.txt
> index 3caf77bcff0f..9333bbb0adc1 100644
> --- a/Documentation/netlabel/introduction.txt
> +++ b/Documentation/netlabel/introduction.txt
> @@ -1,10 +1,13 @@
> +=====================
> NetLabel Introduction
> -==============================================================================
> +=====================
> +
> Paul Moore, paul.moore@hp.com
>
> August 2, 2006
>
> - * Overview
> +Overview
> +========
>
> NetLabel is a mechanism which can be used by kernel security modules to attach
> security attributes to outgoing network packets generated from user space
> @@ -12,7 +15,8 @@ applications and read security attributes from incoming network packets. It
> is composed of three main components, the protocol engines, the communication
> layer, and the kernel security module API.
>
> - * Protocol Engines
> +Protocol Engines
> +================
>
> The protocol engines are responsible for both applying and retrieving the
> network packet's security attributes. If any translation between the network
> @@ -24,7 +28,8 @@ the NetLabel kernel security module API described below.
> Detailed information about each NetLabel protocol engine can be found in this
> directory.
>
> - * Communication Layer
> +Communication Layer
> +===================
>
> The communication layer exists to allow NetLabel configuration and monitoring
> from user space. The NetLabel communication layer uses a message based
> @@ -33,7 +38,8 @@ formatting of these NetLabel messages as well as the Generic NETLINK family
> names can be found in the 'net/netlabel/' directory as comments in the
> header files as well as in 'include/net/netlabel.h'.
>
> - * Security Module API
> +Security Module API
> +===================
>
> The purpose of the NetLabel security module API is to provide a protocol
> independent interface to the underlying NetLabel protocol engines. In addition
> diff --git a/Documentation/netlabel/lsm_interface.txt b/Documentation/netlabel/lsm_interface.txt
> index 638c74f7de7f..026fc267f798 100644
> --- a/Documentation/netlabel/lsm_interface.txt
> +++ b/Documentation/netlabel/lsm_interface.txt
> @@ -1,10 +1,13 @@
> +========================================
> NetLabel Linux Security Module Interface
> -==============================================================================
> +========================================
> +
> Paul Moore, paul.moore@hp.com
>
> May 17, 2006
>
> - * Overview
> +Overview
> +========
>
> NetLabel is a mechanism which can set and retrieve security attributes from
> network packets. It is intended to be used by LSM developers who want to make
> @@ -12,7 +15,8 @@ use of a common code base for several different packet labeling protocols.
> The NetLabel security module API is defined in 'include/net/netlabel.h' but a
> brief overview is given below.
>
> - * NetLabel Security Attributes
> +NetLabel Security Attributes
> +============================
>
> Since NetLabel supports multiple different packet labeling protocols and LSMs
> it uses the concept of security attributes to refer to the packet's security
> @@ -24,7 +28,8 @@ configuration. It is up to the LSM developer to translate the NetLabel
> security attributes into whatever security identifiers are in use for their
> particular LSM.
>
> - * NetLabel LSM Protocol Operations
> +NetLabel LSM Protocol Operations
> +================================
>
> These are the functions which allow the LSM developer to manipulate the labels
> on outgoing packets as well as read the labels on incoming packets. Functions
> @@ -32,7 +37,8 @@ exist to operate both on sockets as well as the sk_buffs directly. These high
> level functions are translated into low level protocol operations based on how
> the administrator has configured the NetLabel subsystem.
>
> - * NetLabel Label Mapping Cache Operations
> +NetLabel Label Mapping Cache Operations
> +=======================================
>
> Depending on the exact configuration, translation between the network packet
> label and the internal LSM security identifier can be time consuming. The
> --
> 2.20.1
>
--
paul moore
www.paul-moore.com
^ permalink raw reply [flat|nested] 81+ messages in thread
* [PATCH 24/57] docs: pcmcia: convert it to ReST format
2019-04-16 2:55 [PATCH 00/57] Convert files to ReST Mauro Carvalho Chehab
` (17 preceding siblings ...)
2019-04-16 2:55 ` [PATCH 23/57] docs: netlabel: convert it to ReST Mauro Carvalho Chehab
@ 2019-04-16 2:55 ` Mauro Carvalho Chehab
2019-04-16 4:58 ` Dominik Brodowski
2019-04-16 2:55 ` [PATCH 26/57] docs: powerpc: convert docs to ReST Mauro Carvalho Chehab
` (33 subsequent siblings)
52 siblings, 1 reply; 81+ messages in thread
From: Mauro Carvalho Chehab @ 2019-04-16 2:55 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Dominik Brodowski
Convert the pcmcia docs to ReST format. Most of the changes here
are trivial, making Sphinx properly identify titles, lists and
literal blocks.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
Documentation/pcmcia/devicetable.txt | 4 +++
Documentation/pcmcia/driver-changes.txt | 35 ++++++++++++++--------
Documentation/pcmcia/driver.txt | 18 ++++++------
Documentation/pcmcia/locking.txt | 39 +++++++++++++++++--------
4 files changed, 63 insertions(+), 33 deletions(-)
diff --git a/Documentation/pcmcia/devicetable.txt b/Documentation/pcmcia/devicetable.txt
index 5f3e00ab54c4..fd1d60d12ca1 100644
--- a/Documentation/pcmcia/devicetable.txt
+++ b/Documentation/pcmcia/devicetable.txt
@@ -1,3 +1,7 @@
+============
+Device table
+============
+
Matching of PCMCIA devices to drivers is done using one or more of the
following criteria:
diff --git a/Documentation/pcmcia/driver-changes.txt b/Documentation/pcmcia/driver-changes.txt
index 78355c4c268a..33fe9ebec049 100644
--- a/Documentation/pcmcia/driver-changes.txt
+++ b/Documentation/pcmcia/driver-changes.txt
@@ -1,15 +1,21 @@
+==============
+Driver changes
+==============
+
This file details changes in 2.6 which affect PCMCIA card driver authors:
+
* pcmcia_loop_config() and autoconfiguration (as of 2.6.36)
- If struct pcmcia_device *p_dev->config_flags is set accordingly,
+ If `struct pcmcia_device *p_dev->config_flags` is set accordingly,
pcmcia_loop_config() now sets up certain configuration values
automatically, though the driver may still override the settings
in the callback function. The following autoconfiguration options
are provided at the moment:
- CONF_AUTO_CHECK_VCC : check for matching Vcc
- CONF_AUTO_SET_VPP : set Vpp
- CONF_AUTO_AUDIO : auto-enable audio line, if required
- CONF_AUTO_SET_IO : set ioport resources (->resource[0,1])
- CONF_AUTO_SET_IOMEM : set first iomem resource (->resource[2])
+
+ - CONF_AUTO_CHECK_VCC : check for matching Vcc
+ - CONF_AUTO_SET_VPP : set Vpp
+ - CONF_AUTO_AUDIO : auto-enable audio line, if required
+ - CONF_AUTO_SET_IO : set ioport resources (->resource[0,1])
+ - CONF_AUTO_SET_IOMEM : set first iomem resource (->resource[2])
* pcmcia_request_configuration -> pcmcia_enable_device (as of 2.6.36)
pcmcia_request_configuration() got renamed to pcmcia_enable_device(),
@@ -19,14 +25,14 @@ This file details changes in 2.6 which affect PCMCIA card driver authors:
* pcmcia_request_window changes (as of 2.6.36)
Instead of win_req_t, drivers are now requested to fill out
- struct pcmcia_device *p_dev->resource[2,3,4,5] for up to four ioport
+ `struct pcmcia_device *p_dev->resource[2,3,4,5]` for up to four ioport
ranges. After a call to pcmcia_request_window(), the regions found there
are reserved and may be used immediately -- until pcmcia_release_window()
is called.
* pcmcia_request_io changes (as of 2.6.36)
Instead of io_req_t, drivers are now requested to fill out
- struct pcmcia_device *p_dev->resource[0,1] for up to two ioport
+ `struct pcmcia_device *p_dev->resource[0,1]` for up to two ioport
ranges. After a call to pcmcia_request_io(), the ports found there
are reserved, after calling pcmcia_request_configuration(), they may
be used.
@@ -42,7 +48,8 @@ This file details changes in 2.6 which affect PCMCIA card driver authors:
* New IRQ request rules (as of 2.6.35)
Instead of the old pcmcia_request_irq() interface, drivers may now
choose between:
- - calling request_irq/free_irq directly. Use the IRQ from *p_dev->irq.
+
+ - calling request_irq/free_irq directly. Use the IRQ from `*p_dev->irq`.
- use pcmcia_request_irq(p_dev, handler_t); the PCMCIA core will
clean up automatically on calls to pcmcia_disable_device() or
device ejection.
@@ -72,13 +79,16 @@ This file details changes in 2.6 which affect PCMCIA card driver authors:
exports for them were removed.
* Unify detach and REMOVAL event code, as well as attach and INSERTION
- code (as of 2.6.16)
+ code (as of 2.6.16)::
+
void (*remove) (struct pcmcia_device *dev);
int (*probe) (struct pcmcia_device *dev);
-* Move suspend, resume and reset out of event handler (as of 2.6.16)
+* Move suspend, resume and reset out of event handler (as of 2.6.16)::
+
int (*suspend) (struct pcmcia_device *dev);
int (*resume) (struct pcmcia_device *dev);
+
should be initialized in struct pcmcia_driver, and handle
(SUSPEND == RESET_PHYSICAL) and (RESUME == CARD_RESET) events
@@ -117,7 +127,8 @@ This file details changes in 2.6 which affect PCMCIA card driver authors:
* core functions no longer available (as of 2.6.11)
The following functions have been removed from the kernel source
because they are unused by all in-kernel drivers, and no external
- driver was reported to rely on them:
+ driver was reported to rely on them::
+
pcmcia_get_first_region()
pcmcia_get_next_region()
pcmcia_modify_window()
diff --git a/Documentation/pcmcia/driver.txt b/Documentation/pcmcia/driver.txt
index 0ac167920778..5c4fe84d51c1 100644
--- a/Documentation/pcmcia/driver.txt
+++ b/Documentation/pcmcia/driver.txt
@@ -1,16 +1,16 @@
+=============
PCMCIA Driver
--------------
-
+=============
sysfs
-----
New PCMCIA IDs may be added to a device driver pcmcia_device_id table at
-runtime as shown below:
+runtime as shown below::
-echo "match_flags manf_id card_id func_id function device_no \
-prod_id_hash[0] prod_id_hash[1] prod_id_hash[2] prod_id_hash[3]" > \
-/sys/bus/pcmcia/drivers/{driver}/new_id
+ echo "match_flags manf_id card_id func_id function device_no \
+ prod_id_hash[0] prod_id_hash[1] prod_id_hash[2] prod_id_hash[3]" > \
+ /sys/bus/pcmcia/drivers/{driver}/new_id
All fields are passed in as hexadecimal values (no leading 0x).
The meaning is described in the PCMCIA specification, the match_flags is
@@ -22,9 +22,9 @@ PCMCIA device listed in its (newly updated) pcmcia_device_id list.
A common use-case is to add a new device according to the manufacturer ID
and the card ID (form the manf_id and card_id file in the device tree).
-For this, just use:
+For this, just use::
-echo "0x3 manf_id card_id 0 0 0 0 0 0 0" > \
- /sys/bus/pcmcia/drivers/{driver}/new_id
+ echo "0x3 manf_id card_id 0 0 0 0 0 0 0" > \
+ /sys/bus/pcmcia/drivers/{driver}/new_id
after loading the driver.
diff --git a/Documentation/pcmcia/locking.txt b/Documentation/pcmcia/locking.txt
index b2c9b478906b..e35257139c89 100644
--- a/Documentation/pcmcia/locking.txt
+++ b/Documentation/pcmcia/locking.txt
@@ -1,3 +1,7 @@
+=======
+Locking
+=======
+
This file explains the locking and exclusion scheme used in the PCCARD
and PCMCIA subsystems.
@@ -5,16 +9,21 @@ and PCMCIA subsystems.
A) Overview, Locking Hierarchy:
===============================
-pcmcia_socket_list_rwsem - protects only the list of sockets
-- skt_mutex - serializes card insert / ejection
- - ops_mutex - serializes socket operation
+pcmcia_socket_list_rwsem
+ - protects only the list of sockets
+
+- skt_mutex
+ - serializes card insert / ejection
+
+ - ops_mutex
+ - serializes socket operation
B) Exclusion
============
The following functions and callbacks to struct pcmcia_socket must
-be called with "skt_mutex" held:
+be called with "skt_mutex" held::
socket_detect_change()
send_event()
@@ -31,7 +40,7 @@ be called with "skt_mutex" held:
struct pcmcia_callback *callback
The following functions and callbacks to struct pcmcia_socket must
-be called with "ops_mutex" held:
+be called with "ops_mutex" held::
socket_reset()
socket_setup()
@@ -39,7 +48,7 @@ be called with "ops_mutex" held:
struct pccard_operations *ops
struct pccard_resource_ops *resource_ops;
-Note that send_event() and struct pcmcia_callback *callback must not be
+Note that send_event() and `struct pcmcia_callback *callback` must not be
called with "ops_mutex" held.
@@ -60,19 +69,23 @@ The resource_ops and their data are protected by ops_mutex.
The "main" struct pcmcia_socket is protected as follows (read-only fields
or single-use fields not mentioned):
-- by pcmcia_socket_list_rwsem:
+- by pcmcia_socket_list_rwsem::
+
struct list_head socket_list;
-- by thread_lock:
+- by thread_lock::
+
unsigned int thread_events;
-- by skt_mutex:
+- by skt_mutex::
+
u_int suspended_state;
void (*tune_bridge);
struct pcmcia_callback *callback;
int resume_status;
-- by ops_mutex:
+- by ops_mutex::
+
socket_state_t socket;
u_int state;
u_short lock_count;
@@ -100,7 +113,8 @@ The "main" struct pcmcia_device is protected as follows (read-only fields
or single-use fields not mentioned):
-- by pcmcia_socket->ops_mutex:
+- by pcmcia_socket->ops_mutex::
+
struct list_head socket_device_list;
struct config_t *function_config;
u16 _irq:1;
@@ -111,7 +125,8 @@ or single-use fields not mentioned):
u16 suspended:1;
u16 _removed:1;
-- by the PCMCIA driver:
+- by the PCMCIA driver::
+
io_req_t io;
irq_req_t irq;
config_req_t conf;
--
2.20.1
^ permalink raw reply related [flat|nested] 81+ messages in thread* Re: [PATCH 24/57] docs: pcmcia: convert it to ReST format
2019-04-16 2:55 ` [PATCH 24/57] docs: pcmcia: convert it to ReST format Mauro Carvalho Chehab
@ 2019-04-16 4:58 ` Dominik Brodowski
0 siblings, 0 replies; 81+ messages in thread
From: Dominik Brodowski @ 2019-04-16 4:58 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: Linux Doc Mailing List, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet
On Mon, Apr 15, 2019 at 11:55:49PM -0300, Mauro Carvalho Chehab wrote:
> Convert the pcmcia docs to ReST format. Most of the changes here
> are trivial, making Sphinx properly identify titles, lists and
> literal blocks.
>
> Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
Acked-by: Dominik Brodowski <linux@dominikbrodowski.net>
Thanks,
Dominik
^ permalink raw reply [flat|nested] 81+ messages in thread
* [PATCH 26/57] docs: powerpc: convert docs to ReST
2019-04-16 2:55 [PATCH 00/57] Convert files to ReST Mauro Carvalho Chehab
` (18 preceding siblings ...)
2019-04-16 2:55 ` [PATCH 24/57] docs: pcmcia: convert it to ReST format Mauro Carvalho Chehab
@ 2019-04-16 2:55 ` Mauro Carvalho Chehab
2019-04-16 2:55 ` [PATCH 27/57] docs: pps/pps.txt convert it to ReST and move to API book Mauro Carvalho Chehab
` (32 subsequent siblings)
52 siblings, 0 replies; 81+ messages in thread
From: Mauro Carvalho Chehab @ 2019-04-16 2:55 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Benjamin Herrenschmidt, Paul Mackerras,
Michael Ellerman, linuxppc-dev
Convert docs to ReST and add them to the arch-specific
book.
The conversion here was trivial, as almost every file there
was already using an elegant format close to ReST standard.
The changes were mostly to mark literal blocks and add a few
missing section title identifiers.
One note with regards to "--": on Sphinx, this can't be used
to identify a list, as it will format it badly. This can be
used, however, to identify a long hyphen - and "---" is an
even longer one.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
Documentation/powerpc/DAWR-POWER9.txt | 10 +-
Documentation/powerpc/bootwrapper.txt | 28 ++-
Documentation/powerpc/cpu_families.txt | 23 +--
Documentation/powerpc/cpu_features.txt | 6 +-
Documentation/powerpc/cxl.txt | 46 +++--
Documentation/powerpc/cxlflash.txt | 8 +-
Documentation/powerpc/dscr.txt | 18 +-
.../powerpc/eeh-pci-error-recovery.txt | 108 +++++------
.../powerpc/firmware-assisted-dump.txt | 117 ++++++------
Documentation/powerpc/hvcs.txt | 108 ++++++-----
Documentation/powerpc/isa-versions.rst | 13 +-
Documentation/powerpc/mpc52xx.txt | 12 +-
.../powerpc/pci_iov_resource_on_powernv.txt | 15 +-
Documentation/powerpc/pmu-ebb.txt | 1 +
Documentation/powerpc/ptrace.txt | 169 +++++++++---------
Documentation/powerpc/qe_firmware.txt | 37 ++--
Documentation/powerpc/syscall64-abi.txt | 29 +--
.../powerpc/transactional_memory.txt | 45 ++---
18 files changed, 447 insertions(+), 346 deletions(-)
diff --git a/Documentation/powerpc/DAWR-POWER9.txt b/Documentation/powerpc/DAWR-POWER9.txt
index 2feaa6619658..882e5af02b9c 100644
--- a/Documentation/powerpc/DAWR-POWER9.txt
+++ b/Documentation/powerpc/DAWR-POWER9.txt
@@ -1,10 +1,11 @@
+=====================
DAWR issues on POWER9
-============================
+=====================
On POWER9 the DAWR can cause a checkstop if it points to cache
inhibited (CI) memory. Currently Linux has no way to disinguish CI
memory when configuring the DAWR, so (for now) the DAWR is disabled by
-this commit:
+this commit::
commit 9654153158d3e0684a1bdb76dbababdb7111d5a0
Author: Michael Neuling <mikey@neuling.org>
@@ -12,7 +13,7 @@ this commit:
powerpc: Disable DAWR in the base POWER9 CPU features
Technical Details:
-============================
+==================
DAWR has 6 different ways of being set.
1) ptrace
@@ -37,7 +38,7 @@ DAWR on the migration.
For xmon, the 'bd' command will return an error on P9.
Consequences for users
-============================
+======================
For GDB watchpoints (ie 'watch' command) on POWER9 bare metal , GDB
will accept the command. Unfortunately since there is no hardware
@@ -55,4 +56,3 @@ guest is migrated to a POWER9 host, the watchpoint will be lost on the
POWER9. Loads and stores to the watchpoint locations will not be
trapped in GDB. The watchpoint is remembered, so if the guest is
migrated back to the POWER8 host, it will start working again.
-
diff --git a/Documentation/powerpc/bootwrapper.txt b/Documentation/powerpc/bootwrapper.txt
index d60fced5e1cc..a6292afba573 100644
--- a/Documentation/powerpc/bootwrapper.txt
+++ b/Documentation/powerpc/bootwrapper.txt
@@ -1,5 +1,7 @@
+========================
The PowerPC boot wrapper
-------------------------
+========================
+
Copyright (C) Secret Lab Technologies Ltd.
PowerPC image targets compresses and wraps the kernel image (vmlinux) with
@@ -21,6 +23,7 @@ it uses the wrapper script (arch/powerpc/boot/wrapper) to generate target
image. The details of the build system is discussed in the next section.
Currently, the following image format targets exist:
+ ==================== ========================================================
cuImage.%: Backwards compatible uImage for older version of
U-Boot (for versions that don't understand the device
tree). This image embeds a device tree blob inside
@@ -29,31 +32,36 @@ Currently, the following image format targets exist:
with boot wrapper code that extracts data from the old
bd_info structure and loads the data into the device
tree before jumping into the kernel.
- Because of the series of #ifdefs found in the
+
+ Because of the series of #ifdefs found in the
bd_info structure used in the old U-Boot interfaces,
cuImages are platform specific. Each specific
U-Boot platform has a different platform init file
which populates the embedded device tree with data
from the platform specific bd_info file. The platform
specific cuImage platform init code can be found in
- arch/powerpc/boot/cuboot.*.c. Selection of the correct
+ `arch/powerpc/boot/cuboot.*.c`. Selection of the correct
cuImage init code for a specific board can be found in
the wrapper structure.
+
dtbImage.%: Similar to zImage, except device tree blob is embedded
inside the image instead of provided by firmware. The
output image file can be either an elf file or a flat
binary depending on the platform.
- dtbImages are used on systems which do not have an
+
+ dtbImages are used on systems which do not have an
interface for passing a device tree directly.
dtbImages are similar to simpleImages except that
dtbImages have platform specific code for extracting
data from the board firmware, but simpleImages do not
talk to the firmware at all.
- PlayStation 3 support uses dtbImage. So do Embedded
+
+ PlayStation 3 support uses dtbImage. So do Embedded
Planet boards using the PlanetCore firmware. Board
specific initialization code is typically found in a
file named arch/powerpc/boot/<platform>.c; but this
can be overridden by the wrapper script.
+
simpleImage.%: Firmware independent compressed image that does not
depend on any particular firmware interface and embeds
a device tree blob. This image is a flat binary that
@@ -61,14 +69,16 @@ Currently, the following image format targets exist:
Firmware cannot pass any configuration data to the
kernel with this image type and it depends entirely on
the embedded device tree for all information.
- The simpleImage is useful for booting systems with
+
+ The simpleImage is useful for booting systems with
an unknown firmware interface or for booting from
a debugger when no firmware is present (such as on
the Xilinx Virtex platform). The only assumption that
simpleImage makes is that RAM is correctly initialized
and that the MMU is either off or has RAM mapped to
base address 0.
- simpleImage also supports inserting special platform
+
+ simpleImage also supports inserting special platform
specific initialization code to the start of the bootup
sequence. The virtex405 platform uses this feature to
ensure that the cache is invalidated before caching
@@ -81,9 +91,11 @@ Currently, the following image format targets exist:
named (virtex405-<board>.dts). Search the wrapper
script for 'virtex405' and see the file
arch/powerpc/boot/virtex405-head.S for details.
+
treeImage.%; Image format for used with OpenBIOS firmware found
on some ppc4xx hardware. This image embeds a device
tree blob inside the image.
+
uImage: Native image format used by U-Boot. The uImage target
does not add any boot code. It just wraps a compressed
vmlinux in the uImage data structure. This image
@@ -91,12 +103,14 @@ Currently, the following image format targets exist:
a device tree to the kernel at boot. If using an older
version of U-Boot, then you need to use a cuImage
instead.
+
zImage.%: Image format which does not embed a device tree.
Used by OpenFirmware and other firmware interfaces
which are able to supply a device tree. This image
expects firmware to provide the device tree at boot.
Typically, if you have general purpose PowerPC
hardware then you want this image format.
+ ==================== ========================================================
Image types which embed a device tree blob (simpleImage, dtbImage, treeImage,
and cuImage) all generate the device tree blob from a file in the
diff --git a/Documentation/powerpc/cpu_families.txt b/Documentation/powerpc/cpu_families.txt
index fc08e22feb1a..1e063c5440c3 100644
--- a/Documentation/powerpc/cpu_families.txt
+++ b/Documentation/powerpc/cpu_families.txt
@@ -1,3 +1,4 @@
+============
CPU Families
============
@@ -8,8 +9,8 @@ and are supported by arch/powerpc.
Book3S (aka sPAPR)
------------------
- - Hash MMU
- - Mix of 32 & 64 bit
+- Hash MMU
+- Mix of 32 & 64 bit::
+--------------+ +----------------+
| Old POWER | --------------> | RS64 (threads) |
@@ -108,8 +109,8 @@ Book3S (aka sPAPR)
IBM BookE
---------
- - Software loaded TLB.
- - All 32 bit
+- Software loaded TLB.
+- All 32 bit::
+--------------+
| 401 |
@@ -155,8 +156,8 @@ IBM BookE
Motorola/Freescale 8xx
----------------------
- - Software loaded with hardware assist.
- - All 32 bit
+- Software loaded with hardware assist.
+- All 32 bit::
+-------------+
| MPC8xx Core |
@@ -166,9 +167,9 @@ Motorola/Freescale 8xx
Freescale BookE
---------------
- - Software loaded TLB.
- - e6500 adds HW loaded indirect TLB entries.
- - Mix of 32 & 64 bit
+- Software loaded TLB.
+- e6500 adds HW loaded indirect TLB entries.
+- Mix of 32 & 64 bit::
+--------------+
| e200 |
@@ -207,8 +208,8 @@ Freescale BookE
IBM A2 core
-----------
- - Book3E, software loaded TLB + HW loaded indirect TLB entries.
- - 64 bit
+- Book3E, software loaded TLB + HW loaded indirect TLB entries.
+- 64 bit::
+--------------+ +----------------+
| A2 core | --> | WSP |
diff --git a/Documentation/powerpc/cpu_features.txt b/Documentation/powerpc/cpu_features.txt
index ae09df8722c8..b7bcdd2f41bb 100644
--- a/Documentation/powerpc/cpu_features.txt
+++ b/Documentation/powerpc/cpu_features.txt
@@ -1,3 +1,7 @@
+============
+CPU Features
+============
+
Hollis Blanchard <hollis@austin.ibm.com>
5 Jun 2002
@@ -32,7 +36,7 @@ anyways).
After detecting the processor type, the kernel patches out sections of code
that shouldn't be used by writing nop's over it. Using cpufeatures requires
just 2 macros (found in arch/powerpc/include/asm/cputable.h), as seen in head.S
-transfer_to_handler:
+transfer_to_handler::
#ifdef CONFIG_ALTIVEC
BEGIN_FTR_SECTION
diff --git a/Documentation/powerpc/cxl.txt b/Documentation/powerpc/cxl.txt
index c5e8d5098ed3..99e704afb09d 100644
--- a/Documentation/powerpc/cxl.txt
+++ b/Documentation/powerpc/cxl.txt
@@ -1,3 +1,4 @@
+====================================
Coherent Accelerator Interface (CXL)
====================================
@@ -21,6 +22,8 @@ Introduction
Hardware overview
=================
+ ::
+
POWER8/9 FPGA
+----------+ +---------+
| | | |
@@ -59,14 +62,16 @@ Hardware overview
the fault. The context to which this fault is serviced is based on
who owns that acceleration function.
- POWER8 <-----> PSL Version 8 is compliant to the CAIA Version 1.0.
- POWER9 <-----> PSL Version 9 is compliant to the CAIA Version 2.0.
+ - POWER8 <------> PSL Version 8 is compliant to the CAIA Version 1.0.
+ - POWER9 <------> PSL Version 9 is compliant to the CAIA Version 2.0.
+
This PSL Version 9 provides new features such as:
+
* Interaction with the nest MMU on the P9 chip.
* Native DMA support.
* Supports sending ASB_Notify messages for host thread wakeup.
* Supports Atomic operations.
- * ....
+ * etc.
Cards with a PSL9 won't work on a POWER8 system and cards with a
PSL8 won't work on a POWER9 system.
@@ -147,7 +152,9 @@ User API
master devices.
A userspace library libcxl is available here:
+
https://github.com/ibm-capi/libcxl
+
This provides a C interface to this kernel API.
open
@@ -165,7 +172,8 @@ open
When all available contexts are allocated the open call will fail
and return -ENOSPC.
- Note: IRQs need to be allocated for each context, which may limit
+ Note:
+ IRQs need to be allocated for each context, which may limit
the number of contexts that can be created, and therefore
how many times the device can be opened. The POWER8 CAPP
supports 2040 IRQs and 3 are used by the kernel, so 2037 are
@@ -186,7 +194,9 @@ ioctl
updated as userspace allocates and frees memory. This ioctl
returns once the AFU context is started.
- Takes a pointer to a struct cxl_ioctl_start_work:
+ Takes a pointer to a struct cxl_ioctl_start_work
+
+ ::
struct cxl_ioctl_start_work {
__u64 flags;
@@ -269,7 +279,7 @@ read
The buffer passed to read() must be at least 4K bytes.
The result of the read will be a buffer of one or more events,
- each event is of type struct cxl_event, of varying size.
+ each event is of type struct cxl_event, of varying size::
struct cxl_event {
struct cxl_event_header header;
@@ -280,7 +290,9 @@ read
};
};
- The struct cxl_event_header is defined as:
+ The struct cxl_event_header is defined as
+
+ ::
struct cxl_event_header {
__u16 type;
@@ -307,7 +319,9 @@ read
For future extensions and padding.
If the event type is CXL_EVENT_AFU_INTERRUPT then the event
- structure is defined as:
+ structure is defined as
+
+ ::
struct cxl_event_afu_interrupt {
__u16 flags;
@@ -326,7 +340,9 @@ read
For future extensions and padding.
If the event type is CXL_EVENT_DATA_STORAGE then the event
- structure is defined as:
+ structure is defined as
+
+ ::
struct cxl_event_data_storage {
__u16 flags;
@@ -356,7 +372,9 @@ read
For future extensions
If the event type is CXL_EVENT_AFU_ERROR then the event structure
- is defined as:
+ is defined as
+
+ ::
struct cxl_event_afu_error {
__u16 flags;
@@ -393,15 +411,15 @@ open
ioctl
-----
-CXL_IOCTL_DOWNLOAD_IMAGE:
-CXL_IOCTL_VALIDATE_IMAGE:
+CXL_IOCTL_DOWNLOAD_IMAGE / CXL_IOCTL_VALIDATE_IMAGE:
Starts and controls flashing a new FPGA image. Partial
reconfiguration is not supported (yet), so the image must contain
a copy of the PSL and AFU(s). Since an image can be quite large,
the caller may have to iterate, splitting the image in smaller
chunks.
- Takes a pointer to a struct cxl_adapter_image:
+ Takes a pointer to a struct cxl_adapter_image::
+
struct cxl_adapter_image {
__u64 flags;
__u64 data;
@@ -442,7 +460,7 @@ Udev rules
The following udev rules could be used to create a symlink to the
most logical chardev to use in any programming mode (afuX.Yd for
dedicated, afuX.Ys for afu directed), since the API is virtually
- identical for each:
+ identical for each::
SUBSYSTEM=="cxl", ATTRS{mode}=="dedicated_process", SYMLINK="cxl/%b"
SUBSYSTEM=="cxl", ATTRS{mode}=="afu_directed", \
diff --git a/Documentation/powerpc/cxlflash.txt b/Documentation/powerpc/cxlflash.txt
index a64bdaa0a1cf..9d79962f1999 100644
--- a/Documentation/powerpc/cxlflash.txt
+++ b/Documentation/powerpc/cxlflash.txt
@@ -1,3 +1,7 @@
+================================
+Coherent Accelerator (CXL) Flash
+================================
+
Introduction
============
@@ -58,7 +62,7 @@ Overview
The CXL Flash Adapter Driver establishes a master context with the
AFU. It uses memory mapped I/O (MMIO) for this control and setup. The
- Adapter Problem Space Memory Map looks like this:
+ Adapter Problem Space Memory Map looks like this::
+-------------------------------+
| 512 * 64 KB User MMIO |
@@ -375,7 +379,7 @@ CXL Flash Driver Host IOCTLs
Each host adapter instance that is supported by the cxlflash driver
has a special character device associated with it to enable a set of
host management function. These character devices are hosted in a
- class dedicated for cxlflash and can be accessed via /dev/cxlflash/*.
+ class dedicated for cxlflash and can be accessed via `/dev/cxlflash/*`.
Applications can be written to perform various functions using the
host ioctl APIs below.
diff --git a/Documentation/powerpc/dscr.txt b/Documentation/powerpc/dscr.txt
index ece300c64f76..2ab99006014c 100644
--- a/Documentation/powerpc/dscr.txt
+++ b/Documentation/powerpc/dscr.txt
@@ -1,5 +1,6 @@
- DSCR (Data Stream Control Register)
- ================================================
+===================================
+DSCR (Data Stream Control Register)
+===================================
DSCR register in powerpc allows user to have some control of prefetch of data
stream in the processor. Please refer to the ISA documents or related manual
@@ -10,14 +11,17 @@ user interface.
(A) Data Structures:
- (1) thread_struct:
+ (1) thread_struct::
+
dscr /* Thread DSCR value */
dscr_inherit /* Thread has changed default DSCR */
- (2) PACA:
+ (2) PACA::
+
dscr_default /* per-CPU DSCR default value */
- (3) sysfs.c:
+ (3) sysfs.c::
+
dscr_default /* System DSCR default value */
(B) Scheduler Changes:
@@ -35,8 +39,8 @@ user interface.
(C) SYSFS Interface:
- Global DSCR default: /sys/devices/system/cpu/dscr_default
- CPU specific DSCR default: /sys/devices/system/cpu/cpuN/dscr
+ - Global DSCR default: /sys/devices/system/cpu/dscr_default
+ - CPU specific DSCR default: /sys/devices/system/cpu/cpuN/dscr
Changing the global DSCR default in the sysfs will change all the CPU
specific DSCR defaults immediately in their PACA structures. Again if
diff --git a/Documentation/powerpc/eeh-pci-error-recovery.txt b/Documentation/powerpc/eeh-pci-error-recovery.txt
index 678189280bb4..438a87ebc095 100644
--- a/Documentation/powerpc/eeh-pci-error-recovery.txt
+++ b/Documentation/powerpc/eeh-pci-error-recovery.txt
@@ -1,10 +1,10 @@
+==========================
+PCI Bus EEH Error Recovery
+==========================
+Linas Vepstas <linas@austin.ibm.com>
- PCI Bus EEH Error Recovery
- --------------------------
- Linas Vepstas
- <linas@austin.ibm.com>
- 12 January 2005
+12 January 2005
Overview:
@@ -143,17 +143,17 @@ seen in /proc/ppc64/eeh (subject to change). Normally, almost
all of these occur during boot, when the PCI bus is scanned, where
a large number of 0xff reads are part of the bus scan procedure.
-If a frozen slot is detected, code in
-arch/powerpc/platforms/pseries/eeh.c will print a stack trace to
-syslog (/var/log/messages). This stack trace has proven to be very
-useful to device-driver authors for finding out at what point the EEH
-error was detected, as the error itself usually occurs slightly
+If a frozen slot is detected, code in
+arch/powerpc/platforms/pseries/eeh.c will print a stack trace to
+syslog (/var/log/messages). This stack trace has proven to be very
+useful to device-driver authors for finding out at what point the EEH
+error was detected, as the error itself usually occurs slightly
beforehand.
Next, it uses the Linux kernel notifier chain/work queue mechanism to
allow any interested parties to find out about the failure. Device
drivers, or other parts of the kernel, can use
-eeh_register_notifier(struct notifier_block *) to find out about EEH
+`eeh_register_notifier(struct notifier_block *)` to find out about EEH
events. The event will include a pointer to the pci device, the
device node and some state info. Receivers of the event can "do as
they wish"; the default handler will be described further in this
@@ -162,10 +162,13 @@ section.
To assist in the recovery of the device, eeh.c exports the
following functions:
-rtas_set_slot_reset() -- assert the PCI #RST line for 1/8th of a second
-rtas_configure_bridge() -- ask firmware to configure any PCI bridges
+rtas_set_slot_reset()
+ assert the PCI #RST line for 1/8th of a second
+rtas_configure_bridge()
+ ask firmware to configure any PCI bridges
located topologically under the pci slot.
-eeh_save_bars() and eeh_restore_bars(): save and restore the PCI
+eeh_save_bars() and eeh_restore_bars():
+ save and restore the PCI
config-space info for a device and any devices under it.
@@ -191,7 +194,7 @@ events get delivered to user-space scripts.
Following is an example sequence of events that cause a device driver
close function to be called during the first phase of an EEH reset.
-The following sequence is an example of the pcnet32 device driver.
+The following sequence is an example of the pcnet32 device driver::
rpa_php_unconfig_pci_adapter (struct slot *) // in rpaphp_pci.c
{
@@ -241,53 +244,54 @@ The following sequence is an example of the pcnet32 device driver.
}}}}}}
- in drivers/pci/pci_driver.c,
- struct device_driver->remove() is just pci_device_remove()
- which calls struct pci_driver->remove() which is pcnet32_remove_one()
- which calls unregister_netdev() (in net/core/dev.c)
- which calls dev_close() (in net/core/dev.c)
- which calls dev->stop() which is pcnet32_close()
- which then does the appropriate shutdown.
+in drivers/pci/pci_driver.c,
+struct device_driver->remove() is just pci_device_remove()
+which calls struct pci_driver->remove() which is pcnet32_remove_one()
+which calls unregister_netdev() (in net/core/dev.c)
+which calls dev_close() (in net/core/dev.c)
+which calls dev->stop() which is pcnet32_close()
+which then does the appropriate shutdown.
---
+
Following is the analogous stack trace for events sent to user-space
-when the pci device is unconfigured.
+when the pci device is unconfigured::
-rpa_php_unconfig_pci_adapter() { // in rpaphp_pci.c
- calls
- pci_remove_bus_device (struct pci_dev *) { // in /drivers/pci/remove.c
+ rpa_php_unconfig_pci_adapter() { // in rpaphp_pci.c
calls
- pci_destroy_dev (struct pci_dev *) {
+ pci_remove_bus_device (struct pci_dev *) { // in /drivers/pci/remove.c
calls
- device_unregister (&dev->dev) { // in /drivers/base/core.c
+ pci_destroy_dev (struct pci_dev *) {
calls
- device_del(struct device * dev) { // in /drivers/base/core.c
+ device_unregister (&dev->dev) { // in /drivers/base/core.c
calls
- kobject_del() { //in /libs/kobject.c
+ device_del(struct device * dev) { // in /drivers/base/core.c
calls
- kobject_uevent() { // in /libs/kobject.c
+ kobject_del() { //in /libs/kobject.c
calls
- kset_uevent() { // in /lib/kobject.c
+ kobject_uevent() { // in /libs/kobject.c
calls
- kset->uevent_ops->uevent() // which is really just
- a call to
- dev_uevent() { // in /drivers/base/core.c
+ kset_uevent() { // in /lib/kobject.c
calls
- dev->bus->uevent() which is really just a call to
- pci_uevent () { // in drivers/pci/hotplug.c
- which prints device name, etc....
+ kset->uevent_ops->uevent() // which is really just
+ a call to
+ dev_uevent() { // in /drivers/base/core.c
+ calls
+ dev->bus->uevent() which is really just a call to
+ pci_uevent () { // in drivers/pci/hotplug.c
+ which prints device name, etc....
+ }
}
- }
- then kobject_uevent() sends a netlink uevent to userspace
- --> userspace uevent
- (during early boot, nobody listens to netlink events and
- kobject_uevent() executes uevent_helper[], which runs the
- event process /sbin/hotplug)
+ then kobject_uevent() sends a netlink uevent to userspace
+ --> userspace uevent
+ (during early boot, nobody listens to netlink events and
+ kobject_uevent() executes uevent_helper[], which runs the
+ event process /sbin/hotplug)
+ }
}
- }
- kobject_del() then calls sysfs_remove_dir(), which would
- trigger any user-space daemon that was watching /sysfs,
- and notice the delete event.
+ kobject_del() then calls sysfs_remove_dir(), which would
+ trigger any user-space daemon that was watching /sysfs,
+ and notice the delete event.
Pro's and Con's of the Current Design
@@ -299,12 +303,12 @@ individual device drivers, so that the current design throws a wide net.
The biggest negative of the design is that it potentially disturbs
network daemons and file systems that didn't need to be disturbed.
--- A minor complaint is that resetting the network card causes
+- A minor complaint is that resetting the network card causes
user-space back-to-back ifdown/ifup burps that potentially disturb
network daemons, that didn't need to even know that the pci
card was being rebooted.
--- A more serious concern is that the same reset, for SCSI devices,
+- A more serious concern is that the same reset, for SCSI devices,
causes havoc to mounted file systems. Scripts cannot post-facto
unmount a file system without flushing pending buffers, but this
is impossible, because I/O has already been stopped. Thus,
@@ -322,7 +326,7 @@ network daemons and file systems that didn't need to be disturbed.
from the block layer. It would be very natural to add an EEH
reset into this chain of events.
--- If a SCSI error occurs for the root device, all is lost unless
+- If a SCSI error occurs for the root device, all is lost unless
the sysadmin had the foresight to run /bin, /sbin, /etc, /var
and so on, out of ramdisk/tmpfs.
@@ -330,5 +334,3 @@ network daemons and file systems that didn't need to be disturbed.
Conclusions
-----------
There's forward progress ...
-
-
diff --git a/Documentation/powerpc/firmware-assisted-dump.txt b/Documentation/powerpc/firmware-assisted-dump.txt
index 18c5feef2577..5cc4cb242130 100644
--- a/Documentation/powerpc/firmware-assisted-dump.txt
+++ b/Documentation/powerpc/firmware-assisted-dump.txt
@@ -1,7 +1,8 @@
+======================
+Firmware-Assisted Dump
+======================
- Firmware-Assisted Dump
- ------------------------
- July 2011
+July 2011
The goal of firmware-assisted dump is to enable the dump of
a crashed system, and to do so from a fully-reset system, and
@@ -27,11 +28,11 @@ in production use.
Comparing with kdump or other strategies, firmware-assisted
dump offers several strong, practical advantages:
--- Unlike kdump, the system has been reset, and loaded
+- Unlike kdump, the system has been reset, and loaded
with a fresh copy of the kernel. In particular,
PCI and I/O devices have been reinitialized and are
in a clean, consistent state.
--- Once the dump is copied out, the memory that held the dump
+- Once the dump is copied out, the memory that held the dump
is immediately available to the running kernel. And therefore,
unlike kdump, fadump doesn't need a 2nd reboot to get back
the system to the production configuration.
@@ -40,17 +41,18 @@ The above can only be accomplished by coordination with,
and assistance from the Power firmware. The procedure is
as follows:
--- The first kernel registers the sections of memory with the
+- The first kernel registers the sections of memory with the
Power firmware for dump preservation during OS initialization.
These registered sections of memory are reserved by the first
kernel during early boot.
--- When a system crashes, the Power firmware will save
+- When a system crashes, the Power firmware will save
the low memory (boot memory of size larger of 5% of system RAM
or 256MB) of RAM to the previous registered region. It will
also save system registers, and hardware PTE's.
- NOTE: The term 'boot memory' means size of the low memory chunk
+ NOTE:
+ The term 'boot memory' means size of the low memory chunk
that is required for a kernel to boot successfully when
booted with restricted memory. By default, the boot memory
size will be the larger of 5% of system RAM or 256MB.
@@ -64,12 +66,12 @@ as follows:
as fadump uses a predefined offset to reserve memory
for boot memory dump preservation in case of a crash.
--- After the low memory (boot memory) area has been saved, the
+- After the low memory (boot memory) area has been saved, the
firmware will reset PCI and other hardware state. It will
*not* clear the RAM. It will then launch the bootloader, as
normal.
--- The freshly booted kernel will notice that there is a new
+- The freshly booted kernel will notice that there is a new
node (ibm,dump-kernel) in the device tree, indicating that
there is crash data available from a previous boot. During
the early boot OS will reserve rest of the memory above
@@ -77,17 +79,18 @@ as follows:
size. This will make sure that the second kernel will not
touch any of the dump memory area.
--- User-space tools will read /proc/vmcore to obtain the contents
+- User-space tools will read /proc/vmcore to obtain the contents
of memory, which holds the previous crashed kernel dump in ELF
format. The userspace tools may copy this info to disk, or
network, nas, san, iscsi, etc. as desired.
--- Once the userspace tool is done saving dump, it will echo
+- Once the userspace tool is done saving dump, it will echo
'1' to /sys/kernel/fadump_release_mem to release the reserved
memory back to general use, except the memory required for
next firmware-assisted dump registration.
- e.g.
+ e.g.::
+
# echo 1 > /sys/kernel/fadump_release_mem
Please note that the firmware-assisted dump feature
@@ -95,7 +98,7 @@ is only available on Power6 and above systems with recent
firmware versions.
Implementation details:
-----------------------
+-----------------------
During boot, a check is made to see if firmware supports
this feature on that particular machine. If it does, then
@@ -121,7 +124,7 @@ Allocator (CMA) for memory reservation if CMA is configured for kernel.
With CMA reservation this memory will be available for applications to
use it, while kernel is prevented from using it. With this fadump will
still be able to capture all of the kernel memory and most of the user
-space memory except the user pages that were present in CMA region.
+space memory except the user pages that were present in CMA region::
o Memory Reservation during first kernel
@@ -166,7 +169,7 @@ The tools to examine the dump will be same as the ones
used for kdump.
How to enable firmware-assisted dump (fadump):
--------------------------------------
+----------------------------------------------
1. Set config option CONFIG_FA_DUMP=y and build kernel.
2. Boot into linux kernel with 'fadump=on' kernel cmdline option.
@@ -177,19 +180,20 @@ How to enable firmware-assisted dump (fadump):
to specify size of the memory to reserve for boot memory dump
preservation.
-NOTE: 1. 'fadump_reserve_mem=' parameter has been deprecated. Instead
- use 'crashkernel=' to specify size of the memory to reserve
- for boot memory dump preservation.
- 2. If firmware-assisted dump fails to reserve memory then it
- will fallback to existing kdump mechanism if 'crashkernel='
- option is set at kernel cmdline.
- 3. if user wants to capture all of user space memory and ok with
- reserved memory not available to production system, then
- 'fadump=nocma' kernel parameter can be used to fallback to
- old behaviour.
+NOTE:
+ 1. 'fadump_reserve_mem=' parameter has been deprecated. Instead
+ use 'crashkernel=' to specify size of the memory to reserve
+ for boot memory dump preservation.
+ 2. If firmware-assisted dump fails to reserve memory then it
+ will fallback to existing kdump mechanism if 'crashkernel='
+ option is set at kernel cmdline.
+ 3. if user wants to capture all of user space memory and ok with
+ reserved memory not available to production system, then
+ 'fadump=nocma' kernel parameter can be used to fallback to
+ old behaviour.
Sysfs/debugfs files:
-------------
+--------------------
Firmware-assisted dump feature uses sysfs file system to hold
the control files and debugfs file to display memory reserved region.
@@ -197,20 +201,20 @@ the control files and debugfs file to display memory reserved region.
Here is the list of files under kernel sysfs:
/sys/kernel/fadump_enabled
-
This is used to display the fadump status.
- 0 = fadump is disabled
- 1 = fadump is enabled
+
+ - 0 = fadump is disabled
+ - 1 = fadump is enabled
This interface can be used by kdump init scripts to identify if
fadump is enabled in the kernel and act accordingly.
/sys/kernel/fadump_registered
-
This is used to display the fadump registration status as well
as to control (start/stop) the fadump registration.
- 0 = fadump is not registered.
- 1 = fadump is registered and ready to handle system crash.
+
+ - 0 = fadump is not registered.
+ - 1 = fadump is registered and ready to handle system crash.
To register fadump echo 1 > /sys/kernel/fadump_registered and
echo 0 > /sys/kernel/fadump_registered for un-register and stop the
@@ -219,13 +223,12 @@ Here is the list of files under kernel sysfs:
easily integrated with kdump service start/stop.
/sys/kernel/fadump_release_mem
-
This file is available only when fadump is active during
second kernel. This is used to release the reserved memory
region that are held for saving crash dump. To release the
- reserved memory echo 1 to it:
+ reserved memory echo 1 to it::
- echo 1 > /sys/kernel/fadump_release_mem
+ echo 1 > /sys/kernel/fadump_release_mem
After echo 1, the content of the /sys/kernel/debug/powerpc/fadump_region
file will change to reflect the new memory reservations.
@@ -238,38 +241,39 @@ Here is the list of files under powerpc debugfs:
(Assuming debugfs is mounted on /sys/kernel/debug directory.)
/sys/kernel/debug/powerpc/fadump_region
-
This file shows the reserved memory regions if fadump is
enabled otherwise this file is empty. The output format
- is:
- <region>: [<start>-<end>] <reserved-size> bytes, Dumped: <dump-size>
+ is::
+
+ <region>: [<start>-<end>] <reserved-size> bytes, Dumped: <dump-size>
e.g.
- Contents when fadump is registered during first kernel
+ Contents when fadump is registered during first kernel::
- # cat /sys/kernel/debug/powerpc/fadump_region
- CPU : [0x0000006ffb0000-0x0000006fff001f] 0x40020 bytes, Dumped: 0x0
- HPTE: [0x0000006fff0020-0x0000006fff101f] 0x1000 bytes, Dumped: 0x0
- DUMP: [0x0000006fff1020-0x0000007fff101f] 0x10000000 bytes, Dumped: 0x0
+ # cat /sys/kernel/debug/powerpc/fadump_region
+ CPU : [0x0000006ffb0000-0x0000006fff001f] 0x40020 bytes, Dumped: 0x0
+ HPTE: [0x0000006fff0020-0x0000006fff101f] 0x1000 bytes, Dumped: 0x0
+ DUMP: [0x0000006fff1020-0x0000007fff101f] 0x10000000 bytes, Dumped: 0x0
- Contents when fadump is active during second kernel
+ Contents when fadump is active during second kernel::
- # cat /sys/kernel/debug/powerpc/fadump_region
- CPU : [0x0000006ffb0000-0x0000006fff001f] 0x40020 bytes, Dumped: 0x40020
- HPTE: [0x0000006fff0020-0x0000006fff101f] 0x1000 bytes, Dumped: 0x1000
- DUMP: [0x0000006fff1020-0x0000007fff101f] 0x10000000 bytes, Dumped: 0x10000000
- : [0x00000010000000-0x0000006ffaffff] 0x5ffb0000 bytes, Dumped: 0x5ffb0000
+ # cat /sys/kernel/debug/powerpc/fadump_region
+ CPU : [0x0000006ffb0000-0x0000006fff001f] 0x40020 bytes, Dumped: 0x40020
+ HPTE: [0x0000006fff0020-0x0000006fff101f] 0x1000 bytes, Dumped: 0x1000
+ DUMP: [0x0000006fff1020-0x0000007fff101f] 0x10000000 bytes, Dumped: 0x10000000
+ : [0x00000010000000-0x0000006ffaffff] 0x5ffb0000 bytes, Dumped: 0x5ffb0000
-NOTE: Please refer to Documentation/filesystems/debugfs.txt on
+NOTE:
+ Please refer to Documentation/filesystems/debugfs.txt on
how to mount the debugfs filesystem.
TODO:
-----
- o Need to come up with the better approach to find out more
+ - Need to come up with the better approach to find out more
accurate boot memory size that is required for a kernel to
boot successfully when booted with restricted memory.
- o The fadump implementation introduces a fadump crash info structure
+ - The fadump implementation introduces a fadump crash info structure
in the scratch area before the ELF core header. The idea of introducing
this structure is to pass some important crash info data to the second
kernel which will help second kernel to populate ELF core header with
@@ -277,7 +281,9 @@ TODO:
design implementation does not address a possibility of introducing
additional fields (in future) to this structure without affecting
compatibility. Need to come up with the better approach to address this.
+
The possible approaches are:
+
1. Introduce version field for version tracking, bump up the version
whenever a new field is added to the structure in future. The version
field can be used to find out what fields are valid for the current
@@ -285,8 +291,11 @@ TODO:
2. Reserve the area of predefined size (say PAGE_SIZE) for this
structure and have unused area as reserved (initialized to zero)
for future field additions.
+
The advantage of approach 1 over 2 is we don't need to reserve extra space.
----
+
Author: Mahesh Salgaonkar <mahesh@linux.vnet.ibm.com>
+
This document is based on the original documentation written for phyp
+
assisted dump by Linas Vepstas and Manish Ahuja.
diff --git a/Documentation/powerpc/hvcs.txt b/Documentation/powerpc/hvcs.txt
index a730ca5a07f8..6808acde672f 100644
--- a/Documentation/powerpc/hvcs.txt
+++ b/Documentation/powerpc/hvcs.txt
@@ -1,19 +1,22 @@
-===========================================================================
- HVCS
- IBM "Hypervisor Virtual Console Server" Installation Guide
- for Linux Kernel 2.6.4+
- Copyright (C) 2004 IBM Corporation
+===============================================================
+HVCS IBM "Hypervisor Virtual Console Server" Installation Guide
+===============================================================
-===========================================================================
-NOTE:Eight space tabs are the optimum editor setting for reading this file.
-===========================================================================
+for Linux Kernel 2.6.4+
- Author(s) : Ryan S. Arnold <rsa@us.ibm.com>
- Date Created: March, 02, 2004
- Last Changed: August, 24, 2004
+Copyright (C) 2004 IBM Corporation
----------------------------------------------------------------------------
-Table of contents:
+.. ===========================================================================
+.. NOTE:Eight space tabs are the optimum editor setting for reading this file.
+.. ===========================================================================
+
+
+Author(s): Ryan S. Arnold <rsa@us.ibm.com>
+
+Date Created: March, 02, 2004
+Last Changed: August, 24, 2004
+
+.. Table of contents:
1. Driver Introduction:
2. System Requirements
@@ -27,8 +30,8 @@ Table of contents:
8. Questions & Answers:
9. Reporting Bugs:
----------------------------------------------------------------------------
1. Driver Introduction:
+=======================
This is the device driver for the IBM Hypervisor Virtual Console Server,
"hvcs". The IBM hvcs provides a tty driver interface to allow Linux user
@@ -38,8 +41,8 @@ ppc64 system. Physical hardware consoles per partition are not practical
on this hardware so system consoles are accessed by this driver using
firmware interfaces to virtual terminal devices.
----------------------------------------------------------------------------
2. System Requirements:
+=======================
This device driver was written using 2.6.4 Linux kernel APIs and will only
build and run on kernels of this version or later.
@@ -52,8 +55,8 @@ Sysfs must be mounted on the system so that the user can determine which
major and minor numbers are associated with each vty-server. Directions
for sysfs mounting are outside the scope of this document.
----------------------------------------------------------------------------
3. Build Options:
+=================
The hvcs driver registers itself as a tty driver. The tty layer
dynamically allocates a block of major and minor numbers in a quantity
@@ -65,11 +68,11 @@ If the default number of device entries is adequate then this driver can be
built into the kernel. If not, the default can be over-ridden by inserting
the driver as a module with insmod parameters.
----------------------------------------------------------------------------
3.1 Built-in:
+-------------
The following menuconfig example demonstrates selecting to build this
-driver into the kernel.
+driver into the kernel::
Device Drivers --->
Character devices --->
@@ -77,11 +80,11 @@ driver into the kernel.
Begin the kernel make process.
----------------------------------------------------------------------------
3.2 Module:
+-----------
The following menuconfig example demonstrates selecting to build this
-driver as a kernel module.
+driver as a kernel module::
Device Drivers --->
Character devices --->
@@ -89,11 +92,11 @@ driver as a kernel module.
The make process will build the following kernel modules:
- hvcs.ko
- hvcserver.ko
+ - hvcs.ko
+ - hvcserver.ko
To insert the module with the default allocation execute the following
-commands in the order they appear:
+commands in the order they appear::
insmod hvcserver.ko
insmod hvcs.ko
@@ -103,7 +106,7 @@ be inserted first, otherwise the hvcs module will not find some of the
symbols it expects.
To override the default use an insmod parameter as follows (requesting 4
-tty devices as an example):
+tty devices as an example)::
insmod hvcs.ko hvcs_parm_num_devs=4
@@ -115,31 +118,31 @@ source file before building.
NOTE: The length of time it takes to insmod the driver seems to be related
to the number of tty interfaces the registering driver requests.
-In order to remove the driver module execute the following command:
+In order to remove the driver module execute the following command::
rmmod hvcs.ko
The recommended method for installing hvcs as a module is to use depmod to
build a current modules.dep file in /lib/modules/`uname -r` and then
-execute:
+execute::
-modprobe hvcs hvcs_parm_num_devs=4
+ modprobe hvcs hvcs_parm_num_devs=4
The modules.dep file indicates that hvcserver.ko needs to be inserted
before hvcs.ko and modprobe uses this file to smartly insert the modules in
the proper order.
The following modprobe command is used to remove hvcs and hvcserver in the
-proper order:
+proper order::
-modprobe -r hvcs
+ modprobe -r hvcs
----------------------------------------------------------------------------
4. Installation:
+================
The tty layer creates sysfs entries which contain the major and minor
numbers allocated for the hvcs driver. The following snippet of "tree"
-output of the sysfs directory shows where these numbers are presented:
+output of the sysfs directory shows where these numbers are presented::
sys/
|-- *other sysfs base dirs*
@@ -164,7 +167,7 @@ output of the sysfs directory shows where these numbers are presented:
|-- *other sysfs base dirs*
For the above examples the following output is a result of cat'ing the
-"dev" entry in the hvcs directory:
+"dev" entry in the hvcs directory::
Pow5:/sys/class/tty/hvcs0/ # cat dev
254:0
@@ -184,7 +187,7 @@ systems running hvcs will already have the device entries created or udev
will do it automatically.
Given the example output above, to manually create a /dev/hvcs* node entry
-mknod can be used as follows:
+mknod can be used as follows::
mknod /dev/hvcs0 c 254 0
mknod /dev/hvcs1 c 254 1
@@ -195,15 +198,15 @@ Using mknod to manually create the device entries makes these device nodes
persistent. Once created they will exist prior to the driver insmod.
Attempting to connect an application to /dev/hvcs* prior to insertion of
-the hvcs module will result in an error message similar to the following:
+the hvcs module will result in an error message similar to the following::
"/dev/hvcs*: No such device".
NOTE: Just because there is a device node present doesn't mean that there
is a vty-server device configured for that node.
----------------------------------------------------------------------------
5. Connection
+=============
Since this driver controls devices that provide a tty interface a user can
interact with the device node entries using any standard tty-interactive
@@ -249,7 +252,7 @@ vty-server adapter is associated with which /dev/hvcs* node a special sysfs
attribute has been added to each vty-server sysfs entry. This entry is
called "index" and showing it reveals an integer that refers to the
/dev/hvcs* entry to use to connect to that device. For instance cating the
-index attribute of vty-server adapter 30000004 shows the following.
+index attribute of vty-server adapter 30000004 shows the following::
Pow5:/sys/bus/vio/drivers/hvcs/30000004 # cat index
2
@@ -262,8 +265,8 @@ system the /dev/hvcs* entry that interacts with a particular vty-server
adapter is not guaranteed to remain the same across system reboots. Look
in the Q & A section for more on this issue.
----------------------------------------------------------------------------
6. Disconnection
+================
As a security feature to prevent the delivery of stale data to an
unintended target the Power5 system firmware disables the fetching of data
@@ -305,7 +308,7 @@ connection between the vty-server and target vty ONLY if the vterm_state
previously read '1'. The write directive is ignored if the vterm_state
read '0' or if any value other than '0' was written to the vterm_state
attribute. The following example will show the method used for verifying
-the vty-server connection status and disconnecting a vty-server connection.
+the vty-server connection status and disconnecting a vty-server connection::
Pow5:/sys/bus/vio/drivers/hvcs/30000004 # cat vterm_state
1
@@ -318,12 +321,12 @@ the vty-server connection status and disconnecting a vty-server connection.
All vty-server connections are automatically terminated when the device is
hotplug removed and when the module is removed.
----------------------------------------------------------------------------
7. Configuration
+================
Each vty-server has a sysfs entry in the /sys/devices/vio directory, which
is symlinked in several other sysfs tree directories, notably under the
-hvcs driver entry, which looks like the following example:
+hvcs driver entry, which looks like the following example::
Pow5:/sys/bus/vio/drivers/hvcs # ls
. .. 30000003 30000004 rescan
@@ -344,7 +347,7 @@ completed or was never executed.
Vty-server entries in this directory are a 32 bit partition unique unit
address that is created by firmware. An example vty-server sysfs entry
-looks like the following:
+looks like the following::
Pow5:/sys/bus/vio/drivers/hvcs/30000004 # ls
. current_vty devspec name partner_vtys
@@ -352,21 +355,21 @@ looks like the following:
Each entry is provided, by default with a "name" attribute. Reading the
"name" attribute will reveal the device type as shown in the following
-example:
+example::
Pow5:/sys/bus/vio/drivers/hvcs/30000003 # cat name
vty-server
Each entry is also provided, by default, with a "devspec" attribute which
reveals the full device specification when read, as shown in the following
-example:
+example::
Pow5:/sys/bus/vio/drivers/hvcs/30000004 # cat devspec
/vdevice/vty-server@30000004
Each vty-server sysfs dir is provided with two read-only attributes that
provide lists of easily parsed partner vty data: "partner_vtys" and
-"partner_clcs".
+"partner_clcs"::
Pow5:/sys/bus/vio/drivers/hvcs/30000004 # cat partner_vtys
30000000
@@ -396,7 +399,7 @@ A vty-server can only be connected to a single vty at a time. The entry,
read.
The current_vty can be changed by writing a valid partner clc to the entry
-as in the following example:
+as in the following example::
Pow5:/sys/bus/vio/drivers/hvcs/30000004 # echo U5112.428.10304
8A-V4-C0 > current_vty
@@ -408,9 +411,9 @@ currently open connection is freed.
Information on the "vterm_state" attribute was covered earlier on the
chapter entitled "disconnection".
----------------------------------------------------------------------------
8. Questions & Answers:
-===========================================================================
+=======================
+
Q: What are the security concerns involving hvcs?
A: There are three main security concerns:
@@ -429,6 +432,7 @@ A: There are three main security concerns:
partition) will experience the previously logged in session.
---------------------------------------------------------------------------
+
Q: How do I multiplex a console that I grab through hvcs so that other
people can see it:
@@ -440,6 +444,7 @@ term type "screen" to others. This means that curses based programs may
not display properly in screen sessions.
---------------------------------------------------------------------------
+
Q: Why are the colors all messed up?
Q: Why are the control characters acting strange or not working?
Q: Why is the console output all strange and unintelligible?
@@ -455,6 +460,7 @@ disconnect from the console. This will ensure that the next user gets
their own TERM type set when they login.
---------------------------------------------------------------------------
+
Q: When I try to CONNECT kermit to an hvcs device I get:
"Sorry, can't open connection: /dev/hvcs*"What is happening?
@@ -490,6 +496,7 @@ A: There is not a corresponding vty-server device that maps to an existing
/dev/hvcs* entry.
---------------------------------------------------------------------------
+
Q: When I try to CONNECT kermit to an hvcs device I get:
"Sorry, write access to UUCP lockfile directory denied."
@@ -497,6 +504,7 @@ A: The /dev/hvcs* entry you have specified doesn't exist where you said it
does? Maybe you haven't inserted the module (on systems with udev).
---------------------------------------------------------------------------
+
Q: If I already have one Linux partition installed can I use hvcs on said
partition to provide the console for the install of a second Linux
partition?
@@ -505,6 +513,7 @@ A: Yes granted that your are connected to the /dev/hvcs* device using
kermit or cu or some other program that doesn't provide terminal emulation.
---------------------------------------------------------------------------
+
Q: Can I connect to more than one partition's console at a time using this
driver?
@@ -512,6 +521,7 @@ A: Yes. Of course this means that there must be more than one vty-server
configured for this partition and each must point to a disconnected vty.
---------------------------------------------------------------------------
+
Q: Does the hvcs driver support dynamic (hotplug) addition of devices?
A: Yes, if you have dlpar and hotplug enabled for your system and it has
@@ -519,6 +529,7 @@ been built into the kernel the hvcs drivers is configured to dynamically
handle additions of new devices and removals of unused devices.
---------------------------------------------------------------------------
+
Q: For some reason /dev/hvcs* doesn't map to the same vty-server adapter
after a reboot. What happened?
@@ -533,6 +544,7 @@ on how to determine which vty-server goes with which /dev/hvcs* node.
Hint; look at the sysfs "index" attribute for the vty-server.
---------------------------------------------------------------------------
+
Q: Can I use /dev/hvcs* as a conduit to another partition and use a tty
device on that partition as the other end of the pipe?
@@ -554,7 +566,9 @@ read or write to /dev/hvcs*. Now you have a tty conduit between two
partitions.
---------------------------------------------------------------------------
+
9. Reporting Bugs:
+==================
The proper channel for reporting bugs is either through the Linux OS
distribution company that provided your OS or by posting issues to the
diff --git a/Documentation/powerpc/isa-versions.rst b/Documentation/powerpc/isa-versions.rst
index 812e20cc898c..a363d8c1603c 100644
--- a/Documentation/powerpc/isa-versions.rst
+++ b/Documentation/powerpc/isa-versions.rst
@@ -1,11 +1,12 @@
+==========================
CPU to ISA Version Mapping
==========================
Mapping of some CPU versions to relevant ISA versions.
-========= ====================
+========= ====================================================================
CPU Architecture version
-========= ====================
+========= ====================================================================
Power9 Power ISA v3.0B
Power8 Power ISA v2.07
Power7 Power ISA v2.06
@@ -22,7 +23,7 @@ PPC970 - PowerPC User Instruction Set Architecture Book I v2.01
- PowerPC Virtual Environment Architecture Book II v2.01
- PowerPC Operating Environment Architecture Book III v2.01
- Plus Altivec/VMX ~= 2.03
-========= ====================
+========= ====================================================================
Key Features
@@ -58,9 +59,9 @@ Power5 No
PPC970 No
========== ====
-========== ====================
+========== ====================================
CPU Transactional Memory
-========== ====================
+========== ====================================
Power9 Yes (* see transactional_memory.txt)
Power8 Yes
Power7 No
@@ -71,4 +72,4 @@ Power5++ No
Power5+ No
Power5 No
PPC970 No
-========== ====================
+========== ====================================
diff --git a/Documentation/powerpc/mpc52xx.txt b/Documentation/powerpc/mpc52xx.txt
index 0d540a31ea1a..8676ac63e077 100644
--- a/Documentation/powerpc/mpc52xx.txt
+++ b/Documentation/powerpc/mpc52xx.txt
@@ -1,11 +1,13 @@
+=============================
Linux 2.6.x on MPC52xx family
------------------------------
+=============================
For the latest info, go to http://www.246tNt.com/mpc52xx/
To compile/use :
- - U-Boot:
+ - U-Boot::
+
# <edit Makefile to set ARCH=ppc & CROSS_COMPILE=... ( also EXTRAVERSION
if you wish to ).
# make lite5200_defconfig
@@ -16,7 +18,8 @@ To compile/use :
=> tftpboot 400000 pRamdisk
=> bootm 200000 400000
- - DBug:
+ - DBug::
+
# <edit Makefile to set ARCH=ppc & CROSS_COMPILE=... ( also EXTRAVERSION
if you wish to ).
# make lite5200_defconfig
@@ -28,7 +31,8 @@ To compile/use :
DBug> dn -i zImage.initrd.lite5200
-Some remarks :
+Some remarks:
+
- The port is named mpc52xxx, and config options are PPC_MPC52xx. The MGT5100
is not supported, and I'm not sure anyone is interesting in working on it
so. I didn't took 5xxx because there's apparently a lot of 5xxx that have
diff --git a/Documentation/powerpc/pci_iov_resource_on_powernv.txt b/Documentation/powerpc/pci_iov_resource_on_powernv.txt
index b55c5cd83f8d..f5a5793e1613 100644
--- a/Documentation/powerpc/pci_iov_resource_on_powernv.txt
+++ b/Documentation/powerpc/pci_iov_resource_on_powernv.txt
@@ -1,6 +1,13 @@
+===================================================
+PCI Express I/O Virtualization Resource on Powerenv
+===================================================
+
Wei Yang <weiyang@linux.vnet.ibm.com>
+
Benjamin Herrenschmidt <benh@au1.ibm.com>
+
Bjorn Helgaas <bhelgaas@google.com>
+
26 Aug 2014
This document describes the requirement from hardware for PCI MMIO resource
@@ -10,6 +17,7 @@ Endpoints and the implementation on P8 (IODA2). The next two sections talks
about considerations on enabling SRIOV on IODA2.
1. Introduction to Partitionable Endpoints
+==========================================
A Partitionable Endpoint (PE) is a way to group the various resources
associated with a device or a set of devices to provide isolation between
@@ -35,6 +43,7 @@ is a completely separate HW entity that replicates the entire logic, so has
its own set of PEs, etc.
2. Implementation of Partitionable Endpoints on P8 (IODA2)
+==========================================================
P8 supports up to 256 Partitionable Endpoints per PHB.
@@ -149,6 +158,7 @@ P8 supports up to 256 Partitionable Endpoints per PHB.
sense, but we haven't done it yet.
3. Considerations for SR-IOV on PowerKVM
+========================================
* SR-IOV Background
@@ -224,7 +234,7 @@ P8 supports up to 256 Partitionable Endpoints per PHB.
IODA supports 256 PEs, so segmented windows contain 256 segments, so if
total_VFs is less than 256, we have the situation in Figure 1.0, where
segments [total_VFs, 255] of the M64 window may map to some MMIO range on
- other devices:
+ other devices::
0 1 total_VFs - 1
+------+------+- -+------+------+
@@ -243,7 +253,7 @@ P8 supports up to 256 Partitionable Endpoints per PHB.
Figure 1.0 Direct map VF(n) BAR space
Our current solution is to allocate 256 segments even if the VF(n) BAR
- space doesn't need that much, as shown in Figure 1.1:
+ space doesn't need that much, as shown in Figure 1.1::
0 1 total_VFs - 1 255
+------+------+- -+------+------+- -+------+------+
@@ -269,6 +279,7 @@ P8 supports up to 256 Partitionable Endpoints per PHB.
responds to segments [total_VFs, 255].
4. Implications for the Generic PCI Code
+========================================
The PCIe SR-IOV spec requires that the base of the VF(n) BAR space be
aligned to the size of an individual VF BAR.
diff --git a/Documentation/powerpc/pmu-ebb.txt b/Documentation/powerpc/pmu-ebb.txt
index 73cd163dbfb8..4f474758eb55 100644
--- a/Documentation/powerpc/pmu-ebb.txt
+++ b/Documentation/powerpc/pmu-ebb.txt
@@ -1,3 +1,4 @@
+========================
PMU Event Based Branches
========================
diff --git a/Documentation/powerpc/ptrace.txt b/Documentation/powerpc/ptrace.txt
index 99c5ce88d0fe..864d4b6dddd1 100644
--- a/Documentation/powerpc/ptrace.txt
+++ b/Documentation/powerpc/ptrace.txt
@@ -1,3 +1,7 @@
+======
+Ptrace
+======
+
GDB intends to support the following hardware debug features of BookE
processors:
@@ -12,6 +16,7 @@ that GDB doesn't need to special-case each of them. We added the
following 3 new ptrace requests.
1. PTRACE_PPC_GETHWDEBUGINFO
+============================
Query for GDB to discover the hardware debug features. The main info to
be returned here is the minimum alignment for the hardware watchpoints.
@@ -22,9 +27,9 @@ adding special cases to GDB based on what it sees in AUXV.
Since we're at it, we added other useful info that the kernel can return to
GDB: this query will return the number of hardware breakpoints, hardware
watchpoints and whether it supports a range of addresses and a condition.
-The query will fill the following structure provided by the requesting process:
+The query will fill the following structure provided by the requesting process::
-struct ppc_debug_info {
+ struct ppc_debug_info {
unit32_t version;
unit32_t num_instruction_bps;
unit32_t num_data_bps;
@@ -32,46 +37,46 @@ struct ppc_debug_info {
unit32_t data_bp_alignment;
unit32_t sizeof_condition; /* size of the DVC register */
uint64_t features; /* bitmask of the individual flags */
-};
+ };
-features will have bits indicating whether there is support for:
+features will have bits indicating whether there is support for::
-#define PPC_DEBUG_FEATURE_INSN_BP_RANGE 0x1
-#define PPC_DEBUG_FEATURE_INSN_BP_MASK 0x2
-#define PPC_DEBUG_FEATURE_DATA_BP_RANGE 0x4
-#define PPC_DEBUG_FEATURE_DATA_BP_MASK 0x8
-#define PPC_DEBUG_FEATURE_DATA_BP_DAWR 0x10
+ #define PPC_DEBUG_FEATURE_INSN_BP_RANGE 0x1
+ #define PPC_DEBUG_FEATURE_INSN_BP_MASK 0x2
+ #define PPC_DEBUG_FEATURE_DATA_BP_RANGE 0x4
+ #define PPC_DEBUG_FEATURE_DATA_BP_MASK 0x8
+ #define PPC_DEBUG_FEATURE_DATA_BP_DAWR 0x10
2. PTRACE_SETHWDEBUG
-Sets a hardware breakpoint or watchpoint, according to the provided structure:
+Sets a hardware breakpoint or watchpoint, according to the provided structure::
-struct ppc_hw_breakpoint {
+ struct ppc_hw_breakpoint {
uint32_t version;
-#define PPC_BREAKPOINT_TRIGGER_EXECUTE 0x1
-#define PPC_BREAKPOINT_TRIGGER_READ 0x2
-#define PPC_BREAKPOINT_TRIGGER_WRITE 0x4
+ #define PPC_BREAKPOINT_TRIGGER_EXECUTE 0x1
+ #define PPC_BREAKPOINT_TRIGGER_READ 0x2
+ #define PPC_BREAKPOINT_TRIGGER_WRITE 0x4
uint32_t trigger_type; /* only some combinations allowed */
-#define PPC_BREAKPOINT_MODE_EXACT 0x0
-#define PPC_BREAKPOINT_MODE_RANGE_INCLUSIVE 0x1
-#define PPC_BREAKPOINT_MODE_RANGE_EXCLUSIVE 0x2
-#define PPC_BREAKPOINT_MODE_MASK 0x3
+ #define PPC_BREAKPOINT_MODE_EXACT 0x0
+ #define PPC_BREAKPOINT_MODE_RANGE_INCLUSIVE 0x1
+ #define PPC_BREAKPOINT_MODE_RANGE_EXCLUSIVE 0x2
+ #define PPC_BREAKPOINT_MODE_MASK 0x3
uint32_t addr_mode; /* address match mode */
-#define PPC_BREAKPOINT_CONDITION_MODE 0x3
-#define PPC_BREAKPOINT_CONDITION_NONE 0x0
-#define PPC_BREAKPOINT_CONDITION_AND 0x1
-#define PPC_BREAKPOINT_CONDITION_EXACT 0x1 /* different name for the same thing as above */
-#define PPC_BREAKPOINT_CONDITION_OR 0x2
-#define PPC_BREAKPOINT_CONDITION_AND_OR 0x3
-#define PPC_BREAKPOINT_CONDITION_BE_ALL 0x00ff0000 /* byte enable bits */
-#define PPC_BREAKPOINT_CONDITION_BE(n) (1<<((n)+16))
+ #define PPC_BREAKPOINT_CONDITION_MODE 0x3
+ #define PPC_BREAKPOINT_CONDITION_NONE 0x0
+ #define PPC_BREAKPOINT_CONDITION_AND 0x1
+ #define PPC_BREAKPOINT_CONDITION_EXACT 0x1 /* different name for the same thing as above */
+ #define PPC_BREAKPOINT_CONDITION_OR 0x2
+ #define PPC_BREAKPOINT_CONDITION_AND_OR 0x3
+ #define PPC_BREAKPOINT_CONDITION_BE_ALL 0x00ff0000 /* byte enable bits */
+ #define PPC_BREAKPOINT_CONDITION_BE(n) (1<<((n)+16))
uint32_t condition_mode; /* break/watchpoint condition flags */
uint64_t addr;
uint64_t addr2;
uint64_t condition_value;
-};
+ };
A request specifies one event, not necessarily just one register to be set.
For instance, if the request is for a watchpoint with a condition, both the
@@ -88,61 +93,61 @@ can't be allocated on the registers.
Some examples of using the structure to:
-- set a breakpoint in the first breakpoint register
-
- p.version = PPC_DEBUG_CURRENT_VERSION;
- p.trigger_type = PPC_BREAKPOINT_TRIGGER_EXECUTE;
- p.addr_mode = PPC_BREAKPOINT_MODE_EXACT;
- p.condition_mode = PPC_BREAKPOINT_CONDITION_NONE;
- p.addr = (uint64_t) address;
- p.addr2 = 0;
- p.condition_value = 0;
-
-- set a watchpoint which triggers on reads in the second watchpoint register
-
- p.version = PPC_DEBUG_CURRENT_VERSION;
- p.trigger_type = PPC_BREAKPOINT_TRIGGER_READ;
- p.addr_mode = PPC_BREAKPOINT_MODE_EXACT;
- p.condition_mode = PPC_BREAKPOINT_CONDITION_NONE;
- p.addr = (uint64_t) address;
- p.addr2 = 0;
- p.condition_value = 0;
-
-- set a watchpoint which triggers only with a specific value
-
- p.version = PPC_DEBUG_CURRENT_VERSION;
- p.trigger_type = PPC_BREAKPOINT_TRIGGER_READ;
- p.addr_mode = PPC_BREAKPOINT_MODE_EXACT;
- p.condition_mode = PPC_BREAKPOINT_CONDITION_AND | PPC_BREAKPOINT_CONDITION_BE_ALL;
- p.addr = (uint64_t) address;
- p.addr2 = 0;
- p.condition_value = (uint64_t) condition;
-
-- set a ranged hardware breakpoint
-
- p.version = PPC_DEBUG_CURRENT_VERSION;
- p.trigger_type = PPC_BREAKPOINT_TRIGGER_EXECUTE;
- p.addr_mode = PPC_BREAKPOINT_MODE_RANGE_INCLUSIVE;
- p.condition_mode = PPC_BREAKPOINT_CONDITION_NONE;
- p.addr = (uint64_t) begin_range;
- p.addr2 = (uint64_t) end_range;
- p.condition_value = 0;
-
-- set a watchpoint in server processors (BookS)
-
- p.version = 1;
- p.trigger_type = PPC_BREAKPOINT_TRIGGER_RW;
- p.addr_mode = PPC_BREAKPOINT_MODE_RANGE_INCLUSIVE;
- or
- p.addr_mode = PPC_BREAKPOINT_MODE_EXACT;
-
- p.condition_mode = PPC_BREAKPOINT_CONDITION_NONE;
- p.addr = (uint64_t) begin_range;
- /* For PPC_BREAKPOINT_MODE_RANGE_INCLUSIVE addr2 needs to be specified, where
- * addr2 - addr <= 8 Bytes.
- */
- p.addr2 = (uint64_t) end_range;
- p.condition_value = 0;
+- set a breakpoint in the first breakpoint register::
+
+ p.version = PPC_DEBUG_CURRENT_VERSION;
+ p.trigger_type = PPC_BREAKPOINT_TRIGGER_EXECUTE;
+ p.addr_mode = PPC_BREAKPOINT_MODE_EXACT;
+ p.condition_mode = PPC_BREAKPOINT_CONDITION_NONE;
+ p.addr = (uint64_t) address;
+ p.addr2 = 0;
+ p.condition_value = 0;
+
+- set a watchpoint which triggers on reads in the second watchpoint register::
+
+ p.version = PPC_DEBUG_CURRENT_VERSION;
+ p.trigger_type = PPC_BREAKPOINT_TRIGGER_READ;
+ p.addr_mode = PPC_BREAKPOINT_MODE_EXACT;
+ p.condition_mode = PPC_BREAKPOINT_CONDITION_NONE;
+ p.addr = (uint64_t) address;
+ p.addr2 = 0;
+ p.condition_value = 0;
+
+- set a watchpoint which triggers only with a specific value::
+
+ p.version = PPC_DEBUG_CURRENT_VERSION;
+ p.trigger_type = PPC_BREAKPOINT_TRIGGER_READ;
+ p.addr_mode = PPC_BREAKPOINT_MODE_EXACT;
+ p.condition_mode = PPC_BREAKPOINT_CONDITION_AND | PPC_BREAKPOINT_CONDITION_BE_ALL;
+ p.addr = (uint64_t) address;
+ p.addr2 = 0;
+ p.condition_value = (uint64_t) condition;
+
+- set a ranged hardware breakpoint::
+
+ p.version = PPC_DEBUG_CURRENT_VERSION;
+ p.trigger_type = PPC_BREAKPOINT_TRIGGER_EXECUTE;
+ p.addr_mode = PPC_BREAKPOINT_MODE_RANGE_INCLUSIVE;
+ p.condition_mode = PPC_BREAKPOINT_CONDITION_NONE;
+ p.addr = (uint64_t) begin_range;
+ p.addr2 = (uint64_t) end_range;
+ p.condition_value = 0;
+
+- set a watchpoint in server processors (BookS)::
+
+ p.version = 1;
+ p.trigger_type = PPC_BREAKPOINT_TRIGGER_RW;
+ p.addr_mode = PPC_BREAKPOINT_MODE_RANGE_INCLUSIVE;
+ or
+ p.addr_mode = PPC_BREAKPOINT_MODE_EXACT;
+
+ p.condition_mode = PPC_BREAKPOINT_CONDITION_NONE;
+ p.addr = (uint64_t) begin_range;
+ /* For PPC_BREAKPOINT_MODE_RANGE_INCLUSIVE addr2 needs to be specified, where
+ * addr2 - addr <= 8 Bytes.
+ */
+ p.addr2 = (uint64_t) end_range;
+ p.condition_value = 0;
3. PTRACE_DELHWDEBUG
diff --git a/Documentation/powerpc/qe_firmware.txt b/Documentation/powerpc/qe_firmware.txt
index e7ac24aec4ff..42f5103140c9 100644
--- a/Documentation/powerpc/qe_firmware.txt
+++ b/Documentation/powerpc/qe_firmware.txt
@@ -1,23 +1,23 @@
- Freescale QUICC Engine Firmware Uploading
- -----------------------------------------
+=========================================
+Freescale QUICC Engine Firmware Uploading
+=========================================
(c) 2007 Timur Tabi <timur at freescale.com>,
Freescale Semiconductor
-Table of Contents
-=================
+.. Table of Contents
- I - Software License for Firmware
+ I - Software License for Firmware
- II - Microcode Availability
+ II - Microcode Availability
- III - Description and Terminology
+ III - Description and Terminology
- IV - Microcode Programming Details
+ IV - Microcode Programming Details
- V - Firmware Structure Layout
+ V - Firmware Structure Layout
- VI - Sample Code for Creating Firmware Files
+ VI - Sample Code for Creating Firmware Files
Revision Information
====================
@@ -39,7 +39,7 @@ http://opensource.freescale.com. For other firmware files, please contact
your Freescale representative or your operating system vendor.
III - Description and Terminology
-================================
+=================================
In this document, the term 'microcode' refers to the sequence of 32-bit
integers that compose the actual QE microcode.
@@ -89,7 +89,7 @@ being fixed in the RAM package utilizing they should be activated. This data
structure signals the microcode which of these virtual traps is active.
This structure contains 6 words that the application should copy to some
-specific been defined. This table describes the structure.
+specific been defined. This table describes the structure::
---------------------------------------------------------------
| Offset in | | Destination Offset | Size of |
@@ -119,7 +119,7 @@ Extended Modes
This is a double word bit array (64 bits) that defines special functionality
which has an impact on the software drivers. Each bit has its own impact
and has special instructions for the s/w associated with it. This structure is
-described in this table:
+described in this table::
-----------------------------------------------------------------------
| Bit # | Name | Description |
@@ -220,7 +220,8 @@ The 'model' field is a 16-bit number that matches the actual SOC. The
'major' and 'minor' fields are the major and minor revision numbers,
respectively, of the SOC.
-For example, to match the 8323, revision 1.0:
+For example, to match the 8323, revision 1.0::
+
soc.model = 8323
soc.major = 1
soc.minor = 0
@@ -273,10 +274,10 @@ library and available to any driver that calles qe_get_firmware_info().
'reserved'.
After the last microcode is a 32-bit CRC. It can be calculated using
-this algorithm:
+this algorithm::
-u32 crc32(const u8 *p, unsigned int len)
-{
+ u32 crc32(const u8 *p, unsigned int len)
+ {
unsigned int i;
u32 crc = 0;
@@ -286,7 +287,7 @@ u32 crc32(const u8 *p, unsigned int len)
crc = (crc >> 1) ^ ((crc & 1) ? 0xedb88320 : 0);
}
return crc;
-}
+ }
VI - Sample Code for Creating Firmware Files
============================================
diff --git a/Documentation/powerpc/syscall64-abi.txt b/Documentation/powerpc/syscall64-abi.txt
index fa716a0d88bd..e49f69f941b9 100644
--- a/Documentation/powerpc/syscall64-abi.txt
+++ b/Documentation/powerpc/syscall64-abi.txt
@@ -5,12 +5,12 @@ Power Architecture 64-bit Linux system call ABI
syscall
=======
-syscall calling sequence[*] matches the Power Architecture 64-bit ELF ABI
+syscall calling sequence\ [1]_ matches the Power Architecture 64-bit ELF ABI
specification C function calling sequence, including register preservation
rules, with the following differences.
-[*] Some syscalls (typically low-level management functions) may have
- different calling sequences (e.g., rt_sigreturn).
+.. [1] Some syscalls (typically low-level management functions) may have
+ different calling sequences (e.g., rt_sigreturn).
Parameters and return value
---------------------------
@@ -33,12 +33,14 @@ Register preservation rules
Register preservation rules match the ELF ABI calling sequence with the
following differences:
-r0: Volatile. (System call number.)
-r3: Volatile. (Parameter 1, and return value.)
-r4-r8: Volatile. (Parameters 2-6.)
-cr0: Volatile (cr0.SO is the return error condition)
-cr1, cr5-7: Nonvolatile.
-lr: Nonvolatile.
+=========== ============= ========================================
+r0 Volatile (System call number.)
+r3 Volatile (Parameter 1, and return value.)
+r4-r8 Volatile (Parameters 2-6.)
+cr0 Volatile (cr0.SO is the return error condition)
+cr1, cr5-7 Nonvolatile
+lr Nonvolatile
+=========== ============= ========================================
All floating point and vector data registers as well as control and status
registers are nonvolatile.
@@ -90,9 +92,12 @@ The vsyscall may or may not use the caller's stack frame save areas.
Register preservation rules
---------------------------
-r0: Volatile.
-cr1, cr5-7: Volatile.
-lr: Volatile.
+
+=========== ========
+r0 Volatile
+cr1, cr5-7 Volatile
+lr Volatile
+=========== ========
Invocation
----------
diff --git a/Documentation/powerpc/transactional_memory.txt b/Documentation/powerpc/transactional_memory.txt
index 52c023e14f26..09955103acb4 100644
--- a/Documentation/powerpc/transactional_memory.txt
+++ b/Documentation/powerpc/transactional_memory.txt
@@ -1,3 +1,4 @@
+============================
Transactional Memory support
============================
@@ -17,29 +18,29 @@ instructions are presented to delimit transactions; transactions are
guaranteed to either complete atomically or roll back and undo any partial
changes.
-A simple transaction looks like this:
+A simple transaction looks like this::
-begin_move_money:
- tbegin
- beq abort_handler
+ begin_move_money:
+ tbegin
+ beq abort_handler
- ld r4, SAVINGS_ACCT(r3)
- ld r5, CURRENT_ACCT(r3)
- subi r5, r5, 1
- addi r4, r4, 1
- std r4, SAVINGS_ACCT(r3)
- std r5, CURRENT_ACCT(r3)
+ ld r4, SAVINGS_ACCT(r3)
+ ld r5, CURRENT_ACCT(r3)
+ subi r5, r5, 1
+ addi r4, r4, 1
+ std r4, SAVINGS_ACCT(r3)
+ std r5, CURRENT_ACCT(r3)
- tend
+ tend
- b continue
+ b continue
-abort_handler:
- ... test for odd failures ...
+ abort_handler:
+ ... test for odd failures ...
- /* Retry the transaction if it failed because it conflicted with
- * someone else: */
- b begin_move_money
+ /* Retry the transaction if it failed because it conflicted with
+ * someone else: */
+ b begin_move_money
The 'tbegin' instruction denotes the start point, and 'tend' the end point.
@@ -123,7 +124,7 @@ Transaction-aware signal handlers can read the transactional register state
from the second ucontext. This will be necessary for crash handlers to
determine, for example, the address of the instruction causing the SIGSEGV.
-Example signal handler:
+Example signal handler::
void crash_handler(int sig, siginfo_t *si, void *uc)
{
@@ -133,9 +134,9 @@ Example signal handler:
if (ucp_link) {
u64 msr = ucp->uc_mcontext.regs->msr;
/* May have transactional ucontext! */
-#ifndef __powerpc64__
+ #ifndef __powerpc64__
msr |= ((u64)transactional_ucp->uc_mcontext.regs->msr) << 32;
-#endif
+ #endif
if (MSR_TM_ACTIVE(msr)) {
/* Yes, we crashed during a transaction. Oops. */
fprintf(stderr, "Transaction to be restarted at 0x%llx, but "
@@ -176,6 +177,7 @@ Failure cause codes used by kernel
These are defined in <asm/reg.h>, and distinguish different reasons why the
kernel aborted a transaction:
+ ====================== ================================
TM_CAUSE_RESCHED Thread was rescheduled.
TM_CAUSE_TLBI Software TLB invalid.
TM_CAUSE_FAC_UNAV FP/VEC/VSX unavailable trap.
@@ -184,6 +186,7 @@ kernel aborted a transaction:
TM_CAUSE_MISC Currently unused.
TM_CAUSE_ALIGNMENT Alignment fault.
TM_CAUSE_EMULATE Emulation that touched memory.
+ ====================== ================================
These can be checked by the user program's abort handler as TEXASR[0:7]. If
bit 7 is set, it indicates that the error is consider persistent. For example
@@ -203,7 +206,7 @@ POWER9
======
TM on POWER9 has issues with storing the complete register state. This
-is described in this commit:
+is described in this commit::
commit 4bb3c7a0208fc13ca70598efd109901a7cd45ae7
Author: Paul Mackerras <paulus@ozlabs.org>
--
2.20.1
^ permalink raw reply related [flat|nested] 81+ messages in thread* [PATCH 27/57] docs: pps/pps.txt convert it to ReST and move to API book
2019-04-16 2:55 [PATCH 00/57] Convert files to ReST Mauro Carvalho Chehab
` (19 preceding siblings ...)
2019-04-16 2:55 ` [PATCH 26/57] docs: powerpc: convert docs to ReST Mauro Carvalho Chehab
@ 2019-04-16 2:55 ` Mauro Carvalho Chehab
2019-04-16 2:55 ` [PATCH 28/57] docs: ptp.txt: convert to ReST and move to driver-api Mauro Carvalho Chehab
` (31 subsequent siblings)
52 siblings, 0 replies; 81+ messages in thread
From: Mauro Carvalho Chehab @ 2019-04-16 2:55 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet
This file is already in a good shape: just its title and
adding some literal block markups is needed for it to be
part of the document.
While it has a small chapter with sysfs stuff, most of
the document is focused on driver development.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
Documentation/pps/pps.txt | 67 ++++++++++++++++++++-------------------
1 file changed, 34 insertions(+), 33 deletions(-)
diff --git a/Documentation/pps/pps.txt b/Documentation/pps/pps.txt
index 99f5d8c4c652..262151a6dad5 100644
--- a/Documentation/pps/pps.txt
+++ b/Documentation/pps/pps.txt
@@ -1,8 +1,8 @@
+======================
+PPS - Pulse Per Second
+======================
- PPS - Pulse Per Second
- ----------------------
-
-(C) Copyright 2007 Rodolfo Giometti <giometti@enneenne.com>
+Copyright (C) 2007 Rodolfo Giometti <giometti@enneenne.com>
This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
@@ -88,7 +88,7 @@ Coding example
--------------
To register a PPS source into the kernel you should define a struct
-pps_source_info as follows:
+pps_source_info as follows::
static struct pps_source_info pps_ktimer_info = {
.name = "ktimer",
@@ -101,12 +101,12 @@ pps_source_info as follows:
};
and then calling the function pps_register_source() in your
-initialization routine as follows:
+initialization routine as follows::
source = pps_register_source(&pps_ktimer_info,
PPS_CAPTUREASSERT | PPS_OFFSETASSERT);
-The pps_register_source() prototype is:
+The pps_register_source() prototype is::
int pps_register_source(struct pps_source_info *info, int default_params)
@@ -118,7 +118,7 @@ pps_source_info which describe the capabilities of the driver).
Once you have registered a new PPS source into the system you can
signal an assert event (for example in the interrupt handler routine)
-just using:
+just using::
pps_event(source, &ts, PPS_CAPTUREASSERT, ptr)
@@ -134,13 +134,13 @@ Please see the file drivers/pps/clients/pps-ktimer.c for example code.
SYSFS support
-------------
-If the SYSFS filesystem is enabled in the kernel it provides a new class:
+If the SYSFS filesystem is enabled in the kernel it provides a new class::
$ ls /sys/class/pps/
pps0/ pps1/ pps2/
Every directory is the ID of a PPS sources defined in the system and
-inside you find several files:
+inside you find several files::
$ ls -F /sys/class/pps/pps0/
assert dev mode path subsystem@
@@ -148,7 +148,7 @@ inside you find several files:
Inside each "assert" and "clear" file you can find the timestamp and a
-sequence number:
+sequence number::
$ cat /sys/class/pps/pps0/assert
1170026870.983207967#8
@@ -175,11 +175,11 @@ and the userland tools available in your distribution's pps-tools package,
http://linuxpps.org , or https://github.com/redlab-i/pps-tools.
Once you have enabled the compilation of pps-ktimer just modprobe it (if
-not statically compiled):
+not statically compiled)::
# modprobe pps-ktimer
-and the run ppstest as follow:
+and the run ppstest as follow::
$ ./ppstest /dev/pps1
trying PPS source "/dev/pps1"
@@ -204,26 +204,27 @@ nor affordable. The cheap way is to load a PPS generator on one of the
computers (master) and PPS clients on others (slaves), and use very simple
cables to deliver signals using parallel ports, for example.
-Parallel port cable pinout:
-pin name master slave
-1 STROBE *------ *
-2 D0 * | *
-3 D1 * | *
-4 D2 * | *
-5 D3 * | *
-6 D4 * | *
-7 D5 * | *
-8 D6 * | *
-9 D7 * | *
-10 ACK * ------*
-11 BUSY * *
-12 PE * *
-13 SEL * *
-14 AUTOFD * *
-15 ERROR * *
-16 INIT * *
-17 SELIN * *
-18-25 GND *-----------*
+Parallel port cable pinout::
+
+ pin name master slave
+ 1 STROBE *------ *
+ 2 D0 * | *
+ 3 D1 * | *
+ 4 D2 * | *
+ 5 D3 * | *
+ 6 D4 * | *
+ 7 D5 * | *
+ 8 D6 * | *
+ 9 D7 * | *
+ 10 ACK * ------*
+ 11 BUSY * *
+ 12 PE * *
+ 13 SEL * *
+ 14 AUTOFD * *
+ 15 ERROR * *
+ 16 INIT * *
+ 17 SELIN * *
+ 18-25 GND *-----------*
Please note that parallel port interrupt occurs only on high->low transition,
so it is used for PPS assert edge. PPS clear edge can be determined only
--
2.20.1
^ permalink raw reply related [flat|nested] 81+ messages in thread* [PATCH 28/57] docs: ptp.txt: convert to ReST and move to driver-api
2019-04-16 2:55 [PATCH 00/57] Convert files to ReST Mauro Carvalho Chehab
` (20 preceding siblings ...)
2019-04-16 2:55 ` [PATCH 27/57] docs: pps/pps.txt convert it to ReST and move to API book Mauro Carvalho Chehab
@ 2019-04-16 2:55 ` Mauro Carvalho Chehab
2019-04-16 2:55 ` [PATCH 29/57] docs: riscv: convert it to ReST format Mauro Carvalho Chehab
` (30 subsequent siblings)
52 siblings, 0 replies; 81+ messages in thread
From: Mauro Carvalho Chehab @ 2019-04-16 2:55 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet
The conversion is trivial: just adjust title markups.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
Documentation/ptp/ptp.txt | 26 +++++++++++++++++---------
1 file changed, 17 insertions(+), 9 deletions(-)
diff --git a/Documentation/ptp/ptp.txt b/Documentation/ptp/ptp.txt
index 11e904ee073f..65c84a72e9fc 100644
--- a/Documentation/ptp/ptp.txt
+++ b/Documentation/ptp/ptp.txt
@@ -1,5 +1,6 @@
-
-* PTP hardware clock infrastructure for Linux
+===========================================
+PTP hardware clock infrastructure for Linux
+===========================================
This patch set introduces support for IEEE 1588 PTP clocks in
Linux. Together with the SO_TIMESTAMPING socket options, this
@@ -22,7 +23,8 @@
- Period output signals configurable from user space
- Synchronization of the Linux system time via the PPS subsystem
-** PTP hardware clock kernel API
+PTP hardware clock kernel API
+=============================
A PTP clock driver registers itself with the class driver. The
class driver handles all of the dealings with user space. The
@@ -36,7 +38,8 @@
development, it can be useful to have more than one clock in a
single system, in order to allow performance comparisons.
-** PTP hardware clock user space API
+PTP hardware clock user space API
+=================================
The class driver also creates a character device for each
registered clock. User space can use an open file descriptor from
@@ -49,7 +52,8 @@
ancillary clock features. User space can receive time stamped
events via blocking read() and poll().
-** Writing clock drivers
+Writing clock drivers
+=====================
Clock drivers include include/linux/ptp_clock_kernel.h and register
themselves by presenting a 'struct ptp_clock_info' to the
@@ -66,14 +70,17 @@
class driver, since the lock may also be needed by the clock
driver's interrupt service routine.
-** Supported hardware
+Supported hardware
+==================
+
+ * Freescale eTSEC gianfar
- + Freescale eTSEC gianfar
- 2 Time stamp external triggers, programmable polarity (opt. interrupt)
- 2 Alarm registers (optional interrupt)
- 3 Periodic signals (optional interrupt)
- + National DP83640
+ * National DP83640
+
- 6 GPIOs programmable as inputs or outputs
- 6 GPIOs with dedicated functions (LED/JTAG/clock) can also be
used as general inputs or outputs
@@ -81,6 +88,7 @@
- GPIO outputs can produce periodic signals
- 1 interrupt pin
- + Intel IXP465
+ * Intel IXP465
+
- Auxiliary Slave/Master Mode Snapshot (optional interrupt)
- Target Time (optional interrupt)
--
2.20.1
^ permalink raw reply related [flat|nested] 81+ messages in thread* [PATCH 29/57] docs: riscv: convert it to ReST format
2019-04-16 2:55 [PATCH 00/57] Convert files to ReST Mauro Carvalho Chehab
` (21 preceding siblings ...)
2019-04-16 2:55 ` [PATCH 28/57] docs: ptp.txt: convert to ReST and move to driver-api Mauro Carvalho Chehab
@ 2019-04-16 2:55 ` Mauro Carvalho Chehab
2019-04-16 2:55 ` [PATCH 30/57] docs: s390: Debugging390.txt: convert table to ascii artwork Mauro Carvalho Chehab
` (29 subsequent siblings)
52 siblings, 0 replies; 81+ messages in thread
From: Mauro Carvalho Chehab @ 2019-04-16 2:55 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Palmer Dabbelt, Albert Ou, linux-riscv
The conversion here is trivial:
- Adjust the document title's markup
- Do some whitespace alignment;
- mark literal blocks;
- Use ReST way to markup indented lists.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
Documentation/riscv/pmu.txt | 98 ++++++++++++++++++++-----------------
1 file changed, 52 insertions(+), 46 deletions(-)
diff --git a/Documentation/riscv/pmu.txt b/Documentation/riscv/pmu.txt
index b29f03a6d82f..acb216b99c26 100644
--- a/Documentation/riscv/pmu.txt
+++ b/Documentation/riscv/pmu.txt
@@ -1,5 +1,7 @@
+===================================
Supporting PMUs on RISC-V platforms
-==========================================
+===================================
+
Alan Kao <alankao@andestech.com>, Mar 2018
Introduction
@@ -77,13 +79,13 @@ Note that some features can be done in this stage as well:
(2) privilege level setting (user space only, kernel space only, both);
(3) destructor setting. Normally it is sufficient to apply *riscv_destroy_event*;
(4) tweaks for non-sampling events, which will be utilized by functions such as
-*perf_adjust_period*, usually something like the follows:
+ *perf_adjust_period*, usually something like the follows::
-if (!is_sampling_event(event)) {
- hwc->sample_period = x86_pmu.max_period;
- hwc->last_period = hwc->sample_period;
- local64_set(&hwc->period_left, hwc->sample_period);
-}
+ if (!is_sampling_event(event)) {
+ hwc->sample_period = x86_pmu.max_period;
+ hwc->last_period = hwc->sample_period;
+ local64_set(&hwc->period_left, hwc->sample_period);
+ }
In the case of *riscv_base_pmu*, only (3) is provided for now.
@@ -94,10 +96,10 @@ In the case of *riscv_base_pmu*, only (3) is provided for now.
3.1. Interrupt Initialization
This often occurs at the beginning of the *event_init* method. In common
-practice, this should be a code segment like
+practice, this should be a code segment like::
-int x86_reserve_hardware(void)
-{
+ int x86_reserve_hardware(void)
+ {
int err = 0;
if (!atomic_inc_not_zero(&pmc_refcount)) {
@@ -114,7 +116,7 @@ int x86_reserve_hardware(void)
}
return err;
-}
+ }
And the magic is in *reserve_pmc_hardware*, which usually does atomic
operations to make implemented IRQ accessible from some global function pointer.
@@ -128,28 +130,28 @@ which will be introduced in the next section.)
3.2. IRQ Structure
-Basically, a IRQ runs the following pseudo code:
+Basically, a IRQ runs the following pseudo code::
-for each hardware counter that triggered this overflow
+ for each hardware counter that triggered this overflow
- get the event of this counter
+ get the event of this counter
- // following two steps are defined as *read()*,
- // check the section Reading/Writing Counters for details.
- count the delta value since previous interrupt
- update the event->count (# event occurs) by adding delta, and
- event->hw.period_left by subtracting delta
+ // following two steps are defined as *read()*,
+ // check the section Reading/Writing Counters for details.
+ count the delta value since previous interrupt
+ update the event->count (# event occurs) by adding delta, and
+ event->hw.period_left by subtracting delta
- if the event overflows
- sample data
- set the counter appropriately for the next overflow
+ if the event overflows
+ sample data
+ set the counter appropriately for the next overflow
- if the event overflows again
- too frequently, throttle this event
- fi
- fi
+ if the event overflows again
+ too frequently, throttle this event
+ fi
+ fi
-end for
+ end for
However as of this writing, none of the RISC-V implementations have designed an
interrupt for perf, so the details are to be completed in the future.
@@ -195,23 +197,26 @@ A normal flow of these state transitions are as follows:
At this stage, a general event is bound to a physical counter, if any.
The state changes to PERF_HES_STOPPED and PERF_HES_UPTODATE, because it is now
stopped, and the (software) event count does not need updating.
-** *start* is then called, and the counter is enabled.
- With flag PERF_EF_RELOAD, it writes an appropriate value to the counter (check
- previous section for detail).
- Nothing is written if the flag does not contain PERF_EF_RELOAD.
- The state now is reset to none, because it is neither stopped nor updated
- (the counting already started)
+
+ - *start* is then called, and the counter is enabled.
+ With flag PERF_EF_RELOAD, it writes an appropriate value to the counter (check
+ previous section for detail).
+ Nothing is written if the flag does not contain PERF_EF_RELOAD.
+ The state now is reset to none, because it is neither stopped nor updated
+ (the counting already started)
+
* When being context-switched out, *del* is called. It then checks out all the
events in the PMU and calls *stop* to update their counts.
-** *stop* is called by *del*
- and the perf core with flag PERF_EF_UPDATE, and it often shares the same
- subroutine as *read* with the same logic.
- The state changes to PERF_HES_STOPPED and PERF_HES_UPTODATE, again.
-** Life cycle of these two pairs: *add* and *del* are called repeatedly as
- tasks switch in-and-out; *start* and *stop* is also called when the perf core
- needs a quick stop-and-start, for instance, when the interrupt period is being
- adjusted.
+ - *stop* is called by *del*
+ and the perf core with flag PERF_EF_UPDATE, and it often shares the same
+ subroutine as *read* with the same logic.
+ The state changes to PERF_HES_STOPPED and PERF_HES_UPTODATE, again.
+
+ - Life cycle of these two pairs: *add* and *del* are called repeatedly as
+ tasks switch in-and-out; *start* and *stop* is also called when the perf core
+ needs a quick stop-and-start, for instance, when the interrupt period is being
+ adjusted.
Current implementation is sufficient for now and can be easily extended to
features in the future.
@@ -225,25 +230,26 @@ A. Related Structures
Both structures are designed to be read-only.
*struct pmu* defines some function pointer interfaces, and most of them take
-*struct perf_event* as a main argument, dealing with perf events according to
-perf's internal state machine (check kernel/events/core.c for details).
+ *struct perf_event* as a main argument, dealing with perf events according to
+ perf's internal state machine (check kernel/events/core.c for details).
*struct riscv_pmu* defines PMU-specific parameters. The naming follows the
-convention of all other architectures.
+ convention of all other architectures.
* struct perf_event: include/linux/perf_event.h
* struct hw_perf_event
The generic structure that represents perf events, and the hardware-related
-details.
+ details.
* struct riscv_hw_events: arch/riscv/include/asm/perf_event.h
The structure that holds the status of events, has two fixed members:
-the number of events and the array of the events.
+ the number of events and the array of the events.
References
----------
[1] https://github.com/riscv/riscv-linux/pull/124
+
[2] https://groups.google.com/a/groups.riscv.org/forum/#!topic/sw-dev/f19TmCNP6yA
--
2.20.1
^ permalink raw reply related [flat|nested] 81+ messages in thread* [PATCH 30/57] docs: s390: Debugging390.txt: convert table to ascii artwork
2019-04-16 2:55 [PATCH 00/57] Convert files to ReST Mauro Carvalho Chehab
` (22 preceding siblings ...)
2019-04-16 2:55 ` [PATCH 29/57] docs: riscv: convert it to ReST format Mauro Carvalho Chehab
@ 2019-04-16 2:55 ` Mauro Carvalho Chehab
2019-04-16 2:55 ` [PATCH 32/57] s390: include/asm/debug.h add kerneldoc markups Mauro Carvalho Chehab
` (28 subsequent siblings)
52 siblings, 0 replies; 81+ messages in thread
From: Mauro Carvalho Chehab @ 2019-04-16 2:55 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Martin Schwidefsky, Heiko Carstens, linux-s390
The first bit/value table inside the document is very
hard to read and won't fit ReST format. Convert it to
a nice ascii artwork table with makes it easier to read
and is compatible with ReST format parser on Sphinx.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
Documentation/s390/Debugging390.txt | 210 ++++++++++++++++------------
1 file changed, 120 insertions(+), 90 deletions(-)
diff --git a/Documentation/s390/Debugging390.txt b/Documentation/s390/Debugging390.txt
index 5ae7f868a007..c35804c238ad 100644
--- a/Documentation/s390/Debugging390.txt
+++ b/Documentation/s390/Debugging390.txt
@@ -78,96 +78,126 @@ e.g. switching address translation off requires that you
have a logical=physical mapping for the address you are
currently running at.
- Bit Value
-s/390 z/Architecture
-0 0 Reserved ( must be 0 ) otherwise specification exception occurs.
-
-1 1 Program Event Recording 1 PER enabled,
- PER is used to facilitate debugging e.g. single stepping.
-
-2-4 2-4 Reserved ( must be 0 ).
-
-5 5 Dynamic address translation 1=DAT on.
-
-6 6 Input/Output interrupt Mask
-
-7 7 External interrupt Mask used primarily for interprocessor
- signalling and clock interrupts.
-
-8-11 8-11 PSW Key used for complex memory protection mechanism
- (not used under linux)
-
-12 12 1 on s/390 0 on z/Architecture
-
-13 13 Machine Check Mask 1=enable machine check interrupts
-
-14 14 Wait State. Set this to 1 to stop the processor except for
- interrupts and give time to other LPARS. Used in CPU idle in
- the kernel to increase overall usage of processor resources.
-
-15 15 Problem state ( if set to 1 certain instructions are disabled )
- all linux user programs run with this bit 1
- ( useful info for debugging under VM ).
-
-16-17 16-17 Address Space Control
-
- 00 Primary Space Mode:
- The register CR1 contains the primary address-space control ele-
- ment (PASCE), which points to the primary space region/segment
- table origin.
-
- 01 Access register mode
-
- 10 Secondary Space Mode:
- The register CR7 contains the secondary address-space control
- element (SASCE), which points to the secondary space region or
- segment table origin.
-
- 11 Home Space Mode:
- The register CR13 contains the home space address-space control
- element (HASCE), which points to the home space region/segment
- table origin.
-
- See "Address Spaces on Linux for s/390 & z/Architecture" below
- for more information about address space usage in Linux.
-
-18-19 18-19 Condition codes (CC)
-
-20 20 Fixed point overflow mask if 1=FPU exceptions for this event
- occur ( normally 0 )
-
-21 21 Decimal overflow mask if 1=FPU exceptions for this event occur
- ( normally 0 )
-
-22 22 Exponent underflow mask if 1=FPU exceptions for this event occur
- ( normally 0 )
-
-23 23 Significance Mask if 1=FPU exceptions for this event occur
- ( normally 0 )
-
-24-31 24-30 Reserved Must be 0.
-
- 31 Extended Addressing Mode
- 32 Basic Addressing Mode
- Used to set addressing mode
- PSW 31 PSW 32
- 0 0 24 bit
- 0 1 31 bit
- 1 1 64 bit
-
-32 1=31 bit addressing mode 0=24 bit addressing mode (for backward
- compatibility), linux always runs with this bit set to 1
-
-33-64 Instruction address.
- 33-63 Reserved must be 0
- 64-127 Address
- In 24 bits mode bits 64-103=0 bits 104-127 Address
- In 31 bits mode bits 64-96=0 bits 97-127 Address
- Note: unlike 31 bit mode on s/390 bit 96 must be zero
- when loading the address with LPSWE otherwise a
- specification exception occurs, LPSW is fully backward
- compatible.
-
++-------------------------+-------------------------------------------------+
+| Bit | |
++--------+----------------+ Value |
+| s/390 | z/Architecture | |
++========+================+=================================================+
+| 0 | 0 | Reserved (must be 0) otherwise specification |
+| | | exception occurs. |
++--------+----------------+-------------------------------------------------+
+| 1 | 1 | Program Event Recording 1 PER enabled, |
+| | | PER is used to facilitate debugging e.g. |
+| | | single stepping. |
++--------+----------------+-------------------------------------------------+
+| 2-4 | 2-4 | Reserved (must be 0). |
++--------+----------------+-------------------------------------------------+
+| 5 | 5 | Dynamic address translation 1=DAT on. |
++--------+----------------+-------------------------------------------------+
+| 6 | 6 | Input/Output interrupt Mask |
++--------+----------------+-------------------------------------------------+
+| 7 | 7 | External interrupt Mask used primarily for |
+| | | interprocessor signalling and clock interrupts. |
++--------+----------------+-------------------------------------------------+
+| 8-11 | 8-11 | PSW Key used for complex memory protection |
+| | | mechanism (not used under linux) |
++--------+----------------+-------------------------------------------------+
+| 12 | 12 | 1 on s/390 0 on z/Architecture |
++--------+----------------+-------------------------------------------------+
+| 13 | 13 | Machine Check Mask 1=enable machine check |
+| | | interrupts |
++--------+----------------+-------------------------------------------------+
+| 14 | 14 | Wait State. Set this to 1 to stop the processor |
+| | | except for interrupts and give time to other |
+| | | LPARS. Used in CPU idle in the kernel to |
+| | | increase overall usage of processor resources. |
++--------+----------------+-------------------------------------------------+
+| 15 | 15 | Problem state (if set to 1 certain instructions |
+| | | are disabled). All linux user programs run with |
+| | | this bit 1 (useful info for debugging under VM).|
++--------+----------------+-------------------------------------------------+
+| 16-17 | 16-17 | Address Space Control |
+| | | |
+| | | 00 Primary Space Mode: |
+| | | |
+| | | The register CR1 contains the primary |
+| | | address-space control element (PASCE), which |
+| | | points to the primary space region/segment |
+| | | table origin. |
+| | | |
+| | | 01 Access register mode |
+| | | |
+| | | 10 Secondary Space Mode: |
+| | | |
+| | | The register CR7 contains the secondary |
+| | | address-space control element (SASCE), which |
+| | | points to the secondary space region or |
+| | | segment table origin. |
+| | | |
+| | | 11 Home Space Mode: |
+| | | |
+| | | The register CR13 contains the home space |
+| | | address-space control element (HASCE), which |
+| | | points to the home space region/segment |
+| | | table origin. |
+| | | |
+| | | See "Address Spaces on Linux for s/390 & |
+| | | z/Architecture" below for more information |
+| | | about address space usage in Linux. |
++--------+----------------+-------------------------------------------------+
+| 18-19 | 18-19 | Condition codes (CC) |
++--------+----------------+-------------------------------------------------+
+| 20 | 20 | Fixed point overflow mask if 1=FPU exceptions |
+| | | for this event occur (normally 0) |
++--------+----------------+-------------------------------------------------+
+| 21 | 21 | Decimal overflow mask if 1=FPU exceptions for |
+| | | this event occur (normally 0) |
++--------+----------------+-------------------------------------------------+
+| 22 | 22 | Exponent underflow mask if 1=FPU exceptions |
+| | | for this event occur (normally 0) |
++--------+----------------+-------------------------------------------------+
+| 23 | 23 | Significance Mask if 1=FPU exceptions for this |
+| | | event occur (normally 0) |
++--------+----------------+-------------------------------------------------+
+| 24-31 | 24-30 | Reserved Must be 0. |
+| +----------------+-------------------------------------------------+
+| | 31 | Extended Addressing Mode |
+| +----------------+-------------------------------------------------+
+| | 32 | Basic Addressing Mode |
+| | | |
+| | | Used to set addressing mode |
+| | | |
+| | | +---------+----------+----------+ |
+| | | | PSW 31 | PSW 32 | | |
+| | | +---------+----------+----------+ |
+| | | | 0 | 0 | 24 bit | |
+| | | +---------+----------+----------+ |
+| | | | 0 | 1 | 31 bit | |
+| | | +---------+----------+----------+ |
+| | | | 1 | 1 | 64 bit | |
+| | | +---------+----------+----------+ |
++--------+----------------+-------------------------------------------------+
+| 32 | | 1=31 bit addressing mode 0=24 bit addressing |
+| | | mode (for backward compatibility), linux |
+| | | always runs with this bit set to 1 |
++--------+----------------+-------------------------------------------------+
+| 33-64 | | Instruction address. |
+| +----------------+-------------------------------------------------+
+| | 33-63 | Reserved must be 0 |
+| +----------------+-------------------------------------------------+
+| | 64-127 | Address |
+| | | |
+| | | - In 24 bits mode bits 64-103=0 bits 104-127 |
+| | | Address |
+| | | - In 31 bits mode bits 64-96=0 bits 97-127 |
+| | | Address |
+| | | |
+| | | Note: |
+| | | unlike 31 bit mode on s/390 bit 96 must be |
+| | | zero when loading the address with LPSWE |
+| | | otherwise a specification exception occurs, |
+| | | LPSW is fully backward compatible. |
++--------+----------------+-------------------------------------------------+
Prefix Page(s)
--------------
--
2.20.1
^ permalink raw reply related [flat|nested] 81+ messages in thread* [PATCH 32/57] s390: include/asm/debug.h add kerneldoc markups
2019-04-16 2:55 [PATCH 00/57] Convert files to ReST Mauro Carvalho Chehab
` (23 preceding siblings ...)
2019-04-16 2:55 ` [PATCH 30/57] docs: s390: Debugging390.txt: convert table to ascii artwork Mauro Carvalho Chehab
@ 2019-04-16 2:55 ` Mauro Carvalho Chehab
2019-04-16 2:55 ` [PATCH 33/57] docs: serial: convert it to ReST format Mauro Carvalho Chehab
` (27 subsequent siblings)
52 siblings, 0 replies; 81+ messages in thread
From: Mauro Carvalho Chehab @ 2019-04-16 2:55 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Martin Schwidefsky, Heiko Carstens, linux-s390
Instead of keeping the documentation inside s390dbf.txt,
move them to arch/s390/include/asm/debug.h, using standard
kernel-doc markups.
Those were converted to kerneldoc using this specially made
script and manually editted:
<script>
use strict;
my $mode = "";
my $parameter = "";
my $ret = "";
my $descr = "";
sub add_var($)
{
my $ln = shift;
$ln =~ s/^\s+//;
$ln =~ s/\s+$//;
return if ($ln eq "");
$ln =~ s/^(\S+)\s+/$1\t/;
print " * \@$ln\n";
}
sub add_return($)
{
my $ln = shift;
print " *\n * Return:\n" if ($mode ne "Return Value:");
$ln =~ s/^\s+//;
$ln =~ s/\s+$//;
return if ($ln eq "");
print " * - $ln\n";
}
sub add_description($)
{
my $ln = shift;
print " *\n * \n" if ($mode ne "Description:");
$ln =~ s/^\s+//;
$ln =~ s/\s+$//;
return if ($ln eq "");
print " * $ln\n";
}
sub flush_results()
{
print " */\n\n";
}
while (<>) {
if (m/^[\-]+$/) {
flush_results();
$mode = "";
$parameter = "";
$ret = "";
$descr = "";
next;
}
if (m/(Parameter:)(.*)/) {
print " *\n" if ($mode eq "func");
add_var($2);
$mode = $1;
next;
}
if (m/(Return Value:)(.*)/) {
add_return($2);
$mode = $1;
next;
}
if (m/(Description:)(.*)/) {
add_description($2);
$mode = $1;
next;
}
if ($mode eq "Parameter:") {
add_var($_);
next;
}
if ($mode eq "Return Value:") {
add_return($_);
next;
}
if ($mode eq "Description:") {
add_description($_);
next;
}
next if (m/^\s*$/);
if (m/^\S+.*\s\*?(\S+)\s*\(/) {
if ($mode eq "") {
print "/**\n * $1()\n";
} else {
print " * $1()\n";
}
$mode="func";
}
}
flush_results();
</script>
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
Documentation/s390/s390dbf.txt | 322 +--------------------------------
arch/s390/include/asm/debug.h | 231 +++++++++++++++++++++++
2 files changed, 232 insertions(+), 321 deletions(-)
diff --git a/Documentation/s390/s390dbf.txt b/Documentation/s390/s390dbf.txt
index 549dba50fc3b..b0ca0d142ea1 100644
--- a/Documentation/s390/s390dbf.txt
+++ b/Documentation/s390/s390dbf.txt
@@ -107,327 +107,7 @@ will stay deactivated.
Kernel Interfaces:
------------------
-----------------------------------------------------------------------------
-
-::
-
- debug_info_t *debug_register(char *name, int pages, int nr_areas,
- int buf_size);
-
-Parameter:
- name:
- Name of debug log (e.g. used for debugfs entry)
- pages:
- Number of pages, which will be allocated per area
- nr_areas:
- Number of debug areas
- buf_size:
- Size of data area in each debug entry
-
-Return Value:
- Handle for generated debug area
-
- NULL if register failed
-
-Description: Allocates memory for a debug log
- Must not be called within an interrupt handler
-
-----------------------------------------------------------------------------
-
-::
-
- debug_info_t *debug_register_mode(char *name, int pages, int nr_areas,
- int buf_size, mode_t mode, uid_t uid,
- gid_t gid);
-
-Parameter:
- name:
- Name of debug log (e.g. used for debugfs entry)
- pages:
- Number of pages, which will be allocated per area
- nr_areas:
- Number of debug areas
- buf_size:
- Size of data area in each debug entry
- mode:
- File mode for debugfs files. E.g. S_IRWXUGO
- uid:
- User ID for debugfs files. Currently only 0 is
- supported.
- gid:
- Group ID for debugfs files. Currently only 0 is
- supported.
-
-Return Value:
- Handle for generated debug area
-
- NULL if register failed
-
-Description:
- Allocates memory for a debug log
- Must not be called within an interrupt handler
-
----------------------------------------------------------------------------
-
-::
-
- void debug_unregister (debug_info_t * id);
-
-Parameter:
- id:
- handle for debug log
-
-Return Value:
- none
-
-Description:
- frees memory for a debug log and removes all registered debug
- views.
-
- Must not be called within an interrupt handler
-
----------------------------------------------------------------------------
-
-::
-
- void debug_set_level (debug_info_t * id, int new_level);
-
-Parameter: id: handle for debug log
- new_level: new debug level
-
-Return Value:
- none
-
-Description:
- Sets new actual debug level if new_level is valid.
-
----------------------------------------------------------------------------
-
-::
-
- bool debug_level_enabled (debug_info_t * id, int level);
-
-Parameter:
- id:
- handle for debug log
- level:
- debug level
-
-Return Value:
- True if level is less or equal to the current debug level.
-
-Description:
- Returns true if debug events for the specified level would be
- logged. Otherwise returns false.
-
----------------------------------------------------------------------------
-
-::
-
- void debug_stop_all(void);
-
-Parameter:
- none
-
-Return Value:
- none
-
-Description:
- stops the debug feature if stopping is allowed. Currently
- used in case of a kernel oops.
-
----------------------------------------------------------------------------
-
-::
-
- debug_entry_t* debug_event (debug_info_t* id, int level, void* data,
- int length);
-
-Parameter:
- id:
- handle for debug log
- level:
- debug level
- data:
- pointer to data for debug entry
- length:
- length of data in bytes
-
-Return Value:
- Address of written debug entry
-
-Description:
- writes debug entry to active debug area (if level <= actual
- debug level)
-
----------------------------------------------------------------------------
-
-::
-
- debug_entry_t* debug_int_event (debug_info_t * id, int level,
- unsigned int data);
- debug_entry_t* debug_long_event(debug_info_t * id, int level,
- unsigned long data);
-
-Parameter:
- id:
- handle for debug log
- level:
- debug level
- data:
- integer value for debug entry
-
-Return Value:
- Address of written debug entry
-
-Description:
- writes debug entry to active debug area (if level <= actual
- debug level)
-
----------------------------------------------------------------------------
-
-::
-
- debug_entry_t* debug_text_event (debug_info_t * id, int level,
- const char* data);
-
-Parameter:
- id:
- handle for debug log
- level:
- debug level
- data:
- string for debug entry
-
-Return Value:
- Address of written debug entry
-
-Description:
- writes debug entry in ascii format to active debug area
- (if level <= actual debug level)
-
----------------------------------------------------------------------------
-
-::
-
- debug_entry_t* debug_sprintf_event (debug_info_t * id, int level,
- char* string,...);
-
-Parameter:
- id:
- handle for debug log
- level:
- debug level
- string:
- format string for debug entry
- ...:
- varargs used as in sprintf()
-
-Return Value: Address of written debug entry
-
-Description:
- writes debug entry with format string and varargs (longs) to
- active debug area (if level $<=$ actual debug level).
- floats and long long datatypes cannot be used as varargs.
-
----------------------------------------------------------------------------
-
-::
-
- debug_entry_t* debug_exception (debug_info_t* id, int level, void* data,
- int length);
-
-Parameter:
- id:
- handle for debug log
- level:
- debug level
- data:
- pointer to data for debug entry
- length:
- length of data in bytes
-
-Return Value:
- Address of written debug entry
-
-Description:
- writes debug entry to active debug area (if level <= actual
- debug level) and switches to next debug area
-
----------------------------------------------------------------------------
-
-::
- debug_entry_t* debug_int_exception (debug_info_t * id, int level,
- unsigned int data);
- debug_entry_t* debug_long_exception(debug_info_t * id, int level,
- unsigned long data);
-
-Parameter: id: handle for debug log
- level: debug level
- data: integer value for debug entry
-
-Return Value: Address of written debug entry
-
-Description: writes debug entry to active debug area (if level <= actual
- debug level) and switches to next debug area
-
----------------------------------------------------------------------------
-
-debug_entry_t* debug_text_exception (debug_info_t * id, int level,
- const char* data);
-
-Parameter: id: handle for debug log
- level: debug level
- data: string for debug entry
-
-Return Value: Address of written debug entry
-
-Description: writes debug entry in ascii format to active debug area
- (if level <= actual debug level) and switches to next debug
- area
-
----------------------------------------------------------------------------
-
-debug_entry_t* debug_sprintf_exception (debug_info_t * id, int level,
- char* string,...);
-
-Parameter: id: handle for debug log
- level: debug level
- string: format string for debug entry
- ...: varargs used as in sprintf()
-
-Return Value: Address of written debug entry
-
-Description: writes debug entry with format string and varargs (longs) to
- active debug area (if level $<=$ actual debug level) and
- switches to next debug area.
- floats and long long datatypes cannot be used as varargs.
-
----------------------------------------------------------------------------
-
-int debug_register_view (debug_info_t * id, struct debug_view *view);
-
-Parameter: id: handle for debug log
- view: pointer to debug view struct
-
-Return Value: 0 : ok
- < 0: Error
-
-Description: registers new debug view and creates debugfs dir entry
-
----------------------------------------------------------------------------
-
-int debug_unregister_view (debug_info_t * id, struct debug_view *view);
-
-Parameter: id: handle for debug log
- view: pointer to debug view struct
-
-Return Value: 0 : ok
- < 0: Error
-
-Description: unregisters debug view and removes debugfs dir entry
-
-
+.. kernel-doc:: arch/s390/include/asm/debug.h
Predefined views:
-----------------
diff --git a/arch/s390/include/asm/debug.h b/arch/s390/include/asm/debug.h
index c305d39f5016..7cc83938c659 100644
--- a/arch/s390/include/asm/debug.h
+++ b/arch/s390/include/asm/debug.h
@@ -95,25 +95,106 @@ debug_entry_t *debug_exception_common(debug_info_t *id, int level,
/* Debug Feature API: */
+/**
+ * debug_register() - allocates memory for a debug log.
+ *
+ * @name: Name of debug log (e.g. used for debugfs entry)
+ * @pages: Number of pages, which will be allocated per area
+ * @nr_areas: Number of debug areas
+ * @buf_size: Size of data area in each debug entry
+ *
+ * Return:
+ * - Handler for generated debug area
+ * - %NULL if register failed
+ *
+ * Must not be called within an interrupt handler.
+ */
debug_info_t *debug_register(const char *name, int pages, int nr_areas,
int buf_size);
+/**
+ * debug_register_mode() - allocates memory for a debug log.
+ *
+ * @name: Name of debug log (e.g. used for debugfs entry)
+ * @pages: Number of pages, which will be allocated per area
+ * @nr_areas: Number of debug areas
+ * @buf_size: Size of data area in each debug entry
+ * @mode: File mode for debugfs files. E.g. S_IRWXUGO
+ * @uid: User ID for debugfs files. Currently only 0 is supported.
+ * @gid: Group ID for debugfs files. Currently only 0 is supported.
+ *
+ * Return:
+ * - Handler for generated debug area
+ * - %NULL if register failed
+ *
+ * Must not be called within an interrupt handler
+ */
debug_info_t *debug_register_mode(const char *name, int pages, int nr_areas,
int buf_size, umode_t mode, uid_t uid,
gid_t gid);
+/**
+ * debug_unregister() - frees memory for a debug log and removes all
+ * registered debug
+ * views.
+ *
+ * @id: handle for debug log
+ *
+ * Return:
+ * none
+ *
+ * Must not be called within an interrupt handler
+ */
void debug_unregister(debug_info_t *id);
+/**
+ * debug_set_level() - Sets new actual debug level if new_level is valid.
+ *
+ * @id: handle for debug log
+ * @new_level: new debug level
+ *
+ * Return:
+ * none
+ */
void debug_set_level(debug_info_t *id, int new_level);
void debug_set_critical(void);
+
+/**
+ * debug_stop_all() - stops the debug feature if stopping is allowed.
+ *
+ * Return:
+ * - none
+ */
void debug_stop_all(void);
+/**
+ * debug_level_enabled() - Returns true if debug events for the specified
+ * level would be logged. Otherwise returns false.
+ *
+ * @id: handle for debug log
+ * @level: debug level
+ *
+ * Return:
+ * - %true if level is less or equal to the current debug level.
+ */
static inline bool debug_level_enabled(debug_info_t *id, int level)
{
return level <= id->level;
}
+/**
+ * debug_event() - writes debug entry to active debug area
+ * (if level <= actual debug level)
+ *
+ * @id: handle for debug log
+ * @level: debug level
+ * @data: pointer to data for debug entry
+ * @length: length of data in bytes
+ *
+ * Return:
+ * - Address of written debug entry
+ */
static inline debug_entry_t *debug_event(debug_info_t *id, int level,
void *data, int length)
{
@@ -122,6 +203,18 @@ static inline debug_entry_t *debug_event(debug_info_t *id, int level,
return debug_event_common(id, level, data, length);
}
+/**
+ * debug_int_event() - writes debug entry to active debug area
+ * (if level <= actual debug level)
+ *
+ * @id: handle for debug log
+ * @level: debug level
+ * @tag: integer value for debug entry
+ *
+ * Return:
+ * - Address of written debug entry
+ * - %NULL if error
+ */
static inline debug_entry_t *debug_int_event(debug_info_t *id, int level,
unsigned int tag)
{
@@ -132,6 +225,18 @@ static inline debug_entry_t *debug_int_event(debug_info_t *id, int level,
return debug_event_common(id, level, &t, sizeof(unsigned int));
}
+/**
+ * debug_long_event() - writes debug entry to active debug area
+ * (if level <= actual debug level)
+ *
+ * @id: handle for debug log
+ * @level: debug level
+ * @tag: integer value for debug entry
+ *
+ * Return:
+ * - Address of written debug entry
+ * - %NULL if error
+ */
static inline debug_entry_t *debug_long_event(debug_info_t *id, int level,
unsigned long tag)
{
@@ -142,6 +247,18 @@ static inline debug_entry_t *debug_long_event(debug_info_t *id, int level,
return debug_event_common(id, level, &t, sizeof(unsigned long));
}
+/**
+ * debug_text_event() - writes debug entry in ascii format to active
+ * debug area (if level <= actual debug level)
+ *
+ * @id: handle for debug log
+ * @level: debug level
+ * @txt: string for debug entry
+ *
+ * Return:
+ * - Address of written debug entry
+ * - %NULL if error
+ */
static inline debug_entry_t *debug_text_event(debug_info_t *id, int level,
const char *txt)
{
@@ -158,6 +275,22 @@ extern debug_entry_t *
__debug_sprintf_event(debug_info_t *id, int level, char *string, ...)
__attribute__ ((format(printf, 3, 4)));
+/**
+ * debug_sprintf_event() - writes debug entry with format string
+ * and varargs (longs) to active debug area
+ * (if level $<=$ actual debug level).
+ *
+ * @_id: handle for debug log
+ * @_level: debug level
+ * @_fmt: format string for debug entry
+ * @...: varargs used as in sprintf()
+ *
+ * Return:
+ * - Address of written debug entry
+ * - %NULL if error
+ *
+ * floats and long long datatypes cannot be used as varargs.
+ */
#define debug_sprintf_event(_id, _level, _fmt, ...) \
({ \
debug_entry_t *__ret; \
@@ -172,6 +305,20 @@ __debug_sprintf_event(debug_info_t *id, int level, char *string, ...)
__ret; \
})
+/**
+ * debug_exception() - writes debug entry to active debug area
+ * (if level <= actual debug level) and switches
+ * to next debug area
+ *
+ * @id: handle for debug log
+ * @level: debug level
+ * @data: pointer to data for debug entry
+ * @length: length of data in bytes
+ *
+ * Return:
+ * - Address of written debug entry
+ * - %NULL if error
+ */
static inline debug_entry_t *debug_exception(debug_info_t *id, int level,
void *data, int length)
{
@@ -180,6 +327,19 @@ static inline debug_entry_t *debug_exception(debug_info_t *id, int level,
return debug_exception_common(id, level, data, length);
}
+/**
+ * debug_int_exception() - writes debug entry to active debug area
+ * (if level <= actual debug level)
+ * and switches to next debug area
+ *
+ * @id: handle for debug log
+ * @level: debug level
+ * @tag: integer value for debug entry
+ *
+ * Return:
+ * - Address of written debug entry
+ * - %NULL if error
+ */
static inline debug_entry_t *debug_int_exception(debug_info_t *id, int level,
unsigned int tag)
{
@@ -190,6 +350,19 @@ static inline debug_entry_t *debug_int_exception(debug_info_t *id, int level,
return debug_exception_common(id, level, &t, sizeof(unsigned int));
}
+/**
+ * debug_long_exception() - writes debug entry to active debug area
+ * (if level <= actual debug level)
+ * and switches to next debug area
+ *
+ * @id: handle for debug log
+ * @level: debug level
+ * @tag: integer value for debug entry
+ *
+ * Return:
+ * - Address of written debug entry
+ * - %NULL if error
+ */
static inline debug_entry_t *debug_long_exception (debug_info_t *id, int level,
unsigned long tag)
{
@@ -200,6 +373,20 @@ static inline debug_entry_t *debug_long_exception (debug_info_t *id, int level,
return debug_exception_common(id, level, &t, sizeof(unsigned long));
}
+/**
+ * debug_text_exception() - writes debug entry in ascii format to active
+ * debug area (if level <= actual debug level)
+ * and switches to next debug
+ * area
+ *
+ * @id: handle for debug log
+ * @level: debug level
+ * @txt: string for debug entry
+ *
+ * Return:
+ * - Address of written debug entry
+ * - %NULL if error
+ */
static inline debug_entry_t *debug_text_exception(debug_info_t *id, int level,
const char *txt)
{
@@ -216,6 +403,24 @@ extern debug_entry_t *
__debug_sprintf_exception(debug_info_t *id, int level, char *string, ...)
__attribute__ ((format(printf, 3, 4)));
+
+/**
+ * debug_sprintf_exception() - writes debug entry with format string and
+ * varargs (longs) to active debug area
+ * (if level $<=$ actual debug level)
+ * and switches to next debug area.
+ *
+ * @_id: handle for debug log
+ * @_level: debug level
+ * @_fmt: format string for debug entry
+ * @...: varargs used as in sprintf()
+ *
+ * Return:
+ * - Address of written debug entry
+ * - %NULL if error
+ *
+ * floats and long long datatypes cannot be used as varargs.
+ */
#define debug_sprintf_exception(_id, _level, _fmt, ...) \
({ \
debug_entry_t *__ret; \
@@ -230,7 +435,33 @@ __debug_sprintf_exception(debug_info_t *id, int level, char *string, ...)
__ret; \
})
+/**
+ * debug_register_view() - registers new debug view and creates debugfs
+ * dir entry
+ *
+ * @id: handle for debug log
+ * @view: pointer to debug view struct
+ *
+ * Return:
+ * - 0 : ok
+ * - < 0: Error
+ */
int debug_register_view(debug_info_t *id, struct debug_view *view);
+
+/**
+ * debug_unregister_view()
+ *
+ * @id: handle for debug log
+ * @view: pointer to debug view struct
+ *
+ * Return:
+ * - 0 : ok
+ * - < 0: Error
+ *
+ *
+ * unregisters debug view and removes debugfs dir entry
+ */
+
int debug_unregister_view(debug_info_t *id, struct debug_view *view);
/*
--
2.20.1
^ permalink raw reply related [flat|nested] 81+ messages in thread* [PATCH 33/57] docs: serial: convert it to ReST format
2019-04-16 2:55 [PATCH 00/57] Convert files to ReST Mauro Carvalho Chehab
` (24 preceding siblings ...)
2019-04-16 2:55 ` [PATCH 32/57] s390: include/asm/debug.h add kerneldoc markups Mauro Carvalho Chehab
@ 2019-04-16 2:55 ` Mauro Carvalho Chehab
2019-04-16 2:55 ` [PATCH 34/57] docs: target: " Mauro Carvalho Chehab
` (26 subsequent siblings)
52 siblings, 0 replies; 81+ messages in thread
From: Mauro Carvalho Chehab @ 2019-04-16 2:55 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet
The converted files are focused at the Kernel internal API,
so, this is a good candidate for the kernel API set of books.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
Documentation/serial/README.cycladesZ | 5 +-
Documentation/serial/driver | 113 +++-
Documentation/serial/moxa-smartio | 750 +++++++++++++-----------
Documentation/serial/n_gsm.txt | 81 +--
Documentation/serial/rocket.txt | 144 +++--
Documentation/serial/serial-iso7816.txt | 21 +-
Documentation/serial/serial-rs485.txt | 22 +-
Documentation/serial/tty.txt | 111 ++--
8 files changed, 719 insertions(+), 528 deletions(-)
diff --git a/Documentation/serial/README.cycladesZ b/Documentation/serial/README.cycladesZ
index 024a69443cc2..532ff67e2f1c 100644
--- a/Documentation/serial/README.cycladesZ
+++ b/Documentation/serial/README.cycladesZ
@@ -1,8 +1,11 @@
+================
+Cyclades-Z notes
+================
The Cyclades-Z must have firmware loaded onto the card before it will
operate. This operation should be performed during system startup,
The firmware, loader program and the latest device driver code are
available from Cyclades at
+
ftp://ftp.cyclades.com/pub/cyclades/cyclades-z/linux/
-
diff --git a/Documentation/serial/driver b/Documentation/serial/driver
index 86e47c19a924..7fe9e8ec0cae 100644
--- a/Documentation/serial/driver
+++ b/Documentation/serial/driver
@@ -1,6 +1,6 @@
-
- Low Level Serial API
- --------------------
+====================
+Low Level Serial API
+====================
This document is meant as a brief overview of some aspects of the new serial
@@ -44,7 +44,7 @@ are described in the uart_ops listing below.)
There are two locks. A per-port spinlock, and an overall semaphore.
From the core driver perspective, the port->lock locks the following
-data:
+data::
port->mctrl
port->icount
@@ -75,41 +75,51 @@ hardware.
return TIOCSER_TEMT.
Locking: none.
+
Interrupts: caller dependent.
+
This call must not sleep
set_mctrl(port, mctrl)
This function sets the modem control lines for port described
by 'port' to the state described by mctrl. The relevant bits
of mctrl are:
+
- TIOCM_RTS RTS signal.
- TIOCM_DTR DTR signal.
- TIOCM_OUT1 OUT1 signal.
- TIOCM_OUT2 OUT2 signal.
- TIOCM_LOOP Set the port into loopback mode.
+
If the appropriate bit is set, the signal should be driven
active. If the bit is clear, the signal should be driven
inactive.
Locking: port->lock taken.
+
Interrupts: locally disabled.
+
This call must not sleep
get_mctrl(port)
Returns the current state of modem control inputs. The state
of the outputs should not be returned, since the core keeps
track of their state. The state information should include:
+
- TIOCM_CAR state of DCD signal
- TIOCM_CTS state of CTS signal
- TIOCM_DSR state of DSR signal
- TIOCM_RI state of RI signal
+
The bit is set if the signal is currently driven active. If
the port does not support CTS, DCD or DSR, the driver should
indicate that the signal is permanently active. If RI is
not available, the signal should not be indicated as active.
Locking: port->lock taken.
+
Interrupts: locally disabled.
+
This call must not sleep
stop_tx(port)
@@ -121,14 +131,18 @@ hardware.
possible.
Locking: port->lock taken.
+
Interrupts: locally disabled.
+
This call must not sleep
start_tx(port)
Start transmitting characters.
Locking: port->lock taken.
+
Interrupts: locally disabled.
+
This call must not sleep
throttle(port)
@@ -138,16 +152,17 @@ hardware.
This will be called only if hardware assisted flow control is enabled.
Locking: serialized with .unthrottle() and termios modification by the
- tty layer.
+ tty layer.
unthrottle(port)
Notify the serial driver that characters can now be sent to the serial
port without fear of overrunning the input buffers of the line
disciplines.
+
This will be called only if hardware assisted flow control is enabled.
Locking: serialized with .throttle() and termios modification by the
- tty layer.
+ tty layer.
send_xchar(port,ch)
Transmit a high priority character, even if the port is stopped.
@@ -159,6 +174,7 @@ hardware.
Do not transmit if ch == '\0' (__DISABLED_CHAR).
Locking: none.
+
Interrupts: caller dependent.
stop_rx(port)
@@ -166,7 +182,9 @@ hardware.
being closed.
Locking: port->lock taken.
+
Interrupts: locally disabled.
+
This call must not sleep
enable_ms(port)
@@ -177,7 +195,9 @@ hardware.
called.
Locking: port->lock taken.
+
Interrupts: locally disabled.
+
This call must not sleep
break_ctl(port,ctl)
@@ -196,6 +216,7 @@ hardware.
This method will only be called when the port is initially opened.
Locking: port_sem taken.
+
Interrupts: globally disabled.
shutdown(port)
@@ -210,6 +231,7 @@ hardware.
this port.
Locking: port_sem taken.
+
Interrupts: caller dependent.
flush_buffer(port)
@@ -220,7 +242,9 @@ hardware.
buffer is cleared.
Locking: port->lock taken.
+
Interrupts: locally disabled.
+
This call must not sleep
set_termios(port,termios,oldtermios)
@@ -228,29 +252,46 @@ hardware.
bits. Update read_status_mask and ignore_status_mask to indicate
the types of events we are interested in receiving. Relevant
termios->c_cflag bits are:
- CSIZE - word size
- CSTOPB - 2 stop bits
- PARENB - parity enable
- PARODD - odd parity (when PARENB is in force)
- CREAD - enable reception of characters (if not set,
+
+ CSIZE
+ - word size
+ CSTOPB
+ - 2 stop bits
+ PARENB
+ - parity enable
+ PARODD
+ - odd parity (when PARENB is in force)
+ CREAD
+ - enable reception of characters (if not set,
still receive characters from the port, but
throw them away.
- CRTSCTS - if set, enable CTS status change reporting
- CLOCAL - if not set, enable modem status change
+ CRTSCTS
+ - if set, enable CTS status change reporting
+ CLOCAL
+ - if not set, enable modem status change
reporting.
+
Relevant termios->c_iflag bits are:
- INPCK - enable frame and parity error events to be
+
+ INPCK
+ - enable frame and parity error events to be
passed to the TTY layer.
- BRKINT
- PARMRK - both of these enable break events to be
+ BRKINT / PARMRK
+ - both of these enable break events to be
passed to the TTY layer.
- IGNPAR - ignore parity and framing errors
- IGNBRK - ignore break errors, If IGNPAR is also
+ IGNPAR
+ - ignore parity and framing errors
+ IGNBRK
+ - ignore break errors, If IGNPAR is also
set, ignore overrun errors as well.
+
The interaction of the iflag bits is as follows (parity error
given as an example):
+
+ =============== ======= ====== =============================
Parity error INPCK IGNPAR
+ =============== ======= ====== =============================
n/a 0 n/a character received, marked as
TTY_NORMAL
None 1 n/a character received, marked as
@@ -258,12 +299,15 @@ hardware.
Yes 1 0 character received, marked as
TTY_PARITY
Yes 1 1 character discarded
+ =============== ======= ====== =============================
Other flags may be used (eg, xon/xoff characters) if your
hardware supports hardware "soft" flow control.
Locking: caller holds tty_port->mutex
+
Interrupts: caller dependent.
+
This call must not sleep
set_ldisc(port,termios)
@@ -283,6 +327,7 @@ hardware.
will occur even if CONFIG_PM is not set.
Locking: none.
+
Interrupts: caller dependent.
type(port)
@@ -291,6 +336,7 @@ hardware.
substituted.
Locking: none.
+
Interrupts: caller dependent.
release_port(port)
@@ -298,6 +344,7 @@ hardware.
the port.
Locking: none.
+
Interrupts: caller dependent.
request_port(port)
@@ -306,6 +353,7 @@ hardware.
returns, and it should return -EBUSY on failure.
Locking: none.
+
Interrupts: caller dependent.
config_port(port,type)
@@ -321,6 +369,7 @@ hardware.
internally hard wired (eg, system on a chip implementations).
Locking: none.
+
Interrupts: caller dependent.
verify_port(port,serinfo)
@@ -328,6 +377,7 @@ hardware.
suitable for this port type.
Locking: none.
+
Interrupts: caller dependent.
ioctl(port,cmd,arg)
@@ -335,6 +385,7 @@ hardware.
using the standard numbering system found in <asm/ioctl.h>
Locking: none.
+
Interrupts: caller dependent.
poll_init(port)
@@ -343,6 +394,7 @@ hardware.
this should not request interrupts.
Locking: tty_mutex and tty_port->mutex taken.
+
Interrupts: n/a.
poll_put_char(port,ch)
@@ -350,7 +402,9 @@ hardware.
port. It can and should block until there is space in the TX FIFO.
Locking: none.
+
Interrupts: caller dependent.
+
This call must not sleep
poll_get_char(port)
@@ -359,7 +413,9 @@ hardware.
the function should return NO_POLL_CHAR immediately.
Locking: none.
+
Interrupts: caller dependent.
+
This call must not sleep
Other functions
@@ -370,6 +426,7 @@ uart_update_timeout(port,cflag,baud)
number of bits, parity, stop bits and baud rate.
Locking: caller is expected to take port->lock
+
Interrupts: n/a
uart_get_baud_rate(port,termios,old,min,max)
@@ -385,6 +442,7 @@ uart_get_baud_rate(port,termios,old,min,max)
Note: min..max must always allow 9600 baud to be selected.
Locking: caller dependent.
+
Interrupts: n/a
uart_get_divisor(port,baud)
@@ -395,6 +453,7 @@ uart_get_divisor(port,baud)
custom divisor instead.
Locking: caller dependent.
+
Interrupts: n/a
uart_match_port(port1,port2)
@@ -402,6 +461,7 @@ uart_match_port(port1,port2)
uart_port structures describe the same port.
Locking: n/a
+
Interrupts: n/a
uart_write_wakeup(port)
@@ -409,6 +469,7 @@ uart_write_wakeup(port)
characters in the transmit buffer have dropped below a threshold.
Locking: port->lock should be held.
+
Interrupts: n/a
uart_register_driver(drv)
@@ -419,6 +480,7 @@ uart_register_driver(drv)
registered using uart_add_one_port after this call has succeeded.
Locking: none
+
Interrupts: enabled
uart_unregister_driver()
@@ -427,15 +489,16 @@ uart_unregister_driver()
uart_remove_one_port() if it registered them with uart_add_one_port().
Locking: none
+
Interrupts: enabled
-uart_suspend_port()
+**uart_suspend_port()**
-uart_resume_port()
+**uart_resume_port()**
-uart_add_one_port()
+**uart_add_one_port()**
-uart_remove_one_port()
+**uart_remove_one_port()**
Other notes
-----------
@@ -444,7 +507,7 @@ It is intended some day to drop the 'unused' entries from uart_port, and
allow low level drivers to register their own individual uart_port's with
the core. This will allow drivers to use uart_port as a pointer to a
structure containing both the uart_port entry with their own extensions,
-thus:
+thus::
struct my_port {
struct uart_port port;
@@ -459,14 +522,14 @@ Some helpers are provided in order to set/get modem control lines via GPIO.
mctrl_gpio_init(port, idx):
This will get the {cts,rts,...}-gpios from device tree if they are
present and request them, set direction etc, and return an
- allocated structure. devm_* functions are used, so there's no need
+ allocated structure. `devm_*` functions are used, so there's no need
to call mctrl_gpio_free().
As this sets up the irq handling make sure to not handle changes to the
gpio input lines in your driver, too.
mctrl_gpio_free(dev, gpios):
This will free the requested gpios in mctrl_gpio_init().
- As devm_* functions are used, there's generally no need to call
+ As `devm_*` functions are used, there's generally no need to call
this function.
mctrl_gpio_to_gpiod(gpios, gidx)
diff --git a/Documentation/serial/moxa-smartio b/Documentation/serial/moxa-smartio
index 5d2a33be0bd8..156100f17c3f 100644
--- a/Documentation/serial/moxa-smartio
+++ b/Documentation/serial/moxa-smartio
@@ -1,28 +1,34 @@
-=============================================================================
- MOXA Smartio/Industio Family Device Driver Installation Guide
- for Linux Kernel 2.4.x, 2.6.x
- Copyright (C) 2008, Moxa Inc.
-=============================================================================
+=============================================================
+MOXA Smartio/Industio Family Device Driver Installation Guide
+=============================================================
+
+.. note::
+
+ This file is outdated. It needs some care in order to make it
+ updated to Kernel 5.0 and upper
+
+Copyright (C) 2008, Moxa Inc.
+
Date: 01/21/2008
-Content
+.. Content
-1. Introduction
-2. System Requirement
-3. Installation
- 3.1 Hardware installation
- 3.2 Driver files
- 3.3 Device naming convention
- 3.4 Module driver configuration
- 3.5 Static driver configuration for Linux kernel 2.4.x and 2.6.x.
- 3.6 Custom configuration
- 3.7 Verify driver installation
-4. Utilities
-5. Setserial
-6. Troubleshooting
+ 1. Introduction
+ 2. System Requirement
+ 3. Installation
+ 3.1 Hardware installation
+ 3.2 Driver files
+ 3.3 Device naming convention
+ 3.4 Module driver configuration
+ 3.5 Static driver configuration for Linux kernel 2.4.x and 2.6.x.
+ 3.6 Custom configuration
+ 3.7 Verify driver installation
+ 4. Utilities
+ 5. Setserial
+ 6. Troubleshooting
------------------------------------------------------------------------------
1. Introduction
+^^^^^^^^^^^^^^^
The Smartio/Industio/UPCI family Linux driver supports following multiport
boards.
@@ -43,7 +49,7 @@ Content
C104H, C104HS,
CI-104J, CI-104JS,
CI-134, CI-134I, CI-134IS,
- (C114HI, CT-114I, C104P)
+ (C114HI, CT-114I, C104P),
POS-104UL,
CB-114,
CB-134I
@@ -63,13 +69,17 @@ Content
occurs, please contact Moxa at support@moxa.com.tw.
In addition to device driver, useful utilities are also provided in this
- version. They are
- - msdiag Diagnostic program for displaying installed Moxa
+ version. They are:
+
+ - msdiag
+ Diagnostic program for displaying installed Moxa
Smartio/Industio boards.
- - msmon Monitor program to observe data count and line status signals.
+ - msmon
+ Monitor program to observe data count and line status signals.
- msterm A simple terminal program which is useful in testing serial
ports.
- - io-irq.exe Configuration program to setup ISA boards. Please note that
+ - io-irq.exe
+ Configuration program to setup ISA boards. Please note that
this program can only be executed under DOS.
All the drivers and utilities are published in form of source code under
@@ -84,65 +94,63 @@ Content
please refer to hardware installation procedure in the User's Manual.
We assume the user should be familiar with following documents.
+
- Serial-HOWTO
- Kernel-HOWTO
------------------------------------------------------------------------------
2. System Requirement
+^^^^^^^^^^^^^^^^^^^^^
+
- Hardware platform: Intel x86 machine
- Kernel version: 2.4.x or 2.6.x
- gcc version 2.72 or later
- Maximum 4 boards can be installed in combination
------------------------------------------------------------------------------
3. Installation
+^^^^^^^^^^^^^^^
- 3.1 Hardware installation
- 3.2 Driver files
- 3.3 Device naming convention
- 3.4 Module driver configuration
- 3.5 Static driver configuration for Linux kernel 2.4.x, 2.6.x.
- 3.6 Custom configuration
- 3.7 Verify driver installation
+3.1 Hardware installation
+=========================
+ There are two types of buses, ISA and PCI, for Smartio/Industio
+ family multiport board.
- 3.1 Hardware installation
+ISA board
+---------
- There are two types of buses, ISA and PCI, for Smartio/Industio
- family multiport board.
+ You'll have to configure CAP address, I/O address, Interrupt Vector
+ as well as IRQ before installing this driver. Please refer to hardware
+ installation procedure in User's Manual before proceed any further.
+ Please make sure the JP1 is open after the ISA board is set properly.
- ISA board
- ---------
- You'll have to configure CAP address, I/O address, Interrupt Vector
- as well as IRQ before installing this driver. Please refer to hardware
- installation procedure in User's Manual before proceed any further.
- Please make sure the JP1 is open after the ISA board is set properly.
+PCI/UPCI board
+--------------
- PCI/UPCI board
- --------------
- You may need to adjust IRQ usage in BIOS to avoid from IRQ conflict
- with other ISA devices. Please refer to hardware installation
- procedure in User's Manual in advance.
+ You may need to adjust IRQ usage in BIOS to avoid from IRQ conflict
+ with other ISA devices. Please refer to hardware installation
+ procedure in User's Manual in advance.
- PCI IRQ Sharing
- -----------
- Each port within the same multiport board shares the same IRQ. Up to
- 4 Moxa Smartio/Industio PCI Family multiport boards can be installed
- together on one system and they can share the same IRQ.
+PCI IRQ Sharing
+---------------
+ Each port within the same multiport board shares the same IRQ. Up to
+ 4 Moxa Smartio/Industio PCI Family multiport boards can be installed
+ together on one system and they can share the same IRQ.
- 3.2 Driver files
- The driver file may be obtained from ftp, CD-ROM or floppy disk. The
- first step, anyway, is to copy driver file "mxser.tgz" into specified
- directory. e.g. /moxa. The execute commands as below.
+3.2 Driver files
+================
+
+ The driver file may be obtained from ftp, CD-ROM or floppy disk. The
+ first step, anyway, is to copy driver file "mxser.tgz" into specified
+ directory. e.g. /moxa. The execute commands as below::
# cd /
# mkdir moxa
# cd /moxa
# tar xvf /dev/fd0
- or
+or::
# cd /
# mkdir moxa
@@ -151,278 +159,348 @@ Content
# tar xvfz mxser.tgz
- 3.3 Device naming convention
-
- You may find all the driver and utilities files in /moxa/mxser.
- Following installation procedure depends on the model you'd like to
- run the driver. If you prefer module driver, please refer to 3.4.
- If static driver is required, please refer to 3.5.
-
- Dialin and callout port
- -----------------------
- This driver remains traditional serial device properties. There are
- two special file name for each serial port. One is dial-in port
- which is named "ttyMxx". For callout port, the naming convention
- is "cumxx".
-
- Device naming when more than 2 boards installed
- -----------------------------------------------
- Naming convention for each Smartio/Industio multiport board is
- pre-defined as below.
-
- Board Num. Dial-in Port Callout port
- 1st board ttyM0 - ttyM7 cum0 - cum7
- 2nd board ttyM8 - ttyM15 cum8 - cum15
- 3rd board ttyM16 - ttyM23 cum16 - cum23
- 4th board ttyM24 - ttym31 cum24 - cum31
-
-
- !!!!!!!!!!!!!!!!!!!! NOTE !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
- Under Kernel 2.6 the cum Device is Obsolete. So use ttyM*
- device instead.
- !!!!!!!!!!!!!!!!!!!! NOTE !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
-
- Board sequence
- --------------
- This driver will activate ISA boards according to the parameter set
- in the driver. After all specified ISA board activated, PCI board
- will be installed in the system automatically driven.
- Therefore the board number is sorted by the CAP address of ISA boards.
- For PCI boards, their sequence will be after ISA boards and C168H/PCI
- has higher priority than C104H/PCI boards.
-
- 3.4 Module driver configuration
- Module driver is easiest way to install. If you prefer static driver
- installation, please skip this paragraph.
-
-
- ------------- Prepare to use the MOXA driver--------------------
- 3.4.1 Create tty device with correct major number
- Before using MOXA driver, your system must have the tty devices
- which are created with driver's major number. We offer one shell
- script "msmknod" to simplify the procedure.
- This step is only needed to be executed once. But you still
- need to do this procedure when:
- a. You change the driver's major number. Please refer the "3.7"
- section.
- b. Your total installed MOXA boards number is changed. Maybe you
- add/delete one MOXA board.
- c. You want to change the tty name. This needs to modify the
- shell script "msmknod"
-
- The procedure is:
- # cd /moxa/mxser/driver
- # ./msmknod
-
- This shell script will require the major number for dial-in
- device and callout device to create tty device. You also need
- to specify the total installed MOXA board number. Default major
- numbers for dial-in device and callout device are 30, 35. If
- you need to change to other number, please refer section "3.7"
- for more detailed procedure.
- Msmknod will delete any special files occupying the same device
- naming.
-
- 3.4.2 Build the MOXA driver and utilities
- Before using the MOXA driver and utilities, you need compile the
- all the source code. This step is only need to be executed once.
- But you still re-compile the source code if you modify the source
- code. For example, if you change the driver's major number (see
- "3.7" section), then you need to do this step again.
-
- Find "Makefile" in /moxa/mxser, then run
-
- # make clean; make install
-
- !!!!!!!!!! NOTE !!!!!!!!!!!!!!!!!
- For Red Hat 9, Red Hat Enterprise Linux AS3/ES3/WS3 & Fedora Core1:
- # make clean; make installsp1
-
- For Red Hat Enterprise Linux AS4/ES4/WS4:
- # make clean; make installsp2
- !!!!!!!!!! NOTE !!!!!!!!!!!!!!!!!
-
- The driver files "mxser.o" and utilities will be properly compiled
- and copied to system directories respectively.
-
- ------------- Load MOXA driver--------------------
- 3.4.3 Load the MOXA driver
-
- # modprobe mxser <argument>
-
- will activate the module driver. You may run "lsmod" to check
- if "mxser" is activated. If the MOXA board is ISA board, the
- <argument> is needed. Please refer to section "3.4.5" for more
- information.
-
-
- ------------- Load MOXA driver on boot --------------------
- 3.4.4 For the above description, you may manually execute
- "modprobe mxser" to activate this driver and run
- "rmmod mxser" to remove it.
- However, it's better to have a boot time configuration to
- eliminate manual operation. Boot time configuration can be
- achieved by rc file. We offer one "rc.mxser" file to simplify
- the procedure under "moxa/mxser/driver".
-
- But if you use ISA board, please modify the "modprobe ..." command
- to add the argument (see "3.4.5" section). After modifying the
- rc.mxser, please try to execute "/moxa/mxser/driver/rc.mxser"
- manually to make sure the modification is ok. If any error
- encountered, please try to modify again. If the modification is
- completed, follow the below step.
-
- Run following command for setting rc files.
-
- # cd /moxa/mxser/driver
- # cp ./rc.mxser /etc/rc.d
- # cd /etc/rc.d
-
- Check "rc.serial" is existed or not. If "rc.serial" doesn't exist,
- create it by vi, run "chmod 755 rc.serial" to change the permission.
- Add "/etc/rc.d/rc.mxser" in last line,
-
- Reboot and check if moxa.o activated by "lsmod" command.
-
- 3.4.5. If you'd like to drive Smartio/Industio ISA boards in the system,
- you'll have to add parameter to specify CAP address of given
- board while activating "mxser.o". The format for parameters are
- as follows.
-
- modprobe mxser ioaddr=0x???,0x???,0x???,0x???
- | | | |
- | | | +- 4th ISA board
- | | +------ 3rd ISA board
- | +------------ 2nd ISA board
- +------------------- 1st ISA board
-
- 3.5 Static driver configuration for Linux kernel 2.4.x and 2.6.x
-
- Note: To use static driver, you must install the linux kernel
- source package.
-
- 3.5.1 Backup the built-in driver in the kernel.
- # cd /usr/src/linux/drivers/char
- # mv mxser.c mxser.c.old
-
- For Red Hat 7.x user, you need to create link:
- # cd /usr/src
- # ln -s linux-2.4 linux
+3.3 Device naming convention
+============================
+
+ You may find all the driver and utilities files in /moxa/mxser.
+ Following installation procedure depends on the model you'd like to
+ run the driver. If you prefer module driver, please refer to 3.4.
+ If static driver is required, please refer to 3.5.
+
+Dialin and callout port
+-----------------------
+
+ This driver remains traditional serial device properties. There are
+ two special file name for each serial port. One is dial-in port
+ which is named "ttyMxx". For callout port, the naming convention
+ is "cumxx".
+
+Device naming when more than 2 boards installed
+-----------------------------------------------
+
+ Naming convention for each Smartio/Industio multiport board is
+ pre-defined as below.
+
+ ============ =============== ==============
+ Board Num. Dial-in Port Callout port
+ 1st board ttyM0 - ttyM7 cum0 - cum7
+ 2nd board ttyM8 - ttyM15 cum8 - cum15
+ 3rd board ttyM16 - ttyM23 cum16 - cum23
+ 4th board ttyM24 - ttym31 cum24 - cum31
+ ============ =============== ==============
+
+.. note::
+
+ Under Kernel 2.6 and upper, the cum Device is Obsolete. So use ttyM*
+ device instead.
+
+Board sequence
+--------------
+
+ This driver will activate ISA boards according to the parameter set
+ in the driver. After all specified ISA board activated, PCI board
+ will be installed in the system automatically driven.
+ Therefore the board number is sorted by the CAP address of ISA boards.
+ For PCI boards, their sequence will be after ISA boards and C168H/PCI
+ has higher priority than C104H/PCI boards.
+
+3.4 Module driver configuration
+===============================
+
+ Module driver is easiest way to install. If you prefer static driver
+ installation, please skip this paragraph.
+
+
+ ------------- Prepare to use the MOXA driver --------------------
+
+3.4.1 Create tty device with correct major number
+-------------------------------------------------
+
+ Before using MOXA driver, your system must have the tty devices
+ which are created with driver's major number. We offer one shell
+ script "msmknod" to simplify the procedure.
+ This step is only needed to be executed once. But you still
+ need to do this procedure when:
+
+ a. You change the driver's major number. Please refer the "3.7"
+ section.
+ b. Your total installed MOXA boards number is changed. Maybe you
+ add/delete one MOXA board.
+ c. You want to change the tty name. This needs to modify the
+ shell script "msmknod"
+
+ The procedure is::
+
+ # cd /moxa/mxser/driver
+ # ./msmknod
+
+ This shell script will require the major number for dial-in
+ device and callout device to create tty device. You also need
+ to specify the total installed MOXA board number. Default major
+ numbers for dial-in device and callout device are 30, 35. If
+ you need to change to other number, please refer section "3.7"
+ for more detailed procedure.
+ Msmknod will delete any special files occupying the same device
+ naming.
+
+3.4.2 Build the MOXA driver and utilities
+-----------------------------------------
+
+ Before using the MOXA driver and utilities, you need compile the
+ all the source code. This step is only need to be executed once.
+ But you still re-compile the source code if you modify the source
+ code. For example, if you change the driver's major number (see
+ "3.7" section), then you need to do this step again.
+
+ Find "Makefile" in /moxa/mxser, then run
+
+ # make clean; make install
+
+ ..note::
+
+ For Red Hat 9, Red Hat Enterprise Linux AS3/ES3/WS3 & Fedora Core1:
+ # make clean; make installsp1
+
+ For Red Hat Enterprise Linux AS4/ES4/WS4:
+ # make clean; make installsp2
+
+ The driver files "mxser.o" and utilities will be properly compiled
+ and copied to system directories respectively.
+
+------------- Load MOXA driver--------------------
+
+3.4.3 Load the MOXA driver
+--------------------------
+
+ ::
+
+ # modprobe mxser <argument>
+
+ will activate the module driver. You may run "lsmod" to check
+ if "mxser" is activated. If the MOXA board is ISA board, the
+ <argument> is needed. Please refer to section "3.4.5" for more
+ information.
+
+------------- Load MOXA driver on boot --------------------
+
+3.4.4 Load the mxser driver
+---------------------------
+
+
+ For the above description, you may manually execute
+ "modprobe mxser" to activate this driver and run
+ "rmmod mxser" to remove it.
+
+ However, it's better to have a boot time configuration to
+ eliminate manual operation. Boot time configuration can be
+ achieved by rc file. We offer one "rc.mxser" file to simplify
+ the procedure under "moxa/mxser/driver".
+
+ But if you use ISA board, please modify the "modprobe ..." command
+ to add the argument (see "3.4.5" section). After modifying the
+ rc.mxser, please try to execute "/moxa/mxser/driver/rc.mxser"
+ manually to make sure the modification is ok. If any error
+ encountered, please try to modify again. If the modification is
+ completed, follow the below step.
+
+ Run following command for setting rc files::
+
+ # cd /moxa/mxser/driver
+ # cp ./rc.mxser /etc/rc.d
+ # cd /etc/rc.d
+
+ Check "rc.serial" is existed or not. If "rc.serial" doesn't exist,
+ create it by vi, run "chmod 755 rc.serial" to change the permission.
+
+ Add "/etc/rc.d/rc.mxser" in last line.
+
+ Reboot and check if moxa.o activated by "lsmod" command.
+
+3.4.5. specify CAP address
+--------------------------
+
+ If you'd like to drive Smartio/Industio ISA boards in the system,
+ you'll have to add parameter to specify CAP address of given
+ board while activating "mxser.o". The format for parameters are
+ as follows.::
+
+ modprobe mxser ioaddr=0x???,0x???,0x???,0x???
+ | | | |
+ | | | +- 4th ISA board
+ | | +------ 3rd ISA board
+ | +------------ 2nd ISA board
+ +-------------------1st ISA board
+
+3.5 Static driver configuration for Linux kernel 2.4.x and 2.6.x
+================================================================
+
+ Note:
+ To use static driver, you must install the linux kernel
+ source package.
+
+3.5.1 Backup the built-in driver in the kernel
+----------------------------------------------
+
+ ::
+
+ # cd /usr/src/linux/drivers/char
+ # mv mxser.c mxser.c.old
+
+ For Red Hat 7.x user, you need to create link:
+ # cd /usr/src
+ # ln -s linux-2.4 linux
+
+3.5.2 Create link
+-----------------
+ ::
- 3.5.2 Create link
# cd /usr/src/linux/drivers/char
# ln -s /moxa/mxser/driver/mxser.c mxser.c
- 3.5.3 Add CAP address list for ISA boards. For PCI boards user,
- please skip this step.
-
- In module mode, the CAP address for ISA board is given by
- parameter. In static driver configuration, you'll have to
- assign it within driver's source code. If you will not
- install any ISA boards, you may skip to next portion.
- The instructions to modify driver source code are as
- below.
- a. # cd /moxa/mxser/driver
- # vi mxser.c
- b. Find the array mxserBoardCAP[] as below.
-
- static int mxserBoardCAP[]
- = {0x00, 0x00, 0x00, 0x00};
-
- c. Change the address within this array using vi. For
- example, to driver 2 ISA boards with CAP address
- 0x280 and 0x180 as 1st and 2nd board. Just to change
- the source code as follows.
-
- static int mxserBoardCAP[]
- = {0x280, 0x180, 0x00, 0x00};
-
- 3.5.4 Setup kernel configuration
-
- Configure the kernel:
-
- # cd /usr/src/linux
- # make menuconfig
-
- You will go into a menu-driven system. Please select [Character
- devices][Non-standard serial port support], enable the [Moxa
- SmartIO support] driver with "[*]" for built-in (not "[M]"), then
- select [Exit] to exit this program.
-
- 3.5.5 Rebuild kernel
- The following are for Linux kernel rebuilding, for your
- reference only.
- For appropriate details, please refer to the Linux document.
-
- a. cd /usr/src/linux
- b. make clean /* take a few minutes */
- c. make dep /* take a few minutes */
- d. make bzImage /* take probably 10-20 minutes */
- e. make install /* copy boot image to correct position */
- f. Please make sure the boot kernel (vmlinuz) is in the
- correct position.
- g. If you use 'lilo' utility, you should check /etc/lilo.conf
- 'image' item specified the path which is the 'vmlinuz' path,
- or you will load wrong (or old) boot kernel image (vmlinuz).
- After checking /etc/lilo.conf, please run "lilo".
+3.5.3 Add CAP address list for ISA boards.
+------------------------------------------
+
+ For PCI boards user, please skip this step.
+
+ In module mode, the CAP address for ISA board is given by
+ parameter. In static driver configuration, you'll have to
+ assign it within driver's source code. If you will not
+ install any ISA boards, you may skip to next portion.
+ The instructions to modify driver source code are as
+ below.
+
+ a. run::
+
+ # cd /moxa/mxser/driver
+ # vi mxser.c
+
+ b. Find the array mxserBoardCAP[] as below::
+
+ static int mxserBoardCAP[] = {0x00, 0x00, 0x00, 0x00};
+
+ c. Change the address within this array using vi. For
+ example, to driver 2 ISA boards with CAP address
+ 0x280 and 0x180 as 1st and 2nd board. Just to change
+ the source code as follows::
+
+ static int mxserBoardCAP[] = {0x280, 0x180, 0x00, 0x00};
+
+3.5.4 Setup kernel configuration
+--------------------------------
+
+ Configure the kernel::
+
+ # cd /usr/src/linux
+ # make menuconfig
+
+ You will go into a menu-driven system. Please select [Character
+ devices][Non-standard serial port support], enable the [Moxa
+ SmartIO support] driver with "[*]" for built-in (not "[M]"), then
+ select [Exit] to exit this program.
+
+3.5.5 Rebuild kernel
+--------------------
+
+ The following are for Linux kernel rebuilding, for your
+ reference only.
+
+ For appropriate details, please refer to the Linux document:
+
+ a. Run the following commands::
+
+ cd /usr/src/linux
+ make clean # take a few minutes
+ make dep # take a few minutes
+ make bzImage # take probably 10-20 minutes
+ make install # copy boot image to correct position
+
+ f. Please make sure the boot kernel (vmlinuz) is in the
+ correct position.
+ g. If you use 'lilo' utility, you should check /etc/lilo.conf
+ 'image' item specified the path which is the 'vmlinuz' path,
+ or you will load wrong (or old) boot kernel image (vmlinuz).
+ After checking /etc/lilo.conf, please run "lilo".
Note that if the result of "make bzImage" is ERROR, then you have to
go back to Linux configuration Setup. Type "make menuconfig" in
directory /usr/src/linux.
- 3.5.6 Make tty device and special file
- # cd /moxa/mxser/driver
- # ./msmknod
+3.5.6 Make tty device and special file
+--------------------------------------
+
+ ::
+ # cd /moxa/mxser/driver
+ # ./msmknod
+
+3.5.7 Make utility
+------------------
+
+ ::
- 3.5.7 Make utility
# cd /moxa/mxser/utility
# make clean; make install
- 3.5.8 Reboot
-
-
-
- 3.6 Custom configuration
- Although this driver already provides you default configuration, you
- still can change the device name and major number. The instruction to
- change these parameters are shown as below.
-
- Change Device name
- ------------------
- If you'd like to use other device names instead of default naming
- convention, all you have to do is to modify the internal code
- within the shell script "msmknod". First, you have to open "msmknod"
- by vi. Locate each line contains "ttyM" and "cum" and change them
- to the device name you desired. "msmknod" creates the device names
- you need next time executed.
-
- Change Major number
- -------------------
- If major number 30 and 35 had been occupied, you may have to select
- 2 free major numbers for this driver. There are 3 steps to change
- major numbers.
-
- 3.6.1 Find free major numbers
- In /proc/devices, you may find all the major numbers occupied
- in the system. Please select 2 major numbers that are available.
- e.g. 40, 45.
- 3.6.2 Create special files
- Run /moxa/mxser/driver/msmknod to create special files with
- specified major numbers.
- 3.6.3 Modify driver with new major number
- Run vi to open /moxa/mxser/driver/mxser.c. Locate the line
- contains "MXSERMAJOR". Change the content as below.
+3.5.8 Reboot
+------------
+
+
+
+3.6 Custom configuration
+========================
+
+ Although this driver already provides you default configuration, you
+ still can change the device name and major number. The instruction to
+ change these parameters are shown as below.
+
+a. Change Device name
+
+ If you'd like to use other device names instead of default naming
+ convention, all you have to do is to modify the internal code
+ within the shell script "msmknod". First, you have to open "msmknod"
+ by vi. Locate each line contains "ttyM" and "cum" and change them
+ to the device name you desired. "msmknod" creates the device names
+ you need next time executed.
+
+b. Change Major number
+
+ If major number 30 and 35 had been occupied, you may have to select
+ 2 free major numbers for this driver. There are 3 steps to change
+ major numbers.
+
+3.6.1 Find free major numbers
+-----------------------------
+
+ In /proc/devices, you may find all the major numbers occupied
+ in the system. Please select 2 major numbers that are available.
+ e.g. 40, 45.
+
+3.6.2 Create special files
+--------------------------
+
+ Run /moxa/mxser/driver/msmknod to create special files with
+ specified major numbers.
+
+3.6.3 Modify driver with new major number
+-----------------------------------------
+
+ Run vi to open /moxa/mxser/driver/mxser.c. Locate the line
+ contains "MXSERMAJOR". Change the content as below::
+
#define MXSERMAJOR 40
#define MXSERCUMAJOR 45
- 3.6.4 Run "make clean; make install" in /moxa/mxser/driver.
- 3.7 Verify driver installation
- You may refer to /var/log/messages to check the latest status
- log reported by this driver whenever it's activated.
+ 3.6.4 Run "make clean; make install" in /moxa/mxser/driver.
+
+3.7 Verify driver installation
+==============================
+
+ You may refer to /var/log/messages to check the latest status
+ log reported by this driver whenever it's activated.
------------------------------------------------------------------------------
4. Utilities
+^^^^^^^^^^^^
+
There are 3 utilities contained in this driver. They are msdiag, msmon and
msterm. These 3 utilities are released in form of source code. They should
be compiled into executable file and copied into /usr/bin.
@@ -430,16 +508,19 @@ Content
Before using these utilities, please load driver (refer 3.4 & 3.5) and
make sure you had run the "msmknod" utility.
- msdiag - Diagnostic
- --------------------
+msdiag - Diagnostic
+===================
+
This utility provides the function to display what Moxa Smartio/Industio
board found by driver in the system.
- msmon - Port Monitoring
- -----------------------
+msmon - Port Monitoring
+=======================
+
This utility gives the user a quick view about all the MOXA ports'
activities. One can easily learn each port's total received/transmitted
(Rx/Tx) character count since the time when the monitoring is started.
+
Rx/Tx throughputs per second are also reported in interval basis (e.g.
the last 5 seconds) and in average basis (since the time the monitoring
is started). You can reset all ports' count by <HOME> key. <+> <->
@@ -447,19 +528,21 @@ Content
on the port, that cursor stay, to view the port's communication
parameters, signal status, and input/output queue.
- msterm - Terminal Emulation
- ---------------------------
+msterm - Terminal Emulation
+===========================
+
This utility provides data sending and receiving ability of all tty ports,
especially for MOXA ports. It is quite useful for testing simple
application, for example, sending AT command to a modem connected to the
port or used as a terminal for login purpose. Note that this is only a
dumb terminal emulation without handling full screen operation.
------------------------------------------------------------------------------
5. Setserial
+^^^^^^^^^^^^
Supported Setserial parameters are listed as below.
+ ============== =========================================================
uart set UART type(16450-->disable FIFO, 16550A-->enable FIFO)
close_delay set the amount of time(in 1/100 of a second) that DTR
should be kept low while being closed.
@@ -475,49 +558,58 @@ Content
application requests 38.4kb.
divisor This option set the custom division.
baud_base This option set the base baud rate.
+ ============== =========================================================
------------------------------------------------------------------------------
6. Troubleshooting
+^^^^^^^^^^^^^^^^^^
The boot time error messages and solutions are stated as clearly as
possible. If all the possible solutions fail, please contact our technical
support team to get more help.
- Error msg: More than 4 Moxa Smartio/Industio family boards found. Fifth board
+ Error msg:
+ More than 4 Moxa Smartio/Industio family boards found. Fifth board
and after are ignored.
+
Solution:
To avoid this problem, please unplug fifth and after board, because Moxa
driver supports up to 4 boards.
- Error msg: Request_irq fail, IRQ(?) may be conflict with another device.
+ Error msg:
+ Request_irq fail, IRQ(?) may be conflict with another device.
+
Solution:
Other PCI or ISA devices occupy the assigned IRQ. If you are not sure
which device causes the situation, please check /proc/interrupts to find
free IRQ and simply change another free IRQ for Moxa board.
- Error msg: Board #: C1xx Series(CAP=xxx) interrupt number invalid.
+ Error msg:
+ Board #: C1xx Series(CAP=xxx) interrupt number invalid.
+
Solution:
Each port within the same multiport board shares the same IRQ. Please set
one IRQ (IRQ doesn't equal to zero) for one Moxa board.
- Error msg: No interrupt vector be set for Moxa ISA board(CAP=xxx).
+ Error msg:
+ No interrupt vector be set for Moxa ISA board(CAP=xxx).
+
Solution:
Moxa ISA board needs an interrupt vector.Please refer to user's manual
"Hardware Installation" chapter to set interrupt vector.
- Error msg: Couldn't install MOXA Smartio/Industio family driver!
+ Error msg:
+ Couldn't install MOXA Smartio/Industio family driver!
+
Solution:
Load Moxa driver fail, the major number may conflict with other devices.
Please refer to previous section 3.7 to change a free major number for
Moxa driver.
- Error msg: Couldn't install MOXA Smartio/Industio family callout driver!
+ Error msg:
+ Couldn't install MOXA Smartio/Industio family callout driver!
+
Solution:
Load Moxa callout driver fail, the callout device major number may
conflict with other devices. Please refer to previous section 3.7 to
change a free callout device major number for Moxa driver.
-
-
------------------------------------------------------------------------------
-
diff --git a/Documentation/serial/n_gsm.txt b/Documentation/serial/n_gsm.txt
index 875361bb7cb4..f3ad9fd26408 100644
--- a/Documentation/serial/n_gsm.txt
+++ b/Documentation/serial/n_gsm.txt
@@ -1,28 +1,31 @@
-n_gsm.c GSM 0710 tty multiplexor HOWTO
-===================================================
+==============================
+GSM 0710 tty multiplexor HOWTO
+==============================
This line discipline implements the GSM 07.10 multiplexing protocol
-detailed in the following 3GPP document :
-http://www.3gpp.org/ftp/Specs/archive/07_series/07.10/0710-720.zip
+detailed in the following 3GPP document:
+
+ http://www.3gpp.org/ftp/Specs/archive/07_series/07.10/0710-720.zip
This document give some hints on how to use this driver with GPRS and 3G
modems connected to a physical serial port.
How to use it
-------------
-1- initialize the modem in 0710 mux mode (usually AT+CMUX= command) through
-its serial port. Depending on the modem used, you can pass more or less
-parameters to this command,
-2- switch the serial line to using the n_gsm line discipline by using
-TIOCSETD ioctl,
-3- configure the mux using GSMIOC_GETCONF / GSMIOC_SETCONF ioctl,
+1. initialize the modem in 0710 mux mode (usually AT+CMUX= command) through
+ its serial port. Depending on the modem used, you can pass more or less
+ parameters to this command,
+2. switch the serial line to using the n_gsm line discipline by using
+ TIOCSETD ioctl,
+3. configure the mux using GSMIOC_GETCONF / GSMIOC_SETCONF ioctl,
Major parts of the initialization program :
-(a good starting point is util-linux-ng/sys-utils/ldattach.c)
-#include <linux/gsmmux.h>
-#define N_GSM0710 21 /* GSM 0710 Mux */
-#define DEFAULT_SPEED B115200
-#define SERIAL_PORT /dev/ttyS0
+(a good starting point is util-linux-ng/sys-utils/ldattach.c)::
+
+ #include <linux/gsmmux.h>
+ #define N_GSM0710 21 /* GSM 0710 Mux */
+ #define DEFAULT_SPEED B115200
+ #define SERIAL_PORT /dev/ttyS0
int ldisc = N_GSM0710;
struct gsm_config c;
@@ -60,37 +63,41 @@ Major parts of the initialization program :
daemon(0,0);
pause();
-4- create the devices corresponding to the "virtual" serial ports (take care,
-each modem has its configuration and some DLC have dedicated functions,
-for example GPS), starting with minor 1 (DLC0 is reserved for the management
-of the mux)
+4. create the devices corresponding to the "virtual" serial ports (take care,
+ each modem has its configuration and some DLC have dedicated functions,
+ for example GPS), starting with minor 1 (DLC0 is reserved for the management
+ of the mux)::
-MAJOR=`cat /proc/devices |grep gsmtty | awk '{print $1}`
-for i in `seq 1 4`; do
+ MAJOR=`cat /proc/devices |grep gsmtty | awk '{print $1}`
+ for i in `seq 1 4`; do
mknod /dev/ttygsm$i c $MAJOR $i
-done
+ done
-5- use these devices as plain serial ports.
-for example, it's possible :
-- and to use gnokii to send / receive SMS on ttygsm1
-- to use ppp to establish a datalink on ttygsm2
+5. use these devices as plain serial ports.
-6- first close all virtual ports before closing the physical port.
+ for example, it's possible:
-Note that after closing the physical port the modem is still in multiplexing
-mode. This may prevent a successful re-opening of the port later. To avoid
-this situation either reset the modem if your hardware allows that or send
-a disconnect command frame manually before initializing the multiplexing mode
-for the second time. The byte sequence for the disconnect command frame is:
-0xf9, 0x03, 0xef, 0x03, 0xc3, 0x16, 0xf9.
+ - and to use gnokii to send / receive SMS on ttygsm1
+ - to use ppp to establish a datalink on ttygsm2
+
+6. first close all virtual ports before closing the physical port.
+
+ Note that after closing the physical port the modem is still in multiplexing
+ mode. This may prevent a successful re-opening of the port later. To avoid
+ this situation either reset the modem if your hardware allows that or send
+ a disconnect command frame manually before initializing the multiplexing mode
+ for the second time. The byte sequence for the disconnect command frame is::
+
+ 0xf9, 0x03, 0xef, 0x03, 0xc3, 0x16, 0xf9.
Additional Documentation
------------------------
More practical details on the protocol and how it's supported by industrial
modems can be found in the following documents :
-http://www.telit.com/module/infopool/download.php?id=616
-http://www.u-blox.com/images/downloads/Product_Docs/LEON-G100-G200-MuxImplementation_ApplicationNote_%28GSM%20G1-CS-10002%29.pdf
-http://www.sierrawireless.com/Support/Downloads/AirPrime/WMP_Series/~/media/Support_Downloads/AirPrime/Application_notes/CMUX_Feature_Application_Note-Rev004.ashx
-http://wm.sim.com/sim/News/photo/2010721161442.pdf
+
+- http://www.telit.com/module/infopool/download.php?id=616
+- http://www.u-blox.com/images/downloads/Product_Docs/LEON-G100-G200-MuxImplementation_ApplicationNote_%28GSM%20G1-CS-10002%29.pdf
+- http://www.sierrawireless.com/Support/Downloads/AirPrime/WMP_Series/~/media/Support_Downloads/AirPrime/Application_notes/CMUX_Feature_Application_Note-Rev004.ashx
+- http://wm.sim.com/sim/News/photo/2010721161442.pdf
11-03-08 - Eric Bénard - <eric@eukrea.com>
diff --git a/Documentation/serial/rocket.txt b/Documentation/serial/rocket.txt
index 60b039891057..23761eae4282 100644
--- a/Documentation/serial/rocket.txt
+++ b/Documentation/serial/rocket.txt
@@ -1,20 +1,22 @@
-Comtrol(tm) RocketPort(R)/RocketModem(TM) Series
+================================================
+Comtrol(tm) RocketPort(R)/RocketModem(TM) Series
+================================================
+
Device Driver for the Linux Operating System
+============================================
-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
-
-PRODUCT OVERVIEW
+Product overview
----------------
This driver provides a loadable kernel driver for the Comtrol RocketPort
-and RocketModem PCI boards. These boards provide, 2, 4, 8, 16, or 32
+and RocketModem PCI boards. These boards provide, 2, 4, 8, 16, or 32
high-speed serial ports or modems. This driver supports up to a combination
of four RocketPort or RocketModems boards in one machine simultaneously.
This file assumes that you are using the RocketPort driver which is
-integrated into the kernel sources.
+integrated into the kernel sources.
-The driver can also be installed as an external module using the usual
-"make;make install" routine. This external module driver, obtainable
+The driver can also be installed as an external module using the usual
+"make;make install" routine. This external module driver, obtainable
from the Comtrol website listed below, is useful for updating the driver
or installing it into kernels which do not have the driver configured
into them. Installations instructions for the external module
@@ -29,57 +31,59 @@ information on how to set the DIP switches.
You pass the I/O port to the driver using the following module parameters:
-board1 : I/O port for the first ISA board
-board2 : I/O port for the second ISA board
-board3 : I/O port for the third ISA board
-board4 : I/O port for the fourth ISA board
+board1:
+ I/O port for the first ISA board
+board2:
+ I/O port for the second ISA board
+board3:
+ I/O port for the third ISA board
+board4:
+ I/O port for the fourth ISA board
There is a set of utilities and scripts provided with the external driver
-( downloadable from http://www.comtrol.com ) that ease the configuration and
+(downloadable from http://www.comtrol.com) that ease the configuration and
setup of the ISA cards.
The RocketModem II PCI boards require firmware to be loaded into the card
before it will function. The driver has only been tested as a module for this
board.
-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
-
-INSTALLATION PROCEDURES
+Installation Procedures
-----------------------
-RocketPort/RocketModem PCI cards require no driver configuration, they are
+RocketPort/RocketModem PCI cards require no driver configuration, they are
automatically detected and configured.
-The RocketPort driver can be installed as a module (recommended) or built
+The RocketPort driver can be installed as a module (recommended) or built
into the kernel. This is selected, as for other drivers, through the `make config`
-command from the root of the Linux source tree during the kernel build process.
+command from the root of the Linux source tree during the kernel build process.
The RocketPort/RocketModem serial ports installed by this driver are assigned
-device major number 46, and will be named /dev/ttyRx, where x is the port number
+device major number 46, and will be named /dev/ttyRx, where x is the port number
starting at zero (ex. /dev/ttyR0, /devttyR1, ...). If you have multiple cards
installed in the system, the mapping of port names to serial ports is displayed
in the system log at /var/log/messages.
If installed as a module, the module must be loaded. This can be done
manually by entering "modprobe rocket". To have the module loaded automatically
-upon system boot, edit a /etc/modprobe.d/*.conf file and add the line
+upon system boot, edit a `/etc/modprobe.d/*.conf` file and add the line
"alias char-major-46 rocket".
In order to use the ports, their device names (nodes) must be created with mknod.
-This is only required once, the system will retain the names once created. To
-create the RocketPort/RocketModem device names, use the command
-"mknod /dev/ttyRx c 46 x" where x is the port number starting at zero. For example:
+This is only required once, the system will retain the names once created. To
+create the RocketPort/RocketModem device names, use the command
+"mknod /dev/ttyRx c 46 x" where x is the port number starting at zero.
->mknod /dev/ttyR0 c 46 0
->mknod /dev/ttyR1 c 46 1
->mknod /dev/ttyR2 c 46 2
+For example::
+
+ > mknod /dev/ttyR0 c 46 0
+ > mknod /dev/ttyR1 c 46 1
+ > mknod /dev/ttyR2 c 46 2
The Linux script MAKEDEV will create the first 16 ttyRx device names (nodes)
-for you:
+for you::
->/dev/MAKEDEV ttyR
-
-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
+ >/dev/MAKEDEV ttyR
ISA Rocketport Boards
---------------------
@@ -89,7 +93,7 @@ card before installing and using it. This is done by setting a set of DIP
switches on the Rocketport board.
-SETTING THE I/O ADDRESS
+Setting the I/O address
-----------------------
Before installing RocketPort(R) or RocketPort RA boards, you must find
@@ -130,40 +134,36 @@ the first 4 bytes of that range are used by the first board. You would
need to set the second, third, or fourth board to one of the next available
blocks such as 0x180.
-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
+RocketPort and RocketPort RA SW1 Settings::
-RocketPort and RocketPort RA SW1 Settings:
+ +-------------------------------+
+ | 8 | 7 | 6 | 5 | 4 | 3 | 2 | 1 |
+ +-------+-------+---------------+
+ | Unused| Card | I/O Port Block|
+ +-------------------------------+
- +-------------------------------+
- | 8 | 7 | 6 | 5 | 4 | 3 | 2 | 1 |
- +-------+-------+---------------+
- | Unused| Card | I/O Port Block|
- +-------------------------------+
+ DIP Switches DIP Switches
+ 7 8 6 5
+ =================== ===================
+ On On UNUSED, MUST BE ON. On On First Card <==== Default
+ On Off Second Card
+ Off On Third Card
+ Off Off Fourth Card
-DIP Switches DIP Switches
-7 8 6 5
-=================== ===================
-On On UNUSED, MUST BE ON. On On First Card <==== Default
- On Off Second Card
- Off On Third Card
- Off Off Fourth Card
+ DIP Switches I/O Address Range
+ 4 3 2 1 Used by the First Card
+ =====================================
+ On Off On Off 100-143
+ On Off Off On 140-183
+ On Off Off Off 180-1C3 <==== Default
+ Off On On Off 200-243
+ Off On Off On 240-283
+ Off On Off Off 280-2C3
+ Off Off On Off 300-343
+ Off Off Off On 340-383
+ Off Off Off Off 380-3C3
-DIP Switches I/O Address Range
-4 3 2 1 Used by the First Card
-=====================================
-On Off On Off 100-143
-On Off Off On 140-183
-On Off Off Off 180-1C3 <==== Default
-Off On On Off 200-243
-Off On Off On 240-283
-Off On Off Off 280-2C3
-Off Off On Off 300-343
-Off Off Off On 340-383
-Off Off Off Off 380-3C3
-
-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
-
-REPORTING BUGS
+Reporting Bugs
--------------
For technical support, please provide the following
@@ -171,19 +171,15 @@ information: Driver version, kernel release, distribution of
kernel, and type of board you are using. Error messages and log
printouts port configuration details are especially helpful.
-USA
- Phone: (612) 494-4100
- FAX: (612) 494-4199
- email: support@comtrol.com
+USA:
+ :Phone: (612) 494-4100
+ :FAX: (612) 494-4199
+ :email: support@comtrol.com
-Comtrol Europe
- Phone: +44 (0) 1 869 323-220
- FAX: +44 (0) 1 869 323-211
- email: support@comtrol.co.uk
+Comtrol Europe:
+ :Phone: +44 (0) 1 869 323-220
+ :FAX: +44 (0) 1 869 323-211
+ :email: support@comtrol.co.uk
Web: http://www.comtrol.com
FTP: ftp.comtrol.com
-
-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
-
-
diff --git a/Documentation/serial/serial-iso7816.txt b/Documentation/serial/serial-iso7816.txt
index 3193d24a2b0f..d990143de0c6 100644
--- a/Documentation/serial/serial-iso7816.txt
+++ b/Documentation/serial/serial-iso7816.txt
@@ -1,11 +1,15 @@
- ISO7816 SERIAL COMMUNICATIONS
+=============================
+ISO7816 Serial Communications
+=============================
-1. INTRODUCTION
+1. Introduction
+===============
ISO/IEC7816 is a series of standards specifying integrated circuit cards (ICC)
also known as smart cards.
-2. HARDWARE-RELATED CONSIDERATIONS
+2. Hardware-related considerations
+==================================
Some CPUs/UARTs (e.g., Microchip AT91) contain a built-in mode capable of
handling communication with a smart card.
@@ -15,7 +19,8 @@
available at user-level to allow switching from one mode to the other, and
vice versa.
-3. DATA STRUCTURES ALREADY AVAILABLE IN THE KERNEL
+3. Data Structures Already Available in the Kernel
+==================================================
The Linux kernel provides the serial_iso7816 structure (see [1]) to handle
ISO7816 communications. This data structure is used to set and configure
@@ -27,10 +32,11 @@
to TIOCGISO7816 and TIOCSISO7816 ioctls (see below). The iso7816_config
callback receives a pointer to struct serial_iso7816.
-4. USAGE FROM USER-LEVEL
+4. Usage from user-level
+========================
From user-level, ISO7816 configuration can be get/set using the previous
- ioctls. For instance, to set ISO7816 you can use the following code:
+ ioctls. For instance, to set ISO7816 you can use the following code::
#include <linux/serial.h>
@@ -78,6 +84,7 @@
/* Error handling. See errno. */
}
-5. REFERENCES
+5. References
+=============
[1] include/uapi/linux/serial.h
diff --git a/Documentation/serial/serial-rs485.txt b/Documentation/serial/serial-rs485.txt
index ce0c1a9b8aab..6bc824f948f9 100644
--- a/Documentation/serial/serial-rs485.txt
+++ b/Documentation/serial/serial-rs485.txt
@@ -1,6 +1,9 @@
- RS485 SERIAL COMMUNICATIONS
+===========================
+RS485 Serial Communications
+===========================
-1. INTRODUCTION
+1. Introduction
+===============
EIA-485, also known as TIA/EIA-485 or RS-485, is a standard defining the
electrical characteristics of drivers and receivers for use in balanced
@@ -9,7 +12,8 @@
because it can be used effectively over long distances and in electrically
noisy environments.
-2. HARDWARE-RELATED CONSIDERATIONS
+2. Hardware-related Considerations
+==================================
Some CPUs/UARTs (e.g., Atmel AT91 or 16C950 UART) contain a built-in
half-duplex mode capable of automatically controlling line direction by
@@ -22,7 +26,8 @@
available at user-level to allow switching from one mode to the other, and
vice versa.
-3. DATA STRUCTURES ALREADY AVAILABLE IN THE KERNEL
+3. Data Structures Already Available in the Kernel
+==================================================
The Linux kernel provides the serial_rs485 structure (see [1]) to handle
RS485 communications. This data structure is used to set and configure RS485
@@ -38,10 +43,11 @@
to TIOCSRS485 and TIOCGRS485 ioctls (see below). The rs485_config callback
receives a pointer to struct serial_rs485.
-4. USAGE FROM USER-LEVEL
+4. Usage from user-level
+========================
From user-level, RS485 configuration can be get/set using the previous
- ioctls. For instance, to set RS485 you can use the following code:
+ ioctls. For instance, to set RS485 you can use the following code::
#include <linux/serial.h>
@@ -89,7 +95,9 @@
/* Error handling. See errno. */
}
-5. REFERENCES
+5. References
+=============
[1] include/uapi/linux/serial.h
+
[2] Documentation/devicetree/bindings/serial/rs485.txt
diff --git a/Documentation/serial/tty.txt b/Documentation/serial/tty.txt
index b48780977a68..dd972caacf3e 100644
--- a/Documentation/serial/tty.txt
+++ b/Documentation/serial/tty.txt
@@ -1,5 +1,6 @@
-
- The Lockronomicon
+=================
+The Lockronomicon
+=================
Your guide to the ancient and twisted locking policies of the tty layer and
the warped logic behind them. Beware all ye who read on.
@@ -9,12 +10,12 @@ Line Discipline
---------------
Line disciplines are registered with tty_register_ldisc() passing the
-discipline number and the ldisc structure. At the point of registration the
+discipline number and the ldisc structure. At the point of registration the
discipline must be ready to use and it is possible it will get used before
the call returns success. If the call returns an error then it won't get
called. Do not re-use ldisc numbers as they are part of the userspace ABI
and writing over an existing ldisc will cause demons to eat your computer.
-After the return the ldisc data has been copied so you may free your own
+After the return the ldisc data has been copied so you may free your own
copy of the structure. You must not re-register over the top of the line
discipline even with the same data or your computer again will be eaten by
demons.
@@ -26,7 +27,7 @@ code manages the module counts this should not usually be a concern.
Heed this warning: the reference count field of the registered copies of the
tty_ldisc structure in the ldisc table counts the number of lines using this
-discipline. The reference count of the tty_ldisc structure within a tty
+discipline. The reference count of the tty_ldisc structure within a tty
counts the number of active users of the ldisc at this instant. In effect it
counts the number of threads of execution within an ldisc method (plus those
about to enter and exit although this detail matters not).
@@ -34,9 +35,11 @@ about to enter and exit although this detail matters not).
Line Discipline Methods
-----------------------
-TTY side interfaces:
+TTY side interfaces
+^^^^^^^^^^^^^^^^^^^
-open() - Called when the line discipline is attached to
+======================= =======================================================
+open() Called when the line discipline is attached to
the terminal. No other call into the line
discipline for this tty will occur until it
completes successfully. Should initialize any
@@ -47,66 +50,69 @@ open() - Called when the line discipline is attached to
Returning an error will prevent the ldisc from
being attached. Can sleep.
-close() - This is called on a terminal when the line
+close() This is called on a terminal when the line
discipline is being unplugged. At the point of
execution no further users will enter the
ldisc code for this tty. Can sleep.
-hangup() - Called when the tty line is hung up.
+hangup() Called when the tty line is hung up.
The line discipline should cease I/O to the tty.
No further calls into the ldisc code will occur.
The return value is ignored. Can sleep.
-read() - (optional) A process requests reading data from
+read() (optional) A process requests reading data from
the line. Multiple read calls may occur in parallel
and the ldisc must deal with serialization issues.
If not defined, the process will receive an EIO
error. May sleep.
-write() - (optional) A process requests writing data to the
+write() (optional) A process requests writing data to the
line. Multiple write calls are serialized by the
tty layer for the ldisc. If not defined, the
process will receive an EIO error. May sleep.
-flush_buffer() - (optional) May be called at any point between
+flush_buffer() (optional) May be called at any point between
open and close, and instructs the line discipline
to empty its input buffer.
-set_termios() - (optional) Called on termios structure changes.
+set_termios() (optional) Called on termios structure changes.
The caller passes the old termios data and the
current data is in the tty. Called under the
termios semaphore so allowed to sleep. Serialized
against itself only.
-poll() - (optional) Check the status for the poll/select
+poll() (optional) Check the status for the poll/select
calls. Multiple poll calls may occur in parallel.
May sleep.
-ioctl() - (optional) Called when an ioctl is handed to the
+ioctl() (optional) Called when an ioctl is handed to the
tty layer that might be for the ldisc. Multiple
ioctl calls may occur in parallel. May sleep.
-compat_ioctl() - (optional) Called when a 32 bit ioctl is handed
+compat_ioctl() (optional) Called when a 32 bit ioctl is handed
to the tty layer that might be for the ldisc.
Multiple ioctl calls may occur in parallel.
May sleep.
+======================= =======================================================
-Driver Side Interfaces:
+Driver Side Interfaces
+^^^^^^^^^^^^^^^^^^^^^^
-receive_buf() - (optional) Called by the low-level driver to hand
+======================= =======================================================
+receive_buf() (optional) Called by the low-level driver to hand
a buffer of received bytes to the ldisc for
processing. The number of bytes is guaranteed not
to exceed the current value of tty->receive_room.
All bytes must be processed.
-receive_buf2() - (optional) Called by the low-level driver to hand
+receive_buf2() (optional) Called by the low-level driver to hand
a buffer of received bytes to the ldisc for
processing. Returns the number of bytes processed.
If both receive_buf() and receive_buf2() are
defined, receive_buf2() should be preferred.
-write_wakeup() - May be called at any point between open and close.
+write_wakeup() May be called at any point between open and close.
The TTY_DO_WRITE_WAKEUP flag indicates if a call
is needed but always races versus calls. Thus the
ldisc must be careful about setting order and to
@@ -117,17 +123,20 @@ write_wakeup() - May be called at any point between open and close.
is permitted to call the driver write method from
this function. In such a situation defer it.
-dcd_change() - Report to the tty line the current DCD pin status
+dcd_change() Report to the tty line the current DCD pin status
changes and the relative timestamp. The timestamp
cannot be NULL.
+======================= =======================================================
Driver Access
+^^^^^^^^^^^^^
Line discipline methods can call the following methods of the underlying
hardware driver through the function pointers within the tty->driver
structure:
+======================= =======================================================
write() Write a block of characters to the tty device.
Returns the number of characters accepted. The
character buffer passed to this method is already
@@ -189,13 +198,16 @@ wait_until_sent() Waits until the device has written out all of the
characters in its transmitter FIFO.
send_xchar() Send a high-priority XON/XOFF character to the device.
+======================= =======================================================
Flags
+^^^^^
Line discipline methods have access to tty->flags field containing the
following interesting flags:
+======================= =======================================================
TTY_THROTTLED Driver input is throttled. The ldisc should call
tty->driver->unthrottle() in order to resume
reception when it is ready to process more data.
@@ -212,102 +224,105 @@ TTY_OTHER_CLOSED Device is a pty and the other side has closed.
TTY_NO_WRITE_SPLIT Prevent driver from splitting up writes into
smaller chunks.
+======================= =======================================================
Locking
+^^^^^^^
Callers to the line discipline functions from the tty layer are required to
take line discipline locks. The same is true of calls from the driver side
but not yet enforced.
-Three calls are now provided
+Three calls are now provided::
ldisc = tty_ldisc_ref(tty);
takes a handle to the line discipline in the tty and returns it. If no ldisc
is currently attached or the ldisc is being closed and re-opened at this
point then NULL is returned. While this handle is held the ldisc will not
-change or go away.
+change or go away::
tty_ldisc_deref(ldisc)
Returns the ldisc reference and allows the ldisc to be closed. Returning the
reference takes away your right to call the ldisc functions until you take
-a new reference.
+a new reference::
ldisc = tty_ldisc_ref_wait(tty);
Performs the same function as tty_ldisc_ref except that it will wait for an
-ldisc change to complete and then return a reference to the new ldisc.
+ldisc change to complete and then return a reference to the new ldisc.
While these functions are slightly slower than the old code they should have
minimal impact as most receive logic uses the flip buffers and they only
need to take a reference when they push bits up through the driver.
-A caution: The ldisc->open(), ldisc->close() and driver->set_ldisc
+A caution: The ldisc->open(), ldisc->close() and driver->set_ldisc
functions are called with the ldisc unavailable. Thus tty_ldisc_ref will
fail in this situation if used within these functions. Ldisc and driver
-code calling its own functions must be careful in this case.
+code calling its own functions must be careful in this case.
Driver Interface
----------------
-open() - Called when a device is opened. May sleep
+======================= =======================================================
+open() Called when a device is opened. May sleep
-close() - Called when a device is closed. At the point of
- return from this call the driver must make no
+close() Called when a device is closed. At the point of
+ return from this call the driver must make no
further ldisc calls of any kind. May sleep
-write() - Called to write bytes to the device. May not
- sleep. May occur in parallel in special cases.
+write() Called to write bytes to the device. May not
+ sleep. May occur in parallel in special cases.
Because this includes panic paths drivers generally
shouldn't try and do clever locking here.
-put_char() - Stuff a single character onto the queue. The
+put_char() Stuff a single character onto the queue. The
driver is guaranteed following up calls to
flush_chars.
-flush_chars() - Ask the kernel to write put_char queue
+flush_chars() Ask the kernel to write put_char queue
-write_room() - Return the number of characters that can be stuffed
+write_room() Return the number of characters that can be stuffed
into the port buffers without overflow (or less).
The ldisc is responsible for being intelligent
- about multi-threading of write_room/write calls
+ about multi-threading of write_room/write calls
-ioctl() - Called when an ioctl may be for the driver
+ioctl() Called when an ioctl may be for the driver
-set_termios() - Called on termios change, serialized against
+set_termios() Called on termios change, serialized against
itself by a semaphore. May sleep.
-set_ldisc() - Notifier for discipline change. At the point this
+set_ldisc() Notifier for discipline change. At the point this
is done the discipline is not yet usable. Can now
sleep (I think)
-throttle() - Called by the ldisc to ask the driver to do flow
+throttle() Called by the ldisc to ask the driver to do flow
control. Serialization including with unthrottle
is the job of the ldisc layer.
-unthrottle() - Called by the ldisc to ask the driver to stop flow
+unthrottle() Called by the ldisc to ask the driver to stop flow
control.
-stop() - Ldisc notifier to the driver to stop output. As with
+stop() Ldisc notifier to the driver to stop output. As with
throttle the serializations with start() are down
to the ldisc layer.
-start() - Ldisc notifier to the driver to start output.
+start() Ldisc notifier to the driver to start output.
-hangup() - Ask the tty driver to cause a hangup initiated
+hangup() Ask the tty driver to cause a hangup initiated
from the host side. [Can sleep ??]
-break_ctl() - Send RS232 break. Can sleep. Can get called in
+break_ctl() Send RS232 break. Can sleep. Can get called in
parallel, driver must serialize (for now), and
with write calls.
-wait_until_sent() - Wait for characters to exit the hardware queue
+wait_until_sent() Wait for characters to exit the hardware queue
of the driver. Can sleep
-send_xchar() - Send XON/XOFF and if possible jump the queue with
+send_xchar() Send XON/XOFF and if possible jump the queue with
it in order to get fast flow control responses.
Cannot sleep ??
-
+======================= =======================================================
--
2.20.1
^ permalink raw reply related [flat|nested] 81+ messages in thread* [PATCH 34/57] docs: target: convert it to ReST format
2019-04-16 2:55 [PATCH 00/57] Convert files to ReST Mauro Carvalho Chehab
` (25 preceding siblings ...)
2019-04-16 2:55 ` [PATCH 33/57] docs: serial: convert it to ReST format Mauro Carvalho Chehab
@ 2019-04-16 2:55 ` Mauro Carvalho Chehab
2019-04-16 2:56 ` [PATCH 35/57] docs: timers: convert documentation to ReST Mauro Carvalho Chehab
` (25 subsequent siblings)
52 siblings, 0 replies; 81+ messages in thread
From: Mauro Carvalho Chehab @ 2019-04-16 2:55 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Martin K. Petersen, linux-scsi, target-devel
Convert the TCM docs to ReST format and add them to the
bookset.
This has a mix of userspace-faced and Kernelspace faced
docs. Still, it sounds a better candidate to be added at
the kernel API set of docs.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
Documentation/target/tcm_mod_builder.txt | 200 ++++++++---------
Documentation/target/tcmu-design.txt | 268 ++++++++++++-----------
2 files changed, 248 insertions(+), 220 deletions(-)
diff --git a/Documentation/target/tcm_mod_builder.txt b/Documentation/target/tcm_mod_builder.txt
index ae22f7005540..9bfc9822e2bd 100644
--- a/Documentation/target/tcm_mod_builder.txt
+++ b/Documentation/target/tcm_mod_builder.txt
@@ -1,145 +1,149 @@
->>>>>>>>>> The TCM v4 fabric module script generator <<<<<<<<<<
+=========================================
+The TCM v4 fabric module script generator
+=========================================
Greetings all,
This document is intended to be a mini-HOWTO for using the tcm_mod_builder.py
script to generate a brand new functional TCM v4 fabric .ko module of your very own,
that once built can be immediately be loaded to start access the new TCM/ConfigFS
-fabric skeleton, by simply using:
+fabric skeleton, by simply using::
modprobe $TCM_NEW_MOD
mkdir -p /sys/kernel/config/target/$TCM_NEW_MOD
This script will create a new drivers/target/$TCM_NEW_MOD/, and will do the following
- *) Generate new API callers for drivers/target/target_core_fabric_configs.c logic
+ 1) Generate new API callers for drivers/target/target_core_fabric_configs.c logic
->make_tpg(), ->drop_tpg(), ->make_wwn(), ->drop_wwn(). These are created
into $TCM_NEW_MOD/$TCM_NEW_MOD_configfs.c
- *) Generate basic infrastructure for loading/unloading LKMs and TCM/ConfigFS fabric module
+ 2) Generate basic infrastructure for loading/unloading LKMs and TCM/ConfigFS fabric module
using a skeleton struct target_core_fabric_ops API template.
- *) Based on user defined T10 Proto_Ident for the new fabric module being built,
+ 3) Based on user defined T10 Proto_Ident for the new fabric module being built,
the TransportID / Initiator and Target WWPN related handlers for
SPC-3 persistent reservation are automatically generated in $TCM_NEW_MOD/$TCM_NEW_MOD_fabric.c
using drivers/target/target_core_fabric_lib.c logic.
- *) NOP API calls for all other Data I/O path and fabric dependent attribute logic
+ 4) NOP API calls for all other Data I/O path and fabric dependent attribute logic
in $TCM_NEW_MOD/$TCM_NEW_MOD_fabric.c
tcm_mod_builder.py depends upon the mandatory '-p $PROTO_IDENT' and '-m
-$FABRIC_MOD_name' parameters, and actually running the script looks like:
+$FABRIC_MOD_name' parameters, and actually running the script looks like::
-target:/mnt/sdb/lio-core-2.6.git/Documentation/target# python tcm_mod_builder.py -p iSCSI -m tcm_nab5000
-tcm_dir: /mnt/sdb/lio-core-2.6.git/Documentation/target/../../
-Set fabric_mod_name: tcm_nab5000
-Set fabric_mod_dir:
-/mnt/sdb/lio-core-2.6.git/Documentation/target/../../drivers/target/tcm_nab5000
-Using proto_ident: iSCSI
-Creating fabric_mod_dir:
-/mnt/sdb/lio-core-2.6.git/Documentation/target/../../drivers/target/tcm_nab5000
-Writing file:
-/mnt/sdb/lio-core-2.6.git/Documentation/target/../../drivers/target/tcm_nab5000/tcm_nab5000_base.h
-Using tcm_mod_scan_fabric_ops:
-/mnt/sdb/lio-core-2.6.git/Documentation/target/../../include/target/target_core_fabric_ops.h
-Writing file:
-/mnt/sdb/lio-core-2.6.git/Documentation/target/../../drivers/target/tcm_nab5000/tcm_nab5000_fabric.c
-Writing file:
-/mnt/sdb/lio-core-2.6.git/Documentation/target/../../drivers/target/tcm_nab5000/tcm_nab5000_fabric.h
-Writing file:
-/mnt/sdb/lio-core-2.6.git/Documentation/target/../../drivers/target/tcm_nab5000/tcm_nab5000_configfs.c
-Writing file:
-/mnt/sdb/lio-core-2.6.git/Documentation/target/../../drivers/target/tcm_nab5000/Kbuild
-Writing file:
-/mnt/sdb/lio-core-2.6.git/Documentation/target/../../drivers/target/tcm_nab5000/Kconfig
-Would you like to add tcm_nab5000to drivers/target/Kbuild..? [yes,no]: yes
-Would you like to add tcm_nab5000to drivers/target/Kconfig..? [yes,no]: yes
+ target:/mnt/sdb/lio-core-2.6.git/Documentation/target# python tcm_mod_builder.py -p iSCSI -m tcm_nab5000
+ tcm_dir: /mnt/sdb/lio-core-2.6.git/Documentation/target/../../
+ Set fabric_mod_name: tcm_nab5000
+ Set fabric_mod_dir:
+ /mnt/sdb/lio-core-2.6.git/Documentation/target/../../drivers/target/tcm_nab5000
+ Using proto_ident: iSCSI
+ Creating fabric_mod_dir:
+ /mnt/sdb/lio-core-2.6.git/Documentation/target/../../drivers/target/tcm_nab5000
+ Writing file:
+ /mnt/sdb/lio-core-2.6.git/Documentation/target/../../drivers/target/tcm_nab5000/tcm_nab5000_base.h
+ Using tcm_mod_scan_fabric_ops:
+ /mnt/sdb/lio-core-2.6.git/Documentation/target/../../include/target/target_core_fabric_ops.h
+ Writing file:
+ /mnt/sdb/lio-core-2.6.git/Documentation/target/../../drivers/target/tcm_nab5000/tcm_nab5000_fabric.c
+ Writing file:
+ /mnt/sdb/lio-core-2.6.git/Documentation/target/../../drivers/target/tcm_nab5000/tcm_nab5000_fabric.h
+ Writing file:
+ /mnt/sdb/lio-core-2.6.git/Documentation/target/../../drivers/target/tcm_nab5000/tcm_nab5000_configfs.c
+ Writing file:
+ /mnt/sdb/lio-core-2.6.git/Documentation/target/../../drivers/target/tcm_nab5000/Kbuild
+ Writing file:
+ /mnt/sdb/lio-core-2.6.git/Documentation/target/../../drivers/target/tcm_nab5000/Kconfig
+ Would you like to add tcm_nab5000to drivers/target/Kbuild..? [yes,no]: yes
+ Would you like to add tcm_nab5000to drivers/target/Kconfig..? [yes,no]: yes
At the end of tcm_mod_builder.py. the script will ask to add the following
-line to drivers/target/Kbuild:
+line to drivers/target/Kbuild::
obj-$(CONFIG_TCM_NAB5000) += tcm_nab5000/
-and the same for drivers/target/Kconfig:
+and the same for drivers/target/Kconfig::
source "drivers/target/tcm_nab5000/Kconfig"
-*) Run 'make menuconfig' and select the new CONFIG_TCM_NAB5000 item:
+#) Run 'make menuconfig' and select the new CONFIG_TCM_NAB5000 item::
<M> TCM_NAB5000 fabric module
-*) Build using 'make modules', once completed you will have:
+#) Build using 'make modules', once completed you will have::
-target:/mnt/sdb/lio-core-2.6.git# ls -la drivers/target/tcm_nab5000/
-total 1348
-drwxr-xr-x 2 root root 4096 2010-10-05 03:23 .
-drwxr-xr-x 9 root root 4096 2010-10-05 03:22 ..
--rw-r--r-- 1 root root 282 2010-10-05 03:22 Kbuild
--rw-r--r-- 1 root root 171 2010-10-05 03:22 Kconfig
--rw-r--r-- 1 root root 49 2010-10-05 03:23 modules.order
--rw-r--r-- 1 root root 738 2010-10-05 03:22 tcm_nab5000_base.h
--rw-r--r-- 1 root root 9096 2010-10-05 03:22 tcm_nab5000_configfs.c
--rw-r--r-- 1 root root 191200 2010-10-05 03:23 tcm_nab5000_configfs.o
--rw-r--r-- 1 root root 40504 2010-10-05 03:23 .tcm_nab5000_configfs.o.cmd
--rw-r--r-- 1 root root 5414 2010-10-05 03:22 tcm_nab5000_fabric.c
--rw-r--r-- 1 root root 2016 2010-10-05 03:22 tcm_nab5000_fabric.h
--rw-r--r-- 1 root root 190932 2010-10-05 03:23 tcm_nab5000_fabric.o
--rw-r--r-- 1 root root 40713 2010-10-05 03:23 .tcm_nab5000_fabric.o.cmd
--rw-r--r-- 1 root root 401861 2010-10-05 03:23 tcm_nab5000.ko
--rw-r--r-- 1 root root 265 2010-10-05 03:23 .tcm_nab5000.ko.cmd
--rw-r--r-- 1 root root 459 2010-10-05 03:23 tcm_nab5000.mod.c
--rw-r--r-- 1 root root 23896 2010-10-05 03:23 tcm_nab5000.mod.o
--rw-r--r-- 1 root root 22655 2010-10-05 03:23 .tcm_nab5000.mod.o.cmd
--rw-r--r-- 1 root root 379022 2010-10-05 03:23 tcm_nab5000.o
--rw-r--r-- 1 root root 211 2010-10-05 03:23 .tcm_nab5000.o.cmd
+ target:/mnt/sdb/lio-core-2.6.git# ls -la drivers/target/tcm_nab5000/
+ total 1348
+ drwxr-xr-x 2 root root 4096 2010-10-05 03:23 .
+ drwxr-xr-x 9 root root 4096 2010-10-05 03:22 ..
+ -rw-r--r-- 1 root root 282 2010-10-05 03:22 Kbuild
+ -rw-r--r-- 1 root root 171 2010-10-05 03:22 Kconfig
+ -rw-r--r-- 1 root root 49 2010-10-05 03:23 modules.order
+ -rw-r--r-- 1 root root 738 2010-10-05 03:22 tcm_nab5000_base.h
+ -rw-r--r-- 1 root root 9096 2010-10-05 03:22 tcm_nab5000_configfs.c
+ -rw-r--r-- 1 root root 191200 2010-10-05 03:23 tcm_nab5000_configfs.o
+ -rw-r--r-- 1 root root 40504 2010-10-05 03:23 .tcm_nab5000_configfs.o.cmd
+ -rw-r--r-- 1 root root 5414 2010-10-05 03:22 tcm_nab5000_fabric.c
+ -rw-r--r-- 1 root root 2016 2010-10-05 03:22 tcm_nab5000_fabric.h
+ -rw-r--r-- 1 root root 190932 2010-10-05 03:23 tcm_nab5000_fabric.o
+ -rw-r--r-- 1 root root 40713 2010-10-05 03:23 .tcm_nab5000_fabric.o.cmd
+ -rw-r--r-- 1 root root 401861 2010-10-05 03:23 tcm_nab5000.ko
+ -rw-r--r-- 1 root root 265 2010-10-05 03:23 .tcm_nab5000.ko.cmd
+ -rw-r--r-- 1 root root 459 2010-10-05 03:23 tcm_nab5000.mod.c
+ -rw-r--r-- 1 root root 23896 2010-10-05 03:23 tcm_nab5000.mod.o
+ -rw-r--r-- 1 root root 22655 2010-10-05 03:23 .tcm_nab5000.mod.o.cmd
+ -rw-r--r-- 1 root root 379022 2010-10-05 03:23 tcm_nab5000.o
+ -rw-r--r-- 1 root root 211 2010-10-05 03:23 .tcm_nab5000.o.cmd
-*) Load the new module, create a lun_0 configfs group, and add new TCM Core
- IBLOCK backstore symlink to port:
+#) Load the new module, create a lun_0 configfs group, and add new TCM Core
+ IBLOCK backstore symlink to port::
-target:/mnt/sdb/lio-core-2.6.git# insmod drivers/target/tcm_nab5000.ko
-target:/mnt/sdb/lio-core-2.6.git# mkdir -p /sys/kernel/config/target/nab5000/iqn.foo/tpgt_1/lun/lun_0
-target:/mnt/sdb/lio-core-2.6.git# cd /sys/kernel/config/target/nab5000/iqn.foo/tpgt_1/lun/lun_0/
-target:/sys/kernel/config/target/nab5000/iqn.foo/tpgt_1/lun/lun_0# ln -s /sys/kernel/config/target/core/iblock_0/lvm_test0 nab5000_port
+ target:/mnt/sdb/lio-core-2.6.git# insmod drivers/target/tcm_nab5000.ko
+ target:/mnt/sdb/lio-core-2.6.git# mkdir -p /sys/kernel/config/target/nab5000/iqn.foo/tpgt_1/lun/lun_0
+ target:/mnt/sdb/lio-core-2.6.git# cd /sys/kernel/config/target/nab5000/iqn.foo/tpgt_1/lun/lun_0/
+ target:/sys/kernel/config/target/nab5000/iqn.foo/tpgt_1/lun/lun_0# ln -s /sys/kernel/config/target/core/iblock_0/lvm_test0 nab5000_port
-target:/sys/kernel/config/target/nab5000/iqn.foo/tpgt_1/lun/lun_0# cd -
-target:/mnt/sdb/lio-core-2.6.git# tree /sys/kernel/config/target/nab5000/
-/sys/kernel/config/target/nab5000/
-|-- discovery_auth
-|-- iqn.foo
-| `-- tpgt_1
-| |-- acls
-| |-- attrib
-| |-- lun
-| | `-- lun_0
-| | |-- alua_tg_pt_gp
-| | |-- alua_tg_pt_offline
-| | |-- alua_tg_pt_status
-| | |-- alua_tg_pt_write_md
-| | `-- nab5000_port -> ../../../../../../target/core/iblock_0/lvm_test0
-| |-- np
-| `-- param
-`-- version
+ target:/sys/kernel/config/target/nab5000/iqn.foo/tpgt_1/lun/lun_0# cd -
+ target:/mnt/sdb/lio-core-2.6.git# tree /sys/kernel/config/target/nab5000/
+ /sys/kernel/config/target/nab5000/
+ |-- discovery_auth
+ |-- iqn.foo
+ | `-- tpgt_1
+ | |-- acls
+ | |-- attrib
+ | |-- lun
+ | | `-- lun_0
+ | | |-- alua_tg_pt_gp
+ | | |-- alua_tg_pt_offline
+ | | |-- alua_tg_pt_status
+ | | |-- alua_tg_pt_write_md
+ | | `-- nab5000_port -> ../../../../../../target/core/iblock_0/lvm_test0
+ | |-- np
+ | `-- param
+ `-- version
-target:/mnt/sdb/lio-core-2.6.git# lsmod
-Module Size Used by
-tcm_nab5000 3935 4
-iscsi_target_mod 193211 0
-target_core_stgt 8090 0
-target_core_pscsi 11122 1
-target_core_file 9172 2
-target_core_iblock 9280 1
-target_core_mod 228575 31
-tcm_nab5000,iscsi_target_mod,target_core_stgt,target_core_pscsi,target_core_file,target_core_iblock
-libfc 73681 0
-scsi_debug 56265 0
-scsi_tgt 8666 1 target_core_stgt
-configfs 20644 2 target_core_mod
+ target:/mnt/sdb/lio-core-2.6.git# lsmod
+ Module Size Used by
+ tcm_nab5000 3935 4
+ iscsi_target_mod 193211 0
+ target_core_stgt 8090 0
+ target_core_pscsi 11122 1
+ target_core_file 9172 2
+ target_core_iblock 9280 1
+ target_core_mod 228575 31
+ tcm_nab5000,iscsi_target_mod,target_core_stgt,target_core_pscsi,target_core_file,target_core_iblock
+ libfc 73681 0
+ scsi_debug 56265 0
+ scsi_tgt 8666 1 target_core_stgt
+ configfs 20644 2 target_core_mod
----------------------------------------------------------------------
-Future TODO items:
+Future TODO items
+=================
- *) Add more T10 proto_idents
- *) Make tcm_mod_dump_fabric_ops() smarter and generate function pointer
+ 1) Add more T10 proto_idents
+ 2) Make tcm_mod_dump_fabric_ops() smarter and generate function pointer
defs directly from include/target/target_core_fabric_ops.h:struct target_core_fabric_ops
structure members.
October 5th, 2010
+
Nicholas A. Bellinger <nab@linux-iscsi.org>
diff --git a/Documentation/target/tcmu-design.txt b/Documentation/target/tcmu-design.txt
index 4cebc1ebf99a..a7b426707bf6 100644
--- a/Documentation/target/tcmu-design.txt
+++ b/Documentation/target/tcmu-design.txt
@@ -1,25 +1,30 @@
-Contents:
+====================
+TCM Userspace Design
+====================
+
+
+.. Contents:
-1) TCM Userspace Design
- a) Background
- b) Benefits
- c) Design constraints
- d) Implementation overview
- i. Mailbox
- ii. Command ring
- iii. Data Area
- e) Device discovery
- f) Device events
- g) Other contingencies
-2) Writing a user pass-through handler
- a) Discovering and configuring TCMU uio devices
- b) Waiting for events on the device(s)
- c) Managing the command ring
-3) A final note
+ 1) TCM Userspace Design
+ a) Background
+ b) Benefits
+ c) Design constraints
+ d) Implementation overview
+ i. Mailbox
+ ii. Command ring
+ iii. Data Area
+ e) Device discovery
+ f) Device events
+ g) Other contingencies
+ 2) Writing a user pass-through handler
+ a) Discovering and configuring TCMU uio devices
+ b) Waiting for events on the device(s)
+ c) Managing the command ring
+ 3) A final note
TCM Userspace Design
---------------------
+====================
TCM is another name for LIO, an in-kernel iSCSI target (server).
Existing TCM targets run in the kernel. TCMU (TCM in Userspace)
@@ -32,7 +37,8 @@ modules for file, block device, RAM or using another SCSI device as
storage. These are called "backstores" or "storage engines". These
built-in modules are implemented entirely as kernel code.
-Background:
+Background
+----------
In addition to modularizing the transport protocol used for carrying
SCSI commands ("fabrics"), the Linux kernel target, LIO, also modularizes
@@ -60,7 +66,8 @@ kernel, another approach is to create a userspace pass-through
backstore for LIO, "TCMU".
-Benefits:
+Benefits
+--------
In addition to allowing relatively easy support for RBD and GLFS, TCMU
will also allow easier development of new backstores. TCMU combines
@@ -72,21 +79,25 @@ The disadvantage is there are more distinct components to configure, and
potentially to malfunction. This is unavoidable, but hopefully not
fatal if we're careful to keep things as simple as possible.
-Design constraints:
+Design constraints
+------------------
- Good performance: high throughput, low latency
- Cleanly handle if userspace:
+
1) never attaches
2) hangs
3) dies
4) misbehaves
+
- Allow future flexibility in user & kernel implementations
- Be reasonably memory-efficient
- Simple to configure & run
- Simple to write a userspace backend
-Implementation overview:
+Implementation overview
+-----------------------
The core of the TCMU interface is a memory region that is shared
between kernel and userspace. Within this region is: a control area
@@ -108,7 +119,8 @@ the region mapped at a different virtual address.
See target_core_user.h for the struct definitions.
-The Mailbox:
+The Mailbox
+-----------
The mailbox is always at the start of the shared memory region, and
contains a version, details about the starting offset and size of the
@@ -117,19 +129,27 @@ userspace (respectively) to put commands on the ring, and indicate
when the commands are completed.
version - 1 (userspace should abort if otherwise)
+
flags:
-- TCMU_MAILBOX_FLAG_CAP_OOOC: indicates out-of-order completion is
- supported. See "The Command Ring" for details.
-cmdr_off - The offset of the start of the command ring from the start
-of the memory region, to account for the mailbox size.
-cmdr_size - The size of the command ring. This does *not* need to be a
-power of two.
-cmd_head - Modified by the kernel to indicate when a command has been
-placed on the ring.
-cmd_tail - Modified by userspace to indicate when it has completed
-processing of a command.
+ - TCMU_MAILBOX_FLAG_CAP_OOOC:
+ indicates out-of-order completion is supported.
+ See "The Command Ring" for details.
-The Command Ring:
+cmdr_off
+ The offset of the start of the command ring from the start
+ of the memory region, to account for the mailbox size.
+cmdr_size
+ The size of the command ring. This does *not* need to be a
+ power of two.
+cmd_head
+ Modified by the kernel to indicate when a command has been
+ placed on the ring.
+cmd_tail
+ Modified by userspace to indicate when it has completed
+ processing of a command.
+
+The Command Ring
+----------------
Commands are placed on the ring by the kernel incrementing
mailbox.cmd_head by the size of the command, modulo cmdr_size, and
@@ -180,29 +200,31 @@ opcode it does not handle, it must set UNKNOWN_OP bit (bit 0) in
hdr.uflags, update cmd_tail, and proceed with processing additional
commands, if any.
-The Data Area:
+The Data Area
+-------------
This is shared-memory space after the command ring. The organization
of this area is not defined in the TCMU interface, and userspace
should access only the parts referenced by pending iovs.
-Device Discovery:
+Device Discovery
+----------------
Other devices may be using UIO besides TCMU. Unrelated user processes
may also be handling different sets of TCMU devices. TCMU userspace
processes must find their devices by scanning sysfs
class/uio/uio*/name. For TCMU devices, these names will be of the
-format:
+format::
-tcm-user/<hba_num>/<device_name>/<subtype>/<path>
+ tcm-user/<hba_num>/<device_name>/<subtype>/<path>
where "tcm-user" is common for all TCMU-backed UIO devices. <hba_num>
and <device_name> allow userspace to find the device's path in the
kernel target's configfs tree. Assuming the usual mount point, it is
-found at:
+found at::
-/sys/kernel/config/target/core/user_<hba_num>/<device_name>
+ /sys/kernel/config/target/core/user_<hba_num>/<device_name>
This location contains attributes such as "hw_block_size", that
userspace needs to know for correct operation.
@@ -214,15 +236,16 @@ configure the device, if needed. The name cannot contain ':', due to
LIO limitations.
For all devices so discovered, the user handler opens /dev/uioX and
-calls mmap():
+calls mmap()::
-mmap(NULL, size, PROT_READ|PROT_WRITE, MAP_SHARED, fd, 0)
+ mmap(NULL, size, PROT_READ|PROT_WRITE, MAP_SHARED, fd, 0)
where size must be equal to the value read from
/sys/class/uio/uioX/maps/map0/size.
-Device Events:
+Device Events
+-------------
If a new device is added or removed, a notification will be broadcast
over netlink, using a generic netlink family name of "TCM-USER" and a
@@ -233,7 +256,8 @@ the LIO device, so that after determining the device is supported
(based on subtype) it can take the appropriate action.
-Other contingencies:
+Other contingencies
+-------------------
Userspace handler process never attaches:
@@ -258,7 +282,7 @@ Userspace handler process is malicious:
Writing a user pass-through handler (with example code)
--------------------------------------------------------
+=======================================================
A user process handing a TCMU device must support the following:
@@ -277,103 +301,103 @@ TCMU is designed so that multiple unrelated processes can manage TCMU
devices separately. All handlers should make sure to only open their
devices, based opon a known subtype string.
-a) Discovering and configuring TCMU UIO devices:
+a) Discovering and configuring TCMU UIO devices::
-(error checking omitted for brevity)
+ /* error checking omitted for brevity */
-int fd, dev_fd;
-char buf[256];
-unsigned long long map_len;
-void *map;
+ int fd, dev_fd;
+ char buf[256];
+ unsigned long long map_len;
+ void *map;
-fd = open("/sys/class/uio/uio0/name", O_RDONLY);
-ret = read(fd, buf, sizeof(buf));
-close(fd);
-buf[ret-1] = '\0'; /* null-terminate and chop off the \n */
+ fd = open("/sys/class/uio/uio0/name", O_RDONLY);
+ ret = read(fd, buf, sizeof(buf));
+ close(fd);
+ buf[ret-1] = '\0'; /* null-terminate and chop off the \n */
-/* we only want uio devices whose name is a format we expect */
-if (strncmp(buf, "tcm-user", 8))
+ /* we only want uio devices whose name is a format we expect */
+ if (strncmp(buf, "tcm-user", 8))
exit(-1);
-/* Further checking for subtype also needed here */
+ /* Further checking for subtype also needed here */
-fd = open(/sys/class/uio/%s/maps/map0/size, O_RDONLY);
-ret = read(fd, buf, sizeof(buf));
-close(fd);
-str_buf[ret-1] = '\0'; /* null-terminate and chop off the \n */
+ fd = open(/sys/class/uio/%s/maps/map0/size, O_RDONLY);
+ ret = read(fd, buf, sizeof(buf));
+ close(fd);
+ str_buf[ret-1] = '\0'; /* null-terminate and chop off the \n */
-map_len = strtoull(buf, NULL, 0);
+ map_len = strtoull(buf, NULL, 0);
-dev_fd = open("/dev/uio0", O_RDWR);
-map = mmap(NULL, map_len, PROT_READ|PROT_WRITE, MAP_SHARED, dev_fd, 0);
+ dev_fd = open("/dev/uio0", O_RDWR);
+ map = mmap(NULL, map_len, PROT_READ|PROT_WRITE, MAP_SHARED, dev_fd, 0);
-b) Waiting for events on the device(s)
+ b) Waiting for events on the device(s)
-while (1) {
- char buf[4];
+ while (1) {
+ char buf[4];
- int ret = read(dev_fd, buf, 4); /* will block */
+ int ret = read(dev_fd, buf, 4); /* will block */
- handle_device_events(dev_fd, map);
-}
-
-
-c) Managing the command ring
-
-#include <linux/target_core_user.h>
-
-int handle_device_events(int fd, void *map)
-{
- struct tcmu_mailbox *mb = map;
- struct tcmu_cmd_entry *ent = (void *) mb + mb->cmdr_off + mb->cmd_tail;
- int did_some_work = 0;
-
- /* Process events from cmd ring until we catch up with cmd_head */
- while (ent != (void *)mb + mb->cmdr_off + mb->cmd_head) {
-
- if (tcmu_hdr_get_op(ent->hdr.len_op) == TCMU_OP_CMD) {
- uint8_t *cdb = (void *)mb + ent->req.cdb_off;
- bool success = true;
+ handle_device_events(dev_fd, map);
+ }
- /* Handle command here. */
- printf("SCSI opcode: 0x%x\n", cdb[0]);
- /* Set response fields */
- if (success)
- ent->rsp.scsi_status = SCSI_NO_SENSE;
- else {
- /* Also fill in rsp->sense_buffer here */
- ent->rsp.scsi_status = SCSI_CHECK_CONDITION;
+c) Managing the command ring::
+
+ #include <linux/target_core_user.h>
+
+ int handle_device_events(int fd, void *map)
+ {
+ struct tcmu_mailbox *mb = map;
+ struct tcmu_cmd_entry *ent = (void *) mb + mb->cmdr_off + mb->cmd_tail;
+ int did_some_work = 0;
+
+ /* Process events from cmd ring until we catch up with cmd_head */
+ while (ent != (void *)mb + mb->cmdr_off + mb->cmd_head) {
+
+ if (tcmu_hdr_get_op(ent->hdr.len_op) == TCMU_OP_CMD) {
+ uint8_t *cdb = (void *)mb + ent->req.cdb_off;
+ bool success = true;
+
+ /* Handle command here. */
+ printf("SCSI opcode: 0x%x\n", cdb[0]);
+
+ /* Set response fields */
+ if (success)
+ ent->rsp.scsi_status = SCSI_NO_SENSE;
+ else {
+ /* Also fill in rsp->sense_buffer here */
+ ent->rsp.scsi_status = SCSI_CHECK_CONDITION;
+ }
+ }
+ else if (tcmu_hdr_get_op(ent->hdr.len_op) != TCMU_OP_PAD) {
+ /* Tell the kernel we didn't handle unknown opcodes */
+ ent->hdr.uflags |= TCMU_UFLAG_UNKNOWN_OP;
+ }
+ else {
+ /* Do nothing for PAD entries except update cmd_tail */
+ }
+
+ /* update cmd_tail */
+ mb->cmd_tail = (mb->cmd_tail + tcmu_hdr_get_len(&ent->hdr)) % mb->cmdr_size;
+ ent = (void *) mb + mb->cmdr_off + mb->cmd_tail;
+ did_some_work = 1;
+ }
+
+ /* Notify the kernel that work has been finished */
+ if (did_some_work) {
+ uint32_t buf = 0;
+
+ write(fd, &buf, 4);
+ }
+
+ return 0;
}
- }
- else if (tcmu_hdr_get_op(ent->hdr.len_op) != TCMU_OP_PAD) {
- /* Tell the kernel we didn't handle unknown opcodes */
- ent->hdr.uflags |= TCMU_UFLAG_UNKNOWN_OP;
- }
- else {
- /* Do nothing for PAD entries except update cmd_tail */
- }
-
- /* update cmd_tail */
- mb->cmd_tail = (mb->cmd_tail + tcmu_hdr_get_len(&ent->hdr)) % mb->cmdr_size;
- ent = (void *) mb + mb->cmdr_off + mb->cmd_tail;
- did_some_work = 1;
- }
-
- /* Notify the kernel that work has been finished */
- if (did_some_work) {
- uint32_t buf = 0;
-
- write(fd, &buf, 4);
- }
-
- return 0;
-}
A final note
-------------
+============
Please be careful to return codes as defined by the SCSI
specifications. These are different than some values defined in the
--
2.20.1
^ permalink raw reply related [flat|nested] 81+ messages in thread* [PATCH 35/57] docs: timers: convert documentation to ReST
2019-04-16 2:55 [PATCH 00/57] Convert files to ReST Mauro Carvalho Chehab
` (26 preceding siblings ...)
2019-04-16 2:55 ` [PATCH 34/57] docs: target: " Mauro Carvalho Chehab
@ 2019-04-16 2:56 ` Mauro Carvalho Chehab
2019-04-16 2:56 ` [PATCH 37/57] docs: watchdog: convert documents to ReST format Mauro Carvalho Chehab
` (24 subsequent siblings)
52 siblings, 0 replies; 81+ messages in thread
From: Mauro Carvalho Chehab @ 2019-04-16 2:56 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Thomas Gleixner
The conversion here is really trivial: just a bunch of title
markups and very few puntual changes is enough to make it to
be parsed by Sphinx and generate a nice html.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
Documentation/timers/NO_HZ.txt | 40 ++++++++++++++++-----------
Documentation/timers/highres.txt | 11 ++++----
Documentation/timers/hpet.txt | 4 ++-
Documentation/timers/hrtimers.txt | 6 ++--
Documentation/timers/timekeeping.txt | 3 +-
Documentation/timers/timers-howto.txt | 15 +++++++---
6 files changed, 49 insertions(+), 30 deletions(-)
diff --git a/Documentation/timers/NO_HZ.txt b/Documentation/timers/NO_HZ.txt
index 9591092da5e0..065db217cb04 100644
--- a/Documentation/timers/NO_HZ.txt
+++ b/Documentation/timers/NO_HZ.txt
@@ -1,4 +1,6 @@
- NO_HZ: Reducing Scheduling-Clock Ticks
+======================================
+NO_HZ: Reducing Scheduling-Clock Ticks
+======================================
This document describes Kconfig options and boot parameters that can
@@ -28,7 +30,8 @@ by a third section on RCU-specific considerations, a fourth section
discussing testing, and a fifth and final section listing known issues.
-NEVER OMIT SCHEDULING-CLOCK TICKS
+Never Omit Scheduling-Clock Ticks
+=================================
Very old versions of Linux from the 1990s and the very early 2000s
are incapable of omitting scheduling-clock ticks. It turns out that
@@ -59,7 +62,8 @@ degrade your applications performance. If this describes your workload,
you should read the following two sections.
-OMIT SCHEDULING-CLOCK TICKS FOR IDLE CPUs
+Omit Scheduling-Clock Ticks For Idle CPUs
+=========================================
If a CPU is idle, there is little point in sending it a scheduling-clock
interrupt. After all, the primary purpose of a scheduling-clock interrupt
@@ -97,7 +101,8 @@ By default, CONFIG_NO_HZ_IDLE=y kernels boot with "nohz=on", enabling
dyntick-idle mode.
-OMIT SCHEDULING-CLOCK TICKS FOR CPUs WITH ONLY ONE RUNNABLE TASK
+Omit Scheduling-Clock Ticks For CPUs With Only One Runnable Task
+================================================================
If a CPU has only one runnable task, there is little point in sending it
a scheduling-clock interrupt because there is no other task to switch to.
@@ -174,7 +179,8 @@ However, the drawbacks listed above mean that adaptive ticks should not
(yet) be enabled by default.
-RCU IMPLICATIONS
+RCU Implications
+================
There are situations in which idle CPUs cannot be permitted to
enter either dyntick-idle mode or adaptive-tick mode, the most
@@ -199,7 +205,8 @@ scheduler will decide where to run them, which might or might not be
where you want them to run.
-TESTING
+Testing
+=======
So you enable all the OS-jitter features described in this document,
but do not see any change in your workload's behavior. Is this because
@@ -222,9 +229,10 @@ We do not currently have a good way to remove OS jitter from single-CPU
systems.
-KNOWN ISSUES
+Known Issues
+============
-o Dyntick-idle slows transitions to and from idle slightly.
+* Dyntick-idle slows transitions to and from idle slightly.
In practice, this has not been a problem except for the most
aggressive real-time workloads, which have the option of disabling
dyntick-idle mode, an option that most of them take. However,
@@ -248,13 +256,13 @@ o Dyntick-idle slows transitions to and from idle slightly.
this parameter effectively disables Turbo Mode on Intel
CPUs, which can significantly reduce maximum performance.
-o Adaptive-ticks slows user/kernel transitions slightly.
+* Adaptive-ticks slows user/kernel transitions slightly.
This is not expected to be a problem for computationally intensive
workloads, which have few such transitions. Careful benchmarking
will be required to determine whether or not other workloads
are significantly affected by this effect.
-o Adaptive-ticks does not do anything unless there is only one
+* Adaptive-ticks does not do anything unless there is only one
runnable task for a given CPU, even though there are a number
of other situations where the scheduling-clock tick is not
needed. To give but one example, consider a CPU that has one
@@ -275,7 +283,7 @@ o Adaptive-ticks does not do anything unless there is only one
Better handling of these sorts of situations is future work.
-o A reboot is required to reconfigure both adaptive idle and RCU
+* A reboot is required to reconfigure both adaptive idle and RCU
callback offloading. Runtime reconfiguration could be provided
if needed, however, due to the complexity of reconfiguring RCU at
runtime, there would need to be an earthshakingly good reason.
@@ -283,12 +291,12 @@ o A reboot is required to reconfigure both adaptive idle and RCU
simply offloading RCU callbacks from all CPUs and pinning them
where you want them whenever you want them pinned.
-o Additional configuration is required to deal with other sources
+* Additional configuration is required to deal with other sources
of OS jitter, including interrupts and system-utility tasks
and processes. This configuration normally involves binding
interrupts and tasks to particular CPUs.
-o Some sources of OS jitter can currently be eliminated only by
+* Some sources of OS jitter can currently be eliminated only by
constraining the workload. For example, the only way to eliminate
OS jitter due to global TLB shootdowns is to avoid the unmapping
operations (such as kernel module unload operations) that
@@ -299,17 +307,17 @@ o Some sources of OS jitter can currently be eliminated only by
helpful, especially when combined with the mlock() and mlockall()
system calls.
-o Unless all CPUs are idle, at least one CPU must keep the
+* Unless all CPUs are idle, at least one CPU must keep the
scheduling-clock interrupt going in order to support accurate
timekeeping.
-o If there might potentially be some adaptive-ticks CPUs, there
+* If there might potentially be some adaptive-ticks CPUs, there
will be at least one CPU keeping the scheduling-clock interrupt
going, even if all CPUs are otherwise idle.
Better handling of this situation is ongoing work.
-o Some process-handling operations still require the occasional
+* Some process-handling operations still require the occasional
scheduling-clock tick. These operations include calculating CPU
load, maintaining sched average, computing CFS entity vruntime,
computing avenrun, and carrying out load balancing. They are
diff --git a/Documentation/timers/highres.txt b/Documentation/timers/highres.txt
index 8f9741592123..f93528e6f1c8 100644
--- a/Documentation/timers/highres.txt
+++ b/Documentation/timers/highres.txt
@@ -1,5 +1,6 @@
+=====================================================
High resolution timers and dynamic ticks design notes
------------------------------------------------------
+=====================================================
Further information can be found in the paper of the OLS 2006 talk "hrtimers
and beyond". The paper is part of the OLS 2006 Proceedings Volume 1, which can
@@ -35,6 +36,7 @@ also figure #2 (OLS slides p. 15)
The main differences to the timer wheel, which holds the armed timer_list type
timers are:
+
- time ordered enqueueing into a rb-tree
- independent of ticks (the processing is based on nanoseconds)
@@ -55,7 +57,8 @@ merged into the 2.6.18 kernel.
Further information about the Generic Time Of Day framework is available in the
OLS 2005 Proceedings Volume 1:
-http://www.linuxsymposium.org/2005/linuxsymposium_procv1.pdf
+
+ http://www.linuxsymposium.org/2005/linuxsymposium_procv1.pdf
The paper "We Are Not Getting Any Younger: A New Approach to Time and
Timers" was written by J. Stultz, D.V. Hart, & N. Aravamudan.
@@ -100,6 +103,7 @@ accounting, profiling, and high resolution timers.
The management layer assigns one or more of the following functions to a clock
event device:
+
- system global periodic tick (jiffies update)
- cpu local update_process_times
- cpu local profiling
@@ -244,6 +248,3 @@ extended to x86_64 and ARM already. Initial (work in progress) support is also
available for MIPS and PowerPC.
Thomas, Ingo
-
-
-
diff --git a/Documentation/timers/hpet.txt b/Documentation/timers/hpet.txt
index 895345ec513b..c9d05d3caaca 100644
--- a/Documentation/timers/hpet.txt
+++ b/Documentation/timers/hpet.txt
@@ -1,4 +1,6 @@
- High Precision Event Timer Driver for Linux
+===========================================
+High Precision Event Timer Driver for Linux
+===========================================
The High Precision Event Timer (HPET) hardware follows a specification
by Intel and Microsoft, revision 1.
diff --git a/Documentation/timers/hrtimers.txt b/Documentation/timers/hrtimers.txt
index 588d85724f10..c1c20a693e8f 100644
--- a/Documentation/timers/hrtimers.txt
+++ b/Documentation/timers/hrtimers.txt
@@ -1,6 +1,6 @@
-
+======================================================
hrtimers - subsystem for high-resolution kernel timers
-----------------------------------------------------
+======================================================
This patch introduces a new subsystem for high-resolution kernel timers.
@@ -146,7 +146,7 @@ the clock_getres() interface. This will return whatever real resolution
a given clock has - be it low-res, high-res, or artificially-low-res.
hrtimers - testing and verification
-----------------------------------
+-----------------------------------
We used the high-resolution clock subsystem ontop of hrtimers to verify
the hrtimer implementation details in praxis, and we also ran the posix
diff --git a/Documentation/timers/timekeeping.txt b/Documentation/timers/timekeeping.txt
index 2d1732b0a868..f83e98852e2c 100644
--- a/Documentation/timers/timekeeping.txt
+++ b/Documentation/timers/timekeeping.txt
@@ -1,5 +1,6 @@
+===========================================================
Clock sources, Clock events, sched_clock() and delay timers
------------------------------------------------------------
+===========================================================
This document tries to briefly explain some basic kernel timekeeping
abstractions. It partly pertains to the drivers usually found in
diff --git a/Documentation/timers/timers-howto.txt b/Documentation/timers/timers-howto.txt
index 038f8c77a076..7e3167bec2b1 100644
--- a/Documentation/timers/timers-howto.txt
+++ b/Documentation/timers/timers-howto.txt
@@ -1,5 +1,6 @@
+===================================================================
delays - Information on the various kernel delay / sleep mechanisms
--------------------------------------------------------------------
+===================================================================
This document seeks to answer the common question: "What is the
RightWay (TM) to insert a delay?"
@@ -17,7 +18,7 @@ code in an atomic context?" This should be followed closely by "Does
it really need to delay in atomic context?" If so...
ATOMIC CONTEXT:
- You must use the *delay family of functions. These
+ You must use the `*delay` family of functions. These
functions use the jiffie estimation of clock speed
and will busy wait for enough loop cycles to achieve
the desired delay:
@@ -35,21 +36,26 @@ ATOMIC CONTEXT:
be refactored to allow for the use of msleep.
NON-ATOMIC CONTEXT:
- You should use the *sleep[_range] family of functions.
+ You should use the `*sleep[_range]` family of functions.
There are a few more options here, while any of them may
work correctly, using the "right" sleep function will
help the scheduler, power management, and just make your
driver better :)
-- Backed by busy-wait loop:
+
udelay(unsigned long usecs)
+
-- Backed by hrtimers:
+
usleep_range(unsigned long min, unsigned long max)
+
-- Backed by jiffies / legacy_timers
+
msleep(unsigned long msecs)
msleep_interruptible(unsigned long msecs)
- Unlike the *delay family, the underlying mechanism
+ Unlike the `*delay` family, the underlying mechanism
driving each of these calls varies, thus there are
quirks you should be aware of.
@@ -70,6 +76,7 @@ NON-ATOMIC CONTEXT:
- Why not msleep for (1ms - 20ms)?
Explained originally here:
http://lkml.org/lkml/2007/8/3/250
+
msleep(1~20) may not do what the caller intends, and
will often sleep longer (~20 ms actual sleep for any
value given in the 1~20ms range). In many cases this
--
2.20.1
^ permalink raw reply related [flat|nested] 81+ messages in thread* [PATCH 37/57] docs: watchdog: convert documents to ReST format
2019-04-16 2:55 [PATCH 00/57] Convert files to ReST Mauro Carvalho Chehab
` (27 preceding siblings ...)
2019-04-16 2:56 ` [PATCH 35/57] docs: timers: convert documentation to ReST Mauro Carvalho Chehab
@ 2019-04-16 2:56 ` Mauro Carvalho Chehab
2019-04-17 17:53 ` Guenter Roeck
2019-04-16 2:56 ` [PATCH 39/57] docs: xilinx: convert eemi.txt to ReST Mauro Carvalho Chehab
` (23 subsequent siblings)
52 siblings, 1 reply; 81+ messages in thread
From: Mauro Carvalho Chehab @ 2019-04-16 2:56 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Wim Van Sebroeck, Guenter Roeck, linux-watchdog
Convert those documents and prepare them to be part of the kernel
API book, as most of the stuff there are related to the
Kernel interfaces.
Still, in the future, it would make sense to split the docs,
as some of the stuff is clearly focused on sysadmin tasks.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
.../convert_drivers_to_kernel_api.txt | 109 +--
Documentation/watchdog/hpwdt.txt | 23 +-
Documentation/watchdog/mlx-wdt.txt | 24 +-
Documentation/watchdog/pcwd-watchdog.txt | 13 +-
Documentation/watchdog/watchdog-api.txt | 76 +-
.../watchdog/watchdog-kernel-api.txt | 89 ++-
.../watchdog/watchdog-parameters.txt | 672 +++++++++++++-----
Documentation/watchdog/watchdog-pm.txt | 3 +
Documentation/watchdog/wdt.txt | 31 +-
9 files changed, 733 insertions(+), 307 deletions(-)
diff --git a/Documentation/watchdog/convert_drivers_to_kernel_api.txt b/Documentation/watchdog/convert_drivers_to_kernel_api.txt
index 9fffb2958d13..dd934cc08e40 100644
--- a/Documentation/watchdog/convert_drivers_to_kernel_api.txt
+++ b/Documentation/watchdog/convert_drivers_to_kernel_api.txt
@@ -1,6 +1,8 @@
+=========================================================
Converting old watchdog drivers to the watchdog framework
+=========================================================
+
by Wolfram Sang <w.sang@pengutronix.de>
-=========================================================
Before the watchdog framework came into the kernel, every driver had to
implement the API on its own. Now, as the framework factored out the common
@@ -69,16 +71,16 @@ Here is a overview of the functions and probably needed actions:
-ENOIOCTLCMD, the IOCTLs of the framework will be tried, too. Any other error
is directly given to the user.
-Example conversion:
+Example conversion::
--static const struct file_operations s3c2410wdt_fops = {
-- .owner = THIS_MODULE,
-- .llseek = no_llseek,
-- .write = s3c2410wdt_write,
-- .unlocked_ioctl = s3c2410wdt_ioctl,
-- .open = s3c2410wdt_open,
-- .release = s3c2410wdt_release,
--};
+ -static const struct file_operations s3c2410wdt_fops = {
+ - .owner = THIS_MODULE,
+ - .llseek = no_llseek,
+ - .write = s3c2410wdt_write,
+ - .unlocked_ioctl = s3c2410wdt_ioctl,
+ - .open = s3c2410wdt_open,
+ - .release = s3c2410wdt_release,
+ -};
Check the functions for device-specific stuff and keep it for later
refactoring. The rest can go.
@@ -89,24 +91,24 @@ Remove the miscdevice
Since the file_operations are gone now, you can also remove the 'struct
miscdevice'. The framework will create it on watchdog_dev_register() called by
-watchdog_register_device().
+watchdog_register_device()::
--static struct miscdevice s3c2410wdt_miscdev = {
-- .minor = WATCHDOG_MINOR,
-- .name = "watchdog",
-- .fops = &s3c2410wdt_fops,
--};
+ -static struct miscdevice s3c2410wdt_miscdev = {
+ - .minor = WATCHDOG_MINOR,
+ - .name = "watchdog",
+ - .fops = &s3c2410wdt_fops,
+ -};
Remove obsolete includes and defines
------------------------------------
Because of the simplifications, a few defines are probably unused now. Remove
-them. Includes can be removed, too. For example:
+them. Includes can be removed, too. For example::
-- #include <linux/fs.h>
-- #include <linux/miscdevice.h> (if MODULE_ALIAS_MISCDEV is not used)
-- #include <linux/uaccess.h> (if no custom IOCTLs are used)
+ - #include <linux/fs.h>
+ - #include <linux/miscdevice.h> (if MODULE_ALIAS_MISCDEV is not used)
+ - #include <linux/uaccess.h> (if no custom IOCTLs are used)
Add the watchdog operations
@@ -121,30 +123,30 @@ change the function header. Other changes are most likely not needed, because
here simply happens the direct hardware access. If you have device-specific
code left from the above steps, it should be refactored into these callbacks.
-Here is a simple example:
+Here is a simple example::
-+static struct watchdog_ops s3c2410wdt_ops = {
-+ .owner = THIS_MODULE,
-+ .start = s3c2410wdt_start,
-+ .stop = s3c2410wdt_stop,
-+ .ping = s3c2410wdt_keepalive,
-+ .set_timeout = s3c2410wdt_set_heartbeat,
-+};
+ +static struct watchdog_ops s3c2410wdt_ops = {
+ + .owner = THIS_MODULE,
+ + .start = s3c2410wdt_start,
+ + .stop = s3c2410wdt_stop,
+ + .ping = s3c2410wdt_keepalive,
+ + .set_timeout = s3c2410wdt_set_heartbeat,
+ +};
-A typical function-header change looks like:
+A typical function-header change looks like::
--static void s3c2410wdt_keepalive(void)
-+static int s3c2410wdt_keepalive(struct watchdog_device *wdd)
- {
-...
-+
-+ return 0;
- }
+ -static void s3c2410wdt_keepalive(void)
+ +static int s3c2410wdt_keepalive(struct watchdog_device *wdd)
+ {
+ ...
+ +
+ + return 0;
+ }
-...
+ ...
-- s3c2410wdt_keepalive();
-+ s3c2410wdt_keepalive(&s3c2410_wdd);
+ - s3c2410wdt_keepalive();
+ + s3c2410wdt_keepalive(&s3c2410_wdd);
Add the watchdog device
@@ -159,12 +161,12 @@ static variables. Those have to be converted to use the members in
watchdog_device. Note that the timeout values are unsigned int. Some drivers
use signed int, so this has to be converted, too.
-Here is a simple example for a watchdog device:
+Here is a simple example for a watchdog device::
-+static struct watchdog_device s3c2410_wdd = {
-+ .info = &s3c2410_wdt_ident,
-+ .ops = &s3c2410wdt_ops,
-+};
+ +static struct watchdog_device s3c2410_wdd = {
+ + .info = &s3c2410_wdt_ident,
+ + .ops = &s3c2410wdt_ops,
+ +};
Handle the 'nowayout' feature
@@ -173,12 +175,12 @@ Handle the 'nowayout' feature
A few drivers use nowayout statically, i.e. there is no module parameter for it
and only CONFIG_WATCHDOG_NOWAYOUT determines if the feature is going to be
used. This needs to be converted by initializing the status variable of the
-watchdog_device like this:
+watchdog_device like this::
.status = WATCHDOG_NOWAYOUT_INIT_STATUS,
Most drivers, however, also allow runtime configuration of nowayout, usually
-by adding a module parameter. The conversion for this would be something like:
+by adding a module parameter. The conversion for this would be something like::
watchdog_set_nowayout(&s3c2410_wdd, nowayout);
@@ -191,15 +193,15 @@ Register the watchdog device
Replace misc_register(&miscdev) with watchdog_register_device(&watchdog_dev).
Make sure the return value gets checked and the error message, if present,
-still fits. Also convert the unregister case.
+still fits. Also convert the unregister case::
-- ret = misc_register(&s3c2410wdt_miscdev);
-+ ret = watchdog_register_device(&s3c2410_wdd);
+ - ret = misc_register(&s3c2410wdt_miscdev);
+ + ret = watchdog_register_device(&s3c2410_wdd);
-...
+ ...
-- misc_deregister(&s3c2410wdt_miscdev);
-+ watchdog_unregister_device(&s3c2410_wdd);
+ - misc_deregister(&s3c2410wdt_miscdev);
+ + watchdog_unregister_device(&s3c2410_wdd);
Update the Kconfig-entry
@@ -207,7 +209,7 @@ Update the Kconfig-entry
The entry for the driver now needs to select WATCHDOG_CORE:
-+ select WATCHDOG_CORE
+ + select WATCHDOG_CORE
Create a patch and send it to upstream
@@ -215,4 +217,3 @@ Create a patch and send it to upstream
Make sure you understood Documentation/process/submitting-patches.rst and send your patch to
linux-watchdog@vger.kernel.org. We are looking forward to it :)
-
diff --git a/Documentation/watchdog/hpwdt.txt b/Documentation/watchdog/hpwdt.txt
index 55df692c5595..a8c6751321de 100644
--- a/Documentation/watchdog/hpwdt.txt
+++ b/Documentation/watchdog/hpwdt.txt
@@ -1,7 +1,12 @@
+===========================
+HPE iLO NMI Watchdog Driver
+===========================
+
+for iLO based ProLiant Servers
+==============================
+
Last reviewed: 08/20/2018
- HPE iLO NMI Watchdog Driver
- for iLO based ProLiant Servers
The HPE iLO NMI Watchdog driver is a kernel module that provides basic
watchdog functionality and handler for the iLO "Generate NMI to System"
@@ -20,21 +25,24 @@ Last reviewed: 08/20/2018
The hpwdt driver also has the following module parameters:
- soft_margin - allows the user to set the watchdog timer value.
+ ============ ================================================================
+ soft_margin allows the user to set the watchdog timer value.
Default value is 30 seconds.
- timeout - an alias of soft_margin.
- pretimeout - allows the user to set the watchdog pretimeout value.
+ timeout an alias of soft_margin.
+ pretimeout allows the user to set the watchdog pretimeout value.
This is the number of seconds before timeout when an
NMI is delivered to the system. Setting the value to
zero disables the pretimeout NMI.
Default value is 9 seconds.
- nowayout - basic watchdog parameter that does not allow the timer to
+ nowayout basic watchdog parameter that does not allow the timer to
be restarted or an impending ASR to be escaped.
Default value is set when compiling the kernel. If it is set
to "Y", then there is no way of disabling the watchdog once
it has been started.
+ ============ ================================================================
- NOTE: More information about watchdog drivers in general, including the ioctl
+ NOTE:
+ More information about watchdog drivers in general, including the ioctl
interface to /dev/watchdog can be found in
Documentation/watchdog/watchdog-api.txt and Documentation/IPMI.txt.
@@ -63,4 +71,3 @@ Last reviewed: 08/20/2018
The HPE iLO NMI Watchdog Driver and documentation were originally developed
by Tom Mingarelli.
-
diff --git a/Documentation/watchdog/mlx-wdt.txt b/Documentation/watchdog/mlx-wdt.txt
index 66eeb78505c3..bf5bafac47f0 100644
--- a/Documentation/watchdog/mlx-wdt.txt
+++ b/Documentation/watchdog/mlx-wdt.txt
@@ -1,5 +1,9 @@
- Mellanox watchdog drivers
- for x86 based system switches
+=========================
+Mellanox watchdog drivers
+=========================
+
+for x86 based system switches
+=============================
This driver provides watchdog functionality for various Mellanox
Ethernet and Infiniband switch systems.
@@ -9,16 +13,16 @@ Mellanox watchdog device is implemented in a programmable logic device.
There are 2 types of HW watchdog implementations.
Type 1:
-Actual HW timeout can be defined as a power of 2 msec.
-e.g. timeout 20 sec will be rounded up to 32768 msec.
-The maximum timeout period is 32 sec (32768 msec.),
-Get time-left isn't supported
+ Actual HW timeout can be defined as a power of 2 msec.
+ e.g. timeout 20 sec will be rounded up to 32768 msec.
+ The maximum timeout period is 32 sec (32768 msec.),
+ Get time-left isn't supported
Type 2:
-Actual HW timeout is defined in sec. and it's the same as
-a user-defined timeout.
-Maximum timeout is 255 sec.
-Get time-left is supported.
+ Actual HW timeout is defined in sec. and it's the same as
+ a user-defined timeout.
+ Maximum timeout is 255 sec.
+ Get time-left is supported.
Type 1 HW watchdog implementation exist in old systems and
all new systems have type 2 HW watchdog.
diff --git a/Documentation/watchdog/pcwd-watchdog.txt b/Documentation/watchdog/pcwd-watchdog.txt
index b8e60a441a43..405e2a370082 100644
--- a/Documentation/watchdog/pcwd-watchdog.txt
+++ b/Documentation/watchdog/pcwd-watchdog.txt
@@ -1,8 +1,13 @@
+===================================
+Berkshire Products PC Watchdog Card
+===================================
+
Last reviewed: 10/05/2007
- Berkshire Products PC Watchdog Card
- Support for ISA Cards Revision A and C
- Documentation and Driver by Ken Hollis <kenji@bitgate.com>
+Support for ISA Cards Revision A and C
+=======================================
+
+Documentation and Driver by Ken Hollis <kenji@bitgate.com>
The PC Watchdog is a card that offers the same type of functionality that
the WDT card does, only it doesn't require an IRQ to run. Furthermore,
@@ -33,6 +38,7 @@ Last reviewed: 10/05/2007
WDIOC_GETSUPPORT
This returns the support of the card itself. This
returns in structure "PCWDS" which returns:
+
options = WDIOS_TEMPPANIC
(This card supports temperature)
firmware_version = xxxx
@@ -63,4 +69,3 @@ Last reviewed: 10/05/2007
-- Ken Hollis
(kenji@bitgate.com)
-
diff --git a/Documentation/watchdog/watchdog-api.txt b/Documentation/watchdog/watchdog-api.txt
index 0e62ba33b7fb..c6c1e9fa9f73 100644
--- a/Documentation/watchdog/watchdog-api.txt
+++ b/Documentation/watchdog/watchdog-api.txt
@@ -1,7 +1,10 @@
+=============================
+The Linux Watchdog driver API
+=============================
+
Last reviewed: 10/05/2007
-The Linux Watchdog driver API.
Copyright 2002 Christer Weingel <wingel@nano-system.com>
@@ -10,7 +13,8 @@ driver which is (c) Copyright 2000 Jakob Oestergaard <jakob@ostenfeld.dk>
This document describes the state of the Linux 2.4.18 kernel.
-Introduction:
+Introduction
+============
A Watchdog Timer (WDT) is a hardware circuit that can reset the
computer system in case of a software fault. You probably knew that
@@ -30,7 +34,8 @@ drivers implement different, and sometimes incompatible, parts of it.
This file is an attempt to document the existing usage and allow
future driver writers to use it as a reference.
-The simplest API:
+The simplest API
+================
All drivers support the basic mode of operation, where the watchdog
activates as soon as /dev/watchdog is opened and will reboot unless
@@ -54,7 +59,8 @@ after the timeout has passed. Watchdog devices also usually support
the nowayout module parameter so that this option can be controlled at
runtime.
-Magic Close feature:
+Magic Close feature
+===================
If a driver supports "Magic Close", the driver will not disable the
watchdog unless a specific magic character 'V' has been sent to
@@ -64,7 +70,8 @@ will assume that the daemon (and userspace in general) died, and will
stop pinging the watchdog without disabling it first. This will then
cause a reboot if the watchdog is not re-opened in sufficient time.
-The ioctl API:
+The ioctl API
+=============
All conforming drivers also support an ioctl API.
@@ -73,7 +80,7 @@ Pinging the watchdog using an ioctl:
All drivers that have an ioctl interface support at least one ioctl,
KEEPALIVE. This ioctl does exactly the same thing as a write to the
watchdog device, so the main loop in the above program could be
-replaced with:
+replaced with::
while (1) {
ioctl(fd, WDIOC_KEEPALIVE, 0);
@@ -82,14 +89,15 @@ replaced with:
the argument to the ioctl is ignored.
-Setting and getting the timeout:
+Setting and getting the timeout
+===============================
For some drivers it is possible to modify the watchdog timeout on the
fly with the SETTIMEOUT ioctl, those drivers have the WDIOF_SETTIMEOUT
flag set in their option field. The argument is an integer
representing the timeout in seconds. The driver returns the real
timeout used in the same variable, and this timeout might differ from
-the requested one due to limitation of the hardware.
+the requested one due to limitation of the hardware::
int timeout = 45;
ioctl(fd, WDIOC_SETTIMEOUT, &timeout);
@@ -99,18 +107,19 @@ This example might actually print "The timeout was set to 60 seconds"
if the device has a granularity of minutes for its timeout.
Starting with the Linux 2.4.18 kernel, it is possible to query the
-current timeout using the GETTIMEOUT ioctl.
+current timeout using the GETTIMEOUT ioctl::
ioctl(fd, WDIOC_GETTIMEOUT, &timeout);
printf("The timeout was is %d seconds\n", timeout);
-Pretimeouts:
+Pretimeouts
+===========
Some watchdog timers can be set to have a trigger go off before the
actual time they will reset the system. This can be done with an NMI,
interrupt, or other mechanism. This allows Linux to record useful
information (like panic information and kernel coredumps) before it
-resets.
+resets::
pretimeout = 10;
ioctl(fd, WDIOC_SETPRETIMEOUT, &pretimeout);
@@ -121,89 +130,113 @@ the pretimeout. So, for instance, if you set the timeout to 60 seconds
and the pretimeout to 10 seconds, the pretimeout will go off in 50
seconds. Setting a pretimeout to zero disables it.
-There is also a get function for getting the pretimeout:
+There is also a get function for getting the pretimeout::
ioctl(fd, WDIOC_GETPRETIMEOUT, &timeout);
printf("The pretimeout was is %d seconds\n", timeout);
Not all watchdog drivers will support a pretimeout.
-Get the number of seconds before reboot:
+Get the number of seconds before reboot
+=======================================
Some watchdog drivers have the ability to report the remaining time
before the system will reboot. The WDIOC_GETTIMELEFT is the ioctl
-that returns the number of seconds before reboot.
+that returns the number of seconds before reboot::
ioctl(fd, WDIOC_GETTIMELEFT, &timeleft);
printf("The timeout was is %d seconds\n", timeleft);
-Environmental monitoring:
+Environmental monitoring
+========================
All watchdog drivers are required return more information about the system,
some do temperature, fan and power level monitoring, some can tell you
the reason for the last reboot of the system. The GETSUPPORT ioctl is
-available to ask what the device can do:
+available to ask what the device can do::
struct watchdog_info ident;
ioctl(fd, WDIOC_GETSUPPORT, &ident);
the fields returned in the ident struct are:
+ ================ =============================================
identity a string identifying the watchdog driver
firmware_version the firmware version of the card if available
options a flags describing what the device supports
+ ================ =============================================
the options field can have the following bits set, and describes what
kind of information that the GET_STATUS and GET_BOOT_STATUS ioctls can
return. [FIXME -- Is this correct?]
+ ================ =========================
WDIOF_OVERHEAT Reset due to CPU overheat
+ ================ =========================
The machine was last rebooted by the watchdog because the thermal limit was
-exceeded
+exceeded:
+ ============== ==========
WDIOF_FANFAULT Fan failed
+ ============== ==========
A system fan monitored by the watchdog card has failed
+ ============= ================
WDIOF_EXTERN1 External relay 1
+ ============= ================
External monitoring relay/source 1 was triggered. Controllers intended for
real world applications include external monitoring pins that will trigger
a reset.
+ ============= ================
WDIOF_EXTERN2 External relay 2
+ ============= ================
External monitoring relay/source 2 was triggered
+ ================ =====================
WDIOF_POWERUNDER Power bad/power fault
+ ================ =====================
The machine is showing an undervoltage status
+ =============== =============================
WDIOF_CARDRESET Card previously reset the CPU
+ =============== =============================
The last reboot was caused by the watchdog card
+ ================ =====================
WDIOF_POWEROVER Power over voltage
+ ================ =====================
The machine is showing an overvoltage status. Note that if one level is
under and one over both bits will be set - this may seem odd but makes
sense.
+ =================== =====================
WDIOF_KEEPALIVEPING Keep alive ping reply
+ =================== =====================
The watchdog saw a keepalive ping since it was last queried.
+ ================ =======================
WDIOF_SETTIMEOUT Can set/get the timeout
+ ================ =======================
The watchdog can do pretimeouts.
+ ================ ================================
WDIOF_PRETIMEOUT Pretimeout (in seconds), get/set
+ ================ ================================
For those drivers that return any bits set in the option field, the
GETSTATUS and GETBOOTSTATUS ioctls can be used to ask for the current
-status, and the status at the last reboot, respectively.
+status, and the status at the last reboot, respectively::
int flags;
ioctl(fd, WDIOC_GETSTATUS, &flags);
@@ -216,22 +249,23 @@ Note that not all devices support these two calls, and some only
support the GETBOOTSTATUS call.
Some drivers can measure the temperature using the GETTEMP ioctl. The
-returned value is the temperature in degrees fahrenheit.
+returned value is the temperature in degrees fahrenheit::
int temperature;
ioctl(fd, WDIOC_GETTEMP, &temperature);
Finally the SETOPTIONS ioctl can be used to control some aspects of
-the cards operation.
+the cards operation::
int options = 0;
ioctl(fd, WDIOC_SETOPTIONS, &options);
The following options are available:
+ ================= ================================
WDIOS_DISABLECARD Turn off the watchdog timer
WDIOS_ENABLECARD Turn on the watchdog timer
WDIOS_TEMPPANIC Kernel panic on temperature trip
+ ================= ================================
[FIXME -- better explanations]
-
diff --git a/Documentation/watchdog/watchdog-kernel-api.txt b/Documentation/watchdog/watchdog-kernel-api.txt
index 3a91ef5af044..452002be568c 100644
--- a/Documentation/watchdog/watchdog-kernel-api.txt
+++ b/Documentation/watchdog/watchdog-kernel-api.txt
@@ -1,5 +1,7 @@
-The Linux WatchDog Timer Driver Core kernel API.
===============================================
+The Linux WatchDog Timer Driver Core kernel API
+===============================================
+
Last reviewed: 12-Feb-2013
Wim Van Sebroeck <wim@iguana.be>
@@ -23,10 +25,10 @@ The API
Each watchdog timer driver that wants to use the WatchDog Timer Driver Core
must #include <linux/watchdog.h> (you would have to do this anyway when
writing a watchdog device driver). This include file contains following
-register/unregister routines:
+register/unregister routines::
-extern int watchdog_register_device(struct watchdog_device *);
-extern void watchdog_unregister_device(struct watchdog_device *);
+ extern int watchdog_register_device(struct watchdog_device *);
+ extern void watchdog_unregister_device(struct watchdog_device *);
The watchdog_register_device routine registers a watchdog timer device.
The parameter of this routine is a pointer to a watchdog_device structure.
@@ -40,9 +42,9 @@ The watchdog subsystem includes an registration deferral mechanism,
which allows you to register an watchdog as early as you wish during
the boot process.
-The watchdog device structure looks like this:
+The watchdog device structure looks like this::
-struct watchdog_device {
+ struct watchdog_device {
int id;
struct device *parent;
const struct attribute_group **groups;
@@ -62,9 +64,10 @@ struct watchdog_device {
struct watchdog_core_data *wd_data;
unsigned long status;
struct list_head deferred;
-};
+ };
It contains following fields:
+
* id: set by watchdog_register_device, id 0 is special. It has both a
/dev/watchdog0 cdev (dynamic major, minor 0) as well as the old
/dev/watchdog miscdev. The id is set automatically when calling
@@ -114,9 +117,9 @@ It contains following fields:
* deferred: entry in wtd_deferred_reg_list which is used to
register early initialized watchdogs.
-The list of watchdog operations is defined as:
+The list of watchdog operations is defined as::
-struct watchdog_ops {
+ struct watchdog_ops {
struct module *owner;
/* mandatory operations */
int (*start)(struct watchdog_device *);
@@ -129,7 +132,7 @@ struct watchdog_ops {
unsigned int (*get_timeleft)(struct watchdog_device *);
int (*restart)(struct watchdog_device *);
long (*ioctl)(struct watchdog_device *, unsigned int, unsigned long);
-};
+ };
It is important that you first define the module owner of the watchdog timer
driver's operations. This module owner will be used to lock the module when
@@ -138,6 +141,7 @@ module and /dev/watchdog is still open).
Some operations are mandatory and some are optional. The mandatory operations
are:
+
* start: this is a pointer to the routine that starts the watchdog timer
device.
The routine needs a pointer to the watchdog timer device structure as a
@@ -146,51 +150,64 @@ are:
Not all watchdog timer hardware supports the same functionality. That's why
all other routines/operations are optional. They only need to be provided if
they are supported. These optional routines/operations are:
+
* stop: with this routine the watchdog timer device is being stopped.
+
The routine needs a pointer to the watchdog timer device structure as a
parameter. It returns zero on success or a negative errno code for failure.
Some watchdog timer hardware can only be started and not be stopped. A
driver supporting such hardware does not have to implement the stop routine.
+
If a driver has no stop function, the watchdog core will set WDOG_HW_RUNNING
and start calling the driver's keepalive pings function after the watchdog
device is closed.
+
If a watchdog driver does not implement the stop function, it must set
max_hw_heartbeat_ms.
* ping: this is the routine that sends a keepalive ping to the watchdog timer
hardware.
+
The routine needs a pointer to the watchdog timer device structure as a
parameter. It returns zero on success or a negative errno code for failure.
+
Most hardware that does not support this as a separate function uses the
start function to restart the watchdog timer hardware. And that's also what
the watchdog timer driver core does: to send a keepalive ping to the watchdog
timer hardware it will either use the ping operation (when available) or the
start operation (when the ping operation is not available).
+
(Note: the WDIOC_KEEPALIVE ioctl call will only be active when the
WDIOF_KEEPALIVEPING bit has been set in the option field on the watchdog's
info structure).
* status: this routine checks the status of the watchdog timer device. The
status of the device is reported with watchdog WDIOF_* status flags/bits.
+
WDIOF_MAGICCLOSE and WDIOF_KEEPALIVEPING are reported by the watchdog core;
it is not necessary to report those bits from the driver. Also, if no status
function is provided by the driver, the watchdog core reports the status bits
provided in the bootstatus variable of struct watchdog_device.
+
* set_timeout: this routine checks and changes the timeout of the watchdog
timer device. It returns 0 on success, -EINVAL for "parameter out of range"
and -EIO for "could not write value to the watchdog". On success this
routine should set the timeout value of the watchdog_device to the
achieved timeout value (which may be different from the requested one
because the watchdog does not necessarily have a 1 second resolution).
+
Drivers implementing max_hw_heartbeat_ms set the hardware watchdog heartbeat
to the minimum of timeout and max_hw_heartbeat_ms. Those drivers set the
timeout value of the watchdog_device either to the requested timeout value
(if it is larger than max_hw_heartbeat_ms), or to the achieved timeout value.
(Note: the WDIOF_SETTIMEOUT needs to be set in the options field of the
watchdog's info structure).
+
If the watchdog driver does not have to perform any action but setting the
watchdog_device.timeout, this callback can be omitted.
+
If set_timeout is not provided but, WDIOF_SETTIMEOUT is set, the watchdog
infrastructure updates the timeout value of the watchdog_device internally
to the requested value.
+
If the pretimeout feature is used (WDIOF_PRETIMEOUT), then set_timeout must
also take care of checking if pretimeout is still valid and set up the timer
accordingly. This can't be done in the core without races, so it is the
@@ -201,13 +218,16 @@ they are supported. These optional routines/operations are:
seconds before the actual timeout would happen. It returns 0 on success,
-EINVAL for "parameter out of range" and -EIO for "could not write value to
the watchdog". A value of 0 disables pretimeout notification.
+
(Note: the WDIOF_PRETIMEOUT needs to be set in the options field of the
watchdog's info structure).
+
If the watchdog driver does not have to perform any action but setting the
watchdog_device.pretimeout, this callback can be omitted. That means if
set_pretimeout is not provided but WDIOF_PRETIMEOUT is set, the watchdog
infrastructure updates the pretimeout value of the watchdog_device internally
to the requested value.
+
* get_timeleft: this routines returns the time that's left before a reset.
* restart: this routine restarts the machine. It returns 0 on success or a
negative errno code for failure.
@@ -218,6 +238,7 @@ they are supported. These optional routines/operations are:
The status bits should (preferably) be set with the set_bit and clear_bit alike
bit-operations. The status bits that are defined are:
+
* WDOG_ACTIVE: this status bit indicates whether or not a watchdog timer device
is active or not from user perspective. User space is expected to send
heartbeat requests to the driver while this flag is set.
@@ -235,22 +256,30 @@ bit-operations. The status bits that are defined are:
To set the WDOG_NO_WAY_OUT status bit (before registering your watchdog
timer device) you can either:
+
* set it statically in your watchdog_device struct with
+
.status = WATCHDOG_NOWAYOUT_INIT_STATUS,
+
(this will set the value the same as CONFIG_WATCHDOG_NOWAYOUT) or
- * use the following helper function:
- static inline void watchdog_set_nowayout(struct watchdog_device *wdd, int nowayout)
+ * use the following helper function::
+
+ static inline void watchdog_set_nowayout(struct watchdog_device *wdd,
+ int nowayout)
+
+Note:
+ The WatchDog Timer Driver Core supports the magic close feature and
+ the nowayout feature. To use the magic close feature you must set the
+ WDIOF_MAGICCLOSE bit in the options field of the watchdog's info structure.
-Note: The WatchDog Timer Driver Core supports the magic close feature and
-the nowayout feature. To use the magic close feature you must set the
-WDIOF_MAGICCLOSE bit in the options field of the watchdog's info structure.
The nowayout feature will overrule the magic close feature.
To get or set driver specific data the following two helper functions should be
-used:
+used::
-static inline void watchdog_set_drvdata(struct watchdog_device *wdd, void *data)
-static inline void *watchdog_get_drvdata(struct watchdog_device *wdd)
+ static inline void watchdog_set_drvdata(struct watchdog_device *wdd,
+ void *data)
+ static inline void *watchdog_get_drvdata(struct watchdog_device *wdd)
The watchdog_set_drvdata function allows you to add driver specific data. The
arguments of this function are the watchdog device where you want to add the
@@ -260,10 +289,11 @@ The watchdog_get_drvdata function allows you to retrieve driver specific data.
The argument of this function is the watchdog device where you want to retrieve
data from. The function returns the pointer to the driver specific data.
-To initialize the timeout field, the following function can be used:
+To initialize the timeout field, the following function can be used::
-extern int watchdog_init_timeout(struct watchdog_device *wdd,
- unsigned int timeout_parm, struct device *dev);
+ extern int watchdog_init_timeout(struct watchdog_device *wdd,
+ unsigned int timeout_parm,
+ struct device *dev);
The watchdog_init_timeout function allows you to initialize the timeout field
using the module timeout parameter or by retrieving the timeout-sec property from
@@ -272,30 +302,33 @@ to set the default timeout value as timeout value in the watchdog_device and
then use this function to set the user "preferred" timeout value.
This routine returns zero on success and a negative errno code for failure.
-To disable the watchdog on reboot, the user must call the following helper:
+To disable the watchdog on reboot, the user must call the following helper::
-static inline void watchdog_stop_on_reboot(struct watchdog_device *wdd);
+ static inline void watchdog_stop_on_reboot(struct watchdog_device *wdd);
To disable the watchdog when unregistering the watchdog, the user must call
the following helper. Note that this will only stop the watchdog if the
nowayout flag is not set.
-static inline void watchdog_stop_on_unregister(struct watchdog_device *wdd);
+::
+
+ static inline void watchdog_stop_on_unregister(struct watchdog_device *wdd);
To change the priority of the restart handler the following helper should be
-used:
+used::
-void watchdog_set_restart_priority(struct watchdog_device *wdd, int priority);
+ void watchdog_set_restart_priority(struct watchdog_device *wdd, int priority);
User should follow the following guidelines for setting the priority:
+
* 0: should be called in last resort, has limited restart capabilities
* 128: default restart handler, use if no other handler is expected to be
available, and/or if restart is sufficient to restart the entire system
* 255: highest priority, will preempt all other restart handlers
-To raise a pretimeout notification, the following function should be used:
+To raise a pretimeout notification, the following function should be used::
-void watchdog_notify_pretimeout(struct watchdog_device *wdd)
+ void watchdog_notify_pretimeout(struct watchdog_device *wdd)
The function can be called in the interrupt context. If watchdog pretimeout
governor framework (kbuild CONFIG_WATCHDOG_PRETIMEOUT_GOV symbol) is enabled,
diff --git a/Documentation/watchdog/watchdog-parameters.txt b/Documentation/watchdog/watchdog-parameters.txt
index 0b88e333f9e1..b121caae7798 100644
--- a/Documentation/watchdog/watchdog-parameters.txt
+++ b/Documentation/watchdog/watchdog-parameters.txt
@@ -1,410 +1,736 @@
+==========================
+WatchDog Module Parameters
+==========================
+
This file provides information on the module parameters of many of
the Linux watchdog drivers. Watchdog driver parameter specs should
be listed here unless the driver has its own driver-specific information
file.
-
See Documentation/admin-guide/kernel-parameters.rst for information on
providing kernel parameters for builtin drivers versus loadable
modules.
-
-------------------------------------------------
+
acquirewdt:
-wdt_stop: Acquire WDT 'stop' io port (default 0x43)
-wdt_start: Acquire WDT 'start' io port (default 0x443)
-nowayout: Watchdog cannot be stopped once started
+ wdt_stop:
+ Acquire WDT 'stop' io port (default 0x43)
+ wdt_start:
+ Acquire WDT 'start' io port (default 0x443)
+ nowayout:
+ Watchdog cannot be stopped once started
(default=kernel config parameter)
+
-------------------------------------------------
+
advantechwdt:
-wdt_stop: Advantech WDT 'stop' io port (default 0x443)
-wdt_start: Advantech WDT 'start' io port (default 0x443)
-timeout: Watchdog timeout in seconds. 1<= timeout <=63, default=60.
-nowayout: Watchdog cannot be stopped once started
+ wdt_stop:
+ Advantech WDT 'stop' io port (default 0x443)
+ wdt_start:
+ Advantech WDT 'start' io port (default 0x443)
+ timeout:
+ Watchdog timeout in seconds. 1<= timeout <=63, default=60.
+ nowayout:
+ Watchdog cannot be stopped once started
(default=kernel config parameter)
+
-------------------------------------------------
+
alim1535_wdt:
-timeout: Watchdog timeout in seconds. (0 < timeout < 18000, default=60
-nowayout: Watchdog cannot be stopped once started
+ timeout:
+ Watchdog timeout in seconds. (0 < timeout < 18000, default=60
+ nowayout:
+ Watchdog cannot be stopped once started
(default=kernel config parameter)
+
-------------------------------------------------
+
alim7101_wdt:
-timeout: Watchdog timeout in seconds. (1<=timeout<=3600, default=30
-use_gpio: Use the gpio watchdog (required by old cobalt boards).
+ timeout:
+ Watchdog timeout in seconds. (1<=timeout<=3600, default=30
+ use_gpio:
+ Use the gpio watchdog (required by old cobalt boards).
default=0/off/no
-nowayout: Watchdog cannot be stopped once started
+ nowayout:
+ Watchdog cannot be stopped once started
(default=kernel config parameter)
+
-------------------------------------------------
+
ar7_wdt:
-margin: Watchdog margin in seconds (default=60)
-nowayout: Disable watchdog shutdown on close
+ margin:
+ Watchdog margin in seconds (default=60)
+ nowayout:
+ Disable watchdog shutdown on close
(default=kernel config parameter)
+
-------------------------------------------------
+
armada_37xx_wdt:
-timeout: Watchdog timeout in seconds. (default=120)
-nowayout: Disable watchdog shutdown on close
+ timeout:
+ Watchdog timeout in seconds. (default=120)
+ nowayout:
+ Disable watchdog shutdown on close
(default=kernel config parameter)
+
-------------------------------------------------
+
at91rm9200_wdt:
-wdt_time: Watchdog time in seconds. (default=5)
-nowayout: Watchdog cannot be stopped once started
+ wdt_time:
+ Watchdog time in seconds. (default=5)
+ nowayout:
+ Watchdog cannot be stopped once started
(default=kernel config parameter)
+
-------------------------------------------------
+
at91sam9_wdt:
-heartbeat: Watchdog heartbeats in seconds. (default = 15)
-nowayout: Watchdog cannot be stopped once started
+ heartbeat:
+ Watchdog heartbeats in seconds. (default = 15)
+ nowayout:
+ Watchdog cannot be stopped once started
(default=kernel config parameter)
+
-------------------------------------------------
+
bcm47xx_wdt:
-wdt_time: Watchdog time in seconds. (default=30)
-nowayout: Watchdog cannot be stopped once started
+ wdt_time:
+ Watchdog time in seconds. (default=30)
+ nowayout:
+ Watchdog cannot be stopped once started
(default=kernel config parameter)
+
-------------------------------------------------
+
coh901327_wdt:
-margin: Watchdog margin in seconds (default 60s)
+ margin:
+ Watchdog margin in seconds (default 60s)
+
-------------------------------------------------
+
cpu5wdt:
-port: base address of watchdog card, default is 0x91
-verbose: be verbose, default is 0 (no)
-ticks: count down ticks, default is 10000
+ port:
+ base address of watchdog card, default is 0x91
+ verbose:
+ be verbose, default is 0 (no)
+ ticks:
+ count down ticks, default is 10000
+
-------------------------------------------------
+
cpwd:
-wd0_timeout: Default watchdog0 timeout in 1/10secs
-wd1_timeout: Default watchdog1 timeout in 1/10secs
-wd2_timeout: Default watchdog2 timeout in 1/10secs
+ wd0_timeout:
+ Default watchdog0 timeout in 1/10secs
+ wd1_timeout:
+ Default watchdog1 timeout in 1/10secs
+ wd2_timeout:
+ Default watchdog2 timeout in 1/10secs
+
-------------------------------------------------
+
da9052wdt:
-timeout: Watchdog timeout in seconds. 2<= timeout <=131, default=2.048s
-nowayout: Watchdog cannot be stopped once started
+ timeout:
+ Watchdog timeout in seconds. 2<= timeout <=131, default=2.048s
+ nowayout:
+ Watchdog cannot be stopped once started
(default=kernel config parameter)
+
-------------------------------------------------
+
davinci_wdt:
-heartbeat: Watchdog heartbeat period in seconds from 1 to 600, default 60
+ heartbeat:
+ Watchdog heartbeat period in seconds from 1 to 600, default 60
+
-------------------------------------------------
+
ebc-c384_wdt:
-timeout: Watchdog timeout in seconds. (1<=timeout<=15300, default=60)
-nowayout: Watchdog cannot be stopped once started
+ timeout:
+ Watchdog timeout in seconds. (1<=timeout<=15300, default=60)
+ nowayout:
+ Watchdog cannot be stopped once started
+
-------------------------------------------------
+
ep93xx_wdt:
-nowayout: Watchdog cannot be stopped once started
-timeout: Watchdog timeout in seconds. (1<=timeout<=3600, default=TBD)
+ nowayout:
+ Watchdog cannot be stopped once started
+ timeout:
+ Watchdog timeout in seconds. (1<=timeout<=3600, default=TBD)
+
-------------------------------------------------
+
eurotechwdt:
-nowayout: Watchdog cannot be stopped once started
+ nowayout:
+ Watchdog cannot be stopped once started
(default=kernel config parameter)
-io: Eurotech WDT io port (default=0x3f0)
-irq: Eurotech WDT irq (default=10)
-ev: Eurotech WDT event type (default is `int')
+ io:
+ Eurotech WDT io port (default=0x3f0)
+ irq:
+ Eurotech WDT irq (default=10)
+ ev:
+ Eurotech WDT event type (default is `int`)
+
-------------------------------------------------
+
gef_wdt:
-nowayout: Watchdog cannot be stopped once started
+ nowayout:
+ Watchdog cannot be stopped once started
(default=kernel config parameter)
+
-------------------------------------------------
+
geodewdt:
-timeout: Watchdog timeout in seconds. 1<= timeout <=131, default=60.
-nowayout: Watchdog cannot be stopped once started
+ timeout:
+ Watchdog timeout in seconds. 1<= timeout <=131, default=60.
+ nowayout:
+ Watchdog cannot be stopped once started
(default=kernel config parameter)
+
-------------------------------------------------
+
i6300esb:
-heartbeat: Watchdog heartbeat in seconds. (1<heartbeat<2046, default=30)
-nowayout: Watchdog cannot be stopped once started
+ heartbeat:
+ Watchdog heartbeat in seconds. (1<heartbeat<2046, default=30)
+ nowayout:
+ Watchdog cannot be stopped once started
(default=kernel config parameter)
+
-------------------------------------------------
+
iTCO_wdt:
-heartbeat: Watchdog heartbeat in seconds.
+ heartbeat:
+ Watchdog heartbeat in seconds.
(2<heartbeat<39 (TCO v1) or 613 (TCO v2), default=30)
-nowayout: Watchdog cannot be stopped once started
+ nowayout:
+ Watchdog cannot be stopped once started
(default=kernel config parameter)
+
-------------------------------------------------
+
iTCO_vendor_support:
-vendorsupport: iTCO vendor specific support mode, default=0 (none),
+ vendorsupport:
+ iTCO vendor specific support mode, default=0 (none),
1=SuperMicro Pent3, 2=SuperMicro Pent4+, 911=Broken SMI BIOS
+
-------------------------------------------------
+
ib700wdt:
-timeout: Watchdog timeout in seconds. 0<= timeout <=30, default=30.
-nowayout: Watchdog cannot be stopped once started
+ timeout:
+ Watchdog timeout in seconds. 0<= timeout <=30, default=30.
+ nowayout:
+ Watchdog cannot be stopped once started
(default=kernel config parameter)
+
-------------------------------------------------
+
ibmasr:
-nowayout: Watchdog cannot be stopped once started
+ nowayout:
+ Watchdog cannot be stopped once started
(default=kernel config parameter)
+
-------------------------------------------------
+
imx2_wdt:
-timeout: Watchdog timeout in seconds (default 60 s)
-nowayout: Watchdog cannot be stopped once started
+ timeout:
+ Watchdog timeout in seconds (default 60 s)
+ nowayout:
+ Watchdog cannot be stopped once started
(default=kernel config parameter)
+
-------------------------------------------------
+
indydog:
-nowayout: Watchdog cannot be stopped once started
+ nowayout:
+ Watchdog cannot be stopped once started
(default=kernel config parameter)
+
-------------------------------------------------
+
iop_wdt:
-nowayout: Watchdog cannot be stopped once started
+ nowayout:
+ Watchdog cannot be stopped once started
(default=kernel config parameter)
+
-------------------------------------------------
+
it8712f_wdt:
-margin: Watchdog margin in seconds (default 60)
-nowayout: Disable watchdog shutdown on close
+ margin:
+ Watchdog margin in seconds (default 60)
+ nowayout:
+ Disable watchdog shutdown on close
(default=kernel config parameter)
+
-------------------------------------------------
+
it87_wdt:
-nogameport: Forbid the activation of game port, default=0
-nocir: Forbid the use of CIR (workaround for some buggy setups); set to 1 if
+ nogameport:
+ Forbid the activation of game port, default=0
+ nocir:
+ Forbid the use of CIR (workaround for some buggy setups); set to 1 if
system resets despite watchdog daemon running, default=0
-exclusive: Watchdog exclusive device open, default=1
-timeout: Watchdog timeout in seconds, default=60
-testmode: Watchdog test mode (1 = no reboot), default=0
-nowayout: Watchdog cannot be stopped once started
+ exclusive:
+ Watchdog exclusive device open, default=1
+ timeout:
+ Watchdog timeout in seconds, default=60
+ testmode:
+ Watchdog test mode (1 = no reboot), default=0
+ nowayout:
+ Watchdog cannot be stopped once started
(default=kernel config parameter)
+
-------------------------------------------------
+
ixp4xx_wdt:
-heartbeat: Watchdog heartbeat in seconds (default 60s)
-nowayout: Watchdog cannot be stopped once started
+ heartbeat:
+ Watchdog heartbeat in seconds (default 60s)
+ nowayout:
+ Watchdog cannot be stopped once started
(default=kernel config parameter)
+
-------------------------------------------------
+
ks8695_wdt:
-wdt_time: Watchdog time in seconds. (default=5)
-nowayout: Watchdog cannot be stopped once started
+ wdt_time:
+ Watchdog time in seconds. (default=5)
+ nowayout:
+ Watchdog cannot be stopped once started
(default=kernel config parameter)
+
-------------------------------------------------
+
machzwd:
-nowayout: Watchdog cannot be stopped once started
+ nowayout:
+ Watchdog cannot be stopped once started
(default=kernel config parameter)
-action: after watchdog resets, generate:
+ action:
+ after watchdog resets, generate:
0 = RESET(*) 1 = SMI 2 = NMI 3 = SCI
+
-------------------------------------------------
+
max63xx_wdt:
-heartbeat: Watchdog heartbeat period in seconds from 1 to 60, default 60
-nowayout: Watchdog cannot be stopped once started
+ heartbeat:
+ Watchdog heartbeat period in seconds from 1 to 60, default 60
+ nowayout:
+ Watchdog cannot be stopped once started
(default=kernel config parameter)
-nodelay: Force selection of a timeout setting without initial delay
+ nodelay:
+ Force selection of a timeout setting without initial delay
(max6373/74 only, default=0)
+
-------------------------------------------------
+
mixcomwd:
-nowayout: Watchdog cannot be stopped once started
+ nowayout:
+ Watchdog cannot be stopped once started
(default=kernel config parameter)
+
-------------------------------------------------
+
mpc8xxx_wdt:
-timeout: Watchdog timeout in ticks. (0<timeout<65536, default=65535)
-reset: Watchdog Interrupt/Reset Mode. 0 = interrupt, 1 = reset
-nowayout: Watchdog cannot be stopped once started
+ timeout:
+ Watchdog timeout in ticks. (0<timeout<65536, default=65535)
+ reset:
+ Watchdog Interrupt/Reset Mode. 0 = interrupt, 1 = reset
+ nowayout:
+ Watchdog cannot be stopped once started
(default=kernel config parameter)
+
-------------------------------------------------
+
mv64x60_wdt:
-nowayout: Watchdog cannot be stopped once started
+ nowayout:
+ Watchdog cannot be stopped once started
(default=kernel config parameter)
+
-------------------------------------------------
+
ni903x_wdt:
-timeout: Initial watchdog timeout in seconds (0<timeout<516, default=60)
-nowayout: Watchdog cannot be stopped once started
+ timeout:
+ Initial watchdog timeout in seconds (0<timeout<516, default=60)
+ nowayout:
+ Watchdog cannot be stopped once started
(default=kernel config parameter)
+
-------------------------------------------------
+
nic7018_wdt:
-timeout: Initial watchdog timeout in seconds (0<timeout<464, default=80)
-nowayout: Watchdog cannot be stopped once started
+ timeout:
+ Initial watchdog timeout in seconds (0<timeout<464, default=80)
+ nowayout:
+ Watchdog cannot be stopped once started
(default=kernel config parameter)
+
-------------------------------------------------
+
nuc900_wdt:
-heartbeat: Watchdog heartbeats in seconds.
+ heartbeat:
+ Watchdog heartbeats in seconds.
(default = 15)
-nowayout: Watchdog cannot be stopped once started
+ nowayout:
+ Watchdog cannot be stopped once started
(default=kernel config parameter)
+
-------------------------------------------------
+
omap_wdt:
-timer_margin: initial watchdog timeout (in seconds)
-early_enable: Watchdog is started on module insertion (default=0
-nowayout: Watchdog cannot be stopped once started
+ timer_margin:
+ initial watchdog timeout (in seconds)
+ early_enable:
+ Watchdog is started on module insertion (default=0
+ nowayout:
+ Watchdog cannot be stopped once started
(default=kernel config parameter)
+
-------------------------------------------------
+
orion_wdt:
-heartbeat: Initial watchdog heartbeat in seconds
-nowayout: Watchdog cannot be stopped once started
+ heartbeat:
+ Initial watchdog heartbeat in seconds
+ nowayout:
+ Watchdog cannot be stopped once started
(default=kernel config parameter)
+
-------------------------------------------------
+
pc87413_wdt:
-io: pc87413 WDT I/O port (default: io).
-timeout: Watchdog timeout in minutes (default=timeout).
-nowayout: Watchdog cannot be stopped once started
+ io:
+ pc87413 WDT I/O port (default: io).
+ timeout:
+ Watchdog timeout in minutes (default=timeout).
+ nowayout:
+ Watchdog cannot be stopped once started
(default=kernel config parameter)
+
-------------------------------------------------
+
pika_wdt:
-heartbeat: Watchdog heartbeats in seconds. (default = 15)
-nowayout: Watchdog cannot be stopped once started
+ heartbeat:
+ Watchdog heartbeats in seconds. (default = 15)
+ nowayout:
+ Watchdog cannot be stopped once started
(default=kernel config parameter)
+
-------------------------------------------------
+
pnx4008_wdt:
-heartbeat: Watchdog heartbeat period in seconds from 1 to 60, default 19
-nowayout: Set to 1 to keep watchdog running after device release
+ heartbeat:
+ Watchdog heartbeat period in seconds from 1 to 60, default 19
+ nowayout:
+ Set to 1 to keep watchdog running after device release
+
-------------------------------------------------
+
pnx833x_wdt:
-timeout: Watchdog timeout in Mhz. (68Mhz clock), default=2040000000 (30 seconds)
-nowayout: Watchdog cannot be stopped once started
+ timeout:
+ Watchdog timeout in Mhz. (68Mhz clock), default=2040000000 (30 seconds)
+ nowayout:
+ Watchdog cannot be stopped once started
(default=kernel config parameter)
-start_enabled: Watchdog is started on module insertion (default=1)
+ start_enabled:
+ Watchdog is started on module insertion (default=1)
+
-------------------------------------------------
+
rc32434_wdt:
-timeout: Watchdog timeout value, in seconds (default=20)
-nowayout: Watchdog cannot be stopped once started
+ timeout:
+ Watchdog timeout value, in seconds (default=20)
+ nowayout:
+ Watchdog cannot be stopped once started
(default=kernel config parameter)
+
-------------------------------------------------
+
riowd:
-riowd_timeout: Watchdog timeout in minutes (default=1)
+ riowd_timeout:
+ Watchdog timeout in minutes (default=1)
+
-------------------------------------------------
+
s3c2410_wdt:
-tmr_margin: Watchdog tmr_margin in seconds. (default=15)
-tmr_atboot: Watchdog is started at boot time if set to 1, default=0
-nowayout: Watchdog cannot be stopped once started
+ tmr_margin:
+ Watchdog tmr_margin in seconds. (default=15)
+ tmr_atboot:
+ Watchdog is started at boot time if set to 1, default=0
+ nowayout:
+ Watchdog cannot be stopped once started
(default=kernel config parameter)
-soft_noboot: Watchdog action, set to 1 to ignore reboots, 0 to reboot
-debug: Watchdog debug, set to >1 for debug, (default 0)
+ soft_noboot:
+ Watchdog action, set to 1 to ignore reboots, 0 to reboot
+ debug:
+ Watchdog debug, set to >1 for debug, (default 0)
+
-------------------------------------------------
+
sa1100_wdt:
-margin: Watchdog margin in seconds (default 60s)
+ margin:
+ Watchdog margin in seconds (default 60s)
+
-------------------------------------------------
+
sb_wdog:
-timeout: Watchdog timeout in microseconds (max/default 8388607 or 8.3ish secs)
+ timeout:
+ Watchdog timeout in microseconds (max/default 8388607 or 8.3ish secs)
+
-------------------------------------------------
+
sbc60xxwdt:
-wdt_stop: SBC60xx WDT 'stop' io port (default 0x45)
-wdt_start: SBC60xx WDT 'start' io port (default 0x443)
-timeout: Watchdog timeout in seconds. (1<=timeout<=3600, default=30)
-nowayout: Watchdog cannot be stopped once started
+ wdt_stop:
+ SBC60xx WDT 'stop' io port (default 0x45)
+ wdt_start:
+ SBC60xx WDT 'start' io port (default 0x443)
+ timeout:
+ Watchdog timeout in seconds. (1<=timeout<=3600, default=30)
+ nowayout:
+ Watchdog cannot be stopped once started
(default=kernel config parameter)
+
-------------------------------------------------
+
sbc7240_wdt:
-timeout: Watchdog timeout in seconds. (1<=timeout<=255, default=30)
-nowayout: Disable watchdog when closing device file
+ timeout:
+ Watchdog timeout in seconds. (1<=timeout<=255, default=30)
+ nowayout:
+ Disable watchdog when closing device file
+
-------------------------------------------------
+
sbc8360:
-timeout: Index into timeout table (0-63) (default=27 (60s))
-nowayout: Watchdog cannot be stopped once started
+ timeout:
+ Index into timeout table (0-63) (default=27 (60s))
+ nowayout:
+ Watchdog cannot be stopped once started
(default=kernel config parameter)
+
-------------------------------------------------
+
sbc_epx_c3:
-nowayout: Watchdog cannot be stopped once started
+ nowayout:
+ Watchdog cannot be stopped once started
(default=kernel config parameter)
+
-------------------------------------------------
+
sbc_fitpc2_wdt:
-margin: Watchdog margin in seconds (default 60s)
-nowayout: Watchdog cannot be stopped once started
+ margin:
+ Watchdog margin in seconds (default 60s)
+ nowayout:
+ Watchdog cannot be stopped once started
+
-------------------------------------------------
+
sbsa_gwdt:
-timeout: Watchdog timeout in seconds. (default 10s)
-action: Watchdog action at the first stage timeout,
+ timeout:
+ Watchdog timeout in seconds. (default 10s)
+ action:
+ Watchdog action at the first stage timeout,
set to 0 to ignore, 1 to panic. (default=0)
-nowayout: Watchdog cannot be stopped once started
+ nowayout:
+ Watchdog cannot be stopped once started
(default=kernel config parameter)
+
-------------------------------------------------
+
sc1200wdt:
-isapnp: When set to 0 driver ISA PnP support will be disabled (default=1)
-io: io port
-timeout: range is 0-255 minutes, default is 1
-nowayout: Watchdog cannot be stopped once started
+ isapnp:
+ When set to 0 driver ISA PnP support will be disabled (default=1)
+ io:
+ io port
+ timeout:
+ range is 0-255 minutes, default is 1
+ nowayout:
+ Watchdog cannot be stopped once started
(default=kernel config parameter)
+
-------------------------------------------------
+
sc520_wdt:
-timeout: Watchdog timeout in seconds. (1 <= timeout <= 3600, default=30)
-nowayout: Watchdog cannot be stopped once started
+ timeout:
+ Watchdog timeout in seconds. (1 <= timeout <= 3600, default=30)
+ nowayout:
+ Watchdog cannot be stopped once started
(default=kernel config parameter)
+
-------------------------------------------------
+
sch311x_wdt:
-force_id: Override the detected device ID
-therm_trip: Should a ThermTrip trigger the reset generator
-timeout: Watchdog timeout in seconds. 1<= timeout <=15300, default=60
-nowayout: Watchdog cannot be stopped once started
+ force_id:
+ Override the detected device ID
+ therm_trip:
+ Should a ThermTrip trigger the reset generator
+ timeout:
+ Watchdog timeout in seconds. 1<= timeout <=15300, default=60
+ nowayout:
+ Watchdog cannot be stopped once started
(default=kernel config parameter)
+
-------------------------------------------------
+
scx200_wdt:
-margin: Watchdog margin in seconds
-nowayout: Disable watchdog shutdown on close
+ margin:
+ Watchdog margin in seconds
+ nowayout:
+ Disable watchdog shutdown on close
+
-------------------------------------------------
+
shwdt:
-clock_division_ratio: Clock division ratio. Valid ranges are from 0x5 (1.31ms)
+ clock_division_ratio:
+ Clock division ratio. Valid ranges are from 0x5 (1.31ms)
to 0x7 (5.25ms). (default=7)
-heartbeat: Watchdog heartbeat in seconds. (1 <= heartbeat <= 3600, default=30
-nowayout: Watchdog cannot be stopped once started
+ heartbeat:
+ Watchdog heartbeat in seconds. (1 <= heartbeat <= 3600, default=30
+ nowayout:
+ Watchdog cannot be stopped once started
(default=kernel config parameter)
+
-------------------------------------------------
+
smsc37b787_wdt:
-timeout: range is 1-255 units, default is 60
-nowayout: Watchdog cannot be stopped once started
+ timeout:
+ range is 1-255 units, default is 60
+ nowayout:
+ Watchdog cannot be stopped once started
(default=kernel config parameter)
+
-------------------------------------------------
+
softdog:
-soft_margin: Watchdog soft_margin in seconds.
+ soft_margin:
+ Watchdog soft_margin in seconds.
(0 < soft_margin < 65536, default=60)
-nowayout: Watchdog cannot be stopped once started
+ nowayout:
+ Watchdog cannot be stopped once started
(default=kernel config parameter)
-soft_noboot: Softdog action, set to 1 to ignore reboots, 0 to reboot
+ soft_noboot:
+ Softdog action, set to 1 to ignore reboots, 0 to reboot
(default=0)
+
-------------------------------------------------
+
stmp3xxx_wdt:
-heartbeat: Watchdog heartbeat period in seconds from 1 to 4194304, default 19
+ heartbeat:
+ Watchdog heartbeat period in seconds from 1 to 4194304, default 19
+
-------------------------------------------------
+
tegra_wdt:
-heartbeat: Watchdog heartbeats in seconds. (default = 120)
-nowayout: Watchdog cannot be stopped once started
+ heartbeat:
+ Watchdog heartbeats in seconds. (default = 120)
+ nowayout:
+ Watchdog cannot be stopped once started
(default=kernel config parameter)
+
-------------------------------------------------
+
ts72xx_wdt:
-timeout: Watchdog timeout in seconds. (1 <= timeout <= 8, default=8)
-nowayout: Disable watchdog shutdown on close
+ timeout:
+ Watchdog timeout in seconds. (1 <= timeout <= 8, default=8)
+ nowayout:
+ Disable watchdog shutdown on close
+
-------------------------------------------------
+
twl4030_wdt:
-nowayout: Watchdog cannot be stopped once started
+ nowayout:
+ Watchdog cannot be stopped once started
(default=kernel config parameter)
+
-------------------------------------------------
+
txx9wdt:
-timeout: Watchdog timeout in seconds. (0<timeout<N, default=60)
-nowayout: Watchdog cannot be stopped once started
+ timeout:
+ Watchdog timeout in seconds. (0<timeout<N, default=60)
+ nowayout:
+ Watchdog cannot be stopped once started
(default=kernel config parameter)
+
-------------------------------------------------
+
uniphier_wdt:
-timeout: Watchdog timeout in power of two seconds.
+ timeout:
+ Watchdog timeout in power of two seconds.
(1 <= timeout <= 128, default=64)
-nowayout: Watchdog cannot be stopped once started
+ nowayout:
+ Watchdog cannot be stopped once started
(default=kernel config parameter)
+
-------------------------------------------------
+
w83627hf_wdt:
-wdt_io: w83627hf/thf WDT io port (default 0x2E)
-timeout: Watchdog timeout in seconds. 1 <= timeout <= 255, default=60.
-nowayout: Watchdog cannot be stopped once started
+ wdt_io:
+ w83627hf/thf WDT io port (default 0x2E)
+ timeout:
+ Watchdog timeout in seconds. 1 <= timeout <= 255, default=60.
+ nowayout:
+ Watchdog cannot be stopped once started
(default=kernel config parameter)
+
-------------------------------------------------
+
w83877f_wdt:
-timeout: Watchdog timeout in seconds. (1<=timeout<=3600, default=30)
-nowayout: Watchdog cannot be stopped once started
+ timeout:
+ Watchdog timeout in seconds. (1<=timeout<=3600, default=30)
+ nowayout:
+ Watchdog cannot be stopped once started
(default=kernel config parameter)
+
-------------------------------------------------
+
w83977f_wdt:
-timeout: Watchdog timeout in seconds (15..7635), default=45)
-testmode: Watchdog testmode (1 = no reboot), default=0
-nowayout: Watchdog cannot be stopped once started
+ timeout:
+ Watchdog timeout in seconds (15..7635), default=45)
+ testmode:
+ Watchdog testmode (1 = no reboot), default=0
+ nowayout:
+ Watchdog cannot be stopped once started
(default=kernel config parameter)
+
-------------------------------------------------
+
wafer5823wdt:
-timeout: Watchdog timeout in seconds. 1 <= timeout <= 255, default=60.
-nowayout: Watchdog cannot be stopped once started
+ timeout:
+ Watchdog timeout in seconds. 1 <= timeout <= 255, default=60.
+ nowayout:
+ Watchdog cannot be stopped once started
(default=kernel config parameter)
+
-------------------------------------------------
+
wdt285:
-soft_margin: Watchdog timeout in seconds (default=60)
+ soft_margin:
+ Watchdog timeout in seconds (default=60)
+
-------------------------------------------------
+
wdt977:
-timeout: Watchdog timeout in seconds (60..15300, default=60)
-testmode: Watchdog testmode (1 = no reboot), default=0
-nowayout: Watchdog cannot be stopped once started
+ timeout:
+ Watchdog timeout in seconds (60..15300, default=60)
+ testmode:
+ Watchdog testmode (1 = no reboot), default=0
+ nowayout:
+ Watchdog cannot be stopped once started
(default=kernel config parameter)
+
-------------------------------------------------
+
wm831x_wdt:
-nowayout: Watchdog cannot be stopped once started
+ nowayout:
+ Watchdog cannot be stopped once started
(default=kernel config parameter)
+
-------------------------------------------------
+
wm8350_wdt:
-nowayout: Watchdog cannot be stopped once started
+ nowayout:
+ Watchdog cannot be stopped once started
(default=kernel config parameter)
+
-------------------------------------------------
+
sun4v_wdt:
-timeout_ms: Watchdog timeout in milliseconds 1..180000, default=60000)
-nowayout: Watchdog cannot be stopped once started
--------------------------------------------------
+ timeout_ms:
+ Watchdog timeout in milliseconds 1..180000, default=60000)
+ nowayout:
+ Watchdog cannot be stopped once started
diff --git a/Documentation/watchdog/watchdog-pm.txt b/Documentation/watchdog/watchdog-pm.txt
index 7a4dd46e0d24..646e1f28f31f 100644
--- a/Documentation/watchdog/watchdog-pm.txt
+++ b/Documentation/watchdog/watchdog-pm.txt
@@ -1,5 +1,7 @@
+===============================================
The Linux WatchDog Timer Power Management Guide
===============================================
+
Last reviewed: 17-Dec-2018
Wolfram Sang <wsa+renesas@sang-engineering.com>
@@ -16,4 +18,5 @@ On resume, a watchdog timer shall be reset to its selected value to give
userspace enough time to resume. [1] [2]
[1] https://patchwork.kernel.org/patch/10252209/
+
[2] https://patchwork.kernel.org/patch/10711625/
diff --git a/Documentation/watchdog/wdt.txt b/Documentation/watchdog/wdt.txt
index ed2f0b860869..d97b0361535b 100644
--- a/Documentation/watchdog/wdt.txt
+++ b/Documentation/watchdog/wdt.txt
@@ -1,11 +1,14 @@
+============================================================
+WDT Watchdog Timer Interfaces For The Linux Operating System
+============================================================
+
Last Reviewed: 10/05/2007
- WDT Watchdog Timer Interfaces For The Linux Operating System
- Alan Cox <alan@lxorguk.ukuu.org.uk>
+Alan Cox <alan@lxorguk.ukuu.org.uk>
- ICS WDT501-P
- ICS WDT501-P (no fan tachometer)
- ICS WDT500-P
+ - ICS WDT501-P
+ - ICS WDT501-P (no fan tachometer)
+ - ICS WDT500-P
All the interfaces provide /dev/watchdog, which when open must be written
to within a timeout or the machine will reboot. Each write delays the reboot
@@ -21,19 +24,26 @@ degrees Fahrenheit. Each read returns a single byte giving the temperature.
The third interface logs kernel messages on additional alert events.
The ICS ISA-bus wdt card cannot be safely probed for. Instead you need to
-pass IO address and IRQ boot parameters. E.g.:
+pass IO address and IRQ boot parameters. E.g.::
+
wdt.io=0x240 wdt.irq=11
Other "wdt" driver parameters are:
+
+ =========== ======================================================
heartbeat Watchdog heartbeat in seconds (default 60)
nowayout Watchdog cannot be stopped once started (kernel
- build parameter)
+ build parameter)
tachometer WDT501-P Fan Tachometer support (0=disable, default=0)
type WDT501-P Card type (500 or 501, default=500)
+ =========== ======================================================
Features
--------
- WDT501P WDT500P
+
+================ ======= =======
+ WDT501P WDT500P
+================ ======= =======
Reboot Timer X X
External Reboot X X
I/O Port Monitor o o
@@ -42,9 +52,12 @@ Fan Speed X o
Power Under X o
Power Over X o
Overheat X o
+================ ======= =======
The external event interfaces on the WDT boards are not currently supported.
Minor numbers are however allocated for it.
-Example Watchdog Driver: see samples/watchdog/watchdog-simple.c
+Example Watchdog Driver:
+
+ see samples/watchdog/watchdog-simple.c
--
2.20.1
^ permalink raw reply related [flat|nested] 81+ messages in thread* Re: [PATCH 37/57] docs: watchdog: convert documents to ReST format
2019-04-16 2:56 ` [PATCH 37/57] docs: watchdog: convert documents to ReST format Mauro Carvalho Chehab
@ 2019-04-17 17:53 ` Guenter Roeck
0 siblings, 0 replies; 81+ messages in thread
From: Guenter Roeck @ 2019-04-17 17:53 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: Linux Doc Mailing List, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Wim Van Sebroeck, linux-watchdog
On Mon, Apr 15, 2019 at 11:56:02PM -0300, Mauro Carvalho Chehab wrote:
> Convert those documents and prepare them to be part of the kernel
> API book, as most of the stuff there are related to the
> Kernel interfaces.
>
> Still, in the future, it would make sense to split the docs,
> as some of the stuff is clearly focused on sysadmin tasks.
>
> Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
Reviewed-by: Guenter Roeck <linux@roeck-us.net>
What is the plan here ? Submit through watchdog subsystem or through
some other subsystem ? Also, will the files be renamed ?
Thanks,
Guenter
> ---
> .../convert_drivers_to_kernel_api.txt | 109 +--
> Documentation/watchdog/hpwdt.txt | 23 +-
> Documentation/watchdog/mlx-wdt.txt | 24 +-
> Documentation/watchdog/pcwd-watchdog.txt | 13 +-
> Documentation/watchdog/watchdog-api.txt | 76 +-
> .../watchdog/watchdog-kernel-api.txt | 89 ++-
> .../watchdog/watchdog-parameters.txt | 672 +++++++++++++-----
> Documentation/watchdog/watchdog-pm.txt | 3 +
> Documentation/watchdog/wdt.txt | 31 +-
> 9 files changed, 733 insertions(+), 307 deletions(-)
>
> diff --git a/Documentation/watchdog/convert_drivers_to_kernel_api.txt b/Documentation/watchdog/convert_drivers_to_kernel_api.txt
> index 9fffb2958d13..dd934cc08e40 100644
> --- a/Documentation/watchdog/convert_drivers_to_kernel_api.txt
> +++ b/Documentation/watchdog/convert_drivers_to_kernel_api.txt
> @@ -1,6 +1,8 @@
> +=========================================================
> Converting old watchdog drivers to the watchdog framework
> +=========================================================
> +
> by Wolfram Sang <w.sang@pengutronix.de>
> -=========================================================
>
> Before the watchdog framework came into the kernel, every driver had to
> implement the API on its own. Now, as the framework factored out the common
> @@ -69,16 +71,16 @@ Here is a overview of the functions and probably needed actions:
> -ENOIOCTLCMD, the IOCTLs of the framework will be tried, too. Any other error
> is directly given to the user.
>
> -Example conversion:
> +Example conversion::
>
> --static const struct file_operations s3c2410wdt_fops = {
> -- .owner = THIS_MODULE,
> -- .llseek = no_llseek,
> -- .write = s3c2410wdt_write,
> -- .unlocked_ioctl = s3c2410wdt_ioctl,
> -- .open = s3c2410wdt_open,
> -- .release = s3c2410wdt_release,
> --};
> + -static const struct file_operations s3c2410wdt_fops = {
> + - .owner = THIS_MODULE,
> + - .llseek = no_llseek,
> + - .write = s3c2410wdt_write,
> + - .unlocked_ioctl = s3c2410wdt_ioctl,
> + - .open = s3c2410wdt_open,
> + - .release = s3c2410wdt_release,
> + -};
>
> Check the functions for device-specific stuff and keep it for later
> refactoring. The rest can go.
> @@ -89,24 +91,24 @@ Remove the miscdevice
>
> Since the file_operations are gone now, you can also remove the 'struct
> miscdevice'. The framework will create it on watchdog_dev_register() called by
> -watchdog_register_device().
> +watchdog_register_device()::
>
> --static struct miscdevice s3c2410wdt_miscdev = {
> -- .minor = WATCHDOG_MINOR,
> -- .name = "watchdog",
> -- .fops = &s3c2410wdt_fops,
> --};
> + -static struct miscdevice s3c2410wdt_miscdev = {
> + - .minor = WATCHDOG_MINOR,
> + - .name = "watchdog",
> + - .fops = &s3c2410wdt_fops,
> + -};
>
>
> Remove obsolete includes and defines
> ------------------------------------
>
> Because of the simplifications, a few defines are probably unused now. Remove
> -them. Includes can be removed, too. For example:
> +them. Includes can be removed, too. For example::
>
> -- #include <linux/fs.h>
> -- #include <linux/miscdevice.h> (if MODULE_ALIAS_MISCDEV is not used)
> -- #include <linux/uaccess.h> (if no custom IOCTLs are used)
> + - #include <linux/fs.h>
> + - #include <linux/miscdevice.h> (if MODULE_ALIAS_MISCDEV is not used)
> + - #include <linux/uaccess.h> (if no custom IOCTLs are used)
>
>
> Add the watchdog operations
> @@ -121,30 +123,30 @@ change the function header. Other changes are most likely not needed, because
> here simply happens the direct hardware access. If you have device-specific
> code left from the above steps, it should be refactored into these callbacks.
>
> -Here is a simple example:
> +Here is a simple example::
>
> -+static struct watchdog_ops s3c2410wdt_ops = {
> -+ .owner = THIS_MODULE,
> -+ .start = s3c2410wdt_start,
> -+ .stop = s3c2410wdt_stop,
> -+ .ping = s3c2410wdt_keepalive,
> -+ .set_timeout = s3c2410wdt_set_heartbeat,
> -+};
> + +static struct watchdog_ops s3c2410wdt_ops = {
> + + .owner = THIS_MODULE,
> + + .start = s3c2410wdt_start,
> + + .stop = s3c2410wdt_stop,
> + + .ping = s3c2410wdt_keepalive,
> + + .set_timeout = s3c2410wdt_set_heartbeat,
> + +};
>
> -A typical function-header change looks like:
> +A typical function-header change looks like::
>
> --static void s3c2410wdt_keepalive(void)
> -+static int s3c2410wdt_keepalive(struct watchdog_device *wdd)
> - {
> -...
> -+
> -+ return 0;
> - }
> + -static void s3c2410wdt_keepalive(void)
> + +static int s3c2410wdt_keepalive(struct watchdog_device *wdd)
> + {
> + ...
> + +
> + + return 0;
> + }
>
> -...
> + ...
>
> -- s3c2410wdt_keepalive();
> -+ s3c2410wdt_keepalive(&s3c2410_wdd);
> + - s3c2410wdt_keepalive();
> + + s3c2410wdt_keepalive(&s3c2410_wdd);
>
>
> Add the watchdog device
> @@ -159,12 +161,12 @@ static variables. Those have to be converted to use the members in
> watchdog_device. Note that the timeout values are unsigned int. Some drivers
> use signed int, so this has to be converted, too.
>
> -Here is a simple example for a watchdog device:
> +Here is a simple example for a watchdog device::
>
> -+static struct watchdog_device s3c2410_wdd = {
> -+ .info = &s3c2410_wdt_ident,
> -+ .ops = &s3c2410wdt_ops,
> -+};
> + +static struct watchdog_device s3c2410_wdd = {
> + + .info = &s3c2410_wdt_ident,
> + + .ops = &s3c2410wdt_ops,
> + +};
>
>
> Handle the 'nowayout' feature
> @@ -173,12 +175,12 @@ Handle the 'nowayout' feature
> A few drivers use nowayout statically, i.e. there is no module parameter for it
> and only CONFIG_WATCHDOG_NOWAYOUT determines if the feature is going to be
> used. This needs to be converted by initializing the status variable of the
> -watchdog_device like this:
> +watchdog_device like this::
>
> .status = WATCHDOG_NOWAYOUT_INIT_STATUS,
>
> Most drivers, however, also allow runtime configuration of nowayout, usually
> -by adding a module parameter. The conversion for this would be something like:
> +by adding a module parameter. The conversion for this would be something like::
>
> watchdog_set_nowayout(&s3c2410_wdd, nowayout);
>
> @@ -191,15 +193,15 @@ Register the watchdog device
>
> Replace misc_register(&miscdev) with watchdog_register_device(&watchdog_dev).
> Make sure the return value gets checked and the error message, if present,
> -still fits. Also convert the unregister case.
> +still fits. Also convert the unregister case::
>
> -- ret = misc_register(&s3c2410wdt_miscdev);
> -+ ret = watchdog_register_device(&s3c2410_wdd);
> + - ret = misc_register(&s3c2410wdt_miscdev);
> + + ret = watchdog_register_device(&s3c2410_wdd);
>
> -...
> + ...
>
> -- misc_deregister(&s3c2410wdt_miscdev);
> -+ watchdog_unregister_device(&s3c2410_wdd);
> + - misc_deregister(&s3c2410wdt_miscdev);
> + + watchdog_unregister_device(&s3c2410_wdd);
>
>
> Update the Kconfig-entry
> @@ -207,7 +209,7 @@ Update the Kconfig-entry
>
> The entry for the driver now needs to select WATCHDOG_CORE:
>
> -+ select WATCHDOG_CORE
> + + select WATCHDOG_CORE
>
>
> Create a patch and send it to upstream
> @@ -215,4 +217,3 @@ Create a patch and send it to upstream
>
> Make sure you understood Documentation/process/submitting-patches.rst and send your patch to
> linux-watchdog@vger.kernel.org. We are looking forward to it :)
> -
> diff --git a/Documentation/watchdog/hpwdt.txt b/Documentation/watchdog/hpwdt.txt
> index 55df692c5595..a8c6751321de 100644
> --- a/Documentation/watchdog/hpwdt.txt
> +++ b/Documentation/watchdog/hpwdt.txt
> @@ -1,7 +1,12 @@
> +===========================
> +HPE iLO NMI Watchdog Driver
> +===========================
> +
> +for iLO based ProLiant Servers
> +==============================
> +
> Last reviewed: 08/20/2018
>
> - HPE iLO NMI Watchdog Driver
> - for iLO based ProLiant Servers
>
> The HPE iLO NMI Watchdog driver is a kernel module that provides basic
> watchdog functionality and handler for the iLO "Generate NMI to System"
> @@ -20,21 +25,24 @@ Last reviewed: 08/20/2018
>
> The hpwdt driver also has the following module parameters:
>
> - soft_margin - allows the user to set the watchdog timer value.
> + ============ ================================================================
> + soft_margin allows the user to set the watchdog timer value.
> Default value is 30 seconds.
> - timeout - an alias of soft_margin.
> - pretimeout - allows the user to set the watchdog pretimeout value.
> + timeout an alias of soft_margin.
> + pretimeout allows the user to set the watchdog pretimeout value.
> This is the number of seconds before timeout when an
> NMI is delivered to the system. Setting the value to
> zero disables the pretimeout NMI.
> Default value is 9 seconds.
> - nowayout - basic watchdog parameter that does not allow the timer to
> + nowayout basic watchdog parameter that does not allow the timer to
> be restarted or an impending ASR to be escaped.
> Default value is set when compiling the kernel. If it is set
> to "Y", then there is no way of disabling the watchdog once
> it has been started.
> + ============ ================================================================
>
> - NOTE: More information about watchdog drivers in general, including the ioctl
> + NOTE:
> + More information about watchdog drivers in general, including the ioctl
> interface to /dev/watchdog can be found in
> Documentation/watchdog/watchdog-api.txt and Documentation/IPMI.txt.
>
> @@ -63,4 +71,3 @@ Last reviewed: 08/20/2018
>
> The HPE iLO NMI Watchdog Driver and documentation were originally developed
> by Tom Mingarelli.
> -
> diff --git a/Documentation/watchdog/mlx-wdt.txt b/Documentation/watchdog/mlx-wdt.txt
> index 66eeb78505c3..bf5bafac47f0 100644
> --- a/Documentation/watchdog/mlx-wdt.txt
> +++ b/Documentation/watchdog/mlx-wdt.txt
> @@ -1,5 +1,9 @@
> - Mellanox watchdog drivers
> - for x86 based system switches
> +=========================
> +Mellanox watchdog drivers
> +=========================
> +
> +for x86 based system switches
> +=============================
>
> This driver provides watchdog functionality for various Mellanox
> Ethernet and Infiniband switch systems.
> @@ -9,16 +13,16 @@ Mellanox watchdog device is implemented in a programmable logic device.
> There are 2 types of HW watchdog implementations.
>
> Type 1:
> -Actual HW timeout can be defined as a power of 2 msec.
> -e.g. timeout 20 sec will be rounded up to 32768 msec.
> -The maximum timeout period is 32 sec (32768 msec.),
> -Get time-left isn't supported
> + Actual HW timeout can be defined as a power of 2 msec.
> + e.g. timeout 20 sec will be rounded up to 32768 msec.
> + The maximum timeout period is 32 sec (32768 msec.),
> + Get time-left isn't supported
>
> Type 2:
> -Actual HW timeout is defined in sec. and it's the same as
> -a user-defined timeout.
> -Maximum timeout is 255 sec.
> -Get time-left is supported.
> + Actual HW timeout is defined in sec. and it's the same as
> + a user-defined timeout.
> + Maximum timeout is 255 sec.
> + Get time-left is supported.
>
> Type 1 HW watchdog implementation exist in old systems and
> all new systems have type 2 HW watchdog.
> diff --git a/Documentation/watchdog/pcwd-watchdog.txt b/Documentation/watchdog/pcwd-watchdog.txt
> index b8e60a441a43..405e2a370082 100644
> --- a/Documentation/watchdog/pcwd-watchdog.txt
> +++ b/Documentation/watchdog/pcwd-watchdog.txt
> @@ -1,8 +1,13 @@
> +===================================
> +Berkshire Products PC Watchdog Card
> +===================================
> +
> Last reviewed: 10/05/2007
>
> - Berkshire Products PC Watchdog Card
> - Support for ISA Cards Revision A and C
> - Documentation and Driver by Ken Hollis <kenji@bitgate.com>
> +Support for ISA Cards Revision A and C
> +=======================================
> +
> +Documentation and Driver by Ken Hollis <kenji@bitgate.com>
>
> The PC Watchdog is a card that offers the same type of functionality that
> the WDT card does, only it doesn't require an IRQ to run. Furthermore,
> @@ -33,6 +38,7 @@ Last reviewed: 10/05/2007
> WDIOC_GETSUPPORT
> This returns the support of the card itself. This
> returns in structure "PCWDS" which returns:
> +
> options = WDIOS_TEMPPANIC
> (This card supports temperature)
> firmware_version = xxxx
> @@ -63,4 +69,3 @@ Last reviewed: 10/05/2007
>
> -- Ken Hollis
> (kenji@bitgate.com)
> -
> diff --git a/Documentation/watchdog/watchdog-api.txt b/Documentation/watchdog/watchdog-api.txt
> index 0e62ba33b7fb..c6c1e9fa9f73 100644
> --- a/Documentation/watchdog/watchdog-api.txt
> +++ b/Documentation/watchdog/watchdog-api.txt
> @@ -1,7 +1,10 @@
> +=============================
> +The Linux Watchdog driver API
> +=============================
> +
> Last reviewed: 10/05/2007
>
>
> -The Linux Watchdog driver API.
>
> Copyright 2002 Christer Weingel <wingel@nano-system.com>
>
> @@ -10,7 +13,8 @@ driver which is (c) Copyright 2000 Jakob Oestergaard <jakob@ostenfeld.dk>
>
> This document describes the state of the Linux 2.4.18 kernel.
>
> -Introduction:
> +Introduction
> +============
>
> A Watchdog Timer (WDT) is a hardware circuit that can reset the
> computer system in case of a software fault. You probably knew that
> @@ -30,7 +34,8 @@ drivers implement different, and sometimes incompatible, parts of it.
> This file is an attempt to document the existing usage and allow
> future driver writers to use it as a reference.
>
> -The simplest API:
> +The simplest API
> +================
>
> All drivers support the basic mode of operation, where the watchdog
> activates as soon as /dev/watchdog is opened and will reboot unless
> @@ -54,7 +59,8 @@ after the timeout has passed. Watchdog devices also usually support
> the nowayout module parameter so that this option can be controlled at
> runtime.
>
> -Magic Close feature:
> +Magic Close feature
> +===================
>
> If a driver supports "Magic Close", the driver will not disable the
> watchdog unless a specific magic character 'V' has been sent to
> @@ -64,7 +70,8 @@ will assume that the daemon (and userspace in general) died, and will
> stop pinging the watchdog without disabling it first. This will then
> cause a reboot if the watchdog is not re-opened in sufficient time.
>
> -The ioctl API:
> +The ioctl API
> +=============
>
> All conforming drivers also support an ioctl API.
>
> @@ -73,7 +80,7 @@ Pinging the watchdog using an ioctl:
> All drivers that have an ioctl interface support at least one ioctl,
> KEEPALIVE. This ioctl does exactly the same thing as a write to the
> watchdog device, so the main loop in the above program could be
> -replaced with:
> +replaced with::
>
> while (1) {
> ioctl(fd, WDIOC_KEEPALIVE, 0);
> @@ -82,14 +89,15 @@ replaced with:
>
> the argument to the ioctl is ignored.
>
> -Setting and getting the timeout:
> +Setting and getting the timeout
> +===============================
>
> For some drivers it is possible to modify the watchdog timeout on the
> fly with the SETTIMEOUT ioctl, those drivers have the WDIOF_SETTIMEOUT
> flag set in their option field. The argument is an integer
> representing the timeout in seconds. The driver returns the real
> timeout used in the same variable, and this timeout might differ from
> -the requested one due to limitation of the hardware.
> +the requested one due to limitation of the hardware::
>
> int timeout = 45;
> ioctl(fd, WDIOC_SETTIMEOUT, &timeout);
> @@ -99,18 +107,19 @@ This example might actually print "The timeout was set to 60 seconds"
> if the device has a granularity of minutes for its timeout.
>
> Starting with the Linux 2.4.18 kernel, it is possible to query the
> -current timeout using the GETTIMEOUT ioctl.
> +current timeout using the GETTIMEOUT ioctl::
>
> ioctl(fd, WDIOC_GETTIMEOUT, &timeout);
> printf("The timeout was is %d seconds\n", timeout);
>
> -Pretimeouts:
> +Pretimeouts
> +===========
>
> Some watchdog timers can be set to have a trigger go off before the
> actual time they will reset the system. This can be done with an NMI,
> interrupt, or other mechanism. This allows Linux to record useful
> information (like panic information and kernel coredumps) before it
> -resets.
> +resets::
>
> pretimeout = 10;
> ioctl(fd, WDIOC_SETPRETIMEOUT, &pretimeout);
> @@ -121,89 +130,113 @@ the pretimeout. So, for instance, if you set the timeout to 60 seconds
> and the pretimeout to 10 seconds, the pretimeout will go off in 50
> seconds. Setting a pretimeout to zero disables it.
>
> -There is also a get function for getting the pretimeout:
> +There is also a get function for getting the pretimeout::
>
> ioctl(fd, WDIOC_GETPRETIMEOUT, &timeout);
> printf("The pretimeout was is %d seconds\n", timeout);
>
> Not all watchdog drivers will support a pretimeout.
>
> -Get the number of seconds before reboot:
> +Get the number of seconds before reboot
> +=======================================
>
> Some watchdog drivers have the ability to report the remaining time
> before the system will reboot. The WDIOC_GETTIMELEFT is the ioctl
> -that returns the number of seconds before reboot.
> +that returns the number of seconds before reboot::
>
> ioctl(fd, WDIOC_GETTIMELEFT, &timeleft);
> printf("The timeout was is %d seconds\n", timeleft);
>
> -Environmental monitoring:
> +Environmental monitoring
> +========================
>
> All watchdog drivers are required return more information about the system,
> some do temperature, fan and power level monitoring, some can tell you
> the reason for the last reboot of the system. The GETSUPPORT ioctl is
> -available to ask what the device can do:
> +available to ask what the device can do::
>
> struct watchdog_info ident;
> ioctl(fd, WDIOC_GETSUPPORT, &ident);
>
> the fields returned in the ident struct are:
>
> + ================ =============================================
> identity a string identifying the watchdog driver
> firmware_version the firmware version of the card if available
> options a flags describing what the device supports
> + ================ =============================================
>
> the options field can have the following bits set, and describes what
> kind of information that the GET_STATUS and GET_BOOT_STATUS ioctls can
> return. [FIXME -- Is this correct?]
>
> + ================ =========================
> WDIOF_OVERHEAT Reset due to CPU overheat
> + ================ =========================
>
> The machine was last rebooted by the watchdog because the thermal limit was
> -exceeded
> +exceeded:
>
> + ============== ==========
> WDIOF_FANFAULT Fan failed
> + ============== ==========
>
> A system fan monitored by the watchdog card has failed
>
> + ============= ================
> WDIOF_EXTERN1 External relay 1
> + ============= ================
>
> External monitoring relay/source 1 was triggered. Controllers intended for
> real world applications include external monitoring pins that will trigger
> a reset.
>
> + ============= ================
> WDIOF_EXTERN2 External relay 2
> + ============= ================
>
> External monitoring relay/source 2 was triggered
>
> + ================ =====================
> WDIOF_POWERUNDER Power bad/power fault
> + ================ =====================
>
> The machine is showing an undervoltage status
>
> + =============== =============================
> WDIOF_CARDRESET Card previously reset the CPU
> + =============== =============================
>
> The last reboot was caused by the watchdog card
>
> + ================ =====================
> WDIOF_POWEROVER Power over voltage
> + ================ =====================
>
> The machine is showing an overvoltage status. Note that if one level is
> under and one over both bits will be set - this may seem odd but makes
> sense.
>
> + =================== =====================
> WDIOF_KEEPALIVEPING Keep alive ping reply
> + =================== =====================
>
> The watchdog saw a keepalive ping since it was last queried.
>
> + ================ =======================
> WDIOF_SETTIMEOUT Can set/get the timeout
> + ================ =======================
>
> The watchdog can do pretimeouts.
>
> + ================ ================================
> WDIOF_PRETIMEOUT Pretimeout (in seconds), get/set
> + ================ ================================
>
>
> For those drivers that return any bits set in the option field, the
> GETSTATUS and GETBOOTSTATUS ioctls can be used to ask for the current
> -status, and the status at the last reboot, respectively.
> +status, and the status at the last reboot, respectively::
>
> int flags;
> ioctl(fd, WDIOC_GETSTATUS, &flags);
> @@ -216,22 +249,23 @@ Note that not all devices support these two calls, and some only
> support the GETBOOTSTATUS call.
>
> Some drivers can measure the temperature using the GETTEMP ioctl. The
> -returned value is the temperature in degrees fahrenheit.
> +returned value is the temperature in degrees fahrenheit::
>
> int temperature;
> ioctl(fd, WDIOC_GETTEMP, &temperature);
>
> Finally the SETOPTIONS ioctl can be used to control some aspects of
> -the cards operation.
> +the cards operation::
>
> int options = 0;
> ioctl(fd, WDIOC_SETOPTIONS, &options);
>
> The following options are available:
>
> + ================= ================================
> WDIOS_DISABLECARD Turn off the watchdog timer
> WDIOS_ENABLECARD Turn on the watchdog timer
> WDIOS_TEMPPANIC Kernel panic on temperature trip
> + ================= ================================
>
> [FIXME -- better explanations]
> -
> diff --git a/Documentation/watchdog/watchdog-kernel-api.txt b/Documentation/watchdog/watchdog-kernel-api.txt
> index 3a91ef5af044..452002be568c 100644
> --- a/Documentation/watchdog/watchdog-kernel-api.txt
> +++ b/Documentation/watchdog/watchdog-kernel-api.txt
> @@ -1,5 +1,7 @@
> -The Linux WatchDog Timer Driver Core kernel API.
> ===============================================
> +The Linux WatchDog Timer Driver Core kernel API
> +===============================================
> +
> Last reviewed: 12-Feb-2013
>
> Wim Van Sebroeck <wim@iguana.be>
> @@ -23,10 +25,10 @@ The API
> Each watchdog timer driver that wants to use the WatchDog Timer Driver Core
> must #include <linux/watchdog.h> (you would have to do this anyway when
> writing a watchdog device driver). This include file contains following
> -register/unregister routines:
> +register/unregister routines::
>
> -extern int watchdog_register_device(struct watchdog_device *);
> -extern void watchdog_unregister_device(struct watchdog_device *);
> + extern int watchdog_register_device(struct watchdog_device *);
> + extern void watchdog_unregister_device(struct watchdog_device *);
>
> The watchdog_register_device routine registers a watchdog timer device.
> The parameter of this routine is a pointer to a watchdog_device structure.
> @@ -40,9 +42,9 @@ The watchdog subsystem includes an registration deferral mechanism,
> which allows you to register an watchdog as early as you wish during
> the boot process.
>
> -The watchdog device structure looks like this:
> +The watchdog device structure looks like this::
>
> -struct watchdog_device {
> + struct watchdog_device {
> int id;
> struct device *parent;
> const struct attribute_group **groups;
> @@ -62,9 +64,10 @@ struct watchdog_device {
> struct watchdog_core_data *wd_data;
> unsigned long status;
> struct list_head deferred;
> -};
> + };
>
> It contains following fields:
> +
> * id: set by watchdog_register_device, id 0 is special. It has both a
> /dev/watchdog0 cdev (dynamic major, minor 0) as well as the old
> /dev/watchdog miscdev. The id is set automatically when calling
> @@ -114,9 +117,9 @@ It contains following fields:
> * deferred: entry in wtd_deferred_reg_list which is used to
> register early initialized watchdogs.
>
> -The list of watchdog operations is defined as:
> +The list of watchdog operations is defined as::
>
> -struct watchdog_ops {
> + struct watchdog_ops {
> struct module *owner;
> /* mandatory operations */
> int (*start)(struct watchdog_device *);
> @@ -129,7 +132,7 @@ struct watchdog_ops {
> unsigned int (*get_timeleft)(struct watchdog_device *);
> int (*restart)(struct watchdog_device *);
> long (*ioctl)(struct watchdog_device *, unsigned int, unsigned long);
> -};
> + };
>
> It is important that you first define the module owner of the watchdog timer
> driver's operations. This module owner will be used to lock the module when
> @@ -138,6 +141,7 @@ module and /dev/watchdog is still open).
>
> Some operations are mandatory and some are optional. The mandatory operations
> are:
> +
> * start: this is a pointer to the routine that starts the watchdog timer
> device.
> The routine needs a pointer to the watchdog timer device structure as a
> @@ -146,51 +150,64 @@ are:
> Not all watchdog timer hardware supports the same functionality. That's why
> all other routines/operations are optional. They only need to be provided if
> they are supported. These optional routines/operations are:
> +
> * stop: with this routine the watchdog timer device is being stopped.
> +
> The routine needs a pointer to the watchdog timer device structure as a
> parameter. It returns zero on success or a negative errno code for failure.
> Some watchdog timer hardware can only be started and not be stopped. A
> driver supporting such hardware does not have to implement the stop routine.
> +
> If a driver has no stop function, the watchdog core will set WDOG_HW_RUNNING
> and start calling the driver's keepalive pings function after the watchdog
> device is closed.
> +
> If a watchdog driver does not implement the stop function, it must set
> max_hw_heartbeat_ms.
> * ping: this is the routine that sends a keepalive ping to the watchdog timer
> hardware.
> +
> The routine needs a pointer to the watchdog timer device structure as a
> parameter. It returns zero on success or a negative errno code for failure.
> +
> Most hardware that does not support this as a separate function uses the
> start function to restart the watchdog timer hardware. And that's also what
> the watchdog timer driver core does: to send a keepalive ping to the watchdog
> timer hardware it will either use the ping operation (when available) or the
> start operation (when the ping operation is not available).
> +
> (Note: the WDIOC_KEEPALIVE ioctl call will only be active when the
> WDIOF_KEEPALIVEPING bit has been set in the option field on the watchdog's
> info structure).
> * status: this routine checks the status of the watchdog timer device. The
> status of the device is reported with watchdog WDIOF_* status flags/bits.
> +
> WDIOF_MAGICCLOSE and WDIOF_KEEPALIVEPING are reported by the watchdog core;
> it is not necessary to report those bits from the driver. Also, if no status
> function is provided by the driver, the watchdog core reports the status bits
> provided in the bootstatus variable of struct watchdog_device.
> +
> * set_timeout: this routine checks and changes the timeout of the watchdog
> timer device. It returns 0 on success, -EINVAL for "parameter out of range"
> and -EIO for "could not write value to the watchdog". On success this
> routine should set the timeout value of the watchdog_device to the
> achieved timeout value (which may be different from the requested one
> because the watchdog does not necessarily have a 1 second resolution).
> +
> Drivers implementing max_hw_heartbeat_ms set the hardware watchdog heartbeat
> to the minimum of timeout and max_hw_heartbeat_ms. Those drivers set the
> timeout value of the watchdog_device either to the requested timeout value
> (if it is larger than max_hw_heartbeat_ms), or to the achieved timeout value.
> (Note: the WDIOF_SETTIMEOUT needs to be set in the options field of the
> watchdog's info structure).
> +
> If the watchdog driver does not have to perform any action but setting the
> watchdog_device.timeout, this callback can be omitted.
> +
> If set_timeout is not provided but, WDIOF_SETTIMEOUT is set, the watchdog
> infrastructure updates the timeout value of the watchdog_device internally
> to the requested value.
> +
> If the pretimeout feature is used (WDIOF_PRETIMEOUT), then set_timeout must
> also take care of checking if pretimeout is still valid and set up the timer
> accordingly. This can't be done in the core without races, so it is the
> @@ -201,13 +218,16 @@ they are supported. These optional routines/operations are:
> seconds before the actual timeout would happen. It returns 0 on success,
> -EINVAL for "parameter out of range" and -EIO for "could not write value to
> the watchdog". A value of 0 disables pretimeout notification.
> +
> (Note: the WDIOF_PRETIMEOUT needs to be set in the options field of the
> watchdog's info structure).
> +
> If the watchdog driver does not have to perform any action but setting the
> watchdog_device.pretimeout, this callback can be omitted. That means if
> set_pretimeout is not provided but WDIOF_PRETIMEOUT is set, the watchdog
> infrastructure updates the pretimeout value of the watchdog_device internally
> to the requested value.
> +
> * get_timeleft: this routines returns the time that's left before a reset.
> * restart: this routine restarts the machine. It returns 0 on success or a
> negative errno code for failure.
> @@ -218,6 +238,7 @@ they are supported. These optional routines/operations are:
>
> The status bits should (preferably) be set with the set_bit and clear_bit alike
> bit-operations. The status bits that are defined are:
> +
> * WDOG_ACTIVE: this status bit indicates whether or not a watchdog timer device
> is active or not from user perspective. User space is expected to send
> heartbeat requests to the driver while this flag is set.
> @@ -235,22 +256,30 @@ bit-operations. The status bits that are defined are:
>
> To set the WDOG_NO_WAY_OUT status bit (before registering your watchdog
> timer device) you can either:
> +
> * set it statically in your watchdog_device struct with
> +
> .status = WATCHDOG_NOWAYOUT_INIT_STATUS,
> +
> (this will set the value the same as CONFIG_WATCHDOG_NOWAYOUT) or
> - * use the following helper function:
> - static inline void watchdog_set_nowayout(struct watchdog_device *wdd, int nowayout)
> + * use the following helper function::
> +
> + static inline void watchdog_set_nowayout(struct watchdog_device *wdd,
> + int nowayout)
> +
> +Note:
> + The WatchDog Timer Driver Core supports the magic close feature and
> + the nowayout feature. To use the magic close feature you must set the
> + WDIOF_MAGICCLOSE bit in the options field of the watchdog's info structure.
>
> -Note: The WatchDog Timer Driver Core supports the magic close feature and
> -the nowayout feature. To use the magic close feature you must set the
> -WDIOF_MAGICCLOSE bit in the options field of the watchdog's info structure.
> The nowayout feature will overrule the magic close feature.
>
> To get or set driver specific data the following two helper functions should be
> -used:
> +used::
>
> -static inline void watchdog_set_drvdata(struct watchdog_device *wdd, void *data)
> -static inline void *watchdog_get_drvdata(struct watchdog_device *wdd)
> + static inline void watchdog_set_drvdata(struct watchdog_device *wdd,
> + void *data)
> + static inline void *watchdog_get_drvdata(struct watchdog_device *wdd)
>
> The watchdog_set_drvdata function allows you to add driver specific data. The
> arguments of this function are the watchdog device where you want to add the
> @@ -260,10 +289,11 @@ The watchdog_get_drvdata function allows you to retrieve driver specific data.
> The argument of this function is the watchdog device where you want to retrieve
> data from. The function returns the pointer to the driver specific data.
>
> -To initialize the timeout field, the following function can be used:
> +To initialize the timeout field, the following function can be used::
>
> -extern int watchdog_init_timeout(struct watchdog_device *wdd,
> - unsigned int timeout_parm, struct device *dev);
> + extern int watchdog_init_timeout(struct watchdog_device *wdd,
> + unsigned int timeout_parm,
> + struct device *dev);
>
> The watchdog_init_timeout function allows you to initialize the timeout field
> using the module timeout parameter or by retrieving the timeout-sec property from
> @@ -272,30 +302,33 @@ to set the default timeout value as timeout value in the watchdog_device and
> then use this function to set the user "preferred" timeout value.
> This routine returns zero on success and a negative errno code for failure.
>
> -To disable the watchdog on reboot, the user must call the following helper:
> +To disable the watchdog on reboot, the user must call the following helper::
>
> -static inline void watchdog_stop_on_reboot(struct watchdog_device *wdd);
> + static inline void watchdog_stop_on_reboot(struct watchdog_device *wdd);
>
> To disable the watchdog when unregistering the watchdog, the user must call
> the following helper. Note that this will only stop the watchdog if the
> nowayout flag is not set.
>
> -static inline void watchdog_stop_on_unregister(struct watchdog_device *wdd);
> +::
> +
> + static inline void watchdog_stop_on_unregister(struct watchdog_device *wdd);
>
> To change the priority of the restart handler the following helper should be
> -used:
> +used::
>
> -void watchdog_set_restart_priority(struct watchdog_device *wdd, int priority);
> + void watchdog_set_restart_priority(struct watchdog_device *wdd, int priority);
>
> User should follow the following guidelines for setting the priority:
> +
> * 0: should be called in last resort, has limited restart capabilities
> * 128: default restart handler, use if no other handler is expected to be
> available, and/or if restart is sufficient to restart the entire system
> * 255: highest priority, will preempt all other restart handlers
>
> -To raise a pretimeout notification, the following function should be used:
> +To raise a pretimeout notification, the following function should be used::
>
> -void watchdog_notify_pretimeout(struct watchdog_device *wdd)
> + void watchdog_notify_pretimeout(struct watchdog_device *wdd)
>
> The function can be called in the interrupt context. If watchdog pretimeout
> governor framework (kbuild CONFIG_WATCHDOG_PRETIMEOUT_GOV symbol) is enabled,
> diff --git a/Documentation/watchdog/watchdog-parameters.txt b/Documentation/watchdog/watchdog-parameters.txt
> index 0b88e333f9e1..b121caae7798 100644
> --- a/Documentation/watchdog/watchdog-parameters.txt
> +++ b/Documentation/watchdog/watchdog-parameters.txt
> @@ -1,410 +1,736 @@
> +==========================
> +WatchDog Module Parameters
> +==========================
> +
> This file provides information on the module parameters of many of
> the Linux watchdog drivers. Watchdog driver parameter specs should
> be listed here unless the driver has its own driver-specific information
> file.
>
> -
> See Documentation/admin-guide/kernel-parameters.rst for information on
> providing kernel parameters for builtin drivers versus loadable
> modules.
>
> -
> -------------------------------------------------
> +
> acquirewdt:
> -wdt_stop: Acquire WDT 'stop' io port (default 0x43)
> -wdt_start: Acquire WDT 'start' io port (default 0x443)
> -nowayout: Watchdog cannot be stopped once started
> + wdt_stop:
> + Acquire WDT 'stop' io port (default 0x43)
> + wdt_start:
> + Acquire WDT 'start' io port (default 0x443)
> + nowayout:
> + Watchdog cannot be stopped once started
> (default=kernel config parameter)
> +
> -------------------------------------------------
> +
> advantechwdt:
> -wdt_stop: Advantech WDT 'stop' io port (default 0x443)
> -wdt_start: Advantech WDT 'start' io port (default 0x443)
> -timeout: Watchdog timeout in seconds. 1<= timeout <=63, default=60.
> -nowayout: Watchdog cannot be stopped once started
> + wdt_stop:
> + Advantech WDT 'stop' io port (default 0x443)
> + wdt_start:
> + Advantech WDT 'start' io port (default 0x443)
> + timeout:
> + Watchdog timeout in seconds. 1<= timeout <=63, default=60.
> + nowayout:
> + Watchdog cannot be stopped once started
> (default=kernel config parameter)
> +
> -------------------------------------------------
> +
> alim1535_wdt:
> -timeout: Watchdog timeout in seconds. (0 < timeout < 18000, default=60
> -nowayout: Watchdog cannot be stopped once started
> + timeout:
> + Watchdog timeout in seconds. (0 < timeout < 18000, default=60
> + nowayout:
> + Watchdog cannot be stopped once started
> (default=kernel config parameter)
> +
> -------------------------------------------------
> +
> alim7101_wdt:
> -timeout: Watchdog timeout in seconds. (1<=timeout<=3600, default=30
> -use_gpio: Use the gpio watchdog (required by old cobalt boards).
> + timeout:
> + Watchdog timeout in seconds. (1<=timeout<=3600, default=30
> + use_gpio:
> + Use the gpio watchdog (required by old cobalt boards).
> default=0/off/no
> -nowayout: Watchdog cannot be stopped once started
> + nowayout:
> + Watchdog cannot be stopped once started
> (default=kernel config parameter)
> +
> -------------------------------------------------
> +
> ar7_wdt:
> -margin: Watchdog margin in seconds (default=60)
> -nowayout: Disable watchdog shutdown on close
> + margin:
> + Watchdog margin in seconds (default=60)
> + nowayout:
> + Disable watchdog shutdown on close
> (default=kernel config parameter)
> +
> -------------------------------------------------
> +
> armada_37xx_wdt:
> -timeout: Watchdog timeout in seconds. (default=120)
> -nowayout: Disable watchdog shutdown on close
> + timeout:
> + Watchdog timeout in seconds. (default=120)
> + nowayout:
> + Disable watchdog shutdown on close
> (default=kernel config parameter)
> +
> -------------------------------------------------
> +
> at91rm9200_wdt:
> -wdt_time: Watchdog time in seconds. (default=5)
> -nowayout: Watchdog cannot be stopped once started
> + wdt_time:
> + Watchdog time in seconds. (default=5)
> + nowayout:
> + Watchdog cannot be stopped once started
> (default=kernel config parameter)
> +
> -------------------------------------------------
> +
> at91sam9_wdt:
> -heartbeat: Watchdog heartbeats in seconds. (default = 15)
> -nowayout: Watchdog cannot be stopped once started
> + heartbeat:
> + Watchdog heartbeats in seconds. (default = 15)
> + nowayout:
> + Watchdog cannot be stopped once started
> (default=kernel config parameter)
> +
> -------------------------------------------------
> +
> bcm47xx_wdt:
> -wdt_time: Watchdog time in seconds. (default=30)
> -nowayout: Watchdog cannot be stopped once started
> + wdt_time:
> + Watchdog time in seconds. (default=30)
> + nowayout:
> + Watchdog cannot be stopped once started
> (default=kernel config parameter)
> +
> -------------------------------------------------
> +
> coh901327_wdt:
> -margin: Watchdog margin in seconds (default 60s)
> + margin:
> + Watchdog margin in seconds (default 60s)
> +
> -------------------------------------------------
> +
> cpu5wdt:
> -port: base address of watchdog card, default is 0x91
> -verbose: be verbose, default is 0 (no)
> -ticks: count down ticks, default is 10000
> + port:
> + base address of watchdog card, default is 0x91
> + verbose:
> + be verbose, default is 0 (no)
> + ticks:
> + count down ticks, default is 10000
> +
> -------------------------------------------------
> +
> cpwd:
> -wd0_timeout: Default watchdog0 timeout in 1/10secs
> -wd1_timeout: Default watchdog1 timeout in 1/10secs
> -wd2_timeout: Default watchdog2 timeout in 1/10secs
> + wd0_timeout:
> + Default watchdog0 timeout in 1/10secs
> + wd1_timeout:
> + Default watchdog1 timeout in 1/10secs
> + wd2_timeout:
> + Default watchdog2 timeout in 1/10secs
> +
> -------------------------------------------------
> +
> da9052wdt:
> -timeout: Watchdog timeout in seconds. 2<= timeout <=131, default=2.048s
> -nowayout: Watchdog cannot be stopped once started
> + timeout:
> + Watchdog timeout in seconds. 2<= timeout <=131, default=2.048s
> + nowayout:
> + Watchdog cannot be stopped once started
> (default=kernel config parameter)
> +
> -------------------------------------------------
> +
> davinci_wdt:
> -heartbeat: Watchdog heartbeat period in seconds from 1 to 600, default 60
> + heartbeat:
> + Watchdog heartbeat period in seconds from 1 to 600, default 60
> +
> -------------------------------------------------
> +
> ebc-c384_wdt:
> -timeout: Watchdog timeout in seconds. (1<=timeout<=15300, default=60)
> -nowayout: Watchdog cannot be stopped once started
> + timeout:
> + Watchdog timeout in seconds. (1<=timeout<=15300, default=60)
> + nowayout:
> + Watchdog cannot be stopped once started
> +
> -------------------------------------------------
> +
> ep93xx_wdt:
> -nowayout: Watchdog cannot be stopped once started
> -timeout: Watchdog timeout in seconds. (1<=timeout<=3600, default=TBD)
> + nowayout:
> + Watchdog cannot be stopped once started
> + timeout:
> + Watchdog timeout in seconds. (1<=timeout<=3600, default=TBD)
> +
> -------------------------------------------------
> +
> eurotechwdt:
> -nowayout: Watchdog cannot be stopped once started
> + nowayout:
> + Watchdog cannot be stopped once started
> (default=kernel config parameter)
> -io: Eurotech WDT io port (default=0x3f0)
> -irq: Eurotech WDT irq (default=10)
> -ev: Eurotech WDT event type (default is `int')
> + io:
> + Eurotech WDT io port (default=0x3f0)
> + irq:
> + Eurotech WDT irq (default=10)
> + ev:
> + Eurotech WDT event type (default is `int`)
> +
> -------------------------------------------------
> +
> gef_wdt:
> -nowayout: Watchdog cannot be stopped once started
> + nowayout:
> + Watchdog cannot be stopped once started
> (default=kernel config parameter)
> +
> -------------------------------------------------
> +
> geodewdt:
> -timeout: Watchdog timeout in seconds. 1<= timeout <=131, default=60.
> -nowayout: Watchdog cannot be stopped once started
> + timeout:
> + Watchdog timeout in seconds. 1<= timeout <=131, default=60.
> + nowayout:
> + Watchdog cannot be stopped once started
> (default=kernel config parameter)
> +
> -------------------------------------------------
> +
> i6300esb:
> -heartbeat: Watchdog heartbeat in seconds. (1<heartbeat<2046, default=30)
> -nowayout: Watchdog cannot be stopped once started
> + heartbeat:
> + Watchdog heartbeat in seconds. (1<heartbeat<2046, default=30)
> + nowayout:
> + Watchdog cannot be stopped once started
> (default=kernel config parameter)
> +
> -------------------------------------------------
> +
> iTCO_wdt:
> -heartbeat: Watchdog heartbeat in seconds.
> + heartbeat:
> + Watchdog heartbeat in seconds.
> (2<heartbeat<39 (TCO v1) or 613 (TCO v2), default=30)
> -nowayout: Watchdog cannot be stopped once started
> + nowayout:
> + Watchdog cannot be stopped once started
> (default=kernel config parameter)
> +
> -------------------------------------------------
> +
> iTCO_vendor_support:
> -vendorsupport: iTCO vendor specific support mode, default=0 (none),
> + vendorsupport:
> + iTCO vendor specific support mode, default=0 (none),
> 1=SuperMicro Pent3, 2=SuperMicro Pent4+, 911=Broken SMI BIOS
> +
> -------------------------------------------------
> +
> ib700wdt:
> -timeout: Watchdog timeout in seconds. 0<= timeout <=30, default=30.
> -nowayout: Watchdog cannot be stopped once started
> + timeout:
> + Watchdog timeout in seconds. 0<= timeout <=30, default=30.
> + nowayout:
> + Watchdog cannot be stopped once started
> (default=kernel config parameter)
> +
> -------------------------------------------------
> +
> ibmasr:
> -nowayout: Watchdog cannot be stopped once started
> + nowayout:
> + Watchdog cannot be stopped once started
> (default=kernel config parameter)
> +
> -------------------------------------------------
> +
> imx2_wdt:
> -timeout: Watchdog timeout in seconds (default 60 s)
> -nowayout: Watchdog cannot be stopped once started
> + timeout:
> + Watchdog timeout in seconds (default 60 s)
> + nowayout:
> + Watchdog cannot be stopped once started
> (default=kernel config parameter)
> +
> -------------------------------------------------
> +
> indydog:
> -nowayout: Watchdog cannot be stopped once started
> + nowayout:
> + Watchdog cannot be stopped once started
> (default=kernel config parameter)
> +
> -------------------------------------------------
> +
> iop_wdt:
> -nowayout: Watchdog cannot be stopped once started
> + nowayout:
> + Watchdog cannot be stopped once started
> (default=kernel config parameter)
> +
> -------------------------------------------------
> +
> it8712f_wdt:
> -margin: Watchdog margin in seconds (default 60)
> -nowayout: Disable watchdog shutdown on close
> + margin:
> + Watchdog margin in seconds (default 60)
> + nowayout:
> + Disable watchdog shutdown on close
> (default=kernel config parameter)
> +
> -------------------------------------------------
> +
> it87_wdt:
> -nogameport: Forbid the activation of game port, default=0
> -nocir: Forbid the use of CIR (workaround for some buggy setups); set to 1 if
> + nogameport:
> + Forbid the activation of game port, default=0
> + nocir:
> + Forbid the use of CIR (workaround for some buggy setups); set to 1 if
> system resets despite watchdog daemon running, default=0
> -exclusive: Watchdog exclusive device open, default=1
> -timeout: Watchdog timeout in seconds, default=60
> -testmode: Watchdog test mode (1 = no reboot), default=0
> -nowayout: Watchdog cannot be stopped once started
> + exclusive:
> + Watchdog exclusive device open, default=1
> + timeout:
> + Watchdog timeout in seconds, default=60
> + testmode:
> + Watchdog test mode (1 = no reboot), default=0
> + nowayout:
> + Watchdog cannot be stopped once started
> (default=kernel config parameter)
> +
> -------------------------------------------------
> +
> ixp4xx_wdt:
> -heartbeat: Watchdog heartbeat in seconds (default 60s)
> -nowayout: Watchdog cannot be stopped once started
> + heartbeat:
> + Watchdog heartbeat in seconds (default 60s)
> + nowayout:
> + Watchdog cannot be stopped once started
> (default=kernel config parameter)
> +
> -------------------------------------------------
> +
> ks8695_wdt:
> -wdt_time: Watchdog time in seconds. (default=5)
> -nowayout: Watchdog cannot be stopped once started
> + wdt_time:
> + Watchdog time in seconds. (default=5)
> + nowayout:
> + Watchdog cannot be stopped once started
> (default=kernel config parameter)
> +
> -------------------------------------------------
> +
> machzwd:
> -nowayout: Watchdog cannot be stopped once started
> + nowayout:
> + Watchdog cannot be stopped once started
> (default=kernel config parameter)
> -action: after watchdog resets, generate:
> + action:
> + after watchdog resets, generate:
> 0 = RESET(*) 1 = SMI 2 = NMI 3 = SCI
> +
> -------------------------------------------------
> +
> max63xx_wdt:
> -heartbeat: Watchdog heartbeat period in seconds from 1 to 60, default 60
> -nowayout: Watchdog cannot be stopped once started
> + heartbeat:
> + Watchdog heartbeat period in seconds from 1 to 60, default 60
> + nowayout:
> + Watchdog cannot be stopped once started
> (default=kernel config parameter)
> -nodelay: Force selection of a timeout setting without initial delay
> + nodelay:
> + Force selection of a timeout setting without initial delay
> (max6373/74 only, default=0)
> +
> -------------------------------------------------
> +
> mixcomwd:
> -nowayout: Watchdog cannot be stopped once started
> + nowayout:
> + Watchdog cannot be stopped once started
> (default=kernel config parameter)
> +
> -------------------------------------------------
> +
> mpc8xxx_wdt:
> -timeout: Watchdog timeout in ticks. (0<timeout<65536, default=65535)
> -reset: Watchdog Interrupt/Reset Mode. 0 = interrupt, 1 = reset
> -nowayout: Watchdog cannot be stopped once started
> + timeout:
> + Watchdog timeout in ticks. (0<timeout<65536, default=65535)
> + reset:
> + Watchdog Interrupt/Reset Mode. 0 = interrupt, 1 = reset
> + nowayout:
> + Watchdog cannot be stopped once started
> (default=kernel config parameter)
> +
> -------------------------------------------------
> +
> mv64x60_wdt:
> -nowayout: Watchdog cannot be stopped once started
> + nowayout:
> + Watchdog cannot be stopped once started
> (default=kernel config parameter)
> +
> -------------------------------------------------
> +
> ni903x_wdt:
> -timeout: Initial watchdog timeout in seconds (0<timeout<516, default=60)
> -nowayout: Watchdog cannot be stopped once started
> + timeout:
> + Initial watchdog timeout in seconds (0<timeout<516, default=60)
> + nowayout:
> + Watchdog cannot be stopped once started
> (default=kernel config parameter)
> +
> -------------------------------------------------
> +
> nic7018_wdt:
> -timeout: Initial watchdog timeout in seconds (0<timeout<464, default=80)
> -nowayout: Watchdog cannot be stopped once started
> + timeout:
> + Initial watchdog timeout in seconds (0<timeout<464, default=80)
> + nowayout:
> + Watchdog cannot be stopped once started
> (default=kernel config parameter)
> +
> -------------------------------------------------
> +
> nuc900_wdt:
> -heartbeat: Watchdog heartbeats in seconds.
> + heartbeat:
> + Watchdog heartbeats in seconds.
> (default = 15)
> -nowayout: Watchdog cannot be stopped once started
> + nowayout:
> + Watchdog cannot be stopped once started
> (default=kernel config parameter)
> +
> -------------------------------------------------
> +
> omap_wdt:
> -timer_margin: initial watchdog timeout (in seconds)
> -early_enable: Watchdog is started on module insertion (default=0
> -nowayout: Watchdog cannot be stopped once started
> + timer_margin:
> + initial watchdog timeout (in seconds)
> + early_enable:
> + Watchdog is started on module insertion (default=0
> + nowayout:
> + Watchdog cannot be stopped once started
> (default=kernel config parameter)
> +
> -------------------------------------------------
> +
> orion_wdt:
> -heartbeat: Initial watchdog heartbeat in seconds
> -nowayout: Watchdog cannot be stopped once started
> + heartbeat:
> + Initial watchdog heartbeat in seconds
> + nowayout:
> + Watchdog cannot be stopped once started
> (default=kernel config parameter)
> +
> -------------------------------------------------
> +
> pc87413_wdt:
> -io: pc87413 WDT I/O port (default: io).
> -timeout: Watchdog timeout in minutes (default=timeout).
> -nowayout: Watchdog cannot be stopped once started
> + io:
> + pc87413 WDT I/O port (default: io).
> + timeout:
> + Watchdog timeout in minutes (default=timeout).
> + nowayout:
> + Watchdog cannot be stopped once started
> (default=kernel config parameter)
> +
> -------------------------------------------------
> +
> pika_wdt:
> -heartbeat: Watchdog heartbeats in seconds. (default = 15)
> -nowayout: Watchdog cannot be stopped once started
> + heartbeat:
> + Watchdog heartbeats in seconds. (default = 15)
> + nowayout:
> + Watchdog cannot be stopped once started
> (default=kernel config parameter)
> +
> -------------------------------------------------
> +
> pnx4008_wdt:
> -heartbeat: Watchdog heartbeat period in seconds from 1 to 60, default 19
> -nowayout: Set to 1 to keep watchdog running after device release
> + heartbeat:
> + Watchdog heartbeat period in seconds from 1 to 60, default 19
> + nowayout:
> + Set to 1 to keep watchdog running after device release
> +
> -------------------------------------------------
> +
> pnx833x_wdt:
> -timeout: Watchdog timeout in Mhz. (68Mhz clock), default=2040000000 (30 seconds)
> -nowayout: Watchdog cannot be stopped once started
> + timeout:
> + Watchdog timeout in Mhz. (68Mhz clock), default=2040000000 (30 seconds)
> + nowayout:
> + Watchdog cannot be stopped once started
> (default=kernel config parameter)
> -start_enabled: Watchdog is started on module insertion (default=1)
> + start_enabled:
> + Watchdog is started on module insertion (default=1)
> +
> -------------------------------------------------
> +
> rc32434_wdt:
> -timeout: Watchdog timeout value, in seconds (default=20)
> -nowayout: Watchdog cannot be stopped once started
> + timeout:
> + Watchdog timeout value, in seconds (default=20)
> + nowayout:
> + Watchdog cannot be stopped once started
> (default=kernel config parameter)
> +
> -------------------------------------------------
> +
> riowd:
> -riowd_timeout: Watchdog timeout in minutes (default=1)
> + riowd_timeout:
> + Watchdog timeout in minutes (default=1)
> +
> -------------------------------------------------
> +
> s3c2410_wdt:
> -tmr_margin: Watchdog tmr_margin in seconds. (default=15)
> -tmr_atboot: Watchdog is started at boot time if set to 1, default=0
> -nowayout: Watchdog cannot be stopped once started
> + tmr_margin:
> + Watchdog tmr_margin in seconds. (default=15)
> + tmr_atboot:
> + Watchdog is started at boot time if set to 1, default=0
> + nowayout:
> + Watchdog cannot be stopped once started
> (default=kernel config parameter)
> -soft_noboot: Watchdog action, set to 1 to ignore reboots, 0 to reboot
> -debug: Watchdog debug, set to >1 for debug, (default 0)
> + soft_noboot:
> + Watchdog action, set to 1 to ignore reboots, 0 to reboot
> + debug:
> + Watchdog debug, set to >1 for debug, (default 0)
> +
> -------------------------------------------------
> +
> sa1100_wdt:
> -margin: Watchdog margin in seconds (default 60s)
> + margin:
> + Watchdog margin in seconds (default 60s)
> +
> -------------------------------------------------
> +
> sb_wdog:
> -timeout: Watchdog timeout in microseconds (max/default 8388607 or 8.3ish secs)
> + timeout:
> + Watchdog timeout in microseconds (max/default 8388607 or 8.3ish secs)
> +
> -------------------------------------------------
> +
> sbc60xxwdt:
> -wdt_stop: SBC60xx WDT 'stop' io port (default 0x45)
> -wdt_start: SBC60xx WDT 'start' io port (default 0x443)
> -timeout: Watchdog timeout in seconds. (1<=timeout<=3600, default=30)
> -nowayout: Watchdog cannot be stopped once started
> + wdt_stop:
> + SBC60xx WDT 'stop' io port (default 0x45)
> + wdt_start:
> + SBC60xx WDT 'start' io port (default 0x443)
> + timeout:
> + Watchdog timeout in seconds. (1<=timeout<=3600, default=30)
> + nowayout:
> + Watchdog cannot be stopped once started
> (default=kernel config parameter)
> +
> -------------------------------------------------
> +
> sbc7240_wdt:
> -timeout: Watchdog timeout in seconds. (1<=timeout<=255, default=30)
> -nowayout: Disable watchdog when closing device file
> + timeout:
> + Watchdog timeout in seconds. (1<=timeout<=255, default=30)
> + nowayout:
> + Disable watchdog when closing device file
> +
> -------------------------------------------------
> +
> sbc8360:
> -timeout: Index into timeout table (0-63) (default=27 (60s))
> -nowayout: Watchdog cannot be stopped once started
> + timeout:
> + Index into timeout table (0-63) (default=27 (60s))
> + nowayout:
> + Watchdog cannot be stopped once started
> (default=kernel config parameter)
> +
> -------------------------------------------------
> +
> sbc_epx_c3:
> -nowayout: Watchdog cannot be stopped once started
> + nowayout:
> + Watchdog cannot be stopped once started
> (default=kernel config parameter)
> +
> -------------------------------------------------
> +
> sbc_fitpc2_wdt:
> -margin: Watchdog margin in seconds (default 60s)
> -nowayout: Watchdog cannot be stopped once started
> + margin:
> + Watchdog margin in seconds (default 60s)
> + nowayout:
> + Watchdog cannot be stopped once started
> +
> -------------------------------------------------
> +
> sbsa_gwdt:
> -timeout: Watchdog timeout in seconds. (default 10s)
> -action: Watchdog action at the first stage timeout,
> + timeout:
> + Watchdog timeout in seconds. (default 10s)
> + action:
> + Watchdog action at the first stage timeout,
> set to 0 to ignore, 1 to panic. (default=0)
> -nowayout: Watchdog cannot be stopped once started
> + nowayout:
> + Watchdog cannot be stopped once started
> (default=kernel config parameter)
> +
> -------------------------------------------------
> +
> sc1200wdt:
> -isapnp: When set to 0 driver ISA PnP support will be disabled (default=1)
> -io: io port
> -timeout: range is 0-255 minutes, default is 1
> -nowayout: Watchdog cannot be stopped once started
> + isapnp:
> + When set to 0 driver ISA PnP support will be disabled (default=1)
> + io:
> + io port
> + timeout:
> + range is 0-255 minutes, default is 1
> + nowayout:
> + Watchdog cannot be stopped once started
> (default=kernel config parameter)
> +
> -------------------------------------------------
> +
> sc520_wdt:
> -timeout: Watchdog timeout in seconds. (1 <= timeout <= 3600, default=30)
> -nowayout: Watchdog cannot be stopped once started
> + timeout:
> + Watchdog timeout in seconds. (1 <= timeout <= 3600, default=30)
> + nowayout:
> + Watchdog cannot be stopped once started
> (default=kernel config parameter)
> +
> -------------------------------------------------
> +
> sch311x_wdt:
> -force_id: Override the detected device ID
> -therm_trip: Should a ThermTrip trigger the reset generator
> -timeout: Watchdog timeout in seconds. 1<= timeout <=15300, default=60
> -nowayout: Watchdog cannot be stopped once started
> + force_id:
> + Override the detected device ID
> + therm_trip:
> + Should a ThermTrip trigger the reset generator
> + timeout:
> + Watchdog timeout in seconds. 1<= timeout <=15300, default=60
> + nowayout:
> + Watchdog cannot be stopped once started
> (default=kernel config parameter)
> +
> -------------------------------------------------
> +
> scx200_wdt:
> -margin: Watchdog margin in seconds
> -nowayout: Disable watchdog shutdown on close
> + margin:
> + Watchdog margin in seconds
> + nowayout:
> + Disable watchdog shutdown on close
> +
> -------------------------------------------------
> +
> shwdt:
> -clock_division_ratio: Clock division ratio. Valid ranges are from 0x5 (1.31ms)
> + clock_division_ratio:
> + Clock division ratio. Valid ranges are from 0x5 (1.31ms)
> to 0x7 (5.25ms). (default=7)
> -heartbeat: Watchdog heartbeat in seconds. (1 <= heartbeat <= 3600, default=30
> -nowayout: Watchdog cannot be stopped once started
> + heartbeat:
> + Watchdog heartbeat in seconds. (1 <= heartbeat <= 3600, default=30
> + nowayout:
> + Watchdog cannot be stopped once started
> (default=kernel config parameter)
> +
> -------------------------------------------------
> +
> smsc37b787_wdt:
> -timeout: range is 1-255 units, default is 60
> -nowayout: Watchdog cannot be stopped once started
> + timeout:
> + range is 1-255 units, default is 60
> + nowayout:
> + Watchdog cannot be stopped once started
> (default=kernel config parameter)
> +
> -------------------------------------------------
> +
> softdog:
> -soft_margin: Watchdog soft_margin in seconds.
> + soft_margin:
> + Watchdog soft_margin in seconds.
> (0 < soft_margin < 65536, default=60)
> -nowayout: Watchdog cannot be stopped once started
> + nowayout:
> + Watchdog cannot be stopped once started
> (default=kernel config parameter)
> -soft_noboot: Softdog action, set to 1 to ignore reboots, 0 to reboot
> + soft_noboot:
> + Softdog action, set to 1 to ignore reboots, 0 to reboot
> (default=0)
> +
> -------------------------------------------------
> +
> stmp3xxx_wdt:
> -heartbeat: Watchdog heartbeat period in seconds from 1 to 4194304, default 19
> + heartbeat:
> + Watchdog heartbeat period in seconds from 1 to 4194304, default 19
> +
> -------------------------------------------------
> +
> tegra_wdt:
> -heartbeat: Watchdog heartbeats in seconds. (default = 120)
> -nowayout: Watchdog cannot be stopped once started
> + heartbeat:
> + Watchdog heartbeats in seconds. (default = 120)
> + nowayout:
> + Watchdog cannot be stopped once started
> (default=kernel config parameter)
> +
> -------------------------------------------------
> +
> ts72xx_wdt:
> -timeout: Watchdog timeout in seconds. (1 <= timeout <= 8, default=8)
> -nowayout: Disable watchdog shutdown on close
> + timeout:
> + Watchdog timeout in seconds. (1 <= timeout <= 8, default=8)
> + nowayout:
> + Disable watchdog shutdown on close
> +
> -------------------------------------------------
> +
> twl4030_wdt:
> -nowayout: Watchdog cannot be stopped once started
> + nowayout:
> + Watchdog cannot be stopped once started
> (default=kernel config parameter)
> +
> -------------------------------------------------
> +
> txx9wdt:
> -timeout: Watchdog timeout in seconds. (0<timeout<N, default=60)
> -nowayout: Watchdog cannot be stopped once started
> + timeout:
> + Watchdog timeout in seconds. (0<timeout<N, default=60)
> + nowayout:
> + Watchdog cannot be stopped once started
> (default=kernel config parameter)
> +
> -------------------------------------------------
> +
> uniphier_wdt:
> -timeout: Watchdog timeout in power of two seconds.
> + timeout:
> + Watchdog timeout in power of two seconds.
> (1 <= timeout <= 128, default=64)
> -nowayout: Watchdog cannot be stopped once started
> + nowayout:
> + Watchdog cannot be stopped once started
> (default=kernel config parameter)
> +
> -------------------------------------------------
> +
> w83627hf_wdt:
> -wdt_io: w83627hf/thf WDT io port (default 0x2E)
> -timeout: Watchdog timeout in seconds. 1 <= timeout <= 255, default=60.
> -nowayout: Watchdog cannot be stopped once started
> + wdt_io:
> + w83627hf/thf WDT io port (default 0x2E)
> + timeout:
> + Watchdog timeout in seconds. 1 <= timeout <= 255, default=60.
> + nowayout:
> + Watchdog cannot be stopped once started
> (default=kernel config parameter)
> +
> -------------------------------------------------
> +
> w83877f_wdt:
> -timeout: Watchdog timeout in seconds. (1<=timeout<=3600, default=30)
> -nowayout: Watchdog cannot be stopped once started
> + timeout:
> + Watchdog timeout in seconds. (1<=timeout<=3600, default=30)
> + nowayout:
> + Watchdog cannot be stopped once started
> (default=kernel config parameter)
> +
> -------------------------------------------------
> +
> w83977f_wdt:
> -timeout: Watchdog timeout in seconds (15..7635), default=45)
> -testmode: Watchdog testmode (1 = no reboot), default=0
> -nowayout: Watchdog cannot be stopped once started
> + timeout:
> + Watchdog timeout in seconds (15..7635), default=45)
> + testmode:
> + Watchdog testmode (1 = no reboot), default=0
> + nowayout:
> + Watchdog cannot be stopped once started
> (default=kernel config parameter)
> +
> -------------------------------------------------
> +
> wafer5823wdt:
> -timeout: Watchdog timeout in seconds. 1 <= timeout <= 255, default=60.
> -nowayout: Watchdog cannot be stopped once started
> + timeout:
> + Watchdog timeout in seconds. 1 <= timeout <= 255, default=60.
> + nowayout:
> + Watchdog cannot be stopped once started
> (default=kernel config parameter)
> +
> -------------------------------------------------
> +
> wdt285:
> -soft_margin: Watchdog timeout in seconds (default=60)
> + soft_margin:
> + Watchdog timeout in seconds (default=60)
> +
> -------------------------------------------------
> +
> wdt977:
> -timeout: Watchdog timeout in seconds (60..15300, default=60)
> -testmode: Watchdog testmode (1 = no reboot), default=0
> -nowayout: Watchdog cannot be stopped once started
> + timeout:
> + Watchdog timeout in seconds (60..15300, default=60)
> + testmode:
> + Watchdog testmode (1 = no reboot), default=0
> + nowayout:
> + Watchdog cannot be stopped once started
> (default=kernel config parameter)
> +
> -------------------------------------------------
> +
> wm831x_wdt:
> -nowayout: Watchdog cannot be stopped once started
> + nowayout:
> + Watchdog cannot be stopped once started
> (default=kernel config parameter)
> +
> -------------------------------------------------
> +
> wm8350_wdt:
> -nowayout: Watchdog cannot be stopped once started
> + nowayout:
> + Watchdog cannot be stopped once started
> (default=kernel config parameter)
> +
> -------------------------------------------------
> +
> sun4v_wdt:
> -timeout_ms: Watchdog timeout in milliseconds 1..180000, default=60000)
> -nowayout: Watchdog cannot be stopped once started
> --------------------------------------------------
> + timeout_ms:
> + Watchdog timeout in milliseconds 1..180000, default=60000)
> + nowayout:
> + Watchdog cannot be stopped once started
> diff --git a/Documentation/watchdog/watchdog-pm.txt b/Documentation/watchdog/watchdog-pm.txt
> index 7a4dd46e0d24..646e1f28f31f 100644
> --- a/Documentation/watchdog/watchdog-pm.txt
> +++ b/Documentation/watchdog/watchdog-pm.txt
> @@ -1,5 +1,7 @@
> +===============================================
> The Linux WatchDog Timer Power Management Guide
> ===============================================
> +
> Last reviewed: 17-Dec-2018
>
> Wolfram Sang <wsa+renesas@sang-engineering.com>
> @@ -16,4 +18,5 @@ On resume, a watchdog timer shall be reset to its selected value to give
> userspace enough time to resume. [1] [2]
>
> [1] https://patchwork.kernel.org/patch/10252209/
> +
> [2] https://patchwork.kernel.org/patch/10711625/
> diff --git a/Documentation/watchdog/wdt.txt b/Documentation/watchdog/wdt.txt
> index ed2f0b860869..d97b0361535b 100644
> --- a/Documentation/watchdog/wdt.txt
> +++ b/Documentation/watchdog/wdt.txt
> @@ -1,11 +1,14 @@
> +============================================================
> +WDT Watchdog Timer Interfaces For The Linux Operating System
> +============================================================
> +
> Last Reviewed: 10/05/2007
>
> - WDT Watchdog Timer Interfaces For The Linux Operating System
> - Alan Cox <alan@lxorguk.ukuu.org.uk>
> +Alan Cox <alan@lxorguk.ukuu.org.uk>
>
> - ICS WDT501-P
> - ICS WDT501-P (no fan tachometer)
> - ICS WDT500-P
> + - ICS WDT501-P
> + - ICS WDT501-P (no fan tachometer)
> + - ICS WDT500-P
>
> All the interfaces provide /dev/watchdog, which when open must be written
> to within a timeout or the machine will reboot. Each write delays the reboot
> @@ -21,19 +24,26 @@ degrees Fahrenheit. Each read returns a single byte giving the temperature.
> The third interface logs kernel messages on additional alert events.
>
> The ICS ISA-bus wdt card cannot be safely probed for. Instead you need to
> -pass IO address and IRQ boot parameters. E.g.:
> +pass IO address and IRQ boot parameters. E.g.::
> +
> wdt.io=0x240 wdt.irq=11
>
> Other "wdt" driver parameters are:
> +
> + =========== ======================================================
> heartbeat Watchdog heartbeat in seconds (default 60)
> nowayout Watchdog cannot be stopped once started (kernel
> - build parameter)
> + build parameter)
> tachometer WDT501-P Fan Tachometer support (0=disable, default=0)
> type WDT501-P Card type (500 or 501, default=500)
> + =========== ======================================================
>
> Features
> --------
> - WDT501P WDT500P
> +
> +================ ======= =======
> + WDT501P WDT500P
> +================ ======= =======
> Reboot Timer X X
> External Reboot X X
> I/O Port Monitor o o
> @@ -42,9 +52,12 @@ Fan Speed X o
> Power Under X o
> Power Over X o
> Overheat X o
> +================ ======= =======
>
> The external event interfaces on the WDT boards are not currently supported.
> Minor numbers are however allocated for it.
>
>
> -Example Watchdog Driver: see samples/watchdog/watchdog-simple.c
> +Example Watchdog Driver:
> +
> + see samples/watchdog/watchdog-simple.c
> --
> 2.20.1
>
^ permalink raw reply [flat|nested] 81+ messages in thread
* [PATCH 39/57] docs: xilinx: convert eemi.txt to ReST
2019-04-16 2:55 [PATCH 00/57] Convert files to ReST Mauro Carvalho Chehab
` (28 preceding siblings ...)
2019-04-16 2:56 ` [PATCH 37/57] docs: watchdog: convert documents to ReST format Mauro Carvalho Chehab
@ 2019-04-16 2:56 ` Mauro Carvalho Chehab
2019-04-16 2:56 ` [PATCH 40/57] docs: scheduler: convert files " Mauro Carvalho Chehab
` (22 subsequent siblings)
52 siblings, 0 replies; 81+ messages in thread
From: Mauro Carvalho Chehab @ 2019-04-16 2:56 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Michal Simek, linux-arm-kernel
This is a very trivial conversion: adjust the title markup
and add a few literal block markups to produce a better
visual when parsed and avoid warnings.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
Documentation/xilinx/eemi.txt | 8 ++++----
1 file changed, 4 insertions(+), 4 deletions(-)
diff --git a/Documentation/xilinx/eemi.txt b/Documentation/xilinx/eemi.txt
index 0ab686c173be..8ca82c782ba6 100644
--- a/Documentation/xilinx/eemi.txt
+++ b/Documentation/xilinx/eemi.txt
@@ -1,6 +1,6 @@
----------------------------------------------------------------------
+====================================
Xilinx Zynq MPSoC EEMI Documentation
----------------------------------------------------------------------
+====================================
Xilinx Zynq MPSoC Firmware Interface
-------------------------------------
@@ -21,7 +21,7 @@ The zynqmp-firmware driver maintain all EEMI APIs in zynqmp_eemi_ops
structure. Any driver who want to communicate with PMC using EEMI APIs
can call zynqmp_pm_get_eemi_ops().
-Example of EEMI ops:
+Example of EEMI ops::
/* zynqmp-firmware driver maintain all EEMI APIs */
struct zynqmp_eemi_ops {
@@ -34,7 +34,7 @@ Example of EEMI ops:
.query_data = zynqmp_pm_query_data,
};
-Example of EEMI ops usage:
+Example of EEMI ops usage::
static const struct zynqmp_eemi_ops *eemi_ops;
u32 ret_payload[PAYLOAD_ARG_CNT];
--
2.20.1
^ permalink raw reply related [flat|nested] 81+ messages in thread* [PATCH 40/57] docs: scheduler: convert files to ReST
2019-04-16 2:55 [PATCH 00/57] Convert files to ReST Mauro Carvalho Chehab
` (29 preceding siblings ...)
2019-04-16 2:56 ` [PATCH 39/57] docs: xilinx: convert eemi.txt to ReST Mauro Carvalho Chehab
@ 2019-04-16 2:56 ` Mauro Carvalho Chehab
2019-04-16 2:56 ` [PATCH 41/57] docs: EDID/HOWTO.txt: convert to ReST and move to kernel-API Mauro Carvalho Chehab
` (21 subsequent siblings)
52 siblings, 0 replies; 81+ messages in thread
From: Mauro Carvalho Chehab @ 2019-04-16 2:56 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet
In order to prepare to add them to the Kernel API book,
convert the files to ReST format.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
Documentation/scheduler/completion.txt | 38 +--
Documentation/scheduler/sched-arch.txt | 18 +-
Documentation/scheduler/sched-bwc.txt | 28 +-
Documentation/scheduler/sched-deadline.txt | 293 +++++++++---------
Documentation/scheduler/sched-design-CFS.txt | 15 +-
Documentation/scheduler/sched-domains.txt | 8 +-
Documentation/scheduler/sched-energy.txt | 47 +--
Documentation/scheduler/sched-nice-design.txt | 6 +-
Documentation/scheduler/sched-rt-group.txt | 28 +-
Documentation/scheduler/sched-stats.txt | 35 ++-
10 files changed, 290 insertions(+), 226 deletions(-)
diff --git a/Documentation/scheduler/completion.txt b/Documentation/scheduler/completion.txt
index e5b9df4d8078..9f039b4f4b09 100644
--- a/Documentation/scheduler/completion.txt
+++ b/Documentation/scheduler/completion.txt
@@ -1,3 +1,4 @@
+================================================
Completions - "wait for completion" barrier APIs
================================================
@@ -46,7 +47,7 @@ it has to wait for it.
To use completions you need to #include <linux/completion.h> and
create a static or dynamic variable of type 'struct completion',
-which has only two fields:
+which has only two fields::
struct completion {
unsigned int done;
@@ -57,7 +58,7 @@ This provides the ->wait waitqueue to place tasks on for waiting (if any), and
the ->done completion flag for indicating whether it's completed or not.
Completions should be named to refer to the event that is being synchronized on.
-A good example is:
+A good example is::
wait_for_completion(&early_console_added);
@@ -81,7 +82,7 @@ have taken place, even if these wait functions return prematurely due to a timeo
or a signal triggering.
Initializing of dynamically allocated completion objects is done via a call to
-init_completion():
+init_completion()::
init_completion(&dynamic_object->done);
@@ -100,7 +101,8 @@ but be aware of other races.
For static declaration and initialization, macros are available.
-For static (or global) declarations in file scope you can use DECLARE_COMPLETION():
+For static (or global) declarations in file scope you can use
+DECLARE_COMPLETION()::
static DECLARE_COMPLETION(setup_done);
DECLARE_COMPLETION(setup_done);
@@ -111,7 +113,7 @@ initialized to 'not done' and doesn't require an init_completion() call.
When a completion is declared as a local variable within a function,
then the initialization should always use DECLARE_COMPLETION_ONSTACK()
explicitly, not just to make lockdep happy, but also to make it clear
-that limited scope had been considered and is intentional:
+that limited scope had been considered and is intentional::
DECLARE_COMPLETION_ONSTACK(setup_done)
@@ -140,11 +142,11 @@ Waiting for completions:
------------------------
For a thread to wait for some concurrent activity to finish, it
-calls wait_for_completion() on the initialized completion structure:
+calls wait_for_completion() on the initialized completion structure::
void wait_for_completion(struct completion *done)
-A typical usage scenario is:
+A typical usage scenario is::
CPU#1 CPU#2
@@ -192,17 +194,17 @@ A common problem that occurs is to have unclean assignment of return types,
so take care to assign return-values to variables of the proper type.
Checking for the specific meaning of return values also has been found
-to be quite inaccurate, e.g. constructs like:
+to be quite inaccurate, e.g. constructs like::
if (!wait_for_completion_interruptible_timeout(...))
... would execute the same code path for successful completion and for the
-interrupted case - which is probably not what you want.
+interrupted case - which is probably not what you want::
int wait_for_completion_interruptible(struct completion *done)
This function marks the task TASK_INTERRUPTIBLE while it is waiting.
-If a signal was received while waiting it will return -ERESTARTSYS; 0 otherwise.
+If a signal was received while waiting it will return -ERESTARTSYS; 0 otherwise::
unsigned long wait_for_completion_timeout(struct completion *done, unsigned long timeout)
@@ -214,7 +216,7 @@ Timeouts are preferably calculated with msecs_to_jiffies() or usecs_to_jiffies()
to make the code largely HZ-invariant.
If the returned timeout value is deliberately ignored a comment should probably explain
-why (e.g. see drivers/mfd/wm8350-core.c wm8350_read_auxadc()).
+why (e.g. see drivers/mfd/wm8350-core.c wm8350_read_auxadc())::
long wait_for_completion_interruptible_timeout(struct completion *done, unsigned long timeout)
@@ -225,14 +227,14 @@ jiffies if completion occurred.
Further variants include _killable which uses TASK_KILLABLE as the
designated tasks state and will return -ERESTARTSYS if it is interrupted,
-or 0 if completion was achieved. There is a _timeout variant as well:
+or 0 if completion was achieved. There is a _timeout variant as well::
long wait_for_completion_killable(struct completion *done)
long wait_for_completion_killable_timeout(struct completion *done, unsigned long timeout)
The _io variants wait_for_completion_io() behave the same as the non-_io
variants, except for accounting waiting time as 'waiting on IO', which has
-an impact on how the task is accounted in scheduling/IO stats:
+an impact on how the task is accounted in scheduling/IO stats::
void wait_for_completion_io(struct completion *done)
unsigned long wait_for_completion_io_timeout(struct completion *done, unsigned long timeout)
@@ -243,11 +245,11 @@ Signaling completions:
A thread that wants to signal that the conditions for continuation have been
achieved calls complete() to signal exactly one of the waiters that it can
-continue:
+continue::
void complete(struct completion *done)
-... or calls complete_all() to signal all current and future waiters:
+... or calls complete_all() to signal all current and future waiters::
void complete_all(struct completion *done)
@@ -268,7 +270,7 @@ probably are a design bug.
Signaling completion from IRQ context is fine as it will appropriately
lock with spin_lock_irqsave()/spin_unlock_irqrestore() and it will never
-sleep.
+sleep.
try_wait_for_completion()/completion_done():
@@ -276,14 +278,14 @@ try_wait_for_completion()/completion_done():
The try_wait_for_completion() function will not put the thread on the wait
queue but rather returns false if it would need to enqueue (block) the thread,
-else it consumes one posted completion and returns true.
+else it consumes one posted completion and returns true::
bool try_wait_for_completion(struct completion *done)
Finally, to check the state of a completion without changing it in any way,
call completion_done(), which returns false if there are no posted
completions that were not yet consumed by waiters (implying that there are
-waiters) and true otherwise;
+waiters) and true otherwise::
bool completion_done(struct completion *done)
diff --git a/Documentation/scheduler/sched-arch.txt b/Documentation/scheduler/sched-arch.txt
index a2f27bbf2cba..0eaec669790a 100644
--- a/Documentation/scheduler/sched-arch.txt
+++ b/Documentation/scheduler/sched-arch.txt
@@ -1,4 +1,6 @@
- CPU Scheduler implementation hints for architecture specific code
+=================================================================
+CPU Scheduler implementation hints for architecture specific code
+=================================================================
Nick Piggin, 2005
@@ -35,9 +37,10 @@ Your cpu_idle routines need to obey the following rules:
4. The only time interrupts need to be disabled when checking
need_resched is if we are about to sleep the processor until
the next interrupt (this doesn't provide any protection of
- need_resched, it prevents losing an interrupt).
+ need_resched, it prevents losing an interrupt):
+
+ 4a. Common problem with this type of sleep appears to be::
- 4a. Common problem with this type of sleep appears to be:
local_irq_disable();
if (!need_resched()) {
local_irq_enable();
@@ -51,10 +54,10 @@ Your cpu_idle routines need to obey the following rules:
although it may be reasonable to do some background work or enter
a low CPU priority.
- 5a. If TIF_POLLING_NRFLAG is set, and we do decide to enter
- an interrupt sleep, it needs to be cleared then a memory
- barrier issued (followed by a test of need_resched with
- interrupts disabled, as explained in 3).
+ - 5a. If TIF_POLLING_NRFLAG is set, and we do decide to enter
+ an interrupt sleep, it needs to be cleared then a memory
+ barrier issued (followed by a test of need_resched with
+ interrupts disabled, as explained in 3).
arch/x86/kernel/process.c has examples of both polling and
sleeping idle functions.
@@ -71,4 +74,3 @@ sh64 - Is sleeping racy vs interrupts? (See #4a)
sparc - IRQs on at this point(?), change local_irq_save to _disable.
- TODO: needs secondary CPUs to disable preempt (See #1)
-
diff --git a/Documentation/scheduler/sched-bwc.txt b/Documentation/scheduler/sched-bwc.txt
index f6b1873f68ab..4ee2bd2f791d 100644
--- a/Documentation/scheduler/sched-bwc.txt
+++ b/Documentation/scheduler/sched-bwc.txt
@@ -1,3 +1,4 @@
+=====================
CFS Bandwidth Control
=====================
@@ -27,7 +28,8 @@ cpu.cfs_quota_us: the total available run-time within a period (in microseconds)
cpu.cfs_period_us: the length of a period (in microseconds)
cpu.stat: exports throttling statistics [explained further below]
-The default values are:
+The default values are::
+
cpu.cfs_period_us=100ms
cpu.cfs_quota=-1
@@ -55,7 +57,8 @@ For efficiency run-time is transferred between the global pool and CPU local
on large systems. The amount transferred each time such an update is required
is described as the "slice".
-This is tunable via procfs:
+This is tunable via procfs::
+
/proc/sys/kernel/sched_cfs_bandwidth_slice_us (default=5ms)
Larger slice values will reduce transfer overheads, while smaller values allow
@@ -66,6 +69,7 @@ Statistics
A group's bandwidth statistics are exported via 3 fields in cpu.stat.
cpu.stat:
+
- nr_periods: Number of enforcement intervals that have elapsed.
- nr_throttled: Number of times the group has been throttled/limited.
- throttled_time: The total time duration (in nanoseconds) for which entities
@@ -78,12 +82,15 @@ Hierarchical considerations
The interface enforces that an individual entity's bandwidth is always
attainable, that is: max(c_i) <= C. However, over-subscription in the
aggregate case is explicitly allowed to enable work-conserving semantics
-within a hierarchy.
+within a hierarchy:
+
e.g. \Sum (c_i) may exceed C
+
[ Where C is the parent's bandwidth, and c_i its children ]
There are two ways in which a group may become throttled:
+
a. it fully consumes its own quota within a period
b. a parent's quota is fully consumed within its period
@@ -92,7 +99,7 @@ be allowed to until the parent's runtime is refreshed.
Examples
--------
-1. Limit a group to 1 CPU worth of runtime.
+1. Limit a group to 1 CPU worth of runtime::
If period is 250ms and quota is also 250ms, the group will get
1 CPU worth of runtime every 250ms.
@@ -100,10 +107,10 @@ Examples
# echo 250000 > cpu.cfs_quota_us /* quota = 250ms */
# echo 250000 > cpu.cfs_period_us /* period = 250ms */
-2. Limit a group to 2 CPUs worth of runtime on a multi-CPU machine.
+2. Limit a group to 2 CPUs worth of runtime on a multi-CPU machine
- With 500ms period and 1000ms quota, the group can get 2 CPUs worth of
- runtime every 500ms.
+ With 500ms period and 1000ms quota, the group can get 2 CPUs worth of
+ runtime every 500ms::
# echo 1000000 > cpu.cfs_quota_us /* quota = 1000ms */
# echo 500000 > cpu.cfs_period_us /* period = 500ms */
@@ -112,11 +119,10 @@ Examples
3. Limit a group to 20% of 1 CPU.
- With 50ms period, 10ms quota will be equivalent to 20% of 1 CPU.
+ With 50ms period, 10ms quota will be equivalent to 20% of 1 CPU::
# echo 10000 > cpu.cfs_quota_us /* quota = 10ms */
# echo 50000 > cpu.cfs_period_us /* period = 50ms */
- By using a small period here we are ensuring a consistent latency
- response at the expense of burst capacity.
-
+ By using a small period here we are ensuring a consistent latency
+ response at the expense of burst capacity.
diff --git a/Documentation/scheduler/sched-deadline.txt b/Documentation/scheduler/sched-deadline.txt
index b14e03ff3528..12b8147b7995 100644
--- a/Documentation/scheduler/sched-deadline.txt
+++ b/Documentation/scheduler/sched-deadline.txt
@@ -1,29 +1,29 @@
- Deadline Task Scheduling
- ------------------------
+========================
+Deadline Task Scheduling
+========================
-CONTENTS
-========
+.. CONTENTS
- 0. WARNING
- 1. Overview
- 2. Scheduling algorithm
- 2.1 Main algorithm
- 2.2 Bandwidth reclaiming
- 3. Scheduling Real-Time Tasks
- 3.1 Definitions
- 3.2 Schedulability Analysis for Uniprocessor Systems
- 3.3 Schedulability Analysis for Multiprocessor Systems
- 3.4 Relationship with SCHED_DEADLINE Parameters
- 4. Bandwidth management
- 4.1 System-wide settings
- 4.2 Task interface
- 4.3 Default behavior
- 4.4 Behavior of sched_yield()
- 5. Tasks CPU affinity
- 5.1 SCHED_DEADLINE and cpusets HOWTO
- 6. Future plans
- A. Test suite
- B. Minimal main()
+ 0. WARNING
+ 1. Overview
+ 2. Scheduling algorithm
+ 2.1 Main algorithm
+ 2.2 Bandwidth reclaiming
+ 3. Scheduling Real-Time Tasks
+ 3.1 Definitions
+ 3.2 Schedulability Analysis for Uniprocessor Systems
+ 3.3 Schedulability Analysis for Multiprocessor Systems
+ 3.4 Relationship with SCHED_DEADLINE Parameters
+ 4. Bandwidth management
+ 4.1 System-wide settings
+ 4.2 Task interface
+ 4.3 Default behavior
+ 4.4 Behavior of sched_yield()
+ 5. Tasks CPU affinity
+ 5.1 SCHED_DEADLINE and cpusets HOWTO
+ 6. Future plans
+ A. Test suite
+ B. Minimal main()
0. WARNING
@@ -44,7 +44,7 @@ CONTENTS
2. Scheduling algorithm
-==================
+=======================
2.1 Main algorithm
------------------
@@ -80,7 +80,7 @@ CONTENTS
a "remaining runtime". These two parameters are initially set to 0;
- When a SCHED_DEADLINE task wakes up (becomes ready for execution),
- the scheduler checks if
+ the scheduler checks if::
remaining runtime runtime
---------------------------------- > ---------
@@ -97,7 +97,7 @@ CONTENTS
left unchanged;
- When a SCHED_DEADLINE task executes for an amount of time t, its
- remaining runtime is decreased as
+ remaining runtime is decreased as::
remaining runtime = remaining runtime - t
@@ -112,7 +112,7 @@ CONTENTS
- When the current time is equal to the replenishment time of a
throttled task, the scheduling deadline and the remaining runtime are
- updated as
+ updated as::
scheduling deadline = scheduling deadline + period
remaining runtime = remaining runtime + runtime
@@ -129,7 +129,7 @@ CONTENTS
Reclamation of Unused Bandwidth) algorithm [15, 16, 17] and it is enabled
when flag SCHED_FLAG_RECLAIM is set.
- The following diagram illustrates the state names for tasks handled by GRUB:
+ The following diagram illustrates the state names for tasks handled by GRUB::
------------
(d) | Active |
@@ -168,7 +168,7 @@ CONTENTS
breaking the real-time guarantees.
The 0-lag time for a task entering the ActiveNonContending state is
- computed as
+ computed as::
(runtime * dl_period)
deadline - ---------------------
@@ -183,7 +183,7 @@ CONTENTS
the task's utilization must be removed from the previous runqueue's active
utilization and must be added to the new runqueue's active utilization.
In order to avoid races between a task waking up on a runqueue while the
- "inactive timer" is running on a different CPU, the "dl_non_contending"
+ "inactive timer" is running on a different CPU, the "dl_non_contending"
flag is used to indicate that a task is not on a runqueue but is active
(so, the flag is set when the task blocks and is cleared when the
"inactive timer" fires or when the task wakes up).
@@ -222,36 +222,36 @@ CONTENTS
Let's now see a trivial example of two deadline tasks with runtime equal
- to 4 and period equal to 8 (i.e., bandwidth equal to 0.5):
+ to 4 and period equal to 8 (i.e., bandwidth equal to 0.5)::
- A Task T1
- |
- | |
- | |
- |-------- |----
- | | V
- |---|---|---|---|---|---|---|---|--------->t
- 0 1 2 3 4 5 6 7 8
+ A Task T1
+ |
+ | |
+ | |
+ |-------- |----
+ | | V
+ |---|---|---|---|---|---|---|---|--------->t
+ 0 1 2 3 4 5 6 7 8
- A Task T2
- |
- | |
- | |
- | ------------------------|
- | | V
- |---|---|---|---|---|---|---|---|--------->t
- 0 1 2 3 4 5 6 7 8
+ A Task T2
+ |
+ | |
+ | |
+ | ------------------------|
+ | | V
+ |---|---|---|---|---|---|---|---|--------->t
+ 0 1 2 3 4 5 6 7 8
- A running_bw
- |
- 1 ----------------- ------
- | | |
- 0.5- -----------------
- | |
- |---|---|---|---|---|---|---|---|--------->t
- 0 1 2 3 4 5 6 7 8
+ A running_bw
+ |
+ 1 ----------------- ------
+ | | |
+ 0.5- -----------------
+ | |
+ |---|---|---|---|---|---|---|---|--------->t
+ 0 1 2 3 4 5 6 7 8
- Time t = 0:
@@ -284,7 +284,7 @@ CONTENTS
2.3 Energy-aware scheduling
-------------------------
+---------------------------
When cpufreq's schedutil governor is selected, SCHED_DEADLINE implements the
GRUB-PA [19] algorithm, reducing the CPU operating frequency to the minimum
@@ -299,15 +299,20 @@ CONTENTS
3. Scheduling Real-Time Tasks
=============================
- * BIG FAT WARNING ******************************************************
- *
- * This section contains a (not-thorough) summary on classical deadline
- * scheduling theory, and how it applies to SCHED_DEADLINE.
- * The reader can "safely" skip to Section 4 if only interested in seeing
- * how the scheduling policy can be used. Anyway, we strongly recommend
- * to come back here and continue reading (once the urge for testing is
- * satisfied :P) to be sure of fully understanding all technical details.
- ************************************************************************
+
+
+ .. BIG FAT WARNING ******************************************************
+
+ .. warning::
+
+ This section contains a (not-thorough) summary on classical deadline
+ scheduling theory, and how it applies to SCHED_DEADLINE.
+ The reader can "safely" skip to Section 4 if only interested in seeing
+ how the scheduling policy can be used. Anyway, we strongly recommend
+ to come back here and continue reading (once the urge for testing is
+ satisfied :P) to be sure of fully understanding all technical details.
+
+ .. ************************************************************************
There are no limitations on what kind of task can exploit this new
scheduling discipline, even if it must be said that it is particularly
@@ -329,6 +334,7 @@ CONTENTS
sporadic with minimum inter-arrival time P is r_{j+1} >= r_j + P. Finally,
d_j = r_j + D, where D is the task's relative deadline.
Summing up, a real-time task can be described as
+
Task = (WCET, D, P)
The utilization of a real-time task is defined as the ratio between its
@@ -352,13 +358,15 @@ CONTENTS
between the finishing time of a job and its absolute deadline).
More precisely, it can be proven that using a global EDF scheduler the
maximum tardiness of each task is smaller or equal than
+
((M − 1) · WCET_max − WCET_min)/(M − (M − 2) · U_max) + WCET_max
+
where WCET_max = max{WCET_i} is the maximum WCET, WCET_min=min{WCET_i}
is the minimum WCET, and U_max = max{WCET_i/P_i} is the maximum
utilization[12].
3.2 Schedulability Analysis for Uniprocessor Systems
-------------------------
+----------------------------------------------------
If M=1 (uniprocessor system), or in case of partitioned scheduling (each
real-time task is statically assigned to one and only one CPU), it is
@@ -370,7 +378,9 @@ CONTENTS
a task as WCET_i/min{D_i,P_i}, and EDF is able to respect all the deadlines
of all the tasks running on a CPU if the sum of the densities of the tasks
running on such a CPU is smaller or equal than 1:
+
sum(WCET_i / min{D_i, P_i}) <= 1
+
It is important to notice that this condition is only sufficient, and not
necessary: there are task sets that are schedulable, but do not respect the
condition. For example, consider the task set {Task_1,Task_2} composed by
@@ -379,7 +389,9 @@ CONTENTS
(Task_1 is scheduled as soon as it is released, and finishes just in time
to respect its deadline; Task_2 is scheduled immediately after Task_1, hence
its response time cannot be larger than 50ms + 10ms = 60ms) even if
+
50 / min{50,100} + 10 / min{100, 100} = 50 / 50 + 10 / 100 = 1.1
+
Of course it is possible to test the exact schedulability of tasks with
D_i != P_i (checking a condition that is both sufficient and necessary),
but this cannot be done by comparing the total utilization or density with
@@ -399,7 +411,7 @@ CONTENTS
4 Linux uses an admission test based on the tasks' utilizations.
3.3 Schedulability Analysis for Multiprocessor Systems
-------------------------
+------------------------------------------------------
On multiprocessor systems with global EDF scheduling (non partitioned
systems), a sufficient test for schedulability can not be based on the
@@ -428,7 +440,9 @@ CONTENTS
between total utilization (or density) and a fixed constant. If all tasks
have D_i = P_i, a sufficient schedulability condition can be expressed in
a simple way:
+
sum(WCET_i / P_i) <= M - (M - 1) · U_max
+
where U_max = max{WCET_i / P_i}[10]. Notice that for U_max = 1,
M - (M - 1) · U_max becomes M - M + 1 = 1 and this schedulability condition
just confirms the Dhall's effect. A more complete survey of the literature
@@ -447,7 +461,7 @@ CONTENTS
the tasks are limited.
3.4 Relationship with SCHED_DEADLINE Parameters
-------------------------
+-----------------------------------------------
Finally, it is important to understand the relationship between the
SCHED_DEADLINE scheduling parameters described in Section 2 (runtime,
@@ -473,6 +487,7 @@ CONTENTS
this task, as it is not possible to respect its temporal constraints.
References:
+
1 - C. L. Liu and J. W. Layland. Scheduling algorithms for multiprogram-
ming in a hard-real-time environment. Journal of the Association for
Computing Machinery, 20(1), 1973.
@@ -596,11 +611,13 @@ CONTENTS
Specifying a periodic/sporadic task that executes for a given amount of
runtime at each instance, and that is scheduled according to the urgency of
its own timing constraints needs, in general, a way of declaring:
+
- a (maximum/typical) instance execution time,
- a minimum interval between consecutive instances,
- a time constraint by which each instance must be completed.
Therefore:
+
* a new struct sched_attr, containing all the necessary fields is
provided;
* the new scheduling related syscalls that manipulate it, i.e.,
@@ -658,21 +675,21 @@ CONTENTS
------------------------------------
An example of a simple configuration (pin a -deadline task to CPU0)
- follows (rt-app is used to create a -deadline task).
+ follows (rt-app is used to create a -deadline task)::
- mkdir /dev/cpuset
- mount -t cgroup -o cpuset cpuset /dev/cpuset
- cd /dev/cpuset
- mkdir cpu0
- echo 0 > cpu0/cpuset.cpus
- echo 0 > cpu0/cpuset.mems
- echo 1 > cpuset.cpu_exclusive
- echo 0 > cpuset.sched_load_balance
- echo 1 > cpu0/cpuset.cpu_exclusive
- echo 1 > cpu0/cpuset.mem_exclusive
- echo $$ > cpu0/tasks
- rt-app -t 100000:10000:d:0 -D5 (it is now actually superfluous to specify
- task affinity)
+ mkdir /dev/cpuset
+ mount -t cgroup -o cpuset cpuset /dev/cpuset
+ cd /dev/cpuset
+ mkdir cpu0
+ echo 0 > cpu0/cpuset.cpus
+ echo 0 > cpu0/cpuset.mems
+ echo 1 > cpuset.cpu_exclusive
+ echo 0 > cpuset.sched_load_balance
+ echo 1 > cpu0/cpuset.cpu_exclusive
+ echo 1 > cpu0/cpuset.mem_exclusive
+ echo $$ > cpu0/tasks
+ rt-app -t 100000:10000:d:0 -D5 # it is now actually superfluous to specify
+ # task affinity
6. Future plans
===============
@@ -711,7 +728,7 @@ Appendix A. Test suite
rt-app is available at: https://github.com/scheduler-tools/rt-app.
Thread parameters can be specified from the command line, with something like
- this:
+ this::
# rt-app -t 100000:10000:d -t 150000:20000:f:10 -D5
@@ -721,27 +738,27 @@ Appendix A. Test suite
of 5 seconds.
More interestingly, configurations can be described with a json file that
- can be passed as input to rt-app with something like this:
+ can be passed as input to rt-app with something like this::
# rt-app my_config.json
The parameters that can be specified with the second method are a superset
of the command line options. Please refer to rt-app documentation for more
- details (<rt-app-sources>/doc/*.json).
+ details (`<rt-app-sources>/doc/*.json`).
The second testing application is a modification of schedtool, called
schedtool-dl, which can be used to setup SCHED_DEADLINE parameters for a
certain pid/application. schedtool-dl is available at:
https://github.com/scheduler-tools/schedtool-dl.git.
- The usage is straightforward:
+ The usage is straightforward::
# schedtool -E -t 10000000:100000000 -e ./my_cpuhog_app
With this, my_cpuhog_app is put to run inside a SCHED_DEADLINE reservation
of 10ms every 100ms (note that parameters are expressed in microseconds).
You can also use schedtool to create a reservation for an already running
- application, given that you know its pid:
+ application, given that you know its pid::
# schedtool -E -t 10000000:100000000 my_app_pid
@@ -750,43 +767,43 @@ Appendix B. Minimal main()
We provide in what follows a simple (ugly) self-contained code snippet
showing how SCHED_DEADLINE reservations can be created by a real-time
- application developer.
-
- #define _GNU_SOURCE
- #include <unistd.h>
- #include <stdio.h>
- #include <stdlib.h>
- #include <string.h>
- #include <time.h>
- #include <linux/unistd.h>
- #include <linux/kernel.h>
- #include <linux/types.h>
- #include <sys/syscall.h>
- #include <pthread.h>
-
- #define gettid() syscall(__NR_gettid)
-
- #define SCHED_DEADLINE 6
-
- /* XXX use the proper syscall numbers */
- #ifdef __x86_64__
- #define __NR_sched_setattr 314
- #define __NR_sched_getattr 315
- #endif
-
- #ifdef __i386__
- #define __NR_sched_setattr 351
- #define __NR_sched_getattr 352
- #endif
-
- #ifdef __arm__
- #define __NR_sched_setattr 380
- #define __NR_sched_getattr 381
- #endif
-
- static volatile int done;
-
- struct sched_attr {
+ application developer::
+
+ #define _GNU_SOURCE
+ #include <unistd.h>
+ #include <stdio.h>
+ #include <stdlib.h>
+ #include <string.h>
+ #include <time.h>
+ #include <linux/unistd.h>
+ #include <linux/kernel.h>
+ #include <linux/types.h>
+ #include <sys/syscall.h>
+ #include <pthread.h>
+
+ #define gettid() syscall(__NR_gettid)
+
+ #define SCHED_DEADLINE 6
+
+ /* XXX use the proper syscall numbers */
+ #ifdef __x86_64__
+ #define __NR_sched_setattr 314
+ #define __NR_sched_getattr 315
+ #endif
+
+ #ifdef __i386__
+ #define __NR_sched_setattr 351
+ #define __NR_sched_getattr 352
+ #endif
+
+ #ifdef __arm__
+ #define __NR_sched_setattr 380
+ #define __NR_sched_getattr 381
+ #endif
+
+ static volatile int done;
+
+ struct sched_attr {
__u32 size;
__u32 sched_policy;
@@ -802,25 +819,25 @@ Appendix B. Minimal main()
__u64 sched_runtime;
__u64 sched_deadline;
__u64 sched_period;
- };
+ };
- int sched_setattr(pid_t pid,
+ int sched_setattr(pid_t pid,
const struct sched_attr *attr,
unsigned int flags)
- {
+ {
return syscall(__NR_sched_setattr, pid, attr, flags);
- }
+ }
- int sched_getattr(pid_t pid,
+ int sched_getattr(pid_t pid,
struct sched_attr *attr,
unsigned int size,
unsigned int flags)
- {
+ {
return syscall(__NR_sched_getattr, pid, attr, size, flags);
- }
+ }
- void *run_deadline(void *data)
- {
+ void *run_deadline(void *data)
+ {
struct sched_attr attr;
int x = 0;
int ret;
@@ -851,10 +868,10 @@ Appendix B. Minimal main()
printf("deadline thread dies [%ld]\n", gettid());
return NULL;
- }
+ }
- int main (int argc, char **argv)
- {
+ int main (int argc, char **argv)
+ {
pthread_t thread;
printf("main thread [%ld]\n", gettid());
@@ -868,4 +885,4 @@ Appendix B. Minimal main()
printf("main dies [%ld]\n", gettid());
return 0;
- }
+ }
diff --git a/Documentation/scheduler/sched-design-CFS.txt b/Documentation/scheduler/sched-design-CFS.txt
index edd861c94c1b..82406685365a 100644
--- a/Documentation/scheduler/sched-design-CFS.txt
+++ b/Documentation/scheduler/sched-design-CFS.txt
@@ -1,9 +1,10 @@
- =============
- CFS Scheduler
- =============
+=============
+CFS Scheduler
+=============
1. OVERVIEW
+============
CFS stands for "Completely Fair Scheduler," and is the new "desktop" process
scheduler implemented by Ingo Molnar and merged in Linux 2.6.23. It is the
@@ -27,6 +28,7 @@ is its actual runtime normalized to the total number of running tasks.
2. FEW IMPLEMENTATION DETAILS
+==============================
In CFS the virtual runtime is expressed and tracked via the per-task
p->se.vruntime (nanosec-unit) value. This way, it's possible to accurately
@@ -49,6 +51,7 @@ algorithm variants to recognize sleepers.
3. THE RBTREE
+==============
CFS's design is quite radical: it does not use the old data structures for the
runqueues, but it uses a time-ordered rbtree to build a "timeline" of future
@@ -84,6 +87,7 @@ picked and the current task is preempted.
4. SOME FEATURES OF CFS
+========================
CFS uses nanosecond granularity accounting and does not rely on any jiffies or
other HZ detail. Thus the CFS scheduler has no notion of "timeslices" in the
@@ -113,6 +117,7 @@ result.
5. Scheduling policies
+======================
CFS implements three scheduling policies:
@@ -137,6 +142,7 @@ SCHED_IDLE.
6. SCHEDULING CLASSES
+======================
The new CFS scheduler has been designed in such a way to introduce "Scheduling
Classes," an extensible hierarchy of scheduler modules. These modules
@@ -197,6 +203,7 @@ This is the (partial) list of the hooks:
7. GROUP SCHEDULER EXTENSIONS TO CFS
+=====================================
Normally, the scheduler operates on individual tasks and strives to provide
fair CPU time to each task. Sometimes, it may be desirable to group tasks and
@@ -219,7 +226,7 @@ SCHED_BATCH) tasks.
When CONFIG_FAIR_GROUP_SCHED is defined, a "cpu.shares" file is created for each
group created using the pseudo filesystem. See example steps below to create
-task groups and modify their CPU share using the "cgroups" pseudo filesystem.
+task groups and modify their CPU share using the "cgroups" pseudo filesystem::
# mount -t tmpfs cgroup_root /sys/fs/cgroup
# mkdir /sys/fs/cgroup/cpu
diff --git a/Documentation/scheduler/sched-domains.txt b/Documentation/scheduler/sched-domains.txt
index 4af80b1c05aa..f7504226f445 100644
--- a/Documentation/scheduler/sched-domains.txt
+++ b/Documentation/scheduler/sched-domains.txt
@@ -1,3 +1,7 @@
+=================
+Scheduler Domains
+=================
+
Each CPU has a "base" scheduling domain (struct sched_domain). The domain
hierarchy is built from these base domains via the ->parent pointer. ->parent
MUST be NULL terminated, and domain structures should be per-CPU as they are
@@ -46,7 +50,9 @@ CPU's runqueue and the newly found busiest one and starts moving tasks from it
to our runqueue. The exact number of tasks amounts to an imbalance previously
computed while iterating over this sched domain's groups.
-*** Implementing sched domains ***
+Implementing sched domains
+==========================
+
The "base" domain will "span" the first level of the hierarchy. In the case
of SMT, you'll span all siblings of the physical CPU, with each group being
a single virtual CPU.
diff --git a/Documentation/scheduler/sched-energy.txt b/Documentation/scheduler/sched-energy.txt
index 197d81f4b836..fce5858c9082 100644
--- a/Documentation/scheduler/sched-energy.txt
+++ b/Documentation/scheduler/sched-energy.txt
@@ -1,6 +1,6 @@
- =======================
- Energy Aware Scheduling
- =======================
+=======================
+Energy Aware Scheduling
+=======================
1. Introduction
---------------
@@ -12,7 +12,7 @@ with a minimal impact on throughput. This document aims at providing an
introduction on how EAS works, what are the main design decisions behind it, and
details what is needed to get it to run.
-Before going any further, please note that at the time of writing:
+Before going any further, please note that at the time of writing::
/!\ EAS does not support platforms with symmetric CPU topologies /!\
@@ -33,13 +33,13 @@ To make it clear from the start:
- power = energy/time = [joule/second] = [watt]
The goal of EAS is to minimize energy, while still getting the job done. That
-is, we want to maximize:
+is, we want to maximize::
performance [inst/s]
--------------------
power [W]
-which is equivalent to minimizing:
+which is equivalent to minimizing::
energy [J]
-----------
@@ -97,7 +97,7 @@ domains can contain duplicate elements.
Example 1.
Let us consider a platform with 12 CPUs, split in 3 performance domains
- (pd0, pd4 and pd8), organized as follows:
+ (pd0, pd4 and pd8), organized as follows::
CPUs: 0 1 2 3 4 5 6 7 8 9 10 11
PDs: |--pd0--|--pd4--|---pd8---|
@@ -108,6 +108,7 @@ Example 1.
containing 6 CPUs. The two root domains are denoted rd1 and rd2 in the
above figure. Since pd4 intersects with both rd1 and rd2, it will be
present in the linked list '->pd' attached to each of them:
+
* rd1->pd: pd0 -> pd4
* rd2->pd: pd4 -> pd8
@@ -159,9 +160,9 @@ Example 2.
Each performance domain has three Operating Performance Points (OPPs).
The CPU capacity and power cost associated with each OPP is listed in
the Energy Model table. The util_avg of P is shown on the figures
- below as 'PP'.
+ below as 'PP'::
- CPU util.
+ CPU util.
1024 - - - - - - - Energy Model
+-----------+-------------+
| Little | Big |
@@ -188,8 +189,7 @@ Example 2.
(which is coherent with the behaviour of the schedutil CPUFreq
governor, see Section 6. for more details on this topic).
- Case 1. P is migrated to CPU1
- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ **Case 1. P is migrated to CPU1**::
1024 - - - - - - -
@@ -207,8 +207,7 @@ Example 2.
CPU0 CPU1 CPU2 CPU3
- Case 2. P is migrated to CPU3
- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ **Case 2. P is migrated to CPU3**::
1024 - - - - - - -
@@ -226,8 +225,7 @@ Example 2.
CPU0 CPU1 CPU2 CPU3
- Case 3. P stays on prev_cpu / CPU 0
- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ **Case 3. P stays on prev_cpu / CPU 0**::
1024 - - - - - - -
@@ -324,7 +322,9 @@ hardware properties and on other features of the kernel being enabled. This
section lists these dependencies and provides hints as to how they can be met.
- 6.1 - Asymmetric CPU topology
+6.1 - Asymmetric CPU topology
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
As mentioned in the introduction, EAS is only supported on platforms with
asymmetric CPU topologies for now. This requirement is checked at run-time by
@@ -347,7 +347,8 @@ significant savings on SMP platforms have been observed yet. This restriction
could be amended in the future if proven otherwise.
- 6.2 - Energy Model presence
+6.2 - Energy Model presence
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
EAS uses the EM of a platform to estimate the impact of scheduling decisions on
energy. So, your platform must provide power cost tables to the EM framework in
@@ -358,7 +359,8 @@ Please also note that the scheduling domains need to be re-built after the
EM has been registered in order to start EAS.
- 6.3 - Energy Model complexity
+6.3 - Energy Model complexity
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The task wake-up path is very latency-sensitive. When the EM of a platform is
too complex (too many CPUs, too many performance domains, too many performance
@@ -388,7 +390,8 @@ two possible options:
hence enabling it to cope with larger EMs in reasonable time.
- 6.4 - Schedutil governor
+6.4 - Schedutil governor
+^^^^^^^^^^^^^^^^^^^^^^^^
EAS tries to predict at which OPP will the CPUs be running in the close future
in order to estimate their energy consumption. To do so, it is assumed that OPPs
@@ -405,7 +408,8 @@ frequency requests and energy predictions.
Using EAS with any other governor than schedutil is not supported.
- 6.5 Scale-invariant utilization signals
+6.5 Scale-invariant utilization signals
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
In order to make accurate prediction across CPUs and for all performance
states, EAS needs frequency-invariant and CPU-invariant PELT signals. These can
@@ -416,7 +420,8 @@ Using EAS on a platform that doesn't implement these two callbacks is not
supported.
- 6.6 Multithreading (SMT)
+6.6 Multithreading (SMT)
+^^^^^^^^^^^^^^^^^^^^^^^^
EAS in its current form is SMT unaware and is not able to leverage
multithreaded hardware to save energy. EAS considers threads as independent
diff --git a/Documentation/scheduler/sched-nice-design.txt b/Documentation/scheduler/sched-nice-design.txt
index 3ac1e46d5365..0571f1b47e64 100644
--- a/Documentation/scheduler/sched-nice-design.txt
+++ b/Documentation/scheduler/sched-nice-design.txt
@@ -1,3 +1,7 @@
+=====================
+Scheduler Nice Design
+=====================
+
This document explains the thinking about the revamped and streamlined
nice-levels implementation in the new Linux scheduler.
@@ -14,7 +18,7 @@ much stronger than they were before in 2.4 (and people were happy about
that change), and we also intentionally calibrated the linear timeslice
rule so that nice +19 level would be _exactly_ 1 jiffy. To better
understand it, the timeslice graph went like this (cheesy ASCII art
-alert!):
+alert!)::
A
diff --git a/Documentation/scheduler/sched-rt-group.txt b/Documentation/scheduler/sched-rt-group.txt
index d8fce3e78457..79b30a21c51a 100644
--- a/Documentation/scheduler/sched-rt-group.txt
+++ b/Documentation/scheduler/sched-rt-group.txt
@@ -1,18 +1,18 @@
- Real-Time group scheduling
- --------------------------
+==========================
+Real-Time group scheduling
+==========================
-CONTENTS
-========
+.. CONTENTS
-0. WARNING
-1. Overview
- 1.1 The problem
- 1.2 The solution
-2. The interface
- 2.1 System-wide settings
- 2.2 Default behaviour
- 2.3 Basis for grouping tasks
-3. Future plans
+ 0. WARNING
+ 1. Overview
+ 1.1 The problem
+ 1.2 The solution
+ 2. The interface
+ 2.1 System-wide settings
+ 2.2 Default behaviour
+ 2.3 Basis for grouping tasks
+ 3. Future plans
0. WARNING
@@ -159,9 +159,11 @@ Consider two sibling groups A and B; both have 50% bandwidth, but A's
period is twice the length of B's.
* group A: period=100000us, runtime=50000us
+
- this runs for 0.05s once every 0.1s
* group B: period= 50000us, runtime=25000us
+
- this runs for 0.025s twice every 0.1s (or once every 0.05 sec).
This means that currently a while (1) loop in A will run for the full period of
diff --git a/Documentation/scheduler/sched-stats.txt b/Documentation/scheduler/sched-stats.txt
index 8259b34a66ae..0cb0aa714545 100644
--- a/Documentation/scheduler/sched-stats.txt
+++ b/Documentation/scheduler/sched-stats.txt
@@ -1,3 +1,7 @@
+====================
+Scheduler Statistics
+====================
+
Version 15 of schedstats dropped counters for some sched_yield:
yld_exp_empty, yld_act_empty and yld_both_empty. Otherwise, it is
identical to version 14.
@@ -35,19 +39,23 @@ CPU statistics
cpu<N> 1 2 3 4 5 6 7 8 9
First field is a sched_yield() statistic:
+
1) # of times sched_yield() was called
Next three are schedule() statistics:
+
2) This field is a legacy array expiration count field used in the O(1)
scheduler. We kept it for ABI compatibility, but it is always set to zero.
3) # of times schedule() was called
4) # of times schedule() left the processor idle
Next two are try_to_wake_up() statistics:
+
5) # of times try_to_wake_up() was called
6) # of times try_to_wake_up() was called to wake up the local cpu
Next three are statistics describing scheduling latency:
+
7) sum of all time spent running by tasks on this processor (in jiffies)
8) sum of all time spent waiting to run by tasks on this processor (in
jiffies)
@@ -67,24 +75,23 @@ The first field is a bit mask indicating what cpus this domain operates over.
The next 24 are a variety of load_balance() statistics in grouped into types
of idleness (idle, busy, and newly idle):
- 1) # of times in this domain load_balance() was called when the
+ 1) # of times in this domain load_balance() was called when the
cpu was idle
- 2) # of times in this domain load_balance() checked but found
+ 2) # of times in this domain load_balance() checked but found
the load did not require balancing when the cpu was idle
- 3) # of times in this domain load_balance() tried to move one or
+ 3) # of times in this domain load_balance() tried to move one or
more tasks and failed, when the cpu was idle
- 4) sum of imbalances discovered (if any) with each call to
+ 4) sum of imbalances discovered (if any) with each call to
load_balance() in this domain when the cpu was idle
- 5) # of times in this domain pull_task() was called when the cpu
+ 5) # of times in this domain pull_task() was called when the cpu
was idle
- 6) # of times in this domain pull_task() was called even though
+ 6) # of times in this domain pull_task() was called even though
the target task was cache-hot when idle
- 7) # of times in this domain load_balance() was called but did
+ 7) # of times in this domain load_balance() was called but did
not find a busier queue while the cpu was idle
- 8) # of times in this domain a busier queue was found while the
+ 8) # of times in this domain a busier queue was found while the
cpu was idle but no busier group was found
-
- 9) # of times in this domain load_balance() was called when the
+ 9) # of times in this domain load_balance() was called when the
cpu was busy
10) # of times in this domain load_balance() checked but found the
load did not require balancing when busy
@@ -117,21 +124,25 @@ of idleness (idle, busy, and newly idle):
was just becoming idle but no busier group was found
Next three are active_load_balance() statistics:
+
25) # of times active_load_balance() was called
26) # of times active_load_balance() tried to move a task and failed
27) # of times active_load_balance() successfully moved a task
Next three are sched_balance_exec() statistics:
+
28) sbe_cnt is not used
29) sbe_balanced is not used
30) sbe_pushed is not used
Next three are sched_balance_fork() statistics:
+
31) sbf_cnt is not used
32) sbf_balanced is not used
33) sbf_pushed is not used
Next three are try_to_wake_up() statistics:
+
34) # of times in this domain try_to_wake_up() awoke a task that
last ran on a different cpu in this domain
35) # of times in this domain try_to_wake_up() moved a task to the
@@ -139,10 +150,11 @@ of idleness (idle, busy, and newly idle):
36) # of times in this domain try_to_wake_up() started passive balancing
/proc/<pid>/schedstat
-----------------
+---------------------
schedstats also adds a new /proc/<pid>/schedstat file to include some of
the same information on a per-process level. There are three fields in
this file correlating for that process to:
+
1) time spent on the cpu
2) time spent waiting on a runqueue
3) # of timeslices run on this cpu
@@ -151,4 +163,5 @@ A program could be easily written to make use of these extra fields to
report on how well a particular process or set of processes is faring
under the scheduler's policies. A simple version of such a program is
available at
+
http://eaglet.rain.com/rick/linux/schedstat/v12/latency.c
--
2.20.1
^ permalink raw reply related [flat|nested] 81+ messages in thread* [PATCH 41/57] docs: EDID/HOWTO.txt: convert to ReST and move to kernel-API
2019-04-16 2:55 [PATCH 00/57] Convert files to ReST Mauro Carvalho Chehab
` (30 preceding siblings ...)
2019-04-16 2:56 ` [PATCH 40/57] docs: scheduler: convert files " Mauro Carvalho Chehab
@ 2019-04-16 2:56 ` Mauro Carvalho Chehab
2019-04-16 2:56 ` [PATCH 42/57] docs: connector.txt: convert to ReST Mauro Carvalho Chehab
` (20 subsequent siblings)
52 siblings, 0 replies; 81+ messages in thread
From: Mauro Carvalho Chehab @ 2019-04-16 2:56 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet
Sphinx need to know when a paragraph ends. So, do some adjustments
at the file for it to be properly parsed.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
Documentation/EDID/HOWTO.txt | 29 ++++++++++++++++++-----------
1 file changed, 18 insertions(+), 11 deletions(-)
diff --git a/Documentation/EDID/HOWTO.txt b/Documentation/EDID/HOWTO.txt
index 539871c3b785..9a9b512e0ac9 100644
--- a/Documentation/EDID/HOWTO.txt
+++ b/Documentation/EDID/HOWTO.txt
@@ -1,3 +1,7 @@
+====
+EDID
+====
+
In the good old days when graphics parameters were configured explicitly
in a file called xorg.conf, even broken hardware could be managed.
@@ -34,16 +38,19 @@ Makefile. Please note that the EDID data structure expects the timing
values in a different way as compared to the standard X11 format.
X11:
-HTimings: hdisp hsyncstart hsyncend htotal
-VTimings: vdisp vsyncstart vsyncend vtotal
+ HTimings:
+ hdisp hsyncstart hsyncend htotal
+ VTimings:
+ vdisp vsyncstart vsyncend vtotal
-EDID:
-#define XPIX hdisp
-#define XBLANK htotal-hdisp
-#define XOFFSET hsyncstart-hdisp
-#define XPULSE hsyncend-hsyncstart
+EDID::
-#define YPIX vdisp
-#define YBLANK vtotal-vdisp
-#define YOFFSET vsyncstart-vdisp
-#define YPULSE vsyncend-vsyncstart
+ #define XPIX hdisp
+ #define XBLANK htotal-hdisp
+ #define XOFFSET hsyncstart-hdisp
+ #define XPULSE hsyncend-hsyncstart
+
+ #define YPIX vdisp
+ #define YBLANK vtotal-vdisp
+ #define YOFFSET vsyncstart-vdisp
+ #define YPULSE vsyncend-vsyncstart
--
2.20.1
^ permalink raw reply related [flat|nested] 81+ messages in thread* [PATCH 42/57] docs: connector.txt: convert to ReST
2019-04-16 2:55 [PATCH 00/57] Convert files to ReST Mauro Carvalho Chehab
` (31 preceding siblings ...)
2019-04-16 2:56 ` [PATCH 41/57] docs: EDID/HOWTO.txt: convert to ReST and move to kernel-API Mauro Carvalho Chehab
@ 2019-04-16 2:56 ` Mauro Carvalho Chehab
2019-04-16 2:56 ` [PATCH 43/57] docs: lcd-panel-cgram.txt convert it to ReST and move to admin-guide Mauro Carvalho Chehab
` (19 subsequent siblings)
52 siblings, 0 replies; 81+ messages in thread
From: Mauro Carvalho Chehab @ 2019-04-16 2:56 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet
As it has some function definitions, move them to connector.h.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
Documentation/connector/connector.txt | 128 +++++++++-----------------
include/linux/connector.h | 63 ++++++++++++-
2 files changed, 105 insertions(+), 86 deletions(-)
diff --git a/Documentation/connector/connector.txt b/Documentation/connector/connector.txt
index ab7ca897fab7..2cf9b5adfe2a 100644
--- a/Documentation/connector/connector.txt
+++ b/Documentation/connector/connector.txt
@@ -1,6 +1,6 @@
-/*****************************************/
-Kernel Connector.
-/*****************************************/
+================
+Kernel Connector
+================
Kernel connector - new netlink based userspace <-> kernel space easy
to use communication module.
@@ -12,94 +12,55 @@ identifier, the appropriate callback will be called.
From the userspace point of view it's quite straightforward:
- socket();
- bind();
- send();
- recv();
+ - socket();
+ - bind();
+ - send();
+ - recv();
But if kernelspace wants to use the full power of such connections, the
driver writer must create special sockets, must know about struct sk_buff
handling, etc... The Connector driver allows any kernelspace agents to use
netlink based networking for inter-process communication in a significantly
-easier way:
+easier way::
-int cn_add_callback(struct cb_id *id, char *name, void (*callback) (struct cn_msg *, struct netlink_skb_parms *));
-void cn_netlink_send_multi(struct cn_msg *msg, u16 len, u32 portid, u32 __group, int gfp_mask);
-void cn_netlink_send(struct cn_msg *msg, u32 portid, u32 __group, int gfp_mask);
+ int cn_add_callback(struct cb_id *id, char *name, void (*callback) (struct cn_msg *, struct netlink_skb_parms *));
+ void cn_netlink_send_multi(struct cn_msg *msg, u16 len, u32 portid, u32 __group, int gfp_mask);
+ void cn_netlink_send(struct cn_msg *msg, u32 portid, u32 __group, int gfp_mask);
-struct cb_id
-{
+ struct cb_id
+ {
__u32 idx;
__u32 val;
-};
+ };
idx and val are unique identifiers which must be registered in the
-connector.h header for in-kernel usage. void (*callback) (void *) is a
+connector.h header for in-kernel usage. `void (*callback) (void *)` is a
callback function which will be called when a message with above idx.val
is received by the connector core. The argument for that function must
-be dereferenced to struct cn_msg *.
+be dereferenced to `struct cn_msg *`::
-struct cn_msg
-{
+ struct cn_msg
+ {
struct cb_id id;
__u32 seq;
__u32 ack;
- __u32 len; /* Length of the following data */
+ __u32 len; /* Length of the following data */
__u8 data[0];
-};
+ };
-/*****************************************/
-Connector interfaces.
-/*****************************************/
+Connector interfaces
+====================
-int cn_add_callback(struct cb_id *id, char *name, void (*callback) (struct cn_msg *, struct netlink_skb_parms *));
+ .. kernel-doc:: include/linux/connector.h
- Registers new callback with connector core.
+ Note:
+ When registering new callback user, connector core assigns
+ netlink group to the user which is equal to its id.idx.
- struct cb_id *id - unique connector's user identifier.
- It must be registered in connector.h for legal in-kernel users.
- char *name - connector's callback symbolic name.
- void (*callback) (struct cn..) - connector's callback.
- cn_msg and the sender's credentials
-
-
-void cn_del_callback(struct cb_id *id);
-
- Unregisters new callback with connector core.
-
- struct cb_id *id - unique connector's user identifier.
-
-
-int cn_netlink_send_multi(struct cn_msg *msg, u16 len, u32 portid, u32 __groups, int gfp_mask);
-int cn_netlink_send(struct cn_msg *msg, u32 portid, u32 __groups, int gfp_mask);
-
- Sends message to the specified groups. It can be safely called from
- softirq context, but may silently fail under strong memory pressure.
- If there are no listeners for given group -ESRCH can be returned.
-
- struct cn_msg * - message header(with attached data).
- u16 len - for *_multi multiple cn_msg messages can be sent
- u32 port - destination port.
- If non-zero the message will be sent to the
- given port, which should be set to the
- original sender.
- u32 __group - destination group.
- If port and __group is zero, then appropriate group will
- be searched through all registered connector users,
- and message will be delivered to the group which was
- created for user with the same ID as in msg.
- If __group is not zero, then message will be delivered
- to the specified group.
- int gfp_mask - GFP mask.
-
- Note: When registering new callback user, connector core assigns
- netlink group to the user which is equal to its id.idx.
-
-/*****************************************/
-Protocol description.
-/*****************************************/
+Protocol description
+====================
The current framework offers a transport layer with fixed headers. The
recommended protocol which uses such a header is as following:
@@ -132,9 +93,8 @@ driver (it also registers itself with id={-1, -1}).
As example of this usage can be found in the cn_test.c module which
uses the connector to request notification and to send messages.
-/*****************************************/
-Reliability.
-/*****************************************/
+Reliability
+===========
Netlink itself is not a reliable protocol. That means that messages can
be lost due to memory pressure or process' receiving queue overflowed,
@@ -142,32 +102,31 @@ so caller is warned that it must be prepared. That is why the struct
cn_msg [main connector's message header] contains u32 seq and u32 ack
fields.
-/*****************************************/
-Userspace usage.
-/*****************************************/
+Userspace usage
+===============
2.6.14 has a new netlink socket implementation, which by default does not
allow people to send data to netlink groups other than 1.
So, if you wish to use a netlink socket (for example using connector)
with a different group number, the userspace application must subscribe to
-that group first. It can be achieved by the following pseudocode:
+that group first. It can be achieved by the following pseudocode::
-s = socket(PF_NETLINK, SOCK_DGRAM, NETLINK_CONNECTOR);
+ s = socket(PF_NETLINK, SOCK_DGRAM, NETLINK_CONNECTOR);
-l_local.nl_family = AF_NETLINK;
-l_local.nl_groups = 12345;
-l_local.nl_pid = 0;
+ l_local.nl_family = AF_NETLINK;
+ l_local.nl_groups = 12345;
+ l_local.nl_pid = 0;
-if (bind(s, (struct sockaddr *)&l_local, sizeof(struct sockaddr_nl)) == -1) {
+ if (bind(s, (struct sockaddr *)&l_local, sizeof(struct sockaddr_nl)) == -1) {
perror("bind");
close(s);
return -1;
-}
+ }
-{
+ {
int on = l_local.nl_groups;
setsockopt(s, 270, 1, &on, sizeof(on));
-}
+ }
Where 270 above is SOL_NETLINK, and 1 is a NETLINK_ADD_MEMBERSHIP socket
option. To drop a multicast subscription, one should call the above socket
@@ -180,16 +139,15 @@ group number 12345, you must increment CN_NETLINK_USERS to that number.
Additional 0xf numbers are allocated to be used by non-in-kernel users.
Due to this limitation, group 0xffffffff does not work now, so one can
-not use add/remove connector's group notifications, but as far as I know,
+not use add/remove connector's group notifications, but as far as I know,
only cn_test.c test module used it.
Some work in netlink area is still being done, so things can be changed in
2.6.15 timeframe, if it will happen, documentation will be updated for that
kernel.
-/*****************************************/
Code samples
-/*****************************************/
+============
Sample code for a connector test module and user space can be found
in samples/connector/. To build this code, enable CONFIG_CONNECTOR
diff --git a/include/linux/connector.h b/include/linux/connector.h
index 032102b19645..5aeb15f71b3a 100644
--- a/include/linux/connector.h
+++ b/include/linux/connector.h
@@ -68,10 +68,71 @@ struct cn_dev {
struct cn_queue_dev *cbdev;
};
+/**
+ * cn_add_callback() - Registers new callback with connector core.
+ *
+ * @id: unique connector's user identifier.
+ * It must be registered in connector.h for legal
+ * in-kernel users.
+ * @name: connector's callback symbolic name.
+ * @callback: connector's callback.
+ * parameters are %cn_msg and the sender's credentials
+ */
int cn_add_callback(struct cb_id *id, const char *name,
void (*callback)(struct cn_msg *, struct netlink_skb_parms *));
-void cn_del_callback(struct cb_id *);
+/**
+ * cn_del_callback() - Unregisters new callback with connector core.
+ *
+ * @id: unique connector's user identifier.
+ */
+void cn_del_callback(struct cb_id *id);
+
+
+/**
+ * cn_netlink_send_mult - Sends message to the specified groups.
+ *
+ * @msg: message header(with attached data).
+ * @len: Number of @msg to be sent.
+ * @portid: destination port.
+ * If non-zero the message will be sent to the given port,
+ * which should be set to the original sender.
+ * @group: destination group.
+ * If @portid and @group is zero, then appropriate group will
+ * be searched through all registered connector users, and
+ * message will be delivered to the group which was created
+ * for user with the same ID as in @msg.
+ * If @group is not zero, then message will be delivered
+ * to the specified group.
+ * @gfp_mask: GFP mask.
+ *
+ * It can be safely called from softirq context, but may silently
+ * fail under strong memory pressure.
+ *
+ * If there are no listeners for given group %-ESRCH can be returned.
+ */
int cn_netlink_send_mult(struct cn_msg *msg, u16 len, u32 portid, u32 group, gfp_t gfp_mask);
+
+/**
+ * cn_netlink_send_mult - Sends message to the specified groups.
+ *
+ * @msg: message header(with attached data).
+ * @portid: destination port.
+ * If non-zero the message will be sent to the given port,
+ * which should be set to the original sender.
+ * @group: destination group.
+ * If @portid and @group is zero, then appropriate group will
+ * be searched through all registered connector users, and
+ * message will be delivered to the group which was created
+ * for user with the same ID as in @msg.
+ * If @group is not zero, then message will be delivered
+ * to the specified group.
+ * @gfp_mask: GFP mask.
+ *
+ * It can be safely called from softirq context, but may silently
+ * fail under strong memory pressure.
+ *
+ * If there are no listeners for given group %-ESRCH can be returned.
+ */
int cn_netlink_send(struct cn_msg *msg, u32 portid, u32 group, gfp_t gfp_mask);
int cn_queue_add_callback(struct cn_queue_dev *dev, const char *name,
--
2.20.1
^ permalink raw reply related [flat|nested] 81+ messages in thread* [PATCH 43/57] docs: lcd-panel-cgram.txt convert it to ReST and move to admin-guide
2019-04-16 2:55 [PATCH 00/57] Convert files to ReST Mauro Carvalho Chehab
` (32 preceding siblings ...)
2019-04-16 2:56 ` [PATCH 42/57] docs: connector.txt: convert to ReST Mauro Carvalho Chehab
@ 2019-04-16 2:56 ` Mauro Carvalho Chehab
2019-04-16 2:56 ` [PATCH 44/57] docs: lp855x-driver.txt: convert to ReST and move to kernel-api Mauro Carvalho Chehab
` (18 subsequent siblings)
52 siblings, 0 replies; 81+ messages in thread
From: Mauro Carvalho Chehab @ 2019-04-16 2:56 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet
This small text file describes the usage of parallel port LCD
displays from userspace PoV. So, a good candidate for the
admin guide.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
Documentation/auxdisplay/lcd-panel-cgram.txt | 7 +++++--
1 file changed, 5 insertions(+), 2 deletions(-)
diff --git a/Documentation/auxdisplay/lcd-panel-cgram.txt b/Documentation/auxdisplay/lcd-panel-cgram.txt
index 7f82c905763d..a3eb00c62f53 100644
--- a/Documentation/auxdisplay/lcd-panel-cgram.txt
+++ b/Documentation/auxdisplay/lcd-panel-cgram.txt
@@ -1,3 +1,7 @@
+======================================
+Parallel port LCD/Keypad Panel support
+======================================
+
Some LCDs allow you to define up to 8 characters, mapped to ASCII
characters 0 to 7. The escape code to define a new character is
'\e[LG' followed by one digit from 0 to 7, representing the character
@@ -7,7 +11,7 @@ illuminated pixel with LSB on the right. Lines are numbered from the
top of the character to the bottom. On a 5x7 matrix, only the 5 lower
bits of the 7 first bytes are used for each character. If the string
is incomplete, only complete lines will be redefined. Here are some
-examples :
+examples::
printf "\e[LG0010101050D1F0C04;" => 0 = [enter]
printf "\e[LG1040E1F0000000000;" => 1 = [up]
@@ -21,4 +25,3 @@ examples :
printf "\e[LG00002061E1E060200;" => small speaker
Willy
-
--
2.20.1
^ permalink raw reply related [flat|nested] 81+ messages in thread* [PATCH 44/57] docs: lp855x-driver.txt: convert to ReST and move to kernel-api
2019-04-16 2:55 [PATCH 00/57] Convert files to ReST Mauro Carvalho Chehab
` (33 preceding siblings ...)
2019-04-16 2:56 ` [PATCH 43/57] docs: lcd-panel-cgram.txt convert it to ReST and move to admin-guide Mauro Carvalho Chehab
@ 2019-04-16 2:56 ` Mauro Carvalho Chehab
2019-04-16 2:56 ` [PATCH 45/57] docs: m68k: convert it to ReST file format and add to arch bookset Mauro Carvalho Chehab
` (17 subsequent siblings)
52 siblings, 0 replies; 81+ messages in thread
From: Mauro Carvalho Chehab @ 2019-04-16 2:56 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet
This small file seems to be an attempt to start documenting
backlight drivers.
It contains descriptions of the controls for the driver
with could sound as an somewhat user-faced description, but
it's main focus is to describe, instead, the data that should
be passed via platform data and some driver-specific stuff.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
Documentation/backlight/lp855x-driver.txt | 65 ++++++++++++++---------
1 file changed, 40 insertions(+), 25 deletions(-)
diff --git a/Documentation/backlight/lp855x-driver.txt b/Documentation/backlight/lp855x-driver.txt
index 01bce243d3d7..1e0b224fc397 100644
--- a/Documentation/backlight/lp855x-driver.txt
+++ b/Documentation/backlight/lp855x-driver.txt
@@ -1,9 +1,11 @@
+====================
Kernel driver lp855x
====================
Backlight driver for LP855x ICs
Supported chips:
+
Texas Instruments LP8550, LP8551, LP8552, LP8553, LP8555, LP8556 and
LP8557
@@ -14,53 +16,66 @@ Description
* Brightness control
-Brightness can be controlled by the pwm input or the i2c command.
-The lp855x driver supports both cases.
+ Brightness can be controlled by the pwm input or the i2c command.
+ The lp855x driver supports both cases.
* Device attributes
-1) bl_ctl_mode
-Backlight control mode.
-Value : pwm based or register based
+ 1) bl_ctl_mode
-2) chip_id
-The lp855x chip id.
-Value : lp8550/lp8551/lp8552/lp8553/lp8555/lp8556/lp8557
+ Backlight control mode.
+
+ Value: pwm based or register based
+
+ 2) chip_id
+
+ The lp855x chip id.
+
+ Value: lp8550/lp8551/lp8552/lp8553/lp8555/lp8556/lp8557
Platform data for lp855x
------------------------
For supporting platform specific data, the lp855x platform data can be used.
-* name : Backlight driver name. If it is not defined, default name is set.
-* device_control : Value of DEVICE CONTROL register.
-* initial_brightness : Initial value of backlight brightness.
-* period_ns : Platform specific PWM period value. unit is nano.
- Only valid when brightness is pwm input mode.
-* size_program : Total size of lp855x_rom_data.
-* rom_data : List of new eeprom/eprom registers.
+* name:
+ Backlight driver name. If it is not defined, default name is set.
+* device_control:
+ Value of DEVICE CONTROL register.
+* initial_brightness:
+ Initial value of backlight brightness.
+* period_ns:
+ Platform specific PWM period value. unit is nano.
+ Only valid when brightness is pwm input mode.
+* size_program:
+ Total size of lp855x_rom_data.
+* rom_data:
+ List of new eeprom/eprom registers.
-example 1) lp8552 platform data : i2c register mode with new eeprom data
+Examples
+========
-#define EEPROM_A5_ADDR 0xA5
-#define EEPROM_A5_VAL 0x4f /* EN_VSYNC=0 */
+1) lp8552 platform data: i2c register mode with new eeprom data::
-static struct lp855x_rom_data lp8552_eeprom_arr[] = {
+ #define EEPROM_A5_ADDR 0xA5
+ #define EEPROM_A5_VAL 0x4f /* EN_VSYNC=0 */
+
+ static struct lp855x_rom_data lp8552_eeprom_arr[] = {
{EEPROM_A5_ADDR, EEPROM_A5_VAL},
-};
+ };
-static struct lp855x_platform_data lp8552_pdata = {
+ static struct lp855x_platform_data lp8552_pdata = {
.name = "lcd-bl",
.device_control = I2C_CONFIG(LP8552),
.initial_brightness = INITIAL_BRT,
.size_program = ARRAY_SIZE(lp8552_eeprom_arr),
.rom_data = lp8552_eeprom_arr,
-};
+ };
-example 2) lp8556 platform data : pwm input mode with default rom data
+2) lp8556 platform data: pwm input mode with default rom data::
-static struct lp855x_platform_data lp8556_pdata = {
+ static struct lp855x_platform_data lp8556_pdata = {
.device_control = PWM_CONFIG(LP8556),
.initial_brightness = INITIAL_BRT,
.period_ns = 1000000,
-};
+ };
--
2.20.1
^ permalink raw reply related [flat|nested] 81+ messages in thread* [PATCH 45/57] docs: m68k: convert it to ReST file format and add to arch bookset
2019-04-16 2:55 [PATCH 00/57] Convert files to ReST Mauro Carvalho Chehab
` (34 preceding siblings ...)
2019-04-16 2:56 ` [PATCH 44/57] docs: lp855x-driver.txt: convert to ReST and move to kernel-api Mauro Carvalho Chehab
@ 2019-04-16 2:56 ` Mauro Carvalho Chehab
2019-04-16 2:56 ` [PATCH 46/57] docs: cma/debugfs.txt: convert to ReST and move to admin-guide/mm Mauro Carvalho Chehab
` (16 subsequent siblings)
52 siblings, 0 replies; 81+ messages in thread
From: Mauro Carvalho Chehab @ 2019-04-16 2:56 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet
Convert the m68k kernel-options.txt file to ReST.
The conversion is trivial, as the document is already on a format
close enough to ReST. Just some small adjustments were needed in
order to make it both good for being parsed while keeping it on
a good txt shape.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
Documentation/m68k/kernel-options.txt | 319 ++++++++++++++------------
1 file changed, 173 insertions(+), 146 deletions(-)
diff --git a/Documentation/m68k/kernel-options.txt b/Documentation/m68k/kernel-options.txt
index 79d21246c75a..cabd9419740d 100644
--- a/Documentation/m68k/kernel-options.txt
+++ b/Documentation/m68k/kernel-options.txt
@@ -1,22 +1,24 @@
-
-
- Command Line Options for Linux/m68k
- ===================================
+===================================
+Command Line Options for Linux/m68k
+===================================
Last Update: 2 May 1999
+
Linux/m68k version: 2.2.6
+
Author: Roman.Hodek@informatik.uni-erlangen.de (Roman Hodek)
+
Update: jds@kom.auc.dk (Jes Sorensen) and faq@linux-m68k.org (Chris Lawrence)
0) Introduction
===============
- Often I've been asked which command line options the Linux/m68k
+Often I've been asked which command line options the Linux/m68k
kernel understands, or how the exact syntax for the ... option is, or
... about the option ... . I hope, this document supplies all the
answers...
- Note that some options might be outdated, their descriptions being
+Note that some options might be outdated, their descriptions being
incomplete or missing. Please update the information and send in the
patches.
@@ -38,11 +40,11 @@ argument contains an '=', it is of class 2, and the definition is put
into init's environment. All other arguments are passed to init as
command line options.
- This document describes the valid kernel options for Linux/m68k in
+This document describes the valid kernel options for Linux/m68k in
the version mentioned at the start of this file. Later revisions may
add new such options, and some may be missing in older versions.
- In general, the value (the part after the '=') of an option is a
+In general, the value (the part after the '=') of an option is a
list of values separated by commas. The interpretation of these values
is up to the driver that "owns" the option. This association of
options with drivers is also the reason that some are further
@@ -55,21 +57,21 @@ subdivided.
2.1) root=
----------
-Syntax: root=/dev/<device>
- or: root=<hex_number>
+:Syntax: root=/dev/<device>
+:or: root=<hex_number>
This tells the kernel which device it should mount as the root
filesystem. The device must be a block device with a valid filesystem
on it.
- The first syntax gives the device by name. These names are converted
+The first syntax gives the device by name. These names are converted
into a major/minor number internally in the kernel in an unusual way.
Normally, this "conversion" is done by the device files in /dev, but
this isn't possible here, because the root filesystem (with /dev)
isn't mounted yet... So the kernel parses the name itself, with some
hardcoded name to number mappings. The name must always be a
combination of two or three letters, followed by a decimal number.
-Valid names are:
+Valid names are::
/dev/ram: -> 0x0100 (initial ramdisk)
/dev/hda: -> 0x0300 (first IDE disk)
@@ -81,7 +83,7 @@ Valid names are:
/dev/sde: -> 0x0840 (fifth SCSI disk)
/dev/fd : -> 0x0200 (floppy disk)
- The name must be followed by a decimal number, that stands for the
+The name must be followed by a decimal number, that stands for the
partition number. Internally, the value of the number is just
added to the device number mentioned in the table above. The
exceptions are /dev/ram and /dev/fd, where /dev/ram refers to an
@@ -100,12 +102,12 @@ the kernel command line.
[Strange and maybe uninteresting stuff ON]
- This unusual translation of device names has some strange
+This unusual translation of device names has some strange
consequences: If, for example, you have a symbolic link from /dev/fd
to /dev/fd0D720 as an abbreviation for floppy driver #0 in DD format,
you cannot use this name for specifying the root device, because the
kernel cannot see this symlink before mounting the root FS and it
-isn't in the table above. If you use it, the root device will not be
+isn't in the table above. If you use it, the root device will not be
set at all, without an error message. Another example: You cannot use a
partition on e.g. the sixth SCSI disk as the root filesystem, if you
want to specify it by name. This is, because only the devices up to
@@ -118,7 +120,7 @@ knowledge that each disk uses 16 minors, and write "root=/dev/sde17"
[Strange and maybe uninteresting stuff OFF]
- If the device containing your root partition isn't in the table
+If the device containing your root partition isn't in the table
above, you can also specify it by major and minor numbers. These are
written in hex, with no prefix and no separator between. E.g., if you
have a CD with contents appropriate as a root filesystem in the first
@@ -136,6 +138,7 @@ known partition UUID as the starting point. For example,
if partition 5 of the device has the UUID of
00112233-4455-6677-8899-AABBCCDDEEFF then partition 3 may be found as
follows:
+
PARTUUID=00112233-4455-6677-8899-AABBCCDDEEFF/PARTNROFF=-2
Authoritative information can be found in
@@ -145,8 +148,8 @@ Authoritative information can be found in
2.2) ro, rw
-----------
-Syntax: ro
- or: rw
+:Syntax: ro
+:or: rw
These two options tell the kernel whether it should mount the root
filesystem read-only or read-write. The default is read-only, except
@@ -156,7 +159,7 @@ for ramdisks, which default to read-write.
2.3) debug
----------
-Syntax: debug
+:Syntax: debug
This raises the kernel log level to 10 (the default is 7). This is the
same level as set by the "dmesg" command, just that the maximum level
@@ -166,7 +169,7 @@ selectable by dmesg is 8.
2.4) debug=
-----------
-Syntax: debug=<device>
+:Syntax: debug=<device>
This option causes certain kernel messages be printed to the selected
debugging device. This can aid debugging the kernel, since the
@@ -175,7 +178,7 @@ devices are possible depends on the machine type. There are no checks
for the validity of the device name. If the device isn't implemented,
nothing happens.
- Messages logged this way are in general stack dumps after kernel
+Messages logged this way are in general stack dumps after kernel
memory faults or bad kernel traps, and kernel panics. To be exact: all
messages of level 0 (panic messages) and all messages printed while
the log level is 8 or more (their level doesn't matter). Before stack
@@ -185,19 +188,27 @@ at least 8 can also be set by the "debug" command line option (see
Devices possible for Amiga:
- - "ser": built-in serial port; parameters: 9600bps, 8N1
- - "mem": Save the messages to a reserved area in chip mem. After
+ - "ser":
+ built-in serial port; parameters: 9600bps, 8N1
+ - "mem":
+ Save the messages to a reserved area in chip mem. After
rebooting, they can be read under AmigaOS with the tool
'dmesg'.
Devices possible for Atari:
- - "ser1": ST-MFP serial port ("Modem1"); parameters: 9600bps, 8N1
- - "ser2": SCC channel B serial port ("Modem2"); parameters: 9600bps, 8N1
- - "ser" : default serial port
+ - "ser1":
+ ST-MFP serial port ("Modem1"); parameters: 9600bps, 8N1
+ - "ser2":
+ SCC channel B serial port ("Modem2"); parameters: 9600bps, 8N1
+ - "ser" :
+ default serial port
This is "ser2" for a Falcon, and "ser1" for any other machine
- - "midi": The MIDI port; parameters: 31250bps, 8N1
- - "par" : parallel port
+ - "midi":
+ The MIDI port; parameters: 31250bps, 8N1
+ - "par" :
+ parallel port
+
The printing routine for this implements a timeout for the
case there's no printer connected (else the kernel would
lock up). The timeout is not exact, but usually a few
@@ -205,26 +216,29 @@ Devices possible for Atari:
2.6) ramdisk_size=
--------------
+------------------
-Syntax: ramdisk_size=<size>
+:Syntax: ramdisk_size=<size>
- This option instructs the kernel to set up a ramdisk of the given
+This option instructs the kernel to set up a ramdisk of the given
size in KBytes. Do not use this option if the ramdisk contents are
passed by bootstrap! In this case, the size is selected automatically
and should not be overwritten.
- The only application is for root filesystems on floppy disks, that
+The only application is for root filesystems on floppy disks, that
should be loaded into memory. To do that, select the corresponding
size of the disk as ramdisk size, and set the root device to the disk
drive (with "root=").
2.7) swap=
+
+ I can't find any sign of this option in 2.2.6.
+
2.8) buff=
-----------
- I can't find any sign of these options in 2.2.6.
+ I can't find any sign of this option in 2.2.6.
3) General Device Options (Amiga and Atari)
@@ -233,13 +247,13 @@ drive (with "root=").
3.1) ether=
-----------
-Syntax: ether=[<irq>[,<base_addr>[,<mem_start>[,<mem_end>]]]],<dev-name>
+:Syntax: ether=[<irq>[,<base_addr>[,<mem_start>[,<mem_end>]]]],<dev-name>
- <dev-name> is the name of a net driver, as specified in
+<dev-name> is the name of a net driver, as specified in
drivers/net/Space.c in the Linux source. Most prominent are eth0, ...
eth3, sl0, ... sl3, ppp0, ..., ppp3, dummy, and lo.
- The non-ethernet drivers (sl, ppp, dummy, lo) obviously ignore the
+The non-ethernet drivers (sl, ppp, dummy, lo) obviously ignore the
settings by this options. Also, the existing ethernet drivers for
Linux/m68k (ariadne, a2065, hydra) don't use them because Zorro boards
are really Plug-'n-Play, so the "ether=" option is useless altogether
@@ -249,9 +263,9 @@ for Linux/m68k.
3.2) hd=
--------
-Syntax: hd=<cylinders>,<heads>,<sectors>
+:Syntax: hd=<cylinders>,<heads>,<sectors>
- This option sets the disk geometry of an IDE disk. The first hd=
+This option sets the disk geometry of an IDE disk. The first hd=
option is for the first IDE disk, the second for the second one.
(I.e., you can give this option twice.) In most cases, you won't have
to use this option, since the kernel can obtain the geometry data
@@ -262,9 +276,9 @@ disks.
3.3) max_scsi_luns=
-------------------
-Syntax: max_scsi_luns=<n>
+:Syntax: max_scsi_luns=<n>
- Sets the maximum number of LUNs (logical units) of SCSI devices to
+Sets the maximum number of LUNs (logical units) of SCSI devices to
be scanned. Valid values for <n> are between 1 and 8. Default is 8 if
"Probe all LUNs on each SCSI device" was selected during the kernel
configuration, else 1.
@@ -273,9 +287,9 @@ configuration, else 1.
3.4) st=
--------
-Syntax: st=<buffer_size>,[<write_thres>,[<max_buffers>]]
+:Syntax: st=<buffer_size>,[<write_thres>,[<max_buffers>]]
- Sets several parameters of the SCSI tape driver. <buffer_size> is
+Sets several parameters of the SCSI tape driver. <buffer_size> is
the number of 512-byte buffers reserved for tape operations for each
device. <write_thres> sets the number of blocks which must be filled
to start an actual write operation to the tape. Maximum value is the
@@ -286,9 +300,9 @@ buffers allocated for all tape devices.
3.5) dmasound=
--------------
-Syntax: dmasound=[<buffers>,<buffer-size>[,<catch-radius>]]
+:Syntax: dmasound=[<buffers>,<buffer-size>[,<catch-radius>]]
- This option controls some configurations of the Linux/m68k DMA sound
+This option controls some configurations of the Linux/m68k DMA sound
driver (Amiga and Atari): <buffers> is the number of buffers you want
to use (minimum 4, default 4), <buffer-size> is the size of each
buffer in kilobytes (minimum 4, default 32) and <catch-radius> says
@@ -305,20 +319,22 @@ don't need to expand the sound.
4.1) video=
-----------
-Syntax: video=<fbname>:<sub-options...>
+:Syntax: video=<fbname>:<sub-options...>
The <fbname> parameter specifies the name of the frame buffer,
-eg. most atari users will want to specify `atafb' here. The
+eg. most atari users will want to specify `atafb` here. The
<sub-options> is a comma-separated list of the sub-options listed
below.
-NB: Please notice that this option was renamed from `atavideo' to
- `video' during the development of the 1.3.x kernels, thus you
+NB:
+ Please notice that this option was renamed from `atavideo` to
+ `video` during the development of the 1.3.x kernels, thus you
might need to update your boot-scripts if upgrading to 2.x from
an 1.2.x kernel.
-NBB: The behavior of video= was changed in 2.1.57 so the recommended
-option is to specify the name of the frame buffer.
+NBB:
+ The behavior of video= was changed in 2.1.57 so the recommended
+ option is to specify the name of the frame buffer.
4.1.1) Video Mode
-----------------
@@ -341,11 +357,11 @@ mode, if the hardware allows. Currently defined names are:
- falh2 : 896x608x1, Falcon only
- falh16 : 896x608x4, Falcon only
- If no video mode is given on the command line, the kernel tries the
+If no video mode is given on the command line, the kernel tries the
modes names "default<n>" in turn, until one is possible with the
hardware in use.
- A video mode setting doesn't make sense, if the external driver is
+A video mode setting doesn't make sense, if the external driver is
activated by a "external:" sub-option.
4.1.2) inverse
@@ -358,17 +374,17 @@ option, you can make the background white.
4.1.3) font
-----------
-Syntax: font:<fontname>
+:Syntax: font:<fontname>
Specify the font to use in text modes. Currently you can choose only
-between `VGA8x8', `VGA8x16' and `PEARL8x8'. `VGA8x8' is default, if the
+between `VGA8x8`, `VGA8x16` and `PEARL8x8`. `VGA8x8` is default, if the
vertical size of the display is less than 400 pixel rows. Otherwise, the
-`VGA8x16' font is the default.
+`VGA8x16` font is the default.
-4.1.4) hwscroll_
-----------------
+4.1.4) `hwscroll_`
+------------------
-Syntax: hwscroll_<n>
+:Syntax: `hwscroll_<n>`
The number of additional lines of video memory to reserve for
speeding up the scrolling ("hardware scrolling"). Hardware scrolling
@@ -378,7 +394,7 @@ possible with plain STs and graphics cards (The former because the
base address must be on a 256 byte boundary there, the latter because
the kernel doesn't know how to set the base address at all.)
- By default, <n> is set to the number of visible text lines on the
+By default, <n> is set to the number of visible text lines on the
display. Thus, the amount of video memory is doubled, compared to no
hardware scrolling. You can turn off the hardware scrolling altogether
by setting <n> to 0.
@@ -386,31 +402,31 @@ by setting <n> to 0.
4.1.5) internal:
----------------
-Syntax: internal:<xres>;<yres>[;<xres_max>;<yres_max>;<offset>]
+:Syntax: internal:<xres>;<yres>[;<xres_max>;<yres_max>;<offset>]
This option specifies the capabilities of some extended internal video
hardware, like e.g. OverScan. <xres> and <yres> give the (extended)
dimensions of the screen.
- If your OverScan needs a black border, you have to write the last
+If your OverScan needs a black border, you have to write the last
three arguments of the "internal:". <xres_max> is the maximum line
length the hardware allows, <yres_max> the maximum number of lines.
<offset> is the offset of the visible part of the screen memory to its
physical start, in bytes.
- Often, extended interval video hardware has to be activated somehow.
+Often, extended interval video hardware has to be activated somehow.
For this, see the "sw_*" options below.
4.1.6) external:
----------------
-Syntax:
- external:<xres>;<yres>;<depth>;<org>;<scrmem>[;<scrlen>[;<vgabase>\
- [;<colw>[;<coltype>[;<xres_virtual>]]]]]
+:Syntax:
+ external:<xres>;<yres>;<depth>;<org>;<scrmem>[;<scrlen>[;<vgabase>
+ [;<colw>[;<coltype>[;<xres_virtual>]]]]]
-[I had to break this line...]
+.. I had to break this line...
- This is probably the most complicated parameter... It specifies that
+This is probably the most complicated parameter... It specifies that
you have some external video hardware (a graphics board), and how to
use it under Linux/m68k. The kernel cannot know more about the hardware
than you tell it here! The kernel also is unable to set or change any
@@ -418,38 +434,44 @@ video modes, since it doesn't know about any board internal. So, you
have to switch to that video mode before you start Linux, and cannot
switch to another mode once Linux has started.
- The first 3 parameters of this sub-option should be obvious: <xres>,
+The first 3 parameters of this sub-option should be obvious: <xres>,
<yres> and <depth> give the dimensions of the screen and the number of
planes (depth). The depth is the logarithm to base 2 of the number
of colors possible. (Or, the other way round: The number of colors is
2^depth).
- You have to tell the kernel furthermore how the video memory is
+You have to tell the kernel furthermore how the video memory is
organized. This is done by a letter as <org> parameter:
- 'n': "normal planes", i.e. one whole plane after another
- 'i': "interleaved planes", i.e. 16 bit of the first plane, than 16 bit
+ 'n':
+ "normal planes", i.e. one whole plane after another
+ 'i':
+ "interleaved planes", i.e. 16 bit of the first plane, than 16 bit
of the next, and so on... This mode is used only with the
- built-in Atari video modes, I think there is no card that
- supports this mode.
- 'p': "packed pixels", i.e. <depth> consecutive bits stand for all
- planes of one pixel; this is the most common mode for 8 planes
- (256 colors) on graphic cards
- 't': "true color" (more or less packed pixels, but without a color
- lookup table); usually depth is 24
+ built-in Atari video modes, I think there is no card that
+ supports this mode.
+ 'p':
+ "packed pixels", i.e. <depth> consecutive bits stand for all
+ planes of one pixel; this is the most common mode for 8 planes
+ (256 colors) on graphic cards
+ 't':
+ "true color" (more or less packed pixels, but without a color
+ lookup table); usually depth is 24
For monochrome modes (i.e., <depth> is 1), the <org> letter has a
different meaning:
- 'n': normal colors, i.e. 0=white, 1=black
- 'i': inverted colors, i.e. 0=black, 1=white
+ 'n':
+ normal colors, i.e. 0=white, 1=black
+ 'i':
+ inverted colors, i.e. 0=black, 1=white
- The next important information about the video hardware is the base
+The next important information about the video hardware is the base
address of the video memory. That is given in the <scrmem> parameter,
as a hexadecimal number with a "0x" prefix. You have to find out this
address in the documentation of your hardware.
- The next parameter, <scrlen>, tells the kernel about the size of the
+The next parameter, <scrlen>, tells the kernel about the size of the
video memory. If it's missing, the size is calculated from <xres>,
<yres>, and <depth>. For now, it is not useful to write a value here.
It would be used only for hardware scrolling (which isn't possible
@@ -460,7 +482,7 @@ empty, either by ending the "external:" after the video address or by
writing two consecutive semicolons, if you want to give a <vgabase>
(it is allowed to leave this parameter empty).
- The <vgabase> parameter is optional. If it is not given, the kernel
+The <vgabase> parameter is optional. If it is not given, the kernel
cannot read or write any color registers of the video hardware, and
thus you have to set appropriate colors before you start Linux. But if
your card is somehow VGA compatible, you can tell the kernel the base
@@ -472,18 +494,18 @@ uses the addresses vgabase+0x3c7...vgabase+0x3c9. The <vgabase>
parameter is written in hexadecimal with a "0x" prefix, just as
<scrmem>.
- <colw> is meaningful only if <vgabase> is specified. It tells the
+<colw> is meaningful only if <vgabase> is specified. It tells the
kernel how wide each of the color register is, i.e. the number of bits
per single color (red/green/blue). Default is 6, another quite usual
value is 8.
- Also <coltype> is used together with <vgabase>. It tells the kernel
+Also <coltype> is used together with <vgabase>. It tells the kernel
about the color register model of your gfx board. Currently, the types
"vga" (which is also the default) and "mv300" (SANG MV300) are
implemented.
- Parameter <xres_virtual> is required for ProMST or ET4000 cards where
-the physical linelength differs from the visible length. With ProMST,
+Parameter <xres_virtual> is required for ProMST or ET4000 cards where
+the physical linelength differs from the visible length. With ProMST,
xres_virtual must be set to 2048. For ET4000, xres_virtual depends on the
initialisation of the video-card.
If you're missing a corresponding yres_virtual: the external part is legacy,
@@ -499,13 +521,13 @@ currently works only with the ScreenWonder!
4.1.8) monitorcap:
-------------------
-Syntax: monitorcap:<vmin>;<vmax>;<hmin>;<hmax>
+:Syntax: monitorcap:<vmin>;<vmax>;<hmin>;<hmax>
This describes the capabilities of a multisync monitor. Don't use it
with a fixed-frequency monitor! For now, only the Falcon frame buffer
uses the settings of "monitorcap:".
- <vmin> and <vmax> are the minimum and maximum, resp., vertical frequencies
+<vmin> and <vmax> are the minimum and maximum, resp., vertical frequencies
your monitor can work with, in Hz. <hmin> and <hmax> are the same for
the horizontal frequency, in kHz.
@@ -520,28 +542,28 @@ If this option is given, the framebuffer device doesn't do any video
mode calculations and settings on its own. The only Atari fb device
that does this currently is the Falcon.
- What you reach with this: Settings for unknown video extensions
+What you reach with this: Settings for unknown video extensions
aren't overridden by the driver, so you can still use the mode found
when booting, when the driver doesn't know to set this mode itself.
But this also means, that you can't switch video modes anymore...
- An example where you may want to use "keep" is the ScreenBlaster for
+An example where you may want to use "keep" is the ScreenBlaster for
the Falcon.
4.2) atamouse=
--------------
-Syntax: atamouse=<x-threshold>,[<y-threshold>]
+:Syntax: atamouse=<x-threshold>,[<y-threshold>]
- With this option, you can set the mouse movement reporting threshold.
+With this option, you can set the mouse movement reporting threshold.
This is the number of pixels of mouse movement that have to accumulate
before the IKBD sends a new mouse packet to the kernel. Higher values
reduce the mouse interrupt load and thus reduce the chance of keyboard
overruns. Lower values give a slightly faster mouse responses and
slightly better mouse tracking.
- You can set the threshold in x and y separately, but usually this is
+You can set the threshold in x and y separately, but usually this is
of little practical use. If there's just one number in the option, it
is used for both dimensions. The default value is 2 for both
thresholds.
@@ -550,7 +572,7 @@ thresholds.
4.3) ataflop=
-------------
-Syntax: ataflop=<drive type>[,<trackbuffering>[,<steprateA>[,<steprateB>]]]
+:Syntax: ataflop=<drive type>[,<trackbuffering>[,<steprateA>[,<steprateB>]]]
The drive type may be 0, 1, or 2, for DD, HD, and ED, resp. This
setting affects how many buffers are reserved and which formats are
@@ -563,15 +585,15 @@ Syntax: ataflop=<drive type>[,<trackbuffering>[,<steprateA>[,<steprateB>]]]
no for the Medusa and yes for all others.
With the two following parameters, you can change the default
- steprate used for drive A and B, resp.
+ steprate used for drive A and B, resp.
4.4) atascsi=
-------------
-Syntax: atascsi=<can_queue>[,<cmd_per_lun>[,<scat-gat>[,<host-id>[,<tagged>]]]]
+:Syntax: atascsi=<can_queue>[,<cmd_per_lun>[,<scat-gat>[,<host-id>[,<tagged>]]]]
- This option sets some parameters for the Atari native SCSI driver.
+This option sets some parameters for the Atari native SCSI driver.
Generally, any number of arguments can be omitted from the end. And
for each of the numbers, a negative value means "use default". The
defaults depend on whether TT-style or Falcon-style SCSI is used.
@@ -597,11 +619,14 @@ ignored (others aren't affected).
32). Default: 8/1. (Note: Values > 1 seem to cause problems on a
Falcon, cause not yet known.)
- The <cmd_per_lun> value at a great part determines the amount of
+ The <cmd_per_lun> value at a great part determines the amount of
memory SCSI reserves for itself. The formula is rather
complicated, but I can give you some hints:
- no scatter-gather : cmd_per_lun * 232 bytes
- full scatter-gather: cmd_per_lun * approx. 17 Kbytes
+
+ no scatter-gather:
+ cmd_per_lun * 232 bytes
+ full scatter-gather:
+ cmd_per_lun * approx. 17 Kbytes
<scat-gat>:
Size of the scatter-gather table, i.e. the number of requests
@@ -634,19 +659,23 @@ ignored (others aren't affected).
4.5 switches=
-------------
-Syntax: switches=<list of switches>
+:Syntax: switches=<list of switches>
- With this option you can switch some hardware lines that are often
+With this option you can switch some hardware lines that are often
used to enable/disable certain hardware extensions. Examples are
OverScan, overclocking, ...
- The <list of switches> is a comma-separated list of the following
+The <list of switches> is a comma-separated list of the following
items:
- ikbd: set RTS of the keyboard ACIA high
- midi: set RTS of the MIDI ACIA high
- snd6: set bit 6 of the PSG port A
- snd7: set bit 6 of the PSG port A
+ ikbd:
+ set RTS of the keyboard ACIA high
+ midi:
+ set RTS of the MIDI ACIA high
+ snd6:
+ set bit 6 of the PSG port A
+ snd7:
+ set bit 6 of the PSG port A
It doesn't make sense to mention a switch more than once (no
difference to only once), but you can give as many switches as you
@@ -654,16 +683,16 @@ want to enable different features. The switch lines are set as early
as possible during kernel initialization (even before determining the
present hardware.)
- All of the items can also be prefixed with "ov_", i.e. "ov_ikbd",
-"ov_midi", ... These options are meant for switching on an OverScan
+All of the items can also be prefixed with `ov_`, i.e. `ov_ikbd`,
+`ov_midi`, ... These options are meant for switching on an OverScan
video extension. The difference to the bare option is that the
switch-on is done after video initialization, and somehow synchronized
to the HBLANK. A speciality is that ov_ikbd and ov_midi are switched
off before rebooting, so that OverScan is disabled and TOS boots
correctly.
- If you give an option both, with and without the "ov_" prefix, the
-earlier initialization ("ov_"-less) takes precedence. But the
+If you give an option both, with and without the `ov_` prefix, the
+earlier initialization (`ov_`-less) takes precedence. But the
switching-off on reset still happens in this case.
5) Options for Amiga Only:
@@ -672,10 +701,10 @@ switching-off on reset still happens in this case.
5.1) video=
-----------
-Syntax: video=<fbname>:<sub-options...>
+:Syntax: video=<fbname>:<sub-options...>
The <fbname> parameter specifies the name of the frame buffer, valid
-options are `amifb', `cyber', 'virge', `retz3' and `clgen', provided
+options are `amifb`, `cyber`, 'virge', `retz3` and `clgen`, provided
that the respective frame buffer devices have been compiled into the
kernel (or compiled as loadable modules). The behavior of the <fbname>
option was changed in 2.1.57 so it is now recommended to specify this
@@ -697,9 +726,11 @@ predefined video modes are available:
NTSC modes:
- ntsc : 640x200, 15 kHz, 60 Hz
- ntsc-lace : 640x400, 15 kHz, 60 Hz interlaced
+
PAL modes:
- pal : 640x256, 15 kHz, 50 Hz
- pal-lace : 640x512, 15 kHz, 50 Hz interlaced
+
ECS modes:
- multiscan : 640x480, 29 kHz, 57 Hz
- multiscan-lace : 640x960, 29 kHz, 57 Hz interlaced
@@ -715,6 +746,7 @@ ECS modes:
- dblpal-lace : 640x1024, 27 kHz, 47 Hz interlaced
- dblntsc : 640x200, 27 kHz, 57 Hz doublescan
- dblpal : 640x256, 27 kHz, 47 Hz doublescan
+
VGA modes:
- vga : 640x480, 31 kHz, 60 Hz
- vga70 : 640x400, 31 kHz, 70 Hz
@@ -726,7 +758,7 @@ chipset and 8-bit color for the AGA chipset.
5.1.2) depth
------------
-Syntax: depth:<nr. of bit-planes>
+:Syntax: depth:<nr. of bit-planes>
Specify the number of bit-planes for the selected video-mode.
@@ -739,32 +771,32 @@ Use inverted display (black on white). Functionally the same as the
5.1.4) font
-----------
-Syntax: font:<fontname>
+:Syntax: font:<fontname>
Specify the font to use in text modes. Functionally the same as the
-"font" sub-option for the Atari, except that `PEARL8x8' is used instead
-of `VGA8x8' if the vertical size of the display is less than 400 pixel
+"font" sub-option for the Atari, except that `PEARL8x8` is used instead
+of `VGA8x8` if the vertical size of the display is less than 400 pixel
rows.
5.1.5) monitorcap:
-------------------
-Syntax: monitorcap:<vmin>;<vmax>;<hmin>;<hmax>
+:Syntax: monitorcap:<vmin>;<vmax>;<hmin>;<hmax>
This describes the capabilities of a multisync monitor. For now, only
the color frame buffer uses the settings of "monitorcap:".
- <vmin> and <vmax> are the minimum and maximum, resp., vertical frequencies
+<vmin> and <vmax> are the minimum and maximum, resp., vertical frequencies
your monitor can work with, in Hz. <hmin> and <hmax> are the same for
the horizontal frequency, in kHz.
- The defaults are 50;90;15;38 (Generic Amiga multisync monitor).
+The defaults are 50;90;15;38 (Generic Amiga multisync monitor).
5.2) fd_def_df0=
----------------
-Syntax: fd_def_df0=<value>
+:Syntax: fd_def_df0=<value>
Sets the df0 value for "silent" floppy drives. The value should be in
hexadecimal with "0x" prefix.
@@ -773,7 +805,7 @@ hexadecimal with "0x" prefix.
5.3) wd33c93=
-------------
-Syntax: wd33c93=<sub-options...>
+:Syntax: wd33c93=<sub-options...>
These options affect the A590/A2091, A3000 and GVP Series II SCSI
controllers.
@@ -784,9 +816,9 @@ below.
5.3.1) nosync
-------------
-Syntax: nosync:bitmask
+:Syntax: nosync:bitmask
- bitmask is a byte where the 1st 7 bits correspond with the 7
+bitmask is a byte where the 1st 7 bits correspond with the 7
possible SCSI devices. Set a bit to prevent sync negotiation on that
device. To maintain backwards compatibility, a command-line such as
"wd33c93=255" will be automatically translated to
@@ -796,35 +828,35 @@ all devices, eg. nosync:0xff.
5.3.2) period
-------------
-Syntax: period:ns
+:Syntax: period:ns
- `ns' is the minimum # of nanoseconds in a SCSI data transfer
+`ns` is the minimum # of nanoseconds in a SCSI data transfer
period. Default is 500; acceptable values are 250 - 1000.
5.3.3) disconnect
-----------------
-Syntax: disconnect:x
+:Syntax: disconnect:x
- Specify x = 0 to never allow disconnects, 2 to always allow them.
+Specify x = 0 to never allow disconnects, 2 to always allow them.
x = 1 does 'adaptive' disconnects, which is the default and generally
the best choice.
5.3.4) debug
------------
-Syntax: debug:x
+:Syntax: debug:x
- If `DEBUGGING_ON' is defined, x is a bit mask that causes various
+If `DEBUGGING_ON` is defined, x is a bit mask that causes various
types of debug output to printed - see the DB_xxx defines in
wd33c93.h.
5.3.5) clock
------------
-Syntax: clock:x
+:Syntax: clock:x
- x = clock input in MHz for WD33c93 chip. Normal values would be from
+x = clock input in MHz for WD33c93 chip. Normal values would be from
8 through 20. The default value depends on your hostadapter(s),
default for the A3000 internal controller is 14, for the A2091 it's 8
and for the GVP hostadapters it's either 8 or 14, depending on the
@@ -834,15 +866,15 @@ hostadapters.
5.3.6) next
-----------
- No argument. Used to separate blocks of keywords when there's more
+No argument. Used to separate blocks of keywords when there's more
than one wd33c93-based host adapter in the system.
5.3.7) nodma
------------
-Syntax: nodma:x
+:Syntax: nodma:x
- If x is 1 (or if the option is just written as "nodma"), the WD33c93
+If x is 1 (or if the option is just written as "nodma"), the WD33c93
controller will not use DMA (= direct memory access) to access the
Amiga's memory. This is useful for some systems (like A3000's and
A4000's with the A3640 accelerator, revision 3.0) that have problems
@@ -853,32 +885,27 @@ possible.
5.4) gvp11=
-----------
-Syntax: gvp11=<addr-mask>
+:Syntax: gvp11=<addr-mask>
- The earlier versions of the GVP driver did not handle DMA
+The earlier versions of the GVP driver did not handle DMA
address-mask settings correctly which made it necessary for some
people to use this option, in order to get their GVP controller
running under Linux. These problems have hopefully been solved and the
use of this option is now highly unrecommended!
- Incorrect use can lead to unpredictable behavior, so please only use
+Incorrect use can lead to unpredictable behavior, so please only use
this option if you *know* what you are doing and have a reason to do
so. In any case if you experience problems and need to use this
option, please inform us about it by mailing to the Linux/68k kernel
mailing list.
- The address mask set by this option specifies which addresses are
+The address mask set by this option specifies which addresses are
valid for DMA with the GVP Series II SCSI controller. An address is
valid, if no bits are set except the bits that are set in the mask,
too.
- Some versions of the GVP can only DMA into a 24 bit address range,
+Some versions of the GVP can only DMA into a 24 bit address range,
some can address a 25 bit address range while others can use the whole
32 bit address range for DMA. The correct setting depends on your
controller and should be autodetected by the driver. An example is the
24 bit region which is specified by a mask of 0x00fffffe.
-
-
-/* Local Variables: */
-/* mode: text */
-/* End: */
--
2.20.1
^ permalink raw reply related [flat|nested] 81+ messages in thread* [PATCH 46/57] docs: cma/debugfs.txt: convert to ReST and move to admin-guide/mm
2019-04-16 2:55 [PATCH 00/57] Convert files to ReST Mauro Carvalho Chehab
` (35 preceding siblings ...)
2019-04-16 2:56 ` [PATCH 45/57] docs: m68k: convert it to ReST file format and add to arch bookset Mauro Carvalho Chehab
@ 2019-04-16 2:56 ` Mauro Carvalho Chehab
2019-04-16 5:21 ` Mike Rapoport
2019-04-16 2:56 ` [PATCH 47/57] docs: console.txt: convert to ReST format Mauro Carvalho Chehab
` (15 subsequent siblings)
52 siblings, 1 reply; 81+ messages in thread
From: Mauro Carvalho Chehab @ 2019-04-16 2:56 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet
The debugfs interface for CMA should be there together with other
mm-related documents.
Convert this small file to ReST and move it to its rightful place.
The conversion is actually quite simple: just add a title for the
document. In order to make it to look better for the audience,
also mark the "echo" command as a literal block.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
Documentation/cma/debugfs.txt | 6 +++++-
1 file changed, 5 insertions(+), 1 deletion(-)
diff --git a/Documentation/cma/debugfs.txt b/Documentation/cma/debugfs.txt
index 6cef20a8cedc..4e06ffabd78a 100644
--- a/Documentation/cma/debugfs.txt
+++ b/Documentation/cma/debugfs.txt
@@ -1,3 +1,7 @@
+=====================
+CMA Debugfs Interface
+=====================
+
The CMA debugfs interface is useful to retrieve basic information out of the
different CMA areas and to test allocation/release in each of the areas.
@@ -12,7 +16,7 @@ The structure of the files created under that directory is as follows:
- [RO] count: Amount of memory in the CMA area.
- [RO] order_per_bit: Order of pages represented by one bit.
- [RO] bitmap: The bitmap of page states in the zone.
- - [WO] alloc: Allocate N pages from that CMA area. For example:
+ - [WO] alloc: Allocate N pages from that CMA area. For example::
echo 5 > <debugfs>/cma/cma-2/alloc
--
2.20.1
^ permalink raw reply related [flat|nested] 81+ messages in thread* Re: [PATCH 46/57] docs: cma/debugfs.txt: convert to ReST and move to admin-guide/mm
2019-04-16 2:56 ` [PATCH 46/57] docs: cma/debugfs.txt: convert to ReST and move to admin-guide/mm Mauro Carvalho Chehab
@ 2019-04-16 5:21 ` Mike Rapoport
2019-04-16 11:35 ` Mauro Carvalho Chehab
0 siblings, 1 reply; 81+ messages in thread
From: Mike Rapoport @ 2019-04-16 5:21 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: Linux Doc Mailing List, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet
Hi Mauro,
On Mon, Apr 15, 2019 at 11:56:11PM -0300, Mauro Carvalho Chehab wrote:
> The debugfs interface for CMA should be there together with other
> mm-related documents.
>
> Convert this small file to ReST and move it to its rightful place.
>
> The conversion is actually quite simple: just add a title for the
> document. In order to make it to look better for the audience,
> also mark the "echo" command as a literal block.
>
> Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
> ---
> Documentation/cma/debugfs.txt | 6 +++++-
It wasn't really moved ;-)
> 1 file changed, 5 insertions(+), 1 deletion(-)
>
> diff --git a/Documentation/cma/debugfs.txt b/Documentation/cma/debugfs.txt
> index 6cef20a8cedc..4e06ffabd78a 100644
> --- a/Documentation/cma/debugfs.txt
> +++ b/Documentation/cma/debugfs.txt
> @@ -1,3 +1,7 @@
> +=====================
> +CMA Debugfs Interface
> +=====================
> +
> The CMA debugfs interface is useful to retrieve basic information out of the
> different CMA areas and to test allocation/release in each of the areas.
>
> @@ -12,7 +16,7 @@ The structure of the files created under that directory is as follows:
> - [RO] count: Amount of memory in the CMA area.
> - [RO] order_per_bit: Order of pages represented by one bit.
> - [RO] bitmap: The bitmap of page states in the zone.
> - - [WO] alloc: Allocate N pages from that CMA area. For example:
> + - [WO] alloc: Allocate N pages from that CMA area. For example::
>
> echo 5 > <debugfs>/cma/cma-2/alloc
>
> --
> 2.20.1
>
--
Sincerely yours,
Mike.
^ permalink raw reply [flat|nested] 81+ messages in thread
* Re: [PATCH 46/57] docs: cma/debugfs.txt: convert to ReST and move to admin-guide/mm
2019-04-16 5:21 ` Mike Rapoport
@ 2019-04-16 11:35 ` Mauro Carvalho Chehab
0 siblings, 0 replies; 81+ messages in thread
From: Mauro Carvalho Chehab @ 2019-04-16 11:35 UTC (permalink / raw)
To: Mike Rapoport
Cc: Linux Doc Mailing List, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet
Em Tue, 16 Apr 2019 08:21:59 +0300
Mike Rapoport <rppt@linux.ibm.com> escreveu:
> Hi Mauro,
>
> On Mon, Apr 15, 2019 at 11:56:11PM -0300, Mauro Carvalho Chehab wrote:
> > The debugfs interface for CMA should be there together with other
> > mm-related documents.
> >
> > Convert this small file to ReST and move it to its rightful place.
> >
> > The conversion is actually quite simple: just add a title for the
> > document. In order to make it to look better for the audience,
> > also mark the "echo" command as a literal block.
> >
> > Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
> > ---
> > Documentation/cma/debugfs.txt | 6 +++++-
>
> It wasn't really moved ;-)
Heh, yeah! The original patch was moving it:
https://git.linuxtv.org/mchehab/experimental.git/commit/?h=all_with_indexes&id=e02d3ba65eba1676b01c82988b8054b88e6e5cdc
It seems I forgot to fix the comment here.
I opted to do just the conversion and place the move patch on a separate
series (yet to be submitted), in order to avoid merge conflicts.
>
> > 1 file changed, 5 insertions(+), 1 deletion(-)
> >
> > diff --git a/Documentation/cma/debugfs.txt b/Documentation/cma/debugfs.txt
> > index 6cef20a8cedc..4e06ffabd78a 100644
> > --- a/Documentation/cma/debugfs.txt
> > +++ b/Documentation/cma/debugfs.txt
> > @@ -1,3 +1,7 @@
> > +=====================
> > +CMA Debugfs Interface
> > +=====================
> > +
> > The CMA debugfs interface is useful to retrieve basic information out of the
> > different CMA areas and to test allocation/release in each of the areas.
> >
> > @@ -12,7 +16,7 @@ The structure of the files created under that directory is as follows:
> > - [RO] count: Amount of memory in the CMA area.
> > - [RO] order_per_bit: Order of pages represented by one bit.
> > - [RO] bitmap: The bitmap of page states in the zone.
> > - - [WO] alloc: Allocate N pages from that CMA area. For example:
> > + - [WO] alloc: Allocate N pages from that CMA area. For example::
> >
> > echo 5 > <debugfs>/cma/cma-2/alloc
> >
> > --
> > 2.20.1
> >
>
Thanks,
Mauro
^ permalink raw reply [flat|nested] 81+ messages in thread
* [PATCH 47/57] docs: console.txt: convert to ReST format
2019-04-16 2:55 [PATCH 00/57] Convert files to ReST Mauro Carvalho Chehab
` (36 preceding siblings ...)
2019-04-16 2:56 ` [PATCH 46/57] docs: cma/debugfs.txt: convert to ReST and move to admin-guide/mm Mauro Carvalho Chehab
@ 2019-04-16 2:56 ` Mauro Carvalho Chehab
2019-04-16 2:56 ` [PATCH 48/57] docs: pti_intel_mid.txt: convert to ReST Mauro Carvalho Chehab
` (14 subsequent siblings)
52 siblings, 0 replies; 81+ messages in thread
From: Mauro Carvalho Chehab @ 2019-04-16 2:56 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet
Convert this small file to ReST in preparation for adding it to
the driver-api book.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
Documentation/console/console.txt | 61 +++++++++++++++++--------------
1 file changed, 33 insertions(+), 28 deletions(-)
diff --git a/Documentation/console/console.txt b/Documentation/console/console.txt
index d73c2ab4beda..8b0205d27a71 100644
--- a/Documentation/console/console.txt
+++ b/Documentation/console/console.txt
@@ -1,3 +1,4 @@
+===============
Console Drivers
===============
@@ -17,25 +18,26 @@ of driver occupying the consoles.) They can only take over the console that is
occupied by the system driver. In the same token, if the modular driver is
released by the console, the system driver will take over.
-Modular drivers, from the programmer's point of view, have to call:
+Modular drivers, from the programmer's point of view, have to call::
do_take_over_console() - load and bind driver to console layer
give_up_console() - unload driver; it will only work if driver
is fully unbound
-In newer kernels, the following are also available:
+In newer kernels, the following are also available::
do_register_con_driver()
do_unregister_con_driver()
If sysfs is enabled, the contents of /sys/class/vtconsole can be
examined. This shows the console backends currently registered by the
-system which are named vtcon<n> where <n> is an integer from 0 to 15. Thus:
+system which are named vtcon<n> where <n> is an integer from 0 to 15.
+Thus::
ls /sys/class/vtconsole
. .. vtcon0 vtcon1
-Each directory in /sys/class/vtconsole has 3 files:
+Each directory in /sys/class/vtconsole has 3 files::
ls /sys/class/vtconsole/vtcon0
. .. bind name uevent
@@ -46,27 +48,29 @@ What do these files signify?
read, or acts to bind or unbind the driver to the virtual consoles
when written to. The possible values are:
- 0 - means the driver is not bound and if echo'ed, commands the driver
+ 0
+ - means the driver is not bound and if echo'ed, commands the driver
to unbind
- 1 - means the driver is bound and if echo'ed, commands the driver to
+ 1
+ - means the driver is bound and if echo'ed, commands the driver to
bind
- 2. name - read-only file. Shows the name of the driver in this format:
+ 2. name - read-only file. Shows the name of the driver in this format::
- cat /sys/class/vtconsole/vtcon0/name
- (S) VGA+
+ cat /sys/class/vtconsole/vtcon0/name
+ (S) VGA+
- '(S)' stands for a (S)ystem driver, i.e., it cannot be directly
- commanded to bind or unbind
+ '(S)' stands for a (S)ystem driver, i.e., it cannot be directly
+ commanded to bind or unbind
- 'VGA+' is the name of the driver
+ 'VGA+' is the name of the driver
- cat /sys/class/vtconsole/vtcon1/name
- (M) frame buffer device
+ cat /sys/class/vtconsole/vtcon1/name
+ (M) frame buffer device
- In this case, '(M)' stands for a (M)odular driver, one that can be
- directly commanded to bind or unbind.
+ In this case, '(M)' stands for a (M)odular driver, one that can be
+ directly commanded to bind or unbind.
3. uevent - ignore this file
@@ -75,14 +79,17 @@ driver takes over the consoles vacated by the driver. Binding, on the other
hand, will bind the driver to the consoles that are currently occupied by a
system driver.
-NOTE1: Binding and unbinding must be selected in Kconfig. It's under:
+NOTE1:
+ Binding and unbinding must be selected in Kconfig. It's under::
-Device Drivers -> Character devices -> Support for binding and unbinding
-console drivers
+ Device Drivers ->
+ Character devices ->
+ Support for binding and unbinding console drivers
-NOTE2: If any of the virtual consoles are in KD_GRAPHICS mode, then binding or
-unbinding will not succeed. An example of an application that sets the console
-to KD_GRAPHICS is X.
+NOTE2:
+ If any of the virtual consoles are in KD_GRAPHICS mode, then binding or
+ unbinding will not succeed. An example of an application that sets the
+ console to KD_GRAPHICS is X.
How useful is this feature? This is very useful for console driver
developers. By unbinding the driver from the console layer, one can unload the
@@ -92,10 +99,10 @@ framebuffer console to VGA console and vice versa, this feature also makes
this possible. (NOTE NOTE NOTE: Please read fbcon.txt under Documentation/fb
for more details.)
-Notes for developers:
-=====================
+Notes for developers
+====================
-do_take_over_console() is now broken up into:
+do_take_over_console() is now broken up into::
do_register_con_driver()
do_bind_con_driver() - private function
@@ -104,7 +111,7 @@ give_up_console() is a wrapper to do_unregister_con_driver(), and a driver must
be fully unbound for this call to succeed. con_is_bound() will check if the
driver is bound or not.
-Guidelines for console driver writers:
+Guidelines for console driver writers
=====================================
In order for binding to and unbinding from the console to properly work,
@@ -140,6 +147,4 @@ The current crop of console drivers should still work correctly, but binding
and unbinding them may cause problems. With minimal fixes, these drivers can
be made to work correctly.
-==========================
Antonino Daplas <adaplas@pol.net>
-
--
2.20.1
^ permalink raw reply related [flat|nested] 81+ messages in thread* [PATCH 48/57] docs: pti_intel_mid.txt: convert to ReST
2019-04-16 2:55 [PATCH 00/57] Convert files to ReST Mauro Carvalho Chehab
` (37 preceding siblings ...)
2019-04-16 2:56 ` [PATCH 47/57] docs: console.txt: convert to ReST format Mauro Carvalho Chehab
@ 2019-04-16 2:56 ` Mauro Carvalho Chehab
2019-04-16 2:56 ` [PATCH 49/57] docs: early-userspace: convert docs " Mauro Carvalho Chehab
` (13 subsequent siblings)
52 siblings, 0 replies; 81+ messages in thread
From: Mauro Carvalho Chehab @ 2019-04-16 2:56 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet
Convert this small file to ReST format.
Most of the conversion were related to adjusting whitespaces
in order for each section to be properly parsed.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
Documentation/pti/pti_intel_mid.txt | 135 ++++++++++++++--------------
1 file changed, 70 insertions(+), 65 deletions(-)
diff --git a/Documentation/pti/pti_intel_mid.txt b/Documentation/pti/pti_intel_mid.txt
index e7a5b6d1f7a9..a674317790ba 100644
--- a/Documentation/pti/pti_intel_mid.txt
+++ b/Documentation/pti/pti_intel_mid.txt
@@ -1,13 +1,17 @@
+=============
+Intel MID PTI
+=============
+
The Intel MID PTI project is HW implemented in Intel Atom
system-on-a-chip designs based on the Parallel Trace
Interface for MIPI P1149.7 cJTAG standard. The kernel solution
-for this platform involves the following files:
+for this platform involves the following files::
-./include/linux/pti.h
-./drivers/.../n_tracesink.h
-./drivers/.../n_tracerouter.c
-./drivers/.../n_tracesink.c
-./drivers/.../pti.c
+ ./include/linux/pti.h
+ ./drivers/.../n_tracesink.h
+ ./drivers/.../n_tracerouter.c
+ ./drivers/.../n_tracesink.c
+ ./drivers/.../pti.c
pti.c is the driver that enables various debugging features
popular on platforms from certain mobile manufacturers.
@@ -24,13 +28,14 @@ kernel->user->kernel context switch overheads of routing
data).
An example debugging usage for this driver system:
- *Hook /dev/ttyPTI0 to syslogd. Opening this port will also start
+
+ * Hook /dev/ttyPTI0 to syslogd. Opening this port will also start
a console device to further capture debugging messages to PTI.
- *Hook /dev/ttyPTI1 to modem debugging data to write to PTI HW.
+ * Hook /dev/ttyPTI1 to modem debugging data to write to PTI HW.
This is where n_tracerouter and n_tracesink are used.
- *Hook /dev/pti to a user-level debugging application for writing
+ * Hook /dev/pti to a user-level debugging application for writing
to PTI HW.
- *Use mipi_* Kernel Driver API in other device drivers for
+ * `Use mipi_` Kernel Driver API in other device drivers for
debugging to PTI by first requesting a PTI write address via
mipi_request_masterchannel(1).
@@ -42,58 +47,58 @@ but is not just blindly executing as 'root'. Keep in mind
the use of ioctl(,TIOCSETD,) is not specific to the n_tracerouter
and n_tracesink line discpline drivers but is a generic
operation for a program to use a line discpline driver
-on a tty port other than the default n_tty.
-
-/////////// To hook up n_tracerouter and n_tracesink /////////
-
-// Note that n_tracerouter depends on n_tracesink.
-#include <errno.h>
-#define ONE_TTY "/dev/ttyOne"
-#define TWO_TTY "/dev/ttyTwo"
-
-// needed global to hand onto ldisc connection
-static int g_fd_source = -1;
-static int g_fd_sink = -1;
-
-// these two vars used to grab LDISC values from loaded ldisc drivers
-// in OS. Look at /proc/tty/ldiscs to get the right numbers from
-// the ldiscs loaded in the system.
-int source_ldisc_num, sink_ldisc_num = -1;
-int retval;
-
-g_fd_source = open(ONE_TTY, O_RDWR); // must be R/W
-g_fd_sink = open(TWO_TTY, O_RDWR); // must be R/W
-
-if (g_fd_source <= 0) || (g_fd_sink <= 0) {
- // doubt you'll want to use these exact error lines of code
- printf("Error on open(). errno: %d\n",errno);
- return errno;
-}
-
-retval = ioctl(g_fd_sink, TIOCSETD, &sink_ldisc_num);
-if (retval < 0) {
- printf("Error on ioctl(). errno: %d\n", errno);
- return errno;
-}
-
-retval = ioctl(g_fd_source, TIOCSETD, &source_ldisc_num);
-if (retval < 0) {
- printf("Error on ioctl(). errno: %d\n", errno);
- return errno;
-}
-
-/////////// To disconnect n_tracerouter and n_tracesink ////////
-
-// First make sure data through the ldiscs has stopped.
-
-// Second, disconnect ldiscs. This provides a
-// little cleaner shutdown on tty stack.
-sink_ldisc_num = 0;
-source_ldisc_num = 0;
-ioctl(g_fd_uart, TIOCSETD, &sink_ldisc_num);
-ioctl(g_fd_gadget, TIOCSETD, &source_ldisc_num);
-
-// Three, program closes connection, and cleanup:
-close(g_fd_uart);
-close(g_fd_gadget);
-g_fd_uart = g_fd_gadget = NULL;
+on a tty port other than the default n_tty::
+
+ /////////// To hook up n_tracerouter and n_tracesink /////////
+
+ // Note that n_tracerouter depends on n_tracesink.
+ #include <errno.h>
+ #define ONE_TTY "/dev/ttyOne"
+ #define TWO_TTY "/dev/ttyTwo"
+
+ // needed global to hand onto ldisc connection
+ static int g_fd_source = -1;
+ static int g_fd_sink = -1;
+
+ // these two vars used to grab LDISC values from loaded ldisc drivers
+ // in OS. Look at /proc/tty/ldiscs to get the right numbers from
+ // the ldiscs loaded in the system.
+ int source_ldisc_num, sink_ldisc_num = -1;
+ int retval;
+
+ g_fd_source = open(ONE_TTY, O_RDWR); // must be R/W
+ g_fd_sink = open(TWO_TTY, O_RDWR); // must be R/W
+
+ if (g_fd_source <= 0) || (g_fd_sink <= 0) {
+ // doubt you'll want to use these exact error lines of code
+ printf("Error on open(). errno: %d\n",errno);
+ return errno;
+ }
+
+ retval = ioctl(g_fd_sink, TIOCSETD, &sink_ldisc_num);
+ if (retval < 0) {
+ printf("Error on ioctl(). errno: %d\n", errno);
+ return errno;
+ }
+
+ retval = ioctl(g_fd_source, TIOCSETD, &source_ldisc_num);
+ if (retval < 0) {
+ printf("Error on ioctl(). errno: %d\n", errno);
+ return errno;
+ }
+
+ /////////// To disconnect n_tracerouter and n_tracesink ////////
+
+ // First make sure data through the ldiscs has stopped.
+
+ // Second, disconnect ldiscs. This provides a
+ // little cleaner shutdown on tty stack.
+ sink_ldisc_num = 0;
+ source_ldisc_num = 0;
+ ioctl(g_fd_uart, TIOCSETD, &sink_ldisc_num);
+ ioctl(g_fd_gadget, TIOCSETD, &source_ldisc_num);
+
+ // Three, program closes connection, and cleanup:
+ close(g_fd_uart);
+ close(g_fd_gadget);
+ g_fd_uart = g_fd_gadget = NULL;
--
2.20.1
^ permalink raw reply related [flat|nested] 81+ messages in thread* [PATCH 49/57] docs: early-userspace: convert docs to ReST
2019-04-16 2:55 [PATCH 00/57] Convert files to ReST Mauro Carvalho Chehab
` (38 preceding siblings ...)
2019-04-16 2:56 ` [PATCH 48/57] docs: pti_intel_mid.txt: convert to ReST Mauro Carvalho Chehab
@ 2019-04-16 2:56 ` Mauro Carvalho Chehab
2019-04-16 2:56 ` [PATCH 50/57] docs: driver-model: convert it to ReST format Mauro Carvalho Chehab
` (12 subsequent siblings)
52 siblings, 0 replies; 81+ messages in thread
From: Mauro Carvalho Chehab @ 2019-04-16 2:56 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet
The two files there describes a Kernel API feature, used to
support early userspace stuff. Prepare for moving them to
the kernel API book by converting to ReST format.
The conversion itself was quite trivial: just add/mark a few
titles as such, add a literal block markup, add a table markup
and a few blank lines, in order to make Sphinx to properly parse it.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
Documentation/early-userspace/README | 3 +++
.../early-userspace/buffer-format.txt | 19 +++++++++++++------
2 files changed, 16 insertions(+), 6 deletions(-)
diff --git a/Documentation/early-userspace/README b/Documentation/early-userspace/README
index 955d667dc87e..3deefb34046b 100644
--- a/Documentation/early-userspace/README
+++ b/Documentation/early-userspace/README
@@ -1,3 +1,4 @@
+=======================
Early userspace support
=======================
@@ -26,6 +27,7 @@ archive to be used as the image or have the kernel build process build
the image from specifications.
CPIO ARCHIVE method
+-------------------
You can create a cpio archive that contains the early userspace image.
Your cpio archive should be specified in CONFIG_INITRAMFS_SOURCE and it
@@ -34,6 +36,7 @@ CONFIG_INITRAMFS_SOURCE and directory and file names are not allowed in
combination with a cpio archive.
IMAGE BUILDING method
+---------------------
The kernel build process can also build an early userspace image from
source parts rather than supplying a cpio archive. This method provides
diff --git a/Documentation/early-userspace/buffer-format.txt b/Documentation/early-userspace/buffer-format.txt
index e1fd7f9dad16..7f74e301fdf3 100644
--- a/Documentation/early-userspace/buffer-format.txt
+++ b/Documentation/early-userspace/buffer-format.txt
@@ -1,8 +1,10 @@
- initramfs buffer format
- -----------------------
+=======================
+initramfs buffer format
+=======================
- Al Viro, H. Peter Anvin
- Last revision: 2002-01-13
+Al Viro, H. Peter Anvin
+
+Last revision: 2002-01-13
Starting with kernel 2.5.x, the old "initial ramdisk" protocol is
getting {replaced/complemented} with the new "initial ramfs"
@@ -18,7 +20,8 @@ archive can be compressed using gzip(1). One valid version of an
initramfs buffer is thus a single .cpio.gz file.
The full format of the initramfs buffer is defined by the following
-grammar, where:
+grammar, where::
+
* is used to indicate "0 or more occurrences of"
(|) indicates alternatives
+ indicates concatenation
@@ -49,7 +52,9 @@ hexadecimal ASCII numbers fully padded with '0' on the left to the
full width of the field, for example, the integer 4780 is represented
by the ASCII string "000012ac"):
+============= ================== ==============================================
Field name Field size Meaning
+============= ================== ==============================================
c_magic 6 bytes The string "070701" or "070702"
c_ino 8 bytes File inode number
c_mode 8 bytes File mode and permissions
@@ -65,6 +70,7 @@ c_rmin 8 bytes Minor part of device node reference
c_namesize 8 bytes Length of filename, including final \0
c_chksum 8 bytes Checksum of data field if c_magic is 070702;
otherwise zero
+============= ================== ==============================================
The c_mode field matches the contents of st_mode returned by stat(2)
on Linux, and encodes the file type and file permissions.
@@ -82,7 +88,8 @@ If the filename is "TRAILER!!!" this is actually an end-of-archive
marker; the c_filesize for an end-of-archive marker must be zero.
-*** Handling of hard links
+Handling of hard links
+======================
When a nondirectory with c_nlink > 1 is seen, the (c_maj,c_min,c_ino)
tuple is looked up in a tuple buffer. If not found, it is entered in
--
2.20.1
^ permalink raw reply related [flat|nested] 81+ messages in thread* [PATCH 50/57] docs: driver-model: convert it to ReST format
2019-04-16 2:55 [PATCH 00/57] Convert files to ReST Mauro Carvalho Chehab
` (39 preceding siblings ...)
2019-04-16 2:56 ` [PATCH 49/57] docs: early-userspace: convert docs " Mauro Carvalho Chehab
@ 2019-04-16 2:56 ` Mauro Carvalho Chehab
2019-04-16 2:56 ` [PATCH 52/57] docs: memory-devices: convert ti-emif.txt " Mauro Carvalho Chehab
` (11 subsequent siblings)
52 siblings, 0 replies; 81+ messages in thread
From: Mauro Carvalho Chehab @ 2019-04-16 2:56 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet
Convert the various documents at the driver-model, preparing
them to be part of the driver-api book.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
Documentation/driver-model/binding.txt | 20 +-
Documentation/driver-model/bus.txt | 69 ++--
Documentation/driver-model/class.txt | 74 ++--
.../driver-model/design-patterns.txt | 106 +++---
Documentation/driver-model/device.txt | 57 +--
Documentation/driver-model/devres.txt | 50 +--
Documentation/driver-model/driver.txt | 112 +++---
Documentation/driver-model/overview.txt | 37 +-
Documentation/driver-model/platform.txt | 30 +-
Documentation/driver-model/porting.txt | 333 +++++++++---------
10 files changed, 455 insertions(+), 433 deletions(-)
diff --git a/Documentation/driver-model/binding.txt b/Documentation/driver-model/binding.txt
index abfc8e290d53..7ea1d7a41e1d 100644
--- a/Documentation/driver-model/binding.txt
+++ b/Documentation/driver-model/binding.txt
@@ -1,5 +1,6 @@
-
+==============
Driver Binding
+==============
Driver binding is the process of associating a device with a device
driver that can control it. Bus drivers have typically handled this
@@ -25,7 +26,7 @@ device_register
When a new device is added, the bus's list of drivers is iterated over
to find one that supports it. In order to determine that, the device
ID of the device must match one of the device IDs that the driver
-supports. The format and semantics for comparing IDs is bus-specific.
+supports. The format and semantics for comparing IDs is bus-specific.
Instead of trying to derive a complex state machine and matching
algorithm, it is up to the bus driver to provide a callback to compare
a device against the IDs of a driver. The bus returns 1 if a match was
@@ -36,14 +37,14 @@ int match(struct device * dev, struct device_driver * drv);
If a match is found, the device's driver field is set to the driver
and the driver's probe callback is called. This gives the driver a
chance to verify that it really does support the hardware, and that
-it's in a working state.
+it's in a working state.
Device Class
~~~~~~~~~~~~
Upon the successful completion of probe, the device is registered with
the class to which it belongs. Device drivers belong to one and only one
-class, and that is set in the driver's devclass field.
+class, and that is set in the driver's devclass field.
devclass_add_device is called to enumerate the device within the class
and actually register it with the class, which happens with the
class's register_dev callback.
@@ -53,7 +54,7 @@ Driver
~~~~~~
When a driver is attached to a device, the device is inserted into the
-driver's list of devices.
+driver's list of devices.
sysfs
@@ -67,18 +68,18 @@ to the device's directory in the physical hierarchy.
A directory for the device is created in the class's directory. A
symlink is created in that directory that points to the device's
-physical location in the sysfs tree.
+physical location in the sysfs tree.
A symlink can be created (though this isn't done yet) in the device's
physical directory to either its class directory, or the class's
top-level directory. One can also be created to point to its driver's
-directory also.
+directory also.
driver_register
~~~~~~~~~~~~~~~
-The process is almost identical for when a new driver is added.
+The process is almost identical for when a new driver is added.
The bus's list of devices is iterated over to find a match. Devices
that already have a driver are skipped. All the devices are iterated
over, to bind as many devices as possible to the driver.
@@ -94,5 +95,4 @@ of the driver is decremented. All symlinks between the two are removed.
When a driver is removed, the list of devices that it supports is
iterated over, and the driver's remove callback is called for each
-one. The device is removed from that list and the symlinks removed.
-
+one. The device is removed from that list and the symlinks removed.
diff --git a/Documentation/driver-model/bus.txt b/Documentation/driver-model/bus.txt
index c247b488a567..016b15a6e8ea 100644
--- a/Documentation/driver-model/bus.txt
+++ b/Documentation/driver-model/bus.txt
@@ -1,5 +1,6 @@
-
-Bus Types
+=========
+Bus Types
+=========
Definition
~~~~~~~~~~
@@ -13,12 +14,12 @@ Declaration
Each bus type in the kernel (PCI, USB, etc) should declare one static
object of this type. They must initialize the name field, and may
-optionally initialize the match callback.
+optionally initialize the match callback::
-struct bus_type pci_bus_type = {
- .name = "pci",
- .match = pci_bus_match,
-};
+ struct bus_type pci_bus_type = {
+ .name = "pci",
+ .match = pci_bus_match,
+ };
The structure should be exported to drivers in a header file:
@@ -30,8 +31,8 @@ Registration
When a bus driver is initialized, it calls bus_register. This
initializes the rest of the fields in the bus object and inserts it
-into a global list of bus types. Once the bus object is registered,
-the fields in it are usable by the bus driver.
+into a global list of bus types. Once the bus object is registered,
+the fields in it are usable by the bus driver.
Callbacks
@@ -43,17 +44,17 @@ match(): Attaching Drivers to Devices
The format of device ID structures and the semantics for comparing
them are inherently bus-specific. Drivers typically declare an array
of device IDs of devices they support that reside in a bus-specific
-driver structure.
+driver structure.
The purpose of the match callback is to give the bus an opportunity to
determine if a particular driver supports a particular device by
comparing the device IDs the driver supports with the device ID of a
particular device, without sacrificing bus-specific functionality or
-type-safety.
+type-safety.
When a driver is registered with the bus, the bus's list of devices is
iterated over, and the match callback is called for each device that
-does not have a driver associated with it.
+does not have a driver associated with it.
@@ -64,22 +65,23 @@ The lists of devices and drivers are intended to replace the local
lists that many buses keep. They are lists of struct devices and
struct device_drivers, respectively. Bus drivers are free to use the
lists as they please, but conversion to the bus-specific type may be
-necessary.
+necessary.
-The LDM core provides helper functions for iterating over each list.
+The LDM core provides helper functions for iterating over each list::
-int bus_for_each_dev(struct bus_type * bus, struct device * start, void * data,
- int (*fn)(struct device *, void *));
+ int bus_for_each_dev(struct bus_type * bus, struct device * start,
+ void * data,
+ int (*fn)(struct device *, void *));
-int bus_for_each_drv(struct bus_type * bus, struct device_driver * start,
- void * data, int (*fn)(struct device_driver *, void *));
+ int bus_for_each_drv(struct bus_type * bus, struct device_driver * start,
+ void * data, int (*fn)(struct device_driver *, void *));
These helpers iterate over the respective list, and call the callback
for each device or driver in the list. All list accesses are
synchronized by taking the bus's lock (read currently). The reference
count on each object in the list is incremented before the callback is
called; it is decremented after the next object has been obtained. The
-lock is not held when calling the callback.
+lock is not held when calling the callback.
sysfs
@@ -87,14 +89,14 @@ sysfs
There is a top-level directory named 'bus'.
Each bus gets a directory in the bus directory, along with two default
-directories:
+directories::
/sys/bus/pci/
|-- devices
`-- drivers
Drivers registered with the bus get a directory in the bus's drivers
-directory:
+directory::
/sys/bus/pci/
|-- devices
@@ -106,7 +108,7 @@ directory:
Each device that is discovered on a bus of that type gets a symlink in
the bus's devices directory to the device's directory in the physical
-hierarchy:
+hierarchy::
/sys/bus/pci/
|-- devices
@@ -118,26 +120,27 @@ hierarchy:
Exporting Attributes
~~~~~~~~~~~~~~~~~~~~
-struct bus_attribute {
+
+::
+
+ struct bus_attribute {
struct attribute attr;
ssize_t (*show)(struct bus_type *, char * buf);
ssize_t (*store)(struct bus_type *, const char * buf, size_t count);
-};
+ };
Bus drivers can export attributes using the BUS_ATTR_RW macro that works
similarly to the DEVICE_ATTR_RW macro for devices. For example, a
-definition like this:
+definition like this::
-static BUS_ATTR_RW(debug);
+ static BUS_ATTR_RW(debug);
-is equivalent to declaring:
+is equivalent to declaring::
-static bus_attribute bus_attr_debug;
+ static bus_attribute bus_attr_debug;
This can then be used to add and remove the attribute from the bus's
-sysfs directory using:
-
-int bus_create_file(struct bus_type *, struct bus_attribute *);
-void bus_remove_file(struct bus_type *, struct bus_attribute *);
-
+sysfs directory using::
+ int bus_create_file(struct bus_type *, struct bus_attribute *);
+ void bus_remove_file(struct bus_type *, struct bus_attribute *);
diff --git a/Documentation/driver-model/class.txt b/Documentation/driver-model/class.txt
index 1fefc480a80b..fff55b80e86a 100644
--- a/Documentation/driver-model/class.txt
+++ b/Documentation/driver-model/class.txt
@@ -1,6 +1,6 @@
-
+==============
Device Classes
-
+==============
Introduction
~~~~~~~~~~~~
@@ -13,37 +13,37 @@ device. The following device classes have been identified:
Each device class defines a set of semantics and a programming interface
that devices of that class adhere to. Device drivers are the
implementation of that programming interface for a particular device on
-a particular bus.
+a particular bus.
Device classes are agnostic with respect to what bus a device resides
-on.
+on.
Programming Interface
~~~~~~~~~~~~~~~~~~~~~
-The device class structure looks like:
+The device class structure looks like::
-typedef int (*devclass_add)(struct device *);
-typedef void (*devclass_remove)(struct device *);
+ typedef int (*devclass_add)(struct device *);
+ typedef void (*devclass_remove)(struct device *);
See the kerneldoc for the struct class.
-A typical device class definition would look like:
+A typical device class definition would look like::
-struct device_class input_devclass = {
+ struct device_class input_devclass = {
.name = "input",
.add_device = input_add_device,
.remove_device = input_remove_device,
-};
+ };
Each device class structure should be exported in a header file so it
can be used by drivers, extensions and interfaces.
-Device classes are registered and unregistered with the core using:
+Device classes are registered and unregistered with the core using::
-int devclass_register(struct device_class * cls);
-void devclass_unregister(struct device_class * cls);
+ int devclass_register(struct device_class * cls);
+ void devclass_unregister(struct device_class * cls);
Devices
@@ -52,16 +52,16 @@ As devices are bound to drivers, they are added to the device class
that the driver belongs to. Before the driver model core, this would
typically happen during the driver's probe() callback, once the device
has been initialized. It now happens after the probe() callback
-finishes from the core.
+finishes from the core.
The device is enumerated in the class. Each time a device is added to
the class, the class's devnum field is incremented and assigned to the
device. The field is never decremented, so if the device is removed
from the class and re-added, it will receive a different enumerated
-value.
+value.
The class is allowed to create a class-specific structure for the
-device and store it in the device's class_data pointer.
+device and store it in the device's class_data pointer.
There is no list of devices in the device class. Each driver has a
list of devices that it supports. The device class has a list of
@@ -73,15 +73,15 @@ Device Drivers
~~~~~~~~~~~~~~
Device drivers are added to device classes when they are registered
with the core. A driver specifies the class it belongs to by setting
-the struct device_driver::devclass field.
+the struct device_driver::devclass field.
sysfs directory structure
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-There is a top-level sysfs directory named 'class'.
+There is a top-level sysfs directory named 'class'.
Each class gets a directory in the class directory, along with two
-default subdirectories:
+default subdirectories::
class/
`-- input
@@ -89,8 +89,8 @@ default subdirectories:
`-- drivers
-Drivers registered with the class get a symlink in the drivers/ directory
-that points to the driver's directory (under its bus directory):
+Drivers registered with the class get a symlink in the drivers/ directory
+that points to the driver's directory (under its bus directory)::
class/
`-- input
@@ -99,8 +99,8 @@ that points to the driver's directory (under its bus directory):
`-- usb:usb_mouse -> ../../../bus/drivers/usb_mouse/
-Each device gets a symlink in the devices/ directory that points to the
-device's directory in the physical hierarchy:
+Each device gets a symlink in the devices/ directory that points to the
+device's directory in the physical hierarchy::
class/
`-- input
@@ -111,37 +111,39 @@ device's directory in the physical hierarchy:
Exporting Attributes
~~~~~~~~~~~~~~~~~~~~
-struct devclass_attribute {
+
+::
+
+ struct devclass_attribute {
struct attribute attr;
ssize_t (*show)(struct device_class *, char * buf, size_t count, loff_t off);
ssize_t (*store)(struct device_class *, const char * buf, size_t count, loff_t off);
-};
+ };
Class drivers can export attributes using the DEVCLASS_ATTR macro that works
-similarly to the DEVICE_ATTR macro for devices. For example, a definition
-like this:
+similarly to the DEVICE_ATTR macro for devices. For example, a definition
+like this::
-static DEVCLASS_ATTR(debug,0644,show_debug,store_debug);
+ static DEVCLASS_ATTR(debug,0644,show_debug,store_debug);
-is equivalent to declaring:
+is equivalent to declaring::
-static devclass_attribute devclass_attr_debug;
+ static devclass_attribute devclass_attr_debug;
The bus driver can add and remove the attribute from the class's
-sysfs directory using:
+sysfs directory using::
-int devclass_create_file(struct device_class *, struct devclass_attribute *);
-void devclass_remove_file(struct device_class *, struct devclass_attribute *);
+ int devclass_create_file(struct device_class *, struct devclass_attribute *);
+ void devclass_remove_file(struct device_class *, struct devclass_attribute *);
In the example above, the file will be named 'debug' in placed in the
-class's directory in sysfs.
+class's directory in sysfs.
Interfaces
~~~~~~~~~~
There may exist multiple mechanisms for accessing the same device of a
-particular class type. Device interfaces describe these mechanisms.
+particular class type. Device interfaces describe these mechanisms.
When a device is added to a device class, the core attempts to add it
to every interface that is registered with the device class.
-
diff --git a/Documentation/driver-model/design-patterns.txt b/Documentation/driver-model/design-patterns.txt
index ba7b2df64904..41eb8f41f7dd 100644
--- a/Documentation/driver-model/design-patterns.txt
+++ b/Documentation/driver-model/design-patterns.txt
@@ -1,6 +1,6 @@
-
+=============================
Device Driver Design Patterns
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+=============================
This document describes a few common design patterns found in device drivers.
It is likely that subsystem maintainers will ask driver developers to
@@ -19,23 +19,23 @@ that the device the driver binds to will appear in several instances. This
means that the probe() function and all callbacks need to be reentrant.
The most common way to achieve this is to use the state container design
-pattern. It usually has this form:
+pattern. It usually has this form::
-struct foo {
- spinlock_t lock; /* Example member */
- (...)
-};
+ struct foo {
+ spinlock_t lock; /* Example member */
+ (...)
+ };
-static int foo_probe(...)
-{
- struct foo *foo;
+ static int foo_probe(...)
+ {
+ struct foo *foo;
- foo = devm_kzalloc(dev, sizeof(*foo), GFP_KERNEL);
- if (!foo)
- return -ENOMEM;
- spin_lock_init(&foo->lock);
- (...)
-}
+ foo = devm_kzalloc(dev, sizeof(*foo), GFP_KERNEL);
+ if (!foo)
+ return -ENOMEM;
+ spin_lock_init(&foo->lock);
+ (...)
+ }
This will create an instance of struct foo in memory every time probe() is
called. This is our state container for this instance of the device driver.
@@ -43,21 +43,21 @@ Of course it is then necessary to always pass this instance of the
state around to all functions that need access to the state and its members.
For example, if the driver is registering an interrupt handler, you would
-pass around a pointer to struct foo like this:
+pass around a pointer to struct foo like this::
-static irqreturn_t foo_handler(int irq, void *arg)
-{
- struct foo *foo = arg;
- (...)
-}
+ static irqreturn_t foo_handler(int irq, void *arg)
+ {
+ struct foo *foo = arg;
+ (...)
+ }
-static int foo_probe(...)
-{
- struct foo *foo;
+ static int foo_probe(...)
+ {
+ struct foo *foo;
- (...)
- ret = request_irq(irq, foo_handler, 0, "foo", foo);
-}
+ (...)
+ ret = request_irq(irq, foo_handler, 0, "foo", foo);
+ }
This way you always get a pointer back to the correct instance of foo in
your interrupt handler.
@@ -66,38 +66,38 @@ your interrupt handler.
2. container_of()
~~~~~~~~~~~~~~~~~
-Continuing on the above example we add an offloaded work:
+Continuing on the above example we add an offloaded work::
-struct foo {
- spinlock_t lock;
- struct workqueue_struct *wq;
- struct work_struct offload;
- (...)
-};
+ struct foo {
+ spinlock_t lock;
+ struct workqueue_struct *wq;
+ struct work_struct offload;
+ (...)
+ };
-static void foo_work(struct work_struct *work)
-{
- struct foo *foo = container_of(work, struct foo, offload);
+ static void foo_work(struct work_struct *work)
+ {
+ struct foo *foo = container_of(work, struct foo, offload);
- (...)
-}
+ (...)
+ }
-static irqreturn_t foo_handler(int irq, void *arg)
-{
- struct foo *foo = arg;
+ static irqreturn_t foo_handler(int irq, void *arg)
+ {
+ struct foo *foo = arg;
- queue_work(foo->wq, &foo->offload);
- (...)
-}
+ queue_work(foo->wq, &foo->offload);
+ (...)
+ }
-static int foo_probe(...)
-{
- struct foo *foo;
+ static int foo_probe(...)
+ {
+ struct foo *foo;
- foo->wq = create_singlethread_workqueue("foo-wq");
- INIT_WORK(&foo->offload, foo_work);
- (...)
-}
+ foo->wq = create_singlethread_workqueue("foo-wq");
+ INIT_WORK(&foo->offload, foo_work);
+ (...)
+ }
The design pattern is the same for an hrtimer or something similar that will
return a single argument which is a pointer to a struct member in the
diff --git a/Documentation/driver-model/device.txt b/Documentation/driver-model/device.txt
index 2403eb856187..2b868d49d349 100644
--- a/Documentation/driver-model/device.txt
+++ b/Documentation/driver-model/device.txt
@@ -1,6 +1,6 @@
-
+==========================
The Basic Device Structure
-~~~~~~~~~~~~~~~~~~~~~~~~~~
+==========================
See the kerneldoc for the struct device.
@@ -8,9 +8,9 @@ See the kerneldoc for the struct device.
Programming Interface
~~~~~~~~~~~~~~~~~~~~~
The bus driver that discovers the device uses this to register the
-device with the core:
+device with the core::
-int device_register(struct device * dev);
+ int device_register(struct device * dev);
The bus should initialize the following fields:
@@ -20,30 +20,33 @@ The bus should initialize the following fields:
- bus
A device is removed from the core when its reference count goes to
-0. The reference count can be adjusted using:
+0. The reference count can be adjusted using::
-struct device * get_device(struct device * dev);
-void put_device(struct device * dev);
+ struct device * get_device(struct device * dev);
+ void put_device(struct device * dev);
get_device() will return a pointer to the struct device passed to it
if the reference is not already 0 (if it's in the process of being
removed already).
-A driver can access the lock in the device structure using:
+A driver can access the lock in the device structure using::
-void lock_device(struct device * dev);
-void unlock_device(struct device * dev);
+ void lock_device(struct device * dev);
+ void unlock_device(struct device * dev);
Attributes
~~~~~~~~~~
-struct device_attribute {
+
+::
+
+ struct device_attribute {
struct attribute attr;
ssize_t (*show)(struct device *dev, struct device_attribute *attr,
char *buf);
ssize_t (*store)(struct device *dev, struct device_attribute *attr,
const char *buf, size_t count);
-};
+ };
Attributes of devices can be exported by a device driver through sysfs.
@@ -54,39 +57,39 @@ As explained in Documentation/kobject.txt, device attributes must be
created before the KOBJ_ADD uevent is generated. The only way to realize
that is by defining an attribute group.
-Attributes are declared using a macro called DEVICE_ATTR:
+Attributes are declared using a macro called DEVICE_ATTR::
-#define DEVICE_ATTR(name,mode,show,store)
+ #define DEVICE_ATTR(name,mode,show,store)
-Example:
+Example:::
-static DEVICE_ATTR(type, 0444, show_type, NULL);
-static DEVICE_ATTR(power, 0644, show_power, store_power);
+ static DEVICE_ATTR(type, 0444, show_type, NULL);
+ static DEVICE_ATTR(power, 0644, show_power, store_power);
This declares two structures of type struct device_attribute with respective
names 'dev_attr_type' and 'dev_attr_power'. These two attributes can be
-organized as follows into a group:
+organized as follows into a group::
-static struct attribute *dev_attrs[] = {
+ static struct attribute *dev_attrs[] = {
&dev_attr_type.attr,
&dev_attr_power.attr,
NULL,
-};
+ };
-static struct attribute_group dev_attr_group = {
+ static struct attribute_group dev_attr_group = {
.attrs = dev_attrs,
-};
+ };
-static const struct attribute_group *dev_attr_groups[] = {
+ static const struct attribute_group *dev_attr_groups[] = {
&dev_attr_group,
NULL,
-};
+ };
This array of groups can then be associated with a device by setting the
-group pointer in struct device before device_register() is invoked:
+group pointer in struct device before device_register() is invoked::
- dev->groups = dev_attr_groups;
- device_register(dev);
+ dev->groups = dev_attr_groups;
+ device_register(dev);
The device_register() function will use the 'groups' pointer to create the
device attributes and the device_unregister() function will use this pointer
diff --git a/Documentation/driver-model/devres.txt b/Documentation/driver-model/devres.txt
index 99994a461359..4f88bdd7d555 100644
--- a/Documentation/driver-model/devres.txt
+++ b/Documentation/driver-model/devres.txt
@@ -1,3 +1,4 @@
+================================
Devres - Managed Device Resource
================================
@@ -5,17 +6,18 @@ Tejun Heo <teheo@suse.de>
First draft 10 January 2007
+.. contents
-1. Intro : Huh? Devres?
-2. Devres : Devres in a nutshell
-3. Devres Group : Group devres'es and release them together
-4. Details : Life time rules, calling context, ...
-5. Overhead : How much do we have to pay for this?
-6. List of managed interfaces : Currently implemented managed interfaces
+ 1. Intro : Huh? Devres?
+ 2. Devres : Devres in a nutshell
+ 3. Devres Group : Group devres'es and release them together
+ 4. Details : Life time rules, calling context, ...
+ 5. Overhead : How much do we have to pay for this?
+ 6. List of managed interfaces: Currently implemented managed interfaces
- 1. Intro
- --------
+1. Intro
+--------
devres came up while trying to convert libata to use iomap. Each
iomapped address should be kept and unmapped on driver detach. For
@@ -42,8 +44,8 @@ would leak resources or even cause oops when failure occurs. iomap
adds more to this mix. So do msi and msix.
- 2. Devres
- ---------
+2. Devres
+---------
devres is basically linked list of arbitrarily sized memory areas
associated with a struct device. Each devres entry is associated with
@@ -58,7 +60,7 @@ using dma_alloc_coherent(). The managed version is called
dmam_alloc_coherent(). It is identical to dma_alloc_coherent() except
for the DMA memory allocated using it is managed and will be
automatically released on driver detach. Implementation looks like
-the following.
+the following::
struct dma_devres {
size_t size;
@@ -98,7 +100,7 @@ If a driver uses dmam_alloc_coherent(), the area is guaranteed to be
freed whether initialization fails half-way or the device gets
detached. If most resources are acquired using managed interface, a
driver can have much simpler init and exit code. Init path basically
-looks like the following.
+looks like the following::
my_init_one()
{
@@ -119,7 +121,7 @@ looks like the following.
return register_to_upper_layer(d);
}
-And exit path,
+And exit path::
my_remove_one()
{
@@ -140,13 +142,13 @@ on you. In some cases this may mean introducing checks that were not
necessary before moving to the managed devm_* calls.
- 3. Devres group
- ---------------
+3. Devres group
+---------------
Devres entries can be grouped using devres group. When a group is
released, all contained normal devres entries and properly nested
groups are released. One usage is to rollback series of acquired
-resources on failure. For example,
+resources on failure. For example::
if (!devres_open_group(dev, NULL, GFP_KERNEL))
return -ENOMEM;
@@ -172,7 +174,7 @@ like above are usually useful in midlayer driver (e.g. libata core
layer) where interface function shouldn't have side effect on failure.
For LLDs, just returning error code suffices in most cases.
-Each group is identified by void *id. It can either be explicitly
+Each group is identified by `void *id`. It can either be explicitly
specified by @id argument to devres_open_group() or automatically
created by passing NULL as @id as in the above example. In both
cases, devres_open_group() returns the group's id. The returned id
@@ -180,7 +182,7 @@ can be passed to other devres functions to select the target group.
If NULL is given to those functions, the latest open group is
selected.
-For example, you can do something like the following.
+For example, you can do something like the following::
int my_midlayer_create_something()
{
@@ -199,8 +201,8 @@ For example, you can do something like the following.
}
- 4. Details
- ----------
+4. Details
+----------
Lifetime of a devres entry begins on devres allocation and finishes
when it is released or destroyed (removed and freed) - no reference
@@ -220,8 +222,8 @@ All devres interface functions can be called without context if the
right gfp mask is given.
- 5. Overhead
- -----------
+5. Overhead
+-----------
Each devres bookkeeping info is allocated together with requested data
area. With debug option turned off, bookkeeping info occupies 16
@@ -237,8 +239,8 @@ and 400 bytes on 32bit machine after naive conversion (we can
certainly invest a bit more effort into libata core layer).
- 6. List of managed interfaces
- -----------------------------
+6. List of managed interfaces
+-----------------------------
CLOCK
devm_clk_get()
diff --git a/Documentation/driver-model/driver.txt b/Documentation/driver-model/driver.txt
index d661e6f7e6a0..11d281506a04 100644
--- a/Documentation/driver-model/driver.txt
+++ b/Documentation/driver-model/driver.txt
@@ -1,5 +1,6 @@
-
+==============
Device Drivers
+==============
See the kerneldoc for the struct device_driver.
@@ -26,50 +27,50 @@ Declaration
As stated above, struct device_driver objects are statically
allocated. Below is an example declaration of the eepro100
driver. This declaration is hypothetical only; it relies on the driver
-being converted completely to the new model.
+being converted completely to the new model::
-static struct device_driver eepro100_driver = {
- .name = "eepro100",
- .bus = &pci_bus_type,
-
- .probe = eepro100_probe,
- .remove = eepro100_remove,
- .suspend = eepro100_suspend,
- .resume = eepro100_resume,
-};
+ static struct device_driver eepro100_driver = {
+ .name = "eepro100",
+ .bus = &pci_bus_type,
+
+ .probe = eepro100_probe,
+ .remove = eepro100_remove,
+ .suspend = eepro100_suspend,
+ .resume = eepro100_resume,
+ };
Most drivers will not be able to be converted completely to the new
model because the bus they belong to has a bus-specific structure with
-bus-specific fields that cannot be generalized.
+bus-specific fields that cannot be generalized.
The most common example of this are device ID structures. A driver
typically defines an array of device IDs that it supports. The format
of these structures and the semantics for comparing device IDs are
completely bus-specific. Defining them as bus-specific entities would
-sacrifice type-safety, so we keep bus-specific structures around.
+sacrifice type-safety, so we keep bus-specific structures around.
Bus-specific drivers should include a generic struct device_driver in
-the definition of the bus-specific driver. Like this:
+the definition of the bus-specific driver. Like this::
-struct pci_driver {
- const struct pci_device_id *id_table;
- struct device_driver driver;
-};
+ struct pci_driver {
+ const struct pci_device_id *id_table;
+ struct device_driver driver;
+ };
A definition that included bus-specific fields would look like
-(using the eepro100 driver again):
+(using the eepro100 driver again)::
-static struct pci_driver eepro100_driver = {
- .id_table = eepro100_pci_tbl,
- .driver = {
+ static struct pci_driver eepro100_driver = {
+ .id_table = eepro100_pci_tbl,
+ .driver = {
.name = "eepro100",
.bus = &pci_bus_type,
.probe = eepro100_probe,
.remove = eepro100_remove,
.suspend = eepro100_suspend,
.resume = eepro100_resume,
- },
-};
+ },
+ };
Some may find the syntax of embedded struct initialization awkward or
even a bit ugly. So far, it's the best way we've found to do what we want...
@@ -77,12 +78,14 @@ even a bit ugly. So far, it's the best way we've found to do what we want...
Registration
~~~~~~~~~~~~
-int driver_register(struct device_driver * drv);
+::
+
+ int driver_register(struct device_driver *drv);
The driver registers the structure on startup. For drivers that have
no bus-specific fields (i.e. don't have a bus-specific driver
structure), they would use driver_register and pass a pointer to their
-struct device_driver object.
+struct device_driver object.
Most drivers, however, will have a bus-specific structure and will
need to register with the bus using something like pci_driver_register.
@@ -101,7 +104,7 @@ By defining wrapper functions, the transition to the new model can be
made easier. Drivers can ignore the generic structure altogether and
let the bus wrapper fill in the fields. For the callbacks, the bus can
define generic callbacks that forward the call to the bus-specific
-callbacks of the drivers.
+callbacks of the drivers.
This solution is intended to be only temporary. In order to get class
information in the driver, the drivers must be modified anyway. Since
@@ -113,16 +116,16 @@ Access
~~~~~~
Once the object has been registered, it may access the common fields of
-the object, like the lock and the list of devices.
+the object, like the lock and the list of devices::
-int driver_for_each_dev(struct device_driver * drv, void * data,
- int (*callback)(struct device * dev, void * data));
+ int driver_for_each_dev(struct device_driver *drv, void *data,
+ int (*callback)(struct device *dev, void *data));
The devices field is a list of all the devices that have been bound to
the driver. The LDM core provides a helper function to operate on all
the devices a driver controls. This helper locks the driver on each
node access, and does proper reference counting on each device as it
-accesses it.
+accesses it.
sysfs
@@ -142,7 +145,9 @@ supports.
Callbacks
~~~~~~~~~
- int (*probe) (struct device * dev);
+::
+
+ int (*probe) (struct device *dev);
The probe() entry is called in task context, with the bus's rwsem locked
and the driver partially bound to the device. Drivers commonly use
@@ -162,9 +167,9 @@ the driver to that device.
A driver's probe() may return a negative errno value to indicate that
the driver did not bind to this device, in which case it should have
-released all resources it allocated.
+released all resources it allocated::
- int (*remove) (struct device * dev);
+ int (*remove) (struct device *dev);
remove is called to unbind a driver from a device. This may be
called if a device is physically removed from the system, if the
@@ -173,43 +178,46 @@ in other cases.
It is up to the driver to determine if the device is present or
not. It should free any resources allocated specifically for the
-device; i.e. anything in the device's driver_data field.
+device; i.e. anything in the device's driver_data field.
If the device is still present, it should quiesce the device and place
-it into a supported low-power state.
+it into a supported low-power state::
- int (*suspend) (struct device * dev, pm_message_t state);
+ int (*suspend) (struct device *dev, pm_message_t state);
-suspend is called to put the device in a low power state.
+suspend is called to put the device in a low power state::
- int (*resume) (struct device * dev);
+ int (*resume) (struct device *dev);
Resume is used to bring a device back from a low power state.
Attributes
~~~~~~~~~~
-struct driver_attribute {
- struct attribute attr;
- ssize_t (*show)(struct device_driver *driver, char *buf);
- ssize_t (*store)(struct device_driver *, const char * buf, size_t count);
-};
-Device drivers can export attributes via their sysfs directories.
+::
+
+ struct driver_attribute {
+ struct attribute attr;
+ ssize_t (*show)(struct device_driver *driver, char *buf);
+ ssize_t (*store)(struct device_driver *, const char *buf, size_t count);
+ };
+
+Device drivers can export attributes via their sysfs directories.
Drivers can declare attributes using a DRIVER_ATTR_RW and DRIVER_ATTR_RO
macro that works identically to the DEVICE_ATTR_RW and DEVICE_ATTR_RO
macros.
-Example:
+Example::
-DRIVER_ATTR_RW(debug);
+ DRIVER_ATTR_RW(debug);
-This is equivalent to declaring:
+This is equivalent to declaring::
-struct driver_attribute driver_attr_debug;
+ struct driver_attribute driver_attr_debug;
This can then be used to add and remove the attribute from the
-driver's directory using:
+driver's directory using::
-int driver_create_file(struct device_driver *, const struct driver_attribute *);
-void driver_remove_file(struct device_driver *, const struct driver_attribute *);
+ int driver_create_file(struct device_driver *, const struct driver_attribute *);
+ void driver_remove_file(struct device_driver *, const struct driver_attribute *);
diff --git a/Documentation/driver-model/overview.txt b/Documentation/driver-model/overview.txt
index 6a8f9a8075d8..d4d1e9b40e0c 100644
--- a/Documentation/driver-model/overview.txt
+++ b/Documentation/driver-model/overview.txt
@@ -1,4 +1,6 @@
+=============================
The Linux Kernel Device Model
+=============================
Patrick Mochel <mochel@digitalimplant.org>
@@ -41,14 +43,14 @@ data structure. These fields must still be accessed by the bus layers,
and sometimes by the device-specific drivers.
Other bus layers are encouraged to do what has been done for the PCI layer.
-struct pci_dev now looks like this:
+struct pci_dev now looks like this::
-struct pci_dev {
+ struct pci_dev {
...
struct device dev; /* Generic device interface */
...
-};
+ };
Note first that the struct device dev within the struct pci_dev is
statically allocated. This means only one allocation on device discovery.
@@ -80,26 +82,26 @@ easy. This has been accomplished by implementing a special purpose virtual
file system named sysfs.
Almost all mainstream Linux distros mount this filesystem automatically; you
-can see some variation of the following in the output of the "mount" command:
+can see some variation of the following in the output of the "mount" command::
-$ mount
-...
-none on /sys type sysfs (rw,noexec,nosuid,nodev)
-...
-$
+ $ mount
+ ...
+ none on /sys type sysfs (rw,noexec,nosuid,nodev)
+ ...
+ $
The auto-mounting of sysfs is typically accomplished by an entry similar to
-the following in the /etc/fstab file:
+the following in the /etc/fstab file::
-none /sys sysfs defaults 0 0
+ none /sys sysfs defaults 0 0
-or something similar in the /lib/init/fstab file on Debian-based systems:
+or something similar in the /lib/init/fstab file on Debian-based systems::
-none /sys sysfs nodev,noexec,nosuid 0 0
+ none /sys sysfs nodev,noexec,nosuid 0 0
-If sysfs is not automatically mounted, you can always do it manually with:
+If sysfs is not automatically mounted, you can always do it manually with::
-# mount -t sysfs sysfs /sys
+ # mount -t sysfs sysfs /sys
Whenever a device is inserted into the tree, a directory is created for it.
This directory may be populated at each layer of discovery - the global layer,
@@ -108,7 +110,7 @@ the bus layer, or the device layer.
The global layer currently creates two files - 'name' and 'power'. The
former only reports the name of the device. The latter reports the
current power state of the device. It will also be used to set the current
-power state.
+power state.
The bus layer may also create files for the devices it finds while probing the
bus. For example, the PCI layer currently creates 'irq' and 'resource' files
@@ -118,6 +120,5 @@ A device-specific driver may also export files in its directory to expose
device-specific data or tunable interfaces.
More information about the sysfs directory layout can be found in
-the other documents in this directory and in the file
+the other documents in this directory and in the file
Documentation/filesystems/sysfs.txt.
-
diff --git a/Documentation/driver-model/platform.txt b/Documentation/driver-model/platform.txt
index 9d9e47dfc013..334dd4071ae4 100644
--- a/Documentation/driver-model/platform.txt
+++ b/Documentation/driver-model/platform.txt
@@ -1,5 +1,7 @@
+============================
Platform Devices and Drivers
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+============================
+
See <linux/platform_device.h> for the driver model interface to the
platform bus: platform_device, and platform_driver. This pseudo-bus
is used to connect devices on busses with minimal infrastructure,
@@ -19,15 +21,15 @@ be connected through a segment of some other kind of bus; but its
registers will still be directly addressable.
Platform devices are given a name, used in driver binding, and a
-list of resources such as addresses and IRQs.
+list of resources such as addresses and IRQs::
-struct platform_device {
+ struct platform_device {
const char *name;
u32 id;
struct device dev;
u32 num_resources;
struct resource *resource;
-};
+ };
Platform drivers
@@ -35,9 +37,9 @@ Platform drivers
Platform drivers follow the standard driver model convention, where
discovery/enumeration is handled outside the drivers, and drivers
provide probe() and remove() methods. They support power management
-and shutdown notifications using the standard conventions.
+and shutdown notifications using the standard conventions::
-struct platform_driver {
+ struct platform_driver {
int (*probe)(struct platform_device *);
int (*remove)(struct platform_device *);
void (*shutdown)(struct platform_device *);
@@ -46,25 +48,25 @@ struct platform_driver {
int (*resume_early)(struct platform_device *);
int (*resume)(struct platform_device *);
struct device_driver driver;
-};
+ };
Note that probe() should in general verify that the specified device hardware
actually exists; sometimes platform setup code can't be sure. The probing
can use device resources, including clocks, and device platform_data.
-Platform drivers register themselves the normal way:
+Platform drivers register themselves the normal way::
int platform_driver_register(struct platform_driver *drv);
Or, in common situations where the device is known not to be hot-pluggable,
the probe() routine can live in an init section to reduce the driver's
-runtime memory footprint:
+runtime memory footprint::
int platform_driver_probe(struct platform_driver *drv,
int (*probe)(struct platform_device *))
Kernel modules can be composed of several platform drivers. The platform core
-provides helpers to register and unregister an array of drivers:
+provides helpers to register and unregister an array of drivers::
int __platform_register_drivers(struct platform_driver * const *drivers,
unsigned int count, struct module *owner);
@@ -73,7 +75,7 @@ provides helpers to register and unregister an array of drivers:
If one of the drivers fails to register, all drivers registered up to that
point will be unregistered in reverse order. Note that there is a convenience
-macro that passes THIS_MODULE as owner parameter:
+macro that passes THIS_MODULE as owner parameter::
#define platform_register_drivers(drivers, count)
@@ -81,7 +83,7 @@ macro that passes THIS_MODULE as owner parameter:
Device Enumeration
~~~~~~~~~~~~~~~~~~
As a rule, platform specific (and often board-specific) setup code will
-register platform devices:
+register platform devices::
int platform_device_register(struct platform_device *pdev);
@@ -133,14 +135,14 @@ tend to already have "normal" modes, such as ones using device nodes that
were created by PNP or by platform device setup.
None the less, there are some APIs to support such legacy drivers. Avoid
-using these calls except with such hotplug-deficient drivers.
+using these calls except with such hotplug-deficient drivers::
struct platform_device *platform_device_alloc(
const char *name, int id);
You can use platform_device_alloc() to dynamically allocate a device, which
you will then initialize with resources and platform_device_register().
-A better solution is usually:
+A better solution is usually::
struct platform_device *platform_device_register_simple(
const char *name, int id,
diff --git a/Documentation/driver-model/porting.txt b/Documentation/driver-model/porting.txt
index 453053f1661f..4db1be49c6d8 100644
--- a/Documentation/driver-model/porting.txt
+++ b/Documentation/driver-model/porting.txt
@@ -1,5 +1,6 @@
-
+=======================================
Porting Drivers to the New Driver Model
+=======================================
Patrick Mochel
@@ -8,8 +9,8 @@ Patrick Mochel
Overview
-Please refer to Documentation/driver-model/*.txt for definitions of
-various driver types and concepts.
+Please refer to `Documentation/driver-model/*.txt` for definitions of
+various driver types and concepts.
Most of the work of porting devices drivers to the new model happens
at the bus driver layer. This was intentional, to minimize the
@@ -18,11 +19,11 @@ of bus drivers.
In a nutshell, the driver model consists of a set of objects that can
be embedded in larger, bus-specific objects. Fields in these generic
-objects can replace fields in the bus-specific objects.
+objects can replace fields in the bus-specific objects.
The generic objects must be registered with the driver model core. By
doing so, they will exported via the sysfs filesystem. sysfs can be
-mounted by doing
+mounted by doing::
# mount -t sysfs sysfs /sys
@@ -30,108 +31,109 @@ mounted by doing
The Process
-Step 0: Read include/linux/device.h for object and function definitions.
+Step 0: Read include/linux/device.h for object and function definitions.
-Step 1: Registering the bus driver.
+Step 1: Registering the bus driver.
-- Define a struct bus_type for the bus driver.
+- Define a struct bus_type for the bus driver::
-struct bus_type pci_bus_type = {
- .name = "pci",
-};
+ struct bus_type pci_bus_type = {
+ .name = "pci",
+ };
- Register the bus type.
+
This should be done in the initialization function for the bus type,
- which is usually the module_init(), or equivalent, function.
+ which is usually the module_init(), or equivalent, function::
-static int __init pci_driver_init(void)
-{
- return bus_register(&pci_bus_type);
-}
+ static int __init pci_driver_init(void)
+ {
+ return bus_register(&pci_bus_type);
+ }
-subsys_initcall(pci_driver_init);
+ subsys_initcall(pci_driver_init);
The bus type may be unregistered (if the bus driver may be compiled
- as a module) by doing:
+ as a module) by doing::
bus_unregister(&pci_bus_type);
-- Export the bus type for others to use.
+- Export the bus type for others to use.
- Other code may wish to reference the bus type, so declare it in a
+ Other code may wish to reference the bus type, so declare it in a
shared header file and export the symbol.
-From include/linux/pci.h:
+From include/linux/pci.h::
-extern struct bus_type pci_bus_type;
+ extern struct bus_type pci_bus_type;
-From file the above code appears in:
+From file the above code appears in::
-EXPORT_SYMBOL(pci_bus_type);
+ EXPORT_SYMBOL(pci_bus_type);
- This will cause the bus to show up in /sys/bus/pci/ with two
- subdirectories: 'devices' and 'drivers'.
+ subdirectories: 'devices' and 'drivers'::
-# tree -d /sys/bus/pci/
-/sys/bus/pci/
-|-- devices
-`-- drivers
+ # tree -d /sys/bus/pci/
+ /sys/bus/pci/
+ |-- devices
+ `-- drivers
-Step 2: Registering Devices.
+Step 2: Registering Devices.
struct device represents a single device. It mainly contains metadata
-describing the relationship the device has to other entities.
+describing the relationship the device has to other entities.
-- Embed a struct device in the bus-specific device type.
+- Embed a struct device in the bus-specific device type::
-struct pci_dev {
- ...
- struct device dev; /* Generic device interface */
- ...
-};
+ struct pci_dev {
+ ...
+ struct device dev; /* Generic device interface */
+ ...
+ };
- It is recommended that the generic device not be the first item in
+ It is recommended that the generic device not be the first item in
the struct to discourage programmers from doing mindless casts
between the object types. Instead macros, or inline functions,
- should be created to convert from the generic object type.
+ should be created to convert from the generic object type::
-#define to_pci_dev(n) container_of(n, struct pci_dev, dev)
+ #define to_pci_dev(n) container_of(n, struct pci_dev, dev)
-or
+ or
-static inline struct pci_dev * to_pci_dev(struct kobject * kobj)
-{
+ static inline struct pci_dev * to_pci_dev(struct kobject * kobj)
+ {
return container_of(n, struct pci_dev, dev);
-}
+ }
- This allows the compiler to verify type-safety of the operations
+ This allows the compiler to verify type-safety of the operations
that are performed (which is Good).
- Initialize the device on registration.
- When devices are discovered or registered with the bus type, the
+ When devices are discovered or registered with the bus type, the
bus driver should initialize the generic device. The most important
things to initialize are the bus_id, parent, and bus fields.
The bus_id is an ASCII string that contains the device's address on
the bus. The format of this string is bus-specific. This is
- necessary for representing devices in sysfs.
+ necessary for representing devices in sysfs.
parent is the physical parent of the device. It is important that
- the bus driver sets this field correctly.
+ the bus driver sets this field correctly.
The driver model maintains an ordered list of devices that it uses
for power management. This list must be in order to guarantee that
@@ -140,13 +142,13 @@ static inline struct pci_dev * to_pci_dev(struct kobject * kobj)
devices.
Also, the location of the device's sysfs directory depends on a
- device's parent. sysfs exports a directory structure that mirrors
+ device's parent. sysfs exports a directory structure that mirrors
the device hierarchy. Accurately setting the parent guarantees that
sysfs will accurately represent the hierarchy.
The device's bus field is a pointer to the bus type the device
belongs to. This should be set to the bus_type that was declared
- and initialized before.
+ and initialized before.
Optionally, the bus driver may set the device's name and release
fields.
@@ -155,107 +157,107 @@ static inline struct pci_dev * to_pci_dev(struct kobject * kobj)
"ATI Technologies Inc Radeon QD"
- The release field is a callback that the driver model core calls
- when the device has been removed, and all references to it have
+ The release field is a callback that the driver model core calls
+ when the device has been removed, and all references to it have
been released. More on this in a moment.
-- Register the device.
+- Register the device.
Once the generic device has been initialized, it can be registered
- with the driver model core by doing:
+ with the driver model core by doing::
device_register(&dev->dev);
- It can later be unregistered by doing:
+ It can later be unregistered by doing::
device_unregister(&dev->dev);
- This should happen on buses that support hotpluggable devices.
+ This should happen on buses that support hotpluggable devices.
If a bus driver unregisters a device, it should not immediately free
- it. It should instead wait for the driver model core to call the
- device's release method, then free the bus-specific object.
+ it. It should instead wait for the driver model core to call the
+ device's release method, then free the bus-specific object.
(There may be other code that is currently referencing the device
- structure, and it would be rude to free the device while that is
+ structure, and it would be rude to free the device while that is
happening).
- When the device is registered, a directory in sysfs is created.
- The PCI tree in sysfs looks like:
+ When the device is registered, a directory in sysfs is created.
+ The PCI tree in sysfs looks like::
-/sys/devices/pci0/
-|-- 00:00.0
-|-- 00:01.0
-| `-- 01:00.0
-|-- 00:02.0
-| `-- 02:1f.0
-| `-- 03:00.0
-|-- 00:1e.0
-| `-- 04:04.0
-|-- 00:1f.0
-|-- 00:1f.1
-| |-- ide0
-| | |-- 0.0
-| | `-- 0.1
-| `-- ide1
-| `-- 1.0
-|-- 00:1f.2
-|-- 00:1f.3
-`-- 00:1f.5
+ /sys/devices/pci0/
+ |-- 00:00.0
+ |-- 00:01.0
+ | `-- 01:00.0
+ |-- 00:02.0
+ | `-- 02:1f.0
+ | `-- 03:00.0
+ |-- 00:1e.0
+ | `-- 04:04.0
+ |-- 00:1f.0
+ |-- 00:1f.1
+ | |-- ide0
+ | | |-- 0.0
+ | | `-- 0.1
+ | `-- ide1
+ | `-- 1.0
+ |-- 00:1f.2
+ |-- 00:1f.3
+ `-- 00:1f.5
Also, symlinks are created in the bus's 'devices' directory
- that point to the device's directory in the physical hierarchy.
+ that point to the device's directory in the physical hierarchy::
-/sys/bus/pci/devices/
-|-- 00:00.0 -> ../../../devices/pci0/00:00.0
-|-- 00:01.0 -> ../../../devices/pci0/00:01.0
-|-- 00:02.0 -> ../../../devices/pci0/00:02.0
-|-- 00:1e.0 -> ../../../devices/pci0/00:1e.0
-|-- 00:1f.0 -> ../../../devices/pci0/00:1f.0
-|-- 00:1f.1 -> ../../../devices/pci0/00:1f.1
-|-- 00:1f.2 -> ../../../devices/pci0/00:1f.2
-|-- 00:1f.3 -> ../../../devices/pci0/00:1f.3
-|-- 00:1f.5 -> ../../../devices/pci0/00:1f.5
-|-- 01:00.0 -> ../../../devices/pci0/00:01.0/01:00.0
-|-- 02:1f.0 -> ../../../devices/pci0/00:02.0/02:1f.0
-|-- 03:00.0 -> ../../../devices/pci0/00:02.0/02:1f.0/03:00.0
-`-- 04:04.0 -> ../../../devices/pci0/00:1e.0/04:04.0
+ /sys/bus/pci/devices/
+ |-- 00:00.0 -> ../../../devices/pci0/00:00.0
+ |-- 00:01.0 -> ../../../devices/pci0/00:01.0
+ |-- 00:02.0 -> ../../../devices/pci0/00:02.0
+ |-- 00:1e.0 -> ../../../devices/pci0/00:1e.0
+ |-- 00:1f.0 -> ../../../devices/pci0/00:1f.0
+ |-- 00:1f.1 -> ../../../devices/pci0/00:1f.1
+ |-- 00:1f.2 -> ../../../devices/pci0/00:1f.2
+ |-- 00:1f.3 -> ../../../devices/pci0/00:1f.3
+ |-- 00:1f.5 -> ../../../devices/pci0/00:1f.5
+ |-- 01:00.0 -> ../../../devices/pci0/00:01.0/01:00.0
+ |-- 02:1f.0 -> ../../../devices/pci0/00:02.0/02:1f.0
+ |-- 03:00.0 -> ../../../devices/pci0/00:02.0/02:1f.0/03:00.0
+ `-- 04:04.0 -> ../../../devices/pci0/00:1e.0/04:04.0
Step 3: Registering Drivers.
struct device_driver is a simple driver structure that contains a set
-of operations that the driver model core may call.
+of operations that the driver model core may call.
-- Embed a struct device_driver in the bus-specific driver.
+- Embed a struct device_driver in the bus-specific driver.
- Just like with devices, do something like:
+ Just like with devices, do something like::
-struct pci_driver {
- ...
- struct device_driver driver;
-};
+ struct pci_driver {
+ ...
+ struct device_driver driver;
+ };
-- Initialize the generic driver structure.
+- Initialize the generic driver structure.
When the driver registers with the bus (e.g. doing pci_register_driver()),
initialize the necessary fields of the driver: the name and bus
- fields.
+ fields.
- Register the driver.
- After the generic driver has been initialized, call
+ After the generic driver has been initialized, call::
driver_register(&drv->driver);
to register the driver with the core.
When the driver is unregistered from the bus, unregister it from the
- core by doing:
+ core by doing::
driver_unregister(&drv->driver);
@@ -265,15 +267,15 @@ struct pci_driver {
- Sysfs representation.
- Drivers are exported via sysfs in their bus's 'driver's directory.
- For example:
+ Drivers are exported via sysfs in their bus's 'driver's directory.
+ For example::
-/sys/bus/pci/drivers/
-|-- 3c59x
-|-- Ensoniq AudioPCI
-|-- agpgart-amdk7
-|-- e100
-`-- serial
+ /sys/bus/pci/drivers/
+ |-- 3c59x
+ |-- Ensoniq AudioPCI
+ |-- agpgart-amdk7
+ |-- e100
+ `-- serial
Step 4: Define Generic Methods for Drivers.
@@ -281,30 +283,30 @@ Step 4: Define Generic Methods for Drivers.
struct device_driver defines a set of operations that the driver model
core calls. Most of these operations are probably similar to
operations the bus already defines for drivers, but taking different
-parameters.
+parameters.
It would be difficult and tedious to force every driver on a bus to
simultaneously convert their drivers to generic format. Instead, the
bus driver should define single instances of the generic methods that
-forward call to the bus-specific drivers. For instance:
+forward call to the bus-specific drivers. For instance::
-static int pci_device_remove(struct device * dev)
-{
- struct pci_dev * pci_dev = to_pci_dev(dev);
- struct pci_driver * drv = pci_dev->driver;
+ static int pci_device_remove(struct device * dev)
+ {
+ struct pci_dev * pci_dev = to_pci_dev(dev);
+ struct pci_driver * drv = pci_dev->driver;
- if (drv) {
- if (drv->remove)
- drv->remove(pci_dev);
- pci_dev->driver = NULL;
- }
- return 0;
-}
+ if (drv) {
+ if (drv->remove)
+ drv->remove(pci_dev);
+ pci_dev->driver = NULL;
+ }
+ return 0;
+ }
The generic driver should be initialized with these methods before it
-is registered.
+is registered::
/* initialize common driver fields */
drv->driver.name = drv->name;
@@ -320,23 +322,23 @@ is registered.
Ideally, the bus should only initialize the fields if they are not
already set. This allows the drivers to implement their own generic
-methods.
+methods.
-Step 5: Support generic driver binding.
+Step 5: Support generic driver binding.
The model assumes that a device or driver can be dynamically
registered with the bus at any time. When registration happens,
devices must be bound to a driver, or drivers must be bound to all
-devices that it supports.
+devices that it supports.
A driver typically contains a list of device IDs that it supports. The
-bus driver compares these IDs to the IDs of devices registered with it.
+bus driver compares these IDs to the IDs of devices registered with it.
The format of the device IDs, and the semantics for comparing them are
-bus-specific, so the generic model does attempt to generalize them.
+bus-specific, so the generic model does attempt to generalize them.
Instead, a bus may supply a method in struct bus_type that does the
-comparison:
+comparison::
int (*match)(struct device * dev, struct device_driver * drv);
@@ -346,59 +348,59 @@ and zero otherwise. It may also return error code (for example
not possible.
When a device is registered, the bus's list of drivers is iterated
-over. bus->match() is called for each one until a match is found.
+over. bus->match() is called for each one until a match is found.
When a driver is registered, the bus's list of devices is iterated
over. bus->match() is called for each device that is not already
-claimed by a driver.
+claimed by a driver.
When a device is successfully bound to a driver, device->driver is
set, the device is added to a per-driver list of devices, and a
symlink is created in the driver's sysfs directory that points to the
-device's physical directory:
+device's physical directory::
-/sys/bus/pci/drivers/
-|-- 3c59x
-| `-- 00:0b.0 -> ../../../../devices/pci0/00:0b.0
-|-- Ensoniq AudioPCI
-|-- agpgart-amdk7
-| `-- 00:00.0 -> ../../../../devices/pci0/00:00.0
-|-- e100
-| `-- 00:0c.0 -> ../../../../devices/pci0/00:0c.0
-`-- serial
+ /sys/bus/pci/drivers/
+ |-- 3c59x
+ | `-- 00:0b.0 -> ../../../../devices/pci0/00:0b.0
+ |-- Ensoniq AudioPCI
+ |-- agpgart-amdk7
+ | `-- 00:00.0 -> ../../../../devices/pci0/00:00.0
+ |-- e100
+ | `-- 00:0c.0 -> ../../../../devices/pci0/00:0c.0
+ `-- serial
This driver binding should replace the existing driver binding
-mechanism the bus currently uses.
+mechanism the bus currently uses.
Step 6: Supply a hotplug callback.
Whenever a device is registered with the driver model core, the
-userspace program /sbin/hotplug is called to notify userspace.
+userspace program /sbin/hotplug is called to notify userspace.
Users can define actions to perform when a device is inserted or
-removed.
+removed.
The driver model core passes several arguments to userspace via
environment variables, including
- ACTION: set to 'add' or 'remove'
-- DEVPATH: set to the device's physical path in sysfs.
+- DEVPATH: set to the device's physical path in sysfs.
A bus driver may also supply additional parameters for userspace to
consume. To do this, a bus must implement the 'hotplug' method in
-struct bus_type:
+struct bus_type::
- int (*hotplug) (struct device *dev, char **envp,
+ int (*hotplug) (struct device *dev, char **envp,
int num_envp, char *buffer, int buffer_size);
-This is called immediately before /sbin/hotplug is executed.
+This is called immediately before /sbin/hotplug is executed.
Step 7: Cleaning up the bus driver.
The generic bus, device, and driver structures provide several fields
-that can replace those defined privately to the bus driver.
+that can replace those defined privately to the bus driver.
- Device list.
@@ -407,36 +409,36 @@ type. This includes all devices on all instances of that bus type.
An internal list that the bus uses may be removed, in favor of using
this one.
-The core provides an iterator to access these devices.
+The core provides an iterator to access these devices::
-int bus_for_each_dev(struct bus_type * bus, struct device * start,
- void * data, int (*fn)(struct device *, void *));
+ int bus_for_each_dev(struct bus_type * bus, struct device * start,
+ void * data, int (*fn)(struct device *, void *));
- Driver list.
struct bus_type also contains a list of all drivers registered with
-it. An internal list of drivers that the bus driver maintains may
-be removed in favor of using the generic one.
+it. An internal list of drivers that the bus driver maintains may
+be removed in favor of using the generic one.
-The drivers may be iterated over, like devices:
+The drivers may be iterated over, like devices::
-int bus_for_each_drv(struct bus_type * bus, struct device_driver * start,
- void * data, int (*fn)(struct device_driver *, void *));
+ int bus_for_each_drv(struct bus_type * bus, struct device_driver * start,
+ void * data, int (*fn)(struct device_driver *, void *));
Please see drivers/base/bus.c for more information.
-- rwsem
+- rwsem
struct bus_type contains an rwsem that protects all core accesses to
the device and driver lists. This can be used by the bus driver
internally, and should be used when accessing the device or driver
-lists the bus maintains.
+lists the bus maintains.
-- Device and driver fields.
+- Device and driver fields.
Some of the fields in struct device and struct device_driver duplicate
fields in the bus-specific representations of these objects. Feel free
@@ -444,4 +446,3 @@ to remove the bus-specific ones and favor the generic ones. Note
though, that this will likely mean fixing up all the drivers that
reference the bus-specific fields (though those should all be 1-line
changes).
-
--
2.20.1
^ permalink raw reply related [flat|nested] 81+ messages in thread* [PATCH 52/57] docs: memory-devices: convert ti-emif.txt to ReST format
2019-04-16 2:55 [PATCH 00/57] Convert files to ReST Mauro Carvalho Chehab
` (40 preceding siblings ...)
2019-04-16 2:56 ` [PATCH 50/57] docs: driver-model: convert it to ReST format Mauro Carvalho Chehab
@ 2019-04-16 2:56 ` Mauro Carvalho Chehab
2019-04-16 2:56 ` [PATCH 53/57] docs: xen-tpmfront.txt: convert the file " Mauro Carvalho Chehab
` (10 subsequent siblings)
52 siblings, 0 replies; 81+ messages in thread
From: Mauro Carvalho Chehab @ 2019-04-16 2:56 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet
Prepare this file to be moved to a kernel book by converting
it to ReST format.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
Documentation/bus-devices/ti-gpmc.txt | 1 +
Documentation/memory-devices/ti-emif.txt | 25 ++++++++++++++----------
2 files changed, 16 insertions(+), 10 deletions(-)
diff --git a/Documentation/bus-devices/ti-gpmc.txt b/Documentation/bus-devices/ti-gpmc.txt
index cc9ce57e0a26..c434fcfc5e4c 100644
--- a/Documentation/bus-devices/ti-gpmc.txt
+++ b/Documentation/bus-devices/ti-gpmc.txt
@@ -3,6 +3,7 @@ GPMC (General Purpose Memory Controller):
GPMC is an unified memory controller dedicated to interfacing external
memory devices like
+
* Asynchronous SRAM like memories and application specific integrated
circuit devices.
* Asynchronous, synchronous, and page mode burst NOR flash devices
diff --git a/Documentation/memory-devices/ti-emif.txt b/Documentation/memory-devices/ti-emif.txt
index f4ad9a7d0f4b..371f581bd276 100644
--- a/Documentation/memory-devices/ti-emif.txt
+++ b/Documentation/memory-devices/ti-emif.txt
@@ -1,20 +1,22 @@
-TI EMIF SDRAM Controller Driver:
+===============================
+TI EMIF SDRAM Controller Driver
+===============================
Author
-========
+======
Aneesh V <aneesh@ti.com>
Location
-============
+========
driver/memory/emif.c
Supported SoCs:
-===================
+===============
TI OMAP44xx
TI OMAP54xx
Menuconfig option:
-==========================
+==================
Device Drivers
Memory devices
Texas Instruments EMIF driver
@@ -29,10 +31,11 @@ functions of the driver includes re-configuring AC timing
parameters and other settings during frequency, voltage and
temperature changes
-Platform Data (see include/linux/platform_data/emif_plat.h):
-=====================================================================
+Platform Data (see include/linux/platform_data/emif_plat.h)
+===========================================================
DDR device details and other board dependent and SoC dependent
information can be passed through platform data (struct emif_platform_data)
+
- DDR device details: 'struct ddr_device_info'
- Device AC timings: 'struct lpddr2_timings' and 'struct lpddr2_min_tck'
- Custom configurations: customizable policy options through
@@ -40,17 +43,19 @@ information can be passed through platform data (struct emif_platform_data)
- IP revision
- PHY type
-Interface to the external world:
-================================
+Interface to the external world
+===============================
EMIF driver registers notifiers for voltage and frequency changes
affecting EMIF and takes appropriate actions when these are invoked.
+
- freq_pre_notify_handling()
- freq_post_notify_handling()
- volt_notify_handling()
Debugfs
-========
+=======
The driver creates two debugfs entries per device.
+
- regcache_dump : dump of register values calculated and saved for all
frequencies used so far.
- mr4 : last polled value of MR4 register in the LPDDR2 device. MR4
--
2.20.1
^ permalink raw reply related [flat|nested] 81+ messages in thread* [PATCH 53/57] docs: xen-tpmfront.txt: convert the file to ReST format
2019-04-16 2:55 [PATCH 00/57] Convert files to ReST Mauro Carvalho Chehab
` (41 preceding siblings ...)
2019-04-16 2:56 ` [PATCH 52/57] docs: memory-devices: convert ti-emif.txt " Mauro Carvalho Chehab
@ 2019-04-16 2:56 ` Mauro Carvalho Chehab
2019-04-16 2:56 ` [PATCH 54/57] docs: bus-devices: ti-gpmc.txt: convert it to ReST Mauro Carvalho Chehab
` (9 subsequent siblings)
52 siblings, 0 replies; 81+ messages in thread
From: Mauro Carvalho Chehab @ 2019-04-16 2:56 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet
In order to be able to add this file to the security book,
we need first to convert it to reST.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
Documentation/security/tpm/xen-tpmfront.txt | 101 +++++++++++---------
1 file changed, 56 insertions(+), 45 deletions(-)
diff --git a/Documentation/security/tpm/xen-tpmfront.txt b/Documentation/security/tpm/xen-tpmfront.txt
index 69346de87ff3..00d5b1db227d 100644
--- a/Documentation/security/tpm/xen-tpmfront.txt
+++ b/Documentation/security/tpm/xen-tpmfront.txt
@@ -1,4 +1,6 @@
+=============================
Virtual TPM interface for Xen
+=============================
Authors: Matthew Fioravante (JHUAPL), Daniel De Graaf (NSA)
@@ -6,7 +8,8 @@ This document describes the virtual Trusted Platform Module (vTPM) subsystem for
Xen. The reader is assumed to have familiarity with building and installing Xen,
Linux, and a basic understanding of the TPM and vTPM concepts.
-INTRODUCTION
+Introduction
+------------
The goal of this work is to provide a TPM functionality to a virtual guest
operating system (in Xen terms, a DomU). This allows programs to interact with
@@ -24,81 +27,89 @@ This mini-os vTPM subsystem was built on top of the previous vTPM work done by
IBM and Intel corporation.
-DESIGN OVERVIEW
+Design Overview
---------------
-The architecture of vTPM is described below:
+The architecture of vTPM is described below::
-+------------------+
-| Linux DomU | ...
-| | ^ |
-| v | |
-| xen-tpmfront |
-+------------------+
- | ^
- v |
-+------------------+
-| mini-os/tpmback |
-| | ^ |
-| v | |
-| vtpm-stubdom | ...
-| | ^ |
-| v | |
-| mini-os/tpmfront |
-+------------------+
- | ^
- v |
-+------------------+
-| mini-os/tpmback |
-| | ^ |
-| v | |
-| vtpmmgr-stubdom |
-| | ^ |
-| v | |
-| mini-os/tpm_tis |
-+------------------+
- | ^
- v |
-+------------------+
-| Hardware TPM |
-+------------------+
+ +------------------+
+ | Linux DomU | ...
+ | | ^ |
+ | v | |
+ | xen-tpmfront |
+ +------------------+
+ | ^
+ v |
+ +------------------+
+ | mini-os/tpmback |
+ | | ^ |
+ | v | |
+ | vtpm-stubdom | ...
+ | | ^ |
+ | v | |
+ | mini-os/tpmfront |
+ +------------------+
+ | ^
+ v |
+ +------------------+
+ | mini-os/tpmback |
+ | | ^ |
+ | v | |
+ | vtpmmgr-stubdom |
+ | | ^ |
+ | v | |
+ | mini-os/tpm_tis |
+ +------------------+
+ | ^
+ v |
+ +------------------+
+ | Hardware TPM |
+ +------------------+
- * Linux DomU: The Linux based guest that wants to use a vTPM. There may be
+* Linux DomU:
+ The Linux based guest that wants to use a vTPM. There may be
more than one of these.
- * xen-tpmfront.ko: Linux kernel virtual TPM frontend driver. This driver
+* xen-tpmfront.ko:
+ Linux kernel virtual TPM frontend driver. This driver
provides vTPM access to a Linux-based DomU.
- * mini-os/tpmback: Mini-os TPM backend driver. The Linux frontend driver
+* mini-os/tpmback:
+ Mini-os TPM backend driver. The Linux frontend driver
connects to this backend driver to facilitate communications
between the Linux DomU and its vTPM. This driver is also
used by vtpmmgr-stubdom to communicate with vtpm-stubdom.
- * vtpm-stubdom: A mini-os stub domain that implements a vTPM. There is a
+* vtpm-stubdom:
+ A mini-os stub domain that implements a vTPM. There is a
one to one mapping between running vtpm-stubdom instances and
logical vtpms on the system. The vTPM Platform Configuration
Registers (PCRs) are normally all initialized to zero.
- * mini-os/tpmfront: Mini-os TPM frontend driver. The vTPM mini-os domain
+* mini-os/tpmfront:
+ Mini-os TPM frontend driver. The vTPM mini-os domain
vtpm-stubdom uses this driver to communicate with
vtpmmgr-stubdom. This driver is also used in mini-os
domains such as pv-grub that talk to the vTPM domain.
- * vtpmmgr-stubdom: A mini-os domain that implements the vTPM manager. There is
+* vtpmmgr-stubdom:
+ A mini-os domain that implements the vTPM manager. There is
only one vTPM manager and it should be running during the
entire lifetime of the machine. This domain regulates
access to the physical TPM on the system and secures the
persistent state of each vTPM.
- * mini-os/tpm_tis: Mini-os TPM version 1.2 TPM Interface Specification (TIS)
+* mini-os/tpm_tis:
+ Mini-os TPM version 1.2 TPM Interface Specification (TIS)
driver. This driver used by vtpmmgr-stubdom to talk directly to
the hardware TPM. Communication is facilitated by mapping
hardware memory pages into vtpmmgr-stubdom.
- * Hardware TPM: The physical TPM that is soldered onto the motherboard.
+* Hardware TPM:
+ The physical TPM that is soldered onto the motherboard.
-INTEGRATION WITH XEN
+Integration With Xen
--------------------
Support for the vTPM driver was added in Xen using the libxl toolstack in Xen
--
2.20.1
^ permalink raw reply related [flat|nested] 81+ messages in thread* [PATCH 54/57] docs: bus-devices: ti-gpmc.txt: convert it to ReST
2019-04-16 2:55 [PATCH 00/57] Convert files to ReST Mauro Carvalho Chehab
` (42 preceding siblings ...)
2019-04-16 2:56 ` [PATCH 53/57] docs: xen-tpmfront.txt: convert the file " Mauro Carvalho Chehab
@ 2019-04-16 2:56 ` Mauro Carvalho Chehab
2019-04-16 2:56 ` [PATCH 55/57] docs: nvmem: convert file to ReST format Mauro Carvalho Chehab
` (8 subsequent siblings)
52 siblings, 0 replies; 81+ messages in thread
From: Mauro Carvalho Chehab @ 2019-04-16 2:56 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet
In order to be able to add this file to a book, it needs
first to be converted to ReST.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
Documentation/bus-devices/ti-gpmc.txt | 156 +++++++++++++++++---------
1 file changed, 105 insertions(+), 51 deletions(-)
diff --git a/Documentation/bus-devices/ti-gpmc.txt b/Documentation/bus-devices/ti-gpmc.txt
index c434fcfc5e4c..afed53688904 100644
--- a/Documentation/bus-devices/ti-gpmc.txt
+++ b/Documentation/bus-devices/ti-gpmc.txt
@@ -1,5 +1,6 @@
-GPMC (General Purpose Memory Controller):
-=========================================
+========================================
+GPMC (General Purpose Memory Controller)
+========================================
GPMC is an unified memory controller dedicated to interfacing external
memory devices like
@@ -49,75 +50,128 @@ most of the datasheets & hardware (to be exact none of those supported
in mainline having custom timing routine) and by simulation.
gpmc timing dependency on peripheral timings:
+
[<gpmc_timing>: <peripheral timing1>, <peripheral timing2> ...]
1. common
-cs_on: t_ceasu
-adv_on: t_avdasu, t_ceavd
+
+cs_on:
+ t_ceasu
+adv_on:
+ t_avdasu, t_ceavd
2. sync common
-sync_clk: clk
-page_burst_access: t_bacc
-clk_activation: t_ces, t_avds
+
+sync_clk:
+ clk
+page_burst_access:
+ t_bacc
+clk_activation:
+ t_ces, t_avds
3. read async muxed
-adv_rd_off: t_avdp_r
-oe_on: t_oeasu, t_aavdh
-access: t_iaa, t_oe, t_ce, t_aa
-rd_cycle: t_rd_cycle, t_cez_r, t_oez
+
+adv_rd_off:
+ t_avdp_r
+oe_on:
+ t_oeasu, t_aavdh
+access:
+ t_iaa, t_oe, t_ce, t_aa
+rd_cycle:
+ t_rd_cycle, t_cez_r, t_oez
4. read async non-muxed
-adv_rd_off: t_avdp_r
-oe_on: t_oeasu
-access: t_iaa, t_oe, t_ce, t_aa
-rd_cycle: t_rd_cycle, t_cez_r, t_oez
+
+adv_rd_off:
+ t_avdp_r
+oe_on:
+ t_oeasu
+access:
+ t_iaa, t_oe, t_ce, t_aa
+rd_cycle:
+ t_rd_cycle, t_cez_r, t_oez
5. read sync muxed
-adv_rd_off: t_avdp_r, t_avdh
-oe_on: t_oeasu, t_ach, cyc_aavdh_oe
-access: t_iaa, cyc_iaa, cyc_oe
-rd_cycle: t_cez_r, t_oez, t_ce_rdyz
+
+adv_rd_off:
+ t_avdp_r, t_avdh
+oe_on:
+ t_oeasu, t_ach, cyc_aavdh_oe
+access:
+ t_iaa, cyc_iaa, cyc_oe
+rd_cycle:
+ t_cez_r, t_oez, t_ce_rdyz
6. read sync non-muxed
-adv_rd_off: t_avdp_r
-oe_on: t_oeasu
-access: t_iaa, cyc_iaa, cyc_oe
-rd_cycle: t_cez_r, t_oez, t_ce_rdyz
+
+adv_rd_off:
+ t_avdp_r
+oe_on:
+ t_oeasu
+access:
+ t_iaa, cyc_iaa, cyc_oe
+rd_cycle:
+ t_cez_r, t_oez, t_ce_rdyz
7. write async muxed
-adv_wr_off: t_avdp_w
-we_on, wr_data_mux_bus: t_weasu, t_aavdh, cyc_aavhd_we
-we_off: t_wpl
-cs_wr_off: t_wph
-wr_cycle: t_cez_w, t_wr_cycle
+
+adv_wr_off:
+ t_avdp_w
+we_on, wr_data_mux_bus:
+ t_weasu, t_aavdh, cyc_aavhd_we
+we_off:
+ t_wpl
+cs_wr_off:
+ t_wph
+wr_cycle:
+ t_cez_w, t_wr_cycle
8. write async non-muxed
-adv_wr_off: t_avdp_w
-we_on, wr_data_mux_bus: t_weasu
-we_off: t_wpl
-cs_wr_off: t_wph
-wr_cycle: t_cez_w, t_wr_cycle
+
+adv_wr_off:
+ t_avdp_w
+we_on, wr_data_mux_bus:
+ t_weasu
+we_off:
+ t_wpl
+cs_wr_off:
+ t_wph
+wr_cycle:
+ t_cez_w, t_wr_cycle
9. write sync muxed
-adv_wr_off: t_avdp_w, t_avdh
-we_on, wr_data_mux_bus: t_weasu, t_rdyo, t_aavdh, cyc_aavhd_we
-we_off: t_wpl, cyc_wpl
-cs_wr_off: t_wph
-wr_cycle: t_cez_w, t_ce_rdyz
+
+adv_wr_off:
+ t_avdp_w, t_avdh
+we_on, wr_data_mux_bus:
+ t_weasu, t_rdyo, t_aavdh, cyc_aavhd_we
+we_off:
+ t_wpl, cyc_wpl
+cs_wr_off:
+ t_wph
+wr_cycle:
+ t_cez_w, t_ce_rdyz
10. write sync non-muxed
-adv_wr_off: t_avdp_w
-we_on, wr_data_mux_bus: t_weasu, t_rdyo
-we_off: t_wpl, cyc_wpl
-cs_wr_off: t_wph
-wr_cycle: t_cez_w, t_ce_rdyz
+adv_wr_off:
+ t_avdp_w
+we_on, wr_data_mux_bus:
+ t_weasu, t_rdyo
+we_off:
+ t_wpl, cyc_wpl
+cs_wr_off:
+ t_wph
+wr_cycle:
+ t_cez_w, t_ce_rdyz
-Note: Many of gpmc timings are dependent on other gpmc timings (a few
-gpmc timings purely dependent on other gpmc timings, a reason that
-some of the gpmc timings are missing above), and it will result in
-indirect dependency of peripheral timings to gpmc timings other than
-mentioned above, refer timing routine for more details. To know what
-these peripheral timings correspond to, please see explanations in
-struct gpmc_device_timings definition. And for gpmc timings refer
-IP details (link above).
+
+Note:
+ Many of gpmc timings are dependent on other gpmc timings (a few
+ gpmc timings purely dependent on other gpmc timings, a reason that
+ some of the gpmc timings are missing above), and it will result in
+ indirect dependency of peripheral timings to gpmc timings other than
+ mentioned above, refer timing routine for more details. To know what
+ these peripheral timings correspond to, please see explanations in
+ struct gpmc_device_timings definition. And for gpmc timings refer
+ IP details (link above).
--
2.20.1
^ permalink raw reply related [flat|nested] 81+ messages in thread* [PATCH 55/57] docs: nvmem: convert file to ReST format
2019-04-16 2:55 [PATCH 00/57] Convert files to ReST Mauro Carvalho Chehab
` (43 preceding siblings ...)
2019-04-16 2:56 ` [PATCH 54/57] docs: bus-devices: ti-gpmc.txt: convert it to ReST Mauro Carvalho Chehab
@ 2019-04-16 2:56 ` Mauro Carvalho Chehab
2019-04-16 2:56 ` [PATCH 56/57] docs: phy: convert samsung-usb2.txt " Mauro Carvalho Chehab
` (7 subsequent siblings)
52 siblings, 0 replies; 81+ messages in thread
From: Mauro Carvalho Chehab @ 2019-04-16 2:56 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet
In order to be able to add it into a doc book, we need first
convert it to ReST.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
Documentation/nvmem/nvmem.txt | 110 ++++++++++++++++++----------------
1 file changed, 57 insertions(+), 53 deletions(-)
diff --git a/Documentation/nvmem/nvmem.txt b/Documentation/nvmem/nvmem.txt
index fc2fe4b18655..c93a9c6cd878 100644
--- a/Documentation/nvmem/nvmem.txt
+++ b/Documentation/nvmem/nvmem.txt
@@ -1,5 +1,8 @@
- NVMEM SUBSYSTEM
- Srinivas Kandagatla <srinivas.kandagatla@linaro.org>
+===============
+NVMEM Subsystem
+===============
+
+ Srinivas Kandagatla <srinivas.kandagatla@linaro.org>
This document explains the NVMEM Framework along with the APIs provided,
and how to use it.
@@ -40,54 +43,54 @@ nvmem_device pointer.
nvmem_unregister(nvmem) is used to unregister a previously registered provider.
-For example, a simple qfprom case:
+For example, a simple qfprom case::
-static struct nvmem_config econfig = {
+ static struct nvmem_config econfig = {
.name = "qfprom",
.owner = THIS_MODULE,
-};
+ };
-static int qfprom_probe(struct platform_device *pdev)
-{
+ static int qfprom_probe(struct platform_device *pdev)
+ {
...
econfig.dev = &pdev->dev;
nvmem = nvmem_register(&econfig);
...
-}
+ }
It is mandatory that the NVMEM provider has a regmap associated with its
struct device. Failure to do would return error code from nvmem_register().
Users of board files can define and register nvmem cells using the
-nvmem_cell_table struct:
+nvmem_cell_table struct::
-static struct nvmem_cell_info foo_nvmem_cells[] = {
+ static struct nvmem_cell_info foo_nvmem_cells[] = {
{
.name = "macaddr",
.offset = 0x7f00,
.bytes = ETH_ALEN,
}
-};
+ };
-static struct nvmem_cell_table foo_nvmem_cell_table = {
+ static struct nvmem_cell_table foo_nvmem_cell_table = {
.nvmem_name = "i2c-eeprom",
.cells = foo_nvmem_cells,
.ncells = ARRAY_SIZE(foo_nvmem_cells),
-};
+ };
-nvmem_add_cell_table(&foo_nvmem_cell_table);
+ nvmem_add_cell_table(&foo_nvmem_cell_table);
Additionally it is possible to create nvmem cell lookup entries and register
-them with the nvmem framework from machine code as shown in the example below:
+them with the nvmem framework from machine code as shown in the example below::
-static struct nvmem_cell_lookup foo_nvmem_lookup = {
+ static struct nvmem_cell_lookup foo_nvmem_lookup = {
.nvmem_name = "i2c-eeprom",
.cell_name = "macaddr",
.dev_id = "foo_mac.0",
.con_id = "mac-address",
-};
+ };
-nvmem_add_cell_lookups(&foo_nvmem_lookup, 1);
+ nvmem_add_cell_lookups(&foo_nvmem_lookup, 1);
NVMEM Consumers
+++++++++++++++
@@ -99,43 +102,43 @@ read from and to NVMEM.
=================================
NVMEM cells are the data entries/fields in the NVMEM.
-The NVMEM framework provides 3 APIs to read/write NVMEM cells.
+The NVMEM framework provides 3 APIs to read/write NVMEM cells::
-struct nvmem_cell *nvmem_cell_get(struct device *dev, const char *name);
-struct nvmem_cell *devm_nvmem_cell_get(struct device *dev, const char *name);
+ struct nvmem_cell *nvmem_cell_get(struct device *dev, const char *name);
+ struct nvmem_cell *devm_nvmem_cell_get(struct device *dev, const char *name);
-void nvmem_cell_put(struct nvmem_cell *cell);
-void devm_nvmem_cell_put(struct device *dev, struct nvmem_cell *cell);
+ void nvmem_cell_put(struct nvmem_cell *cell);
+ void devm_nvmem_cell_put(struct device *dev, struct nvmem_cell *cell);
-void *nvmem_cell_read(struct nvmem_cell *cell, ssize_t *len);
-int nvmem_cell_write(struct nvmem_cell *cell, void *buf, ssize_t len);
+ void *nvmem_cell_read(struct nvmem_cell *cell, ssize_t *len);
+ int nvmem_cell_write(struct nvmem_cell *cell, void *buf, ssize_t len);
-*nvmem_cell_get() apis will get a reference to nvmem cell for a given id,
+`*nvmem_cell_get()` apis will get a reference to nvmem cell for a given id,
and nvmem_cell_read/write() can then read or write to the cell.
-Once the usage of the cell is finished the consumer should call *nvmem_cell_put()
-to free all the allocation memory for the cell.
+Once the usage of the cell is finished the consumer should call
+`*nvmem_cell_put()` to free all the allocation memory for the cell.
4. Direct NVMEM device based consumer APIs
==========================================
In some instances it is necessary to directly read/write the NVMEM.
-To facilitate such consumers NVMEM framework provides below apis.
+To facilitate such consumers NVMEM framework provides below apis::
-struct nvmem_device *nvmem_device_get(struct device *dev, const char *name);
-struct nvmem_device *devm_nvmem_device_get(struct device *dev,
+ struct nvmem_device *nvmem_device_get(struct device *dev, const char *name);
+ struct nvmem_device *devm_nvmem_device_get(struct device *dev,
const char *name);
-void nvmem_device_put(struct nvmem_device *nvmem);
-int nvmem_device_read(struct nvmem_device *nvmem, unsigned int offset,
+ void nvmem_device_put(struct nvmem_device *nvmem);
+ int nvmem_device_read(struct nvmem_device *nvmem, unsigned int offset,
size_t bytes, void *buf);
-int nvmem_device_write(struct nvmem_device *nvmem, unsigned int offset,
+ int nvmem_device_write(struct nvmem_device *nvmem, unsigned int offset,
size_t bytes, void *buf);
-int nvmem_device_cell_read(struct nvmem_device *nvmem,
+ int nvmem_device_cell_read(struct nvmem_device *nvmem,
struct nvmem_cell_info *info, void *buf);
-int nvmem_device_cell_write(struct nvmem_device *nvmem,
+ int nvmem_device_cell_write(struct nvmem_device *nvmem,
struct nvmem_cell_info *info, void *buf);
Before the consumers can read/write NVMEM directly, it should get hold
-of nvmem_controller from one of the *nvmem_device_get() api.
+of nvmem_controller from one of the `*nvmem_device_get()` api.
The difference between these apis and cell based apis is that these apis always
take nvmem_device as parameter.
@@ -145,12 +148,12 @@ take nvmem_device as parameter.
When a consumer no longer needs the NVMEM, it has to release the reference
to the NVMEM it has obtained using the APIs mentioned in the above section.
-The NVMEM framework provides 2 APIs to release a reference to the NVMEM.
+The NVMEM framework provides 2 APIs to release a reference to the NVMEM::
-void nvmem_cell_put(struct nvmem_cell *cell);
-void devm_nvmem_cell_put(struct device *dev, struct nvmem_cell *cell);
-void nvmem_device_put(struct nvmem_device *nvmem);
-void devm_nvmem_device_put(struct device *dev, struct nvmem_device *nvmem);
+ void nvmem_cell_put(struct nvmem_cell *cell);
+ void devm_nvmem_cell_put(struct device *dev, struct nvmem_cell *cell);
+ void nvmem_device_put(struct nvmem_device *nvmem);
+ void devm_nvmem_device_put(struct device *dev, struct nvmem_device *nvmem);
Both these APIs are used to release a reference to the NVMEM and
devm_nvmem_cell_put and devm_nvmem_device_put destroys the devres associated
@@ -162,20 +165,21 @@ Userspace
6. Userspace binary interface
==============================
-Userspace can read/write the raw NVMEM file located at
-/sys/bus/nvmem/devices/*/nvmem
+Userspace can read/write the raw NVMEM file located at::
-ex:
+ /sys/bus/nvmem/devices/*/nvmem
-hexdump /sys/bus/nvmem/devices/qfprom0/nvmem
+ex::
-0000000 0000 0000 0000 0000 0000 0000 0000 0000
-*
-00000a0 db10 2240 0000 e000 0c00 0c00 0000 0c00
-0000000 0000 0000 0000 0000 0000 0000 0000 0000
-...
-*
-0001000
+ hexdump /sys/bus/nvmem/devices/qfprom0/nvmem
+
+ 0000000 0000 0000 0000 0000 0000 0000 0000 0000
+ *
+ 00000a0 db10 2240 0000 e000 0c00 0c00 0000 0c00
+ 0000000 0000 0000 0000 0000 0000 0000 0000 0000
+ ...
+ *
+ 0001000
7. DeviceTree Binding
=====================
--
2.20.1
^ permalink raw reply related [flat|nested] 81+ messages in thread* [PATCH 56/57] docs: phy: convert samsung-usb2.txt to ReST format
2019-04-16 2:55 [PATCH 00/57] Convert files to ReST Mauro Carvalho Chehab
` (44 preceding siblings ...)
2019-04-16 2:56 ` [PATCH 55/57] docs: nvmem: convert file to ReST format Mauro Carvalho Chehab
@ 2019-04-16 2:56 ` Mauro Carvalho Chehab
2019-04-16 2:56 ` [PATCH 57/57] docs: Prepare files to be renamed to *.rst Mauro Carvalho Chehab
` (6 subsequent siblings)
52 siblings, 0 replies; 81+ messages in thread
From: Mauro Carvalho Chehab @ 2019-04-16 2:56 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet
In order to merge it into a Sphinx book, we need first to
convert to ReST.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
Documentation/phy/samsung-usb2.txt | 60 +++++++++++++++---------------
1 file changed, 31 insertions(+), 29 deletions(-)
diff --git a/Documentation/phy/samsung-usb2.txt b/Documentation/phy/samsung-usb2.txt
index ed12d437189d..c48c8b9797b9 100644
--- a/Documentation/phy/samsung-usb2.txt
+++ b/Documentation/phy/samsung-usb2.txt
@@ -1,9 +1,9 @@
-.------------------------------------------------------------------------------+
-| Samsung USB 2.0 PHY adaptation layer |
-+-----------------------------------------------------------------------------+'
+====================================
+Samsung USB 2.0 PHY adaptation layer
+====================================
-| 1. Description
-+----------------
+1. Description
+--------------
The architecture of the USB 2.0 PHY module in Samsung SoCs is similar
among many SoCs. In spite of the similarities it proved difficult to
@@ -14,8 +14,8 @@ the PHY powering up process had to be altered. This adaptation layer is
a compromise between having separate drivers and having a single driver
with added support for many special cases.
-| 2. Files description
-+----------------------
+2. Files description
+--------------------
- phy-samsung-usb2.c
This is the main file of the adaptation layer. This file contains
@@ -32,44 +32,45 @@ with added support for many special cases.
driver. In addition it should contain extern declarations for
structures that describe particular SoCs.
-| 3. Supporting SoCs
-+--------------------
+3. Supporting SoCs
+------------------
To support a new SoC a new file should be added to the drivers/phy
directory. Each SoC's configuration is stored in an instance of the
-struct samsung_usb2_phy_config.
+struct samsung_usb2_phy_config::
-struct samsung_usb2_phy_config {
+ struct samsung_usb2_phy_config {
const struct samsung_usb2_common_phy *phys;
int (*rate_to_clk)(unsigned long, u32 *);
unsigned int num_phys;
bool has_mode_switch;
-};
+ };
-The num_phys is the number of phys handled by the driver. *phys is an
+The num_phys is the number of phys handled by the driver. `*phys` is an
array that contains the configuration for each phy. The has_mode_switch
property is a boolean flag that determines whether the SoC has USB host
and device on a single pair of pins. If so, a special register has to
be modified to change the internal routing of these pins between a USB
device or host module.
-For example the configuration for Exynos 4210 is following:
+For example the configuration for Exynos 4210 is following::
-const struct samsung_usb2_phy_config exynos4210_usb2_phy_config = {
+ const struct samsung_usb2_phy_config exynos4210_usb2_phy_config = {
.has_mode_switch = 0,
.num_phys = EXYNOS4210_NUM_PHYS,
.phys = exynos4210_phys,
.rate_to_clk = exynos4210_rate_to_clk,
-}
+ }
+
+- `int (*rate_to_clk)(unsigned long, u32 *)`
-- int (*rate_to_clk)(unsigned long, u32 *)
The rate_to_clk callback is to convert the rate of the clock
used as the reference clock for the PHY module to the value
that should be written in the hardware register.
-The exynos4210_phys configuration array is as follows:
+The exynos4210_phys configuration array is as follows::
-static const struct samsung_usb2_common_phy exynos4210_phys[] = {
+ static const struct samsung_usb2_common_phy exynos4210_phys[] = {
{
.label = "device",
.id = EXYNOS4210_DEVICE,
@@ -95,29 +96,30 @@ static const struct samsung_usb2_common_phy exynos4210_phys[] = {
.power_off = exynos4210_power_off,
},
{},
-};
+ };
+
+- `int (*power_on)(struct samsung_usb2_phy_instance *);`
+ `int (*power_off)(struct samsung_usb2_phy_instance *);`
-- int (*power_on)(struct samsung_usb2_phy_instance *);
-- int (*power_off)(struct samsung_usb2_phy_instance *);
These two callbacks are used to power on and power off the phy
by modifying appropriate registers.
Final change to the driver is adding appropriate compatible value to the
phy-samsung-usb2.c file. In case of Exynos 4210 the following lines were
-added to the struct of_device_id samsung_usb2_phy_of_match[] array:
+added to the struct of_device_id samsung_usb2_phy_of_match[] array::
-#ifdef CONFIG_PHY_EXYNOS4210_USB2
+ #ifdef CONFIG_PHY_EXYNOS4210_USB2
{
.compatible = "samsung,exynos4210-usb2-phy",
.data = &exynos4210_usb2_phy_config,
},
-#endif
+ #endif
To add further flexibility to the driver the Kconfig file enables to
include support for selected SoCs in the compiled driver. The Kconfig
-entry for Exynos 4210 is following:
+entry for Exynos 4210 is following::
-config PHY_EXYNOS4210_USB2
+ config PHY_EXYNOS4210_USB2
bool "Support for Exynos 4210"
depends on PHY_SAMSUNG_USB2
depends on CPU_EXYNOS4210
@@ -128,8 +130,8 @@ config PHY_EXYNOS4210_USB2
phys are available - device, host, HSCI0 and HSCI1.
The newly created file that supports the new SoC has to be also added to the
-Makefile. In case of Exynos 4210 the added line is following:
+Makefile. In case of Exynos 4210 the added line is following::
-obj-$(CONFIG_PHY_EXYNOS4210_USB2) += phy-exynos4210-usb2.o
+ obj-$(CONFIG_PHY_EXYNOS4210_USB2) += phy-exynos4210-usb2.o
After completing these steps the support for the new SoC should be ready.
--
2.20.1
^ permalink raw reply related [flat|nested] 81+ messages in thread* [PATCH 57/57] docs: Prepare files to be renamed to *.rst
2019-04-16 2:55 [PATCH 00/57] Convert files to ReST Mauro Carvalho Chehab
` (45 preceding siblings ...)
2019-04-16 2:56 ` [PATCH 56/57] docs: phy: convert samsung-usb2.txt " Mauro Carvalho Chehab
@ 2019-04-16 2:56 ` Mauro Carvalho Chehab
[not found] ` <eaafc5741ccfe3b96ab2a9ef799c537c49ab20e5.1555382110.git.mchehab+samsung@kernel.org>
` (5 subsequent siblings)
52 siblings, 0 replies; 81+ messages in thread
From: Mauro Carvalho Chehab @ 2019-04-16 2:56 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet
Remove some blank spaces at the end of the lines.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
Documentation/bt8xxgpio.txt | 1 -
Documentation/bus-virt-phys-mapping.txt | 50 ++++++++++++------------
Documentation/highuid.txt | 2 +-
Documentation/kobject.txt | 2 +-
Documentation/ldm.txt | 3 +-
Documentation/memory-barriers.txt | 2 +-
Documentation/numastat.txt | 1 -
Documentation/pnp.txt | 11 +++---
Documentation/preempt-locking.txt | 2 +-
Documentation/rbtree.txt | 52 ++++++++++++-------------
Documentation/rtc.txt | 6 +--
Documentation/zorro.txt | 5 +--
12 files changed, 66 insertions(+), 71 deletions(-)
diff --git a/Documentation/bt8xxgpio.txt b/Documentation/bt8xxgpio.txt
index a845feb074de..4f937bead52c 100644
--- a/Documentation/bt8xxgpio.txt
+++ b/Documentation/bt8xxgpio.txt
@@ -59,4 +59,3 @@ The GPIO pins are marked with G00-G23::
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
^
This is pin 1
-
diff --git a/Documentation/bus-virt-phys-mapping.txt b/Documentation/bus-virt-phys-mapping.txt
index 4bb07c2f3e7d..0d45d6cf0fcb 100644
--- a/Documentation/bus-virt-phys-mapping.txt
+++ b/Documentation/bus-virt-phys-mapping.txt
@@ -19,35 +19,35 @@ How to access I/O mapped memory from within device drivers
The AHA-1542 is a bus-master device, and your patch makes the driver give the
controller the physical address of the buffers, which is correct on x86
-(because all bus master devices see the physical memory mappings directly).
+(because all bus master devices see the physical memory mappings directly).
However, on many setups, there are actually **three** different ways of looking
at memory addresses, and in this case we actually want the third, the
-so-called "bus address".
+so-called "bus address".
Essentially, the three ways of addressing memory are (this is "real memory",
-that is, normal RAM--see later about other details):
+that is, normal RAM--see later about other details):
- - CPU untranslated. This is the "physical" address. Physical address
+ - CPU untranslated. This is the "physical" address. Physical address
0 is what the CPU sees when it drives zeroes on the memory bus.
- - CPU translated address. This is the "virtual" address, and is
+ - CPU translated address. This is the "virtual" address, and is
completely internal to the CPU itself with the CPU doing the appropriate
- translations into "CPU untranslated".
+ translations into "CPU untranslated".
- - bus address. This is the address of memory as seen by OTHER devices,
- not the CPU. Now, in theory there could be many different bus
+ - bus address. This is the address of memory as seen by OTHER devices,
+ not the CPU. Now, in theory there could be many different bus
addresses, with each device seeing memory in some device-specific way, but
happily most hardware designers aren't actually actively trying to make
- things any more complex than necessary, so you can assume that all
- external hardware sees the memory the same way.
+ things any more complex than necessary, so you can assume that all
+ external hardware sees the memory the same way.
Now, on normal PCs the bus address is exactly the same as the physical
address, and things are very simple indeed. However, they are that simple
because the memory and the devices share the same address space, and that is
-not generally necessarily true on other PCI/ISA setups.
+not generally necessarily true on other PCI/ISA setups.
-Now, just as an example, on the PReP (PowerPC Reference Platform), the
+Now, just as an example, on the PReP (PowerPC Reference Platform), the
CPU sees a memory map something like this (this is from memory)::
0-2 GB "real memory"
@@ -58,17 +58,17 @@ Now, that looks simple enough. However, when you look at the same thing from
the viewpoint of the devices, you have the reverse, and the physical memory
address 0 actually shows up as address 2 GB for any IO master.
-So when the CPU wants any bus master to write to physical memory 0, it
+So when the CPU wants any bus master to write to physical memory 0, it
has to give the master address 0x80000000 as the memory address.
-So, for example, depending on how the kernel is actually mapped on the
+So, for example, depending on how the kernel is actually mapped on the
PPC, you can end up with a setup like this::
physical address: 0
virtual address: 0xC0000000
bus address: 0x80000000
-where all the addresses actually point to the same thing. It's just seen
+where all the addresses actually point to the same thing. It's just seen
through different translations..
Similarly, on the Alpha, the normal translation is::
@@ -78,7 +78,7 @@ Similarly, on the Alpha, the normal translation is::
bus address: 0x40000000
(but there are also Alphas where the physical address and the bus address
-are the same).
+are the same).
Anyway, the way to look up all these translations, you do::
@@ -113,7 +113,7 @@ pointer from the kernel. So you can have something like this::
case STATUS_OK:
...
-on the other hand, you want the bus address when you have a buffer that
+on the other hand, you want the bus address when you have a buffer that
you want to give to the controller::
/* ask the controller to read the sense status into "sense_buffer" */
@@ -124,7 +124,7 @@ you want to give to the controller::
And you generally **never** want to use the physical address, because you can't
use that from the CPU (the CPU only uses translated virtual addresses), and
-you can't use it from the bus master.
+you can't use it from the bus master.
So why do we care about the physical address at all? We do need the physical
address in some cases, it's just not very often in normal code. The physical
@@ -142,7 +142,7 @@ shouldn't need to know about "bus addresses" etc).
There is a completely different type of memory too, and that's the "shared
memory" on the PCI or ISA bus. That's generally not RAM (although in the case
of a video graphics card it can be normal DRAM that is just used for a frame
-buffer), but can be things like a packet buffer in a network card etc.
+buffer), but can be things like a packet buffer in a network card etc.
This memory is called "PCI memory" or "shared memory" or "IO memory" or
whatever, and there is only one way to access it: the readb/writeb and
@@ -151,7 +151,7 @@ there is really nothing you can do with such an address: it's not
conceptually in the same memory space as "real memory" at all, so you cannot
just dereference a pointer. (Sadly, on x86 it **is** in the same memory space,
so on x86 it actually works to just deference a pointer, but it's not
-portable).
+portable).
For such memory, you can do things like:
@@ -197,19 +197,19 @@ Note that kernel versions 2.0.x (and earlier) mistakenly called the
ioremap() function "vremap()". ioremap() is the proper name, but I
didn't think straight when I wrote it originally. People who have to
support both can do something like::
-
+
/* support old naming silliness */
#if LINUX_VERSION_CODE < 0x020100
#define ioremap vremap
- #define iounmap vfree
+ #define iounmap vfree
#endif
-
+
at the top of their source files, and then they can use the right names
-even on 2.0.x systems.
+even on 2.0.x systems.
And the above sounds worse than it really is. Most real drivers really
don't do all that complex things (or rather: the complexity is not so
-much in the actual IO accesses as in error handling and timeouts etc).
+much in the actual IO accesses as in error handling and timeouts etc).
It's generally not hard to fix drivers, and in many cases the code
actually looks better afterwards::
diff --git a/Documentation/highuid.txt b/Documentation/highuid.txt
index 6ee70465c0ea..1ab59d7807d1 100644
--- a/Documentation/highuid.txt
+++ b/Documentation/highuid.txt
@@ -19,7 +19,7 @@ What's left to be done for 32-bit UIDs on all Linux architectures:
underlying filesystem, because quota records are written at offsets
corresponding to the UID in question.
Further investigation is needed to see if the quota system can cope
- properly with huge UIDs. If it can deal with 64-bit file offsets on all
+ properly with huge UIDs. If it can deal with 64-bit file offsets on all
architectures, this should not be a problem.
- Decide whether or not to keep backwards compatibility with the system
diff --git a/Documentation/kobject.txt b/Documentation/kobject.txt
index ff4c25098119..fa0009ca0bc7 100644
--- a/Documentation/kobject.txt
+++ b/Documentation/kobject.txt
@@ -270,7 +270,7 @@ such a method has a form like::
void my_object_release(struct kobject *kobj)
{
- struct my_object *mine = container_of(kobj, struct my_object, kobj);
+ struct my_object *mine = container_of(kobj, struct my_object, kobj);
/* Perform any additional cleanup on this object, then... */
kfree(mine);
diff --git a/Documentation/ldm.txt b/Documentation/ldm.txt
index 12c571368e73..90ccf24ebfdd 100644
--- a/Documentation/ldm.txt
+++ b/Documentation/ldm.txt
@@ -75,7 +75,7 @@ When Linux boots, you will see something like::
Compiling LDM Support
---------------------
-To enable LDM, choose the following two options:
+To enable LDM, choose the following two options:
- "Advanced partition selection" CONFIG_PARTITION_ADVANCED
- "Windows Logical Disk Manager (Dynamic Disk) support" CONFIG_LDM_PARTITION
@@ -118,4 +118,3 @@ me.
Cheers,
FlatCap - Richard Russon
ldm@flatcap.org
-
diff --git a/Documentation/memory-barriers.txt b/Documentation/memory-barriers.txt
index 4e0446230205..f585022aed8f 100644
--- a/Documentation/memory-barriers.txt
+++ b/Documentation/memory-barriers.txt
@@ -334,7 +334,7 @@ And there are anti-guarantees:
of the standard containing this guarantee is Section 3.14, which
defines "memory location" as follows:
- memory location
+ memory location
either an object of scalar type, or a maximal sequence
of adjacent bit-fields all having nonzero width
diff --git a/Documentation/numastat.txt b/Documentation/numastat.txt
index aaf1667489f8..d6f07ca00c27 100644
--- a/Documentation/numastat.txt
+++ b/Documentation/numastat.txt
@@ -27,4 +27,3 @@ interleave_hit Interleaving wanted to allocate from this node
For easier reading you can use the numastat utility from the numactl package
(http://oss.sgi.com/projects/libnuma/). Note that it only works
well right now on machines with a small number of CPUs.
-
diff --git a/Documentation/pnp.txt b/Documentation/pnp.txt
index bab2d10631f0..c103acb9ad99 100644
--- a/Documentation/pnp.txt
+++ b/Documentation/pnp.txt
@@ -10,7 +10,7 @@ Overview
--------
Plug and Play provides a means of detecting and setting resources for legacy or
-otherwise unconfigurable devices. The Linux Plug and Play Layer provides these
+otherwise unconfigurable devices. The Linux Plug and Play Layer provides these
services to compatible drivers.
@@ -18,7 +18,7 @@ The User Interface
------------------
The Linux Plug and Play user interface provides a means to activate PnP devices
-for legacy and user level drivers that do not support Linux Plug and Play. The
+for legacy and user level drivers that do not support Linux Plug and Play. The
user interface is integrated into sysfs.
In addition to the standard sysfs file the following are created in each
@@ -113,9 +113,9 @@ The Unified Plug and Play Layer
-------------------------------
All Plug and Play drivers, protocols, and services meet at a central location
-called the Plug and Play Layer. This layer is responsible for the exchange of
-information between PnP drivers and PnP protocols. Thus it automatically
-forwards commands to the proper protocol. This makes writing PnP drivers
+called the Plug and Play Layer. This layer is responsible for the exchange of
+information between PnP drivers and PnP protocols. Thus it automatically
+forwards commands to the proper protocol. This makes writing PnP drivers
significantly easier.
The following functions are available from the Plug and Play Layer:
@@ -289,4 +289,3 @@ They are as follows::
unsigned short vendor,
unsigned short function,
struct pnp_dev *from)
-
diff --git a/Documentation/preempt-locking.txt b/Documentation/preempt-locking.txt
index 509f5a422d57..47ad9688dc11 100644
--- a/Documentation/preempt-locking.txt
+++ b/Documentation/preempt-locking.txt
@@ -16,7 +16,7 @@ requires explicit additional locking for very few additional situations.
This document is for all kernel hackers. Developing code in the kernel
requires protecting these situations.
-
+
RULE #1: Per-CPU data structures need explicit protection
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
diff --git a/Documentation/rbtree.txt b/Documentation/rbtree.txt
index c42a21b99046..f2bea06b471b 100644
--- a/Documentation/rbtree.txt
+++ b/Documentation/rbtree.txt
@@ -62,8 +62,8 @@ Creating a new rbtree
Data nodes in an rbtree tree are structures containing a struct rb_node member::
struct mytype {
- struct rb_node node;
- char *keystring;
+ struct rb_node node;
+ char *keystring;
};
When dealing with a pointer to the embedded struct rb_node, the containing data
@@ -85,20 +85,20 @@ Example::
struct mytype *my_search(struct rb_root *root, char *string)
{
- struct rb_node *node = root->rb_node;
+ struct rb_node *node = root->rb_node;
- while (node) {
- struct mytype *data = container_of(node, struct mytype, node);
+ while (node) {
+ struct mytype *data = container_of(node, struct mytype, node);
int result;
result = strcmp(string, data->keystring);
if (result < 0)
- node = node->rb_left;
+ node = node->rb_left;
else if (result > 0)
- node = node->rb_right;
+ node = node->rb_right;
else
- return data;
+ return data;
}
return NULL;
}
@@ -117,25 +117,25 @@ Example::
int my_insert(struct rb_root *root, struct mytype *data)
{
- struct rb_node **new = &(root->rb_node), *parent = NULL;
+ struct rb_node **new = &(root->rb_node), *parent = NULL;
- /* Figure out where to put new node */
- while (*new) {
- struct mytype *this = container_of(*new, struct mytype, node);
- int result = strcmp(data->keystring, this->keystring);
+ /* Figure out where to put new node */
+ while (*new) {
+ struct mytype *this = container_of(*new, struct mytype, node);
+ int result = strcmp(data->keystring, this->keystring);
parent = *new;
- if (result < 0)
- new = &((*new)->rb_left);
- else if (result > 0)
- new = &((*new)->rb_right);
- else
- return FALSE;
- }
+ if (result < 0)
+ new = &((*new)->rb_left);
+ else if (result > 0)
+ new = &((*new)->rb_right);
+ else
+ return FALSE;
+ }
- /* Add new node and rebalance tree. */
- rb_link_node(&data->node, parent, new);
- rb_insert_color(&data->node, root);
+ /* Add new node and rebalance tree. */
+ rb_link_node(&data->node, parent, new);
+ rb_insert_color(&data->node, root);
return TRUE;
}
@@ -152,14 +152,14 @@ Example::
struct mytype *data = mysearch(&mytree, "walrus");
if (data) {
- rb_erase(&data->node, &mytree);
- myfree(data);
+ rb_erase(&data->node, &mytree);
+ myfree(data);
}
To replace an existing node in a tree with a new one with the same key, call::
void rb_replace_node(struct rb_node *old, struct rb_node *new,
- struct rb_root *tree);
+ struct rb_root *tree);
Replacing a node this way does not re-sort the tree: If the new node doesn't
have the same key as the old node, the rbtree will probably become corrupted.
diff --git a/Documentation/rtc.txt b/Documentation/rtc.txt
index 688c95b11919..c7647de33c69 100644
--- a/Documentation/rtc.txt
+++ b/Documentation/rtc.txt
@@ -86,9 +86,9 @@ a different value to /proc/sys/dev/rtc/max-user-freq. Note that the
interrupt handler is only a few lines of code to minimize any possibility
of this effect.
-Also, if the kernel time is synchronized with an external source, the
-kernel will write the time back to the CMOS clock every 11 minutes. In
-the process of doing this, the kernel briefly turns off RTC periodic
+Also, if the kernel time is synchronized with an external source, the
+kernel will write the time back to the CMOS clock every 11 minutes. In
+the process of doing this, the kernel briefly turns off RTC periodic
interrupts, so be aware of this if you are doing serious work. If you
don't synchronize the kernel time with an external source (via ntp or
whatever) then the kernel will keep its hands off the RTC, allowing you
diff --git a/Documentation/zorro.txt b/Documentation/zorro.txt
index 664072b017e3..59fb1634d903 100644
--- a/Documentation/zorro.txt
+++ b/Documentation/zorro.txt
@@ -77,7 +77,7 @@ The treatment of these regions depends on the type of Zorro space:
- Zorro II address space is always mapped and does not have to be mapped
explicitly using z_ioremap().
-
+
Conversion from bus/physical Zorro II addresses to kernel virtual addresses
and vice versa is done using::
@@ -86,7 +86,7 @@ The treatment of these regions depends on the type of Zorro space:
- Zorro III address space must be mapped explicitly using z_ioremap() first
before it can be accessed::
-
+
virt_addr = z_ioremap(bus_addr, size);
...
z_iounmap(virt_addr);
@@ -101,4 +101,3 @@ References
#. linux/arch/m68k/include/asm/zorro.h
#. linux/drivers/zorro
#. /proc/bus/zorro
-
--
2.20.1
^ permalink raw reply related [flat|nested] 81+ messages in thread[parent not found: <eaafc5741ccfe3b96ab2a9ef799c537c49ab20e5.1555382110.git.mchehab+samsung@kernel.org>]
* Re: [PATCH 36/57] docs: usb: convert documents to ReST
[not found] ` <eaafc5741ccfe3b96ab2a9ef799c537c49ab20e5.1555382110.git.mchehab+samsung@kernel.org>
@ 2019-04-16 6:12 ` Felipe Balbi
2019-04-16 11:43 ` Mauro Carvalho Chehab
0 siblings, 1 reply; 81+ messages in thread
From: Felipe Balbi @ 2019-04-16 6:12 UTC (permalink / raw)
To: Mauro Carvalho Chehab, Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Greg Kroah-Hartman, linux-usb
[-- Attachment #1: Type: text/plain, Size: 1723 bytes --]
Mauro Carvalho Chehab <mchehab+samsung@kernel.org> writes:
> Convert USB documents to ReST, in order to prepare for adding it
> to the kernel API book, as most of the stuff there are driver or
> subsystem-related.
>
> Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
> ---
> Documentation/usb/WUSB-Design-overview.txt | 56 +-
> Documentation/usb/acm.txt | 156 +++---
> Documentation/usb/authorization.txt | 75 +--
> Documentation/usb/chipidea.txt | 101 ++--
> Documentation/usb/dwc3.txt | 12 +-
> Documentation/usb/ehci.txt | 42 +-
> Documentation/usb/functionfs.txt | 17 +-
> Documentation/usb/gadget-testing.txt | 609 ++++++++++++---------
> Documentation/usb/gadget_configfs.txt | 302 +++++-----
> Documentation/usb/gadget_hid.txt | 175 +++---
> Documentation/usb/gadget_multi.txt | 43 +-
> Documentation/usb/gadget_printer.txt | 155 +++---
> Documentation/usb/gadget_serial.txt | 73 +--
> Documentation/usb/iuu_phoenix.txt | 34 +-
> Documentation/usb/mass-storage.txt | 19 +-
> Documentation/usb/misc_usbsevseg.txt | 9 +-
> Documentation/usb/mtouchusb.txt | 42 +-
> Documentation/usb/ohci.txt | 5 +-
> Documentation/usb/rio.txt | 83 +--
> Documentation/usb/usb-help.txt | 21 +-
> Documentation/usb/usb-serial.txt | 203 ++++---
> Documentation/usb/usbip_protocol.txt | 552 ++++++++++---------
> Documentation/usb/usbmon.txt | 100 ++--
should you change extension to .rst while at that?
--
balbi
[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 832 bytes --]
^ permalink raw reply [flat|nested] 81+ messages in thread* Re: [PATCH 36/57] docs: usb: convert documents to ReST
2019-04-16 6:12 ` [PATCH 36/57] docs: usb: convert documents to ReST Felipe Balbi
@ 2019-04-16 11:43 ` Mauro Carvalho Chehab
0 siblings, 0 replies; 81+ messages in thread
From: Mauro Carvalho Chehab @ 2019-04-16 11:43 UTC (permalink / raw)
To: Felipe Balbi
Cc: Linux Doc Mailing List, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Greg Kroah-Hartman, linux-usb
Em Tue, 16 Apr 2019 09:12:32 +0300
Felipe Balbi <felipe.balbi@linux.intel.com> escreveu:
> Mauro Carvalho Chehab <mchehab+samsung@kernel.org> writes:
>
> > Convert USB documents to ReST, in order to prepare for adding it
> > to the kernel API book, as most of the stuff there are driver or
> > subsystem-related.
> >
> > Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
> > ---
> > Documentation/usb/WUSB-Design-overview.txt | 56 +-
> > Documentation/usb/acm.txt | 156 +++---
> > Documentation/usb/authorization.txt | 75 +--
> > Documentation/usb/chipidea.txt | 101 ++--
> > Documentation/usb/dwc3.txt | 12 +-
> > Documentation/usb/ehci.txt | 42 +-
> > Documentation/usb/functionfs.txt | 17 +-
> > Documentation/usb/gadget-testing.txt | 609 ++++++++++++---------
> > Documentation/usb/gadget_configfs.txt | 302 +++++-----
> > Documentation/usb/gadget_hid.txt | 175 +++---
> > Documentation/usb/gadget_multi.txt | 43 +-
> > Documentation/usb/gadget_printer.txt | 155 +++---
> > Documentation/usb/gadget_serial.txt | 73 +--
> > Documentation/usb/iuu_phoenix.txt | 34 +-
> > Documentation/usb/mass-storage.txt | 19 +-
> > Documentation/usb/misc_usbsevseg.txt | 9 +-
> > Documentation/usb/mtouchusb.txt | 42 +-
> > Documentation/usb/ohci.txt | 5 +-
> > Documentation/usb/rio.txt | 83 +--
> > Documentation/usb/usb-help.txt | 21 +-
> > Documentation/usb/usb-serial.txt | 203 ++++---
> > Documentation/usb/usbip_protocol.txt | 552 ++++++++++---------
> > Documentation/usb/usbmon.txt | 100 ++--
>
> should you change extension to .rst while at that?
I did that on a first version (not submitted):
https://git.linuxtv.org/mchehab/experimental.git/commit/?h=all_with_indexes&id=d7eec4678dbfeb1a40c58bca7a157c8a4c39fa04
but I opted do the postpone the rename to a new series yet to be
sent.
The problem is that renaming it will make Sphinx to try to build them,
causing lots of warnings because they won't be inside an index file.
Adding index would touch Documentation/index (or Documentation/drivers-api),
with would cause merge conflicts.
Once this patch gets merged upstream, a renaming patch can happen
anytime. It probably makes sense to do all renames at once, late
at a merge window.
Thanks,
Mauro
^ permalink raw reply [flat|nested] 81+ messages in thread
[parent not found: <cfab8842b681a84518b327980b08aee95d159605.1555382110.git.mchehab+samsung@kernel.org>]
* Re: [PATCH 25/57] docs: power: convert docs to ReST
[not found] ` <cfab8842b681a84518b327980b08aee95d159605.1555382110.git.mchehab+samsung@kernel.org>
@ 2019-04-16 7:20 ` Pavel Machek
2019-04-16 8:59 ` Rafael J. Wysocki
1 sibling, 0 replies; 81+ messages in thread
From: Pavel Machek @ 2019-04-16 7:20 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: Linux Doc Mailing List, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Rafael J. Wysocki, Len Brown, Liam Girdwood,
Mark Brown, linux-pm
[-- Attachment #1: Type: text/plain, Size: 398 bytes --]
On Mon 2019-04-15 23:55:50, Mauro Carvalho Chehab wrote:
> Convert the PM documents to ReST, in order to allow them to
> build with Sphinx.
>
> Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
Acked-by: Pavel Machek <pavel@ucw.cz>
--
(english) http://www.livejournal.com/~pavelmachek
(cesky, pictures) http://atrey.karlin.mff.cuni.cz/~pavel/picture/horses/blog.html
[-- Attachment #2: Digital signature --]
[-- Type: application/pgp-signature, Size: 181 bytes --]
^ permalink raw reply [flat|nested] 81+ messages in thread* Re: [PATCH 25/57] docs: power: convert docs to ReST
[not found] ` <cfab8842b681a84518b327980b08aee95d159605.1555382110.git.mchehab+samsung@kernel.org>
2019-04-16 7:20 ` [PATCH 25/57] docs: power: convert docs " Pavel Machek
@ 2019-04-16 8:59 ` Rafael J. Wysocki
2019-04-16 10:41 ` Mauro Carvalho Chehab
1 sibling, 1 reply; 81+ messages in thread
From: Rafael J. Wysocki @ 2019-04-16 8:59 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: Linux Doc Mailing List, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Len Brown, Pavel Machek, Liam Girdwood,
Mark Brown, linux-pm
On Tuesday, April 16, 2019 4:55:50 AM CEST Mauro Carvalho Chehab wrote:
> Convert the PM documents to ReST, in order to allow them to
> build with Sphinx.
And what exactly is the motivation for doing that?
There are plans for some of these files to be converted already, some of them need to be merged or split and it just is not worth it to convert some others.
Thanks,
Rafael
^ permalink raw reply [flat|nested] 81+ messages in thread* Re: [PATCH 25/57] docs: power: convert docs to ReST
2019-04-16 8:59 ` Rafael J. Wysocki
@ 2019-04-16 10:41 ` Mauro Carvalho Chehab
2019-04-16 10:47 ` Rafael J. Wysocki
0 siblings, 1 reply; 81+ messages in thread
From: Mauro Carvalho Chehab @ 2019-04-16 10:41 UTC (permalink / raw)
To: Rafael J. Wysocki
Cc: Linux Doc Mailing List, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Len Brown, Pavel Machek, Liam Girdwood,
Mark Brown, linux-pm
Em Tue, 16 Apr 2019 10:59:23 +0200
"Rafael J. Wysocki" <rjw@rjwysocki.net> escreveu:
> On Tuesday, April 16, 2019 4:55:50 AM CEST Mauro Carvalho Chehab wrote:
> > Convert the PM documents to ReST, in order to allow them to
> > build with Sphinx.
>
> And what exactly is the motivation for doing that?
Providing a little of context, I tried to submit a patchset that would
just place existing documents on a sort of "staging" way, without
actually reformatting:
https://lkml.org/lkml/2019/4/10/244
Jon had some concerns about such approach.
So, I split into one patch per subsystem. Then, I looked on each, and
opted to do the conversion, as, on several cases, the conversion
seemed to be easy enough.
My selfish motivation is that I was returning from vacations and wanted to
review some stuff at the Kernel docs, but, discovered that, despite we
started migrating the documentation on May, 2016, still the vast
majority of documents that weren't converted.
For me, the main motivation for the conversion are:
1) Documents will be grouped into books and chapters,
with makes easier to study them;
2) The Sphinx javascript is very convenient for seeking a
document and a keyword within the body of the document;
3) Using a browser to read documentation allows to better
scale the document to the screen I'm using.
That's said, sometimes I just prefer to convert the document
to a PDF and read it on my tablet. PDF tools also provide
similar features.
In other words, for my own consumption, I prefer reading
documents using document tools, instead of reading in plain
text.
> There are plans for some of these files to be converted already, some of them need to be merged or split and it just is not worth it to convert some others.
Feel free to use this patch as an starting point. If you prefer,
I can split into smaller sets, but my main goal here is just
to help to speedup the conversion.
Thanks,
Mauro
^ permalink raw reply [flat|nested] 81+ messages in thread
* Re: [PATCH 25/57] docs: power: convert docs to ReST
2019-04-16 10:41 ` Mauro Carvalho Chehab
@ 2019-04-16 10:47 ` Rafael J. Wysocki
0 siblings, 0 replies; 81+ messages in thread
From: Rafael J. Wysocki @ 2019-04-16 10:47 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: Rafael J. Wysocki, Linux Doc Mailing List, Mauro Carvalho Chehab,
Linux Kernel Mailing List, Jonathan Corbet, Len Brown,
Pavel Machek, Liam Girdwood, Mark Brown, Linux PM
On Tue, Apr 16, 2019 at 12:41 PM Mauro Carvalho Chehab
<mchehab+samsung@kernel.org> wrote:
>
> Em Tue, 16 Apr 2019 10:59:23 +0200
> "Rafael J. Wysocki" <rjw@rjwysocki.net> escreveu:
>
> > On Tuesday, April 16, 2019 4:55:50 AM CEST Mauro Carvalho Chehab wrote:
> > > Convert the PM documents to ReST, in order to allow them to
> > > build with Sphinx.
> >
> > And what exactly is the motivation for doing that?
>
> Providing a little of context, I tried to submit a patchset that would
> just place existing documents on a sort of "staging" way, without
> actually reformatting:
>
> https://lkml.org/lkml/2019/4/10/244
>
> Jon had some concerns about such approach.
>
> So, I split into one patch per subsystem. Then, I looked on each, and
> opted to do the conversion, as, on several cases, the conversion
> seemed to be easy enough.
>
> My selfish motivation is that I was returning from vacations and wanted to
> review some stuff at the Kernel docs, but, discovered that, despite we
> started migrating the documentation on May, 2016, still the vast
> majority of documents that weren't converted.
>
> For me, the main motivation for the conversion are:
>
> 1) Documents will be grouped into books and chapters,
> with makes easier to study them;
> 2) The Sphinx javascript is very convenient for seeking a
> document and a keyword within the body of the document;
> 3) Using a browser to read documentation allows to better
> scale the document to the screen I'm using.
>
> That's said, sometimes I just prefer to convert the document
> to a PDF and read it on my tablet. PDF tools also provide
> similar features.
>
> In other words, for my own consumption, I prefer reading
> documents using document tools, instead of reading in plain
> text.
I see, thanks!
> > There are plans for some of these files to be converted already, some of them need to be merged or split and it just is not worth it to convert some others.
>
> Feel free to use this patch as an starting point. If you prefer,
> I can split into smaller sets, but my main goal here is just
> to help to speedup the conversion.
OK, we'll see. Thank you!
^ permalink raw reply [flat|nested] 81+ messages in thread
[parent not found: <9dd3c4eca01489bd67ea6de88dfedef8b0e81901.1555382110.git.mchehab+samsung@kernel.org>]
* Re: [PATCH 10/57] docs: device-mapper: convert it to ReST format
[not found] ` <9dd3c4eca01489bd67ea6de88dfedef8b0e81901.1555382110.git.mchehab+samsung@kernel.org>
@ 2019-04-16 13:28 ` Mike Snitzer
2019-04-16 14:00 ` Jonathan Corbet
0 siblings, 1 reply; 81+ messages in thread
From: Mike Snitzer @ 2019-04-16 13:28 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: Linux Doc Mailing List, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Alasdair Kergon, dm-devel
On Mon, Apr 15 2019 at 10:55pm -0400,
Mauro Carvalho Chehab <mchehab+samsung@kernel.org> wrote:
> Convert the Device Mapper documentation to ReST.
Can you help me understand why this is the direction text based
Documenation is taking in the Linux kernel? All I see is markup, and
escaping of characters, that is a chore to administer over time.
Please advise, thanks.
Mike
^ permalink raw reply [flat|nested] 81+ messages in thread* Re: [PATCH 10/57] docs: device-mapper: convert it to ReST format
2019-04-16 13:28 ` [PATCH 10/57] docs: device-mapper: convert it to ReST format Mike Snitzer
@ 2019-04-16 14:00 ` Jonathan Corbet
2019-04-16 14:33 ` Mauro Carvalho Chehab
2019-04-16 15:48 ` Mike Snitzer
0 siblings, 2 replies; 81+ messages in thread
From: Jonathan Corbet @ 2019-04-16 14:00 UTC (permalink / raw)
To: Mike Snitzer
Cc: Mauro Carvalho Chehab, Linux Doc Mailing List,
Mauro Carvalho Chehab, linux-kernel, Alasdair Kergon, dm-devel
On Tue, 16 Apr 2019 09:28:52 -0400
Mike Snitzer <snitzer@redhat.com> wrote:
> Can you help me understand why this is the direction text based
> Documenation is taking in the Linux kernel? All I see is markup, and
> escaping of characters, that is a chore to administer over time.
This is a discussion that was mostly resolved some years ago...
Classic Documentation/ is a jumbled collection of unorganized text files,
some of which contain highly useful information and others of which
haven't had much to offer since about 1996. We are working to turn it
into an organized collection where, hopefully, some thought has actually
been given to the people who will be reading it.
The ReST conversion, in particular, allows us to link documents into a
larger structure, create indexes and cross references, and produce output
in formats like HTML and PDF. It lets us present the documentation like
this:
https://www.kernel.org/doc/html/latest/
Among other things, making the documentation more accessible in this way
makes it easier and more rewarding for developers to improve it, and I
believe we are seeing the results of that. Linus called out the
documentation work in the 5.1-rc1 announcement, for example.
Nobody has complained about the maintenance burden of RST docs - so far as
I have heard, anyway. Things do break occasionally, but problems in the
docs build almost always result from code changes that mess up the
kerneldoc comments rather than RST changes, and it's been that way for as
long as I've been paying attention.
Thanks,
jon
^ permalink raw reply [flat|nested] 81+ messages in thread
* Re: [PATCH 10/57] docs: device-mapper: convert it to ReST format
2019-04-16 14:00 ` Jonathan Corbet
@ 2019-04-16 14:33 ` Mauro Carvalho Chehab
2019-04-16 15:48 ` Mike Snitzer
1 sibling, 0 replies; 81+ messages in thread
From: Mauro Carvalho Chehab @ 2019-04-16 14:33 UTC (permalink / raw)
To: Jonathan Corbet
Cc: Mike Snitzer, Linux Doc Mailing List, Mauro Carvalho Chehab,
linux-kernel, Alasdair Kergon, dm-devel
Em Tue, 16 Apr 2019 08:00:24 -0600
Jonathan Corbet <corbet@lwn.net> escreveu:
> On Tue, 16 Apr 2019 09:28:52 -0400
> Mike Snitzer <snitzer@redhat.com> wrote:
>
> > Can you help me understand why this is the direction text based
> > Documenation is taking in the Linux kernel? All I see is markup, and
> > escaping of characters, that is a chore to administer over time.
>
> This is a discussion that was mostly resolved some years ago...
>
> Classic Documentation/ is a jumbled collection of unorganized text files,
> some of which contain highly useful information and others of which
> haven't had much to offer since about 1996. We are working to turn it
> into an organized collection where, hopefully, some thought has actually
> been given to the people who will be reading it.
>
> The ReST conversion, in particular, allows us to link documents into a
> larger structure, create indexes and cross references, and produce output
> in formats like HTML and PDF. It lets us present the documentation like
> this:
>
> https://www.kernel.org/doc/html/latest/
Just to mention, in the specific case of the device-mapper patch,
this is the result of those changes (after renaming the files to .rst,
and adding an index file):
https://www.infradead.org/~mchehab/rst_conversion/device-mapper/index.html
>
> Among other things, making the documentation more accessible in this way
> makes it easier and more rewarding for developers to improve it, and I
> believe we are seeing the results of that. Linus called out the
> documentation work in the 5.1-rc1 announcement, for example.
>
> Nobody has complained about the maintenance burden of RST docs - so far as
> I have heard, anyway. Things do break occasionally, but problems in the
> docs build almost always result from code changes that mess up the
> kerneldoc comments rather than RST changes, and it's been that way for as
> long as I've been paying attention.
>
> Thanks,
>
> jon
Thanks,
Mauro
^ permalink raw reply [flat|nested] 81+ messages in thread
* Re: [PATCH 10/57] docs: device-mapper: convert it to ReST format
2019-04-16 14:00 ` Jonathan Corbet
2019-04-16 14:33 ` Mauro Carvalho Chehab
@ 2019-04-16 15:48 ` Mike Snitzer
2019-04-16 17:27 ` Jonathan Corbet
2019-04-16 18:14 ` Mauro Carvalho Chehab
1 sibling, 2 replies; 81+ messages in thread
From: Mike Snitzer @ 2019-04-16 15:48 UTC (permalink / raw)
To: Jonathan Corbet
Cc: Mauro Carvalho Chehab, Linux Doc Mailing List,
Mauro Carvalho Chehab, linux-kernel, Alasdair Kergon, dm-devel
On Tue, Apr 16 2019 at 10:00am -0400,
Jonathan Corbet <corbet@lwn.net> wrote:
> On Tue, 16 Apr 2019 09:28:52 -0400
> Mike Snitzer <snitzer@redhat.com> wrote:
>
> > Can you help me understand why this is the direction text based
> > Documenation is taking in the Linux kernel? All I see is markup, and
> > escaping of characters, that is a chore to administer over time.
>
> This is a discussion that was mostly resolved some years ago...
>
> Classic Documentation/ is a jumbled collection of unorganized text files,
> some of which contain highly useful information and others of which
> haven't had much to offer since about 1996. We are working to turn it
> into an organized collection where, hopefully, some thought has actually
> been given to the people who will be reading it.
>
> The ReST conversion, in particular, allows us to link documents into a
> larger structure, create indexes and cross references, and produce output
> in formats like HTML and PDF. It lets us present the documentation like
> this:
>
> https://www.kernel.org/doc/html/latest/
>
> Among other things, making the documentation more accessible in this way
> makes it easier and more rewarding for developers to improve it, and I
> believe we are seeing the results of that. Linus called out the
> documentation work in the 5.1-rc1 announcement, for example.
>
> Nobody has complained about the maintenance burden of RST docs - so far as
> I have heard, anyway. Things do break occasionally, but problems in the
> docs build almost always result from code changes that mess up the
> kerneldoc comments rather than RST changes, and it's been that way for as
> long as I've been paying attention.
Thanks for the context. I clearly just haven't followed the evolution.
Certainly looks like a solid improvement.
Think the last piece I'm missing is: how does one edit a .rst document
without having to know to sprinkle syntactic sugar around? Does emacs
have a ReST mode? If not what client interface are people using to
properly change these documents?
(apologies if this is all spelled out nicely in Documentation/
somewhere, but please help this man learn to fish).
Thanks,
Mike
^ permalink raw reply [flat|nested] 81+ messages in thread
* Re: [PATCH 10/57] docs: device-mapper: convert it to ReST format
2019-04-16 15:48 ` Mike Snitzer
@ 2019-04-16 17:27 ` Jonathan Corbet
2019-04-16 18:14 ` Mauro Carvalho Chehab
1 sibling, 0 replies; 81+ messages in thread
From: Jonathan Corbet @ 2019-04-16 17:27 UTC (permalink / raw)
To: Mike Snitzer
Cc: Mauro Carvalho Chehab, Linux Doc Mailing List,
Mauro Carvalho Chehab, linux-kernel, Alasdair Kergon, dm-devel
On Tue, 16 Apr 2019 11:48:59 -0400
Mike Snitzer <snitzer@redhat.com> wrote:
> Think the last piece I'm missing is: how does one edit a .rst document
> without having to know to sprinkle syntactic sugar around? Does emacs
> have a ReST mode? If not what client interface are people using to
> properly change these documents?
There is an RST mode for Emacs, yes. But you likely don't really need
it. RST is a simple format and, in general, we try to keep the markup to
a minimum so that the plain-text files remain as readable as possible.
Most of our documents are 99% RST before anybody gets around to formally
converting them.
> (apologies if this is all spelled out nicely in Documentation/
> somewhere, but please help this man learn to fish).
Basics in Documentation/doc-guide (or
https://www.kernel.org/doc/html/latest/doc-guide/index.html). There's
also some history and overview in:
https://lwn.net/Articles/692704/
https://lwn.net/Articles/692705/
Thanks,
jon
^ permalink raw reply [flat|nested] 81+ messages in thread
* Re: [PATCH 10/57] docs: device-mapper: convert it to ReST format
2019-04-16 15:48 ` Mike Snitzer
2019-04-16 17:27 ` Jonathan Corbet
@ 2019-04-16 18:14 ` Mauro Carvalho Chehab
1 sibling, 0 replies; 81+ messages in thread
From: Mauro Carvalho Chehab @ 2019-04-16 18:14 UTC (permalink / raw)
To: Mike Snitzer
Cc: Jonathan Corbet, Linux Doc Mailing List, Mauro Carvalho Chehab,
linux-kernel, Alasdair Kergon, dm-devel
Em Tue, 16 Apr 2019 11:48:59 -0400
Mike Snitzer <snitzer@redhat.com> escreveu:
> On Tue, Apr 16 2019 at 10:00am -0400,
> Jonathan Corbet <corbet@lwn.net> wrote:
>
> > On Tue, 16 Apr 2019 09:28:52 -0400
> > Mike Snitzer <snitzer@redhat.com> wrote:
> >
> > > Can you help me understand why this is the direction text based
> > > Documenation is taking in the Linux kernel? All I see is markup, and
> > > escaping of characters, that is a chore to administer over time.
> >
> > This is a discussion that was mostly resolved some years ago...
> >
> > Classic Documentation/ is a jumbled collection of unorganized text files,
> > some of which contain highly useful information and others of which
> > haven't had much to offer since about 1996. We are working to turn it
> > into an organized collection where, hopefully, some thought has actually
> > been given to the people who will be reading it.
> >
> > The ReST conversion, in particular, allows us to link documents into a
> > larger structure, create indexes and cross references, and produce output
> > in formats like HTML and PDF. It lets us present the documentation like
> > this:
> >
> > https://www.kernel.org/doc/html/latest/
> >
> > Among other things, making the documentation more accessible in this way
> > makes it easier and more rewarding for developers to improve it, and I
> > believe we are seeing the results of that. Linus called out the
> > documentation work in the 5.1-rc1 announcement, for example.
> >
> > Nobody has complained about the maintenance burden of RST docs - so far as
> > I have heard, anyway. Things do break occasionally, but problems in the
> > docs build almost always result from code changes that mess up the
> > kerneldoc comments rather than RST changes, and it's been that way for as
> > long as I've been paying attention.
>
> Thanks for the context. I clearly just haven't followed the evolution.
> Certainly looks like a solid improvement.
>
> Think the last piece I'm missing is: how does one edit a .rst document
> without having to know to sprinkle syntactic sugar around? Does emacs
> have a ReST mode? If not what client interface are people using to
> properly change these documents?
I guess the main point is that, after writing a .rst file, run
"make htmldocs" and see how it fits :-)
As Jon mentioned, a large number of documents (even some written lots of
years ago) already fits into ReST, and keeping it simpler makes easier
for plain text file readers.
We do have some documents (like the media book), were we use a lot
of the markup stuff, as those documents came from DocBook and it is full of
cross-references, complex tables, images, examples, etc, but for most
subsystems, you're safe with the usual stuff.
>
> (apologies if this is all spelled out nicely in Documentation/
> somewhere, but please help this man learn to fish).
A few tips if you want to write documents that are easy to
read as text files and produce nice output after parsed:
1) it is written to document Python. So, it is indentation
sensitive. Usually most of the fixes are just to properly
indent things;
2) By default, it identifies line breaks with two \n. The
exceptions are literal blocks like:
::
foo
bar
and things like:
foo
bar
(in this case, it will bold **foo**)
Another trick that I use to avoid the need of adding an extra \n is to
convert itemized lists into a table, with:
===
foo
bar
===
3) Things like "struct *foo" usually produces error, as a single
* is interpreted as italic. The parser will look for another *. As
it won't find, it will produce an error. So, this need to be escaped
somehow.
While you can escape such special characters like * and _ with an
inverted bar, like "struct \*foo", that looks ugly for casual
text file readers.
Instead, I do either::
struct *foo
or, if I want it in the middle of a text, I use `struct *foo`.
IMO, placing it on a literal block (::) looks visually better for
both text and html modes.
Thanks,
Mauro
^ permalink raw reply [flat|nested] 81+ messages in thread
[parent not found: <5cfeb21a8841c1e029e8396bdaa7cd55ac0b08a2.1555382110.git.mchehab+samsung@kernel.org>]
* Re: [PATCH 18/57] docs: kbuild: convert it to ReST output
[not found] ` <5cfeb21a8841c1e029e8396bdaa7cd55ac0b08a2.1555382110.git.mchehab+samsung@kernel.org>
@ 2019-04-18 9:25 ` Masahiro Yamada
2019-04-18 10:26 ` Mauro Carvalho Chehab
0 siblings, 1 reply; 81+ messages in thread
From: Masahiro Yamada @ 2019-04-18 9:25 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: Linux Doc Mailing List, Mauro Carvalho Chehab,
Linux Kernel Mailing List, Jonathan Corbet, Michal Marek,
Linux Kbuild mailing list
On Tue, Apr 16, 2019 at 12:01 PM Mauro Carvalho Chehab
<mchehab+samsung@kernel.org> wrote:
>
> The kbuild documentation clearly shows that the documents
> there are written at different times: some use markdown,
> some use their own peculiar logic to split sections.
>
> Convert everything to ReST without affecting too much
> the author's style and avoiding adding uneeded markups.
Sorry for my ignorance, but shouldn't ReST use
the extension '.rst' instead of '.txt' ?
> Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
> ---
> Documentation/kbuild/headers_install.txt | 5 +-
> Documentation/kbuild/kbuild.txt | 119 ++--
> Documentation/kbuild/kconfig-language.txt | 232 ++++----
> .../kbuild/kconfig-macro-language.txt | 37 +-
> Documentation/kbuild/kconfig.txt | 136 +++--
> Documentation/kbuild/makefiles.txt | 518 +++++++++++-------
> Documentation/kbuild/modules.txt | 166 +++---
> 7 files changed, 720 insertions(+), 493 deletions(-)
>
--
Best Regards
Masahiro Yamada
^ permalink raw reply [flat|nested] 81+ messages in thread* Re: [PATCH 18/57] docs: kbuild: convert it to ReST output
2019-04-18 9:25 ` [PATCH 18/57] docs: kbuild: convert it to ReST output Masahiro Yamada
@ 2019-04-18 10:26 ` Mauro Carvalho Chehab
0 siblings, 0 replies; 81+ messages in thread
From: Mauro Carvalho Chehab @ 2019-04-18 10:26 UTC (permalink / raw)
To: Masahiro Yamada
Cc: Linux Doc Mailing List, Mauro Carvalho Chehab,
Linux Kernel Mailing List, Jonathan Corbet, Michal Marek,
Linux Kbuild mailing list
Em Thu, 18 Apr 2019 18:25:45 +0900
Masahiro Yamada <yamada.masahiro@socionext.com> escreveu:
> On Tue, Apr 16, 2019 at 12:01 PM Mauro Carvalho Chehab
> <mchehab+samsung@kernel.org> wrote:
> >
> > The kbuild documentation clearly shows that the documents
> > there are written at different times: some use markdown,
> > some use their own peculiar logic to split sections.
> >
> > Convert everything to ReST without affecting too much
> > the author's style and avoiding adding uneeded markups.
>
> Sorry for my ignorance, but shouldn't ReST use
> the extension '.rst' instead of '.txt' ?
Yes. I have a patch with the rename step, but the problem is that doing
such renames on 57 different subdirs and then adding all of them to the
existing index.rst files (in order to add into a bookset) would cause
huge merge conflicts - and keeping them renamed without adding into
an index would cause a *lot* new warnings when building them.
So, IMO, the best would be to have the fixup stuff merged first, and
then do the renames/merges at once, after subsystem maintainers
pick the patches from this rst fixup series.
If you want to see the renaming patch, it is at:
https://git.linuxtv.org/mchehab/experimental.git/commit/?h=all_with_indexes-v3&id=9cfeb3eb6d48d1aeff9d2ddd84880ab1dc782b00
(I'll probably split it later into per-subdir renames)
The results of this patch, plus the rename one, is at:
https://www.infradead.org/~mchehab/rst_conversion/kbuild/index.html
>
>
>
> > Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
> > ---
> > Documentation/kbuild/headers_install.txt | 5 +-
> > Documentation/kbuild/kbuild.txt | 119 ++--
> > Documentation/kbuild/kconfig-language.txt | 232 ++++----
> > .../kbuild/kconfig-macro-language.txt | 37 +-
> > Documentation/kbuild/kconfig.txt | 136 +++--
> > Documentation/kbuild/makefiles.txt | 518 +++++++++++-------
> > Documentation/kbuild/modules.txt | 166 +++---
> > 7 files changed, 720 insertions(+), 493 deletions(-)
> >
>
Thanks,
Mauro
^ permalink raw reply [flat|nested] 81+ messages in thread
* Avoiding merge conflicts while adding new docs - Was: Re: [PATCH 00/57] Convert files to ReST
2019-04-16 2:55 [PATCH 00/57] Convert files to ReST Mauro Carvalho Chehab
` (50 preceding siblings ...)
[not found] ` <5cfeb21a8841c1e029e8396bdaa7cd55ac0b08a2.1555382110.git.mchehab+samsung@kernel.org>
@ 2019-04-18 12:42 ` Mauro Carvalho Chehab
2019-04-19 22:10 ` Jonathan Corbet
[not found] ` <CGME20190416025636epcas4p2b3bd395b2673bffb3cc0cbdd211aa841@epcas4p2.samsung.com>
52 siblings, 1 reply; 81+ messages in thread
From: Mauro Carvalho Chehab @ 2019-04-18 12:42 UTC (permalink / raw)
To: Jonathan Corbet
Cc: Linux Doc Mailing List, Mauro Carvalho Chehab, linux-kernel,
linux-riscv, linux-fbdev, linux-s390, Greg Kroah-Hartman,
linux-watchdog, xdp-newbies, linux-samsung-soc, linux-acpi,
linux-stm32, bpf, linux-ide, linux-pm, dri-devel, linux-scsi,
linux-gpio, linuxppc-dev, x86, dm-devel, target-devel, netdev,
kexec, linux-fpga, linux-rdma, linux-kbuild, Thomas Gleixner,
linux-security-module, linux-usb, linux-arm-kernel
Jon,
Em Mon, 15 Apr 2019 23:55:25 -0300
Mauro Carvalho Chehab <mchehab+samsung@kernel.org> escreveu:
> I have a separate patch series with do the actual rename and
> adjustment of references. I opted to submit this first, as it
> sounds easier to merge this way, as each subsystem maintainer
> can apply the conversion directly on their trees (or at docs
> tree), avoiding merge conflects.
Based on the number of feedbacks we have about this, I'm
considering to submit a second version of my conversion patch
series that would be doing the rename together with each patch,
adding the rst files to an index file.
However, doing that would produce lots of warnings. We have
already lots of those at linux-next:
checking consistency...
docs/Documentation/accelerators/ocxl.rst: WARNING: document isn't included in any toctree
docs/Documentation/admin-guide/mm/numaperf.rst: WARNING: document isn't included in any toctree
docs/Documentation/filesystems/ext4/allocators.rst: WARNING: document isn't included in any toctree
docs/Documentation/filesystems/ext4/attributes.rst: WARNING: document isn't included in any toctree
docs/Documentation/filesystems/ext4/bigalloc.rst: WARNING: document isn't included in any toctree
docs/Documentation/filesystems/ext4/bitmaps.rst: WARNING: document isn't included in any toctree
docs/Documentation/filesystems/ext4/blockgroup.rst: WARNING: document isn't included in any toctree
docs/Documentation/filesystems/ext4/blocks.rst: WARNING: document isn't included in any toctree
docs/Documentation/filesystems/ext4/checksums.rst: WARNING: document isn't included in any toctree
docs/Documentation/filesystems/ext4/directory.rst: WARNING: document isn't included in any toctree
docs/Documentation/filesystems/ext4/eainode.rst: WARNING: document isn't included in any toctree
docs/Documentation/filesystems/ext4/group_descr.rst: WARNING: document isn't included in any toctree
docs/Documentation/filesystems/ext4/ifork.rst: WARNING: document isn't included in any toctree
docs/Documentation/filesystems/ext4/inlinedata.rst: WARNING: document isn't included in any toctree
docs/Documentation/filesystems/ext4/inodes.rst: WARNING: document isn't included in any toctree
docs/Documentation/filesystems/ext4/journal.rst: WARNING: document isn't included in any toctree
docs/Documentation/filesystems/ext4/mmp.rst: WARNING: document isn't included in any toctree
docs/Documentation/filesystems/ext4/special_inodes.rst: WARNING: document isn't included in any toctree
docs/Documentation/filesystems/ext4/super.rst: WARNING: document isn't included in any toctree
docs/Documentation/fmc/index.rst: WARNING: document isn't included in any toctree
docs/Documentation/gpu/msm-crash-dump.rst: WARNING: document isn't included in any toctree
docs/Documentation/interconnect/interconnect.rst: WARNING: document isn't included in any toctree
docs/Documentation/laptops/lg-laptop.rst: WARNING: document isn't included in any toctree
docs/Documentation/virtual/kvm/amd-memory-encryption.rst: WARNING: document isn't included in any toctree
docs/Documentation/virtual/kvm/vcpu-requests.rst: WARNING: document isn't included in any toctree
After thinking a little bit and doing some tests, I think a good solution
would be to add ":orphan:" markup to the new .rst files that were not
added yet into the main body (e. g. something like the enclosed example).
That will make Sphinx suppress the:
"WARNING: document isn't included in any toctree"
warning for the new files, while they're not included at the main indexes.
This way, maintainers can do all the hard work of doing/applying the ReST
file conversion/addition patch series on their own trees, and, once
everything gets merged, submit a patch against the latest docs-next
tree, removing the :orphan: tag and add them to the common index.rst
files.
That should largely avoid merging conflicts.
For example, assuming that someone converts the stuff at
Documentation/accounting and rename the text files there to
RST (I'm actually doing that), he could add the enclosed change on
the top of its index file:
diff --git a/Documentation/accounting/index.rst b/Documentation/accounting/index.rst
index e7dda5afa73f..e1f6284b5ff3 100644
--- a/Documentation/accounting/index.rst
+++ b/Documentation/accounting/index.rst
@@ -1,3 +1,5 @@
+:orphan:
+
==========
Accounting
==========
With would make Sphinx to ignore the subdir index file while
reporting errors. It will still build the documentation, allowing
the developer to test the changes.
One of the advantages is that checking the orphaned docs is as
easy as running:
$ git grep -l ":orphan:" Documentation/
...
Documentation/accounting/index.rst
...
Making easy for people to check the orphaned files and send a fixup
patch if something got orphaned after the merge window and send a
fixes patches to be applied upstream.
What do you think?
Regards,
Mauro
^ permalink raw reply [flat|nested] 81+ messages in thread* Re: Avoiding merge conflicts while adding new docs - Was: Re: [PATCH 00/57] Convert files to ReST
2019-04-18 12:42 ` Avoiding merge conflicts while adding new docs - Was: Re: [PATCH 00/57] Convert files to ReST Mauro Carvalho Chehab
@ 2019-04-19 22:10 ` Jonathan Corbet
0 siblings, 0 replies; 81+ messages in thread
From: Jonathan Corbet @ 2019-04-19 22:10 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: Linux Doc Mailing List, Mauro Carvalho Chehab, linux-kernel,
linux-riscv, linux-fbdev, linux-s390, Greg Kroah-Hartman,
linux-watchdog, xdp-newbies, linux-samsung-soc, linux-acpi,
linux-stm32, bpf, linux-ide, linux-pm, dri-devel, linux-scsi,
linux-gpio, linuxppc-dev, x86, dm-devel, target-devel, netdev,
kexec, linux-fpga, linux-rdma, linux-kbuild, Thomas Gleixner,
linux-security-module, linux-usb, linux-arm-kernel
On Thu, 18 Apr 2019 09:42:23 -0300
Mauro Carvalho Chehab <mchehab+samsung@kernel.org> wrote:
> After thinking a little bit and doing some tests, I think a good solution
> would be to add ":orphan:" markup to the new .rst files that were not
> added yet into the main body (e. g. something like the enclosed example).
Interesting...I didn't know about that. Yes, I think it makes sense to
put that in...
jon
^ permalink raw reply [flat|nested] 81+ messages in thread
[parent not found: <CGME20190416025636epcas4p2b3bd395b2673bffb3cc0cbdd211aa841@epcas4p2.samsung.com>]