Merge tag 'for-5.4-rc1-tag' of git://git.kernel.org/pub/scm/linux/kernel/git/kdave/linux
Pull btrfs fixes from David Sterba:
"A bunch of fixes that accumulated in recent weeks, mostly material for
stable.
Summary:
- fix for regression from 5.3 that prevents to use balance convert
with single profile
- qgroup fixes: rescan race, accounting leak with multiple writers,
potential leak after io failure recovery
- fix for use after free in relocation (reported by KASAN)
- other error handling fixups"
* tag 'for-5.4-rc1-tag' of git://git.kernel.org/pub/scm/linux/kernel/git/kdave/linux:
btrfs: qgroup: Fix reserved data space leak if we have multiple reserve calls
btrfs: qgroup: Fix the wrong target io_tree when freeing reserved data space
btrfs: Fix a regression which we can't convert to SINGLE profile
btrfs: relocation: fix use-after-free on dead relocation roots
Btrfs: fix race setting up and completing qgroup rescan workers
Btrfs: fix missing error return if writeback for extent buffer never started
btrfs: adjust dirty_metadata_bytes after writeback failure of extent buffer
Btrfs: fix selftests failure due to uninitialized i_mode in test inodes
diff --git a/.gitignore b/.gitignore
index 2030c7a..70580bd 100644
--- a/.gitignore
+++ b/.gitignore
@@ -32,9 +32,9 @@
*.lzo
*.mod
*.mod.c
+*.ns_deps
*.o
*.o.*
-*.order
*.patch
*.s
*.so
@@ -46,6 +46,7 @@
*.xz
Module.symvers
modules.builtin
+modules.order
#
# Top-level generic files
diff --git a/.mailmap b/.mailmap
index afaad60..edcac87 100644
--- a/.mailmap
+++ b/.mailmap
@@ -47,6 +47,8 @@
Boris Brezillon <bbrezillon@kernel.org> <b.brezillon@overkiz.com>
Brian Avery <b.avery@hp.com>
Brian King <brking@us.ibm.com>
+Chao Yu <chao@kernel.org> <chao2.yu@samsung.com>
+Chao Yu <chao@kernel.org> <yuchao0@huawei.com>
Christoph Hellwig <hch@lst.de>
Christophe Ricard <christophe.ricard@gmail.com>
Corey Minyard <minyard@acm.org>
@@ -63,6 +65,7 @@
Dengcheng Zhu <dzhu@wavecomp.com> <dengcheng.zhu@imgtec.com>
Dengcheng Zhu <dzhu@wavecomp.com> <dczhu@mips.com>
Dengcheng Zhu <dzhu@wavecomp.com> <dengcheng.zhu@gmail.com>
+<dev.kurt@vandijck-laurijssen.be> <kurt.van.dijck@eia.be>
Dmitry Eremin-Solenikov <dbaryshkov@gmail.com>
Dmitry Safonov <0x7f454c46@gmail.com> <dsafonov@virtuozzo.com>
Dmitry Safonov <0x7f454c46@gmail.com> <d.safonov@partner.samsung.com>
@@ -80,6 +83,8 @@
Frank Rowand <frowand.list@gmail.com> <frank.rowand@am.sony.com>
Frank Rowand <frowand.list@gmail.com> <frank.rowand@sonymobile.com>
Frank Zago <fzago@systemfabricworks.com>
+Gao Xiang <xiang@kernel.org> <gaoxiang25@huawei.com>
+Gao Xiang <xiang@kernel.org> <hsiangkao@aol.com>
Greg Kroah-Hartman <greg@echidna.(none)>
Greg Kroah-Hartman <gregkh@suse.de>
Greg Kroah-Hartman <greg@kroah.com>
@@ -90,6 +95,9 @@
Henrik Rydberg <rydberg@bitmath.org>
Herbert Xu <herbert@gondor.apana.org.au>
Jacob Shin <Jacob.Shin@amd.com>
+Jaegeuk Kim <jaegeuk@kernel.org> <jaegeuk@google.com>
+Jaegeuk Kim <jaegeuk@kernel.org> <jaegeuk@motorola.com>
+Jaegeuk Kim <jaegeuk@kernel.org> <jaegeuk.kim@samsung.com>
James Bottomley <jejb@mulgrave.(none)>
James Bottomley <jejb@titanic.il.steeleye.com>
James E Wilson <wilson@specifix.com>
@@ -178,8 +186,14 @@
Morten Welinder <welinder@troll.com>
Mythri P K <mythripk@ti.com>
Nguyen Anh Quynh <aquynh@gmail.com>
+Nicolas Ferre <nicolas.ferre@microchip.com> <nicolas.ferre@atmel.com>
Nicolas Pitre <nico@fluxnic.net> <nicolas.pitre@linaro.org>
Nicolas Pitre <nico@fluxnic.net> <nico@linaro.org>
+Oleksij Rempel <linux@rempel-privat.de> <bug-track@fisher-privat.net>
+Oleksij Rempel <linux@rempel-privat.de> <external.Oleksij.Rempel@de.bosch.com>
+Oleksij Rempel <linux@rempel-privat.de> <fixed-term.Oleksij.Rempel@de.bosch.com>
+Oleksij Rempel <linux@rempel-privat.de> <o.rempel@pengutronix.de>
+Oleksij Rempel <linux@rempel-privat.de> <ore@pengutronix.de>
Paolo 'Blaisorblade' Giarrusso <blaisorblade@yahoo.it>
Patrick Mochel <mochel@digitalimplant.org>
Paul Burton <paul.burton@mips.com> <paul.burton@imgtec.com>
@@ -190,11 +204,7 @@
Praveen BP <praveenbp@ti.com>
Punit Agrawal <punitagrawal@gmail.com> <punit.agrawal@arm.com>
Qais Yousef <qsyousef@gmail.com> <qais.yousef@imgtec.com>
-Oleksij Rempel <linux@rempel-privat.de> <bug-track@fisher-privat.net>
-Oleksij Rempel <linux@rempel-privat.de> <external.Oleksij.Rempel@de.bosch.com>
-Oleksij Rempel <linux@rempel-privat.de> <fixed-term.Oleksij.Rempel@de.bosch.com>
-Oleksij Rempel <linux@rempel-privat.de> <o.rempel@pengutronix.de>
-Oleksij Rempel <linux@rempel-privat.de> <ore@pengutronix.de>
+Quentin Perret <qperret@qperret.net> <quentin.perret@arm.com>
Rajesh Shah <rajesh.shah@intel.com>
Ralf Baechle <ralf@linux-mips.org>
Ralf Wildenhues <Ralf.Wildenhues@gmx.de>
@@ -229,6 +239,7 @@
Tejun Heo <htejun@gmail.com>
Thomas Graf <tgraf@suug.ch>
Thomas Pedersen <twp@codeaurora.org>
+Todor Tomov <todor.too@gmail.com> <todor.tomov@linaro.org>
Tony Luck <tony.luck@intel.com>
TripleX Chung <xxx.phy@gmail.com> <zhongyu@18mail.cn>
TripleX Chung <xxx.phy@gmail.com> <triplex@zh-kernel.org>
diff --git a/CREDITS b/CREDITS
index a738760..8b67a85 100644
--- a/CREDITS
+++ b/CREDITS
@@ -751,7 +751,7 @@
S: USA
N: Luis Correia
-E: lfcorreia@users.sf.net
+E: luisfcorreia@gmail.com
D: Ralink rt2x00 WLAN driver
S: Belas, Portugal
diff --git a/Documentation/ABI/stable/sysfs-bus-w1 b/Documentation/ABI/stable/sysfs-bus-w1
index 140d85b..992dfb1 100644
--- a/Documentation/ABI/stable/sysfs-bus-w1
+++ b/Documentation/ABI/stable/sysfs-bus-w1
@@ -6,6 +6,6 @@
control systems are attached/generate presence for as short as
100 ms - hence the tens-to-hundreds milliseconds scan intervals
are required.
- see Documentation/w1/w1.generic for detailed information.
+ see Documentation/w1/w1-generic.rst for detailed information.
Users: any user space application which wants to know bus scanning
interval
diff --git a/Documentation/ABI/stable/sysfs-driver-w1_ds28e04 b/Documentation/ABI/stable/sysfs-driver-w1_ds28e04
index 26579ee..3e1c1fa 100644
--- a/Documentation/ABI/stable/sysfs-driver-w1_ds28e04
+++ b/Documentation/ABI/stable/sysfs-driver-w1_ds28e04
@@ -2,7 +2,7 @@
Date: May 2012
Contact: Markus Franke <franm@hrz.tu-chemnitz.de>
Description: read/write the contents of the two PIO's of the DS28E04-100
- see Documentation/w1/slaves/w1_ds28e04 for detailed information
+ see Documentation/w1/slaves/w1_ds28e04.rst for detailed information
Users: any user space application which wants to communicate with DS28E04-100
@@ -11,5 +11,5 @@
Date: May 2012
Contact: Markus Franke <franm@hrz.tu-chemnitz.de>
Description: read/write the contents of the EEPROM memory of the DS28E04-100
- see Documentation/w1/slaves/w1_ds28e04 for detailed information
+ see Documentation/w1/slaves/w1_ds28e04.rst for detailed information
Users: any user space application which wants to communicate with DS28E04-100
diff --git a/Documentation/ABI/stable/sysfs-driver-w1_ds28ea00 b/Documentation/ABI/stable/sysfs-driver-w1_ds28ea00
index e928def..534e637 100644
--- a/Documentation/ABI/stable/sysfs-driver-w1_ds28ea00
+++ b/Documentation/ABI/stable/sysfs-driver-w1_ds28ea00
@@ -2,5 +2,5 @@
Date: Apr 2015
Contact: Matt Campbell <mattrcampbell@gmail.com>
Description: Support for the DS28EA00 chain sequence function
- see Documentation/w1/slaves/w1_therm for detailed information
+ see Documentation/w1/slaves/w1_therm.rst for detailed information
Users: any user space application which wants to communicate with DS28EA00
diff --git a/Documentation/ABI/testing/debugfs-hisi-zip b/Documentation/ABI/testing/debugfs-hisi-zip
new file mode 100644
index 0000000..a7c63e6
--- /dev/null
+++ b/Documentation/ABI/testing/debugfs-hisi-zip
@@ -0,0 +1,50 @@
+What: /sys/kernel/debug/hisi_zip/<bdf>/comp_core[01]/regs
+Date: Nov 2018
+Contact: linux-crypto@vger.kernel.org
+Description: Dump of compression cores related debug registers.
+ Only available for PF.
+
+What: /sys/kernel/debug/hisi_zip/<bdf>/decomp_core[0-5]/regs
+Date: Nov 2018
+Contact: linux-crypto@vger.kernel.org
+Description: Dump of decompression cores related debug registers.
+ Only available for PF.
+
+What: /sys/kernel/debug/hisi_zip/<bdf>/clear_enable
+Date: Nov 2018
+Contact: linux-crypto@vger.kernel.org
+Description: Compression/decompression core debug registers read clear
+ control. 1 means enable register read clear, otherwise 0.
+ Writing to this file has no functional effect, only enable or
+ disable counters clear after reading of these registers.
+ Only available for PF.
+
+What: /sys/kernel/debug/hisi_zip/<bdf>/current_qm
+Date: Nov 2018
+Contact: linux-crypto@vger.kernel.org
+Description: One ZIP controller has one PF and multiple VFs, each function
+ has a QM. Select the QM which below qm refers to.
+ Only available for PF.
+
+What: /sys/kernel/debug/hisi_zip/<bdf>/qm/qm_regs
+Date: Nov 2018
+Contact: linux-crypto@vger.kernel.org
+Description: Dump of QM related debug registers.
+ Available for PF and VF in host. VF in guest currently only
+ has one debug register.
+
+What: /sys/kernel/debug/hisi_zip/<bdf>/qm/current_q
+Date: Nov 2018
+Contact: linux-crypto@vger.kernel.org
+Description: One QM may contain multiple queues. Select specific queue to
+ show its debug registers in above qm_regs.
+ Only available for PF.
+
+What: /sys/kernel/debug/hisi_zip/<bdf>/qm/clear_enable
+Date: Nov 2018
+Contact: linux-crypto@vger.kernel.org
+Description: QM debug registers(qm_regs) read clear control. 1 means enable
+ register read clear, otherwise 0.
+ Writing to this file has no functional effect, only enable or
+ disable counters clear after reading of these registers.
+ Only available for PF.
diff --git a/Documentation/ABI/testing/debugfs-moxtet b/Documentation/ABI/testing/debugfs-moxtet
new file mode 100644
index 0000000..67b1717
--- /dev/null
+++ b/Documentation/ABI/testing/debugfs-moxtet
@@ -0,0 +1,23 @@
+What: /sys/kernel/debug/moxtet/input
+Date: March 2019
+KernelVersion: 5.3
+Contact: Marek Behún <marek.behun@nic.cz>
+Description: (R) Read input from the shift registers, in hexadecimal.
+ Returns N+1 bytes, where N is the number of Moxtet connected
+ modules. The first byte is from the CPU board itself.
+ Example: 101214
+ 10: CPU board with SD card
+ 12: 2 = PCIe module, 1 = IRQ not active
+ 14: 4 = Peridot module, 1 = IRQ not active
+
+What: /sys/kernel/debug/moxtet/output
+Date: March 2019
+KernelVersion: 5.3
+Contact: Marek Behún <marek.behun@nic.cz>
+Description: (RW) Read last written value to the shift registers, in
+ hexadecimal, or write values to the shift registers, also
+ in hexadecimal.
+ Example: 0102
+ 01: 01 was last written, or is to be written, to the
+ first module's shift register
+ 02: the same for second module
diff --git a/Documentation/ABI/testing/dev-kmsg b/Documentation/ABI/testing/dev-kmsg
index fff817e..f307506e 100644
--- a/Documentation/ABI/testing/dev-kmsg
+++ b/Documentation/ABI/testing/dev-kmsg
@@ -12,7 +12,7 @@
The logged line can be prefixed with a <N> syslog prefix, which
carries the syslog priority and facility. The single decimal
prefix number is composed of the 3 lowest bits being the syslog
- priority and the higher bits the syslog facility number.
+ priority and the next 8 bits the syslog facility number.
If no prefix is given, the priority number is the default kernel
log priority and the facility number is set to LOG_USER (1). It
@@ -90,13 +90,12 @@
+sound:card0 - subsystem:devname
The flags field carries '-' by default. A 'c' indicates a
- fragment of a line. All following fragments are flagged with
- '+'. Note, that these hints about continuation lines are not
- necessarily correct, and the stream could be interleaved with
- unrelated messages, but merging the lines in the output
- usually produces better human readable results. A similar
- logic is used internally when messages are printed to the
- console, /proc/kmsg or the syslog() syscall.
+ fragment of a line. Note, that these hints about continuation
+ lines are not necessarily correct, and the stream could be
+ interleaved with unrelated messages, but merging the lines in
+ the output usually produces better human readable results. A
+ similar logic is used internally when messages are printed to
+ the console, /proc/kmsg or the syslog() syscall.
By default, kernel tries to avoid fragments by concatenating
when it can and fragments are rare; however, when extended
diff --git a/Documentation/ABI/testing/ima_policy b/Documentation/ABI/testing/ima_policy
index fc376a3..29ebe9a 100644
--- a/Documentation/ABI/testing/ima_policy
+++ b/Documentation/ABI/testing/ima_policy
@@ -37,7 +37,7 @@
euid:= decimal value
fowner:= decimal value
lsm: are LSM specific
- option: appraise_type:= [imasig]
+ option: appraise_type:= [imasig] [imasig|modsig]
template:= name of a defined IMA template type
(eg, ima-ng). Only valid when action is "measure".
pcr:= decimal value
@@ -105,3 +105,7 @@
measure func=KEXEC_KERNEL_CHECK pcr=4
measure func=KEXEC_INITRAMFS_CHECK pcr=5
+
+ Example of appraise rule allowing modsig appended signatures:
+
+ appraise func=KEXEC_KERNEL_CHECK appraise_type=imasig|modsig
diff --git a/Documentation/ABI/testing/sysfs-bus-iio-dfsdm-adc-stm32 b/Documentation/ABI/testing/sysfs-bus-iio-dfsdm-adc-stm32
index da98223..0e66ae9 100644
--- a/Documentation/ABI/testing/sysfs-bus-iio-dfsdm-adc-stm32
+++ b/Documentation/ABI/testing/sysfs-bus-iio-dfsdm-adc-stm32
@@ -13,4 +13,4 @@
error on writing
If DFSDM input is SPI Slave:
Reading returns value previously set.
- Writing value before starting conversions.
\ No newline at end of file
+ Writing value before starting conversions.
diff --git a/Documentation/ABI/testing/sysfs-bus-iio-timer-stm32 b/Documentation/ABI/testing/sysfs-bus-iio-timer-stm32
index 161c147..b725923 100644
--- a/Documentation/ABI/testing/sysfs-bus-iio-timer-stm32
+++ b/Documentation/ABI/testing/sysfs-bus-iio-timer-stm32
@@ -91,29 +91,6 @@
When counting down the counter start from preset value
and fire event when reach 0.
-What: /sys/bus/iio/devices/iio:deviceX/in_count_quadrature_mode_available
-KernelVersion: 4.12
-Contact: benjamin.gaignard@st.com
-Description:
- Reading returns the list possible quadrature modes.
-
-What: /sys/bus/iio/devices/iio:deviceX/in_count0_quadrature_mode
-KernelVersion: 4.12
-Contact: benjamin.gaignard@st.com
-Description:
- Configure the device counter quadrature modes:
- channel_A:
- Encoder A input servers as the count input and B as
- the UP/DOWN direction control input.
-
- channel_B:
- Encoder B input serves as the count input and A as
- the UP/DOWN direction control input.
-
- quadrature:
- Encoder A and B inputs are mixed to get direction
- and count with a scale of 0.25.
-
What: /sys/bus/iio/devices/iio:deviceX/in_count_enable_mode_available
KernelVersion: 4.12
Contact: benjamin.gaignard@st.com
diff --git a/Documentation/ABI/testing/sysfs-bus-intel_th-devices-msc b/Documentation/ABI/testing/sysfs-bus-intel_th-devices-msc
index f54ae24..456cb62 100644
--- a/Documentation/ABI/testing/sysfs-bus-intel_th-devices-msc
+++ b/Documentation/ABI/testing/sysfs-bus-intel_th-devices-msc
@@ -12,7 +12,8 @@
- "single", for contiguous buffer mode (high-order alloc);
- "multi", for multiblock mode;
- "ExI", for DCI handler mode;
- - "debug", for debug mode.
+ - "debug", for debug mode;
+ - any of the currently loaded buffer sinks.
If operating mode changes, existing buffer is deallocated,
provided there are no active users and tracing is not enabled,
otherwise the write will fail.
diff --git a/Documentation/ABI/testing/sysfs-bus-moxtet-devices b/Documentation/ABI/testing/sysfs-bus-moxtet-devices
new file mode 100644
index 0000000..3559585
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-bus-moxtet-devices
@@ -0,0 +1,17 @@
+What: /sys/bus/moxtet/devices/moxtet-<name>.<addr>/module_description
+Date: March 2019
+KernelVersion: 5.3
+Contact: Marek Behún <marek.behun@nic.cz>
+Description: (R) Moxtet module description. Format: string
+
+What: /sys/bus/moxtet/devices/moxtet-<name>.<addr>/module_id
+Date: March 2019
+KernelVersion: 5.3
+Contact: Marek Behún <marek.behun@nic.cz>
+Description: (R) Moxtet module ID. Format: %x
+
+What: /sys/bus/moxtet/devices/moxtet-<name>.<addr>/module_name
+Date: March 2019
+KernelVersion: 5.3
+Contact: Marek Behún <marek.behun@nic.cz>
+Description: (R) Moxtet module name. Format: string
diff --git a/Documentation/ABI/testing/sysfs-class-backlight b/Documentation/ABI/testing/sysfs-class-backlight
new file mode 100644
index 0000000..3ab175a
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-class-backlight
@@ -0,0 +1,26 @@
+What: /sys/class/backlight/<backlight>/scale
+Date: July 2019
+KernelVersion: 5.4
+Contact: Daniel Thompson <daniel.thompson@linaro.org>
+Description:
+ Description of the scale of the brightness curve.
+
+ The human eye senses brightness approximately logarithmically,
+ hence linear changes in brightness are perceived as being
+ non-linear. To achieve a linear perception of brightness changes
+ controls like sliders need to apply a logarithmic mapping for
+ backlights with a linear brightness curve.
+
+ Possible values of the attribute are:
+
+ unknown
+ The scale of the brightness curve is unknown.
+
+ linear
+ The brightness changes linearly with each step. Brightness
+ controls should apply a logarithmic mapping for a linear
+ perception.
+
+ non-linear
+ The brightness changes non-linearly with each step. Brightness
+ controls should use a linear mapping for a linear perception.
diff --git a/Documentation/ABI/testing/sysfs-class-mic.txt b/Documentation/ABI/testing/sysfs-class-mic
similarity index 100%
rename from Documentation/ABI/testing/sysfs-class-mic.txt
rename to Documentation/ABI/testing/sysfs-class-mic
diff --git a/Documentation/ABI/testing/sysfs-class-remoteproc b/Documentation/ABI/testing/sysfs-class-remoteproc
index c3afe9f..36094fb 100644
--- a/Documentation/ABI/testing/sysfs-class-remoteproc
+++ b/Documentation/ABI/testing/sysfs-class-remoteproc
@@ -48,3 +48,13 @@
Writing "stop" will attempt to halt the remote processor and
return it to the "offline" state.
+
+What: /sys/class/remoteproc/.../name
+Date: August 2019
+KernelVersion: 5.4
+Contact: Suman Anna <s-anna@ti.com>
+Description: Remote processor name
+
+ Reports the name of the remote processor. This can be used by
+ userspace in exactly identifying a remote processor and ease
+ up the usage in modifying the 'firmware' or 'state' files.
diff --git a/Documentation/ABI/testing/sysfs-class-wakeup b/Documentation/ABI/testing/sysfs-class-wakeup
new file mode 100644
index 0000000..754aab8
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-class-wakeup
@@ -0,0 +1,76 @@
+What: /sys/class/wakeup/
+Date: June 2019
+Contact: Tri Vo <trong@android.com>
+Description:
+ The /sys/class/wakeup/ directory contains pointers to all
+ wakeup sources in the kernel at that moment in time.
+
+What: /sys/class/wakeup/.../name
+Date: June 2019
+Contact: Tri Vo <trong@android.com>
+Description:
+ This file contains the name of the wakeup source.
+
+What: /sys/class/wakeup/.../active_count
+Date: June 2019
+Contact: Tri Vo <trong@android.com>
+Description:
+ This file contains the number of times the wakeup source was
+ activated.
+
+What: /sys/class/wakeup/.../event_count
+Date: June 2019
+Contact: Tri Vo <trong@android.com>
+Description:
+ This file contains the number of signaled wakeup events
+ associated with the wakeup source.
+
+What: /sys/class/wakeup/.../wakeup_count
+Date: June 2019
+Contact: Tri Vo <trong@android.com>
+Description:
+ This file contains the number of times the wakeup source might
+ abort suspend.
+
+What: /sys/class/wakeup/.../expire_count
+Date: June 2019
+Contact: Tri Vo <trong@android.com>
+Description:
+ This file contains the number of times the wakeup source's
+ timeout has expired.
+
+What: /sys/class/wakeup/.../active_time_ms
+Date: June 2019
+Contact: Tri Vo <trong@android.com>
+Description:
+ This file contains the amount of time the wakeup source has
+ been continuously active, in milliseconds. If the wakeup
+ source is not active, this file contains '0'.
+
+What: /sys/class/wakeup/.../total_time_ms
+Date: June 2019
+Contact: Tri Vo <trong@android.com>
+Description:
+ This file contains the total amount of time this wakeup source
+ has been active, in milliseconds.
+
+What: /sys/class/wakeup/.../max_time_ms
+Date: June 2019
+Contact: Tri Vo <trong@android.com>
+Description:
+ This file contains the maximum amount of time this wakeup
+ source has been continuously active, in milliseconds.
+
+What: /sys/class/wakeup/.../last_change_ms
+Date: June 2019
+Contact: Tri Vo <trong@android.com>
+Description:
+ This file contains the monotonic clock time when the wakeup
+ source was touched last time, in milliseconds.
+
+What: /sys/class/wakeup/.../prevent_suspend_time_ms
+Date: June 2019
+Contact: Tri Vo <trong@android.com>
+Description:
+ The file contains the total amount of time this wakeup source
+ has been preventing autosleep, in milliseconds.
diff --git a/Documentation/ABI/testing/sysfs-class-watchdog b/Documentation/ABI/testing/sysfs-class-watchdog
index 6317ade..675f9b5 100644
--- a/Documentation/ABI/testing/sysfs-class-watchdog
+++ b/Documentation/ABI/testing/sysfs-class-watchdog
@@ -72,3 +72,37 @@
It is a read/write file. When read, the currently assigned
pretimeout governor is returned. When written, it sets
the pretimeout governor.
+
+What: /sys/class/watchdog/watchdog1/access_cs0
+Date: August 2019
+Contact: Ivan Mikhaylov <i.mikhaylov@yadro.com>,
+ Alexander Amelkin <a.amelkin@yadro.com>
+Description:
+ It is a read/write file. This attribute exists only if the
+ system has booted from the alternate flash chip due to
+ expiration of a watchdog timer of AST2400/AST2500 when
+ alternate boot function was enabled with 'aspeed,alt-boot'
+ devicetree option for that watchdog or with an appropriate
+ h/w strapping (for WDT2 only).
+
+ At alternate flash the 'access_cs0' sysfs node provides:
+ ast2400: a way to get access to the primary SPI flash
+ chip at CS0 after booting from the alternate
+ chip at CS1.
+ ast2500: a way to restore the normal address mapping
+ from (CS0->CS1, CS1->CS0) to (CS0->CS0,
+ CS1->CS1).
+
+ Clearing the boot code selection and timeout counter also
+ resets to the initial state the chip select line mapping. When
+ the SoC is in normal mapping state (i.e. booted from CS0),
+ clearing those bits does nothing for both versions of the SoC.
+ For alternate boot mode (booted from CS1 due to wdt2
+ expiration) the behavior differs as described above.
+
+ This option can be used with wdt2 (watchdog1) only.
+
+ When read, the current status of the boot code selection is
+ shown. When written with any non-zero value, it clears
+ the boot code selection and the timeout counter, which results
+ in chipselect reset for AST2400/AST2500.
diff --git a/Documentation/ABI/testing/sysfs-devices-platform-stratix10-rsu b/Documentation/ABI/testing/sysfs-devices-platform-stratix10-rsu
new file mode 100644
index 0000000..ae9af98
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-devices-platform-stratix10-rsu
@@ -0,0 +1,128 @@
+ Intel Stratix10 Remote System Update (RSU) device attributes
+
+What: /sys/devices/platform/stratix10-rsu.0/current_image
+Date: August 2019
+KernelVersion: 5.4
+Contact: Richard Gong <richard.gong@linux.intel.com>
+Description:
+ (RO) the address in flash of currently running image.
+
+What: /sys/devices/platform/stratix10-rsu.0/fail_image
+Date: August 2019
+KernelVersion: 5.4
+Contact: Richard Gong <richard.gong@linux.intel.com>
+Description:
+ (RO) the address in flash of failed image.
+
+What: /sys/devices/platform/stratix10-rsu.0/state
+Date: August 2019
+KernelVersion: 5.4
+Contact: Richard Gong <richard.gong@linux.intel.com>
+Description:
+ (RO) the state of RSU system.
+ The state field has two parts: major error code in
+ upper 16 bits and minor error code in lower 16 bits.
+
+ b[15:0]
+ Currently used only when major error is 0xF006
+ (CPU watchdog timeout), in which case the minor
+ error code is the value reported by CPU to
+ firmware through the RSU notify command before
+ the watchdog timeout occurs.
+
+ b[31:16]
+ 0xF001 bitstream error
+ 0xF002 hardware access failure
+ 0xF003 bitstream corruption
+ 0xF004 internal error
+ 0xF005 device error
+ 0xF006 CPU watchdog timeout
+ 0xF007 internal unknown error
+
+What: /sys/devices/platform/stratix10-rsu.0/version
+Date: August 2019
+KernelVersion: 5.4
+Contact: Richard Gong <richard.gong@linux.intel.com>
+Description:
+ (RO) the version number of RSU firmware. 19.3 or late
+ version includes information about the firmware which
+ reported the error.
+
+ pre 19.3:
+ b[31:0]
+ 0x0 version number
+
+ 19.3 or late:
+ b[15:0]
+ 0x1 version number
+ b[31:16]
+ 0x0 no error
+ 0x0DCF Decision CMF error
+ 0x0ACF Application CMF error
+
+What: /sys/devices/platform/stratix10-rsu.0/error_location
+Date: August 2019
+KernelVersion: 5.4
+Contact: Richard Gong <richard.gong@linux.intel.com>
+Description:
+ (RO) the error offset inside the image that failed.
+
+What: /sys/devices/platform/stratix10-rsu.0/error_details
+Date: August 2019
+KernelVersion: 5.4
+Contact: Richard Gong <richard.gong@linux.intel.com>
+Description:
+ (RO) error code.
+
+What: /sys/devices/platform/stratix10-rsu.0/retry_counter
+Date: August 2019
+KernelVersion: 5.4
+Contact: Richard Gong <richard.gong@linux.intel.com>
+Description:
+ (RO) the current image's retry counter, which is used by
+ user to know how many times the images is still allowed
+ to reload itself before giving up and starting RSU
+ fail-over flow.
+
+What: /sys/devices/platform/stratix10-rsu.0/reboot_image
+Date: August 2019
+KernelVersion: 5.4
+Contact: Richard Gong <richard.gong@linux.intel.com>
+Description:
+ (WO) the address in flash of image to be loaded on next
+ reboot command.
+
+What: /sys/devices/platform/stratix10-rsu.0/notify
+Date: August 2019
+KernelVersion: 5.4
+Contact: Richard Gong <richard.gong@linux.intel.com>
+Description:
+ (WO) client to notify firmware with different actions.
+
+ b[15:0]
+ inform firmware the current software execution
+ stage.
+ 0 the first stage bootloader didn't run or
+ didn't reach the point of launching second
+ stage bootloader.
+ 1 failed in second bootloader or didn't get
+ to the point of launching the operating
+ system.
+ 2 both first and second stage bootloader ran
+ and the operating system launch was
+ attempted.
+
+ b[16]
+ 1 firmware to reset current image retry
+ counter.
+ 0 no action.
+
+ b[17]
+ 1 firmware to clear RSU log
+ 0 no action.
+
+ b[18]
+ this is negative logic
+ 1 no action
+ 0 firmware record the notify code defined
+ in b[15:0].
diff --git a/Documentation/ABI/testing/sysfs-devices-power b/Documentation/ABI/testing/sysfs-devices-power
index 80a00f7..1763e64 100644
--- a/Documentation/ABI/testing/sysfs-devices-power
+++ b/Documentation/ABI/testing/sysfs-devices-power
@@ -260,3 +260,12 @@
This attribute has no effect on system-wide suspend/resume and
hibernation.
+
+What: /sys/devices/.../power/runtime_status
+Date: April 2010
+Contact: Rafael J. Wysocki <rjw@rjwysocki.net>
+Description:
+ The /sys/devices/.../power/runtime_status attribute contains
+ the current runtime PM status of the device, which may be
+ "suspended", "suspending", "resuming", "active", "error" (fatal
+ error), or "unsupported" (runtime PM is disabled).
diff --git a/Documentation/ABI/testing/sysfs-devices-soc b/Documentation/ABI/testing/sysfs-devices-soc
index 6d9cc25..ba3a3fa 100644
--- a/Documentation/ABI/testing/sysfs-devices-soc
+++ b/Documentation/ABI/testing/sysfs-devices-soc
@@ -26,6 +26,13 @@
Read-only attribute common to all SoCs. Contains SoC family name
(e.g. DB8500).
+What: /sys/devices/socX/serial_number
+Date: January 2019
+contact: Bjorn Andersson <bjorn.andersson@linaro.org>
+Description:
+ Read-only attribute supported by most SoCs. Contains the SoC's
+ serial number, if available.
+
What: /sys/devices/socX/soc_id
Date: January 2012
contact: Lee Jones <lee.jones@linaro.org>
diff --git a/Documentation/ABI/testing/sysfs-devices-system-cpu b/Documentation/ABI/testing/sysfs-devices-system-cpu
index 5f7d7b1..06d0931 100644
--- a/Documentation/ABI/testing/sysfs-devices-system-cpu
+++ b/Documentation/ABI/testing/sysfs-devices-system-cpu
@@ -562,3 +562,13 @@
or C0.2 state. The time is an unsigned 32-bit number.
Note that a value of zero means there is no limit.
Low order two bits must be zero.
+
+What: /sys/devices/system/cpu/svm
+Date: August 2019
+Contact: Linux kernel mailing list <linux-kernel@vger.kernel.org>
+ Linux for PowerPC mailing list <linuxppc-dev@ozlabs.org>
+Description: Secure Virtual Machine
+
+ If 1, it means the system is using the Protected Execution
+ Facility in POWER9 and newer processors. i.e., it is a Secure
+ Virtual Machine.
diff --git a/Documentation/ABI/testing/sysfs-driver-habanalabs b/Documentation/ABI/testing/sysfs-driver-habanalabs
index f433fc6..782df74 100644
--- a/Documentation/ABI/testing/sysfs-driver-habanalabs
+++ b/Documentation/ABI/testing/sysfs-driver-habanalabs
@@ -57,6 +57,7 @@
Contact: oded.gabbay@gmail.com
Description: Allows the user to set the maximum clock frequency for MME, TPC
and IC when the power management profile is set to "automatic".
+ This property is valid only for the Goya ASIC family
What: /sys/class/habanalabs/hl<n>/ic_clk
Date: Jan 2019
@@ -127,8 +128,8 @@
the max clock frequency to a low value when there are no user
processes that are opened on the device's file. In "manual"
mode, the user sets the maximum clock frequency by writing to
- ic_clk, mme_clk and tpc_clk
-
+ ic_clk, mme_clk and tpc_clk. This property is valid only for
+ the Goya ASIC family
What: /sys/class/habanalabs/hl<n>/preboot_btl_ver
Date: Jan 2019
@@ -186,11 +187,4 @@
Date: Jan 2019
KernelVersion: 5.1
Contact: oded.gabbay@gmail.com
-Description: Version of the u-boot running on the device's CPU
-
-What: /sys/class/habanalabs/hl<n>/write_open_cnt
-Date: Jan 2019
-KernelVersion: 5.1
-Contact: oded.gabbay@gmail.com
-Description: Displays the total number of user processes that are currently
- opened on the device's file
+Description: Version of the u-boot running on the device's CPU
\ No newline at end of file
diff --git a/Documentation/ABI/testing/sysfs-firmware-efi b/Documentation/ABI/testing/sysfs-firmware-efi
index e794eac..5e4d0b2 100644
--- a/Documentation/ABI/testing/sysfs-firmware-efi
+++ b/Documentation/ABI/testing/sysfs-firmware-efi
@@ -28,3 +28,11 @@
versions are always printed first, i.e. ACPI20 comes
before ACPI.
Users: dmidecode
+
+What: /sys/firmware/efi/tables/rci2
+Date: July 2019
+Contact: Narendra K <Narendra.K@dell.com>, linux-bugs@dell.com
+Description: Displays the content of the Runtime Configuration Interface
+ Table version 2 on Dell EMC PowerEdge systems in binary format
+Users: It is used by Dell EMC OpenManage Server Administrator tool to
+ populate BIOS setup page.
diff --git a/Documentation/ABI/testing/sysfs-firmware-turris-mox-rwtm b/Documentation/ABI/testing/sysfs-firmware-turris-mox-rwtm
new file mode 100644
index 0000000..15595fa
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-firmware-turris-mox-rwtm
@@ -0,0 +1,37 @@
+What: /sys/firmware/turris-mox-rwtm/board_version
+Date: August 2019
+KernelVersion: 5.4
+Contact: Marek Behún <marek.behun@nic.cz>
+Description: (R) Board version burned into eFuses of this Turris Mox board.
+ Format: %i
+
+What: /sys/firmware/turris-mox-rwtm/mac_address*
+Date: August 2019
+KernelVersion: 5.4
+Contact: Marek Behún <marek.behun@nic.cz>
+Description: (R) MAC addresses burned into eFuses of this Turris Mox board.
+ Format: %pM
+
+What: /sys/firmware/turris-mox-rwtm/pubkey
+Date: August 2019
+KernelVersion: 5.4
+Contact: Marek Behún <marek.behun@nic.cz>
+Description: (R) ECDSA public key (in pubkey hex compressed form) computed
+ as pair to the ECDSA private key burned into eFuses of this
+ Turris Mox Board.
+ Format: string
+
+What: /sys/firmware/turris-mox-rwtm/ram_size
+Date: August 2019
+KernelVersion: 5.4
+Contact: Marek Behún <marek.behun@nic.cz>
+Description: (R) RAM size in MiB of this Turris Mox board as was detected
+ during manufacturing and burned into eFuses. Can be 512 or 1024.
+ Format: %i
+
+What: /sys/firmware/turris-mox-rwtm/serial_number
+Date: August 2019
+KernelVersion: 5.4
+Contact: Marek Behún <marek.behun@nic.cz>
+Description: (R) Serial number burned into eFuses of this Turris Mox device.
+ Format: %016X
diff --git a/Documentation/ABI/testing/sysfs-fs-f2fs b/Documentation/ABI/testing/sysfs-fs-f2fs
index dca326e..7ab2b1b 100644
--- a/Documentation/ABI/testing/sysfs-fs-f2fs
+++ b/Documentation/ABI/testing/sysfs-fs-f2fs
@@ -251,3 +251,10 @@
If checkpoint=disable, it displays the number of blocks that are unusable.
If checkpoint=enable it displays the enumber of blocks that would be unusable
if checkpoint=disable were to be set.
+
+What: /sys/fs/f2fs/<disk>/encoding
+Date July 2019
+Contact: "Daniel Rosenberg" <drosen@google.com>
+Description:
+ Displays name and version of the encoding set for the filesystem.
+ If no encoding is set, displays (none)
diff --git a/Documentation/ABI/testing/sysfs-kernel-btf b/Documentation/ABI/testing/sysfs-kernel-btf
new file mode 100644
index 0000000..2c9744b
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-kernel-btf
@@ -0,0 +1,17 @@
+What: /sys/kernel/btf
+Date: Aug 2019
+KernelVersion: 5.5
+Contact: bpf@vger.kernel.org
+Description:
+ Contains BTF type information and related data for kernel and
+ kernel modules.
+
+What: /sys/kernel/btf/vmlinux
+Date: Aug 2019
+KernelVersion: 5.5
+Contact: bpf@vger.kernel.org
+Description:
+ Read-only binary attribute exposing kernel's own BTF type
+ information with description of all internal kernel types. See
+ Documentation/bpf/btf.rst for detailed description of format
+ itself.
diff --git a/Documentation/ABI/testing/sysfs-kernel-slab b/Documentation/ABI/testing/sysfs-kernel-slab
index 29601d9..ed35833 100644
--- a/Documentation/ABI/testing/sysfs-kernel-slab
+++ b/Documentation/ABI/testing/sysfs-kernel-slab
@@ -429,10 +429,15 @@
Contact: Pekka Enberg <penberg@cs.helsinki.fi>,
Christoph Lameter <cl@linux-foundation.org>
Description:
- The shrink file is written when memory should be reclaimed from
- a cache. Empty partial slabs are freed and the partial list is
- sorted so the slabs with the fewest available objects are used
- first.
+ The shrink file is used to reclaim unused slab cache
+ memory from a cache. Empty per-cpu or partial slabs
+ are freed and the partial list is sorted so the slabs
+ with the fewest available objects are used first.
+ It only accepts a value of "1" on write for shrinking
+ the cache. Other input values are considered invalid.
+ Shrinking slab caches might be expensive and can
+ adversely impact other running applications. So it
+ should be used with care.
What: /sys/kernel/slab/cache/slab_size
Date: May 2007
diff --git a/Documentation/ABI/testing/sysfs-platform-dfl-fme b/Documentation/ABI/testing/sysfs-platform-dfl-fme
index 8fa4feb..72634d3 100644
--- a/Documentation/ABI/testing/sysfs-platform-dfl-fme
+++ b/Documentation/ABI/testing/sysfs-platform-dfl-fme
@@ -21,3 +21,88 @@
Description: Read-only. It returns Bitstream (static FPGA region) meta
data, which includes the synthesis date, seed and other
information of this static FPGA region.
+
+What: /sys/bus/platform/devices/dfl-fme.0/cache_size
+Date: August 2019
+KernelVersion: 5.4
+Contact: Wu Hao <hao.wu@intel.com>
+Description: Read-only. It returns cache size of this FPGA device.
+
+What: /sys/bus/platform/devices/dfl-fme.0/fabric_version
+Date: August 2019
+KernelVersion: 5.4
+Contact: Wu Hao <hao.wu@intel.com>
+Description: Read-only. It returns fabric version of this FPGA device.
+ Userspace applications need this information to select
+ best data channels per different fabric design.
+
+What: /sys/bus/platform/devices/dfl-fme.0/socket_id
+Date: August 2019
+KernelVersion: 5.4
+Contact: Wu Hao <hao.wu@intel.com>
+Description: Read-only. It returns socket_id to indicate which socket
+ this FPGA belongs to, only valid for integrated solution.
+ User only needs this information, in case standard numa node
+ can't provide correct information.
+
+What: /sys/bus/platform/devices/dfl-fme.0/errors/pcie0_errors
+Date: August 2019
+KernelVersion: 5.4
+Contact: Wu Hao <hao.wu@intel.com>
+Description: Read-Write. Read this file for errors detected on pcie0 link.
+ Write this file to clear errors logged in pcie0_errors. Write
+ fails with -EINVAL if input parsing fails or input error code
+ doesn't match.
+
+What: /sys/bus/platform/devices/dfl-fme.0/errors/pcie1_errors
+Date: August 2019
+KernelVersion: 5.4
+Contact: Wu Hao <hao.wu@intel.com>
+Description: Read-Write. Read this file for errors detected on pcie1 link.
+ Write this file to clear errors logged in pcie1_errors. Write
+ fails with -EINVAL if input parsing fails or input error code
+ doesn't match.
+
+What: /sys/bus/platform/devices/dfl-fme.0/errors/nonfatal_errors
+Date: August 2019
+KernelVersion: 5.4
+Contact: Wu Hao <hao.wu@intel.com>
+Description: Read-only. It returns non-fatal errors detected.
+
+What: /sys/bus/platform/devices/dfl-fme.0/errors/catfatal_errors
+Date: August 2019
+KernelVersion: 5.4
+Contact: Wu Hao <hao.wu@intel.com>
+Description: Read-only. It returns catastrophic and fatal errors detected.
+
+What: /sys/bus/platform/devices/dfl-fme.0/errors/inject_errors
+Date: August 2019
+KernelVersion: 5.4
+Contact: Wu Hao <hao.wu@intel.com>
+Description: Read-Write. Read this file to check errors injected. Write this
+ file to inject errors for testing purpose. Write fails with
+ -EINVAL if input parsing fails or input inject error code isn't
+ supported.
+
+What: /sys/bus/platform/devices/dfl-fme.0/errors/fme_errors
+Date: August 2019
+KernelVersion: 5.4
+Contact: Wu Hao <hao.wu@intel.com>
+Description: Read-Write. Read this file to get errors detected on FME.
+ Write this file to clear errors logged in fme_errors. Write
+ fials with -EINVAL if input parsing fails or input error code
+ doesn't match.
+
+What: /sys/bus/platform/devices/dfl-fme.0/errors/first_error
+Date: August 2019
+KernelVersion: 5.4
+Contact: Wu Hao <hao.wu@intel.com>
+Description: Read-only. Read this file to get the first error detected by
+ hardware.
+
+What: /sys/bus/platform/devices/dfl-fme.0/errors/next_error
+Date: August 2019
+KernelVersion: 5.4
+Contact: Wu Hao <hao.wu@intel.com>
+Description: Read-only. Read this file to get the second error detected by
+ hardware.
diff --git a/Documentation/ABI/testing/sysfs-platform-dfl-port b/Documentation/ABI/testing/sysfs-platform-dfl-port
index 6a92dda..6565826 100644
--- a/Documentation/ABI/testing/sysfs-platform-dfl-port
+++ b/Documentation/ABI/testing/sysfs-platform-dfl-port
@@ -14,3 +14,88 @@
Accelerator Function Unit (AFU) for different functions. It
returns uuid which could be used to identify which PR bitstream
is programmed in this AFU.
+
+What: /sys/bus/platform/devices/dfl-port.0/power_state
+Date: August 2019
+KernelVersion: 5.4
+Contact: Wu Hao <hao.wu@intel.com>
+Description: Read-only. It reports the APx (AFU Power) state, different APx
+ means different throttling level. When reading this file, it
+ returns "0" - Normal / "1" - AP1 / "2" - AP2 / "6" - AP6.
+
+What: /sys/bus/platform/devices/dfl-port.0/ap1_event
+Date: August 2019
+KernelVersion: 5.4
+Contact: Wu Hao <hao.wu@intel.com>
+Description: Read-write. Read this file for AP1 (AFU Power State 1) event.
+ It's used to indicate transient AP1 state. Write 1 to this
+ file to clear AP1 event.
+
+What: /sys/bus/platform/devices/dfl-port.0/ap2_event
+Date: August 2019
+KernelVersion: 5.4
+Contact: Wu Hao <hao.wu@intel.com>
+Description: Read-write. Read this file for AP2 (AFU Power State 2) event.
+ It's used to indicate transient AP2 state. Write 1 to this
+ file to clear AP2 event.
+
+What: /sys/bus/platform/devices/dfl-port.0/ltr
+Date: August 2019
+KernelVersion: 5.4
+Contact: Wu Hao <hao.wu@intel.com>
+Description: Read-write. Read or set AFU latency tolerance reporting value.
+ Set ltr to 1 if the AFU can tolerate latency >= 40us or set it
+ to 0 if it is latency sensitive.
+
+What: /sys/bus/platform/devices/dfl-port.0/userclk_freqcmd
+Date: August 2019
+KernelVersion: 5.4
+Contact: Wu Hao <hao.wu@intel.com>
+Description: Write-only. User writes command to this interface to set
+ userclock to AFU.
+
+What: /sys/bus/platform/devices/dfl-port.0/userclk_freqsts
+Date: August 2019
+KernelVersion: 5.4
+Contact: Wu Hao <hao.wu@intel.com>
+Description: Read-only. Read this file to get the status of issued command
+ to userclck_freqcmd.
+
+What: /sys/bus/platform/devices/dfl-port.0/userclk_freqcntrcmd
+Date: August 2019
+KernelVersion: 5.4
+Contact: Wu Hao <hao.wu@intel.com>
+Description: Write-only. User writes command to this interface to set
+ userclock counter.
+
+What: /sys/bus/platform/devices/dfl-port.0/userclk_freqcntrsts
+Date: August 2019
+KernelVersion: 5.4
+Contact: Wu Hao <hao.wu@intel.com>
+Description: Read-only. Read this file to get the status of issued command
+ to userclck_freqcntrcmd.
+
+What: /sys/bus/platform/devices/dfl-port.0/errors/errors
+Date: August 2019
+KernelVersion: 5.4
+Contact: Wu Hao <hao.wu@intel.com>
+Description: Read-Write. Read this file to get errors detected on port and
+ Accelerated Function Unit (AFU). Write error code to this file
+ to clear errors. Write fails with -EINVAL if input parsing
+ fails or input error code doesn't match. Write fails with
+ -EBUSY or -ETIMEDOUT if error can't be cleared as hardware
+ in low power state (-EBUSY) or not respoding (-ETIMEDOUT).
+
+What: /sys/bus/platform/devices/dfl-port.0/errors/first_error
+Date: August 2019
+KernelVersion: 5.4
+Contact: Wu Hao <hao.wu@intel.com>
+Description: Read-only. Read this file to get the first error detected by
+ hardware.
+
+What: /sys/bus/platform/devices/dfl-port.0/errors/first_malformed_req
+Date: August 2019
+KernelVersion: 5.4
+Contact: Wu Hao <hao.wu@intel.com>
+Description: Read-only. Read this file to get the first malformed request
+ captured by hardware.
diff --git a/Documentation/ABI/testing/sysfs-power b/Documentation/ABI/testing/sysfs-power
index 3c51303..6f87b9d 100644
--- a/Documentation/ABI/testing/sysfs-power
+++ b/Documentation/ABI/testing/sysfs-power
@@ -301,3 +301,109 @@
Using this sysfs file will override any values that were
set using the kernel command line for disk offset.
+
+What: /sys/power/suspend_stats
+Date: July 2019
+Contact: Kalesh Singh <kaleshsingh96@gmail.com>
+Description:
+ The /sys/power/suspend_stats directory contains suspend related
+ statistics.
+
+What: /sys/power/suspend_stats/success
+Date: July 2019
+Contact: Kalesh Singh <kaleshsingh96@gmail.com>
+Description:
+ The /sys/power/suspend_stats/success file contains the number
+ of times entering system sleep state succeeded.
+
+What: /sys/power/suspend_stats/fail
+Date: July 2019
+Contact: Kalesh Singh <kaleshsingh96@gmail.com>
+Description:
+ The /sys/power/suspend_stats/fail file contains the number
+ of times entering system sleep state failed.
+
+What: /sys/power/suspend_stats/failed_freeze
+Date: July 2019
+Contact: Kalesh Singh <kaleshsingh96@gmail.com>
+Description:
+ The /sys/power/suspend_stats/failed_freeze file contains the
+ number of times freezing processes failed.
+
+What: /sys/power/suspend_stats/failed_prepare
+Date: July 2019
+Contact: Kalesh Singh <kaleshsingh96@gmail.com>
+Description:
+ The /sys/power/suspend_stats/failed_prepare file contains the
+ number of times preparing all non-sysdev devices for
+ a system PM transition failed.
+
+What: /sys/power/suspend_stats/failed_resume
+Date: July 2019
+Contact: Kalesh Singh <kaleshsingh96@gmail.com>
+Description:
+ The /sys/power/suspend_stats/failed_resume file contains the
+ number of times executing "resume" callbacks of
+ non-sysdev devices failed.
+
+What: /sys/power/suspend_stats/failed_resume_early
+Date: July 2019
+Contact: Kalesh Singh <kaleshsingh96@gmail.com>
+Description:
+ The /sys/power/suspend_stats/failed_resume_early file contains
+ the number of times executing "early resume" callbacks
+ of devices failed.
+
+What: /sys/power/suspend_stats/failed_resume_noirq
+Date: July 2019
+Contact: Kalesh Singh <kaleshsingh96@gmail.com>
+Description:
+ The /sys/power/suspend_stats/failed_resume_noirq file contains
+ the number of times executing "noirq resume" callbacks
+ of devices failed.
+
+What: /sys/power/suspend_stats/failed_suspend
+Date: July 2019
+Contact: Kalesh Singh <kaleshsingh96@gmail.com>
+Description:
+ The /sys/power/suspend_stats/failed_suspend file contains
+ the number of times executing "suspend" callbacks
+ of all non-sysdev devices failed.
+
+What: /sys/power/suspend_stats/failed_suspend_late
+Date: July 2019
+Contact: Kalesh Singh <kaleshsingh96@gmail.com>
+Description:
+ The /sys/power/suspend_stats/failed_suspend_late file contains
+ the number of times executing "late suspend" callbacks
+ of all devices failed.
+
+What: /sys/power/suspend_stats/failed_suspend_noirq
+Date: July 2019
+Contact: Kalesh Singh <kaleshsingh96@gmail.com>
+Description:
+ The /sys/power/suspend_stats/failed_suspend_noirq file contains
+ the number of times executing "noirq suspend" callbacks
+ of all devices failed.
+
+What: /sys/power/suspend_stats/last_failed_dev
+Date: July 2019
+Contact: Kalesh Singh <kaleshsingh96@gmail.com>
+Description:
+ The /sys/power/suspend_stats/last_failed_dev file contains
+ the last device for which a suspend/resume callback failed.
+
+What: /sys/power/suspend_stats/last_failed_errno
+Date: July 2019
+Contact: Kalesh Singh <kaleshsingh96@gmail.com>
+Description:
+ The /sys/power/suspend_stats/last_failed_errno file contains
+ the errno of the last failed attempt at entering
+ system sleep state.
+
+What: /sys/power/suspend_stats/last_failed_step
+Date: July 2019
+Contact: Kalesh Singh <kaleshsingh96@gmail.com>
+Description:
+ The /sys/power/suspend_stats/last_failed_step file contains
+ the last failed step in the suspend/resume path.
diff --git a/Documentation/DMA-API.txt b/Documentation/DMA-API.txt
index e47c63b..2d8d2fe 100644
--- a/Documentation/DMA-API.txt
+++ b/Documentation/DMA-API.txt
@@ -204,6 +204,14 @@
of the mapping functions like dma_map_single(), dma_map_page() and
others should not be larger than the returned value.
+::
+
+ unsigned long
+ dma_get_merge_boundary(struct device *dev);
+
+Returns the DMA merge boundary. If the device cannot merge any the DMA address
+segments, the function returns 0.
+
Part Id - Streaming DMA mappings
--------------------------------
@@ -595,17 +603,6 @@
region only at the granularity of a page. For smaller allocations,
you should use the dma_pool() API.
-::
-
- void
- dma_release_declared_memory(struct device *dev)
-
-Remove the memory region previously declared from the system. This
-API performs *no* in-use checking for this region and will return
-unconditionally having removed all the required structures. It is the
-driver's job to ensure that no parts of this memory region are
-currently in use.
-
Part III - Debug drivers use of the DMA-API
-------------------------------------------
diff --git a/Documentation/PCI/pci-error-recovery.rst b/Documentation/PCI/pci-error-recovery.rst
index e5d450d..13beee2 100644
--- a/Documentation/PCI/pci-error-recovery.rst
+++ b/Documentation/PCI/pci-error-recovery.rst
@@ -421,7 +421,6 @@
- drivers/net/ixgbe
- drivers/net/cxgb3
- drivers/net/s2io.c
- - drivers/net/qlge
The End
-------
diff --git a/Documentation/RCU/Design/Requirements/Requirements.html b/Documentation/RCU/Design/Requirements/Requirements.html
index 5a9238a..467251f 100644
--- a/Documentation/RCU/Design/Requirements/Requirements.html
+++ b/Documentation/RCU/Design/Requirements/Requirements.html
@@ -2129,6 +2129,8 @@
<li> <a href="#Hotplug CPU">Hotplug CPU</a>.
<li> <a href="#Scheduler and RCU">Scheduler and RCU</a>.
<li> <a href="#Tracing and RCU">Tracing and RCU</a>.
+<li> <a href="#Accesses to User Memory and RCU">
+Accesses to User Memory and RCU</a>.
<li> <a href="#Energy Efficiency">Energy Efficiency</a>.
<li> <a href="#Scheduling-Clock Interrupts and RCU">
Scheduling-Clock Interrupts and RCU</a>.
@@ -2512,7 +2514,7 @@
<p>
It is possible to use tracing on RCU code, but tracing itself
uses RCU.
-For this reason, <tt>rcu_dereference_raw_notrace()</tt>
+For this reason, <tt>rcu_dereference_raw_check()</tt>
is provided for use by tracing, which avoids the destructive
recursion that could otherwise ensue.
This API is also used by virtualization in some architectures,
@@ -2521,6 +2523,75 @@
The tracing folks both located the requirement and provided the
needed fix, so this surprise requirement was relatively painless.
+<h3><a name="Accesses to User Memory and RCU">
+Accesses to User Memory and RCU</a></h3>
+
+<p>
+The kernel needs to access user-space memory, for example, to access
+data referenced by system-call parameters.
+The <tt>get_user()</tt> macro does this job.
+
+<p>
+However, user-space memory might well be paged out, which means
+that <tt>get_user()</tt> might well page-fault and thus block while
+waiting for the resulting I/O to complete.
+It would be a very bad thing for the compiler to reorder
+a <tt>get_user()</tt> invocation into an RCU read-side critical
+section.
+For example, suppose that the source code looked like this:
+
+<blockquote>
+<pre>
+ 1 rcu_read_lock();
+ 2 p = rcu_dereference(gp);
+ 3 v = p->value;
+ 4 rcu_read_unlock();
+ 5 get_user(user_v, user_p);
+ 6 do_something_with(v, user_v);
+</pre>
+</blockquote>
+
+<p>
+The compiler must not be permitted to transform this source code into
+the following:
+
+<blockquote>
+<pre>
+ 1 rcu_read_lock();
+ 2 p = rcu_dereference(gp);
+ 3 get_user(user_v, user_p); // BUG: POSSIBLE PAGE FAULT!!!
+ 4 v = p->value;
+ 5 rcu_read_unlock();
+ 6 do_something_with(v, user_v);
+</pre>
+</blockquote>
+
+<p>
+If the compiler did make this transformation in a
+<tt>CONFIG_PREEMPT=n</tt> kernel build, and if <tt>get_user()</tt> did
+page fault, the result would be a quiescent state in the middle
+of an RCU read-side critical section.
+This misplaced quiescent state could result in line 4 being
+a use-after-free access, which could be bad for your kernel's
+actuarial statistics.
+Similar examples can be constructed with the call to <tt>get_user()</tt>
+preceding the <tt>rcu_read_lock()</tt>.
+
+<p>
+Unfortunately, <tt>get_user()</tt> doesn't have any particular
+ordering properties, and in some architectures the underlying <tt>asm</tt>
+isn't even marked <tt>volatile</tt>.
+And even if it was marked <tt>volatile</tt>, the above access to
+<tt>p->value</tt> is not volatile, so the compiler would not have any
+reason to keep those two accesses in order.
+
+<p>
+Therefore, the Linux-kernel definitions of <tt>rcu_read_lock()</tt>
+and <tt>rcu_read_unlock()</tt> must act as compiler barriers,
+at least for outermost instances of <tt>rcu_read_lock()</tt> and
+<tt>rcu_read_unlock()</tt> within a nested set of RCU read-side critical
+sections.
+
<h3><a name="Energy Efficiency">Energy Efficiency</a></h3>
<p>
diff --git a/Documentation/RCU/stallwarn.txt b/Documentation/RCU/stallwarn.txt
index 13e88fc..f48f462 100644
--- a/Documentation/RCU/stallwarn.txt
+++ b/Documentation/RCU/stallwarn.txt
@@ -57,6 +57,12 @@
CONFIG_PREEMPT_RCU case, you might see stall-warning
messages.
+ You can use the rcutree.kthread_prio kernel boot parameter to
+ increase the scheduling priority of RCU's kthreads, which can
+ help avoid this problem. However, please note that doing this
+ can increase your system's context-switch rate and thus degrade
+ performance.
+
o A periodic interrupt whose handler takes longer than the time
interval between successive pairs of interrupts. This can
prevent RCU's kthreads and softirq handlers from running.
diff --git a/Documentation/acpi/dsd/leds.txt b/Documentation/acpi/dsd/leds.txt
deleted file mode 100644
index cc58b1a..0000000
--- a/Documentation/acpi/dsd/leds.txt
+++ /dev/null
@@ -1,99 +0,0 @@
-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
-tells the numerical ID of each individual LED output to which the LEDs are
-connected. [3] The hierarchical data nodes are named "led@X", where X is the
-number of the LED output.
-
-Referring to LEDs in Device tree is documented in [4], in "flash-leds" property
-documentation. In short, LEDs are directly referred to by using phandles.
-
-While Device tree allows referring to any node in the tree[1], in ACPI
-references are limited to device nodes only [2]. For this reason using the same
-mechanism on ACPI is not possible. A mechanism to refer to non-device ACPI nodes
-is documented in [7].
-
-ACPI allows (as does DT) using integer arguments after the reference. A
-combination of the LED driver device reference and an integer argument,
-referring to the "reg" property of the relevant LED, is used to identify
-individual LEDs. The value of the "reg" property is a contract between the
-firmware and software, it uniquely identifies the LED driver outputs.
-
-Under the LED driver device, The first hierarchical data extension package list
-entry shall contain the string "led@" followed by the number of the LED,
-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.
-
- Device (LED)
- {
- Name (_DSD, Package () {
- ToUUID("dbb8e3e6-5886-4ba6-8795-1319f52a966b"),
- Package () {
- Package () { "led@0", LED0 },
- Package () { "led@1", LED1 },
- }
- })
- Name (LED0, Package () {
- ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
- Package () {
- Package () { "reg", 0 },
- Package () { "flash-max-microamp", 1000000 },
- Package () { "flash-timeout-us", 200000 },
- Package () { "led-max-microamp", 100000 },
- Package () { "label", "white:flash" },
- }
- })
- Name (LED1, Package () {
- ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
- Package () {
- Package () { "reg", 1 },
- Package () { "led-max-microamp", 10000 },
- Package () { "label", "red:indicator" },
- }
- })
- }
-
- Device (SEN)
- {
- Name (_DSD, Package () {
- ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
- Package () {
- Package () {
- "flash-leds",
- Package () { ^LED, "led@0", ^LED, "led@1" },
- }
- }
- })
- }
-
-where
-
- 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.
-
-[2] Advanced Configuration and Power Interface Specification.
- <URL:https://uefi.org/sites/default/files/resources/ACPI_6_3_final_Jan30.pdf>,
- referenced 2019-02-21.
-
-[3] Documentation/devicetree/bindings/leds/common.txt
-
-[4] Documentation/devicetree/bindings/media/video-interfaces.txt
-
-[5] Device Properties UUID For _DSD.
- <URL:http://www.uefi.org/sites/default/files/resources/_DSD-device-properties-UUID.pdf>,
- referenced 2019-02-21.
-
-[6] Hierarchical Data Extension UUID For _DSD.
- <URL:http://www.uefi.org/sites/default/files/resources/_DSD-hierarchical-data-extension-UUID-v1.1.pdf>,
- referenced 2019-02-21.
-
-[7] Documentation/firmware-guide/acpi/dsd/data-node-references.rst
diff --git a/Documentation/admin-guide/auxdisplay/cfag12864b.rst b/Documentation/admin-guide/auxdisplay/cfag12864b.rst
new file mode 100644
index 0000000..18c2865
--- /dev/null
+++ b/Documentation/admin-guide/auxdisplay/cfag12864b.rst
@@ -0,0 +1,98 @@
+===================================
+cfag12864b LCD Driver Documentation
+===================================
+
+:License: GPLv2
+:Author & Maintainer: Miguel Ojeda Sandonis
+:Date: 2006-10-27
+
+
+
+.. INDEX
+
+ 1. DRIVER INFORMATION
+ 2. DEVICE INFORMATION
+ 3. WIRING
+ 4. USERSPACE PROGRAMMING
+
+1. Driver Information
+---------------------
+
+This driver supports a cfag12864b LCD.
+
+
+2. Device Information
+---------------------
+
+:Manufacturer: Crystalfontz
+:Device Name: Crystalfontz 12864b LCD Series
+:Device Code: cfag12864b
+:Webpage: http://www.crystalfontz.com
+:Device Webpage: http://www.crystalfontz.com/products/12864b/
+:Type: LCD (Liquid Crystal Display)
+:Width: 128
+:Height: 64
+:Colors: 2 (B/N)
+:Controller: ks0108
+:Controllers: 2
+:Pages: 8 each controller
+:Addresses: 64 each page
+:Data size: 1 byte each address
+:Memory size: 2 * 8 * 64 * 1 = 1024 bytes = 1 Kbyte
+
+
+3. Wiring
+---------
+
+The cfag12864b LCD Series don't have official wiring.
+
+The common wiring is done to the parallel port as shown::
+
+ Parallel Port cfag12864b
+
+ Name Pin# Pin# Name
+
+ Strobe ( 1)------------------------------(17) Enable
+ Data 0 ( 2)------------------------------( 4) Data 0
+ Data 1 ( 3)------------------------------( 5) Data 1
+ Data 2 ( 4)------------------------------( 6) Data 2
+ Data 3 ( 5)------------------------------( 7) Data 3
+ Data 4 ( 6)------------------------------( 8) Data 4
+ Data 5 ( 7)------------------------------( 9) Data 5
+ Data 6 ( 8)------------------------------(10) Data 6
+ Data 7 ( 9)------------------------------(11) Data 7
+ (10) [+5v]---( 1) Vdd
+ (11) [GND]---( 2) Ground
+ (12) [+5v]---(14) Reset
+ (13) [GND]---(15) Read / Write
+ Line (14)------------------------------(13) Controller Select 1
+ (15)
+ Init (16)------------------------------(12) Controller Select 2
+ Select (17)------------------------------(16) Data / Instruction
+ Ground (18)---[GND] [+5v]---(19) LED +
+ Ground (19)---[GND]
+ Ground (20)---[GND] E A Values:
+ Ground (21)---[GND] [GND]---[P1]---(18) Vee - R = Resistor = 22 ohm
+ Ground (22)---[GND] | - P1 = Preset = 10 Kohm
+ Ground (23)---[GND] ---- S ------( 3) V0 - P2 = Preset = 1 Kohm
+ Ground (24)---[GND] | |
+ Ground (25)---[GND] [GND]---[P2]---[R]---(20) LED -
+
+
+4. Userspace Programming
+------------------------
+
+The cfag12864bfb describes a framebuffer device (/dev/fbX).
+
+It has a size of 1024 bytes = 1 Kbyte.
+Each bit represents one pixel. If the bit is high, the pixel will
+turn on. If the pixel is low, the pixel will turn off.
+
+You can use the framebuffer as a file: fopen, fwrite, fclose...
+Although the LCD won't get updated until the next refresh time arrives.
+
+Also, you can mmap the framebuffer: open & mmap, munmap & close...
+which is the best option for most uses.
+
+Check samples/auxdisplay/cfag12864b-example.c
+for a real working userspace complete program with usage examples.
diff --git a/Documentation/admin-guide/auxdisplay/index.rst b/Documentation/admin-guide/auxdisplay/index.rst
new file mode 100644
index 0000000..e466f05
--- /dev/null
+++ b/Documentation/admin-guide/auxdisplay/index.rst
@@ -0,0 +1,16 @@
+=========================
+Auxiliary Display Support
+=========================
+
+.. toctree::
+ :maxdepth: 1
+
+ ks0108.rst
+ cfag12864b.rst
+
+.. only:: subproject and html
+
+ Indices
+ =======
+
+ * :ref:`genindex`
diff --git a/Documentation/admin-guide/auxdisplay/ks0108.rst b/Documentation/admin-guide/auxdisplay/ks0108.rst
new file mode 100644
index 0000000..c0b7faf
--- /dev/null
+++ b/Documentation/admin-guide/auxdisplay/ks0108.rst
@@ -0,0 +1,50 @@
+==========================================
+ks0108 LCD Controller Driver Documentation
+==========================================
+
+:License: GPLv2
+:Author & Maintainer: Miguel Ojeda Sandonis
+:Date: 2006-10-27
+
+
+
+.. INDEX
+
+ 1. DRIVER INFORMATION
+ 2. DEVICE INFORMATION
+ 3. WIRING
+
+
+1. Driver Information
+---------------------
+
+This driver supports the ks0108 LCD controller.
+
+
+2. Device Information
+---------------------
+
+:Manufacturer: Samsung
+:Device Name: KS0108 LCD Controller
+:Device Code: ks0108
+:Webpage: -
+:Device Webpage: -
+:Type: LCD Controller (Liquid Crystal Display Controller)
+:Width: 64
+:Height: 64
+:Colors: 2 (B/N)
+:Pages: 8
+:Addresses: 64 each page
+:Data size: 1 byte each address
+:Memory size: 8 * 64 * 1 = 512 bytes
+
+
+3. Wiring
+---------
+
+The driver supports data parallel port wiring.
+
+If you aren't building LCD related hardware, you should check
+your LCD specific wiring information in the same folder.
+
+For example, check Documentation/admin-guide/auxdisplay/cfag12864b.rst
diff --git a/Documentation/admin-guide/cgroup-v1/blkio-controller.rst b/Documentation/admin-guide/cgroup-v1/blkio-controller.rst
index 1d7d962..36d43ae 100644
--- a/Documentation/admin-guide/cgroup-v1/blkio-controller.rst
+++ b/Documentation/admin-guide/cgroup-v1/blkio-controller.rst
@@ -130,12 +130,6 @@
dev weight
8:16 300
-- blkio.leaf_weight[_device]
- - Equivalents of blkio.weight[_device] for the purpose of
- deciding how much weight tasks in the given cgroup has while
- competing with the cgroup's child cgroups. For details,
- please refer to Documentation/block/cfq-iosched.txt.
-
- blkio.time
- disk time allocated to cgroup per device in milliseconds. First
two fields specify the major and minor number of the device and
diff --git a/Documentation/admin-guide/cgroup-v1/memory.rst b/Documentation/admin-guide/cgroup-v1/memory.rst
index 41bdc03..0ae4f56 100644
--- a/Documentation/admin-guide/cgroup-v1/memory.rst
+++ b/Documentation/admin-guide/cgroup-v1/memory.rst
@@ -85,8 +85,10 @@
memory.oom_control set/show oom controls.
memory.numa_stat show the number of memory usage per numa
node
-
memory.kmem.limit_in_bytes set/show hard limit for kernel memory
+ This knob is deprecated and shouldn't be
+ used. It is planned that this be removed in
+ the foreseeable future.
memory.kmem.usage_in_bytes show current kernel memory allocation
memory.kmem.failcnt show the number of kernel memory usage
hits limits
diff --git a/Documentation/admin-guide/cgroup-v2.rst b/Documentation/admin-guide/cgroup-v2.rst
index 3b29005..0fa8c0e 100644
--- a/Documentation/admin-guide/cgroup-v2.rst
+++ b/Documentation/admin-guide/cgroup-v2.rst
@@ -951,6 +951,13 @@
normal scheduling policy and absolute bandwidth allocation model for
realtime scheduling policy.
+In all the above models, cycles distribution is defined only on a temporal
+base and it does not account for the frequency at which tasks are executed.
+The (optional) utilization clamping support allows to hint the schedutil
+cpufreq governor about the minimum desired frequency which should always be
+provided by a CPU, as well as the maximum desired frequency, which should not
+be exceeded by a CPU.
+
WARNING: cgroup2 doesn't yet support control of realtime processes and
the cpu controller can only be enabled when all RT processes are in
the root cgroup. Be aware that system management software may already
@@ -1016,6 +1023,33 @@
Shows pressure stall information for CPU. See
Documentation/accounting/psi.rst for details.
+ cpu.uclamp.min
+ A read-write single value file which exists on non-root cgroups.
+ The default is "0", i.e. no utilization boosting.
+
+ The requested minimum utilization (protection) as a percentage
+ rational number, e.g. 12.34 for 12.34%.
+
+ This interface allows reading and setting minimum utilization clamp
+ values similar to the sched_setattr(2). This minimum utilization
+ value is used to clamp the task specific minimum utilization clamp.
+
+ The requested minimum utilization (protection) is always capped by
+ the current value for the maximum utilization (limit), i.e.
+ `cpu.uclamp.max`.
+
+ cpu.uclamp.max
+ A read-write single value file which exists on non-root cgroups.
+ The default is "max". i.e. no utilization capping
+
+ The requested maximum utilization (limit) as a percentage rational
+ number, e.g. 98.76 for 98.76%.
+
+ This interface allows reading and setting maximum utilization clamp
+ values similar to the sched_setattr(2). This maximum utilization
+ value is used to clamp the task specific maximum utilization clamp.
+
+
Memory
------
@@ -1435,6 +1469,103 @@
8:16 rbytes=1459200 wbytes=314773504 rios=192 wios=353 dbytes=0 dios=0
8:0 rbytes=90430464 wbytes=299008000 rios=8950 wios=1252 dbytes=50331648 dios=3021
+ io.cost.qos
+ A read-write nested-keyed file with exists only on the root
+ cgroup.
+
+ This file configures the Quality of Service of the IO cost
+ model based controller (CONFIG_BLK_CGROUP_IOCOST) which
+ currently implements "io.weight" proportional control. Lines
+ are keyed by $MAJ:$MIN device numbers and not ordered. The
+ line for a given device is populated on the first write for
+ the device on "io.cost.qos" or "io.cost.model". The following
+ nested keys are defined.
+
+ ====== =====================================
+ enable Weight-based control enable
+ ctrl "auto" or "user"
+ rpct Read latency percentile [0, 100]
+ rlat Read latency threshold
+ wpct Write latency percentile [0, 100]
+ wlat Write latency threshold
+ min Minimum scaling percentage [1, 10000]
+ max Maximum scaling percentage [1, 10000]
+ ====== =====================================
+
+ The controller is disabled by default and can be enabled by
+ setting "enable" to 1. "rpct" and "wpct" parameters default
+ to zero and the controller uses internal device saturation
+ state to adjust the overall IO rate between "min" and "max".
+
+ When a better control quality is needed, latency QoS
+ parameters can be configured. For example::
+
+ 8:16 enable=1 ctrl=auto rpct=95.00 rlat=75000 wpct=95.00 wlat=150000 min=50.00 max=150.0
+
+ shows that on sdb, the controller is enabled, will consider
+ the device saturated if the 95th percentile of read completion
+ latencies is above 75ms or write 150ms, and adjust the overall
+ IO issue rate between 50% and 150% accordingly.
+
+ The lower the saturation point, the better the latency QoS at
+ the cost of aggregate bandwidth. The narrower the allowed
+ adjustment range between "min" and "max", the more conformant
+ to the cost model the IO behavior. Note that the IO issue
+ base rate may be far off from 100% and setting "min" and "max"
+ blindly can lead to a significant loss of device capacity or
+ control quality. "min" and "max" are useful for regulating
+ devices which show wide temporary behavior changes - e.g. a
+ ssd which accepts writes at the line speed for a while and
+ then completely stalls for multiple seconds.
+
+ When "ctrl" is "auto", the parameters are controlled by the
+ kernel and may change automatically. Setting "ctrl" to "user"
+ or setting any of the percentile and latency parameters puts
+ it into "user" mode and disables the automatic changes. The
+ automatic mode can be restored by setting "ctrl" to "auto".
+
+ io.cost.model
+ A read-write nested-keyed file with exists only on the root
+ cgroup.
+
+ This file configures the cost model of the IO cost model based
+ controller (CONFIG_BLK_CGROUP_IOCOST) which currently
+ implements "io.weight" proportional control. Lines are keyed
+ by $MAJ:$MIN device numbers and not ordered. The line for a
+ given device is populated on the first write for the device on
+ "io.cost.qos" or "io.cost.model". The following nested keys
+ are defined.
+
+ ===== ================================
+ ctrl "auto" or "user"
+ model The cost model in use - "linear"
+ ===== ================================
+
+ When "ctrl" is "auto", the kernel may change all parameters
+ dynamically. When "ctrl" is set to "user" or any other
+ parameters are written to, "ctrl" become "user" and the
+ automatic changes are disabled.
+
+ When "model" is "linear", the following model parameters are
+ defined.
+
+ ============= ========================================
+ [r|w]bps The maximum sequential IO throughput
+ [r|w]seqiops The maximum 4k sequential IOs per second
+ [r|w]randiops The maximum 4k random IOs per second
+ ============= ========================================
+
+ From the above, the builtin linear model determines the base
+ costs of a sequential and random IO and the cost coefficient
+ for the IO size. While simple, this model can cover most
+ common device classes acceptably.
+
+ The IO cost model isn't expected to be accurate in absolute
+ sense and is scaled to the device behavior dynamically.
+
+ If needed, tools/cgroup/iocost_coef_gen.py can be used to
+ generate device-specific coefficients.
+
io.weight
A read-write flat-keyed file which exists on non-root cgroups.
The default is "default 100".
diff --git a/Documentation/admin-guide/cifs/authors.rst b/Documentation/admin-guide/cifs/authors.rst
new file mode 100644
index 0000000..b02d6dd
--- /dev/null
+++ b/Documentation/admin-guide/cifs/authors.rst
@@ -0,0 +1,69 @@
+=======
+Authors
+=======
+
+Original Author
+---------------
+
+Steve French (sfrench@samba.org)
+
+The author wishes to express his appreciation and thanks to:
+Andrew Tridgell (Samba team) for his early suggestions about smb/cifs VFS
+improvements. Thanks to IBM for allowing me time and test resources to pursue
+this project, to Jim McDonough from IBM (and the Samba Team) for his help, to
+the IBM Linux JFS team for explaining many esoteric Linux filesystem features.
+Jeremy Allison of the Samba team has done invaluable work in adding the server
+side of the original CIFS Unix extensions and reviewing and implementing
+portions of the newer CIFS POSIX extensions into the Samba 3 file server. Thank
+Dave Boutcher of IBM Rochester (author of the OS/400 smb/cifs filesystem client)
+for proving years ago that very good smb/cifs clients could be done on Unix-like
+operating systems. Volker Lendecke, Andrew Tridgell, Urban Widmark, John
+Newbigin and others for their work on the Linux smbfs module. Thanks to
+the other members of the Storage Network Industry Association CIFS Technical
+Workgroup for their work specifying this highly complex protocol and finally
+thanks to the Samba team for their technical advice and encouragement.
+
+Patch Contributors
+------------------
+
+- Zwane Mwaikambo
+- Andi Kleen
+- Amrut Joshi
+- Shobhit Dayal
+- Sergey Vlasov
+- Richard Hughes
+- Yury Umanets
+- Mark Hamzy (for some of the early cifs IPv6 work)
+- Domen Puncer
+- Jesper Juhl (in particular for lots of whitespace/formatting cleanup)
+- Vince Negri and Dave Stahl (for finding an important caching bug)
+- Adrian Bunk (kcalloc cleanups)
+- Miklos Szeredi
+- Kazeon team for various fixes especially for 2.4 version.
+- Asser Ferno (Change Notify support)
+- Shaggy (Dave Kleikamp) for innumerable small fs suggestions and some good cleanup
+- Gunter Kukkukk (testing and suggestions for support of old servers)
+- Igor Mammedov (DFS support)
+- Jeff Layton (many, many fixes, as well as great work on the cifs Kerberos code)
+- Scott Lovenberg
+- Pavel Shilovsky (for great work adding SMB2 support, and various SMB3 features)
+- Aurelien Aptel (for DFS SMB3 work and some key bug fixes)
+- Ronnie Sahlberg (for SMB3 xattr work, bug fixes, and lots of great work on compounding)
+- Shirish Pargaonkar (for many ACL patches over the years)
+- Sachin Prabhu (many bug fixes, including for reconnect, copy offload and security)
+- Paulo Alcantara
+- Long Li (some great work on RDMA, SMB Direct)
+
+
+Test case and Bug Report contributors
+-------------------------------------
+Thanks to those in the community who have submitted detailed bug reports
+and debug of problems they have found: Jochen Dolze, David Blaine,
+Rene Scharfe, Martin Josefsson, Alexander Wild, Anthony Liguori,
+Lars Muller, Urban Widmark, Massimiliano Ferrero, Howard Owen,
+Olaf Kirch, Kieron Briggs, Nick Millington and others. Also special
+mention to the Stanford Checker (SWAT) which pointed out many minor
+bugs in error paths. Valuable suggestions also have come from Al Viro
+and Dave Miller.
+
+And thanks to the IBM LTC and Power test teams and SuSE and Citrix and RedHat testers for finding multiple bugs during excellent stress test runs.
diff --git a/Documentation/admin-guide/cifs/changes.rst b/Documentation/admin-guide/cifs/changes.rst
new file mode 100644
index 0000000..71f2ecb
--- /dev/null
+++ b/Documentation/admin-guide/cifs/changes.rst
@@ -0,0 +1,8 @@
+=======
+Changes
+=======
+
+See https://wiki.samba.org/index.php/LinuxCIFSKernel for summary
+information (that may be easier to read than parsing the output of
+"git log fs/cifs") about fixes/improvements to CIFS/SMB2/SMB3 support (changes
+to cifs.ko module) by kernel version (and cifs internal module version).
diff --git a/Documentation/admin-guide/cifs/index.rst b/Documentation/admin-guide/cifs/index.rst
new file mode 100644
index 0000000..fad5268
--- /dev/null
+++ b/Documentation/admin-guide/cifs/index.rst
@@ -0,0 +1,21 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+====
+CIFS
+====
+
+.. toctree::
+ :maxdepth: 2
+
+ introduction
+ usage
+ todo
+ changes
+ authors
+
+.. only:: subproject and html
+
+ Indices
+ =======
+
+ * :ref:`genindex`
diff --git a/Documentation/admin-guide/cifs/introduction.rst b/Documentation/admin-guide/cifs/introduction.rst
new file mode 100644
index 0000000..0b98f67
--- /dev/null
+++ b/Documentation/admin-guide/cifs/introduction.rst
@@ -0,0 +1,53 @@
+============
+Introduction
+============
+
+ This is the client VFS module for the SMB3 NAS protocol as well
+ as for older dialects such as the Common Internet File System (CIFS)
+ protocol which was the successor to the Server Message Block
+ (SMB) protocol, the native file sharing mechanism for most early
+ PC operating systems. New and improved versions of CIFS are now
+ called SMB2 and SMB3. Use of SMB3 (and later, including SMB3.1.1)
+ is strongly preferred over using older dialects like CIFS due to
+ security reaasons. All modern dialects, including the most recent,
+ SMB3.1.1 are supported by the CIFS VFS module. The SMB3 protocol
+ is implemented and supported by all major file servers
+ such as all modern versions of Windows (including Windows 2016
+ Server), as well as by Samba (which provides excellent
+ CIFS/SMB2/SMB3 server support and tools for Linux and many other
+ operating systems). Apple systems also support SMB3 well, as
+ do most Network Attached Storage vendors, so this network
+ filesystem client can mount to a wide variety of systems.
+ It also supports mounting to the cloud (for example
+ Microsoft Azure), including the necessary security features.
+
+ The intent of this module is to provide the most advanced network
+ file system function for SMB3 compliant servers, including advanced
+ security features, excellent parallelized high performance i/o, better
+ POSIX compliance, secure per-user session establishment, encryption,
+ high performance safe distributed caching (leases/oplocks), optional packet
+ signing, large files, Unicode support and other internationalization
+ improvements. Since both Samba server and this filesystem client support
+ the CIFS Unix extensions (and in the future SMB3 POSIX extensions),
+ the combination can provide a reasonable alternative to other network and
+ cluster file systems for fileserving in some Linux to Linux environments,
+ not just in Linux to Windows (or Linux to Mac) environments.
+
+ This filesystem has a mount utility (mount.cifs) and various user space
+ tools (including smbinfo and setcifsacl) that can be obtained from
+
+ https://git.samba.org/?p=cifs-utils.git
+
+ or
+
+ git://git.samba.org/cifs-utils.git
+
+ mount.cifs should be installed in the directory with the other mount helpers.
+
+ For more information on the module see the project wiki page at
+
+ https://wiki.samba.org/index.php/LinuxCIFS
+
+ and
+
+ https://wiki.samba.org/index.php/LinuxCIFS_utils
diff --git a/Documentation/admin-guide/cifs/todo.rst b/Documentation/admin-guide/cifs/todo.rst
new file mode 100644
index 0000000..084c25f
--- /dev/null
+++ b/Documentation/admin-guide/cifs/todo.rst
@@ -0,0 +1,133 @@
+====
+TODO
+====
+
+Version 2.14 December 21, 2018
+
+A Partial List of Missing Features
+==================================
+
+Contributions are welcome. There are plenty of opportunities
+for visible, important contributions to this module. Here
+is a partial list of the known problems and missing features:
+
+a) SMB3 (and SMB3.1.1) missing optional features:
+
+ - multichannel (started), integration with RDMA
+ - directory leases (improved metadata caching), started (root dir only)
+ - T10 copy offload ie "ODX" (copy chunk, and "Duplicate Extents" ioctl
+ currently the only two server side copy mechanisms supported)
+
+b) improved sparse file support (fiemap and SEEK_HOLE are implemented
+ but additional features would be supportable by the protocol).
+
+c) Directory entry caching relies on a 1 second timer, rather than
+ using Directory Leases, currently only the root file handle is cached longer
+
+d) quota support (needs minor kernel change since quota calls
+ to make it to network filesystems or deviceless filesystems)
+
+e) Additional use cases can be optimized to use "compounding" (e.g.
+ open/query/close and open/setinfo/close) to reduce the number of
+ roundtrips to the server and improve performance. Various cases
+ (stat, statfs, create, unlink, mkdir) already have been improved by
+ using compounding but more can be done. In addition we could
+ significantly reduce redundant opens by using deferred close (with
+ handle caching leases) and better using reference counters on file
+ handles.
+
+f) Finish inotify support so kde and gnome file list windows
+ will autorefresh (partially complete by Asser). Needs minor kernel
+ vfs change to support removing D_NOTIFY on a file.
+
+g) Add GUI tool to configure /proc/fs/cifs settings and for display of
+ the CIFS statistics (started)
+
+h) implement support for security and trusted categories of xattrs
+ (requires minor protocol extension) to enable better support for SELINUX
+
+i) Add support for tree connect contexts (see MS-SMB2) a new SMB3.1.1 protocol
+ feature (may be especially useful for virtualization).
+
+j) Create UID mapping facility so server UIDs can be mapped on a per
+ mount or a per server basis to client UIDs or nobody if no mapping
+ exists. Also better integration with winbind for resolving SID owners
+
+k) Add tools to take advantage of more smb3 specific ioctls and features
+ (passthrough ioctl/fsctl is now implemented in cifs.ko to allow
+ sending various SMB3 fsctls and query info and set info calls
+ directly from user space) Add tools to make setting various non-POSIX
+ metadata attributes easier from tools (e.g. extending what was done
+ in smb-info tool).
+
+l) encrypted file support
+
+m) improved stats gathering tools (perhaps integration with nfsometer?)
+ to extend and make easier to use what is currently in /proc/fs/cifs/Stats
+
+n) Add support for claims based ACLs ("DAC")
+
+o) mount helper GUI (to simplify the various configuration options on mount)
+
+p) Add support for witness protocol (perhaps ioctl to cifs.ko from user space
+ tool listening on witness protocol RPC) to allow for notification of share
+ move, server failover, and server adapter changes. And also improve other
+ failover scenarios, e.g. when client knows multiple DFS entries point to
+ different servers, and the server we are connected to has gone down.
+
+q) Allow mount.cifs to be more verbose in reporting errors with dialect
+ or unsupported feature errors.
+
+r) updating cifs documentation, and user guide.
+
+s) Addressing bugs found by running a broader set of xfstests in standard
+ file system xfstest suite.
+
+t) split cifs and smb3 support into separate modules so legacy (and less
+ secure) CIFS dialect can be disabled in environments that don't need it
+ and simplify the code.
+
+v) POSIX Extensions for SMB3.1.1 (started, create and mkdir support added
+ so far).
+
+w) Add support for additional strong encryption types, and additional spnego
+ authentication mechanisms (see MS-SMB2)
+
+x) Finish support for SMB3.1.1 compression
+
+Known Bugs
+==========
+
+See http://bugzilla.samba.org - search on product "CifsVFS" for
+current bug list. Also check http://bugzilla.kernel.org (Product = File System, Component = CIFS)
+
+1) existing symbolic links (Windows reparse points) are recognized but
+ can not be created remotely. They are implemented for Samba and those that
+ support the CIFS Unix extensions, although earlier versions of Samba
+ overly restrict the pathnames.
+2) follow_link and readdir code does not follow dfs junctions
+ but recognizes them
+
+Misc testing to do
+==================
+1) check out max path names and max path name components against various server
+ types. Try nested symlinks (8 deep). Return max path name in stat -f information
+
+2) Improve xfstest's cifs/smb3 enablement and adapt xfstests where needed to test
+ cifs/smb3 better
+
+3) Additional performance testing and optimization using iozone and similar -
+ there are some easy changes that can be done to parallelize sequential writes,
+ and when signing is disabled to request larger read sizes (larger than
+ negotiated size) and send larger write sizes to modern servers.
+
+4) More exhaustively test against less common servers
+
+5) Continue to extend the smb3 "buildbot" which does automated xfstesting
+ against Windows, Samba and Azure currently - to add additional tests and
+ to allow the buildbot to execute the tests faster. The URL for the
+ buildbot is: http://smb3-test-rhel-75.southcentralus.cloudapp.azure.com
+
+6) Address various coverity warnings (most are not bugs per-se, but
+ the more warnings are addressed, the easier it is to spot real
+ problems that static analyzers will point out in the future).
diff --git a/Documentation/admin-guide/cifs/usage.rst b/Documentation/admin-guide/cifs/usage.rst
new file mode 100644
index 0000000..d3fb67b
--- /dev/null
+++ b/Documentation/admin-guide/cifs/usage.rst
@@ -0,0 +1,869 @@
+=====
+Usage
+=====
+
+This module supports the SMB3 family of advanced network protocols (as well
+as older dialects, originally called "CIFS" or SMB1).
+
+The CIFS VFS module for Linux supports many advanced network filesystem
+features such as hierarchical DFS like namespace, hardlinks, locking and more.
+It was designed to comply with the SNIA CIFS Technical Reference (which
+supersedes the 1992 X/Open SMB Standard) as well as to perform best practice
+practical interoperability with Windows 2000, Windows XP, Samba and equivalent
+servers. This code was developed in participation with the Protocol Freedom
+Information Foundation. CIFS and now SMB3 has now become a defacto
+standard for interoperating between Macs and Windows and major NAS appliances.
+
+Please see
+MS-SMB2 (for detailed SMB2/SMB3/SMB3.1.1 protocol specification)
+http://protocolfreedom.org/ and
+http://samba.org/samba/PFIF/
+for more details.
+
+
+For questions or bug reports please contact:
+
+ smfrench@gmail.com
+
+See the project page at: https://wiki.samba.org/index.php/LinuxCIFS_utils
+
+Build instructions
+==================
+
+For Linux:
+
+1) Download the kernel (e.g. from http://www.kernel.org)
+ and change directory into the top of the kernel directory tree
+ (e.g. /usr/src/linux-2.5.73)
+2) make menuconfig (or make xconfig)
+3) select cifs from within the network filesystem choices
+4) save and exit
+5) make
+
+
+Installation instructions
+=========================
+
+If you have built the CIFS vfs as module (successfully) simply
+type ``make modules_install`` (or if you prefer, manually copy the file to
+the modules directory e.g. /lib/modules/2.4.10-4GB/kernel/fs/cifs/cifs.ko).
+
+If you have built the CIFS vfs into the kernel itself, follow the instructions
+for your distribution on how to install a new kernel (usually you
+would simply type ``make install``).
+
+If you do not have the utility mount.cifs (in the Samba 4.x source tree and on
+the CIFS VFS web site) copy it to the same directory in which mount helpers
+reside (usually /sbin). Although the helper software is not
+required, mount.cifs is recommended. Most distros include a ``cifs-utils``
+package that includes this utility so it is recommended to install this.
+
+Note that running the Winbind pam/nss module (logon service) on all of your
+Linux clients is useful in mapping Uids and Gids consistently across the
+domain to the proper network user. The mount.cifs mount helper can be
+found at cifs-utils.git on git.samba.org
+
+If cifs is built as a module, then the size and number of network buffers
+and maximum number of simultaneous requests to one server can be configured.
+Changing these from their defaults is not recommended. By executing modinfo::
+
+ modinfo kernel/fs/cifs/cifs.ko
+
+on kernel/fs/cifs/cifs.ko the list of configuration changes that can be made
+at module initialization time (by running insmod cifs.ko) can be seen.
+
+Recommendations
+===============
+
+To improve security the SMB2.1 dialect or later (usually will get SMB3) is now
+the new default. To use old dialects (e.g. to mount Windows XP) use "vers=1.0"
+on mount (or vers=2.0 for Windows Vista). Note that the CIFS (vers=1.0) is
+much older and less secure than the default dialect SMB3 which includes
+many advanced security features such as downgrade attack detection
+and encrypted shares and stronger signing and authentication algorithms.
+There are additional mount options that may be helpful for SMB3 to get
+improved POSIX behavior (NB: can use vers=3.0 to force only SMB3, never 2.1):
+
+ ``mfsymlinks`` and ``cifsacl`` and ``idsfromsid``
+
+Allowing User Mounts
+====================
+
+To permit users to mount and unmount over directories they own is possible
+with the cifs vfs. A way to enable such mounting is to mark the mount.cifs
+utility as suid (e.g. ``chmod +s /sbin/mount.cifs``). To enable users to
+umount shares they mount requires
+
+1) mount.cifs version 1.4 or later
+2) an entry for the share in /etc/fstab indicating that a user may
+ unmount it e.g.::
+
+ //server/usersharename /mnt/username cifs user 0 0
+
+Note that when the mount.cifs utility is run suid (allowing user mounts),
+in order to reduce risks, the ``nosuid`` mount flag is passed in on mount to
+disallow execution of an suid program mounted on the remote target.
+When mount is executed as root, nosuid is not passed in by default,
+and execution of suid programs on the remote target would be enabled
+by default. This can be changed, as with nfs and other filesystems,
+by simply specifying ``nosuid`` among the mount options. For user mounts
+though to be able to pass the suid flag to mount requires rebuilding
+mount.cifs with the following flag: CIFS_ALLOW_USR_SUID
+
+There is a corresponding manual page for cifs mounting in the Samba 3.0 and
+later source tree in docs/manpages/mount.cifs.8
+
+Allowing User Unmounts
+======================
+
+To permit users to ummount directories that they have user mounted (see above),
+the utility umount.cifs may be used. It may be invoked directly, or if
+umount.cifs is placed in /sbin, umount can invoke the cifs umount helper
+(at least for most versions of the umount utility) for umount of cifs
+mounts, unless umount is invoked with -i (which will avoid invoking a umount
+helper). As with mount.cifs, to enable user unmounts umount.cifs must be marked
+as suid (e.g. ``chmod +s /sbin/umount.cifs``) or equivalent (some distributions
+allow adding entries to a file to the /etc/permissions file to achieve the
+equivalent suid effect). For this utility to succeed the target path
+must be a cifs mount, and the uid of the current user must match the uid
+of the user who mounted the resource.
+
+Also note that the customary way of allowing user mounts and unmounts is
+(instead of using mount.cifs and unmount.cifs as suid) to add a line
+to the file /etc/fstab for each //server/share you wish to mount, but
+this can become unwieldy when potential mount targets include many
+or unpredictable UNC names.
+
+Samba Considerations
+====================
+
+Most current servers support SMB2.1 and SMB3 which are more secure,
+but there are useful protocol extensions for the older less secure CIFS
+dialect, so to get the maximum benefit if mounting using the older dialect
+(CIFS/SMB1), we recommend using a server that supports the SNIA CIFS
+Unix Extensions standard (e.g. almost any version of Samba ie version
+2.2.5 or later) but the CIFS vfs works fine with a wide variety of CIFS servers.
+Note that uid, gid and file permissions will display default values if you do
+not have a server that supports the Unix extensions for CIFS (such as Samba
+2.2.5 or later). To enable the Unix CIFS Extensions in the Samba server, add
+the line::
+
+ unix extensions = yes
+
+to your smb.conf file on the server. Note that the following smb.conf settings
+are also useful (on the Samba server) when the majority of clients are Unix or
+Linux::
+
+ case sensitive = yes
+ delete readonly = yes
+ ea support = yes
+
+Note that server ea support is required for supporting xattrs from the Linux
+cifs client, and that EA support is present in later versions of Samba (e.g.
+3.0.6 and later (also EA support works in all versions of Windows, at least to
+shares on NTFS filesystems). Extended Attribute (xattr) support is an optional
+feature of most Linux filesystems which may require enabling via
+make menuconfig. Client support for extended attributes (user xattr) can be
+disabled on a per-mount basis by specifying ``nouser_xattr`` on mount.
+
+The CIFS client can get and set POSIX ACLs (getfacl, setfacl) to Samba servers
+version 3.10 and later. Setting POSIX ACLs requires enabling both XATTR and
+then POSIX support in the CIFS configuration options when building the cifs
+module. POSIX ACL support can be disabled on a per mount basic by specifying
+``noacl`` on mount.
+
+Some administrators may want to change Samba's smb.conf ``map archive`` and
+``create mask`` parameters from the default. Unless the create mask is changed
+newly created files can end up with an unnecessarily restrictive default mode,
+which may not be what you want, although if the CIFS Unix extensions are
+enabled on the server and client, subsequent setattr calls (e.g. chmod) can
+fix the mode. Note that creating special devices (mknod) remotely
+may require specifying a mkdev function to Samba if you are not using
+Samba 3.0.6 or later. For more information on these see the manual pages
+(``man smb.conf``) on the Samba server system. Note that the cifs vfs,
+unlike the smbfs vfs, does not read the smb.conf on the client system
+(the few optional settings are passed in on mount via -o parameters instead).
+Note that Samba 2.2.7 or later includes a fix that allows the CIFS VFS to delete
+open files (required for strict POSIX compliance). Windows Servers already
+supported this feature. Samba server does not allow symlinks that refer to files
+outside of the share, so in Samba versions prior to 3.0.6, most symlinks to
+files with absolute paths (ie beginning with slash) such as::
+
+ ln -s /mnt/foo bar
+
+would be forbidden. Samba 3.0.6 server or later includes the ability to create
+such symlinks safely by converting unsafe symlinks (ie symlinks to server
+files that are outside of the share) to a samba specific format on the server
+that is ignored by local server applications and non-cifs clients and that will
+not be traversed by the Samba server). This is opaque to the Linux client
+application using the cifs vfs. Absolute symlinks will work to Samba 3.0.5 or
+later, but only for remote clients using the CIFS Unix extensions, and will
+be invisbile to Windows clients and typically will not affect local
+applications running on the same server as Samba.
+
+Use instructions
+================
+
+Once the CIFS VFS support is built into the kernel or installed as a module
+(cifs.ko), you can use mount syntax like the following to access Samba or
+Mac or Windows servers::
+
+ mount -t cifs //9.53.216.11/e$ /mnt -o username=myname,password=mypassword
+
+Before -o the option -v may be specified to make the mount.cifs
+mount helper display the mount steps more verbosely.
+After -o the following commonly used cifs vfs specific options
+are supported::
+
+ username=<username>
+ password=<password>
+ domain=<domain name>
+
+Other cifs mount options are described below. Use of TCP names (in addition to
+ip addresses) is available if the mount helper (mount.cifs) is installed. If
+you do not trust the server to which are mounted, or if you do not have
+cifs signing enabled (and the physical network is insecure), consider use
+of the standard mount options ``noexec`` and ``nosuid`` to reduce the risk of
+running an altered binary on your local system (downloaded from a hostile server
+or altered by a hostile router).
+
+Although mounting using format corresponding to the CIFS URL specification is
+not possible in mount.cifs yet, it is possible to use an alternate format
+for the server and sharename (which is somewhat similar to NFS style mount
+syntax) instead of the more widely used UNC format (i.e. \\server\share)::
+
+ mount -t cifs tcp_name_of_server:share_name /mnt -o user=myname,pass=mypasswd
+
+When using the mount helper mount.cifs, passwords may be specified via alternate
+mechanisms, instead of specifying it after -o using the normal ``pass=`` syntax
+on the command line:
+1) By including it in a credential file. Specify credentials=filename as one
+of the mount options. Credential files contain two lines::
+
+ username=someuser
+ password=your_password
+
+2) By specifying the password in the PASSWD environment variable (similarly
+ the user name can be taken from the USER environment variable).
+3) By specifying the password in a file by name via PASSWD_FILE
+4) By specifying the password in a file by file descriptor via PASSWD_FD
+
+If no password is provided, mount.cifs will prompt for password entry
+
+Restrictions
+============
+
+Servers must support either "pure-TCP" (port 445 TCP/IP CIFS connections) or RFC
+1001/1002 support for "Netbios-Over-TCP/IP." This is not likely to be a
+problem as most servers support this.
+
+Valid filenames differ between Windows and Linux. Windows typically restricts
+filenames which contain certain reserved characters (e.g.the character :
+which is used to delimit the beginning of a stream name by Windows), while
+Linux allows a slightly wider set of valid characters in filenames. Windows
+servers can remap such characters when an explicit mapping is specified in
+the Server's registry. Samba starting with version 3.10 will allow such
+filenames (ie those which contain valid Linux characters, which normally
+would be forbidden for Windows/CIFS semantics) as long as the server is
+configured for Unix Extensions (and the client has not disabled
+/proc/fs/cifs/LinuxExtensionsEnabled). In addition the mount option
+``mapposix`` can be used on CIFS (vers=1.0) to force the mapping of
+illegal Windows/NTFS/SMB characters to a remap range (this mount parm
+is the default for SMB3). This remap (``mapposix``) range is also
+compatible with Mac (and "Services for Mac" on some older Windows).
+
+CIFS VFS Mount Options
+======================
+A partial list of the supported mount options follows:
+
+ username
+ The user name to use when trying to establish
+ the CIFS session.
+ password
+ The user password. If the mount helper is
+ installed, the user will be prompted for password
+ if not supplied.
+ ip
+ The ip address of the target server
+ unc
+ The target server Universal Network Name (export) to
+ mount.
+ domain
+ Set the SMB/CIFS workgroup name prepended to the
+ username during CIFS session establishment
+ forceuid
+ Set the default uid for inodes to the uid
+ passed in on mount. For mounts to servers
+ which do support the CIFS Unix extensions, such as a
+ properly configured Samba server, the server provides
+ the uid, gid and mode so this parameter should not be
+ specified unless the server and clients uid and gid
+ numbering differ. If the server and client are in the
+ same domain (e.g. running winbind or nss_ldap) and
+ the server supports the Unix Extensions then the uid
+ and gid can be retrieved from the server (and uid
+ and gid would not have to be specified on the mount.
+ For servers which do not support the CIFS Unix
+ extensions, the default uid (and gid) returned on lookup
+ of existing files will be the uid (gid) of the person
+ who executed the mount (root, except when mount.cifs
+ is configured setuid for user mounts) unless the ``uid=``
+ (gid) mount option is specified. Also note that permission
+ checks (authorization checks) on accesses to a file occur
+ at the server, but there are cases in which an administrator
+ may want to restrict at the client as well. For those
+ servers which do not report a uid/gid owner
+ (such as Windows), permissions can also be checked at the
+ client, and a crude form of client side permission checking
+ can be enabled by specifying file_mode and dir_mode on
+ the client. (default)
+ forcegid
+ (similar to above but for the groupid instead of uid) (default)
+ noforceuid
+ Fill in file owner information (uid) by requesting it from
+ the server if possible. With this option, the value given in
+ the uid= option (on mount) will only be used if the server
+ can not support returning uids on inodes.
+ noforcegid
+ (similar to above but for the group owner, gid, instead of uid)
+ uid
+ Set the default uid for inodes, and indicate to the
+ cifs kernel driver which local user mounted. If the server
+ supports the unix extensions the default uid is
+ not used to fill in the owner fields of inodes (files)
+ unless the ``forceuid`` parameter is specified.
+ gid
+ Set the default gid for inodes (similar to above).
+ file_mode
+ If CIFS Unix extensions are not supported by the server
+ this overrides the default mode for file inodes.
+ fsc
+ Enable local disk caching using FS-Cache (off by default). This
+ option could be useful to improve performance on a slow link,
+ heavily loaded server and/or network where reading from the
+ disk is faster than reading from the server (over the network).
+ This could also impact scalability positively as the
+ number of calls to the server are reduced. However, local
+ caching is not suitable for all workloads for e.g. read-once
+ type workloads. So, you need to consider carefully your
+ workload/scenario before using this option. Currently, local
+ disk caching is functional for CIFS files opened as read-only.
+ dir_mode
+ If CIFS Unix extensions are not supported by the server
+ this overrides the default mode for directory inodes.
+ port
+ attempt to contact the server on this tcp port, before
+ trying the usual ports (port 445, then 139).
+ iocharset
+ Codepage used to convert local path names to and from
+ Unicode. Unicode is used by default for network path
+ names if the server supports it. If iocharset is
+ not specified then the nls_default specified
+ during the local client kernel build will be used.
+ If server does not support Unicode, this parameter is
+ unused.
+ rsize
+ default read size (usually 16K). The client currently
+ can not use rsize larger than CIFSMaxBufSize. CIFSMaxBufSize
+ defaults to 16K and may be changed (from 8K to the maximum
+ kmalloc size allowed by your kernel) at module install time
+ for cifs.ko. Setting CIFSMaxBufSize to a very large value
+ will cause cifs to use more memory and may reduce performance
+ in some cases. To use rsize greater than 127K (the original
+ cifs protocol maximum) also requires that the server support
+ a new Unix Capability flag (for very large read) which some
+ newer servers (e.g. Samba 3.0.26 or later) do. rsize can be
+ set from a minimum of 2048 to a maximum of 130048 (127K or
+ CIFSMaxBufSize, whichever is smaller)
+ wsize
+ default write size (default 57344)
+ maximum wsize currently allowed by CIFS is 57344 (fourteen
+ 4096 byte pages)
+ actimeo=n
+ attribute cache timeout in seconds (default 1 second).
+ After this timeout, the cifs client requests fresh attribute
+ information from the server. This option allows to tune the
+ attribute cache timeout to suit the workload needs. Shorter
+ timeouts mean better the cache coherency, but increased number
+ of calls to the server. Longer timeouts mean reduced number
+ of calls to the server at the expense of less stricter cache
+ coherency checks (i.e. incorrect attribute cache for a short
+ period of time).
+ rw
+ mount the network share read-write (note that the
+ server may still consider the share read-only)
+ ro
+ mount network share read-only
+ version
+ used to distinguish different versions of the
+ mount helper utility (not typically needed)
+ sep
+ if first mount option (after the -o), overrides
+ the comma as the separator between the mount
+ parms. e.g.::
+
+ -o user=myname,password=mypassword,domain=mydom
+
+ could be passed instead with period as the separator by::
+
+ -o sep=.user=myname.password=mypassword.domain=mydom
+
+ this might be useful when comma is contained within username
+ or password or domain. This option is less important
+ when the cifs mount helper cifs.mount (version 1.1 or later)
+ is used.
+ nosuid
+ Do not allow remote executables with the suid bit
+ program to be executed. This is only meaningful for mounts
+ to servers such as Samba which support the CIFS Unix Extensions.
+ If you do not trust the servers in your network (your mount
+ targets) it is recommended that you specify this option for
+ greater security.
+ exec
+ Permit execution of binaries on the mount.
+ noexec
+ Do not permit execution of binaries on the mount.
+ dev
+ Recognize block devices on the remote mount.
+ nodev
+ Do not recognize devices on the remote mount.
+ suid
+ Allow remote files on this mountpoint with suid enabled to
+ be executed (default for mounts when executed as root,
+ nosuid is default for user mounts).
+ credentials
+ Although ignored by the cifs kernel component, it is used by
+ the mount helper, mount.cifs. When mount.cifs is installed it
+ opens and reads the credential file specified in order
+ to obtain the userid and password arguments which are passed to
+ the cifs vfs.
+ guest
+ Although ignored by the kernel component, the mount.cifs
+ mount helper will not prompt the user for a password
+ if guest is specified on the mount options. If no
+ password is specified a null password will be used.
+ perm
+ Client does permission checks (vfs_permission check of uid
+ and gid of the file against the mode and desired operation),
+ Note that this is in addition to the normal ACL check on the
+ target machine done by the server software.
+ Client permission checking is enabled by default.
+ noperm
+ Client does not do permission checks. This can expose
+ files on this mount to access by other users on the local
+ client system. It is typically only needed when the server
+ supports the CIFS Unix Extensions but the UIDs/GIDs on the
+ client and server system do not match closely enough to allow
+ access by the user doing the mount, but it may be useful with
+ non CIFS Unix Extension mounts for cases in which the default
+ mode is specified on the mount but is not to be enforced on the
+ client (e.g. perhaps when MultiUserMount is enabled)
+ Note that this does not affect the normal ACL check on the
+ target machine done by the server software (of the server
+ ACL against the user name provided at mount time).
+ serverino
+ Use server's inode numbers instead of generating automatically
+ incrementing inode numbers on the client. Although this will
+ make it easier to spot hardlinked files (as they will have
+ the same inode numbers) and inode numbers may be persistent,
+ note that the server does not guarantee that the inode numbers
+ are unique if multiple server side mounts are exported under a
+ single share (since inode numbers on the servers might not
+ be unique if multiple filesystems are mounted under the same
+ shared higher level directory). Note that some older
+ (e.g. pre-Windows 2000) do not support returning UniqueIDs
+ or the CIFS Unix Extensions equivalent and for those
+ this mount option will have no effect. Exporting cifs mounts
+ under nfsd requires this mount option on the cifs mount.
+ This is now the default if server supports the
+ required network operation.
+ noserverino
+ Client generates inode numbers (rather than using the actual one
+ from the server). These inode numbers will vary after
+ unmount or reboot which can confuse some applications,
+ but not all server filesystems support unique inode
+ numbers.
+ setuids
+ If the CIFS Unix extensions are negotiated with the server
+ the client will attempt to set the effective uid and gid of
+ the local process on newly created files, directories, and
+ devices (create, mkdir, mknod). If the CIFS Unix Extensions
+ are not negotiated, for newly created files and directories
+ instead of using the default uid and gid specified on
+ the mount, cache the new file's uid and gid locally which means
+ that the uid for the file can change when the inode is
+ reloaded (or the user remounts the share).
+ nosetuids
+ The client will not attempt to set the uid and gid on
+ on newly created files, directories, and devices (create,
+ mkdir, mknod) which will result in the server setting the
+ uid and gid to the default (usually the server uid of the
+ user who mounted the share). Letting the server (rather than
+ the client) set the uid and gid is the default. If the CIFS
+ Unix Extensions are not negotiated then the uid and gid for
+ new files will appear to be the uid (gid) of the mounter or the
+ uid (gid) parameter specified on the mount.
+ netbiosname
+ When mounting to servers via port 139, specifies the RFC1001
+ source name to use to represent the client netbios machine
+ name when doing the RFC1001 netbios session initialize.
+ direct
+ Do not do inode data caching on files opened on this mount.
+ This precludes mmapping files on this mount. In some cases
+ with fast networks and little or no caching benefits on the
+ client (e.g. when the application is doing large sequential
+ reads bigger than page size without rereading the same data)
+ this can provide better performance than the default
+ behavior which caches reads (readahead) and writes
+ (writebehind) through the local Linux client pagecache
+ if oplock (caching token) is granted and held. Note that
+ direct allows write operations larger than page size
+ to be sent to the server.
+ strictcache
+ Use for switching on strict cache mode. In this mode the
+ client read from the cache all the time it has Oplock Level II,
+ otherwise - read from the server. All written data are stored
+ in the cache, but if the client doesn't have Exclusive Oplock,
+ it writes the data to the server.
+ rwpidforward
+ Forward pid of a process who opened a file to any read or write
+ operation on that file. This prevent applications like WINE
+ from failing on read and write if we use mandatory brlock style.
+ acl
+ Allow setfacl and getfacl to manage posix ACLs if server
+ supports them. (default)
+ noacl
+ Do not allow setfacl and getfacl calls on this mount
+ user_xattr
+ Allow getting and setting user xattrs (those attributes whose
+ name begins with ``user.`` or ``os2.``) as OS/2 EAs (extended
+ attributes) to the server. This allows support of the
+ setfattr and getfattr utilities. (default)
+ nouser_xattr
+ Do not allow getfattr/setfattr to get/set/list xattrs
+ mapchars
+ Translate six of the seven reserved characters (not backslash)::
+
+ *?<>|:
+
+ to the remap range (above 0xF000), which also
+ allows the CIFS client to recognize files created with
+ such characters by Windows's POSIX emulation. This can
+ also be useful when mounting to most versions of Samba
+ (which also forbids creating and opening files
+ whose names contain any of these seven characters).
+ This has no effect if the server does not support
+ Unicode on the wire.
+ nomapchars
+ Do not translate any of these seven characters (default).
+ nocase
+ Request case insensitive path name matching (case
+ sensitive is the default if the server supports it).
+ (mount option ``ignorecase`` is identical to ``nocase``)
+ posixpaths
+ If CIFS Unix extensions are supported, attempt to
+ negotiate posix path name support which allows certain
+ characters forbidden in typical CIFS filenames, without
+ requiring remapping. (default)
+ noposixpaths
+ If CIFS Unix extensions are supported, do not request
+ posix path name support (this may cause servers to
+ reject creatingfile with certain reserved characters).
+ nounix
+ Disable the CIFS Unix Extensions for this mount (tree
+ connection). This is rarely needed, but it may be useful
+ in order to turn off multiple settings all at once (ie
+ posix acls, posix locks, posix paths, symlink support
+ and retrieving uids/gids/mode from the server) or to
+ work around a bug in server which implement the Unix
+ Extensions.
+ nobrl
+ Do not send byte range lock requests to the server.
+ This is necessary for certain applications that break
+ with cifs style mandatory byte range locks (and most
+ cifs servers do not yet support requesting advisory
+ byte range locks).
+ forcemandatorylock
+ Even if the server supports posix (advisory) byte range
+ locking, send only mandatory lock requests. For some
+ (presumably rare) applications, originally coded for
+ DOS/Windows, which require Windows style mandatory byte range
+ locking, they may be able to take advantage of this option,
+ forcing the cifs client to only send mandatory locks
+ even if the cifs server would support posix advisory locks.
+ ``forcemand`` is accepted as a shorter form of this mount
+ option.
+ nostrictsync
+ If this mount option is set, when an application does an
+ fsync call then the cifs client does not send an SMB Flush
+ to the server (to force the server to write all dirty data
+ for this file immediately to disk), although cifs still sends
+ all dirty (cached) file data to the server and waits for the
+ server to respond to the write. Since SMB Flush can be
+ very slow, and some servers may be reliable enough (to risk
+ delaying slightly flushing the data to disk on the server),
+ turning on this option may be useful to improve performance for
+ applications that fsync too much, at a small risk of server
+ crash. If this mount option is not set, by default cifs will
+ send an SMB flush request (and wait for a response) on every
+ fsync call.
+ nodfs
+ Disable DFS (global name space support) even if the
+ server claims to support it. This can help work around
+ a problem with parsing of DFS paths with Samba server
+ versions 3.0.24 and 3.0.25.
+ remount
+ remount the share (often used to change from ro to rw mounts
+ or vice versa)
+ cifsacl
+ Report mode bits (e.g. on stat) based on the Windows ACL for
+ the file. (EXPERIMENTAL)
+ servern
+ Specify the server 's netbios name (RFC1001 name) to use
+ when attempting to setup a session to the server.
+ This is needed for mounting to some older servers (such
+ as OS/2 or Windows 98 and Windows ME) since they do not
+ support a default server name. A server name can be up
+ to 15 characters long and is usually uppercased.
+ sfu
+ When the CIFS Unix Extensions are not negotiated, attempt to
+ create device files and fifos in a format compatible with
+ Services for Unix (SFU). In addition retrieve bits 10-12
+ of the mode via the SETFILEBITS extended attribute (as
+ SFU does). In the future the bottom 9 bits of the
+ mode also will be emulated using queries of the security
+ descriptor (ACL).
+ mfsymlinks
+ Enable support for Minshall+French symlinks
+ (see http://wiki.samba.org/index.php/UNIX_Extensions#Minshall.2BFrench_symlinks)
+ This option is ignored when specified together with the
+ 'sfu' option. Minshall+French symlinks are used even if
+ the server supports the CIFS Unix Extensions.
+ sign
+ Must use packet signing (helps avoid unwanted data modification
+ by intermediate systems in the route). Note that signing
+ does not work with lanman or plaintext authentication.
+ seal
+ Must seal (encrypt) all data on this mounted share before
+ sending on the network. Requires support for Unix Extensions.
+ Note that this differs from the sign mount option in that it
+ causes encryption of data sent over this mounted share but other
+ shares mounted to the same server are unaffected.
+ locallease
+ This option is rarely needed. Fcntl F_SETLEASE is
+ used by some applications such as Samba and NFSv4 server to
+ check to see whether a file is cacheable. CIFS has no way
+ to explicitly request a lease, but can check whether a file
+ is cacheable (oplocked). Unfortunately, even if a file
+ is not oplocked, it could still be cacheable (ie cifs client
+ could grant fcntl leases if no other local processes are using
+ the file) for cases for example such as when the server does not
+ support oplocks and the user is sure that the only updates to
+ the file will be from this client. Specifying this mount option
+ will allow the cifs client to check for leases (only) locally
+ for files which are not oplocked instead of denying leases
+ in that case. (EXPERIMENTAL)
+ sec
+ Security mode. Allowed values are:
+
+ none
+ attempt to connection as a null user (no name)
+ krb5
+ Use Kerberos version 5 authentication
+ krb5i
+ Use Kerberos authentication and packet signing
+ ntlm
+ Use NTLM password hashing (default)
+ ntlmi
+ Use NTLM password hashing with signing (if
+ /proc/fs/cifs/PacketSigningEnabled on or if
+ server requires signing also can be the default)
+ ntlmv2
+ Use NTLMv2 password hashing
+ ntlmv2i
+ Use NTLMv2 password hashing with packet signing
+ lanman
+ (if configured in kernel config) use older
+ lanman hash
+ hard
+ Retry file operations if server is not responding
+ soft
+ Limit retries to unresponsive servers (usually only
+ one retry) before returning an error. (default)
+
+The mount.cifs mount helper also accepts a few mount options before -o
+including:
+
+=============== ===============================================================
+ -S take password from stdin (equivalent to setting the environment
+ variable ``PASSWD_FD=0``
+ -V print mount.cifs version
+ -? display simple usage information
+=============== ===============================================================
+
+With most 2.6 kernel versions of modutils, the version of the cifs kernel
+module can be displayed via modinfo.
+
+Misc /proc/fs/cifs Flags and Debug Info
+=======================================
+
+Informational pseudo-files:
+
+======================= =======================================================
+DebugData Displays information about active CIFS sessions and
+ shares, features enabled as well as the cifs.ko
+ version.
+Stats Lists summary resource usage information as well as per
+ share statistics.
+======================= =======================================================
+
+Configuration pseudo-files:
+
+======================= =======================================================
+SecurityFlags Flags which control security negotiation and
+ also packet signing. Authentication (may/must)
+ flags (e.g. for NTLM and/or NTLMv2) may be combined with
+ the signing flags. Specifying two different password
+ hashing mechanisms (as "must use") on the other hand
+ does not make much sense. Default flags are::
+
+ 0x07007
+
+ (NTLM, NTLMv2 and packet signing allowed). The maximum
+ allowable flags if you want to allow mounts to servers
+ using weaker password hashes is 0x37037 (lanman,
+ plaintext, ntlm, ntlmv2, signing allowed). Some
+ SecurityFlags require the corresponding menuconfig
+ options to be enabled (lanman and plaintext require
+ CONFIG_CIFS_WEAK_PW_HASH for example). Enabling
+ plaintext authentication currently requires also
+ enabling lanman authentication in the security flags
+ because the cifs module only supports sending
+ laintext passwords using the older lanman dialect
+ form of the session setup SMB. (e.g. for authentication
+ using plain text passwords, set the SecurityFlags
+ to 0x30030)::
+
+ may use packet signing 0x00001
+ must use packet signing 0x01001
+ may use NTLM (most common password hash) 0x00002
+ must use NTLM 0x02002
+ may use NTLMv2 0x00004
+ must use NTLMv2 0x04004
+ may use Kerberos security 0x00008
+ must use Kerberos 0x08008
+ may use lanman (weak) password hash 0x00010
+ must use lanman password hash 0x10010
+ may use plaintext passwords 0x00020
+ must use plaintext passwords 0x20020
+ (reserved for future packet encryption) 0x00040
+
+cifsFYI If set to non-zero value, additional debug information
+ will be logged to the system error log. This field
+ contains three flags controlling different classes of
+ debugging entries. The maximum value it can be set
+ to is 7 which enables all debugging points (default 0).
+ Some debugging statements are not compiled into the
+ cifs kernel unless CONFIG_CIFS_DEBUG2 is enabled in the
+ kernel configuration. cifsFYI may be set to one or
+ nore of the following flags (7 sets them all)::
+
+ +-----------------------------------------------+------+
+ | log cifs informational messages | 0x01 |
+ +-----------------------------------------------+------+
+ | log return codes from cifs entry points | 0x02 |
+ +-----------------------------------------------+------+
+ | log slow responses | 0x04 |
+ | (ie which take longer than 1 second) | |
+ | | |
+ | CONFIG_CIFS_STATS2 must be enabled in .config | |
+ +-----------------------------------------------+------+
+
+traceSMB If set to one, debug information is logged to the
+ system error log with the start of smb requests
+ and responses (default 0)
+LookupCacheEnable If set to one, inode information is kept cached
+ for one second improving performance of lookups
+ (default 1)
+LinuxExtensionsEnabled If set to one then the client will attempt to
+ use the CIFS "UNIX" extensions which are optional
+ protocol enhancements that allow CIFS servers
+ to return accurate UID/GID information as well
+ as support symbolic links. If you use servers
+ such as Samba that support the CIFS Unix
+ extensions but do not want to use symbolic link
+ support and want to map the uid and gid fields
+ to values supplied at mount (rather than the
+ actual values, then set this to zero. (default 1)
+======================= =======================================================
+
+These experimental features and tracing can be enabled by changing flags in
+/proc/fs/cifs (after the cifs module has been installed or built into the
+kernel, e.g. insmod cifs). To enable a feature set it to 1 e.g. to enable
+tracing to the kernel message log type::
+
+ echo 7 > /proc/fs/cifs/cifsFYI
+
+cifsFYI functions as a bit mask. Setting it to 1 enables additional kernel
+logging of various informational messages. 2 enables logging of non-zero
+SMB return codes while 4 enables logging of requests that take longer
+than one second to complete (except for byte range lock requests).
+Setting it to 4 requires CONFIG_CIFS_STATS2 to be set in kernel configuration
+(.config). Setting it to seven enables all three. Finally, tracing
+the start of smb requests and responses can be enabled via::
+
+ echo 1 > /proc/fs/cifs/traceSMB
+
+Per share (per client mount) statistics are available in /proc/fs/cifs/Stats.
+Additional information is available if CONFIG_CIFS_STATS2 is enabled in the
+kernel configuration (.config). The statistics returned include counters which
+represent the number of attempted and failed (ie non-zero return code from the
+server) SMB3 (or cifs) requests grouped by request type (read, write, close etc.).
+Also recorded is the total bytes read and bytes written to the server for
+that share. Note that due to client caching effects this can be less than the
+number of bytes read and written by the application running on the client.
+Statistics can be reset to zero by ``echo 0 > /proc/fs/cifs/Stats`` which may be
+useful if comparing performance of two different scenarios.
+
+Also note that ``cat /proc/fs/cifs/DebugData`` will display information about
+the active sessions and the shares that are mounted.
+
+Enabling Kerberos (extended security) works but requires version 1.2 or later
+of the helper program cifs.upcall to be present and to be configured in the
+/etc/request-key.conf file. The cifs.upcall helper program is from the Samba
+project(http://www.samba.org). NTLM and NTLMv2 and LANMAN support do not
+require this helper. Note that NTLMv2 security (which does not require the
+cifs.upcall helper program), instead of using Kerberos, is sufficient for
+some use cases.
+
+DFS support allows transparent redirection to shares in an MS-DFS name space.
+In addition, DFS support for target shares which are specified as UNC
+names which begin with host names (rather than IP addresses) requires
+a user space helper (such as cifs.upcall) to be present in order to
+translate host names to ip address, and the user space helper must also
+be configured in the file /etc/request-key.conf. Samba, Windows servers and
+many NAS appliances support DFS as a way of constructing a global name
+space to ease network configuration and improve reliability.
+
+To use cifs Kerberos and DFS support, the Linux keyutils package should be
+installed and something like the following lines should be added to the
+/etc/request-key.conf file::
+
+ create cifs.spnego * * /usr/local/sbin/cifs.upcall %k
+ create dns_resolver * * /usr/local/sbin/cifs.upcall %k
+
+CIFS kernel module parameters
+=============================
+These module parameters can be specified or modified either during the time of
+module loading or during the runtime by using the interface::
+
+ /proc/module/cifs/parameters/<param>
+
+i.e.::
+
+ echo "value" > /sys/module/cifs/parameters/<param>
+
+================= ==========================================================
+1. enable_oplocks Enable or disable oplocks. Oplocks are enabled by default.
+ [Y/y/1]. To disable use any of [N/n/0].
+================= ==========================================================
diff --git a/Documentation/filesystems/cifs/winucase_convert.pl b/Documentation/admin-guide/cifs/winucase_convert.pl
similarity index 100%
rename from Documentation/filesystems/cifs/winucase_convert.pl
rename to Documentation/admin-guide/cifs/winucase_convert.pl
diff --git a/Documentation/admin-guide/device-mapper/dm-clone.rst b/Documentation/admin-guide/device-mapper/dm-clone.rst
new file mode 100644
index 0000000..b43a34c
--- /dev/null
+++ b/Documentation/admin-guide/device-mapper/dm-clone.rst
@@ -0,0 +1,333 @@
+.. SPDX-License-Identifier: GPL-2.0-only
+
+========
+dm-clone
+========
+
+Introduction
+============
+
+dm-clone is a device mapper target which produces a one-to-one copy of an
+existing, read-only source device into a writable destination device: It
+presents a virtual block device which makes all data appear immediately, and
+redirects reads and writes accordingly.
+
+The main use case of dm-clone is to clone a potentially remote, high-latency,
+read-only, archival-type block device into a writable, fast, primary-type device
+for fast, low-latency I/O. The cloned device is visible/mountable immediately
+and the copy of the source device to the destination device happens in the
+background, in parallel with user I/O.
+
+For example, one could restore an application backup from a read-only copy,
+accessible through a network storage protocol (NBD, Fibre Channel, iSCSI, AoE,
+etc.), into a local SSD or NVMe device, and start using the device immediately,
+without waiting for the restore to complete.
+
+When the cloning completes, the dm-clone table can be removed altogether and be
+replaced, e.g., by a linear table, mapping directly to the destination device.
+
+The dm-clone target reuses the metadata library used by the thin-provisioning
+target.
+
+Glossary
+========
+
+ Hydration
+ The process of filling a region of the destination device with data from
+ the same region of the source device, i.e., copying the region from the
+ source to the destination device.
+
+Once a region gets hydrated we redirect all I/O regarding it to the destination
+device.
+
+Design
+======
+
+Sub-devices
+-----------
+
+The target is constructed by passing three devices to it (along with other
+parameters detailed later):
+
+1. A source device - the read-only device that gets cloned and source of the
+ hydration.
+
+2. A destination device - the destination of the hydration, which will become a
+ clone of the source device.
+
+3. A small metadata device - it records which regions are already valid in the
+ destination device, i.e., which regions have already been hydrated, or have
+ been written to directly, via user I/O.
+
+The size of the destination device must be at least equal to the size of the
+source device.
+
+Regions
+-------
+
+dm-clone divides the source and destination devices in fixed sized regions.
+Regions are the unit of hydration, i.e., the minimum amount of data copied from
+the source to the destination device.
+
+The region size is configurable when you first create the dm-clone device. The
+recommended region size is the same as the file system block size, which usually
+is 4KB. The region size must be between 8 sectors (4KB) and 2097152 sectors
+(1GB) and a power of two.
+
+Reads and writes from/to hydrated regions are serviced from the destination
+device.
+
+A read to a not yet hydrated region is serviced directly from the source device.
+
+A write to a not yet hydrated region will be delayed until the corresponding
+region has been hydrated and the hydration of the region starts immediately.
+
+Note that a write request with size equal to region size will skip copying of
+the corresponding region from the source device and overwrite the region of the
+destination device directly.
+
+Discards
+--------
+
+dm-clone interprets a discard request to a range that hasn't been hydrated yet
+as a hint to skip hydration of the regions covered by the request, i.e., it
+skips copying the region's data from the source to the destination device, and
+only updates its metadata.
+
+If the destination device supports discards, then by default dm-clone will pass
+down discard requests to it.
+
+Background Hydration
+--------------------
+
+dm-clone copies continuously from the source to the destination device, until
+all of the device has been copied.
+
+Copying data from the source to the destination device uses bandwidth. The user
+can set a throttle to prevent more than a certain amount of copying occurring at
+any one time. Moreover, dm-clone takes into account user I/O traffic going to
+the devices and pauses the background hydration when there is I/O in-flight.
+
+A message `hydration_threshold <#regions>` can be used to set the maximum number
+of regions being copied, the default being 1 region.
+
+dm-clone employs dm-kcopyd for copying portions of the source device to the
+destination device. By default, we issue copy requests of size equal to the
+region size. A message `hydration_batch_size <#regions>` can be used to tune the
+size of these copy requests. Increasing the hydration batch size results in
+dm-clone trying to batch together contiguous regions, so we copy the data in
+batches of this many regions.
+
+When the hydration of the destination device finishes, a dm event will be sent
+to user space.
+
+Updating on-disk metadata
+-------------------------
+
+On-disk metadata is committed every time a FLUSH or FUA bio is written. If no
+such requests are made then commits will occur every second. This means the
+dm-clone device behaves like a physical disk that has a volatile write cache. If
+power is lost you may lose some recent writes. The metadata should always be
+consistent in spite of any crash.
+
+Target Interface
+================
+
+Constructor
+-----------
+
+ ::
+
+ clone <metadata dev> <destination dev> <source dev> <region size>
+ [<#feature args> [<feature arg>]* [<#core args> [<core arg>]*]]
+
+ ================ ==============================================================
+ metadata dev Fast device holding the persistent metadata
+ destination dev The destination device, where the source will be cloned
+ source dev Read only device containing the data that gets cloned
+ region size The size of a region in sectors
+
+ #feature args Number of feature arguments passed
+ feature args no_hydration or no_discard_passdown
+
+ #core args An even number of arguments corresponding to key/value pairs
+ passed to dm-clone
+ core args Key/value pairs passed to dm-clone, e.g. `hydration_threshold
+ 256`
+ ================ ==============================================================
+
+Optional feature arguments are:
+
+ ==================== =========================================================
+ no_hydration Create a dm-clone instance with background hydration
+ disabled
+ no_discard_passdown Disable passing down discards to the destination device
+ ==================== =========================================================
+
+Optional core arguments are:
+
+ ================================ ==============================================
+ hydration_threshold <#regions> Maximum number of regions being copied from
+ the source to the destination device at any
+ one time, during background hydration.
+ hydration_batch_size <#regions> During background hydration, try to batch
+ together contiguous regions, so we copy data
+ from the source to the destination device in
+ batches of this many regions.
+ ================================ ==============================================
+
+Status
+------
+
+ ::
+
+ <metadata block size> <#used metadata blocks>/<#total metadata blocks>
+ <region size> <#hydrated regions>/<#total regions> <#hydrating regions>
+ <#feature args> <feature args>* <#core args> <core args>*
+ <clone metadata mode>
+
+ ======================= =======================================================
+ metadata block size Fixed block size for each metadata block in sectors
+ #used metadata blocks Number of metadata blocks used
+ #total metadata blocks Total number of metadata blocks
+ region size Configurable region size for the device in sectors
+ #hydrated regions Number of regions that have finished hydrating
+ #total regions Total number of regions to hydrate
+ #hydrating regions Number of regions currently hydrating
+ #feature args Number of feature arguments to follow
+ feature args Feature arguments, e.g. `no_hydration`
+ #core args Even number of core arguments to follow
+ core args Key/value pairs for tuning the core, e.g.
+ `hydration_threshold 256`
+ clone metadata mode ro if read-only, rw if read-write
+
+ In serious cases where even a read-only mode is deemed
+ unsafe no further I/O will be permitted and the status
+ will just contain the string 'Fail'. If the metadata
+ mode changes, a dm event will be sent to user space.
+ ======================= =======================================================
+
+Messages
+--------
+
+ `disable_hydration`
+ Disable the background hydration of the destination device.
+
+ `enable_hydration`
+ Enable the background hydration of the destination device.
+
+ `hydration_threshold <#regions>`
+ Set background hydration threshold.
+
+ `hydration_batch_size <#regions>`
+ Set background hydration batch size.
+
+Examples
+========
+
+Clone a device containing a file system
+---------------------------------------
+
+1. Create the dm-clone device.
+
+ ::
+
+ dmsetup create clone --table "0 1048576000 clone $metadata_dev $dest_dev \
+ $source_dev 8 1 no_hydration"
+
+2. Mount the device and trim the file system. dm-clone interprets the discards
+ sent by the file system and it will not hydrate the unused space.
+
+ ::
+
+ mount /dev/mapper/clone /mnt/cloned-fs
+ fstrim /mnt/cloned-fs
+
+3. Enable background hydration of the destination device.
+
+ ::
+
+ dmsetup message clone 0 enable_hydration
+
+4. When the hydration finishes, we can replace the dm-clone table with a linear
+ table.
+
+ ::
+
+ dmsetup suspend clone
+ dmsetup load clone --table "0 1048576000 linear $dest_dev 0"
+ dmsetup resume clone
+
+ The metadata device is no longer needed and can be safely discarded or reused
+ for other purposes.
+
+Known issues
+============
+
+1. We redirect reads, to not-yet-hydrated regions, to the source device. If
+ reading the source device has high latency and the user repeatedly reads from
+ the same regions, this behaviour could degrade performance. We should use
+ these reads as hints to hydrate the relevant regions sooner. Currently, we
+ rely on the page cache to cache these regions, so we hopefully don't end up
+ reading them multiple times from the source device.
+
+2. Release in-core resources, i.e., the bitmaps tracking which regions are
+ hydrated, after the hydration has finished.
+
+3. During background hydration, if we fail to read the source or write to the
+ destination device, we print an error message, but the hydration process
+ continues indefinitely, until it succeeds. We should stop the background
+ hydration after a number of failures and emit a dm event for user space to
+ notice.
+
+Why not...?
+===========
+
+We explored the following alternatives before implementing dm-clone:
+
+1. Use dm-cache with cache size equal to the source device and implement a new
+ cloning policy:
+
+ * The resulting cache device is not a one-to-one mirror of the source device
+ and thus we cannot remove the cache device once cloning completes.
+
+ * dm-cache writes to the source device, which violates our requirement that
+ the source device must be treated as read-only.
+
+ * Caching is semantically different from cloning.
+
+2. Use dm-snapshot with a COW device equal to the source device:
+
+ * dm-snapshot stores its metadata in the COW device, so the resulting device
+ is not a one-to-one mirror of the source device.
+
+ * No background copying mechanism.
+
+ * dm-snapshot needs to commit its metadata whenever a pending exception
+ completes, to ensure snapshot consistency. In the case of cloning, we don't
+ need to be so strict and can rely on committing metadata every time a FLUSH
+ or FUA bio is written, or periodically, like dm-thin and dm-cache do. This
+ improves the performance significantly.
+
+3. Use dm-mirror: The mirror target has a background copying/mirroring
+ mechanism, but it writes to all mirrors, thus violating our requirement that
+ the source device must be treated as read-only.
+
+4. Use dm-thin's external snapshot functionality. This approach is the most
+ promising among all alternatives, as the thinly-provisioned volume is a
+ one-to-one mirror of the source device and handles reads and writes to
+ un-provisioned/not-yet-cloned areas the same way as dm-clone does.
+
+ Still:
+
+ * There is no background copying mechanism, though one could be implemented.
+
+ * Most importantly, we want to support arbitrary block devices as the
+ destination of the cloning process and not restrict ourselves to
+ thinly-provisioned volumes. Thin-provisioning has an inherent metadata
+ overhead, for maintaining the thin volume mappings, which significantly
+ degrades performance.
+
+ Moreover, cloning a device shouldn't force the use of thin-provisioning. On
+ the other hand, if we wish to use thin provisioning, we can just use a thin
+ LV as dm-clone's destination device.
diff --git a/Documentation/admin-guide/device-mapper/verity.rst b/Documentation/admin-guide/device-mapper/verity.rst
index a4d1c14..bb02caa 100644
--- a/Documentation/admin-guide/device-mapper/verity.rst
+++ b/Documentation/admin-guide/device-mapper/verity.rst
@@ -125,6 +125,13 @@
blocks, and a hash block will not be verified any more after all the data
blocks it covers have been verified anyway.
+root_hash_sig_key_desc <key_description>
+ This is the description of the USER_KEY that the kernel will lookup to get
+ the pkcs7 signature of the roothash. The pkcs7 signature is used to validate
+ the root hash during the creation of the device mapper block device.
+ Verification of roothash depends on the config DM_VERITY_VERIFY_ROOTHASH_SIG
+ being set in the kernel.
+
Theory of operation
===================
diff --git a/Documentation/admin-guide/devices.txt b/Documentation/admin-guide/devices.txt
index e56e006..1c5d228 100644
--- a/Documentation/admin-guide/devices.txt
+++ b/Documentation/admin-guide/devices.txt
@@ -1647,8 +1647,17 @@
0 = /dev/comedi0 First comedi device
1 = /dev/comedi1 Second comedi device
...
+ 47 = /dev/comedi47 48th comedi device
- See http://stm.lbl.gov/comedi.
+ Minors 48 to 255 are reserved for comedi subdevices with
+ pathnames of the form "/dev/comediX_subdY", where "X" is the
+ minor number of the associated comedi device and "Y" is the
+ subdevice number. These subdevice minors are assigned
+ dynamically, so there is no fixed mapping from subdevice
+ pathnames to minor numbers.
+
+ See http://www.comedi.org/ for information about the Comedi
+ project.
98 block User-mode virtual block device
0 = /dev/ubda First user-mode block device
diff --git a/Documentation/admin-guide/index.rst b/Documentation/admin-guide/index.rst
index 33feab2..34cc20e 100644
--- a/Documentation/admin-guide/index.rst
+++ b/Documentation/admin-guide/index.rst
@@ -77,7 +77,10 @@
blockdev/index
ext4
binderfs
+ cifs/index
xfs
+ jfs
+ ufs
pm/index
thunderbolt
LSM/index
@@ -98,6 +101,7 @@
iostats
kernel-per-CPU-kthreads
laptops/index
+ auxdisplay/index
lcd-panel-cgram
ldm
lockup-watchdogs
@@ -105,6 +109,7 @@
pnp
rtc
svga
+ wimax/index
video-output
.. only:: subproject and html
diff --git a/Documentation/admin-guide/jfs.rst b/Documentation/admin-guide/jfs.rst
new file mode 100644
index 0000000..9e12d93
--- /dev/null
+++ b/Documentation/admin-guide/jfs.rst
@@ -0,0 +1,66 @@
+===========================================
+IBM's Journaled File System (JFS) for Linux
+===========================================
+
+JFS Homepage: http://jfs.sourceforge.net/
+
+The following mount options are supported:
+
+(*) == default
+
+iocharset=name
+ Character set to use for converting from Unicode to
+ ASCII. The default is to do no conversion. Use
+ iocharset=utf8 for UTF-8 translations. This requires
+ CONFIG_NLS_UTF8 to be set in the kernel .config file.
+ iocharset=none specifies the default behavior explicitly.
+
+resize=value
+ Resize the volume to <value> blocks. JFS only supports
+ growing a volume, not shrinking it. This option is only
+ valid during a remount, when the volume is mounted
+ read-write. The resize keyword with no value will grow
+ the volume to the full size of the partition.
+
+nointegrity
+ Do not write to the journal. The primary use of this option
+ is to allow for higher performance when restoring a volume
+ from backup media. The integrity of the volume is not
+ guaranteed if the system abnormally abends.
+
+integrity(*)
+ Commit metadata changes to the journal. Use this option to
+ remount a volume where the nointegrity option was
+ previously specified in order to restore normal behavior.
+
+errors=continue
+ Keep going on a filesystem error.
+errors=remount-ro(*)
+ Remount the filesystem read-only on an error.
+errors=panic
+ Panic and halt the machine if an error occurs.
+
+uid=value
+ Override on-disk uid with specified value
+gid=value
+ Override on-disk gid with specified value
+umask=value
+ Override on-disk umask with specified octal value. For
+ directories, the execute bit will be set if the corresponding
+ read bit is set.
+
+discard=minlen, discard/nodiscard(*)
+ This enables/disables the use of discard/TRIM commands.
+ The discard/TRIM commands are sent to the underlying
+ block device when blocks are freed. This is useful for SSD
+ devices and sparse/thinly-provisioned LUNs. The FITRIM ioctl
+ command is also available together with the nodiscard option.
+ The value of minlen specifies the minimum blockcount, when
+ a TRIM command to the block device is considered useful.
+ When no value is given to the discard option, it defaults to
+ 64 blocks, which means 256KiB in JFS.
+ The minlen value of discard overrides the minlen value given
+ on an FITRIM ioctl().
+
+The JFS mailing list can be subscribed to by using the link labeled
+"Mail list Subscribe" at our web page http://jfs.sourceforge.net/
diff --git a/Documentation/admin-guide/kernel-parameters.txt b/Documentation/admin-guide/kernel-parameters.txt
index 4c19719..c7ac2f3 100644
--- a/Documentation/admin-guide/kernel-parameters.txt
+++ b/Documentation/admin-guide/kernel-parameters.txt
@@ -809,6 +809,8 @@
enables the feature at boot time. By default, it is
disabled and the system will work mostly the same as a
kernel built without CONFIG_DEBUG_PAGEALLOC.
+ Note: to get most of debug_pagealloc error reports, it's
+ useful to also enable the page_owner functionality.
on: enable the feature
debugpat [X86] Enable PAT debugging
@@ -860,6 +862,10 @@
disable_radix [PPC]
Disable RADIX MMU mode on POWER9
+ disable_tlbie [PPC]
+ Disable TLBIE instruction. Currently does not work
+ with KVM, with HASH MMU, or with coherent accelerators.
+
disable_cpu_apicid= [X86,APIC,SMP]
Format: <int>
The number of initial APIC ID for the
@@ -1044,6 +1050,10 @@
specified address. The serial port must already be
setup and configured. Options are not yet supported.
+ sbi
+ Use RISC-V SBI (Supervisor Binary Interface) for early
+ console.
+
smh Use ARM semihosting calls for early console.
s3c2410,<addr>
@@ -1090,6 +1100,12 @@
the framebuffer, pass the 'ram' option so that it is
mapped with the correct attributes.
+ linflex,<addr>
+ Use early console provided by Freescale LinFlex UART
+ serial driver for NXP S32V234 SoCs. A valid base
+ address must be provided, and the serial port must
+ already be setup and configured.
+
earlyprintk= [X86,SH,ARM,M68k,S390]
earlyprintk=vga
earlyprintk=sclp
@@ -1197,12 +1213,6 @@
See comment before function elanfreq_setup() in
arch/x86/kernel/cpu/cpufreq/elanfreq.c.
- elevator= [IOSCHED]
- Format: { "mq-deadline" | "kyber" | "bfq" }
- See Documentation/block/deadline-iosched.rst,
- Documentation/block/kyber-iosched.rst and
- Documentation/block/bfq-iosched.rst for details.
-
elfcorehdr=[size[KMG]@]offset[KMG] [IA64,PPC,SH,X86,S390]
Specifies physical address of start of kernel core
image elf header and optionally the size. Generally
@@ -1732,6 +1742,11 @@
Note that using this option lowers the security
provided by tboot because it makes the system
vulnerable to DMA attacks.
+ nobounce [Default off]
+ Disable bounce buffer for unstrusted devices such as
+ the Thunderbolt devices. This will treat the untrusted
+ devices as the trusted ones, hence might expose security
+ risks of DMA attacks.
intel_idle.max_cstate= [KNL,HW,ACPI,X86]
0 disables intel_idle and fall back on acpi_idle.
@@ -1811,7 +1826,7 @@
synchronously.
iommu.passthrough=
- [ARM64] Configure DMA to bypass the IOMMU by default.
+ [ARM64, X86] Configure DMA to bypass the IOMMU by default.
Format: { "0" | "1" }
0 - Use IOMMU translation for DMA.
1 - Bypass the IOMMU for DMA.
@@ -2261,6 +2276,15 @@
lockd.nlm_udpport=M [NFS] Assign UDP port.
Format: <integer>
+ lockdown= [SECURITY]
+ { integrity | confidentiality }
+ Enable the kernel lockdown feature. If set to
+ integrity, kernel features that allow userland to
+ modify the running kernel are disabled. If set to
+ confidentiality, kernel features that allow userland
+ to extract confidential information from the kernel
+ are also disabled.
+
locktorture.nreaders_stress= [KNL]
Set the number of locking read-acquisition kthreads.
Defaults to being automatically set based on the
@@ -2373,7 +2397,7 @@
machvec= [IA-64] Force the use of a particular machine-vector
(machvec) in a generic kernel.
- Example: machvec=hpzx1_swiotlb
+ Example: machvec=hpzx1
machtype= [Loongson] Share the same kernel image file between different
yeeloong laptop.
@@ -3452,12 +3476,13 @@
specify the device is described above.
If <order of align> is not specified,
PAGE_SIZE is used as alignment.
- PCI-PCI bridge can be specified, if resource
+ A PCI-PCI bridge can be specified if resource
windows need to be expanded.
To specify the alignment for several
instances of a device, the PCI vendor,
device, subvendor, and subdevice may be
- specified, e.g., 4096@pci:8086:9c22:103c:198f
+ specified, e.g., 12@pci:8086:9c22:103c:198f
+ for 4096-byte alignment.
ecrc= Enable/disable PCIe ECRC (transaction layer
end-to-end CRC checking).
bios: Use BIOS/firmware settings. This is the
@@ -3837,12 +3862,13 @@
RCU_BOOST is not set, valid values are 0-99 and
the default is zero (non-realtime operation).
- rcutree.rcu_nocb_leader_stride= [KNL]
- Set the number of NOCB kthread groups, which
- defaults to the square root of the number of
- CPUs. Larger numbers reduces the wakeup overhead
- on the per-CPU grace-period kthreads, but increases
- that same overhead on each group's leader.
+ rcutree.rcu_nocb_gp_stride= [KNL]
+ Set the number of NOCB callback kthreads in
+ each group, which defaults to the square root
+ of the number of CPUs. Larger numbers reduce
+ the wakeup overhead on the global grace-period
+ kthread, but increases that same overhead on
+ each group's NOCB grace-period kthread.
rcutree.qhimark= [KNL]
Set threshold of queued RCU callbacks beyond which
@@ -4047,6 +4073,10 @@
rcutorture.verbose= [KNL]
Enable additional printk() statements.
+ rcupdate.rcu_cpu_stall_ftrace_dump= [KNL]
+ Dump ftrace buffer after reporting RCU CPU
+ stall warning.
+
rcupdate.rcu_cpu_stall_suppress= [KNL]
Suppress RCU CPU stall warning messages.
@@ -4627,6 +4657,11 @@
/sys/power/pm_test). Only available when CONFIG_PM_DEBUG
is set. Default value is 5.
+ svm= [PPC]
+ Format: { on | off | y | n | 1 | 0 }
+ This parameter controls use of the Protected
+ Execution Facility on pSeries.
+
swapaccount=[0|1]
[KNL] Enable accounting of swap in memory resource
controller if no parameter or 1 is given or disable
@@ -5312,3 +5347,22 @@
A hex value specifying bitmask with supplemental xhci
host controller quirks. Meaning of each bit can be
consulted in header drivers/usb/host/xhci.h.
+
+ xmon [PPC]
+ Format: { early | on | rw | ro | off }
+ Controls if xmon debugger is enabled. Default is off.
+ Passing only "xmon" is equivalent to "xmon=early".
+ early Call xmon as early as possible on boot; xmon
+ debugger is called from setup_arch().
+ on xmon debugger hooks will be installed so xmon
+ is only called on a kernel crash. Default mode,
+ i.e. either "ro" or "rw" mode, is controlled
+ with CONFIG_XMON_DEFAULT_RO_MODE.
+ rw xmon debugger hooks will be installed so xmon
+ is called only on a kernel crash, mode is write,
+ meaning SPR registers, memory and, other data
+ can be written using xmon commands.
+ ro same as "rw" option above but SPR registers,
+ memory, and other data can't be written using
+ xmon commands.
+ off xmon is disabled.
diff --git a/Documentation/admin-guide/kernel-per-CPU-kthreads.rst b/Documentation/admin-guide/kernel-per-CPU-kthreads.rst
index 4f18456..baeeba8 100644
--- a/Documentation/admin-guide/kernel-per-CPU-kthreads.rst
+++ b/Documentation/admin-guide/kernel-per-CPU-kthreads.rst
@@ -274,9 +274,7 @@
(based on an earlier one from Gilad Ben-Yossef) that
reduces or even eliminates vmstat overhead for some
workloads at https://lkml.org/lkml/2013/9/4/379.
- e. Boot with "elevator=noop" to avoid workqueue use by
- the block layer.
- f. If running on high-end powerpc servers, build with
+ e. If running on high-end powerpc servers, build with
CONFIG_PPC_RTAS_DAEMON=n. This prevents the RTAS
daemon from running on each CPU every second or so.
(This will require editing Kconfig files and will defeat
@@ -284,12 +282,12 @@
due to the rtas_event_scan() function.
WARNING: Please check your CPU specifications to
make sure that this is safe on your particular system.
- g. If running on Cell Processor, build your kernel with
+ f. If running on Cell Processor, build your kernel with
CBE_CPUFREQ_SPU_GOVERNOR=n to avoid OS jitter from
spu_gov_work().
WARNING: Please check your CPU specifications to
make sure that this is safe on your particular system.
- h. If running on PowerMAC, build your kernel with
+ g. If running on PowerMAC, build your kernel with
CONFIG_PMAC_RACKMETER=n to disable the CPU-meter,
avoiding OS jitter from rackmeter_do_timer().
diff --git a/Documentation/admin-guide/laptops/thinkpad-acpi.rst b/Documentation/admin-guide/laptops/thinkpad-acpi.rst
index adea0bf..822907d 100644
--- a/Documentation/admin-guide/laptops/thinkpad-acpi.rst
+++ b/Documentation/admin-guide/laptops/thinkpad-acpi.rst
@@ -49,6 +49,7 @@
- Fan control and monitoring: fan speed, fan enable/disable
- WAN enable and disable
- UWB enable and disable
+ - LCD Shadow (PrivacyGuard) enable and disable
A compatibility table by model and feature is maintained on the web
site, http://ibm-acpi.sf.net/. I appreciate any success or failure
@@ -1409,6 +1410,28 @@
Documentation/driver-api/rfkill.rst for details.
+LCD Shadow control
+------------------
+
+procfs: /proc/acpi/ibm/lcdshadow
+
+Some newer T480s and T490s ThinkPads provide a feature called
+PrivacyGuard. By turning this feature on, the usable vertical and
+horizontal viewing angles of the LCD can be limited (as if some privacy
+screen was applied manually in front of the display).
+
+procfs notes
+^^^^^^^^^^^^
+
+The available commands are::
+
+ echo '0' >/proc/acpi/ibm/lcdshadow
+ echo '1' >/proc/acpi/ibm/lcdshadow
+
+The first command ensures the best viewing angle and the latter one turns
+on the feature, restricting the viewing angles.
+
+
EXPERIMENTAL: UWB
-----------------
diff --git a/Documentation/admin-guide/perf/imx-ddr.rst b/Documentation/admin-guide/perf/imx-ddr.rst
new file mode 100644
index 0000000..517a205
--- /dev/null
+++ b/Documentation/admin-guide/perf/imx-ddr.rst
@@ -0,0 +1,52 @@
+=====================================================
+Freescale i.MX8 DDR Performance Monitoring Unit (PMU)
+=====================================================
+
+There are no performance counters inside the DRAM controller, so performance
+signals are brought out to the edge of the controller where a set of 4 x 32 bit
+counters is implemented. This is controlled by the CSV modes programed in counter
+control register which causes a large number of PERF signals to be generated.
+
+Selection of the value for each counter is done via the config registers. There
+is one register for each counter. Counter 0 is special in that it always counts
+“time” and when expired causes a lock on itself and the other counters and an
+interrupt is raised. If any other counter overflows, it continues counting, and
+no interrupt is raised.
+
+The "format" directory describes format of the config (event ID) and config1
+(AXI filtering) fields of the perf_event_attr structure, see /sys/bus/event_source/
+devices/imx8_ddr0/format/. The "events" directory describes the events types
+hardware supported that can be used with perf tool, see /sys/bus/event_source/
+devices/imx8_ddr0/events/.
+ e.g.::
+ perf stat -a -e imx8_ddr0/cycles/ cmd
+ perf stat -a -e imx8_ddr0/read/,imx8_ddr0/write/ cmd
+
+AXI filtering is only used by CSV modes 0x41 (axid-read) and 0x42 (axid-write)
+to count reading or writing matches filter setting. Filter setting is various
+from different DRAM controller implementations, which is distinguished by quirks
+in the driver.
+
+* With DDR_CAP_AXI_ID_FILTER quirk.
+ Filter is defined with two configuration parts:
+ --AXI_ID defines AxID matching value.
+ --AXI_MASKING defines which bits of AxID are meaningful for the matching.
+ 0：corresponding bit is masked.
+ 1: corresponding bit is not masked, i.e. used to do the matching.
+
+ AXI_ID and AXI_MASKING are mapped on DPCR1 register in performance counter.
+ When non-masked bits are matching corresponding AXI_ID bits then counter is
+ incremented. Perf counter is incremented if
+ AxID && AXI_MASKING == AXI_ID && AXI_MASKING
+
+ This filter doesn't support filter different AXI ID for axid-read and axid-write
+ event at the same time as this filter is shared between counters.
+ e.g.::
+ perf stat -a -e imx8_ddr0/axid-read,axi_mask=0xMMMM,axi_id=0xDDDD/ cmd
+ perf stat -a -e imx8_ddr0/axid-write,axi_mask=0xMMMM,axi_id=0xDDDD/ cmd
+
+ NOTE: axi_mask is inverted in userspace(i.e. set bits are bits to mask), and
+ it will be reverted in driver automatically. so that the user can just specify
+ axi_id to monitor a specific id, rather than having to specify axi_mask.
+ e.g.::
+ perf stat -a -e imx8_ddr0/axid-read,axi_id=0x12/ cmd, which will monitor ARID=0x12
diff --git a/Documentation/admin-guide/sysrq.rst b/Documentation/admin-guide/sysrq.rst
index 7b9035c..72b2cfb 100644
--- a/Documentation/admin-guide/sysrq.rst
+++ b/Documentation/admin-guide/sysrq.rst
@@ -171,22 +171,20 @@
useful when you want to exit a program that will not let you switch consoles.
(For example, X or a svgalib program.)
-``reboot(b)`` is good when you're unable to shut down. But you should also
-``sync(s)`` and ``umount(u)`` first.
+``reboot(b)`` is good when you're unable to shut down, it is an equivalent
+of pressing the "reset" button.
``crash(c)`` can be used to manually trigger a crashdump when the system is hung.
Note that this just triggers a crash if there is no dump mechanism available.
-``sync(s)`` is great when your system is locked up, it allows you to sync your
-disks and will certainly lessen the chance of data loss and fscking. Note
-that the sync hasn't taken place until you see the "OK" and "Done" appear
-on the screen. (If the kernel is really in strife, you may not ever get the
-OK or Done message...)
+``sync(s)`` is handy before yanking removable medium or after using a rescue
+shell that provides no graceful shutdown -- it will ensure your data is
+safely written to the disk. Note that the sync hasn't taken place until you see
+the "OK" and "Done" appear on the screen.
-``umount(u)`` is basically useful in the same ways as ``sync(s)``. I generally
-``sync(s)``, ``umount(u)``, then ``reboot(b)`` when my system locks. It's saved
-me many a fsck. Again, the unmount (remount read-only) hasn't taken place until
-you see the "OK" and "Done" message appear on the screen.
+``umount(u)`` can be used to mark filesystems as properly unmounted. From the
+running system's point of view, they will be remounted read-only. The remount
+isn't complete until you see the "OK" and "Done" message appear on the screen.
The loglevels ``0``-``9`` are useful when your console is being flooded with
kernel messages you do not want to see. Selecting ``0`` will prevent all but
diff --git a/Documentation/admin-guide/ufs.rst b/Documentation/admin-guide/ufs.rst
new file mode 100644
index 0000000..55d1529
--- /dev/null
+++ b/Documentation/admin-guide/ufs.rst
@@ -0,0 +1,68 @@
+=========
+Using UFS
+=========
+
+mount -t ufs -o ufstype=type_of_ufs device dir
+
+
+UFS Options
+===========
+
+ufstype=type_of_ufs
+ UFS is a file system widely used in different operating systems.
+ The problem are differences among implementations. Features of
+ some implementations are undocumented, so its hard to recognize
+ type of ufs automatically. That's why user must specify type of
+ ufs manually by mount option ufstype. Possible values are:
+
+ old
+ old format of ufs
+ default value, supported as read-only
+
+ 44bsd
+ used in FreeBSD, NetBSD, OpenBSD
+ supported as read-write
+
+ ufs2
+ used in FreeBSD 5.x
+ supported as read-write
+
+ 5xbsd
+ synonym for ufs2
+
+ sun
+ used in SunOS (Solaris)
+ supported as read-write
+
+ sunx86
+ used in SunOS for Intel (Solarisx86)
+ supported as read-write
+
+ hp
+ used in HP-UX
+ supported as read-only
+
+ nextstep
+ used in NextStep
+ supported as read-only
+
+ nextstep-cd
+ used for NextStep CDROMs (block_size == 2048)
+ supported as read-only
+
+ openstep
+ used in OpenStep
+ supported as read-only
+
+
+Possible Problems
+-----------------
+
+See next section, if you have any.
+
+
+Bug Reports
+-----------
+
+Any ufs bug report you can send to daniel.pirkl@email.cz or
+to dushistov@mail.ru (do not send partition tables bug reports).
diff --git a/Documentation/admin-guide/wimax/i2400m.rst b/Documentation/admin-guide/wimax/i2400m.rst
new file mode 100644
index 0000000..194388c
--- /dev/null
+++ b/Documentation/admin-guide/wimax/i2400m.rst
@@ -0,0 +1,283 @@
+.. include:: <isonum.txt>
+
+====================================================
+Driver for the Intel Wireless Wimax Connection 2400m
+====================================================
+
+:Copyright: |copy| 2008 Intel Corporation < linux-wimax@intel.com >
+
+ This provides a driver for the Intel Wireless WiMAX Connection 2400m
+ and a basic Linux kernel WiMAX stack.
+
+1. Requirements
+===============
+
+ * Linux installation with Linux kernel 2.6.22 or newer (if building
+ from a separate tree)
+ * Intel i2400m Echo Peak or Baxter Peak; this includes the Intel
+ Wireless WiMAX/WiFi Link 5x50 series.
+ * build tools:
+
+ + Linux kernel development package for the target kernel; to
+ build against your currently running kernel, you need to have
+ the kernel development package corresponding to the running
+ image installed (usually if your kernel is named
+ linux-VERSION, the development package is called
+ linux-dev-VERSION or linux-headers-VERSION).
+ + GNU C Compiler, make
+
+2. Compilation and installation
+===============================
+
+2.1. Compilation of the drivers included in the kernel
+------------------------------------------------------
+
+ Configure the kernel; to enable the WiMAX drivers select Drivers >
+ Networking Drivers > WiMAX device support. Enable all of them as
+ modules (easier).
+
+ If USB or SDIO are not enabled in the kernel configuration, the options
+ to build the i2400m USB or SDIO drivers will not show. Enable said
+ subsystems and go back to the WiMAX menu to enable the drivers.
+
+ Compile and install your kernel as usual.
+
+2.2. Compilation of the drivers distributed as an standalone module
+-------------------------------------------------------------------
+
+ To compile::
+
+ $ cd source/directory
+ $ make
+
+ Once built you can load and unload using the provided load.sh script;
+ load.sh will load the modules, load.sh u will unload them.
+
+ To install in the default kernel directories (and enable auto loading
+ when the device is plugged)::
+
+ $ make install
+ $ depmod -a
+
+ If your kernel development files are located in a non standard
+ directory or if you want to build for a kernel that is not the
+ currently running one, set KDIR to the right location::
+
+ $ make KDIR=/path/to/kernel/dev/tree
+
+ For more information, please contact linux-wimax@intel.com.
+
+3. Installing the firmware
+--------------------------
+
+ The firmware can be obtained from http://linuxwimax.org or might have
+ been supplied with your hardware.
+
+ It has to be installed in the target system::
+
+ $ cp FIRMWAREFILE.sbcf /lib/firmware/i2400m-fw-BUSTYPE-1.3.sbcf
+
+ * NOTE: if your firmware came in an .rpm or .deb file, just install
+ it as normal, with the rpm (rpm -i FIRMWARE.rpm) or dpkg
+ (dpkg -i FIRMWARE.deb) commands. No further action is needed.
+ * BUSTYPE will be usb or sdio, depending on the hardware you have.
+ Each hardware type comes with its own firmware and will not work
+ with other types.
+
+4. Design
+=========
+
+ This package contains two major parts: a WiMAX kernel stack and a
+ driver for the Intel i2400m.
+
+ The WiMAX stack is designed to provide for common WiMAX control
+ services to current and future WiMAX devices from any vendor; please
+ see README.wimax for details.
+
+ The i2400m kernel driver is broken up in two main parts: the bus
+ generic driver and the bus-specific drivers. The bus generic driver
+ forms the drivercore and contain no knowledge of the actual method we
+ use to connect to the device. The bus specific drivers are just the
+ glue to connect the bus-generic driver and the device. Currently only
+ USB and SDIO are supported. See drivers/net/wimax/i2400m/i2400m.h for
+ more information.
+
+ The bus generic driver is logically broken up in two parts: OS-glue and
+ hardware-glue. The OS-glue interfaces with Linux. The hardware-glue
+ interfaces with the device on using an interface provided by the
+ bus-specific driver. The reason for this breakup is to be able to
+ easily reuse the hardware-glue to write drivers for other OSes; note
+ the hardware glue part is written as a native Linux driver; no
+ abstraction layers are used, so to port to another OS, the Linux kernel
+ API calls should be replaced with the target OS's.
+
+5. Usage
+========
+
+ To load the driver, follow the instructions in the install section;
+ once the driver is loaded, plug in the device (unless it is permanently
+ plugged in). The driver will enumerate the device, upload the firmware
+ and output messages in the kernel log (dmesg, /var/log/messages or
+ /var/log/kern.log) such as::
+
+ ...
+ i2400m_usb 5-4:1.0: firmware interface version 8.0.0
+ i2400m_usb 5-4:1.0: WiMAX interface wmx0 (00:1d:e1:01:94:2c) ready
+
+ At this point the device is ready to work.
+
+ Current versions require the Intel WiMAX Network Service in userspace
+ to make things work. See the network service's README for instructions
+ on how to scan, connect and disconnect.
+
+5.1. Module parameters
+----------------------
+
+ Module parameters can be set at kernel or module load time or by
+ echoing values::
+
+ $ echo VALUE > /sys/module/MODULENAME/parameters/PARAMETERNAME
+
+ To make changes permanent, for example, for the i2400m module, you can
+ also create a file named /etc/modprobe.d/i2400m containing::
+
+ options i2400m idle_mode_disabled=1
+
+ To find which parameters are supported by a module, run::
+
+ $ modinfo path/to/module.ko
+
+ During kernel bootup (if the driver is linked in the kernel), specify
+ the following to the kernel command line::
+
+ i2400m.PARAMETER=VALUE
+
+5.1.1. i2400m: idle_mode_disabled
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+ The i2400m module supports a parameter to disable idle mode. This
+ parameter, once set, will take effect only when the device is
+ reinitialized by the driver (eg: following a reset or a reconnect).
+
+5.2. Debug operations: debugfs entries
+--------------------------------------
+
+ The driver will register debugfs entries that allow the user to tweak
+ debug settings. There are three main container directories where
+ entries are placed, which correspond to the three blocks a i2400m WiMAX
+ driver has:
+
+ * /sys/kernel/debug/wimax:DEVNAME/ for the generic WiMAX stack
+ controls
+ * /sys/kernel/debug/wimax:DEVNAME/i2400m for the i2400m generic
+ driver controls
+ * /sys/kernel/debug/wimax:DEVNAME/i2400m-usb (or -sdio) for the
+ bus-specific i2400m-usb or i2400m-sdio controls).
+
+ Of course, if debugfs is mounted in a directory other than
+ /sys/kernel/debug, those paths will change.
+
+5.2.1. Increasing debug output
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+ The files named *dl_* indicate knobs for controlling the debug output
+ of different submodules::
+
+ # find /sys/kernel/debug/wimax\:wmx0 -name \*dl_\*
+ /sys/kernel/debug/wimax:wmx0/i2400m-usb/dl_tx
+ /sys/kernel/debug/wimax:wmx0/i2400m-usb/dl_rx
+ /sys/kernel/debug/wimax:wmx0/i2400m-usb/dl_notif
+ /sys/kernel/debug/wimax:wmx0/i2400m-usb/dl_fw
+ /sys/kernel/debug/wimax:wmx0/i2400m-usb/dl_usb
+ /sys/kernel/debug/wimax:wmx0/i2400m/dl_tx
+ /sys/kernel/debug/wimax:wmx0/i2400m/dl_rx
+ /sys/kernel/debug/wimax:wmx0/i2400m/dl_rfkill
+ /sys/kernel/debug/wimax:wmx0/i2400m/dl_netdev
+ /sys/kernel/debug/wimax:wmx0/i2400m/dl_fw
+ /sys/kernel/debug/wimax:wmx0/i2400m/dl_debugfs
+ /sys/kernel/debug/wimax:wmx0/i2400m/dl_driver
+ /sys/kernel/debug/wimax:wmx0/i2400m/dl_control
+ /sys/kernel/debug/wimax:wmx0/wimax_dl_stack
+ /sys/kernel/debug/wimax:wmx0/wimax_dl_op_rfkill
+ /sys/kernel/debug/wimax:wmx0/wimax_dl_op_reset
+ /sys/kernel/debug/wimax:wmx0/wimax_dl_op_msg
+ /sys/kernel/debug/wimax:wmx0/wimax_dl_id_table
+ /sys/kernel/debug/wimax:wmx0/wimax_dl_debugfs
+
+ By reading the file you can obtain the current value of said debug
+ level; by writing to it, you can set it.
+
+ To increase the debug level of, for example, the i2400m's generic TX
+ engine, just write::
+
+ $ echo 3 > /sys/kernel/debug/wimax:wmx0/i2400m/dl_tx
+
+ Increasing numbers yield increasing debug information; for details of
+ what is printed and the available levels, check the source. The code
+ uses 0 for disabled and increasing values until 8.
+
+5.2.2. RX and TX statistics
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+ The i2400m/rx_stats and i2400m/tx_stats provide statistics about the
+ data reception/delivery from the device::
+
+ $ cat /sys/kernel/debug/wimax:wmx0/i2400m/rx_stats
+ 45 1 3 34 3104 48 480
+
+ The numbers reported are:
+
+ * packets/RX-buffer: total, min, max
+ * RX-buffers: total RX buffers received, accumulated RX buffer size
+ in bytes, min size received, max size received
+
+ Thus, to find the average buffer size received, divide accumulated
+ RX-buffer / total RX-buffers.
+
+ To clear the statistics back to 0, write anything to the rx_stats file::
+
+ $ echo 1 > /sys/kernel/debug/wimax:wmx0/i2400m_rx_stats
+
+ Likewise for TX.
+
+ Note the packets this debug file refers to are not network packet, but
+ packets in the sense of the device-specific protocol for communication
+ to the host. See drivers/net/wimax/i2400m/tx.c.
+
+5.2.3. Tracing messages received from user space
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+ To echo messages received from user space into the trace pipe that the
+ i2400m driver creates, set the debug file i2400m/trace_msg_from_user to
+ 1::
+
+ $ echo 1 > /sys/kernel/debug/wimax:wmx0/i2400m/trace_msg_from_user
+
+5.2.4. Performing a device reset
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+ By writing a 0, a 1 or a 2 to the file
+ /sys/kernel/debug/wimax:wmx0/reset, the driver performs a warm (without
+ disconnecting from the bus), cold (disconnecting from the bus) or bus
+ (bus specific) reset on the device.
+
+5.2.5. Asking the device to enter power saving mode
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+ By writing any value to the /sys/kernel/debug/wimax:wmx0 file, the
+ device will attempt to enter power saving mode.
+
+6. Troubleshooting
+==================
+
+6.1. Driver complains about ``i2400m-fw-usb-1.2.sbcf: request failed``
+----------------------------------------------------------------------
+
+ If upon connecting the device, the following is output in the kernel
+ log::
+
+ i2400m_usb 5-4:1.0: fw i2400m-fw-usb-1.3.sbcf: request failed: -2
+
+ This means that the driver cannot locate the firmware file named
+ /lib/firmware/i2400m-fw-usb-1.2.sbcf. Check that the file is present in
+ the right location.
diff --git a/Documentation/admin-guide/wimax/index.rst b/Documentation/admin-guide/wimax/index.rst
new file mode 100644
index 0000000..fdf7c1f
--- /dev/null
+++ b/Documentation/admin-guide/wimax/index.rst
@@ -0,0 +1,19 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+===============
+WiMAX subsystem
+===============
+
+.. toctree::
+ :maxdepth: 2
+
+ wimax
+
+ i2400m
+
+.. only:: subproject and html
+
+ Indices
+ =======
+
+ * :ref:`genindex`
diff --git a/Documentation/admin-guide/wimax/wimax.rst b/Documentation/admin-guide/wimax/wimax.rst
new file mode 100644
index 0000000..817ee8b
--- /dev/null
+++ b/Documentation/admin-guide/wimax/wimax.rst
@@ -0,0 +1,89 @@
+.. include:: <isonum.txt>
+
+========================
+Linux kernel WiMAX stack
+========================
+
+:Copyright: |copy| 2008 Intel Corporation < linux-wimax@intel.com >
+
+ This provides a basic Linux kernel WiMAX stack to provide a common
+ control API for WiMAX devices, usable from kernel and user space.
+
+1. Design
+=========
+
+ The WiMAX stack is designed to provide for common WiMAX control
+ services to current and future WiMAX devices from any vendor.
+
+ Because currently there is only one and we don't know what would be the
+ common services, the APIs it currently provides are very minimal.
+ However, it is done in such a way that it is easily extensible to
+ accommodate future requirements.
+
+ The stack works by embedding a struct wimax_dev in your device's
+ control structures. This provides a set of callbacks that the WiMAX
+ stack will call in order to implement control operations requested by
+ the user. As well, the stack provides API functions that the driver
+ calls to notify about changes of state in the device.
+
+ The stack exports the API calls needed to control the device to user
+ space using generic netlink as a marshalling mechanism. You can access
+ them using your own code or use the wrappers provided for your
+ convenience in libwimax (in the wimax-tools package).
+
+ For detailed information on the stack, please see
+ include/linux/wimax.h.
+
+2. Usage
+========
+
+ For usage in a driver (registration, API, etc) please refer to the
+ instructions in the header file include/linux/wimax.h.
+
+ When a device is registered with the WiMAX stack, a set of debugfs
+ files will appear in /sys/kernel/debug/wimax:wmxX can tweak for
+ control.
+
+2.1. Obtaining debug information: debugfs entries
+-------------------------------------------------
+
+ The WiMAX stack is compiled, by default, with debug messages that can
+ be used to diagnose issues. By default, said messages are disabled.
+
+ The drivers will register debugfs entries that allow the user to tweak
+ debug settings.
+
+ Each driver, when registering with the stack, will cause a debugfs
+ directory named wimax:DEVICENAME to be created; optionally, it might
+ create more subentries below it.
+
+2.1.1. Increasing debug output
+------------------------------
+
+ The files named *dl_* indicate knobs for controlling the debug output
+ of different submodules of the WiMAX stack::
+
+ # find /sys/kernel/debug/wimax\:wmx0 -name \*dl_\*
+ /sys/kernel/debug/wimax:wmx0/wimax_dl_stack
+ /sys/kernel/debug/wimax:wmx0/wimax_dl_op_rfkill
+ /sys/kernel/debug/wimax:wmx0/wimax_dl_op_reset
+ /sys/kernel/debug/wimax:wmx0/wimax_dl_op_msg
+ /sys/kernel/debug/wimax:wmx0/wimax_dl_id_table
+ /sys/kernel/debug/wimax:wmx0/wimax_dl_debugfs
+ /sys/kernel/debug/wimax:wmx0/.... # other driver specific files
+
+ NOTE:
+ Of course, if debugfs is mounted in a directory other than
+ /sys/kernel/debug, those paths will change.
+
+ By reading the file you can obtain the current value of said debug
+ level; by writing to it, you can set it.
+
+ To increase the debug level of, for example, the id-table submodule,
+ just write:
+
+ $ echo 3 > /sys/kernel/debug/wimax:wmx0/wimax_dl_id_table
+
+ Increasing numbers yield increasing debug information; for details of
+ what is printed and the available levels, check the source. The code
+ uses 0 for disabled and increasing values until 8.
diff --git a/Documentation/admin-guide/xfs.rst b/Documentation/admin-guide/xfs.rst
index e76665a..fb5b39f7 100644
--- a/Documentation/admin-guide/xfs.rst
+++ b/Documentation/admin-guide/xfs.rst
@@ -337,11 +337,12 @@
Removed Sysctls
===============
+============================= =======
Name Removed
- ---- -------
+============================= =======
fs.xfs.xfsbufd_centisec v4.0
fs.xfs.age_buffer_centisecs v4.0
-
+============================= =======
Error handling
==============
diff --git a/Documentation/arm/sa1100/adsbitsy.rst b/Documentation/arm/sa1100/adsbitsy.rst
deleted file mode 100644
index c179cb2..0000000
--- a/Documentation/arm/sa1100/adsbitsy.rst
+++ /dev/null
@@ -1,51 +0,0 @@
-===============================
-ADS Bitsy Single Board Computer
-===============================
-
-(It is different from Bitsy(iPAQ) of Compaq)
-
-For more details, contact Applied Data Systems or see
-http://www.applieddata.net/products.html
-
-The Linux support for this product has been provided by
-Woojung Huh <whuh@applieddata.net>
-
-Use 'make adsbitsy_config' before any 'make config'.
-This will set up defaults for ADS Bitsy support.
-
-The kernel zImage is linked to be loaded and executed at 0xc0400000.
-
-Linux can be used with the ADS BootLoader that ships with the
-newer rev boards. See their documentation on how to load Linux.
-
-Supported peripherals
-=====================
-
-- SA1100 LCD frame buffer (8/16bpp...sort of)
-- SA1111 USB Master
-- SA1100 serial port
-- pcmcia, compact flash
-- touchscreen(ucb1200)
-- console on LCD screen
-- serial ports (ttyS[0-2])
- - ttyS0 is default for serial console
-
-To do
-=====
-
-- everything else! :-)
-
-Notes
-=====
-
-- The flash on board is divided into 3 partitions.
- You should be careful to use flash on board.
- Its partition is different from GraphicsClient Plus and GraphicsMaster
-
-- 16bpp mode requires a different cable than what ships with the board.
- Contact ADS or look through the manual to wire your own. Currently,
- if you compile with 16bit mode support and switch into a lower bpp
- mode, the timing is off so the image is corrupted. This will be
- fixed soon.
-
-Any contribution can be sent to nico@fluxnic.net and will be greatly welcome!
diff --git a/Documentation/arm/sa1100/assabet.rst b/Documentation/arm/sa1100/assabet.rst
index 3e70483..a761e12 100644
--- a/Documentation/arm/sa1100/assabet.rst
+++ b/Documentation/arm/sa1100/assabet.rst
@@ -14,7 +14,7 @@
To build the kernel with current defaults::
- make assabet_config
+ make assabet_defconfig
make oldconfig
make zImage
diff --git a/Documentation/arm/sa1100/brutus.rst b/Documentation/arm/sa1100/brutus.rst
deleted file mode 100644
index e1a23be..0000000
--- a/Documentation/arm/sa1100/brutus.rst
+++ /dev/null
@@ -1,69 +0,0 @@
-======
-Brutus
-======
-
-Brutus is an evaluation platform for the SA1100 manufactured by Intel.
-For more details, see:
-
-http://developer.intel.com
-
-To compile for Brutus, you must issue the following commands::
-
- make brutus_config
- make config
- [accept all the defaults]
- make zImage
-
-The resulting kernel will end up in linux/arch/arm/boot/zImage. This file
-must be loaded at 0xc0008000 in Brutus's memory and execution started at
-0xc0008000 as well with the value of registers r0 = 0 and r1 = 16 upon
-entry.
-
-But prior to execute the kernel, a ramdisk image must also be loaded in
-memory. Use memory address 0xd8000000 for this. Note that the file
-containing the (compressed) ramdisk image must not exceed 4 MB.
-
-Typically, you'll need angelboot to load the kernel.
-The following angelboot.opt file should be used::
-
- base 0xc0008000
- entry 0xc0008000
- r0 0x00000000
- r1 0x00000010
- device /dev/ttyS0
- options "9600 8N1"
- baud 115200
- otherfile ramdisk_img.gz
- otherbase 0xd8000000
-
-Then load the kernel and ramdisk with::
-
- angelboot -f angelboot.opt zImage
-
-The first Brutus serial port (assumed to be linked to /dev/ttyS0 on your
-host PC) is used by angel to load the kernel and ramdisk image. The serial
-console is provided through the second Brutus serial port. To access it,
-you may use minicom configured with /dev/ttyS1, 9600 baud, 8N1, no flow
-control.
-
-Currently supported
-===================
-
- - RS232 serial ports
- - audio output
- - LCD screen
- - keyboard
-
-The actual Brutus support may not be complete without extra patches.
-If such patches exist, they should be found from
-ftp.netwinder.org/users/n/nico.
-
-A full PCMCIA support is still missing, although it's possible to hack
-some drivers in order to drive already inserted cards at boot time with
-little modifications.
-
-Any contribution is welcome.
-
-Please send patches to nico@fluxnic.net
-
-Have Fun !
diff --git a/Documentation/arm/sa1100/freebird.rst b/Documentation/arm/sa1100/freebird.rst
deleted file mode 100644
index 81043d0..0000000
--- a/Documentation/arm/sa1100/freebird.rst
+++ /dev/null
@@ -1,25 +0,0 @@
-========
-Freebird
-========
-
-Freebird-1.1 is produced by Legend(C), Inc.
-`http://web.archive.org/web/*/http://www.legend.com.cn`
-and software/linux maintained by Coventive(C), Inc.
-(http://www.coventive.com)
-
-Based on the Nicolas's strongarm kernel tree.
-
-Maintainer:
-
-Chester Kuo
- - <chester@coventive.com>
- - <chester@linux.org.tw>
-
-Author:
-
-- Tim wu <timwu@coventive.com>
-- CIH <cih@coventive.com>
-- Eric Peng <ericpeng@coventive.com>
-- Jeff Lee <jeff_lee@coventive.com>
-- Allen Cheng
-- Tony Liu <tonyliu@coventive.com>
diff --git a/Documentation/arm/sa1100/graphicsclient.rst b/Documentation/arm/sa1100/graphicsclient.rst
deleted file mode 100644
index a73d61c3..0000000
--- a/Documentation/arm/sa1100/graphicsclient.rst
+++ /dev/null
@@ -1,102 +0,0 @@
-=============================================
-ADS GraphicsClient Plus Single Board Computer
-=============================================
-
-For more details, contact Applied Data Systems or see
-http://www.applieddata.net/products.html
-
-The original Linux support for this product has been provided by
-Nicolas Pitre <nico@fluxnic.net>. Continued development work by
-Woojung Huh <whuh@applieddata.net>
-
-It's currently possible to mount a root filesystem via NFS providing a
-complete Linux environment. Otherwise a ramdisk image may be used. The
-board supports MTD/JFFS, so you could also mount something on there.
-
-Use 'make graphicsclient_config' before any 'make config'. This will set up
-defaults for GraphicsClient Plus support.
-
-The kernel zImage is linked to be loaded and executed at 0xc0200000.
-Also the following registers should have the specified values upon entry::
-
- r0 = 0
- r1 = 29 (this is the GraphicsClient architecture number)
-
-Linux can be used with the ADS BootLoader that ships with the
-newer rev boards. See their documentation on how to load Linux.
-Angel is not available for the GraphicsClient Plus AFAIK.
-
-There is a board known as just the GraphicsClient that ADS used to
-produce but has end of lifed. This code will not work on the older
-board with the ADS bootloader, but should still work with Angel,
-as outlined below. In any case, if you're planning on deploying
-something en masse, you should probably get the newer board.
-
-If using Angel on the older boards, here is a typical angel.opt option file
-if the kernel is loaded through the Angel Debug Monitor::
-
- base 0xc0200000
- entry 0xc0200000
- r0 0x00000000
- r1 0x0000001d
- device /dev/ttyS1
- options "38400 8N1"
- baud 115200
- #otherfile ramdisk.gz
- #otherbase 0xc0800000
- exec minicom
-
-Then the kernel (and ramdisk if otherfile/otherbase lines above are
-uncommented) would be loaded with::
-
- angelboot -f angelboot.opt zImage
-
-Here it is assumed that the board is connected to ttyS1 on your PC
-and that minicom is preconfigured with /dev/ttyS1, 38400 baud, 8N1, no flow
-control by default.
-
-If any other bootloader is used, ensure it accomplish the same, especially
-for r0/r1 register values before jumping into the kernel.
-
-
-Supported peripherals
-=====================
-
-- SA1100 LCD frame buffer (8/16bpp...sort of)
-- on-board SMC 92C96 ethernet NIC
-- SA1100 serial port
-- flash memory access (MTD/JFFS)
-- pcmcia
-- touchscreen(ucb1200)
-- ps/2 keyboard
-- console on LCD screen
-- serial ports (ttyS[0-2])
- - ttyS0 is default for serial console
-- Smart I/O (ADC, keypad, digital inputs, etc)
- See http://www.eurotech-inc.com/linux-sbc.asp for IOCTL documentation
- and example user space code. ps/2 keybd is multiplexed through this driver
-
-To do
-=====
-
-- UCB1200 audio with new ucb_generic layer
-- everything else! :-)
-
-Notes
-=====
-
-- The flash on board is divided into 3 partitions. mtd0 is where
- the ADS boot ROM and zImage is stored. It's been marked as
- read-only to keep you from blasting over the bootloader. :) mtd1 is
- for the ramdisk.gz image. mtd2 is user flash space and can be
- utilized for either JFFS or if you're feeling crazy, running ext2
- on top of it. If you're not using the ADS bootloader, you're
- welcome to blast over the mtd1 partition also.
-
-- 16bpp mode requires a different cable than what ships with the board.
- Contact ADS or look through the manual to wire your own. Currently,
- if you compile with 16bit mode support and switch into a lower bpp
- mode, the timing is off so the image is corrupted. This will be
- fixed soon.
-
-Any contribution can be sent to nico@fluxnic.net and will be greatly welcome!
diff --git a/Documentation/arm/sa1100/graphicsmaster.rst b/Documentation/arm/sa1100/graphicsmaster.rst
deleted file mode 100644
index e398925..0000000
--- a/Documentation/arm/sa1100/graphicsmaster.rst
+++ /dev/null
@@ -1,60 +0,0 @@
-========================================
-ADS GraphicsMaster Single Board Computer
-========================================
-
-For more details, contact Applied Data Systems or see
-http://www.applieddata.net/products.html
-
-The original Linux support for this product has been provided by
-Nicolas Pitre <nico@fluxnic.net>. Continued development work by
-Woojung Huh <whuh@applieddata.net>
-
-Use 'make graphicsmaster_config' before any 'make config'.
-This will set up defaults for GraphicsMaster support.
-
-The kernel zImage is linked to be loaded and executed at 0xc0400000.
-
-Linux can be used with the ADS BootLoader that ships with the
-newer rev boards. See their documentation on how to load Linux.
-
-Supported peripherals
-=====================
-
-- SA1100 LCD frame buffer (8/16bpp...sort of)
-- SA1111 USB Master
-- on-board SMC 92C96 ethernet NIC
-- SA1100 serial port
-- flash memory access (MTD/JFFS)
-- pcmcia, compact flash
-- touchscreen(ucb1200)
-- ps/2 keyboard
-- console on LCD screen
-- serial ports (ttyS[0-2])
- - ttyS0 is default for serial console
-- Smart I/O (ADC, keypad, digital inputs, etc)
- See http://www.eurotech-inc.com/linux-sbc.asp for IOCTL documentation
- and example user space code. ps/2 keybd is multiplexed through this driver
-
-To do
-=====
-
-- everything else! :-)
-
-Notes
-=====
-
-- The flash on board is divided into 3 partitions. mtd0 is where
- the zImage is stored. It's been marked as read-only to keep you
- from blasting over the bootloader. :) mtd1 is
- for the ramdisk.gz image. mtd2 is user flash space and can be
- utilized for either JFFS or if you're feeling crazy, running ext2
- on top of it. If you're not using the ADS bootloader, you're
- welcome to blast over the mtd1 partition also.
-
-- 16bpp mode requires a different cable than what ships with the board.
- Contact ADS or look through the manual to wire your own. Currently,
- if you compile with 16bit mode support and switch into a lower bpp
- mode, the timing is off so the image is corrupted. This will be
- fixed soon.
-
-Any contribution can be sent to nico@fluxnic.net and will be greatly welcome!
diff --git a/Documentation/arm/sa1100/huw_webpanel.rst b/Documentation/arm/sa1100/huw_webpanel.rst
deleted file mode 100644
index 1dc7ccb..0000000
--- a/Documentation/arm/sa1100/huw_webpanel.rst
+++ /dev/null
@@ -1,21 +0,0 @@
-=======================
-Hoeft & Wessel Webpanel
-=======================
-
-The HUW_WEBPANEL is a product of the german company Hoeft & Wessel AG
-
-If you want more information, please visit
-http://www.hoeft-wessel.de
-
-To build the kernel::
-
- make huw_webpanel_config
- make oldconfig
- [accept all defaults]
- make zImage
-
-Mostly of the work is done by:
-Roman Jordan jor@hoeft-wessel.de
-Christoph Schulz schu@hoeft-wessel.de
-
-2000/12/18/
diff --git a/Documentation/arm/sa1100/index.rst b/Documentation/arm/sa1100/index.rst
index 68c2a28..c9aed43 100644
--- a/Documentation/arm/sa1100/index.rst
+++ b/Documentation/arm/sa1100/index.rst
@@ -7,19 +7,7 @@
.. toctree::
:maxdepth: 1
- adsbitsy
assabet
- brutus
cerf
- freebird
- graphicsclient
- graphicsmaster
- huw_webpanel
- itsy
lart
- nanoengine
- pangolin
- pleb
serial_uart
- tifon
- yopy
diff --git a/Documentation/arm/sa1100/itsy.rst b/Documentation/arm/sa1100/itsy.rst
deleted file mode 100644
index f49896b..0000000
--- a/Documentation/arm/sa1100/itsy.rst
+++ /dev/null
@@ -1,47 +0,0 @@
-====
-Itsy
-====
-
-Itsy is a research project done by the Western Research Lab, and Systems
-Research Center in Palo Alto, CA. The Itsy project is one of several
-research projects at Compaq that are related to pocket computing.
-
-For more information, see:
-
- http://www.hpl.hp.com/downloads/crl/itsy/
-
-Notes on initial 2.4 Itsy support (8/27/2000) :
-
-The port was done on an Itsy version 1.5 machine with a daughtercard with
-64 Meg of DRAM and 32 Meg of Flash. The initial work includes support for
-serial console (to see what you're doing). No other devices have been
-enabled.
-
-To build, do a "make menuconfig" (or xmenuconfig) and select Itsy support.
-Disable Flash and LCD support. and then do a make zImage.
-Finally, you will need to cd to arch/arm/boot/tools and execute a make there
-to build the params-itsy program used to boot the kernel.
-
-In order to install the port of 2.4 to the itsy, You will need to set the
-configuration parameters in the monitor as follows::
-
- Arg 1:0x08340000, Arg2: 0xC0000000, Arg3:18 (0x12), Arg4:0
-
-Make sure the start-routine address is set to 0x00060000.
-
-Next, flash the params-itsy program to 0x00060000 ("p 1 0x00060000" in the
-flash menu) Flash the kernel in arch/arm/boot/zImage into 0x08340000
-("p 1 0x00340000"). Finally flash an initial ramdisk into 0xC8000000
-("p 2 0x0") We used ramdisk-2-30.gz from the 0.11 version directory on
-handhelds.org.
-
-The serial connection we established was at:
-
-8-bit data, no parity, 1 stop bit(s), 115200.00 b/s. in the monitor, in the
-params-itsy program, and in the kernel itself. This can be changed, but
-not easily. The monitor parameters are easily changed, the params program
-setup is assembly outl's, and the kernel is a configuration item specific to
-the itsy. (i.e. grep for CONFIG_SA1100_ITSY and you'll find where it is.)
-
-
-This should get you a properly booting 2.4 kernel on the itsy.
diff --git a/Documentation/arm/sa1100/nanoengine.rst b/Documentation/arm/sa1100/nanoengine.rst
deleted file mode 100644
index 47f1a14..0000000
--- a/Documentation/arm/sa1100/nanoengine.rst
+++ /dev/null
@@ -1,11 +0,0 @@
-==========
-nanoEngine
-==========
-
-"nanoEngine" is a SA1110 based single board computer from
-Bright Star Engineering Inc. See www.brightstareng.com/arm
-for more info.
-(Ref: Stuart Adams <sja@brightstareng.com>)
-
-Also visit Larry Doolittle's "Linux for the nanoEngine" site:
-http://www.brightstareng.com/arm/nanoeng.htm
diff --git a/Documentation/arm/sa1100/pangolin.rst b/Documentation/arm/sa1100/pangolin.rst
deleted file mode 100644
index f0c5c16..0000000
--- a/Documentation/arm/sa1100/pangolin.rst
+++ /dev/null
@@ -1,29 +0,0 @@
-========
-Pangolin
-========
-
-Pangolin is a StrongARM 1110-based evaluation platform produced
-by Dialogue Technology (http://www.dialogue.com.tw/).
-It has EISA slots for ease of configuration with SDRAM/Flash
-memory card, USB/Serial/Audio card, Compact Flash card,
-PCMCIA/IDE card and TFT-LCD card.
-
-To compile for Pangolin, you must issue the following commands::
-
- make pangolin_config
- make oldconfig
- make zImage
-
-Supported peripherals
-=====================
-
-- SA1110 serial port (UART1/UART2/UART3)
-- flash memory access
-- compact flash driver
-- UDA1341 sound driver
-- SA1100 LCD controller for 800x600 16bpp TFT-LCD
-- MQ-200 driver for 800x600 16bpp TFT-LCD
-- Penmount(touch panel) driver
-- PCMCIA driver
-- SMC91C94 LAN driver
-- IDE driver (experimental)
diff --git a/Documentation/arm/sa1100/pleb.rst b/Documentation/arm/sa1100/pleb.rst
deleted file mode 100644
index d5b7329..0000000
--- a/Documentation/arm/sa1100/pleb.rst
+++ /dev/null
@@ -1,13 +0,0 @@
-====
-PLEB
-====
-
-The PLEB project was started as a student initiative at the School of
-Computer Science and Engineering, University of New South Wales to make a
-pocket computer capable of running the Linux Kernel.
-
-PLEB support has yet to be fully integrated.
-
-For more information, see:
-
- http://www.cse.unsw.edu.au
diff --git a/Documentation/arm/sa1100/tifon.rst b/Documentation/arm/sa1100/tifon.rst
deleted file mode 100644
index c26e910..0000000
--- a/Documentation/arm/sa1100/tifon.rst
+++ /dev/null
@@ -1,7 +0,0 @@
-=====
-Tifon
-=====
-
-More info has to come...
-
-Contact: Peter Danielsson <peter.danielsson@era-t.ericsson.se>
diff --git a/Documentation/arm/sa1100/yopy.rst b/Documentation/arm/sa1100/yopy.rst
deleted file mode 100644
index 5b35a5f..0000000
--- a/Documentation/arm/sa1100/yopy.rst
+++ /dev/null
@@ -1,5 +0,0 @@
-====
-Yopy
-====
-
-See http://www.yopydeveloper.org for more.
diff --git a/Documentation/arm/samsung-s3c24xx/index.rst b/Documentation/arm/samsung-s3c24xx/index.rst
index 5b8a7f9..ccb951a 100644
--- a/Documentation/arm/samsung-s3c24xx/index.rst
+++ b/Documentation/arm/samsung-s3c24xx/index.rst
@@ -1,6 +1,6 @@
.. SPDX-License-Identifier: GPL-2.0
-==========================
+==========================
Samsung S3C24XX SoC Family
==========================
diff --git a/Documentation/arm/sh-mobile/.gitignore b/Documentation/arm/sh-mobile/.gitignore
deleted file mode 100644
index c928dbf3..0000000
--- a/Documentation/arm/sh-mobile/.gitignore
+++ /dev/null
@@ -1 +0,0 @@
-vrl4
diff --git a/Documentation/arm64/index.rst b/Documentation/arm64/index.rst
index 96b696b..5c0c69d 100644
--- a/Documentation/arm64/index.rst
+++ b/Documentation/arm64/index.rst
@@ -16,6 +16,7 @@
pointer-authentication
silicon-errata
sve
+ tagged-address-abi
tagged-pointers
.. only:: subproject and html
diff --git a/Documentation/arm64/kasan-offsets.sh b/Documentation/arm64/kasan-offsets.sh
new file mode 100644
index 0000000..2b7a021
--- /dev/null
+++ b/Documentation/arm64/kasan-offsets.sh
@@ -0,0 +1,27 @@
+#!/bin/sh
+
+# Print out the KASAN_SHADOW_OFFSETS required to place the KASAN SHADOW
+# start address at the mid-point of the kernel VA space
+
+print_kasan_offset () {
+ printf "%02d\t" $1
+ printf "0x%08x00000000\n" $(( (0xffffffff & (-1 << ($1 - 1 - 32))) \
+ + (1 << ($1 - 32 - $2)) \
+ - (1 << (64 - 32 - $2)) ))
+}
+
+echo KASAN_SHADOW_SCALE_SHIFT = 3
+printf "VABITS\tKASAN_SHADOW_OFFSET\n"
+print_kasan_offset 48 3
+print_kasan_offset 47 3
+print_kasan_offset 42 3
+print_kasan_offset 39 3
+print_kasan_offset 36 3
+echo
+echo KASAN_SHADOW_SCALE_SHIFT = 4
+printf "VABITS\tKASAN_SHADOW_OFFSET\n"
+print_kasan_offset 48 4
+print_kasan_offset 47 4
+print_kasan_offset 42 4
+print_kasan_offset 39 4
+print_kasan_offset 36 4
diff --git a/Documentation/arm64/memory.rst b/Documentation/arm64/memory.rst
index 464b880..b040909 100644
--- a/Documentation/arm64/memory.rst
+++ b/Documentation/arm64/memory.rst
@@ -14,6 +14,10 @@
64KB pages, only 2 levels of translation tables, allowing 42-bit (4TB)
virtual address, are used but the memory layout is the same.
+ARMv8.2 adds optional support for Large Virtual Address space. This is
+only available when running with a 64KB page size and expands the
+number of descriptors in the first level of translation.
+
User addresses have bits 63:48 set to 0 while the kernel addresses have
the same bits set to 1. TTBRx selection is given by bit 63 of the
virtual address. The swapper_pg_dir contains only kernel (global)
@@ -22,40 +26,43 @@
TTBR0.
-AArch64 Linux memory layout with 4KB pages + 3 levels::
-
- 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 (48-bit)::
Start End Size Use
-----------------------------------------------------------------------
0000000000000000 0000ffffffffffff 256TB user
- ffff000000000000 ffffffffffffffff 256TB kernel
+ ffff000000000000 ffff7fffffffffff 128TB kernel logical memory map
+ ffff800000000000 ffff9fffffffffff 32TB kasan shadow region
+ ffffa00000000000 ffffa00007ffffff 128MB bpf jit region
+ ffffa00008000000 ffffa0000fffffff 128MB modules
+ ffffa00010000000 fffffdffbffeffff ~93TB vmalloc
+ fffffdffbfff0000 fffffdfffe5f8fff ~998MB [guard region]
+ fffffdfffe5f9000 fffffdfffe9fffff 4124KB fixed mappings
+ fffffdfffea00000 fffffdfffebfffff 2MB [guard region]
+ fffffdfffec00000 fffffdffffbfffff 16MB PCI I/O space
+ fffffdffffc00000 fffffdffffdfffff 2MB [guard region]
+ fffffdffffe00000 ffffffffffdfffff 2TB vmemmap
+ ffffffffffe00000 ffffffffffffffff 2MB [guard region]
-AArch64 Linux memory layout with 64KB pages + 2 levels::
+AArch64 Linux memory layout with 64KB pages + 3 levels (52-bit with HW support)::
Start End Size Use
-----------------------------------------------------------------------
- 0000000000000000 000003ffffffffff 4TB user
- fffffc0000000000 ffffffffffffffff 4TB kernel
-
-
-AArch64 Linux memory layout with 64KB pages + 3 levels::
-
- 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.
+ 0000000000000000 000fffffffffffff 4PB user
+ fff0000000000000 fff7ffffffffffff 2PB kernel logical memory map
+ fff8000000000000 fffd9fffffffffff 1440TB [gap]
+ fffda00000000000 ffff9fffffffffff 512TB kasan shadow region
+ ffffa00000000000 ffffa00007ffffff 128MB bpf jit region
+ ffffa00008000000 ffffa0000fffffff 128MB modules
+ ffffa00010000000 fffff81ffffeffff ~88TB vmalloc
+ fffff81fffff0000 fffffc1ffe58ffff ~3TB [guard region]
+ fffffc1ffe590000 fffffc1ffe9fffff 4544KB fixed mappings
+ fffffc1ffea00000 fffffc1ffebfffff 2MB [guard region]
+ fffffc1ffec00000 fffffc1fffbfffff 16MB PCI I/O space
+ fffffc1fffc00000 fffffc1fffdfffff 2MB [guard region]
+ fffffc1fffe00000 ffffffffffdfffff 3968GB vmemmap
+ ffffffffffe00000 ffffffffffffffff 2MB [guard region]
Translation table lookup with 4KB pages::
@@ -83,7 +90,8 @@
| | | | [15:0] in-page offset
| | | +----------> [28:16] L3 index
| | +--------------------------> [41:29] L2 index
- | +-------------------------------> [47:42] L1 index
+ | +-------------------------------> [47:42] L1 index (48-bit)
+ | [51:42] L1 index (52-bit)
+-------------------------------------------------> [63] TTBR0/1
@@ -96,3 +104,62 @@
When using KVM with the Virtualization Host Extensions, no additional
mappings are created, since the host kernel runs directly in EL2.
+
+52-bit VA support in the kernel
+-------------------------------
+If the ARMv8.2-LVA optional feature is present, and we are running
+with a 64KB page size; then it is possible to use 52-bits of address
+space for both userspace and kernel addresses. However, any kernel
+binary that supports 52-bit must also be able to fall back to 48-bit
+at early boot time if the hardware feature is not present.
+
+This fallback mechanism necessitates the kernel .text to be in the
+higher addresses such that they are invariant to 48/52-bit VAs. Due
+to the kasan shadow being a fraction of the entire kernel VA space,
+the end of the kasan shadow must also be in the higher half of the
+kernel VA space for both 48/52-bit. (Switching from 48-bit to 52-bit,
+the end of the kasan shadow is invariant and dependent on ~0UL,
+whilst the start address will "grow" towards the lower addresses).
+
+In order to optimise phys_to_virt and virt_to_phys, the PAGE_OFFSET
+is kept constant at 0xFFF0000000000000 (corresponding to 52-bit),
+this obviates the need for an extra variable read. The physvirt
+offset and vmemmap offsets are computed at early boot to enable
+this logic.
+
+As a single binary will need to support both 48-bit and 52-bit VA
+spaces, the VMEMMAP must be sized large enough for 52-bit VAs and
+also must be sized large enought to accommodate a fixed PAGE_OFFSET.
+
+Most code in the kernel should not need to consider the VA_BITS, for
+code that does need to know the VA size the variables are
+defined as follows:
+
+VA_BITS constant the *maximum* VA space size
+
+VA_BITS_MIN constant the *minimum* VA space size
+
+vabits_actual variable the *actual* VA space size
+
+
+Maximum and minimum sizes can be useful to ensure that buffers are
+sized large enough or that addresses are positioned close enough for
+the "worst" case.
+
+52-bit userspace VAs
+--------------------
+To maintain compatibility with software that relies on the ARMv8.0
+VA space maximum size of 48-bits, the kernel will, by default,
+return virtual addresses to userspace from a 48-bit range.
+
+Software can "opt-in" to receiving VAs from a 52-bit space by
+specifying an mmap hint parameter that is larger than 48-bit.
+For example:
+ maybe_high_address = mmap(~0UL, size, prot, flags,...);
+
+It is also possible to build a debug kernel that returns addresses
+from a 52-bit space by enabling the following kernel config options:
+ CONFIG_EXPERT=y && CONFIG_ARM64_FORCE_52BIT=y
+
+Note that this option is only intended for debugging applications
+and should not be used in production.
diff --git a/Documentation/arm64/silicon-errata.rst b/Documentation/arm64/silicon-errata.rst
index 3e57d09..17ea3fe 100644
--- a/Documentation/arm64/silicon-errata.rst
+++ b/Documentation/arm64/silicon-errata.rst
@@ -115,6 +115,8 @@
+----------------+-----------------+-----------------+-----------------------------+
| Hisilicon | Hip0{6,7} | #161010701 | N/A |
+----------------+-----------------+-----------------+-----------------------------+
+| Hisilicon | Hip0{6,7} | #161010803 | N/A |
++----------------+-----------------+-----------------+-----------------------------+
| Hisilicon | Hip07 | #161600802 | HISILICON_ERRATUM_161600802 |
+----------------+-----------------+-----------------+-----------------------------+
| Hisilicon | Hip08 SMMU PMCG | #162001800 | N/A |
diff --git a/Documentation/arm64/tagged-address-abi.rst b/Documentation/arm64/tagged-address-abi.rst
new file mode 100644
index 0000000..d4a85d5
--- /dev/null
+++ b/Documentation/arm64/tagged-address-abi.rst
@@ -0,0 +1,156 @@
+==========================
+AArch64 TAGGED ADDRESS ABI
+==========================
+
+Authors: Vincenzo Frascino <vincenzo.frascino@arm.com>
+ Catalin Marinas <catalin.marinas@arm.com>
+
+Date: 21 August 2019
+
+This document describes the usage and semantics of the Tagged Address
+ABI on AArch64 Linux.
+
+1. Introduction
+---------------
+
+On AArch64 the ``TCR_EL1.TBI0`` bit is set by default, allowing
+userspace (EL0) to perform memory accesses through 64-bit pointers with
+a non-zero top byte. This document describes the relaxation of the
+syscall ABI that allows userspace to pass certain tagged pointers to
+kernel syscalls.
+
+2. AArch64 Tagged Address ABI
+-----------------------------
+
+From the kernel syscall interface perspective and for the purposes of
+this document, a "valid tagged pointer" is a pointer with a potentially
+non-zero top-byte that references an address in the user process address
+space obtained in one of the following ways:
+
+- ``mmap()`` syscall where either:
+
+ - flags have the ``MAP_ANONYMOUS`` bit set or
+ - the file descriptor refers to a regular file (including those
+ returned by ``memfd_create()``) or ``/dev/zero``
+
+- ``brk()`` syscall (i.e. the heap area between the initial location of
+ the program break at process creation and its current location).
+
+- any memory mapped by the kernel in the address space of the process
+ during creation and with the same restrictions as for ``mmap()`` above
+ (e.g. data, bss, stack).
+
+The AArch64 Tagged Address ABI has two stages of relaxation depending
+how the user addresses are used by the kernel:
+
+1. User addresses not accessed by the kernel but used for address space
+ management (e.g. ``mmap()``, ``mprotect()``, ``madvise()``). The use
+ of valid tagged pointers in this context is always allowed.
+
+2. User addresses accessed by the kernel (e.g. ``write()``). This ABI
+ relaxation is disabled by default and the application thread needs to
+ explicitly enable it via ``prctl()`` as follows:
+
+ - ``PR_SET_TAGGED_ADDR_CTRL``: enable or disable the AArch64 Tagged
+ Address ABI for the calling thread.
+
+ The ``(unsigned int) arg2`` argument is a bit mask describing the
+ control mode used:
+
+ - ``PR_TAGGED_ADDR_ENABLE``: enable AArch64 Tagged Address ABI.
+ Default status is disabled.
+
+ Arguments ``arg3``, ``arg4``, and ``arg5`` must be 0.
+
+ - ``PR_GET_TAGGED_ADDR_CTRL``: get the status of the AArch64 Tagged
+ Address ABI for the calling thread.
+
+ Arguments ``arg2``, ``arg3``, ``arg4``, and ``arg5`` must be 0.
+
+ The ABI properties described above are thread-scoped, inherited on
+ clone() and fork() and cleared on exec().
+
+ Calling ``prctl(PR_SET_TAGGED_ADDR_CTRL, PR_TAGGED_ADDR_ENABLE, 0, 0, 0)``
+ returns ``-EINVAL`` if the AArch64 Tagged Address ABI is globally
+ disabled by ``sysctl abi.tagged_addr_disabled=1``. The default
+ ``sysctl abi.tagged_addr_disabled`` configuration is 0.
+
+When the AArch64 Tagged Address ABI is enabled for a thread, the
+following behaviours are guaranteed:
+
+- All syscalls except the cases mentioned in section 3 can accept any
+ valid tagged pointer.
+
+- The syscall behaviour is undefined for invalid tagged pointers: it may
+ result in an error code being returned, a (fatal) signal being raised,
+ or other modes of failure.
+
+- The syscall behaviour for a valid tagged pointer is the same as for
+ the corresponding untagged pointer.
+
+
+A definition of the meaning of tagged pointers on AArch64 can be found
+in Documentation/arm64/tagged-pointers.rst.
+
+3. AArch64 Tagged Address ABI Exceptions
+-----------------------------------------
+
+The following system call parameters must be untagged regardless of the
+ABI relaxation:
+
+- ``prctl()`` other than pointers to user data either passed directly or
+ indirectly as arguments to be accessed by the kernel.
+
+- ``ioctl()`` other than pointers to user data either passed directly or
+ indirectly as arguments to be accessed by the kernel.
+
+- ``shmat()`` and ``shmdt()``.
+
+Any attempt to use non-zero tagged pointers may result in an error code
+being returned, a (fatal) signal being raised, or other modes of
+failure.
+
+4. Example of correct usage
+---------------------------
+.. code-block:: c
+
+ #include <stdlib.h>
+ #include <string.h>
+ #include <unistd.h>
+ #include <sys/mman.h>
+ #include <sys/prctl.h>
+
+ #define PR_SET_TAGGED_ADDR_CTRL 55
+ #define PR_TAGGED_ADDR_ENABLE (1UL << 0)
+
+ #define TAG_SHIFT 56
+
+ int main(void)
+ {
+ int tbi_enabled = 0;
+ unsigned long tag = 0;
+ char *ptr;
+
+ /* check/enable the tagged address ABI */
+ if (!prctl(PR_SET_TAGGED_ADDR_CTRL, PR_TAGGED_ADDR_ENABLE, 0, 0, 0))
+ tbi_enabled = 1;
+
+ /* memory allocation */
+ ptr = mmap(NULL, sysconf(_SC_PAGE_SIZE), PROT_READ | PROT_WRITE,
+ MAP_PRIVATE | MAP_ANONYMOUS, -1, 0);
+ if (ptr == MAP_FAILED)
+ return 1;
+
+ /* set a non-zero tag if the ABI is available */
+ if (tbi_enabled)
+ tag = rand() & 0xff;
+ ptr = (char *)((unsigned long)ptr | (tag << TAG_SHIFT));
+
+ /* memory access to a tagged address */
+ strcpy(ptr, "tagged pointer\n");
+
+ /* syscall with a tagged pointer */
+ write(1, ptr, strlen(ptr));
+
+ return 0;
+ }
diff --git a/Documentation/arm64/tagged-pointers.rst b/Documentation/arm64/tagged-pointers.rst
index 2acdec3..eab4323 100644
--- a/Documentation/arm64/tagged-pointers.rst
+++ b/Documentation/arm64/tagged-pointers.rst
@@ -20,7 +20,9 @@
--------------------------------------
All interpretation of userspace memory addresses by the kernel assumes
-an address tag of 0x00.
+an address tag of 0x00, unless the application enables the AArch64
+Tagged Address ABI explicitly
+(Documentation/arm64/tagged-address-abi.rst).
This includes, but is not limited to, addresses found in:
@@ -33,13 +35,15 @@
- the frame pointer (x29) and frame records, e.g. when interpreting
them to generate a backtrace or call graph.
-Using non-zero address tags in any of these locations may result in an
-error code being returned, a (fatal) signal being raised, or other modes
-of failure.
+Using non-zero address tags in any of these locations when the
+userspace application did not enable the AArch64 Tagged Address ABI may
+result in an error code being returned, a (fatal) signal being raised,
+or other modes of failure.
-For these reasons, passing non-zero address tags to the kernel via
-system calls is forbidden, and using a non-zero address tag for sp is
-strongly discouraged.
+For these reasons, when the AArch64 Tagged Address ABI is disabled,
+passing non-zero address tags to the kernel via system calls is
+forbidden, and using a non-zero address tag for sp is strongly
+discouraged.
Programs maintaining a frame pointer and frame records that use non-zero
address tags may suffer impaired or inaccurate debug and profiling
@@ -59,6 +63,9 @@
The architecture prevents the use of a tagged PC, so the upper byte will
be set to a sign-extension of bit 55 on exception return.
+This behaviour is maintained when the AArch64 Tagged Address ABI is
+enabled.
+
Other considerations
--------------------
diff --git a/Documentation/auxdisplay/cfag12864b b/Documentation/auxdisplay/cfag12864b
deleted file mode 100644
index 12fd51b..0000000
--- a/Documentation/auxdisplay/cfag12864b
+++ /dev/null
@@ -1,105 +0,0 @@
- ===================================
- cfag12864b LCD Driver Documentation
- ===================================
-
-License: GPLv2
-Author & Maintainer: Miguel Ojeda Sandonis
-Date: 2006-10-27
-
-
-
---------
-0. INDEX
---------
-
- 1. DRIVER INFORMATION
- 2. DEVICE INFORMATION
- 3. WIRING
- 4. USERSPACE PROGRAMMING
-
-
----------------------
-1. DRIVER INFORMATION
----------------------
-
-This driver supports a cfag12864b LCD.
-
-
----------------------
-2. DEVICE INFORMATION
----------------------
-
-Manufacturer: Crystalfontz
-Device Name: Crystalfontz 12864b LCD Series
-Device Code: cfag12864b
-Webpage: http://www.crystalfontz.com
-Device Webpage: http://www.crystalfontz.com/products/12864b/
-Type: LCD (Liquid Crystal Display)
-Width: 128
-Height: 64
-Colors: 2 (B/N)
-Controller: ks0108
-Controllers: 2
-Pages: 8 each controller
-Addresses: 64 each page
-Data size: 1 byte each address
-Memory size: 2 * 8 * 64 * 1 = 1024 bytes = 1 Kbyte
-
-
----------
-3. WIRING
----------
-
-The cfag12864b LCD Series don't have official wiring.
-
-The common wiring is done to the parallel port as shown:
-
-Parallel Port cfag12864b
-
- Name Pin# Pin# Name
-
-Strobe ( 1)------------------------------(17) Enable
-Data 0 ( 2)------------------------------( 4) Data 0
-Data 1 ( 3)------------------------------( 5) Data 1
-Data 2 ( 4)------------------------------( 6) Data 2
-Data 3 ( 5)------------------------------( 7) Data 3
-Data 4 ( 6)------------------------------( 8) Data 4
-Data 5 ( 7)------------------------------( 9) Data 5
-Data 6 ( 8)------------------------------(10) Data 6
-Data 7 ( 9)------------------------------(11) Data 7
- (10) [+5v]---( 1) Vdd
- (11) [GND]---( 2) Ground
- (12) [+5v]---(14) Reset
- (13) [GND]---(15) Read / Write
- Line (14)------------------------------(13) Controller Select 1
- (15)
- Init (16)------------------------------(12) Controller Select 2
-Select (17)------------------------------(16) Data / Instruction
-Ground (18)---[GND] [+5v]---(19) LED +
-Ground (19)---[GND]
-Ground (20)---[GND] E A Values:
-Ground (21)---[GND] [GND]---[P1]---(18) Vee - R = Resistor = 22 ohm
-Ground (22)---[GND] | - P1 = Preset = 10 Kohm
-Ground (23)---[GND] ---- S ------( 3) V0 - P2 = Preset = 1 Kohm
-Ground (24)---[GND] | |
-Ground (25)---[GND] [GND]---[P2]---[R]---(20) LED -
-
-
-------------------------
-4. USERSPACE PROGRAMMING
-------------------------
-
-The cfag12864bfb describes a framebuffer device (/dev/fbX).
-
-It has a size of 1024 bytes = 1 Kbyte.
-Each bit represents one pixel. If the bit is high, the pixel will
-turn on. If the pixel is low, the pixel will turn off.
-
-You can use the framebuffer as a file: fopen, fwrite, fclose...
-Although the LCD won't get updated until the next refresh time arrives.
-
-Also, you can mmap the framebuffer: open & mmap, munmap & close...
-which is the best option for most uses.
-
-Check samples/auxdisplay/cfag12864b-example.c
-for a real working userspace complete program with usage examples.
diff --git a/Documentation/auxdisplay/ks0108 b/Documentation/auxdisplay/ks0108
deleted file mode 100644
index 8ddda0c..0000000
--- a/Documentation/auxdisplay/ks0108
+++ /dev/null
@@ -1,55 +0,0 @@
- ==========================================
- ks0108 LCD Controller Driver Documentation
- ==========================================
-
-License: GPLv2
-Author & Maintainer: Miguel Ojeda Sandonis
-Date: 2006-10-27
-
-
-
---------
-0. INDEX
---------
-
- 1. DRIVER INFORMATION
- 2. DEVICE INFORMATION
- 3. WIRING
-
-
----------------------
-1. DRIVER INFORMATION
----------------------
-
-This driver supports the ks0108 LCD controller.
-
-
----------------------
-2. DEVICE INFORMATION
----------------------
-
-Manufacturer: Samsung
-Device Name: KS0108 LCD Controller
-Device Code: ks0108
-Webpage: -
-Device Webpage: -
-Type: LCD Controller (Liquid Crystal Display Controller)
-Width: 64
-Height: 64
-Colors: 2 (B/N)
-Pages: 8
-Addresses: 64 each page
-Data size: 1 byte each address
-Memory size: 8 * 64 * 1 = 512 bytes
-
-
----------
-3. WIRING
----------
-
-The driver supports data parallel port wiring.
-
-If you aren't building LCD related hardware, you should check
-your LCD specific wiring information in the same folder.
-
-For example, check Documentation/auxdisplay/cfag12864b.
diff --git a/Documentation/block/null_blk.rst b/Documentation/block/null_blk.rst
index 31451d8..edbbab2 100644
--- a/Documentation/block/null_blk.rst
+++ b/Documentation/block/null_blk.rst
@@ -1,19 +1,16 @@
+.. SPDX-License-Identifier: GPL-2.0
+
========================
Null block device driver
========================
-1. Overview
-===========
+Overview
+========
-The null block device (/dev/nullb*) is used for benchmarking the various
+The null block device (``/dev/nullb*``) is used for benchmarking the various
block-layer implementations. It emulates a block device of X gigabytes in size.
-The following instances are possible:
-
- Single-queue block-layer
-
- - Request-based.
- - Single submission queue per device.
- - Implements IO scheduling algorithms (CFQ, Deadline, noop).
+It does not execute any read/write operation, just mark them as complete in
+the request queue. The following instances are possible:
Multi-queue block-layer
@@ -27,15 +24,15 @@
All of them have a completion queue for each core in the system.
-2. Module parameters applicable for all instances
-=================================================
+Module parameters
+=================
queue_mode=[0-2]: Default: 2-Multi-queue
Selects which block-layer the module should instantiate with.
= ============
0 Bio-based
- 1 Single-queue
+ 1 Single-queue (deprecated)
2 Multi-queue
= ============
@@ -67,7 +64,7 @@
completion_nsec=[ns]: Default: 10,000ns
Combined with irqmode=2 (timer). The time each completion event must wait.
-submit_queues=[1..nr_cpus]:
+submit_queues=[1..nr_cpus]: Default: 1
The number of submission queues attached to the device driver. If unset, it
defaults to 1. For multi-queue, it is ignored when use_per_node_hctx module
parameter is 1.
@@ -75,9 +72,11 @@
hw_queue_depth=[0..qdepth]: Default: 64
The hardware queue depth of the device.
-III: Multi-queue specific parameters
+Multi-queue specific parameters
+-------------------------------
use_per_node_hctx=[0/1]: Default: 0
+ Number of hardware context queues.
= =====================================================================
0 The number of submit queues are set to the value of the submit_queues
@@ -87,6 +86,7 @@
= =====================================================================
no_sched=[0/1]: Default: 0
+ Enable/disable the io scheduler.
= ======================================
0 nullb* use default blk-mq io scheduler
@@ -94,6 +94,7 @@
= ======================================
blocking=[0/1]: Default: 0
+ Blocking behavior of the request queue.
= ===============================================================
0 Register as a non-blocking blk-mq driver device.
@@ -103,6 +104,7 @@
= ===============================================================
shared_tags=[0/1]: Default: 0
+ Sharing tags between devices.
= ================================================================
0 Tag set is not shared.
@@ -111,6 +113,7 @@
= ================================================================
zoned=[0/1]: Default: 0
+ Device is a random-access or a zoned block device.
= ======================================================================
0 Block device is exposed as a random-access block device.
diff --git a/Documentation/block/switching-sched.rst b/Documentation/block/switching-sched.rst
index 4204241..520f6b8 100644
--- a/Documentation/block/switching-sched.rst
+++ b/Documentation/block/switching-sched.rst
@@ -2,10 +2,6 @@
Switching Scheduler
===================
-To choose IO schedulers at boot time, use the argument 'elevator=deadline'.
-'noop' and 'cfq' (the default) are also available. IO schedulers are assigned
-globally at boot time only presently.
-
Each io queue has a set of io scheduler tunables associated with it. These
tunables control how the io scheduler works. You can find these entries
in::
diff --git a/Documentation/bpf/prog_flow_dissector.rst b/Documentation/bpf/prog_flow_dissector.rst
index ed343ab..a78bf03 100644
--- a/Documentation/bpf/prog_flow_dissector.rst
+++ b/Documentation/bpf/prog_flow_dissector.rst
@@ -26,6 +26,7 @@
* ``nhoff`` - initial offset of the networking header
* ``thoff`` - initial offset of the transport header, initialized to nhoff
* ``n_proto`` - L3 protocol type, parsed out of L2 header
+ * ``flags`` - optional flags
Flow dissector BPF program should fill out the rest of the ``struct
bpf_flow_keys`` fields. Input arguments ``nhoff/thoff/n_proto`` should be
@@ -101,6 +102,23 @@
handle both cases.
+Flags
+=====
+
+``flow_keys->flags`` might contain optional input flags that work as follows:
+
+* ``BPF_FLOW_DISSECTOR_F_PARSE_1ST_FRAG`` - tells BPF flow dissector to
+ continue parsing first fragment; the default expected behavior is that
+ flow dissector returns as soon as it finds out that the packet is fragmented;
+ used by ``eth_get_headlen`` to estimate length of all headers for GRO.
+* ``BPF_FLOW_DISSECTOR_F_STOP_AT_FLOW_LABEL`` - tells BPF flow dissector to
+ stop parsing as soon as it reaches IPv6 flow label; used by
+ ``___skb_get_hash`` and ``__skb_get_hash_symmetric`` to get flow hash.
+* ``BPF_FLOW_DISSECTOR_F_STOP_AT_ENCAP`` - tells BPF flow dissector to stop
+ parsing as soon as it reaches encapsulated headers; used by routing
+ infrastructure.
+
+
Reference Implementation
========================
diff --git a/Documentation/core-api/index.rst b/Documentation/core-api/index.rst
index da0ed97..fa16a05 100644
--- a/Documentation/core-api/index.rst
+++ b/Documentation/core-api/index.rst
@@ -25,6 +25,7 @@
librs
genalloc
errseq
+ packing
printk-formats
circular-buffers
generic-radix-tree
@@ -48,7 +49,7 @@
debug-objects
tracepoint
-.. only:: subproject
+.. only:: subproject and html
Indices
=======
diff --git a/Documentation/core-api/kernel-api.rst b/Documentation/core-api/kernel-api.rst
index 08af5ca..f77de49 100644
--- a/Documentation/core-api/kernel-api.rst
+++ b/Documentation/core-api/kernel-api.rst
@@ -42,6 +42,9 @@
.. kernel-doc:: lib/string.c
:export:
+.. kernel-doc:: include/linux/string.h
+ :internal:
+
.. kernel-doc:: mm/util.c
:functions: kstrdup kstrdup_const kstrndup kmemdup kmemdup_nul memdup_user
vmemdup_user strndup_user memdup_user_nul
diff --git a/Documentation/core-api/packing.rst b/Documentation/core-api/packing.rst
new file mode 100644
index 0000000..d8c341f
--- /dev/null
+++ b/Documentation/core-api/packing.rst
@@ -0,0 +1,166 @@
+================================================
+Generic bitfield packing and unpacking functions
+================================================
+
+Problem statement
+-----------------
+
+When working with hardware, one has to choose between several approaches of
+interfacing with it.
+One can memory-map a pointer to a carefully crafted struct over the hardware
+device's memory region, and access its fields as struct members (potentially
+declared as bitfields). But writing code this way would make it less portable,
+due to potential endianness mismatches between the CPU and the hardware device.
+Additionally, one has to pay close attention when translating register
+definitions from the hardware documentation into bit field indices for the
+structs. Also, some hardware (typically networking equipment) tends to group
+its register fields in ways that violate any reasonable word boundaries
+(sometimes even 64 bit ones). This creates the inconvenience of having to
+define "high" and "low" portions of register fields within the struct.
+A more robust alternative to struct field definitions would be to extract the
+required fields by shifting the appropriate number of bits. But this would
+still not protect from endianness mismatches, except if all memory accesses
+were performed byte-by-byte. Also the code can easily get cluttered, and the
+high-level idea might get lost among the many bit shifts required.
+Many drivers take the bit-shifting approach and then attempt to reduce the
+clutter with tailored macros, but more often than not these macros take
+shortcuts that still prevent the code from being truly portable.
+
+The solution
+------------
+
+This API deals with 2 basic operations:
+
+ - Packing a CPU-usable number into a memory buffer (with hardware
+ constraints/quirks)
+ - Unpacking a memory buffer (which has hardware constraints/quirks)
+ into a CPU-usable number.
+
+The API offers an abstraction over said hardware constraints and quirks,
+over CPU endianness and therefore between possible mismatches between
+the two.
+
+The basic unit of these API functions is the u64. From the CPU's
+perspective, bit 63 always means bit offset 7 of byte 7, albeit only
+logically. The question is: where do we lay this bit out in memory?
+
+The following examples cover the memory layout of a packed u64 field.
+The byte offsets in the packed buffer are always implicitly 0, 1, ... 7.
+What the examples show is where the logical bytes and bits sit.
+
+1. Normally (no quirks), we would do it like this:
+
+::
+
+ 63 62 61 60 59 58 57 56 55 54 53 52 51 50 49 48 47 46 45 44 43 42 41 40 39 38 37 36 35 34 33 32
+ 7 6 5 4
+ 31 30 29 28 27 26 25 24 23 22 21 20 19 18 17 16 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0
+ 3 2 1 0
+
+That is, the MSByte (7) of the CPU-usable u64 sits at memory offset 0, and the
+LSByte (0) of the u64 sits at memory offset 7.
+This corresponds to what most folks would regard to as "big endian", where
+bit i corresponds to the number 2^i. This is also referred to in the code
+comments as "logical" notation.
+
+
+2. If QUIRK_MSB_ON_THE_RIGHT is set, we do it like this:
+
+::
+
+ 56 57 58 59 60 61 62 63 48 49 50 51 52 53 54 55 40 41 42 43 44 45 46 47 32 33 34 35 36 37 38 39
+ 7 6 5 4
+ 24 25 26 27 28 29 30 31 16 17 18 19 20 21 22 23 8 9 10 11 12 13 14 15 0 1 2 3 4 5 6 7
+ 3 2 1 0
+
+That is, QUIRK_MSB_ON_THE_RIGHT does not affect byte positioning, but
+inverts bit offsets inside a byte.
+
+
+3. If QUIRK_LITTLE_ENDIAN is set, we do it like this:
+
+::
+
+ 39 38 37 36 35 34 33 32 47 46 45 44 43 42 41 40 55 54 53 52 51 50 49 48 63 62 61 60 59 58 57 56
+ 4 5 6 7
+ 7 6 5 4 3 2 1 0 15 14 13 12 11 10 9 8 23 22 21 20 19 18 17 16 31 30 29 28 27 26 25 24
+ 0 1 2 3
+
+Therefore, QUIRK_LITTLE_ENDIAN means that inside the memory region, every
+byte from each 4-byte word is placed at its mirrored position compared to
+the boundary of that word.
+
+4. If QUIRK_MSB_ON_THE_RIGHT and QUIRK_LITTLE_ENDIAN are both set, we do it
+ like this:
+
+::
+
+ 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63
+ 4 5 6 7
+ 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31
+ 0 1 2 3
+
+
+5. If just QUIRK_LSW32_IS_FIRST is set, we do it like this:
+
+::
+
+ 31 30 29 28 27 26 25 24 23 22 21 20 19 18 17 16 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0
+ 3 2 1 0
+ 63 62 61 60 59 58 57 56 55 54 53 52 51 50 49 48 47 46 45 44 43 42 41 40 39 38 37 36 35 34 33 32
+ 7 6 5 4
+
+In this case the 8 byte memory region is interpreted as follows: first
+4 bytes correspond to the least significant 4-byte word, next 4 bytes to
+the more significant 4-byte word.
+
+
+6. If QUIRK_LSW32_IS_FIRST and QUIRK_MSB_ON_THE_RIGHT are set, we do it like
+ this:
+
+::
+
+ 24 25 26 27 28 29 30 31 16 17 18 19 20 21 22 23 8 9 10 11 12 13 14 15 0 1 2 3 4 5 6 7
+ 3 2 1 0
+ 56 57 58 59 60 61 62 63 48 49 50 51 52 53 54 55 40 41 42 43 44 45 46 47 32 33 34 35 36 37 38 39
+ 7 6 5 4
+
+
+7. If QUIRK_LSW32_IS_FIRST and QUIRK_LITTLE_ENDIAN are set, it looks like
+ this:
+
+::
+
+ 7 6 5 4 3 2 1 0 15 14 13 12 11 10 9 8 23 22 21 20 19 18 17 16 31 30 29 28 27 26 25 24
+ 0 1 2 3
+ 39 38 37 36 35 34 33 32 47 46 45 44 43 42 41 40 55 54 53 52 51 50 49 48 63 62 61 60 59 58 57 56
+ 4 5 6 7
+
+
+8. If QUIRK_LSW32_IS_FIRST, QUIRK_LITTLE_ENDIAN and QUIRK_MSB_ON_THE_RIGHT
+ are set, it looks like this:
+
+::
+
+ 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31
+ 0 1 2 3
+ 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63
+ 4 5 6 7
+
+
+We always think of our offsets as if there were no quirk, and we translate
+them afterwards, before accessing the memory region.
+
+Intended use
+------------
+
+Drivers that opt to use this API first need to identify which of the above 3
+quirk combinations (for a total of 8) match what the hardware documentation
+describes. Then they should wrap the packing() function, creating a new
+xxx_packing() that calls it using the proper QUIRK_* one-hot bits set.
+
+The packing() function returns an int-encoded error code, which protects the
+programmer against incorrect API use. The errors are not expected to occur
+durring runtime, therefore it is reasonable for xxx_packing() to return void
+and simply swallow those errors. Optionally it can dump stack or print the
+error description.
diff --git a/Documentation/core-api/printk-formats.rst b/Documentation/core-api/printk-formats.rst
index c6224d0..ecbebf4 100644
--- a/Documentation/core-api/printk-formats.rst
+++ b/Documentation/core-api/printk-formats.rst
@@ -13,10 +13,10 @@
If variable is of Type, use printk format specifier:
------------------------------------------------------------
- char %hhd or %hhx
- unsigned char %hhu or %hhx
- short int %hd or %hx
- unsigned short int %hu or %hx
+ char %d or %x
+ unsigned char %u or %x
+ short int %d or %x
+ unsigned short int %u or %x
int %d or %x
unsigned int %u or %x
long %ld or %lx
@@ -25,10 +25,10 @@
unsigned long long %llu or %llx
size_t %zu or %zx
ssize_t %zd or %zx
- s8 %hhd or %hhx
- u8 %hhu or %hhx
- s16 %hd or %hx
- u16 %hu or %hx
+ s8 %d or %x
+ u8 %u or %x
+ s16 %d or %x
+ u16 %u or %x
s32 %d or %x
u32 %u or %x
s64 %lld or %llx
diff --git a/Documentation/cpu-freq/core.txt b/Documentation/cpu-freq/core.txt
index 55193e6..ed577d9 100644
--- a/Documentation/cpu-freq/core.txt
+++ b/Documentation/cpu-freq/core.txt
@@ -57,19 +57,11 @@
2.1 CPUFreq policy notifiers
----------------------------
-These are notified when a new policy is intended to be set. Each
-CPUFreq policy notifier is called twice for a policy transition:
+These are notified when a new policy is created or removed.
-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
- 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 phase is specified in the second argument to the notifier. The phase is
+CPUFREQ_CREATE_POLICY when the policy is first created and it is
+CPUFREQ_REMOVE_POLICY when the policy is removed.
The third argument, a void *pointer, points to a struct cpufreq_policy
consisting of several values, including min, max (the lower and upper
diff --git a/Documentation/crypto/crypto_engine.rst b/Documentation/crypto/crypto_engine.rst
index 236c674..3baa23c 100644
--- a/Documentation/crypto/crypto_engine.rst
+++ b/Documentation/crypto/crypto_engine.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GPL-2.0
+
Crypto Engine
=============
diff --git a/Documentation/devicetree/bindings/arm/actions.txt b/Documentation/devicetree/bindings/arm/actions.txt
deleted file mode 100644
index d54f33c..0000000
--- a/Documentation/devicetree/bindings/arm/actions.txt
+++ /dev/null
@@ -1,56 +0,0 @@
-Actions Semi platforms device tree bindings
--------------------------------------------
-
-
-S500 SoC
-========
-
-Required root node properties:
-
- - compatible : must contain "actions,s500"
-
-
-Modules:
-
-Root node property compatible must contain, depending on module:
-
- - LeMaker Guitar: "lemaker,guitar"
-
-
-Boards:
-
-Root node property compatible must contain, depending on board:
-
- - Allo.com Sparky: "allo,sparky"
- - Cubietech CubieBoard6: "cubietech,cubieboard6"
- - LeMaker Guitar Base Board rev. B: "lemaker,guitar-bb-rev-b", "lemaker,guitar"
-
-
-S700 SoC
-========
-
-Required root node properties:
-
-- compatible : must contain "actions,s700"
-
-
-Boards:
-
-Root node property compatible must contain, depending on board:
-
- - Cubietech CubieBoard7: "cubietech,cubieboard7"
-
-
-S900 SoC
-========
-
-Required root node properties:
-
-- compatible : must contain "actions,s900"
-
-
-Boards:
-
-Root node property compatible must contain, depending on board:
-
- - uCRobotics Bubblegum-96: "ucrobotics,bubblegum-96"
diff --git a/Documentation/devicetree/bindings/arm/actions.yaml b/Documentation/devicetree/bindings/arm/actions.yaml
new file mode 100644
index 0000000..ace3fda
--- /dev/null
+++ b/Documentation/devicetree/bindings/arm/actions.yaml
@@ -0,0 +1,38 @@
+# SPDX-License-Identifier: GPL-2.0-or-later OR BSD-2-Clause
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/arm/actions.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Actions Semi platforms device tree bindings
+
+maintainers:
+ - Andreas Färber <afaerber@suse.de>
+ - Manivannan Sadhasivam <manivannan.sadhasivam@linaro.org>
+
+properties:
+ compatible:
+ oneOf:
+ # The Actions Semi S500 is a quad-core ARM Cortex-A9 SoC.
+ - items:
+ - enum:
+ - allo,sparky # Allo.com Sparky
+ - cubietech,cubieboard6 # Cubietech CubieBoard6
+ - const: actions,s500
+ - items:
+ - enum:
+ - lemaker,guitar-bb-rev-b # LeMaker Guitar Base Board rev. B
+ - const: lemaker,guitar
+ - const: actions,s500
+
+ # The Actions Semi S700 is a quad-core ARM Cortex-A53 SoC.
+ - items:
+ - enum:
+ - cubietech,cubieboard7 # Cubietech CubieBoard7
+ - const: actions,s700
+
+ # The Actions Semi S900 is a quad-core ARM Cortex-A53 SoC.
+ - items:
+ - enum:
+ - ucrobotics,bubblegum-96 # uCRobotics Bubblegum-96
+ - const: actions,s900
diff --git a/Documentation/devicetree/bindings/arm/amlogic.yaml b/Documentation/devicetree/bindings/arm/amlogic.yaml
index 325c6fd..99015ce 100644
--- a/Documentation/devicetree/bindings/arm/amlogic.yaml
+++ b/Documentation/devicetree/bindings/arm/amlogic.yaml
@@ -91,13 +91,11 @@
- description: Boards with the Amlogic Meson GXL S905X SoC
items:
- enum:
- - amediatech,x96-max
- amlogic,p212
- hwacom,amazetv
- khadas,vim
- libretech,cc
- nexbox,a95x
- - seirobotics,sei510
- const: amlogic,s905x
- const: amlogic,meson-gxl
@@ -129,16 +127,33 @@
- const: amlogic,a113d
- const: amlogic,meson-axg
- - description: Boards with the Amlogic Meson G12A S905D2 SoC
+ - description: Boards with the Amlogic Meson G12A S905D2/X2/Y2 SoC
items:
- enum:
+ - amediatech,x96-max
- amlogic,u200
+ - seirobotics,sei510
- const: amlogic,g12a
+ - description: Boards with the Amlogic Meson G12B A311D SoC
+ items:
+ - enum:
+ - khadas,vim3
+ - const: amlogic,a311d
+ - const: amlogic,g12b
+
- description: Boards with the Amlogic Meson G12B S922X SoC
items:
- enum:
- hardkernel,odroid-n2
+ - khadas,vim3
+ - const: amlogic,s922x
- const: amlogic,g12b
+ - description: Boards with the Amlogic Meson SM1 S905X3/D3/Y3 SoC
+ items:
+ - enum:
+ - seirobotics,sei610
+ - khadas,vim3l
+ - const: amlogic,sm1
...
diff --git a/Documentation/devicetree/bindings/arm/amlogic/amlogic,meson-gx-ao-secure.txt b/Documentation/devicetree/bindings/arm/amlogic/amlogic,meson-gx-ao-secure.txt
deleted file mode 100644
index c67d9f4..0000000
--- a/Documentation/devicetree/bindings/arm/amlogic/amlogic,meson-gx-ao-secure.txt
+++ /dev/null
@@ -1,28 +0,0 @@
-Amlogic Meson Firmware registers Interface
-------------------------------------------
-
-The Meson SoCs have a register bank with status and data shared with the
-secure firmware.
-
-Required properties:
- - compatible: For Meson GX SoCs, must be "amlogic,meson-gx-ao-secure", "syscon"
-
-Properties should indentify components of this register interface :
-
-Meson GX SoC Information
-------------------------
-A firmware register encodes the SoC type, package and revision information on
-the Meson GX SoCs.
-If present, the following property should be added :
-
-Optional properties:
- - amlogic,has-chip-id: If present, the interface gives the current SoC version.
-
-Example
--------
-
-ao-secure@140 {
- compatible = "amlogic,meson-gx-ao-secure", "syscon";
- reg = <0x0 0x140 0x0 0x140>;
- amlogic,has-chip-id;
-};
diff --git a/Documentation/devicetree/bindings/arm/amlogic/amlogic,meson-gx-ao-secure.yaml b/Documentation/devicetree/bindings/arm/amlogic/amlogic,meson-gx-ao-secure.yaml
new file mode 100644
index 0000000..853d7d2
--- /dev/null
+++ b/Documentation/devicetree/bindings/arm/amlogic/amlogic,meson-gx-ao-secure.yaml
@@ -0,0 +1,52 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+# Copyright 2019 BayLibre, SAS
+%YAML 1.2
+---
+$id: "http://devicetree.org/schemas/arm/amlogic/amlogic,meson-gx-ao-secure.yaml#"
+$schema: "http://devicetree.org/meta-schemas/core.yaml#"
+
+title: Amlogic Meson Firmware registers Interface
+
+maintainers:
+ - Neil Armstrong <narmstrong@baylibre.com>
+
+description: |
+ The Meson SoCs have a register bank with status and data shared with the
+ secure firmware.
+
+# We need a select here so we don't match all nodes with 'syscon'
+select:
+ properties:
+ compatible:
+ contains:
+ const: amlogic,meson-gx-ao-secure
+ required:
+ - compatible
+
+properties:
+ compatible:
+ items:
+ - const: amlogic,meson-gx-ao-secure
+ - const: syscon
+
+ reg:
+ maxItems: 1
+
+ amlogic,has-chip-id:
+ description: |
+ A firmware register encodes the SoC type, package and revision
+ information on the Meson GX SoCs. If present, the interface gives
+ the current SoC version.
+ type: boolean
+
+required:
+ - compatible
+ - reg
+
+examples:
+ - |
+ ao-secure@140 {
+ compatible = "amlogic,meson-gx-ao-secure", "syscon";
+ reg = <0x140 0x140>;
+ amlogic,has-chip-id;
+ };
diff --git a/Documentation/devicetree/bindings/arm/arm,scmi.txt b/Documentation/devicetree/bindings/arm/arm,scmi.txt
index 317a2fc..083dbf9 100644
--- a/Documentation/devicetree/bindings/arm/arm,scmi.txt
+++ b/Documentation/devicetree/bindings/arm/arm,scmi.txt
@@ -73,6 +73,16 @@
as used by the firmware. Refer to platform details
for your implementation for the IDs to use.
+Reset signal bindings for the reset domains based on SCMI Message Protocol
+------------------------------------------------------------
+
+This binding for the SCMI reset domain providers uses the generic reset
+signal binding[5].
+
+Required properties:
+ - #reset-cells : Should be 1. Contains the reset domain ID value used
+ by SCMI commands.
+
SRAM and Shared Memory for SCMI
-------------------------------
@@ -93,6 +103,7 @@
[2] Documentation/devicetree/bindings/power/power_domain.txt
[3] Documentation/devicetree/bindings/thermal/thermal.txt
[4] Documentation/devicetree/bindings/sram/sram.txt
+[5] Documentation/devicetree/bindings/reset/reset.txt
Example:
@@ -152,6 +163,11 @@
reg = <0x15>;
#thermal-sensor-cells = <1>;
};
+
+ scmi_reset: protocol@16 {
+ reg = <0x16>;
+ #reset-cells = <1>;
+ };
};
};
@@ -166,6 +182,7 @@
reg = <0 0x7ff60000 0 0x1000>;
clocks = <&scmi_clk 4>;
power-domains = <&scmi_devpd 1>;
+ resets = <&scmi_reset 10>;
};
thermal-zones {
diff --git a/Documentation/devicetree/bindings/arm/arm-boards b/Documentation/devicetree/bindings/arm/arm-boards
index 6758ece..b2a9f9f 100644
--- a/Documentation/devicetree/bindings/arm/arm-boards
+++ b/Documentation/devicetree/bindings/arm/arm-boards
@@ -199,7 +199,7 @@
A detailed description of the bindings used for "psci" nodes is present
in the psci.yaml file.
- a "cpus" node describing the available cores and their associated
- "enable-method"s. For more details see cpus.txt file.
+ "enable-method"s. For more details see cpus.yaml file.
Example:
diff --git a/Documentation/devicetree/bindings/arm/cpus.yaml b/Documentation/devicetree/bindings/arm/cpus.yaml
index aa40b07..cb30895 100644
--- a/Documentation/devicetree/bindings/arm/cpus.yaml
+++ b/Documentation/devicetree/bindings/arm/cpus.yaml
@@ -124,6 +124,7 @@
- arm,cortex-a15
- arm,cortex-a17
- arm,cortex-a53
+ - arm,cortex-a55
- arm,cortex-a57
- arm,cortex-a72
- arm,cortex-a73
@@ -155,6 +156,7 @@
- qcom,krait
- qcom,kryo
- qcom,kryo385
+ - qcom,kryo485
- qcom,scorpion
enable-method:
@@ -175,6 +177,7 @@
- amlogic,meson8-smp
- amlogic,meson8b-smp
- arm,realview-smp
+ - aspeed,ast2600-smp
- brcm,bcm11351-cpu-method
- brcm,bcm23550
- brcm,bcm2836-smp
diff --git a/Documentation/devicetree/bindings/arm/freescale/fsl,scu.txt b/Documentation/devicetree/bindings/arm/freescale/fsl,scu.txt
index a575e42..c149fad 100644
--- a/Documentation/devicetree/bindings/arm/freescale/fsl,scu.txt
+++ b/Documentation/devicetree/bindings/arm/freescale/fsl,scu.txt
@@ -136,7 +136,9 @@
OCOTP bindings based on SCU Message Protocol
------------------------------------------------------------
Required properties:
-- compatible: Should be "fsl,imx8qxp-scu-ocotp"
+- compatible: Should be one of:
+ "fsl,imx8qm-scu-ocotp",
+ "fsl,imx8qxp-scu-ocotp".
- #address-cells: Must be 1. Contains byte index
- #size-cells: Must be 1. Contains byte length
diff --git a/Documentation/devicetree/bindings/arm/fsl.yaml b/Documentation/devicetree/bindings/arm/fsl.yaml
index 7294ac3..1b4b4e6 100644
--- a/Documentation/devicetree/bindings/arm/fsl.yaml
+++ b/Documentation/devicetree/bindings/arm/fsl.yaml
@@ -161,6 +161,20 @@
items:
- enum:
- fsl,imx6ul-14x14-evk # i.MX6 UltraLite 14x14 EVK Board
+ - kontron,imx6ul-n6310-som # Kontron N6310 SOM
+ - const: fsl,imx6ul
+
+ - description: Kontron N6310 S Board
+ items:
+ - const: kontron,imx6ul-n6310-s
+ - const: kontron,imx6ul-n6310-som
+ - const: fsl,imx6ul
+
+ - description: Kontron N6310 S 43 Board
+ items:
+ - const: kontron,imx6ul-n6310-s-43
+ - const: kontron,imx6ul-n6310-s
+ - const: kontron,imx6ul-n6310-som
- const: fsl,imx6ul
- description: i.MX6ULL based Boards
@@ -188,6 +202,7 @@
- fsl,imx7d-sdb # i.MX7 SabreSD Board
- novtech,imx7d-meerkat96 # i.MX7 Meerkat96 Board
- tq,imx7d-mba7 # i.MX7D TQ MBa7 with TQMa7D SoM
+ - zii,imx7d-rmu2 # ZII RMU2 Board
- zii,imx7d-rpu2 # ZII RPU2 Board
- const: fsl,imx7d
@@ -214,16 +229,26 @@
- fsl,imx8mm-evk # i.MX8MM EVK Board
- const: fsl,imx8mm
+ - description: i.MX8MN based Boards
+ items:
+ - enum:
+ - fsl,imx8mn-ddr4-evk # i.MX8MN DDR4 EVK Board
+ - const: fsl,imx8mn
+
- description: i.MX8MQ based Boards
items:
- enum:
+ - boundary,imx8mq-nitrogen8m # i.MX8MQ NITROGEN Board
- fsl,imx8mq-evk # i.MX8MQ EVK Board
- purism,librem5-devkit # Purism Librem5 devkit
+ - solidrun,hummingboard-pulse # SolidRun Hummingboard Pulse
+ - technexion,pico-pi-imx8m # TechNexion PICO-PI-8M evk
- const: fsl,imx8mq
- description: i.MX8QXP based Boards
items:
- enum:
+ - einfochips,imx8qxp-ai_ml # i.MX8QXP AI_ML Board
- fsl,imx8qxp-mek # i.MX8QXP MEK Board
- const: fsl,imx8qxp
@@ -283,6 +308,7 @@
- description: LS1046A based Boards
items:
- enum:
+ - fsl,ls1046a-frwy
- fsl,ls1046a-qds
- fsl,ls1046a-rdb
- const: fsl,ls1046a
diff --git a/Documentation/devicetree/bindings/arm/idle-states.txt b/Documentation/devicetree/bindings/arm/idle-states.txt
index 2d325be..771f5d2 100644
--- a/Documentation/devicetree/bindings/arm/idle-states.txt
+++ b/Documentation/devicetree/bindings/arm/idle-states.txt
@@ -28,7 +28,7 @@
states listed above; "off" state is not an idle state since it does not have
wake-up capabilities, hence it is not considered in this document).
-Idle state parameters (eg entry latency) are platform specific and need to be
+Idle state parameters (e.g. entry latency) are platform specific and need to be
characterized with bindings that provide the required information to OS PM
code so that it can build the required tables and use them at runtime.
@@ -90,24 +90,24 @@
An idle CPU requires the expected min-residency time to select the most
appropriate idle state based on the expected expiry time of the next IRQ
-(ie wake-up) that causes the CPU to return to the EXEC phase.
+(i.e. wake-up) that causes the CPU to return to the EXEC phase.
An operating system scheduler may need to compute the shortest wake-up delay
for CPUs in the system by detecting how long will it take to get a CPU out
-of an idle state, eg:
+of an idle state, e.g.:
wakeup-delay = exit-latency + max(entry-latency - (now - entry-timestamp), 0)
In other words, the scheduler can make its scheduling decision by selecting
-(eg waking-up) the CPU with the shortest wake-up latency.
-The wake-up latency must take into account the entry latency if that period
+(e.g. waking-up) the CPU with the shortest wake-up delay.
+The wake-up delay must take into account the entry latency if that period
has not expired. The abortable nature of the PREP period can be ignored
if it cannot be relied upon (e.g. the PREP deadline may occur much sooner than
-the worst case since it depends on the CPU operating conditions, ie caches
+the worst case since it depends on the CPU operating conditions, i.e. caches
state).
An OS has to reliably probe the wakeup-latency since some devices can enforce
-latency constraints guarantees to work properly, so the OS has to detect the
+latency constraint guarantees to work properly, so the OS has to detect the
worst case wake-up latency it can incur if a CPU is allowed to enter an
idle state, and possibly to prevent that to guarantee reliable device
functioning.
@@ -183,15 +183,15 @@
Graph 2: idle states min-residency example
In graph 2 above, that takes into account idle states entry/exit energy
-costs, it is clear that if the idle state residency time (ie time till next
+costs, it is clear that if the idle state residency time (i.e. time till next
wake-up IRQ) is less than IDLE2-min-residency, IDLE1 is the better idle state
choice energywise.
This is mainly down to the fact that IDLE1 entry/exit energy costs are lower
than IDLE2.
-However, the lower power consumption (ie shallower energy curve slope) of idle
-state IDLE2 implies that after a suitable time, IDLE2 becomes more energy
+However, the lower power consumption (i.e. shallower energy curve slope) of
+idle state IDLE2 implies that after a suitable time, IDLE2 becomes more energy
efficient.
The time at which IDLE2 becomes more energy efficient than IDLE1 (and other
@@ -214,8 +214,8 @@
Usage: Optional - On ARM systems, it is a container of processor idle
states nodes. If the system does not provide CPU
- power management capabilities or the processor just
- supports idle_standby an idle-states node is not
+ power management capabilities, or the processor just
+ supports idle_standby, an idle-states node is not
required.
Description: idle-states node is a container node, where its
@@ -287,14 +287,14 @@
Value type: <prop-encoded-array>
Definition: u32 value representing worst case latency in
microseconds required to enter the idle state.
- The exit-latency-us duration may be guaranteed
- only after entry-latency-us has passed.
- exit-latency-us
Usage: Required
Value type: <prop-encoded-array>
Definition: u32 value representing worst case latency
in microseconds required to exit the idle state.
+ The exit-latency-us duration may be guaranteed
+ only after entry-latency-us has passed.
- min-residency-us
Usage: Required
@@ -342,8 +342,8 @@
state.
In addition to the properties listed above, a state node may require
- additional properties specifics to the entry-method defined in the
- idle-states node, please refer to the entry-method bindings
+ additional properties specific to the entry-method defined in the
+ idle-states node. Please refer to the entry-method bindings
documentation for properties definitions.
===========================================
diff --git a/Documentation/devicetree/bindings/arm/l2c2x0.yaml b/Documentation/devicetree/bindings/arm/l2c2x0.yaml
index bfc5c18..913a8cd 100644
--- a/Documentation/devicetree/bindings/arm/l2c2x0.yaml
+++ b/Documentation/devicetree/bindings/arm/l2c2x0.yaml
@@ -176,6 +176,10 @@
description: disable parity checking on the L2 cache (L220 or PL310).
type: boolean
+ marvell,ecc-enable:
+ description: enable ECC protection on the L2 cache
+ type: boolean
+
arm,outer-sync-disable:
description: disable the outer sync operation on the L2 cache.
Some core tiles, especially ARM PB11MPCore have a faulty L220 cache that
diff --git a/Documentation/devicetree/bindings/arm/marvell/ap806-system-controller.txt b/Documentation/devicetree/bindings/arm/marvell/ap806-system-controller.txt
index 7b8b8eb..26410fb 100644
--- a/Documentation/devicetree/bindings/arm/marvell/ap806-system-controller.txt
+++ b/Documentation/devicetree/bindings/arm/marvell/ap806-system-controller.txt
@@ -18,17 +18,19 @@
-------
-The Device Tree node representing the AP806 system controller provides
-a number of clocks:
+The Device Tree node representing the AP806/AP807 system controller
+provides a number of clocks:
- - 0: clock of CPU cluster 0
- - 1: clock of CPU cluster 1
+ - 0: reference clock of CPU cluster 0
+ - 1: reference clock of CPU cluster 1
- 2: fixed PLL at 1200 Mhz
- 3: MSS clock, derived from the fixed PLL
Required properties:
- - compatible: must be: "marvell,ap806-clock"
+ - compatible: must be one of:
+ * "marvell,ap806-clock"
+ * "marvell,ap807-clock"
- #clock-cells: must be set to 1
Pinctrl:
@@ -143,3 +145,33 @@
#thermal-sensor-cells = <1>;
};
};
+
+Cluster clocks:
+---------------
+
+Device Tree Clock bindings for cluster clock of Marvell
+AP806/AP807. Each cluster contain up to 2 CPUs running at the same
+frequency.
+
+Required properties:
+ - compatible: must be one of:
+ * "marvell,ap806-cpu-clock"
+ * "marvell,ap807-cpu-clock"
+- #clock-cells : should be set to 1.
+
+- clocks : shall be the input parent clock(s) phandle for the clock
+ (one per cluster)
+
+- reg: register range associated with the cluster clocks
+
+ap_syscon1: system-controller@6f8000 {
+ compatible = "marvell,armada-ap806-syscon1", "syscon", "simple-mfd";
+ reg = <0x6f8000 0x1000>;
+
+ cpu_clk: clock-cpu@278 {
+ compatible = "marvell,ap806-cpu-clock";
+ clocks = <&ap_clk 0>, <&ap_clk 1>;
+ #clock-cells = <1>;
+ reg = <0x278 0xa30>;
+ };
+};
diff --git a/Documentation/devicetree/bindings/arm/marvell/armada-37xx.txt b/Documentation/devicetree/bindings/arm/marvell/armada-37xx.txt
index eddde4f..f6d6642 100644
--- a/Documentation/devicetree/bindings/arm/marvell/armada-37xx.txt
+++ b/Documentation/devicetree/bindings/arm/marvell/armada-37xx.txt
@@ -48,3 +48,11 @@
compatible = "marvell,armada-3700-avs", "syscon";
reg = <0x11500 0x40>;
}
+
+
+CZ.NIC's Turris Mox SOHO router Device Tree Bindings
+----------------------------------------------------
+
+Required root node property:
+
+ - compatible: must contain "cznic,turris-mox"
diff --git a/Documentation/devicetree/bindings/arm/marvell/cp110-system-controller.txt b/Documentation/devicetree/bindings/arm/marvell/cp110-system-controller.txt
index 4db4119..f982a8e 100644
--- a/Documentation/devicetree/bindings/arm/marvell/cp110-system-controller.txt
+++ b/Documentation/devicetree/bindings/arm/marvell/cp110-system-controller.txt
@@ -78,8 +78,8 @@
Required properties:
-- compatible: "marvell,armada-7k-pinctrl",
- "marvell,armada-8k-cpm-pinctrl" or "marvell,armada-8k-cps-pinctrl"
+- compatible: "marvell,armada-7k-pinctrl", "marvell,armada-8k-cpm-pinctrl",
+ "marvell,armada-8k-cps-pinctrl" or "marvell,cp115-standalone-pinctrl"
depending on the specific variant of the SoC being used.
Available mpp pins/groups and functions:
diff --git a/Documentation/devicetree/bindings/arm/mediatek.yaml b/Documentation/devicetree/bindings/arm/mediatek.yaml
index a4ad2eb..4043c50 100644
--- a/Documentation/devicetree/bindings/arm/mediatek.yaml
+++ b/Documentation/devicetree/bindings/arm/mediatek.yaml
@@ -48,6 +48,10 @@
- const: mediatek,mt6765
- items:
- enum:
+ - mediatek,mt6779-evb
+ - const: mediatek,mt6779
+ - items:
+ - enum:
- mediatek,mt6795-evb
- const: mediatek,mt6795
- items:
diff --git a/Documentation/devicetree/bindings/arm/mediatek/mediatek,apmixedsys.txt b/Documentation/devicetree/bindings/arm/mediatek/mediatek,apmixedsys.txt
index 161e63a..ff000cc 100644
--- a/Documentation/devicetree/bindings/arm/mediatek/mediatek,apmixedsys.txt
+++ b/Documentation/devicetree/bindings/arm/mediatek/mediatek,apmixedsys.txt
@@ -8,6 +8,7 @@
- compatible: Should be one of:
- "mediatek,mt2701-apmixedsys"
- "mediatek,mt2712-apmixedsys", "syscon"
+ - "mediatek,mt6779-apmixedsys", "syscon"
- "mediatek,mt6797-apmixedsys"
- "mediatek,mt7622-apmixedsys"
- "mediatek,mt7623-apmixedsys", "mediatek,mt2701-apmixedsys"
diff --git a/Documentation/devicetree/bindings/arm/mediatek/mediatek,audsys.txt b/Documentation/devicetree/bindings/arm/mediatek/mediatek,audsys.txt
index 07c9d81..e4ca7b7 100644
--- a/Documentation/devicetree/bindings/arm/mediatek/mediatek,audsys.txt
+++ b/Documentation/devicetree/bindings/arm/mediatek/mediatek,audsys.txt
@@ -7,6 +7,7 @@
- compatible: Should be one of:
- "mediatek,mt2701-audsys", "syscon"
+ - "mediatek,mt6779-audio", "syscon"
- "mediatek,mt7622-audsys", "syscon"
- "mediatek,mt7623-audsys", "mediatek,mt2701-audsys", "syscon"
- "mediatek,mt8183-audiosys", "syscon"
diff --git a/Documentation/devicetree/bindings/arm/mediatek/mediatek,camsys.txt b/Documentation/devicetree/bindings/arm/mediatek/mediatek,camsys.txt
index d8930f6..1f4aaa1 100644
--- a/Documentation/devicetree/bindings/arm/mediatek/mediatek,camsys.txt
+++ b/Documentation/devicetree/bindings/arm/mediatek/mediatek,camsys.txt
@@ -6,6 +6,7 @@
Required Properties:
- compatible: Should be one of:
+ - "mediatek,mt6779-camsys", "syscon"
- "mediatek,mt8183-camsys", "syscon"
- #clock-cells: Must be 1
diff --git a/Documentation/devicetree/bindings/arm/mediatek/mediatek,imgsys.txt b/Documentation/devicetree/bindings/arm/mediatek/mediatek,imgsys.txt
index e3bc4a1..2b693e3 100644
--- a/Documentation/devicetree/bindings/arm/mediatek/mediatek,imgsys.txt
+++ b/Documentation/devicetree/bindings/arm/mediatek/mediatek,imgsys.txt
@@ -8,6 +8,7 @@
- compatible: Should be one of:
- "mediatek,mt2701-imgsys", "syscon"
- "mediatek,mt2712-imgsys", "syscon"
+ - "mediatek,mt6779-imgsys", "syscon"
- "mediatek,mt6797-imgsys", "syscon"
- "mediatek,mt7623-imgsys", "mediatek,mt2701-imgsys", "syscon"
- "mediatek,mt8173-imgsys", "syscon"
diff --git a/Documentation/devicetree/bindings/arm/mediatek/mediatek,infracfg.txt b/Documentation/devicetree/bindings/arm/mediatek/mediatek,infracfg.txt
index a909139..db2f4fd 100644
--- a/Documentation/devicetree/bindings/arm/mediatek/mediatek,infracfg.txt
+++ b/Documentation/devicetree/bindings/arm/mediatek/mediatek,infracfg.txt
@@ -9,6 +9,7 @@
- compatible: Should be one of:
- "mediatek,mt2701-infracfg", "syscon"
- "mediatek,mt2712-infracfg", "syscon"
+ - "mediatek,mt6779-infracfg_ao", "syscon"
- "mediatek,mt6797-infracfg", "syscon"
- "mediatek,mt7622-infracfg", "syscon"
- "mediatek,mt7623-infracfg", "mediatek,mt2701-infracfg", "syscon"
diff --git a/Documentation/devicetree/bindings/arm/mediatek/mediatek,ipesys.txt b/Documentation/devicetree/bindings/arm/mediatek/mediatek,ipesys.txt
new file mode 100644
index 0000000..2ce889b
--- /dev/null
+++ b/Documentation/devicetree/bindings/arm/mediatek/mediatek,ipesys.txt
@@ -0,0 +1,22 @@
+Mediatek ipesys controller
+============================
+
+The Mediatek ipesys controller provides various clocks to the system.
+
+Required Properties:
+
+- compatible: Should be one of:
+ - "mediatek,mt6779-ipesys", "syscon"
+- #clock-cells: Must be 1
+
+The ipesys controller uses the common clk binding from
+Documentation/devicetree/bindings/clock/clock-bindings.txt
+The available clocks are defined in dt-bindings/clock/mt*-clk.h.
+
+Example:
+
+ipesys: clock-controller@1b000000 {
+ compatible = "mediatek,mt6779-ipesys", "syscon";
+ reg = <0 0x1b000000 0 0x1000>;
+ #clock-cells = <1>;
+};
diff --git a/Documentation/devicetree/bindings/arm/mediatek/mediatek,mfgcfg.txt b/Documentation/devicetree/bindings/arm/mediatek/mediatek,mfgcfg.txt
index 72787e7..ad5f9d2 100644
--- a/Documentation/devicetree/bindings/arm/mediatek/mediatek,mfgcfg.txt
+++ b/Documentation/devicetree/bindings/arm/mediatek/mediatek,mfgcfg.txt
@@ -7,6 +7,7 @@
- compatible: Should be one of:
- "mediatek,mt2712-mfgcfg", "syscon"
+ - "mediatek,mt6779-mfgcfg", "syscon"
- "mediatek,mt8183-mfgcfg", "syscon"
- #clock-cells: Must be 1
diff --git a/Documentation/devicetree/bindings/arm/mediatek/mediatek,mmsys.txt b/Documentation/devicetree/bindings/arm/mediatek/mediatek,mmsys.txt
index 545eab7..301eefb 100644
--- a/Documentation/devicetree/bindings/arm/mediatek/mediatek,mmsys.txt
+++ b/Documentation/devicetree/bindings/arm/mediatek/mediatek,mmsys.txt
@@ -8,6 +8,7 @@
- compatible: Should be one of:
- "mediatek,mt2701-mmsys", "syscon"
- "mediatek,mt2712-mmsys", "syscon"
+ - "mediatek,mt6779-mmsys", "syscon"
- "mediatek,mt6797-mmsys", "syscon"
- "mediatek,mt7623-mmsys", "mediatek,mt2701-mmsys", "syscon"
- "mediatek,mt8173-mmsys", "syscon"
diff --git a/Documentation/devicetree/bindings/arm/mediatek/mediatek,pericfg.txt b/Documentation/devicetree/bindings/arm/mediatek/mediatek,pericfg.txt
index 4c7e478..ecf027a 100644
--- a/Documentation/devicetree/bindings/arm/mediatek/mediatek,pericfg.txt
+++ b/Documentation/devicetree/bindings/arm/mediatek/mediatek,pericfg.txt
@@ -14,6 +14,7 @@
- "mediatek,mt7629-pericfg", "syscon"
- "mediatek,mt8135-pericfg", "syscon"
- "mediatek,mt8173-pericfg", "syscon"
+ - "mediatek,mt8183-pericfg", "syscon"
- #clock-cells: Must be 1
- #reset-cells: Must be 1
diff --git a/Documentation/devicetree/bindings/arm/mediatek/mediatek,sgmiisys.txt b/Documentation/devicetree/bindings/arm/mediatek/mediatek,sgmiisys.txt
index f5518f2..30cb645 100644
--- a/Documentation/devicetree/bindings/arm/mediatek/mediatek,sgmiisys.txt
+++ b/Documentation/devicetree/bindings/arm/mediatek/mediatek,sgmiisys.txt
@@ -9,8 +9,6 @@
- "mediatek,mt7622-sgmiisys", "syscon"
- "mediatek,mt7629-sgmiisys", "syscon"
- #clock-cells: Must be 1
-- mediatek,physpeed: Should be one of "auto", "1000" or "2500" to match up
- the capability of the target PHY.
The SGMIISYS controller uses the common clk binding from
Documentation/devicetree/bindings/clock/clock-bindings.txt
diff --git a/Documentation/devicetree/bindings/arm/mediatek/mediatek,topckgen.txt b/Documentation/devicetree/bindings/arm/mediatek/mediatek,topckgen.txt
index a023b83..0293d69 100644
--- a/Documentation/devicetree/bindings/arm/mediatek/mediatek,topckgen.txt
+++ b/Documentation/devicetree/bindings/arm/mediatek/mediatek,topckgen.txt
@@ -8,6 +8,7 @@
- compatible: Should be one of:
- "mediatek,mt2701-topckgen"
- "mediatek,mt2712-topckgen", "syscon"
+ - "mediatek,mt6779-topckgen", "syscon"
- "mediatek,mt6797-topckgen"
- "mediatek,mt7622-topckgen"
- "mediatek,mt7623-topckgen", "mediatek,mt2701-topckgen"
diff --git a/Documentation/devicetree/bindings/arm/mediatek/mediatek,vdecsys.txt b/Documentation/devicetree/bindings/arm/mediatek/mediatek,vdecsys.txt
index 57176bb..7894558 100644
--- a/Documentation/devicetree/bindings/arm/mediatek/mediatek,vdecsys.txt
+++ b/Documentation/devicetree/bindings/arm/mediatek/mediatek,vdecsys.txt
@@ -8,6 +8,7 @@
- compatible: Should be one of:
- "mediatek,mt2701-vdecsys", "syscon"
- "mediatek,mt2712-vdecsys", "syscon"
+ - "mediatek,mt6779-vdecsys", "syscon"
- "mediatek,mt6797-vdecsys", "syscon"
- "mediatek,mt7623-vdecsys", "mediatek,mt2701-vdecsys", "syscon"
- "mediatek,mt8173-vdecsys", "syscon"
diff --git a/Documentation/devicetree/bindings/arm/mediatek/mediatek,vencsys.txt b/Documentation/devicetree/bindings/arm/mediatek/mediatek,vencsys.txt
index c9faa62..6a6a14e 100644
--- a/Documentation/devicetree/bindings/arm/mediatek/mediatek,vencsys.txt
+++ b/Documentation/devicetree/bindings/arm/mediatek/mediatek,vencsys.txt
@@ -7,6 +7,7 @@
- compatible: Should be one of:
- "mediatek,mt2712-vencsys", "syscon"
+ - "mediatek,mt6779-vencsys", "syscon"
- "mediatek,mt6797-vencsys", "syscon"
- "mediatek,mt8173-vencsys", "syscon"
- "mediatek,mt8183-vencsys", "syscon"
diff --git a/Documentation/devicetree/bindings/arm/qcom.yaml b/Documentation/devicetree/bindings/arm/qcom.yaml
index 54ef6b6..e39d8f0 100644
--- a/Documentation/devicetree/bindings/arm/qcom.yaml
+++ b/Documentation/devicetree/bindings/arm/qcom.yaml
@@ -45,6 +45,7 @@
mtp
sbc
hk01
+ qrd
The 'soc_version' and 'board_version' elements take the form of v<Major>.<Minor>
where the minor number may be omitted when it's zero, i.e. v1.0 is the same
@@ -116,6 +117,13 @@
- const: qcom,msm8916
- items:
+ - enum:
+ - longcheer,l8150
+ - samsung,a3u-eur
+ - samsung,a5u-eur
+ - const: qcom,msm8916
+
+ - items:
- const: qcom,msm8996-mtp
- items:
diff --git a/Documentation/devicetree/bindings/arm/realtek.txt b/Documentation/devicetree/bindings/arm/realtek.txt
deleted file mode 100644
index 95839e1..0000000
--- a/Documentation/devicetree/bindings/arm/realtek.txt
+++ /dev/null
@@ -1,22 +0,0 @@
-Realtek platforms device tree bindings
---------------------------------------
-
-
-RTD1295 SoC
-===========
-
-Required root node properties:
-
- - compatible : must contain "realtek,rtd1295"
-
-
-Root node property compatible must contain, depending on board:
-
- - MeLE V9: "mele,v9"
- - ProBox2 AVA: "probox2,ava"
- - Zidoo X9S: "zidoo,x9s"
-
-
-Example:
-
- compatible = "zidoo,x9s", "realtek,rtd1295";
diff --git a/Documentation/devicetree/bindings/arm/realtek.yaml b/Documentation/devicetree/bindings/arm/realtek.yaml
new file mode 100644
index 0000000..3528b61
--- /dev/null
+++ b/Documentation/devicetree/bindings/arm/realtek.yaml
@@ -0,0 +1,23 @@
+# SPDX-License-Identifier: GPL-2.0-or-later OR BSD-2-Clause
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/arm/realtek.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Realtek platforms device tree bindings
+
+maintainers:
+ - Andreas Färber <afaerber@suse.de>
+
+properties:
+ $nodename:
+ const: '/'
+ compatible:
+ # RTD1295 SoC based boards
+ items:
+ - enum:
+ - mele,v9
+ - probox2,ava
+ - zidoo,x9s
+ - const: realtek,rtd1295
+...
diff --git a/Documentation/devicetree/bindings/arm/rockchip.yaml b/Documentation/devicetree/bindings/arm/rockchip.yaml
index 3486504..c82c5e5 100644
--- a/Documentation/devicetree/bindings/arm/rockchip.yaml
+++ b/Documentation/devicetree/bindings/arm/rockchip.yaml
@@ -128,6 +128,21 @@
- const: google,veyron
- const: rockchip,rk3288
+ - description: Google Fievel (AOPEN Chromebox Mini)
+ items:
+ - const: google,veyron-fievel-rev8
+ - const: google,veyron-fievel-rev7
+ - const: google,veyron-fievel-rev6
+ - const: google,veyron-fievel-rev5
+ - const: google,veyron-fievel-rev4
+ - const: google,veyron-fievel-rev3
+ - const: google,veyron-fievel-rev2
+ - const: google,veyron-fievel-rev1
+ - const: google,veyron-fievel-rev0
+ - const: google,veyron-fievel
+ - const: google,veyron
+ - const: rockchip,rk3288
+
- description: Google Gru (dev-board)
items:
- const: google,gru-rev15
@@ -311,6 +326,21 @@
- const: google,veyron
- const: rockchip,rk3288
+ - description: Google Tiger (AOpen Chromebase Mini)
+ items:
+ - const: google,veyron-tiger-rev8
+ - const: google,veyron-tiger-rev7
+ - const: google,veyron-tiger-rev6
+ - const: google,veyron-tiger-rev5
+ - const: google,veyron-tiger-rev4
+ - const: google,veyron-tiger-rev3
+ - const: google,veyron-tiger-rev2
+ - const: google,veyron-tiger-rev1
+ - const: google,veyron-tiger-rev0
+ - const: google,veyron-tiger
+ - const: google,veyron
+ - const: rockchip,rk3288
+
- description: Haoyu MarsBoard RK3066
items:
- const: haoyu,marsboard-rk3066
@@ -329,6 +359,16 @@
- khadas,edge-v
- const: rockchip,rk3399
+ - description: Mecer Xtreme Mini S6
+ items:
+ - const: mecer,xms6
+ - const: rockchip,rk3229
+
+ - description: Leez RK3399 P710
+ items:
+ - const: leez,p710
+ - const: rockchip,rk3399
+
- description: mqmaker MiQi
items:
- const: mqmaker,miqi
@@ -424,11 +464,6 @@
- rockchip,rk3288-evb-rk808
- const: rockchip,rk3288
- - description: Rockchip RK3288 Fennec
- items:
- - const: rockchip,rk3288-fennec
- - const: rockchip,rk3288
-
- description: Rockchip RK3328 Evaluation board
items:
- const: rockchip,rk3328-evb
diff --git a/Documentation/devicetree/bindings/arm/sunxi.yaml b/Documentation/devicetree/bindings/arm/sunxi.yaml
index 000a00d..972b1e9 100644
--- a/Documentation/devicetree/bindings/arm/sunxi.yaml
+++ b/Documentation/devicetree/bindings/arm/sunxi.yaml
@@ -353,6 +353,12 @@
- const: licheepi,licheepi-zero
- const: allwinner,sun8i-v3s
+ - description: Lichee Zero Plus (with S3, without eMMC/SPI Flash)
+ items:
+ - const: sipeed,lichee-zero-plus
+ - const: sochip,s3
+ - const: allwinner,sun8i-v3
+
- description: Linksprite PCDuino
items:
- const: linksprite,a10-pcduino
@@ -568,6 +574,11 @@
- const: olimex,a64-olinuxino
- const: allwinner,sun50i-a64
+ - description: Olimex A64-OlinuXino (with eMMC)
+ items:
+ - const: olimex,a64-olinuxino-emmc
+ - const: allwinner,sun50i-a64
+
- description: Olimex A64 Teres-I
items:
- const: olimex,a64-teres-i
@@ -671,6 +682,11 @@
- const: sinlinx,sina33
- const: allwinner,sun8i-a33
+ - description: Tanix TX6
+ items:
+ - const: oranth,tanix-tx6
+ - const: allwinner,sun50i-h6
+
- description: TBS A711 Tablet
items:
- const: tbs-biometrics,a711
diff --git a/Documentation/devicetree/bindings/arm/topology.txt b/Documentation/devicetree/bindings/arm/topology.txt
deleted file mode 100644
index b0d80c0f..0000000
--- a/Documentation/devicetree/bindings/arm/topology.txt
+++ /dev/null
@@ -1,475 +0,0 @@
-===========================================
-ARM topology binding description
-===========================================
-
-===========================================
-1 - Introduction
-===========================================
-
-In an ARM system, the hierarchy of CPUs is defined through three entities that
-are used to describe the layout of physical CPUs in the system:
-
-- cluster
-- core
-- thread
-
-The cpu nodes (bindings defined in [1]) represent the devices that
-correspond to physical CPUs and are to be mapped to the hierarchy levels.
-
-The bottom hierarchy level sits at core or thread level depending on whether
-symmetric multi-threading (SMT) is supported or not.
-
-For instance in a system where CPUs support SMT, "cpu" nodes represent all
-threads existing in the system and map to the hierarchy level "thread" above.
-In systems where SMT is not supported "cpu" nodes represent all cores present
-in the system and map to the hierarchy level "core" above.
-
-ARM topology bindings allow one to associate cpu nodes with hierarchical groups
-corresponding to the system hierarchy; syntactically they are defined as device
-tree nodes.
-
-The remainder of this document provides the topology bindings for ARM, based
-on the Devicetree Specification, available from:
-
-https://www.devicetree.org/specifications/
-
-If not stated otherwise, whenever a reference to a cpu node phandle is made its
-value must point to a cpu node compliant with the cpu node bindings as
-documented in [1].
-A topology description containing phandles to cpu nodes that are not compliant
-with bindings standardized in [1] is therefore considered invalid.
-
-===========================================
-2 - cpu-map node
-===========================================
-
-The ARM CPU topology is defined within the cpu-map node, which is a direct
-child of the cpus node and provides a container where the actual topology
-nodes are listed.
-
-- cpu-map node
-
- Usage: Optional - On ARM SMP systems provide CPUs topology to the OS.
- ARM uniprocessor systems do not require a topology
- description and therefore should not define a
- cpu-map node.
-
- Description: The cpu-map node is just a container node where its
- subnodes describe the CPU topology.
-
- Node name must be "cpu-map".
-
- The cpu-map node's parent node must be the cpus node.
-
- The cpu-map node's child nodes can be:
-
- - one or more cluster nodes
-
- Any other configuration is considered invalid.
-
-The cpu-map node can only contain three types of child nodes:
-
-- cluster node
-- core node
-- thread node
-
-whose bindings are described in paragraph 3.
-
-The nodes describing the CPU topology (cluster/core/thread) can only
-be defined within the cpu-map node and every core/thread in the system
-must be defined within the topology. Any other configuration is
-invalid and therefore must be ignored.
-
-===========================================
-2.1 - cpu-map child nodes naming convention
-===========================================
-
-cpu-map child nodes must follow a naming convention where the node name
-must be "clusterN", "coreN", "threadN" depending on the node type (ie
-cluster/core/thread) (where N = {0, 1, ...} is the node number; nodes which
-are siblings within a single common parent node must be given a unique and
-sequential N value, starting from 0).
-cpu-map child nodes which do not share a common parent node can have the same
-name (ie same number N as other cpu-map child nodes at different device tree
-levels) since name uniqueness will be guaranteed by the device tree hierarchy.
-
-===========================================
-3 - cluster/core/thread node bindings
-===========================================
-
-Bindings for cluster/cpu/thread nodes are defined as follows:
-
-- cluster node
-
- Description: must be declared within a cpu-map node, one node
- per cluster. A system can contain several layers of
- clustering and cluster nodes can be contained in parent
- cluster nodes.
-
- The cluster node name must be "clusterN" as described in 2.1 above.
- A cluster node can not be a leaf node.
-
- A cluster node's child nodes must be:
-
- - one or more cluster nodes; or
- - one or more core nodes
-
- Any other configuration is considered invalid.
-
-- core node
-
- Description: must be declared in a cluster node, one node per core in
- the cluster. If the system does not support SMT, core
- nodes are leaf nodes, otherwise they become containers of
- thread nodes.
-
- The core node name must be "coreN" as described in 2.1 above.
-
- A core node must be a leaf node if SMT is not supported.
-
- Properties for core nodes that are leaf nodes:
-
- - cpu
- Usage: required
- Value type: <phandle>
- Definition: a phandle to the cpu node that corresponds to the
- core node.
-
- If a core node is not a leaf node (CPUs supporting SMT) a core node's
- child nodes can be:
-
- - one or more thread nodes
-
- Any other configuration is considered invalid.
-
-- thread node
-
- Description: must be declared in a core node, one node per thread
- in the core if the system supports SMT. Thread nodes are
- always leaf nodes in the device tree.
-
- The thread node name must be "threadN" as described in 2.1 above.
-
- A thread node must be a leaf node.
-
- A thread node must contain the following property:
-
- - cpu
- Usage: required
- Value type: <phandle>
- Definition: a phandle to the cpu node that corresponds to
- the thread node.
-
-===========================================
-4 - Example dts
-===========================================
-
-Example 1 (ARM 64-bit, 16-cpu system, two clusters of clusters):
-
-cpus {
- #size-cells = <0>;
- #address-cells = <2>;
-
- cpu-map {
- cluster0 {
- cluster0 {
- core0 {
- thread0 {
- cpu = <&CPU0>;
- };
- thread1 {
- cpu = <&CPU1>;
- };
- };
-
- core1 {
- thread0 {
- cpu = <&CPU2>;
- };
- thread1 {
- cpu = <&CPU3>;
- };
- };
- };
-
- cluster1 {
- core0 {
- thread0 {
- cpu = <&CPU4>;
- };
- thread1 {
- cpu = <&CPU5>;
- };
- };
-
- core1 {
- thread0 {
- cpu = <&CPU6>;
- };
- thread1 {
- cpu = <&CPU7>;
- };
- };
- };
- };
-
- cluster1 {
- cluster0 {
- core0 {
- thread0 {
- cpu = <&CPU8>;
- };
- thread1 {
- cpu = <&CPU9>;
- };
- };
- core1 {
- thread0 {
- cpu = <&CPU10>;
- };
- thread1 {
- cpu = <&CPU11>;
- };
- };
- };
-
- cluster1 {
- core0 {
- thread0 {
- cpu = <&CPU12>;
- };
- thread1 {
- cpu = <&CPU13>;
- };
- };
- core1 {
- thread0 {
- cpu = <&CPU14>;
- };
- thread1 {
- cpu = <&CPU15>;
- };
- };
- };
- };
- };
-
- CPU0: cpu@0 {
- device_type = "cpu";
- compatible = "arm,cortex-a57";
- reg = <0x0 0x0>;
- enable-method = "spin-table";
- cpu-release-addr = <0 0x20000000>;
- };
-
- CPU1: cpu@1 {
- device_type = "cpu";
- compatible = "arm,cortex-a57";
- reg = <0x0 0x1>;
- enable-method = "spin-table";
- cpu-release-addr = <0 0x20000000>;
- };
-
- CPU2: cpu@100 {
- device_type = "cpu";
- compatible = "arm,cortex-a57";
- reg = <0x0 0x100>;
- enable-method = "spin-table";
- cpu-release-addr = <0 0x20000000>;
- };
-
- CPU3: cpu@101 {
- device_type = "cpu";
- compatible = "arm,cortex-a57";
- reg = <0x0 0x101>;
- enable-method = "spin-table";
- cpu-release-addr = <0 0x20000000>;
- };
-
- CPU4: cpu@10000 {
- device_type = "cpu";
- compatible = "arm,cortex-a57";
- reg = <0x0 0x10000>;
- enable-method = "spin-table";
- cpu-release-addr = <0 0x20000000>;
- };
-
- CPU5: cpu@10001 {
- device_type = "cpu";
- compatible = "arm,cortex-a57";
- reg = <0x0 0x10001>;
- enable-method = "spin-table";
- cpu-release-addr = <0 0x20000000>;
- };
-
- CPU6: cpu@10100 {
- device_type = "cpu";
- compatible = "arm,cortex-a57";
- reg = <0x0 0x10100>;
- enable-method = "spin-table";
- cpu-release-addr = <0 0x20000000>;
- };
-
- CPU7: cpu@10101 {
- device_type = "cpu";
- compatible = "arm,cortex-a57";
- reg = <0x0 0x10101>;
- enable-method = "spin-table";
- cpu-release-addr = <0 0x20000000>;
- };
-
- CPU8: cpu@100000000 {
- device_type = "cpu";
- compatible = "arm,cortex-a57";
- reg = <0x1 0x0>;
- enable-method = "spin-table";
- cpu-release-addr = <0 0x20000000>;
- };
-
- CPU9: cpu@100000001 {
- device_type = "cpu";
- compatible = "arm,cortex-a57";
- reg = <0x1 0x1>;
- enable-method = "spin-table";
- cpu-release-addr = <0 0x20000000>;
- };
-
- CPU10: cpu@100000100 {
- device_type = "cpu";
- compatible = "arm,cortex-a57";
- reg = <0x1 0x100>;
- enable-method = "spin-table";
- cpu-release-addr = <0 0x20000000>;
- };
-
- CPU11: cpu@100000101 {
- device_type = "cpu";
- compatible = "arm,cortex-a57";
- reg = <0x1 0x101>;
- enable-method = "spin-table";
- cpu-release-addr = <0 0x20000000>;
- };
-
- CPU12: cpu@100010000 {
- device_type = "cpu";
- compatible = "arm,cortex-a57";
- reg = <0x1 0x10000>;
- enable-method = "spin-table";
- cpu-release-addr = <0 0x20000000>;
- };
-
- CPU13: cpu@100010001 {
- device_type = "cpu";
- compatible = "arm,cortex-a57";
- reg = <0x1 0x10001>;
- enable-method = "spin-table";
- cpu-release-addr = <0 0x20000000>;
- };
-
- CPU14: cpu@100010100 {
- device_type = "cpu";
- compatible = "arm,cortex-a57";
- reg = <0x1 0x10100>;
- enable-method = "spin-table";
- cpu-release-addr = <0 0x20000000>;
- };
-
- CPU15: cpu@100010101 {
- device_type = "cpu";
- compatible = "arm,cortex-a57";
- reg = <0x1 0x10101>;
- enable-method = "spin-table";
- cpu-release-addr = <0 0x20000000>;
- };
-};
-
-Example 2 (ARM 32-bit, dual-cluster, 8-cpu system, no SMT):
-
-cpus {
- #size-cells = <0>;
- #address-cells = <1>;
-
- cpu-map {
- cluster0 {
- core0 {
- cpu = <&CPU0>;
- };
- core1 {
- cpu = <&CPU1>;
- };
- core2 {
- cpu = <&CPU2>;
- };
- core3 {
- cpu = <&CPU3>;
- };
- };
-
- cluster1 {
- core0 {
- cpu = <&CPU4>;
- };
- core1 {
- cpu = <&CPU5>;
- };
- core2 {
- cpu = <&CPU6>;
- };
- core3 {
- cpu = <&CPU7>;
- };
- };
- };
-
- CPU0: cpu@0 {
- device_type = "cpu";
- compatible = "arm,cortex-a15";
- reg = <0x0>;
- };
-
- CPU1: cpu@1 {
- device_type = "cpu";
- compatible = "arm,cortex-a15";
- reg = <0x1>;
- };
-
- CPU2: cpu@2 {
- device_type = "cpu";
- compatible = "arm,cortex-a15";
- reg = <0x2>;
- };
-
- CPU3: cpu@3 {
- device_type = "cpu";
- compatible = "arm,cortex-a15";
- reg = <0x3>;
- };
-
- CPU4: cpu@100 {
- device_type = "cpu";
- compatible = "arm,cortex-a7";
- reg = <0x100>;
- };
-
- CPU5: cpu@101 {
- device_type = "cpu";
- compatible = "arm,cortex-a7";
- reg = <0x101>;
- };
-
- CPU6: cpu@102 {
- device_type = "cpu";
- compatible = "arm,cortex-a7";
- reg = <0x102>;
- };
-
- CPU7: cpu@103 {
- device_type = "cpu";
- compatible = "arm,cortex-a7";
- reg = <0x103>;
- };
-};
-
-===============================================================================
-[1] ARM Linux kernel documentation
- Documentation/devicetree/bindings/arm/cpus.yaml
diff --git a/Documentation/devicetree/bindings/ata/ahci-platform.txt b/Documentation/devicetree/bindings/ata/ahci-platform.txt
index e30fd10..55c6fab 100644
--- a/Documentation/devicetree/bindings/ata/ahci-platform.txt
+++ b/Documentation/devicetree/bindings/ata/ahci-platform.txt
@@ -45,7 +45,7 @@
- #address-cells : number of cells to encode an address
- #size-cells : number of cells representing the size of an address
-For allwinner,sun8i-r40-ahci, the reset propertie must be present.
+For allwinner,sun8i-r40-ahci, the reset property must be present.
Sub-nodes required properties:
- reg : the port number
diff --git a/Documentation/devicetree/bindings/bus/allwinner,sun50i-a64-de2.yaml b/Documentation/devicetree/bindings/bus/allwinner,sun50i-a64-de2.yaml
new file mode 100644
index 0000000..d2a8722
--- /dev/null
+++ b/Documentation/devicetree/bindings/bus/allwinner,sun50i-a64-de2.yaml
@@ -0,0 +1,85 @@
+# SPDX-License-Identifier: GPL-2.0
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/bus/allwinner,sun50i-a64-de2.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Allwinner A64 Display Engine Bus Device Tree Bindings
+
+maintainers:
+ - Chen-Yu Tsai <wens@csie.org>
+ - Maxime Ripard <maxime.ripard@bootlin.com>
+
+properties:
+ $nodename:
+ pattern: "^bus(@[0-9a-f]+)?$"
+
+ "#address-cells":
+ const: 1
+
+ "#size-cells":
+ const: 1
+
+ compatible:
+ oneOf:
+ - const: allwinner,sun50i-a64-de2
+ - items:
+ - const: allwinner,sun50i-h6-de3
+ - const: allwinner,sun50i-a64-de2
+
+ reg:
+ maxItems: 1
+
+ allwinner,sram:
+ allOf:
+ - $ref: /schemas/types.yaml#definitions/phandle-array
+ - maxItems: 1
+ description:
+ The SRAM that needs to be claimed to access the display engine
+ bus.
+
+ ranges: true
+
+patternProperties:
+ # All other properties should be child nodes with unit-address and 'reg'
+ "^[a-zA-Z][a-zA-Z0-9,+\\-._]{0,63}@[0-9a-fA-F]+$":
+ type: object
+ properties:
+ reg:
+ maxItems: 1
+
+ required:
+ - reg
+
+required:
+ - compatible
+ - reg
+ - "#address-cells"
+ - "#size-cells"
+ - ranges
+ - allwinner,sram
+
+additionalProperties: false
+
+examples:
+ - |
+ bus@1000000 {
+ compatible = "allwinner,sun50i-a64-de2";
+ reg = <0x1000000 0x400000>;
+ allwinner,sram = <&de2_sram 1>;
+ #address-cells = <1>;
+ #size-cells = <1>;
+ ranges = <0 0x1000000 0x400000>;
+
+ display_clocks: clock@0 {
+ compatible = "allwinner,sun50i-a64-de2-clk";
+ reg = <0x0 0x100000>;
+ clocks = <&ccu 52>, <&ccu 99>;
+ clock-names = "bus", "mod";
+ resets = <&ccu 30>;
+ #clock-cells = <1>;
+ #reset-cells = <1>;
+ };
+ };
+
+...
diff --git a/Documentation/devicetree/bindings/bus/imx-weim.txt b/Documentation/devicetree/bindings/bus/imx-weim.txt
index dda7d6d..1b1d1c5 100644
--- a/Documentation/devicetree/bindings/bus/imx-weim.txt
+++ b/Documentation/devicetree/bindings/bus/imx-weim.txt
@@ -44,6 +44,10 @@
what bootloader sets up in IOMUXC_GPR1[11:0] will be
used.
+ - fsl,burst-clk-enable For "fsl,imx50-weim" and "fsl,imx6q-weim" type of
+ devices, the presence of this property indicates that
+ the weim bus should operate in Burst Clock Mode.
+
Timing property for child nodes. It is mandatory, not optional.
- fsl,weim-cs-timing: The timing array, contains timing values for the
diff --git a/Documentation/devicetree/bindings/bus/moxtet.txt b/Documentation/devicetree/bindings/bus/moxtet.txt
new file mode 100644
index 0000000..fb50fc8
--- /dev/null
+++ b/Documentation/devicetree/bindings/bus/moxtet.txt
@@ -0,0 +1,46 @@
+Turris Mox module status and configuration bus (over SPI)
+
+Required properties:
+ - compatible : Should be "cznic,moxtet"
+ - #address-cells : Has to be 1
+ - #size-cells : Has to be 0
+ - spi-cpol : Required inverted clock polarity
+ - spi-cpha : Required shifted clock phase
+ - interrupts : Must contain reference to the shared interrupt line
+ - interrupt-controller : Required
+ - #interrupt-cells : Has to be 1
+
+For other required and optional properties of SPI slave nodes please refer to
+../spi/spi-bus.txt.
+
+Required properties of subnodes:
+ - reg : Should be position on the Moxtet bus (how many Moxtet
+ modules are between this module and CPU module, so
+ either 0 or a positive integer)
+
+The driver finds the devices connected to the bus by itself, but it may be
+needed to reference some of them from other parts of the device tree. In that
+case the devices can be defined as subnodes of the moxtet node.
+
+Example:
+
+ moxtet@1 {
+ compatible = "cznic,moxtet";
+ #address-cells = <1>;
+ #size-cells = <0>;
+ reg = <1>;
+ spi-max-frequency = <10000000>;
+ spi-cpol;
+ spi-cpha;
+ interrupt-controller;
+ #interrupt-cells = <1>;
+ interrupt-parent = <&gpiosb>;
+ interrupts = <5 IRQ_TYPE_EDGE_FALLING>;
+
+ moxtet_sfp: gpio@0 {
+ compatible = "cznic,moxtet-gpio";
+ gpio-controller;
+ #gpio-cells = <2>;
+ reg = <0>;
+ }
+ };
diff --git a/Documentation/devicetree/bindings/bus/qcom,ebi2.txt b/Documentation/devicetree/bindings/bus/qcom,ebi2.txt
index 5a7d567..5058aa2c 100644
--- a/Documentation/devicetree/bindings/bus/qcom,ebi2.txt
+++ b/Documentation/devicetree/bindings/bus/qcom,ebi2.txt
@@ -71,7 +71,7 @@
The following optional properties are properties that can be tagged onto
any device subnode. We are assuming that there can be only ONE device per
-chipselect subnode, else the properties will become ambigous.
+chipselect subnode, else the properties will become ambiguous.
Optional properties arrays for SLOW chip selects:
- qcom,xmem-recovery-cycles: recovery cycles is the time the memory continues to
diff --git a/Documentation/devicetree/bindings/bus/sun50i-de2-bus.txt b/Documentation/devicetree/bindings/bus/sun50i-de2-bus.txt
deleted file mode 100644
index b9d5337..0000000
--- a/Documentation/devicetree/bindings/bus/sun50i-de2-bus.txt
+++ /dev/null
@@ -1,40 +0,0 @@
-Device tree bindings for Allwinner DE2/3 bus
-
-The Allwinner A64 DE2 is on a special bus, which needs a SRAM region (SRAM C)
-to be claimed for enabling the access. The DE3 on Allwinner H6 is at the same
-situation, and the binding also applies.
-
-Required properties:
-
- - compatible: Should be one of:
- - "allwinner,sun50i-a64-de2"
- - "allwinner,sun50i-h6-de3", "allwinner,sun50i-a64-de2"
- - reg: A resource specifier for the register space
- - #address-cells: Must be set to 1
- - #size-cells: Must be set to 1
- - ranges: Must be set up to map the address space inside the
- DE2, for the sub-blocks of DE2.
- - allwinner,sram: the SRAM that needs to be claimed
-
-Example:
-
- de2@1000000 {
- compatible = "allwinner,sun50i-a64-de2";
- reg = <0x1000000 0x400000>;
- allwinner,sram = <&de2_sram 1>;
- #address-cells = <1>;
- #size-cells = <1>;
- ranges = <0 0x1000000 0x400000>;
-
- display_clocks: clock@0 {
- compatible = "allwinner,sun50i-a64-de2-clk";
- reg = <0x0 0x100000>;
- clocks = <&ccu CLK_DE>,
- <&ccu CLK_BUS_DE>;
- clock-names = "mod",
- "bus";
- resets = <&ccu RST_BUS_DE>;
- #clock-cells = <1>;
- #reset-cells = <1>;
- };
- };
diff --git a/Documentation/devicetree/bindings/clock/allwinner,sun4i-a10-ccu.yaml b/Documentation/devicetree/bindings/clock/allwinner,sun4i-a10-ccu.yaml
index fa4d143..64938fd 100644
--- a/Documentation/devicetree/bindings/clock/allwinner,sun4i-a10-ccu.yaml
+++ b/Documentation/devicetree/bindings/clock/allwinner,sun4i-a10-ccu.yaml
@@ -31,6 +31,7 @@
- allwinner,sun8i-h3-ccu
- allwinner,sun8i-h3-r-ccu
- allwinner,sun8i-r40-ccu
+ - allwinner,sun8i-v3-ccu
- allwinner,sun8i-v3s-ccu
- allwinner,sun9i-a80-ccu
- allwinner,sun50i-a64-ccu
diff --git a/Documentation/devicetree/bindings/clock/amlogic,axg-audio-clkc.txt b/Documentation/devicetree/bindings/clock/amlogic,axg-audio-clkc.txt
index 0f77774..b3957d1 100644
--- a/Documentation/devicetree/bindings/clock/amlogic,axg-audio-clkc.txt
+++ b/Documentation/devicetree/bindings/clock/amlogic,axg-audio-clkc.txt
@@ -22,6 +22,7 @@
components.
- resets : phandle of the internal reset line
- #clock-cells : should be 1.
+- #reset-cells : should be 1 on the g12a (and following) soc family
Each clock is assigned an identifier and client nodes can use this identifier
to specify the clock which they consume. All available clocks are defined as
diff --git a/Documentation/devicetree/bindings/clock/amlogic,gxbb-clkc.txt b/Documentation/devicetree/bindings/clock/amlogic,gxbb-clkc.txt
index 6eaa520..7ccecd5 100644
--- a/Documentation/devicetree/bindings/clock/amlogic,gxbb-clkc.txt
+++ b/Documentation/devicetree/bindings/clock/amlogic,gxbb-clkc.txt
@@ -11,6 +11,7 @@
"amlogic,axg-clkc" for AXG SoC.
"amlogic,g12a-clkc" for G12A SoC.
"amlogic,g12b-clkc" for G12B SoC.
+ "amlogic,sm1-clkc" for SM1 SoC.
- clocks : list of clock phandle, one for each entry clock-names.
- clock-names : should contain the following:
* "xtal": the platform xtal
diff --git a/Documentation/devicetree/bindings/clock/brcm,bcm2835-cprman.txt b/Documentation/devicetree/bindings/clock/brcm,bcm2835-cprman.txt
index dd906db..9e0b03a 100644
--- a/Documentation/devicetree/bindings/clock/brcm,bcm2835-cprman.txt
+++ b/Documentation/devicetree/bindings/clock/brcm,bcm2835-cprman.txt
@@ -12,7 +12,9 @@
the PLL dividers directly.
Required properties:
-- compatible: Should be "brcm,bcm2835-cprman"
+- compatible: should be one of the following,
+ "brcm,bcm2711-cprman"
+ "brcm,bcm2835-cprman"
- #clock-cells: Should be <1>. The permitted clock-specifier values can be
found in include/dt-bindings/clock/bcm2835.h
- reg: Specifies base physical address and size of the registers
diff --git a/Documentation/devicetree/bindings/clock/imx8mn-clock.yaml b/Documentation/devicetree/bindings/clock/imx8mn-clock.yaml
new file mode 100644
index 0000000..622f365
--- /dev/null
+++ b/Documentation/devicetree/bindings/clock/imx8mn-clock.yaml
@@ -0,0 +1,112 @@
+# SPDX-License-Identifier: GPL-2.0
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/bindings/clock/imx8mn-clock.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: NXP i.MX8M Nano Clock Control Module Binding
+
+maintainers:
+ - Anson Huang <Anson.Huang@nxp.com>
+
+description: |
+ NXP i.MX8M Nano clock control module is an integrated clock controller, which
+ generates and supplies to all modules.
+
+properties:
+ compatible:
+ const: fsl,imx8mn-ccm
+
+ reg:
+ maxItems: 1
+
+ clocks:
+ items:
+ - description: 32k osc
+ - description: 24m osc
+ - description: ext1 clock input
+ - description: ext2 clock input
+ - description: ext3 clock input
+ - description: ext4 clock input
+
+ clock-names:
+ items:
+ - const: osc_32k
+ - const: osc_24m
+ - const: clk_ext1
+ - const: clk_ext2
+ - const: clk_ext3
+ - const: clk_ext4
+
+ '#clock-cells':
+ const: 1
+ description: |
+ The clock consumer should specify the desired clock by having the clock
+ ID in its "clocks" phandle cell. See include/dt-bindings/clock/imx8mn-clock.h
+ for the full list of i.MX8M Nano clock IDs.
+
+required:
+ - compatible
+ - reg
+ - clocks
+ - clock-names
+ - '#clock-cells'
+
+examples:
+ # Clock Control Module node:
+ - |
+ clk: clock-controller@30380000 {
+ compatible = "fsl,imx8mn-ccm";
+ reg = <0x0 0x30380000 0x0 0x10000>;
+ #clock-cells = <1>;
+ clocks = <&osc_32k>, <&osc_24m>, <&clk_ext1>,
+ <&clk_ext2>, <&clk_ext3>, <&clk_ext4>;
+ clock-names = "osc_32k", "osc_24m", "clk_ext1",
+ "clk_ext2", "clk_ext3", "clk_ext4";
+ };
+
+ # Required external clocks for Clock Control Module node:
+ - |
+ osc_32k: clock-osc-32k {
+ compatible = "fixed-clock";
+ #clock-cells = <0>;
+ clock-frequency = <32768>;
+ clock-output-names = "osc_32k";
+ };
+
+ osc_24m: clock-osc-24m {
+ compatible = "fixed-clock";
+ #clock-cells = <0>;
+ clock-frequency = <24000000>;
+ clock-output-names = "osc_24m";
+ };
+
+ clk_ext1: clock-ext1 {
+ compatible = "fixed-clock";
+ #clock-cells = <0>;
+ clock-frequency = <133000000>;
+ clock-output-names = "clk_ext1";
+ };
+
+ clk_ext2: clock-ext2 {
+ compatible = "fixed-clock";
+ #clock-cells = <0>;
+ clock-frequency = <133000000>;
+ clock-output-names = "clk_ext2";
+ };
+
+ clk_ext3: clock-ext3 {
+ compatible = "fixed-clock";
+ #clock-cells = <0>;
+ clock-frequency = <133000000>;
+ clock-output-names = "clk_ext3";
+ };
+
+ clk_ext4: clock-ext4 {
+ compatible = "fixed-clock";
+ #clock-cells = <0>;
+ clock-frequency= <133000000>;
+ clock-output-names = "clk_ext4";
+ };
+
+...
diff --git a/Documentation/devicetree/bindings/clock/qcom,gcc.txt b/Documentation/devicetree/bindings/clock/qcom,gcc.txt
index 8661c3c..d14362a 100644
--- a/Documentation/devicetree/bindings/clock/qcom,gcc.txt
+++ b/Documentation/devicetree/bindings/clock/qcom,gcc.txt
@@ -23,6 +23,7 @@
"qcom,gcc-sdm630"
"qcom,gcc-sdm660"
"qcom,gcc-sdm845"
+ "qcom,gcc-sm8150"
- reg : shall contain base register location and length
- #clock-cells : shall contain 1
@@ -38,6 +39,13 @@
- protected-clocks : Protected clock specifier list as per common clock
binding.
+For SM8150 only:
+ - clocks: a list of phandles and clock-specifier pairs,
+ one for each entry in clock-names.
+ - clock-names: "bi_tcxo" (required)
+ "sleep_clk" (optional)
+ "aud_ref_clock" (optional)
+
Example:
clock-controller@900000 {
compatible = "qcom,gcc-msm8960";
@@ -71,3 +79,16 @@
<GCC_LPASS_Q6_AXI_CLK>,
<GCC_LPASS_SWAY_CLK>;
};
+
+Example of GCC with clocks
+ gcc: clock-controller@100000 {
+ compatible = "qcom,gcc-sm8150";
+ reg = <0x00100000 0x1f0000>;
+ #clock-cells = <1>;
+ #reset-cells = <1>;
+ #power-domain-cells = <1>;
+ clock-names = "bi_tcxo",
+ "sleep_clk";
+ clocks = <&rpmcc RPM_SMD_XO_CLK_SRC>,
+ <&sleep_clk>;
+ };
diff --git a/Documentation/devicetree/bindings/clock/qcom,rpmh-clk.txt b/Documentation/devicetree/bindings/clock/qcom,rpmh-clk.txt
index 3c00765..365bbde 100644
--- a/Documentation/devicetree/bindings/clock/qcom,rpmh-clk.txt
+++ b/Documentation/devicetree/bindings/clock/qcom,rpmh-clk.txt
@@ -6,9 +6,14 @@
other hardware subsystems via RSC to control clocks.
Required properties :
-- compatible : shall contain "qcom,sdm845-rpmh-clk"
+- compatible : must be one of:
+ "qcom,sdm845-rpmh-clk"
+ "qcom,sm8150-rpmh-clk"
- #clock-cells : must contain 1
+- clocks: a list of phandles and clock-specifier pairs,
+ one for each entry in clock-names.
+- clock-names: Parent board clock: "xo".
Example :
diff --git a/Documentation/devicetree/bindings/clock/emev2-clock.txt b/Documentation/devicetree/bindings/clock/renesas,emev2-smu.txt
similarity index 100%
rename from Documentation/devicetree/bindings/clock/emev2-clock.txt
rename to Documentation/devicetree/bindings/clock/renesas,emev2-smu.txt
diff --git a/Documentation/devicetree/bindings/clock/rockchip,rk3308-cru.txt b/Documentation/devicetree/bindings/clock/rockchip,rk3308-cru.txt
new file mode 100644
index 0000000..9b151c5
--- /dev/null
+++ b/Documentation/devicetree/bindings/clock/rockchip,rk3308-cru.txt
@@ -0,0 +1,60 @@
+* Rockchip RK3308 Clock and Reset Unit
+
+The RK3308 clock controller generates and supplies clock to various
+controllers within the SoC and also implements a reset controller for SoC
+peripherals.
+
+Required Properties:
+
+- compatible: CRU should be "rockchip,rk3308-cru"
+- reg: physical base address of the controller and length of memory mapped
+ region.
+- #clock-cells: should be 1.
+- #reset-cells: should be 1.
+
+Optional Properties:
+
+- rockchip,grf: phandle to the syscon managing the "general register files"
+ If missing, pll rates are not changeable, due to the missing pll lock status.
+
+Each clock is assigned an identifier and client nodes can use this identifier
+to specify the clock which they consume. All available clocks are defined as
+preprocessor macros in the dt-bindings/clock/rk3308-cru.h headers and can be
+used in device tree sources. Similar macros exist for the reset sources in
+these files.
+
+External clocks:
+
+There are several clocks that are generated outside the SoC. It is expected
+that they are defined using standard clock bindings with following
+clock-output-names:
+ - "xin24m" - crystal input - required,
+ - "xin32k" - rtc clock - optional,
+ - "mclk_i2s0_8ch_in", "mclk_i2s1_8ch_in", "mclk_i2s2_8ch_in",
+ "mclk_i2s3_8ch_in", "mclk_i2s0_2ch_in",
+ "mclk_i2s1_2ch_in" - external I2S or SPDIF clock - optional,
+ - "mac_clkin" - external MAC clock - optional
+
+Example: Clock controller node:
+
+ cru: clock-controller@ff500000 {
+ compatible = "rockchip,rk3308-cru";
+ reg = <0x0 0xff500000 0x0 0x1000>;
+ rockchip,grf = <&grf>;
+ #clock-cells = <1>;
+ #reset-cells = <1>;
+ };
+
+Example: UART controller node that consumes the clock generated by the clock
+ controller:
+
+ uart0: serial@ff0a0000 {
+ compatible = "rockchip,rk3308-uart", "snps,dw-apb-uart";
+ reg = <0x0 0xff0a0000 0x0 0x100>;
+ interrupts = <GIC_SPI 18 IRQ_TYPE_LEVEL_HIGH>;
+ clocks = <&cru SCLK_UART0>, <&cru PCLK_UART0>;
+ clock-names = "baudclk", "apb_pclk";
+ reg-shift = <2>;
+ reg-io-width = <4>;
+ status = "disabled";
+ };
diff --git a/Documentation/devicetree/bindings/clock/ti,cdce925.txt b/Documentation/devicetree/bindings/clock/ti,cdce925.txt
index 0d01f2d..26544c8 100644
--- a/Documentation/devicetree/bindings/clock/ti,cdce925.txt
+++ b/Documentation/devicetree/bindings/clock/ti,cdce925.txt
@@ -24,6 +24,8 @@
Optional properties:
- xtal-load-pf: Crystal load-capacitor value to fine-tune performance on a
board, or to compensate for external influences.
+- vdd-supply: A regulator node for Vdd
+- vddout-supply: A regulator node for Vddout
For all PLL1, PLL2, ... an optional child node can be used to specify spread
spectrum clocking parameters for a board.
@@ -41,6 +43,8 @@
clocks = <&xtal_27Mhz>;
#clock-cells = <1>;
xtal-load-pf = <5>;
+ vdd-supply = <&1v8-reg>;
+ vddout-supply = <&3v3-reg>;
/* PLL options to get SSC 1% centered */
PLL2 {
spread-spectrum = <4>;
diff --git a/Documentation/devicetree/bindings/connector/usb-connector.txt b/Documentation/devicetree/bindings/connector/usb-connector.txt
index cef556d..d357987 100644
--- a/Documentation/devicetree/bindings/connector/usb-connector.txt
+++ b/Documentation/devicetree/bindings/connector/usb-connector.txt
@@ -17,6 +17,20 @@
- self-powered: Set this property if the usb device that has its own power
source.
+Optional properties for usb-b-connector:
+- id-gpios: an input gpio for USB ID pin.
+- vbus-gpios: an input gpio for USB VBUS pin, used to detect presence of
+ VBUS 5V.
+ see gpio/gpio.txt.
+- vbus-supply: a phandle to the regulator for USB VBUS if needed when host
+ mode or dual role mode is supported.
+ Particularly, if use an output GPIO to control a VBUS regulator, should
+ model it as a regulator.
+ see regulator/fixed-regulator.yaml
+- pinctrl-names : a pinctrl state named "default" is optional
+- pinctrl-0 : pin control group
+ see pinctrl/pinctrl-bindings.txt
+
Optional properties for usb-c-connector:
- power-role: should be one of "source", "sink" or "dual"(DRP) if typec
connector has power support.
diff --git a/Documentation/devicetree/bindings/cpu/cpu-topology.txt b/Documentation/devicetree/bindings/cpu/cpu-topology.txt
new file mode 100644
index 0000000..9991818
--- /dev/null
+++ b/Documentation/devicetree/bindings/cpu/cpu-topology.txt
@@ -0,0 +1,553 @@
+===========================================
+CPU topology binding description
+===========================================
+
+===========================================
+1 - Introduction
+===========================================
+
+In a SMP system, the hierarchy of CPUs is defined through three entities that
+are used to describe the layout of physical CPUs in the system:
+
+- socket
+- cluster
+- core
+- thread
+
+The bottom hierarchy level sits at core or thread level depending on whether
+symmetric multi-threading (SMT) is supported or not.
+
+For instance in a system where CPUs support SMT, "cpu" nodes represent all
+threads existing in the system and map to the hierarchy level "thread" above.
+In systems where SMT is not supported "cpu" nodes represent all cores present
+in the system and map to the hierarchy level "core" above.
+
+CPU topology bindings allow one to associate cpu nodes with hierarchical groups
+corresponding to the system hierarchy; syntactically they are defined as device
+tree nodes.
+
+Currently, only ARM/RISC-V intend to use this cpu topology binding but it may be
+used for any other architecture as well.
+
+The cpu nodes, as per bindings defined in [4], represent the devices that
+correspond to physical CPUs and are to be mapped to the hierarchy levels.
+
+A topology description containing phandles to cpu nodes that are not compliant
+with bindings standardized in [4] is therefore considered invalid.
+
+===========================================
+2 - cpu-map node
+===========================================
+
+The ARM/RISC-V CPU topology is defined within the cpu-map node, which is a direct
+child of the cpus node and provides a container where the actual topology
+nodes are listed.
+
+- cpu-map node
+
+ Usage: Optional - On SMP systems provide CPUs topology to the OS.
+ Uniprocessor systems do not require a topology
+ description and therefore should not define a
+ cpu-map node.
+
+ Description: The cpu-map node is just a container node where its
+ subnodes describe the CPU topology.
+
+ Node name must be "cpu-map".
+
+ The cpu-map node's parent node must be the cpus node.
+
+ The cpu-map node's child nodes can be:
+
+ - one or more cluster nodes or
+ - one or more socket nodes in a multi-socket system
+
+ Any other configuration is considered invalid.
+
+The cpu-map node can only contain 4 types of child nodes:
+
+- socket node
+- cluster node
+- core node
+- thread node
+
+whose bindings are described in paragraph 3.
+
+The nodes describing the CPU topology (socket/cluster/core/thread) can
+only be defined within the cpu-map node and every core/thread in the
+system must be defined within the topology. Any other configuration is
+invalid and therefore must be ignored.
+
+===========================================
+2.1 - cpu-map child nodes naming convention
+===========================================
+
+cpu-map child nodes must follow a naming convention where the node name
+must be "socketN", "clusterN", "coreN", "threadN" depending on the node type
+(ie socket/cluster/core/thread) (where N = {0, 1, ...} is the node number; nodes
+which are siblings within a single common parent node must be given a unique and
+sequential N value, starting from 0).
+cpu-map child nodes which do not share a common parent node can have the same
+name (ie same number N as other cpu-map child nodes at different device tree
+levels) since name uniqueness will be guaranteed by the device tree hierarchy.
+
+===========================================
+3 - socket/cluster/core/thread node bindings
+===========================================
+
+Bindings for socket/cluster/cpu/thread nodes are defined as follows:
+
+- socket node
+
+ Description: must be declared within a cpu-map node, one node
+ per physical socket in the system. A system can
+ contain single or multiple physical socket.
+ The association of sockets and NUMA nodes is beyond
+ the scope of this bindings, please refer [2] for
+ NUMA bindings.
+
+ This node is optional for a single socket system.
+
+ The socket node name must be "socketN" as described in 2.1 above.
+ A socket node can not be a leaf node.
+
+ A socket node's child nodes must be one or more cluster nodes.
+
+ Any other configuration is considered invalid.
+
+- cluster node
+
+ Description: must be declared within a cpu-map node, one node
+ per cluster. A system can contain several layers of
+ clustering within a single physical socket and cluster
+ nodes can be contained in parent cluster nodes.
+
+ The cluster node name must be "clusterN" as described in 2.1 above.
+ A cluster node can not be a leaf node.
+
+ A cluster node's child nodes must be:
+
+ - one or more cluster nodes; or
+ - one or more core nodes
+
+ Any other configuration is considered invalid.
+
+- core node
+
+ Description: must be declared in a cluster node, one node per core in
+ the cluster. If the system does not support SMT, core
+ nodes are leaf nodes, otherwise they become containers of
+ thread nodes.
+
+ The core node name must be "coreN" as described in 2.1 above.
+
+ A core node must be a leaf node if SMT is not supported.
+
+ Properties for core nodes that are leaf nodes:
+
+ - cpu
+ Usage: required
+ Value type: <phandle>
+ Definition: a phandle to the cpu node that corresponds to the
+ core node.
+
+ If a core node is not a leaf node (CPUs supporting SMT) a core node's
+ child nodes can be:
+
+ - one or more thread nodes
+
+ Any other configuration is considered invalid.
+
+- thread node
+
+ Description: must be declared in a core node, one node per thread
+ in the core if the system supports SMT. Thread nodes are
+ always leaf nodes in the device tree.
+
+ The thread node name must be "threadN" as described in 2.1 above.
+
+ A thread node must be a leaf node.
+
+ A thread node must contain the following property:
+
+ - cpu
+ Usage: required
+ Value type: <phandle>
+ Definition: a phandle to the cpu node that corresponds to
+ the thread node.
+
+===========================================
+4 - Example dts
+===========================================
+
+Example 1 (ARM 64-bit, 16-cpu system, two clusters of clusters in a single
+physical socket):
+
+cpus {
+ #size-cells = <0>;
+ #address-cells = <2>;
+
+ cpu-map {
+ socket0 {
+ cluster0 {
+ cluster0 {
+ core0 {
+ thread0 {
+ cpu = <&CPU0>;
+ };
+ thread1 {
+ cpu = <&CPU1>;
+ };
+ };
+
+ core1 {
+ thread0 {
+ cpu = <&CPU2>;
+ };
+ thread1 {
+ cpu = <&CPU3>;
+ };
+ };
+ };
+
+ cluster1 {
+ core0 {
+ thread0 {
+ cpu = <&CPU4>;
+ };
+ thread1 {
+ cpu = <&CPU5>;
+ };
+ };
+
+ core1 {
+ thread0 {
+ cpu = <&CPU6>;
+ };
+ thread1 {
+ cpu = <&CPU7>;
+ };
+ };
+ };
+ };
+
+ cluster1 {
+ cluster0 {
+ core0 {
+ thread0 {
+ cpu = <&CPU8>;
+ };
+ thread1 {
+ cpu = <&CPU9>;
+ };
+ };
+ core1 {
+ thread0 {
+ cpu = <&CPU10>;
+ };
+ thread1 {
+ cpu = <&CPU11>;
+ };
+ };
+ };
+
+ cluster1 {
+ core0 {
+ thread0 {
+ cpu = <&CPU12>;
+ };
+ thread1 {
+ cpu = <&CPU13>;
+ };
+ };
+ core1 {
+ thread0 {
+ cpu = <&CPU14>;
+ };
+ thread1 {
+ cpu = <&CPU15>;
+ };
+ };
+ };
+ };
+ };
+ };
+
+ CPU0: cpu@0 {
+ device_type = "cpu";
+ compatible = "arm,cortex-a57";
+ reg = <0x0 0x0>;
+ enable-method = "spin-table";
+ cpu-release-addr = <0 0x20000000>;
+ };
+
+ CPU1: cpu@1 {
+ device_type = "cpu";
+ compatible = "arm,cortex-a57";
+ reg = <0x0 0x1>;
+ enable-method = "spin-table";
+ cpu-release-addr = <0 0x20000000>;
+ };
+
+ CPU2: cpu@100 {
+ device_type = "cpu";
+ compatible = "arm,cortex-a57";
+ reg = <0x0 0x100>;
+ enable-method = "spin-table";
+ cpu-release-addr = <0 0x20000000>;
+ };
+
+ CPU3: cpu@101 {
+ device_type = "cpu";
+ compatible = "arm,cortex-a57";
+ reg = <0x0 0x101>;
+ enable-method = "spin-table";
+ cpu-release-addr = <0 0x20000000>;
+ };
+
+ CPU4: cpu@10000 {
+ device_type = "cpu";
+ compatible = "arm,cortex-a57";
+ reg = <0x0 0x10000>;
+ enable-method = "spin-table";
+ cpu-release-addr = <0 0x20000000>;
+ };
+
+ CPU5: cpu@10001 {
+ device_type = "cpu";
+ compatible = "arm,cortex-a57";
+ reg = <0x0 0x10001>;
+ enable-method = "spin-table";
+ cpu-release-addr = <0 0x20000000>;
+ };
+
+ CPU6: cpu@10100 {
+ device_type = "cpu";
+ compatible = "arm,cortex-a57";
+ reg = <0x0 0x10100>;
+ enable-method = "spin-table";
+ cpu-release-addr = <0 0x20000000>;
+ };
+
+ CPU7: cpu@10101 {
+ device_type = "cpu";
+ compatible = "arm,cortex-a57";
+ reg = <0x0 0x10101>;
+ enable-method = "spin-table";
+ cpu-release-addr = <0 0x20000000>;
+ };
+
+ CPU8: cpu@100000000 {
+ device_type = "cpu";
+ compatible = "arm,cortex-a57";
+ reg = <0x1 0x0>;
+ enable-method = "spin-table";
+ cpu-release-addr = <0 0x20000000>;
+ };
+
+ CPU9: cpu@100000001 {
+ device_type = "cpu";
+ compatible = "arm,cortex-a57";
+ reg = <0x1 0x1>;
+ enable-method = "spin-table";
+ cpu-release-addr = <0 0x20000000>;
+ };
+
+ CPU10: cpu@100000100 {
+ device_type = "cpu";
+ compatible = "arm,cortex-a57";
+ reg = <0x1 0x100>;
+ enable-method = "spin-table";
+ cpu-release-addr = <0 0x20000000>;
+ };
+
+ CPU11: cpu@100000101 {
+ device_type = "cpu";
+ compatible = "arm,cortex-a57";
+ reg = <0x1 0x101>;
+ enable-method = "spin-table";
+ cpu-release-addr = <0 0x20000000>;
+ };
+
+ CPU12: cpu@100010000 {
+ device_type = "cpu";
+ compatible = "arm,cortex-a57";
+ reg = <0x1 0x10000>;
+ enable-method = "spin-table";
+ cpu-release-addr = <0 0x20000000>;
+ };
+
+ CPU13: cpu@100010001 {
+ device_type = "cpu";
+ compatible = "arm,cortex-a57";
+ reg = <0x1 0x10001>;
+ enable-method = "spin-table";
+ cpu-release-addr = <0 0x20000000>;
+ };
+
+ CPU14: cpu@100010100 {
+ device_type = "cpu";
+ compatible = "arm,cortex-a57";
+ reg = <0x1 0x10100>;
+ enable-method = "spin-table";
+ cpu-release-addr = <0 0x20000000>;
+ };
+
+ CPU15: cpu@100010101 {
+ device_type = "cpu";
+ compatible = "arm,cortex-a57";
+ reg = <0x1 0x10101>;
+ enable-method = "spin-table";
+ cpu-release-addr = <0 0x20000000>;
+ };
+};
+
+Example 2 (ARM 32-bit, dual-cluster, 8-cpu system, no SMT):
+
+cpus {
+ #size-cells = <0>;
+ #address-cells = <1>;
+
+ cpu-map {
+ cluster0 {
+ core0 {
+ cpu = <&CPU0>;
+ };
+ core1 {
+ cpu = <&CPU1>;
+ };
+ core2 {
+ cpu = <&CPU2>;
+ };
+ core3 {
+ cpu = <&CPU3>;
+ };
+ };
+
+ cluster1 {
+ core0 {
+ cpu = <&CPU4>;
+ };
+ core1 {
+ cpu = <&CPU5>;
+ };
+ core2 {
+ cpu = <&CPU6>;
+ };
+ core3 {
+ cpu = <&CPU7>;
+ };
+ };
+ };
+
+ CPU0: cpu@0 {
+ device_type = "cpu";
+ compatible = "arm,cortex-a15";
+ reg = <0x0>;
+ };
+
+ CPU1: cpu@1 {
+ device_type = "cpu";
+ compatible = "arm,cortex-a15";
+ reg = <0x1>;
+ };
+
+ CPU2: cpu@2 {
+ device_type = "cpu";
+ compatible = "arm,cortex-a15";
+ reg = <0x2>;
+ };
+
+ CPU3: cpu@3 {
+ device_type = "cpu";
+ compatible = "arm,cortex-a15";
+ reg = <0x3>;
+ };
+
+ CPU4: cpu@100 {
+ device_type = "cpu";
+ compatible = "arm,cortex-a7";
+ reg = <0x100>;
+ };
+
+ CPU5: cpu@101 {
+ device_type = "cpu";
+ compatible = "arm,cortex-a7";
+ reg = <0x101>;
+ };
+
+ CPU6: cpu@102 {
+ device_type = "cpu";
+ compatible = "arm,cortex-a7";
+ reg = <0x102>;
+ };
+
+ CPU7: cpu@103 {
+ device_type = "cpu";
+ compatible = "arm,cortex-a7";
+ reg = <0x103>;
+ };
+};
+
+Example 3: HiFive Unleashed (RISC-V 64 bit, 4 core system)
+
+{
+ #address-cells = <2>;
+ #size-cells = <2>;
+ compatible = "sifive,fu540g", "sifive,fu500";
+ model = "sifive,hifive-unleashed-a00";
+
+ ...
+ cpus {
+ #address-cells = <1>;
+ #size-cells = <0>;
+ cpu-map {
+ socket0 {
+ cluster0 {
+ core0 {
+ cpu = <&CPU1>;
+ };
+ core1 {
+ cpu = <&CPU2>;
+ };
+ core2 {
+ cpu0 = <&CPU2>;
+ };
+ core3 {
+ cpu0 = <&CPU3>;
+ };
+ };
+ };
+ };
+
+ CPU1: cpu@1 {
+ device_type = "cpu";
+ compatible = "sifive,rocket0", "riscv";
+ reg = <0x1>;
+ }
+
+ CPU2: cpu@2 {
+ device_type = "cpu";
+ compatible = "sifive,rocket0", "riscv";
+ reg = <0x2>;
+ }
+ CPU3: cpu@3 {
+ device_type = "cpu";
+ compatible = "sifive,rocket0", "riscv";
+ reg = <0x3>;
+ }
+ CPU4: cpu@4 {
+ device_type = "cpu";
+ compatible = "sifive,rocket0", "riscv";
+ reg = <0x4>;
+ }
+ }
+};
+===============================================================================
+[1] ARM Linux kernel documentation
+ Documentation/devicetree/bindings/arm/cpus.yaml
+[2] Devicetree NUMA binding description
+ Documentation/devicetree/bindings/numa.txt
+[3] RISC-V Linux kernel documentation
+ Documentation/devicetree/bindings/riscv/cpus.txt
+[4] https://www.devicetree.org/specifications/
diff --git a/Documentation/devicetree/bindings/crypto/allwinner,sun4i-a10-crypto.yaml b/Documentation/devicetree/bindings/crypto/allwinner,sun4i-a10-crypto.yaml
new file mode 100644
index 0000000..80b3e73
--- /dev/null
+++ b/Documentation/devicetree/bindings/crypto/allwinner,sun4i-a10-crypto.yaml
@@ -0,0 +1,79 @@
+# SPDX-License-Identifier: GPL-2.0
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/crypto/allwinner,sun4i-a10-crypto.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Allwinner A10 Security System Device Tree Bindings
+
+maintainers:
+ - Chen-Yu Tsai <wens@csie.org>
+ - Maxime Ripard <maxime.ripard@bootlin.com>
+
+properties:
+ compatible:
+ oneOf:
+ - const: allwinner,sun4i-a10-crypto
+ - items:
+ - const: allwinner,sun5i-a13-crypto
+ - const: allwinner,sun4i-a10-crypto
+ - items:
+ - const: allwinner,sun6i-a31-crypto
+ - const: allwinner,sun4i-a10-crypto
+ - items:
+ - const: allwinner,sun7i-a20-crypto
+ - const: allwinner,sun4i-a10-crypto
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+ clocks:
+ items:
+ - description: Bus Clock
+ - description: Module Clock
+
+ clock-names:
+ items:
+ - const: ahb
+ - const: mod
+
+ resets:
+ maxItems: 1
+
+ reset-names:
+ const: ahb
+
+required:
+ - compatible
+ - reg
+ - interrupts
+ - clocks
+ - clock-names
+
+if:
+ properties:
+ compatible:
+ contains:
+ const: allwinner,sun6i-a31-crypto
+
+then:
+ required:
+ - resets
+ - reset-names
+
+additionalProperties: false
+
+examples:
+ - |
+ crypto: crypto-engine@1c15000 {
+ compatible = "allwinner,sun4i-a10-crypto";
+ reg = <0x01c15000 0x1000>;
+ interrupts = <86>;
+ clocks = <&ahb_gates 5>, <&ss_clk>;
+ clock-names = "ahb", "mod";
+ };
+
+...
diff --git a/Documentation/devicetree/bindings/crypto/sun4i-ss.txt b/Documentation/devicetree/bindings/crypto/sun4i-ss.txt
deleted file mode 100644
index f2dc3d9..0000000
--- a/Documentation/devicetree/bindings/crypto/sun4i-ss.txt
+++ /dev/null
@@ -1,23 +0,0 @@
-* Allwinner Security System found on A20 SoC
-
-Required properties:
-- compatible : Should be "allwinner,sun4i-a10-crypto".
-- reg: Should contain the Security System register location and length.
-- interrupts: Should contain the IRQ line for the Security System.
-- clocks : List of clock specifiers, corresponding to ahb and ss.
-- clock-names : Name of the functional clock, should be
- * "ahb" : AHB gating clock
- * "mod" : SS controller clock
-
-Optional properties:
- - resets : phandle + reset specifier pair
- - reset-names : must contain "ahb"
-
-Example:
- crypto: crypto-engine@1c15000 {
- compatible = "allwinner,sun4i-a10-crypto";
- reg = <0x01c15000 0x1000>;
- interrupts = <GIC_SPI 86 IRQ_TYPE_LEVEL_HIGH>;
- clocks = <&ahb_gates 5>, <&ss_clk>;
- clock-names = "ahb", "mod";
- };
diff --git a/Documentation/devicetree/bindings/display/amlogic,meson-dw-hdmi.txt b/Documentation/devicetree/bindings/display/amlogic,meson-dw-hdmi.txt
deleted file mode 100644
index 3a50a78..0000000
--- a/Documentation/devicetree/bindings/display/amlogic,meson-dw-hdmi.txt
+++ /dev/null
@@ -1,119 +0,0 @@
-Amlogic specific extensions to the Synopsys Designware HDMI Controller
-======================================================================
-
-The Amlogic Meson Synopsys Designware Integration is composed of :
-- A Synopsys DesignWare HDMI Controller IP
-- A TOP control block controlling the Clocks and PHY
-- A custom HDMI PHY in order to convert video to TMDS signal
- ___________________________________
-| HDMI TOP |<= HPD
-|___________________________________|
-| | |
-| Synopsys HDMI | HDMI PHY |=> TMDS
-| Controller |________________|
-|___________________________________|<=> DDC
-
-The HDMI TOP block only supports HPD sensing.
-The Synopsys HDMI Controller interrupt is routed through the
-TOP Block interrupt.
-Communication to the TOP Block and the Synopsys HDMI Controller is done
-via a pair of dedicated addr+read/write registers.
-The HDMI PHY is configured by registers in the HHI register block.
-
-Pixel data arrives in 4:4:4 format from the VENC block and the VPU HDMI mux
-selects either the ENCI encoder for the 576i or 480i formats or the ENCP
-encoder for all the other formats including interlaced HD formats.
-
-The VENC uses a DVI encoder on top of the ENCI or ENCP encoders to generate
-DVI timings for the HDMI controller.
-
-Amlogic Meson GXBB, GXL and GXM SoCs families embeds the Synopsys DesignWare
-HDMI TX IP version 2.01a with HDCP and I2C & S/PDIF
-audio source interfaces.
-
-Required properties:
-- compatible: value should be different for each SoC family as :
- - GXBB (S905) : "amlogic,meson-gxbb-dw-hdmi"
- - GXL (S905X, S905D) : "amlogic,meson-gxl-dw-hdmi"
- - GXM (S912) : "amlogic,meson-gxm-dw-hdmi"
- followed by the common "amlogic,meson-gx-dw-hdmi"
- - G12A (S905X2, S905Y2, S905D2) : "amlogic,meson-g12a-dw-hdmi"
-- reg: Physical base address and length of the controller's registers.
-- interrupts: The HDMI interrupt number
-- clocks, clock-names : must have the phandles to the HDMI iahb and isfr clocks,
- and the Amlogic Meson venci clocks as described in
- Documentation/devicetree/bindings/clock/clock-bindings.txt,
- the clocks are soc specific, the clock-names should be "iahb", "isfr", "venci"
-- resets, resets-names: must have the phandles to the HDMI apb, glue and phy
- resets as described in :
- Documentation/devicetree/bindings/reset/reset.txt,
- the reset-names should be "hdmitx_apb", "hdmitx", "hdmitx_phy"
-
-Optional properties:
-- hdmi-supply: Optional phandle to an external 5V regulator to power the HDMI
- logic, as described in the file ../regulator/regulator.txt
-
-Required nodes:
-
-The connections to the HDMI ports are modeled using the OF graph
-bindings specified in Documentation/devicetree/bindings/graph.txt.
-
-The following table lists for each supported model the port number
-corresponding to each HDMI output and input.
-
- Port 0 Port 1
------------------------------------------
- S905 (GXBB) VENC Input TMDS Output
- S905X (GXL) VENC Input TMDS Output
- S905D (GXL) VENC Input TMDS Output
- S912 (GXM) VENC Input TMDS Output
- S905X2 (G12A) VENC Input TMDS Output
- S905Y2 (G12A) VENC Input TMDS Output
- S905D2 (G12A) VENC Input TMDS Output
-
-Example:
-
-hdmi-connector {
- compatible = "hdmi-connector";
- type = "a";
-
- port {
- hdmi_connector_in: endpoint {
- remote-endpoint = <&hdmi_tx_tmds_out>;
- };
- };
-};
-
-hdmi_tx: hdmi-tx@c883a000 {
- compatible = "amlogic,meson-gxbb-dw-hdmi", "amlogic,meson-gx-dw-hdmi";
- reg = <0x0 0xc883a000 0x0 0x1c>;
- interrupts = <GIC_SPI 57 IRQ_TYPE_EDGE_RISING>;
- resets = <&reset RESET_HDMITX_CAPB3>,
- <&reset RESET_HDMI_SYSTEM_RESET>,
- <&reset RESET_HDMI_TX>;
- reset-names = "hdmitx_apb", "hdmitx", "hdmitx_phy";
- clocks = <&clkc CLKID_HDMI_PCLK>,
- <&clkc CLKID_CLK81>,
- <&clkc CLKID_GCLK_VENCI_INT0>;
- clock-names = "isfr", "iahb", "venci";
- #address-cells = <1>;
- #size-cells = <0>;
-
- /* VPU VENC Input */
- hdmi_tx_venc_port: port@0 {
- reg = <0>;
-
- hdmi_tx_in: endpoint {
- remote-endpoint = <&hdmi_tx_out>;
- };
- };
-
- /* TMDS Output */
- hdmi_tx_tmds_port: port@1 {
- reg = <1>;
-
- hdmi_tx_tmds_out: endpoint {
- remote-endpoint = <&hdmi_connector_in>;
- };
- };
-};
diff --git a/Documentation/devicetree/bindings/display/amlogic,meson-dw-hdmi.yaml b/Documentation/devicetree/bindings/display/amlogic,meson-dw-hdmi.yaml
new file mode 100644
index 0000000..fb74768
--- /dev/null
+++ b/Documentation/devicetree/bindings/display/amlogic,meson-dw-hdmi.yaml
@@ -0,0 +1,150 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+# Copyright 2019 BayLibre, SAS
+%YAML 1.2
+---
+$id: "http://devicetree.org/schemas/display/amlogic,meson-dw-hdmi.yaml#"
+$schema: "http://devicetree.org/meta-schemas/core.yaml#"
+
+title: Amlogic specific extensions to the Synopsys Designware HDMI Controller
+
+maintainers:
+ - Neil Armstrong <narmstrong@baylibre.com>
+
+description: |
+ The Amlogic Meson Synopsys Designware Integration is composed of
+ - A Synopsys DesignWare HDMI Controller IP
+ - A TOP control block controlling the Clocks and PHY
+ - A custom HDMI PHY in order to convert video to TMDS signal
+ ___________________________________
+ | HDMI TOP |<= HPD
+ |___________________________________|
+ | | |
+ | Synopsys HDMI | HDMI PHY |=> TMDS
+ | Controller |________________|
+ |___________________________________|<=> DDC
+
+ The HDMI TOP block only supports HPD sensing.
+ The Synopsys HDMI Controller interrupt is routed through the
+ TOP Block interrupt.
+ Communication to the TOP Block and the Synopsys HDMI Controller is done
+ via a pair of dedicated addr+read/write registers.
+ The HDMI PHY is configured by registers in the HHI register block.
+
+ Pixel data arrives in "4:4:4" format from the VENC block and the VPU HDMI mux
+ selects either the ENCI encoder for the 576i or 480i formats or the ENCP
+ encoder for all the other formats including interlaced HD formats.
+
+ The VENC uses a DVI encoder on top of the ENCI or ENCP encoders to generate
+ DVI timings for the HDMI controller.
+
+ Amlogic Meson GXBB, GXL and GXM SoCs families embeds the Synopsys DesignWare
+ HDMI TX IP version 2.01a with HDCP and I2C & S/PDIF
+ audio source interfaces.
+
+properties:
+ compatible:
+ oneOf:
+ - items:
+ - enum:
+ - amlogic,meson-gxbb-dw-hdmi # GXBB (S905)
+ - amlogic,meson-gxl-dw-hdmi # GXL (S905X, S905D)
+ - amlogic,meson-gxm-dw-hdmi # GXM (S912)
+ - const: amlogic,meson-gx-dw-hdmi
+ - enum:
+ - amlogic,meson-g12a-dw-hdmi # G12A (S905X2, S905Y2, S905D2)
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+ clocks:
+ minItems: 3
+
+ clock-names:
+ items:
+ - const: isfr
+ - const: iahb
+ - const: venci
+
+ resets:
+ minItems: 3
+
+ reset-names:
+ items:
+ - const: hdmitx_apb
+ - const: hdmitx
+ - const: hdmitx_phy
+
+ hdmi-supply:
+ description: phandle to an external 5V regulator to power the HDMI logic
+ allOf:
+ - $ref: /schemas/types.yaml#/definitions/phandle
+
+ port@0:
+ type: object
+ description:
+ A port node pointing to the VENC Input port node.
+
+ port@1:
+ type: object
+ description:
+ A port node pointing to the TMDS Output port node.
+
+ "#address-cells":
+ const: 1
+
+ "#size-cells":
+ const: 0
+
+ "#sound-dai-cells":
+ const: 0
+
+required:
+ - compatible
+ - reg
+ - interrupts
+ - clocks
+ - clock-names
+ - resets
+ - reset-names
+ - port@0
+ - port@1
+ - "#address-cells"
+ - "#size-cells"
+
+additionalProperties: false
+
+examples:
+ - |
+ hdmi_tx: hdmi-tx@c883a000 {
+ compatible = "amlogic,meson-gxbb-dw-hdmi", "amlogic,meson-gx-dw-hdmi";
+ reg = <0xc883a000 0x1c>;
+ interrupts = <57>;
+ resets = <&reset_apb>, <&reset_hdmitx>, <&reset_hdmitx_phy>;
+ reset-names = "hdmitx_apb", "hdmitx", "hdmitx_phy";
+ clocks = <&clk_isfr>, <&clk_iahb>, <&clk_venci>;
+ clock-names = "isfr", "iahb", "venci";
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ /* VPU VENC Input */
+ hdmi_tx_venc_port: port@0 {
+ reg = <0>;
+
+ hdmi_tx_in: endpoint {
+ remote-endpoint = <&hdmi_tx_out>;
+ };
+ };
+
+ /* TMDS Output */
+ hdmi_tx_tmds_port: port@1 {
+ reg = <1>;
+
+ hdmi_tx_tmds_out: endpoint {
+ remote-endpoint = <&hdmi_connector_in>;
+ };
+ };
+ };
+
diff --git a/Documentation/devicetree/bindings/display/amlogic,meson-vpu.txt b/Documentation/devicetree/bindings/display/amlogic,meson-vpu.txt
deleted file mode 100644
index be40a78..0000000
--- a/Documentation/devicetree/bindings/display/amlogic,meson-vpu.txt
+++ /dev/null
@@ -1,121 +0,0 @@
-Amlogic Meson Display Controller
-================================
-
-The Amlogic Meson Display controller is composed of several components
-that are going to be documented below:
-
-DMC|---------------VPU (Video Processing Unit)----------------|------HHI------|
- | vd1 _______ _____________ _________________ | |
-D |-------| |----| | | | | HDMI PLL |
-D | vd2 | VIU | | Video Post | | Video Encoders |<---|-----VCLK |
-R |-------| |----| Processing | | | | |
- | osd2 | | | |---| Enci ----------|----|-----VDAC------|
-R |-------| CSC |----| Scalers | | Encp ----------|----|----HDMI-TX----|
-A | osd1 | | | Blenders | | Encl ----------|----|---------------|
-M |-------|______|----|____________| |________________| | |
-___|__________________________________________________________|_______________|
-
-
-VIU: Video Input Unit
----------------------
-
-The Video Input Unit is in charge of the pixel scanout from the DDR memory.
-It fetches the frames addresses, stride and parameters from the "Canvas" memory.
-This part is also in charge of the CSC (Colorspace Conversion).
-It can handle 2 OSD Planes and 2 Video Planes.
-
-VPP: Video Post Processing
---------------------------
-
-The Video Post Processing is in charge of the scaling and blending of the
-various planes into a single pixel stream.
-There is a special "pre-blending" used by the video planes with a dedicated
-scaler and a "post-blending" to merge with the OSD Planes.
-The OSD planes also have a dedicated scaler for one of the OSD.
-
-VENC: Video Encoders
---------------------
-
-The VENC is composed of the multiple pixel encoders :
- - ENCI : Interlace Video encoder for CVBS and Interlace HDMI
- - ENCP : Progressive Video Encoder for HDMI
- - ENCL : LCD LVDS Encoder
-The VENC Unit gets a Pixel Clocks (VCLK) from a dedicated HDMI PLL and clock
-tree and provides the scanout clock to the VPP and VIU.
-The ENCI is connected to a single VDAC for Composite Output.
-The ENCI and ENCP are connected to an on-chip HDMI Transceiver.
-
-Device Tree Bindings:
----------------------
-
-VPU: Video Processing Unit
---------------------------
-
-Required properties:
-- compatible: value should be different for each SoC family as :
- - GXBB (S905) : "amlogic,meson-gxbb-vpu"
- - GXL (S905X, S905D) : "amlogic,meson-gxl-vpu"
- - GXM (S912) : "amlogic,meson-gxm-vpu"
- followed by the common "amlogic,meson-gx-vpu"
- - G12A (S905X2, S905Y2, S905D2) : "amlogic,meson-g12a-vpu"
-- reg: base address and size of he following memory-mapped regions :
- - vpu
- - hhi
-- reg-names: should contain the names of the previous memory regions
-- interrupts: should contain the VENC Vsync interrupt number
-- amlogic,canvas: phandle to canvas provider node as described in the file
- ../soc/amlogic/amlogic,canvas.txt
-
-Optional properties:
-- power-domains: Optional phandle to associated power domain as described in
- the file ../power/power_domain.txt
-
-Required nodes:
-
-The connections to the VPU output video ports are modeled using the OF graph
-bindings specified in Documentation/devicetree/bindings/graph.txt.
-
-The following table lists for each supported model the port number
-corresponding to each VPU output.
-
- Port 0 Port 1
------------------------------------------
- S905 (GXBB) CVBS VDAC HDMI-TX
- S905X (GXL) CVBS VDAC HDMI-TX
- S905D (GXL) CVBS VDAC HDMI-TX
- S912 (GXM) CVBS VDAC HDMI-TX
- S905X2 (G12A) CVBS VDAC HDMI-TX
- S905Y2 (G12A) CVBS VDAC HDMI-TX
- S905D2 (G12A) CVBS VDAC HDMI-TX
-
-Example:
-
-tv-connector {
- compatible = "composite-video-connector";
-
- port {
- tv_connector_in: endpoint {
- remote-endpoint = <&cvbs_vdac_out>;
- };
- };
-};
-
-vpu: vpu@d0100000 {
- compatible = "amlogic,meson-gxbb-vpu";
- reg = <0x0 0xd0100000 0x0 0x100000>,
- <0x0 0xc883c000 0x0 0x1000>,
- <0x0 0xc8838000 0x0 0x1000>;
- reg-names = "vpu", "hhi", "dmc";
- interrupts = <GIC_SPI 3 IRQ_TYPE_EDGE_RISING>;
- #address-cells = <1>;
- #size-cells = <0>;
-
- /* CVBS VDAC output port */
- port@0 {
- reg = <0>;
-
- cvbs_vdac_out: endpoint {
- remote-endpoint = <&tv_connector_in>;
- };
- };
-};
diff --git a/Documentation/devicetree/bindings/display/amlogic,meson-vpu.yaml b/Documentation/devicetree/bindings/display/amlogic,meson-vpu.yaml
new file mode 100644
index 0000000..d1205a6
--- /dev/null
+++ b/Documentation/devicetree/bindings/display/amlogic,meson-vpu.yaml
@@ -0,0 +1,137 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+# Copyright 2019 BayLibre, SAS
+%YAML 1.2
+---
+$id: "http://devicetree.org/schemas/display/amlogic,meson-vpu.yaml#"
+$schema: "http://devicetree.org/meta-schemas/core.yaml#"
+
+title: Amlogic Meson Display Controller
+
+maintainers:
+ - Neil Armstrong <narmstrong@baylibre.com>
+
+description: |
+ The Amlogic Meson Display controller is composed of several components
+ that are going to be documented below
+
+ DMC|---------------VPU (Video Processing Unit)----------------|------HHI------|
+ | vd1 _______ _____________ _________________ | |
+ D |-------| |----| | | | | HDMI PLL |
+ D | vd2 | VIU | | Video Post | | Video Encoders |<---|-----VCLK |
+ R |-------| |----| Processing | | | | |
+ | osd2 | | | |---| Enci ----------|----|-----VDAC------|
+ R |-------| CSC |----| Scalers | | Encp ----------|----|----HDMI-TX----|
+ A | osd1 | | | Blenders | | Encl ----------|----|---------------|
+ M |-------|______|----|____________| |________________| | |
+ ___|__________________________________________________________|_______________|
+
+
+ VIU: Video Input Unit
+ ---------------------
+
+ The Video Input Unit is in charge of the pixel scanout from the DDR memory.
+ It fetches the frames addresses, stride and parameters from the "Canvas" memory.
+ This part is also in charge of the CSC (Colorspace Conversion).
+ It can handle 2 OSD Planes and 2 Video Planes.
+
+ VPP: Video Post Processing
+ --------------------------
+
+ The Video Post Processing is in charge of the scaling and blending of the
+ various planes into a single pixel stream.
+ There is a special "pre-blending" used by the video planes with a dedicated
+ scaler and a "post-blending" to merge with the OSD Planes.
+ The OSD planes also have a dedicated scaler for one of the OSD.
+
+ VENC: Video Encoders
+ --------------------
+
+ The VENC is composed of the multiple pixel encoders
+ - ENCI : Interlace Video encoder for CVBS and Interlace HDMI
+ - ENCP : Progressive Video Encoder for HDMI
+ - ENCL : LCD LVDS Encoder
+ The VENC Unit gets a Pixel Clocks (VCLK) from a dedicated HDMI PLL and clock
+ tree and provides the scanout clock to the VPP and VIU.
+ The ENCI is connected to a single VDAC for Composite Output.
+ The ENCI and ENCP are connected to an on-chip HDMI Transceiver.
+
+properties:
+ compatible:
+ oneOf:
+ - items:
+ - enum:
+ - amlogic,meson-gxbb-vpu # GXBB (S905)
+ - amlogic,meson-gxl-vpu # GXL (S905X, S905D)
+ - amlogic,meson-gxm-vpu # GXM (S912)
+ - const: amlogic,meson-gx-vpu
+ - enum:
+ - amlogic,meson-g12a-vpu # G12A (S905X2, S905Y2, S905D2)
+
+ reg:
+ maxItems: 2
+
+ reg-names:
+ items:
+ - const: vpu
+ - const: hhi
+
+ interrupts:
+ maxItems: 1
+
+ power-domains:
+ maxItems: 1
+ description: phandle to the associated power domain
+
+ port@0:
+ type: object
+ description:
+ A port node pointing to the CVBS VDAC port node.
+
+ port@1:
+ type: object
+ description:
+ A port node pointing to the HDMI-TX port node.
+
+ "#address-cells":
+ const: 1
+
+ "#size-cells":
+ const: 0
+
+required:
+ - compatible
+ - reg
+ - interrupts
+ - port@0
+ - port@1
+ - "#address-cells"
+ - "#size-cells"
+
+examples:
+ - |
+ vpu: vpu@d0100000 {
+ compatible = "amlogic,meson-gxbb-vpu", "amlogic,meson-gx-vpu";
+ reg = <0xd0100000 0x100000>, <0xc883c000 0x1000>;
+ reg-names = "vpu", "hhi";
+ interrupts = <3>;
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ /* CVBS VDAC output port */
+ port@0 {
+ reg = <0>;
+
+ cvbs_vdac_out: endpoint {
+ remote-endpoint = <&tv_connector_in>;
+ };
+ };
+
+ /* HDMI TX output port */
+ port@1 {
+ reg = <1>;
+
+ hdmi_tx_out: endpoint {
+ remote-endpoint = <&hdmi_tx_in>;
+ };
+ };
+ };
diff --git a/Documentation/devicetree/bindings/display/arm,pl11x.txt b/Documentation/devicetree/bindings/display/arm,pl11x.txt
index 572fa27..3f977e7 100644
--- a/Documentation/devicetree/bindings/display/arm,pl11x.txt
+++ b/Documentation/devicetree/bindings/display/arm,pl11x.txt
@@ -39,9 +39,11 @@
- port: describes LCD panel signals, following the common binding
for video transmitter interfaces; see
- Documentation/devicetree/bindings/media/video-interfaces.txt;
- when it is a TFT panel, the port's endpoint must define the
- following property:
+ Documentation/devicetree/bindings/media/video-interfaces.txt
+
+Deprecated properties:
+ The port's endbpoint subnode had this, now deprecated property
+ in the past. Drivers should be able to survive without it:
- arm,pl11x,tft-r0g0b0-pads: an array of three 32-bit values,
defining the way CLD pads are wired up; first value
@@ -80,7 +82,6 @@
port {
clcd_pads: endpoint {
remote-endpoint = <&clcd_panel>;
- arm,pl11x,tft-r0g0b0-pads = <0 8 16>;
};
};
diff --git a/Documentation/devicetree/bindings/display/bridge/sii902x.txt b/Documentation/devicetree/bindings/display/bridge/sii902x.txt
index 2df44b7..6e14e08 100644
--- a/Documentation/devicetree/bindings/display/bridge/sii902x.txt
+++ b/Documentation/devicetree/bindings/display/bridge/sii902x.txt
@@ -26,9 +26,8 @@
- clocks: phandle and clock specifier for each clock listed in
the clock-names property
- clock-names: "mclk"
- Describes SII902x MCLK input. MCLK is used to produce
- HDMI audio CTS values. This property is required if
- "#sound-dai-cells"-property is present. This property follows
+ Describes SII902x MCLK input. MCLK can be used to produce
+ HDMI audio CTS values. This property follows
Documentation/devicetree/bindings/clock/clock-bindings.txt
consumer binding.
diff --git a/Documentation/devicetree/bindings/display/connector/hdmi-connector.txt b/Documentation/devicetree/bindings/display/connector/hdmi-connector.txt
index 508aee4..aeb07c4 100644
--- a/Documentation/devicetree/bindings/display/connector/hdmi-connector.txt
+++ b/Documentation/devicetree/bindings/display/connector/hdmi-connector.txt
@@ -9,6 +9,7 @@
- label: a symbolic name for the connector
- hpd-gpios: HPD GPIO number
- ddc-i2c-bus: phandle link to the I2C controller used for DDC EDID probing
+- ddc-en-gpios: signal to enable DDC bus
Required nodes:
- Video port for HDMI input
diff --git a/Documentation/devicetree/bindings/display/panel/ampire,am-480272h3tmqw-t01h.txt b/Documentation/devicetree/bindings/display/panel/ampire,am-480272h3tmqw-t01h.txt
deleted file mode 100644
index 6812280..0000000
--- a/Documentation/devicetree/bindings/display/panel/ampire,am-480272h3tmqw-t01h.txt
+++ /dev/null
@@ -1,26 +0,0 @@
-Ampire AM-480272H3TMQW-T01H 4.3" WQVGA TFT LCD panel
-
-This binding is compatible with the simple-panel binding, which is specified
-in simple-panel.txt in this directory.
-
-Required properties:
-- compatible: should be "ampire,am-480272h3tmqw-t01h"
-
-Optional properties:
-- power-supply: regulator to provide the supply voltage
-- enable-gpios: GPIO pin to enable or disable the panel
-- backlight: phandle of the backlight device attached to the panel
-
-Optional nodes:
-- Video port for RGB input.
-
-Example:
- panel_rgb: panel-rgb {
- compatible = "ampire,am-480272h3tmqw-t01h";
- enable-gpios = <&gpioa 8 1>;
- port {
- panel_in_rgb: endpoint {
- remote-endpoint = <&controller_out_rgb>;
- };
- };
- };
diff --git a/Documentation/devicetree/bindings/display/panel/ampire,am-480272h3tmqw-t01h.yaml b/Documentation/devicetree/bindings/display/panel/ampire,am-480272h3tmqw-t01h.yaml
new file mode 100644
index 0000000..c6e33e7
--- /dev/null
+++ b/Documentation/devicetree/bindings/display/panel/ampire,am-480272h3tmqw-t01h.yaml
@@ -0,0 +1,42 @@
+# SPDX-License-Identifier: GPL-2.0
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/display/panel/ampire,am-480272h3tmqw-t01h.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Ampire AM-480272H3TMQW-T01H 4.3" WQVGA TFT LCD panel
+
+maintainers:
+ - Yannick Fertre <yannick.fertre@st.com>
+ - Thierry Reding <treding@nvidia.com>
+
+allOf:
+ - $ref: panel-common.yaml#
+
+properties:
+ compatible:
+ const: ampire,am-480272h3tmqw-t01h
+
+ power-supply: true
+ enable-gpios: true
+ backlight: true
+ port: true
+
+required:
+ - compatible
+
+additionalProperties: false
+
+examples:
+ - |
+ panel_rgb: panel {
+ compatible = "ampire,am-480272h3tmqw-t01h";
+ enable-gpios = <&gpioa 8 1>;
+ port {
+ panel_in_rgb: endpoint {
+ remote-endpoint = <&controller_out_rgb>;
+ };
+ };
+ };
+
+...
diff --git a/Documentation/devicetree/bindings/display/panel/arm,versatile-tft-panel.txt b/Documentation/devicetree/bindings/display/panel/arm,versatile-tft-panel.txt
index 248141c..0601a9e 100644
--- a/Documentation/devicetree/bindings/display/panel/arm,versatile-tft-panel.txt
+++ b/Documentation/devicetree/bindings/display/panel/arm,versatile-tft-panel.txt
@@ -10,7 +10,7 @@
- compatible: should be "arm,versatile-tft-panel"
Required subnodes:
-- port: see display/panel/panel-common.txt, graph.txt
+- port: see display/panel/panel-common.yaml, graph.txt
Example:
diff --git a/Documentation/devicetree/bindings/display/panel/armadeus,st0700-adapt.txt b/Documentation/devicetree/bindings/display/panel/armadeus,st0700-adapt.txt
deleted file mode 100644
index a30d63d..0000000
--- a/Documentation/devicetree/bindings/display/panel/armadeus,st0700-adapt.txt
+++ /dev/null
@@ -1,9 +0,0 @@
-Armadeus ST0700 Adapt. A Santek ST0700I5Y-RBSLW 7.0" WVGA (800x480) TFT with
-an adapter board.
-
-Required properties:
-- compatible: "armadeus,st0700-adapt"
-- power-supply: see panel-common.txt
-
-Optional properties:
-- backlight: see panel-common.txt
diff --git a/Documentation/devicetree/bindings/display/panel/armadeus,st0700-adapt.yaml b/Documentation/devicetree/bindings/display/panel/armadeus,st0700-adapt.yaml
new file mode 100644
index 0000000..a6ade47
--- /dev/null
+++ b/Documentation/devicetree/bindings/display/panel/armadeus,st0700-adapt.yaml
@@ -0,0 +1,33 @@
+# SPDX-License-Identifier: GPL-2.0
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/display/panel/armadeus,st0700-adapt.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Armadeus ST0700 Adapter
+
+description:
+ A Santek ST0700I5Y-RBSLW 7.0" WVGA (800x480) TFT with an adapter board.
+
+maintainers:
+ - '"Sébastien Szymanski" <sebastien.szymanski@armadeus.com>'
+ - Thierry Reding <thierry.reding@gmail.com>
+
+allOf:
+ - $ref: panel-common.yaml#
+
+properties:
+ compatible:
+ const: armadeus,st0700-adapt
+
+ power-supply: true
+ backlight: true
+ port: true
+
+additionalProperties: false
+
+required:
+ - compatible
+ - power-supply
+
+...
diff --git a/Documentation/devicetree/bindings/display/panel/bananapi,s070wv20-ct16.txt b/Documentation/devicetree/bindings/display/panel/bananapi,s070wv20-ct16.txt
deleted file mode 100644
index 35bc0c8..0000000
--- a/Documentation/devicetree/bindings/display/panel/bananapi,s070wv20-ct16.txt
+++ /dev/null
@@ -1,12 +0,0 @@
-Banana Pi 7" (S070WV20-CT16) TFT LCD Panel
-
-Required properties:
-- compatible: should be "bananapi,s070wv20-ct16"
-- power-supply: see ./panel-common.txt
-
-Optional properties:
-- enable-gpios: see ./simple-panel.txt
-- backlight: see ./simple-panel.txt
-
-This binding is compatible with the simple-panel binding, which is specified
-in ./simple-panel.txt.
diff --git a/Documentation/devicetree/bindings/display/panel/bananapi,s070wv20-ct16.yaml b/Documentation/devicetree/bindings/display/panel/bananapi,s070wv20-ct16.yaml
new file mode 100644
index 0000000..bbf127f
--- /dev/null
+++ b/Documentation/devicetree/bindings/display/panel/bananapi,s070wv20-ct16.yaml
@@ -0,0 +1,31 @@
+# SPDX-License-Identifier: GPL-2.0
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/display/panel/bananapi,s070wv20-ct16.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Banana Pi 7" (S070WV20-CT16) TFT LCD Panel
+
+maintainers:
+ - Chen-Yu Tsai <wens@csie.org>
+ - Thierry Reding <thierry.reding@gmail.com>
+
+allOf:
+ - $ref: panel-common.yaml#
+
+properties:
+ compatible:
+ const: bananapi,s070wv20-ct16
+
+ power-supply: true
+ backlight: true
+ enable-gpios: true
+ port: true
+
+additionalProperties: false
+
+required:
+ - compatible
+ - power-supply
+
+...
diff --git a/Documentation/devicetree/bindings/display/panel/boe,himax8279d.txt b/Documentation/devicetree/bindings/display/panel/boe,himax8279d.txt
new file mode 100644
index 0000000..3caea21
--- /dev/null
+++ b/Documentation/devicetree/bindings/display/panel/boe,himax8279d.txt
@@ -0,0 +1,24 @@
+Boe Himax8279d 1200x1920 TFT LCD panel
+
+Required properties:
+- compatible: should be "boe,himax8279d8p" and one of: "boe,himax8279d10p"
+- reg: DSI virtual channel of the peripheral
+- enable-gpios: panel enable gpio
+- pp33-gpios: a GPIO phandle for the 3.3v pin that provides the supply voltage
+- pp18-gpios: a GPIO phandle for the 1.8v pin that provides the supply voltage
+
+Optional properties:
+- backlight: phandle of the backlight device attached to the panel
+
+Example:
+
+ &mipi_dsi {
+ panel {
+ compatible = "boe,himax8279d8p", "boe,himax8279d10p";
+ reg = <0>;
+ backlight = <&backlight>;
+ enable-gpios = <&gpio 45 GPIO_ACTIVE_HIGH>;
+ pp33-gpios = <&gpio 35 GPIO_ACTIVE_HIGH>;
+ pp18-gpios = <&gpio 36 GPIO_ACTIVE_HIGH>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/display/panel/dlc,dlc0700yzg-1.txt b/Documentation/devicetree/bindings/display/panel/dlc,dlc0700yzg-1.txt
deleted file mode 100644
index bf06bb0..0000000
--- a/Documentation/devicetree/bindings/display/panel/dlc,dlc0700yzg-1.txt
+++ /dev/null
@@ -1,13 +0,0 @@
-DLC Display Co. DLC0700YZG-1 7.0" WSVGA TFT LCD panel
-
-Required properties:
-- compatible: should be "dlc,dlc0700yzg-1"
-- power-supply: See simple-panel.txt
-
-Optional properties:
-- reset-gpios: See panel-common.txt
-- enable-gpios: See simple-panel.txt
-- backlight: See simple-panel.txt
-
-This binding is compatible with the simple-panel binding, which is specified
-in simple-panel.txt in this directory.
diff --git a/Documentation/devicetree/bindings/display/panel/dlc,dlc0700yzg-1.yaml b/Documentation/devicetree/bindings/display/panel/dlc,dlc0700yzg-1.yaml
new file mode 100644
index 0000000..287e2fe
--- /dev/null
+++ b/Documentation/devicetree/bindings/display/panel/dlc,dlc0700yzg-1.yaml
@@ -0,0 +1,31 @@
+# SPDX-License-Identifier: GPL-2.0
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/display/panel/dlc,dlc0700yzg-1.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: DLC Display Co. DLC0700YZG-1 7.0" WSVGA TFT LCD panel
+
+maintainers:
+ - Philipp Zabel <p.zabel@pengutronix.de>
+ - Thierry Reding <thierry.reding@gmail.com>
+
+allOf:
+ - $ref: panel-common.yaml#
+
+properties:
+ compatible:
+ const: dlc,dlc0700yzg-1
+
+ reset-gpios: true
+ enable-gpios: true
+ backlight: true
+ port: true
+
+additionalProperties: false
+
+required:
+ - compatible
+ - power-supply
+
+...
diff --git a/Documentation/devicetree/bindings/display/panel/edt,et-series.txt b/Documentation/devicetree/bindings/display/panel/edt,et-series.txt
index be86843..b7ac1c7 100644
--- a/Documentation/devicetree/bindings/display/panel/edt,et-series.txt
+++ b/Documentation/devicetree/bindings/display/panel/edt,et-series.txt
@@ -40,7 +40,7 @@
| Identifier | compatbile | description |
+=================+=====================+=====================================+
| ETM0700G0DH6 | edt,etm070080dh6 | WVGA TFT Display with capacitive |
-| | | Touchscreen |
+| | edt,etm0700g0dh6 | Touchscreen |
+-----------------+---------------------+-------------------------------------+
| ETM0700G0BDH6 | edt,etm070080bdh6 | Same as ETM0700G0DH6 but with |
| | | inverted pixel clock. |
diff --git a/Documentation/devicetree/bindings/display/panel/giantplus,gpm940b0.txt b/Documentation/devicetree/bindings/display/panel/giantplus,gpm940b0.txt
new file mode 100644
index 0000000..3dab52f
--- /dev/null
+++ b/Documentation/devicetree/bindings/display/panel/giantplus,gpm940b0.txt
@@ -0,0 +1,12 @@
+GiantPlus 3.0" (320x240 pixels) 24-bit TFT LCD panel
+
+Required properties:
+- compatible: should be "giantplus,gpm940b0"
+- power-supply: as specified in the base binding
+
+Optional properties:
+- backlight: as specified in the base binding
+- enable-gpios: as specified in the base binding
+
+This binding is compatible with the simple-panel binding, which is specified
+in simple-panel.txt in this directory.
diff --git a/Documentation/devicetree/bindings/display/panel/innolux,ee101ia-01d.txt b/Documentation/devicetree/bindings/display/panel/innolux,ee101ia-01d.txt
deleted file mode 100644
index e5ca4cc..0000000
--- a/Documentation/devicetree/bindings/display/panel/innolux,ee101ia-01d.txt
+++ /dev/null
@@ -1,7 +0,0 @@
-Innolux Corporation 10.1" EE101IA-01D WXGA (1280x800) LVDS panel
-
-Required properties:
-- compatible: should be "innolux,ee101ia-01d"
-
-This binding is compatible with the lvds-panel binding, which is specified
-in panel-lvds.txt in this directory.
diff --git a/Documentation/devicetree/bindings/display/panel/innolux,ee101ia-01d.yaml b/Documentation/devicetree/bindings/display/panel/innolux,ee101ia-01d.yaml
new file mode 100644
index 0000000..a69681e
--- /dev/null
+++ b/Documentation/devicetree/bindings/display/panel/innolux,ee101ia-01d.yaml
@@ -0,0 +1,31 @@
+# SPDX-License-Identifier: GPL-2.0
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/display/panel/innolux,ee101ia-01d.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Innolux Corporation 10.1" EE101IA-01D WXGA (1280x800) LVDS panel
+
+maintainers:
+ - Heiko Stuebner <heiko.stuebner@bq.com>
+ - Thierry Reding <thierry.reding@gmail.com>
+
+allOf:
+ - $ref: lvds.yaml#
+
+properties:
+ compatible:
+ items:
+ - const: innolux,ee101ia-01d
+ - {} # panel-lvds, but not listed here to avoid false select
+
+ backlight: true
+ enable-gpios: true
+ power-supply: true
+ width-mm: true
+ height-mm: true
+ panel-timing: true
+ port: true
+
+additionalProperties: false
+...
diff --git a/Documentation/devicetree/bindings/display/panel/kingdisplay,kd035g6-54nt.txt b/Documentation/devicetree/bindings/display/panel/kingdisplay,kd035g6-54nt.txt
new file mode 100644
index 0000000..fa95960
--- /dev/null
+++ b/Documentation/devicetree/bindings/display/panel/kingdisplay,kd035g6-54nt.txt
@@ -0,0 +1,42 @@
+King Display KD035G6-54NT 3.5" (320x240 pixels) 24-bit TFT LCD panel
+
+Required properties:
+- compatible: should be "kingdisplay,kd035g6-54nt"
+- power-supply: See panel-common.txt
+- reset-gpios: See panel-common.txt
+
+Optional properties:
+- backlight: see panel-common.txt
+
+The generic bindings for the SPI slaves documented in [1] also apply.
+
+The device node can contain one 'port' child node with one child
+'endpoint' node, according to the bindings defined in [2]. This
+node should describe panel's video bus.
+
+[1]: Documentation/devicetree/bindings/spi/spi-bus.txt
+[2]: Documentation/devicetree/bindings/graph.txt
+
+Example:
+
+&spi {
+ panel@0 {
+ compatible = "kingdisplay,kd035g6-54nt";
+ reg = <0>;
+
+ spi-max-frequency = <3125000>;
+ spi-3wire;
+ spi-cs-high;
+
+ reset-gpios = <&gpe 2 GPIO_ACTIVE_LOW>;
+
+ backlight = <&backlight>;
+ power-supply = <&ldo6>;
+
+ port {
+ panel_input: endpoint {
+ remote-endpoint = <&panel_output>;
+ };
+ };
+ };
+};
diff --git a/Documentation/devicetree/bindings/display/panel/lvds.yaml b/Documentation/devicetree/bindings/display/panel/lvds.yaml
new file mode 100644
index 0000000..d008330
--- /dev/null
+++ b/Documentation/devicetree/bindings/display/panel/lvds.yaml
@@ -0,0 +1,107 @@
+# SPDX-License-Identifier: GPL-2.0
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/display/panel/lvds.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: LVDS Display Panel
+
+maintainers:
+ - Laurent Pinchart <laurent.pinchart+renesas@ideasonboard.com>
+ - Thierry Reding <thierry.reding@gmail.com>
+
+description: |+
+ LVDS is a physical layer specification defined in ANSI/TIA/EIA-644-A. Multiple
+ incompatible data link layers have been used over time to transmit image data
+ to LVDS panels. This bindings supports display panels compatible with the
+ following specifications.
+
+ [JEIDA] "Digital Interface Standards for Monitor", JEIDA-59-1999, February
+ 1999 (Version 1.0), Japan Electronic Industry Development Association (JEIDA)
+ [LDI] "Open LVDS Display Interface", May 1999 (Version 0.95), National
+ Semiconductor
+ [VESA] "VESA Notebook Panel Standard", October 2007 (Version 1.0), Video
+ Electronics Standards Association (VESA)
+
+ Device compatible with those specifications have been marketed under the
+ FPD-Link and FlatLink brands.
+
+allOf:
+ - $ref: panel-common.yaml#
+
+properties:
+ compatible:
+ contains:
+ const: panel-lvds
+ description:
+ Shall contain "panel-lvds" in addition to a mandatory panel-specific
+ compatible string defined in individual panel bindings. The "panel-lvds"
+ value shall never be used on its own.
+
+ data-mapping:
+ enum:
+ - jeida-18
+ - jeida-24
+ - vesa-24
+ description: |
+ The color signals mapping order.
+
+ LVDS data mappings are defined as follows.
+
+ - "jeida-18" - 18-bit data mapping compatible with the [JEIDA], [LDI] and
+ [VESA] specifications. Data are transferred as follows on 3 LVDS lanes.
+
+ Slot 0 1 2 3 4 5 6
+ ________________ _________________
+ Clock \_______________________/
+ ______ ______ ______ ______ ______ ______ ______
+ DATA0 ><__G0__><__R5__><__R4__><__R3__><__R2__><__R1__><__R0__><
+ DATA1 ><__B1__><__B0__><__G5__><__G4__><__G3__><__G2__><__G1__><
+ DATA2 ><_CTL2_><_CTL1_><_CTL0_><__B5__><__B4__><__B3__><__B2__><
+
+ - "jeida-24" - 24-bit data mapping compatible with the [DSIM] and [LDI]
+ specifications. Data are transferred as follows on 4 LVDS lanes.
+
+ Slot 0 1 2 3 4 5 6
+ ________________ _________________
+ Clock \_______________________/
+ ______ ______ ______ ______ ______ ______ ______
+ DATA0 ><__G2__><__R7__><__R6__><__R5__><__R4__><__R3__><__R2__><
+ DATA1 ><__B3__><__B2__><__G7__><__G6__><__G5__><__G4__><__G3__><
+ DATA2 ><_CTL2_><_CTL1_><_CTL0_><__B7__><__B6__><__B5__><__B4__><
+ DATA3 ><_CTL3_><__B1__><__B0__><__G1__><__G0__><__R1__><__R0__><
+
+ - "vesa-24" - 24-bit data mapping compatible with the [VESA] specification.
+ Data are transferred as follows on 4 LVDS lanes.
+
+ Slot 0 1 2 3 4 5 6
+ ________________ _________________
+ Clock \_______________________/
+ ______ ______ ______ ______ ______ ______ ______
+ DATA0 ><__G0__><__R5__><__R4__><__R3__><__R2__><__R1__><__R0__><
+ DATA1 ><__B1__><__B0__><__G5__><__G4__><__G3__><__G2__><__G1__><
+ DATA2 ><_CTL2_><_CTL1_><_CTL0_><__B5__><__B4__><__B3__><__B2__><
+ DATA3 ><_CTL3_><__B7__><__B6__><__G7__><__G6__><__R7__><__R6__><
+
+ Control signals are mapped as follows.
+
+ CTL0: HSync
+ CTL1: VSync
+ CTL2: Data Enable
+ CTL3: 0
+
+ data-mirror:
+ type: boolean
+ description:
+ If set, reverse the bit order described in the data mappings below on all
+ data lanes, transmitting bits for slots 6 to 0 instead of 0 to 6.
+
+required:
+ - compatible
+ - data-mapping
+ - width-mm
+ - height-mm
+ - panel-timing
+ - port
+
+...
diff --git a/Documentation/devicetree/bindings/display/panel/mitsubishi,aa104xd12.txt b/Documentation/devicetree/bindings/display/panel/mitsubishi,aa104xd12.txt
deleted file mode 100644
index ced0121..0000000
--- a/Documentation/devicetree/bindings/display/panel/mitsubishi,aa104xd12.txt
+++ /dev/null
@@ -1,47 +0,0 @@
-Mitsubishi AA204XD12 LVDS Display Panel
-=======================================
-
-The AA104XD12 is a 10.4" XGA TFT-LCD display panel.
-
-These DT bindings follow the LVDS panel bindings defined in panel-lvds.txt
-with the following device-specific properties.
-
-
-Required properties:
-
-- compatible: Shall contain "mitsubishi,aa121td01" and "panel-lvds", in that
- order.
-- vcc-supply: Reference to the regulator powering the panel VCC pins.
-
-
-Example
--------
-
-panel {
- compatible = "mitsubishi,aa104xd12", "panel-lvds";
- vcc-supply = <&vcc_3v3>;
-
- width-mm = <210>;
- height-mm = <158>;
-
- data-mapping = "jeida-24";
-
- panel-timing {
- /* 1024x768 @65Hz */
- clock-frequency = <65000000>;
- hactive = <1024>;
- vactive = <768>;
- hsync-len = <136>;
- hfront-porch = <20>;
- hback-porch = <160>;
- vfront-porch = <3>;
- vback-porch = <29>;
- vsync-len = <6>;
- };
-
- port {
- panel_in: endpoint {
- remote-endpoint = <&lvds_encoder>;
- };
- };
-};
diff --git a/Documentation/devicetree/bindings/display/panel/mitsubishi,aa104xd12.yaml b/Documentation/devicetree/bindings/display/panel/mitsubishi,aa104xd12.yaml
new file mode 100644
index 0000000..b5e7ee2
--- /dev/null
+++ b/Documentation/devicetree/bindings/display/panel/mitsubishi,aa104xd12.yaml
@@ -0,0 +1,75 @@
+# SPDX-License-Identifier: GPL-2.0
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/display/panel/mitsubishi,aa104xd12.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Mitsubishi AA104XD12 10.4" XGA LVDS Display Panel
+
+maintainers:
+ - Laurent Pinchart <laurent.pinchart@ideasonboard.com>
+ - Thierry Reding <thierry.reding@gmail.com>
+
+allOf:
+ - $ref: lvds.yaml#
+
+properties:
+ compatible:
+ items:
+ - const: mitsubishi,aa104xd12
+ - {} # panel-lvds, but not listed here to avoid false select
+
+ vcc-supply:
+ description: Reference to the regulator powering the panel VCC pins.
+
+ data-mapping:
+ const: jeida-24
+
+ width-mm:
+ const: 210
+
+ height-mm:
+ const: 158
+
+ panel-timing: true
+ port: true
+
+additionalProperties: false
+
+required:
+ - compatible
+ - vcc-supply
+
+examples:
+ - |+
+
+ panel {
+ compatible = "mitsubishi,aa104xd12", "panel-lvds";
+ vcc-supply = <&vcc_3v3>;
+
+ width-mm = <210>;
+ height-mm = <158>;
+
+ data-mapping = "jeida-24";
+
+ panel-timing {
+ /* 1024x768 @65Hz */
+ clock-frequency = <65000000>;
+ hactive = <1024>;
+ vactive = <768>;
+ hsync-len = <136>;
+ hfront-porch = <20>;
+ hback-porch = <160>;
+ vfront-porch = <3>;
+ vback-porch = <29>;
+ vsync-len = <6>;
+ };
+
+ port {
+ panel_in: endpoint {
+ remote-endpoint = <&lvds_encoder>;
+ };
+ };
+ };
+
+...
diff --git a/Documentation/devicetree/bindings/display/panel/mitsubishi,aa121td01.txt b/Documentation/devicetree/bindings/display/panel/mitsubishi,aa121td01.txt
deleted file mode 100644
index d6e1097..0000000
--- a/Documentation/devicetree/bindings/display/panel/mitsubishi,aa121td01.txt
+++ /dev/null
@@ -1,47 +0,0 @@
-Mitsubishi AA121TD01 LVDS Display Panel
-=======================================
-
-The AA121TD01 is a 12.1" WXGA TFT-LCD display panel.
-
-These DT bindings follow the LVDS panel bindings defined in panel-lvds.txt
-with the following device-specific properties.
-
-
-Required properties:
-
-- compatible: Shall contain "mitsubishi,aa121td01" and "panel-lvds", in that
- order.
-- vcc-supply: Reference to the regulator powering the panel VCC pins.
-
-
-Example
--------
-
-panel {
- compatible = "mitsubishi,aa121td01", "panel-lvds";
- vcc-supply = <&vcc_3v3>;
-
- width-mm = <261>;
- height-mm = <163>;
-
- data-mapping = "jeida-24";
-
- panel-timing {
- /* 1280x800 @60Hz */
- clock-frequency = <71000000>;
- hactive = <1280>;
- vactive = <800>;
- hsync-len = <70>;
- hfront-porch = <20>;
- hback-porch = <70>;
- vsync-len = <5>;
- vfront-porch = <3>;
- vback-porch = <15>;
- };
-
- port {
- panel_in: endpoint {
- remote-endpoint = <&lvds_encoder>;
- };
- };
-};
diff --git a/Documentation/devicetree/bindings/display/panel/mitsubishi,aa121td01.yaml b/Documentation/devicetree/bindings/display/panel/mitsubishi,aa121td01.yaml
new file mode 100644
index 0000000..977c50a
--- /dev/null
+++ b/Documentation/devicetree/bindings/display/panel/mitsubishi,aa121td01.yaml
@@ -0,0 +1,74 @@
+# SPDX-License-Identifier: GPL-2.0
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/display/panel/mitsubishi,aa121td01.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Mitsubishi AA121TD01 12.1" WXGA LVDS Display Panel
+
+maintainers:
+ - Laurent Pinchart <laurent.pinchart@ideasonboard.com>
+ - Thierry Reding <thierry.reding@gmail.com>
+
+allOf:
+ - $ref: lvds.yaml#
+
+properties:
+ compatible:
+ items:
+ - const: mitsubishi,aa121td01
+ - {} # panel-lvds, but not listed here to avoid false select
+
+ vcc-supply:
+ description: Reference to the regulator powering the panel VCC pins.
+
+ data-mapping:
+ const: jeida-24
+
+ width-mm:
+ const: 261
+
+ height-mm:
+ const: 163
+
+ panel-timing: true
+ port: true
+
+additionalProperties: false
+
+required:
+ - compatible
+ - vcc-supply
+
+examples:
+ - |+
+ panel {
+ compatible = "mitsubishi,aa121td01", "panel-lvds";
+ vcc-supply = <&vcc_3v3>;
+
+ width-mm = <261>;
+ height-mm = <163>;
+
+ data-mapping = "jeida-24";
+
+ panel-timing {
+ /* 1280x800 @60Hz */
+ clock-frequency = <71000000>;
+ hactive = <1280>;
+ vactive = <800>;
+ hsync-len = <70>;
+ hfront-porch = <20>;
+ hback-porch = <70>;
+ vsync-len = <5>;
+ vfront-porch = <3>;
+ vback-porch = <15>;
+ };
+
+ port {
+ panel_in: endpoint {
+ remote-endpoint = <&lvds_encoder>;
+ };
+ };
+ };
+
+...
diff --git a/Documentation/devicetree/bindings/display/panel/nec,nl8048hl11.yaml b/Documentation/devicetree/bindings/display/panel/nec,nl8048hl11.yaml
new file mode 100644
index 0000000..aa788ea
--- /dev/null
+++ b/Documentation/devicetree/bindings/display/panel/nec,nl8048hl11.yaml
@@ -0,0 +1,62 @@
+# SPDX-License-Identifier: GPL-2.0
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/display/panel/nec,nl8048hl11.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: NEC NL8048HL11 4.1" WVGA TFT LCD panel
+
+description:
+ The NEC NL8048HL11 is a 4.1" WVGA TFT LCD panel with a 24-bit RGB parallel
+ data interface and an SPI control interface.
+
+maintainers:
+ - Laurent Pinchart <laurent.pinchart@ideasonboard.com>
+
+allOf:
+ - $ref: panel-common.yaml#
+
+properties:
+ compatible:
+ const: nec,nl8048hl11
+
+ label: true
+ port: true
+ reg: true
+ reset-gpios: true
+
+ spi-max-frequency:
+ maximum: 10000000
+
+required:
+ - compatible
+ - reg
+ - reset-gpios
+ - port
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/gpio/gpio.h>
+
+ spi0 {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ lcd_panel: panel@0 {
+ compatible = "nec,nl8048hl11";
+ reg = <0>;
+ spi-max-frequency = <10000000>;
+
+ reset-gpios = <&gpio7 7 GPIO_ACTIVE_LOW>;
+
+ port {
+ lcd_in: endpoint {
+ remote-endpoint = <&dpi_out>;
+ };
+ };
+ };
+ };
+
+...
diff --git a/Documentation/devicetree/bindings/display/panel/ortustech,com37h3m05dtc.txt b/Documentation/devicetree/bindings/display/panel/ortustech,com37h3m05dtc.txt
new file mode 100644
index 0000000..c16907c
--- /dev/null
+++ b/Documentation/devicetree/bindings/display/panel/ortustech,com37h3m05dtc.txt
@@ -0,0 +1,12 @@
+OrtusTech COM37H3M05DTC Blanview 3.7" VGA portrait TFT-LCD panel
+
+Required properties:
+- compatible: should be "ortustech,com37h3m05dtc"
+
+Optional properties:
+- enable-gpios: GPIO pin to enable or disable the panel
+- backlight: phandle of the backlight device attached to the panel
+- power-supply: phandle of the regulator that provides the supply voltage
+
+This binding is compatible with the simple-panel binding, which is specified
+in simple-panel.txt in this directory.
diff --git a/Documentation/devicetree/bindings/display/panel/ortustech,com37h3m99dtc.txt b/Documentation/devicetree/bindings/display/panel/ortustech,com37h3m99dtc.txt
new file mode 100644
index 0000000..06a73c3
--- /dev/null
+++ b/Documentation/devicetree/bindings/display/panel/ortustech,com37h3m99dtc.txt
@@ -0,0 +1,12 @@
+OrtusTech COM37H3M99DTC Blanview 3.7" VGA portrait TFT-LCD panel
+
+Required properties:
+- compatible: should be "ortustech,com37h3m99dtc"
+
+Optional properties:
+- enable-gpios: GPIO pin to enable or disable the panel
+- backlight: phandle of the backlight device attached to the panel
+- power-supply: phandle of the regulator that provides the supply voltage
+
+This binding is compatible with the simple-panel binding, which is specified
+in simple-panel.txt in this directory.
diff --git a/Documentation/devicetree/bindings/display/panel/panel-common.txt b/Documentation/devicetree/bindings/display/panel/panel-common.txt
deleted file mode 100644
index 5d2519a..0000000
--- a/Documentation/devicetree/bindings/display/panel/panel-common.txt
+++ /dev/null
@@ -1,101 +0,0 @@
-Common Properties for Display Panel
-===================================
-
-This document defines device tree properties common to several classes of
-display panels. It doesn't constitue a device tree binding specification by
-itself but is meant to be referenced by device tree bindings.
-
-When referenced from panel device tree bindings the properties defined in this
-document are defined as follows. The panel device tree bindings are
-responsible for defining whether each property is required or optional.
-
-
-Descriptive Properties
-----------------------
-
-- width-mm,
-- height-mm: The width-mm and height-mm specify the width and height of the
- physical area where images are displayed. These properties are expressed in
- millimeters and rounded to the closest unit.
-
-- label: The label property specifies a symbolic name for the panel as a
- string suitable for use by humans. It typically contains a name inscribed on
- the system (e.g. as an affixed label) or specified in the system's
- documentation (e.g. in the user's manual).
-
- If no such name exists, and unless the property is mandatory according to
- device tree bindings, it shall rather be omitted than constructed of
- non-descriptive information. For instance an LCD panel in a system that
- contains a single panel shall not be labelled "LCD" if that name is not
- inscribed on the system or used in a descriptive fashion in system
- documentation.
-
-
-Display Timings
----------------
-
-- panel-timing: Most display panels are restricted to a single resolution and
- require specific display timings. The panel-timing subnode expresses those
- timings as specified in the timing subnode section of the display timing
- bindings defined in
- Documentation/devicetree/bindings/display/panel/display-timing.txt.
-
-
-Connectivity
-------------
-
-- ports: Panels receive video data through one or multiple connections. While
- the nature of those connections is specific to the panel type, the
- connectivity is expressed in a standard fashion using ports as specified in
- the device graph bindings defined in
- Documentation/devicetree/bindings/graph.txt.
-
-- ddc-i2c-bus: Some panels expose EDID information through an I2C-compatible
- bus such as DDC2 or E-DDC. For such panels the ddc-i2c-bus contains a
- phandle to the system I2C controller connected to that bus.
-
-
-Control I/Os
-------------
-
-Many display panels can be controlled through pins driven by GPIOs. The nature
-and timing of those control signals are device-specific and left for panel
-device tree bindings to specify. The following GPIO specifiers can however be
-used for panels that implement compatible control signals.
-
-- enable-gpios: Specifier for a GPIO connected to the panel enable control
- signal. The enable signal is active high and enables operation of the panel.
- This property can also be used for panels implementing an active low power
- down signal, which is a negated version of the enable signal. Active low
- enable signals (or active high power down signals) can be supported by
- inverting the GPIO specifier polarity flag.
-
- Note that the enable signal control panel operation only and must not be
- confused with a backlight enable signal.
-
-- reset-gpios: Specifier for a GPIO coonnected to the panel reset control
- signal. The reset signal is active low and resets the panel internal logic
- while active. Active high reset signals can be supported by inverting the
- GPIO specifier polarity flag.
-
-Power
------
-
-- power-supply: display panels require power to be supplied. While several
- panels need more than one power supply with panel-specific constraints
- governing the order and timings of the power supplies, in many cases a single
- power supply is sufficient, either because the panel has a single power rail,
- or because all its power rails can be driven by the same supply. In that case
- the power-supply property specifies the supply powering the panel as a phandle
- to a regulator.
-
-Backlight
----------
-
-Most display panels include a backlight. Some of them also include a backlight
-controller exposed through a control bus such as I2C or DSI. Others expose
-backlight control through GPIO, PWM or other signals connected to an external
-backlight controller.
-
-- backlight: For panels whose backlight is controlled by an external backlight
- controller, this property contains a phandle that references the controller.
diff --git a/Documentation/devicetree/bindings/display/panel/panel-common.yaml b/Documentation/devicetree/bindings/display/panel/panel-common.yaml
new file mode 100644
index 0000000..ef8d8cd
--- /dev/null
+++ b/Documentation/devicetree/bindings/display/panel/panel-common.yaml
@@ -0,0 +1,149 @@
+# SPDX-License-Identifier: GPL-2.0
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/display/panel/panel-common.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Common Properties for Display Panels
+
+maintainers:
+ - Thierry Reding <thierry.reding@gmail.com>
+ - Laurent Pinchart <laurent.pinchart+renesas@ideasonboard.com>
+
+description: |
+ This document defines device tree properties common to several classes of
+ display panels. It doesn't constitue a device tree binding specification by
+ itself but is meant to be referenced by device tree bindings.
+
+ When referenced from panel device tree bindings the properties defined in this
+ document are defined as follows. The panel device tree bindings are
+ responsible for defining whether each property is required or optional.
+
+properties:
+ # Descriptive Properties
+ width-mm:
+ description:
+ Specifies the width of the physical area where images are displayed. This
+ property is expressed in millimeters and rounded to the closest unit.
+
+ height-mm:
+ description:
+ Specifies the height of the physical area where images are displayed. This
+ property is expressed in millimeters and rounded to the closest unit.
+
+ label:
+ description: |
+ The label property specifies a symbolic name for the panel as a
+ string suitable for use by humans. It typically contains a name inscribed
+ on the system (e.g. as an affixed label) or specified in the system's
+ documentation (e.g. in the user's manual).
+
+ If no such name exists, and unless the property is mandatory according to
+ device tree bindings, it shall rather be omitted than constructed of
+ non-descriptive information. For instance an LCD panel in a system that
+ contains a single panel shall not be labelled "LCD" if that name is not
+ inscribed on the system or used in a descriptive fashion in system
+ documentation.
+
+ rotation:
+ description:
+ Display rotation in degrees counter clockwise (0,90,180,270)
+ allOf:
+ - $ref: /schemas/types.yaml#/definitions/uint32
+ - enum: [ 0, 90, 180, 270 ]
+
+ # Display Timings
+ panel-timing:
+ type: object
+ description:
+ Most display panels are restricted to a single resolution and
+ require specific display timings. The panel-timing subnode expresses those
+ timings as specified in the timing subnode section of the display timing
+ bindings defined in
+ Documentation/devicetree/bindings/display/panel/display-timing.txt.
+
+ # Connectivity
+ port:
+ type: object
+
+ ports:
+ type: object
+ description:
+ Panels receive video data through one or multiple connections. While
+ the nature of those connections is specific to the panel type, the
+ connectivity is expressed in a standard fashion using ports as specified
+ in the device graph bindings defined in
+ Documentation/devicetree/bindings/graph.txt.
+
+ ddc-i2c-bus:
+ $ref: /schemas/types.yaml#/definitions/phandle
+ description:
+ Some panels expose EDID information through an I2C-compatible
+ bus such as DDC2 or E-DDC. For such panels the ddc-i2c-bus contains a
+ phandle to the system I2C controller connected to that bus.
+
+ no-hpd:
+ type: boolean
+ description:
+ This panel is supposed to communicate that it's ready via HPD
+ (hot plug detect) signal, but the signal isn't hooked up so we should
+ hardcode the max delay from the panel spec when powering up the panel.
+
+ # Control I/Os
+
+ # Many display panels can be controlled through pins driven by GPIOs. The nature
+ # and timing of those control signals are device-specific and left for panel
+ # device tree bindings to specify. The following GPIO specifiers can however be
+ # used for panels that implement compatible control signals.
+
+ enable-gpios:
+ maxItems: 1
+ description: |
+ Specifier for a GPIO connected to the panel enable control signal. The
+ enable signal is active high and enables operation of the panel. This
+ property can also be used for panels implementing an active low power down
+ signal, which is a negated version of the enable signal. Active low enable
+ signals (or active high power down signals) can be supported by inverting
+ the GPIO specifier polarity flag.
+
+ Note that the enable signal control panel operation only and must not be
+ confused with a backlight enable signal.
+
+ reset-gpios:
+ maxItems: 1
+ description:
+ Specifier for a GPIO connected to the panel reset control signal.
+ The reset signal is active low and resets the panel internal logic
+ while active. Active high reset signals can be supported by inverting the
+ GPIO specifier polarity flag.
+
+ # Power
+ power-supply:
+ description:
+ Display panels require power to be supplied. While several panels need
+ more than one power supply with panel-specific constraints governing the
+ order and timings of the power supplies, in many cases a single power
+ supply is sufficient, either because the panel has a single power rail, or
+ because all its power rails can be driven by the same supply. In that case
+ the power-supply property specifies the supply powering the panel as a
+ phandle to a regulator.
+
+ # Backlight
+
+ # Most display panels include a backlight. Some of them also include a backlight
+ # controller exposed through a control bus such as I2C or DSI. Others expose
+ # backlight control through GPIO, PWM or other signals connected to an external
+ # backlight controller.
+
+ backlight:
+ $ref: /schemas/types.yaml#/definitions/phandle
+ description:
+ For panels whose backlight is controlled by an external backlight
+ controller, this property contains a phandle that references the
+ controller.
+
+dependencies:
+ width-mm: [ height-mm ]
+ height-mm: [ width-mm ]
+
+...
diff --git a/Documentation/devicetree/bindings/display/panel/panel-lvds.txt b/Documentation/devicetree/bindings/display/panel/panel-lvds.txt
deleted file mode 100644
index 250850a..0000000
--- a/Documentation/devicetree/bindings/display/panel/panel-lvds.txt
+++ /dev/null
@@ -1,121 +0,0 @@
-LVDS Display Panel
-==================
-
-LVDS is a physical layer specification defined in ANSI/TIA/EIA-644-A. Multiple
-incompatible data link layers have been used over time to transmit image data
-to LVDS panels. This bindings supports display panels compatible with the
-following specifications.
-
-[JEIDA] "Digital Interface Standards for Monitor", JEIDA-59-1999, February
-1999 (Version 1.0), Japan Electronic Industry Development Association (JEIDA)
-[LDI] "Open LVDS Display Interface", May 1999 (Version 0.95), National
-Semiconductor
-[VESA] "VESA Notebook Panel Standard", October 2007 (Version 1.0), Video
-Electronics Standards Association (VESA)
-
-Device compatible with those specifications have been marketed under the
-FPD-Link and FlatLink brands.
-
-
-Required properties:
-
-- compatible: Shall contain "panel-lvds" in addition to a mandatory
- panel-specific compatible string defined in individual panel bindings. The
- "panel-lvds" value shall never be used on its own.
-- width-mm: See panel-common.txt.
-- height-mm: See panel-common.txt.
-- data-mapping: The color signals mapping order, "jeida-18", "jeida-24"
- or "vesa-24".
-
-Optional properties:
-
-- label: See panel-common.txt.
-- gpios: See panel-common.txt.
-- backlight: See panel-common.txt.
-- power-supply: See panel-common.txt.
-- data-mirror: If set, reverse the bit order described in the data mappings
- below on all data lanes, transmitting bits for slots 6 to 0 instead of
- 0 to 6.
-
-Required nodes:
-
-- panel-timing: See panel-common.txt.
-- ports: See panel-common.txt. These bindings require a single port subnode
- corresponding to the panel LVDS input.
-
-
-LVDS data mappings are defined as follows.
-
-- "jeida-18" - 18-bit data mapping compatible with the [JEIDA], [LDI] and
- [VESA] specifications. Data are transferred as follows on 3 LVDS lanes.
-
-Slot 0 1 2 3 4 5 6
- ________________ _________________
-Clock \_______________________/
- ______ ______ ______ ______ ______ ______ ______
-DATA0 ><__G0__><__R5__><__R4__><__R3__><__R2__><__R1__><__R0__><
-DATA1 ><__B1__><__B0__><__G5__><__G4__><__G3__><__G2__><__G1__><
-DATA2 ><_CTL2_><_CTL1_><_CTL0_><__B5__><__B4__><__B3__><__B2__><
-
-- "jeida-24" - 24-bit data mapping compatible with the [DSIM] and [LDI]
- specifications. Data are transferred as follows on 4 LVDS lanes.
-
-Slot 0 1 2 3 4 5 6
- ________________ _________________
-Clock \_______________________/
- ______ ______ ______ ______ ______ ______ ______
-DATA0 ><__G2__><__R7__><__R6__><__R5__><__R4__><__R3__><__R2__><
-DATA1 ><__B3__><__B2__><__G7__><__G6__><__G5__><__G4__><__G3__><
-DATA2 ><_CTL2_><_CTL1_><_CTL0_><__B7__><__B6__><__B5__><__B4__><
-DATA3 ><_CTL3_><__B1__><__B0__><__G1__><__G0__><__R1__><__R0__><
-
-- "vesa-24" - 24-bit data mapping compatible with the [VESA] specification.
- Data are transferred as follows on 4 LVDS lanes.
-
-Slot 0 1 2 3 4 5 6
- ________________ _________________
-Clock \_______________________/
- ______ ______ ______ ______ ______ ______ ______
-DATA0 ><__G0__><__R5__><__R4__><__R3__><__R2__><__R1__><__R0__><
-DATA1 ><__B1__><__B0__><__G5__><__G4__><__G3__><__G2__><__G1__><
-DATA2 ><_CTL2_><_CTL1_><_CTL0_><__B5__><__B4__><__B3__><__B2__><
-DATA3 ><_CTL3_><__B7__><__B6__><__G7__><__G6__><__R7__><__R6__><
-
-Control signals are mapped as follows.
-
-CTL0: HSync
-CTL1: VSync
-CTL2: Data Enable
-CTL3: 0
-
-
-Example
--------
-
-panel {
- compatible = "mitsubishi,aa121td01", "panel-lvds";
-
- width-mm = <261>;
- height-mm = <163>;
-
- data-mapping = "jeida-24";
-
- panel-timing {
- /* 1280x800 @60Hz */
- clock-frequency = <71000000>;
- hactive = <1280>;
- vactive = <800>;
- hsync-len = <70>;
- hfront-porch = <20>;
- hback-porch = <70>;
- vsync-len = <5>;
- vfront-porch = <3>;
- vback-porch = <15>;
- };
-
- port {
- panel_in: endpoint {
- remote-endpoint = <&lvds_encoder>;
- };
- };
-};
diff --git a/Documentation/devicetree/bindings/display/panel/panel.txt b/Documentation/devicetree/bindings/display/panel/panel.txt
deleted file mode 100644
index e2e6867..0000000
--- a/Documentation/devicetree/bindings/display/panel/panel.txt
+++ /dev/null
@@ -1,4 +0,0 @@
-Common display properties
--------------------------
-
-- rotation: Display rotation in degrees counter clockwise (0,90,180,270)
diff --git a/Documentation/devicetree/bindings/display/panel/pda,91-00156-a0.txt b/Documentation/devicetree/bindings/display/panel/pda,91-00156-a0.txt
deleted file mode 100644
index 1639fb1..0000000
--- a/Documentation/devicetree/bindings/display/panel/pda,91-00156-a0.txt
+++ /dev/null
@@ -1,14 +0,0 @@
-PDA 91-00156-A0 5.0" WVGA TFT LCD panel
-
-Required properties:
-- compatible: should be "pda,91-00156-a0"
-- power-supply: this panel requires a single power supply. A phandle to a
-regulator needs to be specified here. Compatible with panel-common binding which
-is specified in the panel-common.txt in this directory.
-- backlight: this panel's backlight is controlled by an external backlight
-controller. A phandle to this controller needs to be specified here.
-Compatible with panel-common binding which is specified in the panel-common.txt
-in this directory.
-
-This binding is compatible with the simple-panel binding, which is specified
-in simple-panel.txt in this directory.
diff --git a/Documentation/devicetree/bindings/display/panel/pda,91-00156-a0.yaml b/Documentation/devicetree/bindings/display/panel/pda,91-00156-a0.yaml
new file mode 100644
index 0000000..ccd3623b
--- /dev/null
+++ b/Documentation/devicetree/bindings/display/panel/pda,91-00156-a0.yaml
@@ -0,0 +1,31 @@
+# SPDX-License-Identifier: GPL-2.0
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/display/panel/pda,91-00156-a0.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: PDA 91-00156-A0 5.0" WVGA TFT LCD panel
+
+maintainers:
+ - Cristian Birsan <cristian.birsan@microchip.com>
+ - Thierry Reding <thierry.reding@gmail.com>
+
+allOf:
+ - $ref: panel-common.yaml#
+
+properties:
+ compatible:
+ const: pda,91-00156-a0
+
+ power-supply: true
+ backlight: true
+ port: true
+
+additionalProperties: false
+
+required:
+ - compatible
+ - power-supply
+ - backlight
+
+...
diff --git a/Documentation/devicetree/bindings/display/panel/raspberrypi,7inch-touchscreen.txt b/Documentation/devicetree/bindings/display/panel/raspberrypi,7inch-touchscreen.txt
deleted file mode 100644
index e9e19c0..0000000
--- a/Documentation/devicetree/bindings/display/panel/raspberrypi,7inch-touchscreen.txt
+++ /dev/null
@@ -1,49 +0,0 @@
-This binding covers the official 7" (800x480) Raspberry Pi touchscreen
-panel.
-
-This DSI panel contains:
-
-- TC358762 DSI->DPI bridge
-- Atmel microcontroller on I2C for power sequencing the DSI bridge and
- controlling backlight
-- Touchscreen controller on I2C for touch input
-
-and this binding covers the DSI display parts but not its touch input.
-
-Required properties:
-- compatible: Must be "raspberrypi,7inch-touchscreen-panel"
-- reg: Must be "45"
-- port: See panel-common.txt
-
-Example:
-
-dsi1: dsi@7e700000 {
- #address-cells = <1>;
- #size-cells = <0>;
- <...>
-
- port {
- dsi_out_port: endpoint {
- remote-endpoint = <&panel_dsi_port>;
- };
- };
-};
-
-i2c_dsi: i2c {
- compatible = "i2c-gpio";
- #address-cells = <1>;
- #size-cells = <0>;
- gpios = <&gpio 28 0
- &gpio 29 0>;
-
- lcd@45 {
- compatible = "raspberrypi,7inch-touchscreen-panel";
- reg = <0x45>;
-
- port {
- panel_dsi_port: endpoint {
- remote-endpoint = <&dsi_out_port>;
- };
- };
- };
-};
diff --git a/Documentation/devicetree/bindings/display/panel/raspberrypi,7inch-touchscreen.yaml b/Documentation/devicetree/bindings/display/panel/raspberrypi,7inch-touchscreen.yaml
new file mode 100644
index 0000000..22a083f
--- /dev/null
+++ b/Documentation/devicetree/bindings/display/panel/raspberrypi,7inch-touchscreen.yaml
@@ -0,0 +1,71 @@
+# SPDX-License-Identifier: GPL-2.0
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/display/panel/raspberrypi,7inch-touchscreen.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: The official 7" (800x480) Raspberry Pi touchscreen
+
+maintainers:
+ - Eric Anholt <eric@anholt.net>
+ - Thierry Reding <thierry.reding@gmail.com>
+
+description: |+
+ This DSI panel contains:
+
+ - TC358762 DSI->DPI bridge
+ - Atmel microcontroller on I2C for power sequencing the DSI bridge and
+ controlling backlight
+ - Touchscreen controller on I2C for touch input
+
+ and this binding covers the DSI display parts but not its touch input.
+
+properties:
+ compatible:
+ const: raspberrypi,7inch-touchscreen-panel
+
+ reg:
+ const: 0x45
+
+ port: true
+
+required:
+ - compatible
+ - reg
+ - port
+
+additionalProperties: false
+
+examples:
+ - |+
+ dsi1: dsi {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ port {
+ dsi_out_port: endpoint {
+ remote-endpoint = <&panel_dsi_port>;
+ };
+ };
+ };
+
+ i2c_dsi: i2c {
+ compatible = "i2c-gpio";
+ #address-cells = <1>;
+ #size-cells = <0>;
+ scl-gpios = <&gpio 28 0>;
+ sda-gpios = <&gpio 29 0>;
+
+ lcd@45 {
+ compatible = "raspberrypi,7inch-touchscreen-panel";
+ reg = <0x45>;
+
+ port {
+ panel_dsi_port: endpoint {
+ remote-endpoint = <&dsi_out_port>;
+ };
+ };
+ };
+ };
+
+...
diff --git a/Documentation/devicetree/bindings/display/panel/raydium,rm67191.txt b/Documentation/devicetree/bindings/display/panel/raydium,rm67191.txt
new file mode 100644
index 0000000..1042469
--- /dev/null
+++ b/Documentation/devicetree/bindings/display/panel/raydium,rm67191.txt
@@ -0,0 +1,41 @@
+Raydium RM67171 OLED LCD panel with MIPI-DSI protocol
+
+Required properties:
+- compatible: "raydium,rm67191"
+- reg: virtual channel for MIPI-DSI protocol
+ must be <0>
+- dsi-lanes: number of DSI lanes to be used
+ must be <3> or <4>
+- port: input port node with endpoint definition as
+ defined in Documentation/devicetree/bindings/graph.txt;
+ the input port should be connected to a MIPI-DSI device
+ driver
+
+Optional properties:
+- reset-gpios: a GPIO spec for the RST_B GPIO pin
+- v3p3-supply: phandle to 3.3V regulator that powers the VDD_3V3 pin
+- v1p8-supply: phandle to 1.8V regulator that powers the VDD_1V8 pin
+- width-mm: see panel-common.txt
+- height-mm: see panel-common.txt
+- video-mode: 0 - burst-mode
+ 1 - non-burst with sync event
+ 2 - non-burst with sync pulse
+
+Example:
+
+ panel@0 {
+ compatible = "raydium,rm67191";
+ reg = <0>;
+ pinctrl-0 = <&pinctrl_mipi_dsi_0_1_en>;
+ pinctrl-names = "default";
+ reset-gpios = <&gpio1 7 GPIO_ACTIVE_LOW>;
+ dsi-lanes = <4>;
+ width-mm = <68>;
+ height-mm = <121>;
+
+ port {
+ panel_in: endpoint {
+ remote-endpoint = <&mipi_out>;
+ };
+ };
+ };
diff --git a/Documentation/devicetree/bindings/display/panel/rocktech,jh057n00900.txt b/Documentation/devicetree/bindings/display/panel/rocktech,jh057n00900.txt
index 1b57632..a372c5d 100644
--- a/Documentation/devicetree/bindings/display/panel/rocktech,jh057n00900.txt
+++ b/Documentation/devicetree/bindings/display/panel/rocktech,jh057n00900.txt
@@ -5,6 +5,9 @@
- reg: DSI virtual channel of the peripheral
- reset-gpios: panel reset gpio
- backlight: phandle of the backlight device attached to the panel
+- vcc-supply: phandle of the regulator that provides the vcc supply voltage.
+- iovcc-supply: phandle of the regulator that provides the iovcc supply
+ voltage.
Example:
@@ -14,5 +17,7 @@
reg = <0>;
backlight = <&backlight>;
reset-gpios = <&gpio3 13 GPIO_ACTIVE_LOW>;
+ vcc-supply = <®_2v8_p>;
+ iovcc-supply = <®_1v8_p>;
};
};
diff --git a/Documentation/devicetree/bindings/display/panel/sgd,gktw70sdae4se.txt b/Documentation/devicetree/bindings/display/panel/sgd,gktw70sdae4se.txt
deleted file mode 100644
index d06644b..0000000
--- a/Documentation/devicetree/bindings/display/panel/sgd,gktw70sdae4se.txt
+++ /dev/null
@@ -1,41 +0,0 @@
-Solomon Goldentek Display GKTW70SDAE4SE LVDS Display Panel
-==========================================================
-
-The GKTW70SDAE4SE is a 7" WVGA TFT-LCD display panel.
-
-These DT bindings follow the LVDS panel bindings defined in panel-lvds.txt
-with the following device-specific properties.
-
-Required properties:
-
-- compatible: Shall contain "sgd,gktw70sdae4se" and "panel-lvds", in that order.
-
-Example
--------
-
-panel {
- compatible = "sgd,gktw70sdae4se", "panel-lvds";
-
- width-mm = <153>;
- height-mm = <86>;
-
- data-mapping = "jeida-18";
-
- panel-timing {
- clock-frequency = <32000000>;
- hactive = <800>;
- vactive = <480>;
- hback-porch = <39>;
- hfront-porch = <39>;
- vback-porch = <29>;
- vfront-porch = <13>;
- hsync-len = <47>;
- vsync-len = <2>;
- };
-
- port {
- panel_in: endpoint {
- remote-endpoint = <&lvds_encoder>;
- };
- };
-};
diff --git a/Documentation/devicetree/bindings/display/panel/sgd,gktw70sdae4se.yaml b/Documentation/devicetree/bindings/display/panel/sgd,gktw70sdae4se.yaml
new file mode 100644
index 0000000..e63a570
--- /dev/null
+++ b/Documentation/devicetree/bindings/display/panel/sgd,gktw70sdae4se.yaml
@@ -0,0 +1,68 @@
+# SPDX-License-Identifier: GPL-2.0
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/display/panel/sgd,gktw70sdae4se.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Solomon Goldentek Display GKTW70SDAE4SE 7" WVGA LVDS Display Panel
+
+maintainers:
+ - Neil Armstrong <narmstrong@baylibre.com>
+ - Thierry Reding <thierry.reding@gmail.com>
+
+allOf:
+ - $ref: lvds.yaml#
+
+properties:
+ compatible:
+ items:
+ - const: sgd,gktw70sdae4se
+ - {} # panel-lvds, but not listed here to avoid false select
+
+ data-mapping:
+ const: jeida-18
+
+ width-mm:
+ const: 153
+
+ height-mm:
+ const: 86
+
+ panel-timing: true
+ port: true
+
+additionalProperties: false
+
+required:
+ - compatible
+
+examples:
+ - |+
+ panel {
+ compatible = "sgd,gktw70sdae4se", "panel-lvds";
+
+ width-mm = <153>;
+ height-mm = <86>;
+
+ data-mapping = "jeida-18";
+
+ panel-timing {
+ clock-frequency = <32000000>;
+ hactive = <800>;
+ vactive = <480>;
+ hback-porch = <39>;
+ hfront-porch = <39>;
+ vback-porch = <29>;
+ vfront-porch = <13>;
+ hsync-len = <47>;
+ vsync-len = <2>;
+ };
+
+ port {
+ panel_in: endpoint {
+ remote-endpoint = <&lvds_encoder>;
+ };
+ };
+ };
+
+...
diff --git a/Documentation/devicetree/bindings/display/panel/sharp,ld-d5116z01b.txt b/Documentation/devicetree/bindings/display/panel/sharp,ld-d5116z01b.txt
new file mode 100644
index 0000000..fd9cf39
--- /dev/null
+++ b/Documentation/devicetree/bindings/display/panel/sharp,ld-d5116z01b.txt
@@ -0,0 +1,26 @@
+Sharp LD-D5116Z01B 12.3" WUXGA+ eDP panel
+
+Required properties:
+- compatible: should be "sharp,ld-d5116z01b"
+- power-supply: regulator to provide the VCC supply voltage (3.3 volts)
+
+This binding is compatible with the simple-panel binding.
+
+The device node can contain one 'port' child node with one child
+'endpoint' node, according to the bindings defined in [1]. This
+node should describe panel's video bus.
+
+[1]: Documentation/devicetree/bindings/media/video-interfaces.txt
+
+Example:
+
+ panel: panel {
+ compatible = "sharp,ld-d5116z01b";
+ power-supply = <&vlcd_3v3>;
+
+ port {
+ panel_ep: endpoint {
+ remote-endpoint = <&bridge_out_ep>;
+ };
+ };
+ };
diff --git a/Documentation/devicetree/bindings/display/panel/sharp,lq070y3dg3b.txt b/Documentation/devicetree/bindings/display/panel/sharp,lq070y3dg3b.txt
new file mode 100644
index 0000000..95534b5
--- /dev/null
+++ b/Documentation/devicetree/bindings/display/panel/sharp,lq070y3dg3b.txt
@@ -0,0 +1,12 @@
+Sharp LQ070Y3DG3B 7.0" WVGA landscape TFT LCD panel
+
+Required properties:
+- compatible: should be "sharp,lq070y3dg3b"
+
+Optional properties:
+- enable-gpios: GPIO pin to enable or disable the panel
+- backlight: phandle of the backlight device attached to the panel
+- power-supply: phandle of the regulator that provides the supply voltage
+
+This binding is compatible with the simple-panel binding, which is specified
+in simple-panel.txt in this directory.
diff --git a/Documentation/devicetree/bindings/display/panel/sharp,ls020b1dd01d.txt b/Documentation/devicetree/bindings/display/panel/sharp,ls020b1dd01d.txt
new file mode 100644
index 0000000..e45edbc
--- /dev/null
+++ b/Documentation/devicetree/bindings/display/panel/sharp,ls020b1dd01d.txt
@@ -0,0 +1,12 @@
+Sharp 2.0" (240x160 pixels) 16-bit TFT LCD panel
+
+Required properties:
+- compatible: should be "sharp,ls020b1dd01d"
+- power-supply: as specified in the base binding
+
+Optional properties:
+- backlight: as specified in the base binding
+- enable-gpios: as specified in the base binding
+
+This binding is compatible with the simple-panel binding, which is specified
+in simple-panel.txt in this directory.
diff --git a/Documentation/devicetree/bindings/display/panel/simple-panel.txt b/Documentation/devicetree/bindings/display/panel/simple-panel.txt
index b2b872c..e11208f 100644
--- a/Documentation/devicetree/bindings/display/panel/simple-panel.txt
+++ b/Documentation/devicetree/bindings/display/panel/simple-panel.txt
@@ -1,28 +1 @@
-Simple display panel
-====================
-
-panel node
-----------
-
-Required properties:
-- power-supply: See panel-common.txt
-
-Optional properties:
-- ddc-i2c-bus: phandle of an I2C controller used for DDC EDID probing
-- enable-gpios: GPIO pin to enable or disable the panel
-- backlight: phandle of the backlight device attached to the panel
-- no-hpd: This panel is supposed to communicate that it's ready via HPD
- (hot plug detect) signal, but the signal isn't hooked up so we should
- hardcode the max delay from the panel spec when powering up the panel.
-
-Example:
-
- panel: panel {
- compatible = "cptt,claa101wb01";
- ddc-i2c-bus = <&panelddc>;
-
- power-supply = <&vdd_pnl_reg>;
- enable-gpios = <&gpio 90 0>;
-
- backlight = <&backlight>;
- };
+See panel-common.yaml in this directory.
diff --git a/Documentation/devicetree/bindings/display/panel/tfc,s9700rtwv43tr-01b.txt b/Documentation/devicetree/bindings/display/panel/tfc,s9700rtwv43tr-01b.txt
deleted file mode 100644
index dfb572f..0000000
--- a/Documentation/devicetree/bindings/display/panel/tfc,s9700rtwv43tr-01b.txt
+++ /dev/null
@@ -1,15 +0,0 @@
-TFC S9700RTWV43TR-01B 7" Three Five Corp 800x480 LCD panel with
-resistive touch
-
-The panel is found on TI AM335x-evm.
-
-Required properties:
-- compatible: should be "tfc,s9700rtwv43tr-01b"
-- power-supply: See panel-common.txt
-
-Optional properties:
-- enable-gpios: GPIO pin to enable or disable the panel, if there is one
-- backlight: phandle of the backlight device attached to the panel
-
-This binding is compatible with the simple-panel binding, which is specified
-in simple-panel.txt in this directory.
diff --git a/Documentation/devicetree/bindings/display/panel/tfc,s9700rtwv43tr-01b.yaml b/Documentation/devicetree/bindings/display/panel/tfc,s9700rtwv43tr-01b.yaml
new file mode 100644
index 0000000..9e59944
--- /dev/null
+++ b/Documentation/devicetree/bindings/display/panel/tfc,s9700rtwv43tr-01b.yaml
@@ -0,0 +1,33 @@
+# SPDX-License-Identifier: GPL-2.0
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/display/panel/tfc,s9700rtwv43tr-01b.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: TFC S9700RTWV43TR-01B 7" Three Five Corp 800x480 LCD panel with resistive touch
+
+maintainers:
+ - Jyri Sarha <jsarha@ti.com>
+ - Thierry Reding <thierry.reding@gmail.com>
+
+description: |+
+ The panel is found on TI AM335x-evm.
+
+allOf:
+ - $ref: panel-common.yaml#
+
+properties:
+ compatible:
+ const: tfc,s9700rtwv43tr-01b
+
+ enable-gpios: true
+ backlight: true
+ port: true
+
+additionalProperties: false
+
+required:
+ - compatible
+ - power-supply
+
+...
diff --git a/Documentation/devicetree/bindings/display/panel/ti,nspire.yaml b/Documentation/devicetree/bindings/display/panel/ti,nspire.yaml
new file mode 100644
index 0000000..5c5a3b5
--- /dev/null
+++ b/Documentation/devicetree/bindings/display/panel/ti,nspire.yaml
@@ -0,0 +1,36 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/display/panel/ti,nspire.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Texas Instruments NSPIRE Display Panels
+
+maintainers:
+ - Linus Walleij <linus.walleij@linaro.org>
+
+allOf:
+ - $ref: panel-common.yaml#
+
+properties:
+ compatible:
+ enum:
+ - ti,nspire-cx-lcd-panel
+ - ti,nspire-classic-lcd-panel
+ port: true
+
+required:
+ - compatible
+
+additionalProperties: false
+
+examples:
+ - |
+ panel {
+ compatible = "ti,nspire-cx-lcd-panel";
+ port {
+ panel_in: endpoint {
+ remote-endpoint = <&pads>;
+ };
+ };
+ };
diff --git a/Documentation/devicetree/bindings/display/panel/tpo,tpg110.txt b/Documentation/devicetree/bindings/display/panel/tpo,tpg110.txt
deleted file mode 100644
index 40f3d7c..0000000
--- a/Documentation/devicetree/bindings/display/panel/tpo,tpg110.txt
+++ /dev/null
@@ -1,70 +0,0 @@
-TPO TPG110 Panel
-================
-
-This panel driver is a component that acts as an intermediary
-between an RGB output and a variety of panels. The panel
-driver is strapped up in electronics to the desired resolution
-and other properties, and has a control interface over 3WIRE
-SPI. By talking to the TPG110 over SPI, the strapped properties
-can be discovered and the hardware is therefore mostly
-self-describing.
-
- +--------+
-SPI -> | TPO | -> physical display
-RGB -> | TPG110 |
- +--------+
-
-If some electrical strap or alternate resolution is desired,
-this can be set up by taking software control of the display
-over the SPI interface. The interface can also adjust
-for properties of the display such as gamma correction and
-certain electrical driving levels.
-
-The TPG110 does not know the physical dimensions of the panel
-connected, so this needs to be specified in the device tree.
-
-It requires a GPIO line for control of its reset line.
-
-The serial protocol has line names that resemble I2C but the
-protocol is not I2C but 3WIRE SPI.
-
-Required properties:
-- compatible : one of:
- "ste,nomadik-nhk15-display", "tpo,tpg110"
- "tpo,tpg110"
-- grestb-gpios : panel reset GPIO
-- width-mm : see display/panel/panel-common.txt
-- height-mm : see display/panel/panel-common.txt
-
-The device needs to be a child of an SPI bus, see
-spi/spi-bus.txt. The SPI child must set the following
-properties:
-- spi-3wire
-- spi-max-frequency = <3000000>;
-as these are characteristics of this device.
-
-The device node can contain one 'port' child node with one child
-'endpoint' node, according to the bindings defined in
-media/video-interfaces.txt. This node should describe panel's video bus.
-
-Example
--------
-
-panel: display@0 {
- compatible = "tpo,tpg110";
- reg = <0>;
- spi-3wire;
- /* 320 ns min period ~= 3 MHz */
- spi-max-frequency = <3000000>;
- /* Width and height from data sheet */
- width-mm = <116>;
- height-mm = <87>;
- grestb-gpios = <&foo_gpio 5 GPIO_ACTIVE_LOW>;
- backlight = <&bl>;
-
- port {
- nomadik_clcd_panel: endpoint {
- remote-endpoint = <&foo>;
- };
- };
-};
diff --git a/Documentation/devicetree/bindings/display/panel/tpo,tpg110.yaml b/Documentation/devicetree/bindings/display/panel/tpo,tpg110.yaml
new file mode 100644
index 0000000..a51660b
--- /dev/null
+++ b/Documentation/devicetree/bindings/display/panel/tpo,tpg110.yaml
@@ -0,0 +1,101 @@
+# SPDX-License-Identifier: GPL-2.0
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/display/panel/tpo,tpg110.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: TPO TPG110 Panel
+
+maintainers:
+ - Linus Walleij <linus.walleij@linaro.org>
+ - Thierry Reding <thierry.reding@gmail.com>
+
+description: |+
+ This panel driver is a component that acts as an intermediary
+ between an RGB output and a variety of panels. The panel
+ driver is strapped up in electronics to the desired resolution
+ and other properties, and has a control interface over 3WIRE
+ SPI. By talking to the TPG110 over SPI, the strapped properties
+ can be discovered and the hardware is therefore mostly
+ self-describing.
+
+ +--------+
+ SPI -> | TPO | -> physical display
+ RGB -> | TPG110 |
+ +--------+
+
+ If some electrical strap or alternate resolution is desired,
+ this can be set up by taking software control of the display
+ over the SPI interface. The interface can also adjust
+ for properties of the display such as gamma correction and
+ certain electrical driving levels.
+
+ The TPG110 does not know the physical dimensions of the panel
+ connected, so this needs to be specified in the device tree.
+
+ It requires a GPIO line for control of its reset line.
+
+ The serial protocol has line names that resemble I2C but the
+ protocol is not I2C but 3WIRE SPI.
+
+
+allOf:
+ - $ref: panel-common.yaml#
+
+properties:
+ compatible:
+ oneOf:
+ - items:
+ - enum:
+ - ste,nomadik-nhk15-display
+ - const: tpo,tpg110
+ - const: tpo,tpg110
+
+ reg: true
+
+ grestb-gpios:
+ maxItems: 1
+ description: panel reset GPIO
+
+ spi-3wire: true
+
+ spi-max-frequency:
+ const: 3000000
+
+required:
+ - compatible
+ - reg
+ - grestb-gpios
+ - width-mm
+ - height-mm
+ - spi-3wire
+ - spi-max-frequency
+ - port
+
+examples:
+ - |+
+ spi {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ panel: display@0 {
+ compatible = "tpo,tpg110";
+ reg = <0>;
+ spi-3wire;
+ /* 320 ns min period ~= 3 MHz */
+ spi-max-frequency = <3000000>;
+ /* Width and height from data sheet */
+ width-mm = <116>;
+ height-mm = <87>;
+ grestb-gpios = <&foo_gpio 5 1>;
+ backlight = <&bl>;
+
+ port {
+ nomadik_clcd_panel: endpoint {
+ remote-endpoint = <&foo>;
+ };
+ };
+ };
+ };
+
+...
diff --git a/Documentation/devicetree/bindings/display/rockchip/dw_mipi_dsi_rockchip.txt b/Documentation/devicetree/bindings/display/rockchip/dw_mipi_dsi_rockchip.txt
index 6bb59ab..ce4c1fc 100644
--- a/Documentation/devicetree/bindings/display/rockchip/dw_mipi_dsi_rockchip.txt
+++ b/Documentation/devicetree/bindings/display/rockchip/dw_mipi_dsi_rockchip.txt
@@ -14,6 +14,8 @@
- rockchip,grf: this soc should set GRF regs to mux vopl/vopb.
- ports: contain a port node with endpoint definitions as defined in [2].
For vopb,set the reg = <0> and set the reg = <1> for vopl.
+- video port 0 for the VOP input, the remote endpoint maybe vopb or vopl
+- video port 1 for either a panel or subsequent encoder
Optional properties:
- power-domains: a phandle to mipi dsi power domain node.
@@ -40,11 +42,12 @@
ports {
#address-cells = <1>;
#size-cells = <0>;
- reg = <1>;
- mipi_in: port {
+ mipi_in: port@0 {
+ reg = <0>;
#address-cells = <1>;
#size-cells = <0>;
+
mipi_in_vopb: endpoint@0 {
reg = <0>;
remote-endpoint = <&vopb_out_mipi>;
@@ -54,6 +57,16 @@
remote-endpoint = <&vopl_out_mipi>;
};
};
+
+ mipi_out: port@1 {
+ reg = <1>;
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ mipi_out_panel: endpoint {
+ remote-endpoint = <&panel_in_mipi>;
+ };
+ };
};
panel {
@@ -64,5 +77,11 @@
pinctrl-names = "default";
pinctrl-0 = <&lcd_en>;
backlight = <&backlight>;
+
+ port {
+ panel_in_mipi: endpoint {
+ remote-endpoint = <&mipi_out_panel>;
+ };
+ };
};
};
diff --git a/Documentation/devicetree/bindings/display/rockchip/rockchip-lvds.txt b/Documentation/devicetree/bindings/display/rockchip/rockchip-lvds.txt
index da6939e..7849ff0 100644
--- a/Documentation/devicetree/bindings/display/rockchip/rockchip-lvds.txt
+++ b/Documentation/devicetree/bindings/display/rockchip/rockchip-lvds.txt
@@ -32,17 +32,6 @@
- video port 0 for the VOP input, the remote endpoint maybe vopb or vopl
- video port 1 for either a panel or subsequent encoder
-the lvds panel described by
- Documentation/devicetree/bindings/display/panel/simple-panel.txt
-
-Panel required properties:
-- ports for remote LVDS output
-
-Panel optional properties:
-- data-mapping: should be "vesa-24","jeida-24" or "jeida-18".
-This describes decribed by:
- Documentation/devicetree/bindings/display/panel/panel-lvds.txt
-
Example:
lvds_panel: lvds-panel {
diff --git a/Documentation/devicetree/bindings/display/ssd1307fb.txt b/Documentation/devicetree/bindings/display/ssd1307fb.txt
index b67f8ca..27333b9 100644
--- a/Documentation/devicetree/bindings/display/ssd1307fb.txt
+++ b/Documentation/devicetree/bindings/display/ssd1307fb.txt
@@ -27,6 +27,15 @@
- solomon,prechargep2: Length of precharge period (phase 2) in clock cycles.
This needs to be the higher, the higher the capacitance
of the OLED's pixels is
+ - solomon,dclk-div: Clock divisor 1 to 16
+ - solomon,dclk-frq: Clock frequency 0 to 15, higher value means higher
+ frequency
+ - solomon,lookup-table: 8 bit value array of current drive pulse widths for
+ BANK0, and colors A, B, and C. Each value in range
+ of 31 to 63 for pulse widths of 32 to 64. Color D
+ is always width 64.
+ - solomon,area-color-enable: Display uses color mode
+ - solomon,low-power. Display runs in low power mode
[0]: Documentation/devicetree/bindings/pwm/pwm.txt
@@ -46,4 +55,5 @@
solomon,com-lrremap;
solomon,com-invdir;
solomon,com-offset = <32>;
+ solomon,lookup-table = /bits/ 8 <0x3f 0x3f 0x3f 0x3f>;
};
diff --git a/Documentation/devicetree/bindings/dma/allwinner,sun4i-a10-dma.yaml b/Documentation/devicetree/bindings/dma/allwinner,sun4i-a10-dma.yaml
new file mode 100644
index 0000000..15abc0f
--- /dev/null
+++ b/Documentation/devicetree/bindings/dma/allwinner,sun4i-a10-dma.yaml
@@ -0,0 +1,55 @@
+# SPDX-License-Identifier: GPL-2.0
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/dma/allwinner,sun4i-a10-dma.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Allwinner A10 DMA Controller Device Tree Bindings
+
+maintainers:
+ - Chen-Yu Tsai <wens@csie.org>
+ - Maxime Ripard <maxime.ripard@bootlin.com>
+
+allOf:
+ - $ref: "dma-controller.yaml#"
+
+properties:
+ "#dma-cells":
+ const: 2
+ description:
+ The first cell is either 0 or 1, the former to use the normal
+ DMA, 1 for dedicated DMA. The second cell is the request line
+ number.
+
+ compatible:
+ const: allwinner,sun4i-a10-dma
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+ clocks:
+ maxItems: 1
+
+required:
+ - "#dma-cells"
+ - compatible
+ - reg
+ - interrupts
+ - clocks
+
+additionalProperties: false
+
+examples:
+ - |
+ dma: dma-controller@1c02000 {
+ compatible = "allwinner,sun4i-a10-dma";
+ reg = <0x01c02000 0x1000>;
+ interrupts = <27>;
+ clocks = <&ahb_gates 6>;
+ #dma-cells = <2>;
+ };
+
+...
diff --git a/Documentation/devicetree/bindings/dma/allwinner,sun50i-a64-dma.yaml b/Documentation/devicetree/bindings/dma/allwinner,sun50i-a64-dma.yaml
new file mode 100644
index 0000000..4cb9d6b
--- /dev/null
+++ b/Documentation/devicetree/bindings/dma/allwinner,sun50i-a64-dma.yaml
@@ -0,0 +1,88 @@
+# SPDX-License-Identifier: GPL-2.0
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/dma/allwinner,sun50i-a64-dma.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Allwinner A64 DMA Controller Device Tree Bindings
+
+maintainers:
+ - Chen-Yu Tsai <wens@csie.org>
+ - Maxime Ripard <maxime.ripard@bootlin.com>
+
+allOf:
+ - $ref: "dma-controller.yaml#"
+
+properties:
+ "#dma-cells":
+ const: 1
+ description: The cell is the request line number.
+
+ compatible:
+ enum:
+ - allwinner,sun50i-a64-dma
+ - allwinner,sun50i-h6-dma
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+ clocks:
+ minItems: 1
+ maxItems: 2
+
+ clock-names:
+ items:
+ - const: bus
+ - const: mbus
+
+ resets:
+ maxItems: 1
+
+required:
+ - "#dma-cells"
+ - compatible
+ - reg
+ - interrupts
+ - clocks
+ - resets
+ - dma-channels
+
+if:
+ properties:
+ compatible:
+ const: allwinner,sun50i-h6-dma
+
+then:
+ properties:
+ clocks:
+ maxItems: 2
+
+ required:
+ - clock-names
+
+else:
+ properties:
+ clocks:
+ maxItems: 1
+
+# FIXME: We should set it, but it would report all the generic
+# properties as additional properties.
+# additionalProperties: false
+
+examples:
+ - |
+ dma: dma-controller@1c02000 {
+ compatible = "allwinner,sun50i-a64-dma";
+ reg = <0x01c02000 0x1000>;
+ interrupts = <0 50 4>;
+ clocks = <&ccu 30>;
+ dma-channels = <8>;
+ dma-requests = <27>;
+ resets = <&ccu 7>;
+ #dma-cells = <1>;
+ };
+
+...
diff --git a/Documentation/devicetree/bindings/dma/allwinner,sun6i-a31-dma.yaml b/Documentation/devicetree/bindings/dma/allwinner,sun6i-a31-dma.yaml
new file mode 100644
index 0000000..740b7f9
--- /dev/null
+++ b/Documentation/devicetree/bindings/dma/allwinner,sun6i-a31-dma.yaml
@@ -0,0 +1,62 @@
+# SPDX-License-Identifier: GPL-2.0
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/dma/allwinner,sun6i-a31-dma.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Allwinner A31 DMA Controller Device Tree Bindings
+
+maintainers:
+ - Chen-Yu Tsai <wens@csie.org>
+ - Maxime Ripard <maxime.ripard@bootlin.com>
+
+allOf:
+ - $ref: "dma-controller.yaml#"
+
+properties:
+ "#dma-cells":
+ const: 1
+ description: The cell is the request line number.
+
+ compatible:
+ oneOf:
+ - const: allwinner,sun6i-a31-dma
+ - const: allwinner,sun8i-a23-dma
+ - const: allwinner,sun8i-a83t-dma
+ - const: allwinner,sun8i-h3-dma
+ - const: allwinner,sun8i-v3s-dma
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+ clocks:
+ maxItems: 1
+
+ resets:
+ maxItems: 1
+
+required:
+ - "#dma-cells"
+ - compatible
+ - reg
+ - interrupts
+ - clocks
+ - resets
+
+additionalProperties: false
+
+examples:
+ - |
+ dma: dma-controller@1c02000 {
+ compatible = "allwinner,sun6i-a31-dma";
+ reg = <0x01c02000 0x1000>;
+ interrupts = <0 50 4>;
+ clocks = <&ahb1_gates 6>;
+ resets = <&ahb1_rst 6>;
+ #dma-cells = <1>;
+ };
+
+...
diff --git a/Documentation/devicetree/bindings/dma/dma-common.yaml b/Documentation/devicetree/bindings/dma/dma-common.yaml
new file mode 100644
index 0000000..ed0a49a
--- /dev/null
+++ b/Documentation/devicetree/bindings/dma/dma-common.yaml
@@ -0,0 +1,45 @@
+# SPDX-License-Identifier: GPL-2.0
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/dma/dma-common.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: DMA Engine Generic Binding
+
+maintainers:
+ - Vinod Koul <vkoul@kernel.org>
+
+description:
+ Generic binding to provide a way for a driver using DMA Engine to
+ retrieve the DMA request or channel information that goes from a
+ hardware device to a DMA controller.
+
+select: false
+
+properties:
+ "#dma-cells":
+ minimum: 1
+ # Should be enough
+ maximum: 255
+ description:
+ Used to provide DMA controller specific information.
+
+ dma-channel-mask:
+ $ref: /schemas/types.yaml#definitions/uint32
+ description:
+ Bitmask of available DMA channels in ascending order that are
+ not reserved by firmware and are available to the
+ kernel. i.e. first channel corresponds to LSB.
+
+ dma-channels:
+ $ref: /schemas/types.yaml#definitions/uint32
+ description:
+ Number of DMA channels supported by the controller.
+
+ dma-requests:
+ $ref: /schemas/types.yaml#definitions/uint32
+ description:
+ Number of DMA request signals supported by the controller.
+
+required:
+ - "#dma-cells"
diff --git a/Documentation/devicetree/bindings/dma/dma-controller.yaml b/Documentation/devicetree/bindings/dma/dma-controller.yaml
new file mode 100644
index 0000000..c39f6de
--- /dev/null
+++ b/Documentation/devicetree/bindings/dma/dma-controller.yaml
@@ -0,0 +1,35 @@
+# SPDX-License-Identifier: GPL-2.0
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/dma/dma-controller.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: DMA Controller Generic Binding
+
+maintainers:
+ - Vinod Koul <vkoul@kernel.org>
+
+allOf:
+ - $ref: "dma-common.yaml#"
+
+# Everything else is described in the common file
+properties:
+ $nodename:
+ pattern: "^dma-controller(@.*)?$"
+
+examples:
+ - |
+ dma: dma-controller@48000000 {
+ compatible = "ti,omap-sdma";
+ reg = <0x48000000 0x1000>;
+ interrupts = <0 12 0x4
+ 0 13 0x4
+ 0 14 0x4
+ 0 15 0x4>;
+ #dma-cells = <1>;
+ dma-channels = <32>;
+ dma-requests = <127>;
+ dma-channel-mask = <0xfffe>;
+ };
+
+...
diff --git a/Documentation/devicetree/bindings/dma/dma-router.yaml b/Documentation/devicetree/bindings/dma/dma-router.yaml
new file mode 100644
index 0000000..5b5f073
--- /dev/null
+++ b/Documentation/devicetree/bindings/dma/dma-router.yaml
@@ -0,0 +1,50 @@
+# SPDX-License-Identifier: GPL-2.0
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/dma/dma-router.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: DMA Router Generic Binding
+
+maintainers:
+ - Vinod Koul <vkoul@kernel.org>
+
+allOf:
+ - $ref: "dma-common.yaml#"
+
+description:
+ DMA routers are transparent IP blocks used to route DMA request
+ lines from devices to the DMA controller. Some SoCs (like TI DRA7x)
+ have more peripherals integrated with DMA requests than what the DMA
+ controller can handle directly.
+
+properties:
+ $nodename:
+ pattern: "^dma-router(@.*)?$"
+
+ dma-masters:
+ $ref: /schemas/types.yaml#definitions/phandle-array
+ description:
+ Array of phandles to the DMA controllers the router can direct
+ the signal to.
+
+ dma-requests:
+ description:
+ Number of incoming request lines the router can handle.
+
+required:
+ - "#dma-cells"
+ - dma-masters
+
+examples:
+ - |
+ sdma_xbar: dma-router@4a002b78 {
+ compatible = "ti,dra7-dma-crossbar";
+ reg = <0x4a002b78 0xfc>;
+ #dma-cells = <1>;
+ dma-requests = <205>;
+ ti,dma-safe-map = <0>;
+ dma-masters = <&sdma>;
+ };
+
+...
diff --git a/Documentation/devicetree/bindings/dma/dma.txt b/Documentation/devicetree/bindings/dma/dma.txt
index eeb4e4d..90a67a0 100644
--- a/Documentation/devicetree/bindings/dma/dma.txt
+++ b/Documentation/devicetree/bindings/dma/dma.txt
@@ -1,113 +1 @@
-* Generic DMA Controller and DMA request bindings
-
-Generic binding to provide a way for a driver using DMA Engine to retrieve the
-DMA request or channel information that goes from a hardware device to a DMA
-controller.
-
-
-* DMA controller
-
-Required property:
-- #dma-cells: Must be at least 1. Used to provide DMA controller
- specific information. See DMA client binding below for
- more details.
-
-Optional properties:
-- dma-channels: Number of DMA channels supported by the controller.
-- dma-requests: Number of DMA request signals supported by the
- controller.
-- dma-channel-mask: Bitmask of available DMA channels in ascending order
- that are not reserved by firmware and are available to
- the kernel. i.e. first channel corresponds to LSB.
-
-Example:
-
- dma: dma@48000000 {
- compatible = "ti,omap-sdma";
- reg = <0x48000000 0x1000>;
- interrupts = <0 12 0x4
- 0 13 0x4
- 0 14 0x4
- 0 15 0x4>;
- #dma-cells = <1>;
- dma-channels = <32>;
- dma-requests = <127>;
- dma-channel-mask = <0xfffe>
- };
-
-* DMA router
-
-DMA routers are transparent IP blocks used to route DMA request lines from
-devices to the DMA controller. Some SoCs (like TI DRA7x) have more peripherals
-integrated with DMA requests than what the DMA controller can handle directly.
-
-Required property:
-- dma-masters: phandle of the DMA controller or list of phandles for
- the DMA controllers the router can direct the signal to.
-- #dma-cells: Must be at least 1. Used to provide DMA router specific
- information. See DMA client binding below for more
- details.
-
-Optional properties:
-- dma-requests: Number of incoming request lines the router can handle.
-- In the node pointed by the dma-masters:
- - dma-requests: The router driver might need to look for this in order
- to configure the routing.
-
-Example:
- sdma_xbar: dma-router@4a002b78 {
- compatible = "ti,dra7-dma-crossbar";
- reg = <0x4a002b78 0xfc>;
- #dma-cells = <1>;
- dma-requests = <205>;
- ti,dma-safe-map = <0>;
- dma-masters = <&sdma>;
- };
-
-* DMA client
-
-Client drivers should specify the DMA property using a phandle to the controller
-followed by DMA controller specific data.
-
-Required property:
-- dmas: List of one or more DMA specifiers, each consisting of
- - A phandle pointing to DMA controller node
- - A number of integer cells, as determined by the
- #dma-cells property in the node referenced by phandle
- containing DMA controller specific information. This
- typically contains a DMA request line number or a
- channel number, but can contain any data that is
- required for configuring a channel.
-- dma-names: Contains one identifier string for each DMA specifier in
- the dmas property. The specific strings that can be used
- are defined in the binding of the DMA client device.
- Multiple DMA specifiers can be used to represent
- alternatives and in this case the dma-names for those
- DMA specifiers must be identical (see examples).
-
-Examples:
-
-1. A device with one DMA read channel, one DMA write channel:
-
- i2c1: i2c@1 {
- ...
- dmas = <&dma 2 /* read channel */
- &dma 3>; /* write channel */
- dma-names = "rx", "tx";
- ...
- };
-
-2. A single read-write channel with three alternative DMA controllers:
-
- dmas = <&dma1 5
- &dma2 7
- &dma3 2>;
- dma-names = "rx-tx", "rx-tx", "rx-tx";
-
-3. A device with three channels, one of which has two alternatives:
-
- dmas = <&dma1 2 /* read channel */
- &dma1 3 /* write channel */
- &dma2 0 /* error read */
- &dma3 0>; /* alternative error read */
- dma-names = "rx", "tx", "error", "error";
+This file has been moved to dma-controller.yaml.
diff --git a/Documentation/devicetree/bindings/dma/nbpfaxi.txt b/Documentation/devicetree/bindings/dma/renesas,nbpfaxi.txt
similarity index 100%
rename from Documentation/devicetree/bindings/dma/nbpfaxi.txt
rename to Documentation/devicetree/bindings/dma/renesas,nbpfaxi.txt
diff --git a/Documentation/devicetree/bindings/dma/shdma.txt b/Documentation/devicetree/bindings/dma/renesas,shdma.txt
similarity index 100%
rename from Documentation/devicetree/bindings/dma/shdma.txt
rename to Documentation/devicetree/bindings/dma/renesas,shdma.txt
diff --git a/Documentation/devicetree/bindings/dma/sun4i-dma.txt b/Documentation/devicetree/bindings/dma/sun4i-dma.txt
deleted file mode 100644
index 8ad556a..0000000
--- a/Documentation/devicetree/bindings/dma/sun4i-dma.txt
+++ /dev/null
@@ -1,45 +0,0 @@
-Allwinner A10 DMA Controller
-
-This driver follows the generic DMA bindings defined in dma.txt.
-
-Required properties:
-
-- compatible: Must be "allwinner,sun4i-a10-dma"
-- reg: Should contain the registers base address and length
-- interrupts: Should contain a reference to the interrupt used by this device
-- clocks: Should contain a reference to the parent AHB clock
-- #dma-cells : Should be 2, first cell denoting normal or dedicated dma,
- second cell holding the request line number.
-
-Example:
- dma: dma-controller@1c02000 {
- compatible = "allwinner,sun4i-a10-dma";
- reg = <0x01c02000 0x1000>;
- interrupts = <27>;
- clocks = <&ahb_gates 6>;
- #dma-cells = <2>;
- };
-
-Clients:
-
-DMA clients connected to the Allwinner A10 DMA controller must use the
-format described in the dma.txt file, using a three-cell specifier for
-each channel: a phandle plus two integer cells.
-The three cells in order are:
-
-1. A phandle pointing to the DMA controller.
-2. Whether it is using normal (0) or dedicated (1) channels
-3. The port ID as specified in the datasheet
-
-Example:
- spi2: spi@1c17000 {
- compatible = "allwinner,sun4i-a10-spi";
- reg = <0x01c17000 0x1000>;
- interrupts = <0 12 4>;
- clocks = <&ahb_gates 22>, <&spi2_clk>;
- clock-names = "ahb", "mod";
- dmas = <&dma 1 29>, <&dma 1 28>;
- dma-names = "rx", "tx";
- #address-cells = <1>;
- #size-cells = <0>;
- };
diff --git a/Documentation/devicetree/bindings/dma/sun6i-dma.txt b/Documentation/devicetree/bindings/dma/sun6i-dma.txt
deleted file mode 100644
index cae31f4..0000000
--- a/Documentation/devicetree/bindings/dma/sun6i-dma.txt
+++ /dev/null
@@ -1,81 +0,0 @@
-Allwinner A31 DMA Controller
-
-This driver follows the generic DMA bindings defined in dma.txt.
-
-Required properties:
-
-- compatible: Must be one of
- "allwinner,sun6i-a31-dma"
- "allwinner,sun8i-a23-dma"
- "allwinner,sun8i-a83t-dma"
- "allwinner,sun8i-h3-dma"
- "allwinner,sun8i-v3s-dma"
-- reg: Should contain the registers base address and length
-- interrupts: Should contain a reference to the interrupt used by this device
-- clocks: Should contain a reference to the parent AHB clock
-- resets: Should contain a reference to the reset controller asserting
- this device in reset
-- #dma-cells : Should be 1, a single cell holding a line request number
-
-Example:
- dma: dma-controller@1c02000 {
- compatible = "allwinner,sun6i-a31-dma";
- reg = <0x01c02000 0x1000>;
- interrupts = <0 50 4>;
- clocks = <&ahb1_gates 6>;
- resets = <&ahb1_rst 6>;
- #dma-cells = <1>;
- };
-
-------------------------------------------------------------------------------
-For A64 and H6 DMA controller:
-
-Required properties:
-- compatible: Must be one of
- "allwinner,sun50i-a64-dma"
- "allwinner,sun50i-h6-dma"
-- dma-channels: Number of DMA channels supported by the controller.
- Refer to Documentation/devicetree/bindings/dma/dma.txt
-- clocks: In addition to parent AHB clock, it should also contain mbus
- clock (H6 only)
-- clock-names: Should contain "bus" and "mbus" (H6 only)
-- all properties above, i.e. reg, interrupts, clocks, resets and #dma-cells
-
-Optional properties:
-- dma-requests: Number of DMA request signals supported by the controller.
- Refer to Documentation/devicetree/bindings/dma/dma.txt
-
-Example:
- dma: dma-controller@1c02000 {
- compatible = "allwinner,sun50i-a64-dma";
- reg = <0x01c02000 0x1000>;
- interrupts = <GIC_SPI 50 IRQ_TYPE_LEVEL_HIGH>;
- clocks = <&ccu CLK_BUS_DMA>;
- dma-channels = <8>;
- dma-requests = <27>;
- resets = <&ccu RST_BUS_DMA>;
- #dma-cells = <1>;
- };
-------------------------------------------------------------------------------
-
-Clients:
-
-DMA clients connected to the A31 DMA controller must use the format
-described in the dma.txt file, using a two-cell specifier for each
-channel: a phandle plus one integer cells.
-The two cells in order are:
-
-1. A phandle pointing to the DMA controller.
-2. The port ID as specified in the datasheet
-
-Example:
-spi2: spi@1c6a000 {
- compatible = "allwinner,sun6i-a31-spi";
- reg = <0x01c6a000 0x1000>;
- interrupts = <0 67 4>;
- clocks = <&ahb1_gates 22>, <&spi2_clk>;
- clock-names = "ahb", "mod";
- dmas = <&dma 25>, <&dma 25>;
- dma-names = "rx", "tx";
- resets = <&ahb1_rst 22>;
-};
diff --git a/Documentation/devicetree/bindings/dsp/fsl,dsp.yaml b/Documentation/devicetree/bindings/dsp/fsl,dsp.yaml
new file mode 100644
index 0000000..3248595
--- /dev/null
+++ b/Documentation/devicetree/bindings/dsp/fsl,dsp.yaml
@@ -0,0 +1,88 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/dsp/fsl,dsp.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: NXP i.MX8 DSP core
+
+maintainers:
+ - Daniel Baluta <daniel.baluta@nxp.com>
+
+description: |
+ Some boards from i.MX8 family contain a DSP core used for
+ advanced pre- and post- audio processing.
+
+properties:
+ compatible:
+ enum:
+ - fsl,imx8qxp-dsp
+
+ reg:
+ description: Should contain register location and length
+
+ clocks:
+ items:
+ - description: ipg clock
+ - description: ocram clock
+ - description: core clock
+
+ clock-names:
+ items:
+ - const: ipg
+ - const: ocram
+ - const: core
+
+ power-domains:
+ description:
+ List of phandle and PM domain specifier as documented in
+ Documentation/devicetree/bindings/power/power_domain.txt
+ maxItems: 4
+
+ mboxes:
+ description:
+ List of <&phandle type channel> - 2 channels for TXDB, 2 channels for RXDB
+ (see mailbox/fsl,mu.txt)
+ maxItems: 4
+
+ mbox-names:
+ items:
+ - const: txdb0
+ - const: txdb1
+ - const: rxdb0
+ - const: rxdb1
+
+ memory-region:
+ description:
+ phandle to a node describing reserved memory (System RAM memory)
+ used by DSP (see bindings/reserved-memory/reserved-memory.txt)
+ maxItems: 1
+
+required:
+ - compatible
+ - reg
+ - clocks
+ - clock-names
+ - power-domains
+ - mboxes
+ - mbox-names
+ - memory-region
+
+examples:
+ - |
+ #include <dt-bindings/firmware/imx/rsrc.h>
+ #include <dt-bindings/clock/imx8-clock.h>
+ dsp@596e8000 {
+ compatible = "fsl,imx8qxp-dsp";
+ reg = <0x596e8000 0x88000>;
+ clocks = <&adma_lpcg IMX_ADMA_LPCG_DSP_IPG_CLK>,
+ <&adma_lpcg IMX_ADMA_LPCG_OCRAM_IPG_CLK>,
+ <&adma_lpcg IMX_ADMA_LPCG_DSP_CORE_CLK>;
+ clock-names = "ipg", "ocram", "core";
+ power-domains = <&pd IMX_SC_R_MU_13A>,
+ <&pd IMX_SC_R_MU_13B>,
+ <&pd IMX_SC_R_DSP>,
+ <&pd IMX_SC_R_DSP_RAM>;
+ mbox-names = "txdb0", "txdb1", "rxdb0", "rxdb1";
+ mboxes = <&lsio_mu13 2 0>, <&lsio_mu13 2 1>, <&lsio_mu13 3 0>, <&lsio_mu13 3 1>;
+ };
diff --git a/Documentation/devicetree/bindings/eeprom/at25.txt b/Documentation/devicetree/bindings/eeprom/at25.txt
index b3bde97..42577dd 100644
--- a/Documentation/devicetree/bindings/eeprom/at25.txt
+++ b/Documentation/devicetree/bindings/eeprom/at25.txt
@@ -3,6 +3,7 @@
Required properties:
- compatible : Should be "<vendor>,<type>", and generic value "atmel,at25".
Example "<vendor>,<type>" values:
+ "anvo,anv32e61w"
"microchip,25lc040"
"st,m95m02"
"st,m95256"
diff --git a/Documentation/devicetree/bindings/example-schema.yaml b/Documentation/devicetree/bindings/example-schema.yaml
index 9175d67..c43819c 100644
--- a/Documentation/devicetree/bindings/example-schema.yaml
+++ b/Documentation/devicetree/bindings/example-schema.yaml
@@ -5,7 +5,7 @@
# All the top-level keys are standard json-schema keywords except for
# 'maintainers' and 'select'
-# $id is a unique idenifier based on the filename. There may or may not be a
+# $id is a unique identifier based on the filename. There may or may not be a
# file present at the URL.
$id: "http://devicetree.org/schemas/example-schema.yaml#"
# $schema is the meta-schema this schema should be validated with.
diff --git a/Documentation/devicetree/bindings/extcon/extcon-arizona.txt b/Documentation/devicetree/bindings/extcon/extcon-arizona.txt
index 7f3d94a..208daaf 100644
--- a/Documentation/devicetree/bindings/extcon/extcon-arizona.txt
+++ b/Documentation/devicetree/bindings/extcon/extcon-arizona.txt
@@ -72,5 +72,5 @@
1 2 1 /* MICDET2 MICBIAS2 GPIO=high */
>;
- wlf,gpsw = <0>;
+ wlf,gpsw = <ARIZONA_GPSW_OPEN>;
};
diff --git a/Documentation/devicetree/bindings/extcon/extcon-fsa9480.txt b/Documentation/devicetree/bindings/extcon/extcon-fsa9480.txt
index d592c21..624bd76 100644
--- a/Documentation/devicetree/bindings/extcon/extcon-fsa9480.txt
+++ b/Documentation/devicetree/bindings/extcon/extcon-fsa9480.txt
@@ -5,7 +5,9 @@
microphone, and UART data to use a common connector port.
Required properties:
- - compatible : Must be "fcs,fsa9480"
+ - compatible : Must be one of
+ "fcs,fsa9480"
+ "fcs,fsa880"
- reg : Specifies i2c slave address. Must be 0x25.
- interrupts : Should contain one entry specifying interrupt signal of
interrupt parent to which interrupt pin of the chip is connected.
diff --git a/Documentation/devicetree/bindings/firmware/cznic,turris-mox-rwtm.txt b/Documentation/devicetree/bindings/firmware/cznic,turris-mox-rwtm.txt
new file mode 100644
index 0000000..338169d
--- /dev/null
+++ b/Documentation/devicetree/bindings/firmware/cznic,turris-mox-rwtm.txt
@@ -0,0 +1,19 @@
+Turris Mox rWTM firmware driver
+
+Required properties:
+ - compatible : Should be "cznic,turris-mox-rwtm"
+ - mboxes : Must contain a reference to associated mailbox
+
+This device tree node should be used on Turris Mox, or potentially another A3700
+compatible device running the Mox's rWTM firmware in the secure processor (for
+example it is possible to flash this firmware into EspressoBin).
+
+Example:
+
+ firmware {
+ turris-mox-rwtm {
+ compatible = "cznic,turris-mox-rwtm";
+ mboxes = <&rwtm 0>;
+ status = "okay";
+ };
+ };
diff --git a/Documentation/devicetree/bindings/firmware/qcom,scm.txt b/Documentation/devicetree/bindings/firmware/qcom,scm.txt
index 41f133a..3f29ea0 100644
--- a/Documentation/devicetree/bindings/firmware/qcom,scm.txt
+++ b/Documentation/devicetree/bindings/firmware/qcom,scm.txt
@@ -9,14 +9,16 @@
- compatible: must contain one of the following:
* "qcom,scm-apq8064"
* "qcom,scm-apq8084"
+ * "qcom,scm-ipq4019"
* "qcom,scm-msm8660"
* "qcom,scm-msm8916"
* "qcom,scm-msm8960"
* "qcom,scm-msm8974"
* "qcom,scm-msm8996"
* "qcom,scm-msm8998"
- * "qcom,scm-ipq4019"
+ * "qcom,scm-sc7180"
* "qcom,scm-sdm845"
+ * "qcom,scm-sm8150"
and:
* "qcom,scm"
- clocks: Specifies clocks needed by the SCM interface, if any:
diff --git a/Documentation/devicetree/bindings/fpga/altera-fpga2sdram-bridge.txt b/Documentation/devicetree/bindings/fpga/altera-fpga2sdram-bridge.txt
index 817a8d4..5dd0ff0 100644
--- a/Documentation/devicetree/bindings/fpga/altera-fpga2sdram-bridge.txt
+++ b/Documentation/devicetree/bindings/fpga/altera-fpga2sdram-bridge.txt
@@ -3,10 +3,7 @@
Required properties:
- compatible : Should contain "altr,socfpga-fpga2sdram-bridge"
-Optional properties:
-- bridge-enable : 0 if driver should disable bridge at startup
- 1 if driver should enable bridge at startup
- Default is to leave bridge in current state.
+See Documentation/devicetree/bindings/fpga/fpga-bridge.txt for generic bindings.
Example:
fpga_bridge3: fpga-bridge@ffc25080 {
diff --git a/Documentation/devicetree/bindings/fpga/altera-freeze-bridge.txt b/Documentation/devicetree/bindings/fpga/altera-freeze-bridge.txt
index f8e288c7..8b26fbc 100644
--- a/Documentation/devicetree/bindings/fpga/altera-freeze-bridge.txt
+++ b/Documentation/devicetree/bindings/fpga/altera-freeze-bridge.txt
@@ -10,10 +10,7 @@
- compatible : Should contain "altr,freeze-bridge-controller"
- regs : base address and size for freeze bridge module
-Optional properties:
-- bridge-enable : 0 if driver should disable bridge at startup
- 1 if driver should enable bridge at startup
- Default is to leave bridge in current state.
+See Documentation/devicetree/bindings/fpga/fpga-bridge.txt for generic bindings.
Example:
freeze-controller@100000450 {
diff --git a/Documentation/devicetree/bindings/fpga/altera-hps2fpga-bridge.txt b/Documentation/devicetree/bindings/fpga/altera-hps2fpga-bridge.txt
index 6406f93..68cce39 100644
--- a/Documentation/devicetree/bindings/fpga/altera-hps2fpga-bridge.txt
+++ b/Documentation/devicetree/bindings/fpga/altera-hps2fpga-bridge.txt
@@ -9,10 +9,7 @@
- resets : Phandle and reset specifier for this bridge's reset
- clocks : Clocks used by this module.
-Optional properties:
-- bridge-enable : 0 if driver should disable bridge at startup.
- 1 if driver should enable bridge at startup.
- Default is to leave bridge in its current state.
+See Documentation/devicetree/bindings/fpga/fpga-bridge.txt for generic bindings.
Example:
fpga_bridge0: fpga-bridge@ff400000 {
diff --git a/Documentation/devicetree/bindings/fpga/fpga-bridge.txt b/Documentation/devicetree/bindings/fpga/fpga-bridge.txt
new file mode 100644
index 0000000..72e0691
--- /dev/null
+++ b/Documentation/devicetree/bindings/fpga/fpga-bridge.txt
@@ -0,0 +1,13 @@
+FPGA Bridge Device Tree Binding
+
+Optional properties:
+- bridge-enable : 0 if driver should disable bridge at startup
+ 1 if driver should enable bridge at startup
+ Default is to leave bridge in current state.
+
+Example:
+ fpga_bridge3: fpga-bridge@ffc25080 {
+ compatible = "altr,socfpga-fpga2sdram-bridge";
+ reg = <0xffc25080 0x4>;
+ bridge-enable = <0>;
+ };
diff --git a/Documentation/devicetree/bindings/fpga/xilinx-pr-decoupler.txt b/Documentation/devicetree/bindings/fpga/xilinx-pr-decoupler.txt
index 8dcfba9..4284d29 100644
--- a/Documentation/devicetree/bindings/fpga/xilinx-pr-decoupler.txt
+++ b/Documentation/devicetree/bindings/fpga/xilinx-pr-decoupler.txt
@@ -18,12 +18,8 @@
- clocks : input clock to IP
- clock-names : should contain "aclk"
-Optional properties:
-- bridge-enable : 0 if driver should disable bridge at startup
- 1 if driver should enable bridge at startup
- Default is to leave bridge in current state.
-
-See Documentation/devicetree/bindings/fpga/fpga-region.txt for generic bindings.
+See Documentation/devicetree/bindings/fpga/fpga-region.txt and
+Documentation/devicetree/bindings/fpga/fpga-bridge.txt for generic bindings.
Example:
fpga-bridge@100000450 {
diff --git a/Documentation/devicetree/bindings/gpio/gpio-aspeed.txt b/Documentation/devicetree/bindings/gpio/gpio-aspeed.txt
index 7e9b586..b2033fc 100644
--- a/Documentation/devicetree/bindings/gpio/gpio-aspeed.txt
+++ b/Documentation/devicetree/bindings/gpio/gpio-aspeed.txt
@@ -2,7 +2,8 @@
-------------------------------------------
Required properties:
-- compatible : Either "aspeed,ast2400-gpio" or "aspeed,ast2500-gpio"
+- compatible : Either "aspeed,ast2400-gpio", "aspeed,ast2500-gpio",
+ or "aspeed,ast2600-gpio".
- #gpio-cells : Should be two
- First cell is the GPIO line number
@@ -17,7 +18,9 @@
Optional properties:
-- clocks : A phandle to the clock to use for debounce timings
+- clocks : A phandle to the clock to use for debounce timings
+- ngpios : Number of GPIOs controlled by this controller. Should be set
+ when there are multiple GPIO controllers on a SoC (ast2600).
The gpio and interrupt properties are further described in their respective
bindings documentation:
diff --git a/Documentation/devicetree/bindings/gpio/gpio-davinci.txt b/Documentation/devicetree/bindings/gpio/gpio-davinci.txt
index bc6b4b6..cd91d61 100644
--- a/Documentation/devicetree/bindings/gpio/gpio-davinci.txt
+++ b/Documentation/devicetree/bindings/gpio/gpio-davinci.txt
@@ -6,6 +6,7 @@
66AK2E SoCs
"ti,k2g-gpio", "ti,keystone-gpio": for 66AK2G
"ti,am654-gpio", "ti,keystone-gpio": for TI K3 AM654
+ "ti,j721e-gpio", "ti,keystone-gpio": for J721E SoCs
- reg: Physical base address of the controller and the size of memory mapped
registers.
diff --git a/Documentation/devicetree/bindings/gpio/gpio-moxtet.txt b/Documentation/devicetree/bindings/gpio/gpio-moxtet.txt
new file mode 100644
index 0000000..410759d
--- /dev/null
+++ b/Documentation/devicetree/bindings/gpio/gpio-moxtet.txt
@@ -0,0 +1,18 @@
+Turris Mox Moxtet GPIO expander via Moxtet bus
+
+Required properties:
+ - compatible : Should be "cznic,moxtet-gpio".
+ - gpio-controller : Marks the device node as a GPIO controller.
+ - #gpio-cells : Should be two. For consumer use see gpio.txt.
+
+Other properties are required for a Moxtet bus device, please refer to
+Documentation/devicetree/bindings/bus/moxtet.txt.
+
+Example:
+
+ moxtet_sfp: gpio@0 {
+ compatible = "cznic,moxtet-gpio";
+ gpio-controller;
+ #gpio-cells = <2>;
+ reg = <0>;
+ }
diff --git a/Documentation/devicetree/bindings/gpio/gpio-mpc8xxx.txt b/Documentation/devicetree/bindings/gpio/gpio-mpc8xxx.txt
index 69d4616..cd28e93 100644
--- a/Documentation/devicetree/bindings/gpio/gpio-mpc8xxx.txt
+++ b/Documentation/devicetree/bindings/gpio/gpio-mpc8xxx.txt
@@ -4,7 +4,7 @@
- compatible : Should be "fsl,<soc>-gpio"
The following <soc>s are known to be supported:
mpc5121, mpc5125, mpc8349, mpc8572, mpc8610, pq3, qoriq,
- ls1021a, ls1043a, ls2080a.
+ ls1021a, ls1043a, ls2080a, ls1028a, ls1088a.
- reg : Address and length of the register set for the device
- interrupts : Should be the port interrupt shared by all 32 pins.
- #gpio-cells : Should be two. The first cell is the pin number and
@@ -37,3 +37,17 @@
interrupt-controller;
#interrupt-cells = <2>;
};
+
+
+Example of gpio-controller node for a ls1028a/ls1088a SoC:
+
+gpio1: gpio@2300000 {
+ compatible = "fsl,ls1028a-gpio", "fsl,ls1088a-gpio", "fsl,qoriq-gpio";
+ reg = <0x0 0x2300000 0x0 0x10000>;
+ interrupts = <GIC_SPI 36 IRQ_TYPE_LEVEL_HIGH>;
+ gpio-controller;
+ #gpio-cells = <2>;
+ interrupt-controller;
+ #interrupt-cells = <2>;
+ little-endian;
+};
diff --git a/Documentation/devicetree/bindings/gpio/sgpio-aspeed.txt b/Documentation/devicetree/bindings/gpio/sgpio-aspeed.txt
new file mode 100644
index 0000000..d4d8391
--- /dev/null
+++ b/Documentation/devicetree/bindings/gpio/sgpio-aspeed.txt
@@ -0,0 +1,45 @@
+Aspeed SGPIO controller Device Tree Bindings
+--------------------------------------------
+
+This SGPIO controller is for ASPEED AST2500 SoC, it supports up to 80 full
+featured Serial GPIOs. Each of the Serial GPIO pins can be programmed to
+support the following options:
+- Support interrupt option for each input port and various interrupt
+ sensitivity option (level-high, level-low, edge-high, edge-low)
+- Support reset tolerance option for each output port
+- Directly connected to APB bus and its shift clock is from APB bus clock
+ divided by a programmable value.
+- Co-work with external signal-chained TTL components (74LV165/74LV595)
+
+Required properties:
+
+- compatible : Should be one of
+ "aspeed,ast2400-sgpio", "aspeed,ast2500-sgpio"
+- #gpio-cells : Should be 2, see gpio.txt
+- reg : Address and length of the register set for the device
+- gpio-controller : Marks the device node as a GPIO controller
+- interrupts : Interrupt specifier, see interrupt-controller/interrupts.txt
+- interrupt-controller : Mark the GPIO controller as an interrupt-controller
+- ngpios : number of GPIO lines, see gpio.txt
+ (should be multiple of 8, up to 80 pins)
+- clocks : A phandle to the APB clock for SGPM clock division
+- bus-frequency : SGPM CLK frequency
+
+The sgpio and interrupt properties are further described in their respective
+bindings documentation:
+
+- Documentation/devicetree/bindings/gpio/gpio.txt
+- Documentation/devicetree/bindings/interrupt-controller/interrupts.txt
+
+ Example:
+ sgpio: sgpio@1e780200 {
+ #gpio-cells = <2>;
+ compatible = "aspeed,ast2500-sgpio";
+ gpio-controller;
+ interrupts = <40>;
+ reg = <0x1e780200 0x0100>;
+ clocks = <&syscon ASPEED_CLK_APB>;
+ interrupt-controller;
+ ngpios = <8>;
+ bus-frequency = <12000000>;
+ };
diff --git a/Documentation/devicetree/bindings/gpu/arm,mali-bifrost.txt b/Documentation/devicetree/bindings/gpu/arm,mali-bifrost.txt
deleted file mode 100644
index b8be9db..0000000
--- a/Documentation/devicetree/bindings/gpu/arm,mali-bifrost.txt
+++ /dev/null
@@ -1,92 +0,0 @@
-ARM Mali Bifrost GPU
-====================
-
-Required properties:
-
-- compatible :
- * Since Mali Bifrost GPU model/revision is fully discoverable by reading
- some determined registers, must contain the following:
- + "arm,mali-bifrost"
- * which must be preceded by one of the following vendor specifics:
- + "amlogic,meson-g12a-mali"
-
-- reg : Physical base address of the device and length of the register area.
-
-- interrupts : Contains the three IRQ lines required by Mali Bifrost devices,
- in the following defined order.
-
-- interrupt-names : Contains the names of IRQ resources in this exact defined
- order: "job", "mmu", "gpu".
-
-Optional properties:
-
-- clocks : Phandle to clock for the Mali Bifrost device.
-
-- mali-supply : Phandle to regulator for the Mali device. Refer to
- Documentation/devicetree/bindings/regulator/regulator.txt for details.
-
-- operating-points-v2 : Refer to Documentation/devicetree/bindings/opp/opp.txt
- for details.
-
-- resets : Phandle of the GPU reset line.
-
-Vendor-specific bindings
-------------------------
-
-The Mali GPU is integrated very differently from one SoC to
-another. In order to accommodate those differences, you have the option
-to specify one more vendor-specific compatible, among:
-
-- "amlogic,meson-g12a-mali"
- Required properties:
- - resets : Should contain phandles of :
- + GPU reset line
- + GPU APB glue reset line
-
-Example for a Mali-G31:
-
-gpu@ffa30000 {
- compatible = "amlogic,meson-g12a-mali", "arm,mali-bifrost";
- reg = <0xffe40000 0x10000>;
- interrupts = <GIC_SPI 160 IRQ_TYPE_LEVEL_HIGH>,
- <GIC_SPI 161 IRQ_TYPE_LEVEL_HIGH>,
- <GIC_SPI 162 IRQ_TYPE_LEVEL_HIGH>;
- interrupt-names = "job", "mmu", "gpu";
- clocks = <&clk CLKID_MALI>;
- mali-supply = <&vdd_gpu>;
- operating-points-v2 = <&gpu_opp_table>;
- resets = <&reset RESET_DVALIN_CAPB3>, <&reset RESET_DVALIN>;
-};
-
-gpu_opp_table: opp_table0 {
- compatible = "operating-points-v2";
-
- opp@533000000 {
- opp-hz = /bits/ 64 <533000000>;
- opp-microvolt = <1250000>;
- };
- opp@450000000 {
- opp-hz = /bits/ 64 <450000000>;
- opp-microvolt = <1150000>;
- };
- opp@400000000 {
- opp-hz = /bits/ 64 <400000000>;
- opp-microvolt = <1125000>;
- };
- opp@350000000 {
- opp-hz = /bits/ 64 <350000000>;
- opp-microvolt = <1075000>;
- };
- opp@266000000 {
- opp-hz = /bits/ 64 <266000000>;
- opp-microvolt = <1025000>;
- };
- opp@160000000 {
- opp-hz = /bits/ 64 <160000000>;
- opp-microvolt = <925000>;
- };
- opp@100000000 {
- opp-hz = /bits/ 64 <100000000>;
- opp-microvolt = <912500>;
- };
-};
diff --git a/Documentation/devicetree/bindings/gpu/arm,mali-bifrost.yaml b/Documentation/devicetree/bindings/gpu/arm,mali-bifrost.yaml
new file mode 100644
index 0000000..5f1fd6d
--- /dev/null
+++ b/Documentation/devicetree/bindings/gpu/arm,mali-bifrost.yaml
@@ -0,0 +1,116 @@
+# SPDX-License-Identifier: GPL-2.0-only
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/gpu/arm,mali-bifrost.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: ARM Mali Bifrost GPU
+
+maintainers:
+ - Rob Herring <robh@kernel.org>
+
+properties:
+ $nodename:
+ pattern: '^gpu@[a-f0-9]+$'
+
+ compatible:
+ items:
+ - enum:
+ - amlogic,meson-g12a-mali
+ - const: arm,mali-bifrost # Mali Bifrost GPU model/revision is fully discoverable
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ items:
+ - description: Job interrupt
+ - description: MMU interrupt
+ - description: GPU interrupt
+
+ interrupt-names:
+ items:
+ - const: job
+ - const: mmu
+ - const: gpu
+
+ clocks:
+ maxItems: 1
+
+ mali-supply:
+ maxItems: 1
+
+ operating-points-v2: true
+
+required:
+ - compatible
+ - reg
+ - interrupts
+ - interrupt-names
+ - clocks
+
+allOf:
+ - if:
+ properties:
+ compatible:
+ contains:
+ const: amlogic,meson-g12a-mali
+ then:
+ properties:
+ resets:
+ minItems: 2
+ required:
+ - resets
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/irq.h>
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+
+ gpu@ffe40000 {
+ compatible = "amlogic,meson-g12a-mali", "arm,mali-bifrost";
+ reg = <0xffe40000 0x10000>;
+ interrupts = <GIC_SPI 160 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 161 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 162 IRQ_TYPE_LEVEL_HIGH>;
+ interrupt-names = "job", "mmu", "gpu";
+ clocks = <&clk 1>;
+ mali-supply = <&vdd_gpu>;
+ operating-points-v2 = <&gpu_opp_table>;
+ resets = <&reset 0>, <&reset 1>;
+ };
+
+ gpu_opp_table: opp_table0 {
+ compatible = "operating-points-v2";
+
+ opp@533000000 {
+ opp-hz = /bits/ 64 <533000000>;
+ opp-microvolt = <1250000>;
+ };
+ opp@450000000 {
+ opp-hz = /bits/ 64 <450000000>;
+ opp-microvolt = <1150000>;
+ };
+ opp@400000000 {
+ opp-hz = /bits/ 64 <400000000>;
+ opp-microvolt = <1125000>;
+ };
+ opp@350000000 {
+ opp-hz = /bits/ 64 <350000000>;
+ opp-microvolt = <1075000>;
+ };
+ opp@266000000 {
+ opp-hz = /bits/ 64 <266000000>;
+ opp-microvolt = <1025000>;
+ };
+ opp@160000000 {
+ opp-hz = /bits/ 64 <160000000>;
+ opp-microvolt = <925000>;
+ };
+ opp@100000000 {
+ opp-hz = /bits/ 64 <100000000>;
+ opp-microvolt = <912500>;
+ };
+ };
+
+...
diff --git a/Documentation/devicetree/bindings/gpu/arm,mali-midgard.txt b/Documentation/devicetree/bindings/gpu/arm,mali-midgard.txt
deleted file mode 100644
index 9b298ed..0000000
--- a/Documentation/devicetree/bindings/gpu/arm,mali-midgard.txt
+++ /dev/null
@@ -1,119 +0,0 @@
-ARM Mali Midgard GPU
-====================
-
-Required properties:
-
-- compatible :
- * Must contain one of the following:
- + "arm,mali-t604"
- + "arm,mali-t624"
- + "arm,mali-t628"
- + "arm,mali-t720"
- + "arm,mali-t760"
- + "arm,mali-t820"
- + "arm,mali-t830"
- + "arm,mali-t860"
- + "arm,mali-t880"
- * which must be preceded by one of the following vendor specifics:
- + "allwinner,sun50i-h6-mali"
- + "amlogic,meson-gxm-mali"
- + "samsung,exynos5433-mali"
- + "rockchip,rk3288-mali"
- + "rockchip,rk3399-mali"
-
-- reg : Physical base address of the device and length of the register area.
-
-- interrupts : Contains the three IRQ lines required by Mali Midgard devices.
-
-- interrupt-names : Contains the names of IRQ resources in the order they were
- provided in the interrupts property. Must contain: "job", "mmu", "gpu".
-
-
-Optional properties:
-
-- clocks : Phandle to clock for the Mali Midgard device.
-
-- clock-names : Specify the names of the clocks specified in clocks
- when multiple clocks are present.
- * core: clock driving the GPU itself (When only one clock is present,
- assume it's this clock.)
- * bus: bus clock for the GPU
-
-- mali-supply : Phandle to regulator for the Mali device. Refer to
- Documentation/devicetree/bindings/regulator/regulator.txt for details.
-
-- operating-points-v2 : Refer to Documentation/devicetree/bindings/opp/opp.txt
- for details.
-
-- #cooling-cells: Refer to Documentation/devicetree/bindings/thermal/thermal.txt
- for details.
-
-- resets : Phandle of the GPU reset line.
-
-Vendor-specific bindings
-------------------------
-
-The Mali GPU is integrated very differently from one SoC to
-another. In order to accommodate those differences, you have the option
-to specify one more vendor-specific compatible, among:
-
-- "allwinner,sun50i-h6-mali"
- Required properties:
- - clocks : phandles to core and bus clocks
- - clock-names : must contain "core" and "bus"
- - resets: phandle to GPU reset line
-
-- "amlogic,meson-gxm-mali"
- Required properties:
- - resets : Should contain phandles of :
- + GPU reset line
- + GPU APB glue reset line
-
-Example for a Mali-T760:
-
-gpu@ffa30000 {
- compatible = "rockchip,rk3288-mali", "arm,mali-t760";
- reg = <0xffa30000 0x10000>;
- interrupts = <GIC_SPI 6 IRQ_TYPE_LEVEL_HIGH>,
- <GIC_SPI 7 IRQ_TYPE_LEVEL_HIGH>,
- <GIC_SPI 8 IRQ_TYPE_LEVEL_HIGH>;
- interrupt-names = "job", "mmu", "gpu";
- clocks = <&cru ACLK_GPU>;
- mali-supply = <&vdd_gpu>;
- operating-points-v2 = <&gpu_opp_table>;
- power-domains = <&power RK3288_PD_GPU>;
- #cooling-cells = <2>;
-};
-
-gpu_opp_table: opp_table0 {
- compatible = "operating-points-v2";
-
- opp@533000000 {
- opp-hz = /bits/ 64 <533000000>;
- opp-microvolt = <1250000>;
- };
- opp@450000000 {
- opp-hz = /bits/ 64 <450000000>;
- opp-microvolt = <1150000>;
- };
- opp@400000000 {
- opp-hz = /bits/ 64 <400000000>;
- opp-microvolt = <1125000>;
- };
- opp@350000000 {
- opp-hz = /bits/ 64 <350000000>;
- opp-microvolt = <1075000>;
- };
- opp@266000000 {
- opp-hz = /bits/ 64 <266000000>;
- opp-microvolt = <1025000>;
- };
- opp@160000000 {
- opp-hz = /bits/ 64 <160000000>;
- opp-microvolt = <925000>;
- };
- opp@100000000 {
- opp-hz = /bits/ 64 <100000000>;
- opp-microvolt = <912500>;
- };
-};
diff --git a/Documentation/devicetree/bindings/gpu/arm,mali-midgard.yaml b/Documentation/devicetree/bindings/gpu/arm,mali-midgard.yaml
new file mode 100644
index 0000000..47bc1ac
--- /dev/null
+++ b/Documentation/devicetree/bindings/gpu/arm,mali-midgard.yaml
@@ -0,0 +1,168 @@
+# SPDX-License-Identifier: GPL-2.0-only
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/gpu/arm,mali-midgard.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: ARM Mali Midgard GPU
+
+maintainers:
+ - Rob Herring <robh@kernel.org>
+
+properties:
+ $nodename:
+ pattern: '^gpu@[a-f0-9]+$'
+ compatible:
+ oneOf:
+ - items:
+ - enum:
+ - allwinner,sun50i-h6-mali
+ - const: arm,mali-t720
+ - items:
+ - enum:
+ - amlogic,meson-gxm-mali
+ - const: arm,mali-t820
+ - items:
+ - enum:
+ - rockchip,rk3288-mali
+ - const: arm,mali-t760
+ - items:
+ - enum:
+ - rockchip,rk3399-mali
+ - const: arm,mali-t860
+ - items:
+ - enum:
+ - samsung,exynos5250-mali
+ - const: arm,mali-t604
+ - items:
+ - enum:
+ - samsung,exynos5433-mali
+ - const: arm,mali-t760
+
+ # "arm,mali-t624"
+ # "arm,mali-t628"
+ # "arm,mali-t830"
+ # "arm,mali-t880"
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ items:
+ - description: Job interrupt
+ - description: MMU interrupt
+ - description: GPU interrupt
+
+ interrupt-names:
+ items:
+ - const: job
+ - const: mmu
+ - const: gpu
+
+ clocks:
+ minItems: 1
+ maxItems: 2
+
+ clock-names:
+ minItems: 1
+ items:
+ - const: core
+ - const: bus
+
+ mali-supply:
+ maxItems: 1
+
+ resets:
+ minItems: 1
+ maxItems: 2
+
+ operating-points-v2: true
+
+ "#cooling-cells":
+ const: 2
+
+required:
+ - compatible
+ - reg
+ - interrupts
+ - interrupt-names
+ - clocks
+
+allOf:
+ - if:
+ properties:
+ compatible:
+ contains:
+ const: allwinner,sun50i-h6-mali
+ then:
+ properties:
+ clocks:
+ minItems: 2
+ required:
+ - clock-names
+ - resets
+ - if:
+ properties:
+ compatible:
+ contains:
+ const: amlogic,meson-gxm-mali
+ then:
+ properties:
+ resets:
+ minItems: 2
+ required:
+ - resets
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/irq.h>
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+
+ gpu@ffa30000 {
+ compatible = "rockchip,rk3288-mali", "arm,mali-t760";
+ reg = <0xffa30000 0x10000>;
+ interrupts = <GIC_SPI 6 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 7 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 8 IRQ_TYPE_LEVEL_HIGH>;
+ interrupt-names = "job", "mmu", "gpu";
+ clocks = <&cru 0>;
+ mali-supply = <&vdd_gpu>;
+ operating-points-v2 = <&gpu_opp_table>;
+ power-domains = <&power 0>;
+ #cooling-cells = <2>;
+ };
+
+ gpu_opp_table: opp_table0 {
+ compatible = "operating-points-v2";
+
+ opp@533000000 {
+ opp-hz = /bits/ 64 <533000000>;
+ opp-microvolt = <1250000>;
+ };
+ opp@450000000 {
+ opp-hz = /bits/ 64 <450000000>;
+ opp-microvolt = <1150000>;
+ };
+ opp@400000000 {
+ opp-hz = /bits/ 64 <400000000>;
+ opp-microvolt = <1125000>;
+ };
+ opp@350000000 {
+ opp-hz = /bits/ 64 <350000000>;
+ opp-microvolt = <1075000>;
+ };
+ opp@266000000 {
+ opp-hz = /bits/ 64 <266000000>;
+ opp-microvolt = <1025000>;
+ };
+ opp@160000000 {
+ opp-hz = /bits/ 64 <160000000>;
+ opp-microvolt = <925000>;
+ };
+ opp@100000000 {
+ opp-hz = /bits/ 64 <100000000>;
+ opp-microvolt = <912500>;
+ };
+ };
+
+...
diff --git a/Documentation/devicetree/bindings/gpu/arm,mali-utgard.txt b/Documentation/devicetree/bindings/gpu/arm,mali-utgard.txt
deleted file mode 100644
index b352a68..0000000
--- a/Documentation/devicetree/bindings/gpu/arm,mali-utgard.txt
+++ /dev/null
@@ -1,124 +0,0 @@
-ARM Mali Utgard GPU
-===================
-
-Required properties:
- - compatible
- * Must be one of the following:
- + "arm,mali-300"
- + "arm,mali-400"
- + "arm,mali-450"
- * And, optionally, one of the vendor specific compatible:
- + allwinner,sun4i-a10-mali
- + allwinner,sun7i-a20-mali
- + allwinner,sun8i-h3-mali
- + allwinner,sun50i-a64-mali
- + allwinner,sun50i-h5-mali
- + amlogic,meson8-mali
- + amlogic,meson8b-mali
- + amlogic,meson-gxbb-mali
- + amlogic,meson-gxl-mali
- + samsung,exynos4210-mali
- + rockchip,rk3036-mali
- + rockchip,rk3066-mali
- + rockchip,rk3188-mali
- + rockchip,rk3228-mali
- + rockchip,rk3328-mali
- + stericsson,db8500-mali
-
- - reg: Physical base address and length of the GPU registers
-
- - interrupts: an entry for each entry in interrupt-names.
- See ../interrupt-controller/interrupts.txt for details.
-
- - interrupt-names:
- * ppX: Pixel Processor X interrupt (X from 0 to 7)
- * ppmmuX: Pixel Processor X MMU interrupt (X from 0 to 7)
- * pp: Pixel Processor broadcast interrupt (mali-450 only)
- * gp: Geometry Processor interrupt
- * gpmmu: Geometry Processor MMU interrupt
-
- - clocks: an entry for each entry in clock-names
- - clock-names:
- * bus: bus clock for the GPU
- * core: clock driving the GPU itself
-
-Optional properties:
- - interrupt-names and interrupts:
- * pmu: Power Management Unit interrupt, if implemented in hardware
-
- - memory-region:
- Memory region to allocate from, as defined in
- Documentation/devicetree/bindings/reserved-memory/reserved-memory.txt
-
- - mali-supply:
- Phandle to regulator for the Mali device, as defined in
- Documentation/devicetree/bindings/regulator/regulator.txt for details.
-
- - operating-points-v2:
- Operating Points for the GPU, as defined in
- Documentation/devicetree/bindings/opp/opp.txt
-
- - power-domains:
- A power domain consumer specifier as defined in
- Documentation/devicetree/bindings/power/power_domain.txt
-
-Vendor-specific bindings
-------------------------
-
-The Mali GPU is integrated very differently from one SoC to
-another. In order to accomodate those differences, you have the option
-to specify one more vendor-specific compatible, among:
-
- - allwinner,sun4i-a10-mali
- Required properties:
- * resets: phandle to the reset line for the GPU
-
- - allwinner,sun7i-a20-mali
- Required properties:
- * resets: phandle to the reset line for the GPU
-
- - allwinner,sun50i-a64-mali
- Required properties:
- * resets: phandle to the reset line for the GPU
-
- - allwinner,sun50i-h5-mali
- Required properties:
- * resets: phandle to the reset line for the GPU
-
- - amlogic,meson8-mali and amlogic,meson8b-mali
- Required properties:
- * resets: phandle to the reset line for the GPU
-
- - Rockchip variants:
- Required properties:
- * resets: phandle to the reset line for the GPU
-
- - stericsson,db8500-mali
- Required properties:
- * interrupt-names and interrupts:
- + combined: combined interrupt of all of the above lines
-
-Example:
-
-mali: gpu@1c40000 {
- compatible = "allwinner,sun7i-a20-mali", "arm,mali-400";
- reg = <0x01c40000 0x10000>;
- interrupts = <GIC_SPI 97 IRQ_TYPE_LEVEL_HIGH>,
- <GIC_SPI 98 IRQ_TYPE_LEVEL_HIGH>,
- <GIC_SPI 99 IRQ_TYPE_LEVEL_HIGH>,
- <GIC_SPI 100 IRQ_TYPE_LEVEL_HIGH>,
- <GIC_SPI 102 IRQ_TYPE_LEVEL_HIGH>,
- <GIC_SPI 103 IRQ_TYPE_LEVEL_HIGH>,
- <GIC_SPI 101 IRQ_TYPE_LEVEL_HIGH>;
- interrupt-names = "gp",
- "gpmmu",
- "pp0",
- "ppmmu0",
- "pp1",
- "ppmmu1",
- "pmu";
- clocks = <&ccu CLK_BUS_GPU>, <&ccu CLK_GPU>;
- clock-names = "bus", "core";
- resets = <&ccu RST_BUS_GPU>;
-};
-
diff --git a/Documentation/devicetree/bindings/gpu/arm,mali-utgard.yaml b/Documentation/devicetree/bindings/gpu/arm,mali-utgard.yaml
new file mode 100644
index 0000000..c5d93c5
--- /dev/null
+++ b/Documentation/devicetree/bindings/gpu/arm,mali-utgard.yaml
@@ -0,0 +1,168 @@
+# SPDX-License-Identifier: GPL-2.0-only
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/gpu/arm,mali-utgard.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: ARM Mali Utgard GPU
+
+maintainers:
+ - Rob Herring <robh@kernel.org>
+ - Maxime Ripard <maxime.ripard@free-electrons.com>
+ - Heiko Stuebner <heiko@sntech.de>
+
+properties:
+ $nodename:
+ pattern: '^gpu@[a-f0-9]+$'
+ compatible:
+ oneOf:
+ - items:
+ - const: allwinner,sun8i-a23-mali
+ - const: allwinner,sun7i-a20-mali
+ - const: arm,mali-400
+ - items:
+ - enum:
+ - allwinner,sun4i-a10-mali
+ - allwinner,sun7i-a20-mali
+ - allwinner,sun8i-h3-mali
+ - allwinner,sun50i-a64-mali
+ - rockchip,rk3036-mali
+ - rockchip,rk3066-mali
+ - rockchip,rk3188-mali
+ - rockchip,rk3228-mali
+ - samsung,exynos4210-mali
+ - stericsson,db8500-mali
+ - const: arm,mali-400
+ - items:
+ - enum:
+ - allwinner,sun50i-h5-mali
+ - amlogic,meson8-mali
+ - amlogic,meson8b-mali
+ - amlogic,meson-gxbb-mali
+ - amlogic,meson-gxl-mali
+ - hisilicon,hi6220-mali
+ - rockchip,rk3328-mali
+ - const: arm,mali-450
+
+ # "arm,mali-300"
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ minItems: 4
+ maxItems: 20
+
+ interrupt-names:
+ allOf:
+ - additionalItems: true
+ minItems: 4
+ maxItems: 20
+ items:
+ # At least enforce the first 2 interrupts
+ - const: gp
+ - const: gpmmu
+ - items:
+ # Not ideal as any order and combination are allowed
+ enum:
+ - gp # Geometry Processor interrupt
+ - gpmmu # Geometry Processor MMU interrupt
+ - pp # Pixel Processor broadcast interrupt (mali-450 only)
+ - pp0 # Pixel Processor X interrupt (X from 0 to 7)
+ - ppmmu0 # Pixel Processor X MMU interrupt (X from 0 to 7)
+ - pp1
+ - ppmmu1
+ - pp2
+ - ppmmu2
+ - pp3
+ - ppmmu3
+ - pp4
+ - ppmmu4
+ - pp5
+ - ppmmu5
+ - pp6
+ - ppmmu6
+ - pp7
+ - ppmmu7
+ - pmu # Power Management Unit interrupt (optional)
+ - combined # stericsson,db8500-mali only
+
+ clocks:
+ maxItems: 2
+
+ clock-names:
+ items:
+ - const: bus
+ - const: core
+
+ memory-region: true
+
+ mali-supply:
+ maxItems: 1
+
+ power-domains:
+ maxItems: 1
+
+ resets:
+ maxItems: 1
+
+ operating-points-v2: true
+
+required:
+ - compatible
+ - reg
+ - interrupts
+ - interrupt-names
+ - clocks
+ - clock-names
+
+allOf:
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - allwinner,sun4i-a10-mali
+ - allwinner,sun7i-a20-mali
+ - allwinner,sun50i-a64-mali
+ - allwinner,sun50i-h5-mali
+ - amlogic,meson8-mali
+ - amlogic,meson8b-mali
+ - hisilicon,hi6220-mali
+ - rockchip,rk3036-mali
+ - rockchip,rk3066-mali
+ - rockchip,rk3188-mali
+ - rockchip,rk3228-mali
+ - rockchip,rk3328-mali
+ then:
+ required:
+ - resets
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/irq.h>
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+
+ mali: gpu@1c40000 {
+ compatible = "allwinner,sun7i-a20-mali", "arm,mali-400";
+ reg = <0x01c40000 0x10000>;
+ interrupts = <GIC_SPI 97 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 98 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 99 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 100 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 102 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 103 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 101 IRQ_TYPE_LEVEL_HIGH>;
+ interrupt-names = "gp",
+ "gpmmu",
+ "pp0",
+ "ppmmu0",
+ "pp1",
+ "ppmmu1",
+ "pmu";
+ clocks = <&ccu 1>, <&ccu 2>;
+ clock-names = "bus", "core";
+ resets = <&ccu 1>;
+ };
+
+...
diff --git a/Documentation/devicetree/bindings/hwmon/as370.txt b/Documentation/devicetree/bindings/hwmon/as370.txt
new file mode 100644
index 0000000..d102fe76
--- /dev/null
+++ b/Documentation/devicetree/bindings/hwmon/as370.txt
@@ -0,0 +1,11 @@
+Bindings for Synaptics AS370 PVT sensors
+
+Required properties:
+- compatible : "syna,as370-hwmon"
+- reg : address and length of the register set.
+
+Example:
+ hwmon@ea0810 {
+ compatible = "syna,as370-hwmon";
+ reg = <0xea0810 0xc>;
+ };
diff --git a/Documentation/devicetree/bindings/hwmon/ibm,cffps1.txt b/Documentation/devicetree/bindings/hwmon/ibm,cffps1.txt
index f68a0a6..1036f65 100644
--- a/Documentation/devicetree/bindings/hwmon/ibm,cffps1.txt
+++ b/Documentation/devicetree/bindings/hwmon/ibm,cffps1.txt
@@ -1,8 +1,10 @@
-Device-tree bindings for IBM Common Form Factor Power Supply Version 1
-----------------------------------------------------------------------
+Device-tree bindings for IBM Common Form Factor Power Supply Versions 1 and 2
+-----------------------------------------------------------------------------
Required properties:
- - compatible = "ibm,cffps1";
+ - compatible : Must be one of the following:
+ "ibm,cffps1"
+ "ibm,cffps2"
- reg = < I2C bus address >; : Address of the power supply on the
I2C bus.
diff --git a/Documentation/devicetree/bindings/hwmon/lm75.txt b/Documentation/devicetree/bindings/hwmon/lm75.txt
index 586b5ed7..2736167 100644
--- a/Documentation/devicetree/bindings/hwmon/lm75.txt
+++ b/Documentation/devicetree/bindings/hwmon/lm75.txt
@@ -15,6 +15,7 @@
"maxim,max31725",
"maxim,max31726",
"maxim,mcp980x",
+ "nxp,pct2075",
"st,stds75",
"st,stlm75",
"microchip,tcn75",
diff --git a/Documentation/devicetree/bindings/i2c/brcm,bcm2835-i2c.txt b/Documentation/devicetree/bindings/i2c/brcm,bcm2835-i2c.txt
index e9de375..c9a6587 100644
--- a/Documentation/devicetree/bindings/i2c/brcm,bcm2835-i2c.txt
+++ b/Documentation/devicetree/bindings/i2c/brcm,bcm2835-i2c.txt
@@ -1,7 +1,9 @@
Broadcom BCM2835 I2C controller
Required properties:
-- compatible : Should be "brcm,bcm2835-i2c".
+- compatible : Should be one of:
+ "brcm,bcm2711-i2c"
+ "brcm,bcm2835-i2c"
- reg: Should contain register location and length.
- interrupts: Should contain interrupt.
- clocks : The clock feeding the I2C controller.
diff --git a/Documentation/devicetree/bindings/i2c/i2c-mux-gpmux.txt b/Documentation/devicetree/bindings/i2c/i2c-mux-gpmux.txt
index 2907dab..8b444b9 100644
--- a/Documentation/devicetree/bindings/i2c/i2c-mux-gpmux.txt
+++ b/Documentation/devicetree/bindings/i2c/i2c-mux-gpmux.txt
@@ -42,7 +42,7 @@
This means that no unrelated I2C transactions are allowed on the parent I2C
adapter for the complete multiplexed I2C transaction.
The properties of mux-locked and parent-locked multiplexers are discussed
- in more detail in Documentation/i2c/i2c-topology.
+ in more detail in Documentation/i2c/i2c-topology.rst.
For each i2c child node, an I2C child bus will be created. They will
be numbered based on their order in the device tree.
diff --git a/Documentation/devicetree/bindings/i2c/marvell,mv64xxx-i2c.yaml b/Documentation/devicetree/bindings/i2c/marvell,mv64xxx-i2c.yaml
index 001f2b7..c779000 100644
--- a/Documentation/devicetree/bindings/i2c/marvell,mv64xxx-i2c.yaml
+++ b/Documentation/devicetree/bindings/i2c/marvell,mv64xxx-i2c.yaml
@@ -26,6 +26,9 @@
- items:
- const: allwinner,sun50i-a64-i2c
- const: allwinner,sun6i-a31-i2c
+ - items:
+ - const: allwinner,sun50i-h6-i2c
+ - const: allwinner,sun6i-a31-i2c
- const: marvell,mv64xxx-i2c
- const: marvell,mv78230-i2c
diff --git a/Documentation/devicetree/bindings/i2c/i2c-rcar.txt b/Documentation/devicetree/bindings/i2c/renesas,i2c.txt
similarity index 100%
rename from Documentation/devicetree/bindings/i2c/i2c-rcar.txt
rename to Documentation/devicetree/bindings/i2c/renesas,i2c.txt
diff --git a/Documentation/devicetree/bindings/i2c/i2c-emev2.txt b/Documentation/devicetree/bindings/i2c/renesas,iic-emev2.txt
similarity index 100%
rename from Documentation/devicetree/bindings/i2c/i2c-emev2.txt
rename to Documentation/devicetree/bindings/i2c/renesas,iic-emev2.txt
diff --git a/Documentation/devicetree/bindings/i2c/i2c-sh_mobile.txt b/Documentation/devicetree/bindings/i2c/renesas,iic.txt
similarity index 100%
rename from Documentation/devicetree/bindings/i2c/i2c-sh_mobile.txt
rename to Documentation/devicetree/bindings/i2c/renesas,iic.txt
diff --git a/Documentation/devicetree/bindings/i2c/i2c-riic.txt b/Documentation/devicetree/bindings/i2c/renesas,riic.txt
similarity index 100%
rename from Documentation/devicetree/bindings/i2c/i2c-riic.txt
rename to Documentation/devicetree/bindings/i2c/renesas,riic.txt
diff --git a/Documentation/devicetree/bindings/iio/adc/adi,ad7192.yaml b/Documentation/devicetree/bindings/iio/adc/adi,ad7192.yaml
new file mode 100644
index 0000000..676ec42
--- /dev/null
+++ b/Documentation/devicetree/bindings/iio/adc/adi,ad7192.yaml
@@ -0,0 +1,121 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+# Copyright 2019 Analog Devices Inc.
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/bindings/iio/adc/adi,ad7192.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Analog Devices AD7192 ADC device driver
+
+maintainers:
+ - Michael Hennerich <michael.hennerich@analog.com>
+
+description: |
+ Bindings for the Analog Devices AD7192 ADC device. Datasheet can be
+ found here:
+ https://www.analog.com/media/en/technical-documentation/data-sheets/AD7192.pdf
+
+properties:
+ compatible:
+ enum:
+ - adi,ad7190
+ - adi,ad7192
+ - adi,ad7193
+ - adi,ad7195
+
+ reg:
+ maxItems: 1
+
+ spi-cpol: true
+
+ spi-cpha: true
+
+ clocks:
+ maxItems: 1
+ description: phandle to the master clock (mclk)
+
+ clock-names:
+ items:
+ - const: mclk
+
+ interrupts:
+ maxItems: 1
+
+ dvdd-supply:
+ description: DVdd voltage supply
+ items:
+ - const: dvdd
+
+ avdd-supply:
+ description: AVdd voltage supply
+ items:
+ - const: avdd
+
+ adi,rejection-60-Hz-enable:
+ description: |
+ This bit enables a notch at 60 Hz when the first notch of the sinc
+ filter is at 50 Hz. When REJ60 is set, a filter notch is placed at
+ 60 Hz when the sinc filter first notch is at 50 Hz. This allows
+ simultaneous 50 Hz/ 60 Hz rejection.
+ type: boolean
+
+ adi,refin2-pins-enable:
+ description: |
+ External reference applied between the P1/REFIN2(+) and P0/REFIN2(−) pins.
+ type: boolean
+
+ adi,buffer-enable:
+ description: |
+ Enables the buffer on the analog inputs. If cleared, the analog inputs
+ are unbuffered, lowering the power consumption of the device. If this
+ bit is set, the analog inputs are buffered, allowing the user to place
+ source impedances on the front end without contributing gain errors to
+ the system.
+ type: boolean
+
+ adi,burnout-currents-enable:
+ description: |
+ When this bit is set to 1, the 500 nA current sources in the signal
+ path are enabled. When BURN = 0, the burnout currents are disabled.
+ The burnout currents can be enabled only when the buffer is active
+ and when chop is disabled.
+ type: boolean
+
+ bipolar:
+ description: see Documentation/devicetree/bindings/iio/adc/adc.txt
+ type: boolean
+
+required:
+ - compatible
+ - reg
+ - clocks
+ - clock-names
+ - interrupts
+ - dvdd-supply
+ - avdd-supply
+ - spi-cpol
+ - spi-cpha
+
+examples:
+ - |
+ spi0 {
+ adc@0 {
+ compatible = "adi,ad7192";
+ reg = <0>;
+ spi-max-frequency = <1000000>;
+ spi-cpol;
+ spi-cpha;
+ clocks = <&ad7192_mclk>;
+ clock-names = "mclk";
+ #interrupt-cells = <2>;
+ interrupts = <25 0x2>;
+ interrupt-parent = <&gpio>;
+ dvdd-supply = <&dvdd>;
+ avdd-supply = <&avdd>;
+
+ adi,refin2-pins-enable;
+ adi,rejection-60-Hz-enable;
+ adi,buffer-enable;
+ adi,burnout-currents-enable;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/iio/adc/adi,ad7606.txt b/Documentation/devicetree/bindings/iio/adc/adi,ad7606.txt
deleted file mode 100644
index d865246..0000000
--- a/Documentation/devicetree/bindings/iio/adc/adi,ad7606.txt
+++ /dev/null
@@ -1,66 +0,0 @@
-Analog Devices AD7606 Simultaneous Sampling ADC
-
-Required properties for the AD7606:
-
-- compatible: Must be one of
- * "adi,ad7605-4"
- * "adi,ad7606-8"
- * "adi,ad7606-6"
- * "adi,ad7606-4"
- * "adi,ad7616"
-- reg: SPI chip select number for the device
-- spi-max-frequency: Max SPI frequency to use
- see: Documentation/devicetree/bindings/spi/spi-bus.txt
-- spi-cpha: See Documentation/devicetree/bindings/spi/spi-bus.txt
-- avcc-supply: phandle to the Avcc power supply
-- interrupts: IRQ line for the ADC
- see: Documentation/devicetree/bindings/interrupt-controller/interrupts.txt
-- adi,conversion-start-gpios: must be the device tree identifier of the CONVST pin.
- This logic input is used to initiate conversions on the analog
- input channels. As the line is active high, it should be marked
- GPIO_ACTIVE_HIGH.
-
-Optional properties:
-
-- reset-gpios: must be the device tree identifier of the RESET pin. If specified,
- it will be asserted during driver probe. As the line is active high,
- it should be marked GPIO_ACTIVE_HIGH.
-- standby-gpios: must be the device tree identifier of the STBY pin. This pin is used
- to place the AD7606 into one of two power-down modes, Standby mode or
- Shutdown mode. As the line is active low, it should be marked
- GPIO_ACTIVE_LOW.
-- adi,first-data-gpios: must be the device tree identifier of the FRSTDATA pin.
- The FRSTDATA output indicates when the first channel, V1, is
- being read back on either the parallel, byte or serial interface.
- As the line is active high, it should be marked GPIO_ACTIVE_HIGH.
-- adi,range-gpios: must be the device tree identifier of the RANGE pin. The polarity on
- this pin determines the input range of the analog input channels. If
- this pin is tied to a logic high, the analog input range is ±10V for
- all channels. If this pin is tied to a logic low, the analog input range
- is ±5V for all channels. As the line is active high, it should be marked
- GPIO_ACTIVE_HIGH.
-- adi,oversampling-ratio-gpios: must be the device tree identifier of the over-sampling
- mode pins. As the line is active high, it should be marked
- GPIO_ACTIVE_HIGH.
-
-Example:
-
- adc@0 {
- compatible = "adi,ad7606-8";
- reg = <0>;
- spi-max-frequency = <1000000>;
- spi-cpol;
-
- avcc-supply = <&adc_vref>;
-
- interrupts = <25 IRQ_TYPE_EDGE_FALLING>;
- interrupt-parent = <&gpio>;
-
- adi,conversion-start-gpios = <&gpio 17 GPIO_ACTIVE_HIGH>;
- reset-gpios = <&gpio 27 GPIO_ACTIVE_HIGH>;
- adi,first-data-gpios = <&gpio 22 GPIO_ACTIVE_HIGH>;
- adi,oversampling-ratio-gpios = <&gpio 18 GPIO_ACTIVE_HIGH
- &gpio 23 GPIO_ACTIVE_HIGH
- &gpio 26 GPIO_ACTIVE_HIGH>;
- standby-gpios = <&gpio 24 GPIO_ACTIVE_LOW>;
- };
diff --git a/Documentation/devicetree/bindings/iio/adc/adi,ad7606.yaml b/Documentation/devicetree/bindings/iio/adc/adi,ad7606.yaml
new file mode 100644
index 0000000..cc544fd
--- /dev/null
+++ b/Documentation/devicetree/bindings/iio/adc/adi,ad7606.yaml
@@ -0,0 +1,138 @@
+# SPDX-License-Identifier: GPL-2.0
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iio/adc/adi,ad7606.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Analog Devices AD7606 Simultaneous Sampling ADC
+
+maintainers:
+ - Beniamin Bia <beniamin.bia@analog.com>
+ - Stefan Popa <stefan.popa@analog.com>
+
+description: |
+ Analog Devices AD7606 Simultaneous Sampling ADC
+ https://www.analog.com/media/en/technical-documentation/data-sheets/ad7606_7606-6_7606-4.pdf
+ https://www.analog.com/media/en/technical-documentation/data-sheets/AD7606B.pdf
+ https://www.analog.com/media/en/technical-documentation/data-sheets/AD7616.pdf
+
+properties:
+ compatible:
+ enum:
+ - adi,ad7605-4
+ - adi,ad7606-8
+ - adi,ad7606-6
+ - adi,ad7606-4
+ - adi,ad7606b
+ - adi,ad7616
+
+ reg:
+ maxItems: 1
+
+ spi-cpha: true
+
+ avcc-supply:
+ description:
+ Phandle to the Avcc power supply
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+ adi,conversion-start-gpios:
+ description:
+ Must be the device tree identifier of the CONVST pin.
+ This logic input is used to initiate conversions on the analog
+ input channels. As the line is active high, it should be marked
+ GPIO_ACTIVE_HIGH.
+ maxItems: 1
+
+ reset-gpios:
+ description:
+ Must be the device tree identifier of the RESET pin. If specified,
+ it will be asserted during driver probe. As the line is active high,
+ it should be marked GPIO_ACTIVE_HIGH.
+ maxItems: 1
+
+ standby-gpios:
+ description:
+ Must be the device tree identifier of the STBY pin. This pin is used
+ to place the AD7606 into one of two power-down modes, Standby mode or
+ Shutdown mode. As the line is active low, it should be marked
+ GPIO_ACTIVE_LOW.
+ maxItems: 1
+
+ adi,first-data-gpios:
+ description:
+ Must be the device tree identifier of the FRSTDATA pin.
+ The FRSTDATA output indicates when the first channel, V1, is
+ being read back on either the parallel, byte or serial interface.
+ As the line is active high, it should be marked GPIO_ACTIVE_HIGH.
+ maxItems: 1
+
+ adi,range-gpios:
+ description:
+ Must be the device tree identifier of the RANGE pin. The polarity on
+ this pin determines the input range of the analog input channels. If
+ this pin is tied to a logic high, the analog input range is ±10V for
+ all channels. If this pin is tied to a logic low, the analog input range
+ is ±5V for all channels. As the line is active high, it should be marked
+ GPIO_ACTIVE_HIGH.
+ maxItems: 1
+
+ adi,oversampling-ratio-gpios:
+ description:
+ Must be the device tree identifier of the over-sampling
+ mode pins. As the line is active high, it should be marked
+ GPIO_ACTIVE_HIGH.
+ maxItems: 1
+
+ adi,sw-mode:
+ description:
+ Software mode of operation, so far available only for ad7616 and ad7606b.
+ It is enabled when all three oversampling mode pins are connected to
+ high level. The device is configured by the corresponding registers. If the
+ adi,oversampling-ratio-gpios property is defined, then the driver will set the
+ oversampling gpios to high. Otherwise, it is assumed that the pins are hardwired
+ to VDD.
+ type: boolean
+
+required:
+ - compatible
+ - reg
+ - spi-cpha
+ - avcc-supply
+ - interrupts
+ - adi,conversion-start-gpios
+
+examples:
+ - |
+ #include <dt-bindings/gpio/gpio.h>
+ #include <dt-bindings/interrupt-controller/irq.h>
+ spi0 {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ adc@0 {
+ compatible = "adi,ad7606-8";
+ reg = <0>;
+ spi-max-frequency = <1000000>;
+ spi-cpol;
+ spi-cpha;
+
+ avcc-supply = <&adc_vref>;
+
+ interrupts = <25 IRQ_TYPE_EDGE_FALLING>;
+ interrupt-parent = <&gpio>;
+
+ adi,conversion-start-gpios = <&gpio 17 GPIO_ACTIVE_HIGH>;
+ reset-gpios = <&gpio 27 GPIO_ACTIVE_HIGH>;
+ adi,first-data-gpios = <&gpio 22 GPIO_ACTIVE_HIGH>;
+ adi,oversampling-ratio-gpios = <&gpio 18 GPIO_ACTIVE_HIGH
+ &gpio 23 GPIO_ACTIVE_HIGH
+ &gpio 26 GPIO_ACTIVE_HIGH>;
+ standby-gpios = <&gpio 24 GPIO_ACTIVE_LOW>;
+ adi,sw-mode;
+ };
+ };
+...
diff --git a/Documentation/devicetree/bindings/hwmon/ads1015.txt b/Documentation/devicetree/bindings/iio/adc/ads1015.txt
similarity index 100%
rename from Documentation/devicetree/bindings/hwmon/ads1015.txt
rename to Documentation/devicetree/bindings/iio/adc/ads1015.txt
diff --git a/Documentation/devicetree/bindings/iio/adc/allwinner,sun8i-a33-ths.yaml b/Documentation/devicetree/bindings/iio/adc/allwinner,sun8i-a33-ths.yaml
new file mode 100644
index 0000000..d74962c
--- /dev/null
+++ b/Documentation/devicetree/bindings/iio/adc/allwinner,sun8i-a33-ths.yaml
@@ -0,0 +1,43 @@
+# SPDX-License-Identifier: GPL-2.0
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iio/adc/allwinner,sun8i-a33-ths.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Allwinner A33 Thermal Sensor Device Tree Bindings
+
+maintainers:
+ - Chen-Yu Tsai <wens@csie.org>
+ - Maxime Ripard <maxime.ripard@bootlin.com>
+
+properties:
+ "#io-channel-cells":
+ const: 0
+
+ "#thermal-sensor-cells":
+ const: 0
+
+ compatible:
+ const: allwinner,sun8i-a33-ths
+
+ reg:
+ maxItems: 1
+
+required:
+ - "#io-channel-cells"
+ - "#thermal-sensor-cells"
+ - compatible
+ - reg
+
+additionalProperties: false
+
+examples:
+ - |
+ ths: ths@1c25000 {
+ compatible = "allwinner,sun8i-a33-ths";
+ reg = <0x01c25000 0x100>;
+ #thermal-sensor-cells = <0>;
+ #io-channel-cells = <0>;
+ };
+
+...
diff --git a/Documentation/devicetree/bindings/iio/adc/st,stm32-adc.txt b/Documentation/devicetree/bindings/iio/adc/st,stm32-adc.txt
index 93a0bd2..4c0da8c 100644
--- a/Documentation/devicetree/bindings/iio/adc/st,stm32-adc.txt
+++ b/Documentation/devicetree/bindings/iio/adc/st,stm32-adc.txt
@@ -47,6 +47,12 @@
Optional properties:
- A pinctrl state named "default" for each ADC channel may be defined to set
inX ADC pins in mode of operation for analog input on external pin.
+- booster-supply: Phandle to the embedded booster regulator that can be used
+ to supply ADC analog input switches on stm32h7 and stm32mp1.
+- vdd-supply: Phandle to the vdd input voltage. It can be used to supply ADC
+ analog input switches on stm32mp1.
+- st,syscfg: Phandle to system configuration controller. It can be used to
+ control the analog circuitry on stm32mp1.
Contents of a stm32 adc child node:
-----------------------------------
diff --git a/Documentation/devicetree/bindings/iio/chemical/plantower,pms7003.txt b/Documentation/devicetree/bindings/iio/chemical/plantower,pms7003.txt
deleted file mode 100644
index c52ea21..0000000
--- a/Documentation/devicetree/bindings/iio/chemical/plantower,pms7003.txt
+++ /dev/null
@@ -1,26 +0,0 @@
-* Plantower PMS7003 particulate matter sensor
-
-Required properties:
-- compatible: must one of:
- "plantower,pms1003"
- "plantower,pms3003"
- "plantower,pms5003"
- "plantower,pms6003"
- "plantower,pms7003"
- "plantower,pmsa003"
-- vcc-supply: phandle to the regulator that provides power to the sensor
-
-Optional properties:
-- plantower,set-gpios: phandle to the GPIO connected to the SET line
-- reset-gpios: phandle to the GPIO connected to the RESET line
-
-Refer to serial/slave-device.txt for generic serial attached device bindings.
-
-Example:
-
-&uart0 {
- air-pollution-sensor {
- compatible = "plantower,pms7003";
- vcc-supply = <®_vcc5v0>;
- };
-};
diff --git a/Documentation/devicetree/bindings/iio/chemical/plantower,pms7003.yaml b/Documentation/devicetree/bindings/iio/chemical/plantower,pms7003.yaml
new file mode 100644
index 0000000..a551d31
--- /dev/null
+++ b/Documentation/devicetree/bindings/iio/chemical/plantower,pms7003.yaml
@@ -0,0 +1,51 @@
+# SPDX-License-Identifier: GPL-2.0
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iio/chemical/plantower,pms7003.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Plantower PMS7003 air pollution sensor
+
+maintainers:
+ - Tomasz Duszynski <tduszyns@gmail.com>
+
+description: |
+ Air pollution sensor capable of measuring mass concentration of dust
+ particles.
+
+properties:
+ compatible:
+ enum:
+ - plantower,pms1003
+ - plantower,pms3003
+ - plantower,pms5003
+ - plantower,pms6003
+ - plantower,pms7003
+ - plantower,pmsa003
+
+ vcc-supply:
+ description: regulator that provides power to the sensor
+ maxItems: 1
+
+ plantower,set-gpios:
+ description: GPIO connected to the SET line
+ maxItems: 1
+
+ reset-gpios:
+ description: GPIO connected to the RESET line
+ maxItems: 1
+
+required:
+ - compatible
+ - vcc-supply
+
+examples:
+ - |
+ serial {
+ air-pollution-sensor {
+ compatible = "plantower,pms7003";
+ vcc-supply = <®_vcc5v0>;
+ };
+ };
+
+...
diff --git a/Documentation/devicetree/bindings/iio/imu/adi,adis16460.yaml b/Documentation/devicetree/bindings/iio/imu/adi,adis16460.yaml
new file mode 100644
index 0000000..0c53009
--- /dev/null
+++ b/Documentation/devicetree/bindings/iio/imu/adi,adis16460.yaml
@@ -0,0 +1,53 @@
+# SPDX-License-Identifier: GPL-2.0
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iio/imu/adi,adis16460.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Analog Devices ADIS16460 and similar IMUs
+
+maintainers:
+ - Dragos Bogdan <dragos.bogdan@analog.com>
+
+description: |
+ Analog Devices ADIS16460 and similar IMUs
+ https://www.analog.com/media/en/technical-documentation/data-sheets/ADIS16460.pdf
+
+properties:
+ compatible:
+ enum:
+ - adi,adis16460
+
+ reg:
+ maxItems: 1
+
+ spi-cpha: true
+
+ spi-cpol: true
+
+ interrupts:
+ maxItems: 1
+
+required:
+ - compatible
+ - reg
+ - interrupts
+
+examples:
+ - |
+ #include <dt-bindings/gpio/gpio.h>
+ #include <dt-bindings/interrupt-controller/irq.h>
+ spi0 {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ imu@0 {
+ compatible = "adi,adis16460";
+ reg = <0>;
+ spi-max-frequency = <5000000>;
+ spi-cpol;
+ spi-cpha;
+ interrupt-parent = <&gpio0>;
+ interrupts = <0 IRQ_TYPE_LEVEL_HIGH>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/iio/imu/st_lsm6dsx.txt b/Documentation/devicetree/bindings/iio/imu/st_lsm6dsx.txt
index efec9ec..6d0c050 100644
--- a/Documentation/devicetree/bindings/iio/imu/st_lsm6dsx.txt
+++ b/Documentation/devicetree/bindings/iio/imu/st_lsm6dsx.txt
@@ -11,6 +11,9 @@
"st,asm330lhh"
"st,lsm6dsox"
"st,lsm6dsr"
+ "st,lsm6ds3tr-c"
+ "st,ism330dhcx"
+ "st,lsm9ds1-imu"
- reg: i2c address of the sensor / spi cs line
Optional properties:
diff --git a/Documentation/devicetree/bindings/iio/light/noa1305.yaml b/Documentation/devicetree/bindings/iio/light/noa1305.yaml
new file mode 100644
index 0000000..17e7f14
--- /dev/null
+++ b/Documentation/devicetree/bindings/iio/light/noa1305.yaml
@@ -0,0 +1,44 @@
+# SPDX-License-Identifier: GPL-2.0
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iio/light/noa1305.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: ON Semiconductor NOA1305 Ambient Light Sensor
+
+maintainers:
+ - Martyn Welch <martyn.welch@collabora.com>
+
+description: |
+ Ambient sensing with an i2c interface.
+
+ https://www.onsemi.com/pub/Collateral/NOA1305-D.PDF
+
+properties:
+ compatible:
+ enum:
+ - onnn,noa1305
+
+ reg:
+ maxItems: 1
+
+ vin-supply:
+ description: Regulator that provides power to the sensor
+
+required:
+ - compatible
+ - reg
+
+examples:
+ - |
+ i2c {
+
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ light@39 {
+ compatible = "onnn,noa1305";
+ reg = <0x39>;
+ };
+ };
+...
diff --git a/Documentation/devicetree/bindings/iio/light/isl29501.txt b/Documentation/devicetree/bindings/iio/light/renesas,isl29501.txt
similarity index 100%
rename from Documentation/devicetree/bindings/iio/light/isl29501.txt
rename to Documentation/devicetree/bindings/iio/light/renesas,isl29501.txt
diff --git a/Documentation/devicetree/bindings/iio/light/stk33xx.yaml b/Documentation/devicetree/bindings/iio/light/stk33xx.yaml
new file mode 100644
index 0000000..aae8a6d
--- /dev/null
+++ b/Documentation/devicetree/bindings/iio/light/stk33xx.yaml
@@ -0,0 +1,49 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iio/light/stk33xx.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: |
+ Sensortek STK33xx I2C Ambient Light and Proximity sensor
+
+maintainers:
+ - Jonathan Cameron <jic23@kernel.org>
+
+description: |
+ Ambient light and proximity sensor over an i2c interface.
+
+properties:
+ compatible:
+ enum:
+ - sensortek,stk3310
+ - sensortek,stk3311
+ - sensortek,stk3335
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+required:
+ - compatible
+ - reg
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/irq.h>
+
+ i2c {
+
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ stk3310@48 {
+ compatible = "sensortek,stk3310";
+ reg = <0x48>;
+ interrupt-parent = <&gpio1>;
+ interrupts = <5 IRQ_TYPE_LEVEL_LOW>;
+ };
+ };
+...
diff --git a/Documentation/devicetree/bindings/iio/mount-matrix.txt b/Documentation/devicetree/bindings/iio/mount-matrix.txt
new file mode 100644
index 0000000..c3344ab
--- /dev/null
+++ b/Documentation/devicetree/bindings/iio/mount-matrix.txt
@@ -0,0 +1,203 @@
+For discussion. Unclear are:
+* is the definition of +/- values practical or counterintuitive?
+* are the definitions unambiguous and easy to follow?
+* are the examples correct?
+* should we have HOWTO engineer a correct matrix for a new device (without comparing to a different one)?
+
+====
+
+
+Mounting matrix
+
+The mounting matrix is a device tree property used to orient any device
+that produce three-dimensional data in relation to the world where it is
+deployed.
+
+The purpose of the mounting matrix is to translate the sensor frame of
+reference into the device frame of reference using a translation matrix as
+defined in linear algebra.
+
+The typical usecase is that where a component has an internal representation
+of the (x,y,z) triplets, such as different registers to read these coordinates,
+and thus implying that the component should be mounted in a certain orientation
+relative to some specific device frame of reference.
+
+For example a device with some kind of screen, where the user is supposed to
+interact with the environment using an accelerometer, gyroscope or magnetometer
+mounted on the same chassis as this screen, will likely take the screen as
+reference to (x,y,z) orientation, with (x,y) corresponding to these axes on the
+screen and (z) being depth, the axis perpendicular to the screen.
+
+For a screen you probably want (x) coordinates to go from negative on the left
+to positive on the right, (y) from negative on the bottom to positive on top
+and (z) depth to be negative under the screen and positive in front of it,
+toward the face of the user.
+
+A sensor can be mounted in any angle along the axes relative to the frame of
+reference. This means that the sensor may be flipped upside-down, left-right,
+or tilted at any angle relative to the frame of reference.
+
+Another frame of reference is how the device with its sensor relates to the
+external world, the environment where the device is deployed. Usually the data
+from the sensor is used to figure out how the device is oriented with respect
+to this world. When using the mounting matrix, the sensor and device orientation
+becomes identical and we can focus on the data as it relates to the surrounding
+world.
+
+Device-to-world examples for some three-dimensional sensor types:
+
+- Accelerometers have their world frame of reference toward the center of
+ gravity, usually to the core of the planet. A reading of the (x,y,z) values
+ from the sensor will give a projection of the gravity vector through the
+ device relative to the center of the planet, i.e. relative to its surface at
+ this point. Up and down in the world relative to the device frame of
+ reference can thus be determined. and users would likely expect a value of
+ 9.81 m/s^2 upwards along the (z) axis, i.e. out of the screen when the device
+ is held with its screen flat on the planets surface and 0 on the other axes,
+ as the gravity vector is projected 1:1 onto the sensors (z)-axis.
+
+ If you tilt the device, the g vector virtually coming out of the display
+ is projected onto the (x,y) plane of the display panel.
+
+ Example:
+
+ ^ z: +g ^ z: > 0
+ ! /!
+ ! x=y=0 / ! x: > 0
+ +--------+ +--------+
+ ! ! ! !
+ +--------+ +--------+
+ ! /
+ ! /
+ v v
+ center of center of
+ gravity gravity
+
+
+ If the device is tilted to the left, you get a positive x value. If you point
+ its top towards surface, you get a negative y axis.
+
+ (---------)
+ ! ! y: -g
+ ! ! ^
+ ! ! !
+ ! !
+ ! ! x: +g <- z: +g -> x: -g
+ ! 1 2 3 !
+ ! 4 5 6 ! !
+ ! 7 8 9 ! v
+ ! * 0 # ! y: +g
+ (---------)
+
+
+- Magnetometers (compasses) have their world frame of reference relative to the
+ geomagnetic field. The system orientation vis-a-vis the world is defined with
+ respect to the local earth geomagnetic reference frame where (y) is in the
+ ground plane and positive towards magnetic North, (x) is in the ground plane,
+ perpendicular to the North axis and positive towards the East and (z) is
+ perpendicular to the ground plane and positive upwards.
+
+
+ ^^^ North: y > 0
+
+ (---------)
+ ! !
+ ! !
+ ! !
+ ! ! >
+ ! ! > North: x > 0
+ ! 1 2 3 ! >
+ ! 4 5 6 !
+ ! 7 8 9 !
+ ! * 0 # !
+ (---------)
+
+ Since the geomagnetic field is not uniform this definition fails if we come
+ closer to the poles.
+
+ Sensors and driver can not and should not take care of this because there
+ are complex calculations and empirical data to be taken care of. We leave
+ this up to user space.
+
+ The definition we take:
+
+ If the device is placed at the equator and the top is pointing north, the
+ display is readable by a person standing upright on the earth surface, this
+ defines a positive y value.
+
+
+- Gyroscopes detects the movement relative the device itself. The angular
+ velocity is defined as orthogonal to the plane of rotation, so if you put the
+ device on a flat surface and spin it around the z axis (such as rotating a
+ device with a screen lying flat on a table), you should get a negative value
+ along the (z) axis if rotated clockwise, and a positive value if rotated
+ counter-clockwise according to the right-hand rule.
+
+
+ (---------) y > 0
+ ! ! v---\
+ ! !
+ ! !
+ ! ! <--\
+ ! ! ! z > 0
+ ! 1 2 3 ! --/
+ ! 4 5 6 !
+ ! 7 8 9 !
+ ! * 0 # !
+ (---------)
+
+
+So unless the sensor is ideally mounted, we need a means to indicate the
+relative orientation of any given sensor of this type with respect to the
+frame of reference.
+
+To achieve this, use the device tree property "mount-matrix" for the sensor.
+
+This supplies a 3x3 rotation matrix in the strict linear algebraic sense,
+to orient the senor axes relative to a desired point of reference. This means
+the resulting values from the sensor, after scaling to proper units, should be
+multiplied by this matrix to give the proper vectors values in three-dimensional
+space, relative to the device or world point of reference.
+
+For more information, consult:
+https://en.wikipedia.org/wiki/Rotation_matrix
+
+The mounting matrix has the layout:
+
+ (mxx, myx, mzx)
+ (mxy, myy, mzy)
+ (mxz, myz, mzz)
+
+Values are intended to be multiplied as:
+
+ x' = mxx * x + myx * y + mzx * z
+ y' = mxy * x + myy * y + mzy * z
+ z' = mxz * x + myz * y + mzz * z
+
+It is represented as an array of strings containing the real values for
+producing the transformation matrix.
+
+Examples:
+
+Identity matrix (nothing happens to the coordinates, which means the device was
+mechanically mounted in an ideal way and we need no transformation):
+
+mount-matrix = "1", "0", "0",
+ "0", "1", "0",
+ "0", "0", "1";
+
+The sensor is mounted 30 degrees (Pi/6 radians) tilted along the X axis, so we
+compensate by performing a -30 degrees rotation around the X axis:
+
+mount-matrix = "1", "0", "0",
+ "0", "0.866", "0.5",
+ "0", "-0.5", "0.866";
+
+The sensor is flipped 180 degrees (Pi radians) around the Z axis, i.e. mounted
+upside-down:
+
+mount-matrix = "0.998", "0.054", "0",
+ "-0.054", "0.998", "0",
+ "0", "0", "1";
+
+???: this does not match "180 degrees" - factors indicate ca. 3 degrees compensation
diff --git a/Documentation/devicetree/bindings/iio/potentiometer/max5432.yaml b/Documentation/devicetree/bindings/iio/potentiometer/max5432.yaml
new file mode 100644
index 0000000..5082f91
--- /dev/null
+++ b/Documentation/devicetree/bindings/iio/potentiometer/max5432.yaml
@@ -0,0 +1,44 @@
+# SPDX-License-Identifier: GPL-2.0
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iio/potentiometer/max5432.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Maxim Integrated MAX5432-MAX5435 Digital Potentiometers
+
+maintainers:
+ - Martin Kaiser <martin@kaiser.cx>
+
+description: |
+ Maxim Integrated MAX5432-MAX5435 Digital Potentiometers connected via I2C
+
+ Datasheet:
+ https://datasheets.maximintegrated.com/en/ds/MAX5432-MAX5435.pdf
+
+properties:
+ compatible:
+ enum:
+ - maxim,max5432
+ - maxim,max5433
+ - maxim,max5434
+ - maxim,max5435
+
+ reg:
+ maxItems: 1
+
+required:
+ - compatible
+ - reg
+
+additionalProperties: false
+
+examples:
+ - |
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+ max5434@28 {
+ compatible = "maxim,max5434";
+ reg = <0x28>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/input/allwinner,sun4i-a10-lradc-keys.yaml b/Documentation/devicetree/bindings/input/allwinner,sun4i-a10-lradc-keys.yaml
new file mode 100644
index 0000000..b3bd8ef
--- /dev/null
+++ b/Documentation/devicetree/bindings/input/allwinner,sun4i-a10-lradc-keys.yaml
@@ -0,0 +1,95 @@
+# SPDX-License-Identifier: GPL-2.0
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/input/allwinner,sun4i-a10-lradc-keys.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Allwinner A10 LRADC Device Tree Bindings
+
+maintainers:
+ - Chen-Yu Tsai <wens@csie.org>
+ - Maxime Ripard <maxime.ripard@bootlin.com>
+
+properties:
+ compatible:
+ oneOf:
+ - const: allwinner,sun4i-a10-lradc-keys
+ - const: allwinner,sun8i-a83t-r-lradc
+ - items:
+ - const: allwinner,sun50i-a64-lradc
+ - const: allwinner,sun8i-a83t-r-lradc
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+ vref-supply:
+ description:
+ Regulator for the LRADC reference voltage
+
+patternProperties:
+ "^button-[0-9]+$":
+ type: object
+ properties:
+ label:
+ $ref: /schemas/types.yaml#/definitions/string
+ description: Descriptive name of the key
+
+ linux,code:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description: Keycode to emit
+
+ channel:
+ allOf:
+ - $ref: /schemas/types.yaml#/definitions/uint32
+ - enum: [0, 1]
+ description: ADC Channel this key is attached to
+
+ voltage:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description:
+ Voltage in microvolts at LRADC input when this key is
+ pressed
+
+ required:
+ - label
+ - linux,code
+ - channel
+ - voltage
+
+ additionalProperties: false
+
+required:
+ - compatible
+ - reg
+ - interrupts
+ - vref-supply
+
+additionalProperties: false
+
+examples:
+ - |
+ lradc: lradc@1c22800 {
+ compatible = "allwinner,sun4i-a10-lradc-keys";
+ reg = <0x01c22800 0x100>;
+ interrupts = <31>;
+ vref-supply = <®_vcc3v0>;
+
+ button-191 {
+ label = "Volume Up";
+ linux,code = <115>;
+ channel = <0>;
+ voltage = <191274>;
+ };
+
+ button-392 {
+ label = "Volume Down";
+ linux,code = <114>;
+ channel = <0>;
+ voltage = <392644>;
+ };
+ };
+
+...
diff --git a/Documentation/devicetree/bindings/input/sun4i-lradc-keys.txt b/Documentation/devicetree/bindings/input/sun4i-lradc-keys.txt
deleted file mode 100644
index 507b737..0000000
--- a/Documentation/devicetree/bindings/input/sun4i-lradc-keys.txt
+++ /dev/null
@@ -1,65 +0,0 @@
-Allwinner sun4i low res adc attached tablet keys
-------------------------------------------------
-
-Required properties:
- - compatible: should be one of the following string:
- "allwinner,sun4i-a10-lradc-keys"
- "allwinner,sun8i-a83t-r-lradc"
- "allwinner,sun50i-a64-lradc", "allwinner,sun8i-a83t-r-lradc"
- - reg: mmio address range of the chip
- - interrupts: interrupt to which the chip is connected
- - vref-supply: powersupply for the lradc reference voltage
-
-Each key is represented as a sub-node of the compatible mentioned above:
-
-Required subnode-properties:
- - label: Descriptive name of the key.
- - linux,code: Keycode to emit.
- - channel: Channel this key is attached to, must be 0 or 1.
- - voltage: Voltage in µV at lradc input when this key is pressed.
-
-Example:
-
-#include <dt-bindings/input/input.h>
-
- lradc: lradc@1c22800 {
- compatible = "allwinner,sun4i-a10-lradc-keys";
- reg = <0x01c22800 0x100>;
- interrupts = <31>;
- vref-supply = <®_vcc3v0>;
-
- button@191 {
- label = "Volume Up";
- linux,code = <KEY_VOLUMEUP>;
- channel = <0>;
- voltage = <191274>;
- };
-
- button@392 {
- label = "Volume Down";
- linux,code = <KEY_VOLUMEDOWN>;
- channel = <0>;
- voltage = <392644>;
- };
-
- button@601 {
- label = "Menu";
- linux,code = <KEY_MENU>;
- channel = <0>;
- voltage = <601151>;
- };
-
- button@795 {
- label = "Enter";
- linux,code = <KEY_ENTER>;
- channel = <0>;
- voltage = <795090>;
- };
-
- button@987 {
- label = "Home";
- linux,code = <KEY_HOMEPAGE>;
- channel = <0>;
- voltage = <987387>;
- };
- };
diff --git a/Documentation/devicetree/bindings/input/touchscreen/ads7846.txt b/Documentation/devicetree/bindings/input/touchscreen/ads7846.txt
index 04413da..81f6bda 100644
--- a/Documentation/devicetree/bindings/input/touchscreen/ads7846.txt
+++ b/Documentation/devicetree/bindings/input/touchscreen/ads7846.txt
@@ -32,7 +32,6 @@
(ADS7846).
ti,keep-vref-on set to keep vref on for differential
measurements as well
- ti,swap-xy swap x and y axis
ti,settle-delay-usec Settling time of the analog signals;
a function of Vcc and the capacitance
on the X/Y drivers. If set to non-zero,
@@ -51,13 +50,6 @@
in Ohms (u16).
ti,x-min Minimum value on the X axis (u16).
ti,y-min Minimum value on the Y axis (u16).
- ti,x-max Maximum value on the X axis (u16).
- ti,y-max Minimum value on the Y axis (u16).
- ti,pressure-min Minimum reported pressure value
- (threshold) - u16.
- ti,pressure-max Maximum reported pressure value (u16).
- ti,debounce-max Max number of additional readings per
- sample (u16).
ti,debounce-tol Tolerance used for filtering (u16).
ti,debounce-rep Additional consecutive good readings
required after the first two (u16).
@@ -67,7 +59,28 @@
line is connected to.
wakeup-source use any event on touchscreen as wakeup event.
(Legacy property support: "linux,wakeup")
+ touchscreen-size-x General touchscreen binding, see [1].
+ touchscreen-size-y General touchscreen binding, see [1].
+ touchscreen-max-pressure General touchscreen binding, see [1].
+ touchscreen-min-pressure General touchscreen binding, see [1].
+ touchscreen-average-samples General touchscreen binding, see [1].
+ touchscreen-inverted-x General touchscreen binding, see [1].
+ touchscreen-inverted-y General touchscreen binding, see [1].
+ touchscreen-swapped-x-y General touchscreen binding, see [1].
+[1] All general touchscreen properties are described in
+ Documentation/devicetree/bindings/input/touchscreen/touchscreen.txt.
+
+Deprecated properties:
+
+ ti,swap-xy swap x and y axis
+ ti,x-max Maximum value on the X axis (u16).
+ ti,y-max Maximum value on the Y axis (u16).
+ ti,pressure-min Minimum reported pressure value
+ (threshold) - u16.
+ ti,pressure-max Maximum reported pressure value (u16).
+ ti,debounce-max Max number of additional readings per
+ sample (u16).
Example for a TSC2046 chip connected to an McSPI controller of an OMAP SoC::
diff --git a/Documentation/devicetree/bindings/input/touchscreen/bu21013.txt b/Documentation/devicetree/bindings/input/touchscreen/bu21013.txt
index 56d835242..da4c9d8 100644
--- a/Documentation/devicetree/bindings/input/touchscreen/bu21013.txt
+++ b/Documentation/devicetree/bindings/input/touchscreen/bu21013.txt
@@ -2,11 +2,24 @@
Required properties:
- compatible : "rohm,bu21013_tp"
- - reg : I2C device address
+ - reg : I2C device address
+ - reset-gpios : GPIO pin enabling (selecting) chip (CS)
+ - interrupt-parent : the phandle for the gpio controller
+ - interrupts : (gpio) interrupt to which the chip is connected
Optional properties:
- - touch-gpio : GPIO pin registering a touch event
+ - touch-gpios : GPIO pin registering a touch event
- <supply_name>-supply : Phandle to a regulator supply
+ - touchscreen-size-x : General touchscreen binding, see [1].
+ - touchscreen-size-y : General touchscreen binding, see [1].
+ - touchscreen-inverted-x : General touchscreen binding, see [1].
+ - touchscreen-inverted-y : General touchscreen binding, see [1].
+ - touchscreen-swapped-x-y : General touchscreen binding, see [1].
+
+[1] All general touchscreen properties are described in
+ Documentation/devicetree/bindings/input/touchscreen/touchscreen.txt.
+
+Deprecated properties:
- rohm,touch-max-x : Maximum outward permitted limit in the X axis
- rohm,touch-max-y : Maximum outward permitted limit in the Y axis
- rohm,flip-x : Flip touch coordinates on the X axis
@@ -18,11 +31,13 @@
bu21013_tp@5c {
compatible = "rohm,bu21013_tp";
reg = <0x5c>;
- touch-gpio = <&gpio2 20 0x4>;
+ interrupt-parent = <&gpio2>;
+ interrupts <&20 IRQ_TYPE_LEVEL_LOW>;
+ touch-gpio = <&gpio2 20 GPIO_ACTIVE_LOW>;
avdd-supply = <&ab8500_ldo_aux1_reg>;
- rohm,touch-max-x = <384>;
- rohm,touch-max-y = <704>;
- rohm,flip-y;
+ touchscreen-size-x = <384>;
+ touchscreen-size-y = <704>;
+ touchscreen-inverted-y;
};
};
diff --git a/Documentation/devicetree/bindings/interconnect/qcom,qcs404.txt b/Documentation/devicetree/bindings/interconnect/qcom,qcs404.txt
new file mode 100644
index 0000000..c07d898
--- /dev/null
+++ b/Documentation/devicetree/bindings/interconnect/qcom,qcs404.txt
@@ -0,0 +1,45 @@
+Qualcomm QCS404 Network-On-Chip interconnect driver binding
+-----------------------------------------------------------
+
+Required properties :
+- compatible : shall contain only one of the following:
+ "qcom,qcs404-bimc"
+ "qcom,qcs404-pcnoc"
+ "qcom,qcs404-snoc"
+- #interconnect-cells : should contain 1
+
+reg : specifies the physical base address and size of registers
+clocks : list of phandles and specifiers to all interconnect bus clocks
+clock-names : clock names should include both "bus" and "bus_a"
+
+Example:
+
+soc {
+ ...
+ bimc: interconnect@400000 {
+ reg = <0x00400000 0x80000>;
+ compatible = "qcom,qcs404-bimc";
+ #interconnect-cells = <1>;
+ clock-names = "bus", "bus_a";
+ clocks = <&rpmcc RPM_SMD_BIMC_CLK>,
+ <&rpmcc RPM_SMD_BIMC_A_CLK>;
+ };
+
+ pnoc: interconnect@500000 {
+ reg = <0x00500000 0x15080>;
+ compatible = "qcom,qcs404-pcnoc";
+ #interconnect-cells = <1>;
+ clock-names = "bus", "bus_a";
+ clocks = <&rpmcc RPM_SMD_PNOC_CLK>,
+ <&rpmcc RPM_SMD_PNOC_A_CLK>;
+ };
+
+ snoc: interconnect@580000 {
+ reg = <0x00580000 0x23080>;
+ compatible = "qcom,qcs404-snoc";
+ #interconnect-cells = <1>;
+ clock-names = "bus", "bus_a";
+ clocks = <&rpmcc RPM_SMD_SNOC_CLK>,
+ <&rpmcc RPM_SMD_SNOC_A_CLK>;
+ };
+};
diff --git a/Documentation/devicetree/bindings/interrupt-controller/allwinner,sun4i-a10-ic.yaml b/Documentation/devicetree/bindings/interrupt-controller/allwinner,sun4i-a10-ic.yaml
new file mode 100644
index 0000000..23a202d
--- /dev/null
+++ b/Documentation/devicetree/bindings/interrupt-controller/allwinner,sun4i-a10-ic.yaml
@@ -0,0 +1,47 @@
+# SPDX-License-Identifier: GPL-2.0
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/interrupt-controller/allwinner,sun4i-a10-ic.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Allwinner A10 Interrupt Controller Device Tree Bindings
+
+maintainers:
+ - Chen-Yu Tsai <wens@csie.org>
+ - Maxime Ripard <maxime.ripard@bootlin.com>
+
+allOf:
+ - $ref: /schemas/interrupt-controller.yaml#
+
+properties:
+ "#interrupt-cells":
+ const: 1
+
+ compatible:
+ enum:
+ - allwinner,sun4i-a10-ic
+ - allwinner,suniv-f1c100s-ic
+
+ reg:
+ maxItems: 1
+
+ interrupt-controller: true
+
+required:
+ - "#interrupt-cells"
+ - compatible
+ - reg
+ - interrupt-controller
+
+additionalProperties: false
+
+examples:
+ - |
+ intc: interrupt-controller@1c20400 {
+ compatible = "allwinner,sun4i-a10-ic";
+ reg = <0x01c20400 0x400>;
+ interrupt-controller;
+ #interrupt-cells = <1>;
+ };
+
+...
diff --git a/Documentation/devicetree/bindings/interrupt-controller/allwinner,sun4i-ic.txt b/Documentation/devicetree/bindings/interrupt-controller/allwinner,sun4i-ic.txt
deleted file mode 100644
index 4043525..0000000
--- a/Documentation/devicetree/bindings/interrupt-controller/allwinner,sun4i-ic.txt
+++ /dev/null
@@ -1,20 +0,0 @@
-Allwinner Sunxi Interrupt Controller
-
-Required properties:
-
-- compatible : should be one of the following:
- "allwinner,sun4i-a10-ic"
- "allwinner,suniv-f1c100s-ic"
-- reg : Specifies base physical address and size of the registers.
-- interrupt-controller : Identifies the node as an interrupt controller
-- #interrupt-cells : Specifies the number of cells needed to encode an
- interrupt source. The value shall be 1.
-
-Example:
-
-intc: interrupt-controller {
- compatible = "allwinner,sun4i-a10-ic";
- reg = <0x01c20400 0x400>;
- interrupt-controller;
- #interrupt-cells = <1>;
-};
diff --git a/Documentation/devicetree/bindings/interrupt-controller/allwinner,sun7i-a20-sc-nmi.yaml b/Documentation/devicetree/bindings/interrupt-controller/allwinner,sun7i-a20-sc-nmi.yaml
new file mode 100644
index 0000000..0eccf55
--- /dev/null
+++ b/Documentation/devicetree/bindings/interrupt-controller/allwinner,sun7i-a20-sc-nmi.yaml
@@ -0,0 +1,70 @@
+# SPDX-License-Identifier: GPL-2.0
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/interrupt-controller/allwinner,sun7i-a20-sc-nmi.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Allwinner A20 Non-Maskable Interrupt Controller Device Tree Bindings
+
+maintainers:
+ - Chen-Yu Tsai <wens@csie.org>
+ - Maxime Ripard <maxime.ripard@bootlin.com>
+
+allOf:
+ - $ref: /schemas/interrupt-controller.yaml#
+
+properties:
+ "#interrupt-cells":
+ const: 2
+ description:
+ The first cell is the IRQ number, the second cell the trigger
+ type as defined in interrupt.txt in this directory.
+
+ compatible:
+ oneOf:
+ - const: allwinner,sun6i-a31-r-intc
+ - const: allwinner,sun6i-a31-sc-nmi
+ deprecated: true
+ - const: allwinner,sun7i-a20-sc-nmi
+ - items:
+ - const: allwinner,sun8i-a83t-r-intc
+ - const: allwinner,sun6i-a31-r-intc
+ - const: allwinner,sun9i-a80-sc-nmi
+ - items:
+ - const: allwinner,sun50i-a64-r-intc
+ - const: allwinner,sun6i-a31-r-intc
+ - items:
+ - const: allwinner,sun50i-h6-r-intc
+ - const: allwinner,sun6i-a31-r-intc
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+ interrupt-controller: true
+
+required:
+ - "#interrupt-cells"
+ - compatible
+ - reg
+ - interrupts
+ - interrupt-controller
+
+# FIXME: We should set it, but it would report all the generic
+# properties as additional properties.
+# additionalProperties: false
+
+examples:
+ - |
+ interrupt-controller@1c00030 {
+ compatible = "allwinner,sun7i-a20-sc-nmi";
+ interrupt-controller;
+ #interrupt-cells = <2>;
+ reg = <0x01c00030 0x0c>;
+ interrupt-parent = <&gic>;
+ interrupts = <0 0 4>;
+ };
+
+...
diff --git a/Documentation/devicetree/bindings/interrupt-controller/allwinner,sunxi-nmi.txt b/Documentation/devicetree/bindings/interrupt-controller/allwinner,sunxi-nmi.txt
deleted file mode 100644
index 24beadf..0000000
--- a/Documentation/devicetree/bindings/interrupt-controller/allwinner,sunxi-nmi.txt
+++ /dev/null
@@ -1,29 +0,0 @@
-Allwinner Sunxi NMI Controller
-==============================
-
-Required properties:
-
-- compatible : should be one of the following:
- - "allwinner,sun7i-a20-sc-nmi"
- - "allwinner,sun6i-a31-sc-nmi" (deprecated)
- - "allwinner,sun6i-a31-r-intc"
- - "allwinner,sun9i-a80-nmi"
-- reg : Specifies base physical address and size of the registers.
-- interrupt-controller : Identifies the node as an interrupt controller
-- #interrupt-cells : Specifies the number of cells needed to encode an
- interrupt source. The value shall be 2. The first cell is the IRQ number, the
- second cell the trigger type as defined in interrupt.txt in this directory.
-- interrupts: Specifies the interrupt line (NMI) which is handled by
- the interrupt controller in the parent controller's notation. This value
- shall be the NMI.
-
-Example:
-
-sc-nmi-intc@1c00030 {
- compatible = "allwinner,sun7i-a20-sc-nmi";
- interrupt-controller;
- #interrupt-cells = <2>;
- reg = <0x01c00030 0x0c>;
- interrupt-parent = <&gic>;
- interrupts = <0 0 4>;
-};
diff --git a/Documentation/devicetree/bindings/interrupt-controller/amlogic,meson-gpio-intc.txt b/Documentation/devicetree/bindings/interrupt-controller/amlogic,meson-gpio-intc.txt
index 7d531d5..684bb1c 100644
--- a/Documentation/devicetree/bindings/interrupt-controller/amlogic,meson-gpio-intc.txt
+++ b/Documentation/devicetree/bindings/interrupt-controller/amlogic,meson-gpio-intc.txt
@@ -16,6 +16,7 @@
"amlogic,meson-gxl-gpio-intc" for GXL SoCs (S905X, S912)
"amlogic,meson-axg-gpio-intc" for AXG SoCs (A113D, A113X)
"amlogic,meson-g12a-gpio-intc" for G12A SoCs (S905D2, S905X2, S905Y2)
+ "amlogic,meson-sm1-gpio-intc" for SM1 SoCs (S905D3, S905X3, S905Y3)
- reg : Specifies base physical address and size of the registers.
- interrupt-controller : Identifies the node as an interrupt controller.
- #interrupt-cells : Specifies the number of cells needed to encode an
diff --git a/Documentation/devicetree/bindings/interrupt-controller/arm,gic-v3.yaml b/Documentation/devicetree/bindings/interrupt-controller/arm,gic-v3.yaml
index c34df35..1fe147d 100644
--- a/Documentation/devicetree/bindings/interrupt-controller/arm,gic-v3.yaml
+++ b/Documentation/devicetree/bindings/interrupt-controller/arm,gic-v3.yaml
@@ -44,11 +44,13 @@
be at least 4.
The 1st cell is the interrupt type; 0 for SPI interrupts, 1 for PPI
- interrupts. Other values are reserved for future use.
+ interrupts, 2 for interrupts in the Extended SPI range, 3 for the
+ Extended PPI range. Other values are reserved for future use.
The 2nd cell contains the interrupt number for the interrupt type.
SPI interrupts are in the range [0-987]. PPI interrupts are in the
- range [0-15].
+ range [0-15]. Extented SPI interrupts are in the range [0-1023].
+ Extended PPI interrupts are in the range [0-127].
The 3rd cell is the flags, encoded as follows:
bits[3:0] trigger type and level flags.
diff --git a/Documentation/devicetree/bindings/interrupt-controller/interrupts.txt b/Documentation/devicetree/bindings/interrupt-controller/interrupts.txt
index 8a3c408..4a3ee25 100644
--- a/Documentation/devicetree/bindings/interrupt-controller/interrupts.txt
+++ b/Documentation/devicetree/bindings/interrupt-controller/interrupts.txt
@@ -22,10 +22,10 @@
interrupt client node or in any of its parent nodes. Interrupts listed in the
"interrupts" property are always in reference to the node's interrupt parent.
-The "interrupts-extended" property is a special form for use when a node needs
-to reference multiple interrupt parents. Each entry in this property contains
-both the parent phandle and the interrupt specifier. "interrupts-extended"
-should only be used when a device has multiple interrupt parents.
+The "interrupts-extended" property is a special form; useful when a node needs
+to reference multiple interrupt parents or a different interrupt parent than
+the inherited one. Each entry in this property contains both the parent phandle
+and the interrupt specifier.
Example:
interrupts-extended = <&intc1 5 1>, <&intc2 1 0>;
diff --git a/Documentation/devicetree/bindings/interrupt-controller/mediatek,sysirq.txt b/Documentation/devicetree/bindings/interrupt-controller/mediatek,sysirq.txt
index 0e312fe..84ced3f 100644
--- a/Documentation/devicetree/bindings/interrupt-controller/mediatek,sysirq.txt
+++ b/Documentation/devicetree/bindings/interrupt-controller/mediatek,sysirq.txt
@@ -15,6 +15,7 @@
"mediatek,mt7629-sysirq", "mediatek,mt6577-sysirq": for MT7629
"mediatek,mt6795-sysirq", "mediatek,mt6577-sysirq": for MT6795
"mediatek,mt6797-sysirq", "mediatek,mt6577-sysirq": for MT6797
+ "mediatek,mt6779-sysirq", "mediatek,mt6577-sysirq": for MT6779
"mediatek,mt6765-sysirq", "mediatek,mt6577-sysirq": for MT6765
"mediatek,mt6755-sysirq", "mediatek,mt6577-sysirq": for MT6755
"mediatek,mt6592-sysirq", "mediatek,mt6577-sysirq": for MT6592
diff --git a/Documentation/devicetree/bindings/iommu/mediatek,iommu.txt b/Documentation/devicetree/bindings/iommu/mediatek,iommu.txt
index 6922db5..ce59a50 100644
--- a/Documentation/devicetree/bindings/iommu/mediatek,iommu.txt
+++ b/Documentation/devicetree/bindings/iommu/mediatek,iommu.txt
@@ -11,10 +11,23 @@
|
m4u (Multimedia Memory Management Unit)
|
+ +--------+
+ | |
+ gals0-rx gals1-rx (Global Async Local Sync rx)
+ | |
+ | |
+ gals0-tx gals1-tx (Global Async Local Sync tx)
+ | | Some SoCs may have GALS.
+ +--------+
+ |
SMI Common(Smart Multimedia Interface Common)
|
+----------------+-------
| |
+ | gals-rx There may be GALS in some larbs.
+ | |
+ | |
+ | gals-tx
| |
SMI larb0 SMI larb1 ... SoCs have several SMI local arbiter(larb).
(display) (vdec)
@@ -36,6 +49,10 @@
like display, video decode, and camera. And there are different ports
in each larb. Take a example, There are many ports like MC, PP, VLD in the
video decode local arbiter, all these ports are according to the video HW.
+ In some SoCs, there may be a GALS(Global Async Local Sync) module between
+smi-common and m4u, and additional GALS module between smi-larb and
+smi-common. GALS can been seen as a "asynchronous fifo" which could help
+synchronize for the modules in different clock frequency.
Required properties:
- compatible : must be one of the following string:
@@ -44,18 +61,25 @@
"mediatek,mt7623-m4u", "mediatek,mt2701-m4u" for mt7623 which uses
generation one m4u HW.
"mediatek,mt8173-m4u" for mt8173 which uses generation two m4u HW.
+ "mediatek,mt8183-m4u" for mt8183 which uses generation two m4u HW.
- reg : m4u register base and size.
- interrupts : the interrupt of m4u.
- clocks : must contain one entry for each clock-names.
-- clock-names : must be "bclk", It is the block clock of m4u.
+- clock-names : Only 1 optional clock:
+ - "bclk": the block clock of m4u.
+ Here is the list which require this "bclk":
+ - mt2701, mt2712, mt7623 and mt8173.
+ Note that m4u use the EMI clock which always has been enabled before kernel
+ if there is no this "bclk".
- mediatek,larbs : List of phandle to the local arbiters in the current Socs.
Refer to bindings/memory-controllers/mediatek,smi-larb.txt. It must sort
according to the local arbiter index, like larb0, larb1, larb2...
- iommu-cells : must be 1. This is the mtk_m4u_id according to the HW.
Specifies the mtk_m4u_id as defined in
dt-binding/memory/mt2701-larb-port.h for mt2701, mt7623
- dt-binding/memory/mt2712-larb-port.h for mt2712, and
- dt-binding/memory/mt8173-larb-port.h for mt8173.
+ dt-binding/memory/mt2712-larb-port.h for mt2712,
+ dt-binding/memory/mt8173-larb-port.h for mt8173, and
+ dt-binding/memory/mt8183-larb-port.h for mt8183.
Example:
iommu: iommu@10205000 {
diff --git a/Documentation/devicetree/bindings/leds/ams,as3645a.txt b/Documentation/devicetree/bindings/leds/ams,as3645a.txt
index fdc40e3..4af2987 100644
--- a/Documentation/devicetree/bindings/leds/ams,as3645a.txt
+++ b/Documentation/devicetree/bindings/leds/ams,as3645a.txt
@@ -39,7 +39,9 @@
Optional properties of the flash child node
===========================================
-label : The label of the flash LED.
+function : See Documentation/devicetree/bindings/leds/common.txt.
+color : See Documentation/devicetree/bindings/leds/common.txt.
+label : See Documentation/devicetree/bindings/leds/common.txt (deprecated).
Required properties of the indicator child node (1)
@@ -52,28 +54,32 @@
Optional properties of the indicator child node
===============================================
-label : The label of the indicator LED.
+function : See Documentation/devicetree/bindings/leds/common.txt.
+color : See Documentation/devicetree/bindings/leds/common.txt.
+label : See Documentation/devicetree/bindings/leds/common.txt (deprecated).
Example
=======
+#include <dt-bindings/leds/common.h>
+
as3645a@30 {
- #address-cells: 1
- #size-cells: 0
+ #address-cells = <1>;
+ #size-cells = <0>;
reg = <0x30>;
compatible = "ams,as3645a";
- flash@0 {
+ led@0 {
reg = <0x0>;
flash-timeout-us = <150000>;
flash-max-microamp = <320000>;
led-max-microamp = <60000>;
ams,input-max-microamp = <1750000>;
- label = "as3645a:flash";
+ function = LED_FUNCTION_FLASH;
};
- indicator@1 {
+ led@1 {
reg = <0x1>;
led-max-microamp = <10000>;
- label = "as3645a:indicator";
+ function = LED_FUNCTION_INDICATOR;
};
};
diff --git a/Documentation/devicetree/bindings/leds/common.txt b/Documentation/devicetree/bindings/leds/common.txt
index 70876ac..9fa6f97 100644
--- a/Documentation/devicetree/bindings/leds/common.txt
+++ b/Documentation/devicetree/bindings/leds/common.txt
@@ -10,14 +10,30 @@
have to be tightly coupled with the LED device binding. They are represented
by child nodes of the parent LED device binding.
+
Optional properties for child nodes:
- led-sources : List of device current outputs the LED is connected to. The
outputs are identified by the numbers that must be defined
in the LED device binding documentation.
+
+- function: LED functon. Use one of the LED_FUNCTION_* prefixed definitions
+ from the header include/dt-bindings/leds/common.h.
+ If there is no matching LED_FUNCTION available, add a new one.
+
+- color : Color of the LED. Use one of the LED_COLOR_ID_* prefixed definitions
+ from the header include/dt-bindings/leds/common.h.
+ If there is no matching LED_COLOR_ID available, add a new one.
+
+- function-enumerator: Integer to be used when more than one instance
+ of the same function is needed, differing only with
+ an ordinal number.
+
- label : The label for this LED. If omitted, the label is taken from the node
name (excluding the unit address). It has to uniquely identify
a device, i.e. no other LED class device can be assigned the same
- label.
+ label. This property is deprecated - use 'function' and 'color'
+ properties instead. function-enumerator has no effect when this
+ property is present.
- default-state : The initial state of the LED. Valid values are "on", "off",
and "keep". If the LED is already on or off and the default-state property is
@@ -99,29 +115,59 @@
* Examples
-gpio-leds {
+#include <dt-bindings/leds/common.h>
+
+led-controller@0 {
compatible = "gpio-leds";
- system-status {
- label = "Status";
+ led0 {
+ function = LED_FUNCTION_STATUS;
linux,default-trigger = "heartbeat";
gpios = <&gpio0 0 GPIO_ACTIVE_HIGH>;
};
- usb {
+ led1 {
+ function = LED_FUNCTION_USB;
gpios = <&gpio0 1 GPIO_ACTIVE_HIGH>;
trigger-sources = <&ohci_port1>, <&ehci_port1>;
};
};
-max77693-led {
+led-controller@0 {
compatible = "maxim,max77693-led";
- camera-flash {
- label = "Flash";
+ led {
+ function = LED_FUNCTION_FLASH;
+ color = <LED_COLOR_ID_WHITE>;
led-sources = <0>, <1>;
led-max-microamp = <50000>;
flash-max-microamp = <320000>;
flash-max-timeout-us = <500000>;
};
};
+
+led-controller@30 {
+ compatible = "panasonic,an30259a";
+ reg = <0x30>;
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ led@1 {
+ reg = <1>;
+ linux,default-trigger = "heartbeat";
+ function = LED_FUNCTION_INDICATOR;
+ function-enumerator = <1>;
+ };
+
+ led@2 {
+ reg = <2>;
+ function = LED_FUNCTION_INDICATOR;
+ function-enumerator = <2>;
+ };
+
+ led@3 {
+ reg = <3>;
+ function = LED_FUNCTION_INDICATOR;
+ function-enumerator = <3>;
+ };
+};
diff --git a/Documentation/devicetree/bindings/leds/leds-aat1290.txt b/Documentation/devicetree/bindings/leds/leds-aat1290.txt
index 85c0c58..62ed17e 100644
--- a/Documentation/devicetree/bindings/leds/leds-aat1290.txt
+++ b/Documentation/devicetree/bindings/leds/leds-aat1290.txt
@@ -32,15 +32,18 @@
formula: T = 8.82 * 10^9 * Ct.
Optional properties of the LED child node:
-- label : see Documentation/devicetree/bindings/leds/common.txt
+- function : see Documentation/devicetree/bindings/leds/common.txt
+- color : see Documentation/devicetree/bindings/leds/common.txt
+- label : see Documentation/devicetree/bindings/leds/common.txt (deprecated)
Example (by Ct = 220nF, Rset = 160kohm and exynos4412-trats2 board with
a switch that allows for routing strobe signal either from the host or from
the camera sensor):
#include "exynos4412.dtsi"
+#include <dt-bindings/leds/common.h>
-aat1290 {
+led-controller {
compatible = "skyworks,aat1290";
flen-gpios = <&gpj1 1 GPIO_ACTIVE_HIGH>;
enset-gpios = <&gpj1 2 GPIO_ACTIVE_HIGH>;
@@ -50,8 +53,9 @@
pinctrl-1 = <&camera_flash_host>;
pinctrl-2 = <&camera_flash_isp>;
- camera_flash: flash-led {
- label = "aat1290-flash";
+ camera_flash: led {
+ function = LED_FUNCTION_FLASH;
+ color = <LED_COLOR_ID_WHITE>;
led-max-microamp = <520833>;
flash-max-microamp = <1012500>;
flash-max-timeout-us = <1940000>;
diff --git a/Documentation/devicetree/bindings/leds/leds-an30259a.txt b/Documentation/devicetree/bindings/leds/leds-an30259a.txt
index 6ffb861..cbd8339 100644
--- a/Documentation/devicetree/bindings/leds/leds-an30259a.txt
+++ b/Documentation/devicetree/bindings/leds/leds-an30259a.txt
@@ -15,10 +15,19 @@
- reg: Pin that the LED is connected to. Must be 1, 2, or 3.
Optional sub-node properties:
- - label: see Documentation/devicetree/bindings/leds/common.txt
- - linux,default-trigger: see Documentation/devicetree/bindings/leds/common.txt
+ - function :
+ see Documentation/devicetree/bindings/leds/common.txt
+ - color :
+ see Documentation/devicetree/bindings/leds/common.txt
+ - label :
+ see Documentation/devicetree/bindings/leds/common.txt (deprecated)
+ - linux,default-trigger :
+ see Documentation/devicetree/bindings/leds/common.txt
Example:
+
+#include <dt-bindings/leds/common.h>
+
led-controller@30 {
compatible = "panasonic,an30259a";
reg = <0x30>;
@@ -28,16 +37,19 @@
led@1 {
reg = <1>;
linux,default-trigger = "heartbeat";
- label = "red:indicator";
+ function = LED_FUNCTION_INDICATOR;
+ color = <LED_COLOR_ID_RED>;
};
led@2 {
reg = <2>;
- label = "green:indicator";
+ function = LED_FUNCTION_INDICATOR;
+ color = <LED_COLOR_ID_GREEN>;
};
led@3 {
reg = <3>;
- label = "blue:indicator";
+ function = LED_FUNCTION_INDICATOR;
+ color = <LED_COLOR_ID_BLUE>;
};
};
diff --git a/Documentation/devicetree/bindings/leds/leds-cr0014114.txt b/Documentation/devicetree/bindings/leds/leds-cr0014114.txt
index 4255b19..f8de751 100644
--- a/Documentation/devicetree/bindings/leds/leds-cr0014114.txt
+++ b/Documentation/devicetree/bindings/leds/leds-cr0014114.txt
@@ -11,14 +11,20 @@
apply. In particular, "reg" and "spi-max-frequency" properties must be given.
LED sub-node properties:
-- label :
+- function :
see Documentation/devicetree/bindings/leds/common.txt
+- color :
+ see Documentation/devicetree/bindings/leds/common.txt
+- label :
+ see Documentation/devicetree/bindings/leds/common.txt (deprecated)
- linux,default-trigger : (optional)
see Documentation/devicetree/bindings/leds/common.txt
Example
-------
+#include <dt-bindings/leds/common.h>
+
led-controller@0 {
compatible = "crane,cr0014114";
reg = <0>;
@@ -28,27 +34,33 @@
led@0 {
reg = <0>;
- label = "red:coin";
+ function = "coin";
+ color = <LED_COLOR_ID_RED>;
};
led@1 {
reg = <1>;
- label = "green:coin";
+ function = "coin";
+ color = <LED_COLOR_ID_GREEN>;
};
led@2 {
reg = <2>;
- label = "blue:coin";
+ function = "coin";
+ color = <LED_COLOR_ID_BLUE>;
};
led@3 {
reg = <3>;
- label = "red:bill";
+ function = "bill";
+ color = <LED_COLOR_ID_RED>;
};
led@4 {
reg = <4>;
- label = "green:bill";
+ function = "bill";
+ color = <LED_COLOR_ID_GREEN>;
};
led@5 {
reg = <5>;
- label = "blue:bill";
+ function = "bill";
+ color = <LED_COLOR_ID_BLUE>;
};
...
};
diff --git a/Documentation/devicetree/bindings/leds/leds-gpio.txt b/Documentation/devicetree/bindings/leds/leds-gpio.txt
index a48dda2..d21281b 100644
--- a/Documentation/devicetree/bindings/leds/leds-gpio.txt
+++ b/Documentation/devicetree/bindings/leds/leds-gpio.txt
@@ -10,8 +10,12 @@
- gpios : Should specify the LED's GPIO, see "gpios property" in
Documentation/devicetree/bindings/gpio/gpio.txt. Active low LEDs should be
indicated using flags in the GPIO specifier.
-- label : (optional)
+- function : (optional)
see Documentation/devicetree/bindings/leds/common.txt
+- color : (optional)
+ see Documentation/devicetree/bindings/leds/common.txt
+- label : (optional)
+ see Documentation/devicetree/bindings/leds/common.txt (deprecated)
- linux,default-trigger : (optional)
see Documentation/devicetree/bindings/leds/common.txt
- default-state: (optional) The initial state of the LED.
@@ -27,30 +31,34 @@
Examples:
#include <dt-bindings/gpio/gpio.h>
+#include <dt-bindings/leds/common.h>
leds {
compatible = "gpio-leds";
- hdd {
- label = "Disk Activity";
+ led0 {
gpios = <&mcu_pio 0 GPIO_ACTIVE_LOW>;
linux,default-trigger = "disk-activity";
+ function = LED_FUNCTION_DISK;
};
- fault {
+ led1 {
gpios = <&mcu_pio 1 GPIO_ACTIVE_HIGH>;
/* Keep LED on if BIOS detected hardware fault */
default-state = "keep";
+ function = LED_FUNCTION_FAULT;
};
};
run-control {
compatible = "gpio-leds";
- red {
+ led0 {
gpios = <&mpc8572 6 GPIO_ACTIVE_HIGH>;
+ color = <LED_COLOR_ID_RED>;
default-state = "off";
};
- green {
+ led1 {
gpios = <&mpc8572 7 GPIO_ACTIVE_HIGH>;
+ color = <LED_COLOR_ID_GREEN>;
default-state = "on";
};
};
@@ -58,9 +66,10 @@
leds {
compatible = "gpio-leds";
- charger-led {
+ led0 {
gpios = <&gpio1 2 GPIO_ACTIVE_HIGH>;
linux,default-trigger = "max8903-charger-charging";
retain-state-suspended;
+ function = LED_FUNCTION_CHARGE;
};
};
diff --git a/Documentation/devicetree/bindings/leds/leds-lm3532.txt b/Documentation/devicetree/bindings/leds/leds-lm3532.txt
index c087f85..5379321 100644
--- a/Documentation/devicetree/bindings/leds/leds-lm3532.txt
+++ b/Documentation/devicetree/bindings/leds/leds-lm3532.txt
@@ -62,6 +62,9 @@
- label : see Documentation/devicetree/bindings/leds/common.txt
- linux,default-trigger :
see Documentation/devicetree/bindings/leds/common.txt
+ - led-max-microamp : Defines the full scale current value for each control
+ bank. The range is from 5000uA-29800uA in increments
+ of 800uA.
Example:
led-controller@38 {
@@ -85,6 +88,7 @@
reg = <0>;
led-sources = <2>;
ti,led-mode = <1>;
+ led-max-microamp = <21800>;
label = ":backlight";
linux,default-trigger = "backlight";
};
diff --git a/Documentation/devicetree/bindings/leds/leds-lm3601x.txt b/Documentation/devicetree/bindings/leds/leds-lm3601x.txt
index a88b2c4..095dafb 100644
--- a/Documentation/devicetree/bindings/leds/leds-lm3601x.txt
+++ b/Documentation/devicetree/bindings/leds/leds-lm3601x.txt
@@ -22,9 +22,14 @@
- led-max-microamp : Range from 2.4mA - 376mA
Optional child properties:
- - label : see Documentation/devicetree/bindings/leds/common.txt
+ - function : see Documentation/devicetree/bindings/leds/common.txt
+ - color : see Documentation/devicetree/bindings/leds/common.txt
+ - label : see Documentation/devicetree/bindings/leds/common.txt (deprecated)
Example:
+
+#include <dt-bindings/leds/common.h>
+
led-controller@64 {
compatible = "ti,lm36010";
#address-cells = <1>;
@@ -33,7 +38,8 @@
led@0 {
reg = <1>;
- label = "white:torch";
+ function = LED_FUNCTION_TORCH;
+ color = <LED_COLOR_ID_WHITE>;
led-max-microamp = <376000>;
flash-max-microamp = <1500000>;
flash-max-timeout-us = <1600000>;
diff --git a/Documentation/devicetree/bindings/leds/leds-lm3692x.txt b/Documentation/devicetree/bindings/leds/leds-lm3692x.txt
index 08b3528..4c2d923 100644
--- a/Documentation/devicetree/bindings/leds/leds-lm3692x.txt
+++ b/Documentation/devicetree/bindings/leds/leds-lm3692x.txt
@@ -26,12 +26,16 @@
3 - Will enable the LED3 sync (LM36923 only)
Optional child properties:
- - label : see Documentation/devicetree/bindings/leds/common.txt
+ - function : see Documentation/devicetree/bindings/leds/common.txt
+ - color : see Documentation/devicetree/bindings/leds/common.txt
+ - label : see Documentation/devicetree/bindings/leds/common.txt (deprecated)
- linux,default-trigger :
see Documentation/devicetree/bindings/leds/common.txt
Example:
+#include <dt-bindings/leds/common.h>
+
led-controller@36 {
compatible = "ti,lm3692x";
reg = <0x36>;
@@ -43,7 +47,8 @@
led@0 {
reg = <0>;
- label = "white:backlight_cluster";
+ function = LED_FUNCTION_BACKLIGHT;
+ color = <LED_COLOR_ID_WHITE>;
linux,default-trigger = "backlight";
};
}
diff --git a/Documentation/devicetree/bindings/leds/leds-lp8860.txt b/Documentation/devicetree/bindings/leds/leds-lp8860.txt
index 5f0e892..9863220 100644
--- a/Documentation/devicetree/bindings/leds/leds-lp8860.txt
+++ b/Documentation/devicetree/bindings/leds/leds-lp8860.txt
@@ -20,12 +20,16 @@
- reg : 0
Optional child properties:
- - label : see Documentation/devicetree/bindings/leds/common.txt
+ - function : see Documentation/devicetree/bindings/leds/common.txt
+ - color : see Documentation/devicetree/bindings/leds/common.txt
+ - label : see Documentation/devicetree/bindings/leds/common.txt (deprecated)
- linux,default-trigger :
see Documentation/devicetree/bindings/leds/common.txt
Example:
+#include <dt-bindings/leds/common.h>
+
led-controller@2d {
compatible = "ti,lp8860";
#address-cells = <1>;
@@ -36,7 +40,8 @@
led@0 {
reg = <0>;
- label = "white:backlight";
+ function = LED_FUNCTION_BACKLIGHT;
+ color = <LED_COLOR_ID_WHITE>;
linux,default-trigger = "backlight";
};
}
diff --git a/Documentation/devicetree/bindings/leds/leds-lt3593.txt b/Documentation/devicetree/bindings/leds/leds-lt3593.txt
index 6b2cabc..24eccda 100644
--- a/Documentation/devicetree/bindings/leds/leds-lt3593.txt
+++ b/Documentation/devicetree/bindings/leds/leds-lt3593.txt
@@ -9,8 +9,10 @@
configured in a sub-node in the device node.
Optional sub-node properties:
-- label: A label for the LED. If none is given, the LED will be
- named "lt3595::".
+- function: See Documentation/devicetree/bindings/leds/common.txt
+- color: See Documentation/devicetree/bindings/leds/common.txt
+- label: A label for the LED. If none is given, the LED will be
+ named "lt3595::" (deprecated)
- linux,default-trigger: The default trigger for the LED.
See Documentation/devicetree/bindings/leds/common.txt
- default-state: The initial state of the LED.
@@ -21,12 +23,15 @@
Example:
+#include <dt-bindings/leds/common.h>
+
led-controller {
compatible = "lltc,lt3593";
lltc,ctrl-gpios = <&gpio 0 GPIO_ACTIVE_HIGH>;
led {
- label = "white:backlight";
+ function = LED_FUNCTION_BACKLIGHT;
+ color = <LED_COLOR_ID_WHITE>;
default-state = "on";
};
};
diff --git a/Documentation/devicetree/bindings/leds/leds-sc27xx-bltc.txt b/Documentation/devicetree/bindings/leds/leds-sc27xx-bltc.txt
index dddf84f..df2b4e1 100644
--- a/Documentation/devicetree/bindings/leds/leds-sc27xx-bltc.txt
+++ b/Documentation/devicetree/bindings/leds/leds-sc27xx-bltc.txt
@@ -14,7 +14,9 @@
- reg: Port this LED is connected to.
Optional child properties:
-- label: See Documentation/devicetree/bindings/leds/common.txt.
+- function: See Documentation/devicetree/bindings/leds/common.txt.
+- color: See Documentation/devicetree/bindings/leds/common.txt.
+- label: See Documentation/devicetree/bindings/leds/common.txt (deprecated).
Examples:
@@ -25,17 +27,17 @@
reg = <0x200>;
led@0 {
- label = "red";
+ color = <LED_COLOR_ID_RED>;
reg = <0x0>;
};
led@1 {
- label = "green";
+ color = <LED_COLOR_ID_GREEN>;
reg = <0x1>;
};
led@2 {
- label = "blue";
+ color = <LED_COLOR_ID_BLUE>;
reg = <0x2>;
};
};
diff --git a/Documentation/devicetree/bindings/mailbox/amlogic,meson-gxbb-mhu.yaml b/Documentation/devicetree/bindings/mailbox/amlogic,meson-gxbb-mhu.yaml
new file mode 100644
index 0000000..3192805
--- /dev/null
+++ b/Documentation/devicetree/bindings/mailbox/amlogic,meson-gxbb-mhu.yaml
@@ -0,0 +1,52 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+# Copyright 2019 BayLibre, SAS
+%YAML 1.2
+---
+$id: "http://devicetree.org/schemas/mailbox/amlogic,meson-gxbb-mhu.yaml#"
+$schema: "http://devicetree.org/meta-schemas/core.yaml#"
+
+title: Amlogic Meson Message-Handling-Unit Controller
+
+maintainers:
+ - Neil Armstrong <narmstrong@baylibre.com>
+
+description: |
+ The Amlogic's Meson SoCs Message-Handling-Unit (MHU) is a mailbox controller
+ that has 3 independent channels/links to communicate with remote processor(s).
+ MHU links are hardwired on a platform. A link raises interrupt for any
+ received data. However, there is no specified way of knowing if the sent
+ data has been read by the remote. This driver assumes the sender polls
+ STAT register and the remote clears it after having read the data.
+
+properties:
+ compatible:
+ enum:
+ - amlogic,meson-gxbb-mhu
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ minItems: 3
+ description:
+ Contains the interrupt information corresponding to each of the 3 links
+ of MHU.
+
+ "#mbox-cells":
+ const: 1
+
+required:
+ - compatible
+ - reg
+ - interrupts
+ - "#mbox-cells"
+
+examples:
+ - |
+ mailbox@c883c404 {
+ compatible = "amlogic,meson-gxbb-mhu";
+ reg = <0xc883c404 0x4c>;
+ interrupts = <208>, <209>, <210>;
+ #mbox-cells = <1>;
+ };
+
diff --git a/Documentation/devicetree/bindings/mailbox/meson-mhu.txt b/Documentation/devicetree/bindings/mailbox/meson-mhu.txt
deleted file mode 100644
index a530310..0000000
--- a/Documentation/devicetree/bindings/mailbox/meson-mhu.txt
+++ /dev/null
@@ -1,34 +0,0 @@
-Amlogic Meson MHU Mailbox Driver
-================================
-
-The Amlogic's Meson SoCs Message-Handling-Unit (MHU) is a mailbox controller
-that has 3 independent channels/links to communicate with remote processor(s).
-MHU links are hardwired on a platform. A link raises interrupt for any
-received data. However, there is no specified way of knowing if the sent
-data has been read by the remote. This driver assumes the sender polls
-STAT register and the remote clears it after having read the data.
-
-Mailbox Device Node:
-====================
-
-Required properties:
---------------------
-- compatible: Shall be "amlogic,meson-gxbb-mhu"
-- reg: Contains the mailbox register address range (base
- address and length)
-- #mbox-cells Shall be 1 - the index of the channel needed.
-- interrupts: Contains the interrupt information corresponding to
- each of the 2 links of MHU.
-
-Example:
---------
-
- mailbox: mailbox@c883c404 {
- #mbox-cells = <1>;
- compatible = "amlogic,meson-gxbb-mhu";
- reg = <0 0xc883c404 0 0x4c>;
- interrupts = <0 208 IRQ_TYPE_EDGE_RISING>,
- <0 209 IRQ_TYPE_EDGE_RISING>,
- <0 210 IRQ_TYPE_EDGE_RISING>;
- #mbox-cells = <1>;
- };
diff --git a/Documentation/devicetree/bindings/mailbox/mtk-gce.txt b/Documentation/devicetree/bindings/mailbox/mtk-gce.txt
index 7d72b21..7b13787 100644
--- a/Documentation/devicetree/bindings/mailbox/mtk-gce.txt
+++ b/Documentation/devicetree/bindings/mailbox/mtk-gce.txt
@@ -9,7 +9,7 @@
mailbox.txt for generic information about mailbox device-tree bindings.
Required properties:
-- compatible: Must be "mediatek,mt8173-gce"
+- compatible: can be "mediatek,mt8173-gce" or "mediatek,mt8183-gce"
- reg: Address range of the GCE unit
- interrupts: The interrupt signal from the GCE block
- clock: Clocks according to the common clock binding
@@ -25,11 +25,19 @@
Required properties for a client device:
- mboxes: Client use mailbox to communicate with GCE, it should have this
property and list of phandle, mailbox specifiers.
-- mediatek,gce-subsys: u32, specify the sub-system id which is corresponding
- to the register address.
+Optional properties for a client device:
+- mediatek,gce-client-reg: Specify the sub-system id which is corresponding
+ to the register address, it should have this property and list of phandle,
+ sub-system specifiers.
+ <&phandle subsys_number start_offset size>
+ phandle: Label name of a gce node.
+ subsys_number: specify the sub-system id which is corresponding
+ to the register address.
+ start_offset: the start offset of register address that GCE can access.
+ size: the total size of register address that GCE can access.
-Some vaules of properties are defined in 'dt-bindings/gce/mt8173-gce.h'. Such as
-sub-system ids, thread priority, event ids.
+Some vaules of properties are defined in 'dt-bindings/gce/mt8173-gce.h'
+or 'dt-binding/gce/mt8183-gce.h'. Such as sub-system ids, thread priority, event ids.
Example:
@@ -39,7 +47,6 @@
interrupts = <GIC_SPI 135 IRQ_TYPE_LEVEL_LOW>;
clocks = <&infracfg CLK_INFRA_GCE>;
clock-names = "gce";
- thread-num = CMDQ_THR_MAX_COUNT;
#mbox-cells = <3>;
};
@@ -49,9 +56,9 @@
compatible = "mediatek,mt8173-mmsys";
mboxes = <&gce 0 CMDQ_THR_PRIO_LOWEST 1>,
<&gce 1 CMDQ_THR_PRIO_LOWEST 1>;
- mediatek,gce-subsys = <SUBSYS_1400XXXX>;
mutex-event-eof = <CMDQ_EVENT_MUTEX0_STREAM_EOF
CMDQ_EVENT_MUTEX1_STREAM_EOF>;
-
+ mediatek,gce-client-reg = <&gce SUBSYS_1400XXXX 0x3000 0x1000>,
+ <&gce SUBSYS_1401XXXX 0x2000 0x100>;
...
};
diff --git a/Documentation/devicetree/bindings/mailbox/qcom,apcs-kpss-global.txt b/Documentation/devicetree/bindings/mailbox/qcom,apcs-kpss-global.txt
index 1232fc9..0278482a 100644
--- a/Documentation/devicetree/bindings/mailbox/qcom,apcs-kpss-global.txt
+++ b/Documentation/devicetree/bindings/mailbox/qcom,apcs-kpss-global.txt
@@ -12,7 +12,10 @@
"qcom,msm8996-apcs-hmss-global"
"qcom,msm8998-apcs-hmss-global"
"qcom,qcs404-apcs-apps-global"
+ "qcom,sc7180-apss-shared"
"qcom,sdm845-apss-shared"
+ "qcom,sm8150-apss-shared"
+ "qcom,ipq8074-apcs-apps-global"
- reg:
Usage: required
diff --git a/Documentation/devicetree/bindings/media/allwinner,sun4i-a10-csi.yaml b/Documentation/devicetree/bindings/media/allwinner,sun4i-a10-csi.yaml
new file mode 100644
index 0000000..27f38ee
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/allwinner,sun4i-a10-csi.yaml
@@ -0,0 +1,109 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/arm/allwinner,sun4i-a10-csi.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Allwinner A10 CMOS Sensor Interface (CSI) Device Tree Bindings
+
+maintainers:
+ - Chen-Yu Tsai <wens@csie.org>
+ - Maxime Ripard <maxime.ripard@bootlin.com>
+
+description: |-
+ The Allwinner A10 and later has a CMOS Sensor Interface to retrieve
+ frames from a parallel or BT656 sensor.
+
+properties:
+ compatible:
+ const: allwinner,sun7i-a20-csi0
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+ clocks:
+ items:
+ - description: The CSI interface clock
+ - description: The CSI module clock
+ - description: The CSI ISP clock
+ - description: The CSI DRAM clock
+
+ clock-names:
+ items:
+ - const: bus
+ - const: mod
+ - const: isp
+ - const: ram
+
+ resets:
+ maxItems: 1
+
+ # See ./video-interfaces.txt for details
+ port:
+ type: object
+ additionalProperties: false
+
+ properties:
+ endpoint:
+ type: object
+
+ properties:
+ bus-width:
+ enum: [8, 16]
+
+ data-active: true
+ hsync-active: true
+ pclk-sample: true
+ remote-endpoint: true
+ vsync-active: true
+
+ required:
+ - bus-width
+ - data-active
+ - hsync-active
+ - pclk-sample
+ - remote-endpoint
+ - vsync-active
+
+ required:
+ - endpoint
+
+required:
+ - compatible
+ - reg
+ - interrupts
+ - clocks
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+ #include <dt-bindings/clock/sun7i-a20-ccu.h>
+ #include <dt-bindings/reset/sun4i-a10-ccu.h>
+
+ csi0: csi@1c09000 {
+ compatible = "allwinner,sun7i-a20-csi0";
+ reg = <0x01c09000 0x1000>;
+ interrupts = <GIC_SPI 42 IRQ_TYPE_LEVEL_HIGH>;
+ clocks = <&ccu CLK_AHB_CSI0>, <&ccu CLK_CSI0>,
+ <&ccu CLK_CSI_SCLK>, <&ccu CLK_DRAM_CSI0>;
+ clock-names = "bus", "mod", "isp", "ram";
+ resets = <&ccu RST_CSI0>;
+
+ port {
+ csi_from_ov5640: endpoint {
+ remote-endpoint = <&ov5640_to_csi>;
+ bus-width = <8>;
+ hsync-active = <1>; /* Active high */
+ vsync-active = <0>; /* Active low */
+ data-active = <1>; /* Active high */
+ pclk-sample = <1>; /* Rising */
+ };
+ };
+ };
+
+...
diff --git a/Documentation/devicetree/bindings/media/allwinner,sun4i-a10-ir.yaml b/Documentation/devicetree/bindings/media/allwinner,sun4i-a10-ir.yaml
new file mode 100644
index 0000000..98c1bdd
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/allwinner,sun4i-a10-ir.yaml
@@ -0,0 +1,80 @@
+# SPDX-License-Identifier: GPL-2.0
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/media/allwinner,sun4i-a10-ir.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Allwinner A10 Infrared Controller Device Tree Bindings
+
+maintainers:
+ - Chen-Yu Tsai <wens@csie.org>
+ - Maxime Ripard <maxime.ripard@bootlin.com>
+
+allOf:
+ - $ref: "rc.yaml#"
+
+properties:
+ compatible:
+ oneOf:
+ - const: allwinner,sun4i-a10-ir
+ - const: allwinner,sun5i-a13-ir
+ - items:
+ - const: allwinner,sun8i-a83t-ir
+ - const: allwinner,sun6i-a31-ir
+ - const: allwinner,sun6i-a31-ir
+ - items:
+ - const: allwinner,sun50i-a64-ir
+ - const: allwinner,sun6i-a31-ir
+ - items:
+ - const: allwinner,sun50i-h6-ir
+ - const: allwinner,sun6i-a31-ir
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+ clocks:
+ items:
+ - description: Bus Clock
+ - description: Module Clock
+
+ clock-names:
+ items:
+ - const: apb
+ - const: ir
+
+ resets:
+ maxItems: 1
+
+ clock-frequency:
+ default: 8000000
+ description:
+ IR Receiver clock frequency, in Hertz.
+
+required:
+ - compatible
+ - reg
+ - interrupts
+ - clocks
+ - clock-names
+
+# FIXME: We should set it, but it would report all the generic
+# properties as additional properties.
+# additionalProperties: false
+
+examples:
+ - |
+ ir0: ir@1c21800 {
+ compatible = "allwinner,sun4i-a10-ir";
+ clocks = <&apb0_gates 6>, <&ir0_clk>;
+ clock-names = "apb", "ir";
+ clock-frequency = <3000000>;
+ resets = <&apb0_rst 1>;
+ interrupts = <0 5 1>;
+ reg = <0x01C21800 0x40>;
+ linux,rc-map-name = "rc-rc6-mce";
+ };
+
+...
diff --git a/Documentation/devicetree/bindings/media/amlogic,vdec.txt b/Documentation/devicetree/bindings/media/amlogic,vdec.txt
index aabdd01..9b6aace 100644
--- a/Documentation/devicetree/bindings/media/amlogic,vdec.txt
+++ b/Documentation/devicetree/bindings/media/amlogic,vdec.txt
@@ -26,6 +26,7 @@
- GXBB (S905) : "amlogic,gxbb-vdec"
- GXL (S905X, S905D) : "amlogic,gxl-vdec"
- GXM (S912) : "amlogic,gxm-vdec"
+ followed by the common "amlogic,gx-vdec"
- reg: base address and size of he following memory-mapped regions :
- dos
- esparser
@@ -47,8 +48,8 @@
Example:
-vdec: video-decoder@c8820000 {
- compatible = "amlogic,gxbb-vdec";
+vdec: video-codec@c8820000 {
+ compatible = "amlogic,gxbb-vdec", "amlogic,gx-vdec";
reg = <0x0 0xc8820000 0x0 0x10000>,
<0x0 0xc110a580 0x0 0xe4>;
reg-names = "dos", "esparser";
diff --git a/Documentation/devicetree/bindings/media/cdns,csi2tx.txt b/Documentation/devicetree/bindings/media/cdns,csi2tx.txt
index 459c6e3..751b9ed 100644
--- a/Documentation/devicetree/bindings/media/cdns,csi2tx.txt
+++ b/Documentation/devicetree/bindings/media/cdns,csi2tx.txt
@@ -5,7 +5,8 @@
4 CSI lanes in output, and up to 4 different pixel streams in input.
Required properties:
- - compatible: must be set to "cdns,csi2tx"
+ - compatible: must be set to "cdns,csi2tx" or "cdns,csi2tx-1.3"
+ for version 1.3 of the controller, "cdns,csi2tx-2.1" for v2.1
- reg: base address and size of the memory mapped region
- clocks: phandles to the clocks driving the controller
- clock-names: must contain:
diff --git a/Documentation/devicetree/bindings/media/i2c/nokia,smia.txt b/Documentation/devicetree/bindings/media/i2c/nokia,smia.txt
index 8ee7c79..c3c3479 100644
--- a/Documentation/devicetree/bindings/media/i2c/nokia,smia.txt
+++ b/Documentation/devicetree/bindings/media/i2c/nokia,smia.txt
@@ -7,6 +7,9 @@
More detailed documentation can be found in
Documentation/devicetree/bindings/media/video-interfaces.txt .
+The device node should contain a "port" node which may contain one or more
+endpoint nodes, in accordance with video interface bindings defined in
+Documentation/devicetree/bindings/media/video-interfaces.txt .
Mandatory properties
--------------------
@@ -37,9 +40,7 @@
Endpoint node mandatory properties
----------------------------------
-- clock-lanes: <0>
- data-lanes: <1..n>
-- remote-endpoint: A phandle to the bus receiver's endpoint node.
Example
@@ -48,7 +49,7 @@
&i2c2 {
clock-frequency = <400000>;
- smiapp_1: camera@10 {
+ camera-sensor@10 {
compatible = "nokia,smia";
reg = <0x10>;
reset-gpios = <&gpio3 20 0>;
@@ -58,8 +59,7 @@
nokia,nvm-size = <512>; /* 8 * 64 */
link-frequencies = /bits/ 64 <199200000 210000000 499200000>;
port {
- smiapp_1_1: endpoint {
- clock-lanes = <0>;
+ smiapp_ep: endpoint {
data-lanes = <1 2>;
remote-endpoint = <&csi2a_ep>;
};
diff --git a/Documentation/devicetree/bindings/media/imx7-csi.txt b/Documentation/devicetree/bindings/media/imx7-csi.txt
index 443aef07..d80ceef 100644
--- a/Documentation/devicetree/bindings/media/imx7-csi.txt
+++ b/Documentation/devicetree/bindings/media/imx7-csi.txt
@@ -9,7 +9,7 @@
Required properties:
-- compatible : "fsl,imx7-csi";
+- compatible : "fsl,imx7-csi" or "fsl,imx6ul-csi";
- reg : base address and length of the register set for the device;
- interrupts : should contain CSI interrupt;
- clocks : list of clock specifiers, see
diff --git a/Documentation/devicetree/bindings/media/meson-ao-cec.txt b/Documentation/devicetree/bindings/media/meson-ao-cec.txt
index c67fc41..ad92ee4 100644
--- a/Documentation/devicetree/bindings/media/meson-ao-cec.txt
+++ b/Documentation/devicetree/bindings/media/meson-ao-cec.txt
@@ -5,10 +5,12 @@
Required properties:
- compatible : value should be following depending on the SoC :
- For GXBB, GXL, GXM and G12A (AO_CEC_A module) :
+ For GXBB, GXL, GXM, G12A and SM1 (AO_CEC_A module) :
"amlogic,meson-gx-ao-cec"
For G12A (AO_CEC_B module) :
"amlogic,meson-g12a-ao-cec"
+ For SM1 (AO_CEC_B module) :
+ "amlogic,meson-sm1-ao-cec"
- reg : Physical base address of the IP registers and length of memory
mapped region.
@@ -16,9 +18,9 @@
- interrupts : AO-CEC interrupt number to the CPU.
- clocks : from common clock binding: handle to AO-CEC clock.
- clock-names : from common clock binding, must contain :
- For GXBB, GXL, GXM and G12A (AO_CEC_A module) :
+ For GXBB, GXL, GXM, G12A and SM1 (AO_CEC_A module) :
- "core"
- For G12A (AO_CEC_B module) :
+ For G12A, SM1 (AO_CEC_B module) :
- "oscin"
corresponding to entry in the clocks property.
- hdmi-phandle: phandle to the HDMI controller
diff --git a/Documentation/devicetree/bindings/media/nvidia,tegra-vde.txt b/Documentation/devicetree/bindings/media/nvidia,tegra-vde.txt
index 7302e94..602169b 100644
--- a/Documentation/devicetree/bindings/media/nvidia,tegra-vde.txt
+++ b/Documentation/devicetree/bindings/media/nvidia,tegra-vde.txt
@@ -35,6 +35,7 @@
- resets : Must contain an entry for each entry in reset-names.
- reset-names : Must include the following entries:
- mc
+- iommus: Must contain phandle to the IOMMU device node.
Example:
@@ -59,4 +60,5 @@
clocks = <&tegra_car TEGRA20_CLK_VDE>;
reset-names = "vde", "mc";
resets = <&tegra_car 61>, <&mc TEGRA20_MC_RESET_VDE>;
+ iommus = <&mc TEGRA_SWGROUP_VDE>;
};
diff --git a/Documentation/devicetree/bindings/media/rc.txt b/Documentation/devicetree/bindings/media/rc.txt
index d3e7a01..be629f7 100644
--- a/Documentation/devicetree/bindings/media/rc.txt
+++ b/Documentation/devicetree/bindings/media/rc.txt
@@ -1,117 +1 @@
-The following properties are common to the infrared remote controllers:
-
-- linux,rc-map-name: string, specifies the scancode/key mapping table
- defined in-kernel for the remote controller. Support values are:
- * "rc-adstech-dvb-t-pci"
- * "rc-alink-dtu-m"
- * "rc-anysee"
- * "rc-apac-viewcomp"
- * "rc-asus-pc39"
- * "rc-asus-ps3-100"
- * "rc-ati-tv-wonder-hd-600"
- * "rc-ati-x10"
- * "rc-avermedia-a16d"
- * "rc-avermedia-cardbus"
- * "rc-avermedia-dvbt"
- * "rc-avermedia-m135a"
- * "rc-avermedia-m733a-rm-k6"
- * "rc-avermedia-rm-ks"
- * "rc-avermedia"
- * "rc-avertv-303"
- * "rc-azurewave-ad-tu700"
- * "rc-behold-columbus"
- * "rc-behold"
- * "rc-budget-ci-old"
- * "rc-cec"
- * "rc-cinergy-1400"
- * "rc-cinergy"
- * "rc-delock-61959"
- * "rc-dib0700-nec"
- * "rc-dib0700-rc5"
- * "rc-digitalnow-tinytwin"
- * "rc-digittrade"
- * "rc-dm1105-nec"
- * "rc-dntv-live-dvbt-pro"
- * "rc-dntv-live-dvb-t"
- * "rc-dtt200u"
- * "rc-dvbsky"
- * "rc-empty"
- * "rc-em-terratec"
- * "rc-encore-enltv2"
- * "rc-encore-enltv-fm53"
- * "rc-encore-enltv"
- * "rc-evga-indtube"
- * "rc-eztv"
- * "rc-flydvb"
- * "rc-flyvideo"
- * "rc-fusionhdtv-mce"
- * "rc-gadmei-rm008z"
- * "rc-geekbox"
- * "rc-genius-tvgo-a11mce"
- * "rc-gotview7135"
- * "rc-hauppauge"
- * "rc-imon-mce"
- * "rc-imon-pad"
- * "rc-iodata-bctv7e"
- * "rc-it913x-v1"
- * "rc-it913x-v2"
- * "rc-kaiomy"
- * "rc-kworld-315u"
- * "rc-kworld-pc150u"
- * "rc-kworld-plus-tv-analog"
- * "rc-leadtek-y04g0051"
- * "rc-lirc"
- * "rc-lme2510"
- * "rc-manli"
- * "rc-medion-x10"
- * "rc-medion-x10-digitainer"
- * "rc-medion-x10-or2x"
- * "rc-msi-digivox-ii"
- * "rc-msi-digivox-iii"
- * "rc-msi-tvanywhere-plus"
- * "rc-msi-tvanywhere"
- * "rc-nebula"
- * "rc-nec-terratec-cinergy-xs"
- * "rc-norwood"
- * "rc-npgtech"
- * "rc-pctv-sedna"
- * "rc-pinnacle-color"
- * "rc-pinnacle-grey"
- * "rc-pinnacle-pctv-hd"
- * "rc-pixelview-new"
- * "rc-pixelview"
- * "rc-pixelview-002t"
- * "rc-pixelview-mk12"
- * "rc-powercolor-real-angel"
- * "rc-proteus-2309"
- * "rc-purpletv"
- * "rc-pv951"
- * "rc-hauppauge"
- * "rc-rc5-tv"
- * "rc-rc6-mce"
- * "rc-real-audio-220-32-keys"
- * "rc-reddo"
- * "rc-snapstream-firefly"
- * "rc-streamzap"
- * "rc-tbs-nec"
- * "rc-technisat-ts35"
- * "rc-technisat-usb2"
- * "rc-terratec-cinergy-c-pci"
- * "rc-terratec-cinergy-s2-hd"
- * "rc-terratec-cinergy-xs"
- * "rc-terratec-slim"
- * "rc-terratec-slim-2"
- * "rc-tevii-nec"
- * "rc-tivo"
- * "rc-total-media-in-hand"
- * "rc-total-media-in-hand-02"
- * "rc-trekstor"
- * "rc-tt-1500"
- * "rc-twinhan-dtv-cab-ci"
- * "rc-twinhan1027"
- * "rc-videomate-k100"
- * "rc-videomate-s350"
- * "rc-videomate-tv-pvr"
- * "rc-winfast"
- * "rc-winfast-usbii-deluxe"
- * "rc-su3000"
+This file has been moved to rc.yaml.
diff --git a/Documentation/devicetree/bindings/media/rc.yaml b/Documentation/devicetree/bindings/media/rc.yaml
new file mode 100644
index 0000000..3d5c154
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/rc.yaml
@@ -0,0 +1,145 @@
+# SPDX-License-Identifier: GPL-2.0
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/media/rc.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Generic Infrared Remote Controller Device Tree Bindings
+
+maintainers:
+ - Mauro Carvalho Chehab <mchehab@kernel.org>
+ - Sean Young <sean@mess.org>
+
+properties:
+ $nodename:
+ pattern: "^ir(@[a-f0-9]+)?$"
+
+ linux,rc-map-name:
+ description:
+ Specifies the scancode/key mapping table defined in-kernel for
+ the remote controller.
+ allOf:
+ - $ref: '/schemas/types.yaml#/definitions/string'
+ - enum:
+ - rc-adstech-dvb-t-pci
+ - rc-alink-dtu-m
+ - rc-anysee
+ - rc-apac-viewcomp
+ - rc-astrometa-t2hybrid
+ - rc-asus-pc39
+ - rc-asus-ps3-100
+ - rc-ati-tv-wonder-hd-600
+ - rc-ati-x10
+ - rc-avermedia
+ - rc-avermedia-a16d
+ - rc-avermedia-cardbus
+ - rc-avermedia-dvbt
+ - rc-avermedia-m135a
+ - rc-avermedia-m733a-rm-k6
+ - rc-avermedia-rm-ks
+ - rc-avertv-303
+ - rc-azurewave-ad-tu700
+ - rc-behold
+ - rc-behold-columbus
+ - rc-budget-ci-old
+ - rc-cec
+ - rc-cinergy
+ - rc-cinergy-1400
+ - rc-d680-dmb
+ - rc-delock-61959
+ - rc-dib0700-nec
+ - rc-dib0700-rc5
+ - rc-digitalnow-tinytwin
+ - rc-digittrade
+ - rc-dm1105-nec
+ - rc-dntv-live-dvb-t
+ - rc-dntv-live-dvbt-pro
+ - rc-dtt200u
+ - rc-dvbsky
+ - rc-dvico-mce
+ - rc-dvico-portable
+ - rc-em-terratec
+ - rc-empty
+ - rc-encore-enltv
+ - rc-encore-enltv-fm53
+ - rc-encore-enltv2
+ - rc-evga-indtube
+ - rc-eztv
+ - rc-flydvb
+ - rc-flyvideo
+ - rc-fusionhdtv-mce
+ - rc-gadmei-rm008z
+ - rc-geekbox
+ - rc-genius-tvgo-a11mce
+ - rc-gotview7135
+ - rc-hauppauge
+ - rc-hauppauge
+ - rc-hisi-poplar
+ - rc-hisi-tv-demo
+ - rc-imon-mce
+ - rc-imon-pad
+ - rc-imon-rsc
+ - rc-iodata-bctv7e
+ - rc-it913x-v1
+ - rc-it913x-v2
+ - rc-kaiomy
+ - rc-kworld-315u
+ - rc-kworld-pc150u
+ - rc-kworld-plus-tv-analog
+ - rc-leadtek-y04g0051
+ - rc-lme2510
+ - rc-manli
+ - rc-medion-x10
+ - rc-medion-x10-digitainer
+ - rc-medion-x10-or2x
+ - rc-msi-digivox-ii
+ - rc-msi-digivox-iii
+ - rc-msi-tvanywhere
+ - rc-msi-tvanywhere-plus
+ - rc-nebula
+ - rc-nec-terratec-cinergy-xs
+ - rc-norwood
+ - rc-npgtech
+ - rc-pctv-sedna
+ - rc-pinnacle-color
+ - rc-pinnacle-grey
+ - rc-pinnacle-pctv-hd
+ - rc-pixelview
+ - rc-pixelview-002t
+ - rc-pixelview-mk12
+ - rc-pixelview-new
+ - rc-powercolor-real-angel
+ - rc-proteus-2309
+ - rc-purpletv
+ - rc-pv951
+ - rc-rc5-tv
+ - rc-rc6-mce
+ - rc-real-audio-220-32-keys
+ - rc-reddo
+ - rc-snapstream-firefly
+ - rc-streamzap
+ - rc-su3000
+ - rc-tango
+ - rc-tbs-nec
+ - rc-technisat-ts35
+ - rc-technisat-usb2
+ - rc-terratec-cinergy-c-pci
+ - rc-terratec-cinergy-s2-hd
+ - rc-terratec-cinergy-xs
+ - rc-terratec-slim
+ - rc-terratec-slim-2
+ - rc-tevii-nec
+ - rc-tivo
+ - rc-total-media-in-hand
+ - rc-total-media-in-hand-02
+ - rc-trekstor
+ - rc-tt-1500
+ - rc-twinhan-dtv-cab-ci
+ - rc-twinhan1027
+ - rc-videomate-k100
+ - rc-videomate-s350
+ - rc-videomate-tv-pvr
+ - rc-winfast
+ - rc-winfast-usbii-deluxe
+ - rc-xbox-dvd
+ - rc-zx-irdec
diff --git a/Documentation/devicetree/bindings/media/renesas,rcar-csi2.txt b/Documentation/devicetree/bindings/media/renesas,csi2.txt
similarity index 100%
rename from Documentation/devicetree/bindings/media/renesas,rcar-csi2.txt
rename to Documentation/devicetree/bindings/media/renesas,csi2.txt
diff --git a/Documentation/devicetree/bindings/media/rcar_imr.txt b/Documentation/devicetree/bindings/media/renesas,imr.txt
similarity index 100%
rename from Documentation/devicetree/bindings/media/rcar_imr.txt
rename to Documentation/devicetree/bindings/media/renesas,imr.txt
diff --git a/Documentation/devicetree/bindings/media/rcar_vin.txt b/Documentation/devicetree/bindings/media/renesas,vin.txt
similarity index 100%
rename from Documentation/devicetree/bindings/media/rcar_vin.txt
rename to Documentation/devicetree/bindings/media/renesas,vin.txt
diff --git a/Documentation/devicetree/bindings/media/rockchip-vpu.txt b/Documentation/devicetree/bindings/media/rockchip-vpu.txt
index 35dc464..339252d 100644
--- a/Documentation/devicetree/bindings/media/rockchip-vpu.txt
+++ b/Documentation/devicetree/bindings/media/rockchip-vpu.txt
@@ -1,14 +1,17 @@
device-tree bindings for rockchip VPU codec
Rockchip (Video Processing Unit) present in various Rockchip platforms,
-such as RK3288 and RK3399.
+such as RK3288, RK3328 and RK3399.
Required properties:
- compatible: value should be one of the following
"rockchip,rk3288-vpu";
+ "rockchip,rk3328-vpu";
"rockchip,rk3399-vpu";
- interrupts: encoding and decoding interrupt specifiers
-- interrupt-names: should be "vepu" and "vdpu"
+- interrupt-names: should be
+ "vepu", "vdpu" on RK3288 and RK3399,
+ "vdpu" on RK3328.
- clocks: phandle to VPU aclk, hclk clocks
- clock-names: should be "aclk" and "hclk"
- power-domains: phandle to power domain node
@@ -27,3 +30,14 @@
power-domains = <&power RK3288_PD_VIDEO>;
iommus = <&vpu_mmu>;
};
+
+ vpu: video-codec@ff350000 {
+ compatible = "rockchip,rk3328-vpu";
+ reg = <0x0 0xff350000 0x0 0x800>;
+ interrupts = <GIC_SPI 9 IRQ_TYPE_LEVEL_HIGH>;
+ interrupt-names = "vdpu";
+ clocks = <&cru ACLK_VPU>, <&cru HCLK_VPU>;
+ clock-names = "aclk", "hclk";
+ power-domains = <&power RK3328_PD_VPU>;
+ iommus = <&vpu_mmu>;
+ };
diff --git a/Documentation/devicetree/bindings/media/sunxi-ir.txt b/Documentation/devicetree/bindings/media/sunxi-ir.txt
deleted file mode 100644
index 2780989..0000000
--- a/Documentation/devicetree/bindings/media/sunxi-ir.txt
+++ /dev/null
@@ -1,28 +0,0 @@
-Device-Tree bindings for SUNXI IR controller found in sunXi SoC family
-
-Required properties:
-- compatible : "allwinner,sun4i-a10-ir" or "allwinner,sun5i-a13-ir"
-- clocks : list of clock specifiers, corresponding to
- entries in clock-names property;
-- clock-names : should contain "apb" and "ir" entries;
-- interrupts : should contain IR IRQ number;
-- reg : should contain IO map address for IR.
-
-Optional properties:
-- linux,rc-map-name: see rc.txt file in the same directory.
-- resets : phandle + reset specifier pair
-- clock-frequency : IR Receiver clock frequency, in Hertz. Defaults to 8 MHz
- if missing.
-
-Example:
-
-ir0: ir@1c21800 {
- compatible = "allwinner,sun4i-a10-ir";
- clocks = <&apb0_gates 6>, <&ir0_clk>;
- clock-names = "apb", "ir";
- clock-frequency = <3000000>;
- resets = <&apb0_rst 1>;
- interrupts = <0 5 1>;
- reg = <0x01C21800 0x40>;
- linux,rc-map-name = "rc-rc6-mce";
-};
diff --git a/Documentation/devicetree/bindings/memory-controllers/mediatek,smi-common.txt b/Documentation/devicetree/bindings/memory-controllers/mediatek,smi-common.txt
index e937ddd..b478ade 100644
--- a/Documentation/devicetree/bindings/memory-controllers/mediatek,smi-common.txt
+++ b/Documentation/devicetree/bindings/memory-controllers/mediatek,smi-common.txt
@@ -2,9 +2,10 @@
The hardware block diagram please check bindings/iommu/mediatek,iommu.txt
-Mediatek SMI have two generations of HW architecture, mt2712 and mt8173 use
-the second generation of SMI HW while mt2701 uses the first generation HW of
-SMI.
+Mediatek SMI have two generations of HW architecture, here is the list
+which generation the SoCs use:
+generation 1: mt2701 and mt7623.
+generation 2: mt2712, mt8173 and mt8183.
There's slight differences between the two SMI, for generation 2, the
register which control the iommu port is at each larb's register base. But
@@ -19,6 +20,7 @@
"mediatek,mt2712-smi-common"
"mediatek,mt7623-smi-common", "mediatek,mt2701-smi-common"
"mediatek,mt8173-smi-common"
+ "mediatek,mt8183-smi-common"
- reg : the register and size of the SMI block.
- power-domains : a phandle to the power domain of this local arbiter.
- clocks : Must contain an entry for each entry in clock-names.
@@ -30,6 +32,10 @@
They may be the same if both source clocks are the same.
- "async" : asynchronous clock, it help transform the smi clock into the emi
clock domain, this clock is only needed by generation 1 smi HW.
+ and these 2 option clocks for generation 2 smi HW:
+ - "gals0": the path0 clock of GALS(Global Async Local Sync).
+ - "gals1": the path1 clock of GALS(Global Async Local Sync).
+ Here is the list which has this GALS: mt8183.
Example:
smi_common: smi@14022000 {
diff --git a/Documentation/devicetree/bindings/memory-controllers/mediatek,smi-larb.txt b/Documentation/devicetree/bindings/memory-controllers/mediatek,smi-larb.txt
index 94eddca..4b369b3 100644
--- a/Documentation/devicetree/bindings/memory-controllers/mediatek,smi-larb.txt
+++ b/Documentation/devicetree/bindings/memory-controllers/mediatek,smi-larb.txt
@@ -8,6 +8,7 @@
"mediatek,mt2712-smi-larb"
"mediatek,mt7623-smi-larb", "mediatek,mt2701-smi-larb"
"mediatek,mt8173-smi-larb"
+ "mediatek,mt8183-smi-larb"
- reg : the register and size of this local arbiter.
- mediatek,smi : a phandle to the smi_common node.
- power-domains : a phandle to the power domain of this local arbiter.
@@ -16,6 +17,9 @@
- "apb" : Advanced Peripheral Bus clock, It's the clock for setting
the register.
- "smi" : It's the clock for transfer data and command.
+ and this optional clock name:
+ - "gals": the clock for GALS(Global Async Local Sync).
+ Here is the list which has this GALS: mt8183.
Required property for mt2701, mt2712 and mt7623:
- mediatek,larb-id :the hardware id of this larb.
diff --git a/Documentation/devicetree/bindings/memory-controllers/renesas-memory-controllers.txt b/Documentation/devicetree/bindings/memory-controllers/renesas,dbsc.txt
similarity index 100%
rename from Documentation/devicetree/bindings/memory-controllers/renesas-memory-controllers.txt
rename to Documentation/devicetree/bindings/memory-controllers/renesas,dbsc.txt
diff --git a/Documentation/devicetree/bindings/mfd/allwinner,sun4i-a10-ts.yaml b/Documentation/devicetree/bindings/mfd/allwinner,sun4i-a10-ts.yaml
new file mode 100644
index 0000000..4b1a09a
--- /dev/null
+++ b/Documentation/devicetree/bindings/mfd/allwinner,sun4i-a10-ts.yaml
@@ -0,0 +1,76 @@
+# SPDX-License-Identifier: GPL-2.0
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/mfd/allwinner,sun4i-a10-ts.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Allwinner A10 Resistive Touchscreen Controller Device Tree Bindings
+
+maintainers:
+ - Chen-Yu Tsai <wens@csie.org>
+ - Maxime Ripard <maxime.ripard@bootlin.com>
+
+properties:
+ "#thermal-sensor-cells":
+ const: 0
+
+ compatible:
+ enum:
+ - allwinner,sun4i-a10-ts
+ - allwinner,sun5i-a13-ts
+ - allwinner,sun6i-a31-ts
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+ allwinner,ts-attached:
+ $ref: /schemas/types.yaml#/definitions/flag
+ description: A touchscreen is attached to the controller
+
+ allwinner,tp-sensitive-adjust:
+ allOf:
+ - $ref: /schemas/types.yaml#/definitions/uint32
+ - minimum: 0
+ maximum: 15
+ default: 15
+ description: Sensitivity of pen down detection
+
+ allwinner,filter-type:
+ allOf:
+ - $ref: /schemas/types.yaml#/definitions/uint32
+ - minimum: 0
+ maximum: 3
+ default: 1
+ description: |
+ Select median and averaging filter. Sample used for median /
+ averaging filter:
+ 0: 4/2
+ 1: 5/3
+ 2: 8/4
+ 3: 16/8
+
+required:
+ - "#thermal-sensor-cells"
+ - compatible
+ - reg
+ - interrupts
+
+additionalProperties: false
+
+examples:
+ - |
+ rtp: rtp@1c25000 {
+ compatible = "allwinner,sun4i-a10-ts";
+ reg = <0x01c25000 0x100>;
+ interrupts = <29>;
+ allwinner,ts-attached;
+ #thermal-sensor-cells = <0>;
+ /* sensitive/noisy touch panel */
+ allwinner,tp-sensitive-adjust = <0>;
+ allwinner,filter-type = <3>;
+ };
+
+...
diff --git a/Documentation/devicetree/bindings/mfd/aspeed-scu.txt b/Documentation/devicetree/bindings/mfd/aspeed-scu.txt
index ce8cf0e..4d92c0b 100644
--- a/Documentation/devicetree/bindings/mfd/aspeed-scu.txt
+++ b/Documentation/devicetree/bindings/mfd/aspeed-scu.txt
@@ -4,9 +4,7 @@
Required properties:
- compatible: One of:
"aspeed,ast2400-scu", "syscon", "simple-mfd"
- "aspeed,g4-scu", "syscon", "simple-mfd"
"aspeed,ast2500-scu", "syscon", "simple-mfd"
- "aspeed,g5-scu", "syscon", "simple-mfd"
- reg: contains the offset and length of the SCU memory region
- #clock-cells: should be set to <1> - the system controller is also a
diff --git a/Documentation/devicetree/bindings/mfd/mt6397.txt b/Documentation/devicetree/bindings/mfd/mt6397.txt
index 0ebd08a..a9b105a 100644
--- a/Documentation/devicetree/bindings/mfd/mt6397.txt
+++ b/Documentation/devicetree/bindings/mfd/mt6397.txt
@@ -8,11 +8,12 @@
- Clock
- LED
- Keys
+- Power controller
It is interfaced to host controller using SPI interface by a proprietary hardware
called PMIC wrapper or pwrap. MT6397/MT6323 MFD is a child device of pwrap.
See the following for pwarp node definitions:
-Documentation/devicetree/bindings/soc/mediatek/pwrap.txt
+../soc/mediatek/pwrap.txt
This document describes the binding for MFD device and its sub module.
@@ -22,14 +23,16 @@
Optional subnodes:
- rtc
- Required properties:
+ Required properties: Should be one of follows
+ - compatible: "mediatek,mt6323-rtc"
- compatible: "mediatek,mt6397-rtc"
+ For details, see ../rtc/rtc-mt6397.txt
- regulators
Required properties:
- compatible: "mediatek,mt6397-regulator"
- see Documentation/devicetree/bindings/regulator/mt6397-regulator.txt
+ see ../regulator/mt6397-regulator.txt
- compatible: "mediatek,mt6323-regulator"
- see Documentation/devicetree/bindings/regulator/mt6323-regulator.txt
+ see ../regulator/mt6323-regulator.txt
- codec
Required properties:
- compatible: "mediatek,mt6397-codec"
@@ -39,12 +42,17 @@
- led
Required properties:
- compatible: "mediatek,mt6323-led"
- see Documentation/devicetree/bindings/leds/leds-mt6323.txt
+ see ../leds/leds-mt6323.txt
- keys
Required properties:
- compatible: "mediatek,mt6397-keys" or "mediatek,mt6323-keys"
- see Documentation/devicetree/bindings/input/mtk-pmic-keys.txt
+ see ../input/mtk-pmic-keys.txt
+
+- power-controller
+ Required properties:
+ - compatible: "mediatek,mt6323-pwrc"
+ For details, see ../power/reset/mt6323-poweroff.txt
Example:
pwrap: pwrap@1000f000 {
diff --git a/Documentation/devicetree/bindings/mfd/rn5t618.txt b/Documentation/devicetree/bindings/mfd/rn5t618.txt
index 65c2326..b74e5e9 100644
--- a/Documentation/devicetree/bindings/mfd/rn5t618.txt
+++ b/Documentation/devicetree/bindings/mfd/rn5t618.txt
@@ -14,6 +14,10 @@
"ricoh,rc5t619"
- reg: the I2C slave address of the device
+Optional properties:
+ - system-power-controller:
+ See Documentation/devicetree/bindings/power/power-controller.txt
+
Sub-nodes:
- regulators: the node is required if the regulator functionality is
needed. The valid regulator names are: DCDC1, DCDC2, DCDC3, DCDC4
@@ -28,6 +32,7 @@
pmic@32 {
compatible = "ricoh,rn5t618";
reg = <0x32>;
+ system-power-controller;
regulators {
DCDC1 {
diff --git a/Documentation/devicetree/bindings/mfd/sun4i-gpadc.txt b/Documentation/devicetree/bindings/mfd/sun4i-gpadc.txt
deleted file mode 100644
index 86dd819..0000000
--- a/Documentation/devicetree/bindings/mfd/sun4i-gpadc.txt
+++ /dev/null
@@ -1,59 +0,0 @@
-Allwinner SoCs' GPADC Device Tree bindings
-------------------------------------------
-The Allwinner SoCs all have an ADC that can also act as a thermal sensor
-and sometimes as a touchscreen controller.
-
-Required properties:
- - compatible: "allwinner,sun8i-a33-ths",
- - reg: mmio address range of the chip,
- - #thermal-sensor-cells: shall be 0,
- - #io-channel-cells: shall be 0,
-
-Example:
- ths: ths@1c25000 {
- compatible = "allwinner,sun8i-a33-ths";
- reg = <0x01c25000 0x100>;
- #thermal-sensor-cells = <0>;
- #io-channel-cells = <0>;
- };
-
-sun4i, sun5i and sun6i SoCs are also supported via the older binding:
-
-sun4i resistive touchscreen controller
---------------------------------------
-
-Required properties:
- - compatible: "allwinner,sun4i-a10-ts", "allwinner,sun5i-a13-ts" or
- "allwinner,sun6i-a31-ts"
- - reg: mmio address range of the chip
- - interrupts: interrupt to which the chip is connected
- - #thermal-sensor-cells: shall be 0
-
-Optional properties:
- - allwinner,ts-attached : boolean indicating that an actual touchscreen
- is attached to the controller
- - allwinner,tp-sensitive-adjust : integer (4 bits)
- adjust sensitivity of pen down detection
- between 0 (least sensitive) and 15
- (defaults to 15)
- - allwinner,filter-type : integer (2 bits)
- select median and averaging filter
- samples used for median / averaging filter
- 0: 4/2
- 1: 5/3
- 2: 8/4
- 3: 16/8
- (defaults to 1)
-
-Example:
-
- rtp: rtp@1c25000 {
- compatible = "allwinner,sun4i-a10-ts";
- reg = <0x01c25000 0x100>;
- interrupts = <29>;
- allwinner,ts-attached;
- #thermal-sensor-cells = <0>;
- /* sensitive/noisy touch panel */
- allwinner,tp-sensitive-adjust = <0>;
- allwinner,filter-type = <3>;
- };
diff --git a/Documentation/devicetree/bindings/misc/aspeed-p2a-ctrl.txt b/Documentation/devicetree/bindings/misc/aspeed-p2a-ctrl.txt
index 854bd67..0e1fa5b 100644
--- a/Documentation/devicetree/bindings/misc/aspeed-p2a-ctrl.txt
+++ b/Documentation/devicetree/bindings/misc/aspeed-p2a-ctrl.txt
@@ -26,9 +26,7 @@
- compatible : Should be one of the following:
"aspeed,ast2400-scu", "syscon", "simple-mfd"
- "aspeed,g4-scu", "syscon", "simple-mfd"
"aspeed,ast2500-scu", "syscon", "simple-mfd"
- "aspeed,g5-scu", "syscon", "simple-mfd"
Example
===================
diff --git a/Documentation/devicetree/bindings/mmc/allwinner,sun4i-a10-mmc.yaml b/Documentation/devicetree/bindings/mmc/allwinner,sun4i-a10-mmc.yaml
index df0280e..d2d4308 100644
--- a/Documentation/devicetree/bindings/mmc/allwinner,sun4i-a10-mmc.yaml
+++ b/Documentation/devicetree/bindings/mmc/allwinner,sun4i-a10-mmc.yaml
@@ -30,17 +30,23 @@
- const: allwinner,sun8i-a83t-mmc
- const: allwinner,sun7i-a20-mmc
- items:
- - const: allwinner,sun50i-h6-emmc
- - const: allwinner,sun50i-a64-emmc
- - items:
- - const: allwinner,sun50i-h6-mmc
- - const: allwinner,sun50i-a64-mmc
- - items:
- const: allwinner,sun8i-r40-emmc
- const: allwinner,sun50i-a64-emmc
- items:
- const: allwinner,sun8i-r40-mmc
- const: allwinner,sun50i-a64-mmc
+ - items:
+ - const: allwinner,sun50i-h5-emmc
+ - const: allwinner,sun50i-a64-emmc
+ - items:
+ - const: allwinner,sun50i-h5-mmc
+ - const: allwinner,sun50i-a64-mmc
+ - items:
+ - const: allwinner,sun50i-h6-emmc
+ - const: allwinner,sun50i-a64-emmc
+ - items:
+ - const: allwinner,sun50i-h6-mmc
+ - const: allwinner,sun50i-a64-mmc
reg:
maxItems: 1
diff --git a/Documentation/devicetree/bindings/mmc/arasan,sdhci.txt b/Documentation/devicetree/bindings/mmc/arasan,sdhci.txt
index 1edbb04..7ca0aa7 100644
--- a/Documentation/devicetree/bindings/mmc/arasan,sdhci.txt
+++ b/Documentation/devicetree/bindings/mmc/arasan,sdhci.txt
@@ -17,6 +17,8 @@
For this device it is strongly suggested to include arasan,soc-ctl-syscon.
- "ti,am654-sdhci-5.1", "arasan,sdhci-5.1": TI AM654 MMC PHY
Note: This binding has been deprecated and moved to [5].
+ - "intel,lgm-sdhci-5.1-emmc", "arasan,sdhci-5.1": Intel LGM eMMC PHY
+ For this device it is strongly suggested to include arasan,soc-ctl-syscon.
[5] Documentation/devicetree/bindings/mmc/sdhci-am654.txt
@@ -80,3 +82,18 @@
phy-names = "phy_arasan";
#clock-cells = <0>;
};
+
+ emmc: sdhci@ec700000 {
+ compatible = "intel,lgm-sdhci-5.1-emmc", "arasan,sdhci-5.1";
+ reg = <0xec700000 0x300>;
+ interrupt-parent = <&ioapic1>;
+ interrupts = <44 1>;
+ clocks = <&cgu0 LGM_CLK_EMMC5>, <&cgu0 LGM_CLK_NGI>,
+ <&cgu0 LGM_GCLK_EMMC>;
+ clock-names = "clk_xin", "clk_ahb", "gate";
+ clock-output-names = "emmc_cardclock";
+ #clock-cells = <0>;
+ phys = <&emmc_phy>;
+ phy-names = "phy_arasan";
+ arasan,soc-ctl-syscon = <&sysconf>;
+ };
diff --git a/Documentation/devicetree/bindings/mmc/aspeed,sdhci.yaml b/Documentation/devicetree/bindings/mmc/aspeed,sdhci.yaml
new file mode 100644
index 0000000..200de93
--- /dev/null
+++ b/Documentation/devicetree/bindings/mmc/aspeed,sdhci.yaml
@@ -0,0 +1,106 @@
+# SPDX-License-Identifier: GPL-2.0-or-later
+# Copyright 2019 IBM Corp.
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/mmc/aspeed,sdhci.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: ASPEED SD/SDIO/MMC Controller
+
+maintainers:
+ - Andrew Jeffery <andrew@aj.id.au>
+ - Ryan Chen <ryanchen.aspeed@gmail.com>
+
+description: |+
+ The ASPEED SD/SDIO/eMMC controller exposes two slots implementing the SDIO
+ Host Specification v2.00, with 1 or 4 bit data buses, or an 8 bit data bus if
+ only a single slot is enabled.
+
+ The two slots are supported by a common configuration area. As the SDHCIs for
+ the slots are dependent on the common configuration area, they are described
+ as child nodes.
+
+properties:
+ compatible:
+ enum:
+ - aspeed,ast2400-sd-controller
+ - aspeed,ast2500-sd-controller
+ - aspeed,ast2600-sd-controller
+ reg:
+ maxItems: 1
+ description: Common configuration registers
+ "#address-cells":
+ const: 1
+ "#size-cells":
+ const: 1
+ ranges: true
+ clocks:
+ maxItems: 1
+ description: The SD/SDIO controller clock gate
+
+patternProperties:
+ "^sdhci@[0-9a-f]+$":
+ type: object
+ allOf:
+ - $ref: mmc-controller.yaml
+ properties:
+ compatible:
+ enum:
+ - aspeed,ast2400-sdhci
+ - aspeed,ast2500-sdhci
+ - aspeed,ast2600-sdhci
+ reg:
+ maxItems: 1
+ description: The SDHCI registers
+ clocks:
+ maxItems: 1
+ description: The SD bus clock
+ interrupts:
+ maxItems: 1
+ description: The SD interrupt shared between both slots
+ sdhci,auto-cmd12:
+ type: boolean
+ description: Specifies that controller should use auto CMD12
+ required:
+ - compatible
+ - reg
+ - clocks
+ - interrupts
+
+additionalProperties: false
+
+required:
+ - compatible
+ - reg
+ - "#address-cells"
+ - "#size-cells"
+ - ranges
+ - clocks
+
+examples:
+ - |
+ #include <dt-bindings/clock/aspeed-clock.h>
+ sdc@1e740000 {
+ compatible = "aspeed,ast2500-sd-controller";
+ reg = <0x1e740000 0x100>;
+ #address-cells = <1>;
+ #size-cells = <1>;
+ ranges = <0 0x1e740000 0x20000>;
+ clocks = <&syscon ASPEED_CLK_GATE_SDCLK>;
+
+ sdhci0: sdhci@100 {
+ compatible = "aspeed,ast2500-sdhci";
+ reg = <0x100 0x100>;
+ interrupts = <26>;
+ sdhci,auto-cmd12;
+ clocks = <&syscon ASPEED_CLK_SDIO>;
+ };
+
+ sdhci1: sdhci@200 {
+ compatible = "aspeed,ast2500-sdhci";
+ reg = <0x200 0x100>;
+ interrupts = <26>;
+ sdhci,auto-cmd12;
+ clocks = <&syscon ASPEED_CLK_SDIO>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/mmc/brcm,sdhci-iproc.txt b/Documentation/devicetree/bindings/mmc/brcm,sdhci-iproc.txt
index fa90d25..09d87cc 100644
--- a/Documentation/devicetree/bindings/mmc/brcm,sdhci-iproc.txt
+++ b/Documentation/devicetree/bindings/mmc/brcm,sdhci-iproc.txt
@@ -6,10 +6,12 @@
Required properties:
- compatible : Should be one of the following
"brcm,bcm2835-sdhci"
+ "brcm,bcm2711-emmc2"
"brcm,sdhci-iproc-cygnus"
"brcm,sdhci-iproc"
-Use brcm2835-sdhci for Rasperry PI.
+Use brcm2835-sdhci for the eMMC controller on the BCM2835 (Raspberry Pi) and
+bcm2711-emmc2 for the additional eMMC2 controller on BCM2711.
Use sdhci-iproc-cygnus for Broadcom SDHCI Controllers
restricted to 32bit host accesses to SDHCI registers.
diff --git a/Documentation/devicetree/bindings/mtd/mxic-nand.txt b/Documentation/devicetree/bindings/mtd/mxic-nand.txt
new file mode 100644
index 0000000..46c5529
--- /dev/null
+++ b/Documentation/devicetree/bindings/mtd/mxic-nand.txt
@@ -0,0 +1,36 @@
+Macronix Raw NAND Controller Device Tree Bindings
+-------------------------------------------------
+
+Required properties:
+- compatible: should be "mxic,multi-itfc-v009-nand-controller"
+- reg: should contain 1 entry for the registers
+- #address-cells: should be set to 1
+- #size-cells: should be set to 0
+- interrupts: interrupt line connected to this raw NAND controller
+- clock-names: should contain "ps", "send" and "send_dly"
+- clocks: should contain 3 phandles for the "ps", "send" and
+ "send_dly" clocks
+
+Children nodes:
+- children nodes represent the available NAND chips.
+
+See Documentation/devicetree/bindings/mtd/nand-controller.yaml
+for more details on generic bindings.
+
+Example:
+
+ nand: nand-controller@43c30000 {
+ compatible = "mxic,multi-itfc-v009-nand-controller";
+ reg = <0x43c30000 0x10000>;
+ #address-cells = <1>;
+ #size-cells = <0>;
+ interrupts = <GIC_SPI 0x1d IRQ_TYPE_EDGE_RISING>;
+ clocks = <&clkwizard 0>, <&clkwizard 1>, <&clkc 15>;
+ clock-names = "send", "send_dly", "ps";
+
+ nand@0 {
+ reg = <0>;
+ nand-ecc-mode = "soft";
+ nand-ecc-algo = "bch";
+ };
+ };
diff --git a/Documentation/devicetree/bindings/net/adi,adin.yaml b/Documentation/devicetree/bindings/net/adi,adin.yaml
new file mode 100644
index 0000000..d95cc69
--- /dev/null
+++ b/Documentation/devicetree/bindings/net/adi,adin.yaml
@@ -0,0 +1,66 @@
+# SPDX-License-Identifier: GPL-2.0+
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/net/adi,adin.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Analog Devices ADIN1200/ADIN1300 PHY
+
+maintainers:
+ - Alexandru Ardelean <alexandru.ardelean@analog.com>
+
+description: |
+ Bindings for Analog Devices Industrial Ethernet PHYs
+
+allOf:
+ - $ref: ethernet-phy.yaml#
+
+properties:
+ adi,rx-internal-delay-ps:
+ description: |
+ RGMII RX Clock Delay used only when PHY operates in RGMII mode with
+ internal delay (phy-mode is 'rgmii-id' or 'rgmii-rxid') in pico-seconds.
+ enum: [ 1600, 1800, 2000, 2200, 2400 ]
+ default: 2000
+
+ adi,tx-internal-delay-ps:
+ description: |
+ RGMII TX Clock Delay used only when PHY operates in RGMII mode with
+ internal delay (phy-mode is 'rgmii-id' or 'rgmii-txid') in pico-seconds.
+ enum: [ 1600, 1800, 2000, 2200, 2400 ]
+ default: 2000
+
+ adi,fifo-depth-bits:
+ description: |
+ When operating in RMII mode, this option configures the FIFO depth.
+ enum: [ 4, 8, 12, 16, 20, 24 ]
+ default: 8
+
+examples:
+ - |
+ ethernet {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ phy-mode = "rgmii-id";
+
+ ethernet-phy@0 {
+ reg = <0>;
+
+ adi,rx-internal-delay-ps = <1800>;
+ adi,tx-internal-delay-ps = <2200>;
+ };
+ };
+ - |
+ ethernet {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ phy-mode = "rmii";
+
+ ethernet-phy@1 {
+ reg = <1>;
+
+ adi,fifo-depth-bits = <16>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/net/allwinner,sun7i-a20-gmac.yaml b/Documentation/devicetree/bindings/net/allwinner,sun7i-a20-gmac.yaml
index 06b1cc8..ef446ae 100644
--- a/Documentation/devicetree/bindings/net/allwinner,sun7i-a20-gmac.yaml
+++ b/Documentation/devicetree/bindings/net/allwinner,sun7i-a20-gmac.yaml
@@ -17,6 +17,9 @@
compatible:
const: allwinner,sun7i-a20-gmac
+ reg:
+ maxItems: 1
+
interrupts:
maxItems: 1
diff --git a/Documentation/devicetree/bindings/net/amlogic,meson-dwmac.yaml b/Documentation/devicetree/bindings/net/amlogic,meson-dwmac.yaml
new file mode 100644
index 0000000..ae91aa9
--- /dev/null
+++ b/Documentation/devicetree/bindings/net/amlogic,meson-dwmac.yaml
@@ -0,0 +1,113 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+# Copyright 2019 BayLibre, SAS
+%YAML 1.2
+---
+$id: "http://devicetree.org/schemas/net/amlogic,meson-dwmac.yaml#"
+$schema: "http://devicetree.org/meta-schemas/core.yaml#"
+
+title: Amlogic Meson DWMAC Ethernet controller
+
+maintainers:
+ - Neil Armstrong <narmstrong@baylibre.com>
+ - Martin Blumenstingl <martin.blumenstingl@googlemail.com>
+
+# We need a select here so we don't match all nodes with 'snps,dwmac'
+select:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - amlogic,meson6-dwmac
+ - amlogic,meson8b-dwmac
+ - amlogic,meson8m2-dwmac
+ - amlogic,meson-gxbb-dwmac
+ - amlogic,meson-axg-dwmac
+ required:
+ - compatible
+
+allOf:
+ - $ref: "snps,dwmac.yaml#"
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - amlogic,meson8b-dwmac
+ - amlogic,meson8m2-dwmac
+ - amlogic,meson-gxbb-dwmac
+ - amlogic,meson-axg-dwmac
+
+ then:
+ properties:
+ clocks:
+ items:
+ - description: GMAC main clock
+ - description: First parent clock of the internal mux
+ - description: Second parent clock of the internal mux
+
+ clock-names:
+ minItems: 3
+ maxItems: 3
+ items:
+ - const: stmmaceth
+ - const: clkin0
+ - const: clkin1
+
+ amlogic,tx-delay-ns:
+ $ref: /schemas/types.yaml#definitions/uint32
+ description:
+ The internal RGMII TX clock delay (provided by this driver) in
+ nanoseconds. Allowed values are 0ns, 2ns, 4ns, 6ns.
+ When phy-mode is set to "rgmii" then the TX delay should be
+ explicitly configured. When not configured a fallback of 2ns is
+ used. When the phy-mode is set to either "rgmii-id" or "rgmii-txid"
+ the TX clock delay is already provided by the PHY. In that case
+ this property should be set to 0ns (which disables the TX clock
+ delay in the MAC to prevent the clock from going off because both
+ PHY and MAC are adding a delay).
+ Any configuration is ignored when the phy-mode is set to "rmii".
+
+properties:
+ compatible:
+ additionalItems: true
+ maxItems: 3
+ items:
+ - enum:
+ - amlogic,meson6-dwmac
+ - amlogic,meson8b-dwmac
+ - amlogic,meson8m2-dwmac
+ - amlogic,meson-gxbb-dwmac
+ - amlogic,meson-axg-dwmac
+ contains:
+ enum:
+ - snps,dwmac-3.70a
+ - snps,dwmac
+
+ reg:
+ items:
+ - description:
+ The first register range should be the one of the DWMAC controller
+ - description:
+ The second range is is for the Amlogic specific configuration
+ (for example the PRG_ETHERNET register range on Meson8b and newer)
+
+required:
+ - compatible
+ - reg
+ - interrupts
+ - interrupt-names
+ - clocks
+ - clock-names
+ - phy-mode
+
+examples:
+ - |
+ ethmac: ethernet@c9410000 {
+ compatible = "amlogic,meson-gxbb-dwmac", "snps,dwmac";
+ reg = <0xc9410000 0x10000>, <0xc8834540 0x8>;
+ interrupts = <8>;
+ interrupt-names = "macirq";
+ clocks = <&clk_eth>, <&clkc_fclk_div2>, <&clk_mpll2>;
+ clock-names = "stmmaceth", "clkin0", "clkin1";
+ phy-mode = "rgmii";
+ };
diff --git a/Documentation/devicetree/bindings/net/aspeed,ast2600-mdio.yaml b/Documentation/devicetree/bindings/net/aspeed,ast2600-mdio.yaml
new file mode 100644
index 0000000..71808e7
--- /dev/null
+++ b/Documentation/devicetree/bindings/net/aspeed,ast2600-mdio.yaml
@@ -0,0 +1,45 @@
+# SPDX-License-Identifier: GPL-2.0-or-later
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/net/aspeed,ast2600-mdio.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: ASPEED AST2600 MDIO Controller
+
+maintainers:
+ - Andrew Jeffery <andrew@aj.id.au>
+
+description: |+
+ The ASPEED AST2600 MDIO controller is the third iteration of ASPEED's MDIO
+ bus register interface, this time also separating out the controller from the
+ MAC.
+
+allOf:
+ - $ref: "mdio.yaml#"
+
+properties:
+ compatible:
+ const: aspeed,ast2600-mdio
+ reg:
+ maxItems: 1
+ description: The register range of the MDIO controller instance
+
+required:
+ - compatible
+ - reg
+ - "#address-cells"
+ - "#size-cells"
+
+examples:
+ - |
+ mdio0: mdio@1e650000 {
+ compatible = "aspeed,ast2600-mdio";
+ reg = <0x1e650000 0x8>;
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ ethphy0: ethernet-phy@0 {
+ compatible = "ethernet-phy-ieee802.3-c22";
+ reg = <0>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/net/broadcom-bluetooth.txt b/Documentation/devicetree/bindings/net/broadcom-bluetooth.txt
index c26f4e1..4fa00e2 100644
--- a/Documentation/devicetree/bindings/net/broadcom-bluetooth.txt
+++ b/Documentation/devicetree/bindings/net/broadcom-bluetooth.txt
@@ -13,6 +13,7 @@
* "brcm,bcm20702a1"
* "brcm,bcm4330-bt"
* "brcm,bcm43438-bt"
+ * "brcm,bcm4345c5"
Optional properties:
diff --git a/Documentation/devicetree/bindings/net/can/fsl-flexcan.txt b/Documentation/devicetree/bindings/net/can/fsl-flexcan.txt
index bc77477..94c0f8b 100644
--- a/Documentation/devicetree/bindings/net/can/fsl-flexcan.txt
+++ b/Documentation/devicetree/bindings/net/can/fsl-flexcan.txt
@@ -32,6 +32,15 @@
ack_gpr is the gpr register offset of CAN stop acknowledge.
ack_bit is the bit offset of CAN stop acknowledge.
+- fsl,clk-source: Select the clock source to the CAN Protocol Engine (PE).
+ It's SoC Implementation dependent. Refer to RM for detailed
+ definition. If this property is not set in device tree node
+ then driver selects clock source 1 by default.
+ 0: clock source 0 (oscillator clock)
+ 1: clock source 1 (peripheral clock)
+
+- wakeup-source: enable CAN remote wakeup
+
Example:
can@1c000 {
@@ -40,4 +49,5 @@
interrupts = <48 0x2>;
interrupt-parent = <&mpic>;
clock-frequency = <200000000>; // filled in by bootloader
+ fsl,clk-source = <0>; // select clock source 0 for PE
};
diff --git a/Documentation/devicetree/bindings/net/can/rcar_can.txt b/Documentation/devicetree/bindings/net/can/rcar_can.txt
index b463e12..19e4a7d 100644
--- a/Documentation/devicetree/bindings/net/can/rcar_can.txt
+++ b/Documentation/devicetree/bindings/net/can/rcar_can.txt
@@ -5,6 +5,7 @@
- compatible: "renesas,can-r8a7743" if CAN controller is a part of R8A7743 SoC.
"renesas,can-r8a7744" if CAN controller is a part of R8A7744 SoC.
"renesas,can-r8a7745" if CAN controller is a part of R8A7745 SoC.
+ "renesas,can-r8a77470" if CAN controller is a part of R8A77470 SoC.
"renesas,can-r8a774a1" if CAN controller is a part of R8A774A1 SoC.
"renesas,can-r8a774c0" if CAN controller is a part of R8A774C0 SoC.
"renesas,can-r8a7778" if CAN controller is a part of R8A7778 SoC.
@@ -17,6 +18,8 @@
"renesas,can-r8a7795" if CAN controller is a part of R8A7795 SoC.
"renesas,can-r8a7796" if CAN controller is a part of R8A7796 SoC.
"renesas,can-r8a77965" if CAN controller is a part of R8A77965 SoC.
+ "renesas,can-r8a77990" if CAN controller is a part of R8A77990 SoC.
+ "renesas,can-r8a77995" if CAN controller is a part of R8A77995 SoC.
"renesas,rcar-gen1-can" for a generic R-Car Gen1 compatible device.
"renesas,rcar-gen2-can" for a generic R-Car Gen2 or RZ/G1
compatible device.
@@ -33,7 +36,8 @@
- pinctrl-0: pin control group to be used for this controller.
- pinctrl-names: must be "default".
-Required properties for R8A7795, R8A7796 and R8A77965:
+Required properties for R8A774A1, R8A774C0, R8A7795, R8A7796, R8A77965,
+R8A77990, and R8A77995:
For the denoted SoCs, "clkp2" can be CANFD clock. This is a div6 clock and can
be used by both CAN and CAN FD controller at the same time. It needs to be
scaled to maximum frequency if any of these controllers use it. This is done
diff --git a/Documentation/devicetree/bindings/net/can/rcar_canfd.txt b/Documentation/devicetree/bindings/net/can/rcar_canfd.txt
index 32f051f..a901cd9 100644
--- a/Documentation/devicetree/bindings/net/can/rcar_canfd.txt
+++ b/Documentation/devicetree/bindings/net/can/rcar_canfd.txt
@@ -4,6 +4,7 @@
Required properties:
- compatible: Must contain one or more of the following:
- "renesas,rcar-gen3-canfd" for R-Car Gen3 and RZ/G2 compatible controllers.
+ - "renesas,r8a774a1-canfd" for R8A774A1 (RZ/G2M) compatible controller.
- "renesas,r8a774c0-canfd" for R8A774C0 (RZ/G2E) compatible controller.
- "renesas,r8a7795-canfd" for R8A7795 (R-Car H3) compatible controller.
- "renesas,r8a7796-canfd" for R8A7796 (R-Car M3-W) compatible controller.
@@ -11,6 +12,7 @@
- "renesas,r8a77970-canfd" for R8A77970 (R-Car V3M) compatible controller.
- "renesas,r8a77980-canfd" for R8A77980 (R-Car V3H) compatible controller.
- "renesas,r8a77990-canfd" for R8A77990 (R-Car E3) compatible controller.
+ - "renesas,r8a77995-canfd" for R8A77995 (R-Car D3) compatible controller.
When compatible with the generic version, nodes must list the
SoC-specific version corresponding to the platform first, followed by the
@@ -29,13 +31,12 @@
child node supports the "status" property only, which is used to
enable/disable the respective channel.
-Required properties for "renesas,r8a774c0-canfd", "renesas,r8a7795-canfd",
-"renesas,r8a7796-canfd", "renesas,r8a77965-canfd", and "renesas,r8a77990-canfd"
-compatible:
-In R8A774C0, R8A7795, R8A7796, R8A77965, and R8A77990 SoCs, canfd clock is a
-div6 clock and can be used by both CAN and CAN FD controller at the same time.
-It needs to be scaled to maximum frequency if any of these controllers use it.
-This is done using the below properties:
+Required properties for R8A774A1, R8A774C0, R8A7795, R8A7796, R8A77965,
+R8A77990, and R8A77995:
+In the denoted SoCs, canfd clock is a div6 clock and can be used by both CAN
+and CAN FD controller at the same time. It needs to be scaled to maximum
+frequency if any of these controllers use it. This is done using the below
+properties:
- assigned-clocks: phandle of canfd clock.
- assigned-clock-rates: maximum frequency of this clock.
diff --git a/Documentation/devicetree/bindings/net/can/tcan4x5x.txt b/Documentation/devicetree/bindings/net/can/tcan4x5x.txt
new file mode 100644
index 0000000..27e1b4c
--- /dev/null
+++ b/Documentation/devicetree/bindings/net/can/tcan4x5x.txt
@@ -0,0 +1,40 @@
+Texas Instruments TCAN4x5x CAN Controller
+================================================
+
+This file provides device node information for the TCAN4x5x interface contains.
+
+Required properties:
+ - compatible: "ti,tcan4x5x"
+ - reg: 0
+ - #address-cells: 1
+ - #size-cells: 0
+ - spi-max-frequency: Maximum frequency of the SPI bus the chip can
+ operate at should be less than or equal to 18 MHz.
+ - device-wake-gpios: Wake up GPIO to wake up the TCAN device.
+ - interrupt-parent: the phandle to the interrupt controller which provides
+ the interrupt.
+ - interrupts: interrupt specification for data-ready.
+
+See Documentation/devicetree/bindings/net/can/m_can.txt for additional
+required property details.
+
+Optional properties:
+ - reset-gpios: Hardwired output GPIO. If not defined then software
+ reset.
+ - device-state-gpios: Input GPIO that indicates if the device is in
+ a sleep state or if the device is active.
+
+Example:
+tcan4x5x: tcan4x5x@0 {
+ compatible = "ti,tcan4x5x";
+ reg = <0>;
+ #address-cells = <1>;
+ #size-cells = <1>;
+ spi-max-frequency = <10000000>;
+ bosch,mram-cfg = <0x0 0 0 32 0 0 1 1>;
+ interrupt-parent = <&gpio1>;
+ interrupts = <14 GPIO_ACTIVE_LOW>;
+ device-state-gpios = <&gpio3 21 GPIO_ACTIVE_HIGH>;
+ device-wake-gpios = <&gpio1 15 GPIO_ACTIVE_HIGH>;
+ reset-gpios = <&gpio1 27 GPIO_ACTIVE_LOW>;
+};
diff --git a/Documentation/devicetree/bindings/net/dsa/ksz.txt b/Documentation/devicetree/bindings/net/dsa/ksz.txt
index 113e7ac..95e91e8 100644
--- a/Documentation/devicetree/bindings/net/dsa/ksz.txt
+++ b/Documentation/devicetree/bindings/net/dsa/ksz.txt
@@ -5,6 +5,9 @@
- compatible: For external switch chips, compatible string must be exactly one
of the following:
+ - "microchip,ksz8765"
+ - "microchip,ksz8794"
+ - "microchip,ksz8795"
- "microchip,ksz9477"
- "microchip,ksz9897"
- "microchip,ksz9896"
diff --git a/Documentation/devicetree/bindings/net/dsa/marvell.txt b/Documentation/devicetree/bindings/net/dsa/marvell.txt
index 6f95389..30c11fe 100644
--- a/Documentation/devicetree/bindings/net/dsa/marvell.txt
+++ b/Documentation/devicetree/bindings/net/dsa/marvell.txt
@@ -22,7 +22,7 @@
- "marvell,mv88e6190" : Switch has base address 0x00. Use with models:
6190, 6190X, 6191, 6290, 6390, 6390X
- "marvell,mv88e6250" : Switch has base address 0x08 or 0x18. Use with model:
- 6250
+ 6220, 6250
Required properties:
- compatible : Should be one of "marvell,mv88e6085",
diff --git a/Documentation/devicetree/bindings/net/dsa/mt7530.txt b/Documentation/devicetree/bindings/net/dsa/mt7530.txt
index 47aa205..c5ed5d2 100644
--- a/Documentation/devicetree/bindings/net/dsa/mt7530.txt
+++ b/Documentation/devicetree/bindings/net/dsa/mt7530.txt
@@ -35,6 +35,42 @@
- phy-mode: String, must be either "trgmii" or "rgmii" for port labeled
"cpu".
+Port 5 of the switch is muxed between:
+1. GMAC5: GMAC5 can interface with another external MAC or PHY.
+2. PHY of port 0 or port 4: PHY interfaces with an external MAC like 2nd GMAC
+ of the SOC. Used in many setups where port 0/4 becomes the WAN port.
+ Note: On a MT7621 SOC with integrated switch: 2nd GMAC can only connected to
+ GMAC5 when the gpios for RGMII2 (GPIO 22-33) are not used and not
+ connected to external component!
+
+Port 5 modes/configurations:
+1. Port 5 is disabled and isolated: An external phy can interface to the 2nd
+ GMAC of the SOC.
+ In the case of a build-in MT7530 switch, port 5 shares the RGMII bus with 2nd
+ GMAC and an optional external phy. Mind the GPIO/pinctl settings of the SOC!
+2. Port 5 is muxed to PHY of port 0/4: Port 0/4 interfaces with 2nd GMAC.
+ It is a simple MAC to PHY interface, port 5 needs to be setup for xMII mode
+ and RGMII delay.
+3. Port 5 is muxed to GMAC5 and can interface to an external phy.
+ Port 5 becomes an extra switch port.
+ Only works on platform where external phy TX<->RX lines are swapped.
+ Like in the Ubiquiti ER-X-SFP.
+4. Port 5 is muxed to GMAC5 and interfaces with the 2nd GAMC as 2nd CPU port.
+ Currently a 2nd CPU port is not supported by DSA code.
+
+Depending on how the external PHY is wired:
+1. normal: The PHY can only connect to 2nd GMAC but not to the switch
+2. swapped: RGMII TX, RX are swapped; external phy interface with the switch as
+ a ethernet port. But can't interface to the 2nd GMAC.
+
+Based on the DT the port 5 mode is configured.
+
+Driver tries to lookup the phy-handle of the 2nd GMAC of the master device.
+When phy-handle matches PHY of port 0 or 4 then port 5 set-up as mode 2.
+phy-mode must be set, see also example 2 below!
+ * mt7621: phy-mode = "rgmii-txid";
+ * mt7623: phy-mode = "rgmii";
+
See Documentation/devicetree/bindings/net/dsa/dsa.txt for a list of additional
required, optional properties and how the integrated switch subnodes must
be specified.
@@ -94,3 +130,181 @@
};
};
};
+
+Example 2: MT7621: Port 4 is WAN port: 2nd GMAC -> Port 5 -> PHY port 4.
+
+ð {
+ gmac0: mac@0 {
+ compatible = "mediatek,eth-mac";
+ reg = <0>;
+ phy-mode = "rgmii";
+
+ fixed-link {
+ speed = <1000>;
+ full-duplex;
+ pause;
+ };
+ };
+
+ gmac1: mac@1 {
+ compatible = "mediatek,eth-mac";
+ reg = <1>;
+ phy-mode = "rgmii-txid";
+ phy-handle = <&phy4>;
+ };
+
+ mdio: mdio-bus {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ /* Internal phy */
+ phy4: ethernet-phy@4 {
+ reg = <4>;
+ };
+
+ mt7530: switch@1f {
+ compatible = "mediatek,mt7621";
+ #address-cells = <1>;
+ #size-cells = <0>;
+ reg = <0x1f>;
+ pinctrl-names = "default";
+ mediatek,mcm;
+
+ resets = <&rstctrl 2>;
+ reset-names = "mcm";
+
+ ports {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ port@0 {
+ reg = <0>;
+ label = "lan0";
+ };
+
+ port@1 {
+ reg = <1>;
+ label = "lan1";
+ };
+
+ port@2 {
+ reg = <2>;
+ label = "lan2";
+ };
+
+ port@3 {
+ reg = <3>;
+ label = "lan3";
+ };
+
+/* Commented out. Port 4 is handled by 2nd GMAC.
+ port@4 {
+ reg = <4>;
+ label = "lan4";
+ };
+*/
+
+ cpu_port0: port@6 {
+ reg = <6>;
+ label = "cpu";
+ ethernet = <&gmac0>;
+ phy-mode = "rgmii";
+
+ fixed-link {
+ speed = <1000>;
+ full-duplex;
+ pause;
+ };
+ };
+ };
+ };
+ };
+};
+
+Example 3: MT7621: Port 5 is connected to external PHY: Port 5 -> external PHY.
+
+ð {
+ gmac0: mac@0 {
+ compatible = "mediatek,eth-mac";
+ reg = <0>;
+ phy-mode = "rgmii";
+
+ fixed-link {
+ speed = <1000>;
+ full-duplex;
+ pause;
+ };
+ };
+
+ mdio: mdio-bus {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ /* External phy */
+ ephy5: ethernet-phy@7 {
+ reg = <7>;
+ };
+
+ mt7530: switch@1f {
+ compatible = "mediatek,mt7621";
+ #address-cells = <1>;
+ #size-cells = <0>;
+ reg = <0x1f>;
+ pinctrl-names = "default";
+ mediatek,mcm;
+
+ resets = <&rstctrl 2>;
+ reset-names = "mcm";
+
+ ports {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ port@0 {
+ reg = <0>;
+ label = "lan0";
+ };
+
+ port@1 {
+ reg = <1>;
+ label = "lan1";
+ };
+
+ port@2 {
+ reg = <2>;
+ label = "lan2";
+ };
+
+ port@3 {
+ reg = <3>;
+ label = "lan3";
+ };
+
+ port@4 {
+ reg = <4>;
+ label = "lan4";
+ };
+
+ port@5 {
+ reg = <5>;
+ label = "lan5";
+ phy-mode = "rgmii";
+ phy-handle = <&ephy5>;
+ };
+
+ cpu_port0: port@6 {
+ reg = <6>;
+ label = "cpu";
+ ethernet = <&gmac0>;
+ phy-mode = "rgmii";
+
+ fixed-link {
+ speed = <1000>;
+ full-duplex;
+ pause;
+ };
+ };
+ };
+ };
+ };
+};
diff --git a/Documentation/devicetree/bindings/net/fsl-enetc.txt b/Documentation/devicetree/bindings/net/fsl-enetc.txt
index 25fc687..b7034cc 100644
--- a/Documentation/devicetree/bindings/net/fsl-enetc.txt
+++ b/Documentation/devicetree/bindings/net/fsl-enetc.txt
@@ -11,7 +11,9 @@
to parent node bindings.
- compatible : Should be "fsl,enetc".
-1) The ENETC external port is connected to a MDIO configurable phy:
+1. The ENETC external port is connected to a MDIO configurable phy
+
+1.1. Using the local ENETC Port MDIO interface
In this case, the ENETC node should include a "mdio" sub-node
that in turn should contain the "ethernet-phy" node describing the
@@ -47,8 +49,42 @@
};
};
-2) The ENETC port is an internal port or has a fixed-link external
-connection:
+1.2. Using the central MDIO PCIe endpoint device
+
+In this case, the mdio node should be defined as another PCIe
+endpoint node, at the same level with the ENETC port nodes.
+
+Required properties:
+
+- reg : Specifies PCIe Device Number and Function
+ Number of the ENETC endpoint device, according
+ to parent node bindings.
+- compatible : Should be "fsl,enetc-mdio".
+
+The remaining required mdio bus properties are standard, their bindings
+already defined in Documentation/devicetree/bindings/net/mdio.txt.
+
+Example:
+
+ ethernet@0,0 {
+ compatible = "fsl,enetc";
+ reg = <0x000000 0 0 0 0>;
+ phy-handle = <&sgmii_phy0>;
+ phy-connection-type = "sgmii";
+ };
+
+ mdio@0,3 {
+ compatible = "fsl,enetc-mdio";
+ reg = <0x000300 0 0 0 0>;
+ #address-cells = <1>;
+ #size-cells = <0>;
+ sgmii_phy0: ethernet-phy@2 {
+ reg = <0x2>;
+ };
+ };
+
+2. The ENETC port is an internal port or has a fixed-link external
+connection
In this case, the ENETC port node defines a fixed link connection,
as specified by Documentation/devicetree/bindings/net/fixed-link.txt.
diff --git a/Documentation/devicetree/bindings/net/mediatek-net.txt b/Documentation/devicetree/bindings/net/mediatek-net.txt
index 770ff98..72d03e0 100644
--- a/Documentation/devicetree/bindings/net/mediatek-net.txt
+++ b/Documentation/devicetree/bindings/net/mediatek-net.txt
@@ -12,6 +12,7 @@
"mediatek,mt7623-eth", "mediatek,mt2701-eth": for MT7623 SoC
"mediatek,mt7622-eth": for MT7622 SoC
"mediatek,mt7629-eth": for MT7629 SoC
+ "ralink,rt5350-eth": for Ralink Rt5350F and MT7628/88 SoC
- reg: Address and length of the register set for the device
- interrupts: Should contain the three frame engines interrupts in numeric
order. These are fe_int0, fe_int1 and fe_int2.
diff --git a/Documentation/devicetree/bindings/net/meson-dwmac.txt b/Documentation/devicetree/bindings/net/meson-dwmac.txt
deleted file mode 100644
index 1321bb1..0000000
--- a/Documentation/devicetree/bindings/net/meson-dwmac.txt
+++ /dev/null
@@ -1,71 +0,0 @@
-* Amlogic Meson DWMAC Ethernet controller
-
-The device inherits all the properties of the dwmac/stmmac devices
-described in the file stmmac.txt in the current directory with the
-following changes.
-
-Required properties on all platforms:
-
-- compatible: Depending on the platform this should be one of:
- - "amlogic,meson6-dwmac"
- - "amlogic,meson8b-dwmac"
- - "amlogic,meson8m2-dwmac"
- - "amlogic,meson-gxbb-dwmac"
- - "amlogic,meson-axg-dwmac"
- Additionally "snps,dwmac" and any applicable more
- detailed version number described in net/stmmac.txt
- should be used.
-
-- reg: The first register range should be the one of the DWMAC
- controller. The second range is is for the Amlogic specific
- configuration (for example the PRG_ETHERNET register range
- on Meson8b and newer)
-
-Required properties on Meson8b, Meson8m2, GXBB and newer:
-- clock-names: Should contain the following:
- - "stmmaceth" - see stmmac.txt
- - "clkin0" - first parent clock of the internal mux
- - "clkin1" - second parent clock of the internal mux
-
-Optional properties on Meson8b, Meson8m2, GXBB and newer:
-- amlogic,tx-delay-ns: The internal RGMII TX clock delay (provided
- by this driver) in nanoseconds. Allowed values
- are: 0ns, 2ns, 4ns, 6ns.
- When phy-mode is set to "rgmii" then the TX
- delay should be explicitly configured. When
- not configured a fallback of 2ns is used.
- When the phy-mode is set to either "rgmii-id"
- or "rgmii-txid" the TX clock delay is already
- provided by the PHY. In that case this
- property should be set to 0ns (which disables
- the TX clock delay in the MAC to prevent the
- clock from going off because both PHY and MAC
- are adding a delay).
- Any configuration is ignored when the phy-mode
- is set to "rmii".
-
-Example for Meson6:
-
- ethmac: ethernet@c9410000 {
- compatible = "amlogic,meson6-dwmac", "snps,dwmac";
- reg = <0xc9410000 0x10000
- 0xc1108108 0x4>;
- interrupts = <0 8 1>;
- interrupt-names = "macirq";
- clocks = <&clk81>;
- clock-names = "stmmaceth";
- }
-
-Example for GXBB:
- ethmac: ethernet@c9410000 {
- compatible = "amlogic,meson-gxbb-dwmac", "snps,dwmac";
- reg = <0x0 0xc9410000 0x0 0x10000>,
- <0x0 0xc8834540 0x0 0x8>;
- interrupts = <0 8 1>;
- interrupt-names = "macirq";
- clocks = <&clkc CLKID_ETH>,
- <&clkc CLKID_FCLK_DIV2>,
- <&clkc CLKID_MPLL2>;
- clock-names = "stmmaceth", "clkin0", "clkin1";
- phy-mode = "rgmii";
- };
diff --git a/Documentation/devicetree/bindings/net/micrel-ksz90x1.txt b/Documentation/devicetree/bindings/net/micrel-ksz90x1.txt
index 5100358..b921731 100644
--- a/Documentation/devicetree/bindings/net/micrel-ksz90x1.txt
+++ b/Documentation/devicetree/bindings/net/micrel-ksz90x1.txt
@@ -12,8 +12,36 @@
KSZ9021:
All skew control options are specified in picoseconds. The minimum
- value is 0, the maximum value is 3000, and it is incremented by 200ps
- steps.
+ value is 0, the maximum value is 3000, and it can be specified in 200ps
+ steps, *but* these values are in not fact what you get because this chip's
+ skew values actually increase in 120ps steps, starting from -840ps. The
+ incorrect values came from an error in the original KSZ9021 datasheet
+ before it was corrected in revision 1.2 (Feb 2014), but it is too late to
+ change the driver now because of the many existing device trees that have
+ been created using values that go up in increments of 200.
+
+ The following table shows the actual skew delay you will get for each of the
+ possible devicetree values, and the number that will be programmed into the
+ corresponding pad skew register:
+
+ Device Tree Value Delay Pad Skew Register Value
+ -----------------------------------------------------
+ 0 -840ps 0000
+ 200 -720ps 0001
+ 400 -600ps 0010
+ 600 -480ps 0011
+ 800 -360ps 0100
+ 1000 -240ps 0101
+ 1200 -120ps 0110
+ 1400 0ps 0111
+ 1600 120ps 1000
+ 1800 240ps 1001
+ 2000 360ps 1010
+ 2200 480ps 1011
+ 2400 600ps 1100
+ 2600 720ps 1101
+ 2800 840ps 1110
+ 3000 960ps 1111
Optional properties:
diff --git a/Documentation/devicetree/bindings/net/mscc-ocelot.txt b/Documentation/devicetree/bindings/net/mscc-ocelot.txt
index 9e5c17d..3b6290b 100644
--- a/Documentation/devicetree/bindings/net/mscc-ocelot.txt
+++ b/Documentation/devicetree/bindings/net/mscc-ocelot.txt
@@ -12,13 +12,15 @@
- "sys"
- "rew"
- "qs"
+ - "ptp" (optional due to backward compatibility)
- "qsys"
- "ana"
- "portX" with X from 0 to the number of last port index available on that
switch
-- interrupts: Should contain the switch interrupts for frame extraction and
- frame injection
-- interrupt-names: should contain the interrupt names: "xtr", "inj"
+- interrupts: Should contain the switch interrupts for frame extraction,
+ frame injection and PTP ready.
+- interrupt-names: should contain the interrupt names: "xtr", "inj". Can contain
+ "ptp_rdy" which is optional due to backward compatibility.
- ethernet-ports: A container for child nodes representing switch ports.
The ethernet-ports container has the following properties
@@ -44,6 +46,7 @@
reg = <0x1010000 0x10000>,
<0x1030000 0x10000>,
<0x1080000 0x100>,
+ <0x10e0000 0x10000>,
<0x11e0000 0x100>,
<0x11f0000 0x100>,
<0x1200000 0x100>,
@@ -57,11 +60,12 @@
<0x1280000 0x100>,
<0x1800000 0x80000>,
<0x1880000 0x10000>;
- reg-names = "sys", "rew", "qs", "port0", "port1", "port2",
- "port3", "port4", "port5", "port6", "port7",
- "port8", "port9", "port10", "qsys", "ana";
- interrupts = <21 22>;
- interrupt-names = "xtr", "inj";
+ reg-names = "sys", "rew", "qs", "ptp", "port0", "port1",
+ "port2", "port3", "port4", "port5", "port6",
+ "port7", "port8", "port9", "port10", "qsys",
+ "ana";
+ interrupts = <18 21 22>;
+ interrupt-names = "ptp_rdy", "xtr", "inj";
ethernet-ports {
#address-cells = <1>;
diff --git a/Documentation/devicetree/bindings/net/renesas,ravb.txt b/Documentation/devicetree/bindings/net/renesas,ravb.txt
index 7ad3621..5df4aa7 100644
--- a/Documentation/devicetree/bindings/net/renesas,ravb.txt
+++ b/Documentation/devicetree/bindings/net/renesas,ravb.txt
@@ -18,6 +18,7 @@
R-Car Gen2 and RZ/G1 devices.
- "renesas,etheravb-r8a774a1" for the R8A774A1 SoC.
+ - "renesas,etheravb-r8a774b1" for the R8A774B1 SoC.
- "renesas,etheravb-r8a774c0" for the R8A774C0 SoC.
- "renesas,etheravb-r8a7795" for the R8A7795 SoC.
- "renesas,etheravb-r8a7796" for the R8A7796 SoC.
diff --git a/Documentation/devicetree/bindings/net/snps,dwmac.yaml b/Documentation/devicetree/bindings/net/snps,dwmac.yaml
index 76fea2b..4845e294 100644
--- a/Documentation/devicetree/bindings/net/snps,dwmac.yaml
+++ b/Documentation/devicetree/bindings/net/snps,dwmac.yaml
@@ -50,6 +50,11 @@
- allwinner,sun8i-r40-emac
- allwinner,sun8i-v3s-emac
- allwinner,sun50i-a64-emac
+ - amlogic,meson6-dwmac
+ - amlogic,meson8b-dwmac
+ - amlogic,meson8m2-dwmac
+ - amlogic,meson-gxbb-dwmac
+ - amlogic,meson-axg-dwmac
- snps,dwmac
- snps,dwmac-3.50a
- snps,dwmac-3.610
@@ -61,7 +66,8 @@
- snps,dwxgmac-2.10
reg:
- maxItems: 1
+ minItems: 1
+ maxItems: 2
interrupts:
minItems: 1
@@ -106,6 +112,14 @@
reset-names:
const: stmmaceth
+ mac-mode:
+ $ref: ethernet-controller.yaml#/properties/phy-connection-type
+ description:
+ The property is identical to 'phy-mode', and assumes that there is mode
+ converter in-between the MAC & PHY (e.g. GMII-to-RGMII). This converter
+ can be passive (no SW requirement), and requires that the MAC operate
+ in a different mode than the PHY in order to function.
+
snps,axi-config:
$ref: /schemas/types.yaml#definitions/phandle
description:
diff --git a/Documentation/devicetree/bindings/net/ti,dp83867.txt b/Documentation/devicetree/bindings/net/ti,dp83867.txt
index db6aa3f..388ff48 100644
--- a/Documentation/devicetree/bindings/net/ti,dp83867.txt
+++ b/Documentation/devicetree/bindings/net/ti,dp83867.txt
@@ -37,6 +37,10 @@
for applicable values. The CLK_OUT pin can also
be disabled by this property. When omitted, the
PHY's default will be left as is.
+ - ti,sgmii-ref-clock-output-enable - This denotes which
+ SGMII configuration is used (4 or 6-wire modes).
+ Some MACs work with differential SGMII clock.
+ See data manual for details.
Note: ti,min-output-impedance and ti,max-output-impedance are mutually
exclusive. When both properties are present ti,max-output-impedance
diff --git a/Documentation/devicetree/bindings/nvmem/imx-ocotp.txt b/Documentation/devicetree/bindings/nvmem/imx-ocotp.txt
index 96ffd06..904dadf 100644
--- a/Documentation/devicetree/bindings/nvmem/imx-ocotp.txt
+++ b/Documentation/devicetree/bindings/nvmem/imx-ocotp.txt
@@ -2,7 +2,7 @@
This binding represents the on-chip eFuse OTP controller found on
i.MX6Q/D, i.MX6DL/S, i.MX6SL, i.MX6SX, i.MX6UL, i.MX6ULL/ULZ, i.MX6SLL,
-i.MX7D/S, i.MX7ULP and i.MX8MQ SoCs.
+i.MX7D/S, i.MX7ULP, i.MX8MQ, i.MX8MM and i.MX8MN SoCs.
Required properties:
- compatible: should be one of
@@ -16,6 +16,7 @@
"fsl,imx7ulp-ocotp" (i.MX7ULP),
"fsl,imx8mq-ocotp" (i.MX8MQ),
"fsl,imx8mm-ocotp" (i.MX8MM),
+ "fsl,imx8mn-ocotp" (i.MX8MN),
followed by "syscon".
- #address-cells : Should be 1
- #size-cells : Should be 1
diff --git a/Documentation/devicetree/bindings/opp/kryo-cpufreq.txt b/Documentation/devicetree/bindings/opp/kryo-cpufreq.txt
deleted file mode 100644
index c2127b9..0000000
--- a/Documentation/devicetree/bindings/opp/kryo-cpufreq.txt
+++ /dev/null
@@ -1,680 +0,0 @@
-Qualcomm Technologies, Inc. KRYO CPUFreq and OPP bindings
-===================================
-
-In Certain Qualcomm Technologies, Inc. SoCs like apq8096 and msm8996
-that have KRYO processors, the CPU ferequencies subset and voltage value
-of each OPP varies based on the silicon variant in use.
-Qualcomm Technologies, Inc. Process Voltage Scaling Tables
-defines the voltage and frequency value based on the msm-id in SMEM
-and speedbin blown in the efuse combination.
-The qcom-cpufreq-kryo driver reads the msm-id and efuse value from the SoC
-to provide the OPP framework with required information (existing HW bitmap).
-This is used to determine the voltage and frequency value for each OPP of
-operating-points-v2 table when it is parsed by the OPP framework.
-
-Required properties:
---------------------
-In 'cpus' nodes:
-- operating-points-v2: Phandle to the operating-points-v2 table to use.
-
-In 'operating-points-v2' table:
-- compatible: Should be
- - 'operating-points-v2-kryo-cpu' for apq8096 and msm8996.
-- nvmem-cells: A phandle pointing to a nvmem-cells node representing the
- efuse registers that has information about the
- speedbin that is used to select the right frequency/voltage
- value pair.
- Please refer the for nvmem-cells
- bindings Documentation/devicetree/bindings/nvmem/nvmem.txt
- and also examples below.
-
-In every OPP node:
-- opp-supported-hw: A single 32 bit bitmap value, representing compatible HW.
- Bitmap:
- 0: MSM8996 V3, speedbin 0
- 1: MSM8996 V3, speedbin 1
- 2: MSM8996 V3, speedbin 2
- 3: unused
- 4: MSM8996 SG, speedbin 0
- 5: MSM8996 SG, speedbin 1
- 6: MSM8996 SG, speedbin 2
- 7-31: unused
-
-Example 1:
----------
-
- cpus {
- #address-cells = <2>;
- #size-cells = <0>;
-
- CPU0: cpu@0 {
- device_type = "cpu";
- compatible = "qcom,kryo";
- reg = <0x0 0x0>;
- enable-method = "psci";
- clocks = <&kryocc 0>;
- cpu-supply = <&pm8994_s11_saw>;
- operating-points-v2 = <&cluster0_opp>;
- #cooling-cells = <2>;
- next-level-cache = <&L2_0>;
- L2_0: l2-cache {
- compatible = "cache";
- cache-level = <2>;
- };
- };
-
- CPU1: cpu@1 {
- device_type = "cpu";
- compatible = "qcom,kryo";
- reg = <0x0 0x1>;
- enable-method = "psci";
- clocks = <&kryocc 0>;
- cpu-supply = <&pm8994_s11_saw>;
- operating-points-v2 = <&cluster0_opp>;
- #cooling-cells = <2>;
- next-level-cache = <&L2_0>;
- };
-
- CPU2: cpu@100 {
- device_type = "cpu";
- compatible = "qcom,kryo";
- reg = <0x0 0x100>;
- enable-method = "psci";
- clocks = <&kryocc 1>;
- cpu-supply = <&pm8994_s11_saw>;
- operating-points-v2 = <&cluster1_opp>;
- #cooling-cells = <2>;
- next-level-cache = <&L2_1>;
- L2_1: l2-cache {
- compatible = "cache";
- cache-level = <2>;
- };
- };
-
- CPU3: cpu@101 {
- device_type = "cpu";
- compatible = "qcom,kryo";
- reg = <0x0 0x101>;
- enable-method = "psci";
- clocks = <&kryocc 1>;
- cpu-supply = <&pm8994_s11_saw>;
- operating-points-v2 = <&cluster1_opp>;
- #cooling-cells = <2>;
- next-level-cache = <&L2_1>;
- };
-
- cpu-map {
- cluster0 {
- core0 {
- cpu = <&CPU0>;
- };
-
- core1 {
- cpu = <&CPU1>;
- };
- };
-
- cluster1 {
- core0 {
- cpu = <&CPU2>;
- };
-
- core1 {
- cpu = <&CPU3>;
- };
- };
- };
- };
-
- cluster0_opp: opp_table0 {
- compatible = "operating-points-v2-kryo-cpu";
- nvmem-cells = <&speedbin_efuse>;
- opp-shared;
-
- opp-307200000 {
- opp-hz = /bits/ 64 <307200000>;
- opp-microvolt = <905000 905000 1140000>;
- opp-supported-hw = <0x77>;
- clock-latency-ns = <200000>;
- };
- opp-384000000 {
- opp-hz = /bits/ 64 <384000000>;
- opp-microvolt = <905000 905000 1140000>;
- opp-supported-hw = <0x70>;
- clock-latency-ns = <200000>;
- };
- opp-422400000 {
- opp-hz = /bits/ 64 <422400000>;
- opp-microvolt = <905000 905000 1140000>;
- opp-supported-hw = <0x7>;
- clock-latency-ns = <200000>;
- };
- opp-460800000 {
- opp-hz = /bits/ 64 <460800000>;
- opp-microvolt = <905000 905000 1140000>;
- opp-supported-hw = <0x70>;
- clock-latency-ns = <200000>;
- };
- opp-480000000 {
- opp-hz = /bits/ 64 <480000000>;
- opp-microvolt = <905000 905000 1140000>;
- opp-supported-hw = <0x7>;
- clock-latency-ns = <200000>;
- };
- opp-537600000 {
- opp-hz = /bits/ 64 <537600000>;
- opp-microvolt = <905000 905000 1140000>;
- opp-supported-hw = <0x70>;
- clock-latency-ns = <200000>;
- };
- opp-556800000 {
- opp-hz = /bits/ 64 <556800000>;
- opp-microvolt = <905000 905000 1140000>;
- opp-supported-hw = <0x7>;
- clock-latency-ns = <200000>;
- };
- opp-614400000 {
- opp-hz = /bits/ 64 <614400000>;
- opp-microvolt = <905000 905000 1140000>;
- opp-supported-hw = <0x70>;
- clock-latency-ns = <200000>;
- };
- opp-652800000 {
- opp-hz = /bits/ 64 <652800000>;
- opp-microvolt = <905000 905000 1140000>;
- opp-supported-hw = <0x7>;
- clock-latency-ns = <200000>;
- };
- opp-691200000 {
- opp-hz = /bits/ 64 <691200000>;
- opp-microvolt = <905000 905000 1140000>;
- opp-supported-hw = <0x70>;
- clock-latency-ns = <200000>;
- };
- opp-729600000 {
- opp-hz = /bits/ 64 <729600000>;
- opp-microvolt = <905000 905000 1140000>;
- opp-supported-hw = <0x7>;
- clock-latency-ns = <200000>;
- };
- opp-768000000 {
- opp-hz = /bits/ 64 <768000000>;
- opp-microvolt = <905000 905000 1140000>;
- opp-supported-hw = <0x70>;
- clock-latency-ns = <200000>;
- };
- opp-844800000 {
- opp-hz = /bits/ 64 <844800000>;
- opp-microvolt = <905000 905000 1140000>;
- opp-supported-hw = <0x77>;
- clock-latency-ns = <200000>;
- };
- opp-902400000 {
- opp-hz = /bits/ 64 <902400000>;
- opp-microvolt = <905000 905000 1140000>;
- opp-supported-hw = <0x70>;
- clock-latency-ns = <200000>;
- };
- opp-960000000 {
- opp-hz = /bits/ 64 <960000000>;
- opp-microvolt = <905000 905000 1140000>;
- opp-supported-hw = <0x7>;
- clock-latency-ns = <200000>;
- };
- opp-979200000 {
- opp-hz = /bits/ 64 <979200000>;
- opp-microvolt = <905000 905000 1140000>;
- opp-supported-hw = <0x70>;
- clock-latency-ns = <200000>;
- };
- opp-1036800000 {
- opp-hz = /bits/ 64 <1036800000>;
- opp-microvolt = <905000 905000 1140000>;
- opp-supported-hw = <0x7>;
- clock-latency-ns = <200000>;
- };
- opp-1056000000 {
- opp-hz = /bits/ 64 <1056000000>;
- opp-microvolt = <905000 905000 1140000>;
- opp-supported-hw = <0x70>;
- clock-latency-ns = <200000>;
- };
- opp-1113600000 {
- opp-hz = /bits/ 64 <1113600000>;
- opp-microvolt = <905000 905000 1140000>;
- opp-supported-hw = <0x7>;
- clock-latency-ns = <200000>;
- };
- opp-1132800000 {
- opp-hz = /bits/ 64 <1132800000>;
- opp-microvolt = <905000 905000 1140000>;
- opp-supported-hw = <0x70>;
- clock-latency-ns = <200000>;
- };
- opp-1190400000 {
- opp-hz = /bits/ 64 <1190400000>;
- opp-microvolt = <905000 905000 1140000>;
- opp-supported-hw = <0x7>;
- clock-latency-ns = <200000>;
- };
- opp-1209600000 {
- opp-hz = /bits/ 64 <1209600000>;
- opp-microvolt = <905000 905000 1140000>;
- opp-supported-hw = <0x70>;
- clock-latency-ns = <200000>;
- };
- opp-1228800000 {
- opp-hz = /bits/ 64 <1228800000>;
- opp-microvolt = <905000 905000 1140000>;
- opp-supported-hw = <0x7>;
- clock-latency-ns = <200000>;
- };
- opp-1286400000 {
- opp-hz = /bits/ 64 <1286400000>;
- opp-microvolt = <1140000 905000 1140000>;
- opp-supported-hw = <0x70>;
- clock-latency-ns = <200000>;
- };
- opp-1324800000 {
- opp-hz = /bits/ 64 <1324800000>;
- opp-microvolt = <1140000 905000 1140000>;
- opp-supported-hw = <0x5>;
- clock-latency-ns = <200000>;
- };
- opp-1363200000 {
- opp-hz = /bits/ 64 <1363200000>;
- opp-microvolt = <1140000 905000 1140000>;
- opp-supported-hw = <0x72>;
- clock-latency-ns = <200000>;
- };
- opp-1401600000 {
- opp-hz = /bits/ 64 <1401600000>;
- opp-microvolt = <1140000 905000 1140000>;
- opp-supported-hw = <0x5>;
- clock-latency-ns = <200000>;
- };
- opp-1440000000 {
- opp-hz = /bits/ 64 <1440000000>;
- opp-microvolt = <1140000 905000 1140000>;
- opp-supported-hw = <0x70>;
- clock-latency-ns = <200000>;
- };
- opp-1478400000 {
- opp-hz = /bits/ 64 <1478400000>;
- opp-microvolt = <1140000 905000 1140000>;
- opp-supported-hw = <0x1>;
- clock-latency-ns = <200000>;
- };
- opp-1497600000 {
- opp-hz = /bits/ 64 <1497600000>;
- opp-microvolt = <1140000 905000 1140000>;
- opp-supported-hw = <0x4>;
- clock-latency-ns = <200000>;
- };
- opp-1516800000 {
- opp-hz = /bits/ 64 <1516800000>;
- opp-microvolt = <1140000 905000 1140000>;
- opp-supported-hw = <0x70>;
- clock-latency-ns = <200000>;
- };
- opp-1593600000 {
- opp-hz = /bits/ 64 <1593600000>;
- opp-microvolt = <1140000 905000 1140000>;
- opp-supported-hw = <0x71>;
- clock-latency-ns = <200000>;
- };
- opp-1996800000 {
- opp-hz = /bits/ 64 <1996800000>;
- opp-microvolt = <1140000 905000 1140000>;
- opp-supported-hw = <0x20>;
- clock-latency-ns = <200000>;
- };
- opp-2188800000 {
- opp-hz = /bits/ 64 <2188800000>;
- opp-microvolt = <1140000 905000 1140000>;
- opp-supported-hw = <0x10>;
- clock-latency-ns = <200000>;
- };
- };
-
- cluster1_opp: opp_table1 {
- compatible = "operating-points-v2-kryo-cpu";
- nvmem-cells = <&speedbin_efuse>;
- opp-shared;
-
- opp-307200000 {
- opp-hz = /bits/ 64 <307200000>;
- opp-microvolt = <905000 905000 1140000>;
- opp-supported-hw = <0x77>;
- clock-latency-ns = <200000>;
- };
- opp-384000000 {
- opp-hz = /bits/ 64 <384000000>;
- opp-microvolt = <905000 905000 1140000>;
- opp-supported-hw = <0x70>;
- clock-latency-ns = <200000>;
- };
- opp-403200000 {
- opp-hz = /bits/ 64 <403200000>;
- opp-microvolt = <905000 905000 1140000>;
- opp-supported-hw = <0x7>;
- clock-latency-ns = <200000>;
- };
- opp-460800000 {
- opp-hz = /bits/ 64 <460800000>;
- opp-microvolt = <905000 905000 1140000>;
- opp-supported-hw = <0x70>;
- clock-latency-ns = <200000>;
- };
- opp-480000000 {
- opp-hz = /bits/ 64 <480000000>;
- opp-microvolt = <905000 905000 1140000>;
- opp-supported-hw = <0x7>;
- clock-latency-ns = <200000>;
- };
- opp-537600000 {
- opp-hz = /bits/ 64 <537600000>;
- opp-microvolt = <905000 905000 1140000>;
- opp-supported-hw = <0x70>;
- clock-latency-ns = <200000>;
- };
- opp-556800000 {
- opp-hz = /bits/ 64 <556800000>;
- opp-microvolt = <905000 905000 1140000>;
- opp-supported-hw = <0x7>;
- clock-latency-ns = <200000>;
- };
- opp-614400000 {
- opp-hz = /bits/ 64 <614400000>;
- opp-microvolt = <905000 905000 1140000>;
- opp-supported-hw = <0x70>;
- clock-latency-ns = <200000>;
- };
- opp-652800000 {
- opp-hz = /bits/ 64 <652800000>;
- opp-microvolt = <905000 905000 1140000>;
- opp-supported-hw = <0x7>;
- clock-latency-ns = <200000>;
- };
- opp-691200000 {
- opp-hz = /bits/ 64 <691200000>;
- opp-microvolt = <905000 905000 1140000>;
- opp-supported-hw = <0x70>;
- clock-latency-ns = <200000>;
- };
- opp-729600000 {
- opp-hz = /bits/ 64 <729600000>;
- opp-microvolt = <905000 905000 1140000>;
- opp-supported-hw = <0x7>;
- clock-latency-ns = <200000>;
- };
- opp-748800000 {
- opp-hz = /bits/ 64 <748800000>;
- opp-microvolt = <905000 905000 1140000>;
- opp-supported-hw = <0x70>;
- clock-latency-ns = <200000>;
- };
- opp-806400000 {
- opp-hz = /bits/ 64 <806400000>;
- opp-microvolt = <905000 905000 1140000>;
- opp-supported-hw = <0x7>;
- clock-latency-ns = <200000>;
- };
- opp-825600000 {
- opp-hz = /bits/ 64 <825600000>;
- opp-microvolt = <905000 905000 1140000>;
- opp-supported-hw = <0x70>;
- clock-latency-ns = <200000>;
- };
- opp-883200000 {
- opp-hz = /bits/ 64 <883200000>;
- opp-microvolt = <905000 905000 1140000>;
- opp-supported-hw = <0x7>;
- clock-latency-ns = <200000>;
- };
- opp-902400000 {
- opp-hz = /bits/ 64 <902400000>;
- opp-microvolt = <905000 905000 1140000>;
- opp-supported-hw = <0x70>;
- clock-latency-ns = <200000>;
- };
- opp-940800000 {
- opp-hz = /bits/ 64 <940800000>;
- opp-microvolt = <905000 905000 1140000>;
- opp-supported-hw = <0x7>;
- clock-latency-ns = <200000>;
- };
- opp-979200000 {
- opp-hz = /bits/ 64 <979200000>;
- opp-microvolt = <905000 905000 1140000>;
- opp-supported-hw = <0x70>;
- clock-latency-ns = <200000>;
- };
- opp-1036800000 {
- opp-hz = /bits/ 64 <1036800000>;
- opp-microvolt = <905000 905000 1140000>;
- opp-supported-hw = <0x7>;
- clock-latency-ns = <200000>;
- };
- opp-1056000000 {
- opp-hz = /bits/ 64 <1056000000>;
- opp-microvolt = <905000 905000 1140000>;
- opp-supported-hw = <0x70>;
- clock-latency-ns = <200000>;
- };
- opp-1113600000 {
- opp-hz = /bits/ 64 <1113600000>;
- opp-microvolt = <905000 905000 1140000>;
- opp-supported-hw = <0x7>;
- clock-latency-ns = <200000>;
- };
- opp-1132800000 {
- opp-hz = /bits/ 64 <1132800000>;
- opp-microvolt = <905000 905000 1140000>;
- opp-supported-hw = <0x70>;
- clock-latency-ns = <200000>;
- };
- opp-1190400000 {
- opp-hz = /bits/ 64 <1190400000>;
- opp-microvolt = <905000 905000 1140000>;
- opp-supported-hw = <0x7>;
- clock-latency-ns = <200000>;
- };
- opp-1209600000 {
- opp-hz = /bits/ 64 <1209600000>;
- opp-microvolt = <905000 905000 1140000>;
- opp-supported-hw = <0x70>;
- clock-latency-ns = <200000>;
- };
- opp-1248000000 {
- opp-hz = /bits/ 64 <1248000000>;
- opp-microvolt = <905000 905000 1140000>;
- opp-supported-hw = <0x7>;
- clock-latency-ns = <200000>;
- };
- opp-1286400000 {
- opp-hz = /bits/ 64 <1286400000>;
- opp-microvolt = <905000 905000 1140000>;
- opp-supported-hw = <0x70>;
- clock-latency-ns = <200000>;
- };
- opp-1324800000 {
- opp-hz = /bits/ 64 <1324800000>;
- opp-microvolt = <1140000 905000 1140000>;
- opp-supported-hw = <0x7>;
- clock-latency-ns = <200000>;
- };
- opp-1363200000 {
- opp-hz = /bits/ 64 <1363200000>;
- opp-microvolt = <1140000 905000 1140000>;
- opp-supported-hw = <0x70>;
- clock-latency-ns = <200000>;
- };
- opp-1401600000 {
- opp-hz = /bits/ 64 <1401600000>;
- opp-microvolt = <1140000 905000 1140000>;
- opp-supported-hw = <0x7>;
- clock-latency-ns = <200000>;
- };
- opp-1440000000 {
- opp-hz = /bits/ 64 <1440000000>;
- opp-microvolt = <1140000 905000 1140000>;
- opp-supported-hw = <0x70>;
- clock-latency-ns = <200000>;
- };
- opp-1478400000 {
- opp-hz = /bits/ 64 <1478400000>;
- opp-microvolt = <1140000 905000 1140000>;
- opp-supported-hw = <0x7>;
- clock-latency-ns = <200000>;
- };
- opp-1516800000 {
- opp-hz = /bits/ 64 <1516800000>;
- opp-microvolt = <1140000 905000 1140000>;
- opp-supported-hw = <0x70>;
- clock-latency-ns = <200000>;
- };
- opp-1555200000 {
- opp-hz = /bits/ 64 <1555200000>;
- opp-microvolt = <1140000 905000 1140000>;
- opp-supported-hw = <0x7>;
- clock-latency-ns = <200000>;
- };
- opp-1593600000 {
- opp-hz = /bits/ 64 <1593600000>;
- opp-microvolt = <1140000 905000 1140000>;
- opp-supported-hw = <0x70>;
- clock-latency-ns = <200000>;
- };
- opp-1632000000 {
- opp-hz = /bits/ 64 <1632000000>;
- opp-microvolt = <1140000 905000 1140000>;
- opp-supported-hw = <0x7>;
- clock-latency-ns = <200000>;
- };
- opp-1670400000 {
- opp-hz = /bits/ 64 <1670400000>;
- opp-microvolt = <1140000 905000 1140000>;
- opp-supported-hw = <0x70>;
- clock-latency-ns = <200000>;
- };
- opp-1708800000 {
- opp-hz = /bits/ 64 <1708800000>;
- opp-microvolt = <1140000 905000 1140000>;
- opp-supported-hw = <0x7>;
- clock-latency-ns = <200000>;
- };
- opp-1747200000 {
- opp-hz = /bits/ 64 <1747200000>;
- opp-microvolt = <1140000 905000 1140000>;
- opp-supported-hw = <0x70>;
- clock-latency-ns = <200000>;
- };
- opp-1785600000 {
- opp-hz = /bits/ 64 <1785600000>;
- opp-microvolt = <1140000 905000 1140000>;
- opp-supported-hw = <0x7>;
- clock-latency-ns = <200000>;
- };
- opp-1804800000 {
- opp-hz = /bits/ 64 <1804800000>;
- opp-microvolt = <1140000 905000 1140000>;
- opp-supported-hw = <0x6>;
- clock-latency-ns = <200000>;
- };
- opp-1824000000 {
- opp-hz = /bits/ 64 <1824000000>;
- opp-microvolt = <1140000 905000 1140000>;
- opp-supported-hw = <0x71>;
- clock-latency-ns = <200000>;
- };
- opp-1900800000 {
- opp-hz = /bits/ 64 <1900800000>;
- opp-microvolt = <1140000 905000 1140000>;
- opp-supported-hw = <0x74>;
- clock-latency-ns = <200000>;
- };
- opp-1920000000 {
- opp-hz = /bits/ 64 <1920000000>;
- opp-microvolt = <1140000 905000 1140000>;
- opp-supported-hw = <0x1>;
- clock-latency-ns = <200000>;
- };
- opp-1977600000 {
- opp-hz = /bits/ 64 <1977600000>;
- opp-microvolt = <1140000 905000 1140000>;
- opp-supported-hw = <0x30>;
- clock-latency-ns = <200000>;
- };
- opp-1996800000 {
- opp-hz = /bits/ 64 <1996800000>;
- opp-microvolt = <1140000 905000 1140000>;
- opp-supported-hw = <0x1>;
- clock-latency-ns = <200000>;
- };
- opp-2054400000 {
- opp-hz = /bits/ 64 <2054400000>;
- opp-microvolt = <1140000 905000 1140000>;
- opp-supported-hw = <0x30>;
- clock-latency-ns = <200000>;
- };
- opp-2073600000 {
- opp-hz = /bits/ 64 <2073600000>;
- opp-microvolt = <1140000 905000 1140000>;
- opp-supported-hw = <0x1>;
- clock-latency-ns = <200000>;
- };
- opp-2150400000 {
- opp-hz = /bits/ 64 <2150400000>;
- opp-microvolt = <1140000 905000 1140000>;
- opp-supported-hw = <0x31>;
- clock-latency-ns = <200000>;
- };
- opp-2246400000 {
- opp-hz = /bits/ 64 <2246400000>;
- opp-microvolt = <1140000 905000 1140000>;
- opp-supported-hw = <0x10>;
- clock-latency-ns = <200000>;
- };
- opp-2342400000 {
- opp-hz = /bits/ 64 <2342400000>;
- opp-microvolt = <1140000 905000 1140000>;
- opp-supported-hw = <0x10>;
- clock-latency-ns = <200000>;
- };
- };
-
-....
-
-reserved-memory {
- #address-cells = <2>;
- #size-cells = <2>;
- ranges;
-....
- smem_mem: smem-mem@86000000 {
- reg = <0x0 0x86000000 0x0 0x200000>;
- no-map;
- };
-....
-};
-
-smem {
- compatible = "qcom,smem";
- memory-region = <&smem_mem>;
- hwlocks = <&tcsr_mutex 3>;
-};
-
-soc {
-....
- qfprom: qfprom@74000 {
- compatible = "qcom,qfprom";
- reg = <0x00074000 0x8ff>;
- #address-cells = <1>;
- #size-cells = <1>;
- ....
- speedbin_efuse: speedbin@133 {
- reg = <0x133 0x1>;
- bits = <5 3>;
- };
- };
-};
diff --git a/Documentation/devicetree/bindings/opp/opp.txt b/Documentation/devicetree/bindings/opp/opp.txt
index 76b6c79..6859227 100644
--- a/Documentation/devicetree/bindings/opp/opp.txt
+++ b/Documentation/devicetree/bindings/opp/opp.txt
@@ -140,8 +140,8 @@
frequency for a short duration of time limited by the device's power, current
and thermal limits.
-- opp-suspend: Marks the OPP to be used during device suspend. Only one OPP in
- the table should have this.
+- opp-suspend: Marks the OPP to be used during device suspend. If multiple OPPs
+ in the table have this, the OPP with highest opp-hz will be used.
- opp-supported-hw: This enables us to select only a subset of OPPs from the
larger OPP table, based on what version of the hardware we are running on. We
diff --git a/Documentation/devicetree/bindings/opp/qcom-nvmem-cpufreq.txt b/Documentation/devicetree/bindings/opp/qcom-nvmem-cpufreq.txt
new file mode 100644
index 0000000..4751029
--- /dev/null
+++ b/Documentation/devicetree/bindings/opp/qcom-nvmem-cpufreq.txt
@@ -0,0 +1,795 @@
+Qualcomm Technologies, Inc. NVMEM CPUFreq and OPP bindings
+===================================
+
+In Certain Qualcomm Technologies, Inc. SoCs like apq8096 and msm8996,
+the CPU frequencies subset and voltage value of each OPP varies based on
+the silicon variant in use.
+Qualcomm Technologies, Inc. Process Voltage Scaling Tables
+defines the voltage and frequency value based on the msm-id in SMEM
+and speedbin blown in the efuse combination.
+The qcom-cpufreq-nvmem driver reads the msm-id and efuse value from the SoC
+to provide the OPP framework with required information (existing HW bitmap).
+This is used to determine the voltage and frequency value for each OPP of
+operating-points-v2 table when it is parsed by the OPP framework.
+
+Required properties:
+--------------------
+In 'cpu' nodes:
+- operating-points-v2: Phandle to the operating-points-v2 table to use.
+
+In 'operating-points-v2' table:
+- compatible: Should be
+ - 'operating-points-v2-kryo-cpu' for apq8096 and msm8996.
+
+Optional properties:
+--------------------
+In 'cpu' nodes:
+- power-domains: A phandle pointing to the PM domain specifier which provides
+ the performance states available for active state management.
+ Please refer to the power-domains bindings
+ Documentation/devicetree/bindings/power/power_domain.txt
+ and also examples below.
+- power-domain-names: Should be
+ - 'cpr' for qcs404.
+
+In 'operating-points-v2' table:
+- nvmem-cells: A phandle pointing to a nvmem-cells node representing the
+ efuse registers that has information about the
+ speedbin that is used to select the right frequency/voltage
+ value pair.
+ Please refer the for nvmem-cells
+ bindings Documentation/devicetree/bindings/nvmem/nvmem.txt
+ and also examples below.
+
+In every OPP node:
+- opp-supported-hw: A single 32 bit bitmap value, representing compatible HW.
+ Bitmap:
+ 0: MSM8996 V3, speedbin 0
+ 1: MSM8996 V3, speedbin 1
+ 2: MSM8996 V3, speedbin 2
+ 3: unused
+ 4: MSM8996 SG, speedbin 0
+ 5: MSM8996 SG, speedbin 1
+ 6: MSM8996 SG, speedbin 2
+ 7-31: unused
+
+Example 1:
+---------
+
+ cpus {
+ #address-cells = <2>;
+ #size-cells = <0>;
+
+ CPU0: cpu@0 {
+ device_type = "cpu";
+ compatible = "qcom,kryo";
+ reg = <0x0 0x0>;
+ enable-method = "psci";
+ clocks = <&kryocc 0>;
+ cpu-supply = <&pm8994_s11_saw>;
+ operating-points-v2 = <&cluster0_opp>;
+ #cooling-cells = <2>;
+ next-level-cache = <&L2_0>;
+ L2_0: l2-cache {
+ compatible = "cache";
+ cache-level = <2>;
+ };
+ };
+
+ CPU1: cpu@1 {
+ device_type = "cpu";
+ compatible = "qcom,kryo";
+ reg = <0x0 0x1>;
+ enable-method = "psci";
+ clocks = <&kryocc 0>;
+ cpu-supply = <&pm8994_s11_saw>;
+ operating-points-v2 = <&cluster0_opp>;
+ #cooling-cells = <2>;
+ next-level-cache = <&L2_0>;
+ };
+
+ CPU2: cpu@100 {
+ device_type = "cpu";
+ compatible = "qcom,kryo";
+ reg = <0x0 0x100>;
+ enable-method = "psci";
+ clocks = <&kryocc 1>;
+ cpu-supply = <&pm8994_s11_saw>;
+ operating-points-v2 = <&cluster1_opp>;
+ #cooling-cells = <2>;
+ next-level-cache = <&L2_1>;
+ L2_1: l2-cache {
+ compatible = "cache";
+ cache-level = <2>;
+ };
+ };
+
+ CPU3: cpu@101 {
+ device_type = "cpu";
+ compatible = "qcom,kryo";
+ reg = <0x0 0x101>;
+ enable-method = "psci";
+ clocks = <&kryocc 1>;
+ cpu-supply = <&pm8994_s11_saw>;
+ operating-points-v2 = <&cluster1_opp>;
+ #cooling-cells = <2>;
+ next-level-cache = <&L2_1>;
+ };
+
+ cpu-map {
+ cluster0 {
+ core0 {
+ cpu = <&CPU0>;
+ };
+
+ core1 {
+ cpu = <&CPU1>;
+ };
+ };
+
+ cluster1 {
+ core0 {
+ cpu = <&CPU2>;
+ };
+
+ core1 {
+ cpu = <&CPU3>;
+ };
+ };
+ };
+ };
+
+ cluster0_opp: opp_table0 {
+ compatible = "operating-points-v2-kryo-cpu";
+ nvmem-cells = <&speedbin_efuse>;
+ opp-shared;
+
+ opp-307200000 {
+ opp-hz = /bits/ 64 <307200000>;
+ opp-microvolt = <905000 905000 1140000>;
+ opp-supported-hw = <0x77>;
+ clock-latency-ns = <200000>;
+ };
+ opp-384000000 {
+ opp-hz = /bits/ 64 <384000000>;
+ opp-microvolt = <905000 905000 1140000>;
+ opp-supported-hw = <0x70>;
+ clock-latency-ns = <200000>;
+ };
+ opp-422400000 {
+ opp-hz = /bits/ 64 <422400000>;
+ opp-microvolt = <905000 905000 1140000>;
+ opp-supported-hw = <0x7>;
+ clock-latency-ns = <200000>;
+ };
+ opp-460800000 {
+ opp-hz = /bits/ 64 <460800000>;
+ opp-microvolt = <905000 905000 1140000>;
+ opp-supported-hw = <0x70>;
+ clock-latency-ns = <200000>;
+ };
+ opp-480000000 {
+ opp-hz = /bits/ 64 <480000000>;
+ opp-microvolt = <905000 905000 1140000>;
+ opp-supported-hw = <0x7>;
+ clock-latency-ns = <200000>;
+ };
+ opp-537600000 {
+ opp-hz = /bits/ 64 <537600000>;
+ opp-microvolt = <905000 905000 1140000>;
+ opp-supported-hw = <0x70>;
+ clock-latency-ns = <200000>;
+ };
+ opp-556800000 {
+ opp-hz = /bits/ 64 <556800000>;
+ opp-microvolt = <905000 905000 1140000>;
+ opp-supported-hw = <0x7>;
+ clock-latency-ns = <200000>;
+ };
+ opp-614400000 {
+ opp-hz = /bits/ 64 <614400000>;
+ opp-microvolt = <905000 905000 1140000>;
+ opp-supported-hw = <0x70>;
+ clock-latency-ns = <200000>;
+ };
+ opp-652800000 {
+ opp-hz = /bits/ 64 <652800000>;
+ opp-microvolt = <905000 905000 1140000>;
+ opp-supported-hw = <0x7>;
+ clock-latency-ns = <200000>;
+ };
+ opp-691200000 {
+ opp-hz = /bits/ 64 <691200000>;
+ opp-microvolt = <905000 905000 1140000>;
+ opp-supported-hw = <0x70>;
+ clock-latency-ns = <200000>;
+ };
+ opp-729600000 {
+ opp-hz = /bits/ 64 <729600000>;
+ opp-microvolt = <905000 905000 1140000>;
+ opp-supported-hw = <0x7>;
+ clock-latency-ns = <200000>;
+ };
+ opp-768000000 {
+ opp-hz = /bits/ 64 <768000000>;
+ opp-microvolt = <905000 905000 1140000>;
+ opp-supported-hw = <0x70>;
+ clock-latency-ns = <200000>;
+ };
+ opp-844800000 {
+ opp-hz = /bits/ 64 <844800000>;
+ opp-microvolt = <905000 905000 1140000>;
+ opp-supported-hw = <0x77>;
+ clock-latency-ns = <200000>;
+ };
+ opp-902400000 {
+ opp-hz = /bits/ 64 <902400000>;
+ opp-microvolt = <905000 905000 1140000>;
+ opp-supported-hw = <0x70>;
+ clock-latency-ns = <200000>;
+ };
+ opp-960000000 {
+ opp-hz = /bits/ 64 <960000000>;
+ opp-microvolt = <905000 905000 1140000>;
+ opp-supported-hw = <0x7>;
+ clock-latency-ns = <200000>;
+ };
+ opp-979200000 {
+ opp-hz = /bits/ 64 <979200000>;
+ opp-microvolt = <905000 905000 1140000>;
+ opp-supported-hw = <0x70>;
+ clock-latency-ns = <200000>;
+ };
+ opp-1036800000 {
+ opp-hz = /bits/ 64 <1036800000>;
+ opp-microvolt = <905000 905000 1140000>;
+ opp-supported-hw = <0x7>;
+ clock-latency-ns = <200000>;
+ };
+ opp-1056000000 {
+ opp-hz = /bits/ 64 <1056000000>;
+ opp-microvolt = <905000 905000 1140000>;
+ opp-supported-hw = <0x70>;
+ clock-latency-ns = <200000>;
+ };
+ opp-1113600000 {
+ opp-hz = /bits/ 64 <1113600000>;
+ opp-microvolt = <905000 905000 1140000>;
+ opp-supported-hw = <0x7>;
+ clock-latency-ns = <200000>;
+ };
+ opp-1132800000 {
+ opp-hz = /bits/ 64 <1132800000>;
+ opp-microvolt = <905000 905000 1140000>;
+ opp-supported-hw = <0x70>;
+ clock-latency-ns = <200000>;
+ };
+ opp-1190400000 {
+ opp-hz = /bits/ 64 <1190400000>;
+ opp-microvolt = <905000 905000 1140000>;
+ opp-supported-hw = <0x7>;
+ clock-latency-ns = <200000>;
+ };
+ opp-1209600000 {
+ opp-hz = /bits/ 64 <1209600000>;
+ opp-microvolt = <905000 905000 1140000>;
+ opp-supported-hw = <0x70>;
+ clock-latency-ns = <200000>;
+ };
+ opp-1228800000 {
+ opp-hz = /bits/ 64 <1228800000>;
+ opp-microvolt = <905000 905000 1140000>;
+ opp-supported-hw = <0x7>;
+ clock-latency-ns = <200000>;
+ };
+ opp-1286400000 {
+ opp-hz = /bits/ 64 <1286400000>;
+ opp-microvolt = <1140000 905000 1140000>;
+ opp-supported-hw = <0x70>;
+ clock-latency-ns = <200000>;
+ };
+ opp-1324800000 {
+ opp-hz = /bits/ 64 <1324800000>;
+ opp-microvolt = <1140000 905000 1140000>;
+ opp-supported-hw = <0x5>;
+ clock-latency-ns = <200000>;
+ };
+ opp-1363200000 {
+ opp-hz = /bits/ 64 <1363200000>;
+ opp-microvolt = <1140000 905000 1140000>;
+ opp-supported-hw = <0x72>;
+ clock-latency-ns = <200000>;
+ };
+ opp-1401600000 {
+ opp-hz = /bits/ 64 <1401600000>;
+ opp-microvolt = <1140000 905000 1140000>;
+ opp-supported-hw = <0x5>;
+ clock-latency-ns = <200000>;
+ };
+ opp-1440000000 {
+ opp-hz = /bits/ 64 <1440000000>;
+ opp-microvolt = <1140000 905000 1140000>;
+ opp-supported-hw = <0x70>;
+ clock-latency-ns = <200000>;
+ };
+ opp-1478400000 {
+ opp-hz = /bits/ 64 <1478400000>;
+ opp-microvolt = <1140000 905000 1140000>;
+ opp-supported-hw = <0x1>;
+ clock-latency-ns = <200000>;
+ };
+ opp-1497600000 {
+ opp-hz = /bits/ 64 <1497600000>;
+ opp-microvolt = <1140000 905000 1140000>;
+ opp-supported-hw = <0x4>;
+ clock-latency-ns = <200000>;
+ };
+ opp-1516800000 {
+ opp-hz = /bits/ 64 <1516800000>;
+ opp-microvolt = <1140000 905000 1140000>;
+ opp-supported-hw = <0x70>;
+ clock-latency-ns = <200000>;
+ };
+ opp-1593600000 {
+ opp-hz = /bits/ 64 <1593600000>;
+ opp-microvolt = <1140000 905000 1140000>;
+ opp-supported-hw = <0x71>;
+ clock-latency-ns = <200000>;
+ };
+ opp-1996800000 {
+ opp-hz = /bits/ 64 <1996800000>;
+ opp-microvolt = <1140000 905000 1140000>;
+ opp-supported-hw = <0x20>;
+ clock-latency-ns = <200000>;
+ };
+ opp-2188800000 {
+ opp-hz = /bits/ 64 <2188800000>;
+ opp-microvolt = <1140000 905000 1140000>;
+ opp-supported-hw = <0x10>;
+ clock-latency-ns = <200000>;
+ };
+ };
+
+ cluster1_opp: opp_table1 {
+ compatible = "operating-points-v2-kryo-cpu";
+ nvmem-cells = <&speedbin_efuse>;
+ opp-shared;
+
+ opp-307200000 {
+ opp-hz = /bits/ 64 <307200000>;
+ opp-microvolt = <905000 905000 1140000>;
+ opp-supported-hw = <0x77>;
+ clock-latency-ns = <200000>;
+ };
+ opp-384000000 {
+ opp-hz = /bits/ 64 <384000000>;
+ opp-microvolt = <905000 905000 1140000>;
+ opp-supported-hw = <0x70>;
+ clock-latency-ns = <200000>;
+ };
+ opp-403200000 {
+ opp-hz = /bits/ 64 <403200000>;
+ opp-microvolt = <905000 905000 1140000>;
+ opp-supported-hw = <0x7>;
+ clock-latency-ns = <200000>;
+ };
+ opp-460800000 {
+ opp-hz = /bits/ 64 <460800000>;
+ opp-microvolt = <905000 905000 1140000>;
+ opp-supported-hw = <0x70>;
+ clock-latency-ns = <200000>;
+ };
+ opp-480000000 {
+ opp-hz = /bits/ 64 <480000000>;
+ opp-microvolt = <905000 905000 1140000>;
+ opp-supported-hw = <0x7>;
+ clock-latency-ns = <200000>;
+ };
+ opp-537600000 {
+ opp-hz = /bits/ 64 <537600000>;
+ opp-microvolt = <905000 905000 1140000>;
+ opp-supported-hw = <0x70>;
+ clock-latency-ns = <200000>;
+ };
+ opp-556800000 {
+ opp-hz = /bits/ 64 <556800000>;
+ opp-microvolt = <905000 905000 1140000>;
+ opp-supported-hw = <0x7>;
+ clock-latency-ns = <200000>;
+ };
+ opp-614400000 {
+ opp-hz = /bits/ 64 <614400000>;
+ opp-microvolt = <905000 905000 1140000>;
+ opp-supported-hw = <0x70>;
+ clock-latency-ns = <200000>;
+ };
+ opp-652800000 {
+ opp-hz = /bits/ 64 <652800000>;
+ opp-microvolt = <905000 905000 1140000>;
+ opp-supported-hw = <0x7>;
+ clock-latency-ns = <200000>;
+ };
+ opp-691200000 {
+ opp-hz = /bits/ 64 <691200000>;
+ opp-microvolt = <905000 905000 1140000>;
+ opp-supported-hw = <0x70>;
+ clock-latency-ns = <200000>;
+ };
+ opp-729600000 {
+ opp-hz = /bits/ 64 <729600000>;
+ opp-microvolt = <905000 905000 1140000>;
+ opp-supported-hw = <0x7>;
+ clock-latency-ns = <200000>;
+ };
+ opp-748800000 {
+ opp-hz = /bits/ 64 <748800000>;
+ opp-microvolt = <905000 905000 1140000>;
+ opp-supported-hw = <0x70>;
+ clock-latency-ns = <200000>;
+ };
+ opp-806400000 {
+ opp-hz = /bits/ 64 <806400000>;
+ opp-microvolt = <905000 905000 1140000>;
+ opp-supported-hw = <0x7>;
+ clock-latency-ns = <200000>;
+ };
+ opp-825600000 {
+ opp-hz = /bits/ 64 <825600000>;
+ opp-microvolt = <905000 905000 1140000>;
+ opp-supported-hw = <0x70>;
+ clock-latency-ns = <200000>;
+ };
+ opp-883200000 {
+ opp-hz = /bits/ 64 <883200000>;
+ opp-microvolt = <905000 905000 1140000>;
+ opp-supported-hw = <0x7>;
+ clock-latency-ns = <200000>;
+ };
+ opp-902400000 {
+ opp-hz = /bits/ 64 <902400000>;
+ opp-microvolt = <905000 905000 1140000>;
+ opp-supported-hw = <0x70>;
+ clock-latency-ns = <200000>;
+ };
+ opp-940800000 {
+ opp-hz = /bits/ 64 <940800000>;
+ opp-microvolt = <905000 905000 1140000>;
+ opp-supported-hw = <0x7>;
+ clock-latency-ns = <200000>;
+ };
+ opp-979200000 {
+ opp-hz = /bits/ 64 <979200000>;
+ opp-microvolt = <905000 905000 1140000>;
+ opp-supported-hw = <0x70>;
+ clock-latency-ns = <200000>;
+ };
+ opp-1036800000 {
+ opp-hz = /bits/ 64 <1036800000>;
+ opp-microvolt = <905000 905000 1140000>;
+ opp-supported-hw = <0x7>;
+ clock-latency-ns = <200000>;
+ };
+ opp-1056000000 {
+ opp-hz = /bits/ 64 <1056000000>;
+ opp-microvolt = <905000 905000 1140000>;
+ opp-supported-hw = <0x70>;
+ clock-latency-ns = <200000>;
+ };
+ opp-1113600000 {
+ opp-hz = /bits/ 64 <1113600000>;
+ opp-microvolt = <905000 905000 1140000>;
+ opp-supported-hw = <0x7>;
+ clock-latency-ns = <200000>;
+ };
+ opp-1132800000 {
+ opp-hz = /bits/ 64 <1132800000>;
+ opp-microvolt = <905000 905000 1140000>;
+ opp-supported-hw = <0x70>;
+ clock-latency-ns = <200000>;
+ };
+ opp-1190400000 {
+ opp-hz = /bits/ 64 <1190400000>;
+ opp-microvolt = <905000 905000 1140000>;
+ opp-supported-hw = <0x7>;
+ clock-latency-ns = <200000>;
+ };
+ opp-1209600000 {
+ opp-hz = /bits/ 64 <1209600000>;
+ opp-microvolt = <905000 905000 1140000>;
+ opp-supported-hw = <0x70>;
+ clock-latency-ns = <200000>;
+ };
+ opp-1248000000 {
+ opp-hz = /bits/ 64 <1248000000>;
+ opp-microvolt = <905000 905000 1140000>;
+ opp-supported-hw = <0x7>;
+ clock-latency-ns = <200000>;
+ };
+ opp-1286400000 {
+ opp-hz = /bits/ 64 <1286400000>;
+ opp-microvolt = <905000 905000 1140000>;
+ opp-supported-hw = <0x70>;
+ clock-latency-ns = <200000>;
+ };
+ opp-1324800000 {
+ opp-hz = /bits/ 64 <1324800000>;
+ opp-microvolt = <1140000 905000 1140000>;
+ opp-supported-hw = <0x7>;
+ clock-latency-ns = <200000>;
+ };
+ opp-1363200000 {
+ opp-hz = /bits/ 64 <1363200000>;
+ opp-microvolt = <1140000 905000 1140000>;
+ opp-supported-hw = <0x70>;
+ clock-latency-ns = <200000>;
+ };
+ opp-1401600000 {
+ opp-hz = /bits/ 64 <1401600000>;
+ opp-microvolt = <1140000 905000 1140000>;
+ opp-supported-hw = <0x7>;
+ clock-latency-ns = <200000>;
+ };
+ opp-1440000000 {
+ opp-hz = /bits/ 64 <1440000000>;
+ opp-microvolt = <1140000 905000 1140000>;
+ opp-supported-hw = <0x70>;
+ clock-latency-ns = <200000>;
+ };
+ opp-1478400000 {
+ opp-hz = /bits/ 64 <1478400000>;
+ opp-microvolt = <1140000 905000 1140000>;
+ opp-supported-hw = <0x7>;
+ clock-latency-ns = <200000>;
+ };
+ opp-1516800000 {
+ opp-hz = /bits/ 64 <1516800000>;
+ opp-microvolt = <1140000 905000 1140000>;
+ opp-supported-hw = <0x70>;
+ clock-latency-ns = <200000>;
+ };
+ opp-1555200000 {
+ opp-hz = /bits/ 64 <1555200000>;
+ opp-microvolt = <1140000 905000 1140000>;
+ opp-supported-hw = <0x7>;
+ clock-latency-ns = <200000>;
+ };
+ opp-1593600000 {
+ opp-hz = /bits/ 64 <1593600000>;
+ opp-microvolt = <1140000 905000 1140000>;
+ opp-supported-hw = <0x70>;
+ clock-latency-ns = <200000>;
+ };
+ opp-1632000000 {
+ opp-hz = /bits/ 64 <1632000000>;
+ opp-microvolt = <1140000 905000 1140000>;
+ opp-supported-hw = <0x7>;
+ clock-latency-ns = <200000>;
+ };
+ opp-1670400000 {
+ opp-hz = /bits/ 64 <1670400000>;
+ opp-microvolt = <1140000 905000 1140000>;
+ opp-supported-hw = <0x70>;
+ clock-latency-ns = <200000>;
+ };
+ opp-1708800000 {
+ opp-hz = /bits/ 64 <1708800000>;
+ opp-microvolt = <1140000 905000 1140000>;
+ opp-supported-hw = <0x7>;
+ clock-latency-ns = <200000>;
+ };
+ opp-1747200000 {
+ opp-hz = /bits/ 64 <1747200000>;
+ opp-microvolt = <1140000 905000 1140000>;
+ opp-supported-hw = <0x70>;
+ clock-latency-ns = <200000>;
+ };
+ opp-1785600000 {
+ opp-hz = /bits/ 64 <1785600000>;
+ opp-microvolt = <1140000 905000 1140000>;
+ opp-supported-hw = <0x7>;
+ clock-latency-ns = <200000>;
+ };
+ opp-1804800000 {
+ opp-hz = /bits/ 64 <1804800000>;
+ opp-microvolt = <1140000 905000 1140000>;
+ opp-supported-hw = <0x6>;
+ clock-latency-ns = <200000>;
+ };
+ opp-1824000000 {
+ opp-hz = /bits/ 64 <1824000000>;
+ opp-microvolt = <1140000 905000 1140000>;
+ opp-supported-hw = <0x71>;
+ clock-latency-ns = <200000>;
+ };
+ opp-1900800000 {
+ opp-hz = /bits/ 64 <1900800000>;
+ opp-microvolt = <1140000 905000 1140000>;
+ opp-supported-hw = <0x74>;
+ clock-latency-ns = <200000>;
+ };
+ opp-1920000000 {
+ opp-hz = /bits/ 64 <1920000000>;
+ opp-microvolt = <1140000 905000 1140000>;
+ opp-supported-hw = <0x1>;
+ clock-latency-ns = <200000>;
+ };
+ opp-1977600000 {
+ opp-hz = /bits/ 64 <1977600000>;
+ opp-microvolt = <1140000 905000 1140000>;
+ opp-supported-hw = <0x30>;
+ clock-latency-ns = <200000>;
+ };
+ opp-1996800000 {
+ opp-hz = /bits/ 64 <1996800000>;
+ opp-microvolt = <1140000 905000 1140000>;
+ opp-supported-hw = <0x1>;
+ clock-latency-ns = <200000>;
+ };
+ opp-2054400000 {
+ opp-hz = /bits/ 64 <2054400000>;
+ opp-microvolt = <1140000 905000 1140000>;
+ opp-supported-hw = <0x30>;
+ clock-latency-ns = <200000>;
+ };
+ opp-2073600000 {
+ opp-hz = /bits/ 64 <2073600000>;
+ opp-microvolt = <1140000 905000 1140000>;
+ opp-supported-hw = <0x1>;
+ clock-latency-ns = <200000>;
+ };
+ opp-2150400000 {
+ opp-hz = /bits/ 64 <2150400000>;
+ opp-microvolt = <1140000 905000 1140000>;
+ opp-supported-hw = <0x31>;
+ clock-latency-ns = <200000>;
+ };
+ opp-2246400000 {
+ opp-hz = /bits/ 64 <2246400000>;
+ opp-microvolt = <1140000 905000 1140000>;
+ opp-supported-hw = <0x10>;
+ clock-latency-ns = <200000>;
+ };
+ opp-2342400000 {
+ opp-hz = /bits/ 64 <2342400000>;
+ opp-microvolt = <1140000 905000 1140000>;
+ opp-supported-hw = <0x10>;
+ clock-latency-ns = <200000>;
+ };
+ };
+
+....
+
+reserved-memory {
+ #address-cells = <2>;
+ #size-cells = <2>;
+ ranges;
+....
+ smem_mem: smem-mem@86000000 {
+ reg = <0x0 0x86000000 0x0 0x200000>;
+ no-map;
+ };
+....
+};
+
+smem {
+ compatible = "qcom,smem";
+ memory-region = <&smem_mem>;
+ hwlocks = <&tcsr_mutex 3>;
+};
+
+soc {
+....
+ qfprom: qfprom@74000 {
+ compatible = "qcom,qfprom";
+ reg = <0x00074000 0x8ff>;
+ #address-cells = <1>;
+ #size-cells = <1>;
+ ....
+ speedbin_efuse: speedbin@133 {
+ reg = <0x133 0x1>;
+ bits = <5 3>;
+ };
+ };
+};
+
+Example 2:
+---------
+
+ cpus {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ CPU0: cpu@100 {
+ device_type = "cpu";
+ compatible = "arm,cortex-a53";
+ reg = <0x100>;
+ ....
+ clocks = <&apcs_glb>;
+ operating-points-v2 = <&cpu_opp_table>;
+ power-domains = <&cpr>;
+ power-domain-names = "cpr";
+ };
+
+ CPU1: cpu@101 {
+ device_type = "cpu";
+ compatible = "arm,cortex-a53";
+ reg = <0x101>;
+ ....
+ clocks = <&apcs_glb>;
+ operating-points-v2 = <&cpu_opp_table>;
+ power-domains = <&cpr>;
+ power-domain-names = "cpr";
+ };
+
+ CPU2: cpu@102 {
+ device_type = "cpu";
+ compatible = "arm,cortex-a53";
+ reg = <0x102>;
+ ....
+ clocks = <&apcs_glb>;
+ operating-points-v2 = <&cpu_opp_table>;
+ power-domains = <&cpr>;
+ power-domain-names = "cpr";
+ };
+
+ CPU3: cpu@103 {
+ device_type = "cpu";
+ compatible = "arm,cortex-a53";
+ reg = <0x103>;
+ ....
+ clocks = <&apcs_glb>;
+ operating-points-v2 = <&cpu_opp_table>;
+ power-domains = <&cpr>;
+ power-domain-names = "cpr";
+ };
+ };
+
+ cpu_opp_table: cpu-opp-table {
+ compatible = "operating-points-v2-kryo-cpu";
+ opp-shared;
+
+ opp-1094400000 {
+ opp-hz = /bits/ 64 <1094400000>;
+ required-opps = <&cpr_opp1>;
+ };
+ opp-1248000000 {
+ opp-hz = /bits/ 64 <1248000000>;
+ required-opps = <&cpr_opp2>;
+ };
+ opp-1401600000 {
+ opp-hz = /bits/ 64 <1401600000>;
+ required-opps = <&cpr_opp3>;
+ };
+ };
+
+ cpr_opp_table: cpr-opp-table {
+ compatible = "operating-points-v2-qcom-level";
+
+ cpr_opp1: opp1 {
+ opp-level = <1>;
+ qcom,opp-fuse-level = <1>;
+ };
+ cpr_opp2: opp2 {
+ opp-level = <2>;
+ qcom,opp-fuse-level = <2>;
+ };
+ cpr_opp3: opp3 {
+ opp-level = <3>;
+ qcom,opp-fuse-level = <3>;
+ };
+ };
+
+....
+
+soc {
+....
+ cpr: power-controller@b018000 {
+ compatible = "qcom,qcs404-cpr", "qcom,cpr";
+ reg = <0x0b018000 0x1000>;
+ ....
+ vdd-apc-supply = <&pms405_s3>;
+ #power-domain-cells = <0>;
+ operating-points-v2 = <&cpr_opp_table>;
+ ....
+ };
+};
diff --git a/Documentation/devicetree/bindings/opp/qcom-opp.txt b/Documentation/devicetree/bindings/opp/qcom-opp.txt
new file mode 100644
index 0000000..32eb079
--- /dev/null
+++ b/Documentation/devicetree/bindings/opp/qcom-opp.txt
@@ -0,0 +1,19 @@
+Qualcomm OPP bindings to describe OPP nodes
+
+The bindings are based on top of the operating-points-v2 bindings
+described in Documentation/devicetree/bindings/opp/opp.txt
+Additional properties are described below.
+
+* OPP Table Node
+
+Required properties:
+- compatible: Allow OPPs to express their compatibility. It should be:
+ "operating-points-v2-qcom-level"
+
+* OPP Node
+
+Required properties:
+- qcom,opp-fuse-level: A positive value representing the fuse corner/level
+ associated with this OPP node. Sometimes several corners/levels shares
+ a certain fuse corner/level. A fuse corner/level contains e.g. ref uV,
+ min uV, and max uV.
diff --git a/Documentation/devicetree/bindings/opp/sun50i-nvmem-cpufreq.txt b/Documentation/devicetree/bindings/opp/sun50i-nvmem-cpufreq.txt
new file mode 100644
index 0000000..7deae57
--- /dev/null
+++ b/Documentation/devicetree/bindings/opp/sun50i-nvmem-cpufreq.txt
@@ -0,0 +1,167 @@
+Allwinner Technologies, Inc. NVMEM CPUFreq and OPP bindings
+===================================
+
+For some SoCs, the CPU frequency subset and voltage value of each OPP
+varies based on the silicon variant in use. Allwinner Process Voltage
+Scaling Tables defines the voltage and frequency value based on the
+speedbin blown in the efuse combination. The sun50i-cpufreq-nvmem driver
+reads the efuse value from the SoC to provide the OPP framework with
+required information.
+
+Required properties:
+--------------------
+In 'cpus' nodes:
+- operating-points-v2: Phandle to the operating-points-v2 table to use.
+
+In 'operating-points-v2' table:
+- compatible: Should be
+ - 'allwinner,sun50i-h6-operating-points'.
+- nvmem-cells: A phandle pointing to a nvmem-cells node representing the
+ efuse registers that has information about the speedbin
+ that is used to select the right frequency/voltage value
+ pair. Please refer the for nvmem-cells bindings
+ Documentation/devicetree/bindings/nvmem/nvmem.txt and
+ also examples below.
+
+In every OPP node:
+- opp-microvolt-<name>: Voltage in micro Volts.
+ At runtime, the platform can pick a <name> and
+ matching opp-microvolt-<name> property.
+ [See: opp.txt]
+ HW: <name>:
+ sun50i-h6 speed0 speed1 speed2
+
+Example 1:
+---------
+
+ cpus {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ cpu0: cpu@0 {
+ compatible = "arm,cortex-a53";
+ device_type = "cpu";
+ reg = <0>;
+ enable-method = "psci";
+ clocks = <&ccu CLK_CPUX>;
+ clock-latency-ns = <244144>; /* 8 32k periods */
+ operating-points-v2 = <&cpu_opp_table>;
+ #cooling-cells = <2>;
+ };
+
+ cpu1: cpu@1 {
+ compatible = "arm,cortex-a53";
+ device_type = "cpu";
+ reg = <1>;
+ enable-method = "psci";
+ clocks = <&ccu CLK_CPUX>;
+ clock-latency-ns = <244144>; /* 8 32k periods */
+ operating-points-v2 = <&cpu_opp_table>;
+ #cooling-cells = <2>;
+ };
+
+ cpu2: cpu@2 {
+ compatible = "arm,cortex-a53";
+ device_type = "cpu";
+ reg = <2>;
+ enable-method = "psci";
+ clocks = <&ccu CLK_CPUX>;
+ clock-latency-ns = <244144>; /* 8 32k periods */
+ operating-points-v2 = <&cpu_opp_table>;
+ #cooling-cells = <2>;
+ };
+
+ cpu3: cpu@3 {
+ compatible = "arm,cortex-a53";
+ device_type = "cpu";
+ reg = <3>;
+ enable-method = "psci";
+ clocks = <&ccu CLK_CPUX>;
+ clock-latency-ns = <244144>; /* 8 32k periods */
+ operating-points-v2 = <&cpu_opp_table>;
+ #cooling-cells = <2>;
+ };
+ };
+
+ cpu_opp_table: opp_table {
+ compatible = "allwinner,sun50i-h6-operating-points";
+ nvmem-cells = <&speedbin_efuse>;
+ opp-shared;
+
+ opp@480000000 {
+ clock-latency-ns = <244144>; /* 8 32k periods */
+ opp-hz = /bits/ 64 <480000000>;
+
+ opp-microvolt-speed0 = <880000>;
+ opp-microvolt-speed1 = <820000>;
+ opp-microvolt-speed2 = <800000>;
+ };
+
+ opp@720000000 {
+ clock-latency-ns = <244144>; /* 8 32k periods */
+ opp-hz = /bits/ 64 <720000000>;
+
+ opp-microvolt-speed0 = <880000>;
+ opp-microvolt-speed1 = <820000>;
+ opp-microvolt-speed2 = <800000>;
+ };
+
+ opp@816000000 {
+ clock-latency-ns = <244144>; /* 8 32k periods */
+ opp-hz = /bits/ 64 <816000000>;
+
+ opp-microvolt-speed0 = <880000>;
+ opp-microvolt-speed1 = <820000>;
+ opp-microvolt-speed2 = <800000>;
+ };
+
+ opp@888000000 {
+ clock-latency-ns = <244144>; /* 8 32k periods */
+ opp-hz = /bits/ 64 <888000000>;
+
+ opp-microvolt-speed0 = <940000>;
+ opp-microvolt-speed1 = <820000>;
+ opp-microvolt-speed2 = <800000>;
+ };
+
+ opp@1080000000 {
+ clock-latency-ns = <244144>; /* 8 32k periods */
+ opp-hz = /bits/ 64 <1080000000>;
+
+ opp-microvolt-speed0 = <1060000>;
+ opp-microvolt-speed1 = <880000>;
+ opp-microvolt-speed2 = <840000>;
+ };
+
+ opp@1320000000 {
+ clock-latency-ns = <244144>; /* 8 32k periods */
+ opp-hz = /bits/ 64 <1320000000>;
+
+ opp-microvolt-speed0 = <1160000>;
+ opp-microvolt-speed1 = <940000>;
+ opp-microvolt-speed2 = <900000>;
+ };
+
+ opp@1488000000 {
+ clock-latency-ns = <244144>; /* 8 32k periods */
+ opp-hz = /bits/ 64 <1488000000>;
+
+ opp-microvolt-speed0 = <1160000>;
+ opp-microvolt-speed1 = <1000000>;
+ opp-microvolt-speed2 = <960000>;
+ };
+ };
+....
+soc {
+....
+ sid: sid@3006000 {
+ compatible = "allwinner,sun50i-h6-sid";
+ reg = <0x03006000 0x400>;
+ #address-cells = <1>;
+ #size-cells = <1>;
+ ....
+ speedbin_efuse: speed@1c {
+ reg = <0x1c 4>;
+ };
+ };
+};
diff --git a/Documentation/devicetree/bindings/pci/designware-pcie.txt b/Documentation/devicetree/bindings/pci/designware-pcie.txt
index 5561a1c..78494c4 100644
--- a/Documentation/devicetree/bindings/pci/designware-pcie.txt
+++ b/Documentation/devicetree/bindings/pci/designware-pcie.txt
@@ -11,7 +11,6 @@
the ATU address space.
(The old way of getting the configuration address space from "ranges"
is deprecated and should be avoided.)
-- num-lanes: number of lanes to use
RC mode:
- #address-cells: set to <3>
- #size-cells: set to <2>
@@ -34,6 +33,11 @@
- clock-names: Must include the following entries:
- "pcie"
- "pcie_bus"
+- snps,enable-cdm-check: This is a boolean property and if present enables
+ automatic checking of CDM (Configuration Dependent Module) registers
+ for data corruption. CDM registers include standard PCIe configuration
+ space registers, Port Logic registers, DMA and iATU (internal Address
+ Translation Unit) registers.
RC mode:
- num-viewport: number of view ports configured in hardware. If a platform
does not specify it, the driver assumes 2.
diff --git a/Documentation/devicetree/bindings/pci/fsl,imx6q-pcie.txt b/Documentation/devicetree/bindings/pci/fsl,imx6q-pcie.txt
index a7f5f5a..de4b2ba 100644
--- a/Documentation/devicetree/bindings/pci/fsl,imx6q-pcie.txt
+++ b/Documentation/devicetree/bindings/pci/fsl,imx6q-pcie.txt
@@ -50,7 +50,7 @@
- power-domains: Must be set to a phandle pointing to PCIE_PHY power domain
- resets: Must contain phandles to PCIe-related reset lines exposed by SRC
IP block
-- reset-names: Must contain the following entires:
+- reset-names: Must contain the following entries:
- "pciephy"
- "apps"
- "turnoff"
diff --git a/Documentation/devicetree/bindings/pci/mediatek-pcie.txt b/Documentation/devicetree/bindings/pci/mediatek-pcie.txt
index 92437a3..7468d66 100644
--- a/Documentation/devicetree/bindings/pci/mediatek-pcie.txt
+++ b/Documentation/devicetree/bindings/pci/mediatek-pcie.txt
@@ -6,6 +6,7 @@
"mediatek,mt2712-pcie"
"mediatek,mt7622-pcie"
"mediatek,mt7623-pcie"
+ "mediatek,mt7629-pcie"
- device_type: Must be "pci"
- reg: Base addresses and lengths of the PCIe subsys and root ports.
- reg-names: Names of the above areas to use during resource lookup.
diff --git a/Documentation/devicetree/bindings/pci/nvidia,tegra194-pcie.txt b/Documentation/devicetree/bindings/pci/nvidia,tegra194-pcie.txt
new file mode 100644
index 0000000..b739f92
--- /dev/null
+++ b/Documentation/devicetree/bindings/pci/nvidia,tegra194-pcie.txt
@@ -0,0 +1,171 @@
+NVIDIA Tegra PCIe controller (Synopsys DesignWare Core based)
+
+This PCIe host controller is based on the Synopsis Designware PCIe IP
+and thus inherits all the common properties defined in designware-pcie.txt.
+
+Required properties:
+- compatible: For Tegra19x, must contain "nvidia,tegra194-pcie".
+- device_type: Must be "pci"
+- power-domains: A phandle to the node that controls power to the respective
+ PCIe controller and a specifier name for the PCIe controller. Following are
+ the specifiers for the different PCIe controllers
+ TEGRA194_POWER_DOMAIN_PCIEX8B: C0
+ TEGRA194_POWER_DOMAIN_PCIEX1A: C1
+ TEGRA194_POWER_DOMAIN_PCIEX1A: C2
+ TEGRA194_POWER_DOMAIN_PCIEX1A: C3
+ TEGRA194_POWER_DOMAIN_PCIEX4A: C4
+ TEGRA194_POWER_DOMAIN_PCIEX8A: C5
+ these specifiers are defined in
+ "include/dt-bindings/power/tegra194-powergate.h" file.
+- reg: A list of physical base address and length pairs for each set of
+ controller registers. Must contain an entry for each entry in the reg-names
+ property.
+- reg-names: Must include the following entries:
+ "appl": Controller's application logic registers
+ "config": As per the definition in designware-pcie.txt
+ "atu_dma": iATU and DMA registers. This is where the iATU (internal Address
+ Translation Unit) registers of the PCIe core are made available
+ for SW access.
+ "dbi": The aperture where root port's own configuration registers are
+ available
+- interrupts: A list of interrupt outputs of the controller. Must contain an
+ entry for each entry in the interrupt-names property.
+- interrupt-names: Must include the following entries:
+ "intr": The Tegra interrupt that is asserted for controller interrupts
+ "msi": The Tegra interrupt that is asserted when an MSI is received
+- bus-range: Range of bus numbers associated with this controller
+- #address-cells: Address representation for root ports (must be 3)
+ - cell 0 specifies the bus and device numbers of the root port:
+ [23:16]: bus number
+ [15:11]: device number
+ - cell 1 denotes the upper 32 address bits and should be 0
+ - cell 2 contains the lower 32 address bits and is used to translate to the
+ CPU address space
+- #size-cells: Size representation for root ports (must be 2)
+- ranges: Describes the translation of addresses for root ports and standard
+ PCI regions. The entries must be 7 cells each, where the first three cells
+ correspond to the address as described for the #address-cells property
+ above, the fourth and fifth cells are for the physical CPU address to
+ translate to and the sixth and seventh cells are as described for the
+ #size-cells property above.
+ - Entries setup the mapping for the standard I/O, memory and
+ prefetchable PCI regions. The first cell determines the type of region
+ that is setup:
+ - 0x81000000: I/O memory region
+ - 0x82000000: non-prefetchable memory region
+ - 0xc2000000: prefetchable memory region
+ Please refer to the standard PCI bus binding document for a more detailed
+ explanation.
+- #interrupt-cells: Size representation for interrupts (must be 1)
+- interrupt-map-mask and interrupt-map: Standard PCI IRQ mapping properties
+ Please refer to the standard PCI bus binding document for a more detailed
+ explanation.
+- clocks: Must contain an entry for each entry in clock-names.
+ See ../clocks/clock-bindings.txt for details.
+- clock-names: Must include the following entries:
+ - core
+- resets: Must contain an entry for each entry in reset-names.
+ See ../reset/reset.txt for details.
+- reset-names: Must include the following entries:
+ - apb
+ - core
+- phys: Must contain a phandle to P2U PHY for each entry in phy-names.
+- phy-names: Must include an entry for each active lane.
+ "p2u-N": where N ranges from 0 to one less than the total number of lanes
+- nvidia,bpmp: Must contain a pair of phandle to BPMP controller node followed
+ by controller-id. Following are the controller ids for each controller.
+ 0: C0
+ 1: C1
+ 2: C2
+ 3: C3
+ 4: C4
+ 5: C5
+- vddio-pex-ctl-supply: Regulator supply for PCIe side band signals
+
+Optional properties:
+- pinctrl-names: A list of pinctrl state names.
+ It is mandatory for C5 controller and optional for other controllers.
+ - "default": Configures PCIe I/O for proper operation.
+- pinctrl-0: phandle for the 'default' state of pin configuration.
+ It is mandatory for C5 controller and optional for other controllers.
+- supports-clkreq: Refer to Documentation/devicetree/bindings/pci/pci.txt
+- nvidia,update-fc-fixup: This is a boolean property and needs to be present to
+ improve performance when a platform is designed in such a way that it
+ satisfies at least one of the following conditions thereby enabling root
+ port to exchange optimum number of FC (Flow Control) credits with
+ downstream devices
+ 1. If C0/C4/C5 run at x1/x2 link widths (irrespective of speed and MPS)
+ 2. If C0/C1/C2/C3/C4/C5 operate at their respective max link widths and
+ a) speed is Gen-2 and MPS is 256B
+ b) speed is >= Gen-3 with any MPS
+- nvidia,aspm-cmrt-us: Common Mode Restore Time for proper operation of ASPM
+ to be specified in microseconds
+- nvidia,aspm-pwr-on-t-us: Power On time for proper operation of ASPM to be
+ specified in microseconds
+- nvidia,aspm-l0s-entrance-latency-us: ASPM L0s entrance latency to be
+ specified in microseconds
+- vpcie3v3-supply: A phandle to the regulator node that supplies 3.3V to the slot
+ if the platform has one such slot. (Ex:- x16 slot owned by C5 controller
+ in p2972-0000 platform).
+- vpcie12v-supply: A phandle to the regulator node that supplies 12V to the slot
+ if the platform has one such slot. (Ex:- x16 slot owned by C5 controller
+ in p2972-0000 platform).
+
+Examples:
+=========
+
+Tegra194:
+--------
+
+ pcie@14180000 {
+ compatible = "nvidia,tegra194-pcie", "snps,dw-pcie";
+ power-domains = <&bpmp TEGRA194_POWER_DOMAIN_PCIEX8B>;
+ reg = <0x00 0x14180000 0x0 0x00020000 /* appl registers (128K) */
+ 0x00 0x38000000 0x0 0x00040000 /* configuration space (256K) */
+ 0x00 0x38040000 0x0 0x00040000>; /* iATU_DMA reg space (256K) */
+ reg-names = "appl", "config", "atu_dma";
+
+ #address-cells = <3>;
+ #size-cells = <2>;
+ device_type = "pci";
+ num-lanes = <8>;
+ linux,pci-domain = <0>;
+
+ pinctrl-names = "default";
+ pinctrl-0 = <&pex_rst_c5_out_state>, <&clkreq_c5_bi_dir_state>;
+
+ clocks = <&bpmp TEGRA194_CLK_PEX0_CORE_0>;
+ clock-names = "core";
+
+ resets = <&bpmp TEGRA194_RESET_PEX0_CORE_0_APB>,
+ <&bpmp TEGRA194_RESET_PEX0_CORE_0>;
+ reset-names = "apb", "core";
+
+ interrupts = <GIC_SPI 72 IRQ_TYPE_LEVEL_HIGH>, /* controller interrupt */
+ <GIC_SPI 73 IRQ_TYPE_LEVEL_HIGH>; /* MSI interrupt */
+ interrupt-names = "intr", "msi";
+
+ #interrupt-cells = <1>;
+ interrupt-map-mask = <0 0 0 0>;
+ interrupt-map = <0 0 0 0 &gic GIC_SPI 72 IRQ_TYPE_LEVEL_HIGH>;
+
+ nvidia,bpmp = <&bpmp 0>;
+
+ supports-clkreq;
+ nvidia,aspm-cmrt-us = <60>;
+ nvidia,aspm-pwr-on-t-us = <20>;
+ nvidia,aspm-l0s-entrance-latency-us = <3>;
+
+ bus-range = <0x0 0xff>;
+ ranges = <0x81000000 0x0 0x38100000 0x0 0x38100000 0x0 0x00100000 /* downstream I/O (1MB) */
+ 0x82000000 0x0 0x38200000 0x0 0x38200000 0x0 0x01E00000 /* non-prefetchable memory (30MB) */
+ 0xc2000000 0x18 0x00000000 0x18 0x00000000 0x4 0x00000000>; /* prefetchable memory (16GB) */
+
+ vddio-pex-ctl-supply = <&vdd_1v8ao>;
+ vpcie3v3-supply = <&vdd_3v3_pcie>;
+ vpcie12v-supply = <&vdd_12v_pcie>;
+
+ phys = <&p2u_hsio_2>, <&p2u_hsio_3>, <&p2u_hsio_4>,
+ <&p2u_hsio_5>;
+ phy-names = "p2u-0", "p2u-1", "p2u-2", "p2u-3";
+ };
diff --git a/Documentation/devicetree/bindings/pci/pci-armada8k.txt b/Documentation/devicetree/bindings/pci/pci-armada8k.txt
index 9e3fc15..7a813d0 100644
--- a/Documentation/devicetree/bindings/pci/pci-armada8k.txt
+++ b/Documentation/devicetree/bindings/pci/pci-armada8k.txt
@@ -11,12 +11,20 @@
- reg-names:
- "ctrl" for the control register region
- "config" for the config space region
-- interrupts: Interrupt specifier for the PCIe controler
+- interrupts: Interrupt specifier for the PCIe controller
- clocks: reference to the PCIe controller clocks
- clock-names: mandatory if there is a second clock, in this case the
name must be "core" for the first clock and "reg" for the second
one
+Optional properties:
+- phys: phandle(s) to PHY node(s) following the generic PHY bindings.
+ Either 1, 2 or 4 PHYs might be needed depending on the number of
+ PCIe lanes.
+- phy-names: names of the PHYs corresponding to the number of lanes.
+ Must be "cp0-pcie0-x4-lane0-phy", "cp0-pcie0-x4-lane1-phy" for
+ 2 PHYs.
+
Example:
pcie@f2600000 {
diff --git a/Documentation/devicetree/bindings/pci/pci-msi.txt b/Documentation/devicetree/bindings/pci/pci-msi.txt
index 9b3cc81..b73d839 100644
--- a/Documentation/devicetree/bindings/pci/pci-msi.txt
+++ b/Documentation/devicetree/bindings/pci/pci-msi.txt
@@ -201,7 +201,7 @@
#msi-cells = <1>;
};
- pci: pci@c {
+ pci: pci@f {
reg = <0xf 0x1>;
compatible = "vendor,pcie-root-complex";
device_type = "pci";
diff --git a/Documentation/devicetree/bindings/pci/pci.txt b/Documentation/devicetree/bindings/pci/pci.txt
index 2a5d910..29bcbd8 100644
--- a/Documentation/devicetree/bindings/pci/pci.txt
+++ b/Documentation/devicetree/bindings/pci/pci.txt
@@ -27,6 +27,11 @@
- reset-gpios:
If present this property specifies PERST# GPIO. Host drivers can parse the
GPIO and apply fundamental reset to endpoints.
+- supports-clkreq:
+ If present this property specifies that CLKREQ signal routing exists from
+ root port to downstream device and host bridge drivers can do programming
+ which depends on CLKREQ signal existence. For example, programming root port
+ not to advertise ASPM L1 Sub-States support if there is no CLKREQ signal.
PCI-PCI Bridge properties
-------------------------
diff --git a/Documentation/devicetree/bindings/pci/pcie-al.txt b/Documentation/devicetree/bindings/pci/pcie-al.txt
new file mode 100644
index 0000000..557a508
--- /dev/null
+++ b/Documentation/devicetree/bindings/pci/pcie-al.txt
@@ -0,0 +1,46 @@
+* Amazon Annapurna Labs PCIe host bridge
+
+Amazon's Annapurna Labs PCIe Host Controller is based on the Synopsys DesignWare
+PCI core. It inherits common properties defined in
+Documentation/devicetree/bindings/pci/designware-pcie.txt.
+
+Properties of the host controller node that differ from it are:
+
+- compatible:
+ Usage: required
+ Value type: <stringlist>
+ Definition: Value should contain
+ - "amazon,al-alpine-v2-pcie" for alpine_v2
+ - "amazon,al-alpine-v3-pcie" for alpine_v3
+
+- reg:
+ Usage: required
+ Value type: <prop-encoded-array>
+ Definition: Register ranges as listed in the reg-names property
+
+- reg-names:
+ Usage: required
+ Value type: <stringlist>
+ Definition: Must include the following entries
+ - "config" PCIe ECAM space
+ - "controller" AL proprietary registers
+ - "dbi" Designware PCIe registers
+
+Example:
+
+ pcie-external0: pcie@fb600000 {
+ compatible = "amazon,al-alpine-v3-pcie";
+ reg = <0x0 0xfb600000 0x0 0x00100000
+ 0x0 0xfd800000 0x0 0x00010000
+ 0x0 0xfd810000 0x0 0x00001000>;
+ reg-names = "config", "controller", "dbi";
+ bus-range = <0 255>;
+ device_type = "pci";
+ #address-cells = <3>;
+ #size-cells = <2>;
+ #interrupt-cells = <1>;
+ interrupts = <GIC_SPI 49 IRQ_TYPE_LEVEL_HIGH>;
+ interrupt-map-mask = <0x00 0 0 7>;
+ interrupt-map = <0x0000 0 0 1 &gic GIC_SPI 41 IRQ_TYPE_LEVEL_HIGH>; /* INTa */
+ ranges = <0x02000000 0x0 0xc0010000 0x0 0xc0010000 0x0 0x07ff0000>;
+ };
diff --git a/Documentation/devicetree/bindings/phy/amlogic,meson-g12a-usb2-phy.yaml b/Documentation/devicetree/bindings/phy/amlogic,meson-g12a-usb2-phy.yaml
new file mode 100644
index 0000000..51254b4
--- /dev/null
+++ b/Documentation/devicetree/bindings/phy/amlogic,meson-g12a-usb2-phy.yaml
@@ -0,0 +1,63 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+# Copyright 2019 BayLibre, SAS
+%YAML 1.2
+---
+$id: "http://devicetree.org/schemas/phy/amlogic,meson-g12a-usb2-phy.yaml#"
+$schema: "http://devicetree.org/meta-schemas/core.yaml#"
+
+title: Amlogic G12A USB2 PHY
+
+maintainers:
+ - Neil Armstrong <narmstrong@baylibre.com>
+
+properties:
+ compatible:
+ enum:
+ - amlogic,meson-g12a-usb2-phy
+
+ reg:
+ maxItems: 1
+
+ clocks:
+ maxItems: 1
+
+ clock-names:
+ items:
+ - const: xtal
+
+ resets:
+ maxItems: 1
+
+ reset-names:
+ items:
+ - const: phy
+
+ "#phy-cells":
+ const: 0
+
+ phy-supply:
+ maxItems: 1
+ description:
+ Phandle to a regulator that provides power to the PHY. This
+ regulator will be managed during the PHY power on/off sequence.
+
+required:
+ - compatible
+ - reg
+ - clocks
+ - clock-names
+ - resets
+ - reset-names
+ - "#phy-cells"
+
+examples:
+ - |
+ phy@36000 {
+ compatible = "amlogic,meson-g12a-usb2-phy";
+ reg = <0x36000 0x2000>;
+ clocks = <&xtal>;
+ clock-names = "xtal";
+ resets = <&phy_reset>;
+ reset-names = "phy";
+ #phy-cells = <0>;
+ };
diff --git a/Documentation/devicetree/bindings/phy/amlogic,meson-g12a-usb3-pcie-phy.yaml b/Documentation/devicetree/bindings/phy/amlogic,meson-g12a-usb3-pcie-phy.yaml
new file mode 100644
index 0000000..346f9c3
--- /dev/null
+++ b/Documentation/devicetree/bindings/phy/amlogic,meson-g12a-usb3-pcie-phy.yaml
@@ -0,0 +1,57 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+# Copyright 2019 BayLibre, SAS
+%YAML 1.2
+---
+$id: "http://devicetree.org/schemas/phy/amlogic,meson-g12a-usb3-pcie-phy.yaml#"
+$schema: "http://devicetree.org/meta-schemas/core.yaml#"
+
+title: Amlogic G12A USB3 + PCIE Combo PHY
+
+maintainers:
+ - Neil Armstrong <narmstrong@baylibre.com>
+
+properties:
+ compatible:
+ enum:
+ - amlogic,meson-g12a-usb3-pcie-phy
+
+ reg:
+ maxItems: 1
+
+ clocks:
+ maxItems: 1
+
+ clock-names:
+ items:
+ - const: ref_clk
+
+ resets:
+ maxItems: 1
+
+ reset-names:
+ items:
+ - const: phy
+
+ "#phy-cells":
+ const: 1
+
+required:
+ - compatible
+ - reg
+ - clocks
+ - clock-names
+ - resets
+ - reset-names
+ - "#phy-cells"
+
+examples:
+ - |
+ phy@46000 {
+ compatible = "amlogic,meson-g12a-usb3-pcie-phy";
+ reg = <0x46000 0x2000>;
+ clocks = <&ref_clk>;
+ clock-names = "ref_clk";
+ resets = <&phy_reset>;
+ reset-names = "phy";
+ #phy-cells = <1>;
+ };
diff --git a/Documentation/devicetree/bindings/phy/lantiq,vrx200-pcie-phy.yaml b/Documentation/devicetree/bindings/phy/lantiq,vrx200-pcie-phy.yaml
new file mode 100644
index 0000000..8a56a85
--- /dev/null
+++ b/Documentation/devicetree/bindings/phy/lantiq,vrx200-pcie-phy.yaml
@@ -0,0 +1,95 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/phy/lantiq,vrx200-pcie-phy.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Lantiq VRX200 and ARX300 PCIe PHY Device Tree Bindings
+
+maintainers:
+ - Martin Blumenstingl <martin.blumenstingl@googlemail.com>
+
+properties:
+ "#phy-cells":
+ const: 1
+ description: selects the PHY mode as defined in <dt-bindings/phy/phy-lantiq-vrx200-pcie.h>
+
+ compatible:
+ enum:
+ - lantiq,vrx200-pcie-phy
+ - lantiq,arx300-pcie-phy
+
+ reg:
+ maxItems: 1
+
+ clocks:
+ items:
+ - description: PHY module clock
+ - description: PDI register clock
+
+ clock-names:
+ items:
+ - const: phy
+ - const: pdi
+
+ resets:
+ items:
+ - description: exclusive PHY reset line
+ - description: shared reset line between the PCIe PHY and PCIe controller
+
+ resets-names:
+ items:
+ - const: phy
+ - const: pcie
+
+ lantiq,rcu:
+ $ref: /schemas/types.yaml#/definitions/phandle
+ description: phandle to the RCU syscon
+
+ lantiq,rcu-endian-offset:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description: the offset of the endian registers for this PHY instance in the RCU syscon
+
+ lantiq,rcu-big-endian-mask:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description: the mask to set the PDI (PHY) registers for this PHY instance to big endian
+
+ big-endian:
+ description: Configures the PDI (PHY) registers in big-endian mode
+ type: boolean
+
+ little-endian:
+ description: Configures the PDI (PHY) registers in big-endian mode
+ type: boolean
+
+required:
+ - "#phy-cells"
+ - compatible
+ - reg
+ - clocks
+ - clock-names
+ - resets
+ - reset-names
+ - lantiq,rcu
+ - lantiq,rcu-endian-offset
+ - lantiq,rcu-big-endian-mask
+
+additionalProperties: false
+
+examples:
+ - |
+ pcie0_phy: phy@106800 {
+ compatible = "lantiq,vrx200-pcie-phy";
+ reg = <0x106800 0x100>;
+ lantiq,rcu = <&rcu0>;
+ lantiq,rcu-endian-offset = <0x4c>;
+ lantiq,rcu-big-endian-mask = <0x80>; /* bit 7 */
+ big-endian;
+ clocks = <&pmu 32>, <&pmu 36>;
+ clock-names = "phy", "pdi";
+ resets = <&reset0 12 24>, <&reset0 22 22>;
+ reset-names = "phy", "pcie";
+ #phy-cells = <1>;
+ };
+
+...
diff --git a/Documentation/devicetree/bindings/phy/meson-g12a-usb2-phy.txt b/Documentation/devicetree/bindings/phy/meson-g12a-usb2-phy.txt
deleted file mode 100644
index a6ebc3d..0000000
--- a/Documentation/devicetree/bindings/phy/meson-g12a-usb2-phy.txt
+++ /dev/null
@@ -1,22 +0,0 @@
-* Amlogic G12A USB2 PHY binding
-
-Required properties:
-- compatible: Should be "amlogic,meson-g12a-usb2-phy"
-- reg: The base address and length of the registers
-- #phys-cells: must be 0 (see phy-bindings.txt in this directory)
-- clocks: a phandle to the clock of this PHY
-- clock-names: must be "xtal"
-- resets: a phandle to the reset line of this PHY
-- reset-names: must be "phy"
-- phy-supply: see phy-bindings.txt in this directory
-
-Example:
- usb2_phy0: phy@36000 {
- compatible = "amlogic,g12a-usb2-phy";
- reg = <0x0 0x36000 0x0 0x2000>;
- clocks = <&xtal>;
- clock-names = "xtal";
- resets = <&reset RESET_USB_PHY21>;
- reset-names = "phy";
- #phy-cells = <0>;
- };
diff --git a/Documentation/devicetree/bindings/phy/meson-g12a-usb3-pcie-phy.txt b/Documentation/devicetree/bindings/phy/meson-g12a-usb3-pcie-phy.txt
deleted file mode 100644
index 7cfc17e..0000000
--- a/Documentation/devicetree/bindings/phy/meson-g12a-usb3-pcie-phy.txt
+++ /dev/null
@@ -1,22 +0,0 @@
-* Amlogic G12A USB3 + PCIE Combo PHY binding
-
-Required properties:
-- compatible: Should be "amlogic,meson-g12a-usb3-pcie-phy"
-- #phys-cells: must be 1. The cell number is used to select the phy mode
- as defined in <dt-bindings/phy/phy.h> between PHY_TYPE_USB3 and PHY_TYPE_PCIE
-- reg: The base address and length of the registers
-- clocks: a phandle to the 100MHz reference clock of this PHY
-- clock-names: must be "ref_clk"
-- resets: phandle to the reset lines for the PHY control
-- reset-names: must be "phy"
-
-Example:
- usb3_pcie_phy: phy@46000 {
- compatible = "amlogic,g12a-usb3-pcie-phy";
- reg = <0x0 0x46000 0x0 0x2000>;
- clocks = <&clkc CLKID_PCIE_PLL>;
- clock-names = "ref_clk";
- resets = <&reset RESET_PCIE_PHY>;
- reset-names = "phy";
- #phy-cells = <1>;
- };
diff --git a/Documentation/devicetree/bindings/phy/phy-mvebu-comphy.txt b/Documentation/devicetree/bindings/phy/phy-mvebu-comphy.txt
index cf2cd86..8c60e69 100644
--- a/Documentation/devicetree/bindings/phy/phy-mvebu-comphy.txt
+++ b/Documentation/devicetree/bindings/phy/phy-mvebu-comphy.txt
@@ -25,6 +25,13 @@
- #address-cells: should be 1.
- #size-cells: should be 0.
+Optional properlties:
+
+- clocks: pointers to the reference clocks for this device (CP110 only),
+ consequently: MG clock, MG Core clock, AXI clock.
+- clock-names: names of used clocks for CP110 only, must be :
+ "mg_clk", "mg_core_clk" and "axi_clk".
+
A sub-node is required for each comphy lane provided by the comphy.
Required properties (child nodes):
@@ -39,6 +46,9 @@
compatible = "marvell,comphy-cp110";
reg = <0x120000 0x6000>;
marvell,system-controller = <&cpm_syscon0>;
+ clocks = <&CP110_LABEL(clk) 1 5>, <&CP110_LABEL(clk) 1 6>,
+ <&CP110_LABEL(clk) 1 18>;
+ clock-names = "mg_clk", "mg_core_clk", "axi_clk";
#address-cells = <1>;
#size-cells = <0>;
diff --git a/Documentation/devicetree/bindings/phy/phy-tegra194-p2u.txt b/Documentation/devicetree/bindings/phy/phy-tegra194-p2u.txt
new file mode 100644
index 0000000..d23ff90
--- /dev/null
+++ b/Documentation/devicetree/bindings/phy/phy-tegra194-p2u.txt
@@ -0,0 +1,28 @@
+NVIDIA Tegra194 P2U binding
+
+Tegra194 has two PHY bricks namely HSIO (High Speed IO) and NVHS (NVIDIA High
+Speed) each interfacing with 12 and 8 P2U instances respectively.
+A P2U instance is a glue logic between Synopsys DesignWare Core PCIe IP's PIPE
+interface and PHY of HSIO/NVHS bricks. Each P2U instance represents one PCIe
+lane.
+
+Required properties:
+- compatible: For Tegra19x, must contain "nvidia,tegra194-p2u".
+- reg: Should be the physical address space and length of respective each P2U
+ instance.
+- reg-names: Must include the entry "ctl".
+
+Required properties for PHY port node:
+- #phy-cells: Defined by generic PHY bindings. Must be 0.
+
+Refer to phy/phy-bindings.txt for the generic PHY binding properties.
+
+Example:
+
+p2u_hsio_0: phy@3e10000 {
+ compatible = "nvidia,tegra194-p2u";
+ reg = <0x03e10000 0x10000>;
+ reg-names = "ctl";
+
+ #phy-cells = <0>;
+};
diff --git a/Documentation/devicetree/bindings/pinctrl/aspeed,ast2400-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/aspeed,ast2400-pinctrl.yaml
index 125599a..39ad865 100644
--- a/Documentation/devicetree/bindings/pinctrl/aspeed,ast2400-pinctrl.yaml
+++ b/Documentation/devicetree/bindings/pinctrl/aspeed,ast2400-pinctrl.yaml
@@ -15,16 +15,13 @@
- compatible: Should be one of the following:
"aspeed,ast2400-scu", "syscon", "simple-mfd"
- "aspeed,g4-scu", "syscon", "simple-mfd"
Refer to the the bindings described in
Documentation/devicetree/bindings/mfd/syscon.txt
properties:
compatible:
- enum:
- - aspeed,ast2400-pinctrl
- - aspeed,g4-pinctrl
+ const: aspeed,ast2400-pinctrl
patternProperties:
'^.*$':
@@ -35,28 +32,24 @@
"^function|groups$":
allOf:
- $ref: "/schemas/types.yaml#/definitions/string"
- - enum: [ "ACPI", "ADC0", "ADC1", "ADC10", "ADC11", "ADC12", "ADC13",
- "ADC14", "ADC15", "ADC2", "ADC3", "ADC4", "ADC5", "ADC6", "ADC7",
- "ADC8", "ADC9", "BMCINT", "DDCCLK", "DDCDAT", "EXTRST", "FLACK",
- "FLBUSY", "FLWP", "GPID", "GPID0", "GPID2", "GPID4", "GPID6",
- "GPIE0", "GPIE2", "GPIE4", "GPIE6", "I2C10", "I2C11", "I2C12",
- "I2C13", "I2C14", "I2C3", "I2C4", "I2C5", "I2C6", "I2C7", "I2C8",
- "I2C9", "LPCPD", "LPCPME", "LPCRST", "LPCSMI", "MAC1LINK",
- "MAC2LINK", "MDIO1", "MDIO2", "NCTS1", "NCTS2", "NCTS3", "NCTS4",
- "NDCD1", "NDCD2", "NDCD3", "NDCD4", "NDSR1", "NDSR2", "NDSR3",
- "NDSR4", "NDTR1", "NDTR2", "NDTR3", "NDTR4", "NDTS4", "NRI1",
- "NRI2", "NRI3", "NRI4", "NRTS1", "NRTS2", "NRTS3", "OSCCLK",
- "PWM0", "PWM1", "PWM2", "PWM3", "PWM4", "PWM5", "PWM6", "PWM7",
- "RGMII1", "RGMII2", "RMII1", "RMII2", "ROM16", "ROM8", "ROMCS1",
- "ROMCS2", "ROMCS3", "ROMCS4", "RXD1", "RXD2", "RXD3", "RXD4",
- "SALT1", "SALT2", "SALT3", "SALT4", "SD1", "SD2", "SGPMCK",
- "SGPMI", "SGPMLD", "SGPMO", "SGPSCK", "SGPSI0", "SGPSI1", "SGPSLD",
- "SIOONCTRL", "SIOPBI", "SIOPBO", "SIOPWREQ", "SIOPWRGD", "SIOS3",
- "SIOS5", "SIOSCI", "SPI1", "SPI1DEBUG", "SPI1PASSTHRU", "SPICS1",
- "TIMER3", "TIMER4", "TIMER5", "TIMER6", "TIMER7", "TIMER8", "TXD1",
- "TXD2", "TXD3", "TXD4", "UART6", "USB11D1", "USB11H2", "USB2D1",
- "USB2H1", "USBCKI", "VGABIOS_ROM", "VGAHS", "VGAVS", "VPI18",
- "VPI24", "VPI30", "VPO12", "VPO24", "WDTRST1", "WDTRST2" ]
+ - enum: [ ACPI, ADC0, ADC1, ADC10, ADC11, ADC12, ADC13, ADC14,
+ ADC15, ADC2, ADC3, ADC4, ADC5, ADC6, ADC7, ADC8, ADC9, BMCINT,
+ DDCCLK, DDCDAT, EXTRST, FLACK, FLBUSY, FLWP, GPID, GPID0, GPID2,
+ GPID4, GPID6, GPIE0, GPIE2, GPIE4, GPIE6, I2C10, I2C11, I2C12,
+ I2C13, I2C14, I2C3, I2C4, I2C5, I2C6, I2C7, I2C8, I2C9, LPCPD,
+ LPCPME, LPCRST, LPCSMI, MAC1LINK, MAC2LINK, MDIO1, MDIO2, NCTS1,
+ NCTS2, NCTS3, NCTS4, NDCD1, NDCD2, NDCD3, NDCD4, NDSR1, NDSR2,
+ NDSR3, NDSR4, NDTR1, NDTR2, NDTR3, NDTR4, NDTS4, NRI1, NRI2,
+ NRI3, NRI4, NRTS1, NRTS2, NRTS3, OSCCLK, PWM0, PWM1, PWM2, PWM3,
+ PWM4, PWM5, PWM6, PWM7, RGMII1, RGMII2, RMII1, RMII2, ROM16,
+ ROM8, ROMCS1, ROMCS2, ROMCS3, ROMCS4, RXD1, RXD2, RXD3, RXD4,
+ SALT1, SALT2, SALT3, SALT4, SD1, SD2, SGPMCK, SGPMI, SGPMLD,
+ SGPMO, SGPSCK, SGPSI0, SGPSI1, SGPSLD, SIOONCTRL, SIOPBI, SIOPBO,
+ SIOPWREQ, SIOPWRGD, SIOS3, SIOS5, SIOSCI, SPI1, SPI1DEBUG,
+ SPI1PASSTHRU, SPICS1, TIMER3, TIMER4, TIMER5, TIMER6, TIMER7,
+ TIMER8, TXD1, TXD2, TXD3, TXD4, UART6, USB11D1, USB11H2, USB2D1,
+ USB2H1, USBCKI, VGABIOS_ROM, VGAHS, VGAVS, VPI18, VPI24, VPI30,
+ VPO12, VPO24, WDTRST1, WDTRST2 ]
required:
- compatible
diff --git a/Documentation/devicetree/bindings/pinctrl/aspeed,ast2500-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/aspeed,ast2500-pinctrl.yaml
index 3e6d853..3c6405b 100644
--- a/Documentation/devicetree/bindings/pinctrl/aspeed,ast2500-pinctrl.yaml
+++ b/Documentation/devicetree/bindings/pinctrl/aspeed,ast2500-pinctrl.yaml
@@ -22,9 +22,7 @@
properties:
compatible:
- enum:
- - aspeed,ast2500-pinctrl
- - aspeed,g5-pinctrl
+ const: aspeed,ast2500-pinctrl
aspeed,external-nodes:
minItems: 2
maxItems: 2
@@ -44,31 +42,26 @@
"^function|groups$":
allOf:
- $ref: "/schemas/types.yaml#/definitions/string"
- - enum: [ "ACPI", "ADC0", "ADC1", "ADC10", "ADC11", "ADC12", "ADC13",
- "ADC14", "ADC15", "ADC2", "ADC3", "ADC4", "ADC5", "ADC6", "ADC7",
- "ADC8", "ADC9", "BMCINT", "DDCCLK", "DDCDAT", "ESPI", "FWSPICS1",
- "FWSPICS2", "GPID0", "GPID2", "GPID4", "GPID6", "GPIE0", "GPIE2",
- "GPIE4", "GPIE6", "I2C10", "I2C11", "I2C12", "I2C13", "I2C14",
- "I2C3", "I2C4", "I2C5", "I2C6", "I2C7", "I2C8", "I2C9", "LAD0",
- "LAD1", "LAD2", "LAD3", "LCLK", "LFRAME", "LPCHC", "LPCPD",
- "LPCPLUS", "LPCPME", "LPCRST", "LPCSMI", "LSIRQ", "MAC1LINK",
- "MAC2LINK", "MDIO1", "MDIO2", "NCTS1", "NCTS2", "NCTS3", "NCTS4",
- "NDCD1", "NDCD2", "NDCD3", "NDCD4", "NDSR1", "NDSR2", "NDSR3",
- "NDSR4", "NDTR1", "NDTR2", "NDTR3", "NDTR4", "NRI1", "NRI2",
- "NRI3", "NRI4", "NRTS1", "NRTS2", "NRTS3", "NRTS4", "OSCCLK",
- "PEWAKE", "PNOR", "PWM0", "PWM1", "PWM2", "PWM3", "PWM4", "PWM5",
- "PWM6", "PWM7", "RGMII1", "RGMII2", "RMII1", "RMII2", "RXD1",
- "RXD2", "RXD3", "RXD4", "SALT1", "SALT10", "SALT11", "SALT12",
- "SALT13", "SALT14", "SALT2", "SALT3", "SALT4", "SALT5", "SALT6",
- "SALT7", "SALT8", "SALT9", "SCL1", "SCL2", "SD1", "SD2", "SDA1",
- "SDA2", "SGPS1", "SGPS2", "SIOONCTRL", "SIOPBI", "SIOPBO",
- "SIOPWREQ", "SIOPWRGD", "SIOS3", "SIOS5", "SIOSCI", "SPI1",
- "SPI1CS1", "SPI1DEBUG", "SPI1PASSTHRU", "SPI2CK", "SPI2CS0",
- "SPI2CS1", "SPI2MISO", "SPI2MOSI", "TIMER3", "TIMER4", "TIMER5",
- "TIMER6", "TIMER7", "TIMER8", "TXD1", "TXD2", "TXD3", "TXD4",
- "UART6", "USB11BHID", "USB2AD", "USB2AH", "USB2BD", "USB2BH",
- "USBCKI", "VGABIOSROM", "VGAHS", "VGAVS", "VPI24", "VPO",
- "WDTRST1", "WDTRST2", ]
+ - enum: [ ACPI, ADC0, ADC1, ADC10, ADC11, ADC12, ADC13, ADC14,
+ ADC15, ADC2, ADC3, ADC4, ADC5, ADC6, ADC7, ADC8, ADC9, BMCINT,
+ DDCCLK, DDCDAT, ESPI, FWSPICS1, FWSPICS2, GPID0, GPID2, GPID4,
+ GPID6, GPIE0, GPIE2, GPIE4, GPIE6, I2C10, I2C11, I2C12, I2C13,
+ I2C14, I2C3, I2C4, I2C5, I2C6, I2C7, I2C8, I2C9, LAD0, LAD1,
+ LAD2, LAD3, LCLK, LFRAME, LPCHC, LPCPD, LPCPLUS, LPCPME, LPCRST,
+ LPCSMI, LSIRQ, MAC1LINK, MAC2LINK, MDIO1, MDIO2, NCTS1, NCTS2,
+ NCTS3, NCTS4, NDCD1, NDCD2, NDCD3, NDCD4, NDSR1, NDSR2, NDSR3,
+ NDSR4, NDTR1, NDTR2, NDTR3, NDTR4, NRI1, NRI2, NRI3, NRI4, NRTS1,
+ NRTS2, NRTS3, NRTS4, OSCCLK, PEWAKE, PNOR, PWM0, PWM1, PWM2,
+ PWM3, PWM4, PWM5, PWM6, PWM7, RGMII1, RGMII2, RMII1, RMII2, RXD1,
+ RXD2, RXD3, RXD4, SALT1, SALT10, SALT11, SALT12, SALT13, SALT14,
+ SALT2, SALT3, SALT4, SALT5, SALT6, SALT7, SALT8, SALT9, SCL1,
+ SCL2, SD1, SD2, SDA1, SDA2, SGPS1, SGPS2, SIOONCTRL, SIOPBI,
+ SIOPBO, SIOPWREQ, SIOPWRGD, SIOS3, SIOS5, SIOSCI, SPI1, SPI1CS1,
+ SPI1DEBUG, SPI1PASSTHRU, SPI2CK, SPI2CS0, SPI2CS1, SPI2MISO,
+ SPI2MOSI, TIMER3, TIMER4, TIMER5, TIMER6, TIMER7, TIMER8, TXD1,
+ TXD2, TXD3, TXD4, UART6, USB11BHID, USB2AD, USB2AH, USB2BD,
+ USB2BH, USBCKI, VGABIOSROM, VGAHS, VGAVS, VPI24, VPO, WDTRST1,
+ WDTRST2, ]
required:
- compatible
diff --git a/Documentation/devicetree/bindings/pinctrl/aspeed,ast2600-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/aspeed,ast2600-pinctrl.yaml
new file mode 100644
index 0000000..f83d888
--- /dev/null
+++ b/Documentation/devicetree/bindings/pinctrl/aspeed,ast2600-pinctrl.yaml
@@ -0,0 +1,115 @@
+# SPDX-License-Identifier: GPL-2.0+
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/pinctrl/aspeed,ast2600-pinctrl.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: ASPEED AST2600 Pin Controller
+
+maintainers:
+ - Andrew Jeffery <andrew@aj.id.au>
+
+description: |+
+ The pin controller node should be the child of a syscon node with the
+ required property:
+
+ - compatible: Should be one of the following:
+ "aspeed,ast2600-scu", "syscon", "simple-mfd"
+
+ Refer to the the bindings described in
+ Documentation/devicetree/bindings/mfd/syscon.txt
+
+properties:
+ compatible:
+ const: aspeed,ast2600-pinctrl
+
+patternProperties:
+ '^.*$':
+ if:
+ type: object
+ then:
+ properties:
+ function:
+ allOf:
+ - $ref: "/schemas/types.yaml#/definitions/string"
+ - enum: [ ADC0, ADC1, ADC10, ADC11, ADC12, ADC13, ADC14, ADC15,
+ ADC2, ADC3, ADC4, ADC5, ADC6, ADC7, ADC8, ADC9, BMCINT, ESPI,
+ ESPIALT, FSI1, FSI2, FWSPIABR, FWSPID, FWSPIWP, GPIT0, GPIT1,
+ GPIT2, GPIT3, GPIT4, GPIT5, GPIT6, GPIT7, GPIU0, GPIU1, GPIU2,
+ GPIU3, GPIU4, GPIU5, GPIU6, GPIU7, I2C1, I2C10, I2C11, I2C12,
+ I2C13, I2C14, I2C15, I2C16, I2C2, I2C3, I2C4, I2C5, I2C6, I2C7,
+ I2C8, I2C9, I3C3, I3C4, I3C5, I3C6, JTAGM, LHPD, LHSIRQ, LPC,
+ LPCHC, LPCPD, LPCPME, LPCSMI, LSIRQ, MACLINK1, MACLINK2,
+ MACLINK3, MACLINK4, MDIO1, MDIO2, MDIO3, MDIO4, NCTS1, NCTS2,
+ NCTS3, NCTS4, NDCD1, NDCD2, NDCD3, NDCD4, NDSR1, NDSR2, NDSR3,
+ NDSR4, NDTR1, NDTR2, NDTR3, NDTR4, NRI1, NRI2, NRI3, NRI4, NRTS1,
+ NRTS2, NRTS3, NRTS4, OSCCLK, PEWAKE, PWM0, PWM1, PWM10, PWM11,
+ PWM12, PWM13, PWM14, PWM15, PWM2, PWM3, PWM4, PWM5, PWM6, PWM7,
+ PWM8, PWM9, RGMII1, RGMII2, RGMII3, RGMII4, RMII1, RMII2, RMII3,
+ RMII4, RXD1, RXD2, RXD3, RXD4, SALT1, SALT10, SALT11, SALT12,
+ SALT13, SALT14, SALT15, SALT16, SALT2, SALT3, SALT4, SALT5,
+ SALT6, SALT7, SALT8, SALT9, SD1, SD2, SD3, SD3DAT4, SD3DAT5,
+ SD3DAT6, SD3DAT7, SGPM1, SGPS1, SIOONCTRL, SIOPBI, SIOPBO,
+ SIOPWREQ, SIOPWRGD, SIOS3, SIOS5, SIOSCI, SPI1, SPI1ABR, SPI1CS1,
+ SPI1WP, SPI2, SPI2CS1, SPI2CS2, TACH0, TACH1, TACH10, TACH11,
+ TACH12, TACH13, TACH14, TACH15, TACH2, TACH3, TACH4, TACH5,
+ TACH6, TACH7, TACH8, TACH9, THRU0, THRU1, THRU2, THRU3, TXD1,
+ TXD2, TXD3, TXD4, UART10, UART11, UART12, UART13, UART6, UART7,
+ UART8, UART9, VB, VGAHS, VGAVS, WDTRST1, WDTRST2, WDTRST3,
+ WDTRST4, ]
+ groups:
+ allOf:
+ - $ref: "/schemas/types.yaml#/definitions/string"
+ - enum: [ ADC0, ADC1, ADC10, ADC11, ADC12, ADC13, ADC14, ADC15,
+ ADC2, ADC3, ADC4, ADC5, ADC6, ADC7, ADC8, ADC9, BMCINT, ESPI,
+ ESPIALT, FSI1, FSI2, FWSPIABR, FWSPID, FWQSPID, FWSPIWP, GPIT0,
+ GPIT1, GPIT2, GPIT3, GPIT4, GPIT5, GPIT6, GPIT7, GPIU0, GPIU1,
+ GPIU2, GPIU3, GPIU4, GPIU5, GPIU6, GPIU7, HVI3C3, HVI3C4, I2C1,
+ I2C10, I2C11, I2C12, I2C13, I2C14, I2C15, I2C16, I2C2, I2C3,
+ I2C4, I2C5, I2C6, I2C7, I2C8, I2C9, I3C3, I3C4, I3C5, I3C6,
+ JTAGM, LHPD, LHSIRQ, LPC, LPCHC, LPCPD, LPCPME, LPCSMI, LSIRQ,
+ MACLINK1, MACLINK2, MACLINK3, MACLINK4, MDIO1, MDIO2, MDIO3,
+ MDIO4, NCTS1, NCTS2, NCTS3, NCTS4, NDCD1, NDCD2, NDCD3, NDCD4,
+ NDSR1, NDSR2, NDSR3, NDSR4, NDTR1, NDTR2, NDTR3, NDTR4, NRI1,
+ NRI2, NRI3, NRI4, NRTS1, NRTS2, NRTS3, NRTS4, OSCCLK, PEWAKE,
+ PWM0, PWM1, PWM10G0, PWM10G1, PWM11G0, PWM11G1, PWM12G0, PWM12G1,
+ PWM13G0, PWM13G1, PWM14G0, PWM14G1, PWM15G0, PWM15G1, PWM2, PWM3,
+ PWM4, PWM5, PWM6, PWM7, PWM8G0, PWM8G1, PWM9G0, PWM9G1, QSPI1,
+ QSPI2, RGMII1, RGMII2, RGMII3, RGMII4, RMII1, RMII2, RMII3,
+ RMII4, RXD1, RXD2, RXD3, RXD4, SALT1, SALT10G0, SALT10G1,
+ SALT11G0, SALT11G1, SALT12G0, SALT12G1, SALT13G0, SALT13G1,
+ SALT14G0, SALT14G1, SALT15G0, SALT15G1, SALT16G0, SALT16G1,
+ SALT2, SALT3, SALT4, SALT5, SALT6, SALT7, SALT8, SALT9G0,
+ SALT9G1, SD1, SD2, SD3, SD3DAT4, SD3DAT5, SD3DAT6, SD3DAT7,
+ SGPM1, SGPS1, SIOONCTRL, SIOPBI, SIOPBO, SIOPWREQ, SIOPWRGD,
+ SIOS3, SIOS5, SIOSCI, SPI1, SPI1ABR, SPI1CS1, SPI1WP, SPI2,
+ SPI2CS1, SPI2CS2, TACH0, TACH1, TACH10, TACH11, TACH12, TACH13,
+ TACH14, TACH15, TACH2, TACH3, TACH4, TACH5, TACH6, TACH7, TACH8,
+ TACH9, THRU0, THRU1, THRU2, THRU3, TXD1, TXD2, TXD3, TXD4,
+ UART10, UART11, UART12G0, UART12G1, UART13G0, UART13G1, UART6,
+ UART7, UART8, UART9, VB, VGAHS, VGAVS, WDTRST1, WDTRST2, WDTRST3,
+ WDTRST4, ]
+
+required:
+ - compatible
+
+examples:
+ - |
+ syscon: scu@1e6e2000 {
+ compatible = "aspeed,ast2600-scu", "syscon", "simple-mfd";
+ reg = <0x1e6e2000 0xf6c>;
+
+ pinctrl: pinctrl {
+ compatible = "aspeed,g6-pinctrl";
+
+ pinctrl_pwm10g1_default: pwm10g1_default {
+ function = "PWM10";
+ groups = "PWM10G1";
+ };
+
+ pinctrl_gpioh0_unbiased_default: gpioh0 {
+ pins = "A18";
+ bias-disable;
+ };
+ };
+ };
diff --git a/Documentation/devicetree/bindings/pinctrl/brcm,bcm2835-gpio.txt b/Documentation/devicetree/bindings/pinctrl/brcm,bcm2835-gpio.txt
index ac6d614..3cab733 100644
--- a/Documentation/devicetree/bindings/pinctrl/brcm,bcm2835-gpio.txt
+++ b/Documentation/devicetree/bindings/pinctrl/brcm,bcm2835-gpio.txt
@@ -8,6 +8,7 @@
- compatible: should be one of:
"brcm,bcm2835-gpio" - BCM2835 compatible pinctrl
"brcm,bcm7211-gpio" - BCM7211 compatible pinctrl
+ "brcm,bcm2711-gpio" - BCM2711 compatible pinctrl
- reg: Should contain the physical address of the GPIO module's registers.
- gpio-controller: Marks the device node as a GPIO controller.
- #gpio-cells : Should be two. The first cell is the pin number and the
diff --git a/Documentation/devicetree/bindings/pinctrl/ingenic,pinctrl.txt b/Documentation/devicetree/bindings/pinctrl/ingenic,pinctrl.txt
index af20b0e..0014d98 100644
--- a/Documentation/devicetree/bindings/pinctrl/ingenic,pinctrl.txt
+++ b/Documentation/devicetree/bindings/pinctrl/ingenic,pinctrl.txt
@@ -1,18 +1,18 @@
-Ingenic jz47xx pin controller
+Ingenic XBurst pin controller
Please refer to pinctrl-bindings.txt in this directory for details of the
common pinctrl bindings used by client devices, including the meaning of the
phrase "pin configuration node".
-For the jz47xx SoCs, pin control is tightly bound with GPIO ports. All pins may
+For the XBurst SoCs, pin control is tightly bound with GPIO ports. All pins may
be used as GPIOs, multiplexed device functions are configured within the
GPIO port configuration registers and it is typical to refer to pins using the
naming scheme "PxN" where x is a character identifying the GPIO port with
which the pin is associated and N is an integer from 0 to 31 identifying the
pin within that GPIO port. For example PA0 is the first pin in GPIO port A, and
-PB31 is the last pin in GPIO port B. The jz4740 contains 4 GPIO ports, PA to
-PD, for a total of 128 pins. The jz4780 contains 6 GPIO ports, PA to PF, for a
-total of 192 pins.
+PB31 is the last pin in GPIO port B. The jz4740 and the x1000 contains 4 GPIO
+ports, PA to PD, for a total of 128 pins. The jz4760, the jz4770 and the jz4780
+contains 6 GPIO ports, PA to PF, for a total of 192 pins.
Required properties:
@@ -21,8 +21,13 @@
- compatible: One of:
- "ingenic,jz4740-pinctrl"
- "ingenic,jz4725b-pinctrl"
+ - "ingenic,jz4760-pinctrl"
+ - "ingenic,jz4760b-pinctrl"
- "ingenic,jz4770-pinctrl"
- "ingenic,jz4780-pinctrl"
+ - "ingenic,x1000-pinctrl"
+ - "ingenic,x1000e-pinctrl"
+ - "ingenic,x1500-pinctrl"
- reg: Address range of the pinctrl registers.
@@ -31,8 +36,10 @@
- compatible: Must contain one of:
- "ingenic,jz4740-gpio"
+ - "ingenic,jz4760-gpio"
- "ingenic,jz4770-gpio"
- "ingenic,jz4780-gpio"
+ - "ingenic,x1000-gpio"
- reg: The GPIO bank number.
- interrupt-controller: Marks the device node as an interrupt controller.
- interrupts: Interrupt specifier for the controllers interrupt.
diff --git a/Documentation/devicetree/bindings/pinctrl/pinctrl-mcp23s08.txt b/Documentation/devicetree/bindings/pinctrl/pinctrl-mcp23s08.txt
index 625a22e..8b94aa8 100644
--- a/Documentation/devicetree/bindings/pinctrl/pinctrl-mcp23s08.txt
+++ b/Documentation/devicetree/bindings/pinctrl/pinctrl-mcp23s08.txt
@@ -82,7 +82,7 @@
compatible = "microchip,mcp23s17";
gpio-controller;
#gpio-cells = <2>;
- spi-present-mask = <0x01>;
+ microchip,spi-present-mask = <0x01>;
reg = <0>;
spi-max-frequency = <1000000>;
};
diff --git a/Documentation/devicetree/bindings/pinctrl/qcom,msm8998-pinctrl.txt b/Documentation/devicetree/bindings/pinctrl/qcom,msm8998-pinctrl.txt
index cdec1ee..c4de930 100644
--- a/Documentation/devicetree/bindings/pinctrl/qcom,msm8998-pinctrl.txt
+++ b/Documentation/devicetree/bindings/pinctrl/qcom,msm8998-pinctrl.txt
@@ -132,9 +132,8 @@
qlink_request, qua_mi2s, sd_card, sd_write, sdc40, sdc41,
sdc42, sdc43, sdc4_clk, sdc4_cmd, sec_mi2s, sp_cmu,
spkr_i2s, ssbi1, ssc_irq, ter_mi2s, tgu_ch0, tgu_ch1,
- tsense_pwm1, tsense_pwm2, tsif1_clk, tsif1_data, tsif1_en,
- tsif1_error, tsif1_sync, tsif2_clk, tsif2_data, tsif2_en,
- tsif2_error, tsif2_sync, uim1_clk, uim1_data, uim1_present,
+ tsense_pwm1, tsense_pwm2, tsif0, tsif1,
+ uim1_clk, uim1_data, uim1_present,
uim1_reset, uim2_clk, uim2_data, uim2_present, uim2_reset,
uim_batt, usb_phy, vfr_1, vsense_clkout, vsense_data0,
vsense_data1, vsense_mode, wlan1_adc0, wlan1_adc1,
diff --git a/Documentation/devicetree/bindings/pinctrl/qcom,pmic-gpio.txt b/Documentation/devicetree/bindings/pinctrl/qcom,pmic-gpio.txt
index 7f64a7e..c32bf32 100644
--- a/Documentation/devicetree/bindings/pinctrl/qcom,pmic-gpio.txt
+++ b/Documentation/devicetree/bindings/pinctrl/qcom,pmic-gpio.txt
@@ -21,6 +21,8 @@
"qcom,pmi8994-gpio"
"qcom,pmi8998-gpio"
"qcom,pms405-gpio"
+ "qcom,pm8150-gpio"
+ "qcom,pm8150b-gpio"
And must contain either "qcom,spmi-gpio" or "qcom,ssbi-gpio"
if the device is on an spmi bus or an ssbi bus respectively
@@ -94,6 +96,10 @@
gpio1-gpio22 for pma8084
gpio1-gpio10 for pmi8994
gpio1-gpio12 for pms405 (holes on gpio1, gpio9 and gpio10)
+ gpio1-gpio10 for pm8150 (holes on gpio2, gpio5, gpio7
+ and gpio8)
+ gpio1-gpio12 for pm8150b (holes on gpio3, gpio4, gpio7)
+ gpio1-gpio12 for pm8150l (hole on gpio7)
- function:
Usage: required
diff --git a/Documentation/devicetree/bindings/pinctrl/qcom,sc7180-pinctrl.txt b/Documentation/devicetree/bindings/pinctrl/qcom,sc7180-pinctrl.txt
new file mode 100644
index 0000000..b5767ee
--- /dev/null
+++ b/Documentation/devicetree/bindings/pinctrl/qcom,sc7180-pinctrl.txt
@@ -0,0 +1,186 @@
+Qualcomm Technologies, Inc. SC7180 TLMM block
+
+This binding describes the Top Level Mode Multiplexer block found in the
+SC7180 platform.
+
+- compatible:
+ Usage: required
+ Value type: <string>
+ Definition: must be "qcom,sc7180-pinctrl"
+
+- reg:
+ Usage: required
+ Value type: <prop-encoded-array>
+ Definition: the base address and size of the north, south and west
+ TLMM tiles
+
+- reg-names:
+ Usage: required
+ Value type: <prop-encoded-array>
+ Definition: names for the cells of reg, must contain "north", "south"
+ and "west".
+
+- interrupts:
+ Usage: required
+ Value type: <prop-encoded-array>
+ Definition: should specify the TLMM summary IRQ.
+
+- interrupt-controller:
+ Usage: required
+ Value type: <none>
+ Definition: identifies this node as an interrupt controller
+
+- #interrupt-cells:
+ Usage: required
+ Value type: <u32>
+ Definition: must be 2. Specifying the pin number and flags, as defined
+ in <dt-bindings/interrupt-controller/irq.h>
+
+- gpio-controller:
+ Usage: required
+ Value type: <none>
+ Definition: identifies this node as a gpio controller
+
+- #gpio-cells:
+ Usage: required
+ Value type: <u32>
+ Definition: must be 2. Specifying the pin number and flags, as defined
+ in <dt-bindings/gpio/gpio.h>
+
+- gpio-ranges:
+ Usage: required
+ Value type: <prop-encoded-array>
+ Definition: see ../gpio/gpio.txt
+
+- gpio-reserved-ranges:
+ Usage: optional
+ Value type: <prop-encoded-array>
+ Definition: see ../gpio/gpio.txt
+
+Please refer to ../gpio/gpio.txt and ../interrupt-controller/interrupts.txt for
+a general description of GPIO and interrupt bindings.
+
+Please refer to pinctrl-bindings.txt in this directory for details of the
+common pinctrl bindings used by client devices, including the meaning of the
+phrase "pin configuration node".
+
+The pin configuration nodes act as a container for an arbitrary number of
+subnodes. Each of these subnodes represents some desired configuration for a
+pin, a group, or a list of pins or groups. This configuration can include the
+mux function to select on those pin(s)/group(s), and various pin configuration
+parameters, such as pull-up, drive strength, etc.
+
+
+PIN CONFIGURATION NODES:
+
+The name of each subnode is not important; all subnodes should be enumerated
+and processed purely based on their content.
+
+Each subnode only affects those parameters that are explicitly listed. In
+other words, a subnode that lists a mux function but no pin configuration
+parameters implies no information about any pin configuration parameters.
+Similarly, a pin subnode that describes a pullup parameter implies no
+information about e.g. the mux function.
+
+
+The following generic properties as defined in pinctrl-bindings.txt are valid
+to specify in a pin configuration subnode:
+
+- pins:
+ Usage: required
+ Value type: <string-array>
+ Definition: List of gpio pins affected by the properties specified in
+ this subnode.
+
+ Valid pins are:
+ gpio0-gpio118
+ Supports mux, bias and drive-strength
+
+ sdc1_clk, sdc1_cmd, sdc1_data sdc2_clk, sdc2_cmd,
+ sdc2_data sdc1_rclk
+ Supports bias and drive-strength
+
+ ufs_reset
+ Supports bias and drive-strength
+
+- function:
+ Usage: required
+ Value type: <string>
+ Definition: Specify the alternative function to be configured for the
+ specified pins. Functions are only valid for gpio pins.
+ Valid values are:
+
+ adsp_ext, agera_pll, aoss_cti, atest_char, atest_char0,
+ atest_char1, atest_char2, atest_char3, atest_tsens,
+ atest_tsens2, atest_usb1, atest_usb10, atest_usb11,
+ atest_usb12, atest_usb13, atest_usb2, atest_usb20,
+ atest_usb21, atest_usb22, atest_usb23, audio_ref,
+ btfm_slimbus, cam_mclk, cci_async, cci_i2c, cci_timer0,
+ cci_timer1, cci_timer2, cci_timer3, cci_timer4,
+ cri_trng, dbg_out, ddr_bist, ddr_pxi0, ddr_pxi1,
+ ddr_pxi2, ddr_pxi3, dp_hot, edp_lcd, gcc_gp1, gcc_gp2,
+ gcc_gp3, gpio, gp_pdm0, gp_pdm1, gp_pdm2, gps_tx,
+ jitter_bist, ldo_en, ldo_update, lpass_ext, mdp_vsync,
+ mdp_vsync0, mdp_vsync1, mdp_vsync2, mdp_vsync3, mi2s_0,
+ mi2s_1, mi2s_2, mss_lte, m_voc, pa_indicator, phase_flag,
+ PLL_BIST, pll_bypassnl, pll_reset, prng_rosc, qdss,
+ qdss_cti, qlink_enable, qlink_request, qspi_clk, qspi_cs,
+ qspi_data, qup00, qup01, qup02, qup03, qup04, qup05,
+ qup10, qup11, qup12, qup13, qup14, qup15, sdc1_tb,
+ sdc2_tb, sd_write, sp_cmu, tgu_ch0, tgu_ch1, tgu_ch2,
+ tgu_ch3, tsense_pwm1, tsense_pwm2, uim1, uim2, uim_batt,
+ usb_phy, vfr_1, _V_GPIO, _V_PPS_IN, _V_PPS_OUT,
+ vsense_trigger, wlan1_adc0, wlan1_adc1, wlan2_adc0,
+ wlan2_adc1,
+
+- bias-disable:
+ Usage: optional
+ Value type: <none>
+ Definition: The specified pins should be configured as no pull.
+
+- bias-pull-down:
+ Usage: optional
+ Value type: <none>
+ Definition: The specified pins should be configured as pull down.
+
+- bias-pull-up:
+ Usage: optional
+ Value type: <none>
+ Definition: The specified pins should be configured as pull up.
+
+- output-high:
+ Usage: optional
+ Value type: <none>
+ Definition: The specified pins are configured in output mode, driven
+ high.
+ Not valid for sdc pins.
+
+- output-low:
+ Usage: optional
+ Value type: <none>
+ Definition: The specified pins are configured in output mode, driven
+ low.
+ Not valid for sdc pins.
+
+- drive-strength:
+ Usage: optional
+ Value type: <u32>
+ Definition: Selects the drive strength for the specified pins, in mA.
+ Valid values are: 2, 4, 6, 8, 10, 12, 14 and 16
+
+Example:
+
+ tlmm: pinctrl@3500000 {
+ compatible = "qcom,sc7180-pinctrl";
+ reg = <0x3500000 0x300000>,
+ <0x3900000 0x300000>,
+ <0x3D00000 0x300000>;
+ reg-names = "west", "north", "south";
+ interrupts = <GIC_SPI 208 IRQ_TYPE_LEVEL_HIGH>;
+ gpio-controller;
+ #gpio-cells = <2>;
+ gpio-ranges = <&tlmm 0 0 119>;
+ gpio-reserved-ranges = <0 4>, <106 4>;
+ interrupt-controller;
+ #interrupt-cells = <2>;
+ };
diff --git a/Documentation/devicetree/bindings/power/amlogic,meson-ee-pwrc.yaml b/Documentation/devicetree/bindings/power/amlogic,meson-ee-pwrc.yaml
new file mode 100644
index 0000000..aab70e8
--- /dev/null
+++ b/Documentation/devicetree/bindings/power/amlogic,meson-ee-pwrc.yaml
@@ -0,0 +1,93 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+# Copyright 2019 BayLibre, SAS
+%YAML 1.2
+---
+$id: "http://devicetree.org/schemas/power/amlogic,meson-ee-pwrc.yaml#"
+$schema: "http://devicetree.org/meta-schemas/core.yaml#"
+
+title: Amlogic Meson Everything-Else Power Domains
+
+maintainers:
+ - Neil Armstrong <narmstrong@baylibre.com>
+
+description: |+
+ The Everything-Else Power Domains node should be the child of a syscon
+ node with the required property:
+
+ - compatible: Should be the following:
+ "amlogic,meson-gx-hhi-sysctrl", "simple-mfd", "syscon"
+
+ Refer to the the bindings described in
+ Documentation/devicetree/bindings/mfd/syscon.txt
+
+properties:
+ compatible:
+ enum:
+ - amlogic,meson-g12a-pwrc
+ - amlogic,meson-sm1-pwrc
+
+ clocks:
+ minItems: 2
+
+ clock-names:
+ items:
+ - const: vpu
+ - const: vapb
+
+ resets:
+ minItems: 11
+
+ reset-names:
+ items:
+ - const: viu
+ - const: venc
+ - const: vcbus
+ - const: bt656
+ - const: rdma
+ - const: venci
+ - const: vencp
+ - const: vdac
+ - const: vdi6
+ - const: vencl
+ - const: vid_lock
+
+ "#power-domain-cells":
+ const: 1
+
+ amlogic,ao-sysctrl:
+ description: phandle to the AO sysctrl node
+ allOf:
+ - $ref: /schemas/types.yaml#/definitions/phandle
+
+required:
+ - compatible
+ - clocks
+ - clock-names
+ - resets
+ - reset-names
+ - "#power-domain-cells"
+ - amlogic,ao-sysctrl
+
+examples:
+ - |
+ pwrc: power-controller {
+ compatible = "amlogic,meson-sm1-pwrc";
+ #power-domain-cells = <1>;
+ amlogic,ao-sysctrl = <&rti>;
+ resets = <&reset_viu>,
+ <&reset_venc>,
+ <&reset_vcbus>,
+ <&reset_bt656>,
+ <&reset_rdma>,
+ <&reset_venci>,
+ <&reset_vencp>,
+ <&reset_vdac>,
+ <&reset_vdi6>,
+ <&reset_vencl>,
+ <&reset_vid_lock>;
+ reset-names = "viu", "venc", "vcbus", "bt656",
+ "rdma", "venci", "vencp", "vdac",
+ "vdi6", "vencl", "vid_lock";
+ clocks = <&clk_vpu>, <&clk_vapb>;
+ clock-names = "vpu", "vapb";
+ };
diff --git a/Documentation/devicetree/bindings/power/reset/mt6323-poweroff.txt b/Documentation/devicetree/bindings/power/reset/mt6323-poweroff.txt
new file mode 100644
index 0000000..933f0c4
--- /dev/null
+++ b/Documentation/devicetree/bindings/power/reset/mt6323-poweroff.txt
@@ -0,0 +1,20 @@
+Device Tree Bindings for Power Controller on MediaTek PMIC
+
+The power controller which could be found on PMIC is responsible for externally
+powering off or on the remote MediaTek SoC through the circuit BBPU.
+
+Required properties:
+- compatible: Should be one of follows
+ "mediatek,mt6323-pwrc": for MT6323 PMIC
+
+Example:
+
+ pmic {
+ compatible = "mediatek,mt6323";
+
+ ...
+
+ power-controller {
+ compatible = "mediatek,mt6323-pwrc";
+ };
+ }
diff --git a/Documentation/devicetree/bindings/pwm/ingenic,jz47xx-pwm.txt b/Documentation/devicetree/bindings/pwm/ingenic,jz47xx-pwm.txt
deleted file mode 100644
index 493bec8..0000000
--- a/Documentation/devicetree/bindings/pwm/ingenic,jz47xx-pwm.txt
+++ /dev/null
@@ -1,22 +0,0 @@
-Ingenic JZ47xx PWM Controller
-=============================
-
-Required properties:
-- compatible: Should be "ingenic,jz4740-pwm"
-- #pwm-cells: Should be 3. See pwm.txt in this directory for a description
- of the cells format.
-- clocks : phandle to the external clock.
-- clock-names : Should be "ext".
-
-
-Example:
-
- pwm: pwm@10002000 {
- compatible = "ingenic,jz4740-pwm";
- reg = <0x10002000 0x1000>;
-
- #pwm-cells = <3>;
-
- clocks = <&ext>;
- clock-names = "ext";
- };
diff --git a/Documentation/devicetree/bindings/pwm/pwm-mediatek.txt b/Documentation/devicetree/bindings/pwm/pwm-mediatek.txt
index 991728c..c850153 100644
--- a/Documentation/devicetree/bindings/pwm/pwm-mediatek.txt
+++ b/Documentation/devicetree/bindings/pwm/pwm-mediatek.txt
@@ -6,6 +6,8 @@
- "mediatek,mt7622-pwm": found on mt7622 SoC.
- "mediatek,mt7623-pwm": found on mt7623 SoC.
- "mediatek,mt7628-pwm": found on mt7628 SoC.
+ - "mediatek,mt7629-pwm", "mediatek,mt7622-pwm": found on mt7629 SoC.
+ - "mediatek,mt8516-pwm": found on mt8516 SoC.
- reg: physical base address and length of the controller's registers.
- #pwm-cells: must be 2. See pwm.txt in this directory for a description of
the cell format.
diff --git a/Documentation/devicetree/bindings/pwm/pwm-sprd.txt b/Documentation/devicetree/bindings/pwm/pwm-sprd.txt
new file mode 100644
index 0000000..16fa5a0
--- /dev/null
+++ b/Documentation/devicetree/bindings/pwm/pwm-sprd.txt
@@ -0,0 +1,40 @@
+Spreadtrum PWM controller
+
+Spreadtrum SoCs PWM controller provides 4 PWM channels.
+
+Required properties:
+- compatible : Should be "sprd,ums512-pwm".
+- reg: Physical base address and length of the controller's registers.
+- clocks: The phandle and specifier referencing the controller's clocks.
+- clock-names: Should contain following entries:
+ "pwmn": used to derive the functional clock for PWM channel n (n range: 0 ~ 3).
+ "enablen": for PWM channel n enable clock (n range: 0 ~ 3).
+- #pwm-cells: Should be 2. See pwm.txt in this directory for a description of
+ the cells format.
+
+Optional properties:
+- assigned-clocks: Reference to the PWM clock entries.
+- assigned-clock-parents: The phandle of the parent clock of PWM clock.
+
+Example:
+ pwms: pwm@32260000 {
+ compatible = "sprd,ums512-pwm";
+ reg = <0 0x32260000 0 0x10000>;
+ clock-names = "pwm0", "enable0",
+ "pwm1", "enable1",
+ "pwm2", "enable2",
+ "pwm3", "enable3";
+ clocks = <&aon_clk CLK_PWM0>, <&aonapb_gate CLK_PWM0_EB>,
+ <&aon_clk CLK_PWM1>, <&aonapb_gate CLK_PWM1_EB>,
+ <&aon_clk CLK_PWM2>, <&aonapb_gate CLK_PWM2_EB>,
+ <&aon_clk CLK_PWM3>, <&aonapb_gate CLK_PWM3_EB>;
+ assigned-clocks = <&aon_clk CLK_PWM0>,
+ <&aon_clk CLK_PWM1>,
+ <&aon_clk CLK_PWM2>,
+ <&aon_clk CLK_PWM3>;
+ assigned-clock-parents = <&ext_26m>,
+ <&ext_26m>,
+ <&ext_26m>,
+ <&ext_26m>;
+ #pwm-cells = <2>;
+ };
diff --git a/Documentation/devicetree/bindings/regulator/act8865-regulator.txt b/Documentation/devicetree/bindings/regulator/act8865-regulator.txt
index 3ae9f10..b9f58e4 100644
--- a/Documentation/devicetree/bindings/regulator/act8865-regulator.txt
+++ b/Documentation/devicetree/bindings/regulator/act8865-regulator.txt
@@ -34,6 +34,9 @@
- inl67-supply: The input supply for LDO_REG3 and LDO_REG4
Any standard regulator properties can be used to configure the single regulator.
+regulator-initial-mode, regulator-allowed-modes and regulator-mode could be specified
+for act8865 using mode values from dt-bindings/regulator/active-semi,8865-regulator.h
+file.
The valid names for regulators are:
- for act8846:
@@ -47,6 +50,8 @@
Example:
--------
+#include <dt-bindings/regulator/active-semi,8865-regulator.h>
+
i2c1: i2c@f0018000 {
pmic: act8865@5b {
compatible = "active-semi,act8865";
@@ -65,9 +70,19 @@
regulator-name = "VCC_1V2";
regulator-min-microvolt = <1100000>;
regulator-max-microvolt = <1300000>;
- regulator-suspend-mem-microvolt = <1150000>;
- regulator-suspend-standby-microvolt = <1150000>;
regulator-always-on;
+
+ regulator-allowed-modes = <ACT8865_REGULATOR_MODE_FIXED>,
+ <ACT8865_REGULATOR_MODE_LOWPOWER>;
+ regulator-initial-mode = <ACT8865_REGULATOR_MODE_FIXED>;
+
+ regulator-state-mem {
+ regulator-on-in-suspend;
+ regulator-suspend-min-microvolt = <1150000>;
+ regulator-suspend-max-microvolt = <1150000>;
+ regulator-changeable-in-suspend;
+ regulator-mode = <ACT8865_REGULATOR_MODE_LOWPOWER>;
+ };
};
vcc_3v3_reg: DCDC_REG3 {
@@ -82,6 +97,14 @@
regulator-min-microvolt = <3300000>;
regulator-max-microvolt = <3300000>;
regulator-always-on;
+
+ regulator-allowed-modes = <ACT8865_REGULATOR_MODE_NORMAL>,
+ <ACT8865_REGULATOR_MODE_LOWPOWER>;
+ regulator-initial-mode = <ACT8865_REGULATOR_MODE_NORMAL>;
+
+ regulator-state-mem {
+ regulator-off-in-suspend;
+ };
};
vddfuse_reg: LDO_REG2 {
diff --git a/Documentation/devicetree/bindings/regulator/fixed-regulator.yaml b/Documentation/devicetree/bindings/regulator/fixed-regulator.yaml
index a650b45..a78150c 100644
--- a/Documentation/devicetree/bindings/regulator/fixed-regulator.yaml
+++ b/Documentation/devicetree/bindings/regulator/fixed-regulator.yaml
@@ -19,9 +19,19 @@
allOf:
- $ref: "regulator.yaml#"
+if:
+ properties:
+ compatible:
+ contains:
+ const: regulator-fixed-clock
+ required:
+ - clocks
+
properties:
compatible:
- const: regulator-fixed
+ enum:
+ - const: regulator-fixed
+ - const: regulator-fixed-clock
regulator-name: true
@@ -29,6 +39,13 @@
description: gpio to use for enable control
maxItems: 1
+ clocks:
+ description:
+ clock to use for enable control. This binding is only available if
+ the compatible is chosen to regulator-fixed-clock. The clock binding
+ is mandatory if compatible is chosen to regulator-fixed-clock.
+ maxItems: 1
+
startup-delay-us:
description: startup time in microseconds
$ref: /schemas/types.yaml#/definitions/uint32
diff --git a/Documentation/devicetree/bindings/regulator/mt6358-regulator.txt b/Documentation/devicetree/bindings/regulator/mt6358-regulator.txt
new file mode 100644
index 0000000..9a90a92
--- /dev/null
+++ b/Documentation/devicetree/bindings/regulator/mt6358-regulator.txt
@@ -0,0 +1,358 @@
+MediaTek MT6358 Regulator
+
+All voltage regulators provided by the MT6358 PMIC are described as the
+subnodes of the MT6358 regulators node. Each regulator is named according
+to its regulator type, buck_<name> and ldo_<name>. The definition for each
+of these nodes is defined using the standard binding for regulators at
+Documentation/devicetree/bindings/regulator/regulator.txt.
+
+The valid names for regulators are::
+BUCK:
+ buck_vdram1, buck_vcore, buck_vpa, buck_vproc11, buck_vproc12, buck_vgpu,
+ buck_vs2, buck_vmodem, buck_vs1
+LDO:
+ ldo_vdram2, ldo_vsim1, ldo_vibr, ldo_vrf12, ldo_vio18, ldo_vusb, ldo_vcamio,
+ ldo_vcamd, ldo_vcn18, ldo_vfe28, ldo_vsram_proc11, ldo_vcn28, ldo_vsram_others,
+ ldo_vsram_gpu, ldo_vxo22, ldo_vefuse, ldo_vaux18, ldo_vmch, ldo_vbif28,
+ ldo_vsram_proc12, ldo_vcama1, ldo_vemc, ldo_vio28, ldo_va12, ldo_vrf18,
+ ldo_vcn33_bt, ldo_vcn33_wifi, ldo_vcama2, ldo_vmc, ldo_vldo28, ldo_vaud28,
+ ldo_vsim2
+
+Example:
+
+ pmic {
+ compatible = "mediatek,mt6358";
+
+ mt6358regulator: mt6358regulator {
+ compatible = "mediatek,mt6358-regulator";
+
+ mt6358_vdram1_reg: buck_vdram1 {
+ regulator-compatible = "buck_vdram1";
+ regulator-name = "vdram1";
+ regulator-min-microvolt = <500000>;
+ regulator-max-microvolt = <2087500>;
+ regulator-ramp-delay = <12500>;
+ regulator-enable-ramp-delay = <0>;
+ regulator-always-on;
+ };
+
+ mt6358_vcore_reg: buck_vcore {
+ regulator-name = "vcore";
+ regulator-min-microvolt = <500000>;
+ regulator-max-microvolt = <1293750>;
+ regulator-ramp-delay = <6250>;
+ regulator-enable-ramp-delay = <200>;
+ regulator-always-on;
+ };
+
+ mt6358_vpa_reg: buck_vpa {
+ regulator-name = "vpa";
+ regulator-min-microvolt = <500000>;
+ regulator-max-microvolt = <3650000>;
+ regulator-ramp-delay = <50000>;
+ regulator-enable-ramp-delay = <250>;
+ };
+
+ mt6358_vproc11_reg: buck_vproc11 {
+ regulator-name = "vproc11";
+ regulator-min-microvolt = <500000>;
+ regulator-max-microvolt = <1293750>;
+ regulator-ramp-delay = <6250>;
+ regulator-enable-ramp-delay = <200>;
+ regulator-always-on;
+ };
+
+ mt6358_vproc12_reg: buck_vproc12 {
+ regulator-name = "vproc12";
+ regulator-min-microvolt = <500000>;
+ regulator-max-microvolt = <1293750>;
+ regulator-ramp-delay = <6250>;
+ regulator-enable-ramp-delay = <200>;
+ regulator-always-on;
+ };
+
+ mt6358_vgpu_reg: buck_vgpu {
+ regulator-name = "vgpu";
+ regulator-min-microvolt = <500000>;
+ regulator-max-microvolt = <1293750>;
+ regulator-ramp-delay = <6250>;
+ regulator-enable-ramp-delay = <200>;
+ };
+
+ mt6358_vs2_reg: buck_vs2 {
+ regulator-name = "vs2";
+ regulator-min-microvolt = <500000>;
+ regulator-max-microvolt = <2087500>;
+ regulator-ramp-delay = <12500>;
+ regulator-enable-ramp-delay = <0>;
+ regulator-always-on;
+ };
+
+ mt6358_vmodem_reg: buck_vmodem {
+ regulator-name = "vmodem";
+ regulator-min-microvolt = <500000>;
+ regulator-max-microvolt = <1293750>;
+ regulator-ramp-delay = <6250>;
+ regulator-enable-ramp-delay = <900>;
+ regulator-always-on;
+ };
+
+ mt6358_vs1_reg: buck_vs1 {
+ regulator-name = "vs1";
+ regulator-min-microvolt = <1000000>;
+ regulator-max-microvolt = <2587500>;
+ regulator-ramp-delay = <12500>;
+ regulator-enable-ramp-delay = <0>;
+ regulator-always-on;
+ };
+
+ mt6358_vdram2_reg: ldo_vdram2 {
+ regulator-name = "vdram2";
+ regulator-min-microvolt = <600000>;
+ regulator-max-microvolt = <1800000>;
+ regulator-enable-ramp-delay = <3300>;
+ };
+
+ mt6358_vsim1_reg: ldo_vsim1 {
+ regulator-name = "vsim1";
+ regulator-min-microvolt = <1700000>;
+ regulator-max-microvolt = <3100000>;
+ regulator-enable-ramp-delay = <540>;
+ };
+
+ mt6358_vibr_reg: ldo_vibr {
+ regulator-name = "vibr";
+ regulator-min-microvolt = <1200000>;
+ regulator-max-microvolt = <3300000>;
+ regulator-enable-ramp-delay = <60>;
+ };
+
+ mt6358_vrf12_reg: ldo_vrf12 {
+ compatible = "regulator-fixed";
+ regulator-name = "vrf12";
+ regulator-min-microvolt = <1200000>;
+ regulator-max-microvolt = <1200000>;
+ regulator-enable-ramp-delay = <120>;
+ };
+
+ mt6358_vio18_reg: ldo_vio18 {
+ compatible = "regulator-fixed";
+ regulator-name = "vio18";
+ regulator-min-microvolt = <1800000>;
+ regulator-max-microvolt = <1800000>;
+ regulator-enable-ramp-delay = <2700>;
+ regulator-always-on;
+ };
+
+ mt6358_vusb_reg: ldo_vusb {
+ regulator-name = "vusb";
+ regulator-min-microvolt = <3000000>;
+ regulator-max-microvolt = <3100000>;
+ regulator-enable-ramp-delay = <270>;
+ regulator-always-on;
+ };
+
+ mt6358_vcamio_reg: ldo_vcamio {
+ compatible = "regulator-fixed";
+ regulator-name = "vcamio";
+ regulator-min-microvolt = <1800000>;
+ regulator-max-microvolt = <1800000>;
+ regulator-enable-ramp-delay = <270>;
+ };
+
+ mt6358_vcamd_reg: ldo_vcamd {
+ regulator-name = "vcamd";
+ regulator-min-microvolt = <900000>;
+ regulator-max-microvolt = <1800000>;
+ regulator-enable-ramp-delay = <270>;
+ };
+
+ mt6358_vcn18_reg: ldo_vcn18 {
+ compatible = "regulator-fixed";
+ regulator-name = "vcn18";
+ regulator-min-microvolt = <1800000>;
+ regulator-max-microvolt = <1800000>;
+ regulator-enable-ramp-delay = <270>;
+ };
+
+ mt6358_vfe28_reg: ldo_vfe28 {
+ compatible = "regulator-fixed";
+ regulator-name = "vfe28";
+ regulator-min-microvolt = <2800000>;
+ regulator-max-microvolt = <2800000>;
+ regulator-enable-ramp-delay = <270>;
+ };
+
+ mt6358_vsram_proc11_reg: ldo_vsram_proc11 {
+ regulator-name = "vsram_proc11";
+ regulator-min-microvolt = <500000>;
+ regulator-max-microvolt = <1293750>;
+ regulator-ramp-delay = <6250>;
+ regulator-enable-ramp-delay = <240>;
+ regulator-always-on;
+ };
+
+ mt6358_vcn28_reg: ldo_vcn28 {
+ compatible = "regulator-fixed";
+ regulator-name = "vcn28";
+ regulator-min-microvolt = <2800000>;
+ regulator-max-microvolt = <2800000>;
+ regulator-enable-ramp-delay = <270>;
+ };
+
+ mt6358_vsram_others_reg: ldo_vsram_others {
+ regulator-name = "vsram_others";
+ regulator-min-microvolt = <500000>;
+ regulator-max-microvolt = <1293750>;
+ regulator-ramp-delay = <6250>;
+ regulator-enable-ramp-delay = <240>;
+ regulator-always-on;
+ };
+
+ mt6358_vsram_gpu_reg: ldo_vsram_gpu {
+ regulator-name = "vsram_gpu";
+ regulator-min-microvolt = <500000>;
+ regulator-max-microvolt = <1293750>;
+ regulator-ramp-delay = <6250>;
+ regulator-enable-ramp-delay = <240>;
+ };
+
+ mt6358_vxo22_reg: ldo_vxo22 {
+ compatible = "regulator-fixed";
+ regulator-name = "vxo22";
+ regulator-min-microvolt = <2200000>;
+ regulator-max-microvolt = <2200000>;
+ regulator-enable-ramp-delay = <120>;
+ regulator-always-on;
+ };
+
+ mt6358_vefuse_reg: ldo_vefuse {
+ regulator-name = "vefuse";
+ regulator-min-microvolt = <1700000>;
+ regulator-max-microvolt = <1900000>;
+ regulator-enable-ramp-delay = <270>;
+ };
+
+ mt6358_vaux18_reg: ldo_vaux18 {
+ compatible = "regulator-fixed";
+ regulator-name = "vaux18";
+ regulator-min-microvolt = <1800000>;
+ regulator-max-microvolt = <1800000>;
+ regulator-enable-ramp-delay = <270>;
+ };
+
+ mt6358_vmch_reg: ldo_vmch {
+ regulator-name = "vmch";
+ regulator-min-microvolt = <2900000>;
+ regulator-max-microvolt = <3300000>;
+ regulator-enable-ramp-delay = <60>;
+ };
+
+ mt6358_vbif28_reg: ldo_vbif28 {
+ compatible = "regulator-fixed";
+ regulator-name = "vbif28";
+ regulator-min-microvolt = <2800000>;
+ regulator-max-microvolt = <2800000>;
+ regulator-enable-ramp-delay = <270>;
+ };
+
+ mt6358_vsram_proc12_reg: ldo_vsram_proc12 {
+ regulator-name = "vsram_proc12";
+ regulator-min-microvolt = <500000>;
+ regulator-max-microvolt = <1293750>;
+ regulator-ramp-delay = <6250>;
+ regulator-enable-ramp-delay = <240>;
+ regulator-always-on;
+ };
+
+ mt6358_vcama1_reg: ldo_vcama1 {
+ regulator-name = "vcama1";
+ regulator-min-microvolt = <1800000>;
+ regulator-max-microvolt = <3000000>;
+ regulator-enable-ramp-delay = <270>;
+ };
+
+ mt6358_vemc_reg: ldo_vemc {
+ regulator-name = "vemc";
+ regulator-min-microvolt = <2900000>;
+ regulator-max-microvolt = <3300000>;
+ regulator-enable-ramp-delay = <60>;
+ regulator-always-on;
+ };
+
+ mt6358_vio28_reg: ldo_vio28 {
+ compatible = "regulator-fixed";
+ regulator-name = "vio28";
+ regulator-min-microvolt = <2800000>;
+ regulator-max-microvolt = <2800000>;
+ regulator-enable-ramp-delay = <270>;
+ };
+
+ mt6358_va12_reg: ldo_va12 {
+ compatible = "regulator-fixed";
+ regulator-name = "va12";
+ regulator-min-microvolt = <1200000>;
+ regulator-max-microvolt = <1200000>;
+ regulator-enable-ramp-delay = <270>;
+ regulator-always-on;
+ };
+
+ mt6358_vrf18_reg: ldo_vrf18 {
+ compatible = "regulator-fixed";
+ regulator-name = "vrf18";
+ regulator-min-microvolt = <1800000>;
+ regulator-max-microvolt = <1800000>;
+ regulator-enable-ramp-delay = <120>;
+ };
+
+ mt6358_vcn33_bt_reg: ldo_vcn33_bt {
+ regulator-name = "vcn33_bt";
+ regulator-min-microvolt = <3300000>;
+ regulator-max-microvolt = <3500000>;
+ regulator-enable-ramp-delay = <270>;
+ };
+
+ mt6358_vcn33_wifi_reg: ldo_vcn33_wifi {
+ regulator-name = "vcn33_wifi";
+ regulator-min-microvolt = <3300000>;
+ regulator-max-microvolt = <3500000>;
+ regulator-enable-ramp-delay = <270>;
+ };
+
+ mt6358_vcama2_reg: ldo_vcama2 {
+ regulator-name = "vcama2";
+ regulator-min-microvolt = <1800000>;
+ regulator-max-microvolt = <3000000>;
+ regulator-enable-ramp-delay = <270>;
+ };
+
+ mt6358_vmc_reg: ldo_vmc {
+ regulator-name = "vmc";
+ regulator-min-microvolt = <1800000>;
+ regulator-max-microvolt = <3300000>;
+ regulator-enable-ramp-delay = <60>;
+ };
+
+ mt6358_vldo28_reg: ldo_vldo28 {
+ regulator-name = "vldo28";
+ regulator-min-microvolt = <2800000>;
+ regulator-max-microvolt = <3000000>;
+ regulator-enable-ramp-delay = <270>;
+ };
+
+ mt6358_vaud28_reg: ldo_vaud28 {
+ compatible = "regulator-fixed";
+ regulator-name = "vaud28";
+ regulator-min-microvolt = <2800000>;
+ regulator-max-microvolt = <2800000>;
+ regulator-enable-ramp-delay = <270>;
+ };
+
+ mt6358_vsim2_reg: ldo_vsim2 {
+ regulator-name = "vsim2";
+ regulator-min-microvolt = <1700000>;
+ regulator-max-microvolt = <3100000>;
+ regulator-enable-ramp-delay = <540>;
+ };
+ };
+ };
diff --git a/Documentation/devicetree/bindings/regulator/qcom,rpmh-regulator.txt b/Documentation/devicetree/bindings/regulator/qcom,rpmh-regulator.txt
index 14d2eee..bab9f71 100644
--- a/Documentation/devicetree/bindings/regulator/qcom,rpmh-regulator.txt
+++ b/Documentation/devicetree/bindings/regulator/qcom,rpmh-regulator.txt
@@ -22,9 +22,12 @@
The names used for regulator nodes must match those supported by a given PMIC.
Supported regulator node names:
+ PM8005: smps1 - smps4
+ PM8009: smps1 - smps2, ldo1 - ldo7
+ PM8150: smps1 - smps10, ldo1 - ldo18
+ PM8150L: smps1 - smps8, ldo1 - ldo11, bob, flash, rgb
PM8998: smps1 - smps13, ldo1 - ldo28, lvs1 - lvs2
PMI8998: bob
- PM8005: smps1 - smps4
========================
First Level Nodes - PMIC
@@ -33,9 +36,13 @@
- compatible
Usage: required
Value type: <string>
- Definition: Must be one of: "qcom,pm8998-rpmh-regulators",
- "qcom,pmi8998-rpmh-regulators" or
- "qcom,pm8005-rpmh-regulators".
+ Definition: Must be one of below:
+ "qcom,pm8005-rpmh-regulators"
+ "qcom,pm8009-rpmh-regulators"
+ "qcom,pm8150-rpmh-regulators"
+ "qcom,pm8150l-rpmh-regulators"
+ "qcom,pm8998-rpmh-regulators"
+ "qcom,pmi8998-rpmh-regulators"
- qcom,pmic-id
Usage: required
diff --git a/Documentation/devicetree/bindings/regulator/sy8824x.txt b/Documentation/devicetree/bindings/regulator/sy8824x.txt
new file mode 100644
index 0000000..c5e9585
--- /dev/null
+++ b/Documentation/devicetree/bindings/regulator/sy8824x.txt
@@ -0,0 +1,24 @@
+SY8824C/SY8824E/SY20276 Voltage regulator
+
+Required properties:
+- compatible: Must be one of the following.
+ "silergy,sy8824c"
+ "silergy,sy8824e"
+ "silergy,sy20276"
+ "silergy,sy20278"
+- reg: I2C slave address
+
+Any property defined as part of the core regulator binding, defined in
+./regulator.txt, can also be used.
+
+Example:
+
+ vcore: regulator@00 {
+ compatible = "silergy,sy8824c";
+ reg = <0x66>;
+ regulator-name = "vcore";
+ regulator-min-microvolt = <800000>;
+ regulator-max-microvolt = <1150000>;
+ regulator-boot-on;
+ regulator-always-on;
+ };
diff --git a/Documentation/devicetree/bindings/regulator/twl-regulator.txt b/Documentation/devicetree/bindings/regulator/twl-regulator.txt
index 74a91c4..549f804 100644
--- a/Documentation/devicetree/bindings/regulator/twl-regulator.txt
+++ b/Documentation/devicetree/bindings/regulator/twl-regulator.txt
@@ -71,3 +71,10 @@
regulator-min-microvolt = <1000000>;
regulator-max-microvolt = <3000000>;
};
+
+For twl6030 regulators/LDOs:
+
+ - ti,retain-on-reset: Does not turn off the supplies during warm
+ reset. Could be needed for VMMC, as TWL6030
+ reset sequence for this signal does not comply
+ with the SD specification.
diff --git a/Documentation/devicetree/bindings/regulator/uniphier-regulator.txt b/Documentation/devicetree/bindings/regulator/uniphier-regulator.txt
index c9919f4..94fd38b 100644
--- a/Documentation/devicetree/bindings/regulator/uniphier-regulator.txt
+++ b/Documentation/devicetree/bindings/regulator/uniphier-regulator.txt
@@ -13,6 +13,7 @@
Required properties:
- compatible: Should be
"socionext,uniphier-pro4-usb3-regulator" - for Pro4 SoC
+ "socionext,uniphier-pro5-usb3-regulator" - for Pro5 SoC
"socionext,uniphier-pxs2-usb3-regulator" - for PXs2 SoC
"socionext,uniphier-ld20-usb3-regulator" - for LD20 SoC
"socionext,uniphier-pxs3-usb3-regulator" - for PXs3 SoC
@@ -20,12 +21,12 @@
- clocks: A list of phandles to the clock gate for USB3 glue layer.
According to the clock-names, appropriate clocks are required.
- clock-names: Should contain
- "gio", "link" - for Pro4 SoC
+ "gio", "link" - for Pro4 and Pro5 SoCs
"link" - for others
- resets: A list of phandles to the reset control for USB3 glue layer.
According to the reset-names, appropriate resets are required.
- reset-names: Should contain
- "gio", "link" - for Pro4 SoC
+ "gio", "link" - for Pro4 and Pro5 SoCs
"link" - for others
See Documentation/devicetree/bindings/regulator/regulator.txt
diff --git a/Documentation/devicetree/bindings/reset/amlogic,meson-reset.txt b/Documentation/devicetree/bindings/reset/amlogic,meson-reset.txt
deleted file mode 100644
index 28ef6c2..0000000
--- a/Documentation/devicetree/bindings/reset/amlogic,meson-reset.txt
+++ /dev/null
@@ -1,19 +0,0 @@
-Amlogic Meson SoC Reset Controller
-=======================================
-
-Please also refer to reset.txt in this directory for common reset
-controller binding usage.
-
-Required properties:
-- compatible: Should be "amlogic,meson8b-reset", "amlogic,meson-gxbb-reset" or
- "amlogic,meson-axg-reset".
-- reg: should contain the register address base
-- #reset-cells: 1, see below
-
-example:
-
-reset: reset-controller {
- compatible = "amlogic,meson-gxbb-reset";
- reg = <0x0 0x04404 0x0 0x20>;
- #reset-cells = <1>;
-};
diff --git a/Documentation/devicetree/bindings/reset/amlogic,meson-reset.yaml b/Documentation/devicetree/bindings/reset/amlogic,meson-reset.yaml
new file mode 100644
index 0000000..00917d8
--- /dev/null
+++ b/Documentation/devicetree/bindings/reset/amlogic,meson-reset.yaml
@@ -0,0 +1,37 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+# Copyright 2019 BayLibre, SAS
+%YAML 1.2
+---
+$id: "http://devicetree.org/schemas/reset/amlogic,meson-reset.yaml#"
+$schema: "http://devicetree.org/meta-schemas/core.yaml#"
+
+title: Amlogic Meson SoC Reset Controller
+
+maintainers:
+ - Neil Armstrong <narmstrong@baylibre.com>
+
+properties:
+ compatible:
+ enum:
+ - amlogic,meson8b-reset # Reset Controller on Meson8b and compatible SoCs
+ - amlogic,meson-gxbb-reset # Reset Controller on GXBB and compatible SoCs
+ - amlogic,meson-axg-reset # Reset Controller on AXG and compatible SoCs
+
+ reg:
+ maxItems: 1
+
+ "#reset-cells":
+ const: 1
+
+required:
+ - compatible
+ - reg
+ - "#reset-cells"
+
+examples:
+ - |
+ reset-controller@c884404 {
+ compatible = "amlogic,meson-gxbb-reset";
+ reg = <0xc884404 0x20>;
+ #reset-cells = <1>;
+ };
diff --git a/Documentation/devicetree/bindings/reset/fsl,imx7-src.txt b/Documentation/devicetree/bindings/reset/fsl,imx7-src.txt
index 13e0951..c2489e4 100644
--- a/Documentation/devicetree/bindings/reset/fsl,imx7-src.txt
+++ b/Documentation/devicetree/bindings/reset/fsl,imx7-src.txt
@@ -8,6 +8,7 @@
- compatible:
- For i.MX7 SoCs should be "fsl,imx7d-src", "syscon"
- For i.MX8MQ SoCs should be "fsl,imx8mq-src", "syscon"
+ - For i.MX8MM SoCs should be "fsl,imx8mm-src", "fsl,imx8mq-src", "syscon"
- reg: should be register base and length as documented in the
datasheet
- interrupts: Should contain SRC interrupt
@@ -46,5 +47,6 @@
For list of all valid reset indices see
-<dt-bindings/reset/imx7-reset.h> for i.MX7 and
-<dt-bindings/reset/imx8mq-reset.h> for i.MX8MQ
+<dt-bindings/reset/imx7-reset.h> for i.MX7,
+<dt-bindings/reset/imx8mq-reset.h> for i.MX8MQ and
+<dt-bindings/reset/imx8mq-reset.h> for i.MX8MM
diff --git a/Documentation/devicetree/bindings/reset/hisilicon,hi6220-reset.txt b/Documentation/devicetree/bindings/reset/hisilicon,hi6220-reset.txt
index c25da39..ea0a6a9 100644
--- a/Documentation/devicetree/bindings/reset/hisilicon,hi6220-reset.txt
+++ b/Documentation/devicetree/bindings/reset/hisilicon,hi6220-reset.txt
@@ -11,6 +11,7 @@
- compatible: should be one of the following:
- "hisilicon,hi6220-sysctrl", "syscon" : For peripheral reset controller.
- "hisilicon,hi6220-mediactrl", "syscon" : For media reset controller.
+ - "hisilicon,hi6220-aoctrl", "syscon" : For ao reset controller.
- reg: should be register base and length as documented in the
datasheet
- #reset-cells: 1, see below
diff --git a/Documentation/devicetree/bindings/reset/snps,dw-reset.txt b/Documentation/devicetree/bindings/reset/snps,dw-reset.txt
new file mode 100644
index 0000000..f94f911
--- /dev/null
+++ b/Documentation/devicetree/bindings/reset/snps,dw-reset.txt
@@ -0,0 +1,30 @@
+Synopsys DesignWare Reset controller
+=======================================
+
+Please also refer to reset.txt in this directory for common reset
+controller binding usage.
+
+Required properties:
+
+- compatible: should be one of the following.
+ "snps,dw-high-reset" - for active high configuration
+ "snps,dw-low-reset" - for active low configuration
+
+- reg: physical base address of the controller and length of memory mapped
+ region.
+
+- #reset-cells: must be 1.
+
+example:
+
+ dw_rst_1: reset-controller@0000 {
+ compatible = "snps,dw-high-reset";
+ reg = <0x0000 0x4>;
+ #reset-cells = <1>;
+ };
+
+ dw_rst_2: reset-controller@1000 {i
+ compatible = "snps,dw-low-reset";
+ reg = <0x1000 0x8>;
+ #reset-cells = <1>;
+ };
diff --git a/Documentation/devicetree/bindings/rng/amlogic,meson-rng.txt b/Documentation/devicetree/bindings/rng/amlogic,meson-rng.txt
deleted file mode 100644
index 4d40364..0000000
--- a/Documentation/devicetree/bindings/rng/amlogic,meson-rng.txt
+++ /dev/null
@@ -1,21 +0,0 @@
-Amlogic Meson Random number generator
-=====================================
-
-Required properties:
-
-- compatible : should be "amlogic,meson-rng"
-- reg : Specifies base physical address and size of the registers.
-
-Optional properties:
-
-- clocks : phandle to the following named clocks
-- clock-names: Name of core clock, must be "core"
-
-Example:
-
-rng {
- compatible = "amlogic,meson-rng";
- reg = <0x0 0xc8834000 0x0 0x4>;
- clocks = <&clkc CLKID_RNG0>;
- clock-names = "core";
-};
diff --git a/Documentation/devicetree/bindings/rng/amlogic,meson-rng.yaml b/Documentation/devicetree/bindings/rng/amlogic,meson-rng.yaml
new file mode 100644
index 0000000..a9ff3cb
--- /dev/null
+++ b/Documentation/devicetree/bindings/rng/amlogic,meson-rng.yaml
@@ -0,0 +1,37 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+# Copyright 2019 BayLibre, SAS
+%YAML 1.2
+---
+$id: "http://devicetree.org/schemas/rng/amlogic,meson-rng.yaml#"
+$schema: "http://devicetree.org/meta-schemas/core.yaml#"
+
+title: Amlogic Meson Random number generator
+
+maintainers:
+ - Neil Armstrong <narmstrong@baylibre.com>
+
+properties:
+ compatible:
+ enum:
+ - amlogic,meson-rng
+
+ reg:
+ maxItems: 1
+
+ clocks:
+ maxItems: 1
+
+ clock-names:
+ items:
+ - const: core
+
+required:
+ - compatible
+ - reg
+
+examples:
+ - |
+ rng@c8834000 {
+ compatible = "amlogic,meson-rng";
+ reg = <0xc8834000 0x4>;
+ };
diff --git a/Documentation/devicetree/bindings/rng/mtk-rng.txt b/Documentation/devicetree/bindings/rng/mtk-rng.txt
index 2bc89f1..dfdcb5c 100644
--- a/Documentation/devicetree/bindings/rng/mtk-rng.txt
+++ b/Documentation/devicetree/bindings/rng/mtk-rng.txt
@@ -6,6 +6,7 @@
"mediatek,mt7622-rng", "mediatek,mt7623-rng" : for MT7622
"mediatek,mt7629-rng", "mediatek,mt7623-rng" : for MT7629
"mediatek,mt7623-rng" : for MT7623
+ "mediatek,mt8516-rng", "mediatek,mt7623-rng" : for MT8516
- clocks : list of clock specifiers, corresponding to
entries in clock-names property;
- clock-names : Should contain "rng" entries;
diff --git a/Documentation/devicetree/bindings/rng/timeriomem_rng.txt b/Documentation/devicetree/bindings/rng/timeriomem_rng.txt
index 2149400..fb48461 100644
--- a/Documentation/devicetree/bindings/rng/timeriomem_rng.txt
+++ b/Documentation/devicetree/bindings/rng/timeriomem_rng.txt
@@ -12,7 +12,7 @@
which disables using this rng to automatically fill the kernel's
entropy pool.
-N.B. currently 'reg' must be four bytes wide and aligned
+N.B. currently 'reg' must be at least four bytes wide and 32-bit aligned
Example:
diff --git a/Documentation/devicetree/bindings/rtc/allwinner,sun6i-a31-rtc.yaml b/Documentation/devicetree/bindings/rtc/allwinner,sun6i-a31-rtc.yaml
index 924622f..d7a57ec 100644
--- a/Documentation/devicetree/bindings/rtc/allwinner,sun6i-a31-rtc.yaml
+++ b/Documentation/devicetree/bindings/rtc/allwinner,sun6i-a31-rtc.yaml
@@ -25,6 +25,7 @@
- items:
- const: allwinner,sun50i-a64-rtc
- const: allwinner,sun8i-h3-rtc
+ - const: allwinner,sun50i-h6-rtc
reg:
maxItems: 1
@@ -96,6 +97,18 @@
properties:
compatible:
contains:
+ const: allwinner,sun50i-h6-rtc
+
+ then:
+ properties:
+ clock-output-names:
+ minItems: 3
+ maxItems: 3
+
+ - if:
+ properties:
+ compatible:
+ contains:
const: allwinner,sun8i-r40-rtc
then:
diff --git a/Documentation/devicetree/bindings/rtc/nxp,rtc-2123.txt b/Documentation/devicetree/bindings/rtc/nxp,rtc-2123.txt
index 1994f60..7371f52 100644
--- a/Documentation/devicetree/bindings/rtc/nxp,rtc-2123.txt
+++ b/Documentation/devicetree/bindings/rtc/nxp,rtc-2123.txt
@@ -1,7 +1,7 @@
NXP PCF2123 SPI Real Time Clock
Required properties:
-- compatible: should be: "nxp,rtc-pcf2123"
+- compatible: should be: "nxp,pcf2123"
or "microcrystal,rv2123"
- reg: should be the SPI slave chipselect address
@@ -11,7 +11,7 @@
Example:
pcf2123: rtc@3 {
- compatible = "nxp,rtc-pcf2123"
+ compatible = "nxp,pcf2123"
reg = <3>
spi-cs-high;
};
diff --git a/Documentation/devicetree/bindings/rtc/pcf8563.txt b/Documentation/devicetree/bindings/rtc/pcf8563.txt
index 36984ac..6076fe7 100644
--- a/Documentation/devicetree/bindings/rtc/pcf8563.txt
+++ b/Documentation/devicetree/bindings/rtc/pcf8563.txt
@@ -3,7 +3,9 @@
Philips PCF8563/Epson RTC8564 Real Time Clock
Required properties:
-- compatible: Should contain "nxp,pcf8563".
+- compatible: Should contain "nxp,pcf8563",
+ "epson,rtc8564" or
+ "microcrystal,rv8564"
- reg: I2C address for chip.
Optional property:
diff --git a/Documentation/devicetree/bindings/rtc/rtc-ds1307.txt b/Documentation/devicetree/bindings/rtc/rtc-ds1307.txt
index eaee19b..66f0a31 100644
--- a/Documentation/devicetree/bindings/rtc/rtc-ds1307.txt
+++ b/Documentation/devicetree/bindings/rtc/rtc-ds1307.txt
@@ -19,6 +19,7 @@
"pericom,pt7c4338",
"epson,rx8025",
"isil,isl12057"
+ "epson,rx8130"
- reg: I2C bus address of the device
Optional properties:
diff --git a/Documentation/devicetree/bindings/rtc/rtc-fsl-ftm-alarm.txt b/Documentation/devicetree/bindings/rtc/rtc-fsl-ftm-alarm.txt
new file mode 100644
index 0000000..fffac74
--- /dev/null
+++ b/Documentation/devicetree/bindings/rtc/rtc-fsl-ftm-alarm.txt
@@ -0,0 +1,36 @@
+Freescale FlexTimer Module (FTM) Alarm
+
+Required properties:
+- compatible : Should be "fsl,<chip>-ftm-alarm", the
+ supported chips include
+ "fsl,ls1012a-ftm-alarm"
+ "fsl,ls1021a-ftm-alarm"
+ "fsl,ls1028a-ftm-alarm"
+ "fsl,ls1043a-ftm-alarm"
+ "fsl,ls1046a-ftm-alarm"
+ "fsl,ls1088a-ftm-alarm"
+ "fsl,ls208xa-ftm-alarm"
+ "fsl,lx2160a-ftm-alarm"
+- reg : Specifies base physical address and size of the register sets for the
+ FlexTimer Module.
+- interrupts : Should be the FlexTimer Module interrupt.
+- fsl,rcpm-wakeup property and rcpm node : Please refer
+ Documentation/devicetree/bindings/soc/fsl/rcpm.txt
+
+Optional properties:
+- big-endian: If the host controller is big-endian mode, specify this property.
+ The default endian mode is little-endian.
+
+Example:
+rcpm: rcpm@1e34040 {
+ compatible = "fsl,ls1088a-rcpm", "fsl,qoriq-rcpm-2.1+";
+ reg = <0x0 0x1e34040 0x0 0x18>;
+ #fsl,rcpm-wakeup-cells = <6>;
+};
+
+ftm_alarm0: timer@2800000 {
+ compatible = "fsl,ls1088a-ftm-alarm";
+ reg = <0x0 0x2800000 0x0 0x10000>;
+ fsl,rcpm-wakeup = <&rcpm 0x0 0x0 0x0 0x0 0x4000 0x0>;
+ interrupts = <0 44 4>;
+};
diff --git a/Documentation/devicetree/bindings/rtc/rtc-meson-vrtc.txt b/Documentation/devicetree/bindings/rtc/rtc-meson-vrtc.txt
new file mode 100644
index 0000000..c014f54
--- /dev/null
+++ b/Documentation/devicetree/bindings/rtc/rtc-meson-vrtc.txt
@@ -0,0 +1,22 @@
+* Amlogic Virtual RTC (VRTC)
+
+This is a Linux interface to an RTC managed by firmware, hence it's
+virtual from a Linux perspective. The interface is 1 register where
+an alarm time (in seconds) is to be written.
+
+Required properties:
+- compatible: should be "amlogic,meson-vrtc"
+- reg: physical address for the alarm register
+
+The alarm register is a simple scratch register shared between the
+application processors (AP) and the secure co-processor (SCP.) When
+the AP suspends, the SCP will use the value of this register to
+program an always-on timer before going sleep. When the timer expires,
+the SCP will wake up and will then wake the AP.
+
+Example:
+
+ vrtc: rtc@0a8 {
+ compatible = "amlogic,meson-vrtc";
+ reg = <0x0 0x000a8 0x0 0x4>;
+ };
diff --git a/Documentation/devicetree/bindings/rtc/trivial-rtc.yaml b/Documentation/devicetree/bindings/rtc/trivial-rtc.yaml
index 0c12ce9..18cb456 100644
--- a/Documentation/devicetree/bindings/rtc/trivial-rtc.yaml
+++ b/Documentation/devicetree/bindings/rtc/trivial-rtc.yaml
@@ -52,8 +52,6 @@
- nxp,pcf2127
# Real-time clock
- nxp,pcf2129
- # Real-time clock/calendar
- - nxp,pcf8563
# Real-time Clock Module
- pericom,pt7c4338
# I2C bus SERIAL INTERFACE REAL-TIME CLOCK IC
diff --git a/Documentation/devicetree/bindings/serial/amlogic,meson-uart.txt b/Documentation/devicetree/bindings/serial/amlogic,meson-uart.txt
deleted file mode 100644
index c06c045..0000000
--- a/Documentation/devicetree/bindings/serial/amlogic,meson-uart.txt
+++ /dev/null
@@ -1,38 +0,0 @@
-Amlogic Meson SoC UART Serial Interface
-=======================================
-
-The Amlogic Meson SoC UART Serial Interface is present on a large range
-of SoCs, and can be present either in the "Always-On" power domain or the
-"Everything-Else" power domain.
-
-The particularity of the "Always-On" Serial Interface is that the hardware
-is active since power-on and does not need any clock gating and is usable
-as very early serial console.
-
-Required properties:
-- compatible : compatible: value should be different for each SoC family as :
- - Meson6 : "amlogic,meson6-uart"
- - Meson8 : "amlogic,meson8-uart"
- - Meson8b : "amlogic,meson8b-uart"
- - GX (GXBB, GXL, GXM) : "amlogic,meson-gx-uart"
- eventually followed by : "amlogic,meson-ao-uart" if this UART interface
- is in the "Always-On" power domain.
-- reg : offset and length of the register set for the device.
-- interrupts : identifier to the device interrupt
-- clocks : a list of phandle + clock-specifier pairs, one for each
- entry in clock names.
-- clock-names :
- * "xtal" for external xtal clock identifier
- * "pclk" for the bus core clock, either the clk81 clock or the gate clock
- * "baud" for the source of the baudrate generator, can be either the xtal
- or the pclk.
-
-e.g.
-uart_A: serial@84c0 {
- compatible = "amlogic,meson-gx-uart";
- reg = <0x0 0x84c0 0x0 0x14>;
- interrupts = <GIC_SPI 26 IRQ_TYPE_EDGE_RISING>;
- /* Use xtal as baud rate clock source */
- clocks = <&xtal>, <&clkc CLKID_UART0>, <&xtal>;
- clock-names = "xtal", "pclk", "baud";
-};
diff --git a/Documentation/devicetree/bindings/serial/amlogic,meson-uart.yaml b/Documentation/devicetree/bindings/serial/amlogic,meson-uart.yaml
new file mode 100644
index 0000000..214fe8b
--- /dev/null
+++ b/Documentation/devicetree/bindings/serial/amlogic,meson-uart.yaml
@@ -0,0 +1,73 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+# Copyright 2019 BayLibre, SAS
+%YAML 1.2
+---
+$id: "http://devicetree.org/schemas/serial/amlogic,meson-uart.yaml#"
+$schema: "http://devicetree.org/meta-schemas/core.yaml#"
+
+title: Amlogic Meson SoC UART Serial Interface
+
+maintainers:
+ - Neil Armstrong <narmstrong@baylibre.com>
+
+description: |
+ The Amlogic Meson SoC UART Serial Interface is present on a large range
+ of SoCs, and can be present either in the "Always-On" power domain or the
+ "Everything-Else" power domain.
+
+ The particularity of the "Always-On" Serial Interface is that the hardware
+ is active since power-on and does not need any clock gating and is usable
+ as very early serial console.
+
+properties:
+ compatible:
+ oneOf:
+ - description: Always-on power domain UART controller
+ items:
+ - enum:
+ - amlogic,meson6-uart
+ - amlogic,meson8-uart
+ - amlogic,meson8b-uart
+ - amlogic,meson-gx-uart
+ - const: amlogic,meson-ao-uart
+ - description: Everything-Else power domain UART controller
+ enum:
+ - amlogic,meson6-uart
+ - amlogic,meson8-uart
+ - amlogic,meson8b-uart
+ - amlogic,meson-gx-uart
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+ clocks:
+ items:
+ - description: external xtal clock identifier
+ - description: the bus core clock, either the clk81 clock or the gate clock
+ - description: the source of the baudrate generator, can be either the xtal or the pclk
+
+ clock-names:
+ items:
+ - const: xtal
+ - const: pclk
+ - const: baud
+
+required:
+ - compatible
+ - reg
+ - interrupts
+ - clocks
+ - clock-names
+
+examples:
+ - |
+ serial@84c0 {
+ compatible = "amlogic,meson-gx-uart";
+ reg = <0x84c0 0x14>;
+ interrupts = <26>;
+ clocks = <&xtal>, <&pclk>, <&xtal>;
+ clock-names = "xtal", "pclk", "baud";
+ };
diff --git a/Documentation/devicetree/bindings/serial/fsl,s32-linflexuart.txt b/Documentation/devicetree/bindings/serial/fsl,s32-linflexuart.txt
new file mode 100644
index 0000000..f1bbe08
--- /dev/null
+++ b/Documentation/devicetree/bindings/serial/fsl,s32-linflexuart.txt
@@ -0,0 +1,22 @@
+* Freescale LINFlexD UART
+
+The LINFlexD controller implements several LIN protocol versions, as well as
+support for full-duplex UART communication through 8-bit and 9-bit frames.
+
+See chapter 47 ("LINFlexD") in the reference manual[1].
+
+Required properties:
+- compatible :
+ - "fsl,s32v234-linflexuart" for LINFlexD configured in UART mode, which
+ is compatible with the one integrated on S32V234 SoC
+- reg : Address and length of the register set for the device
+- interrupts : Should contain uart interrupt
+
+Example:
+uart0: serial@40053000 {
+ compatible = "fsl,s32v234-linflexuart";
+ reg = <0x0 0x40053000 0x0 0x1000>;
+ interrupts = <0 59 4>;
+};
+
+[1] https://www.nxp.com/webapp/Download?colCode=S32V234RM
diff --git a/Documentation/devicetree/bindings/serial/fsl-lpuart.txt b/Documentation/devicetree/bindings/serial/fsl-lpuart.txt
index 21483ba..3495eee 100644
--- a/Documentation/devicetree/bindings/serial/fsl-lpuart.txt
+++ b/Documentation/devicetree/bindings/serial/fsl-lpuart.txt
@@ -13,7 +13,10 @@
- reg : Address and length of the register set for the device
- interrupts : Should contain uart interrupt
- clocks : phandle + clock specifier pairs, one for each entry in clock-names
-- clock-names : should contain: "ipg" - the uart clock
+- clock-names : For vf610/ls1021a/imx7ulp, "ipg" clock is for uart bus/baud
+ clock. For imx8qxp lpuart, "ipg" clock is bus clock that is used to access
+ lpuart controller registers, it also requires "baud" clock for module to
+ receive/transmit data.
Optional properties:
- dmas: A list of two dma specifiers, one for each entry in dma-names.
diff --git a/Documentation/devicetree/bindings/serial/mtk-uart.txt b/Documentation/devicetree/bindings/serial/mtk-uart.txt
index 6fdffb7..3a3b570 100644
--- a/Documentation/devicetree/bindings/serial/mtk-uart.txt
+++ b/Documentation/devicetree/bindings/serial/mtk-uart.txt
@@ -9,6 +9,7 @@
* "mediatek,mt6589-uart" for MT6589 compatible UARTS
* "mediatek,mt6755-uart" for MT6755 compatible UARTS
* "mediatek,mt6765-uart" for MT6765 compatible UARTS
+ * "mediatek,mt6779-uart" for MT6779 compatible UARTS
* "mediatek,mt6795-uart" for MT6795 compatible UARTS
* "mediatek,mt6797-uart" for MT6797 compatible UARTS
* "mediatek,mt7622-uart" for MT7622 compatible UARTS
diff --git a/Documentation/devicetree/bindings/serial/nvidia,tegra20-hsuart.txt b/Documentation/devicetree/bindings/serial/nvidia,tegra20-hsuart.txt
index d7edf73..f709304 100644
--- a/Documentation/devicetree/bindings/serial/nvidia,tegra20-hsuart.txt
+++ b/Documentation/devicetree/bindings/serial/nvidia,tegra20-hsuart.txt
@@ -1,7 +1,12 @@
NVIDIA Tegra20/Tegra30 high speed (DMA based) UART controller driver.
Required properties:
-- compatible : should be "nvidia,tegra30-hsuart", "nvidia,tegra20-hsuart".
+- compatible : should be,
+ "nvidia,tegra20-hsuart" for Tegra20,
+ "nvidia,tegra30-hsuart" for Tegra30,
+ "nvidia,tegra186-hsuart" for Tegra186,
+ "nvidia,tegra194-hsuart" for Tegra194.
+
- reg: Should contain UART controller registers location and length.
- interrupts: Should contain UART controller interrupts.
- clocks: Must contain one entry, for the module clock.
@@ -19,6 +24,37 @@
Optional properties:
- nvidia,enable-modem-interrupt: Enable modem interrupts. Should be enable
only if all 8 lines of UART controller are pinmuxed.
+- nvidia,adjust-baud-rates: List of entries providing percentage of baud rate
+ adjustment within a range.
+ Each entry contains sets of 3 values. Range low/high and adjusted rate.
+ <range_low range_high adjusted_rate>
+ When baud rate set on controller falls within the range mentioned in this
+ field, baud rate will be adjusted by percentage mentioned here.
+ Ex: <9600 115200 200>
+ Increase baud rate by 2% when set baud rate falls within range 9600 to 115200
+
+Baud Rate tolerance:
+ Standard UART devices are expected to have tolerance for baud rate error by
+ -4 to +4 %. All Tegra devices till Tegra210 had this support. However,
+ Tegra186 chip has a known hardware issue. UART Rx baud rate tolerance level
+ is 0% to +4% in 1-stop config. Otherwise, the received data will have
+ corruption/invalid framing errors. Parker errata suggests adjusting baud
+ rate to be higher than the deviations observed in Tx.
+
+ Tx deviation of connected device can be captured over scope (or noted from
+ its spec) for valid range and Tegra baud rate has to be set above actual
+ Tx baud rate observed. To do this we use nvidia,adjust-baud-rates
+
+ As an example, consider there is deviation observed in Tx for baud rates as
+ listed below.
+ 0 to 9600 has 1% deviation
+ 9600 to 115200 2% deviation
+ This slight deviation is expcted and Tegra UART is expected to handle it. Due
+ to the issue stated above, baud rate on Tegra UART should be set equal to or
+ above deviation observed for avoiding frame errors.
+ Property should be set like this
+ nvidia,adjust-baud-rates = <0 9600 100>,
+ <9600 115200 200>;
Example:
@@ -33,4 +69,5 @@
reset-names = "serial";
dmas = <&apbdma 8>, <&apbdma 8>;
dma-names = "rx", "tx";
+ nvidia,adjust-baud-rates = <1000000 4000000 136>; /* 1.36% shift */
};
diff --git a/Documentation/devicetree/bindings/serial/sifive-serial.txt b/Documentation/devicetree/bindings/serial/sifive-serial.txt
deleted file mode 100644
index c86b1e5..0000000
--- a/Documentation/devicetree/bindings/serial/sifive-serial.txt
+++ /dev/null
@@ -1,33 +0,0 @@
-SiFive asynchronous serial interface (UART)
-
-Required properties:
-
-- compatible: should be something similar to
- "sifive,<chip>-uart" for the UART as integrated
- on a particular chip, and "sifive,uart<version>" for the
- general UART IP block programming model. Supported
- compatible strings as of the date of this writing are:
- "sifive,fu540-c000-uart" for the SiFive UART v0 as
- integrated onto the SiFive FU540 chip, or "sifive,uart0"
- for the SiFive UART v0 IP block with no chip integration
- tweaks (if any)
-- reg: address and length of the register space
-- interrupts: Should contain the UART interrupt identifier
-- clocks: Should contain a clock identifier for the UART's parent clock
-
-
-UART HDL that corresponds to the IP block version numbers can be found
-here:
-
-https://github.com/sifive/sifive-blocks/tree/master/src/main/scala/devices/uart
-
-
-Example:
-
-uart0: serial@10010000 {
- compatible = "sifive,fu540-c000-uart", "sifive,uart0";
- interrupt-parent = <&plic0>;
- interrupts = <80>;
- reg = <0x0 0x10010000 0x0 0x1000>;
- clocks = <&prci PRCI_CLK_TLCLK>;
-};
diff --git a/Documentation/devicetree/bindings/serial/sifive-serial.yaml b/Documentation/devicetree/bindings/serial/sifive-serial.yaml
new file mode 100644
index 0000000..e8d3aed
--- /dev/null
+++ b/Documentation/devicetree/bindings/serial/sifive-serial.yaml
@@ -0,0 +1,62 @@
+# SPDX-License-Identifier: GPL-2.0
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/serial/sifive-serial.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: SiFive asynchronous serial interface (UART)
+
+maintainers:
+ - Pragnesh Patel <pragnesh.patel@sifive.com>
+ - Paul Walmsley <paul.walmsley@sifive.com>
+ - Palmer Dabbelt <palmer@sifive.com>
+
+allOf:
+ - $ref: /schemas/serial.yaml#
+
+properties:
+ compatible:
+ items:
+ - const: sifive,fu540-c000-uart
+ - const: sifive,uart0
+
+ description:
+ Should be something similar to "sifive,<chip>-uart"
+ for the UART as integrated on a particular chip,
+ and "sifive,uart<version>" for the general UART IP
+ block programming model.
+
+ UART HDL that corresponds to the IP block version
+ numbers can be found here -
+
+ https://github.com/sifive/sifive-blocks/tree/master/src/main/scala/devices/uart
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+ clocks:
+ maxItems: 1
+
+required:
+ - compatible
+ - reg
+ - interrupts
+ - clocks
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/clock/sifive-fu540-prci.h>
+ serial@10010000 {
+ compatible = "sifive,fu540-c000-uart", "sifive,uart0";
+ interrupt-parent = <&plic0>;
+ interrupts = <80>;
+ reg = <0x0 0x10010000 0x0 0x1000>;
+ clocks = <&prci PRCI_CLK_TLCLK>;
+ };
+
+...
diff --git a/Documentation/devicetree/bindings/serial/st,stm32-usart.txt b/Documentation/devicetree/bindings/serial/st,stm32-usart.txt
index a6b1948..8620f7f 100644
--- a/Documentation/devicetree/bindings/serial/st,stm32-usart.txt
+++ b/Documentation/devicetree/bindings/serial/st,stm32-usart.txt
@@ -20,6 +20,11 @@
linux,rs485-enabled-at-boot-time: see rs485.txt.
- dmas: phandle(s) to DMA controller node(s). Refer to stm32-dma.txt
- dma-names: "rx" and/or "tx"
+- wakeup-source: bool flag to indicate this device has wakeup capabilities
+- interrupt-names, if optional wake-up interrupt is used, should be:
+ - "event": the name for the interrupt line of the USART instance
+ - "wakeup" the name for the optional wake-up interrupt
+
Examples:
usart4: serial@40004c00 {
diff --git a/Documentation/devicetree/bindings/soc/amlogic/clk-measure.txt b/Documentation/devicetree/bindings/soc/amlogic/clk-measure.txt
index 6bf6b43..3dd563c 100644
--- a/Documentation/devicetree/bindings/soc/amlogic/clk-measure.txt
+++ b/Documentation/devicetree/bindings/soc/amlogic/clk-measure.txt
@@ -11,6 +11,7 @@
"amlogic,meson8b-clk-measure" for Meson8b SoCs
"amlogic,meson-axg-clk-measure" for AXG SoCs
"amlogic,meson-g12a-clk-measure" for G12a SoCs
+ "amlogic,meson-sm1-clk-measure" for SM1 SoCs
- reg: base address and size of the Clock Measurer register space.
Example:
diff --git a/Documentation/devicetree/bindings/soc/fsl/cpm_qe/qe.txt b/Documentation/devicetree/bindings/soc/fsl/cpm_qe/qe.txt
index d7afaff..05ec2a8 100644
--- a/Documentation/devicetree/bindings/soc/fsl/cpm_qe/qe.txt
+++ b/Documentation/devicetree/bindings/soc/fsl/cpm_qe/qe.txt
@@ -18,7 +18,8 @@
- reg : offset and length of the device registers.
- bus-frequency : the clock frequency for QUICC Engine.
- fsl,qe-num-riscs: define how many RISC engines the QE has.
-- fsl,qe-num-snums: define how many serial number(SNUM) the QE can use for the
+- fsl,qe-snums: This property has to be specified as '/bits/ 8' value,
+ defining the array of serial number (SNUM) values for the virtual
threads.
Optional properties:
@@ -34,6 +35,11 @@
- brg-frequency : the internal clock source frequency for baud-rate
generators in Hz.
+Deprecated properties
+- fsl,qe-num-snums: define how many serial number(SNUM) the QE can use
+ for the threads. Use fsl,qe-snums instead to not only specify the
+ number of snums, but also their values.
+
Example:
qe@e0100000 {
#address-cells = <1>;
@@ -44,6 +50,11 @@
reg = <e0100000 480>;
brg-frequency = <0>;
bus-frequency = <179A7B00>;
+ fsl,qe-snums = /bits/ 8 <
+ 0x04 0x05 0x0C 0x0D 0x14 0x15 0x1C 0x1D
+ 0x24 0x25 0x2C 0x2D 0x34 0x35 0x88 0x89
+ 0x98 0x99 0xA8 0xA9 0xB8 0xB9 0xC8 0xC9
+ 0xD8 0xD9 0xE8 0xE9>;
}
* Multi-User RAM (MURAM)
diff --git a/Documentation/devicetree/bindings/soc/qcom/qcom,aoss-qmp.txt b/Documentation/devicetree/bindings/soc/qcom/qcom,aoss-qmp.txt
index 954ffee..4fc571e7 100644
--- a/Documentation/devicetree/bindings/soc/qcom/qcom,aoss-qmp.txt
+++ b/Documentation/devicetree/bindings/soc/qcom/qcom,aoss-qmp.txt
@@ -15,7 +15,10 @@
- compatible:
Usage: required
Value type: <string>
- Definition: must be "qcom,sdm845-aoss-qmp"
+ Definition: must be one of:
+ "qcom,sc7180-aoss-qmp"
+ "qcom,sdm845-aoss-qmp"
+ "qcom,sm8150-aoss-qmp"
- reg:
Usage: required
diff --git a/Documentation/devicetree/bindings/soc/ti/sci-pm-domain.txt b/Documentation/devicetree/bindings/soc/ti/sci-pm-domain.txt
index f7b00a7..f541d1f 100644
--- a/Documentation/devicetree/bindings/soc/ti/sci-pm-domain.txt
+++ b/Documentation/devicetree/bindings/soc/ti/sci-pm-domain.txt
@@ -19,8 +19,15 @@
Required Properties:
--------------------
- compatible: should be "ti,sci-pm-domain"
-- #power-domain-cells: Must be 1 so that an id can be provided in each
- device node.
+- #power-domain-cells: Can be one of the following:
+ 1: Containing the device id of each node
+ 2: First entry should be device id
+ Second entry should be one of the floowing:
+ TI_SCI_PD_EXCLUSIVE: To allow device to be
+ exclusively controlled by
+ the requesting hosts.
+ TI_SCI_PD_SHARED: To allow device to be shared
+ by multiple hosts.
Example (K2G):
-------------
diff --git a/Documentation/devicetree/bindings/sound/allwinner,sun4i-a10-spdif.yaml b/Documentation/devicetree/bindings/sound/allwinner,sun4i-a10-spdif.yaml
index e0284d8..38d4ced 100644
--- a/Documentation/devicetree/bindings/sound/allwinner,sun4i-a10-spdif.yaml
+++ b/Documentation/devicetree/bindings/sound/allwinner,sun4i-a10-spdif.yaml
@@ -70,7 +70,9 @@
properties:
compatible:
contains:
- const: allwinner,sun8i-h3-spdif
+ enum:
+ - allwinner,sun8i-h3-spdif
+ - allwinner,sun50i-h6-spdif
then:
properties:
diff --git a/Documentation/devicetree/bindings/sound/allwinner,sun50i-a64-codec-analog.yaml b/Documentation/devicetree/bindings/sound/allwinner,sun50i-a64-codec-analog.yaml
new file mode 100644
index 0000000..f290eb7
--- /dev/null
+++ b/Documentation/devicetree/bindings/sound/allwinner,sun50i-a64-codec-analog.yaml
@@ -0,0 +1,39 @@
+# SPDX-License-Identifier: GPL-2.0
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/sound/allwinner,sun50i-a64-codec-analog.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Allwinner A64 Analog Codec Device Tree Bindings
+
+maintainers:
+ - Chen-Yu Tsai <wens@csie.org>
+ - Maxime Ripard <maxime.ripard@bootlin.com>
+
+properties:
+ compatible:
+ const: allwinner,sun50i-a64-codec-analog
+
+ reg:
+ maxItems: 1
+
+ cpvdd-supply:
+ description:
+ Regulator for the headphone amplifier
+
+required:
+ - compatible
+ - reg
+ - cpvdd-supply
+
+additionalProperties: false
+
+examples:
+ - |
+ codec_analog: codec-analog@1f015c0 {
+ compatible = "allwinner,sun50i-a64-codec-analog";
+ reg = <0x01f015c0 0x4>;
+ cpvdd-supply = <®_eldo1>;
+ };
+
+...
diff --git a/Documentation/devicetree/bindings/sound/allwinner,sun8i-a33-codec.yaml b/Documentation/devicetree/bindings/sound/allwinner,sun8i-a33-codec.yaml
new file mode 100644
index 0000000..5e7cc05
--- /dev/null
+++ b/Documentation/devicetree/bindings/sound/allwinner,sun8i-a33-codec.yaml
@@ -0,0 +1,57 @@
+# SPDX-License-Identifier: GPL-2.0
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/sound/allwinner,sun8i-a33-codec.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Allwinner A33 Codec Device Tree Bindings
+
+maintainers:
+ - Chen-Yu Tsai <wens@csie.org>
+ - Maxime Ripard <maxime.ripard@bootlin.com>
+
+properties:
+ "#sound-dai-cells":
+ const: 0
+
+ compatible:
+ const: allwinner,sun8i-a33-codec
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+ clocks:
+ items:
+ - description: Bus Clock
+ - description: Module Clock
+
+ clock-names:
+ items:
+ - const: bus
+ - const: mod
+
+required:
+ - "#sound-dai-cells"
+ - compatible
+ - reg
+ - interrupts
+ - clocks
+ - clock-names
+
+additionalProperties: false
+
+examples:
+ - |
+ audio-codec@1c22e00 {
+ #sound-dai-cells = <0>;
+ compatible = "allwinner,sun8i-a33-codec";
+ reg = <0x01c22e00 0x400>;
+ interrupts = <0 29 4>;
+ clocks = <&ccu 47>, <&ccu 92>;
+ clock-names = "bus", "mod";
+ };
+
+...
diff --git a/Documentation/devicetree/bindings/sound/amlogic,axg-fifo.txt b/Documentation/devicetree/bindings/sound/amlogic,axg-fifo.txt
index 4330fc9..3080979 100644
--- a/Documentation/devicetree/bindings/sound/amlogic,axg-fifo.txt
+++ b/Documentation/devicetree/bindings/sound/amlogic,axg-fifo.txt
@@ -4,13 +4,18 @@
- compatible: 'amlogic,axg-toddr' or
'amlogic,axg-toddr' or
'amlogic,g12a-frddr' or
- 'amlogic,g12a-toddr'
+ 'amlogic,g12a-toddr' or
+ 'amlogic,sm1-frddr' or
+ 'amlogic,sm1-toddr'
- reg: physical base address of the controller and length of memory
mapped region.
- interrupts: interrupt specifier for the fifo.
- clocks: phandle to the fifo peripheral clock provided by the audio
clock controller.
-- resets: phandle to memory ARB line provided by the arb reset controller.
+- resets: list of reset phandle, one for each entry reset-names.
+- reset-names: should contain the following:
+ * "arb" : memory ARB line (required)
+ * "rst" : dedicated device reset line (optional)
- #sound-dai-cells: must be 0.
Example of FRDDR A on the A113 SoC:
diff --git a/Documentation/devicetree/bindings/sound/amlogic,axg-pdm.txt b/Documentation/devicetree/bindings/sound/amlogic,axg-pdm.txt
index 73f473a..7168781 100644
--- a/Documentation/devicetree/bindings/sound/amlogic,axg-pdm.txt
+++ b/Documentation/devicetree/bindings/sound/amlogic,axg-pdm.txt
@@ -2,7 +2,8 @@
Required properties:
- compatible: 'amlogic,axg-pdm' or
- 'amlogic,g12a-pdm'
+ 'amlogic,g12a-pdm' or
+ 'amlogic,sm1-pdm'
- reg: physical base address of the controller and length of memory
mapped region.
- clocks: list of clock phandle, one for each entry clock-names.
@@ -12,6 +13,9 @@
* "sysclk" : dsp system clock
- #sound-dai-cells: must be 0.
+Optional property:
+- resets: phandle to the dedicated reset line of the pdm input.
+
Example of PDM on the A113 SoC:
pdm: audio-controller@ff632000 {
diff --git a/Documentation/devicetree/bindings/sound/amlogic,axg-spdifin.txt b/Documentation/devicetree/bindings/sound/amlogic,axg-spdifin.txt
index 0b82504..df92a4e 100644
--- a/Documentation/devicetree/bindings/sound/amlogic,axg-spdifin.txt
+++ b/Documentation/devicetree/bindings/sound/amlogic,axg-spdifin.txt
@@ -2,7 +2,8 @@
Required properties:
- compatible: 'amlogic,axg-spdifin' or
- 'amlogic,g12a-spdifin'
+ 'amlogic,g12a-spdifin' or
+ 'amlogic,sm1-spdifin'
- interrupts: interrupt specifier for the spdif input.
- clocks: list of clock phandle, one for each entry clock-names.
- clock-names: should contain the following:
@@ -10,6 +11,9 @@
* "refclk" : spdif input reference clock
- #sound-dai-cells: must be 0.
+Optional property:
+- resets: phandle to the dedicated reset line of the spdif input.
+
Example on the A113 SoC:
spdifin: audio-controller@400 {
diff --git a/Documentation/devicetree/bindings/sound/amlogic,axg-spdifout.txt b/Documentation/devicetree/bindings/sound/amlogic,axg-spdifout.txt
index 8261527..28381dd 100644
--- a/Documentation/devicetree/bindings/sound/amlogic,axg-spdifout.txt
+++ b/Documentation/devicetree/bindings/sound/amlogic,axg-spdifout.txt
@@ -2,13 +2,17 @@
Required properties:
- compatible: 'amlogic,axg-spdifout' or
- 'amlogic,g12a-spdifout'
+ 'amlogic,g12a-spdifout' or
+ 'amlogic,sm1-spdifout'
- clocks: list of clock phandle, one for each entry clock-names.
- clock-names: should contain the following:
* "pclk" : peripheral clock.
* "mclk" : master clock
- #sound-dai-cells: must be 0.
+Optional property:
+- resets: phandle to the dedicated reset line of the spdif output.
+
Example on the A113 SoC:
spdifout: audio-controller@480 {
diff --git a/Documentation/devicetree/bindings/sound/amlogic,axg-tdm-formatters.txt b/Documentation/devicetree/bindings/sound/amlogic,axg-tdm-formatters.txt
index 8835a43..5996c0c 100644
--- a/Documentation/devicetree/bindings/sound/amlogic,axg-tdm-formatters.txt
+++ b/Documentation/devicetree/bindings/sound/amlogic,axg-tdm-formatters.txt
@@ -4,7 +4,9 @@
- compatible: 'amlogic,axg-tdmin' or
'amlogic,axg-tdmout' or
'amlogic,g12a-tdmin' or
- 'amlogic,g12a-tdmout'
+ 'amlogic,g12a-tdmout' or
+ 'amlogic,sm1-tdmin' or
+ 'amlogic,sm1-tdmout
- reg: physical base address of the controller and length of memory
mapped region.
- clocks: list of clock phandle, one for each entry clock-names.
diff --git a/Documentation/devicetree/bindings/sound/amlogic,g12a-tohdmitx.txt b/Documentation/devicetree/bindings/sound/amlogic,g12a-tohdmitx.txt
index aa6c355..4e8cd7e 100644
--- a/Documentation/devicetree/bindings/sound/amlogic,g12a-tohdmitx.txt
+++ b/Documentation/devicetree/bindings/sound/amlogic,g12a-tohdmitx.txt
@@ -1,10 +1,12 @@
* Amlogic HDMI Tx control glue
Required properties:
-- compatible: "amlogic,g12a-tohdmitx"
+- compatible: "amlogic,g12a-tohdmitx" or
+ "amlogic,sm1-tohdmitx"
- reg: physical base address of the controller and length of memory
mapped region.
- #sound-dai-cells: should be 1.
+- resets: phandle to the dedicated reset line of the hdmitx glue.
Example on the S905X2 SoC:
@@ -12,6 +14,7 @@
compatible = "amlogic,g12a-tohdmitx";
reg = <0x0 0x744 0x0 0x4>;
#sound-dai-cells = <1>;
+ resets = <&clkc_audio AUD_RESET_TOHDMITX>;
};
Example of an 'amlogic,axg-sound-card':
diff --git a/Documentation/devicetree/bindings/sound/everest,es8316.txt b/Documentation/devicetree/bindings/sound/everest,es8316.txt
new file mode 100644
index 0000000..1bf03c5
--- /dev/null
+++ b/Documentation/devicetree/bindings/sound/everest,es8316.txt
@@ -0,0 +1,23 @@
+Everest ES8316 audio CODEC
+
+This device supports both I2C and SPI.
+
+Required properties:
+
+ - compatible : should be "everest,es8316"
+ - reg : the I2C address of the device for I2C
+
+Optional properties:
+
+ - clocks : a list of phandle, should contain entries for clock-names
+ - clock-names : should include as follows:
+ "mclk" : master clock (MCLK) of the device
+
+Example:
+
+es8316: codec@11 {
+ compatible = "everest,es8316";
+ reg = <0x11>;
+ clocks = <&clks 10>;
+ clock-names = "mclk";
+};
diff --git a/Documentation/devicetree/bindings/sound/fsl,esai.txt b/Documentation/devicetree/bindings/sound/fsl,esai.txt
index 5b99143..0e6e2166 100644
--- a/Documentation/devicetree/bindings/sound/fsl,esai.txt
+++ b/Documentation/devicetree/bindings/sound/fsl,esai.txt
@@ -7,8 +7,11 @@
Required properties:
- - compatible : Compatible list, must contain "fsl,imx35-esai" or
- "fsl,vf610-esai"
+ - compatible : Compatible list, should contain one of the following
+ compatibles:
+ "fsl,imx35-esai",
+ "fsl,vf610-esai",
+ "fsl,imx6ull-esai",
- reg : Offset and length of the register set for the device.
diff --git a/Documentation/devicetree/bindings/sound/fsl-sai.txt b/Documentation/devicetree/bindings/sound/fsl-sai.txt
index 2e726b9..0dc83cc 100644
--- a/Documentation/devicetree/bindings/sound/fsl-sai.txt
+++ b/Documentation/devicetree/bindings/sound/fsl-sai.txt
@@ -8,7 +8,9 @@
Required properties:
- compatible : Compatible list, contains "fsl,vf610-sai",
- "fsl,imx6sx-sai" or "fsl,imx6ul-sai"
+ "fsl,imx6sx-sai", "fsl,imx6ul-sai",
+ "fsl,imx7ulp-sai", "fsl,imx8mq-sai" or
+ "fsl,imx8qm-sai".
- reg : Offset and length of the register set for the device.
diff --git a/Documentation/devicetree/bindings/sound/sun50i-codec-analog.txt b/Documentation/devicetree/bindings/sound/sun50i-codec-analog.txt
deleted file mode 100644
index 056a098..0000000
--- a/Documentation/devicetree/bindings/sound/sun50i-codec-analog.txt
+++ /dev/null
@@ -1,14 +0,0 @@
-* Allwinner A64 Codec Analog Controls
-
-Required properties:
-- compatible: must be one of the following compatibles:
- - "allwinner,sun50i-a64-codec-analog"
-- reg: must contain the registers location and length
-- cpvdd-supply: Regulator supply for the headphone amplifier
-
-Example:
- codec_analog: codec-analog@1f015c0 {
- compatible = "allwinner,sun50i-a64-codec-analog";
- reg = <0x01f015c0 0x4>;
- cpvdd-supply = <®_eldo1>;
- };
diff --git a/Documentation/devicetree/bindings/sound/sun8i-a33-codec.txt b/Documentation/devicetree/bindings/sound/sun8i-a33-codec.txt
deleted file mode 100644
index 2ca3d13..0000000
--- a/Documentation/devicetree/bindings/sound/sun8i-a33-codec.txt
+++ /dev/null
@@ -1,63 +0,0 @@
-Allwinner SUN8I audio codec
-------------------------------------
-
-On Sun8i-A33 SoCs, the audio is separated in different parts:
- - A DAI driver. It uses the "sun4i-i2s" driver which is
- documented here:
- Documentation/devicetree/bindings/sound/sun4i-i2s.txt
- - An analog part of the codec which is handled as PRCM registers.
- See Documentation/devicetree/bindings/sound/sun8i-codec-analog.txt
- - An digital part of the codec which is documented in this current
- binding documentation.
- - And finally, an audio card which links all the above components.
- The simple-audio card will be used.
- See Documentation/devicetree/bindings/sound/simple-card.txt
-
-This bindings documentation exposes Sun8i codec (digital part).
-
-Required properties:
-- compatible: must be "allwinner,sun8i-a33-codec"
-- reg: must contain the registers location and length
-- interrupts: must contain the codec interrupt
-- clocks: a list of phandle + clock-specifer pairs, one for each entry
- in clock-names.
-- clock-names: should contain followings:
- - "bus": the parent APB clock for this controller
- - "mod": the parent module clock
-
-Here is an example to add a sound card and the codec binding on sun8i SoCs that
-are similar to A33 using simple-card:
-
- sound {
- compatible = "simple-audio-card";
- simple-audio-card,name = "sun8i-a33-audio";
- simple-audio-card,format = "i2s";
- simple-audio-card,frame-master = <&link_codec>;
- simple-audio-card,bitclock-master = <&link_codec>;
- simple-audio-card,mclk-fs = <512>;
- simple-audio-card,aux-devs = <&codec_analog>;
- simple-audio-card,routing =
- "Left DAC", "Digital Left DAC",
- "Right DAC", "Digital Right DAC";
-
- simple-audio-card,cpu {
- sound-dai = <&dai>;
- };
-
- link_codec: simple-audio-card,codec {
- sound-dai = <&codec>;
- };
-
- soc@1c00000 {
- [...]
-
- audio-codec@1c22e00 {
- #sound-dai-cells = <0>;
- compatible = "allwinner,sun8i-a33-codec";
- reg = <0x01c22e00 0x400>;
- interrupts = <GIC_SPI 29 IRQ_TYPE_LEVEL_HIGH>;
- clocks = <&ccu CLK_BUS_CODEC>, <&ccu CLK_AC_DIG>;
- clock-names = "bus", "mod";
- };
- };
-
diff --git a/Documentation/devicetree/bindings/sound/uda1334.txt b/Documentation/devicetree/bindings/sound/uda1334.txt
new file mode 100644
index 0000000..f64071b
--- /dev/null
+++ b/Documentation/devicetree/bindings/sound/uda1334.txt
@@ -0,0 +1,17 @@
+UDA1334 audio CODEC
+
+This device uses simple GPIO pins for controlling codec settings.
+
+Required properties:
+
+ - compatible : "nxp,uda1334"
+ - nxp,mute-gpios: a GPIO spec for the MUTE pin.
+ - nxp,deemph-gpios: a GPIO spec for the De-emphasis pin
+
+Example:
+
+uda1334: audio-codec {
+ compatible = "nxp,uda1334";
+ nxp,mute-gpios = <&gpio1 8 GPIO_ACTIVE_LOW>;
+ nxp,deemph-gpios = <&gpio3 3 GPIO_ACTIVE_LOW>;
+};
diff --git a/Documentation/devicetree/bindings/soundwire/soundwire-controller.yaml b/Documentation/devicetree/bindings/soundwire/soundwire-controller.yaml
new file mode 100644
index 0000000..1b43993
--- /dev/null
+++ b/Documentation/devicetree/bindings/soundwire/soundwire-controller.yaml
@@ -0,0 +1,82 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/soundwire/soundwire-controller.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: SoundWire Controller Generic Binding
+
+maintainers:
+ - Srinivas Kandagatla <srinivas.kandagatla@linaro.org>
+ - Vinod Koul <vkoul@kernel.org>
+
+description: |
+ SoundWire busses can be described with a node for the SoundWire controller
+ device and a set of child nodes for each SoundWire slave on the bus.
+
+properties:
+ $nodename:
+ pattern: "^soundwire(@.*)?$"
+
+ "#address-cells":
+ const: 2
+
+ "#size-cells":
+ const: 0
+
+patternProperties:
+ "^.*@[0-9a-f],[0-9a-f]$":
+ type: object
+
+ properties:
+ compatible:
+ pattern: "^sdw[0-9a-f]{1}[0-9a-f]{4}[0-9a-f]{4}[0-9a-f]{2}$"
+ description: Is the textual representation of SoundWire Enumeration
+ address. compatible string should contain SoundWire Version ID,
+ Manufacturer ID, Part ID and Class ID in order and shall be in
+ lower-case hexadecimal with leading zeroes.
+ Valid sizes of these fields are
+ Version ID is 1 nibble, number '0x1' represents SoundWire 1.0
+ and '0x2' represents SoundWire 1.1 and so on.
+ MFD is 4 nibbles
+ PID is 4 nibbles
+ CID is 2 nibbles
+ More Information on detail of encoding of these fields can be
+ found in MIPI Alliance DisCo & SoundWire 1.0 Specifications.
+
+ reg:
+ maxItems: 1
+ description:
+ Link ID followed by Instance ID of SoundWire Device Address.
+
+ required:
+ - compatible
+ - reg
+
+required:
+ - "#address-cells"
+ - "#size-cells"
+
+examples:
+ - |
+ soundwire@c2d0000 {
+ #address-cells = <2>;
+ #size-cells = <0>;
+ reg = <0x0c2d0000 0x2000>;
+
+ speaker@0,1 {
+ compatible = "sdw10217201000";
+ reg = <0 1>;
+ powerdown-gpios = <&wcdpinctrl 2 0>;
+ #thermal-sensor-cells = <0>;
+ };
+
+ speaker@0,2 {
+ compatible = "sdw10217201000";
+ reg = <0 2>;
+ powerdown-gpios = <&wcdpinctrl 2 0>;
+ #thermal-sensor-cells = <0>;
+ };
+ };
+
+...
diff --git a/Documentation/devicetree/bindings/spi/amlogic,meson-gx-spicc.yaml b/Documentation/devicetree/bindings/spi/amlogic,meson-gx-spicc.yaml
new file mode 100644
index 0000000..49b617c
--- /dev/null
+++ b/Documentation/devicetree/bindings/spi/amlogic,meson-gx-spicc.yaml
@@ -0,0 +1,67 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+# Copyright 2019 BayLibre, SAS
+%YAML 1.2
+---
+$id: "http://devicetree.org/schemas/spi/amlogic,meson-gx-spicc.yaml#"
+$schema: "http://devicetree.org/meta-schemas/core.yaml#"
+
+title: Amlogic Meson SPI Communication Controller
+
+maintainers:
+ - Neil Armstrong <narmstrong@baylibre.com>
+
+allOf:
+ - $ref: "spi-controller.yaml#"
+
+description: |
+ The Meson SPICC is a generic SPI controller for general purpose Full-Duplex
+ communications with dedicated 16 words RX/TX PIO FIFOs.
+
+properties:
+ compatible:
+ enum:
+ - amlogic,meson-gx-spicc # SPICC controller on Amlogic GX and compatible SoCs
+ - amlogic,meson-axg-spicc # SPICC controller on Amlogic AXG and compatible SoCs
+
+ interrupts:
+ maxItems: 1
+
+ reg:
+ maxItems: 1
+
+ resets:
+ maxItems: 1
+
+ clocks:
+ maxItems: 1
+
+ clock-names:
+ description: input clock for the baud rate generator
+ items:
+ - const: core
+
+required:
+ - compatible
+ - reg
+ - interrupts
+ - clocks
+ - clock-names
+
+examples:
+ - |
+ spi@c1108d80 {
+ compatible = "amlogic,meson-gx-spicc";
+ reg = <0xc1108d80 0x80>;
+ interrupts = <112>;
+ clocks = <&clk81>;
+ clock-names = "core";
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ ethernet-switch@0 {
+ compatible = "micrel,ks8995m";
+ spi-max-frequency = <1000000>;
+ reg = <0>;
+ };
+ };
+
diff --git a/Documentation/devicetree/bindings/spi/amlogic,meson6-spifc.yaml b/Documentation/devicetree/bindings/spi/amlogic,meson6-spifc.yaml
new file mode 100644
index 0000000..5f33c39
--- /dev/null
+++ b/Documentation/devicetree/bindings/spi/amlogic,meson6-spifc.yaml
@@ -0,0 +1,53 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+# Copyright 2019 BayLibre, SAS
+%YAML 1.2
+---
+$id: "http://devicetree.org/schemas/spi/amlogic,meson6-spifc.yaml#"
+$schema: "http://devicetree.org/meta-schemas/core.yaml#"
+
+title: Amlogic Meson SPI Flash Controller
+
+maintainers:
+ - Neil Armstrong <narmstrong@baylibre.com>
+
+allOf:
+ - $ref: "spi-controller.yaml#"
+
+description: |
+ The Meson SPIFC is a controller optimized for communication with SPI
+ NOR memories, without DMA support and a 64-byte unified transmit /
+ receive buffer.
+
+properties:
+ compatible:
+ enum:
+ - amlogic,meson6-spifc # SPI Flash Controller on Meson6 and compatible SoCs
+ - amlogic,meson-gxbb-spifc # SPI Flash Controller on GXBB and compatible SoCs
+
+ reg:
+ maxItems: 1
+
+ clocks:
+ maxItems: 1
+
+required:
+ - compatible
+ - reg
+ - clocks
+
+examples:
+ - |
+ spi@c1108c80 {
+ compatible = "amlogic,meson6-spifc";
+ reg = <0xc1108c80 0x80>;
+ clocks = <&clk81>;
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ flash: flash@0 {
+ compatible = "spansion,m25p80", "jedec,spi-nor";
+ reg = <0>;
+ spi-max-frequency = <40000000>;
+ };
+ };
+
diff --git a/Documentation/devicetree/bindings/spi/nuvoton,npcm-fiu.txt b/Documentation/devicetree/bindings/spi/nuvoton,npcm-fiu.txt
new file mode 100644
index 0000000..a388005
--- /dev/null
+++ b/Documentation/devicetree/bindings/spi/nuvoton,npcm-fiu.txt
@@ -0,0 +1,47 @@
+* Nuvoton FLASH Interface Unit (FIU) SPI Controller
+
+NPCM FIU supports single, dual and quad communication interface.
+
+The NPCM7XX supports three FIU modules,
+FIU0 and FIUx supports two chip selects,
+FIU3 support four chip select.
+
+Required properties:
+ - compatible : "nuvoton,npcm750-fiu" for the NPCM7XX BMC
+ - #address-cells : should be 1.
+ - #size-cells : should be 0.
+ - reg : the first contains the register location and length,
+ the second contains the memory mapping address and length
+ - reg-names: Should contain the reg names "control" and "memory"
+ - clocks : phandle of FIU reference clock.
+
+Required properties in case the pins can be muxed:
+ - pinctrl-names : a pinctrl state named "default" must be defined.
+ - pinctrl-0 : phandle referencing pin configuration of the device.
+
+Optional property:
+ - nuvoton,spix-mode: enable spix-mode for an expansion bus to an ASIC or CPLD.
+
+Aliases:
+- All the FIU controller nodes should be represented in the aliases node using
+ the following format 'fiu{n}' where n is a unique number for the alias.
+ In the NPCM7XX BMC:
+ fiu0 represent fiu 0 controller
+ fiu1 represent fiu 3 controller
+ fiu2 represent fiu x controller
+
+Example:
+fiu3: spi@c00000000 {
+ compatible = "nuvoton,npcm750-fiu";
+ #address-cells = <1>;
+ #size-cells = <0>;
+ reg = <0xfb000000 0x1000>, <0x80000000 0x10000000>;
+ reg-names = "control", "memory";
+ clocks = <&clk NPCM7XX_CLK_AHB>;
+ pinctrl-names = "default";
+ pinctrl-0 = <&spi3_pins>;
+ spi-nor@0 {
+ ...
+ };
+};
+
diff --git a/Documentation/devicetree/bindings/spi/spi-controller.yaml b/Documentation/devicetree/bindings/spi/spi-controller.yaml
index a02e2fe..7323392 100644
--- a/Documentation/devicetree/bindings/spi/spi-controller.yaml
+++ b/Documentation/devicetree/bindings/spi/spi-controller.yaml
@@ -31,7 +31,7 @@
If that property is used, the number of chip selects will be
increased automatically with max(cs-gpios, hardware chip selects).
- So if, for example, the controller has 2 CS lines, and the
+ So if, for example, the controller has 4 CS lines, and the
cs-gpios looks like this
cs-gpios = <&gpio1 0 0>, <0>, <&gpio1 1 0>, <&gpio1 2 0>;
diff --git a/Documentation/devicetree/bindings/spi/spi-fsl-dspi.txt b/Documentation/devicetree/bindings/spi/spi-fsl-dspi.txt
index dcc7eaa..162e024 100644
--- a/Documentation/devicetree/bindings/spi/spi-fsl-dspi.txt
+++ b/Documentation/devicetree/bindings/spi/spi-fsl-dspi.txt
@@ -6,6 +6,7 @@
or
"fsl,ls2080a-dspi" followed by "fsl,ls2085a-dspi"
"fsl,ls1012a-dspi" followed by "fsl,ls1021a-v1.0-dspi"
+ "fsl,ls1088a-dspi" followed by "fsl,ls1021a-v1.0-dspi"
- reg : Offset and length of the register set for the device
- interrupts : Should contain SPI controller interrupt
- clocks: from common clock binding: handle to dspi clock.
diff --git a/Documentation/devicetree/bindings/spi/spi-fsl-qspi.txt b/Documentation/devicetree/bindings/spi/spi-fsl-qspi.txt
index e8f1d62..69dc5d5 100644
--- a/Documentation/devicetree/bindings/spi/spi-fsl-qspi.txt
+++ b/Documentation/devicetree/bindings/spi/spi-fsl-qspi.txt
@@ -3,9 +3,8 @@
Required properties:
- compatible : Should be "fsl,vf610-qspi", "fsl,imx6sx-qspi",
"fsl,imx7d-qspi", "fsl,imx6ul-qspi",
- "fsl,ls1021a-qspi"
+ "fsl,ls1021a-qspi", "fsl,ls2080a-qspi"
or
- "fsl,ls2080a-qspi" followed by "fsl,ls1021a-qspi",
"fsl,ls1043a-qspi" followed by "fsl,ls1021a-qspi"
- reg : the first contains the register location and length,
the second contains the memory mapping address and length
@@ -34,7 +33,11 @@
clock-names = "qspi_en", "qspi";
flash0: s25fl128s@0 {
- ....
+ #address-cells = <1>;
+ #size-cells = <1>;
+ compatible = "spansion,s25fl128s", "jedec,spi-nor";
+ spi-max-frequency = <50000000>;
+ reg = <0>;
};
};
diff --git a/Documentation/devicetree/bindings/spi/spi-meson.txt b/Documentation/devicetree/bindings/spi/spi-meson.txt
deleted file mode 100644
index b7f5e86..0000000
--- a/Documentation/devicetree/bindings/spi/spi-meson.txt
+++ /dev/null
@@ -1,55 +0,0 @@
-Amlogic Meson SPI controllers
-
-* SPIFC (SPI Flash Controller)
-
-The Meson SPIFC is a controller optimized for communication with SPI
-NOR memories, without DMA support and a 64-byte unified transmit /
-receive buffer.
-
-Required properties:
- - compatible: should be "amlogic,meson6-spifc" or "amlogic,meson-gxbb-spifc"
- - reg: physical base address and length of the controller registers
- - clocks: phandle of the input clock for the baud rate generator
- - #address-cells: should be 1
- - #size-cells: should be 0
-
- spi@c1108c80 {
- compatible = "amlogic,meson6-spifc";
- reg = <0xc1108c80 0x80>;
- clocks = <&clk81>;
- #address-cells = <1>;
- #size-cells = <0>;
- };
-
-* SPICC (SPI Communication Controller)
-
-The Meson SPICC is generic SPI controller for general purpose Full-Duplex
-communications with dedicated 16 words RX/TX PIO FIFOs.
-
-Required properties:
- - compatible: should be:
- "amlogic,meson-gx-spicc" on Amlogic GX and compatible SoCs.
- "amlogic,meson-axg-spicc" on Amlogic AXG and compatible SoCs
- - reg: physical base address and length of the controller registers
- - interrupts: The interrupt specifier
- - clock-names: Must contain "core"
- - clocks: phandle of the input clock for the baud rate generator
- - #address-cells: should be 1
- - #size-cells: should be 0
-
-Optional properties:
- - resets: phandle of the internal reset line
-
-See ../spi/spi-bus.txt for more details on SPI bus master and slave devices
-required and optional properties.
-
-Example :
- spi@c1108d80 {
- compatible = "amlogic,meson-gx-spicc";
- reg = <0xc1108d80 0x80>;
- interrupts = <GIC_SPI 112 IRQ_TYPE_LEVEL_HIGH>;
- clock-names = "core";
- clocks = <&clk81>;
- #address-cells = <1>;
- #size-cells = <0>;
- };
diff --git a/Documentation/devicetree/bindings/spi/spi-mt65xx.txt b/Documentation/devicetree/bindings/spi/spi-mt65xx.txt
index c0f6c8e..3a8079e 100644
--- a/Documentation/devicetree/bindings/spi/spi-mt65xx.txt
+++ b/Documentation/devicetree/bindings/spi/spi-mt65xx.txt
@@ -5,6 +5,7 @@
- mediatek,mt2701-spi: for mt2701 platforms
- mediatek,mt2712-spi: for mt2712 platforms
- mediatek,mt6589-spi: for mt6589 platforms
+ - mediatek,mt6765-spi: for mt6765 platforms
- mediatek,mt7622-spi: for mt7622 platforms
- "mediatek,mt7629-spi", "mediatek,mt7622-spi": for mt7629 platforms
- mediatek,mt8135-spi: for mt8135 platforms
diff --git a/Documentation/devicetree/bindings/spi/spi-sprd-adi.txt b/Documentation/devicetree/bindings/spi/spi-sprd-adi.txt
index 8de589b..2567c82 100644
--- a/Documentation/devicetree/bindings/spi/spi-sprd-adi.txt
+++ b/Documentation/devicetree/bindings/spi/spi-sprd-adi.txt
@@ -25,18 +25,23 @@
ADI registers will make ADI controller registers chaos to lead incorrect results.
Then we need one hardware spinlock to synchronize between the multiple subsystems.
+The new version ADI controller supplies multiple master channels for different
+subsystem accessing, that means no need to add hardware spinlock to synchronize,
+thus change the hardware spinlock support to be optional to keep backward
+compatibility.
+
Required properties:
- compatible: Should be "sprd,sc9860-adi".
- reg: Offset and length of ADI-SPI controller register space.
-- hwlocks: Reference to a phandle of a hwlock provider node.
-- hwlock-names: Reference to hwlock name strings defined in the same order
- as the hwlocks, should be "adi".
- #address-cells: Number of cells required to define a chip select address
on the ADI-SPI bus. Should be set to 1.
- #size-cells: Size of cells required to define a chip select address size
on the ADI-SPI bus. Should be set to 0.
Optional properties:
+- hwlocks: Reference to a phandle of a hwlock provider node.
+- hwlock-names: Reference to hwlock name strings defined in the same order
+ as the hwlocks, should be "adi".
- sprd,hw-channels: This is an array of channel values up to 49 channels.
The first value specifies the hardware channel id which is used to
transfer data triggered by hardware automatically, and the second
diff --git a/Documentation/devicetree/bindings/thermal/qoriq-thermal.txt b/Documentation/devicetree/bindings/thermal/qoriq-thermal.txt
index 04cbb90..28f2cba 100644
--- a/Documentation/devicetree/bindings/thermal/qoriq-thermal.txt
+++ b/Documentation/devicetree/bindings/thermal/qoriq-thermal.txt
@@ -23,6 +23,7 @@
Optional property:
- little-endian : If present, the TMU registers are little endian. If absent,
the default is big endian.
+- clocks : the clock for clocking the TMU silicon.
Example:
diff --git a/Documentation/devicetree/bindings/timer/allwinner,sun4i-a10-timer.yaml b/Documentation/devicetree/bindings/timer/allwinner,sun4i-a10-timer.yaml
new file mode 100644
index 0000000..20adc1c
--- /dev/null
+++ b/Documentation/devicetree/bindings/timer/allwinner,sun4i-a10-timer.yaml
@@ -0,0 +1,102 @@
+# SPDX-License-Identifier: GPL-2.0
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/timer/allwinner,sun4i-a10-timer.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Allwinner A10 Timer Device Tree Bindings
+
+maintainers:
+ - Chen-Yu Tsai <wens@csie.org>
+ - Maxime Ripard <maxime.ripard@bootlin.com>
+
+properties:
+ compatible:
+ enum:
+ - allwinner,sun4i-a10-timer
+ - allwinner,sun8i-a23-timer
+ - allwinner,sun8i-v3s-timer
+ - allwinner,suniv-f1c100s-timer
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ description:
+ List of timers interrupts
+
+ clocks:
+ maxItems: 1
+
+allOf:
+ - if:
+ properties:
+ compatible:
+ items:
+ const: allwinner,sun4i-a10-timer
+
+ then:
+ properties:
+ interrupts:
+ minItems: 6
+ maxItems: 6
+
+ - if:
+ properties:
+ compatible:
+ items:
+ const: allwinner,sun8i-a23-timer
+
+ then:
+ properties:
+ interrupts:
+ minItems: 2
+ maxItems: 2
+
+ - if:
+ properties:
+ compatible:
+ items:
+ const: allwinner,sun8i-v3s-timer
+
+ then:
+ properties:
+ interrupts:
+ minItems: 3
+ maxItems: 3
+
+ - if:
+ properties:
+ compatible:
+ items:
+ const: allwinner,suniv-f1c100s-timer
+
+ then:
+ properties:
+ interrupts:
+ minItems: 3
+ maxItems: 3
+
+required:
+ - compatible
+ - reg
+ - interrupts
+ - clocks
+
+additionalProperties: false
+
+examples:
+ - |
+ timer {
+ compatible = "allwinner,sun4i-a10-timer";
+ reg = <0x01c20c00 0x400>;
+ interrupts = <22>,
+ <23>,
+ <24>,
+ <25>,
+ <67>,
+ <68>;
+ clocks = <&osc>;
+ };
+
+...
diff --git a/Documentation/devicetree/bindings/timer/allwinner,sun4i-timer.txt b/Documentation/devicetree/bindings/timer/allwinner,sun4i-timer.txt
deleted file mode 100644
index 3da9d51..0000000
--- a/Documentation/devicetree/bindings/timer/allwinner,sun4i-timer.txt
+++ /dev/null
@@ -1,19 +0,0 @@
-Allwinner A1X SoCs Timer Controller
-
-Required properties:
-
-- compatible : should be one of the following:
- "allwinner,sun4i-a10-timer"
- "allwinner,suniv-f1c100s-timer"
-- reg : Specifies base physical address and size of the registers.
-- interrupts : The interrupt of the first timer
-- clocks: phandle to the source clock (usually a 24 MHz fixed clock)
-
-Example:
-
-timer {
- compatible = "allwinner,sun4i-a10-timer";
- reg = <0x01c20c00 0x400>;
- interrupts = <22>;
- clocks = <&osc>;
-};
diff --git a/Documentation/devicetree/bindings/timer/allwinner,sun5i-a13-hstimer.txt b/Documentation/devicetree/bindings/timer/allwinner,sun5i-a13-hstimer.txt
deleted file mode 100644
index 2c5c1be..0000000
--- a/Documentation/devicetree/bindings/timer/allwinner,sun5i-a13-hstimer.txt
+++ /dev/null
@@ -1,26 +0,0 @@
-Allwinner SoCs High Speed Timer Controller
-
-Required properties:
-
-- compatible : should be "allwinner,sun5i-a13-hstimer" or
- "allwinner,sun7i-a20-hstimer"
-- reg : Specifies base physical address and size of the registers.
-- interrupts : The interrupts of these timers (2 for the sun5i IP, 4 for the sun7i
- one)
-- clocks: phandle to the source clock (usually the AHB clock)
-
-Optional properties:
-- resets: phandle to a reset controller asserting the timer
-
-Example:
-
-timer@1c60000 {
- compatible = "allwinner,sun7i-a20-hstimer";
- reg = <0x01c60000 0x1000>;
- interrupts = <0 51 1>,
- <0 52 1>,
- <0 53 1>,
- <0 54 1>;
- clocks = <&ahb1_gates 19>;
- resets = <&ahb1rst 19>;
-};
diff --git a/Documentation/devicetree/bindings/timer/allwinner,sun5i-a13-hstimer.yaml b/Documentation/devicetree/bindings/timer/allwinner,sun5i-a13-hstimer.yaml
new file mode 100644
index 0000000..dfa0c41
--- /dev/null
+++ b/Documentation/devicetree/bindings/timer/allwinner,sun5i-a13-hstimer.yaml
@@ -0,0 +1,79 @@
+# SPDX-License-Identifier: GPL-2.0
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/timer/allwinner,sun5i-a13-hstimer.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Allwinner A13 High-Speed Timer Device Tree Bindings
+
+maintainers:
+ - Chen-Yu Tsai <wens@csie.org>
+ - Maxime Ripard <maxime.ripard@bootlin.com>
+
+properties:
+ compatible:
+ oneOf:
+ - const: allwinner,sun5i-a13-hstimer
+ - const: allwinner,sun7i-a20-hstimer
+ - items:
+ - const: allwinner,sun6i-a31-hstimer
+ - const: allwinner,sun7i-a20-hstimer
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ minItems: 2
+ maxItems: 4
+ items:
+ - description: Timer 0 Interrupt
+ - description: Timer 1 Interrupt
+ - description: Timer 2 Interrupt
+ - description: Timer 3 Interrupt
+
+ clocks:
+ maxItems: 1
+
+ resets:
+ maxItems: 1
+
+required:
+ - compatible
+ - reg
+ - interrupts
+ - clocks
+
+if:
+ properties:
+ compatible:
+ items:
+ const: allwinner,sun5i-a13-hstimer
+
+then:
+ properties:
+ interrupts:
+ minItems: 2
+ maxItems: 2
+
+else:
+ properties:
+ interrupts:
+ minItems: 4
+ maxItems: 4
+
+additionalProperties: false
+
+examples:
+ - |
+ timer@1c60000 {
+ compatible = "allwinner,sun7i-a20-hstimer";
+ reg = <0x01c60000 0x1000>;
+ interrupts = <0 51 1>,
+ <0 52 1>,
+ <0 53 1>,
+ <0 54 1>;
+ clocks = <&ahb1_gates 19>;
+ resets = <&ahb1rst 19>;
+ };
+
+...
diff --git a/Documentation/devicetree/bindings/timer/ingenic,tcu.txt b/Documentation/devicetree/bindings/timer/ingenic,tcu.txt
new file mode 100644
index 0000000..5a4b9dd
--- /dev/null
+++ b/Documentation/devicetree/bindings/timer/ingenic,tcu.txt
@@ -0,0 +1,137 @@
+Ingenic JZ47xx SoCs Timer/Counter Unit devicetree bindings
+==========================================================
+
+For a description of the TCU hardware and drivers, have a look at
+Documentation/mips/ingenic-tcu.txt.
+
+Required properties:
+
+- compatible: Must be one of:
+ * ingenic,jz4740-tcu
+ * ingenic,jz4725b-tcu
+ * ingenic,jz4770-tcu
+ followed by "simple-mfd".
+- reg: Should be the offset/length value corresponding to the TCU registers
+- clocks: List of phandle & clock specifiers for clocks external to the TCU.
+ The "pclk", "rtc" and "ext" clocks should be provided. The "tcu" clock
+ should be provided if the SoC has it.
+- clock-names: List of name strings for the external clocks.
+- #clock-cells: Should be <1>;
+ Clock consumers specify this argument to identify a clock. The valid values
+ may be found in <dt-bindings/clock/ingenic,tcu.h>.
+- interrupt-controller : Identifies the node as an interrupt controller
+- #interrupt-cells : Specifies the number of cells needed to encode an
+ interrupt source. The value should be 1.
+- interrupts : Specifies the interrupt the controller is connected to.
+
+Optional properties:
+
+- ingenic,pwm-channels-mask: Bitmask of TCU channels reserved for PWM use.
+ Default value is 0xfc.
+
+
+Children nodes
+==========================================================
+
+
+PWM node:
+---------
+
+Required properties:
+
+- compatible: Must be one of:
+ * ingenic,jz4740-pwm
+ * ingenic,jz4725b-pwm
+- #pwm-cells: Should be 3. See ../pwm/pwm.txt for a description of the cell
+ format.
+- clocks: List of phandle & clock specifiers for the TCU clocks.
+- clock-names: List of name strings for the TCU clocks.
+
+
+Watchdog node:
+--------------
+
+Required properties:
+
+- compatible: Must be "ingenic,jz4740-watchdog"
+- clocks: phandle to the WDT clock
+- clock-names: should be "wdt"
+
+
+OS Timer node:
+---------
+
+Required properties:
+
+- compatible: Must be one of:
+ * ingenic,jz4725b-ost
+ * ingenic,jz4770-ost
+- clocks: phandle to the OST clock
+- clock-names: should be "ost"
+- interrupts : Specifies the interrupt the OST is connected to.
+
+
+Example
+==========================================================
+
+#include <dt-bindings/clock/jz4770-cgu.h>
+#include <dt-bindings/clock/ingenic,tcu.h>
+
+/ {
+ tcu: timer@10002000 {
+ compatible = "ingenic,jz4770-tcu", "simple-mfd";
+ reg = <0x10002000 0x1000>;
+ #address-cells = <1>;
+ #size-cells = <1>;
+ ranges = <0x0 0x10002000 0x1000>;
+
+ #clock-cells = <1>;
+
+ clocks = <&cgu JZ4770_CLK_RTC
+ &cgu JZ4770_CLK_EXT
+ &cgu JZ4770_CLK_PCLK>;
+ clock-names = "rtc", "ext", "pclk";
+
+ interrupt-controller;
+ #interrupt-cells = <1>;
+
+ interrupt-parent = <&intc>;
+ interrupts = <27 26 25>;
+
+ watchdog: watchdog@0 {
+ compatible = "ingenic,jz4740-watchdog";
+ reg = <0x0 0xc>;
+
+ clocks = <&tcu TCU_CLK_WDT>;
+ clock-names = "wdt";
+ };
+
+ pwm: pwm@40 {
+ compatible = "ingenic,jz4740-pwm";
+ reg = <0x40 0x80>;
+
+ #pwm-cells = <3>;
+
+ clocks = <&tcu TCU_CLK_TIMER0
+ &tcu TCU_CLK_TIMER1
+ &tcu TCU_CLK_TIMER2
+ &tcu TCU_CLK_TIMER3
+ &tcu TCU_CLK_TIMER4
+ &tcu TCU_CLK_TIMER5
+ &tcu TCU_CLK_TIMER6
+ &tcu TCU_CLK_TIMER7>;
+ clock-names = "timer0", "timer1", "timer2", "timer3",
+ "timer4", "timer5", "timer6", "timer7";
+ };
+
+ ost: timer@e0 {
+ compatible = "ingenic,jz4770-ost";
+ reg = <0xe0 0x20>;
+
+ clocks = <&tcu TCU_CLK_OST>;
+ clock-names = "ost";
+
+ interrupts = <15>;
+ };
+ };
+};
diff --git a/Documentation/devicetree/bindings/timer/renesas,cmt.txt b/Documentation/devicetree/bindings/timer/renesas,cmt.txt
index c5220bc..a444cfc 100644
--- a/Documentation/devicetree/bindings/timer/renesas,cmt.txt
+++ b/Documentation/devicetree/bindings/timer/renesas,cmt.txt
@@ -12,16 +12,13 @@
Required Properties:
- compatible: must contain one or more of the following:
- - "renesas,cmt-48-sh73a0" for the sh73A0 48-bit CMT
- (CMT1)
- - "renesas,cmt-48-r8a7740" for the r8a7740 48-bit CMT
- (CMT1)
- - "renesas,cmt-48" for all non-second generation 48-bit CMT
- (CMT1 on sh73a0 and r8a7740)
- This is a fallback for the above renesas,cmt-48-* entries.
-
- "renesas,r8a73a4-cmt0" for the 32-bit CMT0 device included in r8a73a4.
- "renesas,r8a73a4-cmt1" for the 48-bit CMT1 device included in r8a73a4.
+ - "renesas,r8a7740-cmt0" for the 32-bit CMT0 device included in r8a7740.
+ - "renesas,r8a7740-cmt1" for the 48-bit CMT1 device included in r8a7740.
+ - "renesas,r8a7740-cmt2" for the 32-bit CMT2 device included in r8a7740.
+ - "renesas,r8a7740-cmt3" for the 32-bit CMT3 device included in r8a7740.
+ - "renesas,r8a7740-cmt4" for the 32-bit CMT4 device included in r8a7740.
- "renesas,r8a7743-cmt0" for the 32-bit CMT0 device included in r8a7743.
- "renesas,r8a7743-cmt1" for the 48-bit CMT1 device included in r8a7743.
- "renesas,r8a7744-cmt0" for the 32-bit CMT0 device included in r8a7744.
@@ -31,29 +28,38 @@
- "renesas,r8a77470-cmt0" for the 32-bit CMT0 device included in r8a77470.
- "renesas,r8a77470-cmt1" for the 48-bit CMT1 device included in r8a77470.
- "renesas,r8a774a1-cmt0" for the 32-bit CMT0 device included in r8a774a1.
- - "renesas,r8a774a1-cmt1" for the 48-bit CMT1 device included in r8a774a1.
+ - "renesas,r8a774a1-cmt1" for the 48-bit CMT devices included in r8a774a1.
- "renesas,r8a774c0-cmt0" for the 32-bit CMT0 device included in r8a774c0.
- - "renesas,r8a774c0-cmt1" for the 48-bit CMT1 device included in r8a774c0.
+ - "renesas,r8a774c0-cmt1" for the 48-bit CMT devices included in r8a774c0.
- "renesas,r8a7790-cmt0" for the 32-bit CMT0 device included in r8a7790.
- "renesas,r8a7790-cmt1" for the 48-bit CMT1 device included in r8a7790.
- "renesas,r8a7791-cmt0" for the 32-bit CMT0 device included in r8a7791.
- "renesas,r8a7791-cmt1" for the 48-bit CMT1 device included in r8a7791.
+ - "renesas,r8a7792-cmt0" for the 32-bit CMT0 device included in r8a7792.
+ - "renesas,r8a7792-cmt1" for the 48-bit CMT1 device included in r8a7792.
- "renesas,r8a7793-cmt0" for the 32-bit CMT0 device included in r8a7793.
- "renesas,r8a7793-cmt1" for the 48-bit CMT1 device included in r8a7793.
- "renesas,r8a7794-cmt0" for the 32-bit CMT0 device included in r8a7794.
- "renesas,r8a7794-cmt1" for the 48-bit CMT1 device included in r8a7794.
- "renesas,r8a7795-cmt0" for the 32-bit CMT0 device included in r8a7795.
- - "renesas,r8a7795-cmt1" for the 48-bit CMT1 device included in r8a7795.
+ - "renesas,r8a7795-cmt1" for the 48-bit CMT devices included in r8a7795.
- "renesas,r8a7796-cmt0" for the 32-bit CMT0 device included in r8a7796.
- - "renesas,r8a7796-cmt1" for the 48-bit CMT1 device included in r8a7796.
+ - "renesas,r8a7796-cmt1" for the 48-bit CMT devices included in r8a7796.
- "renesas,r8a77965-cmt0" for the 32-bit CMT0 device included in r8a77965.
- - "renesas,r8a77965-cmt1" for the 48-bit CMT1 device included in r8a77965.
+ - "renesas,r8a77965-cmt1" for the 48-bit CMT devices included in r8a77965.
- "renesas,r8a77970-cmt0" for the 32-bit CMT0 device included in r8a77970.
- - "renesas,r8a77970-cmt1" for the 48-bit CMT1 device included in r8a77970.
+ - "renesas,r8a77970-cmt1" for the 48-bit CMT devices included in r8a77970.
- "renesas,r8a77980-cmt0" for the 32-bit CMT0 device included in r8a77980.
- - "renesas,r8a77980-cmt1" for the 48-bit CMT1 device included in r8a77980.
+ - "renesas,r8a77980-cmt1" for the 48-bit CMT devices included in r8a77980.
- "renesas,r8a77990-cmt0" for the 32-bit CMT0 device included in r8a77990.
- - "renesas,r8a77990-cmt1" for the 48-bit CMT1 device included in r8a77990.
+ - "renesas,r8a77990-cmt1" for the 48-bit CMT devices included in r8a77990.
+ - "renesas,r8a77995-cmt0" for the 32-bit CMT0 device included in r8a77995.
+ - "renesas,r8a77995-cmt1" for the 48-bit CMT devices included in r8a77995.
+ - "renesas,sh73a0-cmt0" for the 32-bit CMT0 device included in sh73a0.
+ - "renesas,sh73a0-cmt1" for the 48-bit CMT1 device included in sh73a0.
+ - "renesas,sh73a0-cmt2" for the 32-bit CMT2 device included in sh73a0.
+ - "renesas,sh73a0-cmt3" for the 32-bit CMT3 device included in sh73a0.
+ - "renesas,sh73a0-cmt4" for the 32-bit CMT4 device included in sh73a0.
- "renesas,rcar-gen2-cmt0" for 32-bit CMT0 devices included in R-Car Gen2
and RZ/G1.
@@ -63,7 +69,7 @@
listed above.
- "renesas,rcar-gen3-cmt0" for 32-bit CMT0 devices included in R-Car Gen3
and RZ/G2.
- - "renesas,rcar-gen3-cmt1" for 48-bit CMT1 devices included in R-Car Gen3
+ - "renesas,rcar-gen3-cmt1" for 48-bit CMT devices included in R-Car Gen3
and RZ/G2.
These are fallbacks for R-Car Gen3 and RZ/G2 entries listed
above.
diff --git a/Documentation/devicetree/bindings/trivial-devices.yaml b/Documentation/devicetree/bindings/trivial-devices.yaml
index 2e742d3..870ac52 100644
--- a/Documentation/devicetree/bindings/trivial-devices.yaml
+++ b/Documentation/devicetree/bindings/trivial-devices.yaml
@@ -104,6 +104,8 @@
- infineon,slb9645tt
# Infineon TLV493D-A1B6 I2C 3D Magnetic Sensor
- infineon,tlv493d-a1b6
+ # Inspur Power System power supply unit version 1
+ - inspur,ipsps1
# Intersil ISL29028 Ambient Light and Proximity Sensor
- isil,isl29028
# Intersil ISL29030 Ambient Light and Proximity Sensor
diff --git a/Documentation/devicetree/bindings/ufs/ufshcd-pltfrm.txt b/Documentation/devicetree/bindings/ufs/ufshcd-pltfrm.txt
index a747204..d78ef63 100644
--- a/Documentation/devicetree/bindings/ufs/ufshcd-pltfrm.txt
+++ b/Documentation/devicetree/bindings/ufs/ufshcd-pltfrm.txt
@@ -54,6 +54,8 @@
PHY reset from the UFS controller.
- resets : reset node register
- reset-names : describe reset node register, the "rst" corresponds to reset the whole UFS IP.
+- reset-gpios : A phandle and gpio specifier denoting the GPIO connected
+ to the RESET pin of the UFS memory device.
Note: If above properties are not defined it can be assumed that the supply
regulators or clocks are always on.
diff --git a/Documentation/devicetree/bindings/usb/cdns-usb3.txt b/Documentation/devicetree/bindings/usb/cdns-usb3.txt
new file mode 100644
index 0000000..b7dc606
--- /dev/null
+++ b/Documentation/devicetree/bindings/usb/cdns-usb3.txt
@@ -0,0 +1,45 @@
+Binding for the Cadence USBSS-DRD controller
+
+Required properties:
+ - reg: Physical base address and size of the controller's register areas.
+ Controller has 3 different regions:
+ - HOST registers area
+ - DEVICE registers area
+ - OTG/DRD registers area
+ - reg-names - register memory area names:
+ "xhci" - for HOST registers space
+ "dev" - for DEVICE registers space
+ "otg" - for OTG/DRD registers space
+ - compatible: Should contain: "cdns,usb3"
+ - interrupts: Interrupts used by cdns3 controller:
+ "host" - interrupt used by XHCI driver.
+ "peripheral" - interrupt used by device driver
+ "otg" - interrupt used by DRD/OTG part of driver
+
+Optional properties:
+ - maximum-speed : valid arguments are "super-speed", "high-speed" and
+ "full-speed"; refer to usb/generic.txt
+ - dr_mode: Should be one of "host", "peripheral" or "otg".
+ - phys: reference to the USB PHY
+ - phy-names: from the *Generic PHY* bindings;
+ Supported names are:
+ - cdns3,usb2-phy
+ - cdns3,usb3-phy
+
+ - cdns,on-chip-buff-size : size of memory intended as internal memory for endpoints
+ buffers expressed in KB
+
+Example:
+ usb@f3000000 {
+ compatible = "cdns,usb3";
+ interrupts = <GIC_USB_IRQ 7 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_USB_IRQ 7 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_USB_IRQ 8 IRQ_TYPE_LEVEL_HIGH>;
+ interrupt-names = "host", "peripheral", "otg";
+ reg = <0xf3000000 0x10000>, /* memory area for HOST registers */
+ <0xf3010000 0x10000>, /* memory area for DEVICE registers */
+ <0xf3020000 0x10000>; /* memory area for OTG/DRD registers */
+ reg-names = "xhci", "dev", "otg";
+ phys = <&usb2_phy>, <&usb3_phy>;
+ phy-names = "cdns3,usb2-phy", "cnds3,usb3-phy";
+ };
diff --git a/Documentation/devicetree/bindings/usb/ci-hdrc-usb2.txt b/Documentation/devicetree/bindings/usb/ci-hdrc-usb2.txt
index a254386..cfc9f40 100644
--- a/Documentation/devicetree/bindings/usb/ci-hdrc-usb2.txt
+++ b/Documentation/devicetree/bindings/usb/ci-hdrc-usb2.txt
@@ -10,6 +10,7 @@
"fsl,imx6sx-usb"
"fsl,imx6ul-usb"
"fsl,imx7d-usb"
+ "fsl,imx7ulp-usb"
"lsi,zevio-usb"
"qcom,ci-hdrc"
"chipidea,usb2"
diff --git a/Documentation/devicetree/bindings/usb/exynos-usb.txt b/Documentation/devicetree/bindings/usb/exynos-usb.txt
index b7111f4..66c394f 100644
--- a/Documentation/devicetree/bindings/usb/exynos-usb.txt
+++ b/Documentation/devicetree/bindings/usb/exynos-usb.txt
@@ -12,13 +12,11 @@
- interrupts: interrupt number to the cpu.
- clocks: from common clock binding: handle to usb clock.
- clock-names: from common clock binding: Shall be "usbhost".
- - port: if in the SoC there are EHCI phys, they should be listed here.
- One phy per port. Each port should have following entries:
- - reg: port number on EHCI controller, e.g
- On Exynos5250, port 0 is USB2.0 otg phy
- port 1 is HSIC phy0
- port 2 is HSIC phy1
- - phys: from the *Generic PHY* bindings; specifying phy used by port.
+ - phys: from the *Generic PHY* bindings; array specifying phy(s) used
+ by the root port.
+ - phy-names: from the *Generic PHY* bindings; array of the names for
+ each phy for the root ports, must be a subset of the following:
+ "host", "hsic0", "hsic1".
Optional properties:
- samsung,vbus-gpio: if present, specifies the GPIO that
@@ -35,12 +33,8 @@
clocks = <&clock 285>;
clock-names = "usbhost";
- #address-cells = <1>;
- #size-cells = <0>;
- port@0 {
- reg = <0>;
- phys = <&usb2phy 1>;
- };
+ phys = <&usb2phy 1>;
+ phy-names = "host";
};
OHCI
@@ -52,13 +46,11 @@
- interrupts: interrupt number to the cpu.
- clocks: from common clock binding: handle to usb clock.
- clock-names: from common clock binding: Shall be "usbhost".
- - port: if in the SoC there are OHCI phys, they should be listed here.
- One phy per port. Each port should have following entries:
- - reg: port number on OHCI controller, e.g
- On Exynos5250, port 0 is USB2.0 otg phy
- port 1 is HSIC phy0
- port 2 is HSIC phy1
- - phys: from the *Generic PHY* bindings, specifying phy used by port.
+ - phys: from the *Generic PHY* bindings; array specifying phy(s) used
+ by the root port.
+ - phy-names: from the *Generic PHY* bindings; array of the names for
+ each phy for the root ports, must be a subset of the following:
+ "host", "hsic0", "hsic1".
Example:
usb@12120000 {
@@ -69,13 +61,8 @@
clocks = <&clock 285>;
clock-names = "usbhost";
- #address-cells = <1>;
- #size-cells = <0>;
- port@0 {
- reg = <0>;
- phys = <&usb2phy 1>;
- };
-
+ phys = <&usb2phy 1>;
+ phy-names = "host";
};
DWC3
diff --git a/Documentation/devicetree/bindings/usb/fcs,fusb302.txt b/Documentation/devicetree/bindings/usb/fcs,fusb302.txt
index a5d011d..ba2e32d 100644
--- a/Documentation/devicetree/bindings/usb/fcs,fusb302.txt
+++ b/Documentation/devicetree/bindings/usb/fcs,fusb302.txt
@@ -11,13 +11,6 @@
Documentation/devicetree/bindings/connector/usb-connector.txt
-Deprecated properties :
-- fcs,max-sink-microvolt : Maximum sink voltage accepted by port controller
-- fcs,max-sink-microamp : Maximum sink current accepted by port controller
-- fcs,max-sink-microwatt : Maximum sink power accepted by port controller
-- fcs,operating-sink-microwatt : Minimum amount of power accepted from a sink
- when negotiating
-
Example:
diff --git a/Documentation/devicetree/bindings/usb/generic.txt b/Documentation/devicetree/bindings/usb/generic.txt
index 0a74ab8..cf5a1ad 100644
--- a/Documentation/devicetree/bindings/usb/generic.txt
+++ b/Documentation/devicetree/bindings/usb/generic.txt
@@ -30,6 +30,10 @@
optional for OTG device.
- adp-disable: tells OTG controllers we want to disable OTG ADP, ADP is
optional for OTG device.
+ - usb-role-switch: boolean, indicates that the device is capable of assigning
+ the USB data role (USB host or USB device) for a given
+ USB connector, such as Type-C, Type-B(micro).
+ see connector/usb-connector.txt.
This is an attribute to a USB controller such as:
diff --git a/Documentation/devicetree/bindings/usb/mediatek,mtk-xhci.txt b/Documentation/devicetree/bindings/usb/mediatek,mtk-xhci.txt
index 266c2d9..f3e4ace 100644
--- a/Documentation/devicetree/bindings/usb/mediatek,mtk-xhci.txt
+++ b/Documentation/devicetree/bindings/usb/mediatek,mtk-xhci.txt
@@ -30,7 +30,8 @@
the following ones are optional:
"ref_ck": reference clock used by low power mode etc,
"mcu_ck": mcu_bus clock for register access,
- "dma_ck": dma_bus clock for data transfer by DMA
+ "dma_ck": dma_bus clock for data transfer by DMA,
+ "xhci_ck": controller clock
- phys : see usb-hcd.txt in the current directory
@@ -100,7 +101,7 @@
- clocks : a list of phandle + clock-specifier pairs, one for each
entry in clock-names
- clock-names : must contain "sys_ck", and the following ones are optional:
- "ref_ck", "mcu_ck" and "dma_ck"
+ "ref_ck", "mcu_ck" and "dma_ck", "xhci_ck"
Optional properties:
- vbus-supply : reference to the VBUS regulator;
diff --git a/Documentation/devicetree/bindings/usb/mediatek,mtu3.txt b/Documentation/devicetree/bindings/usb/mediatek,mtu3.txt
index 3382b5c..b9af7f5 100644
--- a/Documentation/devicetree/bindings/usb/mediatek,mtu3.txt
+++ b/Documentation/devicetree/bindings/usb/mediatek,mtu3.txt
@@ -16,7 +16,7 @@
entry in clock-names
- clock-names : must contain "sys_ck" for clock of controller,
the following clocks are optional:
- "ref_ck", "mcu_ck" and "dam_ck";
+ "ref_ck", "mcu_ck" and "dma_ck";
- phys : see usb-hcd.txt in the current directory
- dr_mode : should be one of "host", "peripheral" or "otg",
refer to usb/generic.txt
@@ -28,8 +28,13 @@
parent's address space
- extcon : external connector for vbus and idpin changes detection, needed
when supports dual-role mode.
+ it's considered valid for compatibility reasons, not allowed for
+ new bindings, and use "usb-role-switch" property instead.
- vbus-supply : reference to the VBUS regulator, needed when supports
dual-role mode.
+ it's considered valid for compatibility reasons, not allowed for
+ new bindings, and put into a usb-connector node.
+ see connector/usb-connector.txt.
- pinctrl-names : a pinctrl state named "default" is optional, and need be
defined if auto drd switch is enabled, that means the property dr_mode
is set as "otg", and meanwhile the property "mediatek,enable-manual-drd"
@@ -39,6 +44,8 @@
- maximum-speed : valid arguments are "super-speed", "high-speed" and
"full-speed"; refer to usb/generic.txt
+ - usb-role-switch : use USB Role Switch to support dual-role switch, but
+ not extcon; see usb/generic.txt.
- enable-manual-drd : supports manual dual-role switch via debugfs; usually
used when receptacle is TYPE-A and also wants to support dual-role
mode.
@@ -61,6 +68,9 @@
if host mode is enabled. The DT binding details of xhci can be found in:
Documentation/devicetree/bindings/usb/mediatek,mtk-xhci.txt
+The port would be added as subnode if use "usb-role-switch" property.
+ see graph.txt
+
Example:
ssusb: usb@11271000 {
compatible = "mediatek,mt8173-mtu3";
diff --git a/Documentation/devicetree/bindings/usb/renesas,usb3.txt b/Documentation/devicetree/bindings/usb/renesas,usb3-peri.txt
similarity index 100%
rename from Documentation/devicetree/bindings/usb/renesas,usb3.txt
rename to Documentation/devicetree/bindings/usb/renesas,usb3-peri.txt
diff --git a/Documentation/devicetree/bindings/usb/usb-conn-gpio.txt b/Documentation/devicetree/bindings/usb/usb-conn-gpio.txt
new file mode 100644
index 0000000..3d05ae5
--- /dev/null
+++ b/Documentation/devicetree/bindings/usb/usb-conn-gpio.txt
@@ -0,0 +1,30 @@
+USB GPIO Based Connection Detection
+
+This is typically used to switch dual role mode from the USB ID pin connected
+to an input GPIO, and also used to enable/disable device mode from the USB
+Vbus pin connected to an input GPIO.
+
+Required properties:
+- compatible : should include "gpio-usb-b-connector" and "usb-b-connector".
+- id-gpios, vbus-gpios : input gpios, either one of them must be present,
+ and both can be present as well.
+ see connector/usb-connector.txt
+
+Optional properties:
+- vbus-supply : can be present if needed when supports dual role mode.
+ see connector/usb-connector.txt
+
+- Sub-nodes:
+ - port : can be present.
+ see graph.txt
+
+Example:
+
+&mtu3 {
+ connector {
+ compatible = "gpio-usb-b-connector", "usb-b-connector";
+ type = "micro";
+ id-gpios = <&pio 12 GPIO_ACTIVE_HIGH>;
+ vbus-supply = <&usb_p0_vbus>;
+ };
+};
diff --git a/Documentation/devicetree/bindings/usb/usbmisc-imx.txt b/Documentation/devicetree/bindings/usb/usbmisc-imx.txt
index a85a631..b353b98 100644
--- a/Documentation/devicetree/bindings/usb/usbmisc-imx.txt
+++ b/Documentation/devicetree/bindings/usb/usbmisc-imx.txt
@@ -7,6 +7,7 @@
"fsl,vf610-usbmisc" for Vybrid vf610
"fsl,imx6sx-usbmisc" for imx6sx
"fsl,imx7d-usbmisc" for imx7d
+ "fsl,imx7ulp-usbmisc" for imx7ulp
- reg: Should contain registers location and length
Examples:
diff --git a/Documentation/devicetree/bindings/vendor-prefixes.yaml b/Documentation/devicetree/bindings/vendor-prefixes.yaml
index 6992bbb..967e78c 100644
--- a/Documentation/devicetree/bindings/vendor-prefixes.yaml
+++ b/Documentation/devicetree/bindings/vendor-prefixes.yaml
@@ -27,6 +27,8 @@
description: Abilis Systems
"^abracon,.*":
description: Abracon Corporation
+ "^acme,.*":
+ description: Acme Systems srl
"^actions,.*":
description: Actions Semiconductor Co., Ltd.
"^active-semi,.*":
@@ -81,6 +83,8 @@
description: Analogix Semiconductor, Inc.
"^andestech,.*":
description: Andes Technology Corporation
+ "^anvo,.*":
+ description: Anvo-Systems Dresden GmbH
"^apm,.*":
description: Applied Micro Circuits Corporation (APM)
"^aptina,.*":
@@ -269,6 +273,8 @@
description: Emerging Display Technologies
"^eeti,.*":
description: eGalax_eMPIA Technology Inc
+ "^einfochips,.*":
+ description: Einfochips
"^elan,.*":
description: Elan Microelectronic Corp.
"^elgin,.*":
@@ -437,6 +443,8 @@
description: Innolux Corporation
"^inside-secure,.*":
description: INSIDE Secure
+ "^inspur,.*":
+ description: Inspur Corporation
"^intel,.*":
description: Intel Corporation
"^intercontrol,.*":
@@ -503,6 +511,8 @@
description: Lantiq Semiconductor
"^lattice,.*":
description: Lattice Semiconductor
+ "^leez,.*":
+ description: Leez
"^lego,.*":
description: LEGO Systems A/S
"^lemaker,.*":
@@ -511,6 +521,8 @@
description: Lenovo Group Ltd.
"^lg,.*":
description: LG Corporation
+ "^lgphilips,.*":
+ description: LG Display
"^libretech,.*":
description: Shenzhen Libre Technology Co., Ltd
"^licheepi,.*":
@@ -529,6 +541,8 @@
description: Linear Technology Corporation
"^logicpd,.*":
description: Logic PD, Inc.
+ "^longcheer,.*":
+ description: Longcheer Technology (Shanghai) Co., Ltd.
"^lsi,.*":
description: LSI Corp. (LSI Logic)
"^lwn,.*":
@@ -549,6 +563,8 @@
description: mCube
"^meas,.*":
description: Measurement Specialties
+ "^mecer,.*":
+ description: Mustek Limited
"^mediatek,.*":
description: MediaTek Inc.
"^megachips,.*":
@@ -575,6 +591,8 @@
description: Micro Crystal AG
"^micron,.*":
description: Micron Technology Inc.
+ "^microsoft,.*":
+ description: Microsoft Corporation
"^mikroe,.*":
description: MikroElektronika d.o.o.
"^miniand,.*":
@@ -813,6 +831,8 @@
description: Semtech Corporation
"^sensirion,.*":
description: Sensirion AG
+ "^sensortek,.*":
+ description: Sensortek Technology Corporation
"^sff,.*":
description: Small Form Factor Committee
"^sgd,.*":
@@ -933,6 +953,9 @@
description: Tecon Microprocessor Technologies, LLC.
"^topeet,.*":
description: Topeet
+ "^toppoly,.*":
+ description: TPO (deprecated, use tpo)
+ deprecated: true
"^toradex,.*":
description: Toradex AG
"^toshiba,.*":
diff --git a/Documentation/devicetree/bindings/watchdog/allwinner,sun4i-a10-wdt.yaml b/Documentation/devicetree/bindings/watchdog/allwinner,sun4i-a10-wdt.yaml
new file mode 100644
index 0000000..3a54f58
--- /dev/null
+++ b/Documentation/devicetree/bindings/watchdog/allwinner,sun4i-a10-wdt.yaml
@@ -0,0 +1,58 @@
+# SPDX-License-Identifier: GPL-2.0
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/watchdog/allwinner,sun4i-a10-wdt.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Allwinner A10 Watchdog Device Tree Bindings
+
+allOf:
+ - $ref: "watchdog.yaml#"
+
+maintainers:
+ - Chen-Yu Tsai <wens@csie.org>
+ - Maxime Ripard <maxime.ripard@bootlin.com>
+
+properties:
+ compatible:
+ oneOf:
+ - const: allwinner,sun4i-a10-wdt
+ - const: allwinner,sun6i-a31-wdt
+ - items:
+ - const: allwinner,sun50i-a64-wdt
+ - const: allwinner,sun6i-a31-wdt
+ - items:
+ - const: allwinner,sun50i-h6-wdt
+ - const: allwinner,sun6i-a31-wdt
+ - items:
+ - const: allwinner,suniv-f1c100s-wdt
+ - const: allwinner,sun4i-a10-wdt
+
+ reg:
+ maxItems: 1
+
+ clocks:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+required:
+ - compatible
+ - reg
+ - clocks
+ - interrupts
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ wdt: watchdog@1c20c90 {
+ compatible = "allwinner,sun4i-a10-wdt";
+ reg = <0x01c20c90 0x10>;
+ interrupts = <24>;
+ clocks = <&osc24M>;
+ timeout-sec = <10>;
+ };
+
+...
diff --git a/Documentation/devicetree/bindings/watchdog/amlogic,meson-gxbb-wdt.yaml b/Documentation/devicetree/bindings/watchdog/amlogic,meson-gxbb-wdt.yaml
new file mode 100644
index 0000000..d7352f7
--- /dev/null
+++ b/Documentation/devicetree/bindings/watchdog/amlogic,meson-gxbb-wdt.yaml
@@ -0,0 +1,37 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+# Copyright 2019 BayLibre, SAS
+%YAML 1.2
+---
+$id: "http://devicetree.org/schemas/watchdog/amlogic,meson-gxbb-wdt.yaml#"
+$schema: "http://devicetree.org/meta-schemas/core.yaml#"
+
+title: Meson GXBB SoCs Watchdog timer
+
+maintainers:
+ - Neil Armstrong <narmstrong@baylibre.com>
+
+properties:
+ compatible:
+ enum:
+ - amlogic,meson-gxbb-wdt
+
+ reg:
+ maxItems: 1
+
+ clocks:
+ maxItems: 1
+ description:
+ A phandle to the clock of this PHY
+
+required:
+ - compatible
+ - reg
+ - clocks
+
+examples:
+ - |
+ watchdog@98d0 {
+ compatible = "amlogic,meson-gxbb-wdt";
+ reg = <0x98d0 0x10>;
+ clocks = <&xtal>;
+ };
diff --git a/Documentation/devicetree/bindings/watchdog/aspeed-wdt.txt b/Documentation/devicetree/bindings/watchdog/aspeed-wdt.txt
index c5077a1..d78d4a8f 100644
--- a/Documentation/devicetree/bindings/watchdog/aspeed-wdt.txt
+++ b/Documentation/devicetree/bindings/watchdog/aspeed-wdt.txt
@@ -4,6 +4,7 @@
- compatible: must be one of:
- "aspeed,ast2400-wdt"
- "aspeed,ast2500-wdt"
+ - "aspeed,ast2600-wdt"
- reg: physical base address of the controller and length of memory mapped
region
diff --git a/Documentation/devicetree/bindings/watchdog/fsl-imx7ulp-wdt.txt b/Documentation/devicetree/bindings/watchdog/fsl-imx7ulp-wdt.txt
new file mode 100644
index 0000000..f902508
--- /dev/null
+++ b/Documentation/devicetree/bindings/watchdog/fsl-imx7ulp-wdt.txt
@@ -0,0 +1,22 @@
+* Freescale i.MX7ULP Watchdog Timer (WDT) Controller
+
+Required properties:
+- compatible : Should be "fsl,imx7ulp-wdt"
+- reg : Should contain WDT registers location and length
+- interrupts : Should contain WDT interrupt
+- clocks: Should contain a phandle pointing to the gated peripheral clock.
+
+Optional properties:
+- timeout-sec : Contains the watchdog timeout in seconds
+
+Examples:
+
+wdog1: watchdog@403d0000 {
+ compatible = "fsl,imx7ulp-wdt";
+ reg = <0x403d0000 0x10000>;
+ interrupts = <GIC_SPI 55 IRQ_TYPE_LEVEL_HIGH>;
+ clocks = <&pcc2 IMX7ULP_CLK_WDG1>;
+ assigned-clocks = <&pcc2 IMX7ULP_CLK_WDG1>;
+ assigned-clocks-parents = <&scg1 IMX7ULP_CLK_FIRC_BUS_CLK>;
+ timeout-sec = <40>;
+};
diff --git a/Documentation/devicetree/bindings/watchdog/ingenic,jz4740-wdt.txt b/Documentation/devicetree/bindings/watchdog/ingenic,jz4740-wdt.txt
deleted file mode 100644
index ce1cb72..0000000
--- a/Documentation/devicetree/bindings/watchdog/ingenic,jz4740-wdt.txt
+++ /dev/null
@@ -1,17 +0,0 @@
-Ingenic Watchdog Timer (WDT) Controller for JZ4740 & JZ4780
-
-Required properties:
-compatible: "ingenic,jz4740-watchdog" or "ingenic,jz4780-watchdog"
-reg: Register address and length for watchdog registers
-clocks: phandle to the RTC clock
-clock-names: should be "rtc"
-
-Example:
-
-watchdog: jz4740-watchdog@10002000 {
- compatible = "ingenic,jz4740-watchdog";
- reg = <0x10002000 0x10>;
-
- clocks = <&cgu JZ4740_CLK_RTC>;
- clock-names = "rtc";
-};
diff --git a/Documentation/devicetree/bindings/watchdog/meson-gxbb-wdt.txt b/Documentation/devicetree/bindings/watchdog/meson-gxbb-wdt.txt
deleted file mode 100644
index c7fe36f..0000000
--- a/Documentation/devicetree/bindings/watchdog/meson-gxbb-wdt.txt
+++ /dev/null
@@ -1,16 +0,0 @@
-Meson GXBB SoCs Watchdog timer
-
-Required properties:
-
-- compatible : should be "amlogic,meson-gxbb-wdt"
-- reg : Specifies base physical address and size of the registers.
-- clocks : Should be a phandle to the Watchdog clock source, for GXBB the xtal
- is the default clock source.
-
-Example:
-
-wdt: watchdog@98d0 {
- compatible = "amlogic,meson-gxbb-wdt";
- reg = <0 0x98d0 0x0 0x10>;
- clocks = <&xtal>;
-};
diff --git a/Documentation/devicetree/bindings/watchdog/sunxi-wdt.txt b/Documentation/devicetree/bindings/watchdog/sunxi-wdt.txt
deleted file mode 100644
index e65198d..0000000
--- a/Documentation/devicetree/bindings/watchdog/sunxi-wdt.txt
+++ /dev/null
@@ -1,22 +0,0 @@
-Allwinner SoCs Watchdog timer
-
-Required properties:
-
-- compatible : should be one of
- "allwinner,sun4i-a10-wdt"
- "allwinner,sun6i-a31-wdt"
- "allwinner,sun50i-a64-wdt","allwinner,sun6i-a31-wdt"
- "allwinner,sun50i-h6-wdt","allwinner,sun6i-a31-wdt"
- "allwinner,suniv-f1c100s-wdt", "allwinner,sun4i-a10-wdt"
-- reg : Specifies base physical address and size of the registers.
-
-Optional properties:
-- timeout-sec : Contains the watchdog timeout in seconds
-
-Example:
-
-wdt: watchdog@1c20c90 {
- compatible = "allwinner,sun4i-a10-wdt";
- reg = <0x01c20c90 0x10>;
- timeout-sec = <10>;
-};
diff --git a/Documentation/devicetree/bindings/watchdog/watchdog.yaml b/Documentation/devicetree/bindings/watchdog/watchdog.yaml
new file mode 100644
index 0000000..187bf6c
--- /dev/null
+++ b/Documentation/devicetree/bindings/watchdog/watchdog.yaml
@@ -0,0 +1,26 @@
+# SPDX-License-Identifier: GPL-2.0
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/watchdog/watchdog.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Watchdog Generic Bindings
+
+maintainers:
+ - Guenter Roeck <linux@roeck-us.net>
+ - Wim Van Sebroeck <wim@linux-watchdog.org>
+
+description: |
+ This document describes generic bindings which can be used to
+ describe watchdog devices in a device tree.
+
+properties:
+ $nodename:
+ pattern: "^watchdog(@.*|-[0-9a-f])?$"
+
+ timeout-sec:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description:
+ Contains the watchdog timeout in seconds.
+
+...
diff --git a/Documentation/devicetree/writing-schema.md b/Documentation/devicetree/writing-schema.md
deleted file mode 100644
index dc032db..0000000
--- a/Documentation/devicetree/writing-schema.md
+++ /dev/null
@@ -1,130 +0,0 @@
-# Writing DeviceTree Bindings in json-schema
-
-Devicetree bindings are written using json-schema vocabulary. Schema files are
-written in a JSON compatible subset of YAML. YAML is used instead of JSON as it
-considered more human readable and has some advantages such as allowing
-comments (Prefixed with '#').
-
-## Schema Contents
-
-Each schema doc is a structured json-schema which is defined by a set of
-top-level properties. Generally, there is one binding defined per file. The
-top-level json-schema properties used are:
-
-- __$id__ - A json-schema unique identifier string. The string must be a valid
-URI typically containing the binding's filename and path. For DT schema, it must
-begin with "http://devicetree.org/schemas/". The URL is used in constructing
-references to other files specified in schema "$ref" properties. A $ref values
-with a leading '/' will have the hostname prepended. A $ref value a relative
-path or filename only will be prepended with the hostname and path components
-of the current schema file's '$id' value. A URL is used even for local files,
-but there may not actually be files present at those locations.
-
-- __$schema__ - Indicates the meta-schema the schema file adheres to.
-
-- __title__ - A one line description on the contents of the binding schema.
-
-- __maintainers__ - A DT specific property. Contains a list of email address(es)
-for maintainers of this binding.
-
-- __description__ - Optional. A multi-line text block containing any detailed
-information about this binding. It should contain things such as what the block
-or device does, standards the device conforms to, and links to datasheets for
-more information.
-
-- __select__ - Optional. A json-schema used to match nodes for applying the
-schema. By default without 'select', nodes are matched against their possible
-compatible string values or node name. Most bindings should not need select.
-
-- __allOf__ - Optional. A list of other schemas to include. This is used to
-include other schemas the binding conforms to. This may be schemas for a
-particular class of devices such as I2C or SPI controllers.
-
-- __properties__ - A set of sub-schema defining all the DT properties for the
-binding. The exact schema syntax depends on whether properties are known,
-common properties (e.g. 'interrupts') or are binding/vendor specific properties.
-
- A property can also define a child DT node with child properties defined
-under it.
-
- For more details on properties sections, see 'Property Schema' section.
-
-- __patternProperties__ - Optional. Similar to 'properties', but names are regex.
-
-- __required__ - A list of DT properties from the 'properties' section that
-must always be present.
-
-- __examples__ - Optional. A list of one or more DTS hunks implementing the
-binding. Note: YAML doesn't allow leading tabs, so spaces must be used instead.
-
-Unless noted otherwise, all properties are required.
-
-## Property Schema
-
-The 'properties' section of the schema contains all the DT properties for a
-binding. Each property contains a set of constraints using json-schema
-vocabulary for that property. The properties schemas are what is used for
-validation of DT files.
-
-For common properties, only additional constraints not covered by the common
-binding schema need to be defined such as how many values are valid or what
-possible values are valid.
-
-Vendor specific properties will typically need more detailed schema. With the
-exception of boolean properties, they should have a reference to a type in
-schemas/types.yaml. A "description" property is always required.
-
-The Devicetree schemas don't exactly match the YAML encoded DT data produced by
-dtc. They are simplified to make them more compact and avoid a bunch of
-boilerplate. The tools process the schema files to produce the final schema for
-validation. There are currently 2 transformations the tools perform.
-
-The default for arrays in json-schema is they are variable sized and allow more
-entries than explicitly defined. This can be restricted by defining 'minItems',
-'maxItems', and 'additionalItems'. However, for DeviceTree Schemas, a fixed
-size is desired in most cases, so these properties are added based on the
-number of entries in an 'items' list.
-
-The YAML Devicetree format also makes all string values an array and scalar
-values a matrix (in order to define groupings) even when only a single value
-is present. Single entries in schemas are fixed up to match this encoding.
-
-## Testing
-
-### Dependencies
-
-The DT schema project must be installed in order to validate the DT schema
-binding documents and validate DTS files using the DT schema. The DT schema
-project can be installed with pip:
-
-`pip3 install git+https://github.com/devicetree-org/dt-schema.git@master`
-
-dtc must also be built with YAML output support enabled. This requires that
-libyaml and its headers be installed on the host system.
-
-### Running checks
-
-The DT schema binding documents must be validated using the meta-schema (the
-schema for the schema) to ensure they are both valid json-schema and valid
-binding schema. All of the DT binding documents can be validated using the
-`dt_binding_check` target:
-
-`make dt_binding_check`
-
-In order to perform validation of DT source files, use the `dtbs_check` target:
-
-`make dtbs_check`
-
-This will first run the `dt_binding_check` which generates the processed schema.
-
-It is also possible to run checks with a single schema file by setting the
-'DT_SCHEMA_FILES' variable to a specific schema file.
-
-`make dtbs_check DT_SCHEMA_FILES=Documentation/devicetree/bindings/trivial-devices.yaml`
-
-
-## json-schema Resources
-
-[JSON-Schema Specifications](http://json-schema.org/)
-
-[Using JSON Schema Book](http://usingjsonschema.com/)
diff --git a/Documentation/devicetree/writing-schema.rst b/Documentation/devicetree/writing-schema.rst
new file mode 100644
index 0000000..f4a6380
--- /dev/null
+++ b/Documentation/devicetree/writing-schema.rst
@@ -0,0 +1,154 @@
+:orphan:
+
+Writing DeviceTree Bindings in json-schema
+==========================================
+
+Devicetree bindings are written using json-schema vocabulary. Schema files are
+written in a JSON compatible subset of YAML. YAML is used instead of JSON as it
+considered more human readable and has some advantages such as allowing
+comments (Prefixed with '#').
+
+Schema Contents
+---------------
+
+Each schema doc is a structured json-schema which is defined by a set of
+top-level properties. Generally, there is one binding defined per file. The
+top-level json-schema properties used are:
+
+$id
+ A json-schema unique identifier string. The string must be a valid
+ URI typically containing the binding's filename and path. For DT schema, it must
+ begin with "http://devicetree.org/schemas/". The URL is used in constructing
+ references to other files specified in schema "$ref" properties. A $ref values
+ with a leading '/' will have the hostname prepended. A $ref value a relative
+ path or filename only will be prepended with the hostname and path components
+ of the current schema file's '$id' value. A URL is used even for local files,
+ but there may not actually be files present at those locations.
+
+$schema
+ Indicates the meta-schema the schema file adheres to.
+
+title
+ A one line description on the contents of the binding schema.
+
+maintainers
+ A DT specific property. Contains a list of email address(es)
+ for maintainers of this binding.
+
+description
+ Optional. A multi-line text block containing any detailed
+ information about this binding. It should contain things such as what the block
+ or device does, standards the device conforms to, and links to datasheets for
+ more information.
+
+select
+ Optional. A json-schema used to match nodes for applying the
+ schema. By default without 'select', nodes are matched against their possible
+ compatible string values or node name. Most bindings should not need select.
+
+ allOf
+ Optional. A list of other schemas to include. This is used to
+ include other schemas the binding conforms to. This may be schemas for a
+ particular class of devices such as I2C or SPI controllers.
+
+ properties
+ A set of sub-schema defining all the DT properties for the
+ binding. The exact schema syntax depends on whether properties are known,
+ common properties (e.g. 'interrupts') or are binding/vendor specific properties.
+
+A property can also define a child DT node with child properties defined
+under it.
+
+For more details on properties sections, see 'Property Schema' section.
+
+patternProperties
+ Optional. Similar to 'properties', but names are regex.
+
+required
+ A list of DT properties from the 'properties' section that
+ must always be present.
+
+examples
+ Optional. A list of one or more DTS hunks implementing the
+ binding. Note: YAML doesn't allow leading tabs, so spaces must be used instead.
+
+Unless noted otherwise, all properties are required.
+
+Property Schema
+---------------
+
+The 'properties' section of the schema contains all the DT properties for a
+binding. Each property contains a set of constraints using json-schema
+vocabulary for that property. The properties schemas are what is used for
+validation of DT files.
+
+For common properties, only additional constraints not covered by the common
+binding schema need to be defined such as how many values are valid or what
+possible values are valid.
+
+Vendor specific properties will typically need more detailed schema. With the
+exception of boolean properties, they should have a reference to a type in
+schemas/types.yaml. A "description" property is always required.
+
+The Devicetree schemas don't exactly match the YAML encoded DT data produced by
+dtc. They are simplified to make them more compact and avoid a bunch of
+boilerplate. The tools process the schema files to produce the final schema for
+validation. There are currently 2 transformations the tools perform.
+
+The default for arrays in json-schema is they are variable sized and allow more
+entries than explicitly defined. This can be restricted by defining 'minItems',
+'maxItems', and 'additionalItems'. However, for DeviceTree Schemas, a fixed
+size is desired in most cases, so these properties are added based on the
+number of entries in an 'items' list.
+
+The YAML Devicetree format also makes all string values an array and scalar
+values a matrix (in order to define groupings) even when only a single value
+is present. Single entries in schemas are fixed up to match this encoding.
+
+Testing
+-------
+
+Dependencies
+~~~~~~~~~~~~
+
+The DT schema project must be installed in order to validate the DT schema
+binding documents and validate DTS files using the DT schema. The DT schema
+project can be installed with pip::
+
+ pip3 install git+https://github.com/devicetree-org/dt-schema.git@master
+
+dtc must also be built with YAML output support enabled. This requires that
+libyaml and its headers be installed on the host system.
+
+Running checks
+~~~~~~~~~~~~~~
+
+The DT schema binding documents must be validated using the meta-schema (the
+schema for the schema) to ensure they are both valid json-schema and valid
+binding schema. All of the DT binding documents can be validated using the
+``dt_binding_check`` target::
+
+ make dt_binding_check
+
+In order to perform validation of DT source files, use the `dtbs_check` target::
+
+ make dtbs_check
+
+This will first run the `dt_binding_check` which generates the processed schema.
+
+It is also possible to run checks with a single schema file by setting the
+``DT_SCHEMA_FILES`` variable to a specific schema file.
+
+::
+
+ make dt_binding_check DT_SCHEMA_FILES=Documentation/devicetree/bindings/trivial-devices.yaml
+ make dtbs_check DT_SCHEMA_FILES=Documentation/devicetree/bindings/trivial-devices.yaml
+
+
+json-schema Resources
+---------------------
+
+
+`JSON-Schema Specifications <http://json-schema.org/>`_
+
+`Using JSON Schema Book <http://usingjsonschema.com/>`_
diff --git a/Documentation/driver-api/device_link.rst b/Documentation/driver-api/device_link.rst
index ae1e3d0..1b5020e 100644
--- a/Documentation/driver-api/device_link.rst
+++ b/Documentation/driver-api/device_link.rst
@@ -78,8 +78,8 @@
driver is compiled as a module, the device link is added on module load and
orderly deleted on unload. The same restrictions that apply to device link
addition (e.g. exclusion of a parallel suspend/resume transition) apply equally
-to deletion. Device links with ``DL_FLAG_STATELESS`` unset (i.e. managed
-device links) are deleted automatically by the driver core.
+to deletion. Device links managed by the driver core are deleted automatically
+by it.
Several flags may be specified on device link addition, two of which
have already been mentioned above: ``DL_FLAG_STATELESS`` to express that no
diff --git a/Documentation/driver-api/dmaengine/index.rst b/Documentation/driver-api/dmaengine/index.rst
index 3026fa9..b9df904 100644
--- a/Documentation/driver-api/dmaengine/index.rst
+++ b/Documentation/driver-api/dmaengine/index.rst
@@ -47,7 +47,7 @@
pxa_dma
-.. only:: subproject
+.. only:: subproject and html
Indices
=======
diff --git a/Documentation/driver-api/gpio/driver.rst b/Documentation/driver-api/gpio/driver.rst
index 921c71a..3fdb324 100644
--- a/Documentation/driver-api/gpio/driver.rst
+++ b/Documentation/driver-api/gpio/driver.rst
@@ -69,9 +69,9 @@
The code implementing a gpio_chip should support multiple instances of the
controller, preferably using the driver model. That code will configure each
-gpio_chip and issue ``gpiochip_add[_data]()`` or ``devm_gpiochip_add_data()``.
-Removing a GPIO controller should be rare; use ``[devm_]gpiochip_remove()``
-when it is unavoidable.
+gpio_chip and issue gpiochip_add(), gpiochip_add_data(), or
+devm_gpiochip_add_data(). Removing a GPIO controller should be rare; use
+gpiochip_remove() when it is unavoidable.
Often a gpio_chip is part of an instance-specific structure with states not
exposed by the GPIO interfaces, such as addressing, power management, and more.
@@ -259,7 +259,7 @@
cases the GPIO logic is melded with a SoC's primary interrupt controller.
The IRQ portions of the GPIO block are implemented using an irq_chip, using
-the header <linux/irq.h>. So basically such a driver is utilizing two sub-
+the header <linux/irq.h>. So this combined driver is utilizing two sub-
systems simultaneously: gpio and irq.
It is legal for any IRQ consumer to request an IRQ from any irqchip even if it
@@ -391,25 +391,119 @@
----------------------------------------
To help out in handling the set-up and management of GPIO irqchips and the
-associated irqdomain and resource allocation callbacks, the gpiolib has
-some helpers that can be enabled by selecting the GPIOLIB_IRQCHIP Kconfig
-symbol:
+associated irqdomain and resource allocation callbacks. These are activated
+by selecting the Kconfig symbol GPIOLIB_IRQCHIP. If the symbol
+IRQ_DOMAIN_HIERARCHY is also selected, hierarchical helpers will also be
+provided. A big portion of overhead code will be managed by gpiolib,
+under the assumption that your interrupts are 1-to-1-mapped to the
+GPIO line index:
-- gpiochip_irqchip_add(): adds a chained cascaded irqchip to a gpiochip. It
- will pass the struct gpio_chip* for the chip to all IRQ callbacks, so the
- callbacks need to embed the gpio_chip in its state container and obtain a
- pointer to the container using container_of().
- (See Documentation/driver-api/driver-model/design-patterns.rst)
+ GPIO line offset Hardware IRQ
+ 0 0
+ 1 1
+ 2 2
+ ... ...
+ ngpio-1 ngpio-1
+
+If some GPIO lines do not have corresponding IRQs, the bitmask valid_mask
+and the flag need_valid_mask in gpio_irq_chip can be used to mask off some
+lines as invalid for associating with IRQs.
+
+The preferred way to set up the helpers is to fill in the
+struct gpio_irq_chip inside struct gpio_chip before adding the gpio_chip.
+If you do this, the additional irq_chip will be set up by gpiolib at the
+same time as setting up the rest of the GPIO functionality. The following
+is a typical example of a cascaded interrupt handler using gpio_irq_chip:
+
+ /* Typical state container with dynamic irqchip */
+ struct my_gpio {
+ struct gpio_chip gc;
+ struct irq_chip irq;
+ };
+
+ int irq; /* from platform etc */
+ struct my_gpio *g;
+ struct gpio_irq_chip *girq;
+
+ /* Set up the irqchip dynamically */
+ g->irq.name = "my_gpio_irq";
+ g->irq.irq_ack = my_gpio_ack_irq;
+ g->irq.irq_mask = my_gpio_mask_irq;
+ g->irq.irq_unmask = my_gpio_unmask_irq;
+ g->irq.irq_set_type = my_gpio_set_irq_type;
+
+ /* Get a pointer to the gpio_irq_chip */
+ girq = &g->gc.irq;
+ girq->chip = &g->irq;
+ girq->parent_handler = ftgpio_gpio_irq_handler;
+ girq->num_parents = 1;
+ girq->parents = devm_kcalloc(dev, 1, sizeof(*girq->parents),
+ GFP_KERNEL);
+ if (!girq->parents)
+ return -ENOMEM;
+ girq->default_type = IRQ_TYPE_NONE;
+ girq->handler = handle_bad_irq;
+ girq->parents[0] = irq;
+
+ return devm_gpiochip_add_data(dev, &g->gc, g);
+
+The helper support using hierarchical interrupt controllers as well.
+In this case the typical set-up will look like this:
+
+ /* Typical state container with dynamic irqchip */
+ struct my_gpio {
+ struct gpio_chip gc;
+ struct irq_chip irq;
+ struct fwnode_handle *fwnode;
+ };
+
+ int irq; /* from platform etc */
+ struct my_gpio *g;
+ struct gpio_irq_chip *girq;
+
+ /* Set up the irqchip dynamically */
+ g->irq.name = "my_gpio_irq";
+ g->irq.irq_ack = my_gpio_ack_irq;
+ g->irq.irq_mask = my_gpio_mask_irq;
+ g->irq.irq_unmask = my_gpio_unmask_irq;
+ g->irq.irq_set_type = my_gpio_set_irq_type;
+
+ /* Get a pointer to the gpio_irq_chip */
+ girq = &g->gc.irq;
+ girq->chip = &g->irq;
+ girq->default_type = IRQ_TYPE_NONE;
+ girq->handler = handle_bad_irq;
+ girq->fwnode = g->fwnode;
+ girq->parent_domain = parent;
+ girq->child_to_parent_hwirq = my_gpio_child_to_parent_hwirq;
+
+ return devm_gpiochip_add_data(dev, &g->gc, g);
+
+As you can see pretty similar, but you do not supply a parent handler for
+the IRQ, instead a parent irqdomain, an fwnode for the hardware and
+a funcion .child_to_parent_hwirq() that has the purpose of looking up
+the parent hardware irq from a child (i.e. this gpio chip) hardware irq.
+As always it is good to look at examples in the kernel tree for advice
+on how to find the required pieces.
+
+The old way of adding irqchips to gpiochips after registration is also still
+available but we try to move away from this:
+
+- DEPRECATED: gpiochip_irqchip_add(): adds a chained cascaded irqchip to a
+ gpiochip. It will pass the struct gpio_chip* for the chip to all IRQ
+ callbacks, so the callbacks need to embed the gpio_chip in its state
+ container and obtain a pointer to the container using container_of().
+ (See Documentation/driver-model/design-patterns.txt)
- gpiochip_irqchip_add_nested(): adds a nested cascaded irqchip to a gpiochip,
as discussed above regarding different types of cascaded irqchips. The
cascaded irq has to be handled by a threaded interrupt handler.
Apart from that it works exactly like the chained irqchip.
-- gpiochip_set_chained_irqchip(): sets up a chained cascaded irq handler for a
- gpio_chip from a parent IRQ and passes the struct gpio_chip* as handler
- data. Notice that we pass is as the handler data, since the irqchip data is
- likely used by the parent irqchip.
+- DEPRECATED: gpiochip_set_chained_irqchip(): sets up a chained cascaded irq
+ handler for a gpio_chip from a parent IRQ and passes the struct gpio_chip*
+ as handler data. Notice that we pass is as the handler data, since the
+ irqchip data is likely used by the parent irqchip.
- gpiochip_set_nested_irqchip(): sets up a nested cascaded irq handler for a
gpio_chip from a parent IRQ. As the parent IRQ has usually been
@@ -418,11 +512,11 @@
If there is a need to exclude certain GPIO lines from the IRQ domain handled by
these helpers, we can set .irq.need_valid_mask of the gpiochip before
-``[devm_]gpiochip_add_data()`` is called. This allocates an .irq.valid_mask with as
-many bits set as there are GPIO lines in the chip, each bit representing line
-0..n-1. Drivers can exclude GPIO lines by clearing bits from this mask. The mask
-must be filled in before gpiochip_irqchip_add() or gpiochip_irqchip_add_nested()
-is called.
+devm_gpiochip_add_data() or gpiochip_add_data() is called. This allocates an
+.irq.valid_mask with as many bits set as there are GPIO lines in the chip, each
+bit representing line 0..n-1. Drivers can exclude GPIO lines by clearing bits
+from this mask. The mask must be filled in before gpiochip_irqchip_add() or
+gpiochip_irqchip_add_nested() is called.
To use the helpers please keep the following in mind:
diff --git a/Documentation/driver-api/index.rst b/Documentation/driver-api/index.rst
index d12a80f..38e638a 100644
--- a/Documentation/driver-api/index.rst
+++ b/Documentation/driver-api/index.rst
@@ -65,6 +65,7 @@
dmaengine/index
slimbus
soundwire/index
+ thermal/index
fpga/index
acpi/index
backlight/lp855x-driver.rst
@@ -75,6 +76,7 @@
dell_rbu
edid
eisa
+ ipmb
isa
isapnp
generic-counter
diff --git a/Documentation/driver-api/ipmb.rst b/Documentation/driver-api/ipmb.rst
index 7e22651..3ec3bae 100644
--- a/Documentation/driver-api/ipmb.rst
+++ b/Documentation/driver-api/ipmb.rst
@@ -83,7 +83,7 @@
----------------------
After loading the driver, you can instantiate the device as
-described in 'Documentation/i2c/instantiating-devices'.
+described in 'Documentation/i2c/instantiating-devices.rst'.
If you have multiple BMCs, each connected to your Satellite MC via
a different I2C bus, you can instantiate a device for each of
those BMCs.
diff --git a/Documentation/driver-api/mtd/spi-nor.rst b/Documentation/driver-api/mtd/spi-nor.rst
index f5333e3..1f043767 100644
--- a/Documentation/driver-api/mtd/spi-nor.rst
+++ b/Documentation/driver-api/mtd/spi-nor.rst
@@ -59,7 +59,7 @@
The main API is spi_nor_scan(). Before you call the hook, a driver should
initialize the necessary fields for spi_nor{}. Please see
-drivers/mtd/spi-nor/spi-nor.c for detail. Please also refer to fsl-quadspi.c
+drivers/mtd/spi-nor/spi-nor.c for detail. Please also refer to spi-fsl-qspi.c
when you want to write a new driver for a SPI NOR controller.
Another API is spi_nor_restore(), this is used to restore the status of SPI
flash chip such as addressing mode. Call it whenever detach the driver from
diff --git a/Documentation/driver-api/pinctl.rst b/Documentation/driver-api/pinctl.rst
index 2bb1bc4..3d2deaf 100644
--- a/Documentation/driver-api/pinctl.rst
+++ b/Documentation/driver-api/pinctl.rst
@@ -638,8 +638,8 @@
}
static int foo_get_group_pins(struct pinctrl_dev *pctldev, unsigned selector,
- unsigned ** const pins,
- unsigned * const num_pins)
+ const unsigned ** pins,
+ unsigned * num_pins)
{
*pins = (unsigned *) foo_groups[selector].pins;
*num_pins = foo_groups[selector].num_pins;
@@ -705,7 +705,7 @@
{
u8 regbit = (1 << selector + group);
- writeb((readb(MUX)|regbit), MUX)
+ writeb((readb(MUX)|regbit), MUX);
return 0;
}
diff --git a/Documentation/driver-api/serial/n_gsm.rst b/Documentation/driver-api/serial/n_gsm.rst
index f3ad9fd..286e7ff 100644
--- a/Documentation/driver-api/serial/n_gsm.rst
+++ b/Documentation/driver-api/serial/n_gsm.rst
@@ -18,18 +18,22 @@
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,
+4. obtain base gsmtty number for the used serial port,
Major parts of the initialization program :
(a good starting point is util-linux-ng/sys-utils/ldattach.c)::
+ #include <stdio.h>
+ #include <stdint.h>
#include <linux/gsmmux.h>
- #define N_GSM0710 21 /* GSM 0710 Mux */
+ #include <linux/tty.h>
#define DEFAULT_SPEED B115200
#define SERIAL_PORT /dev/ttyS0
int ldisc = N_GSM0710;
struct gsm_config c;
struct termios configuration;
+ uint32_t first;
/* open the serial port connected to the modem */
fd = open(SERIAL_PORT, O_RDWR | O_NOCTTY | O_NDELAY);
@@ -58,21 +62,14 @@
c.mtu = 127;
/* set the new configuration */
ioctl(fd, GSMIOC_SETCONF, &c);
+ /* get first gsmtty device node */
+ ioctl(fd, GSMIOC_GETFIRST, &first);
+ printf("first muxed line: /dev/gsmtty%i\n", first);
/* and wait for ever to keep the line discipline enabled */
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)::
-
- MAJOR=`cat /proc/devices |grep gsmtty | awk '{print $1}`
- for i in `seq 1 4`; do
- mknod /dev/ttygsm$i c $MAJOR $i
- done
-
5. use these devices as plain serial ports.
for example, it's possible:
diff --git a/Documentation/driver-api/sgi-ioc4.rst b/Documentation/driver-api/sgi-ioc4.rst
deleted file mode 100644
index 7270922..0000000
--- a/Documentation/driver-api/sgi-ioc4.rst
+++ /dev/null
@@ -1,49 +0,0 @@
-====================================
-SGI IOC4 PCI (multi function) device
-====================================
-
-The SGI IOC4 PCI device is a bit of a strange beast, so some notes on
-it are in order.
-
-First, even though the IOC4 performs multiple functions, such as an
-IDE controller, a serial controller, a PS/2 keyboard/mouse controller,
-and an external interrupt mechanism, it's not implemented as a
-multifunction device. The consequence of this from a software
-standpoint is that all these functions share a single IRQ, and
-they can't all register to own the same PCI device ID. To make
-matters a bit worse, some of the register blocks (and even registers
-themselves) present in IOC4 are mixed-purpose between these several
-functions, meaning that there's no clear "owning" device driver.
-
-The solution is to organize the IOC4 driver into several independent
-drivers, "ioc4", "sgiioc4", and "ioc4_serial". Note that there is no
-PS/2 controller driver as this functionality has never been wired up
-on a shipping IO card.
-
-ioc4
-====
-This is the core (or shim) driver for IOC4. It is responsible for
-initializing the basic functionality of the chip, and allocating
-the PCI resources that are shared between the IOC4 functions.
-
-This driver also provides registration functions that the other
-IOC4 drivers can call to make their presence known. Each driver
-needs to provide a probe and remove function, which are invoked
-by the core driver at appropriate times. The interface of these
-IOC4 function probe and remove operations isn't precisely the same
-as PCI device probe and remove operations, but is logically the
-same operation.
-
-sgiioc4
-=======
-This is the IDE driver for IOC4. Its name isn't very descriptive
-simply for historical reasons (it used to be the only IOC4 driver
-component). There's not much to say about it other than it hooks
-up to the ioc4 driver via the appropriate registration, probe, and
-remove functions.
-
-ioc4_serial
-===========
-This is the serial driver for IOC4. There's not much to say about it
-other than it hooks up to the ioc4 driver via the appropriate registration,
-probe, and remove functions.
diff --git a/Documentation/driver-api/soundwire/index.rst b/Documentation/driver-api/soundwire/index.rst
index 6db0260..234911a 100644
--- a/Documentation/driver-api/soundwire/index.rst
+++ b/Documentation/driver-api/soundwire/index.rst
@@ -10,7 +10,7 @@
error_handling
locking
-.. only:: subproject
+.. only:: subproject and html
Indices
=======
diff --git a/Documentation/thermal/cpu-cooling-api.rst b/Documentation/driver-api/thermal/cpu-cooling-api.rst
similarity index 100%
rename from Documentation/thermal/cpu-cooling-api.rst
rename to Documentation/driver-api/thermal/cpu-cooling-api.rst
diff --git a/Documentation/thermal/exynos_thermal.rst b/Documentation/driver-api/thermal/exynos_thermal.rst
similarity index 100%
rename from Documentation/thermal/exynos_thermal.rst
rename to Documentation/driver-api/thermal/exynos_thermal.rst
diff --git a/Documentation/thermal/exynos_thermal_emulation.rst b/Documentation/driver-api/thermal/exynos_thermal_emulation.rst
similarity index 100%
rename from Documentation/thermal/exynos_thermal_emulation.rst
rename to Documentation/driver-api/thermal/exynos_thermal_emulation.rst
diff --git a/Documentation/driver-api/thermal/index.rst b/Documentation/driver-api/thermal/index.rst
new file mode 100644
index 0000000..5ba61d1
--- /dev/null
+++ b/Documentation/driver-api/thermal/index.rst
@@ -0,0 +1,18 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+=======
+Thermal
+=======
+
+.. toctree::
+ :maxdepth: 1
+
+ cpu-cooling-api
+ sysfs-api
+ power_allocator
+
+ exynos_thermal
+ exynos_thermal_emulation
+ intel_powerclamp
+ nouveau_thermal
+ x86_pkg_temperature_thermal
diff --git a/Documentation/thermal/intel_powerclamp.rst b/Documentation/driver-api/thermal/intel_powerclamp.rst
similarity index 100%
rename from Documentation/thermal/intel_powerclamp.rst
rename to Documentation/driver-api/thermal/intel_powerclamp.rst
diff --git a/Documentation/thermal/nouveau_thermal.rst b/Documentation/driver-api/thermal/nouveau_thermal.rst
similarity index 100%
rename from Documentation/thermal/nouveau_thermal.rst
rename to Documentation/driver-api/thermal/nouveau_thermal.rst
diff --git a/Documentation/thermal/power_allocator.rst b/Documentation/driver-api/thermal/power_allocator.rst
similarity index 100%
rename from Documentation/thermal/power_allocator.rst
rename to Documentation/driver-api/thermal/power_allocator.rst
diff --git a/Documentation/driver-api/thermal/sysfs-api.rst b/Documentation/driver-api/thermal/sysfs-api.rst
new file mode 100644
index 0000000..fab2c9b
--- /dev/null
+++ b/Documentation/driver-api/thermal/sysfs-api.rst
@@ -0,0 +1,798 @@
+===================================
+Generic Thermal Sysfs driver How To
+===================================
+
+Written by Sujith Thomas <sujith.thomas@intel.com>, Zhang Rui <rui.zhang@intel.com>
+
+Updated: 2 January 2008
+
+Copyright (c) 2008 Intel Corporation
+
+
+0. Introduction
+===============
+
+The generic thermal sysfs provides a set of interfaces for thermal zone
+devices (sensors) and thermal cooling devices (fan, processor...) to register
+with the thermal management solution and to be a part of it.
+
+This how-to focuses on enabling new thermal zone and cooling devices to
+participate in thermal management.
+This solution is platform independent and any type of thermal zone devices
+and cooling devices should be able to make use of the infrastructure.
+
+The main task of the thermal sysfs driver is to expose thermal zone attributes
+as well as cooling device attributes to the user space.
+An intelligent thermal management application can make decisions based on
+inputs from thermal zone attributes (the current temperature and trip point
+temperature) and throttle appropriate devices.
+
+- `[0-*]` denotes any positive number starting from 0
+- `[1-*]` denotes any positive number starting from 1
+
+1. thermal sysfs driver interface functions
+===========================================
+
+1.1 thermal zone device interface
+---------------------------------
+
+ ::
+
+ struct thermal_zone_device
+ *thermal_zone_device_register(char *type,
+ int trips, int mask, void *devdata,
+ struct thermal_zone_device_ops *ops,
+ const struct thermal_zone_params *tzp,
+ int passive_delay, int polling_delay))
+
+ This interface function adds a new thermal zone device (sensor) to
+ /sys/class/thermal folder as `thermal_zone[0-*]`. It tries to bind all the
+ thermal cooling devices registered at the same time.
+
+ type:
+ the thermal zone type.
+ trips:
+ the total number of trip points this thermal zone supports.
+ mask:
+ Bit string: If 'n'th bit is set, then trip point 'n' is writeable.
+ devdata:
+ device private data
+ ops:
+ thermal zone device call-backs.
+
+ .bind:
+ bind the thermal zone device with a thermal cooling device.
+ .unbind:
+ unbind the thermal zone device with a thermal cooling device.
+ .get_temp:
+ get the current temperature of the thermal zone.
+ .set_trips:
+ set the trip points window. Whenever the current temperature
+ is updated, the trip points immediately below and above the
+ current temperature are found.
+ .get_mode:
+ get the current mode (enabled/disabled) of the thermal zone.
+
+ - "enabled" means the kernel thermal management is
+ enabled.
+ - "disabled" will prevent kernel thermal driver action
+ upon trip points so that user applications can take
+ charge of thermal management.
+ .set_mode:
+ set the mode (enabled/disabled) of the thermal zone.
+ .get_trip_type:
+ get the type of certain trip point.
+ .get_trip_temp:
+ get the temperature above which the certain trip point
+ will be fired.
+ .set_emul_temp:
+ set the emulation temperature which helps in debugging
+ different threshold temperature points.
+ tzp:
+ thermal zone platform parameters.
+ passive_delay:
+ number of milliseconds to wait between polls when
+ performing passive cooling.
+ polling_delay:
+ number of milliseconds to wait between polls when checking
+ whether trip points have been crossed (0 for interrupt driven systems).
+
+ ::
+
+ void thermal_zone_device_unregister(struct thermal_zone_device *tz)
+
+ This interface function removes the thermal zone device.
+ It deletes the corresponding entry from /sys/class/thermal folder and
+ unbinds all the thermal cooling devices it uses.
+
+ ::
+
+ struct thermal_zone_device
+ *thermal_zone_of_sensor_register(struct device *dev, int sensor_id,
+ void *data,
+ const struct thermal_zone_of_device_ops *ops)
+
+ This interface adds a new sensor to a DT thermal zone.
+ This function will search the list of thermal zones described in
+ device tree and look for the zone that refer to the sensor device
+ pointed by dev->of_node as temperature providers. For the zone
+ pointing to the sensor node, the sensor will be added to the DT
+ thermal zone device.
+
+ The parameters for this interface are:
+
+ dev:
+ Device node of sensor containing valid node pointer in
+ dev->of_node.
+ sensor_id:
+ a sensor identifier, in case the sensor IP has more
+ than one sensors
+ data:
+ a private pointer (owned by the caller) that will be
+ passed back, when a temperature reading is needed.
+ ops:
+ `struct thermal_zone_of_device_ops *`.
+
+ ============== =======================================
+ get_temp a pointer to a function that reads the
+ sensor temperature. This is mandatory
+ callback provided by sensor driver.
+ set_trips a pointer to a function that sets a
+ temperature window. When this window is
+ left the driver must inform the thermal
+ core via thermal_zone_device_update.
+ get_trend a pointer to a function that reads the
+ sensor temperature trend.
+ set_emul_temp a pointer to a function that sets
+ sensor emulated temperature.
+ ============== =======================================
+
+ The thermal zone temperature is provided by the get_temp() function
+ pointer of thermal_zone_of_device_ops. When called, it will
+ have the private pointer @data back.
+
+ It returns error pointer if fails otherwise valid thermal zone device
+ handle. Caller should check the return handle with IS_ERR() for finding
+ whether success or not.
+
+ ::
+
+ void thermal_zone_of_sensor_unregister(struct device *dev,
+ struct thermal_zone_device *tzd)
+
+ This interface unregisters a sensor from a DT thermal zone which was
+ successfully added by interface thermal_zone_of_sensor_register().
+ This function removes the sensor callbacks and private data from the
+ thermal zone device registered with thermal_zone_of_sensor_register()
+ interface. It will also silent the zone by remove the .get_temp() and
+ get_trend() thermal zone device callbacks.
+
+ ::
+
+ struct thermal_zone_device
+ *devm_thermal_zone_of_sensor_register(struct device *dev,
+ int sensor_id,
+ void *data,
+ const struct thermal_zone_of_device_ops *ops)
+
+ This interface is resource managed version of
+ thermal_zone_of_sensor_register().
+
+ All details of thermal_zone_of_sensor_register() described in
+ section 1.1.3 is applicable here.
+
+ The benefit of using this interface to register sensor is that it
+ is not require to explicitly call thermal_zone_of_sensor_unregister()
+ in error path or during driver unbinding as this is done by driver
+ resource manager.
+
+ ::
+
+ void devm_thermal_zone_of_sensor_unregister(struct device *dev,
+ struct thermal_zone_device *tzd)
+
+ This interface is resource managed version of
+ thermal_zone_of_sensor_unregister().
+ All details of thermal_zone_of_sensor_unregister() described in
+ section 1.1.4 is applicable here.
+ Normally this function will not need to be called and the resource
+ management code will ensure that the resource is freed.
+
+ ::
+
+ int thermal_zone_get_slope(struct thermal_zone_device *tz)
+
+ This interface is used to read the slope attribute value
+ for the thermal zone device, which might be useful for platform
+ drivers for temperature calculations.
+
+ ::
+
+ int thermal_zone_get_offset(struct thermal_zone_device *tz)
+
+ This interface is used to read the offset attribute value
+ for the thermal zone device, which might be useful for platform
+ drivers for temperature calculations.
+
+1.2 thermal cooling device interface
+------------------------------------
+
+
+ ::
+
+ struct thermal_cooling_device
+ *thermal_cooling_device_register(char *name,
+ void *devdata, struct thermal_cooling_device_ops *)
+
+ This interface function adds a new thermal cooling device (fan/processor/...)
+ to /sys/class/thermal/ folder as `cooling_device[0-*]`. It tries to bind itself
+ to all the thermal zone devices registered at the same time.
+
+ name:
+ the cooling device name.
+ devdata:
+ device private data.
+ ops:
+ thermal cooling devices call-backs.
+
+ .get_max_state:
+ get the Maximum throttle state of the cooling device.
+ .get_cur_state:
+ get the Currently requested throttle state of the
+ cooling device.
+ .set_cur_state:
+ set the Current throttle state of the cooling device.
+
+ ::
+
+ void thermal_cooling_device_unregister(struct thermal_cooling_device *cdev)
+
+ This interface function removes the thermal cooling device.
+ It deletes the corresponding entry from /sys/class/thermal folder and
+ unbinds itself from all the thermal zone devices using it.
+
+1.3 interface for binding a thermal zone device with a thermal cooling device
+-----------------------------------------------------------------------------
+
+ ::
+
+ int thermal_zone_bind_cooling_device(struct thermal_zone_device *tz,
+ int trip, struct thermal_cooling_device *cdev,
+ unsigned long upper, unsigned long lower, unsigned int weight);
+
+ This interface function binds a thermal cooling device to a particular trip
+ point of a thermal zone device.
+
+ This function is usually called in the thermal zone device .bind callback.
+
+ tz:
+ the thermal zone device
+ cdev:
+ thermal cooling device
+ trip:
+ indicates which trip point in this thermal zone the cooling device
+ is associated with.
+ upper:
+ the Maximum cooling state for this trip point.
+ THERMAL_NO_LIMIT means no upper limit,
+ and the cooling device can be in max_state.
+ lower:
+ the Minimum cooling state can be used for this trip point.
+ THERMAL_NO_LIMIT means no lower limit,
+ and the cooling device can be in cooling state 0.
+ weight:
+ the influence of this cooling device in this thermal
+ zone. See 1.4.1 below for more information.
+
+ ::
+
+ int thermal_zone_unbind_cooling_device(struct thermal_zone_device *tz,
+ int trip, struct thermal_cooling_device *cdev);
+
+ This interface function unbinds a thermal cooling device from a particular
+ trip point of a thermal zone device. This function is usually called in
+ the thermal zone device .unbind callback.
+
+ tz:
+ the thermal zone device
+ cdev:
+ thermal cooling device
+ trip:
+ indicates which trip point in this thermal zone the cooling device
+ is associated with.
+
+1.4 Thermal Zone Parameters
+---------------------------
+
+ ::
+
+ struct thermal_bind_params
+
+ This structure defines the following parameters that are used to bind
+ a zone with a cooling device for a particular trip point.
+
+ .cdev:
+ The cooling device pointer
+ .weight:
+ The 'influence' of a particular cooling device on this
+ zone. This is relative to the rest of the cooling
+ devices. For example, if all cooling devices have a
+ weight of 1, then they all contribute the same. You can
+ use percentages if you want, but it's not mandatory. A
+ weight of 0 means that this cooling device doesn't
+ contribute to the cooling of this zone unless all cooling
+ devices have a weight of 0. If all weights are 0, then
+ they all contribute the same.
+ .trip_mask:
+ This is a bit mask that gives the binding relation between
+ this thermal zone and cdev, for a particular trip point.
+ If nth bit is set, then the cdev and thermal zone are bound
+ for trip point n.
+ .binding_limits:
+ This is an array of cooling state limits. Must have
+ exactly 2 * thermal_zone.number_of_trip_points. It is an
+ array consisting of tuples <lower-state upper-state> of
+ state limits. Each trip will be associated with one state
+ limit tuple when binding. A NULL pointer means
+ <THERMAL_NO_LIMITS THERMAL_NO_LIMITS> on all trips.
+ These limits are used when binding a cdev to a trip point.
+ .match:
+ This call back returns success(0) if the 'tz and cdev' need to
+ be bound, as per platform data.
+
+ ::
+
+ struct thermal_zone_params
+
+ This structure defines the platform level parameters for a thermal zone.
+ This data, for each thermal zone should come from the platform layer.
+ This is an optional feature where some platforms can choose not to
+ provide this data.
+
+ .governor_name:
+ Name of the thermal governor used for this zone
+ .no_hwmon:
+ a boolean to indicate if the thermal to hwmon sysfs interface
+ is required. when no_hwmon == false, a hwmon sysfs interface
+ will be created. when no_hwmon == true, nothing will be done.
+ In case the thermal_zone_params is NULL, the hwmon interface
+ will be created (for backward compatibility).
+ .num_tbps:
+ Number of thermal_bind_params entries for this zone
+ .tbp:
+ thermal_bind_params entries
+
+2. sysfs attributes structure
+=============================
+
+== ================
+RO read only value
+WO write only value
+RW read/write value
+== ================
+
+Thermal sysfs attributes will be represented under /sys/class/thermal.
+Hwmon sysfs I/F extension is also available under /sys/class/hwmon
+if hwmon is compiled in or built as a module.
+
+Thermal zone device sys I/F, created once it's registered::
+
+ /sys/class/thermal/thermal_zone[0-*]:
+ |---type: Type of the thermal zone
+ |---temp: Current temperature
+ |---mode: Working mode of the thermal zone
+ |---policy: Thermal governor used for this zone
+ |---available_policies: Available thermal governors for this zone
+ |---trip_point_[0-*]_temp: Trip point temperature
+ |---trip_point_[0-*]_type: Trip point type
+ |---trip_point_[0-*]_hyst: Hysteresis value for this trip point
+ |---emul_temp: Emulated temperature set node
+ |---sustainable_power: Sustainable dissipatable power
+ |---k_po: Proportional term during temperature overshoot
+ |---k_pu: Proportional term during temperature undershoot
+ |---k_i: PID's integral term in the power allocator gov
+ |---k_d: PID's derivative term in the power allocator
+ |---integral_cutoff: Offset above which errors are accumulated
+ |---slope: Slope constant applied as linear extrapolation
+ |---offset: Offset constant applied as linear extrapolation
+
+Thermal cooling device sys I/F, created once it's registered::
+
+ /sys/class/thermal/cooling_device[0-*]:
+ |---type: Type of the cooling device(processor/fan/...)
+ |---max_state: Maximum cooling state of the cooling device
+ |---cur_state: Current cooling state of the cooling device
+ |---stats: Directory containing cooling device's statistics
+ |---stats/reset: Writing any value resets the statistics
+ |---stats/time_in_state_ms: Time (msec) spent in various cooling states
+ |---stats/total_trans: Total number of times cooling state is changed
+ |---stats/trans_table: Cooing state transition table
+
+
+Then next two dynamic attributes are created/removed in pairs. They represent
+the relationship between a thermal zone and its associated cooling device.
+They are created/removed for each successful execution of
+thermal_zone_bind_cooling_device/thermal_zone_unbind_cooling_device.
+
+::
+
+ /sys/class/thermal/thermal_zone[0-*]:
+ |---cdev[0-*]: [0-*]th cooling device in current thermal zone
+ |---cdev[0-*]_trip_point: Trip point that cdev[0-*] is associated with
+ |---cdev[0-*]_weight: Influence of the cooling device in
+ this thermal zone
+
+Besides the thermal zone device sysfs I/F and cooling device sysfs I/F,
+the generic thermal driver also creates a hwmon sysfs I/F for each _type_
+of thermal zone device. E.g. the generic thermal driver registers one hwmon
+class device and build the associated hwmon sysfs I/F for all the registered
+ACPI thermal zones.
+
+::
+
+ /sys/class/hwmon/hwmon[0-*]:
+ |---name: The type of the thermal zone devices
+ |---temp[1-*]_input: The current temperature of thermal zone [1-*]
+ |---temp[1-*]_critical: The critical trip point of thermal zone [1-*]
+
+Please read Documentation/hwmon/sysfs-interface.rst for additional information.
+
+Thermal zone attributes
+-----------------------
+
+type
+ Strings which represent the thermal zone type.
+ This is given by thermal zone driver as part of registration.
+ E.g: "acpitz" indicates it's an ACPI thermal device.
+ In order to keep it consistent with hwmon sys attribute; this should
+ be a short, lowercase string, not containing spaces nor dashes.
+ RO, Required
+
+temp
+ Current temperature as reported by thermal zone (sensor).
+ Unit: millidegree Celsius
+ RO, Required
+
+mode
+ One of the predefined values in [enabled, disabled].
+ This file gives information about the algorithm that is currently
+ managing the thermal zone. It can be either default kernel based
+ algorithm or user space application.
+
+ enabled
+ enable Kernel Thermal management.
+ disabled
+ Preventing kernel thermal zone driver actions upon
+ trip points so that user application can take full
+ charge of the thermal management.
+
+ RW, Optional
+
+policy
+ One of the various thermal governors used for a particular zone.
+
+ RW, Required
+
+available_policies
+ Available thermal governors which can be used for a particular zone.
+
+ RO, Required
+
+`trip_point_[0-*]_temp`
+ The temperature above which trip point will be fired.
+
+ Unit: millidegree Celsius
+
+ RO, Optional
+
+`trip_point_[0-*]_type`
+ Strings which indicate the type of the trip point.
+
+ E.g. it can be one of critical, hot, passive, `active[0-*]` for ACPI
+ thermal zone.
+
+ RO, Optional
+
+`trip_point_[0-*]_hyst`
+ The hysteresis value for a trip point, represented as an integer
+ Unit: Celsius
+ RW, Optional
+
+`cdev[0-*]`
+ Sysfs link to the thermal cooling device node where the sys I/F
+ for cooling device throttling control represents.
+
+ RO, Optional
+
+`cdev[0-*]_trip_point`
+ The trip point in this thermal zone which `cdev[0-*]` is associated
+ with; -1 means the cooling device is not associated with any trip
+ point.
+
+ RO, Optional
+
+`cdev[0-*]_weight`
+ The influence of `cdev[0-*]` in this thermal zone. This value
+ is relative to the rest of cooling devices in the thermal
+ zone. For example, if a cooling device has a weight double
+ than that of other, it's twice as effective in cooling the
+ thermal zone.
+
+ RW, Optional
+
+passive
+ Attribute is only present for zones in which the passive cooling
+ policy is not supported by native thermal driver. Default is zero
+ and can be set to a temperature (in millidegrees) to enable a
+ passive trip point for the zone. Activation is done by polling with
+ an interval of 1 second.
+
+ Unit: millidegrees Celsius
+
+ Valid values: 0 (disabled) or greater than 1000
+
+ RW, Optional
+
+emul_temp
+ Interface to set the emulated temperature method in thermal zone
+ (sensor). After setting this temperature, the thermal zone may pass
+ this temperature to platform emulation function if registered or
+ cache it locally. This is useful in debugging different temperature
+ threshold and its associated cooling action. This is write only node
+ and writing 0 on this node should disable emulation.
+ Unit: millidegree Celsius
+
+ WO, Optional
+
+ WARNING:
+ Be careful while enabling this option on production systems,
+ because userland can easily disable the thermal policy by simply
+ flooding this sysfs node with low temperature values.
+
+sustainable_power
+ An estimate of the sustained power that can be dissipated by
+ the thermal zone. Used by the power allocator governor. For
+ more information see Documentation/driver-api/thermal/power_allocator.rst
+
+ Unit: milliwatts
+
+ RW, Optional
+
+k_po
+ The proportional term of the power allocator governor's PID
+ controller during temperature overshoot. Temperature overshoot
+ is when the current temperature is above the "desired
+ temperature" trip point. For more information see
+ Documentation/driver-api/thermal/power_allocator.rst
+
+ RW, Optional
+
+k_pu
+ The proportional term of the power allocator governor's PID
+ controller during temperature undershoot. Temperature undershoot
+ is when the current temperature is below the "desired
+ temperature" trip point. For more information see
+ Documentation/driver-api/thermal/power_allocator.rst
+
+ RW, Optional
+
+k_i
+ The integral term of the power allocator governor's PID
+ controller. This term allows the PID controller to compensate
+ for long term drift. For more information see
+ Documentation/driver-api/thermal/power_allocator.rst
+
+ RW, Optional
+
+k_d
+ The derivative term of the power allocator governor's PID
+ controller. For more information see
+ Documentation/driver-api/thermal/power_allocator.rst
+
+ RW, Optional
+
+integral_cutoff
+ Temperature offset from the desired temperature trip point
+ above which the integral term of the power allocator
+ governor's PID controller starts accumulating errors. For
+ example, if integral_cutoff is 0, then the integral term only
+ accumulates error when temperature is above the desired
+ temperature trip point. For more information see
+ Documentation/driver-api/thermal/power_allocator.rst
+
+ Unit: millidegree Celsius
+
+ RW, Optional
+
+slope
+ The slope constant used in a linear extrapolation model
+ to determine a hotspot temperature based off the sensor's
+ raw readings. It is up to the device driver to determine
+ the usage of these values.
+
+ RW, Optional
+
+offset
+ The offset constant used in a linear extrapolation model
+ to determine a hotspot temperature based off the sensor's
+ raw readings. It is up to the device driver to determine
+ the usage of these values.
+
+ RW, Optional
+
+Cooling device attributes
+-------------------------
+
+type
+ String which represents the type of device, e.g:
+
+ - for generic ACPI: should be "Fan", "Processor" or "LCD"
+ - for memory controller device on intel_menlow platform:
+ should be "Memory controller".
+
+ RO, Required
+
+max_state
+ The maximum permissible cooling state of this cooling device.
+
+ RO, Required
+
+cur_state
+ The current cooling state of this cooling device.
+ The value can any integer numbers between 0 and max_state:
+
+ - cur_state == 0 means no cooling
+ - cur_state == max_state means the maximum cooling.
+
+ RW, Required
+
+stats/reset
+ Writing any value resets the cooling device's statistics.
+ WO, Required
+
+stats/time_in_state_ms:
+ The amount of time spent by the cooling device in various cooling
+ states. The output will have "<state> <time>" pair in each line, which
+ will mean this cooling device spent <time> msec of time at <state>.
+ Output will have one line for each of the supported states. usertime
+ units here is 10mS (similar to other time exported in /proc).
+ RO, Required
+
+
+stats/total_trans:
+ A single positive value showing the total number of times the state of a
+ cooling device is changed.
+
+ RO, Required
+
+stats/trans_table:
+ This gives fine grained information about all the cooling state
+ transitions. The cat output here is a two dimensional matrix, where an
+ entry <i,j> (row i, column j) represents the number of transitions from
+ State_i to State_j. If the transition table is bigger than PAGE_SIZE,
+ reading this will return an -EFBIG error.
+ RO, Required
+
+3. A simple implementation
+==========================
+
+ACPI thermal zone may support multiple trip points like critical, hot,
+passive, active. If an ACPI thermal zone supports critical, passive,
+active[0] and active[1] at the same time, it may register itself as a
+thermal_zone_device (thermal_zone1) with 4 trip points in all.
+It has one processor and one fan, which are both registered as
+thermal_cooling_device. Both are considered to have the same
+effectiveness in cooling the thermal zone.
+
+If the processor is listed in _PSL method, and the fan is listed in _AL0
+method, the sys I/F structure will be built like this::
+
+ /sys/class/thermal:
+ |thermal_zone1:
+ |---type: acpitz
+ |---temp: 37000
+ |---mode: enabled
+ |---policy: step_wise
+ |---available_policies: step_wise fair_share
+ |---trip_point_0_temp: 100000
+ |---trip_point_0_type: critical
+ |---trip_point_1_temp: 80000
+ |---trip_point_1_type: passive
+ |---trip_point_2_temp: 70000
+ |---trip_point_2_type: active0
+ |---trip_point_3_temp: 60000
+ |---trip_point_3_type: active1
+ |---cdev0: --->/sys/class/thermal/cooling_device0
+ |---cdev0_trip_point: 1 /* cdev0 can be used for passive */
+ |---cdev0_weight: 1024
+ |---cdev1: --->/sys/class/thermal/cooling_device3
+ |---cdev1_trip_point: 2 /* cdev1 can be used for active[0]*/
+ |---cdev1_weight: 1024
+
+ |cooling_device0:
+ |---type: Processor
+ |---max_state: 8
+ |---cur_state: 0
+
+ |cooling_device3:
+ |---type: Fan
+ |---max_state: 2
+ |---cur_state: 0
+
+ /sys/class/hwmon:
+ |hwmon0:
+ |---name: acpitz
+ |---temp1_input: 37000
+ |---temp1_crit: 100000
+
+4. Event Notification
+=====================
+
+The framework includes a simple notification mechanism, in the form of a
+netlink event. Netlink socket initialization is done during the _init_
+of the framework. Drivers which intend to use the notification mechanism
+just need to call thermal_generate_netlink_event() with two arguments viz
+(originator, event). The originator is a pointer to struct thermal_zone_device
+from where the event has been originated. An integer which represents the
+thermal zone device will be used in the message to identify the zone. The
+event will be one of:{THERMAL_AUX0, THERMAL_AUX1, THERMAL_CRITICAL,
+THERMAL_DEV_FAULT}. Notification can be sent when the current temperature
+crosses any of the configured thresholds.
+
+5. Export Symbol APIs
+=====================
+
+5.1. get_tz_trend
+-----------------
+
+This function returns the trend of a thermal zone, i.e the rate of change
+of temperature of the thermal zone. Ideally, the thermal sensor drivers
+are supposed to implement the callback. If they don't, the thermal
+framework calculated the trend by comparing the previous and the current
+temperature values.
+
+5.2. get_thermal_instance
+-------------------------
+
+This function returns the thermal_instance corresponding to a given
+{thermal_zone, cooling_device, trip_point} combination. Returns NULL
+if such an instance does not exist.
+
+5.3. thermal_notify_framework
+-----------------------------
+
+This function handles the trip events from sensor drivers. It starts
+throttling the cooling devices according to the policy configured.
+For CRITICAL and HOT trip points, this notifies the respective drivers,
+and does actual throttling for other trip points i.e ACTIVE and PASSIVE.
+The throttling policy is based on the configured platform data; if no
+platform data is provided, this uses the step_wise throttling policy.
+
+5.4. thermal_cdev_update
+------------------------
+
+This function serves as an arbitrator to set the state of a cooling
+device. It sets the cooling device to the deepest cooling state if
+possible.
+
+6. thermal_emergency_poweroff
+=============================
+
+On an event of critical trip temperature crossing. Thermal framework
+allows the system to shutdown gracefully by calling orderly_poweroff().
+In the event of a failure of orderly_poweroff() to shut down the system
+we are in danger of keeping the system alive at undesirably high
+temperatures. To mitigate this high risk scenario we program a work
+queue to fire after a pre-determined number of seconds to start
+an emergency shutdown of the device using the kernel_power_off()
+function. In case kernel_power_off() fails then finally
+emergency_restart() is called in the worst case.
+
+The delay should be carefully profiled so as to give adequate time for
+orderly_poweroff(). In case of failure of an orderly_poweroff() the
+emergency poweroff kicks in after the delay has elapsed and shuts down
+the system.
+
+If set to 0 emergency poweroff will not be supported. So a carefully
+profiled non-zero positive value is a must for emergerncy poweroff to be
+triggered.
diff --git a/Documentation/driver-api/thermal/x86_pkg_temperature_thermal.rst b/Documentation/driver-api/thermal/x86_pkg_temperature_thermal.rst
new file mode 100644
index 0000000..2ac42cc
--- /dev/null
+++ b/Documentation/driver-api/thermal/x86_pkg_temperature_thermal.rst
@@ -0,0 +1,55 @@
+===================================
+Kernel driver: x86_pkg_temp_thermal
+===================================
+
+Supported chips:
+
+* x86: with package level thermal management
+
+(Verify using: CPUID.06H:EAX[bit 6] =1)
+
+Authors: Srinivas Pandruvada <srinivas.pandruvada@linux.intel.com>
+
+Reference
+---------
+
+Intel® 64 and IA-32 Architectures Software Developer’s Manual (Jan, 2013):
+Chapter 14.6: PACKAGE LEVEL THERMAL MANAGEMENT
+
+Description
+-----------
+
+This driver register CPU digital temperature package level sensor as a thermal
+zone with maximum two user mode configurable trip points. Number of trip points
+depends on the capability of the package. Once the trip point is violated,
+user mode can receive notification via thermal notification mechanism and can
+take any action to control temperature.
+
+
+Threshold management
+--------------------
+Each package will register as a thermal zone under /sys/class/thermal.
+
+Example::
+
+ /sys/class/thermal/thermal_zone1
+
+This contains two trip points:
+
+- trip_point_0_temp
+- trip_point_1_temp
+
+User can set any temperature between 0 to TJ-Max temperature. Temperature units
+are in milli-degree Celsius. Refer to "Documentation/driver-api/thermal/sysfs-api.rst" for
+thermal sys-fs details.
+
+Any value other than 0 in these trip points, can trigger thermal notifications.
+Setting 0, stops sending thermal notifications.
+
+Thermal notifications:
+To get kobject-uevent notifications, set the thermal zone
+policy to "user_space".
+
+For example::
+
+ echo -n "user_space" > policy
diff --git a/Documentation/driver-api/uio-howto.rst b/Documentation/driver-api/uio-howto.rst
index 8fecfa1..84091cd 100644
--- a/Documentation/driver-api/uio-howto.rst
+++ b/Documentation/driver-api/uio-howto.rst
@@ -408,6 +408,13 @@
internal registers to create the kernel part of the driver. All you need
to know is the irq number of the pin the chip is connected to.
+When used in a device-tree enabled system, the driver needs to be
+probed with the ``"of_id"`` module parameter set to the ``"compatible"``
+string of the node the driver is supposed to handle. By default, the
+node's name (without the unit address) is exposed as name for the
+UIO device in userspace. To set a custom name, a property named
+``"linux,uio-name"`` may be specified in the DT node.
+
Using uio_dmem_genirq for platform devices
------------------------------------------
diff --git a/Documentation/features/core/jump-labels/arch-support.txt b/Documentation/features/core/jump-labels/arch-support.txt
index 7fc2e24..cae7be2 100644
--- a/Documentation/features/core/jump-labels/arch-support.txt
+++ b/Documentation/features/core/jump-labels/arch-support.txt
@@ -21,7 +21,7 @@
| nds32: | TODO |
| nios2: | TODO |
| openrisc: | TODO |
- | parisc: | TODO |
+ | parisc: | ok |
| powerpc: | ok |
| riscv: | TODO |
| s390: | ok |
diff --git a/Documentation/features/debug/kprobes-on-ftrace/arch-support.txt b/Documentation/features/debug/kprobes-on-ftrace/arch-support.txt
index 68f2669..4fae046 100644
--- a/Documentation/features/debug/kprobes-on-ftrace/arch-support.txt
+++ b/Documentation/features/debug/kprobes-on-ftrace/arch-support.txt
@@ -21,7 +21,7 @@
| nds32: | TODO |
| nios2: | TODO |
| openrisc: | TODO |
- | parisc: | TODO |
+ | parisc: | ok |
| powerpc: | ok |
| riscv: | TODO |
| s390: | TODO |
diff --git a/Documentation/features/locking/queued-rwlocks/arch-support.txt b/Documentation/features/locking/queued-rwlocks/arch-support.txt
index c683da1..ee92274 100644
--- a/Documentation/features/locking/queued-rwlocks/arch-support.txt
+++ b/Documentation/features/locking/queued-rwlocks/arch-support.txt
@@ -30,5 +30,5 @@
| um: | TODO |
| unicore32: | TODO |
| x86: | ok |
- | xtensa: | TODO |
+ | xtensa: | ok |
-----------------------
diff --git a/Documentation/features/locking/queued-spinlocks/arch-support.txt b/Documentation/features/locking/queued-spinlocks/arch-support.txt
index e3080b8..c52116c 100644
--- a/Documentation/features/locking/queued-spinlocks/arch-support.txt
+++ b/Documentation/features/locking/queued-spinlocks/arch-support.txt
@@ -9,7 +9,7 @@
| alpha: | TODO |
| arc: | TODO |
| arm: | TODO |
- | arm64: | TODO |
+ | arm64: | ok |
| c6x: | TODO |
| csky: | TODO |
| h8300: | TODO |
@@ -30,5 +30,5 @@
| um: | TODO |
| unicore32: | TODO |
| x86: | ok |
- | xtensa: | TODO |
+ | xtensa: | ok |
-----------------------
diff --git a/Documentation/features/locking/rwsem-optimized/arch-support.txt b/Documentation/features/locking/rwsem-optimized/arch-support.txt
deleted file mode 100644
index 7521d75..0000000
--- a/Documentation/features/locking/rwsem-optimized/arch-support.txt
+++ /dev/null
@@ -1,34 +0,0 @@
-#
-# Feature name: rwsem-optimized
-# Kconfig: !RWSEM_GENERIC_SPINLOCK
-# description: arch provides optimized rwsem APIs
-#
- -----------------------
- | arch |status|
- -----------------------
- | alpha: | ok |
- | arc: | TODO |
- | arm: | ok |
- | arm64: | ok |
- | c6x: | TODO |
- | csky: | TODO |
- | h8300: | TODO |
- | hexagon: | TODO |
- | ia64: | ok |
- | m68k: | TODO |
- | microblaze: | TODO |
- | mips: | TODO |
- | nds32: | TODO |
- | nios2: | TODO |
- | openrisc: | TODO |
- | parisc: | TODO |
- | powerpc: | TODO |
- | riscv: | TODO |
- | s390: | ok |
- | sh: | ok |
- | sparc: | ok |
- | um: | ok |
- | unicore32: | TODO |
- | x86: | ok |
- | xtensa: | ok |
- -----------------------
diff --git a/Documentation/filesystems/Locking b/Documentation/filesystems/Locking
deleted file mode 100644
index 204dd3e..0000000
--- a/Documentation/filesystems/Locking
+++ /dev/null
@@ -1,576 +0,0 @@
- The text below describes the locking rules for VFS-related methods.
-It is (believed to be) up-to-date. *Please*, if you change anything in
-prototypes or locking protocols - update this file. And update the relevant
-instances in the tree, don't leave that to maintainers of filesystems/devices/
-etc. At the very least, put the list of dubious cases in the end of this file.
-Don't turn it into log - maintainers of out-of-the-tree code are supposed to
-be able to use diff(1).
- Thing currently missing here: socket operations. Alexey?
-
---------------------------- dentry_operations --------------------------
-prototypes:
- int (*d_revalidate)(struct dentry *, unsigned int);
- int (*d_weak_revalidate)(struct dentry *, unsigned int);
- int (*d_hash)(const struct dentry *, struct qstr *);
- int (*d_compare)(const struct dentry *,
- unsigned int, const char *, const struct qstr *);
- int (*d_delete)(struct dentry *);
- int (*d_init)(struct dentry *);
- void (*d_release)(struct dentry *);
- void (*d_iput)(struct dentry *, struct inode *);
- char *(*d_dname)((struct dentry *dentry, char *buffer, int buflen);
- struct vfsmount *(*d_automount)(struct path *path);
- int (*d_manage)(const struct path *, bool);
- struct dentry *(*d_real)(struct dentry *, const struct inode *);
-
-locking rules:
- rename_lock ->d_lock may block rcu-walk
-d_revalidate: no no yes (ref-walk) maybe
-d_weak_revalidate:no no yes no
-d_hash no no no maybe
-d_compare: yes no no maybe
-d_delete: no yes no no
-d_init: no no yes no
-d_release: no no yes no
-d_prune: no yes no no
-d_iput: no no yes no
-d_dname: no no no no
-d_automount: no no yes no
-d_manage: no no yes (ref-walk) maybe
-d_real no no yes no
-
---------------------------- inode_operations ---------------------------
-prototypes:
- int (*create) (struct inode *,struct dentry *,umode_t, bool);
- struct dentry * (*lookup) (struct inode *,struct dentry *, unsigned int);
- int (*link) (struct dentry *,struct inode *,struct dentry *);
- int (*unlink) (struct inode *,struct dentry *);
- int (*symlink) (struct inode *,struct dentry *,const char *);
- int (*mkdir) (struct inode *,struct dentry *,umode_t);
- int (*rmdir) (struct inode *,struct dentry *);
- int (*mknod) (struct inode *,struct dentry *,umode_t,dev_t);
- int (*rename) (struct inode *, struct dentry *,
- struct inode *, struct dentry *, unsigned int);
- int (*readlink) (struct dentry *, char __user *,int);
- const char *(*get_link) (struct dentry *, struct inode *, struct delayed_call *);
- void (*truncate) (struct inode *);
- int (*permission) (struct inode *, int, unsigned int);
- int (*get_acl)(struct inode *, int);
- int (*setattr) (struct dentry *, struct iattr *);
- int (*getattr) (const struct path *, struct kstat *, u32, unsigned int);
- ssize_t (*listxattr) (struct dentry *, char *, size_t);
- int (*fiemap)(struct inode *, struct fiemap_extent_info *, u64 start, u64 len);
- void (*update_time)(struct inode *, struct timespec *, int);
- int (*atomic_open)(struct inode *, struct dentry *,
- struct file *, unsigned open_flag,
- umode_t create_mode);
- int (*tmpfile) (struct inode *, struct dentry *, umode_t);
-
-locking rules:
- all may block
- i_rwsem(inode)
-lookup: shared
-create: exclusive
-link: exclusive (both)
-mknod: exclusive
-symlink: exclusive
-mkdir: exclusive
-unlink: exclusive (both)
-rmdir: exclusive (both)(see below)
-rename: exclusive (all) (see below)
-readlink: no
-get_link: no
-setattr: exclusive
-permission: no (may not block if called in rcu-walk mode)
-get_acl: no
-getattr: no
-listxattr: no
-fiemap: no
-update_time: no
-atomic_open: exclusive
-tmpfile: no
-
-
- Additionally, ->rmdir(), ->unlink() and ->rename() have ->i_rwsem
- exclusive on victim.
- cross-directory ->rename() has (per-superblock) ->s_vfs_rename_sem.
-
-See Documentation/filesystems/directory-locking for more detailed discussion
-of the locking scheme for directory operations.
-
------------------------ xattr_handler operations -----------------------
-prototypes:
- bool (*list)(struct dentry *dentry);
- int (*get)(const struct xattr_handler *handler, struct dentry *dentry,
- struct inode *inode, const char *name, void *buffer,
- size_t size);
- int (*set)(const struct xattr_handler *handler, struct dentry *dentry,
- struct inode *inode, const char *name, const void *buffer,
- size_t size, int flags);
-
-locking rules:
- all may block
- i_rwsem(inode)
-list: no
-get: no
-set: exclusive
-
---------------------------- super_operations ---------------------------
-prototypes:
- struct inode *(*alloc_inode)(struct super_block *sb);
- void (*free_inode)(struct inode *);
- void (*destroy_inode)(struct inode *);
- void (*dirty_inode) (struct inode *, int flags);
- int (*write_inode) (struct inode *, struct writeback_control *wbc);
- int (*drop_inode) (struct inode *);
- void (*evict_inode) (struct inode *);
- void (*put_super) (struct super_block *);
- int (*sync_fs)(struct super_block *sb, int wait);
- int (*freeze_fs) (struct super_block *);
- int (*unfreeze_fs) (struct super_block *);
- int (*statfs) (struct dentry *, struct kstatfs *);
- int (*remount_fs) (struct super_block *, int *, char *);
- void (*umount_begin) (struct super_block *);
- int (*show_options)(struct seq_file *, struct dentry *);
- ssize_t (*quota_read)(struct super_block *, int, char *, size_t, loff_t);
- ssize_t (*quota_write)(struct super_block *, int, const char *, size_t, loff_t);
- int (*bdev_try_to_free_page)(struct super_block*, struct page*, gfp_t);
-
-locking rules:
- All may block [not true, see below]
- s_umount
-alloc_inode:
-free_inode: called from RCU callback
-destroy_inode:
-dirty_inode:
-write_inode:
-drop_inode: !!!inode->i_lock!!!
-evict_inode:
-put_super: write
-sync_fs: read
-freeze_fs: write
-unfreeze_fs: write
-statfs: maybe(read) (see below)
-remount_fs: write
-umount_begin: no
-show_options: no (namespace_sem)
-quota_read: no (see below)
-quota_write: no (see below)
-bdev_try_to_free_page: no (see below)
-
-->statfs() has s_umount (shared) when called by ustat(2) (native or
-compat), but that's an accident of bad API; s_umount is used to pin
-the superblock down when we only have dev_t given us by userland to
-identify the superblock. Everything else (statfs(), fstatfs(), etc.)
-doesn't hold it when calling ->statfs() - superblock is pinned down
-by resolving the pathname passed to syscall.
-->quota_read() and ->quota_write() functions are both guaranteed to
-be the only ones operating on the quota file by the quota code (via
-dqio_sem) (unless an admin really wants to screw up something and
-writes to quota files with quotas on). For other details about locking
-see also dquot_operations section.
-->bdev_try_to_free_page is called from the ->releasepage handler of
-the block device inode. See there for more details.
-
---------------------------- file_system_type ---------------------------
-prototypes:
- struct dentry *(*mount) (struct file_system_type *, int,
- const char *, void *);
- void (*kill_sb) (struct super_block *);
-locking rules:
- may block
-mount yes
-kill_sb yes
-
-->mount() returns ERR_PTR or the root dentry; its superblock should be locked
-on return.
-->kill_sb() takes a write-locked superblock, does all shutdown work on it,
-unlocks and drops the reference.
-
---------------------------- address_space_operations --------------------------
-prototypes:
- int (*writepage)(struct page *page, struct writeback_control *wbc);
- int (*readpage)(struct file *, struct page *);
- int (*writepages)(struct address_space *, struct writeback_control *);
- int (*set_page_dirty)(struct page *page);
- int (*readpages)(struct file *filp, struct address_space *mapping,
- struct list_head *pages, unsigned nr_pages);
- int (*write_begin)(struct file *, struct address_space *mapping,
- loff_t pos, unsigned len, unsigned flags,
- struct page **pagep, void **fsdata);
- int (*write_end)(struct file *, struct address_space *mapping,
- loff_t pos, unsigned len, unsigned copied,
- struct page *page, void *fsdata);
- sector_t (*bmap)(struct address_space *, sector_t);
- void (*invalidatepage) (struct page *, unsigned int, unsigned int);
- int (*releasepage) (struct page *, int);
- void (*freepage)(struct page *);
- int (*direct_IO)(struct kiocb *, struct iov_iter *iter);
- bool (*isolate_page) (struct page *, isolate_mode_t);
- int (*migratepage)(struct address_space *, struct page *, struct page *);
- void (*putback_page) (struct page *);
- int (*launder_page)(struct page *);
- int (*is_partially_uptodate)(struct page *, unsigned long, unsigned long);
- int (*error_remove_page)(struct address_space *, struct page *);
- int (*swap_activate)(struct file *);
- int (*swap_deactivate)(struct file *);
-
-locking rules:
- All except set_page_dirty and freepage may block
-
- PageLocked(page) i_rwsem
-writepage: yes, unlocks (see below)
-readpage: yes, unlocks
-writepages:
-set_page_dirty no
-readpages:
-write_begin: locks the page exclusive
-write_end: yes, unlocks exclusive
-bmap:
-invalidatepage: yes
-releasepage: yes
-freepage: yes
-direct_IO:
-isolate_page: yes
-migratepage: yes (both)
-putback_page: yes
-launder_page: yes
-is_partially_uptodate: yes
-error_remove_page: yes
-swap_activate: no
-swap_deactivate: no
-
- ->write_begin(), ->write_end() and ->readpage() may be called from
-the request handler (/dev/loop).
-
- ->readpage() unlocks the page, either synchronously or via I/O
-completion.
-
- ->readpages() populates the pagecache with the passed pages and starts
-I/O against them. They come unlocked upon I/O completion.
-
- ->writepage() is used for two purposes: for "memory cleansing" and for
-"sync". These are quite different operations and the behaviour may differ
-depending upon the mode.
-
-If writepage is called for sync (wbc->sync_mode != WBC_SYNC_NONE) then
-it *must* start I/O against the page, even if that would involve
-blocking on in-progress I/O.
-
-If writepage is called for memory cleansing (sync_mode ==
-WBC_SYNC_NONE) then its role is to get as much writeout underway as
-possible. So writepage should try to avoid blocking against
-currently-in-progress I/O.
-
-If the filesystem is not called for "sync" and it determines that it
-would need to block against in-progress I/O to be able to start new I/O
-against the page the filesystem should redirty the page with
-redirty_page_for_writepage(), then unlock the page and return zero.
-This may also be done to avoid internal deadlocks, but rarely.
-
-If the filesystem is called for sync then it must wait on any
-in-progress I/O and then start new I/O.
-
-The filesystem should unlock the page synchronously, before returning to the
-caller, unless ->writepage() returns special WRITEPAGE_ACTIVATE
-value. WRITEPAGE_ACTIVATE means that page cannot really be written out
-currently, and VM should stop calling ->writepage() on this page for some
-time. VM does this by moving page to the head of the active list, hence the
-name.
-
-Unless the filesystem is going to redirty_page_for_writepage(), unlock the page
-and return zero, writepage *must* run set_page_writeback() against the page,
-followed by unlocking it. Once set_page_writeback() has been run against the
-page, write I/O can be submitted and the write I/O completion handler must run
-end_page_writeback() once the I/O is complete. If no I/O is submitted, the
-filesystem must run end_page_writeback() against the page before returning from
-writepage.
-
-That is: after 2.5.12, pages which are under writeout are *not* locked. Note,
-if the filesystem needs the page to be locked during writeout, that is ok, too,
-the page is allowed to be unlocked at any point in time between the calls to
-set_page_writeback() and end_page_writeback().
-
-Note, failure to run either redirty_page_for_writepage() or the combination of
-set_page_writeback()/end_page_writeback() on a page submitted to writepage
-will leave the page itself marked clean but it will be tagged as dirty in the
-radix tree. This incoherency can lead to all sorts of hard-to-debug problems
-in the filesystem like having dirty inodes at umount and losing written data.
-
- ->writepages() is used for periodic writeback and for syscall-initiated
-sync operations. The address_space should start I/O against at least
-*nr_to_write pages. *nr_to_write must be decremented for each page which is
-written. The address_space implementation may write more (or less) pages
-than *nr_to_write asks for, but it should try to be reasonably close. If
-nr_to_write is NULL, all dirty pages must be written.
-
-writepages should _only_ write pages which are present on
-mapping->io_pages.
-
- ->set_page_dirty() is called from various places in the kernel
-when the target page is marked as needing writeback. It may be called
-under spinlock (it cannot block) and is sometimes called with the page
-not locked.
-
- ->bmap() is currently used by legacy ioctl() (FIBMAP) provided by some
-filesystems and by the swapper. The latter will eventually go away. Please,
-keep it that way and don't breed new callers.
-
- ->invalidatepage() is called when the filesystem must attempt to drop
-some or all of the buffers from the page when it is being truncated. It
-returns zero on success. If ->invalidatepage is zero, the kernel uses
-block_invalidatepage() instead.
-
- ->releasepage() is called when the kernel is about to try to drop the
-buffers from the page in preparation for freeing it. It returns zero to
-indicate that the buffers are (or may be) freeable. If ->releasepage is zero,
-the kernel assumes that the fs has no private interest in the buffers.
-
- ->freepage() is called when the kernel is done dropping the page
-from the page cache.
-
- ->launder_page() may be called prior to releasing a page if
-it is still found to be dirty. It returns zero if the page was successfully
-cleaned, or an error value if not. Note that in order to prevent the page
-getting mapped back in and redirtied, it needs to be kept locked
-across the entire operation.
-
- ->swap_activate will be called with a non-zero argument on
-files backing (non block device backed) swapfiles. A return value
-of zero indicates success, in which case this file can be used for
-backing swapspace. The swapspace operations will be proxied to the
-address space operations.
-
- ->swap_deactivate() will be called in the sys_swapoff()
-path after ->swap_activate() returned success.
-
------------------------ file_lock_operations ------------------------------
-prototypes:
- void (*fl_copy_lock)(struct file_lock *, struct file_lock *);
- void (*fl_release_private)(struct file_lock *);
-
-
-locking rules:
- inode->i_lock may block
-fl_copy_lock: yes no
-fl_release_private: maybe maybe[1]
-
-[1]: ->fl_release_private for flock or POSIX locks is currently allowed
-to block. Leases however can still be freed while the i_lock is held and
-so fl_release_private called on a lease should not block.
-
------------------------ lock_manager_operations ---------------------------
-prototypes:
- void (*lm_notify)(struct file_lock *); /* unblock callback */
- int (*lm_grant)(struct file_lock *, struct file_lock *, int);
- void (*lm_break)(struct file_lock *); /* break_lease callback */
- int (*lm_change)(struct file_lock **, int);
-
-locking rules:
-
- inode->i_lock blocked_lock_lock may block
-lm_notify: yes yes no
-lm_grant: no no no
-lm_break: yes no no
-lm_change yes no no
-
---------------------------- buffer_head -----------------------------------
-prototypes:
- void (*b_end_io)(struct buffer_head *bh, int uptodate);
-
-locking rules:
- called from interrupts. In other words, extreme care is needed here.
-bh is locked, but that's all warranties we have here. Currently only RAID1,
-highmem, fs/buffer.c, and fs/ntfs/aops.c are providing these. Block devices
-call this method upon the IO completion.
-
---------------------------- block_device_operations -----------------------
-prototypes:
- int (*open) (struct block_device *, fmode_t);
- int (*release) (struct gendisk *, fmode_t);
- int (*ioctl) (struct block_device *, fmode_t, unsigned, unsigned long);
- int (*compat_ioctl) (struct block_device *, fmode_t, unsigned, unsigned long);
- int (*direct_access) (struct block_device *, sector_t, void **,
- unsigned long *);
- int (*media_changed) (struct gendisk *);
- void (*unlock_native_capacity) (struct gendisk *);
- int (*revalidate_disk) (struct gendisk *);
- int (*getgeo)(struct block_device *, struct hd_geometry *);
- void (*swap_slot_free_notify) (struct block_device *, unsigned long);
-
-locking rules:
- bd_mutex
-open: yes
-release: yes
-ioctl: no
-compat_ioctl: no
-direct_access: no
-media_changed: no
-unlock_native_capacity: no
-revalidate_disk: no
-getgeo: no
-swap_slot_free_notify: no (see below)
-
-media_changed, unlock_native_capacity and revalidate_disk are called only from
-check_disk_change().
-
-swap_slot_free_notify is called with swap_lock and sometimes the page lock
-held.
-
-
---------------------------- file_operations -------------------------------
-prototypes:
- loff_t (*llseek) (struct file *, loff_t, int);
- ssize_t (*read) (struct file *, char __user *, size_t, loff_t *);
- ssize_t (*write) (struct file *, const char __user *, size_t, loff_t *);
- ssize_t (*read_iter) (struct kiocb *, struct iov_iter *);
- ssize_t (*write_iter) (struct kiocb *, struct iov_iter *);
- int (*iterate) (struct file *, struct dir_context *);
- int (*iterate_shared) (struct file *, struct dir_context *);
- __poll_t (*poll) (struct file *, struct poll_table_struct *);
- long (*unlocked_ioctl) (struct file *, unsigned int, unsigned long);
- long (*compat_ioctl) (struct file *, unsigned int, unsigned long);
- int (*mmap) (struct file *, struct vm_area_struct *);
- int (*open) (struct inode *, struct file *);
- int (*flush) (struct file *);
- int (*release) (struct inode *, struct file *);
- int (*fsync) (struct file *, loff_t start, loff_t end, int datasync);
- int (*fasync) (int, struct file *, int);
- int (*lock) (struct file *, int, struct file_lock *);
- ssize_t (*readv) (struct file *, const struct iovec *, unsigned long,
- loff_t *);
- ssize_t (*writev) (struct file *, const struct iovec *, unsigned long,
- loff_t *);
- ssize_t (*sendfile) (struct file *, loff_t *, size_t, read_actor_t,
- void __user *);
- ssize_t (*sendpage) (struct file *, struct page *, int, size_t,
- loff_t *, int);
- unsigned long (*get_unmapped_area)(struct file *, unsigned long,
- unsigned long, unsigned long, unsigned long);
- int (*check_flags)(int);
- int (*flock) (struct file *, int, struct file_lock *);
- ssize_t (*splice_write)(struct pipe_inode_info *, struct file *, loff_t *,
- size_t, unsigned int);
- ssize_t (*splice_read)(struct file *, loff_t *, struct pipe_inode_info *,
- size_t, unsigned int);
- int (*setlease)(struct file *, long, struct file_lock **, void **);
- long (*fallocate)(struct file *, int, loff_t, loff_t);
-};
-
-locking rules:
- All may block.
-
-->llseek() locking has moved from llseek to the individual llseek
-implementations. If your fs is not using generic_file_llseek, you
-need to acquire and release the appropriate locks in your ->llseek().
-For many filesystems, it is probably safe to acquire the inode
-mutex or just to use i_size_read() instead.
-Note: this does not protect the file->f_pos against concurrent modifications
-since this is something the userspace has to take care about.
-
-->iterate() is called with i_rwsem exclusive.
-
-->iterate_shared() is called with i_rwsem at least shared.
-
-->fasync() is responsible for maintaining the FASYNC bit in filp->f_flags.
-Most instances call fasync_helper(), which does that maintenance, so it's
-not normally something one needs to worry about. Return values > 0 will be
-mapped to zero in the VFS layer.
-
-->readdir() and ->ioctl() on directories must be changed. Ideally we would
-move ->readdir() to inode_operations and use a separate method for directory
-->ioctl() or kill the latter completely. One of the problems is that for
-anything that resembles union-mount we won't have a struct file for all
-components. And there are other reasons why the current interface is a mess...
-
-->read on directories probably must go away - we should just enforce -EISDIR
-in sys_read() and friends.
-
-->setlease operations should call generic_setlease() before or after setting
-the lease within the individual filesystem to record the result of the
-operation
-
---------------------------- dquot_operations -------------------------------
-prototypes:
- int (*write_dquot) (struct dquot *);
- int (*acquire_dquot) (struct dquot *);
- int (*release_dquot) (struct dquot *);
- int (*mark_dirty) (struct dquot *);
- int (*write_info) (struct super_block *, int);
-
-These operations are intended to be more or less wrapping functions that ensure
-a proper locking wrt the filesystem and call the generic quota operations.
-
-What filesystem should expect from the generic quota functions:
-
- FS recursion Held locks when called
-write_dquot: yes dqonoff_sem or dqptr_sem
-acquire_dquot: yes dqonoff_sem or dqptr_sem
-release_dquot: yes dqonoff_sem or dqptr_sem
-mark_dirty: no -
-write_info: yes dqonoff_sem
-
-FS recursion means calling ->quota_read() and ->quota_write() from superblock
-operations.
-
-More details about quota locking can be found in fs/dquot.c.
-
---------------------------- vm_operations_struct -----------------------------
-prototypes:
- void (*open)(struct vm_area_struct*);
- void (*close)(struct vm_area_struct*);
- vm_fault_t (*fault)(struct vm_area_struct*, struct vm_fault *);
- vm_fault_t (*page_mkwrite)(struct vm_area_struct *, struct vm_fault *);
- vm_fault_t (*pfn_mkwrite)(struct vm_area_struct *, struct vm_fault *);
- int (*access)(struct vm_area_struct *, unsigned long, void*, int, int);
-
-locking rules:
- mmap_sem PageLocked(page)
-open: yes
-close: yes
-fault: yes can return with page locked
-map_pages: yes
-page_mkwrite: yes can return with page locked
-pfn_mkwrite: yes
-access: yes
-
- ->fault() is called when a previously not present pte is about
-to be faulted in. The filesystem must find and return the page associated
-with the passed in "pgoff" in the vm_fault structure. If it is possible that
-the page may be truncated and/or invalidated, then the filesystem must lock
-the page, then ensure it is not already truncated (the page lock will block
-subsequent truncate), and then return with VM_FAULT_LOCKED, and the page
-locked. The VM will unlock the page.
-
- ->map_pages() is called when VM asks to map easy accessible pages.
-Filesystem should find and map pages associated with offsets from "start_pgoff"
-till "end_pgoff". ->map_pages() is called with page table locked and must
-not block. If it's not possible to reach a page without blocking,
-filesystem should skip it. Filesystem should use do_set_pte() to setup
-page table entry. Pointer to entry associated with the page is passed in
-"pte" field in vm_fault structure. Pointers to entries for other offsets
-should be calculated relative to "pte".
-
- ->page_mkwrite() is called when a previously read-only pte is
-about to become writeable. The filesystem again must ensure that there are
-no truncate/invalidate races, and then return with the page locked. If
-the page has been truncated, the filesystem should not look up a new page
-like the ->fault() handler, but simply return with VM_FAULT_NOPAGE, which
-will cause the VM to retry the fault.
-
- ->pfn_mkwrite() is the same as page_mkwrite but when the pte is
-VM_PFNMAP or VM_MIXEDMAP with a page-less entry. Expected return is
-VM_FAULT_NOPAGE. Or one of the VM_FAULT_ERROR types. The default behavior
-after this call is to make the pte read-write, unless pfn_mkwrite returns
-an error.
-
- ->access() is called when get_user_pages() fails in
-access_process_vm(), typically used to debug a process through
-/proc/pid/mem or ptrace. This function is needed only for
-VM_IO | VM_PFNMAP VMAs.
-
-================================================================================
- Dubious stuff
-
-(if you break something or notice that it is broken and do not fix it yourself
-- at least put it here)
diff --git a/Documentation/filesystems/ceph.txt b/Documentation/filesystems/ceph.txt
index d2c6a5c..b19b6a0 100644
--- a/Documentation/filesystems/ceph.txt
+++ b/Documentation/filesystems/ceph.txt
@@ -158,6 +158,20 @@
copies. Currently, it's only used in copy_file_range, which will revert
to the default VFS implementation if this option is used.
+ recover_session=<no|clean>
+ Set auto reconnect mode in the case where the client is blacklisted. The
+ available modes are "no" and "clean". The default is "no".
+
+ * no: never attempt to reconnect when client detects that it has been
+ blacklisted. Operations will generally fail after being blacklisted.
+
+ * clean: client reconnects to the ceph cluster automatically when it
+ detects that it has been blacklisted. During reconnect, client drops
+ dirty data/metadata, invalidates page caches and writable file handles.
+ After reconnect, file locks become stale because the MDS loses track
+ of them. If an inode contains any stale file locks, read/write on the
+ inode is not allowed until applications release all stale file locks.
+
More Information
================
diff --git a/Documentation/filesystems/cifs/AUTHORS b/Documentation/filesystems/cifs/AUTHORS
deleted file mode 100644
index 75865da..0000000
--- a/Documentation/filesystems/cifs/AUTHORS
+++ /dev/null
@@ -1,63 +0,0 @@
-Original Author
-===============
-Steve French (sfrench@samba.org)
-
-The author wishes to express his appreciation and thanks to:
-Andrew Tridgell (Samba team) for his early suggestions about smb/cifs VFS
-improvements. Thanks to IBM for allowing me time and test resources to pursue
-this project, to Jim McDonough from IBM (and the Samba Team) for his help, to
-the IBM Linux JFS team for explaining many esoteric Linux filesystem features.
-Jeremy Allison of the Samba team has done invaluable work in adding the server
-side of the original CIFS Unix extensions and reviewing and implementing
-portions of the newer CIFS POSIX extensions into the Samba 3 file server. Thank
-Dave Boutcher of IBM Rochester (author of the OS/400 smb/cifs filesystem client)
-for proving years ago that very good smb/cifs clients could be done on Unix-like
-operating systems. Volker Lendecke, Andrew Tridgell, Urban Widmark, John
-Newbigin and others for their work on the Linux smbfs module. Thanks to
-the other members of the Storage Network Industry Association CIFS Technical
-Workgroup for their work specifying this highly complex protocol and finally
-thanks to the Samba team for their technical advice and encouragement.
-
-Patch Contributors
-------------------
-Zwane Mwaikambo
-Andi Kleen
-Amrut Joshi
-Shobhit Dayal
-Sergey Vlasov
-Richard Hughes
-Yury Umanets
-Mark Hamzy (for some of the early cifs IPv6 work)
-Domen Puncer
-Jesper Juhl (in particular for lots of whitespace/formatting cleanup)
-Vince Negri and Dave Stahl (for finding an important caching bug)
-Adrian Bunk (kcalloc cleanups)
-Miklos Szeredi
-Kazeon team for various fixes especially for 2.4 version.
-Asser Ferno (Change Notify support)
-Shaggy (Dave Kleikamp) for innumerable small fs suggestions and some good cleanup
-Gunter Kukkukk (testing and suggestions for support of old servers)
-Igor Mammedov (DFS support)
-Jeff Layton (many, many fixes, as well as great work on the cifs Kerberos code)
-Scott Lovenberg
-Pavel Shilovsky (for great work adding SMB2 support, and various SMB3 features)
-Aurelien Aptel (for DFS SMB3 work and some key bug fixes)
-Ronnie Sahlberg (for SMB3 xattr work, bug fixes, and lots of great work on compounding)
-Shirish Pargaonkar (for many ACL patches over the years)
-Sachin Prabhu (many bug fixes, including for reconnect, copy offload and security)
-Paulo Alcantara
-Long Li (some great work on RDMA, SMB Direct)
-
-
-Test case and Bug Report contributors
--------------------------------------
-Thanks to those in the community who have submitted detailed bug reports
-and debug of problems they have found: Jochen Dolze, David Blaine,
-Rene Scharfe, Martin Josefsson, Alexander Wild, Anthony Liguori,
-Lars Muller, Urban Widmark, Massimiliano Ferrero, Howard Owen,
-Olaf Kirch, Kieron Briggs, Nick Millington and others. Also special
-mention to the Stanford Checker (SWAT) which pointed out many minor
-bugs in error paths. Valuable suggestions also have come from Al Viro
-and Dave Miller.
-
-And thanks to the IBM LTC and Power test teams and SuSE and Citrix and RedHat testers for finding multiple bugs during excellent stress test runs.
diff --git a/Documentation/filesystems/cifs/CHANGES b/Documentation/filesystems/cifs/CHANGES
deleted file mode 100644
index 1df7f49..0000000
--- a/Documentation/filesystems/cifs/CHANGES
+++ /dev/null
@@ -1,4 +0,0 @@
-See https://wiki.samba.org/index.php/LinuxCIFSKernel for summary
-information (that may be easier to read than parsing the output of
-"git log fs/cifs") about fixes/improvements to CIFS/SMB2/SMB3 support (changes
-to cifs.ko module) by kernel version (and cifs internal module version).
diff --git a/Documentation/filesystems/cifs/README b/Documentation/filesystems/cifs/README
deleted file mode 100644
index 4a80461..0000000
--- a/Documentation/filesystems/cifs/README
+++ /dev/null
@@ -1,743 +0,0 @@
-This module supports the SMB3 family of advanced network protocols (as well
-as older dialects, originally called "CIFS" or SMB1).
-
-The CIFS VFS module for Linux supports many advanced network filesystem
-features such as hierarchical DFS like namespace, hardlinks, locking and more.
-It was designed to comply with the SNIA CIFS Technical Reference (which
-supersedes the 1992 X/Open SMB Standard) as well as to perform best practice
-practical interoperability with Windows 2000, Windows XP, Samba and equivalent
-servers. This code was developed in participation with the Protocol Freedom
-Information Foundation. CIFS and now SMB3 has now become a defacto
-standard for interoperating between Macs and Windows and major NAS appliances.
-
-Please see
- MS-SMB2 (for detailed SMB2/SMB3/SMB3.1.1 protocol specification)
- http://protocolfreedom.org/ and
- http://samba.org/samba/PFIF/
-for more details.
-
-
-For questions or bug reports please contact:
- smfrench@gmail.com
-
-See the project page at: https://wiki.samba.org/index.php/LinuxCIFS_utils
-
-Build instructions:
-==================
-For Linux:
-1) Download the kernel (e.g. from http://www.kernel.org)
-and change directory into the top of the kernel directory tree
-(e.g. /usr/src/linux-2.5.73)
-2) make menuconfig (or make xconfig)
-3) select cifs from within the network filesystem choices
-4) save and exit
-5) make
-
-
-Installation instructions:
-=========================
-If you have built the CIFS vfs as module (successfully) simply
-type "make modules_install" (or if you prefer, manually copy the file to
-the modules directory e.g. /lib/modules/2.4.10-4GB/kernel/fs/cifs/cifs.ko).
-
-If you have built the CIFS vfs into the kernel itself, follow the instructions
-for your distribution on how to install a new kernel (usually you
-would simply type "make install").
-
-If you do not have the utility mount.cifs (in the Samba 4.x source tree and on
-the CIFS VFS web site) copy it to the same directory in which mount helpers
-reside (usually /sbin). Although the helper software is not
-required, mount.cifs is recommended. Most distros include a "cifs-utils"
-package that includes this utility so it is recommended to install this.
-
-Note that running the Winbind pam/nss module (logon service) on all of your
-Linux clients is useful in mapping Uids and Gids consistently across the
-domain to the proper network user. The mount.cifs mount helper can be
-found at cifs-utils.git on git.samba.org
-
-If cifs is built as a module, then the size and number of network buffers
-and maximum number of simultaneous requests to one server can be configured.
-Changing these from their defaults is not recommended. By executing modinfo
- modinfo kernel/fs/cifs/cifs.ko
-on kernel/fs/cifs/cifs.ko the list of configuration changes that can be made
-at module initialization time (by running insmod cifs.ko) can be seen.
-
-Recommendations
-===============
-To improve security the SMB2.1 dialect or later (usually will get SMB3) is now
-the new default. To use old dialects (e.g. to mount Windows XP) use "vers=1.0"
-on mount (or vers=2.0 for Windows Vista). Note that the CIFS (vers=1.0) is
-much older and less secure than the default dialect SMB3 which includes
-many advanced security features such as downgrade attack detection
-and encrypted shares and stronger signing and authentication algorithms.
-There are additional mount options that may be helpful for SMB3 to get
-improved POSIX behavior (NB: can use vers=3.0 to force only SMB3, never 2.1):
- "mfsymlinks" and "cifsacl" and "idsfromsid"
-
-Allowing User Mounts
-====================
-To permit users to mount and unmount over directories they own is possible
-with the cifs vfs. A way to enable such mounting is to mark the mount.cifs
-utility as suid (e.g. "chmod +s /sbin/mount.cifs). To enable users to
-umount shares they mount requires
-1) mount.cifs version 1.4 or later
-2) an entry for the share in /etc/fstab indicating that a user may
-unmount it e.g.
-//server/usersharename /mnt/username cifs user 0 0
-
-Note that when the mount.cifs utility is run suid (allowing user mounts),
-in order to reduce risks, the "nosuid" mount flag is passed in on mount to
-disallow execution of an suid program mounted on the remote target.
-When mount is executed as root, nosuid is not passed in by default,
-and execution of suid programs on the remote target would be enabled
-by default. This can be changed, as with nfs and other filesystems,
-by simply specifying "nosuid" among the mount options. For user mounts
-though to be able to pass the suid flag to mount requires rebuilding
-mount.cifs with the following flag: CIFS_ALLOW_USR_SUID
-
-There is a corresponding manual page for cifs mounting in the Samba 3.0 and
-later source tree in docs/manpages/mount.cifs.8
-
-Allowing User Unmounts
-======================
-To permit users to ummount directories that they have user mounted (see above),
-the utility umount.cifs may be used. It may be invoked directly, or if
-umount.cifs is placed in /sbin, umount can invoke the cifs umount helper
-(at least for most versions of the umount utility) for umount of cifs
-mounts, unless umount is invoked with -i (which will avoid invoking a umount
-helper). As with mount.cifs, to enable user unmounts umount.cifs must be marked
-as suid (e.g. "chmod +s /sbin/umount.cifs") or equivalent (some distributions
-allow adding entries to a file to the /etc/permissions file to achieve the
-equivalent suid effect). For this utility to succeed the target path
-must be a cifs mount, and the uid of the current user must match the uid
-of the user who mounted the resource.
-
-Also note that the customary way of allowing user mounts and unmounts is
-(instead of using mount.cifs and unmount.cifs as suid) to add a line
-to the file /etc/fstab for each //server/share you wish to mount, but
-this can become unwieldy when potential mount targets include many
-or unpredictable UNC names.
-
-Samba Considerations
-====================
-Most current servers support SMB2.1 and SMB3 which are more secure,
-but there are useful protocol extensions for the older less secure CIFS
-dialect, so to get the maximum benefit if mounting using the older dialect
-(CIFS/SMB1), we recommend using a server that supports the SNIA CIFS
-Unix Extensions standard (e.g. almost any version of Samba ie version
-2.2.5 or later) but the CIFS vfs works fine with a wide variety of CIFS servers.
-Note that uid, gid and file permissions will display default values if you do
-not have a server that supports the Unix extensions for CIFS (such as Samba
-2.2.5 or later). To enable the Unix CIFS Extensions in the Samba server, add
-the line:
-
- unix extensions = yes
-
-to your smb.conf file on the server. Note that the following smb.conf settings
-are also useful (on the Samba server) when the majority of clients are Unix or
-Linux:
-
- case sensitive = yes
- delete readonly = yes
- ea support = yes
-
-Note that server ea support is required for supporting xattrs from the Linux
-cifs client, and that EA support is present in later versions of Samba (e.g.
-3.0.6 and later (also EA support works in all versions of Windows, at least to
-shares on NTFS filesystems). Extended Attribute (xattr) support is an optional
-feature of most Linux filesystems which may require enabling via
-make menuconfig. Client support for extended attributes (user xattr) can be
-disabled on a per-mount basis by specifying "nouser_xattr" on mount.
-
-The CIFS client can get and set POSIX ACLs (getfacl, setfacl) to Samba servers
-version 3.10 and later. Setting POSIX ACLs requires enabling both XATTR and
-then POSIX support in the CIFS configuration options when building the cifs
-module. POSIX ACL support can be disabled on a per mount basic by specifying
-"noacl" on mount.
-
-Some administrators may want to change Samba's smb.conf "map archive" and
-"create mask" parameters from the default. Unless the create mask is changed
-newly created files can end up with an unnecessarily restrictive default mode,
-which may not be what you want, although if the CIFS Unix extensions are
-enabled on the server and client, subsequent setattr calls (e.g. chmod) can
-fix the mode. Note that creating special devices (mknod) remotely
-may require specifying a mkdev function to Samba if you are not using
-Samba 3.0.6 or later. For more information on these see the manual pages
-("man smb.conf") on the Samba server system. Note that the cifs vfs,
-unlike the smbfs vfs, does not read the smb.conf on the client system
-(the few optional settings are passed in on mount via -o parameters instead).
-Note that Samba 2.2.7 or later includes a fix that allows the CIFS VFS to delete
-open files (required for strict POSIX compliance). Windows Servers already
-supported this feature. Samba server does not allow symlinks that refer to files
-outside of the share, so in Samba versions prior to 3.0.6, most symlinks to
-files with absolute paths (ie beginning with slash) such as:
- ln -s /mnt/foo bar
-would be forbidden. Samba 3.0.6 server or later includes the ability to create
-such symlinks safely by converting unsafe symlinks (ie symlinks to server
-files that are outside of the share) to a samba specific format on the server
-that is ignored by local server applications and non-cifs clients and that will
-not be traversed by the Samba server). This is opaque to the Linux client
-application using the cifs vfs. Absolute symlinks will work to Samba 3.0.5 or
-later, but only for remote clients using the CIFS Unix extensions, and will
-be invisbile to Windows clients and typically will not affect local
-applications running on the same server as Samba.
-
-Use instructions:
-================
-Once the CIFS VFS support is built into the kernel or installed as a module
-(cifs.ko), you can use mount syntax like the following to access Samba or
-Mac or Windows servers:
-
- mount -t cifs //9.53.216.11/e$ /mnt -o username=myname,password=mypassword
-
-Before -o the option -v may be specified to make the mount.cifs
-mount helper display the mount steps more verbosely.
-After -o the following commonly used cifs vfs specific options
-are supported:
-
- username=<username>
- password=<password>
- domain=<domain name>
-
-Other cifs mount options are described below. Use of TCP names (in addition to
-ip addresses) is available if the mount helper (mount.cifs) is installed. If
-you do not trust the server to which are mounted, or if you do not have
-cifs signing enabled (and the physical network is insecure), consider use
-of the standard mount options "noexec" and "nosuid" to reduce the risk of
-running an altered binary on your local system (downloaded from a hostile server
-or altered by a hostile router).
-
-Although mounting using format corresponding to the CIFS URL specification is
-not possible in mount.cifs yet, it is possible to use an alternate format
-for the server and sharename (which is somewhat similar to NFS style mount
-syntax) instead of the more widely used UNC format (i.e. \\server\share):
- mount -t cifs tcp_name_of_server:share_name /mnt -o user=myname,pass=mypasswd
-
-When using the mount helper mount.cifs, passwords may be specified via alternate
-mechanisms, instead of specifying it after -o using the normal "pass=" syntax
-on the command line:
-1) By including it in a credential file. Specify credentials=filename as one
-of the mount options. Credential files contain two lines
- username=someuser
- password=your_password
-2) By specifying the password in the PASSWD environment variable (similarly
-the user name can be taken from the USER environment variable).
-3) By specifying the password in a file by name via PASSWD_FILE
-4) By specifying the password in a file by file descriptor via PASSWD_FD
-
-If no password is provided, mount.cifs will prompt for password entry
-
-Restrictions
-============
-Servers must support either "pure-TCP" (port 445 TCP/IP CIFS connections) or RFC
-1001/1002 support for "Netbios-Over-TCP/IP." This is not likely to be a
-problem as most servers support this.
-
-Valid filenames differ between Windows and Linux. Windows typically restricts
-filenames which contain certain reserved characters (e.g.the character :
-which is used to delimit the beginning of a stream name by Windows), while
-Linux allows a slightly wider set of valid characters in filenames. Windows
-servers can remap such characters when an explicit mapping is specified in
-the Server's registry. Samba starting with version 3.10 will allow such
-filenames (ie those which contain valid Linux characters, which normally
-would be forbidden for Windows/CIFS semantics) as long as the server is
-configured for Unix Extensions (and the client has not disabled
-/proc/fs/cifs/LinuxExtensionsEnabled). In addition the mount option
-"mapposix" can be used on CIFS (vers=1.0) to force the mapping of
-illegal Windows/NTFS/SMB characters to a remap range (this mount parm
-is the default for SMB3). This remap ("mapposix") range is also
-compatible with Mac (and "Services for Mac" on some older Windows).
-
-CIFS VFS Mount Options
-======================
-A partial list of the supported mount options follows:
- username The user name to use when trying to establish
- the CIFS session.
- password The user password. If the mount helper is
- installed, the user will be prompted for password
- if not supplied.
- ip The ip address of the target server
- unc The target server Universal Network Name (export) to
- mount.
- domain Set the SMB/CIFS workgroup name prepended to the
- username during CIFS session establishment
- forceuid Set the default uid for inodes to the uid
- passed in on mount. For mounts to servers
- which do support the CIFS Unix extensions, such as a
- properly configured Samba server, the server provides
- the uid, gid and mode so this parameter should not be
- specified unless the server and clients uid and gid
- numbering differ. If the server and client are in the
- same domain (e.g. running winbind or nss_ldap) and
- the server supports the Unix Extensions then the uid
- and gid can be retrieved from the server (and uid
- and gid would not have to be specified on the mount.
- For servers which do not support the CIFS Unix
- extensions, the default uid (and gid) returned on lookup
- of existing files will be the uid (gid) of the person
- who executed the mount (root, except when mount.cifs
- is configured setuid for user mounts) unless the "uid="
- (gid) mount option is specified. Also note that permission
- checks (authorization checks) on accesses to a file occur
- at the server, but there are cases in which an administrator
- may want to restrict at the client as well. For those
- servers which do not report a uid/gid owner
- (such as Windows), permissions can also be checked at the
- client, and a crude form of client side permission checking
- can be enabled by specifying file_mode and dir_mode on
- the client. (default)
- forcegid (similar to above but for the groupid instead of uid) (default)
- noforceuid Fill in file owner information (uid) by requesting it from
- the server if possible. With this option, the value given in
- the uid= option (on mount) will only be used if the server
- can not support returning uids on inodes.
- noforcegid (similar to above but for the group owner, gid, instead of uid)
- uid Set the default uid for inodes, and indicate to the
- cifs kernel driver which local user mounted. If the server
- supports the unix extensions the default uid is
- not used to fill in the owner fields of inodes (files)
- unless the "forceuid" parameter is specified.
- gid Set the default gid for inodes (similar to above).
- file_mode If CIFS Unix extensions are not supported by the server
- this overrides the default mode for file inodes.
- fsc Enable local disk caching using FS-Cache (off by default). This
- option could be useful to improve performance on a slow link,
- heavily loaded server and/or network where reading from the
- disk is faster than reading from the server (over the network).
- This could also impact scalability positively as the
- number of calls to the server are reduced. However, local
- caching is not suitable for all workloads for e.g. read-once
- type workloads. So, you need to consider carefully your
- workload/scenario before using this option. Currently, local
- disk caching is functional for CIFS files opened as read-only.
- dir_mode If CIFS Unix extensions are not supported by the server
- this overrides the default mode for directory inodes.
- port attempt to contact the server on this tcp port, before
- trying the usual ports (port 445, then 139).
- iocharset Codepage used to convert local path names to and from
- Unicode. Unicode is used by default for network path
- names if the server supports it. If iocharset is
- not specified then the nls_default specified
- during the local client kernel build will be used.
- If server does not support Unicode, this parameter is
- unused.
- rsize default read size (usually 16K). The client currently
- can not use rsize larger than CIFSMaxBufSize. CIFSMaxBufSize
- defaults to 16K and may be changed (from 8K to the maximum
- kmalloc size allowed by your kernel) at module install time
- for cifs.ko. Setting CIFSMaxBufSize to a very large value
- will cause cifs to use more memory and may reduce performance
- in some cases. To use rsize greater than 127K (the original
- cifs protocol maximum) also requires that the server support
- a new Unix Capability flag (for very large read) which some
- newer servers (e.g. Samba 3.0.26 or later) do. rsize can be
- set from a minimum of 2048 to a maximum of 130048 (127K or
- CIFSMaxBufSize, whichever is smaller)
- wsize default write size (default 57344)
- maximum wsize currently allowed by CIFS is 57344 (fourteen
- 4096 byte pages)
- actimeo=n attribute cache timeout in seconds (default 1 second).
- After this timeout, the cifs client requests fresh attribute
- information from the server. This option allows to tune the
- attribute cache timeout to suit the workload needs. Shorter
- timeouts mean better the cache coherency, but increased number
- of calls to the server. Longer timeouts mean reduced number
- of calls to the server at the expense of less stricter cache
- coherency checks (i.e. incorrect attribute cache for a short
- period of time).
- rw mount the network share read-write (note that the
- server may still consider the share read-only)
- ro mount network share read-only
- version used to distinguish different versions of the
- mount helper utility (not typically needed)
- sep if first mount option (after the -o), overrides
- the comma as the separator between the mount
- parms. e.g.
- -o user=myname,password=mypassword,domain=mydom
- could be passed instead with period as the separator by
- -o sep=.user=myname.password=mypassword.domain=mydom
- this might be useful when comma is contained within username
- or password or domain. This option is less important
- when the cifs mount helper cifs.mount (version 1.1 or later)
- is used.
- nosuid Do not allow remote executables with the suid bit
- program to be executed. This is only meaningful for mounts
- to servers such as Samba which support the CIFS Unix Extensions.
- If you do not trust the servers in your network (your mount
- targets) it is recommended that you specify this option for
- greater security.
- exec Permit execution of binaries on the mount.
- noexec Do not permit execution of binaries on the mount.
- dev Recognize block devices on the remote mount.
- nodev Do not recognize devices on the remote mount.
- suid Allow remote files on this mountpoint with suid enabled to
- be executed (default for mounts when executed as root,
- nosuid is default for user mounts).
- credentials Although ignored by the cifs kernel component, it is used by
- the mount helper, mount.cifs. When mount.cifs is installed it
- opens and reads the credential file specified in order
- to obtain the userid and password arguments which are passed to
- the cifs vfs.
- guest Although ignored by the kernel component, the mount.cifs
- mount helper will not prompt the user for a password
- if guest is specified on the mount options. If no
- password is specified a null password will be used.
- perm Client does permission checks (vfs_permission check of uid
- and gid of the file against the mode and desired operation),
- Note that this is in addition to the normal ACL check on the
- target machine done by the server software.
- Client permission checking is enabled by default.
- noperm Client does not do permission checks. This can expose
- files on this mount to access by other users on the local
- client system. It is typically only needed when the server
- supports the CIFS Unix Extensions but the UIDs/GIDs on the
- client and server system do not match closely enough to allow
- access by the user doing the mount, but it may be useful with
- non CIFS Unix Extension mounts for cases in which the default
- mode is specified on the mount but is not to be enforced on the
- client (e.g. perhaps when MultiUserMount is enabled)
- Note that this does not affect the normal ACL check on the
- target machine done by the server software (of the server
- ACL against the user name provided at mount time).
- serverino Use server's inode numbers instead of generating automatically
- incrementing inode numbers on the client. Although this will
- make it easier to spot hardlinked files (as they will have
- the same inode numbers) and inode numbers may be persistent,
- note that the server does not guarantee that the inode numbers
- are unique if multiple server side mounts are exported under a
- single share (since inode numbers on the servers might not
- be unique if multiple filesystems are mounted under the same
- shared higher level directory). Note that some older
- (e.g. pre-Windows 2000) do not support returning UniqueIDs
- or the CIFS Unix Extensions equivalent and for those
- this mount option will have no effect. Exporting cifs mounts
- under nfsd requires this mount option on the cifs mount.
- This is now the default if server supports the
- required network operation.
- noserverino Client generates inode numbers (rather than using the actual one
- from the server). These inode numbers will vary after
- unmount or reboot which can confuse some applications,
- but not all server filesystems support unique inode
- numbers.
- setuids If the CIFS Unix extensions are negotiated with the server
- the client will attempt to set the effective uid and gid of
- the local process on newly created files, directories, and
- devices (create, mkdir, mknod). If the CIFS Unix Extensions
- are not negotiated, for newly created files and directories
- instead of using the default uid and gid specified on
- the mount, cache the new file's uid and gid locally which means
- that the uid for the file can change when the inode is
- reloaded (or the user remounts the share).
- nosetuids The client will not attempt to set the uid and gid on
- on newly created files, directories, and devices (create,
- mkdir, mknod) which will result in the server setting the
- uid and gid to the default (usually the server uid of the
- user who mounted the share). Letting the server (rather than
- the client) set the uid and gid is the default. If the CIFS
- Unix Extensions are not negotiated then the uid and gid for
- new files will appear to be the uid (gid) of the mounter or the
- uid (gid) parameter specified on the mount.
- netbiosname When mounting to servers via port 139, specifies the RFC1001
- source name to use to represent the client netbios machine
- name when doing the RFC1001 netbios session initialize.
- direct Do not do inode data caching on files opened on this mount.
- This precludes mmapping files on this mount. In some cases
- with fast networks and little or no caching benefits on the
- client (e.g. when the application is doing large sequential
- reads bigger than page size without rereading the same data)
- this can provide better performance than the default
- behavior which caches reads (readahead) and writes
- (writebehind) through the local Linux client pagecache
- if oplock (caching token) is granted and held. Note that
- direct allows write operations larger than page size
- to be sent to the server.
- strictcache Use for switching on strict cache mode. In this mode the
- client read from the cache all the time it has Oplock Level II,
- otherwise - read from the server. All written data are stored
- in the cache, but if the client doesn't have Exclusive Oplock,
- it writes the data to the server.
- rwpidforward Forward pid of a process who opened a file to any read or write
- operation on that file. This prevent applications like WINE
- from failing on read and write if we use mandatory brlock style.
- acl Allow setfacl and getfacl to manage posix ACLs if server
- supports them. (default)
- noacl Do not allow setfacl and getfacl calls on this mount
- user_xattr Allow getting and setting user xattrs (those attributes whose
- name begins with "user." or "os2.") as OS/2 EAs (extended
- attributes) to the server. This allows support of the
- setfattr and getfattr utilities. (default)
- nouser_xattr Do not allow getfattr/setfattr to get/set/list xattrs
- mapchars Translate six of the seven reserved characters (not backslash)
- *?<>|:
- to the remap range (above 0xF000), which also
- allows the CIFS client to recognize files created with
- such characters by Windows's POSIX emulation. This can
- also be useful when mounting to most versions of Samba
- (which also forbids creating and opening files
- whose names contain any of these seven characters).
- This has no effect if the server does not support
- Unicode on the wire.
- nomapchars Do not translate any of these seven characters (default).
- nocase Request case insensitive path name matching (case
- sensitive is the default if the server supports it).
- (mount option "ignorecase" is identical to "nocase")
- posixpaths If CIFS Unix extensions are supported, attempt to
- negotiate posix path name support which allows certain
- characters forbidden in typical CIFS filenames, without
- requiring remapping. (default)
- noposixpaths If CIFS Unix extensions are supported, do not request
- posix path name support (this may cause servers to
- reject creatingfile with certain reserved characters).
- nounix Disable the CIFS Unix Extensions for this mount (tree
- connection). This is rarely needed, but it may be useful
- in order to turn off multiple settings all at once (ie
- posix acls, posix locks, posix paths, symlink support
- and retrieving uids/gids/mode from the server) or to
- work around a bug in server which implement the Unix
- Extensions.
- nobrl Do not send byte range lock requests to the server.
- This is necessary for certain applications that break
- with cifs style mandatory byte range locks (and most
- cifs servers do not yet support requesting advisory
- byte range locks).
- forcemandatorylock Even if the server supports posix (advisory) byte range
- locking, send only mandatory lock requests. For some
- (presumably rare) applications, originally coded for
- DOS/Windows, which require Windows style mandatory byte range
- locking, they may be able to take advantage of this option,
- forcing the cifs client to only send mandatory locks
- even if the cifs server would support posix advisory locks.
- "forcemand" is accepted as a shorter form of this mount
- option.
- nostrictsync If this mount option is set, when an application does an
- fsync call then the cifs client does not send an SMB Flush
- to the server (to force the server to write all dirty data
- for this file immediately to disk), although cifs still sends
- all dirty (cached) file data to the server and waits for the
- server to respond to the write. Since SMB Flush can be
- very slow, and some servers may be reliable enough (to risk
- delaying slightly flushing the data to disk on the server),
- turning on this option may be useful to improve performance for
- applications that fsync too much, at a small risk of server
- crash. If this mount option is not set, by default cifs will
- send an SMB flush request (and wait for a response) on every
- fsync call.
- nodfs Disable DFS (global name space support) even if the
- server claims to support it. This can help work around
- a problem with parsing of DFS paths with Samba server
- versions 3.0.24 and 3.0.25.
- remount remount the share (often used to change from ro to rw mounts
- or vice versa)
- cifsacl Report mode bits (e.g. on stat) based on the Windows ACL for
- the file. (EXPERIMENTAL)
- servern Specify the server 's netbios name (RFC1001 name) to use
- when attempting to setup a session to the server.
- This is needed for mounting to some older servers (such
- as OS/2 or Windows 98 and Windows ME) since they do not
- support a default server name. A server name can be up
- to 15 characters long and is usually uppercased.
- sfu When the CIFS Unix Extensions are not negotiated, attempt to
- create device files and fifos in a format compatible with
- Services for Unix (SFU). In addition retrieve bits 10-12
- of the mode via the SETFILEBITS extended attribute (as
- SFU does). In the future the bottom 9 bits of the
- mode also will be emulated using queries of the security
- descriptor (ACL).
- mfsymlinks Enable support for Minshall+French symlinks
- (see http://wiki.samba.org/index.php/UNIX_Extensions#Minshall.2BFrench_symlinks)
- This option is ignored when specified together with the
- 'sfu' option. Minshall+French symlinks are used even if
- the server supports the CIFS Unix Extensions.
- sign Must use packet signing (helps avoid unwanted data modification
- by intermediate systems in the route). Note that signing
- does not work with lanman or plaintext authentication.
- seal Must seal (encrypt) all data on this mounted share before
- sending on the network. Requires support for Unix Extensions.
- Note that this differs from the sign mount option in that it
- causes encryption of data sent over this mounted share but other
- shares mounted to the same server are unaffected.
- locallease This option is rarely needed. Fcntl F_SETLEASE is
- used by some applications such as Samba and NFSv4 server to
- check to see whether a file is cacheable. CIFS has no way
- to explicitly request a lease, but can check whether a file
- is cacheable (oplocked). Unfortunately, even if a file
- is not oplocked, it could still be cacheable (ie cifs client
- could grant fcntl leases if no other local processes are using
- the file) for cases for example such as when the server does not
- support oplocks and the user is sure that the only updates to
- the file will be from this client. Specifying this mount option
- will allow the cifs client to check for leases (only) locally
- for files which are not oplocked instead of denying leases
- in that case. (EXPERIMENTAL)
- sec Security mode. Allowed values are:
- none attempt to connection as a null user (no name)
- krb5 Use Kerberos version 5 authentication
- krb5i Use Kerberos authentication and packet signing
- ntlm Use NTLM password hashing (default)
- ntlmi Use NTLM password hashing with signing (if
- /proc/fs/cifs/PacketSigningEnabled on or if
- server requires signing also can be the default)
- ntlmv2 Use NTLMv2 password hashing
- ntlmv2i Use NTLMv2 password hashing with packet signing
- lanman (if configured in kernel config) use older
- lanman hash
-hard Retry file operations if server is not responding
-soft Limit retries to unresponsive servers (usually only
- one retry) before returning an error. (default)
-
-The mount.cifs mount helper also accepts a few mount options before -o
-including:
-
- -S take password from stdin (equivalent to setting the environment
- variable "PASSWD_FD=0"
- -V print mount.cifs version
- -? display simple usage information
-
-With most 2.6 kernel versions of modutils, the version of the cifs kernel
-module can be displayed via modinfo.
-
-Misc /proc/fs/cifs Flags and Debug Info
-=======================================
-Informational pseudo-files:
-DebugData Displays information about active CIFS sessions and
- shares, features enabled as well as the cifs.ko
- version.
-Stats Lists summary resource usage information as well as per
- share statistics.
-
-Configuration pseudo-files:
-SecurityFlags Flags which control security negotiation and
- also packet signing. Authentication (may/must)
- flags (e.g. for NTLM and/or NTLMv2) may be combined with
- the signing flags. Specifying two different password
- hashing mechanisms (as "must use") on the other hand
- does not make much sense. Default flags are
- 0x07007
- (NTLM, NTLMv2 and packet signing allowed). The maximum
- allowable flags if you want to allow mounts to servers
- using weaker password hashes is 0x37037 (lanman,
- plaintext, ntlm, ntlmv2, signing allowed). Some
- SecurityFlags require the corresponding menuconfig
- options to be enabled (lanman and plaintext require
- CONFIG_CIFS_WEAK_PW_HASH for example). Enabling
- plaintext authentication currently requires also
- enabling lanman authentication in the security flags
- because the cifs module only supports sending
- laintext passwords using the older lanman dialect
- form of the session setup SMB. (e.g. for authentication
- using plain text passwords, set the SecurityFlags
- to 0x30030):
-
- may use packet signing 0x00001
- must use packet signing 0x01001
- may use NTLM (most common password hash) 0x00002
- must use NTLM 0x02002
- may use NTLMv2 0x00004
- must use NTLMv2 0x04004
- may use Kerberos security 0x00008
- must use Kerberos 0x08008
- may use lanman (weak) password hash 0x00010
- must use lanman password hash 0x10010
- may use plaintext passwords 0x00020
- must use plaintext passwords 0x20020
- (reserved for future packet encryption) 0x00040
-
-cifsFYI If set to non-zero value, additional debug information
- will be logged to the system error log. This field
- contains three flags controlling different classes of
- debugging entries. The maximum value it can be set
- to is 7 which enables all debugging points (default 0).
- Some debugging statements are not compiled into the
- cifs kernel unless CONFIG_CIFS_DEBUG2 is enabled in the
- kernel configuration. cifsFYI may be set to one or
- nore of the following flags (7 sets them all):
-
- log cifs informational messages 0x01
- log return codes from cifs entry points 0x02
- log slow responses (ie which take longer than 1 second)
- CONFIG_CIFS_STATS2 must be enabled in .config 0x04
-
-
-traceSMB If set to one, debug information is logged to the
- system error log with the start of smb requests
- and responses (default 0)
-LookupCacheEnable If set to one, inode information is kept cached
- for one second improving performance of lookups
- (default 1)
-LinuxExtensionsEnabled If set to one then the client will attempt to
- use the CIFS "UNIX" extensions which are optional
- protocol enhancements that allow CIFS servers
- to return accurate UID/GID information as well
- as support symbolic links. If you use servers
- such as Samba that support the CIFS Unix
- extensions but do not want to use symbolic link
- support and want to map the uid and gid fields
- to values supplied at mount (rather than the
- actual values, then set this to zero. (default 1)
-
-These experimental features and tracing can be enabled by changing flags in
-/proc/fs/cifs (after the cifs module has been installed or built into the
-kernel, e.g. insmod cifs). To enable a feature set it to 1 e.g. to enable
-tracing to the kernel message log type:
-
- echo 7 > /proc/fs/cifs/cifsFYI
-
-cifsFYI functions as a bit mask. Setting it to 1 enables additional kernel
-logging of various informational messages. 2 enables logging of non-zero
-SMB return codes while 4 enables logging of requests that take longer
-than one second to complete (except for byte range lock requests).
-Setting it to 4 requires CONFIG_CIFS_STATS2 to be set in kernel configuration
-(.config). Setting it to seven enables all three. Finally, tracing
-the start of smb requests and responses can be enabled via:
-
- echo 1 > /proc/fs/cifs/traceSMB
-
-Per share (per client mount) statistics are available in /proc/fs/cifs/Stats.
-Additional information is available if CONFIG_CIFS_STATS2 is enabled in the
-kernel configuration (.config). The statistics returned include counters which
-represent the number of attempted and failed (ie non-zero return code from the
-server) SMB3 (or cifs) requests grouped by request type (read, write, close etc.).
-Also recorded is the total bytes read and bytes written to the server for
-that share. Note that due to client caching effects this can be less than the
-number of bytes read and written by the application running on the client.
-Statistics can be reset to zero by "echo 0 > /proc/fs/cifs/Stats" which may be
-useful if comparing performance of two different scenarios.
-
-Also note that "cat /proc/fs/cifs/DebugData" will display information about
-the active sessions and the shares that are mounted.
-
-Enabling Kerberos (extended security) works but requires version 1.2 or later
-of the helper program cifs.upcall to be present and to be configured in the
-/etc/request-key.conf file. The cifs.upcall helper program is from the Samba
-project(http://www.samba.org). NTLM and NTLMv2 and LANMAN support do not
-require this helper. Note that NTLMv2 security (which does not require the
-cifs.upcall helper program), instead of using Kerberos, is sufficient for
-some use cases.
-
-DFS support allows transparent redirection to shares in an MS-DFS name space.
-In addition, DFS support for target shares which are specified as UNC
-names which begin with host names (rather than IP addresses) requires
-a user space helper (such as cifs.upcall) to be present in order to
-translate host names to ip address, and the user space helper must also
-be configured in the file /etc/request-key.conf. Samba, Windows servers and
-many NAS appliances support DFS as a way of constructing a global name
-space to ease network configuration and improve reliability.
-
-To use cifs Kerberos and DFS support, the Linux keyutils package should be
-installed and something like the following lines should be added to the
-/etc/request-key.conf file:
-
-create cifs.spnego * * /usr/local/sbin/cifs.upcall %k
-create dns_resolver * * /usr/local/sbin/cifs.upcall %k
-
-CIFS kernel module parameters
-=============================
-These module parameters can be specified or modified either during the time of
-module loading or during the runtime by using the interface
- /proc/module/cifs/parameters/<param>
-
-i.e. echo "value" > /sys/module/cifs/parameters/<param>
-
-1. enable_oplocks - Enable or disable oplocks. Oplocks are enabled by default.
- [Y/y/1]. To disable use any of [N/n/0].
-
diff --git a/Documentation/filesystems/cifs/TODO b/Documentation/filesystems/cifs/TODO
deleted file mode 100644
index edbbccd..0000000
--- a/Documentation/filesystems/cifs/TODO
+++ /dev/null
@@ -1,125 +0,0 @@
-Version 2.14 December 21, 2018
-
-A Partial List of Missing Features
-==================================
-
-Contributions are welcome. There are plenty of opportunities
-for visible, important contributions to this module. Here
-is a partial list of the known problems and missing features:
-
-a) SMB3 (and SMB3.1.1) missing optional features:
- - multichannel (started), integration with RDMA
- - directory leases (improved metadata caching), started (root dir only)
- - T10 copy offload ie "ODX" (copy chunk, and "Duplicate Extents" ioctl
- currently the only two server side copy mechanisms supported)
-
-b) improved sparse file support (fiemap and SEEK_HOLE are implemented
-but additional features would be supportable by the protocol).
-
-c) Directory entry caching relies on a 1 second timer, rather than
-using Directory Leases, currently only the root file handle is cached longer
-
-d) quota support (needs minor kernel change since quota calls
-to make it to network filesystems or deviceless filesystems)
-
-e) Additional use cases can be optimized to use "compounding"
-(e.g. open/query/close and open/setinfo/close) to reduce the number
-of roundtrips to the server and improve performance. Various cases
-(stat, statfs, create, unlink, mkdir) already have been improved by
-using compounding but more can be done. In addition we could significantly
-reduce redundant opens by using deferred close (with handle caching leases)
-and better using reference counters on file handles.
-
-f) Finish inotify support so kde and gnome file list windows
-will autorefresh (partially complete by Asser). Needs minor kernel
-vfs change to support removing D_NOTIFY on a file.
-
-g) Add GUI tool to configure /proc/fs/cifs settings and for display of
-the CIFS statistics (started)
-
-h) implement support for security and trusted categories of xattrs
-(requires minor protocol extension) to enable better support for SELINUX
-
-i) Add support for tree connect contexts (see MS-SMB2) a new SMB3.1.1 protocol
- feature (may be especially useful for virtualization).
-
-j) Create UID mapping facility so server UIDs can be mapped on a per
-mount or a per server basis to client UIDs or nobody if no mapping
-exists. Also better integration with winbind for resolving SID owners
-
-k) Add tools to take advantage of more smb3 specific ioctls and features
-(passthrough ioctl/fsctl is now implemented in cifs.ko to allow sending
-various SMB3 fsctls and query info and set info calls directly from user space)
-Add tools to make setting various non-POSIX metadata attributes easier
-from tools (e.g. extending what was done in smb-info tool).
-
-l) encrypted file support
-
-m) improved stats gathering tools (perhaps integration with nfsometer?)
-to extend and make easier to use what is currently in /proc/fs/cifs/Stats
-
-n) Add support for claims based ACLs ("DAC")
-
-o) mount helper GUI (to simplify the various configuration options on mount)
-
-p) Add support for witness protocol (perhaps ioctl to cifs.ko from user space
- tool listening on witness protocol RPC) to allow for notification of share
- move, server failover, and server adapter changes. And also improve other
- failover scenarios, e.g. when client knows multiple DFS entries point to
- different servers, and the server we are connected to has gone down.
-
-q) Allow mount.cifs to be more verbose in reporting errors with dialect
-or unsupported feature errors.
-
-r) updating cifs documentation, and user guide.
-
-s) Addressing bugs found by running a broader set of xfstests in standard
-file system xfstest suite.
-
-t) split cifs and smb3 support into separate modules so legacy (and less
-secure) CIFS dialect can be disabled in environments that don't need it
-and simplify the code.
-
-v) POSIX Extensions for SMB3.1.1 (started, create and mkdir support added
-so far).
-
-w) Add support for additional strong encryption types, and additional spnego
-authentication mechanisms (see MS-SMB2)
-
-x) Finish support for SMB3.1.1 compression
-
-KNOWN BUGS
-====================================
-See http://bugzilla.samba.org - search on product "CifsVFS" for
-current bug list. Also check http://bugzilla.kernel.org (Product = File System, Component = CIFS)
-
-1) existing symbolic links (Windows reparse points) are recognized but
-can not be created remotely. They are implemented for Samba and those that
-support the CIFS Unix extensions, although earlier versions of Samba
-overly restrict the pathnames.
-2) follow_link and readdir code does not follow dfs junctions
-but recognizes them
-
-Misc testing to do
-==================
-1) check out max path names and max path name components against various server
-types. Try nested symlinks (8 deep). Return max path name in stat -f information
-
-2) Improve xfstest's cifs/smb3 enablement and adapt xfstests where needed to test
-cifs/smb3 better
-
-3) Additional performance testing and optimization using iozone and similar -
-there are some easy changes that can be done to parallelize sequential writes,
-and when signing is disabled to request larger read sizes (larger than
-negotiated size) and send larger write sizes to modern servers.
-
-4) More exhaustively test against less common servers
-
-5) Continue to extend the smb3 "buildbot" which does automated xfstesting
-against Windows, Samba and Azure currently - to add additional tests and
-to allow the buildbot to execute the tests faster. The URL for the
-buildbot is: http://smb3-test-rhel-75.southcentralus.cloudapp.azure.com
-
-6) Address various coverity warnings (most are not bugs per-se, but
-the more warnings are addressed, the easier it is to spot real
-problems that static analyzers will point out in the future).
diff --git a/Documentation/filesystems/cifs/cifs.txt b/Documentation/filesystems/cifs/cifs.txt
deleted file mode 100644
index 1be3d21..0000000
--- a/Documentation/filesystems/cifs/cifs.txt
+++ /dev/null
@@ -1,45 +0,0 @@
- This is the client VFS module for the SMB3 NAS protocol as well
- as for older dialects such as the Common Internet File System (CIFS)
- protocol which was the successor to the Server Message Block
- (SMB) protocol, the native file sharing mechanism for most early
- PC operating systems. New and improved versions of CIFS are now
- called SMB2 and SMB3. Use of SMB3 (and later, including SMB3.1.1)
- is strongly preferred over using older dialects like CIFS due to
- security reaasons. All modern dialects, including the most recent,
- SMB3.1.1 are supported by the CIFS VFS module. The SMB3 protocol
- is implemented and supported by all major file servers
- such as all modern versions of Windows (including Windows 2016
- Server), as well as by Samba (which provides excellent
- CIFS/SMB2/SMB3 server support and tools for Linux and many other
- operating systems). Apple systems also support SMB3 well, as
- do most Network Attached Storage vendors, so this network
- filesystem client can mount to a wide variety of systems.
- It also supports mounting to the cloud (for example
- Microsoft Azure), including the necessary security features.
-
- The intent of this module is to provide the most advanced network
- file system function for SMB3 compliant servers, including advanced
- security features, excellent parallelized high performance i/o, better
- POSIX compliance, secure per-user session establishment, encryption,
- high performance safe distributed caching (leases/oplocks), optional packet
- signing, large files, Unicode support and other internationalization
- improvements. Since both Samba server and this filesystem client support
- the CIFS Unix extensions (and in the future SMB3 POSIX extensions),
- the combination can provide a reasonable alternative to other network and
- cluster file systems for fileserving in some Linux to Linux environments,
- not just in Linux to Windows (or Linux to Mac) environments.
-
- This filesystem has a mount utility (mount.cifs) and various user space
- tools (including smbinfo and setcifsacl) that can be obtained from
-
- https://git.samba.org/?p=cifs-utils.git
- or
- git://git.samba.org/cifs-utils.git
-
- mount.cifs should be installed in the directory with the other mount helpers.
-
- For more information on the module see the project wiki page at
-
- https://wiki.samba.org/index.php/LinuxCIFS
- and
- https://wiki.samba.org/index.php/LinuxCIFS_utils
diff --git a/Documentation/filesystems/cifs/cifsroot.txt b/Documentation/filesystems/cifs/cifsroot.txt
new file mode 100644
index 0000000..0fa1a2c
--- /dev/null
+++ b/Documentation/filesystems/cifs/cifsroot.txt
@@ -0,0 +1,97 @@
+Mounting root file system via SMB (cifs.ko)
+===========================================
+
+Written 2019 by Paulo Alcantara <palcantara@suse.de>
+Written 2019 by Aurelien Aptel <aaptel@suse.com>
+
+The CONFIG_CIFS_ROOT option enables experimental root file system
+support over the SMB protocol via cifs.ko.
+
+It introduces a new kernel command-line option called 'cifsroot='
+which will tell the kernel to mount the root file system over the
+network by utilizing SMB or CIFS protocol.
+
+In order to mount, the network stack will also need to be set up by
+using 'ip=' config option. For more details, see
+Documentation/filesystems/nfs/nfsroot.txt.
+
+A CIFS root mount currently requires the use of SMB1+UNIX Extensions
+which is only supported by the Samba server. SMB1 is the older
+deprecated version of the protocol but it has been extended to support
+POSIX features (See [1]). The equivalent extensions for the newer
+recommended version of the protocol (SMB3) have not been fully
+implemented yet which means SMB3 doesn't support some required POSIX
+file system objects (e.g. block devices, pipes, sockets).
+
+As a result, a CIFS root will default to SMB1 for now but the version
+to use can nonetheless be changed via the 'vers=' mount option. This
+default will change once the SMB3 POSIX extensions are fully
+implemented.
+
+Server configuration
+====================
+
+To enable SMB1+UNIX extensions you will need to set these global
+settings in Samba smb.conf:
+
+ [global]
+ server min protocol = NT1
+ unix extension = yes # default
+
+Kernel command line
+===================
+
+root=/dev/cifs
+
+This is just a virtual device that basically tells the kernel to mount
+the root file system via SMB protocol.
+
+cifsroot=//<server-ip>/<share>[,options]
+
+Enables the kernel to mount the root file system via SMB that are
+located in the <server-ip> and <share> specified in this option.
+
+The default mount options are set in fs/cifs/cifsroot.c.
+
+server-ip
+ IPv4 address of the server.
+
+share
+ Path to SMB share (rootfs).
+
+options
+ Optional mount options. For more information, see mount.cifs(8).
+
+Examples
+========
+
+Export root file system as a Samba share in smb.conf file.
+
+...
+[linux]
+ path = /path/to/rootfs
+ read only = no
+ guest ok = yes
+ force user = root
+ force group = root
+ browseable = yes
+ writeable = yes
+ admin users = root
+ public = yes
+ create mask = 0777
+ directory mask = 0777
+...
+
+Restart smb service.
+
+# systemctl restart smb
+
+Test it under QEMU on a kernel built with CONFIG_CIFS_ROOT and
+CONFIG_IP_PNP options enabled.
+
+# qemu-system-x86_64 -enable-kvm -cpu host -m 1024 \
+ -kernel /path/to/linux/arch/x86/boot/bzImage -nographic \
+ -append "root=/dev/cifs rw ip=dhcp cifsroot=//10.0.2.2/linux,username=foo,password=bar console=ttyS0 3"
+
+
+1: https://wiki.samba.org/index.php/UNIX_Extensions
diff --git a/Documentation/filesystems/coda.txt b/Documentation/filesystems/coda.txt
index 545262c..1711ad4 100644
--- a/Documentation/filesystems/coda.txt
+++ b/Documentation/filesystems/coda.txt
@@ -421,14 +421,14 @@
The CodaCred structure defines a variety of user and group ids as
- they are set for the calling process. The vuid_t and guid_t are 32 bit
+ they are set for the calling process. The vuid_t and vgid_t are 32 bit
unsigned integers. It also defines group membership in an array. On
Unix the CodaCred has proven sufficient to implement good security
semantics for Coda but the structure may have to undergo modification
for the Windows environment when these mature.
struct CodaCred {
- vuid_t cr_uid, cr_euid, cr_suid, cr_fsuid; /* Real, effective, set, fs uid*/
+ vuid_t cr_uid, cr_euid, cr_suid, cr_fsuid; /* Real, effective, set, fs uid */
vgid_t cr_gid, cr_egid, cr_sgid, cr_fsgid; /* same for groups */
vgid_t cr_groups[NGROUPS]; /* Group membership for caller */
};
diff --git a/Documentation/filesystems/directory-locking b/Documentation/filesystems/directory-locking
deleted file mode 100644
index 4e32cb9..0000000
--- a/Documentation/filesystems/directory-locking
+++ /dev/null
@@ -1,135 +0,0 @@
- Locking scheme used for directory operations is based on two
-kinds of locks - per-inode (->i_rwsem) and per-filesystem
-(->s_vfs_rename_mutex).
-
- When taking the i_rwsem on multiple non-directory objects, we
-always acquire the locks in order by increasing address. We'll call
-that "inode pointer" order in the following.
-
- For our purposes all operations fall in 5 classes:
-
-1) read access. Locking rules: caller locks directory we are accessing.
-The lock is taken shared.
-
-2) object creation. Locking rules: same as above, but the lock is taken
-exclusive.
-
-3) object removal. Locking rules: caller locks parent, finds victim,
-locks victim and calls the method. Locks are exclusive.
-
-4) rename() that is _not_ cross-directory. Locking rules: caller locks
-the parent and finds source and target. In case of exchange (with
-RENAME_EXCHANGE in flags argument) lock both. In any case,
-if the target already exists, lock it. If the source is a non-directory,
-lock it. If we need to lock both, lock them in inode pointer order.
-Then call the method. All locks are exclusive.
-NB: we might get away with locking the the source (and target in exchange
-case) shared.
-
-5) link creation. Locking rules:
- * lock parent
- * check that source is not a directory
- * lock source
- * call the method.
-All locks are exclusive.
-
-6) cross-directory rename. The trickiest in the whole bunch. Locking
-rules:
- * lock the filesystem
- * lock parents in "ancestors first" order.
- * find source and target.
- * if old parent is equal to or is a descendent of target
- fail with -ENOTEMPTY
- * if new parent is equal to or is a descendent of source
- fail with -ELOOP
- * If it's an exchange, lock both the source and the target.
- * If the target exists, lock it. If the source is a non-directory,
- lock it. If we need to lock both, do so in inode pointer order.
- * call the method.
-All ->i_rwsem are taken exclusive. Again, we might get away with locking
-the the source (and target in exchange case) shared.
-
-The rules above obviously guarantee that all directories that are going to be
-read, modified or removed by method will be locked by caller.
-
-
-If no directory is its own ancestor, the scheme above is deadlock-free.
-Proof:
-
- First of all, at any moment we have a partial ordering of the
-objects - A < B iff A is an ancestor of B.
-
- That ordering can change. However, the following is true:
-
-(1) if object removal or non-cross-directory rename holds lock on A and
- attempts to acquire lock on B, A will remain the parent of B until we
- acquire the lock on B. (Proof: only cross-directory rename can change
- the parent of object and it would have to lock the parent).
-
-(2) if cross-directory rename holds the lock on filesystem, order will not
- change until rename acquires all locks. (Proof: other cross-directory
- renames will be blocked on filesystem lock and we don't start changing
- the order until we had acquired all locks).
-
-(3) locks on non-directory objects are acquired only after locks on
- directory objects, and are acquired in inode pointer order.
- (Proof: all operations but renames take lock on at most one
- non-directory object, except renames, which take locks on source and
- target in inode pointer order in the case they are not directories.)
-
- Now consider the minimal deadlock. Each process is blocked on
-attempt to acquire some lock and already holds at least one lock. Let's
-consider the set of contended locks. First of all, filesystem lock is
-not contended, since any process blocked on it is not holding any locks.
-Thus all processes are blocked on ->i_rwsem.
-
- By (3), any process holding a non-directory lock can only be
-waiting on another non-directory lock with a larger address. Therefore
-the process holding the "largest" such lock can always make progress, and
-non-directory objects are not included in the set of contended locks.
-
- Thus link creation can't be a part of deadlock - it can't be
-blocked on source and it means that it doesn't hold any locks.
-
- Any contended object is either held by cross-directory rename or
-has a child that is also contended. Indeed, suppose that it is held by
-operation other than cross-directory rename. Then the lock this operation
-is blocked on belongs to child of that object due to (1).
-
- It means that one of the operations is cross-directory rename.
-Otherwise the set of contended objects would be infinite - each of them
-would have a contended child and we had assumed that no object is its
-own descendent. Moreover, there is exactly one cross-directory rename
-(see above).
-
- Consider the object blocking the cross-directory rename. One
-of its descendents is locked by cross-directory rename (otherwise we
-would again have an infinite set of contended objects). But that
-means that cross-directory rename is taking locks out of order. Due
-to (2) the order hadn't changed since we had acquired filesystem lock.
-But locking rules for cross-directory rename guarantee that we do not
-try to acquire lock on descendent before the lock on ancestor.
-Contradiction. I.e. deadlock is impossible. Q.E.D.
-
-
- These operations are guaranteed to avoid loop creation. Indeed,
-the only operation that could introduce loops is cross-directory rename.
-Since the only new (parent, child) pair added by rename() is (new parent,
-source), such loop would have to contain these objects and the rest of it
-would have to exist before rename(). I.e. at the moment of loop creation
-rename() responsible for that would be holding filesystem lock and new parent
-would have to be equal to or a descendent of source. But that means that
-new parent had been equal to or a descendent of source since the moment when
-we had acquired filesystem lock and rename() would fail with -ELOOP in that
-case.
-
- While this locking scheme works for arbitrary DAGs, it relies on
-ability to check that directory is a descendent of another object. Current
-implementation assumes that directory graph is a tree. This assumption is
-also preserved by all operations (cross-directory rename on a tree that would
-not introduce a cycle will leave it a tree and link() fails for directories).
-
- Notice that "directory" in the above == "anything that might have
-children", so if we are going to introduce hybrid objects we will need
-either to make sure that link(2) doesn't work for them or to make changes
-in is_subdir() that would make it work even in presence of such beasts.
diff --git a/Documentation/filesystems/directory-locking.rst b/Documentation/filesystems/directory-locking.rst
new file mode 100644
index 0000000..de12016
--- /dev/null
+++ b/Documentation/filesystems/directory-locking.rst
@@ -0,0 +1,145 @@
+=================
+Directory Locking
+=================
+
+
+Locking scheme used for directory operations is based on two
+kinds of locks - per-inode (->i_rwsem) and per-filesystem
+(->s_vfs_rename_mutex).
+
+When taking the i_rwsem on multiple non-directory objects, we
+always acquire the locks in order by increasing address. We'll call
+that "inode pointer" order in the following.
+
+For our purposes all operations fall in 5 classes:
+
+1) read access. Locking rules: caller locks directory we are accessing.
+The lock is taken shared.
+
+2) object creation. Locking rules: same as above, but the lock is taken
+exclusive.
+
+3) object removal. Locking rules: caller locks parent, finds victim,
+locks victim and calls the method. Locks are exclusive.
+
+4) rename() that is _not_ cross-directory. Locking rules: caller locks
+the parent and finds source and target. In case of exchange (with
+RENAME_EXCHANGE in flags argument) lock both. In any case,
+if the target already exists, lock it. If the source is a non-directory,
+lock it. If we need to lock both, lock them in inode pointer order.
+Then call the method. All locks are exclusive.
+NB: we might get away with locking the the source (and target in exchange
+case) shared.
+
+5) link creation. Locking rules:
+
+ * lock parent
+ * check that source is not a directory
+ * lock source
+ * call the method.
+
+All locks are exclusive.
+
+6) cross-directory rename. The trickiest in the whole bunch. Locking
+rules:
+
+ * lock the filesystem
+ * lock parents in "ancestors first" order.
+ * find source and target.
+ * if old parent is equal to or is a descendent of target
+ fail with -ENOTEMPTY
+ * if new parent is equal to or is a descendent of source
+ fail with -ELOOP
+ * If it's an exchange, lock both the source and the target.
+ * If the target exists, lock it. If the source is a non-directory,
+ lock it. If we need to lock both, do so in inode pointer order.
+ * call the method.
+
+All ->i_rwsem are taken exclusive. Again, we might get away with locking
+the the source (and target in exchange case) shared.
+
+The rules above obviously guarantee that all directories that are going to be
+read, modified or removed by method will be locked by caller.
+
+
+If no directory is its own ancestor, the scheme above is deadlock-free.
+
+Proof:
+
+ First of all, at any moment we have a partial ordering of the
+ objects - A < B iff A is an ancestor of B.
+
+ That ordering can change. However, the following is true:
+
+(1) if object removal or non-cross-directory rename holds lock on A and
+ attempts to acquire lock on B, A will remain the parent of B until we
+ acquire the lock on B. (Proof: only cross-directory rename can change
+ the parent of object and it would have to lock the parent).
+
+(2) if cross-directory rename holds the lock on filesystem, order will not
+ change until rename acquires all locks. (Proof: other cross-directory
+ renames will be blocked on filesystem lock and we don't start changing
+ the order until we had acquired all locks).
+
+(3) locks on non-directory objects are acquired only after locks on
+ directory objects, and are acquired in inode pointer order.
+ (Proof: all operations but renames take lock on at most one
+ non-directory object, except renames, which take locks on source and
+ target in inode pointer order in the case they are not directories.)
+
+Now consider the minimal deadlock. Each process is blocked on
+attempt to acquire some lock and already holds at least one lock. Let's
+consider the set of contended locks. First of all, filesystem lock is
+not contended, since any process blocked on it is not holding any locks.
+Thus all processes are blocked on ->i_rwsem.
+
+By (3), any process holding a non-directory lock can only be
+waiting on another non-directory lock with a larger address. Therefore
+the process holding the "largest" such lock can always make progress, and
+non-directory objects are not included in the set of contended locks.
+
+Thus link creation can't be a part of deadlock - it can't be
+blocked on source and it means that it doesn't hold any locks.
+
+Any contended object is either held by cross-directory rename or
+has a child that is also contended. Indeed, suppose that it is held by
+operation other than cross-directory rename. Then the lock this operation
+is blocked on belongs to child of that object due to (1).
+
+It means that one of the operations is cross-directory rename.
+Otherwise the set of contended objects would be infinite - each of them
+would have a contended child and we had assumed that no object is its
+own descendent. Moreover, there is exactly one cross-directory rename
+(see above).
+
+Consider the object blocking the cross-directory rename. One
+of its descendents is locked by cross-directory rename (otherwise we
+would again have an infinite set of contended objects). But that
+means that cross-directory rename is taking locks out of order. Due
+to (2) the order hadn't changed since we had acquired filesystem lock.
+But locking rules for cross-directory rename guarantee that we do not
+try to acquire lock on descendent before the lock on ancestor.
+Contradiction. I.e. deadlock is impossible. Q.E.D.
+
+
+These operations are guaranteed to avoid loop creation. Indeed,
+the only operation that could introduce loops is cross-directory rename.
+Since the only new (parent, child) pair added by rename() is (new parent,
+source), such loop would have to contain these objects and the rest of it
+would have to exist before rename(). I.e. at the moment of loop creation
+rename() responsible for that would be holding filesystem lock and new parent
+would have to be equal to or a descendent of source. But that means that
+new parent had been equal to or a descendent of source since the moment when
+we had acquired filesystem lock and rename() would fail with -ELOOP in that
+case.
+
+While this locking scheme works for arbitrary DAGs, it relies on
+ability to check that directory is a descendent of another object. Current
+implementation assumes that directory graph is a tree. This assumption is
+also preserved by all operations (cross-directory rename on a tree that would
+not introduce a cycle will leave it a tree and link() fails for directories).
+
+Notice that "directory" in the above == "anything that might have
+children", so if we are going to introduce hybrid objects we will need
+either to make sure that link(2) doesn't work for them or to make changes
+in is_subdir() that would make it work even in presence of such beasts.
diff --git a/Documentation/filesystems/erofs.txt b/Documentation/filesystems/erofs.txt
new file mode 100644
index 0000000..b0c0853
--- /dev/null
+++ b/Documentation/filesystems/erofs.txt
@@ -0,0 +1,210 @@
+Overview
+========
+
+EROFS file-system stands for Enhanced Read-Only File System. Different
+from other read-only file systems, it aims to be designed for flexibility,
+scalability, but be kept simple and high performance.
+
+It is designed as a better filesystem solution for the following scenarios:
+ - read-only storage media or
+
+ - part of a fully trusted read-only solution, which means it needs to be
+ immutable and bit-for-bit identical to the official golden image for
+ their releases due to security and other considerations and
+
+ - hope to save some extra storage space with guaranteed end-to-end performance
+ by using reduced metadata and transparent file compression, especially
+ for those embedded devices with limited memory (ex, smartphone);
+
+Here is the main features of EROFS:
+ - Little endian on-disk design;
+
+ - Currently 4KB block size (nobh) and therefore maximum 16TB address space;
+
+ - Metadata & data could be mixed by design;
+
+ - 2 inode versions for different requirements:
+ v1 v2
+ Inode metadata size: 32 bytes 64 bytes
+ Max file size: 4 GB 16 EB (also limited by max. vol size)
+ Max uids/gids: 65536 4294967296
+ File creation time: no yes (64 + 32-bit timestamp)
+ Max hardlinks: 65536 4294967296
+ Metadata reserved: 4 bytes 14 bytes
+
+ - Support extended attributes (xattrs) as an option;
+
+ - Support xattr inline and tail-end data inline for all files;
+
+ - Support POSIX.1e ACLs by using xattrs;
+
+ - Support transparent file compression as an option:
+ LZ4 algorithm with 4 KB fixed-output compression for high performance;
+
+The following git tree provides the file system user-space tools under
+development (ex, formatting tool mkfs.erofs):
+>> git://git.kernel.org/pub/scm/linux/kernel/git/xiang/erofs-utils.git
+
+Bugs and patches are welcome, please kindly help us and send to the following
+linux-erofs mailing list:
+>> linux-erofs mailing list <linux-erofs@lists.ozlabs.org>
+
+Mount options
+=============
+
+(no)user_xattr Setup Extended User Attributes. Note: xattr is enabled
+ by default if CONFIG_EROFS_FS_XATTR is selected.
+(no)acl Setup POSIX Access Control List. Note: acl is enabled
+ by default if CONFIG_EROFS_FS_POSIX_ACL is selected.
+cache_strategy=%s Select a strategy for cached decompression from now on:
+ disabled: In-place I/O decompression only;
+ readahead: Cache the last incomplete compressed physical
+ cluster for further reading. It still does
+ in-place I/O decompression for the rest
+ compressed physical clusters;
+ readaround: Cache the both ends of incomplete compressed
+ physical clusters for further reading.
+ It still does in-place I/O decompression
+ for the rest compressed physical clusters.
+
+On-disk details
+===============
+
+Summary
+-------
+Different from other read-only file systems, an EROFS volume is designed
+to be as simple as possible:
+
+ |-> aligned with the block size
+ ____________________________________________________________
+ | |SB| | ... | Metadata | ... | Data | Metadata | ... | Data |
+ |_|__|_|_____|__________|_____|______|__________|_____|______|
+ 0 +1K
+
+All data areas should be aligned with the block size, but metadata areas
+may not. All metadatas can be now observed in two different spaces (views):
+ 1. Inode metadata space
+ Each valid inode should be aligned with an inode slot, which is a fixed
+ value (32 bytes) and designed to be kept in line with v1 inode size.
+
+ Each inode can be directly found with the following formula:
+ inode offset = meta_blkaddr * block_size + 32 * nid
+
+ |-> aligned with 8B
+ |-> followed closely
+ + meta_blkaddr blocks |-> another slot
+ _____________________________________________________________________
+ | ... | inode | xattrs | extents | data inline | ... | inode ...
+ |________|_______|(optional)|(optional)|__(optional)_|_____|__________
+ |-> aligned with the inode slot size
+ . .
+ . .
+ . .
+ . .
+ . .
+ . .
+ .____________________________________________________|-> aligned with 4B
+ | xattr_ibody_header | shared xattrs | inline xattrs |
+ |____________________|_______________|_______________|
+ |-> 12 bytes <-|->x * 4 bytes<-| .
+ . . .
+ . . .
+ . . .
+ ._______________________________.______________________.
+ | id | id | id | id | ... | id | ent | ... | ent| ... |
+ |____|____|____|____|______|____|_____|_____|____|_____|
+ |-> aligned with 4B
+ |-> aligned with 4B
+
+ Inode could be 32 or 64 bytes, which can be distinguished from a common
+ field which all inode versions have -- i_advise:
+
+ __________________ __________________
+ | i_advise | | i_advise |
+ |__________________| |__________________|
+ | ... | | ... |
+ | | | |
+ |__________________| 32 bytes | |
+ | |
+ |__________________| 64 bytes
+
+ Xattrs, extents, data inline are followed by the corresponding inode with
+ proper alignes, and they could be optional for different data mappings,
+ _currently_ there are totally 3 valid data mappings supported:
+
+ 1) flat file data without data inline (no extent);
+ 2) fixed-output size data compression (must have extents);
+ 3) flat file data with tail-end data inline (no extent);
+
+ The size of the optional xattrs is indicated by i_xattr_count in inode
+ header. Large xattrs or xattrs shared by many different files can be
+ stored in shared xattrs metadata rather than inlined right after inode.
+
+ 2. Shared xattrs metadata space
+ Shared xattrs space is similar to the above inode space, started with
+ a specific block indicated by xattr_blkaddr, organized one by one with
+ proper align.
+
+ Each share xattr can also be directly found by the following formula:
+ xattr offset = xattr_blkaddr * block_size + 4 * xattr_id
+
+ |-> aligned by 4 bytes
+ + xattr_blkaddr blocks |-> aligned with 4 bytes
+ _________________________________________________________________________
+ | ... | xattr_entry | xattr data | ... | xattr_entry | xattr data ...
+ |________|_____________|_____________|_____|______________|_______________
+
+Directories
+-----------
+All directories are now organized in a compact on-disk format. Note that
+each directory block is divided into index and name areas in order to support
+random file lookup, and all directory entries are _strictly_ recorded in
+alphabetical order in order to support improved prefix binary search
+algorithm (could refer to the related source code).
+
+ ___________________________
+ / |
+ / ______________|________________
+ / / | nameoff1 | nameoffN-1
+ ____________.______________._______________v________________v__________
+| dirent | dirent | ... | dirent | filename | filename | ... | filename |
+|___.0___|____1___|_____|___N-1__|____0_____|____1_____|_____|___N-1____|
+ \ ^
+ \ | * could have
+ \ | trailing '\0'
+ \________________________| nameoff0
+
+ Directory block
+
+Note that apart from the offset of the first filename, nameoff0 also indicates
+the total number of directory entries in this block since it is no need to
+introduce another on-disk field at all.
+
+Compression
+-----------
+Currently, EROFS supports 4KB fixed-output clustersize transparent file
+compression, as illustrated below:
+
+ |---- Variant-Length Extent ----|-------- VLE --------|----- VLE -----
+ clusterofs clusterofs clusterofs
+ | | | logical data
+_________v_______________________________v_____________________v_______________
+... | . | | . | | . | ...
+____|____.________|_____________|________.____|_____________|__.__________|____
+ |-> cluster <-|-> cluster <-|-> cluster <-|-> cluster <-|-> cluster <-|
+ size size size size size
+ . . . .
+ . . . .
+ . . . .
+ _______._____________._____________._____________._____________________
+ ... | | | | ... physical data
+ _______|_____________|_____________|_____________|_____________________
+ |-> cluster <-|-> cluster <-|-> cluster <-|
+ size size size
+
+Currently each on-disk physical cluster can contain 4KB (un)compressed data
+at most. For each logical cluster, there is a corresponding on-disk index to
+describe its cluster type, physical cluster address, etc.
+
+See "struct z_erofs_vle_decompressed_index" in erofs_fs.h for more details.
+
diff --git a/Documentation/filesystems/ext4/bigalloc.rst b/Documentation/filesystems/ext4/bigalloc.rst
index c6d8855..72075aa 100644
--- a/Documentation/filesystems/ext4/bigalloc.rst
+++ b/Documentation/filesystems/ext4/bigalloc.rst
@@ -9,14 +9,26 @@
exceeds the page size. However, for a filesystem of mostly huge files,
it is desirable to be able to allocate disk blocks in units of multiple
blocks to reduce both fragmentation and metadata overhead. The
-`bigalloc <Bigalloc>`__ feature provides exactly this ability. The
-administrator can set a block cluster size at mkfs time (which is stored
-in the s\_log\_cluster\_size field in the superblock); from then on, the
-block bitmaps track clusters, not individual blocks. This means that
-block groups can be several gigabytes in size (instead of just 128MiB);
-however, the minimum allocation unit becomes a cluster, not a block,
-even for directories. TaoBao had a patchset to extend the “use units of
-clusters instead of blocks” to the extent tree, though it is not clear
-where those patches went-- they eventually morphed into “extent tree v2”
-but that code has not landed as of May 2015.
+bigalloc feature provides exactly this ability.
+
+The bigalloc feature (EXT4_FEATURE_RO_COMPAT_BIGALLOC) changes ext4 to
+use clustered allocation, so that each bit in the ext4 block allocation
+bitmap addresses a power of two number of blocks. For example, if the
+file system is mainly going to be storing large files in the 4-32
+megabyte range, it might make sense to set a cluster size of 1 megabyte.
+This means that each bit in the block allocation bitmap now addresses
+256 4k blocks. This shrinks the total size of the block allocation
+bitmaps for a 2T file system from 64 megabytes to 256 kilobytes. It also
+means that a block group addresses 32 gigabytes instead of 128 megabytes,
+also shrinking the amount of file system overhead for metadata.
+
+The administrator can set a block cluster size at mkfs time (which is
+stored in the s\_log\_cluster\_size field in the superblock); from then
+on, the block bitmaps track clusters, not individual blocks. This means
+that block groups can be several gigabytes in size (instead of just
+128MiB); however, the minimum allocation unit becomes a cluster, not a
+block, even for directories. TaoBao had a patchset to extend the “use
+units of clusters instead of blocks” to the extent tree, though it is
+not clear where those patches went-- they eventually morphed into
+“extent tree v2” but that code has not landed as of May 2015.
diff --git a/Documentation/filesystems/ext4/blockgroup.rst b/Documentation/filesystems/ext4/blockgroup.rst
index baf888e..3da1566 100644
--- a/Documentation/filesystems/ext4/blockgroup.rst
+++ b/Documentation/filesystems/ext4/blockgroup.rst
@@ -71,11 +71,11 @@
superblock, group descriptors, data block bitmaps for groups 0-3, inode
bitmaps for groups 0-3, inode tables for groups 0-3, and the remaining
space in group 0 is for file data. The effect of this is to group the
-block metadata close together for faster loading, and to enable large
-files to be continuous on disk. Backup copies of the superblock and
-group descriptors are always at the beginning of block groups, even if
-flex\_bg is enabled. The number of block groups that make up a flex\_bg
-is given by 2 ^ ``sb.s_log_groups_per_flex``.
+block group metadata close together for faster loading, and to enable
+large files to be continuous on disk. Backup copies of the superblock
+and group descriptors are always at the beginning of block groups, even
+if flex\_bg is enabled. The number of block groups that make up a
+flex\_bg is given by 2 ^ ``sb.s_log_groups_per_flex``.
Meta Block Groups
-----------------
diff --git a/Documentation/filesystems/ext4/blocks.rst b/Documentation/filesystems/ext4/blocks.rst
index 73d4dc0..bd722ec 100644
--- a/Documentation/filesystems/ext4/blocks.rst
+++ b/Documentation/filesystems/ext4/blocks.rst
@@ -10,7 +10,9 @@
4KiB. You may experience mounting problems if block size is greater than
page size (i.e. 64KiB blocks on a i386 which only has 4KiB memory
pages). By default a filesystem can contain 2^32 blocks; if the '64bit'
-feature is enabled, then a filesystem can have 2^64 blocks.
+feature is enabled, then a filesystem can have 2^64 blocks. The location
+of structures is stored in terms of the block number the structure lives
+in and not the absolute offset on disk.
For 32-bit filesystems, limits are as follows:
diff --git a/Documentation/filesystems/ext4/directory.rst b/Documentation/filesystems/ext4/directory.rst
index 614034e..073940c 100644
--- a/Documentation/filesystems/ext4/directory.rst
+++ b/Documentation/filesystems/ext4/directory.rst
@@ -59,7 +59,7 @@
- File name.
Since file names cannot be longer than 255 bytes, the new directory
-entry format shortens the rec\_len field and uses the space for a file
+entry format shortens the name\_len field and uses the space for a file
type flag, probably to avoid having to load every inode during directory
tree traversal. This format is ``ext4_dir_entry_2``, which is at most
263 bytes long, though on disk you'll need to reference
diff --git a/Documentation/filesystems/ext4/group_descr.rst b/Documentation/filesystems/ext4/group_descr.rst
index 0f783ed..7ba6114 100644
--- a/Documentation/filesystems/ext4/group_descr.rst
+++ b/Documentation/filesystems/ext4/group_descr.rst
@@ -99,9 +99,12 @@
* - 0x1E
- \_\_le16
- bg\_checksum
- - Group descriptor checksum; crc16(sb\_uuid+group+desc) if the
- RO\_COMPAT\_GDT\_CSUM feature is set, or crc32c(sb\_uuid+group\_desc) &
- 0xFFFF if the RO\_COMPAT\_METADATA\_CSUM feature is set.
+ - Group descriptor checksum; crc16(sb\_uuid+group\_num+bg\_desc) if the
+ RO\_COMPAT\_GDT\_CSUM feature is set, or
+ crc32c(sb\_uuid+group\_num+bg\_desc) & 0xFFFF if the
+ RO\_COMPAT\_METADATA\_CSUM feature is set. The bg\_checksum
+ field in bg\_desc is skipped when calculating crc16 checksum,
+ and set to zero if crc32c checksum is used.
* -
-
-
diff --git a/Documentation/filesystems/ext4/inodes.rst b/Documentation/filesystems/ext4/inodes.rst
index 6bd35e5..a65baff 100644
--- a/Documentation/filesystems/ext4/inodes.rst
+++ b/Documentation/filesystems/ext4/inodes.rst
@@ -277,6 +277,8 @@
- This is a huge file (EXT4\_HUGE\_FILE\_FL).
* - 0x80000
- Inode uses extents (EXT4\_EXTENTS\_FL).
+ * - 0x100000
+ - Verity protected file (EXT4\_VERITY\_FL).
* - 0x200000
- Inode stores a large extended attribute value in its data blocks
(EXT4\_EA\_INODE\_FL).
@@ -299,9 +301,9 @@
- Reserved for ext4 library (EXT4\_RESERVED\_FL).
* -
- Aggregate flags:
- * - 0x4BDFFF
+ * - 0x705BDFFF
- User-visible flags.
- * - 0x4B80FF
+ * - 0x604BC0FF
- User-modifiable flags. Note that while EXT4\_JOURNAL\_DATA\_FL and
EXT4\_EXTENTS\_FL can be set with setattr, they are not in the kernel's
EXT4\_FL\_USER\_MODIFIABLE mask, since it needs to handle the setting of
@@ -470,8 +472,8 @@
having to upgrade all of the on-disk inodes. Access to fields beyond
EXT2\_GOOD\_OLD\_INODE\_SIZE should be verified to be within
``i_extra_isize``. By default, ext4 inode records are 256 bytes, and (as
-of October 2013) the inode structure is 156 bytes
-(``i_extra_isize = 28``). The extra space between the end of the inode
+of August 2019) the inode structure is 160 bytes
+(``i_extra_isize = 32``). The extra space between the end of the inode
structure and the end of the inode record can be used to store extended
attributes. Each inode record can be as large as the filesystem block
size, though this is not terribly efficient.
diff --git a/Documentation/filesystems/ext4/overview.rst b/Documentation/filesystems/ext4/overview.rst
index cbab18b..123ebfd 100644
--- a/Documentation/filesystems/ext4/overview.rst
+++ b/Documentation/filesystems/ext4/overview.rst
@@ -24,3 +24,4 @@
.. include:: bigalloc.rst
.. include:: inlinedata.rst
.. include:: eainode.rst
+.. include:: verity.rst
diff --git a/Documentation/filesystems/ext4/super.rst b/Documentation/filesystems/ext4/super.rst
index 04ff079..93e55d7 100644
--- a/Documentation/filesystems/ext4/super.rst
+++ b/Documentation/filesystems/ext4/super.rst
@@ -58,7 +58,7 @@
* - 0x1C
- \_\_le32
- s\_log\_cluster\_size
- - Cluster size is (2 ^ s\_log\_cluster\_size) blocks if bigalloc is
+ - Cluster size is 2 ^ (10 + s\_log\_cluster\_size) blocks if bigalloc is
enabled. Otherwise s\_log\_cluster\_size must equal s\_log\_block\_size.
* - 0x20
- \_\_le32
@@ -447,7 +447,7 @@
- Upper 8 bits of the s_wtime field.
* - 0x275
- \_\_u8
- - s\_wtime_hi
+ - s\_mtime_hi
- Upper 8 bits of the s_mtime field.
* - 0x276
- \_\_u8
@@ -466,12 +466,20 @@
- s\_last_error_time_hi
- Upper 8 bits of the s_last_error_time_hi field.
* - 0x27A
- - \_\_u8[2]
- - s\_pad
+ - \_\_u8
+ - s\_pad[2]
- Zero padding.
* - 0x27C
+ - \_\_le16
+ - s\_encoding
+ - Filename charset encoding.
+ * - 0x27E
+ - \_\_le16
+ - s\_encoding_flags
+ - Filename charset encoding flags.
+ * - 0x280
- \_\_le32
- - s\_reserved[96]
+ - s\_reserved[95]
- Padding to the end of the block.
* - 0x3FC
- \_\_le32
@@ -617,7 +625,7 @@
* - 0x80
- Enable a filesystem size of 2^64 blocks (INCOMPAT\_64BIT).
* - 0x100
- - Multiple mount protection. Not implemented (INCOMPAT\_MMP).
+ - Multiple mount protection (INCOMPAT\_MMP).
* - 0x200
- Flexible block groups. See the earlier discussion of this feature
(INCOMPAT\_FLEX\_BG).
@@ -696,6 +704,8 @@
(RO\_COMPAT\_READONLY)
* - 0x2000
- Filesystem tracks project quotas. (RO\_COMPAT\_PROJECT)
+ * - 0x8000
+ - Verity inodes may be present on the filesystem. (RO\_COMPAT\_VERITY)
.. _super_def_hash:
diff --git a/Documentation/filesystems/ext4/verity.rst b/Documentation/filesystems/ext4/verity.rst
new file mode 100644
index 0000000..3e4c0ee
--- /dev/null
+++ b/Documentation/filesystems/ext4/verity.rst
@@ -0,0 +1,41 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+Verity files
+------------
+
+ext4 supports fs-verity, which is a filesystem feature that provides
+Merkle tree based hashing for individual readonly files. Most of
+fs-verity is common to all filesystems that support it; see
+:ref:`Documentation/filesystems/fsverity.rst <fsverity>` for the
+fs-verity documentation. However, the on-disk layout of the verity
+metadata is filesystem-specific. On ext4, the verity metadata is
+stored after the end of the file data itself, in the following format:
+
+- Zero-padding to the next 65536-byte boundary. This padding need not
+ actually be allocated on-disk, i.e. it may be a hole.
+
+- The Merkle tree, as documented in
+ :ref:`Documentation/filesystems/fsverity.rst
+ <fsverity_merkle_tree>`, with the tree levels stored in order from
+ root to leaf, and the tree blocks within each level stored in their
+ natural order.
+
+- Zero-padding to the next filesystem block boundary.
+
+- The verity descriptor, as documented in
+ :ref:`Documentation/filesystems/fsverity.rst <fsverity_descriptor>`,
+ with optionally appended signature blob.
+
+- Zero-padding to the next offset that is 4 bytes before a filesystem
+ block boundary.
+
+- The size of the verity descriptor in bytes, as a 4-byte little
+ endian integer.
+
+Verity inodes have EXT4_VERITY_FL set, and they must use extents, i.e.
+EXT4_EXTENTS_FL must be set and EXT4_INLINE_DATA_FL must be clear.
+They can have EXT4_ENCRYPT_FL set, in which case the verity metadata
+is encrypted as well as the data itself.
+
+Verity files cannot have blocks allocated past the end of the verity
+metadata.
diff --git a/Documentation/filesystems/f2fs.txt b/Documentation/filesystems/f2fs.txt
index 496fa28..7e19913 100644
--- a/Documentation/filesystems/f2fs.txt
+++ b/Documentation/filesystems/f2fs.txt
@@ -157,6 +157,11 @@
enabled by default.
data_flush Enable data flushing before checkpoint in order to
persist data of regular and symlink.
+reserve_root=%d Support configuring reserved space which is used for
+ allocation from a privileged user with specified uid or
+ gid, unit: 4KB, the default limit is 0.2% of user blocks.
+resuid=%d The user ID which may use the reserved blocks.
+resgid=%d The group ID which may use the reserved blocks.
fault_injection=%d Enable fault injection in all supported types with
specified injection rate.
fault_type=%d Support configuring fault injection type, should be
@@ -413,6 +418,9 @@
that would be unusable if checkpoint=disable were
to be set.
+encoding This shows the encoding used for casefolding.
+ If casefolding is not enabled, returns (none)
+
================================================================================
USAGE
================================================================================
diff --git a/Documentation/filesystems/fscrypt.rst b/Documentation/filesystems/fscrypt.rst
index 82efa41..8a0700a 100644
--- a/Documentation/filesystems/fscrypt.rst
+++ b/Documentation/filesystems/fscrypt.rst
@@ -72,6 +72,9 @@
fscrypt (and storage encryption in general) can only provide limited
protection, if any at all, against online attacks. In detail:
+Side-channel attacks
+~~~~~~~~~~~~~~~~~~~~
+
fscrypt is only resistant to side-channel attacks, such as timing or
electromagnetic attacks, to the extent that the underlying Linux
Cryptographic API algorithms are. If a vulnerable algorithm is used,
@@ -80,29 +83,90 @@
Side channel attacks may also be mounted against applications
consuming decrypted data.
-After an encryption key has been provided, fscrypt is not designed to
-hide the plaintext file contents or filenames from other users on the
-same system, regardless of the visibility of the keyring key.
-Instead, existing access control mechanisms such as file mode bits,
-POSIX ACLs, LSMs, or mount namespaces should be used for this purpose.
-Also note that as long as the encryption keys are *anywhere* in
-memory, an online attacker can necessarily compromise them by mounting
-a physical attack or by exploiting any kernel security vulnerability
-which provides an arbitrary memory read primitive.
+Unauthorized file access
+~~~~~~~~~~~~~~~~~~~~~~~~
-While it is ostensibly possible to "evict" keys from the system,
-recently accessed encrypted files will remain accessible at least
-until the filesystem is unmounted or the VFS caches are dropped, e.g.
-using ``echo 2 > /proc/sys/vm/drop_caches``. Even after that, if the
-RAM is compromised before being powered off, it will likely still be
-possible to recover portions of the plaintext file contents, if not
-some of the encryption keys as well. (Since Linux v4.12, all
-in-kernel keys related to fscrypt are sanitized before being freed.
-However, userspace would need to do its part as well.)
+After an encryption key has been added, fscrypt does not hide the
+plaintext file contents or filenames from other users on the same
+system. Instead, existing access control mechanisms such as file mode
+bits, POSIX ACLs, LSMs, or namespaces should be used for this purpose.
-Currently, fscrypt does not prevent a user from maliciously providing
-an incorrect key for another user's existing encrypted files. A
-protection against this is planned.
+(For the reasoning behind this, understand that while the key is
+added, the confidentiality of the data, from the perspective of the
+system itself, is *not* protected by the mathematical properties of
+encryption but rather only by the correctness of the kernel.
+Therefore, any encryption-specific access control checks would merely
+be enforced by kernel *code* and therefore would be largely redundant
+with the wide variety of access control mechanisms already available.)
+
+Kernel memory compromise
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+An attacker who compromises the system enough to read from arbitrary
+memory, e.g. by mounting a physical attack or by exploiting a kernel
+security vulnerability, can compromise all encryption keys that are
+currently in use.
+
+However, fscrypt allows encryption keys to be removed from the kernel,
+which may protect them from later compromise.
+
+In more detail, the FS_IOC_REMOVE_ENCRYPTION_KEY ioctl (or the
+FS_IOC_REMOVE_ENCRYPTION_KEY_ALL_USERS ioctl) can wipe a master
+encryption key from kernel memory. If it does so, it will also try to
+evict all cached inodes which had been "unlocked" using the key,
+thereby wiping their per-file keys and making them once again appear
+"locked", i.e. in ciphertext or encrypted form.
+
+However, these ioctls have some limitations:
+
+- Per-file keys for in-use files will *not* be removed or wiped.
+ Therefore, for maximum effect, userspace should close the relevant
+ encrypted files and directories before removing a master key, as
+ well as kill any processes whose working directory is in an affected
+ encrypted directory.
+
+- The kernel cannot magically wipe copies of the master key(s) that
+ userspace might have as well. Therefore, userspace must wipe all
+ copies of the master key(s) it makes as well; normally this should
+ be done immediately after FS_IOC_ADD_ENCRYPTION_KEY, without waiting
+ for FS_IOC_REMOVE_ENCRYPTION_KEY. Naturally, the same also applies
+ to all higher levels in the key hierarchy. Userspace should also
+ follow other security precautions such as mlock()ing memory
+ containing keys to prevent it from being swapped out.
+
+- In general, decrypted contents and filenames in the kernel VFS
+ caches are freed but not wiped. Therefore, portions thereof may be
+ recoverable from freed memory, even after the corresponding key(s)
+ were wiped. To partially solve this, you can set
+ CONFIG_PAGE_POISONING=y in your kernel config and add page_poison=1
+ to your kernel command line. However, this has a performance cost.
+
+- Secret keys might still exist in CPU registers, in crypto
+ accelerator hardware (if used by the crypto API to implement any of
+ the algorithms), or in other places not explicitly considered here.
+
+Limitations of v1 policies
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+v1 encryption policies have some weaknesses with respect to online
+attacks:
+
+- There is no verification that the provided master key is correct.
+ Therefore, a malicious user can temporarily associate the wrong key
+ with another user's encrypted files to which they have read-only
+ access. Because of filesystem caching, the wrong key will then be
+ used by the other user's accesses to those files, even if the other
+ user has the correct key in their own keyring. This violates the
+ meaning of "read-only access".
+
+- A compromise of a per-file key also compromises the master key from
+ which it was derived.
+
+- Non-root users cannot securely remove encryption keys.
+
+All the above problems are fixed with v2 encryption policies. For
+this reason among others, it is recommended to use v2 encryption
+policies on all new encrypted directories.
Key hierarchy
=============
@@ -123,11 +187,52 @@
of which protects any number of directory trees on any number of
filesystems.
-Userspace should generate master keys either using a cryptographically
-secure random number generator, or by using a KDF (Key Derivation
-Function). Note that whenever a KDF is used to "stretch" a
-lower-entropy secret such as a passphrase, it is critical that a KDF
-designed for this purpose be used, such as scrypt, PBKDF2, or Argon2.
+Master keys must be real cryptographic keys, i.e. indistinguishable
+from random bytestrings of the same length. This implies that users
+**must not** directly use a password as a master key, zero-pad a
+shorter key, or repeat a shorter key. Security cannot be guaranteed
+if userspace makes any such error, as the cryptographic proofs and
+analysis would no longer apply.
+
+Instead, users should generate master keys either using a
+cryptographically secure random number generator, or by using a KDF
+(Key Derivation Function). The kernel does not do any key stretching;
+therefore, if userspace derives the key from a low-entropy secret such
+as a passphrase, it is critical that a KDF designed for this purpose
+be used, such as scrypt, PBKDF2, or Argon2.
+
+Key derivation function
+-----------------------
+
+With one exception, fscrypt never uses the master key(s) for
+encryption directly. Instead, they are only used as input to a KDF
+(Key Derivation Function) to derive the actual keys.
+
+The KDF used for a particular master key differs depending on whether
+the key is used for v1 encryption policies or for v2 encryption
+policies. Users **must not** use the same key for both v1 and v2
+encryption policies. (No real-world attack is currently known on this
+specific case of key reuse, but its security cannot be guaranteed
+since the cryptographic proofs and analysis would no longer apply.)
+
+For v1 encryption policies, the KDF only supports deriving per-file
+encryption keys. It works by encrypting the master key with
+AES-128-ECB, using the file's 16-byte nonce as the AES key. The
+resulting ciphertext is used as the derived key. If the ciphertext is
+longer than needed, then it is truncated to the needed length.
+
+For v2 encryption policies, the KDF is HKDF-SHA512. The master key is
+passed as the "input keying material", no salt is used, and a distinct
+"application-specific information string" is used for each distinct
+key to be derived. For example, when a per-file encryption key is
+derived, the application-specific information string is the file's
+nonce prefixed with "fscrypt\\0" and a context byte. Different
+context bytes are used for other types of derived keys.
+
+HKDF-SHA512 is preferred to the original AES-128-ECB based KDF because
+HKDF is more flexible, is nonreversible, and evenly distributes
+entropy from the master key. HKDF is also standardized and widely
+used by other software, whereas the AES-128-ECB based KDF is ad-hoc.
Per-file keys
-------------
@@ -138,29 +243,9 @@
cases, fscrypt does this by deriving per-file keys. When a new
encrypted inode (regular file, directory, or symlink) is created,
fscrypt randomly generates a 16-byte nonce and stores it in the
-inode's encryption xattr. Then, it uses a KDF (Key Derivation
-Function) to derive the file's key from the master key and nonce.
-
-The Adiantum encryption mode (see `Encryption modes and usage`_) is
-special, since it accepts longer IVs and is suitable for both contents
-and filenames encryption. For it, a "direct key" option is offered
-where the file's nonce is included in the IVs and the master key is
-used for encryption directly. This improves performance; however,
-users must not use the same master key for any other encryption mode.
-
-Below, the KDF and design considerations are described in more detail.
-
-The current KDF works by encrypting the master key with AES-128-ECB,
-using the file's nonce as the AES key. The output is used as the
-derived key. If the output is longer than needed, then it is
-truncated to the needed length.
-
-Note: this KDF meets the primary security requirement, which is to
-produce unique derived keys that preserve the entropy of the master
-key, assuming that the master key is already a good pseudorandom key.
-However, it is nonstandard and has some problems such as being
-reversible, so it is generally considered to be a mistake! It may be
-replaced with HKDF or another more standard KDF in the future.
+inode's encryption xattr. Then, it uses a KDF (as described in `Key
+derivation function`_) to derive the file's key from the master key
+and nonce.
Key derivation was chosen over key wrapping because wrapped keys would
require larger xattrs which would be less likely to fit in-line in the
@@ -176,6 +261,37 @@
resized, and by itself still wouldn't have been sufficient to prevent
the same key from being directly reused for both XTS and CTS-CBC.
+DIRECT_KEY and per-mode keys
+----------------------------
+
+The Adiantum encryption mode (see `Encryption modes and usage`_) is
+suitable for both contents and filenames encryption, and it accepts
+long IVs --- long enough to hold both an 8-byte logical block number
+and a 16-byte per-file nonce. Also, the overhead of each Adiantum key
+is greater than that of an AES-256-XTS key.
+
+Therefore, to improve performance and save memory, for Adiantum a
+"direct key" configuration is supported. When the user has enabled
+this by setting FSCRYPT_POLICY_FLAG_DIRECT_KEY in the fscrypt policy,
+per-file keys are not used. Instead, whenever any data (contents or
+filenames) is encrypted, the file's 16-byte nonce is included in the
+IV. Moreover:
+
+- For v1 encryption policies, the encryption is done directly with the
+ master key. Because of this, users **must not** use the same master
+ key for any other purpose, even for other v1 policies.
+
+- For v2 encryption policies, the encryption is done with a per-mode
+ key derived using the KDF. Users may use the same master key for
+ other v2 encryption policies.
+
+Key identifiers
+---------------
+
+For master keys used for v2 encryption policies, a unique 16-byte "key
+identifier" is also derived using the KDF. This value is stored in
+the clear, since it is needed to reliably identify the key itself.
+
Encryption modes and usage
==========================
@@ -225,9 +341,10 @@
is encrypted with AES-256 where the AES-256 key is the SHA-256 hash
of the file's data encryption key.
-- In the "direct key" configuration (FS_POLICY_FLAG_DIRECT_KEY set in
- the fscrypt_policy), the file's nonce is also appended to the IV.
- Currently this is only allowed with the Adiantum encryption mode.
+- In the "direct key" configuration (FSCRYPT_POLICY_FLAG_DIRECT_KEY
+ set in the fscrypt_policy), the file's nonce is also appended to the
+ IV. Currently this is only allowed with the Adiantum encryption
+ mode.
Filenames encryption
--------------------
@@ -269,49 +386,77 @@
Setting an encryption policy
----------------------------
+FS_IOC_SET_ENCRYPTION_POLICY
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
The FS_IOC_SET_ENCRYPTION_POLICY ioctl sets an encryption policy on an
empty directory or verifies that a directory or regular file already
has the specified encryption policy. It takes in a pointer to a
-:c:type:`struct fscrypt_policy`, defined as follows::
+:c:type:`struct fscrypt_policy_v1` or a :c:type:`struct
+fscrypt_policy_v2`, defined as follows::
- #define FS_KEY_DESCRIPTOR_SIZE 8
-
- struct fscrypt_policy {
+ #define FSCRYPT_POLICY_V1 0
+ #define FSCRYPT_KEY_DESCRIPTOR_SIZE 8
+ struct fscrypt_policy_v1 {
__u8 version;
__u8 contents_encryption_mode;
__u8 filenames_encryption_mode;
__u8 flags;
- __u8 master_key_descriptor[FS_KEY_DESCRIPTOR_SIZE];
+ __u8 master_key_descriptor[FSCRYPT_KEY_DESCRIPTOR_SIZE];
+ };
+ #define fscrypt_policy fscrypt_policy_v1
+
+ #define FSCRYPT_POLICY_V2 2
+ #define FSCRYPT_KEY_IDENTIFIER_SIZE 16
+ struct fscrypt_policy_v2 {
+ __u8 version;
+ __u8 contents_encryption_mode;
+ __u8 filenames_encryption_mode;
+ __u8 flags;
+ __u8 __reserved[4];
+ __u8 master_key_identifier[FSCRYPT_KEY_IDENTIFIER_SIZE];
};
This structure must be initialized as follows:
-- ``version`` must be 0.
+- ``version`` must be FSCRYPT_POLICY_V1 (0) if the struct is
+ :c:type:`fscrypt_policy_v1` or FSCRYPT_POLICY_V2 (2) if the struct
+ is :c:type:`fscrypt_policy_v2`. (Note: we refer to the original
+ policy version as "v1", though its version code is really 0.) For
+ new encrypted directories, use v2 policies.
- ``contents_encryption_mode`` and ``filenames_encryption_mode`` must
- be set to constants from ``<linux/fs.h>`` which identify the
- encryption modes to use. If unsure, use
- FS_ENCRYPTION_MODE_AES_256_XTS (1) for ``contents_encryption_mode``
- and FS_ENCRYPTION_MODE_AES_256_CTS (4) for
- ``filenames_encryption_mode``.
+ be set to constants from ``<linux/fscrypt.h>`` which identify the
+ encryption modes to use. If unsure, use FSCRYPT_MODE_AES_256_XTS
+ (1) for ``contents_encryption_mode`` and FSCRYPT_MODE_AES_256_CTS
+ (4) for ``filenames_encryption_mode``.
-- ``flags`` must contain a value from ``<linux/fs.h>`` which
+- ``flags`` must contain a value from ``<linux/fscrypt.h>`` which
identifies the amount of NUL-padding to use when encrypting
- filenames. If unsure, use FS_POLICY_FLAGS_PAD_32 (0x3).
- In addition, if the chosen encryption modes are both
- FS_ENCRYPTION_MODE_ADIANTUM, this can contain
- FS_POLICY_FLAG_DIRECT_KEY to specify that the master key should be
- used directly, without key derivation.
+ filenames. If unsure, use FSCRYPT_POLICY_FLAGS_PAD_32 (0x3).
+ Additionally, if the encryption modes are both
+ FSCRYPT_MODE_ADIANTUM, this can contain
+ FSCRYPT_POLICY_FLAG_DIRECT_KEY; see `DIRECT_KEY and per-mode keys`_.
-- ``master_key_descriptor`` specifies how to find the master key in
- the keyring; see `Adding keys`_. It is up to userspace to choose a
- unique ``master_key_descriptor`` for each master key. The e4crypt
- and fscrypt tools use the first 8 bytes of
+- For v2 encryption policies, ``__reserved`` must be zeroed.
+
+- For v1 encryption policies, ``master_key_descriptor`` specifies how
+ to find the master key in a keyring; see `Adding keys`_. It is up
+ to userspace to choose a unique ``master_key_descriptor`` for each
+ master key. The e4crypt and fscrypt tools use the first 8 bytes of
``SHA-512(SHA-512(master_key))``, but this particular scheme is not
required. Also, the master key need not be in the keyring yet when
FS_IOC_SET_ENCRYPTION_POLICY is executed. However, it must be added
before any files can be created in the encrypted directory.
+ For v2 encryption policies, ``master_key_descriptor`` has been
+ replaced with ``master_key_identifier``, which is longer and cannot
+ be arbitrarily chosen. Instead, the key must first be added using
+ `FS_IOC_ADD_ENCRYPTION_KEY`_. Then, the ``key_spec.u.identifier``
+ the kernel returned in the :c:type:`struct fscrypt_add_key_arg` must
+ be used as the ``master_key_identifier`` in the :c:type:`struct
+ fscrypt_policy_v2`.
+
If the file is not yet encrypted, then FS_IOC_SET_ENCRYPTION_POLICY
verifies that the file is an empty directory. If so, the specified
encryption policy is assigned to the directory, turning it into an
@@ -327,6 +472,15 @@
returns 0. Otherwise, it fails with EEXIST. This works on both
regular files and directories, including nonempty directories.
+When a v2 encryption policy is assigned to a directory, it is also
+required that either the specified key has been added by the current
+user or that the caller has CAP_FOWNER in the initial user namespace.
+(This is needed to prevent a user from encrypting their data with
+another user's key.) The key must remain added while
+FS_IOC_SET_ENCRYPTION_POLICY is executing. However, if the new
+encrypted directory does not need to be accessed immediately, then the
+key can be removed right away afterwards.
+
Note that the ext4 filesystem does not allow the root directory to be
encrypted, even if it is empty. Users who want to encrypt an entire
filesystem with one key should consider using dm-crypt instead.
@@ -339,7 +493,11 @@
- ``EEXIST``: the file is already encrypted with an encryption policy
different from the one specified
- ``EINVAL``: an invalid encryption policy was specified (invalid
- version, mode(s), or flags)
+ version, mode(s), or flags; or reserved bits were set)
+- ``ENOKEY``: a v2 encryption policy was specified, but the key with
+ the specified ``master_key_identifier`` has not been added, nor does
+ the process have the CAP_FOWNER capability in the initial user
+ namespace
- ``ENOTDIR``: the file is unencrypted and is a regular file, not a
directory
- ``ENOTEMPTY``: the file is unencrypted and is a nonempty directory
@@ -358,25 +516,79 @@
Getting an encryption policy
----------------------------
-The FS_IOC_GET_ENCRYPTION_POLICY ioctl retrieves the :c:type:`struct
-fscrypt_policy`, if any, for a directory or regular file. See above
-for the struct definition. No additional permissions are required
-beyond the ability to open the file.
+Two ioctls are available to get a file's encryption policy:
-FS_IOC_GET_ENCRYPTION_POLICY can fail with the following errors:
+- `FS_IOC_GET_ENCRYPTION_POLICY_EX`_
+- `FS_IOC_GET_ENCRYPTION_POLICY`_
+
+The extended (_EX) version of the ioctl is more general and is
+recommended to use when possible. However, on older kernels only the
+original ioctl is available. Applications should try the extended
+version, and if it fails with ENOTTY fall back to the original
+version.
+
+FS_IOC_GET_ENCRYPTION_POLICY_EX
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The FS_IOC_GET_ENCRYPTION_POLICY_EX ioctl retrieves the encryption
+policy, if any, for a directory or regular file. No additional
+permissions are required beyond the ability to open the file. It
+takes in a pointer to a :c:type:`struct fscrypt_get_policy_ex_arg`,
+defined as follows::
+
+ struct fscrypt_get_policy_ex_arg {
+ __u64 policy_size; /* input/output */
+ union {
+ __u8 version;
+ struct fscrypt_policy_v1 v1;
+ struct fscrypt_policy_v2 v2;
+ } policy; /* output */
+ };
+
+The caller must initialize ``policy_size`` to the size available for
+the policy struct, i.e. ``sizeof(arg.policy)``.
+
+On success, the policy struct is returned in ``policy``, and its
+actual size is returned in ``policy_size``. ``policy.version`` should
+be checked to determine the version of policy returned. Note that the
+version code for the "v1" policy is actually 0 (FSCRYPT_POLICY_V1).
+
+FS_IOC_GET_ENCRYPTION_POLICY_EX can fail with the following errors:
- ``EINVAL``: the file is encrypted, but it uses an unrecognized
- encryption context format
+ encryption policy version
- ``ENODATA``: the file is not encrypted
-- ``ENOTTY``: this type of filesystem does not implement encryption
+- ``ENOTTY``: this type of filesystem does not implement encryption,
+ or this kernel is too old to support FS_IOC_GET_ENCRYPTION_POLICY_EX
+ (try FS_IOC_GET_ENCRYPTION_POLICY instead)
- ``EOPNOTSUPP``: the kernel was not configured with encryption
- support for this filesystem
+ support for this filesystem, or the filesystem superblock has not
+ had encryption enabled on it
+- ``EOVERFLOW``: the file is encrypted and uses a recognized
+ encryption policy version, but the policy struct does not fit into
+ the provided buffer
Note: if you only need to know whether a file is encrypted or not, on
most filesystems it is also possible to use the FS_IOC_GETFLAGS ioctl
and check for FS_ENCRYPT_FL, or to use the statx() system call and
check for STATX_ATTR_ENCRYPTED in stx_attributes.
+FS_IOC_GET_ENCRYPTION_POLICY
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The FS_IOC_GET_ENCRYPTION_POLICY ioctl can also retrieve the
+encryption policy, if any, for a directory or regular file. However,
+unlike `FS_IOC_GET_ENCRYPTION_POLICY_EX`_,
+FS_IOC_GET_ENCRYPTION_POLICY only supports the original policy
+version. It takes in a pointer directly to a :c:type:`struct
+fscrypt_policy_v1` rather than a :c:type:`struct
+fscrypt_get_policy_ex_arg`.
+
+The error codes for FS_IOC_GET_ENCRYPTION_POLICY are the same as those
+for FS_IOC_GET_ENCRYPTION_POLICY_EX, except that
+FS_IOC_GET_ENCRYPTION_POLICY also returns ``EINVAL`` if the file is
+encrypted using a newer encryption policy version.
+
Getting the per-filesystem salt
-------------------------------
@@ -392,8 +604,115 @@
Adding keys
-----------
-To provide a master key, userspace must add it to an appropriate
-keyring using the add_key() system call (see:
+FS_IOC_ADD_ENCRYPTION_KEY
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The FS_IOC_ADD_ENCRYPTION_KEY ioctl adds a master encryption key to
+the filesystem, making all files on the filesystem which were
+encrypted using that key appear "unlocked", i.e. in plaintext form.
+It can be executed on any file or directory on the target filesystem,
+but using the filesystem's root directory is recommended. It takes in
+a pointer to a :c:type:`struct fscrypt_add_key_arg`, defined as
+follows::
+
+ struct fscrypt_add_key_arg {
+ struct fscrypt_key_specifier key_spec;
+ __u32 raw_size;
+ __u32 __reserved[9];
+ __u8 raw[];
+ };
+
+ #define FSCRYPT_KEY_SPEC_TYPE_DESCRIPTOR 1
+ #define FSCRYPT_KEY_SPEC_TYPE_IDENTIFIER 2
+
+ struct fscrypt_key_specifier {
+ __u32 type; /* one of FSCRYPT_KEY_SPEC_TYPE_* */
+ __u32 __reserved;
+ union {
+ __u8 __reserved[32]; /* reserve some extra space */
+ __u8 descriptor[FSCRYPT_KEY_DESCRIPTOR_SIZE];
+ __u8 identifier[FSCRYPT_KEY_IDENTIFIER_SIZE];
+ } u;
+ };
+
+:c:type:`struct fscrypt_add_key_arg` must be zeroed, then initialized
+as follows:
+
+- If the key is being added for use by v1 encryption policies, then
+ ``key_spec.type`` must contain FSCRYPT_KEY_SPEC_TYPE_DESCRIPTOR, and
+ ``key_spec.u.descriptor`` must contain the descriptor of the key
+ being added, corresponding to the value in the
+ ``master_key_descriptor`` field of :c:type:`struct
+ fscrypt_policy_v1`. To add this type of key, the calling process
+ must have the CAP_SYS_ADMIN capability in the initial user
+ namespace.
+
+ Alternatively, if the key is being added for use by v2 encryption
+ policies, then ``key_spec.type`` must contain
+ FSCRYPT_KEY_SPEC_TYPE_IDENTIFIER, and ``key_spec.u.identifier`` is
+ an *output* field which the kernel fills in with a cryptographic
+ hash of the key. To add this type of key, the calling process does
+ not need any privileges. However, the number of keys that can be
+ added is limited by the user's quota for the keyrings service (see
+ ``Documentation/security/keys/core.rst``).
+
+- ``raw_size`` must be the size of the ``raw`` key provided, in bytes.
+
+- ``raw`` is a variable-length field which must contain the actual
+ key, ``raw_size`` bytes long.
+
+For v2 policy keys, the kernel keeps track of which user (identified
+by effective user ID) added the key, and only allows the key to be
+removed by that user --- or by "root", if they use
+`FS_IOC_REMOVE_ENCRYPTION_KEY_ALL_USERS`_.
+
+However, if another user has added the key, it may be desirable to
+prevent that other user from unexpectedly removing it. Therefore,
+FS_IOC_ADD_ENCRYPTION_KEY may also be used to add a v2 policy key
+*again*, even if it's already added by other user(s). In this case,
+FS_IOC_ADD_ENCRYPTION_KEY will just install a claim to the key for the
+current user, rather than actually add the key again (but the raw key
+must still be provided, as a proof of knowledge).
+
+FS_IOC_ADD_ENCRYPTION_KEY returns 0 if either the key or a claim to
+the key was either added or already exists.
+
+FS_IOC_ADD_ENCRYPTION_KEY can fail with the following errors:
+
+- ``EACCES``: FSCRYPT_KEY_SPEC_TYPE_DESCRIPTOR was specified, but the
+ caller does not have the CAP_SYS_ADMIN capability in the initial
+ user namespace
+- ``EDQUOT``: the key quota for this user would be exceeded by adding
+ the key
+- ``EINVAL``: invalid key size or key specifier type, or reserved bits
+ were set
+- ``ENOTTY``: this type of filesystem does not implement encryption
+- ``EOPNOTSUPP``: the kernel was not configured with encryption
+ support for this filesystem, or the filesystem superblock has not
+ had encryption enabled on it
+
+Legacy method
+~~~~~~~~~~~~~
+
+For v1 encryption policies, a master encryption key can also be
+provided by adding it to a process-subscribed keyring, e.g. to a
+session keyring, or to a user keyring if the user keyring is linked
+into the session keyring.
+
+This method is deprecated (and not supported for v2 encryption
+policies) for several reasons. First, it cannot be used in
+combination with FS_IOC_REMOVE_ENCRYPTION_KEY (see `Removing keys`_),
+so for removing a key a workaround such as keyctl_unlink() in
+combination with ``sync; echo 2 > /proc/sys/vm/drop_caches`` would
+have to be used. Second, it doesn't match the fact that the
+locked/unlocked status of encrypted files (i.e. whether they appear to
+be in plaintext form or in ciphertext form) is global. This mismatch
+has caused much confusion as well as real problems when processes
+running under different UIDs, such as a ``sudo`` command, need to
+access encrypted files.
+
+Nevertheless, to add a key to one of the process-subscribed keyrings,
+the add_key() system call can be used (see:
``Documentation/security/keys/core.rst``). The key type must be
"logon"; keys of this type are kept in kernel memory and cannot be
read back by userspace. The key description must be "fscrypt:"
@@ -401,12 +720,12 @@
``master_key_descriptor`` that was set in the encryption policy. The
key payload must conform to the following structure::
- #define FS_MAX_KEY_SIZE 64
+ #define FSCRYPT_MAX_KEY_SIZE 64
struct fscrypt_key {
- u32 mode;
- u8 raw[FS_MAX_KEY_SIZE];
- u32 size;
+ __u32 mode;
+ __u8 raw[FSCRYPT_MAX_KEY_SIZE];
+ __u32 size;
};
``mode`` is ignored; just set it to 0. The actual key is provided in
@@ -418,26 +737,194 @@
filesystem-specific prefixes are deprecated and should not be used in
new programs.
-There are several different types of keyrings in which encryption keys
-may be placed, such as a session keyring, a user session keyring, or a
-user keyring. Each key must be placed in a keyring that is "attached"
-to all processes that might need to access files encrypted with it, in
-the sense that request_key() will find the key. Generally, if only
-processes belonging to a specific user need to access a given
-encrypted directory and no session keyring has been installed, then
-that directory's key should be placed in that user's user session
-keyring or user keyring. Otherwise, a session keyring should be
-installed if needed, and the key should be linked into that session
-keyring, or in a keyring linked into that session keyring.
+Removing keys
+-------------
-Note: introducing the complex visibility semantics of keyrings here
-was arguably a mistake --- especially given that by design, after any
-process successfully opens an encrypted file (thereby setting up the
-per-file key), possessing the keyring key is not actually required for
-any process to read/write the file until its in-memory inode is
-evicted. In the future there probably should be a way to provide keys
-directly to the filesystem instead, which would make the intended
-semantics clearer.
+Two ioctls are available for removing a key that was added by
+`FS_IOC_ADD_ENCRYPTION_KEY`_:
+
+- `FS_IOC_REMOVE_ENCRYPTION_KEY`_
+- `FS_IOC_REMOVE_ENCRYPTION_KEY_ALL_USERS`_
+
+These two ioctls differ only in cases where v2 policy keys are added
+or removed by non-root users.
+
+These ioctls don't work on keys that were added via the legacy
+process-subscribed keyrings mechanism.
+
+Before using these ioctls, read the `Kernel memory compromise`_
+section for a discussion of the security goals and limitations of
+these ioctls.
+
+FS_IOC_REMOVE_ENCRYPTION_KEY
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The FS_IOC_REMOVE_ENCRYPTION_KEY ioctl removes a claim to a master
+encryption key from the filesystem, and possibly removes the key
+itself. It can be executed on any file or directory on the target
+filesystem, but using the filesystem's root directory is recommended.
+It takes in a pointer to a :c:type:`struct fscrypt_remove_key_arg`,
+defined as follows::
+
+ struct fscrypt_remove_key_arg {
+ struct fscrypt_key_specifier key_spec;
+ #define FSCRYPT_KEY_REMOVAL_STATUS_FLAG_FILES_BUSY 0x00000001
+ #define FSCRYPT_KEY_REMOVAL_STATUS_FLAG_OTHER_USERS 0x00000002
+ __u32 removal_status_flags; /* output */
+ __u32 __reserved[5];
+ };
+
+This structure must be zeroed, then initialized as follows:
+
+- The key to remove is specified by ``key_spec``:
+
+ - To remove a key used by v1 encryption policies, set
+ ``key_spec.type`` to FSCRYPT_KEY_SPEC_TYPE_DESCRIPTOR and fill
+ in ``key_spec.u.descriptor``. To remove this type of key, the
+ calling process must have the CAP_SYS_ADMIN capability in the
+ initial user namespace.
+
+ - To remove a key used by v2 encryption policies, set
+ ``key_spec.type`` to FSCRYPT_KEY_SPEC_TYPE_IDENTIFIER and fill
+ in ``key_spec.u.identifier``.
+
+For v2 policy keys, this ioctl is usable by non-root users. However,
+to make this possible, it actually just removes the current user's
+claim to the key, undoing a single call to FS_IOC_ADD_ENCRYPTION_KEY.
+Only after all claims are removed is the key really removed.
+
+For example, if FS_IOC_ADD_ENCRYPTION_KEY was called with uid 1000,
+then the key will be "claimed" by uid 1000, and
+FS_IOC_REMOVE_ENCRYPTION_KEY will only succeed as uid 1000. Or, if
+both uids 1000 and 2000 added the key, then for each uid
+FS_IOC_REMOVE_ENCRYPTION_KEY will only remove their own claim. Only
+once *both* are removed is the key really removed. (Think of it like
+unlinking a file that may have hard links.)
+
+If FS_IOC_REMOVE_ENCRYPTION_KEY really removes the key, it will also
+try to "lock" all files that had been unlocked with the key. It won't
+lock files that are still in-use, so this ioctl is expected to be used
+in cooperation with userspace ensuring that none of the files are
+still open. However, if necessary, this ioctl can be executed again
+later to retry locking any remaining files.
+
+FS_IOC_REMOVE_ENCRYPTION_KEY returns 0 if either the key was removed
+(but may still have files remaining to be locked), the user's claim to
+the key was removed, or the key was already removed but had files
+remaining to be the locked so the ioctl retried locking them. In any
+of these cases, ``removal_status_flags`` is filled in with the
+following informational status flags:
+
+- ``FSCRYPT_KEY_REMOVAL_STATUS_FLAG_FILES_BUSY``: set if some file(s)
+ are still in-use. Not guaranteed to be set in the case where only
+ the user's claim to the key was removed.
+- ``FSCRYPT_KEY_REMOVAL_STATUS_FLAG_OTHER_USERS``: set if only the
+ user's claim to the key was removed, not the key itself
+
+FS_IOC_REMOVE_ENCRYPTION_KEY can fail with the following errors:
+
+- ``EACCES``: The FSCRYPT_KEY_SPEC_TYPE_DESCRIPTOR key specifier type
+ was specified, but the caller does not have the CAP_SYS_ADMIN
+ capability in the initial user namespace
+- ``EINVAL``: invalid key specifier type, or reserved bits were set
+- ``ENOKEY``: the key object was not found at all, i.e. it was never
+ added in the first place or was already fully removed including all
+ files locked; or, the user does not have a claim to the key (but
+ someone else does).
+- ``ENOTTY``: this type of filesystem does not implement encryption
+- ``EOPNOTSUPP``: the kernel was not configured with encryption
+ support for this filesystem, or the filesystem superblock has not
+ had encryption enabled on it
+
+FS_IOC_REMOVE_ENCRYPTION_KEY_ALL_USERS
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+FS_IOC_REMOVE_ENCRYPTION_KEY_ALL_USERS is exactly the same as
+`FS_IOC_REMOVE_ENCRYPTION_KEY`_, except that for v2 policy keys, the
+ALL_USERS version of the ioctl will remove all users' claims to the
+key, not just the current user's. I.e., the key itself will always be
+removed, no matter how many users have added it. This difference is
+only meaningful if non-root users are adding and removing keys.
+
+Because of this, FS_IOC_REMOVE_ENCRYPTION_KEY_ALL_USERS also requires
+"root", namely the CAP_SYS_ADMIN capability in the initial user
+namespace. Otherwise it will fail with EACCES.
+
+Getting key status
+------------------
+
+FS_IOC_GET_ENCRYPTION_KEY_STATUS
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The FS_IOC_GET_ENCRYPTION_KEY_STATUS ioctl retrieves the status of a
+master encryption key. It can be executed on any file or directory on
+the target filesystem, but using the filesystem's root directory is
+recommended. It takes in a pointer to a :c:type:`struct
+fscrypt_get_key_status_arg`, defined as follows::
+
+ struct fscrypt_get_key_status_arg {
+ /* input */
+ struct fscrypt_key_specifier key_spec;
+ __u32 __reserved[6];
+
+ /* output */
+ #define FSCRYPT_KEY_STATUS_ABSENT 1
+ #define FSCRYPT_KEY_STATUS_PRESENT 2
+ #define FSCRYPT_KEY_STATUS_INCOMPLETELY_REMOVED 3
+ __u32 status;
+ #define FSCRYPT_KEY_STATUS_FLAG_ADDED_BY_SELF 0x00000001
+ __u32 status_flags;
+ __u32 user_count;
+ __u32 __out_reserved[13];
+ };
+
+The caller must zero all input fields, then fill in ``key_spec``:
+
+ - To get the status of a key for v1 encryption policies, set
+ ``key_spec.type`` to FSCRYPT_KEY_SPEC_TYPE_DESCRIPTOR and fill
+ in ``key_spec.u.descriptor``.
+
+ - To get the status of a key for v2 encryption policies, set
+ ``key_spec.type`` to FSCRYPT_KEY_SPEC_TYPE_IDENTIFIER and fill
+ in ``key_spec.u.identifier``.
+
+On success, 0 is returned and the kernel fills in the output fields:
+
+- ``status`` indicates whether the key is absent, present, or
+ incompletely removed. Incompletely removed means that the master
+ secret has been removed, but some files are still in use; i.e.,
+ `FS_IOC_REMOVE_ENCRYPTION_KEY`_ returned 0 but set the informational
+ status flag FSCRYPT_KEY_REMOVAL_STATUS_FLAG_FILES_BUSY.
+
+- ``status_flags`` can contain the following flags:
+
+ - ``FSCRYPT_KEY_STATUS_FLAG_ADDED_BY_SELF`` indicates that the key
+ has added by the current user. This is only set for keys
+ identified by ``identifier`` rather than by ``descriptor``.
+
+- ``user_count`` specifies the number of users who have added the key.
+ This is only set for keys identified by ``identifier`` rather than
+ by ``descriptor``.
+
+FS_IOC_GET_ENCRYPTION_KEY_STATUS can fail with the following errors:
+
+- ``EINVAL``: invalid key specifier type, or reserved bits were set
+- ``ENOTTY``: this type of filesystem does not implement encryption
+- ``EOPNOTSUPP``: the kernel was not configured with encryption
+ support for this filesystem, or the filesystem superblock has not
+ had encryption enabled on it
+
+Among other use cases, FS_IOC_GET_ENCRYPTION_KEY_STATUS can be useful
+for determining whether the key for a given encrypted directory needs
+to be added before prompting the user for the passphrase needed to
+derive the key.
+
+FS_IOC_GET_ENCRYPTION_KEY_STATUS can only get the status of keys in
+the filesystem-level keyring, i.e. the keyring managed by
+`FS_IOC_ADD_ENCRYPTION_KEY`_ and `FS_IOC_REMOVE_ENCRYPTION_KEY`_. It
+cannot get the status of a key that has only been added for use by v1
+encryption policies using the legacy mechanism involving
+process-subscribed keyrings.
Access semantics
================
@@ -500,7 +987,7 @@
Some filesystem operations may be performed on encrypted regular
files, directories, and symlinks even before their encryption key has
-been provided:
+been added, or after their encryption key has been removed:
- File metadata may be read, e.g. using stat().
@@ -565,33 +1052,44 @@
------------------
An encryption policy is represented on-disk by a :c:type:`struct
-fscrypt_context`. It is up to individual filesystems to decide where
-to store it, but normally it would be stored in a hidden extended
-attribute. It should *not* be exposed by the xattr-related system
-calls such as getxattr() and setxattr() because of the special
-semantics of the encryption xattr. (In particular, there would be
-much confusion if an encryption policy were to be added to or removed
-from anything other than an empty directory.) The struct is defined
-as follows::
+fscrypt_context_v1` or a :c:type:`struct fscrypt_context_v2`. It is
+up to individual filesystems to decide where to store it, but normally
+it would be stored in a hidden extended attribute. It should *not* be
+exposed by the xattr-related system calls such as getxattr() and
+setxattr() because of the special semantics of the encryption xattr.
+(In particular, there would be much confusion if an encryption policy
+were to be added to or removed from anything other than an empty
+directory.) These structs are defined as follows::
- #define FS_KEY_DESCRIPTOR_SIZE 8
#define FS_KEY_DERIVATION_NONCE_SIZE 16
- struct fscrypt_context {
- u8 format;
+ #define FSCRYPT_KEY_DESCRIPTOR_SIZE 8
+ struct fscrypt_context_v1 {
+ u8 version;
u8 contents_encryption_mode;
u8 filenames_encryption_mode;
u8 flags;
- u8 master_key_descriptor[FS_KEY_DESCRIPTOR_SIZE];
+ u8 master_key_descriptor[FSCRYPT_KEY_DESCRIPTOR_SIZE];
u8 nonce[FS_KEY_DERIVATION_NONCE_SIZE];
};
-Note that :c:type:`struct fscrypt_context` contains the same
-information as :c:type:`struct fscrypt_policy` (see `Setting an
-encryption policy`_), except that :c:type:`struct fscrypt_context`
-also contains a nonce. The nonce is randomly generated by the kernel
-and is used to derive the inode's encryption key as described in
-`Per-file keys`_.
+ #define FSCRYPT_KEY_IDENTIFIER_SIZE 16
+ struct fscrypt_context_v2 {
+ u8 version;
+ u8 contents_encryption_mode;
+ u8 filenames_encryption_mode;
+ u8 flags;
+ u8 __reserved[4];
+ u8 master_key_identifier[FSCRYPT_KEY_IDENTIFIER_SIZE];
+ u8 nonce[FS_KEY_DERIVATION_NONCE_SIZE];
+ };
+
+The context structs contain the same information as the corresponding
+policy structs (see `Setting an encryption policy`_), except that the
+context structs also contain a nonce. The nonce is randomly generated
+by the kernel and is used as KDF input or as a tweak to cause
+different files to be encrypted differently; see `Per-file keys`_ and
+`DIRECT_KEY and per-mode keys`_.
Data path changes
-----------------
diff --git a/Documentation/filesystems/fsverity.rst b/Documentation/filesystems/fsverity.rst
new file mode 100644
index 0000000..42a0b6d
--- /dev/null
+++ b/Documentation/filesystems/fsverity.rst
@@ -0,0 +1,726 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+.. _fsverity:
+
+=======================================================
+fs-verity: read-only file-based authenticity protection
+=======================================================
+
+Introduction
+============
+
+fs-verity (``fs/verity/``) is a support layer that filesystems can
+hook into to support transparent integrity and authenticity protection
+of read-only files. Currently, it is supported by the ext4 and f2fs
+filesystems. Like fscrypt, not too much filesystem-specific code is
+needed to support fs-verity.
+
+fs-verity is similar to `dm-verity
+<https://www.kernel.org/doc/Documentation/device-mapper/verity.txt>`_
+but works on files rather than block devices. On regular files on
+filesystems supporting fs-verity, userspace can execute an ioctl that
+causes the filesystem to build a Merkle tree for the file and persist
+it to a filesystem-specific location associated with the file.
+
+After this, the file is made readonly, and all reads from the file are
+automatically verified against the file's Merkle tree. Reads of any
+corrupted data, including mmap reads, will fail.
+
+Userspace can use another ioctl to retrieve the root hash (actually
+the "file measurement", which is a hash that includes the root hash)
+that fs-verity is enforcing for the file. This ioctl executes in
+constant time, regardless of the file size.
+
+fs-verity is essentially a way to hash a file in constant time,
+subject to the caveat that reads which would violate the hash will
+fail at runtime.
+
+Use cases
+=========
+
+By itself, the base fs-verity feature only provides integrity
+protection, i.e. detection of accidental (non-malicious) corruption.
+
+However, because fs-verity makes retrieving the file hash extremely
+efficient, it's primarily meant to be used as a tool to support
+authentication (detection of malicious modifications) or auditing
+(logging file hashes before use).
+
+Trusted userspace code (e.g. operating system code running on a
+read-only partition that is itself authenticated by dm-verity) can
+authenticate the contents of an fs-verity file by using the
+`FS_IOC_MEASURE_VERITY`_ ioctl to retrieve its hash, then verifying a
+digital signature of it.
+
+A standard file hash could be used instead of fs-verity. However,
+this is inefficient if the file is large and only a small portion may
+be accessed. This is often the case for Android application package
+(APK) files, for example. These typically contain many translations,
+classes, and other resources that are infrequently or even never
+accessed on a particular device. It would be slow and wasteful to
+read and hash the entire file before starting the application.
+
+Unlike an ahead-of-time hash, fs-verity also re-verifies data each
+time it's paged in. This ensures that malicious disk firmware can't
+undetectably change the contents of the file at runtime.
+
+fs-verity does not replace or obsolete dm-verity. dm-verity should
+still be used on read-only filesystems. fs-verity is for files that
+must live on a read-write filesystem because they are independently
+updated and potentially user-installed, so dm-verity cannot be used.
+
+The base fs-verity feature is a hashing mechanism only; actually
+authenticating the files is up to userspace. However, to meet some
+users' needs, fs-verity optionally supports a simple signature
+verification mechanism where users can configure the kernel to require
+that all fs-verity files be signed by a key loaded into a keyring; see
+`Built-in signature verification`_. Support for fs-verity file hashes
+in IMA (Integrity Measurement Architecture) policies is also planned.
+
+User API
+========
+
+FS_IOC_ENABLE_VERITY
+--------------------
+
+The FS_IOC_ENABLE_VERITY ioctl enables fs-verity on a file. It takes
+in a pointer to a :c:type:`struct fsverity_enable_arg`, defined as
+follows::
+
+ struct fsverity_enable_arg {
+ __u32 version;
+ __u32 hash_algorithm;
+ __u32 block_size;
+ __u32 salt_size;
+ __u64 salt_ptr;
+ __u32 sig_size;
+ __u32 __reserved1;
+ __u64 sig_ptr;
+ __u64 __reserved2[11];
+ };
+
+This structure contains the parameters of the Merkle tree to build for
+the file, and optionally contains a signature. It must be initialized
+as follows:
+
+- ``version`` must be 1.
+- ``hash_algorithm`` must be the identifier for the hash algorithm to
+ use for the Merkle tree, such as FS_VERITY_HASH_ALG_SHA256. See
+ ``include/uapi/linux/fsverity.h`` for the list of possible values.
+- ``block_size`` must be the Merkle tree block size. Currently, this
+ must be equal to the system page size, which is usually 4096 bytes.
+ Other sizes may be supported in the future. This value is not
+ necessarily the same as the filesystem block size.
+- ``salt_size`` is the size of the salt in bytes, or 0 if no salt is
+ provided. The salt is a value that is prepended to every hashed
+ block; it can be used to personalize the hashing for a particular
+ file or device. Currently the maximum salt size is 32 bytes.
+- ``salt_ptr`` is the pointer to the salt, or NULL if no salt is
+ provided.
+- ``sig_size`` is the size of the signature in bytes, or 0 if no
+ signature is provided. Currently the signature is (somewhat
+ arbitrarily) limited to 16128 bytes. See `Built-in signature
+ verification`_ for more information.
+- ``sig_ptr`` is the pointer to the signature, or NULL if no
+ signature is provided.
+- All reserved fields must be zeroed.
+
+FS_IOC_ENABLE_VERITY causes the filesystem to build a Merkle tree for
+the file and persist it to a filesystem-specific location associated
+with the file, then mark the file as a verity file. This ioctl may
+take a long time to execute on large files, and it is interruptible by
+fatal signals.
+
+FS_IOC_ENABLE_VERITY checks for write access to the inode. However,
+it must be executed on an O_RDONLY file descriptor and no processes
+can have the file open for writing. Attempts to open the file for
+writing while this ioctl is executing will fail with ETXTBSY. (This
+is necessary to guarantee that no writable file descriptors will exist
+after verity is enabled, and to guarantee that the file's contents are
+stable while the Merkle tree is being built over it.)
+
+On success, FS_IOC_ENABLE_VERITY returns 0, and the file becomes a
+verity file. On failure (including the case of interruption by a
+fatal signal), no changes are made to the file.
+
+FS_IOC_ENABLE_VERITY can fail with the following errors:
+
+- ``EACCES``: the process does not have write access to the file
+- ``EBADMSG``: the signature is malformed
+- ``EBUSY``: this ioctl is already running on the file
+- ``EEXIST``: the file already has verity enabled
+- ``EFAULT``: the caller provided inaccessible memory
+- ``EINTR``: the operation was interrupted by a fatal signal
+- ``EINVAL``: unsupported version, hash algorithm, or block size; or
+ reserved bits are set; or the file descriptor refers to neither a
+ regular file nor a directory.
+- ``EISDIR``: the file descriptor refers to a directory
+- ``EKEYREJECTED``: the signature doesn't match the file
+- ``EMSGSIZE``: the salt or signature is too long
+- ``ENOKEY``: the fs-verity keyring doesn't contain the certificate
+ needed to verify the signature
+- ``ENOPKG``: fs-verity recognizes the hash algorithm, but it's not
+ available in the kernel's crypto API as currently configured (e.g.
+ for SHA-512, missing CONFIG_CRYPTO_SHA512).
+- ``ENOTTY``: this type of filesystem does not implement fs-verity
+- ``EOPNOTSUPP``: the kernel was not configured with fs-verity
+ support; or the filesystem superblock has not had the 'verity'
+ feature enabled on it; or the filesystem does not support fs-verity
+ on this file. (See `Filesystem support`_.)
+- ``EPERM``: the file is append-only; or, a signature is required and
+ one was not provided.
+- ``EROFS``: the filesystem is read-only
+- ``ETXTBSY``: someone has the file open for writing. This can be the
+ caller's file descriptor, another open file descriptor, or the file
+ reference held by a writable memory map.
+
+FS_IOC_MEASURE_VERITY
+---------------------
+
+The FS_IOC_MEASURE_VERITY ioctl retrieves the measurement of a verity
+file. The file measurement is a digest that cryptographically
+identifies the file contents that are being enforced on reads.
+
+This ioctl takes in a pointer to a variable-length structure::
+
+ struct fsverity_digest {
+ __u16 digest_algorithm;
+ __u16 digest_size; /* input/output */
+ __u8 digest[];
+ };
+
+``digest_size`` is an input/output field. On input, it must be
+initialized to the number of bytes allocated for the variable-length
+``digest`` field.
+
+On success, 0 is returned and the kernel fills in the structure as
+follows:
+
+- ``digest_algorithm`` will be the hash algorithm used for the file
+ measurement. It will match ``fsverity_enable_arg::hash_algorithm``.
+- ``digest_size`` will be the size of the digest in bytes, e.g. 32
+ for SHA-256. (This can be redundant with ``digest_algorithm``.)
+- ``digest`` will be the actual bytes of the digest.
+
+FS_IOC_MEASURE_VERITY is guaranteed to execute in constant time,
+regardless of the size of the file.
+
+FS_IOC_MEASURE_VERITY can fail with the following errors:
+
+- ``EFAULT``: the caller provided inaccessible memory
+- ``ENODATA``: the file is not a verity file
+- ``ENOTTY``: this type of filesystem does not implement fs-verity
+- ``EOPNOTSUPP``: the kernel was not configured with fs-verity
+ support, or the filesystem superblock has not had the 'verity'
+ feature enabled on it. (See `Filesystem support`_.)
+- ``EOVERFLOW``: the digest is longer than the specified
+ ``digest_size`` bytes. Try providing a larger buffer.
+
+FS_IOC_GETFLAGS
+---------------
+
+The existing ioctl FS_IOC_GETFLAGS (which isn't specific to fs-verity)
+can also be used to check whether a file has fs-verity enabled or not.
+To do so, check for FS_VERITY_FL (0x00100000) in the returned flags.
+
+The verity flag is not settable via FS_IOC_SETFLAGS. You must use
+FS_IOC_ENABLE_VERITY instead, since parameters must be provided.
+
+Accessing verity files
+======================
+
+Applications can transparently access a verity file just like a
+non-verity one, with the following exceptions:
+
+- Verity files are readonly. They cannot be opened for writing or
+ truncate()d, even if the file mode bits allow it. Attempts to do
+ one of these things will fail with EPERM. However, changes to
+ metadata such as owner, mode, timestamps, and xattrs are still
+ allowed, since these are not measured by fs-verity. Verity files
+ can also still be renamed, deleted, and linked to.
+
+- Direct I/O is not supported on verity files. Attempts to use direct
+ I/O on such files will fall back to buffered I/O.
+
+- DAX (Direct Access) is not supported on verity files, because this
+ would circumvent the data verification.
+
+- Reads of data that doesn't match the verity Merkle tree will fail
+ with EIO (for read()) or SIGBUS (for mmap() reads).
+
+- If the sysctl "fs.verity.require_signatures" is set to 1 and the
+ file's verity measurement is not signed by a key in the fs-verity
+ keyring, then opening the file will fail. See `Built-in signature
+ verification`_.
+
+Direct access to the Merkle tree is not supported. Therefore, if a
+verity file is copied, or is backed up and restored, then it will lose
+its "verity"-ness. fs-verity is primarily meant for files like
+executables that are managed by a package manager.
+
+File measurement computation
+============================
+
+This section describes how fs-verity hashes the file contents using a
+Merkle tree to produce the "file measurement" which cryptographically
+identifies the file contents. This algorithm is the same for all
+filesystems that support fs-verity.
+
+Userspace only needs to be aware of this algorithm if it needs to
+compute the file measurement itself, e.g. in order to sign the file.
+
+.. _fsverity_merkle_tree:
+
+Merkle tree
+-----------
+
+The file contents is divided into blocks, where the block size is
+configurable but is usually 4096 bytes. The end of the last block is
+zero-padded if needed. Each block is then hashed, producing the first
+level of hashes. Then, the hashes in this first level are grouped
+into 'blocksize'-byte blocks (zero-padding the ends as needed) and
+these blocks are hashed, producing the second level of hashes. This
+proceeds up the tree until only a single block remains. The hash of
+this block is the "Merkle tree root hash".
+
+If the file fits in one block and is nonempty, then the "Merkle tree
+root hash" is simply the hash of the single data block. If the file
+is empty, then the "Merkle tree root hash" is all zeroes.
+
+The "blocks" here are not necessarily the same as "filesystem blocks".
+
+If a salt was specified, then it's zero-padded to the closest multiple
+of the input size of the hash algorithm's compression function, e.g.
+64 bytes for SHA-256 or 128 bytes for SHA-512. The padded salt is
+prepended to every data or Merkle tree block that is hashed.
+
+The purpose of the block padding is to cause every hash to be taken
+over the same amount of data, which simplifies the implementation and
+keeps open more possibilities for hardware acceleration. The purpose
+of the salt padding is to make the salting "free" when the salted hash
+state is precomputed, then imported for each hash.
+
+Example: in the recommended configuration of SHA-256 and 4K blocks,
+128 hash values fit in each block. Thus, each level of the Merkle
+tree is approximately 128 times smaller than the previous, and for
+large files the Merkle tree's size converges to approximately 1/127 of
+the original file size. However, for small files, the padding is
+significant, making the space overhead proportionally more.
+
+.. _fsverity_descriptor:
+
+fs-verity descriptor
+--------------------
+
+By itself, the Merkle tree root hash is ambiguous. For example, it
+can't a distinguish a large file from a small second file whose data
+is exactly the top-level hash block of the first file. Ambiguities
+also arise from the convention of padding to the next block boundary.
+
+To solve this problem, the verity file measurement is actually
+computed as a hash of the following structure, which contains the
+Merkle tree root hash as well as other fields such as the file size::
+
+ struct fsverity_descriptor {
+ __u8 version; /* must be 1 */
+ __u8 hash_algorithm; /* Merkle tree hash algorithm */
+ __u8 log_blocksize; /* log2 of size of data and tree blocks */
+ __u8 salt_size; /* size of salt in bytes; 0 if none */
+ __le32 sig_size; /* must be 0 */
+ __le64 data_size; /* size of file the Merkle tree is built over */
+ __u8 root_hash[64]; /* Merkle tree root hash */
+ __u8 salt[32]; /* salt prepended to each hashed block */
+ __u8 __reserved[144]; /* must be 0's */
+ };
+
+Note that the ``sig_size`` field must be set to 0 for the purpose of
+computing the file measurement, even if a signature was provided (or
+will be provided) to `FS_IOC_ENABLE_VERITY`_.
+
+Built-in signature verification
+===============================
+
+With CONFIG_FS_VERITY_BUILTIN_SIGNATURES=y, fs-verity supports putting
+a portion of an authentication policy (see `Use cases`_) in the
+kernel. Specifically, it adds support for:
+
+1. At fs-verity module initialization time, a keyring ".fs-verity" is
+ created. The root user can add trusted X.509 certificates to this
+ keyring using the add_key() system call, then (when done)
+ optionally use keyctl_restrict_keyring() to prevent additional
+ certificates from being added.
+
+2. `FS_IOC_ENABLE_VERITY`_ accepts a pointer to a PKCS#7 formatted
+ detached signature in DER format of the file measurement. On
+ success, this signature is persisted alongside the Merkle tree.
+ Then, any time the file is opened, the kernel will verify the
+ file's actual measurement against this signature, using the
+ certificates in the ".fs-verity" keyring.
+
+3. A new sysctl "fs.verity.require_signatures" is made available.
+ When set to 1, the kernel requires that all verity files have a
+ correctly signed file measurement as described in (2).
+
+File measurements must be signed in the following format, which is
+similar to the structure used by `FS_IOC_MEASURE_VERITY`_::
+
+ struct fsverity_signed_digest {
+ char magic[8]; /* must be "FSVerity" */
+ __le16 digest_algorithm;
+ __le16 digest_size;
+ __u8 digest[];
+ };
+
+fs-verity's built-in signature verification support is meant as a
+relatively simple mechanism that can be used to provide some level of
+authenticity protection for verity files, as an alternative to doing
+the signature verification in userspace or using IMA-appraisal.
+However, with this mechanism, userspace programs still need to check
+that the verity bit is set, and there is no protection against verity
+files being swapped around.
+
+Filesystem support
+==================
+
+fs-verity is currently supported by the ext4 and f2fs filesystems.
+The CONFIG_FS_VERITY kconfig option must be enabled to use fs-verity
+on either filesystem.
+
+``include/linux/fsverity.h`` declares the interface between the
+``fs/verity/`` support layer and filesystems. Briefly, filesystems
+must provide an ``fsverity_operations`` structure that provides
+methods to read and write the verity metadata to a filesystem-specific
+location, including the Merkle tree blocks and
+``fsverity_descriptor``. Filesystems must also call functions in
+``fs/verity/`` at certain times, such as when a file is opened or when
+pages have been read into the pagecache. (See `Verifying data`_.)
+
+ext4
+----
+
+ext4 supports fs-verity since Linux TODO and e2fsprogs v1.45.2.
+
+To create verity files on an ext4 filesystem, the filesystem must have
+been formatted with ``-O verity`` or had ``tune2fs -O verity`` run on
+it. "verity" is an RO_COMPAT filesystem feature, so once set, old
+kernels will only be able to mount the filesystem readonly, and old
+versions of e2fsck will be unable to check the filesystem. Moreover,
+currently ext4 only supports mounting a filesystem with the "verity"
+feature when its block size is equal to PAGE_SIZE (often 4096 bytes).
+
+ext4 sets the EXT4_VERITY_FL on-disk inode flag on verity files. It
+can only be set by `FS_IOC_ENABLE_VERITY`_, and it cannot be cleared.
+
+ext4 also supports encryption, which can be used simultaneously with
+fs-verity. In this case, the plaintext data is verified rather than
+the ciphertext. This is necessary in order to make the file
+measurement meaningful, since every file is encrypted differently.
+
+ext4 stores the verity metadata (Merkle tree and fsverity_descriptor)
+past the end of the file, starting at the first 64K boundary beyond
+i_size. This approach works because (a) verity files are readonly,
+and (b) pages fully beyond i_size aren't visible to userspace but can
+be read/written internally by ext4 with only some relatively small
+changes to ext4. This approach avoids having to depend on the
+EA_INODE feature and on rearchitecturing ext4's xattr support to
+support paging multi-gigabyte xattrs into memory, and to support
+encrypting xattrs. Note that the verity metadata *must* be encrypted
+when the file is, since it contains hashes of the plaintext data.
+
+Currently, ext4 verity only supports the case where the Merkle tree
+block size, filesystem block size, and page size are all the same. It
+also only supports extent-based files.
+
+f2fs
+----
+
+f2fs supports fs-verity since Linux TODO and f2fs-tools v1.11.0.
+
+To create verity files on an f2fs filesystem, the filesystem must have
+been formatted with ``-O verity``.
+
+f2fs sets the FADVISE_VERITY_BIT on-disk inode flag on verity files.
+It can only be set by `FS_IOC_ENABLE_VERITY`_, and it cannot be
+cleared.
+
+Like ext4, f2fs stores the verity metadata (Merkle tree and
+fsverity_descriptor) past the end of the file, starting at the first
+64K boundary beyond i_size. See explanation for ext4 above.
+Moreover, f2fs supports at most 4096 bytes of xattr entries per inode
+which wouldn't be enough for even a single Merkle tree block.
+
+Currently, f2fs verity only supports a Merkle tree block size of 4096.
+Also, f2fs doesn't support enabling verity on files that currently
+have atomic or volatile writes pending.
+
+Implementation details
+======================
+
+Verifying data
+--------------
+
+fs-verity ensures that all reads of a verity file's data are verified,
+regardless of which syscall is used to do the read (e.g. mmap(),
+read(), pread()) and regardless of whether it's the first read or a
+later read (unless the later read can return cached data that was
+already verified). Below, we describe how filesystems implement this.
+
+Pagecache
+~~~~~~~~~
+
+For filesystems using Linux's pagecache, the ``->readpage()`` and
+``->readpages()`` methods must be modified to verify pages before they
+are marked Uptodate. Merely hooking ``->read_iter()`` would be
+insufficient, since ``->read_iter()`` is not used for memory maps.
+
+Therefore, fs/verity/ provides a function fsverity_verify_page() which
+verifies a page that has been read into the pagecache of a verity
+inode, but is still locked and not Uptodate, so it's not yet readable
+by userspace. As needed to do the verification,
+fsverity_verify_page() will call back into the filesystem to read
+Merkle tree pages via fsverity_operations::read_merkle_tree_page().
+
+fsverity_verify_page() returns false if verification failed; in this
+case, the filesystem must not set the page Uptodate. Following this,
+as per the usual Linux pagecache behavior, attempts by userspace to
+read() from the part of the file containing the page will fail with
+EIO, and accesses to the page within a memory map will raise SIGBUS.
+
+fsverity_verify_page() currently only supports the case where the
+Merkle tree block size is equal to PAGE_SIZE (often 4096 bytes).
+
+In principle, fsverity_verify_page() verifies the entire path in the
+Merkle tree from the data page to the root hash. However, for
+efficiency the filesystem may cache the hash pages. Therefore,
+fsverity_verify_page() only ascends the tree reading hash pages until
+an already-verified hash page is seen, as indicated by the PageChecked
+bit being set. It then verifies the path to that page.
+
+This optimization, which is also used by dm-verity, results in
+excellent sequential read performance. This is because usually (e.g.
+127 in 128 times for 4K blocks and SHA-256) the hash page from the
+bottom level of the tree will already be cached and checked from
+reading a previous data page. However, random reads perform worse.
+
+Block device based filesystems
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Block device based filesystems (e.g. ext4 and f2fs) in Linux also use
+the pagecache, so the above subsection applies too. However, they
+also usually read many pages from a file at once, grouped into a
+structure called a "bio". To make it easier for these types of
+filesystems to support fs-verity, fs/verity/ also provides a function
+fsverity_verify_bio() which verifies all pages in a bio.
+
+ext4 and f2fs also support encryption. If a verity file is also
+encrypted, the pages must be decrypted before being verified. To
+support this, these filesystems allocate a "post-read context" for
+each bio and store it in ``->bi_private``::
+
+ struct bio_post_read_ctx {
+ struct bio *bio;
+ struct work_struct work;
+ unsigned int cur_step;
+ unsigned int enabled_steps;
+ };
+
+``enabled_steps`` is a bitmask that specifies whether decryption,
+verity, or both is enabled. After the bio completes, for each needed
+postprocessing step the filesystem enqueues the bio_post_read_ctx on a
+workqueue, and then the workqueue work does the decryption or
+verification. Finally, pages where no decryption or verity error
+occurred are marked Uptodate, and the pages are unlocked.
+
+Files on ext4 and f2fs may contain holes. Normally, ``->readpages()``
+simply zeroes holes and sets the corresponding pages Uptodate; no bios
+are issued. To prevent this case from bypassing fs-verity, these
+filesystems use fsverity_verify_page() to verify hole pages.
+
+ext4 and f2fs disable direct I/O on verity files, since otherwise
+direct I/O would bypass fs-verity. (They also do the same for
+encrypted files.)
+
+Userspace utility
+=================
+
+This document focuses on the kernel, but a userspace utility for
+fs-verity can be found at:
+
+ https://git.kernel.org/pub/scm/linux/kernel/git/ebiggers/fsverity-utils.git
+
+See the README.md file in the fsverity-utils source tree for details,
+including examples of setting up fs-verity protected files.
+
+Tests
+=====
+
+To test fs-verity, use xfstests. For example, using `kvm-xfstests
+<https://github.com/tytso/xfstests-bld/blob/master/Documentation/kvm-quickstart.md>`_::
+
+ kvm-xfstests -c ext4,f2fs -g verity
+
+FAQ
+===
+
+This section answers frequently asked questions about fs-verity that
+weren't already directly answered in other parts of this document.
+
+:Q: Why isn't fs-verity part of IMA?
+:A: fs-verity and IMA (Integrity Measurement Architecture) have
+ different focuses. fs-verity is a filesystem-level mechanism for
+ hashing individual files using a Merkle tree. In contrast, IMA
+ specifies a system-wide policy that specifies which files are
+ hashed and what to do with those hashes, such as log them,
+ authenticate them, or add them to a measurement list.
+
+ IMA is planned to support the fs-verity hashing mechanism as an
+ alternative to doing full file hashes, for people who want the
+ performance and security benefits of the Merkle tree based hash.
+ But it doesn't make sense to force all uses of fs-verity to be
+ through IMA. As a standalone filesystem feature, fs-verity
+ already meets many users' needs, and it's testable like other
+ filesystem features e.g. with xfstests.
+
+:Q: Isn't fs-verity useless because the attacker can just modify the
+ hashes in the Merkle tree, which is stored on-disk?
+:A: To verify the authenticity of an fs-verity file you must verify
+ the authenticity of the "file measurement", which is basically the
+ root hash of the Merkle tree. See `Use cases`_.
+
+:Q: Isn't fs-verity useless because the attacker can just replace a
+ verity file with a non-verity one?
+:A: See `Use cases`_. In the initial use case, it's really trusted
+ userspace code that authenticates the files; fs-verity is just a
+ tool to do this job efficiently and securely. The trusted
+ userspace code will consider non-verity files to be inauthentic.
+
+:Q: Why does the Merkle tree need to be stored on-disk? Couldn't you
+ store just the root hash?
+:A: If the Merkle tree wasn't stored on-disk, then you'd have to
+ compute the entire tree when the file is first accessed, even if
+ just one byte is being read. This is a fundamental consequence of
+ how Merkle tree hashing works. To verify a leaf node, you need to
+ verify the whole path to the root hash, including the root node
+ (the thing which the root hash is a hash of). But if the root
+ node isn't stored on-disk, you have to compute it by hashing its
+ children, and so on until you've actually hashed the entire file.
+
+ That defeats most of the point of doing a Merkle tree-based hash,
+ since if you have to hash the whole file ahead of time anyway,
+ then you could simply do sha256(file) instead. That would be much
+ simpler, and a bit faster too.
+
+ It's true that an in-memory Merkle tree could still provide the
+ advantage of verification on every read rather than just on the
+ first read. However, it would be inefficient because every time a
+ hash page gets evicted (you can't pin the entire Merkle tree into
+ memory, since it may be very large), in order to restore it you
+ again need to hash everything below it in the tree. This again
+ defeats most of the point of doing a Merkle tree-based hash, since
+ a single block read could trigger re-hashing gigabytes of data.
+
+:Q: But couldn't you store just the leaf nodes and compute the rest?
+:A: See previous answer; this really just moves up one level, since
+ one could alternatively interpret the data blocks as being the
+ leaf nodes of the Merkle tree. It's true that the tree can be
+ computed much faster if the leaf level is stored rather than just
+ the data, but that's only because each level is less than 1% the
+ size of the level below (assuming the recommended settings of
+ SHA-256 and 4K blocks). For the exact same reason, by storing
+ "just the leaf nodes" you'd already be storing over 99% of the
+ tree, so you might as well simply store the whole tree.
+
+:Q: Can the Merkle tree be built ahead of time, e.g. distributed as
+ part of a package that is installed to many computers?
+:A: This isn't currently supported. It was part of the original
+ design, but was removed to simplify the kernel UAPI and because it
+ wasn't a critical use case. Files are usually installed once and
+ used many times, and cryptographic hashing is somewhat fast on
+ most modern processors.
+
+:Q: Why doesn't fs-verity support writes?
+:A: Write support would be very difficult and would require a
+ completely different design, so it's well outside the scope of
+ fs-verity. Write support would require:
+
+ - A way to maintain consistency between the data and hashes,
+ including all levels of hashes, since corruption after a crash
+ (especially of potentially the entire file!) is unacceptable.
+ The main options for solving this are data journalling,
+ copy-on-write, and log-structured volume. But it's very hard to
+ retrofit existing filesystems with new consistency mechanisms.
+ Data journalling is available on ext4, but is very slow.
+
+ - Rebuilding the the Merkle tree after every write, which would be
+ extremely inefficient. Alternatively, a different authenticated
+ dictionary structure such as an "authenticated skiplist" could
+ be used. However, this would be far more complex.
+
+ Compare it to dm-verity vs. dm-integrity. dm-verity is very
+ simple: the kernel just verifies read-only data against a
+ read-only Merkle tree. In contrast, dm-integrity supports writes
+ but is slow, is much more complex, and doesn't actually support
+ full-device authentication since it authenticates each sector
+ independently, i.e. there is no "root hash". It doesn't really
+ make sense for the same device-mapper target to support these two
+ very different cases; the same applies to fs-verity.
+
+:Q: Since verity files are immutable, why isn't the immutable bit set?
+:A: The existing "immutable" bit (FS_IMMUTABLE_FL) already has a
+ specific set of semantics which not only make the file contents
+ read-only, but also prevent the file from being deleted, renamed,
+ linked to, or having its owner or mode changed. These extra
+ properties are unwanted for fs-verity, so reusing the immutable
+ bit isn't appropriate.
+
+:Q: Why does the API use ioctls instead of setxattr() and getxattr()?
+:A: Abusing the xattr interface for basically arbitrary syscalls is
+ heavily frowned upon by most of the Linux filesystem developers.
+ An xattr should really just be an xattr on-disk, not an API to
+ e.g. magically trigger construction of a Merkle tree.
+
+:Q: Does fs-verity support remote filesystems?
+:A: Only ext4 and f2fs support is implemented currently, but in
+ principle any filesystem that can store per-file verity metadata
+ can support fs-verity, regardless of whether it's local or remote.
+ Some filesystems may have fewer options of where to store the
+ verity metadata; one possibility is to store it past the end of
+ the file and "hide" it from userspace by manipulating i_size. The
+ data verification functions provided by ``fs/verity/`` also assume
+ that the filesystem uses the Linux pagecache, but both local and
+ remote filesystems normally do so.
+
+:Q: Why is anything filesystem-specific at all? Shouldn't fs-verity
+ be implemented entirely at the VFS level?
+:A: There are many reasons why this is not possible or would be very
+ difficult, including the following:
+
+ - To prevent bypassing verification, pages must not be marked
+ Uptodate until they've been verified. Currently, each
+ filesystem is responsible for marking pages Uptodate via
+ ``->readpages()``. Therefore, currently it's not possible for
+ the VFS to do the verification on its own. Changing this would
+ require significant changes to the VFS and all filesystems.
+
+ - It would require defining a filesystem-independent way to store
+ the verity metadata. Extended attributes don't work for this
+ because (a) the Merkle tree may be gigabytes, but many
+ filesystems assume that all xattrs fit into a single 4K
+ filesystem block, and (b) ext4 and f2fs encryption doesn't
+ encrypt xattrs, yet the Merkle tree *must* be encrypted when the
+ file contents are, because it stores hashes of the plaintext
+ file contents.
+
+ So the verity metadata would have to be stored in an actual
+ file. Using a separate file would be very ugly, since the
+ metadata is fundamentally part of the file to be protected, and
+ it could cause problems where users could delete the real file
+ but not the metadata file or vice versa. On the other hand,
+ having it be in the same file would break applications unless
+ filesystems' notion of i_size were divorced from the VFS's,
+ which would be complex and require changes to all filesystems.
+
+ - It's desirable that FS_IOC_ENABLE_VERITY uses the filesystem's
+ transaction mechanism so that either the file ends up with
+ verity enabled, or no changes were made. Allowing intermediate
+ states to occur after a crash may cause problems.
diff --git a/Documentation/filesystems/index.rst b/Documentation/filesystems/index.rst
index 2de2fe2..2c3a9f76 100644
--- a/Documentation/filesystems/index.rst
+++ b/Documentation/filesystems/index.rst
@@ -20,6 +20,10 @@
path-lookup
api-summary
splice
+ locking
+ directory-locking
+
+ porting
Filesystem support layers
=========================
@@ -32,3 +36,14 @@
journalling
fscrypt
+ fsverity
+
+Filesystems
+===========
+
+Documentation for filesystem implementations.
+
+.. toctree::
+ :maxdepth: 2
+
+ virtiofs
diff --git a/Documentation/filesystems/jfs.txt b/Documentation/filesystems/jfs.txt
deleted file mode 100644
index 41fd7579..0000000
--- a/Documentation/filesystems/jfs.txt
+++ /dev/null
@@ -1,52 +0,0 @@
-IBM's Journaled File System (JFS) for Linux
-
-JFS Homepage: http://jfs.sourceforge.net/
-
-The following mount options are supported:
-(*) == default
-
-iocharset=name Character set to use for converting from Unicode to
- ASCII. The default is to do no conversion. Use
- iocharset=utf8 for UTF-8 translations. This requires
- CONFIG_NLS_UTF8 to be set in the kernel .config file.
- iocharset=none specifies the default behavior explicitly.
-
-resize=value Resize the volume to <value> blocks. JFS only supports
- growing a volume, not shrinking it. This option is only
- valid during a remount, when the volume is mounted
- read-write. The resize keyword with no value will grow
- the volume to the full size of the partition.
-
-nointegrity Do not write to the journal. The primary use of this option
- is to allow for higher performance when restoring a volume
- from backup media. The integrity of the volume is not
- guaranteed if the system abnormally abends.
-
-integrity(*) Commit metadata changes to the journal. Use this option to
- remount a volume where the nointegrity option was
- previously specified in order to restore normal behavior.
-
-errors=continue Keep going on a filesystem error.
-errors=remount-ro(*) Remount the filesystem read-only on an error.
-errors=panic Panic and halt the machine if an error occurs.
-
-uid=value Override on-disk uid with specified value
-gid=value Override on-disk gid with specified value
-umask=value Override on-disk umask with specified octal value. For
- directories, the execute bit will be set if the corresponding
- read bit is set.
-
-discard=minlen This enables/disables the use of discard/TRIM commands.
-discard The discard/TRIM commands are sent to the underlying
-nodiscard(*) block device when blocks are freed. This is useful for SSD
- devices and sparse/thinly-provisioned LUNs. The FITRIM ioctl
- command is also available together with the nodiscard option.
- The value of minlen specifies the minimum blockcount, when
- a TRIM command to the block device is considered useful.
- When no value is given to the discard option, it defaults to
- 64 blocks, which means 256KiB in JFS.
- The minlen value of discard overrides the minlen value given
- on an FITRIM ioctl().
-
-The JFS mailing list can be subscribed to by using the link labeled
-"Mail list Subscribe" at our web page http://jfs.sourceforge.net/
diff --git a/Documentation/filesystems/locking.rst b/Documentation/filesystems/locking.rst
new file mode 100644
index 0000000..fc3a070
--- /dev/null
+++ b/Documentation/filesystems/locking.rst
@@ -0,0 +1,665 @@
+=======
+Locking
+=======
+
+The text below describes the locking rules for VFS-related methods.
+It is (believed to be) up-to-date. *Please*, if you change anything in
+prototypes or locking protocols - update this file. And update the relevant
+instances in the tree, don't leave that to maintainers of filesystems/devices/
+etc. At the very least, put the list of dubious cases in the end of this file.
+Don't turn it into log - maintainers of out-of-the-tree code are supposed to
+be able to use diff(1).
+
+Thing currently missing here: socket operations. Alexey?
+
+dentry_operations
+=================
+
+prototypes::
+
+ int (*d_revalidate)(struct dentry *, unsigned int);
+ int (*d_weak_revalidate)(struct dentry *, unsigned int);
+ int (*d_hash)(const struct dentry *, struct qstr *);
+ int (*d_compare)(const struct dentry *,
+ unsigned int, const char *, const struct qstr *);
+ int (*d_delete)(struct dentry *);
+ int (*d_init)(struct dentry *);
+ void (*d_release)(struct dentry *);
+ void (*d_iput)(struct dentry *, struct inode *);
+ char *(*d_dname)((struct dentry *dentry, char *buffer, int buflen);
+ struct vfsmount *(*d_automount)(struct path *path);
+ int (*d_manage)(const struct path *, bool);
+ struct dentry *(*d_real)(struct dentry *, const struct inode *);
+
+locking rules:
+
+================== =========== ======== ============== ========
+ops rename_lock ->d_lock may block rcu-walk
+================== =========== ======== ============== ========
+d_revalidate: no no yes (ref-walk) maybe
+d_weak_revalidate: no no yes no
+d_hash no no no maybe
+d_compare: yes no no maybe
+d_delete: no yes no no
+d_init: no no yes no
+d_release: no no yes no
+d_prune: no yes no no
+d_iput: no no yes no
+d_dname: no no no no
+d_automount: no no yes no
+d_manage: no no yes (ref-walk) maybe
+d_real no no yes no
+================== =========== ======== ============== ========
+
+inode_operations
+================
+
+prototypes::
+
+ int (*create) (struct inode *,struct dentry *,umode_t, bool);
+ struct dentry * (*lookup) (struct inode *,struct dentry *, unsigned int);
+ int (*link) (struct dentry *,struct inode *,struct dentry *);
+ int (*unlink) (struct inode *,struct dentry *);
+ int (*symlink) (struct inode *,struct dentry *,const char *);
+ int (*mkdir) (struct inode *,struct dentry *,umode_t);
+ int (*rmdir) (struct inode *,struct dentry *);
+ int (*mknod) (struct inode *,struct dentry *,umode_t,dev_t);
+ int (*rename) (struct inode *, struct dentry *,
+ struct inode *, struct dentry *, unsigned int);
+ int (*readlink) (struct dentry *, char __user *,int);
+ const char *(*get_link) (struct dentry *, struct inode *, struct delayed_call *);
+ void (*truncate) (struct inode *);
+ int (*permission) (struct inode *, int, unsigned int);
+ int (*get_acl)(struct inode *, int);
+ int (*setattr) (struct dentry *, struct iattr *);
+ int (*getattr) (const struct path *, struct kstat *, u32, unsigned int);
+ ssize_t (*listxattr) (struct dentry *, char *, size_t);
+ int (*fiemap)(struct inode *, struct fiemap_extent_info *, u64 start, u64 len);
+ void (*update_time)(struct inode *, struct timespec *, int);
+ int (*atomic_open)(struct inode *, struct dentry *,
+ struct file *, unsigned open_flag,
+ umode_t create_mode);
+ int (*tmpfile) (struct inode *, struct dentry *, umode_t);
+
+locking rules:
+ all may block
+
+============ =============================================
+ops i_rwsem(inode)
+============ =============================================
+lookup: shared
+create: exclusive
+link: exclusive (both)
+mknod: exclusive
+symlink: exclusive
+mkdir: exclusive
+unlink: exclusive (both)
+rmdir: exclusive (both)(see below)
+rename: exclusive (all) (see below)
+readlink: no
+get_link: no
+setattr: exclusive
+permission: no (may not block if called in rcu-walk mode)
+get_acl: no
+getattr: no
+listxattr: no
+fiemap: no
+update_time: no
+atomic_open: exclusive
+tmpfile: no
+============ =============================================
+
+
+ Additionally, ->rmdir(), ->unlink() and ->rename() have ->i_rwsem
+ exclusive on victim.
+ cross-directory ->rename() has (per-superblock) ->s_vfs_rename_sem.
+
+See Documentation/filesystems/directory-locking.rst for more detailed discussion
+of the locking scheme for directory operations.
+
+xattr_handler operations
+========================
+
+prototypes::
+
+ bool (*list)(struct dentry *dentry);
+ int (*get)(const struct xattr_handler *handler, struct dentry *dentry,
+ struct inode *inode, const char *name, void *buffer,
+ size_t size);
+ int (*set)(const struct xattr_handler *handler, struct dentry *dentry,
+ struct inode *inode, const char *name, const void *buffer,
+ size_t size, int flags);
+
+locking rules:
+ all may block
+
+===== ==============
+ops i_rwsem(inode)
+===== ==============
+list: no
+get: no
+set: exclusive
+===== ==============
+
+super_operations
+================
+
+prototypes::
+
+ struct inode *(*alloc_inode)(struct super_block *sb);
+ void (*free_inode)(struct inode *);
+ void (*destroy_inode)(struct inode *);
+ void (*dirty_inode) (struct inode *, int flags);
+ int (*write_inode) (struct inode *, struct writeback_control *wbc);
+ int (*drop_inode) (struct inode *);
+ void (*evict_inode) (struct inode *);
+ void (*put_super) (struct super_block *);
+ int (*sync_fs)(struct super_block *sb, int wait);
+ int (*freeze_fs) (struct super_block *);
+ int (*unfreeze_fs) (struct super_block *);
+ int (*statfs) (struct dentry *, struct kstatfs *);
+ int (*remount_fs) (struct super_block *, int *, char *);
+ void (*umount_begin) (struct super_block *);
+ int (*show_options)(struct seq_file *, struct dentry *);
+ ssize_t (*quota_read)(struct super_block *, int, char *, size_t, loff_t);
+ ssize_t (*quota_write)(struct super_block *, int, const char *, size_t, loff_t);
+ int (*bdev_try_to_free_page)(struct super_block*, struct page*, gfp_t);
+
+locking rules:
+ All may block [not true, see below]
+
+====================== ============ ========================
+ops s_umount note
+====================== ============ ========================
+alloc_inode:
+free_inode: called from RCU callback
+destroy_inode:
+dirty_inode:
+write_inode:
+drop_inode: !!!inode->i_lock!!!
+evict_inode:
+put_super: write
+sync_fs: read
+freeze_fs: write
+unfreeze_fs: write
+statfs: maybe(read) (see below)
+remount_fs: write
+umount_begin: no
+show_options: no (namespace_sem)
+quota_read: no (see below)
+quota_write: no (see below)
+bdev_try_to_free_page: no (see below)
+====================== ============ ========================
+
+->statfs() has s_umount (shared) when called by ustat(2) (native or
+compat), but that's an accident of bad API; s_umount is used to pin
+the superblock down when we only have dev_t given us by userland to
+identify the superblock. Everything else (statfs(), fstatfs(), etc.)
+doesn't hold it when calling ->statfs() - superblock is pinned down
+by resolving the pathname passed to syscall.
+
+->quota_read() and ->quota_write() functions are both guaranteed to
+be the only ones operating on the quota file by the quota code (via
+dqio_sem) (unless an admin really wants to screw up something and
+writes to quota files with quotas on). For other details about locking
+see also dquot_operations section.
+
+->bdev_try_to_free_page is called from the ->releasepage handler of
+the block device inode. See there for more details.
+
+file_system_type
+================
+
+prototypes::
+
+ struct dentry *(*mount) (struct file_system_type *, int,
+ const char *, void *);
+ void (*kill_sb) (struct super_block *);
+
+locking rules:
+
+======= =========
+ops may block
+======= =========
+mount yes
+kill_sb yes
+======= =========
+
+->mount() returns ERR_PTR or the root dentry; its superblock should be locked
+on return.
+
+->kill_sb() takes a write-locked superblock, does all shutdown work on it,
+unlocks and drops the reference.
+
+address_space_operations
+========================
+prototypes::
+
+ int (*writepage)(struct page *page, struct writeback_control *wbc);
+ int (*readpage)(struct file *, struct page *);
+ int (*writepages)(struct address_space *, struct writeback_control *);
+ int (*set_page_dirty)(struct page *page);
+ int (*readpages)(struct file *filp, struct address_space *mapping,
+ struct list_head *pages, unsigned nr_pages);
+ int (*write_begin)(struct file *, struct address_space *mapping,
+ loff_t pos, unsigned len, unsigned flags,
+ struct page **pagep, void **fsdata);
+ int (*write_end)(struct file *, struct address_space *mapping,
+ loff_t pos, unsigned len, unsigned copied,
+ struct page *page, void *fsdata);
+ sector_t (*bmap)(struct address_space *, sector_t);
+ void (*invalidatepage) (struct page *, unsigned int, unsigned int);
+ int (*releasepage) (struct page *, int);
+ void (*freepage)(struct page *);
+ int (*direct_IO)(struct kiocb *, struct iov_iter *iter);
+ bool (*isolate_page) (struct page *, isolate_mode_t);
+ int (*migratepage)(struct address_space *, struct page *, struct page *);
+ void (*putback_page) (struct page *);
+ int (*launder_page)(struct page *);
+ int (*is_partially_uptodate)(struct page *, unsigned long, unsigned long);
+ int (*error_remove_page)(struct address_space *, struct page *);
+ int (*swap_activate)(struct file *);
+ int (*swap_deactivate)(struct file *);
+
+locking rules:
+ All except set_page_dirty and freepage may block
+
+====================== ======================== =========
+ops PageLocked(page) i_rwsem
+====================== ======================== =========
+writepage: yes, unlocks (see below)
+readpage: yes, unlocks
+writepages:
+set_page_dirty no
+readpages:
+write_begin: locks the page exclusive
+write_end: yes, unlocks exclusive
+bmap:
+invalidatepage: yes
+releasepage: yes
+freepage: yes
+direct_IO:
+isolate_page: yes
+migratepage: yes (both)
+putback_page: yes
+launder_page: yes
+is_partially_uptodate: yes
+error_remove_page: yes
+swap_activate: no
+swap_deactivate: no
+====================== ======================== =========
+
+->write_begin(), ->write_end() and ->readpage() may be called from
+the request handler (/dev/loop).
+
+->readpage() unlocks the page, either synchronously or via I/O
+completion.
+
+->readpages() populates the pagecache with the passed pages and starts
+I/O against them. They come unlocked upon I/O completion.
+
+->writepage() is used for two purposes: for "memory cleansing" and for
+"sync". These are quite different operations and the behaviour may differ
+depending upon the mode.
+
+If writepage is called for sync (wbc->sync_mode != WBC_SYNC_NONE) then
+it *must* start I/O against the page, even if that would involve
+blocking on in-progress I/O.
+
+If writepage is called for memory cleansing (sync_mode ==
+WBC_SYNC_NONE) then its role is to get as much writeout underway as
+possible. So writepage should try to avoid blocking against
+currently-in-progress I/O.
+
+If the filesystem is not called for "sync" and it determines that it
+would need to block against in-progress I/O to be able to start new I/O
+against the page the filesystem should redirty the page with
+redirty_page_for_writepage(), then unlock the page and return zero.
+This may also be done to avoid internal deadlocks, but rarely.
+
+If the filesystem is called for sync then it must wait on any
+in-progress I/O and then start new I/O.
+
+The filesystem should unlock the page synchronously, before returning to the
+caller, unless ->writepage() returns special WRITEPAGE_ACTIVATE
+value. WRITEPAGE_ACTIVATE means that page cannot really be written out
+currently, and VM should stop calling ->writepage() on this page for some
+time. VM does this by moving page to the head of the active list, hence the
+name.
+
+Unless the filesystem is going to redirty_page_for_writepage(), unlock the page
+and return zero, writepage *must* run set_page_writeback() against the page,
+followed by unlocking it. Once set_page_writeback() has been run against the
+page, write I/O can be submitted and the write I/O completion handler must run
+end_page_writeback() once the I/O is complete. If no I/O is submitted, the
+filesystem must run end_page_writeback() against the page before returning from
+writepage.
+
+That is: after 2.5.12, pages which are under writeout are *not* locked. Note,
+if the filesystem needs the page to be locked during writeout, that is ok, too,
+the page is allowed to be unlocked at any point in time between the calls to
+set_page_writeback() and end_page_writeback().
+
+Note, failure to run either redirty_page_for_writepage() or the combination of
+set_page_writeback()/end_page_writeback() on a page submitted to writepage
+will leave the page itself marked clean but it will be tagged as dirty in the
+radix tree. This incoherency can lead to all sorts of hard-to-debug problems
+in the filesystem like having dirty inodes at umount and losing written data.
+
+->writepages() is used for periodic writeback and for syscall-initiated
+sync operations. The address_space should start I/O against at least
+``*nr_to_write`` pages. ``*nr_to_write`` must be decremented for each page
+which is written. The address_space implementation may write more (or less)
+pages than ``*nr_to_write`` asks for, but it should try to be reasonably close.
+If nr_to_write is NULL, all dirty pages must be written.
+
+writepages should _only_ write pages which are present on
+mapping->io_pages.
+
+->set_page_dirty() is called from various places in the kernel
+when the target page is marked as needing writeback. It may be called
+under spinlock (it cannot block) and is sometimes called with the page
+not locked.
+
+->bmap() is currently used by legacy ioctl() (FIBMAP) provided by some
+filesystems and by the swapper. The latter will eventually go away. Please,
+keep it that way and don't breed new callers.
+
+->invalidatepage() is called when the filesystem must attempt to drop
+some or all of the buffers from the page when it is being truncated. It
+returns zero on success. If ->invalidatepage is zero, the kernel uses
+block_invalidatepage() instead.
+
+->releasepage() is called when the kernel is about to try to drop the
+buffers from the page in preparation for freeing it. It returns zero to
+indicate that the buffers are (or may be) freeable. If ->releasepage is zero,
+the kernel assumes that the fs has no private interest in the buffers.
+
+->freepage() is called when the kernel is done dropping the page
+from the page cache.
+
+->launder_page() may be called prior to releasing a page if
+it is still found to be dirty. It returns zero if the page was successfully
+cleaned, or an error value if not. Note that in order to prevent the page
+getting mapped back in and redirtied, it needs to be kept locked
+across the entire operation.
+
+->swap_activate will be called with a non-zero argument on
+files backing (non block device backed) swapfiles. A return value
+of zero indicates success, in which case this file can be used for
+backing swapspace. The swapspace operations will be proxied to the
+address space operations.
+
+->swap_deactivate() will be called in the sys_swapoff()
+path after ->swap_activate() returned success.
+
+file_lock_operations
+====================
+
+prototypes::
+
+ void (*fl_copy_lock)(struct file_lock *, struct file_lock *);
+ void (*fl_release_private)(struct file_lock *);
+
+
+locking rules:
+
+=================== ============= =========
+ops inode->i_lock may block
+=================== ============= =========
+fl_copy_lock: yes no
+fl_release_private: maybe maybe[1]_
+=================== ============= =========
+
+.. [1]:
+ ->fl_release_private for flock or POSIX locks is currently allowed
+ to block. Leases however can still be freed while the i_lock is held and
+ so fl_release_private called on a lease should not block.
+
+lock_manager_operations
+=======================
+
+prototypes::
+
+ void (*lm_notify)(struct file_lock *); /* unblock callback */
+ int (*lm_grant)(struct file_lock *, struct file_lock *, int);
+ void (*lm_break)(struct file_lock *); /* break_lease callback */
+ int (*lm_change)(struct file_lock **, int);
+
+locking rules:
+
+========== ============= ================= =========
+ops inode->i_lock blocked_lock_lock may block
+========== ============= ================= =========
+lm_notify: yes yes no
+lm_grant: no no no
+lm_break: yes no no
+lm_change yes no no
+========== ============= ================= =========
+
+buffer_head
+===========
+
+prototypes::
+
+ void (*b_end_io)(struct buffer_head *bh, int uptodate);
+
+locking rules:
+
+called from interrupts. In other words, extreme care is needed here.
+bh is locked, but that's all warranties we have here. Currently only RAID1,
+highmem, fs/buffer.c, and fs/ntfs/aops.c are providing these. Block devices
+call this method upon the IO completion.
+
+block_device_operations
+=======================
+prototypes::
+
+ int (*open) (struct block_device *, fmode_t);
+ int (*release) (struct gendisk *, fmode_t);
+ int (*ioctl) (struct block_device *, fmode_t, unsigned, unsigned long);
+ int (*compat_ioctl) (struct block_device *, fmode_t, unsigned, unsigned long);
+ int (*direct_access) (struct block_device *, sector_t, void **,
+ unsigned long *);
+ int (*media_changed) (struct gendisk *);
+ void (*unlock_native_capacity) (struct gendisk *);
+ int (*revalidate_disk) (struct gendisk *);
+ int (*getgeo)(struct block_device *, struct hd_geometry *);
+ void (*swap_slot_free_notify) (struct block_device *, unsigned long);
+
+locking rules:
+
+======================= ===================
+ops bd_mutex
+======================= ===================
+open: yes
+release: yes
+ioctl: no
+compat_ioctl: no
+direct_access: no
+media_changed: no
+unlock_native_capacity: no
+revalidate_disk: no
+getgeo: no
+swap_slot_free_notify: no (see below)
+======================= ===================
+
+media_changed, unlock_native_capacity and revalidate_disk are called only from
+check_disk_change().
+
+swap_slot_free_notify is called with swap_lock and sometimes the page lock
+held.
+
+
+file_operations
+===============
+
+prototypes::
+
+ loff_t (*llseek) (struct file *, loff_t, int);
+ ssize_t (*read) (struct file *, char __user *, size_t, loff_t *);
+ ssize_t (*write) (struct file *, const char __user *, size_t, loff_t *);
+ ssize_t (*read_iter) (struct kiocb *, struct iov_iter *);
+ ssize_t (*write_iter) (struct kiocb *, struct iov_iter *);
+ int (*iterate) (struct file *, struct dir_context *);
+ int (*iterate_shared) (struct file *, struct dir_context *);
+ __poll_t (*poll) (struct file *, struct poll_table_struct *);
+ long (*unlocked_ioctl) (struct file *, unsigned int, unsigned long);
+ long (*compat_ioctl) (struct file *, unsigned int, unsigned long);
+ int (*mmap) (struct file *, struct vm_area_struct *);
+ int (*open) (struct inode *, struct file *);
+ int (*flush) (struct file *);
+ int (*release) (struct inode *, struct file *);
+ int (*fsync) (struct file *, loff_t start, loff_t end, int datasync);
+ int (*fasync) (int, struct file *, int);
+ int (*lock) (struct file *, int, struct file_lock *);
+ ssize_t (*readv) (struct file *, const struct iovec *, unsigned long,
+ loff_t *);
+ ssize_t (*writev) (struct file *, const struct iovec *, unsigned long,
+ loff_t *);
+ ssize_t (*sendfile) (struct file *, loff_t *, size_t, read_actor_t,
+ void __user *);
+ ssize_t (*sendpage) (struct file *, struct page *, int, size_t,
+ loff_t *, int);
+ unsigned long (*get_unmapped_area)(struct file *, unsigned long,
+ unsigned long, unsigned long, unsigned long);
+ int (*check_flags)(int);
+ int (*flock) (struct file *, int, struct file_lock *);
+ ssize_t (*splice_write)(struct pipe_inode_info *, struct file *, loff_t *,
+ size_t, unsigned int);
+ ssize_t (*splice_read)(struct file *, loff_t *, struct pipe_inode_info *,
+ size_t, unsigned int);
+ int (*setlease)(struct file *, long, struct file_lock **, void **);
+ long (*fallocate)(struct file *, int, loff_t, loff_t);
+
+locking rules:
+ All may block.
+
+->llseek() locking has moved from llseek to the individual llseek
+implementations. If your fs is not using generic_file_llseek, you
+need to acquire and release the appropriate locks in your ->llseek().
+For many filesystems, it is probably safe to acquire the inode
+mutex or just to use i_size_read() instead.
+Note: this does not protect the file->f_pos against concurrent modifications
+since this is something the userspace has to take care about.
+
+->iterate() is called with i_rwsem exclusive.
+
+->iterate_shared() is called with i_rwsem at least shared.
+
+->fasync() is responsible for maintaining the FASYNC bit in filp->f_flags.
+Most instances call fasync_helper(), which does that maintenance, so it's
+not normally something one needs to worry about. Return values > 0 will be
+mapped to zero in the VFS layer.
+
+->readdir() and ->ioctl() on directories must be changed. Ideally we would
+move ->readdir() to inode_operations and use a separate method for directory
+->ioctl() or kill the latter completely. One of the problems is that for
+anything that resembles union-mount we won't have a struct file for all
+components. And there are other reasons why the current interface is a mess...
+
+->read on directories probably must go away - we should just enforce -EISDIR
+in sys_read() and friends.
+
+->setlease operations should call generic_setlease() before or after setting
+the lease within the individual filesystem to record the result of the
+operation
+
+dquot_operations
+================
+
+prototypes::
+
+ int (*write_dquot) (struct dquot *);
+ int (*acquire_dquot) (struct dquot *);
+ int (*release_dquot) (struct dquot *);
+ int (*mark_dirty) (struct dquot *);
+ int (*write_info) (struct super_block *, int);
+
+These operations are intended to be more or less wrapping functions that ensure
+a proper locking wrt the filesystem and call the generic quota operations.
+
+What filesystem should expect from the generic quota functions:
+
+============== ============ =========================
+ops FS recursion Held locks when called
+============== ============ =========================
+write_dquot: yes dqonoff_sem or dqptr_sem
+acquire_dquot: yes dqonoff_sem or dqptr_sem
+release_dquot: yes dqonoff_sem or dqptr_sem
+mark_dirty: no -
+write_info: yes dqonoff_sem
+============== ============ =========================
+
+FS recursion means calling ->quota_read() and ->quota_write() from superblock
+operations.
+
+More details about quota locking can be found in fs/dquot.c.
+
+vm_operations_struct
+====================
+
+prototypes::
+
+ void (*open)(struct vm_area_struct*);
+ void (*close)(struct vm_area_struct*);
+ vm_fault_t (*fault)(struct vm_area_struct*, struct vm_fault *);
+ vm_fault_t (*page_mkwrite)(struct vm_area_struct *, struct vm_fault *);
+ vm_fault_t (*pfn_mkwrite)(struct vm_area_struct *, struct vm_fault *);
+ int (*access)(struct vm_area_struct *, unsigned long, void*, int, int);
+
+locking rules:
+
+============= ======== ===========================
+ops mmap_sem PageLocked(page)
+============= ======== ===========================
+open: yes
+close: yes
+fault: yes can return with page locked
+map_pages: yes
+page_mkwrite: yes can return with page locked
+pfn_mkwrite: yes
+access: yes
+============= ======== ===========================
+
+->fault() is called when a previously not present pte is about
+to be faulted in. The filesystem must find and return the page associated
+with the passed in "pgoff" in the vm_fault structure. If it is possible that
+the page may be truncated and/or invalidated, then the filesystem must lock
+the page, then ensure it is not already truncated (the page lock will block
+subsequent truncate), and then return with VM_FAULT_LOCKED, and the page
+locked. The VM will unlock the page.
+
+->map_pages() is called when VM asks to map easy accessible pages.
+Filesystem should find and map pages associated with offsets from "start_pgoff"
+till "end_pgoff". ->map_pages() is called with page table locked and must
+not block. If it's not possible to reach a page without blocking,
+filesystem should skip it. Filesystem should use do_set_pte() to setup
+page table entry. Pointer to entry associated with the page is passed in
+"pte" field in vm_fault structure. Pointers to entries for other offsets
+should be calculated relative to "pte".
+
+->page_mkwrite() is called when a previously read-only pte is
+about to become writeable. The filesystem again must ensure that there are
+no truncate/invalidate races, and then return with the page locked. If
+the page has been truncated, the filesystem should not look up a new page
+like the ->fault() handler, but simply return with VM_FAULT_NOPAGE, which
+will cause the VM to retry the fault.
+
+->pfn_mkwrite() is the same as page_mkwrite but when the pte is
+VM_PFNMAP or VM_MIXEDMAP with a page-less entry. Expected return is
+VM_FAULT_NOPAGE. Or one of the VM_FAULT_ERROR types. The default behavior
+after this call is to make the pte read-write, unless pfn_mkwrite returns
+an error.
+
+->access() is called when get_user_pages() fails in
+access_process_vm(), typically used to debug a process through
+/proc/pid/mem or ptrace. This function is needed only for
+VM_IO | VM_PFNMAP VMAs.
+
+--------------------------------------------------------------------------------
+
+ Dubious stuff
+
+(if you break something or notice that it is broken and do not fix it yourself
+- at least put it here)
diff --git a/Documentation/filesystems/mandatory-locking.txt b/Documentation/filesystems/mandatory-locking.txt
index 0979d1d..a251ca3 100644
--- a/Documentation/filesystems/mandatory-locking.txt
+++ b/Documentation/filesystems/mandatory-locking.txt
@@ -169,3 +169,13 @@
permissions (remove the setgid bit) before trying to read or write to it.
Of course, that might be a bit tricky if the system is hung :-(
+7. The "mand" mount option
+--------------------------
+Mandatory locking is disabled on all filesystems by default, and must be
+administratively enabled by mounting with "-o mand". That mount option
+is only allowed if the mounting task has the CAP_SYS_ADMIN capability.
+
+Since kernel v4.5, it is possible to disable mandatory locking
+altogether by setting CONFIG_MANDATORY_FILE_LOCKING to "n". A kernel
+with this disabled will reject attempts to mount filesystems with the
+"mand" mount option with the error status EPERM.
diff --git a/Documentation/filesystems/nfs/Exporting b/Documentation/filesystems/nfs/Exporting
deleted file mode 100644
index 6388914..0000000
--- a/Documentation/filesystems/nfs/Exporting
+++ /dev/null
@@ -1,160 +0,0 @@
-
-Making Filesystems Exportable
-=============================
-
-Overview
---------
-
-All filesystem operations require a dentry (or two) as a starting
-point. Local applications have a reference-counted hold on suitable
-dentries via open file descriptors or cwd/root. However remote
-applications that access a filesystem via a remote filesystem protocol
-such as NFS may not be able to hold such a reference, and so need a
-different way to refer to a particular dentry. As the alternative
-form of reference needs to be stable across renames, truncates, and
-server-reboot (among other things, though these tend to be the most
-problematic), there is no simple answer like 'filename'.
-
-The mechanism discussed here allows each filesystem implementation to
-specify how to generate an opaque (outside of the filesystem) byte
-string for any dentry, and how to find an appropriate dentry for any
-given opaque byte string.
-This byte string will be called a "filehandle fragment" as it
-corresponds to part of an NFS filehandle.
-
-A filesystem which supports the mapping between filehandle fragments
-and dentries will be termed "exportable".
-
-
-
-Dcache Issues
--------------
-
-The dcache normally contains a proper prefix of any given filesystem
-tree. This means that if any filesystem object is in the dcache, then
-all of the ancestors of that filesystem object are also in the dcache.
-As normal access is by filename this prefix is created naturally and
-maintained easily (by each object maintaining a reference count on
-its parent).
-
-However when objects are included into the dcache by interpreting a
-filehandle fragment, there is no automatic creation of a path prefix
-for the object. This leads to two related but distinct features of
-the dcache that are not needed for normal filesystem access.
-
-1/ The dcache must sometimes contain objects that are not part of the
- proper prefix. i.e that are not connected to the root.
-2/ The dcache must be prepared for a newly found (via ->lookup) directory
- to already have a (non-connected) dentry, and must be able to move
- that dentry into place (based on the parent and name in the
- ->lookup). This is particularly needed for directories as
- it is a dcache invariant that directories only have one dentry.
-
-To implement these features, the dcache has:
-
-a/ A dentry flag DCACHE_DISCONNECTED which is set on
- any dentry that might not be part of the proper prefix.
- This is set when anonymous dentries are created, and cleared when a
- dentry is noticed to be a child of a dentry which is in the proper
- prefix. If the refcount on a dentry with this flag set
- becomes zero, the dentry is immediately discarded, rather than being
- kept in the dcache. If a dentry that is not already in the dcache
- is repeatedly accessed by filehandle (as NFSD might do), an new dentry
- will be a allocated for each access, and discarded at the end of
- the access.
-
- Note that such a dentry can acquire children, name, ancestors, etc.
- without losing DCACHE_DISCONNECTED - that flag is only cleared when
- subtree is successfully reconnected to root. Until then dentries
- in such subtree are retained only as long as there are references;
- refcount reaching zero means immediate eviction, same as for unhashed
- dentries. That guarantees that we won't need to hunt them down upon
- umount.
-
-b/ A primitive for creation of secondary roots - d_obtain_root(inode).
- Those do _not_ bear DCACHE_DISCONNECTED. They are placed on the
- per-superblock list (->s_roots), so they can be located at umount
- time for eviction purposes.
-
-c/ Helper routines to allocate anonymous dentries, and to help attach
- loose directory dentries at lookup time. They are:
- d_obtain_alias(inode) will return a dentry for the given inode.
- If the inode already has a dentry, one of those is returned.
- If it doesn't, a new anonymous (IS_ROOT and
- DCACHE_DISCONNECTED) dentry is allocated and attached.
- In the case of a directory, care is taken that only one dentry
- can ever be attached.
- d_splice_alias(inode, dentry) will introduce a new dentry into the tree;
- either the passed-in dentry or a preexisting alias for the given inode
- (such as an anonymous one created by d_obtain_alias), if appropriate.
- It returns NULL when the passed-in dentry is used, following the calling
- convention of ->lookup.
-
-Filesystem Issues
------------------
-
-For a filesystem to be exportable it must:
-
- 1/ provide the filehandle fragment routines described below.
- 2/ make sure that d_splice_alias is used rather than d_add
- when ->lookup finds an inode for a given parent and name.
-
- If inode is NULL, d_splice_alias(inode, dentry) is equivalent to
-
- d_add(dentry, inode), NULL
-
- Similarly, d_splice_alias(ERR_PTR(err), dentry) = ERR_PTR(err)
-
- Typically the ->lookup routine will simply end with a:
-
- return d_splice_alias(inode, dentry);
- }
-
-
-
- A file system implementation declares that instances of the filesystem
-are exportable by setting the s_export_op field in the struct
-super_block. This field must point to a "struct export_operations"
-struct which has the following members:
-
- encode_fh (optional)
- Takes a dentry and creates a filehandle fragment which can later be used
- to find or create a dentry for the same object. The default
- implementation creates a filehandle fragment that encodes a 32bit inode
- and generation number for the inode encoded, and if necessary the
- same information for the parent.
-
- fh_to_dentry (mandatory)
- Given a filehandle fragment, this should find the implied object and
- create a dentry for it (possibly with d_obtain_alias).
-
- fh_to_parent (optional but strongly recommended)
- Given a filehandle fragment, this should find the parent of the
- implied object and create a dentry for it (possibly with
- d_obtain_alias). May fail if the filehandle fragment is too small.
-
- get_parent (optional but strongly recommended)
- When given a dentry for a directory, this should return a dentry for
- the parent. Quite possibly the parent dentry will have been allocated
- by d_alloc_anon. The default get_parent function just returns an error
- so any filehandle lookup that requires finding a parent will fail.
- ->lookup("..") is *not* used as a default as it can leave ".." entries
- in the dcache which are too messy to work with.
-
- get_name (optional)
- When given a parent dentry and a child dentry, this should find a name
- in the directory identified by the parent dentry, which leads to the
- object identified by the child dentry. If no get_name function is
- supplied, a default implementation is provided which uses vfs_readdir
- to find potential names, and matches inode numbers to find the correct
- match.
-
-
-A filehandle fragment consists of an array of 1 or more 4byte words,
-together with a one byte "type".
-The decode_fh routine should not depend on the stated size that is
-passed to it. This size may be larger than the original filehandle
-generated by encode_fh, in which case it will have been padded with
-nuls. Rather, the encode_fh routine should choose a "type" which
-indicates the decode_fh how much of the filehandle is valid, and how
-it should be interpreted.
diff --git a/Documentation/filesystems/nfs/exporting.rst b/Documentation/filesystems/nfs/exporting.rst
new file mode 100644
index 0000000..33d588a
--- /dev/null
+++ b/Documentation/filesystems/nfs/exporting.rst
@@ -0,0 +1,165 @@
+:orphan:
+
+Making Filesystems Exportable
+=============================
+
+Overview
+--------
+
+All filesystem operations require a dentry (or two) as a starting
+point. Local applications have a reference-counted hold on suitable
+dentries via open file descriptors or cwd/root. However remote
+applications that access a filesystem via a remote filesystem protocol
+such as NFS may not be able to hold such a reference, and so need a
+different way to refer to a particular dentry. As the alternative
+form of reference needs to be stable across renames, truncates, and
+server-reboot (among other things, though these tend to be the most
+problematic), there is no simple answer like 'filename'.
+
+The mechanism discussed here allows each filesystem implementation to
+specify how to generate an opaque (outside of the filesystem) byte
+string for any dentry, and how to find an appropriate dentry for any
+given opaque byte string.
+This byte string will be called a "filehandle fragment" as it
+corresponds to part of an NFS filehandle.
+
+A filesystem which supports the mapping between filehandle fragments
+and dentries will be termed "exportable".
+
+
+
+Dcache Issues
+-------------
+
+The dcache normally contains a proper prefix of any given filesystem
+tree. This means that if any filesystem object is in the dcache, then
+all of the ancestors of that filesystem object are also in the dcache.
+As normal access is by filename this prefix is created naturally and
+maintained easily (by each object maintaining a reference count on
+its parent).
+
+However when objects are included into the dcache by interpreting a
+filehandle fragment, there is no automatic creation of a path prefix
+for the object. This leads to two related but distinct features of
+the dcache that are not needed for normal filesystem access.
+
+1. The dcache must sometimes contain objects that are not part of the
+ proper prefix. i.e that are not connected to the root.
+2. The dcache must be prepared for a newly found (via ->lookup) directory
+ to already have a (non-connected) dentry, and must be able to move
+ that dentry into place (based on the parent and name in the
+ ->lookup). This is particularly needed for directories as
+ it is a dcache invariant that directories only have one dentry.
+
+To implement these features, the dcache has:
+
+a. A dentry flag DCACHE_DISCONNECTED which is set on
+ any dentry that might not be part of the proper prefix.
+ This is set when anonymous dentries are created, and cleared when a
+ dentry is noticed to be a child of a dentry which is in the proper
+ prefix. If the refcount on a dentry with this flag set
+ becomes zero, the dentry is immediately discarded, rather than being
+ kept in the dcache. If a dentry that is not already in the dcache
+ is repeatedly accessed by filehandle (as NFSD might do), an new dentry
+ will be a allocated for each access, and discarded at the end of
+ the access.
+
+ Note that such a dentry can acquire children, name, ancestors, etc.
+ without losing DCACHE_DISCONNECTED - that flag is only cleared when
+ subtree is successfully reconnected to root. Until then dentries
+ in such subtree are retained only as long as there are references;
+ refcount reaching zero means immediate eviction, same as for unhashed
+ dentries. That guarantees that we won't need to hunt them down upon
+ umount.
+
+b. A primitive for creation of secondary roots - d_obtain_root(inode).
+ Those do _not_ bear DCACHE_DISCONNECTED. They are placed on the
+ per-superblock list (->s_roots), so they can be located at umount
+ time for eviction purposes.
+
+c. Helper routines to allocate anonymous dentries, and to help attach
+ loose directory dentries at lookup time. They are:
+
+ d_obtain_alias(inode) will return a dentry for the given inode.
+ If the inode already has a dentry, one of those is returned.
+
+ If it doesn't, a new anonymous (IS_ROOT and
+ DCACHE_DISCONNECTED) dentry is allocated and attached.
+
+ In the case of a directory, care is taken that only one dentry
+ can ever be attached.
+
+ d_splice_alias(inode, dentry) will introduce a new dentry into the tree;
+ either the passed-in dentry or a preexisting alias for the given inode
+ (such as an anonymous one created by d_obtain_alias), if appropriate.
+ It returns NULL when the passed-in dentry is used, following the calling
+ convention of ->lookup.
+
+Filesystem Issues
+-----------------
+
+For a filesystem to be exportable it must:
+
+ 1. provide the filehandle fragment routines described below.
+ 2. make sure that d_splice_alias is used rather than d_add
+ when ->lookup finds an inode for a given parent and name.
+
+ If inode is NULL, d_splice_alias(inode, dentry) is equivalent to::
+
+ d_add(dentry, inode), NULL
+
+ Similarly, d_splice_alias(ERR_PTR(err), dentry) = ERR_PTR(err)
+
+ Typically the ->lookup routine will simply end with a::
+
+ return d_splice_alias(inode, dentry);
+ }
+
+
+
+A file system implementation declares that instances of the filesystem
+are exportable by setting the s_export_op field in the struct
+super_block. This field must point to a "struct export_operations"
+struct which has the following members:
+
+ encode_fh (optional)
+ Takes a dentry and creates a filehandle fragment which can later be used
+ to find or create a dentry for the same object. The default
+ implementation creates a filehandle fragment that encodes a 32bit inode
+ and generation number for the inode encoded, and if necessary the
+ same information for the parent.
+
+ fh_to_dentry (mandatory)
+ Given a filehandle fragment, this should find the implied object and
+ create a dentry for it (possibly with d_obtain_alias).
+
+ fh_to_parent (optional but strongly recommended)
+ Given a filehandle fragment, this should find the parent of the
+ implied object and create a dentry for it (possibly with
+ d_obtain_alias). May fail if the filehandle fragment is too small.
+
+ get_parent (optional but strongly recommended)
+ When given a dentry for a directory, this should return a dentry for
+ the parent. Quite possibly the parent dentry will have been allocated
+ by d_alloc_anon. The default get_parent function just returns an error
+ so any filehandle lookup that requires finding a parent will fail.
+ ->lookup("..") is *not* used as a default as it can leave ".." entries
+ in the dcache which are too messy to work with.
+
+ get_name (optional)
+ When given a parent dentry and a child dentry, this should find a name
+ in the directory identified by the parent dentry, which leads to the
+ object identified by the child dentry. If no get_name function is
+ supplied, a default implementation is provided which uses vfs_readdir
+ to find potential names, and matches inode numbers to find the correct
+ match.
+
+
+A filehandle fragment consists of an array of 1 or more 4byte words,
+together with a one byte "type".
+The decode_fh routine should not depend on the stated size that is
+passed to it. This size may be larger than the original filehandle
+generated by encode_fh, in which case it will have been padded with
+nuls. Rather, the encode_fh routine should choose a "type" which
+indicates the decode_fh how much of the filehandle is valid, and how
+it should be interpreted.
diff --git a/Documentation/filesystems/overlayfs.txt b/Documentation/filesystems/overlayfs.txt
index 1da2f16..845d689 100644
--- a/Documentation/filesystems/overlayfs.txt
+++ b/Documentation/filesystems/overlayfs.txt
@@ -302,7 +302,7 @@
Using an upper layer path and/or a workdir path that are already used by
another overlay mount is not allowed and may fail with EBUSY. Using
-partially overlapping paths is not allowed but will not fail with EBUSY.
+partially overlapping paths is not allowed and may fail with EBUSY.
If files are accessed from two overlayfs mounts which share or overlap the
upper layer and/or workdir path the behavior of the overlay is undefined,
though it will not result in a crash or deadlock.
diff --git a/Documentation/filesystems/porting b/Documentation/filesystems/porting
deleted file mode 100644
index 6b7a41c..0000000
--- a/Documentation/filesystems/porting
+++ /dev/null
@@ -1,686 +0,0 @@
-Changes since 2.5.0:
-
----
-[recommended]
-
-New helpers: sb_bread(), sb_getblk(), sb_find_get_block(), set_bh(),
- sb_set_blocksize() and sb_min_blocksize().
-
-Use them.
-
-(sb_find_get_block() replaces 2.4's get_hash_table())
-
----
-[recommended]
-
-New methods: ->alloc_inode() and ->destroy_inode().
-
-Remove inode->u.foo_inode_i
-Declare
- struct foo_inode_info {
- /* fs-private stuff */
- struct inode vfs_inode;
- };
- static inline struct foo_inode_info *FOO_I(struct inode *inode)
- {
- return list_entry(inode, struct foo_inode_info, vfs_inode);
- }
-
-Use FOO_I(inode) instead of &inode->u.foo_inode_i;
-
-Add foo_alloc_inode() and foo_destroy_inode() - the former should allocate
-foo_inode_info and return the address of ->vfs_inode, the latter should free
-FOO_I(inode) (see in-tree filesystems for examples).
-
-Make them ->alloc_inode and ->destroy_inode in your super_operations.
-
-Keep in mind that now you need explicit initialization of private data
-typically between calling iget_locked() and unlocking the inode.
-
-At some point that will become mandatory.
-
----
-[mandatory]
-
-Change of file_system_type method (->read_super to ->get_sb)
-
-->read_super() is no more. Ditto for DECLARE_FSTYPE and DECLARE_FSTYPE_DEV.
-
-Turn your foo_read_super() into a function that would return 0 in case of
-success and negative number in case of error (-EINVAL unless you have more
-informative error value to report). Call it foo_fill_super(). Now declare
-
-int foo_get_sb(struct file_system_type *fs_type,
- int flags, const char *dev_name, void *data, struct vfsmount *mnt)
-{
- return get_sb_bdev(fs_type, flags, dev_name, data, foo_fill_super,
- mnt);
-}
-
-(or similar with s/bdev/nodev/ or s/bdev/single/, depending on the kind of
-filesystem).
-
-Replace DECLARE_FSTYPE... with explicit initializer and have ->get_sb set as
-foo_get_sb.
-
----
-[mandatory]
-
-Locking change: ->s_vfs_rename_sem is taken only by cross-directory renames.
-Most likely there is no need to change anything, but if you relied on
-global exclusion between renames for some internal purpose - you need to
-change your internal locking. Otherwise exclusion warranties remain the
-same (i.e. parents and victim are locked, etc.).
-
----
-[informational]
-
-Now we have the exclusion between ->lookup() and directory removal (by
-->rmdir() and ->rename()). If you used to need that exclusion and do
-it by internal locking (most of filesystems couldn't care less) - you
-can relax your locking.
-
----
-[mandatory]
-
-->lookup(), ->truncate(), ->create(), ->unlink(), ->mknod(), ->mkdir(),
-->rmdir(), ->link(), ->lseek(), ->symlink(), ->rename()
-and ->readdir() are called without BKL now. Grab it on entry, drop upon return
-- that will guarantee the same locking you used to have. If your method or its
-parts do not need BKL - better yet, now you can shift lock_kernel() and
-unlock_kernel() so that they would protect exactly what needs to be
-protected.
-
----
-[mandatory]
-
-BKL is also moved from around sb operations. BKL should have been shifted into
-individual fs sb_op functions. If you don't need it, remove it.
-
----
-[informational]
-
-check for ->link() target not being a directory is done by callers. Feel
-free to drop it...
-
----
-[informational]
-
-->link() callers hold ->i_mutex on the object we are linking to. Some of your
-problems might be over...
-
----
-[mandatory]
-
-new file_system_type method - kill_sb(superblock). If you are converting
-an existing filesystem, set it according to ->fs_flags:
- FS_REQUIRES_DEV - kill_block_super
- FS_LITTER - kill_litter_super
- neither - kill_anon_super
-FS_LITTER is gone - just remove it from fs_flags.
-
----
-[mandatory]
-
- FS_SINGLE is gone (actually, that had happened back when ->get_sb()
-went in - and hadn't been documented ;-/). Just remove it from fs_flags
-(and see ->get_sb() entry for other actions).
-
----
-[mandatory]
-
-->setattr() is called without BKL now. Caller _always_ holds ->i_mutex, so
-watch for ->i_mutex-grabbing code that might be used by your ->setattr().
-Callers of notify_change() need ->i_mutex now.
-
----
-[recommended]
-
-New super_block field "struct export_operations *s_export_op" for
-explicit support for exporting, e.g. via NFS. The structure is fully
-documented at its declaration in include/linux/fs.h, and in
-Documentation/filesystems/nfs/Exporting.
-
-Briefly it allows for the definition of decode_fh and encode_fh operations
-to encode and decode filehandles, and allows the filesystem to use
-a standard helper function for decode_fh, and provide file-system specific
-support for this helper, particularly get_parent.
-
-It is planned that this will be required for exporting once the code
-settles down a bit.
-
-[mandatory]
-
-s_export_op is now required for exporting a filesystem.
-isofs, ext2, ext3, resierfs, fat
-can be used as examples of very different filesystems.
-
----
-[mandatory]
-
-iget4() and the read_inode2 callback have been superseded by iget5_locked()
-which has the following prototype,
-
- struct inode *iget5_locked(struct super_block *sb, unsigned long ino,
- int (*test)(struct inode *, void *),
- int (*set)(struct inode *, void *),
- void *data);
-
-'test' is an additional function that can be used when the inode
-number is not sufficient to identify the actual file object. 'set'
-should be a non-blocking function that initializes those parts of a
-newly created inode to allow the test function to succeed. 'data' is
-passed as an opaque value to both test and set functions.
-
-When the inode has been created by iget5_locked(), it will be returned with the
-I_NEW flag set and will still be locked. The filesystem then needs to finalize
-the initialization. Once the inode is initialized it must be unlocked by
-calling unlock_new_inode().
-
-The filesystem is responsible for setting (and possibly testing) i_ino
-when appropriate. There is also a simpler iget_locked function that
-just takes the superblock and inode number as arguments and does the
-test and set for you.
-
-e.g.
- inode = iget_locked(sb, ino);
- if (inode->i_state & I_NEW) {
- err = read_inode_from_disk(inode);
- if (err < 0) {
- iget_failed(inode);
- return err;
- }
- unlock_new_inode(inode);
- }
-
-Note that if the process of setting up a new inode fails, then iget_failed()
-should be called on the inode to render it dead, and an appropriate error
-should be passed back to the caller.
-
----
-[recommended]
-
-->getattr() finally getting used. See instances in nfs, minix, etc.
-
----
-[mandatory]
-
-->revalidate() is gone. If your filesystem had it - provide ->getattr()
-and let it call whatever you had as ->revlidate() + (for symlinks that
-had ->revalidate()) add calls in ->follow_link()/->readlink().
-
----
-[mandatory]
-
-->d_parent changes are not protected by BKL anymore. Read access is safe
-if at least one of the following is true:
- * filesystem has no cross-directory rename()
- * we know that parent had been locked (e.g. we are looking at
-->d_parent of ->lookup() argument).
- * we are called from ->rename().
- * the child's ->d_lock is held
-Audit your code and add locking if needed. Notice that any place that is
-not protected by the conditions above is risky even in the old tree - you
-had been relying on BKL and that's prone to screwups. Old tree had quite
-a few holes of that kind - unprotected access to ->d_parent leading to
-anything from oops to silent memory corruption.
-
----
-[mandatory]
-
- FS_NOMOUNT is gone. If you use it - just set SB_NOUSER in flags
-(see rootfs for one kind of solution and bdev/socket/pipe for another).
-
----
-[recommended]
-
- Use bdev_read_only(bdev) instead of is_read_only(kdev). The latter
-is still alive, but only because of the mess in drivers/s390/block/dasd.c.
-As soon as it gets fixed is_read_only() will die.
-
----
-[mandatory]
-
-->permission() is called without BKL now. Grab it on entry, drop upon
-return - that will guarantee the same locking you used to have. If
-your method or its parts do not need BKL - better yet, now you can
-shift lock_kernel() and unlock_kernel() so that they would protect
-exactly what needs to be protected.
-
----
-[mandatory]
-
-->statfs() is now called without BKL held. BKL should have been
-shifted into individual fs sb_op functions where it's not clear that
-it's safe to remove it. If you don't need it, remove it.
-
----
-[mandatory]
-
- is_read_only() is gone; use bdev_read_only() instead.
-
----
-[mandatory]
-
- destroy_buffers() is gone; use invalidate_bdev().
-
----
-[mandatory]
-
- fsync_dev() is gone; use fsync_bdev(). NOTE: lvm breakage is
-deliberate; as soon as struct block_device * is propagated in a reasonable
-way by that code fixing will become trivial; until then nothing can be
-done.
-
-[mandatory]
-
- block truncatation on error exit from ->write_begin, and ->direct_IO
-moved from generic methods (block_write_begin, cont_write_begin,
-nobh_write_begin, blockdev_direct_IO*) to callers. Take a look at
-ext2_write_failed and callers for an example.
-
-[mandatory]
-
- ->truncate is gone. The whole truncate sequence needs to be
-implemented in ->setattr, which is now mandatory for filesystems
-implementing on-disk size changes. Start with a copy of the old inode_setattr
-and vmtruncate, and the reorder the vmtruncate + foofs_vmtruncate sequence to
-be in order of zeroing blocks using block_truncate_page or similar helpers,
-size update and on finally on-disk truncation which should not fail.
-setattr_prepare (which used to be inode_change_ok) now includes the size checks
-for ATTR_SIZE and must be called in the beginning of ->setattr unconditionally.
-
-[mandatory]
-
- ->clear_inode() and ->delete_inode() are gone; ->evict_inode() should
-be used instead. It gets called whenever the inode is evicted, whether it has
-remaining links or not. Caller does *not* evict the pagecache or inode-associated
-metadata buffers; the method has to use truncate_inode_pages_final() to get rid
-of those. Caller makes sure async writeback cannot be running for the inode while
-(or after) ->evict_inode() is called.
-
- ->drop_inode() returns int now; it's called on final iput() with
-inode->i_lock held and it returns true if filesystems wants the inode to be
-dropped. As before, generic_drop_inode() is still the default and it's been
-updated appropriately. generic_delete_inode() is also alive and it consists
-simply of return 1. Note that all actual eviction work is done by caller after
-->drop_inode() returns.
-
- As before, clear_inode() must be called exactly once on each call of
-->evict_inode() (as it used to be for each call of ->delete_inode()). Unlike
-before, if you are using inode-associated metadata buffers (i.e.
-mark_buffer_dirty_inode()), it's your responsibility to call
-invalidate_inode_buffers() before clear_inode().
-
- NOTE: checking i_nlink in the beginning of ->write_inode() and bailing out
-if it's zero is not *and* *never* *had* *been* enough. Final unlink() and iput()
-may happen while the inode is in the middle of ->write_inode(); e.g. if you blindly
-free the on-disk inode, you may end up doing that while ->write_inode() is writing
-to it.
-
----
-[mandatory]
-
- .d_delete() now only advises the dcache as to whether or not to cache
-unreferenced dentries, and is now only called when the dentry refcount goes to
-0. Even on 0 refcount transition, it must be able to tolerate being called 0,
-1, or more times (eg. constant, idempotent).
-
----
-[mandatory]
-
- .d_compare() calling convention and locking rules are significantly
-changed. Read updated documentation in Documentation/filesystems/vfs.rst (and
-look at examples of other filesystems) for guidance.
-
----
-[mandatory]
-
- .d_hash() calling convention and locking rules are significantly
-changed. Read updated documentation in Documentation/filesystems/vfs.rst (and
-look at examples of other filesystems) for guidance.
-
----
-[mandatory]
- dcache_lock is gone, replaced by fine grained locks. See fs/dcache.c
-for details of what locks to replace dcache_lock with in order to protect
-particular things. Most of the time, a filesystem only needs ->d_lock, which
-protects *all* the dcache state of a given dentry.
-
---
-[mandatory]
-
- Filesystems must RCU-free their inodes, if they can have been accessed
-via rcu-walk path walk (basically, if the file can have had a path name in the
-vfs namespace).
-
- Even though i_dentry and i_rcu share storage in a union, we will
-initialize the former in inode_init_always(), so just leave it alone in
-the callback. It used to be necessary to clean it there, but not anymore
-(starting at 3.2).
-
---
-[recommended]
- vfs now tries to do path walking in "rcu-walk mode", which avoids
-atomic operations and scalability hazards on dentries and inodes (see
-Documentation/filesystems/path-lookup.txt). d_hash and d_compare changes
-(above) are examples of the changes required to support this. For more complex
-filesystem callbacks, the vfs drops out of rcu-walk mode before the fs call, so
-no changes are required to the filesystem. However, this is costly and loses
-the benefits of rcu-walk mode. We will begin to add filesystem callbacks that
-are rcu-walk aware, shown below. Filesystems should take advantage of this
-where possible.
-
---
-[mandatory]
- d_revalidate is a callback that is made on every path element (if
-the filesystem provides it), which requires dropping out of rcu-walk mode. This
-may now be called in rcu-walk mode (nd->flags & LOOKUP_RCU). -ECHILD should be
-returned if the filesystem cannot handle rcu-walk. See
-Documentation/filesystems/vfs.rst for more details.
-
- permission is an inode permission check that is called on many or all
-directory inodes on the way down a path walk (to check for exec permission). It
-must now be rcu-walk aware (mask & MAY_NOT_BLOCK). See
-Documentation/filesystems/vfs.rst for more details.
-
---
-[mandatory]
- In ->fallocate() you must check the mode option passed in. If your
-filesystem does not support hole punching (deallocating space in the middle of a
-file) you must return -EOPNOTSUPP if FALLOC_FL_PUNCH_HOLE is set in mode.
-Currently you can only have FALLOC_FL_PUNCH_HOLE with FALLOC_FL_KEEP_SIZE set,
-so the i_size should not change when hole punching, even when puching the end of
-a file off.
-
---
-[mandatory]
- ->get_sb() is gone. Switch to use of ->mount(). Typically it's just
-a matter of switching from calling get_sb_... to mount_... and changing the
-function type. If you were doing it manually, just switch from setting ->mnt_root
-to some pointer to returning that pointer. On errors return ERR_PTR(...).
-
---
-[mandatory]
- ->permission() and generic_permission()have lost flags
-argument; instead of passing IPERM_FLAG_RCU we add MAY_NOT_BLOCK into mask.
- generic_permission() has also lost the check_acl argument; ACL checking
-has been taken to VFS and filesystems need to provide a non-NULL ->i_op->get_acl
-to read an ACL from disk.
-
---
-[mandatory]
- If you implement your own ->llseek() you must handle SEEK_HOLE and
-SEEK_DATA. You can hanle this by returning -EINVAL, but it would be nicer to
-support it in some way. The generic handler assumes that the entire file is
-data and there is a virtual hole at the end of the file. So if the provided
-offset is less than i_size and SEEK_DATA is specified, return the same offset.
-If the above is true for the offset and you are given SEEK_HOLE, return the end
-of the file. If the offset is i_size or greater return -ENXIO in either case.
-
-[mandatory]
- If you have your own ->fsync() you must make sure to call
-filemap_write_and_wait_range() so that all dirty pages are synced out properly.
-You must also keep in mind that ->fsync() is not called with i_mutex held
-anymore, so if you require i_mutex locking you must make sure to take it and
-release it yourself.
-
---
-[mandatory]
- d_alloc_root() is gone, along with a lot of bugs caused by code
-misusing it. Replacement: d_make_root(inode). On success d_make_root(inode)
-allocates and returns a new dentry instantiated with the passed in inode.
-On failure NULL is returned and the passed in inode is dropped so the reference
-to inode is consumed in all cases and failure handling need not do any cleanup
-for the inode. If d_make_root(inode) is passed a NULL inode it returns NULL
-and also requires no further error handling. Typical usage is:
-
- inode = foofs_new_inode(....);
- s->s_root = d_make_root(inode);
- if (!s->s_root)
- /* Nothing needed for the inode cleanup */
- return -ENOMEM;
- ...
-
---
-[mandatory]
- The witch is dead! Well, 2/3 of it, anyway. ->d_revalidate() and
-->lookup() do *not* take struct nameidata anymore; just the flags.
---
-[mandatory]
- ->create() doesn't take struct nameidata *; unlike the previous
-two, it gets "is it an O_EXCL or equivalent?" boolean argument. Note that
-local filesystems can ignore tha argument - they are guaranteed that the
-object doesn't exist. It's remote/distributed ones that might care...
---
-[mandatory]
- FS_REVAL_DOT is gone; if you used to have it, add ->d_weak_revalidate()
-in your dentry operations instead.
---
-[mandatory]
- vfs_readdir() is gone; switch to iterate_dir() instead
---
-[mandatory]
- ->readdir() is gone now; switch to ->iterate()
-[mandatory]
- vfs_follow_link has been removed. Filesystems must use nd_set_link
- from ->follow_link for normal symlinks, or nd_jump_link for magic
- /proc/<pid> style links.
---
-[mandatory]
- iget5_locked()/ilookup5()/ilookup5_nowait() test() callback used to be
- called with both ->i_lock and inode_hash_lock held; the former is *not*
- taken anymore, so verify that your callbacks do not rely on it (none
- of the in-tree instances did). inode_hash_lock is still held,
- of course, so they are still serialized wrt removal from inode hash,
- as well as wrt set() callback of iget5_locked().
---
-[mandatory]
- d_materialise_unique() is gone; d_splice_alias() does everything you
- need now. Remember that they have opposite orders of arguments ;-/
---
-[mandatory]
- f_dentry is gone; use f_path.dentry, or, better yet, see if you can avoid
- it entirely.
---
-[mandatory]
- never call ->read() and ->write() directly; use __vfs_{read,write} or
- wrappers; instead of checking for ->write or ->read being NULL, look for
- FMODE_CAN_{WRITE,READ} in file->f_mode.
---
-[mandatory]
- do _not_ use new_sync_{read,write} for ->read/->write; leave it NULL
- instead.
---
-[mandatory]
- ->aio_read/->aio_write are gone. Use ->read_iter/->write_iter.
----
-[recommended]
- for embedded ("fast") symlinks just set inode->i_link to wherever the
- symlink body is and use simple_follow_link() as ->follow_link().
---
-[mandatory]
- calling conventions for ->follow_link() have changed. Instead of returning
- cookie and using nd_set_link() to store the body to traverse, we return
- the body to traverse and store the cookie using explicit void ** argument.
- nameidata isn't passed at all - nd_jump_link() doesn't need it and
- nd_[gs]et_link() is gone.
---
-[mandatory]
- calling conventions for ->put_link() have changed. It gets inode instead of
- dentry, it does not get nameidata at all and it gets called only when cookie
- is non-NULL. Note that link body isn't available anymore, so if you need it,
- store it as cookie.
---
-[mandatory]
- any symlink that might use page_follow_link_light/page_put_link() must
- have inode_nohighmem(inode) called before anything might start playing with
- its pagecache. No highmem pages should end up in the pagecache of such
- symlinks. That includes any preseeding that might be done during symlink
- creation. __page_symlink() will honour the mapping gfp flags, so once
- you've done inode_nohighmem() it's safe to use, but if you allocate and
- insert the page manually, make sure to use the right gfp flags.
---
-[mandatory]
- ->follow_link() is replaced with ->get_link(); same API, except that
- * ->get_link() gets inode as a separate argument
- * ->get_link() may be called in RCU mode - in that case NULL
- dentry is passed
---
-[mandatory]
- ->get_link() gets struct delayed_call *done now, and should do
- set_delayed_call() where it used to set *cookie.
- ->put_link() is gone - just give the destructor to set_delayed_call()
- in ->get_link().
---
-[mandatory]
- ->getxattr() and xattr_handler.get() get dentry and inode passed separately.
- dentry might be yet to be attached to inode, so do _not_ use its ->d_inode
- in the instances. Rationale: !@#!@# security_d_instantiate() needs to be
- called before we attach dentry to inode.
---
-[mandatory]
- symlinks are no longer the only inodes that do *not* have i_bdev/i_cdev/
- i_pipe/i_link union zeroed out at inode eviction. As the result, you can't
- assume that non-NULL value in ->i_nlink at ->destroy_inode() implies that
- it's a symlink. Checking ->i_mode is really needed now. In-tree we had
- to fix shmem_destroy_callback() that used to take that kind of shortcut;
- watch out, since that shortcut is no longer valid.
---
-[mandatory]
- ->i_mutex is replaced with ->i_rwsem now. inode_lock() et.al. work as
- they used to - they just take it exclusive. However, ->lookup() may be
- called with parent locked shared. Its instances must not
- * use d_instantiate) and d_rehash() separately - use d_add() or
- d_splice_alias() instead.
- * use d_rehash() alone - call d_add(new_dentry, NULL) instead.
- * in the unlikely case when (read-only) access to filesystem
- data structures needs exclusion for some reason, arrange it
- yourself. None of the in-tree filesystems needed that.
- * rely on ->d_parent and ->d_name not changing after dentry has
- been fed to d_add() or d_splice_alias(). Again, none of the
- in-tree instances relied upon that.
- We are guaranteed that lookups of the same name in the same directory
- will not happen in parallel ("same" in the sense of your ->d_compare()).
- Lookups on different names in the same directory can and do happen in
- parallel now.
---
-[recommended]
- ->iterate_shared() is added; it's a parallel variant of ->iterate().
- Exclusion on struct file level is still provided (as well as that
- between it and lseek on the same struct file), but if your directory
- has been opened several times, you can get these called in parallel.
- Exclusion between that method and all directory-modifying ones is
- still provided, of course.
-
- Often enough ->iterate() can serve as ->iterate_shared() without any
- changes - it is a read-only operation, after all. If you have any
- per-inode or per-dentry in-core data structures modified by ->iterate(),
- you might need something to serialize the access to them. If you
- do dcache pre-seeding, you'll need to switch to d_alloc_parallel() for
- that; look for in-tree examples.
-
- Old method is only used if the new one is absent; eventually it will
- be removed. Switch while you still can; the old one won't stay.
---
-[mandatory]
- ->atomic_open() calls without O_CREAT may happen in parallel.
---
-[mandatory]
- ->setxattr() and xattr_handler.set() get dentry and inode passed separately.
- dentry might be yet to be attached to inode, so do _not_ use its ->d_inode
- in the instances. Rationale: !@#!@# security_d_instantiate() needs to be
- called before we attach dentry to inode and !@#!@##!@$!$#!@#$!@$!@$ smack
- ->d_instantiate() uses not just ->getxattr() but ->setxattr() as well.
---
-[mandatory]
- ->d_compare() doesn't get parent as a separate argument anymore. If you
- used it for finding the struct super_block involved, dentry->d_sb will
- work just as well; if it's something more complicated, use dentry->d_parent.
- Just be careful not to assume that fetching it more than once will yield
- the same value - in RCU mode it could change under you.
---
-[mandatory]
- ->rename() has an added flags argument. Any flags not handled by the
- filesystem should result in EINVAL being returned.
---
-[recommended]
- ->readlink is optional for symlinks. Don't set, unless filesystem needs
- to fake something for readlink(2).
---
-[mandatory]
- ->getattr() is now passed a struct path rather than a vfsmount and
- dentry separately, and it now has request_mask and query_flags arguments
- to specify the fields and sync type requested by statx. Filesystems not
- supporting any statx-specific features may ignore the new arguments.
---
-[mandatory]
- ->atomic_open() calling conventions have changed. Gone is int *opened,
- along with FILE_OPENED/FILE_CREATED. In place of those we have
- FMODE_OPENED/FMODE_CREATED, set in file->f_mode. Additionally, return
- value for 'called finish_no_open(), open it yourself' case has become
- 0, not 1. Since finish_no_open() itself is returning 0 now, that part
- does not need any changes in ->atomic_open() instances.
---
-[mandatory]
- alloc_file() has become static now; two wrappers are to be used instead.
- alloc_file_pseudo(inode, vfsmount, name, flags, ops) is for the cases
- when dentry needs to be created; that's the majority of old alloc_file()
- users. Calling conventions: on success a reference to new struct file
- is returned and callers reference to inode is subsumed by that. On
- failure, ERR_PTR() is returned and no caller's references are affected,
- so the caller needs to drop the inode reference it held.
- alloc_file_clone(file, flags, ops) does not affect any caller's references.
- On success you get a new struct file sharing the mount/dentry with the
- original, on failure - ERR_PTR().
---
-[mandatory]
- ->clone_file_range() and ->dedupe_file_range have been replaced with
- ->remap_file_range(). See Documentation/filesystems/vfs.rst for more
- information.
---
-[recommended]
- ->lookup() instances doing an equivalent of
- if (IS_ERR(inode))
- return ERR_CAST(inode);
- return d_splice_alias(inode, dentry);
- don't need to bother with the check - d_splice_alias() will do the
- right thing when given ERR_PTR(...) as inode. Moreover, passing NULL
- inode to d_splice_alias() will also do the right thing (equivalent of
- d_add(dentry, NULL); return NULL;), so that kind of special cases
- also doesn't need a separate treatment.
---
-[strongly recommended]
- take the RCU-delayed parts of ->destroy_inode() into a new method -
- ->free_inode(). If ->destroy_inode() becomes empty - all the better,
- just get rid of it. Synchronous work (e.g. the stuff that can't
- be done from an RCU callback, or any WARN_ON() where we want the
- stack trace) *might* be movable to ->evict_inode(); however,
- that goes only for the things that are not needed to balance something
- done by ->alloc_inode(). IOW, if it's cleaning up the stuff that
- might have accumulated over the life of in-core inode, ->evict_inode()
- might be a fit.
-
- Rules for inode destruction:
- * if ->destroy_inode() is non-NULL, it gets called
- * if ->free_inode() is non-NULL, it gets scheduled by call_rcu()
- * combination of NULL ->destroy_inode and NULL ->free_inode is
- treated as NULL/free_inode_nonrcu, to preserve the compatibility.
-
- Note that the callback (be it via ->free_inode() or explicit call_rcu()
- in ->destroy_inode()) is *NOT* ordered wrt superblock destruction;
- as the matter of fact, the superblock and all associated structures
- might be already gone. The filesystem driver is guaranteed to be still
- there, but that's it. Freeing memory in the callback is fine; doing
- more than that is possible, but requires a lot of care and is best
- avoided.
---
-[mandatory]
- DCACHE_RCUACCESS is gone; having an RCU delay on dentry freeing is the
- default. DCACHE_NORCU opts out, and only d_alloc_pseudo() has any
- business doing so.
---
-[mandatory]
- d_alloc_pseudo() is internal-only; uses outside of alloc_file_pseudo() are
- very suspect (and won't work in modules). Such uses are very likely to
- be misspelled d_alloc_anon().
diff --git a/Documentation/filesystems/porting.rst b/Documentation/filesystems/porting.rst
new file mode 100644
index 0000000..f185060
--- /dev/null
+++ b/Documentation/filesystems/porting.rst
@@ -0,0 +1,852 @@
+====================
+Changes since 2.5.0:
+====================
+
+---
+
+**recommended**
+
+New helpers: sb_bread(), sb_getblk(), sb_find_get_block(), set_bh(),
+sb_set_blocksize() and sb_min_blocksize().
+
+Use them.
+
+(sb_find_get_block() replaces 2.4's get_hash_table())
+
+---
+
+**recommended**
+
+New methods: ->alloc_inode() and ->destroy_inode().
+
+Remove inode->u.foo_inode_i
+
+Declare::
+
+ struct foo_inode_info {
+ /* fs-private stuff */
+ struct inode vfs_inode;
+ };
+ static inline struct foo_inode_info *FOO_I(struct inode *inode)
+ {
+ return list_entry(inode, struct foo_inode_info, vfs_inode);
+ }
+
+Use FOO_I(inode) instead of &inode->u.foo_inode_i;
+
+Add foo_alloc_inode() and foo_destroy_inode() - the former should allocate
+foo_inode_info and return the address of ->vfs_inode, the latter should free
+FOO_I(inode) (see in-tree filesystems for examples).
+
+Make them ->alloc_inode and ->destroy_inode in your super_operations.
+
+Keep in mind that now you need explicit initialization of private data
+typically between calling iget_locked() and unlocking the inode.
+
+At some point that will become mandatory.
+
+---
+
+**mandatory**
+
+Change of file_system_type method (->read_super to ->get_sb)
+
+->read_super() is no more. Ditto for DECLARE_FSTYPE and DECLARE_FSTYPE_DEV.
+
+Turn your foo_read_super() into a function that would return 0 in case of
+success and negative number in case of error (-EINVAL unless you have more
+informative error value to report). Call it foo_fill_super(). Now declare::
+
+ int foo_get_sb(struct file_system_type *fs_type,
+ int flags, const char *dev_name, void *data, struct vfsmount *mnt)
+ {
+ return get_sb_bdev(fs_type, flags, dev_name, data, foo_fill_super,
+ mnt);
+ }
+
+(or similar with s/bdev/nodev/ or s/bdev/single/, depending on the kind of
+filesystem).
+
+Replace DECLARE_FSTYPE... with explicit initializer and have ->get_sb set as
+foo_get_sb.
+
+---
+
+**mandatory**
+
+Locking change: ->s_vfs_rename_sem is taken only by cross-directory renames.
+Most likely there is no need to change anything, but if you relied on
+global exclusion between renames for some internal purpose - you need to
+change your internal locking. Otherwise exclusion warranties remain the
+same (i.e. parents and victim are locked, etc.).
+
+---
+
+**informational**
+
+Now we have the exclusion between ->lookup() and directory removal (by
+->rmdir() and ->rename()). If you used to need that exclusion and do
+it by internal locking (most of filesystems couldn't care less) - you
+can relax your locking.
+
+---
+
+**mandatory**
+
+->lookup(), ->truncate(), ->create(), ->unlink(), ->mknod(), ->mkdir(),
+->rmdir(), ->link(), ->lseek(), ->symlink(), ->rename()
+and ->readdir() are called without BKL now. Grab it on entry, drop upon return
+- that will guarantee the same locking you used to have. If your method or its
+parts do not need BKL - better yet, now you can shift lock_kernel() and
+unlock_kernel() so that they would protect exactly what needs to be
+protected.
+
+---
+
+**mandatory**
+
+BKL is also moved from around sb operations. BKL should have been shifted into
+individual fs sb_op functions. If you don't need it, remove it.
+
+---
+
+**informational**
+
+check for ->link() target not being a directory is done by callers. Feel
+free to drop it...
+
+---
+
+**informational**
+
+->link() callers hold ->i_mutex on the object we are linking to. Some of your
+problems might be over...
+
+---
+
+**mandatory**
+
+new file_system_type method - kill_sb(superblock). If you are converting
+an existing filesystem, set it according to ->fs_flags::
+
+ FS_REQUIRES_DEV - kill_block_super
+ FS_LITTER - kill_litter_super
+ neither - kill_anon_super
+
+FS_LITTER is gone - just remove it from fs_flags.
+
+---
+
+**mandatory**
+
+FS_SINGLE is gone (actually, that had happened back when ->get_sb()
+went in - and hadn't been documented ;-/). Just remove it from fs_flags
+(and see ->get_sb() entry for other actions).
+
+---
+
+**mandatory**
+
+->setattr() is called without BKL now. Caller _always_ holds ->i_mutex, so
+watch for ->i_mutex-grabbing code that might be used by your ->setattr().
+Callers of notify_change() need ->i_mutex now.
+
+---
+
+**recommended**
+
+New super_block field ``struct export_operations *s_export_op`` for
+explicit support for exporting, e.g. via NFS. The structure is fully
+documented at its declaration in include/linux/fs.h, and in
+Documentation/filesystems/nfs/exporting.rst.
+
+Briefly it allows for the definition of decode_fh and encode_fh operations
+to encode and decode filehandles, and allows the filesystem to use
+a standard helper function for decode_fh, and provide file-system specific
+support for this helper, particularly get_parent.
+
+It is planned that this will be required for exporting once the code
+settles down a bit.
+
+**mandatory**
+
+s_export_op is now required for exporting a filesystem.
+isofs, ext2, ext3, resierfs, fat
+can be used as examples of very different filesystems.
+
+---
+
+**mandatory**
+
+iget4() and the read_inode2 callback have been superseded by iget5_locked()
+which has the following prototype::
+
+ struct inode *iget5_locked(struct super_block *sb, unsigned long ino,
+ int (*test)(struct inode *, void *),
+ int (*set)(struct inode *, void *),
+ void *data);
+
+'test' is an additional function that can be used when the inode
+number is not sufficient to identify the actual file object. 'set'
+should be a non-blocking function that initializes those parts of a
+newly created inode to allow the test function to succeed. 'data' is
+passed as an opaque value to both test and set functions.
+
+When the inode has been created by iget5_locked(), it will be returned with the
+I_NEW flag set and will still be locked. The filesystem then needs to finalize
+the initialization. Once the inode is initialized it must be unlocked by
+calling unlock_new_inode().
+
+The filesystem is responsible for setting (and possibly testing) i_ino
+when appropriate. There is also a simpler iget_locked function that
+just takes the superblock and inode number as arguments and does the
+test and set for you.
+
+e.g.::
+
+ inode = iget_locked(sb, ino);
+ if (inode->i_state & I_NEW) {
+ err = read_inode_from_disk(inode);
+ if (err < 0) {
+ iget_failed(inode);
+ return err;
+ }
+ unlock_new_inode(inode);
+ }
+
+Note that if the process of setting up a new inode fails, then iget_failed()
+should be called on the inode to render it dead, and an appropriate error
+should be passed back to the caller.
+
+---
+
+**recommended**
+
+->getattr() finally getting used. See instances in nfs, minix, etc.
+
+---
+
+**mandatory**
+
+->revalidate() is gone. If your filesystem had it - provide ->getattr()
+and let it call whatever you had as ->revlidate() + (for symlinks that
+had ->revalidate()) add calls in ->follow_link()/->readlink().
+
+---
+
+**mandatory**
+
+->d_parent changes are not protected by BKL anymore. Read access is safe
+if at least one of the following is true:
+
+ * filesystem has no cross-directory rename()
+ * we know that parent had been locked (e.g. we are looking at
+ ->d_parent of ->lookup() argument).
+ * we are called from ->rename().
+ * the child's ->d_lock is held
+
+Audit your code and add locking if needed. Notice that any place that is
+not protected by the conditions above is risky even in the old tree - you
+had been relying on BKL and that's prone to screwups. Old tree had quite
+a few holes of that kind - unprotected access to ->d_parent leading to
+anything from oops to silent memory corruption.
+
+---
+
+**mandatory**
+
+FS_NOMOUNT is gone. If you use it - just set SB_NOUSER in flags
+(see rootfs for one kind of solution and bdev/socket/pipe for another).
+
+---
+
+**recommended**
+
+Use bdev_read_only(bdev) instead of is_read_only(kdev). The latter
+is still alive, but only because of the mess in drivers/s390/block/dasd.c.
+As soon as it gets fixed is_read_only() will die.
+
+---
+
+**mandatory**
+
+->permission() is called without BKL now. Grab it on entry, drop upon
+return - that will guarantee the same locking you used to have. If
+your method or its parts do not need BKL - better yet, now you can
+shift lock_kernel() and unlock_kernel() so that they would protect
+exactly what needs to be protected.
+
+---
+
+**mandatory**
+
+->statfs() is now called without BKL held. BKL should have been
+shifted into individual fs sb_op functions where it's not clear that
+it's safe to remove it. If you don't need it, remove it.
+
+---
+
+**mandatory**
+
+is_read_only() is gone; use bdev_read_only() instead.
+
+---
+
+**mandatory**
+
+destroy_buffers() is gone; use invalidate_bdev().
+
+---
+
+**mandatory**
+
+fsync_dev() is gone; use fsync_bdev(). NOTE: lvm breakage is
+deliberate; as soon as struct block_device * is propagated in a reasonable
+way by that code fixing will become trivial; until then nothing can be
+done.
+
+**mandatory**
+
+block truncatation on error exit from ->write_begin, and ->direct_IO
+moved from generic methods (block_write_begin, cont_write_begin,
+nobh_write_begin, blockdev_direct_IO*) to callers. Take a look at
+ext2_write_failed and callers for an example.
+
+**mandatory**
+
+->truncate is gone. The whole truncate sequence needs to be
+implemented in ->setattr, which is now mandatory for filesystems
+implementing on-disk size changes. Start with a copy of the old inode_setattr
+and vmtruncate, and the reorder the vmtruncate + foofs_vmtruncate sequence to
+be in order of zeroing blocks using block_truncate_page or similar helpers,
+size update and on finally on-disk truncation which should not fail.
+setattr_prepare (which used to be inode_change_ok) now includes the size checks
+for ATTR_SIZE and must be called in the beginning of ->setattr unconditionally.
+
+**mandatory**
+
+->clear_inode() and ->delete_inode() are gone; ->evict_inode() should
+be used instead. It gets called whenever the inode is evicted, whether it has
+remaining links or not. Caller does *not* evict the pagecache or inode-associated
+metadata buffers; the method has to use truncate_inode_pages_final() to get rid
+of those. Caller makes sure async writeback cannot be running for the inode while
+(or after) ->evict_inode() is called.
+
+->drop_inode() returns int now; it's called on final iput() with
+inode->i_lock held and it returns true if filesystems wants the inode to be
+dropped. As before, generic_drop_inode() is still the default and it's been
+updated appropriately. generic_delete_inode() is also alive and it consists
+simply of return 1. Note that all actual eviction work is done by caller after
+->drop_inode() returns.
+
+As before, clear_inode() must be called exactly once on each call of
+->evict_inode() (as it used to be for each call of ->delete_inode()). Unlike
+before, if you are using inode-associated metadata buffers (i.e.
+mark_buffer_dirty_inode()), it's your responsibility to call
+invalidate_inode_buffers() before clear_inode().
+
+NOTE: checking i_nlink in the beginning of ->write_inode() and bailing out
+if it's zero is not *and* *never* *had* *been* enough. Final unlink() and iput()
+may happen while the inode is in the middle of ->write_inode(); e.g. if you blindly
+free the on-disk inode, you may end up doing that while ->write_inode() is writing
+to it.
+
+---
+
+**mandatory**
+
+.d_delete() now only advises the dcache as to whether or not to cache
+unreferenced dentries, and is now only called when the dentry refcount goes to
+0. Even on 0 refcount transition, it must be able to tolerate being called 0,
+1, or more times (eg. constant, idempotent).
+
+---
+
+**mandatory**
+
+.d_compare() calling convention and locking rules are significantly
+changed. Read updated documentation in Documentation/filesystems/vfs.rst (and
+look at examples of other filesystems) for guidance.
+
+---
+
+**mandatory**
+
+.d_hash() calling convention and locking rules are significantly
+changed. Read updated documentation in Documentation/filesystems/vfs.rst (and
+look at examples of other filesystems) for guidance.
+
+---
+
+**mandatory**
+
+dcache_lock is gone, replaced by fine grained locks. See fs/dcache.c
+for details of what locks to replace dcache_lock with in order to protect
+particular things. Most of the time, a filesystem only needs ->d_lock, which
+protects *all* the dcache state of a given dentry.
+
+---
+
+**mandatory**
+
+Filesystems must RCU-free their inodes, if they can have been accessed
+via rcu-walk path walk (basically, if the file can have had a path name in the
+vfs namespace).
+
+Even though i_dentry and i_rcu share storage in a union, we will
+initialize the former in inode_init_always(), so just leave it alone in
+the callback. It used to be necessary to clean it there, but not anymore
+(starting at 3.2).
+
+---
+
+**recommended**
+
+vfs now tries to do path walking in "rcu-walk mode", which avoids
+atomic operations and scalability hazards on dentries and inodes (see
+Documentation/filesystems/path-lookup.txt). d_hash and d_compare changes
+(above) are examples of the changes required to support this. For more complex
+filesystem callbacks, the vfs drops out of rcu-walk mode before the fs call, so
+no changes are required to the filesystem. However, this is costly and loses
+the benefits of rcu-walk mode. We will begin to add filesystem callbacks that
+are rcu-walk aware, shown below. Filesystems should take advantage of this
+where possible.
+
+---
+
+**mandatory**
+
+d_revalidate is a callback that is made on every path element (if
+the filesystem provides it), which requires dropping out of rcu-walk mode. This
+may now be called in rcu-walk mode (nd->flags & LOOKUP_RCU). -ECHILD should be
+returned if the filesystem cannot handle rcu-walk. See
+Documentation/filesystems/vfs.rst for more details.
+
+permission is an inode permission check that is called on many or all
+directory inodes on the way down a path walk (to check for exec permission). It
+must now be rcu-walk aware (mask & MAY_NOT_BLOCK). See
+Documentation/filesystems/vfs.rst for more details.
+
+---
+
+**mandatory**
+
+In ->fallocate() you must check the mode option passed in. If your
+filesystem does not support hole punching (deallocating space in the middle of a
+file) you must return -EOPNOTSUPP if FALLOC_FL_PUNCH_HOLE is set in mode.
+Currently you can only have FALLOC_FL_PUNCH_HOLE with FALLOC_FL_KEEP_SIZE set,
+so the i_size should not change when hole punching, even when puching the end of
+a file off.
+
+---
+
+**mandatory**
+
+->get_sb() is gone. Switch to use of ->mount(). Typically it's just
+a matter of switching from calling ``get_sb_``... to ``mount_``... and changing
+the function type. If you were doing it manually, just switch from setting
+->mnt_root to some pointer to returning that pointer. On errors return
+ERR_PTR(...).
+
+---
+
+**mandatory**
+
+->permission() and generic_permission()have lost flags
+argument; instead of passing IPERM_FLAG_RCU we add MAY_NOT_BLOCK into mask.
+
+generic_permission() has also lost the check_acl argument; ACL checking
+has been taken to VFS and filesystems need to provide a non-NULL ->i_op->get_acl
+to read an ACL from disk.
+
+---
+
+**mandatory**
+
+If you implement your own ->llseek() you must handle SEEK_HOLE and
+SEEK_DATA. You can hanle this by returning -EINVAL, but it would be nicer to
+support it in some way. The generic handler assumes that the entire file is
+data and there is a virtual hole at the end of the file. So if the provided
+offset is less than i_size and SEEK_DATA is specified, return the same offset.
+If the above is true for the offset and you are given SEEK_HOLE, return the end
+of the file. If the offset is i_size or greater return -ENXIO in either case.
+
+**mandatory**
+
+If you have your own ->fsync() you must make sure to call
+filemap_write_and_wait_range() so that all dirty pages are synced out properly.
+You must also keep in mind that ->fsync() is not called with i_mutex held
+anymore, so if you require i_mutex locking you must make sure to take it and
+release it yourself.
+
+---
+
+**mandatory**
+
+d_alloc_root() is gone, along with a lot of bugs caused by code
+misusing it. Replacement: d_make_root(inode). On success d_make_root(inode)
+allocates and returns a new dentry instantiated with the passed in inode.
+On failure NULL is returned and the passed in inode is dropped so the reference
+to inode is consumed in all cases and failure handling need not do any cleanup
+for the inode. If d_make_root(inode) is passed a NULL inode it returns NULL
+and also requires no further error handling. Typical usage is::
+
+ inode = foofs_new_inode(....);
+ s->s_root = d_make_root(inode);
+ if (!s->s_root)
+ /* Nothing needed for the inode cleanup */
+ return -ENOMEM;
+ ...
+
+---
+
+**mandatory**
+
+The witch is dead! Well, 2/3 of it, anyway. ->d_revalidate() and
+->lookup() do *not* take struct nameidata anymore; just the flags.
+
+---
+
+**mandatory**
+
+->create() doesn't take ``struct nameidata *``; unlike the previous
+two, it gets "is it an O_EXCL or equivalent?" boolean argument. Note that
+local filesystems can ignore tha argument - they are guaranteed that the
+object doesn't exist. It's remote/distributed ones that might care...
+
+---
+
+**mandatory**
+
+FS_REVAL_DOT is gone; if you used to have it, add ->d_weak_revalidate()
+in your dentry operations instead.
+
+---
+
+**mandatory**
+
+vfs_readdir() is gone; switch to iterate_dir() instead
+
+---
+
+**mandatory**
+
+->readdir() is gone now; switch to ->iterate()
+
+**mandatory**
+
+vfs_follow_link has been removed. Filesystems must use nd_set_link
+from ->follow_link for normal symlinks, or nd_jump_link for magic
+/proc/<pid> style links.
+
+---
+
+**mandatory**
+
+iget5_locked()/ilookup5()/ilookup5_nowait() test() callback used to be
+called with both ->i_lock and inode_hash_lock held; the former is *not*
+taken anymore, so verify that your callbacks do not rely on it (none
+of the in-tree instances did). inode_hash_lock is still held,
+of course, so they are still serialized wrt removal from inode hash,
+as well as wrt set() callback of iget5_locked().
+
+---
+
+**mandatory**
+
+d_materialise_unique() is gone; d_splice_alias() does everything you
+need now. Remember that they have opposite orders of arguments ;-/
+
+---
+
+**mandatory**
+
+f_dentry is gone; use f_path.dentry, or, better yet, see if you can avoid
+it entirely.
+
+---
+
+**mandatory**
+
+never call ->read() and ->write() directly; use __vfs_{read,write} or
+wrappers; instead of checking for ->write or ->read being NULL, look for
+FMODE_CAN_{WRITE,READ} in file->f_mode.
+
+---
+
+**mandatory**
+
+do _not_ use new_sync_{read,write} for ->read/->write; leave it NULL
+instead.
+
+---
+
+**mandatory**
+ ->aio_read/->aio_write are gone. Use ->read_iter/->write_iter.
+
+---
+
+**recommended**
+
+for embedded ("fast") symlinks just set inode->i_link to wherever the
+symlink body is and use simple_follow_link() as ->follow_link().
+
+---
+
+**mandatory**
+
+calling conventions for ->follow_link() have changed. Instead of returning
+cookie and using nd_set_link() to store the body to traverse, we return
+the body to traverse and store the cookie using explicit void ** argument.
+nameidata isn't passed at all - nd_jump_link() doesn't need it and
+nd_[gs]et_link() is gone.
+
+---
+
+**mandatory**
+
+calling conventions for ->put_link() have changed. It gets inode instead of
+dentry, it does not get nameidata at all and it gets called only when cookie
+is non-NULL. Note that link body isn't available anymore, so if you need it,
+store it as cookie.
+
+---
+
+**mandatory**
+
+any symlink that might use page_follow_link_light/page_put_link() must
+have inode_nohighmem(inode) called before anything might start playing with
+its pagecache. No highmem pages should end up in the pagecache of such
+symlinks. That includes any preseeding that might be done during symlink
+creation. __page_symlink() will honour the mapping gfp flags, so once
+you've done inode_nohighmem() it's safe to use, but if you allocate and
+insert the page manually, make sure to use the right gfp flags.
+
+---
+
+**mandatory**
+
+->follow_link() is replaced with ->get_link(); same API, except that
+
+ * ->get_link() gets inode as a separate argument
+ * ->get_link() may be called in RCU mode - in that case NULL
+ dentry is passed
+
+---
+
+**mandatory**
+
+->get_link() gets struct delayed_call ``*done`` now, and should do
+set_delayed_call() where it used to set ``*cookie``.
+
+->put_link() is gone - just give the destructor to set_delayed_call()
+in ->get_link().
+
+---
+
+**mandatory**
+
+->getxattr() and xattr_handler.get() get dentry and inode passed separately.
+dentry might be yet to be attached to inode, so do _not_ use its ->d_inode
+in the instances. Rationale: !@#!@# security_d_instantiate() needs to be
+called before we attach dentry to inode.
+
+---
+
+**mandatory**
+
+symlinks are no longer the only inodes that do *not* have i_bdev/i_cdev/
+i_pipe/i_link union zeroed out at inode eviction. As the result, you can't
+assume that non-NULL value in ->i_nlink at ->destroy_inode() implies that
+it's a symlink. Checking ->i_mode is really needed now. In-tree we had
+to fix shmem_destroy_callback() that used to take that kind of shortcut;
+watch out, since that shortcut is no longer valid.
+
+---
+
+**mandatory**
+
+->i_mutex is replaced with ->i_rwsem now. inode_lock() et.al. work as
+they used to - they just take it exclusive. However, ->lookup() may be
+called with parent locked shared. Its instances must not
+
+ * use d_instantiate) and d_rehash() separately - use d_add() or
+ d_splice_alias() instead.
+ * use d_rehash() alone - call d_add(new_dentry, NULL) instead.
+ * in the unlikely case when (read-only) access to filesystem
+ data structures needs exclusion for some reason, arrange it
+ yourself. None of the in-tree filesystems needed that.
+ * rely on ->d_parent and ->d_name not changing after dentry has
+ been fed to d_add() or d_splice_alias(). Again, none of the
+ in-tree instances relied upon that.
+
+We are guaranteed that lookups of the same name in the same directory
+will not happen in parallel ("same" in the sense of your ->d_compare()).
+Lookups on different names in the same directory can and do happen in
+parallel now.
+
+---
+
+**recommended**
+
+->iterate_shared() is added; it's a parallel variant of ->iterate().
+Exclusion on struct file level is still provided (as well as that
+between it and lseek on the same struct file), but if your directory
+has been opened several times, you can get these called in parallel.
+Exclusion between that method and all directory-modifying ones is
+still provided, of course.
+
+Often enough ->iterate() can serve as ->iterate_shared() without any
+changes - it is a read-only operation, after all. If you have any
+per-inode or per-dentry in-core data structures modified by ->iterate(),
+you might need something to serialize the access to them. If you
+do dcache pre-seeding, you'll need to switch to d_alloc_parallel() for
+that; look for in-tree examples.
+
+Old method is only used if the new one is absent; eventually it will
+be removed. Switch while you still can; the old one won't stay.
+
+---
+
+**mandatory**
+
+->atomic_open() calls without O_CREAT may happen in parallel.
+
+---
+
+**mandatory**
+
+->setxattr() and xattr_handler.set() get dentry and inode passed separately.
+dentry might be yet to be attached to inode, so do _not_ use its ->d_inode
+in the instances. Rationale: !@#!@# security_d_instantiate() needs to be
+called before we attach dentry to inode and !@#!@##!@$!$#!@#$!@$!@$ smack
+->d_instantiate() uses not just ->getxattr() but ->setxattr() as well.
+
+---
+
+**mandatory**
+
+->d_compare() doesn't get parent as a separate argument anymore. If you
+used it for finding the struct super_block involved, dentry->d_sb will
+work just as well; if it's something more complicated, use dentry->d_parent.
+Just be careful not to assume that fetching it more than once will yield
+the same value - in RCU mode it could change under you.
+
+---
+
+**mandatory**
+
+->rename() has an added flags argument. Any flags not handled by the
+filesystem should result in EINVAL being returned.
+
+---
+
+
+**recommended**
+
+->readlink is optional for symlinks. Don't set, unless filesystem needs
+to fake something for readlink(2).
+
+---
+
+**mandatory**
+
+->getattr() is now passed a struct path rather than a vfsmount and
+dentry separately, and it now has request_mask and query_flags arguments
+to specify the fields and sync type requested by statx. Filesystems not
+supporting any statx-specific features may ignore the new arguments.
+
+---
+
+**mandatory**
+
+->atomic_open() calling conventions have changed. Gone is ``int *opened``,
+along with FILE_OPENED/FILE_CREATED. In place of those we have
+FMODE_OPENED/FMODE_CREATED, set in file->f_mode. Additionally, return
+value for 'called finish_no_open(), open it yourself' case has become
+0, not 1. Since finish_no_open() itself is returning 0 now, that part
+does not need any changes in ->atomic_open() instances.
+
+---
+
+**mandatory**
+
+alloc_file() has become static now; two wrappers are to be used instead.
+alloc_file_pseudo(inode, vfsmount, name, flags, ops) is for the cases
+when dentry needs to be created; that's the majority of old alloc_file()
+users. Calling conventions: on success a reference to new struct file
+is returned and callers reference to inode is subsumed by that. On
+failure, ERR_PTR() is returned and no caller's references are affected,
+so the caller needs to drop the inode reference it held.
+alloc_file_clone(file, flags, ops) does not affect any caller's references.
+On success you get a new struct file sharing the mount/dentry with the
+original, on failure - ERR_PTR().
+
+---
+
+**mandatory**
+
+->clone_file_range() and ->dedupe_file_range have been replaced with
+->remap_file_range(). See Documentation/filesystems/vfs.rst for more
+information.
+
+---
+
+**recommended**
+
+->lookup() instances doing an equivalent of::
+
+ if (IS_ERR(inode))
+ return ERR_CAST(inode);
+ return d_splice_alias(inode, dentry);
+
+don't need to bother with the check - d_splice_alias() will do the
+right thing when given ERR_PTR(...) as inode. Moreover, passing NULL
+inode to d_splice_alias() will also do the right thing (equivalent of
+d_add(dentry, NULL); return NULL;), so that kind of special cases
+also doesn't need a separate treatment.
+
+---
+
+**strongly recommended**
+
+take the RCU-delayed parts of ->destroy_inode() into a new method -
+->free_inode(). If ->destroy_inode() becomes empty - all the better,
+just get rid of it. Synchronous work (e.g. the stuff that can't
+be done from an RCU callback, or any WARN_ON() where we want the
+stack trace) *might* be movable to ->evict_inode(); however,
+that goes only for the things that are not needed to balance something
+done by ->alloc_inode(). IOW, if it's cleaning up the stuff that
+might have accumulated over the life of in-core inode, ->evict_inode()
+might be a fit.
+
+Rules for inode destruction:
+
+ * if ->destroy_inode() is non-NULL, it gets called
+ * if ->free_inode() is non-NULL, it gets scheduled by call_rcu()
+ * combination of NULL ->destroy_inode and NULL ->free_inode is
+ treated as NULL/free_inode_nonrcu, to preserve the compatibility.
+
+Note that the callback (be it via ->free_inode() or explicit call_rcu()
+in ->destroy_inode()) is *NOT* ordered wrt superblock destruction;
+as the matter of fact, the superblock and all associated structures
+might be already gone. The filesystem driver is guaranteed to be still
+there, but that's it. Freeing memory in the callback is fine; doing
+more than that is possible, but requires a lot of care and is best
+avoided.
+
+---
+
+**mandatory**
+
+DCACHE_RCUACCESS is gone; having an RCU delay on dentry freeing is the
+default. DCACHE_NORCU opts out, and only d_alloc_pseudo() has any
+business doing so.
+
+---
+
+**mandatory**
+
+d_alloc_pseudo() is internal-only; uses outside of alloc_file_pseudo() are
+very suspect (and won't work in modules). Such uses are very likely to
+be misspelled d_alloc_anon().
diff --git a/Documentation/filesystems/ubifs-authentication.md b/Documentation/filesystems/ubifs-authentication.md
deleted file mode 100644
index 23e6981..0000000
--- a/Documentation/filesystems/ubifs-authentication.md
+++ /dev/null
@@ -1,426 +0,0 @@
-% UBIFS Authentication
-% sigma star gmbh
-% 2018
-
-# Introduction
-
-UBIFS utilizes the fscrypt framework to provide confidentiality for file
-contents and file names. This prevents attacks where an attacker is able to
-read contents of the filesystem on a single point in time. A classic example
-is a lost smartphone where the attacker is unable to read personal data stored
-on the device without the filesystem decryption key.
-
-At the current state, UBIFS encryption however does not prevent attacks where
-the attacker is able to modify the filesystem contents and the user uses the
-device afterwards. In such a scenario an attacker can modify filesystem
-contents arbitrarily without the user noticing. One example is to modify a
-binary to perform a malicious action when executed [DMC-CBC-ATTACK]. Since
-most of the filesystem metadata of UBIFS is stored in plain, this makes it
-fairly easy to swap files and replace their contents.
-
-Other full disk encryption systems like dm-crypt cover all filesystem metadata,
-which makes such kinds of attacks more complicated, but not impossible.
-Especially, if the attacker is given access to the device multiple points in
-time. For dm-crypt and other filesystems that build upon the Linux block IO
-layer, the dm-integrity or dm-verity subsystems [DM-INTEGRITY, DM-VERITY]
-can be used to get full data authentication at the block layer.
-These can also be combined with dm-crypt [CRYPTSETUP2].
-
-This document describes an approach to get file contents _and_ full metadata
-authentication for UBIFS. Since UBIFS uses fscrypt for file contents and file
-name encryption, the authentication system could be tied into fscrypt such that
-existing features like key derivation can be utilized. It should however also
-be possible to use UBIFS authentication without using encryption.
-
-
-## MTD, UBI & UBIFS
-
-On Linux, the MTD (Memory Technology Devices) subsystem provides a uniform
-interface to access raw flash devices. One of the more prominent subsystems that
-work on top of MTD is UBI (Unsorted Block Images). It provides volume management
-for flash devices and is thus somewhat similar to LVM for block devices. In
-addition, it deals with flash-specific wear-leveling and transparent I/O error
-handling. UBI offers logical erase blocks (LEBs) to the layers on top of it
-and maps them transparently to physical erase blocks (PEBs) on the flash.
-
-UBIFS is a filesystem for raw flash which operates on top of UBI. Thus, wear
-leveling and some flash specifics are left to UBI, while UBIFS focuses on
-scalability, performance and recoverability.
-
-
-
- +------------+ +*******+ +-----------+ +-----+
- | | * UBIFS * | UBI-BLOCK | | ... |
- | JFFS/JFFS2 | +*******+ +-----------+ +-----+
- | | +-----------------------------+ +-----------+ +-----+
- | | | UBI | | MTD-BLOCK | | ... |
- +------------+ +-----------------------------+ +-----------+ +-----+
- +------------------------------------------------------------------+
- | MEMORY TECHNOLOGY DEVICES (MTD) |
- +------------------------------------------------------------------+
- +-----------------------------+ +--------------------------+ +-----+
- | NAND DRIVERS | | NOR DRIVERS | | ... |
- +-----------------------------+ +--------------------------+ +-----+
-
- Figure 1: Linux kernel subsystems for dealing with raw flash
-
-
-
-Internally, UBIFS maintains multiple data structures which are persisted on
-the flash:
-
-- *Index*: an on-flash B+ tree where the leaf nodes contain filesystem data
-- *Journal*: an additional data structure to collect FS changes before updating
- the on-flash index and reduce flash wear.
-- *Tree Node Cache (TNC)*: an in-memory B+ tree that reflects the current FS
- state to avoid frequent flash reads. It is basically the in-memory
- representation of the index, but contains additional attributes.
-- *LEB property tree (LPT)*: an on-flash B+ tree for free space accounting per
- UBI LEB.
-
-In the remainder of this section we will cover the on-flash UBIFS data
-structures in more detail. The TNC is of less importance here since it is never
-persisted onto the flash directly. More details on UBIFS can also be found in
-[UBIFS-WP].
-
-
-### UBIFS Index & Tree Node Cache
-
-Basic on-flash UBIFS entities are called *nodes*. UBIFS knows different types
-of nodes. Eg. data nodes (`struct ubifs_data_node`) which store chunks of file
-contents or inode nodes (`struct ubifs_ino_node`) which represent VFS inodes.
-Almost all types of nodes share a common header (`ubifs_ch`) containing basic
-information like node type, node length, a sequence number, etc. (see
-`fs/ubifs/ubifs-media.h`in kernel source). Exceptions are entries of the LPT
-and some less important node types like padding nodes which are used to pad
-unusable content at the end of LEBs.
-
-To avoid re-writing the whole B+ tree on every single change, it is implemented
-as *wandering tree*, where only the changed nodes are re-written and previous
-versions of them are obsoleted without erasing them right away. As a result,
-the index is not stored in a single place on the flash, but *wanders* around
-and there are obsolete parts on the flash as long as the LEB containing them is
-not reused by UBIFS. To find the most recent version of the index, UBIFS stores
-a special node called *master node* into UBI LEB 1 which always points to the
-most recent root node of the UBIFS index. For recoverability, the master node
-is additionally duplicated to LEB 2. Mounting UBIFS is thus a simple read of
-LEB 1 and 2 to get the current master node and from there get the location of
-the most recent on-flash index.
-
-The TNC is the in-memory representation of the on-flash index. It contains some
-additional runtime attributes per node which are not persisted. One of these is
-a dirty-flag which marks nodes that have to be persisted the next time the
-index is written onto the flash. The TNC acts as a write-back cache and all
-modifications of the on-flash index are done through the TNC. Like other caches,
-the TNC does not have to mirror the full index into memory, but reads parts of
-it from flash whenever needed. A *commit* is the UBIFS operation of updating the
-on-flash filesystem structures like the index. On every commit, the TNC nodes
-marked as dirty are written to the flash to update the persisted index.
-
-
-### Journal
-
-To avoid wearing out the flash, the index is only persisted (*commited*) when
-certain conditions are met (eg. `fsync(2)`). The journal is used to record
-any changes (in form of inode nodes, data nodes etc.) between commits
-of the index. During mount, the journal is read from the flash and replayed
-onto the TNC (which will be created on-demand from the on-flash index).
-
-UBIFS reserves a bunch of LEBs just for the journal called *log area*. The
-amount of log area LEBs is configured on filesystem creation (using
-`mkfs.ubifs`) and stored in the superblock node. The log area contains only
-two types of nodes: *reference nodes* and *commit start nodes*. A commit start
-node is written whenever an index commit is performed. Reference nodes are
-written on every journal update. Each reference node points to the position of
-other nodes (inode nodes, data nodes etc.) on the flash that are part of this
-journal entry. These nodes are called *buds* and describe the actual filesystem
-changes including their data.
-
-The log area is maintained as a ring. Whenever the journal is almost full,
-a commit is initiated. This also writes a commit start node so that during
-mount, UBIFS will seek for the most recent commit start node and just replay
-every reference node after that. Every reference node before the commit start
-node will be ignored as they are already part of the on-flash index.
-
-When writing a journal entry, UBIFS first ensures that enough space is
-available to write the reference node and buds part of this entry. Then, the
-reference node is written and afterwards the buds describing the file changes.
-On replay, UBIFS will record every reference node and inspect the location of
-the referenced LEBs to discover the buds. If these are corrupt or missing,
-UBIFS will attempt to recover them by re-reading the LEB. This is however only
-done for the last referenced LEB of the journal. Only this can become corrupt
-because of a power cut. If the recovery fails, UBIFS will not mount. An error
-for every other LEB will directly cause UBIFS to fail the mount operation.
-
-
- | ---- LOG AREA ---- | ---------- MAIN AREA ------------ |
-
- -----+------+-----+--------+---- ------+-----+-----+---------------
- \ | | | | / / | | | \
- / CS | REF | REF | | \ \ DENT | INO | INO | /
- \ | | | | / / | | | \
- ----+------+-----+--------+--- -------+-----+-----+----------------
- | | ^ ^
- | | | |
- +------------------------+ |
- | |
- +-------------------------------+
-
-
- Figure 2: UBIFS flash layout of log area with commit start nodes
- (CS) and reference nodes (REF) pointing to main area
- containing their buds
-
-
-### LEB Property Tree/Table
-
-The LEB property tree is used to store per-LEB information. This includes the
-LEB type and amount of free and *dirty* (old, obsolete content) space [1] on
-the LEB. The type is important, because UBIFS never mixes index nodes with data
-nodes on a single LEB and thus each LEB has a specific purpose. This again is
-useful for free space calculations. See [UBIFS-WP] for more details.
-
-The LEB property tree again is a B+ tree, but it is much smaller than the
-index. Due to its smaller size it is always written as one chunk on every
-commit. Thus, saving the LPT is an atomic operation.
-
-
-[1] Since LEBs can only be appended and never overwritten, there is a
-difference between free space ie. the remaining space left on the LEB to be
-written to without erasing it and previously written content that is obsolete
-but can't be overwritten without erasing the full LEB.
-
-
-# UBIFS Authentication
-
-This chapter introduces UBIFS authentication which enables UBIFS to verify
-the authenticity and integrity of metadata and file contents stored on flash.
-
-
-## Threat Model
-
-UBIFS authentication enables detection of offline data modification. While it
-does not prevent it, it enables (trusted) code to check the integrity and
-authenticity of on-flash file contents and filesystem metadata. This covers
-attacks where file contents are swapped.
-
-UBIFS authentication will not protect against rollback of full flash contents.
-Ie. an attacker can still dump the flash and restore it at a later time without
-detection. It will also not protect against partial rollback of individual
-index commits. That means that an attacker is able to partially undo changes.
-This is possible because UBIFS does not immediately overwrites obsolete
-versions of the index tree or the journal, but instead marks them as obsolete
-and garbage collection erases them at a later time. An attacker can use this by
-erasing parts of the current tree and restoring old versions that are still on
-the flash and have not yet been erased. This is possible, because every commit
-will always write a new version of the index root node and the master node
-without overwriting the previous version. This is further helped by the
-wear-leveling operations of UBI which copies contents from one physical
-eraseblock to another and does not atomically erase the first eraseblock.
-
-UBIFS authentication does not cover attacks where an attacker is able to
-execute code on the device after the authentication key was provided.
-Additional measures like secure boot and trusted boot have to be taken to
-ensure that only trusted code is executed on a device.
-
-
-## Authentication
-
-To be able to fully trust data read from flash, all UBIFS data structures
-stored on flash are authenticated. That is:
-
-- The index which includes file contents, file metadata like extended
- attributes, file length etc.
-- The journal which also contains file contents and metadata by recording changes
- to the filesystem
-- The LPT which stores UBI LEB metadata which UBIFS uses for free space accounting
-
-
-### Index Authentication
-
-Through UBIFS' concept of a wandering tree, it already takes care of only
-updating and persisting changed parts from leaf node up to the root node
-of the full B+ tree. This enables us to augment the index nodes of the tree
-with a hash over each node's child nodes. As a result, the index basically also
-a Merkle tree. Since the leaf nodes of the index contain the actual filesystem
-data, the hashes of their parent index nodes thus cover all the file contents
-and file metadata. When a file changes, the UBIFS index is updated accordingly
-from the leaf nodes up to the root node including the master node. This process
-can be hooked to recompute the hash only for each changed node at the same time.
-Whenever a file is read, UBIFS can verify the hashes from each leaf node up to
-the root node to ensure the node's integrity.
-
-To ensure the authenticity of the whole index, the UBIFS master node stores a
-keyed hash (HMAC) over its own contents and a hash of the root node of the index
-tree. As mentioned above, the master node is always written to the flash whenever
-the index is persisted (ie. on index commit).
-
-Using this approach only UBIFS index nodes and the master node are changed to
-include a hash. All other types of nodes will remain unchanged. This reduces
-the storage overhead which is precious for users of UBIFS (ie. embedded
-devices).
-
-
- +---------------+
- | Master Node |
- | (hash) |
- +---------------+
- |
- v
- +-------------------+
- | Index Node #1 |
- | |
- | branch0 branchn |
- | (hash) (hash) |
- +-------------------+
- | ... | (fanout: 8)
- | |
- +-------+ +------+
- | |
- v v
- +-------------------+ +-------------------+
- | Index Node #2 | | Index Node #3 |
- | | | |
- | branch0 branchn | | branch0 branchn |
- | (hash) (hash) | | (hash) (hash) |
- +-------------------+ +-------------------+
- | ... | ... |
- v v v
- +-----------+ +----------+ +-----------+
- | Data Node | | INO Node | | DENT Node |
- +-----------+ +----------+ +-----------+
-
-
- Figure 3: Coverage areas of index node hash and master node HMAC
-
-
-
-The most important part for robustness and power-cut safety is to atomically
-persist the hash and file contents. Here the existing UBIFS logic for how
-changed nodes are persisted is already designed for this purpose such that
-UBIFS can safely recover if a power-cut occurs while persisting. Adding
-hashes to index nodes does not change this since each hash will be persisted
-atomically together with its respective node.
-
-
-### Journal Authentication
-
-The journal is authenticated too. Since the journal is continuously written
-it is necessary to also add authentication information frequently to the
-journal so that in case of a powercut not too much data can't be authenticated.
-This is done by creating a continuous hash beginning from the commit start node
-over the previous reference nodes, the current reference node, and the bud
-nodes. From time to time whenever it is suitable authentication nodes are added
-between the bud nodes. This new node type contains a HMAC over the current state
-of the hash chain. That way a journal can be authenticated up to the last
-authentication node. The tail of the journal which may not have a authentication
-node cannot be authenticated and is skipped during journal replay.
-
-We get this picture for journal authentication:
-
- ,,,,,,,,
- ,......,...........................................
- ,. CS , hash1.----. hash2.----.
- ,. | , . |hmac . |hmac
- ,. v , . v . v
- ,.REF#0,-> bud -> bud -> bud.-> auth -> bud -> bud.-> auth ...
- ,..|...,...........................................
- , | ,
- , | ,,,,,,,,,,,,,,,
- . | hash3,----.
- , | , |hmac
- , v , v
- , REF#1 -> bud -> bud,-> auth ...
- ,,,|,,,,,,,,,,,,,,,,,,
- v
- REF#2 -> ...
- |
- V
- ...
-
-Since the hash also includes the reference nodes an attacker cannot reorder or
-skip any journal heads for replay. An attacker can only remove bud nodes or
-reference nodes from the end of the journal, effectively rewinding the
-filesystem at maximum back to the last commit.
-
-The location of the log area is stored in the master node. Since the master
-node is authenticated with a HMAC as described above, it is not possible to
-tamper with that without detection. The size of the log area is specified when
-the filesystem is created using `mkfs.ubifs` and stored in the superblock node.
-To avoid tampering with this and other values stored there, a HMAC is added to
-the superblock struct. The superblock node is stored in LEB 0 and is only
-modified on feature flag or similar changes, but never on file changes.
-
-
-### LPT Authentication
-
-The location of the LPT root node on the flash is stored in the UBIFS master
-node. Since the LPT is written and read atomically on every commit, there is
-no need to authenticate individual nodes of the tree. It suffices to
-protect the integrity of the full LPT by a simple hash stored in the master
-node. Since the master node itself is authenticated, the LPTs authenticity can
-be verified by verifying the authenticity of the master node and comparing the
-LTP hash stored there with the hash computed from the read on-flash LPT.
-
-
-## Key Management
-
-For simplicity, UBIFS authentication uses a single key to compute the HMACs
-of superblock, master, commit start and reference nodes. This key has to be
-available on creation of the filesystem (`mkfs.ubifs`) to authenticate the
-superblock node. Further, it has to be available on mount of the filesystem
-to verify authenticated nodes and generate new HMACs for changes.
-
-UBIFS authentication is intended to operate side-by-side with UBIFS encryption
-(fscrypt) to provide confidentiality and authenticity. Since UBIFS encryption
-has a different approach of encryption policies per directory, there can be
-multiple fscrypt master keys and there might be folders without encryption.
-UBIFS authentication on the other hand has an all-or-nothing approach in the
-sense that it either authenticates everything of the filesystem or nothing.
-Because of this and because UBIFS authentication should also be usable without
-encryption, it does not share the same master key with fscrypt, but manages
-a dedicated authentication key.
-
-The API for providing the authentication key has yet to be defined, but the
-key can eg. be provided by userspace through a keyring similar to the way it
-is currently done in fscrypt. It should however be noted that the current
-fscrypt approach has shown its flaws and the userspace API will eventually
-change [FSCRYPT-POLICY2].
-
-Nevertheless, it will be possible for a user to provide a single passphrase
-or key in userspace that covers UBIFS authentication and encryption. This can
-be solved by the corresponding userspace tools which derive a second key for
-authentication in addition to the derived fscrypt master key used for
-encryption.
-
-To be able to check if the proper key is available on mount, the UBIFS
-superblock node will additionally store a hash of the authentication key. This
-approach is similar to the approach proposed for fscrypt encryption policy v2
-[FSCRYPT-POLICY2].
-
-
-# Future Extensions
-
-In certain cases where a vendor wants to provide an authenticated filesystem
-image to customers, it should be possible to do so without sharing the secret
-UBIFS authentication key. Instead, in addition the each HMAC a digital
-signature could be stored where the vendor shares the public key alongside the
-filesystem image. In case this filesystem has to be modified afterwards,
-UBIFS can exchange all digital signatures with HMACs on first mount similar
-to the way the IMA/EVM subsystem deals with such situations. The HMAC key
-will then have to be provided beforehand in the normal way.
-
-
-# References
-
-[CRYPTSETUP2] http://www.saout.de/pipermail/dm-crypt/2017-November/005745.html
-
-[DMC-CBC-ATTACK] http://www.jakoblell.com/blog/2013/12/22/practical-malleability-attack-against-cbc-encrypted-luks-partitions/
-
-[DM-INTEGRITY] https://www.kernel.org/doc/Documentation/device-mapper/dm-integrity.rst
-
-[DM-VERITY] https://www.kernel.org/doc/Documentation/device-mapper/verity.rst
-
-[FSCRYPT-POLICY2] https://www.spinics.net/lists/linux-ext4/msg58710.html
-
-[UBIFS-WP] http://www.linux-mtd.infradead.org/doc/ubifs_whitepaper.pdf
diff --git a/Documentation/filesystems/ubifs-authentication.rst b/Documentation/filesystems/ubifs-authentication.rst
new file mode 100644
index 0000000..6a9584f
--- /dev/null
+++ b/Documentation/filesystems/ubifs-authentication.rst
@@ -0,0 +1,444 @@
+:orphan:
+
+.. UBIFS Authentication
+.. sigma star gmbh
+.. 2018
+
+Introduction
+============
+
+UBIFS utilizes the fscrypt framework to provide confidentiality for file
+contents and file names. This prevents attacks where an attacker is able to
+read contents of the filesystem on a single point in time. A classic example
+is a lost smartphone where the attacker is unable to read personal data stored
+on the device without the filesystem decryption key.
+
+At the current state, UBIFS encryption however does not prevent attacks where
+the attacker is able to modify the filesystem contents and the user uses the
+device afterwards. In such a scenario an attacker can modify filesystem
+contents arbitrarily without the user noticing. One example is to modify a
+binary to perform a malicious action when executed [DMC-CBC-ATTACK]. Since
+most of the filesystem metadata of UBIFS is stored in plain, this makes it
+fairly easy to swap files and replace their contents.
+
+Other full disk encryption systems like dm-crypt cover all filesystem metadata,
+which makes such kinds of attacks more complicated, but not impossible.
+Especially, if the attacker is given access to the device multiple points in
+time. For dm-crypt and other filesystems that build upon the Linux block IO
+layer, the dm-integrity or dm-verity subsystems [DM-INTEGRITY, DM-VERITY]
+can be used to get full data authentication at the block layer.
+These can also be combined with dm-crypt [CRYPTSETUP2].
+
+This document describes an approach to get file contents _and_ full metadata
+authentication for UBIFS. Since UBIFS uses fscrypt for file contents and file
+name encryption, the authentication system could be tied into fscrypt such that
+existing features like key derivation can be utilized. It should however also
+be possible to use UBIFS authentication without using encryption.
+
+
+MTD, UBI & UBIFS
+----------------
+
+On Linux, the MTD (Memory Technology Devices) subsystem provides a uniform
+interface to access raw flash devices. One of the more prominent subsystems that
+work on top of MTD is UBI (Unsorted Block Images). It provides volume management
+for flash devices and is thus somewhat similar to LVM for block devices. In
+addition, it deals with flash-specific wear-leveling and transparent I/O error
+handling. UBI offers logical erase blocks (LEBs) to the layers on top of it
+and maps them transparently to physical erase blocks (PEBs) on the flash.
+
+UBIFS is a filesystem for raw flash which operates on top of UBI. Thus, wear
+leveling and some flash specifics are left to UBI, while UBIFS focuses on
+scalability, performance and recoverability.
+
+::
+
+ +------------+ +*******+ +-----------+ +-----+
+ | | * UBIFS * | UBI-BLOCK | | ... |
+ | JFFS/JFFS2 | +*******+ +-----------+ +-----+
+ | | +-----------------------------+ +-----------+ +-----+
+ | | | UBI | | MTD-BLOCK | | ... |
+ +------------+ +-----------------------------+ +-----------+ +-----+
+ +------------------------------------------------------------------+
+ | MEMORY TECHNOLOGY DEVICES (MTD) |
+ +------------------------------------------------------------------+
+ +-----------------------------+ +--------------------------+ +-----+
+ | NAND DRIVERS | | NOR DRIVERS | | ... |
+ +-----------------------------+ +--------------------------+ +-----+
+
+ Figure 1: Linux kernel subsystems for dealing with raw flash
+
+
+
+Internally, UBIFS maintains multiple data structures which are persisted on
+the flash:
+
+- *Index*: an on-flash B+ tree where the leaf nodes contain filesystem data
+- *Journal*: an additional data structure to collect FS changes before updating
+ the on-flash index and reduce flash wear.
+- *Tree Node Cache (TNC)*: an in-memory B+ tree that reflects the current FS
+ state to avoid frequent flash reads. It is basically the in-memory
+ representation of the index, but contains additional attributes.
+- *LEB property tree (LPT)*: an on-flash B+ tree for free space accounting per
+ UBI LEB.
+
+In the remainder of this section we will cover the on-flash UBIFS data
+structures in more detail. The TNC is of less importance here since it is never
+persisted onto the flash directly. More details on UBIFS can also be found in
+[UBIFS-WP].
+
+
+UBIFS Index & Tree Node Cache
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Basic on-flash UBIFS entities are called *nodes*. UBIFS knows different types
+of nodes. Eg. data nodes (`struct ubifs_data_node`) which store chunks of file
+contents or inode nodes (`struct ubifs_ino_node`) which represent VFS inodes.
+Almost all types of nodes share a common header (`ubifs_ch`) containing basic
+information like node type, node length, a sequence number, etc. (see
+`fs/ubifs/ubifs-media.h`in kernel source). Exceptions are entries of the LPT
+and some less important node types like padding nodes which are used to pad
+unusable content at the end of LEBs.
+
+To avoid re-writing the whole B+ tree on every single change, it is implemented
+as *wandering tree*, where only the changed nodes are re-written and previous
+versions of them are obsoleted without erasing them right away. As a result,
+the index is not stored in a single place on the flash, but *wanders* around
+and there are obsolete parts on the flash as long as the LEB containing them is
+not reused by UBIFS. To find the most recent version of the index, UBIFS stores
+a special node called *master node* into UBI LEB 1 which always points to the
+most recent root node of the UBIFS index. For recoverability, the master node
+is additionally duplicated to LEB 2. Mounting UBIFS is thus a simple read of
+LEB 1 and 2 to get the current master node and from there get the location of
+the most recent on-flash index.
+
+The TNC is the in-memory representation of the on-flash index. It contains some
+additional runtime attributes per node which are not persisted. One of these is
+a dirty-flag which marks nodes that have to be persisted the next time the
+index is written onto the flash. The TNC acts as a write-back cache and all
+modifications of the on-flash index are done through the TNC. Like other caches,
+the TNC does not have to mirror the full index into memory, but reads parts of
+it from flash whenever needed. A *commit* is the UBIFS operation of updating the
+on-flash filesystem structures like the index. On every commit, the TNC nodes
+marked as dirty are written to the flash to update the persisted index.
+
+
+Journal
+~~~~~~~
+
+To avoid wearing out the flash, the index is only persisted (*commited*) when
+certain conditions are met (eg. ``fsync(2)``). The journal is used to record
+any changes (in form of inode nodes, data nodes etc.) between commits
+of the index. During mount, the journal is read from the flash and replayed
+onto the TNC (which will be created on-demand from the on-flash index).
+
+UBIFS reserves a bunch of LEBs just for the journal called *log area*. The
+amount of log area LEBs is configured on filesystem creation (using
+``mkfs.ubifs``) and stored in the superblock node. The log area contains only
+two types of nodes: *reference nodes* and *commit start nodes*. A commit start
+node is written whenever an index commit is performed. Reference nodes are
+written on every journal update. Each reference node points to the position of
+other nodes (inode nodes, data nodes etc.) on the flash that are part of this
+journal entry. These nodes are called *buds* and describe the actual filesystem
+changes including their data.
+
+The log area is maintained as a ring. Whenever the journal is almost full,
+a commit is initiated. This also writes a commit start node so that during
+mount, UBIFS will seek for the most recent commit start node and just replay
+every reference node after that. Every reference node before the commit start
+node will be ignored as they are already part of the on-flash index.
+
+When writing a journal entry, UBIFS first ensures that enough space is
+available to write the reference node and buds part of this entry. Then, the
+reference node is written and afterwards the buds describing the file changes.
+On replay, UBIFS will record every reference node and inspect the location of
+the referenced LEBs to discover the buds. If these are corrupt or missing,
+UBIFS will attempt to recover them by re-reading the LEB. This is however only
+done for the last referenced LEB of the journal. Only this can become corrupt
+because of a power cut. If the recovery fails, UBIFS will not mount. An error
+for every other LEB will directly cause UBIFS to fail the mount operation.
+
+::
+
+ | ---- LOG AREA ---- | ---------- MAIN AREA ------------ |
+
+ -----+------+-----+--------+---- ------+-----+-----+---------------
+ \ | | | | / / | | | \
+ / CS | REF | REF | | \ \ DENT | INO | INO | /
+ \ | | | | / / | | | \
+ ----+------+-----+--------+--- -------+-----+-----+----------------
+ | | ^ ^
+ | | | |
+ +------------------------+ |
+ | |
+ +-------------------------------+
+
+
+ Figure 2: UBIFS flash layout of log area with commit start nodes
+ (CS) and reference nodes (REF) pointing to main area
+ containing their buds
+
+
+LEB Property Tree/Table
+~~~~~~~~~~~~~~~~~~~~~~~
+
+The LEB property tree is used to store per-LEB information. This includes the
+LEB type and amount of free and *dirty* (old, obsolete content) space [1]_ on
+the LEB. The type is important, because UBIFS never mixes index nodes with data
+nodes on a single LEB and thus each LEB has a specific purpose. This again is
+useful for free space calculations. See [UBIFS-WP] for more details.
+
+The LEB property tree again is a B+ tree, but it is much smaller than the
+index. Due to its smaller size it is always written as one chunk on every
+commit. Thus, saving the LPT is an atomic operation.
+
+
+.. [1] Since LEBs can only be appended and never overwritten, there is a
+ difference between free space ie. the remaining space left on the LEB to be
+ written to without erasing it and previously written content that is obsolete
+ but can't be overwritten without erasing the full LEB.
+
+
+UBIFS Authentication
+====================
+
+This chapter introduces UBIFS authentication which enables UBIFS to verify
+the authenticity and integrity of metadata and file contents stored on flash.
+
+
+Threat Model
+------------
+
+UBIFS authentication enables detection of offline data modification. While it
+does not prevent it, it enables (trusted) code to check the integrity and
+authenticity of on-flash file contents and filesystem metadata. This covers
+attacks where file contents are swapped.
+
+UBIFS authentication will not protect against rollback of full flash contents.
+Ie. an attacker can still dump the flash and restore it at a later time without
+detection. It will also not protect against partial rollback of individual
+index commits. That means that an attacker is able to partially undo changes.
+This is possible because UBIFS does not immediately overwrites obsolete
+versions of the index tree or the journal, but instead marks them as obsolete
+and garbage collection erases them at a later time. An attacker can use this by
+erasing parts of the current tree and restoring old versions that are still on
+the flash and have not yet been erased. This is possible, because every commit
+will always write a new version of the index root node and the master node
+without overwriting the previous version. This is further helped by the
+wear-leveling operations of UBI which copies contents from one physical
+eraseblock to another and does not atomically erase the first eraseblock.
+
+UBIFS authentication does not cover attacks where an attacker is able to
+execute code on the device after the authentication key was provided.
+Additional measures like secure boot and trusted boot have to be taken to
+ensure that only trusted code is executed on a device.
+
+
+Authentication
+--------------
+
+To be able to fully trust data read from flash, all UBIFS data structures
+stored on flash are authenticated. That is:
+
+- The index which includes file contents, file metadata like extended
+ attributes, file length etc.
+- The journal which also contains file contents and metadata by recording changes
+ to the filesystem
+- The LPT which stores UBI LEB metadata which UBIFS uses for free space accounting
+
+
+Index Authentication
+~~~~~~~~~~~~~~~~~~~~
+
+Through UBIFS' concept of a wandering tree, it already takes care of only
+updating and persisting changed parts from leaf node up to the root node
+of the full B+ tree. This enables us to augment the index nodes of the tree
+with a hash over each node's child nodes. As a result, the index basically also
+a Merkle tree. Since the leaf nodes of the index contain the actual filesystem
+data, the hashes of their parent index nodes thus cover all the file contents
+and file metadata. When a file changes, the UBIFS index is updated accordingly
+from the leaf nodes up to the root node including the master node. This process
+can be hooked to recompute the hash only for each changed node at the same time.
+Whenever a file is read, UBIFS can verify the hashes from each leaf node up to
+the root node to ensure the node's integrity.
+
+To ensure the authenticity of the whole index, the UBIFS master node stores a
+keyed hash (HMAC) over its own contents and a hash of the root node of the index
+tree. As mentioned above, the master node is always written to the flash whenever
+the index is persisted (ie. on index commit).
+
+Using this approach only UBIFS index nodes and the master node are changed to
+include a hash. All other types of nodes will remain unchanged. This reduces
+the storage overhead which is precious for users of UBIFS (ie. embedded
+devices).
+
+::
+
+ +---------------+
+ | Master Node |
+ | (hash) |
+ +---------------+
+ |
+ v
+ +-------------------+
+ | Index Node #1 |
+ | |
+ | branch0 branchn |
+ | (hash) (hash) |
+ +-------------------+
+ | ... | (fanout: 8)
+ | |
+ +-------+ +------+
+ | |
+ v v
+ +-------------------+ +-------------------+
+ | Index Node #2 | | Index Node #3 |
+ | | | |
+ | branch0 branchn | | branch0 branchn |
+ | (hash) (hash) | | (hash) (hash) |
+ +-------------------+ +-------------------+
+ | ... | ... |
+ v v v
+ +-----------+ +----------+ +-----------+
+ | Data Node | | INO Node | | DENT Node |
+ +-----------+ +----------+ +-----------+
+
+
+ Figure 3: Coverage areas of index node hash and master node HMAC
+
+
+
+The most important part for robustness and power-cut safety is to atomically
+persist the hash and file contents. Here the existing UBIFS logic for how
+changed nodes are persisted is already designed for this purpose such that
+UBIFS can safely recover if a power-cut occurs while persisting. Adding
+hashes to index nodes does not change this since each hash will be persisted
+atomically together with its respective node.
+
+
+Journal Authentication
+~~~~~~~~~~~~~~~~~~~~~~
+
+The journal is authenticated too. Since the journal is continuously written
+it is necessary to also add authentication information frequently to the
+journal so that in case of a powercut not too much data can't be authenticated.
+This is done by creating a continuous hash beginning from the commit start node
+over the previous reference nodes, the current reference node, and the bud
+nodes. From time to time whenever it is suitable authentication nodes are added
+between the bud nodes. This new node type contains a HMAC over the current state
+of the hash chain. That way a journal can be authenticated up to the last
+authentication node. The tail of the journal which may not have a authentication
+node cannot be authenticated and is skipped during journal replay.
+
+We get this picture for journal authentication::
+
+ ,,,,,,,,
+ ,......,...........................................
+ ,. CS , hash1.----. hash2.----.
+ ,. | , . |hmac . |hmac
+ ,. v , . v . v
+ ,.REF#0,-> bud -> bud -> bud.-> auth -> bud -> bud.-> auth ...
+ ,..|...,...........................................
+ , | ,
+ , | ,,,,,,,,,,,,,,,
+ . | hash3,----.
+ , | , |hmac
+ , v , v
+ , REF#1 -> bud -> bud,-> auth ...
+ ,,,|,,,,,,,,,,,,,,,,,,
+ v
+ REF#2 -> ...
+ |
+ V
+ ...
+
+Since the hash also includes the reference nodes an attacker cannot reorder or
+skip any journal heads for replay. An attacker can only remove bud nodes or
+reference nodes from the end of the journal, effectively rewinding the
+filesystem at maximum back to the last commit.
+
+The location of the log area is stored in the master node. Since the master
+node is authenticated with a HMAC as described above, it is not possible to
+tamper with that without detection. The size of the log area is specified when
+the filesystem is created using `mkfs.ubifs` and stored in the superblock node.
+To avoid tampering with this and other values stored there, a HMAC is added to
+the superblock struct. The superblock node is stored in LEB 0 and is only
+modified on feature flag or similar changes, but never on file changes.
+
+
+LPT Authentication
+~~~~~~~~~~~~~~~~~~
+
+The location of the LPT root node on the flash is stored in the UBIFS master
+node. Since the LPT is written and read atomically on every commit, there is
+no need to authenticate individual nodes of the tree. It suffices to
+protect the integrity of the full LPT by a simple hash stored in the master
+node. Since the master node itself is authenticated, the LPTs authenticity can
+be verified by verifying the authenticity of the master node and comparing the
+LTP hash stored there with the hash computed from the read on-flash LPT.
+
+
+Key Management
+--------------
+
+For simplicity, UBIFS authentication uses a single key to compute the HMACs
+of superblock, master, commit start and reference nodes. This key has to be
+available on creation of the filesystem (`mkfs.ubifs`) to authenticate the
+superblock node. Further, it has to be available on mount of the filesystem
+to verify authenticated nodes and generate new HMACs for changes.
+
+UBIFS authentication is intended to operate side-by-side with UBIFS encryption
+(fscrypt) to provide confidentiality and authenticity. Since UBIFS encryption
+has a different approach of encryption policies per directory, there can be
+multiple fscrypt master keys and there might be folders without encryption.
+UBIFS authentication on the other hand has an all-or-nothing approach in the
+sense that it either authenticates everything of the filesystem or nothing.
+Because of this and because UBIFS authentication should also be usable without
+encryption, it does not share the same master key with fscrypt, but manages
+a dedicated authentication key.
+
+The API for providing the authentication key has yet to be defined, but the
+key can eg. be provided by userspace through a keyring similar to the way it
+is currently done in fscrypt. It should however be noted that the current
+fscrypt approach has shown its flaws and the userspace API will eventually
+change [FSCRYPT-POLICY2].
+
+Nevertheless, it will be possible for a user to provide a single passphrase
+or key in userspace that covers UBIFS authentication and encryption. This can
+be solved by the corresponding userspace tools which derive a second key for
+authentication in addition to the derived fscrypt master key used for
+encryption.
+
+To be able to check if the proper key is available on mount, the UBIFS
+superblock node will additionally store a hash of the authentication key. This
+approach is similar to the approach proposed for fscrypt encryption policy v2
+[FSCRYPT-POLICY2].
+
+
+Future Extensions
+=================
+
+In certain cases where a vendor wants to provide an authenticated filesystem
+image to customers, it should be possible to do so without sharing the secret
+UBIFS authentication key. Instead, in addition the each HMAC a digital
+signature could be stored where the vendor shares the public key alongside the
+filesystem image. In case this filesystem has to be modified afterwards,
+UBIFS can exchange all digital signatures with HMACs on first mount similar
+to the way the IMA/EVM subsystem deals with such situations. The HMAC key
+will then have to be provided beforehand in the normal way.
+
+
+References
+==========
+
+[CRYPTSETUP2] http://www.saout.de/pipermail/dm-crypt/2017-November/005745.html
+
+[DMC-CBC-ATTACK] http://www.jakoblell.com/blog/2013/12/22/practical-malleability-attack-against-cbc-encrypted-luks-partitions/
+
+[DM-INTEGRITY] https://www.kernel.org/doc/Documentation/device-mapper/dm-integrity.rst
+
+[DM-VERITY] https://www.kernel.org/doc/Documentation/device-mapper/verity.rst
+
+[FSCRYPT-POLICY2] https://www.spinics.net/lists/linux-ext4/msg58710.html
+
+[UBIFS-WP] http://www.linux-mtd.infradead.org/doc/ubifs_whitepaper.pdf
diff --git a/Documentation/filesystems/ufs.txt b/Documentation/filesystems/ufs.txt
deleted file mode 100644
index 7a602ad..0000000
--- a/Documentation/filesystems/ufs.txt
+++ /dev/null
@@ -1,60 +0,0 @@
-USING UFS
-=========
-
-mount -t ufs -o ufstype=type_of_ufs device dir
-
-
-UFS OPTIONS
-===========
-
-ufstype=type_of_ufs
- UFS is a file system widely used in different operating systems.
- The problem are differences among implementations. Features of
- some implementations are undocumented, so its hard to recognize
- type of ufs automatically. That's why user must specify type of
- ufs manually by mount option ufstype. Possible values are:
-
- old old format of ufs
- default value, supported as read-only
-
- 44bsd used in FreeBSD, NetBSD, OpenBSD
- supported as read-write
-
- ufs2 used in FreeBSD 5.x
- supported as read-write
-
- 5xbsd synonym for ufs2
-
- sun used in SunOS (Solaris)
- supported as read-write
-
- sunx86 used in SunOS for Intel (Solarisx86)
- supported as read-write
-
- hp used in HP-UX
- supported as read-only
-
- nextstep
- used in NextStep
- supported as read-only
-
- nextstep-cd
- used for NextStep CDROMs (block_size == 2048)
- supported as read-only
-
- openstep
- used in OpenStep
- supported as read-only
-
-
-POSSIBLE PROBLEMS
-=================
-
-See next section, if you have any.
-
-
-BUG REPORTS
-===========
-
-Any ufs bug report you can send to daniel.pirkl@email.cz or
-to dushistov@mail.ru (do not send partition tables bug reports).
diff --git a/Documentation/filesystems/vfs.rst b/Documentation/filesystems/vfs.rst
index 0f85ab2..7d4d09d 100644
--- a/Documentation/filesystems/vfs.rst
+++ b/Documentation/filesystems/vfs.rst
@@ -20,7 +20,7 @@
VFS system calls open(2), stat(2), read(2), write(2), chmod(2) and so on
are called from a process context. Filesystem locking is described in
-the document Documentation/filesystems/Locking.
+the document Documentation/filesystems/locking.rst.
Directory Entry Cache (dcache)
diff --git a/Documentation/filesystems/virtiofs.rst b/Documentation/filesystems/virtiofs.rst
new file mode 100644
index 0000000..4f338e3
--- /dev/null
+++ b/Documentation/filesystems/virtiofs.rst
@@ -0,0 +1,60 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+===================================================
+virtiofs: virtio-fs host<->guest shared file system
+===================================================
+
+- Copyright (C) 2019 Red Hat, Inc.
+
+Introduction
+============
+The virtiofs file system for Linux implements a driver for the paravirtualized
+VIRTIO "virtio-fs" device for guest<->host file system sharing. It allows a
+guest to mount a directory that has been exported on the host.
+
+Guests often require access to files residing on the host or remote systems.
+Use cases include making files available to new guests during installation,
+booting from a root file system located on the host, persistent storage for
+stateless or ephemeral guests, and sharing a directory between guests.
+
+Although it is possible to use existing network file systems for some of these
+tasks, they require configuration steps that are hard to automate and they
+expose the storage network to the guest. The virtio-fs device was designed to
+solve these problems by providing file system access without networking.
+
+Furthermore the virtio-fs device takes advantage of the co-location of the
+guest and host to increase performance and provide semantics that are not
+possible with network file systems.
+
+Usage
+=====
+Mount file system with tag ``myfs`` on ``/mnt``:
+
+.. code-block:: sh
+
+ guest# mount -t virtiofs myfs /mnt
+
+Please see https://virtio-fs.gitlab.io/ for details on how to configure QEMU
+and the virtiofsd daemon.
+
+Internals
+=========
+Since the virtio-fs device uses the FUSE protocol for file system requests, the
+virtiofs file system for Linux is integrated closely with the FUSE file system
+client. The guest acts as the FUSE client while the host acts as the FUSE
+server. The /dev/fuse interface between the kernel and userspace is replaced
+with the virtio-fs device interface.
+
+FUSE requests are placed into a virtqueue and processed by the host. The
+response portion of the buffer is filled in by the host and the guest handles
+the request completion.
+
+Mapping /dev/fuse to virtqueues requires solving differences in semantics
+between /dev/fuse and virtqueues. Each time the /dev/fuse device is read, the
+FUSE client may choose which request to transfer, making it possible to
+prioritize certain requests over others. Virtqueues have queue semantics and
+it is not possible to change the order of requests that have been enqueued.
+This is especially important if the virtqueue becomes full since it is then
+impossible to add high priority requests. In order to address this difference,
+the virtio-fs device uses a "hiprio" virtqueue specifically for requests that
+have priority over normal requests.
diff --git a/Documentation/firmware-guide/acpi/dsd/leds.rst b/Documentation/firmware-guide/acpi/dsd/leds.rst
new file mode 100644
index 0000000..946efe2
--- /dev/null
+++ b/Documentation/firmware-guide/acpi/dsd/leds.rst
@@ -0,0 +1,111 @@
+.. SPDX-License-Identifier: GPL-2.0
+.. include:: <isonum.txt>
+
+========================================
+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
+tells the numerical ID of each individual LED output to which the LEDs are
+connected. [3] The hierarchical data nodes are named "led@X", where X is the
+number of the LED output.
+
+Referring to LEDs in Device tree is documented in [4], in "flash-leds" property
+documentation. In short, LEDs are directly referred to by using phandles.
+
+While Device tree allows referring to any node in the tree[1], in ACPI
+references are limited to device nodes only [2]. For this reason using the same
+mechanism on ACPI is not possible. A mechanism to refer to non-device ACPI nodes
+is documented in [7].
+
+ACPI allows (as does DT) using integer arguments after the reference. A
+combination of the LED driver device reference and an integer argument,
+referring to the "reg" property of the relevant LED, is used to identify
+individual LEDs. The value of the "reg" property is a contract between the
+firmware and software, it uniquely identifies the LED driver outputs.
+
+Under the LED driver device, The first hierarchical data extension package list
+entry shall contain the string "led@" followed by the number of the LED,
+followed by the referred object name. That object shall be named "LED" followed
+by the number of the LED.
+
+Example
+=======
+
+An ASL example of a camera sensor device and a LED driver device for two LEDs is
+show below. Objects not relevant for LEDs or the references to them have been
+omitted. ::
+
+ Device (LED)
+ {
+ Name (_DSD, Package () {
+ ToUUID("dbb8e3e6-5886-4ba6-8795-1319f52a966b"),
+ Package () {
+ Package () { "led@0", LED0 },
+ Package () { "led@1", LED1 },
+ }
+ })
+ Name (LED0, Package () {
+ ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
+ Package () {
+ Package () { "reg", 0 },
+ Package () { "flash-max-microamp", 1000000 },
+ Package () { "flash-timeout-us", 200000 },
+ Package () { "led-max-microamp", 100000 },
+ Package () { "label", "white:flash" },
+ }
+ })
+ Name (LED1, Package () {
+ ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
+ Package () {
+ Package () { "reg", 1 },
+ Package () { "led-max-microamp", 10000 },
+ Package () { "label", "red:indicator" },
+ }
+ })
+ }
+
+ Device (SEN)
+ {
+ Name (_DSD, Package () {
+ ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
+ Package () {
+ Package () {
+ "flash-leds",
+ Package () { ^LED, "led@0", ^LED, "led@1" },
+ }
+ }
+ })
+ }
+
+where
+::
+
+ LED LED driver device
+ LED0 First LED
+ LED1 Second LED
+ SEN Camera sensor device (or another device the LED is related to)
+
+References
+==========
+
+[1] Device tree. <URL:http://www.devicetree.org>, referenced 2019-02-21.
+
+[2] Advanced Configuration and Power Interface Specification.
+ <URL:https://uefi.org/sites/default/files/resources/ACPI_6_3_final_Jan30.pdf>,
+ referenced 2019-02-21.
+
+[3] Documentation/devicetree/bindings/leds/common.txt
+
+[4] Documentation/devicetree/bindings/media/video-interfaces.txt
+
+[5] Device Properties UUID For _DSD.
+ <URL:http://www.uefi.org/sites/default/files/resources/_DSD-device-properties-UUID.pdf>,
+ referenced 2019-02-21.
+
+[6] Hierarchical Data Extension UUID For _DSD.
+ <URL:http://www.uefi.org/sites/default/files/resources/_DSD-hierarchical-data-extension-UUID-v1.1.pdf>,
+ referenced 2019-02-21.
+
+[7] Documentation/firmware-guide/acpi/dsd/data-node-references.rst
diff --git a/Documentation/firmware-guide/acpi/index.rst b/Documentation/firmware-guide/acpi/index.rst
index 90c90d4..ad3b5af 100644
--- a/Documentation/firmware-guide/acpi/index.rst
+++ b/Documentation/firmware-guide/acpi/index.rst
@@ -10,6 +10,7 @@
namespace
dsd/graph
dsd/data-node-references
+ dsd/leds
enumeration
osi
method-customizing
diff --git a/Documentation/fpga/dfl.rst b/Documentation/fpga/dfl.rst
index 2f125ab..6fa483f 100644
--- a/Documentation/fpga/dfl.rst
+++ b/Documentation/fpga/dfl.rst
@@ -87,6 +87,8 @@
- Get driver API version (DFL_FPGA_GET_API_VERSION)
- Check for extensions (DFL_FPGA_CHECK_EXTENSION)
- Program bitstream (DFL_FPGA_FME_PORT_PR)
+- Assign port to PF (DFL_FPGA_FME_PORT_ASSIGN)
+- Release port from PF (DFL_FPGA_FME_PORT_RELEASE)
More functions are exposed through sysfs
(/sys/class/fpga_region/regionX/dfl-fme.n/):
@@ -102,6 +104,10 @@
one FPGA device may have more than one port, this sysfs interface indicates
how many ports the FPGA device has.
+ Global error reporting management (errors/)
+ error reporting sysfs interfaces allow user to read errors detected by the
+ hardware, and clear the logged errors.
+
FIU - PORT
==========
@@ -143,6 +149,10 @@
Read Accelerator GUID (afu_id)
afu_id indicates which PR bitstream is programmed to this AFU.
+ Error reporting (errors/)
+ error reporting sysfs interfaces allow user to read port/afu errors
+ detected by the hardware, and clear the logged errors.
+
DFL Framework Overview
======================
@@ -218,6 +228,101 @@
userspace before calling the reconfiguration IOCTL.
+FPGA virtualization - PCIe SRIOV
+================================
+This section describes the virtualization support on DFL based FPGA device to
+enable accessing an accelerator from applications running in a virtual machine
+(VM). This section only describes the PCIe based FPGA device with SRIOV support.
+
+Features supported by the particular FPGA device are exposed through Device
+Feature Lists, as illustrated below:
+
+::
+
+ +-------------------------------+ +-------------+
+ | PF | | VF |
+ +-------------------------------+ +-------------+
+ ^ ^ ^ ^
+ | | | |
+ +-----|------------|---------|--------------|-------+
+ | | | | | |
+ | +-----+ +-------+ +-------+ +-------+ |
+ | | FME | | Port0 | | Port1 | | Port2 | |
+ | +-----+ +-------+ +-------+ +-------+ |
+ | ^ ^ ^ |
+ | | | | |
+ | +-------+ +------+ +-------+ |
+ | | AFU | | AFU | | AFU | |
+ | +-------+ +------+ +-------+ |
+ | |
+ | DFL based FPGA PCIe Device |
+ +---------------------------------------------------+
+
+FME is always accessed through the physical function (PF).
+
+Ports (and related AFUs) are accessed via PF by default, but could be exposed
+through virtual function (VF) devices via PCIe SRIOV. Each VF only contains
+1 Port and 1 AFU for isolation. Users could assign individual VFs (accelerators)
+created via PCIe SRIOV interface, to virtual machines.
+
+The driver organization in virtualization case is illustrated below:
+::
+
+ +-------++------++------+ |
+ | FME || FME || FME | |
+ | FPGA || FPGA || FPGA | |
+ |Manager||Bridge||Region| |
+ +-------++------++------+ |
+ +-----------------------+ +--------+ | +--------+
+ | FME | | AFU | | | AFU |
+ | Module | | Module | | | Module |
+ +-----------------------+ +--------+ | +--------+
+ +-----------------------+ | +-----------------------+
+ | FPGA Container Device | | | FPGA Container Device |
+ | (FPGA Base Region) | | | (FPGA Base Region) |
+ +-----------------------+ | +-----------------------+
+ +------------------+ | +------------------+
+ | FPGA PCIE Module | | Virtual | FPGA PCIE Module |
+ +------------------+ Host | Machine +------------------+
+ -------------------------------------- | ------------------------------
+ +---------------+ | +---------------+
+ | PCI PF Device | | | PCI VF Device |
+ +---------------+ | +---------------+
+
+FPGA PCIe device driver is always loaded first once a FPGA PCIe PF or VF device
+is detected. It:
+
+* Finishes enumeration on both FPGA PCIe PF and VF device using common
+ interfaces from DFL framework.
+* Supports SRIOV.
+
+The FME device driver plays a management role in this driver architecture, it
+provides ioctls to release Port from PF and assign Port to PF. After release
+a port from PF, then it's safe to expose this port through a VF via PCIe SRIOV
+sysfs interface.
+
+To enable accessing an accelerator from applications running in a VM, the
+respective AFU's port needs to be assigned to a VF using the following steps:
+
+#. The PF owns all AFU ports by default. Any port that needs to be
+ reassigned to a VF must first be released through the
+ DFL_FPGA_FME_PORT_RELEASE ioctl on the FME device.
+
+#. Once N ports are released from PF, then user can use command below
+ to enable SRIOV and VFs. Each VF owns only one Port with AFU.
+
+ ::
+
+ echo N > $PCI_DEVICE_PATH/sriov_numvfs
+
+#. Pass through the VFs to VMs
+
+#. The AFU under VF is accessible from applications in VM (using the
+ same driver inside the VF).
+
+Note that an FME can't be assigned to a VF, thus PR and other management
+functions are only available via the PF.
+
Device enumeration
==================
This section introduces how applications enumerate the fpga device from
diff --git a/Documentation/gpu/drivers.rst b/Documentation/gpu/drivers.rst
index 4bfb706..b4a0ed3 100644
--- a/Documentation/gpu/drivers.rst
+++ b/Documentation/gpu/drivers.rst
@@ -11,7 +11,6 @@
meson
pl111
tegra
- tinydrm
tve200
v3d
vc4
diff --git a/Documentation/gpu/drm-kms-helpers.rst b/Documentation/gpu/drm-kms-helpers.rst
index b327bbc..3868008 100644
--- a/Documentation/gpu/drm-kms-helpers.rst
+++ b/Documentation/gpu/drm-kms-helpers.rst
@@ -263,6 +263,18 @@
drm_dp_mst_topology_put_port
drm_dp_mst_get_mstb_malloc drm_dp_mst_put_mstb_malloc
+MIPI DBI Helper Functions Reference
+===================================
+
+.. kernel-doc:: drivers/gpu/drm/drm_mipi_dbi.c
+ :doc: overview
+
+.. kernel-doc:: include/drm/drm_mipi_dbi.h
+ :internal:
+
+.. kernel-doc:: drivers/gpu/drm/drm_mipi_dbi.c
+ :export:
+
MIPI DSI Helper Functions Reference
===================================
diff --git a/Documentation/gpu/drm-mm.rst b/Documentation/gpu/drm-mm.rst
index c8ebd4f..b664f05 100644
--- a/Documentation/gpu/drm-mm.rst
+++ b/Documentation/gpu/drm-mm.rst
@@ -433,43 +433,11 @@
created for the OPTIMUS range of multi-gpu platforms. To userspace PRIME
buffers are dma-buf based file descriptors.
-Overview and Driver Interface
------------------------------
+Overview and Lifetime Rules
+---------------------------
-Similar to GEM global names, PRIME file descriptors are also used to
-share buffer objects across processes. They offer additional security:
-as file descriptors must be explicitly sent over UNIX domain sockets to
-be shared between applications, they can't be guessed like the globally
-unique GEM names.
-
-Drivers that support the PRIME API must set the DRIVER_PRIME bit in the
-struct :c:type:`struct drm_driver <drm_driver>`
-driver_features field, and implement the prime_handle_to_fd and
-prime_fd_to_handle operations.
-
-int (\*prime_handle_to_fd)(struct drm_device \*dev, struct drm_file
-\*file_priv, uint32_t handle, uint32_t flags, int \*prime_fd); int
-(\*prime_fd_to_handle)(struct drm_device \*dev, struct drm_file
-\*file_priv, int prime_fd, uint32_t \*handle); Those two operations
-convert a handle to a PRIME file descriptor and vice versa. Drivers must
-use the kernel dma-buf buffer sharing framework to manage the PRIME file
-descriptors. Similar to the mode setting API PRIME is agnostic to the
-underlying buffer object manager, as long as handles are 32bit unsigned
-integers.
-
-While non-GEM drivers must implement the operations themselves, GEM
-drivers must use the :c:func:`drm_gem_prime_handle_to_fd()` and
-:c:func:`drm_gem_prime_fd_to_handle()` helper functions. Those
-helpers rely on the driver gem_prime_export and gem_prime_import
-operations to create a dma-buf instance from a GEM object (dma-buf
-exporter role) and to create a GEM object from a dma-buf instance
-(dma-buf importer role).
-
-struct dma_buf \* (\*gem_prime_export)(struct drm_device \*dev,
-struct drm_gem_object \*obj, int flags); struct drm_gem_object \*
-(\*gem_prime_import)(struct drm_device \*dev, struct dma_buf
-\*dma_buf); These two operations are mandatory for GEM drivers that
-support PRIME.
+.. kernel-doc:: drivers/gpu/drm/drm_prime.c
+ :doc: overview and lifetime rules
PRIME Helper Functions
----------------------
diff --git a/Documentation/gpu/i915.rst b/Documentation/gpu/i915.rst
index c38ef0d..3415255 100644
--- a/Documentation/gpu/i915.rst
+++ b/Documentation/gpu/i915.rst
@@ -91,9 +91,6 @@
.. kernel-doc:: drivers/gpu/drm/i915/display/intel_frontbuffer.c
:internal:
-.. kernel-doc:: drivers/gpu/drm/i915/i915_gem.c
- :functions: i915_gem_track_fb
-
Display FIFO Underrun Reporting
-------------------------------
@@ -430,31 +427,31 @@
GuC
===
+Firmware Layout
+-------------------
+
+.. kernel-doc:: drivers/gpu/drm/i915/gt/uc/intel_uc_fw_abi.h
+ :doc: Firmware Layout
+
GuC-specific firmware loader
----------------------------
-.. kernel-doc:: drivers/gpu/drm/i915/intel_guc_fw.c
+.. kernel-doc:: drivers/gpu/drm/i915/gt/uc/intel_guc_fw.c
:internal:
GuC-based command submission
----------------------------
-.. kernel-doc:: drivers/gpu/drm/i915/intel_guc_submission.c
+.. kernel-doc:: drivers/gpu/drm/i915/gt/uc/intel_guc_submission.c
:doc: GuC-based command submission
-.. kernel-doc:: drivers/gpu/drm/i915/intel_guc_submission.c
+.. kernel-doc:: drivers/gpu/drm/i915/gt/uc/intel_guc_submission.c
:internal:
-GuC Firmware Layout
--------------------
-
-.. kernel-doc:: drivers/gpu/drm/i915/intel_guc_fwif.h
- :doc: GuC Firmware Layout
-
GuC Address Space
-----------------
-.. kernel-doc:: drivers/gpu/drm/i915/intel_guc.c
+.. kernel-doc:: drivers/gpu/drm/i915/gt/uc/intel_guc.c
:doc: GuC Address Space
Tracing
diff --git a/Documentation/gpu/introduction.rst b/Documentation/gpu/introduction.rst
index fccbe37..25a56e9 100644
--- a/Documentation/gpu/introduction.rst
+++ b/Documentation/gpu/introduction.rst
@@ -51,6 +51,22 @@
Also read the :ref:`guidelines for the kernel documentation at large <doc_guide>`.
+Documentation Requirements for kAPI
+-----------------------------------
+
+All kernel APIs exported to other modules must be documented, including their
+datastructures and at least a short introductory section explaining the overall
+concepts. Documentation should be put into the code itself as kerneldoc comments
+as much as reasonable.
+
+Do not blindly document everything, but document only what's relevant for driver
+authors: Internal functions of drm.ko and definitely static functions should not
+have formal kerneldoc comments. Use normal C comments if you feel like a comment
+is warranted. You may use kerneldoc syntax in the comment, but it shall not
+start with a /** kerneldoc marker. Similar for data structures, annotate
+anything entirely private with ``/* private: */`` comments as per the
+documentation guide.
+
Getting Started
===============
diff --git a/Documentation/gpu/tinydrm.rst b/Documentation/gpu/tinydrm.rst
deleted file mode 100644
index 33a4154..0000000
--- a/Documentation/gpu/tinydrm.rst
+++ /dev/null
@@ -1,30 +0,0 @@
-============================
-drm/tinydrm Tiny DRM drivers
-============================
-
-tinydrm is a collection of DRM drivers that are so small they can fit in a
-single source file.
-
-Helpers
-=======
-
-.. kernel-doc:: include/drm/tinydrm/tinydrm-helpers.h
- :internal:
-
-.. kernel-doc:: drivers/gpu/drm/tinydrm/core/tinydrm-helpers.c
- :export:
-
-.. kernel-doc:: drivers/gpu/drm/tinydrm/core/tinydrm-pipe.c
- :export:
-
-MIPI DBI Compatible Controllers
-===============================
-
-.. kernel-doc:: drivers/gpu/drm/tinydrm/mipi-dbi.c
- :doc: overview
-
-.. kernel-doc:: include/drm/tinydrm/mipi-dbi.h
- :internal:
-
-.. kernel-doc:: drivers/gpu/drm/tinydrm/mipi-dbi.c
- :export:
diff --git a/Documentation/gpu/todo.rst b/Documentation/gpu/todo.rst
index 0a49c5a..32787ac 100644
--- a/Documentation/gpu/todo.rst
+++ b/Documentation/gpu/todo.rst
@@ -162,7 +162,7 @@
A lot of drivers forward gem mmap calls to dma-buf mmap for imported buffers.
And also a lot of them forward dma-buf mmap to the gem mmap implementations.
-Would be great to refactor this all into a set of small common helpers.
+There's drm_gem_prime_mmap() for this now, but still needs to be rolled out.
Contact: Daniel Vetter
@@ -196,15 +196,6 @@
Contact: Daniel Vetter, Noralf Tronnes
-Remove the ->gem_prime_res_obj callback
---------------------------------------------
-
-The ->gem_prime_res_obj callback can be removed from drivers by using the
-reservation_object in the drm_gem_object. It may also be possible to use the
-generic drm_gem_reservation_object_wait helper for waiting for a bo.
-
-Contact: Daniel Vetter
-
idr_init_base()
---------------
@@ -215,22 +206,13 @@
Contact: Daniel Vetter
-Defaults for .gem_prime_import and export
------------------------------------------
-
-Most drivers don't need to set drm_driver->gem_prime_import and
-->gem_prime_export now that drm_gem_prime_import() and drm_gem_prime_export()
-are the default.
-
struct drm_gem_object_funcs
---------------------------
GEM objects can now have a function table instead of having the callbacks on the
DRM driver struct. This is now the preferred way and drivers can be moved over.
-DRM_GEM_CMA_VMAP_DRIVER_OPS, DRM_GEM_SHMEM_DRIVER_OPS already support this, but
-DRM_GEM_VRAM_DRIVER_PRIME does not yet and needs to be aligned with the previous
-two. We also need a 2nd version of the CMA define that doesn't require the
+We also need a 2nd version of the CMA define that doesn't require the
vmapping to be present (different hook for prime importing). Plus this needs to
be rolled out to all drivers using their own implementations, too.
@@ -317,19 +299,6 @@
Contact: Daniel Vetter
-Add missing kerneldoc for exported functions
---------------------------------------------
-
-The DRM reference documentation is still lacking kerneldoc in a few areas. The
-task would be to clean up interfaces like moving functions around between
-files to better group them and improving the interfaces like dropping return
-values for functions that never fail. Then write kerneldoc for all exported
-functions and an overview section and integrate it all into the drm book.
-
-See https://dri.freedesktop.org/docs/drm/ for what's there already.
-
-Contact: Daniel Vetter
-
Make panic handling work
------------------------
@@ -393,6 +362,9 @@
this (together with the drm_minor->drm_device move) would allow us to remove
debugfs_init.
+- Drop the return code and error checking from all debugfs functions. Greg KH is
+ working on this already.
+
Contact: Daniel Vetter
KMS cleanups
@@ -440,39 +412,22 @@
Contact: Daniel Vetter
+Backlight Refactoring
+---------------------
+
+Backlight drivers have a triple enable/disable state, which is a bit overkill.
+Plan to fix this:
+
+1. Roll out backlight_enable() and backlight_disable() helpers everywhere. This
+ has started already.
+2. In all, only look at one of the three status bits set by the above helpers.
+3. Remove the other two status bits.
+
+Contact: Daniel Vetter
+
Driver Specific
===============
-tinydrm
--------
-
-Tinydrm is the helper driver for really simple fb drivers. The goal is to make
-those drivers as simple as possible, so lots of room for refactoring:
-
-- backlight helpers, probably best to put them into a new drm_backlight.c.
- This is because drivers/video is de-facto unmaintained. We could also
- move drivers/video/backlight to drivers/gpu/backlight and take it all
- over within drm-misc, but that's more work. Backlight helpers require a fair
- bit of reworking and refactoring. A simple example is the enabling of a backlight.
- Tinydrm has helpers for this. It would be good if other drivers can also use the
- helper. However, there are various cases we need to consider i.e different
- drivers seem to have different ways of enabling/disabling a backlight.
- We also need to consider the backlight drivers (like gpio_backlight). The situation
- is further complicated by the fact that the backlight is tied to fbdev
- via fb_notifier_callback() which has complicated logic. For further details, refer
- to the following discussion thread:
- https://groups.google.com/forum/#!topic/outreachy-kernel/8rBe30lwtdA
-
-- spi helpers, probably best put into spi core/helper code. Thierry said
- the spi maintainer is fast&reactive, so shouldn't be a big issue.
-
-- extract the mipi-dbi helper (well, the non-tinydrm specific parts at
- least) into a separate helper, like we have for mipi-dsi already. Or follow
- one of the ideas for having a shared dsi/dbi helper, abstracting away the
- transport details more.
-
-Contact: Noralf Trønnes, Daniel Vetter
-
AMD DC Display Driver
---------------------
diff --git a/Documentation/hwmon/adm1021.rst b/Documentation/hwmon/adm1021.rst
index 6cbb0f7..116fb20 100644
--- a/Documentation/hwmon/adm1021.rst
+++ b/Documentation/hwmon/adm1021.rst
@@ -142,7 +142,7 @@
If nothing happens when loading the adm1021 module, and you are certain
that your specific Xeon processor model includes compatible sensors, you
will have to explicitly instantiate the sensor chips from user-space. See
-method 4 in Documentation/i2c/instantiating-devices. Possible slave
+method 4 in Documentation/i2c/instantiating-devices.rst. Possible slave
addresses are 0x18, 0x1a, 0x29, 0x2b, 0x4c, or 0x4e. It is likely that
only temp2 will be correct and temp1 will have to be ignored.
diff --git a/Documentation/hwmon/adm1275.rst b/Documentation/hwmon/adm1275.rst
index 9a1913e..49966ed 100644
--- a/Documentation/hwmon/adm1275.rst
+++ b/Documentation/hwmon/adm1275.rst
@@ -75,7 +75,7 @@
-----------
This driver does not auto-detect devices. You will have to instantiate the
-devices explicitly. Please see Documentation/i2c/instantiating-devices for
+devices explicitly. Please see Documentation/i2c/instantiating-devices.rst for
details.
The ADM1075, unlike many other PMBus devices, does not support internal voltage
diff --git a/Documentation/hwmon/ads1015.rst b/Documentation/hwmon/ads1015.rst
deleted file mode 100644
index e0951c4..0000000
--- a/Documentation/hwmon/ads1015.rst
+++ /dev/null
@@ -1,90 +0,0 @@
-Kernel driver ads1015
-=====================
-
-Supported chips:
-
- * Texas Instruments ADS1015
-
- Prefix: 'ads1015'
-
- Datasheet: Publicly available at the Texas Instruments website:
-
- http://focus.ti.com/lit/ds/symlink/ads1015.pdf
-
- * Texas Instruments ADS1115
-
- Prefix: 'ads1115'
-
- Datasheet: Publicly available at the Texas Instruments website:
-
- http://focus.ti.com/lit/ds/symlink/ads1115.pdf
-
-Authors:
- Dirk Eibach, Guntermann & Drunck GmbH <eibach@gdsys.de>
-
-Description
------------
-
-This driver implements support for the Texas Instruments ADS1015/ADS1115.
-
-This device is a 12/16-bit A-D converter with 4 inputs.
-
-The inputs can be used single ended or in certain differential combinations.
-
-The inputs can be made available by 8 sysfs input files in0_input - in7_input:
-
- - in0: Voltage over AIN0 and AIN1.
- - in1: Voltage over AIN0 and AIN3.
- - in2: Voltage over AIN1 and AIN3.
- - in3: Voltage over AIN2 and AIN3.
- - in4: Voltage over AIN0 and GND.
- - in5: Voltage over AIN1 and GND.
- - in6: Voltage over AIN2 and GND.
- - in7: Voltage over AIN3 and GND.
-
-Which inputs are available can be configured using platform data or devicetree.
-
-By default all inputs are exported.
-
-Platform Data
--------------
-
-In linux/platform_data/ads1015.h platform data is defined, channel_data contains
-configuration data for the used input combinations:
-
-- pga is the programmable gain amplifier (values are full scale)
-
- - 0: +/- 6.144 V
- - 1: +/- 4.096 V
- - 2: +/- 2.048 V
- - 3: +/- 1.024 V
- - 4: +/- 0.512 V
- - 5: +/- 0.256 V
-
-- data_rate in samples per second
-
- - 0: 128
- - 1: 250
- - 2: 490
- - 3: 920
- - 4: 1600
- - 5: 2400
- - 6: 3300
-
-Example::
-
- struct ads1015_platform_data data = {
- .channel_data = {
- [2] = { .enabled = true, .pga = 1, .data_rate = 0 },
- [4] = { .enabled = true, .pga = 4, .data_rate = 5 },
- }
- };
-
-In this case only in2_input (FS +/- 4.096 V, 128 SPS) and in4_input
-(FS +/- 0.512 V, 2400 SPS) would be created.
-
-Devicetree
-----------
-
-Configuration is also possible via devicetree:
-Documentation/devicetree/bindings/hwmon/ads1015.txt
diff --git a/Documentation/hwmon/hih6130.rst b/Documentation/hwmon/hih6130.rst
index 649bd4b..e95d373 100644
--- a/Documentation/hwmon/hih6130.rst
+++ b/Documentation/hwmon/hih6130.rst
@@ -27,7 +27,7 @@
I2C address 0x27 by default, so an entry with I2C_BOARD_INFO("hih6130", 0x27)
can be used in the board setup code.
-Please see Documentation/i2c/instantiating-devices for details on how to
+Please see Documentation/i2c/instantiating-devices.rst for details on how to
instantiate I2C devices.
sysfs-Interface
diff --git a/Documentation/hwmon/ibm-cffps.rst b/Documentation/hwmon/ibm-cffps.rst
index 52e74e39..ef8f3f8 100644
--- a/Documentation/hwmon/ibm-cffps.rst
+++ b/Documentation/hwmon/ibm-cffps.rst
@@ -17,7 +17,7 @@
-----------
This driver does not auto-detect devices. You will have to instantiate the
-devices explicitly. Please see Documentation/i2c/instantiating-devices for
+devices explicitly. Please see Documentation/i2c/instantiating-devices.rst for
details.
Sysfs entries
diff --git a/Documentation/hwmon/index.rst b/Documentation/hwmon/index.rst
index ee090e5..8147c3f 100644
--- a/Documentation/hwmon/index.rst
+++ b/Documentation/hwmon/index.rst
@@ -30,7 +30,6 @@
adm1031
adm1275
adm9240
- ads1015
ads7828
adt7410
adt7411
@@ -130,6 +129,7 @@
pcf8591
pmbus
powr1220
+ pxe1610
pwm-fan
raspberrypi-hwmon
sch5627
diff --git a/Documentation/hwmon/inspur-ipsps1.rst b/Documentation/hwmon/inspur-ipsps1.rst
new file mode 100644
index 0000000..2b871ae
--- /dev/null
+++ b/Documentation/hwmon/inspur-ipsps1.rst
@@ -0,0 +1,79 @@
+Kernel driver inspur-ipsps1
+=======================
+
+Supported chips:
+
+ * Inspur Power System power supply unit
+
+Author: John Wang <wangzqbj@inspur.com>
+
+Description
+-----------
+
+This driver supports Inspur Power System power supplies. This driver
+is a client to the core PMBus driver.
+
+Usage Notes
+-----------
+
+This driver does not auto-detect devices. You will have to instantiate the
+devices explicitly. Please see Documentation/i2c/instantiating-devices for
+details.
+
+Sysfs entries
+-------------
+
+The following attributes are supported:
+
+======================= ======================================================
+curr1_input Measured input current
+curr1_label "iin"
+curr1_max Maximum current
+curr1_max_alarm Current high alarm
+curr2_input Measured output current in mA.
+curr2_label "iout1"
+curr2_crit Critical maximum current
+curr2_crit_alarm Current critical high alarm
+curr2_max Maximum current
+curr2_max_alarm Current high alarm
+
+fan1_alarm Fan 1 warning.
+fan1_fault Fan 1 fault.
+fan1_input Fan 1 speed in RPM.
+
+in1_alarm Input voltage under-voltage alarm.
+in1_input Measured input voltage in mV.
+in1_label "vin"
+in2_input Measured output voltage in mV.
+in2_label "vout1"
+in2_lcrit Critical minimum output voltage
+in2_lcrit_alarm Output voltage critical low alarm
+in2_max Maximum output voltage
+in2_max_alarm Output voltage high alarm
+in2_min Minimum output voltage
+in2_min_alarm Output voltage low alarm
+
+power1_alarm Input fault or alarm.
+power1_input Measured input power in uW.
+power1_label "pin"
+power1_max Input power limit
+power2_max_alarm Output power high alarm
+power2_max Output power limit
+power2_input Measured output power in uW.
+power2_label "pout"
+
+temp[1-3]_input Measured temperature
+temp[1-2]_max Maximum temperature
+temp[1-3]_max_alarm Temperature high alarm
+
+vendor Manufacturer name
+model Product model
+part_number Product part number
+serial_number Product serial number
+fw_version Firmware version
+hw_version Hardware version
+mode Work mode. Can be set to active or
+ standby, when set to standby, PSU will
+ automatically switch between standby
+ and redundancy mode.
+======================= ======================================================
diff --git a/Documentation/hwmon/lm25066.rst b/Documentation/hwmon/lm25066.rst
index da15e30..30e6e77 100644
--- a/Documentation/hwmon/lm25066.rst
+++ b/Documentation/hwmon/lm25066.rst
@@ -76,7 +76,7 @@
-----------
This driver does not auto-detect devices. You will have to instantiate the
-devices explicitly. Please see Documentation/i2c/instantiating-devices for
+devices explicitly. Please see Documentation/i2c/instantiating-devices.rst for
details.
diff --git a/Documentation/hwmon/lm75.rst b/Documentation/hwmon/lm75.rst
index ba8acbd..e749f827 100644
--- a/Documentation/hwmon/lm75.rst
+++ b/Documentation/hwmon/lm75.rst
@@ -119,9 +119,9 @@
http://www.ti.com/product/tmp275
- * NXP LM75B
+ * NXP LM75B, PCT2075
- Prefix: 'lm75b'
+ Prefix: 'lm75b', 'pct2075'
Addresses scanned: none
@@ -129,6 +129,8 @@
http://www.nxp.com/documents/data_sheet/LM75B.pdf
+ http://www.nxp.com/docs/en/data-sheet/PCT2075.pdf
+
Author: Frodo Looijaard <frodol@dds.nl>
Description
diff --git a/Documentation/hwmon/max16064.rst b/Documentation/hwmon/max16064.rst
index 6d5e953..c062492 100644
--- a/Documentation/hwmon/max16064.rst
+++ b/Documentation/hwmon/max16064.rst
@@ -28,7 +28,7 @@
-----------
This driver does not auto-detect devices. You will have to instantiate the
-devices explicitly. Please see Documentation/i2c/instantiating-devices for
+devices explicitly. Please see Documentation/i2c/instantiating-devices.rst for
details.
diff --git a/Documentation/hwmon/max16065.rst b/Documentation/hwmon/max16065.rst
index fa5c852..45f69f3 100644
--- a/Documentation/hwmon/max16065.rst
+++ b/Documentation/hwmon/max16065.rst
@@ -79,7 +79,7 @@
This driver does not probe for devices, since there is no register which
can be safely used to identify the chip. You will have to instantiate
-the devices explicitly. Please see Documentation/i2c/instantiating-devices for
+the devices explicitly. Please see Documentation/i2c/instantiating-devices.rst for
details.
WARNING: Do not access chip registers using the i2cdump command, and do not use
diff --git a/Documentation/hwmon/max20751.rst b/Documentation/hwmon/max20751.rst
index aa4469b..fe701e0 100644
--- a/Documentation/hwmon/max20751.rst
+++ b/Documentation/hwmon/max20751.rst
@@ -30,7 +30,7 @@
-----------
This driver does not auto-detect devices. You will have to instantiate the
-devices explicitly. Please see Documentation/i2c/instantiating-devices for
+devices explicitly. Please see Documentation/i2c/instantiating-devices.rst for
details.
diff --git a/Documentation/hwmon/max34440.rst b/Documentation/hwmon/max34440.rst
index 939138e..5744df1 100644
--- a/Documentation/hwmon/max34440.rst
+++ b/Documentation/hwmon/max34440.rst
@@ -83,7 +83,7 @@
-----------
This driver does not auto-detect devices. You will have to instantiate the
-devices explicitly. Please see Documentation/i2c/instantiating-devices for
+devices explicitly. Please see Documentation/i2c/instantiating-devices.rst for
details.
For MAX34446, the value of the currX_crit attribute determines if current or
diff --git a/Documentation/hwmon/max6650.rst b/Documentation/hwmon/max6650.rst
index 253482a..7952b6e 100644
--- a/Documentation/hwmon/max6650.rst
+++ b/Documentation/hwmon/max6650.rst
@@ -55,7 +55,7 @@
-----------
This driver does not auto-detect devices. You will have to instantiate the
-devices explicitly. Please see Documentation/i2c/instantiating-devices for
+devices explicitly. Please see Documentation/i2c/instantiating-devices.rst for
details.
Module parameters
diff --git a/Documentation/hwmon/max8688.rst b/Documentation/hwmon/max8688.rst
index 0094877..71e7f2c 100644
--- a/Documentation/hwmon/max8688.rst
+++ b/Documentation/hwmon/max8688.rst
@@ -28,7 +28,7 @@
-----------
This driver does not auto-detect devices. You will have to instantiate the
-devices explicitly. Please see Documentation/i2c/instantiating-devices for
+devices explicitly. Please see Documentation/i2c/instantiating-devices.rst for
details.
diff --git a/Documentation/hwmon/menf21bmc.rst b/Documentation/hwmon/menf21bmc.rst
index 1f0c6b2..978691d 100644
--- a/Documentation/hwmon/menf21bmc.rst
+++ b/Documentation/hwmon/menf21bmc.rst
@@ -28,7 +28,7 @@
This driver is part of the MFD driver named "menf21bmc" and does
not auto-detect devices.
You will have to instantiate the MFD driver explicitly.
-Please see Documentation/i2c/instantiating-devices for
+Please see Documentation/i2c/instantiating-devices.rst for
details.
Sysfs entries
diff --git a/Documentation/hwmon/pcf8591.rst b/Documentation/hwmon/pcf8591.rst
index e98bd54..5c4e85f 100644
--- a/Documentation/hwmon/pcf8591.rst
+++ b/Documentation/hwmon/pcf8591.rst
@@ -68,7 +68,7 @@
The PCF8591 is plainly impossible to detect! Thus the driver won't even
try. You have to explicitly instantiate the device at the relevant
address (in the interval [0x48..0x4f]) either through platform data, or
-using the sysfs interface. See Documentation/i2c/instantiating-devices
+using the sysfs interface. See Documentation/i2c/instantiating-devices.rst
for details.
Directories are being created for each instantiated PCF8591:
diff --git a/Documentation/hwmon/pxe1610 b/Documentation/hwmon/pxe1610
deleted file mode 100644
index 211cede..0000000
--- a/Documentation/hwmon/pxe1610
+++ /dev/null
@@ -1,90 +0,0 @@
-Kernel driver pxe1610
-=====================
-
-Supported chips:
- * Infineon PXE1610
- Prefix: 'pxe1610'
- Addresses scanned: -
- Datasheet: Datasheet is not publicly available.
-
- * Infineon PXE1110
- Prefix: 'pxe1110'
- Addresses scanned: -
- Datasheet: Datasheet is not publicly available.
-
- * Infineon PXM1310
- Prefix: 'pxm1310'
- Addresses scanned: -
- Datasheet: Datasheet is not publicly available.
-
-Author: Vijay Khemka <vijaykhemka@fb.com>
-
-
-Description
------------
-
-PXE1610/PXE1110 are Multi-rail/Multiphase Digital Controllers
-and compliant to
- -- Intel VR13 DC-DC converter specifications.
- -- Intel SVID protocol.
-Used for Vcore power regulation for Intel VR13 based microprocessors
- -- Servers, Workstations, and High-end desktops
-
-PXM1310 is a Multi-rail Controller and it is compliant to
- -- Intel VR13 DC-DC converter specifications.
- -- Intel SVID protocol.
-Used for DDR3/DDR4 Memory power regulation for Intel VR13 and
-IMVP8 based systems
-
-
-Usage Notes
------------
-
-This driver does not probe for PMBus devices. You will have
-to instantiate devices explicitly.
-
-Example: the following commands will load the driver for an PXE1610
-at address 0x70 on I2C bus #4:
-
-# modprobe pxe1610
-# echo pxe1610 0x70 > /sys/bus/i2c/devices/i2c-4/new_device
-
-It can also be instantiated by declaring in device tree
-
-
-Sysfs attributes
-----------------
-
-curr1_label "iin"
-curr1_input Measured input current
-curr1_alarm Current high alarm
-
-curr[2-4]_label "iout[1-3]"
-curr[2-4]_input Measured output current
-curr[2-4]_crit Critical maximum current
-curr[2-4]_crit_alarm Current critical high alarm
-
-in1_label "vin"
-in1_input Measured input voltage
-in1_crit Critical maximum input voltage
-in1_crit_alarm Input voltage critical high alarm
-
-in[2-4]_label "vout[1-3]"
-in[2-4]_input Measured output voltage
-in[2-4]_lcrit Critical minimum output voltage
-in[2-4]_lcrit_alarm Output voltage critical low alarm
-in[2-4]_crit Critical maximum output voltage
-in[2-4]_crit_alarm Output voltage critical high alarm
-
-power1_label "pin"
-power1_input Measured input power
-power1_alarm Input power high alarm
-
-power[2-4]_label "pout[1-3]"
-power[2-4]_input Measured output power
-
-temp[1-3]_input Measured temperature
-temp[1-3]_crit Critical high temperature
-temp[1-3]_crit_alarm Chip temperature critical high alarm
-temp[1-3]_max Maximum temperature
-temp[1-3]_max_alarm Chip temperature high alarm
diff --git a/Documentation/hwmon/pxe1610.rst b/Documentation/hwmon/pxe1610.rst
new file mode 100644
index 0000000..4f23888
--- /dev/null
+++ b/Documentation/hwmon/pxe1610.rst
@@ -0,0 +1,107 @@
+Kernel driver pxe1610
+=====================
+
+Supported chips:
+
+ * Infineon PXE1610
+
+ Prefix: 'pxe1610'
+
+ Addresses scanned: -
+
+ Datasheet: Datasheet is not publicly available.
+
+ * Infineon PXE1110
+
+ Prefix: 'pxe1110'
+
+ Addresses scanned: -
+
+ Datasheet: Datasheet is not publicly available.
+
+ * Infineon PXM1310
+
+ Prefix: 'pxm1310'
+
+ Addresses scanned: -
+
+ Datasheet: Datasheet is not publicly available.
+
+Author: Vijay Khemka <vijaykhemka@fb.com>
+
+
+Description
+-----------
+
+PXE1610/PXE1110 are Multi-rail/Multiphase Digital Controllers
+and compliant to
+
+ - Intel VR13 DC-DC converter specifications.
+ - Intel SVID protocol.
+
+Used for Vcore power regulation for Intel VR13 based microprocessors
+
+ - Servers, Workstations, and High-end desktops
+
+PXM1310 is a Multi-rail Controller and it is compliant to
+
+ - Intel VR13 DC-DC converter specifications.
+ - Intel SVID protocol.
+
+Used for DDR3/DDR4 Memory power regulation for Intel VR13 and
+IMVP8 based systems
+
+
+Usage Notes
+-----------
+
+This driver does not probe for PMBus devices. You will have
+to instantiate devices explicitly.
+
+Example: the following commands will load the driver for an PXE1610
+at address 0x70 on I2C bus #4::
+
+ # modprobe pxe1610
+ # echo pxe1610 0x70 > /sys/bus/i2c/devices/i2c-4/new_device
+
+It can also be instantiated by declaring in device tree
+
+
+Sysfs attributes
+----------------
+
+====================== ====================================
+curr1_label "iin"
+curr1_input Measured input current
+curr1_alarm Current high alarm
+
+curr[2-4]_label "iout[1-3]"
+curr[2-4]_input Measured output current
+curr[2-4]_crit Critical maximum current
+curr[2-4]_crit_alarm Current critical high alarm
+
+in1_label "vin"
+in1_input Measured input voltage
+in1_crit Critical maximum input voltage
+in1_crit_alarm Input voltage critical high alarm
+
+in[2-4]_label "vout[1-3]"
+in[2-4]_input Measured output voltage
+in[2-4]_lcrit Critical minimum output voltage
+in[2-4]_lcrit_alarm Output voltage critical low alarm
+in[2-4]_crit Critical maximum output voltage
+in[2-4]_crit_alarm Output voltage critical high alarm
+
+power1_label "pin"
+power1_input Measured input power
+power1_alarm Input power high alarm
+
+power[2-4]_label "pout[1-3]"
+power[2-4]_input Measured output power
+
+temp[1-3]_input Measured temperature
+temp[1-3]_crit Critical high temperature
+temp[1-3]_crit_alarm Chip temperature critical high alarm
+temp[1-3]_max Maximum temperature
+temp[1-3]_max_alarm Chip temperature high alarm
+====================== ====================================
diff --git a/Documentation/hwmon/sht3x.rst b/Documentation/hwmon/sht3x.rst
index 978a711..95a850d 100644
--- a/Documentation/hwmon/sht3x.rst
+++ b/Documentation/hwmon/sht3x.rst
@@ -26,7 +26,7 @@
The device communicates with the I2C protocol. Sensors can have the I2C
addresses 0x44 or 0x45, depending on the wiring. See
-Documentation/i2c/instantiating-devices for methods to instantiate the device.
+Documentation/i2c/instantiating-devices.rst for methods to instantiate the device.
There are two options configurable by means of sht3x_platform_data:
diff --git a/Documentation/hwmon/shtc1.rst b/Documentation/hwmon/shtc1.rst
index aa11633..08380f2 100644
--- a/Documentation/hwmon/shtc1.rst
+++ b/Documentation/hwmon/shtc1.rst
@@ -19,7 +19,17 @@
Addresses scanned: none
- Datasheet: Not publicly available
+ Datasheet: http://www.sensirion.com/file/datasheet_shtw1
+
+
+
+ * Sensirion SHTC3
+
+ Prefix: 'shtc3'
+
+ Addresses scanned: none
+
+ Datasheet: http://www.sensirion.com/file/datasheet_shtc3
@@ -30,13 +40,12 @@
Description
-----------
-This driver implements support for the Sensirion SHTC1 chip, a humidity and
-temperature sensor. Temperature is measured in degrees celsius, relative
-humidity is expressed as a percentage. Driver can be used as well for SHTW1
-chip, which has the same electrical interface.
+This driver implements support for the Sensirion SHTC1, SHTW1, and SHTC3
+chips, a humidity and temperature sensor. Temperature is measured in degrees
+celsius, relative humidity is expressed as a percentage.
The device communicates with the I2C protocol. All sensors are set to I2C
-address 0x70. See Documentation/i2c/instantiating-devices for methods to
+address 0x70. See Documentation/i2c/instantiating-devices.rst for methods to
instantiate the device.
There are two options configurable by means of shtc1_platform_data:
diff --git a/Documentation/hwmon/submitting-patches.rst b/Documentation/hwmon/submitting-patches.rst
index 452fc28..9a218ea 100644
--- a/Documentation/hwmon/submitting-patches.rst
+++ b/Documentation/hwmon/submitting-patches.rst
@@ -20,6 +20,10 @@
errors, no warnings, and few if any check messages. If there are any
messages, please be prepared to explain.
+* Please use the standard multi-line comment style. Do not mix C and C++
+ style comments in a single driver (with the exception of the SPDX license
+ identifier).
+
* If your patch generates checkpatch errors, warnings, or check messages,
please refrain from explanations such as "I prefer that coding style".
Keep in mind that each unnecessary message helps hiding a real problem,
@@ -120,8 +124,8 @@
completely initialize your chip and your driver first, then register with
the hwmon subsystem.
-* Use devm_hwmon_device_register_with_groups() or, if your driver needs a remove
- function, hwmon_device_register_with_groups() to register your driver with the
+* Use devm_hwmon_device_register_with_info() or, if your driver needs a remove
+ function, hwmon_device_register_with_info() to register your driver with the
hwmon subsystem. Try using devm_add_action() instead of a remove function if
possible. Do not use hwmon_device_register().
diff --git a/Documentation/hwmon/tmp103.rst b/Documentation/hwmon/tmp103.rst
index 15d25806..205de61 100644
--- a/Documentation/hwmon/tmp103.rst
+++ b/Documentation/hwmon/tmp103.rst
@@ -30,4 +30,4 @@
Documentation/hwmon/sysfs-interface.rst under Temperatures).
Please refer how to instantiate this driver:
-Documentation/i2c/instantiating-devices
+Documentation/i2c/instantiating-devices.rst
diff --git a/Documentation/hwmon/tps40422.rst b/Documentation/hwmon/tps40422.rst
index b691e30..8fe3e1c 100644
--- a/Documentation/hwmon/tps40422.rst
+++ b/Documentation/hwmon/tps40422.rst
@@ -28,7 +28,7 @@
-----------
This driver does not auto-detect devices. You will have to instantiate the
-devices explicitly. Please see Documentation/i2c/instantiating-devices for
+devices explicitly. Please see Documentation/i2c/instantiating-devices.rst for
details.
diff --git a/Documentation/hwmon/ucd9000.rst b/Documentation/hwmon/ucd9000.rst
index ebc4f2b..746f21f 100644
--- a/Documentation/hwmon/ucd9000.rst
+++ b/Documentation/hwmon/ucd9000.rst
@@ -64,7 +64,7 @@
-----------
This driver does not auto-detect devices. You will have to instantiate the
-devices explicitly. Please see Documentation/i2c/instantiating-devices for
+devices explicitly. Please see Documentation/i2c/instantiating-devices.rst for
details.
diff --git a/Documentation/hwmon/ucd9200.rst b/Documentation/hwmon/ucd9200.rst
index b819dfd..4f0e7c3 100644
--- a/Documentation/hwmon/ucd9200.rst
+++ b/Documentation/hwmon/ucd9200.rst
@@ -40,7 +40,7 @@
-----------
This driver does not auto-detect devices. You will have to instantiate the
-devices explicitly. Please see Documentation/i2c/instantiating-devices for
+devices explicitly. Please see Documentation/i2c/instantiating-devices.rst for
details.
diff --git a/Documentation/hwmon/via686a.rst b/Documentation/hwmon/via686a.rst
index a343c35..7ab9dde 100644
--- a/Documentation/hwmon/via686a.rst
+++ b/Documentation/hwmon/via686a.rst
@@ -40,7 +40,7 @@
The Via 686a southbridge has integrated hardware monitor functionality.
It also has an I2C bus, but this driver only supports the hardware monitor.
-For the I2C bus driver, see <file:Documentation/i2c/busses/i2c-viapro>
+For the I2C bus driver, see <file:Documentation/i2c/busses/i2c-viapro.rst>
The Via 686a implements three temperature sensors, two fan rotation speed
sensors, five voltage sensors and alarms.
diff --git a/Documentation/hwmon/zl6100.rst b/Documentation/hwmon/zl6100.rst
index 41513bb..968aff1 100644
--- a/Documentation/hwmon/zl6100.rst
+++ b/Documentation/hwmon/zl6100.rst
@@ -121,7 +121,7 @@
-----------
This driver does not auto-detect devices. You will have to instantiate the
-devices explicitly. Please see Documentation/i2c/instantiating-devices for
+devices explicitly. Please see Documentation/i2c/instantiating-devices.rst for
details.
.. warning::
diff --git a/Documentation/i2c/busses/i2c-ali1535 b/Documentation/i2c/busses/i2c-ali1535
deleted file mode 100644
index 5d46342..0000000
--- a/Documentation/i2c/busses/i2c-ali1535
+++ /dev/null
@@ -1,42 +0,0 @@
-Kernel driver i2c-ali1535
-
-Supported adapters:
- * Acer Labs, Inc. ALI 1535 (south bridge)
- Datasheet: Now under NDA
- http://www.ali.com.tw/
-
-Authors:
- Frodo Looijaard <frodol@dds.nl>,
- Philip Edelbrock <phil@netroedge.com>,
- Mark D. Studebaker <mdsxyz123@yahoo.com>,
- Dan Eaton <dan.eaton@rocketlogix.com>,
- Stephen Rousset<stephen.rousset@rocketlogix.com>
-
-Description
------------
-
-This is the driver for the SMB Host controller on Acer Labs Inc. (ALI)
-M1535 South Bridge.
-
-The M1535 is a South bridge for portable systems. It is very similar to the
-M15x3 South bridges also produced by Acer Labs Inc. Some of the registers
-within the part have moved and some have been redefined slightly.
-Additionally, the sequencing of the SMBus transactions has been modified to
-be more consistent with the sequencing recommended by the manufacturer and
-observed through testing. These changes are reflected in this driver and
-can be identified by comparing this driver to the i2c-ali15x3 driver. For
-an overview of these chips see http://www.acerlabs.com
-
-The SMB controller is part of the M7101 device, which is an ACPI-compliant
-Power Management Unit (PMU).
-
-The whole M7101 device has to be enabled for the SMB to work. You can't
-just enable the SMB alone. The SMB and the ACPI have separate I/O spaces.
-We make sure that the SMB is enabled. We leave the ACPI alone.
-
-
-Features
---------
-
-This driver controls the SMB Host only. This driver does not use
-interrupts.
diff --git a/Documentation/i2c/busses/i2c-ali1535.rst b/Documentation/i2c/busses/i2c-ali1535.rst
new file mode 100644
index 0000000..6941064
--- /dev/null
+++ b/Documentation/i2c/busses/i2c-ali1535.rst
@@ -0,0 +1,45 @@
+=========================
+Kernel driver i2c-ali1535
+=========================
+
+Supported adapters:
+ * Acer Labs, Inc. ALI 1535 (south bridge)
+
+ Datasheet: Now under NDA
+ http://www.ali.com.tw/
+
+Authors:
+ - Frodo Looijaard <frodol@dds.nl>,
+ - Philip Edelbrock <phil@netroedge.com>,
+ - Mark D. Studebaker <mdsxyz123@yahoo.com>,
+ - Dan Eaton <dan.eaton@rocketlogix.com>,
+ - Stephen Rousset<stephen.rousset@rocketlogix.com>
+
+Description
+-----------
+
+This is the driver for the SMB Host controller on Acer Labs Inc. (ALI)
+M1535 South Bridge.
+
+The M1535 is a South bridge for portable systems. It is very similar to the
+M15x3 South bridges also produced by Acer Labs Inc. Some of the registers
+within the part have moved and some have been redefined slightly.
+Additionally, the sequencing of the SMBus transactions has been modified to
+be more consistent with the sequencing recommended by the manufacturer and
+observed through testing. These changes are reflected in this driver and
+can be identified by comparing this driver to the i2c-ali15x3 driver. For
+an overview of these chips see http://www.acerlabs.com
+
+The SMB controller is part of the M7101 device, which is an ACPI-compliant
+Power Management Unit (PMU).
+
+The whole M7101 device has to be enabled for the SMB to work. You can't
+just enable the SMB alone. The SMB and the ACPI have separate I/O spaces.
+We make sure that the SMB is enabled. We leave the ACPI alone.
+
+
+Features
+--------
+
+This driver controls the SMB Host only. This driver does not use
+interrupts.
diff --git a/Documentation/i2c/busses/i2c-ali1563 b/Documentation/i2c/busses/i2c-ali1563
deleted file mode 100644
index 41b1a07..0000000
--- a/Documentation/i2c/busses/i2c-ali1563
+++ /dev/null
@@ -1,27 +0,0 @@
-Kernel driver i2c-ali1563
-
-Supported adapters:
- * Acer Labs, Inc. ALI 1563 (south bridge)
- Datasheet: Now under NDA
- http://www.ali.com.tw/
-
-Author: Patrick Mochel <mochel@digitalimplant.org>
-
-Description
------------
-
-This is the driver for the SMB Host controller on Acer Labs Inc. (ALI)
-M1563 South Bridge.
-
-For an overview of these chips see http://www.acerlabs.com
-
-The M1563 southbridge is deceptively similar to the M1533, with a few
-notable exceptions. One of those happens to be the fact they upgraded the
-i2c core to be SMBus 2.0 compliant, and happens to be almost identical to
-the i2c controller found in the Intel 801 south bridges.
-
-Features
---------
-
-This driver controls the SMB Host only. This driver does not use
-interrupts.
diff --git a/Documentation/i2c/busses/i2c-ali1563.rst b/Documentation/i2c/busses/i2c-ali1563.rst
new file mode 100644
index 0000000..eec32c3
--- /dev/null
+++ b/Documentation/i2c/busses/i2c-ali1563.rst
@@ -0,0 +1,30 @@
+=========================
+Kernel driver i2c-ali1563
+=========================
+
+Supported adapters:
+ * Acer Labs, Inc. ALI 1563 (south bridge)
+
+ Datasheet: Now under NDA
+ http://www.ali.com.tw/
+
+Author: Patrick Mochel <mochel@digitalimplant.org>
+
+Description
+-----------
+
+This is the driver for the SMB Host controller on Acer Labs Inc. (ALI)
+M1563 South Bridge.
+
+For an overview of these chips see http://www.acerlabs.com
+
+The M1563 southbridge is deceptively similar to the M1533, with a few
+notable exceptions. One of those happens to be the fact they upgraded the
+i2c core to be SMBus 2.0 compliant, and happens to be almost identical to
+the i2c controller found in the Intel 801 south bridges.
+
+Features
+--------
+
+This driver controls the SMB Host only. This driver does not use
+interrupts.
diff --git a/Documentation/i2c/busses/i2c-ali15x3 b/Documentation/i2c/busses/i2c-ali15x3
deleted file mode 100644
index 42888d8..0000000
--- a/Documentation/i2c/busses/i2c-ali15x3
+++ /dev/null
@@ -1,112 +0,0 @@
-Kernel driver i2c-ali15x3
-
-Supported adapters:
- * Acer Labs, Inc. ALI 1533 and 1543C (south bridge)
- Datasheet: Now under NDA
- http://www.ali.com.tw/
-
-Authors:
- Frodo Looijaard <frodol@dds.nl>,
- Philip Edelbrock <phil@netroedge.com>,
- Mark D. Studebaker <mdsxyz123@yahoo.com>
-
-Module Parameters
------------------
-
-* force_addr: int
- Initialize the base address of the i2c controller
-
-
-Notes
------
-
-The force_addr parameter is useful for boards that don't set the address in
-the BIOS. Does not do a PCI force; the device must still be present in
-lspci. Don't use this unless the driver complains that the base address is
-not set.
-
-Example: 'modprobe i2c-ali15x3 force_addr=0xe800'
-
-SMBus periodically hangs on ASUS P5A motherboards and can only be cleared
-by a power cycle. Cause unknown (see Issues below).
-
-
-Description
------------
-
-This is the driver for the SMB Host controller on Acer Labs Inc. (ALI)
-M1541 and M1543C South Bridges.
-
-The M1543C is a South bridge for desktop systems.
-The M1541 is a South bridge for portable systems.
-They are part of the following ALI chipsets:
-
- * "Aladdin Pro 2" includes the M1621 Slot 1 North bridge with AGP and
- 100MHz CPU Front Side bus
- * "Aladdin V" includes the M1541 Socket 7 North bridge with AGP and 100MHz
- CPU Front Side bus
- Some Aladdin V motherboards:
- Asus P5A
- Atrend ATC-5220
- BCM/GVC VP1541
- Biostar M5ALA
- Gigabyte GA-5AX (** Generally doesn't work because the BIOS doesn't
- enable the 7101 device! **)
- Iwill XA100 Plus
- Micronics C200
- Microstar (MSI) MS-5169
-
- * "Aladdin IV" includes the M1541 Socket 7 North bridge
- with host bus up to 83.3 MHz.
-
-For an overview of these chips see http://www.acerlabs.com. At this time the
-full data sheets on the web site are password protected, however if you
-contact the ALI office in San Jose they may give you the password.
-
-The M1533/M1543C devices appear as FOUR separate devices on the PCI bus. An
-output of lspci will show something similar to the following:
-
- 00:02.0 USB Controller: Acer Laboratories Inc. M5237 (rev 03)
- 00:03.0 Bridge: Acer Laboratories Inc. M7101 <= THIS IS THE ONE WE NEED
- 00:07.0 ISA bridge: Acer Laboratories Inc. M1533 (rev c3)
- 00:0f.0 IDE interface: Acer Laboratories Inc. M5229 (rev c1)
-
-** IMPORTANT **
-** If you have a M1533 or M1543C on the board and you get
-** "ali15x3: Error: Can't detect ali15x3!"
-** then run lspci.
-** If you see the 1533 and 5229 devices but NOT the 7101 device,
-** then you must enable ACPI, the PMU, SMB, or something similar
-** in the BIOS.
-** The driver won't work if it can't find the M7101 device.
-
-The SMB controller is part of the M7101 device, which is an ACPI-compliant
-Power Management Unit (PMU).
-
-The whole M7101 device has to be enabled for the SMB to work. You can't
-just enable the SMB alone. The SMB and the ACPI have separate I/O spaces.
-We make sure that the SMB is enabled. We leave the ACPI alone.
-
-Features
---------
-
-This driver controls the SMB Host only. The SMB Slave
-controller on the M15X3 is not enabled. This driver does not use
-interrupts.
-
-
-Issues
-------
-
-This driver requests the I/O space for only the SMB
-registers. It doesn't use the ACPI region.
-
-On the ASUS P5A motherboard, there are several reports that
-the SMBus will hang and this can only be resolved by
-powering off the computer. It appears to be worse when the board
-gets hot, for example under heavy CPU load, or in the summer.
-There may be electrical problems on this board.
-On the P5A, the W83781D sensor chip is on both the ISA and
-SMBus. Therefore the SMBus hangs can generally be avoided
-by accessing the W83781D on the ISA bus only.
-
diff --git a/Documentation/i2c/busses/i2c-ali15x3.rst b/Documentation/i2c/busses/i2c-ali15x3.rst
new file mode 100644
index 0000000..d4c1a2a
--- /dev/null
+++ b/Documentation/i2c/busses/i2c-ali15x3.rst
@@ -0,0 +1,122 @@
+=========================
+Kernel driver i2c-ali15x3
+=========================
+
+Supported adapters:
+ * Acer Labs, Inc. ALI 1533 and 1543C (south bridge)
+
+ Datasheet: Now under NDA
+ http://www.ali.com.tw/
+
+Authors:
+ - Frodo Looijaard <frodol@dds.nl>,
+ - Philip Edelbrock <phil@netroedge.com>,
+ - Mark D. Studebaker <mdsxyz123@yahoo.com>
+
+Module Parameters
+-----------------
+
+* force_addr: int
+ Initialize the base address of the i2c controller
+
+
+Notes
+-----
+
+The force_addr parameter is useful for boards that don't set the address in
+the BIOS. Does not do a PCI force; the device must still be present in
+lspci. Don't use this unless the driver complains that the base address is
+not set.
+
+Example::
+
+ modprobe i2c-ali15x3 force_addr=0xe800
+
+SMBus periodically hangs on ASUS P5A motherboards and can only be cleared
+by a power cycle. Cause unknown (see Issues below).
+
+
+Description
+-----------
+
+This is the driver for the SMB Host controller on Acer Labs Inc. (ALI)
+M1541 and M1543C South Bridges.
+
+The M1543C is a South bridge for desktop systems.
+
+The M1541 is a South bridge for portable systems.
+
+They are part of the following ALI chipsets:
+
+ * "Aladdin Pro 2" includes the M1621 Slot 1 North bridge with AGP and
+ 100MHz CPU Front Side bus
+ * "Aladdin V" includes the M1541 Socket 7 North bridge with AGP and 100MHz
+ CPU Front Side bus
+
+ Some Aladdin V motherboards:
+ - Asus P5A
+ - Atrend ATC-5220
+ - BCM/GVC VP1541
+ - Biostar M5ALA
+ - Gigabyte GA-5AX (Generally doesn't work because the BIOS doesn't
+ enable the 7101 device!)
+ - Iwill XA100 Plus
+ - Micronics C200
+ - Microstar (MSI) MS-5169
+
+ * "Aladdin IV" includes the M1541 Socket 7 North bridge
+ with host bus up to 83.3 MHz.
+
+For an overview of these chips see http://www.acerlabs.com. At this time the
+full data sheets on the web site are password protected, however if you
+contact the ALI office in San Jose they may give you the password.
+
+The M1533/M1543C devices appear as FOUR separate devices on the PCI bus. An
+output of lspci will show something similar to the following::
+
+ 00:02.0 USB Controller: Acer Laboratories Inc. M5237 (rev 03)
+ 00:03.0 Bridge: Acer Laboratories Inc. M7101 <= THIS IS THE ONE WE NEED
+ 00:07.0 ISA bridge: Acer Laboratories Inc. M1533 (rev c3)
+ 00:0f.0 IDE interface: Acer Laboratories Inc. M5229 (rev c1)
+
+.. important::
+
+ If you have a M1533 or M1543C on the board and you get
+ "ali15x3: Error: Can't detect ali15x3!"
+ then run lspci.
+
+ If you see the 1533 and 5229 devices but NOT the 7101 device,
+ then you must enable ACPI, the PMU, SMB, or something similar
+ in the BIOS.
+
+ The driver won't work if it can't find the M7101 device.
+
+The SMB controller is part of the M7101 device, which is an ACPI-compliant
+Power Management Unit (PMU).
+
+The whole M7101 device has to be enabled for the SMB to work. You can't
+just enable the SMB alone. The SMB and the ACPI have separate I/O spaces.
+We make sure that the SMB is enabled. We leave the ACPI alone.
+
+Features
+--------
+
+This driver controls the SMB Host only. The SMB Slave
+controller on the M15X3 is not enabled. This driver does not use
+interrupts.
+
+
+Issues
+------
+
+This driver requests the I/O space for only the SMB
+registers. It doesn't use the ACPI region.
+
+On the ASUS P5A motherboard, there are several reports that
+the SMBus will hang and this can only be resolved by
+powering off the computer. It appears to be worse when the board
+gets hot, for example under heavy CPU load, or in the summer.
+There may be electrical problems on this board.
+On the P5A, the W83781D sensor chip is on both the ISA and
+SMBus. Therefore the SMBus hangs can generally be avoided
+by accessing the W83781D on the ISA bus only.
diff --git a/Documentation/i2c/busses/i2c-amd-mp2 b/Documentation/i2c/busses/i2c-amd-mp2
deleted file mode 100644
index 6571487..0000000
--- a/Documentation/i2c/busses/i2c-amd-mp2
+++ /dev/null
@@ -1,23 +0,0 @@
-Kernel driver i2c-amd-mp2
-
-Supported adapters:
- * AMD MP2 PCIe interface
-
-Datasheet: not publicly available.
-
-Authors:
- Shyam Sundar S K <Shyam-sundar.S-k@amd.com>
- Nehal Shah <nehal-bakulchandra.shah@amd.com>
- Elie Morisse <syniurge@gmail.com>
-
-Description
------------
-
-The MP2 is an ARM processor programmed as an I2C controller and communicating
-with the x86 host through PCI.
-
-If you see something like this:
-
-03:00.7 MP2 I2C controller: Advanced Micro Devices, Inc. [AMD] Device 15e6
-
-in your 'lspci -v', then this driver is for your device.
diff --git a/Documentation/i2c/busses/i2c-amd-mp2.rst b/Documentation/i2c/busses/i2c-amd-mp2.rst
new file mode 100644
index 0000000..ebc2fa8
--- /dev/null
+++ b/Documentation/i2c/busses/i2c-amd-mp2.rst
@@ -0,0 +1,25 @@
+=========================
+Kernel driver i2c-amd-mp2
+=========================
+
+Supported adapters:
+ * AMD MP2 PCIe interface
+
+Datasheet: not publicly available.
+
+Authors:
+ - Shyam Sundar S K <Shyam-sundar.S-k@amd.com>
+ - Nehal Shah <nehal-bakulchandra.shah@amd.com>
+ - Elie Morisse <syniurge@gmail.com>
+
+Description
+-----------
+
+The MP2 is an ARM processor programmed as an I2C controller and communicating
+with the x86 host through PCI.
+
+If you see something like this::
+
+ 03:00.7 MP2 I2C controller: Advanced Micro Devices, Inc. [AMD] Device 15e6
+
+in your ``lspci -v``, then this driver is for your device.
diff --git a/Documentation/i2c/busses/i2c-amd756 b/Documentation/i2c/busses/i2c-amd756
deleted file mode 100644
index 67f3087..0000000
--- a/Documentation/i2c/busses/i2c-amd756
+++ /dev/null
@@ -1,25 +0,0 @@
-Kernel driver i2c-amd756
-
-Supported adapters:
- * AMD 756
- * AMD 766
- * AMD 768
- * AMD 8111
- Datasheets: Publicly available on AMD website
-
- * nVidia nForce
- Datasheet: Unavailable
-
-Authors:
- Frodo Looijaard <frodol@dds.nl>,
- Philip Edelbrock <phil@netroedge.com>
-
-Description
------------
-
-This driver supports the AMD 756, 766, 768 and 8111 Peripheral Bus
-Controllers, and the nVidia nForce.
-
-Note that for the 8111, there are two SMBus adapters. The SMBus 1.0 adapter
-is supported by this driver, and the SMBus 2.0 adapter is supported by the
-i2c-amd8111 driver.
diff --git a/Documentation/i2c/busses/i2c-amd756.rst b/Documentation/i2c/busses/i2c-amd756.rst
new file mode 100644
index 0000000..bc93f39
--- /dev/null
+++ b/Documentation/i2c/busses/i2c-amd756.rst
@@ -0,0 +1,29 @@
+========================
+Kernel driver i2c-amd756
+========================
+
+Supported adapters:
+ * AMD 756
+ * AMD 766
+ * AMD 768
+ * AMD 8111
+
+ Datasheets: Publicly available on AMD website
+
+ * nVidia nForce
+
+ Datasheet: Unavailable
+
+Authors:
+ - Frodo Looijaard <frodol@dds.nl>,
+ - Philip Edelbrock <phil@netroedge.com>
+
+Description
+-----------
+
+This driver supports the AMD 756, 766, 768 and 8111 Peripheral Bus
+Controllers, and the nVidia nForce.
+
+Note that for the 8111, there are two SMBus adapters. The SMBus 1.0 adapter
+is supported by this driver, and the SMBus 2.0 adapter is supported by the
+i2c-amd8111 driver.
diff --git a/Documentation/i2c/busses/i2c-amd8111 b/Documentation/i2c/busses/i2c-amd8111
deleted file mode 100644
index 460dd66..0000000
--- a/Documentation/i2c/busses/i2c-amd8111
+++ /dev/null
@@ -1,41 +0,0 @@
-Kernel driver i2c-adm8111
-
-Supported adapters:
- * AMD-8111 SMBus 2.0 PCI interface
-
-Datasheets:
- AMD datasheet not yet available, but almost everything can be found
- in the publicly available ACPI 2.0 specification, which the adapter
- follows.
-
-Author: Vojtech Pavlik <vojtech@suse.cz>
-
-Description
------------
-
-If you see something like this:
-
-00:07.2 SMBus: Advanced Micro Devices [AMD] AMD-8111 SMBus 2.0 (rev 02)
- Subsystem: Advanced Micro Devices [AMD] AMD-8111 SMBus 2.0
- Flags: medium devsel, IRQ 19
- I/O ports at d400 [size=32]
-
-in your 'lspci -v', then this driver is for your chipset.
-
-Process Call Support
---------------------
-
-Supported.
-
-SMBus 2.0 Support
------------------
-
-Supported. Both PEC and block process call support is implemented. Slave
-mode or host notification are not yet implemented.
-
-Notes
------
-
-Note that for the 8111, there are two SMBus adapters. The SMBus 2.0 adapter
-is supported by this driver, and the SMBus 1.0 adapter is supported by the
-i2c-amd756 driver.
diff --git a/Documentation/i2c/busses/i2c-amd8111.rst b/Documentation/i2c/busses/i2c-amd8111.rst
new file mode 100644
index 0000000..d08bf0a
--- /dev/null
+++ b/Documentation/i2c/busses/i2c-amd8111.rst
@@ -0,0 +1,43 @@
+=========================
+Kernel driver i2c-adm8111
+=========================
+
+Supported adapters:
+ * AMD-8111 SMBus 2.0 PCI interface
+
+Datasheets:
+ AMD datasheet not yet available, but almost everything can be found
+ in the publicly available ACPI 2.0 specification, which the adapter
+ follows.
+
+Author: Vojtech Pavlik <vojtech@suse.cz>
+
+Description
+-----------
+
+If you see something like this::
+
+ 00:07.2 SMBus: Advanced Micro Devices [AMD] AMD-8111 SMBus 2.0 (rev 02)
+ Subsystem: Advanced Micro Devices [AMD] AMD-8111 SMBus 2.0
+ Flags: medium devsel, IRQ 19
+ I/O ports at d400 [size=32]
+
+in your ``lspci -v``, then this driver is for your chipset.
+
+Process Call Support
+--------------------
+
+Supported.
+
+SMBus 2.0 Support
+-----------------
+
+Supported. Both PEC and block process call support is implemented. Slave
+mode or host notification are not yet implemented.
+
+Notes
+-----
+
+Note that for the 8111, there are two SMBus adapters. The SMBus 2.0 adapter
+is supported by this driver, and the SMBus 1.0 adapter is supported by the
+i2c-amd756 driver.
diff --git a/Documentation/i2c/busses/i2c-diolan-u2c b/Documentation/i2c/busses/i2c-diolan-u2c
deleted file mode 100644
index 0d6018c..0000000
--- a/Documentation/i2c/busses/i2c-diolan-u2c
+++ /dev/null
@@ -1,26 +0,0 @@
-Kernel driver i2c-diolan-u2c
-
-Supported adapters:
- * Diolan U2C-12 I2C-USB adapter
- Documentation:
- http://www.diolan.com/i2c/u2c12.html
-
-Author: Guenter Roeck <linux@roeck-us.net>
-
-Description
------------
-
-This is the driver for the Diolan U2C-12 USB-I2C adapter.
-
-The Diolan U2C-12 I2C-USB Adapter provides a low cost solution to connect
-a computer to I2C slave devices using a USB interface. It also supports
-connectivity to SPI devices.
-
-This driver only supports the I2C interface of U2C-12. The driver does not use
-interrupts.
-
-
-Module parameters
------------------
-
-* frequency: I2C bus frequency
diff --git a/Documentation/i2c/busses/i2c-diolan-u2c.rst b/Documentation/i2c/busses/i2c-diolan-u2c.rst
new file mode 100644
index 0000000..c18cbdc
--- /dev/null
+++ b/Documentation/i2c/busses/i2c-diolan-u2c.rst
@@ -0,0 +1,29 @@
+============================
+Kernel driver i2c-diolan-u2c
+============================
+
+Supported adapters:
+ * Diolan U2C-12 I2C-USB adapter
+
+ Documentation:
+ http://www.diolan.com/i2c/u2c12.html
+
+Author: Guenter Roeck <linux@roeck-us.net>
+
+Description
+-----------
+
+This is the driver for the Diolan U2C-12 USB-I2C adapter.
+
+The Diolan U2C-12 I2C-USB Adapter provides a low cost solution to connect
+a computer to I2C slave devices using a USB interface. It also supports
+connectivity to SPI devices.
+
+This driver only supports the I2C interface of U2C-12. The driver does not use
+interrupts.
+
+
+Module parameters
+-----------------
+
+* frequency: I2C bus frequency
diff --git a/Documentation/i2c/busses/i2c-i801 b/Documentation/i2c/busses/i2c-i801
deleted file mode 100644
index f426c13..0000000
--- a/Documentation/i2c/busses/i2c-i801
+++ /dev/null
@@ -1,173 +0,0 @@
-Kernel driver i2c-i801
-
-Supported adapters:
- * Intel 82801AA and 82801AB (ICH and ICH0 - part of the
- '810' and '810E' chipsets)
- * Intel 82801BA (ICH2 - part of the '815E' chipset)
- * Intel 82801CA/CAM (ICH3)
- * Intel 82801DB (ICH4) (HW PEC supported)
- * Intel 82801EB/ER (ICH5) (HW PEC supported)
- * Intel 6300ESB
- * Intel 82801FB/FR/FW/FRW (ICH6)
- * Intel 82801G (ICH7)
- * Intel 631xESB/632xESB (ESB2)
- * Intel 82801H (ICH8)
- * Intel 82801I (ICH9)
- * Intel EP80579 (Tolapai)
- * Intel 82801JI (ICH10)
- * Intel 5/3400 Series (PCH)
- * Intel 6 Series (PCH)
- * Intel Patsburg (PCH)
- * Intel DH89xxCC (PCH)
- * Intel Panther Point (PCH)
- * Intel Lynx Point (PCH)
- * Intel Avoton (SOC)
- * Intel Wellsburg (PCH)
- * Intel Coleto Creek (PCH)
- * Intel Wildcat Point (PCH)
- * Intel BayTrail (SOC)
- * Intel Braswell (SOC)
- * Intel Sunrise Point (PCH)
- * Intel Kaby Lake (PCH)
- * Intel DNV (SOC)
- * Intel Broxton (SOC)
- * Intel Lewisburg (PCH)
- * Intel Gemini Lake (SOC)
- * Intel Cannon Lake (PCH)
- * Intel Cedar Fork (PCH)
- * Intel Ice Lake (PCH)
- * Intel Comet Lake (PCH)
- * Intel Elkhart Lake (PCH)
- * Intel Tiger Lake (PCH)
- Datasheets: Publicly available at the Intel website
-
-On Intel Patsburg and later chipsets, both the normal host SMBus controller
-and the additional 'Integrated Device Function' controllers are supported.
-
-Authors:
- Mark Studebaker <mdsxyz123@yahoo.com>
- Jean Delvare <jdelvare@suse.de>
-
-
-Module Parameters
------------------
-
-* disable_features (bit vector)
-Disable selected features normally supported by the device. This makes it
-possible to work around possible driver or hardware bugs if the feature in
-question doesn't work as intended for whatever reason. Bit values:
- 0x01 disable SMBus PEC
- 0x02 disable the block buffer
- 0x08 disable the I2C block read functionality
- 0x10 don't use interrupts
- 0x20 disable SMBus Host Notify
-
-
-Description
------------
-
-The ICH (properly known as the 82801AA), ICH0 (82801AB), ICH2 (82801BA),
-ICH3 (82801CA/CAM) and later devices (PCH) are Intel chips that are a part of
-Intel's '810' chipset for Celeron-based PCs, '810E' chipset for
-Pentium-based PCs, '815E' chipset, and others.
-
-The ICH chips contain at least SEVEN separate PCI functions in TWO logical
-PCI devices. An output of lspci will show something similar to the
-following:
-
- 00:1e.0 PCI bridge: Intel Corporation: Unknown device 2418 (rev 01)
- 00:1f.0 ISA bridge: Intel Corporation: Unknown device 2410 (rev 01)
- 00:1f.1 IDE interface: Intel Corporation: Unknown device 2411 (rev 01)
- 00:1f.2 USB Controller: Intel Corporation: Unknown device 2412 (rev 01)
- 00:1f.3 Unknown class [0c05]: Intel Corporation: Unknown device 2413 (rev 01)
-
-The SMBus controller is function 3 in device 1f. Class 0c05 is SMBus Serial
-Controller.
-
-The ICH chips are quite similar to Intel's PIIX4 chip, at least in the
-SMBus controller.
-
-
-Process Call Support
---------------------
-
-Block process call is supported on the 82801EB (ICH5) and later chips.
-
-
-I2C Block Read Support
-----------------------
-
-I2C block read is supported on the 82801EB (ICH5) and later chips.
-
-
-SMBus 2.0 Support
------------------
-
-The 82801DB (ICH4) and later chips support several SMBus 2.0 features.
-
-
-Interrupt Support
------------------
-
-PCI interrupt support is supported on the 82801EB (ICH5) and later chips.
-
-
-Hidden ICH SMBus
-----------------
-
-If your system has an Intel ICH south bridge, but you do NOT see the
-SMBus device at 00:1f.3 in lspci, and you can't figure out any way in the
-BIOS to enable it, it means it has been hidden by the BIOS code. Asus is
-well known for first doing this on their P4B motherboard, and many other
-boards after that. Some vendor machines are affected as well.
-
-The first thing to try is the "i2c-scmi" ACPI driver. It could be that the
-SMBus was hidden on purpose because it'll be driven by ACPI. If the
-i2c-scmi driver works for you, just forget about the i2c-i801 driver and
-don't try to unhide the ICH SMBus. Even if i2c-scmi doesn't work, you
-better make sure that the SMBus isn't used by the ACPI code. Try loading
-the "fan" and "thermal" drivers, and check in /sys/class/thermal. If you
-find a thermal zone with type "acpitz", it's likely that the ACPI is
-accessing the SMBus and it's safer not to unhide it. Only once you are
-certain that ACPI isn't using the SMBus, you can attempt to unhide it.
-
-In order to unhide the SMBus, we need to change the value of a PCI
-register before the kernel enumerates the PCI devices. This is done in
-drivers/pci/quirks.c, where all affected boards must be listed (see
-function asus_hides_smbus_hostbridge.) If the SMBus device is missing,
-and you think there's something interesting on the SMBus (e.g. a
-hardware monitoring chip), you need to add your board to the list.
-
-The motherboard is identified using the subvendor and subdevice IDs of the
-host bridge PCI device. Get yours with "lspci -n -v -s 00:00.0":
-
-00:00.0 Class 0600: 8086:2570 (rev 02)
- Subsystem: 1043:80f2
- Flags: bus master, fast devsel, latency 0
- Memory at fc000000 (32-bit, prefetchable) [size=32M]
- Capabilities: [e4] #09 [2106]
- Capabilities: [a0] AGP version 3.0
-
-Here the host bridge ID is 2570 (82865G/PE/P), the subvendor ID is 1043
-(Asus) and the subdevice ID is 80f2 (P4P800-X). You can find the symbolic
-names for the bridge ID and the subvendor ID in include/linux/pci_ids.h,
-and then add a case for your subdevice ID at the right place in
-drivers/pci/quirks.c. Then please give it very good testing, to make sure
-that the unhidden SMBus doesn't conflict with e.g. ACPI.
-
-If it works, proves useful (i.e. there are usable chips on the SMBus)
-and seems safe, please submit a patch for inclusion into the kernel.
-
-Note: There's a useful script in lm_sensors 2.10.2 and later, named
-unhide_ICH_SMBus (in prog/hotplug), which uses the fakephp driver to
-temporarily unhide the SMBus without having to patch and recompile your
-kernel. It's very convenient if you just want to check if there's
-anything interesting on your hidden ICH SMBus.
-
-
-**********************
-The lm_sensors project gratefully acknowledges the support of Texas
-Instruments in the initial development of this driver.
-
-The lm_sensors project gratefully acknowledges the support of Intel in the
-development of SMBus 2.0 / ICH4 features of this driver.
diff --git a/Documentation/i2c/busses/i2c-i801.rst b/Documentation/i2c/busses/i2c-i801.rst
new file mode 100644
index 0000000..2a570c21
--- /dev/null
+++ b/Documentation/i2c/busses/i2c-i801.rst
@@ -0,0 +1,182 @@
+======================
+Kernel driver i2c-i801
+======================
+
+
+Supported adapters:
+ * Intel 82801AA and 82801AB (ICH and ICH0 - part of the
+ '810' and '810E' chipsets)
+ * Intel 82801BA (ICH2 - part of the '815E' chipset)
+ * Intel 82801CA/CAM (ICH3)
+ * Intel 82801DB (ICH4) (HW PEC supported)
+ * Intel 82801EB/ER (ICH5) (HW PEC supported)
+ * Intel 6300ESB
+ * Intel 82801FB/FR/FW/FRW (ICH6)
+ * Intel 82801G (ICH7)
+ * Intel 631xESB/632xESB (ESB2)
+ * Intel 82801H (ICH8)
+ * Intel 82801I (ICH9)
+ * Intel EP80579 (Tolapai)
+ * Intel 82801JI (ICH10)
+ * Intel 5/3400 Series (PCH)
+ * Intel 6 Series (PCH)
+ * Intel Patsburg (PCH)
+ * Intel DH89xxCC (PCH)
+ * Intel Panther Point (PCH)
+ * Intel Lynx Point (PCH)
+ * Intel Avoton (SOC)
+ * Intel Wellsburg (PCH)
+ * Intel Coleto Creek (PCH)
+ * Intel Wildcat Point (PCH)
+ * Intel BayTrail (SOC)
+ * Intel Braswell (SOC)
+ * Intel Sunrise Point (PCH)
+ * Intel Kaby Lake (PCH)
+ * Intel DNV (SOC)
+ * Intel Broxton (SOC)
+ * Intel Lewisburg (PCH)
+ * Intel Gemini Lake (SOC)
+ * Intel Cannon Lake (PCH)
+ * Intel Cedar Fork (PCH)
+ * Intel Ice Lake (PCH)
+ * Intel Comet Lake (PCH)
+ * Intel Elkhart Lake (PCH)
+ * Intel Tiger Lake (PCH)
+
+ Datasheets: Publicly available at the Intel website
+
+On Intel Patsburg and later chipsets, both the normal host SMBus controller
+and the additional 'Integrated Device Function' controllers are supported.
+
+Authors:
+ - Mark Studebaker <mdsxyz123@yahoo.com>
+ - Jean Delvare <jdelvare@suse.de>
+
+
+Module Parameters
+-----------------
+
+* disable_features (bit vector)
+
+Disable selected features normally supported by the device. This makes it
+possible to work around possible driver or hardware bugs if the feature in
+question doesn't work as intended for whatever reason. Bit values:
+
+ ==== =========================================
+ 0x01 disable SMBus PEC
+ 0x02 disable the block buffer
+ 0x08 disable the I2C block read functionality
+ 0x10 don't use interrupts
+ 0x20 disable SMBus Host Notify
+ ==== =========================================
+
+
+Description
+-----------
+
+The ICH (properly known as the 82801AA), ICH0 (82801AB), ICH2 (82801BA),
+ICH3 (82801CA/CAM) and later devices (PCH) are Intel chips that are a part of
+Intel's '810' chipset for Celeron-based PCs, '810E' chipset for
+Pentium-based PCs, '815E' chipset, and others.
+
+The ICH chips contain at least SEVEN separate PCI functions in TWO logical
+PCI devices. An output of lspci will show something similar to the
+following::
+
+ 00:1e.0 PCI bridge: Intel Corporation: Unknown device 2418 (rev 01)
+ 00:1f.0 ISA bridge: Intel Corporation: Unknown device 2410 (rev 01)
+ 00:1f.1 IDE interface: Intel Corporation: Unknown device 2411 (rev 01)
+ 00:1f.2 USB Controller: Intel Corporation: Unknown device 2412 (rev 01)
+ 00:1f.3 Unknown class [0c05]: Intel Corporation: Unknown device 2413 (rev 01)
+
+The SMBus controller is function 3 in device 1f. Class 0c05 is SMBus Serial
+Controller.
+
+The ICH chips are quite similar to Intel's PIIX4 chip, at least in the
+SMBus controller.
+
+
+Process Call Support
+--------------------
+
+Block process call is supported on the 82801EB (ICH5) and later chips.
+
+
+I2C Block Read Support
+----------------------
+
+I2C block read is supported on the 82801EB (ICH5) and later chips.
+
+
+SMBus 2.0 Support
+-----------------
+
+The 82801DB (ICH4) and later chips support several SMBus 2.0 features.
+
+
+Interrupt Support
+-----------------
+
+PCI interrupt support is supported on the 82801EB (ICH5) and later chips.
+
+
+Hidden ICH SMBus
+----------------
+
+If your system has an Intel ICH south bridge, but you do NOT see the
+SMBus device at 00:1f.3 in lspci, and you can't figure out any way in the
+BIOS to enable it, it means it has been hidden by the BIOS code. Asus is
+well known for first doing this on their P4B motherboard, and many other
+boards after that. Some vendor machines are affected as well.
+
+The first thing to try is the "i2c-scmi" ACPI driver. It could be that the
+SMBus was hidden on purpose because it'll be driven by ACPI. If the
+i2c-scmi driver works for you, just forget about the i2c-i801 driver and
+don't try to unhide the ICH SMBus. Even if i2c-scmi doesn't work, you
+better make sure that the SMBus isn't used by the ACPI code. Try loading
+the "fan" and "thermal" drivers, and check in /sys/class/thermal. If you
+find a thermal zone with type "acpitz", it's likely that the ACPI is
+accessing the SMBus and it's safer not to unhide it. Only once you are
+certain that ACPI isn't using the SMBus, you can attempt to unhide it.
+
+In order to unhide the SMBus, we need to change the value of a PCI
+register before the kernel enumerates the PCI devices. This is done in
+drivers/pci/quirks.c, where all affected boards must be listed (see
+function asus_hides_smbus_hostbridge.) If the SMBus device is missing,
+and you think there's something interesting on the SMBus (e.g. a
+hardware monitoring chip), you need to add your board to the list.
+
+The motherboard is identified using the subvendor and subdevice IDs of the
+host bridge PCI device. Get yours with ``lspci -n -v -s 00:00.0``::
+
+ 00:00.0 Class 0600: 8086:2570 (rev 02)
+ Subsystem: 1043:80f2
+ Flags: bus master, fast devsel, latency 0
+ Memory at fc000000 (32-bit, prefetchable) [size=32M]
+ Capabilities: [e4] #09 [2106]
+ Capabilities: [a0] AGP version 3.0
+
+Here the host bridge ID is 2570 (82865G/PE/P), the subvendor ID is 1043
+(Asus) and the subdevice ID is 80f2 (P4P800-X). You can find the symbolic
+names for the bridge ID and the subvendor ID in include/linux/pci_ids.h,
+and then add a case for your subdevice ID at the right place in
+drivers/pci/quirks.c. Then please give it very good testing, to make sure
+that the unhidden SMBus doesn't conflict with e.g. ACPI.
+
+If it works, proves useful (i.e. there are usable chips on the SMBus)
+and seems safe, please submit a patch for inclusion into the kernel.
+
+Note: There's a useful script in lm_sensors 2.10.2 and later, named
+unhide_ICH_SMBus (in prog/hotplug), which uses the fakephp driver to
+temporarily unhide the SMBus without having to patch and recompile your
+kernel. It's very convenient if you just want to check if there's
+anything interesting on your hidden ICH SMBus.
+
+
+----------------------------------------------------------------------------
+
+The lm_sensors project gratefully acknowledges the support of Texas
+Instruments in the initial development of this driver.
+
+The lm_sensors project gratefully acknowledges the support of Intel in the
+development of SMBus 2.0 / ICH4 features of this driver.
diff --git a/Documentation/i2c/busses/i2c-ismt b/Documentation/i2c/busses/i2c-ismt
deleted file mode 100644
index 7373558..0000000
--- a/Documentation/i2c/busses/i2c-ismt
+++ /dev/null
@@ -1,36 +0,0 @@
-Kernel driver i2c-ismt
-
-Supported adapters:
- * Intel S12xx series SOCs
-
-Authors:
- Bill Brown <bill.e.brown@intel.com>
-
-
-Module Parameters
------------------
-
-* bus_speed (unsigned int)
-Allows changing of the bus speed. Normally, the bus speed is set by the BIOS
-and never needs to be changed. However, some SMBus analyzers are too slow for
-monitoring the bus during debug, thus the need for this module parameter.
-Specify the bus speed in kHz.
-Available bus frequency settings:
- 0 no change
- 80 kHz
- 100 kHz
- 400 kHz
- 1000 kHz
-
-
-Description
------------
-
-The S12xx series of SOCs have a pair of integrated SMBus 2.0 controllers
-targeted primarily at the microserver and storage markets.
-
-The S12xx series contain a pair of PCI functions. An output of lspci will show
-something similar to the following:
-
- 00:13.0 System peripheral: Intel Corporation Centerton SMBus 2.0 Controller 0
- 00:13.1 System peripheral: Intel Corporation Centerton SMBus 2.0 Controller 1
diff --git a/Documentation/i2c/busses/i2c-ismt.rst b/Documentation/i2c/busses/i2c-ismt.rst
new file mode 100644
index 0000000..8e74919
--- /dev/null
+++ b/Documentation/i2c/busses/i2c-ismt.rst
@@ -0,0 +1,44 @@
+======================
+Kernel driver i2c-ismt
+======================
+
+
+Supported adapters:
+ * Intel S12xx series SOCs
+
+Authors:
+ Bill Brown <bill.e.brown@intel.com>
+
+
+Module Parameters
+-----------------
+
+* bus_speed (unsigned int)
+
+Allows changing of the bus speed. Normally, the bus speed is set by the BIOS
+and never needs to be changed. However, some SMBus analyzers are too slow for
+monitoring the bus during debug, thus the need for this module parameter.
+Specify the bus speed in kHz.
+
+Available bus frequency settings:
+
+ ==== =========
+ 0 no change
+ 80 kHz
+ 100 kHz
+ 400 kHz
+ 1000 kHz
+ ==== =========
+
+
+Description
+-----------
+
+The S12xx series of SOCs have a pair of integrated SMBus 2.0 controllers
+targeted primarily at the microserver and storage markets.
+
+The S12xx series contain a pair of PCI functions. An output of lspci will show
+something similar to the following::
+
+ 00:13.0 System peripheral: Intel Corporation Centerton SMBus 2.0 Controller 0
+ 00:13.1 System peripheral: Intel Corporation Centerton SMBus 2.0 Controller 1
diff --git a/Documentation/i2c/busses/i2c-mlxcpld b/Documentation/i2c/busses/i2c-mlxcpld
deleted file mode 100644
index 925904a..0000000
--- a/Documentation/i2c/busses/i2c-mlxcpld
+++ /dev/null
@@ -1,51 +0,0 @@
-Driver i2c-mlxcpld
-
-Author: Michael Shych <michaelsh@mellanox.com>
-
-This is the Mellanox I2C controller logic, implemented in Lattice CPLD
-device.
-Device supports:
- - Master mode.
- - One physical bus.
- - Polling mode.
-
-This controller is equipped within the next Mellanox systems:
-"msx6710", "msx6720", "msb7700", "msn2700", "msx1410", "msn2410", "msb7800",
-"msn2740", "msn2100".
-
-The next transaction types are supported:
- - Receive Byte/Block.
- - Send Byte/Block.
- - Read Byte/Block.
- - Write Byte/Block.
-
-Registers:
-CPBLTY 0x0 - capability reg.
- Bits [6:5] - transaction length. b01 - 72B is supported,
- 36B in other case.
- Bit 7 - SMBus block read support.
-CTRL 0x1 - control reg.
- Resets all the registers.
-HALF_CYC 0x4 - cycle reg.
- Configure the width of I2C SCL half clock cycle (in 4 LPC_CLK
- units).
-I2C_HOLD 0x5 - hold reg.
- OE (output enable) is delayed by value set to this register
- (in LPC_CLK units)
-CMD 0x6 - command reg.
- Bit 0, 0 = write, 1 = read.
- Bits [7:1] - the 7bit Address of the I2C device.
- It should be written last as it triggers an I2C transaction.
-NUM_DATA 0x7 - data size reg.
- Number of data bytes to write in read transaction
-NUM_ADDR 0x8 - address reg.
- Number of address bytes to write in read transaction.
-STATUS 0x9 - status reg.
- Bit 0 - transaction is completed.
- Bit 4 - ACK/NACK.
-DATAx 0xa - 0x54 - 68 bytes data buffer regs.
- For write transaction address is specified in four first bytes
- (DATA1 - DATA4), data starting from DATA4.
- For read transactions address is sent in a separate transaction and
- specified in the four first bytes (DATA0 - DATA3). Data is read
- starting from DATA0.
diff --git a/Documentation/i2c/busses/i2c-mlxcpld.rst b/Documentation/i2c/busses/i2c-mlxcpld.rst
new file mode 100644
index 0000000..9a0b291
--- /dev/null
+++ b/Documentation/i2c/busses/i2c-mlxcpld.rst
@@ -0,0 +1,57 @@
+==================
+Driver i2c-mlxcpld
+==================
+
+Author: Michael Shych <michaelsh@mellanox.com>
+
+This is the Mellanox I2C controller logic, implemented in Lattice CPLD
+device.
+
+Device supports:
+ - Master mode.
+ - One physical bus.
+ - Polling mode.
+
+This controller is equipped within the next Mellanox systems:
+"msx6710", "msx6720", "msb7700", "msn2700", "msx1410", "msn2410", "msb7800",
+"msn2740", "msn2100".
+
+The next transaction types are supported:
+ - Receive Byte/Block.
+ - Send Byte/Block.
+ - Read Byte/Block.
+ - Write Byte/Block.
+
+Registers:
+
+=============== === =======================================================================
+CPBLTY 0x0 - capability reg.
+ Bits [6:5] - transaction length. b01 - 72B is supported,
+ 36B in other case.
+ Bit 7 - SMBus block read support.
+CTRL 0x1 - control reg.
+ Resets all the registers.
+HALF_CYC 0x4 - cycle reg.
+ Configure the width of I2C SCL half clock cycle (in 4 LPC_CLK
+ units).
+I2C_HOLD 0x5 - hold reg.
+ OE (output enable) is delayed by value set to this register
+ (in LPC_CLK units)
+CMD 0x6 - command reg.
+ Bit 0, 0 = write, 1 = read.
+ Bits [7:1] - the 7bit Address of the I2C device.
+ It should be written last as it triggers an I2C transaction.
+NUM_DATA 0x7 - data size reg.
+ Number of data bytes to write in read transaction
+NUM_ADDR 0x8 - address reg.
+ Number of address bytes to write in read transaction.
+STATUS 0x9 - status reg.
+ Bit 0 - transaction is completed.
+ Bit 4 - ACK/NACK.
+DATAx 0xa - 0x54 - 68 bytes data buffer regs.
+ For write transaction address is specified in four first bytes
+ (DATA1 - DATA4), data starting from DATA4.
+ For read transactions address is sent in a separate transaction and
+ specified in the four first bytes (DATA0 - DATA3). Data is read
+ starting from DATA0.
+=============== === =======================================================================
diff --git a/Documentation/i2c/busses/i2c-nforce2 b/Documentation/i2c/busses/i2c-nforce2
deleted file mode 100644
index 9698c39..0000000
--- a/Documentation/i2c/busses/i2c-nforce2
+++ /dev/null
@@ -1,50 +0,0 @@
-Kernel driver i2c-nforce2
-
-Supported adapters:
- * nForce2 MCP 10de:0064
- * nForce2 Ultra 400 MCP 10de:0084
- * nForce3 Pro150 MCP 10de:00D4
- * nForce3 250Gb MCP 10de:00E4
- * nForce4 MCP 10de:0052
- * nForce4 MCP-04 10de:0034
- * nForce MCP51 10de:0264
- * nForce MCP55 10de:0368
- * nForce MCP61 10de:03EB
- * nForce MCP65 10de:0446
- * nForce MCP67 10de:0542
- * nForce MCP73 10de:07D8
- * nForce MCP78S 10de:0752
- * nForce MCP79 10de:0AA2
-
-Datasheet: not publicly available, but seems to be similar to the
- AMD-8111 SMBus 2.0 adapter.
-
-Authors:
- Hans-Frieder Vogt <hfvogt@gmx.net>,
- Thomas Leibold <thomas@plx.com>,
- Patrick Dreker <patrick@dreker.de>
-
-Description
------------
-
-i2c-nforce2 is a driver for the SMBuses included in the nVidia nForce2 MCP.
-
-If your 'lspci -v' listing shows something like the following,
-
-00:01.1 SMBus: nVidia Corporation: Unknown device 0064 (rev a2)
- Subsystem: Asustek Computer, Inc.: Unknown device 0c11
- Flags: 66Mhz, fast devsel, IRQ 5
- I/O ports at c000 [size=32]
- Capabilities: <available only to root>
-
-then this driver should support the SMBuses of your motherboard.
-
-
-Notes
------
-
-The SMBus adapter in the nForce2 chipset seems to be very similar to the
-SMBus 2.0 adapter in the AMD-8111 south bridge. However, I could only get
-the driver to work with direct I/O access, which is different to the EC
-interface of the AMD-8111. Tested on Asus A7N8X. The ACPI DSDT table of the
-Asus A7N8X lists two SMBuses, both of which are supported by this driver.
diff --git a/Documentation/i2c/busses/i2c-nforce2.rst b/Documentation/i2c/busses/i2c-nforce2.rst
new file mode 100644
index 0000000..8318144
--- /dev/null
+++ b/Documentation/i2c/busses/i2c-nforce2.rst
@@ -0,0 +1,53 @@
+=========================
+Kernel driver i2c-nforce2
+=========================
+
+Supported adapters:
+ * nForce2 MCP 10de:0064
+ * nForce2 Ultra 400 MCP 10de:0084
+ * nForce3 Pro150 MCP 10de:00D4
+ * nForce3 250Gb MCP 10de:00E4
+ * nForce4 MCP 10de:0052
+ * nForce4 MCP-04 10de:0034
+ * nForce MCP51 10de:0264
+ * nForce MCP55 10de:0368
+ * nForce MCP61 10de:03EB
+ * nForce MCP65 10de:0446
+ * nForce MCP67 10de:0542
+ * nForce MCP73 10de:07D8
+ * nForce MCP78S 10de:0752
+ * nForce MCP79 10de:0AA2
+
+Datasheet:
+ not publicly available, but seems to be similar to the
+ AMD-8111 SMBus 2.0 adapter.
+
+Authors:
+ - Hans-Frieder Vogt <hfvogt@gmx.net>,
+ - Thomas Leibold <thomas@plx.com>,
+ - Patrick Dreker <patrick@dreker.de>
+
+Description
+-----------
+
+i2c-nforce2 is a driver for the SMBuses included in the nVidia nForce2 MCP.
+
+If your ``lspci -v`` listing shows something like the following::
+
+ 00:01.1 SMBus: nVidia Corporation: Unknown device 0064 (rev a2)
+ Subsystem: Asustek Computer, Inc.: Unknown device 0c11
+ Flags: 66Mhz, fast devsel, IRQ 5
+ I/O ports at c000 [size=32]
+ Capabilities: <available only to root>
+
+then this driver should support the SMBuses of your motherboard.
+
+
+Notes
+-----
+
+The SMBus adapter in the nForce2 chipset seems to be very similar to the
+SMBus 2.0 adapter in the AMD-8111 south bridge. However, I could only get
+the driver to work with direct I/O access, which is different to the EC
+interface of the AMD-8111. Tested on Asus A7N8X. The ACPI DSDT table of the
+Asus A7N8X lists two SMBuses, both of which are supported by this driver.
diff --git a/Documentation/i2c/busses/i2c-nvidia-gpu b/Documentation/i2c/busses/i2c-nvidia-gpu
deleted file mode 100644
index 31884d2..0000000
--- a/Documentation/i2c/busses/i2c-nvidia-gpu
+++ /dev/null
@@ -1,18 +0,0 @@
-Kernel driver i2c-nvidia-gpu
-
-Datasheet: not publicly available.
-
-Authors:
- Ajay Gupta <ajayg@nvidia.com>
-
-Description
------------
-
-i2c-nvidia-gpu is a driver for I2C controller included in NVIDIA Turing
-and later GPUs and it is used to communicate with Type-C controller on GPUs.
-
-If your 'lspci -v' listing shows something like the following,
-
-01:00.3 Serial bus controller [0c80]: NVIDIA Corporation Device 1ad9 (rev a1)
-
-then this driver should support the I2C controller of your GPU.
diff --git a/Documentation/i2c/busses/i2c-nvidia-gpu.rst b/Documentation/i2c/busses/i2c-nvidia-gpu.rst
new file mode 100644
index 0000000..38fb8a4
--- /dev/null
+++ b/Documentation/i2c/busses/i2c-nvidia-gpu.rst
@@ -0,0 +1,20 @@
+============================
+Kernel driver i2c-nvidia-gpu
+============================
+
+Datasheet: not publicly available.
+
+Authors:
+ Ajay Gupta <ajayg@nvidia.com>
+
+Description
+-----------
+
+i2c-nvidia-gpu is a driver for I2C controller included in NVIDIA Turing
+and later GPUs and it is used to communicate with Type-C controller on GPUs.
+
+If your ``lspci -v`` listing shows something like the following::
+
+ 01:00.3 Serial bus controller [0c80]: NVIDIA Corporation Device 1ad9 (rev a1)
+
+then this driver should support the I2C controller of your GPU.
diff --git a/Documentation/i2c/busses/i2c-ocores b/Documentation/i2c/busses/i2c-ocores
deleted file mode 100644
index 9caaf7d..0000000
--- a/Documentation/i2c/busses/i2c-ocores
+++ /dev/null
@@ -1,68 +0,0 @@
-Kernel driver i2c-ocores
-
-Supported adapters:
- * OpenCores.org I2C controller by Richard Herveille (see datasheet link)
- https://opencores.org/project/i2c/overview
-
-Author: Peter Korsgaard <peter@korsgaard.com>
-
-Description
------------
-
-i2c-ocores is an i2c bus driver for the OpenCores.org I2C controller
-IP core by Richard Herveille.
-
-Usage
------
-
-i2c-ocores uses the platform bus, so you need to provide a struct
-platform_device with the base address and interrupt number. The
-dev.platform_data of the device should also point to a struct
-ocores_i2c_platform_data (see linux/platform_data/i2c-ocores.h) describing the
-distance between registers and the input clock speed.
-There is also a possibility to attach a list of i2c_board_info which
-the i2c-ocores driver will add to the bus upon creation.
-
-E.G. something like:
-
-static struct resource ocores_resources[] = {
- [0] = {
- .start = MYI2C_BASEADDR,
- .end = MYI2C_BASEADDR + 8,
- .flags = IORESOURCE_MEM,
- },
- [1] = {
- .start = MYI2C_IRQ,
- .end = MYI2C_IRQ,
- .flags = IORESOURCE_IRQ,
- },
-};
-
-/* optional board info */
-struct i2c_board_info ocores_i2c_board_info[] = {
- {
- I2C_BOARD_INFO("tsc2003", 0x48),
- .platform_data = &tsc2003_platform_data,
- .irq = TSC_IRQ
- },
- {
- I2C_BOARD_INFO("adv7180", 0x42 >> 1),
- .irq = ADV_IRQ
- }
-};
-
-static struct ocores_i2c_platform_data myi2c_data = {
- .regstep = 2, /* two bytes between registers */
- .clock_khz = 50000, /* input clock of 50MHz */
- .devices = ocores_i2c_board_info, /* optional table of devices */
- .num_devices = ARRAY_SIZE(ocores_i2c_board_info), /* table size */
-};
-
-static struct platform_device myi2c = {
- .name = "ocores-i2c",
- .dev = {
- .platform_data = &myi2c_data,
- },
- .num_resources = ARRAY_SIZE(ocores_resources),
- .resource = ocores_resources,
-};
diff --git a/Documentation/i2c/busses/i2c-ocores.rst b/Documentation/i2c/busses/i2c-ocores.rst
new file mode 100644
index 0000000..f5e175f
--- /dev/null
+++ b/Documentation/i2c/busses/i2c-ocores.rst
@@ -0,0 +1,70 @@
+========================
+Kernel driver i2c-ocores
+========================
+
+Supported adapters:
+ * OpenCores.org I2C controller by Richard Herveille (see datasheet link)
+ https://opencores.org/project/i2c/overview
+
+Author: Peter Korsgaard <peter@korsgaard.com>
+
+Description
+-----------
+
+i2c-ocores is an i2c bus driver for the OpenCores.org I2C controller
+IP core by Richard Herveille.
+
+Usage
+-----
+
+i2c-ocores uses the platform bus, so you need to provide a struct
+platform_device with the base address and interrupt number. The
+dev.platform_data of the device should also point to a struct
+ocores_i2c_platform_data (see linux/platform_data/i2c-ocores.h) describing the
+distance between registers and the input clock speed.
+There is also a possibility to attach a list of i2c_board_info which
+the i2c-ocores driver will add to the bus upon creation.
+
+E.G. something like::
+
+ static struct resource ocores_resources[] = {
+ [0] = {
+ .start = MYI2C_BASEADDR,
+ .end = MYI2C_BASEADDR + 8,
+ .flags = IORESOURCE_MEM,
+ },
+ [1] = {
+ .start = MYI2C_IRQ,
+ .end = MYI2C_IRQ,
+ .flags = IORESOURCE_IRQ,
+ },
+ };
+
+ /* optional board info */
+ struct i2c_board_info ocores_i2c_board_info[] = {
+ {
+ I2C_BOARD_INFO("tsc2003", 0x48),
+ .platform_data = &tsc2003_platform_data,
+ .irq = TSC_IRQ
+ },
+ {
+ I2C_BOARD_INFO("adv7180", 0x42 >> 1),
+ .irq = ADV_IRQ
+ }
+ };
+
+ static struct ocores_i2c_platform_data myi2c_data = {
+ .regstep = 2, /* two bytes between registers */
+ .clock_khz = 50000, /* input clock of 50MHz */
+ .devices = ocores_i2c_board_info, /* optional table of devices */
+ .num_devices = ARRAY_SIZE(ocores_i2c_board_info), /* table size */
+ };
+
+ static struct platform_device myi2c = {
+ .name = "ocores-i2c",
+ .dev = {
+ .platform_data = &myi2c_data,
+ },
+ .num_resources = ARRAY_SIZE(ocores_resources),
+ .resource = ocores_resources,
+ };
diff --git a/Documentation/i2c/busses/i2c-parport b/Documentation/i2c/busses/i2c-parport
deleted file mode 100644
index c3dbb3b..0000000
--- a/Documentation/i2c/busses/i2c-parport
+++ /dev/null
@@ -1,178 +0,0 @@
-Kernel driver i2c-parport
-
-Author: Jean Delvare <jdelvare@suse.de>
-
-This is a unified driver for several i2c-over-parallel-port adapters,
-such as the ones made by Philips, Velleman or ELV. This driver is
-meant as a replacement for the older, individual drivers:
- * i2c-philips-par
- * i2c-elv
- * i2c-velleman
- * video/i2c-parport (NOT the same as this one, dedicated to home brew
- teletext adapters)
-
-It currently supports the following devices:
- * (type=0) Philips adapter
- * (type=1) home brew teletext adapter
- * (type=2) Velleman K8000 adapter
- * (type=3) ELV adapter
- * (type=4) Analog Devices ADM1032 evaluation board
- * (type=5) Analog Devices evaluation boards: ADM1025, ADM1030, ADM1031
- * (type=6) Barco LPT->DVI (K5800236) adapter
- * (type=7) One For All JP1 parallel port adapter
- * (type=8) VCT-jig
-
-These devices use different pinout configurations, so you have to tell
-the driver what you have, using the type module parameter. There is no
-way to autodetect the devices. Support for different pinout configurations
-can be easily added when needed.
-
-Earlier kernels defaulted to type=0 (Philips). But now, if the type
-parameter is missing, the driver will simply fail to initialize.
-
-SMBus alert support is available on adapters which have this line properly
-connected to the parallel port's interrupt pin.
-
-
-Building your own adapter
--------------------------
-
-If you want to build you own i2c-over-parallel-port adapter, here is
-a sample electronics schema (credits go to Sylvain Munaut):
-
-Device PC
-Side ___________________Vdd (+) Side
- | | |
- --- --- ---
- | | | | | |
- |R| |R| |R|
- | | | | | |
- --- --- ---
- | | |
- | | /| |
-SCL ----------x--------o |-----------x------------------- pin 2
- | \| | |
- | | |
- | |\ | |
-SDA ----------x----x---| o---x--------------------------- pin 13
- | |/ |
- | |
- | /| |
- ---------o |----------------x-------------- pin 3
- \| | |
- | |
- --- ---
- | | | |
- |R| |R|
- | | | |
- --- ---
- | |
- ### ###
- GND GND
-
-Remarks:
- - This is the exact pinout and electronics used on the Analog Devices
- evaluation boards.
- /|
- - All inverters -o |- must be 74HC05, they must be open collector output.
- \|
- - All resitors are 10k.
- - Pins 18-25 of the parallel port connected to GND.
- - Pins 4-9 (D2-D7) could be used as VDD is the driver drives them high.
- The ADM1032 evaluation board uses D4-D7. Beware that the amount of
- current you can draw from the parallel port is limited. Also note that
- all connected lines MUST BE driven at the same state, else you'll short
- circuit the output buffers! So plugging the I2C adapter after loading
- the i2c-parport module might be a good safety since data line state
- prior to init may be unknown.
- - This is 5V!
- - Obviously you cannot read SCL (so it's not really standard-compliant).
- Pretty easy to add, just copy the SDA part and use another input pin.
- That would give (ELV compatible pinout):
-
-
-Device PC
-Side ______________________________Vdd (+) Side
- | | | |
- --- --- --- ---
- | | | | | | | |
- |R| |R| |R| |R|
- | | | | | | | |
- --- --- --- ---
- | | | |
- | | |\ | |
-SCL ----------x--------x--| o---x------------------------ pin 15
- | | |/ |
- | | |
- | | /| |
- | ---o |-------------x-------------- pin 2
- | \| | |
- | | |
- | | |
- | |\ | |
-SDA ---------------x---x--| o--------x------------------- pin 10
- | |/ |
- | |
- | /| |
- ---o |------------------x--------- pin 3
- \| | |
- | |
- --- ---
- | | | |
- |R| |R|
- | | | |
- --- ---
- | |
- ### ###
- GND GND
-
-
-If possible, you should use the same pinout configuration as existing
-adapters do, so you won't even have to change the code.
-
-
-Similar (but different) drivers
--------------------------------
-
-This driver is NOT the same as the i2c-pport driver found in the i2c
-package. The i2c-pport driver makes use of modern parallel port features so
-that you don't need additional electronics. It has other restrictions
-however, and was not ported to Linux 2.6 (yet).
-
-This driver is also NOT the same as the i2c-pcf-epp driver found in the
-lm_sensors package. The i2c-pcf-epp driver doesn't use the parallel port as
-an I2C bus directly. Instead, it uses it to control an external I2C bus
-master. That driver was not ported to Linux 2.6 (yet) either.
-
-
-Legacy documentation for Velleman adapter
------------------------------------------
-
-Useful links:
-Velleman http://www.velleman.be/
-Velleman K8000 Howto http://howto.htlw16.ac.at/k8000-howto.html
-
-The project has lead to new libs for the Velleman K8000 and K8005:
- LIBK8000 v1.99.1 and LIBK8005 v0.21
-With these libs, you can control the K8000 interface card and the K8005
-stepper motor card with the simple commands which are in the original
-Velleman software, like SetIOchannel, ReadADchannel, SendStepCCWFull and
-many more, using /dev/velleman.
- http://home.wanadoo.nl/hihihi/libk8000.htm
- http://home.wanadoo.nl/hihihi/libk8005.htm
- http://struyve.mine.nu:8080/index.php?block=k8000
- http://sourceforge.net/projects/libk8005/
-
-
-One For All JP1 parallel port adapter
--------------------------------------
-
-The JP1 project revolves around a set of remote controls which expose
-the I2C bus their internal configuration EEPROM lives on via a 6 pin
-jumper in the battery compartment. More details can be found at:
-
-http://www.hifi-remote.com/jp1/
-
-Details of the simple parallel port hardware can be found at:
-
-http://www.hifi-remote.com/jp1/hardware.shtml
diff --git a/Documentation/i2c/busses/i2c-parport-light b/Documentation/i2c/busses/i2c-parport-light
deleted file mode 100644
index 7071b8b..0000000
--- a/Documentation/i2c/busses/i2c-parport-light
+++ /dev/null
@@ -1,22 +0,0 @@
-Kernel driver i2c-parport-light
-
-Author: Jean Delvare <jdelvare@suse.de>
-
-This driver is a light version of i2c-parport. It doesn't depend
-on the parport driver, and uses direct I/O access instead. This might be
-preferred on embedded systems where wasting memory for the clean but heavy
-parport handling is not an option. The drawback is a reduced portability
-and the impossibility to daisy-chain other parallel port devices.
-
-Please see i2c-parport for documentation.
-
-Module parameters:
-
-* type: type of adapter (see i2c-parport or modinfo)
-
-* base: base I/O address
- Default is 0x378 which is fairly common for parallel ports, at least on PC.
-
-* irq: optional IRQ
- This must be passed if you want SMBus alert support, assuming your adapter
- actually supports this.
diff --git a/Documentation/i2c/busses/i2c-parport-light.rst b/Documentation/i2c/busses/i2c-parport-light.rst
new file mode 100644
index 0000000..e73af97
--- /dev/null
+++ b/Documentation/i2c/busses/i2c-parport-light.rst
@@ -0,0 +1,24 @@
+===============================
+Kernel driver i2c-parport-light
+===============================
+
+Author: Jean Delvare <jdelvare@suse.de>
+
+This driver is a light version of i2c-parport. It doesn't depend
+on the parport driver, and uses direct I/O access instead. This might be
+preferred on embedded systems where wasting memory for the clean but heavy
+parport handling is not an option. The drawback is a reduced portability
+and the impossibility to daisy-chain other parallel port devices.
+
+Please see i2c-parport for documentation.
+
+Module parameters:
+
+* type: type of adapter (see i2c-parport or modinfo)
+
+* base: base I/O address
+ Default is 0x378 which is fairly common for parallel ports, at least on PC.
+
+* irq: optional IRQ
+ This must be passed if you want SMBus alert support, assuming your adapter
+ actually supports this.
diff --git a/Documentation/i2c/busses/i2c-parport.rst b/Documentation/i2c/busses/i2c-parport.rst
new file mode 100644
index 0000000..a9b4e81
--- /dev/null
+++ b/Documentation/i2c/busses/i2c-parport.rst
@@ -0,0 +1,190 @@
+=========================
+Kernel driver i2c-parport
+=========================
+
+Author: Jean Delvare <jdelvare@suse.de>
+
+This is a unified driver for several i2c-over-parallel-port adapters,
+such as the ones made by Philips, Velleman or ELV. This driver is
+meant as a replacement for the older, individual drivers:
+
+ * i2c-philips-par
+ * i2c-elv
+ * i2c-velleman
+ * video/i2c-parport
+ (NOT the same as this one, dedicated to home brew teletext adapters)
+
+It currently supports the following devices:
+
+ * (type=0) Philips adapter
+ * (type=1) home brew teletext adapter
+ * (type=2) Velleman K8000 adapter
+ * (type=3) ELV adapter
+ * (type=4) Analog Devices ADM1032 evaluation board
+ * (type=5) Analog Devices evaluation boards: ADM1025, ADM1030, ADM1031
+ * (type=6) Barco LPT->DVI (K5800236) adapter
+ * (type=7) One For All JP1 parallel port adapter
+ * (type=8) VCT-jig
+
+These devices use different pinout configurations, so you have to tell
+the driver what you have, using the type module parameter. There is no
+way to autodetect the devices. Support for different pinout configurations
+can be easily added when needed.
+
+Earlier kernels defaulted to type=0 (Philips). But now, if the type
+parameter is missing, the driver will simply fail to initialize.
+
+SMBus alert support is available on adapters which have this line properly
+connected to the parallel port's interrupt pin.
+
+
+Building your own adapter
+-------------------------
+
+If you want to build you own i2c-over-parallel-port adapter, here is
+a sample electronics schema (credits go to Sylvain Munaut)::
+
+ Device PC
+ Side ___________________Vdd (+) Side
+ | | |
+ --- --- ---
+ | | | | | |
+ |R| |R| |R|
+ | | | | | |
+ --- --- ---
+ | | |
+ | | /| |
+ SCL ----------x--------o |-----------x------------------- pin 2
+ | \| | |
+ | | |
+ | |\ | |
+ SDA ----------x----x---| o---x--------------------------- pin 13
+ | |/ |
+ | |
+ | /| |
+ ---------o |----------------x-------------- pin 3
+ \| | |
+ | |
+ --- ---
+ | | | |
+ |R| |R|
+ | | | |
+ --- ---
+ | |
+ ### ###
+ GND GND
+
+Remarks:
+ - This is the exact pinout and electronics used on the Analog Devices
+ evaluation boards.
+ - All inverters::
+
+ /|
+ -o |-
+ \|
+
+ must be 74HC05, they must be open collector output.
+ - All resitors are 10k.
+ - Pins 18-25 of the parallel port connected to GND.
+ - Pins 4-9 (D2-D7) could be used as VDD is the driver drives them high.
+ The ADM1032 evaluation board uses D4-D7. Beware that the amount of
+ current you can draw from the parallel port is limited. Also note that
+ all connected lines MUST BE driven at the same state, else you'll short
+ circuit the output buffers! So plugging the I2C adapter after loading
+ the i2c-parport module might be a good safety since data line state
+ prior to init may be unknown.
+ - This is 5V!
+ - Obviously you cannot read SCL (so it's not really standard-compliant).
+ Pretty easy to add, just copy the SDA part and use another input pin.
+ That would give (ELV compatible pinout)::
+
+
+ Device PC
+ Side ______________________________Vdd (+) Side
+ | | | |
+ --- --- --- ---
+ | | | | | | | |
+ |R| |R| |R| |R|
+ | | | | | | | |
+ --- --- --- ---
+ | | | |
+ | | |\ | |
+ SCL ----------x--------x--| o---x------------------------ pin 15
+ | | |/ |
+ | | |
+ | | /| |
+ | ---o |-------------x-------------- pin 2
+ | \| | |
+ | | |
+ | | |
+ | |\ | |
+ SDA ---------------x---x--| o--------x------------------- pin 10
+ | |/ |
+ | |
+ | /| |
+ ---o |------------------x--------- pin 3
+ \| | |
+ | |
+ --- ---
+ | | | |
+ |R| |R|
+ | | | |
+ --- ---
+ | |
+ ### ###
+ GND GND
+
+
+If possible, you should use the same pinout configuration as existing
+adapters do, so you won't even have to change the code.
+
+
+Similar (but different) drivers
+-------------------------------
+
+This driver is NOT the same as the i2c-pport driver found in the i2c
+package. The i2c-pport driver makes use of modern parallel port features so
+that you don't need additional electronics. It has other restrictions
+however, and was not ported to Linux 2.6 (yet).
+
+This driver is also NOT the same as the i2c-pcf-epp driver found in the
+lm_sensors package. The i2c-pcf-epp driver doesn't use the parallel port as
+an I2C bus directly. Instead, it uses it to control an external I2C bus
+master. That driver was not ported to Linux 2.6 (yet) either.
+
+
+Legacy documentation for Velleman adapter
+-----------------------------------------
+
+Useful links:
+
+- Velleman http://www.velleman.be/
+- Velleman K8000 Howto http://howto.htlw16.ac.at/k8000-howto.html
+
+The project has lead to new libs for the Velleman K8000 and K8005:
+
+ LIBK8000 v1.99.1 and LIBK8005 v0.21
+
+With these libs, you can control the K8000 interface card and the K8005
+stepper motor card with the simple commands which are in the original
+Velleman software, like SetIOchannel, ReadADchannel, SendStepCCWFull and
+many more, using /dev/velleman.
+
+ - http://home.wanadoo.nl/hihihi/libk8000.htm
+ - http://home.wanadoo.nl/hihihi/libk8005.htm
+ - http://struyve.mine.nu:8080/index.php?block=k8000
+ - http://sourceforge.net/projects/libk8005/
+
+
+One For All JP1 parallel port adapter
+-------------------------------------
+
+The JP1 project revolves around a set of remote controls which expose
+the I2C bus their internal configuration EEPROM lives on via a 6 pin
+jumper in the battery compartment. More details can be found at:
+
+http://www.hifi-remote.com/jp1/
+
+Details of the simple parallel port hardware can be found at:
+
+http://www.hifi-remote.com/jp1/hardware.shtml
diff --git a/Documentation/i2c/busses/i2c-pca-isa b/Documentation/i2c/busses/i2c-pca-isa
deleted file mode 100644
index b044e52..0000000
--- a/Documentation/i2c/busses/i2c-pca-isa
+++ /dev/null
@@ -1,23 +0,0 @@
-Kernel driver i2c-pca-isa
-
-Supported adapters:
-This driver supports ISA boards using the Philips PCA 9564
-Parallel bus to I2C bus controller
-
-Author: Ian Campbell <icampbell@arcom.com>, Arcom Control Systems
-
-Module Parameters
------------------
-
-* base int
- I/O base address
-* irq int
- IRQ interrupt
-* clock int
- Clock rate as described in table 1 of PCA9564 datasheet
-
-Description
------------
-
-This driver supports ISA boards using the Philips PCA 9564
-Parallel bus to I2C bus controller
diff --git a/Documentation/i2c/busses/i2c-pca-isa.rst b/Documentation/i2c/busses/i2c-pca-isa.rst
new file mode 100644
index 0000000..a254010
--- /dev/null
+++ b/Documentation/i2c/busses/i2c-pca-isa.rst
@@ -0,0 +1,26 @@
+=========================
+Kernel driver i2c-pca-isa
+=========================
+
+Supported adapters:
+
+This driver supports ISA boards using the Philips PCA 9564
+Parallel bus to I2C bus controller
+
+Author: Ian Campbell <icampbell@arcom.com>, Arcom Control Systems
+
+Module Parameters
+-----------------
+
+* base int
+ I/O base address
+* irq int
+ IRQ interrupt
+* clock int
+ Clock rate as described in table 1 of PCA9564 datasheet
+
+Description
+-----------
+
+This driver supports ISA boards using the Philips PCA 9564
+Parallel bus to I2C bus controller
diff --git a/Documentation/i2c/busses/i2c-piix4 b/Documentation/i2c/busses/i2c-piix4
deleted file mode 100644
index 2703bc3..0000000
--- a/Documentation/i2c/busses/i2c-piix4
+++ /dev/null
@@ -1,112 +0,0 @@
-Kernel driver i2c-piix4
-
-Supported adapters:
- * Intel 82371AB PIIX4 and PIIX4E
- * Intel 82443MX (440MX)
- Datasheet: Publicly available at the Intel website
- * ServerWorks OSB4, CSB5, CSB6, HT-1000 and HT-1100 southbridges
- Datasheet: Only available via NDA from ServerWorks
- * ATI IXP200, IXP300, IXP400, SB600, SB700 and SB800 southbridges
- Datasheet: Not publicly available
- SB700 register reference available at:
- http://support.amd.com/us/Embedded_TechDocs/43009_sb7xx_rrg_pub_1.00.pdf
- * AMD SP5100 (SB700 derivative found on some server mainboards)
- Datasheet: Publicly available at the AMD website
- http://support.amd.com/us/Embedded_TechDocs/44413.pdf
- * AMD Hudson-2, ML, CZ
- Datasheet: Not publicly available
- * Hygon CZ
- Datasheet: Not publicly available
- * Standard Microsystems (SMSC) SLC90E66 (Victory66) southbridge
- Datasheet: Publicly available at the SMSC website http://www.smsc.com
-
-Authors:
- Frodo Looijaard <frodol@dds.nl>
- Philip Edelbrock <phil@netroedge.com>
-
-
-Module Parameters
------------------
-
-* force: int
- Forcibly enable the PIIX4. DANGEROUS!
-* force_addr: int
- Forcibly enable the PIIX4 at the given address. EXTREMELY DANGEROUS!
-
-
-Description
------------
-
-The PIIX4 (properly known as the 82371AB) is an Intel chip with a lot of
-functionality. Among other things, it implements the PCI bus. One of its
-minor functions is implementing a System Management Bus. This is a true
-SMBus - you can not access it on I2C levels. The good news is that it
-natively understands SMBus commands and you do not have to worry about
-timing problems. The bad news is that non-SMBus devices connected to it can
-confuse it mightily. Yes, this is known to happen...
-
-Do 'lspci -v' and see whether it contains an entry like this:
-
-0000:00:02.3 Bridge: Intel Corp. 82371AB/EB/MB PIIX4 ACPI (rev 02)
- Flags: medium devsel, IRQ 9
-
-Bus and device numbers may differ, but the function number must be
-identical (like many PCI devices, the PIIX4 incorporates a number of
-different 'functions', which can be considered as separate devices). If you
-find such an entry, you have a PIIX4 SMBus controller.
-
-On some computers (most notably, some Dells), the SMBus is disabled by
-default. If you use the insmod parameter 'force=1', the kernel module will
-try to enable it. THIS IS VERY DANGEROUS! If the BIOS did not set up a
-correct address for this module, you could get in big trouble (read:
-crashes, data corruption, etc.). Try this only as a last resort (try BIOS
-updates first, for example), and backup first! An even more dangerous
-option is 'force_addr=<IOPORT>'. This will not only enable the PIIX4 like
-'force' foes, but it will also set a new base I/O port address. The SMBus
-parts of the PIIX4 needs a range of 8 of these addresses to function
-correctly. If these addresses are already reserved by some other device,
-you will get into big trouble! DON'T USE THIS IF YOU ARE NOT VERY SURE
-ABOUT WHAT YOU ARE DOING!
-
-The PIIX4E is just an new version of the PIIX4; it is supported as well.
-The PIIX/PIIX3 does not implement an SMBus or I2C bus, so you can't use
-this driver on those mainboards.
-
-The ServerWorks Southbridges, the Intel 440MX, and the Victory66 are
-identical to the PIIX4 in I2C/SMBus support.
-
-The AMD SB700, SB800, SP5100 and Hudson-2 chipsets implement two
-PIIX4-compatible SMBus controllers. If your BIOS initializes the
-secondary controller, it will be detected by this driver as
-an "Auxiliary SMBus Host Controller".
-
-If you own Force CPCI735 motherboard or other OSB4 based systems you may need
-to change the SMBus Interrupt Select register so the SMBus controller uses
-the SMI mode.
-
-1) Use lspci command and locate the PCI device with the SMBus controller:
- 00:0f.0 ISA bridge: ServerWorks OSB4 South Bridge (rev 4f)
- The line may vary for different chipsets. Please consult the driver source
- for all possible PCI ids (and lspci -n to match them). Lets assume the
- device is located at 00:0f.0.
-2) Now you just need to change the value in 0xD2 register. Get it first with
- command: lspci -xxx -s 00:0f.0
- If the value is 0x3 then you need to change it to 0x1
- setpci -s 00:0f.0 d2.b=1
-
-Please note that you don't need to do that in all cases, just when the SMBus is
-not working properly.
-
-
-Hardware-specific issues
-------------------------
-
-This driver will refuse to load on IBM systems with an Intel PIIX4 SMBus.
-Some of these machines have an RFID EEPROM (24RF08) connected to the SMBus,
-which can easily get corrupted due to a state machine bug. These are mostly
-Thinkpad laptops, but desktop systems may also be affected. We have no list
-of all affected systems, so the only safe solution was to prevent access to
-the SMBus on all IBM systems (detected using DMI data.)
-
-For additional information, read:
-http://www.lm-sensors.org/browser/lm-sensors/trunk/README
diff --git a/Documentation/i2c/busses/i2c-piix4.rst b/Documentation/i2c/busses/i2c-piix4.rst
new file mode 100644
index 0000000..cc90002
--- /dev/null
+++ b/Documentation/i2c/busses/i2c-piix4.rst
@@ -0,0 +1,114 @@
+=======================
+Kernel driver i2c-piix4
+=======================
+
+Supported adapters:
+ * Intel 82371AB PIIX4 and PIIX4E
+ * Intel 82443MX (440MX)
+ Datasheet: Publicly available at the Intel website
+ * ServerWorks OSB4, CSB5, CSB6, HT-1000 and HT-1100 southbridges
+ Datasheet: Only available via NDA from ServerWorks
+ * ATI IXP200, IXP300, IXP400, SB600, SB700 and SB800 southbridges
+ Datasheet: Not publicly available
+ SB700 register reference available at:
+ http://support.amd.com/us/Embedded_TechDocs/43009_sb7xx_rrg_pub_1.00.pdf
+ * AMD SP5100 (SB700 derivative found on some server mainboards)
+ Datasheet: Publicly available at the AMD website
+ http://support.amd.com/us/Embedded_TechDocs/44413.pdf
+ * AMD Hudson-2, ML, CZ
+ Datasheet: Not publicly available
+ * Hygon CZ
+ Datasheet: Not publicly available
+ * Standard Microsystems (SMSC) SLC90E66 (Victory66) southbridge
+ Datasheet: Publicly available at the SMSC website http://www.smsc.com
+
+Authors:
+ - Frodo Looijaard <frodol@dds.nl>
+ - Philip Edelbrock <phil@netroedge.com>
+
+
+Module Parameters
+-----------------
+
+* force: int
+ Forcibly enable the PIIX4. DANGEROUS!
+* force_addr: int
+ Forcibly enable the PIIX4 at the given address. EXTREMELY DANGEROUS!
+
+
+Description
+-----------
+
+The PIIX4 (properly known as the 82371AB) is an Intel chip with a lot of
+functionality. Among other things, it implements the PCI bus. One of its
+minor functions is implementing a System Management Bus. This is a true
+SMBus - you can not access it on I2C levels. The good news is that it
+natively understands SMBus commands and you do not have to worry about
+timing problems. The bad news is that non-SMBus devices connected to it can
+confuse it mightily. Yes, this is known to happen...
+
+Do ``lspci -v`` and see whether it contains an entry like this::
+
+ 0000:00:02.3 Bridge: Intel Corp. 82371AB/EB/MB PIIX4 ACPI (rev 02)
+ Flags: medium devsel, IRQ 9
+
+Bus and device numbers may differ, but the function number must be
+identical (like many PCI devices, the PIIX4 incorporates a number of
+different 'functions', which can be considered as separate devices). If you
+find such an entry, you have a PIIX4 SMBus controller.
+
+On some computers (most notably, some Dells), the SMBus is disabled by
+default. If you use the insmod parameter 'force=1', the kernel module will
+try to enable it. THIS IS VERY DANGEROUS! If the BIOS did not set up a
+correct address for this module, you could get in big trouble (read:
+crashes, data corruption, etc.). Try this only as a last resort (try BIOS
+updates first, for example), and backup first! An even more dangerous
+option is 'force_addr=<IOPORT>'. This will not only enable the PIIX4 like
+'force' foes, but it will also set a new base I/O port address. The SMBus
+parts of the PIIX4 needs a range of 8 of these addresses to function
+correctly. If these addresses are already reserved by some other device,
+you will get into big trouble! DON'T USE THIS IF YOU ARE NOT VERY SURE
+ABOUT WHAT YOU ARE DOING!
+
+The PIIX4E is just an new version of the PIIX4; it is supported as well.
+The PIIX/PIIX3 does not implement an SMBus or I2C bus, so you can't use
+this driver on those mainboards.
+
+The ServerWorks Southbridges, the Intel 440MX, and the Victory66 are
+identical to the PIIX4 in I2C/SMBus support.
+
+The AMD SB700, SB800, SP5100 and Hudson-2 chipsets implement two
+PIIX4-compatible SMBus controllers. If your BIOS initializes the
+secondary controller, it will be detected by this driver as
+an "Auxiliary SMBus Host Controller".
+
+If you own Force CPCI735 motherboard or other OSB4 based systems you may need
+to change the SMBus Interrupt Select register so the SMBus controller uses
+the SMI mode.
+
+1) Use lspci command and locate the PCI device with the SMBus controller:
+ 00:0f.0 ISA bridge: ServerWorks OSB4 South Bridge (rev 4f)
+ The line may vary for different chipsets. Please consult the driver source
+ for all possible PCI ids (and lspci -n to match them). Lets assume the
+ device is located at 00:0f.0.
+2) Now you just need to change the value in 0xD2 register. Get it first with
+ command: lspci -xxx -s 00:0f.0
+ If the value is 0x3 then you need to change it to 0x1:
+ setpci -s 00:0f.0 d2.b=1
+
+Please note that you don't need to do that in all cases, just when the SMBus is
+not working properly.
+
+
+Hardware-specific issues
+------------------------
+
+This driver will refuse to load on IBM systems with an Intel PIIX4 SMBus.
+Some of these machines have an RFID EEPROM (24RF08) connected to the SMBus,
+which can easily get corrupted due to a state machine bug. These are mostly
+Thinkpad laptops, but desktop systems may also be affected. We have no list
+of all affected systems, so the only safe solution was to prevent access to
+the SMBus on all IBM systems (detected using DMI data.)
+
+For additional information, read:
+http://www.lm-sensors.org/browser/lm-sensors/trunk/README
diff --git a/Documentation/i2c/busses/i2c-sis5595 b/Documentation/i2c/busses/i2c-sis5595
deleted file mode 100644
index ecd21fb..0000000
--- a/Documentation/i2c/busses/i2c-sis5595
+++ /dev/null
@@ -1,59 +0,0 @@
-Kernel driver i2c-sis5595
-
-Authors:
- Frodo Looijaard <frodol@dds.nl>,
- Mark D. Studebaker <mdsxyz123@yahoo.com>,
- Philip Edelbrock <phil@netroedge.com>
-
-Supported adapters:
- * Silicon Integrated Systems Corp. SiS5595 Southbridge
- Datasheet: Publicly available at the Silicon Integrated Systems Corp. site.
-
-Note: all have mfr. ID 0x1039.
-
- SUPPORTED PCI ID
- 5595 0008
-
- Note: these chips contain a 0008 device which is incompatible with the
- 5595. We recognize these by the presence of the listed
- "blacklist" PCI ID and refuse to load.
-
- NOT SUPPORTED PCI ID BLACKLIST PCI ID
- 540 0008 0540
- 550 0008 0550
- 5513 0008 5511
- 5581 0008 5597
- 5582 0008 5597
- 5597 0008 5597
- 5598 0008 5597/5598
- 630 0008 0630
- 645 0008 0645
- 646 0008 0646
- 648 0008 0648
- 650 0008 0650
- 651 0008 0651
- 730 0008 0730
- 735 0008 0735
- 745 0008 0745
- 746 0008 0746
-
-Module Parameters
------------------
-
-* force_addr=0xaddr Set the I/O base address. Useful for boards
- that don't set the address in the BIOS. Does not do a
- PCI force; the device must still be present in lspci.
- Don't use this unless the driver complains that the
- base address is not set.
-
-Description
------------
-
-i2c-sis5595 is a true SMBus host driver for motherboards with the SiS5595
-southbridges.
-
-WARNING: If you are trying to access the integrated sensors on the SiS5595
-chip, you want the sis5595 driver for those, not this driver. This driver
-is a BUS driver, not a CHIP driver. A BUS driver is used by other CHIP
-drivers to access chips on the bus.
-
diff --git a/Documentation/i2c/busses/i2c-sis5595.rst b/Documentation/i2c/busses/i2c-sis5595.rst
new file mode 100644
index 0000000..b85630c
--- /dev/null
+++ b/Documentation/i2c/busses/i2c-sis5595.rst
@@ -0,0 +1,68 @@
+=========================
+Kernel driver i2c-sis5595
+=========================
+
+Authors:
+ - Frodo Looijaard <frodol@dds.nl>,
+ - Mark D. Studebaker <mdsxyz123@yahoo.com>,
+ - Philip Edelbrock <phil@netroedge.com>
+
+Supported adapters:
+ * Silicon Integrated Systems Corp. SiS5595 Southbridge
+ Datasheet: Publicly available at the Silicon Integrated Systems Corp. site.
+
+Note: all have mfr. ID 0x1039.
+
+ ========= ======
+ SUPPORTED PCI ID
+ ========= ======
+ 5595 0008
+ ========= ======
+
+ Note: these chips contain a 0008 device which is incompatible with the
+ 5595. We recognize these by the presence of the listed
+ "blacklist" PCI ID and refuse to load.
+
+ ============= ====== ================
+ NOT SUPPORTED PCI ID BLACKLIST PCI ID
+ ============= ====== ================
+ 540 0008 0540
+ 550 0008 0550
+ 5513 0008 5511
+ 5581 0008 5597
+ 5582 0008 5597
+ 5597 0008 5597
+ 5598 0008 5597/5598
+ 630 0008 0630
+ 645 0008 0645
+ 646 0008 0646
+ 648 0008 0648
+ 650 0008 0650
+ 651 0008 0651
+ 730 0008 0730
+ 735 0008 0735
+ 745 0008 0745
+ 746 0008 0746
+ ============= ====== ================
+
+Module Parameters
+-----------------
+
+================== =====================================================
+force_addr=0xaddr Set the I/O base address. Useful for boards
+ that don't set the address in the BIOS. Does not do a
+ PCI force; the device must still be present in lspci.
+ Don't use this unless the driver complains that the
+ base address is not set.
+================== =====================================================
+
+Description
+-----------
+
+i2c-sis5595 is a true SMBus host driver for motherboards with the SiS5595
+southbridges.
+
+WARNING: If you are trying to access the integrated sensors on the SiS5595
+chip, you want the sis5595 driver for those, not this driver. This driver
+is a BUS driver, not a CHIP driver. A BUS driver is used by other CHIP
+drivers to access chips on the bus.
diff --git a/Documentation/i2c/busses/i2c-sis630 b/Documentation/i2c/busses/i2c-sis630
deleted file mode 100644
index ee79436..0000000
--- a/Documentation/i2c/busses/i2c-sis630
+++ /dev/null
@@ -1,58 +0,0 @@
-Kernel driver i2c-sis630
-
-Supported adapters:
- * Silicon Integrated Systems Corp (SiS)
- 630 chipset (Datasheet: available at http://www.sfr-fresh.com/linux)
- 730 chipset
- 964 chipset
- * Possible other SiS chipsets ?
-
-Author: Alexander Malysh <amalysh@web.de>
- Amaury Decrême <amaury.decreme@gmail.com> - SiS964 support
-
-Module Parameters
------------------
-
-* force = [1|0] Forcibly enable the SIS630. DANGEROUS!
- This can be interesting for chipsets not named
- above to check if it works for you chipset, but DANGEROUS!
-
-* high_clock = [1|0] Forcibly set Host Master Clock to 56KHz (default,
- what your BIOS use). DANGEROUS! This should be a bit
- faster, but freeze some systems (i.e. my Laptop).
- SIS630/730 chip only.
-
-
-Description
------------
-
-This SMBus only driver is known to work on motherboards with the above
-named chipsets.
-
-If you see something like this:
-
-00:00.0 Host bridge: Silicon Integrated Systems [SiS] 630 Host (rev 31)
-00:01.0 ISA bridge: Silicon Integrated Systems [SiS] 85C503/5513
-
-or like this:
-
-00:00.0 Host bridge: Silicon Integrated Systems [SiS] 730 Host (rev 02)
-00:01.0 ISA bridge: Silicon Integrated Systems [SiS] 85C503/5513
-
-or like this:
-
-00:00.0 Host bridge: Silicon Integrated Systems [SiS] 760/M760 Host (rev 02)
-00:02.0 ISA bridge: Silicon Integrated Systems [SiS] SiS964 [MuTIOL Media IO]
- LPC Controller (rev 36)
-
-in your 'lspci' output , then this driver is for your chipset.
-
-Thank You
----------
-Philip Edelbrock <phil@netroedge.com>
-- testing SiS730 support
-Mark M. Hoffman <mhoffman@lightlink.com>
-- bug fixes
-
-To anyone else which I forgot here ;), thanks!
-
diff --git a/Documentation/i2c/busses/i2c-sis630.rst b/Documentation/i2c/busses/i2c-sis630.rst
new file mode 100644
index 0000000..9fcd74b
--- /dev/null
+++ b/Documentation/i2c/busses/i2c-sis630.rst
@@ -0,0 +1,63 @@
+========================
+Kernel driver i2c-sis630
+========================
+
+Supported adapters:
+ * Silicon Integrated Systems Corp (SiS)
+ 630 chipset (Datasheet: available at http://www.sfr-fresh.com/linux)
+ 730 chipset
+ 964 chipset
+ * Possible other SiS chipsets ?
+
+Author:
+ - Alexander Malysh <amalysh@web.de>
+ - Amaury Decrême <amaury.decreme@gmail.com> - SiS964 support
+
+Module Parameters
+-----------------
+
+================== =====================================================
+force = [1|0] Forcibly enable the SIS630. DANGEROUS!
+ This can be interesting for chipsets not named
+ above to check if it works for you chipset,
+ but DANGEROUS!
+
+high_clock = [1|0] Forcibly set Host Master Clock to 56KHz (default,
+ what your BIOS use). DANGEROUS! This should be a bit
+ faster, but freeze some systems (i.e. my Laptop).
+ SIS630/730 chip only.
+================== =====================================================
+
+
+Description
+-----------
+
+This SMBus only driver is known to work on motherboards with the above
+named chipsets.
+
+If you see something like this::
+
+ 00:00.0 Host bridge: Silicon Integrated Systems [SiS] 630 Host (rev 31)
+ 00:01.0 ISA bridge: Silicon Integrated Systems [SiS] 85C503/5513
+
+or like this::
+
+ 00:00.0 Host bridge: Silicon Integrated Systems [SiS] 730 Host (rev 02)
+ 00:01.0 ISA bridge: Silicon Integrated Systems [SiS] 85C503/5513
+
+or like this::
+
+ 00:00.0 Host bridge: Silicon Integrated Systems [SiS] 760/M760 Host (rev 02)
+ 00:02.0 ISA bridge: Silicon Integrated Systems [SiS] SiS964 [MuTIOL Media IO]
+ LPC Controller (rev 36)
+
+in your ``lspci`` output , then this driver is for your chipset.
+
+Thank You
+---------
+Philip Edelbrock <phil@netroedge.com>
+- testing SiS730 support
+Mark M. Hoffman <mhoffman@lightlink.com>
+- bug fixes
+
+To anyone else which I forgot here ;), thanks!
diff --git a/Documentation/i2c/busses/i2c-sis96x b/Documentation/i2c/busses/i2c-sis96x
deleted file mode 100644
index 0b979f3..0000000
--- a/Documentation/i2c/busses/i2c-sis96x
+++ /dev/null
@@ -1,73 +0,0 @@
-Kernel driver i2c-sis96x
-
-Replaces 2.4.x i2c-sis645
-
-Supported adapters:
- * Silicon Integrated Systems Corp (SiS)
- Any combination of these host bridges:
- 645, 645DX (aka 646), 648, 650, 651, 655, 735, 745, 746
- and these south bridges:
- 961, 962, 963(L)
-
-Author: Mark M. Hoffman <mhoffman@lightlink.com>
-
-Description
------------
-
-This SMBus only driver is known to work on motherboards with the above
-named chipset combinations. The driver was developed without benefit of a
-proper datasheet from SiS. The SMBus registers are assumed compatible with
-those of the SiS630, although they are located in a completely different
-place. Thanks to Alexander Malysh <amalysh@web.de> for providing the
-SiS630 datasheet (and driver).
-
-The command "lspci" as root should produce something like these lines:
-
-00:00.0 Host bridge: Silicon Integrated Systems [SiS]: Unknown device 0645
-00:02.0 ISA bridge: Silicon Integrated Systems [SiS] 85C503/5513
-00:02.1 SMBus: Silicon Integrated Systems [SiS]: Unknown device 0016
-
-or perhaps this...
-
-00:00.0 Host bridge: Silicon Integrated Systems [SiS]: Unknown device 0645
-00:02.0 ISA bridge: Silicon Integrated Systems [SiS]: Unknown device 0961
-00:02.1 SMBus: Silicon Integrated Systems [SiS]: Unknown device 0016
-
-(kernel versions later than 2.4.18 may fill in the "Unknown"s)
-
-If you can't see it please look on quirk_sis_96x_smbus
-(drivers/pci/quirks.c) (also if southbridge detection fails)
-
-I suspect that this driver could be made to work for the following SiS
-chipsets as well: 635, and 635T. If anyone owns a board with those chips
-AND is willing to risk crashing & burning an otherwise well-behaved kernel
-in the name of progress... please contact me at <mhoffman@lightlink.com> or
-via the linux-i2c mailing list: <linux-i2c@vger.kernel.org>. Please send bug
-reports and/or success stories as well.
-
-
-TO DOs
-------
-
-* The driver does not support SMBus block reads/writes; I may add them if a
-scenario is found where they're needed.
-
-
-Thank You
----------
-
-Mark D. Studebaker <mdsxyz123@yahoo.com>
- - design hints and bug fixes
-Alexander Maylsh <amalysh@web.de>
- - ditto, plus an important datasheet... almost the one I really wanted
-Hans-Günter Lütke Uphues <hg_lu@t-online.de>
- - patch for SiS735
-Robert Zwerus <arzie@dds.nl>
- - testing for SiS645DX
-Kianusch Sayah Karadji <kianusch@sk-tech.net>
- - patch for SiS645DX/962
-Ken Healy
- - patch for SiS655
-
-To anyone else who has written w/ feedback, thanks!
-
diff --git a/Documentation/i2c/busses/i2c-sis96x.rst b/Documentation/i2c/busses/i2c-sis96x.rst
new file mode 100644
index 0000000..437cc1d
--- /dev/null
+++ b/Documentation/i2c/busses/i2c-sis96x.rst
@@ -0,0 +1,82 @@
+========================
+Kernel driver i2c-sis96x
+========================
+
+Replaces 2.4.x i2c-sis645
+
+Supported adapters:
+
+ * Silicon Integrated Systems Corp (SiS)
+
+ Any combination of these host bridges:
+ 645, 645DX (aka 646), 648, 650, 651, 655, 735, 745, 746
+
+ and these south bridges:
+ 961, 962, 963(L)
+
+Author: Mark M. Hoffman <mhoffman@lightlink.com>
+
+Description
+-----------
+
+This SMBus only driver is known to work on motherboards with the above
+named chipset combinations. The driver was developed without benefit of a
+proper datasheet from SiS. The SMBus registers are assumed compatible with
+those of the SiS630, although they are located in a completely different
+place. Thanks to Alexander Malysh <amalysh@web.de> for providing the
+SiS630 datasheet (and driver).
+
+The command ``lspci`` as root should produce something like these lines::
+
+ 00:00.0 Host bridge: Silicon Integrated Systems [SiS]: Unknown device 0645
+ 00:02.0 ISA bridge: Silicon Integrated Systems [SiS] 85C503/5513
+ 00:02.1 SMBus: Silicon Integrated Systems [SiS]: Unknown device 0016
+
+or perhaps this::
+
+ 00:00.0 Host bridge: Silicon Integrated Systems [SiS]: Unknown device 0645
+ 00:02.0 ISA bridge: Silicon Integrated Systems [SiS]: Unknown device 0961
+ 00:02.1 SMBus: Silicon Integrated Systems [SiS]: Unknown device 0016
+
+(kernel versions later than 2.4.18 may fill in the "Unknown"s)
+
+If you can't see it please look on quirk_sis_96x_smbus
+(drivers/pci/quirks.c) (also if southbridge detection fails)
+
+I suspect that this driver could be made to work for the following SiS
+chipsets as well: 635, and 635T. If anyone owns a board with those chips
+AND is willing to risk crashing & burning an otherwise well-behaved kernel
+in the name of progress... please contact me at <mhoffman@lightlink.com> or
+via the linux-i2c mailing list: <linux-i2c@vger.kernel.org>. Please send bug
+reports and/or success stories as well.
+
+
+TO DOs
+------
+
+* The driver does not support SMBus block reads/writes; I may add them if a
+ scenario is found where they're needed.
+
+
+Thank You
+---------
+
+Mark D. Studebaker <mdsxyz123@yahoo.com>
+ - design hints and bug fixes
+
+Alexander Maylsh <amalysh@web.de>
+ - ditto, plus an important datasheet... almost the one I really wanted
+
+Hans-Günter Lütke Uphues <hg_lu@t-online.de>
+ - patch for SiS735
+
+Robert Zwerus <arzie@dds.nl>
+ - testing for SiS645DX
+
+Kianusch Sayah Karadji <kianusch@sk-tech.net>
+ - patch for SiS645DX/962
+
+Ken Healy
+ - patch for SiS655
+
+To anyone else who has written w/ feedback, thanks!
diff --git a/Documentation/i2c/busses/i2c-taos-evm b/Documentation/i2c/busses/i2c-taos-evm
deleted file mode 100644
index 6029955..0000000
--- a/Documentation/i2c/busses/i2c-taos-evm
+++ /dev/null
@@ -1,46 +0,0 @@
-Kernel driver i2c-taos-evm
-
-Author: Jean Delvare <jdelvare@suse.de>
-
-This is a driver for the evaluation modules for TAOS I2C/SMBus chips.
-The modules include an SMBus master with limited capabilities, which can
-be controlled over the serial port. Virtually all evaluation modules
-are supported, but a few lines of code need to be added for each new
-module to instantiate the right I2C chip on the bus. Obviously, a driver
-for the chip in question is also needed.
-
-Currently supported devices are:
-
-* TAOS TSL2550 EVM
-
-For additional information on TAOS products, please see
- http://www.taosinc.com/
-
-
-Using this driver
------------------
-
-In order to use this driver, you'll need the serport driver, and the
-inputattach tool, which is part of the input-utils package. The following
-commands will tell the kernel that you have a TAOS EVM on the first
-serial port:
-
-# modprobe serport
-# inputattach --taos-evm /dev/ttyS0
-
-
-Technical details
------------------
-
-Only 4 SMBus transaction types are supported by the TAOS evaluation
-modules:
-* Receive Byte
-* Send Byte
-* Read Byte
-* Write Byte
-
-The communication protocol is text-based and pretty simple. It is
-described in a PDF document on the CD which comes with the evaluation
-module. The communication is rather slow, because the serial port has
-to operate at 1200 bps. However, I don't think this is a big concern in
-practice, as these modules are meant for evaluation and testing only.
diff --git a/Documentation/i2c/busses/i2c-taos-evm.rst b/Documentation/i2c/busses/i2c-taos-evm.rst
new file mode 100644
index 0000000..f342e31
--- /dev/null
+++ b/Documentation/i2c/busses/i2c-taos-evm.rst
@@ -0,0 +1,48 @@
+==========================
+Kernel driver i2c-taos-evm
+==========================
+
+Author: Jean Delvare <jdelvare@suse.de>
+
+This is a driver for the evaluation modules for TAOS I2C/SMBus chips.
+The modules include an SMBus master with limited capabilities, which can
+be controlled over the serial port. Virtually all evaluation modules
+are supported, but a few lines of code need to be added for each new
+module to instantiate the right I2C chip on the bus. Obviously, a driver
+for the chip in question is also needed.
+
+Currently supported devices are:
+
+* TAOS TSL2550 EVM
+
+For additional information on TAOS products, please see
+ http://www.taosinc.com/
+
+
+Using this driver
+-----------------
+
+In order to use this driver, you'll need the serport driver, and the
+inputattach tool, which is part of the input-utils package. The following
+commands will tell the kernel that you have a TAOS EVM on the first
+serial port::
+
+ # modprobe serport
+ # inputattach --taos-evm /dev/ttyS0
+
+
+Technical details
+-----------------
+
+Only 4 SMBus transaction types are supported by the TAOS evaluation
+modules:
+* Receive Byte
+* Send Byte
+* Read Byte
+* Write Byte
+
+The communication protocol is text-based and pretty simple. It is
+described in a PDF document on the CD which comes with the evaluation
+module. The communication is rather slow, because the serial port has
+to operate at 1200 bps. However, I don't think this is a big concern in
+practice, as these modules are meant for evaluation and testing only.
diff --git a/Documentation/i2c/busses/i2c-via b/Documentation/i2c/busses/i2c-via
deleted file mode 100644
index 3438706..0000000
--- a/Documentation/i2c/busses/i2c-via
+++ /dev/null
@@ -1,34 +0,0 @@
-Kernel driver i2c-via
-
-Supported adapters:
- * VIA Technologies, InC. VT82C586B
- Datasheet: Publicly available at the VIA website
-
-Author: Kyösti Mälkki <kmalkki@cc.hut.fi>
-
-Description
------------
-
-i2c-via is an i2c bus driver for motherboards with VIA chipset.
-
-The following VIA pci chipsets are supported:
- - MVP3, VP3, VP2/97, VPX/97
- - others with South bridge VT82C586B
-
-Your lspci listing must show this :
-
- Bridge: VIA Technologies, Inc. VT82C586B ACPI (rev 10)
-
- Problems?
-
- Q: You have VT82C586B on the motherboard, but not in the listing.
-
- A: Go to your BIOS setup, section PCI devices or similar.
- Turn USB support on, and try again.
-
- Q: No error messages, but still i2c doesn't seem to work.
-
- A: This can happen. This driver uses the pins VIA recommends in their
- datasheets, but there are several ways the motherboard manufacturer
- can actually wire the lines.
-
diff --git a/Documentation/i2c/busses/i2c-via.rst b/Documentation/i2c/busses/i2c-via.rst
new file mode 100644
index 0000000..846aa17
--- /dev/null
+++ b/Documentation/i2c/busses/i2c-via.rst
@@ -0,0 +1,40 @@
+=====================
+Kernel driver i2c-via
+=====================
+
+Supported adapters:
+ * VIA Technologies, InC. VT82C586B
+ Datasheet: Publicly available at the VIA website
+
+Author: Kyösti Mälkki <kmalkki@cc.hut.fi>
+
+Description
+-----------
+
+i2c-via is an i2c bus driver for motherboards with VIA chipset.
+
+The following VIA pci chipsets are supported:
+ - MVP3, VP3, VP2/97, VPX/97
+ - others with South bridge VT82C586B
+
+Your ``lspci`` listing must show this ::
+
+ Bridge: VIA Technologies, Inc. VT82C586B ACPI (rev 10)
+
+Problems?
+---------
+
+ Q:
+ You have VT82C586B on the motherboard, but not in the listing.
+
+ A:
+ Go to your BIOS setup, section PCI devices or similar.
+ Turn USB support on, and try again.
+
+ Q:
+ No error messages, but still i2c doesn't seem to work.
+
+ A:
+ This can happen. This driver uses the pins VIA recommends in their
+ datasheets, but there are several ways the motherboard manufacturer
+ can actually wire the lines.
diff --git a/Documentation/i2c/busses/i2c-viapro b/Documentation/i2c/busses/i2c-viapro
deleted file mode 100644
index ab64ce2..0000000
--- a/Documentation/i2c/busses/i2c-viapro
+++ /dev/null
@@ -1,73 +0,0 @@
-Kernel driver i2c-viapro
-
-Supported adapters:
- * VIA Technologies, Inc. VT82C596A/B
- Datasheet: Sometimes available at the VIA website
-
- * VIA Technologies, Inc. VT82C686A/B
- Datasheet: Sometimes available at the VIA website
-
- * VIA Technologies, Inc. VT8231, VT8233, VT8233A
- Datasheet: available on request from VIA
-
- * VIA Technologies, Inc. VT8235, VT8237R, VT8237A, VT8237S, VT8251
- Datasheet: available on request and under NDA from VIA
-
- * VIA Technologies, Inc. CX700
- Datasheet: available on request and under NDA from VIA
-
- * VIA Technologies, Inc. VX800/VX820
- Datasheet: available on http://linux.via.com.tw
-
- * VIA Technologies, Inc. VX855/VX875
- Datasheet: available on http://linux.via.com.tw
-
- * VIA Technologies, Inc. VX900
- Datasheet: available on http://linux.via.com.tw
-
-Authors:
- Kyösti Mälkki <kmalkki@cc.hut.fi>,
- Mark D. Studebaker <mdsxyz123@yahoo.com>,
- Jean Delvare <jdelvare@suse.de>
-
-Module Parameters
------------------
-
-* force: int
- Forcibly enable the SMBus controller. DANGEROUS!
-* force_addr: int
- Forcibly enable the SMBus at the given address. EXTREMELY DANGEROUS!
-
-Description
------------
-
-i2c-viapro is a true SMBus host driver for motherboards with one of the
-supported VIA south bridges.
-
-Your lspci -n listing must show one of these :
-
- device 1106:3050 (VT82C596A function 3)
- device 1106:3051 (VT82C596B function 3)
- device 1106:3057 (VT82C686 function 4)
- device 1106:3074 (VT8233)
- device 1106:3147 (VT8233A)
- device 1106:8235 (VT8231 function 4)
- device 1106:3177 (VT8235)
- device 1106:3227 (VT8237R)
- device 1106:3337 (VT8237A)
- device 1106:3372 (VT8237S)
- device 1106:3287 (VT8251)
- device 1106:8324 (CX700)
- device 1106:8353 (VX800/VX820)
- device 1106:8409 (VX855/VX875)
- device 1106:8410 (VX900)
-
-If none of these show up, you should look in the BIOS for settings like
-enable ACPI / SMBus or even USB.
-
-Except for the oldest chips (VT82C596A/B, VT82C686A and most probably
-VT8231), this driver supports I2C block transactions. Such transactions
-are mainly useful to read from and write to EEPROMs.
-
-The CX700/VX800/VX820 additionally appears to support SMBus PEC, although
-this driver doesn't implement it yet.
diff --git a/Documentation/i2c/busses/i2c-viapro.rst b/Documentation/i2c/busses/i2c-viapro.rst
new file mode 100644
index 0000000..1762f0c
--- /dev/null
+++ b/Documentation/i2c/busses/i2c-viapro.rst
@@ -0,0 +1,77 @@
+========================
+Kernel driver i2c-viapro
+========================
+
+Supported adapters:
+ * VIA Technologies, Inc. VT82C596A/B
+ Datasheet: Sometimes available at the VIA website
+
+ * VIA Technologies, Inc. VT82C686A/B
+ Datasheet: Sometimes available at the VIA website
+
+ * VIA Technologies, Inc. VT8231, VT8233, VT8233A
+ Datasheet: available on request from VIA
+
+ * VIA Technologies, Inc. VT8235, VT8237R, VT8237A, VT8237S, VT8251
+ Datasheet: available on request and under NDA from VIA
+
+ * VIA Technologies, Inc. CX700
+ Datasheet: available on request and under NDA from VIA
+
+ * VIA Technologies, Inc. VX800/VX820
+ Datasheet: available on http://linux.via.com.tw
+
+ * VIA Technologies, Inc. VX855/VX875
+ Datasheet: available on http://linux.via.com.tw
+
+ * VIA Technologies, Inc. VX900
+ Datasheet: available on http://linux.via.com.tw
+
+Authors:
+ - Kyösti Mälkki <kmalkki@cc.hut.fi>,
+ - Mark D. Studebaker <mdsxyz123@yahoo.com>,
+ - Jean Delvare <jdelvare@suse.de>
+
+Module Parameters
+-----------------
+
+* force: int
+ Forcibly enable the SMBus controller. DANGEROUS!
+* force_addr: int
+ Forcibly enable the SMBus at the given address. EXTREMELY DANGEROUS!
+
+Description
+-----------
+
+i2c-viapro is a true SMBus host driver for motherboards with one of the
+supported VIA south bridges.
+
+Your ``lspci -n`` listing must show one of these :
+
+ ================ ======================
+ device 1106:3050 (VT82C596A function 3)
+ device 1106:3051 (VT82C596B function 3)
+ device 1106:3057 (VT82C686 function 4)
+ device 1106:3074 (VT8233)
+ device 1106:3147 (VT8233A)
+ device 1106:8235 (VT8231 function 4)
+ device 1106:3177 (VT8235)
+ device 1106:3227 (VT8237R)
+ device 1106:3337 (VT8237A)
+ device 1106:3372 (VT8237S)
+ device 1106:3287 (VT8251)
+ device 1106:8324 (CX700)
+ device 1106:8353 (VX800/VX820)
+ device 1106:8409 (VX855/VX875)
+ device 1106:8410 (VX900)
+ ================ ======================
+
+If none of these show up, you should look in the BIOS for settings like
+enable ACPI / SMBus or even USB.
+
+Except for the oldest chips (VT82C596A/B, VT82C686A and most probably
+VT8231), this driver supports I2C block transactions. Such transactions
+are mainly useful to read from and write to EEPROMs.
+
+The CX700/VX800/VX820 additionally appears to support SMBus PEC, although
+this driver doesn't implement it yet.
diff --git a/Documentation/i2c/busses/index.rst b/Documentation/i2c/busses/index.rst
new file mode 100644
index 0000000..97ca4d5
--- /dev/null
+++ b/Documentation/i2c/busses/index.rst
@@ -0,0 +1,33 @@
+. SPDX-License-Identifier: GPL-2.0
+
+===============
+I2C Bus Drivers
+===============
+
+.. toctree::
+ :maxdepth: 1
+
+ i2c-ali1535
+ i2c-ali1563
+ i2c-ali15x3
+ i2c-amd756
+ i2c-amd8111
+ i2c-amd-mp2
+ i2c-diolan-u2c
+ i2c-i801
+ i2c-ismt
+ i2c-mlxcpld
+ i2c-nforce2
+ i2c-nvidia-gpu
+ i2c-ocores
+ i2c-parport-light
+ i2c-parport
+ i2c-pca-isa
+ i2c-piix4
+ i2c-sis5595
+ i2c-sis630
+ i2c-sis96x
+ i2c-taos-evm
+ i2c-viapro
+ i2c-via
+ scx200_acb
diff --git a/Documentation/i2c/busses/scx200_acb b/Documentation/i2c/busses/scx200_acb
deleted file mode 100644
index ce83c87..0000000
--- a/Documentation/i2c/busses/scx200_acb
+++ /dev/null
@@ -1,32 +0,0 @@
-Kernel driver scx200_acb
-
-Author: Christer Weinigel <wingel@nano-system.com>
-
-The driver supersedes the older, never merged driver named i2c-nscacb.
-
-Module Parameters
------------------
-
-* base: up to 4 ints
- Base addresses for the ACCESS.bus controllers on SCx200 and SC1100 devices
-
- By default the driver uses two base addresses 0x820 and 0x840.
- If you want only one base address, specify the second as 0 so as to
- override this default.
-
-Description
------------
-
-Enable the use of the ACCESS.bus controller on the Geode SCx200 and
-SC1100 processors and the CS5535 and CS5536 Geode companion devices.
-
-Device-specific notes
----------------------
-
-The SC1100 WRAP boards are known to use base addresses 0x810 and 0x820.
-If the scx200_acb driver is built into the kernel, add the following
-parameter to your boot command line:
- scx200_acb.base=0x810,0x820
-If the scx200_acb driver is built as a module, add the following line to
-a configuration file in /etc/modprobe.d/ instead:
- options scx200_acb base=0x810,0x820
diff --git a/Documentation/i2c/busses/scx200_acb.rst b/Documentation/i2c/busses/scx200_acb.rst
new file mode 100644
index 0000000..8dc7c35
--- /dev/null
+++ b/Documentation/i2c/busses/scx200_acb.rst
@@ -0,0 +1,37 @@
+========================
+Kernel driver scx200_acb
+========================
+
+Author: Christer Weinigel <wingel@nano-system.com>
+
+The driver supersedes the older, never merged driver named i2c-nscacb.
+
+Module Parameters
+-----------------
+
+* base: up to 4 ints
+ Base addresses for the ACCESS.bus controllers on SCx200 and SC1100 devices
+
+ By default the driver uses two base addresses 0x820 and 0x840.
+ If you want only one base address, specify the second as 0 so as to
+ override this default.
+
+Description
+-----------
+
+Enable the use of the ACCESS.bus controller on the Geode SCx200 and
+SC1100 processors and the CS5535 and CS5536 Geode companion devices.
+
+Device-specific notes
+---------------------
+
+The SC1100 WRAP boards are known to use base addresses 0x810 and 0x820.
+If the scx200_acb driver is built into the kernel, add the following
+parameter to your boot command line::
+
+ scx200_acb.base=0x810,0x820
+
+If the scx200_acb driver is built as a module, add the following line to
+a configuration file in /etc/modprobe.d/ instead::
+
+ options scx200_acb base=0x810,0x820
diff --git a/Documentation/i2c/dev-interface b/Documentation/i2c/dev-interface
deleted file mode 100644
index fbed645..0000000
--- a/Documentation/i2c/dev-interface
+++ /dev/null
@@ -1,213 +0,0 @@
-Usually, i2c devices are controlled by a kernel driver. But it is also
-possible to access all devices on an adapter from userspace, through
-the /dev interface. You need to load module i2c-dev for this.
-
-Each registered i2c adapter gets a number, counting from 0. You can
-examine /sys/class/i2c-dev/ to see what number corresponds to which adapter.
-Alternatively, you can run "i2cdetect -l" to obtain a formatted list of all
-i2c adapters present on your system at a given time. i2cdetect is part of
-the i2c-tools package.
-
-I2C device files are character device files with major device number 89
-and a minor device number corresponding to the number assigned as
-explained above. They should be called "i2c-%d" (i2c-0, i2c-1, ...,
-i2c-10, ...). All 256 minor device numbers are reserved for i2c.
-
-
-C example
-=========
-
-So let's say you want to access an i2c adapter from a C program.
-First, you need to include these two headers:
-
- #include <linux/i2c-dev.h>
- #include <i2c/smbus.h>
-
-Now, you have to decide which adapter you want to access. You should
-inspect /sys/class/i2c-dev/ or run "i2cdetect -l" to decide this.
-Adapter numbers are assigned somewhat dynamically, so you can not
-assume much about them. They can even change from one boot to the next.
-
-Next thing, open the device file, as follows:
-
- int file;
- int adapter_nr = 2; /* probably dynamically determined */
- char filename[20];
-
- snprintf(filename, 19, "/dev/i2c-%d", adapter_nr);
- file = open(filename, O_RDWR);
- if (file < 0) {
- /* ERROR HANDLING; you can check errno to see what went wrong */
- exit(1);
- }
-
-When you have opened the device, you must specify with what device
-address you want to communicate:
-
- int addr = 0x40; /* The I2C address */
-
- if (ioctl(file, I2C_SLAVE, addr) < 0) {
- /* ERROR HANDLING; you can check errno to see what went wrong */
- exit(1);
- }
-
-Well, you are all set up now. You can now use SMBus commands or plain
-I2C to communicate with your device. SMBus commands are preferred if
-the device supports them. Both are illustrated below.
-
- __u8 reg = 0x10; /* Device register to access */
- __s32 res;
- char buf[10];
-
- /* Using SMBus commands */
- res = i2c_smbus_read_word_data(file, reg);
- if (res < 0) {
- /* ERROR HANDLING: i2c transaction failed */
- } else {
- /* res contains the read word */
- }
-
- /*
- * Using I2C Write, equivalent of
- * i2c_smbus_write_word_data(file, reg, 0x6543)
- */
- buf[0] = reg;
- buf[1] = 0x43;
- buf[2] = 0x65;
- if (write(file, buf, 3) != 3) {
- /* ERROR HANDLING: i2c transaction failed */
- }
-
- /* Using I2C Read, equivalent of i2c_smbus_read_byte(file) */
- if (read(file, buf, 1) != 1) {
- /* ERROR HANDLING: i2c transaction failed */
- } else {
- /* buf[0] contains the read byte */
- }
-
-Note that only a subset of the I2C and SMBus protocols can be achieved by
-the means of read() and write() calls. In particular, so-called combined
-transactions (mixing read and write messages in the same transaction)
-aren't supported. For this reason, this interface is almost never used by
-user-space programs.
-
-IMPORTANT: because of the use of inline functions, you *have* to use
-'-O' or some variation when you compile your program!
-
-
-Full interface description
-==========================
-
-The following IOCTLs are defined:
-
-ioctl(file, I2C_SLAVE, long addr)
- Change slave address. The address is passed in the 7 lower bits of the
- argument (except for 10 bit addresses, passed in the 10 lower bits in this
- case).
-
-ioctl(file, I2C_TENBIT, long select)
- Selects ten bit addresses if select not equals 0, selects normal 7 bit
- addresses if select equals 0. Default 0. This request is only valid
- if the adapter has I2C_FUNC_10BIT_ADDR.
-
-ioctl(file, I2C_PEC, long select)
- Selects SMBus PEC (packet error checking) generation and verification
- if select not equals 0, disables if select equals 0. Default 0.
- Used only for SMBus transactions. This request only has an effect if the
- the adapter has I2C_FUNC_SMBUS_PEC; it is still safe if not, it just
- doesn't have any effect.
-
-ioctl(file, I2C_FUNCS, unsigned long *funcs)
- Gets the adapter functionality and puts it in *funcs.
-
-ioctl(file, I2C_RDWR, struct i2c_rdwr_ioctl_data *msgset)
- Do combined read/write transaction without stop in between.
- Only valid if the adapter has I2C_FUNC_I2C. The argument is
- a pointer to a
-
- struct i2c_rdwr_ioctl_data {
- struct i2c_msg *msgs; /* ptr to array of simple messages */
- int nmsgs; /* number of messages to exchange */
- }
-
- The msgs[] themselves contain further pointers into data buffers.
- The function will write or read data to or from that buffers depending
- on whether the I2C_M_RD flag is set in a particular message or not.
- The slave address and whether to use ten bit address mode has to be
- set in each message, overriding the values set with the above ioctl's.
-
-ioctl(file, I2C_SMBUS, struct i2c_smbus_ioctl_data *args)
- If possible, use the provided i2c_smbus_* methods described below instead
- of issuing direct ioctls.
-
-You can do plain i2c transactions by using read(2) and write(2) calls.
-You do not need to pass the address byte; instead, set it through
-ioctl I2C_SLAVE before you try to access the device.
-
-You can do SMBus level transactions (see documentation file smbus-protocol
-for details) through the following functions:
- __s32 i2c_smbus_write_quick(int file, __u8 value);
- __s32 i2c_smbus_read_byte(int file);
- __s32 i2c_smbus_write_byte(int file, __u8 value);
- __s32 i2c_smbus_read_byte_data(int file, __u8 command);
- __s32 i2c_smbus_write_byte_data(int file, __u8 command, __u8 value);
- __s32 i2c_smbus_read_word_data(int file, __u8 command);
- __s32 i2c_smbus_write_word_data(int file, __u8 command, __u16 value);
- __s32 i2c_smbus_process_call(int file, __u8 command, __u16 value);
- __s32 i2c_smbus_read_block_data(int file, __u8 command, __u8 *values);
- __s32 i2c_smbus_write_block_data(int file, __u8 command, __u8 length,
- __u8 *values);
-All these transactions return -1 on failure; you can read errno to see
-what happened. The 'write' transactions return 0 on success; the
-'read' transactions return the read value, except for read_block, which
-returns the number of values read. The block buffers need not be longer
-than 32 bytes.
-
-The above functions are made available by linking against the libi2c library,
-which is provided by the i2c-tools project. See:
-https://git.kernel.org/pub/scm/utils/i2c-tools/i2c-tools.git/.
-
-
-Implementation details
-======================
-
-For the interested, here's the code flow which happens inside the kernel
-when you use the /dev interface to I2C:
-
-1* Your program opens /dev/i2c-N and calls ioctl() on it, as described in
-section "C example" above.
-
-2* These open() and ioctl() calls are handled by the i2c-dev kernel
-driver: see i2c-dev.c:i2cdev_open() and i2c-dev.c:i2cdev_ioctl(),
-respectively. You can think of i2c-dev as a generic I2C chip driver
-that can be programmed from user-space.
-
-3* Some ioctl() calls are for administrative tasks and are handled by
-i2c-dev directly. Examples include I2C_SLAVE (set the address of the
-device you want to access) and I2C_PEC (enable or disable SMBus error
-checking on future transactions.)
-
-4* Other ioctl() calls are converted to in-kernel function calls by
-i2c-dev. Examples include I2C_FUNCS, which queries the I2C adapter
-functionality using i2c.h:i2c_get_functionality(), and I2C_SMBUS, which
-performs an SMBus transaction using i2c-core-smbus.c:i2c_smbus_xfer().
-
-The i2c-dev driver is responsible for checking all the parameters that
-come from user-space for validity. After this point, there is no
-difference between these calls that came from user-space through i2c-dev
-and calls that would have been performed by kernel I2C chip drivers
-directly. This means that I2C bus drivers don't need to implement
-anything special to support access from user-space.
-
-5* These i2c.h functions are wrappers to the actual implementation of
-your I2C bus driver. Each adapter must declare callback functions
-implementing these standard calls. i2c.h:i2c_get_functionality() calls
-i2c_adapter.algo->functionality(), while
-i2c-core-smbus.c:i2c_smbus_xfer() calls either
-adapter.algo->smbus_xfer() if it is implemented, or if not,
-i2c-core-smbus.c:i2c_smbus_xfer_emulated() which in turn calls
-i2c_adapter.algo->master_xfer().
-
-After your I2C bus driver has processed these requests, execution runs
-up the call chain, with almost no processing done, except by i2c-dev to
-package the returned data, if any, in suitable format for the ioctl.
diff --git a/Documentation/i2c/dev-interface.rst b/Documentation/i2c/dev-interface.rst
new file mode 100644
index 0000000..69c23a3
--- /dev/null
+++ b/Documentation/i2c/dev-interface.rst
@@ -0,0 +1,219 @@
+====================
+I2C Device Interface
+====================
+
+Usually, i2c devices are controlled by a kernel driver. But it is also
+possible to access all devices on an adapter from userspace, through
+the /dev interface. You need to load module i2c-dev for this.
+
+Each registered i2c adapter gets a number, counting from 0. You can
+examine /sys/class/i2c-dev/ to see what number corresponds to which adapter.
+Alternatively, you can run "i2cdetect -l" to obtain a formatted list of all
+i2c adapters present on your system at a given time. i2cdetect is part of
+the i2c-tools package.
+
+I2C device files are character device files with major device number 89
+and a minor device number corresponding to the number assigned as
+explained above. They should be called "i2c-%d" (i2c-0, i2c-1, ...,
+i2c-10, ...). All 256 minor device numbers are reserved for i2c.
+
+
+C example
+=========
+
+So let's say you want to access an i2c adapter from a C program.
+First, you need to include these two headers::
+
+ #include <linux/i2c-dev.h>
+ #include <i2c/smbus.h>
+
+Now, you have to decide which adapter you want to access. You should
+inspect /sys/class/i2c-dev/ or run "i2cdetect -l" to decide this.
+Adapter numbers are assigned somewhat dynamically, so you can not
+assume much about them. They can even change from one boot to the next.
+
+Next thing, open the device file, as follows::
+
+ int file;
+ int adapter_nr = 2; /* probably dynamically determined */
+ char filename[20];
+
+ snprintf(filename, 19, "/dev/i2c-%d", adapter_nr);
+ file = open(filename, O_RDWR);
+ if (file < 0) {
+ /* ERROR HANDLING; you can check errno to see what went wrong */
+ exit(1);
+ }
+
+When you have opened the device, you must specify with what device
+address you want to communicate::
+
+ int addr = 0x40; /* The I2C address */
+
+ if (ioctl(file, I2C_SLAVE, addr) < 0) {
+ /* ERROR HANDLING; you can check errno to see what went wrong */
+ exit(1);
+ }
+
+Well, you are all set up now. You can now use SMBus commands or plain
+I2C to communicate with your device. SMBus commands are preferred if
+the device supports them. Both are illustrated below::
+
+ __u8 reg = 0x10; /* Device register to access */
+ __s32 res;
+ char buf[10];
+
+ /* Using SMBus commands */
+ res = i2c_smbus_read_word_data(file, reg);
+ if (res < 0) {
+ /* ERROR HANDLING: i2c transaction failed */
+ } else {
+ /* res contains the read word */
+ }
+
+ /*
+ * Using I2C Write, equivalent of
+ * i2c_smbus_write_word_data(file, reg, 0x6543)
+ */
+ buf[0] = reg;
+ buf[1] = 0x43;
+ buf[2] = 0x65;
+ if (write(file, buf, 3) != 3) {
+ /* ERROR HANDLING: i2c transaction failed */
+ }
+
+ /* Using I2C Read, equivalent of i2c_smbus_read_byte(file) */
+ if (read(file, buf, 1) != 1) {
+ /* ERROR HANDLING: i2c transaction failed */
+ } else {
+ /* buf[0] contains the read byte */
+ }
+
+Note that only a subset of the I2C and SMBus protocols can be achieved by
+the means of read() and write() calls. In particular, so-called combined
+transactions (mixing read and write messages in the same transaction)
+aren't supported. For this reason, this interface is almost never used by
+user-space programs.
+
+IMPORTANT: because of the use of inline functions, you *have* to use
+'-O' or some variation when you compile your program!
+
+
+Full interface description
+==========================
+
+The following IOCTLs are defined:
+
+``ioctl(file, I2C_SLAVE, long addr)``
+ Change slave address. The address is passed in the 7 lower bits of the
+ argument (except for 10 bit addresses, passed in the 10 lower bits in this
+ case).
+
+``ioctl(file, I2C_TENBIT, long select)``
+ Selects ten bit addresses if select not equals 0, selects normal 7 bit
+ addresses if select equals 0. Default 0. This request is only valid
+ if the adapter has I2C_FUNC_10BIT_ADDR.
+
+``ioctl(file, I2C_PEC, long select)``
+ Selects SMBus PEC (packet error checking) generation and verification
+ if select not equals 0, disables if select equals 0. Default 0.
+ Used only for SMBus transactions. This request only has an effect if the
+ the adapter has I2C_FUNC_SMBUS_PEC; it is still safe if not, it just
+ doesn't have any effect.
+
+``ioctl(file, I2C_FUNCS, unsigned long *funcs)``
+ Gets the adapter functionality and puts it in ``*funcs``.
+
+``ioctl(file, I2C_RDWR, struct i2c_rdwr_ioctl_data *msgset)``
+ Do combined read/write transaction without stop in between.
+ Only valid if the adapter has I2C_FUNC_I2C. The argument is
+ a pointer to a::
+
+ struct i2c_rdwr_ioctl_data {
+ struct i2c_msg *msgs; /* ptr to array of simple messages */
+ int nmsgs; /* number of messages to exchange */
+ }
+
+ The msgs[] themselves contain further pointers into data buffers.
+ The function will write or read data to or from that buffers depending
+ on whether the I2C_M_RD flag is set in a particular message or not.
+ The slave address and whether to use ten bit address mode has to be
+ set in each message, overriding the values set with the above ioctl's.
+
+``ioctl(file, I2C_SMBUS, struct i2c_smbus_ioctl_data *args)``
+ If possible, use the provided ``i2c_smbus_*`` methods described below instead
+ of issuing direct ioctls.
+
+You can do plain i2c transactions by using read(2) and write(2) calls.
+You do not need to pass the address byte; instead, set it through
+ioctl I2C_SLAVE before you try to access the device.
+
+You can do SMBus level transactions (see documentation file smbus-protocol
+for details) through the following functions::
+
+ __s32 i2c_smbus_write_quick(int file, __u8 value);
+ __s32 i2c_smbus_read_byte(int file);
+ __s32 i2c_smbus_write_byte(int file, __u8 value);
+ __s32 i2c_smbus_read_byte_data(int file, __u8 command);
+ __s32 i2c_smbus_write_byte_data(int file, __u8 command, __u8 value);
+ __s32 i2c_smbus_read_word_data(int file, __u8 command);
+ __s32 i2c_smbus_write_word_data(int file, __u8 command, __u16 value);
+ __s32 i2c_smbus_process_call(int file, __u8 command, __u16 value);
+ __s32 i2c_smbus_read_block_data(int file, __u8 command, __u8 *values);
+ __s32 i2c_smbus_write_block_data(int file, __u8 command, __u8 length,
+ __u8 *values);
+
+All these transactions return -1 on failure; you can read errno to see
+what happened. The 'write' transactions return 0 on success; the
+'read' transactions return the read value, except for read_block, which
+returns the number of values read. The block buffers need not be longer
+than 32 bytes.
+
+The above functions are made available by linking against the libi2c library,
+which is provided by the i2c-tools project. See:
+https://git.kernel.org/pub/scm/utils/i2c-tools/i2c-tools.git/.
+
+
+Implementation details
+======================
+
+For the interested, here's the code flow which happens inside the kernel
+when you use the /dev interface to I2C:
+
+1) Your program opens /dev/i2c-N and calls ioctl() on it, as described in
+ section "C example" above.
+
+2) These open() and ioctl() calls are handled by the i2c-dev kernel
+ driver: see i2c-dev.c:i2cdev_open() and i2c-dev.c:i2cdev_ioctl(),
+ respectively. You can think of i2c-dev as a generic I2C chip driver
+ that can be programmed from user-space.
+
+3) Some ioctl() calls are for administrative tasks and are handled by
+ i2c-dev directly. Examples include I2C_SLAVE (set the address of the
+ device you want to access) and I2C_PEC (enable or disable SMBus error
+ checking on future transactions.)
+
+4) Other ioctl() calls are converted to in-kernel function calls by
+ i2c-dev. Examples include I2C_FUNCS, which queries the I2C adapter
+ functionality using i2c.h:i2c_get_functionality(), and I2C_SMBUS, which
+ performs an SMBus transaction using i2c-core-smbus.c:i2c_smbus_xfer().
+
+ The i2c-dev driver is responsible for checking all the parameters that
+ come from user-space for validity. After this point, there is no
+ difference between these calls that came from user-space through i2c-dev
+ and calls that would have been performed by kernel I2C chip drivers
+ directly. This means that I2C bus drivers don't need to implement
+ anything special to support access from user-space.
+
+5) These i2c.h functions are wrappers to the actual implementation of
+ your I2C bus driver. Each adapter must declare callback functions
+ implementing these standard calls. i2c.h:i2c_get_functionality() calls
+ i2c_adapter.algo->functionality(), while
+ i2c-core-smbus.c:i2c_smbus_xfer() calls either
+ adapter.algo->smbus_xfer() if it is implemented, or if not,
+ i2c-core-smbus.c:i2c_smbus_xfer_emulated() which in turn calls
+ i2c_adapter.algo->master_xfer().
+
+After your I2C bus driver has processed these requests, execution runs
+up the call chain, with almost no processing done, except by i2c-dev to
+package the returned data, if any, in suitable format for the ioctl.
diff --git a/Documentation/i2c/DMA-considerations b/Documentation/i2c/dma-considerations.rst
similarity index 100%
rename from Documentation/i2c/DMA-considerations
rename to Documentation/i2c/dma-considerations.rst
diff --git a/Documentation/i2c/fault-codes b/Documentation/i2c/fault-codes
deleted file mode 100644
index 0cee0fc..0000000
--- a/Documentation/i2c/fault-codes
+++ /dev/null
@@ -1,128 +0,0 @@
-This is a summary of the most important conventions for use of fault
-codes in the I2C/SMBus stack.
-
-
-A "Fault" is not always an "Error"
-----------------------------------
-Not all fault reports imply errors; "page faults" should be a familiar
-example. Software often retries idempotent operations after transient
-faults. There may be fancier recovery schemes that are appropriate in
-some cases, such as re-initializing (and maybe resetting). After such
-recovery, triggered by a fault report, there is no error.
-
-In a similar way, sometimes a "fault" code just reports one defined
-result for an operation ... it doesn't indicate that anything is wrong
-at all, just that the outcome wasn't on the "golden path".
-
-In short, your I2C driver code may need to know these codes in order
-to respond correctly. Other code may need to rely on YOUR code reporting
-the right fault code, so that it can (in turn) behave correctly.
-
-
-I2C and SMBus fault codes
--------------------------
-These are returned as negative numbers from most calls, with zero or
-some positive number indicating a non-fault return. The specific
-numbers associated with these symbols differ between architectures,
-though most Linux systems use <asm-generic/errno*.h> numbering.
-
-Note that the descriptions here are not exhaustive. There are other
-codes that may be returned, and other cases where these codes should
-be returned. However, drivers should not return other codes for these
-cases (unless the hardware doesn't provide unique fault reports).
-
-Also, codes returned by adapter probe methods follow rules which are
-specific to their host bus (such as PCI, or the platform bus).
-
-
-EAGAIN
- Returned by I2C adapters when they lose arbitration in master
- transmit mode: some other master was transmitting different
- data at the same time.
-
- Also returned when trying to invoke an I2C operation in an
- atomic context, when some task is already using that I2C bus
- to execute some other operation.
-
-EBADMSG
- Returned by SMBus logic when an invalid Packet Error Code byte
- is received. This code is a CRC covering all bytes in the
- transaction, and is sent before the terminating STOP. This
- fault is only reported on read transactions; the SMBus slave
- may have a way to report PEC mismatches on writes from the
- host. Note that even if PECs are in use, you should not rely
- on these as the only way to detect incorrect data transfers.
-
-EBUSY
- Returned by SMBus adapters when the bus was busy for longer
- than allowed. This usually indicates some device (maybe the
- SMBus adapter) needs some fault recovery (such as resetting),
- or that the reset was attempted but failed.
-
-EINVAL
- This rather vague error means an invalid parameter has been
- detected before any I/O operation was started. Use a more
- specific fault code when you can.
-
-EIO
- This rather vague error means something went wrong when
- performing an I/O operation. Use a more specific fault
- code when you can.
-
-ENODEV
- Returned by driver probe() methods. This is a bit more
- specific than ENXIO, implying the problem isn't with the
- address, but with the device found there. Driver probes
- may verify the device returns *correct* responses, and
- return this as appropriate. (The driver core will warn
- about probe faults other than ENXIO and ENODEV.)
-
-ENOMEM
- Returned by any component that can't allocate memory when
- it needs to do so.
-
-ENXIO
- Returned by I2C adapters to indicate that the address phase
- of a transfer didn't get an ACK. While it might just mean
- an I2C device was temporarily not responding, usually it
- means there's nothing listening at that address.
-
- Returned by driver probe() methods to indicate that they
- found no device to bind to. (ENODEV may also be used.)
-
-EOPNOTSUPP
- Returned by an adapter when asked to perform an operation
- that it doesn't, or can't, support.
-
- For example, this would be returned when an adapter that
- doesn't support SMBus block transfers is asked to execute
- one. In that case, the driver making that request should
- have verified that functionality was supported before it
- made that block transfer request.
-
- Similarly, if an I2C adapter can't execute all legal I2C
- messages, it should return this when asked to perform a
- transaction it can't. (These limitations can't be seen in
- the adapter's functionality mask, since the assumption is
- that if an adapter supports I2C it supports all of I2C.)
-
-EPROTO
- Returned when slave does not conform to the relevant I2C
- or SMBus (or chip-specific) protocol specifications. One
- case is when the length of an SMBus block data response
- (from the SMBus slave) is outside the range 1-32 bytes.
-
-ESHUTDOWN
- Returned when a transfer was requested using an adapter
- which is already suspended.
-
-ETIMEDOUT
- This is returned by drivers when an operation took too much
- time, and was aborted before it completed.
-
- SMBus adapters may return it when an operation took more
- time than allowed by the SMBus specification; for example,
- when a slave stretches clocks too far. I2C has no such
- timeouts, but it's normal for I2C adapters to impose some
- arbitrary limits (much longer than SMBus!) too.
-
diff --git a/Documentation/i2c/fault-codes.rst b/Documentation/i2c/fault-codes.rst
new file mode 100644
index 0000000..80b14e7
--- /dev/null
+++ b/Documentation/i2c/fault-codes.rst
@@ -0,0 +1,131 @@
+=====================
+I2C/SMBUS Fault Codes
+=====================
+
+This is a summary of the most important conventions for use of fault
+codes in the I2C/SMBus stack.
+
+
+A "Fault" is not always an "Error"
+----------------------------------
+Not all fault reports imply errors; "page faults" should be a familiar
+example. Software often retries idempotent operations after transient
+faults. There may be fancier recovery schemes that are appropriate in
+some cases, such as re-initializing (and maybe resetting). After such
+recovery, triggered by a fault report, there is no error.
+
+In a similar way, sometimes a "fault" code just reports one defined
+result for an operation ... it doesn't indicate that anything is wrong
+at all, just that the outcome wasn't on the "golden path".
+
+In short, your I2C driver code may need to know these codes in order
+to respond correctly. Other code may need to rely on YOUR code reporting
+the right fault code, so that it can (in turn) behave correctly.
+
+
+I2C and SMBus fault codes
+-------------------------
+These are returned as negative numbers from most calls, with zero or
+some positive number indicating a non-fault return. The specific
+numbers associated with these symbols differ between architectures,
+though most Linux systems use <asm-generic/errno*.h> numbering.
+
+Note that the descriptions here are not exhaustive. There are other
+codes that may be returned, and other cases where these codes should
+be returned. However, drivers should not return other codes for these
+cases (unless the hardware doesn't provide unique fault reports).
+
+Also, codes returned by adapter probe methods follow rules which are
+specific to their host bus (such as PCI, or the platform bus).
+
+
+EAGAIN
+ Returned by I2C adapters when they lose arbitration in master
+ transmit mode: some other master was transmitting different
+ data at the same time.
+
+ Also returned when trying to invoke an I2C operation in an
+ atomic context, when some task is already using that I2C bus
+ to execute some other operation.
+
+EBADMSG
+ Returned by SMBus logic when an invalid Packet Error Code byte
+ is received. This code is a CRC covering all bytes in the
+ transaction, and is sent before the terminating STOP. This
+ fault is only reported on read transactions; the SMBus slave
+ may have a way to report PEC mismatches on writes from the
+ host. Note that even if PECs are in use, you should not rely
+ on these as the only way to detect incorrect data transfers.
+
+EBUSY
+ Returned by SMBus adapters when the bus was busy for longer
+ than allowed. This usually indicates some device (maybe the
+ SMBus adapter) needs some fault recovery (such as resetting),
+ or that the reset was attempted but failed.
+
+EINVAL
+ This rather vague error means an invalid parameter has been
+ detected before any I/O operation was started. Use a more
+ specific fault code when you can.
+
+EIO
+ This rather vague error means something went wrong when
+ performing an I/O operation. Use a more specific fault
+ code when you can.
+
+ENODEV
+ Returned by driver probe() methods. This is a bit more
+ specific than ENXIO, implying the problem isn't with the
+ address, but with the device found there. Driver probes
+ may verify the device returns *correct* responses, and
+ return this as appropriate. (The driver core will warn
+ about probe faults other than ENXIO and ENODEV.)
+
+ENOMEM
+ Returned by any component that can't allocate memory when
+ it needs to do so.
+
+ENXIO
+ Returned by I2C adapters to indicate that the address phase
+ of a transfer didn't get an ACK. While it might just mean
+ an I2C device was temporarily not responding, usually it
+ means there's nothing listening at that address.
+
+ Returned by driver probe() methods to indicate that they
+ found no device to bind to. (ENODEV may also be used.)
+
+EOPNOTSUPP
+ Returned by an adapter when asked to perform an operation
+ that it doesn't, or can't, support.
+
+ For example, this would be returned when an adapter that
+ doesn't support SMBus block transfers is asked to execute
+ one. In that case, the driver making that request should
+ have verified that functionality was supported before it
+ made that block transfer request.
+
+ Similarly, if an I2C adapter can't execute all legal I2C
+ messages, it should return this when asked to perform a
+ transaction it can't. (These limitations can't be seen in
+ the adapter's functionality mask, since the assumption is
+ that if an adapter supports I2C it supports all of I2C.)
+
+EPROTO
+ Returned when slave does not conform to the relevant I2C
+ or SMBus (or chip-specific) protocol specifications. One
+ case is when the length of an SMBus block data response
+ (from the SMBus slave) is outside the range 1-32 bytes.
+
+ESHUTDOWN
+ Returned when a transfer was requested using an adapter
+ which is already suspended.
+
+ETIMEDOUT
+ This is returned by drivers when an operation took too much
+ time, and was aborted before it completed.
+
+ SMBus adapters may return it when an operation took more
+ time than allowed by the SMBus specification; for example,
+ when a slave stretches clocks too far. I2C has no such
+ timeouts, but it's normal for I2C adapters to impose some
+ arbitrary limits (much longer than SMBus!) too.
diff --git a/Documentation/i2c/functionality b/Documentation/i2c/functionality
deleted file mode 100644
index 4aae8ed..0000000
--- a/Documentation/i2c/functionality
+++ /dev/null
@@ -1,148 +0,0 @@
-INTRODUCTION
-------------
-
-Because not every I2C or SMBus adapter implements everything in the
-I2C specifications, a client can not trust that everything it needs
-is implemented when it is given the option to attach to an adapter:
-the client needs some way to check whether an adapter has the needed
-functionality.
-
-
-FUNCTIONALITY CONSTANTS
------------------------
-
-For the most up-to-date list of functionality constants, please check
-<uapi/linux/i2c.h>!
-
- I2C_FUNC_I2C Plain i2c-level commands (Pure SMBus
- adapters typically can not do these)
- I2C_FUNC_10BIT_ADDR Handles the 10-bit address extensions
- I2C_FUNC_PROTOCOL_MANGLING Knows about the I2C_M_IGNORE_NAK,
- I2C_M_REV_DIR_ADDR and I2C_M_NO_RD_ACK
- flags (which modify the I2C protocol!)
- I2C_FUNC_NOSTART Can skip repeated start sequence
- I2C_FUNC_SMBUS_QUICK Handles the SMBus write_quick command
- I2C_FUNC_SMBUS_READ_BYTE Handles the SMBus read_byte command
- I2C_FUNC_SMBUS_WRITE_BYTE Handles the SMBus write_byte command
- I2C_FUNC_SMBUS_READ_BYTE_DATA Handles the SMBus read_byte_data command
- I2C_FUNC_SMBUS_WRITE_BYTE_DATA Handles the SMBus write_byte_data command
- I2C_FUNC_SMBUS_READ_WORD_DATA Handles the SMBus read_word_data command
- I2C_FUNC_SMBUS_WRITE_WORD_DATA Handles the SMBus write_byte_data command
- I2C_FUNC_SMBUS_PROC_CALL Handles the SMBus process_call command
- I2C_FUNC_SMBUS_READ_BLOCK_DATA Handles the SMBus read_block_data command
- I2C_FUNC_SMBUS_WRITE_BLOCK_DATA Handles the SMBus write_block_data command
- I2C_FUNC_SMBUS_READ_I2C_BLOCK Handles the SMBus read_i2c_block_data command
- I2C_FUNC_SMBUS_WRITE_I2C_BLOCK Handles the SMBus write_i2c_block_data command
-
-A few combinations of the above flags are also defined for your convenience:
-
- I2C_FUNC_SMBUS_BYTE Handles the SMBus read_byte
- and write_byte commands
- I2C_FUNC_SMBUS_BYTE_DATA Handles the SMBus read_byte_data
- and write_byte_data commands
- I2C_FUNC_SMBUS_WORD_DATA Handles the SMBus read_word_data
- and write_word_data commands
- I2C_FUNC_SMBUS_BLOCK_DATA Handles the SMBus read_block_data
- and write_block_data commands
- I2C_FUNC_SMBUS_I2C_BLOCK Handles the SMBus read_i2c_block_data
- and write_i2c_block_data commands
- I2C_FUNC_SMBUS_EMUL Handles all SMBus commands that can be
- emulated by a real I2C adapter (using
- the transparent emulation layer)
-
-In kernel versions prior to 3.5 I2C_FUNC_NOSTART was implemented as
-part of I2C_FUNC_PROTOCOL_MANGLING.
-
-
-ADAPTER IMPLEMENTATION
-----------------------
-
-When you write a new adapter driver, you will have to implement a
-function callback `functionality'. Typical implementations are given
-below.
-
-A typical SMBus-only adapter would list all the SMBus transactions it
-supports. This example comes from the i2c-piix4 driver:
-
- static u32 piix4_func(struct i2c_adapter *adapter)
- {
- return I2C_FUNC_SMBUS_QUICK | I2C_FUNC_SMBUS_BYTE |
- I2C_FUNC_SMBUS_BYTE_DATA | I2C_FUNC_SMBUS_WORD_DATA |
- I2C_FUNC_SMBUS_BLOCK_DATA;
- }
-
-A typical full-I2C adapter would use the following (from the i2c-pxa
-driver):
-
- static u32 i2c_pxa_functionality(struct i2c_adapter *adap)
- {
- return I2C_FUNC_I2C | I2C_FUNC_SMBUS_EMUL;
- }
-
-I2C_FUNC_SMBUS_EMUL includes all the SMBus transactions (with the
-addition of I2C block transactions) which i2c-core can emulate using
-I2C_FUNC_I2C without any help from the adapter driver. The idea is
-to let the client drivers check for the support of SMBus functions
-without having to care whether the said functions are implemented in
-hardware by the adapter, or emulated in software by i2c-core on top
-of an I2C adapter.
-
-
-CLIENT CHECKING
----------------
-
-Before a client tries to attach to an adapter, or even do tests to check
-whether one of the devices it supports is present on an adapter, it should
-check whether the needed functionality is present. The typical way to do
-this is (from the lm75 driver):
-
- static int lm75_detect(...)
- {
- (...)
- if (!i2c_check_functionality(adapter, I2C_FUNC_SMBUS_BYTE_DATA |
- I2C_FUNC_SMBUS_WORD_DATA))
- goto exit;
- (...)
- }
-
-Here, the lm75 driver checks if the adapter can do both SMBus byte data
-and SMBus word data transactions. If not, then the driver won't work on
-this adapter and there's no point in going on. If the check above is
-successful, then the driver knows that it can call the following
-functions: i2c_smbus_read_byte_data(), i2c_smbus_write_byte_data(),
-i2c_smbus_read_word_data() and i2c_smbus_write_word_data(). As a rule of
-thumb, the functionality constants you test for with
-i2c_check_functionality() should match exactly the i2c_smbus_* functions
-which you driver is calling.
-
-Note that the check above doesn't tell whether the functionalities are
-implemented in hardware by the underlying adapter or emulated in
-software by i2c-core. Client drivers don't have to care about this, as
-i2c-core will transparently implement SMBus transactions on top of I2C
-adapters.
-
-
-CHECKING THROUGH /DEV
----------------------
-
-If you try to access an adapter from a userspace program, you will have
-to use the /dev interface. You will still have to check whether the
-functionality you need is supported, of course. This is done using
-the I2C_FUNCS ioctl. An example, adapted from the i2cdetect program, is
-below:
-
- int file;
- if (file = open("/dev/i2c-0", O_RDWR) < 0) {
- /* Some kind of error handling */
- exit(1);
- }
- if (ioctl(file, I2C_FUNCS, &funcs) < 0) {
- /* Some kind of error handling */
- exit(1);
- }
- if (!(funcs & I2C_FUNC_SMBUS_QUICK)) {
- /* Oops, the needed functionality (SMBus write_quick function) is
- not available! */
- exit(1);
- }
- /* Now it is safe to use the SMBus write_quick command */
diff --git a/Documentation/i2c/functionality.rst b/Documentation/i2c/functionality.rst
new file mode 100644
index 0000000..377507c
--- /dev/null
+++ b/Documentation/i2c/functionality.rst
@@ -0,0 +1,156 @@
+=======================
+I2C/SMBus Functionality
+=======================
+
+INTRODUCTION
+------------
+
+Because not every I2C or SMBus adapter implements everything in the
+I2C specifications, a client can not trust that everything it needs
+is implemented when it is given the option to attach to an adapter:
+the client needs some way to check whether an adapter has the needed
+functionality.
+
+
+FUNCTIONALITY CONSTANTS
+-----------------------
+
+For the most up-to-date list of functionality constants, please check
+<uapi/linux/i2c.h>!
+
+ =============================== ==============================================
+ I2C_FUNC_I2C Plain i2c-level commands (Pure SMBus
+ adapters typically can not do these)
+ I2C_FUNC_10BIT_ADDR Handles the 10-bit address extensions
+ I2C_FUNC_PROTOCOL_MANGLING Knows about the I2C_M_IGNORE_NAK,
+ I2C_M_REV_DIR_ADDR and I2C_M_NO_RD_ACK
+ flags (which modify the I2C protocol!)
+ I2C_FUNC_NOSTART Can skip repeated start sequence
+ I2C_FUNC_SMBUS_QUICK Handles the SMBus write_quick command
+ I2C_FUNC_SMBUS_READ_BYTE Handles the SMBus read_byte command
+ I2C_FUNC_SMBUS_WRITE_BYTE Handles the SMBus write_byte command
+ I2C_FUNC_SMBUS_READ_BYTE_DATA Handles the SMBus read_byte_data command
+ I2C_FUNC_SMBUS_WRITE_BYTE_DATA Handles the SMBus write_byte_data command
+ I2C_FUNC_SMBUS_READ_WORD_DATA Handles the SMBus read_word_data command
+ I2C_FUNC_SMBUS_WRITE_WORD_DATA Handles the SMBus write_byte_data command
+ I2C_FUNC_SMBUS_PROC_CALL Handles the SMBus process_call command
+ I2C_FUNC_SMBUS_READ_BLOCK_DATA Handles the SMBus read_block_data command
+ I2C_FUNC_SMBUS_WRITE_BLOCK_DATA Handles the SMBus write_block_data command
+ I2C_FUNC_SMBUS_READ_I2C_BLOCK Handles the SMBus read_i2c_block_data command
+ I2C_FUNC_SMBUS_WRITE_I2C_BLOCK Handles the SMBus write_i2c_block_data command
+ =============================== ==============================================
+
+A few combinations of the above flags are also defined for your convenience:
+
+ ========================= ======================================
+ I2C_FUNC_SMBUS_BYTE Handles the SMBus read_byte
+ and write_byte commands
+ I2C_FUNC_SMBUS_BYTE_DATA Handles the SMBus read_byte_data
+ and write_byte_data commands
+ I2C_FUNC_SMBUS_WORD_DATA Handles the SMBus read_word_data
+ and write_word_data commands
+ I2C_FUNC_SMBUS_BLOCK_DATA Handles the SMBus read_block_data
+ and write_block_data commands
+ I2C_FUNC_SMBUS_I2C_BLOCK Handles the SMBus read_i2c_block_data
+ and write_i2c_block_data commands
+ I2C_FUNC_SMBUS_EMUL Handles all SMBus commands that can be
+ emulated by a real I2C adapter (using
+ the transparent emulation layer)
+ ========================= ======================================
+
+In kernel versions prior to 3.5 I2C_FUNC_NOSTART was implemented as
+part of I2C_FUNC_PROTOCOL_MANGLING.
+
+
+ADAPTER IMPLEMENTATION
+----------------------
+
+When you write a new adapter driver, you will have to implement a
+function callback ``functionality``. Typical implementations are given
+below.
+
+A typical SMBus-only adapter would list all the SMBus transactions it
+supports. This example comes from the i2c-piix4 driver::
+
+ static u32 piix4_func(struct i2c_adapter *adapter)
+ {
+ return I2C_FUNC_SMBUS_QUICK | I2C_FUNC_SMBUS_BYTE |
+ I2C_FUNC_SMBUS_BYTE_DATA | I2C_FUNC_SMBUS_WORD_DATA |
+ I2C_FUNC_SMBUS_BLOCK_DATA;
+ }
+
+A typical full-I2C adapter would use the following (from the i2c-pxa
+driver)::
+
+ static u32 i2c_pxa_functionality(struct i2c_adapter *adap)
+ {
+ return I2C_FUNC_I2C | I2C_FUNC_SMBUS_EMUL;
+ }
+
+I2C_FUNC_SMBUS_EMUL includes all the SMBus transactions (with the
+addition of I2C block transactions) which i2c-core can emulate using
+I2C_FUNC_I2C without any help from the adapter driver. The idea is
+to let the client drivers check for the support of SMBus functions
+without having to care whether the said functions are implemented in
+hardware by the adapter, or emulated in software by i2c-core on top
+of an I2C adapter.
+
+
+CLIENT CHECKING
+---------------
+
+Before a client tries to attach to an adapter, or even do tests to check
+whether one of the devices it supports is present on an adapter, it should
+check whether the needed functionality is present. The typical way to do
+this is (from the lm75 driver)::
+
+ static int lm75_detect(...)
+ {
+ (...)
+ if (!i2c_check_functionality(adapter, I2C_FUNC_SMBUS_BYTE_DATA |
+ I2C_FUNC_SMBUS_WORD_DATA))
+ goto exit;
+ (...)
+ }
+
+Here, the lm75 driver checks if the adapter can do both SMBus byte data
+and SMBus word data transactions. If not, then the driver won't work on
+this adapter and there's no point in going on. If the check above is
+successful, then the driver knows that it can call the following
+functions: i2c_smbus_read_byte_data(), i2c_smbus_write_byte_data(),
+i2c_smbus_read_word_data() and i2c_smbus_write_word_data(). As a rule of
+thumb, the functionality constants you test for with
+i2c_check_functionality() should match exactly the i2c_smbus_* functions
+which you driver is calling.
+
+Note that the check above doesn't tell whether the functionalities are
+implemented in hardware by the underlying adapter or emulated in
+software by i2c-core. Client drivers don't have to care about this, as
+i2c-core will transparently implement SMBus transactions on top of I2C
+adapters.
+
+
+CHECKING THROUGH /DEV
+---------------------
+
+If you try to access an adapter from a userspace program, you will have
+to use the /dev interface. You will still have to check whether the
+functionality you need is supported, of course. This is done using
+the I2C_FUNCS ioctl. An example, adapted from the i2cdetect program, is
+below::
+
+ int file;
+ if (file = open("/dev/i2c-0", O_RDWR) < 0) {
+ /* Some kind of error handling */
+ exit(1);
+ }
+ if (ioctl(file, I2C_FUNCS, &funcs) < 0) {
+ /* Some kind of error handling */
+ exit(1);
+ }
+ if (!(funcs & I2C_FUNC_SMBUS_QUICK)) {
+ /* Oops, the needed functionality (SMBus write_quick function) is
+ not available! */
+ exit(1);
+ }
+ /* Now it is safe to use the SMBus write_quick command */
diff --git a/Documentation/i2c/gpio-fault-injection b/Documentation/i2c/gpio-fault-injection
deleted file mode 100644
index c87f416..0000000
--- a/Documentation/i2c/gpio-fault-injection
+++ /dev/null
@@ -1,136 +0,0 @@
-=========================
-Linux I2C fault injection
-=========================
-
-The GPIO based I2C bus master driver can be configured to provide fault
-injection capabilities. It is then meant to be connected to another I2C bus
-which is driven by the I2C bus master driver under test. The GPIO fault
-injection driver can create special states on the bus which the other I2C bus
-master driver should handle gracefully.
-
-Once the Kconfig option I2C_GPIO_FAULT_INJECTOR is enabled, there will be an
-'i2c-fault-injector' subdirectory in the Kernel debugfs filesystem, usually
-mounted at /sys/kernel/debug. There will be a separate subdirectory per GPIO
-driven I2C bus. Each subdirectory will contain files to trigger the fault
-injection. They will be described now along with their intended use-cases.
-
-Wire states
-===========
-
-"scl"
------
-
-By reading this file, you get the current state of SCL. By writing, you can
-change its state to either force it low or to release it again. So, by using
-"echo 0 > scl" you force SCL low and thus, no communication will be possible
-because the bus master under test will not be able to clock. It should detect
-the condition of SCL being unresponsive and report an error to the upper
-layers.
-
-"sda"
------
-
-By reading this file, you get the current state of SDA. By writing, you can
-change its state to either force it low or to release it again. So, by using
-"echo 0 > sda" you force SDA low and thus, data cannot be transmitted. The bus
-master under test should detect this condition and trigger a bus recovery (see
-I2C specification version 4, section 3.1.16) using the helpers of the Linux I2C
-core (see 'struct bus_recovery_info'). However, the bus recovery will not
-succeed because SDA is still pinned low until you manually release it again
-with "echo 1 > sda". A test with an automatic release can be done with the
-"incomplete transfers" class of fault injectors.
-
-Incomplete transfers
-====================
-
-The following fault injectors create situations where SDA will be held low by a
-device. Bus recovery should be able to fix these situations. But please note:
-there are I2C client devices which detect a stuck SDA on their side and release
-it on their own after a few milliseconds. Also, there might be an external
-device deglitching and monitoring the I2C bus. It could also detect a stuck SDA
-and will init a bus recovery on its own. If you want to implement bus recovery
-in a bus master driver, make sure you checked your hardware setup for such
-devices before. And always verify with a scope or logic analyzer!
-
-"incomplete_address_phase"
---------------------------
-
-This file is write only and you need to write the address of an existing I2C
-client device to it. Then, a read transfer to this device will be started, but
-it will stop at the ACK phase after the address of the client has been
-transmitted. Because the device will ACK its presence, this results in SDA
-being pulled low by the device while SCL is high. So, similar to the "sda" file
-above, the bus master under test should detect this condition and try a bus
-recovery. This time, however, it should succeed and the device should release
-SDA after toggling SCL.
-
-"incomplete_write_byte"
------------------------
-
-Similar to above, this file is write only and you need to write the address of
-an existing I2C client device to it.
-
-The injector will again stop at one ACK phase, so the device will keep SDA low
-because it acknowledges data. However, there are two differences compared to
-'incomplete_address_phase':
-
-a) the message sent out will be a write message
-b) after the address byte, a 0x00 byte will be transferred. Then, stop at ACK.
-
-This is a highly delicate state, the device is set up to write any data to
-register 0x00 (if it has registers) when further clock pulses happen on SCL.
-This is why bus recovery (up to 9 clock pulses) must either check SDA or send
-additional STOP conditions to ensure the bus has been released. Otherwise
-random data will be written to a device!
-
-Lost arbitration
-================
-
-Here, we want to simulate the condition where the master under test loses the
-bus arbitration against another master in a multi-master setup.
-
-"lose_arbitration"
-------------------
-
-This file is write only and you need to write the duration of the arbitration
-intereference (in µs, maximum is 100ms). The calling process will then sleep
-and wait for the next bus clock. The process is interruptible, though.
-
-Arbitration lost is achieved by waiting for SCL going down by the master under
-test and then pulling SDA low for some time. So, the I2C address sent out
-should be corrupted and that should be detected properly. That means that the
-address sent out should have a lot of '1' bits to be able to detect corruption.
-There doesn't need to be a device at this address because arbitration lost
-should be detected beforehand. Also note, that SCL going down is monitored
-using interrupts, so the interrupt latency might cause the first bits to be not
-corrupted. A good starting point for using this fault injector on an otherwise
-idle bus is:
-
-# echo 200 > lose_arbitration &
-# i2cget -y <bus_to_test> 0x3f
-
-Panic during transfer
-=====================
-
-This fault injector will create a Kernel panic once the master under test
-started a transfer. This usually means that the state machine of the bus master
-driver will be ungracefully interrupted and the bus may end up in an unusual
-state. Use this to check if your shutdown/reboot/boot code can handle this
-scenario.
-
-"inject_panic"
---------------
-
-This file is write only and you need to write the delay between the detected
-start of a transmission and the induced Kernel panic (in µs, maximum is 100ms).
-The calling process will then sleep and wait for the next bus clock. The
-process is interruptible, though.
-
-Start of a transfer is detected by waiting for SCL going down by the master
-under test. A good starting point for using this fault injector is:
-
-# echo 0 > inject_panic &
-# i2cget -y <bus_to_test> <some_address>
-
-Note that there doesn't need to be a device listening to the address you are
-using. Results may vary depending on that, though.
diff --git a/Documentation/i2c/gpio-fault-injection.rst b/Documentation/i2c/gpio-fault-injection.rst
new file mode 100644
index 0000000..9dca6ec
--- /dev/null
+++ b/Documentation/i2c/gpio-fault-injection.rst
@@ -0,0 +1,136 @@
+=========================
+Linux I2C fault injection
+=========================
+
+The GPIO based I2C bus master driver can be configured to provide fault
+injection capabilities. It is then meant to be connected to another I2C bus
+which is driven by the I2C bus master driver under test. The GPIO fault
+injection driver can create special states on the bus which the other I2C bus
+master driver should handle gracefully.
+
+Once the Kconfig option I2C_GPIO_FAULT_INJECTOR is enabled, there will be an
+'i2c-fault-injector' subdirectory in the Kernel debugfs filesystem, usually
+mounted at /sys/kernel/debug. There will be a separate subdirectory per GPIO
+driven I2C bus. Each subdirectory will contain files to trigger the fault
+injection. They will be described now along with their intended use-cases.
+
+Wire states
+===========
+
+"scl"
+-----
+
+By reading this file, you get the current state of SCL. By writing, you can
+change its state to either force it low or to release it again. So, by using
+"echo 0 > scl" you force SCL low and thus, no communication will be possible
+because the bus master under test will not be able to clock. It should detect
+the condition of SCL being unresponsive and report an error to the upper
+layers.
+
+"sda"
+-----
+
+By reading this file, you get the current state of SDA. By writing, you can
+change its state to either force it low or to release it again. So, by using
+"echo 0 > sda" you force SDA low and thus, data cannot be transmitted. The bus
+master under test should detect this condition and trigger a bus recovery (see
+I2C specification version 4, section 3.1.16) using the helpers of the Linux I2C
+core (see 'struct bus_recovery_info'). However, the bus recovery will not
+succeed because SDA is still pinned low until you manually release it again
+with "echo 1 > sda". A test with an automatic release can be done with the
+"incomplete transfers" class of fault injectors.
+
+Incomplete transfers
+====================
+
+The following fault injectors create situations where SDA will be held low by a
+device. Bus recovery should be able to fix these situations. But please note:
+there are I2C client devices which detect a stuck SDA on their side and release
+it on their own after a few milliseconds. Also, there might be an external
+device deglitching and monitoring the I2C bus. It could also detect a stuck SDA
+and will init a bus recovery on its own. If you want to implement bus recovery
+in a bus master driver, make sure you checked your hardware setup for such
+devices before. And always verify with a scope or logic analyzer!
+
+"incomplete_address_phase"
+--------------------------
+
+This file is write only and you need to write the address of an existing I2C
+client device to it. Then, a read transfer to this device will be started, but
+it will stop at the ACK phase after the address of the client has been
+transmitted. Because the device will ACK its presence, this results in SDA
+being pulled low by the device while SCL is high. So, similar to the "sda" file
+above, the bus master under test should detect this condition and try a bus
+recovery. This time, however, it should succeed and the device should release
+SDA after toggling SCL.
+
+"incomplete_write_byte"
+-----------------------
+
+Similar to above, this file is write only and you need to write the address of
+an existing I2C client device to it.
+
+The injector will again stop at one ACK phase, so the device will keep SDA low
+because it acknowledges data. However, there are two differences compared to
+'incomplete_address_phase':
+
+a) the message sent out will be a write message
+b) after the address byte, a 0x00 byte will be transferred. Then, stop at ACK.
+
+This is a highly delicate state, the device is set up to write any data to
+register 0x00 (if it has registers) when further clock pulses happen on SCL.
+This is why bus recovery (up to 9 clock pulses) must either check SDA or send
+additional STOP conditions to ensure the bus has been released. Otherwise
+random data will be written to a device!
+
+Lost arbitration
+================
+
+Here, we want to simulate the condition where the master under test loses the
+bus arbitration against another master in a multi-master setup.
+
+"lose_arbitration"
+------------------
+
+This file is write only and you need to write the duration of the arbitration
+intereference (in µs, maximum is 100ms). The calling process will then sleep
+and wait for the next bus clock. The process is interruptible, though.
+
+Arbitration lost is achieved by waiting for SCL going down by the master under
+test and then pulling SDA low for some time. So, the I2C address sent out
+should be corrupted and that should be detected properly. That means that the
+address sent out should have a lot of '1' bits to be able to detect corruption.
+There doesn't need to be a device at this address because arbitration lost
+should be detected beforehand. Also note, that SCL going down is monitored
+using interrupts, so the interrupt latency might cause the first bits to be not
+corrupted. A good starting point for using this fault injector on an otherwise
+idle bus is::
+
+ # echo 200 > lose_arbitration &
+ # i2cget -y <bus_to_test> 0x3f
+
+Panic during transfer
+=====================
+
+This fault injector will create a Kernel panic once the master under test
+started a transfer. This usually means that the state machine of the bus master
+driver will be ungracefully interrupted and the bus may end up in an unusual
+state. Use this to check if your shutdown/reboot/boot code can handle this
+scenario.
+
+"inject_panic"
+--------------
+
+This file is write only and you need to write the delay between the detected
+start of a transmission and the induced Kernel panic (in µs, maximum is 100ms).
+The calling process will then sleep and wait for the next bus clock. The
+process is interruptible, though.
+
+Start of a transfer is detected by waiting for SCL going down by the master
+under test. A good starting point for using this fault injector is::
+
+ # echo 0 > inject_panic &
+ # i2cget -y <bus_to_test> <some_address>
+
+Note that there doesn't need to be a device listening to the address you are
+using. Results may vary depending on that, though.
diff --git a/Documentation/i2c/i2c-protocol b/Documentation/i2c/i2c-protocol
deleted file mode 100644
index ff6d6ce..0000000
--- a/Documentation/i2c/i2c-protocol
+++ /dev/null
@@ -1,88 +0,0 @@
-This document describes the i2c protocol. Or will, when it is finished :-)
-
-Key to symbols
-==============
-
-S (1 bit) : Start bit
-P (1 bit) : Stop bit
-Rd/Wr (1 bit) : Read/Write bit. Rd equals 1, Wr equals 0.
-A, NA (1 bit) : Accept and reverse accept bit.
-Addr (7 bits): I2C 7 bit address. Note that this can be expanded as usual to
- get a 10 bit I2C address.
-Comm (8 bits): Command byte, a data byte which often selects a register on
- the device.
-Data (8 bits): A plain data byte. Sometimes, I write DataLow, DataHigh
- for 16 bit data.
-Count (8 bits): A data byte containing the length of a block operation.
-
-[..]: Data sent by I2C device, as opposed to data sent by the host adapter.
-
-
-Simple send transaction
-======================
-
-This corresponds to i2c_master_send.
-
- S Addr Wr [A] Data [A] Data [A] ... [A] Data [A] P
-
-
-Simple receive transaction
-===========================
-
-This corresponds to i2c_master_recv
-
- S Addr Rd [A] [Data] A [Data] A ... A [Data] NA P
-
-
-Combined transactions
-====================
-
-This corresponds to i2c_transfer
-
-They are just like the above transactions, but instead of a stop bit P
-a start bit S is sent and the transaction continues. An example of
-a byte read, followed by a byte write:
-
- S Addr Rd [A] [Data] NA S Addr Wr [A] Data [A] P
-
-
-Modified transactions
-=====================
-
-The following modifications to the I2C protocol can also be generated by
-setting these flags for i2c messages. With the exception of I2C_M_NOSTART, they
-are usually only needed to work around device issues:
-
-I2C_M_IGNORE_NAK:
- Normally message is interrupted immediately if there is [NA] from the
- client. Setting this flag treats any [NA] as [A], and all of
- message is sent.
- These messages may still fail to SCL lo->hi timeout.
-
-I2C_M_NO_RD_ACK:
- In a read message, master A/NA bit is skipped.
-
-I2C_M_NOSTART:
- In a combined transaction, no 'S Addr Wr/Rd [A]' is generated at some
- point. For example, setting I2C_M_NOSTART on the second partial message
- generates something like:
- S Addr Rd [A] [Data] NA Data [A] P
- If you set the I2C_M_NOSTART variable for the first partial message,
- we do not generate Addr, but we do generate the startbit S. This will
- probably confuse all other clients on your bus, so don't try this.
-
- This is often used to gather transmits from multiple data buffers in
- system memory into something that appears as a single transfer to the
- I2C device but may also be used between direction changes by some
- rare devices.
-
-I2C_M_REV_DIR_ADDR:
- This toggles the Rd/Wr flag. That is, if you want to do a write, but
- need to emit an Rd instead of a Wr, or vice versa, you set this
- flag. For example:
- S Addr Rd [A] Data [A] Data [A] ... [A] Data [A] P
-
-I2C_M_STOP:
- Force a stop condition (P) after the message. Some I2C related protocols
- like SCCB require that. Normally, you really don't want to get interrupted
- between the messages of one transfer.
diff --git a/Documentation/i2c/i2c-protocol.rst b/Documentation/i2c/i2c-protocol.rst
new file mode 100644
index 0000000..2f8fcf6
--- /dev/null
+++ b/Documentation/i2c/i2c-protocol.rst
@@ -0,0 +1,98 @@
+============
+I2C Protocol
+============
+
+This document describes the i2c protocol. Or will, when it is finished :-)
+
+Key to symbols
+==============
+
+=============== =============================================================
+S (1 bit) : Start bit
+P (1 bit) : Stop bit
+Rd/Wr (1 bit) : Read/Write bit. Rd equals 1, Wr equals 0.
+A, NA (1 bit) : Accept and reverse accept bit.
+Addr (7 bits): I2C 7 bit address. Note that this can be expanded as usual to
+ get a 10 bit I2C address.
+Comm (8 bits): Command byte, a data byte which often selects a register on
+ the device.
+Data (8 bits): A plain data byte. Sometimes, I write DataLow, DataHigh
+ for 16 bit data.
+Count (8 bits): A data byte containing the length of a block operation.
+
+[..]: Data sent by I2C device, as opposed to data sent by the
+ host adapter.
+=============== =============================================================
+
+
+Simple send transaction
+=======================
+
+This corresponds to i2c_master_send::
+
+ S Addr Wr [A] Data [A] Data [A] ... [A] Data [A] P
+
+
+Simple receive transaction
+==========================
+
+This corresponds to i2c_master_recv::
+
+ S Addr Rd [A] [Data] A [Data] A ... A [Data] NA P
+
+
+Combined transactions
+=====================
+
+This corresponds to i2c_transfer
+
+They are just like the above transactions, but instead of a stop bit P
+a start bit S is sent and the transaction continues. An example of
+a byte read, followed by a byte write::
+
+ S Addr Rd [A] [Data] NA S Addr Wr [A] Data [A] P
+
+
+Modified transactions
+=====================
+
+The following modifications to the I2C protocol can also be generated by
+setting these flags for i2c messages. With the exception of I2C_M_NOSTART, they
+are usually only needed to work around device issues:
+
+I2C_M_IGNORE_NAK:
+ Normally message is interrupted immediately if there is [NA] from the
+ client. Setting this flag treats any [NA] as [A], and all of
+ message is sent.
+ These messages may still fail to SCL lo->hi timeout.
+
+I2C_M_NO_RD_ACK:
+ In a read message, master A/NA bit is skipped.
+
+I2C_M_NOSTART:
+ In a combined transaction, no 'S Addr Wr/Rd [A]' is generated at some
+ point. For example, setting I2C_M_NOSTART on the second partial message
+ generates something like::
+
+ S Addr Rd [A] [Data] NA Data [A] P
+
+ If you set the I2C_M_NOSTART variable for the first partial message,
+ we do not generate Addr, but we do generate the startbit S. This will
+ probably confuse all other clients on your bus, so don't try this.
+
+ This is often used to gather transmits from multiple data buffers in
+ system memory into something that appears as a single transfer to the
+ I2C device but may also be used between direction changes by some
+ rare devices.
+
+I2C_M_REV_DIR_ADDR:
+ This toggles the Rd/Wr flag. That is, if you want to do a write, but
+ need to emit an Rd instead of a Wr, or vice versa, you set this
+ flag. For example::
+
+ S Addr Rd [A] Data [A] Data [A] ... [A] Data [A] P
+
+I2C_M_STOP:
+ Force a stop condition (P) after the message. Some I2C related protocols
+ like SCCB require that. Normally, you really don't want to get interrupted
+ between the messages of one transfer.
diff --git a/Documentation/i2c/i2c-stub b/Documentation/i2c/i2c-stub
deleted file mode 100644
index a16924f..0000000
--- a/Documentation/i2c/i2c-stub
+++ /dev/null
@@ -1,64 +0,0 @@
-MODULE: i2c-stub
-
-DESCRIPTION:
-
-This module is a very simple fake I2C/SMBus driver. It implements six
-types of SMBus commands: write quick, (r/w) byte, (r/w) byte data, (r/w)
-word data, (r/w) I2C block data, and (r/w) SMBus block data.
-
-You need to provide chip addresses as a module parameter when loading this
-driver, which will then only react to SMBus commands to these addresses.
-
-No hardware is needed nor associated with this module. It will accept write
-quick commands to the specified addresses; it will respond to the other
-commands (also to the specified addresses) by reading from or writing to
-arrays in memory. It will also spam the kernel logs for every command it
-handles.
-
-A pointer register with auto-increment is implemented for all byte
-operations. This allows for continuous byte reads like those supported by
-EEPROMs, among others.
-
-SMBus block command support is disabled by default, and must be enabled
-explicitly by setting the respective bits (0x03000000) in the functionality
-module parameter.
-
-SMBus block commands must be written to configure an SMBus command for
-SMBus block operations. Writes can be partial. Block read commands always
-return the number of bytes selected with the largest write so far.
-
-The typical use-case is like this:
- 1. load this module
- 2. use i2cset (from the i2c-tools project) to pre-load some data
- 3. load the target chip driver module
- 4. observe its behavior in the kernel log
-
-There's a script named i2c-stub-from-dump in the i2c-tools package which
-can load register values automatically from a chip dump.
-
-PARAMETERS:
-
-int chip_addr[10]:
- The SMBus addresses to emulate chips at.
-
-unsigned long functionality:
- Functionality override, to disable some commands. See I2C_FUNC_*
- constants in <linux/i2c.h> for the suitable values. For example,
- value 0x1f0000 would only enable the quick, byte and byte data
- commands.
-
-u8 bank_reg[10]
-u8 bank_mask[10]
-u8 bank_start[10]
-u8 bank_end[10]:
- Optional bank settings. They tell which bits in which register
- select the active bank, as well as the range of banked registers.
-
-CAVEATS:
-
-If your target driver polls some byte or word waiting for it to change, the
-stub could lock it up. Use i2cset to unlock it.
-
-If you spam it hard enough, printk can be lossy. This module really wants
-something like relayfs.
-
diff --git a/Documentation/i2c/i2c-stub.rst b/Documentation/i2c/i2c-stub.rst
new file mode 100644
index 0000000..a6fc691
--- /dev/null
+++ b/Documentation/i2c/i2c-stub.rst
@@ -0,0 +1,66 @@
+========
+i2c-stub
+========
+
+Description
+===========
+
+This module is a very simple fake I2C/SMBus driver. It implements six
+types of SMBus commands: write quick, (r/w) byte, (r/w) byte data, (r/w)
+word data, (r/w) I2C block data, and (r/w) SMBus block data.
+
+You need to provide chip addresses as a module parameter when loading this
+driver, which will then only react to SMBus commands to these addresses.
+
+No hardware is needed nor associated with this module. It will accept write
+quick commands to the specified addresses; it will respond to the other
+commands (also to the specified addresses) by reading from or writing to
+arrays in memory. It will also spam the kernel logs for every command it
+handles.
+
+A pointer register with auto-increment is implemented for all byte
+operations. This allows for continuous byte reads like those supported by
+EEPROMs, among others.
+
+SMBus block command support is disabled by default, and must be enabled
+explicitly by setting the respective bits (0x03000000) in the functionality
+module parameter.
+
+SMBus block commands must be written to configure an SMBus command for
+SMBus block operations. Writes can be partial. Block read commands always
+return the number of bytes selected with the largest write so far.
+
+The typical use-case is like this:
+
+ 1. load this module
+ 2. use i2cset (from the i2c-tools project) to pre-load some data
+ 3. load the target chip driver module
+ 4. observe its behavior in the kernel log
+
+There's a script named i2c-stub-from-dump in the i2c-tools package which
+can load register values automatically from a chip dump.
+
+Parameters
+==========
+
+int chip_addr[10]:
+ The SMBus addresses to emulate chips at.
+
+unsigned long functionality:
+ Functionality override, to disable some commands. See I2C_FUNC_*
+ constants in <linux/i2c.h> for the suitable values. For example,
+ value 0x1f0000 would only enable the quick, byte and byte data
+ commands.
+
+u8 bank_reg[10], u8 bank_mask[10], u8 bank_start[10], u8 bank_end[10]:
+ Optional bank settings. They tell which bits in which register
+ select the active bank, as well as the range of banked registers.
+
+Caveats
+=======
+
+If your target driver polls some byte or word waiting for it to change, the
+stub could lock it up. Use i2cset to unlock it.
+
+If you spam it hard enough, printk can be lossy. This module really wants
+something like relayfs.
diff --git a/Documentation/i2c/i2c-topology b/Documentation/i2c/i2c-topology
deleted file mode 100644
index f74d78b..0000000
--- a/Documentation/i2c/i2c-topology
+++ /dev/null
@@ -1,376 +0,0 @@
-I2C topology
-============
-
-There are a couple of reasons for building more complex i2c topologies
-than a straight-forward i2c bus with one adapter and one or more devices.
-
-1. A mux may be needed on the bus to prevent address collisions.
-
-2. The bus may be accessible from some external bus master, and arbitration
- may be needed to determine if it is ok to access the bus.
-
-3. A device (particularly RF tuners) may want to avoid the digital noise
- from the i2c bus, at least most of the time, and sits behind a gate
- that has to be operated before the device can be accessed.
-
-Etc
-
-These constructs are represented as i2c adapter trees by Linux, where
-each adapter has a parent adapter (except the root adapter) and zero or
-more child adapters. The root adapter is the actual adapter that issues
-i2c transfers, and all adapters with a parent are part of an "i2c-mux"
-object (quoted, since it can also be an arbitrator or a gate).
-
-Depending of the particular mux driver, something happens when there is
-an i2c transfer on one of its child adapters. The mux driver can
-obviously operate a mux, but it can also do arbitration with an external
-bus master or open a gate. The mux driver has two operations for this,
-select and deselect. select is called before the transfer and (the
-optional) deselect is called after the transfer.
-
-
-Locking
-=======
-
-There are two variants of locking available to i2c muxes, they can be
-mux-locked or parent-locked muxes. As is evident from below, it can be
-useful to know if a mux is mux-locked or if it is parent-locked. The
-following list was correct at the time of writing:
-
-In drivers/i2c/muxes/
-i2c-arb-gpio-challenge Parent-locked
-i2c-mux-gpio Normally parent-locked, mux-locked iff
- all involved gpio pins are controlled by the
- same i2c root adapter that they mux.
-i2c-mux-gpmux Normally parent-locked, mux-locked iff
- specified in device-tree.
-i2c-mux-ltc4306 Mux-locked
-i2c-mux-mlxcpld Parent-locked
-i2c-mux-pca9541 Parent-locked
-i2c-mux-pca954x Parent-locked
-i2c-mux-pinctrl Normally parent-locked, mux-locked iff
- all involved pinctrl devices are controlled
- by the same i2c root adapter that they mux.
-i2c-mux-reg Parent-locked
-
-In drivers/iio/
-gyro/mpu3050 Mux-locked
-imu/inv_mpu6050/ Mux-locked
-
-In drivers/media/
-dvb-frontends/lgdt3306a Mux-locked
-dvb-frontends/m88ds3103 Parent-locked
-dvb-frontends/rtl2830 Parent-locked
-dvb-frontends/rtl2832 Mux-locked
-dvb-frontends/si2168 Mux-locked
-usb/cx231xx/ Parent-locked
-
-
-Mux-locked muxes
-----------------
-
-Mux-locked muxes does not lock the entire parent adapter during the
-full select-transfer-deselect transaction, only the muxes on the parent
-adapter are locked. Mux-locked muxes are mostly interesting if the
-select and/or deselect operations must use i2c transfers to complete
-their tasks. Since the parent adapter is not fully locked during the
-full transaction, unrelated i2c transfers may interleave the different
-stages of the transaction. This has the benefit that the mux driver
-may be easier and cleaner to implement, but it has some caveats.
-
-ML1. If you build a topology with a mux-locked mux being the parent
- of a parent-locked mux, this might break the expectation from the
- parent-locked mux that the root adapter is locked during the
- transaction.
-
-ML2. It is not safe to build arbitrary topologies with two (or more)
- mux-locked muxes that are not siblings, when there are address
- collisions between the devices on the child adapters of these
- non-sibling muxes.
-
- I.e. the select-transfer-deselect transaction targeting e.g. device
- address 0x42 behind mux-one may be interleaved with a similar
- operation targeting device address 0x42 behind mux-two. The
- intension with such a topology would in this hypothetical example
- be that mux-one and mux-two should not be selected simultaneously,
- but mux-locked muxes do not guarantee that in all topologies.
-
-ML3. A mux-locked mux cannot be used by a driver for auto-closing
- gates/muxes, i.e. something that closes automatically after a given
- number (one, in most cases) of i2c transfers. Unrelated i2c transfers
- may creep in and close prematurely.
-
-ML4. If any non-i2c operation in the mux driver changes the i2c mux state,
- the driver has to lock the root adapter during that operation.
- Otherwise garbage may appear on the bus as seen from devices
- behind the mux, when an unrelated i2c transfer is in flight during
- the non-i2c mux-changing operation.
-
-
-Mux-locked Example
-------------------
-
- .----------. .--------.
- .--------. | mux- |-----| dev D1 |
- | root |--+--| locked | '--------'
- '--------' | | mux M1 |--. .--------.
- | '----------' '--| dev D2 |
- | .--------. '--------'
- '--| dev D3 |
- '--------'
-
-When there is an access to D1, this happens:
-
- 1. Someone issues an i2c-transfer to D1.
- 2. M1 locks muxes on its parent (the root adapter in this case).
- 3. M1 calls ->select to ready the mux.
- 4. M1 (presumably) does some i2c-transfers as part of its select.
- These transfers are normal i2c-transfers that locks the parent
- adapter.
- 5. M1 feeds the i2c-transfer from step 1 to its parent adapter as a
- normal i2c-transfer that locks the parent adapter.
- 6. M1 calls ->deselect, if it has one.
- 7. Same rules as in step 4, but for ->deselect.
- 8. M1 unlocks muxes on its parent.
-
-This means that accesses to D2 are lockout out for the full duration
-of the entire operation. But accesses to D3 are possibly interleaved
-at any point.
-
-
-Parent-locked muxes
--------------------
-
-Parent-locked muxes lock the parent adapter during the full select-
-transfer-deselect transaction. The implication is that the mux driver
-has to ensure that any and all i2c transfers through that parent
-adapter during the transaction are unlocked i2c transfers (using e.g.
-__i2c_transfer), or a deadlock will follow. There are a couple of
-caveats.
-
-PL1. If you build a topology with a parent-locked mux being the child
- of another mux, this might break a possible assumption from the
- child mux that the root adapter is unused between its select op
- and the actual transfer (e.g. if the child mux is auto-closing
- and the parent mux issus i2c-transfers as part of its select).
- This is especially the case if the parent mux is mux-locked, but
- it may also happen if the parent mux is parent-locked.
-
-PL2. If select/deselect calls out to other subsystems such as gpio,
- pinctrl, regmap or iio, it is essential that any i2c transfers
- caused by these subsystems are unlocked. This can be convoluted to
- accomplish, maybe even impossible if an acceptably clean solution
- is sought.
-
-
-Parent-locked Example
----------------------
-
- .----------. .--------.
- .--------. | parent- |-----| dev D1 |
- | root |--+--| locked | '--------'
- '--------' | | mux M1 |--. .--------.
- | '----------' '--| dev D2 |
- | .--------. '--------'
- '--| dev D3 |
- '--------'
-
-When there is an access to D1, this happens:
-
- 1. Someone issues an i2c-transfer to D1.
- 2. M1 locks muxes on its parent (the root adapter in this case).
- 3. M1 locks its parent adapter.
- 4. M1 calls ->select to ready the mux.
- 5. If M1 does any i2c-transfers (on this root adapter) as part of
- its select, those transfers must be unlocked i2c-transfers so
- that they do not deadlock the root adapter.
- 6. M1 feeds the i2c-transfer from step 1 to the root adapter as an
- unlocked i2c-transfer, so that it does not deadlock the parent
- adapter.
- 7. M1 calls ->deselect, if it has one.
- 8. Same rules as in step 5, but for ->deselect.
- 9. M1 unlocks its parent adapter.
-10. M1 unlocks muxes on its parent.
-
-
-This means that accesses to both D2 and D3 are locked out for the full
-duration of the entire operation.
-
-
-Complex Examples
-================
-
-Parent-locked mux as parent of parent-locked mux
-------------------------------------------------
-
-This is a useful topology, but it can be bad.
-
- .----------. .----------. .--------.
- .--------. | parent- |-----| parent- |-----| dev D1 |
- | root |--+--| locked | | locked | '--------'
- '--------' | | mux M1 |--. | mux M2 |--. .--------.
- | '----------' | '----------' '--| dev D2 |
- | .--------. | .--------. '--------'
- '--| dev D4 | '--| dev D3 |
- '--------' '--------'
-
-When any device is accessed, all other devices are locked out for
-the full duration of the operation (both muxes lock their parent,
-and specifically when M2 requests its parent to lock, M1 passes
-the buck to the root adapter).
-
-This topology is bad if M2 is an auto-closing mux and M1->select
-issues any unlocked i2c transfers on the root adapter that may leak
-through and be seen by the M2 adapter, thus closing M2 prematurely.
-
-
-Mux-locked mux as parent of mux-locked mux
-------------------------------------------
-
-This is a good topology.
-
- .----------. .----------. .--------.
- .--------. | mux- |-----| mux- |-----| dev D1 |
- | root |--+--| locked | | locked | '--------'
- '--------' | | mux M1 |--. | mux M2 |--. .--------.
- | '----------' | '----------' '--| dev D2 |
- | .--------. | .--------. '--------'
- '--| dev D4 | '--| dev D3 |
- '--------' '--------'
-
-When device D1 is accessed, accesses to D2 are locked out for the
-full duration of the operation (muxes on the top child adapter of M1
-are locked). But accesses to D3 and D4 are possibly interleaved at
-any point. Accesses to D3 locks out D1 and D2, but accesses to D4
-are still possibly interleaved.
-
-
-Mux-locked mux as parent of parent-locked mux
----------------------------------------------
-
-This is probably a bad topology.
-
- .----------. .----------. .--------.
- .--------. | mux- |-----| parent- |-----| dev D1 |
- | root |--+--| locked | | locked | '--------'
- '--------' | | mux M1 |--. | mux M2 |--. .--------.
- | '----------' | '----------' '--| dev D2 |
- | .--------. | .--------. '--------'
- '--| dev D4 | '--| dev D3 |
- '--------' '--------'
-
-When device D1 is accessed, accesses to D2 and D3 are locked out
-for the full duration of the operation (M1 locks child muxes on the
-root adapter). But accesses to D4 are possibly interleaved at any
-point.
-
-This kind of topology is generally not suitable and should probably
-be avoided. The reason is that M2 probably assumes that there will
-be no i2c transfers during its calls to ->select and ->deselect, and
-if there are, any such transfers might appear on the slave side of M2
-as partial i2c transfers, i.e. garbage or worse. This might cause
-device lockups and/or other problems.
-
-The topology is especially troublesome if M2 is an auto-closing
-mux. In that case, any interleaved accesses to D4 might close M2
-prematurely, as might any i2c-transfers part of M1->select.
-
-But if M2 is not making the above stated assumption, and if M2 is not
-auto-closing, the topology is fine.
-
-
-Parent-locked mux as parent of mux-locked mux
----------------------------------------------
-
-This is a good topology.
-
- .----------. .----------. .--------.
- .--------. | parent- |-----| mux- |-----| dev D1 |
- | root |--+--| locked | | locked | '--------'
- '--------' | | mux M1 |--. | mux M2 |--. .--------.
- | '----------' | '----------' '--| dev D2 |
- | .--------. | .--------. '--------'
- '--| dev D4 | '--| dev D3 |
- '--------' '--------'
-
-When D1 is accessed, accesses to D2 are locked out for the full
-duration of the operation (muxes on the top child adapter of M1
-are locked). Accesses to D3 and D4 are possibly interleaved at
-any point, just as is expected for mux-locked muxes.
-
-When D3 or D4 are accessed, everything else is locked out. For D3
-accesses, M1 locks the root adapter. For D4 accesses, the root
-adapter is locked directly.
-
-
-Two mux-locked sibling muxes
-----------------------------
-
-This is a good topology.
-
- .--------.
- .----------. .--| dev D1 |
- | mux- |--' '--------'
- .--| locked | .--------.
- | | mux M1 |-----| dev D2 |
- | '----------' '--------'
- | .----------. .--------.
- .--------. | | mux- |-----| dev D3 |
- | root |--+--| locked | '--------'
- '--------' | | mux M2 |--. .--------.
- | '----------' '--| dev D4 |
- | .--------. '--------'
- '--| dev D5 |
- '--------'
-
-When D1 is accessed, accesses to D2, D3 and D4 are locked out. But
-accesses to D5 may be interleaved at any time.
-
-
-Two parent-locked sibling muxes
--------------------------------
-
-This is a good topology.
-
- .--------.
- .----------. .--| dev D1 |
- | parent- |--' '--------'
- .--| locked | .--------.
- | | mux M1 |-----| dev D2 |
- | '----------' '--------'
- | .----------. .--------.
- .--------. | | parent- |-----| dev D3 |
- | root |--+--| locked | '--------'
- '--------' | | mux M2 |--. .--------.
- | '----------' '--| dev D4 |
- | .--------. '--------'
- '--| dev D5 |
- '--------'
-
-When any device is accessed, accesses to all other devices are locked
-out.
-
-
-Mux-locked and parent-locked sibling muxes
-------------------------------------------
-
-This is a good topology.
-
- .--------.
- .----------. .--| dev D1 |
- | mux- |--' '--------'
- .--| locked | .--------.
- | | mux M1 |-----| dev D2 |
- | '----------' '--------'
- | .----------. .--------.
- .--------. | | parent- |-----| dev D3 |
- | root |--+--| locked | '--------'
- '--------' | | mux M2 |--. .--------.
- | '----------' '--| dev D4 |
- | .--------. '--------'
- '--| dev D5 |
- '--------'
-
-When D1 or D2 are accessed, accesses to D3 and D4 are locked out while
-accesses to D5 may interleave. When D3 or D4 are accessed, accesses to
-all other devices are locked out.
diff --git a/Documentation/i2c/i2c-topology.rst b/Documentation/i2c/i2c-topology.rst
new file mode 100644
index 0000000..0c1ae95
--- /dev/null
+++ b/Documentation/i2c/i2c-topology.rst
@@ -0,0 +1,396 @@
+============
+I2C topology
+============
+
+There are a couple of reasons for building more complex i2c topologies
+than a straight-forward i2c bus with one adapter and one or more devices.
+
+1. A mux may be needed on the bus to prevent address collisions.
+
+2. The bus may be accessible from some external bus master, and arbitration
+ may be needed to determine if it is ok to access the bus.
+
+3. A device (particularly RF tuners) may want to avoid the digital noise
+ from the i2c bus, at least most of the time, and sits behind a gate
+ that has to be operated before the device can be accessed.
+
+Etc
+===
+
+These constructs are represented as i2c adapter trees by Linux, where
+each adapter has a parent adapter (except the root adapter) and zero or
+more child adapters. The root adapter is the actual adapter that issues
+i2c transfers, and all adapters with a parent are part of an "i2c-mux"
+object (quoted, since it can also be an arbitrator or a gate).
+
+Depending of the particular mux driver, something happens when there is
+an i2c transfer on one of its child adapters. The mux driver can
+obviously operate a mux, but it can also do arbitration with an external
+bus master or open a gate. The mux driver has two operations for this,
+select and deselect. select is called before the transfer and (the
+optional) deselect is called after the transfer.
+
+
+Locking
+=======
+
+There are two variants of locking available to i2c muxes, they can be
+mux-locked or parent-locked muxes. As is evident from below, it can be
+useful to know if a mux is mux-locked or if it is parent-locked. The
+following list was correct at the time of writing:
+
+In drivers/i2c/muxes/:
+
+====================== =============================================
+i2c-arb-gpio-challenge Parent-locked
+i2c-mux-gpio Normally parent-locked, mux-locked iff
+ all involved gpio pins are controlled by the
+ same i2c root adapter that they mux.
+i2c-mux-gpmux Normally parent-locked, mux-locked iff
+ specified in device-tree.
+i2c-mux-ltc4306 Mux-locked
+i2c-mux-mlxcpld Parent-locked
+i2c-mux-pca9541 Parent-locked
+i2c-mux-pca954x Parent-locked
+i2c-mux-pinctrl Normally parent-locked, mux-locked iff
+ all involved pinctrl devices are controlled
+ by the same i2c root adapter that they mux.
+i2c-mux-reg Parent-locked
+====================== =============================================
+
+In drivers/iio/:
+
+====================== =============================================
+gyro/mpu3050 Mux-locked
+imu/inv_mpu6050/ Mux-locked
+====================== =============================================
+
+In drivers/media/:
+
+======================= =============================================
+dvb-frontends/lgdt3306a Mux-locked
+dvb-frontends/m88ds3103 Parent-locked
+dvb-frontends/rtl2830 Parent-locked
+dvb-frontends/rtl2832 Mux-locked
+dvb-frontends/si2168 Mux-locked
+usb/cx231xx/ Parent-locked
+======================= =============================================
+
+
+Mux-locked muxes
+----------------
+
+Mux-locked muxes does not lock the entire parent adapter during the
+full select-transfer-deselect transaction, only the muxes on the parent
+adapter are locked. Mux-locked muxes are mostly interesting if the
+select and/or deselect operations must use i2c transfers to complete
+their tasks. Since the parent adapter is not fully locked during the
+full transaction, unrelated i2c transfers may interleave the different
+stages of the transaction. This has the benefit that the mux driver
+may be easier and cleaner to implement, but it has some caveats.
+
+==== =====================================================================
+ML1. If you build a topology with a mux-locked mux being the parent
+ of a parent-locked mux, this might break the expectation from the
+ parent-locked mux that the root adapter is locked during the
+ transaction.
+
+ML2. It is not safe to build arbitrary topologies with two (or more)
+ mux-locked muxes that are not siblings, when there are address
+ collisions between the devices on the child adapters of these
+ non-sibling muxes.
+
+ I.e. the select-transfer-deselect transaction targeting e.g. device
+ address 0x42 behind mux-one may be interleaved with a similar
+ operation targeting device address 0x42 behind mux-two. The
+ intension with such a topology would in this hypothetical example
+ be that mux-one and mux-two should not be selected simultaneously,
+ but mux-locked muxes do not guarantee that in all topologies.
+
+ML3. A mux-locked mux cannot be used by a driver for auto-closing
+ gates/muxes, i.e. something that closes automatically after a given
+ number (one, in most cases) of i2c transfers. Unrelated i2c transfers
+ may creep in and close prematurely.
+
+ML4. If any non-i2c operation in the mux driver changes the i2c mux state,
+ the driver has to lock the root adapter during that operation.
+ Otherwise garbage may appear on the bus as seen from devices
+ behind the mux, when an unrelated i2c transfer is in flight during
+ the non-i2c mux-changing operation.
+==== =====================================================================
+
+
+Mux-locked Example
+------------------
+
+
+::
+
+ .----------. .--------.
+ .--------. | mux- |-----| dev D1 |
+ | root |--+--| locked | '--------'
+ '--------' | | mux M1 |--. .--------.
+ | '----------' '--| dev D2 |
+ | .--------. '--------'
+ '--| dev D3 |
+ '--------'
+
+When there is an access to D1, this happens:
+
+ 1. Someone issues an i2c-transfer to D1.
+ 2. M1 locks muxes on its parent (the root adapter in this case).
+ 3. M1 calls ->select to ready the mux.
+ 4. M1 (presumably) does some i2c-transfers as part of its select.
+ These transfers are normal i2c-transfers that locks the parent
+ adapter.
+ 5. M1 feeds the i2c-transfer from step 1 to its parent adapter as a
+ normal i2c-transfer that locks the parent adapter.
+ 6. M1 calls ->deselect, if it has one.
+ 7. Same rules as in step 4, but for ->deselect.
+ 8. M1 unlocks muxes on its parent.
+
+This means that accesses to D2 are lockout out for the full duration
+of the entire operation. But accesses to D3 are possibly interleaved
+at any point.
+
+
+Parent-locked muxes
+-------------------
+
+Parent-locked muxes lock the parent adapter during the full select-
+transfer-deselect transaction. The implication is that the mux driver
+has to ensure that any and all i2c transfers through that parent
+adapter during the transaction are unlocked i2c transfers (using e.g.
+__i2c_transfer), or a deadlock will follow. There are a couple of
+caveats.
+
+==== ====================================================================
+PL1. If you build a topology with a parent-locked mux being the child
+ of another mux, this might break a possible assumption from the
+ child mux that the root adapter is unused between its select op
+ and the actual transfer (e.g. if the child mux is auto-closing
+ and the parent mux issus i2c-transfers as part of its select).
+ This is especially the case if the parent mux is mux-locked, but
+ it may also happen if the parent mux is parent-locked.
+
+PL2. If select/deselect calls out to other subsystems such as gpio,
+ pinctrl, regmap or iio, it is essential that any i2c transfers
+ caused by these subsystems are unlocked. This can be convoluted to
+ accomplish, maybe even impossible if an acceptably clean solution
+ is sought.
+==== ====================================================================
+
+
+Parent-locked Example
+---------------------
+
+::
+
+ .----------. .--------.
+ .--------. | parent- |-----| dev D1 |
+ | root |--+--| locked | '--------'
+ '--------' | | mux M1 |--. .--------.
+ | '----------' '--| dev D2 |
+ | .--------. '--------'
+ '--| dev D3 |
+ '--------'
+
+When there is an access to D1, this happens:
+
+ 1. Someone issues an i2c-transfer to D1.
+ 2. M1 locks muxes on its parent (the root adapter in this case).
+ 3. M1 locks its parent adapter.
+ 4. M1 calls ->select to ready the mux.
+ 5. If M1 does any i2c-transfers (on this root adapter) as part of
+ its select, those transfers must be unlocked i2c-transfers so
+ that they do not deadlock the root adapter.
+ 6. M1 feeds the i2c-transfer from step 1 to the root adapter as an
+ unlocked i2c-transfer, so that it does not deadlock the parent
+ adapter.
+ 7. M1 calls ->deselect, if it has one.
+ 8. Same rules as in step 5, but for ->deselect.
+ 9. M1 unlocks its parent adapter.
+ 10. M1 unlocks muxes on its parent.
+
+
+This means that accesses to both D2 and D3 are locked out for the full
+duration of the entire operation.
+
+
+Complex Examples
+================
+
+Parent-locked mux as parent of parent-locked mux
+------------------------------------------------
+
+This is a useful topology, but it can be bad::
+
+ .----------. .----------. .--------.
+ .--------. | parent- |-----| parent- |-----| dev D1 |
+ | root |--+--| locked | | locked | '--------'
+ '--------' | | mux M1 |--. | mux M2 |--. .--------.
+ | '----------' | '----------' '--| dev D2 |
+ | .--------. | .--------. '--------'
+ '--| dev D4 | '--| dev D3 |
+ '--------' '--------'
+
+When any device is accessed, all other devices are locked out for
+the full duration of the operation (both muxes lock their parent,
+and specifically when M2 requests its parent to lock, M1 passes
+the buck to the root adapter).
+
+This topology is bad if M2 is an auto-closing mux and M1->select
+issues any unlocked i2c transfers on the root adapter that may leak
+through and be seen by the M2 adapter, thus closing M2 prematurely.
+
+
+Mux-locked mux as parent of mux-locked mux
+------------------------------------------
+
+This is a good topology::
+
+ .----------. .----------. .--------.
+ .--------. | mux- |-----| mux- |-----| dev D1 |
+ | root |--+--| locked | | locked | '--------'
+ '--------' | | mux M1 |--. | mux M2 |--. .--------.
+ | '----------' | '----------' '--| dev D2 |
+ | .--------. | .--------. '--------'
+ '--| dev D4 | '--| dev D3 |
+ '--------' '--------'
+
+When device D1 is accessed, accesses to D2 are locked out for the
+full duration of the operation (muxes on the top child adapter of M1
+are locked). But accesses to D3 and D4 are possibly interleaved at
+any point. Accesses to D3 locks out D1 and D2, but accesses to D4
+are still possibly interleaved.
+
+
+Mux-locked mux as parent of parent-locked mux
+---------------------------------------------
+
+This is probably a bad topology::
+
+ .----------. .----------. .--------.
+ .--------. | mux- |-----| parent- |-----| dev D1 |
+ | root |--+--| locked | | locked | '--------'
+ '--------' | | mux M1 |--. | mux M2 |--. .--------.
+ | '----------' | '----------' '--| dev D2 |
+ | .--------. | .--------. '--------'
+ '--| dev D4 | '--| dev D3 |
+ '--------' '--------'
+
+When device D1 is accessed, accesses to D2 and D3 are locked out
+for the full duration of the operation (M1 locks child muxes on the
+root adapter). But accesses to D4 are possibly interleaved at any
+point.
+
+This kind of topology is generally not suitable and should probably
+be avoided. The reason is that M2 probably assumes that there will
+be no i2c transfers during its calls to ->select and ->deselect, and
+if there are, any such transfers might appear on the slave side of M2
+as partial i2c transfers, i.e. garbage or worse. This might cause
+device lockups and/or other problems.
+
+The topology is especially troublesome if M2 is an auto-closing
+mux. In that case, any interleaved accesses to D4 might close M2
+prematurely, as might any i2c-transfers part of M1->select.
+
+But if M2 is not making the above stated assumption, and if M2 is not
+auto-closing, the topology is fine.
+
+
+Parent-locked mux as parent of mux-locked mux
+---------------------------------------------
+
+This is a good topology::
+
+ .----------. .----------. .--------.
+ .--------. | parent- |-----| mux- |-----| dev D1 |
+ | root |--+--| locked | | locked | '--------'
+ '--------' | | mux M1 |--. | mux M2 |--. .--------.
+ | '----------' | '----------' '--| dev D2 |
+ | .--------. | .--------. '--------'
+ '--| dev D4 | '--| dev D3 |
+ '--------' '--------'
+
+When D1 is accessed, accesses to D2 are locked out for the full
+duration of the operation (muxes on the top child adapter of M1
+are locked). Accesses to D3 and D4 are possibly interleaved at
+any point, just as is expected for mux-locked muxes.
+
+When D3 or D4 are accessed, everything else is locked out. For D3
+accesses, M1 locks the root adapter. For D4 accesses, the root
+adapter is locked directly.
+
+
+Two mux-locked sibling muxes
+----------------------------
+
+This is a good topology::
+
+ .--------.
+ .----------. .--| dev D1 |
+ | mux- |--' '--------'
+ .--| locked | .--------.
+ | | mux M1 |-----| dev D2 |
+ | '----------' '--------'
+ | .----------. .--------.
+ .--------. | | mux- |-----| dev D3 |
+ | root |--+--| locked | '--------'
+ '--------' | | mux M2 |--. .--------.
+ | '----------' '--| dev D4 |
+ | .--------. '--------'
+ '--| dev D5 |
+ '--------'
+
+When D1 is accessed, accesses to D2, D3 and D4 are locked out. But
+accesses to D5 may be interleaved at any time.
+
+
+Two parent-locked sibling muxes
+-------------------------------
+
+This is a good topology::
+
+ .--------.
+ .----------. .--| dev D1 |
+ | parent- |--' '--------'
+ .--| locked | .--------.
+ | | mux M1 |-----| dev D2 |
+ | '----------' '--------'
+ | .----------. .--------.
+ .--------. | | parent- |-----| dev D3 |
+ | root |--+--| locked | '--------'
+ '--------' | | mux M2 |--. .--------.
+ | '----------' '--| dev D4 |
+ | .--------. '--------'
+ '--| dev D5 |
+ '--------'
+
+When any device is accessed, accesses to all other devices are locked
+out.
+
+
+Mux-locked and parent-locked sibling muxes
+------------------------------------------
+
+This is a good topology::
+
+ .--------.
+ .----------. .--| dev D1 |
+ | mux- |--' '--------'
+ .--| locked | .--------.
+ | | mux M1 |-----| dev D2 |
+ | '----------' '--------'
+ | .----------. .--------.
+ .--------. | | parent- |-----| dev D3 |
+ | root |--+--| locked | '--------'
+ '--------' | | mux M2 |--. .--------.
+ | '----------' '--| dev D4 |
+ | .--------. '--------'
+ '--| dev D5 |
+ '--------'
+
+When D1 or D2 are accessed, accesses to D3 and D4 are locked out while
+accesses to D5 may interleave. When D3 or D4 are accessed, accesses to
+all other devices are locked out.
diff --git a/Documentation/i2c/index.rst b/Documentation/i2c/index.rst
new file mode 100644
index 0000000..cd8d020
--- /dev/null
+++ b/Documentation/i2c/index.rst
@@ -0,0 +1,37 @@
+. SPDX-License-Identifier: GPL-2.0
+
+===================
+I2C/SMBus Subsystem
+===================
+
+.. toctree::
+ :maxdepth: 1
+
+ dev-interface
+ dma-considerations
+ fault-codes
+ functionality
+ gpio-fault-injection
+ i2c-protocol
+ i2c-stub
+ i2c-topology
+ instantiating-devices
+ old-module-parameters
+ slave-eeprom-backend
+ slave-interface
+ smbus-protocol
+ summary
+ ten-bit-addresses
+ upgrading-clients
+ writing-clients
+
+ muxes/i2c-mux-gpio
+
+ busses/index
+
+.. only:: subproject and html
+
+ Indices
+ =======
+
+ * :ref:`genindex`
diff --git a/Documentation/i2c/instantiating-devices b/Documentation/i2c/instantiating-devices
deleted file mode 100644
index 345e9ea..0000000
--- a/Documentation/i2c/instantiating-devices
+++ /dev/null
@@ -1,248 +0,0 @@
-How to instantiate I2C devices
-==============================
-
-Unlike PCI or USB devices, I2C devices are not enumerated at the hardware
-level. Instead, the software must know which devices are connected on each
-I2C bus segment, and what address these devices are using. For this
-reason, the kernel code must instantiate I2C devices explicitly. There are
-several ways to achieve this, depending on the context and requirements.
-
-
-Method 1a: Declare the I2C devices by bus number
-------------------------------------------------
-
-This method is appropriate when the I2C bus is a system bus as is the case
-for many embedded systems. On such systems, each I2C bus has a number
-which is known in advance. It is thus possible to pre-declare the I2C
-devices which live on this bus. This is done with an array of struct
-i2c_board_info which is registered by calling i2c_register_board_info().
-
-Example (from omap2 h4):
-
-static struct i2c_board_info h4_i2c_board_info[] __initdata = {
- {
- I2C_BOARD_INFO("isp1301_omap", 0x2d),
- .irq = OMAP_GPIO_IRQ(125),
- },
- { /* EEPROM on mainboard */
- I2C_BOARD_INFO("24c01", 0x52),
- .platform_data = &m24c01,
- },
- { /* EEPROM on cpu card */
- I2C_BOARD_INFO("24c01", 0x57),
- .platform_data = &m24c01,
- },
-};
-
-static void __init omap_h4_init(void)
-{
- (...)
- i2c_register_board_info(1, h4_i2c_board_info,
- ARRAY_SIZE(h4_i2c_board_info));
- (...)
-}
-
-The above code declares 3 devices on I2C bus 1, including their respective
-addresses and custom data needed by their drivers. When the I2C bus in
-question is registered, the I2C devices will be instantiated automatically
-by i2c-core.
-
-The devices will be automatically unbound and destroyed when the I2C bus
-they sit on goes away (if ever.)
-
-
-Method 1b: Declare the I2C devices via devicetree
--------------------------------------------------
-
-This method has the same implications as method 1a. The declaration of I2C
-devices is here done via devicetree as subnodes of the master controller.
-
-Example:
-
- i2c1: i2c@400a0000 {
- /* ... master properties skipped ... */
- clock-frequency = <100000>;
-
- flash@50 {
- compatible = "atmel,24c256";
- reg = <0x50>;
- };
-
- pca9532: gpio@60 {
- compatible = "nxp,pca9532";
- gpio-controller;
- #gpio-cells = <2>;
- reg = <0x60>;
- };
- };
-
-Here, two devices are attached to the bus using a speed of 100kHz. For
-additional properties which might be needed to set up the device, please refer
-to its devicetree documentation in Documentation/devicetree/bindings/.
-
-
-Method 1c: Declare the I2C devices via ACPI
--------------------------------------------
-
-ACPI can also describe I2C devices. There is special documentation for this
-which is currently located at Documentation/firmware-guide/acpi/enumeration.rst.
-
-
-Method 2: Instantiate the devices explicitly
---------------------------------------------
-
-This method is appropriate when a larger device uses an I2C bus for
-internal communication. A typical case is TV adapters. These can have a
-tuner, a video decoder, an audio decoder, etc. usually connected to the
-main chip by the means of an I2C bus. You won't know the number of the I2C
-bus in advance, so the method 1 described above can't be used. Instead,
-you can instantiate your I2C devices explicitly. This is done by filling
-a struct i2c_board_info and calling i2c_new_device().
-
-Example (from the sfe4001 network driver):
-
-static struct i2c_board_info sfe4001_hwmon_info = {
- I2C_BOARD_INFO("max6647", 0x4e),
-};
-
-int sfe4001_init(struct efx_nic *efx)
-{
- (...)
- efx->board_info.hwmon_client =
- i2c_new_device(&efx->i2c_adap, &sfe4001_hwmon_info);
-
- (...)
-}
-
-The above code instantiates 1 I2C device on the I2C bus which is on the
-network adapter in question.
-
-A variant of this is when you don't know for sure if an I2C device is
-present or not (for example for an optional feature which is not present
-on cheap variants of a board but you have no way to tell them apart), or
-it may have different addresses from one board to the next (manufacturer
-changing its design without notice). In this case, you can call
-i2c_new_probed_device() instead of i2c_new_device().
-
-Example (from the nxp OHCI driver):
-
-static const unsigned short normal_i2c[] = { 0x2c, 0x2d, I2C_CLIENT_END };
-
-static int usb_hcd_nxp_probe(struct platform_device *pdev)
-{
- (...)
- struct i2c_adapter *i2c_adap;
- struct i2c_board_info i2c_info;
-
- (...)
- i2c_adap = i2c_get_adapter(2);
- memset(&i2c_info, 0, sizeof(struct i2c_board_info));
- strscpy(i2c_info.type, "isp1301_nxp", sizeof(i2c_info.type));
- isp1301_i2c_client = i2c_new_probed_device(i2c_adap, &i2c_info,
- normal_i2c, NULL);
- i2c_put_adapter(i2c_adap);
- (...)
-}
-
-The above code instantiates up to 1 I2C device on the I2C bus which is on
-the OHCI adapter in question. It first tries at address 0x2c, if nothing
-is found there it tries address 0x2d, and if still nothing is found, it
-simply gives up.
-
-The driver which instantiated the I2C device is responsible for destroying
-it on cleanup. This is done by calling i2c_unregister_device() on the
-pointer that was earlier returned by i2c_new_device() or
-i2c_new_probed_device().
-
-
-Method 3: Probe an I2C bus for certain devices
-----------------------------------------------
-
-Sometimes you do not have enough information about an I2C device, not even
-to call i2c_new_probed_device(). The typical case is hardware monitoring
-chips on PC mainboards. There are several dozen models, which can live
-at 25 different addresses. Given the huge number of mainboards out there,
-it is next to impossible to build an exhaustive list of the hardware
-monitoring chips being used. Fortunately, most of these chips have
-manufacturer and device ID registers, so they can be identified by
-probing.
-
-In that case, I2C devices are neither declared nor instantiated
-explicitly. Instead, i2c-core will probe for such devices as soon as their
-drivers are loaded, and if any is found, an I2C device will be
-instantiated automatically. In order to prevent any misbehavior of this
-mechanism, the following restrictions apply:
-* The I2C device driver must implement the detect() method, which
- identifies a supported device by reading from arbitrary registers.
-* Only buses which are likely to have a supported device and agree to be
- probed, will be probed. For example this avoids probing for hardware
- monitoring chips on a TV adapter.
-
-Example:
-See lm90_driver and lm90_detect() in drivers/hwmon/lm90.c
-
-I2C devices instantiated as a result of such a successful probe will be
-destroyed automatically when the driver which detected them is removed,
-or when the underlying I2C bus is itself destroyed, whichever happens
-first.
-
-Those of you familiar with the i2c subsystem of 2.4 kernels and early 2.6
-kernels will find out that this method 3 is essentially similar to what
-was done there. Two significant differences are:
-* Probing is only one way to instantiate I2C devices now, while it was the
- only way back then. Where possible, methods 1 and 2 should be preferred.
- Method 3 should only be used when there is no other way, as it can have
- undesirable side effects.
-* I2C buses must now explicitly say which I2C driver classes can probe
- them (by the means of the class bitfield), while all I2C buses were
- probed by default back then. The default is an empty class which means
- that no probing happens. The purpose of the class bitfield is to limit
- the aforementioned undesirable side effects.
-
-Once again, method 3 should be avoided wherever possible. Explicit device
-instantiation (methods 1 and 2) is much preferred for it is safer and
-faster.
-
-
-Method 4: Instantiate from user-space
--------------------------------------
-
-In general, the kernel should know which I2C devices are connected and
-what addresses they live at. However, in certain cases, it does not, so a
-sysfs interface was added to let the user provide the information. This
-interface is made of 2 attribute files which are created in every I2C bus
-directory: new_device and delete_device. Both files are write only and you
-must write the right parameters to them in order to properly instantiate,
-respectively delete, an I2C device.
-
-File new_device takes 2 parameters: the name of the I2C device (a string)
-and the address of the I2C device (a number, typically expressed in
-hexadecimal starting with 0x, but can also be expressed in decimal.)
-
-File delete_device takes a single parameter: the address of the I2C
-device. As no two devices can live at the same address on a given I2C
-segment, the address is sufficient to uniquely identify the device to be
-deleted.
-
-Example:
-# echo eeprom 0x50 > /sys/bus/i2c/devices/i2c-3/new_device
-
-While this interface should only be used when in-kernel device declaration
-can't be done, there is a variety of cases where it can be helpful:
-* The I2C driver usually detects devices (method 3 above) but the bus
- segment your device lives on doesn't have the proper class bit set and
- thus detection doesn't trigger.
-* The I2C driver usually detects devices, but your device lives at an
- unexpected address.
-* The I2C driver usually detects devices, but your device is not detected,
- either because the detection routine is too strict, or because your
- device is not officially supported yet but you know it is compatible.
-* You are developing a driver on a test board, where you soldered the I2C
- device yourself.
-
-This interface is a replacement for the force_* module parameters some I2C
-drivers implement. Being implemented in i2c-core rather than in each
-device driver individually, it is much more efficient, and also has the
-advantage that you do not have to reload the driver to change a setting.
-You can also instantiate the device before the driver is loaded or even
-available, and you don't need to know what driver the device needs.
diff --git a/Documentation/i2c/instantiating-devices.rst b/Documentation/i2c/instantiating-devices.rst
new file mode 100644
index 0000000..1238f1f
--- /dev/null
+++ b/Documentation/i2c/instantiating-devices.rst
@@ -0,0 +1,253 @@
+==============================
+How to instantiate I2C devices
+==============================
+
+Unlike PCI or USB devices, I2C devices are not enumerated at the hardware
+level. Instead, the software must know which devices are connected on each
+I2C bus segment, and what address these devices are using. For this
+reason, the kernel code must instantiate I2C devices explicitly. There are
+several ways to achieve this, depending on the context and requirements.
+
+
+Method 1a: Declare the I2C devices by bus number
+------------------------------------------------
+
+This method is appropriate when the I2C bus is a system bus as is the case
+for many embedded systems. On such systems, each I2C bus has a number
+which is known in advance. It is thus possible to pre-declare the I2C
+devices which live on this bus. This is done with an array of struct
+i2c_board_info which is registered by calling i2c_register_board_info().
+
+Example (from omap2 h4)::
+
+ static struct i2c_board_info h4_i2c_board_info[] __initdata = {
+ {
+ I2C_BOARD_INFO("isp1301_omap", 0x2d),
+ .irq = OMAP_GPIO_IRQ(125),
+ },
+ { /* EEPROM on mainboard */
+ I2C_BOARD_INFO("24c01", 0x52),
+ .platform_data = &m24c01,
+ },
+ { /* EEPROM on cpu card */
+ I2C_BOARD_INFO("24c01", 0x57),
+ .platform_data = &m24c01,
+ },
+ };
+
+ static void __init omap_h4_init(void)
+ {
+ (...)
+ i2c_register_board_info(1, h4_i2c_board_info,
+ ARRAY_SIZE(h4_i2c_board_info));
+ (...)
+ }
+
+The above code declares 3 devices on I2C bus 1, including their respective
+addresses and custom data needed by their drivers. When the I2C bus in
+question is registered, the I2C devices will be instantiated automatically
+by i2c-core.
+
+The devices will be automatically unbound and destroyed when the I2C bus
+they sit on goes away (if ever.)
+
+
+Method 1b: Declare the I2C devices via devicetree
+-------------------------------------------------
+
+This method has the same implications as method 1a. The declaration of I2C
+devices is here done via devicetree as subnodes of the master controller.
+
+Example::
+
+ i2c1: i2c@400a0000 {
+ /* ... master properties skipped ... */
+ clock-frequency = <100000>;
+
+ flash@50 {
+ compatible = "atmel,24c256";
+ reg = <0x50>;
+ };
+
+ pca9532: gpio@60 {
+ compatible = "nxp,pca9532";
+ gpio-controller;
+ #gpio-cells = <2>;
+ reg = <0x60>;
+ };
+ };
+
+Here, two devices are attached to the bus using a speed of 100kHz. For
+additional properties which might be needed to set up the device, please refer
+to its devicetree documentation in Documentation/devicetree/bindings/.
+
+
+Method 1c: Declare the I2C devices via ACPI
+-------------------------------------------
+
+ACPI can also describe I2C devices. There is special documentation for this
+which is currently located at Documentation/firmware-guide/acpi/enumeration.rst.
+
+
+Method 2: Instantiate the devices explicitly
+--------------------------------------------
+
+This method is appropriate when a larger device uses an I2C bus for
+internal communication. A typical case is TV adapters. These can have a
+tuner, a video decoder, an audio decoder, etc. usually connected to the
+main chip by the means of an I2C bus. You won't know the number of the I2C
+bus in advance, so the method 1 described above can't be used. Instead,
+you can instantiate your I2C devices explicitly. This is done by filling
+a struct i2c_board_info and calling i2c_new_device().
+
+Example (from the sfe4001 network driver)::
+
+ static struct i2c_board_info sfe4001_hwmon_info = {
+ I2C_BOARD_INFO("max6647", 0x4e),
+ };
+
+ int sfe4001_init(struct efx_nic *efx)
+ {
+ (...)
+ efx->board_info.hwmon_client =
+ i2c_new_device(&efx->i2c_adap, &sfe4001_hwmon_info);
+
+ (...)
+ }
+
+The above code instantiates 1 I2C device on the I2C bus which is on the
+network adapter in question.
+
+A variant of this is when you don't know for sure if an I2C device is
+present or not (for example for an optional feature which is not present
+on cheap variants of a board but you have no way to tell them apart), or
+it may have different addresses from one board to the next (manufacturer
+changing its design without notice). In this case, you can call
+i2c_new_probed_device() instead of i2c_new_device().
+
+Example (from the nxp OHCI driver)::
+
+ static const unsigned short normal_i2c[] = { 0x2c, 0x2d, I2C_CLIENT_END };
+
+ static int usb_hcd_nxp_probe(struct platform_device *pdev)
+ {
+ (...)
+ struct i2c_adapter *i2c_adap;
+ struct i2c_board_info i2c_info;
+
+ (...)
+ i2c_adap = i2c_get_adapter(2);
+ memset(&i2c_info, 0, sizeof(struct i2c_board_info));
+ strscpy(i2c_info.type, "isp1301_nxp", sizeof(i2c_info.type));
+ isp1301_i2c_client = i2c_new_probed_device(i2c_adap, &i2c_info,
+ normal_i2c, NULL);
+ i2c_put_adapter(i2c_adap);
+ (...)
+ }
+
+The above code instantiates up to 1 I2C device on the I2C bus which is on
+the OHCI adapter in question. It first tries at address 0x2c, if nothing
+is found there it tries address 0x2d, and if still nothing is found, it
+simply gives up.
+
+The driver which instantiated the I2C device is responsible for destroying
+it on cleanup. This is done by calling i2c_unregister_device() on the
+pointer that was earlier returned by i2c_new_device() or
+i2c_new_probed_device().
+
+
+Method 3: Probe an I2C bus for certain devices
+----------------------------------------------
+
+Sometimes you do not have enough information about an I2C device, not even
+to call i2c_new_probed_device(). The typical case is hardware monitoring
+chips on PC mainboards. There are several dozen models, which can live
+at 25 different addresses. Given the huge number of mainboards out there,
+it is next to impossible to build an exhaustive list of the hardware
+monitoring chips being used. Fortunately, most of these chips have
+manufacturer and device ID registers, so they can be identified by
+probing.
+
+In that case, I2C devices are neither declared nor instantiated
+explicitly. Instead, i2c-core will probe for such devices as soon as their
+drivers are loaded, and if any is found, an I2C device will be
+instantiated automatically. In order to prevent any misbehavior of this
+mechanism, the following restrictions apply:
+
+* The I2C device driver must implement the detect() method, which
+ identifies a supported device by reading from arbitrary registers.
+* Only buses which are likely to have a supported device and agree to be
+ probed, will be probed. For example this avoids probing for hardware
+ monitoring chips on a TV adapter.
+
+Example:
+See lm90_driver and lm90_detect() in drivers/hwmon/lm90.c
+
+I2C devices instantiated as a result of such a successful probe will be
+destroyed automatically when the driver which detected them is removed,
+or when the underlying I2C bus is itself destroyed, whichever happens
+first.
+
+Those of you familiar with the i2c subsystem of 2.4 kernels and early 2.6
+kernels will find out that this method 3 is essentially similar to what
+was done there. Two significant differences are:
+
+* Probing is only one way to instantiate I2C devices now, while it was the
+ only way back then. Where possible, methods 1 and 2 should be preferred.
+ Method 3 should only be used when there is no other way, as it can have
+ undesirable side effects.
+* I2C buses must now explicitly say which I2C driver classes can probe
+ them (by the means of the class bitfield), while all I2C buses were
+ probed by default back then. The default is an empty class which means
+ that no probing happens. The purpose of the class bitfield is to limit
+ the aforementioned undesirable side effects.
+
+Once again, method 3 should be avoided wherever possible. Explicit device
+instantiation (methods 1 and 2) is much preferred for it is safer and
+faster.
+
+
+Method 4: Instantiate from user-space
+-------------------------------------
+
+In general, the kernel should know which I2C devices are connected and
+what addresses they live at. However, in certain cases, it does not, so a
+sysfs interface was added to let the user provide the information. This
+interface is made of 2 attribute files which are created in every I2C bus
+directory: new_device and delete_device. Both files are write only and you
+must write the right parameters to them in order to properly instantiate,
+respectively delete, an I2C device.
+
+File new_device takes 2 parameters: the name of the I2C device (a string)
+and the address of the I2C device (a number, typically expressed in
+hexadecimal starting with 0x, but can also be expressed in decimal.)
+
+File delete_device takes a single parameter: the address of the I2C
+device. As no two devices can live at the same address on a given I2C
+segment, the address is sufficient to uniquely identify the device to be
+deleted.
+
+Example::
+
+ # echo eeprom 0x50 > /sys/bus/i2c/devices/i2c-3/new_device
+
+While this interface should only be used when in-kernel device declaration
+can't be done, there is a variety of cases where it can be helpful:
+
+* The I2C driver usually detects devices (method 3 above) but the bus
+ segment your device lives on doesn't have the proper class bit set and
+ thus detection doesn't trigger.
+* The I2C driver usually detects devices, but your device lives at an
+ unexpected address.
+* The I2C driver usually detects devices, but your device is not detected,
+ either because the detection routine is too strict, or because your
+ device is not officially supported yet but you know it is compatible.
+* You are developing a driver on a test board, where you soldered the I2C
+ device yourself.
+
+This interface is a replacement for the force_* module parameters some I2C
+drivers implement. Being implemented in i2c-core rather than in each
+device driver individually, it is much more efficient, and also has the
+advantage that you do not have to reload the driver to change a setting.
+You can also instantiate the device before the driver is loaded or even
+available, and you don't need to know what driver the device needs.
diff --git a/Documentation/i2c/muxes/i2c-mux-gpio b/Documentation/i2c/muxes/i2c-mux-gpio
deleted file mode 100644
index 893ecdf..0000000
--- a/Documentation/i2c/muxes/i2c-mux-gpio
+++ /dev/null
@@ -1,83 +0,0 @@
-Kernel driver i2c-mux-gpio
-
-Author: Peter Korsgaard <peter.korsgaard@barco.com>
-
-Description
------------
-
-i2c-mux-gpio is an i2c mux driver providing access to I2C bus segments
-from a master I2C bus and a hardware MUX controlled through GPIO pins.
-
-E.G.:
-
- ---------- ---------- Bus segment 1 - - - - -
- | | SCL/SDA | |-------------- | |
- | |------------| |
- | | | | Bus segment 2 | |
- | Linux | GPIO 1..N | MUX |--------------- Devices
- | |------------| | | |
- | | | | Bus segment M
- | | | |---------------| |
- ---------- ---------- - - - - -
-
-SCL/SDA of the master I2C bus is multiplexed to bus segment 1..M
-according to the settings of the GPIO pins 1..N.
-
-Usage
------
-
-i2c-mux-gpio uses the platform bus, so you need to provide a struct
-platform_device with the platform_data pointing to a struct
-i2c_mux_gpio_platform_data with the I2C adapter number of the master
-bus, the number of bus segments to create and the GPIO pins used
-to control it. See include/linux/platform_data/i2c-mux-gpio.h for details.
-
-E.G. something like this for a MUX providing 4 bus segments
-controlled through 3 GPIO pins:
-
-#include <linux/platform_data/i2c-mux-gpio.h>
-#include <linux/platform_device.h>
-
-static const unsigned myboard_gpiomux_gpios[] = {
- AT91_PIN_PC26, AT91_PIN_PC25, AT91_PIN_PC24
-};
-
-static const unsigned myboard_gpiomux_values[] = {
- 0, 1, 2, 3
-};
-
-static struct i2c_mux_gpio_platform_data myboard_i2cmux_data = {
- .parent = 1,
- .base_nr = 2, /* optional */
- .values = myboard_gpiomux_values,
- .n_values = ARRAY_SIZE(myboard_gpiomux_values),
- .gpios = myboard_gpiomux_gpios,
- .n_gpios = ARRAY_SIZE(myboard_gpiomux_gpios),
- .idle = 4, /* optional */
-};
-
-static struct platform_device myboard_i2cmux = {
- .name = "i2c-mux-gpio",
- .id = 0,
- .dev = {
- .platform_data = &myboard_i2cmux_data,
- },
-};
-
-If you don't know the absolute GPIO pin numbers at registration time,
-you can instead provide a chip name (.chip_name) and relative GPIO pin
-numbers, and the i2c-mux-gpio driver will do the work for you,
-including deferred probing if the GPIO chip isn't immediately
-available.
-
-Device Registration
--------------------
-
-When registering your i2c-mux-gpio device, you should pass the number
-of any GPIO pin it uses as the device ID. This guarantees that every
-instance has a different ID.
-
-Alternatively, if you don't need a stable device name, you can simply
-pass PLATFORM_DEVID_AUTO as the device ID, and the platform core will
-assign a dynamic ID to your device. If you do not know the absolute
-GPIO pin numbers at registration time, this is even the only option.
diff --git a/Documentation/i2c/muxes/i2c-mux-gpio.rst b/Documentation/i2c/muxes/i2c-mux-gpio.rst
new file mode 100644
index 0000000..7d27444
--- /dev/null
+++ b/Documentation/i2c/muxes/i2c-mux-gpio.rst
@@ -0,0 +1,85 @@
+==========================
+Kernel driver i2c-mux-gpio
+==========================
+
+Author: Peter Korsgaard <peter.korsgaard@barco.com>
+
+Description
+-----------
+
+i2c-mux-gpio is an i2c mux driver providing access to I2C bus segments
+from a master I2C bus and a hardware MUX controlled through GPIO pins.
+
+E.G.::
+
+ ---------- ---------- Bus segment 1 - - - - -
+ | | SCL/SDA | |-------------- | |
+ | |------------| |
+ | | | | Bus segment 2 | |
+ | Linux | GPIO 1..N | MUX |--------------- Devices
+ | |------------| | | |
+ | | | | Bus segment M
+ | | | |---------------| |
+ ---------- ---------- - - - - -
+
+SCL/SDA of the master I2C bus is multiplexed to bus segment 1..M
+according to the settings of the GPIO pins 1..N.
+
+Usage
+-----
+
+i2c-mux-gpio uses the platform bus, so you need to provide a struct
+platform_device with the platform_data pointing to a struct
+i2c_mux_gpio_platform_data with the I2C adapter number of the master
+bus, the number of bus segments to create and the GPIO pins used
+to control it. See include/linux/platform_data/i2c-mux-gpio.h for details.
+
+E.G. something like this for a MUX providing 4 bus segments
+controlled through 3 GPIO pins::
+
+ #include <linux/platform_data/i2c-mux-gpio.h>
+ #include <linux/platform_device.h>
+
+ static const unsigned myboard_gpiomux_gpios[] = {
+ AT91_PIN_PC26, AT91_PIN_PC25, AT91_PIN_PC24
+ };
+
+ static const unsigned myboard_gpiomux_values[] = {
+ 0, 1, 2, 3
+ };
+
+ static struct i2c_mux_gpio_platform_data myboard_i2cmux_data = {
+ .parent = 1,
+ .base_nr = 2, /* optional */
+ .values = myboard_gpiomux_values,
+ .n_values = ARRAY_SIZE(myboard_gpiomux_values),
+ .gpios = myboard_gpiomux_gpios,
+ .n_gpios = ARRAY_SIZE(myboard_gpiomux_gpios),
+ .idle = 4, /* optional */
+ };
+
+ static struct platform_device myboard_i2cmux = {
+ .name = "i2c-mux-gpio",
+ .id = 0,
+ .dev = {
+ .platform_data = &myboard_i2cmux_data,
+ },
+ };
+
+If you don't know the absolute GPIO pin numbers at registration time,
+you can instead provide a chip name (.chip_name) and relative GPIO pin
+numbers, and the i2c-mux-gpio driver will do the work for you,
+including deferred probing if the GPIO chip isn't immediately
+available.
+
+Device Registration
+-------------------
+
+When registering your i2c-mux-gpio device, you should pass the number
+of any GPIO pin it uses as the device ID. This guarantees that every
+instance has a different ID.
+
+Alternatively, if you don't need a stable device name, you can simply
+pass PLATFORM_DEVID_AUTO as the device ID, and the platform core will
+assign a dynamic ID to your device. If you do not know the absolute
+GPIO pin numbers at registration time, this is even the only option.
diff --git a/Documentation/i2c/old-module-parameters b/Documentation/i2c/old-module-parameters
deleted file mode 100644
index 8e2b629..0000000
--- a/Documentation/i2c/old-module-parameters
+++ /dev/null
@@ -1,44 +0,0 @@
-I2C device driver binding control from user-space
-=================================================
-
-Up to kernel 2.6.32, many i2c drivers used helper macros provided by
-<linux/i2c.h> which created standard module parameters to let the user
-control how the driver would probe i2c buses and attach to devices. These
-parameters were known as "probe" (to let the driver probe for an extra
-address), "force" (to forcibly attach the driver to a given device) and
-"ignore" (to prevent a driver from probing a given address).
-
-With the conversion of the i2c subsystem to the standard device driver
-binding model, it became clear that these per-module parameters were no
-longer needed, and that a centralized implementation was possible. The new,
-sysfs-based interface is described in the documentation file
-"instantiating-devices", section "Method 4: Instantiate from user-space".
-
-Below is a mapping from the old module parameters to the new interface.
-
-Attaching a driver to an I2C device
------------------------------------
-
-Old method (module parameters):
-# modprobe <driver> probe=1,0x2d
-# modprobe <driver> force=1,0x2d
-# modprobe <driver> force_<device>=1,0x2d
-
-New method (sysfs interface):
-# echo <device> 0x2d > /sys/bus/i2c/devices/i2c-1/new_device
-
-Preventing a driver from attaching to an I2C device
----------------------------------------------------
-
-Old method (module parameters):
-# modprobe <driver> ignore=1,0x2f
-
-New method (sysfs interface):
-# echo dummy 0x2f > /sys/bus/i2c/devices/i2c-1/new_device
-# modprobe <driver>
-
-Of course, it is important to instantiate the "dummy" device before loading
-the driver. The dummy device will be handled by i2c-core itself, preventing
-other drivers from binding to it later on. If there is a real device at the
-problematic address, and you want another driver to bind to it, then simply
-pass the name of the device in question instead of "dummy".
diff --git a/Documentation/i2c/old-module-parameters.rst b/Documentation/i2c/old-module-parameters.rst
new file mode 100644
index 0000000..a193951
--- /dev/null
+++ b/Documentation/i2c/old-module-parameters.rst
@@ -0,0 +1,49 @@
+=================================================
+I2C device driver binding control from user-space
+=================================================
+
+Up to kernel 2.6.32, many i2c drivers used helper macros provided by
+<linux/i2c.h> which created standard module parameters to let the user
+control how the driver would probe i2c buses and attach to devices. These
+parameters were known as "probe" (to let the driver probe for an extra
+address), "force" (to forcibly attach the driver to a given device) and
+"ignore" (to prevent a driver from probing a given address).
+
+With the conversion of the i2c subsystem to the standard device driver
+binding model, it became clear that these per-module parameters were no
+longer needed, and that a centralized implementation was possible. The new,
+sysfs-based interface is described in the documentation file
+"instantiating-devices", section "Method 4: Instantiate from user-space".
+
+Below is a mapping from the old module parameters to the new interface.
+
+Attaching a driver to an I2C device
+-----------------------------------
+
+Old method (module parameters)::
+
+ # modprobe <driver> probe=1,0x2d
+ # modprobe <driver> force=1,0x2d
+ # modprobe <driver> force_<device>=1,0x2d
+
+New method (sysfs interface)::
+
+ # echo <device> 0x2d > /sys/bus/i2c/devices/i2c-1/new_device
+
+Preventing a driver from attaching to an I2C device
+---------------------------------------------------
+
+Old method (module parameters)::
+
+ # modprobe <driver> ignore=1,0x2f
+
+New method (sysfs interface)::
+
+ # echo dummy 0x2f > /sys/bus/i2c/devices/i2c-1/new_device
+ # modprobe <driver>
+
+Of course, it is important to instantiate the "dummy" device before loading
+the driver. The dummy device will be handled by i2c-core itself, preventing
+other drivers from binding to it later on. If there is a real device at the
+problematic address, and you want another driver to bind to it, then simply
+pass the name of the device in question instead of "dummy".
diff --git a/Documentation/i2c/slave-eeprom-backend b/Documentation/i2c/slave-eeprom-backend
deleted file mode 100644
index 04f8d8a..0000000
--- a/Documentation/i2c/slave-eeprom-backend
+++ /dev/null
@@ -1,14 +0,0 @@
-Linux I2C slave eeprom backend
-==============================
-
-by Wolfram Sang <wsa@sang-engineering.com> in 2014-15
-
-This is a proof-of-concept backend which acts like an EEPROM on the connected
-I2C bus. The memory contents can be modified from userspace via this file
-located in sysfs:
-
- /sys/bus/i2c/devices/<device-directory>/slave-eeprom
-
-As of 2015, Linux doesn't support poll on binary sysfs files, so there is no
-notification when another master changed the content.
-
diff --git a/Documentation/i2c/slave-eeprom-backend.rst b/Documentation/i2c/slave-eeprom-backend.rst
new file mode 100644
index 0000000..0b8cd83
--- /dev/null
+++ b/Documentation/i2c/slave-eeprom-backend.rst
@@ -0,0 +1,14 @@
+==============================
+Linux I2C slave eeprom backend
+==============================
+
+by Wolfram Sang <wsa@sang-engineering.com> in 2014-15
+
+This is a proof-of-concept backend which acts like an EEPROM on the connected
+I2C bus. The memory contents can be modified from userspace via this file
+located in sysfs::
+
+ /sys/bus/i2c/devices/<device-directory>/slave-eeprom
+
+As of 2015, Linux doesn't support poll on binary sysfs files, so there is no
+notification when another master changed the content.
diff --git a/Documentation/i2c/slave-interface b/Documentation/i2c/slave-interface
deleted file mode 100644
index 7e2a228..0000000
--- a/Documentation/i2c/slave-interface
+++ /dev/null
@@ -1,193 +0,0 @@
-Linux I2C slave interface description
-=====================================
-
-by Wolfram Sang <wsa@sang-engineering.com> in 2014-15
-
-Linux can also be an I2C slave if the I2C controller in use has slave
-functionality. For that to work, one needs slave support in the bus driver plus
-a hardware independent software backend providing the actual functionality. An
-example for the latter is the slave-eeprom driver, which acts as a dual memory
-driver. While another I2C master on the bus can access it like a regular
-EEPROM, the Linux I2C slave can access the content via sysfs and handle data as
-needed. The backend driver and the I2C bus driver communicate via events. Here
-is a small graph visualizing the data flow and the means by which data is
-transported. The dotted line marks only one example. The backend could also
-use a character device, be in-kernel only, or something completely different:
-
-
- e.g. sysfs I2C slave events I/O registers
- +-----------+ v +---------+ v +--------+ v +------------+
- | Userspace +........+ Backend +-----------+ Driver +-----+ Controller |
- +-----------+ +---------+ +--------+ +------------+
- | |
- ----------------------------------------------------------------+-- I2C
- --------------------------------------------------------------+---- Bus
-
-Note: Technically, there is also the I2C core between the backend and the
-driver. However, at this time of writing, the layer is transparent.
-
-
-User manual
-===========
-
-I2C slave backends behave like standard I2C clients. So, you can instantiate
-them as described in the document 'instantiating-devices'. The only difference
-is that i2c slave backends have their own address space. So, you have to add
-0x1000 to the address you would originally request. An example for
-instantiating the slave-eeprom driver from userspace at the 7 bit address 0x64
-on bus 1:
-
- # echo slave-24c02 0x1064 > /sys/bus/i2c/devices/i2c-1/new_device
-
-Each backend should come with separate documentation to describe its specific
-behaviour and setup.
-
-
-Developer manual
-================
-
-First, the events which are used by the bus driver and the backend will be
-described in detail. After that, some implementation hints for extending bus
-drivers and writing backends will be given.
-
-
-I2C slave events
-----------------
-
-The bus driver sends an event to the backend using the following function:
-
- ret = i2c_slave_event(client, event, &val)
-
-'client' describes the i2c slave device. 'event' is one of the special event
-types described hereafter. 'val' holds an u8 value for the data byte to be
-read/written and is thus bidirectional. The pointer to val must always be
-provided even if val is not used for an event, i.e. don't use NULL here. 'ret'
-is the return value from the backend. Mandatory events must be provided by the
-bus drivers and must be checked for by backend drivers.
-
-Event types:
-
-* I2C_SLAVE_WRITE_REQUESTED (mandatory)
-
-'val': unused
-'ret': always 0
-
-Another I2C master wants to write data to us. This event should be sent once
-our own address and the write bit was detected. The data did not arrive yet, so
-there is nothing to process or return. Wakeup or initialization probably needs
-to be done, though.
-
-* I2C_SLAVE_READ_REQUESTED (mandatory)
-
-'val': backend returns first byte to be sent
-'ret': always 0
-
-Another I2C master wants to read data from us. This event should be sent once
-our own address and the read bit was detected. After returning, the bus driver
-should transmit the first byte.
-
-* I2C_SLAVE_WRITE_RECEIVED (mandatory)
-
-'val': bus driver delivers received byte
-'ret': 0 if the byte should be acked, some errno if the byte should be nacked
-
-Another I2C master has sent a byte to us which needs to be set in 'val'. If 'ret'
-is zero, the bus driver should ack this byte. If 'ret' is an errno, then the byte
-should be nacked.
-
-* I2C_SLAVE_READ_PROCESSED (mandatory)
-
-'val': backend returns next byte to be sent
-'ret': always 0
-
-The bus driver requests the next byte to be sent to another I2C master in
-'val'. Important: This does not mean that the previous byte has been acked, it
-only means that the previous byte is shifted out to the bus! To ensure seamless
-transmission, most hardware requests the next byte when the previous one is
-still shifted out. If the master sends NACK and stops reading after the byte
-currently shifted out, this byte requested here is never used. It very likely
-needs to be sent again on the next I2C_SLAVE_READ_REQUEST, depending a bit on
-your backend, though.
-
-* I2C_SLAVE_STOP (mandatory)
-
-'val': unused
-'ret': always 0
-
-A stop condition was received. This can happen anytime and the backend should
-reset its state machine for I2C transfers to be able to receive new requests.
-
-
-Software backends
------------------
-
-If you want to write a software backend:
-
-* use a standard i2c_driver and its matching mechanisms
-* write the slave_callback which handles the above slave events
- (best using a state machine)
-* register this callback via i2c_slave_register()
-
-Check the i2c-slave-eeprom driver as an example.
-
-
-Bus driver support
-------------------
-
-If you want to add slave support to the bus driver:
-
-* implement calls to register/unregister the slave and add those to the
- struct i2c_algorithm. When registering, you probably need to set the i2c
- slave address and enable slave specific interrupts. If you use runtime pm, you
- should use pm_runtime_get_sync() because your device usually needs to be
- powered on always to be able to detect its slave address. When unregistering,
- do the inverse of the above.
-
-* Catch the slave interrupts and send appropriate i2c_slave_events to the backend.
-
-Note that most hardware supports being master _and_ slave on the same bus. So,
-if you extend a bus driver, please make sure that the driver supports that as
-well. In almost all cases, slave support does not need to disable the master
-functionality.
-
-Check the i2c-rcar driver as an example.
-
-
-About ACK/NACK
---------------
-
-It is good behaviour to always ACK the address phase, so the master knows if a
-device is basically present or if it mysteriously disappeared. Using NACK to
-state being busy is troublesome. SMBus demands to always ACK the address phase,
-while the I2C specification is more loose on that. Most I2C controllers also
-automatically ACK when detecting their slave addresses, so there is no option
-to NACK them. For those reasons, this API does not support NACK in the address
-phase.
-
-Currently, there is no slave event to report if the master did ACK or NACK a
-byte when it reads from us. We could make this an optional event if the need
-arises. However, cases should be extremely rare because the master is expected
-to send STOP after that and we have an event for that. Also, keep in mind not
-all I2C controllers have the possibility to report that event.
-
-
-About buffers
--------------
-
-During development of this API, the question of using buffers instead of just
-bytes came up. Such an extension might be possible, usefulness is unclear at
-this time of writing. Some points to keep in mind when using buffers:
-
-* Buffers should be opt-in and backend drivers will always have to support
- byte-based transactions as the ultimate fallback anyhow because this is how
- the majority of HW works.
-
-* For backends simulating hardware registers, buffers are largely not helpful
- because after each byte written an action should be immediately triggered.
- For reads, the data kept in the buffer might get stale if the backend just
- updated a register because of internal processing.
-
-* A master can send STOP at any time. For partially transferred buffers, this
- means additional code to handle this exception. Such code tends to be
- error-prone.
-
diff --git a/Documentation/i2c/slave-interface.rst b/Documentation/i2c/slave-interface.rst
new file mode 100644
index 0000000..c769bd6
--- /dev/null
+++ b/Documentation/i2c/slave-interface.rst
@@ -0,0 +1,198 @@
+=====================================
+Linux I2C slave interface description
+=====================================
+
+by Wolfram Sang <wsa@sang-engineering.com> in 2014-15
+
+Linux can also be an I2C slave if the I2C controller in use has slave
+functionality. For that to work, one needs slave support in the bus driver plus
+a hardware independent software backend providing the actual functionality. An
+example for the latter is the slave-eeprom driver, which acts as a dual memory
+driver. While another I2C master on the bus can access it like a regular
+EEPROM, the Linux I2C slave can access the content via sysfs and handle data as
+needed. The backend driver and the I2C bus driver communicate via events. Here
+is a small graph visualizing the data flow and the means by which data is
+transported. The dotted line marks only one example. The backend could also
+use a character device, be in-kernel only, or something completely different::
+
+
+ e.g. sysfs I2C slave events I/O registers
+ +-----------+ v +---------+ v +--------+ v +------------+
+ | Userspace +........+ Backend +-----------+ Driver +-----+ Controller |
+ +-----------+ +---------+ +--------+ +------------+
+ | |
+ ----------------------------------------------------------------+-- I2C
+ --------------------------------------------------------------+---- Bus
+
+Note: Technically, there is also the I2C core between the backend and the
+driver. However, at this time of writing, the layer is transparent.
+
+
+User manual
+===========
+
+I2C slave backends behave like standard I2C clients. So, you can instantiate
+them as described in the document 'instantiating-devices'. The only difference
+is that i2c slave backends have their own address space. So, you have to add
+0x1000 to the address you would originally request. An example for
+instantiating the slave-eeprom driver from userspace at the 7 bit address 0x64
+on bus 1::
+
+ # echo slave-24c02 0x1064 > /sys/bus/i2c/devices/i2c-1/new_device
+
+Each backend should come with separate documentation to describe its specific
+behaviour and setup.
+
+
+Developer manual
+================
+
+First, the events which are used by the bus driver and the backend will be
+described in detail. After that, some implementation hints for extending bus
+drivers and writing backends will be given.
+
+
+I2C slave events
+----------------
+
+The bus driver sends an event to the backend using the following function::
+
+ ret = i2c_slave_event(client, event, &val)
+
+'client' describes the i2c slave device. 'event' is one of the special event
+types described hereafter. 'val' holds an u8 value for the data byte to be
+read/written and is thus bidirectional. The pointer to val must always be
+provided even if val is not used for an event, i.e. don't use NULL here. 'ret'
+is the return value from the backend. Mandatory events must be provided by the
+bus drivers and must be checked for by backend drivers.
+
+Event types:
+
+* I2C_SLAVE_WRITE_REQUESTED (mandatory)
+
+ 'val': unused
+
+ 'ret': always 0
+
+Another I2C master wants to write data to us. This event should be sent once
+our own address and the write bit was detected. The data did not arrive yet, so
+there is nothing to process or return. Wakeup or initialization probably needs
+to be done, though.
+
+* I2C_SLAVE_READ_REQUESTED (mandatory)
+
+ 'val': backend returns first byte to be sent
+
+ 'ret': always 0
+
+Another I2C master wants to read data from us. This event should be sent once
+our own address and the read bit was detected. After returning, the bus driver
+should transmit the first byte.
+
+* I2C_SLAVE_WRITE_RECEIVED (mandatory)
+
+ 'val': bus driver delivers received byte
+
+ 'ret': 0 if the byte should be acked, some errno if the byte should be nacked
+
+Another I2C master has sent a byte to us which needs to be set in 'val'. If 'ret'
+is zero, the bus driver should ack this byte. If 'ret' is an errno, then the byte
+should be nacked.
+
+* I2C_SLAVE_READ_PROCESSED (mandatory)
+
+ 'val': backend returns next byte to be sent
+
+ 'ret': always 0
+
+The bus driver requests the next byte to be sent to another I2C master in
+'val'. Important: This does not mean that the previous byte has been acked, it
+only means that the previous byte is shifted out to the bus! To ensure seamless
+transmission, most hardware requests the next byte when the previous one is
+still shifted out. If the master sends NACK and stops reading after the byte
+currently shifted out, this byte requested here is never used. It very likely
+needs to be sent again on the next I2C_SLAVE_READ_REQUEST, depending a bit on
+your backend, though.
+
+* I2C_SLAVE_STOP (mandatory)
+
+ 'val': unused
+
+ 'ret': always 0
+
+A stop condition was received. This can happen anytime and the backend should
+reset its state machine for I2C transfers to be able to receive new requests.
+
+
+Software backends
+-----------------
+
+If you want to write a software backend:
+
+* use a standard i2c_driver and its matching mechanisms
+* write the slave_callback which handles the above slave events
+ (best using a state machine)
+* register this callback via i2c_slave_register()
+
+Check the i2c-slave-eeprom driver as an example.
+
+
+Bus driver support
+------------------
+
+If you want to add slave support to the bus driver:
+
+* implement calls to register/unregister the slave and add those to the
+ struct i2c_algorithm. When registering, you probably need to set the i2c
+ slave address and enable slave specific interrupts. If you use runtime pm, you
+ should use pm_runtime_get_sync() because your device usually needs to be
+ powered on always to be able to detect its slave address. When unregistering,
+ do the inverse of the above.
+
+* Catch the slave interrupts and send appropriate i2c_slave_events to the backend.
+
+Note that most hardware supports being master _and_ slave on the same bus. So,
+if you extend a bus driver, please make sure that the driver supports that as
+well. In almost all cases, slave support does not need to disable the master
+functionality.
+
+Check the i2c-rcar driver as an example.
+
+
+About ACK/NACK
+--------------
+
+It is good behaviour to always ACK the address phase, so the master knows if a
+device is basically present or if it mysteriously disappeared. Using NACK to
+state being busy is troublesome. SMBus demands to always ACK the address phase,
+while the I2C specification is more loose on that. Most I2C controllers also
+automatically ACK when detecting their slave addresses, so there is no option
+to NACK them. For those reasons, this API does not support NACK in the address
+phase.
+
+Currently, there is no slave event to report if the master did ACK or NACK a
+byte when it reads from us. We could make this an optional event if the need
+arises. However, cases should be extremely rare because the master is expected
+to send STOP after that and we have an event for that. Also, keep in mind not
+all I2C controllers have the possibility to report that event.
+
+
+About buffers
+-------------
+
+During development of this API, the question of using buffers instead of just
+bytes came up. Such an extension might be possible, usefulness is unclear at
+this time of writing. Some points to keep in mind when using buffers:
+
+* Buffers should be opt-in and backend drivers will always have to support
+ byte-based transactions as the ultimate fallback anyhow because this is how
+ the majority of HW works.
+
+* For backends simulating hardware registers, buffers are largely not helpful
+ because after each byte written an action should be immediately triggered.
+ For reads, the data kept in the buffer might get stale if the backend just
+ updated a register because of internal processing.
+
+* A master can send STOP at any time. For partially transferred buffers, this
+ means additional code to handle this exception. Such code tends to be
+ error-prone.
diff --git a/Documentation/i2c/smbus-protocol b/Documentation/i2c/smbus-protocol
deleted file mode 100644
index 092d474..0000000
--- a/Documentation/i2c/smbus-protocol
+++ /dev/null
@@ -1,283 +0,0 @@
-SMBus Protocol Summary
-======================
-
-The following is a summary of the SMBus protocol. It applies to
-all revisions of the protocol (1.0, 1.1, and 2.0).
-Certain protocol features which are not supported by
-this package are briefly described at the end of this document.
-
-Some adapters understand only the SMBus (System Management Bus) protocol,
-which is a subset from the I2C protocol. Fortunately, many devices use
-only the same subset, which makes it possible to put them on an SMBus.
-
-If you write a driver for some I2C device, please try to use the SMBus
-commands if at all possible (if the device uses only that subset of the
-I2C protocol). This makes it possible to use the device driver on both
-SMBus adapters and I2C adapters (the SMBus command set is automatically
-translated to I2C on I2C adapters, but plain I2C commands can not be
-handled at all on most pure SMBus adapters).
-
-Below is a list of SMBus protocol operations, and the functions executing
-them. Note that the names used in the SMBus protocol specifications usually
-don't match these function names. For some of the operations which pass a
-single data byte, the functions using SMBus protocol operation names execute
-a different protocol operation entirely.
-
-Each transaction type corresponds to a functionality flag. Before calling a
-transaction function, a device driver should always check (just once) for
-the corresponding functionality flag to ensure that the underlying I2C
-adapter supports the transaction in question. See
-<file:Documentation/i2c/functionality> for the details.
-
-
-Key to symbols
-==============
-
-S (1 bit) : Start bit
-P (1 bit) : Stop bit
-Rd/Wr (1 bit) : Read/Write bit. Rd equals 1, Wr equals 0.
-A, NA (1 bit) : Accept and reverse accept bit.
-Addr (7 bits): I2C 7 bit address. Note that this can be expanded as usual to
- get a 10 bit I2C address.
-Comm (8 bits): Command byte, a data byte which often selects a register on
- the device.
-Data (8 bits): A plain data byte. Sometimes, I write DataLow, DataHigh
- for 16 bit data.
-Count (8 bits): A data byte containing the length of a block operation.
-
-[..]: Data sent by I2C device, as opposed to data sent by the host adapter.
-
-
-SMBus Quick Command
-===================
-
-This sends a single bit to the device, at the place of the Rd/Wr bit.
-
-A Addr Rd/Wr [A] P
-
-Functionality flag: I2C_FUNC_SMBUS_QUICK
-
-
-SMBus Receive Byte: i2c_smbus_read_byte()
-==========================================
-
-This reads a single byte from a device, without specifying a device
-register. Some devices are so simple that this interface is enough; for
-others, it is a shorthand if you want to read the same register as in
-the previous SMBus command.
-
-S Addr Rd [A] [Data] NA P
-
-Functionality flag: I2C_FUNC_SMBUS_READ_BYTE
-
-
-SMBus Send Byte: i2c_smbus_write_byte()
-========================================
-
-This operation is the reverse of Receive Byte: it sends a single byte
-to a device. See Receive Byte for more information.
-
-S Addr Wr [A] Data [A] P
-
-Functionality flag: I2C_FUNC_SMBUS_WRITE_BYTE
-
-
-SMBus Read Byte: i2c_smbus_read_byte_data()
-============================================
-
-This reads a single byte from a device, from a designated register.
-The register is specified through the Comm byte.
-
-S Addr Wr [A] Comm [A] S Addr Rd [A] [Data] NA P
-
-Functionality flag: I2C_FUNC_SMBUS_READ_BYTE_DATA
-
-
-SMBus Read Word: i2c_smbus_read_word_data()
-============================================
-
-This operation is very like Read Byte; again, data is read from a
-device, from a designated register that is specified through the Comm
-byte. But this time, the data is a complete word (16 bits).
-
-S Addr Wr [A] Comm [A] S Addr Rd [A] [DataLow] A [DataHigh] NA P
-
-Functionality flag: I2C_FUNC_SMBUS_READ_WORD_DATA
-
-Note the convenience function i2c_smbus_read_word_swapped is
-available for reads where the two data bytes are the other way
-around (not SMBus compliant, but very popular.)
-
-
-SMBus Write Byte: i2c_smbus_write_byte_data()
-==============================================
-
-This writes a single byte to a device, to a designated register. The
-register is specified through the Comm byte. This is the opposite of
-the Read Byte operation.
-
-S Addr Wr [A] Comm [A] Data [A] P
-
-Functionality flag: I2C_FUNC_SMBUS_WRITE_BYTE_DATA
-
-
-SMBus Write Word: i2c_smbus_write_word_data()
-==============================================
-
-This is the opposite of the Read Word operation. 16 bits
-of data is written to a device, to the designated register that is
-specified through the Comm byte.
-
-S Addr Wr [A] Comm [A] DataLow [A] DataHigh [A] P
-
-Functionality flag: I2C_FUNC_SMBUS_WRITE_WORD_DATA
-
-Note the convenience function i2c_smbus_write_word_swapped is
-available for writes where the two data bytes are the other way
-around (not SMBus compliant, but very popular.)
-
-
-SMBus Process Call:
-===================
-
-This command selects a device register (through the Comm byte), sends
-16 bits of data to it, and reads 16 bits of data in return.
-
-S Addr Wr [A] Comm [A] DataLow [A] DataHigh [A]
- S Addr Rd [A] [DataLow] A [DataHigh] NA P
-
-Functionality flag: I2C_FUNC_SMBUS_PROC_CALL
-
-
-SMBus Block Read: i2c_smbus_read_block_data()
-==============================================
-
-This command reads a block of up to 32 bytes from a device, from a
-designated register that is specified through the Comm byte. The amount
-of data is specified by the device in the Count byte.
-
-S Addr Wr [A] Comm [A]
- S Addr Rd [A] [Count] A [Data] A [Data] A ... A [Data] NA P
-
-Functionality flag: I2C_FUNC_SMBUS_READ_BLOCK_DATA
-
-
-SMBus Block Write: i2c_smbus_write_block_data()
-================================================
-
-The opposite of the Block Read command, this writes up to 32 bytes to
-a device, to a designated register that is specified through the
-Comm byte. The amount of data is specified in the Count byte.
-
-S Addr Wr [A] Comm [A] Count [A] Data [A] Data [A] ... [A] Data [A] P
-
-Functionality flag: I2C_FUNC_SMBUS_WRITE_BLOCK_DATA
-
-
-SMBus Block Write - Block Read Process Call
-===========================================
-
-SMBus Block Write - Block Read Process Call was introduced in
-Revision 2.0 of the specification.
-
-This command selects a device register (through the Comm byte), sends
-1 to 31 bytes of data to it, and reads 1 to 31 bytes of data in return.
-
-S Addr Wr [A] Comm [A] Count [A] Data [A] ...
- S Addr Rd [A] [Count] A [Data] ... A P
-
-Functionality flag: I2C_FUNC_SMBUS_BLOCK_PROC_CALL
-
-
-SMBus Host Notify
-=================
-
-This command is sent from a SMBus device acting as a master to the
-SMBus host acting as a slave.
-It is the same form as Write Word, with the command code replaced by the
-alerting device's address.
-
-[S] [HostAddr] [Wr] A [DevAddr] A [DataLow] A [DataHigh] A [P]
-
-This is implemented in the following way in the Linux kernel:
-* I2C bus drivers which support SMBus Host Notify should report
- I2C_FUNC_SMBUS_HOST_NOTIFY.
-* I2C bus drivers trigger SMBus Host Notify by a call to
- i2c_handle_smbus_host_notify().
-* I2C drivers for devices which can trigger SMBus Host Notify will have
- client->irq assigned to a Host Notify IRQ if noone else specified an other.
-
-There is currently no way to retrieve the data parameter from the client.
-
-
-Packet Error Checking (PEC)
-===========================
-
-Packet Error Checking was introduced in Revision 1.1 of the specification.
-
-PEC adds a CRC-8 error-checking byte to transfers using it, immediately
-before the terminating STOP.
-
-
-Address Resolution Protocol (ARP)
-=================================
-
-The Address Resolution Protocol was introduced in Revision 2.0 of
-the specification. It is a higher-layer protocol which uses the
-messages above.
-
-ARP adds device enumeration and dynamic address assignment to
-the protocol. All ARP communications use slave address 0x61 and
-require PEC checksums.
-
-
-SMBus Alert
-===========
-
-SMBus Alert was introduced in Revision 1.0 of the specification.
-
-The SMBus alert protocol allows several SMBus slave devices to share a
-single interrupt pin on the SMBus master, while still allowing the master
-to know which slave triggered the interrupt.
-
-This is implemented the following way in the Linux kernel:
-* I2C bus drivers which support SMBus alert should call
- i2c_setup_smbus_alert() to setup SMBus alert support.
-* I2C drivers for devices which can trigger SMBus alerts should implement
- the optional alert() callback.
-
-
-I2C Block Transactions
-======================
-
-The following I2C block transactions are supported by the
-SMBus layer and are described here for completeness.
-They are *NOT* defined by the SMBus specification.
-
-I2C block transactions do not limit the number of bytes transferred
-but the SMBus layer places a limit of 32 bytes.
-
-
-I2C Block Read: i2c_smbus_read_i2c_block_data()
-================================================
-
-This command reads a block of bytes from a device, from a
-designated register that is specified through the Comm byte.
-
-S Addr Wr [A] Comm [A]
- S Addr Rd [A] [Data] A [Data] A ... A [Data] NA P
-
-Functionality flag: I2C_FUNC_SMBUS_READ_I2C_BLOCK
-
-
-I2C Block Write: i2c_smbus_write_i2c_block_data()
-==================================================
-
-The opposite of the Block Read command, this writes bytes to
-a device, to a designated register that is specified through the
-Comm byte. Note that command lengths of 0, 2, or more bytes are
-supported as they are indistinguishable from data.
-
-S Addr Wr [A] Comm [A] Data [A] Data [A] ... [A] Data [A] P
-
-Functionality flag: I2C_FUNC_SMBUS_WRITE_I2C_BLOCK
diff --git a/Documentation/i2c/smbus-protocol.rst b/Documentation/i2c/smbus-protocol.rst
new file mode 100644
index 0000000..e30eb1d
--- /dev/null
+++ b/Documentation/i2c/smbus-protocol.rst
@@ -0,0 +1,301 @@
+======================
+SMBus Protocol Summary
+======================
+
+The following is a summary of the SMBus protocol. It applies to
+all revisions of the protocol (1.0, 1.1, and 2.0).
+Certain protocol features which are not supported by
+this package are briefly described at the end of this document.
+
+Some adapters understand only the SMBus (System Management Bus) protocol,
+which is a subset from the I2C protocol. Fortunately, many devices use
+only the same subset, which makes it possible to put them on an SMBus.
+
+If you write a driver for some I2C device, please try to use the SMBus
+commands if at all possible (if the device uses only that subset of the
+I2C protocol). This makes it possible to use the device driver on both
+SMBus adapters and I2C adapters (the SMBus command set is automatically
+translated to I2C on I2C adapters, but plain I2C commands can not be
+handled at all on most pure SMBus adapters).
+
+Below is a list of SMBus protocol operations, and the functions executing
+them. Note that the names used in the SMBus protocol specifications usually
+don't match these function names. For some of the operations which pass a
+single data byte, the functions using SMBus protocol operation names execute
+a different protocol operation entirely.
+
+Each transaction type corresponds to a functionality flag. Before calling a
+transaction function, a device driver should always check (just once) for
+the corresponding functionality flag to ensure that the underlying I2C
+adapter supports the transaction in question. See
+<file:Documentation/i2c/functionality.rst> for the details.
+
+
+Key to symbols
+==============
+
+=============== =============================================================
+S (1 bit) : Start bit
+P (1 bit) : Stop bit
+Rd/Wr (1 bit) : Read/Write bit. Rd equals 1, Wr equals 0.
+A, NA (1 bit) : Accept and reverse accept bit.
+Addr (7 bits): I2C 7 bit address. Note that this can be expanded as usual to
+ get a 10 bit I2C address.
+Comm (8 bits): Command byte, a data byte which often selects a register on
+ the device.
+Data (8 bits): A plain data byte. Sometimes, I write DataLow, DataHigh
+ for 16 bit data.
+Count (8 bits): A data byte containing the length of a block operation.
+
+[..]: Data sent by I2C device, as opposed to data sent by the host
+ adapter.
+=============== =============================================================
+
+
+SMBus Quick Command
+===================
+
+This sends a single bit to the device, at the place of the Rd/Wr bit::
+
+ A Addr Rd/Wr [A] P
+
+Functionality flag: I2C_FUNC_SMBUS_QUICK
+
+
+SMBus Receive Byte: i2c_smbus_read_byte()
+==========================================
+
+This reads a single byte from a device, without specifying a device
+register. Some devices are so simple that this interface is enough; for
+others, it is a shorthand if you want to read the same register as in
+the previous SMBus command::
+
+ S Addr Rd [A] [Data] NA P
+
+Functionality flag: I2C_FUNC_SMBUS_READ_BYTE
+
+
+SMBus Send Byte: i2c_smbus_write_byte()
+========================================
+
+This operation is the reverse of Receive Byte: it sends a single byte
+to a device. See Receive Byte for more information.
+
+::
+
+ S Addr Wr [A] Data [A] P
+
+Functionality flag: I2C_FUNC_SMBUS_WRITE_BYTE
+
+
+SMBus Read Byte: i2c_smbus_read_byte_data()
+============================================
+
+This reads a single byte from a device, from a designated register.
+The register is specified through the Comm byte::
+
+ S Addr Wr [A] Comm [A] S Addr Rd [A] [Data] NA P
+
+Functionality flag: I2C_FUNC_SMBUS_READ_BYTE_DATA
+
+
+SMBus Read Word: i2c_smbus_read_word_data()
+============================================
+
+This operation is very like Read Byte; again, data is read from a
+device, from a designated register that is specified through the Comm
+byte. But this time, the data is a complete word (16 bits)::
+
+ S Addr Wr [A] Comm [A] S Addr Rd [A] [DataLow] A [DataHigh] NA P
+
+Functionality flag: I2C_FUNC_SMBUS_READ_WORD_DATA
+
+Note the convenience function i2c_smbus_read_word_swapped is
+available for reads where the two data bytes are the other way
+around (not SMBus compliant, but very popular.)
+
+
+SMBus Write Byte: i2c_smbus_write_byte_data()
+==============================================
+
+This writes a single byte to a device, to a designated register. The
+register is specified through the Comm byte. This is the opposite of
+the Read Byte operation.
+
+::
+
+ S Addr Wr [A] Comm [A] Data [A] P
+
+Functionality flag: I2C_FUNC_SMBUS_WRITE_BYTE_DATA
+
+
+SMBus Write Word: i2c_smbus_write_word_data()
+==============================================
+
+This is the opposite of the Read Word operation. 16 bits
+of data is written to a device, to the designated register that is
+specified through the Comm byte.::
+
+ S Addr Wr [A] Comm [A] DataLow [A] DataHigh [A] P
+
+Functionality flag: I2C_FUNC_SMBUS_WRITE_WORD_DATA
+
+Note the convenience function i2c_smbus_write_word_swapped is
+available for writes where the two data bytes are the other way
+around (not SMBus compliant, but very popular.)
+
+
+SMBus Process Call:
+===================
+
+This command selects a device register (through the Comm byte), sends
+16 bits of data to it, and reads 16 bits of data in return::
+
+ S Addr Wr [A] Comm [A] DataLow [A] DataHigh [A]
+ S Addr Rd [A] [DataLow] A [DataHigh] NA P
+
+Functionality flag: I2C_FUNC_SMBUS_PROC_CALL
+
+
+SMBus Block Read: i2c_smbus_read_block_data()
+==============================================
+
+This command reads a block of up to 32 bytes from a device, from a
+designated register that is specified through the Comm byte. The amount
+of data is specified by the device in the Count byte.
+
+::
+
+ S Addr Wr [A] Comm [A]
+ S Addr Rd [A] [Count] A [Data] A [Data] A ... A [Data] NA P
+
+Functionality flag: I2C_FUNC_SMBUS_READ_BLOCK_DATA
+
+
+SMBus Block Write: i2c_smbus_write_block_data()
+================================================
+
+The opposite of the Block Read command, this writes up to 32 bytes to
+a device, to a designated register that is specified through the
+Comm byte. The amount of data is specified in the Count byte.
+
+::
+
+ S Addr Wr [A] Comm [A] Count [A] Data [A] Data [A] ... [A] Data [A] P
+
+Functionality flag: I2C_FUNC_SMBUS_WRITE_BLOCK_DATA
+
+
+SMBus Block Write - Block Read Process Call
+===========================================
+
+SMBus Block Write - Block Read Process Call was introduced in
+Revision 2.0 of the specification.
+
+This command selects a device register (through the Comm byte), sends
+1 to 31 bytes of data to it, and reads 1 to 31 bytes of data in return::
+
+ S Addr Wr [A] Comm [A] Count [A] Data [A] ...
+ S Addr Rd [A] [Count] A [Data] ... A P
+
+Functionality flag: I2C_FUNC_SMBUS_BLOCK_PROC_CALL
+
+
+SMBus Host Notify
+=================
+
+This command is sent from a SMBus device acting as a master to the
+SMBus host acting as a slave.
+It is the same form as Write Word, with the command code replaced by the
+alerting device's address.
+
+::
+
+ [S] [HostAddr] [Wr] A [DevAddr] A [DataLow] A [DataHigh] A [P]
+
+This is implemented in the following way in the Linux kernel:
+
+* I2C bus drivers which support SMBus Host Notify should report
+ I2C_FUNC_SMBUS_HOST_NOTIFY.
+* I2C bus drivers trigger SMBus Host Notify by a call to
+ i2c_handle_smbus_host_notify().
+* I2C drivers for devices which can trigger SMBus Host Notify will have
+ client->irq assigned to a Host Notify IRQ if noone else specified an other.
+
+There is currently no way to retrieve the data parameter from the client.
+
+
+Packet Error Checking (PEC)
+===========================
+
+Packet Error Checking was introduced in Revision 1.1 of the specification.
+
+PEC adds a CRC-8 error-checking byte to transfers using it, immediately
+before the terminating STOP.
+
+
+Address Resolution Protocol (ARP)
+=================================
+
+The Address Resolution Protocol was introduced in Revision 2.0 of
+the specification. It is a higher-layer protocol which uses the
+messages above.
+
+ARP adds device enumeration and dynamic address assignment to
+the protocol. All ARP communications use slave address 0x61 and
+require PEC checksums.
+
+
+SMBus Alert
+===========
+
+SMBus Alert was introduced in Revision 1.0 of the specification.
+
+The SMBus alert protocol allows several SMBus slave devices to share a
+single interrupt pin on the SMBus master, while still allowing the master
+to know which slave triggered the interrupt.
+
+This is implemented the following way in the Linux kernel:
+
+* I2C bus drivers which support SMBus alert should call
+ i2c_setup_smbus_alert() to setup SMBus alert support.
+* I2C drivers for devices which can trigger SMBus alerts should implement
+ the optional alert() callback.
+
+
+I2C Block Transactions
+======================
+
+The following I2C block transactions are supported by the
+SMBus layer and are described here for completeness.
+They are *NOT* defined by the SMBus specification.
+
+I2C block transactions do not limit the number of bytes transferred
+but the SMBus layer places a limit of 32 bytes.
+
+
+I2C Block Read: i2c_smbus_read_i2c_block_data()
+================================================
+
+This command reads a block of bytes from a device, from a
+designated register that is specified through the Comm byte::
+
+ S Addr Wr [A] Comm [A]
+ S Addr Rd [A] [Data] A [Data] A ... A [Data] NA P
+
+Functionality flag: I2C_FUNC_SMBUS_READ_I2C_BLOCK
+
+
+I2C Block Write: i2c_smbus_write_i2c_block_data()
+==================================================
+
+The opposite of the Block Read command, this writes bytes to
+a device, to a designated register that is specified through the
+Comm byte. Note that command lengths of 0, 2, or more bytes are
+supported as they are indistinguishable from data.
+
+::
+
+ S Addr Wr [A] Comm [A] Data [A] Data [A] ... [A] Data [A] P
+
+Functionality flag: I2C_FUNC_SMBUS_WRITE_I2C_BLOCK
diff --git a/Documentation/i2c/summary b/Documentation/i2c/summary
deleted file mode 100644
index 809541a..0000000
--- a/Documentation/i2c/summary
+++ /dev/null
@@ -1,43 +0,0 @@
-I2C and SMBus
-=============
-
-I2C (pronounce: I squared C) is a protocol developed by Philips. It is a
-slow two-wire protocol (variable speed, up to 400 kHz), with a high speed
-extension (3.4 MHz). It provides an inexpensive bus for connecting many
-types of devices with infrequent or low bandwidth communications needs.
-I2C is widely used with embedded systems. Some systems use variants that
-don't meet branding requirements, and so are not advertised as being I2C.
-
-SMBus (System Management Bus) is based on the I2C protocol, and is mostly
-a subset of I2C protocols and signaling. Many I2C devices will work on an
-SMBus, but some SMBus protocols add semantics beyond what is required to
-achieve I2C branding. Modern PC mainboards rely on SMBus. The most common
-devices connected through SMBus are RAM modules configured using I2C EEPROMs,
-and hardware monitoring chips.
-
-Because the SMBus is mostly a subset of the generalized I2C bus, we can
-use its protocols on many I2C systems. However, there are systems that don't
-meet both SMBus and I2C electrical constraints; and others which can't
-implement all the common SMBus protocol semantics or messages.
-
-
-Terminology
-===========
-
-When we talk about I2C, we use the following terms:
- Bus -> Algorithm
- Adapter
- Device -> Driver
- Client
-
-An Algorithm driver contains general code that can be used for a whole class
-of I2C adapters. Each specific adapter driver either depends on one algorithm
-driver, or includes its own implementation.
-
-A Driver driver (yes, this sounds ridiculous, sorry) contains the general
-code to access some type of device. Each detected device gets its own
-data in the Client structure. Usually, Driver and Client are more closely
-integrated than Algorithm and Adapter.
-
-For a given configuration, you will need a driver for your I2C bus, and
-drivers for your I2C devices (usually one driver for each device).
diff --git a/Documentation/i2c/summary.rst b/Documentation/i2c/summary.rst
new file mode 100644
index 0000000..3a24eac
--- /dev/null
+++ b/Documentation/i2c/summary.rst
@@ -0,0 +1,45 @@
+=============
+I2C and SMBus
+=============
+
+I2C (pronounce: I squared C) is a protocol developed by Philips. It is a
+slow two-wire protocol (variable speed, up to 400 kHz), with a high speed
+extension (3.4 MHz). It provides an inexpensive bus for connecting many
+types of devices with infrequent or low bandwidth communications needs.
+I2C is widely used with embedded systems. Some systems use variants that
+don't meet branding requirements, and so are not advertised as being I2C.
+
+SMBus (System Management Bus) is based on the I2C protocol, and is mostly
+a subset of I2C protocols and signaling. Many I2C devices will work on an
+SMBus, but some SMBus protocols add semantics beyond what is required to
+achieve I2C branding. Modern PC mainboards rely on SMBus. The most common
+devices connected through SMBus are RAM modules configured using I2C EEPROMs,
+and hardware monitoring chips.
+
+Because the SMBus is mostly a subset of the generalized I2C bus, we can
+use its protocols on many I2C systems. However, there are systems that don't
+meet both SMBus and I2C electrical constraints; and others which can't
+implement all the common SMBus protocol semantics or messages.
+
+
+Terminology
+===========
+
+When we talk about I2C, we use the following terms::
+
+ Bus -> Algorithm
+ Adapter
+ Device -> Driver
+ Client
+
+An Algorithm driver contains general code that can be used for a whole class
+of I2C adapters. Each specific adapter driver either depends on one algorithm
+driver, or includes its own implementation.
+
+A Driver driver (yes, this sounds ridiculous, sorry) contains the general
+code to access some type of device. Each detected device gets its own
+data in the Client structure. Usually, Driver and Client are more closely
+integrated than Algorithm and Adapter.
+
+For a given configuration, you will need a driver for your I2C bus, and
+drivers for your I2C devices (usually one driver for each device).
diff --git a/Documentation/i2c/ten-bit-addresses b/Documentation/i2c/ten-bit-addresses
deleted file mode 100644
index 7b2d11e..0000000
--- a/Documentation/i2c/ten-bit-addresses
+++ /dev/null
@@ -1,28 +0,0 @@
-The I2C protocol knows about two kinds of device addresses: normal 7 bit
-addresses, and an extended set of 10 bit addresses. The sets of addresses
-do not intersect: the 7 bit address 0x10 is not the same as the 10 bit
-address 0x10 (though a single device could respond to both of them).
-To avoid ambiguity, the user sees 10 bit addresses mapped to a different
-address space, namely 0xa000-0xa3ff. The leading 0xa (= 10) represents the
-10 bit mode. This is used for creating device names in sysfs. It is also
-needed when instantiating 10 bit devices via the new_device file in sysfs.
-
-I2C messages to and from 10-bit address devices have a different format.
-See the I2C specification for the details.
-
-The current 10 bit address support is minimal. It should work, however
-you can expect some problems along the way:
-* Not all bus drivers support 10-bit addresses. Some don't because the
- hardware doesn't support them (SMBus doesn't require 10-bit address
- support for example), some don't because nobody bothered adding the
- code (or it's there but not working properly.) Software implementation
- (i2c-algo-bit) is known to work.
-* Some optional features do not support 10-bit addresses. This is the
- case of automatic detection and instantiation of devices by their,
- drivers, for example.
-* Many user-space packages (for example i2c-tools) lack support for
- 10-bit addresses.
-
-Note that 10-bit address devices are still pretty rare, so the limitations
-listed above could stay for a long time, maybe even forever if nobody
-needs them to be fixed.
diff --git a/Documentation/i2c/ten-bit-addresses.rst b/Documentation/i2c/ten-bit-addresses.rst
new file mode 100644
index 0000000..5c765af
--- /dev/null
+++ b/Documentation/i2c/ten-bit-addresses.rst
@@ -0,0 +1,33 @@
+=====================
+I2C Ten-bit Addresses
+=====================
+
+The I2C protocol knows about two kinds of device addresses: normal 7 bit
+addresses, and an extended set of 10 bit addresses. The sets of addresses
+do not intersect: the 7 bit address 0x10 is not the same as the 10 bit
+address 0x10 (though a single device could respond to both of them).
+To avoid ambiguity, the user sees 10 bit addresses mapped to a different
+address space, namely 0xa000-0xa3ff. The leading 0xa (= 10) represents the
+10 bit mode. This is used for creating device names in sysfs. It is also
+needed when instantiating 10 bit devices via the new_device file in sysfs.
+
+I2C messages to and from 10-bit address devices have a different format.
+See the I2C specification for the details.
+
+The current 10 bit address support is minimal. It should work, however
+you can expect some problems along the way:
+
+* Not all bus drivers support 10-bit addresses. Some don't because the
+ hardware doesn't support them (SMBus doesn't require 10-bit address
+ support for example), some don't because nobody bothered adding the
+ code (or it's there but not working properly.) Software implementation
+ (i2c-algo-bit) is known to work.
+* Some optional features do not support 10-bit addresses. This is the
+ case of automatic detection and instantiation of devices by their,
+ drivers, for example.
+* Many user-space packages (for example i2c-tools) lack support for
+ 10-bit addresses.
+
+Note that 10-bit address devices are still pretty rare, so the limitations
+listed above could stay for a long time, maybe even forever if nobody
+needs them to be fixed.
diff --git a/Documentation/i2c/upgrading-clients b/Documentation/i2c/upgrading-clients
deleted file mode 100644
index 96392cc..0000000
--- a/Documentation/i2c/upgrading-clients
+++ /dev/null
@@ -1,279 +0,0 @@
-Upgrading I2C Drivers to the new 2.6 Driver Model
-=================================================
-
-Ben Dooks <ben-linux@fluff.org>
-
-Introduction
-------------
-
-This guide outlines how to alter existing Linux 2.6 client drivers from
-the old to the new new binding methods.
-
-
-Example old-style driver
-------------------------
-
-
-struct example_state {
- struct i2c_client client;
- ....
-};
-
-static struct i2c_driver example_driver;
-
-static unsigned short ignore[] = { I2C_CLIENT_END };
-static unsigned short normal_addr[] = { OUR_ADDR, I2C_CLIENT_END };
-
-I2C_CLIENT_INSMOD;
-
-static int example_attach(struct i2c_adapter *adap, int addr, int kind)
-{
- struct example_state *state;
- struct device *dev = &adap->dev; /* to use for dev_ reports */
- int ret;
-
- state = kzalloc(sizeof(struct example_state), GFP_KERNEL);
- if (state == NULL) {
- dev_err(dev, "failed to create our state\n");
- return -ENOMEM;
- }
-
- example->client.addr = addr;
- example->client.flags = 0;
- example->client.adapter = adap;
-
- i2c_set_clientdata(&state->i2c_client, state);
- strscpy(client->i2c_client.name, "example", sizeof(client->i2c_client.name));
-
- ret = i2c_attach_client(&state->i2c_client);
- if (ret < 0) {
- dev_err(dev, "failed to attach client\n");
- kfree(state);
- return ret;
- }
-
- dev = &state->i2c_client.dev;
-
- /* rest of the initialisation goes here. */
-
- dev_info(dev, "example client created\n");
-
- return 0;
-}
-
-static int example_detach(struct i2c_client *client)
-{
- struct example_state *state = i2c_get_clientdata(client);
-
- i2c_detach_client(client);
- kfree(state);
- return 0;
-}
-
-static int example_attach_adapter(struct i2c_adapter *adap)
-{
- return i2c_probe(adap, &addr_data, example_attach);
-}
-
-static struct i2c_driver example_driver = {
- .driver = {
- .owner = THIS_MODULE,
- .name = "example",
- .pm = &example_pm_ops,
- },
- .attach_adapter = example_attach_adapter,
- .detach_client = example_detach,
-};
-
-
-Updating the client
--------------------
-
-The new style binding model will check against a list of supported
-devices and their associated address supplied by the code registering
-the busses. This means that the driver .attach_adapter and
-.detach_client methods can be removed, along with the addr_data,
-as follows:
-
-- static struct i2c_driver example_driver;
-
-- static unsigned short ignore[] = { I2C_CLIENT_END };
-- static unsigned short normal_addr[] = { OUR_ADDR, I2C_CLIENT_END };
-
-- I2C_CLIENT_INSMOD;
-
-- static int example_attach_adapter(struct i2c_adapter *adap)
-- {
-- return i2c_probe(adap, &addr_data, example_attach);
-- }
-
- static struct i2c_driver example_driver = {
-- .attach_adapter = example_attach_adapter,
-- .detach_client = example_detach,
- }
-
-Add the probe and remove methods to the i2c_driver, as so:
-
- static struct i2c_driver example_driver = {
-+ .probe = example_probe,
-+ .remove = example_remove,
- }
-
-Change the example_attach method to accept the new parameters
-which include the i2c_client that it will be working with:
-
-- static int example_attach(struct i2c_adapter *adap, int addr, int kind)
-+ static int example_probe(struct i2c_client *client,
-+ const struct i2c_device_id *id)
-
-Change the name of example_attach to example_probe to align it with the
-i2c_driver entry names. The rest of the probe routine will now need to be
-changed as the i2c_client has already been setup for use.
-
-The necessary client fields have already been setup before
-the probe function is called, so the following client setup
-can be removed:
-
-- example->client.addr = addr;
-- example->client.flags = 0;
-- example->client.adapter = adap;
--
-- strscpy(client->i2c_client.name, "example", sizeof(client->i2c_client.name));
-
-The i2c_set_clientdata is now:
-
-- i2c_set_clientdata(&state->client, state);
-+ i2c_set_clientdata(client, state);
-
-The call to i2c_attach_client is no longer needed, if the probe
-routine exits successfully, then the driver will be automatically
-attached by the core. Change the probe routine as so:
-
-- ret = i2c_attach_client(&state->i2c_client);
-- if (ret < 0) {
-- dev_err(dev, "failed to attach client\n");
-- kfree(state);
-- return ret;
-- }
-
-
-Remove the storage of 'struct i2c_client' from the 'struct example_state'
-as we are provided with the i2c_client in our example_probe. Instead we
-store a pointer to it for when it is needed.
-
-struct example_state {
-- struct i2c_client client;
-+ struct i2c_client *client;
-
-the new i2c client as so:
-
-- struct device *dev = &adap->dev; /* to use for dev_ reports */
-+ struct device *dev = &i2c_client->dev; /* to use for dev_ reports */
-
-And remove the change after our client is attached, as the driver no
-longer needs to register a new client structure with the core:
-
-- dev = &state->i2c_client.dev;
-
-In the probe routine, ensure that the new state has the client stored
-in it:
-
-static int example_probe(struct i2c_client *i2c_client,
- const struct i2c_device_id *id)
-{
- struct example_state *state;
- struct device *dev = &i2c_client->dev;
- int ret;
-
- state = kzalloc(sizeof(struct example_state), GFP_KERNEL);
- if (state == NULL) {
- dev_err(dev, "failed to create our state\n");
- return -ENOMEM;
- }
-
-+ state->client = i2c_client;
-
-Update the detach method, by changing the name to _remove and
-to delete the i2c_detach_client call. It is possible that you
-can also remove the ret variable as it is not needed for any
-of the core functions.
-
-- static int example_detach(struct i2c_client *client)
-+ static int example_remove(struct i2c_client *client)
-{
- struct example_state *state = i2c_get_clientdata(client);
-
-- i2c_detach_client(client);
-
-And finally ensure that we have the correct ID table for the i2c-core
-and other utilities:
-
-+ struct i2c_device_id example_idtable[] = {
-+ { "example", 0 },
-+ { }
-+};
-+
-+MODULE_DEVICE_TABLE(i2c, example_idtable);
-
-static struct i2c_driver example_driver = {
- .driver = {
- .owner = THIS_MODULE,
- .name = "example",
- },
-+ .id_table = example_ids,
-
-
-Our driver should now look like this:
-
-struct example_state {
- struct i2c_client *client;
- ....
-};
-
-static int example_probe(struct i2c_client *client,
- const struct i2c_device_id *id)
-{
- struct example_state *state;
- struct device *dev = &client->dev;
-
- state = kzalloc(sizeof(struct example_state), GFP_KERNEL);
- if (state == NULL) {
- dev_err(dev, "failed to create our state\n");
- return -ENOMEM;
- }
-
- state->client = client;
- i2c_set_clientdata(client, state);
-
- /* rest of the initialisation goes here. */
-
- dev_info(dev, "example client created\n");
-
- return 0;
-}
-
-static int example_remove(struct i2c_client *client)
-{
- struct example_state *state = i2c_get_clientdata(client);
-
- kfree(state);
- return 0;
-}
-
-static struct i2c_device_id example_idtable[] = {
- { "example", 0 },
- { }
-};
-
-MODULE_DEVICE_TABLE(i2c, example_idtable);
-
-static struct i2c_driver example_driver = {
- .driver = {
- .owner = THIS_MODULE,
- .name = "example",
- .pm = &example_pm_ops,
- },
- .id_table = example_idtable,
- .probe = example_probe,
- .remove = example_remove,
-};
diff --git a/Documentation/i2c/upgrading-clients.rst b/Documentation/i2c/upgrading-clients.rst
new file mode 100644
index 0000000..27d2903
--- /dev/null
+++ b/Documentation/i2c/upgrading-clients.rst
@@ -0,0 +1,285 @@
+=================================================
+Upgrading I2C Drivers to the new 2.6 Driver Model
+=================================================
+
+Ben Dooks <ben-linux@fluff.org>
+
+Introduction
+------------
+
+This guide outlines how to alter existing Linux 2.6 client drivers from
+the old to the new new binding methods.
+
+
+Example old-style driver
+------------------------
+
+::
+
+ struct example_state {
+ struct i2c_client client;
+ ....
+ };
+
+ static struct i2c_driver example_driver;
+
+ static unsigned short ignore[] = { I2C_CLIENT_END };
+ static unsigned short normal_addr[] = { OUR_ADDR, I2C_CLIENT_END };
+
+ I2C_CLIENT_INSMOD;
+
+ static int example_attach(struct i2c_adapter *adap, int addr, int kind)
+ {
+ struct example_state *state;
+ struct device *dev = &adap->dev; /* to use for dev_ reports */
+ int ret;
+
+ state = kzalloc(sizeof(struct example_state), GFP_KERNEL);
+ if (state == NULL) {
+ dev_err(dev, "failed to create our state\n");
+ return -ENOMEM;
+ }
+
+ example->client.addr = addr;
+ example->client.flags = 0;
+ example->client.adapter = adap;
+
+ i2c_set_clientdata(&state->i2c_client, state);
+ strscpy(client->i2c_client.name, "example", sizeof(client->i2c_client.name));
+
+ ret = i2c_attach_client(&state->i2c_client);
+ if (ret < 0) {
+ dev_err(dev, "failed to attach client\n");
+ kfree(state);
+ return ret;
+ }
+
+ dev = &state->i2c_client.dev;
+
+ /* rest of the initialisation goes here. */
+
+ dev_info(dev, "example client created\n");
+
+ return 0;
+ }
+
+ static int example_detach(struct i2c_client *client)
+ {
+ struct example_state *state = i2c_get_clientdata(client);
+
+ i2c_detach_client(client);
+ kfree(state);
+ return 0;
+ }
+
+ static int example_attach_adapter(struct i2c_adapter *adap)
+ {
+ return i2c_probe(adap, &addr_data, example_attach);
+ }
+
+ static struct i2c_driver example_driver = {
+ .driver = {
+ .owner = THIS_MODULE,
+ .name = "example",
+ .pm = &example_pm_ops,
+ },
+ .attach_adapter = example_attach_adapter,
+ .detach_client = example_detach,
+ };
+
+
+Updating the client
+-------------------
+
+The new style binding model will check against a list of supported
+devices and their associated address supplied by the code registering
+the busses. This means that the driver .attach_adapter and
+.detach_client methods can be removed, along with the addr_data,
+as follows::
+
+ - static struct i2c_driver example_driver;
+
+ - static unsigned short ignore[] = { I2C_CLIENT_END };
+ - static unsigned short normal_addr[] = { OUR_ADDR, I2C_CLIENT_END };
+
+ - I2C_CLIENT_INSMOD;
+
+ - static int example_attach_adapter(struct i2c_adapter *adap)
+ - {
+ - return i2c_probe(adap, &addr_data, example_attach);
+ - }
+
+ static struct i2c_driver example_driver = {
+ - .attach_adapter = example_attach_adapter,
+ - .detach_client = example_detach,
+ }
+
+Add the probe and remove methods to the i2c_driver, as so::
+
+ static struct i2c_driver example_driver = {
+ + .probe = example_probe,
+ + .remove = example_remove,
+ }
+
+Change the example_attach method to accept the new parameters
+which include the i2c_client that it will be working with::
+
+ - static int example_attach(struct i2c_adapter *adap, int addr, int kind)
+ + static int example_probe(struct i2c_client *client,
+ + const struct i2c_device_id *id)
+
+Change the name of example_attach to example_probe to align it with the
+i2c_driver entry names. The rest of the probe routine will now need to be
+changed as the i2c_client has already been setup for use.
+
+The necessary client fields have already been setup before
+the probe function is called, so the following client setup
+can be removed::
+
+ - example->client.addr = addr;
+ - example->client.flags = 0;
+ - example->client.adapter = adap;
+ -
+ - strscpy(client->i2c_client.name, "example", sizeof(client->i2c_client.name));
+
+The i2c_set_clientdata is now::
+
+ - i2c_set_clientdata(&state->client, state);
+ + i2c_set_clientdata(client, state);
+
+The call to i2c_attach_client is no longer needed, if the probe
+routine exits successfully, then the driver will be automatically
+attached by the core. Change the probe routine as so::
+
+ - ret = i2c_attach_client(&state->i2c_client);
+ - if (ret < 0) {
+ - dev_err(dev, "failed to attach client\n");
+ - kfree(state);
+ - return ret;
+ - }
+
+
+Remove the storage of 'struct i2c_client' from the 'struct example_state'
+as we are provided with the i2c_client in our example_probe. Instead we
+store a pointer to it for when it is needed.
+
+::
+
+ struct example_state {
+ - struct i2c_client client;
+ + struct i2c_client *client;
+
+the new i2c client as so::
+
+ - struct device *dev = &adap->dev; /* to use for dev_ reports */
+ + struct device *dev = &i2c_client->dev; /* to use for dev_ reports */
+
+And remove the change after our client is attached, as the driver no
+longer needs to register a new client structure with the core::
+
+ - dev = &state->i2c_client.dev;
+
+In the probe routine, ensure that the new state has the client stored
+in it::
+
+ static int example_probe(struct i2c_client *i2c_client,
+ const struct i2c_device_id *id)
+ {
+ struct example_state *state;
+ struct device *dev = &i2c_client->dev;
+ int ret;
+
+ state = kzalloc(sizeof(struct example_state), GFP_KERNEL);
+ if (state == NULL) {
+ dev_err(dev, "failed to create our state\n");
+ return -ENOMEM;
+ }
+
+ + state->client = i2c_client;
+
+Update the detach method, by changing the name to _remove and
+to delete the i2c_detach_client call. It is possible that you
+can also remove the ret variable as it is not needed for any
+of the core functions.
+
+::
+
+ - static int example_detach(struct i2c_client *client)
+ + static int example_remove(struct i2c_client *client)
+ {
+ struct example_state *state = i2c_get_clientdata(client);
+
+ - i2c_detach_client(client);
+
+And finally ensure that we have the correct ID table for the i2c-core
+and other utilities::
+
+ + struct i2c_device_id example_idtable[] = {
+ + { "example", 0 },
+ + { }
+ +};
+ +
+ +MODULE_DEVICE_TABLE(i2c, example_idtable);
+
+ static struct i2c_driver example_driver = {
+ .driver = {
+ .owner = THIS_MODULE,
+ .name = "example",
+ },
+ + .id_table = example_ids,
+
+
+Our driver should now look like this::
+
+ struct example_state {
+ struct i2c_client *client;
+ ....
+ };
+
+ static int example_probe(struct i2c_client *client,
+ const struct i2c_device_id *id)
+ {
+ struct example_state *state;
+ struct device *dev = &client->dev;
+
+ state = kzalloc(sizeof(struct example_state), GFP_KERNEL);
+ if (state == NULL) {
+ dev_err(dev, "failed to create our state\n");
+ return -ENOMEM;
+ }
+
+ state->client = client;
+ i2c_set_clientdata(client, state);
+
+ /* rest of the initialisation goes here. */
+
+ dev_info(dev, "example client created\n");
+
+ return 0;
+ }
+
+ static int example_remove(struct i2c_client *client)
+ {
+ struct example_state *state = i2c_get_clientdata(client);
+
+ kfree(state);
+ return 0;
+ }
+
+ static struct i2c_device_id example_idtable[] = {
+ { "example", 0 },
+ { }
+ };
+
+ MODULE_DEVICE_TABLE(i2c, example_idtable);
+
+ static struct i2c_driver example_driver = {
+ .driver = {
+ .owner = THIS_MODULE,
+ .name = "example",
+ .pm = &example_pm_ops,
+ },
+ .id_table = example_idtable,
+ .probe = example_probe,
+ .remove = example_remove,
+ };
diff --git a/Documentation/i2c/writing-clients b/Documentation/i2c/writing-clients
deleted file mode 100644
index a755b14..0000000
--- a/Documentation/i2c/writing-clients
+++ /dev/null
@@ -1,403 +0,0 @@
-This is a small guide for those who want to write kernel drivers for I2C
-or SMBus devices, using Linux as the protocol host/master (not slave).
-
-To set up a driver, you need to do several things. Some are optional, and
-some things can be done slightly or completely different. Use this as a
-guide, not as a rule book!
-
-
-General remarks
-===============
-
-Try to keep the kernel namespace as clean as possible. The best way to
-do this is to use a unique prefix for all global symbols. This is
-especially important for exported symbols, but it is a good idea to do
-it for non-exported symbols too. We will use the prefix `foo_' in this
-tutorial.
-
-
-The driver structure
-====================
-
-Usually, you will implement a single driver structure, and instantiate
-all clients from it. Remember, a driver structure contains general access
-routines, and should be zero-initialized except for fields with data you
-provide. A client structure holds device-specific information like the
-driver model device node, and its I2C address.
-
-static struct i2c_device_id foo_idtable[] = {
- { "foo", my_id_for_foo },
- { "bar", my_id_for_bar },
- { }
-};
-
-MODULE_DEVICE_TABLE(i2c, foo_idtable);
-
-static struct i2c_driver foo_driver = {
- .driver = {
- .name = "foo",
- .pm = &foo_pm_ops, /* optional */
- },
-
- .id_table = foo_idtable,
- .probe = foo_probe,
- .remove = foo_remove,
- /* if device autodetection is needed: */
- .class = I2C_CLASS_SOMETHING,
- .detect = foo_detect,
- .address_list = normal_i2c,
-
- .shutdown = foo_shutdown, /* optional */
- .command = foo_command, /* optional, deprecated */
-}
-
-The name field is the driver name, and must not contain spaces. It
-should match the module name (if the driver can be compiled as a module),
-although you can use MODULE_ALIAS (passing "foo" in this example) to add
-another name for the module. If the driver name doesn't match the module
-name, the module won't be automatically loaded (hotplug/coldplug).
-
-All other fields are for call-back functions which will be explained
-below.
-
-
-Extra client data
-=================
-
-Each client structure has a special `data' field that can point to any
-structure at all. You should use this to keep device-specific data.
-
- /* store the value */
- void i2c_set_clientdata(struct i2c_client *client, void *data);
-
- /* retrieve the value */
- void *i2c_get_clientdata(const struct i2c_client *client);
-
-Note that starting with kernel 2.6.34, you don't have to set the `data' field
-to NULL in remove() or if probe() failed anymore. The i2c-core does this
-automatically on these occasions. Those are also the only times the core will
-touch this field.
-
-
-Accessing the client
-====================
-
-Let's say we have a valid client structure. At some time, we will need
-to gather information from the client, or write new information to the
-client.
-
-I have found it useful to define foo_read and foo_write functions for this.
-For some cases, it will be easier to call the i2c functions directly,
-but many chips have some kind of register-value idea that can easily
-be encapsulated.
-
-The below functions are simple examples, and should not be copied
-literally.
-
-int foo_read_value(struct i2c_client *client, u8 reg)
-{
- if (reg < 0x10) /* byte-sized register */
- return i2c_smbus_read_byte_data(client, reg);
- else /* word-sized register */
- return i2c_smbus_read_word_data(client, reg);
-}
-
-int foo_write_value(struct i2c_client *client, u8 reg, u16 value)
-{
- if (reg == 0x10) /* Impossible to write - driver error! */
- return -EINVAL;
- else if (reg < 0x10) /* byte-sized register */
- return i2c_smbus_write_byte_data(client, reg, value);
- else /* word-sized register */
- return i2c_smbus_write_word_data(client, reg, value);
-}
-
-
-Probing and attaching
-=====================
-
-The Linux I2C stack was originally written to support access to hardware
-monitoring chips on PC motherboards, and thus used to embed some assumptions
-that were more appropriate to SMBus (and PCs) than to I2C. One of these
-assumptions was that most adapters and devices drivers support the SMBUS_QUICK
-protocol to probe device presence. Another was that devices and their drivers
-can be sufficiently configured using only such probe primitives.
-
-As Linux and its I2C stack became more widely used in embedded systems
-and complex components such as DVB adapters, those assumptions became more
-problematic. Drivers for I2C devices that issue interrupts need more (and
-different) configuration information, as do drivers handling chip variants
-that can't be distinguished by protocol probing, or which need some board
-specific information to operate correctly.
-
-
-Device/Driver Binding
----------------------
-
-System infrastructure, typically board-specific initialization code or
-boot firmware, reports what I2C devices exist. For example, there may be
-a table, in the kernel or from the boot loader, identifying I2C devices
-and linking them to board-specific configuration information about IRQs
-and other wiring artifacts, chip type, and so on. That could be used to
-create i2c_client objects for each I2C device.
-
-I2C device drivers using this binding model work just like any other
-kind of driver in Linux: they provide a probe() method to bind to
-those devices, and a remove() method to unbind.
-
- static int foo_probe(struct i2c_client *client,
- const struct i2c_device_id *id);
- static int foo_remove(struct i2c_client *client);
-
-Remember that the i2c_driver does not create those client handles. The
-handle may be used during foo_probe(). If foo_probe() reports success
-(zero not a negative status code) it may save the handle and use it until
-foo_remove() returns. That binding model is used by most Linux drivers.
-
-The probe function is called when an entry in the id_table name field
-matches the device's name. It is passed the entry that was matched so
-the driver knows which one in the table matched.
-
-
-Device Creation
----------------
-
-If you know for a fact that an I2C device is connected to a given I2C bus,
-you can instantiate that device by simply filling an i2c_board_info
-structure with the device address and driver name, and calling
-i2c_new_device(). This will create the device, then the driver core will
-take care of finding the right driver and will call its probe() method.
-If a driver supports different device types, you can specify the type you
-want using the type field. You can also specify an IRQ and platform data
-if needed.
-
-Sometimes you know that a device is connected to a given I2C bus, but you
-don't know the exact address it uses. This happens on TV adapters for
-example, where the same driver supports dozens of slightly different
-models, and I2C device addresses change from one model to the next. In
-that case, you can use the i2c_new_probed_device() variant, which is
-similar to i2c_new_device(), except that it takes an additional list of
-possible I2C addresses to probe. A device is created for the first
-responsive address in the list. If you expect more than one device to be
-present in the address range, simply call i2c_new_probed_device() that
-many times.
-
-The call to i2c_new_device() or i2c_new_probed_device() typically happens
-in the I2C bus driver. You may want to save the returned i2c_client
-reference for later use.
-
-
-Device Detection
-----------------
-
-Sometimes you do not know in advance which I2C devices are connected to
-a given I2C bus. This is for example the case of hardware monitoring
-devices on a PC's SMBus. In that case, you may want to let your driver
-detect supported devices automatically. This is how the legacy model
-was working, and is now available as an extension to the standard
-driver model.
-
-You simply have to define a detect callback which will attempt to
-identify supported devices (returning 0 for supported ones and -ENODEV
-for unsupported ones), a list of addresses to probe, and a device type
-(or class) so that only I2C buses which may have that type of device
-connected (and not otherwise enumerated) will be probed. For example,
-a driver for a hardware monitoring chip for which auto-detection is
-needed would set its class to I2C_CLASS_HWMON, and only I2C adapters
-with a class including I2C_CLASS_HWMON would be probed by this driver.
-Note that the absence of matching classes does not prevent the use of
-a device of that type on the given I2C adapter. All it prevents is
-auto-detection; explicit instantiation of devices is still possible.
-
-Note that this mechanism is purely optional and not suitable for all
-devices. You need some reliable way to identify the supported devices
-(typically using device-specific, dedicated identification registers),
-otherwise misdetections are likely to occur and things can get wrong
-quickly. Keep in mind that the I2C protocol doesn't include any
-standard way to detect the presence of a chip at a given address, let
-alone a standard way to identify devices. Even worse is the lack of
-semantics associated to bus transfers, which means that the same
-transfer can be seen as a read operation by a chip and as a write
-operation by another chip. For these reasons, explicit device
-instantiation should always be preferred to auto-detection where
-possible.
-
-
-Device Deletion
----------------
-
-Each I2C device which has been created using i2c_new_device() or
-i2c_new_probed_device() can be unregistered by calling
-i2c_unregister_device(). If you don't call it explicitly, it will be
-called automatically before the underlying I2C bus itself is removed, as a
-device can't survive its parent in the device driver model.
-
-
-Initializing the driver
-=======================
-
-When the kernel is booted, or when your foo driver module is inserted,
-you have to do some initializing. Fortunately, just registering the
-driver module is usually enough.
-
-static int __init foo_init(void)
-{
- return i2c_add_driver(&foo_driver);
-}
-module_init(foo_init);
-
-static void __exit foo_cleanup(void)
-{
- i2c_del_driver(&foo_driver);
-}
-module_exit(foo_cleanup);
-
-The module_i2c_driver() macro can be used to reduce above code.
-
-module_i2c_driver(foo_driver);
-
-Note that some functions are marked by `__init'. These functions can
-be removed after kernel booting (or module loading) is completed.
-Likewise, functions marked by `__exit' are dropped by the compiler when
-the code is built into the kernel, as they would never be called.
-
-
-Driver Information
-==================
-
-/* Substitute your own name and email address */
-MODULE_AUTHOR("Frodo Looijaard <frodol@dds.nl>"
-MODULE_DESCRIPTION("Driver for Barf Inc. Foo I2C devices");
-
-/* a few non-GPL license types are also allowed */
-MODULE_LICENSE("GPL");
-
-
-Power Management
-================
-
-If your I2C device needs special handling when entering a system low
-power state -- like putting a transceiver into a low power mode, or
-activating a system wakeup mechanism -- do that by implementing the
-appropriate callbacks for the dev_pm_ops of the driver (like suspend
-and resume).
-
-These are standard driver model calls, and they work just like they
-would for any other driver stack. The calls can sleep, and can use
-I2C messaging to the device being suspended or resumed (since their
-parent I2C adapter is active when these calls are issued, and IRQs
-are still enabled).
-
-
-System Shutdown
-===============
-
-If your I2C device needs special handling when the system shuts down
-or reboots (including kexec) -- like turning something off -- use a
-shutdown() method.
-
-Again, this is a standard driver model call, working just like it
-would for any other driver stack: the calls can sleep, and can use
-I2C messaging.
-
-
-Command function
-================
-
-A generic ioctl-like function call back is supported. You will seldom
-need this, and its use is deprecated anyway, so newer design should not
-use it.
-
-
-Sending and receiving
-=====================
-
-If you want to communicate with your device, there are several functions
-to do this. You can find all of them in <linux/i2c.h>.
-
-If you can choose between plain I2C communication and SMBus level
-communication, please use the latter. All adapters understand SMBus level
-commands, but only some of them understand plain I2C!
-
-
-Plain I2C communication
------------------------
-
- int i2c_master_send(struct i2c_client *client, const char *buf,
- int count);
- int i2c_master_recv(struct i2c_client *client, char *buf, int count);
-
-These routines read and write some bytes from/to a client. The client
-contains the i2c address, so you do not have to include it. The second
-parameter contains the bytes to read/write, the third the number of bytes
-to read/write (must be less than the length of the buffer, also should be
-less than 64k since msg.len is u16.) Returned is the actual number of bytes
-read/written.
-
- int i2c_transfer(struct i2c_adapter *adap, struct i2c_msg *msg,
- int num);
-
-This sends a series of messages. Each message can be a read or write,
-and they can be mixed in any way. The transactions are combined: no
-stop bit is sent between transaction. The i2c_msg structure contains
-for each message the client address, the number of bytes of the message
-and the message data itself.
-
-You can read the file `i2c-protocol' for more information about the
-actual I2C protocol.
-
-
-SMBus communication
--------------------
-
- s32 i2c_smbus_xfer(struct i2c_adapter *adapter, u16 addr,
- unsigned short flags, char read_write, u8 command,
- int size, union i2c_smbus_data *data);
-
-This is the generic SMBus function. All functions below are implemented
-in terms of it. Never use this function directly!
-
- s32 i2c_smbus_read_byte(struct i2c_client *client);
- s32 i2c_smbus_write_byte(struct i2c_client *client, u8 value);
- s32 i2c_smbus_read_byte_data(struct i2c_client *client, u8 command);
- s32 i2c_smbus_write_byte_data(struct i2c_client *client,
- u8 command, u8 value);
- s32 i2c_smbus_read_word_data(struct i2c_client *client, u8 command);
- s32 i2c_smbus_write_word_data(struct i2c_client *client,
- u8 command, u16 value);
- s32 i2c_smbus_read_block_data(struct i2c_client *client,
- u8 command, u8 *values);
- s32 i2c_smbus_write_block_data(struct i2c_client *client,
- u8 command, u8 length, const u8 *values);
- s32 i2c_smbus_read_i2c_block_data(struct i2c_client *client,
- u8 command, u8 length, u8 *values);
- s32 i2c_smbus_write_i2c_block_data(struct i2c_client *client,
- u8 command, u8 length,
- const u8 *values);
-
-These ones were removed from i2c-core because they had no users, but could
-be added back later if needed:
-
- s32 i2c_smbus_write_quick(struct i2c_client *client, u8 value);
- s32 i2c_smbus_process_call(struct i2c_client *client,
- u8 command, u16 value);
- s32 i2c_smbus_block_process_call(struct i2c_client *client,
- u8 command, u8 length, u8 *values);
-
-All these transactions return a negative errno value on failure. The 'write'
-transactions return 0 on success; the 'read' transactions return the read
-value, except for block transactions, which return the number of values
-read. The block buffers need not be longer than 32 bytes.
-
-You can read the file `smbus-protocol' for more information about the
-actual SMBus protocol.
-
-
-General purpose routines
-========================
-
-Below all general purpose routines are listed, that were not mentioned
-before.
-
- /* Return the adapter number for a specific adapter */
- int i2c_adapter_id(struct i2c_adapter *adap);
diff --git a/Documentation/i2c/writing-clients.rst b/Documentation/i2c/writing-clients.rst
new file mode 100644
index 0000000..dddf0a1
--- /dev/null
+++ b/Documentation/i2c/writing-clients.rst
@@ -0,0 +1,425 @@
+===================
+Writing I2C Clients
+===================
+
+This is a small guide for those who want to write kernel drivers for I2C
+or SMBus devices, using Linux as the protocol host/master (not slave).
+
+To set up a driver, you need to do several things. Some are optional, and
+some things can be done slightly or completely different. Use this as a
+guide, not as a rule book!
+
+
+General remarks
+===============
+
+Try to keep the kernel namespace as clean as possible. The best way to
+do this is to use a unique prefix for all global symbols. This is
+especially important for exported symbols, but it is a good idea to do
+it for non-exported symbols too. We will use the prefix ``foo_`` in this
+tutorial.
+
+
+The driver structure
+====================
+
+Usually, you will implement a single driver structure, and instantiate
+all clients from it. Remember, a driver structure contains general access
+routines, and should be zero-initialized except for fields with data you
+provide. A client structure holds device-specific information like the
+driver model device node, and its I2C address.
+
+::
+
+ static struct i2c_device_id foo_idtable[] = {
+ { "foo", my_id_for_foo },
+ { "bar", my_id_for_bar },
+ { }
+ };
+
+ MODULE_DEVICE_TABLE(i2c, foo_idtable);
+
+ static struct i2c_driver foo_driver = {
+ .driver = {
+ .name = "foo",
+ .pm = &foo_pm_ops, /* optional */
+ },
+
+ .id_table = foo_idtable,
+ .probe = foo_probe,
+ .remove = foo_remove,
+ /* if device autodetection is needed: */
+ .class = I2C_CLASS_SOMETHING,
+ .detect = foo_detect,
+ .address_list = normal_i2c,
+
+ .shutdown = foo_shutdown, /* optional */
+ .command = foo_command, /* optional, deprecated */
+ }
+
+The name field is the driver name, and must not contain spaces. It
+should match the module name (if the driver can be compiled as a module),
+although you can use MODULE_ALIAS (passing "foo" in this example) to add
+another name for the module. If the driver name doesn't match the module
+name, the module won't be automatically loaded (hotplug/coldplug).
+
+All other fields are for call-back functions which will be explained
+below.
+
+
+Extra client data
+=================
+
+Each client structure has a special ``data`` field that can point to any
+structure at all. You should use this to keep device-specific data.
+
+::
+
+ /* store the value */
+ void i2c_set_clientdata(struct i2c_client *client, void *data);
+
+ /* retrieve the value */
+ void *i2c_get_clientdata(const struct i2c_client *client);
+
+Note that starting with kernel 2.6.34, you don't have to set the ``data`` field
+to NULL in remove() or if probe() failed anymore. The i2c-core does this
+automatically on these occasions. Those are also the only times the core will
+touch this field.
+
+
+Accessing the client
+====================
+
+Let's say we have a valid client structure. At some time, we will need
+to gather information from the client, or write new information to the
+client.
+
+I have found it useful to define foo_read and foo_write functions for this.
+For some cases, it will be easier to call the i2c functions directly,
+but many chips have some kind of register-value idea that can easily
+be encapsulated.
+
+The below functions are simple examples, and should not be copied
+literally::
+
+ int foo_read_value(struct i2c_client *client, u8 reg)
+ {
+ if (reg < 0x10) /* byte-sized register */
+ return i2c_smbus_read_byte_data(client, reg);
+ else /* word-sized register */
+ return i2c_smbus_read_word_data(client, reg);
+ }
+
+ int foo_write_value(struct i2c_client *client, u8 reg, u16 value)
+ {
+ if (reg == 0x10) /* Impossible to write - driver error! */
+ return -EINVAL;
+ else if (reg < 0x10) /* byte-sized register */
+ return i2c_smbus_write_byte_data(client, reg, value);
+ else /* word-sized register */
+ return i2c_smbus_write_word_data(client, reg, value);
+ }
+
+
+Probing and attaching
+=====================
+
+The Linux I2C stack was originally written to support access to hardware
+monitoring chips on PC motherboards, and thus used to embed some assumptions
+that were more appropriate to SMBus (and PCs) than to I2C. One of these
+assumptions was that most adapters and devices drivers support the SMBUS_QUICK
+protocol to probe device presence. Another was that devices and their drivers
+can be sufficiently configured using only such probe primitives.
+
+As Linux and its I2C stack became more widely used in embedded systems
+and complex components such as DVB adapters, those assumptions became more
+problematic. Drivers for I2C devices that issue interrupts need more (and
+different) configuration information, as do drivers handling chip variants
+that can't be distinguished by protocol probing, or which need some board
+specific information to operate correctly.
+
+
+Device/Driver Binding
+---------------------
+
+System infrastructure, typically board-specific initialization code or
+boot firmware, reports what I2C devices exist. For example, there may be
+a table, in the kernel or from the boot loader, identifying I2C devices
+and linking them to board-specific configuration information about IRQs
+and other wiring artifacts, chip type, and so on. That could be used to
+create i2c_client objects for each I2C device.
+
+I2C device drivers using this binding model work just like any other
+kind of driver in Linux: they provide a probe() method to bind to
+those devices, and a remove() method to unbind.
+
+::
+
+ static int foo_probe(struct i2c_client *client,
+ const struct i2c_device_id *id);
+ static int foo_remove(struct i2c_client *client);
+
+Remember that the i2c_driver does not create those client handles. The
+handle may be used during foo_probe(). If foo_probe() reports success
+(zero not a negative status code) it may save the handle and use it until
+foo_remove() returns. That binding model is used by most Linux drivers.
+
+The probe function is called when an entry in the id_table name field
+matches the device's name. It is passed the entry that was matched so
+the driver knows which one in the table matched.
+
+
+Device Creation
+---------------
+
+If you know for a fact that an I2C device is connected to a given I2C bus,
+you can instantiate that device by simply filling an i2c_board_info
+structure with the device address and driver name, and calling
+i2c_new_device(). This will create the device, then the driver core will
+take care of finding the right driver and will call its probe() method.
+If a driver supports different device types, you can specify the type you
+want using the type field. You can also specify an IRQ and platform data
+if needed.
+
+Sometimes you know that a device is connected to a given I2C bus, but you
+don't know the exact address it uses. This happens on TV adapters for
+example, where the same driver supports dozens of slightly different
+models, and I2C device addresses change from one model to the next. In
+that case, you can use the i2c_new_probed_device() variant, which is
+similar to i2c_new_device(), except that it takes an additional list of
+possible I2C addresses to probe. A device is created for the first
+responsive address in the list. If you expect more than one device to be
+present in the address range, simply call i2c_new_probed_device() that
+many times.
+
+The call to i2c_new_device() or i2c_new_probed_device() typically happens
+in the I2C bus driver. You may want to save the returned i2c_client
+reference for later use.
+
+
+Device Detection
+----------------
+
+Sometimes you do not know in advance which I2C devices are connected to
+a given I2C bus. This is for example the case of hardware monitoring
+devices on a PC's SMBus. In that case, you may want to let your driver
+detect supported devices automatically. This is how the legacy model
+was working, and is now available as an extension to the standard
+driver model.
+
+You simply have to define a detect callback which will attempt to
+identify supported devices (returning 0 for supported ones and -ENODEV
+for unsupported ones), a list of addresses to probe, and a device type
+(or class) so that only I2C buses which may have that type of device
+connected (and not otherwise enumerated) will be probed. For example,
+a driver for a hardware monitoring chip for which auto-detection is
+needed would set its class to I2C_CLASS_HWMON, and only I2C adapters
+with a class including I2C_CLASS_HWMON would be probed by this driver.
+Note that the absence of matching classes does not prevent the use of
+a device of that type on the given I2C adapter. All it prevents is
+auto-detection; explicit instantiation of devices is still possible.
+
+Note that this mechanism is purely optional and not suitable for all
+devices. You need some reliable way to identify the supported devices
+(typically using device-specific, dedicated identification registers),
+otherwise misdetections are likely to occur and things can get wrong
+quickly. Keep in mind that the I2C protocol doesn't include any
+standard way to detect the presence of a chip at a given address, let
+alone a standard way to identify devices. Even worse is the lack of
+semantics associated to bus transfers, which means that the same
+transfer can be seen as a read operation by a chip and as a write
+operation by another chip. For these reasons, explicit device
+instantiation should always be preferred to auto-detection where
+possible.
+
+
+Device Deletion
+---------------
+
+Each I2C device which has been created using i2c_new_device() or
+i2c_new_probed_device() can be unregistered by calling
+i2c_unregister_device(). If you don't call it explicitly, it will be
+called automatically before the underlying I2C bus itself is removed, as a
+device can't survive its parent in the device driver model.
+
+
+Initializing the driver
+=======================
+
+When the kernel is booted, or when your foo driver module is inserted,
+you have to do some initializing. Fortunately, just registering the
+driver module is usually enough.
+
+::
+
+ static int __init foo_init(void)
+ {
+ return i2c_add_driver(&foo_driver);
+ }
+ module_init(foo_init);
+
+ static void __exit foo_cleanup(void)
+ {
+ i2c_del_driver(&foo_driver);
+ }
+ module_exit(foo_cleanup);
+
+ The module_i2c_driver() macro can be used to reduce above code.
+
+ module_i2c_driver(foo_driver);
+
+Note that some functions are marked by ``__init``. These functions can
+be removed after kernel booting (or module loading) is completed.
+Likewise, functions marked by ``__exit`` are dropped by the compiler when
+the code is built into the kernel, as they would never be called.
+
+
+Driver Information
+==================
+
+::
+
+ /* Substitute your own name and email address */
+ MODULE_AUTHOR("Frodo Looijaard <frodol@dds.nl>"
+ MODULE_DESCRIPTION("Driver for Barf Inc. Foo I2C devices");
+
+ /* a few non-GPL license types are also allowed */
+ MODULE_LICENSE("GPL");
+
+
+Power Management
+================
+
+If your I2C device needs special handling when entering a system low
+power state -- like putting a transceiver into a low power mode, or
+activating a system wakeup mechanism -- do that by implementing the
+appropriate callbacks for the dev_pm_ops of the driver (like suspend
+and resume).
+
+These are standard driver model calls, and they work just like they
+would for any other driver stack. The calls can sleep, and can use
+I2C messaging to the device being suspended or resumed (since their
+parent I2C adapter is active when these calls are issued, and IRQs
+are still enabled).
+
+
+System Shutdown
+===============
+
+If your I2C device needs special handling when the system shuts down
+or reboots (including kexec) -- like turning something off -- use a
+shutdown() method.
+
+Again, this is a standard driver model call, working just like it
+would for any other driver stack: the calls can sleep, and can use
+I2C messaging.
+
+
+Command function
+================
+
+A generic ioctl-like function call back is supported. You will seldom
+need this, and its use is deprecated anyway, so newer design should not
+use it.
+
+
+Sending and receiving
+=====================
+
+If you want to communicate with your device, there are several functions
+to do this. You can find all of them in <linux/i2c.h>.
+
+If you can choose between plain I2C communication and SMBus level
+communication, please use the latter. All adapters understand SMBus level
+commands, but only some of them understand plain I2C!
+
+
+Plain I2C communication
+-----------------------
+
+::
+
+ int i2c_master_send(struct i2c_client *client, const char *buf,
+ int count);
+ int i2c_master_recv(struct i2c_client *client, char *buf, int count);
+
+These routines read and write some bytes from/to a client. The client
+contains the i2c address, so you do not have to include it. The second
+parameter contains the bytes to read/write, the third the number of bytes
+to read/write (must be less than the length of the buffer, also should be
+less than 64k since msg.len is u16.) Returned is the actual number of bytes
+read/written.
+
+::
+
+ int i2c_transfer(struct i2c_adapter *adap, struct i2c_msg *msg,
+ int num);
+
+This sends a series of messages. Each message can be a read or write,
+and they can be mixed in any way. The transactions are combined: no
+stop bit is sent between transaction. The i2c_msg structure contains
+for each message the client address, the number of bytes of the message
+and the message data itself.
+
+You can read the file ``i2c-protocol`` for more information about the
+actual I2C protocol.
+
+
+SMBus communication
+-------------------
+
+::
+
+ s32 i2c_smbus_xfer(struct i2c_adapter *adapter, u16 addr,
+ unsigned short flags, char read_write, u8 command,
+ int size, union i2c_smbus_data *data);
+
+This is the generic SMBus function. All functions below are implemented
+in terms of it. Never use this function directly!
+
+::
+
+ s32 i2c_smbus_read_byte(struct i2c_client *client);
+ s32 i2c_smbus_write_byte(struct i2c_client *client, u8 value);
+ s32 i2c_smbus_read_byte_data(struct i2c_client *client, u8 command);
+ s32 i2c_smbus_write_byte_data(struct i2c_client *client,
+ u8 command, u8 value);
+ s32 i2c_smbus_read_word_data(struct i2c_client *client, u8 command);
+ s32 i2c_smbus_write_word_data(struct i2c_client *client,
+ u8 command, u16 value);
+ s32 i2c_smbus_read_block_data(struct i2c_client *client,
+ u8 command, u8 *values);
+ s32 i2c_smbus_write_block_data(struct i2c_client *client,
+ u8 command, u8 length, const u8 *values);
+ s32 i2c_smbus_read_i2c_block_data(struct i2c_client *client,
+ u8 command, u8 length, u8 *values);
+ s32 i2c_smbus_write_i2c_block_data(struct i2c_client *client,
+ u8 command, u8 length,
+ const u8 *values);
+
+These ones were removed from i2c-core because they had no users, but could
+be added back later if needed::
+
+ s32 i2c_smbus_write_quick(struct i2c_client *client, u8 value);
+ s32 i2c_smbus_process_call(struct i2c_client *client,
+ u8 command, u16 value);
+ s32 i2c_smbus_block_process_call(struct i2c_client *client,
+ u8 command, u8 length, u8 *values);
+
+All these transactions return a negative errno value on failure. The 'write'
+transactions return 0 on success; the 'read' transactions return the read
+value, except for block transactions, which return the number of values
+read. The block buffers need not be longer than 32 bytes.
+
+You can read the file ``smbus-protocol`` for more information about the
+actual SMBus protocol.
+
+
+General purpose routines
+========================
+
+Below all general purpose routines are listed, that were not mentioned
+before::
+
+ /* Return the adapter number for a specific adapter */
+ int i2c_adapter_id(struct i2c_adapter *adap);
diff --git a/Documentation/index.rst b/Documentation/index.rst
index 2df5a3d..b843e31 100644
--- a/Documentation/index.rst
+++ b/Documentation/index.rst
@@ -104,7 +104,9 @@
fb/index
fpga/index
hid/index
+ i2c/index
iio/index
+ isdn/index
infiniband/index
leds/index
media/index
@@ -114,8 +116,10 @@
power/index
target/index
timers/index
+ spi/index
+ w1/index
watchdog/index
- virtual/index
+ virt/index
input/index
hwmon/index
gpu/index
@@ -140,11 +144,14 @@
.. toctree::
:maxdepth: 2
- sh/index
arm/index
arm64/index
ia64/index
m68k/index
+ mips/index
+ nios2/nios2
+ openrisc/index
+ parisc/index
powerpc/index
riscv/index
s390/index
diff --git a/Documentation/infiniband/core_locking.rst b/Documentation/infiniband/core_locking.rst
index f34669b..8f76a8a 100644
--- a/Documentation/infiniband/core_locking.rst
+++ b/Documentation/infiniband/core_locking.rst
@@ -29,10 +29,10 @@
The corresponding functions exported to upper level protocol
consumers:
- - ib_create_ah
- - ib_modify_ah
- - ib_query_ah
- - ib_destroy_ah
+ - rdma_create_ah
+ - rdma_modify_ah
+ - rdma_query_ah
+ - rdma_destroy_ah
- ib_post_send
- ib_post_recv
- ib_req_notify_cq
diff --git a/Documentation/input/multi-touch-protocol.rst b/Documentation/input/multi-touch-protocol.rst
index 6be7034..307fe22 100644
--- a/Documentation/input/multi-touch-protocol.rst
+++ b/Documentation/input/multi-touch-protocol.rst
@@ -23,7 +23,7 @@
describes how to send updates for individual contacts via event slots.
.. note::
- MT potocol type A is obsolete, all kernel drivers have been
+ MT protocol type A is obsolete, all kernel drivers have been
converted to use type B.
Protocol Usage
diff --git a/Documentation/ioctl/ioctl-number.rst b/Documentation/ioctl/ioctl-number.rst
index 7f8dcae..bef79cd 100644
--- a/Documentation/ioctl/ioctl-number.rst
+++ b/Documentation/ioctl/ioctl-number.rst
@@ -233,6 +233,7 @@
'f' 00-0F fs/ext4/ext4.h conflict!
'f' 00-0F linux/fs.h conflict!
'f' 00-0F fs/ocfs2/ocfs2_fs.h conflict!
+'f' 81-8F linux/fsverity.h
'g' 00-0F linux/usb/gadgetfs.h
'g' 20-2F linux/usb/g_printer.h
'h' 00-7F conflict! Charon filesystem
diff --git a/Documentation/isdn/CREDITS b/Documentation/isdn/CREDITS
deleted file mode 100644
index c1679e9..0000000
--- a/Documentation/isdn/CREDITS
+++ /dev/null
@@ -1,70 +0,0 @@
-
-I want to thank all who contributed to this project and especially to:
-(in alphabetical order)
-
-Thomas Bogendörfer (tsbogend@bigbug.franken.de)
- Tester, lots of bugfixes and hints.
-
-Alan Cox (alan@lxorguk.ukuu.org.uk)
- For help getting into standard-kernel.
-
-Henner Eisen (eis@baty.hanse.de)
- For X.25 implementation.
-
-Volker Götz (volker@oops.franken.de)
- For contribution of man-pages, the imontty-tool and a perfect
- maintaining of the mailing-list at hub-wue.
-
-Matthias Hessler (hessler@isdn4linux.de)
- For creating and maintaining the FAQ.
-
-Bernhard Hailer (Bernhard.Hailer@lrz.uni-muenchen.de)
- For creating the FAQ, and the leafsite HOWTO.
-
-Michael 'Ghandi' Herold (michael@abadonna.franken.de)
- For contribution of the vbox answering machine.
-
-Michael Hipp (Michael.Hipp@student.uni-tuebingen.de)
- For his Sync-PPP-code.
-
-Karsten Keil (keil@isdn4linux.de)
- For adding 1TR6-support to the Teles-driver.
- For the HiSax-driver.
-
-Michael Knigge (knick@cove.han.de)
- For contributing the imon-tool
-
-Andreas Kool (akool@Kool.f.EUnet.de)
- For contribution of the isdnlog/isdnrep-tool
-
-Pedro Roque Marques (roque@di.fc.ul.pt)
- For lot of new ideas and the pcbit driver.
-
-Eberhard Mönkeberg (emoenke@gwdg.de)
- For testing and help to get into kernel.
-
-Thomas Neumann (tn@ruhr.de)
- For help with Cisco-SLARP and keepalive
-
-Jan den Ouden (denouden@groovin.xs4all.nl)
- For contribution of the original teles-driver
-
-Carsten Paeth (calle@calle.in-berlin.de)
- For the AVM-B1-CAPI2.0 driver
-
-Thomas Pfeiffer (pfeiffer@pds.de)
- For V.110, extended T.70 and Hylafax extensions in isdn_tty.c
-
-Max Riegel (riegel@max.franken.de)
- For making the ICN hardware-documentation and test-equipment available.
-
-Armin Schindler (mac@melware.de)
- For the eicon active card driver.
-
-Gerhard 'Fido' Schneider (fido@wuff.mayn.de)
- For heavy-duty-beta-testing with his BBS ;)
-
-Thomas Uhl (uhl@think.de)
- For distributing the cards.
- For pushing me to work ;-)
-
diff --git a/Documentation/isdn/INTERFACE.CAPI b/Documentation/isdn/INTERFACE.CAPI
deleted file mode 100644
index 021aa9c..0000000
--- a/Documentation/isdn/INTERFACE.CAPI
+++ /dev/null
@@ -1,355 +0,0 @@
-Kernel CAPI Interface to Hardware Drivers
------------------------------------------
-
-1. Overview
-
-From the CAPI 2.0 specification:
-COMMON-ISDN-API (CAPI) is an application programming interface standard used
-to access ISDN equipment connected to basic rate interfaces (BRI) and primary
-rate interfaces (PRI).
-
-Kernel CAPI operates as a dispatching layer between CAPI applications and CAPI
-hardware drivers. Hardware drivers register ISDN devices (controllers, in CAPI
-lingo) with Kernel CAPI to indicate their readiness to provide their service
-to CAPI applications. CAPI applications also register with Kernel CAPI,
-requesting association with a CAPI device. Kernel CAPI then dispatches the
-application registration to an available device, forwarding it to the
-corresponding hardware driver. Kernel CAPI then forwards CAPI messages in both
-directions between the application and the hardware driver.
-
-Format and semantics of CAPI messages are specified in the CAPI 2.0 standard.
-This standard is freely available from https://www.capi.org.
-
-
-2. Driver and Device Registration
-
-CAPI drivers optionally register themselves with Kernel CAPI by calling the
-Kernel CAPI function register_capi_driver() with a pointer to a struct
-capi_driver. This structure must be filled with the name and revision of the
-driver, and optionally a pointer to a callback function, add_card(). The
-registration can be revoked by calling the function unregister_capi_driver()
-with a pointer to the same struct capi_driver.
-
-CAPI drivers must register each of the ISDN devices they control with Kernel
-CAPI by calling the Kernel CAPI function attach_capi_ctr() with a pointer to a
-struct capi_ctr before they can be used. This structure must be filled with
-the names of the driver and controller, and a number of callback function
-pointers which are subsequently used by Kernel CAPI for communicating with the
-driver. The registration can be revoked by calling the function
-detach_capi_ctr() with a pointer to the same struct capi_ctr.
-
-Before the device can be actually used, the driver must fill in the device
-information fields 'manu', 'version', 'profile' and 'serial' in the capi_ctr
-structure of the device, and signal its readiness by calling capi_ctr_ready().
-From then on, Kernel CAPI may call the registered callback functions for the
-device.
-
-If the device becomes unusable for any reason (shutdown, disconnect ...), the
-driver has to call capi_ctr_down(). This will prevent further calls to the
-callback functions by Kernel CAPI.
-
-
-3. Application Registration and Communication
-
-Kernel CAPI forwards registration requests from applications (calls to CAPI
-operation CAPI_REGISTER) to an appropriate hardware driver by calling its
-register_appl() callback function. A unique Application ID (ApplID, u16) is
-allocated by Kernel CAPI and passed to register_appl() along with the
-parameter structure provided by the application. This is analogous to the
-open() operation on regular files or character devices.
-
-After a successful return from register_appl(), CAPI messages from the
-application may be passed to the driver for the device via calls to the
-send_message() callback function. Conversely, the driver may call Kernel
-CAPI's capi_ctr_handle_message() function to pass a received CAPI message to
-Kernel CAPI for forwarding to an application, specifying its ApplID.
-
-Deregistration requests (CAPI operation CAPI_RELEASE) from applications are
-forwarded as calls to the release_appl() callback function, passing the same
-ApplID as with register_appl(). After return from release_appl(), no CAPI
-messages for that application may be passed to or from the device anymore.
-
-
-4. Data Structures
-
-4.1 struct capi_driver
-
-This structure describes a Kernel CAPI driver itself. It is used in the
-register_capi_driver() and unregister_capi_driver() functions, and contains
-the following non-private fields, all to be set by the driver before calling
-register_capi_driver():
-
-char name[32]
- the name of the driver, as a zero-terminated ASCII string
-char revision[32]
- the revision number of the driver, as a zero-terminated ASCII string
-int (*add_card)(struct capi_driver *driver, capicardparams *data)
- a callback function pointer (may be NULL)
-
-
-4.2 struct capi_ctr
-
-This structure describes an ISDN device (controller) handled by a Kernel CAPI
-driver. After registration via the attach_capi_ctr() function it is passed to
-all controller specific lower layer interface and callback functions to
-identify the controller to operate on.
-
-It contains the following non-private fields:
-
-- to be set by the driver before calling attach_capi_ctr():
-
-struct module *owner
- pointer to the driver module owning the device
-
-void *driverdata
- an opaque pointer to driver specific data, not touched by Kernel CAPI
-
-char name[32]
- the name of the controller, as a zero-terminated ASCII string
-
-char *driver_name
- the name of the driver, as a zero-terminated ASCII string
-
-int (*load_firmware)(struct capi_ctr *ctrlr, capiloaddata *ldata)
- (optional) pointer to a callback function for sending firmware and
- configuration data to the device
- The function may return before the operation has completed.
- Completion must be signalled by a call to capi_ctr_ready().
- Return value: 0 on success, error code on error
- Called in process context.
-
-void (*reset_ctr)(struct capi_ctr *ctrlr)
- (optional) pointer to a callback function for stopping the device,
- releasing all registered applications
- The function may return before the operation has completed.
- Completion must be signalled by a call to capi_ctr_down().
- Called in process context.
-
-void (*register_appl)(struct capi_ctr *ctrlr, u16 applid,
- capi_register_params *rparam)
-void (*release_appl)(struct capi_ctr *ctrlr, u16 applid)
- pointers to callback functions for registration and deregistration of
- applications with the device
- Calls to these functions are serialized by Kernel CAPI so that only
- one call to any of them is active at any time.
-
-u16 (*send_message)(struct capi_ctr *ctrlr, struct sk_buff *skb)
- pointer to a callback function for sending a CAPI message to the
- device
- Return value: CAPI error code
- If the method returns 0 (CAPI_NOERROR) the driver has taken ownership
- of the skb and the caller may no longer access it. If it returns a
- non-zero (error) value then ownership of the skb returns to the caller
- who may reuse or free it.
- The return value should only be used to signal problems with respect
- to accepting or queueing the message. Errors occurring during the
- actual processing of the message should be signaled with an
- appropriate reply message.
- May be called in process or interrupt context.
- Calls to this function are not serialized by Kernel CAPI, ie. it must
- be prepared to be re-entered.
-
-char *(*procinfo)(struct capi_ctr *ctrlr)
- pointer to a callback function returning the entry for the device in
- the CAPI controller info table, /proc/capi/controller
-
-const struct file_operations *proc_fops
- pointers to callback functions for the device's proc file
- system entry, /proc/capi/controllers/<n>; pointer to the device's
- capi_ctr structure is available from struct proc_dir_entry::data
- which is available from struct inode.
-
-Note: Callback functions except send_message() are never called in interrupt
-context.
-
-- to be filled in before calling capi_ctr_ready():
-
-u8 manu[CAPI_MANUFACTURER_LEN]
- value to return for CAPI_GET_MANUFACTURER
-
-capi_version version
- value to return for CAPI_GET_VERSION
-
-capi_profile profile
- value to return for CAPI_GET_PROFILE
-
-u8 serial[CAPI_SERIAL_LEN]
- value to return for CAPI_GET_SERIAL
-
-
-4.3 SKBs
-
-CAPI messages are passed between Kernel CAPI and the driver via send_message()
-and capi_ctr_handle_message(), stored in the data portion of a socket buffer
-(skb). Each skb contains a single CAPI message coded according to the CAPI 2.0
-standard.
-
-For the data transfer messages, DATA_B3_REQ and DATA_B3_IND, the actual
-payload data immediately follows the CAPI message itself within the same skb.
-The Data and Data64 parameters are not used for processing. The Data64
-parameter may be omitted by setting the length field of the CAPI message to 22
-instead of 30.
-
-
-4.4 The _cmsg Structure
-
-(declared in <linux/isdn/capiutil.h>)
-
-The _cmsg structure stores the contents of a CAPI 2.0 message in an easily
-accessible form. It contains members for all possible CAPI 2.0 parameters,
-including subparameters of the Additional Info and B Protocol structured
-parameters, with the following exceptions:
-
-* second Calling party number (CONNECT_IND)
-
-* Data64 (DATA_B3_REQ and DATA_B3_IND)
-
-* Sending complete (subparameter of Additional Info, CONNECT_REQ and INFO_REQ)
-
-* Global Configuration (subparameter of B Protocol, CONNECT_REQ, CONNECT_RESP
- and SELECT_B_PROTOCOL_REQ)
-
-Only those parameters appearing in the message type currently being processed
-are actually used. Unused members should be set to zero.
-
-Members are named after the CAPI 2.0 standard names of the parameters they
-represent. See <linux/isdn/capiutil.h> for the exact spelling. Member data
-types are:
-
-u8 for CAPI parameters of type 'byte'
-
-u16 for CAPI parameters of type 'word'
-
-u32 for CAPI parameters of type 'dword'
-
-_cstruct for CAPI parameters of type 'struct'
- The member is a pointer to a buffer containing the parameter in
- CAPI encoding (length + content). It may also be NULL, which will
- be taken to represent an empty (zero length) parameter.
- Subparameters are stored in encoded form within the content part.
-
-_cmstruct alternative representation for CAPI parameters of type 'struct'
- (used only for the 'Additional Info' and 'B Protocol' parameters)
- The representation is a single byte containing one of the values:
- CAPI_DEFAULT: The parameter is empty/absent.
- CAPI_COMPOSE: The parameter is present.
- Subparameter values are stored individually in the corresponding
- _cmsg structure members.
-
-Functions capi_cmsg2message() and capi_message2cmsg() are provided to convert
-messages between their transport encoding described in the CAPI 2.0 standard
-and their _cmsg structure representation. Note that capi_cmsg2message() does
-not know or check the size of its destination buffer. The caller must make
-sure it is big enough to accommodate the resulting CAPI message.
-
-
-5. Lower Layer Interface Functions
-
-(declared in <linux/isdn/capilli.h>)
-
-void register_capi_driver(struct capi_driver *drvr)
-void unregister_capi_driver(struct capi_driver *drvr)
- register/unregister a driver with Kernel CAPI
-
-int attach_capi_ctr(struct capi_ctr *ctrlr)
-int detach_capi_ctr(struct capi_ctr *ctrlr)
- register/unregister a device (controller) with Kernel CAPI
-
-void capi_ctr_ready(struct capi_ctr *ctrlr)
-void capi_ctr_down(struct capi_ctr *ctrlr)
- signal controller ready/not ready
-
-void capi_ctr_suspend_output(struct capi_ctr *ctrlr)
-void capi_ctr_resume_output(struct capi_ctr *ctrlr)
- signal suspend/resume
-
-void capi_ctr_handle_message(struct capi_ctr * ctrlr, u16 applid,
- struct sk_buff *skb)
- pass a received CAPI message to Kernel CAPI
- for forwarding to the specified application
-
-
-6. Helper Functions and Macros
-
-Library functions (from <linux/isdn/capilli.h>):
-
-void capilib_new_ncci(struct list_head *head, u16 applid,
- u32 ncci, u32 winsize)
-void capilib_free_ncci(struct list_head *head, u16 applid, u32 ncci)
-void capilib_release_appl(struct list_head *head, u16 applid)
-void capilib_release(struct list_head *head)
-void capilib_data_b3_conf(struct list_head *head, u16 applid,
- u32 ncci, u16 msgid)
-u16 capilib_data_b3_req(struct list_head *head, u16 applid,
- u32 ncci, u16 msgid)
-
-
-Macros to extract/set element values from/in a CAPI message header
-(from <linux/isdn/capiutil.h>):
-
-Get Macro Set Macro Element (Type)
-
-CAPIMSG_LEN(m) CAPIMSG_SETLEN(m, len) Total Length (u16)
-CAPIMSG_APPID(m) CAPIMSG_SETAPPID(m, applid) ApplID (u16)
-CAPIMSG_COMMAND(m) CAPIMSG_SETCOMMAND(m,cmd) Command (u8)
-CAPIMSG_SUBCOMMAND(m) CAPIMSG_SETSUBCOMMAND(m, cmd) Subcommand (u8)
-CAPIMSG_CMD(m) - Command*256
- + Subcommand (u16)
-CAPIMSG_MSGID(m) CAPIMSG_SETMSGID(m, msgid) Message Number (u16)
-
-CAPIMSG_CONTROL(m) CAPIMSG_SETCONTROL(m, contr) Controller/PLCI/NCCI
- (u32)
-CAPIMSG_DATALEN(m) CAPIMSG_SETDATALEN(m, len) Data Length (u16)
-
-
-Library functions for working with _cmsg structures
-(from <linux/isdn/capiutil.h>):
-
-unsigned capi_cmsg2message(_cmsg *cmsg, u8 *msg)
- Assembles a CAPI 2.0 message from the parameters in *cmsg, storing the
- result in *msg.
-
-unsigned capi_message2cmsg(_cmsg *cmsg, u8 *msg)
- Disassembles the CAPI 2.0 message in *msg, storing the parameters in
- *cmsg.
-
-unsigned capi_cmsg_header(_cmsg *cmsg, u16 ApplId, u8 Command, u8 Subcommand,
- u16 Messagenumber, u32 Controller)
- Fills the header part and address field of the _cmsg structure *cmsg
- with the given values, zeroing the remainder of the structure so only
- parameters with non-default values need to be changed before sending
- the message.
-
-void capi_cmsg_answer(_cmsg *cmsg)
- Sets the low bit of the Subcommand field in *cmsg, thereby converting
- _REQ to _CONF and _IND to _RESP.
-
-char *capi_cmd2str(u8 Command, u8 Subcommand)
- Returns the CAPI 2.0 message name corresponding to the given command
- and subcommand values, as a static ASCII string. The return value may
- be NULL if the command/subcommand is not one of those defined in the
- CAPI 2.0 standard.
-
-
-7. Debugging
-
-The module kernelcapi has a module parameter showcapimsgs controlling some
-debugging output produced by the module. It can only be set when the module is
-loaded, via a parameter "showcapimsgs=<n>" to the modprobe command, either on
-the command line or in the configuration file.
-
-If the lowest bit of showcapimsgs is set, kernelcapi logs controller and
-application up and down events.
-
-In addition, every registered CAPI controller has an associated traceflag
-parameter controlling how CAPI messages sent from and to tha controller are
-logged. The traceflag parameter is initialized with the value of the
-showcapimsgs parameter when the controller is registered, but can later be
-changed via the MANUFACTURER_REQ command KCAPI_CMD_TRACE.
-
-If the value of traceflag is non-zero, CAPI messages are logged.
-DATA_B3 messages are only logged if the value of traceflag is > 2.
-
-If the lowest bit of traceflag is set, only the command/subcommand and message
-length are logged. Otherwise, kernelcapi logs a readable representation of
-the entire message.
diff --git a/Documentation/isdn/README.avmb1 b/Documentation/isdn/README.avmb1
deleted file mode 100644
index 9e07548..0000000
--- a/Documentation/isdn/README.avmb1
+++ /dev/null
@@ -1,187 +0,0 @@
-Driver for active AVM Controller.
-
-The driver provides a kernel capi2.0 Interface (kernelcapi) and
-on top of this a User-Level-CAPI2.0-interface (capi)
-and a driver to connect isdn4linux with CAPI2.0 (capidrv).
-The lowlevel interface can be used to implement a CAPI2.0
-also for passive cards since July 1999.
-
-The author can be reached at calle@calle.in-berlin.de.
-The command avmcapictrl is part of the isdn4k-utils.
-t4-files can be found at ftp://ftp.avm.de/cardware/b1/linux/firmware
-
-Currently supported cards:
- B1 ISA (all versions)
- B1 PCI
- T1/T1B (HEMA card)
- M1
- M2
- B1 PCMCIA
-
-Installing
-----------
-
-You need at least /dev/capi20 to load the firmware.
-
-mknod /dev/capi20 c 68 0
-mknod /dev/capi20.00 c 68 1
-mknod /dev/capi20.01 c 68 2
-.
-.
-.
-mknod /dev/capi20.19 c 68 20
-
-Running
--------
-
-To use the card you need the t4-files to download the firmware.
-AVM GmbH provides several t4-files for the different D-channel
-protocols (b1.t4 for Euro-ISDN). Install these file in /lib/isdn.
-
-if you configure as modules load the modules this way:
-
-insmod /lib/modules/current/misc/capiutil.o
-insmod /lib/modules/current/misc/b1.o
-insmod /lib/modules/current/misc/kernelcapi.o
-insmod /lib/modules/current/misc/capidrv.o
-insmod /lib/modules/current/misc/capi.o
-
-if you have an B1-PCI card load the module b1pci.o
-insmod /lib/modules/current/misc/b1pci.o
-and load the firmware with
-avmcapictrl load /lib/isdn/b1.t4 1
-
-if you have an B1-ISA card load the module b1isa.o
-and add the card by calling
-avmcapictrl add 0x150 15
-and load the firmware by calling
-avmcapictrl load /lib/isdn/b1.t4 1
-
-if you have an T1-ISA card load the module t1isa.o
-and add the card by calling
-avmcapictrl add 0x450 15 T1 0
-and load the firmware by calling
-avmcapictrl load /lib/isdn/t1.t4 1
-
-if you have an PCMCIA card (B1/M1/M2) load the module b1pcmcia.o
-before you insert the card.
-
-Leased Lines with B1
---------------------
-Init card and load firmware.
-For an D64S use "FV: 1" as phone number
-For an D64S2 use "FV: 1" and "FV: 2" for multilink
-or "FV: 1,2" to use CAPI channel bundling.
-
-/proc-Interface
------------------
-
-/proc/capi:
- dr-xr-xr-x 2 root root 0 Jul 1 14:03 .
- dr-xr-xr-x 82 root root 0 Jun 30 19:08 ..
- -r--r--r-- 1 root root 0 Jul 1 14:03 applications
- -r--r--r-- 1 root root 0 Jul 1 14:03 applstats
- -r--r--r-- 1 root root 0 Jul 1 14:03 capi20
- -r--r--r-- 1 root root 0 Jul 1 14:03 capidrv
- -r--r--r-- 1 root root 0 Jul 1 14:03 controller
- -r--r--r-- 1 root root 0 Jul 1 14:03 contrstats
- -r--r--r-- 1 root root 0 Jul 1 14:03 driver
- -r--r--r-- 1 root root 0 Jul 1 14:03 ncci
- -r--r--r-- 1 root root 0 Jul 1 14:03 users
-
-/proc/capi/applications:
- applid level3cnt datablkcnt datablklen ncci-cnt recvqueuelen
- level3cnt: capi_register parameter
- datablkcnt: capi_register parameter
- ncci-cnt: current number of nccis (connections)
- recvqueuelen: number of messages on receive queue
- for example:
-1 -2 16 2048 1 0
-2 2 7 2048 1 0
-
-/proc/capi/applstats:
- applid recvctlmsg nrecvdatamsg nsentctlmsg nsentdatamsg
- recvctlmsg: capi messages received without DATA_B3_IND
- recvdatamsg: capi DATA_B3_IND received
- sentctlmsg: capi messages sent without DATA_B3_REQ
- sentdatamsg: capi DATA_B3_REQ sent
- for example:
-1 2057 1699 1721 1699
-
-/proc/capi/capi20: statistics of capi.o (/dev/capi20)
- minor nopen nrecvdropmsg nrecvctlmsg nrecvdatamsg sentctlmsg sentdatamsg
- minor: minor device number of capi device
- nopen: number of calls to devices open
- nrecvdropmsg: capi messages dropped (messages in recvqueue in close)
- nrecvctlmsg: capi messages received without DATA_B3_IND
- nrecvdatamsg: capi DATA_B3_IND received
- nsentctlmsg: capi messages sent without DATA_B3_REQ
- nsentdatamsg: capi DATA_B3_REQ sent
-
- for example:
-1 2 18 0 16 2
-
-/proc/capi/capidrv: statistics of capidrv.o (capi messages)
- nrecvctlmsg nrecvdatamsg sentctlmsg sentdatamsg
- nrecvctlmsg: capi messages received without DATA_B3_IND
- nrecvdatamsg: capi DATA_B3_IND received
- nsentctlmsg: capi messages sent without DATA_B3_REQ
- nsentdatamsg: capi DATA_B3_REQ sent
- for example:
-2780 2226 2256 2226
-
-/proc/capi/controller:
- controller drivername state cardname controllerinfo
- for example:
-1 b1pci running b1pci-e000 B1 3.07-01 0xe000 19
-2 t1isa running t1isa-450 B1 3.07-01 0x450 11 0
-3 b1pcmcia running m2-150 B1 3.07-01 0x150 5
-
-/proc/capi/contrstats:
- controller nrecvctlmsg nrecvdatamsg sentctlmsg sentdatamsg
- nrecvctlmsg: capi messages received without DATA_B3_IND
- nrecvdatamsg: capi DATA_B3_IND received
- nsentctlmsg: capi messages sent without DATA_B3_REQ
- nsentdatamsg: capi DATA_B3_REQ sent
- for example:
-1 2845 2272 2310 2274
-2 2 0 2 0
-3 2 0 2 0
-
-/proc/capi/driver:
- drivername ncontroller
- for example:
-b1pci 1
-t1isa 1
-b1pcmcia 1
-b1isa 0
-
-/proc/capi/ncci:
- apllid ncci winsize sendwindow
- for example:
-1 0x10101 8 0
-
-/proc/capi/users: kernelmodules that use the kernelcapi.
- name
- for example:
-capidrv
-capi20
-
-Questions
----------
-Check out the FAQ (ftp.isdn4linux.de) or subscribe to the
-linux-avmb1@calle.in-berlin.de mailing list by sending
-a mail to majordomo@calle.in-berlin.de with
-subscribe linux-avmb1
-in the body.
-
-German documentation and several scripts can be found at
-ftp://ftp.avm.de/cardware/b1/linux/
-
-Bugs
-----
-If you find any please let me know.
-
-Enjoy,
-
-Carsten Paeth (calle@calle.in-berlin.de)
diff --git a/Documentation/isdn/README.gigaset b/Documentation/isdn/README.gigaset
deleted file mode 100644
index f6184b6..0000000
--- a/Documentation/isdn/README.gigaset
+++ /dev/null
@@ -1,403 +0,0 @@
-GigaSet 307x Device Driver
-==========================
-
-1. Requirements
- ------------
-1.1. Hardware
- --------
- This driver supports the connection of the Gigaset 307x/417x family of
- ISDN DECT bases via Gigaset M101 Data, Gigaset M105 Data or direct USB
- connection. The following devices are reported to be compatible:
-
- Bases:
- Siemens Gigaset 3070/3075 isdn
- Siemens Gigaset 4170/4175 isdn
- Siemens Gigaset SX205/255
- Siemens Gigaset SX353
- T-Com Sinus 45 [AB] isdn
- T-Com Sinus 721X[A] [SE]
- Vox Chicago 390 ISDN (KPN Telecom)
-
- RS232 data boxes:
- Siemens Gigaset M101 Data
- T-Com Sinus 45 Data 1
-
- USB data boxes:
- Siemens Gigaset M105 Data
- Siemens Gigaset USB Adapter DECT
- T-Com Sinus 45 Data 2
- T-Com Sinus 721 data
- Chicago 390 USB (KPN)
-
- See also http://www.erbze.info/sinus_gigaset.htm
- (archived at https://web.archive.org/web/20100717020421/http://www.erbze.info:80/sinus_gigaset.htm ) and
- http://gigaset307x.sourceforge.net/
-
- We had also reports from users of Gigaset M105 who could use the drivers
- with SX 100 and CX 100 ISDN bases (only in unimodem mode, see section 2.5.)
- If you have another device that works with our driver, please let us know.
-
- Chances of getting an USB device to work are good if the output of
- lsusb
- at the command line contains one of the following:
- ID 0681:0001
- ID 0681:0002
- ID 0681:0009
- ID 0681:0021
- ID 0681:0022
-
-1.2. Software
- --------
- The driver works with the Kernel CAPI subsystem and can be used with any
- software which is able to use CAPI 2.0 for ISDN connections (voice or data).
-
- There are some user space tools available at
- https://sourceforge.net/projects/gigaset307x/
- which provide access to additional device specific functions like SMS,
- phonebook or call journal.
-
-
-2. How to use the driver
- ---------------------
-2.1. Modules
- -------
- For the devices to work, the proper kernel modules have to be loaded.
- This normally happens automatically when the system detects the USB
- device (base, M105) or when the line discipline is attached (M101). It
- can also be triggered manually using the modprobe(8) command, for example
- for troubleshooting or to pass module parameters.
-
- The module ser_gigaset provides a serial line discipline N_GIGASET_M101
- which uses the regular serial port driver to access the device, and must
- therefore be attached to the serial device to which the M101 is connected.
- The ldattach(8) command (included in util-linux-ng release 2.14 or later)
- can be used for that purpose, for example:
- ldattach GIGASET_M101 /dev/ttyS1
- This will open the device file, attach the line discipline to it, and
- then sleep in the background, keeping the device open so that the line
- discipline remains active. To deactivate it, kill the daemon, for example
- with
- killall ldattach
- before disconnecting the device. To have this happen automatically at
- system startup/shutdown on an LSB compatible system, create and activate
- an appropriate LSB startup script /etc/init.d/gigaset. (The init name
- 'gigaset' is officially assigned to this project by LANANA.)
- Alternatively, just add the 'ldattach' command line to /etc/rc.local.
-
- The modules accept the following parameters:
-
- Module Parameter Meaning
-
- gigaset debug debug level (see section 3.2.)
-
- startmode initial operation mode (see section 2.5.):
- bas_gigaset ) 1=CAPI (default), 0=Unimodem
- ser_gigaset )
- usb_gigaset ) cidmode initial Call-ID mode setting (see section
- 2.5.): 1=on (default), 0=off
-
- Depending on your distribution you may want to create a separate module
- configuration file like /etc/modprobe.d/gigaset.conf for these.
-
-2.2. Device nodes for user space programs
- ------------------------------------
- The device can be accessed from user space (eg. by the user space tools
- mentioned in 1.2.) through the device nodes:
-
- - /dev/ttyGS0 for M101 (RS232 data boxes)
- - /dev/ttyGU0 for M105 (USB data boxes)
- - /dev/ttyGB0 for the base driver (direct USB connection)
-
- If you connect more than one device of a type, they will get consecutive
- device nodes, eg. /dev/ttyGU1 for a second M105.
-
- You can also set a "default device" for the user space tools to use when
- no device node is given as parameter, by creating a symlink /dev/ttyG to
- one of them, eg.:
-
- ln -s /dev/ttyGB0 /dev/ttyG
-
- The devices accept the following device specific ioctl calls
- (defined in gigaset_dev.h):
-
- ioctl(int fd, GIGASET_REDIR, int *cmd);
- If cmd==1, the device is set to be controlled exclusively through the
- character device node; access from the ISDN subsystem is blocked.
- If cmd==0, the device is set to be used from the ISDN subsystem and does
- not communicate through the character device node.
-
- ioctl(int fd, GIGASET_CONFIG, int *cmd);
- (ser_gigaset and usb_gigaset only)
- If cmd==1, the device is set to adapter configuration mode where commands
- are interpreted by the M10x DECT adapter itself instead of being
- forwarded to the base station. In this mode, the device accepts the
- commands described in Siemens document "AT-Kommando Alignment M10x Data"
- for setting the operation mode, associating with a base station and
- querying parameters like field strengh and signal quality.
- Note that there is no ioctl command for leaving adapter configuration
- mode and returning to regular operation. In order to leave adapter
- configuration mode, write the command ATO to the device.
-
- ioctl(int fd, GIGASET_BRKCHARS, unsigned char brkchars[6]);
- (usb_gigaset only)
- Set the break characters on an M105's internal serial adapter to the six
- bytes stored in brkchars[]. Unused bytes should be set to zero.
-
- ioctl(int fd, GIGASET_VERSION, unsigned version[4]);
- Retrieve version information from the driver. version[0] must be set to
- one of:
- - GIGVER_DRIVER: retrieve driver version
- - GIGVER_COMPAT: retrieve interface compatibility version
- - GIGVER_FWBASE: retrieve the firmware version of the base
- Upon return, version[] is filled with the requested version information.
-
-2.3. CAPI
- ----
- The devices will show up as CAPI controllers as soon as the
- corresponding driver module is loaded, and can then be used with
- CAPI 2.0 kernel and user space applications. For user space access,
- the module capi.ko must be loaded.
-
- Most distributions handle loading and unloading of the various CAPI
- modules automatically via the command capiinit(1) from the capi4k-utils
- package or a similar mechanism. Note that capiinit(1) cannot unload the
- Gigaset drivers because it doesn't support more than one module per
- driver.
-
-2.5. Unimodem mode
- -------------
- In this mode the device works like a modem connected to a serial port
- (the /dev/ttyGU0, ... mentioned above) which understands the commands
-
- ATZ init, reset
- => OK or ERROR
- ATD
- ATDT dial
- => OK, CONNECT,
- BUSY,
- NO DIAL TONE,
- NO CARRIER,
- NO ANSWER
- <pause>+++<pause> change to command mode when connected
- ATH hangup
-
- You can use some configuration tool of your distribution to configure this
- "modem" or configure pppd/wvdial manually. There are some example ppp
- configuration files and chat scripts in the gigaset-VERSION/ppp directory
- in the driver packages from https://sourceforge.net/projects/gigaset307x/.
- Please note that the USB drivers are not able to change the state of the
- control lines. This means you must use "Stupid Mode" if you are using
- wvdial or you should use the nocrtscts option of pppd.
- You must also assure that the ppp_async module is loaded with the parameter
- flag_time=0. You can do this e.g. by adding a line like
-
- options ppp_async flag_time=0
-
- to an appropriate module configuration file, like
- /etc/modprobe.d/gigaset.conf.
-
- Unimodem mode is needed for making some devices [e.g. SX100] work which
- do not support the regular Gigaset command set. If debug output (see
- section 3.2.) shows something like this when dialing:
- CMD Received: ERROR
- Available Params: 0
- Connection State: 0, Response: -1
- gigaset_process_response: resp_code -1 in ConState 0 !
- Timeout occurred
- then switching to unimodem mode may help.
-
- If you have installed the command line tool gigacontr, you can enter
- unimodem mode using
- gigacontr --mode unimodem
- You can switch back using
- gigacontr --mode isdn
-
- You can also put the driver directly into Unimodem mode when it's loaded,
- by passing the module parameter startmode=0 to the hardware specific
- module, e.g.
- modprobe usb_gigaset startmode=0
- or by adding a line like
- options usb_gigaset startmode=0
- to an appropriate module configuration file, like
- /etc/modprobe.d/gigaset.conf
-
-2.6. Call-ID (CID) mode
- ------------------
- Call-IDs are numbers used to tag commands to, and responses from, the
- Gigaset base in order to support the simultaneous handling of multiple
- ISDN calls. Their use can be enabled ("CID mode") or disabled ("Unimodem
- mode"). Without Call-IDs (in Unimodem mode), only a very limited set of
- functions is available. It allows outgoing data connections only, but
- does not signal incoming calls or other base events.
-
- DECT cordless data devices (M10x) permanently occupy the cordless
- connection to the base while Call-IDs are activated. As the Gigaset
- bases only support one DECT data connection at a time, this prevents
- other DECT cordless data devices from accessing the base.
-
- During active operation, the driver switches to the necessary mode
- automatically. However, for the reasons above, the mode chosen when
- the device is not in use (idle) can be selected by the user.
- - If you want to receive incoming calls, you can use the default
- settings (CID mode).
- - If you have several DECT data devices (M10x) which you want to use
- in turn, select Unimodem mode by passing the parameter "cidmode=0" to
- the appropriate driver module (ser_gigaset or usb_gigaset).
-
- If you want both of these at once, you are out of luck.
-
- You can also use the tty class parameter "cidmode" of the device to
- change its CID mode while the driver is loaded, eg.
- echo 0 > /sys/class/tty/ttyGU0/cidmode
-
-2.7. Dialing Numbers
- ---------------
- The called party number provided by an application for dialing out must
- be a public network number according to the local dialing plan, without
- any dial prefix for getting an outside line.
-
- Internal calls can be made by providing an internal extension number
- prefixed with "**" (two asterisks) as the called party number. So to dial
- eg. the first registered DECT handset, give "**11" as the called party
- number. Dialing "***" (three asterisks) calls all extensions
- simultaneously (global call).
-
- Unimodem mode does not support internal calls.
-
-2.8. Unregistered Wireless Devices (M101/M105)
- -----------------------------------------
- The main purpose of the ser_gigaset and usb_gigaset drivers is to allow
- the M101 and M105 wireless devices to be used as ISDN devices for ISDN
- connections through a Gigaset base. Therefore they assume that the device
- is registered to a DECT base.
-
- If the M101/M105 device is not registered to a base, initialization of
- the device fails, and a corresponding error message is logged by the
- driver. In that situation, a restricted set of functions is available
- which includes, in particular, those necessary for registering the device
- to a base or for switching it between Fixed Part and Portable Part
- modes. See the gigacontr(8) manpage for details.
-
-3. Troubleshooting
- ---------------
-3.1. Solutions to frequently reported problems
- -----------------------------------------
- Problem:
- You have a slow provider and isdn4linux gives up dialing too early.
- Solution:
- Load the isdn module using the dialtimeout option. You can do this e.g.
- by adding a line like
-
- options isdn dialtimeout=15
-
- to /etc/modprobe.d/gigaset.conf or a similar file.
-
- Problem:
- The isdnlog program emits error messages or just doesn't work.
- Solution:
- Isdnlog supports only the HiSax driver. Do not attempt to use it with
- other drivers such as Gigaset.
-
- Problem:
- You have two or more DECT data adapters (M101/M105) and only the
- first one you turn on works.
- Solution:
- Select Unimodem mode for all DECT data adapters. (see section 2.5.)
-
- Problem:
- Messages like this:
- usb_gigaset 3-2:1.0: Could not initialize the device.
- appear in your syslog.
- Solution:
- Check whether your M10x wireless device is correctly registered to the
- Gigaset base. (see section 2.7.)
-
-3.2. Telling the driver to provide more information
- ----------------------------------------------
- Building the driver with the "Gigaset debugging" kernel configuration
- option (CONFIG_GIGASET_DEBUG) gives it the ability to produce additional
- information useful for debugging.
-
- You can control the amount of debugging information the driver produces by
- writing an appropriate value to /sys/module/gigaset/parameters/debug, e.g.
- echo 0 > /sys/module/gigaset/parameters/debug
- switches off debugging output completely,
- echo 0x302020 > /sys/module/gigaset/parameters/debug
- enables a reasonable set of debugging output messages. These values are
- bit patterns where every bit controls a certain type of debugging output.
- See the constants DEBUG_* in the source file gigaset.h for details.
-
- The initial value can be set using the debug parameter when loading the
- module "gigaset", e.g. by adding a line
- options gigaset debug=0
- to your module configuration file, eg. /etc/modprobe.d/gigaset.conf
-
- Generated debugging information can be found
- - as output of the command
- dmesg
- - in system log files written by your syslog daemon, usually
- in /var/log/, e.g. /var/log/messages.
-
-3.3. Reporting problems and bugs
- ---------------------------
- If you can't solve problems with the driver on your own, feel free to
- use one of the forums, bug trackers, or mailing lists on
- https://sourceforge.net/projects/gigaset307x
- or write an electronic mail to the maintainers.
-
- Try to provide as much information as possible, such as
- - distribution
- - kernel version (uname -r)
- - gcc version (gcc --version)
- - hardware architecture (uname -m, ...)
- - type and firmware version of your device (base and wireless module,
- if any)
- - output of "lsusb -v" (if using an USB device)
- - error messages
- - relevant system log messages (it would help if you activate debug
- output as described in 3.2.)
-
- For help with general configuration problems not specific to our driver,
- such as isdn4linux and network configuration issues, please refer to the
- appropriate forums and newsgroups.
-
-3.4. Reporting problem solutions
- ---------------------------
- If you solved a problem with our drivers, wrote startup scripts for your
- distribution, ... feel free to contact us (using one of the places
- mentioned in 3.3.). We'd like to add scripts, hints, documentation
- to the driver and/or the project web page.
-
-
-4. Links, other software
- ---------------------
- - Sourceforge project developing this driver and associated tools
- https://sourceforge.net/projects/gigaset307x
- - Yahoo! Group on the Siemens Gigaset family of devices
- https://de.groups.yahoo.com/group/Siemens-Gigaset
- - Siemens Gigaset/T-Sinus compatibility table
- http://www.erbze.info/sinus_gigaset.htm
- (archived at https://web.archive.org/web/20100717020421/http://www.erbze.info:80/sinus_gigaset.htm )
-
-
-5. Credits
- -------
- Thanks to
-
- Karsten Keil
- for his help with isdn4linux
- Deti Fliegl
- for his base driver code
- Dennis Dietrich
- for his kernel 2.6 patches
- Andreas Rummel
- for his work and logs to get unimodem mode working
- Andreas Degert
- for his logs and patches to get cx 100 working
- Dietrich Feist
- for his generous donation of one M105 and two M101 cordless adapters
- Christoph Schweers
- for his generous donation of a M34 device
-
- and all the other people who sent logs and other information.
-
diff --git a/Documentation/isdn/README.hysdn b/Documentation/isdn/README.hysdn
deleted file mode 100644
index eeca11f..0000000
--- a/Documentation/isdn/README.hysdn
+++ /dev/null
@@ -1,195 +0,0 @@
-$Id: README.hysdn,v 1.3.6.1 2001/02/10 14:41:19 kai Exp $
-The hysdn driver has been written by
-Werner Cornelius (werner@isdn4linux.de or werner@titro.de)
-for Hypercope GmbH Aachen Germany. Hypercope agreed to publish this driver
-under the GNU General Public License.
-
-The CAPI 2.0-support was added by Ulrich Albrecht (ualbrecht@hypercope.de)
-for Hypercope GmbH Aachen, Germany.
-
-
- 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; either version 2 of the License, or
- (at your option) any later version.
-
- 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.
-
- 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.
-
-Table of contents
-=================
-
-1. About the driver
-
-2. Loading/Unloading the driver
-
-3. Entries in the /proc filesystem
-
-4. The /proc/net/hysdn/cardconfX file
-
-5. The /proc/net/hysdn/cardlogX file
-
-6. Where to get additional info and help
-
-
-1. About the driver
-
- The drivers/isdn/hysdn subdir contains a driver for HYPERCOPEs active
- PCI isdn cards Champ, Ergo and Metro. To enable support for this cards
- enable ISDN support in the kernel config and support for HYSDN cards in
- the active cards submenu. The driver may only be compiled and used if
- support for loadable modules and the process filesystem have been enabled.
-
- These cards provide two different interfaces to the kernel. Without the
- optional CAPI 2.0 support, they register as ethernet card. IP-routing
- to a ISDN-destination is performed on the card itself. All necessary
- handlers for various protocols like ppp and others as well as config info
- and firmware may be fetched from Hypercopes WWW-Site www.hypercope.de.
-
- With CAPI 2.0 support enabled, the card can also be used as a CAPI 2.0
- compliant devices with either CAPI 2.0 applications
- (check isdn4k-utils) or -using the capidrv module- as a regular
- isdn4linux device. This is done via the same mechanism as with the
- active AVM cards and in fact uses the same module.
-
-
-2. Loading/Unloading the driver
-
- The module has no command line parameters and auto detects up to 10 cards
- in the id-range 0-9.
- If a loaded driver shall be unloaded all open files in the /proc/net/hysdn
- subdir need to be closed and all ethernet interfaces allocated by this
- driver must be shut down. Otherwise the module counter will avoid a module
- unload.
-
- If you are using the CAPI 2.0-interface, make sure to load/modprobe the
- kernelcapi-module first.
-
- If you plan to use the capidrv-link to isdn4linux, make sure to load
- capidrv.o after all modules using this driver (i.e. after hysdn and
- any avm-specific modules).
-
-3. Entries in the /proc filesystem
-
- When the module has been loaded it adds the directory hysdn in the
- /proc/net tree. This directory contains exactly 2 file entries for each
- card. One is called cardconfX and the other cardlogX, where X is the
- card id number from 0 to 9.
- The cards are numbered in the order found in the PCI config data.
-
-4. The /proc/net/hysdn/cardconfX file
-
- This file may be read to get by everyone to get info about the cards type,
- actual state, available features and used resources.
- The first 3 entries (id, bus and slot) are PCI info fields, the following
- type field gives the information about the cards type:
-
- 4 -> Ergo card (server card with 2 b-chans)
- 5 -> Metro card (server card with 4 or 8 b-chans)
- 6 -> Champ card (client card with 2 b-chans)
-
- The following 3 fields show the hardware assignments for irq, iobase and the
- dual ported memory (dp-mem).
- The fields b-chans and fax-chans announce the available card resources of
- this types for the user.
- The state variable indicates the actual drivers state for this card with the
- following assignments.
-
- 0 -> card has not been booted since driver load
- 1 -> card booting is actually in progess
- 2 -> card is in an error state due to a previous boot failure
- 3 -> card is booted and active
-
- And the last field (device) shows the name of the ethernet device assigned
- to this card. Up to the first successful boot this field only shows a -
- to tell that no net device has been allocated up to now. Once a net device
- has been allocated it remains assigned to this card, even if a card is
- rebooted and an boot error occurs.
-
- Writing to the cardconfX file boots the card or transfers config lines to
- the cards firmware. The type of data is automatically detected when the
- first data is written. Only root has write access to this file.
- The firmware boot files are normally called hyclient.pof for client cards
- and hyserver.pof for server cards.
- After successfully writing the boot file, complete config files or single
- config lines may be copied to this file.
- If an error occurs the return value given to the writing process has the
- following additional codes (decimal):
-
- 1000 Another process is currently bootng the card
- 1001 Invalid firmware header
- 1002 Boards dual-port RAM test failed
- 1003 Internal firmware handler error
- 1004 Boot image size invalid
- 1005 First boot stage (bootstrap loader) failed
- 1006 Second boot stage failure
- 1007 Timeout waiting for card ready during boot
- 1008 Operation only allowed in booted state
- 1009 Config line too long
- 1010 Invalid channel number
- 1011 Timeout sending config data
-
- Additional info about error reasons may be fetched from the log output.
-
-5. The /proc/net/hysdn/cardlogX file
-
- The cardlogX file entry may be opened multiple for reading by everyone to
- get the cards and drivers log data. Card messages always start with the
- keyword LOG. All other lines are output from the driver.
- The driver log data may be redirected to the syslog by selecting the
- appropriate bitmask. The cards log messages will always be send to this
- interface but never to the syslog.
-
- A root user may write a decimal or hex (with 0x) value t this file to select
- desired output options. As mentioned above the cards log dat is always
- written to the cardlog file independent of the following options only used
- to check and debug the driver itself:
-
- For example:
- echo "0x34560078" > /proc/net/hysdn/cardlog0
- to output the hex log mask 34560078 for card 0.
-
- The written value is regarded as an unsigned 32-Bit value, bit ored for
- desired output. The following bits are already assigned:
-
- 0x80000000 All driver log data is alternatively via syslog
- 0x00000001 Log memory allocation errors
- 0x00000010 Firmware load start and close are logged
- 0x00000020 Log firmware record parser
- 0x00000040 Log every firmware write actions
- 0x00000080 Log all card related boot messages
- 0x00000100 Output all config data sent for debugging purposes
- 0x00000200 Only non comment config lines are shown wth channel
- 0x00000400 Additional conf log output
- 0x00001000 Log the asynchronous scheduler actions (config and log)
- 0x00100000 Log all open and close actions to /proc/net/hysdn/card files
- 0x00200000 Log all actions from /proc file entries
- 0x00010000 Log network interface init and deinit
-
-6. Where to get additional info and help
-
- If you have any problems concerning the driver or configuration contact
- the Hypercope support team (support@hypercope.de) and or the authors
- Werner Cornelius (werner@isdn4linux or cornelius@titro.de) or
- Ulrich Albrecht (ualbrecht@hypercope.de).
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
diff --git a/Documentation/isdn/README.mISDN b/Documentation/isdn/README.mISDN
deleted file mode 100644
index cd8bf92..0000000
--- a/Documentation/isdn/README.mISDN
+++ /dev/null
@@ -1,6 +0,0 @@
-mISDN is a new modular ISDN driver, in the long term it should replace
-the old I4L driver architecture for passiv ISDN cards.
-It was designed to allow a broad range of applications and interfaces
-but only have the basic function in kernel, the interface to the user
-space is based on sockets with a own address family AF_ISDN.
-
diff --git a/Documentation/isdn/avmb1.rst b/Documentation/isdn/avmb1.rst
new file mode 100644
index 0000000..de3961e
--- /dev/null
+++ b/Documentation/isdn/avmb1.rst
@@ -0,0 +1,246 @@
+================================
+Driver for active AVM Controller
+================================
+
+The driver provides a kernel capi2.0 Interface (kernelcapi) and
+on top of this a User-Level-CAPI2.0-interface (capi)
+and a driver to connect isdn4linux with CAPI2.0 (capidrv).
+The lowlevel interface can be used to implement a CAPI2.0
+also for passive cards since July 1999.
+
+The author can be reached at calle@calle.in-berlin.de.
+The command avmcapictrl is part of the isdn4k-utils.
+t4-files can be found at ftp://ftp.avm.de/cardware/b1/linux/firmware
+
+Currently supported cards:
+
+ - B1 ISA (all versions)
+ - B1 PCI
+ - T1/T1B (HEMA card)
+ - M1
+ - M2
+ - B1 PCMCIA
+
+Installing
+----------
+
+You need at least /dev/capi20 to load the firmware.
+
+::
+
+ mknod /dev/capi20 c 68 0
+ mknod /dev/capi20.00 c 68 1
+ mknod /dev/capi20.01 c 68 2
+ .
+ .
+ .
+ mknod /dev/capi20.19 c 68 20
+
+Running
+-------
+
+To use the card you need the t4-files to download the firmware.
+AVM GmbH provides several t4-files for the different D-channel
+protocols (b1.t4 for Euro-ISDN). Install these file in /lib/isdn.
+
+if you configure as modules load the modules this way::
+
+ insmod /lib/modules/current/misc/capiutil.o
+ insmod /lib/modules/current/misc/b1.o
+ insmod /lib/modules/current/misc/kernelcapi.o
+ insmod /lib/modules/current/misc/capidrv.o
+ insmod /lib/modules/current/misc/capi.o
+
+if you have an B1-PCI card load the module b1pci.o::
+
+ insmod /lib/modules/current/misc/b1pci.o
+
+and load the firmware with::
+
+ avmcapictrl load /lib/isdn/b1.t4 1
+
+if you have an B1-ISA card load the module b1isa.o
+and add the card by calling::
+
+ avmcapictrl add 0x150 15
+
+and load the firmware by calling::
+
+ avmcapictrl load /lib/isdn/b1.t4 1
+
+if you have an T1-ISA card load the module t1isa.o
+and add the card by calling::
+
+ avmcapictrl add 0x450 15 T1 0
+
+and load the firmware by calling::
+
+ avmcapictrl load /lib/isdn/t1.t4 1
+
+if you have an PCMCIA card (B1/M1/M2) load the module b1pcmcia.o
+before you insert the card.
+
+Leased Lines with B1
+--------------------
+
+Init card and load firmware.
+
+For an D64S use "FV: 1" as phone number
+
+For an D64S2 use "FV: 1" and "FV: 2" for multilink
+or "FV: 1,2" to use CAPI channel bundling.
+
+/proc-Interface
+-----------------
+
+/proc/capi::
+
+ dr-xr-xr-x 2 root root 0 Jul 1 14:03 .
+ dr-xr-xr-x 82 root root 0 Jun 30 19:08 ..
+ -r--r--r-- 1 root root 0 Jul 1 14:03 applications
+ -r--r--r-- 1 root root 0 Jul 1 14:03 applstats
+ -r--r--r-- 1 root root 0 Jul 1 14:03 capi20
+ -r--r--r-- 1 root root 0 Jul 1 14:03 capidrv
+ -r--r--r-- 1 root root 0 Jul 1 14:03 controller
+ -r--r--r-- 1 root root 0 Jul 1 14:03 contrstats
+ -r--r--r-- 1 root root 0 Jul 1 14:03 driver
+ -r--r--r-- 1 root root 0 Jul 1 14:03 ncci
+ -r--r--r-- 1 root root 0 Jul 1 14:03 users
+
+/proc/capi/applications:
+ applid level3cnt datablkcnt datablklen ncci-cnt recvqueuelen
+ level3cnt:
+ capi_register parameter
+ datablkcnt:
+ capi_register parameter
+ ncci-cnt:
+ current number of nccis (connections)
+ recvqueuelen:
+ number of messages on receive queue
+
+ for example::
+
+ 1 -2 16 2048 1 0
+ 2 2 7 2048 1 0
+
+/proc/capi/applstats:
+ applid recvctlmsg nrecvdatamsg nsentctlmsg nsentdatamsg
+ recvctlmsg:
+ capi messages received without DATA_B3_IND
+ recvdatamsg:
+ capi DATA_B3_IND received
+ sentctlmsg:
+ capi messages sent without DATA_B3_REQ
+ sentdatamsg:
+ capi DATA_B3_REQ sent
+
+ for example::
+
+ 1 2057 1699 1721 1699
+
+/proc/capi/capi20: statistics of capi.o (/dev/capi20)
+ minor nopen nrecvdropmsg nrecvctlmsg nrecvdatamsg sentctlmsg sentdatamsg
+ minor:
+ minor device number of capi device
+ nopen:
+ number of calls to devices open
+ nrecvdropmsg:
+ capi messages dropped (messages in recvqueue in close)
+ nrecvctlmsg:
+ capi messages received without DATA_B3_IND
+ nrecvdatamsg:
+ capi DATA_B3_IND received
+ nsentctlmsg:
+ capi messages sent without DATA_B3_REQ
+ nsentdatamsg:
+ capi DATA_B3_REQ sent
+
+ for example::
+
+ 1 2 18 0 16 2
+
+/proc/capi/capidrv: statistics of capidrv.o (capi messages)
+ nrecvctlmsg nrecvdatamsg sentctlmsg sentdatamsg
+ nrecvctlmsg:
+ capi messages received without DATA_B3_IND
+ nrecvdatamsg:
+ capi DATA_B3_IND received
+ nsentctlmsg:
+ capi messages sent without DATA_B3_REQ
+ nsentdatamsg:
+ capi DATA_B3_REQ sent
+
+ for example:
+ 2780 2226 2256 2226
+
+/proc/capi/controller:
+ controller drivername state cardname controllerinfo
+
+ for example::
+
+ 1 b1pci running b1pci-e000 B1 3.07-01 0xe000 19
+ 2 t1isa running t1isa-450 B1 3.07-01 0x450 11 0
+ 3 b1pcmcia running m2-150 B1 3.07-01 0x150 5
+
+/proc/capi/contrstats:
+ controller nrecvctlmsg nrecvdatamsg sentctlmsg sentdatamsg
+ nrecvctlmsg:
+ capi messages received without DATA_B3_IND
+ nrecvdatamsg:
+ capi DATA_B3_IND received
+ nsentctlmsg:
+ capi messages sent without DATA_B3_REQ
+ nsentdatamsg:
+ capi DATA_B3_REQ sent
+
+ for example::
+
+ 1 2845 2272 2310 2274
+ 2 2 0 2 0
+ 3 2 0 2 0
+
+/proc/capi/driver:
+ drivername ncontroller
+
+ for example::
+
+ b1pci 1
+ t1isa 1
+ b1pcmcia 1
+ b1isa 0
+
+/proc/capi/ncci:
+ apllid ncci winsize sendwindow
+
+ for example::
+
+ 1 0x10101 8 0
+
+/proc/capi/users: kernelmodules that use the kernelcapi.
+ name
+
+ for example::
+
+ capidrv
+ capi20
+
+Questions
+---------
+
+Check out the FAQ (ftp.isdn4linux.de) or subscribe to the
+linux-avmb1@calle.in-berlin.de mailing list by sending
+a mail to majordomo@calle.in-berlin.de with
+subscribe linux-avmb1
+in the body.
+
+German documentation and several scripts can be found at
+ftp://ftp.avm.de/cardware/b1/linux/
+
+Bugs
+----
+
+If you find any please let me know.
+
+Enjoy,
+
+Carsten Paeth (calle@calle.in-berlin.de)
diff --git a/Documentation/isdn/credits.rst b/Documentation/isdn/credits.rst
new file mode 100644
index 0000000..319323f
--- /dev/null
+++ b/Documentation/isdn/credits.rst
@@ -0,0 +1,73 @@
+=======
+Credits
+=======
+
+
+I want to thank all who contributed to this project and especially to:
+(in alphabetical order)
+
+Thomas Bogendörfer (tsbogend@bigbug.franken.de)
+ Tester, lots of bugfixes and hints.
+
+Alan Cox (alan@lxorguk.ukuu.org.uk)
+ For help getting into standard-kernel.
+
+Henner Eisen (eis@baty.hanse.de)
+ For X.25 implementation.
+
+Volker Götz (volker@oops.franken.de)
+ For contribution of man-pages, the imontty-tool and a perfect
+ maintaining of the mailing-list at hub-wue.
+
+Matthias Hessler (hessler@isdn4linux.de)
+ For creating and maintaining the FAQ.
+
+Bernhard Hailer (Bernhard.Hailer@lrz.uni-muenchen.de)
+ For creating the FAQ, and the leafsite HOWTO.
+
+Michael 'Ghandi' Herold (michael@abadonna.franken.de)
+ For contribution of the vbox answering machine.
+
+Michael Hipp (Michael.Hipp@student.uni-tuebingen.de)
+ For his Sync-PPP-code.
+
+Karsten Keil (keil@isdn4linux.de)
+ For adding 1TR6-support to the Teles-driver.
+ For the HiSax-driver.
+
+Michael Knigge (knick@cove.han.de)
+ For contributing the imon-tool
+
+Andreas Kool (akool@Kool.f.EUnet.de)
+ For contribution of the isdnlog/isdnrep-tool
+
+Pedro Roque Marques (roque@di.fc.ul.pt)
+ For lot of new ideas and the pcbit driver.
+
+Eberhard Mönkeberg (emoenke@gwdg.de)
+ For testing and help to get into kernel.
+
+Thomas Neumann (tn@ruhr.de)
+ For help with Cisco-SLARP and keepalive
+
+Jan den Ouden (denouden@groovin.xs4all.nl)
+ For contribution of the original teles-driver
+
+Carsten Paeth (calle@calle.in-berlin.de)
+ For the AVM-B1-CAPI2.0 driver
+
+Thomas Pfeiffer (pfeiffer@pds.de)
+ For V.110, extended T.70 and Hylafax extensions in isdn_tty.c
+
+Max Riegel (riegel@max.franken.de)
+ For making the ICN hardware-documentation and test-equipment available.
+
+Armin Schindler (mac@melware.de)
+ For the eicon active card driver.
+
+Gerhard 'Fido' Schneider (fido@wuff.mayn.de)
+ For heavy-duty-beta-testing with his BBS ;)
+
+Thomas Uhl (uhl@think.de)
+ For distributing the cards.
+ For pushing me to work ;-)
diff --git a/Documentation/isdn/gigaset.rst b/Documentation/isdn/gigaset.rst
new file mode 100644
index 0000000..98b4ec5
--- /dev/null
+++ b/Documentation/isdn/gigaset.rst
@@ -0,0 +1,465 @@
+==========================
+GigaSet 307x Device Driver
+==========================
+
+1. Requirements
+=================
+
+1.1. Hardware
+-------------
+
+ This driver supports the connection of the Gigaset 307x/417x family of
+ ISDN DECT bases via Gigaset M101 Data, Gigaset M105 Data or direct USB
+ connection. The following devices are reported to be compatible:
+
+ Bases:
+ - Siemens Gigaset 3070/3075 isdn
+ - Siemens Gigaset 4170/4175 isdn
+ - Siemens Gigaset SX205/255
+ - Siemens Gigaset SX353
+ - T-Com Sinus 45 [AB] isdn
+ - T-Com Sinus 721X[A] [SE]
+ - Vox Chicago 390 ISDN (KPN Telecom)
+
+ RS232 data boxes:
+ - Siemens Gigaset M101 Data
+ - T-Com Sinus 45 Data 1
+
+ USB data boxes:
+ - Siemens Gigaset M105 Data
+ - Siemens Gigaset USB Adapter DECT
+ - T-Com Sinus 45 Data 2
+ - T-Com Sinus 721 data
+ - Chicago 390 USB (KPN)
+
+ See also http://www.erbze.info/sinus_gigaset.htm
+ (archived at https://web.archive.org/web/20100717020421/http://www.erbze.info:80/sinus_gigaset.htm ) and
+ http://gigaset307x.sourceforge.net/
+
+ We had also reports from users of Gigaset M105 who could use the drivers
+ with SX 100 and CX 100 ISDN bases (only in unimodem mode, see section 2.5.)
+ If you have another device that works with our driver, please let us know.
+
+ Chances of getting an USB device to work are good if the output of::
+
+ lsusb
+
+ at the command line contains one of the following::
+
+ ID 0681:0001
+ ID 0681:0002
+ ID 0681:0009
+ ID 0681:0021
+ ID 0681:0022
+
+1.2. Software
+-------------
+
+ The driver works with the Kernel CAPI subsystem and can be used with any
+ software which is able to use CAPI 2.0 for ISDN connections (voice or data).
+
+ There are some user space tools available at
+ https://sourceforge.net/projects/gigaset307x/
+ which provide access to additional device specific functions like SMS,
+ phonebook or call journal.
+
+
+2. How to use the driver
+==========================
+
+2.1. Modules
+------------
+
+ For the devices to work, the proper kernel modules have to be loaded.
+ This normally happens automatically when the system detects the USB
+ device (base, M105) or when the line discipline is attached (M101). It
+ can also be triggered manually using the modprobe(8) command, for example
+ for troubleshooting or to pass module parameters.
+
+ The module ser_gigaset provides a serial line discipline N_GIGASET_M101
+ which uses the regular serial port driver to access the device, and must
+ therefore be attached to the serial device to which the M101 is connected.
+ The ldattach(8) command (included in util-linux-ng release 2.14 or later)
+ can be used for that purpose, for example::
+
+ ldattach GIGASET_M101 /dev/ttyS1
+
+ This will open the device file, attach the line discipline to it, and
+ then sleep in the background, keeping the device open so that the line
+ discipline remains active. To deactivate it, kill the daemon, for example
+ with::
+
+ killall ldattach
+
+ before disconnecting the device. To have this happen automatically at
+ system startup/shutdown on an LSB compatible system, create and activate
+ an appropriate LSB startup script /etc/init.d/gigaset. (The init name
+ 'gigaset' is officially assigned to this project by LANANA.)
+ Alternatively, just add the 'ldattach' command line to /etc/rc.local.
+
+ The modules accept the following parameters:
+
+ =============== ========== ==========================================
+ Module Parameter Meaning
+
+ gigaset debug debug level (see section 3.2.)
+
+ startmode initial operation mode (see section 2.5.):
+ bas_gigaset ) 1=CAPI (default), 0=Unimodem
+ ser_gigaset )
+ usb_gigaset ) cidmode initial Call-ID mode setting (see section
+ 2.5.): 1=on (default), 0=off
+
+ =============== ========== ==========================================
+
+ Depending on your distribution you may want to create a separate module
+ configuration file like /etc/modprobe.d/gigaset.conf for these.
+
+2.2. Device nodes for user space programs
+-----------------------------------------
+
+ The device can be accessed from user space (eg. by the user space tools
+ mentioned in 1.2.) through the device nodes:
+
+ - /dev/ttyGS0 for M101 (RS232 data boxes)
+ - /dev/ttyGU0 for M105 (USB data boxes)
+ - /dev/ttyGB0 for the base driver (direct USB connection)
+
+ If you connect more than one device of a type, they will get consecutive
+ device nodes, eg. /dev/ttyGU1 for a second M105.
+
+ You can also set a "default device" for the user space tools to use when
+ no device node is given as parameter, by creating a symlink /dev/ttyG to
+ one of them, eg.::
+
+ ln -s /dev/ttyGB0 /dev/ttyG
+
+ The devices accept the following device specific ioctl calls
+ (defined in gigaset_dev.h):
+
+ ``ioctl(int fd, GIGASET_REDIR, int *cmd);``
+
+ If cmd==1, the device is set to be controlled exclusively through the
+ character device node; access from the ISDN subsystem is blocked.
+
+ If cmd==0, the device is set to be used from the ISDN subsystem and does
+ not communicate through the character device node.
+
+ ``ioctl(int fd, GIGASET_CONFIG, int *cmd);``
+
+ (ser_gigaset and usb_gigaset only)
+
+ If cmd==1, the device is set to adapter configuration mode where commands
+ are interpreted by the M10x DECT adapter itself instead of being
+ forwarded to the base station. In this mode, the device accepts the
+ commands described in Siemens document "AT-Kommando Alignment M10x Data"
+ for setting the operation mode, associating with a base station and
+ querying parameters like field strengh and signal quality.
+
+ Note that there is no ioctl command for leaving adapter configuration
+ mode and returning to regular operation. In order to leave adapter
+ configuration mode, write the command ATO to the device.
+
+ ``ioctl(int fd, GIGASET_BRKCHARS, unsigned char brkchars[6]);``
+
+ (usb_gigaset only)
+
+ Set the break characters on an M105's internal serial adapter to the six
+ bytes stored in brkchars[]. Unused bytes should be set to zero.
+
+ ioctl(int fd, GIGASET_VERSION, unsigned version[4]);
+ Retrieve version information from the driver. version[0] must be set to
+ one of:
+
+ - GIGVER_DRIVER: retrieve driver version
+ - GIGVER_COMPAT: retrieve interface compatibility version
+ - GIGVER_FWBASE: retrieve the firmware version of the base
+
+ Upon return, version[] is filled with the requested version information.
+
+2.3. CAPI
+---------
+
+ The devices will show up as CAPI controllers as soon as the
+ corresponding driver module is loaded, and can then be used with
+ CAPI 2.0 kernel and user space applications. For user space access,
+ the module capi.ko must be loaded.
+
+ Most distributions handle loading and unloading of the various CAPI
+ modules automatically via the command capiinit(1) from the capi4k-utils
+ package or a similar mechanism. Note that capiinit(1) cannot unload the
+ Gigaset drivers because it doesn't support more than one module per
+ driver.
+
+2.5. Unimodem mode
+------------------
+
+ In this mode the device works like a modem connected to a serial port
+ (the /dev/ttyGU0, ... mentioned above) which understands the commands::
+
+ ATZ init, reset
+ => OK or ERROR
+ ATD
+ ATDT dial
+ => OK, CONNECT,
+ BUSY,
+ NO DIAL TONE,
+ NO CARRIER,
+ NO ANSWER
+ <pause>+++<pause> change to command mode when connected
+ ATH hangup
+
+ You can use some configuration tool of your distribution to configure this
+ "modem" or configure pppd/wvdial manually. There are some example ppp
+ configuration files and chat scripts in the gigaset-VERSION/ppp directory
+ in the driver packages from https://sourceforge.net/projects/gigaset307x/.
+ Please note that the USB drivers are not able to change the state of the
+ control lines. This means you must use "Stupid Mode" if you are using
+ wvdial or you should use the nocrtscts option of pppd.
+ You must also assure that the ppp_async module is loaded with the parameter
+ flag_time=0. You can do this e.g. by adding a line like::
+
+ options ppp_async flag_time=0
+
+ to an appropriate module configuration file, like::
+
+ /etc/modprobe.d/gigaset.conf.
+
+ Unimodem mode is needed for making some devices [e.g. SX100] work which
+ do not support the regular Gigaset command set. If debug output (see
+ section 3.2.) shows something like this when dialing::
+
+ CMD Received: ERROR
+ Available Params: 0
+ Connection State: 0, Response: -1
+ gigaset_process_response: resp_code -1 in ConState 0 !
+ Timeout occurred
+
+ then switching to unimodem mode may help.
+
+ If you have installed the command line tool gigacontr, you can enter
+ unimodem mode using::
+
+ gigacontr --mode unimodem
+
+ You can switch back using::
+
+ gigacontr --mode isdn
+
+ You can also put the driver directly into Unimodem mode when it's loaded,
+ by passing the module parameter startmode=0 to the hardware specific
+ module, e.g.::
+
+ modprobe usb_gigaset startmode=0
+
+ or by adding a line like::
+
+ options usb_gigaset startmode=0
+
+ to an appropriate module configuration file, like::
+
+ /etc/modprobe.d/gigaset.conf
+
+2.6. Call-ID (CID) mode
+-----------------------
+
+ Call-IDs are numbers used to tag commands to, and responses from, the
+ Gigaset base in order to support the simultaneous handling of multiple
+ ISDN calls. Their use can be enabled ("CID mode") or disabled ("Unimodem
+ mode"). Without Call-IDs (in Unimodem mode), only a very limited set of
+ functions is available. It allows outgoing data connections only, but
+ does not signal incoming calls or other base events.
+
+ DECT cordless data devices (M10x) permanently occupy the cordless
+ connection to the base while Call-IDs are activated. As the Gigaset
+ bases only support one DECT data connection at a time, this prevents
+ other DECT cordless data devices from accessing the base.
+
+ During active operation, the driver switches to the necessary mode
+ automatically. However, for the reasons above, the mode chosen when
+ the device is not in use (idle) can be selected by the user.
+
+ - If you want to receive incoming calls, you can use the default
+ settings (CID mode).
+ - If you have several DECT data devices (M10x) which you want to use
+ in turn, select Unimodem mode by passing the parameter "cidmode=0" to
+ the appropriate driver module (ser_gigaset or usb_gigaset).
+
+ If you want both of these at once, you are out of luck.
+
+ You can also use the tty class parameter "cidmode" of the device to
+ change its CID mode while the driver is loaded, eg.::
+
+ echo 0 > /sys/class/tty/ttyGU0/cidmode
+
+2.7. Dialing Numbers
+--------------------
+provided by an application for dialing out must
+ be a public network number according to the local dialing plan, without
+ any dial prefix for getting an outside line.
+
+ Internal calls can be made by providing an internal extension number
+ prefixed with ``**`` (two asterisks) as the called party number. So to dial
+ eg. the first registered DECT handset, give ``**11`` as the called party
+ number. Dialing ``***`` (three asterisks) calls all extensions
+ simultaneously (global call).
+
+ Unimodem mode does not support internal calls.
+
+2.8. Unregistered Wireless Devices (M101/M105)
+----------------------------------------------
+
+ The main purpose of the ser_gigaset and usb_gigaset drivers is to allow
+ the M101 and M105 wireless devices to be used as ISDN devices for ISDN
+ connections through a Gigaset base. Therefore they assume that the device
+ is registered to a DECT base.
+
+ If the M101/M105 device is not registered to a base, initialization of
+ the device fails, and a corresponding error message is logged by the
+ driver. In that situation, a restricted set of functions is available
+ which includes, in particular, those necessary for registering the device
+ to a base or for switching it between Fixed Part and Portable Part
+ modes. See the gigacontr(8) manpage for details.
+
+3. Troubleshooting
+====================
+
+3.1. Solutions to frequently reported problems
+----------------------------------------------
+
+ Problem:
+ You have a slow provider and isdn4linux gives up dialing too early.
+ Solution:
+ Load the isdn module using the dialtimeout option. You can do this e.g.
+ by adding a line like::
+
+ options isdn dialtimeout=15
+
+ to /etc/modprobe.d/gigaset.conf or a similar file.
+
+ Problem:
+ The isdnlog program emits error messages or just doesn't work.
+ Solution:
+ Isdnlog supports only the HiSax driver. Do not attempt to use it with
+ other drivers such as Gigaset.
+
+ Problem:
+ You have two or more DECT data adapters (M101/M105) and only the
+ first one you turn on works.
+ Solution:
+ Select Unimodem mode for all DECT data adapters. (see section 2.5.)
+
+ Problem:
+ Messages like this::
+
+ usb_gigaset 3-2:1.0: Could not initialize the device.
+
+ appear in your syslog.
+ Solution:
+ Check whether your M10x wireless device is correctly registered to the
+ Gigaset base. (see section 2.7.)
+
+3.2. Telling the driver to provide more information
+---------------------------------------------------
+ Building the driver with the "Gigaset debugging" kernel configuration
+ option (CONFIG_GIGASET_DEBUG) gives it the ability to produce additional
+ information useful for debugging.
+
+ You can control the amount of debugging information the driver produces by
+ writing an appropriate value to /sys/module/gigaset/parameters/debug,
+ e.g.::
+
+ echo 0 > /sys/module/gigaset/parameters/debug
+
+ switches off debugging output completely,
+
+ ::
+
+ echo 0x302020 > /sys/module/gigaset/parameters/debug
+
+ enables a reasonable set of debugging output messages. These values are
+ bit patterns where every bit controls a certain type of debugging output.
+ See the constants DEBUG_* in the source file gigaset.h for details.
+
+ The initial value can be set using the debug parameter when loading the
+ module "gigaset", e.g. by adding a line::
+
+ options gigaset debug=0
+
+ to your module configuration file, eg. /etc/modprobe.d/gigaset.conf
+
+ Generated debugging information can be found
+ - as output of the command::
+
+ dmesg
+
+ - in system log files written by your syslog daemon, usually
+ in /var/log/, e.g. /var/log/messages.
+
+3.3. Reporting problems and bugs
+--------------------------------
+ If you can't solve problems with the driver on your own, feel free to
+ use one of the forums, bug trackers, or mailing lists on
+
+ https://sourceforge.net/projects/gigaset307x
+
+ or write an electronic mail to the maintainers.
+
+ Try to provide as much information as possible, such as
+
+ - distribution
+ - kernel version (uname -r)
+ - gcc version (gcc --version)
+ - hardware architecture (uname -m, ...)
+ - type and firmware version of your device (base and wireless module,
+ if any)
+ - output of "lsusb -v" (if using an USB device)
+ - error messages
+ - relevant system log messages (it would help if you activate debug
+ output as described in 3.2.)
+
+ For help with general configuration problems not specific to our driver,
+ such as isdn4linux and network configuration issues, please refer to the
+ appropriate forums and newsgroups.
+
+3.4. Reporting problem solutions
+--------------------------------
+ If you solved a problem with our drivers, wrote startup scripts for your
+ distribution, ... feel free to contact us (using one of the places
+ mentioned in 3.3.). We'd like to add scripts, hints, documentation
+ to the driver and/or the project web page.
+
+
+4. Links, other software
+==========================
+
+ - Sourceforge project developing this driver and associated tools
+ https://sourceforge.net/projects/gigaset307x
+ - Yahoo! Group on the Siemens Gigaset family of devices
+ https://de.groups.yahoo.com/group/Siemens-Gigaset
+ - Siemens Gigaset/T-Sinus compatibility table
+ http://www.erbze.info/sinus_gigaset.htm
+ (archived at https://web.archive.org/web/20100717020421/http://www.erbze.info:80/sinus_gigaset.htm )
+
+
+5. Credits
+============
+
+ Thanks to
+
+ Karsten Keil
+ for his help with isdn4linux
+ Deti Fliegl
+ for his base driver code
+ Dennis Dietrich
+ for his kernel 2.6 patches
+ Andreas Rummel
+ for his work and logs to get unimodem mode working
+ Andreas Degert
+ for his logs and patches to get cx 100 working
+ Dietrich Feist
+ for his generous donation of one M105 and two M101 cordless adapters
+ Christoph Schweers
+ for his generous donation of a M34 device
+
+ and all the other people who sent logs and other information.
diff --git a/Documentation/isdn/hysdn.rst b/Documentation/isdn/hysdn.rst
new file mode 100644
index 0000000..0a168d1
--- /dev/null
+++ b/Documentation/isdn/hysdn.rst
@@ -0,0 +1,196 @@
+============
+Hysdn Driver
+============
+
+The hysdn driver has been written by
+Werner Cornelius (werner@isdn4linux.de or werner@titro.de)
+for Hypercope GmbH Aachen Germany. Hypercope agreed to publish this driver
+under the GNU General Public License.
+
+The CAPI 2.0-support was added by Ulrich Albrecht (ualbrecht@hypercope.de)
+for Hypercope GmbH Aachen, Germany.
+
+
+ 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; either version 2 of the License, or
+ (at your option) any later version.
+
+ 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.
+
+ 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.
+
+.. Table of contents
+
+ 1. About the driver
+
+ 2. Loading/Unloading the driver
+
+ 3. Entries in the /proc filesystem
+
+ 4. The /proc/net/hysdn/cardconfX file
+
+ 5. The /proc/net/hysdn/cardlogX file
+
+ 6. Where to get additional info and help
+
+
+1. About the driver
+===================
+
+ The drivers/isdn/hysdn subdir contains a driver for HYPERCOPEs active
+ PCI isdn cards Champ, Ergo and Metro. To enable support for this cards
+ enable ISDN support in the kernel config and support for HYSDN cards in
+ the active cards submenu. The driver may only be compiled and used if
+ support for loadable modules and the process filesystem have been enabled.
+
+ These cards provide two different interfaces to the kernel. Without the
+ optional CAPI 2.0 support, they register as ethernet card. IP-routing
+ to a ISDN-destination is performed on the card itself. All necessary
+ handlers for various protocols like ppp and others as well as config info
+ and firmware may be fetched from Hypercopes WWW-Site www.hypercope.de.
+
+ With CAPI 2.0 support enabled, the card can also be used as a CAPI 2.0
+ compliant devices with either CAPI 2.0 applications
+ (check isdn4k-utils) or -using the capidrv module- as a regular
+ isdn4linux device. This is done via the same mechanism as with the
+ active AVM cards and in fact uses the same module.
+
+
+2. Loading/Unloading the driver
+===============================
+
+ The module has no command line parameters and auto detects up to 10 cards
+ in the id-range 0-9.
+ If a loaded driver shall be unloaded all open files in the /proc/net/hysdn
+ subdir need to be closed and all ethernet interfaces allocated by this
+ driver must be shut down. Otherwise the module counter will avoid a module
+ unload.
+
+ If you are using the CAPI 2.0-interface, make sure to load/modprobe the
+ kernelcapi-module first.
+
+ If you plan to use the capidrv-link to isdn4linux, make sure to load
+ capidrv.o after all modules using this driver (i.e. after hysdn and
+ any avm-specific modules).
+
+3. Entries in the /proc filesystem
+==================================
+
+ When the module has been loaded it adds the directory hysdn in the
+ /proc/net tree. This directory contains exactly 2 file entries for each
+ card. One is called cardconfX and the other cardlogX, where X is the
+ card id number from 0 to 9.
+ The cards are numbered in the order found in the PCI config data.
+
+4. The /proc/net/hysdn/cardconfX file
+=====================================
+
+ This file may be read to get by everyone to get info about the cards type,
+ actual state, available features and used resources.
+ The first 3 entries (id, bus and slot) are PCI info fields, the following
+ type field gives the information about the cards type:
+
+ - 4 -> Ergo card (server card with 2 b-chans)
+ - 5 -> Metro card (server card with 4 or 8 b-chans)
+ - 6 -> Champ card (client card with 2 b-chans)
+
+ The following 3 fields show the hardware assignments for irq, iobase and the
+ dual ported memory (dp-mem).
+
+ The fields b-chans and fax-chans announce the available card resources of
+ this types for the user.
+
+ The state variable indicates the actual drivers state for this card with the
+ following assignments.
+
+ - 0 -> card has not been booted since driver load
+ - 1 -> card booting is actually in progess
+ - 2 -> card is in an error state due to a previous boot failure
+ - 3 -> card is booted and active
+
+ And the last field (device) shows the name of the ethernet device assigned
+ to this card. Up to the first successful boot this field only shows a -
+ to tell that no net device has been allocated up to now. Once a net device
+ has been allocated it remains assigned to this card, even if a card is
+ rebooted and an boot error occurs.
+
+ Writing to the cardconfX file boots the card or transfers config lines to
+ the cards firmware. The type of data is automatically detected when the
+ first data is written. Only root has write access to this file.
+ The firmware boot files are normally called hyclient.pof for client cards
+ and hyserver.pof for server cards.
+ After successfully writing the boot file, complete config files or single
+ config lines may be copied to this file.
+ If an error occurs the return value given to the writing process has the
+ following additional codes (decimal):
+
+ ==== ============================================
+ 1000 Another process is currently bootng the card
+ 1001 Invalid firmware header
+ 1002 Boards dual-port RAM test failed
+ 1003 Internal firmware handler error
+ 1004 Boot image size invalid
+ 1005 First boot stage (bootstrap loader) failed
+ 1006 Second boot stage failure
+ 1007 Timeout waiting for card ready during boot
+ 1008 Operation only allowed in booted state
+ 1009 Config line too long
+ 1010 Invalid channel number
+ 1011 Timeout sending config data
+ ==== ============================================
+
+ Additional info about error reasons may be fetched from the log output.
+
+5. The /proc/net/hysdn/cardlogX file
+====================================
+
+ The cardlogX file entry may be opened multiple for reading by everyone to
+ get the cards and drivers log data. Card messages always start with the
+ keyword LOG. All other lines are output from the driver.
+ The driver log data may be redirected to the syslog by selecting the
+ appropriate bitmask. The cards log messages will always be send to this
+ interface but never to the syslog.
+
+ A root user may write a decimal or hex (with 0x) value t this file to select
+ desired output options. As mentioned above the cards log dat is always
+ written to the cardlog file independent of the following options only used
+ to check and debug the driver itself:
+
+ For example::
+
+ echo "0x34560078" > /proc/net/hysdn/cardlog0
+
+ to output the hex log mask 34560078 for card 0.
+
+ The written value is regarded as an unsigned 32-Bit value, bit ored for
+ desired output. The following bits are already assigned:
+
+ ========== ============================================================
+ 0x80000000 All driver log data is alternatively via syslog
+ 0x00000001 Log memory allocation errors
+ 0x00000010 Firmware load start and close are logged
+ 0x00000020 Log firmware record parser
+ 0x00000040 Log every firmware write actions
+ 0x00000080 Log all card related boot messages
+ 0x00000100 Output all config data sent for debugging purposes
+ 0x00000200 Only non comment config lines are shown wth channel
+ 0x00000400 Additional conf log output
+ 0x00001000 Log the asynchronous scheduler actions (config and log)
+ 0x00100000 Log all open and close actions to /proc/net/hysdn/card files
+ 0x00200000 Log all actions from /proc file entries
+ 0x00010000 Log network interface init and deinit
+ ========== ============================================================
+
+6. Where to get additional info and help
+========================================
+
+ If you have any problems concerning the driver or configuration contact
+ the Hypercope support team (support@hypercope.de) and or the authors
+ Werner Cornelius (werner@isdn4linux or cornelius@titro.de) or
+ Ulrich Albrecht (ualbrecht@hypercope.de).
diff --git a/Documentation/isdn/index.rst b/Documentation/isdn/index.rst
new file mode 100644
index 0000000..407e74b7
--- /dev/null
+++ b/Documentation/isdn/index.rst
@@ -0,0 +1,24 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+====
+ISDN
+====
+
+.. toctree::
+ :maxdepth: 2
+
+ interface_capi
+
+ avmb1
+ gigaset
+ hysdn
+ m_isdn
+
+ credits
+
+.. only:: subproject and html
+
+ Indices
+ =======
+
+ * :ref:`genindex`
diff --git a/Documentation/isdn/interface_capi.rst b/Documentation/isdn/interface_capi.rst
new file mode 100644
index 0000000..01a4b5a
--- /dev/null
+++ b/Documentation/isdn/interface_capi.rst
@@ -0,0 +1,407 @@
+=========================================
+Kernel CAPI Interface to Hardware Drivers
+=========================================
+
+1. Overview
+===========
+
+From the CAPI 2.0 specification:
+COMMON-ISDN-API (CAPI) is an application programming interface standard used
+to access ISDN equipment connected to basic rate interfaces (BRI) and primary
+rate interfaces (PRI).
+
+Kernel CAPI operates as a dispatching layer between CAPI applications and CAPI
+hardware drivers. Hardware drivers register ISDN devices (controllers, in CAPI
+lingo) with Kernel CAPI to indicate their readiness to provide their service
+to CAPI applications. CAPI applications also register with Kernel CAPI,
+requesting association with a CAPI device. Kernel CAPI then dispatches the
+application registration to an available device, forwarding it to the
+corresponding hardware driver. Kernel CAPI then forwards CAPI messages in both
+directions between the application and the hardware driver.
+
+Format and semantics of CAPI messages are specified in the CAPI 2.0 standard.
+This standard is freely available from https://www.capi.org.
+
+
+2. Driver and Device Registration
+=================================
+
+CAPI drivers optionally register themselves with Kernel CAPI by calling the
+Kernel CAPI function register_capi_driver() with a pointer to a struct
+capi_driver. This structure must be filled with the name and revision of the
+driver, and optionally a pointer to a callback function, add_card(). The
+registration can be revoked by calling the function unregister_capi_driver()
+with a pointer to the same struct capi_driver.
+
+CAPI drivers must register each of the ISDN devices they control with Kernel
+CAPI by calling the Kernel CAPI function attach_capi_ctr() with a pointer to a
+struct capi_ctr before they can be used. This structure must be filled with
+the names of the driver and controller, and a number of callback function
+pointers which are subsequently used by Kernel CAPI for communicating with the
+driver. The registration can be revoked by calling the function
+detach_capi_ctr() with a pointer to the same struct capi_ctr.
+
+Before the device can be actually used, the driver must fill in the device
+information fields 'manu', 'version', 'profile' and 'serial' in the capi_ctr
+structure of the device, and signal its readiness by calling capi_ctr_ready().
+From then on, Kernel CAPI may call the registered callback functions for the
+device.
+
+If the device becomes unusable for any reason (shutdown, disconnect ...), the
+driver has to call capi_ctr_down(). This will prevent further calls to the
+callback functions by Kernel CAPI.
+
+
+3. Application Registration and Communication
+=============================================
+
+Kernel CAPI forwards registration requests from applications (calls to CAPI
+operation CAPI_REGISTER) to an appropriate hardware driver by calling its
+register_appl() callback function. A unique Application ID (ApplID, u16) is
+allocated by Kernel CAPI and passed to register_appl() along with the
+parameter structure provided by the application. This is analogous to the
+open() operation on regular files or character devices.
+
+After a successful return from register_appl(), CAPI messages from the
+application may be passed to the driver for the device via calls to the
+send_message() callback function. Conversely, the driver may call Kernel
+CAPI's capi_ctr_handle_message() function to pass a received CAPI message to
+Kernel CAPI for forwarding to an application, specifying its ApplID.
+
+Deregistration requests (CAPI operation CAPI_RELEASE) from applications are
+forwarded as calls to the release_appl() callback function, passing the same
+ApplID as with register_appl(). After return from release_appl(), no CAPI
+messages for that application may be passed to or from the device anymore.
+
+
+4. Data Structures
+==================
+
+4.1 struct capi_driver
+----------------------
+
+This structure describes a Kernel CAPI driver itself. It is used in the
+register_capi_driver() and unregister_capi_driver() functions, and contains
+the following non-private fields, all to be set by the driver before calling
+register_capi_driver():
+
+``char name[32]``
+ the name of the driver, as a zero-terminated ASCII string
+``char revision[32]``
+ the revision number of the driver, as a zero-terminated ASCII string
+``int (*add_card)(struct capi_driver *driver, capicardparams *data)``
+ a callback function pointer (may be NULL)
+
+
+4.2 struct capi_ctr
+-------------------
+
+This structure describes an ISDN device (controller) handled by a Kernel CAPI
+driver. After registration via the attach_capi_ctr() function it is passed to
+all controller specific lower layer interface and callback functions to
+identify the controller to operate on.
+
+It contains the following non-private fields:
+
+to be set by the driver before calling attach_capi_ctr():
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+``struct module *owner``
+ pointer to the driver module owning the device
+
+``void *driverdata``
+ an opaque pointer to driver specific data, not touched by Kernel CAPI
+
+``char name[32]``
+ the name of the controller, as a zero-terminated ASCII string
+
+``char *driver_name``
+ the name of the driver, as a zero-terminated ASCII string
+
+``int (*load_firmware)(struct capi_ctr *ctrlr, capiloaddata *ldata)``
+ (optional) pointer to a callback function for sending firmware and
+ configuration data to the device
+
+ The function may return before the operation has completed.
+
+ Completion must be signalled by a call to capi_ctr_ready().
+
+ Return value: 0 on success, error code on error
+ Called in process context.
+
+``void (*reset_ctr)(struct capi_ctr *ctrlr)``
+ (optional) pointer to a callback function for stopping the device,
+ releasing all registered applications
+
+ The function may return before the operation has completed.
+
+ Completion must be signalled by a call to capi_ctr_down().
+
+ Called in process context.
+
+``void (*register_appl)(struct capi_ctr *ctrlr, u16 applid, capi_register_params *rparam)``
+ pointers to callback function for registration of
+ applications with the device
+
+ Calls to these functions are serialized by Kernel CAPI so that only
+ one call to any of them is active at any time.
+
+``void (*release_appl)(struct capi_ctr *ctrlr, u16 applid)``
+ pointers to callback functions deregistration of
+ applications with the device
+
+ Calls to these functions are serialized by Kernel CAPI so that only
+ one call to any of them is active at any time.
+
+``u16 (*send_message)(struct capi_ctr *ctrlr, struct sk_buff *skb)``
+ pointer to a callback function for sending a CAPI message to the
+ device
+
+ Return value: CAPI error code
+
+ If the method returns 0 (CAPI_NOERROR) the driver has taken ownership
+ of the skb and the caller may no longer access it. If it returns a
+ non-zero (error) value then ownership of the skb returns to the caller
+ who may reuse or free it.
+
+ The return value should only be used to signal problems with respect
+ to accepting or queueing the message. Errors occurring during the
+ actual processing of the message should be signaled with an
+ appropriate reply message.
+
+ May be called in process or interrupt context.
+
+ Calls to this function are not serialized by Kernel CAPI, ie. it must
+ be prepared to be re-entered.
+
+``char *(*procinfo)(struct capi_ctr *ctrlr)``
+ pointer to a callback function returning the entry for the device in
+ the CAPI controller info table, /proc/capi/controller
+
+``const struct file_operations *proc_fops``
+ pointers to callback functions for the device's proc file
+ system entry, /proc/capi/controllers/<n>; pointer to the device's
+ capi_ctr structure is available from struct proc_dir_entry::data
+ which is available from struct inode.
+
+Note:
+ Callback functions except send_message() are never called in interrupt
+ context.
+
+to be filled in before calling capi_ctr_ready():
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+``u8 manu[CAPI_MANUFACTURER_LEN]``
+ value to return for CAPI_GET_MANUFACTURER
+
+``capi_version version``
+ value to return for CAPI_GET_VERSION
+
+``capi_profile profile``
+ value to return for CAPI_GET_PROFILE
+
+``u8 serial[CAPI_SERIAL_LEN]``
+ value to return for CAPI_GET_SERIAL
+
+
+4.3 SKBs
+--------
+
+CAPI messages are passed between Kernel CAPI and the driver via send_message()
+and capi_ctr_handle_message(), stored in the data portion of a socket buffer
+(skb). Each skb contains a single CAPI message coded according to the CAPI 2.0
+standard.
+
+For the data transfer messages, DATA_B3_REQ and DATA_B3_IND, the actual
+payload data immediately follows the CAPI message itself within the same skb.
+The Data and Data64 parameters are not used for processing. The Data64
+parameter may be omitted by setting the length field of the CAPI message to 22
+instead of 30.
+
+
+4.4 The _cmsg Structure
+-----------------------
+
+(declared in <linux/isdn/capiutil.h>)
+
+The _cmsg structure stores the contents of a CAPI 2.0 message in an easily
+accessible form. It contains members for all possible CAPI 2.0 parameters,
+including subparameters of the Additional Info and B Protocol structured
+parameters, with the following exceptions:
+
+* second Calling party number (CONNECT_IND)
+
+* Data64 (DATA_B3_REQ and DATA_B3_IND)
+
+* Sending complete (subparameter of Additional Info, CONNECT_REQ and INFO_REQ)
+
+* Global Configuration (subparameter of B Protocol, CONNECT_REQ, CONNECT_RESP
+ and SELECT_B_PROTOCOL_REQ)
+
+Only those parameters appearing in the message type currently being processed
+are actually used. Unused members should be set to zero.
+
+Members are named after the CAPI 2.0 standard names of the parameters they
+represent. See <linux/isdn/capiutil.h> for the exact spelling. Member data
+types are:
+
+=========== =================================================================
+u8 for CAPI parameters of type 'byte'
+
+u16 for CAPI parameters of type 'word'
+
+u32 for CAPI parameters of type 'dword'
+
+_cstruct for CAPI parameters of type 'struct'
+ The member is a pointer to a buffer containing the parameter in
+ CAPI encoding (length + content). It may also be NULL, which will
+ be taken to represent an empty (zero length) parameter.
+ Subparameters are stored in encoded form within the content part.
+
+_cmstruct alternative representation for CAPI parameters of type 'struct'
+ (used only for the 'Additional Info' and 'B Protocol' parameters)
+ The representation is a single byte containing one of the values:
+ CAPI_DEFAULT: The parameter is empty/absent.
+ CAPI_COMPOSE: The parameter is present.
+ Subparameter values are stored individually in the corresponding
+ _cmsg structure members.
+=========== =================================================================
+
+Functions capi_cmsg2message() and capi_message2cmsg() are provided to convert
+messages between their transport encoding described in the CAPI 2.0 standard
+and their _cmsg structure representation. Note that capi_cmsg2message() does
+not know or check the size of its destination buffer. The caller must make
+sure it is big enough to accommodate the resulting CAPI message.
+
+
+5. Lower Layer Interface Functions
+==================================
+
+(declared in <linux/isdn/capilli.h>)
+
+::
+
+ void register_capi_driver(struct capi_driver *drvr)
+ void unregister_capi_driver(struct capi_driver *drvr)
+
+register/unregister a driver with Kernel CAPI
+
+::
+
+ int attach_capi_ctr(struct capi_ctr *ctrlr)
+ int detach_capi_ctr(struct capi_ctr *ctrlr)
+
+register/unregister a device (controller) with Kernel CAPI
+
+::
+
+ void capi_ctr_ready(struct capi_ctr *ctrlr)
+ void capi_ctr_down(struct capi_ctr *ctrlr)
+
+signal controller ready/not ready
+
+::
+
+ void capi_ctr_suspend_output(struct capi_ctr *ctrlr)
+ void capi_ctr_resume_output(struct capi_ctr *ctrlr)
+
+signal suspend/resume
+
+::
+
+ void capi_ctr_handle_message(struct capi_ctr * ctrlr, u16 applid,
+ struct sk_buff *skb)
+
+pass a received CAPI message to Kernel CAPI
+for forwarding to the specified application
+
+
+6. Helper Functions and Macros
+==============================
+
+Library functions (from <linux/isdn/capilli.h>):
+
+::
+
+ void capilib_new_ncci(struct list_head *head, u16 applid,
+ u32 ncci, u32 winsize)
+ void capilib_free_ncci(struct list_head *head, u16 applid, u32 ncci)
+ void capilib_release_appl(struct list_head *head, u16 applid)
+ void capilib_release(struct list_head *head)
+ void capilib_data_b3_conf(struct list_head *head, u16 applid,
+ u32 ncci, u16 msgid)
+ u16 capilib_data_b3_req(struct list_head *head, u16 applid,
+ u32 ncci, u16 msgid)
+
+
+Macros to extract/set element values from/in a CAPI message header
+(from <linux/isdn/capiutil.h>):
+
+====================== ============================= ====================
+Get Macro Set Macro Element (Type)
+====================== ============================= ====================
+CAPIMSG_LEN(m) CAPIMSG_SETLEN(m, len) Total Length (u16)
+CAPIMSG_APPID(m) CAPIMSG_SETAPPID(m, applid) ApplID (u16)
+CAPIMSG_COMMAND(m) CAPIMSG_SETCOMMAND(m,cmd) Command (u8)
+CAPIMSG_SUBCOMMAND(m) CAPIMSG_SETSUBCOMMAND(m, cmd) Subcommand (u8)
+CAPIMSG_CMD(m) - Command*256
+ + Subcommand (u16)
+CAPIMSG_MSGID(m) CAPIMSG_SETMSGID(m, msgid) Message Number (u16)
+
+CAPIMSG_CONTROL(m) CAPIMSG_SETCONTROL(m, contr) Controller/PLCI/NCCI
+ (u32)
+CAPIMSG_DATALEN(m) CAPIMSG_SETDATALEN(m, len) Data Length (u16)
+====================== ============================= ====================
+
+
+Library functions for working with _cmsg structures
+(from <linux/isdn/capiutil.h>):
+
+``unsigned capi_cmsg2message(_cmsg *cmsg, u8 *msg)``
+ Assembles a CAPI 2.0 message from the parameters in ``*cmsg``,
+ storing the result in ``*msg``.
+
+``unsigned capi_message2cmsg(_cmsg *cmsg, u8 *msg)``
+ Disassembles the CAPI 2.0 message in ``*msg``, storing the parameters
+ in ``*cmsg``.
+
+``unsigned capi_cmsg_header(_cmsg *cmsg, u16 ApplId, u8 Command, u8 Subcommand, u16 Messagenumber, u32 Controller)``
+ Fills the header part and address field of the _cmsg structure ``*cmsg``
+ with the given values, zeroing the remainder of the structure so only
+ parameters with non-default values need to be changed before sending
+ the message.
+
+``void capi_cmsg_answer(_cmsg *cmsg)``
+ Sets the low bit of the Subcommand field in ``*cmsg``, thereby
+ converting ``_REQ`` to ``_CONF`` and ``_IND`` to ``_RESP``.
+
+``char *capi_cmd2str(u8 Command, u8 Subcommand)``
+ Returns the CAPI 2.0 message name corresponding to the given command
+ and subcommand values, as a static ASCII string. The return value may
+ be NULL if the command/subcommand is not one of those defined in the
+ CAPI 2.0 standard.
+
+
+7. Debugging
+============
+
+The module kernelcapi has a module parameter showcapimsgs controlling some
+debugging output produced by the module. It can only be set when the module is
+loaded, via a parameter "showcapimsgs=<n>" to the modprobe command, either on
+the command line or in the configuration file.
+
+If the lowest bit of showcapimsgs is set, kernelcapi logs controller and
+application up and down events.
+
+In addition, every registered CAPI controller has an associated traceflag
+parameter controlling how CAPI messages sent from and to tha controller are
+logged. The traceflag parameter is initialized with the value of the
+showcapimsgs parameter when the controller is registered, but can later be
+changed via the MANUFACTURER_REQ command KCAPI_CMD_TRACE.
+
+If the value of traceflag is non-zero, CAPI messages are logged.
+DATA_B3 messages are only logged if the value of traceflag is > 2.
+
+If the lowest bit of traceflag is set, only the command/subcommand and message
+length are logged. Otherwise, kernelcapi logs a readable representation of
+the entire message.
diff --git a/Documentation/isdn/m_isdn.rst b/Documentation/isdn/m_isdn.rst
new file mode 100644
index 0000000..9957de3
--- /dev/null
+++ b/Documentation/isdn/m_isdn.rst
@@ -0,0 +1,9 @@
+============
+mISDN Driver
+============
+
+mISDN is a new modular ISDN driver, in the long term it should replace
+the old I4L driver architecture for passiv ISDN cards.
+It was designed to allow a broad range of applications and interfaces
+but only have the basic function in kernel, the interface to the user
+space is based on sockets with a own address family AF_ISDN.
diff --git a/Documentation/kbuild/index.rst b/Documentation/kbuild/index.rst
index e323a3f..0f144fa 100644
--- a/Documentation/kbuild/index.rst
+++ b/Documentation/kbuild/index.rst
@@ -18,6 +18,7 @@
headers_install
issues
+ reproducible-builds
.. only:: subproject and html
diff --git a/Documentation/kbuild/kbuild.rst b/Documentation/kbuild/kbuild.rst
index 61b2181..f1e5dce 100644
--- a/Documentation/kbuild/kbuild.rst
+++ b/Documentation/kbuild/kbuild.rst
@@ -105,6 +105,15 @@
Setting "O=..." takes precedence over KBUILD_OUTPUT.
+KBUILD_EXTRA_WARN
+-----------------
+Specify the extra build checks. The same value can be assigned by passing
+W=... from the command line.
+
+See `make help` for the list of the supported values.
+
+Setting "W=..." takes precedence over KBUILD_EXTRA_WARN.
+
KBUILD_DEBARCH
--------------
For the deb-pkg target, allows overriding the normal heuristics deployed by
@@ -241,11 +250,6 @@
$ make ALLSOURCE_ARCHS=all tags
-KBUILD_ENABLE_EXTRA_GCC_CHECKS
-------------------------------
-If enabled over the make command line with "W=1", it turns on additional
-gcc -W... options for more extensive build-time checking.
-
KBUILD_BUILD_TIMESTAMP
----------------------
Setting this to a date string overrides the timestamp used in the
@@ -258,17 +262,3 @@
These two variables allow to override the user@host string displayed during
boot and in /proc/version. The default value is the output of the commands
whoami and host, respectively.
-
-KBUILD_LDS
-----------
-The linker script with full path. Assigned by the top-level Makefile.
-
-KBUILD_VMLINUX_OBJS
--------------------
-All object files for vmlinux. They are linked to vmlinux in the same
-order as listed in KBUILD_VMLINUX_OBJS.
-
-KBUILD_VMLINUX_LIBS
--------------------
-All .a "lib" files for vmlinux. KBUILD_VMLINUX_OBJS and KBUILD_VMLINUX_LIBS
-together specify all the object files used to link vmlinux.
diff --git a/Documentation/kbuild/makefiles.rst b/Documentation/kbuild/makefiles.rst
index f4f0f7f..6ba9d53 100644
--- a/Documentation/kbuild/makefiles.rst
+++ b/Documentation/kbuild/makefiles.rst
@@ -471,21 +471,6 @@
The second argument is optional, and if supplied will be used
if first argument is not supported.
- cc-ldoption
- cc-ldoption is used to check if $(CC) when used to link object files
- supports the given option. An optional second option may be
- specified if first option are not supported.
-
- Example::
-
- #arch/x86/kernel/Makefile
- vsyscall-flags += $(call cc-ldoption, -Wl$(comma)--hash-style=sysv)
-
- In the above example, vsyscall-flags will be assigned the option
- -Wl$(comma)--hash-style=sysv if it is supported by $(CC).
- The second argument is optional, and if supplied will be used
- if first argument is not supported.
-
as-instr
as-instr checks if the assembler reports a specific instruction
and then outputs either option1 or option2
@@ -765,7 +750,8 @@
generated by kbuild are deleted all over the kernel src tree when
"make clean" is executed.
-Additional files can be specified in kbuild makefiles by use of $(clean-files).
+Additional files or directories can be specified in kbuild makefiles by use of
+$(clean-files).
Example::
@@ -776,23 +762,8 @@
Kbuild will assume files to be in the same relative directory as the
Makefile, except if prefixed with $(objtree).
-To delete a directory hierarchy use:
-
- Example::
-
- #scripts/package/Makefile
- clean-dirs := $(objtree)/debian/
-
-This will delete the directory debian in the toplevel directory, including all
-subdirectories.
-
-To exclude certain files from make clean, use the $(no-clean-files) variable.
-This is only a special case used in the top level Kbuild file:
-
- Example::
-
- #Kbuild
- no-clean-files := $(bounds-file) $(offsets-file)
+To exclude certain files or directories from make clean, use the
+$(no-clean-files) variable.
Usually kbuild descends down in subdirectories due to "obj-* := dir/",
but in the architecture makefiles where the kbuild infrastructure
@@ -988,13 +959,25 @@
$(KBUILD_ARFLAGS) set by the top level Makefile to "D" (deterministic
mode) if this option is supported by $(AR).
- ARCH_CPPFLAGS, ARCH_AFLAGS, ARCH_CFLAGS Overrides the kbuild defaults
+ KBUILD_LDS
- These variables are appended to the KBUILD_CPPFLAGS,
- KBUILD_AFLAGS, and KBUILD_CFLAGS, respectively, after the
- top-level Makefile has set any other flags. This provides a
- means for an architecture to override the defaults.
+ The linker script with full path. Assigned by the top-level Makefile.
+ KBUILD_LDS_MODULE
+
+ The module linker script with full path. Assigned by the top-level
+ Makefile and additionally by the arch Makefile.
+
+ KBUILD_VMLINUX_OBJS
+
+ All object files for vmlinux. They are linked to vmlinux in the same
+ order as listed in KBUILD_VMLINUX_OBJS.
+
+ KBUILD_VMLINUX_LIBS
+
+ All .a "lib" files for vmlinux. KBUILD_VMLINUX_OBJS and
+ KBUILD_VMLINUX_LIBS together specify all the object files used to
+ link vmlinux.
6.2 Add prerequisites to archheaders
------------------------------------
@@ -1139,7 +1122,7 @@
header-test-y
- header-test-y specifies headers (*.h) in the current directory that
+ header-test-y specifies headers (`*.h`) in the current directory that
should be compile tested to ensure they are self-contained,
i.e. compilable as standalone units. If CONFIG_HEADER_TEST is enabled,
this builds them as part of extra-y.
@@ -1147,11 +1130,11 @@
header-test-pattern-y
This works as a weaker version of header-test-y, and accepts wildcard
- patterns. The typical usage is:
+ patterns. The typical usage is::
- header-test-pattern-y += *.h
+ header-test-pattern-y += *.h
- This specifies all the files that matches to '*.h' in the current
+ This specifies all the files that matches to `*.h` in the current
directory, but the files in 'header-test-' are excluded.
6.7 Commands useful for building a boot image
diff --git a/Documentation/kbuild/modules.rst b/Documentation/kbuild/modules.rst
index 24e7634..d2ae799 100644
--- a/Documentation/kbuild/modules.rst
+++ b/Documentation/kbuild/modules.rst
@@ -470,9 +470,12 @@
The syntax of the Module.symvers file is::
- <CRC> <Symbol> <module>
+ <CRC> <Symbol> <Namespace> <Module> <Export Type>
- 0x2d036834 scsi_remove_host drivers/scsi/scsi_mod
+ 0xe1cc2a05 usb_stor_suspend USB_STORAGE drivers/usb/storage/usb-storage EXPORT_SYMBOL_GPL
+
+ The fields are separated by tabs and values may be empty (e.g.
+ if no namespace is defined for an exported symbol).
For a kernel build without CONFIG_MODVERSIONS enabled, the CRC
would read 0x00000000.
diff --git a/Documentation/kbuild/namespaces.rst b/Documentation/kbuild/namespaces.rst
new file mode 100644
index 0000000..982ed7b
--- /dev/null
+++ b/Documentation/kbuild/namespaces.rst
@@ -0,0 +1,154 @@
+=================
+Symbol Namespaces
+=================
+
+The following document describes how to use Symbol Namespaces to structure the
+export surface of in-kernel symbols exported through the family of
+EXPORT_SYMBOL() macros.
+
+.. Table of Contents
+
+ === 1 Introduction
+ === 2 How to define Symbol Namespaces
+ --- 2.1 Using the EXPORT_SYMBOL macros
+ --- 2.2 Using the DEFAULT_SYMBOL_NAMESPACE define
+ === 3 How to use Symbols exported in Namespaces
+ === 4 Loading Modules that use namespaced Symbols
+ === 5 Automatically creating MODULE_IMPORT_NS statements
+
+1. Introduction
+===============
+
+Symbol Namespaces have been introduced as a means to structure the export
+surface of the in-kernel API. It allows subsystem maintainers to partition
+their exported symbols into separate namespaces. That is useful for
+documentation purposes (think of the SUBSYSTEM_DEBUG namespace) as well as for
+limiting the availability of a set of symbols for use in other parts of the
+kernel. As of today, modules that make use of symbols exported into namespaces,
+are required to import the namespace. Otherwise the kernel will, depending on
+its configuration, reject loading the module or warn about a missing import.
+
+2. How to define Symbol Namespaces
+==================================
+
+Symbols can be exported into namespace using different methods. All of them are
+changing the way EXPORT_SYMBOL and friends are instrumented to create ksymtab
+entries.
+
+2.1 Using the EXPORT_SYMBOL macros
+==================================
+
+In addition to the macros EXPORT_SYMBOL() and EXPORT_SYMBOL_GPL(), that allow
+exporting of kernel symbols to the kernel symbol table, variants of these are
+available to export symbols into a certain namespace: EXPORT_SYMBOL_NS() and
+EXPORT_SYMBOL_NS_GPL(). They take one additional argument: the namespace.
+Please note that due to macro expansion that argument needs to be a
+preprocessor symbol. E.g. to export the symbol `usb_stor_suspend` into the
+namespace `USB_STORAGE`, use::
+
+ EXPORT_SYMBOL_NS(usb_stor_suspend, USB_STORAGE);
+
+The corresponding ksymtab entry struct `kernel_symbol` will have the member
+`namespace` set accordingly. A symbol that is exported without a namespace will
+refer to `NULL`. There is no default namespace if none is defined. `modpost`
+and kernel/module.c make use the namespace at build time or module load time,
+respectively.
+
+2.2 Using the DEFAULT_SYMBOL_NAMESPACE define
+=============================================
+
+Defining namespaces for all symbols of a subsystem can be very verbose and may
+become hard to maintain. Therefore a default define (DEFAULT_SYMBOL_NAMESPACE)
+is been provided, that, if set, will become the default for all EXPORT_SYMBOL()
+and EXPORT_SYMBOL_GPL() macro expansions that do not specify a namespace.
+
+There are multiple ways of specifying this define and it depends on the
+subsystem and the maintainer's preference, which one to use. The first option
+is to define the default namespace in the `Makefile` of the subsystem. E.g. to
+export all symbols defined in usb-common into the namespace USB_COMMON, add a
+line like this to drivers/usb/common/Makefile::
+
+ ccflags-y += -DDEFAULT_SYMBOL_NAMESPACE=USB_COMMON
+
+That will affect all EXPORT_SYMBOL() and EXPORT_SYMBOL_GPL() statements. A
+symbol exported with EXPORT_SYMBOL_NS() while this definition is present, will
+still be exported into the namespace that is passed as the namespace argument
+as this argument has preference over a default symbol namespace.
+
+A second option to define the default namespace is directly in the compilation
+unit as preprocessor statement. The above example would then read::
+
+ #undef DEFAULT_SYMBOL_NAMESPACE
+ #define DEFAULT_SYMBOL_NAMESPACE USB_COMMON
+
+within the corresponding compilation unit before any EXPORT_SYMBOL macro is
+used.
+
+3. How to use Symbols exported in Namespaces
+============================================
+
+In order to use symbols that are exported into namespaces, kernel modules need
+to explicitly import these namespaces. Otherwise the kernel might reject to
+load the module. The module code is required to use the macro MODULE_IMPORT_NS
+for the namespaces it uses symbols from. E.g. a module using the
+usb_stor_suspend symbol from above, needs to import the namespace USB_STORAGE
+using a statement like::
+
+ MODULE_IMPORT_NS(USB_STORAGE);
+
+This will create a `modinfo` tag in the module for each imported namespace.
+This has the side effect, that the imported namespaces of a module can be
+inspected with modinfo::
+
+ $ modinfo drivers/usb/storage/ums-karma.ko
+ [...]
+ import_ns: USB_STORAGE
+ [...]
+
+
+It is advisable to add the MODULE_IMPORT_NS() statement close to other module
+metadata definitions like MODULE_AUTHOR() or MODULE_LICENSE(). Refer to section
+5. for a way to create missing import statements automatically.
+
+4. Loading Modules that use namespaced Symbols
+==============================================
+
+At module loading time (e.g. `insmod`), the kernel will check each symbol
+referenced from the module for its availability and whether the namespace it
+might be exported to has been imported by the module. The default behaviour of
+the kernel is to reject loading modules that don't specify sufficient imports.
+An error will be logged and loading will be failed with EINVAL. In order to
+allow loading of modules that don't satisfy this precondition, a configuration
+option is available: Setting MODULE_ALLOW_MISSING_NAMESPACE_IMPORTS=y will
+enable loading regardless, but will emit a warning.
+
+5. Automatically creating MODULE_IMPORT_NS statements
+=====================================================
+
+Missing namespaces imports can easily be detected at build time. In fact,
+modpost will emit a warning if a module uses a symbol from a namespace
+without importing it.
+MODULE_IMPORT_NS() statements will usually be added at a definite location
+(along with other module meta data). To make the life of module authors (and
+subsystem maintainers) easier, a script and make target is available to fixup
+missing imports. Fixing missing imports can be done with::
+
+ $ make nsdeps
+
+A typical scenario for module authors would be::
+
+ - write code that depends on a symbol from a not imported namespace
+ - `make`
+ - notice the warning of modpost telling about a missing import
+ - run `make nsdeps` to add the import to the correct code location
+
+For subsystem maintainers introducing a namespace, the steps are very similar.
+Again, `make nsdeps` will eventually add the missing namespace imports for
+in-tree modules::
+
+ - move or add symbols to a namespace (e.g. with EXPORT_SYMBOL_NS())
+ - `make` (preferably with an allmodconfig to cover all in-kernel
+ modules)
+ - notice the warning of modpost telling about a missing import
+ - run `make nsdeps` to add the import to the correct code location
+
diff --git a/Documentation/kbuild/reproducible-builds.rst b/Documentation/kbuild/reproducible-builds.rst
new file mode 100644
index 0000000..ab92e98
--- /dev/null
+++ b/Documentation/kbuild/reproducible-builds.rst
@@ -0,0 +1,122 @@
+===================
+Reproducible builds
+===================
+
+It is generally desirable that building the same source code with
+the same set of tools is reproducible, i.e. the output is always
+exactly the same. This makes it possible to verify that the build
+infrastructure for a binary distribution or embedded system has not
+been subverted. This can also make it easier to verify that a source
+or tool change does not make any difference to the resulting binaries.
+
+The `Reproducible Builds project`_ has more information about this
+general topic. This document covers the various reasons why building
+the kernel may be unreproducible, and how to avoid them.
+
+Timestamps
+----------
+
+The kernel embeds a timestamp in two places:
+
+* The version string exposed by ``uname()`` and included in
+ ``/proc/version``
+
+* File timestamps in the embedded initramfs
+
+By default the timestamp is the current time. This must be overridden
+using the `KBUILD_BUILD_TIMESTAMP`_ variable. If you are building
+from a git commit, you could use its commit date.
+
+The kernel does *not* use the ``__DATE__`` and ``__TIME__`` macros,
+and enables warnings if they are used. If you incorporate external
+code that does use these, you must override the timestamp they
+correspond to by setting the `SOURCE_DATE_EPOCH`_ environment
+variable.
+
+User, host
+----------
+
+The kernel embeds the building user and host names in
+``/proc/version``. These must be overridden using the
+`KBUILD_BUILD_USER and KBUILD_BUILD_HOST`_ variables. If you are
+building from a git commit, you could use its committer address.
+
+Absolute filenames
+------------------
+
+When the kernel is built out-of-tree, debug information may include
+absolute filenames for the source files. This must be overridden by
+including the ``-fdebug-prefix-map`` option in the `KCFLAGS`_ variable.
+
+Depending on the compiler used, the ``__FILE__`` macro may also expand
+to an absolute filename in an out-of-tree build. Kbuild automatically
+uses the ``-fmacro-prefix-map`` option to prevent this, if it is
+supported.
+
+The Reproducible Builds web site has more information about these
+`prefix-map options`_.
+
+Generated files in source packages
+----------------------------------
+
+The build processes for some programs under the ``tools/``
+subdirectory do not completely support out-of-tree builds. This may
+cause a later source package build using e.g. ``make rpm-pkg`` to
+include generated files. You should ensure the source tree is
+pristine by running ``make mrproper`` or ``git clean -d -f -x`` before
+building a source package.
+
+Module signing
+--------------
+
+If you enable ``CONFIG_MODULE_SIG_ALL``, the default behaviour is to
+generate a different temporary key for each build, resulting in the
+modules being unreproducible. However, including a signing key with
+your source would presumably defeat the purpose of signing modules.
+
+One approach to this is to divide up the build process so that the
+unreproducible parts can be treated as sources:
+
+1. Generate a persistent signing key. Add the certificate for the key
+ to the kernel source.
+
+2. Set the ``CONFIG_SYSTEM_TRUSTED_KEYS`` symbol to include the
+ signing key's certificate, set ``CONFIG_MODULE_SIG_KEY`` to an
+ empty string, and disable ``CONFIG_MODULE_SIG_ALL``.
+ Build the kernel and modules.
+
+3. Create detached signatures for the modules, and publish them as
+ sources.
+
+4. Perform a second build that attaches the module signatures. It
+ can either rebuild the modules or use the output of step 2.
+
+Structure randomisation
+-----------------------
+
+If you enable ``CONFIG_GCC_PLUGIN_RANDSTRUCT``, you will need to
+pre-generate the random seed in
+``scripts/gcc-plgins/randomize_layout_seed.h`` so the same value
+is used in rebuilds.
+
+Debug info conflicts
+--------------------
+
+This is not a problem of unreproducibility, but of generated files
+being *too* reproducible.
+
+Once you set all the necessary variables for a reproducible build, a
+vDSO's debug information may be identical even for different kernel
+versions. This can result in file conflicts between debug information
+packages for the different kernel versions.
+
+To avoid this, you can make the vDSO different for different
+kernel versions by including an arbitrary string of "salt" in it.
+This is specified by the Kconfig symbol ``CONFIG_BUILD_SALT``.
+
+.. _KBUILD_BUILD_TIMESTAMP: kbuild.html#kbuild-build-timestamp
+.. _KBUILD_BUILD_USER and KBUILD_BUILD_HOST: kbuild.html#kbuild-build-user-kbuild-build-host
+.. _KCFLAGS: kbuild.html#kcflags
+.. _prefix-map options: https://reproducible-builds.org/docs/build-path/
+.. _Reproducible Builds project: https://reproducible-builds.org/
+.. _SOURCE_DATE_EPOCH: https://reproducible-builds.org/docs/source-date-epoch/
diff --git a/Documentation/kernel-hacking/hacking.rst b/Documentation/kernel-hacking/hacking.rst
index 5891a70..a3ddb21 100644
--- a/Documentation/kernel-hacking/hacking.rst
+++ b/Documentation/kernel-hacking/hacking.rst
@@ -594,6 +594,24 @@
maintainers and developers may however require EXPORT_SYMBOL_GPL()
when adding any new APIs or functionality.
+:c:func:`EXPORT_SYMBOL_NS()`
+----------------------------
+
+Defined in ``include/linux/export.h``
+
+This is the variant of `EXPORT_SYMBOL()` that allows specifying a symbol
+namespace. Symbol Namespaces are documented in
+``Documentation/kbuild/namespaces.rst``.
+
+:c:func:`EXPORT_SYMBOL_NS_GPL()`
+--------------------------------
+
+Defined in ``include/linux/export.h``
+
+This is the variant of `EXPORT_SYMBOL_GPL()` that allows specifying a symbol
+namespace. Symbol Namespaces are documented in
+``Documentation/kbuild/namespaces.rst``.
+
Routines and Conventions
========================
diff --git a/Documentation/leds/leds-class.rst b/Documentation/leds/leds-class.rst
index df0120a..a0708d3 100644
--- a/Documentation/leds/leds-class.rst
+++ b/Documentation/leds/leds-class.rst
@@ -43,9 +43,73 @@
Is currently of the form:
- "devicename:colour:function"
+ "devicename:color:function"
-There have been calls for LED properties such as colour to be exported as
+- devicename:
+ it should refer to a unique identifier created by the kernel,
+ like e.g. phyN for network devices or inputN for input devices, rather
+ than to the hardware; the information related to the product and the bus
+ to which given device is hooked is available in sysfs and can be
+ retrieved using get_led_device_info.sh script from tools/leds; generally
+ this section is expected mostly for LEDs that are somehow associated with
+ other devices.
+
+- color:
+ one of LED_COLOR_ID_* definitions from the header
+ include/dt-bindings/leds/common.h.
+
+- function:
+ one of LED_FUNCTION_* definitions from the header
+ include/dt-bindings/leds/common.h.
+
+If required color or function is missing, please submit a patch
+to linux-leds@vger.kernel.org.
+
+It is possible that more than one LED with the same color and function will
+be required for given platform, differing only with an ordinal number.
+In this case it is preferable to just concatenate the predefined LED_FUNCTION_*
+name with required "-N" suffix in the driver. fwnode based drivers can use
+function-enumerator property for that and then the concatenation will be handled
+automatically by the LED core upon LED class device registration.
+
+LED subsystem has also a protection against name clash, that may occur
+when LED class device is created by a driver of hot-pluggable device and
+it doesn't provide unique devicename section. In this case numerical
+suffix (e.g. "_1", "_2", "_3" etc.) is added to the requested LED class
+device name.
+
+There might be still LED class drivers around using vendor or product name
+for devicename, but this approach is now deprecated as it doesn't convey
+any added value. Product information can be found in other places in sysfs
+(see tools/leds/get_led_device_info.sh).
+
+Examples of proper LED names:
+
+ - "red:disk"
+ - "white:flash"
+ - "red:indicator"
+ - "phy1:green:wlan"
+ - "phy3::wlan"
+ - ":kbd_backlight"
+ - "input5::kbd_backlight"
+ - "input3::numlock"
+ - "input3::scrolllock"
+ - "input3::capslock"
+ - "mmc1::status"
+ - "white:status"
+
+get_led_device_info.sh script can be used for verifying if the LED name
+meets the requirements pointed out here. It performs validation of the LED class
+devicename sections and gives hints on expected value for a section in case
+the validation fails for it. So far the script supports validation
+of associations between LEDs and following types of devices:
+
+ - input devices
+ - ieee80211 compliant USB devices
+
+The script is open to extensions.
+
+There have been calls for LED properties such as color to be exported as
individual led class attributes. As a solution which doesn't incur as much
overhead, I suggest these become part of the device name. The naming scheme
above leaves scope for further attributes should they be needed. If sections
diff --git a/Documentation/locking/spinlocks.rst b/Documentation/locking/spinlocks.rst
index e93ec66..66e3792 100644
--- a/Documentation/locking/spinlocks.rst
+++ b/Documentation/locking/spinlocks.rst
@@ -139,18 +139,6 @@
CPU that holds the lock, so the lock-holder can continue and eventually
releases the lock).
-Note that you can be clever with read-write locks and interrupts. For
-example, if you know that the interrupt only ever gets a read-lock, then
-you can use a non-irq version of read locks everywhere - because they
-don't block on each other (and thus there is no dead-lock wrt interrupts.
-But when you do the write-lock, you have to use the irq-safe version.
-
-For an example of being clever with rw-locks, see the "waitqueue_lock"
-handling in kernel/sched/core.c - nothing ever _changes_ a wait-queue from
-within an interrupt, they only read the queue in order to know whom to
-wake up. So read-locks are safe (which is good: they are very common
-indeed), while write-locks need to protect themselves against interrupts.
-
Linus
----
diff --git a/Documentation/m68k/README.buddha b/Documentation/m68k/README.buddha
deleted file mode 100644
index 3ea9827..0000000
--- a/Documentation/m68k/README.buddha
+++ /dev/null
@@ -1,210 +0,0 @@
-
-The Amiga Buddha and Catweasel IDE Driver (part of ide.c) was written by
-Geert Uytterhoeven based on the following specifications:
-
-------------------------------------------------------------------------
-
-Register map of the Buddha IDE controller and the
-Buddha-part of the Catweasel Zorro-II version
-
-The Autoconfiguration has been implemented just as Commodore
-described in their manuals, no tricks have been used (for
-example leaving some address lines out of the equations...).
-If you want to configure the board yourself (for example let
-a Linux kernel configure the card), look at the Commodore
-Docs. Reading the nibbles should give this information:
-
-Vendor number: 4626 ($1212)
-product number: 0 (42 for Catweasel Z-II)
-Serial number: 0
-Rom-vector: $1000
-
-The card should be a Z-II board, size 64K, not for freemem
-list, Rom-Vektor is valid, no second Autoconfig-board on the
-same card, no space preference, supports "Shutup_forever".
-
-Setting the base address should be done in two steps, just
-as the Amiga Kickstart does: The lower nibble of the 8-Bit
-address is written to $4a, then the whole Byte is written to
-$48, while it doesn't matter how often you're writing to $4a
-as long as $48 is not touched. After $48 has been written,
-the whole card disappears from $e8 and is mapped to the new
-address just written. Make sure $4a is written before $48,
-otherwise your chance is only 1:16 to find the board :-).
-
-The local memory-map is even active when mapped to $e8:
-
-$0-$7e Autokonfig-space, see Z-II docs.
-
-$80-$7fd reserved
-
-$7fe Speed-select Register: Read & Write
- (description see further down)
-
-$800-$8ff IDE-Select 0 (Port 0, Register set 0)
-
-$900-$9ff IDE-Select 1 (Port 0, Register set 1)
-
-$a00-$aff IDE-Select 2 (Port 1, Register set 0)
-
-$b00-$bff IDE-Select 3 (Port 1, Register set 1)
-
-$c00-$cff IDE-Select 4 (Port 2, Register set 0,
- Catweasel only!)
-
-$d00-$dff IDE-Select 5 (Port 3, Register set 1,
- Catweasel only!)
-
-$e00-$eff local expansion port, on Catweasel Z-II the
- Catweasel registers are also mapped here.
- Never touch, use multidisk.device!
-
-$f00 read only, Byte-access: Bit 7 shows the
- level of the IRQ-line of IDE port 0.
-
-$f01-$f3f mirror of $f00
-
-$f40 read only, Byte-access: Bit 7 shows the
- level of the IRQ-line of IDE port 1.
-
-$f41-$f7f mirror of $f40
-
-$f80 read only, Byte-access: Bit 7 shows the
- level of the IRQ-line of IDE port 2.
- (Catweasel only!)
-
-$f81-$fbf mirror of $f80
-
-$fc0 write-only: Writing any value to this
- register enables IRQs to be passed from the
- IDE ports to the Zorro bus. This mechanism
- has been implemented to be compatible with
- harddisks that are either defective or have
- a buggy firmware and pull the IRQ line up
- while starting up. If interrupts would
- always be passed to the bus, the computer
- might not start up. Once enabled, this flag
- can not be disabled again. The level of the
- flag can not be determined by software
- (what for? Write to me if it's necessary!).
-
-$fc1-$fff mirror of $fc0
-
-$1000-$ffff Buddha-Rom with offset $1000 in the rom
- chip. The addresses $0 to $fff of the rom
- chip cannot be read. Rom is Byte-wide and
- mapped to even addresses.
-
-The IDE ports issue an INT2. You can read the level of the
-IRQ-lines of the IDE-ports by reading from the three (two
-for Buddha-only) registers $f00, $f40 and $f80. This way
-more than one I/O request can be handled and you can easily
-determine what driver has to serve the INT2. Buddha and
-Catweasel expansion boards can issue an INT6. A separate
-memory map is available for the I/O module and the sysop's
-I/O module.
-
-The IDE ports are fed by the address lines A2 to A4, just as
-the Amiga 1200 and Amiga 4000 IDE ports are. This way
-existing drivers can be easily ported to Buddha. A move.l
-polls two words out of the same address of IDE port since
-every word is mirrored once. movem is not possible, but
-it's not necessary either, because you can only speedup
-68000 systems with this technique. A 68020 system with
-fastmem is faster with move.l.
-
-If you're using the mirrored registers of the IDE-ports with
-A6=1, the Buddha doesn't care about the speed that you have
-selected in the speed register (see further down). With
-A6=1 (for example $840 for port 0, register set 0), a 780ns
-access is being made. These registers should be used for a
-command access to the harddisk/CD-Rom, since command
-accesses are Byte-wide and have to be made slower according
-to the ATA-X3T9 manual.
-
-Now for the speed-register: The register is byte-wide, and
-only the upper three bits are used (Bits 7 to 5). Bit 4
-must always be set to 1 to be compatible with later Buddha
-versions (if I'll ever update this one). I presume that
-I'll never use the lower four bits, but they have to be set
-to 1 by definition.
- The values in this table have to be shifted 5 bits to the
-left and or'd with $1f (this sets the lower 5 bits).
-
-All the timings have in common: Select and IOR/IOW rise at
-the same time. IOR and IOW have a propagation delay of
-about 30ns to the clocks on the Zorro bus, that's why the
-values are no multiple of 71. One clock-cycle is 71ns long
-(exactly 70,5 at 14,18 Mhz on PAL systems).
-
-value 0 (Default after reset)
-
-497ns Select (7 clock cycles) , IOR/IOW after 172ns (2 clock cycles)
-(same timing as the Amiga 1200 does on it's IDE port without
-accelerator card)
-
-value 1
-
-639ns Select (9 clock cycles), IOR/IOW after 243ns (3 clock cycles)
-
-value 2
-
-781ns Select (11 clock cycles), IOR/IOW after 314ns (4 clock cycles)
-
-value 3
-
-355ns Select (5 clock cycles), IOR/IOW after 101ns (1 clock cycle)
-
-value 4
-
-355ns Select (5 clock cycles), IOR/IOW after 172ns (2 clock cycles)
-
-value 5
-
-355ns Select (5 clock cycles), IOR/IOW after 243ns (3 clock cycles)
-
-value 6
-
-1065ns Select (15 clock cycles), IOR/IOW after 314ns (4 clock cycles)
-
-value 7
-
-355ns Select, (5 clock cycles), IOR/IOW after 101ns (1 clock cycle)
-
-When accessing IDE registers with A6=1 (for example $84x),
-the timing will always be mode 0 8-bit compatible, no matter
-what you have selected in the speed register:
-
-781ns select, IOR/IOW after 4 clock cycles (=314ns) aktive.
-
-All the timings with a very short select-signal (the 355ns
-fast accesses) depend on the accelerator card used in the
-system: Sometimes two more clock cycles are inserted by the
-bus interface, making the whole access 497ns long. This
-doesn't affect the reliability of the controller nor the
-performance of the card, since this doesn't happen very
-often.
-
-All the timings are calculated and only confirmed by
-measurements that allowed me to count the clock cycles. If
-the system is clocked by an oscillator other than 28,37516
-Mhz (for example the NTSC-frequency 28,63636 Mhz), each
-clock cycle is shortened to a bit less than 70ns (not worth
-mentioning). You could think of a small performance boost
-by overclocking the system, but you would either need a
-multisync monitor, or a graphics card, and your internal
-diskdrive would go crazy, that's why you shouldn't tune your
-Amiga this way.
-
-Giving you the possibility to write software that is
-compatible with both the Buddha and the Catweasel Z-II, The
-Buddha acts just like a Catweasel Z-II with no device
-connected to the third IDE-port. The IRQ-register $f80
-always shows a "no IRQ here" on the Buddha, and accesses to
-the third IDE port are going into data's Nirwana on the
-Buddha.
-
- Jens Schönfeld february 19th, 1997
- updated may 27th, 1997
- eMail: sysop@nostlgic.tng.oche.de
-
diff --git a/Documentation/m68k/buddha-driver.rst b/Documentation/m68k/buddha-driver.rst
new file mode 100644
index 0000000..20e4014
--- /dev/null
+++ b/Documentation/m68k/buddha-driver.rst
@@ -0,0 +1,209 @@
+=====================================
+Amiga Buddha and Catweasel IDE Driver
+=====================================
+
+The Amiga Buddha and Catweasel IDE Driver (part of ide.c) was written by
+Geert Uytterhoeven based on the following specifications:
+
+------------------------------------------------------------------------
+
+Register map of the Buddha IDE controller and the
+Buddha-part of the Catweasel Zorro-II version
+
+The Autoconfiguration has been implemented just as Commodore
+described in their manuals, no tricks have been used (for
+example leaving some address lines out of the equations...).
+If you want to configure the board yourself (for example let
+a Linux kernel configure the card), look at the Commodore
+Docs. Reading the nibbles should give this information::
+
+ Vendor number: 4626 ($1212)
+ product number: 0 (42 for Catweasel Z-II)
+ Serial number: 0
+ Rom-vector: $1000
+
+The card should be a Z-II board, size 64K, not for freemem
+list, Rom-Vektor is valid, no second Autoconfig-board on the
+same card, no space preference, supports "Shutup_forever".
+
+Setting the base address should be done in two steps, just
+as the Amiga Kickstart does: The lower nibble of the 8-Bit
+address is written to $4a, then the whole Byte is written to
+$48, while it doesn't matter how often you're writing to $4a
+as long as $48 is not touched. After $48 has been written,
+the whole card disappears from $e8 and is mapped to the new
+address just written. Make sure $4a is written before $48,
+otherwise your chance is only 1:16 to find the board :-).
+
+The local memory-map is even active when mapped to $e8:
+
+============== ===========================================
+$0-$7e Autokonfig-space, see Z-II docs.
+
+$80-$7fd reserved
+
+$7fe Speed-select Register: Read & Write
+ (description see further down)
+
+$800-$8ff IDE-Select 0 (Port 0, Register set 0)
+
+$900-$9ff IDE-Select 1 (Port 0, Register set 1)
+
+$a00-$aff IDE-Select 2 (Port 1, Register set 0)
+
+$b00-$bff IDE-Select 3 (Port 1, Register set 1)
+
+$c00-$cff IDE-Select 4 (Port 2, Register set 0,
+ Catweasel only!)
+
+$d00-$dff IDE-Select 5 (Port 3, Register set 1,
+ Catweasel only!)
+
+$e00-$eff local expansion port, on Catweasel Z-II the
+ Catweasel registers are also mapped here.
+ Never touch, use multidisk.device!
+
+$f00 read only, Byte-access: Bit 7 shows the
+ level of the IRQ-line of IDE port 0.
+
+$f01-$f3f mirror of $f00
+
+$f40 read only, Byte-access: Bit 7 shows the
+ level of the IRQ-line of IDE port 1.
+
+$f41-$f7f mirror of $f40
+
+$f80 read only, Byte-access: Bit 7 shows the
+ level of the IRQ-line of IDE port 2.
+ (Catweasel only!)
+
+$f81-$fbf mirror of $f80
+
+$fc0 write-only: Writing any value to this
+ register enables IRQs to be passed from the
+ IDE ports to the Zorro bus. This mechanism
+ has been implemented to be compatible with
+ harddisks that are either defective or have
+ a buggy firmware and pull the IRQ line up
+ while starting up. If interrupts would
+ always be passed to the bus, the computer
+ might not start up. Once enabled, this flag
+ can not be disabled again. The level of the
+ flag can not be determined by software
+ (what for? Write to me if it's necessary!).
+
+$fc1-$fff mirror of $fc0
+
+$1000-$ffff Buddha-Rom with offset $1000 in the rom
+ chip. The addresses $0 to $fff of the rom
+ chip cannot be read. Rom is Byte-wide and
+ mapped to even addresses.
+============== ===========================================
+
+The IDE ports issue an INT2. You can read the level of the
+IRQ-lines of the IDE-ports by reading from the three (two
+for Buddha-only) registers $f00, $f40 and $f80. This way
+more than one I/O request can be handled and you can easily
+determine what driver has to serve the INT2. Buddha and
+Catweasel expansion boards can issue an INT6. A separate
+memory map is available for the I/O module and the sysop's
+I/O module.
+
+The IDE ports are fed by the address lines A2 to A4, just as
+the Amiga 1200 and Amiga 4000 IDE ports are. This way
+existing drivers can be easily ported to Buddha. A move.l
+polls two words out of the same address of IDE port since
+every word is mirrored once. movem is not possible, but
+it's not necessary either, because you can only speedup
+68000 systems with this technique. A 68020 system with
+fastmem is faster with move.l.
+
+If you're using the mirrored registers of the IDE-ports with
+A6=1, the Buddha doesn't care about the speed that you have
+selected in the speed register (see further down). With
+A6=1 (for example $840 for port 0, register set 0), a 780ns
+access is being made. These registers should be used for a
+command access to the harddisk/CD-Rom, since command
+accesses are Byte-wide and have to be made slower according
+to the ATA-X3T9 manual.
+
+Now for the speed-register: The register is byte-wide, and
+only the upper three bits are used (Bits 7 to 5). Bit 4
+must always be set to 1 to be compatible with later Buddha
+versions (if I'll ever update this one). I presume that
+I'll never use the lower four bits, but they have to be set
+to 1 by definition.
+
+The values in this table have to be shifted 5 bits to the
+left and or'd with $1f (this sets the lower 5 bits).
+
+All the timings have in common: Select and IOR/IOW rise at
+the same time. IOR and IOW have a propagation delay of
+about 30ns to the clocks on the Zorro bus, that's why the
+values are no multiple of 71. One clock-cycle is 71ns long
+(exactly 70,5 at 14,18 Mhz on PAL systems).
+
+value 0 (Default after reset)
+ 497ns Select (7 clock cycles) , IOR/IOW after 172ns (2 clock cycles)
+ (same timing as the Amiga 1200 does on it's IDE port without
+ accelerator card)
+
+value 1
+ 639ns Select (9 clock cycles), IOR/IOW after 243ns (3 clock cycles)
+
+value 2
+ 781ns Select (11 clock cycles), IOR/IOW after 314ns (4 clock cycles)
+
+value 3
+ 355ns Select (5 clock cycles), IOR/IOW after 101ns (1 clock cycle)
+
+value 4
+ 355ns Select (5 clock cycles), IOR/IOW after 172ns (2 clock cycles)
+
+value 5
+ 355ns Select (5 clock cycles), IOR/IOW after 243ns (3 clock cycles)
+
+value 6
+ 1065ns Select (15 clock cycles), IOR/IOW after 314ns (4 clock cycles)
+
+value 7
+ 355ns Select, (5 clock cycles), IOR/IOW after 101ns (1 clock cycle)
+
+When accessing IDE registers with A6=1 (for example $84x),
+the timing will always be mode 0 8-bit compatible, no matter
+what you have selected in the speed register:
+
+781ns select, IOR/IOW after 4 clock cycles (=314ns) aktive.
+
+All the timings with a very short select-signal (the 355ns
+fast accesses) depend on the accelerator card used in the
+system: Sometimes two more clock cycles are inserted by the
+bus interface, making the whole access 497ns long. This
+doesn't affect the reliability of the controller nor the
+performance of the card, since this doesn't happen very
+often.
+
+All the timings are calculated and only confirmed by
+measurements that allowed me to count the clock cycles. If
+the system is clocked by an oscillator other than 28,37516
+Mhz (for example the NTSC-frequency 28,63636 Mhz), each
+clock cycle is shortened to a bit less than 70ns (not worth
+mentioning). You could think of a small performance boost
+by overclocking the system, but you would either need a
+multisync monitor, or a graphics card, and your internal
+diskdrive would go crazy, that's why you shouldn't tune your
+Amiga this way.
+
+Giving you the possibility to write software that is
+compatible with both the Buddha and the Catweasel Z-II, The
+Buddha acts just like a Catweasel Z-II with no device
+connected to the third IDE-port. The IRQ-register $f80
+always shows a "no IRQ here" on the Buddha, and accesses to
+the third IDE port are going into data's Nirwana on the
+Buddha.
+
+Jens Schönfeld february 19th, 1997
+
+updated may 27th, 1997
+
+eMail: sysop@nostlgic.tng.oche.de
diff --git a/Documentation/m68k/index.rst b/Documentation/m68k/index.rst
index 3a5ba7f..b89cb6a 100644
--- a/Documentation/m68k/index.rst
+++ b/Documentation/m68k/index.rst
@@ -8,6 +8,7 @@
:maxdepth: 2
kernel-options
+ buddha-driver
.. only:: subproject and html
diff --git a/Documentation/maintainer/pull-requests.rst b/Documentation/maintainer/pull-requests.rst
index 22b271d..1a2f99b 100644
--- a/Documentation/maintainer/pull-requests.rst
+++ b/Documentation/maintainer/pull-requests.rst
@@ -29,7 +29,7 @@
In order to create the pull request you must first tag the branch that you
have just created. It is recommended that you choose a meaningful tag name,
in a way that you and others can understand, even after some time. A good
-practice is to include in the name an indicator of the sybsystem of origin
+practice is to include in the name an indicator of the subsystem of origin
and the target kernel version.
Greg offers the following. A pull request with miscellaneous stuff for
diff --git a/Documentation/media/kapi/csi2.rst b/Documentation/media/kapi/csi2.rst
index a7e75e2..030a5c4 100644
--- a/Documentation/media/kapi/csi2.rst
+++ b/Documentation/media/kapi/csi2.rst
@@ -49,9 +49,13 @@
The transmitter drivers must, if possible, configure the CSI-2
transmitter to *LP-11 mode* whenever the transmitter is powered on but
-not active. Some transmitters do this automatically but some have to
-be explicitly programmed to do so, and some are unable to do so
-altogether due to hardware constraints.
+not active, and maintain *LP-11 mode* until stream on. Only at stream
+on should the transmitter activate the clock on the clock lane and
+transition to *HS mode*.
+
+Some transmitters do this automatically but some have to be explicitly
+programmed to do so, and some are unable to do so altogether due to
+hardware constraints.
Stopping the transmitter
^^^^^^^^^^^^^^^^^^^^^^^^
@@ -72,3 +76,10 @@
:c:type:`v4l2_subdev_core_ops`->s_power() callback. This may take
place either indirectly by using :c:func:`v4l2_pipeline_pm_use` or
directly.
+
+Formats
+-------
+
+The media bus pixel codes document parallel formats. Should the pixel data be
+transported over a serial bus, the media bus pixel code that describes a
+parallel format that transfers a sample on a single clock cycle is used.
diff --git a/Documentation/media/kapi/v4l2-dev.rst b/Documentation/media/kapi/v4l2-dev.rst
index b359f18..4c5a15c 100644
--- a/Documentation/media/kapi/v4l2-dev.rst
+++ b/Documentation/media/kapi/v4l2-dev.rst
@@ -288,6 +288,7 @@
0x08 Log the read and write file operations and the VIDIOC_QBUF and
VIDIOC_DQBUF ioctls.
0x10 Log the poll file operation.
+0x20 Log error and messages in the control operations.
===== ================================================================
Video device cleanup
diff --git a/Documentation/media/uapi/rc/lirc-dev-intro.rst b/Documentation/media/uapi/rc/lirc-dev-intro.rst
index 1a901d8..b68c016 100644
--- a/Documentation/media/uapi/rc/lirc-dev-intro.rst
+++ b/Documentation/media/uapi/rc/lirc-dev-intro.rst
@@ -20,6 +20,9 @@
file_operations defined on it. With respect to transporting raw IR and
decoded scancodes to and fro, the essential fops are read, write and ioctl.
+It is also possible to attach a BPF program to a LIRC device for decoding
+raw IR into scancodes.
+
Example dmesg output upon a driver registering w/LIRC:
.. code-block:: none
@@ -34,6 +37,16 @@
$ ls -l /dev/lirc*
crw-rw---- 1 root root 248, 0 Jul 2 22:20 /dev/lirc0
+Note that the package `v4l-utils <https://git.linuxtv.org/v4l-utils.git/>`_
+contains tools for working with LIRC devices:
+
+ - ir-ctl: can receive raw IR and transmit IR, as well as query LIRC
+ device features.
+
+ - ir-keytable: can load keymaps; allows you to set IR kernel protocols; load
+ BPF IR decoders and test IR decoding. Some BPF IR decoders are also
+ provided.
+
.. _lirc_modes:
**********
@@ -53,11 +66,12 @@
For transmitting (aka sending), create a ``struct lirc_scancode`` with
the desired scancode set in the ``scancode`` member, :c:type:`rc_proto`
- set the IR protocol, and all other members set to 0. Write this struct to
- the lirc device.
+ set to the :ref:`IR protocol <Remote_controllers_Protocols>`, and all other
+ members set to 0. Write this struct to the lirc device.
- For receiving, you read ``struct lirc_scancode`` from the lirc device,
- with ``scancode`` set to the received scancode and the IR protocol
+ For receiving, you read ``struct lirc_scancode`` from the LIRC device.
+ The ``scancode`` field is set to the received scancode and the
+ :ref:`IR protocol <Remote_controllers_Protocols>` is set in
:c:type:`rc_proto`. If the scancode maps to a valid key code, this is set
in the ``keycode`` field, else it is set to ``KEY_RESERVED``.
@@ -129,12 +143,29 @@
This mode is used only for IR send.
+********************
+BPF based IR decoder
+********************
-**************************
-Remote Controller protocol
-**************************
+The kernel has support for decoding the most common
+:ref:`IR protocols <Remote_controllers_Protocols>`, but there
+are many protocols which are not supported. To support these, it is possible
+to load an BPF program which does the decoding. This can only be done on
+LIRC devices which support reading raw IR.
-An enum :c:type:`rc_proto` in the :ref:`lirc_header` lists all the
-supported IR protocols:
+First, using the `bpf(2)`_ syscall with the ``BPF_LOAD_PROG`` argument,
+program must be loaded of type ``BPF_PROG_TYPE_LIRC_MODE2``. Once attached
+to the LIRC device, this program will be called for each pulse, space or
+timeout event on the LIRC device. The context for the BPF program is a
+pointer to a unsigned int, which is a :ref:`LIRC_MODE_MODE2 <lirc-mode-mode2>`
+value. When the program has decoded the scancode, it can be submitted using
+the BPF functions ``bpf_rc_keydown()`` or ``bpf_rc_repeat()``. Mouse or pointer
+movements can be reported using ``bpf_rc_pointer_rel()``.
-.. kernel-doc:: include/uapi/linux/lirc.h
+Once you have the file descriptor for the ``BPF_PROG_TYPE_LIRC_MODE2`` BPF
+program, it can be attached to the LIRC device using the `bpf(2)`_ syscall.
+The target must be the file descriptor for the LIRC device, and the
+attach type must be ``BPF_LIRC_MODE2``. No more than 64 BPF programs can be
+attached to a single LIRC device at a time.
+
+.. _bpf(2): http://man7.org/linux/man-pages/man2/bpf.2.html
diff --git a/Documentation/media/uapi/rc/lirc-read.rst b/Documentation/media/uapi/rc/lirc-read.rst
index a8fedfa..256e520 100644
--- a/Documentation/media/uapi/rc/lirc-read.rst
+++ b/Documentation/media/uapi/rc/lirc-read.rst
@@ -62,7 +62,8 @@
Alternatively, :ref:`LIRC_MODE_SCANCODE <lirc-mode-scancode>` can be available,
in this mode scancodes which are either decoded by software decoders, or
by hardware decoders. The :c:type:`rc_proto` member is set to the
-protocol used for transmission, and ``scancode`` to the decoded scancode,
+:ref:`IR protocol <Remote_controllers_Protocols>`
+used for transmission, and ``scancode`` to the decoded scancode,
and the ``keycode`` set to the keycode or ``KEY_RESERVED``.
diff --git a/Documentation/media/uapi/rc/lirc-write.rst b/Documentation/media/uapi/rc/lirc-write.rst
index 6adf5dd..eafe132 100644
--- a/Documentation/media/uapi/rc/lirc-write.rst
+++ b/Documentation/media/uapi/rc/lirc-write.rst
@@ -64,7 +64,8 @@
When in :ref:`LIRC_MODE_SCANCODE <lirc-mode-scancode>` mode, one
``struct lirc_scancode`` must be written to the chardev at a time, else
``EINVAL`` is returned. Set the desired scancode in the ``scancode`` member,
-and the protocol in the :c:type:`rc_proto`: member. All other members must be
+and the :ref:`IR protocol <Remote_controllers_Protocols>` in the
+:c:type:`rc_proto`: member. All other members must be
set to 0, else ``EINVAL`` is returned. If there is no protocol encoder
for the protocol or the scancode is not valid for the specified protocol,
``EINVAL`` is returned. The write function blocks until the scancode
diff --git a/Documentation/media/uapi/rc/rc-protos.rst b/Documentation/media/uapi/rc/rc-protos.rst
new file mode 100644
index 0000000..b250ebe3
--- /dev/null
+++ b/Documentation/media/uapi/rc/rc-protos.rst
@@ -0,0 +1,456 @@
+.. SPDX-License-Identifier: GPL-2.0
+..
+.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
+
+.. _Remote_controllers_Protocols:
+
+*****************************************
+Remote Controller Protocols and Scancodes
+*****************************************
+
+IR is encoded as a series of pulses and spaces, using a protocol. These
+protocols can encode e.g. an address (which device should respond) and a
+command: what it should do. The values for these are not always consistent
+across different devices for a given protocol.
+
+Therefore out the output of the IR decoder is a scancode; a single u32
+value. Using keymap tables this can be mapped to linux key codes.
+
+Other things can be encoded too. Some IR protocols encode a toggle bit; this
+is to distinguish whether the same button is being held down, or has been
+released and pressed again. If has been released and pressed again, the
+toggle bit will invert from one IR message to the next.
+
+Some remotes have a pointer-type device which can used to control the
+mouse; some air conditioning systems can have their target temperature
+target set in IR.
+
+The following are the protocols the kernel knows about and also lists
+how scancodes are encoded for each protocol.
+
+rc-5 (RC_PROTO_RC5)
+-------------------
+
+This IR protocol uses manchester encoding to encode 14 bits. There is a
+detailed description here https://www.sbprojects.net/knowledge/ir/rc5.php.
+
+The scancode encoding is *not* consistent with the lirc daemon (lircd) rc5
+protocol, or the manchester BPF decoder.
+
+.. flat-table:: rc5 bits scancode mapping
+ :widths: 1 1 2
+
+ * - rc-5 bit
+
+ - scancode bit
+
+ - description
+
+ * - 1
+
+ - none
+
+ - Start bit, always set
+
+ * - 1
+
+ - 6 (inverted)
+
+ - 2nd start bit in rc5, re-used as 6th command bit
+
+ * - 1
+
+ - none
+
+ - Toggle bit
+
+ * - 5
+
+ - 8 to 13
+
+ - Address
+
+ * - 6
+
+ - 0 to 5
+
+ - Command
+
+There is a variant of rc5 called either rc5x or extended rc5
+where there the second stop bit is the 6th commmand bit, but inverted.
+This is done so it the scancodes and encoding is compatible with existing
+schemes. This bit is stored in bit 6 of the scancode, inverted. This is
+done to keep it compatible with plain rc-5 where there are two start bits.
+
+rc-5-sz (RC_PROTO_RC5_SZ)
+-------------------------
+This is much like rc-5 but one bit longer. The scancode is encoded
+differently.
+
+.. flat-table:: rc-5-sz bits scancode mapping
+ :widths: 1 1 2
+
+ * - rc-5-sz bits
+
+ - scancode bit
+
+ - description
+
+ * - 1
+
+ - none
+
+ - Start bit, always set
+
+ * - 1
+
+ - 13
+
+ - Address bit
+
+ * - 1
+
+ - none
+
+ - Toggle bit
+
+ * - 6
+
+ - 6 to 11
+
+ - Address
+
+ * - 6
+
+ - 0 to 5
+
+ - Command
+
+rc-5x-20 (RC_PROTO_RC5X_20)
+---------------------------
+
+This rc-5 extended to encoded 20 bits. The is a 3555 microseconds space
+after the 8th bit.
+
+.. flat-table:: rc-5x-20 bits scancode mapping
+ :widths: 1 1 2
+
+ * - rc-5-sz bits
+
+ - scancode bit
+
+ - description
+
+ * - 1
+
+ - none
+
+ - Start bit, always set
+
+ * - 1
+
+ - 14
+
+ - Address bit
+
+ * - 1
+
+ - none
+
+ - Toggle bit
+
+ * - 5
+
+ - 16 to 20
+
+ - Address
+
+ * - 6
+
+ - 8 to 13
+
+ - Address
+
+ * - 6
+
+ - 0 to 5
+
+ - Command
+
+
+jvc (RC_PROTO_JVC)
+------------------
+
+The jvc protocol is much like nec, without the inverted values. It is
+described here https://www.sbprojects.net/knowledge/ir/jvc.php.
+
+The scancode is a 16 bits value, where the address is the lower 8 bits
+and the command the higher 8 bits; this is reversed from IR order.
+
+sony-12 (RC_PROTO_SONY12)
+-------------------------
+
+The sony protocol is a pulse-width encoding. There are three variants,
+which just differ in number of bits and scancode encoding.
+
+.. flat-table:: sony-12 bits scancode mapping
+ :widths: 1 1 2
+
+ * - sony-12 bits
+
+ - scancode bit
+
+ - description
+
+ * - 5
+
+ - 16 to 20
+
+ - device
+
+ * - 7
+
+ - 0 to 6
+
+ - function
+
+sony-15 (RC_PROTO_SONY15)
+-------------------------
+
+The sony protocol is a pulse-width encoding. There are three variants,
+which just differ in number of bits and scancode encoding.
+
+.. flat-table:: sony-12 bits scancode mapping
+ :widths: 1 1 2
+
+ * - sony-12 bits
+
+ - scancode bit
+
+ - description
+
+ * - 8
+
+ - 16 to 23
+
+ - device
+
+ * - 7
+
+ - 0 to 6
+
+ - function
+
+sony-20 (RC_PROTO_SONY20)
+-------------------------
+
+The sony protocol is a pulse-width encoding. There are three variants,
+which just differ in number of bits and scancode encoding.
+
+.. flat-table:: sony-20 bits scancode mapping
+ :widths: 1 1 2
+
+ * - sony-20 bits
+
+ - scancode bit
+
+ - description
+
+ * - 5
+
+ - 16 to 20
+
+ - device
+
+ * - 7
+
+ - 0 to 7
+
+ - device
+
+ * - 8
+
+ - 8 to 15
+
+ - extended bits
+
+nec (RC_PROTO_NEC)
+------------------
+
+The nec protocol encodes an 8 bit address and an 8 bit command. It is
+described here https://www.sbprojects.net/knowledge/ir/nec.php. Note
+that the protocol sends least significant bit first.
+
+As a check, the nec protocol sends the address and command twice; the
+second time it is inverted. This is done for verification.
+
+A plain nec IR message has 16 bits; the high 8 bits are the address
+and the low 8 bits are the command.
+
+nec-x (RC_PROTO_NECX)
+---------------------
+
+Extended nec has a 16 bit address and a 8 bit command. This is encoded
+as a 24 bit value as you would expect, with the lower 8 bits the command
+and the upper 16 bits the address.
+
+nec-32 (RC_PROTO_NEC32)
+-----------------------
+
+nec-32 does not send an inverted address or an inverted command; the
+entire message, all 32 bits, are used.
+
+For this to be decoded correctly, the second 8 bits must not be the
+inverted value of the first, and also the last 8 bits must not be the
+inverted value of the third 8 bit value.
+
+The scancode has a somewhat unusual encoding.
+
+.. flat-table:: nec-32 bits scancode mapping
+
+ * - nec-32 bits
+
+ - scancode bit
+
+ * - First 8 bits
+
+ - 16 to 23
+
+ * - Second 8 bits
+
+ - 24 to 31
+
+ * - Third 8 bits
+
+ - 0 to 7
+
+ * - Fourth 8 bits
+
+ - 8 to 15
+
+sanyo (RC_PROTO_SANYO)
+----------------------
+
+The sanyo protocol is like the nec protocol, but with 13 bits address
+rather than 8 bits. Both the address and the command are followed by
+their inverted versions, but these are not present in the scancodes.
+
+Bis 8 to 20 of the scancode is the 13 bits address, and the lower 8
+bits are the command.
+
+mcir2-kbd (RC_PROTO_MCIR2_KBD)
+------------------------------
+
+This protocol is generated by the Microsoft MCE keyboard for keyboard
+events. Refer to the ir-mce_kbd-decoder.c to see how it is encoded.
+
+mcir2-mse (RC_PROTO_MCIR2_MSE)
+------------------------------
+
+This protocol is generated by the Microsoft MCE keyboard for pointer
+events. Refer to the ir-mce_kbd-decoder.c to see how it is encoded.
+
+rc-6-0 (RC_PROTO_RC6_0)
+-----------------------
+
+This is the rc-6 in mode 0. rc-6 is described here
+https://www.sbprojects.net/knowledge/ir/rc6.php.
+The scancode is the exact 16 bits as in the protocol. There is also a
+toggle bit.
+
+rc-6-6a-20 (RC_PROTO_RC6_6A_20)
+-------------------------------
+
+This is the rc-6 in mode 6a, 20 bits. rc-6 is described here
+https://www.sbprojects.net/knowledge/ir/rc6.php.
+The scancode is the exact 20 bits
+as in the protocol. There is also a toggle bit.
+
+rc-6-6a-24 (RC_PROTO_RC6_6A_24)
+-------------------------------
+
+This is the rc-6 in mode 6a, 24 bits. rc-6 is described here
+https://www.sbprojects.net/knowledge/ir/rc6.php.
+The scancode is the exact 24 bits
+as in the protocol. There is also a toggle bit.
+
+rc-6-6a-32 (RC_PROTO_RC6_6A_32)
+-------------------------------
+
+This is the rc-6 in mode 6a, 32 bits. rc-6 is described here
+https://www.sbprojects.net/knowledge/ir/rc6.php.
+The upper 16 bits are the vendor,
+and the lower 16 bits are the vendor-specific bits. This protocol is
+for the non-Microsoft MCE variant (vendor != 0x800f).
+
+
+rc-6-mce (RC_PROTO_RC6_MCE)
+---------------------------
+
+This is the rc-6 in mode 6a, 32 bits. The upper 16 bits are the vendor,
+and the lower 16 bits are the vendor-specific bits. This protocol is
+for the Microsoft MCE variant (vendor = 0x800f). The toggle bit in the
+protocol itself is ignored, and the 16th bit should be takes as the toggle
+bit.
+
+sharp (RC_PROTO_SHARP)
+----------------------
+
+This is a protocol used by Sharp VCRs, is described here
+https://www.sbprojects.net/knowledge/ir/sharp.php. There is a very long
+(40ms) space between the normal and inverted values, and some IR receivers
+cannot decode this.
+
+There is a 5 bit address and a 8 bit command. In the scancode the address is
+in bits 8 to 12, and the command in bits 0 to 7.
+
+xmp (RC_PROTO_XMP)
+------------------
+
+This protocol has several versions and only version 1 is supported. Refer
+to the decoder (ir-xmp-decoder.c) to see how it is encoded.
+
+
+cec (RC_PROTO_CEC)
+------------------
+
+This is not an IR protocol, this is a protocol over CEC. The CEC
+infrastructure uses rc-core for handling CEC commands, so that they
+can easily be remapped.
+
+imon (RC_PROTO_IMON)
+--------------------
+
+This protocol is used by Antec Veris/SoundGraph iMON remotes.
+
+The protocol
+describes both button presses and pointer movements. The protocol encodes
+31 bits, and the scancode is simply the 31 bits with the top bit always 0.
+
+rc-mm-12 (RC_PROTO_RCMM12)
+--------------------------
+
+The rc-mm protocol is described here
+https://www.sbprojects.net/knowledge/ir/rcmm.php. The scancode is simply
+the 12 bits.
+
+rc-mm-24 (RC_PROTO_RCMM24)
+--------------------------
+
+The rc-mm protocol is described here
+https://www.sbprojects.net/knowledge/ir/rcmm.php. The scancode is simply
+the 24 bits.
+
+rc-mm-32 (RC_PROTO_RCMM32)
+--------------------------
+
+The rc-mm protocol is described here
+https://www.sbprojects.net/knowledge/ir/rcmm.php. The scancode is simply
+the 32 bits.
+
+xbox-dvd (RC_PROTO_XBOX_DVD)
+----------------------------
+
+This protocol is used by XBox DVD Remote, which was made for the original
+XBox. There is no in-kernel decoder or encoder for this protocol. The usb
+device decodes the protocol. There is a BPF decoder available in v4l-utils.
diff --git a/Documentation/media/uapi/rc/remote_controllers.rst b/Documentation/media/uapi/rc/remote_controllers.rst
index 3051f7a..20e0f98 100644
--- a/Documentation/media/uapi/rc/remote_controllers.rst
+++ b/Documentation/media/uapi/rc/remote_controllers.rst
@@ -27,6 +27,7 @@
rc-intro
rc-sysfs-nodes
+ rc-protos
rc-tables
rc-table-change
lirc-dev
diff --git a/Documentation/media/uapi/v4l/biblio.rst b/Documentation/media/uapi/v4l/biblio.rst
index 8f4eb88..ad2ff25 100644
--- a/Documentation/media/uapi/v4l/biblio.rst
+++ b/Documentation/media/uapi/v4l/biblio.rst
@@ -395,3 +395,13 @@
:title: Color Imaging: Fundamentals and Applications
:author: Erik Reinhard et al.
+
+.. _vp8:
+
+VP8
+===
+
+
+:title: RFC 6386: "VP8 Data Format and Decoding Guide"
+
+:author: J. Bankoski et al.
diff --git a/Documentation/media/uapi/v4l/control.rst b/Documentation/media/uapi/v4l/control.rst
index 71417bb..ef62e08 100644
--- a/Documentation/media/uapi/v4l/control.rst
+++ b/Documentation/media/uapi/v4l/control.rst
@@ -295,7 +295,7 @@
Sets the alpha color component. When a capture device (or capture
queue of a mem-to-mem device) produces a frame format that includes
an alpha component (e.g.
- :ref:`packed RGB image formats <rgb-formats>`) and the alpha value
+ :ref:`packed RGB image formats <pixfmt-rgb>`) and the alpha value
is not defined by the device or the mem-to-mem input data this
control lets you select the alpha component value of all pixels.
When an output device (or output queue of a mem-to-mem device)
diff --git a/Documentation/media/uapi/v4l/dev-decoder.rst b/Documentation/media/uapi/v4l/dev-decoder.rst
new file mode 100644
index 0000000..606b549
--- /dev/null
+++ b/Documentation/media/uapi/v4l/dev-decoder.rst
@@ -0,0 +1,1101 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+.. _decoder:
+
+*************************************************
+Memory-to-Memory Stateful Video Decoder Interface
+*************************************************
+
+A stateful video decoder takes complete chunks of the bytestream (e.g. Annex-B
+H.264/HEVC stream, raw VP8/9 stream) and decodes them into raw video frames in
+display order. The decoder is expected not to require any additional information
+from the client to process these buffers.
+
+Performing software parsing, processing etc. of the stream in the driver in
+order to support this interface is strongly discouraged. In case such
+operations are needed, use of the Stateless Video Decoder Interface (in
+development) is strongly advised.
+
+Conventions and Notations Used in This Document
+===============================================
+
+1. The general V4L2 API rules apply if not specified in this document
+ otherwise.
+
+2. The meaning of words "must", "may", "should", etc. is as per `RFC
+ 2119 <https://tools.ietf.org/html/rfc2119>`_.
+
+3. All steps not marked "optional" are required.
+
+4. :c:func:`VIDIOC_G_EXT_CTRLS` and :c:func:`VIDIOC_S_EXT_CTRLS` may be used
+ interchangeably with :c:func:`VIDIOC_G_CTRL` and :c:func:`VIDIOC_S_CTRL`,
+ unless specified otherwise.
+
+5. Single-planar API (see :ref:`planar-apis`) and applicable structures may be
+ used interchangeably with multi-planar API, unless specified otherwise,
+ depending on decoder capabilities and following the general V4L2 guidelines.
+
+6. i = [a..b]: sequence of integers from a to b, inclusive, i.e. i =
+ [0..2]: i = 0, 1, 2.
+
+7. Given an ``OUTPUT`` buffer A, then A’ represents a buffer on the ``CAPTURE``
+ queue containing data that resulted from processing buffer A.
+
+.. _decoder-glossary:
+
+Glossary
+========
+
+CAPTURE
+ the destination buffer queue; for decoders, the queue of buffers containing
+ decoded frames; for encoders, the queue of buffers containing an encoded
+ bytestream; ``V4L2_BUF_TYPE_VIDEO_CAPTURE`` or
+ ``V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE``; data is captured from the hardware
+ into ``CAPTURE`` buffers.
+
+client
+ the application communicating with the decoder or encoder implementing
+ this interface.
+
+coded format
+ encoded/compressed video bytestream format (e.g. H.264, VP8, etc.); see
+ also: raw format.
+
+coded height
+ height for given coded resolution.
+
+coded resolution
+ stream resolution in pixels aligned to codec and hardware requirements;
+ typically visible resolution rounded up to full macroblocks;
+ see also: visible resolution.
+
+coded width
+ width for given coded resolution.
+
+decode order
+ the order in which frames are decoded; may differ from display order if the
+ coded format includes a feature of frame reordering; for decoders,
+ ``OUTPUT`` buffers must be queued by the client in decode order; for
+ encoders ``CAPTURE`` buffers must be returned by the encoder in decode order.
+
+destination
+ data resulting from the decode process; see ``CAPTURE``.
+
+display order
+ the order in which frames must be displayed; for encoders, ``OUTPUT``
+ buffers must be queued by the client in display order; for decoders,
+ ``CAPTURE`` buffers must be returned by the decoder in display order.
+
+DPB
+ Decoded Picture Buffer; an H.264/HEVC term for a buffer that stores a decoded
+ raw frame available for reference in further decoding steps.
+
+EOS
+ end of stream.
+
+IDR
+ Instantaneous Decoder Refresh; a type of a keyframe in an H.264/HEVC-encoded
+ stream, which clears the list of earlier reference frames (DPBs).
+
+keyframe
+ an encoded frame that does not reference frames decoded earlier, i.e.
+ can be decoded fully on its own.
+
+macroblock
+ a processing unit in image and video compression formats based on linear
+ block transforms (e.g. H.264, VP8, VP9); codec-specific, but for most of
+ popular codecs the size is 16x16 samples (pixels).
+
+OUTPUT
+ the source buffer queue; for decoders, the queue of buffers containing
+ an encoded bytestream; for encoders, the queue of buffers containing raw
+ frames; ``V4L2_BUF_TYPE_VIDEO_OUTPUT`` or
+ ``V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE``; the hardware is fed with data
+ from ``OUTPUT`` buffers.
+
+PPS
+ Picture Parameter Set; a type of metadata entity in an H.264/HEVC bytestream.
+
+raw format
+ uncompressed format containing raw pixel data (e.g. YUV, RGB formats).
+
+resume point
+ a point in the bytestream from which decoding may start/continue, without
+ any previous state/data present, e.g.: a keyframe (VP8/VP9) or
+ SPS/PPS/IDR sequence (H.264/HEVC); a resume point is required to start decode
+ of a new stream, or to resume decoding after a seek.
+
+source
+ data fed to the decoder or encoder; see ``OUTPUT``.
+
+source height
+ height in pixels for given source resolution; relevant to encoders only.
+
+source resolution
+ resolution in pixels of source frames being source to the encoder and
+ subject to further cropping to the bounds of visible resolution; relevant to
+ encoders only.
+
+source width
+ width in pixels for given source resolution; relevant to encoders only.
+
+SPS
+ Sequence Parameter Set; a type of metadata entity in an H.264/HEVC bytestream.
+
+stream metadata
+ additional (non-visual) information contained inside encoded bytestream;
+ for example: coded resolution, visible resolution, codec profile.
+
+visible height
+ height for given visible resolution; display height.
+
+visible resolution
+ stream resolution of the visible picture, in pixels, to be used for
+ display purposes; must be smaller or equal to coded resolution;
+ display resolution.
+
+visible width
+ width for given visible resolution; display width.
+
+State Machine
+=============
+
+.. kernel-render:: DOT
+ :alt: DOT digraph of decoder state machine
+ :caption: Decoder State Machine
+
+ digraph decoder_state_machine {
+ node [shape = doublecircle, label="Decoding"] Decoding;
+
+ node [shape = circle, label="Initialization"] Initialization;
+ node [shape = circle, label="Capture\nsetup"] CaptureSetup;
+ node [shape = circle, label="Dynamic\nResolution\nChange"] ResChange;
+ node [shape = circle, label="Stopped"] Stopped;
+ node [shape = circle, label="Drain"] Drain;
+ node [shape = circle, label="Seek"] Seek;
+ node [shape = circle, label="End of Stream"] EoS;
+
+ node [shape = point]; qi
+ qi -> Initialization [ label = "open()" ];
+
+ Initialization -> CaptureSetup [ label = "CAPTURE\nformat\nestablished" ];
+
+ CaptureSetup -> Stopped [ label = "CAPTURE\nbuffers\nready" ];
+
+ Decoding -> ResChange [ label = "Stream\nresolution\nchange" ];
+ Decoding -> Drain [ label = "V4L2_DEC_CMD_STOP" ];
+ Decoding -> EoS [ label = "EoS mark\nin the stream" ];
+ Decoding -> Seek [ label = "VIDIOC_STREAMOFF(OUTPUT)" ];
+ Decoding -> Stopped [ label = "VIDIOC_STREAMOFF(CAPTURE)" ];
+ Decoding -> Decoding;
+
+ ResChange -> CaptureSetup [ label = "CAPTURE\nformat\nestablished" ];
+ ResChange -> Seek [ label = "VIDIOC_STREAMOFF(OUTPUT)" ];
+
+ EoS -> Drain [ label = "Implicit\ndrain" ];
+
+ Drain -> Stopped [ label = "All CAPTURE\nbuffers dequeued\nor\nVIDIOC_STREAMOFF(CAPTURE)" ];
+ Drain -> Seek [ label = "VIDIOC_STREAMOFF(OUTPUT)" ];
+
+ Seek -> Decoding [ label = "VIDIOC_STREAMON(OUTPUT)" ];
+ Seek -> Initialization [ label = "VIDIOC_REQBUFS(OUTPUT, 0)" ];
+
+ Stopped -> Decoding [ label = "V4L2_DEC_CMD_START\nor\nVIDIOC_STREAMON(CAPTURE)" ];
+ Stopped -> Seek [ label = "VIDIOC_STREAMOFF(OUTPUT)" ];
+ }
+
+Querying Capabilities
+=====================
+
+1. To enumerate the set of coded formats supported by the decoder, the
+ client may call :c:func:`VIDIOC_ENUM_FMT` on ``OUTPUT``.
+
+ * The full set of supported formats will be returned, regardless of the
+ format set on ``CAPTURE``.
+ * Check the flags field of :c:type:`v4l2_fmtdesc` for more information
+ about the decoder's capabilities with respect to each coded format.
+ In particular whether or not the decoder has a full-fledged bytestream
+ parser and if the decoder supports dynamic resolution changes.
+
+2. To enumerate the set of supported raw formats, the client may call
+ :c:func:`VIDIOC_ENUM_FMT` on ``CAPTURE``.
+
+ * Only the formats supported for the format currently active on ``OUTPUT``
+ will be returned.
+
+ * In order to enumerate raw formats supported by a given coded format,
+ the client must first set that coded format on ``OUTPUT`` and then
+ enumerate formats on ``CAPTURE``.
+
+3. The client may use :c:func:`VIDIOC_ENUM_FRAMESIZES` to detect supported
+ resolutions for a given format, passing desired pixel format in
+ :c:type:`v4l2_frmsizeenum` ``pixel_format``.
+
+ * Values returned by :c:func:`VIDIOC_ENUM_FRAMESIZES` for a coded pixel
+ format will include all possible coded resolutions supported by the
+ decoder for given coded pixel format.
+
+ * Values returned by :c:func:`VIDIOC_ENUM_FRAMESIZES` for a raw pixel format
+ will include all possible frame buffer resolutions supported by the
+ decoder for given raw pixel format and the coded format currently set on
+ ``OUTPUT``.
+
+4. Supported profiles and levels for the coded format currently set on
+ ``OUTPUT``, if applicable, may be queried using their respective controls
+ via :c:func:`VIDIOC_QUERYCTRL`.
+
+Initialization
+==============
+
+1. Set the coded format on ``OUTPUT`` via :c:func:`VIDIOC_S_FMT`
+
+ * **Required fields:**
+
+ ``type``
+ a ``V4L2_BUF_TYPE_*`` enum appropriate for ``OUTPUT``.
+
+ ``pixelformat``
+ a coded pixel format.
+
+ ``width``, ``height``
+ coded resolution of the stream; required only if it cannot be parsed
+ from the stream for the given coded format; otherwise the decoder will
+ use this resolution as a placeholder resolution that will likely change
+ as soon as it can parse the actual coded resolution from the stream.
+
+ ``sizeimage``
+ desired size of ``OUTPUT`` buffers; the decoder may adjust it to
+ match hardware requirements.
+
+ other fields
+ follow standard semantics.
+
+ * **Return fields:**
+
+ ``sizeimage``
+ adjusted size of ``OUTPUT`` buffers.
+
+ * The ``CAPTURE`` format will be updated with an appropriate frame buffer
+ resolution instantly based on the width and height returned by
+ :c:func:`VIDIOC_S_FMT`.
+ However, for coded formats that include stream resolution information,
+ after the decoder is done parsing the information from the stream, it will
+ update the ``CAPTURE`` format with new values and signal a source change
+ event, regardless of whether they match the values set by the client or
+ not.
+
+ .. important::
+
+ Changing the ``OUTPUT`` format may change the currently set ``CAPTURE``
+ format. How the new ``CAPTURE`` format is determined is up to the decoder
+ and the client must ensure it matches its needs afterwards.
+
+2. Allocate source (bytestream) buffers via :c:func:`VIDIOC_REQBUFS` on
+ ``OUTPUT``.
+
+ * **Required fields:**
+
+ ``count``
+ requested number of buffers to allocate; greater than zero.
+
+ ``type``
+ a ``V4L2_BUF_TYPE_*`` enum appropriate for ``OUTPUT``.
+
+ ``memory``
+ follows standard semantics.
+
+ * **Return fields:**
+
+ ``count``
+ the actual number of buffers allocated.
+
+ .. warning::
+
+ The actual number of allocated buffers may differ from the ``count``
+ given. The client must check the updated value of ``count`` after the
+ call returns.
+
+ Alternatively, :c:func:`VIDIOC_CREATE_BUFS` on the ``OUTPUT`` queue can be
+ used to have more control over buffer allocation.
+
+ * **Required fields:**
+
+ ``count``
+ requested number of buffers to allocate; greater than zero.
+
+ ``type``
+ a ``V4L2_BUF_TYPE_*`` enum appropriate for ``OUTPUT``.
+
+ ``memory``
+ follows standard semantics.
+
+ ``format``
+ follows standard semantics.
+
+ * **Return fields:**
+
+ ``count``
+ adjusted to the number of allocated buffers.
+
+ .. warning::
+
+ The actual number of allocated buffers may differ from the ``count``
+ given. The client must check the updated value of ``count`` after the
+ call returns.
+
+3. Start streaming on the ``OUTPUT`` queue via :c:func:`VIDIOC_STREAMON`.
+
+4. **This step only applies to coded formats that contain resolution information
+ in the stream.** Continue queuing/dequeuing bytestream buffers to/from the
+ ``OUTPUT`` queue via :c:func:`VIDIOC_QBUF` and :c:func:`VIDIOC_DQBUF`. The
+ buffers will be processed and returned to the client in order, until
+ required metadata to configure the ``CAPTURE`` queue are found. This is
+ indicated by the decoder sending a ``V4L2_EVENT_SOURCE_CHANGE`` event with
+ ``changes`` set to ``V4L2_EVENT_SRC_CH_RESOLUTION``.
+
+ * It is not an error if the first buffer does not contain enough data for
+ this to occur. Processing of the buffers will continue as long as more
+ data is needed.
+
+ * If data in a buffer that triggers the event is required to decode the
+ first frame, it will not be returned to the client, until the
+ initialization sequence completes and the frame is decoded.
+
+ * If the client has not set the coded resolution of the stream on its own,
+ calling :c:func:`VIDIOC_G_FMT`, :c:func:`VIDIOC_S_FMT`,
+ :c:func:`VIDIOC_TRY_FMT` or :c:func:`VIDIOC_REQBUFS` on the ``CAPTURE``
+ queue will not return the real values for the stream until a
+ ``V4L2_EVENT_SOURCE_CHANGE`` event with ``changes`` set to
+ ``V4L2_EVENT_SRC_CH_RESOLUTION`` is signaled.
+
+ .. important::
+
+ Any client query issued after the decoder queues the event will return
+ values applying to the just parsed stream, including queue formats,
+ selection rectangles and controls.
+
+ .. note::
+
+ A client capable of acquiring stream parameters from the bytestream on
+ its own may attempt to set the width and height of the ``OUTPUT`` format
+ to non-zero values matching the coded size of the stream, skip this step
+ and continue with the `Capture Setup` sequence. However, it must not
+ rely on any driver queries regarding stream parameters, such as
+ selection rectangles and controls, since the decoder has not parsed them
+ from the stream yet. If the values configured by the client do not match
+ those parsed by the decoder, a `Dynamic Resolution Change` will be
+ triggered to reconfigure them.
+
+ .. note::
+
+ No decoded frames are produced during this phase.
+
+5. Continue with the `Capture Setup` sequence.
+
+Capture Setup
+=============
+
+1. Call :c:func:`VIDIOC_G_FMT` on the ``CAPTURE`` queue to get format for the
+ destination buffers parsed/decoded from the bytestream.
+
+ * **Required fields:**
+
+ ``type``
+ a ``V4L2_BUF_TYPE_*`` enum appropriate for ``CAPTURE``.
+
+ * **Return fields:**
+
+ ``width``, ``height``
+ frame buffer resolution for the decoded frames.
+
+ ``pixelformat``
+ pixel format for decoded frames.
+
+ ``num_planes`` (for _MPLANE ``type`` only)
+ number of planes for pixelformat.
+
+ ``sizeimage``, ``bytesperline``
+ as per standard semantics; matching frame buffer format.
+
+ .. note::
+
+ The value of ``pixelformat`` may be any pixel format supported by the
+ decoder for the current stream. The decoder should choose a
+ preferred/optimal format for the default configuration. For example, a
+ YUV format may be preferred over an RGB format if an additional
+ conversion step would be required for the latter.
+
+2. **Optional.** Acquire the visible resolution via
+ :c:func:`VIDIOC_G_SELECTION`.
+
+ * **Required fields:**
+
+ ``type``
+ a ``V4L2_BUF_TYPE_*`` enum appropriate for ``CAPTURE``.
+
+ ``target``
+ set to ``V4L2_SEL_TGT_COMPOSE``.
+
+ * **Return fields:**
+
+ ``r.left``, ``r.top``, ``r.width``, ``r.height``
+ the visible rectangle; it must fit within the frame buffer resolution
+ returned by :c:func:`VIDIOC_G_FMT` on ``CAPTURE``.
+
+ * The following selection targets are supported on ``CAPTURE``:
+
+ ``V4L2_SEL_TGT_CROP_BOUNDS``
+ corresponds to the coded resolution of the stream.
+
+ ``V4L2_SEL_TGT_CROP_DEFAULT``
+ the rectangle covering the part of the ``CAPTURE`` buffer that
+ contains meaningful picture data (visible area); width and height
+ will be equal to the visible resolution of the stream.
+
+ ``V4L2_SEL_TGT_CROP``
+ the rectangle within the coded resolution to be output to
+ ``CAPTURE``; defaults to ``V4L2_SEL_TGT_CROP_DEFAULT``; read-only on
+ hardware without additional compose/scaling capabilities.
+
+ ``V4L2_SEL_TGT_COMPOSE_BOUNDS``
+ the maximum rectangle within a ``CAPTURE`` buffer, which the cropped
+ frame can be composed into; equal to ``V4L2_SEL_TGT_CROP`` if the
+ hardware does not support compose/scaling.
+
+ ``V4L2_SEL_TGT_COMPOSE_DEFAULT``
+ equal to ``V4L2_SEL_TGT_CROP``.
+
+ ``V4L2_SEL_TGT_COMPOSE``
+ the rectangle inside a ``CAPTURE`` buffer into which the cropped
+ frame is written; defaults to ``V4L2_SEL_TGT_COMPOSE_DEFAULT``;
+ read-only on hardware without additional compose/scaling capabilities.
+
+ ``V4L2_SEL_TGT_COMPOSE_PADDED``
+ the rectangle inside a ``CAPTURE`` buffer which is overwritten by the
+ hardware; equal to ``V4L2_SEL_TGT_COMPOSE`` if the hardware does not
+ write padding pixels.
+
+ .. warning::
+
+ The values are guaranteed to be meaningful only after the decoder
+ successfully parses the stream metadata. The client must not rely on the
+ query before that happens.
+
+3. **Optional.** Enumerate ``CAPTURE`` formats via :c:func:`VIDIOC_ENUM_FMT` on
+ the ``CAPTURE`` queue. Once the stream information is parsed and known, the
+ client may use this ioctl to discover which raw formats are supported for
+ given stream and select one of them via :c:func:`VIDIOC_S_FMT`.
+
+ .. important::
+
+ The decoder will return only formats supported for the currently
+ established coded format, as per the ``OUTPUT`` format and/or stream
+ metadata parsed in this initialization sequence, even if more formats
+ may be supported by the decoder in general. In other words, the set
+ returned will be a subset of the initial query mentioned in the
+ `Querying Capabilities` section.
+
+ For example, a decoder may support YUV and RGB formats for resolutions
+ 1920x1088 and lower, but only YUV for higher resolutions (due to
+ hardware limitations). After parsing a resolution of 1920x1088 or lower,
+ :c:func:`VIDIOC_ENUM_FMT` may return a set of YUV and RGB pixel formats,
+ but after parsing resolution higher than 1920x1088, the decoder will not
+ return RGB, unsupported for this resolution.
+
+ However, subsequent resolution change event triggered after
+ discovering a resolution change within the same stream may switch
+ the stream into a lower resolution and :c:func:`VIDIOC_ENUM_FMT`
+ would return RGB formats again in that case.
+
+4. **Optional.** Set the ``CAPTURE`` format via :c:func:`VIDIOC_S_FMT` on the
+ ``CAPTURE`` queue. The client may choose a different format than
+ selected/suggested by the decoder in :c:func:`VIDIOC_G_FMT`.
+
+ * **Required fields:**
+
+ ``type``
+ a ``V4L2_BUF_TYPE_*`` enum appropriate for ``CAPTURE``.
+
+ ``pixelformat``
+ a raw pixel format.
+
+ ``width``, ``height``
+ frame buffer resolution of the decoded stream; typically unchanged from
+ what was returned with :c:func:`VIDIOC_G_FMT`, but it may be different
+ if the hardware supports composition and/or scaling.
+
+ * Setting the ``CAPTURE`` format will reset the compose selection rectangles
+ to their default values, based on the new resolution, as described in the
+ previous step.
+
+5. **Optional.** Set the compose rectangle via :c:func:`VIDIOC_S_SELECTION` on
+ the ``CAPTURE`` queue if it is desired and if the decoder has compose and/or
+ scaling capabilities.
+
+ * **Required fields:**
+
+ ``type``
+ a ``V4L2_BUF_TYPE_*`` enum appropriate for ``CAPTURE``.
+
+ ``target``
+ set to ``V4L2_SEL_TGT_COMPOSE``.
+
+ ``r.left``, ``r.top``, ``r.width``, ``r.height``
+ the rectangle inside a ``CAPTURE`` buffer into which the cropped
+ frame is written; defaults to ``V4L2_SEL_TGT_COMPOSE_DEFAULT``;
+ read-only on hardware without additional compose/scaling capabilities.
+
+ * **Return fields:**
+
+ ``r.left``, ``r.top``, ``r.width``, ``r.height``
+ the visible rectangle; it must fit within the frame buffer resolution
+ returned by :c:func:`VIDIOC_G_FMT` on ``CAPTURE``.
+
+ .. warning::
+
+ The decoder may adjust the compose rectangle to the nearest
+ supported one to meet codec and hardware requirements. The client needs
+ to check the adjusted rectangle returned by :c:func:`VIDIOC_S_SELECTION`.
+
+6. If all the following conditions are met, the client may resume the decoding
+ instantly:
+
+ * ``sizeimage`` of the new format (determined in previous steps) is less
+ than or equal to the size of currently allocated buffers,
+
+ * the number of buffers currently allocated is greater than or equal to the
+ minimum number of buffers acquired in previous steps. To fulfill this
+ requirement, the client may use :c:func:`VIDIOC_CREATE_BUFS` to add new
+ buffers.
+
+ In that case, the remaining steps do not apply and the client may resume
+ the decoding by one of the following actions:
+
+ * if the ``CAPTURE`` queue is streaming, call :c:func:`VIDIOC_DECODER_CMD`
+ with the ``V4L2_DEC_CMD_START`` command,
+
+ * if the ``CAPTURE`` queue is not streaming, call :c:func:`VIDIOC_STREAMON`
+ on the ``CAPTURE`` queue.
+
+ However, if the client intends to change the buffer set, to lower
+ memory usage or for any other reasons, it may be achieved by following
+ the steps below.
+
+7. **If the** ``CAPTURE`` **queue is streaming,** keep queuing and dequeuing
+ buffers on the ``CAPTURE`` queue until a buffer marked with the
+ ``V4L2_BUF_FLAG_LAST`` flag is dequeued.
+
+8. **If the** ``CAPTURE`` **queue is streaming,** call :c:func:`VIDIOC_STREAMOFF`
+ on the ``CAPTURE`` queue to stop streaming.
+
+ .. warning::
+
+ The ``OUTPUT`` queue must remain streaming. Calling
+ :c:func:`VIDIOC_STREAMOFF` on it would abort the sequence and trigger a
+ seek.
+
+9. **If the** ``CAPTURE`` **queue has buffers allocated,** free the ``CAPTURE``
+ buffers using :c:func:`VIDIOC_REQBUFS`.
+
+ * **Required fields:**
+
+ ``count``
+ set to 0.
+
+ ``type``
+ a ``V4L2_BUF_TYPE_*`` enum appropriate for ``CAPTURE``.
+
+ ``memory``
+ follows standard semantics.
+
+10. Allocate ``CAPTURE`` buffers via :c:func:`VIDIOC_REQBUFS` on the
+ ``CAPTURE`` queue.
+
+ * **Required fields:**
+
+ ``count``
+ requested number of buffers to allocate; greater than zero.
+
+ ``type``
+ a ``V4L2_BUF_TYPE_*`` enum appropriate for ``CAPTURE``.
+
+ ``memory``
+ follows standard semantics.
+
+ * **Return fields:**
+
+ ``count``
+ actual number of buffers allocated.
+
+ .. warning::
+
+ The actual number of allocated buffers may differ from the ``count``
+ given. The client must check the updated value of ``count`` after the
+ call returns.
+
+ .. note::
+
+ To allocate more than the minimum number of buffers (for pipeline
+ depth), the client may query the ``V4L2_CID_MIN_BUFFERS_FOR_CAPTURE``
+ control to get the minimum number of buffers required, and pass the
+ obtained value plus the number of additional buffers needed in the
+ ``count`` field to :c:func:`VIDIOC_REQBUFS`.
+
+ Alternatively, :c:func:`VIDIOC_CREATE_BUFS` on the ``CAPTURE`` queue can be
+ used to have more control over buffer allocation. For example, by
+ allocating buffers larger than the current ``CAPTURE`` format, future
+ resolution changes can be accommodated.
+
+ * **Required fields:**
+
+ ``count``
+ requested number of buffers to allocate; greater than zero.
+
+ ``type``
+ a ``V4L2_BUF_TYPE_*`` enum appropriate for ``CAPTURE``.
+
+ ``memory``
+ follows standard semantics.
+
+ ``format``
+ a format representing the maximum framebuffer resolution to be
+ accommodated by newly allocated buffers.
+
+ * **Return fields:**
+
+ ``count``
+ adjusted to the number of allocated buffers.
+
+ .. warning::
+
+ The actual number of allocated buffers may differ from the ``count``
+ given. The client must check the updated value of ``count`` after the
+ call returns.
+
+ .. note::
+
+ To allocate buffers for a format different than parsed from the stream
+ metadata, the client must proceed as follows, before the metadata
+ parsing is initiated:
+
+ * set width and height of the ``OUTPUT`` format to desired coded resolution to
+ let the decoder configure the ``CAPTURE`` format appropriately,
+
+ * query the ``CAPTURE`` format using :c:func:`VIDIOC_G_FMT` and save it
+ until this step.
+
+ The format obtained in the query may be then used with
+ :c:func:`VIDIOC_CREATE_BUFS` in this step to allocate the buffers.
+
+11. Call :c:func:`VIDIOC_STREAMON` on the ``CAPTURE`` queue to start decoding
+ frames.
+
+Decoding
+========
+
+This state is reached after the `Capture Setup` sequence finishes successfully.
+In this state, the client queues and dequeues buffers to both queues via
+:c:func:`VIDIOC_QBUF` and :c:func:`VIDIOC_DQBUF`, following the standard
+semantics.
+
+The content of the source ``OUTPUT`` buffers depends on the active coded pixel
+format and may be affected by codec-specific extended controls, as stated in
+the documentation of each format.
+
+Both queues operate independently, following the standard behavior of V4L2
+buffer queues and memory-to-memory devices. In addition, the order of decoded
+frames dequeued from the ``CAPTURE`` queue may differ from the order of queuing
+coded frames to the ``OUTPUT`` queue, due to properties of the selected coded
+format, e.g. frame reordering.
+
+The client must not assume any direct relationship between ``CAPTURE``
+and ``OUTPUT`` buffers and any specific timing of buffers becoming
+available to dequeue. Specifically:
+
+* a buffer queued to ``OUTPUT`` may result in no buffers being produced
+ on ``CAPTURE`` (e.g. if it does not contain encoded data, or if only
+ metadata syntax structures are present in it),
+
+* a buffer queued to ``OUTPUT`` may result in more than one buffer produced
+ on ``CAPTURE`` (if the encoded data contained more than one frame, or if
+ returning a decoded frame allowed the decoder to return a frame that
+ preceded it in decode, but succeeded it in the display order),
+
+* a buffer queued to ``OUTPUT`` may result in a buffer being produced on
+ ``CAPTURE`` later into decode process, and/or after processing further
+ ``OUTPUT`` buffers, or be returned out of order, e.g. if display
+ reordering is used,
+
+* buffers may become available on the ``CAPTURE`` queue without additional
+ buffers queued to ``OUTPUT`` (e.g. during drain or ``EOS``), because of the
+ ``OUTPUT`` buffers queued in the past whose decoding results are only
+ available at later time, due to specifics of the decoding process.
+
+.. note::
+
+ To allow matching decoded ``CAPTURE`` buffers with ``OUTPUT`` buffers they
+ originated from, the client can set the ``timestamp`` field of the
+ :c:type:`v4l2_buffer` struct when queuing an ``OUTPUT`` buffer. The
+ ``CAPTURE`` buffer(s), which resulted from decoding that ``OUTPUT`` buffer
+ will have their ``timestamp`` field set to the same value when dequeued.
+
+ In addition to the straightforward case of one ``OUTPUT`` buffer producing
+ one ``CAPTURE`` buffer, the following cases are defined:
+
+ * one ``OUTPUT`` buffer generates multiple ``CAPTURE`` buffers: the same
+ ``OUTPUT`` timestamp will be copied to multiple ``CAPTURE`` buffers.
+
+ * multiple ``OUTPUT`` buffers generate one ``CAPTURE`` buffer: timestamp of
+ the ``OUTPUT`` buffer queued first will be copied.
+
+ * the decoding order differs from the display order (i.e. the ``CAPTURE``
+ buffers are out-of-order compared to the ``OUTPUT`` buffers): ``CAPTURE``
+ timestamps will not retain the order of ``OUTPUT`` timestamps.
+
+During the decoding, the decoder may initiate one of the special sequences, as
+listed below. The sequences will result in the decoder returning all the
+``CAPTURE`` buffers that originated from all the ``OUTPUT`` buffers processed
+before the sequence started. Last of the buffers will have the
+``V4L2_BUF_FLAG_LAST`` flag set. To determine the sequence to follow, the client
+must check if there is any pending event and:
+
+* if a ``V4L2_EVENT_SOURCE_CHANGE`` event with ``changes`` set to
+ ``V4L2_EVENT_SRC_CH_RESOLUTION`` is pending, the `Dynamic Resolution
+ Change` sequence needs to be followed,
+
+* if a ``V4L2_EVENT_EOS`` event is pending, the `End of Stream` sequence needs
+ to be followed.
+
+Some of the sequences can be intermixed with each other and need to be handled
+as they happen. The exact operation is documented for each sequence.
+
+Should a decoding error occur, it will be reported to the client with the level
+of details depending on the decoder capabilities. Specifically:
+
+* the CAPTURE buffer that contains the results of the failed decode operation
+ will be returned with the V4L2_BUF_FLAG_ERROR flag set,
+
+* if the decoder is able to precisely report the OUTPUT buffer that triggered
+ the error, such buffer will be returned with the V4L2_BUF_FLAG_ERROR flag
+ set.
+
+In case of a fatal failure that does not allow the decoding to continue, any
+further operations on corresponding decoder file handle will return the -EIO
+error code. The client may close the file handle and open a new one, or
+alternatively reinitialize the instance by stopping streaming on both queues,
+releasing all buffers and performing the Initialization sequence again.
+
+Seek
+====
+
+Seek is controlled by the ``OUTPUT`` queue, as it is the source of coded data.
+The seek does not require any specific operation on the ``CAPTURE`` queue, but
+it may be affected as per normal decoder operation.
+
+1. Stop the ``OUTPUT`` queue to begin the seek sequence via
+ :c:func:`VIDIOC_STREAMOFF`.
+
+ * **Required fields:**
+
+ ``type``
+ a ``V4L2_BUF_TYPE_*`` enum appropriate for ``OUTPUT``.
+
+ * The decoder will drop all the pending ``OUTPUT`` buffers and they must be
+ treated as returned to the client (following standard semantics).
+
+2. Restart the ``OUTPUT`` queue via :c:func:`VIDIOC_STREAMON`
+
+ * **Required fields:**
+
+ ``type``
+ a ``V4L2_BUF_TYPE_*`` enum appropriate for ``OUTPUT``.
+
+ * The decoder will start accepting new source bytestream buffers after the
+ call returns.
+
+3. Start queuing buffers containing coded data after the seek to the ``OUTPUT``
+ queue until a suitable resume point is found.
+
+ .. note::
+
+ There is no requirement to begin queuing coded data starting exactly
+ from a resume point (e.g. SPS or a keyframe). Any queued ``OUTPUT``
+ buffers will be processed and returned to the client until a suitable
+ resume point is found. While looking for a resume point, the decoder
+ should not produce any decoded frames into ``CAPTURE`` buffers.
+
+ Some hardware is known to mishandle seeks to a non-resume point. Such an
+ operation may result in an unspecified number of corrupted decoded frames
+ being made available on the ``CAPTURE`` queue. Drivers must ensure that
+ no fatal decoding errors or crashes occur, and implement any necessary
+ handling and workarounds for hardware issues related to seek operations.
+
+ .. warning::
+
+ In case of the H.264/HEVC codec, the client must take care not to seek
+ over a change of SPS/PPS. Even though the target frame could be a
+ keyframe, the stale SPS/PPS inside decoder state would lead to undefined
+ results when decoding. Although the decoder must handle that case without
+ a crash or a fatal decode error, the client must not expect a sensible
+ decode output.
+
+ If the hardware can detect such corrupted decoded frames, then
+ corresponding buffers will be returned to the client with the
+ V4L2_BUF_FLAG_ERROR set. See the `Decoding` section for further
+ description of decode error reporting.
+
+4. After a resume point is found, the decoder will start returning ``CAPTURE``
+ buffers containing decoded frames.
+
+.. important::
+
+ A seek may result in the `Dynamic Resolution Change` sequence being
+ initiated, due to the seek target having decoding parameters different from
+ the part of the stream decoded before the seek. The sequence must be handled
+ as per normal decoder operation.
+
+.. warning::
+
+ It is not specified when the ``CAPTURE`` queue starts producing buffers
+ containing decoded data from the ``OUTPUT`` buffers queued after the seek,
+ as it operates independently from the ``OUTPUT`` queue.
+
+ The decoder may return a number of remaining ``CAPTURE`` buffers containing
+ decoded frames originating from the ``OUTPUT`` buffers queued before the
+ seek sequence is performed.
+
+ The ``VIDIOC_STREAMOFF`` operation discards any remaining queued
+ ``OUTPUT`` buffers, which means that not all of the ``OUTPUT`` buffers
+ queued before the seek sequence may have matching ``CAPTURE`` buffers
+ produced. For example, given the sequence of operations on the
+ ``OUTPUT`` queue:
+
+ QBUF(A), QBUF(B), STREAMOFF(), STREAMON(), QBUF(G), QBUF(H),
+
+ any of the following results on the ``CAPTURE`` queue is allowed:
+
+ {A’, B’, G’, H’}, {A’, G’, H’}, {G’, H’}.
+
+ To determine the CAPTURE buffer containing the first decoded frame after the
+ seek, the client may observe the timestamps to match the CAPTURE and OUTPUT
+ buffers or use V4L2_DEC_CMD_STOP and V4L2_DEC_CMD_START to drain the
+ decoder.
+
+.. note::
+
+ To achieve instantaneous seek, the client may restart streaming on the
+ ``CAPTURE`` queue too to discard decoded, but not yet dequeued buffers.
+
+Dynamic Resolution Change
+=========================
+
+Streams that include resolution metadata in the bytestream may require switching
+to a different resolution during the decoding.
+
+.. note::
+
+ Not all decoders can detect resolution changes. Those that do set the
+ ``V4L2_FMT_FLAG_DYN_RESOLUTION`` flag for the coded format when
+ :c:func:`VIDIOC_ENUM_FMT` is called.
+
+The sequence starts when the decoder detects a coded frame with one or more of
+the following parameters different from those previously established (and
+reflected by corresponding queries):
+
+* coded resolution (``OUTPUT`` width and height),
+
+* visible resolution (selection rectangles),
+
+* the minimum number of buffers needed for decoding.
+
+Whenever that happens, the decoder must proceed as follows:
+
+1. After encountering a resolution change in the stream, the decoder sends a
+ ``V4L2_EVENT_SOURCE_CHANGE`` event with ``changes`` set to
+ ``V4L2_EVENT_SRC_CH_RESOLUTION``.
+
+ .. important::
+
+ Any client query issued after the decoder queues the event will return
+ values applying to the stream after the resolution change, including
+ queue formats, selection rectangles and controls.
+
+2. The decoder will then process and decode all remaining buffers from before
+ the resolution change point.
+
+ * The last buffer from before the change must be marked with the
+ ``V4L2_BUF_FLAG_LAST`` flag, similarly to the `Drain` sequence above.
+
+ .. warning::
+
+ The last buffer may be empty (with :c:type:`v4l2_buffer` ``bytesused``
+ = 0) and in that case it must be ignored by the client, as it does not
+ contain a decoded frame.
+
+ .. note::
+
+ Any attempt to dequeue more ``CAPTURE`` buffers beyond the buffer marked
+ with ``V4L2_BUF_FLAG_LAST`` will result in a -EPIPE error from
+ :c:func:`VIDIOC_DQBUF`.
+
+The client must continue the sequence as described below to continue the
+decoding process.
+
+1. Dequeue the source change event.
+
+ .. important::
+
+ A source change triggers an implicit decoder drain, similar to the
+ explicit `Drain` sequence. The decoder is stopped after it completes.
+ The decoding process must be resumed with either a pair of calls to
+ :c:func:`VIDIOC_STREAMOFF` and :c:func:`VIDIOC_STREAMON` on the
+ ``CAPTURE`` queue, or a call to :c:func:`VIDIOC_DECODER_CMD` with the
+ ``V4L2_DEC_CMD_START`` command.
+
+2. Continue with the `Capture Setup` sequence.
+
+.. note::
+
+ During the resolution change sequence, the ``OUTPUT`` queue must remain
+ streaming. Calling :c:func:`VIDIOC_STREAMOFF` on the ``OUTPUT`` queue would
+ abort the sequence and initiate a seek.
+
+ In principle, the ``OUTPUT`` queue operates separately from the ``CAPTURE``
+ queue and this remains true for the duration of the entire resolution change
+ sequence as well.
+
+ The client should, for best performance and simplicity, keep queuing/dequeuing
+ buffers to/from the ``OUTPUT`` queue even while processing this sequence.
+
+Drain
+=====
+
+To ensure that all queued ``OUTPUT`` buffers have been processed and related
+``CAPTURE`` buffers are given to the client, the client must follow the drain
+sequence described below. After the drain sequence ends, the client has
+received all decoded frames for all ``OUTPUT`` buffers queued before the
+sequence was started.
+
+1. Begin drain by issuing :c:func:`VIDIOC_DECODER_CMD`.
+
+ * **Required fields:**
+
+ ``cmd``
+ set to ``V4L2_DEC_CMD_STOP``.
+
+ ``flags``
+ set to 0.
+
+ ``pts``
+ set to 0.
+
+ .. warning::
+
+ The sequence can be only initiated if both ``OUTPUT`` and ``CAPTURE``
+ queues are streaming. For compatibility reasons, the call to
+ :c:func:`VIDIOC_DECODER_CMD` will not fail even if any of the queues is
+ not streaming, but at the same time it will not initiate the `Drain`
+ sequence and so the steps described below would not be applicable.
+
+2. Any ``OUTPUT`` buffers queued by the client before the
+ :c:func:`VIDIOC_DECODER_CMD` was issued will be processed and decoded as
+ normal. The client must continue to handle both queues independently,
+ similarly to normal decode operation. This includes:
+
+ * handling any operations triggered as a result of processing those buffers,
+ such as the `Dynamic Resolution Change` sequence, before continuing with
+ the drain sequence,
+
+ * queuing and dequeuing ``CAPTURE`` buffers, until a buffer marked with the
+ ``V4L2_BUF_FLAG_LAST`` flag is dequeued,
+
+ .. warning::
+
+ The last buffer may be empty (with :c:type:`v4l2_buffer`
+ ``bytesused`` = 0) and in that case it must be ignored by the client,
+ as it does not contain a decoded frame.
+
+ .. note::
+
+ Any attempt to dequeue more ``CAPTURE`` buffers beyond the buffer
+ marked with ``V4L2_BUF_FLAG_LAST`` will result in a -EPIPE error from
+ :c:func:`VIDIOC_DQBUF`.
+
+ * dequeuing processed ``OUTPUT`` buffers, until all the buffers queued
+ before the ``V4L2_DEC_CMD_STOP`` command are dequeued,
+
+ * dequeuing the ``V4L2_EVENT_EOS`` event, if the client subscribed to it.
+
+ .. note::
+
+ For backwards compatibility, the decoder will signal a ``V4L2_EVENT_EOS``
+ event when the last frame has been decoded and all frames are ready to be
+ dequeued. It is a deprecated behavior and the client must not rely on it.
+ The ``V4L2_BUF_FLAG_LAST`` buffer flag should be used instead.
+
+3. Once all the ``OUTPUT`` buffers queued before the ``V4L2_DEC_CMD_STOP`` call
+ are dequeued and the last ``CAPTURE`` buffer is dequeued, the decoder is
+ stopped and it will accept, but not process, any newly queued ``OUTPUT``
+ buffers until the client issues any of the following operations:
+
+ * ``V4L2_DEC_CMD_START`` - the decoder will not be reset and will resume
+ operation normally, with all the state from before the drain,
+
+ * a pair of :c:func:`VIDIOC_STREAMOFF` and :c:func:`VIDIOC_STREAMON` on the
+ ``CAPTURE`` queue - the decoder will resume the operation normally,
+ however any ``CAPTURE`` buffers still in the queue will be returned to the
+ client,
+
+ * a pair of :c:func:`VIDIOC_STREAMOFF` and :c:func:`VIDIOC_STREAMON` on the
+ ``OUTPUT`` queue - any pending source buffers will be returned to the
+ client and the `Seek` sequence will be triggered.
+
+.. note::
+
+ Once the drain sequence is initiated, the client needs to drive it to
+ completion, as described by the steps above, unless it aborts the process by
+ issuing :c:func:`VIDIOC_STREAMOFF` on any of the ``OUTPUT`` or ``CAPTURE``
+ queues. The client is not allowed to issue ``V4L2_DEC_CMD_START`` or
+ ``V4L2_DEC_CMD_STOP`` again while the drain sequence is in progress and they
+ will fail with -EBUSY error code if attempted.
+
+ Although mandatory, the availability of decoder commands may be queried
+ using :c:func:`VIDIOC_TRY_DECODER_CMD`.
+
+End of Stream
+=============
+
+If the decoder encounters an end of stream marking in the stream, the decoder
+will initiate the `Drain` sequence, which the client must handle as described
+above, skipping the initial :c:func:`VIDIOC_DECODER_CMD`.
+
+Commit Points
+=============
+
+Setting formats and allocating buffers trigger changes in the behavior of the
+decoder.
+
+1. Setting the format on the ``OUTPUT`` queue may change the set of formats
+ supported/advertised on the ``CAPTURE`` queue. In particular, it also means
+ that the ``CAPTURE`` format may be reset and the client must not rely on the
+ previously set format being preserved.
+
+2. Enumerating formats on the ``CAPTURE`` queue always returns only formats
+ supported for the current ``OUTPUT`` format.
+
+3. Setting the format on the ``CAPTURE`` queue does not change the list of
+ formats available on the ``OUTPUT`` queue. An attempt to set a ``CAPTURE``
+ format that is not supported for the currently selected ``OUTPUT`` format
+ will result in the decoder adjusting the requested ``CAPTURE`` format to a
+ supported one.
+
+4. Enumerating formats on the ``OUTPUT`` queue always returns the full set of
+ supported coded formats, irrespectively of the current ``CAPTURE`` format.
+
+5. While buffers are allocated on any of the ``OUTPUT`` or ``CAPTURE`` queues,
+ the client must not change the format on the ``OUTPUT`` queue. Drivers will
+ return the -EBUSY error code for any such format change attempt.
+
+To summarize, setting formats and allocation must always start with the
+``OUTPUT`` queue and the ``OUTPUT`` queue is the master that governs the
+set of supported formats for the ``CAPTURE`` queue.
diff --git a/Documentation/media/uapi/v4l/dev-mem2mem.rst b/Documentation/media/uapi/v4l/dev-mem2mem.rst
index 67a9808..caa05f5 100644
--- a/Documentation/media/uapi/v4l/dev-mem2mem.rst
+++ b/Documentation/media/uapi/v4l/dev-mem2mem.rst
@@ -39,4 +39,10 @@
One of the most common memory-to-memory device is the codec. Codecs
are more complicated than most and require additional setup for
their codec parameters. This is done through codec controls.
-See :ref:`mpeg-controls`.
+See :ref:`mpeg-controls`. More details on how to use codec memory-to-memory
+devices are given in the following sections.
+
+.. toctree::
+ :maxdepth: 1
+
+ dev-decoder
diff --git a/Documentation/media/uapi/v4l/ext-ctrls-codec.rst b/Documentation/media/uapi/v4l/ext-ctrls-codec.rst
index d6ea2ff..bc5dd8e 100644
--- a/Documentation/media/uapi/v4l/ext-ctrls-codec.rst
+++ b/Documentation/media/uapi/v4l/ext-ctrls-codec.rst
@@ -1748,6 +1748,14 @@
- ``size``
-
* - __u32
+ - ``start_byte_offset``
+ Offset (in bytes) from the beginning of the OUTPUT buffer to the start
+ of the slice. If the slice starts with a start code, then this is the
+ offset to such start code. When operating in slice-based decoding mode
+ (see :c:type:`v4l2_mpeg_video_h264_decode_mode`), this field should
+ be set to 0. When operating in frame-based decoding mode, this field
+ should be 0 for the first slice.
+ * - __u32
- ``header_bit_size``
-
* - __u16
@@ -1930,19 +1938,13 @@
-
* - __u16
- ``num_slices``
- - Number of slices needed to decode the current frame
+ - Number of slices needed to decode the current frame/field. When
+ operating in slice-based decoding mode (see
+ :c:type:`v4l2_mpeg_video_h264_decode_mode`), this field
+ should always be set to one.
* - __u16
- ``nal_ref_idc``
- NAL reference ID value coming from the NAL Unit header
- * - __u8
- - ``ref_pic_list_p0[32]``
- - Backward reference list used by P-frames in the original bitstream order
- * - __u8
- - ``ref_pic_list_b0[32]``
- - Backward reference list used by B-frames in the original bitstream order
- * - __u8
- - ``ref_pic_list_b1[32]``
- - Forward reference list used by B-frames in the original bitstream order
* - __s32
- ``top_field_order_cnt``
- Picture Order Count for the coded top field
@@ -2021,6 +2023,83 @@
- 0x00000004
- The DPB entry is a long term reference frame
+``V4L2_CID_MPEG_VIDEO_H264_DECODE_MODE (enum)``
+ Specifies the decoding mode to use. Currently exposes slice-based and
+ frame-based decoding but new modes might be added later on.
+ This control is used as a modifier for V4L2_PIX_FMT_H264_SLICE
+ pixel format. Applications that support V4L2_PIX_FMT_H264_SLICE
+ are required to set this control in order to specify the decoding mode
+ that is expected for the buffer.
+ Drivers may expose a single or multiple decoding modes, depending
+ on what they can support.
+
+ .. note::
+
+ This menu control is not yet part of the public kernel API and
+ it is expected to change.
+
+.. c:type:: v4l2_mpeg_video_h264_decode_mode
+
+.. cssclass:: longtable
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+ * - ``V4L2_MPEG_VIDEO_H264_DECODE_MODE_SLICE_BASED``
+ - 0
+ - Decoding is done at the slice granularity.
+ In this mode, ``num_slices`` field in struct
+ :c:type:`v4l2_ctrl_h264_decode_params` should be set to 1,
+ and ``start_byte_offset`` in struct
+ :c:type:`v4l2_ctrl_h264_slice_params` should be set to 0.
+ The OUTPUT buffer must contain a single slice.
+ * - ``V4L2_MPEG_VIDEO_H264_DECODE_MODE_FRAME_BASED``
+ - 1
+ - Decoding is done at the frame granularity.
+ In this mode, ``num_slices`` field in struct
+ :c:type:`v4l2_ctrl_h264_decode_params` should be set to the number
+ of slices in the frame, and ``start_byte_offset`` in struct
+ :c:type:`v4l2_ctrl_h264_slice_params` should be set accordingly
+ for each slice. For the first slice, ``start_byte_offset`` should
+ be zero.
+ The OUTPUT buffer must contain all slices needed to decode the
+ frame. The OUTPUT buffer must also contain both fields.
+
+``V4L2_CID_MPEG_VIDEO_H264_START_CODE (enum)``
+ Specifies the H264 slice start code expected for each slice.
+ This control is used as a modifier for V4L2_PIX_FMT_H264_SLICE
+ pixel format. Applications that support V4L2_PIX_FMT_H264_SLICE
+ are required to set this control in order to specify the start code
+ that is expected for the buffer.
+ Drivers may expose a single or multiple start codes, depending
+ on what they can support.
+
+ .. note::
+
+ This menu control is not yet part of the public kernel API and
+ it is expected to change.
+
+.. c:type:: v4l2_mpeg_video_h264_start_code
+
+.. cssclass:: longtable
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+ * - ``V4L2_MPEG_VIDEO_H264_START_CODE_NONE``
+ - 0
+ - Selecting this value specifies that H264 slices are passed
+ to the driver without any start code.
+ * - ``V4L2_MPEG_VIDEO_H264_START_CODE_ANNEX_B``
+ - 1
+ - Selecting this value specifies that H264 slices are expected
+ to be prefixed by Annex B start codes. According to :ref:`h264`
+ valid start codes can be 3-bytes 0x000001 or 4-bytes 0x00000001.
+
.. _v4l2-mpeg-mpeg2:
``V4L2_CID_MPEG_VIDEO_MPEG2_SLICE_PARAMS (struct)``
@@ -2234,6 +2313,329 @@
Quantization parameter for a P frame for FWHT. Valid range: from 1
to 31.
+.. _v4l2-mpeg-vp8:
+
+``V4L2_CID_MPEG_VIDEO_VP8_FRAME_HEADER (struct)``
+ Specifies the frame parameters for the associated VP8 parsed frame data.
+ This includes the necessary parameters for
+ configuring a stateless hardware decoding pipeline for VP8.
+ The bitstream parameters are defined according to :ref:`vp8`.
+
+ .. note::
+
+ This compound control is not yet part of the public kernel API and
+ it is expected to change.
+
+.. c:type:: v4l2_ctrl_vp8_frame_header
+
+.. cssclass:: longtable
+
+.. tabularcolumns:: |p{5.8cm}|p{4.8cm}|p{6.6cm}|
+
+.. flat-table:: struct v4l2_ctrl_vp8_frame_header
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+ * - struct :c:type:`v4l2_vp8_segment_header`
+ - ``segment_header``
+ - Structure with segment-based adjustments metadata.
+ * - struct :c:type:`v4l2_vp8_loopfilter_header`
+ - ``loopfilter_header``
+ - Structure with loop filter level adjustments metadata.
+ * - struct :c:type:`v4l2_vp8_quantization_header`
+ - ``quant_header``
+ - Structure with VP8 dequantization indices metadata.
+ * - struct :c:type:`v4l2_vp8_entropy_header`
+ - ``entropy_header``
+ - Structure with VP8 entropy coder probabilities metadata.
+ * - struct :c:type:`v4l2_vp8_entropy_coder_state`
+ - ``coder_state``
+ - Structure with VP8 entropy coder state.
+ * - __u16
+ - ``width``
+ - The width of the frame. Must be set for all frames.
+ * - __u16
+ - ``height``
+ - The height of the frame. Must be set for all frames.
+ * - __u8
+ - ``horizontal_scale``
+ - Horizontal scaling factor.
+ * - __u8
+ - ``vertical_scaling factor``
+ - Vertical scale.
+ * - __u8
+ - ``version``
+ - Bitstream version.
+ * - __u8
+ - ``prob_skip_false``
+ - Indicates the probability that the macroblock is not skipped.
+ * - __u8
+ - ``prob_intra``
+ - Indicates the probability that a macroblock is intra-predicted.
+ * - __u8
+ - ``prob_last``
+ - Indicates the probability that the last reference frame is used
+ for inter-prediction
+ * - __u8
+ - ``prob_gf``
+ - Indicates the probability that the golden reference frame is used
+ for inter-prediction
+ * - __u8
+ - ``num_dct_parts``
+ - Number of DCT coefficients partitions. Must be one of: 1, 2, 4, or 8.
+ * - __u32
+ - ``first_part_size``
+ - Size of the first partition, i.e. the control partition.
+ * - __u32
+ - ``first_part_header_bits``
+ - Size in bits of the first partition header portion.
+ * - __u32
+ - ``dct_part_sizes[8]``
+ - DCT coefficients sizes.
+ * - __u64
+ - ``last_frame_ts``
+ - Timestamp for the V4L2 capture buffer to use as last reference frame, used
+ with inter-coded frames. The timestamp refers to the ``timestamp`` field in
+ struct :c:type:`v4l2_buffer`. Use the :c:func:`v4l2_timeval_to_ns()`
+ function to convert the struct :c:type:`timeval` in struct
+ :c:type:`v4l2_buffer` to a __u64.
+ * - __u64
+ - ``golden_frame_ts``
+ - Timestamp for the V4L2 capture buffer to use as last reference frame, used
+ with inter-coded frames. The timestamp refers to the ``timestamp`` field in
+ struct :c:type:`v4l2_buffer`. Use the :c:func:`v4l2_timeval_to_ns()`
+ function to convert the struct :c:type:`timeval` in struct
+ :c:type:`v4l2_buffer` to a __u64.
+ * - __u64
+ - ``alt_frame_ts``
+ - Timestamp for the V4L2 capture buffer to use as alternate reference frame, used
+ with inter-coded frames. The timestamp refers to the ``timestamp`` field in
+ struct :c:type:`v4l2_buffer`. Use the :c:func:`v4l2_timeval_to_ns()`
+ function to convert the struct :c:type:`timeval` in struct
+ :c:type:`v4l2_buffer` to a __u64.
+ * - __u64
+ - ``flags``
+ - See :ref:`Frame Header Flags <vp8_frame_header_flags>`
+
+.. _vp8_frame_header_flags:
+
+``Frame Header Flags``
+
+.. cssclass:: longtable
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+ * - ``V4L2_VP8_FRAME_HEADER_FLAG_KEY_FRAME``
+ - 0x01
+ - Indicates if the frame is a key frame.
+ * - ``V4L2_VP8_FRAME_HEADER_FLAG_EXPERIMENTAL``
+ - 0x02
+ - Experimental bitstream.
+ * - ``V4L2_VP8_FRAME_HEADER_FLAG_SHOW_FRAME``
+ - 0x04
+ - Show frame flag, indicates if the frame is for display.
+ * - ``V4L2_VP8_FRAME_HEADER_FLAG_MB_NO_SKIP_COEFF``
+ - 0x08
+ - Enable/disable skipping of macroblocks with no non-zero coefficients.
+ * - ``V4L2_VP8_FRAME_HEADER_FLAG_SIGN_BIAS_GOLDEN``
+ - 0x10
+ - Sign of motion vectors when the golden frame is referenced.
+ * - ``V4L2_VP8_FRAME_HEADER_FLAG_SIGN_BIAS_ALT``
+ - 0x20
+ - Sign of motion vectors when the alt frame is referenced.
+
+.. c:type:: v4l2_vp8_entropy_coder_state
+
+.. cssclass:: longtable
+
+.. tabularcolumns:: |p{1.5cm}|p{6.3cm}|p{9.4cm}|
+
+.. flat-table:: struct v4l2_vp8_entropy_coder_state
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+ * - __u8
+ - ``range``
+ -
+ * - __u8
+ - ``value``
+ -
+ * - __u8
+ - ``bit_count``
+ -
+ * - __u8
+ - ``padding``
+ - Applications and drivers must set this to zero.
+
+.. c:type:: v4l2_vp8_segment_header
+
+.. cssclass:: longtable
+
+.. tabularcolumns:: |p{1.5cm}|p{6.3cm}|p{9.4cm}|
+
+.. flat-table:: struct v4l2_vp8_segment_header
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+ * - __s8
+ - ``quant_update[4]``
+ - Signed quantizer value update.
+ * - __s8
+ - ``lf_update[4]``
+ - Signed loop filter level value update.
+ * - __u8
+ - ``segment_probs[3]``
+ - Segment probabilities.
+ * - __u8
+ - ``padding``
+ - Applications and drivers must set this to zero.
+ * - __u32
+ - ``flags``
+ - See :ref:`Segment Header Flags <vp8_segment_header_flags>`
+
+.. _vp8_segment_header_flags:
+
+``Segment Header Flags``
+
+.. cssclass:: longtable
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+ * - ``V4L2_VP8_SEGMENT_HEADER_FLAG_ENABLED``
+ - 0x01
+ - Enable/disable segment-based adjustments.
+ * - ``V4L2_VP8_SEGMENT_HEADER_FLAG_UPDATE_MAP``
+ - 0x02
+ - Indicates if the macroblock segmentation map is updated in this frame.
+ * - ``V4L2_VP8_SEGMENT_HEADER_FLAG_UPDATE_FEATURE_DATA``
+ - 0x04
+ - Indicates if the segment feature data is updated in this frame.
+ * - ``V4L2_VP8_SEGMENT_HEADER_FLAG_DELTA_VALUE_MODE``
+ - 0x08
+ - If is set, the segment feature data mode is delta-value.
+ If cleared, it's absolute-value.
+
+.. c:type:: v4l2_vp8_loopfilter_header
+
+.. cssclass:: longtable
+
+.. tabularcolumns:: |p{1.5cm}|p{6.3cm}|p{9.4cm}|
+
+.. flat-table:: struct v4l2_vp8_loopfilter_header
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+ * - __s8
+ - ``ref_frm_delta[4]``
+ - Reference adjustment (signed) delta value.
+ * - __s8
+ - ``mb_mode_delta[4]``
+ - Macroblock prediction mode adjustment (signed) delta value.
+ * - __u8
+ - ``sharpness_level``
+ - Sharpness level
+ * - __u8
+ - ``level``
+ - Filter level
+ * - __u16
+ - ``padding``
+ - Applications and drivers must set this to zero.
+ * - __u32
+ - ``flags``
+ - See :ref:`Loopfilter Header Flags <vp8_loopfilter_header_flags>`
+
+.. _vp8_loopfilter_header_flags:
+
+``Loopfilter Header Flags``
+
+.. cssclass:: longtable
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+ * - ``V4L2_VP8_LF_HEADER_ADJ_ENABLE``
+ - 0x01
+ - Enable/disable macroblock-level loop filter adjustment.
+ * - ``V4L2_VP8_LF_HEADER_DELTA_UPDATE``
+ - 0x02
+ - Indicates if the delta values used in an adjustment are updated.
+ * - ``V4L2_VP8_LF_FILTER_TYPE_SIMPLE``
+ - 0x04
+ - If set, indicates the filter type is simple.
+ If cleared, the filter type is normal.
+
+.. c:type:: v4l2_vp8_quantization_header
+
+.. cssclass:: longtable
+
+.. tabularcolumns:: |p{1.5cm}|p{6.3cm}|p{9.4cm}|
+
+.. flat-table:: struct v4l2_vp8_quantization_header
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+ * - __u8
+ - ``y_ac_qi``
+ - Luma AC coefficient table index.
+ * - __s8
+ - ``y_dc_delta``
+ - Luma DC delta vaue.
+ * - __s8
+ - ``y2_dc_delta``
+ - Y2 block DC delta value.
+ * - __s8
+ - ``y2_ac_delta``
+ - Y2 block AC delta value.
+ * - __s8
+ - ``uv_dc_delta``
+ - Chroma DC delta value.
+ * - __s8
+ - ``uv_ac_delta``
+ - Chroma AC delta value.
+ * - __u16
+ - ``padding``
+ - Applications and drivers must set this to zero.
+
+.. c:type:: v4l2_vp8_entropy_header
+
+.. cssclass:: longtable
+
+.. tabularcolumns:: |p{1.5cm}|p{6.3cm}|p{9.4cm}|
+
+.. flat-table:: struct v4l2_vp8_entropy_header
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+ * - __u8
+ - ``coeff_probs[4][8][3][11]``
+ - Coefficient update probabilities.
+ * - __u8
+ - ``y_mode_probs[4]``
+ - Luma mode update probabilities.
+ * - __u8
+ - ``uv_mode_probs[3]``
+ - Chroma mode update probabilities.
+ * - __u8
+ - ``mv_probs[2][19]``
+ - MV decoding update probabilities.
+ * - __u8
+ - ``padding[3]``
+ - Applications and drivers must set this to zero.
+
.. raw:: latex
\normalsize
diff --git a/Documentation/media/uapi/v4l/hist-v4l2.rst b/Documentation/media/uapi/v4l/hist-v4l2.rst
index 7d8e9ef..9e097f3 100644
--- a/Documentation/media/uapi/v4l/hist-v4l2.rst
+++ b/Documentation/media/uapi/v4l/hist-v4l2.rst
@@ -900,7 +900,7 @@
:ref:`VIDIOC_ENUM_FRAMEINTERVALS`
were added.
-3. A new pixel format ``V4L2_PIX_FMT_RGB444`` (:ref:`rgb-formats`) was
+3. A new pixel format ``V4L2_PIX_FMT_RGB444`` (:ref:`pixfmt-rgb`) was
added.
diff --git a/Documentation/media/uapi/v4l/pixfmt-bayer.rst b/Documentation/media/uapi/v4l/pixfmt-bayer.rst
new file mode 100644
index 0000000..cfa2f4e
--- /dev/null
+++ b/Documentation/media/uapi/v4l/pixfmt-bayer.rst
@@ -0,0 +1,38 @@
+.. Permission is granted to copy, distribute and/or modify this
+.. document under the terms of the GNU Free Documentation License,
+.. Version 1.1 or any later version published by the Free Software
+.. Foundation, with no Invariant Sections, no Front-Cover Texts
+.. and no Back-Cover Texts. A copy of the license is included at
+.. Documentation/media/uapi/fdl-appendix.rst.
+..
+.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
+
+.. _pixfmt-bayer:
+
+*****************
+Raw Bayer Formats
+*****************
+
+Description
+===========
+
+The raw Bayer formats are used by image sensors before much if any processing is
+performed on the image. The formats contain green, red and blue components, with
+alternating lines of red and green, and blue and green pixels in different
+orders. See also `the Wikipedia article on Bayer filter
+<https://en.wikipedia.org/wiki/Bayer_filter>`__.
+
+
+.. toctree::
+ :maxdepth: 1
+
+ pixfmt-srggb8
+ pixfmt-srggb10
+ pixfmt-srggb10p
+ pixfmt-srggb10alaw8
+ pixfmt-srggb10dpcm8
+ pixfmt-srggb10-ipu3
+ pixfmt-srggb12
+ pixfmt-srggb12p
+ pixfmt-srggb14p
+ pixfmt-srggb16
diff --git a/Documentation/media/uapi/v4l/pixfmt-compressed.rst b/Documentation/media/uapi/v4l/pixfmt-compressed.rst
index 4b701fc..292fdc1 100644
--- a/Documentation/media/uapi/v4l/pixfmt-compressed.rst
+++ b/Documentation/media/uapi/v4l/pixfmt-compressed.rst
@@ -41,7 +41,12 @@
- ``V4L2_PIX_FMT_H264``
- 'H264'
- - H264 video elementary stream with start codes.
+ - H264 Access Unit.
+ The decoder expects one Access Unit per buffer.
+ The encoder generates one Access Unit per buffer.
+ If :ref:`VIDIOC_ENUM_FMT` reports ``V4L2_FMT_FLAG_CONTINUOUS_BYTESTREAM``
+ then the decoder has no requirements since it can parse all the
+ information from the raw bytestream.
* .. _V4L2-PIX-FMT-H264-NO-SC:
- ``V4L2_PIX_FMT_H264_NO_SC``
@@ -52,16 +57,19 @@
- ``V4L2_PIX_FMT_H264_MVC``
- 'M264'
- H264 MVC video elementary stream.
- * .. _V4L2-PIX-FMT-H264-SLICE-RAW:
+ * .. _V4L2-PIX-FMT-H264-SLICE:
- - ``V4L2_PIX_FMT_H264_SLICE_RAW``
+ - ``V4L2_PIX_FMT_H264_SLICE``
- 'S264'
- H264 parsed slice data, without the start code and as
extracted from the H264 bitstream. This format is adapted for
stateless video decoders that implement an H264 pipeline
(using the :ref:`mem2mem` and :ref:`media-request-api`).
- Metadata associated with the frame to decode are required to
- be passed through the ``V4L2_CID_MPEG_VIDEO_H264_SPS``,
+ This pixelformat has two modifiers that must be set at least once
+ through the ``V4L2_CID_MPEG_VIDEO_H264_DECODE_MODE``
+ and ``V4L2_CID_MPEG_VIDEO_H264_START_CODE`` controls.
+ In addition, metadata associated with the frame to decode are
+ required to be passed through the ``V4L2_CID_MPEG_VIDEO_H264_SPS``,
``V4L2_CID_MPEG_VIDEO_H264_PPS``,
``V4L2_CID_MPEG_VIDEO_H264_SCALING_MATRIX``,
``V4L2_CID_MPEG_VIDEO_H264_SLICE_PARAMS`` and
@@ -86,12 +94,20 @@
- ``V4L2_PIX_FMT_MPEG1``
- 'MPG1'
- - MPEG1 video elementary stream.
+ - MPEG1 Picture. Each buffer starts with a Picture header, followed
+ by other headers as needed and ending with the Picture data.
+ If :ref:`VIDIOC_ENUM_FMT` reports ``V4L2_FMT_FLAG_CONTINUOUS_BYTESTREAM``
+ then the decoder has no requirements since it can parse all the
+ information from the raw bytestream.
* .. _V4L2-PIX-FMT-MPEG2:
- ``V4L2_PIX_FMT_MPEG2``
- 'MPG2'
- - MPEG2 video elementary stream.
+ - MPEG2 Picture. Each buffer starts with a Picture header, followed
+ by other headers as needed and ending with the Picture data.
+ If :ref:`VIDIOC_ENUM_FMT` reports ``V4L2_FMT_FLAG_CONTINUOUS_BYTESTREAM``
+ then the decoder has no requirements since it can parse all the
+ information from the raw bytestream.
* .. _V4L2-PIX-FMT-MPEG2-SLICE:
- ``V4L2_PIX_FMT_MPEG2_SLICE``
@@ -132,17 +148,46 @@
- ``V4L2_PIX_FMT_VP8``
- 'VP80'
- - VP8 video elementary stream.
+ - VP8 compressed video frame. The encoder generates one
+ compressed frame per buffer, and the decoder requires one
+ compressed frame per buffer.
+ * .. _V4L2-PIX-FMT-VP8-FRAME:
+
+ - ``V4L2_PIX_FMT_VP8_FRAME``
+ - 'VP8F'
+ - VP8 parsed frame, as extracted from the container.
+ This format is adapted for stateless video decoders that implement a
+ VP8 pipeline (using the :ref:`mem2mem` and :ref:`media-request-api`).
+ Metadata associated with the frame to decode is required to be passed
+ through the ``V4L2_CID_MPEG_VIDEO_VP8_FRAME_HEADER`` control.
+ See the :ref:`associated Codec Control IDs <v4l2-mpeg-vp8>`.
+ Exactly one output and one capture buffer must be provided for use with
+ this pixel format. The output buffer must contain the appropriate number
+ of macroblocks to decode a full corresponding frame to the matching
+ capture buffer.
+
+ .. note::
+
+ This format is not yet part of the public kernel API and it
+ is expected to change.
+
* .. _V4L2-PIX-FMT-VP9:
- ``V4L2_PIX_FMT_VP9``
- 'VP90'
- - VP9 video elementary stream.
+ - VP9 compressed video frame. The encoder generates one
+ compressed frame per buffer, and the decoder requires one
+ compressed frame per buffer.
* .. _V4L2-PIX-FMT-HEVC:
- ``V4L2_PIX_FMT_HEVC``
- 'HEVC'
- - HEVC/H.265 video elementary stream.
+ - HEVC/H.265 Access Unit.
+ The decoder expects one Access Unit per buffer.
+ The encoder generates one Access Unit per buffer.
+ If :ref:`VIDIOC_ENUM_FMT` reports ``V4L2_FMT_FLAG_CONTINUOUS_BYTESTREAM``
+ then the decoder has no requirements since it can parse all the
+ information from the raw bytestream.
* .. _V4L2-PIX-FMT-FWHT:
- ``V4L2_PIX_FMT_FWHT``
@@ -150,6 +195,8 @@
- Video elementary stream using a codec based on the Fast Walsh Hadamard
Transform. This codec is implemented by the vicodec ('Virtual Codec')
driver. See the codec-fwht.h header for more details.
+ :ref:`VIDIOC_ENUM_FMT` reports ``V4L2_FMT_FLAG_CONTINUOUS_BYTESTREAM``
+ since the decoder can parse all the information from the raw bytestream.
* .. _V4L2-PIX-FMT-FWHT-STATELESS:
- ``V4L2_PIX_FMT_FWHT_STATELESS``
diff --git a/Documentation/media/uapi/v4l/pixfmt-packed-rgb.rst b/Documentation/media/uapi/v4l/pixfmt-packed-rgb.rst
deleted file mode 100644
index 738bb14..0000000
--- a/Documentation/media/uapi/v4l/pixfmt-packed-rgb.rst
+++ /dev/null
@@ -1,1306 +0,0 @@
-.. Permission is granted to copy, distribute and/or modify this
-.. document under the terms of the GNU Free Documentation License,
-.. Version 1.1 or any later version published by the Free Software
-.. Foundation, with no Invariant Sections, no Front-Cover Texts
-.. and no Back-Cover Texts. A copy of the license is included at
-.. Documentation/media/uapi/fdl-appendix.rst.
-..
-.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
-
-.. _packed-rgb:
-
-******************
-Packed RGB formats
-******************
-
-Description
-===========
-
-These formats are designed to match the pixel formats of typical PC
-graphics frame buffers. They occupy 8, 16, 24 or 32 bits per pixel.
-These are all packed-pixel formats, meaning all the data for a pixel lie
-next to each other in memory.
-
-.. raw:: latex
-
- \begingroup
- \tiny
- \setlength{\tabcolsep}{2pt}
-
-.. tabularcolumns:: |p{2.8cm}|p{2.0cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|
-
-
-.. _rgb-formats:
-
-.. flat-table:: Packed RGB Image Formats
- :header-rows: 2
- :stub-columns: 0
-
- * - Identifier
- - Code
- - :cspan:`7` Byte 0 in memory
- - :cspan:`7` Byte 1
- - :cspan:`7` Byte 2
- - :cspan:`7` Byte 3
- * -
- -
- - 7
- - 6
- - 5
- - 4
- - 3
- - 2
- - 1
- - 0
-
- - 7
- - 6
- - 5
- - 4
- - 3
- - 2
- - 1
- - 0
-
- - 7
- - 6
- - 5
- - 4
- - 3
- - 2
- - 1
- - 0
-
- - 7
- - 6
- - 5
- - 4
- - 3
- - 2
- - 1
- - 0
- * .. _V4L2-PIX-FMT-RGB332:
-
- - ``V4L2_PIX_FMT_RGB332``
- - 'RGB1'
-
- - r\ :sub:`2`
- - r\ :sub:`1`
- - r\ :sub:`0`
- - g\ :sub:`2`
- - g\ :sub:`1`
- - g\ :sub:`0`
- - b\ :sub:`1`
- - b\ :sub:`0`
- -
- * .. _V4L2-PIX-FMT-ARGB444:
-
- - ``V4L2_PIX_FMT_ARGB444``
- - 'AR12'
-
- - g\ :sub:`3`
- - g\ :sub:`2`
- - g\ :sub:`1`
- - g\ :sub:`0`
- - b\ :sub:`3`
- - b\ :sub:`2`
- - b\ :sub:`1`
- - b\ :sub:`0`
-
- - a\ :sub:`3`
- - a\ :sub:`2`
- - a\ :sub:`1`
- - a\ :sub:`0`
- - r\ :sub:`3`
- - r\ :sub:`2`
- - r\ :sub:`1`
- - r\ :sub:`0`
- -
- * .. _V4L2-PIX-FMT-XRGB444:
-
- - ``V4L2_PIX_FMT_XRGB444``
- - 'XR12'
-
- - g\ :sub:`3`
- - g\ :sub:`2`
- - g\ :sub:`1`
- - g\ :sub:`0`
- - b\ :sub:`3`
- - b\ :sub:`2`
- - b\ :sub:`1`
- - b\ :sub:`0`
-
- -
- -
- -
- -
- - r\ :sub:`3`
- - r\ :sub:`2`
- - r\ :sub:`1`
- - r\ :sub:`0`
- -
- * .. _V4L2-PIX-FMT-RGBA444:
-
- - ``V4L2_PIX_FMT_RGBA444``
- - 'RA12'
-
- - b\ :sub:`3`
- - b\ :sub:`2`
- - b\ :sub:`1`
- - b\ :sub:`0`
- - a\ :sub:`3`
- - a\ :sub:`2`
- - a\ :sub:`1`
- - a\ :sub:`0`
-
- - r\ :sub:`3`
- - r\ :sub:`2`
- - r\ :sub:`1`
- - r\ :sub:`0`
- - g\ :sub:`3`
- - g\ :sub:`2`
- - g\ :sub:`1`
- - g\ :sub:`0`
- -
- * .. _V4L2-PIX-FMT-RGBX444:
-
- - ``V4L2_PIX_FMT_RGBX444``
- - 'RX12'
-
- - b\ :sub:`3`
- - b\ :sub:`2`
- - b\ :sub:`1`
- - b\ :sub:`0`
- -
- -
- -
- -
-
- - r\ :sub:`3`
- - r\ :sub:`2`
- - r\ :sub:`1`
- - r\ :sub:`0`
- - g\ :sub:`3`
- - g\ :sub:`2`
- - g\ :sub:`1`
- - g\ :sub:`0`
- -
- * .. _V4L2-PIX-FMT-ABGR444:
-
- - ``V4L2_PIX_FMT_ABGR444``
- - 'AB12'
-
- - g\ :sub:`3`
- - g\ :sub:`2`
- - g\ :sub:`1`
- - g\ :sub:`0`
- - r\ :sub:`3`
- - r\ :sub:`2`
- - r\ :sub:`1`
- - r\ :sub:`0`
-
- - a\ :sub:`3`
- - a\ :sub:`2`
- - a\ :sub:`1`
- - a\ :sub:`0`
- - b\ :sub:`3`
- - b\ :sub:`2`
- - b\ :sub:`1`
- - b\ :sub:`0`
- -
- * .. _V4L2-PIX-FMT-XBGR444:
-
- - ``V4L2_PIX_FMT_XBGR444``
- - 'XB12'
-
- - g\ :sub:`3`
- - g\ :sub:`2`
- - g\ :sub:`1`
- - g\ :sub:`0`
- - r\ :sub:`3`
- - r\ :sub:`2`
- - r\ :sub:`1`
- - r\ :sub:`0`
-
- -
- -
- -
- -
- - b\ :sub:`3`
- - b\ :sub:`2`
- - b\ :sub:`1`
- - b\ :sub:`0`
- -
- * .. _V4L2-PIX-FMT-BGRA444:
-
- - ``V4L2_PIX_FMT_BGRA444``
- - 'BA12'
-
- - r\ :sub:`3`
- - r\ :sub:`2`
- - r\ :sub:`1`
- - r\ :sub:`0`
- - a\ :sub:`3`
- - a\ :sub:`2`
- - a\ :sub:`1`
- - a\ :sub:`0`
-
- - b\ :sub:`3`
- - b\ :sub:`2`
- - b\ :sub:`1`
- - b\ :sub:`0`
- - g\ :sub:`3`
- - g\ :sub:`2`
- - g\ :sub:`1`
- - g\ :sub:`0`
- -
- * .. _V4L2-PIX-FMT-BGRX444:
-
- - ``V4L2_PIX_FMT_BGRX444``
- - 'BX12'
-
- - r\ :sub:`3`
- - r\ :sub:`2`
- - r\ :sub:`1`
- - r\ :sub:`0`
- -
- -
- -
- -
-
- - b\ :sub:`3`
- - b\ :sub:`2`
- - b\ :sub:`1`
- - b\ :sub:`0`
- - g\ :sub:`3`
- - g\ :sub:`2`
- - g\ :sub:`1`
- - g\ :sub:`0`
- -
- * .. _V4L2-PIX-FMT-ARGB555:
-
- - ``V4L2_PIX_FMT_ARGB555``
- - 'AR15'
-
- - g\ :sub:`2`
- - g\ :sub:`1`
- - g\ :sub:`0`
- - b\ :sub:`4`
- - b\ :sub:`3`
- - b\ :sub:`2`
- - b\ :sub:`1`
- - b\ :sub:`0`
-
- - a
- - r\ :sub:`4`
- - r\ :sub:`3`
- - r\ :sub:`2`
- - r\ :sub:`1`
- - r\ :sub:`0`
- - g\ :sub:`4`
- - g\ :sub:`3`
- -
- * .. _V4L2-PIX-FMT-XRGB555:
-
- - ``V4L2_PIX_FMT_XRGB555``
- - 'XR15'
-
- - g\ :sub:`2`
- - g\ :sub:`1`
- - g\ :sub:`0`
- - b\ :sub:`4`
- - b\ :sub:`3`
- - b\ :sub:`2`
- - b\ :sub:`1`
- - b\ :sub:`0`
-
- -
- - r\ :sub:`4`
- - r\ :sub:`3`
- - r\ :sub:`2`
- - r\ :sub:`1`
- - r\ :sub:`0`
- - g\ :sub:`4`
- - g\ :sub:`3`
- -
- * .. _V4L2-PIX-FMT-RGBA555:
-
- - ``V4L2_PIX_FMT_RGBA555``
- - 'RA15'
-
- - g\ :sub:`1`
- - g\ :sub:`0`
- - b\ :sub:`4`
- - b\ :sub:`3`
- - b\ :sub:`2`
- - b\ :sub:`1`
- - b\ :sub:`0`
- - a
-
- - r\ :sub:`4`
- - r\ :sub:`3`
- - r\ :sub:`2`
- - r\ :sub:`1`
- - r\ :sub:`0`
- - g\ :sub:`4`
- - g\ :sub:`3`
- - g\ :sub:`2`
- -
- * .. _V4L2-PIX-FMT-RGBX555:
-
- - ``V4L2_PIX_FMT_RGBX555``
- - 'RX15'
-
- - g\ :sub:`1`
- - g\ :sub:`0`
- - b\ :sub:`4`
- - b\ :sub:`3`
- - b\ :sub:`2`
- - b\ :sub:`1`
- - b\ :sub:`0`
- -
-
- - r\ :sub:`4`
- - r\ :sub:`3`
- - r\ :sub:`2`
- - r\ :sub:`1`
- - r\ :sub:`0`
- - g\ :sub:`4`
- - g\ :sub:`3`
- - g\ :sub:`2`
- -
- * .. _V4L2-PIX-FMT-ABGR555:
-
- - ``V4L2_PIX_FMT_ABGR555``
- - 'AB15'
-
- - g\ :sub:`2`
- - g\ :sub:`1`
- - g\ :sub:`0`
- - r\ :sub:`4`
- - r\ :sub:`3`
- - r\ :sub:`2`
- - r\ :sub:`1`
- - r\ :sub:`0`
-
- - a
- - b\ :sub:`4`
- - b\ :sub:`3`
- - b\ :sub:`2`
- - b\ :sub:`1`
- - b\ :sub:`0`
- - g\ :sub:`4`
- - g\ :sub:`3`
- -
- * .. _V4L2-PIX-FMT-XBGR555:
-
- - ``V4L2_PIX_FMT_XBGR555``
- - 'XB15'
-
- - g\ :sub:`2`
- - g\ :sub:`1`
- - g\ :sub:`0`
- - r\ :sub:`4`
- - r\ :sub:`3`
- - r\ :sub:`2`
- - r\ :sub:`1`
- - r\ :sub:`0`
-
- -
- - b\ :sub:`4`
- - b\ :sub:`3`
- - b\ :sub:`2`
- - b\ :sub:`1`
- - b\ :sub:`0`
- - g\ :sub:`4`
- - g\ :sub:`3`
- -
- * .. _V4L2-PIX-FMT-BGRA555:
-
- - ``V4L2_PIX_FMT_BGRA555``
- - 'BA15'
-
- - g\ :sub:`1`
- - g\ :sub:`0`
- - r\ :sub:`4`
- - r\ :sub:`3`
- - r\ :sub:`2`
- - r\ :sub:`1`
- - r\ :sub:`0`
- - a
-
- - b\ :sub:`4`
- - b\ :sub:`3`
- - b\ :sub:`2`
- - b\ :sub:`1`
- - b\ :sub:`0`
- - g\ :sub:`4`
- - g\ :sub:`3`
- - g\ :sub:`2`
- -
- * .. _V4L2-PIX-FMT-BGRX555:
-
- - ``V4L2_PIX_FMT_BGRX555``
- - 'BX15'
-
- - g\ :sub:`1`
- - g\ :sub:`0`
- - r\ :sub:`4`
- - r\ :sub:`3`
- - r\ :sub:`2`
- - r\ :sub:`1`
- - r\ :sub:`0`
- -
-
- - b\ :sub:`4`
- - b\ :sub:`3`
- - b\ :sub:`2`
- - b\ :sub:`1`
- - b\ :sub:`0`
- - g\ :sub:`4`
- - g\ :sub:`3`
- - g\ :sub:`2`
- -
- * .. _V4L2-PIX-FMT-RGB565:
-
- - ``V4L2_PIX_FMT_RGB565``
- - 'RGBP'
-
- - g\ :sub:`2`
- - g\ :sub:`1`
- - g\ :sub:`0`
- - b\ :sub:`4`
- - b\ :sub:`3`
- - b\ :sub:`2`
- - b\ :sub:`1`
- - b\ :sub:`0`
-
- - r\ :sub:`4`
- - r\ :sub:`3`
- - r\ :sub:`2`
- - r\ :sub:`1`
- - r\ :sub:`0`
- - g\ :sub:`5`
- - g\ :sub:`4`
- - g\ :sub:`3`
- -
- * .. _V4L2-PIX-FMT-ARGB555X:
-
- - ``V4L2_PIX_FMT_ARGB555X``
- - 'AR15' | (1 << 31)
-
- - a
- - r\ :sub:`4`
- - r\ :sub:`3`
- - r\ :sub:`2`
- - r\ :sub:`1`
- - r\ :sub:`0`
- - g\ :sub:`4`
- - g\ :sub:`3`
-
- - g\ :sub:`2`
- - g\ :sub:`1`
- - g\ :sub:`0`
- - b\ :sub:`4`
- - b\ :sub:`3`
- - b\ :sub:`2`
- - b\ :sub:`1`
- - b\ :sub:`0`
- -
- * .. _V4L2-PIX-FMT-XRGB555X:
-
- - ``V4L2_PIX_FMT_XRGB555X``
- - 'XR15' | (1 << 31)
-
- -
- - r\ :sub:`4`
- - r\ :sub:`3`
- - r\ :sub:`2`
- - r\ :sub:`1`
- - r\ :sub:`0`
- - g\ :sub:`4`
- - g\ :sub:`3`
-
- - g\ :sub:`2`
- - g\ :sub:`1`
- - g\ :sub:`0`
- - b\ :sub:`4`
- - b\ :sub:`3`
- - b\ :sub:`2`
- - b\ :sub:`1`
- - b\ :sub:`0`
- -
- * .. _V4L2-PIX-FMT-RGB565X:
-
- - ``V4L2_PIX_FMT_RGB565X``
- - 'RGBR'
-
- - r\ :sub:`4`
- - r\ :sub:`3`
- - r\ :sub:`2`
- - r\ :sub:`1`
- - r\ :sub:`0`
- - g\ :sub:`5`
- - g\ :sub:`4`
- - g\ :sub:`3`
-
- - g\ :sub:`2`
- - g\ :sub:`1`
- - g\ :sub:`0`
- - b\ :sub:`4`
- - b\ :sub:`3`
- - b\ :sub:`2`
- - b\ :sub:`1`
- - b\ :sub:`0`
- -
- * .. _V4L2-PIX-FMT-BGR24:
-
- - ``V4L2_PIX_FMT_BGR24``
- - 'BGR3'
-
- - b\ :sub:`7`
- - b\ :sub:`6`
- - b\ :sub:`5`
- - b\ :sub:`4`
- - b\ :sub:`3`
- - b\ :sub:`2`
- - b\ :sub:`1`
- - b\ :sub:`0`
-
- - g\ :sub:`7`
- - g\ :sub:`6`
- - g\ :sub:`5`
- - g\ :sub:`4`
- - g\ :sub:`3`
- - g\ :sub:`2`
- - g\ :sub:`1`
- - g\ :sub:`0`
-
- - r\ :sub:`7`
- - r\ :sub:`6`
- - r\ :sub:`5`
- - r\ :sub:`4`
- - r\ :sub:`3`
- - r\ :sub:`2`
- - r\ :sub:`1`
- - r\ :sub:`0`
- -
- * .. _V4L2-PIX-FMT-RGB24:
-
- - ``V4L2_PIX_FMT_RGB24``
- - 'RGB3'
-
- - r\ :sub:`7`
- - r\ :sub:`6`
- - r\ :sub:`5`
- - r\ :sub:`4`
- - r\ :sub:`3`
- - r\ :sub:`2`
- - r\ :sub:`1`
- - r\ :sub:`0`
-
- - g\ :sub:`7`
- - g\ :sub:`6`
- - g\ :sub:`5`
- - g\ :sub:`4`
- - g\ :sub:`3`
- - g\ :sub:`2`
- - g\ :sub:`1`
- - g\ :sub:`0`
-
- - b\ :sub:`7`
- - b\ :sub:`6`
- - b\ :sub:`5`
- - b\ :sub:`4`
- - b\ :sub:`3`
- - b\ :sub:`2`
- - b\ :sub:`1`
- - b\ :sub:`0`
- -
- * .. _V4L2-PIX-FMT-BGR666:
-
- - ``V4L2_PIX_FMT_BGR666``
- - 'BGRH'
-
- - b\ :sub:`5`
- - b\ :sub:`4`
- - b\ :sub:`3`
- - b\ :sub:`2`
- - b\ :sub:`1`
- - b\ :sub:`0`
- - g\ :sub:`5`
- - g\ :sub:`4`
-
- - g\ :sub:`3`
- - g\ :sub:`2`
- - g\ :sub:`1`
- - g\ :sub:`0`
- - r\ :sub:`5`
- - r\ :sub:`4`
- - r\ :sub:`3`
- - r\ :sub:`2`
-
- - r\ :sub:`1`
- - r\ :sub:`0`
- -
- -
- -
- -
- -
- -
-
- -
- -
- -
- -
- -
- -
- -
- -
- * .. _V4L2-PIX-FMT-ABGR32:
-
- - ``V4L2_PIX_FMT_ABGR32``
- - 'AR24'
-
- - b\ :sub:`7`
- - b\ :sub:`6`
- - b\ :sub:`5`
- - b\ :sub:`4`
- - b\ :sub:`3`
- - b\ :sub:`2`
- - b\ :sub:`1`
- - b\ :sub:`0`
-
- - g\ :sub:`7`
- - g\ :sub:`6`
- - g\ :sub:`5`
- - g\ :sub:`4`
- - g\ :sub:`3`
- - g\ :sub:`2`
- - g\ :sub:`1`
- - g\ :sub:`0`
-
- - r\ :sub:`7`
- - r\ :sub:`6`
- - r\ :sub:`5`
- - r\ :sub:`4`
- - r\ :sub:`3`
- - r\ :sub:`2`
- - r\ :sub:`1`
- - r\ :sub:`0`
-
- - a\ :sub:`7`
- - a\ :sub:`6`
- - a\ :sub:`5`
- - a\ :sub:`4`
- - a\ :sub:`3`
- - a\ :sub:`2`
- - a\ :sub:`1`
- - a\ :sub:`0`
- * .. _V4L2-PIX-FMT-XBGR32:
-
- - ``V4L2_PIX_FMT_XBGR32``
- - 'XR24'
-
- - b\ :sub:`7`
- - b\ :sub:`6`
- - b\ :sub:`5`
- - b\ :sub:`4`
- - b\ :sub:`3`
- - b\ :sub:`2`
- - b\ :sub:`1`
- - b\ :sub:`0`
-
- - g\ :sub:`7`
- - g\ :sub:`6`
- - g\ :sub:`5`
- - g\ :sub:`4`
- - g\ :sub:`3`
- - g\ :sub:`2`
- - g\ :sub:`1`
- - g\ :sub:`0`
-
- - r\ :sub:`7`
- - r\ :sub:`6`
- - r\ :sub:`5`
- - r\ :sub:`4`
- - r\ :sub:`3`
- - r\ :sub:`2`
- - r\ :sub:`1`
- - r\ :sub:`0`
-
- -
- -
- -
- -
- -
- -
- -
- -
- * .. _V4L2-PIX-FMT-BGRA32:
-
- - ``V4L2_PIX_FMT_BGRA32``
- - 'RA24'
-
- - a\ :sub:`7`
- - a\ :sub:`6`
- - a\ :sub:`5`
- - a\ :sub:`4`
- - a\ :sub:`3`
- - a\ :sub:`2`
- - a\ :sub:`1`
- - a\ :sub:`0`
-
- - b\ :sub:`7`
- - b\ :sub:`6`
- - b\ :sub:`5`
- - b\ :sub:`4`
- - b\ :sub:`3`
- - b\ :sub:`2`
- - b\ :sub:`1`
- - b\ :sub:`0`
-
- - g\ :sub:`7`
- - g\ :sub:`6`
- - g\ :sub:`5`
- - g\ :sub:`4`
- - g\ :sub:`3`
- - g\ :sub:`2`
- - g\ :sub:`1`
- - g\ :sub:`0`
-
- - r\ :sub:`7`
- - r\ :sub:`6`
- - r\ :sub:`5`
- - r\ :sub:`4`
- - r\ :sub:`3`
- - r\ :sub:`2`
- - r\ :sub:`1`
- - r\ :sub:`0`
- * .. _V4L2-PIX-FMT-BGRX32:
-
- - ``V4L2_PIX_FMT_BGRX32``
- - 'RX24'
-
- -
- -
- -
- -
- -
- -
- -
- -
-
- - b\ :sub:`7`
- - b\ :sub:`6`
- - b\ :sub:`5`
- - b\ :sub:`4`
- - b\ :sub:`3`
- - b\ :sub:`2`
- - b\ :sub:`1`
- - b\ :sub:`0`
-
- - g\ :sub:`7`
- - g\ :sub:`6`
- - g\ :sub:`5`
- - g\ :sub:`4`
- - g\ :sub:`3`
- - g\ :sub:`2`
- - g\ :sub:`1`
- - g\ :sub:`0`
-
- - r\ :sub:`7`
- - r\ :sub:`6`
- - r\ :sub:`5`
- - r\ :sub:`4`
- - r\ :sub:`3`
- - r\ :sub:`2`
- - r\ :sub:`1`
- - r\ :sub:`0`
- * .. _V4L2-PIX-FMT-RGBA32:
-
- - ``V4L2_PIX_FMT_RGBA32``
- - 'AB24'
-
- - r\ :sub:`7`
- - r\ :sub:`6`
- - r\ :sub:`5`
- - r\ :sub:`4`
- - r\ :sub:`3`
- - r\ :sub:`2`
- - r\ :sub:`1`
- - r\ :sub:`0`
-
- - g\ :sub:`7`
- - g\ :sub:`6`
- - g\ :sub:`5`
- - g\ :sub:`4`
- - g\ :sub:`3`
- - g\ :sub:`2`
- - g\ :sub:`1`
- - g\ :sub:`0`
-
- - b\ :sub:`7`
- - b\ :sub:`6`
- - b\ :sub:`5`
- - b\ :sub:`4`
- - b\ :sub:`3`
- - b\ :sub:`2`
- - b\ :sub:`1`
- - b\ :sub:`0`
-
- - a\ :sub:`7`
- - a\ :sub:`6`
- - a\ :sub:`5`
- - a\ :sub:`4`
- - a\ :sub:`3`
- - a\ :sub:`2`
- - a\ :sub:`1`
- - a\ :sub:`0`
- * .. _V4L2-PIX-FMT-RGBX32:
-
- - ``V4L2_PIX_FMT_RGBX32``
- - 'XB24'
-
- - r\ :sub:`7`
- - r\ :sub:`6`
- - r\ :sub:`5`
- - r\ :sub:`4`
- - r\ :sub:`3`
- - r\ :sub:`2`
- - r\ :sub:`1`
- - r\ :sub:`0`
-
- - g\ :sub:`7`
- - g\ :sub:`6`
- - g\ :sub:`5`
- - g\ :sub:`4`
- - g\ :sub:`3`
- - g\ :sub:`2`
- - g\ :sub:`1`
- - g\ :sub:`0`
-
- - b\ :sub:`7`
- - b\ :sub:`6`
- - b\ :sub:`5`
- - b\ :sub:`4`
- - b\ :sub:`3`
- - b\ :sub:`2`
- - b\ :sub:`1`
- - b\ :sub:`0`
-
- -
- -
- -
- -
- -
- -
- -
- -
- * .. _V4L2-PIX-FMT-ARGB32:
-
- - ``V4L2_PIX_FMT_ARGB32``
- - 'BA24'
-
- - a\ :sub:`7`
- - a\ :sub:`6`
- - a\ :sub:`5`
- - a\ :sub:`4`
- - a\ :sub:`3`
- - a\ :sub:`2`
- - a\ :sub:`1`
- - a\ :sub:`0`
-
- - r\ :sub:`7`
- - r\ :sub:`6`
- - r\ :sub:`5`
- - r\ :sub:`4`
- - r\ :sub:`3`
- - r\ :sub:`2`
- - r\ :sub:`1`
- - r\ :sub:`0`
-
- - g\ :sub:`7`
- - g\ :sub:`6`
- - g\ :sub:`5`
- - g\ :sub:`4`
- - g\ :sub:`3`
- - g\ :sub:`2`
- - g\ :sub:`1`
- - g\ :sub:`0`
-
- - b\ :sub:`7`
- - b\ :sub:`6`
- - b\ :sub:`5`
- - b\ :sub:`4`
- - b\ :sub:`3`
- - b\ :sub:`2`
- - b\ :sub:`1`
- - b\ :sub:`0`
- * .. _V4L2-PIX-FMT-XRGB32:
-
- - ``V4L2_PIX_FMT_XRGB32``
- - 'BX24'
-
- -
- -
- -
- -
- -
- -
- -
- -
-
- - r\ :sub:`7`
- - r\ :sub:`6`
- - r\ :sub:`5`
- - r\ :sub:`4`
- - r\ :sub:`3`
- - r\ :sub:`2`
- - r\ :sub:`1`
- - r\ :sub:`0`
-
- - g\ :sub:`7`
- - g\ :sub:`6`
- - g\ :sub:`5`
- - g\ :sub:`4`
- - g\ :sub:`3`
- - g\ :sub:`2`
- - g\ :sub:`1`
- - g\ :sub:`0`
-
- - b\ :sub:`7`
- - b\ :sub:`6`
- - b\ :sub:`5`
- - b\ :sub:`4`
- - b\ :sub:`3`
- - b\ :sub:`2`
- - b\ :sub:`1`
- - b\ :sub:`0`
-
-.. raw:: latex
-
- \endgroup
-
-.. note:: Bit 7 is the most significant bit.
-
-The usage and value of the alpha bits (a) in the ARGB and ABGR formats
-(collectively referred to as alpha formats) depend on the device type
-and hardware operation. :ref:`Capture <capture>` devices (including
-capture queues of mem-to-mem devices) fill the alpha component in
-memory. When the device outputs an alpha channel the alpha component
-will have a meaningful value. Otherwise, when the device doesn't output
-an alpha channel but can set the alpha bit to a user-configurable value,
-the :ref:`V4L2_CID_ALPHA_COMPONENT <v4l2-alpha-component>` control
-is used to specify that alpha value, and the alpha component of all
-pixels will be set to the value specified by that control. Otherwise a
-corresponding format without an alpha component (XRGB or XBGR) must be
-used instead of an alpha format.
-
-:ref:`Output <output>` devices (including output queues of mem-to-mem
-devices and :ref:`video output overlay <osd>` devices) read the alpha
-component from memory. When the device processes the alpha channel the
-alpha component must be filled with meaningful values by applications.
-Otherwise a corresponding format without an alpha component (XRGB or
-XBGR) must be used instead of an alpha format.
-
-The XRGB and XBGR formats contain undefined bits (-). Applications,
-devices and drivers must ignore those bits, for both
-:ref:`capture` and :ref:`output` devices.
-
-**Byte Order.**
-Each cell is one byte.
-
-
-.. raw:: latex
-
- \small
-
-.. tabularcolumns:: |p{3.1cm}|p{0.8cm}|p{0.8cm}|p{0.8cm}|p{0.8cm}|p{0.8cm}|p{0.8cm}|p{0.8cm}|p{0.8cm}|p{0.8cm}|p{0.8cm}|p{0.8cm}|p{0.8cm}|
-
-.. flat-table:: RGB byte order
- :header-rows: 0
- :stub-columns: 0
- :widths: 11 3 3 3 3 3 3 3 3 3 3 3 3
-
- * - start + 0:
- - B\ :sub:`00`
- - G\ :sub:`00`
- - R\ :sub:`00`
- - B\ :sub:`01`
- - G\ :sub:`01`
- - R\ :sub:`01`
- - B\ :sub:`02`
- - G\ :sub:`02`
- - R\ :sub:`02`
- - B\ :sub:`03`
- - G\ :sub:`03`
- - R\ :sub:`03`
- * - start + 12:
- - B\ :sub:`10`
- - G\ :sub:`10`
- - R\ :sub:`10`
- - B\ :sub:`11`
- - G\ :sub:`11`
- - R\ :sub:`11`
- - B\ :sub:`12`
- - G\ :sub:`12`
- - R\ :sub:`12`
- - B\ :sub:`13`
- - G\ :sub:`13`
- - R\ :sub:`13`
- * - start + 24:
- - B\ :sub:`20`
- - G\ :sub:`20`
- - R\ :sub:`20`
- - B\ :sub:`21`
- - G\ :sub:`21`
- - R\ :sub:`21`
- - B\ :sub:`22`
- - G\ :sub:`22`
- - R\ :sub:`22`
- - B\ :sub:`23`
- - G\ :sub:`23`
- - R\ :sub:`23`
- * - start + 36:
- - B\ :sub:`30`
- - G\ :sub:`30`
- - R\ :sub:`30`
- - B\ :sub:`31`
- - G\ :sub:`31`
- - R\ :sub:`31`
- - B\ :sub:`32`
- - G\ :sub:`32`
- - R\ :sub:`32`
- - B\ :sub:`33`
- - G\ :sub:`33`
- - R\ :sub:`33`
-
-.. raw:: latex
-
- \normalsize
-
-Formats defined in :ref:`rgb-formats-deprecated` are deprecated and
-must not be used by new drivers. They are documented here for reference.
-The meaning of their alpha bits ``(a)`` are ill-defined and interpreted as in
-either the corresponding ARGB or XRGB format, depending on the driver.
-
-
-.. raw:: latex
-
- \begingroup
- \tiny
- \setlength{\tabcolsep}{2pt}
-
-.. tabularcolumns:: |p{2.6cm}|p{0.70cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|
-
-.. _rgb-formats-deprecated:
-
-.. flat-table:: Deprecated Packed RGB Image Formats
- :header-rows: 2
- :stub-columns: 0
-
- * - Identifier
- - Code
- - :cspan:`7` Byte 0 in memory
-
- - :cspan:`7` Byte 1
-
- - :cspan:`7` Byte 2
-
- - :cspan:`7` Byte 3
- * -
- -
- - 7
- - 6
- - 5
- - 4
- - 3
- - 2
- - 1
- - 0
-
- - 7
- - 6
- - 5
- - 4
- - 3
- - 2
- - 1
- - 0
-
- - 7
- - 6
- - 5
- - 4
- - 3
- - 2
- - 1
- - 0
-
- - 7
- - 6
- - 5
- - 4
- - 3
- - 2
- - 1
- - 0
- * .. _V4L2-PIX-FMT-RGB444:
-
- - ``V4L2_PIX_FMT_RGB444``
- - 'R444'
-
- - g\ :sub:`3`
- - g\ :sub:`2`
- - g\ :sub:`1`
- - g\ :sub:`0`
- - b\ :sub:`3`
- - b\ :sub:`2`
- - b\ :sub:`1`
- - b\ :sub:`0`
-
- - a\ :sub:`3`
- - a\ :sub:`2`
- - a\ :sub:`1`
- - a\ :sub:`0`
- - r\ :sub:`3`
- - r\ :sub:`2`
- - r\ :sub:`1`
- - r\ :sub:`0`
- -
- * .. _V4L2-PIX-FMT-RGB555:
-
- - ``V4L2_PIX_FMT_RGB555``
- - 'RGBO'
-
- - g\ :sub:`2`
- - g\ :sub:`1`
- - g\ :sub:`0`
- - b\ :sub:`4`
- - b\ :sub:`3`
- - b\ :sub:`2`
- - b\ :sub:`1`
- - b\ :sub:`0`
-
- - a
- - r\ :sub:`4`
- - r\ :sub:`3`
- - r\ :sub:`2`
- - r\ :sub:`1`
- - r\ :sub:`0`
- - g\ :sub:`4`
- - g\ :sub:`3`
- -
- * .. _V4L2-PIX-FMT-RGB555X:
-
- - ``V4L2_PIX_FMT_RGB555X``
- - 'RGBQ'
-
- - a
- - r\ :sub:`4`
- - r\ :sub:`3`
- - r\ :sub:`2`
- - r\ :sub:`1`
- - r\ :sub:`0`
- - g\ :sub:`4`
- - g\ :sub:`3`
-
- - g\ :sub:`2`
- - g\ :sub:`1`
- - g\ :sub:`0`
- - b\ :sub:`4`
- - b\ :sub:`3`
- - b\ :sub:`2`
- - b\ :sub:`1`
- - b\ :sub:`0`
- -
- * .. _V4L2-PIX-FMT-BGR32:
-
- - ``V4L2_PIX_FMT_BGR32``
- - 'BGR4'
-
- - b\ :sub:`7`
- - b\ :sub:`6`
- - b\ :sub:`5`
- - b\ :sub:`4`
- - b\ :sub:`3`
- - b\ :sub:`2`
- - b\ :sub:`1`
- - b\ :sub:`0`
-
- - g\ :sub:`7`
- - g\ :sub:`6`
- - g\ :sub:`5`
- - g\ :sub:`4`
- - g\ :sub:`3`
- - g\ :sub:`2`
- - g\ :sub:`1`
- - g\ :sub:`0`
-
- - r\ :sub:`7`
- - r\ :sub:`6`
- - r\ :sub:`5`
- - r\ :sub:`4`
- - r\ :sub:`3`
- - r\ :sub:`2`
- - r\ :sub:`1`
- - r\ :sub:`0`
-
- - a\ :sub:`7`
- - a\ :sub:`6`
- - a\ :sub:`5`
- - a\ :sub:`4`
- - a\ :sub:`3`
- - a\ :sub:`2`
- - a\ :sub:`1`
- - a\ :sub:`0`
- * .. _V4L2-PIX-FMT-RGB32:
-
- - ``V4L2_PIX_FMT_RGB32``
- - 'RGB4'
-
- - a\ :sub:`7`
- - a\ :sub:`6`
- - a\ :sub:`5`
- - a\ :sub:`4`
- - a\ :sub:`3`
- - a\ :sub:`2`
- - a\ :sub:`1`
- - a\ :sub:`0`
-
- - r\ :sub:`7`
- - r\ :sub:`6`
- - r\ :sub:`5`
- - r\ :sub:`4`
- - r\ :sub:`3`
- - r\ :sub:`2`
- - r\ :sub:`1`
- - r\ :sub:`0`
-
- - g\ :sub:`7`
- - g\ :sub:`6`
- - g\ :sub:`5`
- - g\ :sub:`4`
- - g\ :sub:`3`
- - g\ :sub:`2`
- - g\ :sub:`1`
- - g\ :sub:`0`
-
- - b\ :sub:`7`
- - b\ :sub:`6`
- - b\ :sub:`5`
- - b\ :sub:`4`
- - b\ :sub:`3`
- - b\ :sub:`2`
- - b\ :sub:`1`
- - b\ :sub:`0`
-
-.. raw:: latex
-
- \endgroup
-
-A test utility to determine which RGB formats a driver actually supports
-is available from the LinuxTV v4l-dvb repository. See
-`https://linuxtv.org/repo/ <https://linuxtv.org/repo/>`__ for access
-instructions.
diff --git a/Documentation/media/uapi/v4l/pixfmt-rgb.rst b/Documentation/media/uapi/v4l/pixfmt-rgb.rst
index 48ab800..4ce305c 100644
--- a/Documentation/media/uapi/v4l/pixfmt-rgb.rst
+++ b/Documentation/media/uapi/v4l/pixfmt-rgb.rst
@@ -13,18 +13,1292 @@
RGB Formats
***********
+Description
+===========
-.. toctree::
- :maxdepth: 1
+These formats are designed to match the pixel formats of typical PC
+graphics frame buffers. They occupy 8, 16, 24 or 32 bits per pixel.
+These are all packed-pixel formats, meaning all the data for a pixel lie
+next to each other in memory.
- pixfmt-packed-rgb
- pixfmt-srggb8
- pixfmt-srggb10
- pixfmt-srggb10p
- pixfmt-srggb10alaw8
- pixfmt-srggb10dpcm8
- pixfmt-srggb10-ipu3
- pixfmt-srggb12
- pixfmt-srggb12p
- pixfmt-srggb14p
- pixfmt-srggb16
+.. raw:: latex
+
+ \begingroup
+ \tiny
+ \setlength{\tabcolsep}{2pt}
+
+.. tabularcolumns:: |p{2.8cm}|p{2.0cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|
+
+
+.. flat-table:: RGB Image Formats
+ :header-rows: 2
+ :stub-columns: 0
+
+ * - Identifier
+ - Code
+ - :cspan:`7` Byte 0 in memory
+ - :cspan:`7` Byte 1
+ - :cspan:`7` Byte 2
+ - :cspan:`7` Byte 3
+ * -
+ -
+ - 7
+ - 6
+ - 5
+ - 4
+ - 3
+ - 2
+ - 1
+ - 0
+
+ - 7
+ - 6
+ - 5
+ - 4
+ - 3
+ - 2
+ - 1
+ - 0
+
+ - 7
+ - 6
+ - 5
+ - 4
+ - 3
+ - 2
+ - 1
+ - 0
+
+ - 7
+ - 6
+ - 5
+ - 4
+ - 3
+ - 2
+ - 1
+ - 0
+ * .. _V4L2-PIX-FMT-RGB332:
+
+ - ``V4L2_PIX_FMT_RGB332``
+ - 'RGB1'
+
+ - r\ :sub:`2`
+ - r\ :sub:`1`
+ - r\ :sub:`0`
+ - g\ :sub:`2`
+ - g\ :sub:`1`
+ - g\ :sub:`0`
+ - b\ :sub:`1`
+ - b\ :sub:`0`
+ -
+ * .. _V4L2-PIX-FMT-ARGB444:
+
+ - ``V4L2_PIX_FMT_ARGB444``
+ - 'AR12'
+
+ - g\ :sub:`3`
+ - g\ :sub:`2`
+ - g\ :sub:`1`
+ - g\ :sub:`0`
+ - b\ :sub:`3`
+ - b\ :sub:`2`
+ - b\ :sub:`1`
+ - b\ :sub:`0`
+
+ - a\ :sub:`3`
+ - a\ :sub:`2`
+ - a\ :sub:`1`
+ - a\ :sub:`0`
+ - r\ :sub:`3`
+ - r\ :sub:`2`
+ - r\ :sub:`1`
+ - r\ :sub:`0`
+ -
+ * .. _V4L2-PIX-FMT-XRGB444:
+
+ - ``V4L2_PIX_FMT_XRGB444``
+ - 'XR12'
+
+ - g\ :sub:`3`
+ - g\ :sub:`2`
+ - g\ :sub:`1`
+ - g\ :sub:`0`
+ - b\ :sub:`3`
+ - b\ :sub:`2`
+ - b\ :sub:`1`
+ - b\ :sub:`0`
+
+ -
+ -
+ -
+ -
+ - r\ :sub:`3`
+ - r\ :sub:`2`
+ - r\ :sub:`1`
+ - r\ :sub:`0`
+ -
+ * .. _V4L2-PIX-FMT-RGBA444:
+
+ - ``V4L2_PIX_FMT_RGBA444``
+ - 'RA12'
+
+ - b\ :sub:`3`
+ - b\ :sub:`2`
+ - b\ :sub:`1`
+ - b\ :sub:`0`
+ - a\ :sub:`3`
+ - a\ :sub:`2`
+ - a\ :sub:`1`
+ - a\ :sub:`0`
+
+ - r\ :sub:`3`
+ - r\ :sub:`2`
+ - r\ :sub:`1`
+ - r\ :sub:`0`
+ - g\ :sub:`3`
+ - g\ :sub:`2`
+ - g\ :sub:`1`
+ - g\ :sub:`0`
+ -
+ * .. _V4L2-PIX-FMT-RGBX444:
+
+ - ``V4L2_PIX_FMT_RGBX444``
+ - 'RX12'
+
+ - b\ :sub:`3`
+ - b\ :sub:`2`
+ - b\ :sub:`1`
+ - b\ :sub:`0`
+ -
+ -
+ -
+ -
+
+ - r\ :sub:`3`
+ - r\ :sub:`2`
+ - r\ :sub:`1`
+ - r\ :sub:`0`
+ - g\ :sub:`3`
+ - g\ :sub:`2`
+ - g\ :sub:`1`
+ - g\ :sub:`0`
+ -
+ * .. _V4L2-PIX-FMT-ABGR444:
+
+ - ``V4L2_PIX_FMT_ABGR444``
+ - 'AB12'
+
+ - g\ :sub:`3`
+ - g\ :sub:`2`
+ - g\ :sub:`1`
+ - g\ :sub:`0`
+ - r\ :sub:`3`
+ - r\ :sub:`2`
+ - r\ :sub:`1`
+ - r\ :sub:`0`
+
+ - a\ :sub:`3`
+ - a\ :sub:`2`
+ - a\ :sub:`1`
+ - a\ :sub:`0`
+ - b\ :sub:`3`
+ - b\ :sub:`2`
+ - b\ :sub:`1`
+ - b\ :sub:`0`
+ -
+ * .. _V4L2-PIX-FMT-XBGR444:
+
+ - ``V4L2_PIX_FMT_XBGR444``
+ - 'XB12'
+
+ - g\ :sub:`3`
+ - g\ :sub:`2`
+ - g\ :sub:`1`
+ - g\ :sub:`0`
+ - r\ :sub:`3`
+ - r\ :sub:`2`
+ - r\ :sub:`1`
+ - r\ :sub:`0`
+
+ -
+ -
+ -
+ -
+ - b\ :sub:`3`
+ - b\ :sub:`2`
+ - b\ :sub:`1`
+ - b\ :sub:`0`
+ -
+ * .. _V4L2-PIX-FMT-BGRA444:
+
+ - ``V4L2_PIX_FMT_BGRA444``
+ - 'BA12'
+
+ - r\ :sub:`3`
+ - r\ :sub:`2`
+ - r\ :sub:`1`
+ - r\ :sub:`0`
+ - a\ :sub:`3`
+ - a\ :sub:`2`
+ - a\ :sub:`1`
+ - a\ :sub:`0`
+
+ - b\ :sub:`3`
+ - b\ :sub:`2`
+ - b\ :sub:`1`
+ - b\ :sub:`0`
+ - g\ :sub:`3`
+ - g\ :sub:`2`
+ - g\ :sub:`1`
+ - g\ :sub:`0`
+ -
+ * .. _V4L2-PIX-FMT-BGRX444:
+
+ - ``V4L2_PIX_FMT_BGRX444``
+ - 'BX12'
+
+ - r\ :sub:`3`
+ - r\ :sub:`2`
+ - r\ :sub:`1`
+ - r\ :sub:`0`
+ -
+ -
+ -
+ -
+
+ - b\ :sub:`3`
+ - b\ :sub:`2`
+ - b\ :sub:`1`
+ - b\ :sub:`0`
+ - g\ :sub:`3`
+ - g\ :sub:`2`
+ - g\ :sub:`1`
+ - g\ :sub:`0`
+ -
+ * .. _V4L2-PIX-FMT-ARGB555:
+
+ - ``V4L2_PIX_FMT_ARGB555``
+ - 'AR15'
+
+ - g\ :sub:`2`
+ - g\ :sub:`1`
+ - g\ :sub:`0`
+ - b\ :sub:`4`
+ - b\ :sub:`3`
+ - b\ :sub:`2`
+ - b\ :sub:`1`
+ - b\ :sub:`0`
+
+ - a
+ - r\ :sub:`4`
+ - r\ :sub:`3`
+ - r\ :sub:`2`
+ - r\ :sub:`1`
+ - r\ :sub:`0`
+ - g\ :sub:`4`
+ - g\ :sub:`3`
+ -
+ * .. _V4L2-PIX-FMT-XRGB555:
+
+ - ``V4L2_PIX_FMT_XRGB555``
+ - 'XR15'
+
+ - g\ :sub:`2`
+ - g\ :sub:`1`
+ - g\ :sub:`0`
+ - b\ :sub:`4`
+ - b\ :sub:`3`
+ - b\ :sub:`2`
+ - b\ :sub:`1`
+ - b\ :sub:`0`
+
+ -
+ - r\ :sub:`4`
+ - r\ :sub:`3`
+ - r\ :sub:`2`
+ - r\ :sub:`1`
+ - r\ :sub:`0`
+ - g\ :sub:`4`
+ - g\ :sub:`3`
+ -
+ * .. _V4L2-PIX-FMT-RGBA555:
+
+ - ``V4L2_PIX_FMT_RGBA555``
+ - 'RA15'
+
+ - g\ :sub:`1`
+ - g\ :sub:`0`
+ - b\ :sub:`4`
+ - b\ :sub:`3`
+ - b\ :sub:`2`
+ - b\ :sub:`1`
+ - b\ :sub:`0`
+ - a
+
+ - r\ :sub:`4`
+ - r\ :sub:`3`
+ - r\ :sub:`2`
+ - r\ :sub:`1`
+ - r\ :sub:`0`
+ - g\ :sub:`4`
+ - g\ :sub:`3`
+ - g\ :sub:`2`
+ -
+ * .. _V4L2-PIX-FMT-RGBX555:
+
+ - ``V4L2_PIX_FMT_RGBX555``
+ - 'RX15'
+
+ - g\ :sub:`1`
+ - g\ :sub:`0`
+ - b\ :sub:`4`
+ - b\ :sub:`3`
+ - b\ :sub:`2`
+ - b\ :sub:`1`
+ - b\ :sub:`0`
+ -
+
+ - r\ :sub:`4`
+ - r\ :sub:`3`
+ - r\ :sub:`2`
+ - r\ :sub:`1`
+ - r\ :sub:`0`
+ - g\ :sub:`4`
+ - g\ :sub:`3`
+ - g\ :sub:`2`
+ -
+ * .. _V4L2-PIX-FMT-ABGR555:
+
+ - ``V4L2_PIX_FMT_ABGR555``
+ - 'AB15'
+
+ - g\ :sub:`2`
+ - g\ :sub:`1`
+ - g\ :sub:`0`
+ - r\ :sub:`4`
+ - r\ :sub:`3`
+ - r\ :sub:`2`
+ - r\ :sub:`1`
+ - r\ :sub:`0`
+
+ - a
+ - b\ :sub:`4`
+ - b\ :sub:`3`
+ - b\ :sub:`2`
+ - b\ :sub:`1`
+ - b\ :sub:`0`
+ - g\ :sub:`4`
+ - g\ :sub:`3`
+ -
+ * .. _V4L2-PIX-FMT-XBGR555:
+
+ - ``V4L2_PIX_FMT_XBGR555``
+ - 'XB15'
+
+ - g\ :sub:`2`
+ - g\ :sub:`1`
+ - g\ :sub:`0`
+ - r\ :sub:`4`
+ - r\ :sub:`3`
+ - r\ :sub:`2`
+ - r\ :sub:`1`
+ - r\ :sub:`0`
+
+ -
+ - b\ :sub:`4`
+ - b\ :sub:`3`
+ - b\ :sub:`2`
+ - b\ :sub:`1`
+ - b\ :sub:`0`
+ - g\ :sub:`4`
+ - g\ :sub:`3`
+ -
+ * .. _V4L2-PIX-FMT-BGRA555:
+
+ - ``V4L2_PIX_FMT_BGRA555``
+ - 'BA15'
+
+ - g\ :sub:`1`
+ - g\ :sub:`0`
+ - r\ :sub:`4`
+ - r\ :sub:`3`
+ - r\ :sub:`2`
+ - r\ :sub:`1`
+ - r\ :sub:`0`
+ - a
+
+ - b\ :sub:`4`
+ - b\ :sub:`3`
+ - b\ :sub:`2`
+ - b\ :sub:`1`
+ - b\ :sub:`0`
+ - g\ :sub:`4`
+ - g\ :sub:`3`
+ - g\ :sub:`2`
+ -
+ * .. _V4L2-PIX-FMT-BGRX555:
+
+ - ``V4L2_PIX_FMT_BGRX555``
+ - 'BX15'
+
+ - g\ :sub:`1`
+ - g\ :sub:`0`
+ - r\ :sub:`4`
+ - r\ :sub:`3`
+ - r\ :sub:`2`
+ - r\ :sub:`1`
+ - r\ :sub:`0`
+ -
+
+ - b\ :sub:`4`
+ - b\ :sub:`3`
+ - b\ :sub:`2`
+ - b\ :sub:`1`
+ - b\ :sub:`0`
+ - g\ :sub:`4`
+ - g\ :sub:`3`
+ - g\ :sub:`2`
+ -
+ * .. _V4L2-PIX-FMT-RGB565:
+
+ - ``V4L2_PIX_FMT_RGB565``
+ - 'RGBP'
+
+ - g\ :sub:`2`
+ - g\ :sub:`1`
+ - g\ :sub:`0`
+ - b\ :sub:`4`
+ - b\ :sub:`3`
+ - b\ :sub:`2`
+ - b\ :sub:`1`
+ - b\ :sub:`0`
+
+ - r\ :sub:`4`
+ - r\ :sub:`3`
+ - r\ :sub:`2`
+ - r\ :sub:`1`
+ - r\ :sub:`0`
+ - g\ :sub:`5`
+ - g\ :sub:`4`
+ - g\ :sub:`3`
+ -
+ * .. _V4L2-PIX-FMT-ARGB555X:
+
+ - ``V4L2_PIX_FMT_ARGB555X``
+ - 'AR15' | (1 << 31)
+
+ - a
+ - r\ :sub:`4`
+ - r\ :sub:`3`
+ - r\ :sub:`2`
+ - r\ :sub:`1`
+ - r\ :sub:`0`
+ - g\ :sub:`4`
+ - g\ :sub:`3`
+
+ - g\ :sub:`2`
+ - g\ :sub:`1`
+ - g\ :sub:`0`
+ - b\ :sub:`4`
+ - b\ :sub:`3`
+ - b\ :sub:`2`
+ - b\ :sub:`1`
+ - b\ :sub:`0`
+ -
+ * .. _V4L2-PIX-FMT-XRGB555X:
+
+ - ``V4L2_PIX_FMT_XRGB555X``
+ - 'XR15' | (1 << 31)
+
+ -
+ - r\ :sub:`4`
+ - r\ :sub:`3`
+ - r\ :sub:`2`
+ - r\ :sub:`1`
+ - r\ :sub:`0`
+ - g\ :sub:`4`
+ - g\ :sub:`3`
+
+ - g\ :sub:`2`
+ - g\ :sub:`1`
+ - g\ :sub:`0`
+ - b\ :sub:`4`
+ - b\ :sub:`3`
+ - b\ :sub:`2`
+ - b\ :sub:`1`
+ - b\ :sub:`0`
+ -
+ * .. _V4L2-PIX-FMT-RGB565X:
+
+ - ``V4L2_PIX_FMT_RGB565X``
+ - 'RGBR'
+
+ - r\ :sub:`4`
+ - r\ :sub:`3`
+ - r\ :sub:`2`
+ - r\ :sub:`1`
+ - r\ :sub:`0`
+ - g\ :sub:`5`
+ - g\ :sub:`4`
+ - g\ :sub:`3`
+
+ - g\ :sub:`2`
+ - g\ :sub:`1`
+ - g\ :sub:`0`
+ - b\ :sub:`4`
+ - b\ :sub:`3`
+ - b\ :sub:`2`
+ - b\ :sub:`1`
+ - b\ :sub:`0`
+ -
+ * .. _V4L2-PIX-FMT-BGR24:
+
+ - ``V4L2_PIX_FMT_BGR24``
+ - 'BGR3'
+
+ - b\ :sub:`7`
+ - b\ :sub:`6`
+ - b\ :sub:`5`
+ - b\ :sub:`4`
+ - b\ :sub:`3`
+ - b\ :sub:`2`
+ - b\ :sub:`1`
+ - b\ :sub:`0`
+
+ - g\ :sub:`7`
+ - g\ :sub:`6`
+ - g\ :sub:`5`
+ - g\ :sub:`4`
+ - g\ :sub:`3`
+ - g\ :sub:`2`
+ - g\ :sub:`1`
+ - g\ :sub:`0`
+
+ - r\ :sub:`7`
+ - r\ :sub:`6`
+ - r\ :sub:`5`
+ - r\ :sub:`4`
+ - r\ :sub:`3`
+ - r\ :sub:`2`
+ - r\ :sub:`1`
+ - r\ :sub:`0`
+ -
+ * .. _V4L2-PIX-FMT-RGB24:
+
+ - ``V4L2_PIX_FMT_RGB24``
+ - 'RGB3'
+
+ - r\ :sub:`7`
+ - r\ :sub:`6`
+ - r\ :sub:`5`
+ - r\ :sub:`4`
+ - r\ :sub:`3`
+ - r\ :sub:`2`
+ - r\ :sub:`1`
+ - r\ :sub:`0`
+
+ - g\ :sub:`7`
+ - g\ :sub:`6`
+ - g\ :sub:`5`
+ - g\ :sub:`4`
+ - g\ :sub:`3`
+ - g\ :sub:`2`
+ - g\ :sub:`1`
+ - g\ :sub:`0`
+
+ - b\ :sub:`7`
+ - b\ :sub:`6`
+ - b\ :sub:`5`
+ - b\ :sub:`4`
+ - b\ :sub:`3`
+ - b\ :sub:`2`
+ - b\ :sub:`1`
+ - b\ :sub:`0`
+ -
+ * .. _V4L2-PIX-FMT-BGR666:
+
+ - ``V4L2_PIX_FMT_BGR666``
+ - 'BGRH'
+
+ - b\ :sub:`5`
+ - b\ :sub:`4`
+ - b\ :sub:`3`
+ - b\ :sub:`2`
+ - b\ :sub:`1`
+ - b\ :sub:`0`
+ - g\ :sub:`5`
+ - g\ :sub:`4`
+
+ - g\ :sub:`3`
+ - g\ :sub:`2`
+ - g\ :sub:`1`
+ - g\ :sub:`0`
+ - r\ :sub:`5`
+ - r\ :sub:`4`
+ - r\ :sub:`3`
+ - r\ :sub:`2`
+
+ - r\ :sub:`1`
+ - r\ :sub:`0`
+ -
+ -
+ -
+ -
+ -
+ -
+
+ -
+ -
+ -
+ -
+ -
+ -
+ -
+ -
+ * .. _V4L2-PIX-FMT-ABGR32:
+
+ - ``V4L2_PIX_FMT_ABGR32``
+ - 'AR24'
+
+ - b\ :sub:`7`
+ - b\ :sub:`6`
+ - b\ :sub:`5`
+ - b\ :sub:`4`
+ - b\ :sub:`3`
+ - b\ :sub:`2`
+ - b\ :sub:`1`
+ - b\ :sub:`0`
+
+ - g\ :sub:`7`
+ - g\ :sub:`6`
+ - g\ :sub:`5`
+ - g\ :sub:`4`
+ - g\ :sub:`3`
+ - g\ :sub:`2`
+ - g\ :sub:`1`
+ - g\ :sub:`0`
+
+ - r\ :sub:`7`
+ - r\ :sub:`6`
+ - r\ :sub:`5`
+ - r\ :sub:`4`
+ - r\ :sub:`3`
+ - r\ :sub:`2`
+ - r\ :sub:`1`
+ - r\ :sub:`0`
+
+ - a\ :sub:`7`
+ - a\ :sub:`6`
+ - a\ :sub:`5`
+ - a\ :sub:`4`
+ - a\ :sub:`3`
+ - a\ :sub:`2`
+ - a\ :sub:`1`
+ - a\ :sub:`0`
+ * .. _V4L2-PIX-FMT-XBGR32:
+
+ - ``V4L2_PIX_FMT_XBGR32``
+ - 'XR24'
+
+ - b\ :sub:`7`
+ - b\ :sub:`6`
+ - b\ :sub:`5`
+ - b\ :sub:`4`
+ - b\ :sub:`3`
+ - b\ :sub:`2`
+ - b\ :sub:`1`
+ - b\ :sub:`0`
+
+ - g\ :sub:`7`
+ - g\ :sub:`6`
+ - g\ :sub:`5`
+ - g\ :sub:`4`
+ - g\ :sub:`3`
+ - g\ :sub:`2`
+ - g\ :sub:`1`
+ - g\ :sub:`0`
+
+ - r\ :sub:`7`
+ - r\ :sub:`6`
+ - r\ :sub:`5`
+ - r\ :sub:`4`
+ - r\ :sub:`3`
+ - r\ :sub:`2`
+ - r\ :sub:`1`
+ - r\ :sub:`0`
+
+ -
+ -
+ -
+ -
+ -
+ -
+ -
+ -
+ * .. _V4L2-PIX-FMT-BGRA32:
+
+ - ``V4L2_PIX_FMT_BGRA32``
+ - 'RA24'
+
+ - a\ :sub:`7`
+ - a\ :sub:`6`
+ - a\ :sub:`5`
+ - a\ :sub:`4`
+ - a\ :sub:`3`
+ - a\ :sub:`2`
+ - a\ :sub:`1`
+ - a\ :sub:`0`
+
+ - b\ :sub:`7`
+ - b\ :sub:`6`
+ - b\ :sub:`5`
+ - b\ :sub:`4`
+ - b\ :sub:`3`
+ - b\ :sub:`2`
+ - b\ :sub:`1`
+ - b\ :sub:`0`
+
+ - g\ :sub:`7`
+ - g\ :sub:`6`
+ - g\ :sub:`5`
+ - g\ :sub:`4`
+ - g\ :sub:`3`
+ - g\ :sub:`2`
+ - g\ :sub:`1`
+ - g\ :sub:`0`
+
+ - r\ :sub:`7`
+ - r\ :sub:`6`
+ - r\ :sub:`5`
+ - r\ :sub:`4`
+ - r\ :sub:`3`
+ - r\ :sub:`2`
+ - r\ :sub:`1`
+ - r\ :sub:`0`
+ * .. _V4L2-PIX-FMT-BGRX32:
+
+ - ``V4L2_PIX_FMT_BGRX32``
+ - 'RX24'
+
+ -
+ -
+ -
+ -
+ -
+ -
+ -
+ -
+
+ - b\ :sub:`7`
+ - b\ :sub:`6`
+ - b\ :sub:`5`
+ - b\ :sub:`4`
+ - b\ :sub:`3`
+ - b\ :sub:`2`
+ - b\ :sub:`1`
+ - b\ :sub:`0`
+
+ - g\ :sub:`7`
+ - g\ :sub:`6`
+ - g\ :sub:`5`
+ - g\ :sub:`4`
+ - g\ :sub:`3`
+ - g\ :sub:`2`
+ - g\ :sub:`1`
+ - g\ :sub:`0`
+
+ - r\ :sub:`7`
+ - r\ :sub:`6`
+ - r\ :sub:`5`
+ - r\ :sub:`4`
+ - r\ :sub:`3`
+ - r\ :sub:`2`
+ - r\ :sub:`1`
+ - r\ :sub:`0`
+ * .. _V4L2-PIX-FMT-RGBA32:
+
+ - ``V4L2_PIX_FMT_RGBA32``
+ - 'AB24'
+
+ - r\ :sub:`7`
+ - r\ :sub:`6`
+ - r\ :sub:`5`
+ - r\ :sub:`4`
+ - r\ :sub:`3`
+ - r\ :sub:`2`
+ - r\ :sub:`1`
+ - r\ :sub:`0`
+
+ - g\ :sub:`7`
+ - g\ :sub:`6`
+ - g\ :sub:`5`
+ - g\ :sub:`4`
+ - g\ :sub:`3`
+ - g\ :sub:`2`
+ - g\ :sub:`1`
+ - g\ :sub:`0`
+
+ - b\ :sub:`7`
+ - b\ :sub:`6`
+ - b\ :sub:`5`
+ - b\ :sub:`4`
+ - b\ :sub:`3`
+ - b\ :sub:`2`
+ - b\ :sub:`1`
+ - b\ :sub:`0`
+
+ - a\ :sub:`7`
+ - a\ :sub:`6`
+ - a\ :sub:`5`
+ - a\ :sub:`4`
+ - a\ :sub:`3`
+ - a\ :sub:`2`
+ - a\ :sub:`1`
+ - a\ :sub:`0`
+ * .. _V4L2-PIX-FMT-RGBX32:
+
+ - ``V4L2_PIX_FMT_RGBX32``
+ - 'XB24'
+
+ - r\ :sub:`7`
+ - r\ :sub:`6`
+ - r\ :sub:`5`
+ - r\ :sub:`4`
+ - r\ :sub:`3`
+ - r\ :sub:`2`
+ - r\ :sub:`1`
+ - r\ :sub:`0`
+
+ - g\ :sub:`7`
+ - g\ :sub:`6`
+ - g\ :sub:`5`
+ - g\ :sub:`4`
+ - g\ :sub:`3`
+ - g\ :sub:`2`
+ - g\ :sub:`1`
+ - g\ :sub:`0`
+
+ - b\ :sub:`7`
+ - b\ :sub:`6`
+ - b\ :sub:`5`
+ - b\ :sub:`4`
+ - b\ :sub:`3`
+ - b\ :sub:`2`
+ - b\ :sub:`1`
+ - b\ :sub:`0`
+
+ -
+ -
+ -
+ -
+ -
+ -
+ -
+ -
+ * .. _V4L2-PIX-FMT-ARGB32:
+
+ - ``V4L2_PIX_FMT_ARGB32``
+ - 'BA24'
+
+ - a\ :sub:`7`
+ - a\ :sub:`6`
+ - a\ :sub:`5`
+ - a\ :sub:`4`
+ - a\ :sub:`3`
+ - a\ :sub:`2`
+ - a\ :sub:`1`
+ - a\ :sub:`0`
+
+ - r\ :sub:`7`
+ - r\ :sub:`6`
+ - r\ :sub:`5`
+ - r\ :sub:`4`
+ - r\ :sub:`3`
+ - r\ :sub:`2`
+ - r\ :sub:`1`
+ - r\ :sub:`0`
+
+ - g\ :sub:`7`
+ - g\ :sub:`6`
+ - g\ :sub:`5`
+ - g\ :sub:`4`
+ - g\ :sub:`3`
+ - g\ :sub:`2`
+ - g\ :sub:`1`
+ - g\ :sub:`0`
+
+ - b\ :sub:`7`
+ - b\ :sub:`6`
+ - b\ :sub:`5`
+ - b\ :sub:`4`
+ - b\ :sub:`3`
+ - b\ :sub:`2`
+ - b\ :sub:`1`
+ - b\ :sub:`0`
+ * .. _V4L2-PIX-FMT-XRGB32:
+
+ - ``V4L2_PIX_FMT_XRGB32``
+ - 'BX24'
+
+ -
+ -
+ -
+ -
+ -
+ -
+ -
+ -
+
+ - r\ :sub:`7`
+ - r\ :sub:`6`
+ - r\ :sub:`5`
+ - r\ :sub:`4`
+ - r\ :sub:`3`
+ - r\ :sub:`2`
+ - r\ :sub:`1`
+ - r\ :sub:`0`
+
+ - g\ :sub:`7`
+ - g\ :sub:`6`
+ - g\ :sub:`5`
+ - g\ :sub:`4`
+ - g\ :sub:`3`
+ - g\ :sub:`2`
+ - g\ :sub:`1`
+ - g\ :sub:`0`
+
+ - b\ :sub:`7`
+ - b\ :sub:`6`
+ - b\ :sub:`5`
+ - b\ :sub:`4`
+ - b\ :sub:`3`
+ - b\ :sub:`2`
+ - b\ :sub:`1`
+ - b\ :sub:`0`
+
+.. raw:: latex
+
+ \endgroup
+
+.. note:: Bit 7 is the most significant bit.
+
+The usage and value of the alpha bits (a) in the ARGB and ABGR formats
+(collectively referred to as alpha formats) depend on the device type
+and hardware operation. :ref:`Capture <capture>` devices (including
+capture queues of mem-to-mem devices) fill the alpha component in
+memory. When the device outputs an alpha channel the alpha component
+will have a meaningful value. Otherwise, when the device doesn't output
+an alpha channel but can set the alpha bit to a user-configurable value,
+the :ref:`V4L2_CID_ALPHA_COMPONENT <v4l2-alpha-component>` control
+is used to specify that alpha value, and the alpha component of all
+pixels will be set to the value specified by that control. Otherwise a
+corresponding format without an alpha component (XRGB or XBGR) must be
+used instead of an alpha format.
+
+:ref:`Output <output>` devices (including output queues of mem-to-mem
+devices and :ref:`video output overlay <osd>` devices) read the alpha
+component from memory. When the device processes the alpha channel the
+alpha component must be filled with meaningful values by applications.
+Otherwise a corresponding format without an alpha component (XRGB or
+XBGR) must be used instead of an alpha format.
+
+The XRGB and XBGR formats contain undefined bits (-). Applications,
+devices and drivers must ignore those bits, for both
+:ref:`capture` and :ref:`output` devices.
+
+**Byte Order.**
+Each cell is one byte.
+
+
+.. raw:: latex
+
+ \small
+
+.. tabularcolumns:: |p{3.1cm}|p{0.8cm}|p{0.8cm}|p{0.8cm}|p{0.8cm}|p{0.8cm}|p{0.8cm}|p{0.8cm}|p{0.8cm}|p{0.8cm}|p{0.8cm}|p{0.8cm}|p{0.8cm}|
+
+.. flat-table:: RGB byte order
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 11 3 3 3 3 3 3 3 3 3 3 3 3
+
+ * - start + 0:
+ - B\ :sub:`00`
+ - G\ :sub:`00`
+ - R\ :sub:`00`
+ - B\ :sub:`01`
+ - G\ :sub:`01`
+ - R\ :sub:`01`
+ - B\ :sub:`02`
+ - G\ :sub:`02`
+ - R\ :sub:`02`
+ - B\ :sub:`03`
+ - G\ :sub:`03`
+ - R\ :sub:`03`
+ * - start + 12:
+ - B\ :sub:`10`
+ - G\ :sub:`10`
+ - R\ :sub:`10`
+ - B\ :sub:`11`
+ - G\ :sub:`11`
+ - R\ :sub:`11`
+ - B\ :sub:`12`
+ - G\ :sub:`12`
+ - R\ :sub:`12`
+ - B\ :sub:`13`
+ - G\ :sub:`13`
+ - R\ :sub:`13`
+ * - start + 24:
+ - B\ :sub:`20`
+ - G\ :sub:`20`
+ - R\ :sub:`20`
+ - B\ :sub:`21`
+ - G\ :sub:`21`
+ - R\ :sub:`21`
+ - B\ :sub:`22`
+ - G\ :sub:`22`
+ - R\ :sub:`22`
+ - B\ :sub:`23`
+ - G\ :sub:`23`
+ - R\ :sub:`23`
+ * - start + 36:
+ - B\ :sub:`30`
+ - G\ :sub:`30`
+ - R\ :sub:`30`
+ - B\ :sub:`31`
+ - G\ :sub:`31`
+ - R\ :sub:`31`
+ - B\ :sub:`32`
+ - G\ :sub:`32`
+ - R\ :sub:`32`
+ - B\ :sub:`33`
+ - G\ :sub:`33`
+ - R\ :sub:`33`
+
+.. raw:: latex
+
+ \normalsize
+
+Formats defined in :ref:`pixfmt-rgb-deprecated` are deprecated and
+must not be used by new drivers. They are documented here for reference.
+The meaning of their alpha bits ``(a)`` are ill-defined and interpreted as in
+either the corresponding ARGB or XRGB format, depending on the driver.
+
+
+.. raw:: latex
+
+ \begingroup
+ \tiny
+ \setlength{\tabcolsep}{2pt}
+
+.. tabularcolumns:: |p{2.6cm}|p{0.70cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|
+
+.. _pixfmt-rgb-deprecated:
+
+.. flat-table:: Deprecated Packed RGB Image Formats
+ :header-rows: 2
+ :stub-columns: 0
+
+ * - Identifier
+ - Code
+ - :cspan:`7` Byte 0 in memory
+
+ - :cspan:`7` Byte 1
+
+ - :cspan:`7` Byte 2
+
+ - :cspan:`7` Byte 3
+ * -
+ -
+ - 7
+ - 6
+ - 5
+ - 4
+ - 3
+ - 2
+ - 1
+ - 0
+
+ - 7
+ - 6
+ - 5
+ - 4
+ - 3
+ - 2
+ - 1
+ - 0
+
+ - 7
+ - 6
+ - 5
+ - 4
+ - 3
+ - 2
+ - 1
+ - 0
+
+ - 7
+ - 6
+ - 5
+ - 4
+ - 3
+ - 2
+ - 1
+ - 0
+ * .. _V4L2-PIX-FMT-RGB444:
+
+ - ``V4L2_PIX_FMT_RGB444``
+ - 'R444'
+
+ - g\ :sub:`3`
+ - g\ :sub:`2`
+ - g\ :sub:`1`
+ - g\ :sub:`0`
+ - b\ :sub:`3`
+ - b\ :sub:`2`
+ - b\ :sub:`1`
+ - b\ :sub:`0`
+
+ - a\ :sub:`3`
+ - a\ :sub:`2`
+ - a\ :sub:`1`
+ - a\ :sub:`0`
+ - r\ :sub:`3`
+ - r\ :sub:`2`
+ - r\ :sub:`1`
+ - r\ :sub:`0`
+ -
+ * .. _V4L2-PIX-FMT-RGB555:
+
+ - ``V4L2_PIX_FMT_RGB555``
+ - 'RGBO'
+
+ - g\ :sub:`2`
+ - g\ :sub:`1`
+ - g\ :sub:`0`
+ - b\ :sub:`4`
+ - b\ :sub:`3`
+ - b\ :sub:`2`
+ - b\ :sub:`1`
+ - b\ :sub:`0`
+
+ - a
+ - r\ :sub:`4`
+ - r\ :sub:`3`
+ - r\ :sub:`2`
+ - r\ :sub:`1`
+ - r\ :sub:`0`
+ - g\ :sub:`4`
+ - g\ :sub:`3`
+ -
+ * .. _V4L2-PIX-FMT-RGB555X:
+
+ - ``V4L2_PIX_FMT_RGB555X``
+ - 'RGBQ'
+
+ - a
+ - r\ :sub:`4`
+ - r\ :sub:`3`
+ - r\ :sub:`2`
+ - r\ :sub:`1`
+ - r\ :sub:`0`
+ - g\ :sub:`4`
+ - g\ :sub:`3`
+
+ - g\ :sub:`2`
+ - g\ :sub:`1`
+ - g\ :sub:`0`
+ - b\ :sub:`4`
+ - b\ :sub:`3`
+ - b\ :sub:`2`
+ - b\ :sub:`1`
+ - b\ :sub:`0`
+ -
+ * .. _V4L2-PIX-FMT-BGR32:
+
+ - ``V4L2_PIX_FMT_BGR32``
+ - 'BGR4'
+
+ - b\ :sub:`7`
+ - b\ :sub:`6`
+ - b\ :sub:`5`
+ - b\ :sub:`4`
+ - b\ :sub:`3`
+ - b\ :sub:`2`
+ - b\ :sub:`1`
+ - b\ :sub:`0`
+
+ - g\ :sub:`7`
+ - g\ :sub:`6`
+ - g\ :sub:`5`
+ - g\ :sub:`4`
+ - g\ :sub:`3`
+ - g\ :sub:`2`
+ - g\ :sub:`1`
+ - g\ :sub:`0`
+
+ - r\ :sub:`7`
+ - r\ :sub:`6`
+ - r\ :sub:`5`
+ - r\ :sub:`4`
+ - r\ :sub:`3`
+ - r\ :sub:`2`
+ - r\ :sub:`1`
+ - r\ :sub:`0`
+
+ - a\ :sub:`7`
+ - a\ :sub:`6`
+ - a\ :sub:`5`
+ - a\ :sub:`4`
+ - a\ :sub:`3`
+ - a\ :sub:`2`
+ - a\ :sub:`1`
+ - a\ :sub:`0`
+ * .. _V4L2-PIX-FMT-RGB32:
+
+ - ``V4L2_PIX_FMT_RGB32``
+ - 'RGB4'
+
+ - a\ :sub:`7`
+ - a\ :sub:`6`
+ - a\ :sub:`5`
+ - a\ :sub:`4`
+ - a\ :sub:`3`
+ - a\ :sub:`2`
+ - a\ :sub:`1`
+ - a\ :sub:`0`
+
+ - r\ :sub:`7`
+ - r\ :sub:`6`
+ - r\ :sub:`5`
+ - r\ :sub:`4`
+ - r\ :sub:`3`
+ - r\ :sub:`2`
+ - r\ :sub:`1`
+ - r\ :sub:`0`
+
+ - g\ :sub:`7`
+ - g\ :sub:`6`
+ - g\ :sub:`5`
+ - g\ :sub:`4`
+ - g\ :sub:`3`
+ - g\ :sub:`2`
+ - g\ :sub:`1`
+ - g\ :sub:`0`
+
+ - b\ :sub:`7`
+ - b\ :sub:`6`
+ - b\ :sub:`5`
+ - b\ :sub:`4`
+ - b\ :sub:`3`
+ - b\ :sub:`2`
+ - b\ :sub:`1`
+ - b\ :sub:`0`
+
+.. raw:: latex
+
+ \endgroup
+
+A test utility to determine which RGB formats a driver actually supports
+is available from the LinuxTV v4l-dvb repository. See
+`https://linuxtv.org/repo/ <https://linuxtv.org/repo/>`__ for access
+instructions.
diff --git a/Documentation/media/uapi/v4l/pixfmt-v4l2.rst b/Documentation/media/uapi/v4l/pixfmt-v4l2.rst
index da6da2e..a8321c3 100644
--- a/Documentation/media/uapi/v4l/pixfmt-v4l2.rst
+++ b/Documentation/media/uapi/v4l/pixfmt-v4l2.rst
@@ -39,12 +39,17 @@
to a multiple of the scale factor of any smaller planes. For
example when the image format is YUV 4:2:0, ``width`` and
``height`` must be multiples of two.
+
+ For compressed formats that contain the resolution information encoded
+ inside the stream, when fed to a stateful mem2mem decoder, the fields
+ may be zero to rely on the decoder to detect the right values. For more
+ details see :ref:`decoder` and format descriptions.
* - __u32
- ``pixelformat``
- The pixel format or type of compression, set by the application.
This is a little endian
:ref:`four character code <v4l2-fourcc>`. V4L2 defines standard
- RGB formats in :ref:`rgb-formats`, YUV formats in
+ RGB formats in :ref:`pixfmt-rgb`, YUV formats in
:ref:`yuv-formats`, and reserved codes in
:ref:`reserved-formats`
* - __u32
diff --git a/Documentation/media/uapi/v4l/pixfmt.rst b/Documentation/media/uapi/v4l/pixfmt.rst
index 29be001..a7d4cd4 100644
--- a/Documentation/media/uapi/v4l/pixfmt.rst
+++ b/Documentation/media/uapi/v4l/pixfmt.rst
@@ -31,6 +31,7 @@
pixfmt-intro
pixfmt-indexed
pixfmt-rgb
+ pixfmt-bayer
yuv-formats
hsv-formats
depth-formats
diff --git a/Documentation/media/uapi/v4l/subdev-formats.rst b/Documentation/media/uapi/v4l/subdev-formats.rst
index ab1a48a..15e11f27b4 100644
--- a/Documentation/media/uapi/v4l/subdev-formats.rst
+++ b/Documentation/media/uapi/v4l/subdev-formats.rst
@@ -85,6 +85,14 @@
JPEG just by storing it to memory), there is no one-to-one
correspondence between them.
+The media bus pixel codes document parallel formats. Should the pixel data be
+transported over a serial bus, the media bus pixel code that describes a
+parallel format that transfers a sample on a single clock cycle is used. For
+instance, both MEDIA_BUS_FMT_BGR888_1X24 and MEDIA_BUS_FMT_BGR888_3X8 are used
+on parallel busses for transferring an 8 bits per sample BGR data, whereas on
+serial busses the data in this format is only referred to using
+MEDIA_BUS_FMT_BGR888_1X24. This is because there is effectively only a single
+way to transport that format on the serial busses.
Packed RGB Formats
^^^^^^^^^^^^^^^^^^
@@ -1305,6 +1313,113 @@
- g\ :sub:`6`
- g\ :sub:`5`
- g\ :sub:`4`
+ * .. _MEDIA-BUS-FMT-RGB888-3X8:
+
+ - MEDIA_BUS_FMT_RGB888_3X8
+ - 0x101c
+ -
+ -
+ -
+ -
+ -
+ -
+ -
+ -
+ -
+ -
+ -
+ -
+ -
+ -
+ -
+ -
+ -
+ -
+ -
+ -
+ -
+ -
+ -
+ -
+ -
+ - r\ :sub:`7`
+ - r\ :sub:`6`
+ - r\ :sub:`5`
+ - r\ :sub:`4`
+ - r\ :sub:`3`
+ - r\ :sub:`2`
+ - r\ :sub:`1`
+ - r\ :sub:`0`
+ * -
+ -
+ -
+ -
+ -
+ -
+ -
+ -
+ -
+ -
+ -
+ -
+ -
+ -
+ -
+ -
+ -
+ -
+ -
+ -
+ -
+ -
+ -
+ -
+ -
+ -
+ -
+ - g\ :sub:`7`
+ - g\ :sub:`6`
+ - g\ :sub:`5`
+ - g\ :sub:`4`
+ - g\ :sub:`3`
+ - g\ :sub:`2`
+ - g\ :sub:`1`
+ - g\ :sub:`0`
+ * -
+ -
+ -
+ -
+ -
+ -
+ -
+ -
+ -
+ -
+ -
+ -
+ -
+ -
+ -
+ -
+ -
+ -
+ -
+ -
+ -
+ -
+ -
+ -
+ -
+ -
+ -
+ - b\ :sub:`7`
+ - b\ :sub:`6`
+ - b\ :sub:`5`
+ - b\ :sub:`4`
+ - b\ :sub:`3`
+ - b\ :sub:`2`
+ - b\ :sub:`1`
+ - b\ :sub:`0`
* .. _MEDIA-BUS-FMT-ARGB888-1X32:
- MEDIA_BUS_FMT_ARGB888_1X32
diff --git a/Documentation/media/uapi/v4l/v4l2.rst b/Documentation/media/uapi/v4l/v4l2.rst
index 004ec00..97015b9b40 100644
--- a/Documentation/media/uapi/v4l/v4l2.rst
+++ b/Documentation/media/uapi/v4l/v4l2.rst
@@ -60,6 +60,10 @@
- Original author of the V4L2 API and documentation.
+- Figa, Tomasz <tfiga@chromium.org>
+
+ - Documented the memory-to-memory decoder interface.
+
- H Schimek, Michael <mschimek@gmx.at>
- Original author of the V4L2 API and documentation.
@@ -68,6 +72,10 @@
- Documented the Digital Video timings API.
+- Osciak, Pawel <posciak@chromium.org>
+
+ - Documented the memory-to-memory decoder interface.
+
- Osciak, Pawel <pawel@osciak.com>
- Designed and documented the multi-planar API.
@@ -92,7 +100,7 @@
- Designed and documented the VIDIOC_LOG_STATUS ioctl, the extended control ioctls, major parts of the sliced VBI API, the MPEG encoder and decoder APIs and the DV Timings API.
-**Copyright** |copy| 1999-2016: Bill Dirks, Michael H. Schimek, Hans Verkuil, Martin Rubli, Andy Walls, Muralidharan Karicheri, Mauro Carvalho Chehab, Pawel Osciak, Sakari Ailus & Antti Palosaari.
+**Copyright** |copy| 1999-2018: Bill Dirks, Michael H. Schimek, Hans Verkuil, Martin Rubli, Andy Walls, Muralidharan Karicheri, Mauro Carvalho Chehab, Pawel Osciak, Sakari Ailus & Antti Palosaari, Tomasz Figa
Except when explicitly stated as GPL, programming examples within this
part can be used and distributed without restrictions.
diff --git a/Documentation/media/uapi/v4l/vidioc-decoder-cmd.rst b/Documentation/media/uapi/v4l/vidioc-decoder-cmd.rst
index ccf83b0..57f0066 100644
--- a/Documentation/media/uapi/v4l/vidioc-decoder-cmd.rst
+++ b/Documentation/media/uapi/v4l/vidioc-decoder-cmd.rst
@@ -56,14 +56,16 @@
A :ref:`write() <func-write>` or :ref:`VIDIOC_STREAMON`
call sends an implicit START command to the decoder if it has not been
-started yet.
+started yet. Applies to both queues of mem2mem decoders.
A :ref:`close() <func-close>` or :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>`
call of a streaming file descriptor sends an implicit immediate STOP
-command to the decoder, and all buffered data is discarded.
+command to the decoder, and all buffered data is discarded. Applies to both
+queues of mem2mem decoders.
-These ioctls are optional, not all drivers may support them. They were
-introduced in Linux 3.3.
+In principle, these ioctls are optional, not all drivers may support them. They were
+introduced in Linux 3.3. They are, however, mandatory for stateful mem2mem decoders
+(as further documented in :ref:`decoder`).
.. tabularcolumns:: |p{1.1cm}|p{2.4cm}|p{1.2cm}|p{1.6cm}|p{10.6cm}|
@@ -167,26 +169,32 @@
``V4L2_DEC_CMD_RESUME`` for that. This command has one flag:
``V4L2_DEC_CMD_START_MUTE_AUDIO``. If set, then audio will be
muted when playing back at a non-standard speed.
+
+ For a device implementing the :ref:`decoder`, once the drain sequence
+ is initiated with the ``V4L2_DEC_CMD_STOP`` command, it must be driven
+ to completion before this command can be invoked. Any attempt to
+ invoke the command while the drain sequence is in progress will trigger
+ an ``EBUSY`` error code. The command may be also used to restart the
+ decoder in case of an implicit stop initiated by the decoder itself,
+ without the ``V4L2_DEC_CMD_STOP`` being called explicitly. See
+ :ref:`decoder` for more details.
* - ``V4L2_DEC_CMD_STOP``
- 1
- Stop the decoder. When the decoder is already stopped, this
command does nothing. This command has two flags: if
``V4L2_DEC_CMD_STOP_TO_BLACK`` is set, then the decoder will set
the picture to black after it stopped decoding. Otherwise the last
- image will repeat. mem2mem decoders will stop producing new frames
- altogether. They will send a ``V4L2_EVENT_EOS`` event when the
- last frame has been decoded and all frames are ready to be
- dequeued and will set the ``V4L2_BUF_FLAG_LAST`` buffer flag on
- the last buffer of the capture queue to indicate there will be no
- new buffers produced to dequeue. This buffer may be empty,
- indicated by the driver setting the ``bytesused`` field to 0. Once
- the ``V4L2_BUF_FLAG_LAST`` flag was set, the
- :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl will not block anymore,
- but return an ``EPIPE`` error code. If
+ image will repeat. If
``V4L2_DEC_CMD_STOP_IMMEDIATELY`` is set, then the decoder stops
immediately (ignoring the ``pts`` value), otherwise it will keep
decoding until timestamp >= pts or until the last of the pending
data from its internal buffers was decoded.
+
+ For a device implementing the :ref:`decoder`, the command will initiate
+ the drain sequence as documented in :ref:`decoder`. No flags or other
+ arguments are accepted in this case. Any attempt to invoke the command
+ again before the sequence completes will trigger an ``EBUSY`` error
+ code.
* - ``V4L2_DEC_CMD_PAUSE``
- 2
- Pause the decoder. When the decoder has not been started yet, the
@@ -209,6 +217,11 @@
appropriately. The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.
+EBUSY
+ A drain sequence of a device implementing the :ref:`decoder` is still in
+ progress. It is not allowed to issue another decoder command until it
+ completes.
+
EINVAL
The ``cmd`` field is invalid.
diff --git a/Documentation/media/uapi/v4l/vidioc-dqevent.rst b/Documentation/media/uapi/v4l/vidioc-dqevent.rst
index dea9c0c..42659a3 100644
--- a/Documentation/media/uapi/v4l/vidioc-dqevent.rst
+++ b/Documentation/media/uapi/v4l/vidioc-dqevent.rst
@@ -389,14 +389,19 @@
decoder. Applications will have to query the new resolution (if
any, the signal may also have been lost).
+ For stateful decoders follow the guidelines in :ref:`decoder`.
+ Video Capture devices have to query the new timings using
+ :ref:`VIDIOC_QUERY_DV_TIMINGS` or
+ :ref:`VIDIOC_QUERYSTD <VIDIOC_QUERYSTD>`.
+
*Important*: even if the new video timings appear identical to the old
ones, receiving this event indicates that there was an issue with the
video signal and you must stop and restart streaming
(:ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>`
followed by :ref:`VIDIOC_STREAMON <VIDIOC_STREAMON>`). The reason is
- that many devices are not able to recover from a temporary loss of
- signal and so restarting streaming I/O is required in order for the
- hardware to synchronize to the video signal.
+ that many Video Capture devices are not able to recover from a temporary
+ loss of signal and so restarting streaming I/O is required in order for
+ the hardware to synchronize to the video signal.
Return Value
diff --git a/Documentation/media/uapi/v4l/vidioc-enum-fmt.rst b/Documentation/media/uapi/v4l/vidioc-enum-fmt.rst
index 822d673..399ef10 100644
--- a/Documentation/media/uapi/v4l/vidioc-enum-fmt.rst
+++ b/Documentation/media/uapi/v4l/vidioc-enum-fmt.rst
@@ -127,6 +127,22 @@
- This format is not native to the device but emulated through
software (usually libv4l2), where possible try to use a native
format instead for better performance.
+ * - ``V4L2_FMT_FLAG_CONTINUOUS_BYTESTREAM``
+ - 0x0004
+ - The hardware decoder for this compressed bytestream format (aka coded
+ format) is capable of parsing a continuous bytestream. Applications do
+ not need to parse the bytestream themselves to find the boundaries
+ between frames/fields. This flag can only be used in combination with
+ the ``V4L2_FMT_FLAG_COMPRESSED`` flag, since this applies to compressed
+ formats only. This flag is valid for stateful decoders only.
+ * - ``V4L2_FMT_FLAG_DYN_RESOLUTION``
+ - 0x0008
+ - Dynamic resolution switching is supported by the device for this
+ compressed bytestream format (aka coded format). It will notify the user
+ via the event ``V4L2_EVENT_SOURCE_CHANGE`` when changes in the video
+ parameters are detected. This flag can only be used in combination
+ with the ``V4L2_FMT_FLAG_COMPRESSED`` flag, since this applies to
+ compressed formats only. It is also only applies to stateful codecs.
Return Value
diff --git a/Documentation/media/uapi/v4l/vidioc-queryctrl.rst b/Documentation/media/uapi/v4l/vidioc-queryctrl.rst
index dc50063..a3d56ff 100644
--- a/Documentation/media/uapi/v4l/vidioc-queryctrl.rst
+++ b/Documentation/media/uapi/v4l/vidioc-queryctrl.rst
@@ -39,8 +39,8 @@
File descriptor returned by :ref:`open() <func-open>`.
``argp``
- Pointer to struct :c:type:`v4l2_queryctl`, :c:type:`v4l2_query_ext_ctrl`
- or :c:type`v4l2_querymenu` (depending on the ioctl).
+ Pointer to struct :c:type:`v4l2_queryctrl`, :c:type:`v4l2_query_ext_ctrl`
+ or :c:type:`v4l2_querymenu` (depending on the ioctl).
Description
diff --git a/Documentation/media/v4l-drivers/imx7.rst b/Documentation/media/v4l-drivers/imx7.rst
index fe411f6..1e442c9 100644
--- a/Documentation/media/v4l-drivers/imx7.rst
+++ b/Documentation/media/v4l-drivers/imx7.rst
@@ -41,7 +41,7 @@
virtual channel 0. This module is compliant to previous version of Samsung
D-phy, and supports two D-PHY Rx Data lanes.
-csi_mux
+csi-mux
-------
This is the video multiplexer. It has two sink pads to select from either camera
@@ -56,7 +56,7 @@
to store received image pixel data and embedded DMA controllers to transfer data
from the FIFO through AHB bus.
-This entity has one sink pad that receives from the csi_mux entity and a single
+This entity has one sink pad that receives from the csi-mux entity and a single
source pad that routes video frames directly to memory buffers. This pad is
routed to a capture device node.
@@ -81,14 +81,14 @@
# Setup links
media-ctl -l "'ov2680 1-0036':0 -> 'imx7-mipi-csis.0':0[1]"
- media-ctl -l "'imx7-mipi-csis.0':1 -> 'csi_mux':1[1]"
- media-ctl -l "'csi_mux':2 -> 'csi':0[1]"
+ media-ctl -l "'imx7-mipi-csis.0':1 -> 'csi-mux':1[1]"
+ media-ctl -l "'csi-mux':2 -> 'csi':0[1]"
media-ctl -l "'csi':1 -> 'csi capture':0[1]"
# Configure pads for pipeline
media-ctl -V "'ov2680 1-0036':0 [fmt:SBGGR10_1X10/800x600 field:none]"
- media-ctl -V "'csi_mux':1 [fmt:SBGGR10_1X10/800x600 field:none]"
- media-ctl -V "'csi_mux':2 [fmt:SBGGR10_1X10/800x600 field:none]"
+ media-ctl -V "'csi-mux':1 [fmt:SBGGR10_1X10/800x600 field:none]"
+ media-ctl -V "'csi-mux':2 [fmt:SBGGR10_1X10/800x600 field:none]"
media-ctl -V "'imx7-mipi-csis.0':0 [fmt:SBGGR10_1X10/800x600 field:none]"
media-ctl -V "'csi':0 [fmt:SBGGR10_1X10/800x600 field:none]"
@@ -97,64 +97,63 @@
.. code-block:: none
- root@imx7s-warp:~# media-ctl -p
- Media controller API version 4.17.0
+ # media-ctl -p
+ Media controller API version 5.2.0
- Media device information
- ------------------------
- driver imx-media
- model imx-media
- serial
- bus info
- hw revision 0x0
- driver version 4.17.0
+ Media device information
+ ------------------------
+ driver imx7-csi
+ model imx-media
+ serial
+ bus info
+ hw revision 0x0
+ driver version 5.2.0
- Device topology
- - entity 1: csi (2 pads, 2 links)
- type V4L2 subdev subtype Unknown flags 0
- device node name /dev/v4l-subdev0
- pad0: Sink
- [fmt:SBGGR10_1X10/800x600 field:none]
- <- "csi_mux":2 [ENABLED]
- pad1: Source
- [fmt:SBGGR10_1X10/800x600 field:none]
- -> "csi capture":0 [ENABLED]
+ Device topology
+ - entity 1: csi (2 pads, 2 links)
+ type V4L2 subdev subtype Unknown flags 0
+ device node name /dev/v4l-subdev0
+ pad0: Sink
+ [fmt:SBGGR10_1X10/800x600 field:none colorspace:srgb xfer:srgb ycbcr:601 quantization:full-range]
+ <- "csi-mux":2 [ENABLED]
+ pad1: Source
+ [fmt:SBGGR10_1X10/800x600 field:none colorspace:srgb xfer:srgb ycbcr:601 quantization:full-range]
+ -> "csi capture":0 [ENABLED]
- - entity 4: csi capture (1 pad, 1 link)
- type Node subtype V4L flags 0
- device node name /dev/video0
- pad0: Sink
- <- "csi":1 [ENABLED]
+ - entity 4: csi capture (1 pad, 1 link)
+ type Node subtype V4L flags 0
+ device node name /dev/video0
+ pad0: Sink
+ <- "csi":1 [ENABLED]
- - entity 10: csi_mux (3 pads, 2 links)
- type V4L2 subdev subtype Unknown flags 0
- device node name /dev/v4l-subdev1
- pad0: Sink
- [fmt:unknown/0x0]
- pad1: Sink
- [fmt:unknown/800x600 field:none]
- <- "imx7-mipi-csis.0":1 [ENABLED]
- pad2: Source
- [fmt:unknown/800x600 field:none]
- -> "csi":0 [ENABLED]
+ - entity 10: csi-mux (3 pads, 2 links)
+ type V4L2 subdev subtype Unknown flags 0
+ device node name /dev/v4l-subdev1
+ pad0: Sink
+ [fmt:Y8_1X8/1x1 field:none]
+ pad1: Sink
+ [fmt:SBGGR10_1X10/800x600 field:none]
+ <- "imx7-mipi-csis.0":1 [ENABLED]
+ pad2: Source
+ [fmt:SBGGR10_1X10/800x600 field:none]
+ -> "csi":0 [ENABLED]
- - entity 14: imx7-mipi-csis.0 (2 pads, 2 links)
- type V4L2 subdev subtype Unknown flags 0
- device node name /dev/v4l-subdev2
- pad0: Sink
- [fmt:SBGGR10_1X10/800x600 field:none]
- <- "ov2680 1-0036":0 [ENABLED]
- pad1: Source
- [fmt:SBGGR10_1X10/800x600 field:none]
- -> "csi_mux":1 [ENABLED]
+ - entity 14: imx7-mipi-csis.0 (2 pads, 2 links)
+ type V4L2 subdev subtype Unknown flags 0
+ device node name /dev/v4l-subdev2
+ pad0: Sink
+ [fmt:SBGGR10_1X10/800x600 field:none]
+ <- "ov2680 1-0036":0 [ENABLED]
+ pad1: Source
+ [fmt:SBGGR10_1X10/800x600 field:none]
+ -> "csi-mux":1 [ENABLED]
- - entity 17: ov2680 1-0036 (1 pad, 1 link)
- type V4L2 subdev subtype Sensor flags 0
- device node name /dev/v4l-subdev3
- pad0: Source
- [fmt:SBGGR10_1X10/800x600 field:none]
- -> "imx7-mipi-csis.0":0 [ENABLED]
-
+ - entity 17: ov2680 1-0036 (1 pad, 1 link)
+ type V4L2 subdev subtype Sensor flags 0
+ device node name /dev/v4l-subdev3
+ pad0: Source
+ [fmt:SBGGR10_1X10/800x600@1/30 field:none colorspace:srgb]
+ -> "imx7-mipi-csis.0":0 [ENABLED]
References
----------
diff --git a/Documentation/media/v4l-drivers/vimc.rst b/Documentation/media/v4l-drivers/vimc.rst
index 4628b12..4064176 100644
--- a/Documentation/media/v4l-drivers/vimc.rst
+++ b/Documentation/media/v4l-drivers/vimc.rst
@@ -15,7 +15,7 @@
.. _vimc_topology_graph:
.. kernel-figure:: vimc.dot
- :alt: vimc.dot
+ :alt: Diagram of the default media pipeline topology
:align: center
Media pipeline graph on vimc
@@ -96,3 +96,14 @@
Window size to calculate the mean. Note: the window size needs to be an
odd number, as the main pixel stays in the center of the window,
otherwise the next odd number is considered (the default value is 3).
+
+Source code documentation
+-------------------------
+
+vimc-streamer
+~~~~~~~~~~~~~
+
+.. kernel-doc:: drivers/media/platform/vimc/vimc-streamer.h
+ :internal:
+
+.. kernel-doc:: drivers/media/platform/vimc/vimc-streamer.c
diff --git a/Documentation/media/videodev2.h.rst.exceptions b/Documentation/media/videodev2.h.rst.exceptions
index 55cbe32..adeb6b7 100644
--- a/Documentation/media/videodev2.h.rst.exceptions
+++ b/Documentation/media/videodev2.h.rst.exceptions
@@ -180,15 +180,17 @@
# V4L2 format flags
replace define V4L2_FMT_FLAG_COMPRESSED fmtdesc-flags
replace define V4L2_FMT_FLAG_EMULATED fmtdesc-flags
+replace define V4L2_FMT_FLAG_CONTINUOUS_BYTESTREAM fmtdesc-flags
+replace define V4L2_FMT_FLAG_DYN_RESOLUTION fmtdesc-flags
-# V4L2 tymecode types
+# V4L2 timecode types
replace define V4L2_TC_TYPE_24FPS timecode-type
replace define V4L2_TC_TYPE_25FPS timecode-type
replace define V4L2_TC_TYPE_30FPS timecode-type
replace define V4L2_TC_TYPE_50FPS timecode-type
replace define V4L2_TC_TYPE_60FPS timecode-type
-# V4L2 tymecode flags
+# V4L2 timecode flags
replace define V4L2_TC_FLAG_DROPFRAME timecode-flags
replace define V4L2_TC_FLAG_COLORFRAME timecode-flags
replace define V4L2_TC_USERBITS_field timecode-flags
diff --git a/Documentation/mips/AU1xxx_IDE.README b/Documentation/mips/AU1xxx_IDE.README
deleted file mode 100644
index ff675a1..0000000
--- a/Documentation/mips/AU1xxx_IDE.README
+++ /dev/null
@@ -1,115 +0,0 @@
-README for MIPS AU1XXX IDE driver - Released 2005-07-15
-
-ABOUT
------
-This file describes the 'drivers/ide/au1xxx-ide.c', related files and the
-services they provide.
-
-If you are short in patience and just want to know how to add your hard disc to
-the white or black list, go to the 'ADD NEW HARD DISC TO WHITE OR BLACK LIST'
-section.
-
-
-LICENSE
--------
-
-Copyright (c) 2003-2005 AMD, Personal Connectivity Solutions
-
-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; either version 2 of the License, or (at your option) any later
-version.
-
-THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES,
-INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
-FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR
-BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
-CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
-SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
-INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
-CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
-ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
-POSSIBILITY OF SUCH DAMAGE.
-
-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.
-
-Note: for more information, please refer "AMD Alchemy Au1200/Au1550 IDE
- Interface and Linux Device Driver" Application Note.
-
-
-FILES, CONFIGS AND COMPATIBILITY
---------------------------------
-
-Two files are introduced:
-
- a) 'arch/mips/include/asm/mach-au1x00/au1xxx_ide.h'
- contains : struct _auide_hwif
- timing parameters for PIO mode 0/1/2/3/4
- timing parameters for MWDMA 0/1/2
-
- b) 'drivers/ide/mips/au1xxx-ide.c'
- contains the functionality of the AU1XXX IDE driver
-
-Following extra configs variables are introduced:
-
- CONFIG_BLK_DEV_IDE_AU1XXX_PIO_DBDMA - enable the PIO+DBDMA mode
- CONFIG_BLK_DEV_IDE_AU1XXX_MDMA2_DBDMA - enable the MWDMA mode
-
-
-SUPPORTED IDE MODES
--------------------
-
-The AU1XXX IDE driver supported all PIO modes - PIO mode 0/1/2/3/4 - and all
-MWDMA modes - MWDMA 0/1/2 -. There is no support for SWDMA and UDMA mode.
-
-To change the PIO mode use the program hdparm with option -p, e.g.
-'hdparm -p0 [device]' for PIO mode 0. To enable the MWDMA mode use the option
--X, e.g. 'hdparm -X32 [device]' for MWDMA mode 0.
-
-
-PERFORMANCE CONFIGURATIONS
---------------------------
-
-If the used system doesn't need USB support enable the following kernel configs:
-
-CONFIG_IDE=y
-CONFIG_BLK_DEV_IDE=y
-CONFIG_IDE_GENERIC=y
-CONFIG_BLK_DEV_IDEPCI=y
-CONFIG_BLK_DEV_GENERIC=y
-CONFIG_BLK_DEV_IDEDMA_PCI=y
-CONFIG_BLK_DEV_IDE_AU1XXX=y
-CONFIG_BLK_DEV_IDE_AU1XXX_MDMA2_DBDMA=y
-CONFIG_BLK_DEV_IDEDMA=y
-
-Also define 'IDE_AU1XXX_BURSTMODE' in 'drivers/ide/mips/au1xxx-ide.c' to enable
-the burst support on DBDMA controller.
-
-If the used system need the USB support enable the following kernel configs for
-high IDE to USB throughput.
-
-CONFIG_IDE_GENERIC=y
-CONFIG_BLK_DEV_IDEPCI=y
-CONFIG_BLK_DEV_GENERIC=y
-CONFIG_BLK_DEV_IDEDMA_PCI=y
-CONFIG_BLK_DEV_IDE_AU1XXX=y
-CONFIG_BLK_DEV_IDE_AU1XXX_MDMA2_DBDMA=y
-CONFIG_BLK_DEV_IDEDMA=y
-
-Also undefine 'IDE_AU1XXX_BURSTMODE' in 'drivers/ide/mips/au1xxx-ide.c' to
-disable the burst support on DBDMA controller.
-
-
-ACKNOWLEDGMENTS
----------------
-
-These drivers wouldn't have been done without the base of kernel 2.4.x AU1XXX
-IDE driver from AMD.
-
-Additional input also from:
-Matthias Lenk <matthias.lenk@amd.com>
-
-Happy hacking!
-Enrico Walther <enrico.walther@amd.com>
diff --git a/Documentation/mips/au1xxx_ide.rst b/Documentation/mips/au1xxx_ide.rst
new file mode 100644
index 0000000..2f9c2cf
--- /dev/null
+++ b/Documentation/mips/au1xxx_ide.rst
@@ -0,0 +1,130 @@
+.. include:: <isonum.txt>
+
+======================
+MIPS AU1XXX IDE driver
+======================
+
+Released 2005-07-15
+
+About
+=====
+
+This file describes the 'drivers/ide/au1xxx-ide.c', related files and the
+services they provide.
+
+If you are short in patience and just want to know how to add your hard disc to
+the white or black list, go to the 'ADD NEW HARD DISC TO WHITE OR BLACK LIST'
+section.
+
+
+License
+=======
+
+:Copyright: |copy| 2003-2005 AMD, Personal Connectivity Solutions
+
+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; either version 2 of the License, or (at your option) any later
+version.
+
+THIS SOFTWARE IS PROVIDED ``AS IS`` AND ANY EXPRESS OR IMPLIED WARRANTIES,
+INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
+FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR
+BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+POSSIBILITY OF SUCH DAMAGE.
+
+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.
+
+Note:
+ for more information, please refer "AMD Alchemy Au1200/Au1550 IDE
+ Interface and Linux Device Driver" Application Note.
+
+
+Files, Configs and Compatibility
+================================
+
+Two files are introduced:
+
+ a) 'arch/mips/include/asm/mach-au1x00/au1xxx_ide.h'
+ contains : struct _auide_hwif
+
+ - timing parameters for PIO mode 0/1/2/3/4
+ - timing parameters for MWDMA 0/1/2
+
+ b) 'drivers/ide/mips/au1xxx-ide.c'
+ contains the functionality of the AU1XXX IDE driver
+
+Following extra configs variables are introduced:
+
+ CONFIG_BLK_DEV_IDE_AU1XXX_PIO_DBDMA
+ - enable the PIO+DBDMA mode
+ CONFIG_BLK_DEV_IDE_AU1XXX_MDMA2_DBDMA
+ - enable the MWDMA mode
+
+
+Supported IDE Modes
+===================
+
+The AU1XXX IDE driver supported all PIO modes - PIO mode 0/1/2/3/4 - and all
+MWDMA modes - MWDMA 0/1/2 -. There is no support for SWDMA and UDMA mode.
+
+To change the PIO mode use the program hdparm with option -p, e.g.
+'hdparm -p0 [device]' for PIO mode 0. To enable the MWDMA mode use the option
+-X, e.g. 'hdparm -X32 [device]' for MWDMA mode 0.
+
+
+Performance Configurations
+==========================
+
+If the used system doesn't need USB support enable the following kernel
+configs::
+
+ CONFIG_IDE=y
+ CONFIG_BLK_DEV_IDE=y
+ CONFIG_IDE_GENERIC=y
+ CONFIG_BLK_DEV_IDEPCI=y
+ CONFIG_BLK_DEV_GENERIC=y
+ CONFIG_BLK_DEV_IDEDMA_PCI=y
+ CONFIG_BLK_DEV_IDE_AU1XXX=y
+ CONFIG_BLK_DEV_IDE_AU1XXX_MDMA2_DBDMA=y
+ CONFIG_BLK_DEV_IDEDMA=y
+
+Also define 'IDE_AU1XXX_BURSTMODE' in 'drivers/ide/mips/au1xxx-ide.c' to enable
+the burst support on DBDMA controller.
+
+If the used system need the USB support enable the following kernel configs for
+high IDE to USB throughput.
+
+::
+
+ CONFIG_IDE_GENERIC=y
+ CONFIG_BLK_DEV_IDEPCI=y
+ CONFIG_BLK_DEV_GENERIC=y
+ CONFIG_BLK_DEV_IDEDMA_PCI=y
+ CONFIG_BLK_DEV_IDE_AU1XXX=y
+ CONFIG_BLK_DEV_IDE_AU1XXX_MDMA2_DBDMA=y
+ CONFIG_BLK_DEV_IDEDMA=y
+
+Also undefine 'IDE_AU1XXX_BURSTMODE' in 'drivers/ide/mips/au1xxx-ide.c' to
+disable the burst support on DBDMA controller.
+
+
+Acknowledgments
+===============
+
+These drivers wouldn't have been done without the base of kernel 2.4.x AU1XXX
+IDE driver from AMD.
+
+Additional input also from:
+Matthias Lenk <matthias.lenk@amd.com>
+
+Happy hacking!
+
+Enrico Walther <enrico.walther@amd.com>
diff --git a/Documentation/mips/index.rst b/Documentation/mips/index.rst
new file mode 100644
index 0000000..a93c2f6
--- /dev/null
+++ b/Documentation/mips/index.rst
@@ -0,0 +1,20 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+===========================
+MIPS-specific Documentation
+===========================
+
+.. toctree::
+ :maxdepth: 2
+ :numbered:
+
+ ingenic-tcu
+
+ au1xxx_ide
+
+.. only:: subproject and html
+
+ Indices
+ =======
+
+ * :ref:`genindex`
diff --git a/Documentation/mips/ingenic-tcu.rst b/Documentation/mips/ingenic-tcu.rst
new file mode 100644
index 0000000..c4ef4c4
--- /dev/null
+++ b/Documentation/mips/ingenic-tcu.rst
@@ -0,0 +1,71 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+===============================================
+Ingenic JZ47xx SoCs Timer/Counter Unit hardware
+===============================================
+
+The Timer/Counter Unit (TCU) in Ingenic JZ47xx SoCs is a multi-function
+hardware block. It features up to to eight channels, that can be used as
+counters, timers, or PWM.
+
+- JZ4725B, JZ4750, JZ4755 only have six TCU channels. The other SoCs all
+ have eight channels.
+
+- JZ4725B introduced a separate channel, called Operating System Timer
+ (OST). It is a 32-bit programmable timer. On JZ4760B and above, it is
+ 64-bit.
+
+- Each one of the TCU channels has its own clock, which can be reparented to three
+ different clocks (pclk, ext, rtc), gated, and reclocked, through their TCSR register.
+
+ - The watchdog and OST hardware blocks also feature a TCSR register with the same
+ format in their register space.
+ - The TCU registers used to gate/ungate can also gate/ungate the watchdog and
+ OST clocks.
+
+- Each TCU channel works in one of two modes:
+
+ - mode TCU1: channels cannot work in sleep mode, but are easier to
+ operate.
+ - mode TCU2: channels can work in sleep mode, but the operation is a bit
+ more complicated than with TCU1 channels.
+
+- The mode of each TCU channel depends on the SoC used:
+
+ - On the oldest SoCs (up to JZ4740), all of the eight channels operate in
+ TCU1 mode.
+ - On JZ4725B, channel 5 operates as TCU2, the others operate as TCU1.
+ - On newest SoCs (JZ4750 and above), channels 1-2 operate as TCU2, the
+ others operate as TCU1.
+
+- Each channel can generate an interrupt. Some channels share an interrupt
+ line, some don't, and this changes between SoC versions:
+
+ - on older SoCs (JZ4740 and below), channel 0 and channel 1 have their
+ own interrupt line; channels 2-7 share the last interrupt line.
+ - On JZ4725B, channel 0 has its own interrupt; channels 1-5 share one
+ interrupt line; the OST uses the last interrupt line.
+ - on newer SoCs (JZ4750 and above), channel 5 has its own interrupt;
+ channels 0-4 and (if eight channels) 6-7 all share one interrupt line;
+ the OST uses the last interrupt line.
+
+Implementation
+==============
+
+The functionalities of the TCU hardware are spread across multiple drivers:
+
+=========== =====
+clocks drivers/clk/ingenic/tcu.c
+interrupts drivers/irqchip/irq-ingenic-tcu.c
+timers drivers/clocksource/ingenic-timer.c
+OST drivers/clocksource/ingenic-ost.c
+PWM drivers/pwm/pwm-jz4740.c
+watchdog drivers/watchdog/jz4740_wdt.c
+=========== =====
+
+Because various functionalities of the TCU that belong to different drivers
+and frameworks can be controlled from the same registers, all of these
+drivers access their registers through the same regmap.
+
+For more information regarding the devicetree bindings of the TCU drivers,
+have a look at Documentation/devicetree/bindings/mfd/ingenic,tcu.txt.
diff --git a/Documentation/misc-devices/index.rst b/Documentation/misc-devices/index.rst
index a57f92d..f11c5da 100644
--- a/Documentation/misc-devices/index.rst
+++ b/Documentation/misc-devices/index.rst
@@ -20,3 +20,4 @@
isl29003
lis3lv02d
max6875
+ xilinx_sdfec
diff --git a/Documentation/networking/af_xdp.rst b/Documentation/networking/af_xdp.rst
index eeedc2e..83f7ae5 100644
--- a/Documentation/networking/af_xdp.rst
+++ b/Documentation/networking/af_xdp.rst
@@ -153,10 +153,12 @@
Frames passed to the kernel are used for the ingress path (RX rings).
-The user application produces UMEM addrs to this ring. Note that the
-kernel will mask the incoming addr. E.g. for a chunk size of 2k, the
-log2(2048) LSB of the addr will be masked off, meaning that 2048, 2050
-and 3000 refers to the same chunk.
+The user application produces UMEM addrs to this ring. Note that, if
+running the application with aligned chunk mode, the kernel will mask
+the incoming addr. E.g. for a chunk size of 2k, the log2(2048) LSB of
+the addr will be masked off, meaning that 2048, 2050 and 3000 refers
+to the same chunk. If the user application is run in the unaligned
+chunks mode, then the incoming addr will be left untouched.
UMEM Completion Ring
diff --git a/Documentation/networking/caif/README b/Documentation/networking/caif/README
deleted file mode 100644
index 757ccfa..0000000
--- a/Documentation/networking/caif/README
+++ /dev/null
@@ -1,109 +0,0 @@
-Copyright (C) ST-Ericsson AB 2010
-Author: Sjur Brendeland/ sjur.brandeland@stericsson.com
-License terms: GNU General Public License (GPL) version 2
----------------------------------------------------------
-
-=== Start ===
-If you have compiled CAIF for modules do:
-
-$modprobe crc_ccitt
-$modprobe caif
-$modprobe caif_socket
-$modprobe chnl_net
-
-
-=== Preparing the setup with a STE modem ===
-
-If you are working on integration of CAIF you should make sure
-that the kernel is built with module support.
-
-There are some things that need to be tweaked to get the host TTY correctly
-set up to talk to the modem.
-Since the CAIF stack is running in the kernel and we want to use the existing
-TTY, we are installing our physical serial driver as a line discipline above
-the TTY device.
-
-To achieve this we need to install the N_CAIF ldisc from user space.
-The benefit is that we can hook up to any TTY.
-
-The use of Start-of-frame-extension (STX) must also be set as
-module parameter "ser_use_stx".
-
-Normally Frame Checksum is always used on UART, but this is also provided as a
-module parameter "ser_use_fcs".
-
-$ modprobe caif_serial ser_ttyname=/dev/ttyS0 ser_use_stx=yes
-$ ifconfig caif_ttyS0 up
-
-PLEASE NOTE: There is a limitation in Android shell.
- It only accepts one argument to insmod/modprobe!
-
-=== Trouble shooting ===
-
-There are debugfs parameters provided for serial communication.
-/sys/kernel/debug/caif_serial/<tty-name>/
-
-* ser_state: Prints the bit-mask status where
- - 0x02 means SENDING, this is a transient state.
- - 0x10 means FLOW_OFF_SENT, i.e. the previous frame has not been sent
- and is blocking further send operation. Flow OFF has been propagated
- to all CAIF Channels using this TTY.
-
-* tty_status: Prints the bit-mask tty status information
- - 0x01 - tty->warned is on.
- - 0x02 - tty->low_latency is on.
- - 0x04 - tty->packed is on.
- - 0x08 - tty->flow_stopped is on.
- - 0x10 - tty->hw_stopped is on.
- - 0x20 - tty->stopped is on.
-
-* last_tx_msg: Binary blob Prints the last transmitted frame.
- This can be printed with
- $od --format=x1 /sys/kernel/debug/caif_serial/<tty>/last_rx_msg.
- The first two tx messages sent look like this. Note: The initial
- byte 02 is start of frame extension (STX) used for re-syncing
- upon errors.
-
- - Enumeration:
- 0000000 02 05 00 00 03 01 d2 02
- | | | | | |
- STX(1) | | | |
- Length(2)| | |
- Control Channel(1)
- Command:Enumeration(1)
- Link-ID(1)
- Checksum(2)
- - Channel Setup:
- 0000000 02 07 00 00 00 21 a1 00 48 df
- | | | | | | | |
- STX(1) | | | | | |
- Length(2)| | | | |
- Control Channel(1)
- Command:Channel Setup(1)
- Channel Type(1)
- Priority and Link-ID(1)
- Endpoint(1)
- Checksum(2)
-
-* last_rx_msg: Prints the last transmitted frame.
- The RX messages for LinkSetup look almost identical but they have the
- bit 0x20 set in the command bit, and Channel Setup has added one byte
- before Checksum containing Channel ID.
- NOTE: Several CAIF Messages might be concatenated. The maximum debug
- buffer size is 128 bytes.
-
-== Error Scenarios:
-- last_tx_msg contains channel setup message and last_rx_msg is empty ->
- The host seems to be able to send over the UART, at least the CAIF ldisc get
- notified that sending is completed.
-
-- last_tx_msg contains enumeration message and last_rx_msg is empty ->
- The host is not able to send the message from UART, the tty has not been
- able to complete the transmit operation.
-
-- if /sys/kernel/debug/caif_serial/<tty>/tty_status is non-zero there
- might be problems transmitting over UART.
- E.g. host and modem wiring is not correct you will typically see
- tty_status = 0x10 (hw_stopped) and ser_state = 0x10 (FLOW_OFF_SENT).
- You will probably see the enumeration message in last_tx_message
- and empty last_rx_message.
diff --git a/Documentation/networking/caif/caif.rst b/Documentation/networking/caif/caif.rst
new file mode 100644
index 0000000..07afc80
--- /dev/null
+++ b/Documentation/networking/caif/caif.rst
@@ -0,0 +1,141 @@
+:orphan:
+
+.. SPDX-License-Identifier: GPL-2.0
+.. include:: <isonum.txt>
+
+
+================
+Using Linux CAIF
+================
+
+
+:Copyright: |copy| ST-Ericsson AB 2010
+
+:Author: Sjur Brendeland/ sjur.brandeland@stericsson.com
+
+Start
+=====
+
+If you have compiled CAIF for modules do::
+
+ $modprobe crc_ccitt
+ $modprobe caif
+ $modprobe caif_socket
+ $modprobe chnl_net
+
+
+Preparing the setup with a STE modem
+====================================
+
+If you are working on integration of CAIF you should make sure
+that the kernel is built with module support.
+
+There are some things that need to be tweaked to get the host TTY correctly
+set up to talk to the modem.
+Since the CAIF stack is running in the kernel and we want to use the existing
+TTY, we are installing our physical serial driver as a line discipline above
+the TTY device.
+
+To achieve this we need to install the N_CAIF ldisc from user space.
+The benefit is that we can hook up to any TTY.
+
+The use of Start-of-frame-extension (STX) must also be set as
+module parameter "ser_use_stx".
+
+Normally Frame Checksum is always used on UART, but this is also provided as a
+module parameter "ser_use_fcs".
+
+::
+
+ $ modprobe caif_serial ser_ttyname=/dev/ttyS0 ser_use_stx=yes
+ $ ifconfig caif_ttyS0 up
+
+PLEASE NOTE:
+ There is a limitation in Android shell.
+ It only accepts one argument to insmod/modprobe!
+
+Trouble shooting
+================
+
+There are debugfs parameters provided for serial communication.
+/sys/kernel/debug/caif_serial/<tty-name>/
+
+* ser_state: Prints the bit-mask status where
+
+ - 0x02 means SENDING, this is a transient state.
+ - 0x10 means FLOW_OFF_SENT, i.e. the previous frame has not been sent
+ and is blocking further send operation. Flow OFF has been propagated
+ to all CAIF Channels using this TTY.
+
+* tty_status: Prints the bit-mask tty status information
+
+ - 0x01 - tty->warned is on.
+ - 0x02 - tty->low_latency is on.
+ - 0x04 - tty->packed is on.
+ - 0x08 - tty->flow_stopped is on.
+ - 0x10 - tty->hw_stopped is on.
+ - 0x20 - tty->stopped is on.
+
+* last_tx_msg: Binary blob Prints the last transmitted frame.
+
+ This can be printed with::
+
+ $od --format=x1 /sys/kernel/debug/caif_serial/<tty>/last_rx_msg.
+
+ The first two tx messages sent look like this. Note: The initial
+ byte 02 is start of frame extension (STX) used for re-syncing
+ upon errors.
+
+ - Enumeration::
+
+ 0000000 02 05 00 00 03 01 d2 02
+ | | | | | |
+ STX(1) | | | |
+ Length(2)| | |
+ Control Channel(1)
+ Command:Enumeration(1)
+ Link-ID(1)
+ Checksum(2)
+
+ - Channel Setup::
+
+ 0000000 02 07 00 00 00 21 a1 00 48 df
+ | | | | | | | |
+ STX(1) | | | | | |
+ Length(2)| | | | |
+ Control Channel(1)
+ Command:Channel Setup(1)
+ Channel Type(1)
+ Priority and Link-ID(1)
+ Endpoint(1)
+ Checksum(2)
+
+* last_rx_msg: Prints the last transmitted frame.
+
+ The RX messages for LinkSetup look almost identical but they have the
+ bit 0x20 set in the command bit, and Channel Setup has added one byte
+ before Checksum containing Channel ID.
+
+ NOTE:
+ Several CAIF Messages might be concatenated. The maximum debug
+ buffer size is 128 bytes.
+
+Error Scenarios
+===============
+
+- last_tx_msg contains channel setup message and last_rx_msg is empty ->
+ The host seems to be able to send over the UART, at least the CAIF ldisc get
+ notified that sending is completed.
+
+- last_tx_msg contains enumeration message and last_rx_msg is empty ->
+ The host is not able to send the message from UART, the tty has not been
+ able to complete the transmit operation.
+
+- if /sys/kernel/debug/caif_serial/<tty>/tty_status is non-zero there
+ might be problems transmitting over UART.
+
+ E.g. host and modem wiring is not correct you will typically see
+ tty_status = 0x10 (hw_stopped) and ser_state = 0x10 (FLOW_OFF_SENT).
+
+ You will probably see the enumeration message in last_tx_message
+ and empty last_rx_message.
diff --git a/Documentation/networking/device_drivers/index.rst b/Documentation/networking/device_drivers/index.rst
index 2b7fefe..f51f925 100644
--- a/Documentation/networking/device_drivers/index.rst
+++ b/Documentation/networking/device_drivers/index.rst
@@ -23,8 +23,9 @@
intel/ice
google/gve
mellanox/mlx5
+ pensando/ionic
-.. only:: subproject
+.. only:: subproject and html
Indices
=======
diff --git a/Documentation/networking/device_drivers/intel/iavf.rst b/Documentation/networking/device_drivers/intel/iavf.rst
index 2d0c3ba..cfc0884 100644
--- a/Documentation/networking/device_drivers/intel/iavf.rst
+++ b/Documentation/networking/device_drivers/intel/iavf.rst
@@ -10,11 +10,15 @@
Contents
========
+- Overview
- Identifying Your Adapter
- Additional Configurations
- Known Issues/Troubleshooting
- Support
+Overview
+========
+
This file describes the iavf Linux* Base Driver. This driver was formerly
called i40evf.
@@ -27,6 +31,7 @@
Identifying Your Adapter
========================
+
The driver in this kernel is compatible with devices based on the following:
* Intel(R) XL710 X710 Virtual Function
* Intel(R) X722 Virtual Function
@@ -50,9 +55,10 @@
restricting system messages. In order to see network driver link messages on
your console, set dmesg to eight by entering the following::
- dmesg -n 8
+ # dmesg -n 8
-NOTE: This setting is not saved across reboots.
+NOTE:
+ This setting is not saved across reboots.
ethtool
-------
@@ -72,11 +78,11 @@
To enable/disable VLAN tag stripping for a VF, issue the following command
from inside the VM in which you are running the VF::
- ethtool -K <if_name> rxvlan on/off
+ # ethtool -K <if_name> rxvlan on/off
or alternatively::
- ethtool --offload <if_name> rxvlan on/off
+ # ethtool --offload <if_name> rxvlan on/off
Adaptive Virtual Function
-------------------------
@@ -91,21 +97,21 @@
which the AVF is associated. The following are base mode features:
- 4 Queue Pairs (QP) and associated Configuration Status Registers (CSRs)
- for Tx/Rx.
-- i40e descriptors and ring format.
-- Descriptor write-back completion.
-- 1 control queue, with i40e descriptors, CSRs and ring format.
-- 5 MSI-X interrupt vectors and corresponding i40e CSRs.
-- 1 Interrupt Throttle Rate (ITR) index.
-- 1 Virtual Station Interface (VSI) per VF.
+ for Tx/Rx
+- i40e descriptors and ring format
+- Descriptor write-back completion
+- 1 control queue, with i40e descriptors, CSRs and ring format
+- 5 MSI-X interrupt vectors and corresponding i40e CSRs
+- 1 Interrupt Throttle Rate (ITR) index
+- 1 Virtual Station Interface (VSI) per VF
- 1 Traffic Class (TC), TC0
- Receive Side Scaling (RSS) with 64 entry indirection table and key,
- configured through the PF.
-- 1 unicast MAC address reserved per VF.
-- 16 MAC address filters for each VF.
-- Stateless offloads - non-tunneled checksums.
-- AVF device ID.
-- HW mailbox is used for VF to PF communications (including on Windows).
+ configured through the PF
+- 1 unicast MAC address reserved per VF
+- 16 MAC address filters for each VF
+- Stateless offloads - non-tunneled checksums
+- AVF device ID
+- HW mailbox is used for VF to PF communications (including on Windows)
IEEE 802.1ad (QinQ) Support
---------------------------
@@ -117,8 +123,8 @@
The following are examples of how to configure 802.1ad (QinQ)::
- ip link add link eth0 eth0.24 type vlan proto 802.1ad id 24
- ip link add link eth0.24 eth0.24.371 type vlan proto 802.1Q id 371
+ # ip link add link eth0 eth0.24 type vlan proto 802.1ad id 24
+ # ip link add link eth0.24 eth0.24.371 type vlan proto 802.1Q id 371
Where "24" and "371" are example VLAN IDs.
@@ -133,6 +139,19 @@
and allow Tx traffic to be rate limited per application. Follow the steps below
to set ADq.
+Requirements:
+
+- The sch_mqprio, act_mirred and cls_flower modules must be loaded
+- The latest version of iproute2
+- If another driver (for example, DPDK) has set cloud filters, you cannot
+ enable ADQ
+- Depending on the underlying PF device, ADQ cannot be enabled when the
+ following features are enabled:
+
+ + Data Center Bridging (DCB)
+ + Multiple Functions per Port (MFP)
+ + Sideband Filters
+
1. Create traffic classes (TCs). Maximum of 8 TCs can be created per interface.
The shaper bw_rlimit parameter is optional.
@@ -141,9 +160,9 @@
::
- # tc qdisc add dev <interface> root mqprio num_tc 2 map 0 0 0 0 1 1 1 1
- queues 16@0 16@16 hw 1 mode channel shaper bw_rlimit min_rate 1Gbit 2Gbit
- max_rate 1Gbit 3Gbit
+ tc qdisc add dev <interface> root mqprio num_tc 2 map 0 0 0 0 1 1 1 1
+ queues 16@0 16@16 hw 1 mode channel shaper bw_rlimit min_rate 1Gbit 2Gbit
+ max_rate 1Gbit 3Gbit
map: priority mapping for up to 16 priorities to tcs (e.g. map 0 0 0 0 1 1 1 1
sets priorities 0-3 to use tc0 and 4-7 to use tc1)
@@ -162,6 +181,10 @@
For example: min_rate 1Gbit 3Gbit: Verify bandwidth limit using network
monitoring tools such as ifstat or sar –n DEV [interval] [number of samples]
+NOTE:
+ Setting up channels via ethtool (ethtool -L) is not supported when the
+ TCs are configured using mqprio.
+
2. Enable HW TC offload on interface::
# ethtool -K <interface> hw-tc-offload on
@@ -171,16 +194,16 @@
# tc qdisc add dev <interface> ingress
NOTES:
- - Run all tc commands from the iproute2 <pathtoiproute2>/tc/ directory.
- - ADq is not compatible with cloud filters.
+ - Run all tc commands from the iproute2 <pathtoiproute2>/tc/ directory
+ - ADq is not compatible with cloud filters
- Setting up channels via ethtool (ethtool -L) is not supported when the TCs
- are configured using mqprio.
+ are configured using mqprio
- You must have iproute2 latest version
- - NVM version 6.01 or later is required.
+ - NVM version 6.01 or later is required
- ADq cannot be enabled when any the following features are enabled: Data
- Center Bridging (DCB), Multiple Functions per Port (MFP), or Sideband Filters.
+ Center Bridging (DCB), Multiple Functions per Port (MFP), or Sideband Filters
- If another driver (for example, DPDK) has set cloud filters, you cannot
- enable ADq.
+ enable ADq
- Tunnel filters are not supported in ADq. If encapsulated packets do arrive
in non-tunnel mode, filtering will be done on the inner headers. For example,
for VXLAN traffic in non-tunnel mode, PCTYPE is identified as a VXLAN
@@ -198,6 +221,16 @@
Known Issues/Troubleshooting
============================
+Bonding fails with VFs bound to an Intel(R) Ethernet Controller 700 series device
+---------------------------------------------------------------------------------
+If you bind Virtual Functions (VFs) to an Intel(R) Ethernet Controller 700
+series based device, the VF slaves may fail when they become the active slave.
+If the MAC address of the VF is set by the PF (Physical Function) of the
+device, when you add a slave, or change the active-backup slave, Linux bonding
+tries to sync the backup slave's MAC address to the same MAC address as the
+active slave. Linux bonding will fail at this point. This issue will not occur
+if the VF's MAC address is not set by the PF.
+
Traffic Is Not Being Passed Between VM and Client
-------------------------------------------------
You may not be able to pass traffic between a client system and a
@@ -215,13 +248,28 @@
Machine (VM) is bound to it. Doing so will cause the port to appear to hang.
Once the VM shuts down, or otherwise releases the VF, the command will complete.
+Using four traffic classes fails
+--------------------------------
+Do not try to reserve more than three traffic classes in the iavf driver. Doing
+so will fail to set any traffic classes and will cause the driver to write
+errors to stdout. Use a maximum of three queues to avoid this issue.
+
+Multiple log error messages on iavf driver removal
+--------------------------------------------------
+If you have several VFs and you remove the iavf driver, several instances of
+the following log errors are written to the log::
+
+ Unable to send opcode 2 to PF, err I40E_ERR_QUEUE_EMPTY, aq_err ok
+ Unable to send the message to VF 2 aq_err 12
+ ARQ Overflow Error detected
+
Virtual machine does not get link
---------------------------------
If the virtual machine has more than one virtual port assigned to it, and those
virtual ports are bound to different physical ports, you may not get link on
all of the virtual ports. The following command may work around the issue::
- ethtool -r <PF>
+ # ethtool -r <PF>
Where <PF> is the PF interface in the host, for example: p5p1. You may need to
run the command more than once to get link on all virtual ports.
@@ -251,12 +299,13 @@
If you have multiple interfaces in a server, either turn on ARP filtering by
entering::
- echo 1 > /proc/sys/net/ipv4/conf/all/arp_filter
+ # echo 1 > /proc/sys/net/ipv4/conf/all/arp_filter
-NOTE: This setting is not saved across reboots. The configuration change can be
-made permanent by adding the following line to the file /etc/sysctl.conf::
+NOTE:
+ This setting is not saved across reboots. The configuration change can be
+ made permanent by adding the following line to the file /etc/sysctl.conf::
- net.ipv4.conf.all.arp_filter = 1
+ net.ipv4.conf.all.arp_filter = 1
Another alternative is to install the interfaces in separate broadcast domains
(either in different switches or in a switch partitioned to VLANs).
diff --git a/Documentation/networking/device_drivers/mellanox/mlx5.rst b/Documentation/networking/device_drivers/mellanox/mlx5.rst
index 2143258..d071c6b 100644
--- a/Documentation/networking/device_drivers/mellanox/mlx5.rst
+++ b/Documentation/networking/device_drivers/mellanox/mlx5.rst
@@ -11,7 +11,9 @@
- `Enabling the driver and kconfig options`_
- `Devlink info`_
+- `Devlink parameters`_
- `Devlink health reporters`_
+- `mlx5 tracepoints`_
Enabling the driver and kconfig options
================================================
@@ -121,12 +123,44 @@
stored:
fw.version 16.26.0100
+Devlink parameters
+==================
+
+flow_steering_mode: Device flow steering mode
+---------------------------------------------
+The flow steering mode parameter controls the flow steering mode of the driver.
+Two modes are supported:
+1. 'dmfs' - Device managed flow steering.
+2. 'smfs - Software/Driver managed flow steering.
+
+In DMFS mode, the HW steering entities are created and managed through the
+Firmware.
+In SMFS mode, the HW steering entities are created and managed though by
+the driver directly into Hardware without firmware intervention.
+
+SMFS mode is faster and provides better rule inserstion rate compared to default DMFS mode.
+
+User command examples:
+
+- Set SMFS flow steering mode::
+
+ $ devlink dev param set pci/0000:06:00.0 name flow_steering_mode value "smfs" cmode runtime
+
+- Read device flow steering mode::
+
+ $ devlink dev param show pci/0000:06:00.0 name flow_steering_mode
+ pci/0000:06:00.0:
+ name flow_steering_mode type driver-specific
+ values:
+ cmode runtime value smfs
+
+
Devlink health reporters
========================
tx reporter
-----------
-The tx reporter is responsible of two error scenarios:
+The tx reporter is responsible for reporting and recovering of the following two error scenarios:
- TX timeout
Report on kernel tx timeout detection.
@@ -135,7 +169,7 @@
Report on error tx completion.
Recover by flushing the TX queue and reset it.
-TX reporter also support Diagnose callback, on which it provides
+TX reporter also support on demand diagnose callback, on which it provides
real time information of its send queues status.
User commands examples:
@@ -144,11 +178,40 @@
$ devlink health diagnose pci/0000:82:00.0 reporter tx
+NOTE: This command has valid output only when interface is up, otherwise the command has empty output.
+
- Show number of tx errors indicated, number of recover flows ended successfully,
is autorecover enabled and graceful period from last recover::
$ devlink health show pci/0000:82:00.0 reporter tx
+rx reporter
+-----------
+The rx reporter is responsible for reporting and recovering of the following two error scenarios:
+
+- RX queues initialization (population) timeout
+ RX queues descriptors population on ring initialization is done in
+ napi context via triggering an irq, in case of a failure to get
+ the minimum amount of descriptors, a timeout would occur and it
+ could be recoverable by polling the EQ (Event Queue).
+- RX completions with errors (reported by HW on interrupt context)
+ Report on rx completion error.
+ Recover (if needed) by flushing the related queue and reset it.
+
+RX reporter also supports on demand diagnose callback, on which it
+provides real time information of its receive queues status.
+
+- Diagnose rx queues status, and corresponding completion queue::
+
+ $ devlink health diagnose pci/0000:82:00.0 reporter rx
+
+NOTE: This command has valid output only when interface is up, otherwise the command has empty output.
+
+- Show number of rx errors indicated, number of recover flows ended successfully,
+ is autorecover enabled and graceful period from last recover::
+
+ $ devlink health show pci/0000:82:00.0 reporter rx
+
fw reporter
-----------
The fw reporter implements diagnose and dump callbacks.
@@ -190,3 +253,48 @@
$ devlink health dump show pci/0000:82:00.1 reporter fw_fatal
NOTE: This command can run only on PF.
+
+mlx5 tracepoints
+================
+
+mlx5 driver provides internal trace points for tracking and debugging using
+kernel tracepoints interfaces (refer to Documentation/trace/ftrase.rst).
+
+For the list of support mlx5 events check /sys/kernel/debug/tracing/events/mlx5/
+
+tc and eswitch offloads tracepoints:
+
+- mlx5e_configure_flower: trace flower filter actions and cookies offloaded to mlx5::
+
+ $ echo mlx5:mlx5e_configure_flower >> /sys/kernel/debug/tracing/set_event
+ $ cat /sys/kernel/debug/tracing/trace
+ ...
+ tc-6535 [019] ...1 2672.404466: mlx5e_configure_flower: cookie=0000000067874a55 actions= REDIRECT
+
+- mlx5e_delete_flower: trace flower filter actions and cookies deleted from mlx5::
+
+ $ echo mlx5:mlx5e_delete_flower >> /sys/kernel/debug/tracing/set_event
+ $ cat /sys/kernel/debug/tracing/trace
+ ...
+ tc-6569 [010] .N.1 2686.379075: mlx5e_delete_flower: cookie=0000000067874a55 actions= NULL
+
+- mlx5e_stats_flower: trace flower stats request::
+
+ $ echo mlx5:mlx5e_stats_flower >> /sys/kernel/debug/tracing/set_event
+ $ cat /sys/kernel/debug/tracing/trace
+ ...
+ tc-6546 [010] ...1 2679.704889: mlx5e_stats_flower: cookie=0000000060eb3d6a bytes=0 packets=0 lastused=4295560217
+
+- mlx5e_tc_update_neigh_used_value: trace tunnel rule neigh update value offloaded to mlx5::
+
+ $ echo mlx5:mlx5e_tc_update_neigh_used_value >> /sys/kernel/debug/tracing/set_event
+ $ cat /sys/kernel/debug/tracing/trace
+ ...
+ kworker/u48:4-8806 [009] ...1 55117.882428: mlx5e_tc_update_neigh_used_value: netdev: ens1f0 IPv4: 1.1.1.10 IPv6: ::ffff:1.1.1.10 neigh_used=1
+
+- mlx5e_rep_neigh_update: trace neigh update tasks scheduled due to neigh state change events::
+
+ $ echo mlx5:mlx5e_rep_neigh_update >> /sys/kernel/debug/tracing/set_event
+ $ cat /sys/kernel/debug/tracing/trace
+ ...
+ kworker/u48:7-2221 [009] ...1 1475.387435: mlx5e_rep_neigh_update: netdev: ens1f0 MAC: 24:8a:07:9a:17:9a IPv4: 1.1.1.10 IPv6: ::ffff:1.1.1.10 neigh_connected=1
diff --git a/Documentation/networking/device_drivers/netronome/nfp.rst b/Documentation/networking/device_drivers/netronome/nfp.rst
new file mode 100644
index 0000000..6c08ac8
--- /dev/null
+++ b/Documentation/networking/device_drivers/netronome/nfp.rst
@@ -0,0 +1,133 @@
+.. SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+
+=============================================
+Netronome Flow Processor (NFP) Kernel Drivers
+=============================================
+
+Copyright (c) 2019, Netronome Systems, Inc.
+
+Contents
+========
+
+- `Overview`_
+- `Acquiring Firmware`_
+
+Overview
+========
+
+This driver supports Netronome's line of Flow Processor devices,
+including the NFP4000, NFP5000, and NFP6000 models, which are also
+incorporated in the company's family of Agilio SmartNICs. The SR-IOV
+physical and virtual functions for these devices are supported by
+the driver.
+
+Acquiring Firmware
+==================
+
+The NFP4000 and NFP6000 devices require application specific firmware
+to function. Application firmware can be located either on the host file system
+or in the device flash (if supported by management firmware).
+
+Firmware files on the host filesystem contain card type (`AMDA-*` string), media
+config etc. They should be placed in `/lib/firmware/netronome` directory to
+load firmware from the host file system.
+
+Firmware for basic NIC operation is available in the upstream
+`linux-firmware.git` repository.
+
+Firmware in NVRAM
+-----------------
+
+Recent versions of management firmware supports loading application
+firmware from flash when the host driver gets probed. The firmware loading
+policy configuration may be used to configure this feature appropriately.
+
+Devlink or ethtool can be used to update the application firmware on the device
+flash by providing the appropriate `nic_AMDA*.nffw` file to the respective
+command. Users need to take care to write the correct firmware image for the
+card and media configuration to flash.
+
+Available storage space in flash depends on the card being used.
+
+Dealing with multiple projects
+------------------------------
+
+NFP hardware is fully programmable therefore there can be different
+firmware images targeting different applications.
+
+When using application firmware from host, we recommend placing
+actual firmware files in application-named subdirectories in
+`/lib/firmware/netronome` and linking the desired files, e.g.::
+
+ $ tree /lib/firmware/netronome/
+ /lib/firmware/netronome/
+ ├── bpf
+ │ ├── nic_AMDA0081-0001_1x40.nffw
+ │ └── nic_AMDA0081-0001_4x10.nffw
+ ├── flower
+ │ ├── nic_AMDA0081-0001_1x40.nffw
+ │ └── nic_AMDA0081-0001_4x10.nffw
+ ├── nic
+ │ ├── nic_AMDA0081-0001_1x40.nffw
+ │ └── nic_AMDA0081-0001_4x10.nffw
+ ├── nic_AMDA0081-0001_1x40.nffw -> bpf/nic_AMDA0081-0001_1x40.nffw
+ └── nic_AMDA0081-0001_4x10.nffw -> bpf/nic_AMDA0081-0001_4x10.nffw
+
+ 3 directories, 8 files
+
+You may need to use hard instead of symbolic links on distributions
+which use old `mkinitrd` command instead of `dracut` (e.g. Ubuntu).
+
+After changing firmware files you may need to regenerate the initramfs
+image. Initramfs contains drivers and firmware files your system may
+need to boot. Refer to the documentation of your distribution to find
+out how to update initramfs. Good indication of stale initramfs
+is system loading wrong driver or firmware on boot, but when driver is
+later reloaded manually everything works correctly.
+
+Selecting firmware per device
+-----------------------------
+
+Most commonly all cards on the system use the same type of firmware.
+If you want to load specific firmware image for a specific card, you
+can use either the PCI bus address or serial number. Driver will print
+which files it's looking for when it recognizes a NFP device::
+
+ nfp: Looking for firmware file in order of priority:
+ nfp: netronome/serial-00-12-34-aa-bb-cc-10-ff.nffw: not found
+ nfp: netronome/pci-0000:02:00.0.nffw: not found
+ nfp: netronome/nic_AMDA0081-0001_1x40.nffw: found, loading...
+
+In this case if file (or link) called *serial-00-12-34-aa-bb-5d-10-ff.nffw*
+or *pci-0000:02:00.0.nffw* is present in `/lib/firmware/netronome` this
+firmware file will take precedence over `nic_AMDA*` files.
+
+Note that `serial-*` and `pci-*` files are **not** automatically included
+in initramfs, you will have to refer to documentation of appropriate tools
+to find out how to include them.
+
+Firmware loading policy
+-----------------------
+
+Firmware loading policy is controlled via three HWinfo parameters
+stored as key value pairs in the device flash:
+
+app_fw_from_flash
+ Defines which firmware should take precedence, 'Disk' (0), 'Flash' (1) or
+ the 'Preferred' (2) firmware. When 'Preferred' is selected, the management
+ firmware makes the decision over which firmware will be loaded by comparing
+ versions of the flash firmware and the host supplied firmware.
+ This variable is configurable using the 'fw_load_policy'
+ devlink parameter.
+
+abi_drv_reset
+ Defines if the driver should reset the firmware when
+ the driver is probed, either 'Disk' (0) if firmware was found on disk,
+ 'Always' (1) reset or 'Never' (2) reset. Note that the device is always
+ reset on driver unload if firmware was loaded when the driver was probed.
+ This variable is configurable using the 'reset_dev_on_drv_probe'
+ devlink parameter.
+
+abi_drv_load_ifc
+ Defines a list of PF devices allowed to load FW on the device.
+ This variable is not currently user configurable.
diff --git a/Documentation/networking/device_drivers/pensando/ionic.rst b/Documentation/networking/device_drivers/pensando/ionic.rst
new file mode 100644
index 0000000..67b6839
--- /dev/null
+++ b/Documentation/networking/device_drivers/pensando/ionic.rst
@@ -0,0 +1,43 @@
+.. SPDX-License-Identifier: GPL-2.0+
+
+==========================================================
+Linux* Driver for the Pensando(R) Ethernet adapter family
+==========================================================
+
+Pensando Linux Ethernet driver.
+Copyright(c) 2019 Pensando Systems, Inc
+
+Contents
+========
+
+- Identifying the Adapter
+- Support
+
+Identifying the Adapter
+=======================
+
+To find if one or more Pensando PCI Ethernet devices are installed on the
+host, check for the PCI devices::
+
+ $ lspci -d 1dd8:
+ b5:00.0 Ethernet controller: Device 1dd8:1002
+ b6:00.0 Ethernet controller: Device 1dd8:1002
+
+If such devices are listed as above, then the ionic.ko driver should find
+and configure them for use. There should be log entries in the kernel
+messages such as these::
+
+ $ dmesg | grep ionic
+ ionic Pensando Ethernet NIC Driver, ver 0.15.0-k
+ ionic 0000:b5:00.0 enp181s0: renamed from eth0
+ ionic 0000:b6:00.0 enp182s0: renamed from eth0
+
+Support
+=======
+For general Linux networking support, please use the netdev mailing
+list, which is monitored by Pensando personnel::
+ netdev@vger.kernel.org
+
+For more specific support needs, please use the Pensando driver support
+email::
+ drivers@pensando.io
diff --git a/Documentation/networking/devlink-info-versions.rst b/Documentation/networking/devlink-info-versions.rst
index 4316342..4914f58 100644
--- a/Documentation/networking/devlink-info-versions.rst
+++ b/Documentation/networking/devlink-info-versions.rst
@@ -14,11 +14,27 @@
Board design revision.
+asic.id
+=======
+
+ASIC design identifier.
+
+asic.rev
+========
+
+ASIC design revision.
+
board.manufacture
=================
An identifier of the company or the facility which produced the part.
+fw
+==
+
+Overall firmware version, often representing the collection of
+fw.mgmt, fw.app, etc.
+
fw.mgmt
=======
diff --git a/Documentation/networking/devlink-params-nfp.txt b/Documentation/networking/devlink-params-nfp.txt
new file mode 100644
index 0000000..43e4d40
--- /dev/null
+++ b/Documentation/networking/devlink-params-nfp.txt
@@ -0,0 +1,5 @@
+fw_load_policy [DEVICE, GENERIC]
+ Configuration mode: permanent
+
+reset_dev_on_drv_probe [DEVICE, GENERIC]
+ Configuration mode: permanent
diff --git a/Documentation/networking/devlink-params.txt b/Documentation/networking/devlink-params.txt
index 2d26434..ddba3e9 100644
--- a/Documentation/networking/devlink-params.txt
+++ b/Documentation/networking/devlink-params.txt
@@ -48,4 +48,20 @@
Load firmware version preferred by the driver.
* DEVLINK_PARAM_FW_LOAD_POLICY_VALUE_FLASH (1)
Load firmware currently stored in flash.
+ * DEVLINK_PARAM_FW_LOAD_POLICY_VALUE_DISK (2)
+ Load firmware currently available on host's disk.
+ Type: u8
+
+reset_dev_on_drv_probe [DEVICE, GENERIC]
+ Controls the device's reset policy on driver probe.
+ Valid values:
+ * DEVLINK_PARAM_RESET_DEV_ON_DRV_PROBE_VALUE_UNKNOWN (0)
+ Unknown or invalid value.
+ * DEVLINK_PARAM_RESET_DEV_ON_DRV_PROBE_VALUE_ALWAYS (1)
+ Always reset device on driver probe.
+ * DEVLINK_PARAM_RESET_DEV_ON_DRV_PROBE_VALUE_NEVER (2)
+ Never reset device on driver probe.
+ * DEVLINK_PARAM_RESET_DEV_ON_DRV_PROBE_VALUE_DISK (3)
+ Reset only if device firmware can be found in the
+ filesystem.
Type: u8
diff --git a/Documentation/networking/devlink-trap-netdevsim.rst b/Documentation/networking/devlink-trap-netdevsim.rst
new file mode 100644
index 0000000..b721c94
--- /dev/null
+++ b/Documentation/networking/devlink-trap-netdevsim.rst
@@ -0,0 +1,20 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+======================
+Devlink Trap netdevsim
+======================
+
+Driver-specific Traps
+=====================
+
+.. list-table:: List of Driver-specific Traps Registered by ``netdevsim``
+ :widths: 5 5 90
+
+ * - Name
+ - Type
+ - Description
+ * - ``fid_miss``
+ - ``exception``
+ - When a packet enters the device it is classified to a filtering
+ indentifier (FID) based on the ingress port and VLAN. This trap is used
+ to trap packets for which a FID could not be found
diff --git a/Documentation/networking/devlink-trap.rst b/Documentation/networking/devlink-trap.rst
new file mode 100644
index 0000000..8e90a85
--- /dev/null
+++ b/Documentation/networking/devlink-trap.rst
@@ -0,0 +1,209 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+============
+Devlink Trap
+============
+
+Background
+==========
+
+Devices capable of offloading the kernel's datapath and perform functions such
+as bridging and routing must also be able to send specific packets to the
+kernel (i.e., the CPU) for processing.
+
+For example, a device acting as a multicast-aware bridge must be able to send
+IGMP membership reports to the kernel for processing by the bridge module.
+Without processing such packets, the bridge module could never populate its
+MDB.
+
+As another example, consider a device acting as router which has received an IP
+packet with a TTL of 1. Upon routing the packet the device must send it to the
+kernel so that it will route it as well and generate an ICMP Time Exceeded
+error datagram. Without letting the kernel route such packets itself, utilities
+such as ``traceroute`` could never work.
+
+The fundamental ability of sending certain packets to the kernel for processing
+is called "packet trapping".
+
+Overview
+========
+
+The ``devlink-trap`` mechanism allows capable device drivers to register their
+supported packet traps with ``devlink`` and report trapped packets to
+``devlink`` for further analysis.
+
+Upon receiving trapped packets, ``devlink`` will perform a per-trap packets and
+bytes accounting and potentially report the packet to user space via a netlink
+event along with all the provided metadata (e.g., trap reason, timestamp, input
+port). This is especially useful for drop traps (see :ref:`Trap-Types`)
+as it allows users to obtain further visibility into packet drops that would
+otherwise be invisible.
+
+The following diagram provides a general overview of ``devlink-trap``::
+
+ Netlink event: Packet w/ metadata
+ Or a summary of recent drops
+ ^
+ |
+ Userspace |
+ +---------------------------------------------------+
+ Kernel |
+ |
+ +-------+--------+
+ | |
+ | drop_monitor |
+ | |
+ +-------^--------+
+ |
+ |
+ |
+ +----+----+
+ | | Kernel's Rx path
+ | devlink | (non-drop traps)
+ | |
+ +----^----+ ^
+ | |
+ +-----------+
+ |
+ +-------+-------+
+ | |
+ | Device driver |
+ | |
+ +-------^-------+
+ Kernel |
+ +---------------------------------------------------+
+ Hardware |
+ | Trapped packet
+ |
+ +--+---+
+ | |
+ | ASIC |
+ | |
+ +------+
+
+.. _Trap-Types:
+
+Trap Types
+==========
+
+The ``devlink-trap`` mechanism supports the following packet trap types:
+
+ * ``drop``: Trapped packets were dropped by the underlying device. Packets
+ are only processed by ``devlink`` and not injected to the kernel's Rx path.
+ The trap action (see :ref:`Trap-Actions`) can be changed.
+ * ``exception``: Trapped packets were not forwarded as intended by the
+ underlying device due to an exception (e.g., TTL error, missing neighbour
+ entry) and trapped to the control plane for resolution. Packets are
+ processed by ``devlink`` and injected to the kernel's Rx path. Changing the
+ action of such traps is not allowed, as it can easily break the control
+ plane.
+
+.. _Trap-Actions:
+
+Trap Actions
+============
+
+The ``devlink-trap`` mechanism supports the following packet trap actions:
+
+ * ``trap``: The sole copy of the packet is sent to the CPU.
+ * ``drop``: The packet is dropped by the underlying device and a copy is not
+ sent to the CPU.
+
+Generic Packet Traps
+====================
+
+Generic packet traps are used to describe traps that trap well-defined packets
+or packets that are trapped due to well-defined conditions (e.g., TTL error).
+Such traps can be shared by multiple device drivers and their description must
+be added to the following table:
+
+.. list-table:: List of Generic Packet Traps
+ :widths: 5 5 90
+
+ * - Name
+ - Type
+ - Description
+ * - ``source_mac_is_multicast``
+ - ``drop``
+ - Traps incoming packets that the device decided to drop because of a
+ multicast source MAC
+ * - ``vlan_tag_mismatch``
+ - ``drop``
+ - Traps incoming packets that the device decided to drop in case of VLAN
+ tag mismatch: The ingress bridge port is not configured with a PVID and
+ the packet is untagged or prio-tagged
+ * - ``ingress_vlan_filter``
+ - ``drop``
+ - Traps incoming packets that the device decided to drop in case they are
+ tagged with a VLAN that is not configured on the ingress bridge port
+ * - ``ingress_spanning_tree_filter``
+ - ``drop``
+ - Traps incoming packets that the device decided to drop in case the STP
+ state of the ingress bridge port is not "forwarding"
+ * - ``port_list_is_empty``
+ - ``drop``
+ - Traps packets that the device decided to drop in case they need to be
+ flooded (e.g., unknown unicast, unregistered multicast) and there are
+ no ports the packets should be flooded to
+ * - ``port_loopback_filter``
+ - ``drop``
+ - Traps packets that the device decided to drop in case after layer 2
+ forwarding the only port from which they should be transmitted through
+ is the port from which they were received
+ * - ``blackhole_route``
+ - ``drop``
+ - Traps packets that the device decided to drop in case they hit a
+ blackhole route
+ * - ``ttl_value_is_too_small``
+ - ``exception``
+ - Traps unicast packets that should be forwarded by the device whose TTL
+ was decremented to 0 or less
+ * - ``tail_drop``
+ - ``drop``
+ - Traps packets that the device decided to drop because they could not be
+ enqueued to a transmission queue which is full
+
+Driver-specific Packet Traps
+============================
+
+Device drivers can register driver-specific packet traps, but these must be
+clearly documented. Such traps can correspond to device-specific exceptions and
+help debug packet drops caused by these exceptions. The following list includes
+links to the description of driver-specific traps registered by various device
+drivers:
+
+ * :doc:`/devlink-trap-netdevsim`
+
+Generic Packet Trap Groups
+==========================
+
+Generic packet trap groups are used to aggregate logically related packet
+traps. These groups allow the user to batch operations such as setting the trap
+action of all member traps. In addition, ``devlink-trap`` can report aggregated
+per-group packets and bytes statistics, in case per-trap statistics are too
+narrow. The description of these groups must be added to the following table:
+
+.. list-table:: List of Generic Packet Trap Groups
+ :widths: 10 90
+
+ * - Name
+ - Description
+ * - ``l2_drops``
+ - Contains packet traps for packets that were dropped by the device during
+ layer 2 forwarding (i.e., bridge)
+ * - ``l3_drops``
+ - Contains packet traps for packets that were dropped by the device or hit
+ an exception (e.g., TTL error) during layer 3 forwarding
+ * - ``buffer_drops``
+ - Contains packet traps for packets that were dropped by the device due to
+ an enqueue decision
+
+Testing
+=======
+
+See ``tools/testing/selftests/drivers/net/netdevsim/devlink_trap.sh`` for a
+test covering the core infrastructure. Test cases should be added for any new
+functionality.
+
+Device drivers should focus their tests on device-specific functionality, such
+as the triggering of supported packet traps.
diff --git a/Documentation/networking/dsa/sja1105.rst b/Documentation/networking/dsa/sja1105.rst
index cb2858d..eef20d0 100644
--- a/Documentation/networking/dsa/sja1105.rst
+++ b/Documentation/networking/dsa/sja1105.rst
@@ -146,6 +146,96 @@
this mode, the switch ports beneath br0 are not capable of regular traffic, and
are only used as a conduit for switchdev operations.
+Offloads
+========
+
+Time-aware scheduling
+---------------------
+
+The switch supports a variation of the enhancements for scheduled traffic
+specified in IEEE 802.1Q-2018 (formerly 802.1Qbv). This means it can be used to
+ensure deterministic latency for priority traffic that is sent in-band with its
+gate-open event in the network schedule.
+
+This capability can be managed through the tc-taprio offload ('flags 2'). The
+difference compared to the software implementation of taprio is that the latter
+would only be able to shape traffic originated from the CPU, but not
+autonomously forwarded flows.
+
+The device has 8 traffic classes, and maps incoming frames to one of them based
+on the VLAN PCP bits (if no VLAN is present, the port-based default is used).
+As described in the previous sections, depending on the value of
+``vlan_filtering``, the EtherType recognized by the switch as being VLAN can
+either be the typical 0x8100 or a custom value used internally by the driver
+for tagging. Therefore, the switch ignores the VLAN PCP if used in standalone
+or bridge mode with ``vlan_filtering=0``, as it will not recognize the 0x8100
+EtherType. In these modes, injecting into a particular TX queue can only be
+done by the DSA net devices, which populate the PCP field of the tagging header
+on egress. Using ``vlan_filtering=1``, the behavior is the other way around:
+offloaded flows can be steered to TX queues based on the VLAN PCP, but the DSA
+net devices are no longer able to do that. To inject frames into a hardware TX
+queue with VLAN awareness active, it is necessary to create a VLAN
+sub-interface on the DSA master port, and send normal (0x8100) VLAN-tagged
+towards the switch, with the VLAN PCP bits set appropriately.
+
+Management traffic (having DMAC 01-80-C2-xx-xx-xx or 01-19-1B-xx-xx-xx) is the
+notable exception: the switch always treats it with a fixed priority and
+disregards any VLAN PCP bits even if present. The traffic class for management
+traffic has a value of 7 (highest priority) at the moment, which is not
+configurable in the driver.
+
+Below is an example of configuring a 500 us cyclic schedule on egress port
+``swp5``. The traffic class gate for management traffic (7) is open for 100 us,
+and the gates for all other traffic classes are open for 400 us::
+
+ #!/bin/bash
+
+ set -e -u -o pipefail
+
+ NSEC_PER_SEC="1000000000"
+
+ gatemask() {
+ local tc_list="$1"
+ local mask=0
+
+ for tc in ${tc_list}; do
+ mask=$((${mask} | (1 << ${tc})))
+ done
+
+ printf "%02x" ${mask}
+ }
+
+ if ! systemctl is-active --quiet ptp4l; then
+ echo "Please start the ptp4l service"
+ exit
+ fi
+
+ now=$(phc_ctl /dev/ptp1 get | gawk '/clock time is/ { print $5; }')
+ # Phase-align the base time to the start of the next second.
+ sec=$(echo "${now}" | gawk -F. '{ print $1; }')
+ base_time="$(((${sec} + 1) * ${NSEC_PER_SEC}))"
+
+ tc qdisc add dev swp5 parent root handle 100 taprio \
+ num_tc 8 \
+ map 0 1 2 3 5 6 7 \
+ queues 1@0 1@1 1@2 1@3 1@4 1@5 1@6 1@7 \
+ base-time ${base_time} \
+ sched-entry S $(gatemask 7) 100000 \
+ sched-entry S $(gatemask "0 1 2 3 4 5 6") 400000 \
+ flags 2
+
+It is possible to apply the tc-taprio offload on multiple egress ports. There
+are hardware restrictions related to the fact that no gate event may trigger
+simultaneously on two ports. The driver checks the consistency of the schedules
+against this restriction and errors out when appropriate. Schedule analysis is
+needed to avoid this, which is outside the scope of the document.
+
+At the moment, the time-aware scheduler can only be triggered based on a
+standalone clock and not based on PTP time. This means the base-time argument
+from tc-taprio is ignored and the schedule starts right away. It also means it
+is more difficult to phase-align the scheduler with the other devices in the
+network.
+
Device Tree bindings and board design
=====================================
diff --git a/Documentation/networking/index.rst b/Documentation/networking/index.rst
index a46fca2..d4dca42 100644
--- a/Documentation/networking/index.rst
+++ b/Documentation/networking/index.rst
@@ -14,7 +14,10 @@
device_drivers/index
dsa/index
devlink-info-versions
+ devlink-trap
+ devlink-trap-netdevsim
ieee802154
+ j1939
kapi
z8530book
msg_zerocopy
@@ -31,7 +34,7 @@
tls
tls-offload
-.. only:: subproject
+.. only:: subproject and html
Indices
=======
diff --git a/Documentation/networking/ip-sysctl.txt b/Documentation/networking/ip-sysctl.txt
index df33674..49e95f4 100644
--- a/Documentation/networking/ip-sysctl.txt
+++ b/Documentation/networking/ip-sysctl.txt
@@ -256,6 +256,12 @@
Path MTU discovery (MTU probing). If MTU probing is enabled,
this is the initial MSS used by the connection.
+tcp_mtu_probe_floor - INTEGER
+ If MTU probing is enabled this caps the minimum MSS used for search_low
+ for the connection.
+
+ Default : 48
+
tcp_min_snd_mss - INTEGER
TCP SYN and SYNACK messages usually advertise an ADVMSS option,
as described in RFC 1122 and RFC 6691.
diff --git a/Documentation/networking/j1939.rst b/Documentation/networking/j1939.rst
new file mode 100644
index 0000000..ce7e7a0
--- /dev/null
+++ b/Documentation/networking/j1939.rst
@@ -0,0 +1,422 @@
+.. SPDX-License-Identifier: (GPL-2.0 OR MIT)
+
+===================
+J1939 Documentation
+===================
+
+Overview / What Is J1939
+========================
+
+SAE J1939 defines a higher layer protocol on CAN. It implements a more
+sophisticated addressing scheme and extends the maximum packet size above 8
+bytes. Several derived specifications exist, which differ from the original
+J1939 on the application level, like MilCAN A, NMEA2000 and especially
+ISO-11783 (ISOBUS). This last one specifies the so-called ETP (Extended
+Transport Protocol) which is has been included in this implementation. This
+results in a maximum packet size of ((2 ^ 24) - 1) * 7 bytes == 111 MiB.
+
+Specifications used
+-------------------
+
+* SAE J1939-21 : data link layer
+* SAE J1939-81 : network management
+* ISO 11783-6 : Virtual Terminal (Extended Transport Protocol)
+
+.. _j1939-motivation:
+
+Motivation
+==========
+
+Given the fact there's something like SocketCAN with an API similar to BSD
+sockets, we found some reasons to justify a kernel implementation for the
+addressing and transport methods used by J1939.
+
+* **Addressing:** when a process on an ECU communicates via J1939, it should
+ not necessarily know its source address. Although at least one process per
+ ECU should know the source address. Other processes should be able to reuse
+ that address. This way, address parameters for different processes
+ cooperating for the same ECU, are not duplicated. This way of working is
+ closely related to the UNIX concept where programs do just one thing, and do
+ it well.
+
+* **Dynamic addressing:** Address Claiming in J1939 is time critical.
+ Furthermore data transport should be handled properly during the address
+ negotiation. Putting this functionality in the kernel eliminates it as a
+ requirement for _every_ user space process that communicates via J1939. This
+ results in a consistent J1939 bus with proper addressing.
+
+* **Transport:** both TP & ETP reuse some PGNs to relay big packets over them.
+ Different processes may thus use the same TP & ETP PGNs without actually
+ knowing it. The individual TP & ETP sessions _must_ be serialized
+ (synchronized) between different processes. The kernel solves this problem
+ properly and eliminates the serialization (synchronization) as a requirement
+ for _every_ user space process that communicates via J1939.
+
+J1939 defines some other features (relaying, gateway, fast packet transport,
+...). In-kernel code for these would not contribute to protocol stability.
+Therefore, these parts are left to user space.
+
+The J1939 sockets operate on CAN network devices (see SocketCAN). Any J1939
+user space library operating on CAN raw sockets will still operate properly.
+Since such library does not communicate with the in-kernel implementation, care
+must be taken that these two do not interfere. In practice, this means they
+cannot share ECU addresses. A single ECU (or virtual ECU) address is used by
+the library exclusively, or by the in-kernel system exclusively.
+
+J1939 concepts
+==============
+
+PGN
+---
+
+The PGN (Parameter Group Number) is a number to identify a packet. The PGN
+is composed as follows:
+1 bit : Reserved Bit
+1 bit : Data Page
+8 bits : PF (PDU Format)
+8 bits : PS (PDU Specific)
+
+In J1939-21 distinction is made between PDU1 format (where PF < 240) and PDU2
+format (where PF >= 240). Furthermore, when using PDU2 format, the PS-field
+contains a so-called Group Extension, which is part of the PGN. When using PDU2
+format, the Group Extension is set in the PS-field.
+
+On the other hand, when using PDU1 format, the PS-field contains a so-called
+Destination Address, which is _not_ part of the PGN. When communicating a PGN
+from user space to kernel (or visa versa) and PDU2 format is used, the PS-field
+of the PGN shall be set to zero. The Destination Address shall be set
+elsewhere.
+
+Regarding PGN mapping to 29-bit CAN identifier, the Destination Address shall
+be get/set from/to the appropriate bits of the identifier by the kernel.
+
+
+Addressing
+----------
+
+Both static and dynamic addressing methods can be used.
+
+For static addresses, no extra checks are made by the kernel, and provided
+addresses are considered right. This responsibility is for the OEM or system
+integrator.
+
+For dynamic addressing, so-called Address Claiming, extra support is foreseen
+in the kernel. In J1939 any ECU is known by it's 64-bit NAME. At the moment of
+a successful address claim, the kernel keeps track of both NAME and source
+address being claimed. This serves as a base for filter schemes. By default,
+packets with a destination that is not locally, will be rejected.
+
+Mixed mode packets (from a static to a dynamic address or vice versa) are
+allowed. The BSD sockets define separate API calls for getting/setting the
+local & remote address and are applicable for J1939 sockets.
+
+Filtering
+---------
+
+J1939 defines white list filters per socket that a user can set in order to
+receive a subset of the J1939 traffic. Filtering can be based on:
+
+* SA
+* SOURCE_NAME
+* PGN
+
+When multiple filters are in place for a single socket, and a packet comes in
+that matches several of those filters, the packet is only received once for
+that socket.
+
+How to Use J1939
+================
+
+API Calls
+---------
+
+On CAN, you first need to open a socket for communicating over a CAN network.
+To use J1939, #include <linux/can/j1939.h>. From there, <linux/can.h> will be
+included too. To open a socket, use:
+
+.. code-block:: C
+
+ s = socket(PF_CAN, SOCK_DGRAM, CAN_J1939);
+
+J1939 does use SOCK_DGRAM sockets. In the J1939 specification, connections are
+mentioned in the context of transport protocol sessions. These still deliver
+packets to the other end (using several CAN packets). SOCK_STREAM is not
+supported.
+
+After the successful creation of the socket, you would normally use the bind(2)
+and/or connect(2) system call to bind the socket to a CAN interface. After
+binding and/or connecting the socket, you can read(2) and write(2) from/to the
+socket or use send(2), sendto(2), sendmsg(2) and the recv*() counterpart
+operations on the socket as usual. There are also J1939 specific socket options
+described below.
+
+In order to send data, a bind(2) must have been successful. bind(2) assigns a
+local address to a socket.
+
+Different from CAN is that the payload data is just the data that get send,
+without it's header info. The header info is derived from the sockaddr supplied
+to bind(2), connect(2), sendto(2) and recvfrom(2). A write(2) with size 4 will
+result in a packet with 4 bytes.
+
+The sockaddr structure has extensions for use with J1939 as specified below:
+
+.. code-block:: C
+
+ struct sockaddr_can {
+ sa_family_t can_family;
+ int can_ifindex;
+ union {
+ struct {
+ __u64 name;
+ /* pgn:
+ * 8 bit: PS in PDU2 case, else 0
+ * 8 bit: PF
+ * 1 bit: DP
+ * 1 bit: reserved
+ */
+ __u32 pgn;
+ __u8 addr;
+ } j1939;
+ } can_addr;
+ }
+
+can_family & can_ifindex serve the same purpose as for other SocketCAN sockets.
+
+can_addr.j1939.pgn specifies the PGN (max 0x3ffff). Individual bits are
+specified above.
+
+can_addr.j1939.name contains the 64-bit J1939 NAME.
+
+can_addr.j1939.addr contains the address.
+
+The bind(2) system call assigns the local address, i.e. the source address when
+sending packages. If a PGN during bind(2) is set, it's used as a RX filter.
+I.e. only packets with a matching PGN are received. If an ADDR or NAME is set
+it is used as a receive filter, too. It will match the destination NAME or ADDR
+of the incoming packet. The NAME filter will work only if appropriate Address
+Claiming for this name was done on the CAN bus and registered/cached by the
+kernel.
+
+On the other hand connect(2) assigns the remote address, i.e. the destination
+address. The PGN from connect(2) is used as the default PGN when sending
+packets. If ADDR or NAME is set it will be used as the default destination ADDR
+or NAME. Further a set ADDR or NAME during connect(2) is used as a receive
+filter. It will match the source NAME or ADDR of the incoming packet.
+
+Both write(2) and send(2) will send a packet with local address from bind(2) and
+the remote address from connect(2). Use sendto(2) to overwrite the destination
+address.
+
+If can_addr.j1939.name is set (!= 0) the NAME is looked up by the kernel and
+the corresponding ADDR is used. If can_addr.j1939.name is not set (== 0),
+can_addr.j1939.addr is used.
+
+When creating a socket, reasonable defaults are set. Some options can be
+modified with setsockopt(2) & getsockopt(2).
+
+RX path related options:
+
+- SO_J1939_FILTER - configure array of filters
+- SO_J1939_PROMISC - disable filters set by bind(2) and connect(2)
+
+By default no broadcast packets can be send or received. To enable sending or
+receiving broadcast packets use the socket option SO_BROADCAST:
+
+.. code-block:: C
+
+ int value = 1;
+ setsockopt(sock, SOL_SOCKET, SO_BROADCAST, &value, sizeof(value));
+
+The following diagram illustrates the RX path:
+
+.. code::
+
+ +--------------------+
+ | incoming packet |
+ +--------------------+
+ |
+ V
+ +--------------------+
+ | SO_J1939_PROMISC? |
+ +--------------------+
+ | |
+ no | | yes
+ | |
+ .---------' `---------.
+ | |
+ +---------------------------+ |
+ | bind() + connect() + | |
+ | SOCK_BROADCAST filter | |
+ +---------------------------+ |
+ | |
+ |<---------------------'
+ V
+ +---------------------------+
+ | SO_J1939_FILTER |
+ +---------------------------+
+ |
+ V
+ +---------------------------+
+ | socket recv() |
+ +---------------------------+
+
+TX path related options:
+SO_J1939_SEND_PRIO - change default send priority for the socket
+
+Message Flags during send() and Related System Calls
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+send(2), sendto(2) and sendmsg(2) take a 'flags' argument. Currently
+supported flags are:
+
+* MSG_DONTWAIT, i.e. non-blocking operation.
+
+recvmsg(2)
+^^^^^^^^^
+
+In most cases recvmsg(2) is needed if you want to extract more information than
+recvfrom(2) can provide. For example package priority and timestamp. The
+Destination Address, name and packet priority (if applicable) are attached to
+the msghdr in the recvmsg(2) call. They can be extracted using cmsg(3) macros,
+with cmsg_level == SOL_J1939 && cmsg_type == SCM_J1939_DEST_ADDR,
+SCM_J1939_DEST_NAME or SCM_J1939_PRIO. The returned data is a uint8_t for
+priority and dst_addr, and uint64_t for dst_name.
+
+.. code-block:: C
+
+ uint8_t priority, dst_addr;
+ uint64_t dst_name;
+
+ for (cmsg = CMSG_FIRSTHDR(&msg); cmsg; cmsg = CMSG_NXTHDR(&msg, cmsg)) {
+ switch (cmsg->cmsg_level) {
+ case SOL_CAN_J1939:
+ if (cmsg->cmsg_type == SCM_J1939_DEST_ADDR)
+ dst_addr = *CMSG_DATA(cmsg);
+ else if (cmsg->cmsg_type == SCM_J1939_DEST_NAME)
+ memcpy(&dst_name, CMSG_DATA(cmsg), cmsg->cmsg_len - CMSG_LEN(0));
+ else if (cmsg->cmsg_type == SCM_J1939_PRIO)
+ priority = *CMSG_DATA(cmsg);
+ break;
+ }
+ }
+
+Dynamic Addressing
+------------------
+
+Distinction has to be made between using the claimed address and doing an
+address claim. To use an already claimed address, one has to fill in the
+j1939.name member and provide it to bind(2). If the name had claimed an address
+earlier, all further messages being sent will use that address. And the
+j1939.addr member will be ignored.
+
+An exception on this is PGN 0x0ee00. This is the "Address Claim/Cannot Claim
+Address" message and the kernel will use the j1939.addr member for that PGN if
+necessary.
+
+To claim an address following code example can be used:
+
+.. code-block:: C
+
+ struct sockaddr_can baddr = {
+ .can_family = AF_CAN,
+ .can_addr.j1939 = {
+ .name = name,
+ .addr = J1939_IDLE_ADDR,
+ .pgn = J1939_NO_PGN, /* to disable bind() rx filter for PGN */
+ },
+ .can_ifindex = if_nametoindex("can0"),
+ };
+
+ bind(sock, (struct sockaddr *)&baddr, sizeof(baddr));
+
+ /* for Address Claiming broadcast must be allowed */
+ int value = 1;
+ setsockopt(sock, SOL_SOCKET, SO_BROADCAST, &value, sizeof(value));
+
+ /* configured advanced RX filter with PGN needed for Address Claiming */
+ const struct j1939_filter filt[] = {
+ {
+ .pgn = J1939_PGN_ADDRESS_CLAIMED,
+ .pgn_mask = J1939_PGN_PDU1_MAX,
+ }, {
+ .pgn = J1939_PGN_ADDRESS_REQUEST,
+ .pgn_mask = J1939_PGN_PDU1_MAX,
+ }, {
+ .pgn = J1939_PGN_ADDRESS_COMMANDED,
+ .pgn_mask = J1939_PGN_MAX,
+ },
+ };
+
+ setsockopt(sock, SOL_CAN_J1939, SO_J1939_FILTER, &filt, sizeof(filt));
+
+ uint64_t dat = htole64(name);
+ const struct sockaddr_can saddr = {
+ .can_family = AF_CAN,
+ .can_addr.j1939 = {
+ .pgn = J1939_PGN_ADDRESS_CLAIMED,
+ .addr = J1939_NO_ADDR,
+ },
+ };
+
+ /* Afterwards do a sendto(2) with data set to the NAME (Little Endian). If the
+ * NAME provided, does not match the j1939.name provided to bind(2), EPROTO
+ * will be returned.
+ */
+ sendto(sock, dat, sizeof(dat), 0, (const struct sockaddr *)&saddr, sizeof(saddr));
+
+If no-one else contests the address claim within 250ms after transmission, the
+kernel marks the NAME-SA assignment as valid. The valid assignment will be kept
+among other valid NAME-SA assignments. From that point, any socket bound to the
+NAME can send packets.
+
+If another ECU claims the address, the kernel will mark the NAME-SA expired.
+No socket bound to the NAME can send packets (other than address claims). To
+claim another address, some socket bound to NAME, must bind(2) again, but with
+only j1939.addr changed to the new SA, and must then send a valid address claim
+packet. This restarts the state machine in the kernel (and any other
+participant on the bus) for this NAME.
+
+can-utils also include the jacd tool, so it can be used as code example or as
+default Address Claiming daemon.
+
+Send Examples
+-------------
+
+Static Addressing
+^^^^^^^^^^^^^^^^^
+
+This example will send a PGN (0x12300) from SA 0x20 to DA 0x30.
+
+Bind:
+
+.. code-block:: C
+
+ struct sockaddr_can baddr = {
+ .can_family = AF_CAN,
+ .can_addr.j1939 = {
+ .name = J1939_NO_NAME,
+ .addr = 0x20,
+ .pgn = J1939_NO_PGN,
+ },
+ .can_ifindex = if_nametoindex("can0"),
+ };
+
+ bind(sock, (struct sockaddr *)&baddr, sizeof(baddr));
+
+Now, the socket 'sock' is bound to the SA 0x20. Since no connect(2) was called,
+at this point we can use only sendto(2) or sendmsg(2).
+
+Send:
+
+.. code-block:: C
+
+ const struct sockaddr_can saddr = {
+ .can_family = AF_CAN,
+ .can_addr.j1939 = {
+ .name = J1939_NO_NAME;
+ .pgn = 0x30,
+ .addr = 0x12300,
+ },
+ };
+
+ sendto(sock, dat, sizeof(dat), 0, (const struct sockaddr *)&saddr, sizeof(saddr));
diff --git a/Documentation/networking/mac80211_hwsim/README b/Documentation/networking/mac80211_hwsim/README
deleted file mode 100644
index 3566a72..0000000
--- a/Documentation/networking/mac80211_hwsim/README
+++ /dev/null
@@ -1,68 +0,0 @@
-mac80211_hwsim - software simulator of 802.11 radio(s) for mac80211
-Copyright (c) 2008, Jouni Malinen <j@w1.fi>
-
-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.
-
-
-Introduction
-
-mac80211_hwsim is a Linux kernel module that can be used to simulate
-arbitrary number of IEEE 802.11 radios for mac80211. It can be used to
-test most of the mac80211 functionality and user space tools (e.g.,
-hostapd and wpa_supplicant) in a way that matches very closely with
-the normal case of using real WLAN hardware. From the mac80211 view
-point, mac80211_hwsim is yet another hardware driver, i.e., no changes
-to mac80211 are needed to use this testing tool.
-
-The main goal for mac80211_hwsim is to make it easier for developers
-to test their code and work with new features to mac80211, hostapd,
-and wpa_supplicant. The simulated radios do not have the limitations
-of real hardware, so it is easy to generate an arbitrary test setup
-and always reproduce the same setup for future tests. In addition,
-since all radio operation is simulated, any channel can be used in
-tests regardless of regulatory rules.
-
-mac80211_hwsim kernel module has a parameter 'radios' that can be used
-to select how many radios are simulated (default 2). This allows
-configuration of both very simply setups (e.g., just a single access
-point and a station) or large scale tests (multiple access points with
-hundreds of stations).
-
-mac80211_hwsim works by tracking the current channel of each virtual
-radio and copying all transmitted frames to all other radios that are
-currently enabled and on the same channel as the transmitting
-radio. Software encryption in mac80211 is used so that the frames are
-actually encrypted over the virtual air interface to allow more
-complete testing of encryption.
-
-A global monitoring netdev, hwsim#, is created independent of
-mac80211. This interface can be used to monitor all transmitted frames
-regardless of channel.
-
-
-Simple example
-
-This example shows how to use mac80211_hwsim to simulate two radios:
-one to act as an access point and the other as a station that
-associates with the AP. hostapd and wpa_supplicant are used to take
-care of WPA2-PSK authentication. In addition, hostapd is also
-processing access point side of association.
-
-
-# Build mac80211_hwsim as part of kernel configuration
-
-# Load the module
-modprobe mac80211_hwsim
-
-# Run hostapd (AP) for wlan0
-hostapd hostapd.conf
-
-# Run wpa_supplicant (station) for wlan1
-wpa_supplicant -Dnl80211 -iwlan1 -c wpa_supplicant.conf
-
-
-More test cases are available in hostap.git:
-git://w1.fi/srv/git/hostap.git and mac80211_hwsim/tests subdirectory
-(http://w1.fi/gitweb/gitweb.cgi?p=hostap.git;a=tree;f=mac80211_hwsim/tests)
diff --git a/Documentation/networking/mac80211_hwsim/mac80211_hwsim.rst b/Documentation/networking/mac80211_hwsim/mac80211_hwsim.rst
new file mode 100644
index 0000000..d2266ce
--- /dev/null
+++ b/Documentation/networking/mac80211_hwsim/mac80211_hwsim.rst
@@ -0,0 +1,80 @@
+:orphan:
+
+.. SPDX-License-Identifier: GPL-2.0
+.. include:: <isonum.txt>
+
+===================================================================
+mac80211_hwsim - software simulator of 802.11 radio(s) for mac80211
+===================================================================
+
+:Copyright: |copy| 2008, Jouni Malinen <j@w1.fi>
+
+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.
+
+
+Introduction
+============
+
+mac80211_hwsim is a Linux kernel module that can be used to simulate
+arbitrary number of IEEE 802.11 radios for mac80211. It can be used to
+test most of the mac80211 functionality and user space tools (e.g.,
+hostapd and wpa_supplicant) in a way that matches very closely with
+the normal case of using real WLAN hardware. From the mac80211 view
+point, mac80211_hwsim is yet another hardware driver, i.e., no changes
+to mac80211 are needed to use this testing tool.
+
+The main goal for mac80211_hwsim is to make it easier for developers
+to test their code and work with new features to mac80211, hostapd,
+and wpa_supplicant. The simulated radios do not have the limitations
+of real hardware, so it is easy to generate an arbitrary test setup
+and always reproduce the same setup for future tests. In addition,
+since all radio operation is simulated, any channel can be used in
+tests regardless of regulatory rules.
+
+mac80211_hwsim kernel module has a parameter 'radios' that can be used
+to select how many radios are simulated (default 2). This allows
+configuration of both very simply setups (e.g., just a single access
+point and a station) or large scale tests (multiple access points with
+hundreds of stations).
+
+mac80211_hwsim works by tracking the current channel of each virtual
+radio and copying all transmitted frames to all other radios that are
+currently enabled and on the same channel as the transmitting
+radio. Software encryption in mac80211 is used so that the frames are
+actually encrypted over the virtual air interface to allow more
+complete testing of encryption.
+
+A global monitoring netdev, hwsim#, is created independent of
+mac80211. This interface can be used to monitor all transmitted frames
+regardless of channel.
+
+
+Simple example
+==============
+
+This example shows how to use mac80211_hwsim to simulate two radios:
+one to act as an access point and the other as a station that
+associates with the AP. hostapd and wpa_supplicant are used to take
+care of WPA2-PSK authentication. In addition, hostapd is also
+processing access point side of association.
+
+::
+
+
+ # Build mac80211_hwsim as part of kernel configuration
+
+ # Load the module
+ modprobe mac80211_hwsim
+
+ # Run hostapd (AP) for wlan0
+ hostapd hostapd.conf
+
+ # Run wpa_supplicant (station) for wlan1
+ wpa_supplicant -Dnl80211 -iwlan1 -c wpa_supplicant.conf
+
+
+More test cases are available in hostap.git:
+git://w1.fi/srv/git/hostap.git and mac80211_hwsim/tests subdirectory
+(http://w1.fi/gitweb/gitweb.cgi?p=hostap.git;a=tree;f=mac80211_hwsim/tests)
diff --git a/Documentation/networking/sfp-phylink.rst b/Documentation/networking/sfp-phylink.rst
index 91446b4..a5e00a1 100644
--- a/Documentation/networking/sfp-phylink.rst
+++ b/Documentation/networking/sfp-phylink.rst
@@ -8,7 +8,8 @@
========
phylink is a mechanism to support hot-pluggable networking modules
-without needing to re-initialise the adapter on hot-plug events.
+directly connected to a MAC without needing to re-initialise the
+adapter on hot-plug events.
phylink supports conventional phylib-based setups, fixed link setups
and SFP (Small Formfactor Pluggable) modules at present.
diff --git a/Documentation/nios2/README b/Documentation/nios2/README
deleted file mode 100644
index 054a67d..0000000
--- a/Documentation/nios2/README
+++ /dev/null
@@ -1,23 +0,0 @@
-Linux on the Nios II architecture
-=================================
-
-This is a port of Linux to Nios II (nios2) processor.
-
-In order to compile for Nios II, you need a version of GCC with support for the generic
-system call ABI. Please see this link for more information on how compiling and booting
-software for the Nios II platform:
-http://www.rocketboards.org/foswiki/Documentation/NiosIILinuxUserManual
-
-For reference, please see the following link:
-http://www.altera.com/literature/lit-nio2.jsp
-
-What is Nios II?
-================
-Nios II is a 32-bit embedded-processor architecture designed specifically for the
-Altera family of FPGAs. In order to support Linux, Nios II needs to be configured
-with MMU and hardware multiplier enabled.
-
-Nios II ABI
-===========
-Please refer to chapter "Application Binary Interface" in Nios II Processor Reference
-Handbook.
diff --git a/Documentation/nios2/nios2.rst b/Documentation/nios2/nios2.rst
new file mode 100644
index 0000000..43da3f7
--- /dev/null
+++ b/Documentation/nios2/nios2.rst
@@ -0,0 +1,24 @@
+=================================
+Linux on the Nios II architecture
+=================================
+
+This is a port of Linux to Nios II (nios2) processor.
+
+In order to compile for Nios II, you need a version of GCC with support for the generic
+system call ABI. Please see this link for more information on how compiling and booting
+software for the Nios II platform:
+http://www.rocketboards.org/foswiki/Documentation/NiosIILinuxUserManual
+
+For reference, please see the following link:
+http://www.altera.com/literature/lit-nio2.jsp
+
+What is Nios II?
+================
+Nios II is a 32-bit embedded-processor architecture designed specifically for the
+Altera family of FPGAs. In order to support Linux, Nios II needs to be configured
+with MMU and hardware multiplier enabled.
+
+Nios II ABI
+===========
+Please refer to chapter "Application Binary Interface" in Nios II Processor Reference
+Handbook.
diff --git a/Documentation/openrisc/README b/Documentation/openrisc/README
deleted file mode 100644
index 777a893..0000000
--- a/Documentation/openrisc/README
+++ /dev/null
@@ -1,110 +0,0 @@
-OpenRISC Linux
-==============
-
-This is a port of Linux to the OpenRISC class of microprocessors; the initial
-target architecture, specifically, is the 32-bit OpenRISC 1000 family (or1k).
-
-For information about OpenRISC processors and ongoing development:
-
- website http://openrisc.io
- email openrisc@lists.librecores.org
-
----------------------------------------------------------------------
-
-Build instructions for OpenRISC toolchain and Linux
-===================================================
-
-In order to build and run Linux for OpenRISC, you'll need at least a basic
-toolchain and, perhaps, the architectural simulator. Steps to get these bits
-in place are outlined here.
-
-1) Toolchain
-
-Toolchain binaries can be obtained from openrisc.io or our github releases page.
-Instructions for building the different toolchains can be found on openrisc.io
-or Stafford's toolchain build and release scripts.
-
- binaries https://github.com/openrisc/or1k-gcc/releases
- toolchains https://openrisc.io/software
- building https://github.com/stffrdhrn/or1k-toolchain-build
-
-2) Building
-
-Build the Linux kernel as usual
-
- make ARCH=openrisc defconfig
- make ARCH=openrisc
-
-3) Running on FPGA (optional)
-
-The OpenRISC community typically uses FuseSoC to manage building and programming
-an SoC into an FPGA. The below is an example of programming a De0 Nano
-development board with the OpenRISC SoC. During the build FPGA RTL is code
-downloaded from the FuseSoC IP cores repository and built using the FPGA vendor
-tools. Binaries are loaded onto the board with openocd.
-
- git clone https://github.com/olofk/fusesoc
- cd fusesoc
- sudo pip install -e .
-
- fusesoc init
- fusesoc build de0_nano
- fusesoc pgm de0_nano
-
- openocd -f interface/altera-usb-blaster.cfg \
- -f board/or1k_generic.cfg
-
- telnet localhost 4444
- > init
- > halt; load_image vmlinux ; reset
-
-4) Running on a Simulator (optional)
-
-QEMU is a processor emulator which we recommend for simulating the OpenRISC
-platform. Please follow the OpenRISC instructions on the QEMU website to get
-Linux running on QEMU. You can build QEMU yourself, but your Linux distribution
-likely provides binary packages to support OpenRISC.
-
- qemu openrisc https://wiki.qemu.org/Documentation/Platforms/OpenRISC
-
----------------------------------------------------------------------
-
-Terminology
-===========
-
-In the code, the following particles are used on symbols to limit the scope
-to more or less specific processor implementations:
-
-openrisc: the OpenRISC class of processors
-or1k: the OpenRISC 1000 family of processors
-or1200: the OpenRISC 1200 processor
-
----------------------------------------------------------------------
-
-History
-========
-
-18. 11. 2003 Matjaz Breskvar (phoenix@bsemi.com)
- initial port of linux to OpenRISC/or32 architecture.
- all the core stuff is implemented and seams usable.
-
-08. 12. 2003 Matjaz Breskvar (phoenix@bsemi.com)
- complete change of TLB miss handling.
- rewrite of exceptions handling.
- fully functional sash-3.6 in default initrd.
- a much improved version with changes all around.
-
-10. 04. 2004 Matjaz Breskvar (phoenix@bsemi.com)
- alot of bugfixes all over.
- ethernet support, functional http and telnet servers.
- running many standard linux apps.
-
-26. 06. 2004 Matjaz Breskvar (phoenix@bsemi.com)
- port to 2.6.x
-
-30. 11. 2004 Matjaz Breskvar (phoenix@bsemi.com)
- lots of bugfixes and enhancments.
- added opencores framebuffer driver.
-
-09. 10. 2010 Jonas Bonn (jonas@southpole.se)
- major rewrite to bring up to par with upstream Linux 2.6.36
diff --git a/Documentation/openrisc/TODO b/Documentation/openrisc/TODO
deleted file mode 100644
index c43d4e1..0000000
--- a/Documentation/openrisc/TODO
+++ /dev/null
@@ -1,12 +0,0 @@
-The OpenRISC Linux port is fully functional and has been tracking upstream
-since 2.6.35. There are, however, remaining items to be completed within
-the coming months. Here's a list of known-to-be-less-than-stellar items
-that are due for investigation shortly, i.e. our TODO list:
-
--- Implement the rest of the DMA API... dma_map_sg, etc.
-
--- Finish the renaming cleanup... there are references to or32 in the code
- which was an older name for the architecture. The name we've settled on is
- or1k and this change is slowly trickling through the stack. For the time
- being, or32 is equivalent to or1k.
-
diff --git a/Documentation/openrisc/index.rst b/Documentation/openrisc/index.rst
new file mode 100644
index 0000000..748b3ee
--- /dev/null
+++ b/Documentation/openrisc/index.rst
@@ -0,0 +1,18 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+=====================
+OpenRISC Architecture
+=====================
+
+.. toctree::
+ :maxdepth: 2
+
+ openrisc_port
+ todo
+
+.. only:: subproject and html
+
+ Indices
+ =======
+
+ * :ref:`genindex`
diff --git a/Documentation/openrisc/openrisc_port.rst b/Documentation/openrisc/openrisc_port.rst
new file mode 100644
index 0000000..a18747a
--- /dev/null
+++ b/Documentation/openrisc/openrisc_port.rst
@@ -0,0 +1,121 @@
+==============
+OpenRISC Linux
+==============
+
+This is a port of Linux to the OpenRISC class of microprocessors; the initial
+target architecture, specifically, is the 32-bit OpenRISC 1000 family (or1k).
+
+For information about OpenRISC processors and ongoing development:
+
+ ======= =============================
+ website http://openrisc.io
+ email openrisc@lists.librecores.org
+ ======= =============================
+
+---------------------------------------------------------------------
+
+Build instructions for OpenRISC toolchain and Linux
+===================================================
+
+In order to build and run Linux for OpenRISC, you'll need at least a basic
+toolchain and, perhaps, the architectural simulator. Steps to get these bits
+in place are outlined here.
+
+1) Toolchain
+
+Toolchain binaries can be obtained from openrisc.io or our github releases page.
+Instructions for building the different toolchains can be found on openrisc.io
+or Stafford's toolchain build and release scripts.
+
+ ========== =================================================
+ binaries https://github.com/openrisc/or1k-gcc/releases
+ toolchains https://openrisc.io/software
+ building https://github.com/stffrdhrn/or1k-toolchain-build
+ ========== =================================================
+
+2) Building
+
+Build the Linux kernel as usual::
+
+ make ARCH=openrisc defconfig
+ make ARCH=openrisc
+
+3) Running on FPGA (optional)
+
+The OpenRISC community typically uses FuseSoC to manage building and programming
+an SoC into an FPGA. The below is an example of programming a De0 Nano
+development board with the OpenRISC SoC. During the build FPGA RTL is code
+downloaded from the FuseSoC IP cores repository and built using the FPGA vendor
+tools. Binaries are loaded onto the board with openocd.
+
+::
+
+ git clone https://github.com/olofk/fusesoc
+ cd fusesoc
+ sudo pip install -e .
+
+ fusesoc init
+ fusesoc build de0_nano
+ fusesoc pgm de0_nano
+
+ openocd -f interface/altera-usb-blaster.cfg \
+ -f board/or1k_generic.cfg
+
+ telnet localhost 4444
+ > init
+ > halt; load_image vmlinux ; reset
+
+4) Running on a Simulator (optional)
+
+QEMU is a processor emulator which we recommend for simulating the OpenRISC
+platform. Please follow the OpenRISC instructions on the QEMU website to get
+Linux running on QEMU. You can build QEMU yourself, but your Linux distribution
+likely provides binary packages to support OpenRISC.
+
+ ============= ======================================================
+ qemu openrisc https://wiki.qemu.org/Documentation/Platforms/OpenRISC
+ ============= ======================================================
+
+---------------------------------------------------------------------
+
+Terminology
+===========
+
+In the code, the following particles are used on symbols to limit the scope
+to more or less specific processor implementations:
+
+========= =======================================
+openrisc: the OpenRISC class of processors
+or1k: the OpenRISC 1000 family of processors
+or1200: the OpenRISC 1200 processor
+========= =======================================
+
+---------------------------------------------------------------------
+
+History
+========
+
+18-11-2003 Matjaz Breskvar (phoenix@bsemi.com)
+ initial port of linux to OpenRISC/or32 architecture.
+ all the core stuff is implemented and seams usable.
+
+08-12-2003 Matjaz Breskvar (phoenix@bsemi.com)
+ complete change of TLB miss handling.
+ rewrite of exceptions handling.
+ fully functional sash-3.6 in default initrd.
+ a much improved version with changes all around.
+
+10-04-2004 Matjaz Breskvar (phoenix@bsemi.com)
+ alot of bugfixes all over.
+ ethernet support, functional http and telnet servers.
+ running many standard linux apps.
+
+26-06-2004 Matjaz Breskvar (phoenix@bsemi.com)
+ port to 2.6.x
+
+30-11-2004 Matjaz Breskvar (phoenix@bsemi.com)
+ lots of bugfixes and enhancments.
+ added opencores framebuffer driver.
+
+09-10-2010 Jonas Bonn (jonas@southpole.se)
+ major rewrite to bring up to par with upstream Linux 2.6.36
diff --git a/Documentation/openrisc/todo.rst b/Documentation/openrisc/todo.rst
new file mode 100644
index 0000000..420b18b
--- /dev/null
+++ b/Documentation/openrisc/todo.rst
@@ -0,0 +1,15 @@
+====
+TODO
+====
+
+The OpenRISC Linux port is fully functional and has been tracking upstream
+since 2.6.35. There are, however, remaining items to be completed within
+the coming months. Here's a list of known-to-be-less-than-stellar items
+that are due for investigation shortly, i.e. our TODO list:
+
+- Implement the rest of the DMA API... dma_map_sg, etc.
+
+- Finish the renaming cleanup... there are references to or32 in the code
+ which was an older name for the architecture. The name we've settled on is
+ or1k and this change is slowly trickling through the stack. For the time
+ being, or32 is equivalent to or1k.
diff --git a/Documentation/packing.txt b/Documentation/packing.txt
deleted file mode 100644
index f830c98..0000000
--- a/Documentation/packing.txt
+++ /dev/null
@@ -1,149 +0,0 @@
-================================================
-Generic bitfield packing and unpacking functions
-================================================
-
-Problem statement
------------------
-
-When working with hardware, one has to choose between several approaches of
-interfacing with it.
-One can memory-map a pointer to a carefully crafted struct over the hardware
-device's memory region, and access its fields as struct members (potentially
-declared as bitfields). But writing code this way would make it less portable,
-due to potential endianness mismatches between the CPU and the hardware device.
-Additionally, one has to pay close attention when translating register
-definitions from the hardware documentation into bit field indices for the
-structs. Also, some hardware (typically networking equipment) tends to group
-its register fields in ways that violate any reasonable word boundaries
-(sometimes even 64 bit ones). This creates the inconvenience of having to
-define "high" and "low" portions of register fields within the struct.
-A more robust alternative to struct field definitions would be to extract the
-required fields by shifting the appropriate number of bits. But this would
-still not protect from endianness mismatches, except if all memory accesses
-were performed byte-by-byte. Also the code can easily get cluttered, and the
-high-level idea might get lost among the many bit shifts required.
-Many drivers take the bit-shifting approach and then attempt to reduce the
-clutter with tailored macros, but more often than not these macros take
-shortcuts that still prevent the code from being truly portable.
-
-The solution
-------------
-
-This API deals with 2 basic operations:
- - Packing a CPU-usable number into a memory buffer (with hardware
- constraints/quirks)
- - Unpacking a memory buffer (which has hardware constraints/quirks)
- into a CPU-usable number.
-
-The API offers an abstraction over said hardware constraints and quirks,
-over CPU endianness and therefore between possible mismatches between
-the two.
-
-The basic unit of these API functions is the u64. From the CPU's
-perspective, bit 63 always means bit offset 7 of byte 7, albeit only
-logically. The question is: where do we lay this bit out in memory?
-
-The following examples cover the memory layout of a packed u64 field.
-The byte offsets in the packed buffer are always implicitly 0, 1, ... 7.
-What the examples show is where the logical bytes and bits sit.
-
-1. Normally (no quirks), we would do it like this:
-
-63 62 61 60 59 58 57 56 55 54 53 52 51 50 49 48 47 46 45 44 43 42 41 40 39 38 37 36 35 34 33 32
-7 6 5 4
-31 30 29 28 27 26 25 24 23 22 21 20 19 18 17 16 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0
-3 2 1 0
-
-That is, the MSByte (7) of the CPU-usable u64 sits at memory offset 0, and the
-LSByte (0) of the u64 sits at memory offset 7.
-This corresponds to what most folks would regard to as "big endian", where
-bit i corresponds to the number 2^i. This is also referred to in the code
-comments as "logical" notation.
-
-
-2. If QUIRK_MSB_ON_THE_RIGHT is set, we do it like this:
-
-56 57 58 59 60 61 62 63 48 49 50 51 52 53 54 55 40 41 42 43 44 45 46 47 32 33 34 35 36 37 38 39
-7 6 5 4
-24 25 26 27 28 29 30 31 16 17 18 19 20 21 22 23 8 9 10 11 12 13 14 15 0 1 2 3 4 5 6 7
-3 2 1 0
-
-That is, QUIRK_MSB_ON_THE_RIGHT does not affect byte positioning, but
-inverts bit offsets inside a byte.
-
-
-3. If QUIRK_LITTLE_ENDIAN is set, we do it like this:
-
-39 38 37 36 35 34 33 32 47 46 45 44 43 42 41 40 55 54 53 52 51 50 49 48 63 62 61 60 59 58 57 56
-4 5 6 7
-7 6 5 4 3 2 1 0 15 14 13 12 11 10 9 8 23 22 21 20 19 18 17 16 31 30 29 28 27 26 25 24
-0 1 2 3
-
-Therefore, QUIRK_LITTLE_ENDIAN means that inside the memory region, every
-byte from each 4-byte word is placed at its mirrored position compared to
-the boundary of that word.
-
-4. If QUIRK_MSB_ON_THE_RIGHT and QUIRK_LITTLE_ENDIAN are both set, we do it
- like this:
-
-32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63
-4 5 6 7
-0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31
-0 1 2 3
-
-
-5. If just QUIRK_LSW32_IS_FIRST is set, we do it like this:
-
-31 30 29 28 27 26 25 24 23 22 21 20 19 18 17 16 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0
-3 2 1 0
-63 62 61 60 59 58 57 56 55 54 53 52 51 50 49 48 47 46 45 44 43 42 41 40 39 38 37 36 35 34 33 32
-7 6 5 4
-
-In this case the 8 byte memory region is interpreted as follows: first
-4 bytes correspond to the least significant 4-byte word, next 4 bytes to
-the more significant 4-byte word.
-
-
-6. If QUIRK_LSW32_IS_FIRST and QUIRK_MSB_ON_THE_RIGHT are set, we do it like
- this:
-
-24 25 26 27 28 29 30 31 16 17 18 19 20 21 22 23 8 9 10 11 12 13 14 15 0 1 2 3 4 5 6 7
-3 2 1 0
-56 57 58 59 60 61 62 63 48 49 50 51 52 53 54 55 40 41 42 43 44 45 46 47 32 33 34 35 36 37 38 39
-7 6 5 4
-
-
-7. If QUIRK_LSW32_IS_FIRST and QUIRK_LITTLE_ENDIAN are set, it looks like
- this:
-
-7 6 5 4 3 2 1 0 15 14 13 12 11 10 9 8 23 22 21 20 19 18 17 16 31 30 29 28 27 26 25 24
-0 1 2 3
-39 38 37 36 35 34 33 32 47 46 45 44 43 42 41 40 55 54 53 52 51 50 49 48 63 62 61 60 59 58 57 56
-4 5 6 7
-
-
-8. If QUIRK_LSW32_IS_FIRST, QUIRK_LITTLE_ENDIAN and QUIRK_MSB_ON_THE_RIGHT
- are set, it looks like this:
-
-0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31
-0 1 2 3
-32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63
-4 5 6 7
-
-
-We always think of our offsets as if there were no quirk, and we translate
-them afterwards, before accessing the memory region.
-
-Intended use
-------------
-
-Drivers that opt to use this API first need to identify which of the above 3
-quirk combinations (for a total of 8) match what the hardware documentation
-describes. Then they should wrap the packing() function, creating a new
-xxx_packing() that calls it using the proper QUIRK_* one-hot bits set.
-
-The packing() function returns an int-encoded error code, which protects the
-programmer against incorrect API use. The errors are not expected to occur
-durring runtime, therefore it is reasonable for xxx_packing() to return void
-and simply swallow those errors. Optionally it can dump stack or print the
-error description.
diff --git a/Documentation/padata.txt b/Documentation/padata.txt
index b103d0c..b37ba1e 100644
--- a/Documentation/padata.txt
+++ b/Documentation/padata.txt
@@ -16,10 +16,12 @@
#include <linux/padata.h>
- struct padata_instance *padata_alloc(struct workqueue_struct *wq,
+ struct padata_instance *padata_alloc(const char *name,
const struct cpumask *pcpumask,
const struct cpumask *cbcpumask);
+'name' simply identifies the instance.
+
The pcpumask describes which processors will be used to execute work
submitted to this instance in parallel. The cbcpumask defines which
processors are allowed to be used as the serialization callback processor.
@@ -128,8 +130,7 @@
Each task submitted to padata_do_parallel() will, in turn, be passed to
exactly one call to the above-mentioned parallel() function, on one CPU, so
-true parallelism is achieved by submitting multiple tasks. Despite the
-fact that the workqueue is used to make these calls, parallel() is run with
+true parallelism is achieved by submitting multiple tasks. parallel() runs with
software interrupts disabled and thus cannot sleep. The parallel()
function gets the padata_priv structure pointer as its lone parameter;
information about the actual work to be done is probably obtained by using
@@ -148,7 +149,7 @@
At some point in the future, padata_do_serial() will trigger a call to the
serial() function in the padata_priv structure. That call will happen on
the CPU requested in the initial call to padata_do_parallel(); it, too, is
-done through the workqueue, but with local software interrupts disabled.
+run with local software interrupts disabled.
Note that this call may be deferred for a while since the padata code takes
pains to ensure that tasks are completed in the order in which they were
submitted.
@@ -159,5 +160,4 @@
void padata_free(struct padata_instance *pinst);
This function will busy-wait while any remaining tasks are completed, so it
-might be best not to call it while there is work outstanding. Shutting
-down the workqueue, if necessary, should be done separately.
+might be best not to call it while there is work outstanding.
diff --git a/Documentation/parisc/debugging b/Documentation/parisc/debugging
deleted file mode 100644
index 7d75223..0000000
--- a/Documentation/parisc/debugging
+++ /dev/null
@@ -1,39 +0,0 @@
-okay, here are some hints for debugging the lower-level parts of
-linux/parisc.
-
-
-1. Absolute addresses
-
-A lot of the assembly code currently runs in real mode, which means
-absolute addresses are used instead of virtual addresses as in the
-rest of the kernel. To translate an absolute address to a virtual
-address you can lookup in System.map, add __PAGE_OFFSET (0x10000000
-currently).
-
-
-2. HPMCs
-
-When real-mode code tries to access non-existent memory, you'll get
-an HPMC instead of a kernel oops. To debug an HPMC, try to find
-the System Responder/Requestor addresses. The System Requestor
-address should match (one of the) processor HPAs (high addresses in
-the I/O range); the System Responder address is the address real-mode
-code tried to access.
-
-Typical values for the System Responder address are addresses larger
-than __PAGE_OFFSET (0x10000000) which mean a virtual address didn't
-get translated to a physical address before real-mode code tried to
-access it.
-
-
-3. Q bit fun
-
-Certain, very critical code has to clear the Q bit in the PSW. What
-happens when the Q bit is cleared is the CPU does not update the
-registers interruption handlers read to find out where the machine
-was interrupted - so if you get an interruption between the instruction
-that clears the Q bit and the RFI that sets it again you don't know
-where exactly it happened. If you're lucky the IAOQ will point to the
-instruction that cleared the Q bit, if you're not it points anywhere
-at all. Usually Q bit problems will show themselves in unexplainable
-system hangs or running off the end of physical memory.
diff --git a/Documentation/parisc/debugging.rst b/Documentation/parisc/debugging.rst
new file mode 100644
index 0000000..de1b604
--- /dev/null
+++ b/Documentation/parisc/debugging.rst
@@ -0,0 +1,46 @@
+=================
+PA-RISC Debugging
+=================
+
+okay, here are some hints for debugging the lower-level parts of
+linux/parisc.
+
+
+1. Absolute addresses
+=====================
+
+A lot of the assembly code currently runs in real mode, which means
+absolute addresses are used instead of virtual addresses as in the
+rest of the kernel. To translate an absolute address to a virtual
+address you can lookup in System.map, add __PAGE_OFFSET (0x10000000
+currently).
+
+
+2. HPMCs
+========
+
+When real-mode code tries to access non-existent memory, you'll get
+an HPMC instead of a kernel oops. To debug an HPMC, try to find
+the System Responder/Requestor addresses. The System Requestor
+address should match (one of the) processor HPAs (high addresses in
+the I/O range); the System Responder address is the address real-mode
+code tried to access.
+
+Typical values for the System Responder address are addresses larger
+than __PAGE_OFFSET (0x10000000) which mean a virtual address didn't
+get translated to a physical address before real-mode code tried to
+access it.
+
+
+3. Q bit fun
+============
+
+Certain, very critical code has to clear the Q bit in the PSW. What
+happens when the Q bit is cleared is the CPU does not update the
+registers interruption handlers read to find out where the machine
+was interrupted - so if you get an interruption between the instruction
+that clears the Q bit and the RFI that sets it again you don't know
+where exactly it happened. If you're lucky the IAOQ will point to the
+instruction that cleared the Q bit, if you're not it points anywhere
+at all. Usually Q bit problems will show themselves in unexplainable
+system hangs or running off the end of physical memory.
diff --git a/Documentation/parisc/index.rst b/Documentation/parisc/index.rst
new file mode 100644
index 0000000..aa3ee04
--- /dev/null
+++ b/Documentation/parisc/index.rst
@@ -0,0 +1,18 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+====================
+PA-RISC Architecture
+====================
+
+.. toctree::
+ :maxdepth: 2
+
+ debugging
+ registers
+
+.. only:: subproject and html
+
+ Indices
+ =======
+
+ * :ref:`genindex`
diff --git a/Documentation/parisc/registers b/Documentation/parisc/registers
deleted file mode 100644
index 10c7d17..0000000
--- a/Documentation/parisc/registers
+++ /dev/null
@@ -1,129 +0,0 @@
-Register Usage for Linux/PA-RISC
-
-[ an asterisk is used for planned usage which is currently unimplemented ]
-
- General Registers as specified by ABI
-
- Control Registers
-
-CR 0 (Recovery Counter) used for ptrace
-CR 1-CR 7(undefined) unused
-CR 8 (Protection ID) per-process value*
-CR 9, 12, 13 (PIDS) unused
-CR10 (CCR) lazy FPU saving*
-CR11 as specified by ABI (SAR)
-CR14 (interruption vector) initialized to fault_vector
-CR15 (EIEM) initialized to all ones*
-CR16 (Interval Timer) read for cycle count/write starts Interval Tmr
-CR17-CR22 interruption parameters
-CR19 Interrupt Instruction Register
-CR20 Interrupt Space Register
-CR21 Interrupt Offset Register
-CR22 Interrupt PSW
-CR23 (EIRR) read for pending interrupts/write clears bits
-CR24 (TR 0) Kernel Space Page Directory Pointer
-CR25 (TR 1) User Space Page Directory Pointer
-CR26 (TR 2) not used
-CR27 (TR 3) Thread descriptor pointer
-CR28 (TR 4) not used
-CR29 (TR 5) not used
-CR30 (TR 6) current / 0
-CR31 (TR 7) Temporary register, used in various places
-
- Space Registers (kernel mode)
-
-SR0 temporary space register
-SR4-SR7 set to 0
-SR1 temporary space register
-SR2 kernel should not clobber this
-SR3 used for userspace accesses (current process)
-
- Space Registers (user mode)
-
-SR0 temporary space register
-SR1 temporary space register
-SR2 holds space of linux gateway page
-SR3 holds user address space value while in kernel
-SR4-SR7 Defines short address space for user/kernel
-
-
- Processor Status Word
-
-W (64-bit addresses) 0
-E (Little-endian) 0
-S (Secure Interval Timer) 0
-T (Taken Branch Trap) 0
-H (Higher-privilege trap) 0
-L (Lower-privilege trap) 0
-N (Nullify next instruction) used by C code
-X (Data memory break disable) 0
-B (Taken Branch) used by C code
-C (code address translation) 1, 0 while executing real-mode code
-V (divide step correction) used by C code
-M (HPMC mask) 0, 1 while executing HPMC handler*
-C/B (carry/borrow bits) used by C code
-O (ordered references) 1*
-F (performance monitor) 0
-R (Recovery Counter trap) 0
-Q (collect interruption state) 1 (0 in code directly preceding an rfi)
-P (Protection Identifiers) 1*
-D (Data address translation) 1, 0 while executing real-mode code
-I (external interrupt mask) used by cli()/sti() macros
-
- "Invisible" Registers
-
-PSW default W value 0
-PSW default E value 0
-Shadow Registers used by interruption handler code
-TOC enable bit 1
-
-=========================================================================
-
-The PA-RISC architecture defines 7 registers as "shadow registers".
-Those are used in RETURN FROM INTERRUPTION AND RESTORE instruction to reduce
-the state save and restore time by eliminating the need for general register
-(GR) saves and restores in interruption handlers.
-Shadow registers are the GRs 1, 8, 9, 16, 17, 24, and 25.
-
-=========================================================================
-Register usage notes, originally from John Marvin, with some additional
-notes from Randolph Chung.
-
-For the general registers:
-
-r1,r2,r19-r26,r28,r29 & r31 can be used without saving them first. And of
-course, you need to save them if you care about them, before calling
-another procedure. Some of the above registers do have special meanings
-that you should be aware of:
-
- r1: The addil instruction is hardwired to place its result in r1,
- so if you use that instruction be aware of that.
-
- r2: This is the return pointer. In general you don't want to
- use this, since you need the pointer to get back to your
- caller. However, it is grouped with this set of registers
- since the caller can't rely on the value being the same
- when you return, i.e. you can copy r2 to another register
- and return through that register after trashing r2, and
- that should not cause a problem for the calling routine.
-
- r19-r22: these are generally regarded as temporary registers.
- Note that in 64 bit they are arg7-arg4.
-
- r23-r26: these are arg3-arg0, i.e. you can use them if you
- don't care about the values that were passed in anymore.
-
- r28,r29: are ret0 and ret1. They are what you pass return values
- in. r28 is the primary return. When returning small structures
- r29 may also be used to pass data back to the caller.
-
- r30: stack pointer
-
- r31: the ble instruction puts the return pointer in here.
-
-
-r3-r18,r27,r30 need to be saved and restored. r3-r18 are just
- general purpose registers. r27 is the data pointer, and is
- used to make references to global variables easier. r30 is
- the stack pointer.
-
diff --git a/Documentation/parisc/registers.rst b/Documentation/parisc/registers.rst
new file mode 100644
index 0000000..59c8ecf
--- /dev/null
+++ b/Documentation/parisc/registers.rst
@@ -0,0 +1,154 @@
+================================
+Register Usage for Linux/PA-RISC
+================================
+
+[ an asterisk is used for planned usage which is currently unimplemented ]
+
+General Registers as specified by ABI
+=====================================
+
+Control Registers
+-----------------
+
+=============================== ===============================================
+CR 0 (Recovery Counter) used for ptrace
+CR 1-CR 7(undefined) unused
+CR 8 (Protection ID) per-process value*
+CR 9, 12, 13 (PIDS) unused
+CR10 (CCR) lazy FPU saving*
+CR11 as specified by ABI (SAR)
+CR14 (interruption vector) initialized to fault_vector
+CR15 (EIEM) initialized to all ones*
+CR16 (Interval Timer) read for cycle count/write starts Interval Tmr
+CR17-CR22 interruption parameters
+CR19 Interrupt Instruction Register
+CR20 Interrupt Space Register
+CR21 Interrupt Offset Register
+CR22 Interrupt PSW
+CR23 (EIRR) read for pending interrupts/write clears bits
+CR24 (TR 0) Kernel Space Page Directory Pointer
+CR25 (TR 1) User Space Page Directory Pointer
+CR26 (TR 2) not used
+CR27 (TR 3) Thread descriptor pointer
+CR28 (TR 4) not used
+CR29 (TR 5) not used
+CR30 (TR 6) current / 0
+CR31 (TR 7) Temporary register, used in various places
+=============================== ===============================================
+
+Space Registers (kernel mode)
+-----------------------------
+
+=============================== ===============================================
+SR0 temporary space register
+SR4-SR7 set to 0
+SR1 temporary space register
+SR2 kernel should not clobber this
+SR3 used for userspace accesses (current process)
+=============================== ===============================================
+
+Space Registers (user mode)
+---------------------------
+
+=============================== ===============================================
+SR0 temporary space register
+SR1 temporary space register
+SR2 holds space of linux gateway page
+SR3 holds user address space value while in kernel
+SR4-SR7 Defines short address space for user/kernel
+=============================== ===============================================
+
+
+Processor Status Word
+---------------------
+
+=============================== ===============================================
+W (64-bit addresses) 0
+E (Little-endian) 0
+S (Secure Interval Timer) 0
+T (Taken Branch Trap) 0
+H (Higher-privilege trap) 0
+L (Lower-privilege trap) 0
+N (Nullify next instruction) used by C code
+X (Data memory break disable) 0
+B (Taken Branch) used by C code
+C (code address translation) 1, 0 while executing real-mode code
+V (divide step correction) used by C code
+M (HPMC mask) 0, 1 while executing HPMC handler*
+C/B (carry/borrow bits) used by C code
+O (ordered references) 1*
+F (performance monitor) 0
+R (Recovery Counter trap) 0
+Q (collect interruption state) 1 (0 in code directly preceding an rfi)
+P (Protection Identifiers) 1*
+D (Data address translation) 1, 0 while executing real-mode code
+I (external interrupt mask) used by cli()/sti() macros
+=============================== ===============================================
+
+"Invisible" Registers
+---------------------
+
+=============================== ===============================================
+PSW default W value 0
+PSW default E value 0
+Shadow Registers used by interruption handler code
+TOC enable bit 1
+=============================== ===============================================
+
+-------------------------------------------------------------------------
+
+The PA-RISC architecture defines 7 registers as "shadow registers".
+Those are used in RETURN FROM INTERRUPTION AND RESTORE instruction to reduce
+the state save and restore time by eliminating the need for general register
+(GR) saves and restores in interruption handlers.
+Shadow registers are the GRs 1, 8, 9, 16, 17, 24, and 25.
+
+-------------------------------------------------------------------------
+
+Register usage notes, originally from John Marvin, with some additional
+notes from Randolph Chung.
+
+For the general registers:
+
+r1,r2,r19-r26,r28,r29 & r31 can be used without saving them first. And of
+course, you need to save them if you care about them, before calling
+another procedure. Some of the above registers do have special meanings
+that you should be aware of:
+
+ r1:
+ The addil instruction is hardwired to place its result in r1,
+ so if you use that instruction be aware of that.
+
+ r2:
+ This is the return pointer. In general you don't want to
+ use this, since you need the pointer to get back to your
+ caller. However, it is grouped with this set of registers
+ since the caller can't rely on the value being the same
+ when you return, i.e. you can copy r2 to another register
+ and return through that register after trashing r2, and
+ that should not cause a problem for the calling routine.
+
+ r19-r22:
+ these are generally regarded as temporary registers.
+ Note that in 64 bit they are arg7-arg4.
+
+ r23-r26:
+ these are arg3-arg0, i.e. you can use them if you
+ don't care about the values that were passed in anymore.
+
+ r28,r29:
+ are ret0 and ret1. They are what you pass return values
+ in. r28 is the primary return. When returning small structures
+ r29 may also be used to pass data back to the caller.
+
+ r30:
+ stack pointer
+
+ r31:
+ the ble instruction puts the return pointer in here.
+
+
+ r3-r18,r27,r30 need to be saved and restored. r3-r18 are just
+ general purpose registers. r27 is the data pointer, and is
+ used to make references to global variables easier. r30 is
+ the stack pointer.
diff --git a/Documentation/power/opp.rst b/Documentation/power/opp.rst
index b3cf1de..209c761 100644
--- a/Documentation/power/opp.rst
+++ b/Documentation/power/opp.rst
@@ -46,7 +46,7 @@
----------------------------------------
OPP library provides a set of helper functions to organize and query the OPP
-information. The library is located in drivers/base/power/opp.c and the header
+information. The library is located in drivers/opp/ directory and the header
is located in include/linux/pm_opp.h. OPP library can be enabled by enabling
CONFIG_PM_OPP from power management menuconfig menu. OPP library depends on
CONFIG_PM as certain SoCs such as Texas Instrument's OMAP framework allows to
diff --git a/Documentation/power/pm_qos_interface.rst b/Documentation/power/pm_qos_interface.rst
index 69921f0..3097694 100644
--- a/Documentation/power/pm_qos_interface.rst
+++ b/Documentation/power/pm_qos_interface.rst
@@ -7,8 +7,7 @@
one of the parameters.
Two different PM QoS frameworks are available:
-1. PM QoS classes for cpu_dma_latency, network_latency, network_throughput,
-memory_bandwidth.
+1. PM QoS classes for cpu_dma_latency
2. the per-device PM QoS framework provides the API to manage the per-device latency
constraints and PM QoS flags.
@@ -79,7 +78,7 @@
parameter requests in the following way:
To register the default pm_qos target for the specific parameter, the process
-must open one of /dev/[cpu_dma_latency, network_latency, network_throughput]
+must open /dev/cpu_dma_latency
As long as the device node is held open that process has a registered
request on the parameter.
diff --git a/Documentation/powerpc/elfnote.rst b/Documentation/powerpc/elfnote.rst
new file mode 100644
index 0000000..0660224
--- /dev/null
+++ b/Documentation/powerpc/elfnote.rst
@@ -0,0 +1,41 @@
+==========================
+ELF Note PowerPC Namespace
+==========================
+
+The PowerPC namespace in an ELF Note of the kernel binary is used to store
+capabilities and information which can be used by a bootloader or userland.
+
+Types and Descriptors
+---------------------
+
+The types to be used with the "PowerPC" namesapce are defined in [#f1]_.
+
+ 1) PPC_ELFNOTE_CAPABILITIES
+
+Define the capabilities supported/required by the kernel. This type uses a
+bitmap as "descriptor" field. Each bit is described below:
+
+- Ultravisor-capable bit (PowerNV only).
+
+.. code-block:: c
+
+ #define PPCCAP_ULTRAVISOR_BIT (1 << 0)
+
+Indicate that the powerpc kernel binary knows how to run in an
+ultravisor-enabled system.
+
+In an ultravisor-enabled system, some machine resources are now controlled
+by the ultravisor. If the kernel is not ultravisor-capable, but it ends up
+being run on a machine with ultravisor, the kernel will probably crash
+trying to access ultravisor resources. For instance, it may crash in early
+boot trying to set the partition table entry 0.
+
+In an ultravisor-enabled system, a bootloader could warn the user or prevent
+the kernel from being run if the PowerPC ultravisor capability doesn't exist
+or the Ultravisor-capable bit is not set.
+
+References
+----------
+
+.. [#f1] arch/powerpc/include/asm/elfnote.h
+
diff --git a/Documentation/powerpc/firmware-assisted-dump.rst b/Documentation/powerpc/firmware-assisted-dump.rst
index 9ca1283..0455a78 100644
--- a/Documentation/powerpc/firmware-assisted-dump.rst
+++ b/Documentation/powerpc/firmware-assisted-dump.rst
@@ -9,18 +9,18 @@
to minimize the total elapsed time until the system is back
in production use.
-- Firmware assisted dump (fadump) infrastructure is intended to replace
+- Firmware-Assisted Dump (FADump) infrastructure is intended to replace
the existing phyp assisted dump.
- Fadump uses the same firmware interfaces and memory reservation model
as phyp assisted dump.
-- Unlike phyp dump, fadump exports the memory dump through /proc/vmcore
+- Unlike phyp dump, FADump exports the memory dump through /proc/vmcore
in the ELF format in the same way as kdump. This helps us reuse the
kdump infrastructure for dump capture and filtering.
- Unlike phyp dump, userspace tool does not need to refer any sysfs
interface while reading /proc/vmcore.
-- Unlike phyp dump, fadump allows user to release all the memory reserved
+- Unlike phyp dump, FADump allows user to release all the memory reserved
for dump, with a single operation of echo 1 > /sys/kernel/fadump_release_mem.
-- Once enabled through kernel boot parameter, fadump can be
+- Once enabled through kernel boot parameter, FADump can be
started/stopped through /sys/kernel/fadump_registered interface (see
sysfs files section below) and can be easily integrated with kdump
service start/stop init scripts.
@@ -34,7 +34,7 @@
in a clean, consistent state.
- 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
+ unlike kdump, FADump doesn't need a 2nd reboot to get back
the system to the production configuration.
The above can only be accomplished by coordination with,
@@ -46,10 +46,9 @@
These registered sections of memory are reserved by the first
kernel during early boot.
-- 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.
+- When system crashes, the Power firmware will copy the registered
+ low memory regions (boot memory) from source to destination area.
+ It will also save hardware PTE's.
NOTE:
The term 'boot memory' means size of the low memory chunk
@@ -61,9 +60,9 @@
the default calculated size. Use this option if default
boot memory size is not sufficient for second kernel to
boot successfully. For syntax of crashkernel= parameter,
- refer to Documentation/admin-guide/kdump/kdump.rst. If any offset is
- provided in crashkernel= parameter, it will be ignored
- as fadump uses a predefined offset to reserve memory
+ refer to Documentation/admin-guide/kdump/kdump.rst. If any
+ offset is provided in crashkernel= parameter, it will be
+ ignored 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
@@ -71,13 +70,15 @@
*not* clear the RAM. It will then launch the bootloader, as
normal.
-- The freshly booted kernel will notice that there is a new
- node (ibm,dump-kernel) in the device tree, indicating that
+- The freshly booted kernel will notice that there is a new node
+ (rtas/ibm,kernel-dump on pSeries or ibm,opal/dump/mpipl-boot
+ on OPAL platform) 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
boot memory size effectively booting with restricted memory
- size. This will make sure that the second kernel will not
- touch any of the dump memory area.
+ size. This will make sure that this kernel (also, referred
+ to as second kernel or capture kernel) will not touch any
+ of the dump memory area.
- User-space tools will read /proc/vmcore to obtain the contents
of memory, which holds the previous crashed kernel dump in ELF
@@ -94,8 +95,30 @@
# echo 1 > /sys/kernel/fadump_release_mem
Please note that the firmware-assisted dump feature
-is only available on Power6 and above systems with recent
-firmware versions.
+is only available on POWER6 and above systems on pSeries
+(PowerVM) platform and POWER9 and above systems with OP940
+or later firmware versions on PowerNV (OPAL) platform.
+Note that, OPAL firmware exports ibm,opal/dump node when
+FADump is supported on PowerNV platform.
+
+On OPAL based machines, system first boots into an intermittent
+kernel (referred to as petitboot kernel) before booting into the
+capture kernel. This kernel would have minimal kernel and/or
+userspace support to process crash data. Such kernel needs to
+preserve previously crash'ed kernel's memory for the subsequent
+capture kernel boot to process this crash data. Kernel config
+option CONFIG_PRESERVE_FA_DUMP has to be enabled on such kernel
+to ensure that crash data is preserved to process later.
+
+-- On OPAL based machines (PowerNV), if the kernel is build with
+ CONFIG_OPAL_CORE=y, OPAL memory at the time of crash is also
+ exported as /sys/firmware/opal/core file. This procfs file is
+ helpful in debugging OPAL crashes with GDB. The kernel memory
+ used for exporting this procfs file can be released by echo'ing
+ '1' to /sys/kernel/fadump_release_opalcore node.
+
+ e.g.
+ # echo 1 > /sys/kernel/fadump_release_opalcore
Implementation details:
-----------------------
@@ -110,72 +133,95 @@
/sys/kernel/fadump_release_mem file is created, and the reserved
memory is held.
-If there is no waiting dump data, then only the memory required
-to hold CPU state, HPTE region, boot memory dump and elfcore
-header, is usually reserved at an offset greater than boot memory
-size (see Fig. 1). This area is *not* released: this region will
-be kept permanently reserved, so that it can act as a receptacle
-for a copy of the boot memory content in addition to CPU state
-and HPTE region, in the case a crash does occur. Since this reserved
-memory area is used only after the system crash, there is no point in
-blocking this significant chunk of memory from production kernel.
-Hence, the implementation uses the Linux kernel's Contiguous Memory
-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::
+If there is no waiting dump data, then only the memory required to
+hold CPU state, HPTE region, boot memory dump, FADump header and
+elfcore header, is usually reserved at an offset greater than boot
+memory size (see Fig. 1). This area is *not* released: this region
+will be kept permanently reserved, so that it can act as a receptacle
+for a copy of the boot memory content in addition to CPU state and
+HPTE region, in the case a crash does occur.
+
+Since this reserved memory area is used only after the system crash,
+there is no point in blocking this significant chunk of memory from
+production kernel. Hence, the implementation uses the Linux kernel's
+Contiguous Memory 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::
o Memory Reservation during first kernel
- Low memory Top of memory
- 0 boot memory size |
- | | |<--Reserved dump area -->| |
- V V | Permanent Reservation | V
- +-----------+----------/ /---+---+----+-----------+----+------+
- | | |CPU|HPTE| DUMP |ELF | |
- +-----------+----------/ /---+---+----+-----------+----+------+
- | ^
- | |
- \ /
- -------------------------------------------
- Boot memory content gets transferred to
- reserved area by firmware at the time of
- crash
+ Low memory Top of memory
+ 0 boot memory size |<--- Reserved dump area --->| |
+ | | | Permanent Reservation | |
+ V V | | V
+ +-----------+-----/ /---+---+----+-------+-----+-----+----+--+
+ | | |///|////| DUMP | HDR | ELF |////| |
+ +-----------+-----/ /---+---+----+-------+-----+-----+----+--+
+ | ^ ^ ^ ^ ^
+ | | | | | |
+ \ CPU HPTE / | |
+ ------------------------------ | |
+ Boot memory content gets transferred | |
+ to reserved area by firmware at the | |
+ time of crash. | |
+ FADump Header |
+ (meta area) |
+ |
+ |
+ Metadata: This area holds a metadata struture whose
+ address is registered with f/w and retrieved in the
+ second kernel after crash, on platforms that support
+ tags (OPAL). Having such structure with info needed
+ to process the crashdump eases dump capture process.
+
Fig. 1
+
o Memory Reservation during second kernel after crash
- Low memory Top of memory
- 0 boot memory size |
- | |<------------- Reserved dump area ----------- -->|
- V V V
- +-----------+----------/ /---+---+----+-----------+----+------+
- | | |CPU|HPTE| DUMP |ELF | |
- +-----------+----------/ /---+---+----+-----------+----+------+
- | |
- V V
- Used by second /proc/vmcore
+ Low memory Top of memory
+ 0 boot memory size |
+ | |<------------ Crash preserved area ------------>|
+ V V |<--- Reserved dump area --->| |
+ +-----------+-----/ /---+---+----+-------+-----+-----+----+--+
+ | | |///|////| DUMP | HDR | ELF |////| |
+ +-----------+-----/ /---+---+----+-------+-----+-----+----+--+
+ | |
+ V V
+ Used by second /proc/vmcore
kernel to boot
+
+ +---+
+ |///| -> Regions (CPU, HPTE & Metadata) marked like this in the above
+ +---+ figures are not always present. For example, OPAL platform
+ does not have CPU & HPTE regions while Metadata region is
+ not supported on pSeries currently.
+
Fig. 2
-Currently the dump will be copied from /proc/vmcore to a
-a new file upon user intervention. The dump data available through
-/proc/vmcore will be in ELF format. Hence the existing kdump
-infrastructure (kdump scripts) to save the dump works fine with
-minor modifications.
+
+Currently the dump will be copied from /proc/vmcore to a new file upon
+user intervention. The dump data available through /proc/vmcore will be
+in ELF format. Hence the existing kdump infrastructure (kdump scripts)
+to save the dump works fine with minor modifications. KDump scripts on
+major Distro releases have already been modified to work seemlessly (no
+user intervention in saving the dump) when FADump is used, instead of
+KDump, as dump mechanism.
The tools to examine the dump will be same as the ones
used for kdump.
-How to enable firmware-assisted dump (fadump):
+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.
- By default, fadump reserved memory will be initialized as CMA area.
+ By default, FADump reserved memory will be initialized as CMA area.
Alternatively, user can boot linux kernel with 'fadump=nocma' to
- prevent fadump to use CMA.
+ prevent FADump to use CMA.
3. Optionally, user can also set 'crashkernel=' kernel cmdline
to specify size of the memory to reserve for boot memory dump
preservation.
@@ -201,29 +247,29 @@
Here is the list of files under kernel sysfs:
/sys/kernel/fadump_enabled
- This is used to display the fadump status.
+ 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.
+ 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.
+ 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
+ To register FADump echo 1 > /sys/kernel/fadump_registered and
echo 0 > /sys/kernel/fadump_registered for un-register and stop the
- fadump. Once the fadump is un-registered, the system crash will not
+ FADump. Once the FADump is un-registered, the system crash will not
be handled and vmcore will not be captured. This interface can be
easily integrated with kdump service start/stop.
/sys/kernel/fadump_release_mem
- This file is available only when fadump is active during
+ 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::
@@ -237,25 +283,38 @@
enhanced to use this interface to release the memory reserved for
dump and continue without 2nd reboot.
+ /sys/kernel/fadump_release_opalcore
+
+ This file is available only on OPAL based machines when FADump is
+ active during capture kernel. This is used to release the memory
+ used by the kernel to export /sys/firmware/opal/core file. To
+ release this memory, echo '1' to it:
+
+ echo 1 > /sys/kernel/fadump_release_opalcore
+
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
+ 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>
+ and for kernel DUMP region is:
+
+ DUMP: Src: <src-addr>, Dest: <dest-addr>, Size: <size>, Dumped: # bytes
+
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
- 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
@@ -263,6 +322,7 @@
DUMP: [0x0000006fff1020-0x0000007fff101f] 0x10000000 bytes, Dumped: 0x10000000
: [0x00000010000000-0x0000006ffaffff] 0x5ffb0000 bytes, Dumped: 0x5ffb0000
+
NOTE:
Please refer to Documentation/filesystems/debugfs.txt on
how to mount the debugfs filesystem.
@@ -273,7 +333,7 @@
- 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.
- - 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
diff --git a/Documentation/powerpc/index.rst b/Documentation/powerpc/index.rst
index 549b1cd..db7b6a8 100644
--- a/Documentation/powerpc/index.rst
+++ b/Documentation/powerpc/index.rst
@@ -15,6 +15,7 @@
dawr-power9
dscr
eeh-pci-error-recovery
+ elfnote
firmware-assisted-dump
hvcs
isa-versions
@@ -25,6 +26,7 @@
qe_firmware
syscall64-abi
transactional_memory
+ ultravisor
.. only:: subproject and html
diff --git a/Documentation/powerpc/ultravisor.rst b/Documentation/powerpc/ultravisor.rst
new file mode 100644
index 0000000..730854f
--- /dev/null
+++ b/Documentation/powerpc/ultravisor.rst
@@ -0,0 +1,1054 @@
+.. SPDX-License-Identifier: GPL-2.0
+.. _ultravisor:
+
+============================
+Protected Execution Facility
+============================
+
+.. contents::
+ :depth: 3
+
+Protected Execution Facility
+############################
+
+ Protected Execution Facility (PEF) is an architectural change for
+ POWER 9 that enables Secure Virtual Machines (SVMs). DD2.3 chips
+ (PVR=0x004e1203) or greater will be PEF-capable. A new ISA release
+ will include the PEF RFC02487 changes.
+
+ When enabled, PEF adds a new higher privileged mode, called Ultravisor
+ mode, to POWER architecture. Along with the new mode there is new
+ firmware called the Protected Execution Ultravisor (or Ultravisor
+ for short). Ultravisor mode is the highest privileged mode in POWER
+ architecture.
+
+ +------------------+
+ | Privilege States |
+ +==================+
+ | Problem |
+ +------------------+
+ | Supervisor |
+ +------------------+
+ | Hypervisor |
+ +------------------+
+ | Ultravisor |
+ +------------------+
+
+ PEF protects SVMs from the hypervisor, privileged users, and other
+ VMs in the system. SVMs are protected while at rest and can only be
+ executed by an authorized machine. All virtual machines utilize
+ hypervisor services. The Ultravisor filters calls between the SVMs
+ and the hypervisor to assure that information does not accidentally
+ leak. All hypercalls except H_RANDOM are reflected to the hypervisor.
+ H_RANDOM is not reflected to prevent the hypervisor from influencing
+ random values in the SVM.
+
+ To support this there is a refactoring of the ownership of resources
+ in the CPU. Some of the resources which were previously hypervisor
+ privileged are now ultravisor privileged.
+
+Hardware
+========
+
+ The hardware changes include the following:
+
+ * There is a new bit in the MSR that determines whether the current
+ process is running in secure mode, MSR(S) bit 41. MSR(S)=1, process
+ is in secure mode, MSR(s)=0 process is in normal mode.
+
+ * The MSR(S) bit can only be set by the Ultravisor.
+
+ * HRFID cannot be used to set the MSR(S) bit. If the hypervisor needs
+ to return to a SVM it must use an ultracall. It can determine if
+ the VM it is returning to is secure.
+
+ * There is a new Ultravisor privileged register, SMFCTRL, which has an
+ enable/disable bit SMFCTRL(E).
+
+ * The privilege of a process is now determined by three MSR bits,
+ MSR(S, HV, PR). In each of the tables below the modes are listed
+ from least privilege to highest privilege. The higher privilege
+ modes can access all the resources of the lower privilege modes.
+
+ **Secure Mode MSR Settings**
+
+ +---+---+---+---------------+
+ | S | HV| PR|Privilege |
+ +===+===+===+===============+
+ | 1 | 0 | 1 | Problem |
+ +---+---+---+---------------+
+ | 1 | 0 | 0 | Privileged(OS)|
+ +---+---+---+---------------+
+ | 1 | 1 | 0 | Ultravisor |
+ +---+---+---+---------------+
+ | 1 | 1 | 1 | Reserved |
+ +---+---+---+---------------+
+
+ **Normal Mode MSR Settings**
+
+ +---+---+---+---------------+
+ | S | HV| PR|Privilege |
+ +===+===+===+===============+
+ | 0 | 0 | 1 | Problem |
+ +---+---+---+---------------+
+ | 0 | 0 | 0 | Privileged(OS)|
+ +---+---+---+---------------+
+ | 0 | 1 | 0 | Hypervisor |
+ +---+---+---+---------------+
+ | 0 | 1 | 1 | Problem (Host)|
+ +---+---+---+---------------+
+
+ * Memory is partitioned into secure and normal memory. Only processes
+ that are running in secure mode can access secure memory.
+
+ * The hardware does not allow anything that is not running secure to
+ access secure memory. This means that the Hypervisor cannot access
+ the memory of the SVM without using an ultracall (asking the
+ Ultravisor). The Ultravisor will only allow the hypervisor to see
+ the SVM memory encrypted.
+
+ * I/O systems are not allowed to directly address secure memory. This
+ limits the SVMs to virtual I/O only.
+
+ * The architecture allows the SVM to share pages of memory with the
+ hypervisor that are not protected with encryption. However, this
+ sharing must be initiated by the SVM.
+
+ * When a process is running in secure mode all hypercalls
+ (syscall lev=1) go to the Ultravisor.
+
+ * When a process is in secure mode all interrupts go to the
+ Ultravisor.
+
+ * The following resources have become Ultravisor privileged and
+ require an Ultravisor interface to manipulate:
+
+ * Processor configurations registers (SCOMs).
+
+ * Stop state information.
+
+ * The debug registers CIABR, DAWR, and DAWRX when SMFCTRL(D) is set.
+ If SMFCTRL(D) is not set they do not work in secure mode. When set,
+ reading and writing requires an Ultravisor call, otherwise that
+ will cause a Hypervisor Emulation Assistance interrupt.
+
+ * PTCR and partition table entries (partition table is in secure
+ memory). An attempt to write to PTCR will cause a Hypervisor
+ Emulation Assitance interrupt.
+
+ * LDBAR (LD Base Address Register) and IMC (In-Memory Collection)
+ non-architected registers. An attempt to write to them will cause a
+ Hypervisor Emulation Assistance interrupt.
+
+ * Paging for an SVM, sharing of memory with Hypervisor for an SVM.
+ (Including Virtual Processor Area (VPA) and virtual I/O).
+
+
+Software/Microcode
+==================
+
+ The software changes include:
+
+ * SVMs are created from normal VM using (open source) tooling supplied
+ by IBM.
+
+ * All SVMs start as normal VMs and utilize an ultracall, UV_ESM
+ (Enter Secure Mode), to make the transition.
+
+ * When the UV_ESM ultracall is made the Ultravisor copies the VM into
+ secure memory, decrypts the verification information, and checks the
+ integrity of the SVM. If the integrity check passes the Ultravisor
+ passes control in secure mode.
+
+ * The verification information includes the pass phrase for the
+ encrypted disk associated with the SVM. This pass phrase is given
+ to the SVM when requested.
+
+ * The Ultravisor is not involved in protecting the encrypted disk of
+ the SVM while at rest.
+
+ * For external interrupts the Ultravisor saves the state of the SVM,
+ and reflects the interrupt to the hypervisor for processing.
+ For hypercalls, the Ultravisor inserts neutral state into all
+ registers not needed for the hypercall then reflects the call to
+ the hypervisor for processing. The H_RANDOM hypercall is performed
+ by the Ultravisor and not reflected.
+
+ * For virtual I/O to work bounce buffering must be done.
+
+ * The Ultravisor uses AES (IAPM) for protection of SVM memory. IAPM
+ is a mode of AES that provides integrity and secrecy concurrently.
+
+ * The movement of data between normal and secure pages is coordinated
+ with the Ultravisor by a new HMM plug-in in the Hypervisor.
+
+ The Ultravisor offers new services to the hypervisor and SVMs. These
+ are accessed through ultracalls.
+
+Terminology
+===========
+
+ * Hypercalls: special system calls used to request services from
+ Hypervisor.
+
+ * Normal memory: Memory that is accessible to Hypervisor.
+
+ * Normal page: Page backed by normal memory and available to
+ Hypervisor.
+
+ * Shared page: A page backed by normal memory and available to both
+ the Hypervisor/QEMU and the SVM (i.e page has mappings in SVM and
+ Hypervisor/QEMU).
+
+ * Secure memory: Memory that is accessible only to Ultravisor and
+ SVMs.
+
+ * Secure page: Page backed by secure memory and only available to
+ Ultravisor and SVM.
+
+ * SVM: Secure Virtual Machine.
+
+ * Ultracalls: special system calls used to request services from
+ Ultravisor.
+
+
+Ultravisor calls API
+####################
+
+ This section describes Ultravisor calls (ultracalls) needed to
+ support Secure Virtual Machines (SVM)s and Paravirtualized KVM. The
+ ultracalls allow the SVMs and Hypervisor to request services from the
+ Ultravisor such as accessing a register or memory region that can only
+ be accessed when running in Ultravisor-privileged mode.
+
+ The specific service needed from an ultracall is specified in register
+ R3 (the first parameter to the ultracall). Other parameters to the
+ ultracall, if any, are specified in registers R4 through R12.
+
+ Return value of all ultracalls is in register R3. Other output values
+ from the ultracall, if any, are returned in registers R4 through R12.
+ The only exception to this register usage is the ``UV_RETURN``
+ ultracall described below.
+
+ Each ultracall returns specific error codes, applicable in the context
+ of the ultracall. However, like with the PowerPC Architecture Platform
+ Reference (PAPR), if no specific error code is defined for a
+ particular situation, then the ultracall will fallback to an erroneous
+ parameter-position based code. i.e U_PARAMETER, U_P2, U_P3 etc
+ depending on the ultracall parameter that may have caused the error.
+
+ Some ultracalls involve transferring a page of data between Ultravisor
+ and Hypervisor. Secure pages that are transferred from secure memory
+ to normal memory may be encrypted using dynamically generated keys.
+ When the secure pages are transferred back to secure memory, they may
+ be decrypted using the same dynamically generated keys. Generation and
+ management of these keys will be covered in a separate document.
+
+ For now this only covers ultracalls currently implemented and being
+ used by Hypervisor and SVMs but others can be added here when it
+ makes sense.
+
+ The full specification for all hypercalls/ultracalls will eventually
+ be made available in the public/OpenPower version of the PAPR
+ specification.
+
+ .. note::
+
+ If PEF is not enabled, the ultracalls will be redirected to the
+ Hypervisor which must handle/fail the calls.
+
+Ultracalls used by Hypervisor
+=============================
+
+ This section describes the virtual memory management ultracalls used
+ by the Hypervisor to manage SVMs.
+
+UV_PAGE_OUT
+-----------
+
+ Encrypt and move the contents of a page from secure memory to normal
+ memory.
+
+Syntax
+~~~~~~
+
+.. code-block:: c
+
+ uint64_t ultracall(const uint64_t UV_PAGE_OUT,
+ uint16_t lpid, /* LPAR ID */
+ uint64_t dest_ra, /* real address of destination page */
+ uint64_t src_gpa, /* source guest-physical-address */
+ uint8_t flags, /* flags */
+ uint64_t order) /* page size order */
+
+Return values
+~~~~~~~~~~~~~
+
+ One of the following values:
+
+ * U_SUCCESS on success.
+ * U_PARAMETER if ``lpid`` is invalid.
+ * U_P2 if ``dest_ra`` is invalid.
+ * U_P3 if the ``src_gpa`` address is invalid.
+ * U_P4 if any bit in the ``flags`` is unrecognized
+ * U_P5 if the ``order`` parameter is unsupported.
+ * U_FUNCTION if functionality is not supported.
+ * U_BUSY if page cannot be currently paged-out.
+
+Description
+~~~~~~~~~~~
+
+ Encrypt the contents of a secure-page and make it available to
+ Hypervisor in a normal page.
+
+ By default, the source page is unmapped from the SVM's partition-
+ scoped page table. But the Hypervisor can provide a hint to the
+ Ultravisor to retain the page mapping by setting the ``UV_SNAPSHOT``
+ flag in ``flags`` parameter.
+
+ If the source page is already a shared page the call returns
+ U_SUCCESS, without doing anything.
+
+Use cases
+~~~~~~~~~
+
+ #. QEMU attempts to access an address belonging to the SVM but the
+ page frame for that address is not mapped into QEMU's address
+ space. In this case, the Hypervisor will allocate a page frame,
+ map it into QEMU's address space and issue the ``UV_PAGE_OUT``
+ call to retrieve the encrypted contents of the page.
+
+ #. When Ultravisor runs low on secure memory and it needs to page-out
+ an LRU page. In this case, Ultravisor will issue the
+ ``H_SVM_PAGE_OUT`` hypercall to the Hypervisor. The Hypervisor will
+ then allocate a normal page and issue the ``UV_PAGE_OUT`` ultracall
+ and the Ultravisor will encrypt and move the contents of the secure
+ page into the normal page.
+
+ #. When Hypervisor accesses SVM data, the Hypervisor requests the
+ Ultravisor to transfer the corresponding page into a insecure page,
+ which the Hypervisor can access. The data in the normal page will
+ be encrypted though.
+
+UV_PAGE_IN
+----------
+
+ Move the contents of a page from normal memory to secure memory.
+
+Syntax
+~~~~~~
+
+.. code-block:: c
+
+ uint64_t ultracall(const uint64_t UV_PAGE_IN,
+ uint16_t lpid, /* the LPAR ID */
+ uint64_t src_ra, /* source real address of page */
+ uint64_t dest_gpa, /* destination guest physical address */
+ uint64_t flags, /* flags */
+ uint64_t order) /* page size order */
+
+Return values
+~~~~~~~~~~~~~
+
+ One of the following values:
+
+ * U_SUCCESS on success.
+ * U_BUSY if page cannot be currently paged-in.
+ * U_FUNCTION if functionality is not supported
+ * U_PARAMETER if ``lpid`` is invalid.
+ * U_P2 if ``src_ra`` is invalid.
+ * U_P3 if the ``dest_gpa`` address is invalid.
+ * U_P4 if any bit in the ``flags`` is unrecognized
+ * U_P5 if the ``order`` parameter is unsupported.
+
+Description
+~~~~~~~~~~~
+
+ Move the contents of the page identified by ``src_ra`` from normal
+ memory to secure memory and map it to the guest physical address
+ ``dest_gpa``.
+
+ If `dest_gpa` refers to a shared address, map the page into the
+ partition-scoped page-table of the SVM. If `dest_gpa` is not shared,
+ copy the contents of the page into the corresponding secure page.
+ Depending on the context, decrypt the page before being copied.
+
+ The caller provides the attributes of the page through the ``flags``
+ parameter. Valid values for ``flags`` are:
+
+ * CACHE_INHIBITED
+ * CACHE_ENABLED
+ * WRITE_PROTECTION
+
+ The Hypervisor must pin the page in memory before making
+ ``UV_PAGE_IN`` ultracall.
+
+Use cases
+~~~~~~~~~
+
+ #. When a normal VM switches to secure mode, all its pages residing
+ in normal memory, are moved into secure memory.
+
+ #. When an SVM requests to share a page with Hypervisor the Hypervisor
+ allocates a page and informs the Ultravisor.
+
+ #. When an SVM accesses a secure page that has been paged-out,
+ Ultravisor invokes the Hypervisor to locate the page. After
+ locating the page, the Hypervisor uses UV_PAGE_IN to make the
+ page available to Ultravisor.
+
+UV_PAGE_INVAL
+-------------
+
+ Invalidate the Ultravisor mapping of a page.
+
+Syntax
+~~~~~~
+
+.. code-block:: c
+
+ uint64_t ultracall(const uint64_t UV_PAGE_INVAL,
+ uint16_t lpid, /* the LPAR ID */
+ uint64_t guest_pa, /* destination guest-physical-address */
+ uint64_t order) /* page size order */
+
+Return values
+~~~~~~~~~~~~~
+
+ One of the following values:
+
+ * U_SUCCESS on success.
+ * U_PARAMETER if ``lpid`` is invalid.
+ * U_P2 if ``guest_pa`` is invalid (or corresponds to a secure
+ page mapping).
+ * U_P3 if the ``order`` is invalid.
+ * U_FUNCTION if functionality is not supported.
+ * U_BUSY if page cannot be currently invalidated.
+
+Description
+~~~~~~~~~~~
+
+ This ultracall informs Ultravisor that the page mapping in Hypervisor
+ corresponding to the given guest physical address has been invalidated
+ and that the Ultravisor should not access the page. If the specified
+ ``guest_pa`` corresponds to a secure page, Ultravisor will ignore the
+ attempt to invalidate the page and return U_P2.
+
+Use cases
+~~~~~~~~~
+
+ #. When a shared page is unmapped from the QEMU's page table, possibly
+ because it is paged-out to disk, Ultravisor needs to know that the
+ page should not be accessed from its side too.
+
+
+UV_WRITE_PATE
+-------------
+
+ Validate and write the partition table entry (PATE) for a given
+ partition.
+
+Syntax
+~~~~~~
+
+.. code-block:: c
+
+ uint64_t ultracall(const uint64_t UV_WRITE_PATE,
+ uint32_t lpid, /* the LPAR ID */
+ uint64_t dw0 /* the first double word to write */
+ uint64_t dw1) /* the second double word to write */
+
+Return values
+~~~~~~~~~~~~~
+
+ One of the following values:
+
+ * U_SUCCESS on success.
+ * U_BUSY if PATE cannot be currently written to.
+ * U_FUNCTION if functionality is not supported.
+ * U_PARAMETER if ``lpid`` is invalid.
+ * U_P2 if ``dw0`` is invalid.
+ * U_P3 if the ``dw1`` address is invalid.
+ * U_PERMISSION if the Hypervisor is attempting to change the PATE
+ of a secure virtual machine or if called from a
+ context other than Hypervisor.
+
+Description
+~~~~~~~~~~~
+
+ Validate and write a LPID and its partition-table-entry for the given
+ LPID. If the LPID is already allocated and initialized, this call
+ results in changing the partition table entry.
+
+Use cases
+~~~~~~~~~
+
+ #. The Partition table resides in Secure memory and its entries,
+ called PATE (Partition Table Entries), point to the partition-
+ scoped page tables for the Hypervisor as well as each of the
+ virtual machines (both secure and normal). The Hypervisor
+ operates in partition 0 and its partition-scoped page tables
+ reside in normal memory.
+
+ #. This ultracall allows the Hypervisor to register the partition-
+ scoped and process-scoped page table entries for the Hypervisor
+ and other partitions (virtual machines) with the Ultravisor.
+
+ #. If the value of the PATE for an existing partition (VM) changes,
+ the TLB cache for the partition is flushed.
+
+ #. The Hypervisor is responsible for allocating LPID. The LPID and
+ its PATE entry are registered together. The Hypervisor manages
+ the PATE entries for a normal VM and can change the PATE entry
+ anytime. Ultravisor manages the PATE entries for an SVM and
+ Hypervisor is not allowed to modify them.
+
+UV_RETURN
+---------
+
+ Return control from the Hypervisor back to the Ultravisor after
+ processing an hypercall or interrupt that was forwarded (aka
+ *reflected*) to the Hypervisor.
+
+Syntax
+~~~~~~
+
+.. code-block:: c
+
+ uint64_t ultracall(const uint64_t UV_RETURN)
+
+Return values
+~~~~~~~~~~~~~
+
+ This call never returns to Hypervisor on success. It returns
+ U_INVALID if ultracall is not made from a Hypervisor context.
+
+Description
+~~~~~~~~~~~
+
+ When an SVM makes an hypercall or incurs some other exception, the
+ Ultravisor usually forwards (aka *reflects*) the exceptions to the
+ Hypervisor. After processing the exception, Hypervisor uses the
+ ``UV_RETURN`` ultracall to return control back to the SVM.
+
+ The expected register state on entry to this ultracall is:
+
+ * Non-volatile registers are restored to their original values.
+ * If returning from an hypercall, register R0 contains the return
+ value (**unlike other ultracalls**) and, registers R4 through R12
+ contain any output values of the hypercall.
+ * R3 contains the ultracall number, i.e UV_RETURN.
+ * If returning with a synthesized interrupt, R2 contains the
+ synthesized interrupt number.
+
+Use cases
+~~~~~~~~~
+
+ #. Ultravisor relies on the Hypervisor to provide several services to
+ the SVM such as processing hypercall and other exceptions. After
+ processing the exception, Hypervisor uses UV_RETURN to return
+ control back to the Ultravisor.
+
+ #. Hypervisor has to use this ultracall to return control to the SVM.
+
+
+UV_REGISTER_MEM_SLOT
+--------------------
+
+ Register an SVM address-range with specified properties.
+
+Syntax
+~~~~~~
+
+.. code-block:: c
+
+ uint64_t ultracall(const uint64_t UV_REGISTER_MEM_SLOT,
+ uint64_t lpid, /* LPAR ID of the SVM */
+ uint64_t start_gpa, /* start guest physical address */
+ uint64_t size, /* size of address range in bytes */
+ uint64_t flags /* reserved for future expansion */
+ uint16_t slotid) /* slot identifier */
+
+Return values
+~~~~~~~~~~~~~
+
+ One of the following values:
+
+ * U_SUCCESS on success.
+ * U_PARAMETER if ``lpid`` is invalid.
+ * U_P2 if ``start_gpa`` is invalid.
+ * U_P3 if ``size`` is invalid.
+ * U_P4 if any bit in the ``flags`` is unrecognized.
+ * U_P5 if the ``slotid`` parameter is unsupported.
+ * U_PERMISSION if called from context other than Hypervisor.
+ * U_FUNCTION if functionality is not supported.
+
+
+Description
+~~~~~~~~~~~
+
+ Register a memory range for an SVM. The memory range starts at the
+ guest physical address ``start_gpa`` and is ``size`` bytes long.
+
+Use cases
+~~~~~~~~~
+
+
+ #. When a virtual machine goes secure, all the memory slots managed by
+ the Hypervisor move into secure memory. The Hypervisor iterates
+ through each of memory slots, and registers the slot with
+ Ultravisor. Hypervisor may discard some slots such as those used
+ for firmware (SLOF).
+
+ #. When new memory is hot-plugged, a new memory slot gets registered.
+
+
+UV_UNREGISTER_MEM_SLOT
+----------------------
+
+ Unregister an SVM address-range that was previously registered using
+ UV_REGISTER_MEM_SLOT.
+
+Syntax
+~~~~~~
+
+.. code-block:: c
+
+ uint64_t ultracall(const uint64_t UV_UNREGISTER_MEM_SLOT,
+ uint64_t lpid, /* LPAR ID of the SVM */
+ uint64_t slotid) /* reservation slotid */
+
+Return values
+~~~~~~~~~~~~~
+
+ One of the following values:
+
+ * U_SUCCESS on success.
+ * U_FUNCTION if functionality is not supported.
+ * U_PARAMETER if ``lpid`` is invalid.
+ * U_P2 if ``slotid`` is invalid.
+ * U_PERMISSION if called from context other than Hypervisor.
+
+Description
+~~~~~~~~~~~
+
+ Release the memory slot identified by ``slotid`` and free any
+ resources allocated towards the reservation.
+
+Use cases
+~~~~~~~~~
+
+ #. Memory hot-remove.
+
+
+UV_SVM_TERMINATE
+----------------
+
+ Terminate an SVM and release its resources.
+
+Syntax
+~~~~~~
+
+.. code-block:: c
+
+ uint64_t ultracall(const uint64_t UV_SVM_TERMINATE,
+ uint64_t lpid, /* LPAR ID of the SVM */)
+
+Return values
+~~~~~~~~~~~~~
+
+ One of the following values:
+
+ * U_SUCCESS on success.
+ * U_FUNCTION if functionality is not supported.
+ * U_PARAMETER if ``lpid`` is invalid.
+ * U_INVALID if VM is not secure.
+ * U_PERMISSION if not called from a Hypervisor context.
+
+Description
+~~~~~~~~~~~
+
+ Terminate an SVM and release all its resources.
+
+Use cases
+~~~~~~~~~
+
+ #. Called by Hypervisor when terminating an SVM.
+
+
+Ultracalls used by SVM
+======================
+
+UV_SHARE_PAGE
+-------------
+
+ Share a set of guest physical pages with the Hypervisor.
+
+Syntax
+~~~~~~
+
+.. code-block:: c
+
+ uint64_t ultracall(const uint64_t UV_SHARE_PAGE,
+ uint64_t gfn, /* guest page frame number */
+ uint64_t num) /* number of pages of size PAGE_SIZE */
+
+Return values
+~~~~~~~~~~~~~
+
+ One of the following values:
+
+ * U_SUCCESS on success.
+ * U_FUNCTION if functionality is not supported.
+ * U_INVALID if the VM is not secure.
+ * U_PARAMETER if ``gfn`` is invalid.
+ * U_P2 if ``num`` is invalid.
+
+Description
+~~~~~~~~~~~
+
+ Share the ``num`` pages starting at guest physical frame number ``gfn``
+ with the Hypervisor. Assume page size is PAGE_SIZE bytes. Zero the
+ pages before returning.
+
+ If the address is already backed by a secure page, unmap the page and
+ back it with an insecure page, with the help of the Hypervisor. If it
+ is not backed by any page yet, mark the PTE as insecure and back it
+ with an insecure page when the address is accessed. If it is already
+ backed by an insecure page, zero the page and return.
+
+Use cases
+~~~~~~~~~
+
+ #. The Hypervisor cannot access the SVM pages since they are backed by
+ secure pages. Hence an SVM must explicitly request Ultravisor for
+ pages it can share with Hypervisor.
+
+ #. Shared pages are needed to support virtio and Virtual Processor Area
+ (VPA) in SVMs.
+
+
+UV_UNSHARE_PAGE
+---------------
+
+ Restore a shared SVM page to its initial state.
+
+Syntax
+~~~~~~
+
+.. code-block:: c
+
+ uint64_t ultracall(const uint64_t UV_UNSHARE_PAGE,
+ uint64_t gfn, /* guest page frame number */
+ uint73 num) /* number of pages of size PAGE_SIZE*/
+
+Return values
+~~~~~~~~~~~~~
+
+ One of the following values:
+
+ * U_SUCCESS on success.
+ * U_FUNCTION if functionality is not supported.
+ * U_INVALID if VM is not secure.
+ * U_PARAMETER if ``gfn`` is invalid.
+ * U_P2 if ``num`` is invalid.
+
+Description
+~~~~~~~~~~~
+
+ Stop sharing ``num`` pages starting at ``gfn`` with the Hypervisor.
+ Assume that the page size is PAGE_SIZE. Zero the pages before
+ returning.
+
+ If the address is already backed by an insecure page, unmap the page
+ and back it with a secure page. Inform the Hypervisor to release
+ reference to its shared page. If the address is not backed by a page
+ yet, mark the PTE as secure and back it with a secure page when that
+ address is accessed. If it is already backed by an secure page zero
+ the page and return.
+
+Use cases
+~~~~~~~~~
+
+ #. The SVM may decide to unshare a page from the Hypervisor.
+
+
+UV_UNSHARE_ALL_PAGES
+--------------------
+
+ Unshare all pages the SVM has shared with Hypervisor.
+
+Syntax
+~~~~~~
+
+.. code-block:: c
+
+ uint64_t ultracall(const uint64_t UV_UNSHARE_ALL_PAGES)
+
+Return values
+~~~~~~~~~~~~~
+
+ One of the following values:
+
+ * U_SUCCESS on success.
+ * U_FUNCTION if functionality is not supported.
+ * U_INVAL if VM is not secure.
+
+Description
+~~~~~~~~~~~
+
+ Unshare all shared pages from the Hypervisor. All unshared pages are
+ zeroed on return. Only pages explicitly shared by the SVM with the
+ Hypervisor (using UV_SHARE_PAGE ultracall) are unshared. Ultravisor
+ may internally share some pages with the Hypervisor without explicit
+ request from the SVM. These pages will not be unshared by this
+ ultracall.
+
+Use cases
+~~~~~~~~~
+
+ #. This call is needed when ``kexec`` is used to boot a different
+ kernel. It may also be needed during SVM reset.
+
+UV_ESM
+------
+
+ Secure the virtual machine (*enter secure mode*).
+
+Syntax
+~~~~~~
+
+.. code-block:: c
+
+ uint64_t ultracall(const uint64_t UV_ESM,
+ uint64_t esm_blob_addr, /* location of the ESM blob */
+ unint64_t fdt) /* Flattened device tree */
+
+Return values
+~~~~~~~~~~~~~
+
+ One of the following values:
+
+ * U_SUCCESS on success (including if VM is already secure).
+ * U_FUNCTION if functionality is not supported.
+ * U_INVALID if VM is not secure.
+ * U_PARAMETER if ``esm_blob_addr`` is invalid.
+ * U_P2 if ``fdt`` is invalid.
+ * U_PERMISSION if any integrity checks fail.
+ * U_RETRY insufficient memory to create SVM.
+ * U_NO_KEY symmetric key unavailable.
+
+Description
+~~~~~~~~~~~
+
+ Secure the virtual machine. On successful completion, return
+ control to the virtual machine at the address specified in the
+ ESM blob.
+
+Use cases
+~~~~~~~~~
+
+ #. A normal virtual machine can choose to switch to a secure mode.
+
+Hypervisor Calls API
+####################
+
+ This document describes the Hypervisor calls (hypercalls) that are
+ needed to support the Ultravisor. Hypercalls are services provided by
+ the Hypervisor to virtual machines and Ultravisor.
+
+ Register usage for these hypercalls is identical to that of the other
+ hypercalls defined in the Power Architecture Platform Reference (PAPR)
+ document. i.e on input, register R3 identifies the specific service
+ that is being requested and registers R4 through R11 contain
+ additional parameters to the hypercall, if any. On output, register
+ R3 contains the return value and registers R4 through R9 contain any
+ other output values from the hypercall.
+
+ This document only covers hypercalls currently implemented/planned
+ for Ultravisor usage but others can be added here when it makes sense.
+
+ The full specification for all hypercalls/ultracalls will eventually
+ be made available in the public/OpenPower version of the PAPR
+ specification.
+
+Hypervisor calls to support Ultravisor
+======================================
+
+ Following are the set of hypercalls needed to support Ultravisor.
+
+H_SVM_INIT_START
+----------------
+
+ Begin the process of converting a normal virtual machine into an SVM.
+
+Syntax
+~~~~~~
+
+.. code-block:: c
+
+ uint64_t hypercall(const uint64_t H_SVM_INIT_START)
+
+Return values
+~~~~~~~~~~~~~
+
+ One of the following values:
+
+ * H_SUCCESS on success.
+
+Description
+~~~~~~~~~~~
+
+ Initiate the process of securing a virtual machine. This involves
+ coordinating with the Ultravisor, using ultracalls, to allocate
+ resources in the Ultravisor for the new SVM, transferring the VM's
+ pages from normal to secure memory etc. When the process is
+ completed, Ultravisor issues the H_SVM_INIT_DONE hypercall.
+
+Use cases
+~~~~~~~~~
+
+ #. Ultravisor uses this hypercall to inform Hypervisor that a VM
+ has initiated the process of switching to secure mode.
+
+
+H_SVM_INIT_DONE
+---------------
+
+ Complete the process of securing an SVM.
+
+Syntax
+~~~~~~
+
+.. code-block:: c
+
+ uint64_t hypercall(const uint64_t H_SVM_INIT_DONE)
+
+Return values
+~~~~~~~~~~~~~
+
+ One of the following values:
+
+ * H_SUCCESS on success.
+ * H_UNSUPPORTED if called from the wrong context (e.g.
+ from an SVM or before an H_SVM_INIT_START
+ hypercall).
+
+Description
+~~~~~~~~~~~
+
+ Complete the process of securing a virtual machine. This call must
+ be made after a prior call to ``H_SVM_INIT_START`` hypercall.
+
+Use cases
+~~~~~~~~~
+
+ On successfully securing a virtual machine, the Ultravisor informs
+ Hypervisor about it. Hypervisor can use this call to finish setting
+ up its internal state for this virtual machine.
+
+
+H_SVM_PAGE_IN
+-------------
+
+ Move the contents of a page from normal memory to secure memory.
+
+Syntax
+~~~~~~
+
+.. code-block:: c
+
+ uint64_t hypercall(const uint64_t H_SVM_PAGE_IN,
+ uint64_t guest_pa, /* guest-physical-address */
+ uint64_t flags, /* flags */
+ uint64_t order) /* page size order */
+
+Return values
+~~~~~~~~~~~~~
+
+ One of the following values:
+
+ * H_SUCCESS on success.
+ * H_PARAMETER if ``guest_pa`` is invalid.
+ * H_P2 if ``flags`` is invalid.
+ * H_P3 if ``order`` of page is invalid.
+
+Description
+~~~~~~~~~~~
+
+ Retrieve the content of the page, belonging to the VM at the specified
+ guest physical address.
+
+ Only valid value(s) in ``flags`` are:
+
+ * H_PAGE_IN_SHARED which indicates that the page is to be shared
+ with the Ultravisor.
+
+ * H_PAGE_IN_NONSHARED indicates that the UV is not anymore
+ interested in the page. Applicable if the page is a shared page.
+
+ The ``order`` parameter must correspond to the configured page size.
+
+Use cases
+~~~~~~~~~
+
+ #. When a normal VM becomes a secure VM (using the UV_ESM ultracall),
+ the Ultravisor uses this hypercall to move contents of each page of
+ the VM from normal memory to secure memory.
+
+ #. Ultravisor uses this hypercall to ask Hypervisor to provide a page
+ in normal memory that can be shared between the SVM and Hypervisor.
+
+ #. Ultravisor uses this hypercall to page-in a paged-out page. This
+ can happen when the SVM touches a paged-out page.
+
+ #. If SVM wants to disable sharing of pages with Hypervisor, it can
+ inform Ultravisor to do so. Ultravisor will then use this hypercall
+ and inform Hypervisor that it has released access to the normal
+ page.
+
+H_SVM_PAGE_OUT
+---------------
+
+ Move the contents of the page to normal memory.
+
+Syntax
+~~~~~~
+
+.. code-block:: c
+
+ uint64_t hypercall(const uint64_t H_SVM_PAGE_OUT,
+ uint64_t guest_pa, /* guest-physical-address */
+ uint64_t flags, /* flags (currently none) */
+ uint64_t order) /* page size order */
+
+Return values
+~~~~~~~~~~~~~
+
+ One of the following values:
+
+ * H_SUCCESS on success.
+ * H_PARAMETER if ``guest_pa`` is invalid.
+ * H_P2 if ``flags`` is invalid.
+ * H_P3 if ``order`` is invalid.
+
+Description
+~~~~~~~~~~~
+
+ Move the contents of the page identified by ``guest_pa`` to normal
+ memory.
+
+ Currently ``flags`` is unused and must be set to 0. The ``order``
+ parameter must correspond to the configured page size.
+
+Use cases
+~~~~~~~~~
+
+ #. If Ultravisor is running low on secure pages, it can move the
+ contents of some secure pages, into normal pages using this
+ hypercall. The content will be encrypted.
+
+References
+##########
+
+- `Supporting Protected Computing on IBM Power Architecture <https://developer.ibm.com/articles/l-support-protected-computing/>`_
diff --git a/Documentation/process/email-clients.rst b/Documentation/process/email-clients.rst
index 07faa54..5273d06 100644
--- a/Documentation/process/email-clients.rst
+++ b/Documentation/process/email-clients.rst
@@ -40,7 +40,7 @@
If you configure your email client to send emails with UTF-8 encoding,
you avoid some possible charset problems.
-Email clients should generate and maintain References: or In-Reply-To:
+Email clients should generate and maintain "References:" or "In-Reply-To:"
headers so that mail threading is not broken.
Copy-and-paste (or cut-and-paste) usually does not work for patches
@@ -89,7 +89,7 @@
Works. Some people use this successfully for patches.
-To insert a patch use :menuselection:`Message-->Insert` File (:kbd:`CTRL-I`)
+To insert a patch use :menuselection:`Message-->Insert File` (:kbd:`CTRL-I`)
or an external editor.
If the inserted patch has to be edited in the Claws composition window
@@ -132,8 +132,8 @@
At the bottom of your email, put the commonly-used patch delimiter before
inserting your patch: three hyphens (``---``).
-Then from the :menuselection:`Message` menu item, select insert file and
-choose your patch.
+Then from the :menuselection:`Message` menu item, select
+:menuselection:`insert file` and choose your patch.
As an added bonus you can customise the message creation toolbar menu
and put the :menuselection:`insert file` icon there.
@@ -149,18 +149,16 @@
as inlined text will make them tricky to extract from their 7-bit encoding.
If you absolutely must send patches as attachments instead of inlining
-them as text, right click on the attachment and select properties, and
-highlight :menuselection:`Suggest automatic display` to make the attachment
+them as text, right click on the attachment and select :menuselection:`properties`,
+and highlight :menuselection:`Suggest automatic display` to make the attachment
inlined to make it more viewable.
When saving patches that are sent as inlined text, select the email that
contains the patch from the message list pane, right click and select
:menuselection:`save as`. You can use the whole email unmodified as a patch
-if it was properly composed. There is no option currently to save the email
-when you are actually viewing it in its own window -- there has been a request
-filed at kmail's bugzilla and hopefully this will be addressed. Emails are
-saved as read-write for user only so you will have to chmod them to make them
-group and world readable if you copy them elsewhere.
+if it was properly composed. Emails are saved as read-write for user only so
+you will have to chmod them to make them group and world readable if you copy
+them elsewhere.
Lotus Notes (GUI)
*****************
diff --git a/Documentation/process/embargoed-hardware-issues.rst b/Documentation/process/embargoed-hardware-issues.rst
index 4026363..a3c3349 100644
--- a/Documentation/process/embargoed-hardware-issues.rst
+++ b/Documentation/process/embargoed-hardware-issues.rst
@@ -143,6 +143,20 @@
in their role as Linux kernel developers. They will, however, agree to
adhere to this documented process and the Memorandum of Understanding.
+The disclosing party should provide a list of contacts for all other
+entities who have already been, or should be, informed about the issue.
+This serves several purposes:
+
+ - The list of disclosed entities allows communication accross the
+ industry, e.g. other OS vendors, HW vendors, etc.
+
+ - The disclosed entities can be contacted to name experts who should
+ participate in the mitigation development.
+
+ - If an expert which is required to handle an issue is employed by an
+ listed entity or member of an listed entity, then the response teams can
+ request the disclosure of that expert from that entity. This ensures
+ that the expert is also part of the entity's response team.
Disclosure
""""""""""
@@ -158,10 +172,7 @@
""""""""""""""""""""""
The initial response team sets up an encrypted mailing-list or repurposes
-an existing one if appropriate. The disclosing party should provide a list
-of contacts for all other parties who have already been, or should be,
-informed about the issue. The response team contacts these parties so they
-can name experts who should be subscribed to the mailing-list.
+an existing one if appropriate.
Using a mailing-list is close to the normal Linux development process and
has been successfully used in developing mitigations for various hardware
@@ -175,9 +186,24 @@
stable kernel versions as necessary.
The initial response team will identify further experts from the Linux
-kernel developer community as needed and inform the disclosing party about
-their participation. Bringing in experts can happen at any time of the
-development process and often needs to be handled in a timely manner.
+kernel developer community as needed. Bringing in experts can happen at any
+time of the development process and needs to be handled in a timely manner.
+
+If an expert is employed by or member of an entity on the disclosure list
+provided by the disclosing party, then participation will be requested from
+the relevant entity.
+
+If not, then the disclosing party will be informed about the experts
+participation. The experts are covered by the Memorandum of Understanding
+and the disclosing party is requested to acknowledge the participation. In
+case that the disclosing party has a compelling reason to object, then this
+objection has to be raised within five work days and resolved with the
+incident team immediately. If the disclosing party does not react within
+five work days this is taken as silent acknowledgement.
+
+After acknowledgement or resolution of an objection the expert is disclosed
+by the incident team and brought into the development process.
+
Coordinated release
"""""""""""""""""""
@@ -216,7 +242,7 @@
ARM
AMD
IBM
- Intel
+ Intel Tony Luck <tony.luck@intel.com>
Qualcomm Trilok Soni <tsoni@codeaurora.org>
Microsoft Sasha Levin <sashal@kernel.org>
diff --git a/Documentation/process/howto.rst b/Documentation/process/howto.rst
index 6ab75c1..b6f5a37 100644
--- a/Documentation/process/howto.rst
+++ b/Documentation/process/howto.rst
@@ -123,7 +123,7 @@
https://www.ozlabs.org/~akpm/stuff/tpp.txt
"Linux kernel patch submission format"
- http://linux.yyz.us/patch-format.html
+ https://web.archive.org/web/20180829112450/http://linux.yyz.us/patch-format.html
:ref:`Documentation/process/stable-api-nonsense.rst <stable_api_nonsense>`
This file describes the rationale behind the conscious decision to
diff --git a/Documentation/process/submitting-patches.rst b/Documentation/process/submitting-patches.rst
index 9c42992..fb56297 100644
--- a/Documentation/process/submitting-patches.rst
+++ b/Documentation/process/submitting-patches.rst
@@ -844,7 +844,7 @@
<http://www.ozlabs.org/~akpm/stuff/tpp.txt>
Jeff Garzik, "Linux kernel patch submission format".
- <http://linux.yyz.us/patch-format.html>
+ <https://web.archive.org/web/20180829112450/http://linux.yyz.us/patch-format.html>
Greg Kroah-Hartman, "How to piss off a kernel subsystem maintainer".
<http://www.kroah.com/log/linux/maintainer.html>
diff --git a/Documentation/riscv/boot-image-header.rst b/Documentation/riscv/boot-image-header.rst
new file mode 100644
index 0000000..7b4d1d7
--- /dev/null
+++ b/Documentation/riscv/boot-image-header.rst
@@ -0,0 +1,62 @@
+=================================
+Boot image header in RISC-V Linux
+=================================
+
+:Author: Atish Patra <atish.patra@wdc.com>
+:Date: 20 May 2019
+
+This document only describes the boot image header details for RISC-V Linux.
+
+TODO:
+ Write a complete booting guide.
+
+The following 64-byte header is present in decompressed Linux kernel image::
+
+ u32 code0; /* Executable code */
+ u32 code1; /* Executable code */
+ u64 text_offset; /* Image load offset, little endian */
+ u64 image_size; /* Effective Image size, little endian */
+ u64 flags; /* kernel flags, little endian */
+ u32 version; /* Version of this header */
+ u32 res1 = 0; /* Reserved */
+ u64 res2 = 0; /* Reserved */
+ u64 magic = 0x5643534952; /* Magic number, little endian, "RISCV" */
+ u32 magic2 = 0x56534905; /* Magic number 2, little endian, "RSC\x05" */
+ u32 res4; /* Reserved for PE COFF offset */
+
+This header format is compliant with PE/COFF header and largely inspired from
+ARM64 header. Thus, both ARM64 & RISC-V header can be combined into one common
+header in future.
+
+Notes
+=====
+
+- This header can also be reused to support EFI stub for RISC-V in future. EFI
+ specification needs PE/COFF image header in the beginning of the kernel image
+ in order to load it as an EFI application. In order to support EFI stub,
+ code0 should be replaced with "MZ" magic string and res5(at offset 0x3c) should
+ point to the rest of the PE/COFF header.
+
+- version field indicate header version number
+
+ ========== =============
+ Bits 0:15 Minor version
+ Bits 16:31 Major version
+ ========== =============
+
+ This preserves compatibility across newer and older version of the header.
+ The current version is defined as 0.2.
+
+- The "magic" field is deprecated as of version 0.2. In a future
+ release, it may be removed. This originally should have matched up
+ with the ARM64 header "magic" field, but unfortunately does not.
+ The "magic2" field replaces it, matching up with the ARM64 header.
+
+- In current header, the flags field has only one field.
+
+ ===== ====================================
+ Bit 0 Kernel endianness. 1 if BE, 0 if LE.
+ ===== ====================================
+
+- Image size is mandatory for boot loader to load kernel image. Booting will
+ fail otherwise.
diff --git a/Documentation/riscv/boot-image-header.txt b/Documentation/riscv/boot-image-header.txt
deleted file mode 100644
index 1b73fea..0000000
--- a/Documentation/riscv/boot-image-header.txt
+++ /dev/null
@@ -1,50 +0,0 @@
- Boot image header in RISC-V Linux
- =============================================
-
-Author: Atish Patra <atish.patra@wdc.com>
-Date : 20 May 2019
-
-This document only describes the boot image header details for RISC-V Linux.
-The complete booting guide will be available at Documentation/riscv/booting.txt.
-
-The following 64-byte header is present in decompressed Linux kernel image.
-
- u32 code0; /* Executable code */
- u32 code1; /* Executable code */
- u64 text_offset; /* Image load offset, little endian */
- u64 image_size; /* Effective Image size, little endian */
- u64 flags; /* kernel flags, little endian */
- u32 version; /* Version of this header */
- u32 res1 = 0; /* Reserved */
- u64 res2 = 0; /* Reserved */
- u64 magic = 0x5643534952; /* Magic number, little endian, "RISCV" */
- u32 res3; /* Reserved for additional RISC-V specific header */
- u32 res4; /* Reserved for PE COFF offset */
-
-This header format is compliant with PE/COFF header and largely inspired from
-ARM64 header. Thus, both ARM64 & RISC-V header can be combined into one common
-header in future.
-
-Notes:
-- This header can also be reused to support EFI stub for RISC-V in future. EFI
- specification needs PE/COFF image header in the beginning of the kernel image
- in order to load it as an EFI application. In order to support EFI stub,
- code0 should be replaced with "MZ" magic string and res5(at offset 0x3c) should
- point to the rest of the PE/COFF header.
-
-- version field indicate header version number.
- Bits 0:15 - Minor version
- Bits 16:31 - Major version
-
- This preserves compatibility across newer and older version of the header.
- The current version is defined as 0.1.
-
-- res3 is reserved for offset to any other additional fields. This makes the
- header extendible in future. One example would be to accommodate ISA
- extension for RISC-V in future. For current version, it is set to be zero.
-
-- In current header, the flag field has only one field.
- Bit 0: Kernel endianness. 1 if BE, 0 if LE.
-
-- Image size is mandatory for boot loader to load kernel image. Booting will
- fail otherwise.
diff --git a/Documentation/riscv/index.rst b/Documentation/riscv/index.rst
index e3ca092..215fd3c 100644
--- a/Documentation/riscv/index.rst
+++ b/Documentation/riscv/index.rst
@@ -5,6 +5,7 @@
.. toctree::
:maxdepth: 1
+ boot-image-header
pmu
.. only:: subproject and html
diff --git a/Documentation/s390/dasd.rst b/Documentation/s390/dasd.rst
deleted file mode 100644
index 9e222472..0000000
--- a/Documentation/s390/dasd.rst
+++ /dev/null
@@ -1,84 +0,0 @@
-==================
-DASD device driver
-==================
-
-S/390's disk devices (DASDs) are managed by Linux via the DASD device
-driver. It is valid for all types of DASDs and represents them to
-Linux as block devices, namely "dd". Currently the DASD driver uses a
-single major number (254) and 4 minor numbers per volume (1 for the
-physical volume and 3 for partitions). With respect to partitions see
-below. Thus you may have up to 64 DASD devices in your system.
-
-The kernel parameter 'dasd=from-to,...' may be issued arbitrary times
-in the kernel's parameter line or not at all. The 'from' and 'to'
-parameters are to be given in hexadecimal notation without a leading
-0x.
-If you supply kernel parameters the different instances are processed
-in order of appearance and a minor number is reserved for any device
-covered by the supplied range up to 64 volumes. Additional DASDs are
-ignored. If you do not supply the 'dasd=' kernel parameter at all, the
-DASD driver registers all supported DASDs of your system to a minor
-number in ascending order of the subchannel number.
-
-The driver currently supports ECKD-devices and there are stubs for
-support of the FBA and CKD architectures. For the FBA architecture
-only some smart data structures are missing to make the support
-complete.
-We performed our testing on 3380 and 3390 type disks of different
-sizes, under VM and on the bare hardware (LPAR), using internal disks
-of the multiprise as well as a RAMAC virtual array. Disks exported by
-an Enterprise Storage Server (Seascape) should work fine as well.
-
-We currently implement one partition per volume, which is the whole
-volume, skipping the first blocks up to the volume label. These are
-reserved for IPL records and IBM's volume label to assure
-accessibility of the DASD from other OSs. In a later stage we will
-provide support of partitions, maybe VTOC oriented or using a kind of
-partition table in the label record.
-
-Usage
-=====
-
--Low-level format (?CKD only)
-For using an ECKD-DASD as a Linux harddisk you have to low-level
-format the tracks by issuing the BLKDASDFORMAT-ioctl on that
-device. This will erase any data on that volume including IBM volume
-labels, VTOCs etc. The ioctl may take a `struct format_data *` or
-'NULL' as an argument::
-
- typedef struct {
- int start_unit;
- int stop_unit;
- int blksize;
- } format_data_t;
-
-When a NULL argument is passed to the BLKDASDFORMAT ioctl the whole
-disk is formatted to a blocksize of 1024 bytes. Otherwise start_unit
-and stop_unit are the first and last track to be formatted. If
-stop_unit is -1 it implies that the DASD is formatted from start_unit
-up to the last track. blksize can be any power of two between 512 and
-4096. We recommend no blksize lower than 1024 because the ext2fs uses
-1kB blocks anyway and you gain approx. 50% of capacity increasing your
-blksize from 512 byte to 1kB.
-
-Make a filesystem
-=================
-
-Then you can mk??fs the filesystem of your choice on that volume or
-partition. For reasons of sanity you should build your filesystem on
-the partition /dev/dd?1 instead of the whole volume. You only lose 3kB
-but may be sure that you can reuse your data after introduction of a
-real partition table.
-
-Bugs
-====
-
-- Performance sometimes is rather low because we don't fully exploit clustering
-
-TODO-List
-=========
-
-- Add IBM'S Disk layout to genhd
-- Enhance driver to use more than one major number
-- Enable usage as a module
-- Support Cache fast write and DASD fast write (ECKD)
diff --git a/Documentation/s390/debugging390.rst b/Documentation/s390/debugging390.rst
deleted file mode 100644
index 73ad0b0..0000000
--- a/Documentation/s390/debugging390.rst
+++ /dev/null
@@ -1,2613 +0,0 @@
-=============================================
-Debugging on Linux for s/390 & z/Architecture
-=============================================
-
-Denis Joseph Barrow (djbarrow@de.ibm.com,barrow_dj@yahoo.com)
-
-Copyright (C) 2000-2001 IBM Deutschland Entwicklung GmbH, IBM Corporation
-
-.. Best viewed with fixed width fonts
-
-Overview of Document:
-=====================
-This document is intended to give a good overview of how to debug Linux for
-s/390 and z/Architecture. It is not intended as a complete reference and not a
-tutorial on the fundamentals of C & assembly. It doesn't go into
-390 IO in any detail. It is intended to complement the documents in the
-reference section below & any other worthwhile references you get.
-
-It is intended like the Enterprise Systems Architecture/390 Reference Summary
-to be printed out & used as a quick cheat sheet self help style reference when
-problems occur.
-
-.. Contents
- ========
- Register Set
- Address Spaces on Intel Linux
- Address Spaces on Linux for s/390 & z/Architecture
- The Linux for s/390 & z/Architecture Kernel Task Structure
- Register Usage & Stackframes on Linux for s/390 & z/Architecture
- A sample program with comments
- Compiling programs for debugging on Linux for s/390 & z/Architecture
- Debugging under VM
- s/390 & z/Architecture IO Overview
- Debugging IO on s/390 & z/Architecture under VM
- GDB on s/390 & z/Architecture
- Stack chaining in gdb by hand
- Examining core dumps
- ldd
- Debugging modules
- The proc file system
- SysRq
- References
- Special Thanks
-
-Register Set
-============
-The current architectures have the following registers.
-
-16 General propose registers, 32 bit on s/390 and 64 bit on z/Architecture,
-r0-r15 (or gpr0-gpr15), used for arithmetic and addressing.
-
-16 Control registers, 32 bit on s/390 and 64 bit on z/Architecture, cr0-cr15,
-kernel usage only, used for memory management, interrupt control, debugging
-control etc.
-
-16 Access registers (ar0-ar15), 32 bit on both s/390 and z/Architecture,
-normally not used by normal programs but potentially could be used as
-temporary storage. These registers have a 1:1 association with general
-purpose registers and are designed to be used in the so-called access
-register mode to select different address spaces.
-Access register 0 (and access register 1 on z/Architecture, which needs a
-64 bit pointer) is currently used by the pthread library as a pointer to
-the current running threads private area.
-
-16 64-bit floating point registers (fp0-fp15 ) IEEE & HFP floating
-point format compliant on G5 upwards & a Floating point control reg (FPC)
-
-4 64-bit registers (fp0,fp2,fp4 & fp6) HFP only on older machines.
-
-Note:
- Linux (currently) always uses IEEE & emulates G5 IEEE format on older
- machines, ( provided the kernel is configured for this ).
-
-
-The PSW is the most important register on the machine it
-is 64 bit on s/390 & 128 bit on z/Architecture & serves the roles of
-a program counter (pc), condition code register,memory space designator.
-In IBM standard notation I am counting bit 0 as the MSB.
-It has several advantages over a normal program counter
-in that you can change address translation & program counter
-in a single instruction. To change address translation,
-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 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)
---------------
-This per cpu memory area is too intimately tied to the processor not to mention.
-It exists between the real addresses 0-4096 on s/390 and between 0-8192 on
-z/Architecture and is exchanged with one page on s/390 or two pages on
-z/Architecture in absolute storage by the set prefix instruction during Linux
-startup.
-
-This page is mapped to a different prefix for each processor in an SMP
-configuration (assuming the OS designer is sane of course).
-
-Bytes 0-512 (200 hex) on s/390 and 0-512, 4096-4544, 4604-5119 currently on
-z/Architecture are used by the processor itself for holding such information
-as exception indications and entry points for exceptions.
-
-Bytes after 0xc00 hex are used by linux for per processor globals on s/390 and
-z/Architecture (there is a gap on z/Architecture currently between 0xc00 and
-0x1000, too, which is used by Linux).
-
-The closest thing to this on traditional architectures is the interrupt
-vector table. This is a good thing & does simplify some of the kernel coding
-however it means that we now cannot catch stray NULL pointers in the
-kernel without hard coded checks.
-
-
-
-Address Spaces on Intel Linux
-=============================
-
-The traditional Intel Linux is approximately mapped as follows forgive
-the ascii art::
-
- 0xFFFFFFFF 4GB Himem *****************
- * *
- * Kernel Space *
- * *
- ***************** ****************
- User Space Himem * User Stack * * *
- (typically 0xC0000000 3GB ) ***************** * *
- * Shared Libs * * Next Process *
- ***************** * to *
- * * <== * Run * <==
- * User Program * * *
- * Data BSS * * *
- * Text * * *
- * Sections * * *
- 0x00000000 ***************** ****************
-
-Now it is easy to see that on Intel it is quite easy to recognise a kernel
-address as being one greater than user space himem (in this case 0xC0000000),
-and addresses of less than this are the ones in the current running program on
-this processor (if an smp box).
-
-If using the virtual machine ( VM ) as a debugger it is quite difficult to
-know which user process is running as the address space you are looking at
-could be from any process in the run queue.
-
-The limitation of Intels addressing technique is that the linux
-kernel uses a very simple real address to virtual addressing technique
-of Real Address=Virtual Address-User Space Himem.
-This means that on Intel the kernel linux can typically only address
-Himem=0xFFFFFFFF-0xC0000000=1GB & this is all the RAM these machines
-can typically use.
-
-They can lower User Himem to 2GB or lower & thus be
-able to use 2GB of RAM however this shrinks the maximum size
-of User Space from 3GB to 2GB they have a no win limit of 4GB unless
-they go to 64 Bit.
-
-
-On 390 our limitations & strengths make us slightly different.
-For backward compatibility we are only allowed use 31 bits (2GB)
-of our 32 bit addresses, however, we use entirely separate address
-spaces for the user & kernel.
-
-This means we can support 2GB of non Extended RAM on s/390, & more
-with the Extended memory management swap device &
-currently 4TB of physical memory currently on z/Architecture.
-
-
-Address Spaces on Linux for s/390 & z/Architecture
-==================================================
-
-Our addressing scheme is basically as follows::
-
- Primary Space Home Space
- Himem 0x7fffffff 2GB on s/390 ***************** ****************
- currently 0x3ffffffffff (2^42)-1 * User Stack * * *
- on z/Architecture. ***************** * *
- * Shared Libs * * *
- ***************** * *
- * * * Kernel *
- * User Program * * *
- * Data BSS * * *
- * Text * * *
- * Sections * * *
- 0x00000000 ***************** ****************
-
-This also means that we need to look at the PSW problem state bit and the
-addressing mode to decide whether we are looking at user or kernel space.
-
-User space runs in primary address mode (or access register mode within
-the vdso code).
-
-The kernel usually also runs in home space mode, however when accessing
-user space the kernel switches to primary or secondary address mode if
-the mvcos instruction is not available or if a compare-and-swap (futex)
-instruction on a user space address is performed.
-
-When also looking at the ASCE control registers, this means:
-
-User space:
-
-- runs in primary or access register mode
-- cr1 contains the user asce
-- cr7 contains the user asce
-- cr13 contains the kernel asce
-
-Kernel space:
-
-- runs in home space mode
-- cr1 contains the user or kernel asce
-
- - the kernel asce is loaded when a uaccess requires primary or
- secondary address mode
-
-- cr7 contains the user or kernel asce, (changed with set_fs())
-- cr13 contains the kernel asce
-
-In case of uaccess the kernel changes to:
-
-- primary space mode in case of a uaccess (copy_to_user) and uses
- e.g. the mvcp instruction to access user space. However the kernel
- will stay in home space mode if the mvcos instruction is available
-- secondary space mode in case of futex atomic operations, so that the
- instructions come from primary address space and data from secondary
- space
-
-In case of KVM, the kernel runs in home space mode, but cr1 gets switched
-to contain the gmap asce before the SIE instruction gets executed. When
-the SIE instruction is finished, cr1 will be switched back to contain the
-user asce.
-
-
-Virtual Addresses on s/390 & z/Architecture
-===========================================
-
-A virtual address on s/390 is made up of 3 parts
-The SX (segment index, roughly corresponding to the PGD & PMD in Linux
-terminology) being bits 1-11.
-
-The PX (page index, corresponding to the page table entry (pte) in Linux
-terminology) being bits 12-19.
-
-The remaining bits BX (the byte index are the offset in the page )
-i.e. bits 20 to 31.
-
-On z/Architecture in linux we currently make up an address from 4 parts.
-
-- The region index bits (RX) 0-32 we currently use bits 22-32
-- The segment index (SX) being bits 33-43
-- The page index (PX) being bits 44-51
-- The byte index (BX) being bits 52-63
-
-Notes:
- 1) s/390 has no PMD so the PMD is really the PGD also.
- A lot of this stuff is defined in pgtable.h.
-
- 2) Also seeing as s/390's page indexes are only 1k in size
- (bits 12-19 x 4 bytes per pte ) we use 1 ( page 4k )
- to make the best use of memory by updating 4 segment indices
- entries each time we mess with a PMD & use offsets
- 0,1024,2048 & 3072 in this page as for our segment indexes.
- On z/Architecture our page indexes are now 2k in size
- ( bits 12-19 x 8 bytes per pte ) we do a similar trick
- but only mess with 2 segment indices each time we mess with
- a PMD.
-
- 3) As z/Architecture supports up to a massive 5-level page table lookup we
- can only use 3 currently on Linux ( as this is all the generic kernel
- currently supports ) however this may change in future
- this allows us to access ( according to my sums )
- 4TB of virtual storage per process i.e.
- 4096*512(PTES)*1024(PMDS)*2048(PGD) = 4398046511104 bytes,
- enough for another 2 or 3 of years I think :-).
- to do this we use a region-third-table designation type in
- our address space control registers.
-
-
-The Linux for s/390 & z/Architecture Kernel Task Structure
-==========================================================
-Each process/thread under Linux for S390 has its own kernel task_struct
-defined in linux/include/linux/sched.h
-The S390 on initialisation & resuming of a process on a cpu sets
-the __LC_KERNEL_STACK variable in the spare prefix area for this cpu
-(which we use for per-processor globals).
-
-The kernel stack pointer is intimately tied with the task structure for
-each processor as follows::
-
- s/390
- ************************
- * 1 page kernel stack *
- * ( 4K ) *
- ************************
- * 1 page task_struct *
- * ( 4K ) *
- 8K aligned ************************
-
- z/Architecture
- ************************
- * 2 page kernel stack *
- * ( 8K ) *
- ************************
- * 2 page task_struct *
- * ( 8K ) *
- 16K aligned ************************
-
-What this means is that we don't need to dedicate any register or global
-variable to point to the current running process & can retrieve it with the
-following very simple construct for s/390 & one very similar for
-z/Architecture::
-
- static inline struct task_struct * get_current(void)
- {
- struct task_struct *current;
- __asm__("lhi %0,-8192\n\t"
- "nr %0,15"
- : "=r" (current) );
- return current;
- }
-
-i.e. just anding the current kernel stack pointer with the mask -8192.
-Thankfully because Linux doesn't have support for nested IO interrupts
-& our devices have large buffers can survive interrupts being shut for
-short amounts of time we don't need a separate stack for interrupts.
-
-
-
-
-Register Usage & Stackframes on Linux for s/390 & z/Architecture
-=================================================================
-Overview:
----------
-This is the code that gcc produces at the top & the bottom of
-each function. It usually is fairly consistent & similar from
-function to function & if you know its layout you can probably
-make some headway in finding the ultimate cause of a problem
-after a crash without a source level debugger.
-
-Note: To follow stackframes requires a knowledge of C or Pascal &
-limited knowledge of one assembly language.
-
-It should be noted that there are some differences between the
-s/390 and z/Architecture stack layouts as the z/Architecture stack layout
-didn't have to maintain compatibility with older linkage formats.
-
-Glossary:
----------
-alloca:
- This is a built in compiler function for runtime allocation
- of extra space on the callers stack which is obviously freed
- up on function exit ( e.g. the caller may choose to allocate nothing
- of a buffer of 4k if required for temporary purposes ), it generates
- very efficient code ( a few cycles ) when compared to alternatives
- like malloc.
-
-automatics:
- These are local variables on the stack, i.e they aren't in registers &
- they aren't static.
-
-back-chain:
- This is a pointer to the stack pointer before entering a
- framed functions ( see frameless function ) prologue got by
- dereferencing the address of the current stack pointer,
- i.e. got by accessing the 32 bit value at the stack pointers
- current location.
-
-base-pointer:
- This is a pointer to the back of the literal pool which
- is an area just behind each procedure used to store constants
- in each function.
-
-call-clobbered:
- The caller probably needs to save these registers if there
- is something of value in them, on the stack or elsewhere before making a
- call to another procedure so that it can restore it later.
-
-epilogue:
- The code generated by the compiler to return to the caller.
-
-frameless-function:
- A frameless function in Linux for s390 & z/Architecture is one which doesn't
- need more than the register save area (96 bytes on s/390, 160 on z/Architecture)
- given to it by the caller.
-
- A frameless function never:
-
- 1) Sets up a back chain.
- 2) Calls alloca.
- 3) Calls other normal functions
- 4) Has automatics.
-
-GOT-pointer:
- This is a pointer to the global-offset-table in ELF
- ( Executable Linkable Format, Linux'es most common executable format ),
- all globals & shared library objects are found using this pointer.
-
-lazy-binding
- ELF shared libraries are typically only loaded when routines in the shared
- library are actually first called at runtime. This is lazy binding.
-
-procedure-linkage-table
- This is a table found from the GOT which contains pointers to routines
- in other shared libraries which can't be called to by easier means.
-
-prologue:
- The code generated by the compiler to set up the stack frame.
-
-outgoing-args:
- This is extra area allocated on the stack of the calling function if the
- parameters for the callee's cannot all be put in registers, the same
- area can be reused by each function the caller calls.
-
-routine-descriptor:
- A COFF executable format based concept of a procedure reference
- actually being 8 bytes or more as opposed to a simple pointer to the routine.
- This is typically defined as follows:
-
- - Routine Descriptor offset 0=Pointer to Function
- - Routine Descriptor offset 4=Pointer to Table of Contents
-
- The table of contents/TOC is roughly equivalent to a GOT pointer.
- & it means that shared libraries etc. can be shared between several
- environments each with their own TOC.
-
-static-chain:
- This is used in nested functions a concept adopted from pascal
- by gcc not used in ansi C or C++ ( although quite useful ), basically it
- is a pointer used to reference local variables of enclosing functions.
- You might come across this stuff once or twice in your lifetime.
-
- e.g.
-
- The function below should return 11 though gcc may get upset & toss warnings
- about unused variables::
-
- int FunctionA(int a)
- {
- int b;
- FunctionC(int c)
- {
- b=c+1;
- }
- FunctionC(10);
- return(b);
- }
-
-
-s/390 & z/Architecture Register usage
-=====================================
-
-======== ========================================== ===============
-r0 used by syscalls/assembly call-clobbered
-r1 used by syscalls/assembly call-clobbered
-r2 argument 0 / return value 0 call-clobbered
-r3 argument 1 / return value 1 (if long long) call-clobbered
-r4 argument 2 call-clobbered
-r5 argument 3 call-clobbered
-r6 argument 4 saved
-r7 pointer-to arguments 5 to ... saved
-r8 this & that saved
-r9 this & that saved
-r10 static-chain ( if nested function ) saved
-r11 frame-pointer ( if function used alloca ) saved
-r12 got-pointer saved
-r13 base-pointer saved
-r14 return-address saved
-r15 stack-pointer saved
-
-f0 argument 0 / return value ( float/double ) call-clobbered
-f2 argument 1 call-clobbered
-f4 z/Architecture argument 2 saved
-f6 z/Architecture argument 3 saved
-======== ========================================== ===============
-
-The remaining floating points
-f1,f3,f5 f7-f15 are call-clobbered.
-
-Notes:
-------
-1) The only requirement is that registers which are used
- by the callee are saved, e.g. the compiler is perfectly
- capable of using r11 for purposes other than a frame a
- frame pointer if a frame pointer is not needed.
-2) In functions with variable arguments e.g. printf the calling procedure
- is identical to one without variable arguments & the same number of
- parameters. However, the prologue of this function is somewhat more
- hairy owing to it having to move these parameters to the stack to
- get va_start, va_arg & va_end to work.
-3) Access registers are currently unused by gcc but are used in
- the kernel. Possibilities exist to use them at the moment for
- temporary storage but it isn't recommended.
-4) Only 4 of the floating point registers are used for
- parameter passing as older machines such as G3 only have only 4
- & it keeps the stack frame compatible with other compilers.
- However with IEEE floating point emulation under linux on the
- older machines you are free to use the other 12.
-5) A long long or double parameter cannot be have the
- first 4 bytes in a register & the second four bytes in the
- outgoing args area. It must be purely in the outgoing args
- area if crossing this boundary.
-6) Floating point parameters are mixed with outgoing args
- on the outgoing args area in the order the are passed in as parameters.
-7) Floating point arguments 2 & 3 are saved in the outgoing args area for
- z/Architecture
-
-
-Stack Frame Layout
-------------------
-
-========= ============== ======================================================
-s/390 z/Architecture
-========= ============== ======================================================
-0 0 back chain ( a 0 here signifies end of back chain )
-4 8 eos ( end of stack, not used on Linux for S390 used
- in other linkage formats )
-8 16 glue used in other s/390 linkage formats for saved
- routine descriptors etc.
-12 24 glue used in other s/390 linkage formats for saved
- routine descriptors etc.
-16 32 scratch area
-20 40 scratch area
-24 48 saved r6 of caller function
-28 56 saved r7 of caller function
-32 64 saved r8 of caller function
-36 72 saved r9 of caller function
-40 80 saved r10 of caller function
-44 88 saved r11 of caller function
-48 96 saved r12 of caller function
-52 104 saved r13 of caller function
-56 112 saved r14 of caller function
-60 120 saved r15 of caller function
-64 128 saved f4 of caller function
-72 132 saved f6 of caller function
-80 undefined
-96 160 outgoing args passed from caller to callee
-96+x 160+x possible stack alignment ( 8 bytes desirable )
-96+x+y 160+x+y alloca space of caller ( if used )
-96+x+y+z 160+x+y+z automatics of caller ( if used )
-0 back-chain
-========= ============== ======================================================
-
-A sample program with comments.
-===============================
-
-Comments on the function test
------------------------------
-1) It didn't need to set up a pointer to the constant pool gpr13 as it is not
- used ( :-( ).
-2) This is a frameless function & no stack is bought.
-3) The compiler was clever enough to recognise that it could return the
- value in r2 as well as use it for the passed in parameter ( :-) ).
-4) The basr ( branch relative & save ) trick works as follows the instruction
- has a special case with r0,r0 with some instruction operands is understood as
- the literal value 0, some risc architectures also do this ). So now
- we are branching to the next address & the address new program counter is
- in r13,so now we subtract the size of the function prologue we have executed
- the size of the literal pool to get to the top of the literal pool::
-
-
- 0040037c int test(int b)
- { # Function prologue below
- 40037c: 90 de f0 34 stm %r13,%r14,52(%r15) # Save registers r13 & r14
- 400380: 0d d0 basr %r13,%r0 # Set up pointer to constant pool using
- 400382: a7 da ff fa ahi %r13,-6 # basr trick
- return(5+b);
- # Huge main program
- 400386: a7 2a 00 05 ahi %r2,5 # add 5 to r2
-
- # Function epilogue below
- 40038a: 98 de f0 34 lm %r13,%r14,52(%r15) # restore registers r13 & 14
- 40038e: 07 fe br %r14 # return
- }
-
-Comments on the function main
------------------------------
-1) The compiler did this function optimally ( 8-) )::
-
- Literal pool for main.
- 400390: ff ff ff ec .long 0xffffffec
- main(int argc,char *argv[])
- { # Function prologue below
- 400394: 90 bf f0 2c stm %r11,%r15,44(%r15) # Save necessary registers
- 400398: 18 0f lr %r0,%r15 # copy stack pointer to r0
- 40039a: a7 fa ff a0 ahi %r15,-96 # Make area for callee saving
- 40039e: 0d d0 basr %r13,%r0 # Set up r13 to point to
- 4003a0: a7 da ff f0 ahi %r13,-16 # literal pool
- 4003a4: 50 00 f0 00 st %r0,0(%r15) # Save backchain
-
- return(test(5)); # Main Program Below
- 4003a8: 58 e0 d0 00 l %r14,0(%r13) # load relative address of test from
- # literal pool
- 4003ac: a7 28 00 05 lhi %r2,5 # Set first parameter to 5
- 4003b0: 4d ee d0 00 bas %r14,0(%r14,%r13) # jump to test setting r14 as return
- # address using branch & save instruction.
-
- # Function Epilogue below
- 4003b4: 98 bf f0 8c lm %r11,%r15,140(%r15)# Restore necessary registers.
- 4003b8: 07 fe br %r14 # return to do program exit
- }
-
-
-Compiler updates
-----------------
-
-::
-
- main(int argc,char *argv[])
- {
- 4004fc: 90 7f f0 1c stm %r7,%r15,28(%r15)
- 400500: a7 d5 00 04 bras %r13,400508 <main+0xc>
- 400504: 00 40 04 f4 .long 0x004004f4
- # compiler now puts constant pool in code to so it saves an instruction
- 400508: 18 0f lr %r0,%r15
- 40050a: a7 fa ff a0 ahi %r15,-96
- 40050e: 50 00 f0 00 st %r0,0(%r15)
- return(test(5));
- 400512: 58 10 d0 00 l %r1,0(%r13)
- 400516: a7 28 00 05 lhi %r2,5
- 40051a: 0d e1 basr %r14,%r1
- # compiler adds 1 extra instruction to epilogue this is done to
- # avoid processor pipeline stalls owing to data dependencies on g5 &
- # above as register 14 in the old code was needed directly after being loaded
- # by the lm %r11,%r15,140(%r15) for the br %14.
- 40051c: 58 40 f0 98 l %r4,152(%r15)
- 400520: 98 7f f0 7c lm %r7,%r15,124(%r15)
- 400524: 07 f4 br %r4
- }
-
-
-Hartmut ( our compiler developer ) also has been threatening to take out the
-stack backchain in optimised code as this also causes pipeline stalls, you
-have been warned.
-
-64 bit z/Architecture code disassembly
---------------------------------------
-
-If you understand the stuff above you'll understand the stuff
-below too so I'll avoid repeating myself & just say that
-some of the instructions have g's on the end of them to indicate
-they are 64 bit & the stack offsets are a bigger,
-the only other difference you'll find between 32 & 64 bit is that
-we now use f4 & f6 for floating point arguments on 64 bit::
-
- 00000000800005b0 <test>:
- int test(int b)
- {
- return(5+b);
- 800005b0: a7 2a 00 05 ahi %r2,5
- 800005b4: b9 14 00 22 lgfr %r2,%r2 # downcast to integer
- 800005b8: 07 fe br %r14
- 800005ba: 07 07 bcr 0,%r7
-
-
- }
-
- 00000000800005bc <main>:
- main(int argc,char *argv[])
- {
- 800005bc: eb bf f0 58 00 24 stmg %r11,%r15,88(%r15)
- 800005c2: b9 04 00 1f lgr %r1,%r15
- 800005c6: a7 fb ff 60 aghi %r15,-160
- 800005ca: e3 10 f0 00 00 24 stg %r1,0(%r15)
- return(test(5));
- 800005d0: a7 29 00 05 lghi %r2,5
- # brasl allows jumps > 64k & is overkill here bras would do fune
- 800005d4: c0 e5 ff ff ff ee brasl %r14,800005b0 <test>
- 800005da: e3 40 f1 10 00 04 lg %r4,272(%r15)
- 800005e0: eb bf f0 f8 00 04 lmg %r11,%r15,248(%r15)
- 800005e6: 07 f4 br %r4
- }
-
-
-
-Compiling programs for debugging on Linux for s/390 & z/Architecture
-====================================================================
--gdwarf-2 now works it should be considered the default debugging
-format for s/390 & z/Architecture as it is more reliable for debugging
-shared libraries, normal -g debugging works much better now
-Thanks to the IBM java compiler developers bug reports.
-
-This is typically done adding/appending the flags -g or -gdwarf-2 to the
-CFLAGS & LDFLAGS variables Makefile of the program concerned.
-
-If using gdb & you would like accurate displays of registers &
-stack traces compile without optimisation i.e make sure
-that there is no -O2 or similar on the CFLAGS line of the Makefile &
-the emitted gcc commands, obviously this will produce worse code
-( not advisable for shipment ) but it is an aid to the debugging process.
-
-This aids debugging because the compiler will copy parameters passed in
-in registers onto the stack so backtracing & looking at passed in
-parameters will work, however some larger programs which use inline functions
-will not compile without optimisation.
-
-Debugging with optimisation has since much improved after fixing
-some bugs, please make sure you are using gdb-5.0 or later developed
-after Nov'2000.
-
-
-
-Debugging under VM
-==================
-
-Notes
------
-Addresses & values in the VM debugger are always hex never decimal
-Address ranges are of the format <HexValue1>-<HexValue2> or
-<HexValue1>.<HexValue2>
-For example, the address range 0x2000 to 0x3000 can be described as 2000-3000
-or 2000.1000
-
-The VM Debugger is case insensitive.
-
-VM's strengths are usually other debuggers weaknesses you can get at any
-resource no matter how sensitive e.g. memory management resources, change
-address translation in the PSW. For kernel hacking you will reap dividends if
-you get good at it.
-
-The VM Debugger displays operators but not operands, and also the debugger
-displays useful information on the same line as the author of the code probably
-felt that it was a good idea not to go over the 80 columns on the screen.
-This isn't as unintuitive as it may seem as the s/390 instructions are easy to
-decode mentally and you can make a good guess at a lot of them as all the
-operands are nibble (half byte aligned).
-So if you have an objdump listing by hand, it is quite easy to follow, and if
-you don't have an objdump listing keep a copy of the s/390 Reference Summary
-or alternatively the s/390 principles of operation next to you.
-e.g. even I can guess that
-0001AFF8' LR 180F CC 0
-is a ( load register ) lr r0,r15
-
-Also it is very easy to tell the length of a 390 instruction from the 2 most
-significant bits in the instruction (not that this info is really useful except
-if you are trying to make sense of a hexdump of code).
-Here is a table
-
-======================= ==================
-Bits Instruction Length
-======================= ==================
-00 2 Bytes
-01 4 Bytes
-10 4 Bytes
-11 6 Bytes
-======================= ==================
-
-The debugger also displays other useful info on the same line such as the
-addresses being operated on destination addresses of branches & condition codes.
-e.g.::
-
- 00019736' AHI A7DAFF0E CC 1
- 000198BA' BRC A7840004 -> 000198C2' CC 0
- 000198CE' STM 900EF068 >> 0FA95E78 CC 2
-
-
-
-Useful VM debugger commands
----------------------------
-
-I suppose I'd better mention this before I start
-to list the current active traces do::
-
- Q TR
-
-there can be a maximum of 255 of these per set
-( more about trace sets later ).
-
-To stop traces issue a::
-
- TR END.
-
-To delete a particular breakpoint issue::
-
- TR DEL <breakpoint number>
-
-The PA1 key drops to CP mode so you can issue debugger commands,
-Doing alt c (on my 3270 console at least ) clears the screen.
-
-hitting b <enter> comes back to the running operating system
-from cp mode ( in our case linux ).
-
-It is typically useful to add shortcuts to your profile.exec file
-if you have one ( this is roughly equivalent to autoexec.bat in DOS ).
-file here are a few from mine::
-
- /* this gives me command history on issuing f12 */
- set pf12 retrieve
- /* this continues */
- set pf8 imm b
- /* goes to trace set a */
- set pf1 imm tr goto a
- /* goes to trace set b */
- set pf2 imm tr goto b
- /* goes to trace set c */
- set pf3 imm tr goto c
-
-
-
-Instruction Tracing
--------------------
-Setting a simple breakpoint::
-
- TR I PSWA <address>
-
-To debug a particular function try::
-
- TR I R <function address range>
- TR I on its own will single step.
- TR I DATA <MNEMONIC> <OPTIONAL RANGE> will trace for particular mnemonics
-
-e.g.::
-
- TR I DATA 4D R 0197BC.4000
-
-will trace for BAS'es ( opcode 4D ) in the range 0197BC.4000
-
-if you were inclined you could add traces for all branch instructions &
-suffix them with the run prefix so you would have a backtrace on screen
-when a program crashes::
-
- TR BR <INTO OR FROM> will trace branches into or out of an address.
-
-e.g.::
-
- TR BR INTO 0
-
-is often quite useful if a program is getting awkward & deciding
-to branch to 0 & crashing as this will stop at the address before in jumps to 0.
-
-::
-
- TR I R <address range> RUN cmd d g
-
-single steps a range of addresses but stays running &
-displays the gprs on each step.
-
-
-
-Displaying & modifying Registers
---------------------------------
-D G
- will display all the gprs
-
-Adding a extra G to all the commands is necessary to access the full 64 bit
-content in VM on z/Architecture. Obviously this isn't required for access
-registers as these are still 32 bit.
-
-e.g.
-
-DGG
- instead of DG
-
-D X
- will display all the control registers
-D AR
- will display all the access registers
-D AR4-7
- will display access registers 4 to 7
-CPU ALL D G
- will display the GRPS of all CPUS in the configuration
-D PSW
- will display the current PSW
-st PSW 2000
- will put the value 2000 into the PSW & cause crash your machine.
-D PREFIX
- displays the prefix offset
-
-
-Displaying Memory
------------------
-To display memory mapped using the current PSW's mapping try::
-
- D <range>
-
-To make VM display a message each time it hits a particular address and
-continue try:
-
-D I<range>
- will disassemble/display a range of instructions.
-
-ST addr 32 bit word
- will store a 32 bit aligned address
-D T<range>
- will display the EBCDIC in an address (if you are that way inclined)
-D R<range>
- will display real addresses ( without DAT ) but with prefixing.
-
-There are other complex options to display if you need to get at say home space
-but are in primary space the easiest thing to do is to temporarily
-modify the PSW to the other addressing mode, display the stuff & then
-restore it.
-
-
-
-Hints
------
-If you want to issue a debugger command without halting your virtual machine
-with the PA1 key try prefixing the command with #CP e.g.::
-
- #cp tr i pswa 2000
-
-also suffixing most debugger commands with RUN will cause them not
-to stop just display the mnemonic at the current instruction on the console.
-
-If you have several breakpoints you want to put into your program &
-you get fed up of cross referencing with System.map
-you can do the following trick for several symbols.
-
-::
-
- grep do_signal System.map
-
-which emits the following among other things::
-
- 0001f4e0 T do_signal
-
-now you can do::
-
- TR I PSWA 0001f4e0 cmd msg * do_signal
-
-This sends a message to your own console each time do_signal is entered.
-( As an aside I wrote a perl script once which automatically generated a REXX
-script with breakpoints on every kernel procedure, this isn't a good idea
-because there are thousands of these routines & VM can only set 255 breakpoints
-at a time so you nearly had to spend as long pruning the file down as you would
-entering the msgs by hand), however, the trick might be useful for a single
-object file. In the 3270 terminal emulator x3270 there is a very useful option
-in the file menu called "Save Screen In File" - this is very good for keeping a
-copy of traces.
-
-From CMS help <command name> will give you online help on a particular command.
-e.g.::
-
- HELP DISPLAY
-
-Also CP has a file called profile.exec which automatically gets called
-on startup of CMS ( like autoexec.bat ), keeping on a DOS analogy session
-CP has a feature similar to doskey, it may be useful for you to
-use profile.exec to define some keystrokes.
-
-SET PF9 IMM B
- This does a single step in VM on pressing F8.
-
-SET PF10 ^
- This sets up the ^ key.
- which can be used for ^c (ctrl-c),^z (ctrl-z) which can't be typed
- directly into some 3270 consoles.
-
-SET PF11 ^-
- This types the starting keystrokes for a sysrq see SysRq below.
-SET PF12 RETRIEVE
- This retrieves command history on pressing F12.
-
-
-Sometimes in VM the display is set up to scroll automatically this
-can be very annoying if there are messages you wish to look at
-to stop this do
-
-TERM MORE 255 255
- This will nearly stop automatic screen updates, however it will
- cause a denial of service if lots of messages go to the 3270 console,
- so it would be foolish to use this as the default on a production machine.
-
-
-Tracing particular processes
-----------------------------
-The kernel's text segment is intentionally at an address in memory that it will
-very seldom collide with text segments of user programs ( thanks Martin ),
-this simplifies debugging the kernel.
-However it is quite common for user processes to have addresses which collide
-this can make debugging a particular process under VM painful under normal
-circumstances as the process may change when doing a::
-
- TR I R <address range>.
-
-Thankfully after reading VM's online help I figured out how to debug
-I particular process.
-
-Your first problem is to find the STD ( segment table designation )
-of the program you wish to debug.
-There are several ways you can do this here are a few
-
-Run::
-
- objdump --syms <program to be debugged> | grep main
-
-To get the address of main in the program. Then::
-
- tr i pswa <address of main>
-
-Start the program, if VM drops to CP on what looks like the entry
-point of the main function this is most likely the process you wish to debug.
-Now do a D X13 or D XG13 on z/Architecture.
-
-On 31 bit the STD is bits 1-19 ( the STO segment table origin )
-& 25-31 ( the STL segment table length ) of CR13.
-
-now type::
-
- TR I R STD <CR13's value> 0.7fffffff
-
-e.g.::
-
- TR I R STD 8F32E1FF 0.7fffffff
-
-Another very useful variation is::
-
- TR STORE INTO STD <CR13's value> <address range>
-
-for finding out when a particular variable changes.
-
-An alternative way of finding the STD of a currently running process
-is to do the following, ( this method is more complex but
-could be quite convenient if you aren't updating the kernel much &
-so your kernel structures will stay constant for a reasonable period of
-time ).
-
-::
-
- grep task /proc/<pid>/status
-
-from this you should see something like::
-
- task: 0f160000 ksp: 0f161de8 pt_regs: 0f161f68
-
-This now gives you a pointer to the task structure.
-
-Now make::
-
- CC:="s390-gcc -g" kernel/sched.s
-
-To get the task_struct stabinfo.
-
-( task_struct is defined in include/linux/sched.h ).
-
-Now we want to look at
-task->active_mm->pgd
-
-on my machine the active_mm in the task structure stab is
-active_mm:(4,12),672,32
-
-its offset is 672/8=84=0x54
-
-the pgd member in the mm_struct stab is
-pgd:(4,6)=*(29,5),96,32
-so its offset is 96/8=12=0xc
-
-so we'll::
-
- hexdump -s 0xf160054 /dev/mem | more
-
-i.e. task_struct+active_mm offset
-to look at the active_mm member::
-
- f160054 0fee cc60 0019 e334 0000 0000 0000 0011
-
-::
-
- hexdump -s 0x0feecc6c /dev/mem | more
-
-i.e. active_mm+pgd offset::
-
- feecc6c 0f2c 0000 0000 0001 0000 0001 0000 0010
-
-we get something like
-now do::
-
- TR I R STD <pgd|0x7f> 0.7fffffff
-
-i.e. the 0x7f is added because the pgd only
-gives the page table origin & we need to set the low bits
-to the maximum possible segment table length.
-
-::
-
- TR I R STD 0f2c007f 0.7fffffff
-
-on z/Architecture you'll probably need to do::
-
- TR I R STD <pgd|0x7> 0.ffffffffffffffff
-
-to set the TableType to 0x1 & the Table length to 3.
-
-
-
-Tracing Program Exceptions
---------------------------
-If you get a crash which says something like
-illegal operation or specification exception followed by a register dump
-You can restart linux & trace these using the tr prog <range or value> trace
-option.
-
-
-The most common ones you will normally be tracing for is:
-
-- 1=operation exception
-- 2=privileged operation exception
-- 4=protection exception
-- 5=addressing exception
-- 6=specification exception
-- 10=segment translation exception
-- 11=page translation exception
-
-The full list of these is on page 22 of the current s/390 Reference Summary.
-e.g.
-
-tr prog 10 will trace segment translation exceptions.
-
-tr prog on its own will trace all program interruption codes.
-
-Trace Sets
-----------
-On starting VM you are initially in the INITIAL trace set.
-You can do a Q TR to verify this.
-If you have a complex tracing situation where you wish to wait for instance
-till a driver is open before you start tracing IO, but know in your
-heart that you are going to have to make several runs through the code till you
-have a clue whats going on.
-
-What you can do is::
-
- TR I PSWA <Driver open address>
-
-hit b to continue till breakpoint
-
-reach the breakpoint
-
-now do your::
-
- TR GOTO B
- TR IO 7c08-7c09 inst int run
-
-or whatever the IO channels you wish to trace are & hit b
-
-To got back to the initial trace set do::
-
- TR GOTO INITIAL
-
-& the TR I PSWA <Driver open address> will be the only active breakpoint again.
-
-
-Tracing linux syscalls under VM
--------------------------------
-Syscalls are implemented on Linux for S390 by the Supervisor call instruction
-(SVC). There 256 possibilities of these as the instruction is made up of a 0xA
-opcode and the second byte being the syscall number. They are traced using the
-simple command::
-
- TR SVC <Optional value or range>
-
-the syscalls are defined in linux/arch/s390/include/asm/unistd.h
-e.g. to trace all file opens just do::
-
- TR SVC 5 ( as this is the syscall number of open )
-
-
-SMP Specific commands
----------------------
-To find out how many cpus you have
-Q CPUS displays all the CPU's available to your virtual machine
-To find the cpu that the current cpu VM debugger commands are being directed at
-do Q CPU to change the current cpu VM debugger commands are being directed at
-do::
-
- CPU <desired cpu no>
-
-On a SMP guest issue a command to all CPUs try prefixing the command with cpu
-all. To issue a command to a particular cpu try cpu <cpu number> e.g.::
-
- CPU 01 TR I R 2000.3000
-
-If you are running on a guest with several cpus & you have a IO related problem
-& cannot follow the flow of code but you know it isn't smp related.
-
-from the bash prompt issue::
-
- shutdown -h now or halt.
-
-do a::
-
- Q CPUS
-
-to find out how many cpus you have detach each one of them from cp except
-cpu 0 by issuing a::
-
- DETACH CPU 01-(number of cpus in configuration)
-
-& boot linux again.
-
-TR SIGP
- will trace inter processor signal processor instructions.
-
-DEFINE CPU 01-(number in configuration)
- will get your guests cpus back.
-
-
-Help for displaying ascii textstrings
--------------------------------------
-On the very latest VM Nucleus'es VM can now display ascii
-( thanks Neale for the hint ) by doing::
-
- D TX<lowaddr>.<len>
-
-e.g.::
-
- D TX0.100
-
-Alternatively
-=============
-Under older VM debuggers (I love EBDIC too) you can use following little
-program which converts a command line of hex digits to ascii text. It can be
-compiled under linux and you can copy the hex digits from your x3270 terminal
-to your xterm if you are debugging from a linuxbox.
-
-This is quite useful when looking at a parameter passed in as a text string
-under VM ( unless you are good at decoding ASCII in your head ).
-
-e.g. consider tracing an open syscall::
-
- TR SVC 5
-
-We have stopped at a breakpoint::
-
- 000151B0' SVC 0A05 -> 0001909A' CC 0
-
-D 20.8 to check the SVC old psw in the prefix area and see was it from userspace
-(for the layout of the prefix area consult the "Fixed Storage Locations"
-chapter of the s/390 Reference Summary if you have it available).
-
-::
-
- V00000020 070C2000 800151B2
-
-The problem state bit wasn't set & it's also too early in the boot sequence
-for it to be a userspace SVC if it was we would have to temporarily switch the
-psw to user space addressing so we could get at the first parameter of the open
-in gpr2.
-
-Next do a::
-
- D G2
- GPR 2 = 00014CB4
-
-Now display what gpr2 is pointing to::
-
- D 00014CB4.20
- V00014CB4 2F646576 2F636F6E 736F6C65 00001BF5
- V00014CC4 FC00014C B4001001 E0001000 B8070707
-
-Now copy the text till the first 00 hex ( which is the end of the string
-to an xterm & do hex2ascii on it::
-
- hex2ascii 2F646576 2F636F6E 736F6C65 00
-
-outputs::
-
- Decoded Hex:=/ d e v / c o n s o l e 0x00
-
-We were opening the console device,
-
-You can compile the code below yourself for practice :-),
-
-::
-
- /*
- * hex2ascii.c
- * a useful little tool for converting a hexadecimal command line to ascii
- *
- * Author(s): Denis Joseph Barrow (djbarrow@de.ibm.com,barrow_dj@yahoo.com)
- * (C) 2000 IBM Deutschland Entwicklung GmbH, IBM Corporation.
- */
- #include <stdio.h>
-
- int main(int argc,char *argv[])
- {
- int cnt1,cnt2,len,toggle=0;
- int startcnt=1;
- unsigned char c,hex;
-
- if(argc>1&&(strcmp(argv[1],"-a")==0))
- startcnt=2;
- printf("Decoded Hex:=");
- for(cnt1=startcnt;cnt1<argc;cnt1++)
- {
- len=strlen(argv[cnt1]);
- for(cnt2=0;cnt2<len;cnt2++)
- {
- c=argv[cnt1][cnt2];
- if(c>='0'&&c<='9')
- c=c-'0';
- if(c>='A'&&c<='F')
- c=c-'A'+10;
- if(c>='a'&&c<='f')
- c=c-'a'+10;
- switch(toggle)
- {
- case 0:
- hex=c<<4;
- toggle=1;
- break;
- case 1:
- hex+=c;
- if(hex<32||hex>127)
- {
- if(startcnt==1)
- printf("0x%02X ",(int)hex);
- else
- printf(".");
- }
- else
- {
- printf("%c",hex);
- if(startcnt==1)
- printf(" ");
- }
- toggle=0;
- break;
- }
- }
- }
- printf("\n");
- }
-
-
-
-
-Stack tracing under VM
-----------------------
-A basic backtrace
------------------
-
-Here are the tricks I use 9 out of 10 times it works pretty well,
-
-When your backchain reaches a dead end
---------------------------------------
-This can happen when an exception happens in the kernel and the kernel is
-entered twice. If you reach the NULL pointer at the end of the back chain you
-should be able to sniff further back if you follow the following tricks.
-1) A kernel address should be easy to recognise since it is in
-primary space & the problem state bit isn't set & also
-The Hi bit of the address is set.
-2) Another backchain should also be easy to recognise since it is an
-address pointing to another address approximately 100 bytes or 0x70 hex
-behind the current stackpointer.
-
-
-Here is some practice.
-
-boot the kernel & hit PA1 at some random time
-
-d g to display the gprs, this should display something like::
-
- GPR 0 = 00000001 00156018 0014359C 00000000
- GPR 4 = 00000001 001B8888 000003E0 00000000
- GPR 8 = 00100080 00100084 00000000 000FE000
- GPR 12 = 00010400 8001B2DC 8001B36A 000FFED8
-
-Note that GPR14 is a return address but as we are real men we are going to
-trace the stack.
-display 0x40 bytes after the stack pointer::
-
- V000FFED8 000FFF38 8001B838 80014C8E 000FFF38
- V000FFEE8 00000000 00000000 000003E0 00000000
- V000FFEF8 00100080 00100084 00000000 000FE000
- V000FFF08 00010400 8001B2DC 8001B36A 000FFED8
-
-
-Ah now look at whats in sp+56 (sp+0x38) this is 8001B36A our saved r14 if
-you look above at our stackframe & also agrees with GPR14.
-
-now backchain::
-
- d 000FFF38.40
-
-we now are taking the contents of SP to get our first backchain::
-
- V000FFF38 000FFFA0 00000000 00014995 00147094
- V000FFF48 00147090 001470A0 000003E0 00000000
- V000FFF58 00100080 00100084 00000000 001BF1D0
- V000FFF68 00010400 800149BA 80014CA6 000FFF38
-
-This displays a 2nd return address of 80014CA6
-
-now do::
-
- d 000FFFA0.40
-
-for our 3rd backchain::
-
- V000FFFA0 04B52002 0001107F 00000000 00000000
- V000FFFB0 00000000 00000000 FF000000 0001107F
- V000FFFC0 00000000 00000000 00000000 00000000
- V000FFFD0 00010400 80010802 8001085A 000FFFA0
-
-
-our 3rd return address is 8001085A
-
-as the 04B52002 looks suspiciously like rubbish it is fair to assume that the
-kernel entry routines for the sake of optimisation don't set up a backchain.
-
-now look at System.map to see if the addresses make any sense::
-
- grep -i 0001b3 System.map
-
-outputs among other things::
-
- 0001b304 T cpu_idle
-
-so 8001B36A
-is cpu_idle+0x66 ( quiet the cpu is asleep, don't wake it )
-
-::
-
- grep -i 00014 System.map
-
-produces among other things::
-
- 00014a78 T start_kernel
-
-so 0014CA6 is start_kernel+some hex number I can't add in my head.
-
-::
-
- grep -i 00108 System.map
-
-this produces::
-
- 00010800 T _stext
-
-so 8001085A is _stext+0x5a
-
-Congrats you've done your first backchain.
-
-
-
-s/390 & z/Architecture IO Overview
-==================================
-
-I am not going to give a course in 390 IO architecture as this would take me
-quite a while and I'm no expert. Instead I'll give a 390 IO architecture
-summary for Dummies. If you have the s/390 principles of operation available
-read this instead. If nothing else you may find a few useful keywords in here
-and be able to use them on a web search engine to find more useful information.
-
-Unlike other bus architectures modern 390 systems do their IO using mostly
-fibre optics and devices such as tapes and disks can be shared between several
-mainframes. Also S390 can support up to 65536 devices while a high end PC based
-system might be choking with around 64.
-
-Here is some of the common IO terminology:
-
-Subchannel:
- This is the logical number most IO commands use to talk to an IO device. There
- can be up to 0x10000 (65536) of these in a configuration, typically there are a
- few hundred. Under VM for simplicity they are allocated contiguously, however
- on the native hardware they are not. They typically stay consistent between
- boots provided no new hardware is inserted or removed.
-
- Under Linux for s390 we use these as IRQ's and also when issuing an IO command
- (CLEAR SUBCHANNEL, HALT SUBCHANNEL, MODIFY SUBCHANNEL, RESUME SUBCHANNEL,
- START SUBCHANNEL, STORE SUBCHANNEL and TEST SUBCHANNEL). We use this as the ID
- of the device we wish to talk to. The most important of these instructions are
- START SUBCHANNEL (to start IO), TEST SUBCHANNEL (to check whether the IO
- completed successfully) and HALT SUBCHANNEL (to kill IO). A subchannel can have
- up to 8 channel paths to a device, this offers redundancy if one is not
- available.
-
-Device Number:
- This number remains static and is closely tied to the hardware. There are 65536
- of these, made up of a CHPID (Channel Path ID, the most significant 8 bits) and
- another lsb 8 bits. These remain static even if more devices are inserted or
- removed from the hardware. There is a 1 to 1 mapping between subchannels and
- device numbers, provided devices aren't inserted or removed.
-
-Channel Control Words:
- CCWs are linked lists of instructions initially pointed to by an operation
- request block (ORB), which is initially given to Start Subchannel (SSCH)
- command along with the subchannel number for the IO subsystem to process
- while the CPU continues executing normal code.
- CCWs come in two flavours, Format 0 (24 bit for backward compatibility) and
- Format 1 (31 bit). These are typically used to issue read and write (and many
- other) instructions. They consist of a length field and an absolute address
- field.
-
- Each IO typically gets 1 or 2 interrupts, one for channel end (primary status)
- when the channel is idle, and the second for device end (secondary status).
- Sometimes you get both concurrently. You check how the IO went on by issuing a
- TEST SUBCHANNEL at each interrupt, from which you receive an Interruption
- response block (IRB). If you get channel and device end status in the IRB
- without channel checks etc. your IO probably went okay. If you didn't you
- probably need to examine the IRB, extended status word etc.
- If an error occurs, more sophisticated control units have a facility known as
- concurrent sense. This means that if an error occurs Extended sense information
- will be presented in the Extended status word in the IRB. If not you have to
- issue a subsequent SENSE CCW command after the test subchannel.
-
-
-TPI (Test pending interrupt) can also be used for polled IO, but in
-multitasking multiprocessor systems it isn't recommended except for
-checking special cases (i.e. non looping checks for pending IO etc.).
-
-Store Subchannel and Modify Subchannel can be used to examine and modify
-operating characteristics of a subchannel (e.g. channel paths).
-
-Other IO related Terms:
-
-Sysplex:
- S390's Clustering Technology
-QDIO:
- S390's new high speed IO architecture to support devices such as gigabit
- ethernet, this architecture is also designed to be forward compatible with
- upcoming 64 bit machines.
-
-
-General Concepts
-----------------
-
-Input Output Processors (IOP's) are responsible for communicating between
-the mainframe CPU's & the channel & relieve the mainframe CPU's from the
-burden of communicating with IO devices directly, this allows the CPU's to
-concentrate on data processing.
-
-IOP's can use one or more links ( known as channel paths ) to talk to each
-IO device. It first checks for path availability & chooses an available one,
-then starts ( & sometimes terminates IO ).
-There are two types of channel path: ESCON & the Parallel IO interface.
-
-IO devices are attached to control units, control units provide the
-logic to interface the channel paths & channel path IO protocols to
-the IO devices, they can be integrated with the devices or housed separately
-& often talk to several similar devices ( typical examples would be raid
-controllers or a control unit which connects to 1000 3270 terminals )::
-
-
- +---------------------------------------------------------------+
- | +-----+ +-----+ +-----+ +-----+ +----------+ +----------+ |
- | | CPU | | CPU | | CPU | | CPU | | Main | | Expanded | |
- | | | | | | | | | | Memory | | Storage | |
- | +-----+ +-----+ +-----+ +-----+ +----------+ +----------+ |
- |---------------------------------------------------------------+
- | IOP | IOP | IOP |
- |---------------------------------------------------------------
- | C | C | C | C | C | C | C | C | C | C | C | C | C | C | C | C |
- ----------------------------------------------------------------
- || ||
- || Bus & Tag Channel Path || ESCON
- || ====================== || Channel
- || || || || Path
- +----------+ +----------+ +----------+
- | | | | | |
- | CU | | CU | | CU |
- | | | | | |
- +----------+ +----------+ +----------+
- | | | | |
- +----------+ +----------+ +----------+ +----------+ +----------+
- |I/O Device| |I/O Device| |I/O Device| |I/O Device| |I/O Device|
- +----------+ +----------+ +----------+ +----------+ +----------+
- CPU = Central Processing Unit
- C = Channel
- IOP = IP Processor
- CU = Control Unit
-
-The 390 IO systems come in 2 flavours the current 390 machines support both
-
-The Older 360 & 370 Interface,sometimes called the Parallel I/O interface,
-sometimes called Bus-and Tag & sometimes Original Equipment Manufacturers
-Interface (OEMI).
-
-This byte wide Parallel channel path/bus has parity & data on the "Bus" cable
-and control lines on the "Tag" cable. These can operate in byte multiplex mode
-for sharing between several slow devices or burst mode and monopolize the
-channel for the whole burst. Up to 256 devices can be addressed on one of these
-cables. These cables are about one inch in diameter. The maximum unextended
-length supported by these cables is 125 Meters but this can be extended up to
-2km with a fibre optic channel extended such as a 3044. The maximum burst speed
-supported is 4.5 megabytes per second. However, some really old processors
-support only transfer rates of 3.0, 2.0 & 1.0 MB/sec.
-One of these paths can be daisy chained to up to 8 control units.
-
-
-ESCON if fibre optic it is also called FICON
-Was introduced by IBM in 1990. Has 2 fibre optic cables and uses either leds or
-lasers for communication at a signaling rate of up to 200 megabits/sec. As
-10bits are transferred for every 8 bits info this drops to 160 megabits/sec
-and to 18.6 Megabytes/sec once control info and CRC are added. ESCON only
-operates in burst mode.
-
-ESCONs typical max cable length is 3km for the led version and 20km for the
-laser version known as XDF (extended distance facility). This can be further
-extended by using an ESCON director which triples the above mentioned ranges.
-Unlike Bus & Tag as ESCON is serial it uses a packet switching architecture,
-the standard Bus & Tag control protocol is however present within the packets.
-Up to 256 devices can be attached to each control unit that uses one of these
-interfaces.
-
-Common 390 Devices include:
-Network adapters typically OSA2,3172's,2116's & OSA-E gigabit ethernet adapters,
-Consoles 3270 & 3215 (a teletype emulated under linux for a line mode console).
-DASD's direct access storage devices ( otherwise known as hard disks ).
-Tape Drives.
-CTC ( Channel to Channel Adapters ),
-ESCON or Parallel Cables used as a very high speed serial link
-between 2 machines.
-
-
-Debugging IO on s/390 & z/Architecture under VM
-===============================================
-
-Now we are ready to go on with IO tracing commands under VM
-
-A few self explanatory queries::
-
- Q OSA
- Q CTC
- Q DISK ( This command is CMS specific )
- Q DASD
-
-Q OSA on my machine returns::
-
- OSA 7C08 ON OSA 7C08 SUBCHANNEL = 0000
- OSA 7C09 ON OSA 7C09 SUBCHANNEL = 0001
- OSA 7C14 ON OSA 7C14 SUBCHANNEL = 0002
- OSA 7C15 ON OSA 7C15 SUBCHANNEL = 0003
-
-If you have a guest with certain privileges you may be able to see devices
-which don't belong to you. To avoid this, add the option V.
-e.g.::
-
- Q V OSA
-
-Now using the device numbers returned by this command we will
-Trace the io starting up on the first device 7c08 & 7c09
-In our simplest case we can trace the
-start subchannels
-like TR SSCH 7C08-7C09
-or the halt subchannels
-or TR HSCH 7C08-7C09
-MSCH's ,STSCH's I think you can guess the rest
-
-A good trick is tracing all the IO's and CCWS and spooling them into the reader
-of another VM guest so he can ftp the logfile back to his own machine. I'll do
-a small bit of this and give you a look at the output.
-
-1) Spool stdout to VM reader::
-
- SP PRT TO (another vm guest ) or * for the local vm guest
-
-2) Fill the reader with the trace::
-
- TR IO 7c08-7c09 INST INT CCW PRT RUN
-
-3) Start up linux::
-
- i 00c
-4) Finish the trace::
-
- TR END
-
-5) close the reader::
-
- C PRT
-
-6) list reader contents::
-
- RDRLIST
-
-7) copy it to linux4's minidisk::
-
- RECEIVE / LOG TXT A1 ( replace
-
-8)
-filel & press F11 to look at it
-You should see something like::
-
- 00020942' SSCH B2334000 0048813C CC 0 SCH 0000 DEV 7C08
- CPA 000FFDF0 PARM 00E2C9C4 KEY 0 FPI C0 LPM 80
- CCW 000FFDF0 E4200100 00487FE8 0000 E4240100 ........
- IDAL 43D8AFE8
- IDAL 0FB76000
- 00020B0A' I/O DEV 7C08 -> 000197BC' SCH 0000 PARM 00E2C9C4
- 00021628' TSCH B2354000 >> 00488164 CC 0 SCH 0000 DEV 7C08
- CCWA 000FFDF8 DEV STS 0C SCH STS 00 CNT 00EC
- KEY 0 FPI C0 CC 0 CTLS 4007
- 00022238' STSCH B2344000 >> 00488108 CC 0 SCH 0000 DEV 7C08
-
-If you don't like messing up your readed ( because you possibly booted from it )
-you can alternatively spool it to another readers guest.
-
-
-Other common VM device related commands
----------------------------------------------
-These commands are listed only because they have
-been of use to me in the past & may be of use to
-you too. For more complete info on each of the commands
-use type HELP <command> from CMS.
-
-detaching devices::
-
- DET <devno range>
- ATT <devno range> <guest>
-
-attach a device to guest * for your own guest
-
-READY <devno>
- cause VM to issue a fake interrupt.
-
-The VARY command is normally only available to VM administrators::
-
- VARY ON PATH <path> TO <devno range>
- VARY OFF PATH <PATH> FROM <devno range>
-
-This is used to switch on or off channel paths to devices.
-
-Q CHPID <channel path ID>
- This displays state of devices using this channel path
-
-D SCHIB <subchannel>
- This displays the subchannel information SCHIB block for the device.
- this I believe is also only available to administrators.
-
-DEFINE CTC <devno>
- defines a virtual CTC channel to channel connection
- 2 need to be defined on each guest for the CTC driver to use.
-
-COUPLE devno userid remote devno
- Joins a local virtual device to a remote virtual device
- ( commonly used for the CTC driver ).
-
-Building a VM ramdisk under CMS which linux can use::
-
- def vfb-<blocksize> <subchannel> <number blocks>
-
-blocksize is commonly 4096 for linux.
-
-Formatting it::
-
- format <subchannel> <driver letter e.g. x> (blksize <blocksize>
-
-Sharing a disk between multiple guests::
-
- LINK userid devno1 devno2 mode password
-
-
-
-GDB on S390
-===========
-N.B. if compiling for debugging gdb works better without optimisation
-( see Compiling programs for debugging )
-
-invocation
-----------
-gdb <victim program> <optional corefile>
-
-Online help
------------
-help: gives help on commands
-
-e.g.::
-
- help
- help display
-
-Note gdb's online help is very good use it.
-
-
-Assembly
---------
-info registers:
- displays registers other than floating point.
-
-info all-registers:
- displays floating points as well.
-
-disassemble:
- disassembles
-
-e.g.::
-
- disassemble without parameters will disassemble the current function
- disassemble $pc $pc+10
-
-Viewing & modifying variables
------------------------------
-print or p:
- displays variable or register
-
-e.g. p/x $sp will display the stack pointer
-
-display:
- prints variable or register each time program stops
-
-e.g.::
-
- display/x $pc will display the program counter
- display argc
-
-undisplay:
- undo's display's
-
-info breakpoints:
- shows all current breakpoints
-
-info stack:
- shows stack back trace (if this doesn't work too well, I'll show
- you the stacktrace by hand below).
-
-info locals:
- displays local variables.
-
-info args:
- display current procedure arguments.
-
-set args:
- will set argc & argv each time the victim program is invoked
-
-e.g.::
-
- set <variable>=value
- set argc=100
- set $pc=0
-
-
-
-Modifying execution
--------------------
-step:
- steps n lines of sourcecode
-
-step
- steps 1 line.
-
-step 100
- steps 100 lines of code.
-
-next:
- like step except this will not step into subroutines
-
-stepi:
- steps a single machine code instruction.
-
-e.g.::
-
- stepi 100
-
-nexti:
- steps a single machine code instruction but will not step into
- subroutines.
-
-finish:
- will run until exit of the current routine
-
-run:
- (re)starts a program
-
-cont:
- continues a program
-
-quit:
- exits gdb.
-
-
-breakpoints
-------------
-
-break
- sets a breakpoint
-
-e.g.::
-
- break main
- break *$pc
- break *0x400618
-
-Here's a really useful one for large programs
-
-rbr
- Set a breakpoint for all functions matching REGEXP
-
-e.g.::
-
- rbr 390
-
-will set a breakpoint with all functions with 390 in their name.
-
-info breakpoints
- lists all breakpoints
-
-delete:
- delete breakpoint by number or delete them all
-
-e.g.
-
-delete 1
- will delete the first breakpoint
-
-
-delete
- will delete them all
-
-watch:
- This will set a watchpoint ( usually hardware assisted ),
-
-This will watch a variable till it changes
-
-e.g.
-
-watch cnt
- will watch the variable cnt till it changes.
-
-As an aside unfortunately gdb's, architecture independent watchpoint code
-is inconsistent & not very good, watchpoints usually work but not always.
-
-info watchpoints:
- Display currently active watchpoints
-
-condition: ( another useful one )
- Specify breakpoint number N to break only if COND is true.
-
-Usage is `condition N COND`, where N is an integer and COND is an
-expression to be evaluated whenever breakpoint N is reached.
-
-
-
-User defined functions/macros
------------------------------
-define: ( Note this is very very useful,simple & powerful )
-
-usage define <name> <list of commands> end
-
-examples which you should consider putting into .gdbinit in your home
-directory::
-
- define d
- stepi
- disassemble $pc $pc+10
- end
- define e
- nexti
- disassemble $pc $pc+10
- end
-
-
-Other hard to classify stuff
-----------------------------
-signal n:
- sends the victim program a signal.
-
-e.g. `signal 3` will send a SIGQUIT.
-
-info signals:
- what gdb does when the victim receives certain signals.
-
-list:
-
-e.g.:
-
-list
- lists current function source
-list 1,10
- list first 10 lines of current file.
-
-list test.c:1,10
-
-
-directory:
- Adds directories to be searched for source if gdb cannot find the source.
- (note it is a bit sensitive about slashes)
-
-e.g. To add the root of the filesystem to the searchpath do::
-
- directory //
-
-
-call <function>
-This calls a function in the victim program, this is pretty powerful
-e.g.
-(gdb) call printf("hello world")
-outputs:
-$1 = 11
-
-You might now be thinking that the line above didn't work, something extra had
-to be done.
-(gdb) call fflush(stdout)
-hello world$2 = 0
-As an aside the debugger also calls malloc & free under the hood
-to make space for the "hello world" string.
-
-
-
-hints
------
-1) command completion works just like bash
- ( if you are a bad typist like me this really helps )
-
-e.g. hit br <TAB> & cursor up & down :-).
-
-2) if you have a debugging problem that takes a few steps to recreate
-put the steps into a file called .gdbinit in your current working directory
-if you have defined a few extra useful user defined commands put these in
-your home directory & they will be read each time gdb is launched.
-
-A typical .gdbinit file might be.::
-
- break main
- run
- break runtime_exception
- cont
-
-
-stack chaining in gdb by hand
------------------------------
-This is done using a the same trick described for VM::
-
- p/x (*($sp+56))&0x7fffffff
-
-get the first backchain.
-
-For z/Architecture
-Replace 56 with 112 & ignore the &0x7fffffff
-in the macros below & do nasty casts to longs like the following
-as gdb unfortunately deals with printed arguments as ints which
-messes up everything.
-
-i.e. here is a 3rd backchain dereference::
-
- p/x *(long *)(***(long ***)$sp+112)
-
-
-this outputs::
-
- $5 = 0x528f18
-
-on my machine.
-
-Now you can use::
-
- info symbol (*($sp+56))&0x7fffffff
-
-you might see something like::
-
- rl_getc + 36 in section .text
-
-telling you what is located at address 0x528f18
-Now do::
-
- p/x (*(*$sp+56))&0x7fffffff
-
-This outputs::
-
- $6 = 0x528ed0
-
-Now do::
-
- info symbol (*(*$sp+56))&0x7fffffff
- rl_read_key + 180 in section .text
-
-now do::
-
- p/x (*(**$sp+56))&0x7fffffff
-
-& so on.
-
-Disassembling instructions without debug info
----------------------------------------------
-gdb typically complains if there is a lack of debugging
-symbols in the disassemble command with
-"No function contains specified address." To get around
-this do::
-
- x/<number lines to disassemble>xi <address>
-
-e.g.::
-
- x/20xi 0x400730
-
-
-
-Note:
- Remember gdb has history just like bash you don't need to retype the
- whole line just use the up & down arrows.
-
-
-
-For more info
--------------
-From your linuxbox do::
-
- man gdb
-
-or::
-
- info gdb.
-
-core dumps
-----------
-
-What a core dump ?
-^^^^^^^^^^^^^^^^^^
-
-A core dump is a file generated by the kernel (if allowed) which contains the
-registers and all active pages of the program which has crashed.
-
-From this file gdb will allow you to look at the registers, stack trace and
-memory of the program as if it just crashed on your system. It is usually
-called core and created in the current working directory.
-
-This is very useful in that a customer can mail a core dump to a technical
-support department and the technical support department can reconstruct what
-happened. Provided they have an identical copy of this program with debugging
-symbols compiled in and the source base of this build is available.
-
-In short it is far more useful than something like a crash log could ever hope
-to be.
-
-Why have I never seen one ?
-^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Probably because you haven't used the command::
-
- ulimit -c unlimited in bash
-
-to allow core dumps, now do::
-
- ulimit -a
-
-to verify that the limit was accepted.
-
-A sample core dump
- To create this I'm going to do::
-
- ulimit -c unlimited
- gdb
-
-to launch gdb (my victim app. ) now be bad & do the following from another
-telnet/xterm session to the same machine::
-
- ps -aux | grep gdb
- kill -SIGSEGV <gdb's pid>
-
-or alternatively use `killall -SIGSEGV gdb` if you have the killall command.
-
-Now look at the core dump::
-
- ./gdb core
-
-Displays the following::
-
- GNU gdb 4.18
- Copyright 1998 Free Software Foundation, Inc.
- GDB is free software, covered by the GNU General Public License, and you are
- welcome to change it and/or distribute copies of it under certain conditions.
- Type "show copying" to see the conditions.
- There is absolutely no warranty for GDB. Type "show warranty" for details.
- This GDB was configured as "s390-ibm-linux"...
- Core was generated by `./gdb'.
- Program terminated with signal 11, Segmentation fault.
- Reading symbols from /usr/lib/libncurses.so.4...done.
- Reading symbols from /lib/libm.so.6...done.
- Reading symbols from /lib/libc.so.6...done.
- Reading symbols from /lib/ld-linux.so.2...done.
- #0 0x40126d1a in read () from /lib/libc.so.6
- Setting up the environment for debugging gdb.
- Breakpoint 1 at 0x4dc6f8: file utils.c, line 471.
- Breakpoint 2 at 0x4d87a4: file top.c, line 2609.
- (top-gdb) info stack
- #0 0x40126d1a in read () from /lib/libc.so.6
- #1 0x528f26 in rl_getc (stream=0x7ffffde8) at input.c:402
- #2 0x528ed0 in rl_read_key () at input.c:381
- #3 0x5167e6 in readline_internal_char () at readline.c:454
- #4 0x5168ee in readline_internal_charloop () at readline.c:507
- #5 0x51692c in readline_internal () at readline.c:521
- #6 0x5164fe in readline (prompt=0x7ffff810)
- at readline.c:349
- #7 0x4d7a8a in command_line_input (prompt=0x564420 "(gdb) ", repeat=1,
- annotation_suffix=0x4d6b44 "prompt") at top.c:2091
- #8 0x4d6cf0 in command_loop () at top.c:1345
- #9 0x4e25bc in main (argc=1, argv=0x7ffffdf4) at main.c:635
-
-
-LDD
-===
-This is a program which lists the shared libraries which a library needs,
-Note you also get the relocations of the shared library text segments which
-help when using objdump --source.
-
-e.g.::
-
- ldd ./gdb
-
-outputs::
-
- libncurses.so.4 => /usr/lib/libncurses.so.4 (0x40018000)
- libm.so.6 => /lib/libm.so.6 (0x4005e000)
- libc.so.6 => /lib/libc.so.6 (0x40084000)
- /lib/ld-linux.so.2 => /lib/ld-linux.so.2 (0x40000000)
-
-
-Debugging shared libraries
-==========================
-Most programs use shared libraries, however it can be very painful
-when you single step instruction into a function like printf for the
-first time & you end up in functions like _dl_runtime_resolve this is
-the ld.so doing lazy binding, lazy binding is a concept in ELF where
-shared library functions are not loaded into memory unless they are
-actually used, great for saving memory but a pain to debug.
-
-To get around this either relink the program -static or exit gdb type
-export LD_BIND_NOW=true this will stop lazy binding & restart the gdb'ing
-the program in question.
-
-
-
-Debugging modules
-=================
-As modules are dynamically loaded into the kernel their address can be
-anywhere to get around this use the -m option with insmod to emit a load
-map which can be piped into a file if required.
-
-The proc file system
-====================
-What is it ?.
-It is a filesystem created by the kernel with files which are created on demand
-by the kernel if read, or can be used to modify kernel parameters,
-it is a powerful concept.
-
-e.g.::
-
- cat /proc/sys/net/ipv4/ip_forward
-
-On my machine outputs::
-
- 0
-
-telling me ip_forwarding is not on to switch it on I can do::
-
- echo 1 > /proc/sys/net/ipv4/ip_forward
-
-cat it again::
-
- cat /proc/sys/net/ipv4/ip_forward
-
-On my machine now outputs::
-
- 1
-
-IP forwarding is on.
-
-There is a lot of useful info in here best found by going in and having a look
-around, so I'll take you through some entries I consider important.
-
-All the processes running on the machine have their own entry defined by
-/proc/<pid>
-
-So lets have a look at the init process::
-
- cd /proc/1
- cat cmdline
-
-emits::
-
- init [2]
-
-::
-
- cd /proc/1/fd
-
-This contains numerical entries of all the open files,
-some of these you can cat e.g. stdout (2)::
-
- cat /proc/29/maps
-
-on my machine emits::
-
- 00400000-00478000 r-xp 00000000 5f:00 4103 /bin/bash
- 00478000-0047e000 rw-p 00077000 5f:00 4103 /bin/bash
- 0047e000-00492000 rwxp 00000000 00:00 0
- 40000000-40015000 r-xp 00000000 5f:00 14382 /lib/ld-2.1.2.so
- 40015000-40016000 rw-p 00014000 5f:00 14382 /lib/ld-2.1.2.so
- 40016000-40017000 rwxp 00000000 00:00 0
- 40017000-40018000 rw-p 00000000 00:00 0
- 40018000-4001b000 r-xp 00000000 5f:00 14435 /lib/libtermcap.so.2.0.8
- 4001b000-4001c000 rw-p 00002000 5f:00 14435 /lib/libtermcap.so.2.0.8
- 4001c000-4010d000 r-xp 00000000 5f:00 14387 /lib/libc-2.1.2.so
- 4010d000-40111000 rw-p 000f0000 5f:00 14387 /lib/libc-2.1.2.so
- 40111000-40114000 rw-p 00000000 00:00 0
- 40114000-4011e000 r-xp 00000000 5f:00 14408 /lib/libnss_files-2.1.2.so
- 4011e000-4011f000 rw-p 00009000 5f:00 14408 /lib/libnss_files-2.1.2.so
- 7fffd000-80000000 rwxp ffffe000 00:00 0
-
-
-Showing us the shared libraries init uses where they are in memory
-& memory access permissions for each virtual memory area.
-
-/proc/1/cwd is a softlink to the current working directory.
-
-/proc/1/root is the root of the filesystem for this process.
-
-/proc/1/mem is the current running processes memory which you
-can read & write to like a file.
-
-strace uses this sometimes as it is a bit faster than the
-rather inefficient ptrace interface for peeking at DATA.
-
-::
-
- cat status
-
- Name: init
- State: S (sleeping)
- Pid: 1
- PPid: 0
- Uid: 0 0 0 0
- Gid: 0 0 0 0
- Groups:
- VmSize: 408 kB
- VmLck: 0 kB
- VmRSS: 208 kB
- VmData: 24 kB
- VmStk: 8 kB
- VmExe: 368 kB
- VmLib: 0 kB
- SigPnd: 0000000000000000
- SigBlk: 0000000000000000
- SigIgn: 7fffffffd7f0d8fc
- SigCgt: 00000000280b2603
- CapInh: 00000000fffffeff
- CapPrm: 00000000ffffffff
- CapEff: 00000000fffffeff
-
- User PSW: 070de000 80414146
- task: 004b6000 tss: 004b62d8 ksp: 004b7ca8 pt_regs: 004b7f68
- User GPRS:
- 00000400 00000000 0000000b 7ffffa90
- 00000000 00000000 00000000 0045d9f4
- 0045cafc 7ffffa90 7fffff18 0045cb08
- 00010400 804039e8 80403af8 7ffff8b0
- User ACRS:
- 00000000 00000000 00000000 00000000
- 00000001 00000000 00000000 00000000
- 00000000 00000000 00000000 00000000
- 00000000 00000000 00000000 00000000
- Kernel BackChain CallChain BackChain CallChain
- 004b7ca8 8002bd0c 004b7d18 8002b92c
- 004b7db8 8005cd50 004b7e38 8005d12a
- 004b7f08 80019114
-
-Showing among other things memory usage & status of some signals &
-the processes'es registers from the kernel task_structure
-as well as a backchain which may be useful if a process crashes
-in the kernel for some unknown reason.
-
-Some driver debugging techniques
-================================
-debug feature
--------------
-Some of our drivers now support a "debug feature" in
-/proc/s390dbf see s390dbf.txt in the linux/Documentation directory
-for more info.
-
-e.g.
-to switch on the lcs "debug feature"::
-
- echo 5 > /proc/s390dbf/lcs/level
-
-& then after the error occurred::
-
- cat /proc/s390dbf/lcs/sprintf >/logfile
-
-the logfile now contains some information which may help
-tech support resolve a problem in the field.
-
-
-
-high level debugging network drivers
-------------------------------------
-ifconfig is a quite useful command
-it gives the current state of network drivers.
-
-If you suspect your network device driver is dead
-one way to check is type::
-
- ifconfig <network device>
-
-e.g. tr0
-
-You should see something like::
-
- ifconfig tr0
- tr0 Link encap:16/4 Mbps Token Ring (New) HWaddr 00:04:AC:20:8E:48
- inet addr:9.164.185.132 Bcast:9.164.191.255 Mask:255.255.224.0
- UP BROADCAST RUNNING MULTICAST MTU:2000 Metric:1
- RX packets:246134 errors:0 dropped:0 overruns:0 frame:0
- TX packets:5 errors:0 dropped:0 overruns:0 carrier:0
- collisions:0 txqueuelen:100
-
-if the device doesn't say up
-try::
-
- /etc/rc.d/init.d/network start
-
-( this starts the network stack & hopefully calls ifconfig tr0 up ).
-ifconfig looks at the output of /proc/net/dev and presents it in a more
-presentable form.
-
-Now ping the device from a machine in the same subnet.
-
-if the RX packets count & TX packets counts don't increment you probably
-have problems.
-
-next::
-
- cat /proc/net/arp
-
-Do you see any hardware addresses in the cache if not you may have problems.
-Next try::
-
- ping -c 5 <broadcast_addr>
-
-i.e. the Bcast field above in the output of
-ifconfig. Do you see any replies from machines other than the local machine
-if not you may have problems. also if the TX packets count in ifconfig
-hasn't incremented either you have serious problems in your driver
-(e.g. the txbusy field of the network device being stuck on )
-or you may have multiple network devices connected.
-
-
-chandev
--------
-There is a new device layer for channel devices, some
-drivers e.g. lcs are registered with this layer.
-
-If the device uses the channel device layer you'll be
-able to find what interrupts it uses & the current state
-of the device.
-
-See the manpage chandev.8 &type cat /proc/chandev for more info.
-
-
-SysRq
-=====
-This is now supported by linux for s/390 & z/Architecture.
-
-To enable it do compile the kernel with::
-
- Kernel Hacking -> Magic SysRq Key Enabled
-
-Then::
-
- echo "1" > /proc/sys/kernel/sysrq
-
-also type::
-
- echo "8" >/proc/sys/kernel/printk
-
-To make printk output go to console.
-
-On 390 all commands are prefixed with::
-
- ^-
-
-e.g.::
-
- ^-t will show tasks.
- ^-? or some unknown command will display help.
-
-The sysrq key reading is very picky ( I have to type the keys in an
-xterm session & paste them into the x3270 console )
-& it may be wise to predefine the keys as described in the VM hints above
-
-This is particularly useful for syncing disks unmounting & rebooting
-if the machine gets partially hung.
-
-Read Documentation/admin-guide/sysrq.rst for more info
-
-References:
-===========
-- Enterprise Systems Architecture Reference Summary
-- Enterprise Systems Architecture Principles of Operation
-- Hartmut Penners s390 stack frame sheet.
-- IBM Mainframe Channel Attachment a technology brief from a CISCO webpage
-- Various bits of man & info pages of Linux.
-- Linux & GDB source.
-- Various info & man pages.
-- CMS Help on tracing commands.
-- Linux for s/390 Elf Application Binary Interface
-- Linux for z/Series Elf Application Binary Interface ( Both Highly Recommended )
-- z/Architecture Principles of Operation SA22-7832-00
-- Enterprise Systems Architecture/390 Reference Summary SA22-7209-01 & the
-- Enterprise Systems Architecture/390 Principles of Operation SA22-7201-05
-
-Special Thanks
-==============
-Special thanks to Neale Ferguson who maintains a much
-prettier HTML version of this page at
-http://linuxvm.org/penguinvm/
-Bob Grainger Stefan Bader & others for reporting bugs
diff --git a/Documentation/s390/index.rst b/Documentation/s390/index.rst
index 4602312..f7af206 100644
--- a/Documentation/s390/index.rst
+++ b/Documentation/s390/index.rst
@@ -7,7 +7,6 @@
cds
3270
- debugging390
driver-model
monreader
qeth
@@ -15,7 +14,6 @@
vfio-ap
vfio-ccw
zfcpdump
- dasd
common_io
text_files
diff --git a/Documentation/scheduler/sched-bwc.rst b/Documentation/scheduler/sched-bwc.rst
index 3a90642..9801d6b 100644
--- a/Documentation/scheduler/sched-bwc.rst
+++ b/Documentation/scheduler/sched-bwc.rst
@@ -9,15 +9,16 @@
specification of the maximum CPU bandwidth available to a group or hierarchy.
The bandwidth allowed for a group is specified using a quota and period. Within
-each given "period" (microseconds), a group is allowed to consume only up to
-"quota" microseconds of CPU time. When the CPU bandwidth consumption of a
-group exceeds this limit (for that period), the tasks belonging to its
-hierarchy will be throttled and are not allowed to run again until the next
-period.
+each given "period" (microseconds), a task group is allocated up to "quota"
+microseconds of CPU time. That quota is assigned to per-cpu run queues in
+slices as threads in the cgroup become runnable. Once all quota has been
+assigned any additional requests for quota will result in those threads being
+throttled. Throttled threads will not be able to run again until the next
+period when the quota is replenished.
-A group's unused runtime is globally tracked, being refreshed with quota units
-above at each period boundary. As threads consume this bandwidth it is
-transferred to cpu-local "silos" on a demand basis. The amount transferred
+A group's unassigned quota is globally tracked, being refreshed back to
+cfs_quota units at each period boundary. As threads consume this bandwidth it
+is transferred to cpu-local "silos" on a demand basis. The amount transferred
within each of these updates is tunable and described as the "slice".
Management
@@ -35,12 +36,12 @@
A value of -1 for cpu.cfs_quota_us indicates that the group does not have any
bandwidth restriction in place, such a group is described as an unconstrained
-bandwidth group. This represents the traditional work-conserving behavior for
+bandwidth group. This represents the traditional work-conserving behavior for
CFS.
Writing any (valid) positive value(s) will enact the specified bandwidth limit.
-The minimum quota allowed for the quota or period is 1ms. There is also an
-upper bound on the period length of 1s. Additional restrictions exist when
+The minimum quota allowed for the quota or period is 1ms. There is also an
+upper bound on the period length of 1s. Additional restrictions exist when
bandwidth limits are used in a hierarchical fashion, these are explained in
more detail below.
@@ -53,8 +54,8 @@
System wide settings
--------------------
For efficiency run-time is transferred between the global pool and CPU local
-"silos" in a batch fashion. This greatly reduces global accounting pressure
-on large systems. The amount transferred each time such an update is required
+"silos" in a batch fashion. This greatly reduces global accounting pressure
+on large systems. The amount transferred each time such an update is required
is described as the "slice".
This is tunable via procfs::
@@ -97,6 +98,51 @@
In case b) above, even though the child may have runtime remaining it will not
be allowed to until the parent's runtime is refreshed.
+CFS Bandwidth Quota Caveats
+---------------------------
+Once a slice is assigned to a cpu it does not expire. However all but 1ms of
+the slice may be returned to the global pool if all threads on that cpu become
+unrunnable. This is configured at compile time by the min_cfs_rq_runtime
+variable. This is a performance tweak that helps prevent added contention on
+the global lock.
+
+The fact that cpu-local slices do not expire results in some interesting corner
+cases that should be understood.
+
+For cgroup cpu constrained applications that are cpu limited this is a
+relatively moot point because they will naturally consume the entirety of their
+quota as well as the entirety of each cpu-local slice in each period. As a
+result it is expected that nr_periods roughly equal nr_throttled, and that
+cpuacct.usage will increase roughly equal to cfs_quota_us in each period.
+
+For highly-threaded, non-cpu bound applications this non-expiration nuance
+allows applications to briefly burst past their quota limits by the amount of
+unused slice on each cpu that the task group is running on (typically at most
+1ms per cpu or as defined by min_cfs_rq_runtime). This slight burst only
+applies if quota had been assigned to a cpu and then not fully used or returned
+in previous periods. This burst amount will not be transferred between cores.
+As a result, this mechanism still strictly limits the task group to quota
+average usage, albeit over a longer time window than a single period. This
+also limits the burst ability to no more than 1ms per cpu. This provides
+better more predictable user experience for highly threaded applications with
+small quota limits on high core count machines. It also eliminates the
+propensity to throttle these applications while simultanously using less than
+quota amounts of cpu. Another way to say this, is that by allowing the unused
+portion of a slice to remain valid across periods we have decreased the
+possibility of wastefully expiring quota on cpu-local silos that don't need a
+full slice's amount of cpu time.
+
+The interaction between cpu-bound and non-cpu-bound-interactive applications
+should also be considered, especially when single core usage hits 100%. If you
+gave each of these applications half of a cpu-core and they both got scheduled
+on the same CPU it is theoretically possible that the non-cpu bound application
+will use up to 1ms additional quota in some periods, thereby preventing the
+cpu-bound application from fully using its quota by that same amount. In these
+instances it will be up to the CFS algorithm (see sched-design-CFS.rst) to
+decide which application is chosen to run, as they will both be runnable and
+have remaining quota. This runtime discrepancy will be made up in the following
+periods when the interactive application idles.
+
Examples
--------
1. Limit a group to 1 CPU worth of runtime::
diff --git a/Documentation/security/IMA-templates.rst b/Documentation/security/IMA-templates.rst
index 3d1cca2..c5a8432 100644
--- a/Documentation/security/IMA-templates.rst
+++ b/Documentation/security/IMA-templates.rst
@@ -68,8 +68,10 @@
- 'd-ng': the digest of the event, calculated with an arbitrary hash
algorithm (field format: [<hash algo>:]digest, where the digest
prefix is shown only if the hash algorithm is not SHA1 or MD5);
+ - 'd-modsig': the digest of the event without the appended modsig;
- 'n-ng': the name of the event, without size limitations;
- 'sig': the file signature;
+ - 'modsig' the appended file signature;
- 'buf': the buffer data that was used to generate the hash without size limitations;
@@ -79,6 +81,7 @@
- "ima-ng" (default): its format is ``d-ng|n-ng``;
- "ima-sig": its format is ``d-ng|n-ng|sig``;
- "ima-buf": its format is ``d-ng|n-ng|buf``;
+ - "ima-modsig": its format is ``d-ng|n-ng|sig|d-modsig|modsig``;
Use
diff --git a/Documentation/security/tpm/index.rst b/Documentation/security/tpm/index.rst
index 3296533..fc40e9f 100644
--- a/Documentation/security/tpm/index.rst
+++ b/Documentation/security/tpm/index.rst
@@ -4,5 +4,7 @@
.. toctree::
+ tpm_event_log
tpm_vtpm_proxy
xen-tpmfront
+ tpm_ftpm_tee
diff --git a/Documentation/security/tpm/tpm_event_log.rst b/Documentation/security/tpm/tpm_event_log.rst
new file mode 100644
index 0000000..f00f7a1
--- /dev/null
+++ b/Documentation/security/tpm/tpm_event_log.rst
@@ -0,0 +1,55 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+=============
+TPM Event Log
+=============
+
+This document briefly describes what TPM log is and how it is handed
+over from the preboot firmware to the operating system.
+
+Introduction
+============
+
+The preboot firmware maintains an event log that gets new entries every
+time something gets hashed by it to any of the PCR registers. The events
+are segregated by their type and contain the value of the hashed PCR
+register. Typically, the preboot firmware will hash the components to
+who execution is to be handed over or actions relevant to the boot
+process.
+
+The main application for this is remote attestation and the reason why
+it is useful is nicely put in the very first section of [1]:
+
+"Attestation is used to provide information about the platform’s state
+to a challenger. However, PCR contents are difficult to interpret;
+therefore, attestation is typically more useful when the PCR contents
+are accompanied by a measurement log. While not trusted on their own,
+the measurement log contains a richer set of information than do the PCR
+contents. The PCR contents are used to provide the validation of the
+measurement log."
+
+UEFI event log
+==============
+
+UEFI provided event log has a few somewhat weird quirks.
+
+Before calling ExitBootServices() Linux EFI stub copies the event log to
+a custom configuration table defined by the stub itself. Unfortunately,
+the events generated by ExitBootServices() don't end up in the table.
+
+The firmware provides so called final events configuration table to sort
+out this issue. Events gets mirrored to this table after the first time
+EFI_TCG2_PROTOCOL.GetEventLog() gets called.
+
+This introduces another problem: nothing guarantees that it is not called
+before the Linux EFI stub gets to run. Thus, it needs to calculate and save the
+final events table size while the stub is still running to the custom
+configuration table so that the TPM driver can later on skip these events when
+concatenating two halves of the event log from the custom configuration table
+and the final events table.
+
+References
+==========
+
+- [1] https://trustedcomputinggroup.org/resource/pc-client-specific-platform-firmware-profile-specification/
+- [2] The final concatenation is done in drivers/char/tpm/eventlog/efi.c
diff --git a/Documentation/security/tpm/tpm_ftpm_tee.rst b/Documentation/security/tpm/tpm_ftpm_tee.rst
new file mode 100644
index 0000000..8c2bae1
--- /dev/null
+++ b/Documentation/security/tpm/tpm_ftpm_tee.rst
@@ -0,0 +1,27 @@
+=============================================
+Firmware TPM Driver
+=============================================
+
+This document describes the firmware Trusted Platform Module (fTPM)
+device driver.
+
+Introduction
+============
+
+This driver is a shim for firmware implemented in ARM's TrustZone
+environment. The driver allows programs to interact with the TPM in the same
+way they would interact with a hardware TPM.
+
+Design
+======
+
+The driver acts as a thin layer that passes commands to and from a TPM
+implemented in firmware. The driver itself doesn't contain much logic and is
+used more like a dumb pipe between firmware and kernel/userspace.
+
+The firmware itself is based on the following paper:
+https://www.microsoft.com/en-us/research/wp-content/uploads/2017/06/ftpm1.pdf
+
+When the driver is loaded it will expose ``/dev/tpmX`` character devices to
+userspace which will enable userspace to communicate with the firmware TPM
+through this device.
diff --git a/Documentation/sound/alsa-configuration.rst b/Documentation/sound/alsa-configuration.rst
index 4a3cecc8..02aacd6 100644
--- a/Documentation/sound/alsa-configuration.rst
+++ b/Documentation/sound/alsa-configuration.rst
@@ -1001,6 +1001,8 @@
2 = POSBUF: use position buffer,
3 = VIACOMBO: VIA-specific workaround for capture,
4 = COMBO: use LPIB for playback, auto for capture stream
+ 5 = SKL+: apply the delay calculation available on recent Intel chips
+ 6 = FIFO: correct the position with the fixed FIFO size, for recent AMD chips
probe_mask
Bitmask to probe codecs (default = -1, meaning all slots);
When the bit 8 (0x100) is set, the lower 8 bits are used
diff --git a/Documentation/sound/hd-audio/models.rst b/Documentation/sound/hd-audio/models.rst
index 7d7c191..11298f0 100644
--- a/Documentation/sound/hd-audio/models.rst
+++ b/Documentation/sound/hd-audio/models.rst
@@ -260,6 +260,9 @@
HP Spectre X360 fixups
alc-sense-combo
Headset button support for Chrome platform
+huawei-mbx-stereo
+ Enable initialization verbs for Huawei MBX stereo speakers;
+ might be risky, try this at your own risk
ALC66x/67x/892
==============
diff --git a/Documentation/sound/hd-audio/notes.rst b/Documentation/sound/hd-audio/notes.rst
index 9f73478..0f3109d 100644
--- a/Documentation/sound/hd-audio/notes.rst
+++ b/Documentation/sound/hd-audio/notes.rst
@@ -66,6 +66,11 @@
``position_fix=4`` is another combination available for all controllers,
and uses LPIB for the playback and the position-buffer for the capture
streams.
+``position_fix=5`` is specific to Intel platforms, so far, for Skylake
+and onward. It applies the delay calculation for the precise position
+reporting.
+``position_fix=6`` is to correct the position with the fixed FIFO
+size, mainly targeted for the recent AMD controllers.
0 is the default value for all other
controllers, the automatic check and fallback to LPIB as described in
the above. If you get a problem of repeated sounds, this option might
diff --git a/Documentation/sound/index.rst b/Documentation/sound/index.rst
index 47b89f0..4d7d42a 100644
--- a/Documentation/sound/index.rst
+++ b/Documentation/sound/index.rst
@@ -12,7 +12,7 @@
hd-audio/index
cards/index
-.. only:: subproject
+.. only:: subproject and html
Indices
=======
diff --git a/Documentation/sphinx/automarkup.py b/Documentation/sphinx/automarkup.py
index 77e89c1..5b6119f 100644
--- a/Documentation/sphinx/automarkup.py
+++ b/Documentation/sphinx/automarkup.py
@@ -25,8 +25,9 @@
# to the creation of incorrect and confusing cross references. So
# just don't even try with these names.
#
-Skipfuncs = [ 'open', 'close', 'read', 'write', 'fcntl', 'mmap'
- 'select', 'poll', 'fork', 'execve', 'clone', 'ioctl']
+Skipfuncs = [ 'open', 'close', 'read', 'write', 'fcntl', 'mmap',
+ 'select', 'poll', 'fork', 'execve', 'clone', 'ioctl',
+ 'socket' ]
#
# Find all occurrences of function() and try to replace them with
diff --git a/Documentation/spi/butterfly b/Documentation/spi/butterfly
deleted file mode 100644
index 9927af7a..0000000
--- a/Documentation/spi/butterfly
+++ /dev/null
@@ -1,68 +0,0 @@
-spi_butterfly - parport-to-butterfly adapter driver
-===================================================
-
-This is a hardware and software project that includes building and using
-a parallel port adapter cable, together with an "AVR Butterfly" to run
-firmware for user interfacing and/or sensors. A Butterfly is a $US20
-battery powered card with an AVR microcontroller and lots of goodies:
-sensors, LCD, flash, toggle stick, and more. You can use AVR-GCC to
-develop firmware for this, and flash it using this adapter cable.
-
-You can make this adapter from an old printer cable and solder things
-directly to the Butterfly. Or (if you have the parts and skills) you
-can come up with something fancier, providing ciruit protection to the
-Butterfly and the printer port, or with a better power supply than two
-signal pins from the printer port. Or for that matter, you can use
-similar cables to talk to many AVR boards, even a breadboard.
-
-This is more powerful than "ISP programming" cables since it lets kernel
-SPI protocol drivers interact with the AVR, and could even let the AVR
-issue interrupts to them. Later, your protocol driver should work
-easily with a "real SPI controller", instead of this bitbanger.
-
-
-The first cable connections will hook Linux up to one SPI bus, with the
-AVR and a DataFlash chip; and to the AVR reset line. This is all you
-need to reflash the firmware, and the pins are the standard Atmel "ISP"
-connector pins (used also on non-Butterfly AVR boards). On the parport
-side this is like "sp12" programming cables.
-
- Signal Butterfly Parport (DB-25)
- ------ --------- ---------------
- SCK = J403.PB1/SCK = pin 2/D0
- RESET = J403.nRST = pin 3/D1
- VCC = J403.VCC_EXT = pin 8/D6
- MOSI = J403.PB2/MOSI = pin 9/D7
- MISO = J403.PB3/MISO = pin 11/S7,nBUSY
- GND = J403.GND = pin 23/GND
-
-Then to let Linux master that bus to talk to the DataFlash chip, you must
-(a) flash new firmware that disables SPI (set PRR.2, and disable pullups
-by clearing PORTB.[0-3]); (b) configure the mtd_dataflash driver; and
-(c) cable in the chipselect.
-
- Signal Butterfly Parport (DB-25)
- ------ --------- ---------------
- VCC = J400.VCC_EXT = pin 7/D5
- SELECT = J400.PB0/nSS = pin 17/C3,nSELECT
- GND = J400.GND = pin 24/GND
-
-Or you could flash firmware making the AVR into an SPI slave (keeping the
-DataFlash in reset) and tweak the spi_butterfly driver to make it bind to
-the driver for your custom SPI-based protocol.
-
-The "USI" controller, using J405, can also be used for a second SPI bus.
-That would let you talk to the AVR using custom SPI-with-USI firmware,
-while letting either Linux or the AVR use the DataFlash. There are plenty
-of spare parport pins to wire this one up, such as:
-
- Signal Butterfly Parport (DB-25)
- ------ --------- ---------------
- SCK = J403.PE4/USCK = pin 5/D3
- MOSI = J403.PE5/DI = pin 6/D4
- MISO = J403.PE6/DO = pin 12/S5,nPAPEROUT
- GND = J403.GND = pin 22/GND
-
- IRQ = J402.PF4 = pin 10/S6,ACK
- GND = J402.GND(P2) = pin 25/GND
-
diff --git a/Documentation/spi/butterfly.rst b/Documentation/spi/butterfly.rst
new file mode 100644
index 0000000..e614a58
--- /dev/null
+++ b/Documentation/spi/butterfly.rst
@@ -0,0 +1,74 @@
+===================================================
+spi_butterfly - parport-to-butterfly adapter driver
+===================================================
+
+This is a hardware and software project that includes building and using
+a parallel port adapter cable, together with an "AVR Butterfly" to run
+firmware for user interfacing and/or sensors. A Butterfly is a $US20
+battery powered card with an AVR microcontroller and lots of goodies:
+sensors, LCD, flash, toggle stick, and more. You can use AVR-GCC to
+develop firmware for this, and flash it using this adapter cable.
+
+You can make this adapter from an old printer cable and solder things
+directly to the Butterfly. Or (if you have the parts and skills) you
+can come up with something fancier, providing ciruit protection to the
+Butterfly and the printer port, or with a better power supply than two
+signal pins from the printer port. Or for that matter, you can use
+similar cables to talk to many AVR boards, even a breadboard.
+
+This is more powerful than "ISP programming" cables since it lets kernel
+SPI protocol drivers interact with the AVR, and could even let the AVR
+issue interrupts to them. Later, your protocol driver should work
+easily with a "real SPI controller", instead of this bitbanger.
+
+
+The first cable connections will hook Linux up to one SPI bus, with the
+AVR and a DataFlash chip; and to the AVR reset line. This is all you
+need to reflash the firmware, and the pins are the standard Atmel "ISP"
+connector pins (used also on non-Butterfly AVR boards). On the parport
+side this is like "sp12" programming cables.
+
+ ====== ============= ===================
+ Signal Butterfly Parport (DB-25)
+ ====== ============= ===================
+ SCK J403.PB1/SCK pin 2/D0
+ RESET J403.nRST pin 3/D1
+ VCC J403.VCC_EXT pin 8/D6
+ MOSI J403.PB2/MOSI pin 9/D7
+ MISO J403.PB3/MISO pin 11/S7,nBUSY
+ GND J403.GND pin 23/GND
+ ====== ============= ===================
+
+Then to let Linux master that bus to talk to the DataFlash chip, you must
+(a) flash new firmware that disables SPI (set PRR.2, and disable pullups
+by clearing PORTB.[0-3]); (b) configure the mtd_dataflash driver; and
+(c) cable in the chipselect.
+
+ ====== ============ ===================
+ Signal Butterfly Parport (DB-25)
+ ====== ============ ===================
+ VCC J400.VCC_EXT pin 7/D5
+ SELECT J400.PB0/nSS pin 17/C3,nSELECT
+ GND J400.GND pin 24/GND
+ ====== ============ ===================
+
+Or you could flash firmware making the AVR into an SPI slave (keeping the
+DataFlash in reset) and tweak the spi_butterfly driver to make it bind to
+the driver for your custom SPI-based protocol.
+
+The "USI" controller, using J405, can also be used for a second SPI bus.
+That would let you talk to the AVR using custom SPI-with-USI firmware,
+while letting either Linux or the AVR use the DataFlash. There are plenty
+of spare parport pins to wire this one up, such as:
+
+ ====== ============= ===================
+ Signal Butterfly Parport (DB-25)
+ ====== ============= ===================
+ SCK J403.PE4/USCK pin 5/D3
+ MOSI J403.PE5/DI pin 6/D4
+ MISO J403.PE6/DO pin 12/S5,nPAPEROUT
+ GND J403.GND pin 22/GND
+
+ IRQ J402.PF4 pin 10/S6,ACK
+ GND J402.GND(P2) pin 25/GND
+ ====== ============= ===================
diff --git a/Documentation/spi/index.rst b/Documentation/spi/index.rst
new file mode 100644
index 0000000..06c34ea
--- /dev/null
+++ b/Documentation/spi/index.rst
@@ -0,0 +1,22 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+=================================
+Serial Peripheral Interface (SPI)
+=================================
+
+.. toctree::
+ :maxdepth: 1
+
+ spi-summary
+ spidev
+ butterfly
+ pxa2xx
+ spi-lm70llp
+ spi-sc18is602
+
+.. only:: subproject and html
+
+ Indices
+ =======
+
+ * :ref:`genindex`
diff --git a/Documentation/spi/pxa2xx b/Documentation/spi/pxa2xx
deleted file mode 100644
index 551325b..0000000
--- a/Documentation/spi/pxa2xx
+++ /dev/null
@@ -1,235 +0,0 @@
-PXA2xx SPI on SSP driver HOWTO
-===================================================
-This a mini howto on the pxa2xx_spi driver. The driver turns a PXA2xx
-synchronous serial port into a SPI master controller
-(see Documentation/spi/spi-summary). The driver has the following features
-
-- Support for any PXA2xx SSP
-- SSP PIO and SSP DMA data transfers.
-- External and Internal (SSPFRM) chip selects.
-- Per slave device (chip) configuration.
-- Full suspend, freeze, resume support.
-
-The driver is built around a "spi_message" fifo serviced by workqueue and a
-tasklet. The workqueue, "pump_messages", drives message fifo and the tasklet
-(pump_transfer) is responsible for queuing SPI transactions and setting up and
-launching the dma/interrupt driven transfers.
-
-Declaring PXA2xx Master Controllers
------------------------------------
-Typically a SPI master is defined in the arch/.../mach-*/board-*.c as a
-"platform device". The master configuration is passed to the driver via a table
-found in include/linux/spi/pxa2xx_spi.h:
-
-struct pxa2xx_spi_controller {
- u16 num_chipselect;
- u8 enable_dma;
-};
-
-The "pxa2xx_spi_controller.num_chipselect" field is used to determine the number of
-slave device (chips) attached to this SPI master.
-
-The "pxa2xx_spi_controller.enable_dma" field informs the driver that SSP DMA should
-be used. This caused the driver to acquire two DMA channels: rx_channel and
-tx_channel. The rx_channel has a higher DMA service priority the tx_channel.
-See the "PXA2xx Developer Manual" section "DMA Controller".
-
-NSSP MASTER SAMPLE
-------------------
-Below is a sample configuration using the PXA255 NSSP.
-
-static struct resource pxa_spi_nssp_resources[] = {
- [0] = {
- .start = __PREG(SSCR0_P(2)), /* Start address of NSSP */
- .end = __PREG(SSCR0_P(2)) + 0x2c, /* Range of registers */
- .flags = IORESOURCE_MEM,
- },
- [1] = {
- .start = IRQ_NSSP, /* NSSP IRQ */
- .end = IRQ_NSSP,
- .flags = IORESOURCE_IRQ,
- },
-};
-
-static struct pxa2xx_spi_controller pxa_nssp_master_info = {
- .num_chipselect = 1, /* Matches the number of chips attached to NSSP */
- .enable_dma = 1, /* Enables NSSP DMA */
-};
-
-static struct platform_device pxa_spi_nssp = {
- .name = "pxa2xx-spi", /* MUST BE THIS VALUE, so device match driver */
- .id = 2, /* Bus number, MUST MATCH SSP number 1..n */
- .resource = pxa_spi_nssp_resources,
- .num_resources = ARRAY_SIZE(pxa_spi_nssp_resources),
- .dev = {
- .platform_data = &pxa_nssp_master_info, /* Passed to driver */
- },
-};
-
-static struct platform_device *devices[] __initdata = {
- &pxa_spi_nssp,
-};
-
-static void __init board_init(void)
-{
- (void)platform_add_device(devices, ARRAY_SIZE(devices));
-}
-
-Declaring Slave Devices
------------------------
-Typically each SPI slave (chip) is defined in the arch/.../mach-*/board-*.c
-using the "spi_board_info" structure found in "linux/spi/spi.h". See
-"Documentation/spi/spi-summary" for additional information.
-
-Each slave device attached to the PXA must provide slave specific configuration
-information via the structure "pxa2xx_spi_chip" found in
-"include/linux/spi/pxa2xx_spi.h". The pxa2xx_spi master controller driver
-will uses the configuration whenever the driver communicates with the slave
-device. All fields are optional.
-
-struct pxa2xx_spi_chip {
- u8 tx_threshold;
- u8 rx_threshold;
- u8 dma_burst_size;
- u32 timeout;
- u8 enable_loopback;
- void (*cs_control)(u32 command);
-};
-
-The "pxa2xx_spi_chip.tx_threshold" and "pxa2xx_spi_chip.rx_threshold" fields are
-used to configure the SSP hardware fifo. These fields are critical to the
-performance of pxa2xx_spi driver and misconfiguration will result in rx
-fifo overruns (especially in PIO mode transfers). Good default values are
-
- .tx_threshold = 8,
- .rx_threshold = 8,
-
-The range is 1 to 16 where zero indicates "use default".
-
-The "pxa2xx_spi_chip.dma_burst_size" field is used to configure PXA2xx DMA
-engine and is related the "spi_device.bits_per_word" field. Read and understand
-the PXA2xx "Developer Manual" sections on the DMA controller and SSP Controllers
-to determine the correct value. An SSP configured for byte-wide transfers would
-use a value of 8. The driver will determine a reasonable default if
-dma_burst_size == 0.
-
-The "pxa2xx_spi_chip.timeout" fields is used to efficiently handle
-trailing bytes in the SSP receiver fifo. The correct value for this field is
-dependent on the SPI bus speed ("spi_board_info.max_speed_hz") and the specific
-slave device. Please note that the PXA2xx SSP 1 does not support trailing byte
-timeouts and must busy-wait any trailing bytes.
-
-The "pxa2xx_spi_chip.enable_loopback" field is used to place the SSP porting
-into internal loopback mode. In this mode the SSP controller internally
-connects the SSPTX pin to the SSPRX pin. This is useful for initial setup
-testing.
-
-The "pxa2xx_spi_chip.cs_control" field is used to point to a board specific
-function for asserting/deasserting a slave device chip select. If the field is
-NULL, the pxa2xx_spi master controller driver assumes that the SSP port is
-configured to use SSPFRM instead.
-
-NOTE: the SPI driver cannot control the chip select if SSPFRM is used, so the
-chipselect is dropped after each spi_transfer. Most devices need chip select
-asserted around the complete message. Use SSPFRM as a GPIO (through cs_control)
-to accommodate these chips.
-
-
-NSSP SLAVE SAMPLE
------------------
-The pxa2xx_spi_chip structure is passed to the pxa2xx_spi driver in the
-"spi_board_info.controller_data" field. Below is a sample configuration using
-the PXA255 NSSP.
-
-/* Chip Select control for the CS8415A SPI slave device */
-static void cs8415a_cs_control(u32 command)
-{
- if (command & PXA2XX_CS_ASSERT)
- GPCR(2) = GPIO_bit(2);
- else
- GPSR(2) = GPIO_bit(2);
-}
-
-/* Chip Select control for the CS8405A SPI slave device */
-static void cs8405a_cs_control(u32 command)
-{
- if (command & PXA2XX_CS_ASSERT)
- GPCR(3) = GPIO_bit(3);
- else
- GPSR(3) = GPIO_bit(3);
-}
-
-static struct pxa2xx_spi_chip cs8415a_chip_info = {
- .tx_threshold = 8, /* SSP hardward FIFO threshold */
- .rx_threshold = 8, /* SSP hardward FIFO threshold */
- .dma_burst_size = 8, /* Byte wide transfers used so 8 byte bursts */
- .timeout = 235, /* See Intel documentation */
- .cs_control = cs8415a_cs_control, /* Use external chip select */
-};
-
-static struct pxa2xx_spi_chip cs8405a_chip_info = {
- .tx_threshold = 8, /* SSP hardward FIFO threshold */
- .rx_threshold = 8, /* SSP hardward FIFO threshold */
- .dma_burst_size = 8, /* Byte wide transfers used so 8 byte bursts */
- .timeout = 235, /* See Intel documentation */
- .cs_control = cs8405a_cs_control, /* Use external chip select */
-};
-
-static struct spi_board_info streetracer_spi_board_info[] __initdata = {
- {
- .modalias = "cs8415a", /* Name of spi_driver for this device */
- .max_speed_hz = 3686400, /* Run SSP as fast a possbile */
- .bus_num = 2, /* Framework bus number */
- .chip_select = 0, /* Framework chip select */
- .platform_data = NULL; /* No spi_driver specific config */
- .controller_data = &cs8415a_chip_info, /* Master chip config */
- .irq = STREETRACER_APCI_IRQ, /* Slave device interrupt */
- },
- {
- .modalias = "cs8405a", /* Name of spi_driver for this device */
- .max_speed_hz = 3686400, /* Run SSP as fast a possbile */
- .bus_num = 2, /* Framework bus number */
- .chip_select = 1, /* Framework chip select */
- .controller_data = &cs8405a_chip_info, /* Master chip config */
- .irq = STREETRACER_APCI_IRQ, /* Slave device interrupt */
- },
-};
-
-static void __init streetracer_init(void)
-{
- spi_register_board_info(streetracer_spi_board_info,
- ARRAY_SIZE(streetracer_spi_board_info));
-}
-
-
-DMA and PIO I/O Support
------------------------
-The pxa2xx_spi driver supports both DMA and interrupt driven PIO message
-transfers. The driver defaults to PIO mode and DMA transfers must be enabled
-by setting the "enable_dma" flag in the "pxa2xx_spi_controller" structure. The DMA
-mode supports both coherent and stream based DMA mappings.
-
-The following logic is used to determine the type of I/O to be used on
-a per "spi_transfer" basis:
-
-if !enable_dma then
- always use PIO transfers
-
-if spi_message.len > 8191 then
- print "rate limited" warning
- use PIO transfers
-
-if spi_message.is_dma_mapped and rx_dma_buf != 0 and tx_dma_buf != 0 then
- use coherent DMA mode
-
-if rx_buf and tx_buf are aligned on 8 byte boundary then
- use streaming DMA mode
-
-otherwise
- use PIO transfer
-
-THANKS TO
----------
-
-David Brownell and others for mentoring the development of this driver.
-
diff --git a/Documentation/spi/pxa2xx.rst b/Documentation/spi/pxa2xx.rst
new file mode 100644
index 0000000..882d3cc
--- /dev/null
+++ b/Documentation/spi/pxa2xx.rst
@@ -0,0 +1,240 @@
+==============================
+PXA2xx SPI on SSP driver HOWTO
+==============================
+
+This a mini howto on the pxa2xx_spi driver. The driver turns a PXA2xx
+synchronous serial port into a SPI master controller
+(see Documentation/spi/spi-summary.rst). The driver has the following features
+
+- Support for any PXA2xx SSP
+- SSP PIO and SSP DMA data transfers.
+- External and Internal (SSPFRM) chip selects.
+- Per slave device (chip) configuration.
+- Full suspend, freeze, resume support.
+
+The driver is built around a "spi_message" fifo serviced by workqueue and a
+tasklet. The workqueue, "pump_messages", drives message fifo and the tasklet
+(pump_transfer) is responsible for queuing SPI transactions and setting up and
+launching the dma/interrupt driven transfers.
+
+Declaring PXA2xx Master Controllers
+-----------------------------------
+Typically a SPI master is defined in the arch/.../mach-*/board-*.c as a
+"platform device". The master configuration is passed to the driver via a table
+found in include/linux/spi/pxa2xx_spi.h::
+
+ struct pxa2xx_spi_controller {
+ u16 num_chipselect;
+ u8 enable_dma;
+ };
+
+The "pxa2xx_spi_controller.num_chipselect" field is used to determine the number of
+slave device (chips) attached to this SPI master.
+
+The "pxa2xx_spi_controller.enable_dma" field informs the driver that SSP DMA should
+be used. This caused the driver to acquire two DMA channels: rx_channel and
+tx_channel. The rx_channel has a higher DMA service priority the tx_channel.
+See the "PXA2xx Developer Manual" section "DMA Controller".
+
+NSSP MASTER SAMPLE
+------------------
+Below is a sample configuration using the PXA255 NSSP::
+
+ static struct resource pxa_spi_nssp_resources[] = {
+ [0] = {
+ .start = __PREG(SSCR0_P(2)), /* Start address of NSSP */
+ .end = __PREG(SSCR0_P(2)) + 0x2c, /* Range of registers */
+ .flags = IORESOURCE_MEM,
+ },
+ [1] = {
+ .start = IRQ_NSSP, /* NSSP IRQ */
+ .end = IRQ_NSSP,
+ .flags = IORESOURCE_IRQ,
+ },
+ };
+
+ static struct pxa2xx_spi_controller pxa_nssp_master_info = {
+ .num_chipselect = 1, /* Matches the number of chips attached to NSSP */
+ .enable_dma = 1, /* Enables NSSP DMA */
+ };
+
+ static struct platform_device pxa_spi_nssp = {
+ .name = "pxa2xx-spi", /* MUST BE THIS VALUE, so device match driver */
+ .id = 2, /* Bus number, MUST MATCH SSP number 1..n */
+ .resource = pxa_spi_nssp_resources,
+ .num_resources = ARRAY_SIZE(pxa_spi_nssp_resources),
+ .dev = {
+ .platform_data = &pxa_nssp_master_info, /* Passed to driver */
+ },
+ };
+
+ static struct platform_device *devices[] __initdata = {
+ &pxa_spi_nssp,
+ };
+
+ static void __init board_init(void)
+ {
+ (void)platform_add_device(devices, ARRAY_SIZE(devices));
+ }
+
+Declaring Slave Devices
+-----------------------
+Typically each SPI slave (chip) is defined in the arch/.../mach-*/board-*.c
+using the "spi_board_info" structure found in "linux/spi/spi.h". See
+"Documentation/spi/spi-summary.rst" for additional information.
+
+Each slave device attached to the PXA must provide slave specific configuration
+information via the structure "pxa2xx_spi_chip" found in
+"include/linux/spi/pxa2xx_spi.h". The pxa2xx_spi master controller driver
+will uses the configuration whenever the driver communicates with the slave
+device. All fields are optional.
+
+::
+
+ struct pxa2xx_spi_chip {
+ u8 tx_threshold;
+ u8 rx_threshold;
+ u8 dma_burst_size;
+ u32 timeout;
+ u8 enable_loopback;
+ void (*cs_control)(u32 command);
+ };
+
+The "pxa2xx_spi_chip.tx_threshold" and "pxa2xx_spi_chip.rx_threshold" fields are
+used to configure the SSP hardware fifo. These fields are critical to the
+performance of pxa2xx_spi driver and misconfiguration will result in rx
+fifo overruns (especially in PIO mode transfers). Good default values are::
+
+ .tx_threshold = 8,
+ .rx_threshold = 8,
+
+The range is 1 to 16 where zero indicates "use default".
+
+The "pxa2xx_spi_chip.dma_burst_size" field is used to configure PXA2xx DMA
+engine and is related the "spi_device.bits_per_word" field. Read and understand
+the PXA2xx "Developer Manual" sections on the DMA controller and SSP Controllers
+to determine the correct value. An SSP configured for byte-wide transfers would
+use a value of 8. The driver will determine a reasonable default if
+dma_burst_size == 0.
+
+The "pxa2xx_spi_chip.timeout" fields is used to efficiently handle
+trailing bytes in the SSP receiver fifo. The correct value for this field is
+dependent on the SPI bus speed ("spi_board_info.max_speed_hz") and the specific
+slave device. Please note that the PXA2xx SSP 1 does not support trailing byte
+timeouts and must busy-wait any trailing bytes.
+
+The "pxa2xx_spi_chip.enable_loopback" field is used to place the SSP porting
+into internal loopback mode. In this mode the SSP controller internally
+connects the SSPTX pin to the SSPRX pin. This is useful for initial setup
+testing.
+
+The "pxa2xx_spi_chip.cs_control" field is used to point to a board specific
+function for asserting/deasserting a slave device chip select. If the field is
+NULL, the pxa2xx_spi master controller driver assumes that the SSP port is
+configured to use SSPFRM instead.
+
+NOTE: the SPI driver cannot control the chip select if SSPFRM is used, so the
+chipselect is dropped after each spi_transfer. Most devices need chip select
+asserted around the complete message. Use SSPFRM as a GPIO (through cs_control)
+to accommodate these chips.
+
+
+NSSP SLAVE SAMPLE
+-----------------
+The pxa2xx_spi_chip structure is passed to the pxa2xx_spi driver in the
+"spi_board_info.controller_data" field. Below is a sample configuration using
+the PXA255 NSSP.
+
+::
+
+ /* Chip Select control for the CS8415A SPI slave device */
+ static void cs8415a_cs_control(u32 command)
+ {
+ if (command & PXA2XX_CS_ASSERT)
+ GPCR(2) = GPIO_bit(2);
+ else
+ GPSR(2) = GPIO_bit(2);
+ }
+
+ /* Chip Select control for the CS8405A SPI slave device */
+ static void cs8405a_cs_control(u32 command)
+ {
+ if (command & PXA2XX_CS_ASSERT)
+ GPCR(3) = GPIO_bit(3);
+ else
+ GPSR(3) = GPIO_bit(3);
+ }
+
+ static struct pxa2xx_spi_chip cs8415a_chip_info = {
+ .tx_threshold = 8, /* SSP hardward FIFO threshold */
+ .rx_threshold = 8, /* SSP hardward FIFO threshold */
+ .dma_burst_size = 8, /* Byte wide transfers used so 8 byte bursts */
+ .timeout = 235, /* See Intel documentation */
+ .cs_control = cs8415a_cs_control, /* Use external chip select */
+ };
+
+ static struct pxa2xx_spi_chip cs8405a_chip_info = {
+ .tx_threshold = 8, /* SSP hardward FIFO threshold */
+ .rx_threshold = 8, /* SSP hardward FIFO threshold */
+ .dma_burst_size = 8, /* Byte wide transfers used so 8 byte bursts */
+ .timeout = 235, /* See Intel documentation */
+ .cs_control = cs8405a_cs_control, /* Use external chip select */
+ };
+
+ static struct spi_board_info streetracer_spi_board_info[] __initdata = {
+ {
+ .modalias = "cs8415a", /* Name of spi_driver for this device */
+ .max_speed_hz = 3686400, /* Run SSP as fast a possbile */
+ .bus_num = 2, /* Framework bus number */
+ .chip_select = 0, /* Framework chip select */
+ .platform_data = NULL; /* No spi_driver specific config */
+ .controller_data = &cs8415a_chip_info, /* Master chip config */
+ .irq = STREETRACER_APCI_IRQ, /* Slave device interrupt */
+ },
+ {
+ .modalias = "cs8405a", /* Name of spi_driver for this device */
+ .max_speed_hz = 3686400, /* Run SSP as fast a possbile */
+ .bus_num = 2, /* Framework bus number */
+ .chip_select = 1, /* Framework chip select */
+ .controller_data = &cs8405a_chip_info, /* Master chip config */
+ .irq = STREETRACER_APCI_IRQ, /* Slave device interrupt */
+ },
+ };
+
+ static void __init streetracer_init(void)
+ {
+ spi_register_board_info(streetracer_spi_board_info,
+ ARRAY_SIZE(streetracer_spi_board_info));
+ }
+
+
+DMA and PIO I/O Support
+-----------------------
+The pxa2xx_spi driver supports both DMA and interrupt driven PIO message
+transfers. The driver defaults to PIO mode and DMA transfers must be enabled
+by setting the "enable_dma" flag in the "pxa2xx_spi_controller" structure. The DMA
+mode supports both coherent and stream based DMA mappings.
+
+The following logic is used to determine the type of I/O to be used on
+a per "spi_transfer" basis::
+
+ if !enable_dma then
+ always use PIO transfers
+
+ if spi_message.len > 8191 then
+ print "rate limited" warning
+ use PIO transfers
+
+ if spi_message.is_dma_mapped and rx_dma_buf != 0 and tx_dma_buf != 0 then
+ use coherent DMA mode
+
+ if rx_buf and tx_buf are aligned on 8 byte boundary then
+ use streaming DMA mode
+
+ otherwise
+ use PIO transfer
+
+THANKS TO
+---------
+
+David Brownell and others for mentoring the development of this driver.
diff --git a/Documentation/spi/spi-lm70llp b/Documentation/spi/spi-lm70llp
deleted file mode 100644
index 463f6d0..0000000
--- a/Documentation/spi/spi-lm70llp
+++ /dev/null
@@ -1,79 +0,0 @@
-spi_lm70llp : LM70-LLP parport-to-SPI adapter
-==============================================
-
-Supported board/chip:
- * National Semiconductor LM70 LLP evaluation board
- Datasheet: http://www.national.com/pf/LM/LM70.html
-
-Author:
- Kaiwan N Billimoria <kaiwan@designergraphix.com>
-
-Description
------------
-This driver provides glue code connecting a National Semiconductor LM70 LLP
-temperature sensor evaluation board to the kernel's SPI core subsystem.
-
-This is a SPI master controller driver. It can be used in conjunction with
-(layered under) the LM70 logical driver (a "SPI protocol driver").
-In effect, this driver turns the parallel port interface on the eval board
-into a SPI bus with a single device, which will be driven by the generic
-LM70 driver (drivers/hwmon/lm70.c).
-
-
-Hardware Interfacing
---------------------
-The schematic for this particular board (the LM70EVAL-LLP) is
-available (on page 4) here:
-
- http://www.national.com/appinfo/tempsensors/files/LM70LLPEVALmanual.pdf
-
-The hardware interfacing on the LM70 LLP eval board is as follows:
-
- Parallel LM70 LLP
- Port Direction JP2 Header
- ----------- --------- ----------------
- D0 2 - -
- D1 3 --> V+ 5
- D2 4 --> V+ 5
- D3 5 --> V+ 5
- D4 6 --> V+ 5
- D5 7 --> nCS 8
- D6 8 --> SCLK 3
- D7 9 --> SI/O 5
- GND 25 - GND 7
- Select 13 <-- SI/O 1
- ----------- --------- ----------------
-
-Note that since the LM70 uses a "3-wire" variant of SPI, the SI/SO pin
-is connected to both pin D7 (as Master Out) and Select (as Master In)
-using an arrangement that lets either the parport or the LM70 pull the
-pin low. This can't be shared with true SPI devices, but other 3-wire
-devices might share the same SI/SO pin.
-
-The bitbanger routine in this driver (lm70_txrx) is called back from
-the bound "hwmon/lm70" protocol driver through its sysfs hook, using a
-spi_write_then_read() call. It performs Mode 0 (SPI/Microwire) bitbanging.
-The lm70 driver then inteprets the resulting digital temperature value
-and exports it through sysfs.
-
-A "gotcha": National Semiconductor's LM70 LLP eval board circuit schematic
-shows that the SI/O line from the LM70 chip is connected to the base of a
-transistor Q1 (and also a pullup, and a zener diode to D7); while the
-collector is tied to VCC.
-
-Interpreting this circuit, when the LM70 SI/O line is High (or tristate
-and not grounded by the host via D7), the transistor conducts and switches
-the collector to zero, which is reflected on pin 13 of the DB25 parport
-connector. When SI/O is Low (driven by the LM70 or the host) on the other
-hand, the transistor is cut off and the voltage tied to it's collector is
-reflected on pin 13 as a High level.
-
-So: the getmiso inline routine in this driver takes this fact into account,
-inverting the value read at pin 13.
-
-
-Thanks to
----------
-o David Brownell for mentoring the SPI-side driver development.
-o Dr.Craig Hollabaugh for the (early) "manual" bitbanging driver version.
-o Nadir Billimoria for help interpreting the circuit schematic.
diff --git a/Documentation/spi/spi-lm70llp.rst b/Documentation/spi/spi-lm70llp.rst
new file mode 100644
index 0000000..07631ae
--- /dev/null
+++ b/Documentation/spi/spi-lm70llp.rst
@@ -0,0 +1,84 @@
+==============================================
+spi_lm70llp : LM70-LLP parport-to-SPI adapter
+==============================================
+
+Supported board/chip:
+
+ * National Semiconductor LM70 LLP evaluation board
+
+ Datasheet: http://www.national.com/pf/LM/LM70.html
+
+Author:
+ Kaiwan N Billimoria <kaiwan@designergraphix.com>
+
+Description
+-----------
+This driver provides glue code connecting a National Semiconductor LM70 LLP
+temperature sensor evaluation board to the kernel's SPI core subsystem.
+
+This is a SPI master controller driver. It can be used in conjunction with
+(layered under) the LM70 logical driver (a "SPI protocol driver").
+In effect, this driver turns the parallel port interface on the eval board
+into a SPI bus with a single device, which will be driven by the generic
+LM70 driver (drivers/hwmon/lm70.c).
+
+
+Hardware Interfacing
+--------------------
+The schematic for this particular board (the LM70EVAL-LLP) is
+available (on page 4) here:
+
+ http://www.national.com/appinfo/tempsensors/files/LM70LLPEVALmanual.pdf
+
+The hardware interfacing on the LM70 LLP eval board is as follows:
+
+ ======== == ========= ==========
+ Parallel LM70 LLP
+ Port . Direction JP2 Header
+ ======== == ========= ==========
+ D0 2 - -
+ D1 3 --> V+ 5
+ D2 4 --> V+ 5
+ D3 5 --> V+ 5
+ D4 6 --> V+ 5
+ D5 7 --> nCS 8
+ D6 8 --> SCLK 3
+ D7 9 --> SI/O 5
+ GND 25 - GND 7
+ Select 13 <-- SI/O 1
+ ======== == ========= ==========
+
+Note that since the LM70 uses a "3-wire" variant of SPI, the SI/SO pin
+is connected to both pin D7 (as Master Out) and Select (as Master In)
+using an arrangement that lets either the parport or the LM70 pull the
+pin low. This can't be shared with true SPI devices, but other 3-wire
+devices might share the same SI/SO pin.
+
+The bitbanger routine in this driver (lm70_txrx) is called back from
+the bound "hwmon/lm70" protocol driver through its sysfs hook, using a
+spi_write_then_read() call. It performs Mode 0 (SPI/Microwire) bitbanging.
+The lm70 driver then inteprets the resulting digital temperature value
+and exports it through sysfs.
+
+A "gotcha": National Semiconductor's LM70 LLP eval board circuit schematic
+shows that the SI/O line from the LM70 chip is connected to the base of a
+transistor Q1 (and also a pullup, and a zener diode to D7); while the
+collector is tied to VCC.
+
+Interpreting this circuit, when the LM70 SI/O line is High (or tristate
+and not grounded by the host via D7), the transistor conducts and switches
+the collector to zero, which is reflected on pin 13 of the DB25 parport
+connector. When SI/O is Low (driven by the LM70 or the host) on the other
+hand, the transistor is cut off and the voltage tied to it's collector is
+reflected on pin 13 as a High level.
+
+So: the getmiso inline routine in this driver takes this fact into account,
+inverting the value read at pin 13.
+
+
+Thanks to
+---------
+
+- David Brownell for mentoring the SPI-side driver development.
+- Dr.Craig Hollabaugh for the (early) "manual" bitbanging driver version.
+- Nadir Billimoria for help interpreting the circuit schematic.
diff --git a/Documentation/spi/spi-sc18is602 b/Documentation/spi/spi-sc18is602
deleted file mode 100644
index a457028..0000000
--- a/Documentation/spi/spi-sc18is602
+++ /dev/null
@@ -1,36 +0,0 @@
-Kernel driver spi-sc18is602
-===========================
-
-Supported chips:
- * NXP SI18IS602/602B/603
- Datasheet: http://www.nxp.com/documents/data_sheet/SC18IS602_602B_603.pdf
-
-Author:
- Guenter Roeck <linux@roeck-us.net>
-
-
-Description
------------
-
-This driver provides connects a NXP SC18IS602/603 I2C-bus to SPI bridge to the
-kernel's SPI core subsystem.
-
-The driver does not probe for supported chips, since the SI18IS602/603 does not
-support Chip ID registers. You will have to instantiate the devices explicitly.
-Please see Documentation/i2c/instantiating-devices for details.
-
-
-Usage Notes
------------
-
-This driver requires the I2C adapter driver to support raw I2C messages. I2C
-adapter drivers which can only handle the SMBus protocol are not supported.
-
-The maximum SPI message size supported by SC18IS602/603 is 200 bytes. Attempts
-to initiate longer transfers will fail with -EINVAL. EEPROM read operations and
-similar large accesses have to be split into multiple chunks of no more than
-200 bytes per SPI message (128 bytes of data per message is recommended). This
-means that programs such as "cp" or "od", which automatically use large block
-sizes to access a device, can not be used directly to read data from EEPROM.
-Programs such as dd, where the block size can be specified, should be used
-instead.
diff --git a/Documentation/spi/spi-sc18is602.rst b/Documentation/spi/spi-sc18is602.rst
new file mode 100644
index 0000000..2a31dc7
--- /dev/null
+++ b/Documentation/spi/spi-sc18is602.rst
@@ -0,0 +1,39 @@
+===========================
+Kernel driver spi-sc18is602
+===========================
+
+Supported chips:
+
+ * NXP SI18IS602/602B/603
+
+ Datasheet: http://www.nxp.com/documents/data_sheet/SC18IS602_602B_603.pdf
+
+Author:
+ Guenter Roeck <linux@roeck-us.net>
+
+
+Description
+-----------
+
+This driver provides connects a NXP SC18IS602/603 I2C-bus to SPI bridge to the
+kernel's SPI core subsystem.
+
+The driver does not probe for supported chips, since the SI18IS602/603 does not
+support Chip ID registers. You will have to instantiate the devices explicitly.
+Please see Documentation/i2c/instantiating-devices.rst for details.
+
+
+Usage Notes
+-----------
+
+This driver requires the I2C adapter driver to support raw I2C messages. I2C
+adapter drivers which can only handle the SMBus protocol are not supported.
+
+The maximum SPI message size supported by SC18IS602/603 is 200 bytes. Attempts
+to initiate longer transfers will fail with -EINVAL. EEPROM read operations and
+similar large accesses have to be split into multiple chunks of no more than
+200 bytes per SPI message (128 bytes of data per message is recommended). This
+means that programs such as "cp" or "od", which automatically use large block
+sizes to access a device, can not be used directly to read data from EEPROM.
+Programs such as dd, where the block size can be specified, should be used
+instead.
diff --git a/Documentation/spi/spi-summary b/Documentation/spi/spi-summary
deleted file mode 100644
index 1a63194..0000000
--- a/Documentation/spi/spi-summary
+++ /dev/null
@@ -1,631 +0,0 @@
-Overview of Linux kernel SPI support
-====================================
-
-02-Feb-2012
-
-What is SPI?
-------------
-The "Serial Peripheral Interface" (SPI) is a synchronous four wire serial
-link used to connect microcontrollers to sensors, memory, and peripherals.
-It's a simple "de facto" standard, not complicated enough to acquire a
-standardization body. SPI uses a master/slave configuration.
-
-The three signal wires hold a clock (SCK, often on the order of 10 MHz),
-and parallel data lines with "Master Out, Slave In" (MOSI) or "Master In,
-Slave Out" (MISO) signals. (Other names are also used.) There are four
-clocking modes through which data is exchanged; mode-0 and mode-3 are most
-commonly used. Each clock cycle shifts data out and data in; the clock
-doesn't cycle except when there is a data bit to shift. Not all data bits
-are used though; not every protocol uses those full duplex capabilities.
-
-SPI masters use a fourth "chip select" line to activate a given SPI slave
-device, so those three signal wires may be connected to several chips
-in parallel. All SPI slaves support chipselects; they are usually active
-low signals, labeled nCSx for slave 'x' (e.g. nCS0). Some devices have
-other signals, often including an interrupt to the master.
-
-Unlike serial busses like USB or SMBus, even low level protocols for
-SPI slave functions are usually not interoperable between vendors
-(except for commodities like SPI memory chips).
-
- - SPI may be used for request/response style device protocols, as with
- touchscreen sensors and memory chips.
-
- - It may also be used to stream data in either direction (half duplex),
- or both of them at the same time (full duplex).
-
- - Some devices may use eight bit words. Others may use different word
- lengths, such as streams of 12-bit or 20-bit digital samples.
-
- - Words are usually sent with their most significant bit (MSB) first,
- but sometimes the least significant bit (LSB) goes first instead.
-
- - Sometimes SPI is used to daisy-chain devices, like shift registers.
-
-In the same way, SPI slaves will only rarely support any kind of automatic
-discovery/enumeration protocol. The tree of slave devices accessible from
-a given SPI master will normally be set up manually, with configuration
-tables.
-
-SPI is only one of the names used by such four-wire protocols, and
-most controllers have no problem handling "MicroWire" (think of it as
-half-duplex SPI, for request/response protocols), SSP ("Synchronous
-Serial Protocol"), PSP ("Programmable Serial Protocol"), and other
-related protocols.
-
-Some chips eliminate a signal line by combining MOSI and MISO, and
-limiting themselves to half-duplex at the hardware level. In fact
-some SPI chips have this signal mode as a strapping option. These
-can be accessed using the same programming interface as SPI, but of
-course they won't handle full duplex transfers. You may find such
-chips described as using "three wire" signaling: SCK, data, nCSx.
-(That data line is sometimes called MOMI or SISO.)
-
-Microcontrollers often support both master and slave sides of the SPI
-protocol. This document (and Linux) supports both the master and slave
-sides of SPI interactions.
-
-
-Who uses it? On what kinds of systems?
----------------------------------------
-Linux developers using SPI are probably writing device drivers for embedded
-systems boards. SPI is used to control external chips, and it is also a
-protocol supported by every MMC or SD memory card. (The older "DataFlash"
-cards, predating MMC cards but using the same connectors and card shape,
-support only SPI.) Some PC hardware uses SPI flash for BIOS code.
-
-SPI slave chips range from digital/analog converters used for analog
-sensors and codecs, to memory, to peripherals like USB controllers
-or Ethernet adapters; and more.
-
-Most systems using SPI will integrate a few devices on a mainboard.
-Some provide SPI links on expansion connectors; in cases where no
-dedicated SPI controller exists, GPIO pins can be used to create a
-low speed "bitbanging" adapter. Very few systems will "hotplug" an SPI
-controller; the reasons to use SPI focus on low cost and simple operation,
-and if dynamic reconfiguration is important, USB will often be a more
-appropriate low-pincount peripheral bus.
-
-Many microcontrollers that can run Linux integrate one or more I/O
-interfaces with SPI modes. Given SPI support, they could use MMC or SD
-cards without needing a special purpose MMC/SD/SDIO controller.
-
-
-I'm confused. What are these four SPI "clock modes"?
------------------------------------------------------
-It's easy to be confused here, and the vendor documentation you'll
-find isn't necessarily helpful. The four modes combine two mode bits:
-
- - CPOL indicates the initial clock polarity. CPOL=0 means the
- clock starts low, so the first (leading) edge is rising, and
- the second (trailing) edge is falling. CPOL=1 means the clock
- starts high, so the first (leading) edge is falling.
-
- - CPHA indicates the clock phase used to sample data; CPHA=0 says
- sample on the leading edge, CPHA=1 means the trailing edge.
-
- Since the signal needs to stablize before it's sampled, CPHA=0
- implies that its data is written half a clock before the first
- clock edge. The chipselect may have made it become available.
-
-Chip specs won't always say "uses SPI mode X" in as many words,
-but their timing diagrams will make the CPOL and CPHA modes clear.
-
-In the SPI mode number, CPOL is the high order bit and CPHA is the
-low order bit. So when a chip's timing diagram shows the clock
-starting low (CPOL=0) and data stabilized for sampling during the
-trailing clock edge (CPHA=1), that's SPI mode 1.
-
-Note that the clock mode is relevant as soon as the chipselect goes
-active. So the master must set the clock to inactive before selecting
-a slave, and the slave can tell the chosen polarity by sampling the
-clock level when its select line goes active. That's why many devices
-support for example both modes 0 and 3: they don't care about polarity,
-and always clock data in/out on rising clock edges.
-
-
-How do these driver programming interfaces work?
-------------------------------------------------
-The <linux/spi/spi.h> header file includes kerneldoc, as does the
-main source code, and you should certainly read that chapter of the
-kernel API document. This is just an overview, so you get the big
-picture before those details.
-
-SPI requests always go into I/O queues. Requests for a given SPI device
-are always executed in FIFO order, and complete asynchronously through
-completion callbacks. There are also some simple synchronous wrappers
-for those calls, including ones for common transaction types like writing
-a command and then reading its response.
-
-There are two types of SPI driver, here called:
-
- Controller drivers ... controllers may be built into System-On-Chip
- processors, and often support both Master and Slave roles.
- These drivers touch hardware registers and may use DMA.
- Or they can be PIO bitbangers, needing just GPIO pins.
-
- Protocol drivers ... these pass messages through the controller
- driver to communicate with a Slave or Master device on the
- other side of an SPI link.
-
-So for example one protocol driver might talk to the MTD layer to export
-data to filesystems stored on SPI flash like DataFlash; and others might
-control audio interfaces, present touchscreen sensors as input interfaces,
-or monitor temperature and voltage levels during industrial processing.
-And those might all be sharing the same controller driver.
-
-A "struct spi_device" encapsulates the controller-side interface between
-those two types of drivers.
-
-There is a minimal core of SPI programming interfaces, focussing on
-using the driver model to connect controller and protocol drivers using
-device tables provided by board specific initialization code. SPI
-shows up in sysfs in several locations:
-
- /sys/devices/.../CTLR ... physical node for a given SPI controller
-
- /sys/devices/.../CTLR/spiB.C ... spi_device on bus "B",
- chipselect C, accessed through CTLR.
-
- /sys/bus/spi/devices/spiB.C ... symlink to that physical
- .../CTLR/spiB.C device
-
- /sys/devices/.../CTLR/spiB.C/modalias ... identifies the driver
- that should be used with this device (for hotplug/coldplug)
-
- /sys/bus/spi/drivers/D ... driver for one or more spi*.* devices
-
- /sys/class/spi_master/spiB ... symlink (or actual device node) to
- a logical node which could hold class related state for the SPI
- master controller managing bus "B". All spiB.* devices share one
- physical SPI bus segment, with SCLK, MOSI, and MISO.
-
- /sys/devices/.../CTLR/slave ... virtual file for (un)registering the
- slave device for an SPI slave controller.
- Writing the driver name of an SPI slave handler to this file
- registers the slave device; writing "(null)" unregisters the slave
- device.
- Reading from this file shows the name of the slave device ("(null)"
- if not registered).
-
- /sys/class/spi_slave/spiB ... symlink (or actual device node) to
- a logical node which could hold class related state for the SPI
- slave controller on bus "B". When registered, a single spiB.*
- device is present here, possible sharing the physical SPI bus
- segment with other SPI slave devices.
-
-Note that the actual location of the controller's class state depends
-on whether you enabled CONFIG_SYSFS_DEPRECATED or not. At this time,
-the only class-specific state is the bus number ("B" in "spiB"), so
-those /sys/class entries are only useful to quickly identify busses.
-
-
-How does board-specific init code declare SPI devices?
-------------------------------------------------------
-Linux needs several kinds of information to properly configure SPI devices.
-That information is normally provided by board-specific code, even for
-chips that do support some of automated discovery/enumeration.
-
-DECLARE CONTROLLERS
-
-The first kind of information is a list of what SPI controllers exist.
-For System-on-Chip (SOC) based boards, these will usually be platform
-devices, and the controller may need some platform_data in order to
-operate properly. The "struct platform_device" will include resources
-like the physical address of the controller's first register and its IRQ.
-
-Platforms will often abstract the "register SPI controller" operation,
-maybe coupling it with code to initialize pin configurations, so that
-the arch/.../mach-*/board-*.c files for several boards can all share the
-same basic controller setup code. This is because most SOCs have several
-SPI-capable controllers, and only the ones actually usable on a given
-board should normally be set up and registered.
-
-So for example arch/.../mach-*/board-*.c files might have code like:
-
- #include <mach/spi.h> /* for mysoc_spi_data */
-
- /* if your mach-* infrastructure doesn't support kernels that can
- * run on multiple boards, pdata wouldn't benefit from "__init".
- */
- static struct mysoc_spi_data pdata __initdata = { ... };
-
- static __init board_init(void)
- {
- ...
- /* this board only uses SPI controller #2 */
- mysoc_register_spi(2, &pdata);
- ...
- }
-
-And SOC-specific utility code might look something like:
-
- #include <mach/spi.h>
-
- static struct platform_device spi2 = { ... };
-
- void mysoc_register_spi(unsigned n, struct mysoc_spi_data *pdata)
- {
- struct mysoc_spi_data *pdata2;
-
- pdata2 = kmalloc(sizeof *pdata2, GFP_KERNEL);
- *pdata2 = pdata;
- ...
- if (n == 2) {
- spi2->dev.platform_data = pdata2;
- register_platform_device(&spi2);
-
- /* also: set up pin modes so the spi2 signals are
- * visible on the relevant pins ... bootloaders on
- * production boards may already have done this, but
- * developer boards will often need Linux to do it.
- */
- }
- ...
- }
-
-Notice how the platform_data for boards may be different, even if the
-same SOC controller is used. For example, on one board SPI might use
-an external clock, where another derives the SPI clock from current
-settings of some master clock.
-
-
-DECLARE SLAVE DEVICES
-
-The second kind of information is a list of what SPI slave devices exist
-on the target board, often with some board-specific data needed for the
-driver to work correctly.
-
-Normally your arch/.../mach-*/board-*.c files would provide a small table
-listing the SPI devices on each board. (This would typically be only a
-small handful.) That might look like:
-
- static struct ads7846_platform_data ads_info = {
- .vref_delay_usecs = 100,
- .x_plate_ohms = 580,
- .y_plate_ohms = 410,
- };
-
- static struct spi_board_info spi_board_info[] __initdata = {
- {
- .modalias = "ads7846",
- .platform_data = &ads_info,
- .mode = SPI_MODE_0,
- .irq = GPIO_IRQ(31),
- .max_speed_hz = 120000 /* max sample rate at 3V */ * 16,
- .bus_num = 1,
- .chip_select = 0,
- },
- };
-
-Again, notice how board-specific information is provided; each chip may need
-several types. This example shows generic constraints like the fastest SPI
-clock to allow (a function of board voltage in this case) or how an IRQ pin
-is wired, plus chip-specific constraints like an important delay that's
-changed by the capacitance at one pin.
-
-(There's also "controller_data", information that may be useful to the
-controller driver. An example would be peripheral-specific DMA tuning
-data or chipselect callbacks. This is stored in spi_device later.)
-
-The board_info should provide enough information to let the system work
-without the chip's driver being loaded. The most troublesome aspect of
-that is likely the SPI_CS_HIGH bit in the spi_device.mode field, since
-sharing a bus with a device that interprets chipselect "backwards" is
-not possible until the infrastructure knows how to deselect it.
-
-Then your board initialization code would register that table with the SPI
-infrastructure, so that it's available later when the SPI master controller
-driver is registered:
-
- spi_register_board_info(spi_board_info, ARRAY_SIZE(spi_board_info));
-
-Like with other static board-specific setup, you won't unregister those.
-
-The widely used "card" style computers bundle memory, cpu, and little else
-onto a card that's maybe just thirty square centimeters. On such systems,
-your arch/.../mach-.../board-*.c file would primarily provide information
-about the devices on the mainboard into which such a card is plugged. That
-certainly includes SPI devices hooked up through the card connectors!
-
-
-NON-STATIC CONFIGURATIONS
-
-Developer boards often play by different rules than product boards, and one
-example is the potential need to hotplug SPI devices and/or controllers.
-
-For those cases you might need to use spi_busnum_to_master() to look
-up the spi bus master, and will likely need spi_new_device() to provide the
-board info based on the board that was hotplugged. Of course, you'd later
-call at least spi_unregister_device() when that board is removed.
-
-When Linux includes support for MMC/SD/SDIO/DataFlash cards through SPI, those
-configurations will also be dynamic. Fortunately, such devices all support
-basic device identification probes, so they should hotplug normally.
-
-
-How do I write an "SPI Protocol Driver"?
-----------------------------------------
-Most SPI drivers are currently kernel drivers, but there's also support
-for userspace drivers. Here we talk only about kernel drivers.
-
-SPI protocol drivers somewhat resemble platform device drivers:
-
- static struct spi_driver CHIP_driver = {
- .driver = {
- .name = "CHIP",
- .owner = THIS_MODULE,
- .pm = &CHIP_pm_ops,
- },
-
- .probe = CHIP_probe,
- .remove = CHIP_remove,
- };
-
-The driver core will automatically attempt to bind this driver to any SPI
-device whose board_info gave a modalias of "CHIP". Your probe() code
-might look like this unless you're creating a device which is managing
-a bus (appearing under /sys/class/spi_master).
-
- static int CHIP_probe(struct spi_device *spi)
- {
- struct CHIP *chip;
- struct CHIP_platform_data *pdata;
-
- /* assuming the driver requires board-specific data: */
- pdata = &spi->dev.platform_data;
- if (!pdata)
- return -ENODEV;
-
- /* get memory for driver's per-chip state */
- chip = kzalloc(sizeof *chip, GFP_KERNEL);
- if (!chip)
- return -ENOMEM;
- spi_set_drvdata(spi, chip);
-
- ... etc
- return 0;
- }
-
-As soon as it enters probe(), the driver may issue I/O requests to
-the SPI device using "struct spi_message". When remove() returns,
-or after probe() fails, the driver guarantees that it won't submit
-any more such messages.
-
- - An spi_message is a sequence of protocol operations, executed
- as one atomic sequence. SPI driver controls include:
-
- + when bidirectional reads and writes start ... by how its
- sequence of spi_transfer requests is arranged;
-
- + which I/O buffers are used ... each spi_transfer wraps a
- buffer for each transfer direction, supporting full duplex
- (two pointers, maybe the same one in both cases) and half
- duplex (one pointer is NULL) transfers;
-
- + optionally defining short delays after transfers ... using
- the spi_transfer.delay_usecs setting (this delay can be the
- only protocol effect, if the buffer length is zero);
-
- + whether the chipselect becomes inactive after a transfer and
- any delay ... by using the spi_transfer.cs_change flag;
-
- + hinting whether the next message is likely to go to this same
- device ... using the spi_transfer.cs_change flag on the last
- transfer in that atomic group, and potentially saving costs
- for chip deselect and select operations.
-
- - Follow standard kernel rules, and provide DMA-safe buffers in
- your messages. That way controller drivers using DMA aren't forced
- to make extra copies unless the hardware requires it (e.g. working
- around hardware errata that force the use of bounce buffering).
-
- If standard dma_map_single() handling of these buffers is inappropriate,
- you can use spi_message.is_dma_mapped to tell the controller driver
- that you've already provided the relevant DMA addresses.
-
- - The basic I/O primitive is spi_async(). Async requests may be
- issued in any context (irq handler, task, etc) and completion
- is reported using a callback provided with the message.
- After any detected error, the chip is deselected and processing
- of that spi_message is aborted.
-
- - There are also synchronous wrappers like spi_sync(), and wrappers
- like spi_read(), spi_write(), and spi_write_then_read(). These
- may be issued only in contexts that may sleep, and they're all
- clean (and small, and "optional") layers over spi_async().
-
- - The spi_write_then_read() call, and convenience wrappers around
- it, should only be used with small amounts of data where the
- cost of an extra copy may be ignored. It's designed to support
- common RPC-style requests, such as writing an eight bit command
- and reading a sixteen bit response -- spi_w8r16() being one its
- wrappers, doing exactly that.
-
-Some drivers may need to modify spi_device characteristics like the
-transfer mode, wordsize, or clock rate. This is done with spi_setup(),
-which would normally be called from probe() before the first I/O is
-done to the device. However, that can also be called at any time
-that no message is pending for that device.
-
-While "spi_device" would be the bottom boundary of the driver, the
-upper boundaries might include sysfs (especially for sensor readings),
-the input layer, ALSA, networking, MTD, the character device framework,
-or other Linux subsystems.
-
-Note that there are two types of memory your driver must manage as part
-of interacting with SPI devices.
-
- - I/O buffers use the usual Linux rules, and must be DMA-safe.
- You'd normally allocate them from the heap or free page pool.
- Don't use the stack, or anything that's declared "static".
-
- - The spi_message and spi_transfer metadata used to glue those
- I/O buffers into a group of protocol transactions. These can
- be allocated anywhere it's convenient, including as part of
- other allocate-once driver data structures. Zero-init these.
-
-If you like, spi_message_alloc() and spi_message_free() convenience
-routines are available to allocate and zero-initialize an spi_message
-with several transfers.
-
-
-How do I write an "SPI Master Controller Driver"?
--------------------------------------------------
-An SPI controller will probably be registered on the platform_bus; write
-a driver to bind to the device, whichever bus is involved.
-
-The main task of this type of driver is to provide an "spi_master".
-Use spi_alloc_master() to allocate the master, and spi_master_get_devdata()
-to get the driver-private data allocated for that device.
-
- struct spi_master *master;
- struct CONTROLLER *c;
-
- master = spi_alloc_master(dev, sizeof *c);
- if (!master)
- return -ENODEV;
-
- c = spi_master_get_devdata(master);
-
-The driver will initialize the fields of that spi_master, including the
-bus number (maybe the same as the platform device ID) and three methods
-used to interact with the SPI core and SPI protocol drivers. It will
-also initialize its own internal state. (See below about bus numbering
-and those methods.)
-
-After you initialize the spi_master, then use spi_register_master() to
-publish it to the rest of the system. At that time, device nodes for the
-controller and any predeclared spi devices will be made available, and
-the driver model core will take care of binding them to drivers.
-
-If you need to remove your SPI controller driver, spi_unregister_master()
-will reverse the effect of spi_register_master().
-
-
-BUS NUMBERING
-
-Bus numbering is important, since that's how Linux identifies a given
-SPI bus (shared SCK, MOSI, MISO). Valid bus numbers start at zero. On
-SOC systems, the bus numbers should match the numbers defined by the chip
-manufacturer. For example, hardware controller SPI2 would be bus number 2,
-and spi_board_info for devices connected to it would use that number.
-
-If you don't have such hardware-assigned bus number, and for some reason
-you can't just assign them, then provide a negative bus number. That will
-then be replaced by a dynamically assigned number. You'd then need to treat
-this as a non-static configuration (see above).
-
-
-SPI MASTER METHODS
-
- master->setup(struct spi_device *spi)
- This sets up the device clock rate, SPI mode, and word sizes.
- Drivers may change the defaults provided by board_info, and then
- call spi_setup(spi) to invoke this routine. It may sleep.
-
- Unless each SPI slave has its own configuration registers, don't
- change them right away ... otherwise drivers could corrupt I/O
- that's in progress for other SPI devices.
-
- ** BUG ALERT: for some reason the first version of
- ** many spi_master drivers seems to get this wrong.
- ** When you code setup(), ASSUME that the controller
- ** is actively processing transfers for another device.
-
- master->cleanup(struct spi_device *spi)
- Your controller driver may use spi_device.controller_state to hold
- state it dynamically associates with that device. If you do that,
- be sure to provide the cleanup() method to free that state.
-
- master->prepare_transfer_hardware(struct spi_master *master)
- This will be called by the queue mechanism to signal to the driver
- that a message is coming in soon, so the subsystem requests the
- driver to prepare the transfer hardware by issuing this call.
- This may sleep.
-
- master->unprepare_transfer_hardware(struct spi_master *master)
- This will be called by the queue mechanism to signal to the driver
- that there are no more messages pending in the queue and it may
- relax the hardware (e.g. by power management calls). This may sleep.
-
- master->transfer_one_message(struct spi_master *master,
- struct spi_message *mesg)
- The subsystem calls the driver to transfer a single message while
- queuing transfers that arrive in the meantime. When the driver is
- finished with this message, it must call
- spi_finalize_current_message() so the subsystem can issue the next
- message. This may sleep.
-
- master->transfer_one(struct spi_master *master, struct spi_device *spi,
- struct spi_transfer *transfer)
- The subsystem calls the driver to transfer a single transfer while
- queuing transfers that arrive in the meantime. When the driver is
- finished with this transfer, it must call
- spi_finalize_current_transfer() so the subsystem can issue the next
- transfer. This may sleep. Note: transfer_one and transfer_one_message
- are mutually exclusive; when both are set, the generic subsystem does
- not call your transfer_one callback.
-
- Return values:
- negative errno: error
- 0: transfer is finished
- 1: transfer is still in progress
-
- master->set_cs_timing(struct spi_device *spi, u8 setup_clk_cycles,
- u8 hold_clk_cycles, u8 inactive_clk_cycles)
- This method allows SPI client drivers to request SPI master controller
- for configuring device specific CS setup, hold and inactive timing
- requirements.
-
- DEPRECATED METHODS
-
- master->transfer(struct spi_device *spi, struct spi_message *message)
- This must not sleep. Its responsibility is to arrange that the
- transfer happens and its complete() callback is issued. The two
- will normally happen later, after other transfers complete, and
- if the controller is idle it will need to be kickstarted. This
- method is not used on queued controllers and must be NULL if
- transfer_one_message() and (un)prepare_transfer_hardware() are
- implemented.
-
-
-SPI MESSAGE QUEUE
-
-If you are happy with the standard queueing mechanism provided by the
-SPI subsystem, just implement the queued methods specified above. Using
-the message queue has the upside of centralizing a lot of code and
-providing pure process-context execution of methods. The message queue
-can also be elevated to realtime priority on high-priority SPI traffic.
-
-Unless the queueing mechanism in the SPI subsystem is selected, the bulk
-of the driver will be managing the I/O queue fed by the now deprecated
-function transfer().
-
-That queue could be purely conceptual. For example, a driver used only
-for low-frequency sensor access might be fine using synchronous PIO.
-
-But the queue will probably be very real, using message->queue, PIO,
-often DMA (especially if the root filesystem is in SPI flash), and
-execution contexts like IRQ handlers, tasklets, or workqueues (such
-as keventd). Your driver can be as fancy, or as simple, as you need.
-Such a transfer() method would normally just add the message to a
-queue, and then start some asynchronous transfer engine (unless it's
-already running).
-
-
-THANKS TO
----------
-Contributors to Linux-SPI discussions include (in alphabetical order,
-by last name):
-
-Mark Brown
-David Brownell
-Russell King
-Grant Likely
-Dmitry Pervushin
-Stephen Street
-Mark Underwood
-Andrew Victor
-Linus Walleij
-Vitaly Wool
diff --git a/Documentation/spi/spi-summary.rst b/Documentation/spi/spi-summary.rst
new file mode 100644
index 0000000..f1daffe
--- /dev/null
+++ b/Documentation/spi/spi-summary.rst
@@ -0,0 +1,644 @@
+====================================
+Overview of Linux kernel SPI support
+====================================
+
+02-Feb-2012
+
+What is SPI?
+------------
+The "Serial Peripheral Interface" (SPI) is a synchronous four wire serial
+link used to connect microcontrollers to sensors, memory, and peripherals.
+It's a simple "de facto" standard, not complicated enough to acquire a
+standardization body. SPI uses a master/slave configuration.
+
+The three signal wires hold a clock (SCK, often on the order of 10 MHz),
+and parallel data lines with "Master Out, Slave In" (MOSI) or "Master In,
+Slave Out" (MISO) signals. (Other names are also used.) There are four
+clocking modes through which data is exchanged; mode-0 and mode-3 are most
+commonly used. Each clock cycle shifts data out and data in; the clock
+doesn't cycle except when there is a data bit to shift. Not all data bits
+are used though; not every protocol uses those full duplex capabilities.
+
+SPI masters use a fourth "chip select" line to activate a given SPI slave
+device, so those three signal wires may be connected to several chips
+in parallel. All SPI slaves support chipselects; they are usually active
+low signals, labeled nCSx for slave 'x' (e.g. nCS0). Some devices have
+other signals, often including an interrupt to the master.
+
+Unlike serial busses like USB or SMBus, even low level protocols for
+SPI slave functions are usually not interoperable between vendors
+(except for commodities like SPI memory chips).
+
+ - SPI may be used for request/response style device protocols, as with
+ touchscreen sensors and memory chips.
+
+ - It may also be used to stream data in either direction (half duplex),
+ or both of them at the same time (full duplex).
+
+ - Some devices may use eight bit words. Others may use different word
+ lengths, such as streams of 12-bit or 20-bit digital samples.
+
+ - Words are usually sent with their most significant bit (MSB) first,
+ but sometimes the least significant bit (LSB) goes first instead.
+
+ - Sometimes SPI is used to daisy-chain devices, like shift registers.
+
+In the same way, SPI slaves will only rarely support any kind of automatic
+discovery/enumeration protocol. The tree of slave devices accessible from
+a given SPI master will normally be set up manually, with configuration
+tables.
+
+SPI is only one of the names used by such four-wire protocols, and
+most controllers have no problem handling "MicroWire" (think of it as
+half-duplex SPI, for request/response protocols), SSP ("Synchronous
+Serial Protocol"), PSP ("Programmable Serial Protocol"), and other
+related protocols.
+
+Some chips eliminate a signal line by combining MOSI and MISO, and
+limiting themselves to half-duplex at the hardware level. In fact
+some SPI chips have this signal mode as a strapping option. These
+can be accessed using the same programming interface as SPI, but of
+course they won't handle full duplex transfers. You may find such
+chips described as using "three wire" signaling: SCK, data, nCSx.
+(That data line is sometimes called MOMI or SISO.)
+
+Microcontrollers often support both master and slave sides of the SPI
+protocol. This document (and Linux) supports both the master and slave
+sides of SPI interactions.
+
+
+Who uses it? On what kinds of systems?
+---------------------------------------
+Linux developers using SPI are probably writing device drivers for embedded
+systems boards. SPI is used to control external chips, and it is also a
+protocol supported by every MMC or SD memory card. (The older "DataFlash"
+cards, predating MMC cards but using the same connectors and card shape,
+support only SPI.) Some PC hardware uses SPI flash for BIOS code.
+
+SPI slave chips range from digital/analog converters used for analog
+sensors and codecs, to memory, to peripherals like USB controllers
+or Ethernet adapters; and more.
+
+Most systems using SPI will integrate a few devices on a mainboard.
+Some provide SPI links on expansion connectors; in cases where no
+dedicated SPI controller exists, GPIO pins can be used to create a
+low speed "bitbanging" adapter. Very few systems will "hotplug" an SPI
+controller; the reasons to use SPI focus on low cost and simple operation,
+and if dynamic reconfiguration is important, USB will often be a more
+appropriate low-pincount peripheral bus.
+
+Many microcontrollers that can run Linux integrate one or more I/O
+interfaces with SPI modes. Given SPI support, they could use MMC or SD
+cards without needing a special purpose MMC/SD/SDIO controller.
+
+
+I'm confused. What are these four SPI "clock modes"?
+-----------------------------------------------------
+It's easy to be confused here, and the vendor documentation you'll
+find isn't necessarily helpful. The four modes combine two mode bits:
+
+ - CPOL indicates the initial clock polarity. CPOL=0 means the
+ clock starts low, so the first (leading) edge is rising, and
+ the second (trailing) edge is falling. CPOL=1 means the clock
+ starts high, so the first (leading) edge is falling.
+
+ - CPHA indicates the clock phase used to sample data; CPHA=0 says
+ sample on the leading edge, CPHA=1 means the trailing edge.
+
+ Since the signal needs to stablize before it's sampled, CPHA=0
+ implies that its data is written half a clock before the first
+ clock edge. The chipselect may have made it become available.
+
+Chip specs won't always say "uses SPI mode X" in as many words,
+but their timing diagrams will make the CPOL and CPHA modes clear.
+
+In the SPI mode number, CPOL is the high order bit and CPHA is the
+low order bit. So when a chip's timing diagram shows the clock
+starting low (CPOL=0) and data stabilized for sampling during the
+trailing clock edge (CPHA=1), that's SPI mode 1.
+
+Note that the clock mode is relevant as soon as the chipselect goes
+active. So the master must set the clock to inactive before selecting
+a slave, and the slave can tell the chosen polarity by sampling the
+clock level when its select line goes active. That's why many devices
+support for example both modes 0 and 3: they don't care about polarity,
+and always clock data in/out on rising clock edges.
+
+
+How do these driver programming interfaces work?
+------------------------------------------------
+The <linux/spi/spi.h> header file includes kerneldoc, as does the
+main source code, and you should certainly read that chapter of the
+kernel API document. This is just an overview, so you get the big
+picture before those details.
+
+SPI requests always go into I/O queues. Requests for a given SPI device
+are always executed in FIFO order, and complete asynchronously through
+completion callbacks. There are also some simple synchronous wrappers
+for those calls, including ones for common transaction types like writing
+a command and then reading its response.
+
+There are two types of SPI driver, here called:
+
+ Controller drivers ...
+ controllers may be built into System-On-Chip
+ processors, and often support both Master and Slave roles.
+ These drivers touch hardware registers and may use DMA.
+ Or they can be PIO bitbangers, needing just GPIO pins.
+
+ Protocol drivers ...
+ these pass messages through the controller
+ driver to communicate with a Slave or Master device on the
+ other side of an SPI link.
+
+So for example one protocol driver might talk to the MTD layer to export
+data to filesystems stored on SPI flash like DataFlash; and others might
+control audio interfaces, present touchscreen sensors as input interfaces,
+or monitor temperature and voltage levels during industrial processing.
+And those might all be sharing the same controller driver.
+
+A "struct spi_device" encapsulates the controller-side interface between
+those two types of drivers.
+
+There is a minimal core of SPI programming interfaces, focussing on
+using the driver model to connect controller and protocol drivers using
+device tables provided by board specific initialization code. SPI
+shows up in sysfs in several locations::
+
+ /sys/devices/.../CTLR ... physical node for a given SPI controller
+
+ /sys/devices/.../CTLR/spiB.C ... spi_device on bus "B",
+ chipselect C, accessed through CTLR.
+
+ /sys/bus/spi/devices/spiB.C ... symlink to that physical
+ .../CTLR/spiB.C device
+
+ /sys/devices/.../CTLR/spiB.C/modalias ... identifies the driver
+ that should be used with this device (for hotplug/coldplug)
+
+ /sys/bus/spi/drivers/D ... driver for one or more spi*.* devices
+
+ /sys/class/spi_master/spiB ... symlink (or actual device node) to
+ a logical node which could hold class related state for the SPI
+ master controller managing bus "B". All spiB.* devices share one
+ physical SPI bus segment, with SCLK, MOSI, and MISO.
+
+ /sys/devices/.../CTLR/slave ... virtual file for (un)registering the
+ slave device for an SPI slave controller.
+ Writing the driver name of an SPI slave handler to this file
+ registers the slave device; writing "(null)" unregisters the slave
+ device.
+ Reading from this file shows the name of the slave device ("(null)"
+ if not registered).
+
+ /sys/class/spi_slave/spiB ... symlink (or actual device node) to
+ a logical node which could hold class related state for the SPI
+ slave controller on bus "B". When registered, a single spiB.*
+ device is present here, possible sharing the physical SPI bus
+ segment with other SPI slave devices.
+
+Note that the actual location of the controller's class state depends
+on whether you enabled CONFIG_SYSFS_DEPRECATED or not. At this time,
+the only class-specific state is the bus number ("B" in "spiB"), so
+those /sys/class entries are only useful to quickly identify busses.
+
+
+How does board-specific init code declare SPI devices?
+------------------------------------------------------
+Linux needs several kinds of information to properly configure SPI devices.
+That information is normally provided by board-specific code, even for
+chips that do support some of automated discovery/enumeration.
+
+Declare Controllers
+^^^^^^^^^^^^^^^^^^^
+
+The first kind of information is a list of what SPI controllers exist.
+For System-on-Chip (SOC) based boards, these will usually be platform
+devices, and the controller may need some platform_data in order to
+operate properly. The "struct platform_device" will include resources
+like the physical address of the controller's first register and its IRQ.
+
+Platforms will often abstract the "register SPI controller" operation,
+maybe coupling it with code to initialize pin configurations, so that
+the arch/.../mach-*/board-*.c files for several boards can all share the
+same basic controller setup code. This is because most SOCs have several
+SPI-capable controllers, and only the ones actually usable on a given
+board should normally be set up and registered.
+
+So for example arch/.../mach-*/board-*.c files might have code like::
+
+ #include <mach/spi.h> /* for mysoc_spi_data */
+
+ /* if your mach-* infrastructure doesn't support kernels that can
+ * run on multiple boards, pdata wouldn't benefit from "__init".
+ */
+ static struct mysoc_spi_data pdata __initdata = { ... };
+
+ static __init board_init(void)
+ {
+ ...
+ /* this board only uses SPI controller #2 */
+ mysoc_register_spi(2, &pdata);
+ ...
+ }
+
+And SOC-specific utility code might look something like::
+
+ #include <mach/spi.h>
+
+ static struct platform_device spi2 = { ... };
+
+ void mysoc_register_spi(unsigned n, struct mysoc_spi_data *pdata)
+ {
+ struct mysoc_spi_data *pdata2;
+
+ pdata2 = kmalloc(sizeof *pdata2, GFP_KERNEL);
+ *pdata2 = pdata;
+ ...
+ if (n == 2) {
+ spi2->dev.platform_data = pdata2;
+ register_platform_device(&spi2);
+
+ /* also: set up pin modes so the spi2 signals are
+ * visible on the relevant pins ... bootloaders on
+ * production boards may already have done this, but
+ * developer boards will often need Linux to do it.
+ */
+ }
+ ...
+ }
+
+Notice how the platform_data for boards may be different, even if the
+same SOC controller is used. For example, on one board SPI might use
+an external clock, where another derives the SPI clock from current
+settings of some master clock.
+
+Declare Slave Devices
+^^^^^^^^^^^^^^^^^^^^^
+
+The second kind of information is a list of what SPI slave devices exist
+on the target board, often with some board-specific data needed for the
+driver to work correctly.
+
+Normally your arch/.../mach-*/board-*.c files would provide a small table
+listing the SPI devices on each board. (This would typically be only a
+small handful.) That might look like::
+
+ static struct ads7846_platform_data ads_info = {
+ .vref_delay_usecs = 100,
+ .x_plate_ohms = 580,
+ .y_plate_ohms = 410,
+ };
+
+ static struct spi_board_info spi_board_info[] __initdata = {
+ {
+ .modalias = "ads7846",
+ .platform_data = &ads_info,
+ .mode = SPI_MODE_0,
+ .irq = GPIO_IRQ(31),
+ .max_speed_hz = 120000 /* max sample rate at 3V */ * 16,
+ .bus_num = 1,
+ .chip_select = 0,
+ },
+ };
+
+Again, notice how board-specific information is provided; each chip may need
+several types. This example shows generic constraints like the fastest SPI
+clock to allow (a function of board voltage in this case) or how an IRQ pin
+is wired, plus chip-specific constraints like an important delay that's
+changed by the capacitance at one pin.
+
+(There's also "controller_data", information that may be useful to the
+controller driver. An example would be peripheral-specific DMA tuning
+data or chipselect callbacks. This is stored in spi_device later.)
+
+The board_info should provide enough information to let the system work
+without the chip's driver being loaded. The most troublesome aspect of
+that is likely the SPI_CS_HIGH bit in the spi_device.mode field, since
+sharing a bus with a device that interprets chipselect "backwards" is
+not possible until the infrastructure knows how to deselect it.
+
+Then your board initialization code would register that table with the SPI
+infrastructure, so that it's available later when the SPI master controller
+driver is registered::
+
+ spi_register_board_info(spi_board_info, ARRAY_SIZE(spi_board_info));
+
+Like with other static board-specific setup, you won't unregister those.
+
+The widely used "card" style computers bundle memory, cpu, and little else
+onto a card that's maybe just thirty square centimeters. On such systems,
+your ``arch/.../mach-.../board-*.c`` file would primarily provide information
+about the devices on the mainboard into which such a card is plugged. That
+certainly includes SPI devices hooked up through the card connectors!
+
+
+Non-static Configurations
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Developer boards often play by different rules than product boards, and one
+example is the potential need to hotplug SPI devices and/or controllers.
+
+For those cases you might need to use spi_busnum_to_master() to look
+up the spi bus master, and will likely need spi_new_device() to provide the
+board info based on the board that was hotplugged. Of course, you'd later
+call at least spi_unregister_device() when that board is removed.
+
+When Linux includes support for MMC/SD/SDIO/DataFlash cards through SPI, those
+configurations will also be dynamic. Fortunately, such devices all support
+basic device identification probes, so they should hotplug normally.
+
+
+How do I write an "SPI Protocol Driver"?
+----------------------------------------
+Most SPI drivers are currently kernel drivers, but there's also support
+for userspace drivers. Here we talk only about kernel drivers.
+
+SPI protocol drivers somewhat resemble platform device drivers::
+
+ static struct spi_driver CHIP_driver = {
+ .driver = {
+ .name = "CHIP",
+ .owner = THIS_MODULE,
+ .pm = &CHIP_pm_ops,
+ },
+
+ .probe = CHIP_probe,
+ .remove = CHIP_remove,
+ };
+
+The driver core will automatically attempt to bind this driver to any SPI
+device whose board_info gave a modalias of "CHIP". Your probe() code
+might look like this unless you're creating a device which is managing
+a bus (appearing under /sys/class/spi_master).
+
+::
+
+ static int CHIP_probe(struct spi_device *spi)
+ {
+ struct CHIP *chip;
+ struct CHIP_platform_data *pdata;
+
+ /* assuming the driver requires board-specific data: */
+ pdata = &spi->dev.platform_data;
+ if (!pdata)
+ return -ENODEV;
+
+ /* get memory for driver's per-chip state */
+ chip = kzalloc(sizeof *chip, GFP_KERNEL);
+ if (!chip)
+ return -ENOMEM;
+ spi_set_drvdata(spi, chip);
+
+ ... etc
+ return 0;
+ }
+
+As soon as it enters probe(), the driver may issue I/O requests to
+the SPI device using "struct spi_message". When remove() returns,
+or after probe() fails, the driver guarantees that it won't submit
+any more such messages.
+
+ - An spi_message is a sequence of protocol operations, executed
+ as one atomic sequence. SPI driver controls include:
+
+ + when bidirectional reads and writes start ... by how its
+ sequence of spi_transfer requests is arranged;
+
+ + which I/O buffers are used ... each spi_transfer wraps a
+ buffer for each transfer direction, supporting full duplex
+ (two pointers, maybe the same one in both cases) and half
+ duplex (one pointer is NULL) transfers;
+
+ + optionally defining short delays after transfers ... using
+ the spi_transfer.delay_usecs setting (this delay can be the
+ only protocol effect, if the buffer length is zero);
+
+ + whether the chipselect becomes inactive after a transfer and
+ any delay ... by using the spi_transfer.cs_change flag;
+
+ + hinting whether the next message is likely to go to this same
+ device ... using the spi_transfer.cs_change flag on the last
+ transfer in that atomic group, and potentially saving costs
+ for chip deselect and select operations.
+
+ - Follow standard kernel rules, and provide DMA-safe buffers in
+ your messages. That way controller drivers using DMA aren't forced
+ to make extra copies unless the hardware requires it (e.g. working
+ around hardware errata that force the use of bounce buffering).
+
+ If standard dma_map_single() handling of these buffers is inappropriate,
+ you can use spi_message.is_dma_mapped to tell the controller driver
+ that you've already provided the relevant DMA addresses.
+
+ - The basic I/O primitive is spi_async(). Async requests may be
+ issued in any context (irq handler, task, etc) and completion
+ is reported using a callback provided with the message.
+ After any detected error, the chip is deselected and processing
+ of that spi_message is aborted.
+
+ - There are also synchronous wrappers like spi_sync(), and wrappers
+ like spi_read(), spi_write(), and spi_write_then_read(). These
+ may be issued only in contexts that may sleep, and they're all
+ clean (and small, and "optional") layers over spi_async().
+
+ - The spi_write_then_read() call, and convenience wrappers around
+ it, should only be used with small amounts of data where the
+ cost of an extra copy may be ignored. It's designed to support
+ common RPC-style requests, such as writing an eight bit command
+ and reading a sixteen bit response -- spi_w8r16() being one its
+ wrappers, doing exactly that.
+
+Some drivers may need to modify spi_device characteristics like the
+transfer mode, wordsize, or clock rate. This is done with spi_setup(),
+which would normally be called from probe() before the first I/O is
+done to the device. However, that can also be called at any time
+that no message is pending for that device.
+
+While "spi_device" would be the bottom boundary of the driver, the
+upper boundaries might include sysfs (especially for sensor readings),
+the input layer, ALSA, networking, MTD, the character device framework,
+or other Linux subsystems.
+
+Note that there are two types of memory your driver must manage as part
+of interacting with SPI devices.
+
+ - I/O buffers use the usual Linux rules, and must be DMA-safe.
+ You'd normally allocate them from the heap or free page pool.
+ Don't use the stack, or anything that's declared "static".
+
+ - The spi_message and spi_transfer metadata used to glue those
+ I/O buffers into a group of protocol transactions. These can
+ be allocated anywhere it's convenient, including as part of
+ other allocate-once driver data structures. Zero-init these.
+
+If you like, spi_message_alloc() and spi_message_free() convenience
+routines are available to allocate and zero-initialize an spi_message
+with several transfers.
+
+
+How do I write an "SPI Master Controller Driver"?
+-------------------------------------------------
+An SPI controller will probably be registered on the platform_bus; write
+a driver to bind to the device, whichever bus is involved.
+
+The main task of this type of driver is to provide an "spi_master".
+Use spi_alloc_master() to allocate the master, and spi_master_get_devdata()
+to get the driver-private data allocated for that device.
+
+::
+
+ struct spi_master *master;
+ struct CONTROLLER *c;
+
+ master = spi_alloc_master(dev, sizeof *c);
+ if (!master)
+ return -ENODEV;
+
+ c = spi_master_get_devdata(master);
+
+The driver will initialize the fields of that spi_master, including the
+bus number (maybe the same as the platform device ID) and three methods
+used to interact with the SPI core and SPI protocol drivers. It will
+also initialize its own internal state. (See below about bus numbering
+and those methods.)
+
+After you initialize the spi_master, then use spi_register_master() to
+publish it to the rest of the system. At that time, device nodes for the
+controller and any predeclared spi devices will be made available, and
+the driver model core will take care of binding them to drivers.
+
+If you need to remove your SPI controller driver, spi_unregister_master()
+will reverse the effect of spi_register_master().
+
+
+Bus Numbering
+^^^^^^^^^^^^^
+
+Bus numbering is important, since that's how Linux identifies a given
+SPI bus (shared SCK, MOSI, MISO). Valid bus numbers start at zero. On
+SOC systems, the bus numbers should match the numbers defined by the chip
+manufacturer. For example, hardware controller SPI2 would be bus number 2,
+and spi_board_info for devices connected to it would use that number.
+
+If you don't have such hardware-assigned bus number, and for some reason
+you can't just assign them, then provide a negative bus number. That will
+then be replaced by a dynamically assigned number. You'd then need to treat
+this as a non-static configuration (see above).
+
+
+SPI Master Methods
+^^^^^^^^^^^^^^^^^^
+
+``master->setup(struct spi_device *spi)``
+ This sets up the device clock rate, SPI mode, and word sizes.
+ Drivers may change the defaults provided by board_info, and then
+ call spi_setup(spi) to invoke this routine. It may sleep.
+
+ Unless each SPI slave has its own configuration registers, don't
+ change them right away ... otherwise drivers could corrupt I/O
+ that's in progress for other SPI devices.
+
+ .. note::
+
+ BUG ALERT: for some reason the first version of
+ many spi_master drivers seems to get this wrong.
+ When you code setup(), ASSUME that the controller
+ is actively processing transfers for another device.
+
+``master->cleanup(struct spi_device *spi)``
+ Your controller driver may use spi_device.controller_state to hold
+ state it dynamically associates with that device. If you do that,
+ be sure to provide the cleanup() method to free that state.
+
+``master->prepare_transfer_hardware(struct spi_master *master)``
+ This will be called by the queue mechanism to signal to the driver
+ that a message is coming in soon, so the subsystem requests the
+ driver to prepare the transfer hardware by issuing this call.
+ This may sleep.
+
+``master->unprepare_transfer_hardware(struct spi_master *master)``
+ This will be called by the queue mechanism to signal to the driver
+ that there are no more messages pending in the queue and it may
+ relax the hardware (e.g. by power management calls). This may sleep.
+
+``master->transfer_one_message(struct spi_master *master, struct spi_message *mesg)``
+ The subsystem calls the driver to transfer a single message while
+ queuing transfers that arrive in the meantime. When the driver is
+ finished with this message, it must call
+ spi_finalize_current_message() so the subsystem can issue the next
+ message. This may sleep.
+
+``master->transfer_one(struct spi_master *master, struct spi_device *spi, struct spi_transfer *transfer)``
+ The subsystem calls the driver to transfer a single transfer while
+ queuing transfers that arrive in the meantime. When the driver is
+ finished with this transfer, it must call
+ spi_finalize_current_transfer() so the subsystem can issue the next
+ transfer. This may sleep. Note: transfer_one and transfer_one_message
+ are mutually exclusive; when both are set, the generic subsystem does
+ not call your transfer_one callback.
+
+ Return values:
+
+ * negative errno: error
+ * 0: transfer is finished
+ * 1: transfer is still in progress
+
+``master->set_cs_timing(struct spi_device *spi, u8 setup_clk_cycles, u8 hold_clk_cycles, u8 inactive_clk_cycles)``
+ This method allows SPI client drivers to request SPI master controller
+ for configuring device specific CS setup, hold and inactive timing
+ requirements.
+
+Deprecated Methods
+^^^^^^^^^^^^^^^^^^
+
+``master->transfer(struct spi_device *spi, struct spi_message *message)``
+ This must not sleep. Its responsibility is to arrange that the
+ transfer happens and its complete() callback is issued. The two
+ will normally happen later, after other transfers complete, and
+ if the controller is idle it will need to be kickstarted. This
+ method is not used on queued controllers and must be NULL if
+ transfer_one_message() and (un)prepare_transfer_hardware() are
+ implemented.
+
+
+SPI Message Queue
+^^^^^^^^^^^^^^^^^
+
+If you are happy with the standard queueing mechanism provided by the
+SPI subsystem, just implement the queued methods specified above. Using
+the message queue has the upside of centralizing a lot of code and
+providing pure process-context execution of methods. The message queue
+can also be elevated to realtime priority on high-priority SPI traffic.
+
+Unless the queueing mechanism in the SPI subsystem is selected, the bulk
+of the driver will be managing the I/O queue fed by the now deprecated
+function transfer().
+
+That queue could be purely conceptual. For example, a driver used only
+for low-frequency sensor access might be fine using synchronous PIO.
+
+But the queue will probably be very real, using message->queue, PIO,
+often DMA (especially if the root filesystem is in SPI flash), and
+execution contexts like IRQ handlers, tasklets, or workqueues (such
+as keventd). Your driver can be as fancy, or as simple, as you need.
+Such a transfer() method would normally just add the message to a
+queue, and then start some asynchronous transfer engine (unless it's
+already running).
+
+
+THANKS TO
+---------
+Contributors to Linux-SPI discussions include (in alphabetical order,
+by last name):
+
+- Mark Brown
+- David Brownell
+- Russell King
+- Grant Likely
+- Dmitry Pervushin
+- Stephen Street
+- Mark Underwood
+- Andrew Victor
+- Linus Walleij
+- Vitaly Wool
diff --git a/Documentation/spi/spidev b/Documentation/spi/spidev
deleted file mode 100644
index 3d14035..0000000
--- a/Documentation/spi/spidev
+++ /dev/null
@@ -1,149 +0,0 @@
-SPI devices have a limited userspace API, supporting basic half-duplex
-read() and write() access to SPI slave devices. Using ioctl() requests,
-full duplex transfers and device I/O configuration are also available.
-
- #include <fcntl.h>
- #include <unistd.h>
- #include <sys/ioctl.h>
- #include <linux/types.h>
- #include <linux/spi/spidev.h>
-
-Some reasons you might want to use this programming interface include:
-
- * Prototyping in an environment that's not crash-prone; stray pointers
- in userspace won't normally bring down any Linux system.
-
- * Developing simple protocols used to talk to microcontrollers acting
- as SPI slaves, which you may need to change quite often.
-
-Of course there are drivers that can never be written in userspace, because
-they need to access kernel interfaces (such as IRQ handlers or other layers
-of the driver stack) that are not accessible to userspace.
-
-
-DEVICE CREATION, DRIVER BINDING
-===============================
-The simplest way to arrange to use this driver is to just list it in the
-spi_board_info for a device as the driver it should use: the "modalias"
-entry is "spidev", matching the name of the driver exposing this API.
-Set up the other device characteristics (bits per word, SPI clocking,
-chipselect polarity, etc) as usual, so you won't always need to override
-them later.
-
-(Sysfs also supports userspace driven binding/unbinding of drivers to
-devices. That mechanism might be supported here in the future.)
-
-When you do that, the sysfs node for the SPI device will include a child
-device node with a "dev" attribute that will be understood by udev or mdev.
-(Larger systems will have "udev". Smaller ones may configure "mdev" into
-busybox; it's less featureful, but often enough.) For a SPI device with
-chipselect C on bus B, you should see:
-
- /dev/spidevB.C ... character special device, major number 153 with
- a dynamically chosen minor device number. This is the node
- that userspace programs will open, created by "udev" or "mdev".
-
- /sys/devices/.../spiB.C ... as usual, the SPI device node will
- be a child of its SPI master controller.
-
- /sys/class/spidev/spidevB.C ... created when the "spidev" driver
- binds to that device. (Directory or symlink, based on whether
- or not you enabled the "deprecated sysfs files" Kconfig option.)
-
-Do not try to manage the /dev character device special file nodes by hand.
-That's error prone, and you'd need to pay careful attention to system
-security issues; udev/mdev should already be configured securely.
-
-If you unbind the "spidev" driver from that device, those two "spidev" nodes
-(in sysfs and in /dev) should automatically be removed (respectively by the
-kernel and by udev/mdev). You can unbind by removing the "spidev" driver
-module, which will affect all devices using this driver. You can also unbind
-by having kernel code remove the SPI device, probably by removing the driver
-for its SPI controller (so its spi_master vanishes).
-
-Since this is a standard Linux device driver -- even though it just happens
-to expose a low level API to userspace -- it can be associated with any number
-of devices at a time. Just provide one spi_board_info record for each such
-SPI device, and you'll get a /dev device node for each device.
-
-
-BASIC CHARACTER DEVICE API
-==========================
-Normal open() and close() operations on /dev/spidevB.D files work as you
-would expect.
-
-Standard read() and write() operations are obviously only half-duplex, and
-the chipselect is deactivated between those operations. Full-duplex access,
-and composite operation without chipselect de-activation, is available using
-the SPI_IOC_MESSAGE(N) request.
-
-Several ioctl() requests let your driver read or override the device's current
-settings for data transfer parameters:
-
- SPI_IOC_RD_MODE, SPI_IOC_WR_MODE ... pass a pointer to a byte which will
- return (RD) or assign (WR) the SPI transfer mode. Use the constants
- SPI_MODE_0..SPI_MODE_3; or if you prefer you can combine SPI_CPOL
- (clock polarity, idle high iff this is set) or SPI_CPHA (clock phase,
- sample on trailing edge iff this is set) flags.
- Note that this request is limited to SPI mode flags that fit in a
- single byte.
-
- SPI_IOC_RD_MODE32, SPI_IOC_WR_MODE32 ... pass a pointer to a uin32_t
- which will return (RD) or assign (WR) the full SPI transfer mode,
- not limited to the bits that fit in one byte.
-
- SPI_IOC_RD_LSB_FIRST, SPI_IOC_WR_LSB_FIRST ... pass a pointer to a byte
- which will return (RD) or assign (WR) the bit justification used to
- transfer SPI words. Zero indicates MSB-first; other values indicate
- the less common LSB-first encoding. In both cases the specified value
- is right-justified in each word, so that unused (TX) or undefined (RX)
- bits are in the MSBs.
-
- SPI_IOC_RD_BITS_PER_WORD, SPI_IOC_WR_BITS_PER_WORD ... pass a pointer to
- a byte which will return (RD) or assign (WR) the number of bits in
- each SPI transfer word. The value zero signifies eight bits.
-
- SPI_IOC_RD_MAX_SPEED_HZ, SPI_IOC_WR_MAX_SPEED_HZ ... pass a pointer to a
- u32 which will return (RD) or assign (WR) the maximum SPI transfer
- speed, in Hz. The controller can't necessarily assign that specific
- clock speed.
-
-NOTES:
-
- - At this time there is no async I/O support; everything is purely
- synchronous.
-
- - There's currently no way to report the actual bit rate used to
- shift data to/from a given device.
-
- - From userspace, you can't currently change the chip select polarity;
- that could corrupt transfers to other devices sharing the SPI bus.
- Each SPI device is deselected when it's not in active use, allowing
- other drivers to talk to other devices.
-
- - There's a limit on the number of bytes each I/O request can transfer
- to the SPI device. It defaults to one page, but that can be changed
- using a module parameter.
-
- - Because SPI has no low-level transfer acknowledgement, you usually
- won't see any I/O errors when talking to a non-existent device.
-
-
-FULL DUPLEX CHARACTER DEVICE API
-================================
-
-See the spidev_fdx.c sample program for one example showing the use of the
-full duplex programming interface. (Although it doesn't perform a full duplex
-transfer.) The model is the same as that used in the kernel spi_sync()
-request; the individual transfers offer the same capabilities as are
-available to kernel drivers (except that it's not asynchronous).
-
-The example shows one half-duplex RPC-style request and response message.
-These requests commonly require that the chip not be deselected between
-the request and response. Several such requests could be chained into
-a single kernel request, even allowing the chip to be deselected after
-each response. (Other protocol options include changing the word size
-and bitrate for each transfer segment.)
-
-To make a full duplex request, provide both rx_buf and tx_buf for the
-same transfer. It's even OK if those are the same buffer.
diff --git a/Documentation/spi/spidev.rst b/Documentation/spi/spidev.rst
new file mode 100644
index 0000000..f05dbc5
--- /dev/null
+++ b/Documentation/spi/spidev.rst
@@ -0,0 +1,163 @@
+=================
+SPI userspace API
+=================
+
+SPI devices have a limited userspace API, supporting basic half-duplex
+read() and write() access to SPI slave devices. Using ioctl() requests,
+full duplex transfers and device I/O configuration are also available.
+
+::
+
+ #include <fcntl.h>
+ #include <unistd.h>
+ #include <sys/ioctl.h>
+ #include <linux/types.h>
+ #include <linux/spi/spidev.h>
+
+Some reasons you might want to use this programming interface include:
+
+ * Prototyping in an environment that's not crash-prone; stray pointers
+ in userspace won't normally bring down any Linux system.
+
+ * Developing simple protocols used to talk to microcontrollers acting
+ as SPI slaves, which you may need to change quite often.
+
+Of course there are drivers that can never be written in userspace, because
+they need to access kernel interfaces (such as IRQ handlers or other layers
+of the driver stack) that are not accessible to userspace.
+
+
+DEVICE CREATION, DRIVER BINDING
+===============================
+The simplest way to arrange to use this driver is to just list it in the
+spi_board_info for a device as the driver it should use: the "modalias"
+entry is "spidev", matching the name of the driver exposing this API.
+Set up the other device characteristics (bits per word, SPI clocking,
+chipselect polarity, etc) as usual, so you won't always need to override
+them later.
+
+(Sysfs also supports userspace driven binding/unbinding of drivers to
+devices. That mechanism might be supported here in the future.)
+
+When you do that, the sysfs node for the SPI device will include a child
+device node with a "dev" attribute that will be understood by udev or mdev.
+(Larger systems will have "udev". Smaller ones may configure "mdev" into
+busybox; it's less featureful, but often enough.) For a SPI device with
+chipselect C on bus B, you should see:
+
+ /dev/spidevB.C ...
+ character special device, major number 153 with
+ a dynamically chosen minor device number. This is the node
+ that userspace programs will open, created by "udev" or "mdev".
+
+ /sys/devices/.../spiB.C ...
+ as usual, the SPI device node will
+ be a child of its SPI master controller.
+
+ /sys/class/spidev/spidevB.C ...
+ created when the "spidev" driver
+ binds to that device. (Directory or symlink, based on whether
+ or not you enabled the "deprecated sysfs files" Kconfig option.)
+
+Do not try to manage the /dev character device special file nodes by hand.
+That's error prone, and you'd need to pay careful attention to system
+security issues; udev/mdev should already be configured securely.
+
+If you unbind the "spidev" driver from that device, those two "spidev" nodes
+(in sysfs and in /dev) should automatically be removed (respectively by the
+kernel and by udev/mdev). You can unbind by removing the "spidev" driver
+module, which will affect all devices using this driver. You can also unbind
+by having kernel code remove the SPI device, probably by removing the driver
+for its SPI controller (so its spi_master vanishes).
+
+Since this is a standard Linux device driver -- even though it just happens
+to expose a low level API to userspace -- it can be associated with any number
+of devices at a time. Just provide one spi_board_info record for each such
+SPI device, and you'll get a /dev device node for each device.
+
+
+BASIC CHARACTER DEVICE API
+==========================
+Normal open() and close() operations on /dev/spidevB.D files work as you
+would expect.
+
+Standard read() and write() operations are obviously only half-duplex, and
+the chipselect is deactivated between those operations. Full-duplex access,
+and composite operation without chipselect de-activation, is available using
+the SPI_IOC_MESSAGE(N) request.
+
+Several ioctl() requests let your driver read or override the device's current
+settings for data transfer parameters:
+
+ SPI_IOC_RD_MODE, SPI_IOC_WR_MODE ...
+ pass a pointer to a byte which will
+ return (RD) or assign (WR) the SPI transfer mode. Use the constants
+ SPI_MODE_0..SPI_MODE_3; or if you prefer you can combine SPI_CPOL
+ (clock polarity, idle high iff this is set) or SPI_CPHA (clock phase,
+ sample on trailing edge iff this is set) flags.
+ Note that this request is limited to SPI mode flags that fit in a
+ single byte.
+
+ SPI_IOC_RD_MODE32, SPI_IOC_WR_MODE32 ...
+ pass a pointer to a uin32_t
+ which will return (RD) or assign (WR) the full SPI transfer mode,
+ not limited to the bits that fit in one byte.
+
+ SPI_IOC_RD_LSB_FIRST, SPI_IOC_WR_LSB_FIRST ...
+ pass a pointer to a byte
+ which will return (RD) or assign (WR) the bit justification used to
+ transfer SPI words. Zero indicates MSB-first; other values indicate
+ the less common LSB-first encoding. In both cases the specified value
+ is right-justified in each word, so that unused (TX) or undefined (RX)
+ bits are in the MSBs.
+
+ SPI_IOC_RD_BITS_PER_WORD, SPI_IOC_WR_BITS_PER_WORD ...
+ pass a pointer to
+ a byte which will return (RD) or assign (WR) the number of bits in
+ each SPI transfer word. The value zero signifies eight bits.
+
+ SPI_IOC_RD_MAX_SPEED_HZ, SPI_IOC_WR_MAX_SPEED_HZ ...
+ pass a pointer to a
+ u32 which will return (RD) or assign (WR) the maximum SPI transfer
+ speed, in Hz. The controller can't necessarily assign that specific
+ clock speed.
+
+NOTES:
+
+ - At this time there is no async I/O support; everything is purely
+ synchronous.
+
+ - There's currently no way to report the actual bit rate used to
+ shift data to/from a given device.
+
+ - From userspace, you can't currently change the chip select polarity;
+ that could corrupt transfers to other devices sharing the SPI bus.
+ Each SPI device is deselected when it's not in active use, allowing
+ other drivers to talk to other devices.
+
+ - There's a limit on the number of bytes each I/O request can transfer
+ to the SPI device. It defaults to one page, but that can be changed
+ using a module parameter.
+
+ - Because SPI has no low-level transfer acknowledgement, you usually
+ won't see any I/O errors when talking to a non-existent device.
+
+
+FULL DUPLEX CHARACTER DEVICE API
+================================
+
+See the spidev_fdx.c sample program for one example showing the use of the
+full duplex programming interface. (Although it doesn't perform a full duplex
+transfer.) The model is the same as that used in the kernel spi_sync()
+request; the individual transfers offer the same capabilities as are
+available to kernel drivers (except that it's not asynchronous).
+
+The example shows one half-duplex RPC-style request and response message.
+These requests commonly require that the chip not be deselected between
+the request and response. Several such requests could be chained into
+a single kernel request, even allowing the chip to be deselected after
+each response. (Other protocol options include changing the word size
+and bitrate for each transfer segment.)
+
+To make a full duplex request, provide both rx_buf and tx_buf for the
+same transfer. It's even OK if those are the same buffer.
diff --git a/Documentation/thermal/index.rst b/Documentation/thermal/index.rst
deleted file mode 100644
index 8c1c001..0000000
--- a/Documentation/thermal/index.rst
+++ /dev/null
@@ -1,18 +0,0 @@
-:orphan:
-
-=======
-Thermal
-=======
-
-.. toctree::
- :maxdepth: 1
-
- cpu-cooling-api
- sysfs-api
- power_allocator
-
- exynos_thermal
- exynos_thermal_emulation
- intel_powerclamp
- nouveau_thermal
- x86_pkg_temperature_thermal
diff --git a/Documentation/thermal/sysfs-api.rst b/Documentation/thermal/sysfs-api.rst
deleted file mode 100644
index e493076..0000000
--- a/Documentation/thermal/sysfs-api.rst
+++ /dev/null
@@ -1,798 +0,0 @@
-===================================
-Generic Thermal Sysfs driver How To
-===================================
-
-Written by Sujith Thomas <sujith.thomas@intel.com>, Zhang Rui <rui.zhang@intel.com>
-
-Updated: 2 January 2008
-
-Copyright (c) 2008 Intel Corporation
-
-
-0. Introduction
-===============
-
-The generic thermal sysfs provides a set of interfaces for thermal zone
-devices (sensors) and thermal cooling devices (fan, processor...) to register
-with the thermal management solution and to be a part of it.
-
-This how-to focuses on enabling new thermal zone and cooling devices to
-participate in thermal management.
-This solution is platform independent and any type of thermal zone devices
-and cooling devices should be able to make use of the infrastructure.
-
-The main task of the thermal sysfs driver is to expose thermal zone attributes
-as well as cooling device attributes to the user space.
-An intelligent thermal management application can make decisions based on
-inputs from thermal zone attributes (the current temperature and trip point
-temperature) and throttle appropriate devices.
-
-- `[0-*]` denotes any positive number starting from 0
-- `[1-*]` denotes any positive number starting from 1
-
-1. thermal sysfs driver interface functions
-===========================================
-
-1.1 thermal zone device interface
----------------------------------
-
- ::
-
- struct thermal_zone_device
- *thermal_zone_device_register(char *type,
- int trips, int mask, void *devdata,
- struct thermal_zone_device_ops *ops,
- const struct thermal_zone_params *tzp,
- int passive_delay, int polling_delay))
-
- This interface function adds a new thermal zone device (sensor) to
- /sys/class/thermal folder as `thermal_zone[0-*]`. It tries to bind all the
- thermal cooling devices registered at the same time.
-
- type:
- the thermal zone type.
- trips:
- the total number of trip points this thermal zone supports.
- mask:
- Bit string: If 'n'th bit is set, then trip point 'n' is writeable.
- devdata:
- device private data
- ops:
- thermal zone device call-backs.
-
- .bind:
- bind the thermal zone device with a thermal cooling device.
- .unbind:
- unbind the thermal zone device with a thermal cooling device.
- .get_temp:
- get the current temperature of the thermal zone.
- .set_trips:
- set the trip points window. Whenever the current temperature
- is updated, the trip points immediately below and above the
- current temperature are found.
- .get_mode:
- get the current mode (enabled/disabled) of the thermal zone.
-
- - "enabled" means the kernel thermal management is
- enabled.
- - "disabled" will prevent kernel thermal driver action
- upon trip points so that user applications can take
- charge of thermal management.
- .set_mode:
- set the mode (enabled/disabled) of the thermal zone.
- .get_trip_type:
- get the type of certain trip point.
- .get_trip_temp:
- get the temperature above which the certain trip point
- will be fired.
- .set_emul_temp:
- set the emulation temperature which helps in debugging
- different threshold temperature points.
- tzp:
- thermal zone platform parameters.
- passive_delay:
- number of milliseconds to wait between polls when
- performing passive cooling.
- polling_delay:
- number of milliseconds to wait between polls when checking
- whether trip points have been crossed (0 for interrupt driven systems).
-
- ::
-
- void thermal_zone_device_unregister(struct thermal_zone_device *tz)
-
- This interface function removes the thermal zone device.
- It deletes the corresponding entry from /sys/class/thermal folder and
- unbinds all the thermal cooling devices it uses.
-
- ::
-
- struct thermal_zone_device
- *thermal_zone_of_sensor_register(struct device *dev, int sensor_id,
- void *data,
- const struct thermal_zone_of_device_ops *ops)
-
- This interface adds a new sensor to a DT thermal zone.
- This function will search the list of thermal zones described in
- device tree and look for the zone that refer to the sensor device
- pointed by dev->of_node as temperature providers. For the zone
- pointing to the sensor node, the sensor will be added to the DT
- thermal zone device.
-
- The parameters for this interface are:
-
- dev:
- Device node of sensor containing valid node pointer in
- dev->of_node.
- sensor_id:
- a sensor identifier, in case the sensor IP has more
- than one sensors
- data:
- a private pointer (owned by the caller) that will be
- passed back, when a temperature reading is needed.
- ops:
- `struct thermal_zone_of_device_ops *`.
-
- ============== =======================================
- get_temp a pointer to a function that reads the
- sensor temperature. This is mandatory
- callback provided by sensor driver.
- set_trips a pointer to a function that sets a
- temperature window. When this window is
- left the driver must inform the thermal
- core via thermal_zone_device_update.
- get_trend a pointer to a function that reads the
- sensor temperature trend.
- set_emul_temp a pointer to a function that sets
- sensor emulated temperature.
- ============== =======================================
-
- The thermal zone temperature is provided by the get_temp() function
- pointer of thermal_zone_of_device_ops. When called, it will
- have the private pointer @data back.
-
- It returns error pointer if fails otherwise valid thermal zone device
- handle. Caller should check the return handle with IS_ERR() for finding
- whether success or not.
-
- ::
-
- void thermal_zone_of_sensor_unregister(struct device *dev,
- struct thermal_zone_device *tzd)
-
- This interface unregisters a sensor from a DT thermal zone which was
- successfully added by interface thermal_zone_of_sensor_register().
- This function removes the sensor callbacks and private data from the
- thermal zone device registered with thermal_zone_of_sensor_register()
- interface. It will also silent the zone by remove the .get_temp() and
- get_trend() thermal zone device callbacks.
-
- ::
-
- struct thermal_zone_device
- *devm_thermal_zone_of_sensor_register(struct device *dev,
- int sensor_id,
- void *data,
- const struct thermal_zone_of_device_ops *ops)
-
- This interface is resource managed version of
- thermal_zone_of_sensor_register().
-
- All details of thermal_zone_of_sensor_register() described in
- section 1.1.3 is applicable here.
-
- The benefit of using this interface to register sensor is that it
- is not require to explicitly call thermal_zone_of_sensor_unregister()
- in error path or during driver unbinding as this is done by driver
- resource manager.
-
- ::
-
- void devm_thermal_zone_of_sensor_unregister(struct device *dev,
- struct thermal_zone_device *tzd)
-
- This interface is resource managed version of
- thermal_zone_of_sensor_unregister().
- All details of thermal_zone_of_sensor_unregister() described in
- section 1.1.4 is applicable here.
- Normally this function will not need to be called and the resource
- management code will ensure that the resource is freed.
-
- ::
-
- int thermal_zone_get_slope(struct thermal_zone_device *tz)
-
- This interface is used to read the slope attribute value
- for the thermal zone device, which might be useful for platform
- drivers for temperature calculations.
-
- ::
-
- int thermal_zone_get_offset(struct thermal_zone_device *tz)
-
- This interface is used to read the offset attribute value
- for the thermal zone device, which might be useful for platform
- drivers for temperature calculations.
-
-1.2 thermal cooling device interface
-------------------------------------
-
-
- ::
-
- struct thermal_cooling_device
- *thermal_cooling_device_register(char *name,
- void *devdata, struct thermal_cooling_device_ops *)
-
- This interface function adds a new thermal cooling device (fan/processor/...)
- to /sys/class/thermal/ folder as `cooling_device[0-*]`. It tries to bind itself
- to all the thermal zone devices registered at the same time.
-
- name:
- the cooling device name.
- devdata:
- device private data.
- ops:
- thermal cooling devices call-backs.
-
- .get_max_state:
- get the Maximum throttle state of the cooling device.
- .get_cur_state:
- get the Currently requested throttle state of the
- cooling device.
- .set_cur_state:
- set the Current throttle state of the cooling device.
-
- ::
-
- void thermal_cooling_device_unregister(struct thermal_cooling_device *cdev)
-
- This interface function removes the thermal cooling device.
- It deletes the corresponding entry from /sys/class/thermal folder and
- unbinds itself from all the thermal zone devices using it.
-
-1.3 interface for binding a thermal zone device with a thermal cooling device
------------------------------------------------------------------------------
-
- ::
-
- int thermal_zone_bind_cooling_device(struct thermal_zone_device *tz,
- int trip, struct thermal_cooling_device *cdev,
- unsigned long upper, unsigned long lower, unsigned int weight);
-
- This interface function binds a thermal cooling device to a particular trip
- point of a thermal zone device.
-
- This function is usually called in the thermal zone device .bind callback.
-
- tz:
- the thermal zone device
- cdev:
- thermal cooling device
- trip:
- indicates which trip point in this thermal zone the cooling device
- is associated with.
- upper:
- the Maximum cooling state for this trip point.
- THERMAL_NO_LIMIT means no upper limit,
- and the cooling device can be in max_state.
- lower:
- the Minimum cooling state can be used for this trip point.
- THERMAL_NO_LIMIT means no lower limit,
- and the cooling device can be in cooling state 0.
- weight:
- the influence of this cooling device in this thermal
- zone. See 1.4.1 below for more information.
-
- ::
-
- int thermal_zone_unbind_cooling_device(struct thermal_zone_device *tz,
- int trip, struct thermal_cooling_device *cdev);
-
- This interface function unbinds a thermal cooling device from a particular
- trip point of a thermal zone device. This function is usually called in
- the thermal zone device .unbind callback.
-
- tz:
- the thermal zone device
- cdev:
- thermal cooling device
- trip:
- indicates which trip point in this thermal zone the cooling device
- is associated with.
-
-1.4 Thermal Zone Parameters
----------------------------
-
- ::
-
- struct thermal_bind_params
-
- This structure defines the following parameters that are used to bind
- a zone with a cooling device for a particular trip point.
-
- .cdev:
- The cooling device pointer
- .weight:
- The 'influence' of a particular cooling device on this
- zone. This is relative to the rest of the cooling
- devices. For example, if all cooling devices have a
- weight of 1, then they all contribute the same. You can
- use percentages if you want, but it's not mandatory. A
- weight of 0 means that this cooling device doesn't
- contribute to the cooling of this zone unless all cooling
- devices have a weight of 0. If all weights are 0, then
- they all contribute the same.
- .trip_mask:
- This is a bit mask that gives the binding relation between
- this thermal zone and cdev, for a particular trip point.
- If nth bit is set, then the cdev and thermal zone are bound
- for trip point n.
- .binding_limits:
- This is an array of cooling state limits. Must have
- exactly 2 * thermal_zone.number_of_trip_points. It is an
- array consisting of tuples <lower-state upper-state> of
- state limits. Each trip will be associated with one state
- limit tuple when binding. A NULL pointer means
- <THERMAL_NO_LIMITS THERMAL_NO_LIMITS> on all trips.
- These limits are used when binding a cdev to a trip point.
- .match:
- This call back returns success(0) if the 'tz and cdev' need to
- be bound, as per platform data.
-
- ::
-
- struct thermal_zone_params
-
- This structure defines the platform level parameters for a thermal zone.
- This data, for each thermal zone should come from the platform layer.
- This is an optional feature where some platforms can choose not to
- provide this data.
-
- .governor_name:
- Name of the thermal governor used for this zone
- .no_hwmon:
- a boolean to indicate if the thermal to hwmon sysfs interface
- is required. when no_hwmon == false, a hwmon sysfs interface
- will be created. when no_hwmon == true, nothing will be done.
- In case the thermal_zone_params is NULL, the hwmon interface
- will be created (for backward compatibility).
- .num_tbps:
- Number of thermal_bind_params entries for this zone
- .tbp:
- thermal_bind_params entries
-
-2. sysfs attributes structure
-=============================
-
-== ================
-RO read only value
-WO write only value
-RW read/write value
-== ================
-
-Thermal sysfs attributes will be represented under /sys/class/thermal.
-Hwmon sysfs I/F extension is also available under /sys/class/hwmon
-if hwmon is compiled in or built as a module.
-
-Thermal zone device sys I/F, created once it's registered::
-
- /sys/class/thermal/thermal_zone[0-*]:
- |---type: Type of the thermal zone
- |---temp: Current temperature
- |---mode: Working mode of the thermal zone
- |---policy: Thermal governor used for this zone
- |---available_policies: Available thermal governors for this zone
- |---trip_point_[0-*]_temp: Trip point temperature
- |---trip_point_[0-*]_type: Trip point type
- |---trip_point_[0-*]_hyst: Hysteresis value for this trip point
- |---emul_temp: Emulated temperature set node
- |---sustainable_power: Sustainable dissipatable power
- |---k_po: Proportional term during temperature overshoot
- |---k_pu: Proportional term during temperature undershoot
- |---k_i: PID's integral term in the power allocator gov
- |---k_d: PID's derivative term in the power allocator
- |---integral_cutoff: Offset above which errors are accumulated
- |---slope: Slope constant applied as linear extrapolation
- |---offset: Offset constant applied as linear extrapolation
-
-Thermal cooling device sys I/F, created once it's registered::
-
- /sys/class/thermal/cooling_device[0-*]:
- |---type: Type of the cooling device(processor/fan/...)
- |---max_state: Maximum cooling state of the cooling device
- |---cur_state: Current cooling state of the cooling device
- |---stats: Directory containing cooling device's statistics
- |---stats/reset: Writing any value resets the statistics
- |---stats/time_in_state_ms: Time (msec) spent in various cooling states
- |---stats/total_trans: Total number of times cooling state is changed
- |---stats/trans_table: Cooing state transition table
-
-
-Then next two dynamic attributes are created/removed in pairs. They represent
-the relationship between a thermal zone and its associated cooling device.
-They are created/removed for each successful execution of
-thermal_zone_bind_cooling_device/thermal_zone_unbind_cooling_device.
-
-::
-
- /sys/class/thermal/thermal_zone[0-*]:
- |---cdev[0-*]: [0-*]th cooling device in current thermal zone
- |---cdev[0-*]_trip_point: Trip point that cdev[0-*] is associated with
- |---cdev[0-*]_weight: Influence of the cooling device in
- this thermal zone
-
-Besides the thermal zone device sysfs I/F and cooling device sysfs I/F,
-the generic thermal driver also creates a hwmon sysfs I/F for each _type_
-of thermal zone device. E.g. the generic thermal driver registers one hwmon
-class device and build the associated hwmon sysfs I/F for all the registered
-ACPI thermal zones.
-
-::
-
- /sys/class/hwmon/hwmon[0-*]:
- |---name: The type of the thermal zone devices
- |---temp[1-*]_input: The current temperature of thermal zone [1-*]
- |---temp[1-*]_critical: The critical trip point of thermal zone [1-*]
-
-Please read Documentation/hwmon/sysfs-interface.rst for additional information.
-
-Thermal zone attributes
------------------------
-
-type
- Strings which represent the thermal zone type.
- This is given by thermal zone driver as part of registration.
- E.g: "acpitz" indicates it's an ACPI thermal device.
- In order to keep it consistent with hwmon sys attribute; this should
- be a short, lowercase string, not containing spaces nor dashes.
- RO, Required
-
-temp
- Current temperature as reported by thermal zone (sensor).
- Unit: millidegree Celsius
- RO, Required
-
-mode
- One of the predefined values in [enabled, disabled].
- This file gives information about the algorithm that is currently
- managing the thermal zone. It can be either default kernel based
- algorithm or user space application.
-
- enabled
- enable Kernel Thermal management.
- disabled
- Preventing kernel thermal zone driver actions upon
- trip points so that user application can take full
- charge of the thermal management.
-
- RW, Optional
-
-policy
- One of the various thermal governors used for a particular zone.
-
- RW, Required
-
-available_policies
- Available thermal governors which can be used for a particular zone.
-
- RO, Required
-
-`trip_point_[0-*]_temp`
- The temperature above which trip point will be fired.
-
- Unit: millidegree Celsius
-
- RO, Optional
-
-`trip_point_[0-*]_type`
- Strings which indicate the type of the trip point.
-
- E.g. it can be one of critical, hot, passive, `active[0-*]` for ACPI
- thermal zone.
-
- RO, Optional
-
-`trip_point_[0-*]_hyst`
- The hysteresis value for a trip point, represented as an integer
- Unit: Celsius
- RW, Optional
-
-`cdev[0-*]`
- Sysfs link to the thermal cooling device node where the sys I/F
- for cooling device throttling control represents.
-
- RO, Optional
-
-`cdev[0-*]_trip_point`
- The trip point in this thermal zone which `cdev[0-*]` is associated
- with; -1 means the cooling device is not associated with any trip
- point.
-
- RO, Optional
-
-`cdev[0-*]_weight`
- The influence of `cdev[0-*]` in this thermal zone. This value
- is relative to the rest of cooling devices in the thermal
- zone. For example, if a cooling device has a weight double
- than that of other, it's twice as effective in cooling the
- thermal zone.
-
- RW, Optional
-
-passive
- Attribute is only present for zones in which the passive cooling
- policy is not supported by native thermal driver. Default is zero
- and can be set to a temperature (in millidegrees) to enable a
- passive trip point for the zone. Activation is done by polling with
- an interval of 1 second.
-
- Unit: millidegrees Celsius
-
- Valid values: 0 (disabled) or greater than 1000
-
- RW, Optional
-
-emul_temp
- Interface to set the emulated temperature method in thermal zone
- (sensor). After setting this temperature, the thermal zone may pass
- this temperature to platform emulation function if registered or
- cache it locally. This is useful in debugging different temperature
- threshold and its associated cooling action. This is write only node
- and writing 0 on this node should disable emulation.
- Unit: millidegree Celsius
-
- WO, Optional
-
- WARNING:
- Be careful while enabling this option on production systems,
- because userland can easily disable the thermal policy by simply
- flooding this sysfs node with low temperature values.
-
-sustainable_power
- An estimate of the sustained power that can be dissipated by
- the thermal zone. Used by the power allocator governor. For
- more information see Documentation/thermal/power_allocator.rst
-
- Unit: milliwatts
-
- RW, Optional
-
-k_po
- The proportional term of the power allocator governor's PID
- controller during temperature overshoot. Temperature overshoot
- is when the current temperature is above the "desired
- temperature" trip point. For more information see
- Documentation/thermal/power_allocator.rst
-
- RW, Optional
-
-k_pu
- The proportional term of the power allocator governor's PID
- controller during temperature undershoot. Temperature undershoot
- is when the current temperature is below the "desired
- temperature" trip point. For more information see
- Documentation/thermal/power_allocator.rst
-
- RW, Optional
-
-k_i
- The integral term of the power allocator governor's PID
- controller. This term allows the PID controller to compensate
- for long term drift. For more information see
- Documentation/thermal/power_allocator.rst
-
- RW, Optional
-
-k_d
- The derivative term of the power allocator governor's PID
- controller. For more information see
- Documentation/thermal/power_allocator.rst
-
- RW, Optional
-
-integral_cutoff
- Temperature offset from the desired temperature trip point
- above which the integral term of the power allocator
- governor's PID controller starts accumulating errors. For
- example, if integral_cutoff is 0, then the integral term only
- accumulates error when temperature is above the desired
- temperature trip point. For more information see
- Documentation/thermal/power_allocator.rst
-
- Unit: millidegree Celsius
-
- RW, Optional
-
-slope
- The slope constant used in a linear extrapolation model
- to determine a hotspot temperature based off the sensor's
- raw readings. It is up to the device driver to determine
- the usage of these values.
-
- RW, Optional
-
-offset
- The offset constant used in a linear extrapolation model
- to determine a hotspot temperature based off the sensor's
- raw readings. It is up to the device driver to determine
- the usage of these values.
-
- RW, Optional
-
-Cooling device attributes
--------------------------
-
-type
- String which represents the type of device, e.g:
-
- - for generic ACPI: should be "Fan", "Processor" or "LCD"
- - for memory controller device on intel_menlow platform:
- should be "Memory controller".
-
- RO, Required
-
-max_state
- The maximum permissible cooling state of this cooling device.
-
- RO, Required
-
-cur_state
- The current cooling state of this cooling device.
- The value can any integer numbers between 0 and max_state:
-
- - cur_state == 0 means no cooling
- - cur_state == max_state means the maximum cooling.
-
- RW, Required
-
-stats/reset
- Writing any value resets the cooling device's statistics.
- WO, Required
-
-stats/time_in_state_ms:
- The amount of time spent by the cooling device in various cooling
- states. The output will have "<state> <time>" pair in each line, which
- will mean this cooling device spent <time> msec of time at <state>.
- Output will have one line for each of the supported states. usertime
- units here is 10mS (similar to other time exported in /proc).
- RO, Required
-
-
-stats/total_trans:
- A single positive value showing the total number of times the state of a
- cooling device is changed.
-
- RO, Required
-
-stats/trans_table:
- This gives fine grained information about all the cooling state
- transitions. The cat output here is a two dimensional matrix, where an
- entry <i,j> (row i, column j) represents the number of transitions from
- State_i to State_j. If the transition table is bigger than PAGE_SIZE,
- reading this will return an -EFBIG error.
- RO, Required
-
-3. A simple implementation
-==========================
-
-ACPI thermal zone may support multiple trip points like critical, hot,
-passive, active. If an ACPI thermal zone supports critical, passive,
-active[0] and active[1] at the same time, it may register itself as a
-thermal_zone_device (thermal_zone1) with 4 trip points in all.
-It has one processor and one fan, which are both registered as
-thermal_cooling_device. Both are considered to have the same
-effectiveness in cooling the thermal zone.
-
-If the processor is listed in _PSL method, and the fan is listed in _AL0
-method, the sys I/F structure will be built like this::
-
- /sys/class/thermal:
- |thermal_zone1:
- |---type: acpitz
- |---temp: 37000
- |---mode: enabled
- |---policy: step_wise
- |---available_policies: step_wise fair_share
- |---trip_point_0_temp: 100000
- |---trip_point_0_type: critical
- |---trip_point_1_temp: 80000
- |---trip_point_1_type: passive
- |---trip_point_2_temp: 70000
- |---trip_point_2_type: active0
- |---trip_point_3_temp: 60000
- |---trip_point_3_type: active1
- |---cdev0: --->/sys/class/thermal/cooling_device0
- |---cdev0_trip_point: 1 /* cdev0 can be used for passive */
- |---cdev0_weight: 1024
- |---cdev1: --->/sys/class/thermal/cooling_device3
- |---cdev1_trip_point: 2 /* cdev1 can be used for active[0]*/
- |---cdev1_weight: 1024
-
- |cooling_device0:
- |---type: Processor
- |---max_state: 8
- |---cur_state: 0
-
- |cooling_device3:
- |---type: Fan
- |---max_state: 2
- |---cur_state: 0
-
- /sys/class/hwmon:
- |hwmon0:
- |---name: acpitz
- |---temp1_input: 37000
- |---temp1_crit: 100000
-
-4. Event Notification
-=====================
-
-The framework includes a simple notification mechanism, in the form of a
-netlink event. Netlink socket initialization is done during the _init_
-of the framework. Drivers which intend to use the notification mechanism
-just need to call thermal_generate_netlink_event() with two arguments viz
-(originator, event). The originator is a pointer to struct thermal_zone_device
-from where the event has been originated. An integer which represents the
-thermal zone device will be used in the message to identify the zone. The
-event will be one of:{THERMAL_AUX0, THERMAL_AUX1, THERMAL_CRITICAL,
-THERMAL_DEV_FAULT}. Notification can be sent when the current temperature
-crosses any of the configured thresholds.
-
-5. Export Symbol APIs
-=====================
-
-5.1. get_tz_trend
------------------
-
-This function returns the trend of a thermal zone, i.e the rate of change
-of temperature of the thermal zone. Ideally, the thermal sensor drivers
-are supposed to implement the callback. If they don't, the thermal
-framework calculated the trend by comparing the previous and the current
-temperature values.
-
-5.2. get_thermal_instance
--------------------------
-
-This function returns the thermal_instance corresponding to a given
-{thermal_zone, cooling_device, trip_point} combination. Returns NULL
-if such an instance does not exist.
-
-5.3. thermal_notify_framework
------------------------------
-
-This function handles the trip events from sensor drivers. It starts
-throttling the cooling devices according to the policy configured.
-For CRITICAL and HOT trip points, this notifies the respective drivers,
-and does actual throttling for other trip points i.e ACTIVE and PASSIVE.
-The throttling policy is based on the configured platform data; if no
-platform data is provided, this uses the step_wise throttling policy.
-
-5.4. thermal_cdev_update
-------------------------
-
-This function serves as an arbitrator to set the state of a cooling
-device. It sets the cooling device to the deepest cooling state if
-possible.
-
-6. thermal_emergency_poweroff
-=============================
-
-On an event of critical trip temperature crossing. Thermal framework
-allows the system to shutdown gracefully by calling orderly_poweroff().
-In the event of a failure of orderly_poweroff() to shut down the system
-we are in danger of keeping the system alive at undesirably high
-temperatures. To mitigate this high risk scenario we program a work
-queue to fire after a pre-determined number of seconds to start
-an emergency shutdown of the device using the kernel_power_off()
-function. In case kernel_power_off() fails then finally
-emergency_restart() is called in the worst case.
-
-The delay should be carefully profiled so as to give adequate time for
-orderly_poweroff(). In case of failure of an orderly_poweroff() the
-emergency poweroff kicks in after the delay has elapsed and shuts down
-the system.
-
-If set to 0 emergency poweroff will not be supported. So a carefully
-profiled non-zero positive value is a must for emergerncy poweroff to be
-triggered.
diff --git a/Documentation/thermal/x86_pkg_temperature_thermal.rst b/Documentation/thermal/x86_pkg_temperature_thermal.rst
deleted file mode 100644
index f134dbd..0000000
--- a/Documentation/thermal/x86_pkg_temperature_thermal.rst
+++ /dev/null
@@ -1,55 +0,0 @@
-===================================
-Kernel driver: x86_pkg_temp_thermal
-===================================
-
-Supported chips:
-
-* x86: with package level thermal management
-
-(Verify using: CPUID.06H:EAX[bit 6] =1)
-
-Authors: Srinivas Pandruvada <srinivas.pandruvada@linux.intel.com>
-
-Reference
----------
-
-Intel® 64 and IA-32 Architectures Software Developer’s Manual (Jan, 2013):
-Chapter 14.6: PACKAGE LEVEL THERMAL MANAGEMENT
-
-Description
------------
-
-This driver register CPU digital temperature package level sensor as a thermal
-zone with maximum two user mode configurable trip points. Number of trip points
-depends on the capability of the package. Once the trip point is violated,
-user mode can receive notification via thermal notification mechanism and can
-take any action to control temperature.
-
-
-Threshold management
---------------------
-Each package will register as a thermal zone under /sys/class/thermal.
-
-Example::
-
- /sys/class/thermal/thermal_zone1
-
-This contains two trip points:
-
-- trip_point_0_temp
-- trip_point_1_temp
-
-User can set any temperature between 0 to TJ-Max temperature. Temperature units
-are in milli-degree Celsius. Refer to "Documentation/thermal/sysfs-api.rst" for
-thermal sys-fs details.
-
-Any value other than 0 in these trip points, can trigger thermal notifications.
-Setting 0, stops sending thermal notifications.
-
-Thermal notifications:
-To get kobject-uevent notifications, set the thermal zone
-policy to "user_space".
-
-For example::
-
- echo -n "user_space" > policy
diff --git a/Documentation/trace/coresight-cpu-debug.rst b/Documentation/trace/coresight-cpu-debug.rst
new file mode 100644
index 0000000..993dd29
--- /dev/null
+++ b/Documentation/trace/coresight-cpu-debug.rst
@@ -0,0 +1,192 @@
+==========================
+Coresight CPU Debug Module
+==========================
+
+ :Author: Leo Yan <leo.yan@linaro.org>
+ :Date: April 5th, 2017
+
+Introduction
+------------
+
+Coresight CPU debug module is defined in ARMv8-a architecture reference manual
+(ARM DDI 0487A.k) Chapter 'Part H: External debug', the CPU can integrate
+debug module and it is mainly used for two modes: self-hosted debug and
+external debug. Usually the external debug mode is well known as the external
+debugger connects with SoC from JTAG port; on the other hand the program can
+explore debugging method which rely on self-hosted debug mode, this document
+is to focus on this part.
+
+The debug module provides sample-based profiling extension, which can be used
+to sample CPU program counter, secure state and exception level, etc; usually
+every CPU has one dedicated debug module to be connected. Based on self-hosted
+debug mechanism, Linux kernel can access these related registers from mmio
+region when the kernel panic happens. The callback notifier for kernel panic
+will dump related registers for every CPU; finally this is good for assistant
+analysis for panic.
+
+
+Implementation
+--------------
+
+- During driver registration, it uses EDDEVID and EDDEVID1 - two device ID
+ registers to decide if sample-based profiling is implemented or not. On some
+ platforms this hardware feature is fully or partially implemented; and if
+ this feature is not supported then registration will fail.
+
+- At the time this documentation was written, the debug driver mainly relies on
+ information gathered by the kernel panic callback notifier from three
+ sampling registers: EDPCSR, EDVIDSR and EDCIDSR: from EDPCSR we can get
+ program counter; EDVIDSR has information for secure state, exception level,
+ bit width, etc; EDCIDSR is context ID value which contains the sampled value
+ of CONTEXTIDR_EL1.
+
+- The driver supports a CPU running in either AArch64 or AArch32 mode. The
+ registers naming convention is a bit different between them, AArch64 uses
+ 'ED' for register prefix (ARM DDI 0487A.k, chapter H9.1) and AArch32 uses
+ 'DBG' as prefix (ARM DDI 0487A.k, chapter G5.1). The driver is unified to
+ use AArch64 naming convention.
+
+- ARMv8-a (ARM DDI 0487A.k) and ARMv7-a (ARM DDI 0406C.b) have different
+ register bits definition. So the driver consolidates two difference:
+
+ If PCSROffset=0b0000, on ARMv8-a the feature of EDPCSR is not implemented;
+ but ARMv7-a defines "PCSR samples are offset by a value that depends on the
+ instruction set state". For ARMv7-a, the driver checks furthermore if CPU
+ runs with ARM or thumb instruction set and calibrate PCSR value, the
+ detailed description for offset is in ARMv7-a ARM (ARM DDI 0406C.b) chapter
+ C11.11.34 "DBGPCSR, Program Counter Sampling Register".
+
+ If PCSROffset=0b0010, ARMv8-a defines "EDPCSR implemented, and samples have
+ no offset applied and do not sample the instruction set state in AArch32
+ state". So on ARMv8 if EDDEVID1.PCSROffset is 0b0010 and the CPU operates
+ in AArch32 state, EDPCSR is not sampled; when the CPU operates in AArch64
+ state EDPCSR is sampled and no offset are applied.
+
+
+Clock and power domain
+----------------------
+
+Before accessing debug registers, we should ensure the clock and power domain
+have been enabled properly. In ARMv8-a ARM (ARM DDI 0487A.k) chapter 'H9.1
+Debug registers', the debug registers are spread into two domains: the debug
+domain and the CPU domain.
+::
+
+ +---------------+
+ | |
+ | |
+ +----------+--+ |
+ dbg_clock -->| |**| |<-- cpu_clock
+ | Debug |**| CPU |
+ dbg_power_domain -->| |**| |<-- cpu_power_domain
+ +----------+--+ |
+ | |
+ | |
+ +---------------+
+
+For debug domain, the user uses DT binding "clocks" and "power-domains" to
+specify the corresponding clock source and power supply for the debug logic.
+The driver calls the pm_runtime_{put|get} operations as needed to handle the
+debug power domain.
+
+For CPU domain, the different SoC designs have different power management
+schemes and finally this heavily impacts external debug module. So we can
+divide into below cases:
+
+- On systems with a sane power controller which can behave correctly with
+ respect to CPU power domain, the CPU power domain can be controlled by
+ register EDPRCR in driver. The driver firstly writes bit EDPRCR.COREPURQ
+ to power up the CPU, and then writes bit EDPRCR.CORENPDRQ for emulation
+ of CPU power down. As result, this can ensure the CPU power domain is
+ powered on properly during the period when access debug related registers;
+
+- Some designs will power down an entire cluster if all CPUs on the cluster
+ are powered down - including the parts of the debug registers that should
+ remain powered in the debug power domain. The bits in EDPRCR are not
+ respected in these cases, so these designs do not support debug over
+ power down in the way that the CoreSight / Debug designers anticipated.
+ This means that even checking EDPRSR has the potential to cause a bus hang
+ if the target register is unpowered.
+
+ In this case, accessing to the debug registers while they are not powered
+ is a recipe for disaster; so we need preventing CPU low power states at boot
+ time or when user enable module at the run time. Please see chapter
+ "How to use the module" for detailed usage info for this.
+
+
+Device Tree Bindings
+--------------------
+
+See Documentation/devicetree/bindings/arm/coresight-cpu-debug.txt for details.
+
+
+How to use the module
+---------------------
+
+If you want to enable debugging functionality at boot time, you can add
+"coresight_cpu_debug.enable=1" to the kernel command line parameter.
+
+The driver also can work as module, so can enable the debugging when insmod
+module::
+
+ # insmod coresight_cpu_debug.ko debug=1
+
+When boot time or insmod module you have not enabled the debugging, the driver
+uses the debugfs file system to provide a knob to dynamically enable or disable
+debugging:
+
+To enable it, write a '1' into /sys/kernel/debug/coresight_cpu_debug/enable::
+
+ # echo 1 > /sys/kernel/debug/coresight_cpu_debug/enable
+
+To disable it, write a '0' into /sys/kernel/debug/coresight_cpu_debug/enable::
+
+ # echo 0 > /sys/kernel/debug/coresight_cpu_debug/enable
+
+As explained in chapter "Clock and power domain", if you are working on one
+platform which has idle states to power off debug logic and the power
+controller cannot work well for the request from EDPRCR, then you should
+firstly constraint CPU idle states before enable CPU debugging feature; so can
+ensure the accessing to debug logic.
+
+If you want to limit idle states at boot time, you can use "nohlt" or
+"cpuidle.off=1" in the kernel command line.
+
+At the runtime you can disable idle states with below methods:
+
+It is possible to disable CPU idle states by way of the PM QoS
+subsystem, more specifically by using the "/dev/cpu_dma_latency"
+interface (see Documentation/power/pm_qos_interface.rst for more
+details). As specified in the PM QoS documentation the requested
+parameter will stay in effect until the file descriptor is released.
+For example::
+
+ # exec 3<> /dev/cpu_dma_latency; echo 0 >&3
+ ...
+ Do some work...
+ ...
+ # exec 3<>-
+
+The same can also be done from an application program.
+
+Disable specific CPU's specific idle state from cpuidle sysfs (see
+Documentation/admin-guide/pm/cpuidle.rst)::
+
+ # echo 1 > /sys/devices/system/cpu/cpu$cpu/cpuidle/state$state/disable
+
+Output format
+-------------
+
+Here is an example of the debugging output format::
+
+ ARM external debug module:
+ coresight-cpu-debug 850000.debug: CPU[0]:
+ coresight-cpu-debug 850000.debug: EDPRSR: 00000001 (Power:On DLK:Unlock)
+ coresight-cpu-debug 850000.debug: EDPCSR: handle_IPI+0x174/0x1d8
+ coresight-cpu-debug 850000.debug: EDCIDSR: 00000000
+ coresight-cpu-debug 850000.debug: EDVIDSR: 90000000 (State:Non-secure Mode:EL1/0 Width:64bits VMID:0)
+ coresight-cpu-debug 852000.debug: CPU[1]:
+ coresight-cpu-debug 852000.debug: EDPRSR: 00000001 (Power:On DLK:Unlock)
+ coresight-cpu-debug 852000.debug: EDPCSR: debug_notifier_call+0x23c/0x358
+ coresight-cpu-debug 852000.debug: EDCIDSR: 00000000
+ coresight-cpu-debug 852000.debug: EDVIDSR: 90000000 (State:Non-secure Mode:EL1/0 Width:64bits VMID:0)
diff --git a/Documentation/trace/coresight-cpu-debug.txt b/Documentation/trace/coresight-cpu-debug.txt
deleted file mode 100644
index 1a660a3..0000000
--- a/Documentation/trace/coresight-cpu-debug.txt
+++ /dev/null
@@ -1,187 +0,0 @@
- Coresight CPU Debug Module
- ==========================
-
- Author: Leo Yan <leo.yan@linaro.org>
- Date: April 5th, 2017
-
-Introduction
-------------
-
-Coresight CPU debug module is defined in ARMv8-a architecture reference manual
-(ARM DDI 0487A.k) Chapter 'Part H: External debug', the CPU can integrate
-debug module and it is mainly used for two modes: self-hosted debug and
-external debug. Usually the external debug mode is well known as the external
-debugger connects with SoC from JTAG port; on the other hand the program can
-explore debugging method which rely on self-hosted debug mode, this document
-is to focus on this part.
-
-The debug module provides sample-based profiling extension, which can be used
-to sample CPU program counter, secure state and exception level, etc; usually
-every CPU has one dedicated debug module to be connected. Based on self-hosted
-debug mechanism, Linux kernel can access these related registers from mmio
-region when the kernel panic happens. The callback notifier for kernel panic
-will dump related registers for every CPU; finally this is good for assistant
-analysis for panic.
-
-
-Implementation
---------------
-
-- During driver registration, it uses EDDEVID and EDDEVID1 - two device ID
- registers to decide if sample-based profiling is implemented or not. On some
- platforms this hardware feature is fully or partially implemented; and if
- this feature is not supported then registration will fail.
-
-- At the time this documentation was written, the debug driver mainly relies on
- information gathered by the kernel panic callback notifier from three
- sampling registers: EDPCSR, EDVIDSR and EDCIDSR: from EDPCSR we can get
- program counter; EDVIDSR has information for secure state, exception level,
- bit width, etc; EDCIDSR is context ID value which contains the sampled value
- of CONTEXTIDR_EL1.
-
-- The driver supports a CPU running in either AArch64 or AArch32 mode. The
- registers naming convention is a bit different between them, AArch64 uses
- 'ED' for register prefix (ARM DDI 0487A.k, chapter H9.1) and AArch32 uses
- 'DBG' as prefix (ARM DDI 0487A.k, chapter G5.1). The driver is unified to
- use AArch64 naming convention.
-
-- ARMv8-a (ARM DDI 0487A.k) and ARMv7-a (ARM DDI 0406C.b) have different
- register bits definition. So the driver consolidates two difference:
-
- If PCSROffset=0b0000, on ARMv8-a the feature of EDPCSR is not implemented;
- but ARMv7-a defines "PCSR samples are offset by a value that depends on the
- instruction set state". For ARMv7-a, the driver checks furthermore if CPU
- runs with ARM or thumb instruction set and calibrate PCSR value, the
- detailed description for offset is in ARMv7-a ARM (ARM DDI 0406C.b) chapter
- C11.11.34 "DBGPCSR, Program Counter Sampling Register".
-
- If PCSROffset=0b0010, ARMv8-a defines "EDPCSR implemented, and samples have
- no offset applied and do not sample the instruction set state in AArch32
- state". So on ARMv8 if EDDEVID1.PCSROffset is 0b0010 and the CPU operates
- in AArch32 state, EDPCSR is not sampled; when the CPU operates in AArch64
- state EDPCSR is sampled and no offset are applied.
-
-
-Clock and power domain
-----------------------
-
-Before accessing debug registers, we should ensure the clock and power domain
-have been enabled properly. In ARMv8-a ARM (ARM DDI 0487A.k) chapter 'H9.1
-Debug registers', the debug registers are spread into two domains: the debug
-domain and the CPU domain.
-
- +---------------+
- | |
- | |
- +----------+--+ |
- dbg_clock -->| |**| |<-- cpu_clock
- | Debug |**| CPU |
- dbg_power_domain -->| |**| |<-- cpu_power_domain
- +----------+--+ |
- | |
- | |
- +---------------+
-
-For debug domain, the user uses DT binding "clocks" and "power-domains" to
-specify the corresponding clock source and power supply for the debug logic.
-The driver calls the pm_runtime_{put|get} operations as needed to handle the
-debug power domain.
-
-For CPU domain, the different SoC designs have different power management
-schemes and finally this heavily impacts external debug module. So we can
-divide into below cases:
-
-- On systems with a sane power controller which can behave correctly with
- respect to CPU power domain, the CPU power domain can be controlled by
- register EDPRCR in driver. The driver firstly writes bit EDPRCR.COREPURQ
- to power up the CPU, and then writes bit EDPRCR.CORENPDRQ for emulation
- of CPU power down. As result, this can ensure the CPU power domain is
- powered on properly during the period when access debug related registers;
-
-- Some designs will power down an entire cluster if all CPUs on the cluster
- are powered down - including the parts of the debug registers that should
- remain powered in the debug power domain. The bits in EDPRCR are not
- respected in these cases, so these designs do not support debug over
- power down in the way that the CoreSight / Debug designers anticipated.
- This means that even checking EDPRSR has the potential to cause a bus hang
- if the target register is unpowered.
-
- In this case, accessing to the debug registers while they are not powered
- is a recipe for disaster; so we need preventing CPU low power states at boot
- time or when user enable module at the run time. Please see chapter
- "How to use the module" for detailed usage info for this.
-
-
-Device Tree Bindings
---------------------
-
-See Documentation/devicetree/bindings/arm/coresight-cpu-debug.txt for details.
-
-
-How to use the module
----------------------
-
-If you want to enable debugging functionality at boot time, you can add
-"coresight_cpu_debug.enable=1" to the kernel command line parameter.
-
-The driver also can work as module, so can enable the debugging when insmod
-module:
-# insmod coresight_cpu_debug.ko debug=1
-
-When boot time or insmod module you have not enabled the debugging, the driver
-uses the debugfs file system to provide a knob to dynamically enable or disable
-debugging:
-
-To enable it, write a '1' into /sys/kernel/debug/coresight_cpu_debug/enable:
-# echo 1 > /sys/kernel/debug/coresight_cpu_debug/enable
-
-To disable it, write a '0' into /sys/kernel/debug/coresight_cpu_debug/enable:
-# echo 0 > /sys/kernel/debug/coresight_cpu_debug/enable
-
-As explained in chapter "Clock and power domain", if you are working on one
-platform which has idle states to power off debug logic and the power
-controller cannot work well for the request from EDPRCR, then you should
-firstly constraint CPU idle states before enable CPU debugging feature; so can
-ensure the accessing to debug logic.
-
-If you want to limit idle states at boot time, you can use "nohlt" or
-"cpuidle.off=1" in the kernel command line.
-
-At the runtime you can disable idle states with below methods:
-
-It is possible to disable CPU idle states by way of the PM QoS
-subsystem, more specifically by using the "/dev/cpu_dma_latency"
-interface (see Documentation/power/pm_qos_interface.rst for more
-details). As specified in the PM QoS documentation the requested
-parameter will stay in effect until the file descriptor is released.
-For example:
-
-# exec 3<> /dev/cpu_dma_latency; echo 0 >&3
-...
-Do some work...
-...
-# exec 3<>-
-
-The same can also be done from an application program.
-
-Disable specific CPU's specific idle state from cpuidle sysfs (see
-Documentation/admin-guide/pm/cpuidle.rst):
-# echo 1 > /sys/devices/system/cpu/cpu$cpu/cpuidle/state$state/disable
-
-
-Output format
--------------
-
-Here is an example of the debugging output format:
-
-ARM external debug module:
-coresight-cpu-debug 850000.debug: CPU[0]:
-coresight-cpu-debug 850000.debug: EDPRSR: 00000001 (Power:On DLK:Unlock)
-coresight-cpu-debug 850000.debug: EDPCSR: handle_IPI+0x174/0x1d8
-coresight-cpu-debug 850000.debug: EDCIDSR: 00000000
-coresight-cpu-debug 850000.debug: EDVIDSR: 90000000 (State:Non-secure Mode:EL1/0 Width:64bits VMID:0)
-coresight-cpu-debug 852000.debug: CPU[1]:
-coresight-cpu-debug 852000.debug: EDPRSR: 00000001 (Power:On DLK:Unlock)
-coresight-cpu-debug 852000.debug: EDPCSR: debug_notifier_call+0x23c/0x358
-coresight-cpu-debug 852000.debug: EDCIDSR: 00000000
-coresight-cpu-debug 852000.debug: EDVIDSR: 90000000 (State:Non-secure Mode:EL1/0 Width:64bits VMID:0)
diff --git a/Documentation/trace/coresight.rst b/Documentation/trace/coresight.rst
new file mode 100644
index 0000000..72f4b7e
--- /dev/null
+++ b/Documentation/trace/coresight.rst
@@ -0,0 +1,498 @@
+======================================
+Coresight - HW Assisted Tracing on ARM
+======================================
+
+ :Author: Mathieu Poirier <mathieu.poirier@linaro.org>
+ :Date: September 11th, 2014
+
+Introduction
+------------
+
+Coresight is an umbrella of technologies allowing for the debugging of ARM
+based SoC. It includes solutions for JTAG and HW assisted tracing. This
+document is concerned with the latter.
+
+HW assisted tracing is becoming increasingly useful when dealing with systems
+that have many SoCs and other components like GPU and DMA engines. ARM has
+developed a HW assisted tracing solution by means of different components, each
+being added to a design at synthesis time to cater to specific tracing needs.
+Components are generally categorised as source, link and sinks and are
+(usually) discovered using the AMBA bus.
+
+"Sources" generate a compressed stream representing the processor instruction
+path based on tracing scenarios as configured by users. From there the stream
+flows through the coresight system (via ATB bus) using links that are connecting
+the emanating source to a sink(s). Sinks serve as endpoints to the coresight
+implementation, either storing the compressed stream in a memory buffer or
+creating an interface to the outside world where data can be transferred to a
+host without fear of filling up the onboard coresight memory buffer.
+
+At typical coresight system would look like this::
+
+ *****************************************************************
+ **************************** AMBA AXI ****************************===||
+ ***************************************************************** ||
+ ^ ^ | ||
+ | | * **
+ 0000000 ::::: 0000000 ::::: ::::: @@@@@@@ ||||||||||||
+ 0 CPU 0<-->: C : 0 CPU 0<-->: C : : C : @ STM @ || System ||
+ |->0000000 : T : |->0000000 : T : : T :<--->@@@@@ || Memory ||
+ | #######<-->: I : | #######<-->: I : : I : @@@<-| ||||||||||||
+ | # ETM # ::::: | # PTM # ::::: ::::: @ |
+ | ##### ^ ^ | ##### ^ ! ^ ! . | |||||||||
+ | |->### | ! | |->### | ! | ! . | || DAP ||
+ | | # | ! | | # | ! | ! . | |||||||||
+ | | . | ! | | . | ! | ! . | | |
+ | | . | ! | | . | ! | ! . | | *
+ | | . | ! | | . | ! | ! . | | SWD/
+ | | . | ! | | . | ! | ! . | | JTAG
+ *****************************************************************<-|
+ *************************** AMBA Debug APB ************************
+ *****************************************************************
+ | . ! . ! ! . |
+ | . * . * * . |
+ *****************************************************************
+ ******************** Cross Trigger Matrix (CTM) *******************
+ *****************************************************************
+ | . ^ . . |
+ | * ! * * |
+ *****************************************************************
+ ****************** AMBA Advanced Trace Bus (ATB) ******************
+ *****************************************************************
+ | ! =============== |
+ | * ===== F =====<---------|
+ | ::::::::: ==== U ====
+ |-->:: CTI ::<!! === N ===
+ | ::::::::: ! == N ==
+ | ^ * == E ==
+ | ! &&&&&&&&& IIIIIII == L ==
+ |------>&& ETB &&<......II I =======
+ | ! &&&&&&&&& II I .
+ | ! I I .
+ | ! I REP I<..........
+ | ! I I
+ | !!>&&&&&&&&& II I *Source: ARM ltd.
+ |------>& TPIU &<......II I DAP = Debug Access Port
+ &&&&&&&&& IIIIIII ETM = Embedded Trace Macrocell
+ ; PTM = Program Trace Macrocell
+ ; CTI = Cross Trigger Interface
+ * ETB = Embedded Trace Buffer
+ To trace port TPIU= Trace Port Interface Unit
+ SWD = Serial Wire Debug
+
+While on target configuration of the components is done via the APB bus,
+all trace data are carried out-of-band on the ATB bus. The CTM provides
+a way to aggregate and distribute signals between CoreSight components.
+
+The coresight framework provides a central point to represent, configure and
+manage coresight devices on a platform. This first implementation centers on
+the basic tracing functionality, enabling components such ETM/PTM, funnel,
+replicator, TMC, TPIU and ETB. Future work will enable more
+intricate IP blocks such as STM and CTI.
+
+
+Acronyms and Classification
+---------------------------
+
+Acronyms:
+
+PTM:
+ Program Trace Macrocell
+ETM:
+ Embedded Trace Macrocell
+STM:
+ System trace Macrocell
+ETB:
+ Embedded Trace Buffer
+ITM:
+ Instrumentation Trace Macrocell
+TPIU:
+ Trace Port Interface Unit
+TMC-ETR:
+ Trace Memory Controller, configured as Embedded Trace Router
+TMC-ETF:
+ Trace Memory Controller, configured as Embedded Trace FIFO
+CTI:
+ Cross Trigger Interface
+
+Classification:
+
+Source:
+ ETMv3.x ETMv4, PTMv1.0, PTMv1.1, STM, STM500, ITM
+Link:
+ Funnel, replicator (intelligent or not), TMC-ETR
+Sinks:
+ ETBv1.0, ETB1.1, TPIU, TMC-ETF
+Misc:
+ CTI
+
+
+Device Tree Bindings
+--------------------
+
+See Documentation/devicetree/bindings/arm/coresight.txt for details.
+
+As of this writing drivers for ITM, STMs and CTIs are not provided but are
+expected to be added as the solution matures.
+
+
+Framework and implementation
+----------------------------
+
+The coresight framework provides a central point to represent, configure and
+manage coresight devices on a platform. Any coresight compliant device can
+register with the framework for as long as they use the right APIs:
+
+.. c:function:: struct coresight_device *coresight_register(struct coresight_desc *desc);
+.. c:function:: void coresight_unregister(struct coresight_device *csdev);
+
+The registering function is taking a ``struct coresight_desc *desc`` and
+register the device with the core framework. The unregister function takes
+a reference to a ``struct coresight_device *csdev`` obtained at registration time.
+
+If everything goes well during the registration process the new devices will
+show up under /sys/bus/coresight/devices, as showns here for a TC2 platform::
+
+ root:~# ls /sys/bus/coresight/devices/
+ replicator 20030000.tpiu 2201c000.ptm 2203c000.etm 2203e000.etm
+ 20010000.etb 20040000.funnel 2201d000.ptm 2203d000.etm
+ root:~#
+
+The functions take a ``struct coresight_device``, which looks like this::
+
+ struct coresight_desc {
+ enum coresight_dev_type type;
+ struct coresight_dev_subtype subtype;
+ const struct coresight_ops *ops;
+ struct coresight_platform_data *pdata;
+ struct device *dev;
+ const struct attribute_group **groups;
+ };
+
+
+The "coresight_dev_type" identifies what the device is, i.e, source link or
+sink while the "coresight_dev_subtype" will characterise that type further.
+
+The ``struct coresight_ops`` is mandatory and will tell the framework how to
+perform base operations related to the components, each component having
+a different set of requirement. For that ``struct coresight_ops_sink``,
+``struct coresight_ops_link`` and ``struct coresight_ops_source`` have been
+provided.
+
+The next field ``struct coresight_platform_data *pdata`` is acquired by calling
+``of_get_coresight_platform_data()``, as part of the driver's _probe routine and
+``struct device *dev`` gets the device reference embedded in the ``amba_device``::
+
+ static int etm_probe(struct amba_device *adev, const struct amba_id *id)
+ {
+ ...
+ ...
+ drvdata->dev = &adev->dev;
+ ...
+ }
+
+Specific class of device (source, link, or sink) have generic operations
+that can be performed on them (see ``struct coresight_ops``). The ``**groups``
+is a list of sysfs entries pertaining to operations
+specific to that component only. "Implementation defined" customisations are
+expected to be accessed and controlled using those entries.
+
+Device Naming scheme
+--------------------
+
+The devices that appear on the "coresight" bus were named the same as their
+parent devices, i.e, the real devices that appears on AMBA bus or the platform bus.
+Thus the names were based on the Linux Open Firmware layer naming convention,
+which follows the base physical address of the device followed by the device
+type. e.g::
+
+ root:~# ls /sys/bus/coresight/devices/
+ 20010000.etf 20040000.funnel 20100000.stm 22040000.etm
+ 22140000.etm 230c0000.funnel 23240000.etm 20030000.tpiu
+ 20070000.etr 20120000.replicator 220c0000.funnel
+ 23040000.etm 23140000.etm 23340000.etm
+
+However, with the introduction of ACPI support, the names of the real
+devices are a bit cryptic and non-obvious. Thus, a new naming scheme was
+introduced to use more generic names based on the type of the device. The
+following rules apply::
+
+ 1) Devices that are bound to CPUs, are named based on the CPU logical
+ number.
+
+ e.g, ETM bound to CPU0 is named "etm0"
+
+ 2) All other devices follow a pattern, "<device_type_prefix>N", where :
+
+ <device_type_prefix> - A prefix specific to the type of the device
+ N - a sequential number assigned based on the order
+ of probing.
+
+ e.g, tmc_etf0, tmc_etr0, funnel0, funnel1
+
+Thus, with the new scheme the devices could appear as ::
+
+ root:~# ls /sys/bus/coresight/devices/
+ etm0 etm1 etm2 etm3 etm4 etm5 funnel0
+ funnel1 funnel2 replicator0 stm0 tmc_etf0 tmc_etr0 tpiu0
+
+Some of the examples below might refer to old naming scheme and some
+to the newer scheme, to give a confirmation that what you see on your
+system is not unexpected. One must use the "names" as they appear on
+the system under specified locations.
+
+How to use the tracer modules
+-----------------------------
+
+There are two ways to use the Coresight framework:
+
+1. using the perf cmd line tools.
+2. interacting directly with the Coresight devices using the sysFS interface.
+
+Preference is given to the former as using the sysFS interface
+requires a deep understanding of the Coresight HW. The following sections
+provide details on using both methods.
+
+1) Using the sysFS interface:
+
+Before trace collection can start, a coresight sink needs to be identified.
+There is no limit on the amount of sinks (nor sources) that can be enabled at
+any given moment. As a generic operation, all device pertaining to the sink
+class will have an "active" entry in sysfs::
+
+ root:/sys/bus/coresight/devices# ls
+ replicator 20030000.tpiu 2201c000.ptm 2203c000.etm 2203e000.etm
+ 20010000.etb 20040000.funnel 2201d000.ptm 2203d000.etm
+ root:/sys/bus/coresight/devices# ls 20010000.etb
+ enable_sink status trigger_cntr
+ root:/sys/bus/coresight/devices# echo 1 > 20010000.etb/enable_sink
+ root:/sys/bus/coresight/devices# cat 20010000.etb/enable_sink
+ 1
+ root:/sys/bus/coresight/devices#
+
+At boot time the current etm3x driver will configure the first address
+comparator with "_stext" and "_etext", essentially tracing any instruction
+that falls within that range. As such "enabling" a source will immediately
+trigger a trace capture::
+
+ root:/sys/bus/coresight/devices# echo 1 > 2201c000.ptm/enable_source
+ root:/sys/bus/coresight/devices# cat 2201c000.ptm/enable_source
+ 1
+ root:/sys/bus/coresight/devices# cat 20010000.etb/status
+ Depth: 0x2000
+ Status: 0x1
+ RAM read ptr: 0x0
+ RAM wrt ptr: 0x19d3 <----- The write pointer is moving
+ Trigger cnt: 0x0
+ Control: 0x1
+ Flush status: 0x0
+ Flush ctrl: 0x2001
+ root:/sys/bus/coresight/devices#
+
+Trace collection is stopped the same way::
+
+ root:/sys/bus/coresight/devices# echo 0 > 2201c000.ptm/enable_source
+ root:/sys/bus/coresight/devices#
+
+The content of the ETB buffer can be harvested directly from /dev::
+
+ root:/sys/bus/coresight/devices# dd if=/dev/20010000.etb \
+ of=~/cstrace.bin
+ 64+0 records in
+ 64+0 records out
+ 32768 bytes (33 kB) copied, 0.00125258 s, 26.2 MB/s
+ root:/sys/bus/coresight/devices#
+
+The file cstrace.bin can be decompressed using "ptm2human", DS-5 or Trace32.
+
+Following is a DS-5 output of an experimental loop that increments a variable up
+to a certain value. The example is simple and yet provides a glimpse of the
+wealth of possibilities that coresight provides.
+::
+
+ Info Tracing enabled
+ Instruction 106378866 0x8026B53C E52DE004 false PUSH {lr}
+ Instruction 0 0x8026B540 E24DD00C false SUB sp,sp,#0xc
+ Instruction 0 0x8026B544 E3A03000 false MOV r3,#0
+ Instruction 0 0x8026B548 E58D3004 false STR r3,[sp,#4]
+ Instruction 0 0x8026B54C E59D3004 false LDR r3,[sp,#4]
+ Instruction 0 0x8026B550 E3530004 false CMP r3,#4
+ Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1
+ Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4]
+ Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c
+ Timestamp Timestamp: 17106715833
+ Instruction 319 0x8026B54C E59D3004 false LDR r3,[sp,#4]
+ Instruction 0 0x8026B550 E3530004 false CMP r3,#4
+ Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1
+ Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4]
+ Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c
+ Instruction 9 0x8026B54C E59D3004 false LDR r3,[sp,#4]
+ Instruction 0 0x8026B550 E3530004 false CMP r3,#4
+ Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1
+ Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4]
+ Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c
+ Instruction 7 0x8026B54C E59D3004 false LDR r3,[sp,#4]
+ Instruction 0 0x8026B550 E3530004 false CMP r3,#4
+ Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1
+ Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4]
+ Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c
+ Instruction 7 0x8026B54C E59D3004 false LDR r3,[sp,#4]
+ Instruction 0 0x8026B550 E3530004 false CMP r3,#4
+ Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1
+ Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4]
+ Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c
+ Instruction 10 0x8026B54C E59D3004 false LDR r3,[sp,#4]
+ Instruction 0 0x8026B550 E3530004 false CMP r3,#4
+ Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1
+ Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4]
+ Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c
+ Instruction 6 0x8026B560 EE1D3F30 false MRC p15,#0x0,r3,c13,c0,#1
+ Instruction 0 0x8026B564 E1A0100D false MOV r1,sp
+ Instruction 0 0x8026B568 E3C12D7F false BIC r2,r1,#0x1fc0
+ Instruction 0 0x8026B56C E3C2203F false BIC r2,r2,#0x3f
+ Instruction 0 0x8026B570 E59D1004 false LDR r1,[sp,#4]
+ Instruction 0 0x8026B574 E59F0010 false LDR r0,[pc,#16] ; [0x8026B58C] = 0x80550368
+ Instruction 0 0x8026B578 E592200C false LDR r2,[r2,#0xc]
+ Instruction 0 0x8026B57C E59221D0 false LDR r2,[r2,#0x1d0]
+ Instruction 0 0x8026B580 EB07A4CF true BL {pc}+0x1e9344 ; 0x804548c4
+ Info Tracing enabled
+ Instruction 13570831 0x8026B584 E28DD00C false ADD sp,sp,#0xc
+ Instruction 0 0x8026B588 E8BD8000 true LDM sp!,{pc}
+ Timestamp Timestamp: 17107041535
+
+2) Using perf framework:
+
+Coresight tracers are represented using the Perf framework's Performance
+Monitoring Unit (PMU) abstraction. As such the perf framework takes charge of
+controlling when tracing gets enabled based on when the process of interest is
+scheduled. When configured in a system, Coresight PMUs will be listed when
+queried by the perf command line tool:
+
+ linaro@linaro-nano:~$ ./perf list pmu
+
+ List of pre-defined events (to be used in -e):
+
+ cs_etm// [Kernel PMU event]
+
+ linaro@linaro-nano:~$
+
+Regardless of the number of tracers available in a system (usually equal to the
+amount of processor cores), the "cs_etm" PMU will be listed only once.
+
+A Coresight PMU works the same way as any other PMU, i.e the name of the PMU is
+listed along with configuration options within forward slashes '/'. Since a
+Coresight system will typically have more than one sink, the name of the sink to
+work with needs to be specified as an event option.
+On newer kernels the available sinks are listed in sysFS under
+($SYSFS)/bus/event_source/devices/cs_etm/sinks/::
+
+ root@localhost:/sys/bus/event_source/devices/cs_etm/sinks# ls
+ tmc_etf0 tmc_etr0 tpiu0
+
+On older kernels, this may need to be found from the list of coresight devices,
+available under ($SYSFS)/bus/coresight/devices/::
+
+ root:~# ls /sys/bus/coresight/devices/
+ etm0 etm1 etm2 etm3 etm4 etm5 funnel0
+ funnel1 funnel2 replicator0 stm0 tmc_etf0 tmc_etr0 tpiu0
+ root@linaro-nano:~# perf record -e cs_etm/@tmc_etr0/u --per-thread program
+
+As mentioned above in section "Device Naming scheme", the names of the devices could
+look different from what is used in the example above. One must use the device names
+as it appears under the sysFS.
+
+The syntax within the forward slashes '/' is important. The '@' character
+tells the parser that a sink is about to be specified and that this is the sink
+to use for the trace session.
+
+More information on the above and other example on how to use Coresight with
+the perf tools can be found in the "HOWTO.md" file of the openCSD gitHub
+repository [#third]_.
+
+2.1) AutoFDO analysis using the perf tools:
+
+perf can be used to record and analyze trace of programs.
+
+Execution can be recorded using 'perf record' with the cs_etm event,
+specifying the name of the sink to record to, e.g::
+
+ perf record -e cs_etm/@tmc_etr0/u --per-thread
+
+The 'perf report' and 'perf script' commands can be used to analyze execution,
+synthesizing instruction and branch events from the instruction trace.
+'perf inject' can be used to replace the trace data with the synthesized events.
+The --itrace option controls the type and frequency of synthesized events
+(see perf documentation).
+
+Note that only 64-bit programs are currently supported - further work is
+required to support instruction decode of 32-bit Arm programs.
+
+
+Generating coverage files for Feedback Directed Optimization: AutoFDO
+---------------------------------------------------------------------
+
+'perf inject' accepts the --itrace option in which case tracing data is
+removed and replaced with the synthesized events. e.g.
+::
+
+ perf inject --itrace --strip -i perf.data -o perf.data.new
+
+Below is an example of using ARM ETM for autoFDO. It requires autofdo
+(https://github.com/google/autofdo) and gcc version 5. The bubble
+sort example is from the AutoFDO tutorial (https://gcc.gnu.org/wiki/AutoFDO/Tutorial).
+::
+
+ $ gcc-5 -O3 sort.c -o sort
+ $ taskset -c 2 ./sort
+ Bubble sorting array of 30000 elements
+ 5910 ms
+
+ $ perf record -e cs_etm/@tmc_etr0/u --per-thread taskset -c 2 ./sort
+ Bubble sorting array of 30000 elements
+ 12543 ms
+ [ perf record: Woken up 35 times to write data ]
+ [ perf record: Captured and wrote 69.640 MB perf.data ]
+
+ $ perf inject -i perf.data -o inj.data --itrace=il64 --strip
+ $ create_gcov --binary=./sort --profile=inj.data --gcov=sort.gcov -gcov_version=1
+ $ gcc-5 -O3 -fauto-profile=sort.gcov sort.c -o sort_autofdo
+ $ taskset -c 2 ./sort_autofdo
+ Bubble sorting array of 30000 elements
+ 5806 ms
+
+
+How to use the STM module
+-------------------------
+
+Using the System Trace Macrocell module is the same as the tracers - the only
+difference is that clients are driving the trace capture rather
+than the program flow through the code.
+
+As with any other CoreSight component, specifics about the STM tracer can be
+found in sysfs with more information on each entry being found in [#first]_::
+
+ root@genericarmv8:~# ls /sys/bus/coresight/devices/stm0
+ enable_source hwevent_select port_enable subsystem uevent
+ hwevent_enable mgmt port_select traceid
+ root@genericarmv8:~#
+
+Like any other source a sink needs to be identified and the STM enabled before
+being used::
+
+ root@genericarmv8:~# echo 1 > /sys/bus/coresight/devices/tmc_etf0/enable_sink
+ root@genericarmv8:~# echo 1 > /sys/bus/coresight/devices/stm0/enable_source
+
+From there user space applications can request and use channels using the devfs
+interface provided for that purpose by the generic STM API::
+
+ root@genericarmv8:~# ls -l /dev/stm0
+ crw------- 1 root root 10, 61 Jan 3 18:11 /dev/stm0
+ root@genericarmv8:~#
+
+Details on how to use the generic STM API can be found here [#second]_.
+
+.. [#first] Documentation/ABI/testing/sysfs-bus-coresight-devices-stm
+
+.. [#second] Documentation/trace/stm.rst
+
+.. [#third] https://github.com/Linaro/perf-opencsd
diff --git a/Documentation/trace/coresight.txt b/Documentation/trace/coresight.txt
deleted file mode 100644
index b027d61..0000000
--- a/Documentation/trace/coresight.txt
+++ /dev/null
@@ -1,482 +0,0 @@
- Coresight - HW Assisted Tracing on ARM
- ======================================
-
- Author: Mathieu Poirier <mathieu.poirier@linaro.org>
- Date: September 11th, 2014
-
-Introduction
-------------
-
-Coresight is an umbrella of technologies allowing for the debugging of ARM
-based SoC. It includes solutions for JTAG and HW assisted tracing. This
-document is concerned with the latter.
-
-HW assisted tracing is becoming increasingly useful when dealing with systems
-that have many SoCs and other components like GPU and DMA engines. ARM has
-developed a HW assisted tracing solution by means of different components, each
-being added to a design at synthesis time to cater to specific tracing needs.
-Components are generally categorised as source, link and sinks and are
-(usually) discovered using the AMBA bus.
-
-"Sources" generate a compressed stream representing the processor instruction
-path based on tracing scenarios as configured by users. From there the stream
-flows through the coresight system (via ATB bus) using links that are connecting
-the emanating source to a sink(s). Sinks serve as endpoints to the coresight
-implementation, either storing the compressed stream in a memory buffer or
-creating an interface to the outside world where data can be transferred to a
-host without fear of filling up the onboard coresight memory buffer.
-
-At typical coresight system would look like this:
-
- *****************************************************************
- **************************** AMBA AXI ****************************===||
- ***************************************************************** ||
- ^ ^ | ||
- | | * **
- 0000000 ::::: 0000000 ::::: ::::: @@@@@@@ ||||||||||||
- 0 CPU 0<-->: C : 0 CPU 0<-->: C : : C : @ STM @ || System ||
- |->0000000 : T : |->0000000 : T : : T :<--->@@@@@ || Memory ||
- | #######<-->: I : | #######<-->: I : : I : @@@<-| ||||||||||||
- | # ETM # ::::: | # PTM # ::::: ::::: @ |
- | ##### ^ ^ | ##### ^ ! ^ ! . | |||||||||
- | |->### | ! | |->### | ! | ! . | || DAP ||
- | | # | ! | | # | ! | ! . | |||||||||
- | | . | ! | | . | ! | ! . | | |
- | | . | ! | | . | ! | ! . | | *
- | | . | ! | | . | ! | ! . | | SWD/
- | | . | ! | | . | ! | ! . | | JTAG
- *****************************************************************<-|
- *************************** AMBA Debug APB ************************
- *****************************************************************
- | . ! . ! ! . |
- | . * . * * . |
- *****************************************************************
- ******************** Cross Trigger Matrix (CTM) *******************
- *****************************************************************
- | . ^ . . |
- | * ! * * |
- *****************************************************************
- ****************** AMBA Advanced Trace Bus (ATB) ******************
- *****************************************************************
- | ! =============== |
- | * ===== F =====<---------|
- | ::::::::: ==== U ====
- |-->:: CTI ::<!! === N ===
- | ::::::::: ! == N ==
- | ^ * == E ==
- | ! &&&&&&&&& IIIIIII == L ==
- |------>&& ETB &&<......II I =======
- | ! &&&&&&&&& II I .
- | ! I I .
- | ! I REP I<..........
- | ! I I
- | !!>&&&&&&&&& II I *Source: ARM ltd.
- |------>& TPIU &<......II I DAP = Debug Access Port
- &&&&&&&&& IIIIIII ETM = Embedded Trace Macrocell
- ; PTM = Program Trace Macrocell
- ; CTI = Cross Trigger Interface
- * ETB = Embedded Trace Buffer
- To trace port TPIU= Trace Port Interface Unit
- SWD = Serial Wire Debug
-
-While on target configuration of the components is done via the APB bus,
-all trace data are carried out-of-band on the ATB bus. The CTM provides
-a way to aggregate and distribute signals between CoreSight components.
-
-The coresight framework provides a central point to represent, configure and
-manage coresight devices on a platform. This first implementation centers on
-the basic tracing functionality, enabling components such ETM/PTM, funnel,
-replicator, TMC, TPIU and ETB. Future work will enable more
-intricate IP blocks such as STM and CTI.
-
-
-Acronyms and Classification
----------------------------
-
-Acronyms:
-
-PTM: Program Trace Macrocell
-ETM: Embedded Trace Macrocell
-STM: System trace Macrocell
-ETB: Embedded Trace Buffer
-ITM: Instrumentation Trace Macrocell
-TPIU: Trace Port Interface Unit
-TMC-ETR: Trace Memory Controller, configured as Embedded Trace Router
-TMC-ETF: Trace Memory Controller, configured as Embedded Trace FIFO
-CTI: Cross Trigger Interface
-
-Classification:
-
-Source:
- ETMv3.x ETMv4, PTMv1.0, PTMv1.1, STM, STM500, ITM
-Link:
- Funnel, replicator (intelligent or not), TMC-ETR
-Sinks:
- ETBv1.0, ETB1.1, TPIU, TMC-ETF
-Misc:
- CTI
-
-
-Device Tree Bindings
-----------------------
-
-See Documentation/devicetree/bindings/arm/coresight.txt for details.
-
-As of this writing drivers for ITM, STMs and CTIs are not provided but are
-expected to be added as the solution matures.
-
-
-Framework and implementation
-----------------------------
-
-The coresight framework provides a central point to represent, configure and
-manage coresight devices on a platform. Any coresight compliant device can
-register with the framework for as long as they use the right APIs:
-
-struct coresight_device *coresight_register(struct coresight_desc *desc);
-void coresight_unregister(struct coresight_device *csdev);
-
-The registering function is taking a "struct coresight_device *csdev" and
-register the device with the core framework. The unregister function takes
-a reference to a "struct coresight_device", obtained at registration time.
-
-If everything goes well during the registration process the new devices will
-show up under /sys/bus/coresight/devices, as showns here for a TC2 platform:
-
-root:~# ls /sys/bus/coresight/devices/
-replicator 20030000.tpiu 2201c000.ptm 2203c000.etm 2203e000.etm
-20010000.etb 20040000.funnel 2201d000.ptm 2203d000.etm
-root:~#
-
-The functions take a "struct coresight_device", which looks like this:
-
-struct coresight_desc {
- enum coresight_dev_type type;
- struct coresight_dev_subtype subtype;
- const struct coresight_ops *ops;
- struct coresight_platform_data *pdata;
- struct device *dev;
- const struct attribute_group **groups;
-};
-
-
-The "coresight_dev_type" identifies what the device is, i.e, source link or
-sink while the "coresight_dev_subtype" will characterise that type further.
-
-The "struct coresight_ops" is mandatory and will tell the framework how to
-perform base operations related to the components, each component having
-a different set of requirement. For that "struct coresight_ops_sink",
-"struct coresight_ops_link" and "struct coresight_ops_source" have been
-provided.
-
-The next field, "struct coresight_platform_data *pdata" is acquired by calling
-"of_get_coresight_platform_data()", as part of the driver's _probe routine and
-"struct device *dev" gets the device reference embedded in the "amba_device":
-
-static int etm_probe(struct amba_device *adev, const struct amba_id *id)
-{
- ...
- ...
- drvdata->dev = &adev->dev;
- ...
-}
-
-Specific class of device (source, link, or sink) have generic operations
-that can be performed on them (see "struct coresight_ops"). The
-"**groups" is a list of sysfs entries pertaining to operations
-specific to that component only. "Implementation defined" customisations are
-expected to be accessed and controlled using those entries.
-
-
-Device Naming scheme
-------------------------
-The devices that appear on the "coresight" bus were named the same as their
-parent devices, i.e, the real devices that appears on AMBA bus or the platform bus.
-Thus the names were based on the Linux Open Firmware layer naming convention,
-which follows the base physical address of the device followed by the device
-type. e.g:
-
-root:~# ls /sys/bus/coresight/devices/
- 20010000.etf 20040000.funnel 20100000.stm 22040000.etm
- 22140000.etm 230c0000.funnel 23240000.etm 20030000.tpiu
- 20070000.etr 20120000.replicator 220c0000.funnel
- 23040000.etm 23140000.etm 23340000.etm
-
-However, with the introduction of ACPI support, the names of the real
-devices are a bit cryptic and non-obvious. Thus, a new naming scheme was
-introduced to use more generic names based on the type of the device. The
-following rules apply:
-
- 1) Devices that are bound to CPUs, are named based on the CPU logical
- number.
-
- e.g, ETM bound to CPU0 is named "etm0"
-
- 2) All other devices follow a pattern, "<device_type_prefix>N", where :
-
- <device_type_prefix> - A prefix specific to the type of the device
- N - a sequential number assigned based on the order
- of probing.
-
- e.g, tmc_etf0, tmc_etr0, funnel0, funnel1
-
-Thus, with the new scheme the devices could appear as :
-
-root:~# ls /sys/bus/coresight/devices/
- etm0 etm1 etm2 etm3 etm4 etm5 funnel0
- funnel1 funnel2 replicator0 stm0 tmc_etf0 tmc_etr0 tpiu0
-
-Some of the examples below might refer to old naming scheme and some
-to the newer scheme, to give a confirmation that what you see on your
-system is not unexpected. One must use the "names" as they appear on
-the system under specified locations.
-
-How to use the tracer modules
------------------------------
-
-There are two ways to use the Coresight framework: 1) using the perf cmd line
-tools and 2) interacting directly with the Coresight devices using the sysFS
-interface. Preference is given to the former as using the sysFS interface
-requires a deep understanding of the Coresight HW. The following sections
-provide details on using both methods.
-
-1) Using the sysFS interface:
-
-Before trace collection can start, a coresight sink needs to be identified.
-There is no limit on the amount of sinks (nor sources) that can be enabled at
-any given moment. As a generic operation, all device pertaining to the sink
-class will have an "active" entry in sysfs:
-
-root:/sys/bus/coresight/devices# ls
-replicator 20030000.tpiu 2201c000.ptm 2203c000.etm 2203e000.etm
-20010000.etb 20040000.funnel 2201d000.ptm 2203d000.etm
-root:/sys/bus/coresight/devices# ls 20010000.etb
-enable_sink status trigger_cntr
-root:/sys/bus/coresight/devices# echo 1 > 20010000.etb/enable_sink
-root:/sys/bus/coresight/devices# cat 20010000.etb/enable_sink
-1
-root:/sys/bus/coresight/devices#
-
-At boot time the current etm3x driver will configure the first address
-comparator with "_stext" and "_etext", essentially tracing any instruction
-that falls within that range. As such "enabling" a source will immediately
-trigger a trace capture:
-
-root:/sys/bus/coresight/devices# echo 1 > 2201c000.ptm/enable_source
-root:/sys/bus/coresight/devices# cat 2201c000.ptm/enable_source
-1
-root:/sys/bus/coresight/devices# cat 20010000.etb/status
-Depth: 0x2000
-Status: 0x1
-RAM read ptr: 0x0
-RAM wrt ptr: 0x19d3 <----- The write pointer is moving
-Trigger cnt: 0x0
-Control: 0x1
-Flush status: 0x0
-Flush ctrl: 0x2001
-root:/sys/bus/coresight/devices#
-
-Trace collection is stopped the same way:
-
-root:/sys/bus/coresight/devices# echo 0 > 2201c000.ptm/enable_source
-root:/sys/bus/coresight/devices#
-
-The content of the ETB buffer can be harvested directly from /dev:
-
-root:/sys/bus/coresight/devices# dd if=/dev/20010000.etb \
-of=~/cstrace.bin
-
-64+0 records in
-64+0 records out
-32768 bytes (33 kB) copied, 0.00125258 s, 26.2 MB/s
-root:/sys/bus/coresight/devices#
-
-The file cstrace.bin can be decompressed using "ptm2human", DS-5 or Trace32.
-
-Following is a DS-5 output of an experimental loop that increments a variable up
-to a certain value. The example is simple and yet provides a glimpse of the
-wealth of possibilities that coresight provides.
-
-Info Tracing enabled
-Instruction 106378866 0x8026B53C E52DE004 false PUSH {lr}
-Instruction 0 0x8026B540 E24DD00C false SUB sp,sp,#0xc
-Instruction 0 0x8026B544 E3A03000 false MOV r3,#0
-Instruction 0 0x8026B548 E58D3004 false STR r3,[sp,#4]
-Instruction 0 0x8026B54C E59D3004 false LDR r3,[sp,#4]
-Instruction 0 0x8026B550 E3530004 false CMP r3,#4
-Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1
-Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4]
-Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c
-Timestamp Timestamp: 17106715833
-Instruction 319 0x8026B54C E59D3004 false LDR r3,[sp,#4]
-Instruction 0 0x8026B550 E3530004 false CMP r3,#4
-Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1
-Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4]
-Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c
-Instruction 9 0x8026B54C E59D3004 false LDR r3,[sp,#4]
-Instruction 0 0x8026B550 E3530004 false CMP r3,#4
-Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1
-Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4]
-Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c
-Instruction 7 0x8026B54C E59D3004 false LDR r3,[sp,#4]
-Instruction 0 0x8026B550 E3530004 false CMP r3,#4
-Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1
-Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4]
-Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c
-Instruction 7 0x8026B54C E59D3004 false LDR r3,[sp,#4]
-Instruction 0 0x8026B550 E3530004 false CMP r3,#4
-Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1
-Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4]
-Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c
-Instruction 10 0x8026B54C E59D3004 false LDR r3,[sp,#4]
-Instruction 0 0x8026B550 E3530004 false CMP r3,#4
-Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1
-Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4]
-Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c
-Instruction 6 0x8026B560 EE1D3F30 false MRC p15,#0x0,r3,c13,c0,#1
-Instruction 0 0x8026B564 E1A0100D false MOV r1,sp
-Instruction 0 0x8026B568 E3C12D7F false BIC r2,r1,#0x1fc0
-Instruction 0 0x8026B56C E3C2203F false BIC r2,r2,#0x3f
-Instruction 0 0x8026B570 E59D1004 false LDR r1,[sp,#4]
-Instruction 0 0x8026B574 E59F0010 false LDR r0,[pc,#16] ; [0x8026B58C] = 0x80550368
-Instruction 0 0x8026B578 E592200C false LDR r2,[r2,#0xc]
-Instruction 0 0x8026B57C E59221D0 false LDR r2,[r2,#0x1d0]
-Instruction 0 0x8026B580 EB07A4CF true BL {pc}+0x1e9344 ; 0x804548c4
-Info Tracing enabled
-Instruction 13570831 0x8026B584 E28DD00C false ADD sp,sp,#0xc
-Instruction 0 0x8026B588 E8BD8000 true LDM sp!,{pc}
-Timestamp Timestamp: 17107041535
-
-2) Using perf framework:
-
-Coresight tracers are represented using the Perf framework's Performance
-Monitoring Unit (PMU) abstraction. As such the perf framework takes charge of
-controlling when tracing gets enabled based on when the process of interest is
-scheduled. When configured in a system, Coresight PMUs will be listed when
-queried by the perf command line tool:
-
- linaro@linaro-nano:~$ ./perf list pmu
-
- List of pre-defined events (to be used in -e):
-
- cs_etm// [Kernel PMU event]
-
- linaro@linaro-nano:~$
-
-Regardless of the number of tracers available in a system (usually equal to the
-amount of processor cores), the "cs_etm" PMU will be listed only once.
-
-A Coresight PMU works the same way as any other PMU, i.e the name of the PMU is
-listed along with configuration options within forward slashes '/'. Since a
-Coresight system will typically have more than one sink, the name of the sink to
-work with needs to be specified as an event option.
-On newer kernels the available sinks are listed in sysFS under:
-($SYSFS)/bus/event_source/devices/cs_etm/sinks/
-
- root@localhost:/sys/bus/event_source/devices/cs_etm/sinks# ls
- tmc_etf0 tmc_etr0 tpiu0
-
-On older kernels, this may need to be found from the list of coresight devices,
-available under ($SYSFS)/bus/coresight/devices/:
-
- root:~# ls /sys/bus/coresight/devices/
- etm0 etm1 etm2 etm3 etm4 etm5 funnel0
- funnel1 funnel2 replicator0 stm0 tmc_etf0 tmc_etr0 tpiu0
-
- root@linaro-nano:~# perf record -e cs_etm/@tmc_etr0/u --per-thread program
-
-As mentioned above in section "Device Naming scheme", the names of the devices could
-look different from what is used in the example above. One must use the device names
-as it appears under the sysFS.
-
-The syntax within the forward slashes '/' is important. The '@' character
-tells the parser that a sink is about to be specified and that this is the sink
-to use for the trace session.
-
-More information on the above and other example on how to use Coresight with
-the perf tools can be found in the "HOWTO.md" file of the openCSD gitHub
-repository [3].
-
-2.1) AutoFDO analysis using the perf tools:
-
-perf can be used to record and analyze trace of programs.
-
-Execution can be recorded using 'perf record' with the cs_etm event,
-specifying the name of the sink to record to, e.g:
-
- perf record -e cs_etm/@tmc_etr0/u --per-thread
-
-The 'perf report' and 'perf script' commands can be used to analyze execution,
-synthesizing instruction and branch events from the instruction trace.
-'perf inject' can be used to replace the trace data with the synthesized events.
-The --itrace option controls the type and frequency of synthesized events
-(see perf documentation).
-
-Note that only 64-bit programs are currently supported - further work is
-required to support instruction decode of 32-bit Arm programs.
-
-
-Generating coverage files for Feedback Directed Optimization: AutoFDO
----------------------------------------------------------------------
-
-'perf inject' accepts the --itrace option in which case tracing data is
-removed and replaced with the synthesized events. e.g.
-
- perf inject --itrace --strip -i perf.data -o perf.data.new
-
-Below is an example of using ARM ETM for autoFDO. It requires autofdo
-(https://github.com/google/autofdo) and gcc version 5. The bubble
-sort example is from the AutoFDO tutorial (https://gcc.gnu.org/wiki/AutoFDO/Tutorial).
-
- $ gcc-5 -O3 sort.c -o sort
- $ taskset -c 2 ./sort
- Bubble sorting array of 30000 elements
- 5910 ms
-
- $ perf record -e cs_etm/@tmc_etr0/u --per-thread taskset -c 2 ./sort
- Bubble sorting array of 30000 elements
- 12543 ms
- [ perf record: Woken up 35 times to write data ]
- [ perf record: Captured and wrote 69.640 MB perf.data ]
-
- $ perf inject -i perf.data -o inj.data --itrace=il64 --strip
- $ create_gcov --binary=./sort --profile=inj.data --gcov=sort.gcov -gcov_version=1
- $ gcc-5 -O3 -fauto-profile=sort.gcov sort.c -o sort_autofdo
- $ taskset -c 2 ./sort_autofdo
- Bubble sorting array of 30000 elements
- 5806 ms
-
-
-How to use the STM module
--------------------------
-
-Using the System Trace Macrocell module is the same as the tracers - the only
-difference is that clients are driving the trace capture rather
-than the program flow through the code.
-
-As with any other CoreSight component, specifics about the STM tracer can be
-found in sysfs with more information on each entry being found in [1]:
-
-root@genericarmv8:~# ls /sys/bus/coresight/devices/stm0
-enable_source hwevent_select port_enable subsystem uevent
-hwevent_enable mgmt port_select traceid
-root@genericarmv8:~#
-
-Like any other source a sink needs to be identified and the STM enabled before
-being used:
-
-root@genericarmv8:~# echo 1 > /sys/bus/coresight/devices/tmc_etf0/enable_sink
-root@genericarmv8:~# echo 1 > /sys/bus/coresight/devices/stm0/enable_source
-
-From there user space applications can request and use channels using the devfs
-interface provided for that purpose by the generic STM API:
-
-root@genericarmv8:~# ls -l /dev/stm0
-crw------- 1 root root 10, 61 Jan 3 18:11 /dev/stm0
-root@genericarmv8:~#
-
-Details on how to use the generic STM API can be found here [2].
-
-[1]. Documentation/ABI/testing/sysfs-bus-coresight-devices-stm
-[2]. Documentation/trace/stm.rst
-[3]. https://github.com/Linaro/perf-opencsd
diff --git a/Documentation/trace/ftrace.rst b/Documentation/trace/ftrace.rst
index f600792..e3060ee 100644
--- a/Documentation/trace/ftrace.rst
+++ b/Documentation/trace/ftrace.rst
@@ -125,7 +125,8 @@
This file holds the output of the trace in a human
readable format (described below). Note, tracing is temporarily
- disabled while this file is being read (opened).
+ disabled when the file is open for reading. Once all readers
+ are closed, tracing is re-enabled.
trace_pipe:
@@ -139,8 +140,9 @@
will not be read again with a sequential read. The
"trace" file is static, and if the tracer is not
adding more data, it will display the same
- information every time it is read. This file will not
- disable tracing while being read.
+ information every time it is read. Unlike the
+ "trace" file, opening this file for reading will not
+ temporarily disable tracing.
trace_options:
@@ -3153,7 +3155,10 @@
Note, reading the trace_pipe file will block until more input is
-added.
+added. This is contrary to the trace file. If any process opened
+the trace file for reading, it will actually disable tracing and
+prevent new entries from being added. The trace_pipe file does
+not have this limitation.
trace entries
-------------
diff --git a/Documentation/trace/index.rst b/Documentation/trace/index.rst
index 6b4107c..b7891cb 100644
--- a/Documentation/trace/index.rst
+++ b/Documentation/trace/index.rst
@@ -23,3 +23,5 @@
intel_th
stm
sys-t
+ coresight
+ coresight-cpu-debug
diff --git a/Documentation/trace/kprobetrace.rst b/Documentation/trace/kprobetrace.rst
index fbb314b..5599305 100644
--- a/Documentation/trace/kprobetrace.rst
+++ b/Documentation/trace/kprobetrace.rst
@@ -52,6 +52,7 @@
$retval : Fetch return value.(\*2)
$comm : Fetch current task comm.
+|-[u]OFFS(FETCHARG) : Fetch memory at FETCHARG +|- OFFS address.(\*3)(\*4)
+ \IMM : Store an immediate value to the argument.
NAME=FETCHARG : Set NAME as the argument name of FETCHARG.
FETCHARG:TYPE : Set TYPE as the type of FETCHARG. Currently, basic types
(u8/u16/u32/u64/s8/s16/s32/s64), hexadecimal types
diff --git a/Documentation/trace/uprobetracer.rst b/Documentation/trace/uprobetracer.rst
index 6e75a6c..98cde99 100644
--- a/Documentation/trace/uprobetracer.rst
+++ b/Documentation/trace/uprobetracer.rst
@@ -45,6 +45,7 @@
$retval : Fetch return value.(\*1)
$comm : Fetch current task comm.
+|-[u]OFFS(FETCHARG) : Fetch memory at FETCHARG +|- OFFS address.(\*2)(\*3)
+ \IMM : Store an immediate value to the argument.
NAME=FETCHARG : Set NAME as the argument name of FETCHARG.
FETCHARG:TYPE : Set TYPE as the type of FETCHARG. Currently, basic types
(u8/u16/u32/u64/s8/s16/s32/s64), hexadecimal types
diff --git a/Documentation/translations/it_IT/process/changes.rst b/Documentation/translations/it_IT/process/changes.rst
index d087432..94a6499 100644
--- a/Documentation/translations/it_IT/process/changes.rst
+++ b/Documentation/translations/it_IT/process/changes.rst
@@ -26,16 +26,15 @@
usando, il comando indicato dovrebbe dirvelo.
Questa lista presume che abbiate già un kernel Linux funzionante. In aggiunta,
-non tutti gli strumenti sono necessari ovunque; ovviamente, se non avete un
-modem ISDN, per esempio, probabilmente non dovreste preoccuparvi di
-isdn4k-utils.
+non tutti gli strumenti sono necessari ovunque; ovviamente, se non avete una
+PC Card, per esempio, probabilmente non dovreste preoccuparvi di pcmciautils.
====================== ================= ========================================
Programma Versione minima Comando per verificare la versione
====================== ================= ========================================
GNU C 4.6 gcc --version
GNU make 3.81 make --version
-binutils 2.20 ld -v
+binutils 2.21 ld -v
flex 2.5.35 flex --version
bison 2.0 bison --version
util-linux 2.10o fdformat --version
@@ -49,7 +48,6 @@
pcmciautils 004 pccardctl -V
quota-tools 3.09 quota -V
PPP 2.4.0 pppd --version
-isdn4k-utils 3.1pre1 isdnctrl 2>&1|grep version
nfs-utils 1.0.5 showmount --version
procps 3.2.0 ps --version
oprofile 0.9 oprofiled --version
@@ -81,10 +79,7 @@
Binutils
--------
-Il sistema di compilazione, dalla versione 4.13, per la produzione dei passi
-intermedi, si è convertito all'uso di *thin archive* (`ar T`) piuttosto che
-all'uso del *linking* incrementale (`ld -r`). Questo richiede binutils 2.20 o
-successivo.
+Per generare il kernel è necessario avere Binutils 2.21 o superiore.
pkg-config
----------
@@ -286,11 +281,6 @@
mknod /dev/ppp c 108 0
-Isdn4k-utils
-------------
-
-Per via della modifica del campo per il numero di telefono, il pacchetto
-isdn4k-utils dev'essere ricompilato o (preferibilmente) aggiornato.
NFS-utils
---------
@@ -456,10 +446,6 @@
- <ftp://ftp.samba.org/pub/ppp/>
-Isdn4k-utils
-------------
-
-- <ftp://ftp.isdn4linux.de/pub/isdn4linux/utils/>
NFS-utils
---------
diff --git a/Documentation/translations/it_IT/process/howto.rst b/Documentation/translations/it_IT/process/howto.rst
index 44e6077..1db5a10 100644
--- a/Documentation/translations/it_IT/process/howto.rst
+++ b/Documentation/translations/it_IT/process/howto.rst
@@ -129,7 +129,7 @@
https://www.ozlabs.org/~akpm/stuff/tpp.txt
"Linux kernel patch submission format"
- http://linux.yyz.us/patch-format.html
+ https://web.archive.org/web/20180829112450/http://linux.yyz.us/patch-format.html
:ref:`Documentation/translations/it_IT/process/stable-api-nonsense.rst <it_stable_api_nonsense>`
diff --git a/Documentation/translations/it_IT/process/submitting-patches.rst b/Documentation/translations/it_IT/process/submitting-patches.rst
index 7d7ea92..cba1f8c 100644
--- a/Documentation/translations/it_IT/process/submitting-patches.rst
+++ b/Documentation/translations/it_IT/process/submitting-patches.rst
@@ -868,7 +868,7 @@
<http://www.ozlabs.org/~akpm/stuff/tpp.txt>
Jeff Garzik, "Formato per la sottomissione di patch per il kernel Linux"
- <http://linux.yyz.us/patch-format.html>
+ <https://web.archive.org/web/20180829112450/http://linux.yyz.us/patch-format.html>
Greg Kroah-Hartman, "Come scocciare un manutentore di un sottosistema"
<http://www.kroah.com/log/linux/maintainer.html>
diff --git a/Documentation/translations/ja_JP/SubmittingPatches b/Documentation/translations/ja_JP/SubmittingPatches
index ad979c3c..dd0c328 100644
--- a/Documentation/translations/ja_JP/SubmittingPatches
+++ b/Documentation/translations/ja_JP/SubmittingPatches
@@ -693,7 +693,7 @@
<http://www.ozlabs.org/~akpm/stuff/tpp.txt>
Jeff Garzik, "Linux kernel patch submission format".
- <http://linux.yyz.us/patch-format.html>
+ <https://web.archive.org/web/20180829112450/http://linux.yyz.us/patch-format.html>
Greg Kroah-Hartman, "How to piss off a kernel subsystem maintainer".
<http://www.kroah.com/log/2005/03/31/>
diff --git a/Documentation/translations/ja_JP/howto.rst b/Documentation/translations/ja_JP/howto.rst
index 2621b77..73ebdab 100644
--- a/Documentation/translations/ja_JP/howto.rst
+++ b/Documentation/translations/ja_JP/howto.rst
@@ -139,7 +139,7 @@
"The Perfect Patch"
http://www.ozlabs.org/~akpm/stuff/tpp.txt
"Linux kernel patch submission format"
- http://linux.yyz.us/patch-format.html
+ https://web.archive.org/web/20180829112450/http://linux.yyz.us/patch-format.html
:ref:`Documentation/process/stable-api-nonsense.rst <stable_api_nonsense>`
このファイルはカーネルの中に不変の API を持たないことにした意識的
diff --git a/Documentation/translations/ko_KR/howto.rst b/Documentation/translations/ko_KR/howto.rst
index bcd6373..b3f51b1 100644
--- a/Documentation/translations/ko_KR/howto.rst
+++ b/Documentation/translations/ko_KR/howto.rst
@@ -135,7 +135,7 @@
https://www.ozlabs.org/~akpm/stuff/tpp.txt
"Linux kernel patch submission format"
- http://linux.yyz.us/patch-format.html
+ https://web.archive.org/web/20180829112450/http://linux.yyz.us/patch-format.html
:ref:`Documentation/process/stable-api-nonsense.rst <stable_api_nonsense>`
이 문서는 의도적으로 커널이 불변하는 API를 갖지 않도록 결정한
diff --git a/Documentation/translations/zh_CN/arm64/booting.txt b/Documentation/translations/zh_CN/arm64/booting.txt
index 4e373d1..5b01641 100644
--- a/Documentation/translations/zh_CN/arm64/booting.txt
+++ b/Documentation/translations/zh_CN/arm64/booting.txt
@@ -67,8 +67,8 @@
必要性: 强制
设备树数据块（dtb）必须 8 字节对齐，且大小不能超过 2MB。由于设备树
-数据块将在使能缓存的情况下以 2MB 粒度被映射，故其不能被置于带任意
-特定属性被映射的 2MB 区域内。
+数据块将在使能缓存的情况下以 2MB 粒度被映射，故其不能被置于必须以特定
+属性映射的2M区域内。
注： v4.2 之前的版本同时要求设备树数据块被置于从内核映像以下
text_offset 字节处算起第一个 512MB 内。
diff --git a/Documentation/translations/zh_CN/process/howto.rst b/Documentation/translations/zh_CN/process/howto.rst
index 5b67117..a8e6ab8 100644
--- a/Documentation/translations/zh_CN/process/howto.rst
+++ b/Documentation/translations/zh_CN/process/howto.rst
@@ -113,7 +113,7 @@
"Linux kernel patch submission format"
- http://linux.yyz.us/patch-format.html
+ https://web.archive.org/web/20180829112450/http://linux.yyz.us/patch-format.html
:ref:`Documentation/translations/zh_CN/process/stable-api-nonsense.rst <cn_stable_api_nonsense>`
论证内核为什么特意不包括稳定的内核内部API，也就是说不包括像这样的特
@@ -146,14 +146,18 @@
:ref:`Documentation/process/applying-patches.rst <applying_patches>`
关于补丁是什么以及如何将它打在不同内核开发分支上的好介绍
-内核还拥有大量从代码自动生成的文档。它包含内核内部API的全面介绍以及如何
-妥善处理加锁的规则。生成的文档会放在 Documentation/DocBook/目录下。在内
-核源码的主目录中使用以下不同命令将会分别生成PDF、Postscript、HTML和手册
-页等不同格式的文档::
+内核还拥有大量从代码自动生成或者从 ReStructuredText(ReST) 标记生成的文档，
+比如这个文档，它包含内核内部API的全面介绍以及如何妥善处理加锁的规则。所有
+这些文档都可以通过运行以下命令从内核代码中生成为PDF或HTML文档::
make pdfdocs
make htmldocs
+ReST格式的文档会生成在 Documentation/output. 目录中。
+它们也可以用下列命令生成 LaTeX 和 ePub 格式文档::
+
+ make latexdocs
+ make epubdocs
如何成为内核开发者
------------------
diff --git a/Documentation/translations/zh_CN/process/submitting-patches.rst b/Documentation/translations/zh_CN/process/submitting-patches.rst
index 437c23b..1bb4271 100644
--- a/Documentation/translations/zh_CN/process/submitting-patches.rst
+++ b/Documentation/translations/zh_CN/process/submitting-patches.rst
@@ -652,7 +652,7 @@
<http://www.ozlabs.org/~akpm/stuff/tpp.txt>
Jeff Garzik, "Linux kernel patch submission format".
- <http://linux.yyz.us/patch-format.html>
+ <https://web.archive.org/web/20180829112450/http://linux.yyz.us/patch-format.html>
Greg Kroah-Hartman, "How to piss off a kernel subsystem maintainer".
<http://www.kroah.com/log/linux/maintainer.html>
diff --git a/Documentation/virt/kvm/api.txt b/Documentation/virt/kvm/api.txt
index 2d06776..4833904 100644
--- a/Documentation/virt/kvm/api.txt
+++ b/Documentation/virt/kvm/api.txt
@@ -586,7 +586,7 @@
Architectures: x86
Type: vcpu ioctl
Parameters: struct kvm_msrs (in)
-Returns: 0 on success, -1 on error
+Returns: number of msrs successfully set (see below), -1 on error
Writes model-specific registers to the vcpu. See KVM_GET_MSRS for the
data structures.
@@ -595,6 +595,11 @@
size of the entries array), and the 'index' and 'data' members of each
array entry.
+It tries to set the MSRs in array entries[] one by one. If setting an MSR
+fails, e.g., due to setting reserved bits, the MSR isn't supported/emulated
+by KVM, etc..., it stops processing the MSR list and returns the number of
+MSRs that have been set successfully.
+
4.20 KVM_SET_CPUID
@@ -753,8 +758,8 @@
use PPIs designated for specific cpus. The irq field is interpreted
like this:
- bits: | 31 ... 24 | 23 ... 16 | 15 ... 0 |
- field: | irq_type | vcpu_index | irq_id |
+ bits: | 31 ... 28 | 27 ... 24 | 23 ... 16 | 15 ... 0 |
+ field: | vcpu2_index | irq_type | vcpu_index | irq_id |
The irq_type field has the following values:
- irq_type[0]: out-of-kernel GIC: irq_id 0 is IRQ, irq_id 1 is FIQ
@@ -766,6 +771,14 @@
In both cases, level is used to assert/deassert the line.
+When KVM_CAP_ARM_IRQ_LINE_LAYOUT_2 is supported, the target vcpu is
+identified as (256 * vcpu2_index + vcpu_index). Otherwise, vcpu2_index
+must be zero.
+
+Note that on arm/arm64, the KVM_CAP_IRQCHIP capability only conditions
+injection of interrupts for the in-kernel irqchip. KVM_IRQ_LINE can always
+be used for a userspace interrupt controller.
+
struct kvm_irq_level {
union {
__u32 irq; /* GSI */
@@ -3079,12 +3092,14 @@
flag KVM_S390_MEMOP_F_INJECT_EXCEPTION is set in the "flags" field.
The start address of the memory region has to be specified in the "gaddr"
-field, and the length of the region in the "size" field. "buf" is the buffer
-supplied by the userspace application where the read data should be written
-to for KVM_S390_MEMOP_LOGICAL_READ, or where the data that should be written
-is stored for a KVM_S390_MEMOP_LOGICAL_WRITE. "buf" is unused and can be NULL
-when KVM_S390_MEMOP_F_CHECK_ONLY is specified. "ar" designates the access
-register number to be used.
+field, and the length of the region in the "size" field (which must not
+be 0). The maximum value for "size" can be obtained by checking the
+KVM_CAP_S390_MEM_OP capability. "buf" is the buffer supplied by the
+userspace application where the read data should be written to for
+KVM_S390_MEMOP_LOGICAL_READ, or where the data that should be written is
+stored for a KVM_S390_MEMOP_LOGICAL_WRITE. When KVM_S390_MEMOP_F_CHECK_ONLY
+is specified, "buf" is unused and can be NULL. "ar" designates the access
+register number to be used; the valid range is 0..15.
The "reserved" field is meant for future extensions. It is not used by
KVM with the currently defined set of flags.
@@ -5294,3 +5309,16 @@
This capability indicates that KVM supports paravirtualized Hyper-V IPI send
hypercalls:
HvCallSendSyntheticClusterIpi, HvCallSendSyntheticClusterIpiEx.
+8.21 KVM_CAP_HYPERV_DIRECT_TLBFLUSH
+
+Architecture: x86
+
+This capability indicates that KVM running on top of Hyper-V hypervisor
+enables Direct TLB flush for its guests meaning that TLB flush
+hypercalls are handled by Level 0 hypervisor (Hyper-V) bypassing KVM.
+Due to the different ABI for hypercall parameters between Hyper-V and
+KVM, enabling this capability effectively disables all hypercall
+handling by KVM (as some KVM hypercall may be mistakenly treated as TLB
+flush hypercalls by Hyper-V) so userspace should disable KVM identification
+in CPUID and only exposes Hyper-V identification. In this case, guest
+thinks it's running on Hyper-V and only use Hyper-V hypercalls.
diff --git a/Documentation/virt/kvm/mmu.txt b/Documentation/virt/kvm/mmu.txt
index 1b9880d..dadb29e 100644
--- a/Documentation/virt/kvm/mmu.txt
+++ b/Documentation/virt/kvm/mmu.txt
@@ -294,7 +294,7 @@
- walk shadow page table
- check for valid generation number in the spte (see "Fast invalidation of
MMIO sptes" below)
- - cache the information to vcpu->arch.mmio_gva, vcpu->arch.access and
+ - cache the information to vcpu->arch.mmio_gva, vcpu->arch.mmio_access and
vcpu->arch.mmio_gfn, and call the emulator
- If both P bit and R/W bit of error code are set, this could possibly
be handled as a "fast page fault" (fixed without taking the MMU lock). See
@@ -304,7 +304,7 @@
- if permissions are insufficient, reflect the fault back to the guest
- determine the host page
- if this is an mmio request, there is no host page; cache the info to
- vcpu->arch.mmio_gva, vcpu->arch.access and vcpu->arch.mmio_gfn
+ vcpu->arch.mmio_gva, vcpu->arch.mmio_access and vcpu->arch.mmio_gfn
- walk the shadow page table to find the spte for the translation,
instantiating missing intermediate page tables as necessary
- If this is an mmio request, cache the mmio info to the spte and set some
diff --git a/Documentation/virtual/guest-halt-polling.txt b/Documentation/virtual/guest-halt-polling.txt
new file mode 100644
index 0000000..b3a2a29
--- /dev/null
+++ b/Documentation/virtual/guest-halt-polling.txt
@@ -0,0 +1,78 @@
+Guest halt polling
+==================
+
+The cpuidle_haltpoll driver, with the haltpoll governor, allows
+the guest vcpus to poll for a specified amount of time before
+halting.
+This provides the following benefits to host side polling:
+
+ 1) The POLL flag is set while polling is performed, which allows
+ a remote vCPU to avoid sending an IPI (and the associated
+ cost of handling the IPI) when performing a wakeup.
+
+ 2) The VM-exit cost can be avoided.
+
+The downside of guest side polling is that polling is performed
+even with other runnable tasks in the host.
+
+The basic logic as follows: A global value, guest_halt_poll_ns,
+is configured by the user, indicating the maximum amount of
+time polling is allowed. This value is fixed.
+
+Each vcpu has an adjustable guest_halt_poll_ns
+("per-cpu guest_halt_poll_ns"), which is adjusted by the algorithm
+in response to events (explained below).
+
+Module Parameters
+=================
+
+The haltpoll governor has 5 tunable module parameters:
+
+1) guest_halt_poll_ns:
+Maximum amount of time, in nanoseconds, that polling is
+performed before halting.
+
+Default: 200000
+
+2) guest_halt_poll_shrink:
+Division factor used to shrink per-cpu guest_halt_poll_ns when
+wakeup event occurs after the global guest_halt_poll_ns.
+
+Default: 2
+
+3) guest_halt_poll_grow:
+Multiplication factor used to grow per-cpu guest_halt_poll_ns
+when event occurs after per-cpu guest_halt_poll_ns
+but before global guest_halt_poll_ns.
+
+Default: 2
+
+4) guest_halt_poll_grow_start:
+The per-cpu guest_halt_poll_ns eventually reaches zero
+in case of an idle system. This value sets the initial
+per-cpu guest_halt_poll_ns when growing. This can
+be increased from 10000, to avoid misses during the initial
+growth stage:
+
+10k, 20k, 40k, ... (example assumes guest_halt_poll_grow=2).
+
+Default: 50000
+
+5) guest_halt_poll_allow_shrink:
+
+Bool parameter which allows shrinking. Set to N
+to avoid it (per-cpu guest_halt_poll_ns will remain
+high once achieves global guest_halt_poll_ns value).
+
+Default: Y
+
+The module parameters can be set from the debugfs files in:
+
+ /sys/module/haltpoll/parameters/
+
+Further Notes
+=============
+
+- Care should be taken when setting the guest_halt_poll_ns parameter as a
+large value has the potential to drive the cpu usage to 100% on a machine which
+would be almost entirely idle otherwise.
diff --git a/Documentation/vm/hmm.rst b/Documentation/vm/hmm.rst
index 710ce1c..0a5960b 100644
--- a/Documentation/vm/hmm.rst
+++ b/Documentation/vm/hmm.rst
@@ -192,15 +192,14 @@
the driver callback returns.
When the device driver wants to populate a range of virtual addresses, it can
-use either::
+use::
- long hmm_range_snapshot(struct hmm_range *range);
- long hmm_range_fault(struct hmm_range *range, bool block);
+ long hmm_range_fault(struct hmm_range *range, unsigned int flags);
-The first one (hmm_range_snapshot()) will only fetch present CPU page table
+With the HMM_RANGE_SNAPSHOT flag, it will only fetch present CPU page table
entries and will not trigger a page fault on missing or non-present entries.
-The second one does trigger a page fault on missing or read-only entries if
-write access is requested (see below). Page faults use the generic mm page
+Without that flag, it does trigger a page fault on missing or read-only entries
+if write access is requested (see below). Page faults use the generic mm page
fault code path just like a CPU page fault.
Both functions copy CPU page table entries into their pfns array argument. Each
@@ -223,24 +222,24 @@
range.flags = ...;
range.values = ...;
range.pfn_shift = ...;
- hmm_range_register(&range);
+ hmm_range_register(&range, mirror);
/*
* Just wait for range to be valid, safe to ignore return value as we
- * will use the return value of hmm_range_snapshot() below under the
+ * will use the return value of hmm_range_fault() below under the
* mmap_sem to ascertain the validity of the range.
*/
hmm_range_wait_until_valid(&range, TIMEOUT_IN_MSEC);
again:
down_read(&mm->mmap_sem);
- ret = hmm_range_snapshot(&range);
+ ret = hmm_range_fault(&range, HMM_RANGE_SNAPSHOT);
if (ret) {
up_read(&mm->mmap_sem);
if (ret == -EBUSY) {
/*
* No need to check hmm_range_wait_until_valid() return value
- * on retry we will get proper error with hmm_range_snapshot()
+ * on retry we will get proper error with hmm_range_fault()
*/
hmm_range_wait_until_valid(&range, TIMEOUT_IN_MSEC);
goto again;
@@ -340,58 +339,8 @@
===================================
Because the CPU cannot access device memory, migration must use the device DMA
-engine to perform copy from and to device memory. For this we need a new
-migration helper::
-
- int migrate_vma(const struct migrate_vma_ops *ops,
- struct vm_area_struct *vma,
- unsigned long mentries,
- unsigned long start,
- unsigned long end,
- unsigned long *src,
- unsigned long *dst,
- void *private);
-
-Unlike other migration functions it works on a range of virtual address, there
-are two reasons for that. First, device DMA copy has a high setup overhead cost
-and thus batching multiple pages is needed as otherwise the migration overhead
-makes the whole exercise pointless. The second reason is because the
-migration might be for a range of addresses the device is actively accessing.
-
-The migrate_vma_ops struct defines two callbacks. First one (alloc_and_copy())
-controls destination memory allocation and copy operation. Second one is there
-to allow the device driver to perform cleanup operations after migration::
-
- struct migrate_vma_ops {
- void (*alloc_and_copy)(struct vm_area_struct *vma,
- const unsigned long *src,
- unsigned long *dst,
- unsigned long start,
- unsigned long end,
- void *private);
- void (*finalize_and_map)(struct vm_area_struct *vma,
- const unsigned long *src,
- const unsigned long *dst,
- unsigned long start,
- unsigned long end,
- void *private);
- };
-
-It is important to stress that these migration helpers allow for holes in the
-virtual address range. Some pages in the range might not be migrated for all
-the usual reasons (page is pinned, page is locked, ...). This helper does not
-fail but just skips over those pages.
-
-The alloc_and_copy() might decide to not migrate all pages in the
-range (for reasons under the callback control). For those, the callback just
-has to leave the corresponding dst entry empty.
-
-Finally, the migration of the struct page might fail (for file backed page) for
-various reasons (failure to freeze reference, or update page cache, ...). If
-that happens, then the finalize_and_map() can catch any pages that were not
-migrated. Note those pages were still copied to a new page and thus we wasted
-bandwidth but this is considered as a rare event and a price that we are
-willing to pay to keep all the code simpler.
+engine to perform copy from and to device memory. For this we need to use
+migrate_vma_setup(), migrate_vma_pages(), and migrate_vma_finalize() helpers.
Memory cgroup (memcg) and rss accounting
diff --git a/Documentation/vm/split_page_table_lock.rst b/Documentation/vm/split_page_table_lock.rst
index 889b00b..ff51f4a 100644
--- a/Documentation/vm/split_page_table_lock.rst
+++ b/Documentation/vm/split_page_table_lock.rst
@@ -54,9 +54,9 @@
Support of split page table lock by an architecture
===================================================
-There's no need in special enabling of PTE split page table lock:
-everything required is done by pgtable_page_ctor() and pgtable_page_dtor(),
-which must be called on PTE table allocation / freeing.
+There's no need in special enabling of PTE split page table lock: everything
+required is done by pgtable_pte_page_ctor() and pgtable_pte_page_dtor(), which
+must be called on PTE table allocation / freeing.
Make sure the architecture doesn't use slab allocator for page table
allocation: slab uses page->slab_cache for its pages.
@@ -74,7 +74,7 @@
With everything in place you can set CONFIG_ARCH_ENABLE_SPLIT_PMD_PTLOCK.
-NOTE: pgtable_page_ctor() and pgtable_pmd_page_ctor() can fail -- it must
+NOTE: pgtable_pte_page_ctor() and pgtable_pmd_page_ctor() can fail -- it must
be handled properly.
page->ptl
@@ -94,7 +94,7 @@
split lock with enabled DEBUG_SPINLOCK or DEBUG_LOCK_ALLOC, but costs
one more cache line for indirect access;
-The spinlock_t allocated in pgtable_page_ctor() for PTE table and in
+The spinlock_t allocated in pgtable_pte_page_ctor() for PTE table and in
pgtable_pmd_page_ctor() for PMD table.
Please, never access page->ptl directly -- use appropriate helper.
diff --git a/Documentation/w1/index.rst b/Documentation/w1/index.rst
new file mode 100644
index 0000000..57cba81
--- /dev/null
+++ b/Documentation/w1/index.rst
@@ -0,0 +1,21 @@
+. SPDX-License-Identifier: GPL-2.0
+
+================
+1-Wire Subsystem
+================
+
+.. toctree::
+ :maxdepth: 1
+
+
+ w1-generic.rst
+ w1-netlink.rst
+ masters/index
+ slaves/index
+
+.. only:: subproject and html
+
+ Indices
+ =======
+
+ * :ref:`genindex`
diff --git a/Documentation/w1/masters/ds2482 b/Documentation/w1/masters/ds2482
deleted file mode 100644
index 56f8eda..0000000
--- a/Documentation/w1/masters/ds2482
+++ /dev/null
@@ -1,31 +0,0 @@
-Kernel driver ds2482
-====================
-
-Supported chips:
- * Maxim DS2482-100, Maxim DS2482-800
- Prefix: 'ds2482'
- Addresses scanned: None
- Datasheets:
- http://datasheets.maxim-ic.com/en/ds/DS2482-100.pdf
- http://datasheets.maxim-ic.com/en/ds/DS2482-800.pdf
-
-Author: Ben Gardner <bgardner@wabtec.com>
-
-
-Description
------------
-
-The Maxim/Dallas Semiconductor DS2482 is a I2C device that provides
-one (DS2482-100) or eight (DS2482-800) 1-wire busses.
-
-
-General Remarks
----------------
-
-Valid addresses are 0x18, 0x19, 0x1a, and 0x1b.
-However, the device cannot be detected without writing to the i2c bus, so no
-detection is done. You should instantiate the device explicitly.
-
-$ modprobe ds2482
-$ echo ds2482 0x18 > /sys/bus/i2c/devices/i2c-0/new_device
-
diff --git a/Documentation/w1/masters/ds2482.rst b/Documentation/w1/masters/ds2482.rst
new file mode 100644
index 0000000..17ebe8f
--- /dev/null
+++ b/Documentation/w1/masters/ds2482.rst
@@ -0,0 +1,39 @@
+====================
+Kernel driver ds2482
+====================
+
+Supported chips:
+
+ * Maxim DS2482-100, Maxim DS2482-800
+
+ Prefix: 'ds2482'
+
+ Addresses scanned: None
+
+ Datasheets:
+
+ - http://datasheets.maxim-ic.com/en/ds/DS2482-100.pdf
+ - http://datasheets.maxim-ic.com/en/ds/DS2482-800.pdf
+
+Author: Ben Gardner <bgardner@wabtec.com>
+
+
+Description
+-----------
+
+The Maxim/Dallas Semiconductor DS2482 is a I2C device that provides
+one (DS2482-100) or eight (DS2482-800) 1-wire busses.
+
+
+General Remarks
+---------------
+
+Valid addresses are 0x18, 0x19, 0x1a, and 0x1b.
+
+However, the device cannot be detected without writing to the i2c bus, so no
+detection is done. You should instantiate the device explicitly.
+
+::
+
+ $ modprobe ds2482
+ $ echo ds2482 0x18 > /sys/bus/i2c/devices/i2c-0/new_device
diff --git a/Documentation/w1/masters/ds2490 b/Documentation/w1/masters/ds2490
deleted file mode 100644
index 3e09115..0000000
--- a/Documentation/w1/masters/ds2490
+++ /dev/null
@@ -1,68 +0,0 @@
-Kernel driver ds2490
-====================
-
-Supported chips:
- * Maxim DS2490 based
-
-Author: Evgeniy Polyakov <johnpol@2ka.mipt.ru>
-
-
-Description
------------
-
-The Maxim/Dallas Semiconductor DS2490 is a chip
-which allows to build USB <-> W1 bridges.
-
-DS9490(R) is a USB <-> W1 bus master device
-which has 0x81 family ID integrated chip and DS2490
-low-level operational chip.
-
-Notes and limitations.
-- The weak pullup current is a minimum of 0.9mA and maximum of 6.0mA.
-- The 5V strong pullup is supported with a minimum of 5.9mA and a
- maximum of 30.4 mA. (From DS2490.pdf)
-- The hardware will detect when devices are attached to the bus on the
- next bus (reset?) operation, however only a message is printed as
- the core w1 code doesn't make use of the information. Connecting
- one device tends to give multiple new device notifications.
-- The number of USB bus transactions could be reduced if w1_reset_send
- was added to the API. The name is just a suggestion. It would take
- a write buffer and a read buffer (along with sizes) as arguments.
- The ds2490 block I/O command supports reset, write buffer, read
- buffer, and strong pullup all in one command, instead of the current
- 1 reset bus, 2 write the match rom command and slave rom id, 3 block
- write and read data. The write buffer needs to have the match rom
- command and slave rom id prepended to the front of the requested
- write buffer, both of which are known to the driver.
-- The hardware supports normal, flexible, and overdrive bus
- communication speeds, but only the normal is supported.
-- The registered w1_bus_master functions don't define error
- conditions. If a bus search is in progress and the ds2490 is
- removed it can produce a good amount of error output before the bus
- search finishes.
-- The hardware supports detecting some error conditions, such as
- short, alarming presence on reset, and no presence on reset, but the
- driver doesn't query those values.
-- The ds2490 specification doesn't cover short bulk in reads in
- detail, but my observation is if fewer bytes are requested than are
- available, the bulk read will return an error and the hardware will
- clear the entire bulk in buffer. It would be possible to read the
- maximum buffer size to not run into this error condition, only extra
- bytes in the buffer is a logic error in the driver. The code should
- should match reads and writes as well as data sizes. Reads and
- writes are serialized and the status verifies that the chip is idle
- (and data is available) before the read is executed, so it should
- not happen.
-- Running x86_64 2.6.24 UHCI under qemu 0.9.0 under x86_64 2.6.22-rc6
- with a OHCI controller, ds2490 running in the guest would operate
- normally the first time the module was loaded after qemu attached
- the ds2490 hardware, but if the module was unloaded, then reloaded
- most of the time one of the bulk out or in, and usually the bulk in
- would fail. qemu sets a 50ms timeout and the bulk in would timeout
- even when the status shows data available. A bulk out write would
- show a successful completion, but the ds2490 status register would
- show 0 bytes written. Detaching qemu from the ds2490 hardware and
- reattaching would clear the problem. usbmon output in the guest and
- host did not explain the problem. My guess is a bug in either qemu
- or the host OS and more likely the host OS.
--- 03-06-2008 David Fries <David@Fries.net>
diff --git a/Documentation/w1/masters/ds2490.rst b/Documentation/w1/masters/ds2490.rst
new file mode 100644
index 0000000..7e5b50f
--- /dev/null
+++ b/Documentation/w1/masters/ds2490.rst
@@ -0,0 +1,72 @@
+====================
+Kernel driver ds2490
+====================
+
+Supported chips:
+
+ * Maxim DS2490 based
+
+Author: Evgeniy Polyakov <johnpol@2ka.mipt.ru>
+
+
+Description
+-----------
+
+The Maxim/Dallas Semiconductor DS2490 is a chip
+which allows to build USB <-> W1 bridges.
+
+DS9490(R) is a USB <-> W1 bus master device
+which has 0x81 family ID integrated chip and DS2490
+low-level operational chip.
+
+Notes and limitations.
+
+- The weak pullup current is a minimum of 0.9mA and maximum of 6.0mA.
+- The 5V strong pullup is supported with a minimum of 5.9mA and a
+ maximum of 30.4 mA. (From DS2490.pdf)
+- The hardware will detect when devices are attached to the bus on the
+ next bus (reset?) operation, however only a message is printed as
+ the core w1 code doesn't make use of the information. Connecting
+ one device tends to give multiple new device notifications.
+- The number of USB bus transactions could be reduced if w1_reset_send
+ was added to the API. The name is just a suggestion. It would take
+ a write buffer and a read buffer (along with sizes) as arguments.
+ The ds2490 block I/O command supports reset, write buffer, read
+ buffer, and strong pullup all in one command, instead of the current
+ 1 reset bus, 2 write the match rom command and slave rom id, 3 block
+ write and read data. The write buffer needs to have the match rom
+ command and slave rom id prepended to the front of the requested
+ write buffer, both of which are known to the driver.
+- The hardware supports normal, flexible, and overdrive bus
+ communication speeds, but only the normal is supported.
+- The registered w1_bus_master functions don't define error
+ conditions. If a bus search is in progress and the ds2490 is
+ removed it can produce a good amount of error output before the bus
+ search finishes.
+- The hardware supports detecting some error conditions, such as
+ short, alarming presence on reset, and no presence on reset, but the
+ driver doesn't query those values.
+- The ds2490 specification doesn't cover short bulk in reads in
+ detail, but my observation is if fewer bytes are requested than are
+ available, the bulk read will return an error and the hardware will
+ clear the entire bulk in buffer. It would be possible to read the
+ maximum buffer size to not run into this error condition, only extra
+ bytes in the buffer is a logic error in the driver. The code should
+ should match reads and writes as well as data sizes. Reads and
+ writes are serialized and the status verifies that the chip is idle
+ (and data is available) before the read is executed, so it should
+ not happen.
+- Running x86_64 2.6.24 UHCI under qemu 0.9.0 under x86_64 2.6.22-rc6
+ with a OHCI controller, ds2490 running in the guest would operate
+ normally the first time the module was loaded after qemu attached
+ the ds2490 hardware, but if the module was unloaded, then reloaded
+ most of the time one of the bulk out or in, and usually the bulk in
+ would fail. qemu sets a 50ms timeout and the bulk in would timeout
+ even when the status shows data available. A bulk out write would
+ show a successful completion, but the ds2490 status register would
+ show 0 bytes written. Detaching qemu from the ds2490 hardware and
+ reattaching would clear the problem. usbmon output in the guest and
+ host did not explain the problem. My guess is a bug in either qemu
+ or the host OS and more likely the host OS.
+
+03-06-2008 David Fries <David@Fries.net>
diff --git a/Documentation/w1/masters/index.rst b/Documentation/w1/masters/index.rst
new file mode 100644
index 0000000..4442a988
--- /dev/null
+++ b/Documentation/w1/masters/index.rst
@@ -0,0 +1,14 @@
+. SPDX-License-Identifier: GPL-2.0
+
+=====================
+1-wire Master Drivers
+=====================
+
+.. toctree::
+ :maxdepth: 1
+
+ ds2482
+ ds2490
+ mxc-w1
+ omap-hdq
+ w1-gpio
diff --git a/Documentation/w1/masters/mxc-w1 b/Documentation/w1/masters/mxc-w1
deleted file mode 100644
index 38be1ad..0000000
--- a/Documentation/w1/masters/mxc-w1
+++ /dev/null
@@ -1,12 +0,0 @@
-Kernel driver mxc_w1
-====================
-
-Supported chips:
- * Freescale MX27, MX31 and probably other i.MX SoCs
- Datasheets:
- http://www.freescale.com/files/32bit/doc/data_sheet/MCIMX31.pdf?fpsp=1
- http://cache.freescale.com/files/dsp/doc/archive/MCIMX27.pdf?fsrch=1&WT_TYPE=
- Data%20Sheets&WT_VENDOR=FREESCALE&WT_FILE_FORMAT=pdf&WT_ASSET=Documentation
-
-Author: Originally based on Freescale code, prepared for mainline by
- Sascha Hauer <s.hauer@pengutronix.de>
diff --git a/Documentation/w1/masters/mxc-w1.rst b/Documentation/w1/masters/mxc-w1.rst
new file mode 100644
index 0000000..334f989
--- /dev/null
+++ b/Documentation/w1/masters/mxc-w1.rst
@@ -0,0 +1,17 @@
+====================
+Kernel driver mxc_w1
+====================
+
+Supported chips:
+
+ * Freescale MX27, MX31 and probably other i.MX SoCs
+
+ Datasheets:
+
+ - http://www.freescale.com/files/32bit/doc/data_sheet/MCIMX31.pdf?fpsp=1
+ - http://cache.freescale.com/files/dsp/doc/archive/MCIMX27.pdf?fsrch=1&WT_TYPE=Data%20Sheets&WT_VENDOR=FREESCALE&WT_FILE_FORMAT=pdf&WT_ASSET=Documentation
+
+Author:
+
+ Originally based on Freescale code, prepared for mainline by
+ Sascha Hauer <s.hauer@pengutronix.de>
diff --git a/Documentation/w1/masters/omap-hdq b/Documentation/w1/masters/omap-hdq
deleted file mode 100644
index 2345227..0000000
--- a/Documentation/w1/masters/omap-hdq
+++ /dev/null
@@ -1,52 +0,0 @@
-Kernel driver for omap HDQ/1-wire module.
-========================================
-
-Supported chips:
-================
- HDQ/1-wire controller on the TI OMAP 2430/3430 platforms.
-
-A useful link about HDQ basics:
-===============================
-http://focus.ti.com/lit/an/slua408a/slua408a.pdf
-
-Description:
-============
-The HDQ/1-Wire module of TI OMAP2430/3430 platforms implement the hardware
-protocol of the master functions of the Benchmark HDQ and the Dallas
-Semiconductor 1-Wire protocols. These protocols use a single wire for
-communication between the master (HDQ/1-Wire controller) and the slave
-(HDQ/1-Wire external compliant device).
-
-A typical application of the HDQ/1-Wire module is the communication with battery
-monitor (gas gauge) integrated circuits.
-
-The controller supports operation in both HDQ and 1-wire mode. The essential
-difference between the HDQ and 1-wire mode is how the slave device responds to
-initialization pulse.In HDQ mode, the firmware does not require the host to
-create an initialization pulse to the slave.However, the slave can be reset by
-using an initialization pulse (also referred to as a break pulse).The slave
-does not respond with a presence pulse as it does in the 1-Wire protocol.
-
-Remarks:
-========
-The driver (drivers/w1/masters/omap_hdq.c) supports the HDQ mode of the
-controller. In this mode, as we can not read the ID which obeys the W1
-spec(family:id:crc), a module parameter can be passed to the driver which will
-be used to calculate the CRC and pass back an appropriate slave ID to the W1
-core.
-
-By default the master driver and the BQ slave i/f
-driver(drivers/w1/slaves/w1_bq27000.c) sets the ID to 1.
-Please note to load both the modules with a different ID if required, but note
-that the ID used should be same for both master and slave driver loading.
-
-e.g:
-insmod omap_hdq.ko W1_ID=2
-inamod w1_bq27000.ko F_ID=2
-
-The driver also supports 1-wire mode. In this mode, there is no need to
-pass slave ID as parameter. The driver will auto-detect slaves connected
-to the bus using SEARCH_ROM procedure. 1-wire mode can be selected by
-setting "ti,mode" property to "1w" in DT (see
-Documentation/devicetree/bindings/w1/omap-hdq.txt for more details).
-By default driver is in HDQ mode.
diff --git a/Documentation/w1/masters/omap-hdq.rst b/Documentation/w1/masters/omap-hdq.rst
new file mode 100644
index 0000000..345298a
--- /dev/null
+++ b/Documentation/w1/masters/omap-hdq.rst
@@ -0,0 +1,54 @@
+========================================
+Kernel driver for omap HDQ/1-wire module
+========================================
+
+Supported chips:
+================
+HDQ/1-wire controller on the TI OMAP 2430/3430 platforms.
+
+A useful link about HDQ basics:
+===============================
+http://focus.ti.com/lit/an/slua408a/slua408a.pdf
+
+Description:
+============
+The HDQ/1-Wire module of TI OMAP2430/3430 platforms implement the hardware
+protocol of the master functions of the Benchmark HDQ and the Dallas
+Semiconductor 1-Wire protocols. These protocols use a single wire for
+communication between the master (HDQ/1-Wire controller) and the slave
+(HDQ/1-Wire external compliant device).
+
+A typical application of the HDQ/1-Wire module is the communication with battery
+monitor (gas gauge) integrated circuits.
+
+The controller supports operation in both HDQ and 1-wire mode. The essential
+difference between the HDQ and 1-wire mode is how the slave device responds to
+initialization pulse.In HDQ mode, the firmware does not require the host to
+create an initialization pulse to the slave.However, the slave can be reset by
+using an initialization pulse (also referred to as a break pulse).The slave
+does not respond with a presence pulse as it does in the 1-Wire protocol.
+
+Remarks:
+========
+The driver (drivers/w1/masters/omap_hdq.c) supports the HDQ mode of the
+controller. In this mode, as we can not read the ID which obeys the W1
+spec(family:id:crc), a module parameter can be passed to the driver which will
+be used to calculate the CRC and pass back an appropriate slave ID to the W1
+core.
+
+By default the master driver and the BQ slave i/f
+driver(drivers/w1/slaves/w1_bq27000.c) sets the ID to 1.
+Please note to load both the modules with a different ID if required, but note
+that the ID used should be same for both master and slave driver loading.
+
+e.g::
+
+ insmod omap_hdq.ko W1_ID=2
+ inamod w1_bq27000.ko F_ID=2
+
+The driver also supports 1-wire mode. In this mode, there is no need to
+pass slave ID as parameter. The driver will auto-detect slaves connected
+to the bus using SEARCH_ROM procedure. 1-wire mode can be selected by
+setting "ti,mode" property to "1w" in DT (see
+Documentation/devicetree/bindings/w1/omap-hdq.txt for more details).
+By default driver is in HDQ mode.
diff --git a/Documentation/w1/masters/w1-gpio b/Documentation/w1/masters/w1-gpio
deleted file mode 100644
index 623961d..0000000
--- a/Documentation/w1/masters/w1-gpio
+++ /dev/null
@@ -1,44 +0,0 @@
-Kernel driver w1-gpio
-=====================
-
-Author: Ville Syrjala <syrjala@sci.fi>
-
-
-Description
------------
-
-GPIO 1-wire bus master driver. The driver uses the GPIO API to control the
-wire and the GPIO pin can be specified using GPIO machine descriptor tables.
-It is also possible to define the master using device tree, see
-Documentation/devicetree/bindings/w1/w1-gpio.txt
-
-
-Example (mach-at91)
--------------------
-
-#include <linux/gpio/machine.h>
-#include <linux/w1-gpio.h>
-
-static struct gpiod_lookup_table foo_w1_gpiod_table = {
- .dev_id = "w1-gpio",
- .table = {
- GPIO_LOOKUP_IDX("at91-gpio", AT91_PIN_PB20, NULL, 0,
- GPIO_ACTIVE_HIGH|GPIO_OPEN_DRAIN),
- },
-};
-
-static struct w1_gpio_platform_data foo_w1_gpio_pdata = {
- .ext_pullup_enable_pin = -EINVAL,
-};
-
-static struct platform_device foo_w1_device = {
- .name = "w1-gpio",
- .id = -1,
- .dev.platform_data = &foo_w1_gpio_pdata,
-};
-
-...
- at91_set_GPIO_periph(foo_w1_gpio_pdata.pin, 1);
- at91_set_multi_drive(foo_w1_gpio_pdata.pin, 1);
- gpiod_add_lookup_table(&foo_w1_gpiod_table);
- platform_device_register(&foo_w1_device);
diff --git a/Documentation/w1/masters/w1-gpio.rst b/Documentation/w1/masters/w1-gpio.rst
new file mode 100644
index 0000000..18fdb73
--- /dev/null
+++ b/Documentation/w1/masters/w1-gpio.rst
@@ -0,0 +1,47 @@
+=====================
+Kernel driver w1-gpio
+=====================
+
+Author: Ville Syrjala <syrjala@sci.fi>
+
+
+Description
+-----------
+
+GPIO 1-wire bus master driver. The driver uses the GPIO API to control the
+wire and the GPIO pin can be specified using GPIO machine descriptor tables.
+It is also possible to define the master using device tree, see
+Documentation/devicetree/bindings/w1/w1-gpio.txt
+
+
+Example (mach-at91)
+-------------------
+
+::
+
+ #include <linux/gpio/machine.h>
+ #include <linux/w1-gpio.h>
+
+ static struct gpiod_lookup_table foo_w1_gpiod_table = {
+ .dev_id = "w1-gpio",
+ .table = {
+ GPIO_LOOKUP_IDX("at91-gpio", AT91_PIN_PB20, NULL, 0,
+ GPIO_ACTIVE_HIGH|GPIO_OPEN_DRAIN),
+ },
+ };
+
+ static struct w1_gpio_platform_data foo_w1_gpio_pdata = {
+ .ext_pullup_enable_pin = -EINVAL,
+ };
+
+ static struct platform_device foo_w1_device = {
+ .name = "w1-gpio",
+ .id = -1,
+ .dev.platform_data = &foo_w1_gpio_pdata,
+ };
+
+ ...
+ at91_set_GPIO_periph(foo_w1_gpio_pdata.pin, 1);
+ at91_set_multi_drive(foo_w1_gpio_pdata.pin, 1);
+ gpiod_add_lookup_table(&foo_w1_gpiod_table);
+ platform_device_register(&foo_w1_device);
diff --git a/Documentation/w1/slaves/index.rst b/Documentation/w1/slaves/index.rst
new file mode 100644
index 0000000..d0697b2
--- /dev/null
+++ b/Documentation/w1/slaves/index.rst
@@ -0,0 +1,16 @@
+. SPDX-License-Identifier: GPL-2.0
+
+====================
+1-wire Slave Drivers
+====================
+
+.. toctree::
+ :maxdepth: 1
+
+ w1_ds2406
+ w1_ds2413
+ w1_ds2423
+ w1_ds2438
+ w1_ds28e04
+ w1_ds28e17
+ w1_therm
diff --git a/Documentation/w1/slaves/w1_ds2406 b/Documentation/w1/slaves/w1_ds2406
deleted file mode 100644
index 8137fe6..0000000
--- a/Documentation/w1/slaves/w1_ds2406
+++ /dev/null
@@ -1,25 +0,0 @@
-w1_ds2406 kernel driver
-=======================
-
-Supported chips:
- * Maxim DS2406 (and other family 0x12) addressable switches
-
-Author: Scott Alfter <scott@alfter.us>
-
-Description
------------
-
-The w1_ds2406 driver allows connected devices to be switched on and off.
-These chips also provide 128 bytes of OTP EPROM, but reading/writing it is
-not supported. In TSOC-6 form, the DS2406 provides two switch outputs and
-can be provided with power on a dedicated input. In TO-92 form, it provides
-one output and uses parasitic power only.
-
-The driver provides two sysfs files. state is readable; it gives the
-current state of each switch, with PIO A in bit 0 and PIO B in bit 1. The
-driver ORs this state with 0x30, so shell scripts get an ASCII 0/1/2/3 to
-work with. output is writable; bits 0 and 1 control PIO A and B,
-respectively. Bits 2-7 are ignored, so it's safe to write ASCII data.
-
-CRCs are checked on read and write. Failed checks cause an I/O error to be
-returned. On a failed write, the switch status is not changed.
diff --git a/Documentation/w1/slaves/w1_ds2406.rst b/Documentation/w1/slaves/w1_ds2406.rst
new file mode 100644
index 0000000..d3e6826
--- /dev/null
+++ b/Documentation/w1/slaves/w1_ds2406.rst
@@ -0,0 +1,27 @@
+=======================
+w1_ds2406 kernel driver
+=======================
+
+Supported chips:
+
+ * Maxim DS2406 (and other family 0x12) addressable switches
+
+Author: Scott Alfter <scott@alfter.us>
+
+Description
+-----------
+
+The w1_ds2406 driver allows connected devices to be switched on and off.
+These chips also provide 128 bytes of OTP EPROM, but reading/writing it is
+not supported. In TSOC-6 form, the DS2406 provides two switch outputs and
+can be provided with power on a dedicated input. In TO-92 form, it provides
+one output and uses parasitic power only.
+
+The driver provides two sysfs files. state is readable; it gives the
+current state of each switch, with PIO A in bit 0 and PIO B in bit 1. The
+driver ORs this state with 0x30, so shell scripts get an ASCII 0/1/2/3 to
+work with. output is writable; bits 0 and 1 control PIO A and B,
+respectively. Bits 2-7 are ignored, so it's safe to write ASCII data.
+
+CRCs are checked on read and write. Failed checks cause an I/O error to be
+returned. On a failed write, the switch status is not changed.
diff --git a/Documentation/w1/slaves/w1_ds2413 b/Documentation/w1/slaves/w1_ds2413
deleted file mode 100644
index 936263a..0000000
--- a/Documentation/w1/slaves/w1_ds2413
+++ /dev/null
@@ -1,50 +0,0 @@
-Kernel driver w1_ds2413
-=======================
-
-Supported chips:
- * Maxim DS2413 1-Wire Dual Channel Addressable Switch
-
-supported family codes:
- W1_FAMILY_DS2413 0x3A
-
-Author: Mariusz Bialonczyk <manio@skyboo.net>
-
-Description
------------
-
-The DS2413 chip has two open-drain outputs (PIO A and PIO B).
-Support is provided through the sysfs files "output" and "state".
-
-Reading state
--------------
-The "state" file provides one-byte value which is in the same format as for
-the chip PIO_ACCESS_READ command (refer the datasheet for details):
-
-Bit 0: PIOA Pin State
-Bit 1: PIOA Output Latch State
-Bit 2: PIOB Pin State
-Bit 3: PIOB Output Latch State
-Bit 4-7: Complement of Bit 3 to Bit 0 (verified by the kernel module)
-
-This file is readonly.
-
-Writing output
---------------
-You can set the PIO pins using the "output" file.
-It is writable, you can write one-byte value to this sysfs file.
-Similarly the byte format is the same as for the PIO_ACCESS_WRITE command:
-
-Bit 0: PIOA
-Bit 1: PIOB
-Bit 2-7: No matter (driver will set it to "1"s)
-
-
-The chip has some kind of basic protection against transmission errors.
-When reading the state, there is a four complement bits.
-The driver is checking this complement, and when it is wrong then it is
-returning I/O error.
-
-When writing output, the master must repeat the PIO Output Data byte in
-its inverted form and it is waiting for a confirmation.
-If the write is unsuccessful for three times, the write also returns
-I/O error.
diff --git a/Documentation/w1/slaves/w1_ds2413.rst b/Documentation/w1/slaves/w1_ds2413.rst
new file mode 100644
index 0000000..c15bb5b
--- /dev/null
+++ b/Documentation/w1/slaves/w1_ds2413.rst
@@ -0,0 +1,59 @@
+=======================
+Kernel driver w1_ds2413
+=======================
+
+Supported chips:
+
+ * Maxim DS2413 1-Wire Dual Channel Addressable Switch
+
+supported family codes:
+
+ ================ ====
+ W1_FAMILY_DS2413 0x3A
+ ================ ====
+
+Author: Mariusz Bialonczyk <manio@skyboo.net>
+
+Description
+-----------
+
+The DS2413 chip has two open-drain outputs (PIO A and PIO B).
+Support is provided through the sysfs files "output" and "state".
+
+Reading state
+-------------
+The "state" file provides one-byte value which is in the same format as for
+the chip PIO_ACCESS_READ command (refer the datasheet for details):
+
+======== =============================================================
+Bit 0: PIOA Pin State
+Bit 1: PIOA Output Latch State
+Bit 2: PIOB Pin State
+Bit 3: PIOB Output Latch State
+Bit 4-7: Complement of Bit 3 to Bit 0 (verified by the kernel module)
+======== =============================================================
+
+This file is readonly.
+
+Writing output
+--------------
+You can set the PIO pins using the "output" file.
+It is writable, you can write one-byte value to this sysfs file.
+Similarly the byte format is the same as for the PIO_ACCESS_WRITE command:
+
+======== ======================================
+Bit 0: PIOA
+Bit 1: PIOB
+Bit 2-7: No matter (driver will set it to "1"s)
+======== ======================================
+
+
+The chip has some kind of basic protection against transmission errors.
+When reading the state, there is a four complement bits.
+The driver is checking this complement, and when it is wrong then it is
+returning I/O error.
+
+When writing output, the master must repeat the PIO Output Data byte in
+its inverted form and it is waiting for a confirmation.
+If the write is unsuccessful for three times, the write also returns
+I/O error.
diff --git a/Documentation/w1/slaves/w1_ds2423 b/Documentation/w1/slaves/w1_ds2423
deleted file mode 100644
index 3f98b50..0000000
--- a/Documentation/w1/slaves/w1_ds2423
+++ /dev/null
@@ -1,47 +0,0 @@
-Kernel driver w1_ds2423
-=======================
-
-Supported chips:
- * Maxim DS2423 based counter devices.
-
-supported family codes:
- W1_THERM_DS2423 0x1D
-
-Author: Mika Laitio <lamikr@pilppa.org>
-
-Description
------------
-
-Support is provided through the sysfs w1_slave file. Each opening and
-read sequence of w1_slave file initiates the read of counters and ram
-available in DS2423 pages 12 - 15.
-
-Result of each page is provided as an ASCII output where each counter
-value and associated ram buffer is outpputed to own line.
-
-Each lines will contain the values of 42 bytes read from the counter and
-memory page along the crc=YES or NO for indicating whether the read operation
-was successful and CRC matched.
-If the operation was successful, there is also in the end of each line
-a counter value expressed as an integer after c=
-
-Meaning of 42 bytes represented is following:
- - 1 byte from ram page
- - 4 bytes for the counter value
- - 4 zero bytes
- - 2 bytes for crc16 which was calculated from the data read since the previous crc bytes
- - 31 remaining bytes from the ram page
- - crc=YES/NO indicating whether read was ok and crc matched
- - c=<int> current counter value
-
-example from the successful read:
-00 02 00 00 00 00 00 00 00 6d 38 00 ff ff 00 00 fe ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff crc=YES c=2
-00 02 00 00 00 00 00 00 00 e0 1f 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff crc=YES c=2
-00 29 c6 5d 18 00 00 00 00 04 37 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff crc=YES c=408798761
-00 05 00 00 00 00 00 00 00 8d 39 ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff crc=YES c=5
-
-example from the read with crc errors:
-00 02 00 00 00 00 00 00 00 6d 38 00 ff ff 00 00 fe ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff crc=YES c=2
-00 02 00 00 22 00 00 00 00 e0 1f 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff crc=NO
-00 e1 61 5d 19 00 00 00 00 df 0b 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff crc=NO
-00 05 00 00 20 00 00 00 00 8d 39 ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff crc=NO
diff --git a/Documentation/w1/slaves/w1_ds2423.rst b/Documentation/w1/slaves/w1_ds2423.rst
new file mode 100644
index 0000000..755d659
--- /dev/null
+++ b/Documentation/w1/slaves/w1_ds2423.rst
@@ -0,0 +1,54 @@
+Kernel driver w1_ds2423
+=======================
+
+Supported chips:
+
+ * Maxim DS2423 based counter devices.
+
+supported family codes:
+
+ =============== ====
+ W1_THERM_DS2423 0x1D
+ =============== ====
+
+Author: Mika Laitio <lamikr@pilppa.org>
+
+Description
+-----------
+
+Support is provided through the sysfs w1_slave file. Each opening and
+read sequence of w1_slave file initiates the read of counters and ram
+available in DS2423 pages 12 - 15.
+
+Result of each page is provided as an ASCII output where each counter
+value and associated ram buffer is outpputed to own line.
+
+Each lines will contain the values of 42 bytes read from the counter and
+memory page along the crc=YES or NO for indicating whether the read operation
+was successful and CRC matched.
+If the operation was successful, there is also in the end of each line
+a counter value expressed as an integer after c=
+
+Meaning of 42 bytes represented is following:
+
+ - 1 byte from ram page
+ - 4 bytes for the counter value
+ - 4 zero bytes
+ - 2 bytes for crc16 which was calculated from the data read since the previous crc bytes
+ - 31 remaining bytes from the ram page
+ - crc=YES/NO indicating whether read was ok and crc matched
+ - c=<int> current counter value
+
+example from the successful read::
+
+ 00 02 00 00 00 00 00 00 00 6d 38 00 ff ff 00 00 fe ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff crc=YES c=2
+ 00 02 00 00 00 00 00 00 00 e0 1f 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff crc=YES c=2
+ 00 29 c6 5d 18 00 00 00 00 04 37 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff crc=YES c=408798761
+ 00 05 00 00 00 00 00 00 00 8d 39 ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff crc=YES c=5
+
+example from the read with crc errors::
+
+ 00 02 00 00 00 00 00 00 00 6d 38 00 ff ff 00 00 fe ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff crc=YES c=2
+ 00 02 00 00 22 00 00 00 00 e0 1f 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff crc=NO
+ 00 e1 61 5d 19 00 00 00 00 df 0b 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff crc=NO
+ 00 05 00 00 20 00 00 00 00 8d 39 ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff crc=NO
diff --git a/Documentation/w1/slaves/w1_ds2438 b/Documentation/w1/slaves/w1_ds2438
deleted file mode 100644
index e64f65a..0000000
--- a/Documentation/w1/slaves/w1_ds2438
+++ /dev/null
@@ -1,63 +0,0 @@
-Kernel driver w1_ds2438
-=======================
-
-Supported chips:
- * Maxim DS2438 Smart Battery Monitor
-
-supported family codes:
- W1_FAMILY_DS2438 0x26
-
-Author: Mariusz Bialonczyk <manio@skyboo.net>
-
-Description
------------
-
-The DS2438 chip provides several functions that are desirable to carry in
-a battery pack. It also has a 40 bytes of nonvolatile EEPROM.
-Because the ability of temperature, current and voltage measurement, the chip
-is also often used in weather stations and applications such as: rain gauge,
-wind speed/direction measuring, humidity sensing, etc.
-
-Current support is provided through the following sysfs files (all files
-except "iad" are readonly):
-
-"iad"
------
-This file controls the 'Current A/D Control Bit' (IAD) in the
-Status/Configuration Register.
-Writing a zero value will clear the IAD bit and disables the current
-measurements.
-Writing value "1" is setting the IAD bit (enables the measurements).
-The IAD bit is enabled by default in the DS2438.
-
-When writing to sysfs file bits 2-7 are ignored, so it's safe to write ASCII.
-An I/O error is returned when there is a problem setting the new value.
-
-"page0"
--------
-This file provides full 8 bytes of the chip Page 0 (00h).
-This page contains the most frequently accessed information of the DS2438.
-Internally when this file is read, the additional CRC byte is also obtained
-from the slave device. If it is correct, the 8 bytes page data are passed
-to userspace, otherwise an I/O error is returned.
-
-"temperature"
--------------
-Opening and reading this file initiates the CONVERT_T (temperature conversion)
-command of the chip, afterwards the temperature is read from the device
-registers and provided as an ASCII decimal value.
-
-Important: The returned value has to be divided by 256 to get a real
-temperature in degrees Celsius.
-
-"vad", "vdd"
-------------
-Opening and reading this file initiates the CONVERT_V (voltage conversion)
-command of the chip.
-
-Depending on a sysfs filename a different input for the A/D will be selected:
-vad: general purpose A/D input (VAD)
-vdd: battery input (VDD)
-
-After the voltage conversion the value is returned as decimal ASCII.
-Note: To get a volts the value has to be divided by 100.
diff --git a/Documentation/w1/slaves/w1_ds2438.rst b/Documentation/w1/slaves/w1_ds2438.rst
new file mode 100644
index 0000000..a29309a
--- /dev/null
+++ b/Documentation/w1/slaves/w1_ds2438.rst
@@ -0,0 +1,69 @@
+Kernel driver w1_ds2438
+=======================
+
+Supported chips:
+
+ * Maxim DS2438 Smart Battery Monitor
+
+supported family codes:
+ ================ ====
+ W1_FAMILY_DS2438 0x26
+ ================ ====
+
+Author: Mariusz Bialonczyk <manio@skyboo.net>
+
+Description
+-----------
+
+The DS2438 chip provides several functions that are desirable to carry in
+a battery pack. It also has a 40 bytes of nonvolatile EEPROM.
+Because the ability of temperature, current and voltage measurement, the chip
+is also often used in weather stations and applications such as: rain gauge,
+wind speed/direction measuring, humidity sensing, etc.
+
+Current support is provided through the following sysfs files (all files
+except "iad" are readonly):
+
+"iad"
+-----
+This file controls the 'Current A/D Control Bit' (IAD) in the
+Status/Configuration Register.
+Writing a zero value will clear the IAD bit and disables the current
+measurements.
+Writing value "1" is setting the IAD bit (enables the measurements).
+The IAD bit is enabled by default in the DS2438.
+
+When writing to sysfs file bits 2-7 are ignored, so it's safe to write ASCII.
+An I/O error is returned when there is a problem setting the new value.
+
+"page0"
+-------
+This file provides full 8 bytes of the chip Page 0 (00h).
+This page contains the most frequently accessed information of the DS2438.
+Internally when this file is read, the additional CRC byte is also obtained
+from the slave device. If it is correct, the 8 bytes page data are passed
+to userspace, otherwise an I/O error is returned.
+
+"temperature"
+-------------
+Opening and reading this file initiates the CONVERT_T (temperature conversion)
+command of the chip, afterwards the temperature is read from the device
+registers and provided as an ASCII decimal value.
+
+Important: The returned value has to be divided by 256 to get a real
+temperature in degrees Celsius.
+
+"vad", "vdd"
+------------
+Opening and reading this file initiates the CONVERT_V (voltage conversion)
+command of the chip.
+
+Depending on a sysfs filename a different input for the A/D will be selected:
+
+vad:
+ general purpose A/D input (VAD)
+vdd:
+ battery input (VDD)
+
+After the voltage conversion the value is returned as decimal ASCII.
+Note: To get a volts the value has to be divided by 100.
diff --git a/Documentation/w1/slaves/w1_ds28e04 b/Documentation/w1/slaves/w1_ds28e04
deleted file mode 100644
index 7819b65..0000000
--- a/Documentation/w1/slaves/w1_ds28e04
+++ /dev/null
@@ -1,36 +0,0 @@
-Kernel driver w1_ds28e04
-========================
-
-Supported chips:
- * Maxim DS28E04-100 4096-Bit Addressable 1-Wire EEPROM with PIO
-
-supported family codes:
- W1_FAMILY_DS28E04 0x1C
-
-Author: Markus Franke, <franke.m@sebakmt.com> <franm@hrz.tu-chemnitz.de>
-
-Description
------------
-
-Support is provided through the sysfs files "eeprom" and "pio". CRC checking
-during memory accesses can optionally be enabled/disabled via the device
-attribute "crccheck". The strong pull-up can optionally be enabled/disabled
-via the module parameter "w1_strong_pullup".
-
-Memory Access
-
- A read operation on the "eeprom" file reads the given amount of bytes
- from the EEPROM of the DS28E04.
-
- A write operation on the "eeprom" file writes the given byte sequence
- to the EEPROM of the DS28E04. If CRC checking mode is enabled only
- fully aligned blocks of 32 bytes with valid CRC16 values (in bytes 30
- and 31) are allowed to be written.
-
-PIO Access
-
- The 2 PIOs of the DS28E04-100 are accessible via the "pio" sysfs file.
-
- The current status of the PIO's is returned as an 8 bit value. Bit 0/1
- represent the state of PIO_0/PIO_1. Bits 2..7 do not care. The PIO's are
- driven low-active, i.e. the driver delivers/expects low-active values.
diff --git a/Documentation/w1/slaves/w1_ds28e04.rst b/Documentation/w1/slaves/w1_ds28e04.rst
new file mode 100644
index 0000000..b12b118
--- /dev/null
+++ b/Documentation/w1/slaves/w1_ds28e04.rst
@@ -0,0 +1,41 @@
+========================
+Kernel driver w1_ds28e04
+========================
+
+Supported chips:
+
+ * Maxim DS28E04-100 4096-Bit Addressable 1-Wire EEPROM with PIO
+
+supported family codes:
+
+ ================= ====
+ W1_FAMILY_DS28E04 0x1C
+ ================= ====
+
+Author: Markus Franke, <franke.m@sebakmt.com> <franm@hrz.tu-chemnitz.de>
+
+Description
+-----------
+
+Support is provided through the sysfs files "eeprom" and "pio". CRC checking
+during memory accesses can optionally be enabled/disabled via the device
+attribute "crccheck". The strong pull-up can optionally be enabled/disabled
+via the module parameter "w1_strong_pullup".
+
+Memory Access
+
+ A read operation on the "eeprom" file reads the given amount of bytes
+ from the EEPROM of the DS28E04.
+
+ A write operation on the "eeprom" file writes the given byte sequence
+ to the EEPROM of the DS28E04. If CRC checking mode is enabled only
+ fully aligned blocks of 32 bytes with valid CRC16 values (in bytes 30
+ and 31) are allowed to be written.
+
+PIO Access
+
+ The 2 PIOs of the DS28E04-100 are accessible via the "pio" sysfs file.
+
+ The current status of the PIO's is returned as an 8 bit value. Bit 0/1
+ represent the state of PIO_0/PIO_1. Bits 2..7 do not care. The PIO's are
+ driven low-active, i.e. the driver delivers/expects low-active values.
diff --git a/Documentation/w1/slaves/w1_ds28e17 b/Documentation/w1/slaves/w1_ds28e17
deleted file mode 100644
index 7fcfad5..0000000
--- a/Documentation/w1/slaves/w1_ds28e17
+++ /dev/null
@@ -1,68 +0,0 @@
-Kernel driver w1_ds28e17
-========================
-
-Supported chips:
- * Maxim DS28E17 1-Wire-to-I2C Master Bridge
-
-supported family codes:
- W1_FAMILY_DS28E17 0x19
-
-Author: Jan Kandziora <jjj@gmx.de>
-
-
-Description
------------
-The DS28E17 is a Onewire slave device which acts as an I2C bus master.
-
-This driver creates a new I2C bus for any DS28E17 device detected. I2C buses
-come and go as the DS28E17 devices come and go. I2C slave devices connected to
-a DS28E17 can be accessed by the kernel or userspace tools as if they were
-connected to a "native" I2C bus master.
-
-
-An udev rule like the following
--------------------------------------------------------------------------------
-SUBSYSTEM=="i2c-dev", KERNEL=="i2c-[0-9]*", ATTRS{name}=="w1-19-*", \
- SYMLINK+="i2c-$attr{name}"
--------------------------------------------------------------------------------
-may be used to create stable /dev/i2c- entries based on the unique id of the
-DS28E17 chip.
-
-
-Driver parameters are:
-
-speed:
- This sets up the default I2C speed a DS28E17 get configured for as soon
- it is connected. The power-on default of the DS28E17 is 400kBaud, but
- chips may come and go on the Onewire bus without being de-powered and
- as soon the "w1_ds28e17" driver notices a freshly connected, or
- reconnected DS28E17 device on the Onewire bus, it will re-apply this
- setting.
-
- Valid values are 100, 400, 900 [kBaud]. Any other value means to leave
- alone the current DS28E17 setting on detect. The default value is 100.
-
-stretch:
- This sets up the default stretch value used for freshly connected
- DS28E17 devices. It is a multiplier used on the calculation of the busy
- wait time for an I2C transfer. This is to account for I2C slave devices
- which make heavy use of the I2C clock stretching feature and thus, the
- needed timeout cannot be pre-calculated correctly. As the w1_ds28e17
- driver checks the DS28E17's busy flag in a loop after the precalculated
- wait time, it should be hardly needed to tweak this setting.
-
- Leave it at 1 unless you get ETIMEDOUT errors and a "w1_slave_driver
- 19-00000002dbd8: busy timeout" in the kernel log.
-
- Valid values are 1 to 9. The default is 1.
-
-
-The driver creates sysfs files /sys/bus/w1/devices/19-<id>/speed and
-/sys/bus/w1/devices/19-<id>/stretch for each device, preloaded with the default
-settings from the driver parameters. They may be changed anytime. In addition a
-directory /sys/bus/w1/devices/19-<id>/i2c-<nnn> for the I2C bus master sysfs
-structure is created.
-
-
-See https://github.com/ianka/w1_ds28e17 for even more information.
-
diff --git a/Documentation/w1/slaves/w1_ds28e17.rst b/Documentation/w1/slaves/w1_ds28e17.rst
new file mode 100644
index 0000000..e2d9f96d
--- /dev/null
+++ b/Documentation/w1/slaves/w1_ds28e17.rst
@@ -0,0 +1,72 @@
+========================
+Kernel driver w1_ds28e17
+========================
+
+Supported chips:
+
+ * Maxim DS28E17 1-Wire-to-I2C Master Bridge
+
+supported family codes:
+
+ ================= ====
+ W1_FAMILY_DS28E17 0x19
+ ================= ====
+
+Author: Jan Kandziora <jjj@gmx.de>
+
+
+Description
+-----------
+The DS28E17 is a Onewire slave device which acts as an I2C bus master.
+
+This driver creates a new I2C bus for any DS28E17 device detected. I2C buses
+come and go as the DS28E17 devices come and go. I2C slave devices connected to
+a DS28E17 can be accessed by the kernel or userspace tools as if they were
+connected to a "native" I2C bus master.
+
+
+An udev rule like the following::
+
+ SUBSYSTEM=="i2c-dev", KERNEL=="i2c-[0-9]*", ATTRS{name}=="w1-19-*", \
+ SYMLINK+="i2c-$attr{name}"
+
+may be used to create stable /dev/i2c- entries based on the unique id of the
+DS28E17 chip.
+
+
+Driver parameters are:
+
+speed:
+ This sets up the default I2C speed a DS28E17 get configured for as soon
+ it is connected. The power-on default of the DS28E17 is 400kBaud, but
+ chips may come and go on the Onewire bus without being de-powered and
+ as soon the "w1_ds28e17" driver notices a freshly connected, or
+ reconnected DS28E17 device on the Onewire bus, it will re-apply this
+ setting.
+
+ Valid values are 100, 400, 900 [kBaud]. Any other value means to leave
+ alone the current DS28E17 setting on detect. The default value is 100.
+
+stretch:
+ This sets up the default stretch value used for freshly connected
+ DS28E17 devices. It is a multiplier used on the calculation of the busy
+ wait time for an I2C transfer. This is to account for I2C slave devices
+ which make heavy use of the I2C clock stretching feature and thus, the
+ needed timeout cannot be pre-calculated correctly. As the w1_ds28e17
+ driver checks the DS28E17's busy flag in a loop after the precalculated
+ wait time, it should be hardly needed to tweak this setting.
+
+ Leave it at 1 unless you get ETIMEDOUT errors and a "w1_slave_driver
+ 19-00000002dbd8: busy timeout" in the kernel log.
+
+ Valid values are 1 to 9. The default is 1.
+
+
+The driver creates sysfs files /sys/bus/w1/devices/19-<id>/speed and
+/sys/bus/w1/devices/19-<id>/stretch for each device, preloaded with the default
+settings from the driver parameters. They may be changed anytime. In addition a
+directory /sys/bus/w1/devices/19-<id>/i2c-<nnn> for the I2C bus master sysfs
+structure is created.
+
+
+See https://github.com/ianka/w1_ds28e17 for even more information.
diff --git a/Documentation/w1/slaves/w1_therm b/Documentation/w1/slaves/w1_therm
deleted file mode 100644
index d1f93af..0000000
--- a/Documentation/w1/slaves/w1_therm
+++ /dev/null
@@ -1,67 +0,0 @@
-Kernel driver w1_therm
-====================
-
-Supported chips:
- * Maxim ds18*20 based temperature sensors.
- * Maxim ds1825 based temperature sensors.
-
-Author: Evgeniy Polyakov <johnpol@2ka.mipt.ru>
-
-
-Description
------------
-
-w1_therm provides basic temperature conversion for ds18*20 devices, and the
-ds28ea00 device.
-supported family codes:
-W1_THERM_DS18S20 0x10
-W1_THERM_DS1822 0x22
-W1_THERM_DS18B20 0x28
-W1_THERM_DS1825 0x3B
-W1_THERM_DS28EA00 0x42
-
-Support is provided through the sysfs w1_slave file. Each open and
-read sequence will initiate a temperature conversion then provide two
-lines of ASCII output. The first line contains the nine hex bytes
-read along with a calculated crc value and YES or NO if it matched.
-If the crc matched the returned values are retained. The second line
-displays the retained values along with a temperature in millidegrees
-Centigrade after t=.
-
-Parasite powered devices are limited to one slave performing a
-temperature conversion at a time. If none of the devices are parasite
-powered it would be possible to convert all the devices at the same
-time and then go back to read individual sensors. That isn't
-currently supported. The driver also doesn't support reduced
-precision (which would also reduce the conversion time) when reading values.
-
-Writing a value between 9 and 12 to the sysfs w1_slave file will change the
-precision of the sensor for the next readings. This value is in (volatile)
-SRAM, so it is reset when the sensor gets power-cycled.
-
-To store the current precision configuration into EEPROM, the value 0
-has to be written to the sysfs w1_slave file. Since the EEPROM has a limited
-amount of writes (>50k), this command should be used wisely.
-
-The module parameter strong_pullup can be set to 0 to disable the
-strong pullup, 1 to enable autodetection or 2 to force strong pullup.
-In case of autodetection, the driver will use the "READ POWER SUPPLY"
-command to check if there are pariste powered devices on the bus.
-If so, it will activate the master's strong pullup.
-In case the detection of parasite devices using this command fails
-(seems to be the case with some DS18S20) the strong pullup can
-be force-enabled.
-If the strong pullup is enabled, the master's strong pullup will be
-driven when the conversion is taking place, provided the master driver
-does support the strong pullup (or it falls back to a pullup
-resistor). The DS18b20 temperature sensor specification lists a
-maximum current draw of 1.5mA and that a 5k pullup resistor is not
-sufficient. The strong pullup is designed to provide the additional
-current required.
-
-The DS28EA00 provides an additional two pins for implementing a sequence
-detection algorithm. This feature allows you to determine the physical
-location of the chip in the 1-wire bus without needing pre-existing
-knowledge of the bus ordering. Support is provided through the sysfs
-w1_seq file. The file will contain a single line with an integer value
-representing the device index in the bus starting at 0.
diff --git a/Documentation/w1/slaves/w1_therm.rst b/Documentation/w1/slaves/w1_therm.rst
new file mode 100644
index 0000000..90531c3
--- /dev/null
+++ b/Documentation/w1/slaves/w1_therm.rst
@@ -0,0 +1,74 @@
+======================
+Kernel driver w1_therm
+======================
+
+Supported chips:
+
+ * Maxim ds18*20 based temperature sensors.
+ * Maxim ds1825 based temperature sensors.
+
+Author: Evgeniy Polyakov <johnpol@2ka.mipt.ru>
+
+
+Description
+-----------
+
+w1_therm provides basic temperature conversion for ds18*20 devices, and the
+ds28ea00 device.
+
+Supported family codes:
+
+==================== ====
+W1_THERM_DS18S20 0x10
+W1_THERM_DS1822 0x22
+W1_THERM_DS18B20 0x28
+W1_THERM_DS1825 0x3B
+W1_THERM_DS28EA00 0x42
+==================== ====
+
+Support is provided through the sysfs w1_slave file. Each open and
+read sequence will initiate a temperature conversion then provide two
+lines of ASCII output. The first line contains the nine hex bytes
+read along with a calculated crc value and YES or NO if it matched.
+If the crc matched the returned values are retained. The second line
+displays the retained values along with a temperature in millidegrees
+Centigrade after t=.
+
+Parasite powered devices are limited to one slave performing a
+temperature conversion at a time. If none of the devices are parasite
+powered it would be possible to convert all the devices at the same
+time and then go back to read individual sensors. That isn't
+currently supported. The driver also doesn't support reduced
+precision (which would also reduce the conversion time) when reading values.
+
+Writing a value between 9 and 12 to the sysfs w1_slave file will change the
+precision of the sensor for the next readings. This value is in (volatile)
+SRAM, so it is reset when the sensor gets power-cycled.
+
+To store the current precision configuration into EEPROM, the value 0
+has to be written to the sysfs w1_slave file. Since the EEPROM has a limited
+amount of writes (>50k), this command should be used wisely.
+
+The module parameter strong_pullup can be set to 0 to disable the
+strong pullup, 1 to enable autodetection or 2 to force strong pullup.
+In case of autodetection, the driver will use the "READ POWER SUPPLY"
+command to check if there are pariste powered devices on the bus.
+If so, it will activate the master's strong pullup.
+In case the detection of parasite devices using this command fails
+(seems to be the case with some DS18S20) the strong pullup can
+be force-enabled.
+
+If the strong pullup is enabled, the master's strong pullup will be
+driven when the conversion is taking place, provided the master driver
+does support the strong pullup (or it falls back to a pullup
+resistor). The DS18b20 temperature sensor specification lists a
+maximum current draw of 1.5mA and that a 5k pullup resistor is not
+sufficient. The strong pullup is designed to provide the additional
+current required.
+
+The DS28EA00 provides an additional two pins for implementing a sequence
+detection algorithm. This feature allows you to determine the physical
+location of the chip in the 1-wire bus without needing pre-existing
+knowledge of the bus ordering. Support is provided through the sysfs
+w1_seq file. The file will contain a single line with an integer value
+representing the device index in the bus starting at 0.
diff --git a/Documentation/w1/w1-generic.rst b/Documentation/w1/w1-generic.rst
new file mode 100644
index 0000000..da4e8b4
--- /dev/null
+++ b/Documentation/w1/w1-generic.rst
@@ -0,0 +1,133 @@
+=========================================
+Introduction to the 1-wire (w1) subsystem
+=========================================
+
+The 1-wire bus is a simple master-slave bus that communicates via a single
+signal wire (plus ground, so two wires).
+
+Devices communicate on the bus by pulling the signal to ground via an open
+drain output and by sampling the logic level of the signal line.
+
+The w1 subsystem provides the framework for managing w1 masters and
+communication with slaves.
+
+All w1 slave devices must be connected to a w1 bus master device.
+
+Example w1 master devices:
+
+ - DS9490 usb device
+ - W1-over-GPIO
+ - DS2482 (i2c to w1 bridge)
+ - Emulated devices, such as a RS232 converter, parallel port adapter, etc
+
+
+What does the w1 subsystem do?
+------------------------------
+
+When a w1 master driver registers with the w1 subsystem, the following occurs:
+
+ - sysfs entries for that w1 master are created
+ - the w1 bus is periodically searched for new slave devices
+
+When a device is found on the bus, w1 core tries to load the driver for its family
+and check if it is loaded. If so, the family driver is attached to the slave.
+If there is no driver for the family, default one is assigned, which allows to perform
+almost any kind of operations. Each logical operation is a transaction
+in nature, which can contain several (two or one) low-level operations.
+Let's see how one can read EEPROM context:
+1. one must write control buffer, i.e. buffer containing command byte
+and two byte address. At this step bus is reset and appropriate device
+is selected using either W1_SKIP_ROM or W1_MATCH_ROM command.
+Then provided control buffer is being written to the wire.
+2. reading. This will issue reading eeprom response.
+
+It is possible that between 1. and 2. w1 master thread will reset bus for searching
+and slave device will be even removed, but in this case 0xff will
+be read, since no device was selected.
+
+
+W1 device families
+------------------
+
+Slave devices are handled by a driver written for a family of w1 devices.
+
+A family driver populates a struct w1_family_ops (see w1_family.h) and
+registers with the w1 subsystem.
+
+Current family drivers:
+
+w1_therm
+ - (ds18?20 thermal sensor family driver)
+ provides temperature reading function which is bound to ->rbin() method
+ of the above w1_family_ops structure.
+
+w1_smem
+ - driver for simple 64bit memory cell provides ID reading method.
+
+You can call above methods by reading appropriate sysfs files.
+
+
+What does a w1 master driver need to implement?
+-----------------------------------------------
+
+The driver for w1 bus master must provide at minimum two functions.
+
+Emulated devices must provide the ability to set the output signal level
+(write_bit) and sample the signal level (read_bit).
+
+Devices that support the 1-wire natively must provide the ability to write and
+sample a bit (touch_bit) and reset the bus (reset_bus).
+
+Most hardware provides higher-level functions that offload w1 handling.
+See struct w1_bus_master definition in w1.h for details.
+
+
+w1 master sysfs interface
+-------------------------
+
+========================= =====================================================
+<xx-xxxxxxxxxxxx> A directory for a found device. The format is
+ family-serial
+bus (standard) symlink to the w1 bus
+driver (standard) symlink to the w1 driver
+w1_master_add (rw) manually register a slave device
+w1_master_attempts (ro) the number of times a search was attempted
+w1_master_max_slave_count (rw) maximum number of slaves to search for at a time
+w1_master_name (ro) the name of the device (w1_bus_masterX)
+w1_master_pullup (rw) 5V strong pullup 0 enabled, 1 disabled
+w1_master_remove (rw) manually remove a slave device
+w1_master_search (rw) the number of searches left to do,
+ -1=continual (default)
+w1_master_slave_count (ro) the number of slaves found
+w1_master_slaves (ro) the names of the slaves, one per line
+w1_master_timeout (ro) the delay in seconds between searches
+w1_master_timeout_us (ro) the delay in microseconds beetwen searches
+========================= =====================================================
+
+If you have a w1 bus that never changes (you don't add or remove devices),
+you can set the module parameter search_count to a small positive number
+for an initially small number of bus searches. Alternatively it could be
+set to zero, then manually add the slave device serial numbers by
+w1_master_add device file. The w1_master_add and w1_master_remove files
+generally only make sense when searching is disabled, as a search will
+redetect manually removed devices that are present and timeout manually
+added devices that aren't on the bus.
+
+Bus searches occur at an interval, specified as a summ of timeout and
+timeout_us module parameters (either of which may be 0) for as long as
+w1_master_search remains greater than 0 or is -1. Each search attempt
+decrements w1_master_search by 1 (down to 0) and increments
+w1_master_attempts by 1.
+
+w1 slave sysfs interface
+------------------------
+
+=================== ============================================================
+bus (standard) symlink to the w1 bus
+driver (standard) symlink to the w1 driver
+name the device name, usually the same as the directory name
+w1_slave (optional) a binary file whose meaning depends on the
+ family driver
+rw (optional) created for slave devices which do not have
+ appropriate family driver. Allows to read/write binary data.
+=================== ============================================================
diff --git a/Documentation/w1/w1-netlink.rst b/Documentation/w1/w1-netlink.rst
new file mode 100644
index 0000000..aaa1324
--- /dev/null
+++ b/Documentation/w1/w1-netlink.rst
@@ -0,0 +1,202 @@
+===============================================
+Userspace communication protocol over connector
+===============================================
+
+Message types
+=============
+
+There are three types of messages between w1 core and userspace:
+
+1. Events. They are generated each time a new master or slave device
+ is found either due to automatic or requested search.
+2. Userspace commands.
+3. Replies to userspace commands.
+
+
+Protocol
+========
+
+::
+
+ [struct cn_msg] - connector header.
+ Its length field is equal to size of the attached data
+ [struct w1_netlink_msg] - w1 netlink header.
+ __u8 type - message type.
+ W1_LIST_MASTERS
+ list current bus masters
+ W1_SLAVE_ADD/W1_SLAVE_REMOVE
+ slave add/remove events
+ W1_MASTER_ADD/W1_MASTER_REMOVE
+ master add/remove events
+ W1_MASTER_CMD
+ userspace command for bus master
+ device (search/alarm search)
+ W1_SLAVE_CMD
+ userspace command for slave device
+ (read/write/touch)
+ __u8 status - error indication from kernel
+ __u16 len - size of data attached to this header data
+ union {
+ __u8 id[8]; - slave unique device id
+ struct w1_mst {
+ __u32 id; - master's id
+ __u32 res; - reserved
+ } mst;
+ } id;
+
+ [struct w1_netlink_cmd] - command for given master or slave device.
+ __u8 cmd - command opcode.
+ W1_CMD_READ - read command
+ W1_CMD_WRITE - write command
+ W1_CMD_SEARCH - search command
+ W1_CMD_ALARM_SEARCH - alarm search command
+ W1_CMD_TOUCH - touch command
+ (write and sample data back to userspace)
+ W1_CMD_RESET - send bus reset
+ W1_CMD_SLAVE_ADD - add slave to kernel list
+ W1_CMD_SLAVE_REMOVE - remove slave from kernel list
+ W1_CMD_LIST_SLAVES - get slaves list from kernel
+ __u8 res - reserved
+ __u16 len - length of data for this command
+ For read command data must be allocated like for write command
+ __u8 data[0] - data for this command
+
+
+Each connector message can include one or more w1_netlink_msg with
+zero or more attached w1_netlink_cmd messages.
+
+For event messages there are no w1_netlink_cmd embedded structures,
+only connector header and w1_netlink_msg strucutre with "len" field
+being zero and filled type (one of event types) and id:
+either 8 bytes of slave unique id in host order,
+or master's id, which is assigned to bus master device
+when it is added to w1 core.
+
+Currently replies to userspace commands are only generated for read
+command request. One reply is generated exactly for one w1_netlink_cmd
+read request. Replies are not combined when sent - i.e. typical reply
+messages looks like the following::
+
+ [cn_msg][w1_netlink_msg][w1_netlink_cmd]
+ cn_msg.len = sizeof(struct w1_netlink_msg) +
+ sizeof(struct w1_netlink_cmd) +
+ cmd->len;
+ w1_netlink_msg.len = sizeof(struct w1_netlink_cmd) + cmd->len;
+ w1_netlink_cmd.len = cmd->len;
+
+Replies to W1_LIST_MASTERS should send a message back to the userspace
+which will contain list of all registered master ids in the following
+format::
+
+ cn_msg (CN_W1_IDX.CN_W1_VAL as id, len is equal to sizeof(struct
+ w1_netlink_msg) plus number of masters multiplied by 4)
+ w1_netlink_msg (type: W1_LIST_MASTERS, len is equal to
+ number of masters multiplied by 4 (u32 size))
+ id0 ... idN
+
+Each message is at most 4k in size, so if number of master devices
+exceeds this, it will be split into several messages.
+
+W1 search and alarm search commands.
+
+request::
+
+ [cn_msg]
+ [w1_netlink_msg type = W1_MASTER_CMD
+ id is equal to the bus master id to use for searching]
+ [w1_netlink_cmd cmd = W1_CMD_SEARCH or W1_CMD_ALARM_SEARCH]
+
+reply::
+
+ [cn_msg, ack = 1 and increasing, 0 means the last message,
+ seq is equal to the request seq]
+ [w1_netlink_msg type = W1_MASTER_CMD]
+ [w1_netlink_cmd cmd = W1_CMD_SEARCH or W1_CMD_ALARM_SEARCH
+ len is equal to number of IDs multiplied by 8]
+ [64bit-id0 ... 64bit-idN]
+
+Length in each header corresponds to the size of the data behind it, so
+w1_netlink_cmd->len = N * 8; where N is number of IDs in this message.
+Can be zero.
+
+::
+
+ w1_netlink_msg->len = sizeof(struct w1_netlink_cmd) + N * 8;
+ cn_msg->len = sizeof(struct w1_netlink_msg) +
+ sizeof(struct w1_netlink_cmd) +
+ N*8;
+
+W1 reset command::
+
+ [cn_msg]
+ [w1_netlink_msg type = W1_MASTER_CMD
+ id is equal to the bus master id to use for searching]
+ [w1_netlink_cmd cmd = W1_CMD_RESET]
+
+
+Command status replies
+======================
+
+Each command (either root, master or slave with or without w1_netlink_cmd
+structure) will be 'acked' by the w1 core. Format of the reply is the same
+as request message except that length parameters do not account for data
+requested by the user, i.e. read/write/touch IO requests will not contain
+data, so w1_netlink_cmd.len will be 0, w1_netlink_msg.len will be size
+of the w1_netlink_cmd structure and cn_msg.len will be equal to the sum
+of the sizeof(struct w1_netlink_msg) and sizeof(struct w1_netlink_cmd).
+If reply is generated for master or root command (which do not have
+w1_netlink_cmd attached), reply will contain only cn_msg and w1_netlink_msg
+structures.
+
+w1_netlink_msg.status field will carry positive error value
+(EINVAL for example) or zero in case of success.
+
+All other fields in every structure will mirror the same parameters in the
+request message (except lengths as described above).
+
+Status reply is generated for every w1_netlink_cmd embedded in the
+w1_netlink_msg, if there are no w1_netlink_cmd structures,
+reply will be generated for the w1_netlink_msg.
+
+All w1_netlink_cmd command structures are handled in every w1_netlink_msg,
+even if there were errors, only length mismatch interrupts message processing.
+
+
+Operation steps in w1 core when new command is received
+=======================================================
+
+When new message (w1_netlink_msg) is received w1 core detects if it is
+master or slave request, according to w1_netlink_msg.type field.
+Then master or slave device is searched for.
+When found, master device (requested or those one on where slave device
+is found) is locked. If slave command is requested, then reset/select
+procedure is started to select given device.
+
+Then all requested in w1_netlink_msg operations are performed one by one.
+If command requires reply (like read command) it is sent on command completion.
+
+When all commands (w1_netlink_cmd) are processed master device is unlocked
+and next w1_netlink_msg header processing started.
+
+
+Connector [1] specific documentation
+====================================
+
+Each connector message includes two u32 fields as "address".
+w1 uses CN_W1_IDX and CN_W1_VAL defined in include/linux/connector.h header.
+Each message also includes sequence and acknowledge numbers.
+Sequence number for event messages is appropriate bus master sequence number
+increased with each event message sent "through" this master.
+Sequence number for userspace requests is set by userspace application.
+Sequence number for reply is the same as was in request, and
+acknowledge number is set to seq+1.
+
+
+Additional documentation, source code examples
+==============================================
+
+1. Documentation/driver-api/connector.rst
+2. http://www.ioremap.net/archive/w1
+
+ This archive includes userspace application w1d.c which uses
+ read/write/search commands for all master/slave devices found on the bus.
diff --git a/Documentation/w1/w1.generic b/Documentation/w1/w1.generic
deleted file mode 100644
index c51b1ab..0000000
--- a/Documentation/w1/w1.generic
+++ /dev/null
@@ -1,121 +0,0 @@
-The 1-wire (w1) subsystem
-------------------------------------------------------------------
-The 1-wire bus is a simple master-slave bus that communicates via a single
-signal wire (plus ground, so two wires).
-
-Devices communicate on the bus by pulling the signal to ground via an open
-drain output and by sampling the logic level of the signal line.
-
-The w1 subsystem provides the framework for managing w1 masters and
-communication with slaves.
-
-All w1 slave devices must be connected to a w1 bus master device.
-
-Example w1 master devices:
- DS9490 usb device
- W1-over-GPIO
- DS2482 (i2c to w1 bridge)
- Emulated devices, such as a RS232 converter, parallel port adapter, etc
-
-
-What does the w1 subsystem do?
-------------------------------------------------------------------
-When a w1 master driver registers with the w1 subsystem, the following occurs:
-
- - sysfs entries for that w1 master are created
- - the w1 bus is periodically searched for new slave devices
-
-When a device is found on the bus, w1 core tries to load the driver for its family
-and check if it is loaded. If so, the family driver is attached to the slave.
-If there is no driver for the family, default one is assigned, which allows to perform
-almost any kind of operations. Each logical operation is a transaction
-in nature, which can contain several (two or one) low-level operations.
-Let's see how one can read EEPROM context:
-1. one must write control buffer, i.e. buffer containing command byte
-and two byte address. At this step bus is reset and appropriate device
-is selected using either W1_SKIP_ROM or W1_MATCH_ROM command.
-Then provided control buffer is being written to the wire.
-2. reading. This will issue reading eeprom response.
-
-It is possible that between 1. and 2. w1 master thread will reset bus for searching
-and slave device will be even removed, but in this case 0xff will
-be read, since no device was selected.
-
-
-W1 device families
-------------------------------------------------------------------
-Slave devices are handled by a driver written for a family of w1 devices.
-
-A family driver populates a struct w1_family_ops (see w1_family.h) and
-registers with the w1 subsystem.
-
-Current family drivers:
-w1_therm - (ds18?20 thermal sensor family driver)
- provides temperature reading function which is bound to ->rbin() method
- of the above w1_family_ops structure.
-
-w1_smem - driver for simple 64bit memory cell provides ID reading method.
-
-You can call above methods by reading appropriate sysfs files.
-
-
-What does a w1 master driver need to implement?
-------------------------------------------------------------------
-
-The driver for w1 bus master must provide at minimum two functions.
-
-Emulated devices must provide the ability to set the output signal level
-(write_bit) and sample the signal level (read_bit).
-
-Devices that support the 1-wire natively must provide the ability to write and
-sample a bit (touch_bit) and reset the bus (reset_bus).
-
-Most hardware provides higher-level functions that offload w1 handling.
-See struct w1_bus_master definition in w1.h for details.
-
-
-w1 master sysfs interface
-------------------------------------------------------------------
-<xx-xxxxxxxxxxxx> - A directory for a found device. The format is family-serial
-bus - (standard) symlink to the w1 bus
-driver - (standard) symlink to the w1 driver
-w1_master_add - (rw) manually register a slave device
-w1_master_attempts - (ro) the number of times a search was attempted
-w1_master_max_slave_count
- - (rw) maximum number of slaves to search for at a time
-w1_master_name - (ro) the name of the device (w1_bus_masterX)
-w1_master_pullup - (rw) 5V strong pullup 0 enabled, 1 disabled
-w1_master_remove - (rw) manually remove a slave device
-w1_master_search - (rw) the number of searches left to do,
- -1=continual (default)
-w1_master_slave_count
- - (ro) the number of slaves found
-w1_master_slaves - (ro) the names of the slaves, one per line
-w1_master_timeout - (ro) the delay in seconds between searches
-w1_master_timeout_us
- - (ro) the delay in microseconds beetwen searches
-
-If you have a w1 bus that never changes (you don't add or remove devices),
-you can set the module parameter search_count to a small positive number
-for an initially small number of bus searches. Alternatively it could be
-set to zero, then manually add the slave device serial numbers by
-w1_master_add device file. The w1_master_add and w1_master_remove files
-generally only make sense when searching is disabled, as a search will
-redetect manually removed devices that are present and timeout manually
-added devices that aren't on the bus.
-
-Bus searches occur at an interval, specified as a summ of timeout and
-timeout_us module parameters (either of which may be 0) for as long as
-w1_master_search remains greater than 0 or is -1. Each search attempt
-decrements w1_master_search by 1 (down to 0) and increments
-w1_master_attempts by 1.
-
-w1 slave sysfs interface
-------------------------------------------------------------------
-bus - (standard) symlink to the w1 bus
-driver - (standard) symlink to the w1 driver
-name - the device name, usually the same as the directory name
-w1_slave - (optional) a binary file whose meaning depends on the
- family driver
-rw - (optional) created for slave devices which do not have
- appropriate family driver. Allows to read/write binary data.
diff --git a/Documentation/w1/w1.netlink b/Documentation/w1/w1.netlink
deleted file mode 100644
index 94ad4c4..0000000
--- a/Documentation/w1/w1.netlink
+++ /dev/null
@@ -1,189 +0,0 @@
-Userspace communication protocol over connector [1].
-
-
-Message types.
-=============
-
-There are three types of messages between w1 core and userspace:
-1. Events. They are generated each time a new master or slave device
- is found either due to automatic or requested search.
-2. Userspace commands.
-3. Replies to userspace commands.
-
-
-Protocol.
-========
-
-[struct cn_msg] - connector header.
- Its length field is equal to size of the attached data
-[struct w1_netlink_msg] - w1 netlink header.
- __u8 type - message type.
- W1_LIST_MASTERS
- list current bus masters
- W1_SLAVE_ADD/W1_SLAVE_REMOVE
- slave add/remove events
- W1_MASTER_ADD/W1_MASTER_REMOVE
- master add/remove events
- W1_MASTER_CMD
- userspace command for bus master
- device (search/alarm search)
- W1_SLAVE_CMD
- userspace command for slave device
- (read/write/touch)
- __u8 status - error indication from kernel
- __u16 len - size of data attached to this header data
- union {
- __u8 id[8]; - slave unique device id
- struct w1_mst {
- __u32 id; - master's id
- __u32 res; - reserved
- } mst;
- } id;
-
-[struct w1_netlink_cmd] - command for given master or slave device.
- __u8 cmd - command opcode.
- W1_CMD_READ - read command
- W1_CMD_WRITE - write command
- W1_CMD_SEARCH - search command
- W1_CMD_ALARM_SEARCH - alarm search command
- W1_CMD_TOUCH - touch command
- (write and sample data back to userspace)
- W1_CMD_RESET - send bus reset
- W1_CMD_SLAVE_ADD - add slave to kernel list
- W1_CMD_SLAVE_REMOVE - remove slave from kernel list
- W1_CMD_LIST_SLAVES - get slaves list from kernel
- __u8 res - reserved
- __u16 len - length of data for this command
- For read command data must be allocated like for write command
- __u8 data[0] - data for this command
-
-
-Each connector message can include one or more w1_netlink_msg with
-zero or more attached w1_netlink_cmd messages.
-
-For event messages there are no w1_netlink_cmd embedded structures,
-only connector header and w1_netlink_msg strucutre with "len" field
-being zero and filled type (one of event types) and id:
-either 8 bytes of slave unique id in host order,
-or master's id, which is assigned to bus master device
-when it is added to w1 core.
-
-Currently replies to userspace commands are only generated for read
-command request. One reply is generated exactly for one w1_netlink_cmd
-read request. Replies are not combined when sent - i.e. typical reply
-messages looks like the following:
-
-[cn_msg][w1_netlink_msg][w1_netlink_cmd]
-cn_msg.len = sizeof(struct w1_netlink_msg) +
- sizeof(struct w1_netlink_cmd) +
- cmd->len;
-w1_netlink_msg.len = sizeof(struct w1_netlink_cmd) + cmd->len;
-w1_netlink_cmd.len = cmd->len;
-
-Replies to W1_LIST_MASTERS should send a message back to the userspace
-which will contain list of all registered master ids in the following
-format:
-
- cn_msg (CN_W1_IDX.CN_W1_VAL as id, len is equal to sizeof(struct
- w1_netlink_msg) plus number of masters multiplied by 4)
- w1_netlink_msg (type: W1_LIST_MASTERS, len is equal to
- number of masters multiplied by 4 (u32 size))
- id0 ... idN
-
- Each message is at most 4k in size, so if number of master devices
- exceeds this, it will be split into several messages.
-
-W1 search and alarm search commands.
-request:
-[cn_msg]
- [w1_netlink_msg type = W1_MASTER_CMD
- id is equal to the bus master id to use for searching]
- [w1_netlink_cmd cmd = W1_CMD_SEARCH or W1_CMD_ALARM_SEARCH]
-
-reply:
- [cn_msg, ack = 1 and increasing, 0 means the last message,
- seq is equal to the request seq]
- [w1_netlink_msg type = W1_MASTER_CMD]
- [w1_netlink_cmd cmd = W1_CMD_SEARCH or W1_CMD_ALARM_SEARCH
- len is equal to number of IDs multiplied by 8]
- [64bit-id0 ... 64bit-idN]
-Length in each header corresponds to the size of the data behind it, so
-w1_netlink_cmd->len = N * 8; where N is number of IDs in this message.
- Can be zero.
-w1_netlink_msg->len = sizeof(struct w1_netlink_cmd) + N * 8;
-cn_msg->len = sizeof(struct w1_netlink_msg) +
- sizeof(struct w1_netlink_cmd) +
- N*8;
-
-W1 reset command.
-[cn_msg]
- [w1_netlink_msg type = W1_MASTER_CMD
- id is equal to the bus master id to use for searching]
- [w1_netlink_cmd cmd = W1_CMD_RESET]
-
-
-Command status replies.
-======================
-
-Each command (either root, master or slave with or without w1_netlink_cmd
-structure) will be 'acked' by the w1 core. Format of the reply is the same
-as request message except that length parameters do not account for data
-requested by the user, i.e. read/write/touch IO requests will not contain
-data, so w1_netlink_cmd.len will be 0, w1_netlink_msg.len will be size
-of the w1_netlink_cmd structure and cn_msg.len will be equal to the sum
-of the sizeof(struct w1_netlink_msg) and sizeof(struct w1_netlink_cmd).
-If reply is generated for master or root command (which do not have
-w1_netlink_cmd attached), reply will contain only cn_msg and w1_netlink_msg
-structures.
-
-w1_netlink_msg.status field will carry positive error value
-(EINVAL for example) or zero in case of success.
-
-All other fields in every structure will mirror the same parameters in the
-request message (except lengths as described above).
-
-Status reply is generated for every w1_netlink_cmd embedded in the
-w1_netlink_msg, if there are no w1_netlink_cmd structures,
-reply will be generated for the w1_netlink_msg.
-
-All w1_netlink_cmd command structures are handled in every w1_netlink_msg,
-even if there were errors, only length mismatch interrupts message processing.
-
-
-Operation steps in w1 core when new command is received.
-=======================================================
-
-When new message (w1_netlink_msg) is received w1 core detects if it is
-master or slave request, according to w1_netlink_msg.type field.
-Then master or slave device is searched for.
-When found, master device (requested or those one on where slave device
-is found) is locked. If slave command is requested, then reset/select
-procedure is started to select given device.
-
-Then all requested in w1_netlink_msg operations are performed one by one.
-If command requires reply (like read command) it is sent on command completion.
-
-When all commands (w1_netlink_cmd) are processed master device is unlocked
-and next w1_netlink_msg header processing started.
-
-
-Connector [1] specific documentation.
-====================================
-
-Each connector message includes two u32 fields as "address".
-w1 uses CN_W1_IDX and CN_W1_VAL defined in include/linux/connector.h header.
-Each message also includes sequence and acknowledge numbers.
-Sequence number for event messages is appropriate bus master sequence number
-increased with each event message sent "through" this master.
-Sequence number for userspace requests is set by userspace application.
-Sequence number for reply is the same as was in request, and
-acknowledge number is set to seq+1.
-
-
-Additional documantion, source code examples.
-============================================
-
-1. Documentation/driver-api/connector.rst
-2. http://www.ioremap.net/archive/w1
-This archive includes userspace application w1d.c which uses
-read/write/search commands for all master/slave devices found on the bus.
diff --git a/Documentation/watchdog/watchdog-parameters.rst b/Documentation/watchdog/watchdog-parameters.rst
index a3985cc..223c993 100644
--- a/Documentation/watchdog/watchdog-parameters.rst
+++ b/Documentation/watchdog/watchdog-parameters.rst
@@ -301,15 +301,6 @@
-------------------------------------------------
-ks8695_wdt:
- 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
@@ -375,16 +366,6 @@
-------------------------------------------------
-nuc900_wdt:
- heartbeat:
- Watchdog heartbeats in seconds.
- (default = 15)
- nowayout:
- Watchdog cannot be stopped once started
- (default=kernel config parameter)
-
--------------------------------------------------
-
omap_wdt:
timer_margin:
initial watchdog timeout (in seconds)
diff --git a/Documentation/wimax/README.i2400m b/Documentation/wimax/README.i2400m
deleted file mode 100644
index 7dffd89..0000000
--- a/Documentation/wimax/README.i2400m
+++ /dev/null
@@ -1,260 +0,0 @@
-
- Driver for the Intel Wireless Wimax Connection 2400m
-
- (C) 2008 Intel Corporation < linux-wimax@intel.com >
-
- This provides a driver for the Intel Wireless WiMAX Connection 2400m
- and a basic Linux kernel WiMAX stack.
-
-1. Requirements
-
- * Linux installation with Linux kernel 2.6.22 or newer (if building
- from a separate tree)
- * Intel i2400m Echo Peak or Baxter Peak; this includes the Intel
- Wireless WiMAX/WiFi Link 5x50 series.
- * build tools:
- + Linux kernel development package for the target kernel; to
- build against your currently running kernel, you need to have
- the kernel development package corresponding to the running
- image installed (usually if your kernel is named
- linux-VERSION, the development package is called
- linux-dev-VERSION or linux-headers-VERSION).
- + GNU C Compiler, make
-
-2. Compilation and installation
-
-2.1. Compilation of the drivers included in the kernel
-
- Configure the kernel; to enable the WiMAX drivers select Drivers >
- Networking Drivers > WiMAX device support. Enable all of them as
- modules (easier).
-
- If USB or SDIO are not enabled in the kernel configuration, the options
- to build the i2400m USB or SDIO drivers will not show. Enable said
- subsystems and go back to the WiMAX menu to enable the drivers.
-
- Compile and install your kernel as usual.
-
-2.2. Compilation of the drivers distributed as an standalone module
-
- To compile
-
-$ cd source/directory
-$ make
-
- Once built you can load and unload using the provided load.sh script;
- load.sh will load the modules, load.sh u will unload them.
-
- To install in the default kernel directories (and enable auto loading
- when the device is plugged):
-
-$ make install
-$ depmod -a
-
- If your kernel development files are located in a non standard
- directory or if you want to build for a kernel that is not the
- currently running one, set KDIR to the right location:
-
-$ make KDIR=/path/to/kernel/dev/tree
-
- For more information, please contact linux-wimax@intel.com.
-
-3. Installing the firmware
-
- The firmware can be obtained from http://linuxwimax.org or might have
- been supplied with your hardware.
-
- It has to be installed in the target system:
- *
-$ cp FIRMWAREFILE.sbcf /lib/firmware/i2400m-fw-BUSTYPE-1.3.sbcf
-
- * NOTE: if your firmware came in an .rpm or .deb file, just install
- it as normal, with the rpm (rpm -i FIRMWARE.rpm) or dpkg
- (dpkg -i FIRMWARE.deb) commands. No further action is needed.
- * BUSTYPE will be usb or sdio, depending on the hardware you have.
- Each hardware type comes with its own firmware and will not work
- with other types.
-
-4. Design
-
- This package contains two major parts: a WiMAX kernel stack and a
- driver for the Intel i2400m.
-
- The WiMAX stack is designed to provide for common WiMAX control
- services to current and future WiMAX devices from any vendor; please
- see README.wimax for details.
-
- The i2400m kernel driver is broken up in two main parts: the bus
- generic driver and the bus-specific drivers. The bus generic driver
- forms the drivercore and contain no knowledge of the actual method we
- use to connect to the device. The bus specific drivers are just the
- glue to connect the bus-generic driver and the device. Currently only
- USB and SDIO are supported. See drivers/net/wimax/i2400m/i2400m.h for
- more information.
-
- The bus generic driver is logically broken up in two parts: OS-glue and
- hardware-glue. The OS-glue interfaces with Linux. The hardware-glue
- interfaces with the device on using an interface provided by the
- bus-specific driver. The reason for this breakup is to be able to
- easily reuse the hardware-glue to write drivers for other OSes; note
- the hardware glue part is written as a native Linux driver; no
- abstraction layers are used, so to port to another OS, the Linux kernel
- API calls should be replaced with the target OS's.
-
-5. Usage
-
- To load the driver, follow the instructions in the install section;
- once the driver is loaded, plug in the device (unless it is permanently
- plugged in). The driver will enumerate the device, upload the firmware
- and output messages in the kernel log (dmesg, /var/log/messages or
- /var/log/kern.log) such as:
-
-...
-i2400m_usb 5-4:1.0: firmware interface version 8.0.0
-i2400m_usb 5-4:1.0: WiMAX interface wmx0 (00:1d:e1:01:94:2c) ready
-
- At this point the device is ready to work.
-
- Current versions require the Intel WiMAX Network Service in userspace
- to make things work. See the network service's README for instructions
- on how to scan, connect and disconnect.
-
-5.1. Module parameters
-
- Module parameters can be set at kernel or module load time or by
- echoing values:
-
-$ echo VALUE > /sys/module/MODULENAME/parameters/PARAMETERNAME
-
- To make changes permanent, for example, for the i2400m module, you can
- also create a file named /etc/modprobe.d/i2400m containing:
-
-options i2400m idle_mode_disabled=1
-
- To find which parameters are supported by a module, run:
-
-$ modinfo path/to/module.ko
-
- During kernel bootup (if the driver is linked in the kernel), specify
- the following to the kernel command line:
-
-i2400m.PARAMETER=VALUE
-
-5.1.1. i2400m: idle_mode_disabled
-
- The i2400m module supports a parameter to disable idle mode. This
- parameter, once set, will take effect only when the device is
- reinitialized by the driver (eg: following a reset or a reconnect).
-
-5.2. Debug operations: debugfs entries
-
- The driver will register debugfs entries that allow the user to tweak
- debug settings. There are three main container directories where
- entries are placed, which correspond to the three blocks a i2400m WiMAX
- driver has:
- * /sys/kernel/debug/wimax:DEVNAME/ for the generic WiMAX stack
- controls
- * /sys/kernel/debug/wimax:DEVNAME/i2400m for the i2400m generic
- driver controls
- * /sys/kernel/debug/wimax:DEVNAME/i2400m-usb (or -sdio) for the
- bus-specific i2400m-usb or i2400m-sdio controls).
-
- Of course, if debugfs is mounted in a directory other than
- /sys/kernel/debug, those paths will change.
-
-5.2.1. Increasing debug output
-
- The files named *dl_* indicate knobs for controlling the debug output
- of different submodules:
- *
-# find /sys/kernel/debug/wimax\:wmx0 -name \*dl_\*
-/sys/kernel/debug/wimax:wmx0/i2400m-usb/dl_tx
-/sys/kernel/debug/wimax:wmx0/i2400m-usb/dl_rx
-/sys/kernel/debug/wimax:wmx0/i2400m-usb/dl_notif
-/sys/kernel/debug/wimax:wmx0/i2400m-usb/dl_fw
-/sys/kernel/debug/wimax:wmx0/i2400m-usb/dl_usb
-/sys/kernel/debug/wimax:wmx0/i2400m/dl_tx
-/sys/kernel/debug/wimax:wmx0/i2400m/dl_rx
-/sys/kernel/debug/wimax:wmx0/i2400m/dl_rfkill
-/sys/kernel/debug/wimax:wmx0/i2400m/dl_netdev
-/sys/kernel/debug/wimax:wmx0/i2400m/dl_fw
-/sys/kernel/debug/wimax:wmx0/i2400m/dl_debugfs
-/sys/kernel/debug/wimax:wmx0/i2400m/dl_driver
-/sys/kernel/debug/wimax:wmx0/i2400m/dl_control
-/sys/kernel/debug/wimax:wmx0/wimax_dl_stack
-/sys/kernel/debug/wimax:wmx0/wimax_dl_op_rfkill
-/sys/kernel/debug/wimax:wmx0/wimax_dl_op_reset
-/sys/kernel/debug/wimax:wmx0/wimax_dl_op_msg
-/sys/kernel/debug/wimax:wmx0/wimax_dl_id_table
-/sys/kernel/debug/wimax:wmx0/wimax_dl_debugfs
-
- By reading the file you can obtain the current value of said debug
- level; by writing to it, you can set it.
-
- To increase the debug level of, for example, the i2400m's generic TX
- engine, just write:
-
-$ echo 3 > /sys/kernel/debug/wimax:wmx0/i2400m/dl_tx
-
- Increasing numbers yield increasing debug information; for details of
- what is printed and the available levels, check the source. The code
- uses 0 for disabled and increasing values until 8.
-
-5.2.2. RX and TX statistics
-
- The i2400m/rx_stats and i2400m/tx_stats provide statistics about the
- data reception/delivery from the device:
-
-$ cat /sys/kernel/debug/wimax:wmx0/i2400m/rx_stats
-45 1 3 34 3104 48 480
-
- The numbers reported are
- * packets/RX-buffer: total, min, max
- * RX-buffers: total RX buffers received, accumulated RX buffer size
- in bytes, min size received, max size received
-
- Thus, to find the average buffer size received, divide accumulated
- RX-buffer / total RX-buffers.
-
- To clear the statistics back to 0, write anything to the rx_stats file:
-
-$ echo 1 > /sys/kernel/debug/wimax:wmx0/i2400m_rx_stats
-
- Likewise for TX.
-
- Note the packets this debug file refers to are not network packet, but
- packets in the sense of the device-specific protocol for communication
- to the host. See drivers/net/wimax/i2400m/tx.c.
-
-5.2.3. Tracing messages received from user space
-
- To echo messages received from user space into the trace pipe that the
- i2400m driver creates, set the debug file i2400m/trace_msg_from_user to
- 1:
- *
-$ echo 1 > /sys/kernel/debug/wimax:wmx0/i2400m/trace_msg_from_user
-
-5.2.4. Performing a device reset
-
- By writing a 0, a 1 or a 2 to the file
- /sys/kernel/debug/wimax:wmx0/reset, the driver performs a warm (without
- disconnecting from the bus), cold (disconnecting from the bus) or bus
- (bus specific) reset on the device.
-
-5.2.5. Asking the device to enter power saving mode
-
- By writing any value to the /sys/kernel/debug/wimax:wmx0 file, the
- device will attempt to enter power saving mode.
-
-6. Troubleshooting
-
-6.1. Driver complains about 'i2400m-fw-usb-1.2.sbcf: request failed'
-
- If upon connecting the device, the following is output in the kernel
- log:
-
-i2400m_usb 5-4:1.0: fw i2400m-fw-usb-1.3.sbcf: request failed: -2
-
- This means that the driver cannot locate the firmware file named
- /lib/firmware/i2400m-fw-usb-1.2.sbcf. Check that the file is present in
- the right location.
diff --git a/Documentation/wimax/README.wimax b/Documentation/wimax/README.wimax
deleted file mode 100644
index b78c437..0000000
--- a/Documentation/wimax/README.wimax
+++ /dev/null
@@ -1,81 +0,0 @@
-
- Linux kernel WiMAX stack
-
- (C) 2008 Intel Corporation < linux-wimax@intel.com >
-
- This provides a basic Linux kernel WiMAX stack to provide a common
- control API for WiMAX devices, usable from kernel and user space.
-
-1. Design
-
- The WiMAX stack is designed to provide for common WiMAX control
- services to current and future WiMAX devices from any vendor.
-
- Because currently there is only one and we don't know what would be the
- common services, the APIs it currently provides are very minimal.
- However, it is done in such a way that it is easily extensible to
- accommodate future requirements.
-
- The stack works by embedding a struct wimax_dev in your device's
- control structures. This provides a set of callbacks that the WiMAX
- stack will call in order to implement control operations requested by
- the user. As well, the stack provides API functions that the driver
- calls to notify about changes of state in the device.
-
- The stack exports the API calls needed to control the device to user
- space using generic netlink as a marshalling mechanism. You can access
- them using your own code or use the wrappers provided for your
- convenience in libwimax (in the wimax-tools package).
-
- For detailed information on the stack, please see
- include/linux/wimax.h.
-
-2. Usage
-
- For usage in a driver (registration, API, etc) please refer to the
- instructions in the header file include/linux/wimax.h.
-
- When a device is registered with the WiMAX stack, a set of debugfs
- files will appear in /sys/kernel/debug/wimax:wmxX can tweak for
- control.
-
-2.1. Obtaining debug information: debugfs entries
-
- The WiMAX stack is compiled, by default, with debug messages that can
- be used to diagnose issues. By default, said messages are disabled.
-
- The drivers will register debugfs entries that allow the user to tweak
- debug settings.
-
- Each driver, when registering with the stack, will cause a debugfs
- directory named wimax:DEVICENAME to be created; optionally, it might
- create more subentries below it.
-
-2.1.1. Increasing debug output
-
- The files named *dl_* indicate knobs for controlling the debug output
- of different submodules of the WiMAX stack:
- *
-# find /sys/kernel/debug/wimax\:wmx0 -name \*dl_\*
-/sys/kernel/debug/wimax:wmx0/wimax_dl_stack
-/sys/kernel/debug/wimax:wmx0/wimax_dl_op_rfkill
-/sys/kernel/debug/wimax:wmx0/wimax_dl_op_reset
-/sys/kernel/debug/wimax:wmx0/wimax_dl_op_msg
-/sys/kernel/debug/wimax:wmx0/wimax_dl_id_table
-/sys/kernel/debug/wimax:wmx0/wimax_dl_debugfs
-/sys/kernel/debug/wimax:wmx0/.... # other driver specific files
-
- NOTE: Of course, if debugfs is mounted in a directory other than
- /sys/kernel/debug, those paths will change.
-
- By reading the file you can obtain the current value of said debug
- level; by writing to it, you can set it.
-
- To increase the debug level of, for example, the id-table submodule,
- just write:
-
-$ echo 3 > /sys/kernel/debug/wimax:wmx0/wimax_dl_id_table
-
- Increasing numbers yield increasing debug information; for details of
- what is printed and the available levels, check the source. The code
- uses 0 for disabled and increasing values until 8.
diff --git a/Documentation/x86/x86_64/boot-options.rst b/Documentation/x86/x86_64/boot-options.rst
index 6a4285a..2b98efb 100644
--- a/Documentation/x86/x86_64/boot-options.rst
+++ b/Documentation/x86/x86_64/boot-options.rst
@@ -230,7 +230,7 @@
===========================================
Multiple x86-64 PCI-DMA mapping implementations exist, for example:
- 1. <lib/dma-direct.c>: use no hardware/software IOMMU at all
+ 1. <kernel/dma/direct.c>: use no hardware/software IOMMU at all
(e.g. because you have < 3 GB memory).
Kernel boot message: "PCI-DMA: Disabling IOMMU"
diff --git a/Kbuild b/Kbuild
index 8637fd1..3109ac7 100644
--- a/Kbuild
+++ b/Kbuild
@@ -18,8 +18,6 @@
timeconst-file := include/generated/timeconst.h
-targets += $(timeconst-file)
-
filechk_gentimeconst = echo $(CONFIG_HZ) | bc -q $<
$(timeconst-file): kernel/time/timeconst.bc FORCE
@@ -42,7 +40,6 @@
# Check for missing system calls
always += missing-syscalls
-targets += missing-syscalls
quiet_cmd_syscalls = CALL $<
cmd_syscalls = $(CONFIG_SHELL) $< $(CC) $(c_flags) $(missing_syscalls_flags)
@@ -54,13 +51,9 @@
# Check atomic headers are up-to-date
always += old-atomics
-targets += old-atomics
quiet_cmd_atomics = CALL $<
cmd_atomics = $(CONFIG_SHELL) $<
old-atomics: scripts/atomic/check-atomics.sh FORCE
$(call cmd,atomics)
-
-# Keep these three files during make clean
-no-clean-files := $(bounds-file) $(offsets-file) $(timeconst-file)
diff --git a/MAINTAINERS b/MAINTAINERS
index e7a47b5..296de2b 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -517,14 +517,6 @@
S: Supported
F: drivers/video/backlight/adp8860_bl.c
-ADS1015 HARDWARE MONITOR DRIVER
-M: Dirk Eibach <eibach@gdsys.de>
-L: linux-hwmon@vger.kernel.org
-S: Maintained
-F: Documentation/hwmon/ads1015.rst
-F: drivers/hwmon/ads1015.c
-F: include/linux/platform_data/ads1015.h
-
ADT746X FAN DRIVER
M: Colin Leroy <colin@colino.net>
S: Maintained
@@ -649,6 +641,13 @@
S: Maintained
F: drivers/net/ethernet/alacritech/*
+FORCEDETH GIGABIT ETHERNET DRIVER
+M: Rain River <rain.1986.08.12@gmail.com>
+M: Zhu Yanjun <yanjun.zhu@oracle.com>
+L: netdev@vger.kernel.org
+S: Maintained
+F: drivers/net/ethernet/nvidia/*
+
ALCATEL SPEEDTOUCH USB DRIVER
M: Duncan Sands <duncan.sands@free.fr>
L: linux-usb@vger.kernel.org
@@ -666,7 +665,7 @@
M: Rudolf Marek <r.marek@assembler.cz>
L: linux-i2c@vger.kernel.org
S: Maintained
-F: Documentation/i2c/busses/i2c-ali1563
+F: Documentation/i2c/busses/i2c-ali1563.rst
F: drivers/i2c/busses/i2c-ali1563.c
ALLEGRO DVT VIDEO IP CORE DRIVER
@@ -676,6 +675,13 @@
S: Maintained
F: drivers/staging/media/allegro-dvt/
+ALLWINNER CPUFREQ DRIVER
+M: Yangtao Li <tiny.windzz@gmail.com>
+L: linux-pm@vger.kernel.org
+S: Maintained
+F: Documentation/devicetree/bindings/opp/sun50i-nvmem-cpufreq.txt
+F: drivers/cpufreq/sun50i-cpufreq-nvmem.c
+
ALLWINNER SECURITY SYSTEM
M: Corentin Labbe <clabbe.montjoie@gmail.com>
L: linux-crypto@vger.kernel.org
@@ -723,7 +729,7 @@
M: Thor Thayer <thor.thayer@linux.intel.com>
S: Maintained
F: drivers/mfd/altera-sysmgr.c
-F: include/linux/mfd/altera-sysgmr.h
+F: include/linux/mfd/altera-sysmgr.h
ALTERA SYSTEM RESOURCE DRIVER FOR ARRIA10 DEVKIT
M: Thor Thayer <thor.thayer@linux.intel.com>
@@ -829,17 +835,11 @@
F: include/linux/amd-iommu.h
AMD KFD
-M: Oded Gabbay <oded.gabbay@gmail.com>
-L: dri-devel@lists.freedesktop.org
-T: git git://people.freedesktop.org/~gabbayo/linux.git
+M: Felix Kuehling <Felix.Kuehling@amd.com>
+L: amd-gfx@lists.freedesktop.org
+T: git git://people.freedesktop.org/~agd5f/linux
S: Supported
-F: drivers/gpu/drm/amd/amdgpu/amdgpu_amdkfd.c
-F: drivers/gpu/drm/amd/amdgpu/amdgpu_amdkfd.h
-F: drivers/gpu/drm/amd/amdgpu/amdgpu_amdkfd_gfx_v7.c
-F: drivers/gpu/drm/amd/amdgpu/amdgpu_amdkfd_gfx_v8.c
-F: drivers/gpu/drm/amd/amdgpu/amdgpu_amdkfd_gfx_v9.c
-F: drivers/gpu/drm/amd/amdgpu/amdgpu_amdkfd_fence.c
-F: drivers/gpu/drm/amd/amdgpu/amdgpu_amdkfd_gpuvm.c
+F: drivers/gpu/drm/amd/amdgpu/amdgpu_amdkfd*.[ch]
F: drivers/gpu/drm/amd/amdkfd/
F: drivers/gpu/drm/amd/include/cik_structs.h
F: drivers/gpu/drm/amd/include/kgd_kfd_interface.h
@@ -903,11 +903,12 @@
ANALOG DEVICES INC AD7606 DRIVER
M: Stefan Popa <stefan.popa@analog.com>
+M: Beniamin Bia <beniamin.bia@analog.com>
L: linux-iio@vger.kernel.org
W: http://ez.analog.com/community/linux-device-drivers
S: Supported
F: drivers/iio/adc/ad7606.c
-F: Documentation/devicetree/bindings/iio/adc/adi,ad7606.txt
+F: Documentation/devicetree/bindings/iio/adc/adi,ad7606.yaml
ANALOG DEVICES INC AD7768-1 DRIVER
M: Stefan Popa <stefan.popa@analog.com>
@@ -938,6 +939,14 @@
F: drivers/mux/adgs1408.c
F: Documentation/devicetree/bindings/mux/adi,adgs1408.txt
+ANALOG DEVICES INC ADIN DRIVER
+M: Alexandru Ardelean <alexaundru.ardelean@analog.com>
+L: netdev@vger.kernel.org
+W: http://ez.analog.com/community/linux-device-drivers
+S: Supported
+F: drivers/net/phy/adin.c
+F: Documentation/devicetree/bindings/net/adi,adin.yaml
+
ANALOG DEVICES INC ADIS DRIVER LIBRARY
M: Alexandru Ardelean <alexandru.ardelean@analog.com>
S: Supported
@@ -945,6 +954,14 @@
F: include/linux/iio/imu/adis.h
F: drivers/iio/imu/adis.c
+ANALOG DEVICES INC ADIS16460 DRIVER
+M: Dragos Bogdan <dragos.bogdan@analog.com>
+S: Supported
+L: linux-iio@vger.kernel.org
+W: http://ez.analog.com/community/linux-device-drivers
+F: drivers/iio/imu/adis16460.c
+F: Documentation/devicetree/bindings/iio/imu/adi,adis16460.yaml
+
ANALOG DEVICES INC ADP5061 DRIVER
M: Stefan Popa <stefan.popa@analog.com>
L: linux-pm@vger.kernel.org
@@ -1350,8 +1367,7 @@
R: Robin Murphy <robin.murphy@arm.com>
L: linux-arm-kernel@lists.infradead.org (moderated for non-subscribers)
S: Maintained
-F: drivers/iommu/arm-smmu.c
-F: drivers/iommu/arm-smmu-v3.c
+F: drivers/iommu/arm-smmu*
F: drivers/iommu/io-pgtable-arm.c
F: drivers/iommu/io-pgtable-arm-v7s.c
@@ -1379,7 +1395,7 @@
F: drivers/soc/actions/
F: include/dt-bindings/power/owl-*
F: include/linux/soc/actions/
-F: Documentation/devicetree/bindings/arm/actions.txt
+F: Documentation/devicetree/bindings/arm/actions.yaml
F: Documentation/devicetree/bindings/clock/actions,owl-cmu.txt
F: Documentation/devicetree/bindings/dma/owl-dma.txt
F: Documentation/devicetree/bindings/i2c/i2c-owl.txt
@@ -1421,6 +1437,14 @@
F: drivers/soc/sunxi/
T: git git://git.kernel.org/pub/scm/linux/kernel/git/sunxi/linux.git
+Allwinner A10 CSI driver
+M: Maxime Ripard <mripard@kernel.org>
+L: linux-media@vger.kernel.org
+T: git git://linuxtv.org/media_tree.git
+F: drivers/media/platform/sunxi/sun4i-csi/
+F: Documentation/devicetree/bindings/media/allwinner,sun4i-a10-csi.yaml
+S: Maintained
+
ARM/Amlogic Meson SoC CLOCK FRAMEWORK
M: Neil Armstrong <narmstrong@baylibre.com>
M: Jerome Brunet <jbrunet@baylibre.com>
@@ -1443,6 +1467,7 @@
F: drivers/pinctrl/meson/
F: drivers/mmc/host/meson*
F: drivers/soc/amlogic/
+F: drivers/rtc/rtc-meson*
N: meson
ARM/Amlogic Meson SoC Sound Drivers
@@ -1471,6 +1496,7 @@
F: arch/arm/boot/dts/artpec6*
F: drivers/clk/axis
F: drivers/crypto/axis
+F: drivers/mmc/host/usdhi6rol0.c
F: drivers/pinctrl/pinctrl-artpec*
F: Documentation/devicetree/bindings/pinctrl/axis,artpec6-pinctrl.txt
@@ -1582,8 +1608,8 @@
L: linux-arm-kernel@lists.infradead.org (moderated for non-subscribers)
S: Maintained
F: drivers/hwtracing/coresight/*
-F: Documentation/trace/coresight.txt
-F: Documentation/trace/coresight-cpu-debug.txt
+F: Documentation/trace/coresight.rst
+F: Documentation/trace/coresight-cpu-debug.rst
F: Documentation/devicetree/bindings/arm/coresight.txt
F: Documentation/devicetree/bindings/arm/coresight-cpu-debug.txt
F: Documentation/ABI/testing/sysfs-bus-coresight-devices-*
@@ -1626,6 +1652,21 @@
N: [^a-z]sirf
X: drivers/gnss
+ARM/CZ.NIC TURRIS MOX SUPPORT
+M: Marek Behun <marek.behun@nic.cz>
+W: http://mox.turris.cz
+S: Maintained
+F: Documentation/ABI/testing/debugfs-moxtet
+F: Documentation/ABI/testing/sysfs-bus-moxtet-devices
+F: Documentation/ABI/testing/sysfs-firmware-turris-mox-rwtm
+F: Documentation/devicetree/bindings/bus/moxtet.txt
+F: Documentation/devicetree/bindings/firmware/cznic,turris-mox-rwtm.txt
+F: Documentation/devicetree/bindings/gpio/gpio-moxtet.txt
+F: include/linux/moxtet.h
+F: drivers/bus/moxtet.c
+F: drivers/firmware/turris-mox-rwtm.c
+F: drivers/gpio/gpio-moxtet.c
+
ARM/EBSA110 MACHINE SUPPORT
M: Russell King <linux@armlinux.org.uk>
L: linux-arm-kernel@lists.infradead.org (moderated for non-subscribers)
@@ -1749,20 +1790,11 @@
S: Maintained
F: arch/arm/mach-pxa/colibri-pxa270-income.c
-ARM/INTEL IOP13XX ARM ARCHITECTURE
-M: Lennert Buytenhek <kernel@wantstofly.org>
-L: linux-arm-kernel@lists.infradead.org (moderated for non-subscribers)
-S: Maintained
-
ARM/INTEL IOP32X ARM ARCHITECTURE
M: Lennert Buytenhek <kernel@wantstofly.org>
L: linux-arm-kernel@lists.infradead.org (moderated for non-subscribers)
S: Maintained
-ARM/INTEL IOP33X ARM ARCHITECTURE
-L: linux-arm-kernel@lists.infradead.org (moderated for non-subscribers)
-S: Orphan
-
ARM/INTEL IQ81342EX MACHINE SUPPORT
M: Lennert Buytenhek <kernel@wantstofly.org>
L: linux-arm-kernel@lists.infradead.org (moderated for non-subscribers)
@@ -1921,12 +1953,6 @@
F: drivers/phy/mediatek/
F: Documentation/devicetree/bindings/phy/phy-mtk-*
-ARM/MICREL KS8695 ARCHITECTURE
-M: Greg Ungerer <gerg@uclinux.org>
-L: linux-arm-kernel@lists.infradead.org (moderated for non-subscribers)
-F: arch/arm/mach-ks8695/
-S: Odd Fixes
-
ARM/Microchip (AT91) SoC support
M: Nicolas Ferre <nicolas.ferre@microchip.com>
M: Alexandre Belloni <alexandre.belloni@bootlin.com>
@@ -1968,6 +1994,7 @@
F: arch/arm/mach-nomadik/
F: arch/arm/mach-u300/
F: arch/arm/mach-ux500/
+F: drivers/soc/ux500/
F: arch/arm/boot/dts/ste-*
F: drivers/clk/clk-nomadik.c
F: drivers/clk/clk-u300.c
@@ -2011,22 +2038,6 @@
F: Documentation/devicetree/bindings/*/*npcm*
F: Documentation/devicetree/bindings/*/*/*npcm*
-ARM/NUVOTON W90X900 ARM ARCHITECTURE
-M: Wan ZongShun <mcuos.com@gmail.com>
-L: linux-arm-kernel@lists.infradead.org (moderated for non-subscribers)
-W: http://www.mcuos.com
-S: Maintained
-F: arch/arm/mach-w90x900/
-F: drivers/input/keyboard/w90p910_keypad.c
-F: drivers/input/touchscreen/w90p910_ts.c
-F: drivers/watchdog/nuc900_wdt.c
-F: drivers/net/ethernet/nuvoton/w90p910_ether.c
-F: drivers/mtd/nand/raw/nuc900_nand.c
-F: drivers/rtc/rtc-nuc900.c
-F: drivers/spi/spi-nuc900.c
-F: drivers/usb/host/ehci-w90x900.c
-F: drivers/video/fbdev/nuc900fb.c
-
ARM/OPENMOKO NEO FREERUNNER (GTA02) MACHINE SUPPORT
L: openmoko-kernel@lists.openmoko.org (subscribers-only)
W: http://wiki.openmoko.org/wiki/Neo_FreeRunner
@@ -2151,7 +2162,7 @@
L: linux-arm-kernel@lists.infradead.org (moderated for non-subscribers)
S: Maintained
F: arch/arm64/boot/dts/realtek/
-F: Documentation/devicetree/bindings/arm/realtek.txt
+F: Documentation/devicetree/bindings/arm/realtek.yaml
ARM/RENESAS ARM64 ARCHITECTURE
M: Simon Horman <horms@verge.net.au>
@@ -2219,8 +2230,9 @@
F: drivers/*/*/*s3c24*
F: drivers/*/*s3c64xx*
F: drivers/*/*s5pv210*
-F: drivers/memory/samsung/*
-F: drivers/soc/samsung/*
+F: drivers/memory/samsung/
+F: drivers/soc/samsung/
+F: include/linux/soc/samsung/
F: Documentation/arm/samsung/
F: Documentation/devicetree/bindings/arm/samsung/
F: Documentation/devicetree/bindings/sram/samsung-sram.txt
@@ -2910,11 +2922,14 @@
F: include/linux/backlight.h
F: include/linux/pwm_backlight.h
F: Documentation/devicetree/bindings/leds/backlight
+F: Documentation/ABI/stable/sysfs-class-backlight
+F: Documentation/ABI/testing/sysfs-class-backlight
BATMAN ADVANCED
M: Marek Lindner <mareklindner@neomailbox.ch>
M: Simon Wunderlich <sw@simonwunderlich.de>
M: Antonio Quartulli <a@unstable.cc>
+M: Sven Eckelmann <sven@narfation.org>
L: b.a.t.m.a.n@lists.open-mesh.org (moderated for non-subscribers)
W: https://www.open-mesh.org/
B: https://www.open-mesh.org/projects/batman-adv/issues
@@ -3635,9 +3650,12 @@
F: Documentation/devicetree/bindings/net/can/
F: drivers/net/can/
F: include/linux/can/dev.h
+F: include/linux/can/led.h
+F: include/linux/can/rx-offload.h
F: include/linux/can/platform/
F: include/uapi/linux/can/error.h
F: include/uapi/linux/can/netlink.h
+F: include/uapi/linux/can/vxcan.h
CAN NETWORK LAYER
M: Oliver Hartkopp <socketcan@hartkopp.net>
@@ -3650,11 +3668,23 @@
F: Documentation/networking/can.rst
F: net/can/
F: include/linux/can/core.h
+F: include/linux/can/skb.h
+F: include/net/netns/can.h
F: include/uapi/linux/can.h
F: include/uapi/linux/can/bcm.h
F: include/uapi/linux/can/raw.h
F: include/uapi/linux/can/gw.h
+CAN-J1939 NETWORK LAYER
+M: Robin van der Gracht <robin@protonic.nl>
+M: Oleksij Rempel <o.rempel@pengutronix.de>
+R: Pengutronix Kernel Team <kernel@pengutronix.de>
+L: linux-can@vger.kernel.org
+S: Maintained
+F: Documentation/networking/j1939.txt
+F: net/can/j1939/
+F: include/uapi/linux/can/j1939.h
+
CAPABILITIES
M: Serge Hallyn <serge@hallyn.com>
L: linux-security-module@vger.kernel.org
@@ -3804,14 +3834,9 @@
F: scripts/extract-cert.c
CERTIFIED WIRELESS USB (WUSB) SUBSYSTEM:
-L: linux-usb@vger.kernel.org
-S: Orphan
-F: Documentation/usb/wusb-design-overview.rst
-F: Documentation/usb/wusb-cbaf
-F: drivers/usb/host/hwa-hc.c
-F: drivers/usb/host/whci/
-F: drivers/usb/wusbcore/
-F: include/linux/usb/wusb*
+L: devel@driverdev.osuosl.org
+S: Obsolete
+F: drivers/staging/wusbcore/
CFAG12864B LCD DRIVER
M: Miguel Ojeda Sandonis <miguel.ojeda.sandonis@gmail.com>
@@ -4103,7 +4128,7 @@
W: http://linux-cifs.samba.org/
T: git git://git.samba.org/sfrench/cifs-2.6.git
S: Supported
-F: Documentation/filesystems/cifs/
+F: Documentation/admin-guide/cifs/
F: fs/cifs/
COMPACTPCI HOTPLUG CORE
@@ -4290,6 +4315,14 @@
F: drivers/cpuidle/cpuidle-exynos.c
F: arch/arm/mach-exynos/pm.c
+CPUIDLE DRIVER - ARM PSCI
+M: Lorenzo Pieralisi <lorenzo.pieralisi@arm.com>
+M: Sudeep Holla <sudeep.holla@arm.com>
+L: linux-pm@vger.kernel.org
+L: linux-arm-kernel@lists.infradead.org
+S: Supported
+F: drivers/cpuidle/cpuidle-psci.c
+
CPU IDLE TIME MANAGEMENT FRAMEWORK
M: "Rafael J. Wysocki" <rjw@rjwysocki.net>
M: Daniel Lezcano <daniel.lezcano@linaro.org>
@@ -4308,6 +4341,12 @@
F: Documentation/filesystems/cramfs.txt
F: fs/cramfs/
+CREATIVE SB0540
+M: Bastien Nocera <hadess@hadess.net>
+L: linux-input@vger.kernel.org
+S: Maintained
+F: drivers/hid/hid-creative-sb0540.c
+
CRYPTO API
M: Herbert Xu <herbert@gondor.apana.org.au>
M: "David S. Miller" <davem@davemloft.net>
@@ -4951,7 +4990,9 @@
L: linux-doc@vger.kernel.org
S: Maintained
F: Documentation/
+F: scripts/documentation-file-ref-check
F: scripts/kernel-doc
+F: scripts/sphinx-pre-install
X: Documentation/ABI/
X: Documentation/firmware-guide/acpi/
X: Documentation/devicetree/
@@ -4967,6 +5008,14 @@
S: Maintained
F: Documentation/translations/it_IT
+DOCUMENTATION SCRIPTS
+M: Mauro Carvalho Chehab <mchehab@kernel.org>
+L: linux-doc@vger.kernel.org
+S: Maintained
+F: scripts/documentation-file-ref-check
+F: scripts/sphinx-pre-install
+F: Documentation/sphinx/parse-headers.pl
+
DONGWOON DW9714 LENS VOICE COIL DRIVER
M: Sakari Ailus <sakari.ailus@linux.intel.com>
L: linux-media@vger.kernel.org
@@ -5099,17 +5148,24 @@
F: drivers/gpu/drm/panel/panel-feiyang-fy07024di26a30d.c
F: Documentation/devicetree/bindings/display/panel/feiyang,fy07024di26a30d.txt
+DRM DRIVER FOR GRAIN MEDIA GM12U320 PROJECTORS
+M: Hans de Goede <hdegoede@redhat.com>
+T: git git://anongit.freedesktop.org/drm/drm-misc
+S: Maintained
+F: drivers/gpu/drm/tiny/gm12u320.c
+
DRM DRIVER FOR ILITEK ILI9225 PANELS
M: David Lechner <david@lechnology.com>
+T: git git://anongit.freedesktop.org/drm/drm-misc
S: Maintained
-F: drivers/gpu/drm/tinydrm/ili9225.c
+F: drivers/gpu/drm/tiny/ili9225.c
F: Documentation/devicetree/bindings/display/ilitek,ili9225.txt
DRM DRIVER FOR HX8357D PANELS
M: Eric Anholt <eric@anholt.net>
T: git git://anongit.freedesktop.org/drm/drm-misc
S: Maintained
-F: drivers/gpu/drm/tinydrm/hx8357d.c
+F: drivers/gpu/drm/tiny/hx8357d.c
F: Documentation/devicetree/bindings/display/himax,hx8357d.txt
DRM DRIVER FOR INTEL I810 VIDEO CARDS
@@ -5129,8 +5185,9 @@
DRM DRIVER FOR MI0283QT
M: Noralf Trønnes <noralf@tronnes.org>
+T: git git://anongit.freedesktop.org/drm/drm-misc
S: Maintained
-F: drivers/gpu/drm/tinydrm/mi0283qt.c
+F: drivers/gpu/drm/tiny/mi0283qt.c
F: Documentation/devicetree/bindings/display/multi-inno,mi0283qt.txt
DRM DRIVER FOR MSM ADRENO GPU
@@ -5162,8 +5219,9 @@
DRM DRIVER FOR PERVASIVE DISPLAYS REPAPER PANELS
M: Noralf Trønnes <noralf@tronnes.org>
+T: git git://anongit.freedesktop.org/drm/drm-misc
S: Maintained
-F: drivers/gpu/drm/tinydrm/repaper.c
+F: drivers/gpu/drm/tiny/repaper.c
F: Documentation/devicetree/bindings/display/repaper.txt
DRM DRIVER FOR QEMU'S CIRRUS DEVICE
@@ -5185,6 +5243,12 @@
F: drivers/gpu/drm/qxl/
F: include/uapi/drm/qxl_drm.h
+DRM DRIVER FOR RAYDIUM RM67191 PANELS
+M: Robert Chiras <robert.chiras@nxp.com>
+S: Maintained
+F: drivers/gpu/drm/panel/panel-raydium-rm67191.c
+F: Documentation/devicetree/bindings/display/panel/raydium,rm67191.txt
+
DRM DRIVER FOR RAGE 128 VIDEO CARDS
S: Orphan / Obsolete
F: drivers/gpu/drm/r128/
@@ -5192,6 +5256,7 @@
DRM DRIVER FOR ROCKTECH JH057N00900 PANELS
M: Guido Günther <agx@sigxcpu.org>
+R: Purism Kernel Team <kernel@puri.sm>
S: Maintained
F: drivers/gpu/drm/panel/panel-rocktech-jh057n00900.c
F: Documentation/devicetree/bindings/display/panel/rocktech,jh057n00900.txt
@@ -5214,14 +5279,16 @@
DRM DRIVER FOR SITRONIX ST7586 PANELS
M: David Lechner <david@lechnology.com>
+T: git git://anongit.freedesktop.org/drm/drm-misc
S: Maintained
-F: drivers/gpu/drm/tinydrm/st7586.c
+F: drivers/gpu/drm/tiny/st7586.c
F: Documentation/devicetree/bindings/display/sitronix,st7586.txt
DRM DRIVER FOR SITRONIX ST7735R PANELS
M: David Lechner <david@lechnology.com>
+T: git git://anongit.freedesktop.org/drm/drm-misc
S: Maintained
-F: drivers/gpu/drm/tinydrm/st7735r.c
+F: drivers/gpu/drm/tiny/st7735r.c
F: Documentation/devicetree/bindings/display/sitronix,st7735r.txt
DRM DRIVER FOR ST-ERICSSON MCDE
@@ -5240,7 +5307,7 @@
T: git git://anongit.freedesktop.org/drm/drm-misc
S: Maintained
F: drivers/gpu/drm/panel/panel-tpo-tpg110.c
-F: Documentation/devicetree/bindings/display/panel/tpo,tpg110.txt
+F: Documentation/devicetree/bindings/display/panel/tpo,tpg110.yaml
DRM DRIVER FOR USB DISPLAYLINK VIDEO ADAPTERS
M: Dave Airlie <airlied@redhat.com>
@@ -5322,12 +5389,13 @@
W: http://linux-meson.com/
S: Supported
F: drivers/gpu/drm/meson/
-F: Documentation/devicetree/bindings/display/amlogic,meson-vpu.txt
-F: Documentation/devicetree/bindings/display/amlogic,meson-dw-hdmi.txt
+F: Documentation/devicetree/bindings/display/amlogic,meson-vpu.yaml
+F: Documentation/devicetree/bindings/display/amlogic,meson-dw-hdmi.yaml
F: Documentation/gpu/meson.rst
T: git git://anongit.freedesktop.org/drm/drm-misc
DRM DRIVERS FOR ATMEL HLCDC
+M: Sam Ravnborg <sam@ravnborg.org>
M: Boris Brezillon <bbrezillon@kernel.org>
L: dri-devel@lists.freedesktop.org
S: Supported
@@ -5337,7 +5405,10 @@
DRM DRIVERS FOR BRIDGE CHIPS
M: Andrzej Hajda <a.hajda@samsung.com>
+M: Neil Armstrong <narmstrong@baylibre.com>
R: Laurent Pinchart <Laurent.pinchart@ideasonboard.com>
+R: Jonas Karlman <jonas@kwiboo.se>
+R: Jernej Skrabec <jernej.skrabec@siol.net>
S: Maintained
T: git git://anongit.freedesktop.org/drm/drm-misc
F: drivers/gpu/drm/bridge/
@@ -5525,14 +5596,6 @@
F: include/drm/drm_panel.h
F: Documentation/devicetree/bindings/display/panel/
-DRM TINYDRM DRIVERS
-M: Noralf Trønnes <noralf@tronnes.org>
-W: https://github.com/notro/tinydrm/wiki/Development
-T: git git://anongit.freedesktop.org/drm/drm-misc
-S: Maintained
-F: drivers/gpu/drm/tinydrm/
-F: include/drm/tinydrm/
-
DRM DRIVERS FOR XEN
M: Oleksandr Andrushchenko <oleksandr_andrushchenko@epam.com>
T: git git://anongit.freedesktop.org/drm/drm-misc
@@ -5558,12 +5621,6 @@
S: Maintained
F: drivers/media/radio/dsbr100.c
-DSCC4 DRIVER
-M: Francois Romieu <romieu@fr.zoreil.com>
-L: netdev@vger.kernel.org
-S: Maintained
-F: drivers/net/wan/dscc4.c
-
DT3155 MEDIA DRIVER
M: Hans Verkuil <hverkuil@xs4all.nl>
L: linux-media@vger.kernel.org
@@ -5755,12 +5812,23 @@
S: Maintained
F: drivers/edac/amd64_edac*
+EDAC-ARMADA
+M: Jan Luebbe <jlu@pengutronix.de>
+L: linux-edac@vger.kernel.org
+S: Maintained
+F: drivers/edac/armada_xp_*
+
EDAC-AST2500
M: Stefan Schaeckeler <sschaeck@cisco.com>
S: Supported
F: drivers/edac/aspeed_edac.c
F: Documentation/devicetree/bindings/edac/aspeed-sdram-edac.txt
+EDAC-BLUEFIELD
+M: Shravan Kumar Ramani <sramani@mellanox.com>
+S: Supported
+F: drivers/edac/bluefield_edac.c
+
EDAC-CALXEDA
M: Robert Richter <rric@kernel.org>
L: linux-edac@vger.kernel.org
@@ -5785,10 +5853,11 @@
EDAC-CORE
M: Borislav Petkov <bp@alien8.de>
M: Mauro Carvalho Chehab <mchehab@kernel.org>
+M: Tony Luck <tony.luck@intel.com>
R: James Morse <james.morse@arm.com>
+R: Robert Richter <rrichter@marvell.com>
L: linux-edac@vger.kernel.org
-T: git git://git.kernel.org/pub/scm/linux/kernel/git/bp/bp.git for-next
-T: git git://git.kernel.org/pub/scm/linux/kernel/git/mchehab/linux-edac.git linux_next
+T: git git://git.kernel.org/pub/scm/linux/kernel/git/ras/ras.git edac-for-next
S: Supported
F: Documentation/admin-guide/ras.rst
F: Documentation/driver-api/edac.rst
@@ -6038,6 +6107,13 @@
F: drivers/video/fbdev/s1d13xxxfb.c
F: include/video/s1d13xxxfb.h
+EROFS FILE SYSTEM
+M: Gao Xiang <gaoxiang25@huawei.com>
+M: Chao Yu <yuchao0@huawei.com>
+L: linux-erofs@lists.ozlabs.org
+S: Maintained
+F: fs/erofs/
+
ERRSEQ ERROR TRACKING INFRASTRUCTURE
M: Jeff Layton <jlayton@kernel.org>
S: Maintained
@@ -6082,6 +6158,11 @@
F: include/uapi/linux/mdio.h
F: include/uapi/linux/mii.h
+EXFAT FILE SYSTEM
+M: Valdis Kletnieks <valdis.kletnieks@vt.edu>
+S: Maintained
+F: drivers/staging/exfat/
+
EXT2 FILE SYSTEM
M: Jan Kara <jack@suse.com>
L: linux-ext4@vger.kernel.org
@@ -6268,12 +6349,14 @@
F: drivers/hwmon/f75375s.c
F: include/linux/f75375s.h
-FIREWIRE AUDIO DRIVERS
+FIREWIRE AUDIO DRIVERS and IEC 61883-1/6 PACKET STREAMING ENGINE
M: Clemens Ladisch <clemens@ladisch.de>
+M: Takashi Sakamoto <o-takashi@sakamocchi.jp>
L: alsa-devel@alsa-project.org (moderated for non-subscribers)
T: git git://git.kernel.org/pub/scm/linux/kernel/git/tiwai/sound.git
S: Maintained
F: sound/firewire/
+F: include/uapi/sound/firewire.h
FIREWIRE MEDIA DRIVERS (firedtv)
M: Stefan Richter <stefanr@s5r6.in-berlin.de>
@@ -6321,7 +6404,7 @@
M: Patrick Havelange <patrick.havelange@essensium.com>
L: linux-iio@vger.kernel.org
S: Maintained
-F: Documentation/ABI/testing/sysfs-bus-counter-ftm-quadddec
+F: Documentation/ABI/testing/sysfs-bus-counter-ftm-quaddec
F: Documentation/devicetree/bindings/counter/ftm-quaddec.txt
F: drivers/counter/ftm-quaddec.c
@@ -6331,15 +6414,6 @@
L: linux-block@vger.kernel.org
F: drivers/block/floppy.c
-FMC SUBSYSTEM
-M: Alessandro Rubini <rubini@gnudd.com>
-W: http://www.ohwr.org/projects/fmc-bus
-S: Supported
-F: drivers/fmc/
-F: include/linux/fmc*.h
-F: include/linux/ipmi-fru.h
-K: fmc_d.*register
-
FPGA MANAGER FRAMEWORK
M: Moritz Fischer <mdf@kernel.org>
L: linux-fpga@vger.kernel.org
@@ -6439,6 +6513,7 @@
L: linux-arm-kernel@lists.infradead.org
S: Maintained
F: drivers/perf/fsl_imx8_ddr_perf.c
+F: Documentation/admin-guide/perf/imx-ddr.rst
F: Documentation/devicetree/bindings/perf/fsl-imx-ddr.txt
FREESCALE IMX I2C DRIVER
@@ -6611,6 +6686,7 @@
S: Supported
F: fs/crypto/
F: include/linux/fscrypt*.h
+F: include/uapi/linux/fscrypt.h
F: Documentation/filesystems/fscrypt.rst
FSI SUBSYSTEM
@@ -6642,6 +6718,18 @@
F: fs/notify/
F: include/linux/fsnotify*.h
+FSVERITY: READ-ONLY FILE-BASED AUTHENTICITY PROTECTION
+M: Eric Biggers <ebiggers@kernel.org>
+M: Theodore Y. Ts'o <tytso@mit.edu>
+L: linux-fscrypt@vger.kernel.org
+Q: https://patchwork.kernel.org/project/linux-fscrypt/list/
+T: git git://git.kernel.org/pub/scm/fs/fscrypt/fscrypt.git fsverity
+S: Supported
+F: fs/verity/
+F: include/linux/fsverity.h
+F: include/uapi/linux/fsverity.h
+F: Documentation/filesystems/fsverity.rst
+
FUJITSU LAPTOP EXTRAS
M: Jonathan Woithe <jwoithe@just42.net>
L: platform-driver-x86@vger.kernel.org
@@ -6732,6 +6820,13 @@
S: Maintained
F: drivers/media/radio/radio-gemtek*
+GENERIC ARCHITECTURE TOPOLOGY
+M: Sudeep Holla <sudeep.holla@arm.com>
+L: linux-kernel@vger.kernel.org
+S: Maintained
+F: drivers/base/arch_topology.c
+F: include/linux/arch_topology.h
+
GENERIC GPIO I2C DRIVER
M: Wolfram Sang <wsa+renesas@sang-engineering.com>
S: Supported
@@ -6744,7 +6839,7 @@
S: Supported
F: drivers/i2c/muxes/i2c-mux-gpio.c
F: include/linux/platform_data/i2c-mux-gpio.h
-F: Documentation/i2c/muxes/i2c-mux-gpio
+F: Documentation/i2c/muxes/i2c-mux-gpio.rst
GENERIC HDLC (WAN) DRIVERS
M: Krzysztof Halasa <khc@pm.waw.pl>
@@ -6988,6 +7083,9 @@
M: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
S: Maintained
F: drivers/staging/greybus/
+F: drivers/greybus/
+F: include/linux/greybus.h
+F: include/linux/greybus/
L: greybus-dev@lists.linaro.org (moderated for non-subscribers)
GREYBUS UART PROTOCOLS DRIVERS
@@ -7313,6 +7411,17 @@
F: drivers/scsi/hisi_sas/
F: Documentation/devicetree/bindings/scsi/hisilicon-sas.txt
+HISILICON QM AND ZIP Controller DRIVER
+M: Zhou Wang <wangzhou1@hisilicon.com>
+L: linux-crypto@vger.kernel.org
+S: Maintained
+F: drivers/crypto/hisilicon/qm.c
+F: drivers/crypto/hisilicon/qm.h
+F: drivers/crypto/hisilicon/sgl.c
+F: drivers/crypto/hisilicon/sgl.h
+F: drivers/crypto/hisilicon/zip/
+F: Documentation/ABI/testing/debugfs-hisi-zip
+
HMM - Heterogeneous Memory Management
M: Jérôme Glisse <jglisse@redhat.com>
L: linux-mm@kvack.org
@@ -7456,6 +7565,7 @@
F: drivers/hv/
F: drivers/input/serio/hyperv-keyboard.c
F: drivers/pci/controller/pci-hyperv.c
+F: drivers/pci/controller/pci-hyperv-intf.c
F: drivers/net/hyperv/
F: drivers/scsi/storvsc_drv.c
F: drivers/uio/uio_hv_generic.c
@@ -7493,14 +7603,14 @@
M: Ajay Gupta <ajayg@nvidia.com>
L: linux-i2c@vger.kernel.org
S: Maintained
-F: Documentation/i2c/busses/i2c-nvidia-gpu
+F: Documentation/i2c/busses/i2c-nvidia-gpu.rst
F: drivers/i2c/busses/i2c-nvidia-gpu.c
I2C MUXES
M: Peter Rosin <peda@axentia.se>
L: linux-i2c@vger.kernel.org
S: Maintained
-F: Documentation/i2c/i2c-topology
+F: Documentation/i2c/i2c-topology.rst
F: Documentation/i2c/muxes/
F: Documentation/devicetree/bindings/i2c/i2c-mux*
F: Documentation/devicetree/bindings/i2c/i2c-arb*
@@ -7520,8 +7630,8 @@
M: Jean Delvare <jdelvare@suse.com>
L: linux-i2c@vger.kernel.org
S: Maintained
-F: Documentation/i2c/busses/i2c-parport
-F: Documentation/i2c/busses/i2c-parport-light
+F: Documentation/i2c/busses/i2c-parport.rst
+F: Documentation/i2c/busses/i2c-parport-light.rst
F: drivers/i2c/busses/i2c-parport.c
F: drivers/i2c/busses/i2c-parport-light.c
@@ -7555,7 +7665,7 @@
M: Jean Delvare <jdelvare@suse.com>
L: linux-i2c@vger.kernel.org
S: Maintained
-F: Documentation/i2c/busses/i2c-taos-evm
+F: Documentation/i2c/busses/i2c-taos-evm.rst
F: drivers/i2c/busses/i2c-taos-evm.c
I2C-TINY-USB DRIVER
@@ -7569,19 +7679,19 @@
M: Jean Delvare <jdelvare@suse.com>
L: linux-i2c@vger.kernel.org
S: Maintained
-F: Documentation/i2c/busses/i2c-ali1535
-F: Documentation/i2c/busses/i2c-ali1563
-F: Documentation/i2c/busses/i2c-ali15x3
-F: Documentation/i2c/busses/i2c-amd756
-F: Documentation/i2c/busses/i2c-amd8111
-F: Documentation/i2c/busses/i2c-i801
-F: Documentation/i2c/busses/i2c-nforce2
-F: Documentation/i2c/busses/i2c-piix4
-F: Documentation/i2c/busses/i2c-sis5595
-F: Documentation/i2c/busses/i2c-sis630
-F: Documentation/i2c/busses/i2c-sis96x
-F: Documentation/i2c/busses/i2c-via
-F: Documentation/i2c/busses/i2c-viapro
+F: Documentation/i2c/busses/i2c-ali1535.rst
+F: Documentation/i2c/busses/i2c-ali1563.rst
+F: Documentation/i2c/busses/i2c-ali15x3.rst
+F: Documentation/i2c/busses/i2c-amd756.rst
+F: Documentation/i2c/busses/i2c-amd8111.rst
+F: Documentation/i2c/busses/i2c-i801.rst
+F: Documentation/i2c/busses/i2c-nforce2.rst
+F: Documentation/i2c/busses/i2c-piix4.rst
+F: Documentation/i2c/busses/i2c-sis5595.rst
+F: Documentation/i2c/busses/i2c-sis630.rst
+F: Documentation/i2c/busses/i2c-sis96x.rst
+F: Documentation/i2c/busses/i2c-via.rst
+F: Documentation/i2c/busses/i2c-viapro.rst
F: drivers/i2c/busses/i2c-ali1535.c
F: drivers/i2c/busses/i2c-ali1563.c
F: drivers/i2c/busses/i2c-ali15x3.c
@@ -7610,7 +7720,7 @@
M: Neil Horman <nhorman@tuxdriver.com>
L: linux-i2c@vger.kernel.org
F: drivers/i2c/busses/i2c-ismt.c
-F: Documentation/i2c/busses/i2c-ismt
+F: Documentation/i2c/busses/i2c-ismt.rst
I2C/SMBUS STUB DRIVER
M: Jean Delvare <jdelvare@suse.com>
@@ -7666,7 +7776,7 @@
F: drivers/crypto/nx/nx-sha*
F: drivers/crypto/nx/nx.*
F: drivers/crypto/nx/nx_csbcpb.h
-F: drivers/crypto/nx/nx_debugfs.h
+F: drivers/crypto/nx/nx_debugfs.c
IBM Power Linux RAID adapter
M: Brian King <brking@us.ibm.com>
@@ -7756,6 +7866,12 @@
F: drivers/mfd/lpc_ich.c
F: drivers/gpio/gpio-ich.c
+ICY I2C DRIVER
+M: Max Staudt <max@enpas.org>
+L: linux-i2c@vger.kernel.org
+S: Maintained
+F: drivers/i2c/busses/i2c-icy.c
+
IDE SUBSYSTEM
M: "David S. Miller" <davem@davemloft.net>
L: linux-ide@vger.kernel.org
@@ -8323,6 +8439,17 @@
F: tools/power/x86/intel-speed-select/
F: include/uapi/linux/isst_if.h
+INTEL STRATIX10 FIRMWARE DRIVERS
+M: Richard Gong <richard.gong@linux.intel.com>
+L: linux-kernel@vger.kernel.org
+S: Maintained
+F: drivers/firmware/stratix10-rsu.c
+F: drivers/firmware/stratix10-svc.c
+F: include/linux/firmware/intel/stratix10-smc.h
+F: include/linux/firmware/intel/stratix10-svc-client.h
+F: Documentation/ABI/testing/sysfs-devices-platform-stratix10-rsu
+F: Documentation/devicetree/bindings/firmware/intel,stratix10-svc.txt
+
INTEL TELEMETRY DRIVER
M: Rajneesh Bhardwaj <rajneesh.bhardwaj@linux.intel.com>
M: "David E. Box" <david.e.box@linux.intel.com>
@@ -8360,7 +8487,7 @@
L: wimax@linuxwimax.org (subscribers-only)
S: Supported
W: http://linuxwimax.org
-F: Documentation/wimax/README.i2400m
+F: Documentation/admin-guide/wimax/i2400m.rst
F: drivers/net/wimax/i2400m/
F: include/uapi/linux/wimax/i2400m.h
@@ -8374,6 +8501,7 @@
S: Supported
F: Documentation/trace/intel_th.rst
F: drivers/hwtracing/intel_th/
+F: include/linux/intel_th.h
INTEL(R) TRUSTED EXECUTION TECHNOLOGY (TXT)
M: Ning Sun <ning.sun@intel.com>
@@ -8385,12 +8513,6 @@
F: include/linux/tboot.h
F: arch/x86/kernel/tboot.c
-INTEL-MID GPIO DRIVER
-M: David Cohen <david.a.cohen@linux.intel.com>
-L: linux-gpio@vger.kernel.org
-S: Maintained
-F: drivers/gpio/gpio-intel-mid.c
-
INTERCONNECT API
M: Georgi Djakov <georgi.djakov@linaro.org>
L: linux-pm@vger.kernel.org
@@ -8415,12 +8537,6 @@
S: Maintained
F: drivers/net/ethernet/sgi/ioc3-eth.c
-IOC3 SERIAL DRIVER
-M: Pat Gefre <pfg@sgi.com>
-L: linux-serial@vger.kernel.org
-S: Maintained
-F: drivers/tty/serial/ioc3_serial.c
-
IOMAP FILESYSTEM LIBRARY
M: Christoph Hellwig <hch@infradead.org>
M: Darrick J. Wong <darrick.wong@oracle.com>
@@ -8657,7 +8773,7 @@
W: http://jfs.sourceforge.net/
T: git git://github.com/kleikamp/linux-shaggy.git
S: Maintained
-F: Documentation/filesystems/jfs.txt
+F: Documentation/admin-guide/jfs.rst
F: fs/jfs/
JME NETWORK DRIVER
@@ -8933,7 +9049,7 @@
KEYS-TRUSTED
M: James Bottomley <jejb@linux.ibm.com>
-M: Jarkko Sakkinen <jarkko.sakkinen@linux.intel.com>
+M: Jarkko Sakkinen <jarkko.sakkinen@linux.intel.com>
M: Mimi Zohar <zohar@linux.ibm.com>
L: linux-integrity@vger.kernel.org
L: keyrings@vger.kernel.org
@@ -8941,10 +9057,11 @@
F: Documentation/security/keys/trusted-encrypted.rst
F: include/keys/trusted-type.h
F: security/keys/trusted.c
-F: security/keys/trusted.h
+F: include/keys/trusted.h
KEYS/KEYRINGS:
M: David Howells <dhowells@redhat.com>
+M: Jarkko Sakkinen <jarkko.sakkinen@linux.intel.com>
L: keyrings@vger.kernel.org
S: Maintained
F: Documentation/security/keys/core.rst
@@ -9000,7 +9117,7 @@
KS0108 LCD CONTROLLER DRIVER
M: Miguel Ojeda Sandonis <miguel.ojeda.sandonis@gmail.com>
S: Maintained
-F: Documentation/auxdisplay/ks0108
+F: Documentation/admin-guide/auxdisplay/ks0108.rst
F: drivers/auxdisplay/ks0108.c
F: include/linux/ks0108.h
@@ -9347,7 +9464,7 @@
LINUX KERNEL MEMORY CONSISTENCY MODEL (LKMM)
M: Alan Stern <stern@rowland.harvard.edu>
-M: Andrea Parri <andrea.parri@amarulasolutions.com>
+M: Andrea Parri <parri.andrea@gmail.com>
M: Will Deacon <will@kernel.org>
M: Peter Zijlstra <peterz@infradead.org>
M: Boqun Feng <boqun.feng@gmail.com>
@@ -9355,7 +9472,7 @@
M: David Howells <dhowells@redhat.com>
M: Jade Alglave <j.alglave@ucl.ac.uk>
M: Luc Maranget <luc.maranget@inria.fr>
-M: "Paul E. McKenney" <paulmck@linux.ibm.com>
+M: "Paul E. McKenney" <paulmck@kernel.org>
R: Akira Yokosawa <akiyks@gmail.com>
R: Daniel Lustig <dlustig@nvidia.com>
L: linux-kernel@vger.kernel.org
@@ -9589,7 +9706,7 @@
F: include/net/mac80211.h
F: net/mac80211/
F: drivers/net/wireless/mac80211_hwsim.[ch]
-F: Documentation/networking/mac80211_hwsim/README
+F: Documentation/networking/mac80211_hwsim/mac80211_hwsim.rst
MAILBOX API
M: Jassi Brar <jassisinghbrar@gmail.com>
@@ -10038,8 +10155,8 @@
L: linux-renesas-soc@vger.kernel.org
T: git git://linuxtv.org/media_tree.git
S: Supported
-F: Documentation/devicetree/bindings/media/renesas,rcar-csi2.txt
-F: Documentation/devicetree/bindings/media/rcar_vin.txt
+F: Documentation/devicetree/bindings/media/renesas,csi2.txt
+F: Documentation/devicetree/bindings/media/renesas,vin.txt
F: drivers/media/platform/rcar-vin/
MEDIA DRIVERS FOR RENESAS - VSP1
@@ -10366,7 +10483,7 @@
S: Supported
F: drivers/i2c/busses/i2c-mlxcpld.c
F: drivers/i2c/muxes/i2c-mux-mlxcpld.c
-F: Documentation/i2c/busses/i2c-mlxcpld
+F: Documentation/i2c/busses/i2c-mlxcpld.rst
MELLANOX MLXCPLD LED DRIVER
M: Vadim Pasternak <vadimp@mellanox.com>
@@ -10384,7 +10501,7 @@
MEMBARRIER SUPPORT
M: Mathieu Desnoyers <mathieu.desnoyers@efficios.com>
-M: "Paul E. McKenney" <paulmck@linux.ibm.com>
+M: "Paul E. McKenney" <paulmck@kernel.org>
L: linux-kernel@vger.kernel.org
S: Supported
F: kernel/sched/membarrier.c
@@ -10636,12 +10753,6 @@
S: Supported
F: drivers/power/reset/at91-sama5d2_shdwc.c
-MICROCHIP SAMA5D2-COMPATIBLE PIOBU GPIO
-M: Andrei Stefanescu <andrei.stefanescu@microchip.com>
-L: linux-arm-kernel@lists.infradead.org (moderated for non-subscribers)
-L: linux-gpio@vger.kernel.org
-F: drivers/gpio/gpio-sama5d2-piobu.c
-
MICROCHIP SPI DRIVER
M: Nicolas Ferre <nicolas.ferre@microchip.com>
S: Supported
@@ -10654,13 +10765,6 @@
F: drivers/misc/atmel-ssc.c
F: include/linux/atmel-ssc.h
-MICROCHIP TIMER COUNTER (TC) AND CLOCKSOURCE DRIVERS
-M: Nicolas Ferre <nicolas.ferre@microchip.com>
-L: linux-arm-kernel@lists.infradead.org (moderated for non-subscribers)
-S: Supported
-F: drivers/misc/atmel_tclib.c
-F: drivers/clocksource/tcb_clksrc.c
-
MICROCHIP USBA UDC DRIVER
M: Cristian Birsan <cristian.birsan@microchip.com>
L: linux-arm-kernel@lists.infradead.org (moderated for non-subscribers)
@@ -11166,6 +11270,7 @@
W: https://fedorahosted.org/dropwatch/
F: net/core/drop_monitor.c
F: include/uapi/linux/net_dropmon.h
+F: include/net/drop_monitor.h
NETWORKING DRIVERS
M: "David S. Miller" <davem@davemloft.net>
@@ -11345,7 +11450,6 @@
F: include/uapi/linux/nfc.h
F: drivers/nfc/
F: include/linux/platform_data/nfcmrvl.h
-F: include/linux/platform_data/nxp-nci.h
F: Documentation/devicetree/bindings/net/nfc/
NFS, SUNRPC, AND LOCKD CLIENTS
@@ -11423,7 +11527,6 @@
R: Pali Rohár <pali.rohar@gmail.com>
F: include/linux/power/bq2415x_charger.h
F: include/linux/power/bq27xxx_battery.h
-F: include/linux/power/isp1704_charger.h
F: drivers/power/supply/bq2415x_charger.c
F: drivers/power/supply/bq27xxx_battery.c
F: drivers/power/supply/bq27xxx_battery_i2c.c
@@ -11436,6 +11539,11 @@
T: git git://git.kernel.org/pub/scm/linux/kernel/git/wtarreau/nolibc.git
F: tools/include/nolibc/
+NSDEPS
+M: Matthias Maennich <maennich@google.com>
+S: Maintained
+F: scripts/nsdeps
+
NTB AMD DRIVER
M: Shyam Sundar S K <Shyam-sundar.S-k@amd.com>
L: linux-ntb@googlegroups.com
@@ -11786,6 +11894,7 @@
F: arch/arm/mach-omap2/
F: arch/arm/plat-omap/
F: arch/arm/configs/omap2plus_defconfig
+F: drivers/bus/ti-sysc.c
F: drivers/i2c/busses/i2c-omap.c
F: drivers/irqchip/irq-omap-intc.c
F: drivers/mfd/*omap*.c
@@ -11806,6 +11915,7 @@
F: drivers/regulator/twl-regulator.c
F: drivers/regulator/twl6030-regulator.c
F: include/linux/platform_data/i2c-omap.h
+F: include/linux/platform_data/ti-sysc.h
ONION OMEGA2+ BOARD
M: Harvey Hunt <harveyhuntnexus@gmail.com>
@@ -11868,6 +11978,21 @@
S: Maintained
F: drivers/media/i2c/ov5647.c
+OMNIVISION OV5670 SENSOR DRIVER
+M: Chiranjeevi Rapolu <chiranjeevi.rapolu@intel.com>
+M: Hyungwoo Yang <hyungwoo.yang@intel.com>
+L: linux-media@vger.kernel.org
+T: git git://linuxtv.org/media_tree.git
+S: Maintained
+F: drivers/media/i2c/ov5670.c
+
+OMNIVISION OV5675 SENSOR DRIVER
+M: Shawn Tu <shawnx.tu@intel.com>
+L: linux-media@vger.kernel.org
+T: git git://linuxtv.org/media_tree.git
+S: Maintained
+F: drivers/media/i2c/ov5675.c
+
OMNIVISION OV5695 SENSOR DRIVER
M: Shunqian Zheng <zhengsq@rock-chips.com>
L: linux-media@vger.kernel.org
@@ -11989,7 +12114,7 @@
L: linux-i2c@vger.kernel.org
S: Maintained
F: Documentation/devicetree/bindings/i2c/i2c-ocores.txt
-F: Documentation/i2c/busses/i2c-ocores
+F: Documentation/i2c/busses/i2c-ocores.rst
F: drivers/i2c/busses/i2c-ocores.c
F: include/linux/platform_data/i2c-ocores.h
@@ -12112,7 +12237,7 @@
S: Supported
F: lib/packing.c
F: include/linux/packing.h
-F: Documentation/packing.txt
+F: Documentation/core-api/packing.rst
PADATA PARALLEL EXECUTION MECHANISM
M: Steffen Klassert <steffen.klassert@secunet.com>
@@ -12465,16 +12590,18 @@
PCI NATIVE HOST BRIDGE AND ENDPOINT DRIVERS
M: Lorenzo Pieralisi <lorenzo.pieralisi@arm.com>
+R: Andrew Murray <andrew.murray@arm.com>
L: linux-pci@vger.kernel.org
Q: http://patchwork.ozlabs.org/project/linux-pci/list/
T: git git://git.kernel.org/pub/scm/linux/kernel/git/lpieralisi/pci.git/
S: Supported
F: drivers/pci/controller/
-PCIE DRIVER FOR ANNAPURNA LABS
+PCIE DRIVER FOR AMAZON ANNAPURNA LABS
M: Jonathan Chocron <jonnyc@amazon.com>
L: linux-pci@vger.kernel.org
S: Maintained
+F: Documentation/devicetree/bindings/pci/pcie-al.txt
F: drivers/pci/controller/dwc/pcie-al.c
PCIE DRIVER FOR AMLOGIC MESON
@@ -12593,6 +12720,14 @@
S: Maintained
F: drivers/platform/x86/peaq-wmi.c
+PENSANDO ETHERNET DRIVERS
+M: Shannon Nelson <snelson@pensando.io>
+M: Pensando Drivers <drivers@pensando.io>
+L: netdev@vger.kernel.org
+S: Supported
+F: Documentation/networking/device_drivers/pensando/ionic.rst
+F: drivers/net/ethernet/pensando/
+
PER-CPU MEMORY ALLOCATOR
M: Dennis Zhou <dennis@kernel.org>
M: Tejun Heo <tj@kernel.org>
@@ -12613,6 +12748,7 @@
M: Peter Zijlstra <peterz@infradead.org>
M: Ingo Molnar <mingo@redhat.com>
M: Arnaldo Carvalho de Melo <acme@kernel.org>
+R: Mark Rutland <mark.rutland@arm.com>
R: Alexander Shishkin <alexander.shishkin@linux.intel.com>
R: Jiri Olsa <jolsa@redhat.com>
R: Namhyung Kim <namhyung@kernel.org>
@@ -12645,6 +12781,12 @@
F: Documentation/input/devices/pxrc.rst
F: drivers/input/joystick/pxrc.c
+FLYSKY FSIA6B RC RECEIVER
+M: Markus Koch <markus@notsyncing.net>
+L: linux-input@vger.kernel.org
+S: Maintained
+F: drivers/input/joystick/fsia6b.c
+
PHONET PROTOCOL
M: Remi Denis-Courmont <courmisch@gmail.com>
S: Supported
@@ -12702,6 +12844,7 @@
L: linux-gpio@vger.kernel.org
S: Supported
F: drivers/pinctrl/pinctrl-at91*
+F: drivers/gpio/gpio-sama5d2-piobu.c
PIN CONTROLLER - FREESCALE
M: Dong Aisheng <aisheng.dong@nxp.com>
@@ -12798,6 +12941,12 @@
F: drivers/video/fbdev/fb-puv3.c
F: drivers/rtc/rtc-puv3.c
+PLANTOWER PMS7003 AIR POLLUTION SENSOR DRIVER
+M: Tomasz Duszynski <tduszyns@gmail.com>
+S: Maintained
+F: drivers/iio/chemical/pms7003.c
+F: Documentation/devicetree/bindings/iio/chemical/plantower,pms7003.yaml
+
PMBUS HARDWARE MONITORING DRIVERS
M: Guenter Roeck <linux@roeck-us.net>
L: linux-hwmon@vger.kernel.org
@@ -13098,9 +13247,11 @@
PWM SUBSYSTEM
M: Thierry Reding <thierry.reding@gmail.com>
+R: Uwe Kleine-König <u.kleine-koenig@pengutronix.de>
L: linux-pwm@vger.kernel.org
S: Maintained
T: git git://git.kernel.org/pub/scm/linux/kernel/git/thierry.reding/linux-pwm.git
+Q: https://patchwork.ozlabs.org/project/linux-pwm/list/
F: Documentation/driver-api/pwm.rst
F: Documentation/devicetree/bindings/pwm/
F: include/linux/pwm.h
@@ -13109,6 +13260,7 @@
F: include/linux/pwm_backlight.h
F: drivers/gpio/gpio-mvebu.c
F: Documentation/devicetree/bindings/gpio/gpio-mvebu.txt
+K: pwm_(config|apply_state|ops)
PXA GPIO DRIVER
M: Robert Jarzmik <robert.jarzmik@free.fr>
@@ -13240,7 +13392,7 @@
M: GR-Linux-NIC-Dev@marvell.com
L: netdev@vger.kernel.org
S: Supported
-F: drivers/net/ethernet/qlogic/qlge/
+F: drivers/staging/qlge/
QM1D1B0004 MEDIA DRIVER
M: Akihiro Tsukada <tskd08@gmail.com>
@@ -13308,8 +13460,8 @@
M: Ilia Lin <ilia.lin@kernel.org>
L: linux-pm@vger.kernel.org
S: Maintained
-F: Documentation/devicetree/bindings/opp/kryo-cpufreq.txt
-F: drivers/cpufreq/qcom-cpufreq-kryo.c
+F: Documentation/devicetree/bindings/opp/qcom-nvmem-cpufreq.txt
+F: drivers/cpufreq/qcom-cpufreq-nvmem.c
QUALCOMM EMAC GIGABIT ETHERNET DRIVER
M: Timur Tabi <timur@kernel.org>
@@ -13333,9 +13485,8 @@
F: drivers/i2c/busses/i2c-qcom-geni.c
QUALCOMM HEXAGON ARCHITECTURE
-M: Richard Kuo <rkuo@codeaurora.org>
+M: Brian Cain <bcain@codeaurora.org>
L: linux-hexagon@vger.kernel.org
-T: git git://git.kernel.org/pub/scm/linux/kernel/git/rkuo/linux-hexagon-kernel.git
S: Supported
F: arch/hexagon/
@@ -13499,7 +13650,7 @@
F: drivers/net/wireless/ray*
RCUTORTURE TEST FRAMEWORK
-M: "Paul E. McKenney" <paulmck@linux.ibm.com>
+M: "Paul E. McKenney" <paulmck@kernel.org>
M: Josh Triplett <josh@joshtriplett.org>
R: Steven Rostedt <rostedt@goodmis.org>
R: Mathieu Desnoyers <mathieu.desnoyers@efficios.com>
@@ -13546,7 +13697,7 @@
F: Documentation/x86/resctrl*
READ-COPY UPDATE (RCU)
-M: "Paul E. McKenney" <paulmck@linux.ibm.com>
+M: "Paul E. McKenney" <paulmck@kernel.org>
M: Josh Triplett <josh@joshtriplett.org>
R: Steven Rostedt <rostedt@goodmis.org>
R: Mathieu Desnoyers <mathieu.desnoyers@efficios.com>
@@ -13618,7 +13769,7 @@
M: Ohad Ben-Cohen <ohad@wizery.com>
M: Bjorn Andersson <bjorn.andersson@linaro.org>
L: linux-remoteproc@vger.kernel.org
-T: git git://git.kernel.org/pub/scm/linux/kernel/git/ohad/remoteproc.git
+T: git git://git.kernel.org/pub/scm/linux/kernel/git/andersson/remoteproc.git rproc-next
S: Maintained
F: Documentation/devicetree/bindings/remoteproc/
F: Documentation/ABI/testing/sysfs-class-remoteproc
@@ -13631,7 +13782,7 @@
M: Ohad Ben-Cohen <ohad@wizery.com>
M: Bjorn Andersson <bjorn.andersson@linaro.org>
L: linux-remoteproc@vger.kernel.org
-T: git git://git.kernel.org/pub/scm/linux/kernel/git/ohad/rpmsg.git
+T: git git://git.kernel.org/pub/scm/linux/kernel/git/andersson/remoteproc.git rpmsg-next
S: Maintained
F: drivers/rpmsg/
F: Documentation/rpmsg.txt
@@ -13651,7 +13802,7 @@
RENESAS EMEV2 I2C DRIVER
M: Wolfram Sang <wsa+renesas@sang-engineering.com>
S: Supported
-F: Documentation/devicetree/bindings/i2c/i2c-emev2.txt
+F: Documentation/devicetree/bindings/i2c/renesas,iic-emev2.txt
F: drivers/i2c/busses/i2c-emev2.c
RENESAS ETHERNET DRIVERS
@@ -13673,15 +13824,15 @@
RENESAS R-CAR I2C DRIVERS
M: Wolfram Sang <wsa+renesas@sang-engineering.com>
S: Supported
-F: Documentation/devicetree/bindings/i2c/i2c-rcar.txt
-F: Documentation/devicetree/bindings/i2c/i2c-sh_mobile.txt
+F: Documentation/devicetree/bindings/i2c/renesas,i2c.txt
+F: Documentation/devicetree/bindings/i2c/renesas,iic.txt
F: drivers/i2c/busses/i2c-rcar.c
F: drivers/i2c/busses/i2c-sh_mobile.c
RENESAS RIIC DRIVER
M: Chris Brandt <chris.brandt@renesas.com>
S: Supported
-F: Documentation/devicetree/bindings/i2c/i2c-riic.txt
+F: Documentation/devicetree/bindings/i2c/renesas,riic.txt
F: drivers/i2c/busses/i2c-riic.c
RENESAS USB PHY DRIVER
@@ -13704,7 +13855,7 @@
RESTARTABLE SEQUENCES SUPPORT
M: Mathieu Desnoyers <mathieu.desnoyers@efficios.com>
M: Peter Zijlstra <peterz@infradead.org>
-M: "Paul E. McKenney" <paulmck@linux.ibm.com>
+M: "Paul E. McKenney" <paulmck@kernel.org>
M: Boqun Feng <boqun.feng@gmail.com>
L: linux-kernel@vger.kernel.org
S: Supported
@@ -13767,7 +13918,8 @@
F: Documentation/ABI/*/sysfs-driver-hid-roccat*
ROCKCHIP RASTER 2D GRAPHIC ACCELERATION UNIT DRIVER
-M: Jacob chen <jacob2.chen@rock-chips.com>
+M: Jacob Chen <jacob-chen@iotwrt.com>
+M: Ezequiel Garcia <ezequiel@collabora.com>
L: linux-media@vger.kernel.org
S: Maintained
F: drivers/media/platform/rockchip/rga/
@@ -13777,7 +13929,7 @@
M: Ezequiel Garcia <ezequiel@collabora.com>
L: linux-media@vger.kernel.org
S: Maintained
-F: drivers/staging/media/platform/hantro/
+F: drivers/staging/media/hantro/
F: Documentation/devicetree/bindings/media/rockchip-vpu.txt
ROCKER DRIVER
@@ -14135,6 +14287,8 @@
L: linux-crypto@vger.kernel.org
L: linux-samsung-soc@vger.kernel.org
S: Maintained
+F: Documentation/devicetree/bindings/crypto/samsung-slimsss.txt
+F: Documentation/devicetree/bindings/crypto/samsung-sss.txt
F: drivers/crypto/s5p-sss.c
SAMSUNG S5P/EXYNOS4 SOC SERIES CAMERA SUBSYSTEM DRIVERS
@@ -14155,6 +14309,8 @@
F: drivers/clk/samsung/
F: include/dt-bindings/clock/exynos*.h
F: Documentation/devicetree/bindings/clock/exynos*.txt
+F: Documentation/devicetree/bindings/clock/samsung,s3c*
+F: Documentation/devicetree/bindings/clock/samsung,s5p*
SAMSUNG SPI DRIVERS
M: Kukjin Kim <kgene@kernel.org>
@@ -14205,6 +14361,12 @@
SCHEDULER
M: Ingo Molnar <mingo@redhat.com>
M: Peter Zijlstra <peterz@infradead.org>
+M: Juri Lelli <juri.lelli@redhat.com> (SCHED_DEADLINE)
+M: Vincent Guittot <vincent.guittot@linaro.org> (SCHED_NORMAL)
+R: Dietmar Eggemann <dietmar.eggemann@arm.com> (SCHED_NORMAL)
+R: Steven Rostedt <rostedt@goodmis.org> (SCHED_FIFO/SCHED_RR)
+R: Ben Segall <bsegall@google.com> (CONFIG_CFS_BANDWIDTH)
+R: Mel Gorman <mgorman@suse.de> (CONFIG_NUMA_BALANCING)
L: linux-kernel@vger.kernel.org
T: git git://git.kernel.org/pub/scm/linux/kernel/git/tip/tip.git sched/core
S: Maintained
@@ -14299,7 +14461,7 @@
SCx200 CPU SUPPORT
M: Jim Cromie <jim.cromie@gmail.com>
S: Odd Fixes
-F: Documentation/i2c/busses/scx200_acb
+F: Documentation/i2c/busses/scx200_acb.rst
F: arch/x86/platform/scx200/
F: drivers/watchdog/scx200_wdt.c
F: drivers/i2c/busses/scx200*
@@ -14740,7 +14902,7 @@
SLEEPABLE READ-COPY UPDATE (SRCU)
M: Lai Jiangshan <jiangshanlai@gmail.com>
-M: "Paul E. McKenney" <paulmck@linux.ibm.com>
+M: "Paul E. McKenney" <paulmck@kernel.org>
M: Josh Triplett <josh@joshtriplett.org>
R: Steven Rostedt <rostedt@goodmis.org>
R: Mathieu Desnoyers <mathieu.desnoyers@efficios.com>
@@ -15224,13 +15386,6 @@
S: Odd Fixes
F: drivers/staging/comedi/
-STAGING - EROFS FILE SYSTEM
-M: Gao Xiang <gaoxiang25@huawei.com>
-M: Chao Yu <yuchao0@huawei.com>
-L: linux-erofs@lists.ozlabs.org
-S: Maintained
-F: drivers/staging/erofs/
-
STAGING - FIELDBUS SUBSYSTEM
M: Sven Van Asbroeck <TheSven73@gmail.com>
S: Maintained
@@ -15518,7 +15673,7 @@
SYNOPSYS DESIGNWARE AXI DMAC DRIVER
M: Eugeniy Paltsev <Eugeniy.Paltsev@synopsys.com>
S: Maintained
-F: drivers/dma/dwi-axi-dmac/
+F: drivers/dma/dw-axi-dmac/
F: Documentation/devicetree/bindings/dma/snps,dw-axi-dmac.txt
SYNOPSYS DESIGNWARE DMAC DRIVER
@@ -15575,6 +15730,7 @@
F: drivers/cpufreq/sc[mp]i-cpufreq.c
F: drivers/firmware/arm_scpi.c
F: drivers/firmware/arm_scmi/
+F: drivers/reset/reset-scmi.c
F: include/linux/sc[mp]i_protocol.h
SYSTEM RESET/SHUTDOWN DRIVERS
@@ -15883,6 +16039,7 @@
F: include/linux/soc/ti/ti_sci_protocol.h
F: Documentation/devicetree/bindings/soc/ti/sci-pm-domain.txt
F: drivers/soc/ti/ti_sci_pm_domains.c
+F: include/dt-bindings/soc/ti,sci_pm_domain.h
F: Documentation/devicetree/bindings/reset/ti,sci-reset.txt
F: Documentation/devicetree/bindings/clock/ti,sci-clk.txt
F: drivers/clk/keystone/sci-clk.c
@@ -15919,6 +16076,7 @@
M: Zhang Rui <rui.zhang@intel.com>
M: Eduardo Valentin <edubezval@gmail.com>
R: Daniel Lezcano <daniel.lezcano@linaro.org>
+R: Amit Kucheria <amit.kucheria@verdurent.com>
L: linux-pm@vger.kernel.org
T: git git://git.kernel.org/pub/scm/linux/kernel/git/rzhang/linux.git
T: git git://git.kernel.org/pub/scm/linux/kernel/git/evalenti/linux-soc-thermal.git
@@ -15936,7 +16094,7 @@
M: Javi Merino <javi.merino@kernel.org>
L: linux-pm@vger.kernel.org
S: Supported
-F: Documentation/thermal/cpu-cooling-api.rst
+F: Documentation/driver-api/thermal/cpu-cooling-api.rst
F: drivers/thermal/cpu_cooling.c
F: include/linux/cpu_cooling.h
@@ -16237,7 +16395,7 @@
TORTURE-TEST MODULES
M: Davidlohr Bueso <dave@stgolabs.net>
-M: "Paul E. McKenney" <paulmck@linux.ibm.com>
+M: "Paul E. McKenney" <paulmck@kernel.org>
M: Josh Triplett <josh@joshtriplett.org>
L: linux-kernel@vger.kernel.org
S: Supported
@@ -16459,7 +16617,7 @@
UFS FILESYSTEM
M: Evgeniy Dushistov <dushistov@mail.ru>
S: Maintained
-F: Documentation/filesystems/ufs.txt
+F: Documentation/admin-guide/ufs.rst
F: fs/ufs/
UHID USERSPACE HID IO DRIVER:
@@ -16477,11 +16635,9 @@
F: include/linux/ulpi/
ULTRA-WIDEBAND (UWB) SUBSYSTEM:
-L: linux-usb@vger.kernel.org
-S: Orphan
-F: drivers/uwb/
-F: include/linux/uwb.h
-F: include/linux/uwb/
+L: devel@driverdev.osuosl.org
+S: Obsolete
+F: drivers/staging/uwb/
UNICODE SUBSYSTEM:
M: Gabriel Krisman Bertazi <krisman@collabora.com>
@@ -17125,6 +17281,18 @@
F: drivers/s390/virtio/
F: arch/s390/include/uapi/asm/virtio-ccw.h
+VIRTIO FILE SYSTEM
+M: Vivek Goyal <vgoyal@redhat.com>
+M: Stefan Hajnoczi <stefanha@redhat.com>
+M: Miklos Szeredi <miklos@szeredi.hu>
+L: virtualization@lists.linux-foundation.org
+L: linux-fsdevel@vger.kernel.org
+W: https://virtio-fs.gitlab.io/
+S: Supported
+F: fs/fuse/virtio_fs.c
+F: include/uapi/linux/virtio_fs.h
+F: Documentation/filesystems/virtiofs.rst
+
VIRTIO GPU DRIVER
M: David Airlie <airlied@linux.ie>
M: Gerd Hoffmann <kraxel@redhat.com>
@@ -17214,6 +17382,7 @@
L: virtualization@lists.linux-foundation.org
S: Supported
F: arch/x86/kernel/cpu/vmware.c
+F: arch/x86/include/asm/vmware.h
VMWARE PVRDMA DRIVER
M: Adit Ranadive <aditr@vmware.com>
@@ -17263,6 +17432,7 @@
F: drivers/regulator/
F: include/dt-bindings/regulator/
F: include/linux/regulator/
+K: regulator_get_optional
VRF
M: David Ahern <dsa@cumulusnetworks.com>
@@ -17377,7 +17547,7 @@
L: wimax@linuxwimax.org (subscribers-only)
S: Supported
W: http://linuxwimax.org
-F: Documentation/wimax/README.wimax
+F: Documentation/admin-guide/wimax/wimax.rst
F: include/linux/wimax/debug.h
F: include/net/wimax.h
F: include/uapi/linux/wimax.h
@@ -17531,7 +17701,7 @@
M: Andy Shevchenko <andy@infradead.org>
L: platform-driver-x86@vger.kernel.org
T: git git://git.infradead.org/linux-platform-drivers-x86.git
-S: Maintained
+S: Odd Fixes
F: drivers/platform/x86/
F: drivers/platform/olpc/
@@ -17646,7 +17816,7 @@
XEN NETWORK BACKEND DRIVER
M: Wei Liu <wei.liu@kernel.org>
-M: Paul Durrant <paul.durrant@citrix.com>
+M: Paul Durrant <paul@xen.org>
L: xen-devel@lists.xenproject.org (moderated for non-subscribers)
L: netdev@vger.kernel.org
S: Supported
@@ -17699,8 +17869,7 @@
F: include/uapi/linux/fsmap.h
XILINX AXI ETHERNET DRIVER
-M: Anirudha Sarangi <anirudh@xilinx.com>
-M: John Linn <John.Linn@xilinx.com>
+M: Radhey Shyam Pandey <radhey.shyam.pandey@xilinx.com>
S: Maintained
F: drivers/net/ethernet/xilinx/xilinx_axienet*
@@ -17720,6 +17889,17 @@
F: drivers/media/platform/xilinx/
F: include/uapi/linux/xilinx-v4l2-controls.h
+XILINX SD-FEC IP CORES
+M: Derek Kiernan <derek.kiernan@xilinx.com>
+M: Dragan Cvetic <dragan.cvetic@xilinx.com>
+S: Maintained
+F: Documentation/devicetree/bindings/misc/xlnx,sd-fec.txt
+F: Documentation/misc-devices/xilinx_sdfec.rst
+F: drivers/misc/xilinx_sdfec.c
+F: drivers/misc/Kconfig
+F: drivers/misc/Makefile
+F: include/uapi/misc/xilinx_sdfec.h
+
XILLYBUS DRIVER
M: Eli Billauer <eli.billauer@gmail.com>
L: linux-kernel@vger.kernel.org
@@ -17829,14 +18009,6 @@
F: mm/zpool.c
F: include/linux/zpool.h
-ZR36067 VIDEO FOR LINUX DRIVER
-L: mjpeg-users@lists.sourceforge.net
-L: linux-media@vger.kernel.org
-W: http://mjpeg.sourceforge.net/driver-zoran/
-T: hg https://linuxtv.org/hg/v4l-dvb
-S: Odd Fixes
-F: drivers/staging/media/zoran/
-
ZRAM COMPRESSED RAM BLOCK DEVICE DRVIER
M: Minchan Kim <minchan@kernel.org>
M: Nitin Gupta <ngupta@vflare.org>
diff --git a/Makefile b/Makefile
index 9b08f63..d456746 100644
--- a/Makefile
+++ b/Makefile
@@ -2,7 +2,7 @@
VERSION = 5
PATCHLEVEL = 3
SUBLEVEL = 0
-EXTRAVERSION = -rc8
+EXTRAVERSION =
NAME = Bobtail Squid
# *DOCUMENTATION*
@@ -230,6 +230,8 @@
export KBUILD_CHECKSRC KBUILD_EXTMOD
+extmod-prefix = $(if $(KBUILD_EXTMOD),$(KBUILD_EXTMOD)/)
+
ifeq ($(abs_srctree),$(abs_objtree))
# building in the source tree
srctree := .
@@ -271,52 +273,62 @@
%asm-generic kernelversion %src-pkg
no-sync-config-targets := $(no-dot-config-targets) install %install \
kernelrelease
+single-targets := %.a %.i %.ko %.lds %.ll %.lst %.mod %.o %.s %.symtypes %/
-config-targets := 0
-mixed-targets := 0
-dot-config := 1
-may-sync-config := 1
+config-build :=
+mixed-build :=
+need-config := 1
+may-sync-config := 1
+single-build :=
ifneq ($(filter $(no-dot-config-targets), $(MAKECMDGOALS)),)
ifeq ($(filter-out $(no-dot-config-targets), $(MAKECMDGOALS)),)
- dot-config := 0
+ need-config :=
endif
endif
ifneq ($(filter $(no-sync-config-targets), $(MAKECMDGOALS)),)
ifeq ($(filter-out $(no-sync-config-targets), $(MAKECMDGOALS)),)
- may-sync-config := 0
+ may-sync-config :=
endif
endif
ifneq ($(KBUILD_EXTMOD),)
- may-sync-config := 0
+ may-sync-config :=
endif
ifeq ($(KBUILD_EXTMOD),)
ifneq ($(filter config %config,$(MAKECMDGOALS)),)
- config-targets := 1
+ config-build := 1
ifneq ($(words $(MAKECMDGOALS)),1)
- mixed-targets := 1
+ mixed-build := 1
endif
endif
endif
+# We cannot build single targets and the others at the same time
+ifneq ($(filter $(single-targets), $(MAKECMDGOALS)),)
+ single-build := 1
+ ifneq ($(filter-out $(single-targets), $(MAKECMDGOALS)),)
+ mixed-build := 1
+ endif
+endif
+
# For "make -j clean all", "make -j mrproper defconfig all", etc.
ifneq ($(filter $(clean-targets),$(MAKECMDGOALS)),)
ifneq ($(filter-out $(clean-targets),$(MAKECMDGOALS)),)
- mixed-targets := 1
+ mixed-build := 1
endif
endif
# install and modules_install need also be processed one by one
ifneq ($(filter install,$(MAKECMDGOALS)),)
ifneq ($(filter modules_install,$(MAKECMDGOALS)),)
- mixed-targets := 1
+ mixed-build := 1
endif
endif
-ifeq ($(mixed-targets),1)
+ifdef mixed-build
# ===========================================================================
# We're called with mixed targets (*config and build targets).
# Handle them one by one.
@@ -332,7 +344,7 @@
$(MAKE) -f $(srctree)/Makefile $$i; \
done
-else
+else # !mixed-build
include scripts/Kbuild.include
@@ -392,9 +404,7 @@
export KCONFIG_CONFIG
# SHELL used by kbuild
-CONFIG_SHELL := $(shell if [ -x "$$BASH" ]; then echo $$BASH; \
- else if [ -x /bin/bash ]; then echo /bin/bash; \
- else echo sh; fi ; fi)
+CONFIG_SHELL := sh
HOST_LFS_CFLAGS := $(shell getconf LFS_CFLAGS 2>/dev/null)
HOST_LFS_LDFLAGS := $(shell getconf LFS_LDFLAGS 2>/dev/null)
@@ -431,6 +441,7 @@
PYTHON2 = python2
PYTHON3 = python3
CHECK = sparse
+BASH = bash
CHECKFLAGS := -D__linux__ -Dlinux -D__STDC__ -Dunix -D__unix__ \
-Wbitwise -Wno-return-void -Wno-unknown-attribute $(CF)
@@ -470,12 +481,13 @@
KBUILD_CFLAGS_KERNEL :=
KBUILD_AFLAGS_MODULE := -DMODULE
KBUILD_CFLAGS_MODULE := -DMODULE
-KBUILD_LDFLAGS_MODULE := -T $(srctree)/scripts/module-common.lds
+KBUILD_LDFLAGS_MODULE :=
+export KBUILD_LDS_MODULE := $(srctree)/scripts/module-common.lds
KBUILD_LDFLAGS :=
GCC_PLUGINS_CFLAGS :=
CLANG_FLAGS :=
-export ARCH SRCARCH CONFIG_SHELL HOSTCC KBUILD_HOSTCFLAGS CROSS_COMPILE AS LD CC
+export ARCH SRCARCH CONFIG_SHELL BASH HOSTCC KBUILD_HOSTCFLAGS CROSS_COMPILE AS LD CC
export CPP AR NM STRIP OBJCOPY OBJDUMP OBJSIZE PAHOLE LEX YACC AWK INSTALLKERNEL
export PERL PYTHON PYTHON2 PYTHON3 CHECK CHECKFLAGS MAKE UTS_MACHINE HOSTCXX
export KBUILD_HOSTCXXFLAGS KBUILD_HOSTLDFLAGS KBUILD_HOSTLDLIBS LDFLAGS_MODULE
@@ -506,6 +518,7 @@
$(Q)rm -f .tmp_quiet_recordmcount
PHONY += outputmakefile
+# Before starting out-of-tree build, make sure the source tree is clean.
# outputmakefile generates a Makefile in the output directory, if using a
# separate output directory. This allows convenient use of make in the
# output directory.
@@ -513,6 +526,15 @@
# ignore whole output directory
outputmakefile:
ifdef building_out_of_srctree
+ $(Q)if [ -f $(srctree)/.config -o \
+ -d $(srctree)/include/config -o \
+ -d $(srctree)/arch/$(SRCARCH)/include/generated ]; then \
+ echo >&2 "***"; \
+ echo >&2 "*** The source tree is not clean, please run 'make$(if $(findstring command line, $(origin ARCH)), ARCH=$(ARCH)) mrproper'"; \
+ echo >&2 "*** in $(abs_srctree)";\
+ echo >&2 "***"; \
+ false; \
+ fi
$(Q)ln -fsn $(srctree) source
$(Q)$(CONFIG_SHELL) $(srctree)/scripts/mkmakefile $(srctree)
$(Q)test -e .gitignore || \
@@ -544,7 +566,7 @@
# and from include/config/auto.conf.cmd to detect the compiler upgrade.
CC_VERSION_TEXT = $(shell $(CC) --version 2>/dev/null | head -n 1)
-ifeq ($(config-targets),1)
+ifdef config-build
# ===========================================================================
# *config targets only - make sure prerequisites are updated, and descend
# in scripts/kconfig to make the *config target
@@ -555,13 +577,13 @@
include arch/$(SRCARCH)/Makefile
export KBUILD_DEFCONFIG KBUILD_KCONFIG CC_VERSION_TEXT
-config: scripts_basic outputmakefile FORCE
+config: outputmakefile scripts_basic FORCE
$(Q)$(MAKE) $(build)=scripts/kconfig $@
-%config: scripts_basic outputmakefile FORCE
+%config: outputmakefile scripts_basic FORCE
$(Q)$(MAKE) $(build)=scripts/kconfig $@
-else
+else #!config-build
# ===========================================================================
# Build targets only - this includes vmlinux, arch specific targets, clean
# targets and others. In general all targets except *config targets.
@@ -604,7 +626,7 @@
export KBUILD_MODULES KBUILD_BUILTIN
-ifeq ($(dot-config),1)
+ifdef need-config
include include/config/auto.conf
endif
@@ -645,15 +667,10 @@
export RETPOLINE_CFLAGS
export RETPOLINE_VDSO_CFLAGS
-# The arch Makefile can set ARCH_{CPP,A,C}FLAGS to override the default
-# values of the respective KBUILD_* variables
-ARCH_CPPFLAGS :=
-ARCH_AFLAGS :=
-ARCH_CFLAGS :=
include arch/$(SRCARCH)/Makefile
-ifeq ($(dot-config),1)
-ifeq ($(may-sync-config),1)
+ifdef need-config
+ifdef may-sync-config
# Read in dependencies to all Kconfig* files, make sure to run syncconfig if
# changes are detected. This should be included after arch/$(SRCARCH)/Makefile
# because some architectures define CROSS_COMPILE there.
@@ -676,7 +693,7 @@
# The syncconfig should be executed only once to make all the targets.
%/auto.conf %/auto.conf.cmd %/tristate.conf: $(KCONFIG_CONFIG)
$(Q)$(MAKE) -f $(srctree)/Makefile syncconfig
-else
+else # !may-sync-config
# External modules and some install targets need include/generated/autoconf.h
# and include/config/auto.conf but do not care if they are up-to-date.
# Use auto.conf to trigger the test
@@ -692,7 +709,7 @@
/bin/false)
endif # may-sync-config
-endif # $(dot-config)
+endif # need-config
KBUILD_CFLAGS += $(call cc-option,-fno-delete-null-pointer-checks,)
KBUILD_CFLAGS += $(call cc-disable-warning,frame-address,)
@@ -700,10 +717,12 @@
KBUILD_CFLAGS += $(call cc-disable-warning, format-overflow)
KBUILD_CFLAGS += $(call cc-disable-warning, address-of-packed-member)
-ifdef CONFIG_CC_OPTIMIZE_FOR_SIZE
-KBUILD_CFLAGS += -Os
-else
-KBUILD_CFLAGS += -O2
+ifdef CONFIG_CC_OPTIMIZE_FOR_PERFORMANCE
+KBUILD_CFLAGS += -O2
+else ifdef CONFIG_CC_OPTIMIZE_FOR_PERFORMANCE_O3
+KBUILD_CFLAGS += -O3
+else ifdef CONFIG_CC_OPTIMIZE_FOR_SIZE
+KBUILD_CFLAGS += -Os
endif
ifdef CONFIG_CC_DISABLE_WARN_MAYBE_UNINITIALIZED
@@ -751,6 +770,11 @@
# These warnings generated too much noise in a regular build.
# Use make W=1 to enable them (see scripts/Makefile.extrawarn)
KBUILD_CFLAGS += -Wno-unused-but-set-variable
+
+# Warn about unmarked fall-throughs in switch statement.
+# Disabled for clang while comment to attribute conversion happens and
+# https://github.com/ClangBuiltLinux/linux/issues/636 is discussed.
+KBUILD_CFLAGS += $(call cc-option,-Wimplicit-fallthrough,)
endif
KBUILD_CFLAGS += $(call cc-disable-warning, unused-const-variable)
@@ -845,9 +869,6 @@
# warn about C99 declaration after statement
KBUILD_CFLAGS += -Wdeclaration-after-statement
-# Warn about unmarked fall-throughs in switch statement.
-KBUILD_CFLAGS += $(call cc-option,-Wimplicit-fallthrough,)
-
# Variable Length Arrays (VLAs) should not be used anywhere in the kernel
KBUILD_CFLAGS += -Wvla
@@ -900,11 +921,10 @@
include scripts/Makefile.extrawarn
include scripts/Makefile.ubsan
-# Add any arch overrides and user supplied CPPFLAGS, AFLAGS and CFLAGS as the
-# last assignments
-KBUILD_CPPFLAGS += $(ARCH_CPPFLAGS) $(KCPPFLAGS)
-KBUILD_AFLAGS += $(ARCH_AFLAGS) $(KAFLAGS)
-KBUILD_CFLAGS += $(ARCH_CFLAGS) $(KCFLAGS)
+# Add user supplied CPPFLAGS, AFLAGS and CFLAGS as the last assignments
+KBUILD_CPPFLAGS += $(KCPPFLAGS)
+KBUILD_AFLAGS += $(KAFLAGS)
+KBUILD_CFLAGS += $(KCFLAGS)
KBUILD_LDFLAGS_MODULE += --build-id
LDFLAGS_vmlinux += --build-id
@@ -913,6 +933,10 @@
LDFLAGS_vmlinux += $(call ld-option, -X,)
endif
+ifeq ($(CONFIG_RELR),y)
+LDFLAGS_vmlinux += --pack-dyn-relocs=relr
+endif
+
# insure the checker run with the right endianness
CHECKFLAGS += $(if $(CONFIG_CPU_BIG_ENDIAN),-mbig-endian,-mlittle-endian)
@@ -1003,7 +1027,7 @@
PHONY += prepare0
-export MODORDER := $(if $(KBUILD_EXTMOD),$(KBUILD_EXTMOD)/)modules.order
+export MODORDER := $(extmod-prefix)modules.order
ifeq ($(KBUILD_EXTMOD),)
core-y += kernel/ certs/ mm/ fs/ ipc/ security/ crypto/ block/
@@ -1016,6 +1040,9 @@
$(patsubst %/,%,$(filter %/, $(init-) $(core-) \
$(drivers-) $(net-) $(libs-) $(virt-))))
+build-dirs := $(vmlinux-dirs)
+clean-dirs := $(vmlinux-alldirs)
+
init-y := $(patsubst %/, %/built-in.a, $(init-y))
core-y := $(patsubst %/, %/built-in.a, $(core-y))
drivers-y := $(patsubst %/, %/built-in.a, $(drivers-y))
@@ -1038,7 +1065,7 @@
# Recurse until adjust_autoksyms.sh is satisfied
PHONY += autoksyms_recursive
ifdef CONFIG_TRIM_UNUSED_KSYMS
-autoksyms_recursive: $(vmlinux-deps) modules.order
+autoksyms_recursive: descend modules.order
$(Q)$(CONFIG_SHELL) $(srctree)/scripts/adjust_autoksyms.sh \
"$(MAKE) -f $(srctree)/Makefile vmlinux"
endif
@@ -1070,17 +1097,7 @@
# The actual objects are generated when descending,
# make sure no implicit rule kicks in
-$(sort $(vmlinux-deps)): $(vmlinux-dirs) ;
-
-# Handle descending into subdirectories listed in $(vmlinux-dirs)
-# Preset locale variables to speed up the build process. Limit locale
-# tweaks to this spot to avoid wrong language settings when running
-# make menuconfig etc.
-# Error messages still appears in the original language
-
-PHONY += $(vmlinux-dirs)
-$(vmlinux-dirs): prepare
- $(Q)$(MAKE) $(build)=$@ need-builtin=1 need-modorder=1
+$(sort $(vmlinux-deps)): descend ;
filechk_kernel.release = \
echo "$(KERNELVERSION)$$($(CONFIG_SHELL) $(srctree)/scripts/setlocalversion $(srctree))"
@@ -1102,24 +1119,9 @@
# archprepare is used in arch Makefiles and when processed asm symlink,
# version.h and scripts_basic is processed / created.
-PHONY += prepare archprepare prepare3
+PHONY += prepare archprepare
-# prepare3 is used to check if we are building in a separate output directory,
-# and if so do:
-# 1) Check that make has not been executed in the kernel src $(srctree)
-prepare3: include/config/kernel.release
-ifdef building_out_of_srctree
- @$(kecho) ' Using $(srctree) as source for kernel'
- $(Q)if [ -f $(srctree)/.config -o \
- -d $(srctree)/include/config -o \
- -d $(srctree)/arch/$(SRCARCH)/include/generated ]; then \
- echo >&2 " $(srctree) is not clean, please run 'make ARCH=$(ARCH) mrproper'"; \
- echo >&2 " in the '$(srctree)' directory.";\
- /bin/false; \
- fi;
-endif
-
-archprepare: archheaders archscripts scripts prepare3 outputmakefile \
+archprepare: outputmakefile archheaders archscripts scripts include/config/kernel.release \
asm-generic $(version_h) $(autoksyms_h) include/generated/utsrelease.h
prepare0: archprepare
@@ -1244,7 +1246,7 @@
$(if $(wildcard $(objtree)/.config),, $(error No .config exists, config your kernel first!))
$(Q)find $(srctree)/tools/testing/selftests -name config | \
xargs $(srctree)/scripts/kconfig/merge_config.sh -m $(objtree)/.config
- +$(Q)$(MAKE) -f $(srctree)/Makefile olddefconfig
+ $(Q)$(MAKE) -f $(srctree)/Makefile olddefconfig
# ---------------------------------------------------------------------------
# Devicetree files
@@ -1255,11 +1257,11 @@
ifneq ($(dtstree),)
-%.dtb: prepare3 scripts_dtc
+%.dtb: include/config/kernel.release scripts_dtc
$(Q)$(MAKE) $(build)=$(dtstree) $(dtstree)/$@
PHONY += dtbs dtbs_install dt_binding_check
-dtbs dtbs_check: prepare3 scripts_dtc
+dtbs dtbs_check: include/config/kernel.release scripts_dtc
$(Q)$(MAKE) $(build)=$(dtstree)
dtbs_check: export CHECK_DTBS=1
@@ -1298,17 +1300,16 @@
PHONY += modules
modules: $(if $(KBUILD_BUILTIN),vmlinux) modules.order modules.builtin
- @$(kecho) ' Building modules, stage 2.';
$(Q)$(MAKE) -f $(srctree)/scripts/Makefile.modpost
$(Q)$(CONFIG_SHELL) $(srctree)/scripts/modules-check.sh
-modules.order: $(vmlinux-dirs)
- $(Q)$(AWK) '!x[$$0]++' $(addsuffix /$@, $(vmlinux-dirs)) > $@
+modules.order: descend
+ $(Q)$(AWK) '!x[$$0]++' $(addsuffix /$@, $(build-dirs)) > $@
-modbuiltin-dirs := $(addprefix _modbuiltin_, $(vmlinux-dirs))
+modbuiltin-dirs := $(addprefix _modbuiltin_, $(build-dirs))
modules.builtin: $(modbuiltin-dirs)
- $(Q)$(AWK) '!x[$$0]++' $(addsuffix /$@, $(vmlinux-dirs)) > $@
+ $(Q)$(AWK) '!x[$$0]++' $(addsuffix /$@, $(build-dirs)) > $@
PHONY += $(modbuiltin-dirs)
# tristate.conf is not included from this Makefile. Add it as a prerequisite
@@ -1381,12 +1382,14 @@
# Directories & files removed with 'make mrproper'
MRPROPER_DIRS += include/config include/generated \
- arch/$(SRCARCH)/include/generated .tmp_objdiff
+ arch/$(SRCARCH)/include/generated .tmp_objdiff \
+ debian/ snap/ tar-install/
MRPROPER_FILES += .config .config.old .version \
Module.symvers \
signing_key.pem signing_key.priv signing_key.x509 \
x509.genkey extra_certificates signing_key.x509.keyid \
- signing_key.x509.signer vmlinux-gdb.py
+ signing_key.x509.signer vmlinux-gdb.py \
+ *.spec
# Directories & files removed with 'make distclean'
DISTCLEAN_DIRS +=
@@ -1396,11 +1399,8 @@
#
clean: rm-dirs := $(CLEAN_DIRS)
clean: rm-files := $(CLEAN_FILES)
-clean-dirs := $(addprefix _clean_, . $(vmlinux-alldirs))
-PHONY += $(clean-dirs) clean archclean vmlinuxclean
-$(clean-dirs):
- $(Q)$(MAKE) $(clean)=$(patsubst _clean_%,%,$@)
+PHONY += archclean vmlinuxclean
vmlinuxclean:
$(Q)$(CONFIG_SHELL) $(srctree)/scripts/link-vmlinux.sh clean
@@ -1441,13 +1441,11 @@
# Packaging of the kernel to various formats
# ---------------------------------------------------------------------------
-package-dir := scripts/package
%src-pkg: FORCE
- $(Q)$(MAKE) $(build)=$(package-dir) $@
+ $(Q)$(MAKE) -f $(srctree)/scripts/Makefile.package $@
%pkg: include/config/kernel.release FORCE
- $(Q)$(MAKE) $(build)=$(package-dir) $@
-
+ $(Q)$(MAKE) -f $(srctree)/scripts/Makefile.package $@
# Brief documentation of the typical targets used
# ---------------------------------------------------------------------------
@@ -1500,6 +1498,9 @@
@echo ' headerdep - Detect inclusion cycles in headers'
@echo ' coccicheck - Check with Coccinelle'
@echo ''
+ @echo 'Tools:'
+ @echo ' nsdeps - Generate missing symbol namespace dependencies'
+ @echo ''
@echo 'Kernel selftest:'
@echo ' kselftest - Build and run kernel selftest (run as root)'
@echo ' Build, install, and boot kernel before'
@@ -1510,8 +1511,10 @@
@echo ''
@$(if $(dtstree), \
echo 'Devicetree:'; \
- echo '* dtbs - Build device tree blobs for enabled boards'; \
- echo ' dtbs_install - Install dtbs to $(INSTALL_DTBS_PATH)'; \
+ echo '* dtbs - Build device tree blobs for enabled boards'; \
+ echo ' dtbs_install - Install dtbs to $(INSTALL_DTBS_PATH)'; \
+ echo ' dt_binding_check - Validate device tree binding documents'; \
+ echo ' dtbs_check - Validate device tree source files';\
echo '')
@echo 'Userspace tools targets:'
@@ -1519,7 +1522,7 @@
@echo ' or "cd tools; make help"'
@echo ''
@echo 'Kernel packaging:'
- @$(MAKE) $(build)=$(package-dir) help
+ @$(MAKE) -f $(srctree)/scripts/Makefile.package help
@echo ''
@echo 'Documentation targets:'
@$(MAKE) -f $(srctree)/Documentation/Makefile dochelp
@@ -1544,7 +1547,7 @@
@echo ' make C=1 [targets] Check re-compiled c source with $$CHECK (sparse by default)'
@echo ' make C=2 [targets] Force check of all c source with $$CHECK'
@echo ' make RECORDMCOUNT_WARN=1 [targets] Warn about ignored mcount sections'
- @echo ' make W=n [targets] Enable extra gcc checks, n=1,2,3 where'
+ @echo ' make W=n [targets] Enable extra build checks, n=1,2,3 where'
@echo ' 1: warnings which may be relevant and do not occur too often'
@echo ' 2: warnings which occur quite often but may still be relevant'
@echo ' 3: more obscure warnings, can most likely be ignored'
@@ -1573,7 +1576,7 @@
DOC_TARGETS := xmldocs latexdocs pdfdocs htmldocs epubdocs cleandocs \
linkcheckdocs dochelp refcheckdocs
PHONY += $(DOC_TARGETS)
-$(DOC_TARGETS): scripts_basic FORCE
+$(DOC_TARGETS):
$(Q)$(MAKE) $(build)=Documentation $@
# Misc
@@ -1618,13 +1621,9 @@
echo " is missing; modules will have no dependencies and modversions."; \
echo )
-module-dirs := $(addprefix _module_,$(KBUILD_EXTMOD))
-PHONY += $(module-dirs) modules
-$(module-dirs): prepare $(objtree)/Module.symvers
- $(Q)$(MAKE) $(build)=$(patsubst _module_%,%,$@) need-modorder=1
-
-modules: $(module-dirs)
- @$(kecho) ' Building modules, stage 2.';
+build-dirs := $(KBUILD_EXTMOD)
+PHONY += modules
+modules: descend $(objtree)/Module.symvers
$(Q)$(MAKE) -f $(srctree)/scripts/Makefile.modpost
PHONY += modules_install
@@ -1640,14 +1639,13 @@
_emodinst_post: _emodinst_
$(call cmd,depmod)
-clean-dirs := $(addprefix _clean_,$(KBUILD_EXTMOD))
-
-PHONY += $(clean-dirs) clean
-$(clean-dirs):
- $(Q)$(MAKE) $(clean)=$(patsubst _clean_%,%,$@)
-
+clean-dirs := $(KBUILD_EXTMOD)
clean: rm-files := $(KBUILD_EXTMOD)/Module.symvers
+PHONY += /
+/:
+ @echo >&2 '"$(MAKE) /" is no longer supported. Please use "$(MAKE) ./" instead.'
+
PHONY += help
help:
@echo ' Building external modules.'
@@ -1661,6 +1659,21 @@
PHONY += prepare
endif # KBUILD_EXTMOD
+# Handle descending into subdirectories listed in $(build-dirs)
+# Preset locale variables to speed up the build process. Limit locale
+# tweaks to this spot to avoid wrong language settings when running
+# make menuconfig etc.
+# Error messages still appears in the original language
+PHONY += descend $(build-dirs)
+descend: $(build-dirs)
+$(build-dirs): prepare
+ $(Q)$(MAKE) $(build)=$@ single-build=$(single-build) need-builtin=1 need-modorder=1
+
+clean-dirs := $(addprefix _clean_, $(clean-dirs))
+PHONY += $(clean-dirs) clean
+$(clean-dirs):
+ $(Q)$(MAKE) $(clean)=$(patsubst _clean_%,%,$@)
+
clean: $(clean-dirs)
$(call cmd,rmdirs)
$(call cmd,rmfiles)
@@ -1669,7 +1682,7 @@
-o -name '*.ko.*' \
-o -name '*.dtb' -o -name '*.dtb.S' -o -name '*.dt.yaml' \
-o -name '*.dwo' -o -name '*.lst' \
- -o -name '*.su' -o -name '*.mod' \
+ -o -name '*.su' -o -name '*.mod' -o -name '*.ns_deps' \
-o -name '.*.d' -o -name '.*.tmp' -o -name '*.mod.c' \
-o -name '*.lex.c' -o -name '*.tab.[ch]' \
-o -name '*.asn1.[ch]' \
@@ -1682,11 +1695,20 @@
# Generate tags for editors
# ---------------------------------------------------------------------------
quiet_cmd_tags = GEN $@
- cmd_tags = $(CONFIG_SHELL) $(srctree)/scripts/tags.sh $@
+ cmd_tags = $(BASH) $(srctree)/scripts/tags.sh $@
tags TAGS cscope gtags: FORCE
$(call cmd,tags)
+# Script to generate missing namespace dependencies
+# ---------------------------------------------------------------------------
+
+PHONY += nsdeps
+
+nsdeps: modules
+ $(Q)$(MAKE) -f $(srctree)/scripts/Makefile.modpost nsdeps
+ $(Q)$(CONFIG_SHELL) $(srctree)/scripts/$@
+
# Scripts to check various things for consistency
# ---------------------------------------------------------------------------
@@ -1703,7 +1725,7 @@
| xargs $(PERL) -w $(srctree)/scripts/checkversion.pl
coccicheck:
- $(Q)$(CONFIG_SHELL) $(srctree)/scripts/$@
+ $(Q)$(BASH) $(srctree)/scripts/$@
namespacecheck:
$(PERL) $(srctree)/scripts/namespace.pl
@@ -1751,45 +1773,47 @@
# Single targets
# ---------------------------------------------------------------------------
-# Single targets are compatible with:
-# - build with mixed source and output
-# - build with separate output dir 'make O=...'
-# - external modules
+# To build individual files in subdirectories, you can do like this:
#
-# target-dir => where to store outputfile
-# build-dir => directory in kernel source tree to use
+# make foo/bar/baz.s
+#
+# The supported suffixes for single-target are listed in 'single-targets'
+#
+# To build only under specific subdirectories, you can do like this:
+#
+# make foo/bar/baz/
-build-target = $(if $(KBUILD_EXTMOD), $(KBUILD_EXTMOD)/)$@
-build-dir = $(patsubst %/,%,$(dir $(build-target)))
+ifdef single-build
-%.i: prepare FORCE
- $(Q)$(MAKE) $(build)=$(build-dir) $(build-target)
-%.ll: prepare FORCE
- $(Q)$(MAKE) $(build)=$(build-dir) $(build-target)
-%.lst: prepare FORCE
- $(Q)$(MAKE) $(build)=$(build-dir) $(build-target)
-%.o: prepare FORCE
- $(Q)$(MAKE) $(build)=$(build-dir) $(build-target)
-%.s: prepare FORCE
- $(Q)$(MAKE) $(build)=$(build-dir) $(build-target)
-%.symtypes: prepare FORCE
- $(Q)$(MAKE) $(build)=$(build-dir) $(build-target)
+single-all := $(filter $(single-targets), $(MAKECMDGOALS))
+
+# .ko is special because modpost is needed
+single-ko := $(sort $(filter %.ko, $(single-all)))
+single-no-ko := $(sort $(patsubst %.ko,%.mod, $(single-all)))
+
+$(single-ko): single_modpost
+ @:
+$(single-no-ko): descend
+ @:
+
ifeq ($(KBUILD_EXTMOD),)
-# For the single build of an in-tree module, use a temporary file to avoid
+# For the single build of in-tree modules, use a temporary file to avoid
# the situation of modules_install installing an invalid modules.order.
-%.ko: MODORDER := .modules.tmp
+MODORDER := .modules.tmp
endif
-%.ko: prepare FORCE
- $(Q)$(MAKE) $(build)=$(build-dir) $(build-target:.ko=.mod)
- $(Q)echo $(build-target) > $(MODORDER)
+
+PHONY += single_modpost
+single_modpost: $(single-no-ko)
+ $(Q){ $(foreach m, $(single-ko), echo $(extmod-prefix)$m;) } > $(MODORDER)
$(Q)$(MAKE) -f $(srctree)/scripts/Makefile.modpost
-# Modules
-PHONY += /
-/: ./
+KBUILD_MODULES := 1
-%/: prepare FORCE
- $(Q)$(MAKE) KBUILD_MODULES=1 $(build)=$(bu