Merge tag 'modules-for-v5.9' of git://git.kernel.org/pub/scm/linux/kernel/git/jeyu/linux
Pull module updates from Jessica Yu:
"The most important change would be Christoph Hellwig's patch
implementing proprietary taint inheritance, in an effort to discourage
the creation of GPL "shim" modules that interface between GPL symbols
and proprietary symbols.
Summary:
- Have modules that use symbols from proprietary modules inherit the
TAINT_PROPRIETARY_MODULE taint, in an effort to prevent GPL shim
modules that are used to circumvent _GPL exports. These are modules
that claim to be GPL licensed while also using symbols from
proprietary modules. Such modules will be rejected while non-GPL
modules will inherit the proprietary taint.
- Module export space cleanup. Unexport symbols that are unused
outside of module.c or otherwise used in only built-in code"
* tag 'modules-for-v5.9' of git://git.kernel.org/pub/scm/linux/kernel/git/jeyu/linux:
modules: inherit TAINT_PROPRIETARY_MODULE
modules: return licensing information from find_symbol
modules: rename the licence field in struct symsearch to license
modules: unexport __module_address
modules: unexport __module_text_address
modules: mark each_symbol_section static
modules: mark find_symbol static
modules: mark ref_module static
modules: linux/moduleparam.h: drop duplicated word in a comment
diff --git a/.gitignore b/.gitignore
index 87b9dd8..162bd2b 100644
--- a/.gitignore
+++ b/.gitignore
@@ -44,6 +44,7 @@
*.tab.[ch]
*.tar
*.xz
+*.zst
Module.symvers
modules.builtin
modules.order
@@ -143,6 +144,9 @@
/allrandom.config
/allyes.config
+# Kconfig savedefconfig output
+/defconfig
+
# Kdevelop4
*.kdev4
diff --git a/.mailmap b/.mailmap
index c69d9c7..83d8d01 100644
--- a/.mailmap
+++ b/.mailmap
@@ -2,11 +2,16 @@
# This list is used by git-shortlog to fix a few botched name translations
# in the git archive, either because the author's full name was messed up
# and/or not always written the same way, making contributions from the
-# same person appearing not to be so or badly displayed.
+# same person appearing not to be so or badly displayed. Also allows for
+# old email addresses to map to new email addresses.
#
+# For format details, see "MAPPING AUTHORS" in "man git-shortlog".
+#
+# Please keep this list dictionary sorted.
+#
+# This comment is parsed by git-shortlog:
# repo-abbrev: /pub/scm/linux/kernel/git/
#
-
Aaron Durbin <adurbin@google.com>
Adam Oldham <oldhamca@gmail.com>
Adam Radford <aradford@gmail.com>
@@ -18,6 +23,9 @@
Aleksandar Markovic <aleksandar.markovic@mips.com> <aleksandar.markovic@imgtec.com>
Alex Shi <alex.shi@linux.alibaba.com> <alex.shi@intel.com>
Alex Shi <alex.shi@linux.alibaba.com> <alex.shi@linaro.org>
+Alexander Lobakin <alobakin@pm.me> <alobakin@dlink.ru>
+Alexander Lobakin <alobakin@pm.me> <alobakin@marvell.com>
+Alexander Lobakin <alobakin@pm.me> <bloodyreaper@yandex.ru>
Alexandre Belloni <alexandre.belloni@bootlin.com> <alexandre.belloni@free-electrons.com>
Alexei Starovoitov <ast@kernel.org> <ast@plumgrid.com>
Alexei Starovoitov <ast@kernel.org> <alexei.starovoitov@gmail.com>
@@ -90,11 +98,16 @@
Frank Zago <fzago@systemfabricworks.com>
Gao Xiang <xiang@kernel.org> <gaoxiang25@huawei.com>
Gao Xiang <xiang@kernel.org> <hsiangkao@aol.com>
+Gerald Schaefer <gerald.schaefer@linux.ibm.com> <gerald.schaefer@de.ibm.com>
+Gerald Schaefer <gerald.schaefer@linux.ibm.com> <geraldsc@de.ibm.com>
+Gerald Schaefer <gerald.schaefer@linux.ibm.com> <geraldsc@linux.vnet.ibm.com>
Greg Kroah-Hartman <greg@echidna.(none)>
Greg Kroah-Hartman <gregkh@suse.de>
Greg Kroah-Hartman <greg@kroah.com>
Gregory CLEMENT <gregory.clement@bootlin.com> <gregory.clement@free-electrons.com>
Hanjun Guo <guohanjun@huawei.com> <hanjun.guo@linaro.org>
+Heiko Carstens <hca@linux.ibm.com> <h.carstens@de.ibm.com>
+Heiko Carstens <hca@linux.ibm.com> <heiko.carstens@de.ibm.com>
Henk Vergonet <Henk.Vergonet@gmail.com>
Henrik Kretzschmar <henne@nachtwindheim.de>
Henrik Rydberg <rydberg@bitmath.org>
@@ -129,6 +142,11 @@
Jeff Layton <jlayton@kernel.org> <jlayton@primarydata.com>
Jens Axboe <axboe@suse.de>
Jens Osterkamp <Jens.Osterkamp@de.ibm.com>
+Jiri Slaby <jirislaby@kernel.org> <jirislaby@gmail.com>
+Jiri Slaby <jirislaby@kernel.org> <jslaby@novell.com>
+Jiri Slaby <jirislaby@kernel.org> <jslaby@suse.com>
+Jiri Slaby <jirislaby@kernel.org> <jslaby@suse.cz>
+Jiri Slaby <jirislaby@kernel.org> <xslaby@fi.muni.cz>
Johan Hovold <johan@kernel.org> <jhovold@gmail.com>
Johan Hovold <johan@kernel.org> <johan@hovoldconsulting.com>
John Paul Adrian Glaubitz <glaubitz@physik.fu-berlin.de>
@@ -146,6 +164,7 @@
Kay Sievers <kay.sievers@vrfy.org>
Kenneth W Chen <kenneth.w.chen@intel.com>
Konstantin Khlebnikov <koct9i@gmail.com> <k.khlebnikov@samsung.com>
+Konstantin Khlebnikov <koct9i@gmail.com> <khlebnikov@yandex-team.ru>
Koushik <raghavendra.koushik@neterion.com>
Krzysztof Kozlowski <krzk@kernel.org> <k.kozlowski@samsung.com>
Krzysztof Kozlowski <krzk@kernel.org> <k.kozlowski.k@gmail.com>
@@ -193,6 +212,9 @@
Mayuresh Janorkar <mayur@ti.com>
Michael Buesch <m@bues.ch>
Michel Dänzer <michel@tungstengraphics.com>
+Mike Rapoport <rppt@kernel.org> <mike@compulab.co.il>
+Mike Rapoport <rppt@kernel.org> <mike.rapoport@gmail.com>
+Mike Rapoport <rppt@kernel.org> <rppt@linux.ibm.com>
Miodrag Dinic <miodrag.dinic@mips.com> <miodrag.dinic@imgtec.com>
Miquel Raynal <miquel.raynal@bootlin.com> <miquel.raynal@free-electrons.com>
Mitesh shah <mshah@teja.com>
diff --git a/CREDITS b/CREDITS
index 0787b5872..32ee70a 100644
--- a/CREDITS
+++ b/CREDITS
@@ -34,7 +34,7 @@
N: Mark Adler
E: madler@alumni.caltech.edu
-W: http://alumnus.caltech.edu/~madler/
+W: https://alumnus.caltech.edu/~madler/
D: zlib decompression
N: Monalisa Agrawal
@@ -62,7 +62,7 @@
N: Werner Almesberger
E: werner@almesberger.net
-W: http://www.almesberger.net/
+W: https://www.almesberger.net/
D: dosfs, LILO, some fd features, ATM, various other hacks here and there
S: Buenos Aires
S: Argentina
@@ -96,7 +96,7 @@
N: Erik Andersen
E: andersen@codepoet.org
-W: http://www.codepoet.org/
+W: https://www.codepoet.org/
P: 1024D/30D39057 1BC4 2742 E885 E4DE 9301 0C82 5F9B 643E 30D3 9057
D: Maintainer of ide-cd and Uniform CD-ROM driver,
D: ATAPI CD-Changer support, Major 2.1.x CD-ROM update.
@@ -114,7 +114,7 @@
N: H. Peter Anvin
E: hpa@zytor.com
-W: http://www.zytor.com/~hpa/
+W: https://www.zytor.com/~hpa/
P: 2047/2A960705 BA 03 D3 2C 14 A8 A8 BD 1E DF FE 69 EE 35 BD 74
D: Author of the SYSLINUX boot loader, maintainer of the linux.* news
D: hierarchy and the Linux Device List; various kernel hacks
@@ -124,7 +124,7 @@
N: Andrea Arcangeli
E: andrea@suse.de
-W: http://www.kernel.org/pub/linux/kernel/people/andrea/
+W: https://www.kernel.org/pub/linux/kernel/people/andrea/
P: 1024D/68B9CB43 13D9 8355 295F 4823 7C49 C012 DFA1 686E 68B9 CB43
P: 1024R/CB4660B9 CC A0 71 81 F4 A0 63 AC C0 4B 81 1D 8C 15 C8 E5
D: Parport hacker
@@ -339,7 +339,7 @@
N: Johannes Berg
E: johannes@sipsolutions.net
-W: http://johannes.sipsolutions.net/
+W: https://johannes.sipsolutions.net/
P: 4096R/7BF9099A C0EB C440 F6DA 091C 884D 8532 E0F3 73F3 7BF9 099A
D: powerpc & 802.11 hacker
@@ -376,7 +376,7 @@
N: Anton Blanchard
E: anton@samba.org
-W: http://samba.org/~anton/
+W: https://samba.org/~anton/
P: 1024/8462A731 4C 55 86 34 44 59 A7 99 2B 97 88 4A 88 9A 0D 97
D: sun4 port, Sparc hacker
@@ -509,7 +509,7 @@
N: Paul Bristow
E: paul@paulbristow.net
-W: http://paulbristow.net/linux/idefloppy.html
+W: https://paulbristow.net/linux/idefloppy.html
D: Maintainer of IDE/ATAPI floppy driver
N: Stefano Brivio
@@ -518,7 +518,7 @@
N: Dominik Brodowski
E: linux@brodo.de
-W: http://www.brodo.de/
+W: https://www.brodo.de/
P: 1024D/725B37C6 190F 3E77 9C89 3B6D BECD 46EE 67C3 0308 725B 37C6
D: parts of CPUFreq code, ACPI bugfixes, PCMCIA rewrite, cpufrequtils
S: Tuebingen, Germany
@@ -865,7 +865,7 @@
N: Todd J. Derr
E: tjd@fore.com
-W: http://www.wordsmith.org/~tjd
+W: https://www.wordsmith.org/~tjd
D: Random console hacks and other miscellaneous stuff
S: 3000 FORE Drive
S: Warrendale, Pennsylvania 15086
@@ -894,8 +894,8 @@
N: Matt Domsch
E: Matt_Domsch@dell.com
-W: http://www.dell.com/linux
-W: http://domsch.com/linux
+W: https://www.dell.com/linux
+W: https://domsch.com/linux
D: Linux/IA-64
D: Dell PowerEdge server, SCSI layer, misc drivers, and other patches
S: Dell Inc.
@@ -992,7 +992,7 @@
N: Randy Dunlap
E: rdunlap@infradead.org
-W: http://www.infradead.org/~rdunlap/
+W: https://www.infradead.org/~rdunlap/
D: Linux-USB subsystem, USB core/UHCI/printer/storage drivers
D: x86 SMP, ACPI, bootflag hacking
D: documentation, builds
@@ -1157,7 +1157,7 @@
N: Jeremy Fitzhardinge
E: jeremy@goop.org
-W: http://www.goop.org/~jeremy
+W: https://www.goop.org/~jeremy
D: author of userfs filesystem
D: Improved mmap and munmap handling
D: General mm minor tidyups
@@ -1460,7 +1460,7 @@
N: Oliver Hartkopp
E: oliver.hartkopp@volkswagen.de
-W: http://www.volkswagen.de
+W: https://www.volkswagen.de
D: Controller Area Network (network layer core)
S: Brieffach 1776
S: 38436 Wolfsburg
@@ -1599,13 +1599,13 @@
N: Kenji Hollis
E: kenji@bitgate.com
-W: http://www.bitgate.com/
+W: https://www.bitgate.com/
D: Berkshire PC Watchdog Driver
D: Small/Industrial Driver Project
N: Nick Holloway
E: Nick.Holloway@pyrites.org.uk
-W: http://www.pyrites.org.uk/
+W: https://www.pyrites.org.uk/
P: 1024/36115A04 F4E1 3384 FCFD C055 15D6 BA4C AB03 FBF8 3611 5A04
D: Occasional Linux hacker...
S: (ask for current address)
@@ -1655,7 +1655,7 @@
N: Harald Hoyer
E: harald@redhat.com
-W: http://www.harald-hoyer.de
+W: https://www.harald-hoyer.de
D: ip_masq_quake
D: md boot support
S: Am Strand 5
@@ -1856,7 +1856,7 @@
D: Author of the COSA/SRP sync serial board driver.
D: Port of the syncppp.c from the 2.0 to the 2.1 kernel.
P: 1024/D3498839 0D 99 A7 FB 20 66 05 D7 8B 35 FC DE 05 B1 8A 5E
-W: http://www.fi.muni.cz/~kas/
+W: https://www.fi.muni.cz/~kas/
S: c/o Faculty of Informatics, Masaryk University
S: Botanicka' 68a
S: 602 00 Brno
@@ -2017,7 +2017,7 @@
N: Gene Kozin
E: 74604.152@compuserve.com
-W: http://www.sangoma.com
+W: https://www.sangoma.com
D: WAN Router & Sangoma WAN drivers
S: Sangoma Technologies Inc.
S: 7170 Warden Avenue, Unit 2
@@ -2112,7 +2112,7 @@
N: Jaroslav Kysela
E: perex@perex.cz
-W: http://www.perex.cz
+W: https://www.perex.cz
D: Original Author and Maintainer for HP 10/100 Mbit Network Adapters
D: ISA PnP
S: Sindlovy Dvory 117
@@ -2316,7 +2316,7 @@
N: Daniel J. Maas
E: dmaas@dcine.com
-W: http://www.maasdigital.com
+W: https://www.maasdigital.com
D: dv1394
N: Hamish Macdonald
@@ -2647,7 +2647,7 @@
N: Paul Moore
E: paul@paul-moore.com
-W: http://www.paul-moore.com
+W: https://www.paul-moore.com
D: NetLabel, SELinux, audit
N: James Morris
@@ -2786,7 +2786,7 @@
E: niemi@tux.org
W: http://www.tux.org/~niemi/
D: Assistant maintainer of Mtools, fdutils, and floppy driver
-D: Administrator of Tux.Org Linux Server, http://www.tux.org
+D: Administrator of Tux.Org Linux Server, https://www.tux.org
S: 2364 Old Trail Drive
S: Reston, Virginia 20191
S: USA
@@ -2850,7 +2850,7 @@
N: Mikulas Patocka
E: mikulas@artax.karlin.mff.cuni.cz
-W: http://artax.karlin.mff.cuni.cz/~mikulas/
+W: https://artax.karlin.mff.cuni.cz/~mikulas/
P: 1024/BB11D2D5 A0 F1 28 4A C4 14 1E CF 92 58 7A 8F 69 BC A4 D3
D: Read/write HPFS filesystem
S: Weissova 8
@@ -2872,7 +2872,7 @@
N: Barak A. Pearlmutter
E: bap@cs.unm.edu
-W: http://www.cs.unm.edu/~bap/
+W: https://www.cs.unm.edu/~bap/
P: 512/602D785D 9B A1 83 CD EE CB AD 93 20 C6 4C B7 F5 E9 60 D4
D: Author of mark-and-sweep GC integrated by Alan Cox
S: Computer Science Department
@@ -3035,7 +3035,7 @@
N: Daniel Quinlan
E: quinlan@pathname.com
-W: http://www.pathname.com/~quinlan/
+W: https://www.pathname.com/~quinlan/
D: FSSTND coordinator; FHS editor
D: random Linux documentation, patches, and hacks
S: 4390 Albany Drive #41A
@@ -3130,7 +3130,7 @@
N: Rik van Riel
E: riel@redhat.com
-W: http://www.surriel.com/
+W: https://www.surriel.com/
D: Linux-MM site, Documentation/admin-guide/sysctl/*, swap/mm readaround
D: kswapd fixes, random kernel hacker, rmap VM,
D: nl.linux.org administrator, minor scheduler additions
@@ -3246,7 +3246,7 @@
N: Paul `Rusty' Russell
E: rusty@rustcorp.com.au
-W: http://ozlabs.org/~rusty
+W: https://ozlabs.org/~rusty
D: Ruggedly handsome.
D: netfilter, ipchains with Michael Neuling.
S: 52 Moore St
@@ -3369,7 +3369,7 @@
N: Robert Schwebel
E: robert@schwebel.de
-W: http://www.schwebel.de
+W: https://www.schwebel.de
D: Embedded hacker and book author,
D: AMD Elan support for Linux
S: Pengutronix
@@ -3545,7 +3545,7 @@
N: Henrik Storner
E: storner@image.dk
W: http://www.image.dk/~storner/
-W: http://www.sslug.dk/
+W: https://www.sslug.dk/
D: Configure script: Invented tristate for module-configuration
D: vfat/msdos integration, kerneld docs, Linux promotion
D: Miscellaneous bug-fixes
@@ -3579,7 +3579,7 @@
N: Eugene Surovegin
E: ebs@ebshome.net
-W: http://kernel.ebshome.net/
+W: https://kernel.ebshome.net/
P: 1024D/AE5467F1 FF22 39F1 6728 89F6 6E6C 2365 7602 F33D AE54 67F1
D: Embedded PowerPC 4xx: EMAC, I2C, PIC and random hacks/fixes
S: Sunnyvale, California 94085
@@ -3609,7 +3609,7 @@
N: Urs Thuermann
E: urs.thuermann@volkswagen.de
-W: http://www.volkswagen.de
+W: https://www.volkswagen.de
D: Controller Area Network (network layer core)
S: Brieffach 1776
S: 38436 Wolfsburg
@@ -3656,7 +3656,7 @@
N: Andrew Tridgell
E: tridge@samba.org
-W: http://samba.org/tridge/
+W: https://samba.org/tridge/
D: dosemu, networking, samba
S: 3 Ballow Crescent
S: MacGregor A.C.T 2615
@@ -3894,7 +3894,7 @@
N: David Weinehall
E: tao@acc.umu.se
P: 1024D/DC47CA16 7ACE 0FB0 7A74 F994 9B36 E1D1 D14E 8526 DC47 CA16
-W: http://www.acc.umu.se/~tao/
+W: https://www.acc.umu.se/~tao/
D: v2.0 kernel maintainer
D: Fixes for the NE/2-driver
D: Miscellaneous MCA-support
@@ -3919,7 +3919,7 @@
N: Harald Welte
E: laforge@netfilter.org
P: 1024D/30F48BFF DBDE 6912 8831 9A53 879B 9190 5DA5 C655 30F4 8BFF
-W: http://gnumonks.org/users/laforge
+W: https://gnumonks.org/users/laforge
D: netfilter: new nat helper infrastructure
D: netfilter: ULOG, ECN, DSCP target
D: netfilter: TTL match
diff --git a/Documentation/ABI/stable/sysfs-driver-dma-idxd b/Documentation/ABI/stable/sysfs-driver-dma-idxd
index b5bebf6..1af9c41 100644
--- a/Documentation/ABI/stable/sysfs-driver-dma-idxd
+++ b/Documentation/ABI/stable/sysfs-driver-dma-idxd
@@ -1,47 +1,47 @@
-What: sys/bus/dsa/devices/dsa<m>/version
+What: /sys/bus/dsa/devices/dsa<m>/version
Date: Apr 15, 2020
KernelVersion: 5.8.0
Contact: dmaengine@vger.kernel.org
Description: The hardware version number.
-What: sys/bus/dsa/devices/dsa<m>/cdev_major
+What: /sys/bus/dsa/devices/dsa<m>/cdev_major
Date: Oct 25, 2019
-KernelVersion: 5.6.0
+KernelVersion: 5.6.0
Contact: dmaengine@vger.kernel.org
Description: The major number that the character device driver assigned to
this device.
-What: sys/bus/dsa/devices/dsa<m>/errors
+What: /sys/bus/dsa/devices/dsa<m>/errors
Date: Oct 25, 2019
KernelVersion: 5.6.0
Contact: dmaengine@vger.kernel.org
Description: The error information for this device.
-What: sys/bus/dsa/devices/dsa<m>/max_batch_size
+What: /sys/bus/dsa/devices/dsa<m>/max_batch_size
Date: Oct 25, 2019
KernelVersion: 5.6.0
Contact: dmaengine@vger.kernel.org
Description: The largest number of work descriptors in a batch.
-What: sys/bus/dsa/devices/dsa<m>/max_work_queues_size
+What: /sys/bus/dsa/devices/dsa<m>/max_work_queues_size
Date: Oct 25, 2019
KernelVersion: 5.6.0
Contact: dmaengine@vger.kernel.org
Description: The maximum work queue size supported by this device.
-What: sys/bus/dsa/devices/dsa<m>/max_engines
+What: /sys/bus/dsa/devices/dsa<m>/max_engines
Date: Oct 25, 2019
KernelVersion: 5.6.0
Contact: dmaengine@vger.kernel.org
Description: The maximum number of engines supported by this device.
-What: sys/bus/dsa/devices/dsa<m>/max_groups
+What: /sys/bus/dsa/devices/dsa<m>/max_groups
Date: Oct 25, 2019
KernelVersion: 5.6.0
Contact: dmaengine@vger.kernel.org
Description: The maximum number of groups can be created under this device.
-What: sys/bus/dsa/devices/dsa<m>/max_tokens
+What: /sys/bus/dsa/devices/dsa<m>/max_tokens
Date: Oct 25, 2019
KernelVersion: 5.6.0
Contact: dmaengine@vger.kernel.org
@@ -50,7 +50,7 @@
implementation, and these resources are allocated by engines to
support operations.
-What: sys/bus/dsa/devices/dsa<m>/max_transfer_size
+What: /sys/bus/dsa/devices/dsa<m>/max_transfer_size
Date: Oct 25, 2019
KernelVersion: 5.6.0
Contact: dmaengine@vger.kernel.org
@@ -58,57 +58,57 @@
perform the operation. The maximum transfer size is dependent on
the workqueue the descriptor was submitted to.
-What: sys/bus/dsa/devices/dsa<m>/max_work_queues
+What: /sys/bus/dsa/devices/dsa<m>/max_work_queues
Date: Oct 25, 2019
KernelVersion: 5.6.0
Contact: dmaengine@vger.kernel.org
Description: The maximum work queue number that this device supports.
-What: sys/bus/dsa/devices/dsa<m>/numa_node
+What: /sys/bus/dsa/devices/dsa<m>/numa_node
Date: Oct 25, 2019
KernelVersion: 5.6.0
Contact: dmaengine@vger.kernel.org
Description: The numa node number for this device.
-What: sys/bus/dsa/devices/dsa<m>/op_cap
+What: /sys/bus/dsa/devices/dsa<m>/op_cap
Date: Oct 25, 2019
KernelVersion: 5.6.0
Contact: dmaengine@vger.kernel.org
Description: The operation capability bit mask specify the operation types
supported by the this device.
-What: sys/bus/dsa/devices/dsa<m>/state
+What: /sys/bus/dsa/devices/dsa<m>/state
Date: Oct 25, 2019
KernelVersion: 5.6.0
Contact: dmaengine@vger.kernel.org
Description: The state information of this device. It can be either enabled
or disabled.
-What: sys/bus/dsa/devices/dsa<m>/group<m>.<n>
+What: /sys/bus/dsa/devices/dsa<m>/group<m>.<n>
Date: Oct 25, 2019
KernelVersion: 5.6.0
Contact: dmaengine@vger.kernel.org
Description: The assigned group under this device.
-What: sys/bus/dsa/devices/dsa<m>/engine<m>.<n>
+What: /sys/bus/dsa/devices/dsa<m>/engine<m>.<n>
Date: Oct 25, 2019
KernelVersion: 5.6.0
Contact: dmaengine@vger.kernel.org
Description: The assigned engine under this device.
-What: sys/bus/dsa/devices/dsa<m>/wq<m>.<n>
+What: /sys/bus/dsa/devices/dsa<m>/wq<m>.<n>
Date: Oct 25, 2019
KernelVersion: 5.6.0
Contact: dmaengine@vger.kernel.org
Description: The assigned work queue under this device.
-What: sys/bus/dsa/devices/dsa<m>/configurable
+What: /sys/bus/dsa/devices/dsa<m>/configurable
Date: Oct 25, 2019
KernelVersion: 5.6.0
Contact: dmaengine@vger.kernel.org
Description: To indicate if this device is configurable or not.
-What: sys/bus/dsa/devices/dsa<m>/token_limit
+What: /sys/bus/dsa/devices/dsa<m>/token_limit
Date: Oct 25, 2019
KernelVersion: 5.6.0
Contact: dmaengine@vger.kernel.org
@@ -116,19 +116,19 @@
one time by operations that access low bandwidth memory in the
device.
-What: sys/bus/dsa/devices/wq<m>.<n>/group_id
+What: /sys/bus/dsa/devices/wq<m>.<n>/group_id
Date: Oct 25, 2019
KernelVersion: 5.6.0
Contact: dmaengine@vger.kernel.org
Description: The group id that this work queue belongs to.
-What: sys/bus/dsa/devices/wq<m>.<n>/size
+What: /sys/bus/dsa/devices/wq<m>.<n>/size
Date: Oct 25, 2019
KernelVersion: 5.6.0
Contact: dmaengine@vger.kernel.org
Description: The work queue size for this work queue.
-What: sys/bus/dsa/devices/wq<m>.<n>/type
+What: /sys/bus/dsa/devices/wq<m>.<n>/type
Date: Oct 25, 2019
KernelVersion: 5.6.0
Contact: dmaengine@vger.kernel.org
@@ -136,20 +136,20 @@
queue usages in the kernel space or "user" type for work queue
usages by applications in user space.
-What: sys/bus/dsa/devices/wq<m>.<n>/cdev_minor
+What: /sys/bus/dsa/devices/wq<m>.<n>/cdev_minor
Date: Oct 25, 2019
KernelVersion: 5.6.0
Contact: dmaengine@vger.kernel.org
Description: The minor number assigned to this work queue by the character
device driver.
-What: sys/bus/dsa/devices/wq<m>.<n>/mode
+What: /sys/bus/dsa/devices/wq<m>.<n>/mode
Date: Oct 25, 2019
KernelVersion: 5.6.0
Contact: dmaengine@vger.kernel.org
Description: The work queue mode type for this work queue.
-What: sys/bus/dsa/devices/wq<m>.<n>/priority
+What: /sys/bus/dsa/devices/wq<m>.<n>/priority
Date: Oct 25, 2019
KernelVersion: 5.6.0
Contact: dmaengine@vger.kernel.org
@@ -157,20 +157,20 @@
other work queue in the same group to control quality of service
for dispatching work from multiple workqueues in the same group.
-What: sys/bus/dsa/devices/wq<m>.<n>/state
+What: /sys/bus/dsa/devices/wq<m>.<n>/state
Date: Oct 25, 2019
KernelVersion: 5.6.0
Contact: dmaengine@vger.kernel.org
Description: The current state of the work queue.
-What: sys/bus/dsa/devices/wq<m>.<n>/threshold
+What: /sys/bus/dsa/devices/wq<m>.<n>/threshold
Date: Oct 25, 2019
KernelVersion: 5.6.0
Contact: dmaengine@vger.kernel.org
Description: The number of entries in this work queue that may be filled
via a limited portal.
-What: sys/bus/dsa/devices/engine<m>.<n>/group_id
+What: /sys/bus/dsa/devices/engine<m>.<n>/group_id
Date: Oct 25, 2019
KernelVersion: 5.6.0
Contact: dmaengine@vger.kernel.org
diff --git a/Documentation/ABI/stable/sysfs-driver-mlxreg-io b/Documentation/ABI/stable/sysfs-driver-mlxreg-io
index b0d90cc..fd9a804 100644
--- a/Documentation/ABI/stable/sysfs-driver-mlxreg-io
+++ b/Documentation/ABI/stable/sysfs-driver-mlxreg-io
@@ -206,3 +206,20 @@
regulator devices.
The file is read only.
+
+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/cpld1_pn
+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/cpld2_pn
+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/cpld3_pn
+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/cpld4_pn
+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/cpld1_version_min
+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/cpld2_version_min
+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/cpld3_version_min
+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/cpld4_version_min
+Date: July 2020
+KernelVersion: 5.9
+Contact: Vadim Pasternak <vadimpmellanox.com>
+Description: These files show with which CPLD part numbers and minor
+ versions have been burned CPLD devices equipped on a
+ system.
+
+ The files are read only.
diff --git a/drivers/staging/speakup/sysfs-driver-speakup b/Documentation/ABI/stable/sysfs-driver-speakup
similarity index 100%
rename from drivers/staging/speakup/sysfs-driver-speakup
rename to Documentation/ABI/stable/sysfs-driver-speakup
diff --git a/Documentation/ABI/testing/debugfs-driver-habanalabs b/Documentation/ABI/testing/debugfs-driver-habanalabs
index f6d9c2a..2e9ae31 100644
--- a/Documentation/ABI/testing/debugfs-driver-habanalabs
+++ b/Documentation/ABI/testing/debugfs-driver-habanalabs
@@ -16,7 +16,16 @@
gating mechanism in Gaudi. Due to how Gaudi is built, the
clock gating needs to be disabled in order to access the
registers of the TPC and MME engines. This is sometimes needed
- during debug by the user and hence the user needs this option
+ during debug by the user and hence the user needs this option.
+ The user can supply a bitmask value, each bit represents
+ a different engine to disable/enable its clock gating feature.
+ The bitmask is composed of 20 bits:
+ 0 - 7 : DMA channels
+ 8 - 11 : MME engines
+ 12 - 19 : TPC engines
+ The bit's location of a specific engine can be determined
+ using (1 << GAUDI_ENGINE_ID_*). GAUDI_ENGINE_ID_* values
+ are defined in uapi habanalabs.h file in enum gaudi_engine_id
What: /sys/kernel/debug/habanalabs/hl<n>/command_buffers
Date: Jan 2019
diff --git a/Documentation/ABI/testing/debugfs-turris-mox-rwtm b/Documentation/ABI/testing/debugfs-turris-mox-rwtm
new file mode 100644
index 0000000..2b3255e
--- /dev/null
+++ b/Documentation/ABI/testing/debugfs-turris-mox-rwtm
@@ -0,0 +1,9 @@
+What: /sys/kernel/debug/turris-mox-rwtm/do_sign
+Date: Jun 2020
+KernelVersion: 5.8
+Contact: Marek Behún <marek.behun@nic.cz>
+Description: (W) Message to sign with the ECDSA private key stored in
+ device's OTP. The message must be exactly 64 bytes (since
+ this is intended for SHA-512 hashes).
+ (R) The resulting signature, 136 bytes. This contains the R and
+ S values of the ECDSA signature, both in big-endian format.
diff --git a/Documentation/ABI/testing/dev-kmsg b/Documentation/ABI/testing/dev-kmsg
index 1e6c28b..3c0bb76 100644
--- a/Documentation/ABI/testing/dev-kmsg
+++ b/Documentation/ABI/testing/dev-kmsg
@@ -56,10 +56,16 @@
seek after the last record available at the time
the last SYSLOG_ACTION_CLEAR was issued.
- Due to the record nature of this interface with a "read all"
- behavior and the specific positions each seek operation sets,
- SEEK_CUR is not supported, returning -ESPIPE (invalid seek) to
- errno whenever requested.
+ Other seek operations or offsets are not supported because of
+ the special behavior this device has. The device allows to read
+ or write only whole variable length messages (records) that are
+ stored in a ring buffer.
+
+ Because of the non-standard behavior also the error values are
+ non-standard. -ESPIPE is returned for non-zero offset. -EINVAL
+ is returned for other operations, e.g. SEEK_CUR. This behavior
+ and values are historical and could not be modified without the
+ risk of breaking userspace.
The output format consists of a prefix carrying the syslog
prefix including priority and facility, the 64 bit message
diff --git a/Documentation/ABI/testing/sysfs-block b/Documentation/ABI/testing/sysfs-block
index ed8c14f..2322eb7 100644
--- a/Documentation/ABI/testing/sysfs-block
+++ b/Documentation/ABI/testing/sysfs-block
@@ -273,6 +273,24 @@
device ("host-aware" or "host-managed" zone model). For regular
block devices, the value is always 0.
+What: /sys/block/<disk>/queue/max_active_zones
+Date: July 2020
+Contact: Niklas Cassel <niklas.cassel@wdc.com>
+Description:
+ For zoned block devices (zoned attribute indicating
+ "host-managed" or "host-aware"), the sum of zones belonging to
+ any of the zone states: EXPLICIT OPEN, IMPLICIT OPEN or CLOSED,
+ is limited by this value. If this value is 0, there is no limit.
+
+What: /sys/block/<disk>/queue/max_open_zones
+Date: July 2020
+Contact: Niklas Cassel <niklas.cassel@wdc.com>
+Description:
+ For zoned block devices (zoned attribute indicating
+ "host-managed" or "host-aware"), the sum of zones belonging to
+ any of the zone states: EXPLICIT OPEN or IMPLICIT OPEN,
+ is limited by this value. If this value is 0, there is no limit.
+
What: /sys/block/<disk>/queue/chunk_sectors
Date: September 2016
Contact: Hannes Reinecke <hare@suse.com>
diff --git a/Documentation/ABI/testing/sysfs-bus-event_source-devices-hv_24x7 b/Documentation/ABI/testing/sysfs-bus-event_source-devices-hv_24x7
index e8698af..f7e32f2 100644
--- a/Documentation/ABI/testing/sysfs-bus-event_source-devices-hv_24x7
+++ b/Documentation/ABI/testing/sysfs-bus-event_source-devices-hv_24x7
@@ -43,6 +43,13 @@
This sysfs interface exposes the number of cores per chip
present in the system.
+What: /sys/devices/hv_24x7/interface/cpumask
+Date: July 2020
+Contact: Linux on PowerPC Developer List <linuxppc-dev@lists.ozlabs.org>
+Description: read only
+ This sysfs file exposes the cpumask which is designated to make
+ HCALLs to retrieve hv-24x7 pmu event counter data.
+
What: /sys/bus/event_source/devices/hv_24x7/event_descs/<event-name>
Date: February 2014
Contact: Linux on PowerPC Developer List <linuxppc-dev@lists.ozlabs.org>
diff --git a/Documentation/ABI/testing/sysfs-bus-iio b/Documentation/ABI/testing/sysfs-bus-iio
index d3e53a6..5c62bfb 100644
--- a/Documentation/ABI/testing/sysfs-bus-iio
+++ b/Documentation/ABI/testing/sysfs-bus-iio
@@ -1569,7 +1569,8 @@
KernelVersion: 4.3
Contact: linux-iio@vger.kernel.org
Description:
- Raw (unscaled no offset etc.) percentage reading of a substance.
+ Raw (unscaled no offset etc.) reading of a substance. Units
+ after application of scale and offset are percents.
What: /sys/bus/iio/devices/iio:deviceX/in_resistance_raw
What: /sys/bus/iio/devices/iio:deviceX/in_resistanceX_raw
diff --git a/Documentation/ABI/testing/sysfs-bus-iio-icm42600 b/Documentation/ABI/testing/sysfs-bus-iio-icm42600
new file mode 100644
index 0000000..0bf1fd4
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-bus-iio-icm42600
@@ -0,0 +1,20 @@
+What: /sys/bus/iio/devices/iio:deviceX/in_accel_x_calibbias
+What: /sys/bus/iio/devices/iio:deviceX/in_accel_y_calibbias
+What: /sys/bus/iio/devices/iio:deviceX/in_accel_z_calibbias
+What: /sys/bus/iio/devices/iio:deviceX/in_anglvel_x_calibbias
+What: /sys/bus/iio/devices/iio:deviceX/in_anglvel_y_calibbias
+What: /sys/bus/iio/devices/iio:deviceX/in_anglvel_z_calibbias
+KernelVersion: 5.8
+Contact: linux-iio@vger.kernel.org
+Description:
+ Hardware applied calibration offset (assumed to fix production
+ inaccuracies). Values represent a real physical offset expressed
+ in SI units (m/s^2 for accelerometer and rad/s for gyroscope).
+
+What: /sys/bus/iio/devices/iio:deviceX/in_accel_calibbias_available
+What: /sys/bus/iio/devices/iio:deviceX/in_anglvel_calibbias_available
+KernelVersion: 5.8
+Contact: linux-iio@vger.kernel.org
+Description:
+ Range of available values for hardware offset. Values in SI
+ units (m/s^2 for accelerometer and rad/s for gyroscope).
diff --git a/Documentation/ABI/testing/sysfs-bus-iio-scd30 b/Documentation/ABI/testing/sysfs-bus-iio-scd30
new file mode 100644
index 0000000..b9712f3
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-bus-iio-scd30
@@ -0,0 +1,34 @@
+What: /sys/bus/iio/devices/iio:deviceX/calibration_auto_enable
+Date: June 2020
+KernelVersion: 5.8
+Contact: linux-iio@vger.kernel.org
+Description:
+ Contaminants build-up in the measurement chamber or optical
+ elements deterioration leads to sensor drift.
+
+ One can compensate for sensor drift by using automatic self
+ calibration procedure (asc).
+
+ Writing 1 or 0 to this attribute will respectively activate or
+ deactivate asc.
+
+ Upon reading current asc status is returned.
+
+What: /sys/bus/iio/devices/iio:deviceX/calibration_forced_value
+Date: June 2020
+KernelVersion: 5.8
+Contact: linux-iio@vger.kernel.org
+Description:
+ Contaminants build-up in the measurement chamber or optical
+ elements deterioration leads to sensor drift.
+
+ One can compensate for sensor drift by using forced
+ recalibration (frc). This is useful in case there's known
+ co2 reference available nearby the sensor.
+
+ Picking value from the range [400 1 2000] and writing it to the
+ sensor will set frc.
+
+ Upon reading current frc value is returned. Note that after
+ power cycling default value (i.e 400) is returned even though
+ internally sensor had recalibrated itself.
diff --git a/Documentation/ABI/testing/sysfs-bus-nfit b/Documentation/ABI/testing/sysfs-bus-nfit
index a1cb44d..e4f76e7 100644
--- a/Documentation/ABI/testing/sysfs-bus-nfit
+++ b/Documentation/ABI/testing/sysfs-bus-nfit
@@ -202,6 +202,25 @@
functions. See the section named 'NVDIMM Root Device _DSMs' in
the ACPI specification.
+What: /sys/bus/nd/devices/ndbusX/nfit/firmware_activate_noidle
+Date: Apr, 2020
+KernelVersion: v5.8
+Contact: linux-nvdimm@lists.01.org
+Description:
+ (RW) The Intel platform implementation of firmware activate
+ support exposes an option let the platform force idle devices in
+ the system over the activation event, or trust that the OS will
+ do it. The safe default is to let the platform force idle
+ devices since the kernel is already in a suspend state, and on
+ the chance that a driver does not properly quiesce bus-mastering
+ after a suspend callback the platform will handle it. However,
+ the activation might abort if, for example, platform firmware
+ determines that the activation time exceeds the max PCI-E
+ completion timeout. Since the platform does not know whether the
+ OS is running the activation from a suspend context it aborts,
+ but if the system owner trusts driver suspend callback to be
+ sufficient then 'firmware_activation_noidle' can be
+ enabled to bypass the activation abort.
What: /sys/bus/nd/devices/regionX/nfit/range_index
Date: Jun, 2015
diff --git a/Documentation/ABI/testing/sysfs-bus-nvdimm b/Documentation/ABI/testing/sysfs-bus-nvdimm
new file mode 100644
index 0000000..d643802
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-bus-nvdimm
@@ -0,0 +1,2 @@
+The libnvdimm sub-system implements a common sysfs interface for
+platform nvdimm resources. See Documentation/driver-api/nvdimm/.
diff --git a/Documentation/ABI/testing/sysfs-bus-optee-devices b/Documentation/ABI/testing/sysfs-bus-optee-devices
new file mode 100644
index 0000000..0f58701
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-bus-optee-devices
@@ -0,0 +1,8 @@
+What: /sys/bus/tee/devices/optee-ta-<uuid>/
+Date: May 2020
+KernelVersion 5.8
+Contact: op-tee@lists.trustedfirmware.org
+Description:
+ OP-TEE bus provides reference to registered drivers under this directory. The <uuid>
+ matches Trusted Application (TA) driver and corresponding TA in secure OS. Drivers
+ are free to create needed API under optee-ta-<uuid> directory.
diff --git a/Documentation/ABI/testing/sysfs-bus-papr-pmem b/Documentation/ABI/testing/sysfs-bus-papr-pmem
new file mode 100644
index 0000000..c1a6727
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-bus-papr-pmem
@@ -0,0 +1,54 @@
+What: /sys/bus/nd/devices/nmemX/papr/flags
+Date: Apr, 2020
+KernelVersion: v5.8
+Contact: linuxppc-dev <linuxppc-dev@lists.ozlabs.org>, linux-nvdimm@lists.01.org,
+Description:
+ (RO) Report flags indicating various states of a
+ papr-pmem NVDIMM device. Each flag maps to a one or
+ more bits set in the dimm-health-bitmap retrieved in
+ response to H_SCM_HEALTH hcall. The details of the bit
+ flags returned in response to this hcall is available
+ at 'Documentation/powerpc/papr_hcalls.rst' . Below are
+ the flags reported in this sysfs file:
+
+ * "not_armed" : Indicates that NVDIMM contents will not
+ survive a power cycle.
+ * "flush_fail" : Indicates that NVDIMM contents
+ couldn't be flushed during last
+ shut-down event.
+ * "restore_fail": Indicates that NVDIMM contents
+ couldn't be restored during NVDIMM
+ initialization.
+ * "encrypted" : NVDIMM contents are encrypted.
+ * "smart_notify": There is health event for the NVDIMM.
+ * "scrubbed" : Indicating that contents of the
+ NVDIMM have been scrubbed.
+ * "locked" : Indicating that NVDIMM contents cant
+ be modified until next power cycle.
+
+What: /sys/bus/nd/devices/nmemX/papr/perf_stats
+Date: May, 2020
+KernelVersion: v5.9
+Contact: linuxppc-dev <linuxppc-dev@lists.ozlabs.org>, linux-nvdimm@lists.01.org,
+Description:
+ (RO) Report various performance stats related to papr-scm NVDIMM
+ device. Each stat is reported on a new line with each line
+ composed of a stat-identifier followed by it value. Below are
+ currently known dimm performance stats which are reported:
+
+ * "CtlResCt" : Controller Reset Count
+ * "CtlResTm" : Controller Reset Elapsed Time
+ * "PonSecs " : Power-on Seconds
+ * "MemLife " : Life Remaining
+ * "CritRscU" : Critical Resource Utilization
+ * "HostLCnt" : Host Load Count
+ * "HostSCnt" : Host Store Count
+ * "HostSDur" : Host Store Duration
+ * "HostLDur" : Host Load Duration
+ * "MedRCnt " : Media Read Count
+ * "MedWCnt " : Media Write Count
+ * "MedRDur " : Media Read Duration
+ * "MedWDur " : Media Write Duration
+ * "CchRHCnt" : Cache Read Hit Count
+ * "CchWHCnt" : Cache Write Hit Count
+ * "FastWCnt" : Fast Write Count
\ No newline at end of file
diff --git a/Documentation/ABI/testing/sysfs-bus-platform b/Documentation/ABI/testing/sysfs-bus-platform
index 5172a61..194ca70 100644
--- a/Documentation/ABI/testing/sysfs-bus-platform
+++ b/Documentation/ABI/testing/sysfs-bus-platform
@@ -18,3 +18,13 @@
devices to opt-out of driver binding using a driver_override
name such as "none". Only a single driver may be specified in
the override, there is no support for parsing delimiters.
+
+What: /sys/bus/platform/devices/.../numa_node
+Date: June 2020
+Contact: Barry Song <song.bao.hua@hisilicon.com>
+Description:
+ This file contains the NUMA node to which the platform device
+ is attached. It won't be visible if the node is unknown. The
+ value comes from an ACPI _PXM method or a similar firmware
+ source. Initial users for this file would be devices like
+ arm smmu which are populated by arm64 acpi_iort.
diff --git a/Documentation/ABI/testing/sysfs-bus-thunderbolt b/Documentation/ABI/testing/sysfs-bus-thunderbolt
index 82e80de..dd565c3 100644
--- a/Documentation/ABI/testing/sysfs-bus-thunderbolt
+++ b/Documentation/ABI/testing/sysfs-bus-thunderbolt
@@ -178,11 +178,18 @@
Contact: thunderbolt-software@lists.01.org
Description: When new NVM image is written to the non-active NVM
area (through non_activeX NVMem device), the
- authentication procedure is started by writing 1 to
- this file. If everything goes well, the device is
+ authentication procedure is started by writing to
+ this file.
+ If everything goes well, the device is
restarted with the new NVM firmware. If the image
verification fails an error code is returned instead.
+ This file will accept writing values "1" or "2"
+ - Writing "1" will flush the image to the storage
+ area and authenticate the image in one action.
+ - Writing "2" will run some basic validation on the image
+ and flush it to the storage area.
+
When read holds status of the last authentication
operation if an error occurred during the process. This
is directly the status value from the DMA configuration
@@ -236,3 +243,49 @@
Contact: thunderbolt-software@lists.01.org
Description: This contains XDomain service specific settings as
bitmask. Format: %x
+
+What: /sys/bus/thunderbolt/devices/<device>:<port>.<index>/device
+Date: Oct 2020
+KernelVersion: v5.9
+Contact: Mika Westerberg <mika.westerberg@linux.intel.com>
+Description: Retimer device identifier read from the hardware.
+
+What: /sys/bus/thunderbolt/devices/<device>:<port>.<index>/nvm_authenticate
+Date: Oct 2020
+KernelVersion: v5.9
+Contact: Mika Westerberg <mika.westerberg@linux.intel.com>
+Description: When new NVM image is written to the non-active NVM
+ area (through non_activeX NVMem device), the
+ authentication procedure is started by writing 1 to
+ this file. If everything goes well, the device is
+ restarted with the new NVM firmware. If the image
+ verification fails an error code is returned instead.
+
+ When read holds status of the last authentication
+ operation if an error occurred during the process.
+ Format: %x.
+
+What: /sys/bus/thunderbolt/devices/<device>:<port>.<index>/nvm_version
+Date: Oct 2020
+KernelVersion: v5.9
+Contact: Mika Westerberg <mika.westerberg@linux.intel.com>
+Description: Holds retimer NVM version number. Format: %x.%x, major.minor.
+
+What: /sys/bus/thunderbolt/devices/<device>:<port>.<index>/vendor
+Date: Oct 2020
+KernelVersion: v5.9
+Contact: Mika Westerberg <mika.westerberg@linux.intel.com>
+Description: Retimer vendor identifier read from the hardware.
+
+What: /sys/bus/thunderbolt/devices/.../nvm_authenticate_on_disconnect
+Date: Oct 2020
+KernelVersion: v5.9
+Contact: Mario Limonciello <mario.limonciello@dell.com>
+Description: For supported devices, automatically authenticate the new Thunderbolt
+ image when the device is disconnected from the host system.
+
+ This file will accept writing values "1" or "2"
+ - Writing "1" will flush the image to the storage
+ area and prepare the device for authentication on disconnect.
+ - Writing "2" will run some basic validation on the image
+ and flush it to the storage area.
diff --git a/Documentation/ABI/testing/sysfs-class-devfreq b/Documentation/ABI/testing/sysfs-class-devfreq
index 9758eb8..deefffb 100644
--- a/Documentation/ABI/testing/sysfs-class-devfreq
+++ b/Documentation/ABI/testing/sysfs-class-devfreq
@@ -108,3 +108,15 @@
frequency requested by governors and min_freq.
The max_freq overrides min_freq because max_freq may be
used to throttle devices to avoid overheating.
+
+What: /sys/class/devfreq/.../timer
+Date: July 2020
+Contact: Chanwoo Choi <cw00.choi@samsung.com>
+Description:
+ This ABI shows and stores the kind of work timer by users.
+ This work timer is used by devfreq workqueue in order to
+ monitor the device status such as utilization. The user
+ can change the work timer on runtime according to their demand
+ as following:
+ echo deferrable > /sys/class/devfreq/.../timer
+ echo delayed > /sys/class/devfreq/.../timer
diff --git a/Documentation/ABI/testing/sysfs-class-devlink b/Documentation/ABI/testing/sysfs-class-devlink
new file mode 100644
index 0000000..64791b6
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-class-devlink
@@ -0,0 +1,126 @@
+What: /sys/class/devlink/.../
+Date: May 2020
+Contact: Saravana Kannan <saravanak@google.com>
+Description:
+ Provide a place in sysfs for the device link objects in the
+ kernel at any given time. The name of a device link directory,
+ denoted as ... above, is of the form <supplier>--<consumer>
+ where <supplier> is the supplier device name and <consumer> is
+ the consumer device name.
+
+What: /sys/class/devlink/.../auto_remove_on
+Date: May 2020
+Contact: Saravana Kannan <saravanak@google.com>
+Description:
+ This file indicates if the device link will ever be
+ automatically removed by the driver core when the consumer and
+ supplier devices themselves are still present.
+
+ This will be one of the following strings:
+
+ 'consumer unbind'
+ 'supplier unbind'
+ 'never'
+
+ 'consumer unbind' means the device link will be removed when
+ the consumer's driver is unbound from the consumer device.
+
+ 'supplier unbind' means the device link will be removed when
+ the supplier's driver is unbound from the supplier device.
+
+ 'never' means the device link will not be automatically removed
+ when as long as the supplier and consumer devices themselves
+ are still present.
+
+What: /sys/class/devlink/.../consumer
+Date: May 2020
+Contact: Saravana Kannan <saravanak@google.com>
+Description:
+ This file is a symlink to the consumer device's sysfs directory.
+
+What: /sys/class/devlink/.../runtime_pm
+Date: May 2020
+Contact: Saravana Kannan <saravanak@google.com>
+Description:
+ This file indicates if the device link has any impact on the
+ runtime power management behavior of the consumer and supplier
+ devices. For example: Making sure the supplier doesn't enter
+ runtime suspend while the consumer is active.
+
+ This will be one of the following strings:
+
+ '0' - Does not affect runtime power management
+ '1' - Affects runtime power management
+
+What: /sys/class/devlink/.../status
+Date: May 2020
+Contact: Saravana Kannan <saravanak@google.com>
+Description:
+ This file indicates the status of the device link. The status
+ of a device link is affected by whether the supplier and
+ consumer devices have been bound to their corresponding
+ drivers. The status of a device link also affects the binding
+ and unbinding of the supplier and consumer devices with their
+ drivers and also affects whether the software state of the
+ supplier device is synced with the hardware state of the
+ supplier device after boot up.
+ See also: sysfs-devices-state_synced.
+
+ This will be one of the following strings:
+
+ 'not tracked'
+ 'dormant'
+ 'available'
+ 'consumer probing'
+ 'active'
+ 'supplier unbinding'
+ 'unknown'
+
+ 'not tracked' means this device link does not track the status
+ and has no impact on the binding, unbinding and syncing the
+ hardware and software device state.
+
+ 'dormant' means the supplier and the consumer devices have not
+ bound to their driver.
+
+ 'available' means the supplier has bound to its driver and is
+ available to supply resources to the consumer device.
+
+ 'consumer probing' means the consumer device is currently
+ trying to bind to its driver.
+
+ 'active' means the supplier and consumer devices have both
+ bound successfully to their drivers.
+
+ 'supplier unbinding' means the supplier devices is currently in
+ the process of unbinding from its driver.
+
+ 'unknown' means the state of the device link is not any of the
+ above. If this is ever the value, there's a bug in the kernel.
+
+What: /sys/class/devlink/.../supplier
+Date: May 2020
+Contact: Saravana Kannan <saravanak@google.com>
+Description:
+ This file is a symlink to the supplier device's sysfs directory.
+
+What: /sys/class/devlink/.../sync_state_only
+Date: May 2020
+Contact: Saravana Kannan <saravanak@google.com>
+Description:
+ This file indicates if the device link is limited to only
+ affecting the syncing of the hardware and software state of the
+ supplier device.
+
+ This will be one of the following strings:
+
+ '0'
+ '1' - Affects runtime power management
+
+ '0' means the device link can affect other device behaviors
+ like binding/unbinding, suspend/resume, runtime power
+ management, etc.
+
+ '1' means the device link will only affect the syncing of
+ hardware and software state of the supplier device after boot
+ up and doesn't not affect other behaviors of the devices.
diff --git a/Documentation/ABI/testing/sysfs-class-led-driver-turris-omnia b/Documentation/ABI/testing/sysfs-class-led-driver-turris-omnia
new file mode 100644
index 0000000..795a5de
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-class-led-driver-turris-omnia
@@ -0,0 +1,14 @@
+What: /sys/class/leds/<led>/device/brightness
+Date: July 2020
+KernelVersion: 5.9
+Contact: Marek Behún <marek.behun@nic.cz>
+Description: (RW) On the front panel of the Turris Omnia router there is also
+ a button which can be used to control the intensity of all the
+ LEDs at once, so that if they are too bright, user can dim them.
+
+ The microcontroller cycles between 8 levels of this global
+ brightness (from 100% to 0%), but this setting can have any
+ integer value between 0 and 100. It is therefore convenient to be
+ able to change this setting from software.
+
+ Format: %i
diff --git a/Documentation/ABI/testing/sysfs-class-led-multicolor b/Documentation/ABI/testing/sysfs-class-led-multicolor
new file mode 100644
index 0000000..eeeddcb
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-class-led-multicolor
@@ -0,0 +1,35 @@
+What: /sys/class/leds/<led>/brightness
+Date: March 2020
+KernelVersion: 5.9
+Contact: Dan Murphy <dmurphy@ti.com>
+Description: read/write
+ Writing to this file will update all LEDs within the group to a
+ calculated percentage of what each color LED intensity is set
+ to. The percentage is calculated for each grouped LED via the
+ equation below:
+
+ led_brightness = brightness * multi_intensity/max_brightness
+
+ For additional details please refer to
+ Documentation/leds/leds-class-multicolor.rst.
+
+ The value of the LED is from 0 to
+ /sys/class/leds/<led>/max_brightness.
+
+What: /sys/class/leds/<led>/multi_index
+Date: March 2020
+KernelVersion: 5.9
+Contact: Dan Murphy <dmurphy@ti.com>
+Description: read
+ The multi_index array, when read, will output the LED colors
+ as an array of strings as they are indexed in the
+ multi_intensity file.
+
+What: /sys/class/leds/<led>/multi_intensity
+Date: March 2020
+KernelVersion: 5.9
+Contact: Dan Murphy <dmurphy@ti.com>
+Description: read/write
+ This file contains array of integers. Order of components is
+ described by the multi_index array. The maximum intensity should
+ not exceed /sys/class/leds/<led>/max_brightness.
diff --git a/Documentation/ABI/testing/sysfs-class-mei b/Documentation/ABI/testing/sysfs-class-mei
index e9dc110..5c52372 100644
--- a/Documentation/ABI/testing/sysfs-class-mei
+++ b/Documentation/ABI/testing/sysfs-class-mei
@@ -90,3 +90,16 @@
The ME FW writes Glitch Detection HW (TRC)
status information into trc status register
for BIOS and OS to monitor fw health.
+
+What: /sys/class/mei/meiN/kind
+Date: Jul 2020
+KernelVersion: 5.8
+Contact: Tomas Winkler <tomas.winkler@intel.com>
+Description: Display kind of the device
+
+ Generic devices are marked as "mei"
+ while special purpose have their own
+ names.
+ Available options:
+ - mei: generic mei device.
+ - itouch: itouch (ipts) mei device.
diff --git a/Documentation/ABI/testing/sysfs-class-ocxl b/Documentation/ABI/testing/sysfs-class-ocxl
index b5b1fa1..ae1276e 100644
--- a/Documentation/ABI/testing/sysfs-class-ocxl
+++ b/Documentation/ABI/testing/sysfs-class-ocxl
@@ -33,3 +33,14 @@
Contact: linuxppc-dev@lists.ozlabs.org
Description: read/write
Give access the global mmio area for the AFU
+
+What: /sys/class/ocxl/<afu name>/reload_on_reset
+Date: February 2020
+Contact: linuxppc-dev@lists.ozlabs.org
+Description: read/write
+ Control whether the FPGA is reloaded on a link reset. Enabled
+ through a vendor-specific logic block on the FPGA.
+ 0 Do not reload FPGA image from flash
+ 1 Reload FPGA image from flash
+ unavailable
+ The device does not support this capability
diff --git a/Documentation/ABI/testing/sysfs-class-power b/Documentation/ABI/testing/sysfs-class-power
index 216d61a..40213c7 100644
--- a/Documentation/ABI/testing/sysfs-class-power
+++ b/Documentation/ABI/testing/sysfs-class-power
@@ -205,7 +205,8 @@
Valid values: "Unknown", "Good", "Overheat", "Dead",
"Over voltage", "Unspecified failure", "Cold",
"Watchdog timer expire", "Safety timer expire",
- "Over current", "Calibration required"
+ "Over current", "Calibration required", "Warm",
+ "Cool", "Hot"
What: /sys/class/power_supply/<supply_name>/precharge_current
Date: June 2017
diff --git a/Documentation/ABI/testing/sysfs-class-power-wilco b/Documentation/ABI/testing/sysfs-class-power-wilco
index da1d6ff..84fde1d 100644
--- a/Documentation/ABI/testing/sysfs-class-power-wilco
+++ b/Documentation/ABI/testing/sysfs-class-power-wilco
@@ -14,6 +14,10 @@
Charging begins when level drops below
charge_control_start_threshold, and ceases when
level is above charge_control_end_threshold.
+ Long Life: Customized charge rate for last longer battery life.
+ On Wilco device this mode is pre-configured in the factory
+ through EC's private PID. Swiching to a different mode will
+ be denied by Wilco EC when Long Life mode is enabled.
What: /sys/class/power_supply/wilco-charger/charge_control_start_threshold
Date: April 2019
diff --git a/Documentation/ABI/testing/sysfs-devices-consumer b/Documentation/ABI/testing/sysfs-devices-consumer
new file mode 100644
index 0000000..1f06d74
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-devices-consumer
@@ -0,0 +1,8 @@
+What: /sys/devices/.../consumer:<consumer>
+Date: May 2020
+Contact: Saravana Kannan <saravanak@google.com>
+Description:
+ The /sys/devices/.../consumer:<consumer> are symlinks to device
+ links where this device is the supplier. <consumer> denotes the
+ name of the consumer in that device link. There can be zero or
+ more of these symlinks for a given device.
diff --git a/Documentation/ABI/testing/sysfs-devices-mapping b/Documentation/ABI/testing/sysfs-devices-mapping
new file mode 100644
index 0000000..490ccfd
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-devices-mapping
@@ -0,0 +1,33 @@
+What: /sys/devices/uncore_iio_x/dieX
+Date: February 2020
+Contact: Roman Sudarikov <roman.sudarikov@linux.intel.com>
+Description:
+ Each IIO stack (PCIe root port) has its own IIO PMON block, so
+ each dieX file (where X is die number) holds "Segment:Root Bus"
+ for PCIe root port, which can be monitored by that IIO PMON
+ block.
+ For example, on 4-die Xeon platform with up to 6 IIO stacks per
+ die and, therefore, 6 IIO PMON blocks per die, the mapping of
+ IIO PMON block 0 exposes as the following:
+
+ $ ls /sys/devices/uncore_iio_0/die*
+ -r--r--r-- /sys/devices/uncore_iio_0/die0
+ -r--r--r-- /sys/devices/uncore_iio_0/die1
+ -r--r--r-- /sys/devices/uncore_iio_0/die2
+ -r--r--r-- /sys/devices/uncore_iio_0/die3
+
+ $ tail /sys/devices/uncore_iio_0/die*
+ ==> /sys/devices/uncore_iio_0/die0 <==
+ 0000:00
+ ==> /sys/devices/uncore_iio_0/die1 <==
+ 0000:40
+ ==> /sys/devices/uncore_iio_0/die2 <==
+ 0000:80
+ ==> /sys/devices/uncore_iio_0/die3 <==
+ 0000:c0
+
+ Which means:
+ IIO PMU 0 on die 0 belongs to PCI RP on bus 0x00, domain 0x0000
+ IIO PMU 0 on die 1 belongs to PCI RP on bus 0x40, domain 0x0000
+ IIO PMU 0 on die 2 belongs to PCI RP on bus 0x80, domain 0x0000
+ IIO PMU 0 on die 3 belongs to PCI RP on bus 0xc0, domain 0x0000
diff --git a/Documentation/ABI/testing/sysfs-devices-platform-stratix10-rsu b/Documentation/ABI/testing/sysfs-devices-platform-stratix10-rsu
index ae9af98..a8daceb 100644
--- a/Documentation/ABI/testing/sysfs-devices-platform-stratix10-rsu
+++ b/Documentation/ABI/testing/sysfs-devices-platform-stratix10-rsu
@@ -126,3 +126,39 @@
1 no action
0 firmware record the notify code defined
in b[15:0].
+
+What: /sys/devices/platform/stratix10-rsu.0/dcmf0
+Date: June 2020
+KernelVersion: 5.8
+Contact: Richard Gong <richard.gong@linux.intel.com>
+Description:
+ (RO) Decision firmware copy 0 version information.
+
+What: /sys/devices/platform/stratix10-rsu.0/dcmf1
+Date: June 2020
+KernelVersion: 5.8
+Contact: Richard Gong <richard.gong@linux.intel.com>
+Description:
+ (RO) Decision firmware copy 1 version information.
+
+What: /sys/devices/platform/stratix10-rsu.0/dcmf2
+Date: June 2020
+KernelVersion: 5.8
+Contact: Richard Gong <richard.gong@linux.intel.com>
+Description:
+ (RO) Decision firmware copy 2 version information.
+
+What: /sys/devices/platform/stratix10-rsu.0/dcmf3
+Date: June 2020
+KernelVersion: 5.8
+Contact: Richard Gong <richard.gong@linux.intel.com>
+Description:
+ (RO) Decision firmware copy 3 version information.
+
+What: /sys/devices/platform/stratix10-rsu.0/max_retry
+Date: June 2020
+KernelVersion: 5.8
+Contact: Richard Gong <richard.gong@linux.intel.com>
+Description:
+ (RO) max retry parameter is stored in the firmware
+ decision IO section, as a byte located at offset 0x18c.
diff --git a/Documentation/ABI/testing/sysfs-devices-soc b/Documentation/ABI/testing/sysfs-devices-soc
index ba3a3fa..ea999e2 100644
--- a/Documentation/ABI/testing/sysfs-devices-soc
+++ b/Documentation/ABI/testing/sysfs-devices-soc
@@ -26,6 +26,30 @@
Read-only attribute common to all SoCs. Contains SoC family name
(e.g. DB8500).
+ On many of ARM based silicon with SMCCC v1.2+ compliant firmware
+ this will contain the JEDEC JEP106 manufacturer’s identification
+ code. The format is "jep106:XXYY" where XX is identity code and
+ YY is continuation code.
+
+ This manufacturer’s identification code is defined by one
+ or more eight (8) bit fields, each consisting of seven (7)
+ data bits plus one (1) odd parity bit. It is a single field,
+ limiting the possible number of vendors to 126. To expand
+ the maximum number of identification codes, a continuation
+ scheme has been defined.
+
+ The specified mechanism is that an identity code of 0x7F
+ represents the "continuation code" and implies the presence
+ of an additional identity code field, and this mechanism
+ may be extended to multiple continuation codes followed
+ by the manufacturer's identity code.
+
+ For example, ARM has identity code 0x7F 0x7F 0x7F 0x7F 0x3B,
+ which is code 0x3B on the fifth 'page'. This is shortened
+ as JEP106 identity code of 0x3B and a continuation code of
+ 0x4 to represent the four continuation codes preceding the
+ identity code.
+
What: /sys/devices/socX/serial_number
Date: January 2019
contact: Bjorn Andersson <bjorn.andersson@linaro.org>
@@ -40,6 +64,12 @@
Read-only attribute supported by most SoCs. In the case of
ST-Ericsson's chips this contains the SoC serial number.
+ On many of ARM based silicon with SMCCC v1.2+ compliant firmware
+ this will contain the SOC ID appended to the family attribute
+ to ensure there is no conflict in this namespace across various
+ vendors. The format is "jep106:XXYY:ZZZZ" where XX is identity
+ code, YY is continuation code and ZZZZ is the SOC ID.
+
What: /sys/devices/socX/revision
Date: January 2012
contact: Lee Jones <lee.jones@linaro.org>
diff --git a/Documentation/ABI/testing/sysfs-devices-state_synced b/Documentation/ABI/testing/sysfs-devices-state_synced
new file mode 100644
index 0000000..0c922d7
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-devices-state_synced
@@ -0,0 +1,24 @@
+What: /sys/devices/.../state_synced
+Date: May 2020
+Contact: Saravana Kannan <saravanak@google.com>
+Description:
+ The /sys/devices/.../state_synced attribute is only present for
+ devices whose bus types or driver provides the .sync_state()
+ callback. The number read from it (0 or 1) reflects the value
+ of the device's 'state_synced' field. A value of 0 means the
+ .sync_state() callback hasn't been called yet. A value of 1
+ means the .sync_state() callback has been called.
+
+ Generally, if a device has sync_state() support and has some of
+ the resources it provides enabled at the time the kernel starts
+ (Eg: enabled by hardware reset or bootloader or anything that
+ run before the kernel starts), then it'll keep those resources
+ enabled and in a state that's compatible with the state they
+ were in at the start of the kernel. The device will stop doing
+ this only when the sync_state() callback has been called --
+ which happens only when all its consumer devices are registered
+ and have probed successfully. Resources that were left disabled
+ at the time the kernel starts are not affected or limited in
+ any way by sync_state() callbacks.
+
+
diff --git a/Documentation/ABI/testing/sysfs-devices-supplier b/Documentation/ABI/testing/sysfs-devices-supplier
new file mode 100644
index 0000000..a919e0d
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-devices-supplier
@@ -0,0 +1,8 @@
+What: /sys/devices/.../supplier:<supplier>
+Date: May 2020
+Contact: Saravana Kannan <saravanak@google.com>
+Description:
+ The /sys/devices/.../supplier:<supplier> are symlinks to device
+ links where this device is the consumer. <supplier> denotes the
+ name of the supplier in that device link. There can be zero or
+ more of these symlinks for a given device.
diff --git a/Documentation/ABI/testing/sysfs-devices-waiting_for_supplier b/Documentation/ABI/testing/sysfs-devices-waiting_for_supplier
new file mode 100644
index 0000000..59d073d
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-devices-waiting_for_supplier
@@ -0,0 +1,17 @@
+What: /sys/devices/.../waiting_for_supplier
+Date: May 2020
+Contact: Saravana Kannan <saravanak@google.com>
+Description:
+ The /sys/devices/.../waiting_for_supplier attribute is only
+ present when fw_devlink kernel command line option is enabled
+ and is set to something stricter than "permissive". It is
+ removed once a device probes successfully (because the
+ information is no longer relevant). The number read from it (0
+ or 1) reflects whether the device is waiting for one or more
+ suppliers to be added and then linked to using device links
+ before the device can probe.
+
+ A value of 0 means the device is not waiting for any suppliers
+ to be added before it can probe. A value of 1 means the device
+ is waiting for one or more suppliers to be added before it can
+ probe.
diff --git a/Documentation/ABI/testing/sysfs-driver-input-exc3000 b/Documentation/ABI/testing/sysfs-driver-input-exc3000
new file mode 100644
index 0000000..3d316d5
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-driver-input-exc3000
@@ -0,0 +1,15 @@
+What: /sys/bus/i2c/devices/xxx/fw_version
+Date: Aug 2020
+Contact: linux-input@vger.kernel.org
+Description: Reports the firmware version provided by the touchscreen, for example "00_T6" on a EXC80H60
+
+ Access: Read
+ Valid values: Represented as string
+
+What: /sys/bus/i2c/devices/xxx/model
+Date: Aug 2020
+Contact: linux-input@vger.kernel.org
+Description: Reports the model identification provided by the touchscreen, for example "Orion_1320" on a EXC80H60
+
+ Access: Read
+ Valid values: Represented as string
diff --git a/Documentation/ABI/testing/sysfs-driver-ufs b/Documentation/ABI/testing/sysfs-driver-ufs
index 016724e..d1a3521 100644
--- a/Documentation/ABI/testing/sysfs-driver-ufs
+++ b/Documentation/ABI/testing/sysfs-driver-ufs
@@ -883,3 +883,139 @@
Description: This entry shows the target state of an UFS UIC link
for the chosen system power management level.
The file is read only.
+
+What: /sys/bus/platform/drivers/ufshcd/*/device_descriptor/wb_presv_us_en
+Date: June 2020
+Contact: Asutosh Das <asutoshd@codeaurora.org>
+Description: This entry shows if preserve user-space was configured
+ The file is read only.
+
+What: /sys/bus/platform/drivers/ufshcd/*/device_descriptor/wb_shared_alloc_units
+Date: June 2020
+Contact: Asutosh Das <asutoshd@codeaurora.org>
+Description: This entry shows the shared allocated units of WB buffer
+ The file is read only.
+
+What: /sys/bus/platform/drivers/ufshcd/*/device_descriptor/wb_type
+Date: June 2020
+Contact: Asutosh Das <asutoshd@codeaurora.org>
+Description: This entry shows the configured WB type.
+ 0x1 for shared buffer mode. 0x0 for dedicated buffer mode.
+ The file is read only.
+
+What: /sys/bus/platform/drivers/ufshcd/*/geometry_descriptor/wb_buff_cap_adj
+Date: June 2020
+Contact: Asutosh Das <asutoshd@codeaurora.org>
+Description: This entry shows the total user-space decrease in shared
+ buffer mode.
+ The value of this parameter is 3 for TLC NAND when SLC mode
+ is used as WriteBooster Buffer. 2 for MLC NAND.
+ The file is read only.
+
+What: /sys/bus/platform/drivers/ufshcd/*/geometry_descriptor/wb_max_alloc_units
+Date: June 2020
+Contact: Asutosh Das <asutoshd@codeaurora.org>
+Description: This entry shows the Maximum total WriteBooster Buffer size
+ which is supported by the entire device.
+ The file is read only.
+
+What: /sys/bus/platform/drivers/ufshcd/*/geometry_descriptor/wb_max_wb_luns
+Date: June 2020
+Contact: Asutosh Das <asutoshd@codeaurora.org>
+Description: This entry shows the maximum number of luns that can support
+ WriteBooster.
+ The file is read only.
+
+What: /sys/bus/platform/drivers/ufshcd/*/geometry_descriptor/wb_sup_red_type
+Date: June 2020
+Contact: Asutosh Das <asutoshd@codeaurora.org>
+Description: The supportability of user space reduction mode
+ and preserve user space mode.
+ 00h: WriteBooster Buffer can be configured only in
+ user space reduction type.
+ 01h: WriteBooster Buffer can be configured only in
+ preserve user space type.
+ 02h: Device can be configured in either user space
+ reduction type or preserve user space type.
+ The file is read only.
+
+What: /sys/bus/platform/drivers/ufshcd/*/geometry_descriptor/wb_sup_wb_type
+Date: June 2020
+Contact: Asutosh Das <asutoshd@codeaurora.org>
+Description: The supportability of WriteBooster Buffer type.
+ 00h: LU based WriteBooster Buffer configuration
+ 01h: Single shared WriteBooster Buffer
+ configuration
+ 02h: Supporting both LU based WriteBooster
+ Buffer and Single shared WriteBooster Buffer
+ configuration
+ The file is read only.
+
+What: /sys/bus/platform/drivers/ufshcd/*/flags/wb_enable
+Date: June 2020
+Contact: Asutosh Das <asutoshd@codeaurora.org>
+Description: This entry shows the status of WriteBooster.
+ 0: WriteBooster is not enabled.
+ 1: WriteBooster is enabled
+ The file is read only.
+
+What: /sys/bus/platform/drivers/ufshcd/*/flags/wb_flush_en
+Date: June 2020
+Contact: Asutosh Das <asutoshd@codeaurora.org>
+Description: This entry shows if flush is enabled.
+ 0: Flush operation is not performed.
+ 1: Flush operation is performed.
+ The file is read only.
+
+What: /sys/bus/platform/drivers/ufshcd/*/flags/wb_flush_during_h8
+Date: June 2020
+Contact: Asutosh Das <asutoshd@codeaurora.org>
+Description: Flush WriteBooster Buffer during hibernate state.
+ 0: Device is not allowed to flush the
+ WriteBooster Buffer during link hibernate
+ state.
+ 1: Device is allowed to flush the
+ WriteBooster Buffer during link hibernate
+ state
+ The file is read only.
+
+What: /sys/bus/platform/drivers/ufshcd/*/attributes/wb_avail_buf
+Date: June 2020
+Contact: Asutosh Das <asutoshd@codeaurora.org>
+Description: This entry shows the amount of unused WriteBooster buffer
+ available.
+ The file is read only.
+
+What: /sys/bus/platform/drivers/ufshcd/*/attributes/wb_cur_buf
+Date: June 2020
+Contact: Asutosh Das <asutoshd@codeaurora.org>
+Description: This entry shows the amount of unused current buffer.
+ The file is read only.
+
+What: /sys/bus/platform/drivers/ufshcd/*/attributes/wb_flush_status
+Date: June 2020
+Contact: Asutosh Das <asutoshd@codeaurora.org>
+Description: This entry shows the flush operation status.
+ 00h: idle
+ 01h: Flush operation in progress
+ 02h: Flush operation stopped prematurely.
+ 03h: Flush operation completed successfully
+ 04h: Flush operation general failure
+ The file is read only.
+
+What: /sys/bus/platform/drivers/ufshcd/*/attributes/wb_life_time_est
+Date: June 2020
+Contact: Asutosh Das <asutoshd@codeaurora.org>
+Description: This entry shows an indication of the WriteBooster Buffer
+ lifetime based on the amount of performed program/erase cycles
+ 01h: 0% - 10% WriteBooster Buffer life time used
+ ...
+ 0Ah: 90% - 100% WriteBooster Buffer life time used
+ The file is read only.
+
+What: /sys/class/scsi_device/*/device/unit_descriptor/wb_buf_alloc_units
+Date: June 2020
+Contact: Asutosh Das <asutoshd@codeaurora.org>
+Description: This entry shows the configured size of WriteBooster buffer.
+ 0400h corresponds to 4GB.
+ The file is read only.
diff --git a/Documentation/ABI/testing/sysfs-driver-w1_therm b/Documentation/ABI/testing/sysfs-driver-w1_therm
index 076659d..9b488c0 100644
--- a/Documentation/ABI/testing/sysfs-driver-w1_therm
+++ b/Documentation/ABI/testing/sysfs-driver-w1_therm
@@ -8,7 +8,7 @@
to device min/max capabilities. Values are integer as they are
stored in a 8bit register in the device. Lowest value is
automatically put to TL. Once set, alarms could be search at
- master level, refer to Documentation/w1/w1_generic.rst for
+ master level, refer to Documentation/w1/w1-generic.rst for
detailed information
Users: any user space application which wants to communicate with
w1_term device
diff --git a/Documentation/ABI/testing/sysfs-fs-f2fs b/Documentation/ABI/testing/sysfs-fs-f2fs
index 4bb93a0..7f730c4 100644
--- a/Documentation/ABI/testing/sysfs-fs-f2fs
+++ b/Documentation/ABI/testing/sysfs-fs-f2fs
@@ -229,7 +229,9 @@
Contact: "Jaegeuk Kim" <jaegeuk@kernel.org>
Description: Do background GC agressively when set. When gc_urgent = 1,
background thread starts to do GC by given gc_urgent_sleep_time
- interval. It is set to 0 by default.
+ interval. When gc_urgent = 2, F2FS will lower the bar of
+ checking idle in order to process outstanding discard commands
+ and GC a little bit aggressively. It is set to 0 by default.
What: /sys/fs/f2fs/<disk>/gc_urgent_sleep_time
Date: August 2017
diff --git a/Documentation/ABI/testing/sysfs-platform-chipidea-usb-otg b/Documentation/ABI/testing/sysfs-platform-chipidea-usb-otg
index 151c595..f58cfb0 100644
--- a/Documentation/ABI/testing/sysfs-platform-chipidea-usb-otg
+++ b/Documentation/ABI/testing/sysfs-platform-chipidea-usb-otg
@@ -1,6 +1,6 @@
What: /sys/bus/platform/devices/ci_hdrc.0/inputs/a_bus_req
Date: Feb 2014
-Contact: Li Jun <b47624@freescale.com>
+Contact: Li Jun <jun.li@nxp.com>
Description:
Can be set and read.
Set a_bus_req(A-device bus request) input to be 1 if
@@ -17,7 +17,7 @@
What: /sys/bus/platform/devices/ci_hdrc.0/inputs/a_bus_drop
Date: Feb 2014
-Contact: Li Jun <b47624@freescale.com>
+Contact: Li Jun <jun.li@nxp.com>
Description:
Can be set and read
The a_bus_drop(A-device bus drop) input is 1 when the
@@ -32,7 +32,7 @@
What: /sys/bus/platform/devices/ci_hdrc.0/inputs/b_bus_req
Date: Feb 2014
-Contact: Li Jun <b47624@freescale.com>
+Contact: Li Jun <jun.li@nxp.com>
Description:
Can be set and read.
The b_bus_req(B-device bus request) input is 1 during the time
@@ -47,7 +47,7 @@
What: /sys/bus/platform/devices/ci_hdrc.0/inputs/a_clr_err
Date: Feb 2014
-Contact: Li Jun <b47624@freescale.com>
+Contact: Li Jun <jun.li@nxp.com>
Description:
Only can be set.
The a_clr_err(A-device Vbus error clear) input is used to clear
diff --git a/Documentation/PCI/endpoint/function/binding/pci-test.rst b/Documentation/PCI/endpoint/function/binding/pci-test.rst
new file mode 100644
index 0000000..57ee866
--- /dev/null
+++ b/Documentation/PCI/endpoint/function/binding/pci-test.rst
@@ -0,0 +1,26 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+==========================
+PCI Test Endpoint Function
+==========================
+
+name: Should be "pci_epf_test" to bind to the pci_epf_test driver.
+
+Configurable Fields:
+
+================ ===========================================================
+vendorid should be 0x104c
+deviceid should be 0xb500 for DRA74x and 0xb501 for DRA72x
+revid don't care
+progif_code don't care
+subclass_code don't care
+baseclass_code should be 0xff
+cache_line_size don't care
+subsys_vendor_id don't care
+subsys_id don't care
+interrupt_pin Should be 1 - INTA, 2 - INTB, 3 - INTC, 4 -INTD
+msi_interrupts Should be 1 to 32 depending on the number of MSI interrupts
+ to test
+msix_interrupts Should be 1 to 2048 depending on the number of MSI-X
+ interrupts to test
+================ ===========================================================
diff --git a/Documentation/PCI/endpoint/function/binding/pci-test.txt b/Documentation/PCI/endpoint/function/binding/pci-test.txt
deleted file mode 100644
index cd76ba4..0000000
--- a/Documentation/PCI/endpoint/function/binding/pci-test.txt
+++ /dev/null
@@ -1,19 +0,0 @@
-PCI TEST ENDPOINT FUNCTION
-
-name: Should be "pci_epf_test" to bind to the pci_epf_test driver.
-
-Configurable Fields:
-vendorid : should be 0x104c
-deviceid : should be 0xb500 for DRA74x and 0xb501 for DRA72x
-revid : don't care
-progif_code : don't care
-subclass_code : don't care
-baseclass_code : should be 0xff
-cache_line_size : don't care
-subsys_vendor_id : don't care
-subsys_id : don't care
-interrupt_pin : Should be 1 - INTA, 2 - INTB, 3 - INTC, 4 -INTD
-msi_interrupts : Should be 1 to 32 depending on the number of MSI interrupts
- to test
-msix_interrupts : Should be 1 to 2048 depending on the number of MSI-X
- interrupts to test
diff --git a/Documentation/PCI/endpoint/index.rst b/Documentation/PCI/endpoint/index.rst
index d114ea7..4ca7439 100644
--- a/Documentation/PCI/endpoint/index.rst
+++ b/Documentation/PCI/endpoint/index.rst
@@ -11,3 +11,5 @@
pci-endpoint-cfs
pci-test-function
pci-test-howto
+
+ function/binding/pci-test
diff --git a/Documentation/PCI/endpoint/pci-endpoint-cfs.rst b/Documentation/PCI/endpoint/pci-endpoint-cfs.rst
index b6d39cde..1bbd81e 100644
--- a/Documentation/PCI/endpoint/pci-endpoint-cfs.rst
+++ b/Documentation/PCI/endpoint/pci-endpoint-cfs.rst
@@ -24,7 +24,7 @@
The pci_ep configfs has two directories at its root: controllers and
functions. Every EPC device present in the system will have an entry in
-the *controllers* directory and and every EPF driver present in the system
+the *controllers* directory and every EPF driver present in the system
will have an entry in the *functions* directory.
::
diff --git a/Documentation/PCI/endpoint/pci-endpoint.rst b/Documentation/PCI/endpoint/pci-endpoint.rst
index 7536be44..4f5622a 100644
--- a/Documentation/PCI/endpoint/pci-endpoint.rst
+++ b/Documentation/PCI/endpoint/pci-endpoint.rst
@@ -214,7 +214,7 @@
* pci_epf_create()
Create a new PCI EPF device by passing the name of the PCI EPF device.
- This name will be used to bind the the EPF device to a EPF driver.
+ This name will be used to bind the EPF device to a EPF driver.
* pci_epf_destroy()
diff --git a/Documentation/PCI/pci-error-recovery.rst b/Documentation/PCI/pci-error-recovery.rst
index 13beee2..84ceebb 100644
--- a/Documentation/PCI/pci-error-recovery.rst
+++ b/Documentation/PCI/pci-error-recovery.rst
@@ -79,7 +79,7 @@
struct pci_error_handlers
{
- int (*error_detected)(struct pci_dev *dev, enum pci_channel_state);
+ int (*error_detected)(struct pci_dev *dev, pci_channel_state_t);
int (*mmio_enabled)(struct pci_dev *dev);
int (*slot_reset)(struct pci_dev *dev);
void (*resume)(struct pci_dev *dev);
@@ -87,11 +87,11 @@
The possible channel states are::
- enum pci_channel_state {
+ typedef enum {
pci_channel_io_normal, /* I/O channel is in normal state */
pci_channel_io_frozen, /* I/O to channel is blocked */
pci_channel_io_perm_failure, /* PCI card is dead */
- };
+ } pci_channel_state_t;
Possible return values are::
@@ -248,7 +248,7 @@
------------------
In response to a return value of PCI_ERS_RESULT_NEED_RESET, the
-the platform will perform a slot reset on the requesting PCI device(s).
+platform will perform a slot reset on the requesting PCI device(s).
The actual steps taken by a platform to perform a slot reset
will be platform-dependent. Upon completion of slot reset, the
platform will call the device slot_reset() callback.
@@ -348,7 +348,7 @@
-------------------------
A "permanent failure" has occurred, and the platform cannot recover
the device. The platform will call error_detected() with a
-pci_channel_state value of pci_channel_io_perm_failure.
+pci_channel_state_t value of pci_channel_io_perm_failure.
The device driver should, at this point, assume the worst. It should
cancel all pending I/O, refuse all new I/O, returning -EIO to
diff --git a/Documentation/PCI/pci.rst b/Documentation/PCI/pci.rst
index 8c016d8..814b40f 100644
--- a/Documentation/PCI/pci.rst
+++ b/Documentation/PCI/pci.rst
@@ -17,7 +17,7 @@
A more complete resource is the third edition of "Linux Device Drivers"
by Jonathan Corbet, Alessandro Rubini, and Greg Kroah-Hartman.
LDD3 is available for free (under Creative Commons License) from:
-http://lwn.net/Kernel/LDD3/.
+https://lwn.net/Kernel/LDD3/.
However, keep in mind that all documents are subject to "bit rot".
Refer to the source code if things are not working as described here.
@@ -209,12 +209,12 @@
OS BUG: we don't check resource allocations before enabling those
resources. The sequence would make more sense if we called
pci_request_resources() before calling pci_enable_device().
- Currently, the device drivers can't detect the bug when when two
+ Currently, the device drivers can't detect the bug when two
devices have been allocated the same range. This is not a common
problem and unlikely to get fixed soon.
This has been discussed before but not changed as of 2.6.19:
- http://lkml.org/lkml/2006/3/2/194
+ https://lore.kernel.org/r/20060302180025.GC28895@flint.arm.linux.org.uk/
pci_set_master() will enable DMA by setting the bus master bit
@@ -265,7 +265,7 @@
---------------------
.. note::
If anything below doesn't make sense, please refer to
- Documentation/DMA-API.txt. This section is just a reminder that
+ :doc:`/core-api/dma-api`. This section is just a reminder that
drivers need to indicate DMA capabilities of the device and is not
an authoritative source for DMA interfaces.
@@ -291,7 +291,7 @@
Setup shared control data
-------------------------
Once the DMA masks are set, the driver can allocate "consistent" (a.k.a. shared)
-memory. See Documentation/DMA-API.txt for a full description of
+memory. See :doc:`/core-api/dma-api` for a full description of
the DMA APIs. This section is just a reminder that it needs to be done
before enabling DMA on the device.
@@ -421,7 +421,7 @@
Then clean up "consistent" buffers which contain the control data.
-See Documentation/DMA-API.txt for details on unmapping interfaces.
+See :doc:`/core-api/dma-api` for details on unmapping interfaces.
Unregister from other subsystems
@@ -514,9 +514,8 @@
The device IDs are arbitrary hex numbers (vendor controlled) and normally used
only in a single location, the pci_device_id table.
-Please DO submit new vendor/device IDs to http://pci-ids.ucw.cz/.
-There are mirrors of the pci.ids file at http://pciids.sourceforge.net/
-and https://github.com/pciutils/pciids.
+Please DO submit new vendor/device IDs to https://pci-ids.ucw.cz/.
+There's a mirror of the pci.ids file at https://github.com/pciutils/pciids.
Obsolete functions
diff --git a/Documentation/RCU/Design/Requirements/Requirements.rst b/Documentation/RCU/Design/Requirements/Requirements.rst
index 75b8ca0..8f41ad0 100644
--- a/Documentation/RCU/Design/Requirements/Requirements.rst
+++ b/Documentation/RCU/Design/Requirements/Requirements.rst
@@ -463,7 +463,7 @@
This guarantee was only partially premeditated. DYNIX/ptx used an
explicit memory barrier for publication, but had nothing resembling
``rcu_dereference()`` for subscription, nor did it have anything
-resembling the ``smp_read_barrier_depends()`` that was later subsumed
+resembling the dependency-ordering barrier that was later subsumed
into ``rcu_dereference()`` and later still into ``READ_ONCE()``. The
need for these operations made itself known quite suddenly at a
late-1990s meeting with the DEC Alpha architects, back in the days when
@@ -2583,7 +2583,12 @@
would need to be instructions following ``rcu_read_unlock()``. Although
``synchronize_rcu()`` would guarantee that execution reached the
``rcu_read_unlock()``, it would not be able to guarantee that execution
-had completely left the trampoline.
+had completely left the trampoline. Worse yet, in some situations
+the trampoline's protection must extend a few instructions *prior* to
+execution reaching the trampoline. For example, these few instructions
+might calculate the address of the trampoline, so that entering the
+trampoline would be pre-ordained a surprisingly long time before execution
+actually reached the trampoline itself.
The solution, in the form of `Tasks
RCU <https://lwn.net/Articles/607117/>`__, is to have implicit read-side
diff --git a/Documentation/RCU/checklist.rst b/Documentation/RCU/checklist.rst
new file mode 100644
index 0000000..2efed99
--- /dev/null
+++ b/Documentation/RCU/checklist.rst
@@ -0,0 +1,465 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+================================
+Review Checklist for RCU Patches
+================================
+
+
+This document contains a checklist for producing and reviewing patches
+that make use of RCU. Violating any of the rules listed below will
+result in the same sorts of problems that leaving out a locking primitive
+would cause. This list is based on experiences reviewing such patches
+over a rather long period of time, but improvements are always welcome!
+
+0. Is RCU being applied to a read-mostly situation? If the data
+ structure is updated more than about 10% of the time, then you
+ should strongly consider some other approach, unless detailed
+ performance measurements show that RCU is nonetheless the right
+ tool for the job. Yes, RCU does reduce read-side overhead by
+ increasing write-side overhead, which is exactly why normal uses
+ of RCU will do much more reading than updating.
+
+ Another exception is where performance is not an issue, and RCU
+ provides a simpler implementation. An example of this situation
+ is the dynamic NMI code in the Linux 2.6 kernel, at least on
+ architectures where NMIs are rare.
+
+ Yet another exception is where the low real-time latency of RCU's
+ read-side primitives is critically important.
+
+ One final exception is where RCU readers are used to prevent
+ the ABA problem (https://en.wikipedia.org/wiki/ABA_problem)
+ for lockless updates. This does result in the mildly
+ counter-intuitive situation where rcu_read_lock() and
+ rcu_read_unlock() are used to protect updates, however, this
+ approach provides the same potential simplifications that garbage
+ collectors do.
+
+1. Does the update code have proper mutual exclusion?
+
+ RCU does allow -readers- to run (almost) naked, but -writers- must
+ still use some sort of mutual exclusion, such as:
+
+ a. locking,
+ b. atomic operations, or
+ c. restricting updates to a single task.
+
+ If you choose #b, be prepared to describe how you have handled
+ memory barriers on weakly ordered machines (pretty much all of
+ them -- even x86 allows later loads to be reordered to precede
+ earlier stores), and be prepared to explain why this added
+ complexity is worthwhile. If you choose #c, be prepared to
+ explain how this single task does not become a major bottleneck on
+ big multiprocessor machines (for example, if the task is updating
+ information relating to itself that other tasks can read, there
+ by definition can be no bottleneck). Note that the definition
+ of "large" has changed significantly: Eight CPUs was "large"
+ in the year 2000, but a hundred CPUs was unremarkable in 2017.
+
+2. Do the RCU read-side critical sections make proper use of
+ rcu_read_lock() and friends? These primitives are needed
+ to prevent grace periods from ending prematurely, which
+ could result in data being unceremoniously freed out from
+ under your read-side code, which can greatly increase the
+ actuarial risk of your kernel.
+
+ As a rough rule of thumb, any dereference of an RCU-protected
+ pointer must be covered by rcu_read_lock(), rcu_read_lock_bh(),
+ rcu_read_lock_sched(), or by the appropriate update-side lock.
+ Disabling of preemption can serve as rcu_read_lock_sched(), but
+ is less readable and prevents lockdep from detecting locking issues.
+
+ Letting RCU-protected pointers "leak" out of an RCU read-side
+ critical section is every bid as bad as letting them leak out
+ from under a lock. Unless, of course, you have arranged some
+ other means of protection, such as a lock or a reference count
+ -before- letting them out of the RCU read-side critical section.
+
+3. Does the update code tolerate concurrent accesses?
+
+ The whole point of RCU is to permit readers to run without
+ any locks or atomic operations. This means that readers will
+ be running while updates are in progress. There are a number
+ of ways to handle this concurrency, depending on the situation:
+
+ a. Use the RCU variants of the list and hlist update
+ primitives to add, remove, and replace elements on
+ an RCU-protected list. Alternatively, use the other
+ RCU-protected data structures that have been added to
+ the Linux kernel.
+
+ This is almost always the best approach.
+
+ b. Proceed as in (a) above, but also maintain per-element
+ locks (that are acquired by both readers and writers)
+ that guard per-element state. Of course, fields that
+ the readers refrain from accessing can be guarded by
+ some other lock acquired only by updaters, if desired.
+
+ This works quite well, also.
+
+ c. Make updates appear atomic to readers. For example,
+ pointer updates to properly aligned fields will
+ appear atomic, as will individual atomic primitives.
+ Sequences of operations performed under a lock will -not-
+ appear to be atomic to RCU readers, nor will sequences
+ of multiple atomic primitives.
+
+ This can work, but is starting to get a bit tricky.
+
+ d. Carefully order the updates and the reads so that
+ readers see valid data at all phases of the update.
+ This is often more difficult than it sounds, especially
+ given modern CPUs' tendency to reorder memory references.
+ One must usually liberally sprinkle memory barriers
+ (smp_wmb(), smp_rmb(), smp_mb()) through the code,
+ making it difficult to understand and to test.
+
+ It is usually better to group the changing data into
+ a separate structure, so that the change may be made
+ to appear atomic by updating a pointer to reference
+ a new structure containing updated values.
+
+4. Weakly ordered CPUs pose special challenges. Almost all CPUs
+ are weakly ordered -- even x86 CPUs allow later loads to be
+ reordered to precede earlier stores. RCU code must take all of
+ the following measures to prevent memory-corruption problems:
+
+ a. Readers must maintain proper ordering of their memory
+ accesses. The rcu_dereference() primitive ensures that
+ the CPU picks up the pointer before it picks up the data
+ that the pointer points to. This really is necessary
+ on Alpha CPUs. If you don't believe me, see:
+
+ http://www.openvms.compaq.com/wizard/wiz_2637.html
+
+ The rcu_dereference() primitive is also an excellent
+ documentation aid, letting the person reading the
+ code know exactly which pointers are protected by RCU.
+ Please note that compilers can also reorder code, and
+ they are becoming increasingly aggressive about doing
+ just that. The rcu_dereference() primitive therefore also
+ prevents destructive compiler optimizations. However,
+ with a bit of devious creativity, it is possible to
+ mishandle the return value from rcu_dereference().
+ Please see rcu_dereference.txt in this directory for
+ more information.
+
+ The rcu_dereference() primitive is used by the
+ various "_rcu()" list-traversal primitives, such
+ as the list_for_each_entry_rcu(). Note that it is
+ perfectly legal (if redundant) for update-side code to
+ use rcu_dereference() and the "_rcu()" list-traversal
+ primitives. This is particularly useful in code that
+ is common to readers and updaters. However, lockdep
+ will complain if you access rcu_dereference() outside
+ of an RCU read-side critical section. See lockdep.txt
+ to learn what to do about this.
+
+ Of course, neither rcu_dereference() nor the "_rcu()"
+ list-traversal primitives can substitute for a good
+ concurrency design coordinating among multiple updaters.
+
+ b. If the list macros are being used, the list_add_tail_rcu()
+ and list_add_rcu() primitives must be used in order
+ to prevent weakly ordered machines from misordering
+ structure initialization and pointer planting.
+ Similarly, if the hlist macros are being used, the
+ hlist_add_head_rcu() primitive is required.
+
+ c. If the list macros are being used, the list_del_rcu()
+ primitive must be used to keep list_del()'s pointer
+ poisoning from inflicting toxic effects on concurrent
+ readers. Similarly, if the hlist macros are being used,
+ the hlist_del_rcu() primitive is required.
+
+ The list_replace_rcu() and hlist_replace_rcu() primitives
+ may be used to replace an old structure with a new one
+ in their respective types of RCU-protected lists.
+
+ d. Rules similar to (4b) and (4c) apply to the "hlist_nulls"
+ type of RCU-protected linked lists.
+
+ e. Updates must ensure that initialization of a given
+ structure happens before pointers to that structure are
+ publicized. Use the rcu_assign_pointer() primitive
+ when publicizing a pointer to a structure that can
+ be traversed by an RCU read-side critical section.
+
+5. If call_rcu() or call_srcu() is used, the callback function will
+ be called from softirq context. In particular, it cannot block.
+
+6. Since synchronize_rcu() can block, it cannot be called
+ from any sort of irq context. The same rule applies
+ for synchronize_srcu(), synchronize_rcu_expedited(), and
+ synchronize_srcu_expedited().
+
+ The expedited forms of these primitives have the same semantics
+ as the non-expedited forms, but expediting is both expensive and
+ (with the exception of synchronize_srcu_expedited()) unfriendly
+ to real-time workloads. Use of the expedited primitives should
+ be restricted to rare configuration-change operations that would
+ not normally be undertaken while a real-time workload is running.
+ However, real-time workloads can use rcupdate.rcu_normal kernel
+ boot parameter to completely disable expedited grace periods,
+ though this might have performance implications.
+
+ In particular, if you find yourself invoking one of the expedited
+ primitives repeatedly in a loop, please do everyone a favor:
+ Restructure your code so that it batches the updates, allowing
+ a single non-expedited primitive to cover the entire batch.
+ This will very likely be faster than the loop containing the
+ expedited primitive, and will be much much easier on the rest
+ of the system, especially to real-time workloads running on
+ the rest of the system.
+
+7. As of v4.20, a given kernel implements only one RCU flavor,
+ which is RCU-sched for PREEMPT=n and RCU-preempt for PREEMPT=y.
+ If the updater uses call_rcu() or synchronize_rcu(),
+ then the corresponding readers my use rcu_read_lock() and
+ rcu_read_unlock(), rcu_read_lock_bh() and rcu_read_unlock_bh(),
+ or any pair of primitives that disables and re-enables preemption,
+ for example, rcu_read_lock_sched() and rcu_read_unlock_sched().
+ If the updater uses synchronize_srcu() or call_srcu(),
+ then the corresponding readers must use srcu_read_lock() and
+ srcu_read_unlock(), and with the same srcu_struct. The rules for
+ the expedited primitives are the same as for their non-expedited
+ counterparts. Mixing things up will result in confusion and
+ broken kernels, and has even resulted in an exploitable security
+ issue.
+
+ One exception to this rule: rcu_read_lock() and rcu_read_unlock()
+ may be substituted for rcu_read_lock_bh() and rcu_read_unlock_bh()
+ in cases where local bottom halves are already known to be
+ disabled, for example, in irq or softirq context. Commenting
+ such cases is a must, of course! And the jury is still out on
+ whether the increased speed is worth it.
+
+8. Although synchronize_rcu() is slower than is call_rcu(), it
+ usually results in simpler code. So, unless update performance is
+ critically important, the updaters cannot block, or the latency of
+ synchronize_rcu() is visible from userspace, synchronize_rcu()
+ should be used in preference to call_rcu(). Furthermore,
+ kfree_rcu() usually results in even simpler code than does
+ synchronize_rcu() without synchronize_rcu()'s multi-millisecond
+ latency. So please take advantage of kfree_rcu()'s "fire and
+ forget" memory-freeing capabilities where it applies.
+
+ An especially important property of the synchronize_rcu()
+ primitive is that it automatically self-limits: if grace periods
+ are delayed for whatever reason, then the synchronize_rcu()
+ primitive will correspondingly delay updates. In contrast,
+ code using call_rcu() should explicitly limit update rate in
+ cases where grace periods are delayed, as failing to do so can
+ result in excessive realtime latencies or even OOM conditions.
+
+ Ways of gaining this self-limiting property when using call_rcu()
+ include:
+
+ a. Keeping a count of the number of data-structure elements
+ used by the RCU-protected data structure, including
+ those waiting for a grace period to elapse. Enforce a
+ limit on this number, stalling updates as needed to allow
+ previously deferred frees to complete. Alternatively,
+ limit only the number awaiting deferred free rather than
+ the total number of elements.
+
+ One way to stall the updates is to acquire the update-side
+ mutex. (Don't try this with a spinlock -- other CPUs
+ spinning on the lock could prevent the grace period
+ from ever ending.) Another way to stall the updates
+ is for the updates to use a wrapper function around
+ the memory allocator, so that this wrapper function
+ simulates OOM when there is too much memory awaiting an
+ RCU grace period. There are of course many other
+ variations on this theme.
+
+ b. Limiting update rate. For example, if updates occur only
+ once per hour, then no explicit rate limiting is
+ required, unless your system is already badly broken.
+ Older versions of the dcache subsystem take this approach,
+ guarding updates with a global lock, limiting their rate.
+
+ c. Trusted update -- if updates can only be done manually by
+ superuser or some other trusted user, then it might not
+ be necessary to automatically limit them. The theory
+ here is that superuser already has lots of ways to crash
+ the machine.
+
+ d. Periodically invoke synchronize_rcu(), permitting a limited
+ number of updates per grace period.
+
+ The same cautions apply to call_srcu() and kfree_rcu().
+
+ Note that although these primitives do take action to avoid memory
+ exhaustion when any given CPU has too many callbacks, a determined
+ user could still exhaust memory. This is especially the case
+ if a system with a large number of CPUs has been configured to
+ offload all of its RCU callbacks onto a single CPU, or if the
+ system has relatively little free memory.
+
+9. All RCU list-traversal primitives, which include
+ rcu_dereference(), list_for_each_entry_rcu(), and
+ list_for_each_safe_rcu(), must be either within an RCU read-side
+ critical section or must be protected by appropriate update-side
+ locks. RCU read-side critical sections are delimited by
+ rcu_read_lock() and rcu_read_unlock(), or by similar primitives
+ such as rcu_read_lock_bh() and rcu_read_unlock_bh(), in which
+ case the matching rcu_dereference() primitive must be used in
+ order to keep lockdep happy, in this case, rcu_dereference_bh().
+
+ The reason that it is permissible to use RCU list-traversal
+ primitives when the update-side lock is held is that doing so
+ can be quite helpful in reducing code bloat when common code is
+ shared between readers and updaters. Additional primitives
+ are provided for this case, as discussed in lockdep.txt.
+
+10. Conversely, if you are in an RCU read-side critical section,
+ and you don't hold the appropriate update-side lock, you -must-
+ use the "_rcu()" variants of the list macros. Failing to do so
+ will break Alpha, cause aggressive compilers to generate bad code,
+ and confuse people trying to read your code.
+
+11. Any lock acquired by an RCU callback must be acquired elsewhere
+ with softirq disabled, e.g., via spin_lock_irqsave(),
+ spin_lock_bh(), etc. Failing to disable softirq on a given
+ acquisition of that lock will result in deadlock as soon as
+ the RCU softirq handler happens to run your RCU callback while
+ interrupting that acquisition's critical section.
+
+12. RCU callbacks can be and are executed in parallel. In many cases,
+ the callback code simply wrappers around kfree(), so that this
+ is not an issue (or, more accurately, to the extent that it is
+ an issue, the memory-allocator locking handles it). However,
+ if the callbacks do manipulate a shared data structure, they
+ must use whatever locking or other synchronization is required
+ to safely access and/or modify that data structure.
+
+ Do not assume that RCU callbacks will be executed on the same
+ CPU that executed the corresponding call_rcu() or call_srcu().
+ For example, if a given CPU goes offline while having an RCU
+ callback pending, then that RCU callback will execute on some
+ surviving CPU. (If this was not the case, a self-spawning RCU
+ callback would prevent the victim CPU from ever going offline.)
+ Furthermore, CPUs designated by rcu_nocbs= might well -always-
+ have their RCU callbacks executed on some other CPUs, in fact,
+ for some real-time workloads, this is the whole point of using
+ the rcu_nocbs= kernel boot parameter.
+
+13. Unlike other forms of RCU, it -is- permissible to block in an
+ SRCU read-side critical section (demarked by srcu_read_lock()
+ and srcu_read_unlock()), hence the "SRCU": "sleepable RCU".
+ Please note that if you don't need to sleep in read-side critical
+ sections, you should be using RCU rather than SRCU, because RCU
+ is almost always faster and easier to use than is SRCU.
+
+ Also unlike other forms of RCU, explicit initialization and
+ cleanup is required either at build time via DEFINE_SRCU()
+ or DEFINE_STATIC_SRCU() or at runtime via init_srcu_struct()
+ and cleanup_srcu_struct(). These last two are passed a
+ "struct srcu_struct" that defines the scope of a given
+ SRCU domain. Once initialized, the srcu_struct is passed
+ to srcu_read_lock(), srcu_read_unlock() synchronize_srcu(),
+ synchronize_srcu_expedited(), and call_srcu(). A given
+ synchronize_srcu() waits only for SRCU read-side critical
+ sections governed by srcu_read_lock() and srcu_read_unlock()
+ calls that have been passed the same srcu_struct. This property
+ is what makes sleeping read-side critical sections tolerable --
+ a given subsystem delays only its own updates, not those of other
+ subsystems using SRCU. Therefore, SRCU is less prone to OOM the
+ system than RCU would be if RCU's read-side critical sections
+ were permitted to sleep.
+
+ The ability to sleep in read-side critical sections does not
+ come for free. First, corresponding srcu_read_lock() and
+ srcu_read_unlock() calls must be passed the same srcu_struct.
+ Second, grace-period-detection overhead is amortized only
+ over those updates sharing a given srcu_struct, rather than
+ being globally amortized as they are for other forms of RCU.
+ Therefore, SRCU should be used in preference to rw_semaphore
+ only in extremely read-intensive situations, or in situations
+ requiring SRCU's read-side deadlock immunity or low read-side
+ realtime latency. You should also consider percpu_rw_semaphore
+ when you need lightweight readers.
+
+ SRCU's expedited primitive (synchronize_srcu_expedited())
+ never sends IPIs to other CPUs, so it is easier on
+ real-time workloads than is synchronize_rcu_expedited().
+
+ Note that rcu_assign_pointer() relates to SRCU just as it does to
+ other forms of RCU, but instead of rcu_dereference() you should
+ use srcu_dereference() in order to avoid lockdep splats.
+
+14. The whole point of call_rcu(), synchronize_rcu(), and friends
+ is to wait until all pre-existing readers have finished before
+ carrying out some otherwise-destructive operation. It is
+ therefore critically important to -first- remove any path
+ that readers can follow that could be affected by the
+ destructive operation, and -only- -then- invoke call_rcu(),
+ synchronize_rcu(), or friends.
+
+ Because these primitives only wait for pre-existing readers, it
+ is the caller's responsibility to guarantee that any subsequent
+ readers will execute safely.
+
+15. The various RCU read-side primitives do -not- necessarily contain
+ memory barriers. You should therefore plan for the CPU
+ and the compiler to freely reorder code into and out of RCU
+ read-side critical sections. It is the responsibility of the
+ RCU update-side primitives to deal with this.
+
+ For SRCU readers, you can use smp_mb__after_srcu_read_unlock()
+ immediately after an srcu_read_unlock() to get a full barrier.
+
+16. Use CONFIG_PROVE_LOCKING, CONFIG_DEBUG_OBJECTS_RCU_HEAD, and the
+ __rcu sparse checks to validate your RCU code. These can help
+ find problems as follows:
+
+ CONFIG_PROVE_LOCKING:
+ check that accesses to RCU-protected data
+ structures are carried out under the proper RCU
+ read-side critical section, while holding the right
+ combination of locks, or whatever other conditions
+ are appropriate.
+
+ CONFIG_DEBUG_OBJECTS_RCU_HEAD:
+ check that you don't pass the
+ same object to call_rcu() (or friends) before an RCU
+ grace period has elapsed since the last time that you
+ passed that same object to call_rcu() (or friends).
+
+ __rcu sparse checks:
+ tag the pointer to the RCU-protected data
+ structure with __rcu, and sparse will warn you if you
+ access that pointer without the services of one of the
+ variants of rcu_dereference().
+
+ These debugging aids can help you find problems that are
+ otherwise extremely difficult to spot.
+
+17. If you register a callback using call_rcu() or call_srcu(), and
+ pass in a function defined within a loadable module, then it in
+ necessary to wait for all pending callbacks to be invoked after
+ the last invocation and before unloading that module. Note that
+ it is absolutely -not- sufficient to wait for a grace period!
+ The current (say) synchronize_rcu() implementation is -not-
+ guaranteed to wait for callbacks registered on other CPUs.
+ Or even on the current CPU if that CPU recently went offline
+ and came back online.
+
+ You instead need to use one of the barrier functions:
+
+ - call_rcu() -> rcu_barrier()
+ - call_srcu() -> srcu_barrier()
+
+ However, these barrier functions are absolutely -not- guaranteed
+ to wait for a grace period. In fact, if there are no call_rcu()
+ callbacks waiting anywhere in the system, rcu_barrier() is within
+ its rights to return immediately.
+
+ So if you need to wait for both an RCU grace period and for
+ all pre-existing call_rcu() callbacks, you will need to execute
+ both rcu_barrier() and synchronize_rcu(), if necessary, using
+ something like workqueues to to execute them concurrently.
+
+ See rcubarrier.txt for more information.
diff --git a/Documentation/RCU/checklist.txt b/Documentation/RCU/checklist.txt
deleted file mode 100644
index e98ff26..0000000
--- a/Documentation/RCU/checklist.txt
+++ /dev/null
@@ -1,458 +0,0 @@
-Review Checklist for RCU Patches
-
-
-This document contains a checklist for producing and reviewing patches
-that make use of RCU. Violating any of the rules listed below will
-result in the same sorts of problems that leaving out a locking primitive
-would cause. This list is based on experiences reviewing such patches
-over a rather long period of time, but improvements are always welcome!
-
-0. Is RCU being applied to a read-mostly situation? If the data
- structure is updated more than about 10% of the time, then you
- should strongly consider some other approach, unless detailed
- performance measurements show that RCU is nonetheless the right
- tool for the job. Yes, RCU does reduce read-side overhead by
- increasing write-side overhead, which is exactly why normal uses
- of RCU will do much more reading than updating.
-
- Another exception is where performance is not an issue, and RCU
- provides a simpler implementation. An example of this situation
- is the dynamic NMI code in the Linux 2.6 kernel, at least on
- architectures where NMIs are rare.
-
- Yet another exception is where the low real-time latency of RCU's
- read-side primitives is critically important.
-
- One final exception is where RCU readers are used to prevent
- the ABA problem (https://en.wikipedia.org/wiki/ABA_problem)
- for lockless updates. This does result in the mildly
- counter-intuitive situation where rcu_read_lock() and
- rcu_read_unlock() are used to protect updates, however, this
- approach provides the same potential simplifications that garbage
- collectors do.
-
-1. Does the update code have proper mutual exclusion?
-
- RCU does allow -readers- to run (almost) naked, but -writers- must
- still use some sort of mutual exclusion, such as:
-
- a. locking,
- b. atomic operations, or
- c. restricting updates to a single task.
-
- If you choose #b, be prepared to describe how you have handled
- memory barriers on weakly ordered machines (pretty much all of
- them -- even x86 allows later loads to be reordered to precede
- earlier stores), and be prepared to explain why this added
- complexity is worthwhile. If you choose #c, be prepared to
- explain how this single task does not become a major bottleneck on
- big multiprocessor machines (for example, if the task is updating
- information relating to itself that other tasks can read, there
- by definition can be no bottleneck). Note that the definition
- of "large" has changed significantly: Eight CPUs was "large"
- in the year 2000, but a hundred CPUs was unremarkable in 2017.
-
-2. Do the RCU read-side critical sections make proper use of
- rcu_read_lock() and friends? These primitives are needed
- to prevent grace periods from ending prematurely, which
- could result in data being unceremoniously freed out from
- under your read-side code, which can greatly increase the
- actuarial risk of your kernel.
-
- As a rough rule of thumb, any dereference of an RCU-protected
- pointer must be covered by rcu_read_lock(), rcu_read_lock_bh(),
- rcu_read_lock_sched(), or by the appropriate update-side lock.
- Disabling of preemption can serve as rcu_read_lock_sched(), but
- is less readable and prevents lockdep from detecting locking issues.
-
- Letting RCU-protected pointers "leak" out of an RCU read-side
- critical section is every bid as bad as letting them leak out
- from under a lock. Unless, of course, you have arranged some
- other means of protection, such as a lock or a reference count
- -before- letting them out of the RCU read-side critical section.
-
-3. Does the update code tolerate concurrent accesses?
-
- The whole point of RCU is to permit readers to run without
- any locks or atomic operations. This means that readers will
- be running while updates are in progress. There are a number
- of ways to handle this concurrency, depending on the situation:
-
- a. Use the RCU variants of the list and hlist update
- primitives to add, remove, and replace elements on
- an RCU-protected list. Alternatively, use the other
- RCU-protected data structures that have been added to
- the Linux kernel.
-
- This is almost always the best approach.
-
- b. Proceed as in (a) above, but also maintain per-element
- locks (that are acquired by both readers and writers)
- that guard per-element state. Of course, fields that
- the readers refrain from accessing can be guarded by
- some other lock acquired only by updaters, if desired.
-
- This works quite well, also.
-
- c. Make updates appear atomic to readers. For example,
- pointer updates to properly aligned fields will
- appear atomic, as will individual atomic primitives.
- Sequences of operations performed under a lock will -not-
- appear to be atomic to RCU readers, nor will sequences
- of multiple atomic primitives.
-
- This can work, but is starting to get a bit tricky.
-
- d. Carefully order the updates and the reads so that
- readers see valid data at all phases of the update.
- This is often more difficult than it sounds, especially
- given modern CPUs' tendency to reorder memory references.
- One must usually liberally sprinkle memory barriers
- (smp_wmb(), smp_rmb(), smp_mb()) through the code,
- making it difficult to understand and to test.
-
- It is usually better to group the changing data into
- a separate structure, so that the change may be made
- to appear atomic by updating a pointer to reference
- a new structure containing updated values.
-
-4. Weakly ordered CPUs pose special challenges. Almost all CPUs
- are weakly ordered -- even x86 CPUs allow later loads to be
- reordered to precede earlier stores. RCU code must take all of
- the following measures to prevent memory-corruption problems:
-
- a. Readers must maintain proper ordering of their memory
- accesses. The rcu_dereference() primitive ensures that
- the CPU picks up the pointer before it picks up the data
- that the pointer points to. This really is necessary
- on Alpha CPUs. If you don't believe me, see:
-
- http://www.openvms.compaq.com/wizard/wiz_2637.html
-
- The rcu_dereference() primitive is also an excellent
- documentation aid, letting the person reading the
- code know exactly which pointers are protected by RCU.
- Please note that compilers can also reorder code, and
- they are becoming increasingly aggressive about doing
- just that. The rcu_dereference() primitive therefore also
- prevents destructive compiler optimizations. However,
- with a bit of devious creativity, it is possible to
- mishandle the return value from rcu_dereference().
- Please see rcu_dereference.txt in this directory for
- more information.
-
- The rcu_dereference() primitive is used by the
- various "_rcu()" list-traversal primitives, such
- as the list_for_each_entry_rcu(). Note that it is
- perfectly legal (if redundant) for update-side code to
- use rcu_dereference() and the "_rcu()" list-traversal
- primitives. This is particularly useful in code that
- is common to readers and updaters. However, lockdep
- will complain if you access rcu_dereference() outside
- of an RCU read-side critical section. See lockdep.txt
- to learn what to do about this.
-
- Of course, neither rcu_dereference() nor the "_rcu()"
- list-traversal primitives can substitute for a good
- concurrency design coordinating among multiple updaters.
-
- b. If the list macros are being used, the list_add_tail_rcu()
- and list_add_rcu() primitives must be used in order
- to prevent weakly ordered machines from misordering
- structure initialization and pointer planting.
- Similarly, if the hlist macros are being used, the
- hlist_add_head_rcu() primitive is required.
-
- c. If the list macros are being used, the list_del_rcu()
- primitive must be used to keep list_del()'s pointer
- poisoning from inflicting toxic effects on concurrent
- readers. Similarly, if the hlist macros are being used,
- the hlist_del_rcu() primitive is required.
-
- The list_replace_rcu() and hlist_replace_rcu() primitives
- may be used to replace an old structure with a new one
- in their respective types of RCU-protected lists.
-
- d. Rules similar to (4b) and (4c) apply to the "hlist_nulls"
- type of RCU-protected linked lists.
-
- e. Updates must ensure that initialization of a given
- structure happens before pointers to that structure are
- publicized. Use the rcu_assign_pointer() primitive
- when publicizing a pointer to a structure that can
- be traversed by an RCU read-side critical section.
-
-5. If call_rcu() or call_srcu() is used, the callback function will
- be called from softirq context. In particular, it cannot block.
-
-6. Since synchronize_rcu() can block, it cannot be called
- from any sort of irq context. The same rule applies
- for synchronize_srcu(), synchronize_rcu_expedited(), and
- synchronize_srcu_expedited().
-
- The expedited forms of these primitives have the same semantics
- as the non-expedited forms, but expediting is both expensive and
- (with the exception of synchronize_srcu_expedited()) unfriendly
- to real-time workloads. Use of the expedited primitives should
- be restricted to rare configuration-change operations that would
- not normally be undertaken while a real-time workload is running.
- However, real-time workloads can use rcupdate.rcu_normal kernel
- boot parameter to completely disable expedited grace periods,
- though this might have performance implications.
-
- In particular, if you find yourself invoking one of the expedited
- primitives repeatedly in a loop, please do everyone a favor:
- Restructure your code so that it batches the updates, allowing
- a single non-expedited primitive to cover the entire batch.
- This will very likely be faster than the loop containing the
- expedited primitive, and will be much much easier on the rest
- of the system, especially to real-time workloads running on
- the rest of the system.
-
-7. As of v4.20, a given kernel implements only one RCU flavor,
- which is RCU-sched for PREEMPT=n and RCU-preempt for PREEMPT=y.
- If the updater uses call_rcu() or synchronize_rcu(),
- then the corresponding readers my use rcu_read_lock() and
- rcu_read_unlock(), rcu_read_lock_bh() and rcu_read_unlock_bh(),
- or any pair of primitives that disables and re-enables preemption,
- for example, rcu_read_lock_sched() and rcu_read_unlock_sched().
- If the updater uses synchronize_srcu() or call_srcu(),
- then the corresponding readers must use srcu_read_lock() and
- srcu_read_unlock(), and with the same srcu_struct. The rules for
- the expedited primitives are the same as for their non-expedited
- counterparts. Mixing things up will result in confusion and
- broken kernels, and has even resulted in an exploitable security
- issue.
-
- One exception to this rule: rcu_read_lock() and rcu_read_unlock()
- may be substituted for rcu_read_lock_bh() and rcu_read_unlock_bh()
- in cases where local bottom halves are already known to be
- disabled, for example, in irq or softirq context. Commenting
- such cases is a must, of course! And the jury is still out on
- whether the increased speed is worth it.
-
-8. Although synchronize_rcu() is slower than is call_rcu(), it
- usually results in simpler code. So, unless update performance is
- critically important, the updaters cannot block, or the latency of
- synchronize_rcu() is visible from userspace, synchronize_rcu()
- should be used in preference to call_rcu(). Furthermore,
- kfree_rcu() usually results in even simpler code than does
- synchronize_rcu() without synchronize_rcu()'s multi-millisecond
- latency. So please take advantage of kfree_rcu()'s "fire and
- forget" memory-freeing capabilities where it applies.
-
- An especially important property of the synchronize_rcu()
- primitive is that it automatically self-limits: if grace periods
- are delayed for whatever reason, then the synchronize_rcu()
- primitive will correspondingly delay updates. In contrast,
- code using call_rcu() should explicitly limit update rate in
- cases where grace periods are delayed, as failing to do so can
- result in excessive realtime latencies or even OOM conditions.
-
- Ways of gaining this self-limiting property when using call_rcu()
- include:
-
- a. Keeping a count of the number of data-structure elements
- used by the RCU-protected data structure, including
- those waiting for a grace period to elapse. Enforce a
- limit on this number, stalling updates as needed to allow
- previously deferred frees to complete. Alternatively,
- limit only the number awaiting deferred free rather than
- the total number of elements.
-
- One way to stall the updates is to acquire the update-side
- mutex. (Don't try this with a spinlock -- other CPUs
- spinning on the lock could prevent the grace period
- from ever ending.) Another way to stall the updates
- is for the updates to use a wrapper function around
- the memory allocator, so that this wrapper function
- simulates OOM when there is too much memory awaiting an
- RCU grace period. There are of course many other
- variations on this theme.
-
- b. Limiting update rate. For example, if updates occur only
- once per hour, then no explicit rate limiting is
- required, unless your system is already badly broken.
- Older versions of the dcache subsystem take this approach,
- guarding updates with a global lock, limiting their rate.
-
- c. Trusted update -- if updates can only be done manually by
- superuser or some other trusted user, then it might not
- be necessary to automatically limit them. The theory
- here is that superuser already has lots of ways to crash
- the machine.
-
- d. Periodically invoke synchronize_rcu(), permitting a limited
- number of updates per grace period.
-
- The same cautions apply to call_srcu() and kfree_rcu().
-
- Note that although these primitives do take action to avoid memory
- exhaustion when any given CPU has too many callbacks, a determined
- user could still exhaust memory. This is especially the case
- if a system with a large number of CPUs has been configured to
- offload all of its RCU callbacks onto a single CPU, or if the
- system has relatively little free memory.
-
-9. All RCU list-traversal primitives, which include
- rcu_dereference(), list_for_each_entry_rcu(), and
- list_for_each_safe_rcu(), must be either within an RCU read-side
- critical section or must be protected by appropriate update-side
- locks. RCU read-side critical sections are delimited by
- rcu_read_lock() and rcu_read_unlock(), or by similar primitives
- such as rcu_read_lock_bh() and rcu_read_unlock_bh(), in which
- case the matching rcu_dereference() primitive must be used in
- order to keep lockdep happy, in this case, rcu_dereference_bh().
-
- The reason that it is permissible to use RCU list-traversal
- primitives when the update-side lock is held is that doing so
- can be quite helpful in reducing code bloat when common code is
- shared between readers and updaters. Additional primitives
- are provided for this case, as discussed in lockdep.txt.
-
-10. Conversely, if you are in an RCU read-side critical section,
- and you don't hold the appropriate update-side lock, you -must-
- use the "_rcu()" variants of the list macros. Failing to do so
- will break Alpha, cause aggressive compilers to generate bad code,
- and confuse people trying to read your code.
-
-11. Any lock acquired by an RCU callback must be acquired elsewhere
- with softirq disabled, e.g., via spin_lock_irqsave(),
- spin_lock_bh(), etc. Failing to disable softirq on a given
- acquisition of that lock will result in deadlock as soon as
- the RCU softirq handler happens to run your RCU callback while
- interrupting that acquisition's critical section.
-
-12. RCU callbacks can be and are executed in parallel. In many cases,
- the callback code simply wrappers around kfree(), so that this
- is not an issue (or, more accurately, to the extent that it is
- an issue, the memory-allocator locking handles it). However,
- if the callbacks do manipulate a shared data structure, they
- must use whatever locking or other synchronization is required
- to safely access and/or modify that data structure.
-
- Do not assume that RCU callbacks will be executed on the same
- CPU that executed the corresponding call_rcu() or call_srcu().
- For example, if a given CPU goes offline while having an RCU
- callback pending, then that RCU callback will execute on some
- surviving CPU. (If this was not the case, a self-spawning RCU
- callback would prevent the victim CPU from ever going offline.)
- Furthermore, CPUs designated by rcu_nocbs= might well -always-
- have their RCU callbacks executed on some other CPUs, in fact,
- for some real-time workloads, this is the whole point of using
- the rcu_nocbs= kernel boot parameter.
-
-13. Unlike other forms of RCU, it -is- permissible to block in an
- SRCU read-side critical section (demarked by srcu_read_lock()
- and srcu_read_unlock()), hence the "SRCU": "sleepable RCU".
- Please note that if you don't need to sleep in read-side critical
- sections, you should be using RCU rather than SRCU, because RCU
- is almost always faster and easier to use than is SRCU.
-
- Also unlike other forms of RCU, explicit initialization and
- cleanup is required either at build time via DEFINE_SRCU()
- or DEFINE_STATIC_SRCU() or at runtime via init_srcu_struct()
- and cleanup_srcu_struct(). These last two are passed a
- "struct srcu_struct" that defines the scope of a given
- SRCU domain. Once initialized, the srcu_struct is passed
- to srcu_read_lock(), srcu_read_unlock() synchronize_srcu(),
- synchronize_srcu_expedited(), and call_srcu(). A given
- synchronize_srcu() waits only for SRCU read-side critical
- sections governed by srcu_read_lock() and srcu_read_unlock()
- calls that have been passed the same srcu_struct. This property
- is what makes sleeping read-side critical sections tolerable --
- a given subsystem delays only its own updates, not those of other
- subsystems using SRCU. Therefore, SRCU is less prone to OOM the
- system than RCU would be if RCU's read-side critical sections
- were permitted to sleep.
-
- The ability to sleep in read-side critical sections does not
- come for free. First, corresponding srcu_read_lock() and
- srcu_read_unlock() calls must be passed the same srcu_struct.
- Second, grace-period-detection overhead is amortized only
- over those updates sharing a given srcu_struct, rather than
- being globally amortized as they are for other forms of RCU.
- Therefore, SRCU should be used in preference to rw_semaphore
- only in extremely read-intensive situations, or in situations
- requiring SRCU's read-side deadlock immunity or low read-side
- realtime latency. You should also consider percpu_rw_semaphore
- when you need lightweight readers.
-
- SRCU's expedited primitive (synchronize_srcu_expedited())
- never sends IPIs to other CPUs, so it is easier on
- real-time workloads than is synchronize_rcu_expedited().
-
- Note that rcu_assign_pointer() relates to SRCU just as it does to
- other forms of RCU, but instead of rcu_dereference() you should
- use srcu_dereference() in order to avoid lockdep splats.
-
-14. The whole point of call_rcu(), synchronize_rcu(), and friends
- is to wait until all pre-existing readers have finished before
- carrying out some otherwise-destructive operation. It is
- therefore critically important to -first- remove any path
- that readers can follow that could be affected by the
- destructive operation, and -only- -then- invoke call_rcu(),
- synchronize_rcu(), or friends.
-
- Because these primitives only wait for pre-existing readers, it
- is the caller's responsibility to guarantee that any subsequent
- readers will execute safely.
-
-15. The various RCU read-side primitives do -not- necessarily contain
- memory barriers. You should therefore plan for the CPU
- and the compiler to freely reorder code into and out of RCU
- read-side critical sections. It is the responsibility of the
- RCU update-side primitives to deal with this.
-
- For SRCU readers, you can use smp_mb__after_srcu_read_unlock()
- immediately after an srcu_read_unlock() to get a full barrier.
-
-16. Use CONFIG_PROVE_LOCKING, CONFIG_DEBUG_OBJECTS_RCU_HEAD, and the
- __rcu sparse checks to validate your RCU code. These can help
- find problems as follows:
-
- CONFIG_PROVE_LOCKING: check that accesses to RCU-protected data
- structures are carried out under the proper RCU
- read-side critical section, while holding the right
- combination of locks, or whatever other conditions
- are appropriate.
-
- CONFIG_DEBUG_OBJECTS_RCU_HEAD: check that you don't pass the
- same object to call_rcu() (or friends) before an RCU
- grace period has elapsed since the last time that you
- passed that same object to call_rcu() (or friends).
-
- __rcu sparse checks: tag the pointer to the RCU-protected data
- structure with __rcu, and sparse will warn you if you
- access that pointer without the services of one of the
- variants of rcu_dereference().
-
- These debugging aids can help you find problems that are
- otherwise extremely difficult to spot.
-
-17. If you register a callback using call_rcu() or call_srcu(), and
- pass in a function defined within a loadable module, then it in
- necessary to wait for all pending callbacks to be invoked after
- the last invocation and before unloading that module. Note that
- it is absolutely -not- sufficient to wait for a grace period!
- The current (say) synchronize_rcu() implementation is -not-
- guaranteed to wait for callbacks registered on other CPUs.
- Or even on the current CPU if that CPU recently went offline
- and came back online.
-
- You instead need to use one of the barrier functions:
-
- o call_rcu() -> rcu_barrier()
- o call_srcu() -> srcu_barrier()
-
- However, these barrier functions are absolutely -not- guaranteed
- to wait for a grace period. In fact, if there are no call_rcu()
- callbacks waiting anywhere in the system, rcu_barrier() is within
- its rights to return immediately.
-
- So if you need to wait for both an RCU grace period and for
- all pre-existing call_rcu() callbacks, you will need to execute
- both rcu_barrier() and synchronize_rcu(), if necessary, using
- something like workqueues to to execute them concurrently.
-
- See rcubarrier.txt for more information.
diff --git a/Documentation/RCU/index.rst b/Documentation/RCU/index.rst
index 81a0a1e..e703d3d 100644
--- a/Documentation/RCU/index.rst
+++ b/Documentation/RCU/index.rst
@@ -1,3 +1,5 @@
+.. SPDX-License-Identifier: GPL-2.0
+
.. _rcu_concepts:
============
@@ -8,10 +10,17 @@
:maxdepth: 3
arrayRCU
+ checklist
+ lockdep
+ lockdep-splat
rcubarrier
rcu_dereference
whatisRCU
rcu
+ rculist_nulls
+ rcuref
+ torture
+ stallwarn
listRCU
NMI-RCU
UP
diff --git a/Documentation/RCU/lockdep-splat.rst b/Documentation/RCU/lockdep-splat.rst
new file mode 100644
index 0000000..2a5c79d
--- /dev/null
+++ b/Documentation/RCU/lockdep-splat.rst
@@ -0,0 +1,115 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+=================
+Lockdep-RCU Splat
+=================
+
+Lockdep-RCU was added to the Linux kernel in early 2010
+(http://lwn.net/Articles/371986/). This facility checks for some common
+misuses of the RCU API, most notably using one of the rcu_dereference()
+family to access an RCU-protected pointer without the proper protection.
+When such misuse is detected, an lockdep-RCU splat is emitted.
+
+The usual cause of a lockdep-RCU slat is someone accessing an
+RCU-protected data structure without either (1) being in the right kind of
+RCU read-side critical section or (2) holding the right update-side lock.
+This problem can therefore be serious: it might result in random memory
+overwriting or worse. There can of course be false positives, this
+being the real world and all that.
+
+So let's look at an example RCU lockdep splat from 3.0-rc5, one that
+has long since been fixed::
+
+ =============================
+ WARNING: suspicious RCU usage
+ -----------------------------
+ block/cfq-iosched.c:2776 suspicious rcu_dereference_protected() usage!
+
+other info that might help us debug this::
+
+ rcu_scheduler_active = 1, debug_locks = 0
+ 3 locks held by scsi_scan_6/1552:
+ #0: (&shost->scan_mutex){+.+.}, at: [<ffffffff8145efca>]
+ scsi_scan_host_selected+0x5a/0x150
+ #1: (&eq->sysfs_lock){+.+.}, at: [<ffffffff812a5032>]
+ elevator_exit+0x22/0x60
+ #2: (&(&q->__queue_lock)->rlock){-.-.}, at: [<ffffffff812b6233>]
+ cfq_exit_queue+0x43/0x190
+
+ stack backtrace:
+ Pid: 1552, comm: scsi_scan_6 Not tainted 3.0.0-rc5 #17
+ Call Trace:
+ [<ffffffff810abb9b>] lockdep_rcu_dereference+0xbb/0xc0
+ [<ffffffff812b6139>] __cfq_exit_single_io_context+0xe9/0x120
+ [<ffffffff812b626c>] cfq_exit_queue+0x7c/0x190
+ [<ffffffff812a5046>] elevator_exit+0x36/0x60
+ [<ffffffff812a802a>] blk_cleanup_queue+0x4a/0x60
+ [<ffffffff8145cc09>] scsi_free_queue+0x9/0x10
+ [<ffffffff81460944>] __scsi_remove_device+0x84/0xd0
+ [<ffffffff8145dca3>] scsi_probe_and_add_lun+0x353/0xb10
+ [<ffffffff817da069>] ? error_exit+0x29/0xb0
+ [<ffffffff817d98ed>] ? _raw_spin_unlock_irqrestore+0x3d/0x80
+ [<ffffffff8145e722>] __scsi_scan_target+0x112/0x680
+ [<ffffffff812c690d>] ? trace_hardirqs_off_thunk+0x3a/0x3c
+ [<ffffffff817da069>] ? error_exit+0x29/0xb0
+ [<ffffffff812bcc60>] ? kobject_del+0x40/0x40
+ [<ffffffff8145ed16>] scsi_scan_channel+0x86/0xb0
+ [<ffffffff8145f0b0>] scsi_scan_host_selected+0x140/0x150
+ [<ffffffff8145f149>] do_scsi_scan_host+0x89/0x90
+ [<ffffffff8145f170>] do_scan_async+0x20/0x160
+ [<ffffffff8145f150>] ? do_scsi_scan_host+0x90/0x90
+ [<ffffffff810975b6>] kthread+0xa6/0xb0
+ [<ffffffff817db154>] kernel_thread_helper+0x4/0x10
+ [<ffffffff81066430>] ? finish_task_switch+0x80/0x110
+ [<ffffffff817d9c04>] ? retint_restore_args+0xe/0xe
+ [<ffffffff81097510>] ? __kthread_init_worker+0x70/0x70
+ [<ffffffff817db150>] ? gs_change+0xb/0xb
+
+Line 2776 of block/cfq-iosched.c in v3.0-rc5 is as follows::
+
+ if (rcu_dereference(ioc->ioc_data) == cic) {
+
+This form says that it must be in a plain vanilla RCU read-side critical
+section, but the "other info" list above shows that this is not the
+case. Instead, we hold three locks, one of which might be RCU related.
+And maybe that lock really does protect this reference. If so, the fix
+is to inform RCU, perhaps by changing __cfq_exit_single_io_context() to
+take the struct request_queue "q" from cfq_exit_queue() as an argument,
+which would permit us to invoke rcu_dereference_protected as follows::
+
+ if (rcu_dereference_protected(ioc->ioc_data,
+ lockdep_is_held(&q->queue_lock)) == cic) {
+
+With this change, there would be no lockdep-RCU splat emitted if this
+code was invoked either from within an RCU read-side critical section
+or with the ->queue_lock held. In particular, this would have suppressed
+the above lockdep-RCU splat because ->queue_lock is held (see #2 in the
+list above).
+
+On the other hand, perhaps we really do need an RCU read-side critical
+section. In this case, the critical section must span the use of the
+return value from rcu_dereference(), or at least until there is some
+reference count incremented or some such. One way to handle this is to
+add rcu_read_lock() and rcu_read_unlock() as follows::
+
+ rcu_read_lock();
+ if (rcu_dereference(ioc->ioc_data) == cic) {
+ spin_lock(&ioc->lock);
+ rcu_assign_pointer(ioc->ioc_data, NULL);
+ spin_unlock(&ioc->lock);
+ }
+ rcu_read_unlock();
+
+With this change, the rcu_dereference() is always within an RCU
+read-side critical section, which again would have suppressed the
+above lockdep-RCU splat.
+
+But in this particular case, we don't actually dereference the pointer
+returned from rcu_dereference(). Instead, that pointer is just compared
+to the cic pointer, which means that the rcu_dereference() can be replaced
+by rcu_access_pointer() as follows::
+
+ if (rcu_access_pointer(ioc->ioc_data) == cic) {
+
+Because it is legal to invoke rcu_access_pointer() without protection,
+this change would also suppress the above lockdep-RCU splat.
diff --git a/Documentation/RCU/lockdep-splat.txt b/Documentation/RCU/lockdep-splat.txt
deleted file mode 100644
index b809631..0000000
--- a/Documentation/RCU/lockdep-splat.txt
+++ /dev/null
@@ -1,110 +0,0 @@
-Lockdep-RCU was added to the Linux kernel in early 2010
-(http://lwn.net/Articles/371986/). This facility checks for some common
-misuses of the RCU API, most notably using one of the rcu_dereference()
-family to access an RCU-protected pointer without the proper protection.
-When such misuse is detected, an lockdep-RCU splat is emitted.
-
-The usual cause of a lockdep-RCU slat is someone accessing an
-RCU-protected data structure without either (1) being in the right kind of
-RCU read-side critical section or (2) holding the right update-side lock.
-This problem can therefore be serious: it might result in random memory
-overwriting or worse. There can of course be false positives, this
-being the real world and all that.
-
-So let's look at an example RCU lockdep splat from 3.0-rc5, one that
-has long since been fixed:
-
-=============================
-WARNING: suspicious RCU usage
------------------------------
-block/cfq-iosched.c:2776 suspicious rcu_dereference_protected() usage!
-
-other info that might help us debug this:
-
-
-rcu_scheduler_active = 1, debug_locks = 0
-3 locks held by scsi_scan_6/1552:
- #0: (&shost->scan_mutex){+.+.}, at: [<ffffffff8145efca>]
-scsi_scan_host_selected+0x5a/0x150
- #1: (&eq->sysfs_lock){+.+.}, at: [<ffffffff812a5032>]
-elevator_exit+0x22/0x60
- #2: (&(&q->__queue_lock)->rlock){-.-.}, at: [<ffffffff812b6233>]
-cfq_exit_queue+0x43/0x190
-
-stack backtrace:
-Pid: 1552, comm: scsi_scan_6 Not tainted 3.0.0-rc5 #17
-Call Trace:
- [<ffffffff810abb9b>] lockdep_rcu_dereference+0xbb/0xc0
- [<ffffffff812b6139>] __cfq_exit_single_io_context+0xe9/0x120
- [<ffffffff812b626c>] cfq_exit_queue+0x7c/0x190
- [<ffffffff812a5046>] elevator_exit+0x36/0x60
- [<ffffffff812a802a>] blk_cleanup_queue+0x4a/0x60
- [<ffffffff8145cc09>] scsi_free_queue+0x9/0x10
- [<ffffffff81460944>] __scsi_remove_device+0x84/0xd0
- [<ffffffff8145dca3>] scsi_probe_and_add_lun+0x353/0xb10
- [<ffffffff817da069>] ? error_exit+0x29/0xb0
- [<ffffffff817d98ed>] ? _raw_spin_unlock_irqrestore+0x3d/0x80
- [<ffffffff8145e722>] __scsi_scan_target+0x112/0x680
- [<ffffffff812c690d>] ? trace_hardirqs_off_thunk+0x3a/0x3c
- [<ffffffff817da069>] ? error_exit+0x29/0xb0
- [<ffffffff812bcc60>] ? kobject_del+0x40/0x40
- [<ffffffff8145ed16>] scsi_scan_channel+0x86/0xb0
- [<ffffffff8145f0b0>] scsi_scan_host_selected+0x140/0x150
- [<ffffffff8145f149>] do_scsi_scan_host+0x89/0x90
- [<ffffffff8145f170>] do_scan_async+0x20/0x160
- [<ffffffff8145f150>] ? do_scsi_scan_host+0x90/0x90
- [<ffffffff810975b6>] kthread+0xa6/0xb0
- [<ffffffff817db154>] kernel_thread_helper+0x4/0x10
- [<ffffffff81066430>] ? finish_task_switch+0x80/0x110
- [<ffffffff817d9c04>] ? retint_restore_args+0xe/0xe
- [<ffffffff81097510>] ? __kthread_init_worker+0x70/0x70
- [<ffffffff817db150>] ? gs_change+0xb/0xb
-
-Line 2776 of block/cfq-iosched.c in v3.0-rc5 is as follows:
-
- if (rcu_dereference(ioc->ioc_data) == cic) {
-
-This form says that it must be in a plain vanilla RCU read-side critical
-section, but the "other info" list above shows that this is not the
-case. Instead, we hold three locks, one of which might be RCU related.
-And maybe that lock really does protect this reference. If so, the fix
-is to inform RCU, perhaps by changing __cfq_exit_single_io_context() to
-take the struct request_queue "q" from cfq_exit_queue() as an argument,
-which would permit us to invoke rcu_dereference_protected as follows:
-
- if (rcu_dereference_protected(ioc->ioc_data,
- lockdep_is_held(&q->queue_lock)) == cic) {
-
-With this change, there would be no lockdep-RCU splat emitted if this
-code was invoked either from within an RCU read-side critical section
-or with the ->queue_lock held. In particular, this would have suppressed
-the above lockdep-RCU splat because ->queue_lock is held (see #2 in the
-list above).
-
-On the other hand, perhaps we really do need an RCU read-side critical
-section. In this case, the critical section must span the use of the
-return value from rcu_dereference(), or at least until there is some
-reference count incremented or some such. One way to handle this is to
-add rcu_read_lock() and rcu_read_unlock() as follows:
-
- rcu_read_lock();
- if (rcu_dereference(ioc->ioc_data) == cic) {
- spin_lock(&ioc->lock);
- rcu_assign_pointer(ioc->ioc_data, NULL);
- spin_unlock(&ioc->lock);
- }
- rcu_read_unlock();
-
-With this change, the rcu_dereference() is always within an RCU
-read-side critical section, which again would have suppressed the
-above lockdep-RCU splat.
-
-But in this particular case, we don't actually dereference the pointer
-returned from rcu_dereference(). Instead, that pointer is just compared
-to the cic pointer, which means that the rcu_dereference() can be replaced
-by rcu_access_pointer() as follows:
-
- if (rcu_access_pointer(ioc->ioc_data) == cic) {
-
-Because it is legal to invoke rcu_access_pointer() without protection,
-this change would also suppress the above lockdep-RCU splat.
diff --git a/Documentation/RCU/lockdep.rst b/Documentation/RCU/lockdep.rst
new file mode 100644
index 0000000..f1fc8ae
--- /dev/null
+++ b/Documentation/RCU/lockdep.rst
@@ -0,0 +1,116 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+========================
+RCU and lockdep checking
+========================
+
+All flavors of RCU have lockdep checking available, so that lockdep is
+aware of when each task enters and leaves any flavor of RCU read-side
+critical section. Each flavor of RCU is tracked separately (but note
+that this is not the case in 2.6.32 and earlier). This allows lockdep's
+tracking to include RCU state, which can sometimes help when debugging
+deadlocks and the like.
+
+In addition, RCU provides the following primitives that check lockdep's
+state::
+
+ rcu_read_lock_held() for normal RCU.
+ rcu_read_lock_bh_held() for RCU-bh.
+ rcu_read_lock_sched_held() for RCU-sched.
+ srcu_read_lock_held() for SRCU.
+
+These functions are conservative, and will therefore return 1 if they
+aren't certain (for example, if CONFIG_DEBUG_LOCK_ALLOC is not set).
+This prevents things like WARN_ON(!rcu_read_lock_held()) from giving false
+positives when lockdep is disabled.
+
+In addition, a separate kernel config parameter CONFIG_PROVE_RCU enables
+checking of rcu_dereference() primitives:
+
+ rcu_dereference(p):
+ Check for RCU read-side critical section.
+ rcu_dereference_bh(p):
+ Check for RCU-bh read-side critical section.
+ rcu_dereference_sched(p):
+ Check for RCU-sched read-side critical section.
+ srcu_dereference(p, sp):
+ Check for SRCU read-side critical section.
+ rcu_dereference_check(p, c):
+ Use explicit check expression "c" along with
+ rcu_read_lock_held(). This is useful in code that is
+ invoked by both RCU readers and updaters.
+ rcu_dereference_bh_check(p, c):
+ Use explicit check expression "c" along with
+ rcu_read_lock_bh_held(). This is useful in code that
+ is invoked by both RCU-bh readers and updaters.
+ rcu_dereference_sched_check(p, c):
+ Use explicit check expression "c" along with
+ rcu_read_lock_sched_held(). This is useful in code that
+ is invoked by both RCU-sched readers and updaters.
+ srcu_dereference_check(p, c):
+ Use explicit check expression "c" along with
+ srcu_read_lock_held()(). This is useful in code that
+ is invoked by both SRCU readers and updaters.
+ rcu_dereference_raw(p):
+ Don't check. (Use sparingly, if at all.)
+ rcu_dereference_protected(p, c):
+ Use explicit check expression "c", and omit all barriers
+ and compiler constraints. This is useful when the data
+ structure cannot change, for example, in code that is
+ invoked only by updaters.
+ rcu_access_pointer(p):
+ Return the value of the pointer and omit all barriers,
+ but retain the compiler constraints that prevent duplicating
+ or coalescsing. This is useful when when testing the
+ value of the pointer itself, for example, against NULL.
+
+The rcu_dereference_check() check expression can be any boolean
+expression, but would normally include a lockdep expression. However,
+any boolean expression can be used. For a moderately ornate example,
+consider the following::
+
+ file = rcu_dereference_check(fdt->fd[fd],
+ lockdep_is_held(&files->file_lock) ||
+ atomic_read(&files->count) == 1);
+
+This expression picks up the pointer "fdt->fd[fd]" in an RCU-safe manner,
+and, if CONFIG_PROVE_RCU is configured, verifies that this expression
+is used in:
+
+1. An RCU read-side critical section (implicit), or
+2. with files->file_lock held, or
+3. on an unshared files_struct.
+
+In case (1), the pointer is picked up in an RCU-safe manner for vanilla
+RCU read-side critical sections, in case (2) the ->file_lock prevents
+any change from taking place, and finally, in case (3) the current task
+is the only task accessing the file_struct, again preventing any change
+from taking place. If the above statement was invoked only from updater
+code, it could instead be written as follows::
+
+ file = rcu_dereference_protected(fdt->fd[fd],
+ lockdep_is_held(&files->file_lock) ||
+ atomic_read(&files->count) == 1);
+
+This would verify cases #2 and #3 above, and furthermore lockdep would
+complain if this was used in an RCU read-side critical section unless one
+of these two cases held. Because rcu_dereference_protected() omits all
+barriers and compiler constraints, it generates better code than do the
+other flavors of rcu_dereference(). On the other hand, it is illegal
+to use rcu_dereference_protected() if either the RCU-protected pointer
+or the RCU-protected data that it points to can change concurrently.
+
+Like rcu_dereference(), when lockdep is enabled, RCU list and hlist
+traversal primitives check for being called from within an RCU read-side
+critical section. However, a lockdep expression can be passed to them
+as a additional optional argument. With this lockdep expression, these
+traversal primitives will complain only if the lockdep expression is
+false and they are called from outside any RCU read-side critical section.
+
+For example, the workqueue for_each_pwq() macro is intended to be used
+either within an RCU read-side critical section or with wq->mutex held.
+It is thus implemented as follows::
+
+ #define for_each_pwq(pwq, wq)
+ list_for_each_entry_rcu((pwq), &(wq)->pwqs, pwqs_node,
+ lock_is_held(&(wq->mutex).dep_map))
diff --git a/Documentation/RCU/lockdep.txt b/Documentation/RCU/lockdep.txt
deleted file mode 100644
index 89db949e..0000000
--- a/Documentation/RCU/lockdep.txt
+++ /dev/null
@@ -1,112 +0,0 @@
-RCU and lockdep checking
-
-All flavors of RCU have lockdep checking available, so that lockdep is
-aware of when each task enters and leaves any flavor of RCU read-side
-critical section. Each flavor of RCU is tracked separately (but note
-that this is not the case in 2.6.32 and earlier). This allows lockdep's
-tracking to include RCU state, which can sometimes help when debugging
-deadlocks and the like.
-
-In addition, RCU provides the following primitives that check lockdep's
-state:
-
- rcu_read_lock_held() for normal RCU.
- rcu_read_lock_bh_held() for RCU-bh.
- rcu_read_lock_sched_held() for RCU-sched.
- srcu_read_lock_held() for SRCU.
-
-These functions are conservative, and will therefore return 1 if they
-aren't certain (for example, if CONFIG_DEBUG_LOCK_ALLOC is not set).
-This prevents things like WARN_ON(!rcu_read_lock_held()) from giving false
-positives when lockdep is disabled.
-
-In addition, a separate kernel config parameter CONFIG_PROVE_RCU enables
-checking of rcu_dereference() primitives:
-
- rcu_dereference(p):
- Check for RCU read-side critical section.
- rcu_dereference_bh(p):
- Check for RCU-bh read-side critical section.
- rcu_dereference_sched(p):
- Check for RCU-sched read-side critical section.
- srcu_dereference(p, sp):
- Check for SRCU read-side critical section.
- rcu_dereference_check(p, c):
- Use explicit check expression "c" along with
- rcu_read_lock_held(). This is useful in code that is
- invoked by both RCU readers and updaters.
- rcu_dereference_bh_check(p, c):
- Use explicit check expression "c" along with
- rcu_read_lock_bh_held(). This is useful in code that
- is invoked by both RCU-bh readers and updaters.
- rcu_dereference_sched_check(p, c):
- Use explicit check expression "c" along with
- rcu_read_lock_sched_held(). This is useful in code that
- is invoked by both RCU-sched readers and updaters.
- srcu_dereference_check(p, c):
- Use explicit check expression "c" along with
- srcu_read_lock_held()(). This is useful in code that
- is invoked by both SRCU readers and updaters.
- rcu_dereference_raw(p):
- Don't check. (Use sparingly, if at all.)
- rcu_dereference_protected(p, c):
- Use explicit check expression "c", and omit all barriers
- and compiler constraints. This is useful when the data
- structure cannot change, for example, in code that is
- invoked only by updaters.
- rcu_access_pointer(p):
- Return the value of the pointer and omit all barriers,
- but retain the compiler constraints that prevent duplicating
- or coalescsing. This is useful when when testing the
- value of the pointer itself, for example, against NULL.
-
-The rcu_dereference_check() check expression can be any boolean
-expression, but would normally include a lockdep expression. However,
-any boolean expression can be used. For a moderately ornate example,
-consider the following:
-
- file = rcu_dereference_check(fdt->fd[fd],
- lockdep_is_held(&files->file_lock) ||
- atomic_read(&files->count) == 1);
-
-This expression picks up the pointer "fdt->fd[fd]" in an RCU-safe manner,
-and, if CONFIG_PROVE_RCU is configured, verifies that this expression
-is used in:
-
-1. An RCU read-side critical section (implicit), or
-2. with files->file_lock held, or
-3. on an unshared files_struct.
-
-In case (1), the pointer is picked up in an RCU-safe manner for vanilla
-RCU read-side critical sections, in case (2) the ->file_lock prevents
-any change from taking place, and finally, in case (3) the current task
-is the only task accessing the file_struct, again preventing any change
-from taking place. If the above statement was invoked only from updater
-code, it could instead be written as follows:
-
- file = rcu_dereference_protected(fdt->fd[fd],
- lockdep_is_held(&files->file_lock) ||
- atomic_read(&files->count) == 1);
-
-This would verify cases #2 and #3 above, and furthermore lockdep would
-complain if this was used in an RCU read-side critical section unless one
-of these two cases held. Because rcu_dereference_protected() omits all
-barriers and compiler constraints, it generates better code than do the
-other flavors of rcu_dereference(). On the other hand, it is illegal
-to use rcu_dereference_protected() if either the RCU-protected pointer
-or the RCU-protected data that it points to can change concurrently.
-
-Like rcu_dereference(), when lockdep is enabled, RCU list and hlist
-traversal primitives check for being called from within an RCU read-side
-critical section. However, a lockdep expression can be passed to them
-as a additional optional argument. With this lockdep expression, these
-traversal primitives will complain only if the lockdep expression is
-false and they are called from outside any RCU read-side critical section.
-
-For example, the workqueue for_each_pwq() macro is intended to be used
-either within an RCU read-side critical section or with wq->mutex held.
-It is thus implemented as follows:
-
- #define for_each_pwq(pwq, wq)
- list_for_each_entry_rcu((pwq), &(wq)->pwqs, pwqs_node,
- lock_is_held(&(wq->mutex).dep_map))
diff --git a/Documentation/RCU/rculist_nulls.rst b/Documentation/RCU/rculist_nulls.rst
new file mode 100644
index 0000000..a9fc774
--- /dev/null
+++ b/Documentation/RCU/rculist_nulls.rst
@@ -0,0 +1,200 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+=================================================
+Using RCU hlist_nulls to protect list and objects
+=================================================
+
+This section describes how to use hlist_nulls to
+protect read-mostly linked lists and
+objects using SLAB_TYPESAFE_BY_RCU allocations.
+
+Please read the basics in Documentation/RCU/listRCU.rst
+
+Using 'nulls'
+=============
+
+Using special makers (called 'nulls') is a convenient way
+to solve following problem :
+
+A typical RCU linked list managing objects which are
+allocated with SLAB_TYPESAFE_BY_RCU kmem_cache can
+use following algos :
+
+1) Lookup algo
+--------------
+
+::
+
+ rcu_read_lock()
+ begin:
+ obj = lockless_lookup(key);
+ if (obj) {
+ if (!try_get_ref(obj)) // might fail for free objects
+ goto begin;
+ /*
+ * Because a writer could delete object, and a writer could
+ * reuse these object before the RCU grace period, we
+ * must check key after getting the reference on object
+ */
+ if (obj->key != key) { // not the object we expected
+ put_ref(obj);
+ goto begin;
+ }
+ }
+ rcu_read_unlock();
+
+Beware that lockless_lookup(key) cannot use traditional hlist_for_each_entry_rcu()
+but a version with an additional memory barrier (smp_rmb())
+
+::
+
+ lockless_lookup(key)
+ {
+ struct hlist_node *node, *next;
+ for (pos = rcu_dereference((head)->first);
+ pos && ({ next = pos->next; smp_rmb(); prefetch(next); 1; }) &&
+ ({ tpos = hlist_entry(pos, typeof(*tpos), member); 1; });
+ pos = rcu_dereference(next))
+ if (obj->key == key)
+ return obj;
+ return NULL;
+ }
+
+And note the traditional hlist_for_each_entry_rcu() misses this smp_rmb()::
+
+ struct hlist_node *node;
+ for (pos = rcu_dereference((head)->first);
+ pos && ({ prefetch(pos->next); 1; }) &&
+ ({ tpos = hlist_entry(pos, typeof(*tpos), member); 1; });
+ pos = rcu_dereference(pos->next))
+ if (obj->key == key)
+ return obj;
+ return NULL;
+
+Quoting Corey Minyard::
+
+ "If the object is moved from one list to another list in-between the
+ time the hash is calculated and the next field is accessed, and the
+ object has moved to the end of a new list, the traversal will not
+ complete properly on the list it should have, since the object will
+ be on the end of the new list and there's not a way to tell it's on a
+ new list and restart the list traversal. I think that this can be
+ solved by pre-fetching the "next" field (with proper barriers) before
+ checking the key."
+
+2) Insert algo
+--------------
+
+We need to make sure a reader cannot read the new 'obj->obj_next' value
+and previous value of 'obj->key'. Or else, an item could be deleted
+from a chain, and inserted into another chain. If new chain was empty
+before the move, 'next' pointer is NULL, and lockless reader can
+not detect it missed following items in original chain.
+
+::
+
+ /*
+ * Please note that new inserts are done at the head of list,
+ * not in the middle or end.
+ */
+ obj = kmem_cache_alloc(...);
+ lock_chain(); // typically a spin_lock()
+ obj->key = key;
+ /*
+ * we need to make sure obj->key is updated before obj->next
+ * or obj->refcnt
+ */
+ smp_wmb();
+ atomic_set(&obj->refcnt, 1);
+ hlist_add_head_rcu(&obj->obj_node, list);
+ unlock_chain(); // typically a spin_unlock()
+
+
+3) Remove algo
+--------------
+Nothing special here, we can use a standard RCU hlist deletion.
+But thanks to SLAB_TYPESAFE_BY_RCU, beware a deleted object can be reused
+very very fast (before the end of RCU grace period)
+
+::
+
+ if (put_last_reference_on(obj) {
+ lock_chain(); // typically a spin_lock()
+ hlist_del_init_rcu(&obj->obj_node);
+ unlock_chain(); // typically a spin_unlock()
+ kmem_cache_free(cachep, obj);
+ }
+
+
+
+--------------------------------------------------------------------------
+
+Avoiding extra smp_rmb()
+========================
+
+With hlist_nulls we can avoid extra smp_rmb() in lockless_lookup()
+and extra smp_wmb() in insert function.
+
+For example, if we choose to store the slot number as the 'nulls'
+end-of-list marker for each slot of the hash table, we can detect
+a race (some writer did a delete and/or a move of an object
+to another chain) checking the final 'nulls' value if
+the lookup met the end of chain. If final 'nulls' value
+is not the slot number, then we must restart the lookup at
+the beginning. If the object was moved to the same chain,
+then the reader doesn't care : It might eventually
+scan the list again without harm.
+
+
+1) lookup algo
+--------------
+
+::
+
+ head = &table[slot];
+ rcu_read_lock();
+ begin:
+ hlist_nulls_for_each_entry_rcu(obj, node, head, member) {
+ if (obj->key == key) {
+ if (!try_get_ref(obj)) // might fail for free objects
+ goto begin;
+ if (obj->key != key) { // not the object we expected
+ put_ref(obj);
+ goto begin;
+ }
+ goto out;
+ }
+ /*
+ * if the nulls value we got at the end of this lookup is
+ * not the expected one, we must restart lookup.
+ * We probably met an item that was moved to another chain.
+ */
+ if (get_nulls_value(node) != slot)
+ goto begin;
+ obj = NULL;
+
+ out:
+ rcu_read_unlock();
+
+2) Insert function
+------------------
+
+::
+
+ /*
+ * Please note that new inserts are done at the head of list,
+ * not in the middle or end.
+ */
+ obj = kmem_cache_alloc(cachep);
+ lock_chain(); // typically a spin_lock()
+ obj->key = key;
+ /*
+ * changes to obj->key must be visible before refcnt one
+ */
+ smp_wmb();
+ atomic_set(&obj->refcnt, 1);
+ /*
+ * insert obj in RCU way (readers might be traversing chain)
+ */
+ hlist_nulls_add_head_rcu(&obj->obj_node, list);
+ unlock_chain(); // typically a spin_unlock()
diff --git a/Documentation/RCU/rculist_nulls.txt b/Documentation/RCU/rculist_nulls.txt
deleted file mode 100644
index 23f115d..0000000
--- a/Documentation/RCU/rculist_nulls.txt
+++ /dev/null
@@ -1,172 +0,0 @@
-Using hlist_nulls to protect read-mostly linked lists and
-objects using SLAB_TYPESAFE_BY_RCU allocations.
-
-Please read the basics in Documentation/RCU/listRCU.rst
-
-Using special makers (called 'nulls') is a convenient way
-to solve following problem :
-
-A typical RCU linked list managing objects which are
-allocated with SLAB_TYPESAFE_BY_RCU kmem_cache can
-use following algos :
-
-1) Lookup algo
---------------
-rcu_read_lock()
-begin:
-obj = lockless_lookup(key);
-if (obj) {
- if (!try_get_ref(obj)) // might fail for free objects
- goto begin;
- /*
- * Because a writer could delete object, and a writer could
- * reuse these object before the RCU grace period, we
- * must check key after getting the reference on object
- */
- if (obj->key != key) { // not the object we expected
- put_ref(obj);
- goto begin;
- }
-}
-rcu_read_unlock();
-
-Beware that lockless_lookup(key) cannot use traditional hlist_for_each_entry_rcu()
-but a version with an additional memory barrier (smp_rmb())
-
-lockless_lookup(key)
-{
- struct hlist_node *node, *next;
- for (pos = rcu_dereference((head)->first);
- pos && ({ next = pos->next; smp_rmb(); prefetch(next); 1; }) &&
- ({ tpos = hlist_entry(pos, typeof(*tpos), member); 1; });
- pos = rcu_dereference(next))
- if (obj->key == key)
- return obj;
- return NULL;
-
-And note the traditional hlist_for_each_entry_rcu() misses this smp_rmb() :
-
- struct hlist_node *node;
- for (pos = rcu_dereference((head)->first);
- pos && ({ prefetch(pos->next); 1; }) &&
- ({ tpos = hlist_entry(pos, typeof(*tpos), member); 1; });
- pos = rcu_dereference(pos->next))
- if (obj->key == key)
- return obj;
- return NULL;
-}
-
-Quoting Corey Minyard :
-
-"If the object is moved from one list to another list in-between the
- time the hash is calculated and the next field is accessed, and the
- object has moved to the end of a new list, the traversal will not
- complete properly on the list it should have, since the object will
- be on the end of the new list and there's not a way to tell it's on a
- new list and restart the list traversal. I think that this can be
- solved by pre-fetching the "next" field (with proper barriers) before
- checking the key."
-
-2) Insert algo :
-----------------
-
-We need to make sure a reader cannot read the new 'obj->obj_next' value
-and previous value of 'obj->key'. Or else, an item could be deleted
-from a chain, and inserted into another chain. If new chain was empty
-before the move, 'next' pointer is NULL, and lockless reader can
-not detect it missed following items in original chain.
-
-/*
- * Please note that new inserts are done at the head of list,
- * not in the middle or end.
- */
-obj = kmem_cache_alloc(...);
-lock_chain(); // typically a spin_lock()
-obj->key = key;
-/*
- * we need to make sure obj->key is updated before obj->next
- * or obj->refcnt
- */
-smp_wmb();
-atomic_set(&obj->refcnt, 1);
-hlist_add_head_rcu(&obj->obj_node, list);
-unlock_chain(); // typically a spin_unlock()
-
-
-3) Remove algo
---------------
-Nothing special here, we can use a standard RCU hlist deletion.
-But thanks to SLAB_TYPESAFE_BY_RCU, beware a deleted object can be reused
-very very fast (before the end of RCU grace period)
-
-if (put_last_reference_on(obj) {
- lock_chain(); // typically a spin_lock()
- hlist_del_init_rcu(&obj->obj_node);
- unlock_chain(); // typically a spin_unlock()
- kmem_cache_free(cachep, obj);
-}
-
-
-
---------------------------------------------------------------------------
-With hlist_nulls we can avoid extra smp_rmb() in lockless_lookup()
-and extra smp_wmb() in insert function.
-
-For example, if we choose to store the slot number as the 'nulls'
-end-of-list marker for each slot of the hash table, we can detect
-a race (some writer did a delete and/or a move of an object
-to another chain) checking the final 'nulls' value if
-the lookup met the end of chain. If final 'nulls' value
-is not the slot number, then we must restart the lookup at
-the beginning. If the object was moved to the same chain,
-then the reader doesn't care : It might eventually
-scan the list again without harm.
-
-
-1) lookup algo
-
- head = &table[slot];
- rcu_read_lock();
-begin:
- hlist_nulls_for_each_entry_rcu(obj, node, head, member) {
- if (obj->key == key) {
- if (!try_get_ref(obj)) // might fail for free objects
- goto begin;
- if (obj->key != key) { // not the object we expected
- put_ref(obj);
- goto begin;
- }
- goto out;
- }
-/*
- * if the nulls value we got at the end of this lookup is
- * not the expected one, we must restart lookup.
- * We probably met an item that was moved to another chain.
- */
- if (get_nulls_value(node) != slot)
- goto begin;
- obj = NULL;
-
-out:
- rcu_read_unlock();
-
-2) Insert function :
---------------------
-
-/*
- * Please note that new inserts are done at the head of list,
- * not in the middle or end.
- */
-obj = kmem_cache_alloc(cachep);
-lock_chain(); // typically a spin_lock()
-obj->key = key;
-/*
- * changes to obj->key must be visible before refcnt one
- */
-smp_wmb();
-atomic_set(&obj->refcnt, 1);
-/*
- * insert obj in RCU way (readers might be traversing chain)
- */
-hlist_nulls_add_head_rcu(&obj->obj_node, list);
-unlock_chain(); // typically a spin_unlock()
diff --git a/Documentation/RCU/rcuref.rst b/Documentation/RCU/rcuref.rst
new file mode 100644
index 0000000..b33aeb1
--- /dev/null
+++ b/Documentation/RCU/rcuref.rst
@@ -0,0 +1,158 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+====================================================================
+Reference-count design for elements of lists/arrays protected by RCU
+====================================================================
+
+
+Please note that the percpu-ref feature is likely your first
+stop if you need to combine reference counts and RCU. Please see
+include/linux/percpu-refcount.h for more information. However, in
+those unusual cases where percpu-ref would consume too much memory,
+please read on.
+
+------------------------------------------------------------------------
+
+Reference counting on elements of lists which are protected by traditional
+reader/writer spinlocks or semaphores are straightforward:
+
+CODE LISTING A::
+
+ 1. 2.
+ add() search_and_reference()
+ { {
+ alloc_object read_lock(&list_lock);
+ ... search_for_element
+ atomic_set(&el->rc, 1); atomic_inc(&el->rc);
+ write_lock(&list_lock); ...
+ add_element read_unlock(&list_lock);
+ ... ...
+ write_unlock(&list_lock); }
+ }
+
+ 3. 4.
+ release_referenced() delete()
+ { {
+ ... write_lock(&list_lock);
+ if(atomic_dec_and_test(&el->rc)) ...
+ kfree(el);
+ ... remove_element
+ } write_unlock(&list_lock);
+ ...
+ if (atomic_dec_and_test(&el->rc))
+ kfree(el);
+ ...
+ }
+
+If this list/array is made lock free using RCU as in changing the
+write_lock() in add() and delete() to spin_lock() and changing read_lock()
+in search_and_reference() to rcu_read_lock(), the atomic_inc() in
+search_and_reference() could potentially hold reference to an element which
+has already been deleted from the list/array. Use atomic_inc_not_zero()
+in this scenario as follows:
+
+CODE LISTING B::
+
+ 1. 2.
+ add() search_and_reference()
+ { {
+ alloc_object rcu_read_lock();
+ ... search_for_element
+ atomic_set(&el->rc, 1); if (!atomic_inc_not_zero(&el->rc)) {
+ spin_lock(&list_lock); rcu_read_unlock();
+ return FAIL;
+ add_element }
+ ... ...
+ spin_unlock(&list_lock); rcu_read_unlock();
+ } }
+ 3. 4.
+ release_referenced() delete()
+ { {
+ ... spin_lock(&list_lock);
+ if (atomic_dec_and_test(&el->rc)) ...
+ call_rcu(&el->head, el_free); remove_element
+ ... spin_unlock(&list_lock);
+ } ...
+ if (atomic_dec_and_test(&el->rc))
+ call_rcu(&el->head, el_free);
+ ...
+ }
+
+Sometimes, a reference to the element needs to be obtained in the
+update (write) stream. In such cases, atomic_inc_not_zero() might be
+overkill, since we hold the update-side spinlock. One might instead
+use atomic_inc() in such cases.
+
+It is not always convenient to deal with "FAIL" in the
+search_and_reference() code path. In such cases, the
+atomic_dec_and_test() may be moved from delete() to el_free()
+as follows:
+
+CODE LISTING C::
+
+ 1. 2.
+ add() search_and_reference()
+ { {
+ alloc_object rcu_read_lock();
+ ... search_for_element
+ atomic_set(&el->rc, 1); atomic_inc(&el->rc);
+ spin_lock(&list_lock); ...
+
+ add_element rcu_read_unlock();
+ ... }
+ spin_unlock(&list_lock); 4.
+ } delete()
+ 3. {
+ release_referenced() spin_lock(&list_lock);
+ { ...
+ ... remove_element
+ if (atomic_dec_and_test(&el->rc)) spin_unlock(&list_lock);
+ kfree(el); ...
+ ... call_rcu(&el->head, el_free);
+ } ...
+ 5. }
+ void el_free(struct rcu_head *rhp)
+ {
+ release_referenced();
+ }
+
+The key point is that the initial reference added by add() is not removed
+until after a grace period has elapsed following removal. This means that
+search_and_reference() cannot find this element, which means that the value
+of el->rc cannot increase. Thus, once it reaches zero, there are no
+readers that can or ever will be able to reference the element. The
+element can therefore safely be freed. This in turn guarantees that if
+any reader finds the element, that reader may safely acquire a reference
+without checking the value of the reference counter.
+
+A clear advantage of the RCU-based pattern in listing C over the one
+in listing B is that any call to search_and_reference() that locates
+a given object will succeed in obtaining a reference to that object,
+even given a concurrent invocation of delete() for that same object.
+Similarly, a clear advantage of both listings B and C over listing A is
+that a call to delete() is not delayed even if there are an arbitrarily
+large number of calls to search_and_reference() searching for the same
+object that delete() was invoked on. Instead, all that is delayed is
+the eventual invocation of kfree(), which is usually not a problem on
+modern computer systems, even the small ones.
+
+In cases where delete() can sleep, synchronize_rcu() can be called from
+delete(), so that el_free() can be subsumed into delete as follows::
+
+ 4.
+ delete()
+ {
+ spin_lock(&list_lock);
+ ...
+ remove_element
+ spin_unlock(&list_lock);
+ ...
+ synchronize_rcu();
+ if (atomic_dec_and_test(&el->rc))
+ kfree(el);
+ ...
+ }
+
+As additional examples in the kernel, the pattern in listing C is used by
+reference counting of struct pid, while the pattern in listing B is used by
+struct posix_acl.
diff --git a/Documentation/RCU/rcuref.txt b/Documentation/RCU/rcuref.txt
deleted file mode 100644
index 5e6429d6..0000000
--- a/Documentation/RCU/rcuref.txt
+++ /dev/null
@@ -1,151 +0,0 @@
-Reference-count design for elements of lists/arrays protected by RCU.
-
-
-Please note that the percpu-ref feature is likely your first
-stop if you need to combine reference counts and RCU. Please see
-include/linux/percpu-refcount.h for more information. However, in
-those unusual cases where percpu-ref would consume too much memory,
-please read on.
-
-------------------------------------------------------------------------
-
-Reference counting on elements of lists which are protected by traditional
-reader/writer spinlocks or semaphores are straightforward:
-
-CODE LISTING A:
-1. 2.
-add() search_and_reference()
-{ {
- alloc_object read_lock(&list_lock);
- ... search_for_element
- atomic_set(&el->rc, 1); atomic_inc(&el->rc);
- write_lock(&list_lock); ...
- add_element read_unlock(&list_lock);
- ... ...
- write_unlock(&list_lock); }
-}
-
-3. 4.
-release_referenced() delete()
-{ {
- ... write_lock(&list_lock);
- if(atomic_dec_and_test(&el->rc)) ...
- kfree(el);
- ... remove_element
-} write_unlock(&list_lock);
- ...
- if (atomic_dec_and_test(&el->rc))
- kfree(el);
- ...
- }
-
-If this list/array is made lock free using RCU as in changing the
-write_lock() in add() and delete() to spin_lock() and changing read_lock()
-in search_and_reference() to rcu_read_lock(), the atomic_inc() in
-search_and_reference() could potentially hold reference to an element which
-has already been deleted from the list/array. Use atomic_inc_not_zero()
-in this scenario as follows:
-
-CODE LISTING B:
-1. 2.
-add() search_and_reference()
-{ {
- alloc_object rcu_read_lock();
- ... search_for_element
- atomic_set(&el->rc, 1); if (!atomic_inc_not_zero(&el->rc)) {
- spin_lock(&list_lock); rcu_read_unlock();
- return FAIL;
- add_element }
- ... ...
- spin_unlock(&list_lock); rcu_read_unlock();
-} }
-3. 4.
-release_referenced() delete()
-{ {
- ... spin_lock(&list_lock);
- if (atomic_dec_and_test(&el->rc)) ...
- call_rcu(&el->head, el_free); remove_element
- ... spin_unlock(&list_lock);
-} ...
- if (atomic_dec_and_test(&el->rc))
- call_rcu(&el->head, el_free);
- ...
- }
-
-Sometimes, a reference to the element needs to be obtained in the
-update (write) stream. In such cases, atomic_inc_not_zero() might be
-overkill, since we hold the update-side spinlock. One might instead
-use atomic_inc() in such cases.
-
-It is not always convenient to deal with "FAIL" in the
-search_and_reference() code path. In such cases, the
-atomic_dec_and_test() may be moved from delete() to el_free()
-as follows:
-
-CODE LISTING C:
-1. 2.
-add() search_and_reference()
-{ {
- alloc_object rcu_read_lock();
- ... search_for_element
- atomic_set(&el->rc, 1); atomic_inc(&el->rc);
- spin_lock(&list_lock); ...
-
- add_element rcu_read_unlock();
- ... }
- spin_unlock(&list_lock); 4.
-} delete()
-3. {
-release_referenced() spin_lock(&list_lock);
-{ ...
- ... remove_element
- if (atomic_dec_and_test(&el->rc)) spin_unlock(&list_lock);
- kfree(el); ...
- ... call_rcu(&el->head, el_free);
-} ...
-5. }
-void el_free(struct rcu_head *rhp)
-{
- release_referenced();
-}
-
-The key point is that the initial reference added by add() is not removed
-until after a grace period has elapsed following removal. This means that
-search_and_reference() cannot find this element, which means that the value
-of el->rc cannot increase. Thus, once it reaches zero, there are no
-readers that can or ever will be able to reference the element. The
-element can therefore safely be freed. This in turn guarantees that if
-any reader finds the element, that reader may safely acquire a reference
-without checking the value of the reference counter.
-
-A clear advantage of the RCU-based pattern in listing C over the one
-in listing B is that any call to search_and_reference() that locates
-a given object will succeed in obtaining a reference to that object,
-even given a concurrent invocation of delete() for that same object.
-Similarly, a clear advantage of both listings B and C over listing A is
-that a call to delete() is not delayed even if there are an arbitrarily
-large number of calls to search_and_reference() searching for the same
-object that delete() was invoked on. Instead, all that is delayed is
-the eventual invocation of kfree(), which is usually not a problem on
-modern computer systems, even the small ones.
-
-In cases where delete() can sleep, synchronize_rcu() can be called from
-delete(), so that el_free() can be subsumed into delete as follows:
-
-4.
-delete()
-{
- spin_lock(&list_lock);
- ...
- remove_element
- spin_unlock(&list_lock);
- ...
- synchronize_rcu();
- if (atomic_dec_and_test(&el->rc))
- kfree(el);
- ...
-}
-
-As additional examples in the kernel, the pattern in listing C is used by
-reference counting of struct pid, while the pattern in listing B is used by
-struct posix_acl.
diff --git a/Documentation/RCU/stallwarn.rst b/Documentation/RCU/stallwarn.rst
new file mode 100644
index 0000000..c9ab6af
--- /dev/null
+++ b/Documentation/RCU/stallwarn.rst
@@ -0,0 +1,336 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+==============================
+Using RCU's CPU Stall Detector
+==============================
+
+This document first discusses what sorts of issues RCU's CPU stall
+detector can locate, and then discusses kernel parameters and Kconfig
+options that can be used to fine-tune the detector's operation. Finally,
+this document explains the stall detector's "splat" format.
+
+
+What Causes RCU CPU Stall Warnings?
+===================================
+
+So your kernel printed an RCU CPU stall warning. The next question is
+"What caused it?" The following problems can result in RCU CPU stall
+warnings:
+
+- A CPU looping in an RCU read-side critical section.
+
+- A CPU looping with interrupts disabled.
+
+- A CPU looping with preemption disabled.
+
+- A CPU looping with bottom halves disabled.
+
+- For !CONFIG_PREEMPT kernels, a CPU looping anywhere in the kernel
+ without invoking schedule(). If the looping in the kernel is
+ really expected and desirable behavior, you might need to add
+ some calls to cond_resched().
+
+- Booting Linux using a console connection that is too slow to
+ keep up with the boot-time console-message rate. For example,
+ a 115Kbaud serial console can be -way- too slow to keep up
+ with boot-time message rates, and will frequently result in
+ RCU CPU stall warning messages. Especially if you have added
+ debug printk()s.
+
+- Anything that prevents RCU's grace-period kthreads from running.
+ This can result in the "All QSes seen" console-log message.
+ This message will include information on when the kthread last
+ ran and how often it should be expected to run. It can also
+ result in the ``rcu_.*kthread starved for`` console-log message,
+ which will include additional debugging information.
+
+- A CPU-bound real-time task in a CONFIG_PREEMPT kernel, which might
+ happen to preempt a low-priority task in the middle of an RCU
+ read-side critical section. This is especially damaging if
+ that low-priority task is not permitted to run on any other CPU,
+ in which case the next RCU grace period can never complete, which
+ will eventually cause the system to run out of memory and hang.
+ While the system is in the process of running itself out of
+ memory, you might see stall-warning messages.
+
+- A CPU-bound real-time task in a CONFIG_PREEMPT_RT kernel that
+ is running at a higher priority than the RCU softirq threads.
+ This will prevent RCU callbacks from ever being invoked,
+ and in a CONFIG_PREEMPT_RCU kernel will further prevent
+ RCU grace periods from ever completing. Either way, the
+ system will eventually run out of memory and hang. In the
+ 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.
+
+- 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.
+ Note that certain high-overhead debugging options, for example
+ the function_graph tracer, can result in interrupt handler taking
+ considerably longer than normal, which can in turn result in
+ RCU CPU stall warnings.
+
+- Testing a workload on a fast system, tuning the stall-warning
+ timeout down to just barely avoid RCU CPU stall warnings, and then
+ running the same workload with the same stall-warning timeout on a
+ slow system. Note that thermal throttling and on-demand governors
+ can cause a single system to be sometimes fast and sometimes slow!
+
+- A hardware or software issue shuts off the scheduler-clock
+ interrupt on a CPU that is not in dyntick-idle mode. This
+ problem really has happened, and seems to be most likely to
+ result in RCU CPU stall warnings for CONFIG_NO_HZ_COMMON=n kernels.
+
+- A hardware or software issue that prevents time-based wakeups
+ from occurring. These issues can range from misconfigured or
+ buggy timer hardware through bugs in the interrupt or exception
+ path (whether hardware, firmware, or software) through bugs
+ in Linux's timer subsystem through bugs in the scheduler, and,
+ yes, even including bugs in RCU itself.
+
+- A bug in the RCU implementation.
+
+- A hardware failure. This is quite unlikely, but has occurred
+ at least once in real life. A CPU failed in a running system,
+ becoming unresponsive, but not causing an immediate crash.
+ This resulted in a series of RCU CPU stall warnings, eventually
+ leading the realization that the CPU had failed.
+
+The RCU, RCU-sched, and RCU-tasks implementations have CPU stall warning.
+Note that SRCU does -not- have CPU stall warnings. Please note that
+RCU only detects CPU stalls when there is a grace period in progress.
+No grace period, no CPU stall warnings.
+
+To diagnose the cause of the stall, inspect the stack traces.
+The offending function will usually be near the top of the stack.
+If you have a series of stall warnings from a single extended stall,
+comparing the stack traces can often help determine where the stall
+is occurring, which will usually be in the function nearest the top of
+that portion of the stack which remains the same from trace to trace.
+If you can reliably trigger the stall, ftrace can be quite helpful.
+
+RCU bugs can often be debugged with the help of CONFIG_RCU_TRACE
+and with RCU's event tracing. For information on RCU's event tracing,
+see include/trace/events/rcu.h.
+
+
+Fine-Tuning the RCU CPU Stall Detector
+======================================
+
+The rcuupdate.rcu_cpu_stall_suppress module parameter disables RCU's
+CPU stall detector, which detects conditions that unduly delay RCU grace
+periods. This module parameter enables CPU stall detection by default,
+but may be overridden via boot-time parameter or at runtime via sysfs.
+The stall detector's idea of what constitutes "unduly delayed" is
+controlled by a set of kernel configuration variables and cpp macros:
+
+CONFIG_RCU_CPU_STALL_TIMEOUT
+----------------------------
+
+ This kernel configuration parameter defines the period of time
+ that RCU will wait from the beginning of a grace period until it
+ issues an RCU CPU stall warning. This time period is normally
+ 21 seconds.
+
+ This configuration parameter may be changed at runtime via the
+ /sys/module/rcupdate/parameters/rcu_cpu_stall_timeout, however
+ this parameter is checked only at the beginning of a cycle.
+ So if you are 10 seconds into a 40-second stall, setting this
+ sysfs parameter to (say) five will shorten the timeout for the
+ -next- stall, or the following warning for the current stall
+ (assuming the stall lasts long enough). It will not affect the
+ timing of the next warning for the current stall.
+
+ Stall-warning messages may be enabled and disabled completely via
+ /sys/module/rcupdate/parameters/rcu_cpu_stall_suppress.
+
+RCU_STALL_DELAY_DELTA
+---------------------
+
+ Although the lockdep facility is extremely useful, it does add
+ some overhead. Therefore, under CONFIG_PROVE_RCU, the
+ RCU_STALL_DELAY_DELTA macro allows five extra seconds before
+ giving an RCU CPU stall warning message. (This is a cpp
+ macro, not a kernel configuration parameter.)
+
+RCU_STALL_RAT_DELAY
+-------------------
+
+ The CPU stall detector tries to make the offending CPU print its
+ own warnings, as this often gives better-quality stack traces.
+ However, if the offending CPU does not detect its own stall in
+ the number of jiffies specified by RCU_STALL_RAT_DELAY, then
+ some other CPU will complain. This delay is normally set to
+ two jiffies. (This is a cpp macro, not a kernel configuration
+ parameter.)
+
+rcupdate.rcu_task_stall_timeout
+-------------------------------
+
+ This boot/sysfs parameter controls the RCU-tasks stall warning
+ interval. A value of zero or less suppresses RCU-tasks stall
+ warnings. A positive value sets the stall-warning interval
+ in seconds. An RCU-tasks stall warning starts with the line:
+
+ INFO: rcu_tasks detected stalls on tasks:
+
+ And continues with the output of sched_show_task() for each
+ task stalling the current RCU-tasks grace period.
+
+
+Interpreting RCU's CPU Stall-Detector "Splats"
+==============================================
+
+For non-RCU-tasks flavors of RCU, when a CPU detects that it is stalling,
+it will print a message similar to the following::
+
+ INFO: rcu_sched detected stalls on CPUs/tasks:
+ 2-...: (3 GPs behind) idle=06c/0/0 softirq=1453/1455 fqs=0
+ 16-...: (0 ticks this GP) idle=81c/0/0 softirq=764/764 fqs=0
+ (detected by 32, t=2603 jiffies, g=7075, q=625)
+
+This message indicates that CPU 32 detected that CPUs 2 and 16 were both
+causing stalls, and that the stall was affecting RCU-sched. This message
+will normally be followed by stack dumps for each CPU. Please note that
+PREEMPT_RCU builds can be stalled by tasks as well as by CPUs, and that
+the tasks will be indicated by PID, for example, "P3421". It is even
+possible for an rcu_state stall to be caused by both CPUs -and- tasks,
+in which case the offending CPUs and tasks will all be called out in the list.
+
+CPU 2's "(3 GPs behind)" indicates that this CPU has not interacted with
+the RCU core for the past three grace periods. In contrast, CPU 16's "(0
+ticks this GP)" indicates that this CPU has not taken any scheduling-clock
+interrupts during the current stalled grace period.
+
+The "idle=" portion of the message prints the dyntick-idle state.
+The hex number before the first "/" is the low-order 12 bits of the
+dynticks counter, which will have an even-numbered value if the CPU
+is in dyntick-idle mode and an odd-numbered value otherwise. The hex
+number between the two "/"s is the value of the nesting, which will be
+a small non-negative number if in the idle loop (as shown above) and a
+very large positive number otherwise.
+
+The "softirq=" portion of the message tracks the number of RCU softirq
+handlers that the stalled CPU has executed. The number before the "/"
+is the number that had executed since boot at the time that this CPU
+last noted the beginning of a grace period, which might be the current
+(stalled) grace period, or it might be some earlier grace period (for
+example, if the CPU might have been in dyntick-idle mode for an extended
+time period. The number after the "/" is the number that have executed
+since boot until the current time. If this latter number stays constant
+across repeated stall-warning messages, it is possible that RCU's softirq
+handlers are no longer able to execute on this CPU. This can happen if
+the stalled CPU is spinning with interrupts are disabled, or, in -rt
+kernels, if a high-priority process is starving RCU's softirq handler.
+
+The "fqs=" shows the number of force-quiescent-state idle/offline
+detection passes that the grace-period kthread has made across this
+CPU since the last time that this CPU noted the beginning of a grace
+period.
+
+The "detected by" line indicates which CPU detected the stall (in this
+case, CPU 32), how many jiffies have elapsed since the start of the grace
+period (in this case 2603), the grace-period sequence number (7075), and
+an estimate of the total number of RCU callbacks queued across all CPUs
+(625 in this case).
+
+In kernels with CONFIG_RCU_FAST_NO_HZ, more information is printed
+for each CPU::
+
+ 0: (64628 ticks this GP) idle=dd5/3fffffffffffffff/0 softirq=82/543 last_accelerate: a345/d342 dyntick_enabled: 1
+
+The "last_accelerate:" prints the low-order 16 bits (in hex) of the
+jiffies counter when this CPU last invoked rcu_try_advance_all_cbs()
+from rcu_needs_cpu() or last invoked rcu_accelerate_cbs() from
+rcu_prepare_for_idle(). "dyntick_enabled: 1" indicates that dyntick-idle
+processing is enabled.
+
+If the grace period ends just as the stall warning starts printing,
+there will be a spurious stall-warning message, which will include
+the following::
+
+ INFO: Stall ended before state dump start
+
+This is rare, but does happen from time to time in real life. It is also
+possible for a zero-jiffy stall to be flagged in this case, depending
+on how the stall warning and the grace-period initialization happen to
+interact. Please note that it is not possible to entirely eliminate this
+sort of false positive without resorting to things like stop_machine(),
+which is overkill for this sort of problem.
+
+If all CPUs and tasks have passed through quiescent states, but the
+grace period has nevertheless failed to end, the stall-warning splat
+will include something like the following::
+
+ All QSes seen, last rcu_preempt kthread activity 23807 (4297905177-4297881370), jiffies_till_next_fqs=3, root ->qsmask 0x0
+
+The "23807" indicates that it has been more than 23 thousand jiffies
+since the grace-period kthread ran. The "jiffies_till_next_fqs"
+indicates how frequently that kthread should run, giving the number
+of jiffies between force-quiescent-state scans, in this case three,
+which is way less than 23807. Finally, the root rcu_node structure's
+->qsmask field is printed, which will normally be zero.
+
+If the relevant grace-period kthread has been unable to run prior to
+the stall warning, as was the case in the "All QSes seen" line above,
+the following additional line is printed::
+
+ kthread starved for 23807 jiffies! g7075 f0x0 RCU_GP_WAIT_FQS(3) ->state=0x1 ->cpu=5
+
+Starving the grace-period kthreads of CPU time can of course result
+in RCU CPU stall warnings even when all CPUs and tasks have passed
+through the required quiescent states. The "g" number shows the current
+grace-period sequence number, the "f" precedes the ->gp_flags command
+to the grace-period kthread, the "RCU_GP_WAIT_FQS" indicates that the
+kthread is waiting for a short timeout, the "state" precedes value of the
+task_struct ->state field, and the "cpu" indicates that the grace-period
+kthread last ran on CPU 5.
+
+
+Multiple Warnings From One Stall
+================================
+
+If a stall lasts long enough, multiple stall-warning messages will be
+printed for it. The second and subsequent messages are printed at
+longer intervals, so that the time between (say) the first and second
+message will be about three times the interval between the beginning
+of the stall and the first message.
+
+
+Stall Warnings for Expedited Grace Periods
+==========================================
+
+If an expedited grace period detects a stall, it will place a message
+like the following in dmesg::
+
+ INFO: rcu_sched detected expedited stalls on CPUs/tasks: { 7-... } 21119 jiffies s: 73 root: 0x2/.
+
+This indicates that CPU 7 has failed to respond to a reschedule IPI.
+The three periods (".") following the CPU number indicate that the CPU
+is online (otherwise the first period would instead have been "O"),
+that the CPU was online at the beginning of the expedited grace period
+(otherwise the second period would have instead been "o"), and that
+the CPU has been online at least once since boot (otherwise, the third
+period would instead have been "N"). The number before the "jiffies"
+indicates that the expedited grace period has been going on for 21,119
+jiffies. The number following the "s:" indicates that the expedited
+grace-period sequence counter is 73. The fact that this last value is
+odd indicates that an expedited grace period is in flight. The number
+following "root:" is a bitmask that indicates which children of the root
+rcu_node structure correspond to CPUs and/or tasks that are blocking the
+current expedited grace period. If the tree had more than one level,
+additional hex numbers would be printed for the states of the other
+rcu_node structures in the tree.
+
+As with normal grace periods, PREEMPT_RCU builds can be stalled by
+tasks as well as by CPUs, and that the tasks will be indicated by PID,
+for example, "P3421".
+
+It is entirely possible to see stall warnings from normal and from
+expedited grace periods at about the same time during the same run.
diff --git a/Documentation/RCU/stallwarn.txt b/Documentation/RCU/stallwarn.txt
deleted file mode 100644
index a360a87..0000000
--- a/Documentation/RCU/stallwarn.txt
+++ /dev/null
@@ -1,316 +0,0 @@
-Using RCU's CPU Stall Detector
-
-This document first discusses what sorts of issues RCU's CPU stall
-detector can locate, and then discusses kernel parameters and Kconfig
-options that can be used to fine-tune the detector's operation. Finally,
-this document explains the stall detector's "splat" format.
-
-
-What Causes RCU CPU Stall Warnings?
-
-So your kernel printed an RCU CPU stall warning. The next question is
-"What caused it?" The following problems can result in RCU CPU stall
-warnings:
-
-o A CPU looping in an RCU read-side critical section.
-
-o A CPU looping with interrupts disabled.
-
-o A CPU looping with preemption disabled.
-
-o A CPU looping with bottom halves disabled.
-
-o For !CONFIG_PREEMPT kernels, a CPU looping anywhere in the kernel
- without invoking schedule(). If the looping in the kernel is
- really expected and desirable behavior, you might need to add
- some calls to cond_resched().
-
-o Booting Linux using a console connection that is too slow to
- keep up with the boot-time console-message rate. For example,
- a 115Kbaud serial console can be -way- too slow to keep up
- with boot-time message rates, and will frequently result in
- RCU CPU stall warning messages. Especially if you have added
- debug printk()s.
-
-o Anything that prevents RCU's grace-period kthreads from running.
- This can result in the "All QSes seen" console-log message.
- This message will include information on when the kthread last
- ran and how often it should be expected to run. It can also
- result in the "rcu_.*kthread starved for" console-log message,
- which will include additional debugging information.
-
-o A CPU-bound real-time task in a CONFIG_PREEMPT kernel, which might
- happen to preempt a low-priority task in the middle of an RCU
- read-side critical section. This is especially damaging if
- that low-priority task is not permitted to run on any other CPU,
- in which case the next RCU grace period can never complete, which
- will eventually cause the system to run out of memory and hang.
- While the system is in the process of running itself out of
- memory, you might see stall-warning messages.
-
-o A CPU-bound real-time task in a CONFIG_PREEMPT_RT kernel that
- is running at a higher priority than the RCU softirq threads.
- This will prevent RCU callbacks from ever being invoked,
- and in a CONFIG_PREEMPT_RCU kernel will further prevent
- RCU grace periods from ever completing. Either way, the
- system will eventually run out of memory and hang. In the
- 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.
- Note that certain high-overhead debugging options, for example
- the function_graph tracer, can result in interrupt handler taking
- considerably longer than normal, which can in turn result in
- RCU CPU stall warnings.
-
-o Testing a workload on a fast system, tuning the stall-warning
- timeout down to just barely avoid RCU CPU stall warnings, and then
- running the same workload with the same stall-warning timeout on a
- slow system. Note that thermal throttling and on-demand governors
- can cause a single system to be sometimes fast and sometimes slow!
-
-o A hardware or software issue shuts off the scheduler-clock
- interrupt on a CPU that is not in dyntick-idle mode. This
- problem really has happened, and seems to be most likely to
- result in RCU CPU stall warnings for CONFIG_NO_HZ_COMMON=n kernels.
-
-o A bug in the RCU implementation.
-
-o A hardware failure. This is quite unlikely, but has occurred
- at least once in real life. A CPU failed in a running system,
- becoming unresponsive, but not causing an immediate crash.
- This resulted in a series of RCU CPU stall warnings, eventually
- leading the realization that the CPU had failed.
-
-The RCU, RCU-sched, and RCU-tasks implementations have CPU stall warning.
-Note that SRCU does -not- have CPU stall warnings. Please note that
-RCU only detects CPU stalls when there is a grace period in progress.
-No grace period, no CPU stall warnings.
-
-To diagnose the cause of the stall, inspect the stack traces.
-The offending function will usually be near the top of the stack.
-If you have a series of stall warnings from a single extended stall,
-comparing the stack traces can often help determine where the stall
-is occurring, which will usually be in the function nearest the top of
-that portion of the stack which remains the same from trace to trace.
-If you can reliably trigger the stall, ftrace can be quite helpful.
-
-RCU bugs can often be debugged with the help of CONFIG_RCU_TRACE
-and with RCU's event tracing. For information on RCU's event tracing,
-see include/trace/events/rcu.h.
-
-
-Fine-Tuning the RCU CPU Stall Detector
-
-The rcuupdate.rcu_cpu_stall_suppress module parameter disables RCU's
-CPU stall detector, which detects conditions that unduly delay RCU grace
-periods. This module parameter enables CPU stall detection by default,
-but may be overridden via boot-time parameter or at runtime via sysfs.
-The stall detector's idea of what constitutes "unduly delayed" is
-controlled by a set of kernel configuration variables and cpp macros:
-
-CONFIG_RCU_CPU_STALL_TIMEOUT
-
- This kernel configuration parameter defines the period of time
- that RCU will wait from the beginning of a grace period until it
- issues an RCU CPU stall warning. This time period is normally
- 21 seconds.
-
- This configuration parameter may be changed at runtime via the
- /sys/module/rcupdate/parameters/rcu_cpu_stall_timeout, however
- this parameter is checked only at the beginning of a cycle.
- So if you are 10 seconds into a 40-second stall, setting this
- sysfs parameter to (say) five will shorten the timeout for the
- -next- stall, or the following warning for the current stall
- (assuming the stall lasts long enough). It will not affect the
- timing of the next warning for the current stall.
-
- Stall-warning messages may be enabled and disabled completely via
- /sys/module/rcupdate/parameters/rcu_cpu_stall_suppress.
-
-RCU_STALL_DELAY_DELTA
-
- Although the lockdep facility is extremely useful, it does add
- some overhead. Therefore, under CONFIG_PROVE_RCU, the
- RCU_STALL_DELAY_DELTA macro allows five extra seconds before
- giving an RCU CPU stall warning message. (This is a cpp
- macro, not a kernel configuration parameter.)
-
-RCU_STALL_RAT_DELAY
-
- The CPU stall detector tries to make the offending CPU print its
- own warnings, as this often gives better-quality stack traces.
- However, if the offending CPU does not detect its own stall in
- the number of jiffies specified by RCU_STALL_RAT_DELAY, then
- some other CPU will complain. This delay is normally set to
- two jiffies. (This is a cpp macro, not a kernel configuration
- parameter.)
-
-rcupdate.rcu_task_stall_timeout
-
- This boot/sysfs parameter controls the RCU-tasks stall warning
- interval. A value of zero or less suppresses RCU-tasks stall
- warnings. A positive value sets the stall-warning interval
- in seconds. An RCU-tasks stall warning starts with the line:
-
- INFO: rcu_tasks detected stalls on tasks:
-
- And continues with the output of sched_show_task() for each
- task stalling the current RCU-tasks grace period.
-
-
-Interpreting RCU's CPU Stall-Detector "Splats"
-
-For non-RCU-tasks flavors of RCU, when a CPU detects that it is stalling,
-it will print a message similar to the following:
-
- INFO: rcu_sched detected stalls on CPUs/tasks:
- 2-...: (3 GPs behind) idle=06c/0/0 softirq=1453/1455 fqs=0
- 16-...: (0 ticks this GP) idle=81c/0/0 softirq=764/764 fqs=0
- (detected by 32, t=2603 jiffies, g=7075, q=625)
-
-This message indicates that CPU 32 detected that CPUs 2 and 16 were both
-causing stalls, and that the stall was affecting RCU-sched. This message
-will normally be followed by stack dumps for each CPU. Please note that
-PREEMPT_RCU builds can be stalled by tasks as well as by CPUs, and that
-the tasks will be indicated by PID, for example, "P3421". It is even
-possible for an rcu_state stall to be caused by both CPUs -and- tasks,
-in which case the offending CPUs and tasks will all be called out in the list.
-
-CPU 2's "(3 GPs behind)" indicates that this CPU has not interacted with
-the RCU core for the past three grace periods. In contrast, CPU 16's "(0
-ticks this GP)" indicates that this CPU has not taken any scheduling-clock
-interrupts during the current stalled grace period.
-
-The "idle=" portion of the message prints the dyntick-idle state.
-The hex number before the first "/" is the low-order 12 bits of the
-dynticks counter, which will have an even-numbered value if the CPU
-is in dyntick-idle mode and an odd-numbered value otherwise. The hex
-number between the two "/"s is the value of the nesting, which will be
-a small non-negative number if in the idle loop (as shown above) and a
-very large positive number otherwise.
-
-The "softirq=" portion of the message tracks the number of RCU softirq
-handlers that the stalled CPU has executed. The number before the "/"
-is the number that had executed since boot at the time that this CPU
-last noted the beginning of a grace period, which might be the current
-(stalled) grace period, or it might be some earlier grace period (for
-example, if the CPU might have been in dyntick-idle mode for an extended
-time period. The number after the "/" is the number that have executed
-since boot until the current time. If this latter number stays constant
-across repeated stall-warning messages, it is possible that RCU's softirq
-handlers are no longer able to execute on this CPU. This can happen if
-the stalled CPU is spinning with interrupts are disabled, or, in -rt
-kernels, if a high-priority process is starving RCU's softirq handler.
-
-The "fqs=" shows the number of force-quiescent-state idle/offline
-detection passes that the grace-period kthread has made across this
-CPU since the last time that this CPU noted the beginning of a grace
-period.
-
-The "detected by" line indicates which CPU detected the stall (in this
-case, CPU 32), how many jiffies have elapsed since the start of the grace
-period (in this case 2603), the grace-period sequence number (7075), and
-an estimate of the total number of RCU callbacks queued across all CPUs
-(625 in this case).
-
-In kernels with CONFIG_RCU_FAST_NO_HZ, more information is printed
-for each CPU:
-
- 0: (64628 ticks this GP) idle=dd5/3fffffffffffffff/0 softirq=82/543 last_accelerate: a345/d342 dyntick_enabled: 1
-
-The "last_accelerate:" prints the low-order 16 bits (in hex) of the
-jiffies counter when this CPU last invoked rcu_try_advance_all_cbs()
-from rcu_needs_cpu() or last invoked rcu_accelerate_cbs() from
-rcu_prepare_for_idle(). "dyntick_enabled: 1" indicates that dyntick-idle
-processing is enabled.
-
-If the grace period ends just as the stall warning starts printing,
-there will be a spurious stall-warning message, which will include
-the following:
-
- INFO: Stall ended before state dump start
-
-This is rare, but does happen from time to time in real life. It is also
-possible for a zero-jiffy stall to be flagged in this case, depending
-on how the stall warning and the grace-period initialization happen to
-interact. Please note that it is not possible to entirely eliminate this
-sort of false positive without resorting to things like stop_machine(),
-which is overkill for this sort of problem.
-
-If all CPUs and tasks have passed through quiescent states, but the
-grace period has nevertheless failed to end, the stall-warning splat
-will include something like the following:
-
- All QSes seen, last rcu_preempt kthread activity 23807 (4297905177-4297881370), jiffies_till_next_fqs=3, root ->qsmask 0x0
-
-The "23807" indicates that it has been more than 23 thousand jiffies
-since the grace-period kthread ran. The "jiffies_till_next_fqs"
-indicates how frequently that kthread should run, giving the number
-of jiffies between force-quiescent-state scans, in this case three,
-which is way less than 23807. Finally, the root rcu_node structure's
-->qsmask field is printed, which will normally be zero.
-
-If the relevant grace-period kthread has been unable to run prior to
-the stall warning, as was the case in the "All QSes seen" line above,
-the following additional line is printed:
-
- kthread starved for 23807 jiffies! g7075 f0x0 RCU_GP_WAIT_FQS(3) ->state=0x1 ->cpu=5
-
-Starving the grace-period kthreads of CPU time can of course result
-in RCU CPU stall warnings even when all CPUs and tasks have passed
-through the required quiescent states. The "g" number shows the current
-grace-period sequence number, the "f" precedes the ->gp_flags command
-to the grace-period kthread, the "RCU_GP_WAIT_FQS" indicates that the
-kthread is waiting for a short timeout, the "state" precedes value of the
-task_struct ->state field, and the "cpu" indicates that the grace-period
-kthread last ran on CPU 5.
-
-
-Multiple Warnings From One Stall
-
-If a stall lasts long enough, multiple stall-warning messages will be
-printed for it. The second and subsequent messages are printed at
-longer intervals, so that the time between (say) the first and second
-message will be about three times the interval between the beginning
-of the stall and the first message.
-
-
-Stall Warnings for Expedited Grace Periods
-
-If an expedited grace period detects a stall, it will place a message
-like the following in dmesg:
-
- INFO: rcu_sched detected expedited stalls on CPUs/tasks: { 7-... } 21119 jiffies s: 73 root: 0x2/.
-
-This indicates that CPU 7 has failed to respond to a reschedule IPI.
-The three periods (".") following the CPU number indicate that the CPU
-is online (otherwise the first period would instead have been "O"),
-that the CPU was online at the beginning of the expedited grace period
-(otherwise the second period would have instead been "o"), and that
-the CPU has been online at least once since boot (otherwise, the third
-period would instead have been "N"). The number before the "jiffies"
-indicates that the expedited grace period has been going on for 21,119
-jiffies. The number following the "s:" indicates that the expedited
-grace-period sequence counter is 73. The fact that this last value is
-odd indicates that an expedited grace period is in flight. The number
-following "root:" is a bitmask that indicates which children of the root
-rcu_node structure correspond to CPUs and/or tasks that are blocking the
-current expedited grace period. If the tree had more than one level,
-additional hex numbers would be printed for the states of the other
-rcu_node structures in the tree.
-
-As with normal grace periods, PREEMPT_RCU builds can be stalled by
-tasks as well as by CPUs, and that the tasks will be indicated by PID,
-for example, "P3421".
-
-It is entirely possible to see stall warnings from normal and from
-expedited grace periods at about the same time during the same run.
diff --git a/Documentation/RCU/torture.rst b/Documentation/RCU/torture.rst
new file mode 100644
index 0000000..a901477
--- /dev/null
+++ b/Documentation/RCU/torture.rst
@@ -0,0 +1,293 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+==========================
+RCU Torture Test Operation
+==========================
+
+
+CONFIG_RCU_TORTURE_TEST
+=======================
+
+The CONFIG_RCU_TORTURE_TEST config option is available for all RCU
+implementations. It creates an rcutorture kernel module that can
+be loaded to run a torture test. The test periodically outputs
+status messages via printk(), which can be examined via the dmesg
+command (perhaps grepping for "torture"). The test is started
+when the module is loaded, and stops when the module is unloaded.
+
+Module parameters are prefixed by "rcutorture." in
+Documentation/admin-guide/kernel-parameters.txt.
+
+Output
+======
+
+The statistics output is as follows::
+
+ rcu-torture:--- Start of test: nreaders=16 nfakewriters=4 stat_interval=30 verbose=0 test_no_idle_hz=1 shuffle_interval=3 stutter=5 irqreader=1 fqs_duration=0 fqs_holdoff=0 fqs_stutter=3 test_boost=1/0 test_boost_interval=7 test_boost_duration=4
+ rcu-torture: rtc: (null) ver: 155441 tfle: 0 rta: 155441 rtaf: 8884 rtf: 155440 rtmbe: 0 rtbe: 0 rtbke: 0 rtbre: 0 rtbf: 0 rtb: 0 nt: 3055767
+ rcu-torture: Reader Pipe: 727860534 34213 0 0 0 0 0 0 0 0 0
+ rcu-torture: Reader Batch: 727877838 17003 0 0 0 0 0 0 0 0 0
+ rcu-torture: Free-Block Circulation: 155440 155440 155440 155440 155440 155440 155440 155440 155440 155440 0
+ rcu-torture:--- End of test: SUCCESS: nreaders=16 nfakewriters=4 stat_interval=30 verbose=0 test_no_idle_hz=1 shuffle_interval=3 stutter=5 irqreader=1 fqs_duration=0 fqs_holdoff=0 fqs_stutter=3 test_boost=1/0 test_boost_interval=7 test_boost_duration=4
+
+The command "dmesg | grep torture:" will extract this information on
+most systems. On more esoteric configurations, it may be necessary to
+use other commands to access the output of the printk()s used by
+the RCU torture test. The printk()s use KERN_ALERT, so they should
+be evident. ;-)
+
+The first and last lines show the rcutorture module parameters, and the
+last line shows either "SUCCESS" or "FAILURE", based on rcutorture's
+automatic determination as to whether RCU operated correctly.
+
+The entries are as follows:
+
+* "rtc": The hexadecimal address of the structure currently visible
+ to readers.
+
+* "ver": The number of times since boot that the RCU writer task
+ has changed the structure visible to readers.
+
+* "tfle": If non-zero, indicates that the "torture freelist"
+ containing structures to be placed into the "rtc" area is empty.
+ This condition is important, since it can fool you into thinking
+ that RCU is working when it is not. :-/
+
+* "rta": Number of structures allocated from the torture freelist.
+
+* "rtaf": Number of allocations from the torture freelist that have
+ failed due to the list being empty. It is not unusual for this
+ to be non-zero, but it is bad for it to be a large fraction of
+ the value indicated by "rta".
+
+* "rtf": Number of frees into the torture freelist.
+
+* "rtmbe": A non-zero value indicates that rcutorture believes that
+ rcu_assign_pointer() and rcu_dereference() are not working
+ correctly. This value should be zero.
+
+* "rtbe": A non-zero value indicates that one of the rcu_barrier()
+ family of functions is not working correctly.
+
+* "rtbke": rcutorture was unable to create the real-time kthreads
+ used to force RCU priority inversion. This value should be zero.
+
+* "rtbre": Although rcutorture successfully created the kthreads
+ used to force RCU priority inversion, it was unable to set them
+ to the real-time priority level of 1. This value should be zero.
+
+* "rtbf": The number of times that RCU priority boosting failed
+ to resolve RCU priority inversion.
+
+* "rtb": The number of times that rcutorture attempted to force
+ an RCU priority inversion condition. If you are testing RCU
+ priority boosting via the "test_boost" module parameter, this
+ value should be non-zero.
+
+* "nt": The number of times rcutorture ran RCU read-side code from
+ within a timer handler. This value should be non-zero only
+ if you specified the "irqreader" module parameter.
+
+* "Reader Pipe": Histogram of "ages" of structures seen by readers.
+ If any entries past the first two are non-zero, RCU is broken.
+ And rcutorture prints the error flag string "!!!" to make sure
+ you notice. The age of a newly allocated structure is zero,
+ it becomes one when removed from reader visibility, and is
+ incremented once per grace period subsequently -- and is freed
+ after passing through (RCU_TORTURE_PIPE_LEN-2) grace periods.
+
+ The output displayed above was taken from a correctly working
+ RCU. If you want to see what it looks like when broken, break
+ it yourself. ;-)
+
+* "Reader Batch": Another histogram of "ages" of structures seen
+ by readers, but in terms of counter flips (or batches) rather
+ than in terms of grace periods. The legal number of non-zero
+ entries is again two. The reason for this separate view is that
+ it is sometimes easier to get the third entry to show up in the
+ "Reader Batch" list than in the "Reader Pipe" list.
+
+* "Free-Block Circulation": Shows the number of torture structures
+ that have reached a given point in the pipeline. The first element
+ should closely correspond to the number of structures allocated,
+ the second to the number that have been removed from reader view,
+ and all but the last remaining to the corresponding number of
+ passes through a grace period. The last entry should be zero,
+ as it is only incremented if a torture structure's counter
+ somehow gets incremented farther than it should.
+
+Different implementations of RCU can provide implementation-specific
+additional information. For example, Tree SRCU provides the following
+additional line::
+
+ srcud-torture: Tree SRCU per-CPU(idx=0): 0(35,-21) 1(-4,24) 2(1,1) 3(-26,20) 4(28,-47) 5(-9,4) 6(-10,14) 7(-14,11) T(1,6)
+
+This line shows the per-CPU counter state, in this case for Tree SRCU
+using a dynamically allocated srcu_struct (hence "srcud-" rather than
+"srcu-"). The numbers in parentheses are the values of the "old" and
+"current" counters for the corresponding CPU. The "idx" value maps the
+"old" and "current" values to the underlying array, and is useful for
+debugging. The final "T" entry contains the totals of the counters.
+
+Usage on Specific Kernel Builds
+===============================
+
+It is sometimes desirable to torture RCU on a specific kernel build,
+for example, when preparing to put that kernel build into production.
+In that case, the kernel should be built with CONFIG_RCU_TORTURE_TEST=m
+so that the test can be started using modprobe and terminated using rmmod.
+
+For example, the following script may be used to torture RCU::
+
+ #!/bin/sh
+
+ modprobe rcutorture
+ sleep 3600
+ rmmod rcutorture
+ dmesg | grep torture:
+
+The output can be manually inspected for the error flag of "!!!".
+One could of course create a more elaborate script that automatically
+checked for such errors. The "rmmod" command forces a "SUCCESS",
+"FAILURE", or "RCU_HOTPLUG" indication to be printk()ed. The first
+two are self-explanatory, while the last indicates that while there
+were no RCU failures, CPU-hotplug problems were detected.
+
+
+Usage on Mainline Kernels
+=========================
+
+When using rcutorture to test changes to RCU itself, it is often
+necessary to build a number of kernels in order to test that change
+across a broad range of combinations of the relevant Kconfig options
+and of the relevant kernel boot parameters. In this situation, use
+of modprobe and rmmod can be quite time-consuming and error-prone.
+
+Therefore, the tools/testing/selftests/rcutorture/bin/kvm.sh
+script is available for mainline testing for x86, arm64, and
+powerpc. By default, it will run the series of tests specified by
+tools/testing/selftests/rcutorture/configs/rcu/CFLIST, with each test
+running for 30 minutes within a guest OS using a minimal userspace
+supplied by an automatically generated initrd. After the tests are
+complete, the resulting build products and console output are analyzed
+for errors and the results of the runs are summarized.
+
+On larger systems, rcutorture testing can be accelerated by passing the
+--cpus argument to kvm.sh. For example, on a 64-CPU system, "--cpus 43"
+would use up to 43 CPUs to run tests concurrently, which as of v5.4 would
+complete all the scenarios in two batches, reducing the time to complete
+from about eight hours to about one hour (not counting the time to build
+the sixteen kernels). The "--dryrun sched" argument will not run tests,
+but rather tell you how the tests would be scheduled into batches. This
+can be useful when working out how many CPUs to specify in the --cpus
+argument.
+
+Not all changes require that all scenarios be run. For example, a change
+to Tree SRCU might run only the SRCU-N and SRCU-P scenarios using the
+--configs argument to kvm.sh as follows: "--configs 'SRCU-N SRCU-P'".
+Large systems can run multiple copies of of the full set of scenarios,
+for example, a system with 448 hardware threads can run five instances
+of the full set concurrently. To make this happen::
+
+ kvm.sh --cpus 448 --configs '5*CFLIST'
+
+Alternatively, such a system can run 56 concurrent instances of a single
+eight-CPU scenario::
+
+ kvm.sh --cpus 448 --configs '56*TREE04'
+
+Or 28 concurrent instances of each of two eight-CPU scenarios::
+
+ kvm.sh --cpus 448 --configs '28*TREE03 28*TREE04'
+
+Of course, each concurrent instance will use memory, which can be
+limited using the --memory argument, which defaults to 512M. Small
+values for memory may require disabling the callback-flooding tests
+using the --bootargs parameter discussed below.
+
+Sometimes additional debugging is useful, and in such cases the --kconfig
+parameter to kvm.sh may be used, for example, ``--kconfig 'CONFIG_KASAN=y'``.
+
+Kernel boot arguments can also be supplied, for example, to control
+rcutorture's module parameters. For example, to test a change to RCU's
+CPU stall-warning code, use "--bootargs 'rcutorture.stall_cpu=30'".
+This will of course result in the scripting reporting a failure, namely
+the resuling RCU CPU stall warning. As noted above, reducing memory may
+require disabling rcutorture's callback-flooding tests::
+
+ kvm.sh --cpus 448 --configs '56*TREE04' --memory 128M \
+ --bootargs 'rcutorture.fwd_progress=0'
+
+Sometimes all that is needed is a full set of kernel builds. This is
+what the --buildonly argument does.
+
+Finally, the --trust-make argument allows each kernel build to reuse what
+it can from the previous kernel build.
+
+There are additional more arcane arguments that are documented in the
+source code of the kvm.sh script.
+
+If a run contains failures, the number of buildtime and runtime failures
+is listed at the end of the kvm.sh output, which you really should redirect
+to a file. The build products and console output of each run is kept in
+tools/testing/selftests/rcutorture/res in timestamped directories. A
+given directory can be supplied to kvm-find-errors.sh in order to have
+it cycle you through summaries of errors and full error logs. For example::
+
+ tools/testing/selftests/rcutorture/bin/kvm-find-errors.sh \
+ tools/testing/selftests/rcutorture/res/2020.01.20-15.54.23
+
+However, it is often more convenient to access the files directly.
+Files pertaining to all scenarios in a run reside in the top-level
+directory (2020.01.20-15.54.23 in the example above), while per-scenario
+files reside in a subdirectory named after the scenario (for example,
+"TREE04"). If a given scenario ran more than once (as in "--configs
+'56*TREE04'" above), the directories corresponding to the second and
+subsequent runs of that scenario include a sequence number, for example,
+"TREE04.2", "TREE04.3", and so on.
+
+The most frequently used file in the top-level directory is testid.txt.
+If the test ran in a git repository, then this file contains the commit
+that was tested and any uncommitted changes in diff format.
+
+The most frequently used files in each per-scenario-run directory are:
+
+.config:
+ This file contains the Kconfig options.
+
+Make.out:
+ This contains build output for a specific scenario.
+
+console.log:
+ This contains the console output for a specific scenario.
+ This file may be examined once the kernel has booted, but
+ it might not exist if the build failed.
+
+vmlinux:
+ This contains the kernel, which can be useful with tools like
+ objdump and gdb.
+
+A number of additional files are available, but are less frequently used.
+Many are intended for debugging of rcutorture itself or of its scripting.
+
+As of v5.4, a successful run with the default set of scenarios produces
+the following summary at the end of the run on a 12-CPU system::
+
+ SRCU-N ------- 804233 GPs (148.932/s) [srcu: g10008272 f0x0 ]
+ SRCU-P ------- 202320 GPs (37.4667/s) [srcud: g1809476 f0x0 ]
+ SRCU-t ------- 1122086 GPs (207.794/s) [srcu: g0 f0x0 ]
+ SRCU-u ------- 1111285 GPs (205.794/s) [srcud: g1 f0x0 ]
+ TASKS01 ------- 19666 GPs (3.64185/s) [tasks: g0 f0x0 ]
+ TASKS02 ------- 20541 GPs (3.80389/s) [tasks: g0 f0x0 ]
+ TASKS03 ------- 19416 GPs (3.59556/s) [tasks: g0 f0x0 ]
+ TINY01 ------- 836134 GPs (154.84/s) [rcu: g0 f0x0 ] n_max_cbs: 34198
+ TINY02 ------- 850371 GPs (157.476/s) [rcu: g0 f0x0 ] n_max_cbs: 2631
+ TREE01 ------- 162625 GPs (30.1157/s) [rcu: g1124169 f0x0 ]
+ TREE02 ------- 333003 GPs (61.6672/s) [rcu: g2647753 f0x0 ] n_max_cbs: 35844
+ TREE03 ------- 306623 GPs (56.782/s) [rcu: g2975325 f0x0 ] n_max_cbs: 1496497
+ CPU count limited from 16 to 12
+ TREE04 ------- 246149 GPs (45.5831/s) [rcu: g1695737 f0x0 ] n_max_cbs: 434961
+ TREE05 ------- 314603 GPs (58.2598/s) [rcu: g2257741 f0x2 ] n_max_cbs: 193997
+ TREE07 ------- 167347 GPs (30.9902/s) [rcu: g1079021 f0x0 ] n_max_cbs: 478732
+ CPU count limited from 16 to 12
+ TREE09 ------- 752238 GPs (139.303/s) [rcu: g13075057 f0x0 ] n_max_cbs: 99011
diff --git a/Documentation/RCU/torture.txt b/Documentation/RCU/torture.txt
deleted file mode 100644
index af712a3..0000000
--- a/Documentation/RCU/torture.txt
+++ /dev/null
@@ -1,282 +0,0 @@
-RCU Torture Test Operation
-
-
-CONFIG_RCU_TORTURE_TEST
-
-The CONFIG_RCU_TORTURE_TEST config option is available for all RCU
-implementations. It creates an rcutorture kernel module that can
-be loaded to run a torture test. The test periodically outputs
-status messages via printk(), which can be examined via the dmesg
-command (perhaps grepping for "torture"). The test is started
-when the module is loaded, and stops when the module is unloaded.
-
-Module parameters are prefixed by "rcutorture." in
-Documentation/admin-guide/kernel-parameters.txt.
-
-OUTPUT
-
-The statistics output is as follows:
-
- rcu-torture:--- Start of test: nreaders=16 nfakewriters=4 stat_interval=30 verbose=0 test_no_idle_hz=1 shuffle_interval=3 stutter=5 irqreader=1 fqs_duration=0 fqs_holdoff=0 fqs_stutter=3 test_boost=1/0 test_boost_interval=7 test_boost_duration=4
- rcu-torture: rtc: (null) ver: 155441 tfle: 0 rta: 155441 rtaf: 8884 rtf: 155440 rtmbe: 0 rtbe: 0 rtbke: 0 rtbre: 0 rtbf: 0 rtb: 0 nt: 3055767
- rcu-torture: Reader Pipe: 727860534 34213 0 0 0 0 0 0 0 0 0
- rcu-torture: Reader Batch: 727877838 17003 0 0 0 0 0 0 0 0 0
- rcu-torture: Free-Block Circulation: 155440 155440 155440 155440 155440 155440 155440 155440 155440 155440 0
- rcu-torture:--- End of test: SUCCESS: nreaders=16 nfakewriters=4 stat_interval=30 verbose=0 test_no_idle_hz=1 shuffle_interval=3 stutter=5 irqreader=1 fqs_duration=0 fqs_holdoff=0 fqs_stutter=3 test_boost=1/0 test_boost_interval=7 test_boost_duration=4
-
-The command "dmesg | grep torture:" will extract this information on
-most systems. On more esoteric configurations, it may be necessary to
-use other commands to access the output of the printk()s used by
-the RCU torture test. The printk()s use KERN_ALERT, so they should
-be evident. ;-)
-
-The first and last lines show the rcutorture module parameters, and the
-last line shows either "SUCCESS" or "FAILURE", based on rcutorture's
-automatic determination as to whether RCU operated correctly.
-
-The entries are as follows:
-
-o "rtc": The hexadecimal address of the structure currently visible
- to readers.
-
-o "ver": The number of times since boot that the RCU writer task
- has changed the structure visible to readers.
-
-o "tfle": If non-zero, indicates that the "torture freelist"
- containing structures to be placed into the "rtc" area is empty.
- This condition is important, since it can fool you into thinking
- that RCU is working when it is not. :-/
-
-o "rta": Number of structures allocated from the torture freelist.
-
-o "rtaf": Number of allocations from the torture freelist that have
- failed due to the list being empty. It is not unusual for this
- to be non-zero, but it is bad for it to be a large fraction of
- the value indicated by "rta".
-
-o "rtf": Number of frees into the torture freelist.
-
-o "rtmbe": A non-zero value indicates that rcutorture believes that
- rcu_assign_pointer() and rcu_dereference() are not working
- correctly. This value should be zero.
-
-o "rtbe": A non-zero value indicates that one of the rcu_barrier()
- family of functions is not working correctly.
-
-o "rtbke": rcutorture was unable to create the real-time kthreads
- used to force RCU priority inversion. This value should be zero.
-
-o "rtbre": Although rcutorture successfully created the kthreads
- used to force RCU priority inversion, it was unable to set them
- to the real-time priority level of 1. This value should be zero.
-
-o "rtbf": The number of times that RCU priority boosting failed
- to resolve RCU priority inversion.
-
-o "rtb": The number of times that rcutorture attempted to force
- an RCU priority inversion condition. If you are testing RCU
- priority boosting via the "test_boost" module parameter, this
- value should be non-zero.
-
-o "nt": The number of times rcutorture ran RCU read-side code from
- within a timer handler. This value should be non-zero only
- if you specified the "irqreader" module parameter.
-
-o "Reader Pipe": Histogram of "ages" of structures seen by readers.
- If any entries past the first two are non-zero, RCU is broken.
- And rcutorture prints the error flag string "!!!" to make sure
- you notice. The age of a newly allocated structure is zero,
- it becomes one when removed from reader visibility, and is
- incremented once per grace period subsequently -- and is freed
- after passing through (RCU_TORTURE_PIPE_LEN-2) grace periods.
-
- The output displayed above was taken from a correctly working
- RCU. If you want to see what it looks like when broken, break
- it yourself. ;-)
-
-o "Reader Batch": Another histogram of "ages" of structures seen
- by readers, but in terms of counter flips (or batches) rather
- than in terms of grace periods. The legal number of non-zero
- entries is again two. The reason for this separate view is that
- it is sometimes easier to get the third entry to show up in the
- "Reader Batch" list than in the "Reader Pipe" list.
-
-o "Free-Block Circulation": Shows the number of torture structures
- that have reached a given point in the pipeline. The first element
- should closely correspond to the number of structures allocated,
- the second to the number that have been removed from reader view,
- and all but the last remaining to the corresponding number of
- passes through a grace period. The last entry should be zero,
- as it is only incremented if a torture structure's counter
- somehow gets incremented farther than it should.
-
-Different implementations of RCU can provide implementation-specific
-additional information. For example, Tree SRCU provides the following
-additional line:
-
- srcud-torture: Tree SRCU per-CPU(idx=0): 0(35,-21) 1(-4,24) 2(1,1) 3(-26,20) 4(28,-47) 5(-9,4) 6(-10,14) 7(-14,11) T(1,6)
-
-This line shows the per-CPU counter state, in this case for Tree SRCU
-using a dynamically allocated srcu_struct (hence "srcud-" rather than
-"srcu-"). The numbers in parentheses are the values of the "old" and
-"current" counters for the corresponding CPU. The "idx" value maps the
-"old" and "current" values to the underlying array, and is useful for
-debugging. The final "T" entry contains the totals of the counters.
-
-
-USAGE ON SPECIFIC KERNEL BUILDS
-
-It is sometimes desirable to torture RCU on a specific kernel build,
-for example, when preparing to put that kernel build into production.
-In that case, the kernel should be built with CONFIG_RCU_TORTURE_TEST=m
-so that the test can be started using modprobe and terminated using rmmod.
-
-For example, the following script may be used to torture RCU:
-
- #!/bin/sh
-
- modprobe rcutorture
- sleep 3600
- rmmod rcutorture
- dmesg | grep torture:
-
-The output can be manually inspected for the error flag of "!!!".
-One could of course create a more elaborate script that automatically
-checked for such errors. The "rmmod" command forces a "SUCCESS",
-"FAILURE", or "RCU_HOTPLUG" indication to be printk()ed. The first
-two are self-explanatory, while the last indicates that while there
-were no RCU failures, CPU-hotplug problems were detected.
-
-
-USAGE ON MAINLINE KERNELS
-
-When using rcutorture to test changes to RCU itself, it is often
-necessary to build a number of kernels in order to test that change
-across a broad range of combinations of the relevant Kconfig options
-and of the relevant kernel boot parameters. In this situation, use
-of modprobe and rmmod can be quite time-consuming and error-prone.
-
-Therefore, the tools/testing/selftests/rcutorture/bin/kvm.sh
-script is available for mainline testing for x86, arm64, and
-powerpc. By default, it will run the series of tests specified by
-tools/testing/selftests/rcutorture/configs/rcu/CFLIST, with each test
-running for 30 minutes within a guest OS using a minimal userspace
-supplied by an automatically generated initrd. After the tests are
-complete, the resulting build products and console output are analyzed
-for errors and the results of the runs are summarized.
-
-On larger systems, rcutorture testing can be accelerated by passing the
---cpus argument to kvm.sh. For example, on a 64-CPU system, "--cpus 43"
-would use up to 43 CPUs to run tests concurrently, which as of v5.4 would
-complete all the scenarios in two batches, reducing the time to complete
-from about eight hours to about one hour (not counting the time to build
-the sixteen kernels). The "--dryrun sched" argument will not run tests,
-but rather tell you how the tests would be scheduled into batches. This
-can be useful when working out how many CPUs to specify in the --cpus
-argument.
-
-Not all changes require that all scenarios be run. For example, a change
-to Tree SRCU might run only the SRCU-N and SRCU-P scenarios using the
---configs argument to kvm.sh as follows: "--configs 'SRCU-N SRCU-P'".
-Large systems can run multiple copies of of the full set of scenarios,
-for example, a system with 448 hardware threads can run five instances
-of the full set concurrently. To make this happen:
-
- kvm.sh --cpus 448 --configs '5*CFLIST'
-
-Alternatively, such a system can run 56 concurrent instances of a single
-eight-CPU scenario:
-
- kvm.sh --cpus 448 --configs '56*TREE04'
-
-Or 28 concurrent instances of each of two eight-CPU scenarios:
-
- kvm.sh --cpus 448 --configs '28*TREE03 28*TREE04'
-
-Of course, each concurrent instance will use memory, which can be
-limited using the --memory argument, which defaults to 512M. Small
-values for memory may require disabling the callback-flooding tests
-using the --bootargs parameter discussed below.
-
-Sometimes additional debugging is useful, and in such cases the --kconfig
-parameter to kvm.sh may be used, for example, "--kconfig 'CONFIG_KASAN=y'".
-
-Kernel boot arguments can also be supplied, for example, to control
-rcutorture's module parameters. For example, to test a change to RCU's
-CPU stall-warning code, use "--bootargs 'rcutorture.stall_cpu=30'".
-This will of course result in the scripting reporting a failure, namely
-the resuling RCU CPU stall warning. As noted above, reducing memory may
-require disabling rcutorture's callback-flooding tests:
-
- kvm.sh --cpus 448 --configs '56*TREE04' --memory 128M \
- --bootargs 'rcutorture.fwd_progress=0'
-
-Sometimes all that is needed is a full set of kernel builds. This is
-what the --buildonly argument does.
-
-Finally, the --trust-make argument allows each kernel build to reuse what
-it can from the previous kernel build.
-
-There are additional more arcane arguments that are documented in the
-source code of the kvm.sh script.
-
-If a run contains failures, the number of buildtime and runtime failures
-is listed at the end of the kvm.sh output, which you really should redirect
-to a file. The build products and console output of each run is kept in
-tools/testing/selftests/rcutorture/res in timestamped directories. A
-given directory can be supplied to kvm-find-errors.sh in order to have
-it cycle you through summaries of errors and full error logs. For example:
-
- tools/testing/selftests/rcutorture/bin/kvm-find-errors.sh \
- tools/testing/selftests/rcutorture/res/2020.01.20-15.54.23
-
-However, it is often more convenient to access the files directly.
-Files pertaining to all scenarios in a run reside in the top-level
-directory (2020.01.20-15.54.23 in the example above), while per-scenario
-files reside in a subdirectory named after the scenario (for example,
-"TREE04"). If a given scenario ran more than once (as in "--configs
-'56*TREE04'" above), the directories corresponding to the second and
-subsequent runs of that scenario include a sequence number, for example,
-"TREE04.2", "TREE04.3", and so on.
-
-The most frequently used file in the top-level directory is testid.txt.
-If the test ran in a git repository, then this file contains the commit
-that was tested and any uncommitted changes in diff format.
-
-The most frequently used files in each per-scenario-run directory are:
-
-.config: This file contains the Kconfig options.
-
-Make.out: This contains build output for a specific scenario.
-
-console.log: This contains the console output for a specific scenario.
- This file may be examined once the kernel has booted, but
- it might not exist if the build failed.
-
-vmlinux: This contains the kernel, which can be useful with tools like
- objdump and gdb.
-
-A number of additional files are available, but are less frequently used.
-Many are intended for debugging of rcutorture itself or of its scripting.
-
-As of v5.4, a successful run with the default set of scenarios produces
-the following summary at the end of the run on a 12-CPU system:
-
-SRCU-N ------- 804233 GPs (148.932/s) [srcu: g10008272 f0x0 ]
-SRCU-P ------- 202320 GPs (37.4667/s) [srcud: g1809476 f0x0 ]
-SRCU-t ------- 1122086 GPs (207.794/s) [srcu: g0 f0x0 ]
-SRCU-u ------- 1111285 GPs (205.794/s) [srcud: g1 f0x0 ]
-TASKS01 ------- 19666 GPs (3.64185/s) [tasks: g0 f0x0 ]
-TASKS02 ------- 20541 GPs (3.80389/s) [tasks: g0 f0x0 ]
-TASKS03 ------- 19416 GPs (3.59556/s) [tasks: g0 f0x0 ]
-TINY01 ------- 836134 GPs (154.84/s) [rcu: g0 f0x0 ] n_max_cbs: 34198
-TINY02 ------- 850371 GPs (157.476/s) [rcu: g0 f0x0 ] n_max_cbs: 2631
-TREE01 ------- 162625 GPs (30.1157/s) [rcu: g1124169 f0x0 ]
-TREE02 ------- 333003 GPs (61.6672/s) [rcu: g2647753 f0x0 ] n_max_cbs: 35844
-TREE03 ------- 306623 GPs (56.782/s) [rcu: g2975325 f0x0 ] n_max_cbs: 1496497
-CPU count limited from 16 to 12
-TREE04 ------- 246149 GPs (45.5831/s) [rcu: g1695737 f0x0 ] n_max_cbs: 434961
-TREE05 ------- 314603 GPs (58.2598/s) [rcu: g2257741 f0x2 ] n_max_cbs: 193997
-TREE07 ------- 167347 GPs (30.9902/s) [rcu: g1079021 f0x0 ] n_max_cbs: 478732
-CPU count limited from 16 to 12
-TREE09 ------- 752238 GPs (139.303/s) [rcu: g13075057 f0x0 ] n_max_cbs: 99011
diff --git a/Documentation/admin-guide/LSM/Yama.rst b/Documentation/admin-guide/LSM/Yama.rst
index d0a060d..d9cd937 100644
--- a/Documentation/admin-guide/LSM/Yama.rst
+++ b/Documentation/admin-guide/LSM/Yama.rst
@@ -19,9 +19,10 @@
etc) to extract additional credentials and continue to expand the scope
of their attack without resorting to user-assisted phishing.
-This is not a theoretical problem. SSH session hijacking
-(http://www.storm.net.nz/projects/7) and arbitrary code injection
-(http://c-skills.blogspot.com/2007/05/injectso.html) attacks already
+This is not a theoretical problem. `SSH session hijacking
+<https://www.blackhat.com/presentations/bh-usa-05/bh-us-05-boileau.pdf>`_
+and `arbitrary code injection
+<https://c-skills.blogspot.com/2007/05/injectso.html>`_ attacks already
exist and remain possible if ptrace is allowed to operate as before.
Since ptrace is not commonly used by non-developers and non-admins, system
builders should be allowed the option to disable this debugging system.
diff --git a/Documentation/admin-guide/README.rst b/Documentation/admin-guide/README.rst
index 5fb5269..5aad534 100644
--- a/Documentation/admin-guide/README.rst
+++ b/Documentation/admin-guide/README.rst
@@ -258,7 +258,7 @@
Compiling the kernel
--------------------
- - Make sure you have at least gcc 4.6 available.
+ - Make sure you have at least gcc 4.9 available.
For more information, refer to :ref:`Documentation/process/changes.rst <changes>`.
Please note that you can still run a.out user programs with this kernel.
diff --git a/Documentation/admin-guide/blockdev/drbd/index.rst b/Documentation/admin-guide/blockdev/drbd/index.rst
index 68ecd5c..561fd1e 100644
--- a/Documentation/admin-guide/blockdev/drbd/index.rst
+++ b/Documentation/admin-guide/blockdev/drbd/index.rst
@@ -10,7 +10,7 @@
clusters and in this context, is a "drop-in" replacement for shared
storage. Simplistically, you could see it as a network RAID 1.
- Please visit http://www.drbd.org to find out more.
+ Please visit https://www.drbd.org to find out more.
.. toctree::
:maxdepth: 1
diff --git a/Documentation/admin-guide/blockdev/floppy.rst b/Documentation/admin-guide/blockdev/floppy.rst
index 4a8f31c..0328438 100644
--- a/Documentation/admin-guide/blockdev/floppy.rst
+++ b/Documentation/admin-guide/blockdev/floppy.rst
@@ -6,7 +6,7 @@
=========
A FAQ list may be found in the fdutils package (see below), and also
-at <http://fdutils.linux.lu/faq.html>.
+at <https://fdutils.linux.lu/faq.html>.
LILO configuration options (Thinkpad users, read this)
@@ -220,11 +220,11 @@
The latest version can be found at fdutils homepage:
- http://fdutils.linux.lu
+ https://fdutils.linux.lu
The fdutils releases can be found at:
- http://fdutils.linux.lu/download.html
+ https://fdutils.linux.lu/download.html
http://www.tux.org/pub/knaff/fdutils/
diff --git a/Documentation/admin-guide/bootconfig.rst b/Documentation/admin-guide/bootconfig.rst
index d6b3b77..a22024f 100644
--- a/Documentation/admin-guide/bootconfig.rst
+++ b/Documentation/admin-guide/bootconfig.rst
@@ -71,6 +71,16 @@
foo = bar, baz
foo = qux # !ERROR! we can not re-define same key
+If you want to update the value, you must use the override operator
+``:=`` explicitly. For example::
+
+ foo = bar, baz
+ foo := qux
+
+then, the ``qux`` is assigned to ``foo`` key. This is useful for
+overriding the default value by adding (partial) custom bootconfigs
+without parsing the default bootconfig.
+
If you want to append the value to existing key as an array member,
you can use ``+=`` operator. For example::
@@ -84,6 +94,7 @@
foo = value1
foo.bar = value2 # !ERROR! subkey "bar" and value "value1" can NOT co-exist
+ foo.bar := value2 # !ERROR! even with the override operator, this is NOT allowed.
Comments
diff --git a/Documentation/admin-guide/cgroup-v1/rdma.rst b/Documentation/admin-guide/cgroup-v1/rdma.rst
index 2fcb0a9b..e69369b 100644
--- a/Documentation/admin-guide/cgroup-v1/rdma.rst
+++ b/Documentation/admin-guide/cgroup-v1/rdma.rst
@@ -114,4 +114,4 @@
(d) Delete resource limit::
- echo echo mlx4_0 hca_handle=max hca_object=max > /sys/fs/cgroup/rdma/1/rdma.max
+ echo mlx4_0 hca_handle=max hca_object=max > /sys/fs/cgroup/rdma/1/rdma.max
diff --git a/Documentation/admin-guide/cgroup-v2.rst b/Documentation/admin-guide/cgroup-v2.rst
index ce3e05e..6be4378 100644
--- a/Documentation/admin-guide/cgroup-v2.rst
+++ b/Documentation/admin-guide/cgroup-v2.rst
@@ -1274,6 +1274,10 @@
Amount of memory used for storing in-kernel data
structures.
+ percpu
+ Amount of memory used for storing per-cpu kernel
+ data structures.
+
sock
Amount of memory used in network transmission buffers
@@ -1356,8 +1360,8 @@
thp_fault_alloc
Number of transparent hugepages which were allocated to satisfy
- a page fault, including COW faults. This counter is not present
- when CONFIG_TRANSPARENT_HUGEPAGE is not set.
+ a page fault. This counter is not present when CONFIG_TRANSPARENT_HUGEPAGE
+ is not set.
thp_collapse_alloc
Number of transparent hugepages which were allocated to allow
@@ -1483,8 +1487,7 @@
~~~~~~~~~~~~~~~~~~
io.stat
- A read-only nested-keyed file which exists on non-root
- cgroups.
+ A read-only nested-keyed file.
Lines are keyed by $MAJ:$MIN device numbers and not ordered.
The following nested keys are defined.
@@ -1684,9 +1687,9 @@
of the two is enforced.
cgroup writeback requires explicit support from the underlying
-filesystem. Currently, cgroup writeback is implemented on ext2, ext4
-and btrfs. On other filesystems, all writeback IOs are attributed to
-the root cgroup.
+filesystem. Currently, cgroup writeback is implemented on ext2, ext4,
+btrfs, f2fs, and xfs. On other filesystems, all writeback IOs are
+attributed to the root cgroup.
There are inherent differences in memory and writeback management
which affects how cgroup ownership is tracked. Memory is tracked per
@@ -2043,7 +2046,7 @@
----
The "rdma" controller regulates the distribution and accounting of
-of RDMA resources.
+RDMA resources.
RDMA Interface Files
~~~~~~~~~~~~~~~~~~~~
diff --git a/Documentation/admin-guide/cifs/todo.rst b/Documentation/admin-guide/cifs/todo.rst
index 084c25f..25f1157 100644
--- a/Documentation/admin-guide/cifs/todo.rst
+++ b/Documentation/admin-guide/cifs/todo.rst
@@ -98,7 +98,7 @@
Known Bugs
==========
-See http://bugzilla.samba.org - search on product "CifsVFS" for
+See https://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
diff --git a/Documentation/admin-guide/cifs/usage.rst b/Documentation/admin-guide/cifs/usage.rst
index d3fb67b..7b32d50 100644
--- a/Documentation/admin-guide/cifs/usage.rst
+++ b/Documentation/admin-guide/cifs/usage.rst
@@ -16,8 +16,7 @@
Please see
MS-SMB2 (for detailed SMB2/SMB3/SMB3.1.1 protocol specification)
-http://protocolfreedom.org/ and
-http://samba.org/samba/PFIF/
+or https://samba.org/samba/PFIF/
for more details.
@@ -32,7 +31,7 @@
For Linux:
-1) Download the kernel (e.g. from http://www.kernel.org)
+1) Download the kernel (e.g. from https://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)
@@ -831,7 +830,7 @@
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
+project(https://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.
diff --git a/Documentation/admin-guide/cifs/winucase_convert.pl b/Documentation/admin-guide/cifs/winucase_convert.pl
index 322a9c8..993186b 100755
--- a/Documentation/admin-guide/cifs/winucase_convert.pl
+++ b/Documentation/admin-guide/cifs/winucase_convert.pl
@@ -16,7 +16,7 @@
# 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, see <http://www.gnu.org/licenses/>.
+# along with this program. If not, see <https://www.gnu.org/licenses/>.
#
while(<>) {
diff --git a/Documentation/admin-guide/dell_rbu.rst b/Documentation/admin-guide/dell_rbu.rst
index 8d70e1f..2196caf 100644
--- a/Documentation/admin-guide/dell_rbu.rst
+++ b/Documentation/admin-guide/dell_rbu.rst
@@ -26,7 +26,7 @@
OpenManage and Dell Update packages (DUP).
Libsmbios can also be used to update BIOS on Dell systems go to
-http://linux.dell.com/libsmbios/ for details.
+https://linux.dell.com/libsmbios/ for details.
Dell_RBU driver supports BIOS update using the monolithic image and packetized
image methods. In case of monolithic the driver allocates a contiguous chunk
diff --git a/Documentation/admin-guide/device-mapper/dm-dust.rst b/Documentation/admin-guide/device-mapper/dm-dust.rst
index b6e7e7e..e35ec8c 100644
--- a/Documentation/admin-guide/device-mapper/dm-dust.rst
+++ b/Documentation/admin-guide/device-mapper/dm-dust.rst
@@ -69,10 +69,11 @@
$ sudo dmsetup create dust1 --table '0 33552384 dust /dev/vdb1 0 4096'
Check the status of the read behavior ("bypass" indicates that all I/O
-will be passed through to the underlying device)::
+will be passed through to the underlying device; "verbose" indicates that
+bad block additions, removals, and remaps will be verbosely logged)::
$ sudo dmsetup status dust1
- 0 33552384 dust 252:17 bypass
+ 0 33552384 dust 252:17 bypass verbose
$ sudo dd if=/dev/mapper/dust1 of=/dev/null bs=512 count=128 iflag=direct
128+0 records in
@@ -164,7 +165,7 @@
A message will print with the number of bad blocks currently
configured on the device::
- kernel: device-mapper: dust: countbadblocks: 895 badblock(s) found
+ countbadblocks: 895 badblock(s) found
Querying for specific bad blocks
--------------------------------
@@ -176,11 +177,11 @@
The following message will print if the block is in the list::
- device-mapper: dust: queryblock: block 72 found in badblocklist
+ dust_query_block: block 72 found in badblocklist
The following message will print if the block is not in the list::
- device-mapper: dust: queryblock: block 72 not found in badblocklist
+ dust_query_block: block 72 not found in badblocklist
The "queryblock" message command will work in both the "enabled"
and "disabled" modes, allowing the verification of whether a block
@@ -198,12 +199,28 @@
After clearing the bad block list, the following message will appear::
- kernel: device-mapper: dust: clearbadblocks: badblocks cleared
+ dust_clear_badblocks: badblocks cleared
If there were no bad blocks to clear, the following message will
appear::
- kernel: device-mapper: dust: clearbadblocks: no badblocks found
+ dust_clear_badblocks: no badblocks found
+
+Listing the bad block list
+--------------------------
+
+To list all bad blocks in the bad block list (using an example device
+with blocks 1 and 2 in the bad block list), run the following message
+command::
+
+ $ sudo dmsetup message dust1 0 listbadblocks
+ 1
+ 2
+
+If there are no bad blocks in the bad block list, the command will
+execute with no output::
+
+ $ sudo dmsetup message dust1 0 listbadblocks
Message commands list
---------------------
@@ -223,6 +240,7 @@
countbadblocks
clearbadblocks
+ listbadblocks
disable
enable
quiet
diff --git a/Documentation/admin-guide/device-mapper/dm-integrity.rst b/Documentation/admin-guide/device-mapper/dm-integrity.rst
index 9edd455..3ab4f77 100644
--- a/Documentation/admin-guide/device-mapper/dm-integrity.rst
+++ b/Documentation/admin-guide/device-mapper/dm-integrity.rst
@@ -45,7 +45,7 @@
will format the device
3. unload the dm-integrity target
4. read the "provided_data_sectors" value from the superblock
-5. load the dm-integrity target with the the target size
+5. load the dm-integrity target with the target size
"provided_data_sectors"
6. if you want to use dm-integrity with dm-crypt, load the dm-crypt target
with the size "provided_data_sectors"
@@ -99,7 +99,7 @@
the superblock is used.
meta_device:device
- Don't interleave the data and metadata on on device. Use a
+ Don't interleave the data and metadata on the device. Use a
separate device for metadata.
buffer_sectors:number
diff --git a/Documentation/admin-guide/device-mapper/dm-raid.rst b/Documentation/admin-guide/device-mapper/dm-raid.rst
index 695a2ea..7ef9fe6 100644
--- a/Documentation/admin-guide/device-mapper/dm-raid.rst
+++ b/Documentation/admin-guide/device-mapper/dm-raid.rst
@@ -71,7 +71,7 @@
============= ===============================================================
Reference: Chapter 4 of
- http://www.snia.org/sites/default/files/SNIA_DDF_Technical_Position_v2.0.pdf
+ https://www.snia.org/sites/default/files/SNIA_DDF_Technical_Position_v2.0.pdf
<#raid_params>: The number of parameters that follow.
diff --git a/Documentation/admin-guide/device-mapper/dm-zoned.rst b/Documentation/admin-guide/device-mapper/dm-zoned.rst
index 553752e..e6350413 100644
--- a/Documentation/admin-guide/device-mapper/dm-zoned.rst
+++ b/Documentation/admin-guide/device-mapper/dm-zoned.rst
@@ -14,7 +14,7 @@
For a more detailed description of the zoned block device models and
their constraints see (for SCSI devices):
-http://www.t10.org/drafts.htm#ZBC_Family
+https://www.t10.org/drafts.htm#ZBC_Family
and (for ATA devices):
diff --git a/Documentation/admin-guide/device-mapper/index.rst b/Documentation/admin-guide/device-mapper/index.rst
index ec62fcc..6cf8adc 100644
--- a/Documentation/admin-guide/device-mapper/index.rst
+++ b/Documentation/admin-guide/device-mapper/index.rst
@@ -11,6 +11,7 @@
dm-clone
dm-crypt
dm-dust
+ dm-ebs
dm-flakey
dm-init
dm-integrity
diff --git a/Documentation/admin-guide/device-mapper/verity.rst b/Documentation/admin-guide/device-mapper/verity.rst
index bb02caa..66f71f0 100644
--- a/Documentation/admin-guide/device-mapper/verity.rst
+++ b/Documentation/admin-guide/device-mapper/verity.rst
@@ -83,6 +83,10 @@
not compatible with ignore_corruption and requires user space support to
avoid restart loops.
+panic_on_corruption
+ Panic the device when a corrupted block is discovered. This option is
+ not compatible with ignore_corruption and restart_on_corruption.
+
ignore_zero_blocks
Do not verify blocks that are expected to contain zeroes and always return
zeroes instead. This may be useful if the partition contains unused blocks
diff --git a/Documentation/admin-guide/devices.txt b/Documentation/admin-guide/devices.txt
index 2a97aae..d336f3f 100644
--- a/Documentation/admin-guide/devices.txt
+++ b/Documentation/admin-guide/devices.txt
@@ -375,8 +375,9 @@
239 = /dev/uhid User-space I/O driver support for HID subsystem
240 = /dev/userio Serio driver testing device
241 = /dev/vhost-vsock Host kernel driver for virtio vsock
+ 242 = /dev/rfkill Turning off radio transmissions (rfkill)
- 242-254 Reserved for local use
+ 243-254 Reserved for local use
255 Reserved for MISC_DYNAMIC_MINOR
11 char Raw keyboard device (Linux/SPARC only)
@@ -1442,7 +1443,7 @@
...
The driver and documentation may be obtained from
- http://www.winradio.com/
+ https://www.winradio.com/
82 block I2O hard disk
0 = /dev/i2o/hdag 33rd I2O hard disk, whole disk
@@ -1656,7 +1657,7 @@
dynamically, so there is no fixed mapping from subdevice
pathnames to minor numbers.
- See http://www.comedi.org/ for information about the Comedi
+ See https://www.comedi.org/ for information about the Comedi
project.
98 block User-mode virtual block device
@@ -1723,7 +1724,7 @@
implementations a kernel presence for caching and easy
mounting. For more information about the project,
write to <arla-drinkers@stacken.kth.se> or see
- http://www.stacken.kth.se/project/arla/
+ https://www.stacken.kth.se/project/arla/
103 block Audit device
0 = /dev/audit Audit device
diff --git a/Documentation/admin-guide/dynamic-debug-howto.rst b/Documentation/admin-guide/dynamic-debug-howto.rst
index 1012bd9..e5a8def 100644
--- a/Documentation/admin-guide/dynamic-debug-howto.rst
+++ b/Documentation/admin-guide/dynamic-debug-howto.rst
@@ -70,10 +70,10 @@
nullarbor:~ # cat <debugfs>/dynamic_debug/control
# filename:lineno [module]function flags format
- /usr/src/packages/BUILD/sgi-enhancednfs-1.4/default/net/sunrpc/svc_rdma.c:323 [svcxprt_rdma]svc_rdma_cleanup =_ "SVCRDMA Module Removed, deregister RPC RDMA transport\012"
- /usr/src/packages/BUILD/sgi-enhancednfs-1.4/default/net/sunrpc/svc_rdma.c:341 [svcxprt_rdma]svc_rdma_init =_ "\011max_inline : %d\012"
- /usr/src/packages/BUILD/sgi-enhancednfs-1.4/default/net/sunrpc/svc_rdma.c:340 [svcxprt_rdma]svc_rdma_init =_ "\011sq_depth : %d\012"
- /usr/src/packages/BUILD/sgi-enhancednfs-1.4/default/net/sunrpc/svc_rdma.c:338 [svcxprt_rdma]svc_rdma_init =_ "\011max_requests : %d\012"
+ net/sunrpc/svc_rdma.c:323 [svcxprt_rdma]svc_rdma_cleanup =_ "SVCRDMA Module Removed, deregister RPC RDMA transport\012"
+ net/sunrpc/svc_rdma.c:341 [svcxprt_rdma]svc_rdma_init =_ "\011max_inline : %d\012"
+ net/sunrpc/svc_rdma.c:340 [svcxprt_rdma]svc_rdma_init =_ "\011sq_depth : %d\012"
+ net/sunrpc/svc_rdma.c:338 [svcxprt_rdma]svc_rdma_init =_ "\011max_requests : %d\012"
...
@@ -93,7 +93,7 @@
nullarbor:~ # awk '$3 != "=_"' <debugfs>/dynamic_debug/control
# filename:lineno [module]function flags format
- /usr/src/packages/BUILD/sgi-enhancednfs-1.4/default/net/sunrpc/svcsock.c:1603 [sunrpc]svc_send p "svc_process: st_sendto returned %d\012"
+ net/sunrpc/svcsock.c:1603 [sunrpc]svc_send p "svc_process: st_sendto returned %d\012"
Command Language Reference
==========================
@@ -156,6 +156,7 @@
``line-range`` cannot contain space, e.g.
"1-30" is valid range but "1 - 30" is not.
+ ``module=foo`` combined keyword=value form is interchangably accepted
The meanings of each keyword are:
@@ -164,15 +165,18 @@
of each callsite. Example::
func svc_tcp_accept
+ func *recv* # in rfcomm, bluetooth, ping, tcp
file
- The given string is compared against either the full pathname, the
- src-root relative pathname, or the basename of the source file of
- each callsite. Examples::
+ The given string is compared against either the src-root relative
+ pathname, or the basename of the source file of each callsite.
+ Examples::
file svcsock.c
- file kernel/freezer.c
- file /usr/src/packages/BUILD/sgi-enhancednfs-1.4/default/net/sunrpc/svcsock.c
+ file kernel/freezer.c # ie column 1 of control file
+ file drivers/usb/* # all callsites under it
+ file inode.c:start_* # parse :tail as a func (above)
+ file inode.c:1-100 # parse :tail as a line-range (above)
module
The given string is compared against the module name
@@ -182,6 +186,7 @@
module sunrpc
module nfsd
+ module drm* # both drm, drm_kms_helper
format
The given string is searched for in the dynamic debug format
@@ -251,8 +256,8 @@
bootloader may impose lower limits.
These ``dyndbg`` params are processed just after the ddebug tables are
-processed, as part of the arch_initcall. Thus you can enable debug
-messages in all code run after this arch_initcall via this boot
+processed, as part of the early_initcall. Thus you can enable debug
+messages in all code run after this early_initcall via this boot
parameter.
On an x86 system for example ACPI enablement is a subsys_initcall and::
diff --git a/Documentation/admin-guide/ext4.rst b/Documentation/admin-guide/ext4.rst
index 9443fce..a683976 100644
--- a/Documentation/admin-guide/ext4.rst
+++ b/Documentation/admin-guide/ext4.rst
@@ -395,6 +395,13 @@
Documentation/filesystems/dax.txt. Note that this option is
incompatible with data=journal.
+ inlinecrypt
+ When possible, encrypt/decrypt the contents of encrypted files using the
+ blk-crypto framework rather than filesystem-layer encryption. This
+ allows the use of inline encryption hardware. The on-disk format is
+ unaffected. For more details, see
+ Documentation/block/inline-encryption.rst.
+
Data Mode
=========
There are 3 different data modes:
@@ -611,7 +618,7 @@
programs: http://e2fsprogs.sourceforge.net/
-useful links: http://fedoraproject.org/wiki/ext3-devel
+useful links: https://fedoraproject.org/wiki/ext3-devel
http://www.bullopensource.org/ext4/
http://ext4.wiki.kernel.org/index.php/Main_Page
- http://fedoraproject.org/wiki/Features/Ext4
+ https://fedoraproject.org/wiki/Features/Ext4
diff --git a/Documentation/admin-guide/hw-vuln/special-register-buffer-data-sampling.rst b/Documentation/admin-guide/hw-vuln/special-register-buffer-data-sampling.rst
index 47b1b3a..3b1ce68 100644
--- a/Documentation/admin-guide/hw-vuln/special-register-buffer-data-sampling.rst
+++ b/Documentation/admin-guide/hw-vuln/special-register-buffer-data-sampling.rst
@@ -14,7 +14,7 @@
to MDS attacks.
Affected processors
---------------------
+-------------------
Core models (desktop, mobile, Xeon-E3) that implement RDRAND and/or RDSEED may
be affected.
@@ -59,7 +59,7 @@
Mitigation mechanism
--------------------
+--------------------
Intel will release microcode updates that modify the RDRAND, RDSEED, and
EGETKEY instructions to overwrite secret special register data in the shared
staging buffer before the secret data can be accessed by another logical
@@ -118,7 +118,7 @@
============= =============================================================
SRBDS System Information
------------------------
+------------------------
The Linux kernel provides vulnerability status information through sysfs. For
SRBDS this can be accessed by the following sysfs file:
/sys/devices/system/cpu/vulnerabilities/srbds
diff --git a/Documentation/admin-guide/index.rst b/Documentation/admin-guide/index.rst
index 58c7f9f..ed1cf94 100644
--- a/Documentation/admin-guide/index.rst
+++ b/Documentation/admin-guide/index.rst
@@ -41,6 +41,7 @@
init
kdump/index
perf/index
+ pstore-blk
This is the beginning of a section with information of interest to
application developers. Documents covering various aspects of the kernel
diff --git a/Documentation/admin-guide/kdump/vmcoreinfo.rst b/Documentation/admin-guide/kdump/vmcoreinfo.rst
index e4ee8b2..2baad0b 100644
--- a/Documentation/admin-guide/kdump/vmcoreinfo.rst
+++ b/Documentation/admin-guide/kdump/vmcoreinfo.rst
@@ -93,6 +93,11 @@
similar to the mem_map variable, both of them are used to translate an
address.
+MAX_PHYSMEM_BITS
+----------------
+
+Defines the maximum supported physical address space memory.
+
page
----
@@ -399,6 +404,17 @@
The mask to extract the Pointer Authentication Code from a kernel virtual
address.
+TCR_EL1.T1SZ
+------------
+
+Indicates the size offset of the memory region addressed by TTBR1_EL1.
+The region size is 2^(64-T1SZ) bytes.
+
+TTBR1_EL1 is the table base address register specified by ARMv8-A
+architecture which is used to lookup the page-tables for the Virtual
+addresses in the higher VA range (refer to ARMv8 ARM document for
+more details).
+
arm
===
diff --git a/Documentation/admin-guide/kernel-parameters.txt b/Documentation/admin-guide/kernel-parameters.txt
index fb95fad..bdc1f33 100644
--- a/Documentation/admin-guide/kernel-parameters.txt
+++ b/Documentation/admin-guide/kernel-parameters.txt
@@ -703,6 +703,11 @@
cpufreq.off=1 [CPU_FREQ]
disable the cpufreq sub-system
+ cpufreq.default_governor=
+ [CPU_FREQ] Name of the default cpufreq governor or
+ policy to use. This governor must be registered in the
+ kernel before the cpufreq driver probes.
+
cpu_init_udelay=N
[X86] Delay for N microsec between assert and de-assert
of APIC INIT to start processors. This delay occurs
@@ -719,7 +724,7 @@
memory region [offset, offset + size] for that kernel
image. If '@offset' is omitted, then a suitable offset
is selected automatically.
- [KNL, x86_64] select a region under 4G first, and
+ [KNL, X86-64] Select a region under 4G first, and
fall back to reserve region above 4G when '@offset'
hasn't been specified.
See Documentation/admin-guide/kdump/kdump.rst for further details.
@@ -732,14 +737,14 @@
Documentation/admin-guide/kdump/kdump.rst for an example.
crashkernel=size[KMG],high
- [KNL, x86_64] range could be above 4G. Allow kernel
+ [KNL, X86-64] range could be above 4G. Allow kernel
to allocate physical memory region from top, so could
be above 4G if system have more than 4G ram installed.
Otherwise memory region will be allocated below 4G, if
available.
It will be ignored if crashkernel=X is specified.
crashkernel=size[KMG],low
- [KNL, x86_64] range under 4G. When crashkernel=X,high
+ [KNL, X86-64] range under 4G. When crashkernel=X,high
is passed, kernel could allocate physical memory region
above 4G, that cause second kernel crash on system
that require some amount of low memory, e.g. swiotlb
@@ -827,6 +832,21 @@
useful to also enable the page_owner functionality.
on: enable the feature
+ debugfs= [KNL] This parameter enables what is exposed to userspace
+ and debugfs internal clients.
+ Format: { on, no-mount, off }
+ on: All functions are enabled.
+ no-mount:
+ Filesystem is not registered but kernel clients can
+ access APIs and a crashkernel can be used to read
+ its content. There is nothing to mount.
+ off: Filesystem is not registered and clients
+ get a -EPERM as result when trying to register files
+ or directories within debugfs.
+ This is equivalent of the runtime functionality if
+ debugfs was not enabled in the kernel at all.
+ Default value is set in build-time with a kernel configuration.
+
debugpat [X86] Enable PAT debugging
decnet.addr= [HW,NET]
@@ -896,6 +916,10 @@
disable_radix [PPC]
Disable RADIX MMU mode on POWER9
+ radix_hcall_invalidate=on [PPC/PSERIES]
+ Disable RADIX GTSE feature and use hcall for TLB
+ invalidate.
+
disable_tlbie [PPC]
Disable TLBIE instruction. Currently does not work
with KVM, with HASH MMU, or with coherent accelerators.
@@ -1207,26 +1231,28 @@
Format: {"off" | "on" | "skip[mbr]"}
efi= [EFI]
- Format: { "old_map", "nochunk", "noruntime", "debug",
- "nosoftreserve", "disable_early_pci_dma",
- "no_disable_early_pci_dma" }
- old_map [X86-64]: switch to the old ioremap-based EFI
- runtime services mapping. [Needs CONFIG_X86_UV=y]
+ Format: { "debug", "disable_early_pci_dma",
+ "nochunk", "noruntime", "nosoftreserve",
+ "novamap", "no_disable_early_pci_dma",
+ "old_map" }
+ debug: enable misc debug output.
+ disable_early_pci_dma: disable the busmaster bit on all
+ PCI bridges while in the EFI boot stub.
nochunk: disable reading files in "chunks" in the EFI
boot stub, as chunking can cause problems with some
firmware implementations.
noruntime : disable EFI runtime services support
- debug: enable misc debug output
nosoftreserve: The EFI_MEMORY_SP (Specific Purpose)
attribute may cause the kernel to reserve the
memory range for a memory mapping driver to
claim. Specify efi=nosoftreserve to disable this
reservation and treat the memory by its base type
(i.e. EFI_CONVENTIONAL_MEMORY / "System RAM").
- disable_early_pci_dma: Disable the busmaster bit on all
- PCI bridges while in the EFI boot stub
+ novamap: do not call SetVirtualAddressMap().
no_disable_early_pci_dma: Leave the busmaster bit set
on all PCI bridges while in the EFI boot stub
+ old_map [X86-64]: switch to the old ioremap-based EFI
+ runtime services mapping. [Needs CONFIG_X86_UV=y]
efi_no_storage_paranoia [EFI; X86]
Using this parameter you can use more than 50% of
@@ -1401,7 +1427,7 @@
gamma= [HW,DRM]
- gart_fix_e820= [X86_64] disable the fix e820 for K8 GART
+ gart_fix_e820= [X86-64] disable the fix e820 for K8 GART
Format: off | on
default: on
@@ -1788,7 +1814,7 @@
Format: 0 | 1
Default set by CONFIG_INIT_ON_FREE_DEFAULT_ON.
- init_pkru= [x86] Specify the default memory protection keys rights
+ init_pkru= [X86] Specify the default memory protection keys rights
register contents for all processes. 0x55555554 by
default (disallow access to all but pkey 0). Can
override in debugfs after boot.
@@ -1796,7 +1822,7 @@
inport.irq= [HW] Inport (ATI XL and Microsoft) busmouse driver
Format: <irq>
- int_pln_enable [x86] Enable power limit notification interrupt
+ int_pln_enable [X86] Enable power limit notification interrupt
integrity_audit=[IMA]
Format: { "0" | "1" }
@@ -1814,7 +1840,7 @@
bypassed by not enabling DMAR with this option. In
this case, gfx device will use physical address for
DMA.
- forcedac [x86_64]
+ forcedac [X86-64]
With this option iommu will not optimize to look
for io virtual address below 32-bit forcing dual
address cycle on pci bus for cards supporting greater
@@ -1899,7 +1925,7 @@
strict regions from userspace.
relaxed
- iommu= [x86]
+ iommu= [X86]
off
force
noforce
@@ -1909,8 +1935,8 @@
merge
nomerge
soft
- pt [x86]
- nopt [x86]
+ pt [X86]
+ nopt [X86]
nobypass [PPC/POWERNV]
Disable IOMMU bypass, using IOMMU for PCI devices.
@@ -2053,21 +2079,21 @@
iucv= [HW,NET]
- ivrs_ioapic [HW,X86_64]
+ ivrs_ioapic [HW,X86-64]
Provide an override to the IOAPIC-ID<->DEVICE-ID
mapping provided in the IVRS ACPI table. For
example, to map IOAPIC-ID decimal 10 to
PCI device 00:14.0 write the parameter as:
ivrs_ioapic[10]=00:14.0
- ivrs_hpet [HW,X86_64]
+ ivrs_hpet [HW,X86-64]
Provide an override to the HPET-ID<->DEVICE-ID
mapping provided in the IVRS ACPI table. For
example, to map HPET-ID decimal 0 to
PCI device 00:14.0 write the parameter as:
ivrs_hpet[0]=00:14.0
- ivrs_acpihid [HW,X86_64]
+ ivrs_acpihid [HW,X86-64]
Provide an override to the ACPI-HID:UID<->DEVICE-ID
mapping provided in the IVRS ACPI table. For
example, to map UART-HID:UID AMD0020:0 to
@@ -2344,7 +2370,7 @@
lapic [X86-32,APIC] Enable the local APIC even if BIOS
disabled it.
- lapic= [x86,APIC] "notscdeadline" Do not use TSC deadline
+ lapic= [X86,APIC] "notscdeadline" Do not use TSC deadline
value for LAPIC timer one-shot implementation. Default
back to the programmable timer unit in the LAPIC.
@@ -2786,7 +2812,7 @@
touchscreen support is not enabled in the mainstream
kernel as of 2.6.30, a preliminary port can be found
in the "bleeding edge" mini2440 support kernel at
- http://repo.or.cz/w/linux-2.6/mini2440.git
+ https://repo.or.cz/w/linux-2.6/mini2440.git
mitigations=
[X86,PPC,S390,ARM64] Control optional mitigations for
@@ -3079,6 +3105,8 @@
no5lvl [X86-64] Disable 5-level paging mode. Forces
kernel to use 4-level paging instead.
+ nofsgsbase [X86] Disables FSGSBASE instructions.
+
no_console_suspend
[HW] Never suspend the console
Disable suspending of consoles during suspend and
@@ -3160,12 +3188,12 @@
register save and restore. The kernel will only save
legacy floating-point registers on task switch.
- nohugeiomap [KNL,x86,PPC] Disable kernel huge I/O mappings.
+ nohugeiomap [KNL,X86,PPC] Disable kernel huge I/O mappings.
nosmt [KNL,S390] Disable symmetric multithreading (SMT).
Equivalent to smt=1.
- [KNL,x86] Disable symmetric multithreading (SMT).
+ [KNL,X86] Disable symmetric multithreading (SMT).
nosmt=force: Force disable SMT, cannot be undone
via the sysfs control file.
@@ -3927,7 +3955,7 @@
pt. [PARIDE]
See Documentation/admin-guide/blockdev/paride.rst.
- pti= [X86_64] Control Page Table Isolation of user and
+ pti= [X86-64] Control Page Table Isolation of user and
kernel address spaces. Disabling this feature
removes hardening, but improves performance of
system calls and interrupts.
@@ -3939,7 +3967,7 @@
Not specifying this option is equivalent to pti=auto.
- nopti [X86_64]
+ nopti [X86-64]
Equivalent to pti=off
pty.legacy_count=
@@ -4038,6 +4066,14 @@
latencies, which will choose a value aligned
with the appropriate hardware boundaries.
+ rcutree.rcu_min_cached_objs= [KNL]
+ Minimum number of objects which are cached and
+ maintained per one CPU. Object size is equal
+ to PAGE_SIZE. The cache allows to reduce the
+ pressure to page allocator, also it makes the
+ whole algorithm to behave better in low memory
+ condition.
+
rcutree.jiffies_till_first_fqs= [KNL]
Set delay from grace-period initialization to
first attempt to force quiescent states.
@@ -4258,6 +4294,20 @@
Set time (jiffies) between CPU-hotplug operations,
or zero to disable CPU-hotplug testing.
+ rcutorture.read_exit= [KNL]
+ Set the number of read-then-exit kthreads used
+ to test the interaction of RCU updaters and
+ task-exit processing.
+
+ rcutorture.read_exit_burst= [KNL]
+ The number of times in a given read-then-exit
+ episode that a set of read-then-exit kthreads
+ is spawned.
+
+ rcutorture.read_exit_delay= [KNL]
+ The delay, in seconds, between successive
+ read-then-exit testing episodes.
+
rcutorture.shuffle_interval= [KNL]
Set task-shuffle interval (s). Shuffling tasks
allows some CPUs to go into dyntick-idle mode
@@ -4407,6 +4457,45 @@
reboot_cpu is s[mp]#### with #### being the processor
to be used for rebooting.
+ refscale.holdoff= [KNL]
+ Set test-start holdoff period. The purpose of
+ this parameter is to delay the start of the
+ test until boot completes in order to avoid
+ interference.
+
+ refscale.loops= [KNL]
+ Set the number of loops over the synchronization
+ primitive under test. Increasing this number
+ reduces noise due to loop start/end overhead,
+ but the default has already reduced the per-pass
+ noise to a handful of picoseconds on ca. 2020
+ x86 laptops.
+
+ refscale.nreaders= [KNL]
+ Set number of readers. The default value of -1
+ selects N, where N is roughly 75% of the number
+ of CPUs. A value of zero is an interesting choice.
+
+ refscale.nruns= [KNL]
+ Set number of runs, each of which is dumped onto
+ the console log.
+
+ refscale.readdelay= [KNL]
+ Set the read-side critical-section duration,
+ measured in microseconds.
+
+ refscale.scale_type= [KNL]
+ Specify the read-protection implementation to test.
+
+ refscale.shutdown= [KNL]
+ Shut down the system at the end of the performance
+ test. This defaults to 1 (shut it down) when
+ rcuperf is built into the kernel and to 0 (leave
+ it running) when rcuperf is built as a module.
+
+ refscale.verbose= [KNL]
+ Enable additional printk() statements.
+
relax_domain_level=
[KNL, SMP] Set scheduler's default relax_domain_level.
See Documentation/admin-guide/cgroup-v1/cpusets.rst.
@@ -4604,7 +4693,7 @@
fragmentation. Defaults to 1 for systems with
more than 32MB of RAM, 0 otherwise.
- slub_debug[=options[,slabs]] [MM, SLUB]
+ slub_debug[=options[,slabs][;[options[,slabs]]...] [MM, SLUB]
Enabling slub_debug allows one to determine the
culprit if slab objects become corrupted. Enabling
slub_debug can create guard zones around objects and
@@ -5082,6 +5171,13 @@
Prevent the CPU-hotplug component of torturing
until after init has spawned.
+ torture.ftrace_dump_at_shutdown= [KNL]
+ Dump the ftrace buffer at torture-test shutdown,
+ even if there were no errors. This can be a
+ very costly operation when many torture tests
+ are running concurrently, especially on systems
+ with rotating-rust storage.
+
tp720= [HW,PS2]
tpm_suspend_pcr=[HW,TPM]
@@ -5712,8 +5808,9 @@
panic() code such as dumping handler.
xen_nopvspin [X86,XEN]
- Disables the ticketlock slowpath using Xen PV
- optimizations.
+ Disables the qspinlock slowpath using Xen PV optimizations.
+ This parameter is obsoleted by "nopvspin" parameter, which
+ has equivalent effect for XEN platform.
xen_nopv [X86]
Disables the PV optimizations forcing the HVM guest to
@@ -5739,6 +5836,11 @@
as generic guest with no PV drivers. Currently support
XEN HVM, KVM, HYPER_V and VMWARE guest.
+ nopvspin [X86,XEN,KVM]
+ Disables the qspinlock slow path using PV optimizations
+ which allow the hypervisor to 'idle' the guest on lock
+ contention.
+
xirc2ps_cs= [NET,PCMCIA]
Format:
<irq>,<irq_mask>,<io>,<full_duplex>,<do_sound>,<lockup_hack>[,<irq2>[,<irq3>[,<irq4>]]]
diff --git a/Documentation/admin-guide/laptops/disk-shock-protection.rst b/Documentation/admin-guide/laptops/disk-shock-protection.rst
index e97c5f7..22c7ec3 100644
--- a/Documentation/admin-guide/laptops/disk-shock-protection.rst
+++ b/Documentation/admin-guide/laptops/disk-shock-protection.rst
@@ -135,7 +135,7 @@
for use. Please feel free to add projects that have been the victims
of my ignorance.
-- http://www.thinkwiki.org/wiki/HDAPS
+- https://www.thinkwiki.org/wiki/HDAPS
See this page for information about Linux support of the hard disk
active protection system as implemented in IBM/Lenovo Thinkpads.
diff --git a/Documentation/admin-guide/laptops/sonypi.rst b/Documentation/admin-guide/laptops/sonypi.rst
index c6eaaf4..190da12 100644
--- a/Documentation/admin-guide/laptops/sonypi.rst
+++ b/Documentation/admin-guide/laptops/sonypi.rst
@@ -151,7 +151,7 @@
different way to adjust the backlighting of the screen. There
is a userspace utility to adjust the brightness on those models,
which can be downloaded from
- http://www.acc.umu.se/~erikw/program/smartdimmer-0.1.tar.bz2
+ https://www.acc.umu.se/~erikw/program/smartdimmer-0.1.tar.bz2
- since all development was done by reverse engineering, there is
*absolutely no guarantee* that this driver will not crash your
diff --git a/Documentation/admin-guide/laptops/thinkpad-acpi.rst b/Documentation/admin-guide/laptops/thinkpad-acpi.rst
index 822907d..5e477869 100644
--- a/Documentation/admin-guide/laptops/thinkpad-acpi.rst
+++ b/Documentation/admin-guide/laptops/thinkpad-acpi.rst
@@ -50,6 +50,7 @@
- WAN enable and disable
- UWB enable and disable
- LCD Shadow (PrivacyGuard) enable and disable
+ - Lap mode sensor
A compatibility table by model and feature is maintained on the web
site, http://ibm-acpi.sf.net/. I appreciate any success or failure
@@ -904,7 +905,7 @@
The mapping of thermal sensors to physical locations varies depending on
system-board model (and thus, on ThinkPad model).
-http://thinkwiki.org/wiki/Thermal_Sensors is a public wiki page that
+https://thinkwiki.org/wiki/Thermal_Sensors is a public wiki page that
tries to track down these locations for various models.
Most (newer?) models seem to follow this pattern:
@@ -925,7 +926,7 @@
- 3: Internal HDD
For the T43, T43/p (source: Shmidoax/Thinkwiki.org)
-http://thinkwiki.org/wiki/Thermal_Sensors#ThinkPad_T43.2C_T43p
+https://thinkwiki.org/wiki/Thermal_Sensors#ThinkPad_T43.2C_T43p
- 2: System board, left side (near PCMCIA slot), reported as HDAPS temp
- 3: PCMCIA slot
@@ -935,7 +936,7 @@
- 11: Power regulator, underside of system board, below F2 key
The A31 has a very atypical layout for the thermal sensors
-(source: Milos Popovic, http://thinkwiki.org/wiki/Thermal_Sensors#ThinkPad_A31)
+(source: Milos Popovic, https://thinkwiki.org/wiki/Thermal_Sensors#ThinkPad_A31)
- 1: CPU
- 2: Main Battery: main sensor
@@ -1432,6 +1433,20 @@
on the feature, restricting the viewing angles.
+DYTC Lapmode sensor
+------------------
+
+sysfs: dytc_lapmode
+
+Newer thinkpads and mobile workstations have the ability to determine if
+the device is in deskmode or lapmode. This feature is used by user space
+to decide if WWAN transmission can be increased to maximum power and is
+also useful for understanding the different thermal modes available as
+they differ between desk and lap mode.
+
+The property is read-only. If the platform doesn't have support the sysfs
+class is not created.
+
EXPERIMENTAL: UWB
-----------------
@@ -1470,6 +1485,23 @@
review the laptop's user guide:
http://www.lenovo.com/shop/americas/content/user_guides/x1carbon_2_ug_en.pdf
+Battery charge control
+----------------------
+
+sysfs attributes:
+/sys/class/power_supply/BAT*/charge_control_{start,end}_threshold
+
+These two attributes are created for those batteries that are supported by the
+driver. They enable the user to control the battery charge thresholds of the
+given battery. Both values may be read and set. `charge_control_start_threshold`
+accepts an integer between 0 and 99 (inclusive); this value represents a battery
+percentage level, below which charging will begin. `charge_control_end_threshold`
+accepts an integer between 1 and 100 (inclusive); this value represents a battery
+percentage level, above which charging will stop.
+
+The exact semantics of the attributes may be found in
+Documentation/ABI/testing/sysfs-class-power.
+
Multiple Commands, Module Parameters
------------------------------------
diff --git a/Documentation/admin-guide/md.rst b/Documentation/admin-guide/md.rst
index d973d46..cc8781b 100644
--- a/Documentation/admin-guide/md.rst
+++ b/Documentation/admin-guide/md.rst
@@ -426,6 +426,10 @@
The accepted values when writing to this file are ``ppl`` and ``resync``,
used to enable and disable PPL.
+ uuid
+ This indicates the UUID of the array in the following format:
+ xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
+
As component devices are added to an md array, they appear in the ``md``
directory as new directories named::
diff --git a/Documentation/admin-guide/media/building.rst b/Documentation/admin-guide/media/building.rst
index c898e3a..2d660b7 100644
--- a/Documentation/admin-guide/media/building.rst
+++ b/Documentation/admin-guide/media/building.rst
@@ -90,7 +90,7 @@
Those GPU-specific drivers are selected via the ``Graphics support``
menu, under ``Device Drivers``.
- When a GPU driver supports supports HDMI CEC, it will automatically
+ When a GPU driver supports HDMI CEC, it will automatically
enable the CEC core support at the media subsystem.
Media dependencies
@@ -244,7 +244,7 @@
If you have an hybrid card, you may need to enable both ``Analog TV``
and ``Digital TV`` at the menu.
-When using this option, the defaults for the the media support core
+When using this option, the defaults for the media support core
functionality are usually good enough to provide the basic functionality
for the driver. Yet, you could manually enable some desired extra (optional)
functionality using the settings under each of the following
diff --git a/Documentation/admin-guide/media/fimc.rst b/Documentation/admin-guide/media/fimc.rst
index 0b8ddc4..56b149d 100644
--- a/Documentation/admin-guide/media/fimc.rst
+++ b/Documentation/admin-guide/media/fimc.rst
@@ -2,7 +2,7 @@
.. include:: <isonum.txt>
-The Samsung S5P/EXYNOS4 FIMC driver
+The Samsung S5P/Exynos4 FIMC driver
===================================
Copyright |copy| 2012 - 2013 Samsung Electronics Co., Ltd.
@@ -19,7 +19,7 @@
Supported SoCs
--------------
-S5PC100 (mem-to-mem only), S5PV210, EXYNOS4210
+S5PC100 (mem-to-mem only), S5PV210, Exynos4210
Supported features
------------------
@@ -45,7 +45,7 @@
~~~~~~~~~~~~~~~~~~~~~~
The driver supports Media Controller API as defined at :ref:`media_controller`.
-The media device driver name is "SAMSUNG S5P FIMC".
+The media device driver name is "Samsung S5P FIMC".
The purpose of this interface is to allow changing assignment of FIMC instances
to the SoC peripheral camera input at runtime and optionally to control internal
diff --git a/Documentation/admin-guide/media/vivid.rst b/Documentation/admin-guide/media/vivid.rst
index 52e57b7..6d7175f 100644
--- a/Documentation/admin-guide/media/vivid.rst
+++ b/Documentation/admin-guide/media/vivid.rst
@@ -293,6 +293,15 @@
- 0: vmalloc
- 1: dma-contig
+- cache_hints:
+
+ specifies if the device should set queues' user-space cache and memory
+ consistency hint capability (V4L2_BUF_CAP_SUPPORTS_MMAP_CACHE_HINTS).
+ The hints are valid only when using MMAP streaming I/O. Default is 0.
+
+ - 0: forbid hints
+ - 1: allow hints
+
Taken together, all these module options allow you to precisely customize
the driver behavior and test your application with all sorts of permutations.
It is also very suitable to emulate hardware that is not yet available, e.g.
diff --git a/Documentation/admin-guide/mm/concepts.rst b/Documentation/admin-guide/mm/concepts.rst
index c2531b1..fa0974f 100644
--- a/Documentation/admin-guide/mm/concepts.rst
+++ b/Documentation/admin-guide/mm/concepts.rst
@@ -35,7 +35,7 @@
protection and controlled sharing of data between processes.
With virtual memory, each and every memory access uses a virtual
-address. When the CPU decodes the an instruction that reads (or
+address. When the CPU decodes an instruction that reads (or
writes) from (or to) the system memory, it translates the `virtual`
address encoded in that instruction to a `physical` address that the
memory controller can understand.
diff --git a/Documentation/admin-guide/mm/hugetlbpage.rst b/Documentation/admin-guide/mm/hugetlbpage.rst
index 5026e58..015a5f7 100644
--- a/Documentation/admin-guide/mm/hugetlbpage.rst
+++ b/Documentation/admin-guide/mm/hugetlbpage.rst
@@ -101,37 +101,48 @@
page size may be selected with the "default_hugepagesz=<size>" boot parameter.
Hugetlb boot command line parameter semantics
-hugepagesz - Specify a huge page size. Used in conjunction with hugepages
+
+hugepagesz
+ Specify a huge page size. Used in conjunction with hugepages
parameter to preallocate a number of huge pages of the specified
size. Hence, hugepagesz and hugepages are typically specified in
- pairs such as:
+ pairs such as::
+
hugepagesz=2M hugepages=512
+
hugepagesz can only be specified once on the command line for a
specific huge page size. Valid huge page sizes are architecture
dependent.
-hugepages - Specify the number of huge pages to preallocate. This typically
+hugepages
+ Specify the number of huge pages to preallocate. This typically
follows a valid hugepagesz or default_hugepagesz parameter. However,
if hugepages is the first or only hugetlb command line parameter it
implicitly specifies the number of huge pages of default size to
allocate. If the number of huge pages of default size is implicitly
specified, it can not be overwritten by a hugepagesz,hugepages
parameter pair for the default size.
- For example, on an architecture with 2M default huge page size:
+
+ For example, on an architecture with 2M default huge page size::
+
hugepages=256 hugepagesz=2M hugepages=512
+
will result in 256 2M huge pages being allocated and a warning message
indicating that the hugepages=512 parameter is ignored. If a hugepages
parameter is preceded by an invalid hugepagesz parameter, it will
be ignored.
-default_hugepagesz - Specify the default huge page size. This parameter can
+default_hugepagesz
+ pecify the default huge page size. This parameter can
only be specified once on the command line. default_hugepagesz can
optionally be followed by the hugepages parameter to preallocate a
specific number of huge pages of default size. The number of default
sized huge pages to preallocate can also be implicitly specified as
mentioned in the hugepages section above. Therefore, on an
- architecture with 2M default huge page size:
+ architecture with 2M default huge page size::
+
hugepages=256
default_hugepagesz=2M hugepages=256
hugepages=256 default_hugepagesz=2M
+
will all result in 256 2M huge pages being allocated. Valid default
huge page size is architecture dependent.
diff --git a/Documentation/admin-guide/mm/index.rst b/Documentation/admin-guide/mm/index.rst
index 11db464..cd727cf 100644
--- a/Documentation/admin-guide/mm/index.rst
+++ b/Documentation/admin-guide/mm/index.rst
@@ -31,6 +31,7 @@
idle_page_tracking
ksm
memory-hotplug
+ nommu-mmap
numa_memory_policy
numaperf
pagemap
diff --git a/Documentation/admin-guide/mm/ksm.rst b/Documentation/admin-guide/mm/ksm.rst
index 874eb0c..97d8167 100644
--- a/Documentation/admin-guide/mm/ksm.rst
+++ b/Documentation/admin-guide/mm/ksm.rst
@@ -9,7 +9,7 @@
KSM is a memory-saving de-duplication feature, enabled by CONFIG_KSM=y,
added to the Linux kernel in 2.6.32. See ``mm/ksm.c`` for its implementation,
-and http://lwn.net/Articles/306704/ and http://lwn.net/Articles/330589/
+and http://lwn.net/Articles/306704/ and https://lwn.net/Articles/330589/
KSM was originally developed for use with KVM (where it was known as
Kernel Shared Memory), to fit more virtual machines into physical memory,
@@ -52,7 +52,7 @@
If KSM is not configured into the running kernel, madvise MADV_MERGEABLE
and MADV_UNMERGEABLE simply fail with EINVAL. If the running kernel was
built with CONFIG_KSM=y, those calls will normally succeed: even if the
-the KSM daemon is not currently running, MADV_MERGEABLE still registers
+KSM daemon is not currently running, MADV_MERGEABLE still registers
the range for whenever the KSM daemon is started; even if the range
cannot contain any pages which KSM could actually merge; even if
MADV_UNMERGEABLE is applied to a range which was never MADV_MERGEABLE.
diff --git a/Documentation/nommu-mmap.txt b/Documentation/admin-guide/mm/nommu-mmap.rst
similarity index 100%
rename from Documentation/nommu-mmap.txt
rename to Documentation/admin-guide/mm/nommu-mmap.rst
diff --git a/Documentation/admin-guide/mm/numaperf.rst b/Documentation/admin-guide/mm/numaperf.rst
index a80c3c3..4d69ef1 100644
--- a/Documentation/admin-guide/mm/numaperf.rst
+++ b/Documentation/admin-guide/mm/numaperf.rst
@@ -129,7 +129,7 @@
/sys/devices/system/node/nodeX/memory_side_cache/
-If that directory is not present, the system either does not not provide
+If that directory is not present, the system either does not provide
a memory-side cache, or that information is not accessible to the kernel.
The attributes for each level of cache is provided under its cache
diff --git a/Documentation/admin-guide/mm/transhuge.rst b/Documentation/admin-guide/mm/transhuge.rst
index 6a233e4..b2acd0d 100644
--- a/Documentation/admin-guide/mm/transhuge.rst
+++ b/Documentation/admin-guide/mm/transhuge.rst
@@ -305,8 +305,7 @@
thp_fault_alloc
is incremented every time a huge page is successfully
- allocated to handle a page fault. This applies to both the
- first time a page is faulted and for COW faults.
+ allocated to handle a page fault.
thp_collapse_alloc
is incremented by khugepaged when it has found
diff --git a/Documentation/admin-guide/nfs/nfs-client.rst b/Documentation/admin-guide/nfs/nfs-client.rst
index c4b777c..6adb645 100644
--- a/Documentation/admin-guide/nfs/nfs-client.rst
+++ b/Documentation/admin-guide/nfs/nfs-client.rst
@@ -65,8 +65,8 @@
attribute. See `RFC3530 Section 6: Filesystem Migration and Replication`_ and
`Implementation Guide for Referrals in NFSv4`_.
-.. _RFC3530 Section 6\: Filesystem Migration and Replication: http://tools.ietf.org/html/rfc3530#section-6
-.. _Implementation Guide for Referrals in NFSv4: http://tools.ietf.org/html/draft-ietf-nfsv4-referrals-00
+.. _RFC3530 Section 6\: Filesystem Migration and Replication: https://tools.ietf.org/html/rfc3530#section-6
+.. _Implementation Guide for Referrals in NFSv4: https://tools.ietf.org/html/draft-ietf-nfsv4-referrals-00
The fs_locations information can take the form of either an ip address and
a path, or a DNS hostname and a path. The latter requires the NFS client to
diff --git a/Documentation/admin-guide/nfs/nfs-rdma.rst b/Documentation/admin-guide/nfs/nfs-rdma.rst
index ef0f367..f137485 100644
--- a/Documentation/admin-guide/nfs/nfs-rdma.rst
+++ b/Documentation/admin-guide/nfs/nfs-rdma.rst
@@ -65,7 +65,7 @@
If the version is less than 1.1.2 or the command does not exist,
you should install the latest version of nfs-utils.
- Download the latest package from: http://www.kernel.org/pub/linux/utils/nfs
+ Download the latest package from: https://www.kernel.org/pub/linux/utils/nfs
Uncompress the package and follow the installation instructions.
diff --git a/Documentation/admin-guide/nfs/nfsroot.rst b/Documentation/admin-guide/nfs/nfsroot.rst
index c677207..135218f 100644
--- a/Documentation/admin-guide/nfs/nfsroot.rst
+++ b/Documentation/admin-guide/nfs/nfsroot.rst
@@ -264,7 +264,7 @@
access to the floppy drive device, /dev/fd0
For more information on syslinux, including how to create bootdisks
- for prebuilt kernels, see http://syslinux.zytor.com/
+ for prebuilt kernels, see https://syslinux.zytor.com/
.. note::
Previously it was possible to write a kernel directly to
@@ -292,7 +292,7 @@
cdrecord dev=ATAPI:1,0,0 arch/x86/boot/image.iso
For more information on isolinux, including how to create bootdisks
- for prebuilt kernels, see http://syslinux.zytor.com/
+ for prebuilt kernels, see https://syslinux.zytor.com/
- Using LILO
@@ -346,7 +346,7 @@
see Documentation/admin-guide/serial-console.rst for more information.
For more information on isolinux, including how to create bootdisks
- for prebuilt kernels, see http://syslinux.zytor.com/
+ for prebuilt kernels, see https://syslinux.zytor.com/
diff --git a/Documentation/admin-guide/nfs/pnfs-block-server.rst b/Documentation/admin-guide/nfs/pnfs-block-server.rst
index b00a2e7..20fe9f5 100644
--- a/Documentation/admin-guide/nfs/pnfs-block-server.rst
+++ b/Documentation/admin-guide/nfs/pnfs-block-server.rst
@@ -8,7 +8,7 @@
to the clients to directly access the underlying block devices that are
shared with the client.
-To use pNFS block layouts with with the Linux NFS server the exported file
+To use pNFS block layouts with the Linux NFS server the exported file
system needs to support the pNFS block layouts (currently just XFS), and the
file system must sit on shared storage (typically iSCSI) that is accessible
to the clients in addition to the MDS. As of now the file system needs to
diff --git a/Documentation/admin-guide/nfs/pnfs-scsi-server.rst b/Documentation/admin-guide/nfs/pnfs-scsi-server.rst
index d2f6ee5..b2eec22 100644
--- a/Documentation/admin-guide/nfs/pnfs-scsi-server.rst
+++ b/Documentation/admin-guide/nfs/pnfs-scsi-server.rst
@@ -9,7 +9,7 @@
also hands out layouts to the clients so that they can directly access the
underlying SCSI LUNs that are shared with the client.
-To use pNFS SCSI layouts with with the Linux NFS server, the exported file
+To use pNFS SCSI layouts with the Linux NFS server, the exported file
system needs to support the pNFS SCSI layouts (currently just XFS), and the
file system must sit on a SCSI LUN that is accessible to the clients in
addition to the MDS. As of now the file system needs to sit directly on the
diff --git a/Documentation/admin-guide/perf/arm-ccn.rst b/Documentation/admin-guide/perf/arm-ccn.rst
index 832b0c6..f62f7fe 100644
--- a/Documentation/admin-guide/perf/arm-ccn.rst
+++ b/Documentation/admin-guide/perf/arm-ccn.rst
@@ -27,7 +27,7 @@
and "vc" (virtual channel ID).
Crosspoint watchpoint-based events (special "event" value 0xfe)
-require "xp" and "vc" as as above plus "port" (device port index),
+require "xp" and "vc" as above plus "port" (device port index),
"dir" (transmit/receive direction), comparator values ("cmp_l"
and "cmp_h") and "mask", being index of the comparator mask.
diff --git a/Documentation/admin-guide/pm/cpufreq.rst b/Documentation/admin-guide/pm/cpufreq.rst
index 0c74a77..368e612 100644
--- a/Documentation/admin-guide/pm/cpufreq.rst
+++ b/Documentation/admin-guide/pm/cpufreq.rst
@@ -147,9 +147,9 @@
The next major initialization step for a new policy object is to attach a
scaling governor to it (to begin with, that is the default scaling governor
-determined by the kernel configuration, but it may be changed later
-via ``sysfs``). First, a pointer to the new policy object is passed to the
-governor's ``->init()`` callback which is expected to initialize all of the
+determined by the kernel command line or configuration, but it may be changed
+later via ``sysfs``). First, a pointer to the new policy object is passed to
+the governor's ``->init()`` callback which is expected to initialize all of the
data structures necessary to handle the given policy and, possibly, to add
a governor ``sysfs`` interface to it. Next, the governor is started by
invoking its ``->start()`` callback.
diff --git a/Documentation/admin-guide/pm/intel-speed-select.rst b/Documentation/admin-guide/pm/intel-speed-select.rst
index b2ca601..219f135 100644
--- a/Documentation/admin-guide/pm/intel-speed-select.rst
+++ b/Documentation/admin-guide/pm/intel-speed-select.rst
@@ -114,7 +114,7 @@
Lock/Unlock status
~~~~~~~~~~~~~~~~~~
-Even if there are multiple performance profiles, it is possible that that they
+Even if there are multiple performance profiles, it is possible that they
are locked. If they are locked, users cannot issue a command to change the
performance state. It is possible that there is a BIOS setup to unlock or check
with your system vendor.
@@ -883,7 +883,7 @@
enable:success
In this case, the option "-a" is optional. If set, it enables Intel(R) SST-TF
-feature and also sets the CPUs to high and and low priority using Intel Speed
+feature and also sets the CPUs to high and low priority using Intel Speed
Select Technology Core Power (Intel(R) SST-CP) features. The CPU numbers passed
with "-c" arguments are marked as high priority, including its siblings.
diff --git a/Documentation/admin-guide/pm/intel_pstate.rst b/Documentation/admin-guide/pm/intel_pstate.rst
index 39d80bc..9db9249 100644
--- a/Documentation/admin-guide/pm/intel_pstate.rst
+++ b/Documentation/admin-guide/pm/intel_pstate.rst
@@ -431,6 +431,17 @@
supported in the current configuration, writes to this attribute will
fail with an appropriate error.
+``energy_efficiency``
+ This attribute is only present on platforms, which have CPUs matching
+ Kaby Lake or Coffee Lake desktop CPU model. By default
+ energy efficiency optimizations are disabled on these CPU models in HWP
+ mode by this driver. Enabling energy efficiency may limit maximum
+ operating frequency in both HWP and non HWP mode. In non HWP mode,
+ optimizations are done only in the turbo frequency range. In HWP mode,
+ optimizations are done in the entire frequency range. Setting this
+ attribute to "1" enables energy efficiency optimizations and setting
+ to "0" disables energy efficiency optimizations.
+
Interpretation of Policy Attributes
-----------------------------------
@@ -554,7 +565,11 @@
Strings written to the ``energy_performance_preference`` attribute are
internally translated to integer values written to the processor's
Energy-Performance Preference (EPP) knob (if supported) or its
-Energy-Performance Bias (EPB) knob.
+Energy-Performance Bias (EPB) knob. It is also possible to write a positive
+integer value between 0 to 255, if the EPP feature is present. If the EPP
+feature is not present, writing integer value to this attribute is not
+supported. In this case, user can use
+ "/sys/devices/system/cpu/cpu*/power/energy_perf_bias" interface.
[Note that tasks may by migrated from one CPU to another by the scheduler's
load-balancing algorithm and if different energy vs performance hints are
@@ -708,7 +723,7 @@
The ``ftrace`` interface can be used for low-level diagnostics of
``intel_pstate``. For example, to check how often the function to set a
-P-state is called, the ``ftrace`` filter can be set to to
+P-state is called, the ``ftrace`` filter can be set to
:c:func:`intel_pstate_set_pstate`::
# cd /sys/kernel/debug/tracing/
diff --git a/Documentation/admin-guide/security-bugs.rst b/Documentation/admin-guide/security-bugs.rst
index dcd6c93..c32eb78 100644
--- a/Documentation/admin-guide/security-bugs.rst
+++ b/Documentation/admin-guide/security-bugs.rst
@@ -21,11 +21,18 @@
As it is with any bug, the more information provided the easier it
will be to diagnose and fix. Please review the procedure outlined in
-admin-guide/reporting-bugs.rst if you are unclear about what
+:doc:`reporting-bugs` if you are unclear about what
information is helpful. Any exploit code is very helpful and will not
be released without consent from the reporter unless it has already been
made public.
+Please send plain text emails without attachments where possible.
+It is much harder to have a context-quoted discussion about a complex
+issue if all the details are hidden away in attachments. Think of it like a
+:doc:`regular patch submission <../process/submitting-patches>`
+(even if you don't have a patch yet): describe the problem and impact, list
+reproduction steps, and follow it with a proposed fix, all in plain text.
+
Disclosure and embargoed information
------------------------------------
diff --git a/Documentation/admin-guide/spkguide.txt b/Documentation/admin-guide/spkguide.txt
new file mode 100644
index 0000000..3782f6a
--- /dev/null
+++ b/Documentation/admin-guide/spkguide.txt
@@ -0,0 +1,1575 @@
+
+The Speakup User's Guide
+For Speakup 3.1.2 and Later
+By Gene Collins
+Updated by others
+Last modified on Mon Sep 27 14:26:31 2010
+Document version 1.3
+
+Copyright (c) 2005 Gene Collins
+Copyright (c) 2008 Samuel Thibault
+Copyright (c) 2009, 2010 the Speakup Team
+
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.2 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 in the section entitled "GNU Free
+Documentation License".
+
+Preface
+
+The purpose of this document is to familiarize users with the user
+interface to Speakup, a Linux Screen Reader. If you need instructions
+for installing or obtaining Speakup, visit the web site at
+http://linux-speakup.org/. Speakup is a set of patches to the standard
+Linux kernel source tree. It can be built as a series of modules, or as
+a part of a monolithic kernel. These details are beyond the scope of
+this manual, but the user may need to be aware of the module
+capabilities, depending on how your system administrator has installed
+Speakup. If Speakup is built as a part of a monolithic kernel, and the
+user is using a hardware synthesizer, then Speakup will be able to
+provide speech access from the time the kernel is loaded, until the time
+the system is shutdown. This means that if you have obtained Linux
+installation media for a distribution which includes Speakup as a part
+of its kernel, you will be able, as a blind person, to install Linux
+with speech access unaided by a sighted person. Again, these details
+are beyond the scope of this manual, but the user should be aware of
+them. See the web site mentioned above for further details.
+
+1. Starting Speakup
+
+If your system administrator has installed Speakup to work with your
+specific synthesizer by default, then all you need to do to use Speakup
+is to boot your system, and Speakup should come up talking. This
+assumes of course that your synthesizer is a supported hardware
+synthesizer, and that it is either installed in or connected to your
+system, and is if necessary powered on.
+
+It is possible, however, that Speakup may have been compiled into the
+kernel with no default synthesizer. It is even possible that your
+kernel has been compiled with support for some of the supported
+synthesizers and not others. If you find that this is the case, and
+your synthesizer is supported but not available, complain to the person
+who compiled and installed your kernel. Or better yet, go to the web
+site, and learn how to patch Speakup into your own kernel source, and
+build and install your own kernel.
+
+If your kernel has been compiled with Speakup, and has no default
+synthesizer set, or you would like to use a different synthesizer than
+the default one, then you may issue the following command at the boot
+prompt of your boot loader.
+
+linux speakup.synth=ltlk
+
+This command would tell Speakup to look for and use a LiteTalk or
+DoubleTalk LT at boot up. You may replace the ltlk synthesizer keyword
+with the keyword for whatever synthesizer you wish to use. The
+speakup.synth parameter will accept the following keywords, provided
+that support for the related synthesizers has been built into the
+kernel.
+
+acntsa -- Accent SA
+acntpc -- Accent PC
+apollo -- Apollo
+audptr -- Audapter
+bns -- Braille 'n Speak
+dectlk -- DecTalk Express (old and new, db9 serial only)
+decext -- DecTalk (old) External
+dtlk -- DoubleTalk PC
+keypc -- Keynote Gold PC
+ltlk -- DoubleTalk LT, LiteTalk, or external Tripletalk (db9 serial only)
+spkout -- Speak Out
+txprt -- Transport
+dummy -- Plain text terminal
+
+Note: Speakup does * NOT * support usb connections! Speakup also does *
+NOT * support the internal Tripletalk!
+
+Speakup does support two other synthesizers, but because they work in
+conjunction with other software, they must be loaded as modules after
+their related software is loaded, and so are not available at boot up.
+These are as follows:
+
+decpc -- DecTalk PC (not available at boot up)
+soft -- One of several software synthesizers (not available at boot up)
+
+See the sections on loading modules and software synthesizers later in
+this manual for further details. It should be noted here that the
+speakup.synth boot parameter will have no effect if Speakup has been
+compiled as modules. In order for Speakup modules to be loaded during
+the boot process, such action must be configured by your system
+administrator. This will mean that you will hear some, but not all, of
+the bootup messages.
+
+2. Basic operation
+
+Once you have booted the system, and if necessary, have supplied the
+proper bootup parameter for your synthesizer, Speakup will begin
+talking as soon as the kernel is loaded. In fact, it will talk a lot!
+It will speak all the boot up messages that the kernel prints on the
+screen during the boot process. This is because Speakup is not a
+separate screen reader, but is actually built into the operating
+system. Since almost all console applications must print text on the
+screen using the kernel, and must get their keyboard input through the
+kernel, they are automatically handled properly by Speakup. There are a
+few exceptions, but we'll come to those later.
+
+Note: In this guide I will refer to the numeric keypad as the keypad.
+This is done because the speakupmap.map file referred to later in this
+manual uses the term keypad instead of numeric keypad. Also I'm lazy
+and would rather only type one word. So keypad it is. Got it? Good.
+
+Most of the Speakup review keys are located on the keypad at the far
+right of the keyboard. The numlock key should be off, in order for these
+to work. If you toggle the numlock on, the keypad will produce numbers,
+which is exactly what you want for spreadsheets and such. For the
+purposes of this guide, you should have the numlock turned off, which is
+its default state at bootup.
+
+You probably won't want to listen to all the bootup messages every time
+you start your system, though it's a good idea to listen to them at
+least once, just so you'll know what kind of information is available to
+you during the boot process. You can always review these messages after
+bootup with the command:
+
+dmesg | more
+
+In order to speed the boot process, and to silence the speaking of the
+bootup messages, just press the keypad enter key. This key is located
+in the bottom right corner of the keypad. Speakup will shut up and stay
+that way, until you press another key.
+
+You can check to see if the boot process has completed by pressing the 8
+key on the keypad, which reads the current line. This also has the
+effect of starting Speakup talking again, so you can press keypad enter
+to silence it again if the boot process has not completed.
+
+When the boot process is complete, you will arrive at a "login" prompt.
+At this point, you'll need to type in your user id and password, as
+provided by your system administrator. You will hear Speakup speak the
+letters of your user id as you type it, but not the password. This is
+because the password is not displayed on the screen for security
+reasons. This has nothing to do with Speakup, it's a Linux security
+feature.
+
+Once you've logged in, you can run any Linux command or program which is
+allowed by your user id. Normal users will not be able to run programs
+which require root privileges.
+
+When you are running a program or command, Speakup will automatically
+speak new text as it arrives on the screen. You can at any time silence
+the speech with keypad enter, or use any of the Speakup review keys.
+
+Here are some basic Speakup review keys, and a short description of what
+they do.
+
+keypad 1 -- read previous character
+keypad 2 -- read current character (pressing keypad 2 twice rapidly will speak
+ the current character phonetically)
+keypad 3 -- read next character
+keypad 4 -- read previous word
+keypad 5 -- read current word (press twice rapidly to spell the current word)
+keypad 6 -- read next word
+keypad 7 -- read previous line
+keypad 8 -- read current line (press twice rapidly to hear how much the
+ text on the current line is indented)
+keypad 9 -- read next line
+keypad period -- speak current cursor position and announce current
+ virtual console
+
+It's also worth noting that the insert key on the keypad is mapped
+as the speakup key. Instead of pressing and releasing this key, as you
+do under DOS or Windows, you hold it like a shift key, and press other
+keys in combination with it. For example, repeatedly holding keypad
+insert, from now on called speakup, and keypad enter will toggle the
+speaking of new text on the screen on and off. This is not the same as
+just pressing keypad enter by itself, which just silences the speech
+until you hit another key. When you hit speakup plus keypad enter,
+Speakup will say, "You turned me off.", or "Hey, that's better." When
+Speakup is turned off, no new text on the screen will be spoken. You
+can still use the reading controls to review the screen however.
+
+3. Using the Speakup Help System
+
+In order to enter the Speakup help system, press and hold the speakup
+key (remember that this is the keypad insert key), and press the f1 key.
+You will hear the message:
+
+"Press space to leave help, cursor up or down to scroll, or a letter to
+go to commands in list."
+
+When you press the spacebar to leave the help system, you will hear:
+
+"Leaving help."
+
+While you are in the Speakup help system, you can scroll up or down
+through the list of available commands using the cursor keys. The list
+of commands is arranged in alphabetical order. If you wish to jump to
+commands in a specific part of the alphabet, you may press the letter of
+the alphabet you wish to jump to.
+
+You can also just explore by typing keyboard keys. Pressing keys will
+cause Speakup to speak the command associated with that key. For
+example, if you press the keypad 8 key, you will hear:
+
+"Keypad 8 is line, say current."
+
+You'll notice that some commands do not have keys assigned to them.
+This is because they are very infrequently used commands, and are also
+accessible through the sys system. We'll discuss the sys system later
+in this manual.
+
+You'll also notice that some commands have two keys assigned to them.
+This is because Speakup has a built in set of alternative key bindings
+for laptop users. The alternate speakup key is the caps lock key. You
+can press and hold the caps lock key, while pressing an alternate
+speakup command key to activate the command. On most laptops, the
+numeric keypad is defined as the keys in the j k l area of the keyboard.
+
+There is usually a function key which turns this keypad function on and
+off, and some other key which controls the numlock state. Toggling the
+keypad functionality on and off can become a royal pain. So, Speakup
+gives you a simple way to get at an alternative set of key mappings for
+your laptop. These are also available by default on desktop systems,
+because Speakup does not know whether it is running on a desktop or
+laptop. So you may choose which set of Speakup keys to use. Some
+system administrators may have chosen to compile Speakup for a desktop
+system without this set of alternate key bindings, but these details are
+beyond the scope of this manual. To use the caps lock for its normal
+purpose, hold the shift key while toggling the caps lock on and off. We
+should note here, that holding the caps lock key and pressing the z key
+will toggle the alternate j k l keypad on and off.
+
+4. Keys and Their Assigned Commands
+
+In this section, we'll go through a list of all the speakup keys and
+commands. You can also get a list of commands and assigned keys from
+the help system.
+
+The following list was taken from the speakupmap.map file. Key
+assignments are on the left of the equal sign, and the associated
+Speakup commands are on the right. The designation "spk" means to press
+and hold the speakup key, a.k.a. keypad insert, a.k.a. caps lock, while
+pressing the other specified key.
+
+spk key_f9 = punc_level_dec
+spk key_f10 = punc_level_inc
+spk key_f11 = reading_punc_dec
+spk key_f12 = reading_punc_inc
+spk key_1 = vol_dec
+spk key_2 = vol_inc
+spk key_3 = pitch_dec
+spk key_4 = pitch_inc
+spk key_5 = rate_dec
+spk key_6 = rate_inc
+key_kpasterisk = toggle_cursoring
+spk key_kpasterisk = speakup_goto
+spk key_f1 = speakup_help
+spk key_f2 = set_win
+spk key_f3 = clear_win
+spk key_f4 = enable_win
+spk key_f5 = edit_some
+spk key_f6 = edit_most
+spk key_f7 = edit_delim
+spk key_f8 = edit_repeat
+shift spk key_f9 = edit_exnum
+ key_kp7 = say_prev_line
+spk key_kp7 = left_edge
+ key_kp8 = say_line
+double key_kp8 = say_line_indent
+spk key_kp8 = say_from_top
+ key_kp9 = say_next_line
+spk key_kp9 = top_edge
+ key_kpminus = speakup_parked
+spk key_kpminus = say_char_num
+ key_kp4 = say_prev_word
+spk key_kp4 = say_from_left
+ key_kp5 = say_word
+double key_kp5 = spell_word
+spk key_kp5 = spell_phonetic
+ key_kp6 = say_next_word
+spk key_kp6 = say_to_right
+ key_kpplus = say_screen
+spk key_kpplus = say_win
+ key_kp1 = say_prev_char
+spk key_kp1 = right_edge
+ key_kp2 = say_char
+spk key_kp2 = say_to_bottom
+double key_kp2 = say_phonetic_char
+ key_kp3 = say_next_char
+spk key_kp3 = bottom_edge
+ key_kp0 = spk_key
+ key_kpdot = say_position
+spk key_kpdot = say_attributes
+key_kpenter = speakup_quiet
+spk key_kpenter = speakup_off
+key_sysrq = speech_kill
+ key_kpslash = speakup_cut
+spk key_kpslash = speakup_paste
+spk key_pageup = say_first_char
+spk key_pagedown = say_last_char
+key_capslock = spk_key
+ spk key_z = spk_lock
+key_leftmeta = spk_key
+ctrl spk key_0 = speakup_goto
+spk key_u = say_prev_line
+spk key_i = say_line
+double spk key_i = say_line_indent
+spk key_o = say_next_line
+spk key_minus = speakup_parked
+shift spk key_minus = say_char_num
+spk key_j = say_prev_word
+spk key_k = say_word
+double spk key_k = spell_word
+spk key_l = say_next_word
+spk key_m = say_prev_char
+spk key_comma = say_char
+double spk key_comma = say_phonetic_char
+spk key_dot = say_next_char
+spk key_n = say_position
+ ctrl spk key_m = left_edge
+ ctrl spk key_y = top_edge
+ ctrl spk key_dot = right_edge
+ctrl spk key_p = bottom_edge
+spk key_apostrophe = say_screen
+spk key_h = say_from_left
+spk key_y = say_from_top
+spk key_semicolon = say_to_right
+spk key_p = say_to_bottom
+spk key_slash = say_attributes
+ spk key_enter = speakup_quiet
+ ctrl spk key_enter = speakup_off
+ spk key_9 = speakup_cut
+spk key_8 = speakup_paste
+shift spk key_m = say_first_char
+ ctrl spk key_semicolon = say_last_char
+
+5. The Speakup Sys System
+
+The Speakup screen reader also creates a speakup subdirectory as a part
+of the sys system.
+
+As a convenience, run as root
+
+ln -s /sys/accessibility/speakup /speakup
+
+to directly access speakup parameters from /speakup.
+You can see these entries by typing the command:
+
+ls -1 /speakup/*
+
+If you issue the above ls command, you will get back something like
+this:
+
+/speakup/attrib_bleep
+/speakup/bell_pos
+/speakup/bleep_time
+/speakup/bleeps
+/speakup/cursor_time
+/speakup/delimiters
+/speakup/ex_num
+/speakup/key_echo
+/speakup/keymap
+/speakup/no_interrupt
+/speakup/punc_all
+/speakup/punc_level
+/speakup/punc_most
+/speakup/punc_some
+/speakup/reading_punc
+/speakup/repeats
+/speakup/say_control
+/speakup/say_word_ctl
+/speakup/silent
+/speakup/spell_delay
+/speakup/synth
+/speakup/synth_direct
+/speakup/version
+
+/speakup/i18n:
+announcements
+characters
+chartab
+colors
+ctl_keys
+formatted
+function_names
+key_names
+states
+
+/speakup/soft:
+caps_start
+caps_stop
+delay_time
+direct
+freq
+full_time
+jiffy_delta
+pitch
+inflection
+punct
+rate
+tone
+trigger_time
+voice
+vol
+
+Notice the two subdirectories of /speakup: /speakup/i18n and
+/speakup/soft.
+The i18n subdirectory is described in a later section.
+The files under /speakup/soft represent settings that are specific to the
+driver for the software synthesizer. If you use the LiteTalk, your
+synthesizer-specific settings would be found in /speakup/ltlk. In other words,
+a subdirectory named /speakup/KWD is created to hold parameters specific
+to the device whose keyword is KWD.
+These parameters include volume, rate, pitch, and others.
+
+In addition to using the Speakup hot keys to change such things as
+volume, pitch, and rate, you can also echo values to the appropriate
+entry in the /speakup directory. This is very useful, since it
+lets you control Speakup parameters from within a script. How you
+would write such scripts is somewhat beyond the scope of this manual,
+but I will include a couple of simple examples here to give you a
+general idea of what such scripts can do.
+
+Suppose for example, that you wanted to control both the punctuation
+level and the reading punctuation level at the same time. For
+simplicity, we'll call them punc0, punc1, punc2, and punc3. The scripts
+might look something like this:
+
+#!/bin/bash
+# punc0
+# set punc and reading punc levels to 0
+echo 0 >/speakup/punc_level
+echo 0 >/speakup/reading_punc
+echo Punctuation level set to 0.
+
+#!/bin/bash
+# punc1
+# set punc and reading punc levels to 1
+echo 1 >/speakup/punc_level
+echo 1 >/speakup/reading_punc
+echo Punctuation level set to 1.
+
+#!/bin/bash
+# punc2
+# set punc and reading punc levels to 2
+echo 2 >/speakup/punc_level
+echo 2 >/speakup/reading_punc
+echo Punctuation level set to 2.
+
+#!/bin/bash
+# punc3
+# set punc and reading punc levels to 3
+echo 3 >/speakup/punc_level
+echo 3 >/speakup/reading_punc
+echo Punctuation level set to 3.
+
+If you were to store these four small scripts in a directory in your
+path, perhaps /usr/local/bin, and set the permissions to 755 with the
+chmod command, then you could change the default reading punc and
+punctuation levels at the same time by issuing just one command. For
+example, if you were to execute the punc3 command at your shell prompt,
+then the reading punc and punc level would both get set to 3.
+
+I should note that the above scripts were written to work with bash, but
+regardless of which shell you use, you should be able to do something
+similar.
+
+The Speakup sys system also has another interesting use. You can echo
+Speakup parameters into the sys system in a script during system
+startup, and speakup will return to your preferred parameters every time
+the system is rebooted.
+
+Most of the Speakup sys parameters can be manipulated by a regular user
+on the system. However, there are a few parameters that are dangerous
+enough that they should only be manipulated by the root user on your
+system. There are even some parameters that are read only, and cannot
+be written to at all. For example, the version entry in the Speakup
+sys system is read only. This is because there is no reason for a user
+to tamper with the version number which is reported by Speakup. Doing
+an ls -l on /speakup/version will return this:
+
+-r--r--r-- 1 root root 0 Mar 21 13:46 /speakup/version
+
+As you can see, the version entry in the Speakup sys system is read
+only, is owned by root, and belongs to the root group. Doing a cat of
+/speakup/version will display the Speakup version number, like
+this:
+
+cat /speakup/version
+Speakup v-2.00 CVS: Thu Oct 21 10:38:21 EDT 2004
+synth dtlk version 1.1
+
+The display shows the Speakup version number, along with the version
+number of the driver for the current synthesizer.
+
+Looking at entries in the Speakup sys system can be useful in many
+ways. For example, you might wish to know what level your volume is set
+at. You could type:
+
+cat /speakup/KWD/vol
+# Replace KWD with the keyword for your synthesizer, E.G., ltlk for LiteTalk.
+5
+
+The number five which comes back is the level at which the synthesizer
+volume is set at.
+
+All the entries in the Speakup sys system are readable, some are
+writable by root only, and some are writable by everyone. Unless you
+know what you are doing, you should probably leave the ones that are
+writable by root only alone. Most of the names are self explanatory.
+Vol for controlling volume, pitch for pitch, inflection for pitch range, rate
+for controlling speaking rate, etc. If you find one you aren't sure about, you
+can post a query on the Speakup list.
+
+6. Changing Synthesizers
+
+It is possible to change to a different synthesizer while speakup is
+running. In other words, it is not necessary to reboot the system
+in order to use a different synthesizer. You can simply echo the
+synthesizer keyword to the /speakup/synth sys entry.
+Depending on your situation, you may wish to echo none to the synth
+sys entry, to disable speech while one synthesizer is disconnected and
+a second one is connected in its place. Then echo the keyword for the
+new synthesizer into the synth sys entry in order to start speech
+with the newly connected synthesizer. See the list of synthesizer
+keywords in section 1 to find the keyword which matches your synth.
+
+7. Loading modules
+
+As mentioned earlier, Speakup can either be completely compiled into the
+kernel, with the exception of the help module, or it can be compiled as
+a series of modules. When compiled as modules, Speakup will only be
+able to speak some of the bootup messages if your system administrator
+has configured the system to load the modules at boo time. The modules
+can be loaded after the file systems have been checked and mounted, or
+from an initrd. There is a third possibility. Speakup can be compiled
+with some components built into the kernel, and others as modules. As
+we'll see in the next section, this is particularly useful when you are
+working with software synthesizers.
+
+If Speakup is completely compiled as modules, then you must use the
+modprobe command to load Speakup. You do this by loading the module for
+the synthesizer driver you wish to use. The driver modules are all
+named speakup_<keyword>, where <keyword> is the keyword for the
+synthesizer you want. So, in order to load the driver for the DecTalk
+Express, you would type the following command:
+
+modprobe speakup_dectlk
+
+Issuing this command would load the DecTalk Express driver and all other
+related Speakup modules necessary to get Speakup up and running.
+
+To completely unload Speakup, again presuming that it is entirely built
+as modules, you would give the command:
+
+modprobe -r speakup_dectlk
+
+The above command assumes you were running a DecTalk Express. If you
+were using a different synth, then you would substitute its keyword in
+place of dectlk.
+
+If you have multiple drivers loaded, you need to unload all of them, in
+order to completely unload Speakup.
+For example, if you have loaded both the dectlk and ltlk drivers, use the
+command:
+modprobe -r speakup_dectlk speakup_ltlk
+
+You cannot unload the driver for software synthesizers when a user-space
+daemon is using /dev/softsynth. First, kill the daemon. Next, remove
+the driver with the command:
+modprobe -r speakup_soft
+
+Now, suppose we have a situation where the main Speakup component
+is built into the kernel, and some or all of the drivers are built as
+modules. Since the main part of Speakup is compiled into the kernel, a
+partial Speakup sys system has been created which we can take advantage
+of by simply echoing the synthesizer keyword into the
+/speakup/synth sys entry. This will cause the kernel to
+automatically load the appropriate driver module, and start Speakup
+talking. To switch to another synth, just echo a new keyword to the
+synth sys entry. For example, to load the DoubleTalk LT driver,
+you would type:
+
+echo ltlk >/speakup/synth
+
+You can use the modprobe -r command to unload driver modules, regardless
+of whether the main part of Speakup has been built into the kernel or
+not.
+
+8. Using Software Synthesizers
+
+Using a software synthesizer requires that some other software be
+installed and running on your system. For this reason, software
+synthesizers are not available for use at bootup, or during a system
+installation process.
+There are two freely-available solutions for software speech: Espeakup and
+Speech Dispatcher.
+These are described in subsections 8.1 and 8.2, respectively.
+
+During the rest of this section, we assume that speakup_soft is either
+built in to your kernel, or loaded as a module.
+
+If your system does not have udev installed , before you can use a
+software synthesizer, you must have created the /dev/softsynth device.
+If you have not already done so, issue the following commands as root:
+
+cd /dev
+mknod softsynth c 10 26
+
+While we are at it, we might just as well create the /dev/synth device,
+which can be used to let user space programs send information to your
+synthesizer. To create /dev/synth, change to the /dev directory, and
+issue the following command as root:
+
+mknod synth c 10 25
+
+of both.
+
+8.1. Espeakup
+
+Espeakup is a connector between Speakup and the eSpeak software synthesizer.
+Espeakup may already be available as a package for your distribution
+of Linux. If it is not packaged, you need to install it manually.
+You can find it in the contrib/ subdirectory of the Speakup sources.
+The filename is espeakup-$VERSION.tar.bz2, where $VERSION
+depends on the current release of Espeakup. The Speakup 3.1.2 source
+ships with version 0.71 of Espeakup.
+The README file included with the Espeakup sources describes the process
+of manual installation.
+
+Assuming that Espeakup is installed, either by the user or by the distributor,
+follow these steps to use it.
+
+Tell Speakup to use the "soft driver:
+echo soft > /speakup/synth
+
+Finally, start the espeakup program. There are two ways to do it.
+Both require root privileges.
+
+If Espeakup was installed as a package for your Linux distribution,
+you probably have a distribution-specific script that controls the operation
+of the daemon. Look for a file named espeakup under /etc/init.d or
+/etc/rc.d. Execute the following command with root privileges:
+/etc/init.d/espeakup start
+Replace init.d with rc.d, if your distribution uses scripts located under
+/etc/rc.d.
+Your distribution will also have a procedure for starting daemons at
+boot-time, so it is possible to have software speech as soon as user-space
+daemons are started by the bootup scripts.
+These procedures are not described in this document.
+
+If you built Espeakup manually, the "make install" step placed the binary
+under /usr/bin.
+Run the following command as root:
+/usr/bin/espeakup
+Espeakup should start speaking.
+
+8.2. Speech Dispatcher
+
+For this option, you must have a package called
+Speech Dispatcher running on your system, and it must be configured to
+work with one of its supported software synthesizers.
+
+Two open source synthesizers you might use are Flite and Festival. You
+might also choose to purchase the Software DecTalk from Fonix Sales Inc.
+If you run a google search for Fonix, you'll find their web site.
+
+You can obtain a copy of Speech Dispatcher from free(b)soft at
+http://www.freebsoft.org/. Follow the installation instructions that
+come with Speech Dispatcher in order to install and configure Speech
+Dispatcher. You can check out the web site for your Linux distribution
+in order to get a copy of either Flite or Festival. Your Linux
+distribution may also have a precompiled Speech Dispatcher package.
+
+Once you've installed, configured, and tested Speech Dispatcher with your
+chosen software synthesizer, you still need one more piece of software
+in order to make things work. You need a package called speechd-up.
+You get it from the free(b)soft web site mentioned above. After you've
+compiled and installed speechd-up, you are almost ready to begin using
+your software synthesizer.
+
+Now you can begin using your software synthesizer. In order to do so,
+echo the soft keyword to the synth sys entry like this:
+
+echo soft >/speakup/synth
+
+Next run the speechd_up command like this:
+
+speechd_up &
+
+Your synth should now start talking, and you should be able to adjust
+the pitch, rate, etc.
+
+9. Using The DecTalk PC Card
+
+The DecTalk PC card is an ISA card that is inserted into one of the ISA
+slots in your computer. It requires that the DecTalk PC software be
+installed on your computer, and that the software be loaded onto the
+Dectalk PC card before it can be used.
+
+You can get the dec_pc.tgz file from the linux-speakup.org site. The
+dec_pc.tgz file is in the ~ftp/pub/linux/speakup directory.
+
+After you have downloaded the dec_pc.tgz file, untar it in your home
+directory, and read the Readme file in the newly created dec_pc
+directory.
+
+The easiest way to get the software working is to copy the entire dec_pc
+directory into /user/local/lib. To do this, su to root in your home
+directory, and issue the command:
+
+cp dec_pc /usr/local/lib
+
+You will need to copy the dtload command from the dec_pc directory to a
+directory in your path. Either /usr/bin or /usr/local/bin is a good
+choice.
+
+You can now run the dtload command in order to load the DecTalk PC
+software onto the card. After you have done this, echo the decpc
+keyword to the synth entry in the sys system like this:
+
+echo decpc >/speakup/synth
+
+Your DecTalk PC should start talking, and then you can adjust the pitch,
+rate, volume, voice, etc. The voice entry in the Speakup sys system
+will accept a number from 0 through 7 for the DecTalk PC synthesizer,
+which will give you access to some of the DecTalk voices.
+
+10. Using Cursor Tracking
+
+In Speakup version 2.0 and later, cursor tracking is turned on by
+default. This means that when you are using an editor, Speakup will
+automatically speak characters as you move left and right with the
+cursor keys, and lines as you move up and down with the cursor keys.
+This is the traditional sort of cursor tracking.
+Recent versions of Speakup provide two additional ways to control the
+text that is spoken when the cursor is moved:
+"highlight tracking" and "read window."
+They are described later in this section.
+Sometimes, these modes get in your way, so you can disable cursor tracking
+altogether.
+
+You may select among the various forms of cursor tracking using the keypad
+asterisk key.
+Each time you press this key, a new mode is selected, and Speakup speaks
+the name of the new mode. The names for the four possible states of cursor
+tracking are: "cursoring on", "highlight tracking", "read window",
+and "cursoring off." The keypad asterisk key moves through the list of
+modes in a circular fashion.
+
+If highlight tracking is enabled, Speakup tracks highlighted text,
+rather than the cursor itself. When you move the cursor with the arrow keys,
+Speakup speaks the currently highlighted information.
+This is useful when moving through various menus and dialog boxes.
+If cursor tracking isn't helping you while navigating a menu,
+try highlight tracking.
+
+With the "read window" variety of cursor tracking, you can limit the text
+that Speakup speaks by specifying a window of interest on the screen.
+See section 15 for a description of the process of defining windows.
+When you move the cursor via the arrow keys, Speakup only speaks
+the contents of the window. This is especially helpful when you are hearing
+superfluous speech. Consider the following example.
+
+Suppose that you are at a shell prompt. You use bash, and you want to
+explore your command history using the up and down arrow keys. If you
+have enabled cursor tracking, you will hear two pieces of information.
+Speakup speaks both your shell prompt and the current entry from the
+command history. You may not want to hear the prompt repeated
+each time you move, so you can silence it by specifying a window. Find
+the last line of text on the screen. Clear the current window by pressing
+the key combination speakup f3. Use the review cursor to find the first
+character that follows your shell prompt. Press speakup + f2 twice, to
+define a one-line window. The boundaries of the window are the
+character following the shell prompt and the end of the line. Now, cycle
+through the cursor tracking modes using keypad asterisk, until Speakup
+says "read window." Move through your history using your arrow keys.
+You will notice that Speakup no longer speaks the redundant prompt.
+
+Some folks like to turn cursor tracking off while they are using the
+lynx web browser. You definitely want to turn cursor tracking off when
+you are using the alsamixer application. Otherwise, you won't be able
+to hear your mixer settings while you are using the arrow keys.
+
+11. Cut and Paste
+
+One of Speakup's more useful features is the ability to cut and paste
+text on the screen. This means that you can capture information from a
+program, and paste that captured text into a different place in the
+program, or into an entirely different program, which may even be
+running on a different console.
+
+For example, in this manual, we have made references to several web
+sites. It would be nice if you could cut and paste these urls into your
+web browser. Speakup does this quite nicely. Suppose you wanted to
+past the following url into your browser:
+
+http://linux-speakup.org/
+
+Use the speakup review keys to position the reading cursor on the first
+character of the above url. When the reading cursor is in position,
+press the keypad slash key once. Speakup will say, "mark". Next,
+position the reading cursor on the rightmost character of the above
+url. Press the keypad slash key once again to actually cut the text
+from the screen. Speakup will say, "cut". Although we call this
+cutting, Speakup does not actually delete the cut text from the screen.
+It makes a copy of the text in a special buffer for later pasting.
+
+Now that you have the url cut from the screen, you can paste it into
+your browser, or even paste the url on a command line as an argument to
+your browser.
+
+Suppose you want to start lynx and go to the Speakup site.
+
+You can switch to a different console with the alt left and right
+arrows, or you can switch to a specific console by typing alt and a
+function key. These are not Speakup commands, just standard Linux
+console capabilities.
+
+Once you've changed to an appropriate console, and are at a shell prompt,
+type the word lynx, followed by a space. Now press and hold the speakup
+key, while you type the keypad slash character. The url will be pasted
+onto the command line, just as though you had typed it in. Press the
+enter key to execute the command.
+
+The paste buffer will continue to hold the cut information, until a new
+mark and cut operation is carried out. This means you can paste the cut
+information as many times as you like before doing another cut
+operation.
+
+You are not limited to cutting and pasting only one line on the screen.
+You can also cut and paste rectangular regions of the screen. Just
+position the reading cursor at the top left corner of the text to be
+cut, mark it with the keypad slash key, then position the reading cursor
+at the bottom right corner of the region to be cut, and cut it with the
+keypad slash key.
+
+12. Changing the Pronunciation of Characters
+
+Through the /speakup/i18n/characters sys entry, Speakup gives you the
+ability to change how Speakup pronounces a given character. You could,
+for example, change how some punctuation characters are spoken. You can
+even change how Speakup will pronounce certain letters.
+
+You may, for example, wish to change how Speakup pronounces the z
+character. The author of Speakup, Kirk Reiser, is Canadian, and thus
+believes that the z should be pronounced zed. If you are an American,
+you might wish to use the zee pronunciation instead of zed. You can
+change the pronunciation of both the upper and lower case z with the
+following two commands:
+
+echo 90 zee >/speakup/characters
+echo 122 zee >/speakup/characters
+
+Let's examine the parts of the two previous commands. They are issued
+at the shell prompt, and could be placed in a startup script.
+
+The word echo tells the shell that you want to have it display the
+string of characters that follow the word echo. If you were to just
+type:
+
+echo hello.
+
+You would get the word hello printed on your screen as soon as you
+pressed the enter key. In this case, we are echoing strings that we
+want to be redirected into the sys system.
+
+The numbers 90 and 122 in the above echo commands are the ascii numeric
+values for the upper and lower case z, the characters we wish to change.
+
+The string zee is the pronunciation that we want Speakup to use for the
+upper and lower case z.
+
+The > symbol redirects the output of the echo command to a file, just
+like in DOS, or at the Windows command prompt.
+
+And finally, /speakup/i18n/characters is the file entry in the sys system
+where we want the output to be directed. Speakup looks at the numeric
+value of the character we want to change, and inserts the pronunciation
+string into an internal table.
+
+You can look at the whole table with the following command:
+
+cat /speakup/i18n/characters
+
+Speakup will then print out the entire character pronunciation table. I
+won't display it here, but leave you to look at it at your convenience.
+
+13. Mapping Keys
+
+Speakup has the capability of allowing you to assign or "map" keys to
+internal Speakup commands. This section necessarily assumes you have a
+Linux kernel source tree installed, and that it has been patched and
+configured with Speakup. How you do this is beyond the scope of this
+manual. For this information, visit the Speakup web site at
+http://linux-speakup.org/. The reason you'll need the kernel source
+tree patched with Speakup is that the genmap utility you'll need for
+processing keymaps is in the
+/usr/src/linux-<version_number>/drivers/char/speakup directory. The
+<version_number> in the above directory path is the version number of
+the Linux source tree you are working with.
+
+So ok, you've gone off and gotten your kernel source tree, and patched
+and configured it. Now you can start manipulating keymaps.
+
+You can either use the
+/usr/src/linux-<version_number>/drivers/char/speakup/speakupmap.map file
+included with the Speakup source, or you can cut and paste the copy in
+section 4 into a separate file. If you use the one in the Speakup
+source tree, make sure you make a backup of it before you start making
+changes. You have been warned!
+
+Suppose that you want to swap the key assignments for the Speakup
+say_last_char and the Speakup say_first_char commands. The
+speakupmap.map lists the key mappings for these two commands as follows:
+
+spk key_pageup = say_first_char
+spk key_pagedown = say_last_char
+
+You can edit your copy of the speakupmap.map file and swap the command
+names on the right side of the = (equals) sign. You did make a backup,
+right? The new keymap lines would look like this:
+
+spk key_pageup = say_last_char
+spk key_pagedown = say_first_char
+
+After you edit your copy of the speakupmap.map file, save it under a new
+file name, perhaps newmap.map. Then exit your editor and return to the
+shell prompt.
+
+You are now ready to load your keymap with your swapped key assignments.
+ Assuming that you saved your new keymap as the file newmap.map, you
+would load your keymap into the sys system like this:
+
+/usr/src/linux-<version_number>/drivers/char/speakup/genmap newmap.map
+>/speakup/keymap
+
+Remember to substitute your kernel version number for the
+<version_number> in the above command. Also note that although the
+above command wrapped onto two lines in this document, you should type
+it all on one line.
+
+Your say first and say last characters should now be swapped. Pressing
+speakup pagedown should read you the first non-whitespace character on
+the line your reading cursor is in, and pressing speakup pageup should
+read you the last character on the line your reading cursor is in.
+
+You should note that these new mappings will only stay in effect until
+you reboot, or until you load another keymap.
+
+One final warning. If you try to load a partial map, you will quickly
+find that all the mappings you didn't include in your file got deleted
+from the working map. Be extremely careful, and always make a backup!
+You have been warned!
+
+14. Internationalizing Speakup
+
+Speakup indicates various conditions to the user by speaking messages.
+For instance, when you move to the left edge of the screen with the
+review keys, Speakup says, "left."
+Prior to version 3.1.0 of Speakup, all of these messages were in English,
+and they could not be changed. If you used a non-English synthesizer,
+you still heard English messages, such as "left" and "cursoring on."
+In version 3.1.0 or higher, one may load translations for the various
+messages via the /sys filesystem.
+
+The directory /speakup/i18n contains several collections of messages.
+Each group of messages is stored in its own file.
+The following section lists all of these files, along with a brief description
+of each.
+
+14.1. Files Under the i18n Subdirectory
+
+* announcements:
+This file contains various general announcements, most of which cannot
+be categorized. You will find messages such as "You killed Speakup",
+"I'm alive", "leaving help", "parked", "unparked", and others.
+You will also find the names of the screen edges and cursor tracking modes
+here.
+
+* characters:
+See section 12 for a description of this file.
+
+* chartab:
+See section 12. Unlike the rest of the files in the i18n subdirectory,
+this one does not contain messages to be spoken.
+
+* colors:
+When you use the "say attributes" function, Speakup says the name of the
+foreground and background colors. These names come from the i18n/colors
+file.
+
+* ctl_keys:
+Here, you will find names of control keys. These are used with Speakup's
+say_control feature.
+
+* formatted:
+This group of messages contains embedded formatting codes, to specify
+the type and width of displayed data. If you change these, you must
+preserve all of the formatting codes, and they must appear in the order
+used by the default messages.
+
+* function_names:
+Here, you will find a list of names for Speakup functions. These are used
+by the help system. For example, suppose that you have activated help mode,
+and you pressed keypad 3. Speakup says:
+"keypad 3 is character, say next."
+The message "character, say next" names a Speakup function, and it
+comes from this function_names file.
+
+* key_names:
+Again, key_names is used by Speakup's help system. In the previous
+example, Speakup said that you pressed "keypad 3."
+This name came from the key_names file.
+
+* states:
+This file contains names for key states.
+Again, these are part of the help system. For instance, if you had pressed
+speakup + keypad 3, you would hear:
+"speakup keypad 3 is go to bottom edge."
+The speakup key is depressed, so the name of the key state is speakup.
+This part of the message comes from the states collection.
+
+14.2. Loading Your Own Messages
+
+The files under the i18n subdirectory all follow the same format.
+They consist of lines, with one message per line.
+Each message is represented by a number, followed by the text of the message.
+The number is the position of the message in the given collection.
+For example, if you view the file /speakup/i18n/colors, you will see the
+following list:
+
+0 black
+1 blue
+2 green
+3 cyan
+4 red
+5 magenta
+6 yellow
+7 white
+8 grey
+
+You can change one message, or you can change a whole group.
+To load a whole collection of messages from a new source, simply use
+the cp command:
+cp ~/my_colors /speakup/i18n/colors
+You can change an individual message with the echo command,
+as shown in the following example.
+
+The Spanish name for the color blue is azul.
+Looking at the colors file, we see that the name "blue" is at position 1
+within the colors group. Let's change blue to azul:
+echo '1 azul' > /speakup/i18n/colors
+The next time that Speakup says message 1 from the colors group, it will
+say "azul", rather than "blue."
+
+In the future, translations into various languages will be made available,
+and most users will just load the files necessary for their language.
+
+14.3. No Support for Non-Western-European Languages
+
+As of the current release, Speakup only supports Western European languages.
+Support for the extended characters used by languages outside of the Western
+European family of languages is a work in progress.
+
+15. Using Speakup's Windowing Capability
+
+Speakup has the capability of defining and manipulating windows on the
+screen. Speakup uses the term "Window", to mean a user defined area of
+the screen. The key strokes for defining and manipulating Speakup
+windows are as follows:
+
+speakup + f2 -- Set the bounds of the window.
+Speakup + f3 -- clear the current window definition.
+speakup + f4 -- Toggle window silence on and off.
+speakup + keypad plus -- Say the currently defined window.
+
+These capabilities are useful for tracking a certain part of the screen
+without rereading the whole screen, or for silencing a part of the
+screen that is constantly changing, such as a clock or status line.
+
+There is no way to save these window settings, and you can only have one
+window defined for each virtual console. There is also no way to have
+windows automatically defined for specific applications.
+
+In order to define a window, use the review keys to move your reading
+cursor to the beginning of the area you want to define. Then press
+speakup + f2. Speakup will tell you that the window starts at the
+indicated row and column position. Then move the reading cursor to the
+end of the area to be defined as a window, and press speakup + f2 again.
+ If there is more than one line in the window, Speakup will tell you
+that the window ends at the indicated row and column position. If there
+is only one line in the window, then Speakup will tell you that the
+window is the specified line on the screen. If you are only defining a
+one line window, you can just press speakup + f2 twice after placing the
+reading cursor on the line you want to define as a window. It is not
+necessary to position the reading cursor at the end of the line in order
+to define the whole line as a window.
+
+16. Tools for Controlling Speakup
+
+The speakup distribution includes extra tools (in the tools directory)
+which were written to make speakup easier to use. This section will
+briefly describe the use of these tools.
+
+16.1. Speakupconf
+
+speakupconf began life as a contribution from Steve Holmes, a member of
+the speakup community. We would like to thank him for his work on the
+early versions of this project.
+
+This script may be installed as part of your linux distribution, but if
+it isn't, the recommended places to put it are /usr/local/bin or
+/usr/bin. This script can be run by any user, so it does not require
+root privileges.
+
+Speakupconf allows you to save and load your Speakup settings. It works
+by reading and writing the /sys files described above.
+
+The directory that speakupconf uses to store your settings depends on
+whether it is run from the root account. If you execute speakupconf as
+root, it uses the directory /etc/speakup. Otherwise, it uses the directory
+~/.speakup, where ~ is your home directory.
+Anyone who needs to use Speakup from your console can load his own custom
+settings with this script.
+
+speakupconf takes one required argument: load or save.
+Use the command
+speakupconf save
+to save your Speakup settings, and
+speakupconf load
+to load them into Speakup.
+A second argument may be specified to use an alternate directory to
+load or save the speakup parameters.
+
+16.2. Talkwith
+
+Charles Hallenbeck, another member of the speakup community, wrote the
+initial versions of this script, and we would also like to thank him for
+his work on it.
+
+This script needs root privileges to run, so if it is not installed as
+part of your linux distribution, the recommended places to install it
+are /usr/local/sbin or /usr/sbin.
+
+Talkwith allows you to switch synthesizers on the fly. It takes a synthesizer
+name as an argument. For instance,
+talkwith dectlk
+causes Speakup to use the DecTalk Express. If you wish to switch to a
+software synthesizer, you must also indicate which daemon you wish to
+use. There are two possible choices:
+spd and espeakup. spd is an abbreviation for speechd-up.
+If you wish to use espeakup for software synthesis, give the command
+talkwith soft espeakup
+To use speechd-up, type:
+talkwith soft spd
+Any arguments that follow the name of the daemon are passed to the daemon
+when it is invoked. For instance:
+talkwith espeakup --default-voice=fr
+causes espeakup to use the French voice.
+Note that talkwith must always be executed with root privileges.
+
+Talkwith does not attempt to load your settings after the new
+synthesizer is activated. You can use speakupconf to load your settings
+if desired.
+
+ GNU Free Documentation License
+ Version 1.2, November 2002
+
+
+ Copyright (C) 2000,2001,2002 Free Software Foundation, Inc.
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+
+0. PREAMBLE
+
+The purpose of this License is to make a manual, textbook, or other
+functional and useful document "free" in the sense of freedom: to
+assure everyone the effective freedom to copy and redistribute it,
+with or without modifying it, either commercially or noncommercially.
+Secondarily, this License preserves for the author and publisher a way
+to get credit for their work, while not being considered responsible
+for modifications made by others.
+
+This License is a kind of "copyleft", which means that derivative
+works of the document must themselves be free in the same sense. It
+complements the GNU General Public License, which is a copyleft
+license designed for free software.
+
+We have designed this License in order to use it for manuals for free
+software, because free software needs free documentation: a free
+program should come with manuals providing the same freedoms that the
+software does. But this License is not limited to software manuals;
+it can be used for any textual work, regardless of subject matter or
+whether it is published as a printed book. We recommend this License
+principally for works whose purpose is instruction or reference.
+
+
+1. APPLICABILITY AND DEFINITIONS
+
+This License applies to any manual or other work, in any medium, that
+contains a notice placed by the copyright holder saying it can be
+distributed under the terms of this License. Such a notice grants a
+world-wide, royalty-free license, unlimited in duration, to use that
+work under the conditions stated herein. The "Document", below,
+refers to any such manual or work. Any member of the public is a
+licensee, and is addressed as "you". You accept the license if you
+copy, modify or distribute the work in a way requiring permission
+under copyright law.
+
+A "Modified Version" of the Document means any work containing the
+Document or a portion of it, either copied verbatim, or with
+modifications and/or translated into another language.
+
+A "Secondary Section" is a named appendix or a front-matter section of
+the Document that deals exclusively with the relationship of the
+publishers or authors of the Document to the Document's overall subject
+(or to related matters) and contains nothing that could fall directly
+within that overall subject. (Thus, if the Document is in part a
+textbook of mathematics, a Secondary Section may not explain any
+mathematics.) The relationship could be a matter of historical
+connection with the subject or with related matters, or of legal,
+commercial, philosophical, ethical or political position regarding
+them.
+
+The "Invariant Sections" are certain Secondary Sections whose titles
+are designated, as being those of Invariant Sections, in the notice
+that says that the Document is released under this License. If a
+section does not fit the above definition of Secondary then it is not
+allowed to be designated as Invariant. The Document may contain zero
+Invariant Sections. If the Document does not identify any Invariant
+Sections then there are none.
+
+The "Cover Texts" are certain short passages of text that are listed,
+as Front-Cover Texts or Back-Cover Texts, in the notice that says that
+the Document is released under this License. A Front-Cover Text may
+be at most 5 words, and a Back-Cover Text may be at most 25 words.
+
+A "Transparent" copy of the Document means a machine-readable copy,
+represented in a format whose specification is available to the
+general public, that is suitable for revising the document
+straightforwardly with generic text editors or (for images composed of
+pixels) generic paint programs or (for drawings) some widely available
+drawing editor, and that is suitable for input to text formatters or
+for automatic translation to a variety of formats suitable for input
+to text formatters. A copy made in an otherwise Transparent file
+format whose markup, or absence of markup, has been arranged to thwart
+or discourage subsequent modification by readers is not Transparent.
+An image format is not Transparent if used for any substantial amount
+of text. A copy that is not "Transparent" is called "Opaque".
+
+Examples of suitable formats for Transparent copies include plain
+ASCII without markup, Texinfo input format, LaTeX input format, SGML
+or XML using a publicly available DTD, and standard-conforming simple
+HTML, PostScript or PDF designed for human modification. Examples of
+transparent image formats include PNG, XCF and JPG. Opaque formats
+include proprietary formats that can be read and edited only by
+proprietary word processors, SGML or XML for which the DTD and/or
+processing tools are not generally available, and the
+machine-generated HTML, PostScript or PDF produced by some word
+processors for output purposes only.
+
+The "Title Page" means, for a printed book, the title page itself,
+plus such following pages as are needed to hold, legibly, the material
+this License requires to appear in the title page. For works in
+formats which do not have any title page as such, "Title Page" means
+the text near the most prominent appearance of the work's title,
+preceding the beginning of the body of the text.
+
+A section "Entitled XYZ" means a named subunit of the Document whose
+title either is precisely XYZ or contains XYZ in parentheses following
+text that translates XYZ in another language. (Here XYZ stands for a
+specific section name mentioned below, such as "Acknowledgements",
+"Dedications", "Endorsements", or "History".) To "Preserve the Title"
+of such a section when you modify the Document means that it remains a
+section "Entitled XYZ" according to this definition.
+
+The Document may include Warranty Disclaimers next to the notice which
+states that this License applies to the Document. These Warranty
+Disclaimers are considered to be included by reference in this
+License, but only as regards disclaiming warranties: any other
+implication that these Warranty Disclaimers may have is void and has
+no effect on the meaning of this License.
+
+
+2. VERBATIM COPYING
+
+You may copy and distribute the Document in any medium, either
+commercially or noncommercially, provided that this License, the
+copyright notices, and the license notice saying this License applies
+to the Document are reproduced in all copies, and that you add no other
+conditions whatsoever to those of this License. You may not use
+technical measures to obstruct or control the reading or further
+copying of the copies you make or distribute. However, you may accept
+compensation in exchange for copies. If you distribute a large enough
+number of copies you must also follow the conditions in section 3.
+
+You may also lend copies, under the same conditions stated above, and
+you may publicly display copies.
+
+
+3. COPYING IN QUANTITY
+
+If you publish printed copies (or copies in media that commonly have
+printed covers) of the Document, numbering more than 100, and the
+Document's license notice requires Cover Texts, you must enclose the
+copies in covers that carry, clearly and legibly, all these Cover
+Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on
+the back cover. Both covers must also clearly and legibly identify
+you as the publisher of these copies. The front cover must present
+the full title with all words of the title equally prominent and
+visible. You may add other material on the covers in addition.
+Copying with changes limited to the covers, as long as they preserve
+the title of the Document and satisfy these conditions, can be treated
+as verbatim copying in other respects.
+
+If the required texts for either cover are too voluminous to fit
+legibly, you should put the first ones listed (as many as fit
+reasonably) on the actual cover, and continue the rest onto adjacent
+pages.
+
+If you publish or distribute Opaque copies of the Document numbering
+more than 100, you must either include a machine-readable Transparent
+copy along with each Opaque copy, or state in or with each Opaque copy
+a computer-network location from which the general network-using
+public has access to download using public-standard network protocols
+a complete Transparent copy of the Document, free of added material.
+If you use the latter option, you must take reasonably prudent steps,
+when you begin distribution of Opaque copies in quantity, to ensure
+that this Transparent copy will remain thus accessible at the stated
+location until at least one year after the last time you distribute an
+Opaque copy (directly or through your agents or retailers) of that
+edition to the public.
+
+It is requested, but not required, that you contact the authors of the
+Document well before redistributing any large number of copies, to give
+them a chance to provide you with an updated version of the Document.
+
+
+4. MODIFICATIONS
+
+You may copy and distribute a Modified Version of the Document under
+the conditions of sections 2 and 3 above, provided that you release
+the Modified Version under precisely this License, with the Modified
+Version filling the role of the Document, thus licensing distribution
+and modification of the Modified Version to whoever possesses a copy
+of it. In addition, you must do these things in the Modified Version:
+
+A. Use in the Title Page (and on the covers, if any) a title distinct
+ from that of the Document, and from those of previous versions
+ (which should, if there were any, be listed in the History section
+ of the Document). You may use the same title as a previous version
+ if the original publisher of that version gives permission.
+B. List on the Title Page, as authors, one or more persons or entities
+ responsible for authorship of the modifications in the Modified
+ Version, together with at least five of the principal authors of the
+ Document (all of its principal authors, if it has fewer than five),
+ unless they release you from this requirement.
+C. State on the Title page the name of the publisher of the
+ Modified Version, as the publisher.
+D. Preserve all the copyright notices of the Document.
+E. Add an appropriate copyright notice for your modifications
+ adjacent to the other copyright notices.
+F. Include, immediately after the copyright notices, a license notice
+ giving the public permission to use the Modified Version under the
+ terms of this License, in the form shown in the Addendum below.
+G. Preserve in that license notice the full lists of Invariant Sections
+ and required Cover Texts given in the Document's license notice.
+H. Include an unaltered copy of this License.
+I. Preserve the section Entitled "History", Preserve its Title, and add
+ to it an item stating at least the title, year, new authors, and
+ publisher of the Modified Version as given on the Title Page. If
+ there is no section Entitled "History" in the Document, create one
+ stating the title, year, authors, and publisher of the Document as
+ given on its Title Page, then add an item describing the Modified
+ Version as stated in the previous sentence.
+J. Preserve the network location, if any, given in the Document for
+ public access to a Transparent copy of the Document, and likewise
+ the network locations given in the Document for previous versions
+ it was based on. These may be placed in the "History" section.
+ You may omit a network location for a work that was published at
+ least four years before the Document itself, or if the original
+ publisher of the version it refers to gives permission.
+K. For any section Entitled "Acknowledgements" or "Dedications",
+ Preserve the Title of the section, and preserve in the section all
+ the substance and tone of each of the contributor acknowledgements
+ and/or dedications given therein.
+L. Preserve all the Invariant Sections of the Document,
+ unaltered in their text and in their titles. Section numbers
+ or the equivalent are not considered part of the section titles.
+M. Delete any section Entitled "Endorsements". Such a section
+ may not be included in the Modified Version.
+N. Do not retitle any existing section to be Entitled "Endorsements"
+ or to conflict in title with any Invariant Section.
+O. Preserve any Warranty Disclaimers.
+
+If the Modified Version includes new front-matter sections or
+appendices that qualify as Secondary Sections and contain no material
+copied from the Document, you may at your option designate some or all
+of these sections as invariant. To do this, add their titles to the
+list of Invariant Sections in the Modified Version's license notice.
+These titles must be distinct from any other section titles.
+
+You may add a section Entitled "Endorsements", provided it contains
+nothing but endorsements of your Modified Version by various
+parties--for example, statements of peer review or that the text has
+been approved by an organization as the authoritative definition of a
+standard.
+
+You may add a passage of up to five words as a Front-Cover Text, and a
+passage of up to 25 words as a Back-Cover Text, to the end of the list
+of Cover Texts in the Modified Version. Only one passage of
+Front-Cover Text and one of Back-Cover Text may be added by (or
+through arrangements made by) any one entity. If the Document already
+includes a cover text for the same cover, previously added by you or
+by arrangement made by the same entity you are acting on behalf of,
+you may not add another; but you may replace the old one, on explicit
+permission from the previous publisher that added the old one.
+
+The author(s) and publisher(s) of the Document do not by this License
+give permission to use their names for publicity for or to assert or
+imply endorsement of any Modified Version.
+
+
+5. COMBINING DOCUMENTS
+
+You may combine the Document with other documents released under this
+License, under the terms defined in section 4 above for modified
+versions, provided that you include in the combination all of the
+Invariant Sections of all of the original documents, unmodified, and
+list them all as Invariant Sections of your combined work in its
+license notice, and that you preserve all their Warranty Disclaimers.
+
+The combined work need only contain one copy of this License, and
+multiple identical Invariant Sections may be replaced with a single
+copy. If there are multiple Invariant Sections with the same name but
+different contents, make the title of each such section unique by
+adding at the end of it, in parentheses, the name of the original
+author or publisher of that section if known, or else a unique number.
+Make the same adjustment to the section titles in the list of
+Invariant Sections in the license notice of the combined work.
+
+In the combination, you must combine any sections Entitled "History"
+in the various original documents, forming one section Entitled
+"History"; likewise combine any sections Entitled "Acknowledgements",
+and any sections Entitled "Dedications". You must delete all sections
+Entitled "Endorsements".
+
+
+6. COLLECTIONS OF DOCUMENTS
+
+You may make a collection consisting of the Document and other documents
+released under this License, and replace the individual copies of this
+License in the various documents with a single copy that is included in
+the collection, provided that you follow the rules of this License for
+verbatim copying of each of the documents in all other respects.
+
+You may extract a single document from such a collection, and distribute
+it individually under this License, provided you insert a copy of this
+License into the extracted document, and follow this License in all
+other respects regarding verbatim copying of that document.
+
+
+7. AGGREGATION WITH INDEPENDENT WORKS
+
+A compilation of the Document or its derivatives with other separate
+and independent documents or works, in or on a volume of a storage or
+distribution medium, is called an "aggregate" if the copyright
+resulting from the compilation is not used to limit the legal rights
+of the compilation's users beyond what the individual works permit.
+When the Document is included in an aggregate, this License does not
+apply to the other works in the aggregate which are not themselves
+derivative works of the Document.
+
+If the Cover Text requirement of section 3 is applicable to these
+copies of the Document, then if the Document is less than one half of
+the entire aggregate, the Document's Cover Texts may be placed on
+covers that bracket the Document within the aggregate, or the
+electronic equivalent of covers if the Document is in electronic form.
+Otherwise they must appear on printed covers that bracket the whole
+aggregate.
+
+
+8. TRANSLATION
+
+Translation is considered a kind of modification, so you may
+distribute translations of the Document under the terms of section 4.
+Replacing Invariant Sections with translations requires special
+permission from their copyright holders, but you may include
+translations of some or all Invariant Sections in addition to the
+original versions of these Invariant Sections. You may include a
+translation of this License, and all the license notices in the
+Document, and any Warranty Disclaimers, provided that you also include
+the original English version of this License and the original versions
+of those notices and disclaimers. In case of a disagreement between
+the translation and the original version of this License or a notice
+or disclaimer, the original version will prevail.
+
+If a section in the Document is Entitled "Acknowledgements",
+"Dedications", or "History", the requirement (section 4) to Preserve
+its Title (section 1) will typically require changing the actual
+title.
+
+
+9. TERMINATION
+
+You may not copy, modify, sublicense, or distribute the Document except
+as expressly provided for under this License. Any other attempt to
+copy, modify, sublicense or distribute the Document is void, and will
+automatically terminate your rights under this License. However,
+parties who have received copies, or rights, from you under this
+License will not have their licenses terminated so long as such
+parties remain in full compliance.
+
+
+10. FUTURE REVISIONS OF THIS LICENSE
+
+The Free Software Foundation may publish new, revised versions
+of the GNU Free Documentation License from time to time. Such new
+versions will be similar in spirit to the present version, but may
+differ in detail to address new problems or concerns. See
+https://www.gnu.org/copyleft/.
+
+Each version of the License is given a distinguishing version number.
+If the Document specifies that a particular numbered version of this
+License "or any later version" applies to it, you have the option of
+following the terms and conditions either of that specified version or
+of any later version that has been published (not as a draft) by the
+Free Software Foundation. If the Document does not specify a version
+number of this License, you may choose any version ever published (not
+as a draft) by the Free Software Foundation.
+
+
+ADDENDUM: How to use this License for your documents
+
+To use this License in a document you have written, include a copy of
+the License in the document and put the following copyright and
+license notices just after the title page:
+
+ Copyright (c) YEAR YOUR NAME.
+ Permission is granted to copy, distribute and/or modify this document
+ under the terms of the GNU Free Documentation License, Version 1.2
+ 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 in the section entitled "GNU
+ Free Documentation License".
+
+If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts,
+replace the "with...Texts." line with this:
+
+ with the Invariant Sections being LIST THEIR TITLES, with the
+ Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST.
+
+If you have Invariant Sections without Cover Texts, or some other
+combination of the three, merge those two alternatives to suit the
+situation.
+
+If your document contains nontrivial examples of program code, we
+recommend releasing these examples in parallel under your choice of
+free software license, such as the GNU General Public License,
+to permit their use in free software.
+
+The End.
diff --git a/Documentation/admin-guide/sysctl/fs.rst b/Documentation/admin-guide/sysctl/fs.rst
index 2a45119..f48277a 100644
--- a/Documentation/admin-guide/sysctl/fs.rst
+++ b/Documentation/admin-guide/sysctl/fs.rst
@@ -261,7 +261,7 @@
is to cross privilege boundaries when following a given symlink (i.e. a
root process follows a symlink belonging to another user). For a likely
incomplete list of hundreds of examples across the years, please see:
-http://cve.mitre.org/cgi-bin/cvekey.cgi?keyword=/tmp
+https://cve.mitre.org/cgi-bin/cvekey.cgi?keyword=/tmp
When set to "0", symlink following behavior is unrestricted.
diff --git a/Documentation/admin-guide/sysctl/kernel.rst b/Documentation/admin-guide/sysctl/kernel.rst
index 83acf50..d4b32cc 100644
--- a/Documentation/admin-guide/sysctl/kernel.rst
+++ b/Documentation/admin-guide/sysctl/kernel.rst
@@ -164,7 +164,8 @@
%s signal number
%t UNIX time of dump
%h hostname
- %e executable filename (may be shortened)
+ %e executable filename (may be shortened, could be changed by prctl etc)
+ %f executable filename
%E executable path
%c maximum size of core file by resource limit RLIMIT_CORE
%<OTHER> both are dropped
@@ -235,7 +236,7 @@
from using ``dmesg(8)`` to view messages from the kernel's log
buffer.
When ``dmesg_restrict`` is set to 0 there are no restrictions.
-When ``dmesg_restrict`` is set set to 1, users must have
+When ``dmesg_restrict`` is set to 1, users must have
``CAP_SYSLOG`` to use ``dmesg(8)``.
The kernel config option ``CONFIG_SECURITY_DMESG_RESTRICT`` sets the
@@ -335,8 +336,8 @@
Default value is "``/sbin/hotplug``".
-hung_task_all_cpu_backtrace:
-================
+hung_task_all_cpu_backtrace
+===========================
If this option is set, the kernel will send an NMI to all CPUs to dump
their backtraces when a hung task is detected. This file shows up if
@@ -646,8 +647,8 @@
scanned for a given scan.
-oops_all_cpu_backtrace:
-================
+oops_all_cpu_backtrace
+======================
If this option is set, the kernel will send an NMI to all CPUs to dump
their backtraces when an oops event occurs. It should be used as a last
@@ -996,6 +997,38 @@
See Documentation/filesystems/devpts.rst.
+random
+======
+
+This is a directory, with the following entries:
+
+* ``boot_id``: a UUID generated the first time this is retrieved, and
+ unvarying after that;
+
+* ``entropy_avail``: the pool's entropy count, in bits;
+
+* ``poolsize``: the entropy pool size, in bits;
+
+* ``urandom_min_reseed_secs``: obsolete (used to determine the minimum
+ number of seconds between urandom pool reseeding).
+
+* ``uuid``: a UUID generated every time this is retrieved (this can
+ thus be used to generate UUIDs at will);
+
+* ``write_wakeup_threshold``: when the entropy count drops below this
+ (as a number of bits), processes waiting to write to ``/dev/random``
+ are woken up.
+
+If ``drivers/char/random.c`` is built with ``ADD_INTERRUPT_BENCH``
+defined, these additional entries are present:
+
+* ``add_interrupt_avg_cycles``: the average number of cycles between
+ interrupts used to feed the pool;
+
+* ``add_interrupt_avg_deviation``: the standard deviation seen on the
+ number of cycles between interrupts used to feed the pool.
+
+
randomize_va_space
==================
@@ -1062,6 +1095,60 @@
incurs a small amount of overhead in the scheduler but is
useful for debugging and performance tuning.
+sched_util_clamp_min:
+=====================
+
+Max allowed *minimum* utilization.
+
+Default value is 1024, which is the maximum possible value.
+
+It means that any requested uclamp.min value cannot be greater than
+sched_util_clamp_min, i.e., it is restricted to the range
+[0:sched_util_clamp_min].
+
+sched_util_clamp_max:
+=====================
+
+Max allowed *maximum* utilization.
+
+Default value is 1024, which is the maximum possible value.
+
+It means that any requested uclamp.max value cannot be greater than
+sched_util_clamp_max, i.e., it is restricted to the range
+[0:sched_util_clamp_max].
+
+sched_util_clamp_min_rt_default:
+================================
+
+By default Linux is tuned for performance. Which means that RT tasks always run
+at the highest frequency and most capable (highest capacity) CPU (in
+heterogeneous systems).
+
+Uclamp achieves this by setting the requested uclamp.min of all RT tasks to
+1024 by default, which effectively boosts the tasks to run at the highest
+frequency and biases them to run on the biggest CPU.
+
+This knob allows admins to change the default behavior when uclamp is being
+used. In battery powered devices particularly, running at the maximum
+capacity and frequency will increase energy consumption and shorten the battery
+life.
+
+This knob is only effective for RT tasks which the user hasn't modified their
+requested uclamp.min value via sched_setattr() syscall.
+
+This knob will not escape the range constraint imposed by sched_util_clamp_min
+defined above.
+
+For example if
+
+ sched_util_clamp_min_rt_default = 800
+ sched_util_clamp_min = 600
+
+Then the boost will be clamped to 600 because 800 is outside of the permissible
+range of [0:600]. This could happen for instance if a powersave mode will
+restrict all boosts temporarily by modifying sched_util_clamp_min. As soon as
+this restriction is lifted, the requested sched_util_clamp_min_rt_default
+will take effect.
seccomp
=======
diff --git a/Documentation/admin-guide/sysctl/vm.rst b/Documentation/admin-guide/sysctl/vm.rst
index d46d5b7..4b9d2e8 100644
--- a/Documentation/admin-guide/sysctl/vm.rst
+++ b/Documentation/admin-guide/sysctl/vm.rst
@@ -119,6 +119,21 @@
blocks where possible. This can be important for example in the allocation of
huge pages although processes will also directly compact memory as required.
+compaction_proactiveness
+========================
+
+This tunable takes a value in the range [0, 100] with a default value of
+20. This tunable determines how aggressively compaction is done in the
+background. Setting it to 0 disables proactive compaction.
+
+Note that compaction has a non-trivial system-wide impact as pages
+belonging to different processes are moved around, which could also lead
+to latency spikes in unsuspecting applications. The kernel employs
+various heuristics to avoid wasting CPU cycles if it detects that
+proactive compaction is not being effective.
+
+Be careful when setting it to extreme values like 100, as that may
+cause excessive background compaction activity.
compact_unevictable_allowed
===========================
@@ -583,7 +598,7 @@
The default value is 1.
-See Documentation/nommu-mmap.txt for more information.
+See Documentation/admin-guide/mm/nommu-mmap.rst for more information.
numa_zonelist_order
diff --git a/Documentation/admin-guide/tainted-kernels.rst b/Documentation/admin-guide/tainted-kernels.rst
index 71e9184..abf8047 100644
--- a/Documentation/admin-guide/tainted-kernels.rst
+++ b/Documentation/admin-guide/tainted-kernels.rst
@@ -38,7 +38,7 @@
Tainted: P W O
-The meaning of those characters is explained in the table below. In tis case
+The meaning of those characters is explained in the table below. In this case
the kernel got tainted earlier because a proprietary Module (``P``) was loaded,
a warning occurred (``W``), and an externally-built module was loaded (``O``).
To decode other letters use the table below.
@@ -61,7 +61,7 @@
* Proprietary module was loaded (#0)
* Kernel issued warning (#9)
* Externally-built ('out-of-tree') module was loaded (#12)
- See Documentation/admin-guide/tainted-kernels.rst in the the Linux kernel or
+ See Documentation/admin-guide/tainted-kernels.rst in the Linux kernel or
https://www.kernel.org/doc/html/latest/admin-guide/tainted-kernels.html for
a more details explanation of the various taint flags.
Raw taint value as int/string: 4609/'P W O '
diff --git a/Documentation/admin-guide/thunderbolt.rst b/Documentation/admin-guide/thunderbolt.rst
index 10c4f0c..613cb24 100644
--- a/Documentation/admin-guide/thunderbolt.rst
+++ b/Documentation/admin-guide/thunderbolt.rst
@@ -173,8 +173,8 @@
ACTION=="add", SUBSYSTEM=="thunderbolt", ATTRS{iommu_dma_protection}=="1", ATTR{authorized}=="0", ATTR{authorized}="1"
-Upgrading NVM on Thunderbolt device or host
--------------------------------------------
+Upgrading NVM on Thunderbolt device, host or retimer
+----------------------------------------------------
Since most of the functionality is handled in firmware running on a
host controller or a device, it is important that the firmware can be
upgraded to the latest where possible bugs in it have been fixed.
@@ -185,9 +185,10 @@
`Thunderbolt Updates <https://thunderbolttechnology.net/updates>`_
-Before you upgrade firmware on a device or host, please make sure it is a
-suitable upgrade. Failing to do that may render the device (or host) in a
-state where it cannot be used properly anymore without special tools!
+Before you upgrade firmware on a device, host or retimer, please make
+sure it is a suitable upgrade. Failing to do that may render the device
+in a state where it cannot be used properly anymore without special
+tools!
Host NVM upgrade on Apple Macs is not supported.
diff --git a/Documentation/admin-guide/xfs.rst b/Documentation/admin-guide/xfs.rst
index ad911be..f461d6c 100644
--- a/Documentation/admin-guide/xfs.rst
+++ b/Documentation/admin-guide/xfs.rst
@@ -133,7 +133,7 @@
logbsize must be an integer multiple of the log
stripe unit configured at **mkfs(8)** time.
- The default value for for version 1 logs is 32768, while the
+ The default value for version 1 logs is 32768, while the
default value for version 2 logs is MAX(32768, log_sunit).
logdev=device and rtdev=device
diff --git a/Documentation/arm/arm.rst b/Documentation/arm/arm.rst
index 2edc509..99d660f 100644
--- a/Documentation/arm/arm.rst
+++ b/Documentation/arm/arm.rst
@@ -184,10 +184,8 @@
We group machine (or platform) support code into machine classes. A
class typically based around one or more system on a chip devices, and
acts as a natural container around the actual implementations. These
- classes are given directories - arch/arm/mach-<class> and
- arch/arm/mach-<class> - which contain the source files to/include/mach
- support the machine class. This directories also contain any machine
- specific supporting code.
+ classes are given directories - arch/arm/mach-<class> - which contain
+ the source files and include/mach/ to support the machine class.
For example, the SA1100 class is based upon the SA1100 and SA1110 SoC
devices, and contains the code to support the way the on-board and off-
diff --git a/Documentation/arm/booting.rst b/Documentation/arm/booting.rst
index 4babb6c..a226345 100644
--- a/Documentation/arm/booting.rst
+++ b/Documentation/arm/booting.rst
@@ -128,7 +128,7 @@
The boot loader must load a device tree image (dtb) into system ram
at a 64bit aligned address and initialize it with the boot data. The
-dtb format is documented in Documentation/devicetree/booting-without-of.txt.
+dtb format is documented in Documentation/devicetree/booting-without-of.rst.
The kernel will look for the dtb magic value of 0xd00dfeed at the dtb
physical address to determine if a dtb has been passed instead of a
tagged list.
diff --git a/Documentation/arm64/acpi_object_usage.rst b/Documentation/arm64/acpi_object_usage.rst
index d51b69d..377e9d2 100644
--- a/Documentation/arm64/acpi_object_usage.rst
+++ b/Documentation/arm64/acpi_object_usage.rst
@@ -220,7 +220,7 @@
x86 only table as of ACPI 5.1; starting with ACPI 6.0, processor
descriptions and power states on ARM platforms should use the DSDT
and define processor container devices (_HID ACPI0010, Section 8.4,
- and more specifically 8.4.3 and and 8.4.4).
+ and more specifically 8.4.3 and 8.4.4).
MADT Section 5.2.12 (signature == "APIC")
diff --git a/Documentation/arm64/arm-acpi.rst b/Documentation/arm64/arm-acpi.rst
index 872dbbc..47ecb99 100644
--- a/Documentation/arm64/arm-acpi.rst
+++ b/Documentation/arm64/arm-acpi.rst
@@ -273,7 +273,7 @@
- UUID: daffd814-6eba-4d8c-8a91-bc9bbf4aa301
- - http://www.uefi.org/sites/default/files/resources/_DSD-device-properties-UUID.pdf
+ - https://www.uefi.org/sites/default/files/resources/_DSD-device-properties-UUID.pdf
The UEFI Forum provides a mechanism for registering device properties [4]
so that they may be used across all operating systems supporting ACPI.
@@ -470,7 +470,7 @@
Linux Code
----------
-Individual items specific to Linux on ARM, contained in the the Linux
+Individual items specific to Linux on ARM, contained in the Linux
source code, are in the list that follows:
ACPI_OS_NAME
diff --git a/Documentation/arm64/cpu-feature-registers.rst b/Documentation/arm64/cpu-feature-registers.rst
index 314fa5b..f28853f 100644
--- a/Documentation/arm64/cpu-feature-registers.rst
+++ b/Documentation/arm64/cpu-feature-registers.rst
@@ -171,6 +171,7 @@
3) ID_AA64PFR1_EL1 - Processor Feature Register 1
+
+------------------------------+---------+---------+
| Name | bits | visible |
+------------------------------+---------+---------+
@@ -181,6 +182,7 @@
4) MIDR_EL1 - Main ID Register
+
+------------------------------+---------+---------+
| Name | bits | visible |
+------------------------------+---------+---------+
diff --git a/Documentation/arm64/index.rst b/Documentation/arm64/index.rst
index 09cbb4e..d9665d8 100644
--- a/Documentation/arm64/index.rst
+++ b/Documentation/arm64/index.rst
@@ -14,6 +14,7 @@
hugetlbpage
legacy_instructions
memory
+ perf
pointer-authentication
silicon-errata
sve
diff --git a/Documentation/arm64/perf.rst b/Documentation/arm64/perf.rst
new file mode 100644
index 0000000..9c76a97
--- /dev/null
+++ b/Documentation/arm64/perf.rst
@@ -0,0 +1,88 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+=====================
+Perf Event Attributes
+=====================
+
+:Author: Andrew Murray <andrew.murray@arm.com>
+:Date: 2019-03-06
+
+exclude_user
+------------
+
+This attribute excludes userspace.
+
+Userspace always runs at EL0 and thus this attribute will exclude EL0.
+
+
+exclude_kernel
+--------------
+
+This attribute excludes the kernel.
+
+The kernel runs at EL2 with VHE and EL1 without. Guest kernels always run
+at EL1.
+
+For the host this attribute will exclude EL1 and additionally EL2 on a VHE
+system.
+
+For the guest this attribute will exclude EL1. Please note that EL2 is
+never counted within a guest.
+
+
+exclude_hv
+----------
+
+This attribute excludes the hypervisor.
+
+For a VHE host this attribute is ignored as we consider the host kernel to
+be the hypervisor.
+
+For a non-VHE host this attribute will exclude EL2 as we consider the
+hypervisor to be any code that runs at EL2 which is predominantly used for
+guest/host transitions.
+
+For the guest this attribute has no effect. Please note that EL2 is
+never counted within a guest.
+
+
+exclude_host / exclude_guest
+----------------------------
+
+These attributes exclude the KVM host and guest, respectively.
+
+The KVM host may run at EL0 (userspace), EL1 (non-VHE kernel) and EL2 (VHE
+kernel or non-VHE hypervisor).
+
+The KVM guest may run at EL0 (userspace) and EL1 (kernel).
+
+Due to the overlapping exception levels between host and guests we cannot
+exclusively rely on the PMU's hardware exception filtering - therefore we
+must enable/disable counting on the entry and exit to the guest. This is
+performed differently on VHE and non-VHE systems.
+
+For non-VHE systems we exclude EL2 for exclude_host - upon entering and
+exiting the guest we disable/enable the event as appropriate based on the
+exclude_host and exclude_guest attributes.
+
+For VHE systems we exclude EL1 for exclude_guest and exclude both EL0,EL2
+for exclude_host. Upon entering and exiting the guest we modify the event
+to include/exclude EL0 as appropriate based on the exclude_host and
+exclude_guest attributes.
+
+The statements above also apply when these attributes are used within a
+non-VHE guest however please note that EL2 is never counted within a guest.
+
+
+Accuracy
+--------
+
+On non-VHE hosts we enable/disable counters on the entry/exit of host/guest
+transition at EL2 - however there is a period of time between
+enabling/disabling the counters and entering/exiting the guest. We are
+able to eliminate counters counting host events on the boundaries of guest
+entry/exit when counting guest events by filtering out EL2 for
+exclude_host. However when using !exclude_hv there is a small blackout
+window at the guest entry/exit where host events are not captured.
+
+On VHE systems there are no blackout windows.
diff --git a/Documentation/arm64/perf.txt b/Documentation/arm64/perf.txt
deleted file mode 100644
index 0d6a7d8..0000000
--- a/Documentation/arm64/perf.txt
+++ /dev/null
@@ -1,85 +0,0 @@
-Perf Event Attributes
-=====================
-
-Author: Andrew Murray <andrew.murray@arm.com>
-Date: 2019-03-06
-
-exclude_user
-------------
-
-This attribute excludes userspace.
-
-Userspace always runs at EL0 and thus this attribute will exclude EL0.
-
-
-exclude_kernel
---------------
-
-This attribute excludes the kernel.
-
-The kernel runs at EL2 with VHE and EL1 without. Guest kernels always run
-at EL1.
-
-For the host this attribute will exclude EL1 and additionally EL2 on a VHE
-system.
-
-For the guest this attribute will exclude EL1. Please note that EL2 is
-never counted within a guest.
-
-
-exclude_hv
-----------
-
-This attribute excludes the hypervisor.
-
-For a VHE host this attribute is ignored as we consider the host kernel to
-be the hypervisor.
-
-For a non-VHE host this attribute will exclude EL2 as we consider the
-hypervisor to be any code that runs at EL2 which is predominantly used for
-guest/host transitions.
-
-For the guest this attribute has no effect. Please note that EL2 is
-never counted within a guest.
-
-
-exclude_host / exclude_guest
-----------------------------
-
-These attributes exclude the KVM host and guest, respectively.
-
-The KVM host may run at EL0 (userspace), EL1 (non-VHE kernel) and EL2 (VHE
-kernel or non-VHE hypervisor).
-
-The KVM guest may run at EL0 (userspace) and EL1 (kernel).
-
-Due to the overlapping exception levels between host and guests we cannot
-exclusively rely on the PMU's hardware exception filtering - therefore we
-must enable/disable counting on the entry and exit to the guest. This is
-performed differently on VHE and non-VHE systems.
-
-For non-VHE systems we exclude EL2 for exclude_host - upon entering and
-exiting the guest we disable/enable the event as appropriate based on the
-exclude_host and exclude_guest attributes.
-
-For VHE systems we exclude EL1 for exclude_guest and exclude both EL0,EL2
-for exclude_host. Upon entering and exiting the guest we modify the event
-to include/exclude EL0 as appropriate based on the exclude_host and
-exclude_guest attributes.
-
-The statements above also apply when these attributes are used within a
-non-VHE guest however please note that EL2 is never counted within a guest.
-
-
-Accuracy
---------
-
-On non-VHE hosts we enable/disable counters on the entry/exit of host/guest
-transition at EL2 - however there is a period of time between
-enabling/disabling the counters and entering/exiting the guest. We are
-able to eliminate counters counting host events on the boundaries of guest
-entry/exit when counting guest events by filtering out EL2 for
-exclude_host. However when using !exclude_hv there is a small blackout
-window at the guest entry/exit where host events are not captured.
-
-On VHE systems there are no blackout windows.
diff --git a/Documentation/arm64/silicon-errata.rst b/Documentation/arm64/silicon-errata.rst
index 936cf2a..d358780 100644
--- a/Documentation/arm64/silicon-errata.rst
+++ b/Documentation/arm64/silicon-errata.rst
@@ -125,6 +125,9 @@
| Cavium | ThunderX2 Core | #219 | CAVIUM_TX2_ERRATUM_219 |
+----------------+-----------------+-----------------+-----------------------------+
+----------------+-----------------+-----------------+-----------------------------+
+| Marvell | ARM-MMU-500 | #582743 | N/A |
++----------------+-----------------+-----------------+-----------------------------+
++----------------+-----------------+-----------------+-----------------------------+
| Freescale/NXP | LS2080A/LS1043A | A-008585 | FSL_ERRATUM_A008585 |
+----------------+-----------------+-----------------+-----------------------------+
+----------------+-----------------+-----------------+-----------------------------+
@@ -147,6 +150,14 @@
+----------------+-----------------+-----------------+-----------------------------+
| Qualcomm Tech. | Falkor v{1,2} | E1041 | QCOM_FALKOR_ERRATUM_1041 |
+----------------+-----------------+-----------------+-----------------------------+
+| Qualcomm Tech. | Kryo4xx Gold | N/A | ARM64_ERRATUM_1463225 |
++----------------+-----------------+-----------------+-----------------------------+
+| Qualcomm Tech. | Kryo4xx Gold | N/A | ARM64_ERRATUM_1418040 |
++----------------+-----------------+-----------------+-----------------------------+
+| Qualcomm Tech. | Kryo4xx Silver | N/A | ARM64_ERRATUM_1530923 |
++----------------+-----------------+-----------------+-----------------------------+
+| Qualcomm Tech. | Kryo4xx Silver | N/A | ARM64_ERRATUM_1024718 |
++----------------+-----------------+-----------------+-----------------------------+
+----------------+-----------------+-----------------+-----------------------------+
| Fujitsu | A64FX | E#010001 | FUJITSU_ERRATUM_010001 |
+----------------+-----------------+-----------------+-----------------------------+
diff --git a/Documentation/arm64/sve.rst b/Documentation/arm64/sve.rst
index 5689c74..0313715 100644
--- a/Documentation/arm64/sve.rst
+++ b/Documentation/arm64/sve.rst
@@ -186,7 +186,7 @@
flags:
- PR_SVE_SET_VL_INHERIT
+ PR_SVE_VL_INHERIT
Inherit the current vector length across execve(). Otherwise, the
vector length is reset to the system default at execve(). (See
@@ -247,7 +247,7 @@
The following flag may be OR-ed into the result:
- PR_SVE_SET_VL_INHERIT
+ PR_SVE_VL_INHERIT
Vector length will be inherited across execve().
@@ -393,7 +393,7 @@
* At every execve() call, the new vector length of the new process is set to
the system default vector length, unless
- * PR_SVE_SET_VL_INHERIT (or equivalently SVE_PT_VL_INHERIT) is set for the
+ * PR_SVE_VL_INHERIT (or equivalently SVE_PT_VL_INHERIT) is set for the
calling thread, or
* a deferred vector length change is pending, established via the
@@ -494,7 +494,7 @@
Note: This section is for information only and not intended to be complete or
to replace any architectural specification.
-Refer to [4] for for more information.
+Refer to [4] for more information.
ARMv8-A defines the following floating-point / SIMD register state:
diff --git a/Documentation/atomic_t.txt b/Documentation/atomic_t.txt
index 0ab747e..0f1fded 100644
--- a/Documentation/atomic_t.txt
+++ b/Documentation/atomic_t.txt
@@ -85,22 +85,22 @@
the Non-RMW operations of atomic_t, you do not in fact need atomic_t at all
and are doing it wrong.
-A subtle detail of atomic_set{}() is that it should be observable to the RMW
-ops. That is:
+A note for the implementation of atomic_set{}() is that it must not break the
+atomicity of the RMW ops. That is:
- C atomic-set
+ C Atomic-RMW-ops-are-atomic-WRT-atomic_set
{
- atomic_set(v, 1);
+ atomic_t v = ATOMIC_INIT(1);
+ }
+
+ P0(atomic_t *v)
+ {
+ (void)atomic_add_unless(v, 1, 0);
}
P1(atomic_t *v)
{
- atomic_add_unless(v, 1, 0);
- }
-
- P2(atomic_t *v)
- {
atomic_set(v, 0);
}
@@ -233,19 +233,19 @@
is an ACQUIRE pattern (though very much not typical), but again the barrier is
strictly stronger than ACQUIRE. As illustrated:
- C strong-acquire
+ C Atomic-RMW+mb__after_atomic-is-stronger-than-acquire
{
}
- P1(int *x, atomic_t *y)
+ P0(int *x, atomic_t *y)
{
r0 = READ_ONCE(*x);
smp_rmb();
r1 = atomic_read(y);
}
- P2(int *x, atomic_t *y)
+ P1(int *x, atomic_t *y)
{
atomic_inc(y);
smp_mb__after_atomic();
@@ -253,14 +253,14 @@
}
exists
- (r0=1 /\ r1=0)
+ (0:r0=1 /\ 0:r1=0)
This should not happen; but a hypothetical atomic_inc_acquire() --
(void)atomic_fetch_inc_acquire() for instance -- would allow the outcome,
because it would not order the W part of the RMW against the following
WRITE_ONCE. Thus:
- P1 P2
+ P0 P1
t = LL.acq *y (0)
t++;
diff --git a/Documentation/block/bfq-iosched.rst b/Documentation/block/bfq-iosched.rst
index 0d237d4..19d4d15 100644
--- a/Documentation/block/bfq-iosched.rst
+++ b/Documentation/block/bfq-iosched.rst
@@ -492,13 +492,6 @@
it with auto-tuning. An alternative way to achieve this goal is to
just increase the value of timeout_sync, leaving max_budget equal to 0.
-weights
--------
-
-Read-only parameter, used to show the weights of the currently active
-BFQ queues.
-
-
4. Group scheduling with BFQ
============================
@@ -566,7 +559,7 @@
For each group, there is only the following parameter to set.
weight (namely blkio.bfq.weight or io.bfq-weight): the weight of the
-group inside its parent. Available values: 1..10000 (default 100). The
+group inside its parent. Available values: 1..1000 (default 100). The
linear mapping between ioprio and weights, described at the beginning
of the tunable section, is still valid, but all weights higher than
IOPRIO_BE_NR*10 are mapped to ioprio 0.
diff --git a/Documentation/block/biodoc.rst b/Documentation/block/biodoc.rst
index b964796..1d4d71e 100644
--- a/Documentation/block/biodoc.rst
+++ b/Documentation/block/biodoc.rst
@@ -196,7 +196,7 @@
do not have a corresponding kernel virtual address space mapping) and
low-memory pages.
-Note: Please refer to Documentation/DMA-API-HOWTO.txt for a discussion
+Note: Please refer to :doc:`/core-api/dma-api-howto` for a discussion
on PCI high mem DMA aspects and mapping of scatter gather lists, and support
for 64 bit PCI.
@@ -1036,7 +1036,7 @@
provides drivers with a sector number relative to whole device, rather than
having to take partition number into account in order to arrive at the true
sector number. The routine blk_partition_remap() is invoked by
-generic_make_request even before invoking the queue specific make_request_fn,
+submit_bio_noacct even before invoking the queue specific ->submit_bio,
so the i/o scheduler also gets to operate on whole disk sector numbers. This
should typically not require changes to block drivers, it just never gets
to invoke its own partition sector offset calculations since all bios
diff --git a/Documentation/block/blk-mq.rst b/Documentation/block/blk-mq.rst
new file mode 100644
index 0000000..88c56af
--- /dev/null
+++ b/Documentation/block/blk-mq.rst
@@ -0,0 +1,153 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+================================================
+Multi-Queue Block IO Queueing Mechanism (blk-mq)
+================================================
+
+The Multi-Queue Block IO Queueing Mechanism is an API to enable fast storage
+devices to achieve a huge number of input/output operations per second (IOPS)
+through queueing and submitting IO requests to block devices simultaneously,
+benefiting from the parallelism offered by modern storage devices.
+
+Introduction
+============
+
+Background
+----------
+
+Magnetic hard disks have been the de facto standard from the beginning of the
+development of the kernel. The Block IO subsystem aimed to achieve the best
+performance possible for those devices with a high penalty when doing random
+access, and the bottleneck was the mechanical moving parts, a lot slower than
+any layer on the storage stack. One example of such optimization technique
+involves ordering read/write requests according to the current position of the
+hard disk head.
+
+However, with the development of Solid State Drives and Non-Volatile Memories
+without mechanical parts nor random access penalty and capable of performing
+high parallel access, the bottleneck of the stack had moved from the storage
+device to the operating system. In order to take advantage of the parallelism
+in those devices' design, the multi-queue mechanism was introduced.
+
+The former design had a single queue to store block IO requests with a single
+lock. That did not scale well in SMP systems due to dirty data in cache and the
+bottleneck of having a single lock for multiple processors. This setup also
+suffered with congestion when different processes (or the same process, moving
+to different CPUs) wanted to perform block IO. Instead of this, the blk-mq API
+spawns multiple queues with individual entry points local to the CPU, removing
+the need for a lock. A deeper explanation on how this works is covered in the
+following section (`Operation`_).
+
+Operation
+---------
+
+When the userspace performs IO to a block device (reading or writing a file,
+for instance), blk-mq takes action: it will store and manage IO requests to
+the block device, acting as middleware between the userspace (and a file
+system, if present) and the block device driver.
+
+blk-mq has two group of queues: software staging queues and hardware dispatch
+queues. When the request arrives at the block layer, it will try the shortest
+path possible: send it directly to the hardware queue. However, there are two
+cases that it might not do that: if there's an IO scheduler attached at the
+layer or if we want to try to merge requests. In both cases, requests will be
+sent to the software queue.
+
+Then, after the requests are processed by software queues, they will be placed
+at the hardware queue, a second stage queue were the hardware has direct access
+to process those requests. However, if the hardware does not have enough
+resources to accept more requests, blk-mq will places requests on a temporary
+queue, to be sent in the future, when the hardware is able.
+
+Software staging queues
+~~~~~~~~~~~~~~~~~~~~~~~
+
+The block IO subsystem adds requests in the software staging queues
+(represented by struct :c:type:`blk_mq_ctx`) in case that they weren't sent
+directly to the driver. A request is one or more BIOs. They arrived at the
+block layer through the data structure struct :c:type:`bio`. The block layer
+will then build a new structure from it, the struct :c:type:`request` that will
+be used to communicate with the device driver. Each queue has its own lock and
+the number of queues is defined by a per-CPU or per-node basis.
+
+The staging queue can be used to merge requests for adjacent sectors. For
+instance, requests for sector 3-6, 6-7, 7-9 can become one request for 3-9.
+Even if random access to SSDs and NVMs have the same time of response compared
+to sequential access, grouped requests for sequential access decreases the
+number of individual requests. This technique of merging requests is called
+plugging.
+
+Along with that, the requests can be reordered to ensure fairness of system
+resources (e.g. to ensure that no application suffers from starvation) and/or to
+improve IO performance, by an IO scheduler.
+
+IO Schedulers
+^^^^^^^^^^^^^
+
+There are several schedulers implemented by the block layer, each one following
+a heuristic to improve the IO performance. They are "pluggable" (as in plug
+and play), in the sense of they can be selected at run time using sysfs. You
+can read more about Linux's IO schedulers `here
+<https://www.kernel.org/doc/html/latest/block/index.html>`_. The scheduling
+happens only between requests in the same queue, so it is not possible to merge
+requests from different queues, otherwise there would be cache trashing and a
+need to have a lock for each queue. After the scheduling, the requests are
+eligible to be sent to the hardware. One of the possible schedulers to be
+selected is the NONE scheduler, the most straightforward one. It will just
+place requests on whatever software queue the process is running on, without
+any reordering. When the device starts processing requests in the hardware
+queue (a.k.a. run the hardware queue), the software queues mapped to that
+hardware queue will be drained in sequence according to their mapping.
+
+Hardware dispatch queues
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+The hardware queue (represented by struct :c:type:`blk_mq_hw_ctx`) is a struct
+used by device drivers to map the device submission queues (or device DMA ring
+buffer), and are the last step of the block layer submission code before the
+low level device driver taking ownership of the request. To run this queue, the
+block layer removes requests from the associated software queues and tries to
+dispatch to the hardware.
+
+If it's not possible to send the requests directly to hardware, they will be
+added to a linked list (:c:type:`hctx->dispatch`) of requests. Then,
+next time the block layer runs a queue, it will send the requests laying at the
+:c:type:`dispatch` list first, to ensure a fairness dispatch with those
+requests that were ready to be sent first. The number of hardware queues
+depends on the number of hardware contexts supported by the hardware and its
+device driver, but it will not be more than the number of cores of the system.
+There is no reordering at this stage, and each software queue has a set of
+hardware queues to send requests for.
+
+.. note::
+
+ Neither the block layer nor the device protocols guarantee
+ the order of completion of requests. This must be handled by
+ higher layers, like the filesystem.
+
+Tag-based completion
+~~~~~~~~~~~~~~~~~~~~
+
+In order to indicate which request has been completed, every request is
+identified by an integer, ranging from 0 to the dispatch queue size. This tag
+is generated by the block layer and later reused by the device driver, removing
+the need to create a redundant identifier. When a request is completed in the
+drive, the tag is sent back to the block layer to notify it of the finalization.
+This removes the need to do a linear search to find out which IO has been
+completed.
+
+Further reading
+---------------
+
+- `Linux Block IO: Introducing Multi-queue SSD Access on Multi-core Systems <http://kernel.dk/blk-mq.pdf>`_
+
+- `NOOP scheduler <https://en.wikipedia.org/wiki/Noop_scheduler>`_
+
+- `Null block device driver <https://www.kernel.org/doc/html/latest/block/null_blk.html>`_
+
+Source code documentation
+=========================
+
+.. kernel-doc:: include/linux/blk-mq.h
+
+.. kernel-doc:: block/blk-mq.c
diff --git a/Documentation/block/index.rst b/Documentation/block/index.rst
index 026addf..86dcf71 100644
--- a/Documentation/block/index.rst
+++ b/Documentation/block/index.rst
@@ -10,6 +10,7 @@
bfq-iosched
biodoc
biovecs
+ blk-mq
capability
cmdline-partition
data-integrity
diff --git a/Documentation/block/pr.rst b/Documentation/block/pr.rst
index 30ea1c2..c893d6d 100644
--- a/Documentation/block/pr.rst
+++ b/Documentation/block/pr.rst
@@ -9,7 +9,7 @@
setup.
This document gives a general overview of the support ioctl commands.
-For a more detailed reference please refer the the SCSI Primary
+For a more detailed reference please refer to the SCSI Primary
Commands standard, specifically the section on Reservations and the
"PERSISTENT RESERVE IN" and "PERSISTENT RESERVE OUT" commands.
diff --git a/Documentation/block/queue-sysfs.rst b/Documentation/block/queue-sysfs.rst
index 6a8513a..f261a5c 100644
--- a/Documentation/block/queue-sysfs.rst
+++ b/Documentation/block/queue-sysfs.rst
@@ -117,6 +117,20 @@
data that will be submitted by the block layer core to the associated
block driver.
+max_active_zones (RO)
+---------------------
+For zoned block devices (zoned attribute indicating "host-managed" or
+"host-aware"), the sum of zones belonging to any of the zone states:
+EXPLICIT OPEN, IMPLICIT OPEN or CLOSED, is limited by this value.
+If this value is 0, there is no limit.
+
+max_open_zones (RO)
+-------------------
+For zoned block devices (zoned attribute indicating "host-managed" or
+"host-aware"), the sum of zones belonging to any of the zone states:
+EXPLICIT OPEN or IMPLICIT OPEN, is limited by this value.
+If this value is 0, there is no limit.
+
max_sectors_kb (RW)
-------------------
This is the maximum number of kilobytes that the block layer will allow
diff --git a/Documentation/block/writeback_cache_control.rst b/Documentation/block/writeback_cache_control.rst
index 2c752c5..b208488 100644
--- a/Documentation/block/writeback_cache_control.rst
+++ b/Documentation/block/writeback_cache_control.rst
@@ -47,7 +47,7 @@
may both be set on a single bio.
-Implementation details for make_request_fn based block drivers
+Implementation details for bio based block drivers
--------------------------------------------------------------
These drivers will always see the REQ_PREFLUSH and REQ_FUA bits as they sit
diff --git a/Documentation/bpf/bpf_design_QA.rst b/Documentation/bpf/bpf_design_QA.rst
index 12a246f..2df7b06 100644
--- a/Documentation/bpf/bpf_design_QA.rst
+++ b/Documentation/bpf/bpf_design_QA.rst
@@ -246,17 +246,6 @@
this helper is only useful for experiments and prototypes.
Tracing BPF programs are root only.
-Q: bpf_trace_printk() helper warning
-------------------------------------
-Q: When bpf_trace_printk() helper is used the kernel prints nasty
-warning message. Why is that?
-
-A: This is done to nudge program authors into better interfaces when
-programs need to pass data to user space. Like bpf_perf_event_output()
-can be used to efficiently stream data via perf ring buffer.
-BPF maps can be used for asynchronous data sharing between kernel
-and user space. bpf_trace_printk() should only be used for debugging.
-
Q: New functionality via kernel modules?
----------------------------------------
Q: Can BPF functionality such as new program or map types, new
diff --git a/Documentation/bpf/bpf_devel_QA.rst b/Documentation/bpf/bpf_devel_QA.rst
index 0b3db91..a26aa1b 100644
--- a/Documentation/bpf/bpf_devel_QA.rst
+++ b/Documentation/bpf/bpf_devel_QA.rst
@@ -643,5 +643,6 @@
.. _selftests: ../../tools/testing/selftests/bpf/
.. _Documentation/dev-tools/kselftest.rst:
https://www.kernel.org/doc/html/latest/dev-tools/kselftest.html
+.. _Documentation/bpf/btf.rst: btf.rst
Happy BPF hacking!
diff --git a/Documentation/bpf/btf.rst b/Documentation/bpf/btf.rst
index 4d565d2..b5361b8 100644
--- a/Documentation/bpf/btf.rst
+++ b/Documentation/bpf/btf.rst
@@ -691,6 +691,42 @@
bpf_insn``. For ELF API, the ``insn_off`` is the byte offset from the
beginning of section (``btf_ext_info_sec->sec_name_off``).
+4.2 .BTF_ids section
+====================
+
+The .BTF_ids section encodes BTF ID values that are used within the kernel.
+
+This section is created during the kernel compilation with the help of
+macros defined in ``include/linux/btf_ids.h`` header file. Kernel code can
+use them to create lists and sets (sorted lists) of BTF ID values.
+
+The ``BTF_ID_LIST`` and ``BTF_ID`` macros define unsorted list of BTF ID values,
+with following syntax::
+
+ BTF_ID_LIST(list)
+ BTF_ID(type1, name1)
+ BTF_ID(type2, name2)
+
+resulting in following layout in .BTF_ids section::
+
+ __BTF_ID__type1__name1__1:
+ .zero 4
+ __BTF_ID__type2__name2__2:
+ .zero 4
+
+The ``u32 list[];`` variable is defined to access the list.
+
+The ``BTF_ID_UNUSED`` macro defines 4 zero bytes. It's used when we
+want to define unused entry in BTF_ID_LIST, like::
+
+ BTF_ID_LIST(bpf_skb_output_btf_ids)
+ BTF_ID(struct, sk_buff)
+ BTF_ID_UNUSED
+ BTF_ID(struct, task_struct)
+
+All the BTF ID lists and sets are compiled in the .BTF_ids section and
+resolved during the linking phase of kernel build by ``resolve_btfids`` tool.
+
5. Using BTF
************
diff --git a/Documentation/bpf/index.rst b/Documentation/bpf/index.rst
index 38b4db8..d46429b 100644
--- a/Documentation/bpf/index.rst
+++ b/Documentation/bpf/index.rst
@@ -5,10 +5,10 @@
This directory contains documentation for the BPF (Berkeley Packet
Filter) facility, with a focus on the extended BPF version (eBPF).
-This kernel side documentation is still work in progress. The main
+This kernel side documentation is still work in progress. The main
textual documentation is (for historical reasons) described in
-`Documentation/networking/filter.rst`_, which describe both classical
-and extended BPF instruction-set.
+:ref:`networking-filter`, which describe both classical and extended
+BPF instruction-set.
The Cilium project also maintains a `BPF and XDP Reference Guide`_
that goes into great technical depth about the BPF Architecture.
@@ -48,6 +48,15 @@
bpf_lsm
+Map types
+=========
+
+.. toctree::
+ :maxdepth: 1
+
+ map_cgroup_storage
+
+
Testing and debugging BPF
=========================
@@ -58,8 +67,16 @@
s390
+Other
+=====
+
+.. toctree::
+ :maxdepth: 1
+
+ ringbuf
+
.. Links:
-.. _Documentation/networking/filter.rst: ../networking/filter.txt
+.. _networking-filter: ../networking/filter.rst
.. _man-pages: https://www.kernel.org/doc/man-pages/
-.. _bpf(2): http://man7.org/linux/man-pages/man2/bpf.2.html
-.. _BPF and XDP Reference Guide: http://cilium.readthedocs.io/en/latest/bpf/
+.. _bpf(2): https://man7.org/linux/man-pages/man2/bpf.2.html
+.. _BPF and XDP Reference Guide: https://docs.cilium.io/en/latest/bpf/
diff --git a/Documentation/bpf/map_cgroup_storage.rst b/Documentation/bpf/map_cgroup_storage.rst
new file mode 100644
index 0000000..cab9543
--- /dev/null
+++ b/Documentation/bpf/map_cgroup_storage.rst
@@ -0,0 +1,169 @@
+.. SPDX-License-Identifier: GPL-2.0-only
+.. Copyright (C) 2020 Google LLC.
+
+===========================
+BPF_MAP_TYPE_CGROUP_STORAGE
+===========================
+
+The ``BPF_MAP_TYPE_CGROUP_STORAGE`` map type represents a local fix-sized
+storage. It is only available with ``CONFIG_CGROUP_BPF``, and to programs that
+attach to cgroups; the programs are made available by the same Kconfig. The
+storage is identified by the cgroup the program is attached to.
+
+The map provide a local storage at the cgroup that the BPF program is attached
+to. It provides a faster and simpler access than the general purpose hash
+table, which performs a hash table lookups, and requires user to track live
+cgroups on their own.
+
+This document describes the usage and semantics of the
+``BPF_MAP_TYPE_CGROUP_STORAGE`` map type. Some of its behaviors was changed in
+Linux 5.9 and this document will describe the differences.
+
+Usage
+=====
+
+The map uses key of type of either ``__u64 cgroup_inode_id`` or
+``struct bpf_cgroup_storage_key``, declared in ``linux/bpf.h``::
+
+ struct bpf_cgroup_storage_key {
+ __u64 cgroup_inode_id;
+ __u32 attach_type;
+ };
+
+``cgroup_inode_id`` is the inode id of the cgroup directory.
+``attach_type`` is the the program's attach type.
+
+Linux 5.9 added support for type ``__u64 cgroup_inode_id`` as the key type.
+When this key type is used, then all attach types of the particular cgroup and
+map will share the same storage. Otherwise, if the type is
+``struct bpf_cgroup_storage_key``, then programs of different attach types
+be isolated and see different storages.
+
+To access the storage in a program, use ``bpf_get_local_storage``::
+
+ void *bpf_get_local_storage(void *map, u64 flags)
+
+``flags`` is reserved for future use and must be 0.
+
+There is no implicit synchronization. Storages of ``BPF_MAP_TYPE_CGROUP_STORAGE``
+can be accessed by multiple programs across different CPUs, and user should
+take care of synchronization by themselves. The bpf infrastructure provides
+``struct bpf_spin_lock`` to synchronize the storage. See
+``tools/testing/selftests/bpf/progs/test_spin_lock.c``.
+
+Examples
+========
+
+Usage with key type as ``struct bpf_cgroup_storage_key``::
+
+ #include <bpf/bpf.h>
+
+ struct {
+ __uint(type, BPF_MAP_TYPE_CGROUP_STORAGE);
+ __type(key, struct bpf_cgroup_storage_key);
+ __type(value, __u32);
+ } cgroup_storage SEC(".maps");
+
+ int program(struct __sk_buff *skb)
+ {
+ __u32 *ptr = bpf_get_local_storage(&cgroup_storage, 0);
+ __sync_fetch_and_add(ptr, 1);
+
+ return 0;
+ }
+
+Userspace accessing map declared above::
+
+ #include <linux/bpf.h>
+ #include <linux/libbpf.h>
+
+ __u32 map_lookup(struct bpf_map *map, __u64 cgrp, enum bpf_attach_type type)
+ {
+ struct bpf_cgroup_storage_key = {
+ .cgroup_inode_id = cgrp,
+ .attach_type = type,
+ };
+ __u32 value;
+ bpf_map_lookup_elem(bpf_map__fd(map), &key, &value);
+ // error checking omitted
+ return value;
+ }
+
+Alternatively, using just ``__u64 cgroup_inode_id`` as key type::
+
+ #include <bpf/bpf.h>
+
+ struct {
+ __uint(type, BPF_MAP_TYPE_CGROUP_STORAGE);
+ __type(key, __u64);
+ __type(value, __u32);
+ } cgroup_storage SEC(".maps");
+
+ int program(struct __sk_buff *skb)
+ {
+ __u32 *ptr = bpf_get_local_storage(&cgroup_storage, 0);
+ __sync_fetch_and_add(ptr, 1);
+
+ return 0;
+ }
+
+And userspace::
+
+ #include <linux/bpf.h>
+ #include <linux/libbpf.h>
+
+ __u32 map_lookup(struct bpf_map *map, __u64 cgrp, enum bpf_attach_type type)
+ {
+ __u32 value;
+ bpf_map_lookup_elem(bpf_map__fd(map), &cgrp, &value);
+ // error checking omitted
+ return value;
+ }
+
+Semantics
+=========
+
+``BPF_MAP_TYPE_PERCPU_CGROUP_STORAGE`` is a variant of this map type. This
+per-CPU variant will have different memory regions for each CPU for each
+storage. The non-per-CPU will have the same memory region for each storage.
+
+Prior to Linux 5.9, the lifetime of a storage is precisely per-attachment, and
+for a single ``CGROUP_STORAGE`` map, there can be at most one program loaded
+that uses the map. A program may be attached to multiple cgroups or have
+multiple attach types, and each attach creates a fresh zeroed storage. The
+storage is freed upon detach.
+
+There is a one-to-one association between the map of each type (per-CPU and
+non-per-CPU) and the BPF program during load verification time. As a result,
+each map can only be used by one BPF program and each BPF program can only use
+one storage map of each type. Because of map can only be used by one BPF
+program, sharing of this cgroup's storage with other BPF programs were
+impossible.
+
+Since Linux 5.9, storage can be shared by multiple programs. When a program is
+attached to a cgroup, the kernel would create a new storage only if the map
+does not already contain an entry for the cgroup and attach type pair, or else
+the old storage is reused for the new attachment. If the map is attach type
+shared, then attach type is simply ignored during comparison. Storage is freed
+only when either the map or the cgroup attached to is being freed. Detaching
+will not directly free the storage, but it may cause the reference to the map
+to reach zero and indirectly freeing all storage in the map.
+
+The map is not associated with any BPF program, thus making sharing possible.
+However, the BPF program can still only associate with one map of each type
+(per-CPU and non-per-CPU). A BPF program cannot use more than one
+``BPF_MAP_TYPE_CGROUP_STORAGE`` or more than one
+``BPF_MAP_TYPE_PERCPU_CGROUP_STORAGE``.
+
+In all versions, userspace may use the the attach parameters of cgroup and
+attach type pair in ``struct bpf_cgroup_storage_key`` as the key to the BPF map
+APIs to read or update the storage for a given attachment. For Linux 5.9
+attach type shared storages, only the first value in the struct, cgroup inode
+id, is used during comparison, so userspace may just specify a ``__u64``
+directly.
+
+The storage is bound at attach time. Even if the program is attached to parent
+and triggers in child, the storage still belongs to the parent.
+
+Userspace cannot create a new entry in the map or delete an existing entry.
+Program test runs always use a temporary storage.
diff --git a/Documentation/bpf/prog_cgroup_sockopt.rst b/Documentation/bpf/prog_cgroup_sockopt.rst
index c47d9746..172f957 100644
--- a/Documentation/bpf/prog_cgroup_sockopt.rst
+++ b/Documentation/bpf/prog_cgroup_sockopt.rst
@@ -86,6 +86,20 @@
*not* the original input ``setsockopt`` arguments. The potentially
modified values will be then passed down to the kernel.
+Large optval
+============
+When the ``optval`` is greater than the ``PAGE_SIZE``, the BPF program
+can access only the first ``PAGE_SIZE`` of that data. So it has to options:
+
+* Set ``optlen`` to zero, which indicates that the kernel should
+ use the original buffer from the userspace. Any modifications
+ done by the BPF program to the ``optval`` are ignored.
+* Set ``optlen`` to the value less than ``PAGE_SIZE``, which
+ indicates that the kernel should use BPF's trimmed ``optval``.
+
+When the BPF program returns with the ``optlen`` greater than
+``PAGE_SIZE``, the userspace will receive ``EFAULT`` errno.
+
Example
=======
diff --git a/Documentation/bus-virt-phys-mapping.txt b/Documentation/bus-virt-phys-mapping.txt
deleted file mode 100644
index 4bb07c2..0000000
--- a/Documentation/bus-virt-phys-mapping.txt
+++ /dev/null
@@ -1,220 +0,0 @@
-==========================================================
-How to access I/O mapped memory from within device drivers
-==========================================================
-
-:Author: Linus
-
-.. warning::
-
- The virt_to_bus() and bus_to_virt() functions have been
- superseded by the functionality provided by the PCI DMA interface
- (see Documentation/DMA-API-HOWTO.txt). They continue
- to be documented below for historical purposes, but new code
- must not use them. --davidm 00/12/12
-
-::
-
- [ This is a mail message in response to a query on IO mapping, thus the
- strange format for a "document" ]
-
-The AHA-1542 is a bus-master device, and your patch makes the driver give the
-controller the physical address of the buffers, which is correct on x86
-(because all bus master devices see the physical memory mappings directly).
-
-However, on many setups, there are actually **three** different ways of looking
-at memory addresses, and in this case we actually want the third, the
-so-called "bus address".
-
-Essentially, the three ways of addressing memory are (this is "real memory",
-that is, normal RAM--see later about other details):
-
- - CPU untranslated. This is the "physical" address. Physical address
- 0 is what the CPU sees when it drives zeroes on the memory bus.
-
- - CPU translated address. This is the "virtual" address, and is
- completely internal to the CPU itself with the CPU doing the appropriate
- translations into "CPU untranslated".
-
- - bus address. This is the address of memory as seen by OTHER devices,
- not the CPU. Now, in theory there could be many different bus
- addresses, with each device seeing memory in some device-specific way, but
- happily most hardware designers aren't actually actively trying to make
- things any more complex than necessary, so you can assume that all
- external hardware sees the memory the same way.
-
-Now, on normal PCs the bus address is exactly the same as the physical
-address, and things are very simple indeed. However, they are that simple
-because the memory and the devices share the same address space, and that is
-not generally necessarily true on other PCI/ISA setups.
-
-Now, just as an example, on the PReP (PowerPC Reference Platform), the
-CPU sees a memory map something like this (this is from memory)::
-
- 0-2 GB "real memory"
- 2 GB-3 GB "system IO" (inb/out and similar accesses on x86)
- 3 GB-4 GB "IO memory" (shared memory over the IO bus)
-
-Now, that looks simple enough. However, when you look at the same thing from
-the viewpoint of the devices, you have the reverse, and the physical memory
-address 0 actually shows up as address 2 GB for any IO master.
-
-So when the CPU wants any bus master to write to physical memory 0, it
-has to give the master address 0x80000000 as the memory address.
-
-So, for example, depending on how the kernel is actually mapped on the
-PPC, you can end up with a setup like this::
-
- physical address: 0
- virtual address: 0xC0000000
- bus address: 0x80000000
-
-where all the addresses actually point to the same thing. It's just seen
-through different translations..
-
-Similarly, on the Alpha, the normal translation is::
-
- physical address: 0
- virtual address: 0xfffffc0000000000
- bus address: 0x40000000
-
-(but there are also Alphas where the physical address and the bus address
-are the same).
-
-Anyway, the way to look up all these translations, you do::
-
- #include <asm/io.h>
-
- phys_addr = virt_to_phys(virt_addr);
- virt_addr = phys_to_virt(phys_addr);
- bus_addr = virt_to_bus(virt_addr);
- virt_addr = bus_to_virt(bus_addr);
-
-Now, when do you need these?
-
-You want the **virtual** address when you are actually going to access that
-pointer from the kernel. So you can have something like this::
-
- /*
- * this is the hardware "mailbox" we use to communicate with
- * the controller. The controller sees this directly.
- */
- struct mailbox {
- __u32 status;
- __u32 bufstart;
- __u32 buflen;
- ..
- } mbox;
-
- unsigned char * retbuffer;
-
- /* get the address from the controller */
- retbuffer = bus_to_virt(mbox.bufstart);
- switch (retbuffer[0]) {
- case STATUS_OK:
- ...
-
-on the other hand, you want the bus address when you have a buffer that
-you want to give to the controller::
-
- /* ask the controller to read the sense status into "sense_buffer" */
- mbox.bufstart = virt_to_bus(&sense_buffer);
- mbox.buflen = sizeof(sense_buffer);
- mbox.status = 0;
- notify_controller(&mbox);
-
-And you generally **never** want to use the physical address, because you can't
-use that from the CPU (the CPU only uses translated virtual addresses), and
-you can't use it from the bus master.
-
-So why do we care about the physical address at all? We do need the physical
-address in some cases, it's just not very often in normal code. The physical
-address is needed if you use memory mappings, for example, because the
-"remap_pfn_range()" mm function wants the physical address of the memory to
-be remapped as measured in units of pages, a.k.a. the pfn (the memory
-management layer doesn't know about devices outside the CPU, so it
-shouldn't need to know about "bus addresses" etc).
-
-.. note::
-
- The above is only one part of the whole equation. The above
- only talks about "real memory", that is, CPU memory (RAM).
-
-There is a completely different type of memory too, and that's the "shared
-memory" on the PCI or ISA bus. That's generally not RAM (although in the case
-of a video graphics card it can be normal DRAM that is just used for a frame
-buffer), but can be things like a packet buffer in a network card etc.
-
-This memory is called "PCI memory" or "shared memory" or "IO memory" or
-whatever, and there is only one way to access it: the readb/writeb and
-related functions. You should never take the address of such memory, because
-there is really nothing you can do with such an address: it's not
-conceptually in the same memory space as "real memory" at all, so you cannot
-just dereference a pointer. (Sadly, on x86 it **is** in the same memory space,
-so on x86 it actually works to just deference a pointer, but it's not
-portable).
-
-For such memory, you can do things like:
-
- - reading::
-
- /*
- * read first 32 bits from ISA memory at 0xC0000, aka
- * C000:0000 in DOS terms
- */
- unsigned int signature = isa_readl(0xC0000);
-
- - remapping and writing::
-
- /*
- * remap framebuffer PCI memory area at 0xFC000000,
- * size 1MB, so that we can access it: We can directly
- * access only the 640k-1MB area, so anything else
- * has to be remapped.
- */
- void __iomem *baseptr = ioremap(0xFC000000, 1024*1024);
-
- /* write a 'A' to the offset 10 of the area */
- writeb('A',baseptr+10);
-
- /* unmap when we unload the driver */
- iounmap(baseptr);
-
- - copying and clearing::
-
- /* get the 6-byte Ethernet address at ISA address E000:0040 */
- memcpy_fromio(kernel_buffer, 0xE0040, 6);
- /* write a packet to the driver */
- memcpy_toio(0xE1000, skb->data, skb->len);
- /* clear the frame buffer */
- memset_io(0xA0000, 0, 0x10000);
-
-OK, that just about covers the basics of accessing IO portably. Questions?
-Comments? You may think that all the above is overly complex, but one day you
-might find yourself with a 500 MHz Alpha in front of you, and then you'll be
-happy that your driver works ;)
-
-Note that kernel versions 2.0.x (and earlier) mistakenly called the
-ioremap() function "vremap()". ioremap() is the proper name, but I
-didn't think straight when I wrote it originally. People who have to
-support both can do something like::
-
- /* support old naming silliness */
- #if LINUX_VERSION_CODE < 0x020100
- #define ioremap vremap
- #define iounmap vfree
- #endif
-
-at the top of their source files, and then they can use the right names
-even on 2.0.x systems.
-
-And the above sounds worse than it really is. Most real drivers really
-don't do all that complex things (or rather: the complexity is not so
-much in the actual IO accesses as in error handling and timeouts etc).
-It's generally not hard to fix drivers, and in many cases the code
-actually looks better afterwards::
-
- unsigned long signature = *(unsigned int *) 0xC0000;
- vs
- unsigned long signature = readl(0xC0000);
-
-I think the second version actually is more readable, no?
diff --git a/Documentation/cdrom/cdrom-standard.rst b/Documentation/cdrom/cdrom-standard.rst
index dde4f7f..70500b1 100644
--- a/Documentation/cdrom/cdrom-standard.rst
+++ b/Documentation/cdrom/cdrom-standard.rst
@@ -157,7 +157,6 @@
cdrom_release, /∗ release ∗/
NULL, /∗ fsync ∗/
NULL, /∗ fasync ∗/
- cdrom_media_changed, /∗ media change ∗/
NULL /∗ revalidate ∗/
};
@@ -368,19 +367,6 @@
::
- int media_changed(struct cdrom_device_info *cdi, int disc_nr)
-
-This function is very similar to the original function in $struct
-file_operations*. It returns 1 if the medium of the device *cdi->dev*
-has changed since the last call, and 0 otherwise. The parameter
-*disc_nr* identifies a specific slot in a juke-box, it should be
-ignored for single-disc drives. Note that by `re-routing` this
-function through *cdrom_media_changed()*, we can implement separate
-queues for the VFS and a new *ioctl()* function that can report device
-changes to software (e. g., an auto-mounting daemon).
-
-::
-
int tray_move(struct cdrom_device_info *cdi, int position)
This function, if implemented, should control the tray movement. (No
@@ -571,7 +557,7 @@
CDC_DRIVE_STATUS /* driver implements drive status */
The capability flag is declared *const*, to prevent drivers from
-accidentally tampering with the contents. The capability fags actually
+accidentally tampering with the contents. The capability flags actually
inform `cdrom.c` of what the driver can do. If the drive found
by the driver does not have the capability, is can be masked out by
the *cdrom_device_info* variable *mask*. For instance, the SCSI CD-ROM
@@ -750,7 +736,7 @@
Only a few routines in `cdrom.c` are exported to the drivers. In this
new section we will discuss these, as well as the functions that `take
-over' the CD-ROM interface to the kernel. The header file belonging
+over` the CD-ROM interface to the kernel. The header file belonging
to `cdrom.c` is called `cdrom.h`. Formerly, some of the contents of this
file were placed in the file `ucdrom.h`, but this file has now been
merged back into `cdrom.h`.
@@ -917,9 +903,7 @@
maximum number of discs in the juke-box found in the *cdrom_dops*.
`CDROM_MEDIA_CHANGED`
Returns 1 if a disc has been changed since the last call.
- Note that calls to *cdrom_media_changed* by the VFS are treated
- by an independent queue, so both mechanisms will detect a
- media change once. For juke-boxes, an extra argument *arg*
+ For juke-boxes, an extra argument *arg*
specifies the slot for which the information is given. The special
value *CDSL_CURRENT* requests that information about the currently
selected slot be returned.
diff --git a/Documentation/core-api/bus-virt-phys-mapping.rst b/Documentation/core-api/bus-virt-phys-mapping.rst
new file mode 100644
index 0000000..c7bc99c
--- /dev/null
+++ b/Documentation/core-api/bus-virt-phys-mapping.rst
@@ -0,0 +1,220 @@
+==========================================================
+How to access I/O mapped memory from within device drivers
+==========================================================
+
+:Author: Linus
+
+.. warning::
+
+ The virt_to_bus() and bus_to_virt() functions have been
+ superseded by the functionality provided by the PCI DMA interface
+ (see :doc:`/core-api/dma-api-howto`). They continue
+ to be documented below for historical purposes, but new code
+ must not use them. --davidm 00/12/12
+
+::
+
+ [ This is a mail message in response to a query on IO mapping, thus the
+ strange format for a "document" ]
+
+The AHA-1542 is a bus-master device, and your patch makes the driver give the
+controller the physical address of the buffers, which is correct on x86
+(because all bus master devices see the physical memory mappings directly).
+
+However, on many setups, there are actually **three** different ways of looking
+at memory addresses, and in this case we actually want the third, the
+so-called "bus address".
+
+Essentially, the three ways of addressing memory are (this is "real memory",
+that is, normal RAM--see later about other details):
+
+ - CPU untranslated. This is the "physical" address. Physical address
+ 0 is what the CPU sees when it drives zeroes on the memory bus.
+
+ - CPU translated address. This is the "virtual" address, and is
+ completely internal to the CPU itself with the CPU doing the appropriate
+ translations into "CPU untranslated".
+
+ - bus address. This is the address of memory as seen by OTHER devices,
+ not the CPU. Now, in theory there could be many different bus
+ addresses, with each device seeing memory in some device-specific way, but
+ happily most hardware designers aren't actually actively trying to make
+ things any more complex than necessary, so you can assume that all
+ external hardware sees the memory the same way.
+
+Now, on normal PCs the bus address is exactly the same as the physical
+address, and things are very simple indeed. However, they are that simple
+because the memory and the devices share the same address space, and that is
+not generally necessarily true on other PCI/ISA setups.
+
+Now, just as an example, on the PReP (PowerPC Reference Platform), the
+CPU sees a memory map something like this (this is from memory)::
+
+ 0-2 GB "real memory"
+ 2 GB-3 GB "system IO" (inb/out and similar accesses on x86)
+ 3 GB-4 GB "IO memory" (shared memory over the IO bus)
+
+Now, that looks simple enough. However, when you look at the same thing from
+the viewpoint of the devices, you have the reverse, and the physical memory
+address 0 actually shows up as address 2 GB for any IO master.
+
+So when the CPU wants any bus master to write to physical memory 0, it
+has to give the master address 0x80000000 as the memory address.
+
+So, for example, depending on how the kernel is actually mapped on the
+PPC, you can end up with a setup like this::
+
+ physical address: 0
+ virtual address: 0xC0000000
+ bus address: 0x80000000
+
+where all the addresses actually point to the same thing. It's just seen
+through different translations..
+
+Similarly, on the Alpha, the normal translation is::
+
+ physical address: 0
+ virtual address: 0xfffffc0000000000
+ bus address: 0x40000000
+
+(but there are also Alphas where the physical address and the bus address
+are the same).
+
+Anyway, the way to look up all these translations, you do::
+
+ #include <asm/io.h>
+
+ phys_addr = virt_to_phys(virt_addr);
+ virt_addr = phys_to_virt(phys_addr);
+ bus_addr = virt_to_bus(virt_addr);
+ virt_addr = bus_to_virt(bus_addr);
+
+Now, when do you need these?
+
+You want the **virtual** address when you are actually going to access that
+pointer from the kernel. So you can have something like this::
+
+ /*
+ * this is the hardware "mailbox" we use to communicate with
+ * the controller. The controller sees this directly.
+ */
+ struct mailbox {
+ __u32 status;
+ __u32 bufstart;
+ __u32 buflen;
+ ..
+ } mbox;
+
+ unsigned char * retbuffer;
+
+ /* get the address from the controller */
+ retbuffer = bus_to_virt(mbox.bufstart);
+ switch (retbuffer[0]) {
+ case STATUS_OK:
+ ...
+
+on the other hand, you want the bus address when you have a buffer that
+you want to give to the controller::
+
+ /* ask the controller to read the sense status into "sense_buffer" */
+ mbox.bufstart = virt_to_bus(&sense_buffer);
+ mbox.buflen = sizeof(sense_buffer);
+ mbox.status = 0;
+ notify_controller(&mbox);
+
+And you generally **never** want to use the physical address, because you can't
+use that from the CPU (the CPU only uses translated virtual addresses), and
+you can't use it from the bus master.
+
+So why do we care about the physical address at all? We do need the physical
+address in some cases, it's just not very often in normal code. The physical
+address is needed if you use memory mappings, for example, because the
+"remap_pfn_range()" mm function wants the physical address of the memory to
+be remapped as measured in units of pages, a.k.a. the pfn (the memory
+management layer doesn't know about devices outside the CPU, so it
+shouldn't need to know about "bus addresses" etc).
+
+.. note::
+
+ The above is only one part of the whole equation. The above
+ only talks about "real memory", that is, CPU memory (RAM).
+
+There is a completely different type of memory too, and that's the "shared
+memory" on the PCI or ISA bus. That's generally not RAM (although in the case
+of a video graphics card it can be normal DRAM that is just used for a frame
+buffer), but can be things like a packet buffer in a network card etc.
+
+This memory is called "PCI memory" or "shared memory" or "IO memory" or
+whatever, and there is only one way to access it: the readb/writeb and
+related functions. You should never take the address of such memory, because
+there is really nothing you can do with such an address: it's not
+conceptually in the same memory space as "real memory" at all, so you cannot
+just dereference a pointer. (Sadly, on x86 it **is** in the same memory space,
+so on x86 it actually works to just deference a pointer, but it's not
+portable).
+
+For such memory, you can do things like:
+
+ - reading::
+
+ /*
+ * read first 32 bits from ISA memory at 0xC0000, aka
+ * C000:0000 in DOS terms
+ */
+ unsigned int signature = isa_readl(0xC0000);
+
+ - remapping and writing::
+
+ /*
+ * remap framebuffer PCI memory area at 0xFC000000,
+ * size 1MB, so that we can access it: We can directly
+ * access only the 640k-1MB area, so anything else
+ * has to be remapped.
+ */
+ void __iomem *baseptr = ioremap(0xFC000000, 1024*1024);
+
+ /* write a 'A' to the offset 10 of the area */
+ writeb('A',baseptr+10);
+
+ /* unmap when we unload the driver */
+ iounmap(baseptr);
+
+ - copying and clearing::
+
+ /* get the 6-byte Ethernet address at ISA address E000:0040 */
+ memcpy_fromio(kernel_buffer, 0xE0040, 6);
+ /* write a packet to the driver */
+ memcpy_toio(0xE1000, skb->data, skb->len);
+ /* clear the frame buffer */
+ memset_io(0xA0000, 0, 0x10000);
+
+OK, that just about covers the basics of accessing IO portably. Questions?
+Comments? You may think that all the above is overly complex, but one day you
+might find yourself with a 500 MHz Alpha in front of you, and then you'll be
+happy that your driver works ;)
+
+Note that kernel versions 2.0.x (and earlier) mistakenly called the
+ioremap() function "vremap()". ioremap() is the proper name, but I
+didn't think straight when I wrote it originally. People who have to
+support both can do something like::
+
+ /* support old naming silliness */
+ #if LINUX_VERSION_CODE < 0x020100
+ #define ioremap vremap
+ #define iounmap vfree
+ #endif
+
+at the top of their source files, and then they can use the right names
+even on 2.0.x systems.
+
+And the above sounds worse than it really is. Most real drivers really
+don't do all that complex things (or rather: the complexity is not so
+much in the actual IO accesses as in error handling and timeouts etc).
+It's generally not hard to fix drivers, and in many cases the code
+actually looks better afterwards::
+
+ unsigned long signature = *(unsigned int *) 0xC0000;
+ vs
+ unsigned long signature = readl(0xC0000);
+
+I think the second version actually is more readable, no?
diff --git a/Documentation/core-api/cpu_hotplug.rst b/Documentation/core-api/cpu_hotplug.rst
index 4a50ab7..298c9c8 100644
--- a/Documentation/core-api/cpu_hotplug.rst
+++ b/Documentation/core-api/cpu_hotplug.rst
@@ -35,8 +35,8 @@
other CPUs later online.
``nr_cpus=n``
- Restrict the total amount CPUs the kernel will support. If the number
- supplied here is lower than the number of physically available CPUs than
+ Restrict the total amount of CPUs the kernel will support. If the number
+ supplied here is lower than the number of physically available CPUs, then
those CPUs can not be brought online later.
``additional_cpus=n``
@@ -50,13 +50,6 @@
This option is limited to the X86 and S390 architecture.
-``cede_offline={"off","on"}``
- Use this option to disable/enable putting offlined processors to an extended
- ``H_CEDE`` state on supported pseries platforms. If nothing is specified,
- ``cede_offline`` is set to "on".
-
- This option is limited to the PowerPC architecture.
-
``cpu0_hotplug``
Allow to shutdown CPU0.
diff --git a/Documentation/core-api/dma-api.rst b/Documentation/core-api/dma-api.rst
index 2d8d2fe..3b3abbb 100644
--- a/Documentation/core-api/dma-api.rst
+++ b/Documentation/core-api/dma-api.rst
@@ -5,7 +5,7 @@
:Author: James E.J. Bottomley <James.Bottomley@HansenPartnership.com>
This document describes the DMA API. For a more gentle introduction
-of the API (and actual examples), see Documentation/DMA-API-HOWTO.txt.
+of the API (and actual examples), see :doc:`/core-api/dma-api-howto`.
This API is split into two pieces. Part I describes the basic API.
Part II describes extensions for supporting non-consistent memory
@@ -206,6 +206,14 @@
::
+ bool
+ dma_need_sync(struct device *dev, dma_addr_t dma_addr);
+
+Returns %true if dma_sync_single_for_{device,cpu} calls are required to
+transfer memory ownership. Returns %false if those calls can be skipped.
+
+::
+
unsigned long
dma_get_merge_boundary(struct device *dev);
@@ -471,7 +479,7 @@
dma_attrs.
The interpretation of DMA attributes is architecture-specific, and
-each attribute should be documented in Documentation/DMA-attributes.txt.
+each attribute should be documented in :doc:`/core-api/dma-attributes`.
If dma_attrs are 0, the semantics of each of these functions
is identical to those of the corresponding function
@@ -484,7 +492,7 @@
#include <linux/dma-mapping.h>
/* DMA_ATTR_FOO should be defined in linux/dma-mapping.h and
- * documented in Documentation/DMA-attributes.txt */
+ * documented in Documentation/core-api/dma-attributes.rst */
...
unsigned long attr;
diff --git a/Documentation/core-api/dma-isa-lpc.rst b/Documentation/core-api/dma-isa-lpc.rst
index b1ec7b1..e59a3d3 100644
--- a/Documentation/core-api/dma-isa-lpc.rst
+++ b/Documentation/core-api/dma-isa-lpc.rst
@@ -17,7 +17,7 @@
#include <asm/dma.h>
The first is the generic DMA API used to convert virtual addresses to
-bus addresses (see Documentation/DMA-API.txt for details).
+bus addresses (see :doc:`/core-api/dma-api` for details).
The second contains the routines specific to ISA DMA transfers. Since
this is not present on all platforms make sure you construct your
diff --git a/Documentation/core-api/idr.rst b/Documentation/core-api/idr.rst
index a273805..2eb5afd 100644
--- a/Documentation/core-api/idr.rst
+++ b/Documentation/core-api/idr.rst
@@ -20,48 +20,48 @@
IDR usage
=========
-Start by initialising an IDR, either with :c:func:`DEFINE_IDR`
-for statically allocated IDRs or :c:func:`idr_init` for dynamically
+Start by initialising an IDR, either with DEFINE_IDR()
+for statically allocated IDRs or idr_init() for dynamically
allocated IDRs.
-You can call :c:func:`idr_alloc` to allocate an unused ID. Look up
-the pointer you associated with the ID by calling :c:func:`idr_find`
-and free the ID by calling :c:func:`idr_remove`.
+You can call idr_alloc() to allocate an unused ID. Look up
+the pointer you associated with the ID by calling idr_find()
+and free the ID by calling idr_remove().
If you need to change the pointer associated with an ID, you can call
-:c:func:`idr_replace`. One common reason to do this is to reserve an
+idr_replace(). One common reason to do this is to reserve an
ID by passing a ``NULL`` pointer to the allocation function; initialise the
object with the reserved ID and finally insert the initialised object
into the IDR.
Some users need to allocate IDs larger than ``INT_MAX``. So far all of
these users have been content with a ``UINT_MAX`` limit, and they use
-:c:func:`idr_alloc_u32`. If you need IDs that will not fit in a u32,
+idr_alloc_u32(). If you need IDs that will not fit in a u32,
we will work with you to address your needs.
If you need to allocate IDs sequentially, you can use
-:c:func:`idr_alloc_cyclic`. The IDR becomes less efficient when dealing
+idr_alloc_cyclic(). The IDR becomes less efficient when dealing
with larger IDs, so using this function comes at a slight cost.
To perform an action on all pointers used by the IDR, you can
-either use the callback-based :c:func:`idr_for_each` or the
-iterator-style :c:func:`idr_for_each_entry`. You may need to use
-:c:func:`idr_for_each_entry_continue` to continue an iteration. You can
-also use :c:func:`idr_get_next` if the iterator doesn't fit your needs.
+either use the callback-based idr_for_each() or the
+iterator-style idr_for_each_entry(). You may need to use
+idr_for_each_entry_continue() to continue an iteration. You can
+also use idr_get_next() if the iterator doesn't fit your needs.
-When you have finished using an IDR, you can call :c:func:`idr_destroy`
+When you have finished using an IDR, you can call idr_destroy()
to release the memory used by the IDR. This will not free the objects
pointed to from the IDR; if you want to do that, use one of the iterators
to do it.
-You can use :c:func:`idr_is_empty` to find out whether there are any
+You can use idr_is_empty() to find out whether there are any
IDs currently allocated.
If you need to take a lock while allocating a new ID from the IDR,
you may need to pass a restrictive set of GFP flags, which can lead
to the IDR being unable to allocate memory. To work around this,
-you can call :c:func:`idr_preload` before taking the lock, and then
-:c:func:`idr_preload_end` after the allocation.
+you can call idr_preload() before taking the lock, and then
+idr_preload_end() after the allocation.
.. kernel-doc:: include/linux/idr.h
:doc: idr sync
diff --git a/Documentation/core-api/index.rst b/Documentation/core-api/index.rst
index 15ab861..69171b1 100644
--- a/Documentation/core-api/index.rst
+++ b/Documentation/core-api/index.rst
@@ -39,6 +39,8 @@
rbtree
generic-radix-tree
packing
+ bus-virt-phys-mapping
+ this_cpu_ops
timekeeping
errseq
@@ -82,6 +84,7 @@
:maxdepth: 1
memory-allocation
+ unaligned-memory-access
dma-api
dma-api-howto
dma-attributes
diff --git a/Documentation/core-api/kobject.rst b/Documentation/core-api/kobject.rst
index e93dc8c..2739f8b 100644
--- a/Documentation/core-api/kobject.rst
+++ b/Documentation/core-api/kobject.rst
@@ -6,7 +6,7 @@
:Last updated: December 19, 2007
Based on an original article by Jon Corbet for lwn.net written October 1,
-2003 and located at http://lwn.net/Articles/51437/
+2003 and located at https://lwn.net/Articles/51437/
Part of the difficulty in understanding the driver model - and the kobject
abstraction upon which it is built - is that there is no obvious starting
diff --git a/Documentation/core-api/memory-allocation.rst b/Documentation/core-api/memory-allocation.rst
index 4aa82dd..4446a1ac 100644
--- a/Documentation/core-api/memory-allocation.rst
+++ b/Documentation/core-api/memory-allocation.rst
@@ -84,6 +84,50 @@
And even with hardware with restrictions it is preferable to use
`dma_alloc*` APIs.
+GFP flags and reclaim behavior
+------------------------------
+Memory allocations may trigger direct or background reclaim and it is
+useful to understand how hard the page allocator will try to satisfy that
+or another request.
+
+ * ``GFP_KERNEL & ~__GFP_RECLAIM`` - optimistic allocation without _any_
+ attempt to free memory at all. The most light weight mode which even
+ doesn't kick the background reclaim. Should be used carefully because it
+ might deplete the memory and the next user might hit the more aggressive
+ reclaim.
+
+ * ``GFP_KERNEL & ~__GFP_DIRECT_RECLAIM`` (or ``GFP_NOWAIT``)- optimistic
+ allocation without any attempt to free memory from the current
+ context but can wake kswapd to reclaim memory if the zone is below
+ the low watermark. Can be used from either atomic contexts or when
+ the request is a performance optimization and there is another
+ fallback for a slow path.
+
+ * ``(GFP_KERNEL|__GFP_HIGH) & ~__GFP_DIRECT_RECLAIM`` (aka ``GFP_ATOMIC``) -
+ non sleeping allocation with an expensive fallback so it can access
+ some portion of memory reserves. Usually used from interrupt/bottom-half
+ context with an expensive slow path fallback.
+
+ * ``GFP_KERNEL`` - both background and direct reclaim are allowed and the
+ **default** page allocator behavior is used. That means that not costly
+ allocation requests are basically no-fail but there is no guarantee of
+ that behavior so failures have to be checked properly by callers
+ (e.g. OOM killer victim is allowed to fail currently).
+
+ * ``GFP_KERNEL | __GFP_NORETRY`` - overrides the default allocator behavior
+ and all allocation requests fail early rather than cause disruptive
+ reclaim (one round of reclaim in this implementation). The OOM killer
+ is not invoked.
+
+ * ``GFP_KERNEL | __GFP_RETRY_MAYFAIL`` - overrides the default allocator
+ behavior and all allocation requests try really hard. The request
+ will fail if the reclaim cannot make any progress. The OOM killer
+ won't be triggered.
+
+ * ``GFP_KERNEL | __GFP_NOFAIL`` - overrides the default allocator behavior
+ and all allocation requests will loop endlessly until they succeed.
+ This might be really dangerous especially for larger orders.
+
Selecting memory allocator
==========================
diff --git a/Documentation/core-api/padata.rst b/Documentation/core-api/padata.rst
index 0830e5b..3517571 100644
--- a/Documentation/core-api/padata.rst
+++ b/Documentation/core-api/padata.rst
@@ -27,22 +27,11 @@
#include <linux/padata.h>
- struct padata_instance *padata_alloc_possible(const char *name);
+ struct padata_instance *padata_alloc(const char *name);
'name' simply identifies the instance.
-There are functions for enabling and disabling the instance::
-
- int padata_start(struct padata_instance *pinst);
- void padata_stop(struct padata_instance *pinst);
-
-These functions are setting or clearing the "PADATA_INIT" flag; if that flag is
-not set, other functions will refuse to work. padata_start() returns zero on
-success (flag set) or -EINVAL if the padata cpumask contains no active CPU
-(flag not set). padata_stop() clears the flag and blocks until the padata
-instance is unused.
-
-Finally, complete padata initialization by allocating a padata_shell::
+Then, complete padata initialization by allocating a padata_shell::
struct padata_shell *padata_alloc_shell(struct padata_instance *pinst);
@@ -155,11 +144,10 @@
Destroying
----------
-Cleaning up a padata instance predictably involves calling the three free
+Cleaning up a padata instance predictably involves calling the two free
functions that correspond to the allocation in reverse::
void padata_free_shell(struct padata_shell *ps);
- void padata_stop(struct padata_instance *pinst);
void padata_free(struct padata_instance *pinst);
It is the user's responsibility to ensure all outstanding jobs are complete
diff --git a/Documentation/core-api/pin_user_pages.rst b/Documentation/core-api/pin_user_pages.rst
index 6068266..7ca8c7b 100644
--- a/Documentation/core-api/pin_user_pages.rst
+++ b/Documentation/core-api/pin_user_pages.rst
@@ -33,7 +33,7 @@
pin_user_pages*() APIs are clearly distinct from the get_user_pages*() APIs, so
that's a natural dividing line, and a good point to make separate wrapper calls.
In other words, use pin_user_pages*() for DMA-pinned pages, and
-get_user_pages*() for other cases. There are four cases described later on in
+get_user_pages*() for other cases. There are five cases described later on in
this document, to further clarify that concept.
FOLL_PIN and FOLL_GET are mutually exclusive for a given gup call. However,
diff --git a/Documentation/core-api/printk-basics.rst b/Documentation/core-api/printk-basics.rst
index 563a9ce..965e428 100644
--- a/Documentation/core-api/printk-basics.rst
+++ b/Documentation/core-api/printk-basics.rst
@@ -69,7 +69,7 @@
The result shows the *current*, *default*, *minimum* and *boot-time-default* log
levels.
-To change the current console_loglevel simply write the the desired level to
+To change the current console_loglevel simply write the desired level to
``/proc/sys/kernel/printk``. For example, to print all messages to the console::
# echo 8 > /proc/sys/kernel/printk
diff --git a/Documentation/core-api/printk-formats.rst b/Documentation/core-api/printk-formats.rst
index 8c9aba2..6d26c5c 100644
--- a/Documentation/core-api/printk-formats.rst
+++ b/Documentation/core-api/printk-formats.rst
@@ -317,7 +317,7 @@
The additional ``c`` specifier can be used with the ``I`` specifier to
print a compressed IPv6 address as described by
-http://tools.ietf.org/html/rfc5952
+https://tools.ietf.org/html/rfc5952
Passed by reference.
@@ -341,7 +341,7 @@
flowinfo a ``/`` and scope a ``%``, each followed by the actual value.
In case of an IPv6 address the compressed IPv6 address as described by
-http://tools.ietf.org/html/rfc5952 is being used if the additional
+https://tools.ietf.org/html/rfc5952 is being used if the additional
specifier ``c`` is given. The IPv6 address is surrounded by ``[``, ``]`` in
case of additional specifiers ``p``, ``f`` or ``s`` as suggested by
https://tools.ietf.org/html/draft-ietf-6man-text-addr-representation-07
@@ -494,9 +494,11 @@
%pt[RT]t HH:MM:SS
%pt[RT][dt][r]
-For printing date and time as represented by
+For printing date and time as represented by::
+
R struct rtc_time structure
T time64_t type
+
in human readable format.
By default year will be incremented by 1900 and month by 1.
diff --git a/Documentation/this_cpu_ops.txt b/Documentation/core-api/this_cpu_ops.rst
similarity index 100%
rename from Documentation/this_cpu_ops.txt
rename to Documentation/core-api/this_cpu_ops.rst
diff --git a/Documentation/process/unaligned-memory-access.rst b/Documentation/core-api/unaligned-memory-access.rst
similarity index 100%
rename from Documentation/process/unaligned-memory-access.rst
rename to Documentation/core-api/unaligned-memory-access.rst
diff --git a/Documentation/crypto/api-intro.rst b/Documentation/crypto/api-intro.rst
new file mode 100644
index 0000000..15201be
--- /dev/null
+++ b/Documentation/crypto/api-intro.rst
@@ -0,0 +1,262 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+=============================
+Scatterlist Cryptographic API
+=============================
+
+Introduction
+============
+
+The Scatterlist Crypto API takes page vectors (scatterlists) as
+arguments, and works directly on pages. In some cases (e.g. ECB
+mode ciphers), this will allow for pages to be encrypted in-place
+with no copying.
+
+One of the initial goals of this design was to readily support IPsec,
+so that processing can be applied to paged skb's without the need
+for linearization.
+
+
+Details
+=======
+
+At the lowest level are algorithms, which register dynamically with the
+API.
+
+'Transforms' are user-instantiated objects, which maintain state, handle all
+of the implementation logic (e.g. manipulating page vectors) and provide an
+abstraction to the underlying algorithms. However, at the user
+level they are very simple.
+
+Conceptually, the API layering looks like this::
+
+ [transform api] (user interface)
+ [transform ops] (per-type logic glue e.g. cipher.c, compress.c)
+ [algorithm api] (for registering algorithms)
+
+The idea is to make the user interface and algorithm registration API
+very simple, while hiding the core logic from both. Many good ideas
+from existing APIs such as Cryptoapi and Nettle have been adapted for this.
+
+The API currently supports five main types of transforms: AEAD (Authenticated
+Encryption with Associated Data), Block Ciphers, Ciphers, Compressors and
+Hashes.
+
+Please note that Block Ciphers is somewhat of a misnomer. It is in fact
+meant to support all ciphers including stream ciphers. The difference
+between Block Ciphers and Ciphers is that the latter operates on exactly
+one block while the former can operate on an arbitrary amount of data,
+subject to block size requirements (i.e., non-stream ciphers can only
+process multiples of blocks).
+
+Here's an example of how to use the API::
+
+ #include <crypto/hash.h>
+ #include <linux/err.h>
+ #include <linux/scatterlist.h>
+
+ struct scatterlist sg[2];
+ char result[128];
+ struct crypto_ahash *tfm;
+ struct ahash_request *req;
+
+ tfm = crypto_alloc_ahash("md5", 0, CRYPTO_ALG_ASYNC);
+ if (IS_ERR(tfm))
+ fail();
+
+ /* ... set up the scatterlists ... */
+
+ req = ahash_request_alloc(tfm, GFP_ATOMIC);
+ if (!req)
+ fail();
+
+ ahash_request_set_callback(req, 0, NULL, NULL);
+ ahash_request_set_crypt(req, sg, result, 2);
+
+ if (crypto_ahash_digest(req))
+ fail();
+
+ ahash_request_free(req);
+ crypto_free_ahash(tfm);
+
+
+Many real examples are available in the regression test module (tcrypt.c).
+
+
+Developer Notes
+===============
+
+Transforms may only be allocated in user context, and cryptographic
+methods may only be called from softirq and user contexts. For
+transforms with a setkey method it too should only be called from
+user context.
+
+When using the API for ciphers, performance will be optimal if each
+scatterlist contains data which is a multiple of the cipher's block
+size (typically 8 bytes). This prevents having to do any copying
+across non-aligned page fragment boundaries.
+
+
+Adding New Algorithms
+=====================
+
+When submitting a new algorithm for inclusion, a mandatory requirement
+is that at least a few test vectors from known sources (preferably
+standards) be included.
+
+Converting existing well known code is preferred, as it is more likely
+to have been reviewed and widely tested. If submitting code from LGPL
+sources, please consider changing the license to GPL (see section 3 of
+the LGPL).
+
+Algorithms submitted must also be generally patent-free (e.g. IDEA
+will not be included in the mainline until around 2011), and be based
+on a recognized standard and/or have been subjected to appropriate
+peer review.
+
+Also check for any RFCs which may relate to the use of specific algorithms,
+as well as general application notes such as RFC2451 ("The ESP CBC-Mode
+Cipher Algorithms").
+
+It's a good idea to avoid using lots of macros and use inlined functions
+instead, as gcc does a good job with inlining, while excessive use of
+macros can cause compilation problems on some platforms.
+
+Also check the TODO list at the web site listed below to see what people
+might already be working on.
+
+
+Bugs
+====
+
+Send bug reports to:
+ linux-crypto@vger.kernel.org
+
+Cc:
+ Herbert Xu <herbert@gondor.apana.org.au>,
+ David S. Miller <davem@redhat.com>
+
+
+Further Information
+===================
+
+For further patches and various updates, including the current TODO
+list, see:
+http://gondor.apana.org.au/~herbert/crypto/
+
+
+Authors
+=======
+
+- James Morris
+- David S. Miller
+- Herbert Xu
+
+
+Credits
+=======
+
+The following people provided invaluable feedback during the development
+of the API:
+
+ - Alexey Kuznetzov
+ - Rusty Russell
+ - Herbert Valerio Riedel
+ - Jeff Garzik
+ - Michael Richardson
+ - Andrew Morton
+ - Ingo Oeser
+ - Christoph Hellwig
+
+Portions of this API were derived from the following projects:
+
+ Kerneli Cryptoapi (http://www.kerneli.org/)
+ - Alexander Kjeldaas
+ - Herbert Valerio Riedel
+ - Kyle McMartin
+ - Jean-Luc Cooke
+ - David Bryson
+ - Clemens Fruhwirth
+ - Tobias Ringstrom
+ - Harald Welte
+
+and;
+
+ Nettle (https://www.lysator.liu.se/~nisse/nettle/)
+ - Niels Möller
+
+Original developers of the crypto algorithms:
+
+ - Dana L. How (DES)
+ - Andrew Tridgell and Steve French (MD4)
+ - Colin Plumb (MD5)
+ - Steve Reid (SHA1)
+ - Jean-Luc Cooke (SHA256, SHA384, SHA512)
+ - Kazunori Miyazawa / USAGI (HMAC)
+ - Matthew Skala (Twofish)
+ - Dag Arne Osvik (Serpent)
+ - Brian Gladman (AES)
+ - Kartikey Mahendra Bhatt (CAST6)
+ - Jon Oberheide (ARC4)
+ - Jouni Malinen (Michael MIC)
+ - NTT(Nippon Telegraph and Telephone Corporation) (Camellia)
+
+SHA1 algorithm contributors:
+ - Jean-Francois Dive
+
+DES algorithm contributors:
+ - Raimar Falke
+ - Gisle Sælensminde
+ - Niels Möller
+
+Blowfish algorithm contributors:
+ - Herbert Valerio Riedel
+ - Kyle McMartin
+
+Twofish algorithm contributors:
+ - Werner Koch
+ - Marc Mutz
+
+SHA256/384/512 algorithm contributors:
+ - Andrew McDonald
+ - Kyle McMartin
+ - Herbert Valerio Riedel
+
+AES algorithm contributors:
+ - Alexander Kjeldaas
+ - Herbert Valerio Riedel
+ - Kyle McMartin
+ - Adam J. Richter
+ - Fruhwirth Clemens (i586)
+ - Linus Torvalds (i586)
+
+CAST5 algorithm contributors:
+ - Kartikey Mahendra Bhatt (original developers unknown, FSF copyright).
+
+TEA/XTEA algorithm contributors:
+ - Aaron Grothe
+ - Michael Ringe
+
+Khazad algorithm contributors:
+ - Aaron Grothe
+
+Whirlpool algorithm contributors:
+ - Aaron Grothe
+ - Jean-Luc Cooke
+
+Anubis algorithm contributors:
+ - Aaron Grothe
+
+Tiger algorithm contributors:
+ - Aaron Grothe
+
+VIA PadLock contributors:
+ - Michal Ludvig
+
+Camellia algorithm contributors:
+ - NTT(Nippon Telegraph and Telephone Corporation) (Camellia)
+
+Generic scatterwalk code by Adam J. Richter <adam@yggdrasil.com>
+
+Please send any credits updates or corrections to:
+Herbert Xu <herbert@gondor.apana.org.au>
diff --git a/Documentation/crypto/api-intro.txt b/Documentation/crypto/api-intro.txt
deleted file mode 100644
index 45d943f..0000000
--- a/Documentation/crypto/api-intro.txt
+++ /dev/null
@@ -1,250 +0,0 @@
-
- Scatterlist Cryptographic API
-
-INTRODUCTION
-
-The Scatterlist Crypto API takes page vectors (scatterlists) as
-arguments, and works directly on pages. In some cases (e.g. ECB
-mode ciphers), this will allow for pages to be encrypted in-place
-with no copying.
-
-One of the initial goals of this design was to readily support IPsec,
-so that processing can be applied to paged skb's without the need
-for linearization.
-
-
-DETAILS
-
-At the lowest level are algorithms, which register dynamically with the
-API.
-
-'Transforms' are user-instantiated objects, which maintain state, handle all
-of the implementation logic (e.g. manipulating page vectors) and provide an
-abstraction to the underlying algorithms. However, at the user
-level they are very simple.
-
-Conceptually, the API layering looks like this:
-
- [transform api] (user interface)
- [transform ops] (per-type logic glue e.g. cipher.c, compress.c)
- [algorithm api] (for registering algorithms)
-
-The idea is to make the user interface and algorithm registration API
-very simple, while hiding the core logic from both. Many good ideas
-from existing APIs such as Cryptoapi and Nettle have been adapted for this.
-
-The API currently supports five main types of transforms: AEAD (Authenticated
-Encryption with Associated Data), Block Ciphers, Ciphers, Compressors and
-Hashes.
-
-Please note that Block Ciphers is somewhat of a misnomer. It is in fact
-meant to support all ciphers including stream ciphers. The difference
-between Block Ciphers and Ciphers is that the latter operates on exactly
-one block while the former can operate on an arbitrary amount of data,
-subject to block size requirements (i.e., non-stream ciphers can only
-process multiples of blocks).
-
-Here's an example of how to use the API:
-
- #include <crypto/hash.h>
- #include <linux/err.h>
- #include <linux/scatterlist.h>
-
- struct scatterlist sg[2];
- char result[128];
- struct crypto_ahash *tfm;
- struct ahash_request *req;
-
- tfm = crypto_alloc_ahash("md5", 0, CRYPTO_ALG_ASYNC);
- if (IS_ERR(tfm))
- fail();
-
- /* ... set up the scatterlists ... */
-
- req = ahash_request_alloc(tfm, GFP_ATOMIC);
- if (!req)
- fail();
-
- ahash_request_set_callback(req, 0, NULL, NULL);
- ahash_request_set_crypt(req, sg, result, 2);
-
- if (crypto_ahash_digest(req))
- fail();
-
- ahash_request_free(req);
- crypto_free_ahash(tfm);
-
-
-Many real examples are available in the regression test module (tcrypt.c).
-
-
-DEVELOPER NOTES
-
-Transforms may only be allocated in user context, and cryptographic
-methods may only be called from softirq and user contexts. For
-transforms with a setkey method it too should only be called from
-user context.
-
-When using the API for ciphers, performance will be optimal if each
-scatterlist contains data which is a multiple of the cipher's block
-size (typically 8 bytes). This prevents having to do any copying
-across non-aligned page fragment boundaries.
-
-
-ADDING NEW ALGORITHMS
-
-When submitting a new algorithm for inclusion, a mandatory requirement
-is that at least a few test vectors from known sources (preferably
-standards) be included.
-
-Converting existing well known code is preferred, as it is more likely
-to have been reviewed and widely tested. If submitting code from LGPL
-sources, please consider changing the license to GPL (see section 3 of
-the LGPL).
-
-Algorithms submitted must also be generally patent-free (e.g. IDEA
-will not be included in the mainline until around 2011), and be based
-on a recognized standard and/or have been subjected to appropriate
-peer review.
-
-Also check for any RFCs which may relate to the use of specific algorithms,
-as well as general application notes such as RFC2451 ("The ESP CBC-Mode
-Cipher Algorithms").
-
-It's a good idea to avoid using lots of macros and use inlined functions
-instead, as gcc does a good job with inlining, while excessive use of
-macros can cause compilation problems on some platforms.
-
-Also check the TODO list at the web site listed below to see what people
-might already be working on.
-
-
-BUGS
-
-Send bug reports to:
-linux-crypto@vger.kernel.org
-Cc: Herbert Xu <herbert@gondor.apana.org.au>,
- David S. Miller <davem@redhat.com>
-
-
-FURTHER INFORMATION
-
-For further patches and various updates, including the current TODO
-list, see:
-http://gondor.apana.org.au/~herbert/crypto/
-
-
-AUTHORS
-
-James Morris
-David S. Miller
-Herbert Xu
-
-
-CREDITS
-
-The following people provided invaluable feedback during the development
-of the API:
-
- Alexey Kuznetzov
- Rusty Russell
- Herbert Valerio Riedel
- Jeff Garzik
- Michael Richardson
- Andrew Morton
- Ingo Oeser
- Christoph Hellwig
-
-Portions of this API were derived from the following projects:
-
- Kerneli Cryptoapi (http://www.kerneli.org/)
- Alexander Kjeldaas
- Herbert Valerio Riedel
- Kyle McMartin
- Jean-Luc Cooke
- David Bryson
- Clemens Fruhwirth
- Tobias Ringstrom
- Harald Welte
-
-and;
-
- Nettle (http://www.lysator.liu.se/~nisse/nettle/)
- Niels Möller
-
-Original developers of the crypto algorithms:
-
- Dana L. How (DES)
- Andrew Tridgell and Steve French (MD4)
- Colin Plumb (MD5)
- Steve Reid (SHA1)
- Jean-Luc Cooke (SHA256, SHA384, SHA512)
- Kazunori Miyazawa / USAGI (HMAC)
- Matthew Skala (Twofish)
- Dag Arne Osvik (Serpent)
- Brian Gladman (AES)
- Kartikey Mahendra Bhatt (CAST6)
- Jon Oberheide (ARC4)
- Jouni Malinen (Michael MIC)
- NTT(Nippon Telegraph and Telephone Corporation) (Camellia)
-
-SHA1 algorithm contributors:
- Jean-Francois Dive
-
-DES algorithm contributors:
- Raimar Falke
- Gisle Sælensminde
- Niels Möller
-
-Blowfish algorithm contributors:
- Herbert Valerio Riedel
- Kyle McMartin
-
-Twofish algorithm contributors:
- Werner Koch
- Marc Mutz
-
-SHA256/384/512 algorithm contributors:
- Andrew McDonald
- Kyle McMartin
- Herbert Valerio Riedel
-
-AES algorithm contributors:
- Alexander Kjeldaas
- Herbert Valerio Riedel
- Kyle McMartin
- Adam J. Richter
- Fruhwirth Clemens (i586)
- Linus Torvalds (i586)
-
-CAST5 algorithm contributors:
- Kartikey Mahendra Bhatt (original developers unknown, FSF copyright).
-
-TEA/XTEA algorithm contributors:
- Aaron Grothe
- Michael Ringe
-
-Khazad algorithm contributors:
- Aaron Grothe
-
-Whirlpool algorithm contributors:
- Aaron Grothe
- Jean-Luc Cooke
-
-Anubis algorithm contributors:
- Aaron Grothe
-
-Tiger algorithm contributors:
- Aaron Grothe
-
-VIA PadLock contributors:
- Michal Ludvig
-
-Camellia algorithm contributors:
- NTT(Nippon Telegraph and Telephone Corporation) (Camellia)
-
-Generic scatterwalk code by Adam J. Richter <adam@yggdrasil.com>
-
-Please send any credits updates or corrections to:
-Herbert Xu <herbert@gondor.apana.org.au>
-
diff --git a/Documentation/crypto/asymmetric-keys.rst b/Documentation/crypto/asymmetric-keys.rst
new file mode 100644
index 0000000..349f44a
--- /dev/null
+++ b/Documentation/crypto/asymmetric-keys.rst
@@ -0,0 +1,424 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+=============================================
+Asymmetric / Public-key Cryptography Key Type
+=============================================
+
+.. Contents:
+
+ - Overview.
+ - Key identification.
+ - Accessing asymmetric keys.
+ - Signature verification.
+ - Asymmetric key subtypes.
+ - Instantiation data parsers.
+ - Keyring link restrictions.
+
+
+Overview
+========
+
+The "asymmetric" key type is designed to be a container for the keys used in
+public-key cryptography, without imposing any particular restrictions on the
+form or mechanism of the cryptography or form of the key.
+
+The asymmetric key is given a subtype that defines what sort of data is
+associated with the key and provides operations to describe and destroy it.
+However, no requirement is made that the key data actually be stored in the
+key.
+
+A completely in-kernel key retention and operation subtype can be defined, but
+it would also be possible to provide access to cryptographic hardware (such as
+a TPM) that might be used to both retain the relevant key and perform
+operations using that key. In such a case, the asymmetric key would then
+merely be an interface to the TPM driver.
+
+Also provided is the concept of a data parser. Data parsers are responsible
+for extracting information from the blobs of data passed to the instantiation
+function. The first data parser that recognises the blob gets to set the
+subtype of the key and define the operations that can be done on that key.
+
+A data parser may interpret the data blob as containing the bits representing a
+key, or it may interpret it as a reference to a key held somewhere else in the
+system (for example, a TPM).
+
+
+Key Identification
+==================
+
+If a key is added with an empty name, the instantiation data parsers are given
+the opportunity to pre-parse a key and to determine the description the key
+should be given from the content of the key.
+
+This can then be used to refer to the key, either by complete match or by
+partial match. The key type may also use other criteria to refer to a key.
+
+The asymmetric key type's match function can then perform a wider range of
+comparisons than just the straightforward comparison of the description with
+the criterion string:
+
+ 1) If the criterion string is of the form "id:<hexdigits>" then the match
+ function will examine a key's fingerprint to see if the hex digits given
+ after the "id:" match the tail. For instance::
+
+ keyctl search @s asymmetric id:5acc2142
+
+ will match a key with fingerprint::
+
+ 1A00 2040 7601 7889 DE11 882C 3823 04AD 5ACC 2142
+
+ 2) If the criterion string is of the form "<subtype>:<hexdigits>" then the
+ match will match the ID as in (1), but with the added restriction that
+ only keys of the specified subtype (e.g. tpm) will be matched. For
+ instance::
+
+ keyctl search @s asymmetric tpm:5acc2142
+
+Looking in /proc/keys, the last 8 hex digits of the key fingerprint are
+displayed, along with the subtype::
+
+ 1a39e171 I----- 1 perm 3f010000 0 0 asymmetric modsign.0: DSA 5acc2142 []
+
+
+Accessing Asymmetric Keys
+=========================
+
+For general access to asymmetric keys from within the kernel, the following
+inclusion is required::
+
+ #include <crypto/public_key.h>
+
+This gives access to functions for dealing with asymmetric / public keys.
+Three enums are defined there for representing public-key cryptography
+algorithms::
+
+ enum pkey_algo
+
+digest algorithms used by those::
+
+ enum pkey_hash_algo
+
+and key identifier representations::
+
+ enum pkey_id_type
+
+Note that the key type representation types are required because key
+identifiers from different standards aren't necessarily compatible. For
+instance, PGP generates key identifiers by hashing the key data plus some
+PGP-specific metadata, whereas X.509 has arbitrary certificate identifiers.
+
+The operations defined upon a key are:
+
+ 1) Signature verification.
+
+Other operations are possible (such as encryption) with the same key data
+required for verification, but not currently supported, and others
+(eg. decryption and signature generation) require extra key data.
+
+
+Signature Verification
+----------------------
+
+An operation is provided to perform cryptographic signature verification, using
+an asymmetric key to provide or to provide access to the public key::
+
+ int verify_signature(const struct key *key,
+ const struct public_key_signature *sig);
+
+The caller must have already obtained the key from some source and can then use
+it to check the signature. The caller must have parsed the signature and
+transferred the relevant bits to the structure pointed to by sig::
+
+ struct public_key_signature {
+ u8 *digest;
+ u8 digest_size;
+ enum pkey_hash_algo pkey_hash_algo : 8;
+ u8 nr_mpi;
+ union {
+ MPI mpi[2];
+ ...
+ };
+ };
+
+The algorithm used must be noted in sig->pkey_hash_algo, and all the MPIs that
+make up the actual signature must be stored in sig->mpi[] and the count of MPIs
+placed in sig->nr_mpi.
+
+In addition, the data must have been digested by the caller and the resulting
+hash must be pointed to by sig->digest and the size of the hash be placed in
+sig->digest_size.
+
+The function will return 0 upon success or -EKEYREJECTED if the signature
+doesn't match.
+
+The function may also return -ENOTSUPP if an unsupported public-key algorithm
+or public-key/hash algorithm combination is specified or the key doesn't
+support the operation; -EBADMSG or -ERANGE if some of the parameters have weird
+data; or -ENOMEM if an allocation can't be performed. -EINVAL can be returned
+if the key argument is the wrong type or is incompletely set up.
+
+
+Asymmetric Key Subtypes
+=======================
+
+Asymmetric keys have a subtype that defines the set of operations that can be
+performed on that key and that determines what data is attached as the key
+payload. The payload format is entirely at the whim of the subtype.
+
+The subtype is selected by the key data parser and the parser must initialise
+the data required for it. The asymmetric key retains a reference on the
+subtype module.
+
+The subtype definition structure can be found in::
+
+ #include <keys/asymmetric-subtype.h>
+
+and looks like the following::
+
+ struct asymmetric_key_subtype {
+ struct module *owner;
+ const char *name;
+
+ void (*describe)(const struct key *key, struct seq_file *m);
+ void (*destroy)(void *payload);
+ int (*query)(const struct kernel_pkey_params *params,
+ struct kernel_pkey_query *info);
+ int (*eds_op)(struct kernel_pkey_params *params,
+ const void *in, void *out);
+ int (*verify_signature)(const struct key *key,
+ const struct public_key_signature *sig);
+ };
+
+Asymmetric keys point to this with their payload[asym_subtype] member.
+
+The owner and name fields should be set to the owning module and the name of
+the subtype. Currently, the name is only used for print statements.
+
+There are a number of operations defined by the subtype:
+
+ 1) describe().
+
+ Mandatory. This allows the subtype to display something in /proc/keys
+ against the key. For instance the name of the public key algorithm type
+ could be displayed. The key type will display the tail of the key
+ identity string after this.
+
+ 2) destroy().
+
+ Mandatory. This should free the memory associated with the key. The
+ asymmetric key will look after freeing the fingerprint and releasing the
+ reference on the subtype module.
+
+ 3) query().
+
+ Mandatory. This is a function for querying the capabilities of a key.
+
+ 4) eds_op().
+
+ Optional. This is the entry point for the encryption, decryption and
+ signature creation operations (which are distinguished by the operation ID
+ in the parameter struct). The subtype may do anything it likes to
+ implement an operation, including offloading to hardware.
+
+ 5) verify_signature().
+
+ Optional. This is the entry point for signature verification. The
+ subtype may do anything it likes to implement an operation, including
+ offloading to hardware.
+
+Instantiation Data Parsers
+==========================
+
+The asymmetric key type doesn't generally want to store or to deal with a raw
+blob of data that holds the key data. It would have to parse it and error
+check it each time it wanted to use it. Further, the contents of the blob may
+have various checks that can be performed on it (eg. self-signatures, validity
+dates) and may contain useful data about the key (identifiers, capabilities).
+
+Also, the blob may represent a pointer to some hardware containing the key
+rather than the key itself.
+
+Examples of blob formats for which parsers could be implemented include:
+
+ - OpenPGP packet stream [RFC 4880].
+ - X.509 ASN.1 stream.
+ - Pointer to TPM key.
+ - Pointer to UEFI key.
+ - PKCS#8 private key [RFC 5208].
+ - PKCS#5 encrypted private key [RFC 2898].
+
+During key instantiation each parser in the list is tried until one doesn't
+return -EBADMSG.
+
+The parser definition structure can be found in::
+
+ #include <keys/asymmetric-parser.h>
+
+and looks like the following::
+
+ struct asymmetric_key_parser {
+ struct module *owner;
+ const char *name;
+
+ int (*parse)(struct key_preparsed_payload *prep);
+ };
+
+The owner and name fields should be set to the owning module and the name of
+the parser.
+
+There is currently only a single operation defined by the parser, and it is
+mandatory:
+
+ 1) parse().
+
+ This is called to preparse the key from the key creation and update paths.
+ In particular, it is called during the key creation _before_ a key is
+ allocated, and as such, is permitted to provide the key's description in
+ the case that the caller declines to do so.
+
+ The caller passes a pointer to the following struct with all of the fields
+ cleared, except for data, datalen and quotalen [see
+ Documentation/security/keys/core.rst]::
+
+ struct key_preparsed_payload {
+ char *description;
+ void *payload[4];
+ const void *data;
+ size_t datalen;
+ size_t quotalen;
+ };
+
+ The instantiation data is in a blob pointed to by data and is datalen in
+ size. The parse() function is not permitted to change these two values at
+ all, and shouldn't change any of the other values _unless_ they are
+ recognise the blob format and will not return -EBADMSG to indicate it is
+ not theirs.
+
+ If the parser is happy with the blob, it should propose a description for
+ the key and attach it to ->description, ->payload[asym_subtype] should be
+ set to point to the subtype to be used, ->payload[asym_crypto] should be
+ set to point to the initialised data for that subtype,
+ ->payload[asym_key_ids] should point to one or more hex fingerprints and
+ quotalen should be updated to indicate how much quota this key should
+ account for.
+
+ When clearing up, the data attached to ->payload[asym_key_ids] and
+ ->description will be kfree()'d and the data attached to
+ ->payload[asm_crypto] will be passed to the subtype's ->destroy() method
+ to be disposed of. A module reference for the subtype pointed to by
+ ->payload[asym_subtype] will be put.
+
+
+ If the data format is not recognised, -EBADMSG should be returned. If it
+ is recognised, but the key cannot for some reason be set up, some other
+ negative error code should be returned. On success, 0 should be returned.
+
+ The key's fingerprint string may be partially matched upon. For a
+ public-key algorithm such as RSA and DSA this will likely be a printable
+ hex version of the key's fingerprint.
+
+Functions are provided to register and unregister parsers::
+
+ int register_asymmetric_key_parser(struct asymmetric_key_parser *parser);
+ void unregister_asymmetric_key_parser(struct asymmetric_key_parser *subtype);
+
+Parsers may not have the same name. The names are otherwise only used for
+displaying in debugging messages.
+
+
+Keyring Link Restrictions
+=========================
+
+Keyrings created from userspace using add_key can be configured to check the
+signature of the key being linked. Keys without a valid signature are not
+allowed to link.
+
+Several restriction methods are available:
+
+ 1) Restrict using the kernel builtin trusted keyring
+
+ - Option string used with KEYCTL_RESTRICT_KEYRING:
+ - "builtin_trusted"
+
+ The kernel builtin trusted keyring will be searched for the signing key.
+ If the builtin trusted keyring is not configured, all links will be
+ rejected. The ca_keys kernel parameter also affects which keys are used
+ for signature verification.
+
+ 2) Restrict using the kernel builtin and secondary trusted keyrings
+
+ - Option string used with KEYCTL_RESTRICT_KEYRING:
+ - "builtin_and_secondary_trusted"
+
+ The kernel builtin and secondary trusted keyrings will be searched for the
+ signing key. If the secondary trusted keyring is not configured, this
+ restriction will behave like the "builtin_trusted" option. The ca_keys
+ kernel parameter also affects which keys are used for signature
+ verification.
+
+ 3) Restrict using a separate key or keyring
+
+ - Option string used with KEYCTL_RESTRICT_KEYRING:
+ - "key_or_keyring:<key or keyring serial number>[:chain]"
+
+ Whenever a key link is requested, the link will only succeed if the key
+ being linked is signed by one of the designated keys. This key may be
+ specified directly by providing a serial number for one asymmetric key, or
+ a group of keys may be searched for the signing key by providing the
+ serial number for a keyring.
+
+ When the "chain" option is provided at the end of the string, the keys
+ within the destination keyring will also be searched for signing keys.
+ This allows for verification of certificate chains by adding each
+ certificate in order (starting closest to the root) to a keyring. For
+ instance, one keyring can be populated with links to a set of root
+ certificates, with a separate, restricted keyring set up for each
+ certificate chain to be validated::
+
+ # Create and populate a keyring for root certificates
+ root_id=`keyctl add keyring root-certs "" @s`
+ keyctl padd asymmetric "" $root_id < root1.cert
+ keyctl padd asymmetric "" $root_id < root2.cert
+
+ # Create and restrict a keyring for the certificate chain
+ chain_id=`keyctl add keyring chain "" @s`
+ keyctl restrict_keyring $chain_id asymmetric key_or_keyring:$root_id:chain
+
+ # Attempt to add each certificate in the chain, starting with the
+ # certificate closest to the root.
+ keyctl padd asymmetric "" $chain_id < intermediateA.cert
+ keyctl padd asymmetric "" $chain_id < intermediateB.cert
+ keyctl padd asymmetric "" $chain_id < end-entity.cert
+
+ If the final end-entity certificate is successfully added to the "chain"
+ keyring, we can be certain that it has a valid signing chain going back to
+ one of the root certificates.
+
+ A single keyring can be used to verify a chain of signatures by
+ restricting the keyring after linking the root certificate::
+
+ # Create a keyring for the certificate chain and add the root
+ chain2_id=`keyctl add keyring chain2 "" @s`
+ keyctl padd asymmetric "" $chain2_id < root1.cert
+
+ # Restrict the keyring that already has root1.cert linked. The cert
+ # will remain linked by the keyring.
+ keyctl restrict_keyring $chain2_id asymmetric key_or_keyring:0:chain
+
+ # Attempt to add each certificate in the chain, starting with the
+ # certificate closest to the root.
+ keyctl padd asymmetric "" $chain2_id < intermediateA.cert
+ keyctl padd asymmetric "" $chain2_id < intermediateB.cert
+ keyctl padd asymmetric "" $chain2_id < end-entity.cert
+
+ If the final end-entity certificate is successfully added to the "chain2"
+ keyring, we can be certain that there is a valid signing chain going back
+ to the root certificate that was added before the keyring was restricted.
+
+
+In all of these cases, if the signing key is found the signature of the key to
+be linked will be verified using the signing key. The requested key is added
+to the keyring only if the signature is successfully verified. -ENOKEY is
+returned if the parent certificate could not be found, or -EKEYREJECTED is
+returned if the signature check fails or the key is blacklisted. Other errors
+may be returned if the signature check could not be performed.
diff --git a/Documentation/crypto/asymmetric-keys.txt b/Documentation/crypto/asymmetric-keys.txt
deleted file mode 100644
index 8763866..0000000
--- a/Documentation/crypto/asymmetric-keys.txt
+++ /dev/null
@@ -1,429 +0,0 @@
- =============================================
- ASYMMETRIC / PUBLIC-KEY CRYPTOGRAPHY KEY TYPE
- =============================================
-
-Contents:
-
- - Overview.
- - Key identification.
- - Accessing asymmetric keys.
- - Signature verification.
- - Asymmetric key subtypes.
- - Instantiation data parsers.
- - Keyring link restrictions.
-
-
-========
-OVERVIEW
-========
-
-The "asymmetric" key type is designed to be a container for the keys used in
-public-key cryptography, without imposing any particular restrictions on the
-form or mechanism of the cryptography or form of the key.
-
-The asymmetric key is given a subtype that defines what sort of data is
-associated with the key and provides operations to describe and destroy it.
-However, no requirement is made that the key data actually be stored in the
-key.
-
-A completely in-kernel key retention and operation subtype can be defined, but
-it would also be possible to provide access to cryptographic hardware (such as
-a TPM) that might be used to both retain the relevant key and perform
-operations using that key. In such a case, the asymmetric key would then
-merely be an interface to the TPM driver.
-
-Also provided is the concept of a data parser. Data parsers are responsible
-for extracting information from the blobs of data passed to the instantiation
-function. The first data parser that recognises the blob gets to set the
-subtype of the key and define the operations that can be done on that key.
-
-A data parser may interpret the data blob as containing the bits representing a
-key, or it may interpret it as a reference to a key held somewhere else in the
-system (for example, a TPM).
-
-
-==================
-KEY IDENTIFICATION
-==================
-
-If a key is added with an empty name, the instantiation data parsers are given
-the opportunity to pre-parse a key and to determine the description the key
-should be given from the content of the key.
-
-This can then be used to refer to the key, either by complete match or by
-partial match. The key type may also use other criteria to refer to a key.
-
-The asymmetric key type's match function can then perform a wider range of
-comparisons than just the straightforward comparison of the description with
-the criterion string:
-
- (1) If the criterion string is of the form "id:<hexdigits>" then the match
- function will examine a key's fingerprint to see if the hex digits given
- after the "id:" match the tail. For instance:
-
- keyctl search @s asymmetric id:5acc2142
-
- will match a key with fingerprint:
-
- 1A00 2040 7601 7889 DE11 882C 3823 04AD 5ACC 2142
-
- (2) If the criterion string is of the form "<subtype>:<hexdigits>" then the
- match will match the ID as in (1), but with the added restriction that
- only keys of the specified subtype (e.g. tpm) will be matched. For
- instance:
-
- keyctl search @s asymmetric tpm:5acc2142
-
-Looking in /proc/keys, the last 8 hex digits of the key fingerprint are
-displayed, along with the subtype:
-
- 1a39e171 I----- 1 perm 3f010000 0 0 asymmetric modsign.0: DSA 5acc2142 []
-
-
-=========================
-ACCESSING ASYMMETRIC KEYS
-=========================
-
-For general access to asymmetric keys from within the kernel, the following
-inclusion is required:
-
- #include <crypto/public_key.h>
-
-This gives access to functions for dealing with asymmetric / public keys.
-Three enums are defined there for representing public-key cryptography
-algorithms:
-
- enum pkey_algo
-
-digest algorithms used by those:
-
- enum pkey_hash_algo
-
-and key identifier representations:
-
- enum pkey_id_type
-
-Note that the key type representation types are required because key
-identifiers from different standards aren't necessarily compatible. For
-instance, PGP generates key identifiers by hashing the key data plus some
-PGP-specific metadata, whereas X.509 has arbitrary certificate identifiers.
-
-The operations defined upon a key are:
-
- (1) Signature verification.
-
-Other operations are possible (such as encryption) with the same key data
-required for verification, but not currently supported, and others
-(eg. decryption and signature generation) require extra key data.
-
-
-SIGNATURE VERIFICATION
-----------------------
-
-An operation is provided to perform cryptographic signature verification, using
-an asymmetric key to provide or to provide access to the public key.
-
- int verify_signature(const struct key *key,
- const struct public_key_signature *sig);
-
-The caller must have already obtained the key from some source and can then use
-it to check the signature. The caller must have parsed the signature and
-transferred the relevant bits to the structure pointed to by sig.
-
- struct public_key_signature {
- u8 *digest;
- u8 digest_size;
- enum pkey_hash_algo pkey_hash_algo : 8;
- u8 nr_mpi;
- union {
- MPI mpi[2];
- ...
- };
- };
-
-The algorithm used must be noted in sig->pkey_hash_algo, and all the MPIs that
-make up the actual signature must be stored in sig->mpi[] and the count of MPIs
-placed in sig->nr_mpi.
-
-In addition, the data must have been digested by the caller and the resulting
-hash must be pointed to by sig->digest and the size of the hash be placed in
-sig->digest_size.
-
-The function will return 0 upon success or -EKEYREJECTED if the signature
-doesn't match.
-
-The function may also return -ENOTSUPP if an unsupported public-key algorithm
-or public-key/hash algorithm combination is specified or the key doesn't
-support the operation; -EBADMSG or -ERANGE if some of the parameters have weird
-data; or -ENOMEM if an allocation can't be performed. -EINVAL can be returned
-if the key argument is the wrong type or is incompletely set up.
-
-
-=======================
-ASYMMETRIC KEY SUBTYPES
-=======================
-
-Asymmetric keys have a subtype that defines the set of operations that can be
-performed on that key and that determines what data is attached as the key
-payload. The payload format is entirely at the whim of the subtype.
-
-The subtype is selected by the key data parser and the parser must initialise
-the data required for it. The asymmetric key retains a reference on the
-subtype module.
-
-The subtype definition structure can be found in:
-
- #include <keys/asymmetric-subtype.h>
-
-and looks like the following:
-
- struct asymmetric_key_subtype {
- struct module *owner;
- const char *name;
-
- void (*describe)(const struct key *key, struct seq_file *m);
- void (*destroy)(void *payload);
- int (*query)(const struct kernel_pkey_params *params,
- struct kernel_pkey_query *info);
- int (*eds_op)(struct kernel_pkey_params *params,
- const void *in, void *out);
- int (*verify_signature)(const struct key *key,
- const struct public_key_signature *sig);
- };
-
-Asymmetric keys point to this with their payload[asym_subtype] member.
-
-The owner and name fields should be set to the owning module and the name of
-the subtype. Currently, the name is only used for print statements.
-
-There are a number of operations defined by the subtype:
-
- (1) describe().
-
- Mandatory. This allows the subtype to display something in /proc/keys
- against the key. For instance the name of the public key algorithm type
- could be displayed. The key type will display the tail of the key
- identity string after this.
-
- (2) destroy().
-
- Mandatory. This should free the memory associated with the key. The
- asymmetric key will look after freeing the fingerprint and releasing the
- reference on the subtype module.
-
- (3) query().
-
- Mandatory. This is a function for querying the capabilities of a key.
-
- (4) eds_op().
-
- Optional. This is the entry point for the encryption, decryption and
- signature creation operations (which are distinguished by the operation ID
- in the parameter struct). The subtype may do anything it likes to
- implement an operation, including offloading to hardware.
-
- (5) verify_signature().
-
- Optional. This is the entry point for signature verification. The
- subtype may do anything it likes to implement an operation, including
- offloading to hardware.
-
-
-==========================
-INSTANTIATION DATA PARSERS
-==========================
-
-The asymmetric key type doesn't generally want to store or to deal with a raw
-blob of data that holds the key data. It would have to parse it and error
-check it each time it wanted to use it. Further, the contents of the blob may
-have various checks that can be performed on it (eg. self-signatures, validity
-dates) and may contain useful data about the key (identifiers, capabilities).
-
-Also, the blob may represent a pointer to some hardware containing the key
-rather than the key itself.
-
-Examples of blob formats for which parsers could be implemented include:
-
- - OpenPGP packet stream [RFC 4880].
- - X.509 ASN.1 stream.
- - Pointer to TPM key.
- - Pointer to UEFI key.
- - PKCS#8 private key [RFC 5208].
- - PKCS#5 encrypted private key [RFC 2898].
-
-During key instantiation each parser in the list is tried until one doesn't
-return -EBADMSG.
-
-The parser definition structure can be found in:
-
- #include <keys/asymmetric-parser.h>
-
-and looks like the following:
-
- struct asymmetric_key_parser {
- struct module *owner;
- const char *name;
-
- int (*parse)(struct key_preparsed_payload *prep);
- };
-
-The owner and name fields should be set to the owning module and the name of
-the parser.
-
-There is currently only a single operation defined by the parser, and it is
-mandatory:
-
- (1) parse().
-
- This is called to preparse the key from the key creation and update paths.
- In particular, it is called during the key creation _before_ a key is
- allocated, and as such, is permitted to provide the key's description in
- the case that the caller declines to do so.
-
- The caller passes a pointer to the following struct with all of the fields
- cleared, except for data, datalen and quotalen [see
- Documentation/security/keys/core.rst].
-
- struct key_preparsed_payload {
- char *description;
- void *payload[4];
- const void *data;
- size_t datalen;
- size_t quotalen;
- };
-
- The instantiation data is in a blob pointed to by data and is datalen in
- size. The parse() function is not permitted to change these two values at
- all, and shouldn't change any of the other values _unless_ they are
- recognise the blob format and will not return -EBADMSG to indicate it is
- not theirs.
-
- If the parser is happy with the blob, it should propose a description for
- the key and attach it to ->description, ->payload[asym_subtype] should be
- set to point to the subtype to be used, ->payload[asym_crypto] should be
- set to point to the initialised data for that subtype,
- ->payload[asym_key_ids] should point to one or more hex fingerprints and
- quotalen should be updated to indicate how much quota this key should
- account for.
-
- When clearing up, the data attached to ->payload[asym_key_ids] and
- ->description will be kfree()'d and the data attached to
- ->payload[asm_crypto] will be passed to the subtype's ->destroy() method
- to be disposed of. A module reference for the subtype pointed to by
- ->payload[asym_subtype] will be put.
-
-
- If the data format is not recognised, -EBADMSG should be returned. If it
- is recognised, but the key cannot for some reason be set up, some other
- negative error code should be returned. On success, 0 should be returned.
-
- The key's fingerprint string may be partially matched upon. For a
- public-key algorithm such as RSA and DSA this will likely be a printable
- hex version of the key's fingerprint.
-
-Functions are provided to register and unregister parsers:
-
- int register_asymmetric_key_parser(struct asymmetric_key_parser *parser);
- void unregister_asymmetric_key_parser(struct asymmetric_key_parser *subtype);
-
-Parsers may not have the same name. The names are otherwise only used for
-displaying in debugging messages.
-
-
-=========================
-KEYRING LINK RESTRICTIONS
-=========================
-
-Keyrings created from userspace using add_key can be configured to check the
-signature of the key being linked. Keys without a valid signature are not
-allowed to link.
-
-Several restriction methods are available:
-
- (1) Restrict using the kernel builtin trusted keyring
-
- - Option string used with KEYCTL_RESTRICT_KEYRING:
- - "builtin_trusted"
-
- The kernel builtin trusted keyring will be searched for the signing key.
- If the builtin trusted keyring is not configured, all links will be
- rejected. The ca_keys kernel parameter also affects which keys are used
- for signature verification.
-
- (2) Restrict using the kernel builtin and secondary trusted keyrings
-
- - Option string used with KEYCTL_RESTRICT_KEYRING:
- - "builtin_and_secondary_trusted"
-
- The kernel builtin and secondary trusted keyrings will be searched for the
- signing key. If the secondary trusted keyring is not configured, this
- restriction will behave like the "builtin_trusted" option. The ca_keys
- kernel parameter also affects which keys are used for signature
- verification.
-
- (3) Restrict using a separate key or keyring
-
- - Option string used with KEYCTL_RESTRICT_KEYRING:
- - "key_or_keyring:<key or keyring serial number>[:chain]"
-
- Whenever a key link is requested, the link will only succeed if the key
- being linked is signed by one of the designated keys. This key may be
- specified directly by providing a serial number for one asymmetric key, or
- a group of keys may be searched for the signing key by providing the
- serial number for a keyring.
-
- When the "chain" option is provided at the end of the string, the keys
- within the destination keyring will also be searched for signing keys.
- This allows for verification of certificate chains by adding each
- certificate in order (starting closest to the root) to a keyring. For
- instance, one keyring can be populated with links to a set of root
- certificates, with a separate, restricted keyring set up for each
- certificate chain to be validated:
-
- # Create and populate a keyring for root certificates
- root_id=`keyctl add keyring root-certs "" @s`
- keyctl padd asymmetric "" $root_id < root1.cert
- keyctl padd asymmetric "" $root_id < root2.cert
-
- # Create and restrict a keyring for the certificate chain
- chain_id=`keyctl add keyring chain "" @s`
- keyctl restrict_keyring $chain_id asymmetric key_or_keyring:$root_id:chain
-
- # Attempt to add each certificate in the chain, starting with the
- # certificate closest to the root.
- keyctl padd asymmetric "" $chain_id < intermediateA.cert
- keyctl padd asymmetric "" $chain_id < intermediateB.cert
- keyctl padd asymmetric "" $chain_id < end-entity.cert
-
- If the final end-entity certificate is successfully added to the "chain"
- keyring, we can be certain that it has a valid signing chain going back to
- one of the root certificates.
-
- A single keyring can be used to verify a chain of signatures by
- restricting the keyring after linking the root certificate:
-
- # Create a keyring for the certificate chain and add the root
- chain2_id=`keyctl add keyring chain2 "" @s`
- keyctl padd asymmetric "" $chain2_id < root1.cert
-
- # Restrict the keyring that already has root1.cert linked. The cert
- # will remain linked by the keyring.
- keyctl restrict_keyring $chain2_id asymmetric key_or_keyring:0:chain
-
- # Attempt to add each certificate in the chain, starting with the
- # certificate closest to the root.
- keyctl padd asymmetric "" $chain2_id < intermediateA.cert
- keyctl padd asymmetric "" $chain2_id < intermediateB.cert
- keyctl padd asymmetric "" $chain2_id < end-entity.cert
-
- If the final end-entity certificate is successfully added to the "chain2"
- keyring, we can be certain that there is a valid signing chain going back
- to the root certificate that was added before the keyring was restricted.
-
-
-In all of these cases, if the signing key is found the signature of the key to
-be linked will be verified using the signing key. The requested key is added
-to the keyring only if the signature is successfully verified. -ENOKEY is
-returned if the parent certificate could not be found, or -EKEYREJECTED is
-returned if the signature check fails or the key is blacklisted. Other errors
-may be returned if the signature check could not be performed.
diff --git a/Documentation/crypto/async-tx-api.rst b/Documentation/crypto/async-tx-api.rst
new file mode 100644
index 0000000..bfc7739
--- /dev/null
+++ b/Documentation/crypto/async-tx-api.rst
@@ -0,0 +1,270 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+=====================================
+Asynchronous Transfers/Transforms API
+=====================================
+
+.. Contents
+
+ 1. INTRODUCTION
+
+ 2 GENEALOGY
+
+ 3 USAGE
+ 3.1 General format of the API
+ 3.2 Supported operations
+ 3.3 Descriptor management
+ 3.4 When does the operation execute?
+ 3.5 When does the operation complete?
+ 3.6 Constraints
+ 3.7 Example
+
+ 4 DMAENGINE DRIVER DEVELOPER NOTES
+ 4.1 Conformance points
+ 4.2 "My application needs exclusive control of hardware channels"
+
+ 5 SOURCE
+
+1. Introduction
+===============
+
+The async_tx API provides methods for describing a chain of asynchronous
+bulk memory transfers/transforms with support for inter-transactional
+dependencies. It is implemented as a dmaengine client that smooths over
+the details of different hardware offload engine implementations. Code
+that is written to the API can optimize for asynchronous operation and
+the API will fit the chain of operations to the available offload
+resources.
+
+2.Genealogy
+===========
+
+The API was initially designed to offload the memory copy and
+xor-parity-calculations of the md-raid5 driver using the offload engines
+present in the Intel(R) Xscale series of I/O processors. It also built
+on the 'dmaengine' layer developed for offloading memory copies in the
+network stack using Intel(R) I/OAT engines. The following design
+features surfaced as a result:
+
+1. implicit synchronous path: users of the API do not need to know if
+ the platform they are running on has offload capabilities. The
+ operation will be offloaded when an engine is available and carried out
+ in software otherwise.
+2. cross channel dependency chains: the API allows a chain of dependent
+ operations to be submitted, like xor->copy->xor in the raid5 case. The
+ API automatically handles cases where the transition from one operation
+ to another implies a hardware channel switch.
+3. dmaengine extensions to support multiple clients and operation types
+ beyond 'memcpy'
+
+3. Usage
+========
+
+3.1 General format of the API
+-----------------------------
+
+::
+
+ struct dma_async_tx_descriptor *
+ async_<operation>(<op specific parameters>, struct async_submit ctl *submit)
+
+3.2 Supported operations
+------------------------
+
+======== ====================================================================
+memcpy memory copy between a source and a destination buffer
+memset fill a destination buffer with a byte value
+xor xor a series of source buffers and write the result to a
+ destination buffer
+xor_val xor a series of source buffers and set a flag if the
+ result is zero. The implementation attempts to prevent
+ writes to memory
+pq generate the p+q (raid6 syndrome) from a series of source buffers
+pq_val validate that a p and or q buffer are in sync with a given series of
+ sources
+datap (raid6_datap_recov) recover a raid6 data block and the p block
+ from the given sources
+2data (raid6_2data_recov) recover 2 raid6 data blocks from the given
+ sources
+======== ====================================================================
+
+3.3 Descriptor management
+-------------------------
+
+The return value is non-NULL and points to a 'descriptor' when the operation
+has been queued to execute asynchronously. Descriptors are recycled
+resources, under control of the offload engine driver, to be reused as
+operations complete. When an application needs to submit a chain of
+operations it must guarantee that the descriptor is not automatically recycled
+before the dependency is submitted. This requires that all descriptors be
+acknowledged by the application before the offload engine driver is allowed to
+recycle (or free) the descriptor. A descriptor can be acked by one of the
+following methods:
+
+1. setting the ASYNC_TX_ACK flag if no child operations are to be submitted
+2. submitting an unacknowledged descriptor as a dependency to another
+ async_tx call will implicitly set the acknowledged state.
+3. calling async_tx_ack() on the descriptor.
+
+3.4 When does the operation execute?
+------------------------------------
+
+Operations do not immediately issue after return from the
+async_<operation> call. Offload engine drivers batch operations to
+improve performance by reducing the number of mmio cycles needed to
+manage the channel. Once a driver-specific threshold is met the driver
+automatically issues pending operations. An application can force this
+event by calling async_tx_issue_pending_all(). This operates on all
+channels since the application has no knowledge of channel to operation
+mapping.
+
+3.5 When does the operation complete?
+-------------------------------------
+
+There are two methods for an application to learn about the completion
+of an operation.
+
+1. Call dma_wait_for_async_tx(). This call causes the CPU to spin while
+ it polls for the completion of the operation. It handles dependency
+ chains and issuing pending operations.
+2. Specify a completion callback. The callback routine runs in tasklet
+ context if the offload engine driver supports interrupts, or it is
+ called in application context if the operation is carried out
+ synchronously in software. The callback can be set in the call to
+ async_<operation>, or when the application needs to submit a chain of
+ unknown length it can use the async_trigger_callback() routine to set a
+ completion interrupt/callback at the end of the chain.
+
+3.6 Constraints
+---------------
+
+1. Calls to async_<operation> are not permitted in IRQ context. Other
+ contexts are permitted provided constraint #2 is not violated.
+2. Completion callback routines cannot submit new operations. This
+ results in recursion in the synchronous case and spin_locks being
+ acquired twice in the asynchronous case.
+
+3.7 Example
+-----------
+
+Perform a xor->copy->xor operation where each operation depends on the
+result from the previous operation::
+
+ void callback(void *param)
+ {
+ struct completion *cmp = param;
+
+ complete(cmp);
+ }
+
+ void run_xor_copy_xor(struct page **xor_srcs,
+ int xor_src_cnt,
+ struct page *xor_dest,
+ size_t xor_len,
+ struct page *copy_src,
+ struct page *copy_dest,
+ size_t copy_len)
+ {
+ struct dma_async_tx_descriptor *tx;
+ addr_conv_t addr_conv[xor_src_cnt];
+ struct async_submit_ctl submit;
+ addr_conv_t addr_conv[NDISKS];
+ struct completion cmp;
+
+ init_async_submit(&submit, ASYNC_TX_XOR_DROP_DST, NULL, NULL, NULL,
+ addr_conv);
+ tx = async_xor(xor_dest, xor_srcs, 0, xor_src_cnt, xor_len, &submit)
+
+ submit->depend_tx = tx;
+ tx = async_memcpy(copy_dest, copy_src, 0, 0, copy_len, &submit);
+
+ init_completion(&cmp);
+ init_async_submit(&submit, ASYNC_TX_XOR_DROP_DST | ASYNC_TX_ACK, tx,
+ callback, &cmp, addr_conv);
+ tx = async_xor(xor_dest, xor_srcs, 0, xor_src_cnt, xor_len, &submit);
+
+ async_tx_issue_pending_all();
+
+ wait_for_completion(&cmp);
+ }
+
+See include/linux/async_tx.h for more information on the flags. See the
+ops_run_* and ops_complete_* routines in drivers/md/raid5.c for more
+implementation examples.
+
+4. Driver Development Notes
+===========================
+
+4.1 Conformance points
+----------------------
+
+There are a few conformance points required in dmaengine drivers to
+accommodate assumptions made by applications using the async_tx API:
+
+1. Completion callbacks are expected to happen in tasklet context
+2. dma_async_tx_descriptor fields are never manipulated in IRQ context
+3. Use async_tx_run_dependencies() in the descriptor clean up path to
+ handle submission of dependent operations
+
+4.2 "My application needs exclusive control of hardware channels"
+-----------------------------------------------------------------
+
+Primarily this requirement arises from cases where a DMA engine driver
+is being used to support device-to-memory operations. A channel that is
+performing these operations cannot, for many platform specific reasons,
+be shared. For these cases the dma_request_channel() interface is
+provided.
+
+The interface is::
+
+ struct dma_chan *dma_request_channel(dma_cap_mask_t mask,
+ dma_filter_fn filter_fn,
+ void *filter_param);
+
+Where dma_filter_fn is defined as::
+
+ typedef bool (*dma_filter_fn)(struct dma_chan *chan, void *filter_param);
+
+When the optional 'filter_fn' parameter is set to NULL
+dma_request_channel simply returns the first channel that satisfies the
+capability mask. Otherwise, when the mask parameter is insufficient for
+specifying the necessary channel, the filter_fn routine can be used to
+disposition the available channels in the system. The filter_fn routine
+is called once for each free channel in the system. Upon seeing a
+suitable channel filter_fn returns DMA_ACK which flags that channel to
+be the return value from dma_request_channel. A channel allocated via
+this interface is exclusive to the caller, until dma_release_channel()
+is called.
+
+The DMA_PRIVATE capability flag is used to tag dma devices that should
+not be used by the general-purpose allocator. It can be set at
+initialization time if it is known that a channel will always be
+private. Alternatively, it is set when dma_request_channel() finds an
+unused "public" channel.
+
+A couple caveats to note when implementing a driver and consumer:
+
+1. Once a channel has been privately allocated it will no longer be
+ considered by the general-purpose allocator even after a call to
+ dma_release_channel().
+2. Since capabilities are specified at the device level a dma_device
+ with multiple channels will either have all channels public, or all
+ channels private.
+
+5. Source
+---------
+
+include/linux/dmaengine.h:
+ core header file for DMA drivers and api users
+drivers/dma/dmaengine.c:
+ offload engine channel management routines
+drivers/dma/:
+ location for offload engine drivers
+include/linux/async_tx.h:
+ core header file for the async_tx api
+crypto/async_tx/async_tx.c:
+ async_tx interface to dmaengine and common code
+crypto/async_tx/async_memcpy.c:
+ copy offload
+crypto/async_tx/async_xor.c:
+ xor and xor zero sum offload
diff --git a/Documentation/crypto/async-tx-api.txt b/Documentation/crypto/async-tx-api.txt
deleted file mode 100644
index 7bf1be2..0000000
--- a/Documentation/crypto/async-tx-api.txt
+++ /dev/null
@@ -1,225 +0,0 @@
- Asynchronous Transfers/Transforms API
-
-1 INTRODUCTION
-
-2 GENEALOGY
-
-3 USAGE
-3.1 General format of the API
-3.2 Supported operations
-3.3 Descriptor management
-3.4 When does the operation execute?
-3.5 When does the operation complete?
-3.6 Constraints
-3.7 Example
-
-4 DMAENGINE DRIVER DEVELOPER NOTES
-4.1 Conformance points
-4.2 "My application needs exclusive control of hardware channels"
-
-5 SOURCE
-
----
-
-1 INTRODUCTION
-
-The async_tx API provides methods for describing a chain of asynchronous
-bulk memory transfers/transforms with support for inter-transactional
-dependencies. It is implemented as a dmaengine client that smooths over
-the details of different hardware offload engine implementations. Code
-that is written to the API can optimize for asynchronous operation and
-the API will fit the chain of operations to the available offload
-resources.
-
-2 GENEALOGY
-
-The API was initially designed to offload the memory copy and
-xor-parity-calculations of the md-raid5 driver using the offload engines
-present in the Intel(R) Xscale series of I/O processors. It also built
-on the 'dmaengine' layer developed for offloading memory copies in the
-network stack using Intel(R) I/OAT engines. The following design
-features surfaced as a result:
-1/ implicit synchronous path: users of the API do not need to know if
- the platform they are running on has offload capabilities. The
- operation will be offloaded when an engine is available and carried out
- in software otherwise.
-2/ cross channel dependency chains: the API allows a chain of dependent
- operations to be submitted, like xor->copy->xor in the raid5 case. The
- API automatically handles cases where the transition from one operation
- to another implies a hardware channel switch.
-3/ dmaengine extensions to support multiple clients and operation types
- beyond 'memcpy'
-
-3 USAGE
-
-3.1 General format of the API:
-struct dma_async_tx_descriptor *
-async_<operation>(<op specific parameters>, struct async_submit ctl *submit)
-
-3.2 Supported operations:
-memcpy - memory copy between a source and a destination buffer
-memset - fill a destination buffer with a byte value
-xor - xor a series of source buffers and write the result to a
- destination buffer
-xor_val - xor a series of source buffers and set a flag if the
- result is zero. The implementation attempts to prevent
- writes to memory
-pq - generate the p+q (raid6 syndrome) from a series of source buffers
-pq_val - validate that a p and or q buffer are in sync with a given series of
- sources
-datap - (raid6_datap_recov) recover a raid6 data block and the p block
- from the given sources
-2data - (raid6_2data_recov) recover 2 raid6 data blocks from the given
- sources
-
-3.3 Descriptor management:
-The return value is non-NULL and points to a 'descriptor' when the operation
-has been queued to execute asynchronously. Descriptors are recycled
-resources, under control of the offload engine driver, to be reused as
-operations complete. When an application needs to submit a chain of
-operations it must guarantee that the descriptor is not automatically recycled
-before the dependency is submitted. This requires that all descriptors be
-acknowledged by the application before the offload engine driver is allowed to
-recycle (or free) the descriptor. A descriptor can be acked by one of the
-following methods:
-1/ setting the ASYNC_TX_ACK flag if no child operations are to be submitted
-2/ submitting an unacknowledged descriptor as a dependency to another
- async_tx call will implicitly set the acknowledged state.
-3/ calling async_tx_ack() on the descriptor.
-
-3.4 When does the operation execute?
-Operations do not immediately issue after return from the
-async_<operation> call. Offload engine drivers batch operations to
-improve performance by reducing the number of mmio cycles needed to
-manage the channel. Once a driver-specific threshold is met the driver
-automatically issues pending operations. An application can force this
-event by calling async_tx_issue_pending_all(). This operates on all
-channels since the application has no knowledge of channel to operation
-mapping.
-
-3.5 When does the operation complete?
-There are two methods for an application to learn about the completion
-of an operation.
-1/ Call dma_wait_for_async_tx(). This call causes the CPU to spin while
- it polls for the completion of the operation. It handles dependency
- chains and issuing pending operations.
-2/ Specify a completion callback. The callback routine runs in tasklet
- context if the offload engine driver supports interrupts, or it is
- called in application context if the operation is carried out
- synchronously in software. The callback can be set in the call to
- async_<operation>, or when the application needs to submit a chain of
- unknown length it can use the async_trigger_callback() routine to set a
- completion interrupt/callback at the end of the chain.
-
-3.6 Constraints:
-1/ Calls to async_<operation> are not permitted in IRQ context. Other
- contexts are permitted provided constraint #2 is not violated.
-2/ Completion callback routines cannot submit new operations. This
- results in recursion in the synchronous case and spin_locks being
- acquired twice in the asynchronous case.
-
-3.7 Example:
-Perform a xor->copy->xor operation where each operation depends on the
-result from the previous operation:
-
-void callback(void *param)
-{
- struct completion *cmp = param;
-
- complete(cmp);
-}
-
-void run_xor_copy_xor(struct page **xor_srcs,
- int xor_src_cnt,
- struct page *xor_dest,
- size_t xor_len,
- struct page *copy_src,
- struct page *copy_dest,
- size_t copy_len)
-{
- struct dma_async_tx_descriptor *tx;
- addr_conv_t addr_conv[xor_src_cnt];
- struct async_submit_ctl submit;
- addr_conv_t addr_conv[NDISKS];
- struct completion cmp;
-
- init_async_submit(&submit, ASYNC_TX_XOR_DROP_DST, NULL, NULL, NULL,
- addr_conv);
- tx = async_xor(xor_dest, xor_srcs, 0, xor_src_cnt, xor_len, &submit)
-
- submit->depend_tx = tx;
- tx = async_memcpy(copy_dest, copy_src, 0, 0, copy_len, &submit);
-
- init_completion(&cmp);
- init_async_submit(&submit, ASYNC_TX_XOR_DROP_DST | ASYNC_TX_ACK, tx,
- callback, &cmp, addr_conv);
- tx = async_xor(xor_dest, xor_srcs, 0, xor_src_cnt, xor_len, &submit);
-
- async_tx_issue_pending_all();
-
- wait_for_completion(&cmp);
-}
-
-See include/linux/async_tx.h for more information on the flags. See the
-ops_run_* and ops_complete_* routines in drivers/md/raid5.c for more
-implementation examples.
-
-4 DRIVER DEVELOPMENT NOTES
-
-4.1 Conformance points:
-There are a few conformance points required in dmaengine drivers to
-accommodate assumptions made by applications using the async_tx API:
-1/ Completion callbacks are expected to happen in tasklet context
-2/ dma_async_tx_descriptor fields are never manipulated in IRQ context
-3/ Use async_tx_run_dependencies() in the descriptor clean up path to
- handle submission of dependent operations
-
-4.2 "My application needs exclusive control of hardware channels"
-Primarily this requirement arises from cases where a DMA engine driver
-is being used to support device-to-memory operations. A channel that is
-performing these operations cannot, for many platform specific reasons,
-be shared. For these cases the dma_request_channel() interface is
-provided.
-
-The interface is:
-struct dma_chan *dma_request_channel(dma_cap_mask_t mask,
- dma_filter_fn filter_fn,
- void *filter_param);
-
-Where dma_filter_fn is defined as:
-typedef bool (*dma_filter_fn)(struct dma_chan *chan, void *filter_param);
-
-When the optional 'filter_fn' parameter is set to NULL
-dma_request_channel simply returns the first channel that satisfies the
-capability mask. Otherwise, when the mask parameter is insufficient for
-specifying the necessary channel, the filter_fn routine can be used to
-disposition the available channels in the system. The filter_fn routine
-is called once for each free channel in the system. Upon seeing a
-suitable channel filter_fn returns DMA_ACK which flags that channel to
-be the return value from dma_request_channel. A channel allocated via
-this interface is exclusive to the caller, until dma_release_channel()
-is called.
-
-The DMA_PRIVATE capability flag is used to tag dma devices that should
-not be used by the general-purpose allocator. It can be set at
-initialization time if it is known that a channel will always be
-private. Alternatively, it is set when dma_request_channel() finds an
-unused "public" channel.
-
-A couple caveats to note when implementing a driver and consumer:
-1/ Once a channel has been privately allocated it will no longer be
- considered by the general-purpose allocator even after a call to
- dma_release_channel().
-2/ Since capabilities are specified at the device level a dma_device
- with multiple channels will either have all channels public, or all
- channels private.
-
-5 SOURCE
-
-include/linux/dmaengine.h: core header file for DMA drivers and api users
-drivers/dma/dmaengine.c: offload engine channel management routines
-drivers/dma/: location for offload engine drivers
-include/linux/async_tx.h: core header file for the async_tx api
-crypto/async_tx/async_tx.c: async_tx interface to dmaengine and common code
-crypto/async_tx/async_memcpy.c: copy offload
-crypto/async_tx/async_xor.c: xor and xor zero sum offload
diff --git a/Documentation/crypto/descore-readme.rst b/Documentation/crypto/descore-readme.rst
new file mode 100644
index 0000000..45bd9c8
--- /dev/null
+++ b/Documentation/crypto/descore-readme.rst
@@ -0,0 +1,414 @@
+.. SPDX-License-Identifier: GPL-2.0
+.. include:: <isonum.txt>
+
+===========================================
+Fast & Portable DES encryption & decryption
+===========================================
+
+.. note::
+
+ Below is the original README file from the descore.shar package,
+ converted to ReST format.
+
+------------------------------------------------------------------------------
+
+des - fast & portable DES encryption & decryption.
+
+Copyright |copy| 1992 Dana L. How
+
+This program is free software; you can redistribute it and/or modify
+it under the terms of the GNU Library 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 Library General Public License for more details.
+
+You should have received a copy of the GNU Library General Public License
+along with this program; if not, write to the Free Software
+Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
+
+Author's address: how@isl.stanford.edu
+
+.. README,v 1.15 1992/05/20 00:25:32 how E
+
+==>> To compile after untarring/unsharring, just ``make`` <<==
+
+This package was designed with the following goals:
+
+1. Highest possible encryption/decryption PERFORMANCE.
+2. PORTABILITY to any byte-addressable host with a 32bit unsigned C type
+3. Plug-compatible replacement for KERBEROS's low-level routines.
+
+This second release includes a number of performance enhancements for
+register-starved machines. My discussions with Richard Outerbridge,
+71755.204@compuserve.com, sparked a number of these enhancements.
+
+To more rapidly understand the code in this package, inspect desSmallFips.i
+(created by typing ``make``) BEFORE you tackle desCode.h. The latter is set
+up in a parameterized fashion so it can easily be modified by speed-daemon
+hackers in pursuit of that last microsecond. You will find it more
+illuminating to inspect one specific implementation,
+and then move on to the common abstract skeleton with this one in mind.
+
+
+performance comparison to other available des code which i could
+compile on a SPARCStation 1 (cc -O4, gcc -O2):
+
+this code (byte-order independent):
+
+ - 30us per encryption (options: 64k tables, no IP/FP)
+ - 33us per encryption (options: 64k tables, FIPS standard bit ordering)
+ - 45us per encryption (options: 2k tables, no IP/FP)
+ - 48us per encryption (options: 2k tables, FIPS standard bit ordering)
+ - 275us to set a new key (uses 1k of key tables)
+
+ this has the quickest encryption/decryption routines i've seen.
+ since i was interested in fast des filters rather than crypt(3)
+ and password cracking, i haven't really bothered yet to speed up
+ the key setting routine. also, i have no interest in re-implementing
+ all the other junk in the mit kerberos des library, so i've just
+ provided my routines with little stub interfaces so they can be
+ used as drop-in replacements with mit's code or any of the mit-
+ compatible packages below. (note that the first two timings above
+ are highly variable because of cache effects).
+
+kerberos des replacement from australia (version 1.95):
+
+ - 53us per encryption (uses 2k of tables)
+ - 96us to set a new key (uses 2.25k of key tables)
+
+ so despite the author's inclusion of some of the performance
+ improvements i had suggested to him, this package's
+ encryption/decryption is still slower on the sparc and 68000.
+ more specifically, 19-40% slower on the 68020 and 11-35% slower
+ on the sparc, depending on the compiler;
+ in full gory detail (ALT_ECB is a libdes variant):
+
+ =============== ============== =============== =================
+ compiler machine desCore libdes ALT_ECB slower by
+ =============== ============== =============== =================
+ gcc 2.1 -O2 Sun 3/110 304 uS 369.5uS 461.8uS 22%
+ cc -O1 Sun 3/110 336 uS 436.6uS 399.3uS 19%
+ cc -O2 Sun 3/110 360 uS 532.4uS 505.1uS 40%
+ cc -O4 Sun 3/110 365 uS 532.3uS 505.3uS 38%
+ gcc 2.1 -O2 Sun 4/50 48 uS 53.4uS 57.5uS 11%
+ cc -O2 Sun 4/50 48 uS 64.6uS 64.7uS 35%
+ cc -O4 Sun 4/50 48 uS 64.7uS 64.9uS 35%
+ =============== ============== =============== =================
+
+ (my time measurements are not as accurate as his).
+
+ the comments in my first release of desCore on version 1.92:
+
+ - 68us per encryption (uses 2k of tables)
+ - 96us to set a new key (uses 2.25k of key tables)
+
+ this is a very nice package which implements the most important
+ of the optimizations which i did in my encryption routines.
+ it's a bit weak on common low-level optimizations which is why
+ it's 39%-106% slower. because he was interested in fast crypt(3) and
+ password-cracking applications, he also used the same ideas to
+ speed up the key-setting routines with impressive results.
+ (at some point i may do the same in my package). he also implements
+ the rest of the mit des library.
+
+ (code from eay@psych.psy.uq.oz.au via comp.sources.misc)
+
+fast crypt(3) package from denmark:
+
+ the des routine here is buried inside a loop to do the
+ crypt function and i didn't feel like ripping it out and measuring
+ performance. his code takes 26 sparc instructions to compute one
+ des iteration; above, Quick (64k) takes 21 and Small (2k) takes 37.
+ he claims to use 280k of tables but the iteration calculation seems
+ to use only 128k. his tables and code are machine independent.
+
+ (code from glad@daimi.aau.dk via alt.sources or comp.sources.misc)
+
+swedish reimplementation of Kerberos des library
+
+ - 108us per encryption (uses 34k worth of tables)
+ - 134us to set a new key (uses 32k of key tables to get this speed!)
+
+ the tables used seem to be machine-independent;
+ he seems to have included a lot of special case code
+ so that, e.g., ``long`` loads can be used instead of 4 ``char`` loads
+ when the machine's architecture allows it.
+
+ (code obtained from chalmers.se:pub/des)
+
+crack 3.3c package from england:
+
+ as in crypt above, the des routine is buried in a loop. it's
+ also very modified for crypt. his iteration code uses 16k
+ of tables and appears to be slow.
+
+ (code obtained from aem@aber.ac.uk via alt.sources or comp.sources.misc)
+
+``highly optimized`` and tweaked Kerberos/Athena code (byte-order dependent):
+
+ - 165us per encryption (uses 6k worth of tables)
+ - 478us to set a new key (uses <1k of key tables)
+
+ so despite the comments in this code, it was possible to get
+ faster code AND smaller tables, as well as making the tables
+ machine-independent.
+ (code obtained from prep.ai.mit.edu)
+
+UC Berkeley code (depends on machine-endedness):
+ - 226us per encryption
+ - 10848us to set a new key
+
+ table sizes are unclear, but they don't look very small
+ (code obtained from wuarchive.wustl.edu)
+
+
+motivation and history
+======================
+
+a while ago i wanted some des routines and the routines documented on sun's
+man pages either didn't exist or dumped core. i had heard of kerberos,
+and knew that it used des, so i figured i'd use its routines. but once
+i got it and looked at the code, it really set off a lot of pet peeves -
+it was too convoluted, the code had been written without taking
+advantage of the regular structure of operations such as IP, E, and FP
+(i.e. the author didn't sit down and think before coding),
+it was excessively slow, the author had attempted to clarify the code
+by adding MORE statements to make the data movement more ``consistent``
+instead of simplifying his implementation and cutting down on all data
+movement (in particular, his use of L1, R1, L2, R2), and it was full of
+idiotic ``tweaks`` for particular machines which failed to deliver significant
+speedups but which did obfuscate everything. so i took the test data
+from his verification program and rewrote everything else.
+
+a while later i ran across the great crypt(3) package mentioned above.
+the fact that this guy was computing 2 sboxes per table lookup rather
+than one (and using a MUCH larger table in the process) emboldened me to
+do the same - it was a trivial change from which i had been scared away
+by the larger table size. in his case he didn't realize you don't need to keep
+the working data in TWO forms, one for easy use of half the sboxes in
+indexing, the other for easy use of the other half; instead you can keep
+it in the form for the first half and use a simple rotate to get the other
+half. this means i have (almost) half the data manipulation and half
+the table size. in fairness though he might be encoding something particular
+to crypt(3) in his tables - i didn't check.
+
+i'm glad that i implemented it the way i did, because this C version is
+portable (the ifdef's are performance enhancements) and it is faster
+than versions hand-written in assembly for the sparc!
+
+
+porting notes
+=============
+
+one thing i did not want to do was write an enormous mess
+which depended on endedness and other machine quirks,
+and which necessarily produced different code and different lookup tables
+for different machines. see the kerberos code for an example
+of what i didn't want to do; all their endedness-specific ``optimizations``
+obfuscate the code and in the end were slower than a simpler machine
+independent approach. however, there are always some portability
+considerations of some kind, and i have included some options
+for varying numbers of register variables.
+perhaps some will still regard the result as a mess!
+
+1) i assume everything is byte addressable, although i don't actually
+ depend on the byte order, and that bytes are 8 bits.
+ i assume word pointers can be freely cast to and from char pointers.
+ note that 99% of C programs make these assumptions.
+ i always use unsigned char's if the high bit could be set.
+2) the typedef ``word`` means a 32 bit unsigned integral type.
+ if ``unsigned long`` is not 32 bits, change the typedef in desCore.h.
+ i assume sizeof(word) == 4 EVERYWHERE.
+
+the (worst-case) cost of my NOT doing endedness-specific optimizations
+in the data loading and storing code surrounding the key iterations
+is less than 12%. also, there is the added benefit that
+the input and output work areas do not need to be word-aligned.
+
+
+OPTIONAL performance optimizations
+==================================
+
+1) you should define one of ``i386,`` ``vax,`` ``mc68000,`` or ``sparc,``
+ whichever one is closest to the capabilities of your machine.
+ see the start of desCode.h to see exactly what this selection implies.
+ note that if you select the wrong one, the des code will still work;
+ these are just performance tweaks.
+2) for those with functional ``asm`` keywords: you should change the
+ ROR and ROL macros to use machine rotate instructions if you have them.
+ this will save 2 instructions and a temporary per use,
+ or about 32 to 40 instructions per en/decryption.
+
+ note that gcc is smart enough to translate the ROL/R macros into
+ machine rotates!
+
+these optimizations are all rather persnickety, yet with them you should
+be able to get performance equal to assembly-coding, except that:
+
+1) with the lack of a bit rotate operator in C, rotates have to be synthesized
+ from shifts. so access to ``asm`` will speed things up if your machine
+ has rotates, as explained above in (3) (not necessary if you use gcc).
+2) if your machine has less than 12 32-bit registers i doubt your compiler will
+ generate good code.
+
+ ``i386`` tries to configure the code for a 386 by only declaring 3 registers
+ (it appears that gcc can use ebx, esi and edi to hold register variables).
+ however, if you like assembly coding, the 386 does have 7 32-bit registers,
+ and if you use ALL of them, use ``scaled by 8`` address modes with displacement
+ and other tricks, you can get reasonable routines for DesQuickCore... with
+ about 250 instructions apiece. For DesSmall... it will help to rearrange
+ des_keymap, i.e., now the sbox # is the high part of the index and
+ the 6 bits of data is the low part; it helps to exchange these.
+
+ since i have no way to conveniently test it i have not provided my
+ shoehorned 386 version. note that with this release of desCore, gcc is able
+ to put everything in registers(!), and generate about 370 instructions apiece
+ for the DesQuickCore... routines!
+
+coding notes
+============
+
+the en/decryption routines each use 6 necessary register variables,
+with 4 being actively used at once during the inner iterations.
+if you don't have 4 register variables get a new machine.
+up to 8 more registers are used to hold constants in some configurations.
+
+i assume that the use of a constant is more expensive than using a register:
+
+a) additionally, i have tried to put the larger constants in registers.
+ registering priority was by the following:
+
+ - anything more than 12 bits (bad for RISC and CISC)
+ - greater than 127 in value (can't use movq or byte immediate on CISC)
+ - 9-127 (may not be able to use CISC shift immediate or add/sub quick),
+ - 1-8 were never registered, being the cheapest constants.
+
+b) the compiler may be too stupid to realize table and table+256 should
+ be assigned to different constant registers and instead repetitively
+ do the arithmetic, so i assign these to explicit ``m`` register variables
+ when possible and helpful.
+
+i assume that indexing is cheaper or equivalent to auto increment/decrement,
+where the index is 7 bits unsigned or smaller.
+this assumption is reversed for 68k and vax.
+
+i assume that addresses can be cheaply formed from two registers,
+or from a register and a small constant.
+for the 68000, the ``two registers and small offset`` form is used sparingly.
+all index scaling is done explicitly - no hidden shifts by log2(sizeof).
+
+the code is written so that even a dumb compiler
+should never need more than one hidden temporary,
+increasing the chance that everything will fit in the registers.
+KEEP THIS MORE SUBTLE POINT IN MIND IF YOU REWRITE ANYTHING.
+
+(actually, there are some code fragments now which do require two temps,
+but fixing it would either break the structure of the macros or
+require declaring another temporary).
+
+
+special efficient data format
+==============================
+
+bits are manipulated in this arrangement most of the time (S7 S5 S3 S1)::
+
+ 003130292827xxxx242322212019xxxx161514131211xxxx080706050403xxxx
+
+(the x bits are still there, i'm just emphasizing where the S boxes are).
+bits are rotated left 4 when computing S6 S4 S2 S0::
+
+ 282726252423xxxx201918171615xxxx121110090807xxxx040302010031xxxx
+
+the rightmost two bits are usually cleared so the lower byte can be used
+as an index into an sbox mapping table. the next two x'd bits are set
+to various values to access different parts of the tables.
+
+
+how to use the routines
+
+datatypes:
+ pointer to 8 byte area of type DesData
+ used to hold keys and input/output blocks to des.
+
+ pointer to 128 byte area of type DesKeys
+ used to hold full 768-bit key.
+ must be long-aligned.
+
+DesQuickInit()
+ call this before using any other routine with ``Quick`` in its name.
+ it generates the special 64k table these routines need.
+DesQuickDone()
+ frees this table
+
+DesMethod(m, k)
+ m points to a 128byte block, k points to an 8 byte des key
+ which must have odd parity (or -1 is returned) and which must
+ not be a (semi-)weak key (or -2 is returned).
+ normally DesMethod() returns 0.
+
+ m is filled in from k so that when one of the routines below
+ is called with m, the routine will act like standard des
+ en/decryption with the key k. if you use DesMethod,
+ you supply a standard 56bit key; however, if you fill in
+ m yourself, you will get a 768bit key - but then it won't
+ be standard. it's 768bits not 1024 because the least significant
+ two bits of each byte are not used. note that these two bits
+ will be set to magic constants which speed up the encryption/decryption
+ on some machines. and yes, each byte controls
+ a specific sbox during a specific iteration.
+
+ you really shouldn't use the 768bit format directly; i should
+ provide a routine that converts 128 6-bit bytes (specified in
+ S-box mapping order or something) into the right format for you.
+ this would entail some byte concatenation and rotation.
+
+Des{Small|Quick}{Fips|Core}{Encrypt|Decrypt}(d, m, s)
+ performs des on the 8 bytes at s into the 8 bytes at
+ ``d. (d,s: char *)``.
+
+ uses m as a 768bit key as explained above.
+
+ the Encrypt|Decrypt choice is obvious.
+
+ Fips|Core determines whether a completely standard FIPS initial
+ and final permutation is done; if not, then the data is loaded
+ and stored in a nonstandard bit order (FIPS w/o IP/FP).
+
+ Fips slows down Quick by 10%, Small by 9%.
+
+ Small|Quick determines whether you use the normal routine
+ or the crazy quick one which gobbles up 64k more of memory.
+ Small is 50% slower then Quick, but Quick needs 32 times as much
+ memory. Quick is included for programs that do nothing but DES,
+ e.g., encryption filters, etc.
+
+
+Getting it to compile on your machine
+=====================================
+
+there are no machine-dependencies in the code (see porting),
+except perhaps the ``now()`` macro in desTest.c.
+ALL generated tables are machine independent.
+you should edit the Makefile with the appropriate optimization flags
+for your compiler (MAX optimization).
+
+
+Speeding up kerberos (and/or its des library)
+=============================================
+
+note that i have included a kerberos-compatible interface in desUtil.c
+through the functions des_key_sched() and des_ecb_encrypt().
+to use these with kerberos or kerberos-compatible code put desCore.a
+ahead of the kerberos-compatible library on your linker's command line.
+you should not need to #include desCore.h; just include the header
+file provided with the kerberos library.
+
+Other uses
+==========
+
+the macros in desCode.h would be very useful for putting inline des
+functions in more complicated encryption routines.
diff --git a/Documentation/crypto/descore-readme.txt b/Documentation/crypto/descore-readme.txt
deleted file mode 100644
index 16e9e63..0000000
--- a/Documentation/crypto/descore-readme.txt
+++ /dev/null
@@ -1,352 +0,0 @@
-Below is the original README file from the descore.shar package.
-------------------------------------------------------------------------------
-
-des - fast & portable DES encryption & decryption.
-Copyright (C) 1992 Dana L. How
-
-This program is free software; you can redistribute it and/or modify
-it under the terms of the GNU Library 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 Library General Public License for more details.
-
-You should have received a copy of the GNU Library General Public License
-along with this program; if not, write to the Free Software
-Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
-
-Author's address: how@isl.stanford.edu
-
-$Id: README,v 1.15 1992/05/20 00:25:32 how E $
-
-
-==>> To compile after untarring/unsharring, just `make' <<==
-
-
-This package was designed with the following goals:
-1. Highest possible encryption/decryption PERFORMANCE.
-2. PORTABILITY to any byte-addressable host with a 32bit unsigned C type
-3. Plug-compatible replacement for KERBEROS's low-level routines.
-
-This second release includes a number of performance enhancements for
-register-starved machines. My discussions with Richard Outerbridge,
-71755.204@compuserve.com, sparked a number of these enhancements.
-
-To more rapidly understand the code in this package, inspect desSmallFips.i
-(created by typing `make') BEFORE you tackle desCode.h. The latter is set
-up in a parameterized fashion so it can easily be modified by speed-daemon
-hackers in pursuit of that last microsecond. You will find it more
-illuminating to inspect one specific implementation,
-and then move on to the common abstract skeleton with this one in mind.
-
-
-performance comparison to other available des code which i could
-compile on a SPARCStation 1 (cc -O4, gcc -O2):
-
-this code (byte-order independent):
- 30us per encryption (options: 64k tables, no IP/FP)
- 33us per encryption (options: 64k tables, FIPS standard bit ordering)
- 45us per encryption (options: 2k tables, no IP/FP)
- 48us per encryption (options: 2k tables, FIPS standard bit ordering)
- 275us to set a new key (uses 1k of key tables)
- this has the quickest encryption/decryption routines i've seen.
- since i was interested in fast des filters rather than crypt(3)
- and password cracking, i haven't really bothered yet to speed up
- the key setting routine. also, i have no interest in re-implementing
- all the other junk in the mit kerberos des library, so i've just
- provided my routines with little stub interfaces so they can be
- used as drop-in replacements with mit's code or any of the mit-
- compatible packages below. (note that the first two timings above
- are highly variable because of cache effects).
-
-kerberos des replacement from australia (version 1.95):
- 53us per encryption (uses 2k of tables)
- 96us to set a new key (uses 2.25k of key tables)
- so despite the author's inclusion of some of the performance
- improvements i had suggested to him, this package's
- encryption/decryption is still slower on the sparc and 68000.
- more specifically, 19-40% slower on the 68020 and 11-35% slower
- on the sparc, depending on the compiler;
- in full gory detail (ALT_ECB is a libdes variant):
- compiler machine desCore libdes ALT_ECB slower by
- gcc 2.1 -O2 Sun 3/110 304 uS 369.5uS 461.8uS 22%
- cc -O1 Sun 3/110 336 uS 436.6uS 399.3uS 19%
- cc -O2 Sun 3/110 360 uS 532.4uS 505.1uS 40%
- cc -O4 Sun 3/110 365 uS 532.3uS 505.3uS 38%
- gcc 2.1 -O2 Sun 4/50 48 uS 53.4uS 57.5uS 11%
- cc -O2 Sun 4/50 48 uS 64.6uS 64.7uS 35%
- cc -O4 Sun 4/50 48 uS 64.7uS 64.9uS 35%
- (my time measurements are not as accurate as his).
- the comments in my first release of desCore on version 1.92:
- 68us per encryption (uses 2k of tables)
- 96us to set a new key (uses 2.25k of key tables)
- this is a very nice package which implements the most important
- of the optimizations which i did in my encryption routines.
- it's a bit weak on common low-level optimizations which is why
- it's 39%-106% slower. because he was interested in fast crypt(3) and
- password-cracking applications, he also used the same ideas to
- speed up the key-setting routines with impressive results.
- (at some point i may do the same in my package). he also implements
- the rest of the mit des library.
- (code from eay@psych.psy.uq.oz.au via comp.sources.misc)
-
-fast crypt(3) package from denmark:
- the des routine here is buried inside a loop to do the
- crypt function and i didn't feel like ripping it out and measuring
- performance. his code takes 26 sparc instructions to compute one
- des iteration; above, Quick (64k) takes 21 and Small (2k) takes 37.
- he claims to use 280k of tables but the iteration calculation seems
- to use only 128k. his tables and code are machine independent.
- (code from glad@daimi.aau.dk via alt.sources or comp.sources.misc)
-
-swedish reimplementation of Kerberos des library
- 108us per encryption (uses 34k worth of tables)
- 134us to set a new key (uses 32k of key tables to get this speed!)
- the tables used seem to be machine-independent;
- he seems to have included a lot of special case code
- so that, e.g., `long' loads can be used instead of 4 `char' loads
- when the machine's architecture allows it.
- (code obtained from chalmers.se:pub/des)
-
-crack 3.3c package from england:
- as in crypt above, the des routine is buried in a loop. it's
- also very modified for crypt. his iteration code uses 16k
- of tables and appears to be slow.
- (code obtained from aem@aber.ac.uk via alt.sources or comp.sources.misc)
-
-``highly optimized'' and tweaked Kerberos/Athena code (byte-order dependent):
- 165us per encryption (uses 6k worth of tables)
- 478us to set a new key (uses <1k of key tables)
- so despite the comments in this code, it was possible to get
- faster code AND smaller tables, as well as making the tables
- machine-independent.
- (code obtained from prep.ai.mit.edu)
-
-UC Berkeley code (depends on machine-endedness):
- 226us per encryption
-10848us to set a new key
- table sizes are unclear, but they don't look very small
- (code obtained from wuarchive.wustl.edu)
-
-
-motivation and history
-
-a while ago i wanted some des routines and the routines documented on sun's
-man pages either didn't exist or dumped core. i had heard of kerberos,
-and knew that it used des, so i figured i'd use its routines. but once
-i got it and looked at the code, it really set off a lot of pet peeves -
-it was too convoluted, the code had been written without taking
-advantage of the regular structure of operations such as IP, E, and FP
-(i.e. the author didn't sit down and think before coding),
-it was excessively slow, the author had attempted to clarify the code
-by adding MORE statements to make the data movement more `consistent'
-instead of simplifying his implementation and cutting down on all data
-movement (in particular, his use of L1, R1, L2, R2), and it was full of
-idiotic `tweaks' for particular machines which failed to deliver significant
-speedups but which did obfuscate everything. so i took the test data
-from his verification program and rewrote everything else.
-
-a while later i ran across the great crypt(3) package mentioned above.
-the fact that this guy was computing 2 sboxes per table lookup rather
-than one (and using a MUCH larger table in the process) emboldened me to
-do the same - it was a trivial change from which i had been scared away
-by the larger table size. in his case he didn't realize you don't need to keep
-the working data in TWO forms, one for easy use of half the sboxes in
-indexing, the other for easy use of the other half; instead you can keep
-it in the form for the first half and use a simple rotate to get the other
-half. this means i have (almost) half the data manipulation and half
-the table size. in fairness though he might be encoding something particular
-to crypt(3) in his tables - i didn't check.
-
-i'm glad that i implemented it the way i did, because this C version is
-portable (the ifdef's are performance enhancements) and it is faster
-than versions hand-written in assembly for the sparc!
-
-
-porting notes
-
-one thing i did not want to do was write an enormous mess
-which depended on endedness and other machine quirks,
-and which necessarily produced different code and different lookup tables
-for different machines. see the kerberos code for an example
-of what i didn't want to do; all their endedness-specific `optimizations'
-obfuscate the code and in the end were slower than a simpler machine
-independent approach. however, there are always some portability
-considerations of some kind, and i have included some options
-for varying numbers of register variables.
-perhaps some will still regard the result as a mess!
-
-1) i assume everything is byte addressable, although i don't actually
- depend on the byte order, and that bytes are 8 bits.
- i assume word pointers can be freely cast to and from char pointers.
- note that 99% of C programs make these assumptions.
- i always use unsigned char's if the high bit could be set.
-2) the typedef `word' means a 32 bit unsigned integral type.
- if `unsigned long' is not 32 bits, change the typedef in desCore.h.
- i assume sizeof(word) == 4 EVERYWHERE.
-
-the (worst-case) cost of my NOT doing endedness-specific optimizations
-in the data loading and storing code surrounding the key iterations
-is less than 12%. also, there is the added benefit that
-the input and output work areas do not need to be word-aligned.
-
-
-OPTIONAL performance optimizations
-
-1) you should define one of `i386,' `vax,' `mc68000,' or `sparc,'
- whichever one is closest to the capabilities of your machine.
- see the start of desCode.h to see exactly what this selection implies.
- note that if you select the wrong one, the des code will still work;
- these are just performance tweaks.
-2) for those with functional `asm' keywords: you should change the
- ROR and ROL macros to use machine rotate instructions if you have them.
- this will save 2 instructions and a temporary per use,
- or about 32 to 40 instructions per en/decryption.
- note that gcc is smart enough to translate the ROL/R macros into
- machine rotates!
-
-these optimizations are all rather persnickety, yet with them you should
-be able to get performance equal to assembly-coding, except that:
-1) with the lack of a bit rotate operator in C, rotates have to be synthesized
- from shifts. so access to `asm' will speed things up if your machine
- has rotates, as explained above in (3) (not necessary if you use gcc).
-2) if your machine has less than 12 32-bit registers i doubt your compiler will
- generate good code.
- `i386' tries to configure the code for a 386 by only declaring 3 registers
- (it appears that gcc can use ebx, esi and edi to hold register variables).
- however, if you like assembly coding, the 386 does have 7 32-bit registers,
- and if you use ALL of them, use `scaled by 8' address modes with displacement
- and other tricks, you can get reasonable routines for DesQuickCore... with
- about 250 instructions apiece. For DesSmall... it will help to rearrange
- des_keymap, i.e., now the sbox # is the high part of the index and
- the 6 bits of data is the low part; it helps to exchange these.
- since i have no way to conveniently test it i have not provided my
- shoehorned 386 version. note that with this release of desCore, gcc is able
- to put everything in registers(!), and generate about 370 instructions apiece
- for the DesQuickCore... routines!
-
-coding notes
-
-the en/decryption routines each use 6 necessary register variables,
-with 4 being actively used at once during the inner iterations.
-if you don't have 4 register variables get a new machine.
-up to 8 more registers are used to hold constants in some configurations.
-
-i assume that the use of a constant is more expensive than using a register:
-a) additionally, i have tried to put the larger constants in registers.
- registering priority was by the following:
- anything more than 12 bits (bad for RISC and CISC)
- greater than 127 in value (can't use movq or byte immediate on CISC)
- 9-127 (may not be able to use CISC shift immediate or add/sub quick),
- 1-8 were never registered, being the cheapest constants.
-b) the compiler may be too stupid to realize table and table+256 should
- be assigned to different constant registers and instead repetitively
- do the arithmetic, so i assign these to explicit `m' register variables
- when possible and helpful.
-
-i assume that indexing is cheaper or equivalent to auto increment/decrement,
-where the index is 7 bits unsigned or smaller.
-this assumption is reversed for 68k and vax.
-
-i assume that addresses can be cheaply formed from two registers,
-or from a register and a small constant.
-for the 68000, the `two registers and small offset' form is used sparingly.
-all index scaling is done explicitly - no hidden shifts by log2(sizeof).
-
-the code is written so that even a dumb compiler
-should never need more than one hidden temporary,
-increasing the chance that everything will fit in the registers.
-KEEP THIS MORE SUBTLE POINT IN MIND IF YOU REWRITE ANYTHING.
-(actually, there are some code fragments now which do require two temps,
-but fixing it would either break the structure of the macros or
-require declaring another temporary).
-
-
-special efficient data format
-
-bits are manipulated in this arrangement most of the time (S7 S5 S3 S1):
- 003130292827xxxx242322212019xxxx161514131211xxxx080706050403xxxx
-(the x bits are still there, i'm just emphasizing where the S boxes are).
-bits are rotated left 4 when computing S6 S4 S2 S0:
- 282726252423xxxx201918171615xxxx121110090807xxxx040302010031xxxx
-the rightmost two bits are usually cleared so the lower byte can be used
-as an index into an sbox mapping table. the next two x'd bits are set
-to various values to access different parts of the tables.
-
-
-how to use the routines
-
-datatypes:
- pointer to 8 byte area of type DesData
- used to hold keys and input/output blocks to des.
-
- pointer to 128 byte area of type DesKeys
- used to hold full 768-bit key.
- must be long-aligned.
-
-DesQuickInit()
- call this before using any other routine with `Quick' in its name.
- it generates the special 64k table these routines need.
-DesQuickDone()
- frees this table
-
-DesMethod(m, k)
- m points to a 128byte block, k points to an 8 byte des key
- which must have odd parity (or -1 is returned) and which must
- not be a (semi-)weak key (or -2 is returned).
- normally DesMethod() returns 0.
- m is filled in from k so that when one of the routines below
- is called with m, the routine will act like standard des
- en/decryption with the key k. if you use DesMethod,
- you supply a standard 56bit key; however, if you fill in
- m yourself, you will get a 768bit key - but then it won't
- be standard. it's 768bits not 1024 because the least significant
- two bits of each byte are not used. note that these two bits
- will be set to magic constants which speed up the encryption/decryption
- on some machines. and yes, each byte controls
- a specific sbox during a specific iteration.
- you really shouldn't use the 768bit format directly; i should
- provide a routine that converts 128 6-bit bytes (specified in
- S-box mapping order or something) into the right format for you.
- this would entail some byte concatenation and rotation.
-
-Des{Small|Quick}{Fips|Core}{Encrypt|Decrypt}(d, m, s)
- performs des on the 8 bytes at s into the 8 bytes at d. (d,s: char *).
- uses m as a 768bit key as explained above.
- the Encrypt|Decrypt choice is obvious.
- Fips|Core determines whether a completely standard FIPS initial
- and final permutation is done; if not, then the data is loaded
- and stored in a nonstandard bit order (FIPS w/o IP/FP).
- Fips slows down Quick by 10%, Small by 9%.
- Small|Quick determines whether you use the normal routine
- or the crazy quick one which gobbles up 64k more of memory.
- Small is 50% slower then Quick, but Quick needs 32 times as much
- memory. Quick is included for programs that do nothing but DES,
- e.g., encryption filters, etc.
-
-
-Getting it to compile on your machine
-
-there are no machine-dependencies in the code (see porting),
-except perhaps the `now()' macro in desTest.c.
-ALL generated tables are machine independent.
-you should edit the Makefile with the appropriate optimization flags
-for your compiler (MAX optimization).
-
-
-Speeding up kerberos (and/or its des library)
-
-note that i have included a kerberos-compatible interface in desUtil.c
-through the functions des_key_sched() and des_ecb_encrypt().
-to use these with kerberos or kerberos-compatible code put desCore.a
-ahead of the kerberos-compatible library on your linker's command line.
-you should not need to #include desCore.h; just include the header
-file provided with the kerberos library.
-
-Other uses
-
-the macros in desCode.h would be very useful for putting inline des
-functions in more complicated encryption routines.
diff --git a/Documentation/crypto/index.rst b/Documentation/crypto/index.rst
index c4ff5d7..21338fa 100644
--- a/Documentation/crypto/index.rst
+++ b/Documentation/crypto/index.rst
@@ -17,9 +17,14 @@
:maxdepth: 2
intro
+ api-intro
architecture
+
+ async-tx-api
+ asymmetric-keys
devel-algos
userspace-if
crypto_engine
api
api-samples
+ descore-readme
diff --git a/Documentation/crypto/userspace-if.rst b/Documentation/crypto/userspace-if.rst
index ff86bef..52019e9 100644
--- a/Documentation/crypto/userspace-if.rst
+++ b/Documentation/crypto/userspace-if.rst
@@ -23,7 +23,7 @@
and asynchronous invocations. The user space API call is fully
synchronous.
-[1] http://www.chronox.de/libkcapi.html
+[1] https://www.chronox.de/libkcapi.html
User Space API General Remarks
------------------------------
@@ -384,4 +384,4 @@
the aforementioned Netlink kernel interface. [1] also contains a test
application that invokes all libkcapi API calls.
-[1] http://www.chronox.de/libkcapi.html
+[1] https://www.chronox.de/libkcapi.html
diff --git a/Documentation/dev-tools/coccinelle.rst b/Documentation/dev-tools/coccinelle.rst
index 70274c3..74c5e6a 100644
--- a/Documentation/dev-tools/coccinelle.rst
+++ b/Documentation/dev-tools/coccinelle.rst
@@ -85,7 +85,7 @@
file:line:column-column: message
- ``context`` highlights lines of interest and their context in a
- diff-like style.Lines of interest are indicated with ``-``.
+ diff-like style. Lines of interest are indicated with ``-``.
- ``org`` generates a report in the Org mode format of Emacs.
@@ -119,7 +119,7 @@
description of the problem being checked by the semantic patch, and
includes a reference to Coccinelle.
-As any static code analyzer, Coccinelle produces false
+As with any static code analyzer, Coccinelle produces false
positives. Thus, reports must be carefully checked, and patches
reviewed.
@@ -135,18 +135,18 @@
make coccicheck MODE=report J=4
-As of Coccinelle 1.0.2 Coccinelle uses Ocaml parmap for parallelization,
+As of Coccinelle 1.0.2 Coccinelle uses Ocaml parmap for parallelization;
if support for this is detected you will benefit from parmap parallelization.
When parmap is enabled coccicheck will enable dynamic load balancing by using
-``--chunksize 1`` argument, this ensures we keep feeding threads with work
+``--chunksize 1`` argument. This ensures we keep feeding threads with work
one by one, so that we avoid the situation where most work gets done by only
a few threads. With dynamic load balancing, if a thread finishes early we keep
feeding it more work.
When parmap is enabled, if an error occurs in Coccinelle, this error
-value is propagated back, the return value of the ``make coccicheck``
-captures this return value.
+value is propagated back, and the return value of the ``make coccicheck``
+command captures this return value.
Using Coccinelle with a single semantic patch
---------------------------------------------
@@ -175,15 +175,22 @@
make coccicheck M=drivers/net/wireless/
To apply Coccinelle on a file basis, instead of a directory basis, the
-following command may be used::
+C variable is used by the makefile to select which files to work with.
+This variable can be used to run scripts for the entire kernel, a
+specific directory, or for a single file.
- make C=1 CHECK="scripts/coccicheck"
+For example, to check drivers/bluetooth/bfusb.c, the value 1 is
+passed to the C variable to check files that make considers
+need to be compiled.::
-To check only newly edited code, use the value 2 for the C flag, i.e.::
+ make C=1 CHECK=scripts/coccicheck drivers/bluetooth/bfusb.o
- make C=2 CHECK="scripts/coccicheck"
+The value 2 is passed to the C variable to check files regardless of
+whether they need to be compiled or not.::
-In these modes, which works on a file basis, there is no information
+ make C=2 CHECK=scripts/coccicheck drivers/bluetooth/bfusb.o
+
+In these modes, which work on a file basis, there is no information
about semantic patches displayed, and no commit message proposed.
This runs every semantic patch in scripts/coccinelle by default. The
@@ -198,12 +205,12 @@
Using coccicheck is best as it provides in the spatch command line
include options matching the options used when we compile the kernel.
-You can learn what these options are by using V=1, you could then
+You can learn what these options are by using V=1; you could then
manually run Coccinelle with debug options added.
Alternatively you can debug running Coccinelle against SmPL patches
-by asking for stderr to be redirected to stderr, by default stderr
-is redirected to /dev/null, if you'd like to capture stderr you
+by asking for stderr to be redirected to stderr. By default stderr
+is redirected to /dev/null; if you'd like to capture stderr you
can specify the ``DEBUG_FILE="file.txt"`` option to coccicheck. For
instance::
@@ -211,8 +218,8 @@
make coccicheck COCCI=scripts/coccinelle/free/kfree.cocci MODE=report DEBUG_FILE=cocci.err
cat cocci.err
-You can use SPFLAGS to add debugging flags, for instance you may want to
-add both --profile --show-trying to SPFLAGS when debugging. For instance
+You can use SPFLAGS to add debugging flags; for instance you may want to
+add both --profile --show-trying to SPFLAGS when debugging. For example
you may want to use::
rm -f err.log
@@ -229,7 +236,7 @@
--------------------
Coccinelle supports reading .cocciconfig for default Coccinelle options that
-should be used every time spatch is spawned, the order of precedence for
+should be used every time spatch is spawned. The order of precedence for
variables for .cocciconfig is as follows:
- Your current user's home directory is processed first
@@ -237,7 +244,7 @@
- The directory provided with the --dir option is processed last, if used
Since coccicheck runs through make, it naturally runs from the kernel
-proper dir, as such the second rule above would be implied for picking up a
+proper dir; as such the second rule above would be implied for picking up a
.cocciconfig when using ``make coccicheck``.
``make coccicheck`` also supports using M= targets. If you do not supply
@@ -260,13 +267,13 @@
order logic of .cocciconfig reading. If using the kernel's coccicheck target,
override any of the kernel's .coccicheck's settings using SPFLAGS.
-We help Coccinelle when used against Linux with a set of sensible defaults
+We help Coccinelle when used against Linux with a set of sensible default
options for Linux with our own Linux .cocciconfig. This hints to coccinelle
-git can be used for ``git grep`` queries over coccigrep. A timeout of 200
+that git can be used for ``git grep`` queries over coccigrep. A timeout of 200
seconds should suffice for now.
The options picked up by coccinelle when reading a .cocciconfig do not appear
-as arguments to spatch processes running on your system, to confirm what
+as arguments to spatch processes running on your system. To confirm what
options will be used by Coccinelle run::
spatch --print-options-only
@@ -290,7 +297,7 @@
Coccinelle supports idutils as well but requires coccinelle >= 1.0.6.
When no ID file is specified coccinelle assumes your ID database file
-is in the file .id-utils.index on the top level of the kernel, coccinelle
+is in the file .id-utils.index on the top level of the kernel. Coccinelle
carries a script scripts/idutils_index.sh which creates the database with::
mkid -i C --output .id-utils.index
@@ -317,7 +324,7 @@
---------------------------
SmPL patches can have their own requirements for options passed
-to Coccinelle. SmPL patch specific options can be provided by
+to Coccinelle. SmPL patch-specific options can be provided by
providing them at the top of the SmPL patch, for instance::
// Options: --no-includes --include-headers
@@ -327,7 +334,7 @@
As Coccinelle features get added some more advanced SmPL patches
may require newer versions of Coccinelle. If an SmPL patch requires
-at least a version of Coccinelle, this can be specified as follows,
+a minimum version of Coccinelle, this can be specified as follows,
as an example if requiring at least Coccinelle >= 1.0.5::
// Requires: 1.0.5
diff --git a/Documentation/dev-tools/gcov.rst b/Documentation/dev-tools/gcov.rst
index 7bd0135..9e989ba 100644
--- a/Documentation/dev-tools/gcov.rst
+++ b/Documentation/dev-tools/gcov.rst
@@ -22,7 +22,7 @@
* minimizing kernel configurations (do I need this option if the
associated code is never run?)
-.. _gcov: http://gcc.gnu.org/onlinedocs/gcc/Gcov.html
+.. _gcov: https://gcc.gnu.org/onlinedocs/gcc/Gcov.html
.. _lcov: http://ltp.sourceforge.net/coverage/lcov.php
@@ -171,7 +171,7 @@
GCC and LLVM gcov tools are not necessarily compatible. Use gcov_ to work with
GCC-generated .gcno and .gcda files, and use llvm-cov_ for Clang.
-.. _gcov: http://gcc.gnu.org/onlinedocs/gcc/Gcov.html
+.. _gcov: https://gcc.gnu.org/onlinedocs/gcc/Gcov.html
.. _llvm-cov: https://llvm.org/docs/CommandGuide/llvm-cov.html
Build differences between GCC and Clang gcov are handled by Kconfig. It
diff --git a/Documentation/dev-tools/kasan.rst b/Documentation/dev-tools/kasan.rst
index c652d740..38fd568 100644
--- a/Documentation/dev-tools/kasan.rst
+++ b/Documentation/dev-tools/kasan.rst
@@ -13,11 +13,8 @@
memory access, and therefore requires a compiler version that supports that.
Generic KASAN is supported in both GCC and Clang. With GCC it requires version
-4.9.2 or later for basic support and version 5.0 or later for detection of
-out-of-bounds accesses for stack and global variables and for inline
-instrumentation mode (see the Usage section). With Clang it requires version
-7.0.0 or later and it doesn't support detection of out-of-bounds accesses for
-global variables yet.
+8.3.0 or later. With Clang it requires version 7.0.0 or later, but detection of
+out-of-bounds accesses for global variables is only supported since Clang 11.
Tag-based KASAN is only supported in Clang and requires version 7.0.0 or later.
@@ -193,6 +190,9 @@
This option significantly enlarges kernel but it gives x1.1-x2 performance
boost over outline instrumented kernel.
+Generic KASAN prints up to 2 call_rcu() call stacks in reports, the last one
+and the second to last.
+
Software tag-based KASAN
~~~~~~~~~~~~~~~~~~~~~~~~
diff --git a/Documentation/dev-tools/kcsan.rst b/Documentation/dev-tools/kcsan.rst
index ce4bbd9..be7a0b0 100644
--- a/Documentation/dev-tools/kcsan.rst
+++ b/Documentation/dev-tools/kcsan.rst
@@ -8,7 +8,8 @@
Usage
-----
-KCSAN requires Clang version 11 or later.
+KCSAN is supported by both GCC and Clang. With GCC we require version 11 or
+later, and with Clang also require version 11 or later.
To enable KCSAN configure the kernel with::
@@ -114,12 +115,6 @@
To dynamically limit for which functions to generate reports, see the
`DebugFS interface`_ blacklist/whitelist feature.
- For ``__always_inline`` functions, replace ``__always_inline`` with
- ``__no_kcsan_or_inline`` (which implies ``__always_inline``)::
-
- static __no_kcsan_or_inline void foo(void) {
- ...
-
* To disable data race detection for a particular compilation unit, add to the
``Makefile``::
diff --git a/Documentation/dev-tools/kgdb.rst b/Documentation/dev-tools/kgdb.rst
index 61293f4..c908ef4 100644
--- a/Documentation/dev-tools/kgdb.rst
+++ b/Documentation/dev-tools/kgdb.rst
@@ -316,7 +316,7 @@
Kernel parameter: ``kgdbcon``
-----------------------------
-The ``kgdbcon`` feature allows you to see :c:func:`printk` messages inside gdb
+The ``kgdbcon`` feature allows you to see printk() messages inside gdb
while gdb is connected to the kernel. Kdb does not make use of the kgdbcon
feature.
@@ -432,7 +432,7 @@
``ps`` Displays only the active processes
``ps A`` Shows all the processes
``summary`` Shows kernel version info and memory usage
- ``bt`` Get a backtrace of the current process using :c:func:`dump_stack`
+ ``bt`` Get a backtrace of the current process using dump_stack()
``dmesg`` View the kernel syslog buffer
``go`` Continue the system
=========== =================================================================
@@ -724,7 +724,7 @@
The arch-specific portion implements:
- contains an arch-specific trap catcher which invokes
- :c:func:`kgdb_handle_exception` to start kgdb about doing its work
+ kgdb_handle_exception() to start kgdb about doing its work
- translation to and from gdb specific packet format to :c:type:`pt_regs`
@@ -769,7 +769,7 @@
config. Later run ``modprobe kdb_hello`` and the next time you
enter the kdb shell, you can run the ``hello`` command.
- - The implementation for :c:func:`kdb_printf` which emits messages directly
+ - The implementation for kdb_printf() which emits messages directly
to I/O drivers, bypassing the kernel log.
- SW / HW breakpoint management for the kdb shell
@@ -872,10 +872,10 @@
attached keyboard. The keyboard infrastructure is only compiled into the
kernel when ``CONFIG_KDB_KEYBOARD=y`` is set in the kernel configuration.
-The core polled keyboard driver driver for PS/2 type keyboards is in
+The core polled keyboard driver for PS/2 type keyboards is in
``drivers/char/kdb_keyboard.c``. This driver is hooked into the debug core
when kgdboc populates the callback in the array called
-:c:type:`kdb_poll_funcs[]`. The :c:func:`kdb_get_kbd_char` is the top-level
+:c:type:`kdb_poll_funcs[]`. The kdb_get_kbd_char() is the top-level
function which polls hardware for single character input.
kgdboc and kms
@@ -887,10 +887,10 @@
kernel mode setting support.
Every time the kernel debugger is entered it calls
-:c:func:`kgdboc_pre_exp_handler` which in turn calls :c:func:`con_debug_enter`
+kgdboc_pre_exp_handler() which in turn calls con_debug_enter()
in the virtual console layer. On resuming kernel execution, the kernel
-debugger calls :c:func:`kgdboc_post_exp_handler` which in turn calls
-:c:func:`con_debug_leave`.
+debugger calls kgdboc_post_exp_handler() which in turn calls
+con_debug_leave().
Any video driver that wants to be compatible with the kernel debugger
and the atomic kms callbacks must implement the ``mode_set_base_atomic``,
diff --git a/Documentation/dev-tools/kmemleak.rst b/Documentation/dev-tools/kmemleak.rst
index fce2628..a41a2d2 100644
--- a/Documentation/dev-tools/kmemleak.rst
+++ b/Documentation/dev-tools/kmemleak.rst
@@ -8,8 +8,6 @@
reported via /sys/kernel/debug/kmemleak. A similar method is used by the
Valgrind tool (``memcheck --leak-check``) to detect the memory leaks in
user-space applications.
-Kmemleak is supported on x86, arm, arm64, powerpc, sparc, sh, microblaze, mips,
-s390, nds32, arc and xtensa.
Usage
-----
diff --git a/Documentation/dev-tools/kunit/faq.rst b/Documentation/dev-tools/kunit/faq.rst
index ea55b24..1628862 100644
--- a/Documentation/dev-tools/kunit/faq.rst
+++ b/Documentation/dev-tools/kunit/faq.rst
@@ -61,3 +61,43 @@
kernel by installing a production configuration of the kernel on production
hardware with a production userspace and then trying to exercise some behavior
that depends on interactions between the hardware, the kernel, and userspace.
+
+KUnit isn't working, what should I do?
+======================================
+
+Unfortunately, there are a number of things which can break, but here are some
+things to try.
+
+1. Try running ``./tools/testing/kunit/kunit.py run`` with the ``--raw_output``
+ parameter. This might show details or error messages hidden by the kunit_tool
+ parser.
+2. Instead of running ``kunit.py run``, try running ``kunit.py config``,
+ ``kunit.py build``, and ``kunit.py exec`` independently. This can help track
+ down where an issue is occurring. (If you think the parser is at fault, you
+ can run it manually against stdin or a file with ``kunit.py parse``.)
+3. Running the UML kernel directly can often reveal issues or error messages
+ kunit_tool ignores. This should be as simple as running ``./vmlinux`` after
+ building the UML kernel (e.g., by using ``kunit.py build``). Note that UML
+ has some unusual requirements (such as the host having a tmpfs filesystem
+ mounted), and has had issues in the past when built statically and the host
+ has KASLR enabled. (On older host kernels, you may need to run ``setarch
+ `uname -m` -R ./vmlinux`` to disable KASLR.)
+4. Make sure the kernel .config has ``CONFIG_KUNIT=y`` and at least one test
+ (e.g. ``CONFIG_KUNIT_EXAMPLE_TEST=y``). kunit_tool will keep its .config
+ around, so you can see what config was used after running ``kunit.py run``.
+ It also preserves any config changes you might make, so you can
+ enable/disable things with ``make ARCH=um menuconfig`` or similar, and then
+ re-run kunit_tool.
+5. Try to run ``make ARCH=um defconfig`` before running ``kunit.py run``. This
+ may help clean up any residual config items which could be causing problems.
+6. Finally, try running KUnit outside UML. KUnit and KUnit tests can run be
+ built into any kernel, or can be built as a module and loaded at runtime.
+ Doing so should allow you to determine if UML is causing the issue you're
+ seeing. When tests are built-in, they will execute when the kernel boots, and
+ modules will automatically execute associated tests when loaded. Test results
+ can be collected from ``/sys/kernel/debug/kunit/<test suite>/results``, and
+ can be parsed with ``kunit.py parse``. For more details, see "KUnit on
+ non-UML architectures" in :doc:`usage`.
+
+If none of the above tricks help, you are always welcome to email any issues to
+kunit-dev@googlegroups.com.
diff --git a/Documentation/dev-tools/kunit/kunit-tool.rst b/Documentation/dev-tools/kunit/kunit-tool.rst
index 949af2d..29ae2fe 100644
--- a/Documentation/dev-tools/kunit/kunit-tool.rst
+++ b/Documentation/dev-tools/kunit/kunit-tool.rst
@@ -19,13 +19,13 @@
other program directly inside of a host operating system. To be clear, it does
not require any virtualization support: it is just a regular program.
-What is a kunitconfig?
-======================
+What is a .kunitconfig?
+=======================
It's just a defconfig that kunit_tool looks for in the base directory.
kunit_tool uses it to generate a .config as you might expect. In addition, it
verifies that the generated .config contains the CONFIG options in the
-kunitconfig; the reason it does this is so that it is easy to be sure that a
+.kunitconfig; the reason it does this is so that it is easy to be sure that a
CONFIG that enables a test actually ends up in the .config.
How do I use kunit_tool?
@@ -46,16 +46,9 @@
- ``--timeout`` sets a maximum amount of time to allow tests to run.
- ``--jobs`` sets the number of threads to use to build the kernel.
-If you just want to use the defconfig that ships with the kernel, you can
-append the ``--defconfig`` flag as well:
-
-.. code-block:: bash
-
- ./tools/testing/kunit/kunit.py run --timeout=30 --jobs=`nproc --all` --defconfig
-
.. note::
- This command is particularly helpful for getting started because it
- just works. No kunitconfig needs to be present.
+ This command will work even without a .kunitconfig file: if no
+ .kunitconfig is present, a default one will be used instead.
For a list of all the flags supported by kunit_tool, you can run:
diff --git a/Documentation/dev-tools/kunit/start.rst b/Documentation/dev-tools/kunit/start.rst
index bb112cf..d23385e 100644
--- a/Documentation/dev-tools/kunit/start.rst
+++ b/Documentation/dev-tools/kunit/start.rst
@@ -18,7 +18,7 @@
.. code-block:: bash
- ./tools/testing/kunit/kunit.py run --defconfig
+ ./tools/testing/kunit/kunit.py run
For more information on this wrapper (also called kunit_tool) check out the
:doc:`kunit-tool` page.
diff --git a/Documentation/dev-tools/sparse.rst b/Documentation/dev-tools/sparse.rst
index 6f48705..02102be 100644
--- a/Documentation/dev-tools/sparse.rst
+++ b/Documentation/dev-tools/sparse.rst
@@ -9,6 +9,8 @@
number of potential problems with kernel code. See
https://lwn.net/Articles/689907/ for an overview of sparse; this document
contains some kernel-specific sparse information.
+More information on sparse, mainly about its internals, can be found in
+its official pages at https://sparse.docs.kernel.org.
Using sparse for typechecking
@@ -73,8 +75,8 @@
Getting sparse
--------------
-You can get latest released versions from the Sparse homepage at
-https://sparse.wiki.kernel.org/index.php/Main_Page
+You can get tarballs of the latest released versions from:
+https://www.kernel.org/pub/software/devel/sparse/dist/
Alternatively, you can get snapshots of the latest development version
of sparse using git to clone::
diff --git a/Documentation/devicetree/bindings/Makefile b/Documentation/devicetree/bindings/Makefile
index a638989..91c4d00 100644
--- a/Documentation/devicetree/bindings/Makefile
+++ b/Documentation/devicetree/bindings/Makefile
@@ -2,7 +2,6 @@
DT_DOC_CHECKER ?= dt-doc-validate
DT_EXTRACT_EX ?= dt-extract-example
DT_MK_SCHEMA ?= dt-mk-schema
-DT_MK_SCHEMA_USERONLY_FLAG := $(if $(DT_SCHEMA_FILES), -u)
DT_SCHEMA_MIN_VERSION = 2020.5
@@ -35,21 +34,40 @@
DT_DOCS = $(shell $(find_cmd) | sed -e 's|^$(srctree)/||')
-DT_SCHEMA_FILES ?= $(DT_DOCS)
-
-extra-$(CHECK_DT_BINDING) += $(patsubst $(src)/%.yaml,%.example.dts, $(DT_SCHEMA_FILES))
-extra-$(CHECK_DT_BINDING) += $(patsubst $(src)/%.yaml,%.example.dt.yaml, $(DT_SCHEMA_FILES))
-extra-$(CHECK_DT_BINDING) += processed-schema-examples.yaml
-
override DTC_FLAGS := \
-Wno-avoid_unnecessary_addr_size \
- -Wno-graph_child_address
+ -Wno-graph_child_address \
+ -Wno-interrupt_provider
$(obj)/processed-schema-examples.yaml: $(DT_DOCS) check_dtschema_version FORCE
$(call if_changed,mk_schema)
-$(obj)/processed-schema.yaml: DT_MK_SCHEMA_FLAGS := $(DT_MK_SCHEMA_USERONLY_FLAG)
+ifeq ($(DT_SCHEMA_FILES),)
+
+# Unless DT_SCHEMA_FILES is specified, use the full schema for dtbs_check too.
+# Just copy processed-schema-examples.yaml
+
+$(obj)/processed-schema.yaml: $(obj)/processed-schema-examples.yaml FORCE
+ $(call if_changed,copy)
+
+DT_SCHEMA_FILES = $(DT_DOCS)
+
+else
+
+# If DT_SCHEMA_FILES is specified, use it for processed-schema.yaml
+
+$(obj)/processed-schema.yaml: DT_MK_SCHEMA_FLAGS := -u
$(obj)/processed-schema.yaml: $(DT_SCHEMA_FILES) check_dtschema_version FORCE
$(call if_changed,mk_schema)
-extra-y += processed-schema.yaml
+endif
+
+extra-$(CHECK_DT_BINDING) += $(patsubst $(src)/%.yaml,%.example.dts, $(DT_SCHEMA_FILES))
+extra-$(CHECK_DT_BINDING) += $(patsubst $(src)/%.yaml,%.example.dt.yaml, $(DT_SCHEMA_FILES))
+extra-$(CHECK_DT_BINDING) += processed-schema-examples.yaml
+extra-$(CHECK_DTBS) += processed-schema.yaml
+
+# Hack: avoid 'Argument list too long' error for 'make clean'. Remove most of
+# build artifacts here before they are processed by scripts/Makefile.clean
+clean-files = $(shell find $(obj) \( -name '*.example.dts' -o \
+ -name '*.example.dt.yaml' \) -delete 2>/dev/null)
diff --git a/Documentation/devicetree/bindings/arm/al,alpine.yaml b/Documentation/devicetree/bindings/arm/al,alpine.yaml
deleted file mode 100644
index a70dff2..0000000
--- a/Documentation/devicetree/bindings/arm/al,alpine.yaml
+++ /dev/null
@@ -1,21 +0,0 @@
-# SPDX-License-Identifier: GPL-2.0
-%YAML 1.2
----
-$id: http://devicetree.org/schemas/arm/al,alpine.yaml#
-$schema: http://devicetree.org/meta-schemas/core.yaml#
-
-title: Annapurna Labs Alpine Platform Device Tree Bindings
-
-maintainers:
- - Tsahee Zidenberg <tsahee@annapurnalabs.com>
- - Antoine Tenart <antoine.tenart@bootlin.com>
-
-properties:
- compatible:
- items:
- - const: al,alpine
- model:
- items:
- - const: "Annapurna Labs Alpine Dev Board"
-
-...
diff --git a/Documentation/devicetree/bindings/arm/amazon,al.yaml b/Documentation/devicetree/bindings/arm/amazon,al.yaml
new file mode 100644
index 0000000..a3a4d71
--- /dev/null
+++ b/Documentation/devicetree/bindings/arm/amazon,al.yaml
@@ -0,0 +1,33 @@
+# SPDX-License-Identifier: GPL-2.0
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/arm/amazon,al.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Amazon's Annapurna Labs Alpine Platform Device Tree Bindings
+
+maintainers:
+ - Hanna Hawa <hhhawa@amazon.com>
+ - Talel Shenhar <talel@amazon.com>, <talelshenhar@gmail.com>
+ - Ronen Krupnik <ronenk@amazon.com>
+
+properties:
+ compatible:
+ oneOf:
+ - description: Boards with Alpine V1 SoC
+ items:
+ - const: al,alpine
+
+ - description: Boards with Alpine V2 SoC
+ items:
+ - enum:
+ - al,alpine-v2-evp
+ - const: al,alpine-v2
+
+ - description: Boards with Alpine V3 SoC
+ items:
+ - enum:
+ - amazon,al-alpine-v3-evp
+ - const: amazon,al-alpine-v3
+
+...
diff --git a/Documentation/devicetree/bindings/arm/amlogic.yaml b/Documentation/devicetree/bindings/arm/amlogic.yaml
index 378229f..5eba9f4 100644
--- a/Documentation/devicetree/bindings/arm/amlogic.yaml
+++ b/Documentation/devicetree/bindings/arm/amlogic.yaml
@@ -121,6 +121,7 @@
- libretech,aml-s912-pc
- nexbox,a1
- tronsmart,vega-s96
+ - wetek,core2
- const: amlogic,s912
- const: amlogic,meson-gxm
diff --git a/Documentation/devicetree/bindings/arm/arm,scmi.txt b/Documentation/devicetree/bindings/arm/arm,scmi.txt
index 1f293ea..55deb68 100644
--- a/Documentation/devicetree/bindings/arm/arm,scmi.txt
+++ b/Documentation/devicetree/bindings/arm/arm,scmi.txt
@@ -102,7 +102,7 @@
[0] http://infocenter.arm.com/help/topic/com.arm.doc.den0056a/index.html
[1] Documentation/devicetree/bindings/clock/clock-bindings.txt
[2] Documentation/devicetree/bindings/power/power-domain.yaml
-[3] Documentation/devicetree/bindings/thermal/thermal.txt
+[3] Documentation/devicetree/bindings/thermal/thermal*.yaml
[4] Documentation/devicetree/bindings/sram/sram.yaml
[5] Documentation/devicetree/bindings/reset/reset.txt
diff --git a/Documentation/devicetree/bindings/arm/arm,scpi.txt b/Documentation/devicetree/bindings/arm/arm,scpi.txt
index dd04d9d..bcd6c3e 100644
--- a/Documentation/devicetree/bindings/arm/arm,scpi.txt
+++ b/Documentation/devicetree/bindings/arm/arm,scpi.txt
@@ -108,7 +108,7 @@
[0] http://infocenter.arm.com/help/topic/com.arm.doc.dui0922b/index.html
[1] Documentation/devicetree/bindings/clock/clock-bindings.txt
-[2] Documentation/devicetree/bindings/thermal/thermal.txt
+[2] Documentation/devicetree/bindings/thermal/thermal*.yaml
[3] Documentation/devicetree/bindings/sram/sram.yaml
[4] Documentation/devicetree/bindings/power/power-domain.yaml
diff --git a/Documentation/devicetree/bindings/arm/bcm/raspberrypi,bcm2835-firmware.txt b/Documentation/devicetree/bindings/arm/bcm/raspberrypi,bcm2835-firmware.txt
deleted file mode 100644
index 6824b31..0000000
--- a/Documentation/devicetree/bindings/arm/bcm/raspberrypi,bcm2835-firmware.txt
+++ /dev/null
@@ -1,14 +0,0 @@
-Raspberry Pi VideoCore firmware driver
-
-Required properties:
-
-- compatible: Should be "raspberrypi,bcm2835-firmware"
-- mboxes: Phandle to the firmware device's Mailbox.
- (See: ../mailbox/mailbox.txt for more information)
-
-Example:
-
-firmware {
- compatible = "raspberrypi,bcm2835-firmware";
- mboxes = <&mailbox>;
-};
diff --git a/Documentation/devicetree/bindings/arm/bcm/raspberrypi,bcm2835-firmware.yaml b/Documentation/devicetree/bindings/arm/bcm/raspberrypi,bcm2835-firmware.yaml
new file mode 100644
index 0000000..17e4f20
--- /dev/null
+++ b/Documentation/devicetree/bindings/arm/bcm/raspberrypi,bcm2835-firmware.yaml
@@ -0,0 +1,68 @@
+# SPDX-License-Identifier: GPL-2.0
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/arm/bcm/raspberrypi,bcm2835-firmware.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Raspberry Pi VideoCore firmware driver
+
+maintainers:
+ - Eric Anholt <eric@anholt.net>
+ - Stefan Wahren <wahrenst@gmx.net>
+
+select:
+ properties:
+ compatible:
+ contains:
+ const: raspberrypi,bcm2835-firmware
+
+ required:
+ - compatible
+
+properties:
+ compatible:
+ items:
+ - const: raspberrypi,bcm2835-firmware
+ - const: simple-bus
+
+ mboxes:
+ $ref: '/schemas/types.yaml#/definitions/phandle'
+ description: |
+ Phandle to the firmware device's Mailbox.
+ (See: ../mailbox/mailbox.txt for more information)
+
+ clocks:
+ type: object
+
+ properties:
+ compatible:
+ const: raspberrypi,firmware-clocks
+
+ "#clock-cells":
+ const: 1
+ description: >
+ The argument is the ID of the clocks contained by the
+ firmware messages.
+
+ required:
+ - compatible
+ - "#clock-cells"
+
+ additionalProperties: false
+
+required:
+ - compatible
+ - mboxes
+
+examples:
+ - |
+ firmware {
+ compatible = "raspberrypi,bcm2835-firmware", "simple-bus";
+ mboxes = <&mailbox>;
+
+ firmware_clocks: clocks {
+ compatible = "raspberrypi,firmware-clocks";
+ #clock-cells = <1>;
+ };
+ };
+...
diff --git a/Documentation/devicetree/bindings/arm/coresight.txt b/Documentation/devicetree/bindings/arm/coresight.txt
index 846f6da..d711676 100644
--- a/Documentation/devicetree/bindings/arm/coresight.txt
+++ b/Documentation/devicetree/bindings/arm/coresight.txt
@@ -108,6 +108,13 @@
* arm,cp14: must be present if the system accesses ETM/PTM management
registers via co-processor 14.
+ * qcom,skip-power-up: boolean. Indicates that an implementation can
+ skip powering up the trace unit. TRCPDCR.PU does not have to be set
+ on Qualcomm Technologies Inc. systems since ETMs are in the same power
+ domain as their CPU cores. This property is required to identify such
+ systems with hardware errata where the CPU watchdog counter is stopped
+ when TRCPDCR.PU is set.
+
* Optional property for TMC:
* arm,buffer-size: size of contiguous buffer space for TMC ETR
@@ -121,6 +128,12 @@
* interrupts : Exactly one SPI may be listed for reporting the address
error
+* Optional property for configurable replicators:
+
+ * qcom,replicator-loses-context: boolean. Indicates that the replicator
+ will lose register context when AMBA clock is removed which is observed
+ in some replicator designs.
+
Graph bindings for Coresight
-------------------------------
diff --git a/Documentation/devicetree/bindings/arm/freescale/fsl,scu.txt b/Documentation/devicetree/bindings/arm/freescale/fsl,scu.txt
index 7150474..6064d98 100644
--- a/Documentation/devicetree/bindings/arm/freescale/fsl,scu.txt
+++ b/Documentation/devicetree/bindings/arm/freescale/fsl,scu.txt
@@ -47,7 +47,7 @@
&lsio_mu1 1 2
&lsio_mu1 1 3
&lsio_mu1 3 3>;
- See Documentation/devicetree/bindings/mailbox/fsl,mu.txt
+ See Documentation/devicetree/bindings/mailbox/fsl,mu.yaml
for detailed mailbox binding.
Note: Each mu which supports general interrupt should have an alias correctly
@@ -176,7 +176,7 @@
"fsl,imx8qxp-sc-thermal"
followed by "fsl,imx-sc-thermal";
-- #thermal-sensor-cells: See Documentation/devicetree/bindings/thermal/thermal.txt
+- #thermal-sensor-cells: See Documentation/devicetree/bindings/thermal/thermal-sensor.yaml
for a description.
Example (imx8qxp):
diff --git a/Documentation/devicetree/bindings/arm/fsl.yaml b/Documentation/devicetree/bindings/arm/fsl.yaml
index 05906e2..f63895c 100644
--- a/Documentation/devicetree/bindings/arm/fsl.yaml
+++ b/Documentation/devicetree/bindings/arm/fsl.yaml
@@ -120,6 +120,8 @@
- fsl,imx6q-sabrelite
- fsl,imx6q-sabresd
- kontron,imx6q-samx6i # Kontron i.MX6 Dual/Quad SMARC Module
+ - prt,prti6q # Protonic PRTI6Q board
+ - prt,prtwd2 # Protonic WD2 board
- technexion,imx6q-pico-dwarf # TechNexion i.MX6Q Pico-Dwarf
- technexion,imx6q-pico-hobbit # TechNexion i.MX6Q Pico-Hobbit
- technexion,imx6q-pico-nymph # TechNexion i.MX6Q Pico-Nymph
@@ -172,6 +174,8 @@
- fsl,imx6dl-sabreauto # i.MX6 DualLite/Solo SABRE Automotive Board
- fsl,imx6dl-sabresd # i.MX6 DualLite SABRE Smart Device Board
- kontron,imx6dl-samx6i # Kontron i.MX6 Solo SMARC Module
+ - prt,prtrvt # Protonic RVT board
+ - prt,prtvt7 # Protonic VT7 board
- technexion,imx6dl-pico-dwarf # TechNexion i.MX6DL Pico-Dwarf
- technexion,imx6dl-pico-hobbit # TechNexion i.MX6DL Pico-Hobbit
- technexion,imx6dl-pico-nymph # TechNexion i.MX6DL Pico-Nymph
@@ -268,6 +272,7 @@
- armadeus,imx6ull-opos6uldev # OPOS6UL (i.MX6ULL) SoM on OPOS6ULDev board
- fsl,imx6ull-14x14-evk # i.MX6 UltraLiteLite 14x14 EVK Board
- kontron,imx6ull-n6411-som # Kontron N6411 SOM
+ - myir,imx6ull-mys-6ulx-eval # MYiR Tech iMX6ULL Evaluation Board
- toradex,colibri-imx6ull-eval # Colibri iMX6ULL Module on Colibri Evaluation Board
- toradex,colibri-imx6ull-wifi-eval # Colibri iMX6ULL Wi-Fi / Bluetooth Module on Colibri Evaluation Board
- const: fsl,imx6ull
diff --git a/Documentation/devicetree/bindings/arm/intel,keembay.yaml b/Documentation/devicetree/bindings/arm/intel,keembay.yaml
new file mode 100644
index 0000000..4d92578
--- /dev/null
+++ b/Documentation/devicetree/bindings/arm/intel,keembay.yaml
@@ -0,0 +1,19 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/arm/intel,keembay.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Keem Bay platform device tree bindings
+
+maintainers:
+ - Paul J. Murphy <paul.j.murphy@intel.com>
+ - Daniele Alessandrelli <daniele.alessandrelli@intel.com>
+
+properties:
+ compatible:
+ items:
+ - enum:
+ - intel,keembay-evm
+ - const: intel,keembay
+...
diff --git a/Documentation/devicetree/bindings/arm/keystone/ti,k3-sci-common.yaml b/Documentation/devicetree/bindings/arm/keystone/ti,k3-sci-common.yaml
new file mode 100644
index 0000000..7597bc93
--- /dev/null
+++ b/Documentation/devicetree/bindings/arm/keystone/ti,k3-sci-common.yaml
@@ -0,0 +1,44 @@
+# SPDX-License-Identifier: (GPL-2.0-only or BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/arm/keystone/ti,k3-sci-common.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Common K3 TI-SCI bindings
+
+maintainers:
+ - Nishanth Menon <nm@ti.com>
+
+description: |
+ The TI K3 family of SoCs usually have a central System Controller Processor
+ that is responsible for managing various SoC-level resources like clocks,
+ resets, interrupts etc. The communication with that processor is performed
+ through the TI-SCI protocol.
+
+ Each specific device management node like a clock controller node, a reset
+ controller node or an interrupt-controller node should define a common set
+ of properties that enables them to implement the corresponding functionality
+ over the TI-SCI protocol. The following are some of the common properties
+ needed by such individual nodes. The required properties for each device
+ management node is defined in the respective binding.
+
+properties:
+ ti,sci:
+ $ref: /schemas/types.yaml#/definitions/phandle
+ description:
+ Should be a phandle to the TI-SCI System Controller node
+
+ ti,sci-dev-id:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description: |
+ Should contain the TI-SCI device id corresponding to the device. Please
+ refer to the corresponding System Controller documentation for valid
+ values for the desired device.
+
+ ti,sci-proc-ids:
+ description: Should contain a single tuple of <proc_id host_id>.
+ $ref: /schemas/types.yaml#/definitions/uint32-array
+ items:
+ - description: TI-SCI processor id for the remote processor device
+ - description: TI-SCI host id to which processor control ownership
+ should be transferred to
diff --git a/Documentation/devicetree/bindings/arm/marvell/ap80x-system-controller.txt b/Documentation/devicetree/bindings/arm/marvell/ap80x-system-controller.txt
index 098d932..e315112 100644
--- a/Documentation/devicetree/bindings/arm/marvell/ap80x-system-controller.txt
+++ b/Documentation/devicetree/bindings/arm/marvell/ap80x-system-controller.txt
@@ -111,7 +111,7 @@
--------
For common binding part and usage, refer to
-Documentation/devicetree/bindings/thermal/thermal.txt
+Documentation/devicetree/bindings/thermal/thermal*.yaml
The thermal IP can probe the temperature all around the processor. It
may feature several channels, each of them wired to one sensor.
diff --git a/Documentation/devicetree/bindings/arm/marvell/cp110-system-controller.txt b/Documentation/devicetree/bindings/arm/marvell/cp110-system-controller.txt
index f982a8e..a21f770 100644
--- a/Documentation/devicetree/bindings/arm/marvell/cp110-system-controller.txt
+++ b/Documentation/devicetree/bindings/arm/marvell/cp110-system-controller.txt
@@ -203,7 +203,7 @@
critical point to any subnode of the thermal-zone node.
For common binding part and usage, refer to
-Documentation/devicetree/bindings/thermal/thermal.txt
+Documentation/devicetree/bindings/thermal/thermal*.yaml
Required properties:
- compatible: must be one of:
diff --git a/Documentation/devicetree/bindings/arm/mediatek.yaml b/Documentation/devicetree/bindings/arm/mediatek.yaml
index abc544d..3090896 100644
--- a/Documentation/devicetree/bindings/arm/mediatek.yaml
+++ b/Documentation/devicetree/bindings/arm/mediatek.yaml
@@ -114,4 +114,9 @@
- enum:
- mediatek,mt8183-evb
- const: mediatek,mt8183
+ - description: Google Krane (Lenovo IdeaPad Duet, 10e,...)
+ items:
+ - const: google,krane-sku176
+ - const: google,krane
+ - const: mediatek,mt8183
...
diff --git a/Documentation/devicetree/bindings/arm/microchip,sparx5.yaml b/Documentation/devicetree/bindings/arm/microchip,sparx5.yaml
new file mode 100644
index 0000000..ecf6fa1
--- /dev/null
+++ b/Documentation/devicetree/bindings/arm/microchip,sparx5.yaml
@@ -0,0 +1,65 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/arm/microchip,sparx5.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Microchip Sparx5 Boards Device Tree Bindings
+
+maintainers:
+ - Lars Povlsen <lars.povlsen@microchip.com>
+
+description: |+
+ The Microchip Sparx5 SoC is a ARMv8-based used in a family of
+ gigabit TSN-capable gigabit switches.
+
+ The SparX-5 Ethernet switch family provides a rich set of switching
+ features such as advanced TCAM-based VLAN and QoS processing
+ enabling delivery of differentiated services, and security through
+ TCAM-based frame processing using versatile content aware processor
+ (VCAP)
+
+properties:
+ $nodename:
+ const: '/'
+ compatible:
+ oneOf:
+ - description: The Sparx5 pcb125 board is a modular board,
+ which has both spi-nor and eMMC storage. The modular design
+ allows for connection of different network ports.
+ items:
+ - const: microchip,sparx5-pcb125
+ - const: microchip,sparx5
+
+ - description: The Sparx5 pcb134 is a pizzabox form factor
+ gigabit switch with 20 SFP ports. It features spi-nor and
+ either spi-nand or eMMC storage (mount option).
+ items:
+ - const: microchip,sparx5-pcb134
+ - const: microchip,sparx5
+
+ - description: The Sparx5 pcb135 is a pizzabox form factor
+ gigabit switch with 48+4 Cu ports. It features spi-nor and
+ either spi-nand or eMMC storage (mount option).
+ items:
+ - const: microchip,sparx5-pcb135
+ - const: microchip,sparx5
+
+ axi@600000000:
+ type: object
+ description: the root node in the Sparx5 platforms must contain
+ an axi bus child node. They are always at physical address
+ 0x600000000 in all the Sparx5 variants.
+ properties:
+ compatible:
+ items:
+ - const: simple-bus
+
+ required:
+ - compatible
+
+required:
+ - compatible
+ - axi@600000000
+
+...
diff --git a/Documentation/devicetree/bindings/arm/mstar/mstar,l3bridge.yaml b/Documentation/devicetree/bindings/arm/mstar/mstar,l3bridge.yaml
new file mode 100644
index 0000000..6816bd6
--- /dev/null
+++ b/Documentation/devicetree/bindings/arm/mstar/mstar,l3bridge.yaml
@@ -0,0 +1,44 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+# Copyright 2020 thingy.jp.
+%YAML 1.2
+---
+$id: "http://devicetree.org/schemas/arm/mstar/mstar,l3bridge.yaml#"
+$schema: "http://devicetree.org/meta-schemas/core.yaml#"
+
+title: MStar/SigmaStar Armv7 SoC l3bridge
+
+maintainers:
+ - Daniel Palmer <daniel@thingy.jp>
+
+description: |
+ MStar/SigmaStar's Armv7 SoCs have a pipeline in the interface
+ between the CPU and memory. This means that before DMA capable
+ devices are allowed to run the pipeline must be flushed to ensure
+ everything is in memory.
+
+ The l3bridge region contains registers that allow such a flush
+ to be triggered.
+
+ This node is used by the platform code to find where the registers
+ are and install a barrier that triggers the required pipeline flush.
+
+properties:
+ compatible:
+ items:
+ - const: mstar,l3bridge
+
+ reg:
+ maxItems: 1
+
+required:
+ - compatible
+ - reg
+
+additionalProperties: false
+
+examples:
+ - |
+ l3bridge: l3bridge@1f204400 {
+ compatible = "mstar,l3bridge";
+ reg = <0x1f204400 0x200>;
+ };
diff --git a/Documentation/devicetree/bindings/arm/mstar/mstar.yaml b/Documentation/devicetree/bindings/arm/mstar/mstar.yaml
new file mode 100644
index 0000000..c2f980b
--- /dev/null
+++ b/Documentation/devicetree/bindings/arm/mstar/mstar.yaml
@@ -0,0 +1,33 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/arm/mstar/mstar.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: MStar platforms device tree bindings
+
+maintainers:
+ - Daniel Palmer <daniel@thingy.jp>
+
+properties:
+ $nodename:
+ const: '/'
+ compatible:
+ oneOf:
+ - description: infinity boards
+ items:
+ - enum:
+ - thingyjp,breadbee-crust # thingy.jp BreadBee Crust
+ - const: mstar,infinity
+
+ - description: infinity3 boards
+ items:
+ - enum:
+ - thingyjp,breadbee # thingy.jp BreadBee
+ - const: mstar,infinity3
+
+ - description: mercury5 boards
+ items:
+ - enum:
+ - 70mai,midrived08 # 70mai midrive d08
+ - const: mstar,mercury5
diff --git a/Documentation/devicetree/bindings/arm/nvidia,tegra194-ccplex.yaml b/Documentation/devicetree/bindings/arm/nvidia,tegra194-ccplex.yaml
new file mode 100644
index 0000000..1043e4b
--- /dev/null
+++ b/Documentation/devicetree/bindings/arm/nvidia,tegra194-ccplex.yaml
@@ -0,0 +1,69 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: "http://devicetree.org/schemas/arm/nvidia,tegra194-ccplex.yaml#"
+$schema: "http://devicetree.org/meta-schemas/core.yaml#"
+
+title: NVIDIA Tegra194 CPU Complex device tree bindings
+
+maintainers:
+ - Thierry Reding <thierry.reding@gmail.com>
+ - Jonathan Hunter <jonathanh@nvidia.com>
+ - Sumit Gupta <sumitg@nvidia.com>
+
+description: |+
+ Tegra194 SOC has homogeneous architecture where each cluster has two
+ symmetric cores. Compatible string in "cpus" node represents the CPU
+ Complex having all clusters.
+
+properties:
+ $nodename:
+ const: cpus
+
+ compatible:
+ enum:
+ - nvidia,tegra194-ccplex
+
+ nvidia,bpmp:
+ $ref: '/schemas/types.yaml#/definitions/phandle'
+ description: |
+ Specifies the bpmp node that needs to be queried to get
+ operating point data for all CPUs.
+
+examples:
+ - |
+ cpus {
+ compatible = "nvidia,tegra194-ccplex";
+ nvidia,bpmp = <&bpmp>;
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ cpu0_0: cpu@0 {
+ compatible = "nvidia,tegra194-carmel";
+ device_type = "cpu";
+ reg = <0x0>;
+ enable-method = "psci";
+ };
+
+ cpu0_1: cpu@1 {
+ compatible = "nvidia,tegra194-carmel";
+ device_type = "cpu";
+ reg = <0x001>;
+ enable-method = "psci";
+ };
+
+ cpu1_0: cpu@100 {
+ compatible = "nvidia,tegra194-carmel";
+ device_type = "cpu";
+ reg = <0x100>;
+ enable-method = "psci";
+ };
+
+ cpu1_1: cpu@101 {
+ compatible = "nvidia,tegra194-carmel";
+ device_type = "cpu";
+ reg = <0x101>;
+ enable-method = "psci";
+ };
+ };
+...
diff --git a/Documentation/devicetree/bindings/arm/renesas.yaml b/Documentation/devicetree/bindings/arm/renesas.yaml
index b7d2e92..0d4dabb 100644
--- a/Documentation/devicetree/bindings/arm/renesas.yaml
+++ b/Documentation/devicetree/bindings/arm/renesas.yaml
@@ -118,6 +118,7 @@
items:
- enum:
- hoperun,hihope-rzg2m # HopeRun HiHope RZ/G2M platform
+ - beacon,beacon-rzg2m # Beacon EmbeddedWorks RZ/G2M Kit
- const: renesas,r8a774a1
- items:
@@ -150,6 +151,18 @@
- const: si-linux,cat874
- const: renesas,r8a774c0
+ - description: RZ/G2H (R8A774E1)
+ items:
+ - enum:
+ - hoperun,hihope-rzg2h # HopeRun HiHope RZ/G2H platform
+ - const: renesas,r8a774e1
+
+ - items:
+ - enum:
+ - hoperun,hihope-rzg2-ex # HopeRun expansion board for HiHope RZ/G2 platforms
+ - const: hoperun,hihope-rzg2h
+ - const: renesas,r8a774e1
+
- description: R-Car M1A (R8A77781)
items:
- enum:
diff --git a/Documentation/devicetree/bindings/arm/rockchip.yaml b/Documentation/devicetree/bindings/arm/rockchip.yaml
index d4a4045..db2e3579 100644
--- a/Documentation/devicetree/bindings/arm/rockchip.yaml
+++ b/Documentation/devicetree/bindings/arm/rockchip.yaml
@@ -435,6 +435,12 @@
- const: radxa,rockpi4
- const: rockchip,rk3399
+ - description: Radxa ROCK Pi N8
+ items:
+ - const: radxa,rockpi-n8
+ - const: vamrs,rk3288-vmarc-som
+ - const: rockchip,rk3288
+
- description: Radxa ROCK Pi N10
items:
- const: radxa,rockpi-n10
diff --git a/Documentation/devicetree/bindings/arm/stm32/st,stm32-syscon.yaml b/Documentation/devicetree/bindings/arm/stm32/st,stm32-syscon.yaml
index cf5db5e..6f1cd01 100644
--- a/Documentation/devicetree/bindings/arm/stm32/st,stm32-syscon.yaml
+++ b/Documentation/devicetree/bindings/arm/stm32/st,stm32-syscon.yaml
@@ -16,6 +16,9 @@
- items:
- enum:
- st,stm32mp157-syscfg
+ - st,stm32mp151-pwr-mcu
+ - st,stm32-syscfg
+ - st,stm32-power-config
- const: syscon
reg:
@@ -27,7 +30,16 @@
required:
- compatible
- reg
- - clocks
+
+if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - st,stm32mp157-syscfg
+then:
+ required:
+ - clocks
additionalProperties: false
diff --git a/Documentation/devicetree/bindings/arm/sunxi.yaml b/Documentation/devicetree/bindings/arm/sunxi.yaml
index 87817ff..efc9118 100644
--- a/Documentation/devicetree/bindings/arm/sunxi.yaml
+++ b/Documentation/devicetree/bindings/arm/sunxi.yaml
@@ -657,6 +657,11 @@
- const: pine64,pinephone-1.1
- const: allwinner,sun50i-a64
+ - description: Pine64 PinePhone (1.2)
+ items:
+ - const: pine64,pinephone-1.2
+ - const: allwinner,sun50i-a64
+
- description: Pine64 PineTab
items:
- const: pine64,pinetab
diff --git a/Documentation/devicetree/bindings/arm/tegra.yaml b/Documentation/devicetree/bindings/arm/tegra.yaml
index 60b38eb..e0b3deb 100644
--- a/Documentation/devicetree/bindings/arm/tegra.yaml
+++ b/Documentation/devicetree/bindings/arm/tegra.yaml
@@ -35,6 +35,9 @@
- const: toradex,colibri_t20
- const: nvidia,tegra20
- items:
+ - const: acer,picasso
+ - const: nvidia,tegra20
+ - items:
- enum:
- nvidia,beaver
- const: nvidia,tegra30
@@ -60,6 +63,13 @@
- const: toradex,colibri_t30
- const: nvidia,tegra30
- items:
+ - const: asus,grouper
+ - const: nvidia,tegra30
+ - items:
+ - const: asus,tilapia
+ - const: asus,grouper
+ - const: nvidia,tegra30
+ - items:
- enum:
- nvidia,dalmore
- nvidia,roth
@@ -101,3 +111,11 @@
- enum:
- nvidia,p2972-0000
- const: nvidia,tegra194
+ - description: Jetson Xavier NX
+ items:
+ - const: nvidia,p3668-0000
+ - const: nvidia,tegra194
+ - description: Jetson Xavier NX Developer Kit
+ items:
+ - const: nvidia,p3509-0000+p3668-0000
+ - const: nvidia,tegra194
diff --git a/Documentation/devicetree/bindings/bus/mti,mips-cdmm.yaml b/Documentation/devicetree/bindings/bus/mti,mips-cdmm.yaml
new file mode 100644
index 0000000..9cc2d5f
--- /dev/null
+++ b/Documentation/devicetree/bindings/bus/mti,mips-cdmm.yaml
@@ -0,0 +1,35 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/bus/mti,mips-cdmm.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: MIPS Common Device Memory Map
+
+description: |
+ Defines a location of the MIPS Common Device Memory Map registers.
+
+maintainers:
+ - James Hogan <jhogan@kernel.org>
+
+properties:
+ compatible:
+ const: mti,mips-cdmm
+
+ reg:
+ description: |
+ Base address and size of an unoccupied memory region, which will be
+ used to map the MIPS CDMM registers block.
+ maxItems: 1
+
+required:
+ - compatible
+ - reg
+
+examples:
+ - |
+ cdmm@1bde8000 {
+ compatible = "mti,mips-cdmm";
+ reg = <0x1bde8000 0x8000>;
+ };
+...
diff --git a/Documentation/devicetree/bindings/bus/socionext,uniphier-system-bus.yaml b/Documentation/devicetree/bindings/bus/socionext,uniphier-system-bus.yaml
index c4c9119..a0c6c5d 100644
--- a/Documentation/devicetree/bindings/bus/socionext,uniphier-system-bus.yaml
+++ b/Documentation/devicetree/bindings/bus/socionext,uniphier-system-bus.yaml
@@ -80,14 +80,14 @@
ranges = <1 0x00000000 0x42000000 0x02000000>,
<5 0x00000000 0x46000000 0x01000000>;
- ethernet@1,01f00000 {
+ ethernet@1,1f00000 {
compatible = "smsc,lan9115";
reg = <1 0x01f00000 0x1000>;
interrupts = <0 48 4>;
phy-mode = "mii";
};
- uart@5,00200000 {
+ serial@5,200000 {
compatible = "ns16550a";
reg = <5 0x00200000 0x20>;
interrupts = <0 49 4>;
diff --git a/Documentation/devicetree/bindings/clock/brcm,bcm2711-dvp.yaml b/Documentation/devicetree/bindings/clock/brcm,bcm2711-dvp.yaml
new file mode 100644
index 0000000..08543ec
--- /dev/null
+++ b/Documentation/devicetree/bindings/clock/brcm,bcm2711-dvp.yaml
@@ -0,0 +1,47 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/clock/brcm,bcm2711-dvp.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Broadcom BCM2711 HDMI DVP Device Tree Bindings
+
+maintainers:
+ - Maxime Ripard <mripard@kernel.org>
+
+properties:
+ "#clock-cells":
+ const: 1
+
+ "#reset-cells":
+ const: 1
+
+ compatible:
+ const: brcm,brcm2711-dvp
+
+ reg:
+ maxItems: 1
+
+ clocks:
+ maxItems: 1
+
+required:
+ - "#clock-cells"
+ - "#reset-cells"
+ - compatible
+ - reg
+ - clocks
+
+additionalProperties: false
+
+examples:
+ - |
+ dvp: clock@7ef00000 {
+ compatible = "brcm,brcm2711-dvp";
+ reg = <0x7ef00000 0x10>;
+ clocks = <&clk_108MHz>;
+ #clock-cells = <1>;
+ #reset-cells = <1>;
+ };
+
+...
diff --git a/Documentation/devicetree/bindings/clock/brcm,bcm63xx-clocks.txt b/Documentation/devicetree/bindings/clock/brcm,bcm63xx-clocks.txt
index 3041657..3e7ca55 100644
--- a/Documentation/devicetree/bindings/clock/brcm,bcm63xx-clocks.txt
+++ b/Documentation/devicetree/bindings/clock/brcm,bcm63xx-clocks.txt
@@ -3,6 +3,8 @@
Required properties:
- compatible: must be one of:
"brcm,bcm3368-clocks"
+ "brcm,bcm6318-clocks"
+ "brcm,bcm6318-ubus-clocks"
"brcm,bcm6328-clocks"
"brcm,bcm6358-clocks"
"brcm,bcm6362-clocks"
diff --git a/Documentation/devicetree/bindings/clock/clock-bindings.txt b/Documentation/devicetree/bindings/clock/clock-bindings.txt
index 8a55fdc..f2ea53832 100644
--- a/Documentation/devicetree/bindings/clock/clock-bindings.txt
+++ b/Documentation/devicetree/bindings/clock/clock-bindings.txt
@@ -9,7 +9,7 @@
output on a device. The length of a clock specifier is defined by the
value of a #clock-cells property in the clock provider node.
-[1] http://patchwork.ozlabs.org/patch/31551/
+[1] https://patchwork.ozlabs.org/patch/31551/
==Clock providers==
diff --git a/Documentation/devicetree/bindings/clock/idt,versaclock5.txt b/Documentation/devicetree/bindings/clock/idt,versaclock5.txt
deleted file mode 100644
index bcff681..0000000
--- a/Documentation/devicetree/bindings/clock/idt,versaclock5.txt
+++ /dev/null
@@ -1,92 +0,0 @@
-Binding for IDT VersaClock 5,6 programmable i2c clock generators.
-
-The IDT VersaClock 5 and VersaClock 6 are programmable i2c clock
-generators providing from 3 to 12 output clocks.
-
-==I2C device node==
-
-Required properties:
-- compatible: shall be one of
- "idt,5p49v5923"
- "idt,5p49v5925"
- "idt,5p49v5933"
- "idt,5p49v5935"
- "idt,5p49v6901"
- "idt,5p49v6965"
-- reg: i2c device address, shall be 0x68 or 0x6a.
-- #clock-cells: from common clock binding; shall be set to 1.
-- clocks: from common clock binding; list of parent clock handles,
- - 5p49v5923 and
- 5p49v5925 and
- 5p49v6901: (required) either or both of XTAL or CLKIN
- reference clock.
- - 5p49v5933 and
- - 5p49v5935: (optional) property not present (internal
- Xtal used) or CLKIN reference
- clock.
-- clock-names: from common clock binding; clock input names, can be
- - 5p49v5923 and
- 5p49v5925 and
- 5p49v6901: (required) either or both of "xin", "clkin".
- - 5p49v5933 and
- - 5p49v5935: (optional) property not present or "clkin".
-
-==Mapping between clock specifier and physical pins==
-
-When referencing the provided clock in the DT using phandle and
-clock specifier, the following mapping applies:
-
-5P49V5923:
- 0 -- OUT0_SEL_I2CB
- 1 -- OUT1
- 2 -- OUT2
-
-5P49V5933:
- 0 -- OUT0_SEL_I2CB
- 1 -- OUT1
- 2 -- OUT4
-
-5P49V5925 and
-5P49V5935:
- 0 -- OUT0_SEL_I2CB
- 1 -- OUT1
- 2 -- OUT2
- 3 -- OUT3
- 4 -- OUT4
-
-5P49V6901:
- 0 -- OUT0_SEL_I2CB
- 1 -- OUT1
- 2 -- OUT2
- 3 -- OUT3
- 4 -- OUT4
-
-==Example==
-
-/* 25MHz reference crystal */
-ref25: ref25m {
- compatible = "fixed-clock";
- #clock-cells = <0>;
- clock-frequency = <25000000>;
-};
-
-i2c-master-node {
-
- /* IDT 5P49V5923 i2c clock generator */
- vc5: clock-generator@6a {
- compatible = "idt,5p49v5923";
- reg = <0x6a>;
- #clock-cells = <1>;
-
- /* Connect XIN input to 25MHz reference */
- clocks = <&ref25m>;
- clock-names = "xin";
- };
-};
-
-/* Consumer referencing the 5P49V5923 pin OUT1 */
-consumer {
- ...
- clocks = <&vc5 1>;
- ...
-}
diff --git a/Documentation/devicetree/bindings/clock/idt,versaclock5.yaml b/Documentation/devicetree/bindings/clock/idt,versaclock5.yaml
new file mode 100644
index 0000000..3d4e168
--- /dev/null
+++ b/Documentation/devicetree/bindings/clock/idt,versaclock5.yaml
@@ -0,0 +1,154 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/clock/idt,versaclock5.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Binding for IDT VersaClock 5 and 6 programmable I2C clock generators
+
+description: |
+ The IDT VersaClock 5 and VersaClock 6 are programmable I2C
+ clock generators providing from 3 to 12 output clocks.
+
+ When referencing the provided clock in the DT using phandle and clock
+ specifier, the following mapping applies:
+
+ - 5P49V5923:
+ 0 -- OUT0_SEL_I2CB
+ 1 -- OUT1
+ 2 -- OUT2
+
+ - 5P49V5933:
+ 0 -- OUT0_SEL_I2CB
+ 1 -- OUT1
+ 2 -- OUT4
+
+ - other parts:
+ 0 -- OUT0_SEL_I2CB
+ 1 -- OUT1
+ 2 -- OUT2
+ 3 -- OUT3
+ 4 -- OUT4
+
+maintainers:
+ - Luca Ceresoli <luca@lucaceresoli.net>
+
+properties:
+ compatible:
+ enum:
+ - idt,5p49v5923
+ - idt,5p49v5925
+ - idt,5p49v5933
+ - idt,5p49v5935
+ - idt,5p49v6901
+ - idt,5p49v6965
+
+ reg:
+ description: I2C device address
+ enum: [ 0x68, 0x6a ]
+
+ '#clock-cells':
+ const: 1
+
+patternProperties:
+ "^OUT[1-4]$":
+ type: object
+ description:
+ Description of one of the outputs (OUT1..OUT4). See "Clock1 Output
+ Configuration" in the Versaclock 5/6/6E Family Register Description
+ and Programming Guide.
+ properties:
+ idt,mode:
+ description:
+ The output drive mode. Values defined in dt-bindings/clk/versaclock.h
+ $ref: /schemas/types.yaml#/definitions/uint32
+ minimum: 0
+ maximum: 6
+ idt,voltage-microvolt:
+ description: The output drive voltage.
+ enum: [ 1800000, 2500000, 3300000 ]
+ idt,slew-percent:
+ description: The Slew rate control for CMOS single-ended.
+ $ref: /schemas/types.yaml#/definitions/uint32
+ enum: [ 80, 85, 90, 100 ]
+
+required:
+ - compatible
+ - reg
+ - '#clock-cells'
+
+allOf:
+ - if:
+ properties:
+ compatible:
+ enum:
+ - idt,5p49v5933
+ - idt,5p49v5935
+ then:
+ # Devices with builtin crystal + optional external input
+ properties:
+ clock-names:
+ const: clkin
+ clocks:
+ maxItems: 1
+ else:
+ # Devices without builtin crystal
+ properties:
+ clock-names:
+ minItems: 1
+ maxItems: 2
+ items:
+ enum: [ xin, clkin ]
+ clocks:
+ minItems: 1
+ maxItems: 2
+ required:
+ - clock-names
+ - clocks
+
+examples:
+ - |
+ #include <dt-bindings/clk/versaclock.h>
+
+ /* 25MHz reference crystal */
+ ref25: ref25m {
+ compatible = "fixed-clock";
+ #clock-cells = <0>;
+ clock-frequency = <25000000>;
+ };
+
+ i2c@0 {
+ reg = <0x0 0x100>;
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ /* IDT 5P49V5923 I2C clock generator */
+ vc5: clock-generator@6a {
+ compatible = "idt,5p49v5923";
+ reg = <0x6a>;
+ #clock-cells = <1>;
+
+ /* Connect XIN input to 25MHz reference */
+ clocks = <&ref25m>;
+ clock-names = "xin";
+
+ OUT1 {
+ idt,drive-mode = <VC5_CMOSD>;
+ idt,voltage-microvolts = <1800000>;
+ idt,slew-percent = <80>;
+ };
+
+ OUT4 {
+ idt,drive-mode = <VC5_LVDS>;
+ };
+ };
+ };
+
+ /* Consumer referencing the 5P49V5923 pin OUT1 */
+ consumer {
+ /* ... */
+ clocks = <&vc5 1>;
+ /* ... */
+ };
+
+...
diff --git a/Documentation/devicetree/bindings/clock/imx27-clock.yaml b/Documentation/devicetree/bindings/clock/imx27-clock.yaml
index b5f3ed0..a753654 100644
--- a/Documentation/devicetree/bindings/clock/imx27-clock.yaml
+++ b/Documentation/devicetree/bindings/clock/imx27-clock.yaml
@@ -7,7 +7,7 @@
title: Clock bindings for Freescale i.MX27
maintainers:
- - Fabio Estevam <fabio.estevam@freescale.com>
+ - Fabio Estevam <fabio.estevam@nxp.com>
description: |
The clock consumer should specify the desired clock by having the clock
diff --git a/Documentation/devicetree/bindings/clock/imx31-clock.yaml b/Documentation/devicetree/bindings/clock/imx31-clock.yaml
index 1b6f75d..a25a374 100644
--- a/Documentation/devicetree/bindings/clock/imx31-clock.yaml
+++ b/Documentation/devicetree/bindings/clock/imx31-clock.yaml
@@ -7,7 +7,7 @@
title: Clock bindings for Freescale i.MX31
maintainers:
- - Fabio Estevam <fabio.estevam@freescale.com>
+ - Fabio Estevam <fabio.estevam@nxp.com>
description: |
The clock consumer should specify the desired clock by having the clock
diff --git a/Documentation/devicetree/bindings/clock/imx35-clock.yaml b/Documentation/devicetree/bindings/clock/imx35-clock.yaml
index bd871da..3e20cca 100644
--- a/Documentation/devicetree/bindings/clock/imx35-clock.yaml
+++ b/Documentation/devicetree/bindings/clock/imx35-clock.yaml
@@ -130,7 +130,7 @@
#clock-cells = <1>;
};
- esdhc@53fb4000 {
+ mmc@53fb4000 {
compatible = "fsl,imx35-esdhc";
reg = <0x53fb4000 0x4000>;
interrupts = <7>;
diff --git a/Documentation/devicetree/bindings/clock/imx5-clock.yaml b/Documentation/devicetree/bindings/clock/imx5-clock.yaml
index f5c2b3d..4d9e7c7 100644
--- a/Documentation/devicetree/bindings/clock/imx5-clock.yaml
+++ b/Documentation/devicetree/bindings/clock/imx5-clock.yaml
@@ -7,7 +7,7 @@
title: Clock bindings for Freescale i.MX5
maintainers:
- - Fabio Estevam <fabio.estevam@freescale.com>
+ - Fabio Estevam <fabio.estevam@nxp.com>
description: |
The clock consumer should specify the desired clock by having the clock
diff --git a/Documentation/devicetree/bindings/clock/imx7ulp-clock.txt b/Documentation/devicetree/bindings/clock/imx7ulp-clock.txt
deleted file mode 100644
index 93d89ad..0000000
--- a/Documentation/devicetree/bindings/clock/imx7ulp-clock.txt
+++ /dev/null
@@ -1,103 +0,0 @@
-* Clock bindings for Freescale i.MX7ULP
-
-i.MX7ULP Clock functions are under joint control of the System
-Clock Generation (SCG) modules, Peripheral Clock Control (PCC)
-modules, and Core Mode Controller (CMC)1 blocks
-
-The clocking scheme provides clear separation between M4 domain
-and A7 domain. Except for a few clock sources shared between two
-domains, such as the System Oscillator clock, the Slow IRC (SIRC),
-and and the Fast IRC clock (FIRCLK), clock sources and clock
-management are separated and contained within each domain.
-
-M4 clock management consists of SCG0, PCC0, PCC1, and CMC0 modules.
-A7 clock management consists of SCG1, PCC2, PCC3, and CMC1 modules.
-
-Note: this binding doc is only for A7 clock domain.
-
-System Clock Generation (SCG) modules:
----------------------------------------------------------------------
-The System Clock Generation (SCG) is responsible for clock generation
-and distribution across this device. Functions performed by the SCG
-include: clock reference selection, generation of clock used to derive
-processor, system, peripheral bus and external memory interface clocks,
-source selection for peripheral clocks and control of power saving
-clock gating mode.
-
-Required properties:
-
-- compatible: Should be "fsl,imx7ulp-scg1".
-- reg : Should contain registers location and length.
-- #clock-cells: Should be <1>.
-- clocks: Should contain the fixed input clocks.
-- clock-names: Should contain the following clock names:
- "rosc", "sosc", "sirc", "firc", "upll", "mpll".
-
-Peripheral Clock Control (PCC) modules:
----------------------------------------------------------------------
-The Peripheral Clock Control (PCC) is responsible for clock selection,
-optional division and clock gating mode for peripherals in their
-respected power domain
-
-Required properties:
-- compatible: Should be one of:
- "fsl,imx7ulp-pcc2",
- "fsl,imx7ulp-pcc3".
-- reg : Should contain registers location and length.
-- #clock-cells: Should be <1>.
-- clocks: Should contain the fixed input clocks.
-- clock-names: Should contain the following clock names:
- "nic1_bus_clk", "nic1_clk", "ddr_clk", "apll_pfd2",
- "apll_pfd1", "apll_pfd0", "upll", "sosc_bus_clk",
- "mpll", "firc_bus_clk", "rosc", "spll_bus_clk";
-
-The clock consumer should specify the desired clock by having the clock
-ID in its "clocks" phandle cell.
-See include/dt-bindings/clock/imx7ulp-clock.h
-for the full list of i.MX7ULP clock IDs of each module.
-
-Examples:
-
-#include <dt-bindings/clock/imx7ulp-clock.h>
-
-scg1: scg1@403e0000 {
- compatible = "fsl,imx7ulp-scg1;
- reg = <0x403e0000 0x10000>;
- clocks = <&rosc>, <&sosc>, <&sirc>,
- <&firc>, <&upll>, <&mpll>;
- clock-names = "rosc", "sosc", "sirc",
- "firc", "upll", "mpll";
- #clock-cells = <1>;
-};
-
-pcc2: pcc2@403f0000 {
- compatible = "fsl,imx7ulp-pcc2";
- reg = <0x403f0000 0x10000>;
- #clock-cells = <1>;
- clocks = <&scg1 IMX7ULP_CLK_NIC1_BUS_DIV>,
- <&scg1 IMX7ULP_CLK_NIC1_DIV>,
- <&scg1 IMX7ULP_CLK_DDR_DIV>,
- <&scg1 IMX7ULP_CLK_APLL_PFD2>,
- <&scg1 IMX7ULP_CLK_APLL_PFD1>,
- <&scg1 IMX7ULP_CLK_APLL_PFD0>,
- <&scg1 IMX7ULP_CLK_UPLL>,
- <&scg1 IMX7ULP_CLK_SOSC_BUS_CLK>,
- <&scg1 IMX7ULP_CLK_FIRC_BUS_CLK>,
- <&scg1 IMX7ULP_CLK_ROSC>,
- <&scg1 IMX7ULP_CLK_SPLL_BUS_CLK>;
- clock-names = "nic1_bus_clk", "nic1_clk", "ddr_clk",
- "apll_pfd2", "apll_pfd1", "apll_pfd0",
- "upll", "sosc_bus_clk", "mpll",
- "firc_bus_clk", "rosc", "spll_bus_clk";
-};
-
-usdhc1: usdhc@40380000 {
- compatible = "fsl,imx7ulp-usdhc";
- reg = <0x40380000 0x10000>;
- interrupts = <GIC_SPI 43 IRQ_TYPE_LEVEL_HIGH>;
- clocks = <&scg1 IMX7ULP_CLK_NIC1_BUS_DIV>,
- <&scg1 IMX7ULP_CLK_NIC1_DIV>,
- <&pcc2 IMX7ULP_CLK_USDHC1>;
- clock-names ="ipg", "ahb", "per";
- bus-width = <4>;
-};
diff --git a/Documentation/devicetree/bindings/clock/imx7ulp-pcc-clock.yaml b/Documentation/devicetree/bindings/clock/imx7ulp-pcc-clock.yaml
new file mode 100644
index 0000000..7caf5ce
--- /dev/null
+++ b/Documentation/devicetree/bindings/clock/imx7ulp-pcc-clock.yaml
@@ -0,0 +1,121 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/clock/imx7ulp-pcc-clock.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Clock bindings for Freescale i.MX7ULP Peripheral Clock Control (PCC) modules
+
+maintainers:
+ - A.s. Dong <aisheng.dong@nxp.com>
+
+description: |
+ i.MX7ULP Clock functions are under joint control of the System
+ Clock Generation (SCG) modules, Peripheral Clock Control (PCC)
+ modules, and Core Mode Controller (CMC)1 blocks
+
+ The clocking scheme provides clear separation between M4 domain
+ and A7 domain. Except for a few clock sources shared between two
+ domains, such as the System Oscillator clock, the Slow IRC (SIRC),
+ and and the Fast IRC clock (FIRCLK), clock sources and clock
+ management are separated and contained within each domain.
+
+ M4 clock management consists of SCG0, PCC0, PCC1, and CMC0 modules.
+ A7 clock management consists of SCG1, PCC2, PCC3, and CMC1 modules.
+
+ Note: this binding doc is only for A7 clock domain.
+
+ The Peripheral Clock Control (PCC) is responsible for clock selection,
+ optional division and clock gating mode for peripherals in their
+ respected power domain.
+
+ The clock consumer should specify the desired clock by having the clock
+ ID in its "clocks" phandle cell.
+ See include/dt-bindings/clock/imx7ulp-clock.h for the full list of
+ i.MX7ULP clock IDs of each module.
+
+properties:
+ compatible:
+ enum:
+ - fsl,imx7ulp-pcc2
+ - fsl,imx7ulp-pcc3
+
+ reg:
+ maxItems: 1
+
+ '#clock-cells':
+ const: 1
+
+ clocks:
+ items:
+ - description: nic1 bus clock
+ - description: nic1 clock
+ - description: ddr clock
+ - description: apll pfd2
+ - description: apll pfd1
+ - description: apll pfd0
+ - description: usb pll
+ - description: system osc bus clock
+ - description: fast internal reference clock bus
+ - description: rtc osc
+ - description: system pll bus clock
+
+ clock-names:
+ items:
+ - const: nic1_bus_clk
+ - const: nic1_clk
+ - const: ddr_clk
+ - const: apll_pfd2
+ - const: apll_pfd1
+ - const: apll_pfd0
+ - const: upll
+ - const: sosc_bus_clk
+ - const: firc_bus_clk
+ - const: rosc
+ - const: spll_bus_clk
+
+required:
+ - compatible
+ - reg
+ - '#clock-cells'
+ - clocks
+ - clock-names
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/clock/imx7ulp-clock.h>
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+
+ clock-controller@403f0000 {
+ compatible = "fsl,imx7ulp-pcc2";
+ reg = <0x403f0000 0x10000>;
+ #clock-cells = <1>;
+ clocks = <&scg1 IMX7ULP_CLK_NIC1_BUS_DIV>,
+ <&scg1 IMX7ULP_CLK_NIC1_DIV>,
+ <&scg1 IMX7ULP_CLK_DDR_DIV>,
+ <&scg1 IMX7ULP_CLK_APLL_PFD2>,
+ <&scg1 IMX7ULP_CLK_APLL_PFD1>,
+ <&scg1 IMX7ULP_CLK_APLL_PFD0>,
+ <&scg1 IMX7ULP_CLK_UPLL>,
+ <&scg1 IMX7ULP_CLK_SOSC_BUS_CLK>,
+ <&scg1 IMX7ULP_CLK_FIRC_BUS_CLK>,
+ <&scg1 IMX7ULP_CLK_ROSC>,
+ <&scg1 IMX7ULP_CLK_SPLL_BUS_CLK>;
+ clock-names = "nic1_bus_clk", "nic1_clk", "ddr_clk",
+ "apll_pfd2", "apll_pfd1", "apll_pfd0",
+ "upll", "sosc_bus_clk", "firc_bus_clk",
+ "rosc", "spll_bus_clk";
+ };
+
+ mmc@40380000 {
+ compatible = "fsl,imx7ulp-usdhc";
+ reg = <0x40380000 0x10000>;
+ interrupts = <GIC_SPI 43 IRQ_TYPE_LEVEL_HIGH>;
+ clocks = <&scg1 IMX7ULP_CLK_NIC1_BUS_DIV>,
+ <&scg1 IMX7ULP_CLK_NIC1_DIV>,
+ <&pcc2 IMX7ULP_CLK_USDHC1>;
+ clock-names ="ipg", "ahb", "per";
+ bus-width = <4>;
+ };
diff --git a/Documentation/devicetree/bindings/clock/imx7ulp-scg-clock.yaml b/Documentation/devicetree/bindings/clock/imx7ulp-scg-clock.yaml
new file mode 100644
index 0000000..ee8efb4
--- /dev/null
+++ b/Documentation/devicetree/bindings/clock/imx7ulp-scg-clock.yaml
@@ -0,0 +1,99 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/clock/imx7ulp-scg-clock.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Clock bindings for Freescale i.MX7ULP System Clock Generation (SCG) modules
+
+maintainers:
+ - A.s. Dong <aisheng.dong@nxp.com>
+
+description: |
+ i.MX7ULP Clock functions are under joint control of the System
+ Clock Generation (SCG) modules, Peripheral Clock Control (PCC)
+ modules, and Core Mode Controller (CMC)1 blocks
+
+ The clocking scheme provides clear separation between M4 domain
+ and A7 domain. Except for a few clock sources shared between two
+ domains, such as the System Oscillator clock, the Slow IRC (SIRC),
+ and and the Fast IRC clock (FIRCLK), clock sources and clock
+ management are separated and contained within each domain.
+
+ M4 clock management consists of SCG0, PCC0, PCC1, and CMC0 modules.
+ A7 clock management consists of SCG1, PCC2, PCC3, and CMC1 modules.
+
+ Note: this binding doc is only for A7 clock domain.
+
+ The System Clock Generation (SCG) is responsible for clock generation
+ and distribution across this device. Functions performed by the SCG
+ include: clock reference selection, generation of clock used to derive
+ processor, system, peripheral bus and external memory interface clocks,
+ source selection for peripheral clocks and control of power saving
+ clock gating mode.
+
+ The clock consumer should specify the desired clock by having the clock
+ ID in its "clocks" phandle cell.
+ See include/dt-bindings/clock/imx7ulp-clock.h for the full list of
+ i.MX7ULP clock IDs of each module.
+
+properties:
+ compatible:
+ const: fsl,imx7ulp-scg1
+
+ reg:
+ maxItems: 1
+
+ '#clock-cells':
+ const: 1
+
+ clocks:
+ items:
+ - description: rtc osc
+ - description: system osc
+ - description: slow internal reference clock
+ - description: fast internal reference clock
+ - description: usb PLL
+
+ clock-names:
+ items:
+ - const: rosc
+ - const: sosc
+ - const: sirc
+ - const: firc
+ - const: upll
+
+required:
+ - compatible
+ - reg
+ - '#clock-cells'
+ - clocks
+ - clock-names
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/clock/imx7ulp-clock.h>
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+
+ clock-controller@403e0000 {
+ compatible = "fsl,imx7ulp-scg1";
+ reg = <0x403e0000 0x10000>;
+ clocks = <&rosc>, <&sosc>, <&sirc>,
+ <&firc>, <&upll>;
+ clock-names = "rosc", "sosc", "sirc",
+ "firc", "upll";
+ #clock-cells = <1>;
+ };
+
+ mmc@40380000 {
+ compatible = "fsl,imx7ulp-usdhc";
+ reg = <0x40380000 0x10000>;
+ interrupts = <GIC_SPI 43 IRQ_TYPE_LEVEL_HIGH>;
+ clocks = <&scg1 IMX7ULP_CLK_NIC1_BUS_DIV>,
+ <&scg1 IMX7ULP_CLK_NIC1_DIV>,
+ <&pcc2 IMX7ULP_CLK_USDHC1>;
+ clock-names ="ipg", "ahb", "per";
+ bus-width = <4>;
+ };
diff --git a/Documentation/devicetree/bindings/clock/imx8qxp-lpcg.yaml b/Documentation/devicetree/bindings/clock/imx8qxp-lpcg.yaml
index 33f3010..1d5e9bc 100644
--- a/Documentation/devicetree/bindings/clock/imx8qxp-lpcg.yaml
+++ b/Documentation/devicetree/bindings/clock/imx8qxp-lpcg.yaml
@@ -62,7 +62,7 @@
};
mmc@5b010000 {
- compatible = "fsl,imx8qxp-usdhc", "fsl,imx7d-usdhc";
+ compatible = "fsl,imx8qxp-usdhc";
interrupts = <GIC_SPI 232 IRQ_TYPE_LEVEL_HIGH>;
reg = <0x5b010000 0x10000>;
clocks = <&conn_lpcg IMX_CONN_LPCG_SDHC0_IPG_CLK>,
diff --git a/Documentation/devicetree/bindings/clock/microchip,sparx5-dpll.yaml b/Documentation/devicetree/bindings/clock/microchip,sparx5-dpll.yaml
new file mode 100644
index 0000000..39559a0
--- /dev/null
+++ b/Documentation/devicetree/bindings/clock/microchip,sparx5-dpll.yaml
@@ -0,0 +1,52 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/clock/microchip,sparx5-dpll.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Microchip Sparx5 DPLL Clock
+
+maintainers:
+ - Lars Povlsen <lars.povlsen@microchip.com>
+
+description: |
+ The Sparx5 DPLL clock controller generates and supplies clock to
+ various peripherals within the SoC.
+
+properties:
+ compatible:
+ const: microchip,sparx5-dpll
+
+ reg:
+ maxItems: 1
+
+ clocks:
+ maxItems: 1
+
+ '#clock-cells':
+ const: 1
+
+required:
+ - compatible
+ - reg
+ - clocks
+ - '#clock-cells'
+
+additionalProperties: false
+
+examples:
+ # Clock provider for eMMC:
+ - |
+ lcpll_clk: lcpll-clk {
+ compatible = "fixed-clock";
+ #clock-cells = <0>;
+ clock-frequency = <2500000000>;
+ };
+ clks: clock-controller@61110000c {
+ compatible = "microchip,sparx5-dpll";
+ #clock-cells = <1>;
+ clocks = <&lcpll_clk>;
+ reg = <0x1110000c 0x24>;
+ };
+
+...
diff --git a/Documentation/devicetree/bindings/clock/qcom,a53pll.yaml b/Documentation/devicetree/bindings/clock/qcom,a53pll.yaml
index 20d2638..db3d0ea 100644
--- a/Documentation/devicetree/bindings/clock/qcom,a53pll.yaml
+++ b/Documentation/devicetree/bindings/clock/qcom,a53pll.yaml
@@ -15,7 +15,9 @@
properties:
compatible:
- const: qcom,msm8916-a53pll
+ enum:
+ - qcom,ipq6018-a53pll
+ - qcom,msm8916-a53pll
reg:
maxItems: 1
@@ -23,6 +25,14 @@
'#clock-cells':
const: 0
+ clocks:
+ items:
+ - description: board XO clock
+
+ clock-names:
+ items:
+ - const: xo
+
required:
- compatible
- reg
@@ -38,3 +48,12 @@
reg = <0xb016000 0x40>;
#clock-cells = <0>;
};
+ #Example 2 - A53 PLL found on IPQ6018 devices
+ - |
+ a53pll_ipq: clock-controller@b116000 {
+ compatible = "qcom,ipq6018-a53pll";
+ reg = <0x0b116000 0x40>;
+ #clock-cells = <0>;
+ clocks = <&xo>;
+ clock-names = "xo";
+ };
diff --git a/Documentation/devicetree/bindings/clock/qcom,gpucc.yaml b/Documentation/devicetree/bindings/clock/qcom,gpucc.yaml
new file mode 100644
index 0000000..df943c4
--- /dev/null
+++ b/Documentation/devicetree/bindings/clock/qcom,gpucc.yaml
@@ -0,0 +1,82 @@
+# SPDX-License-Identifier: GPL-2.0-only
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/clock/qcom,gpucc.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Qualcomm Graphics Clock & Reset Controller Binding
+
+maintainers:
+ - Taniya Das <tdas@codeaurora.org>
+
+description: |
+ Qualcomm graphics clock control module which supports the clocks, resets and
+ power domains on SDM845/SC7180/SM8150/SM8250.
+
+ See also:
+ dt-bindings/clock/qcom,gpucc-sdm845.h
+ dt-bindings/clock/qcom,gpucc-sc7180.h
+ dt-bindings/clock/qcom,gpucc-sm8150.h
+ dt-bindings/clock/qcom,gpucc-sm8250.h
+
+properties:
+ compatible:
+ enum:
+ - qcom,sdm845-gpucc
+ - qcom,sc7180-gpucc
+ - qcom,sm8150-gpucc
+ - qcom,sm8250-gpucc
+
+ clocks:
+ items:
+ - description: Board XO source
+ - description: GPLL0 main branch source
+ - description: GPLL0 div branch source
+
+ clock-names:
+ items:
+ - const: bi_tcxo
+ - const: gcc_gpu_gpll0_clk_src
+ - const: gcc_gpu_gpll0_div_clk_src
+
+ '#clock-cells':
+ const: 1
+
+ '#reset-cells':
+ const: 1
+
+ '#power-domain-cells':
+ const: 1
+
+ reg:
+ maxItems: 1
+
+required:
+ - compatible
+ - reg
+ - clocks
+ - clock-names
+ - '#clock-cells'
+ - '#reset-cells'
+ - '#power-domain-cells'
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/clock/qcom,gcc-sdm845.h>
+ #include <dt-bindings/clock/qcom,rpmh.h>
+ clock-controller@5090000 {
+ compatible = "qcom,sdm845-gpucc";
+ reg = <0x05090000 0x9000>;
+ clocks = <&rpmhcc RPMH_CXO_CLK>,
+ <&gcc GCC_GPU_GPLL0_CLK_SRC>,
+ <&gcc GCC_GPU_GPLL0_DIV_CLK_SRC>;
+ clock-names = "bi_tcxo",
+ "gcc_gpu_gpll0_clk_src",
+ "gcc_gpu_gpll0_div_clk_src";
+ #clock-cells = <1>;
+ #reset-cells = <1>;
+ #power-domain-cells = <1>;
+ };
+...
diff --git a/Documentation/devicetree/bindings/clock/qcom,msm8996-apcc.yaml b/Documentation/devicetree/bindings/clock/qcom,msm8996-apcc.yaml
new file mode 100644
index 0000000..a20cb10
--- /dev/null
+++ b/Documentation/devicetree/bindings/clock/qcom,msm8996-apcc.yaml
@@ -0,0 +1,54 @@
+# SPDX-License-Identifier: GPL-2.0-only
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/clock/qcom,msm8996-apcc.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Qualcomm clock controller for MSM8996 CPUs
+
+maintainers:
+ - Loic Poulain <loic.poulain@linaro.org>
+
+description: |
+ Qualcomm CPU clock controller for MSM8996 CPUs, clock 0 is for Power cluster
+ and clock 1 is for Perf cluster.
+
+properties:
+ compatible:
+ enum:
+ - qcom,msm8996-apcc
+
+ reg:
+ maxItems: 1
+
+ '#clock-cells':
+ const: 1
+
+ clocks:
+ items:
+ - description: Primary PLL clock for power cluster (little)
+ - description: Primary PLL clock for perf cluster (big)
+ - description: Alternate PLL clock for power cluster (little)
+ - description: Alternate PLL clock for perf cluster (big)
+
+ clock-names:
+ items:
+ - const: pwrcl_pll
+ - const: perfcl_pll
+ - const: pwrcl_alt_pll
+ - const: perfcl_alt_pll
+
+required:
+ - compatible
+ - reg
+ - '#clock-cells'
+
+additionalProperties: false
+
+examples:
+ - |
+ kryocc: clock-controller@6400000 {
+ compatible = "qcom,msm8996-apcc";
+ reg = <0x6400000 0x90000>;
+ #clock-cells = <1>;
+ };
diff --git a/Documentation/devicetree/bindings/clock/qcom,rpmcc.txt b/Documentation/devicetree/bindings/clock/qcom,rpmcc.txt
index 90a1349..b44a062 100644
--- a/Documentation/devicetree/bindings/clock/qcom,rpmcc.txt
+++ b/Documentation/devicetree/bindings/clock/qcom,rpmcc.txt
@@ -13,13 +13,17 @@
"qcom,rpmcc-msm8660", "qcom,rpmcc"
"qcom,rpmcc-apq8060", "qcom,rpmcc"
"qcom,rpmcc-msm8916", "qcom,rpmcc"
+ "qcom,rpmcc-msm8936", "qcom,rpmcc"
"qcom,rpmcc-msm8974", "qcom,rpmcc"
"qcom,rpmcc-msm8976", "qcom,rpmcc"
"qcom,rpmcc-apq8064", "qcom,rpmcc"
"qcom,rpmcc-ipq806x", "qcom,rpmcc"
+ "qcom,rpmcc-msm8992",·"qcom,rpmcc"
+ "qcom,rpmcc-msm8994",·"qcom,rpmcc"
"qcom,rpmcc-msm8996", "qcom,rpmcc"
"qcom,rpmcc-msm8998", "qcom,rpmcc"
"qcom,rpmcc-qcs404", "qcom,rpmcc"
+ "qcom,rpmcc-sdm660", "qcom,rpmcc"
- #clock-cells : shall contain 1
diff --git a/Documentation/devicetree/bindings/clock/qcom,sc7180-gpucc.yaml b/Documentation/devicetree/bindings/clock/qcom,sc7180-gpucc.yaml
deleted file mode 100644
index fe08461f..0000000
--- a/Documentation/devicetree/bindings/clock/qcom,sc7180-gpucc.yaml
+++ /dev/null
@@ -1,74 +0,0 @@
-# SPDX-License-Identifier: GPL-2.0-only
-%YAML 1.2
----
-$id: http://devicetree.org/schemas/clock/qcom,sc7180-gpucc.yaml#
-$schema: http://devicetree.org/meta-schemas/core.yaml#
-
-title: Qualcomm Graphics Clock & Reset Controller Binding for SC7180
-
-maintainers:
- - Taniya Das <tdas@codeaurora.org>
-
-description: |
- Qualcomm graphics clock control module which supports the clocks, resets and
- power domains on SC7180.
-
- See also dt-bindings/clock/qcom,gpucc-sc7180.h.
-
-properties:
- compatible:
- const: qcom,sc7180-gpucc
-
- clocks:
- items:
- - description: Board XO source
- - description: GPLL0 main branch source
- - description: GPLL0 div branch source
-
- clock-names:
- items:
- - const: bi_tcxo
- - const: gcc_gpu_gpll0_clk_src
- - const: gcc_gpu_gpll0_div_clk_src
-
- '#clock-cells':
- const: 1
-
- '#reset-cells':
- const: 1
-
- '#power-domain-cells':
- const: 1
-
- reg:
- maxItems: 1
-
-required:
- - compatible
- - reg
- - clocks
- - clock-names
- - '#clock-cells'
- - '#reset-cells'
- - '#power-domain-cells'
-
-additionalProperties: false
-
-examples:
- - |
- #include <dt-bindings/clock/qcom,gcc-sc7180.h>
- #include <dt-bindings/clock/qcom,rpmh.h>
- clock-controller@5090000 {
- compatible = "qcom,sc7180-gpucc";
- reg = <0x05090000 0x9000>;
- clocks = <&rpmhcc RPMH_CXO_CLK>,
- <&gcc GCC_GPU_GPLL0_CLK_SRC>,
- <&gcc GCC_GPU_GPLL0_DIV_CLK_SRC>;
- clock-names = "bi_tcxo",
- "gcc_gpu_gpll0_clk_src",
- "gcc_gpu_gpll0_div_clk_src";
- #clock-cells = <1>;
- #reset-cells = <1>;
- #power-domain-cells = <1>;
- };
-...
diff --git a/Documentation/devicetree/bindings/clock/qcom,sc7180-lpasscorecc.yaml b/Documentation/devicetree/bindings/clock/qcom,sc7180-lpasscorecc.yaml
new file mode 100644
index 0000000..c54172f
--- /dev/null
+++ b/Documentation/devicetree/bindings/clock/qcom,sc7180-lpasscorecc.yaml
@@ -0,0 +1,108 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/clock/qcom,sc7180-lpasscorecc.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Qualcomm LPASS Core Clock Controller Binding for SC7180
+
+maintainers:
+ - Taniya Das <tdas@codeaurora.org>
+
+description: |
+ Qualcomm LPASS core clock control module which supports the clocks and
+ power domains on SC7180.
+
+ See also:
+ - dt-bindings/clock/qcom,lpasscorecc-sc7180.h
+
+properties:
+ compatible:
+ enum:
+ - qcom,sc7180-lpasshm
+ - qcom,sc7180-lpasscorecc
+
+ clocks:
+ items:
+ - description: gcc_lpass_sway clock from GCC
+ - description: Board XO source
+
+ clock-names:
+ items:
+ - const: iface
+ - const: bi_tcxo
+
+ power-domains:
+ maxItems: 1
+
+ '#clock-cells':
+ const: 1
+
+ '#power-domain-cells':
+ const: 1
+
+ reg:
+ minItems: 1
+ items:
+ - description: lpass core cc register
+ - description: lpass audio cc register
+
+ reg-names:
+ items:
+ - const: lpass_core_cc
+ - const: lpass_audio_cc
+
+if:
+ properties:
+ compatible:
+ contains:
+ const: qcom,sc7180-lpasshm
+then:
+ properties:
+ reg:
+ maxItems: 1
+
+else:
+ properties:
+ reg:
+ minItems: 2
+
+required:
+ - compatible
+ - reg
+ - clocks
+ - clock-names
+ - '#clock-cells'
+ - '#power-domain-cells'
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/clock/qcom,rpmh.h>
+ #include <dt-bindings/clock/qcom,gcc-sc7180.h>
+ #include <dt-bindings/clock/qcom,lpasscorecc-sc7180.h>
+ clock-controller@63000000 {
+ compatible = "qcom,sc7180-lpasshm";
+ reg = <0x63000000 0x28>;
+ clocks = <&gcc GCC_LPASS_CFG_NOC_SWAY_CLK>, <&rpmhcc RPMH_CXO_CLK>;
+ clock-names = "iface", "bi_tcxo";
+ #clock-cells = <1>;
+ #power-domain-cells = <1>;
+ };
+
+ - |
+ #include <dt-bindings/clock/qcom,rpmh.h>
+ #include <dt-bindings/clock/qcom,gcc-sc7180.h>
+ #include <dt-bindings/clock/qcom,lpasscorecc-sc7180.h>
+ clock-controller@62d00000 {
+ compatible = "qcom,sc7180-lpasscorecc";
+ reg = <0x62d00000 0x50000>, <0x62780000 0x30000>;
+ reg-names = "lpass_core_cc", "lpass_audio_cc";
+ clocks = <&gcc GCC_LPASS_CFG_NOC_SWAY_CLK>, <&rpmhcc RPMH_CXO_CLK>;
+ clock-names = "iface", "bi_tcxo";
+ power-domains = <&lpass_hm LPASS_CORE_HM_GDSCR>;
+ #clock-cells = <1>;
+ #power-domain-cells = <1>;
+ };
+...
diff --git a/Documentation/devicetree/bindings/clock/qcom,sdm845-gpucc.yaml b/Documentation/devicetree/bindings/clock/qcom,sdm845-gpucc.yaml
deleted file mode 100644
index 8a0c576..0000000
--- a/Documentation/devicetree/bindings/clock/qcom,sdm845-gpucc.yaml
+++ /dev/null
@@ -1,74 +0,0 @@
-# SPDX-License-Identifier: GPL-2.0-only
-%YAML 1.2
----
-$id: http://devicetree.org/schemas/clock/qcom,sdm845-gpucc.yaml#
-$schema: http://devicetree.org/meta-schemas/core.yaml#
-
-title: Qualcomm Graphics Clock & Reset Controller Binding for SDM845
-
-maintainers:
- - Taniya Das <tdas@codeaurora.org>
-
-description: |
- Qualcomm graphics clock control module which supports the clocks, resets and
- power domains on SDM845.
-
- See also dt-bindings/clock/qcom,gpucc-sdm845.h.
-
-properties:
- compatible:
- const: qcom,sdm845-gpucc
-
- clocks:
- items:
- - description: Board XO source
- - description: GPLL0 main branch source
- - description: GPLL0 div branch source
-
- clock-names:
- items:
- - const: bi_tcxo
- - const: gcc_gpu_gpll0_clk_src
- - const: gcc_gpu_gpll0_div_clk_src
-
- '#clock-cells':
- const: 1
-
- '#reset-cells':
- const: 1
-
- '#power-domain-cells':
- const: 1
-
- reg:
- maxItems: 1
-
-required:
- - compatible
- - reg
- - clocks
- - clock-names
- - '#clock-cells'
- - '#reset-cells'
- - '#power-domain-cells'
-
-additionalProperties: false
-
-examples:
- - |
- #include <dt-bindings/clock/qcom,gcc-sdm845.h>
- #include <dt-bindings/clock/qcom,rpmh.h>
- clock-controller@5090000 {
- compatible = "qcom,sdm845-gpucc";
- reg = <0x05090000 0x9000>;
- clocks = <&rpmhcc RPMH_CXO_CLK>,
- <&gcc GCC_GPU_GPLL0_CLK_SRC>,
- <&gcc GCC_GPU_GPLL0_DIV_CLK_SRC>;
- clock-names = "bi_tcxo",
- "gcc_gpu_gpll0_clk_src",
- "gcc_gpu_gpll0_div_clk_src";
- #clock-cells = <1>;
- #reset-cells = <1>;
- #power-domain-cells = <1>;
- };
-...
diff --git a/Documentation/devicetree/bindings/clock/renesas,cpg-clocks.yaml b/Documentation/devicetree/bindings/clock/renesas,cpg-clocks.yaml
new file mode 100644
index 0000000..b83f413
--- /dev/null
+++ b/Documentation/devicetree/bindings/clock/renesas,cpg-clocks.yaml
@@ -0,0 +1,241 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/clock/renesas,cpg-clocks.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Renesas Clock Pulse Generator (CPG)
+
+maintainers:
+ - Geert Uytterhoeven <geert+renesas@glider.be>
+
+description:
+ The Clock Pulse Generator (CPG) generates core clocks for the SoC. It
+ includes PLLs, and fixed and variable ratio dividers.
+
+ The CPG may also provide a Clock Domain for SoC devices, in combination with
+ the CPG Module Stop (MSTP) Clocks.
+
+properties:
+ compatible:
+ oneOf:
+ - const: renesas,r8a73a4-cpg-clocks # R-Mobile APE6
+ - const: renesas,r8a7740-cpg-clocks # R-Mobile A1
+ - const: renesas,r8a7778-cpg-clocks # R-Car M1
+ - const: renesas,r8a7779-cpg-clocks # R-Car H1
+ - items:
+ - enum:
+ - renesas,r7s72100-cpg-clocks # RZ/A1H
+ - const: renesas,rz-cpg-clocks # RZ/A1
+ - const: renesas,sh73a0-cpg-clocks # SH-Mobile AG5
+
+ reg:
+ maxItems: 1
+
+ clocks: true
+
+ '#clock-cells':
+ const: 1
+
+ clock-output-names: true
+
+ renesas,mode:
+ description: Board-specific settings of the MD_CK* bits on R-Mobile A1
+ $ref: /schemas/types.yaml#/definitions/uint32
+ minimum: 0
+ maximum: 7
+
+ '#power-domain-cells':
+ const: 0
+
+required:
+ - compatible
+ - reg
+ - clocks
+ - '#clock-cells'
+ - clock-output-names
+
+allOf:
+ - if:
+ properties:
+ compatible:
+ contains:
+ const: renesas,r8a73a4-cpg-clocks
+ then:
+ properties:
+ clocks:
+ items:
+ - description: extal1
+ - description: extal2
+
+ clock-output-names:
+ items:
+ - const: main
+ - const: pll0
+ - const: pll1
+ - const: pll2
+ - const: pll2s
+ - const: pll2h
+ - const: z
+ - const: z2
+ - const: i
+ - const: m3
+ - const: b
+ - const: m1
+ - const: m2
+ - const: zx
+ - const: zs
+ - const: hp
+
+ - if:
+ properties:
+ compatible:
+ contains:
+ const: renesas,r8a7740-cpg-clocks
+ then:
+ properties:
+ clocks:
+ items:
+ - description: extal1
+ - description: extal2
+ - description: extalr
+
+ clock-output-names:
+ items:
+ - const: system
+ - const: pllc0
+ - const: pllc1
+ - const: pllc2
+ - const: r
+ - const: usb24s
+ - const: i
+ - const: zg
+ - const: b
+ - const: m1
+ - const: hp
+ - const: hpp
+ - const: usbp
+ - const: s
+ - const: zb
+ - const: m3
+ - const: cp
+
+ required:
+ - renesas,mode
+
+ - if:
+ properties:
+ compatible:
+ contains:
+ const: renesas,r8a7778-cpg-clocks
+ then:
+ properties:
+ clocks:
+ maxItems: 1
+
+ clock-output-names:
+ items:
+ - const: plla
+ - const: pllb
+ - const: b
+ - const: out
+ - const: p
+ - const: s
+ - const: s1
+
+ - if:
+ properties:
+ compatible:
+ contains:
+ const: renesas,r8a7779-cpg-clocks
+ then:
+ properties:
+ clocks:
+ maxItems: 1
+
+ clock-output-names:
+ items:
+ - const: plla
+ - const: z
+ - const: zs
+ - const: s
+ - const: s1
+ - const: p
+ - const: b
+ - const: out
+
+ - if:
+ properties:
+ compatible:
+ contains:
+ const: renesas,r7s72100-cpg-clocks
+ then:
+ properties:
+ clocks:
+ items:
+ - description: extal1
+ - description: usb_x1
+
+ clock-output-names:
+ items:
+ - const: pll
+ - const: i
+ - const: g
+
+ - if:
+ properties:
+ compatible:
+ contains:
+ const: renesas,sh73a0-cpg-clocks
+ then:
+ properties:
+ clocks:
+ items:
+ - description: extal1
+ - description: extal2
+
+ clock-output-names:
+ items:
+ - const: main
+ - const: pll0
+ - const: pll1
+ - const: pll2
+ - const: pll3
+ - const: dsi0phy
+ - const: dsi1phy
+ - const: zg
+ - const: m3
+ - const: b
+ - const: m1
+ - const: m2
+ - const: z
+ - const: zx
+ - const: hp
+
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - renesas,r8a7778-cpg-clocks
+ - renesas,r8a7779-cpg-clocks
+ - renesas,rz-cpg-clocks
+ then:
+ required:
+ - '#power-domain-cells'
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/clock/r8a7740-clock.h>
+ cpg_clocks: cpg_clocks@e6150000 {
+ compatible = "renesas,r8a7740-cpg-clocks";
+ reg = <0xe6150000 0x10000>;
+ clocks = <&extal1_clk>, <&extal2_clk>, <&extalr_clk>;
+ #clock-cells = <1>;
+ clock-output-names = "system", "pllc0", "pllc1", "pllc2", "r",
+ "usb24s", "i", "zg", "b", "m1", "hp", "hpp",
+ "usbp", "s", "zb", "m3", "cp";
+ renesas,mode = <0x05>;
+ };
diff --git a/Documentation/devicetree/bindings/clock/renesas,cpg-mssr.yaml b/Documentation/devicetree/bindings/clock/renesas,cpg-mssr.yaml
index c745bd6..e13aee8 100644
--- a/Documentation/devicetree/bindings/clock/renesas,cpg-mssr.yaml
+++ b/Documentation/devicetree/bindings/clock/renesas,cpg-mssr.yaml
@@ -33,6 +33,7 @@
- renesas,r8a774a1-cpg-mssr # RZ/G2M
- renesas,r8a774b1-cpg-mssr # RZ/G2N
- renesas,r8a774c0-cpg-mssr # RZ/G2E
+ - renesas,r8a774e1-cpg-mssr # RZ/G2H
- renesas,r8a7790-cpg-mssr # R-Car H2
- renesas,r8a7791-cpg-mssr # R-Car M2-W
- renesas,r8a7792-cpg-mssr # R-Car V2H
diff --git a/Documentation/devicetree/bindings/clock/renesas,r8a73a4-cpg-clocks.txt b/Documentation/devicetree/bindings/clock/renesas,r8a73a4-cpg-clocks.txt
deleted file mode 100644
index ece9239..0000000
--- a/Documentation/devicetree/bindings/clock/renesas,r8a73a4-cpg-clocks.txt
+++ /dev/null
@@ -1,33 +0,0 @@
-* Renesas R8A73A4 Clock Pulse Generator (CPG)
-
-The CPG generates core clocks for the R8A73A4 SoC. It includes five PLLs
-and several fixed ratio dividers.
-
-Required Properties:
-
- - compatible: Must be "renesas,r8a73a4-cpg-clocks"
-
- - reg: Base address and length of the memory resource used by the CPG
-
- - clocks: Reference to the parent clocks ("extal1" and "extal2")
-
- - #clock-cells: Must be 1
-
- - clock-output-names: The names of the clocks. Supported clocks are "main",
- "pll0", "pll1", "pll2", "pll2s", "pll2h", "z", "z2", "i", "m3", "b",
- "m1", "m2", "zx", "zs", and "hp".
-
-
-Example
--------
-
- cpg_clocks: cpg_clocks@e6150000 {
- compatible = "renesas,r8a73a4-cpg-clocks";
- reg = <0 0xe6150000 0 0x10000>;
- clocks = <&extal1_clk>, <&extal2_clk>;
- #clock-cells = <1>;
- clock-output-names = "main", "pll0", "pll1", "pll2",
- "pll2s", "pll2h", "z", "z2",
- "i", "m3", "b", "m1", "m2",
- "zx", "zs", "hp";
- };
diff --git a/Documentation/devicetree/bindings/clock/renesas,r8a7740-cpg-clocks.txt b/Documentation/devicetree/bindings/clock/renesas,r8a7740-cpg-clocks.txt
deleted file mode 100644
index 2c03302..0000000
--- a/Documentation/devicetree/bindings/clock/renesas,r8a7740-cpg-clocks.txt
+++ /dev/null
@@ -1,41 +0,0 @@
-These bindings should be considered EXPERIMENTAL for now.
-
-* Renesas R8A7740 Clock Pulse Generator (CPG)
-
-The CPG generates core clocks for the R8A7740 SoC. It includes three PLLs
-and several fixed ratio and variable ratio dividers.
-
-Required Properties:
-
- - compatible: Must be "renesas,r8a7740-cpg-clocks"
-
- - reg: Base address and length of the memory resource used by the CPG
-
- - clocks: Reference to the three parent clocks
- - #clock-cells: Must be 1
- - clock-output-names: The names of the clocks. Supported clocks are
- "system", "pllc0", "pllc1", "pllc2", "r", "usb24s", "i", "zg", "b",
- "m1", "hp", "hpp", "usbp", "s", "zb", "m3", and "cp".
-
- - renesas,mode: board-specific settings of the MD_CK* bits
-
-
-Example
--------
-
-cpg_clocks: cpg_clocks@e6150000 {
- compatible = "renesas,r8a7740-cpg-clocks";
- reg = <0xe6150000 0x10000>;
- clocks = <&extal1_clk>, <&extal2_clk>, <&extalr_clk>;
- #clock-cells = <1>;
- clock-output-names = "system", "pllc0", "pllc1",
- "pllc2", "r",
- "usb24s",
- "i", "zg", "b", "m1", "hp",
- "hpp", "usbp", "s", "zb", "m3",
- "cp";
-};
-
-&cpg_clocks {
- renesas,mode = <0x05>;
-};
diff --git a/Documentation/devicetree/bindings/clock/renesas,r8a7778-cpg-clocks.txt b/Documentation/devicetree/bindings/clock/renesas,r8a7778-cpg-clocks.txt
deleted file mode 100644
index 7cc4c03..0000000
--- a/Documentation/devicetree/bindings/clock/renesas,r8a7778-cpg-clocks.txt
+++ /dev/null
@@ -1,47 +0,0 @@
-* Renesas R8A7778 Clock Pulse Generator (CPG)
-
-The CPG generates core clocks for the R8A7778. It includes two PLLs and
-several fixed ratio dividers.
-The CPG also provides a Clock Domain for SoC devices, in combination with the
-CPG Module Stop (MSTP) Clocks.
-
-Required Properties:
-
- - compatible: Must be "renesas,r8a7778-cpg-clocks"
- - reg: Base address and length of the memory resource used by the CPG
- - #clock-cells: Must be 1
- - clock-output-names: The names of the clocks. Supported clocks are
- "plla", "pllb", "b", "out", "p", "s", and "s1".
- - #power-domain-cells: Must be 0
-
-SoC devices that are part of the CPG/MSTP Clock Domain and can be power-managed
-through an MSTP clock should refer to the CPG device node in their
-"power-domains" property, as documented by the generic PM domain bindings in
-Documentation/devicetree/bindings/power/power_domain.txt.
-
-
-Examples
---------
-
- - CPG device node:
-
- cpg_clocks: cpg_clocks@ffc80000 {
- compatible = "renesas,r8a7778-cpg-clocks";
- reg = <0xffc80000 0x80>;
- #clock-cells = <1>;
- clocks = <&extal_clk>;
- clock-output-names = "plla", "pllb", "b",
- "out", "p", "s", "s1";
- #power-domain-cells = <0>;
- };
-
-
- - CPG/MSTP Clock Domain member device node:
-
- sdhi0: sd@ffe4c000 {
- compatible = "renesas,sdhi-r8a7778";
- reg = <0xffe4c000 0x100>;
- interrupts = <0 87 IRQ_TYPE_LEVEL_HIGH>;
- clocks = <&mstp3_clks R8A7778_CLK_SDHI0>;
- power-domains = <&cpg_clocks>;
- };
diff --git a/Documentation/devicetree/bindings/clock/renesas,r8a7779-cpg-clocks.txt b/Documentation/devicetree/bindings/clock/renesas,r8a7779-cpg-clocks.txt
deleted file mode 100644
index 8c81547..0000000
--- a/Documentation/devicetree/bindings/clock/renesas,r8a7779-cpg-clocks.txt
+++ /dev/null
@@ -1,49 +0,0 @@
-* Renesas R8A7779 Clock Pulse Generator (CPG)
-
-The CPG generates core clocks for the R8A7779. It includes one PLL and
-several fixed ratio dividers.
-The CPG also provides a Clock Domain for SoC devices, in combination with the
-CPG Module Stop (MSTP) Clocks.
-
-Required Properties:
-
- - compatible: Must be "renesas,r8a7779-cpg-clocks"
- - reg: Base address and length of the memory resource used by the CPG
-
- - clocks: Reference to the parent clock
- - #clock-cells: Must be 1
- - clock-output-names: The names of the clocks. Supported clocks are "plla",
- "z", "zs", "s", "s1", "p", "b", "out".
- - #power-domain-cells: Must be 0
-
-SoC devices that are part of the CPG/MSTP Clock Domain and can be power-managed
-through an MSTP clock should refer to the CPG device node in their
-"power-domains" property, as documented by the generic PM domain bindings in
-Documentation/devicetree/bindings/power/power_domain.txt.
-
-
-Examples
---------
-
- - CPG device node:
-
- cpg_clocks: cpg_clocks@ffc80000 {
- compatible = "renesas,r8a7779-cpg-clocks";
- reg = <0xffc80000 0x30>;
- clocks = <&extal_clk>;
- #clock-cells = <1>;
- clock-output-names = "plla", "z", "zs", "s", "s1", "p",
- "b", "out";
- #power-domain-cells = <0>;
- };
-
-
- - CPG/MSTP Clock Domain member device node:
-
- sata: sata@fc600000 {
- compatible = "renesas,sata-r8a7779", "renesas,rcar-sata";
- reg = <0xfc600000 0x2000>;
- interrupts = <0 100 IRQ_TYPE_LEVEL_HIGH>;
- clocks = <&mstp1_clks R8A7779_CLK_SATA>;
- power-domains = <&cpg_clocks>;
- };
diff --git a/Documentation/devicetree/bindings/clock/renesas,rz-cpg-clocks.txt b/Documentation/devicetree/bindings/clock/renesas,rz-cpg-clocks.txt
deleted file mode 100644
index 8ff3e27..0000000
--- a/Documentation/devicetree/bindings/clock/renesas,rz-cpg-clocks.txt
+++ /dev/null
@@ -1,53 +0,0 @@
-* Renesas RZ/A1 Clock Pulse Generator (CPG)
-
-The CPG generates core clocks for the RZ/A1 SoCs. It includes the PLL, variable
-CPU and GPU clocks, and several fixed ratio dividers.
-The CPG also provides a Clock Domain for SoC devices, in combination with the
-CPG Module Stop (MSTP) Clocks.
-
-Required Properties:
-
- - compatible: Must be one of
- - "renesas,r7s72100-cpg-clocks" for the r7s72100 CPG
- and "renesas,rz-cpg-clocks" as a fallback.
- - reg: Base address and length of the memory resource used by the CPG
- - clocks: References to possible parent clocks. Order must match clock modes
- in the datasheet. For the r7s72100, this is extal, usb_x1.
- - #clock-cells: Must be 1
- - clock-output-names: The names of the clocks. Supported clocks are "pll",
- "i", and "g"
- - #power-domain-cells: Must be 0
-
-SoC devices that are part of the CPG/MSTP Clock Domain and can be power-managed
-through an MSTP clock should refer to the CPG device node in their
-"power-domains" property, as documented by the generic PM domain bindings in
-Documentation/devicetree/bindings/power/power_domain.txt.
-
-
-Examples
---------
-
- - CPG device node:
-
- cpg_clocks: cpg_clocks@fcfe0000 {
- #clock-cells = <1>;
- compatible = "renesas,r7s72100-cpg-clocks",
- "renesas,rz-cpg-clocks";
- reg = <0xfcfe0000 0x18>;
- clocks = <&extal_clk>, <&usb_x1_clk>;
- clock-output-names = "pll", "i", "g";
- #power-domain-cells = <0>;
- };
-
-
- - CPG/MSTP Clock Domain member device node:
-
- mtu2: timer@fcff0000 {
- compatible = "renesas,mtu2-r7s72100", "renesas,mtu2";
- reg = <0xfcff0000 0x400>;
- interrupts = <0 107 IRQ_TYPE_LEVEL_HIGH>;
- interrupt-names = "tgi0a";
- clocks = <&mstp3_clks R7S72100_CLK_MTU2>;
- clock-names = "fck";
- power-domains = <&cpg_clocks>;
- };
diff --git a/Documentation/devicetree/bindings/clock/renesas,sh73a0-cpg-clocks.txt b/Documentation/devicetree/bindings/clock/renesas,sh73a0-cpg-clocks.txt
deleted file mode 100644
index a8978ec..0000000
--- a/Documentation/devicetree/bindings/clock/renesas,sh73a0-cpg-clocks.txt
+++ /dev/null
@@ -1,35 +0,0 @@
-These bindings should be considered EXPERIMENTAL for now.
-
-* Renesas SH73A0 Clock Pulse Generator (CPG)
-
-The CPG generates core clocks for the SH73A0 SoC. It includes four PLLs
-and several fixed ratio dividers.
-
-Required Properties:
-
- - compatible: Must be "renesas,sh73a0-cpg-clocks"
-
- - reg: Base address and length of the memory resource used by the CPG
-
- - clocks: Reference to the parent clocks ("extal1" and "extal2")
-
- - #clock-cells: Must be 1
-
- - clock-output-names: The names of the clocks. Supported clocks are "main",
- "pll0", "pll1", "pll2", "pll3", "dsi0phy", "dsi1phy", "zg", "m3", "b",
- "m1", "m2", "z", "zx", and "hp".
-
-
-Example
--------
-
- cpg_clocks: cpg_clocks@e6150000 {
- compatible = "renesas,sh73a0-cpg-clocks";
- reg = <0 0xe6150000 0 0x10000>;
- clocks = <&extal1_clk>, <&extal2_clk>;
- #clock-cells = <1>;
- clock-output-names = "main", "pll0", "pll1", "pll2",
- "pll3", "dsi0phy", "dsi1phy",
- "zg", "m3", "b", "m1", "m2",
- "z", "zx", "hp";
- };
diff --git a/Documentation/devicetree/bindings/clock/rockchip,rk3288-cru.txt b/Documentation/devicetree/bindings/clock/rockchip,rk3288-cru.txt
index 8cb47c3..bf3a9ec 100644
--- a/Documentation/devicetree/bindings/clock/rockchip,rk3288-cru.txt
+++ b/Documentation/devicetree/bindings/clock/rockchip,rk3288-cru.txt
@@ -4,9 +4,15 @@
controllers within the SoC and also implements a reset controller for SoC
peripherals.
+A revision of this SoC is available: rk3288w. The clock tree is a bit
+different so another dt-compatible is available. Noticed that it is only
+setting the difference but there is no automatic revision detection. This
+should be performed by bootloaders.
+
Required Properties:
-- compatible: should be "rockchip,rk3288-cru"
+- compatible: should be "rockchip,rk3288-cru" or "rockchip,rk3288w-cru" in
+ case of this revision of Rockchip rk3288.
- reg: physical base address of the controller and length of memory mapped
region.
- #clock-cells: should be 1.
diff --git a/Documentation/devicetree/bindings/clock/silabs,si514.txt b/Documentation/devicetree/bindings/clock/silabs,si514.txt
index ea1a9db..a4f28ec 100644
--- a/Documentation/devicetree/bindings/clock/silabs,si514.txt
+++ b/Documentation/devicetree/bindings/clock/silabs,si514.txt
@@ -6,7 +6,7 @@
[1] Documentation/devicetree/bindings/clock/clock-bindings.txt
[2] Si514 datasheet
- http://www.silabs.com/Support%20Documents/TechnicalDocs/si514.pdf
+ https://www.silabs.com/Support%20Documents/TechnicalDocs/si514.pdf
Required properties:
- compatible: Shall be "silabs,si514"
diff --git a/Documentation/devicetree/bindings/clock/silabs,si5351.txt b/Documentation/devicetree/bindings/clock/silabs,si5351.txt
index f00191c..8fe6f80 100644
--- a/Documentation/devicetree/bindings/clock/silabs,si5351.txt
+++ b/Documentation/devicetree/bindings/clock/silabs,si5351.txt
@@ -2,7 +2,7 @@
Reference
[1] Si5351A/B/C Data Sheet
- http://www.silabs.com/Support%20Documents/TechnicalDocs/Si5351.pdf
+ https://www.silabs.com/Support%20Documents/TechnicalDocs/Si5351.pdf
The Si5351a/b/c are programmable i2c clock generators with up to 8 output
clocks. Si5351a also has a reduced pin-count package (MSOP10) where only
diff --git a/Documentation/devicetree/bindings/clock/silabs,si570.txt b/Documentation/devicetree/bindings/clock/silabs,si570.txt
index c09f21e..901935e 100644
--- a/Documentation/devicetree/bindings/clock/silabs,si570.txt
+++ b/Documentation/devicetree/bindings/clock/silabs,si570.txt
@@ -7,9 +7,9 @@
[1] Documentation/devicetree/bindings/clock/clock-bindings.txt
[2] Si570/571 Data Sheet
- http://www.silabs.com/Support%20Documents/TechnicalDocs/si570.pdf
+ https://www.silabs.com/Support%20Documents/TechnicalDocs/si570.pdf
[3] Si598/599 Data Sheet
- http://www.silabs.com/Support%20Documents/TechnicalDocs/si598-99.pdf
+ https://www.silabs.com/Support%20Documents/TechnicalDocs/si598-99.pdf
Required properties:
- compatible: Shall be one of "silabs,si570", "silabs,si571",
diff --git a/Documentation/devicetree/bindings/clock/ti,cdce706.txt b/Documentation/devicetree/bindings/clock/ti,cdce706.txt
index 959d966..21c3ff7 100644
--- a/Documentation/devicetree/bindings/clock/ti,cdce706.txt
+++ b/Documentation/devicetree/bindings/clock/ti,cdce706.txt
@@ -1,7 +1,7 @@
Bindings for Texas Instruments CDCE706 programmable 3-PLL clock
synthesizer/multiplier/divider.
-Reference: http://www.ti.com/lit/ds/symlink/cdce706.pdf
+Reference: https://www.ti.com/lit/ds/symlink/cdce706.pdf
I2C device node required properties:
- compatible: shall be "ti,cdce706".
diff --git a/Documentation/devicetree/bindings/clock/ti,cdce925.txt b/Documentation/devicetree/bindings/clock/ti,cdce925.txt
index 26544c8..df42ab7 100644
--- a/Documentation/devicetree/bindings/clock/ti,cdce925.txt
+++ b/Documentation/devicetree/bindings/clock/ti,cdce925.txt
@@ -4,10 +4,10 @@
This binding uses the common clock binding[1].
[1] Documentation/devicetree/bindings/clock/clock-bindings.txt
-[2] http://www.ti.com/product/cdce913
-[3] http://www.ti.com/product/cdce925
-[4] http://www.ti.com/product/cdce937
-[5] http://www.ti.com/product/cdce949
+[2] https://www.ti.com/product/cdce913
+[3] https://www.ti.com/product/cdce925
+[4] https://www.ti.com/product/cdce937
+[5] https://www.ti.com/product/cdce949
The driver provides clock sources for each output Y1 through Y5.
diff --git a/Documentation/devicetree/bindings/cpufreq/cpufreq-dt.txt b/Documentation/devicetree/bindings/cpufreq/cpufreq-dt.txt
index 332aed8..56f4423 100644
--- a/Documentation/devicetree/bindings/cpufreq/cpufreq-dt.txt
+++ b/Documentation/devicetree/bindings/cpufreq/cpufreq-dt.txt
@@ -18,7 +18,8 @@
in unit of nanoseconds.
- voltage-tolerance: Specify the CPU voltage tolerance in percentage.
- #cooling-cells:
- Please refer to Documentation/devicetree/bindings/thermal/thermal.txt.
+ Please refer to
+ Documentation/devicetree/bindings/thermal/thermal-cooling-devices.yaml.
Examples:
diff --git a/Documentation/devicetree/bindings/cpufreq/cpufreq-mediatek.txt b/Documentation/devicetree/bindings/cpufreq/cpufreq-mediatek.txt
index 0551c78..ea4994b 100644
--- a/Documentation/devicetree/bindings/cpufreq/cpufreq-mediatek.txt
+++ b/Documentation/devicetree/bindings/cpufreq/cpufreq-mediatek.txt
@@ -21,8 +21,8 @@
flow is handled by hardware, hence no software "voltage tracking" is
needed.
- #cooling-cells:
- Please refer to Documentation/devicetree/bindings/thermal/thermal.txt
- for detail.
+ For details, please refer to
+ Documentation/devicetree/bindings/thermal/thermal-cooling-devices.yaml
Example 1 (MT7623 SoC):
diff --git a/Documentation/devicetree/bindings/cpufreq/nvidia,tegra20-cpufreq.txt b/Documentation/devicetree/bindings/cpufreq/nvidia,tegra20-cpufreq.txt
index daeca6a..52a24b8 100644
--- a/Documentation/devicetree/bindings/cpufreq/nvidia,tegra20-cpufreq.txt
+++ b/Documentation/devicetree/bindings/cpufreq/nvidia,tegra20-cpufreq.txt
@@ -5,7 +5,7 @@
- clocks: Must contain an entry for the CPU clock.
See ../clocks/clock-bindings.txt for details.
- operating-points-v2: See ../bindings/opp/opp.txt for details.
-- #cooling-cells: Should be 2. See ../thermal/thermal.txt for details.
+- #cooling-cells: Should be 2. See ../thermal/thermal-cooling-devices.yaml for details.
For each opp entry in 'operating-points-v2' table:
- opp-supported-hw: Two bitfields indicating:
diff --git a/Documentation/devicetree/bindings/crypto/ti,sa2ul.yaml b/Documentation/devicetree/bindings/crypto/ti,sa2ul.yaml
new file mode 100644
index 0000000..85ef69f
--- /dev/null
+++ b/Documentation/devicetree/bindings/crypto/ti,sa2ul.yaml
@@ -0,0 +1,76 @@
+# SPDX-License-Identifier: (GPL-2.0-only or BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/crypto/ti,sa2ul.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: K3 SoC SA2UL crypto module
+
+maintainers:
+ - Tero Kristo <t-kristo@ti.com>
+
+properties:
+ compatible:
+ enum:
+ - ti,j721e-sa2ul
+ - ti,am654-sa2ul
+
+ reg:
+ maxItems: 1
+
+ power-domains:
+ maxItems: 1
+
+ dmas:
+ items:
+ - description: TX DMA Channel
+ - description: RX DMA Channel #1
+ - description: RX DMA Channel #2
+
+ dma-names:
+ items:
+ - const: tx
+ - const: rx1
+ - const: rx2
+
+ dma-coherent: true
+
+ "#address-cells":
+ const: 2
+
+ "#size-cells":
+ const: 2
+
+ ranges:
+ description:
+ Address translation for the possible RNG child node for SA2UL
+
+patternProperties:
+ "^rng@[a-f0-9]+$":
+ type: object
+ description:
+ Child RNG node for SA2UL
+
+required:
+ - compatible
+ - reg
+ - power-domains
+ - dmas
+ - dma-names
+ - dma-coherent
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/soc/ti,sci_pm_domain.h>
+
+ main_crypto: crypto@4e00000 {
+ compatible = "ti,j721-sa2ul";
+ reg = <0x0 0x4e00000 0x0 0x1200>;
+ power-domains = <&k3_pds 264 TI_SCI_PD_EXCLUSIVE>;
+ dmas = <&main_udmap 0xc000>, <&main_udmap 0x4000>,
+ <&main_udmap 0x4001>;
+ dma-names = "tx", "rx1", "rx2";
+ dma-coherent;
+ };
diff --git a/Documentation/devicetree/bindings/devfreq/rk3399_dmc.txt b/Documentation/devicetree/bindings/devfreq/rk3399_dmc.txt
index 0ec6814..a10d1f6 100644
--- a/Documentation/devicetree/bindings/devfreq/rk3399_dmc.txt
+++ b/Documentation/devicetree/bindings/devfreq/rk3399_dmc.txt
@@ -18,6 +18,8 @@
format depends on the interrupt controller.
It should be a DCF interrupt. When DDR DVFS finishes
a DCF interrupt is triggered.
+- rockchip,pmu: Phandle to the syscon managing the "PMU general register
+ files".
Following properties relate to DDR timing:
diff --git a/Documentation/devicetree/bindings/display/allwinner,sun8i-a83t-de2-mixer.yaml b/Documentation/devicetree/bindings/display/allwinner,sun8i-a83t-de2-mixer.yaml
index 1dee641..c040eef 100644
--- a/Documentation/devicetree/bindings/display/allwinner,sun8i-a83t-de2-mixer.yaml
+++ b/Documentation/devicetree/bindings/display/allwinner,sun8i-a83t-de2-mixer.yaml
@@ -36,6 +36,9 @@
- const: bus
- const: mod
+ iommus:
+ maxItems: 1
+
resets:
maxItems: 1
diff --git a/Documentation/devicetree/bindings/display/brcm,bcm-vc4.txt b/Documentation/devicetree/bindings/display/brcm,bcm-vc4.txt
deleted file mode 100644
index 26649b4..0000000
--- a/Documentation/devicetree/bindings/display/brcm,bcm-vc4.txt
+++ /dev/null
@@ -1,174 +0,0 @@
-Broadcom VC4 (VideoCore4) GPU
-
-The VC4 device present on the Raspberry Pi includes a display system
-with HDMI output and the HVS (Hardware Video Scaler) for compositing
-display planes.
-
-Required properties for VC4:
-- compatible: Should be "brcm,bcm2835-vc4" or "brcm,cygnus-vc4"
-
-Required properties for Pixel Valve:
-- compatible: Should be one of "brcm,bcm2835-pixelvalve0",
- "brcm,bcm2835-pixelvalve1", or "brcm,bcm2835-pixelvalve2"
-- reg: Physical base address and length of the PV's registers
-- interrupts: The interrupt number
- See bindings/interrupt-controller/brcm,bcm2835-armctrl-ic.txt
-
-Required properties for HVS:
-- compatible: Should be "brcm,bcm2835-hvs"
-- reg: Physical base address and length of the HVS's registers
-- interrupts: The interrupt number
- See bindings/interrupt-controller/brcm,bcm2835-armctrl-ic.txt
-
-Required properties for HDMI
-- compatible: Should be "brcm,bcm2835-hdmi"
-- reg: Physical base address and length of the two register ranges
- ("HDMI" and "HD", in that order)
-- interrupts: The interrupt numbers
- See bindings/interrupt-controller/brcm,bcm2835-armctrl-ic.txt
-- ddc: phandle of the I2C controller used for DDC EDID probing
-- clocks: a) hdmi: The HDMI state machine clock
- b) pixel: The pixel clock.
-
-Optional properties for HDMI:
-- hpd-gpios: The GPIO pin for HDMI hotplug detect (if it doesn't appear
- as an interrupt/status bit in the HDMI controller
- itself). See bindings/pinctrl/brcm,bcm2835-gpio.txt
-- dmas: Should contain one entry pointing to the DMA channel used to
- transfer audio data
-- dma-names: Should contain "audio-rx"
-
-Required properties for DPI:
-- compatible: Should be "brcm,bcm2835-dpi"
-- reg: Physical base address and length of the registers
-- clocks: a) core: The core clock the unit runs on
- b) pixel: The pixel clock that feeds the pixelvalve
-- port: Port node with a single endpoint connecting to the panel
- device, as defined in [1]
-
-Required properties for VEC:
-- compatible: Should be "brcm,bcm2835-vec"
-- reg: Physical base address and length of the registers
-- clocks: The core clock the unit runs on
-- interrupts: The interrupt number
- See bindings/interrupt-controller/brcm,bcm2835-armctrl-ic.txt
-
-Required properties for V3D:
-- compatible: Should be "brcm,bcm2835-v3d" or "brcm,cygnus-v3d"
-- reg: Physical base address and length of the V3D's registers
-- interrupts: The interrupt number
- See bindings/interrupt-controller/brcm,bcm2835-armctrl-ic.txt
-
-Optional properties for V3D:
-- clocks: The clock the unit runs on
-
-Required properties for DSI:
-- compatible: Should be "brcm,bcm2835-dsi0" or "brcm,bcm2835-dsi1"
-- reg: Physical base address and length of the DSI block's registers
-- interrupts: The interrupt number
- See bindings/interrupt-controller/brcm,bcm2835-armctrl-ic.txt
-- clocks: a) phy: The DSI PLL clock feeding the DSI analog PHY
- b) escape: The DSI ESC clock from CPRMAN
- c) pixel: The DSI pixel clock from CPRMAN
-- clock-output-names:
- The 3 clocks output from the DSI analog PHY: dsi[01]_byte,
- dsi[01]_ddr2, and dsi[01]_ddr
-
-Required properties for the TXP (writeback) block:
-- compatible: Should be "brcm,bcm2835-txp"
-- reg: Physical base address and length of the TXP block's registers
-- interrupts: The interrupt number
- See bindings/interrupt-controller/brcm,bcm2835-armctrl-ic.txt
-
-[1] Documentation/devicetree/bindings/media/video-interfaces.txt
-
-Example:
-pixelvalve@7e807000 {
- compatible = "brcm,bcm2835-pixelvalve2";
- reg = <0x7e807000 0x100>;
- interrupts = <2 10>; /* pixelvalve */
-};
-
-hvs@7e400000 {
- compatible = "brcm,bcm2835-hvs";
- reg = <0x7e400000 0x6000>;
- interrupts = <2 1>;
-};
-
-hdmi: hdmi@7e902000 {
- compatible = "brcm,bcm2835-hdmi";
- reg = <0x7e902000 0x600>,
- <0x7e808000 0x100>;
- interrupts = <2 8>, <2 9>;
- ddc = <&i2c2>;
- hpd-gpios = <&gpio 46 GPIO_ACTIVE_HIGH>;
- clocks = <&clocks BCM2835_PLLH_PIX>,
- <&clocks BCM2835_CLOCK_HSM>;
- clock-names = "pixel", "hdmi";
-};
-
-dpi: dpi@7e208000 {
- compatible = "brcm,bcm2835-dpi";
- reg = <0x7e208000 0x8c>;
- clocks = <&clocks BCM2835_CLOCK_VPU>,
- <&clocks BCM2835_CLOCK_DPI>;
- clock-names = "core", "pixel";
- #address-cells = <1>;
- #size-cells = <0>;
-
- port {
- dpi_out: endpoint@0 {
- remote-endpoint = <&panel_in>;
- };
- };
-};
-
-dsi1: dsi@7e700000 {
- compatible = "brcm,bcm2835-dsi1";
- reg = <0x7e700000 0x8c>;
- interrupts = <2 12>;
- #address-cells = <1>;
- #size-cells = <0>;
- #clock-cells = <1>;
-
- clocks = <&clocks BCM2835_PLLD_DSI1>,
- <&clocks BCM2835_CLOCK_DSI1E>,
- <&clocks BCM2835_CLOCK_DSI1P>;
- clock-names = "phy", "escape", "pixel";
-
- clock-output-names = "dsi1_byte", "dsi1_ddr2", "dsi1_ddr";
-
- pitouchscreen: panel@0 {
- compatible = "raspberrypi,touchscreen";
- reg = <0>;
-
- <...>
- };
-};
-
-vec: vec@7e806000 {
- compatible = "brcm,bcm2835-vec";
- reg = <0x7e806000 0x1000>;
- clocks = <&clocks BCM2835_CLOCK_VEC>;
- interrupts = <2 27>;
-};
-
-v3d: v3d@7ec00000 {
- compatible = "brcm,bcm2835-v3d";
- reg = <0x7ec00000 0x1000>;
- interrupts = <1 10>;
-};
-
-vc4: gpu {
- compatible = "brcm,bcm2835-vc4";
-};
-
-panel: panel {
- compatible = "ontat,yx700wv03", "simple-panel";
-
- port {
- panel_in: endpoint {
- remote-endpoint = <&dpi_out>;
- };
- };
-};
diff --git a/Documentation/devicetree/bindings/display/brcm,bcm2835-dpi.yaml b/Documentation/devicetree/bindings/display/brcm,bcm2835-dpi.yaml
new file mode 100644
index 0000000..5c1024b
--- /dev/null
+++ b/Documentation/devicetree/bindings/display/brcm,bcm2835-dpi.yaml
@@ -0,0 +1,62 @@
+# SPDX-License-Identifier: GPL-2.0
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/display/brcm,bcm2835-dpi.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Broadcom VC4 (VideoCore4) DPI Controller
+
+maintainers:
+ - Eric Anholt <eric@anholt.net>
+
+properties:
+ compatible:
+ const: brcm,bcm2835-dpi
+
+ reg:
+ maxItems: 1
+
+ clocks:
+ items:
+ - description: The core clock the unit runs on
+ - description: The pixel clock that feeds the pixelvalve
+
+ clock-names:
+ items:
+ - const: core
+ - const: pixel
+
+ port:
+ type: object
+ description: >
+ Port node with a single endpoint connecting to the panel, as
+ defined in Documentation/devicetree/bindings/media/video-interfaces.txt.
+
+required:
+ - compatible
+ - reg
+ - clocks
+ - clock-names
+ - port
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/clock/bcm2835.h>
+
+ dpi: dpi@7e208000 {
+ compatible = "brcm,bcm2835-dpi";
+ reg = <0x7e208000 0x8c>;
+ clocks = <&clocks BCM2835_CLOCK_VPU>,
+ <&clocks BCM2835_CLOCK_DPI>;
+ clock-names = "core", "pixel";
+
+ port {
+ dpi_out: endpoint {
+ remote-endpoint = <&panel_in>;
+ };
+ };
+ };
+
+...
diff --git a/Documentation/devicetree/bindings/display/brcm,bcm2835-dsi0.yaml b/Documentation/devicetree/bindings/display/brcm,bcm2835-dsi0.yaml
new file mode 100644
index 0000000..3c643b2
--- /dev/null
+++ b/Documentation/devicetree/bindings/display/brcm,bcm2835-dsi0.yaml
@@ -0,0 +1,84 @@
+# SPDX-License-Identifier: GPL-2.0
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/display/brcm,bcm2835-dsi0.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Broadcom VC4 (VideoCore4) DSI Controller
+
+maintainers:
+ - Eric Anholt <eric@anholt.net>
+
+properties:
+ "#clock-cells":
+ const: 1
+
+ compatible:
+ enum:
+ - brcm,bcm2835-dsi0
+ - brcm,bcm2835-dsi1
+
+ reg:
+ maxItems: 1
+
+ clocks:
+ items:
+ - description: The DSI PLL clock feeding the DSI analog PHY
+ - description: The DSI ESC clock
+ - description: The DSI pixel clock
+
+ clock-names:
+ items:
+ - const: phy
+ - const: escape
+ - const: pixel
+
+ clock-output-names: true
+ # FIXME: The meta-schemas don't seem to allow it for now
+ # items:
+ # - description: The DSI byte clock for the PHY
+ # - description: The DSI DDR2 clock
+ # - description: The DSI DDR clock
+
+ interrupts:
+ maxItems: 1
+
+required:
+ - "#clock-cells"
+ - compatible
+ - reg
+ - clocks
+ - clock-names
+ - clock-output-names
+ - interrupts
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/clock/bcm2835.h>
+
+ dsi1: dsi@7e700000 {
+ compatible = "brcm,bcm2835-dsi1";
+ reg = <0x7e700000 0x8c>;
+ interrupts = <2 12>;
+ #address-cells = <1>;
+ #size-cells = <0>;
+ #clock-cells = <1>;
+
+ clocks = <&clocks BCM2835_PLLD_DSI1>,
+ <&clocks BCM2835_CLOCK_DSI1E>,
+ <&clocks BCM2835_CLOCK_DSI1P>;
+ clock-names = "phy", "escape", "pixel";
+
+ clock-output-names = "dsi1_byte", "dsi1_ddr2", "dsi1_ddr";
+
+ pitouchscreen: panel@0 {
+ compatible = "raspberrypi,touchscreen";
+ reg = <0>;
+
+ /* ... */
+ };
+ };
+
+...
diff --git a/Documentation/devicetree/bindings/display/brcm,bcm2835-hdmi.yaml b/Documentation/devicetree/bindings/display/brcm,bcm2835-hdmi.yaml
new file mode 100644
index 0000000..52b3cda
--- /dev/null
+++ b/Documentation/devicetree/bindings/display/brcm,bcm2835-hdmi.yaml
@@ -0,0 +1,80 @@
+# SPDX-License-Identifier: GPL-2.0
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/display/brcm,bcm2835-hdmi.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Broadcom VC4 (VideoCore4) HDMI Controller
+
+maintainers:
+ - Eric Anholt <eric@anholt.net>
+
+properties:
+ compatible:
+ const: brcm,bcm2835-hdmi
+
+ reg:
+ items:
+ - description: HDMI register range
+ - description: HD register range
+
+ interrupts:
+ minItems: 2
+
+ clocks:
+ items:
+ - description: The pixel clock
+ - description: The HDMI state machine clock
+
+ clock-names:
+ items:
+ - const: pixel
+ - const: hdmi
+
+ ddc:
+ allOf:
+ - $ref: /schemas/types.yaml#/definitions/phandle
+ description: >
+ Phandle of the I2C controller used for DDC EDID probing
+
+ hpd-gpios:
+ description: >
+ The GPIO pin for the HDMI hotplug detect (if it doesn't appear
+ as an interrupt/status bit in the HDMI controller itself)
+
+ dmas:
+ maxItems: 1
+ description: >
+ Should contain one entry pointing to the DMA channel used to
+ transfer audio data.
+
+ dma-names:
+ const: audio-rx
+
+required:
+ - compatible
+ - reg
+ - interrupts
+ - clocks
+ - ddc
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/clock/bcm2835.h>
+ #include <dt-bindings/gpio/gpio.h>
+
+ hdmi: hdmi@7e902000 {
+ compatible = "brcm,bcm2835-hdmi";
+ reg = <0x7e902000 0x600>,
+ <0x7e808000 0x100>;
+ interrupts = <2 8>, <2 9>;
+ ddc = <&i2c2>;
+ hpd-gpios = <&gpio 46 GPIO_ACTIVE_HIGH>;
+ clocks = <&clocks BCM2835_PLLH_PIX>,
+ <&clocks BCM2835_CLOCK_HSM>;
+ clock-names = "pixel", "hdmi";
+ };
+
+...
diff --git a/Documentation/devicetree/bindings/display/brcm,bcm2835-hvs.yaml b/Documentation/devicetree/bindings/display/brcm,bcm2835-hvs.yaml
new file mode 100644
index 0000000..02410f8
--- /dev/null
+++ b/Documentation/devicetree/bindings/display/brcm,bcm2835-hvs.yaml
@@ -0,0 +1,37 @@
+# SPDX-License-Identifier: GPL-2.0
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/display/brcm,bcm2835-hvs.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Broadcom VC4 (VideoCore4) Hardware Video Scaler
+
+maintainers:
+ - Eric Anholt <eric@anholt.net>
+
+properties:
+ compatible:
+ const: brcm,bcm2835-hvs
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+required:
+ - compatible
+ - reg
+ - interrupts
+
+additionalProperties: false
+
+examples:
+ - |
+ hvs@7e400000 {
+ compatible = "brcm,bcm2835-hvs";
+ reg = <0x7e400000 0x6000>;
+ interrupts = <2 1>;
+ };
+
+...
diff --git a/Documentation/devicetree/bindings/display/brcm,bcm2835-pixelvalve0.yaml b/Documentation/devicetree/bindings/display/brcm,bcm2835-pixelvalve0.yaml
new file mode 100644
index 0000000..e60791d
--- /dev/null
+++ b/Documentation/devicetree/bindings/display/brcm,bcm2835-pixelvalve0.yaml
@@ -0,0 +1,40 @@
+# SPDX-License-Identifier: GPL-2.0
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/display/brcm,bcm2835-pixelvalve0.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Broadcom VC4 (VideoCore4) PixelValve
+
+maintainers:
+ - Eric Anholt <eric@anholt.net>
+
+properties:
+ compatible:
+ enum:
+ - brcm,bcm2835-pixelvalve0
+ - brcm,bcm2835-pixelvalve1
+ - brcm,bcm2835-pixelvalve2
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+required:
+ - compatible
+ - reg
+ - interrupts
+
+additionalProperties: false
+
+examples:
+ - |
+ pixelvalve@7e807000 {
+ compatible = "brcm,bcm2835-pixelvalve2";
+ reg = <0x7e807000 0x100>;
+ interrupts = <2 10>; /* pixelvalve */
+ };
+
+...
diff --git a/Documentation/devicetree/bindings/display/brcm,bcm2835-txp.yaml b/Documentation/devicetree/bindings/display/brcm,bcm2835-txp.yaml
new file mode 100644
index 0000000..bb18619
--- /dev/null
+++ b/Documentation/devicetree/bindings/display/brcm,bcm2835-txp.yaml
@@ -0,0 +1,37 @@
+# SPDX-License-Identifier: GPL-2.0
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/display/brcm,bcm2835-txp.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Broadcom VC4 (VideoCore4) TXP (writeback) Controller
+
+maintainers:
+ - Eric Anholt <eric@anholt.net>
+
+properties:
+ compatible:
+ const: brcm,bcm2835-txp
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+required:
+ - compatible
+ - reg
+ - interrupts
+
+additionalProperties: false
+
+examples:
+ - |
+ txp: txp@7e004000 {
+ compatible = "brcm,bcm2835-txp";
+ reg = <0x7e004000 0x20>;
+ interrupts = <1 11>;
+ };
+
+...
diff --git a/Documentation/devicetree/bindings/display/brcm,bcm2835-v3d.yaml b/Documentation/devicetree/bindings/display/brcm,bcm2835-v3d.yaml
new file mode 100644
index 0000000..8a73780
--- /dev/null
+++ b/Documentation/devicetree/bindings/display/brcm,bcm2835-v3d.yaml
@@ -0,0 +1,42 @@
+# SPDX-License-Identifier: GPL-2.0
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/display/brcm,bcm2835-v3d.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Broadcom VC4 (VideoCore4) V3D GPU
+
+maintainers:
+ - Eric Anholt <eric@anholt.net>
+
+properties:
+ compatible:
+ enum:
+ - brcm,bcm2835-v3d
+ - brcm,cygnus-v3d
+
+ reg:
+ maxItems: 1
+
+ clocks:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+required:
+ - compatible
+ - reg
+ - interrupts
+
+additionalProperties: false
+
+examples:
+ - |
+ v3d: v3d@7ec00000 {
+ compatible = "brcm,bcm2835-v3d";
+ reg = <0x7ec00000 0x1000>;
+ interrupts = <1 10>;
+ };
+
+...
diff --git a/Documentation/devicetree/bindings/display/brcm,bcm2835-vc4.yaml b/Documentation/devicetree/bindings/display/brcm,bcm2835-vc4.yaml
new file mode 100644
index 0000000..0dcf0c3
--- /dev/null
+++ b/Documentation/devicetree/bindings/display/brcm,bcm2835-vc4.yaml
@@ -0,0 +1,34 @@
+# SPDX-License-Identifier: GPL-2.0
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/display/brcm,bcm2835-vc4.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Broadcom VC4 (VideoCore4) GPU
+
+maintainers:
+ - Eric Anholt <eric@anholt.net>
+
+description: >
+ The VC4 device present on the Raspberry Pi includes a display system
+ with HDMI output and the HVS (Hardware Video Scaler) for compositing
+ display planes.
+
+properties:
+ compatible:
+ enum:
+ - brcm,bcm2835-vc4
+ - brcm,cygnus-vc4
+
+required:
+ - compatible
+
+additionalProperties: false
+
+examples:
+ - |
+ vc4: gpu {
+ compatible = "brcm,bcm2835-vc4";
+ };
+
+...
diff --git a/Documentation/devicetree/bindings/display/brcm,bcm2835-vec.yaml b/Documentation/devicetree/bindings/display/brcm,bcm2835-vec.yaml
new file mode 100644
index 0000000..d900cc5
--- /dev/null
+++ b/Documentation/devicetree/bindings/display/brcm,bcm2835-vec.yaml
@@ -0,0 +1,44 @@
+# SPDX-License-Identifier: GPL-2.0
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/display/brcm,bcm2835-vec.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Broadcom VC4 (VideoCore4) VEC
+
+maintainers:
+ - Eric Anholt <eric@anholt.net>
+
+properties:
+ compatible:
+ const: brcm,bcm2835-vec
+
+ reg:
+ maxItems: 1
+
+ clocks:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+required:
+ - compatible
+ - reg
+ - clocks
+ - interrupts
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/clock/bcm2835.h>
+
+ vec: vec@7e806000 {
+ compatible = "brcm,bcm2835-vec";
+ reg = <0x7e806000 0x1000>;
+ clocks = <&clocks BCM2835_CLOCK_VEC>;
+ interrupts = <2 27>;
+ };
+
+...
diff --git a/Documentation/devicetree/bindings/display/bridge/nwl-dsi.yaml b/Documentation/devicetree/bindings/display/bridge/nwl-dsi.yaml
index 8aff2d6..2c4c34e 100644
--- a/Documentation/devicetree/bindings/display/bridge/nwl-dsi.yaml
+++ b/Documentation/devicetree/bindings/display/bridge/nwl-dsi.yaml
@@ -165,6 +165,7 @@
- |
#include <dt-bindings/clock/imx8mq-clock.h>
+ #include <dt-bindings/gpio/gpio.h>
#include <dt-bindings/interrupt-controller/arm-gic.h>
#include <dt-bindings/reset/imx8mq-reset.h>
@@ -191,12 +192,12 @@
phy-names = "dphy";
panel@0 {
- #address-cells = <1>;
- #size-cells = <0>;
compatible = "rocktech,jh057n00900";
reg = <0>;
- port@0 {
- reg = <0>;
+ vcc-supply = <®_2v8_p>;
+ iovcc-supply = <®_1v8_p>;
+ reset-gpios = <&gpio3 13 GPIO_ACTIVE_LOW>;
+ port {
panel_in: endpoint {
remote-endpoint = <&mipi_dsi_out>;
};
diff --git a/Documentation/devicetree/bindings/display/bridge/renesas,lvds.txt b/Documentation/devicetree/bindings/display/bridge/renesas,lvds.txt
deleted file mode 100644
index c62ce24..0000000
--- a/Documentation/devicetree/bindings/display/bridge/renesas,lvds.txt
+++ /dev/null
@@ -1,85 +0,0 @@
-Renesas R-Car LVDS Encoder
-==========================
-
-These DT bindings describe the LVDS encoder embedded in the Renesas R-Car
-Gen2, R-Car Gen3 and RZ/G SoCs.
-
-Required properties:
-
-- compatible : Shall contain one of
- - "renesas,r8a7743-lvds" for R8A7743 (RZ/G1M) compatible LVDS encoders
- - "renesas,r8a7744-lvds" for R8A7744 (RZ/G1N) compatible LVDS encoders
- - "renesas,r8a774a1-lvds" for R8A774A1 (RZ/G2M) compatible LVDS encoders
- - "renesas,r8a774b1-lvds" for R8A774B1 (RZ/G2N) compatible LVDS encoders
- - "renesas,r8a774c0-lvds" for R8A774C0 (RZ/G2E) compatible LVDS encoders
- - "renesas,r8a7790-lvds" for R8A7790 (R-Car H2) compatible LVDS encoders
- - "renesas,r8a7791-lvds" for R8A7791 (R-Car M2-W) compatible LVDS encoders
- - "renesas,r8a7793-lvds" for R8A7793 (R-Car M2-N) compatible LVDS encoders
- - "renesas,r8a7795-lvds" for R8A7795 (R-Car H3) compatible LVDS encoders
- - "renesas,r8a7796-lvds" for R8A7796 (R-Car M3-W) compatible LVDS encoders
- - "renesas,r8a77965-lvds" for R8A77965 (R-Car M3-N) compatible LVDS encoders
- - "renesas,r8a77970-lvds" for R8A77970 (R-Car V3M) compatible LVDS encoders
- - "renesas,r8a77980-lvds" for R8A77980 (R-Car V3H) compatible LVDS encoders
- - "renesas,r8a77990-lvds" for R8A77990 (R-Car E3) compatible LVDS encoders
- - "renesas,r8a77995-lvds" for R8A77995 (R-Car D3) compatible LVDS encoders
-
-- reg: Base address and length for the memory-mapped registers
-- clocks: A list of phandles + clock-specifier pairs, one for each entry in
- the clock-names property.
-- clock-names: Name of the clocks. This property is model-dependent.
- - The functional clock, which mandatory for all models, shall be listed
- first, and shall be named "fck".
- - On R8A77990, R8A77995 and R8A774C0, the LVDS encoder can use the EXTAL or
- DU_DOTCLKINx clocks. Those clocks are optional. When supplied they must be
- named "extal" and "dclkin.x" respectively, with "x" being the DU_DOTCLKIN
- numerical index.
- - When the clocks property only contains the functional clock, the
- clock-names property may be omitted.
-- resets: A phandle + reset specifier for the module reset
-
-Required nodes:
-
-The LVDS encoder has two video ports. Their connections are modelled using the
-OF graph bindings specified in Documentation/devicetree/bindings/graph.txt.
-
-- Video port 0 corresponds to the parallel RGB input
-- Video port 1 corresponds to the LVDS output
-
-Each port shall have a single endpoint.
-
-Optional properties:
-
-- renesas,companion : phandle to the companion LVDS encoder. This property is
- mandatory for the first LVDS encoder on D3 and E3 SoCs, and shall point to
- the second encoder to be used as a companion in dual-link mode. It shall not
- be set for any other LVDS encoder.
-
-
-Example:
-
- lvds0: lvds@feb90000 {
- compatible = "renesas,r8a77990-lvds";
- reg = <0 0xfeb90000 0 0x20>;
- clocks = <&cpg CPG_MOD 727>;
- power-domains = <&sysc R8A77990_PD_ALWAYS_ON>;
- resets = <&cpg 727>;
-
- renesas,companion = <&lvds1>;
-
- ports {
- #address-cells = <1>;
- #size-cells = <0>;
-
- port@0 {
- reg = <0>;
- lvds0_in: endpoint {
- remote-endpoint = <&du_out_lvds0>;
- };
- };
- port@1 {
- reg = <1>;
- lvds0_out: endpoint {
- };
- };
- };
- };
diff --git a/Documentation/devicetree/bindings/display/bridge/renesas,lvds.yaml b/Documentation/devicetree/bindings/display/bridge/renesas,lvds.yaml
new file mode 100644
index 0000000..98c7330
--- /dev/null
+++ b/Documentation/devicetree/bindings/display/bridge/renesas,lvds.yaml
@@ -0,0 +1,248 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/display/bridge/renesas,lvds.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Renesas R-Car LVDS Encoder
+
+maintainers:
+ - Laurent Pinchart <laurent.pinchart+renesas@ideasonboard.com>
+
+description: |
+ These DT bindings describe the LVDS encoder embedded in the Renesas R-Car
+ Gen2, R-Car Gen3, RZ/G1 and RZ/G2 SoCs.
+
+properties:
+ compatible:
+ enum:
+ - renesas,r8a7743-lvds # for RZ/G1M compatible LVDS encoders
+ - renesas,r8a7744-lvds # for RZ/G1N compatible LVDS encoders
+ - renesas,r8a774a1-lvds # for RZ/G2M compatible LVDS encoders
+ - renesas,r8a774b1-lvds # for RZ/G2N compatible LVDS encoders
+ - renesas,r8a774c0-lvds # for RZ/G2E compatible LVDS encoders
+ - renesas,r8a7790-lvds # for R-Car H2 compatible LVDS encoders
+ - renesas,r8a7791-lvds # for R-Car M2-W compatible LVDS encoders
+ - renesas,r8a7793-lvds # for R-Car M2-N compatible LVDS encoders
+ - renesas,r8a7795-lvds # for R-Car H3 compatible LVDS encoders
+ - renesas,r8a7796-lvds # for R-Car M3-W compatible LVDS encoders
+ - renesas,r8a77965-lvds # for R-Car M3-N compatible LVDS encoders
+ - renesas,r8a77970-lvds # for R-Car V3M compatible LVDS encoders
+ - renesas,r8a77980-lvds # for R-Car V3H compatible LVDS encoders
+ - renesas,r8a77990-lvds # for R-Car E3 compatible LVDS encoders
+ - renesas,r8a77995-lvds # for R-Car D3 compatible LVDS encoders
+
+ reg:
+ maxItems: 1
+
+ clocks:
+ minItems: 1
+ maxItems: 4
+
+ clock-names:
+ minItems: 1
+ maxItems: 4
+
+ resets:
+ maxItems: 1
+
+ ports:
+ type: object
+ description: |
+ This device has two video ports. Their connections are modelled using the
+ OF graph bindings specified in Documentation/devicetree/bindings/graph.txt.
+ Each port shall have a single endpoint.
+
+ properties:
+ '#address-cells':
+ const: 1
+
+ '#size-cells':
+ const: 0
+
+ port@0:
+ type: object
+ description: Parallel RGB input port
+
+ port@1:
+ type: object
+ description: LVDS output port
+
+ required:
+ - port@0
+ - port@1
+
+ additionalProperties: false
+
+ power-domains:
+ maxItems: 1
+
+ renesas,companion:
+ $ref: /schemas/types.yaml#/definitions/phandle
+ description:
+ phandle to the companion LVDS encoder. This property is mandatory
+ for the first LVDS encoder on D3 and E3 SoCs, and shall point to
+ the second encoder to be used as a companion in dual-link mode. It
+ shall not be set for any other LVDS encoder.
+
+required:
+ - compatible
+ - reg
+ - clocks
+ - power-domains
+ - resets
+ - ports
+
+if:
+ properties:
+ compatible:
+ enum:
+ - renesas,r8a774c0-lvds
+ - renesas,r8a77990-lvds
+ - renesas,r8a77995-lvds
+then:
+ properties:
+ clocks:
+ minItems: 1
+ maxItems: 4
+ items:
+ - description: Functional clock
+ - description: EXTAL input clock
+ - description: DU_DOTCLKIN0 input clock
+ - description: DU_DOTCLKIN1 input clock
+
+ clock-names:
+ minItems: 1
+ maxItems: 4
+ items:
+ - const: fck
+ # The LVDS encoder can use the EXTAL or DU_DOTCLKINx clocks.
+ # These clocks are optional.
+ - enum:
+ - extal
+ - dclkin.0
+ - dclkin.1
+ - enum:
+ - extal
+ - dclkin.0
+ - dclkin.1
+ - enum:
+ - extal
+ - dclkin.0
+ - dclkin.1
+
+ required:
+ - clock-names
+
+else:
+ properties:
+ clocks:
+ maxItems: 1
+ items:
+ - description: Functional clock
+
+ clock-names:
+ maxItems: 1
+ items:
+ - const: fck
+
+ renesas,companion: false
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/clock/renesas-cpg-mssr.h>
+ #include <dt-bindings/power/r8a7795-sysc.h>
+
+ lvds@feb90000 {
+ compatible = "renesas,r8a7795-lvds";
+ reg = <0xfeb90000 0x14>;
+ clocks = <&cpg CPG_MOD 727>;
+ power-domains = <&sysc R8A7795_PD_ALWAYS_ON>;
+ resets = <&cpg 727>;
+
+ ports {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ port@0 {
+ reg = <0>;
+ lvds_in: endpoint {
+ remote-endpoint = <&du_out_lvds0>;
+ };
+ };
+ port@1 {
+ reg = <1>;
+ lvds_out: endpoint {
+ remote-endpoint = <&panel_in>;
+ };
+ };
+ };
+ };
+
+ - |
+ #include <dt-bindings/clock/renesas-cpg-mssr.h>
+ #include <dt-bindings/power/r8a77990-sysc.h>
+
+ lvds0: lvds@feb90000 {
+ compatible = "renesas,r8a77990-lvds";
+ reg = <0xfeb90000 0x20>;
+ clocks = <&cpg CPG_MOD 727>,
+ <&x13_clk>,
+ <&extal_clk>;
+ clock-names = "fck", "dclkin.0", "extal";
+ power-domains = <&sysc R8A77990_PD_ALWAYS_ON>;
+ resets = <&cpg 727>;
+
+ renesas,companion = <&lvds1>;
+
+ ports {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ port@0 {
+ reg = <0>;
+ lvds0_in: endpoint {
+ remote-endpoint = <&du_out_lvds0>;
+ };
+ };
+ port@1 {
+ reg = <1>;
+ lvds0_out: endpoint {
+ remote-endpoint = <&panel_in1>;
+ };
+ };
+ };
+ };
+
+ lvds1: lvds@feb90100 {
+ compatible = "renesas,r8a77990-lvds";
+ reg = <0xfeb90100 0x20>;
+ clocks = <&cpg CPG_MOD 727>,
+ <&x13_clk>,
+ <&extal_clk>;
+ clock-names = "fck", "dclkin.0", "extal";
+ power-domains = <&sysc R8A77990_PD_ALWAYS_ON>;
+ resets = <&cpg 726>;
+
+ ports {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ port@0 {
+ reg = <0>;
+ lvds1_in: endpoint {
+ remote-endpoint = <&du_out_lvds1>;
+ };
+ };
+ port@1 {
+ reg = <1>;
+ lvds1_out: endpoint {
+ remote-endpoint = <&panel_in2>;
+ };
+ };
+ };
+ };
+
+...
diff --git a/Documentation/devicetree/bindings/display/bridge/sii902x.txt b/Documentation/devicetree/bindings/display/bridge/sii902x.txt
index 6e14e08..0d1db3f 100644
--- a/Documentation/devicetree/bindings/display/bridge/sii902x.txt
+++ b/Documentation/devicetree/bindings/display/bridge/sii902x.txt
@@ -37,7 +37,7 @@
simple-card or audio-graph-card binding. See their binding
documents on how to describe the way the sii902x device is
connected to the rest of the audio system:
- Documentation/devicetree/bindings/sound/simple-card.txt
+ Documentation/devicetree/bindings/sound/simple-card.yaml
Documentation/devicetree/bindings/sound/audio-graph-card.txt
Note: In case of the audio-graph-card binding the used port
index should be 3.
diff --git a/Documentation/devicetree/bindings/display/bridge/ti,sn65dsi86.txt b/Documentation/devicetree/bindings/display/bridge/ti,sn65dsi86.txt
deleted file mode 100644
index 8ec4a7f..0000000
--- a/Documentation/devicetree/bindings/display/bridge/ti,sn65dsi86.txt
+++ /dev/null
@@ -1,87 +0,0 @@
-SN65DSI86 DSI to eDP bridge chip
---------------------------------
-
-This is the binding for Texas Instruments SN65DSI86 bridge.
-http://www.ti.com/general/docs/lit/getliterature.tsp?genericPartNumber=sn65dsi86&fileType=pdf
-
-Required properties:
-- compatible: Must be "ti,sn65dsi86"
-- reg: i2c address of the chip, 0x2d as per datasheet
-- enable-gpios: gpio specification for bridge_en pin (active high)
-
-- vccio-supply: A 1.8V supply that powers up the digital IOs.
-- vpll-supply: A 1.8V supply that powers up the displayport PLL.
-- vcca-supply: A 1.2V supply that powers up the analog circuits.
-- vcc-supply: A 1.2V supply that powers up the digital core.
-
-Optional properties:
-- interrupts-extended: Specifier for the SN65DSI86 interrupt line.
-
-- gpio-controller: Marks the device has a GPIO controller.
-- #gpio-cells : Should be two. The first cell is the pin number and
- the second cell is used to specify flags.
- See ../../gpio/gpio.txt for more information.
-- #pwm-cells : Should be one. See ../../pwm/pwm.yaml for description of
- the cell formats.
-
-- clock-names: should be "refclk"
-- clocks: Specification for input reference clock. The reference
- clock rate must be 12 MHz, 19.2 MHz, 26 MHz, 27 MHz or 38.4 MHz.
-
-- data-lanes: See ../../media/video-interface.txt
-- lane-polarities: See ../../media/video-interface.txt
-
-- suspend-gpios: specification for GPIO1 pin on bridge (active low)
-
-Required nodes:
-This device has two video ports. Their connections are modelled using the
-OF graph bindings specified in Documentation/devicetree/bindings/graph.txt.
-
-- Video port 0 for DSI input
-- Video port 1 for eDP output
-
-Example
--------
-
-edp-bridge@2d {
- compatible = "ti,sn65dsi86";
- #address-cells = <1>;
- #size-cells = <0>;
- reg = <0x2d>;
-
- enable-gpios = <&msmgpio 33 GPIO_ACTIVE_HIGH>;
- suspend-gpios = <&msmgpio 34 GPIO_ACTIVE_LOW>;
-
- interrupts-extended = <&gpio3 4 IRQ_TYPE_EDGE_FALLING>;
-
- vccio-supply = <&pm8916_l17>;
- vcca-supply = <&pm8916_l6>;
- vpll-supply = <&pm8916_l17>;
- vcc-supply = <&pm8916_l6>;
-
- clock-names = "refclk";
- clocks = <&input_refclk>;
-
- ports {
- #address-cells = <1>;
- #size-cells = <0>;
-
- port@0 {
- reg = <0>;
-
- edp_bridge_in: endpoint {
- remote-endpoint = <&dsi_out>;
- };
- };
-
- port@1 {
- reg = <1>;
-
- edp_bridge_out: endpoint {
- data-lanes = <2 1 3 0>;
- lane-polarities = <0 1 0 1>;
- remote-endpoint = <&edp_panel_in>;
- };
- };
- };
-}
diff --git a/Documentation/devicetree/bindings/display/bridge/ti,sn65dsi86.yaml b/Documentation/devicetree/bindings/display/bridge/ti,sn65dsi86.yaml
new file mode 100644
index 0000000..f8622bd
--- /dev/null
+++ b/Documentation/devicetree/bindings/display/bridge/ti,sn65dsi86.yaml
@@ -0,0 +1,293 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/display/bridge/ti,sn65dsi86.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: SN65DSI86 DSI to eDP bridge chip
+
+maintainers:
+ - Sandeep Panda <spanda@codeaurora.org>
+
+description: |
+ The Texas Instruments SN65DSI86 bridge takes MIPI DSI in and outputs eDP.
+ https://www.ti.com/general/docs/lit/getliterature.tsp?genericPartNumber=sn65dsi86&fileType=pdf
+
+properties:
+ compatible:
+ const: ti,sn65dsi86
+
+ reg:
+ const: 0x2d
+
+ enable-gpios:
+ maxItems: 1
+ description: GPIO specifier for bridge_en pin (active high).
+
+ suspend-gpios:
+ maxItems: 1
+ description: GPIO specifier for GPIO1 pin on bridge (active low).
+
+ no-hpd:
+ type: boolean
+ description:
+ Set if the HPD line on the bridge isn't hooked up to anything or is
+ otherwise unusable.
+
+ vccio-supply:
+ description: A 1.8V supply that powers the digital IOs.
+
+ vpll-supply:
+ description: A 1.8V supply that powers the DisplayPort PLL.
+
+ vcca-supply:
+ description: A 1.2V supply that powers the analog circuits.
+
+ vcc-supply:
+ description: A 1.2V supply that powers the digital core.
+
+ interrupts:
+ maxItems: 1
+
+ clocks:
+ maxItems: 1
+ description:
+ Clock specifier for input reference clock. The reference clock rate must
+ be 12 MHz, 19.2 MHz, 26 MHz, 27 MHz or 38.4 MHz.
+
+ clock-names:
+ const: refclk
+
+ gpio-controller: true
+ '#gpio-cells':
+ const: 2
+ description:
+ First cell is pin number, second cell is flags. GPIO pin numbers are
+ 1-based to match the datasheet. See ../../gpio/gpio.txt for more
+ information.
+
+ '#pwm-cells':
+ const: 1
+ description: See ../../pwm/pwm.yaml for description of the cell formats.
+
+ ports:
+ type: object
+ additionalProperties: false
+
+ properties:
+ "#address-cells":
+ const: 1
+
+ "#size-cells":
+ const: 0
+
+ port@0:
+ type: object
+ additionalProperties: false
+
+ description:
+ Video port for MIPI DSI input
+
+ properties:
+ reg:
+ const: 0
+
+ endpoint:
+ type: object
+ additionalProperties: false
+ properties:
+ remote-endpoint: true
+
+ required:
+ - reg
+
+ port@1:
+ type: object
+ additionalProperties: false
+
+ description:
+ Video port for eDP output (panel or connector).
+
+ properties:
+ reg:
+ const: 1
+
+ endpoint:
+ type: object
+ additionalProperties: false
+
+ properties:
+ remote-endpoint: true
+
+ data-lanes:
+ oneOf:
+ - minItems: 1
+ maxItems: 1
+ uniqueItems: true
+ items:
+ enum:
+ - 0
+ - 1
+ description:
+ If you have 1 logical lane the bridge supports routing
+ to either port 0 or port 1. Port 0 is suggested.
+ See ../../media/video-interface.txt for details.
+
+ - minItems: 2
+ maxItems: 2
+ uniqueItems: true
+ items:
+ enum:
+ - 0
+ - 1
+ description:
+ If you have 2 logical lanes the bridge supports
+ reordering but only on physical ports 0 and 1.
+ See ../../media/video-interface.txt for details.
+
+ - minItems: 4
+ maxItems: 4
+ uniqueItems: true
+ items:
+ enum:
+ - 0
+ - 1
+ - 2
+ - 3
+ description:
+ If you have 4 logical lanes the bridge supports
+ reordering in any way.
+ See ../../media/video-interface.txt for details.
+
+ lane-polarities:
+ minItems: 1
+ maxItems: 4
+ items:
+ enum:
+ - 0
+ - 1
+ description: See ../../media/video-interface.txt
+
+ dependencies:
+ lane-polarities: [data-lanes]
+
+ required:
+ - reg
+
+ required:
+ - "#address-cells"
+ - "#size-cells"
+ - port@0
+ - port@1
+
+required:
+ - compatible
+ - reg
+ - enable-gpios
+ - vccio-supply
+ - vpll-supply
+ - vcca-supply
+ - vcc-supply
+ - ports
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/clock/qcom,rpmh.h>
+ #include <dt-bindings/gpio/gpio.h>
+ #include <dt-bindings/interrupt-controller/irq.h>
+
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ bridge@2d {
+ compatible = "ti,sn65dsi86";
+ reg = <0x2d>;
+
+ interrupt-parent = <&tlmm>;
+ interrupts = <10 IRQ_TYPE_LEVEL_HIGH>;
+
+ enable-gpios = <&tlmm 102 GPIO_ACTIVE_HIGH>;
+
+ vpll-supply = <&src_pp1800_s4a>;
+ vccio-supply = <&src_pp1800_s4a>;
+ vcca-supply = <&src_pp1200_l2a>;
+ vcc-supply = <&src_pp1200_l2a>;
+
+ clocks = <&rpmhcc RPMH_LN_BB_CLK2>;
+ clock-names = "refclk";
+
+ no-hpd;
+
+ ports {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ port@0 {
+ reg = <0>;
+ endpoint {
+ remote-endpoint = <&dsi0_out>;
+ };
+ };
+
+ port@1 {
+ reg = <1>;
+ endpoint {
+ remote-endpoint = <&panel_in_edp>;
+ };
+ };
+ };
+ };
+ };
+ - |
+ #include <dt-bindings/clock/qcom,rpmh.h>
+ #include <dt-bindings/gpio/gpio.h>
+ #include <dt-bindings/interrupt-controller/irq.h>
+
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ bridge@2d {
+ compatible = "ti,sn65dsi86";
+ reg = <0x2d>;
+
+ enable-gpios = <&msmgpio 33 GPIO_ACTIVE_HIGH>;
+ suspend-gpios = <&msmgpio 34 GPIO_ACTIVE_LOW>;
+
+ interrupts-extended = <&gpio3 4 IRQ_TYPE_EDGE_FALLING>;
+
+ vccio-supply = <&pm8916_l17>;
+ vcca-supply = <&pm8916_l6>;
+ vpll-supply = <&pm8916_l17>;
+ vcc-supply = <&pm8916_l6>;
+
+ clock-names = "refclk";
+ clocks = <&input_refclk>;
+
+ ports {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ port@0 {
+ reg = <0>;
+
+ edp_bridge_in: endpoint {
+ remote-endpoint = <&dsi_out>;
+ };
+ };
+
+ port@1 {
+ reg = <1>;
+
+ edp_bridge_out: endpoint {
+ data-lanes = <2 1 3 0>;
+ lane-polarities = <0 1 0 1>;
+ remote-endpoint = <&edp_panel_in>;
+ };
+ };
+ };
+ };
+ };
diff --git a/Documentation/devicetree/bindings/display/bridge/ti,tfp410.txt b/Documentation/devicetree/bindings/display/bridge/ti,tfp410.txt
deleted file mode 100644
index 5ff4f64..0000000
--- a/Documentation/devicetree/bindings/display/bridge/ti,tfp410.txt
+++ /dev/null
@@ -1,66 +0,0 @@
-TFP410 DPI to DVI encoder
-=========================
-
-Required properties:
-- compatible: "ti,tfp410"
-
-Optional properties:
-- powerdown-gpios: power-down gpio
-- reg: I2C address. If and only if present the device node should be placed
- into the I2C controller node where the TFP410 I2C is connected to.
-- ti,deskew: data de-skew in 350ps increments, from -4 to +3, as configured
- through th DK[3:1] pins. This property shall be present only if the TFP410
- is not connected through I2C.
-
-Required nodes:
-
-This device has two video ports. Their connections are modeled using the OF
-graph bindings specified in [1]. Each port node shall have a single endpoint.
-
-- Port 0 is the DPI input port. Its endpoint subnode shall contain a
- pclk-sample and bus-width property and a remote-endpoint property as specified
- in [1].
- - If pclk-sample is not defined, pclk-sample = 0 should be assumed for
- backward compatibility.
- - If bus-width is not defined then bus-width = 24 should be assumed for
- backward compatibility.
- bus-width = 24: 24 data lines are connected and single-edge mode
- bus-width = 12: 12 data lines are connected and dual-edge mode
-
-- Port 1 is the DVI output port. Its endpoint subnode shall contain a
- remote-endpoint property is specified in [1].
-
-[1] Documentation/devicetree/bindings/media/video-interfaces.txt
-
-
-Example
--------
-
-tfp410: encoder@0 {
- compatible = "ti,tfp410";
- powerdown-gpios = <&twl_gpio 2 GPIO_ACTIVE_LOW>;
- ti,deskew = <4>;
-
- ports {
- #address-cells = <1>;
- #size-cells = <0>;
-
- port@0 {
- reg = <0>;
-
- tfp410_in: endpoint@0 {
- pclk-sample = <1>;
- bus-width = <24>;
- remote-endpoint = <&dpi_out>;
- };
- };
-
- port@1 {
- reg = <1>;
-
- tfp410_out: endpoint@0 {
- remote-endpoint = <&dvi_connector_in>;
- };
- };
- };
-};
diff --git a/Documentation/devicetree/bindings/display/bridge/ti,tfp410.yaml b/Documentation/devicetree/bindings/display/bridge/ti,tfp410.yaml
new file mode 100644
index 0000000..605831c
--- /dev/null
+++ b/Documentation/devicetree/bindings/display/bridge/ti,tfp410.yaml
@@ -0,0 +1,131 @@
+# SPDX-License-Identifier: GPL-2.0-only
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/display/bridge/ti,tfp410.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: TFP410 DPI to DVI encoder
+
+maintainers:
+ - Tomi Valkeinen <tomi.valkeinen@ti.com>
+ - Jyri Sarha <jsarha@ti.com>
+
+properties:
+ compatible:
+ const: ti,tfp410
+
+ reg:
+ description: I2C address of the device.
+ maxItems: 1
+
+ powerdown-gpios:
+ maxItems: 1
+
+ ti,deskew:
+ description:
+ Data de-skew value in 350ps increments, from 0 to 7, as configured
+ through the DK[3:1] pins. The de-skew multiplier is computed as
+ (DK[3:1] - 4), so it ranges from -4 to 3.
+ $ref: /schemas/types.yaml#/definitions/uint32
+ minimum: 0
+ maximum: 7
+
+ ports:
+ description:
+ A node containing input and output port nodes with endpoint
+ definitions as documented in
+ Documentation/devicetree/bindings/media/video-interfaces.txt
+ type: object
+
+ properties:
+ port@0:
+ description: DPI input port.
+ type: object
+
+ properties:
+ reg:
+ const: 0
+
+ endpoint:
+ type: object
+
+ properties:
+ pclk-sample:
+ description:
+ Endpoint sampling edge.
+ enum:
+ - 0 # Falling edge
+ - 1 # Rising edge
+ default: 0
+
+ bus-width:
+ description:
+ Endpoint bus width.
+ enum:
+ - 12 # 12 data lines connected and dual-edge mode
+ - 24 # 24 data lines connected and single-edge mode
+ default: 24
+
+ port@1:
+ description: DVI output port.
+ type: object
+
+ properties:
+ reg:
+ const: 1
+
+ endpoint:
+ type: object
+
+ required:
+ - port@0
+ - port@1
+
+required:
+ - compatible
+ - ports
+
+if:
+ required:
+ - reg
+then:
+ properties:
+ ti,deskew: false
+else:
+ required:
+ - ti,deskew
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/gpio/gpio.h>
+
+ tfp410: encoder {
+ compatible = "ti,tfp410";
+ powerdown-gpios = <&twl_gpio 2 GPIO_ACTIVE_LOW>;
+ ti,deskew = <3>;
+
+ ports {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ port@0 {
+ reg = <0>;
+ tfp410_in: endpoint {
+ pclk-sample = <1>;
+ bus-width = <24>;
+ remote-endpoint = <&dpi_out>;
+ };
+ };
+
+ port@1 {
+ reg = <1>;
+ tfp410_out: endpoint {
+ remote-endpoint = <&dvi_connector_in>;
+ };
+ };
+ };
+ };
+
+...
diff --git a/Documentation/devicetree/bindings/display/connector/analog-tv-connector.txt b/Documentation/devicetree/bindings/display/connector/analog-tv-connector.txt
deleted file mode 100644
index 883bcb2..0000000
--- a/Documentation/devicetree/bindings/display/connector/analog-tv-connector.txt
+++ /dev/null
@@ -1,31 +0,0 @@
-Analog TV Connector
-===================
-
-Required properties:
-- compatible: "composite-video-connector" or "svideo-connector"
-
-Optional properties:
-- label: a symbolic name for the connector
-- sdtv-standards: limit the supported TV standards on a connector to the given
- ones. If not specified all TV standards are allowed.
- Possible TV standards are defined in
- include/dt-bindings/display/sdtv-standards.h.
-
-Required nodes:
-- Video port for TV input
-
-Example
--------
-#include <dt-bindings/display/sdtv-standards.h>
-
-tv: connector {
- compatible = "composite-video-connector";
- label = "tv";
- sdtv-standards = <(SDTV_STD_PAL | SDTV_STD_NTSC)>;
-
- port {
- tv_connector_in: endpoint {
- remote-endpoint = <&venc_out>;
- };
- };
-};
diff --git a/Documentation/devicetree/bindings/display/connector/analog-tv-connector.yaml b/Documentation/devicetree/bindings/display/connector/analog-tv-connector.yaml
new file mode 100644
index 0000000..eebe88f
--- /dev/null
+++ b/Documentation/devicetree/bindings/display/connector/analog-tv-connector.yaml
@@ -0,0 +1,52 @@
+# SPDX-License-Identifier: GPL-2.0-only
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/display/connector/analog-tv-connector.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Analog TV Connector
+
+maintainers:
+ - Laurent Pinchart <Laurent.pinchart@ideasonboard.com>
+
+properties:
+ compatible:
+ enum:
+ - composite-video-connector
+ - svideo-connector
+
+ label: true
+
+ sdtv-standards:
+ description:
+ Limit the supported TV standards on a connector to the given ones. If
+ not specified all TV standards are allowed. Possible TV standards are
+ defined in include/dt-bindings/display/sdtv-standards.h.
+ $ref: /schemas/types.yaml#/definitions/uint32
+
+ port:
+ description: Connection to controller providing analog TV signals
+
+required:
+ - compatible
+ - port
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/display/sdtv-standards.h>
+
+ connector {
+ compatible = "composite-video-connector";
+ label = "tv";
+ sdtv-standards = <(SDTV_STD_PAL | SDTV_STD_NTSC)>;
+
+ port {
+ tv_connector_in: endpoint {
+ remote-endpoint = <&venc_out>;
+ };
+ };
+ };
+
+...
diff --git a/Documentation/devicetree/bindings/display/connector/dvi-connector.txt b/Documentation/devicetree/bindings/display/connector/dvi-connector.txt
deleted file mode 100644
index 207e42e..0000000
--- a/Documentation/devicetree/bindings/display/connector/dvi-connector.txt
+++ /dev/null
@@ -1,36 +0,0 @@
-DVI Connector
-==============
-
-Required properties:
-- compatible: "dvi-connector"
-
-Optional properties:
-- label: a symbolic name for the connector
-- ddc-i2c-bus: phandle to the i2c bus that is connected to DVI DDC
-- analog: the connector has DVI analog pins
-- digital: the connector has DVI digital pins
-- dual-link: the connector has pins for DVI dual-link
-- hpd-gpios: HPD GPIO number
-
-Required nodes:
-- Video port for DVI input
-
-Note: One (or both) of 'analog' or 'digital' must be set.
-
-Example
--------
-
-dvi0: connector@0 {
- compatible = "dvi-connector";
- label = "dvi";
-
- digital;
-
- ddc-i2c-bus = <&i2c3>;
-
- port {
- dvi_connector_in: endpoint {
- remote-endpoint = <&tfp410_out>;
- };
- };
-};
diff --git a/Documentation/devicetree/bindings/display/connector/dvi-connector.yaml b/Documentation/devicetree/bindings/display/connector/dvi-connector.yaml
new file mode 100644
index 0000000..71cb922
--- /dev/null
+++ b/Documentation/devicetree/bindings/display/connector/dvi-connector.yaml
@@ -0,0 +1,70 @@
+# SPDX-License-Identifier: GPL-2.0-only
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/display/connector/dvi-connector.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: DVI Connector
+
+maintainers:
+ - Laurent Pinchart <Laurent.pinchart@ideasonboard.com>
+
+properties:
+ compatible:
+ const: dvi-connector
+
+ label: true
+
+ hpd-gpios:
+ description: A GPIO line connected to HPD
+ maxItems: 1
+
+ ddc-i2c-bus:
+ description: phandle link to the I2C controller used for DDC EDID probing
+ $ref: /schemas/types.yaml#/definitions/phandle
+
+ analog:
+ type: boolean
+ description: the connector has DVI analog pins
+
+ digital:
+ type: boolean
+ description: the connector has DVI digital pins
+
+ dual-link:
+ type: boolean
+ description: the connector has pins for DVI dual-link
+
+ port:
+ description: Connection to controller providing DVI signals
+
+required:
+ - compatible
+ - port
+
+anyOf:
+ - required:
+ - analog
+ - required:
+ - digital
+
+additionalProperties: false
+
+examples:
+ - |
+ connector {
+ compatible = "dvi-connector";
+ label = "dvi";
+
+ digital;
+
+ ddc-i2c-bus = <&i2c3>;
+
+ port {
+ dvi_connector_in: endpoint {
+ remote-endpoint = <&tfp410_out>;
+ };
+ };
+ };
+
+...
diff --git a/Documentation/devicetree/bindings/display/connector/hdmi-connector.txt b/Documentation/devicetree/bindings/display/connector/hdmi-connector.txt
deleted file mode 100644
index aeb07c4..0000000
--- a/Documentation/devicetree/bindings/display/connector/hdmi-connector.txt
+++ /dev/null
@@ -1,31 +0,0 @@
-HDMI Connector
-==============
-
-Required properties:
-- compatible: "hdmi-connector"
-- type: the HDMI connector type: "a", "b", "c", "d" or "e"
-
-Optional properties:
-- 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
-
-Example
--------
-
-hdmi0: connector@1 {
- compatible = "hdmi-connector";
- label = "hdmi";
-
- type = "a";
-
- port {
- hdmi_connector_in: endpoint {
- remote-endpoint = <&tpd12s015_out>;
- };
- };
-};
diff --git a/Documentation/devicetree/bindings/display/connector/hdmi-connector.yaml b/Documentation/devicetree/bindings/display/connector/hdmi-connector.yaml
new file mode 100644
index 0000000..14d7128
--- /dev/null
+++ b/Documentation/devicetree/bindings/display/connector/hdmi-connector.yaml
@@ -0,0 +1,64 @@
+# SPDX-License-Identifier: GPL-2.0-only
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/display/connector/hdmi-connector.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: HDMI Connector
+
+maintainers:
+ - Laurent Pinchart <Laurent.pinchart@ideasonboard.com>
+
+properties:
+ compatible:
+ const: hdmi-connector
+
+ type:
+ description: The HDMI connector type
+ enum:
+ - a # Standard full size
+ - b # Never deployed?
+ - c # Mini
+ - d # Micro
+ - e # automotive
+
+ label: true
+
+ hpd-gpios:
+ description: A GPIO line connected to HPD
+ maxItems: 1
+
+ ddc-i2c-bus:
+ description: phandle link to the I2C controller used for DDC EDID probing
+ $ref: /schemas/types.yaml#/definitions/phandle
+
+ ddc-en-gpios:
+ description: GPIO signal to enable DDC bus
+ maxItems: 1
+
+ port:
+ description: Connection to controller providing HDMI signals
+
+required:
+ - compatible
+ - port
+ - type
+
+additionalProperties: false
+
+examples:
+ - |
+ connector {
+ compatible = "hdmi-connector";
+ label = "hdmi";
+
+ type = "a";
+
+ port {
+ hdmi_connector_in: endpoint {
+ remote-endpoint = <&tpd12s015_out>;
+ };
+ };
+ };
+
+...
diff --git a/Documentation/devicetree/bindings/display/connector/vga-connector.txt b/Documentation/devicetree/bindings/display/connector/vga-connector.txt
deleted file mode 100644
index c727f29..0000000
--- a/Documentation/devicetree/bindings/display/connector/vga-connector.txt
+++ /dev/null
@@ -1,36 +0,0 @@
-VGA Connector
-=============
-
-Required properties:
-
-- compatible: "vga-connector"
-
-Optional properties:
-
-- label: a symbolic name for the connector corresponding to a hardware label
-- ddc-i2c-bus: phandle to the I2C bus that is connected to VGA DDC
-
-Required nodes:
-
-The VGA connector internal connections are modeled using the OF graph bindings
-specified in Documentation/devicetree/bindings/graph.txt.
-
-The VGA connector has a single port that must be connected to a video source
-port.
-
-
-Example
--------
-
-vga0: connector@0 {
- compatible = "vga-connector";
- label = "vga";
-
- ddc-i2c-bus = <&i2c3>;
-
- port {
- vga_connector_in: endpoint {
- remote-endpoint = <&adv7123_out>;
- };
- };
-};
diff --git a/Documentation/devicetree/bindings/display/connector/vga-connector.yaml b/Documentation/devicetree/bindings/display/connector/vga-connector.yaml
new file mode 100644
index 0000000..5782c4b
--- /dev/null
+++ b/Documentation/devicetree/bindings/display/connector/vga-connector.yaml
@@ -0,0 +1,46 @@
+# SPDX-License-Identifier: GPL-2.0-only
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/display/connector/vga-connector.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: VGA Connector
+
+maintainers:
+ - Laurent Pinchart <Laurent.pinchart@ideasonboard.com>
+
+properties:
+ compatible:
+ const: vga-connector
+
+ label: true
+
+ ddc-i2c-bus:
+ description: phandle link to the I2C controller used for DDC EDID probing
+ $ref: /schemas/types.yaml#/definitions/phandle
+
+ port:
+ description: Connection to controller providing VGA signals
+
+required:
+ - compatible
+ - port
+
+additionalProperties: false
+
+examples:
+ - |
+ connector {
+ compatible = "vga-connector";
+ label = "vga";
+
+ ddc-i2c-bus = <&i2c3>;
+
+ port {
+ vga_connector_in: endpoint {
+ remote-endpoint = <&adv7123_out>;
+ };
+ };
+ };
+
+...
diff --git a/Documentation/devicetree/bindings/display/imx/fsl-imx-drm.txt b/Documentation/devicetree/bindings/display/imx/fsl-imx-drm.txt
index 5bf77f6..5a99490 100644
--- a/Documentation/devicetree/bindings/display/imx/fsl-imx-drm.txt
+++ b/Documentation/devicetree/bindings/display/imx/fsl-imx-drm.txt
@@ -68,7 +68,7 @@
datasheet
- clocks : phandle to the PRE axi clock input, as described
in Documentation/devicetree/bindings/clock/clock-bindings.txt and
- Documentation/devicetree/bindings/clock/imx6q-clock.txt.
+ Documentation/devicetree/bindings/clock/imx6q-clock.yaml.
- clock-names: should be "axi"
- interrupts: should contain the PRE interrupt
- fsl,iram: phandle pointing to the mmio-sram device node, that should be
@@ -94,7 +94,7 @@
datasheet
- clocks : phandles to the PRG ipg and axi clock inputs, as described
in Documentation/devicetree/bindings/clock/clock-bindings.txt and
- Documentation/devicetree/bindings/clock/imx6q-clock.txt.
+ Documentation/devicetree/bindings/clock/imx6q-clock.yaml.
- clock-names: should be "ipg" and "axi"
- fsl,pres: phandles to the PRE units attached to this PRG, with the fixed
PRE as the first entry and the muxable PREs following.
diff --git a/Documentation/devicetree/bindings/display/imx/ldb.txt b/Documentation/devicetree/bindings/display/imx/ldb.txt
index 38c637f..8e6e7d7 100644
--- a/Documentation/devicetree/bindings/display/imx/ldb.txt
+++ b/Documentation/devicetree/bindings/display/imx/ldb.txt
@@ -30,8 +30,8 @@
"di2_sel" - IPU2 DI0 mux
"di3_sel" - IPU2 DI1 mux
The needed clock numbers for each are documented in
- Documentation/devicetree/bindings/clock/imx5-clock.txt, and in
- Documentation/devicetree/bindings/clock/imx6q-clock.txt.
+ Documentation/devicetree/bindings/clock/imx5-clock.yaml, and in
+ Documentation/devicetree/bindings/clock/imx6q-clock.yaml.
Optional properties:
- pinctrl-names : should be "default" on i.MX53, not used on i.MX6q
diff --git a/Documentation/devicetree/bindings/display/ingenic,ipu.yaml b/Documentation/devicetree/bindings/display/ingenic,ipu.yaml
new file mode 100644
index 0000000..5bfc33e
--- /dev/null
+++ b/Documentation/devicetree/bindings/display/ingenic,ipu.yaml
@@ -0,0 +1,65 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/display/ingenic,ipu.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Ingenic SoCs Image Processing Unit (IPU) devicetree bindings
+
+maintainers:
+ - Paul Cercueil <paul@crapouillou.net>
+
+properties:
+ compatible:
+ oneOf:
+ - enum:
+ - ingenic,jz4725b-ipu
+ - ingenic,jz4760-ipu
+ - items:
+ - const: ingenic,jz4770-ipu
+ - const: ingenic,jz4760-ipu
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+ clocks:
+ maxItems: 1
+
+ clock-names:
+ const: ipu
+
+patternProperties:
+ "^ports?$":
+ description: OF graph bindings (specified in bindings/graph.txt).
+
+required:
+ - compatible
+ - reg
+ - interrupts
+ - clocks
+ - clock-names
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/clock/jz4770-cgu.h>
+ ipu@13080000 {
+ compatible = "ingenic,jz4770-ipu", "ingenic,jz4760-ipu";
+ reg = <0x13080000 0x800>;
+
+ interrupt-parent = <&intc>;
+ interrupts = <29>;
+
+ clocks = <&cgu JZ4770_CLK_IPU>;
+ clock-names = "ipu";
+
+ port {
+ ipu_ep: endpoint {
+ remote-endpoint = <&lcdc_ep>;
+ };
+ };
+ };
diff --git a/Documentation/devicetree/bindings/display/ingenic,lcd.txt b/Documentation/devicetree/bindings/display/ingenic,lcd.txt
deleted file mode 100644
index 01e3261..0000000
--- a/Documentation/devicetree/bindings/display/ingenic,lcd.txt
+++ /dev/null
@@ -1,45 +0,0 @@
-Ingenic JZ47xx LCD driver
-
-Required properties:
-- compatible: one of:
- * ingenic,jz4740-lcd
- * ingenic,jz4725b-lcd
- * ingenic,jz4770-lcd
-- reg: LCD registers location and length
-- clocks: LCD pixclock and device clock specifiers.
- The device clock is only required on the JZ4740.
-- clock-names: "lcd_pclk" and "lcd"
-- interrupts: Specifies the interrupt line the LCD controller is connected to.
-
-Example:
-
-panel {
- compatible = "sharp,ls020b1dd01d";
-
- backlight = <&backlight>;
- power-supply = <&vcc>;
-
- port {
- panel_input: endpoint {
- remote-endpoint = <&panel_output>;
- };
- };
-};
-
-
-lcd: lcd-controller@13050000 {
- compatible = "ingenic,jz4725b-lcd";
- reg = <0x13050000 0x1000>;
-
- interrupt-parent = <&intc>;
- interrupts = <31>;
-
- clocks = <&cgu JZ4725B_CLK_LCD>;
- clock-names = "lcd";
-
- port {
- panel_output: endpoint {
- remote-endpoint = <&panel_input>;
- };
- };
-};
diff --git a/Documentation/devicetree/bindings/display/ingenic,lcd.yaml b/Documentation/devicetree/bindings/display/ingenic,lcd.yaml
new file mode 100644
index 0000000..d56db18
--- /dev/null
+++ b/Documentation/devicetree/bindings/display/ingenic,lcd.yaml
@@ -0,0 +1,126 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/display/ingenic,lcd.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Ingenic SoCs LCD controller devicetree bindings
+
+maintainers:
+ - Paul Cercueil <paul@crapouillou.net>
+
+properties:
+ $nodename:
+ pattern: "^lcd-controller@[0-9a-f]+$"
+
+ compatible:
+ enum:
+ - ingenic,jz4740-lcd
+ - ingenic,jz4725b-lcd
+ - ingenic,jz4770-lcd
+ - ingenic,jz4780-lcd
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+ clocks:
+ items:
+ - description: Pixel clock
+ - description: Module clock
+ minItems: 1
+
+ clock-names:
+ items:
+ - const: lcd_pclk
+ - const: lcd
+ minItems: 1
+
+ port:
+ description: OF graph bindings (specified in bindings/graph.txt).
+
+ ports:
+ description: OF graph bindings (specified in bindings/graph.txt).
+ type: object
+ properties:
+ port@0:
+ type: object
+ description: DPI output, to interface with TFT panels.
+
+ port@8:
+ type: object
+ description: Link to the Image Processing Unit (IPU).
+ (See ingenic,ipu.yaml).
+
+ required:
+ - port@0
+
+required:
+ - compatible
+ - reg
+ - interrupts
+ - clocks
+ - clock-names
+
+if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - ingenic,jz4740-lcd
+ - ingenic,jz4780-lcd
+then:
+ properties:
+ clocks:
+ minItems: 2
+ clock-names:
+ minItems: 2
+else:
+ properties:
+ clocks:
+ maxItems: 1
+ clock-names:
+ maxItems: 1
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/clock/jz4740-cgu.h>
+ lcd-controller@13050000 {
+ compatible = "ingenic,jz4740-lcd";
+ reg = <0x13050000 0x1000>;
+
+ interrupt-parent = <&intc>;
+ interrupts = <30>;
+
+ clocks = <&cgu JZ4740_CLK_LCD_PCLK>, <&cgu JZ4740_CLK_LCD>;
+ clock-names = "lcd_pclk", "lcd";
+
+ port {
+ endpoint {
+ remote-endpoint = <&panel_input>;
+ };
+ };
+ };
+
+ - |
+ #include <dt-bindings/clock/jz4725b-cgu.h>
+ lcd-controller@13050000 {
+ compatible = "ingenic,jz4725b-lcd";
+ reg = <0x13050000 0x1000>;
+
+ interrupt-parent = <&intc>;
+ interrupts = <31>;
+
+ clocks = <&cgu JZ4725B_CLK_LCD>;
+ clock-names = "lcd_pclk";
+
+ port {
+ endpoint {
+ remote-endpoint = <&panel_input>;
+ };
+ };
+ };
diff --git a/Documentation/devicetree/bindings/display/msm/dsi.txt b/Documentation/devicetree/bindings/display/msm/dsi.txt
index af95586..7884fd7 100644
--- a/Documentation/devicetree/bindings/display/msm/dsi.txt
+++ b/Documentation/devicetree/bindings/display/msm/dsi.txt
@@ -87,6 +87,7 @@
* "qcom,dsi-phy-20nm"
* "qcom,dsi-phy-28nm-8960"
* "qcom,dsi-phy-14nm"
+ * "qcom,dsi-phy-14nm-660"
* "qcom,dsi-phy-10nm"
* "qcom,dsi-phy-10nm-8998"
- reg: Physical base address and length of the registers of PLL, PHY. Some
diff --git a/Documentation/devicetree/bindings/display/msm/gpu.txt b/Documentation/devicetree/bindings/display/msm/gpu.txt
index fd779cd..1af0ff1 100644
--- a/Documentation/devicetree/bindings/display/msm/gpu.txt
+++ b/Documentation/devicetree/bindings/display/msm/gpu.txt
@@ -112,6 +112,34 @@
interconnects = <&rsc_hlos MASTER_GFX3D &rsc_hlos SLAVE_EBI1>;
interconnect-names = "gfx-mem";
+ gpu_opp_table: opp-table {
+ compatible = "operating-points-v2";
+
+ opp-430000000 {
+ opp-hz = /bits/ 64 <430000000>;
+ opp-level = <RPMH_REGULATOR_LEVEL_SVS_L1>;
+ opp-peak-kBps = <5412000>;
+ };
+
+ opp-355000000 {
+ opp-hz = /bits/ 64 <355000000>;
+ opp-level = <RPMH_REGULATOR_LEVEL_SVS>;
+ opp-peak-kBps = <3072000>;
+ };
+
+ opp-267000000 {
+ opp-hz = /bits/ 64 <267000000>;
+ opp-level = <RPMH_REGULATOR_LEVEL_LOW_SVS>;
+ opp-peak-kBps = <3072000>;
+ };
+
+ opp-180000000 {
+ opp-hz = /bits/ 64 <180000000>;
+ opp-level = <RPMH_REGULATOR_LEVEL_MIN_SVS>;
+ opp-peak-kBps = <1804000>;
+ };
+ };
+
qcom,gmu = <&gmu>;
zap-shader {
diff --git a/Documentation/devicetree/bindings/display/panel/arm,versatile-tft-panel.yaml b/Documentation/devicetree/bindings/display/panel/arm,versatile-tft-panel.yaml
index 41fd571..be69e0c 100644
--- a/Documentation/devicetree/bindings/display/panel/arm,versatile-tft-panel.yaml
+++ b/Documentation/devicetree/bindings/display/panel/arm,versatile-tft-panel.yaml
@@ -33,7 +33,7 @@
examples:
- |
- sysreg {
+ sysreg@0 {
compatible = "arm,versatile-sysreg", "syscon", "simple-mfd";
reg = <0x00000 0x1000>;
diff --git a/Documentation/devicetree/bindings/display/panel/innolux,p079zca.txt b/Documentation/devicetree/bindings/display/panel/innolux,p079zca.txt
deleted file mode 100644
index 3ab8c74..0000000
--- a/Documentation/devicetree/bindings/display/panel/innolux,p079zca.txt
+++ /dev/null
@@ -1,22 +0,0 @@
-Innolux P079ZCA 7.85" 768x1024 TFT LCD panel
-
-Required properties:
-- compatible: should be "innolux,p079zca"
-- reg: DSI virtual channel of the peripheral
-- power-supply: phandle of the regulator that provides the supply voltage
-- enable-gpios: panel enable gpio
-
-Optional properties:
-- backlight: phandle of the backlight device attached to the panel
-
-Example:
-
- &mipi_dsi {
- panel@0 {
- compatible = "innolux,p079zca";
- reg = <0>;
- power-supply = <...>;
- backlight = <&backlight>;
- enable-gpios = <&gpio1 13 GPIO_ACTIVE_HIGH>;
- };
- };
diff --git a/Documentation/devicetree/bindings/display/panel/panel-dsi-cm.txt b/Documentation/devicetree/bindings/display/panel/panel-dsi-cm.txt
deleted file mode 100644
index dce48eb..0000000
--- a/Documentation/devicetree/bindings/display/panel/panel-dsi-cm.txt
+++ /dev/null
@@ -1,29 +0,0 @@
-Generic MIPI DSI Command Mode Panel
-===================================
-
-Required properties:
-- compatible: "panel-dsi-cm"
-
-Optional properties:
-- label: a symbolic name for the panel
-- reset-gpios: panel reset gpio
-- te-gpios: panel TE gpio
-
-Required nodes:
-- Video port for DSI input
-
-Example
--------
-
-lcd0: display {
- compatible = "tpo,taal", "panel-dsi-cm";
- label = "lcd0";
-
- reset-gpios = <&gpio4 6 GPIO_ACTIVE_HIGH>;
-
- port {
- lcd0_in: endpoint {
- remote-endpoint = <&dsi1_out_ep>;
- };
- };
-};
diff --git a/Documentation/devicetree/bindings/display/panel/panel-dsi-cm.yaml b/Documentation/devicetree/bindings/display/panel/panel-dsi-cm.yaml
new file mode 100644
index 0000000..d766c94
--- /dev/null
+++ b/Documentation/devicetree/bindings/display/panel/panel-dsi-cm.yaml
@@ -0,0 +1,86 @@
+# SPDX-License-Identifier: (GPL-2.0-only or BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/display/panel/panel-dsi-cm.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: DSI command mode panels
+
+maintainers:
+ - Tomi Valkeinen <tomi.valkeinen@ti.com>
+ - Sebastian Reichel <sre@kernel.org>
+
+description: |
+ This binding file is a collection of the DSI panels that
+ are usually driven in command mode. If no backlight is
+ referenced via the optional backlight property, the DSI
+ panel is assumed to have native backlight support.
+ The panel may use an OF graph binding for the association
+ to the display, or it may be a direct child node of the
+ display.
+
+allOf:
+ - $ref: panel-common.yaml#
+
+properties:
+
+ compatible:
+ items:
+ - enum:
+ - motorola,droid4-panel # Panel from Motorola Droid4 phone
+ - nokia,himalaya # Panel from Nokia N950 phone
+ - tpo,taal # Panel from OMAP4 SDP board
+ - const: panel-dsi-cm # Generic DSI command mode panel compatible fallback
+
+ reg:
+ maxItems: 1
+ description: DSI virtual channel
+
+ vddi-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 vddi-supply property specifies the supply powering the panel as a
+ phandle to a regulator.
+
+ vpnl-supply:
+ description:
+ When the display panel needs a second power supply, this property can be
+ used in addition to vddi-supply. Both supplies will be enabled at the
+ same time before the panel is being accessed.
+
+ width-mm: true
+ height-mm: true
+ label: true
+ rotation: true
+ panel-timing: true
+ port: true
+ reset-gpios: true
+ te-gpios: true
+ backlight: true
+
+additionalProperties: false
+
+required:
+ - compatible
+ - reg
+
+examples:
+ - |
+ #include <dt-bindings/gpio/gpio.h>
+
+ dsi-controller {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ panel@0 {
+ compatible = "tpo,taal", "panel-dsi-cm";
+ reg = <0>;
+ reset-gpios = <&gpio4 6 GPIO_ACTIVE_HIGH>;
+ };
+ };
+
+...
diff --git a/Documentation/devicetree/bindings/display/panel/panel-simple-dsi.yaml b/Documentation/devicetree/bindings/display/panel/panel-simple-dsi.yaml
index 16778ce..c0dd9fa 100644
--- a/Documentation/devicetree/bindings/display/panel/panel-simple-dsi.yaml
+++ b/Documentation/devicetree/bindings/display/panel/panel-simple-dsi.yaml
@@ -33,6 +33,8 @@
- auo,b080uan01
# Boe Corporation 8.0" WUXGA TFT LCD panel
- boe,tv080wum-nl0
+ # Innolux P079ZCA 7.85" 768x1024 TFT LCD panel
+ - innolux,p079zca
# Kingdisplay KD097D04 9.7" 1536x2048 TFT LCD panel
- kingdisplay,kd097d04
# LG ACX467AKM-7 4.95" 1080×1920 LCD Panel
diff --git a/Documentation/devicetree/bindings/display/panel/panel-simple.yaml b/Documentation/devicetree/bindings/display/panel/panel-simple.yaml
index d6cca14..6deeeed 100644
--- a/Documentation/devicetree/bindings/display/panel/panel-simple.yaml
+++ b/Documentation/devicetree/bindings/display/panel/panel-simple.yaml
@@ -81,6 +81,10 @@
- boe,nv140fhmn49
# CDTech(H.K.) Electronics Limited 4.3" 480x272 color TFT-LCD panel
- cdtech,s043wq26h-ct7
+ # CDTech(H.K.) Electronics Limited 7" WSVGA (1024x600) TFT LCD Panel
+ - cdtech,s070pws19hp-fc21
+ # CDTech(H.K.) Electronics Limited 7" WVGA (800x480) TFT LCD Panel
+ - cdtech,s070swv29hg-dc44
# CDTech(H.K.) Electronics Limited 7" 800x480 color TFT-LCD panel
- cdtech,s070wv95-ct16
# Chunghwa Picture Tubes Ltd. 7" WXGA TFT LCD panel
@@ -157,6 +161,8 @@
- innolux,zj070na-01p
# Kaohsiung Opto-Electronics Inc. 5.7" QVGA (320 x 240) TFT LCD panel
- koe,tx14d24vm1bpa
+ # Kaohsiung Opto-Electronics Inc. 10.1" WUXGA (1920 x 1200) LVDS TFT LCD panel
+ - koe,tx26d202vm0bwa
# Kaohsiung Opto-Electronics. TX31D200VM0BAA 12.3" HSXGA LVDS panel
- koe,tx31d200vm0baa
# Kyocera Corporation 12.1" XGA (1024x768) TFT LCD panel
@@ -245,6 +251,8 @@
- starry,kr122ea0sra
# Tianma Micro-electronics TM070JDHG30 7.0" WXGA TFT LCD panel
- tianma,tm070jdhg30
+ # Tianma Micro-electronics TM070JVHG33 7.0" WXGA TFT LCD panel
+ - tianma,tm070jvhg33
# Tianma Micro-electronics TM070RVHG71 7.0" WXGA TFT LCD panel
- tianma,tm070rvhg71
# Toshiba 8.9" WXGA (1280x768) TFT LCD panel
diff --git a/Documentation/devicetree/bindings/display/panel/rocktech,jh057n00900.txt b/Documentation/devicetree/bindings/display/panel/rocktech,jh057n00900.txt
deleted file mode 100644
index a372c5d..0000000
--- a/Documentation/devicetree/bindings/display/panel/rocktech,jh057n00900.txt
+++ /dev/null
@@ -1,23 +0,0 @@
-Rocktech jh057n00900 5.5" 720x1440 TFT LCD panel
-
-Required properties:
-- compatible: should be "rocktech,jh057n00900"
-- 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:
-
- &mipi_dsi {
- panel@0 {
- compatible = "rocktech,jh057n00900";
- 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/rocktech,jh057n00900.yaml b/Documentation/devicetree/bindings/display/panel/rocktech,jh057n00900.yaml
new file mode 100644
index 0000000..d5733ef
--- /dev/null
+++ b/Documentation/devicetree/bindings/display/panel/rocktech,jh057n00900.yaml
@@ -0,0 +1,71 @@
+# SPDX-License-Identifier: (GPL-2.0-only or BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/display/panel/rocktech,jh057n00900.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Rocktech JH057N00900 5.5" 720x1440 TFT LCD panel
+
+maintainers:
+ - Ondrej Jirman <megi@xff.cz>
+
+description: |
+ Rocktech JH057N00900 is a 720x1440 TFT LCD panel
+ connected using a MIPI-DSI video interface.
+
+allOf:
+ - $ref: panel-common.yaml#
+
+properties:
+ compatible:
+ enum:
+ # Rocktech JH057N00900 5.5" 720x1440 TFT LCD panel
+ - rocktech,jh057n00900
+ # Xingbangda XBD599 5.99" 720x1440 TFT LCD panel
+ - xingbangda,xbd599
+
+ port: true
+ reg:
+ maxItems: 1
+ description: DSI virtual channel
+
+ vcc-supply:
+ description: Panel power supply
+
+ iovcc-supply:
+ description: I/O voltage supply
+
+ reset-gpios:
+ description: GPIO used for the reset pin
+ maxItems: 1
+
+ backlight:
+ description: Backlight used by the panel
+ $ref: "/schemas/types.yaml#/definitions/phandle"
+
+required:
+ - compatible
+ - reg
+ - vcc-supply
+ - iovcc-supply
+ - reset-gpios
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/gpio/gpio.h>
+
+ dsi {
+ #address-cells = <1>;
+ #size-cells = <0>;
+ panel@0 {
+ compatible = "rocktech,jh057n00900";
+ reg = <0>;
+ vcc-supply = <®_2v8_p>;
+ iovcc-supply = <®_1v8_p>;
+ reset-gpios = <&gpio3 13 GPIO_ACTIVE_LOW>;
+ backlight = <&backlight>;
+ };
+ };
+...
diff --git a/Documentation/devicetree/bindings/display/panel/samsung,s6e8aa0.txt b/Documentation/devicetree/bindings/display/panel/samsung,s6e8aa0.txt
deleted file mode 100644
index 9e766c5..0000000
--- a/Documentation/devicetree/bindings/display/panel/samsung,s6e8aa0.txt
+++ /dev/null
@@ -1,56 +0,0 @@
-Samsung S6E8AA0 AMOLED LCD 5.3 inch panel
-
-Required properties:
- - compatible: "samsung,s6e8aa0"
- - reg: the virtual channel number of a DSI peripheral
- - vdd3-supply: core voltage supply
- - vci-supply: voltage supply for analog circuits
- - reset-gpios: a GPIO spec for the reset pin
- - display-timings: timings for the connected panel as described by [1]
-
-Optional properties:
- - power-on-delay: delay after turning regulators on [ms]
- - reset-delay: delay after reset sequence [ms]
- - init-delay: delay after initialization sequence [ms]
- - panel-width-mm: physical panel width [mm]
- - panel-height-mm: physical panel height [mm]
- - flip-horizontal: boolean to flip image horizontally
- - flip-vertical: boolean to flip image vertically
-
-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/display/panel/display-timing.txt
-[2]: Documentation/devicetree/bindings/media/video-interfaces.txt
-
-Example:
-
- panel {
- compatible = "samsung,s6e8aa0";
- reg = <0>;
- vdd3-supply = <&vcclcd_reg>;
- vci-supply = <&vlcd_reg>;
- reset-gpios = <&gpy4 5 0>;
- power-on-delay= <50>;
- reset-delay = <100>;
- init-delay = <100>;
- panel-width-mm = <58>;
- panel-height-mm = <103>;
- flip-horizontal;
- flip-vertical;
-
- display-timings {
- timing0: timing-0 {
- clock-frequency = <57153600>;
- hactive = <720>;
- vactive = <1280>;
- hfront-porch = <5>;
- hback-porch = <5>;
- hsync-len = <5>;
- vfront-porch = <13>;
- vback-porch = <1>;
- vsync-len = <2>;
- };
- };
- };
diff --git a/Documentation/devicetree/bindings/display/panel/samsung,s6e8aa0.yaml b/Documentation/devicetree/bindings/display/panel/samsung,s6e8aa0.yaml
new file mode 100644
index 0000000..ca95945
--- /dev/null
+++ b/Documentation/devicetree/bindings/display/panel/samsung,s6e8aa0.yaml
@@ -0,0 +1,100 @@
+# SPDX-License-Identifier: GPL-2.0
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/display/panel/samsung,s6e8aa0.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Samsung S6E8AA0 AMOLED LCD 5.3 inch panel
+
+maintainers:
+ - Andrzej Hajda <a.hajda@samsung.com>
+
+allOf:
+ - $ref: panel-common.yaml#
+
+properties:
+ compatible:
+ const: samsung,s6e8aa0
+
+ reg: true
+ reset-gpios: true
+ display-timings: true
+
+ vdd3-supply:
+ description: core voltage supply
+
+ vci-supply:
+ description: voltage supply for analog circuits
+
+ power-on-delay:
+ description: delay after turning regulators on [ms]
+ $ref: /schemas/types.yaml#/definitions/uint32
+
+ reset-delay:
+ description: delay after reset sequence [ms]
+ $ref: /schemas/types.yaml#/definitions/uint32
+
+ init-delay:
+ description: delay after initialization sequence [ms]
+
+ panel-width-mm:
+ description: physical panel width [mm]
+
+ panel-height-mm:
+ description: physical panel height [mm]
+
+ flip-horizontal:
+ description: boolean to flip image horizontally
+ type: boolean
+
+ flip-vertical:
+ description: boolean to flip image vertically
+ type: boolean
+
+required:
+ - compatible
+ - reg
+ - vdd3-supply
+ - vci-supply
+ - reset-gpios
+ - display-timings
+
+additionalProperties: false
+
+examples:
+ - |
+ dsi {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ panel@0 {
+ compatible = "samsung,s6e8aa0";
+ reg = <0>;
+ vdd3-supply = <&vcclcd_reg>;
+ vci-supply = <&vlcd_reg>;
+ reset-gpios = <&gpy4 5 0>;
+ power-on-delay= <50>;
+ reset-delay = <100>;
+ init-delay = <100>;
+ panel-width-mm = <58>;
+ panel-height-mm = <103>;
+ flip-horizontal;
+ flip-vertical;
+
+ display-timings {
+ timing0: timing-0 {
+ clock-frequency = <57153600>;
+ hactive = <720>;
+ vactive = <1280>;
+ hfront-porch = <5>;
+ hback-porch = <5>;
+ hsync-len = <5>;
+ vfront-porch = <13>;
+ vback-porch = <1>;
+ vsync-len = <2>;
+ };
+ };
+ };
+ };
+
+...
diff --git a/Documentation/devicetree/bindings/display/panel/sharp,lq101r1sx01.txt b/Documentation/devicetree/bindings/display/panel/sharp,lq101r1sx01.txt
deleted file mode 100644
index f522bb8..0000000
--- a/Documentation/devicetree/bindings/display/panel/sharp,lq101r1sx01.txt
+++ /dev/null
@@ -1,49 +0,0 @@
-Sharp Microelectronics 10.1" WQXGA TFT LCD panel
-
-This panel requires a dual-channel DSI host to operate. It supports two modes:
-- left-right: each channel drives the left or right half of the screen
-- even-odd: each channel drives the even or odd lines of the screen
-
-Each of the DSI channels controls a separate DSI peripheral. The peripheral
-driven by the first link (DSI-LINK1), left or even, is considered the primary
-peripheral and controls the device. The 'link2' property contains a phandle
-to the peripheral driven by the second link (DSI-LINK2, right or odd).
-
-Note that in video mode the DSI-LINK1 interface always provides the left/even
-pixels and DSI-LINK2 always provides the right/odd pixels. In command mode it
-is possible to program either link to drive the left/even or right/odd pixels
-but for the sake of consistency this binding assumes that the same assignment
-is chosen as for video mode.
-
-Required properties:
-- compatible: should be "sharp,lq101r1sx01"
-- reg: DSI virtual channel of the peripheral
-
-Required properties (for DSI-LINK1 only):
-- link2: phandle to the DSI peripheral on the secondary link. Note that the
- presence of this property marks the containing node as DSI-LINK1.
-- power-supply: phandle of the regulator that provides the supply voltage
-
-Optional properties (for DSI-LINK1 only):
-- backlight: phandle of the backlight device attached to the panel
-
-Example:
-
- dsi@54300000 {
- panel: panel@0 {
- compatible = "sharp,lq101r1sx01";
- reg = <0>;
-
- link2 = <&secondary>;
-
- power-supply = <...>;
- backlight = <...>;
- };
- };
-
- dsi@54400000 {
- secondary: panel@0 {
- compatible = "sharp,lq101r1sx01";
- reg = <0>;
- };
- };
diff --git a/Documentation/devicetree/bindings/display/panel/sharp,lq101r1sx01.yaml b/Documentation/devicetree/bindings/display/panel/sharp,lq101r1sx01.yaml
new file mode 100644
index 0000000..a679d36
--- /dev/null
+++ b/Documentation/devicetree/bindings/display/panel/sharp,lq101r1sx01.yaml
@@ -0,0 +1,87 @@
+# SPDX-License-Identifier: GPL-2.0
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/display/panel/sharp,lq101r1sx01.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Sharp Microelectronics 10.1" WQXGA TFT LCD panel
+
+maintainers:
+ - Thierry Reding <treding@nvidia.com>
+
+description: |
+ This panel requires a dual-channel DSI host to operate. It supports two modes:
+ - left-right: each channel drives the left or right half of the screen
+ - even-odd: each channel drives the even or odd lines of the screen
+
+ Each of the DSI channels controls a separate DSI peripheral. The peripheral
+ driven by the first link (DSI-LINK1), left or even, is considered the primary
+ peripheral and controls the device. The 'link2' property contains a phandle
+ to the peripheral driven by the second link (DSI-LINK2, right or odd).
+
+ Note that in video mode the DSI-LINK1 interface always provides the left/even
+ pixels and DSI-LINK2 always provides the right/odd pixels. In command mode it
+ is possible to program either link to drive the left/even or right/odd pixels
+ but for the sake of consistency this binding assumes that the same assignment
+ is chosen as for video mode.
+
+allOf:
+ - $ref: panel-common.yaml#
+
+properties:
+ compatible:
+ const: sharp,lq101r1sx01
+
+ reg: true
+ power-supply: true
+ backlight: true
+
+ link2:
+ $ref: /schemas/types.yaml#/definitions/phandle
+ description: |
+ phandle to the DSI peripheral on the secondary link. Note that the
+ presence of this property marks the containing node as DSI-LINK1
+
+required:
+ - compatible
+ - reg
+
+if:
+ required:
+ - link2
+then:
+ required:
+ - power-supply
+
+additionalProperties: false
+
+examples:
+ - |
+ dsi0: dsi@fd922800 {
+ #address-cells = <1>;
+ #size-cells = <0>;
+ reg = <0xfd922800 0x200>;
+
+ panel: panel@0 {
+ compatible = "sharp,lq101r1sx01";
+ reg = <0>;
+
+ link2 = <&secondary>;
+
+ power-supply = <&power>;
+ backlight = <&backlight>;
+ };
+ };
+
+ dsi1: dsi@fd922a00 {
+ #address-cells = <1>;
+ #size-cells = <0>;
+ reg = <0xfd922a00 0x200>;
+
+ secondary: panel@0 {
+ compatible = "sharp,lq101r1sx01";
+ reg = <0>;
+ };
+ };
+
+...
diff --git a/Documentation/devicetree/bindings/display/rockchip/rockchip-drm.yaml b/Documentation/devicetree/bindings/display/rockchip/rockchip-drm.yaml
index ec8ae74..7204da5 100644
--- a/Documentation/devicetree/bindings/display/rockchip/rockchip-drm.yaml
+++ b/Documentation/devicetree/bindings/display/rockchip/rockchip-drm.yaml
@@ -24,7 +24,7 @@
description: |
Should contain a list of phandles pointing to display interface port
of vop devices. vop definitions as defined in
- Documentation/devicetree/bindings/display/rockchip/rockchip-vop.txt
+ Documentation/devicetree/bindings/display/rockchip/rockchip-vop.yaml
required:
- compatible
diff --git a/Documentation/devicetree/bindings/display/simple-framebuffer.yaml b/Documentation/devicetree/bindings/display/simple-framebuffer.yaml
index 1db608c..eaf8c54 100644
--- a/Documentation/devicetree/bindings/display/simple-framebuffer.yaml
+++ b/Documentation/devicetree/bindings/display/simple-framebuffer.yaml
@@ -152,28 +152,28 @@
examples:
- |
- aliases {
- display0 = &lcdc0;
- };
+ / {
+ compatible = "foo";
+ model = "foo";
+ #address-cells = <1>;
+ #size-cells = <1>;
- chosen {
- #address-cells = <1>;
- #size-cells = <1>;
- stdout-path = "display0";
- framebuffer0: framebuffer@1d385000 {
- compatible = "allwinner,simple-framebuffer", "simple-framebuffer";
- allwinner,pipeline = "de_be0-lcd0";
- reg = <0x1d385000 3840000>;
- width = <1600>;
- height = <1200>;
- stride = <3200>;
- format = "r5g6b5";
- clocks = <&ahb_gates 36>, <&ahb_gates 43>, <&ahb_gates 44>;
- lcd-supply = <®_dc1sw>;
- display = <&lcdc0>;
- };
+ chosen {
+ #address-cells = <1>;
+ #size-cells = <1>;
+ framebuffer0: framebuffer@1d385000 {
+ compatible = "allwinner,simple-framebuffer", "simple-framebuffer";
+ allwinner,pipeline = "de_be0-lcd0";
+ reg = <0x1d385000 3840000>;
+ width = <1600>;
+ height = <1200>;
+ stride = <3200>;
+ format = "r5g6b5";
+ clocks = <&ahb_gates 36>, <&ahb_gates 43>, <&ahb_gates 44>;
+ lcd-supply = <®_dc1sw>;
+ display = <&lcdc0>;
+ };
+ };
};
- lcdc0: lcdc { };
-
...
diff --git a/Documentation/devicetree/bindings/display/tilcdc/tilcdc.txt b/Documentation/devicetree/bindings/display/tilcdc/tilcdc.txt
index aac617a..8b2a713 100644
--- a/Documentation/devicetree/bindings/display/tilcdc/tilcdc.txt
+++ b/Documentation/devicetree/bindings/display/tilcdc/tilcdc.txt
@@ -46,7 +46,7 @@
crossed and LCD_DATA[0:4] is for Red[3:7] and LCD_DATA[11:15] is
for Blue[3-7]. For more details see section 3.1.1 in AM335x
Silicon Errata:
- http://www.ti.com/general/docs/lit/getliterature.tsp?baseLiteratureNumber=sprz360
+ https://www.ti.com/general/docs/lit/getliterature.tsp?baseLiteratureNumber=sprz360
Example:
diff --git a/Documentation/devicetree/bindings/display/xlnx/xlnx,zynqmp-dpsub.yaml b/Documentation/devicetree/bindings/display/xlnx/xlnx,zynqmp-dpsub.yaml
new file mode 100644
index 0000000..52a939c
--- /dev/null
+++ b/Documentation/devicetree/bindings/display/xlnx/xlnx,zynqmp-dpsub.yaml
@@ -0,0 +1,174 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/display/xlnx/xlnx,zynqmp-dpsub.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Xilinx ZynqMP DisplayPort Subsystem
+
+description: |
+ The DisplayPort subsystem of Xilinx ZynqMP (Zynq UltraScale+ MPSoC)
+ implements the display and audio pipelines based on the DisplayPort v1.2
+ standard. The subsystem includes multiple functional blocks as below:
+
+ +------------------------------------------------------------+
+ +--------+ | +----------------+ +-----------+ |
+ | DPDMA | --->| | --> | Video | Video +-------------+ |
+ | 4x vid | | | | | Rendering | -+--> | | | +------+
+ | 2x aud | | | Audio/Video | --> | Pipeline | | | DisplayPort |---> | PHY0 |
+ +--------+ | | Buffer Manager | +-----------+ | | Source | | +------+
+ | | and STC | +-----------+ | | Controller | | +------+
+ Live Video --->| | --> | Audio | Audio | |---> | PHY1 |
+ | | | | Mixer | --+-> | | | +------+
+ Live Audio --->| | --> | | || +-------------+ |
+ | +----------------+ +-----------+ || |
+ +---------------------------------------||-------------------+
+ vv
+ Blended Video and
+ Mixed Audio to PL
+
+ The Buffer Manager interacts with external interface such as DMA engines or
+ live audio/video streams from the programmable logic. The Video Rendering
+ Pipeline blends the video and graphics layers and performs colorspace
+ conversion. The Audio Mixer mixes the incoming audio streams. The DisplayPort
+ Source Controller handles the DisplayPort protocol and connects to external
+ PHYs.
+
+ The subsystem supports 2 video and 2 audio streams, and various pixel formats
+ and depths up to 4K@30 resolution.
+
+ Please refer to "Zynq UltraScale+ Device Technical Reference Manual"
+ (https://www.xilinx.com/support/documentation/user_guides/ug1085-zynq-ultrascale-trm.pdf)
+ for more details.
+
+maintainers:
+ - Laurent Pinchart <laurent.pinchart@ideasonboard.com>
+
+properties:
+ compatible:
+ const: xlnx,zynqmp-dpsub-1.7
+
+ reg:
+ maxItems: 4
+ reg-names:
+ items:
+ - const: dp
+ - const: blend
+ - const: av_buf
+ - const: aud
+
+ interrupts:
+ maxItems: 1
+
+ clocks:
+ description:
+ The APB clock and at least one video clock are mandatory, the audio clock
+ is optional.
+ minItems: 2
+ maxItems: 4
+ items:
+ - description: dp_apb_clk is the APB clock
+ - description: dp_aud_clk is the Audio clock
+ - description:
+ dp_vtc_pixel_clk_in is the non-live video clock (from Processing
+ System)
+ - description:
+ dp_live_video_in_clk is the live video clock (from Programmable
+ Logic)
+ clock-names:
+ oneOf:
+ - minItems: 2
+ maxItems: 3
+ items:
+ - const: dp_apb_clk
+ - enum: [ dp_vtc_pixel_clk_in, dp_live_video_in_clk ]
+ - enum: [ dp_vtc_pixel_clk_in, dp_live_video_in_clk ]
+ - minItems: 3
+ maxItems: 4
+ items:
+ - const: dp_apb_clk
+ - const: dp_aud_clk
+ - enum: [ dp_vtc_pixel_clk_in, dp_live_video_in_clk ]
+ - enum: [ dp_vtc_pixel_clk_in, dp_live_video_in_clk ]
+
+ power-domains:
+ maxItems: 1
+
+ resets:
+ maxItems: 1
+
+ dmas:
+ maxItems: 4
+ items:
+ - description: Video layer, plane 0 (RGB or luma)
+ - description: Video layer, plane 1 (U/V or U)
+ - description: Video layer, plane 2 (V)
+ - description: Graphics layer
+ dma-names:
+ items:
+ - const: vid0
+ - const: vid1
+ - const: vid2
+ - const: gfx0
+
+ phys:
+ description: PHYs for the DP data lanes
+ minItems: 1
+ maxItems: 2
+ phy-names:
+ minItems: 1
+ maxItems: 2
+ items:
+ - const: dp-phy0
+ - const: dp-phy1
+
+required:
+ - compatible
+ - reg
+ - reg-names
+ - interrupts
+ - clocks
+ - clock-names
+ - power-domains
+ - resets
+ - dmas
+ - dma-names
+ - phys
+ - phy-names
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/phy/phy.h>
+ #include <dt-bindings/reset/xlnx-zynqmp-resets.h>
+
+ display@fd4a0000 {
+ compatible = "xlnx,zynqmp-dpsub-1.7";
+ reg = <0x0 0xfd4a0000 0x0 0x1000>,
+ <0x0 0xfd4aa000 0x0 0x1000>,
+ <0x0 0xfd4ab000 0x0 0x1000>,
+ <0x0 0xfd4ac000 0x0 0x1000>;
+ reg-names = "dp", "blend", "av_buf", "aud";
+ interrupts = <0 119 4>;
+ interrupt-parent = <&gic>;
+
+ clock-names = "dp_apb_clk", "dp_aud_clk", "dp_live_video_in_clk";
+ clocks = <&dp_aclk>, <&clkc 17>, <&si570_1>;
+
+ power-domains = <&pd_dp>;
+ resets = <&reset ZYNQMP_RESET_DP>;
+
+ dma-names = "vid0", "vid1", "vid2", "gfx0";
+ dmas = <&xlnx_dpdma 0>,
+ <&xlnx_dpdma 1>,
+ <&xlnx_dpdma 2>,
+ <&xlnx_dpdma 3>;
+
+ phys = <&psgtr 1 PHY_TYPE_DP 0 3 27000000>,
+ <&psgtr 0 PHY_TYPE_DP 1 3 27000000>;
+
+ phy-names = "dp-phy0", "dp-phy1";
+ };
+
+...
diff --git a/Documentation/devicetree/bindings/dma/arm-pl330.txt b/Documentation/devicetree/bindings/dma/arm-pl330.txt
index 2c7fd19..315e901 100644
--- a/Documentation/devicetree/bindings/dma/arm-pl330.txt
+++ b/Documentation/devicetree/bindings/dma/arm-pl330.txt
@@ -16,6 +16,7 @@
- dma-channels: contains the total number of DMA channels supported by the DMAC
- dma-requests: contains the total number of DMA requests supported by the DMAC
- arm,pl330-broken-no-flushp: quirk for avoiding to execute DMAFLUSHP
+ - arm,pl330-periph-burst: quirk for performing burst transfer only
- resets: contains an entry for each entry in reset-names.
See ../reset/reset.txt for details.
- reset-names: must contain at least "dma", and optional is "dma-ocp".
diff --git a/Documentation/devicetree/bindings/dma/owl-dma.txt b/Documentation/devicetree/bindings/dma/owl-dma.txt
deleted file mode 100644
index 03e9bb12..0000000
--- a/Documentation/devicetree/bindings/dma/owl-dma.txt
+++ /dev/null
@@ -1,47 +0,0 @@
-* Actions Semi Owl SoCs DMA controller
-
-This binding follows the generic DMA bindings defined in dma.txt.
-
-Required properties:
-- compatible: Should be "actions,s900-dma".
-- reg: Should contain DMA registers location and length.
-- interrupts: Should contain 4 interrupts shared by all channel.
-- #dma-cells: Must be <1>. Used to represent the number of integer
- cells in the dmas property of client device.
-- dma-channels: Physical channels supported.
-- dma-requests: Number of DMA request signals supported by the controller.
- Refer to Documentation/devicetree/bindings/dma/dma.txt
-- clocks: Phandle and Specifier of the clock feeding the DMA controller.
-
-Example:
-
-Controller:
- dma: dma-controller@e0260000 {
- compatible = "actions,s900-dma";
- reg = <0x0 0xe0260000 0x0 0x1000>;
- interrupts = <GIC_SPI 57 IRQ_TYPE_LEVEL_HIGH>,
- <GIC_SPI 58 IRQ_TYPE_LEVEL_HIGH>,
- <GIC_SPI 59 IRQ_TYPE_LEVEL_HIGH>,
- <GIC_SPI 60 IRQ_TYPE_LEVEL_HIGH>;
- #dma-cells = <1>;
- dma-channels = <12>;
- dma-requests = <46>;
- clocks = <&clock CLK_DMAC>;
- };
-
-Client:
-
-DMA clients connected to the Actions Semi Owl SoCs DMA controller must
-use the format described in the dma.txt file, using a two-cell specifier
-for each channel.
-
-The two cells in order are:
-1. A phandle pointing to the DMA controller.
-2. The channel id.
-
-uart5: serial@e012a000 {
- ...
- dma-names = "tx", "rx";
- dmas = <&dma 26>, <&dma 27>;
- ...
-};
diff --git a/Documentation/devicetree/bindings/dma/owl-dma.yaml b/Documentation/devicetree/bindings/dma/owl-dma.yaml
new file mode 100644
index 0000000..256d62a
--- /dev/null
+++ b/Documentation/devicetree/bindings/dma/owl-dma.yaml
@@ -0,0 +1,79 @@
+# SPDX-License-Identifier: GPL-2.0
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/dma/owl-dma.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Actions Semi Owl SoCs DMA controller
+
+description: |
+ The OWL DMA is a general-purpose direct memory access controller capable of
+ supporting 10 and 12 independent DMA channels for S700 and S900 SoCs
+ respectively.
+
+maintainers:
+ - Manivannan Sadhasivam <manivannan.sadhasivam@linaro.org>
+
+allOf:
+ - $ref: "dma-controller.yaml#"
+
+properties:
+ compatible:
+ enum:
+ - actions,s900-dma
+ - actions,s700-dma
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ description:
+ controller supports 4 interrupts, which are freely assignable to the
+ DMA channels.
+ maxItems: 4
+
+ "#dma-cells":
+ const: 1
+
+ dma-channels:
+ maximum: 12
+
+ dma-requests:
+ maximum: 46
+
+ clocks:
+ maxItems: 1
+ description:
+ Phandle and Specifier of the clock feeding the DMA controller.
+
+ power-domains:
+ maxItems: 1
+
+required:
+ - compatible
+ - reg
+ - interrupts
+ - "#dma-cells"
+ - dma-channels
+ - dma-requests
+ - clocks
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+ dma: dma-controller@e0260000 {
+ compatible = "actions,s900-dma";
+ reg = <0xe0260000 0x1000>;
+ interrupts = <GIC_SPI 57 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 58 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 59 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 60 IRQ_TYPE_LEVEL_HIGH>;
+ #dma-cells = <1>;
+ dma-channels = <12>;
+ dma-requests = <46>;
+ clocks = <&clock 22>;
+ };
+
+...
diff --git a/Documentation/devicetree/bindings/dma/renesas,rcar-dmac.yaml b/Documentation/devicetree/bindings/dma/renesas,rcar-dmac.yaml
index b842dfd9..13f1a46 100644
--- a/Documentation/devicetree/bindings/dma/renesas,rcar-dmac.yaml
+++ b/Documentation/devicetree/bindings/dma/renesas,rcar-dmac.yaml
@@ -23,6 +23,7 @@
- renesas,dmac-r8a774a1 # RZ/G2M
- renesas,dmac-r8a774b1 # RZ/G2N
- renesas,dmac-r8a774c0 # RZ/G2E
+ - renesas,dmac-r8a774e1 # RZ/G2H
- renesas,dmac-r8a7790 # R-Car H2
- renesas,dmac-r8a7791 # R-Car M2-W
- renesas,dmac-r8a7792 # R-Car V2H
diff --git a/Documentation/devicetree/bindings/dma/renesas,usb-dmac.yaml b/Documentation/devicetree/bindings/dma/renesas,usb-dmac.yaml
index 9ca6d8d..ab287c6 100644
--- a/Documentation/devicetree/bindings/dma/renesas,usb-dmac.yaml
+++ b/Documentation/devicetree/bindings/dma/renesas,usb-dmac.yaml
@@ -16,6 +16,7 @@
compatible:
items:
- enum:
+ - renesas,r8a7742-usb-dmac # RZ/G1H
- renesas,r8a7743-usb-dmac # RZ/G1M
- renesas,r8a7744-usb-dmac # RZ/G1N
- renesas,r8a7745-usb-dmac # RZ/G1E
@@ -23,6 +24,7 @@
- renesas,r8a774a1-usb-dmac # RZ/G2M
- renesas,r8a774b1-usb-dmac # RZ/G2N
- renesas,r8a774c0-usb-dmac # RZ/G2E
+ - renesas,r8a774e1-usb-dmac # RZ/G2H
- renesas,r8a7790-usb-dmac # R-Car H2
- renesas,r8a7791-usb-dmac # R-Car M2-W
- renesas,r8a7793-usb-dmac # R-Car M2-N
diff --git a/Documentation/devicetree/bindings/dma/snps,dma-spear1340.yaml b/Documentation/devicetree/bindings/dma/snps,dma-spear1340.yaml
new file mode 100644
index 0000000..20870f5
--- /dev/null
+++ b/Documentation/devicetree/bindings/dma/snps,dma-spear1340.yaml
@@ -0,0 +1,176 @@
+# SPDX-License-Identifier: GPL-2.0-only
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/dma/snps,dma-spear1340.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Synopsys Designware DMA Controller
+
+maintainers:
+ - Viresh Kumar <vireshk@kernel.org>
+ - Andy Shevchenko <andriy.shevchenko@linux.intel.com>
+
+allOf:
+ - $ref: "dma-controller.yaml#"
+
+properties:
+ compatible:
+ const: snps,dma-spear1340
+
+ "#dma-cells":
+ const: 3
+ description: |
+ First cell is a phandle pointing to the DMA controller. Second one is
+ the DMA request line number. Third cell is the memory master identifier
+ for transfers on dynamically allocated channel. Fourth cell is the
+ peripheral master identifier for transfers on an allocated channel.
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+ clocks:
+ maxItems: 1
+
+ clock-names:
+ description: AHB interface reference clock.
+ const: hclk
+
+ dma-channels:
+ description: |
+ Number of DMA channels supported by the controller. In case if
+ not specified the driver will try to auto-detect this and
+ the rest of the optional parameters.
+ minimum: 1
+ maximum: 8
+
+ dma-requests:
+ minimum: 1
+ maximum: 16
+
+ dma-masters:
+ $ref: /schemas/types.yaml#definitions/uint32
+ description: |
+ Number of DMA masters supported by the controller. In case if
+ not specified the driver will try to auto-detect this and
+ the rest of the optional parameters.
+ minimum: 1
+ maximum: 4
+
+ chan_allocation_order:
+ $ref: /schemas/types.yaml#definitions/uint32
+ description: |
+ DMA channels allocation order specifier. Zero means ascending order
+ (first free allocated), while one - descending (last free allocated).
+ default: 0
+ enum: [0, 1]
+
+ chan_priority:
+ $ref: /schemas/types.yaml#definitions/uint32
+ description: |
+ DMA channels priority order. Zero means ascending channels priority
+ so the very first channel has the highest priority. While 1 means
+ descending priority (the last channel has the highest priority).
+ default: 0
+ enum: [0, 1]
+
+ block_size:
+ $ref: /schemas/types.yaml#definitions/uint32
+ description: Maximum block size supported by the DMA controller.
+ enum: [3, 7, 15, 31, 63, 127, 255, 511, 1023, 2047, 4095]
+
+ data-width:
+ $ref: /schemas/types.yaml#/definitions/uint32-array
+ description: Data bus width per each DMA master in bytes.
+ items:
+ maxItems: 4
+ items:
+ enum: [4, 8, 16, 32]
+
+ data_width:
+ $ref: /schemas/types.yaml#/definitions/uint32-array
+ deprecated: true
+ description: |
+ Data bus width per each DMA master in (2^n * 8) bits. This property is
+ deprecated. It' usage is discouraged in favor of data-width one. Moreover
+ the property incorrectly permits to define data-bus width of 8 and 16
+ bits, which is impossible in accordance with DW DMAC IP-core data book.
+ items:
+ maxItems: 4
+ items:
+ enum:
+ - 0 # 8 bits
+ - 1 # 16 bits
+ - 2 # 32 bits
+ - 3 # 64 bits
+ - 4 # 128 bits
+ - 5 # 256 bits
+ default: 0
+
+ multi-block:
+ $ref: /schemas/types.yaml#/definitions/uint32-array
+ description: |
+ LLP-based multi-block transfer supported by hardware per
+ each DMA channel.
+ items:
+ maxItems: 8
+ items:
+ enum: [0, 1]
+ default: 1
+
+ snps,max-burst-len:
+ $ref: /schemas/types.yaml#/definitions/uint32-array
+ description: |
+ Maximum length of the burst transactions supported by the controller.
+ This property defines the upper limit of the run-time burst setting
+ (CTLx.SRC_MSIZE/CTLx.DST_MSIZE fields) so the allowed burst length
+ will be from 1 to max-burst-len words. It's an array property with one
+ cell per channel in the units determined by the value set in the
+ CTLx.SRC_TR_WIDTH/CTLx.DST_TR_WIDTH fields (data width).
+ items:
+ maxItems: 8
+ items:
+ enum: [4, 8, 16, 32, 64, 128, 256]
+ default: 256
+
+ snps,dma-protection-control:
+ $ref: /schemas/types.yaml#definitions/uint32
+ description: |
+ Bits one-to-one passed to the AHB HPROT[3:1] bus. Each bit setting
+ indicates the following features: bit 0 - privileged mode,
+ bit 1 - DMA is bufferable, bit 2 - DMA is cacheable.
+ default: 0
+ minimum: 0
+ maximum: 7
+
+unevaluatedProperties: false
+
+required:
+ - compatible
+ - "#dma-cells"
+ - reg
+ - interrupts
+
+examples:
+ - |
+ dma-controller@fc000000 {
+ compatible = "snps,dma-spear1340";
+ reg = <0xfc000000 0x1000>;
+ interrupt-parent = <&vic1>;
+ interrupts = <12>;
+
+ dma-channels = <8>;
+ dma-requests = <16>;
+ dma-masters = <4>;
+ #dma-cells = <3>;
+
+ chan_allocation_order = <1>;
+ chan_priority = <1>;
+ block_size = <0xfff>;
+ data-width = <8 8>;
+ multi-block = <0 0 0 0 0 0 0 0>;
+ snps,max-burst-len = <16 16 4 4 4 4 4 4>;
+ };
+...
diff --git a/Documentation/devicetree/bindings/dma/snps-dma.txt b/Documentation/devicetree/bindings/dma/snps-dma.txt
deleted file mode 100644
index 0bedcee..0000000
--- a/Documentation/devicetree/bindings/dma/snps-dma.txt
+++ /dev/null
@@ -1,69 +0,0 @@
-* Synopsys Designware DMA Controller
-
-Required properties:
-- compatible: "snps,dma-spear1340"
-- reg: Address range of the DMAC registers
-- interrupt: Should contain the DMAC interrupt number
-- dma-channels: Number of channels supported by hardware
-- dma-requests: Number of DMA request lines supported, up to 16
-- dma-masters: Number of AHB masters supported by the controller
-- #dma-cells: must be <3>
-- chan_allocation_order: order of allocation of channel, 0 (default): ascending,
- 1: descending
-- chan_priority: priority of channels. 0 (default): increase from chan 0->n, 1:
- increase from chan n->0
-- block_size: Maximum block size supported by the controller
-- data-width: Maximum data width supported by hardware per AHB master
- (in bytes, power of 2)
-
-
-Deprecated properties:
-- data_width: Maximum data width supported by hardware per AHB master
- (0 - 8bits, 1 - 16bits, ..., 5 - 256bits)
-
-
-Optional properties:
-- multi-block: Multi block transfers supported by hardware. Array property with
- one cell per channel. 0: not supported, 1 (default): supported.
-- snps,dma-protection-control: AHB HPROT[3:1] protection setting.
- The default value is 0 (for non-cacheable, non-buffered,
- unprivileged data access).
- Refer to include/dt-bindings/dma/dw-dmac.h for possible values.
-
-Example:
-
- dmahost: dma@fc000000 {
- compatible = "snps,dma-spear1340";
- reg = <0xfc000000 0x1000>;
- interrupt-parent = <&vic1>;
- interrupts = <12>;
-
- dma-channels = <8>;
- dma-requests = <16>;
- dma-masters = <2>;
- #dma-cells = <3>;
- chan_allocation_order = <1>;
- chan_priority = <1>;
- block_size = <0xfff>;
- data-width = <8 8>;
- };
-
-DMA clients connected to the Designware DMA controller must use the format
-described in the dma.txt file, using a four-cell specifier for each channel.
-The four cells in order are:
-
-1. A phandle pointing to the DMA controller
-2. The DMA request line number
-3. Memory master for transfers on allocated channel
-4. Peripheral master for transfers on allocated channel
-
-Example:
-
- serial@e0000000 {
- compatible = "arm,pl011", "arm,primecell";
- reg = <0xe0000000 0x1000>;
- interrupts = <0 35 0x4>;
- dmas = <&dmahost 12 0 1>,
- <&dmahost 13 1 0>;
- dma-names = "rx", "rx";
- };
diff --git a/Documentation/devicetree/bindings/dma/xilinx/xlnx,zynqmp-dpdma.yaml b/Documentation/devicetree/bindings/dma/xilinx/xlnx,zynqmp-dpdma.yaml
new file mode 100644
index 0000000..5de510f
--- /dev/null
+++ b/Documentation/devicetree/bindings/dma/xilinx/xlnx,zynqmp-dpdma.yaml
@@ -0,0 +1,68 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/dma/xilinx/xlnx,zynqmp-dpdma.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Xilinx ZynqMP DisplayPort DMA Controller Device Tree Bindings
+
+description: |
+ These bindings describe the DMA engine included in the Xilinx ZynqMP
+ DisplayPort Subsystem. The DMA engine supports up to 6 DMA channels (3
+ channels for a video stream, 1 channel for a graphics stream, and 2 channels
+ for an audio stream).
+
+maintainers:
+ - Laurent Pinchart <laurent.pinchart@ideasonboard.com>
+
+allOf:
+ - $ref: "../dma-controller.yaml#"
+
+properties:
+ "#dma-cells":
+ const: 1
+ description: |
+ The cell is the DMA channel ID (see dt-bindings/dma/xlnx-zynqmp-dpdma.h
+ for a list of channel IDs).
+
+ compatible:
+ const: xlnx,zynqmp-dpdma
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+ clocks:
+ description: The AXI clock
+ maxItems: 1
+
+ clock-names:
+ const: axi_clk
+
+required:
+ - "#dma-cells"
+ - compatible
+ - reg
+ - interrupts
+ - clocks
+ - clock-names
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+
+ dma: dma-controller@fd4c0000 {
+ compatible = "xlnx,zynqmp-dpdma";
+ reg = <0x0 0xfd4c0000 0x0 0x1000>;
+ interrupts = <GIC_SPI 122 IRQ_TYPE_LEVEL_HIGH>;
+ interrupt-parent = <&gic>;
+ clocks = <&dpdma_clk>;
+ clock-names = "axi_clk";
+ #dma-cells = <1>;
+ };
+
+...
diff --git a/Documentation/devicetree/bindings/firmware/qcom,scm.txt b/Documentation/devicetree/bindings/firmware/qcom,scm.txt
index 354b448..7845643 100644
--- a/Documentation/devicetree/bindings/firmware/qcom,scm.txt
+++ b/Documentation/devicetree/bindings/firmware/qcom,scm.txt
@@ -11,10 +11,12 @@
* "qcom,scm-apq8084"
* "qcom,scm-ipq4019"
* "qcom,scm-ipq806x"
+ * "qcom,scm-ipq8074"
* "qcom,scm-msm8660"
* "qcom,scm-msm8916"
* "qcom,scm-msm8960"
* "qcom,scm-msm8974"
+ * "qcom,scm-msm8994"
* "qcom,scm-msm8996"
* "qcom,scm-msm8998"
* "qcom,scm-sc7180"
diff --git a/Documentation/devicetree/bindings/fpga/fpga-region.txt b/Documentation/devicetree/bindings/fpga/fpga-region.txt
index 8ab19d1..e811cf8 100644
--- a/Documentation/devicetree/bindings/fpga/fpga-region.txt
+++ b/Documentation/devicetree/bindings/fpga/fpga-region.txt
@@ -493,4 +493,4 @@
--
[1] www.altera.com/content/dam/altera-www/global/en_US/pdfs/literature/ug/ug_partrecon.pdf
[2] tspace.library.utoronto.ca/bitstream/1807/67932/1/Byma_Stuart_A_201411_MAS_thesis.pdf
-[3] http://www.xilinx.com/support/documentation/sw_manuals/xilinx14_1/ug702.pdf
+[3] https://www.xilinx.com/support/documentation/sw_manuals/xilinx14_1/ug702.pdf
diff --git a/Documentation/devicetree/bindings/fpga/xilinx-slave-serial.txt b/Documentation/devicetree/bindings/fpga/xilinx-slave-serial.txt
index cfa4ed4..5ef659c 100644
--- a/Documentation/devicetree/bindings/fpga/xilinx-slave-serial.txt
+++ b/Documentation/devicetree/bindings/fpga/xilinx-slave-serial.txt
@@ -1,11 +1,14 @@
Xilinx Slave Serial SPI FPGA Manager
-Xilinx Spartan-6 FPGAs support a method of loading the bitstream over
-what is referred to as "slave serial" interface.
+Xilinx Spartan-6 and 7 Series FPGAs support a method of loading the
+bitstream over what is referred to as "slave serial" interface.
The slave serial link is not technically SPI, and might require extra
circuits in order to play nicely with other SPI slaves on the same bus.
-See https://www.xilinx.com/support/documentation/user_guides/ug380.pdf
+See:
+- https://www.xilinx.com/support/documentation/user_guides/ug380.pdf
+- https://www.xilinx.com/support/documentation/user_guides/ug470_7Series_Config.pdf
+- https://www.xilinx.com/support/documentation/application_notes/xapp583-fpga-configuration.pdf
Required properties:
- compatible: should contain "xlnx,fpga-slave-serial"
@@ -13,6 +16,10 @@
- prog_b-gpios: config pin (referred to as PROGRAM_B in the manual)
- done-gpios: config status pin (referred to as DONE in the manual)
+Optional properties:
+- init-b-gpios: initialization status and configuration error pin
+ (referred to as INIT_B in the manual)
+
Example for full FPGA configuration:
fpga-region0 {
@@ -37,7 +44,8 @@
spi-max-frequency = <60000000>;
spi-cpha;
reg = <0>;
- done-gpios = <&gpio0 9 GPIO_ACTIVE_HIGH>;
prog_b-gpios = <&gpio0 29 GPIO_ACTIVE_LOW>;
+ init-b-gpios = <&gpio0 28 GPIO_ACTIVE_LOW>;
+ done-gpios = <&gpio0 9 GPIO_ACTIVE_HIGH>;
};
};
diff --git a/Documentation/devicetree/bindings/fuse/nvidia,tegra20-fuse.txt b/Documentation/devicetree/bindings/fuse/nvidia,tegra20-fuse.txt
index 41372d4..2aaf661 100644
--- a/Documentation/devicetree/bindings/fuse/nvidia,tegra20-fuse.txt
+++ b/Documentation/devicetree/bindings/fuse/nvidia,tegra20-fuse.txt
@@ -4,8 +4,9 @@
- compatible : For Tegra20, must contain "nvidia,tegra20-efuse". For Tegra30,
must contain "nvidia,tegra30-efuse". For Tegra114, must contain
"nvidia,tegra114-efuse". For Tegra124, must contain "nvidia,tegra124-efuse".
- Otherwise, must contain "nvidia,<chip>-efuse", plus one of the above, where
- <chip> is tegra132.
+ For Tegra132 must contain "nvidia,tegra132-efuse", "nvidia,tegra124-efuse".
+ For Tegra210 must contain "nvidia,tegra210-efuse". For Tegra186 must contain
+ "nvidia,tegra186-efuse". For Tegra194 must contain "nvidia,tegra194-efuse".
Details:
nvidia,tegra20-efuse: Tegra20 requires using APB DMA to read the fuse data
due to a hardware bug. Tegra20 also lacks certain information which is
diff --git a/Documentation/devicetree/bindings/gpio/gpio-pca953x.txt b/Documentation/devicetree/bindings/gpio/gpio-pca953x.txt
index dab537c..3126c38 100644
--- a/Documentation/devicetree/bindings/gpio/gpio-pca953x.txt
+++ b/Documentation/devicetree/bindings/gpio/gpio-pca953x.txt
@@ -19,6 +19,7 @@
nxp,pca9698
nxp,pcal6416
nxp,pcal6524
+ nxp,pcal9535
nxp,pcal9555a
maxim,max7310
maxim,max7312
diff --git a/Documentation/devicetree/bindings/gpio/gpio-pca9570.yaml b/Documentation/devicetree/bindings/gpio/gpio-pca9570.yaml
new file mode 100644
index 0000000..338c531
--- /dev/null
+++ b/Documentation/devicetree/bindings/gpio/gpio-pca9570.yaml
@@ -0,0 +1,47 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/gpio/gpio-pca9570.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: PCA9570 I2C GPO expander
+
+maintainers:
+ - Sungbo Eo <mans0n@gorani.run>
+
+properties:
+ compatible:
+ enum:
+ - nxp,pca9570
+
+ reg:
+ maxItems: 1
+
+ gpio-controller: true
+
+ '#gpio-cells':
+ const: 2
+
+required:
+ - compatible
+ - reg
+ - gpio-controller
+ - "#gpio-cells"
+
+additionalProperties: false
+
+examples:
+ - |
+ i2c0 {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ gpio@24 {
+ compatible = "nxp,pca9570";
+ reg = <0x24>;
+ gpio-controller;
+ #gpio-cells = <2>;
+ };
+ };
+
+...
diff --git a/Documentation/devicetree/bindings/gpio/gpio-zynq.txt b/Documentation/devicetree/bindings/gpio/gpio-zynq.txt
index 4fa4eb5..f693e82 100644
--- a/Documentation/devicetree/bindings/gpio/gpio-zynq.txt
+++ b/Documentation/devicetree/bindings/gpio/gpio-zynq.txt
@@ -6,7 +6,9 @@
- First cell is the GPIO line number
- Second cell is used to specify optional
parameters (unused)
-- compatible : Should be "xlnx,zynq-gpio-1.0" or "xlnx,zynqmp-gpio-1.0"
+- compatible : Should be "xlnx,zynq-gpio-1.0" or
+ "xlnx,zynqmp-gpio-1.0" or "xlnx,versal-gpio-1.0
+ or "xlnx,pmc-gpio-1.0
- clocks : Clock specifier (see clock bindings for details)
- gpio-controller : Marks the device node as a GPIO controller.
- interrupts : Interrupt specifier (see interrupt bindings for
diff --git a/Documentation/devicetree/bindings/gpio/mediatek,mt7621-gpio.txt b/Documentation/devicetree/bindings/gpio/mediatek,mt7621-gpio.txt
index ba45558..e1c49b6 100644
--- a/Documentation/devicetree/bindings/gpio/mediatek,mt7621-gpio.txt
+++ b/Documentation/devicetree/bindings/gpio/mediatek,mt7621-gpio.txt
@@ -12,7 +12,7 @@
Only the GPIO_ACTIVE_HIGH and GPIO_ACTIVE_LOW flags are supported.
- #interrupt-cells : Specifies the number of cells needed to encode an
interrupt. Should be 2. The first cell defines the interrupt number,
- the second encodes the triger flags encoded as described in
+ the second encodes the trigger flags encoded as described in
Documentation/devicetree/bindings/interrupt-controller/interrupts.txt
- compatible:
- "mediatek,mt7621-gpio" for Mediatek controllers
diff --git a/Documentation/devicetree/bindings/gpio/mrvl-gpio.txt b/Documentation/devicetree/bindings/gpio/mrvl-gpio.txt
deleted file mode 100644
index 30fd220..0000000
--- a/Documentation/devicetree/bindings/gpio/mrvl-gpio.txt
+++ /dev/null
@@ -1,48 +0,0 @@
-* Marvell PXA GPIO controller
-
-Required properties:
-- compatible : Should be "intel,pxa25x-gpio", "intel,pxa26x-gpio",
- "intel,pxa27x-gpio", "intel,pxa3xx-gpio",
- "marvell,pxa93x-gpio", "marvell,mmp-gpio",
- "marvell,mmp2-gpio" or marvell,pxa1928-gpio.
-- reg : Address and length of the register set for the device
-- interrupts : Should be the port interrupt shared by all gpio pins.
- There're three gpio interrupts in arch-pxa, and they're gpio0,
- gpio1 and gpio_mux. There're only one gpio interrupt in arch-mmp,
- gpio_mux.
-- interrupt-names : Should be the names of irq resources. Each interrupt
- uses its own interrupt name, so there should be as many interrupt names
- as referenced interrupts.
-- interrupt-controller : Identifies the node as an interrupt controller.
-- #interrupt-cells: Specifies the number of cells needed to encode an
- interrupt source.
-- gpio-controller : Marks the device node as a gpio controller.
-- #gpio-cells : Should be two. The first cell is the pin number and
- the second cell is used to specify flags. See gpio.txt for possible
- values.
-
-Example for a MMP platform:
-
- gpio: gpio@d4019000 {
- compatible = "marvell,mmp-gpio";
- reg = <0xd4019000 0x1000>;
- interrupts = <49>;
- interrupt-names = "gpio_mux";
- gpio-controller;
- #gpio-cells = <2>;
- interrupt-controller;
- #interrupt-cells = <1>;
- };
-
-Example for a PXA3xx platform:
-
- gpio: gpio@40e00000 {
- compatible = "intel,pxa3xx-gpio";
- reg = <0x40e00000 0x10000>;
- interrupt-names = "gpio0", "gpio1", "gpio_mux";
- interrupts = <8 9 10>;
- gpio-controller;
- #gpio-cells = <0x2>;
- interrupt-controller;
- #interrupt-cells = <0x2>;
- };
diff --git a/Documentation/devicetree/bindings/gpio/mrvl-gpio.yaml b/Documentation/devicetree/bindings/gpio/mrvl-gpio.yaml
new file mode 100644
index 0000000..4db3b8a
--- /dev/null
+++ b/Documentation/devicetree/bindings/gpio/mrvl-gpio.yaml
@@ -0,0 +1,173 @@
+# SPDX-License-Identifier: GPL-2.0-only
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/gpio/mrvl-gpio.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Marvell PXA GPIO controller
+
+maintainers:
+ - Linus Walleij <linus.walleij@linaro.org>
+ - Bartosz Golaszewski <bgolaszewski@baylibre.com>
+ - Rob Herring <robh+dt@kernel.org>
+
+allOf:
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - intel,pxa25x-gpio
+ - intel,pxa26x-gpio
+ - intel,pxa27x-gpio
+ - intel,pxa3xx-gpio
+ then:
+ properties:
+ interrupts:
+ minItems: 3
+ maxItems: 3
+ interrupt-names:
+ items:
+ - const: gpio0
+ - const: gpio1
+ - const: gpio_mux
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - marvell,mmp-gpio
+ - marvell,mmp2-gpio
+ then:
+ properties:
+ interrupts:
+ maxItems: 1
+ interrupt-names:
+ items:
+ - const: gpio_mux
+
+properties:
+ $nodename:
+ pattern: '^gpio@[0-9a-f]+$'
+
+ compatible:
+ enum:
+ - intel,pxa25x-gpio
+ - intel,pxa26x-gpio
+ - intel,pxa27x-gpio
+ - intel,pxa3xx-gpio
+ - marvell,mmp-gpio
+ - marvell,mmp2-gpio
+ - marvell,pxa93x-gpio
+
+ reg:
+ maxItems: 1
+
+ clocks:
+ maxItems: 1
+
+ resets:
+ maxItems: 1
+
+ ranges: true
+
+ '#address-cells':
+ const: 1
+
+ '#size-cells':
+ const: 1
+
+ gpio-controller: true
+
+ '#gpio-cells':
+ const: 2
+
+ gpio-ranges:
+ maxItems: 1
+
+ interrupts: true
+
+ interrupt-names: true
+
+ interrupt-controller: true
+
+ '#interrupt-cells':
+ const: 2
+
+patternProperties:
+ '^gpio@[0-9a-f]*$':
+ type: object
+ properties:
+ reg:
+ maxItems: 1
+
+ required:
+ - reg
+
+ additionalProperties: false
+
+required:
+ - compatible
+ - '#address-cells'
+ - '#size-cells'
+ - reg
+ - gpio-controller
+ - '#gpio-cells'
+ - interrupts
+ - interrupt-names
+ - interrupt-controller
+ - '#interrupt-cells'
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/clock/pxa-clock.h>
+ gpio@40e00000 {
+ compatible = "intel,pxa3xx-gpio";
+ #address-cells = <1>;
+ #size-cells = <1>;
+ reg = <0x40e00000 0x10000>;
+ gpio-controller;
+ #gpio-cells = <2>;
+ interrupts = <8>, <9>, <10>;
+ interrupt-names = "gpio0", "gpio1", "gpio_mux";
+ clocks = <&clks CLK_GPIO>;
+ interrupt-controller;
+ #interrupt-cells = <2>;
+ };
+ - |
+ #include <dt-bindings/clock/marvell,pxa910.h>
+ gpio@d4019000 {
+ compatible = "marvell,mmp-gpio";
+ #address-cells = <1>;
+ #size-cells = <1>;
+ reg = <0xd4019000 0x1000>;
+ gpio-controller;
+ #gpio-cells = <2>;
+ interrupts = <49>;
+ interrupt-names = "gpio_mux";
+ clocks = <&soc_clocks PXA910_CLK_GPIO>;
+ resets = <&soc_clocks PXA910_CLK_GPIO>;
+ interrupt-controller;
+ #interrupt-cells = <2>;
+ ranges;
+
+ gpio@d4019000 {
+ reg = <0xd4019000 0x4>;
+ };
+
+ gpio@d4019004 {
+ reg = <0xd4019004 0x4>;
+ };
+
+ gpio@d4019008 {
+ reg = <0xd4019008 0x4>;
+ };
+
+ gpio@d4019100 {
+ reg = <0xd4019100 0x4>;
+ };
+ };
+
+...
diff --git a/Documentation/devicetree/bindings/gpu/nvidia,gk20a.txt b/Documentation/devicetree/bindings/gpu/nvidia,gk20a.txt
index f32bbba..662a3c8 100644
--- a/Documentation/devicetree/bindings/gpu/nvidia,gk20a.txt
+++ b/Documentation/devicetree/bindings/gpu/nvidia,gk20a.txt
@@ -6,6 +6,7 @@
- nvidia,gk20a
- nvidia,gm20b
- nvidia,gp10b
+ - nvidia,gv11b
- reg: Physical base address and length of the controller's registers.
Must contain two entries:
- first entry for bar0
@@ -25,6 +26,9 @@
If the compatible string is "nvidia,gm20b", then the following clock
is also required:
- ref
+If the compatible string is "nvidia,gv11b", then the following clock is also
+required:
+ - fuse
- resets: Must contain an entry for each entry in reset-names.
See ../reset/reset.txt for details.
- reset-names: Must include the following entries:
@@ -88,3 +92,24 @@
power-domains = <&bpmp TEGRA186_POWER_DOMAIN_GPU>;
iommus = <&smmu TEGRA186_SID_GPU>;
};
+
+Example for GV11B:
+
+ gpu@17000000 {
+ compatible = "nvidia,gv11b";
+ reg = <0x17000000 0x10000000>,
+ <0x18000000 0x10000000>;
+ interrupts = <GIC_SPI 70 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 71 IRQ_TYPE_LEVEL_HIGH>;
+ interrupt-names = "stall", "nonstall";
+ clocks = <&bpmp TEGRA194_CLK_GPCCLK>,
+ <&bpmp TEGRA194_CLK_GPU_PWR>,
+ <&bpmp TEGRA194_CLK_FUSE>;
+ clock-names = "gpu", "pwr", "fuse";
+ resets = <&bpmp TEGRA194_RESET_GPU>;
+ reset-names = "gpu";
+ dma-coherent;
+
+ power-domains = <&bpmp TEGRA194_POWER_DOMAIN_GPU>;
+ iommus = <&smmu TEGRA194_SID_GPU>;
+ };
diff --git a/Documentation/devicetree/bindings/hwlock/qcom-hwspinlock.txt b/Documentation/devicetree/bindings/hwlock/qcom-hwspinlock.txt
deleted file mode 100644
index 4563f52..0000000
--- a/Documentation/devicetree/bindings/hwlock/qcom-hwspinlock.txt
+++ /dev/null
@@ -1,39 +0,0 @@
-Qualcomm Hardware Mutex Block:
-
-The hardware block provides mutexes utilized between different processors on
-the SoC as part of the communication protocol used by these processors.
-
-- compatible:
- Usage: required
- Value type: <string>
- Definition: must be one of:
- "qcom,sfpb-mutex",
- "qcom,tcsr-mutex"
-
-- syscon:
- Usage: required
- Value type: <prop-encoded-array>
- Definition: one cell containing:
- syscon phandle
- offset of the hwmutex block within the syscon
- stride of the hwmutex registers
-
-- #hwlock-cells:
- Usage: required
- Value type: <u32>
- Definition: must be 1, the specified cell represent the lock id
- (hwlock standard property, see hwlock.txt)
-
-Example:
-
- tcsr_mutex_block: syscon@fd484000 {
- compatible = "syscon";
- reg = <0xfd484000 0x2000>;
- };
-
- hwlock@fd484000 {
- compatible = "qcom,tcsr-mutex";
- syscon = <&tcsr_mutex_block 0 0x80>;
-
- #hwlock-cells = <1>;
- };
diff --git a/Documentation/devicetree/bindings/hwlock/qcom-hwspinlock.yaml b/Documentation/devicetree/bindings/hwlock/qcom-hwspinlock.yaml
new file mode 100644
index 0000000..1c7149f
--- /dev/null
+++ b/Documentation/devicetree/bindings/hwlock/qcom-hwspinlock.yaml
@@ -0,0 +1,42 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/hwlock/qcom-hwspinlock.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Qualcomm Hardware Mutex Block
+
+maintainers:
+ - Bjorn Andersson <bjorn.andersson@linaro.org>
+
+description:
+ The hardware block provides mutexes utilized between different processors on
+ the SoC as part of the communication protocol used by these processors.
+
+properties:
+ compatible:
+ enum:
+ - qcom,sfpb-mutex
+ - qcom,tcsr-mutex
+
+ reg:
+ maxItems: 1
+
+ '#hwlock-cells':
+ const: 1
+
+required:
+ - compatible
+ - reg
+ - '#hwlock-cells'
+
+additionalProperties: false
+
+examples:
+ - |
+ tcsr_mutex: hwlock@1f40000 {
+ compatible = "qcom,tcsr-mutex";
+ reg = <0x01f40000 0x40000>;
+ #hwlock-cells = <1>;
+ };
+...
diff --git a/Documentation/devicetree/bindings/hwmon/gpio-fan.txt b/Documentation/devicetree/bindings/hwmon/gpio-fan.txt
index 2becdcf..f4cfa35 100644
--- a/Documentation/devicetree/bindings/hwmon/gpio-fan.txt
+++ b/Documentation/devicetree/bindings/hwmon/gpio-fan.txt
@@ -12,7 +12,8 @@
- alarm-gpios: This pin going active indicates something is wrong with
the fan, and a udev event will be fired.
- #cooling-cells: If used as a cooling device, must be <2>
- Also see: Documentation/devicetree/bindings/thermal/thermal.txt
+ Also see:
+ Documentation/devicetree/bindings/thermal/thermal-cooling-devices.yaml
min and max states are derived from the speed-map of the fan.
Note: At least one the "gpios" or "alarm-gpios" properties must be set.
diff --git a/Documentation/devicetree/bindings/hwmon/lm90.txt b/Documentation/devicetree/bindings/hwmon/lm90.txt
index c76a7ac..398dcb9 100644
--- a/Documentation/devicetree/bindings/hwmon/lm90.txt
+++ b/Documentation/devicetree/bindings/hwmon/lm90.txt
@@ -34,8 +34,8 @@
LM90 "-ALERT" pin output.
See interrupt-controller/interrupts.txt for the format.
-- #thermal-sensor-cells: should be set to 1. See thermal/thermal.txt for
- details. See <include/dt-bindings/thermal/lm90.h> for the
+- #thermal-sensor-cells: should be set to 1. See thermal/thermal-sensor.yaml
+ for details. See <include/dt-bindings/thermal/lm90.h> for the
definition of the local, remote and 2nd remote sensor index
constants.
diff --git a/Documentation/devicetree/bindings/hwmon/microchip,sparx5-temp.yaml b/Documentation/devicetree/bindings/hwmon/microchip,sparx5-temp.yaml
new file mode 100644
index 0000000..76be625
--- /dev/null
+++ b/Documentation/devicetree/bindings/hwmon/microchip,sparx5-temp.yaml
@@ -0,0 +1,44 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/hwmon/microchip,sparx5-temp.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Microchip Sparx5 Temperature Monitor
+
+maintainers:
+ - Lars Povlsen <lars.povlsen@microchip.com>
+
+description: |
+ Microchip Sparx5 embedded temperature monitor
+
+properties:
+ compatible:
+ enum:
+ - microchip,sparx5-temp
+
+ reg:
+ maxItems: 1
+
+ clocks:
+ items:
+ - description: AHB reference clock
+
+ '#thermal-sensor-cells':
+ const: 0
+
+required:
+ - compatible
+ - reg
+ - clocks
+
+additionalProperties: false
+
+examples:
+ - |
+ tmon0: tmon@610508110 {
+ compatible = "microchip,sparx5-temp";
+ reg = <0x10508110 0xc>;
+ #thermal-sensor-cells = <0>;
+ clocks = <&ahb_clk>;
+ };
diff --git a/Documentation/devicetree/bindings/hwmon/ti,tmp513.yaml b/Documentation/devicetree/bindings/hwmon/ti,tmp513.yaml
index 90b2fa3..c17e5d3 100644
--- a/Documentation/devicetree/bindings/hwmon/ti,tmp513.yaml
+++ b/Documentation/devicetree/bindings/hwmon/ti,tmp513.yaml
@@ -18,8 +18,8 @@
consumption.
Datasheets:
- http://www.ti.com/lit/gpn/tmp513
- http://www.ti.com/lit/gpn/tmp512
+ https://www.ti.com/lit/gpn/tmp513
+ https://www.ti.com/lit/gpn/tmp512
properties:
diff --git a/Documentation/devicetree/bindings/i2c/i2c-gpio.yaml b/Documentation/devicetree/bindings/i2c/i2c-gpio.yaml
index da61290..78ffcab 100644
--- a/Documentation/devicetree/bindings/i2c/i2c-gpio.yaml
+++ b/Documentation/devicetree/bindings/i2c/i2c-gpio.yaml
@@ -52,15 +52,15 @@
description: sda and scl gpio, alternative for {sda,scl}-gpios
i2c-gpio,sda-open-drain:
- # Generate a warning if present
- not: true
+ type: boolean
+ deprecated: true
description: this means that something outside of our control has put
the GPIO line used for SDA into open drain mode, and that something is
not the GPIO chip. It is essentially an inconsistency flag.
i2c-gpio,scl-open-drain:
- # Generate a warning if present
- not: true
+ type: boolean
+ deprecated: true
description: this means that something outside of our control has put the
GPIO line used for SCL into open drain mode, and that something is not
the GPIO chip. It is essentially an inconsistency flag.
diff --git a/Documentation/devicetree/bindings/i2c/i2c-imx-lpi2c.txt b/Documentation/devicetree/bindings/i2c/i2c-imx-lpi2c.txt
deleted file mode 100644
index f0c072f..0000000
--- a/Documentation/devicetree/bindings/i2c/i2c-imx-lpi2c.txt
+++ /dev/null
@@ -1,20 +0,0 @@
-* Freescale Low Power Inter IC (LPI2C) for i.MX
-
-Required properties:
-- compatible :
- - "fsl,imx7ulp-lpi2c" for LPI2C compatible with the one integrated on i.MX7ULP soc
- - "fsl,imx8qxp-lpi2c" for LPI2C compatible with the one integrated on i.MX8QXP soc
- - "fsl,imx8qm-lpi2c" for LPI2C compatible with the one integrated on i.MX8QM soc
-- reg : address and length of the lpi2c master registers
-- interrupts : lpi2c interrupt
-- clocks : lpi2c clock specifier
-
-Examples:
-
-lpi2c7: lpi2c7@40a50000 {
- compatible = "fsl,imx7ulp-lpi2c";
- reg = <0x40A50000 0x10000>;
- interrupt-parent = <&intc>;
- interrupts = <GIC_SPI 37 IRQ_TYPE_LEVEL_HIGH>;
- clocks = <&clks IMX7ULP_CLK_LPI2C7>;
-};
diff --git a/Documentation/devicetree/bindings/i2c/i2c-imx-lpi2c.yaml b/Documentation/devicetree/bindings/i2c/i2c-imx-lpi2c.yaml
new file mode 100644
index 0000000..ac0bc5d
--- /dev/null
+++ b/Documentation/devicetree/bindings/i2c/i2c-imx-lpi2c.yaml
@@ -0,0 +1,47 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/i2c/i2c-imx-lpi2c.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Freescale Low Power Inter IC (LPI2C) for i.MX
+
+maintainers:
+ - Anson Huang <Anson.Huang@nxp.com>
+
+properties:
+ compatible:
+ enum:
+ - fsl,imx7ulp-lpi2c
+ - fsl,imx8qxp-lpi2c
+ - fsl,imx8qm-lpi2c
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+ clocks:
+ maxItems: 1
+
+required:
+ - compatible
+ - reg
+ - interrupts
+ - clocks
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/clock/imx7ulp-clock.h>
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+
+ lpi2c7@40a50000 {
+ compatible = "fsl,imx7ulp-lpi2c";
+ reg = <0x40A50000 0x10000>;
+ interrupt-parent = <&intc>;
+ interrupts = <GIC_SPI 37 IRQ_TYPE_LEVEL_HIGH>;
+ clocks = <&clks IMX7ULP_CLK_LPI2C7>;
+ };
diff --git a/Documentation/devicetree/bindings/i2c/i2c-imx.txt b/Documentation/devicetree/bindings/i2c/i2c-imx.txt
deleted file mode 100644
index b967544..0000000
--- a/Documentation/devicetree/bindings/i2c/i2c-imx.txt
+++ /dev/null
@@ -1,49 +0,0 @@
-* Freescale Inter IC (I2C) and High Speed Inter IC (HS-I2C) for i.MX
-
-Required properties:
-- compatible :
- - "fsl,imx1-i2c" for I2C compatible with the one integrated on i.MX1 SoC
- - "fsl,imx21-i2c" for I2C compatible with the one integrated on i.MX21 SoC
- - "fsl,vf610-i2c" for I2C compatible with the one integrated on Vybrid vf610 SoC
-- reg : Should contain I2C/HS-I2C registers location and length
-- interrupts : Should contain I2C/HS-I2C interrupt
-- clocks : Should contain the I2C/HS-I2C clock specifier
-
-Optional properties:
-- clock-frequency : Constains desired I2C/HS-I2C bus clock frequency in Hz.
- The absence of the property indicates the default frequency 100 kHz.
-- dmas: A list of two dma specifiers, one for each entry in dma-names.
-- dma-names: should contain "tx" and "rx".
-- scl-gpios: specify the gpio related to SCL pin
-- sda-gpios: specify the gpio related to SDA pin
-- pinctrl: add extra pinctrl to configure i2c pins to gpio function for i2c
- bus recovery, call it "gpio" state
-
-Examples:
-
-i2c@83fc4000 { /* I2C2 on i.MX51 */
- compatible = "fsl,imx51-i2c", "fsl,imx21-i2c";
- reg = <0x83fc4000 0x4000>;
- interrupts = <63>;
-};
-
-i2c@70038000 { /* HS-I2C on i.MX51 */
- compatible = "fsl,imx51-i2c", "fsl,imx21-i2c";
- reg = <0x70038000 0x4000>;
- interrupts = <64>;
- clock-frequency = <400000>;
-};
-
-i2c0: i2c@40066000 { /* i2c0 on vf610 */
- compatible = "fsl,vf610-i2c";
- reg = <0x40066000 0x1000>;
- interrupts =<0 71 0x04>;
- dmas = <&edma0 0 50>,
- <&edma0 0 51>;
- dma-names = "rx","tx";
- pinctrl-names = "default", "gpio";
- pinctrl-0 = <&pinctrl_i2c1>;
- pinctrl-1 = <&pinctrl_i2c1_gpio>;
- scl-gpios = <&gpio5 26 GPIO_ACTIVE_HIGH>;
- sda-gpios = <&gpio5 27 GPIO_ACTIVE_HIGH>;
-};
diff --git a/Documentation/devicetree/bindings/i2c/i2c-imx.yaml b/Documentation/devicetree/bindings/i2c/i2c-imx.yaml
new file mode 100644
index 0000000..869f2ae
--- /dev/null
+++ b/Documentation/devicetree/bindings/i2c/i2c-imx.yaml
@@ -0,0 +1,103 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/i2c/i2c-imx.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Freescale Inter IC (I2C) and High Speed Inter IC (HS-I2C) for i.MX
+
+maintainers:
+ - Wolfram Sang <wolfram@the-dreams.de>
+
+properties:
+ compatible:
+ oneOf:
+ - const: fsl,imx1-i2c
+ - const: fsl,imx21-i2c
+ - const: fsl,vf610-i2c
+ - items:
+ - const: fsl,imx35-i2c
+ - const: fsl,imx1-i2c
+ - items:
+ - enum:
+ - fsl,imx25-i2c
+ - fsl,imx27-i2c
+ - fsl,imx31-i2c
+ - fsl,imx50-i2c
+ - fsl,imx51-i2c
+ - fsl,imx53-i2c
+ - fsl,imx6q-i2c
+ - fsl,imx6sl-i2c
+ - fsl,imx6sx-i2c
+ - fsl,imx6sll-i2c
+ - fsl,imx6ul-i2c
+ - fsl,imx7s-i2c
+ - fsl,imx8mq-i2c
+ - fsl,imx8mm-i2c
+ - fsl,imx8mn-i2c
+ - fsl,imx8mp-i2c
+ - const: fsl,imx21-i2c
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+ clocks:
+ maxItems: 1
+
+ clock-names:
+ const: ipg
+
+ clock-frequency:
+ enum: [ 100000, 400000 ]
+
+ dmas:
+ items:
+ - description: DMA controller phandle and request line for RX
+ - description: DMA controller phandle and request line for TX
+
+ dma-names:
+ items:
+ - const: rx
+ - const: tx
+
+ sda-gpios:
+ maxItems: 1
+
+ scl-gpios:
+ maxItems: 1
+
+required:
+ - compatible
+ - reg
+ - interrupts
+ - clocks
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/clock/imx5-clock.h>
+ #include <dt-bindings/clock/vf610-clock.h>
+ #include <dt-bindings/gpio/gpio.h>
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+
+ i2c@83fc4000 {
+ compatible = "fsl,imx51-i2c", "fsl,imx21-i2c";
+ reg = <0x83fc4000 0x4000>;
+ interrupts = <63>;
+ clocks = <&clks IMX5_CLK_I2C2_GATE>;
+ };
+
+ i2c@40066000 {
+ compatible = "fsl,vf610-i2c";
+ reg = <0x40066000 0x1000>;
+ interrupts = <71 IRQ_TYPE_LEVEL_HIGH>;
+ clocks = <&clks VF610_CLK_I2C0>;
+ clock-names = "ipg";
+ dmas = <&edma0 0 50>,
+ <&edma0 0 51>;
+ dma-names = "rx", "tx";
+ };
diff --git a/Documentation/devicetree/bindings/i2c/i2c-mt65xx.txt b/Documentation/devicetree/bindings/i2c/i2c-mt65xx.txt
index 88b71c1..7f0194f 100644
--- a/Documentation/devicetree/bindings/i2c/i2c-mt65xx.txt
+++ b/Documentation/devicetree/bindings/i2c/i2c-mt65xx.txt
@@ -14,6 +14,7 @@
"mediatek,mt7629-i2c", "mediatek,mt2712-i2c": for MediaTek MT7629
"mediatek,mt8173-i2c": for MediaTek MT8173
"mediatek,mt8183-i2c": for MediaTek MT8183
+ "mediatek,mt8192-i2c": for MediaTek MT8192
"mediatek,mt8516-i2c", "mediatek,mt2712-i2c": for MediaTek MT8516
- reg: physical base address of the controller and dma base, length of memory
mapped region.
diff --git a/Documentation/devicetree/bindings/i2c/i2c-mxs.txt b/Documentation/devicetree/bindings/i2c/i2c-mxs.txt
deleted file mode 100644
index 4e1c8ac..0000000
--- a/Documentation/devicetree/bindings/i2c/i2c-mxs.txt
+++ /dev/null
@@ -1,25 +0,0 @@
-* Freescale MXS Inter IC (I2C) Controller
-
-Required properties:
-- compatible: Should be "fsl,<chip>-i2c"
-- reg: Should contain registers location and length
-- interrupts: Should contain ERROR interrupt number
-- clock-frequency: Desired I2C bus clock frequency in Hz.
- Only 100000Hz and 400000Hz modes are supported.
-- dmas: DMA specifier, consisting of a phandle to DMA controller node
- and I2C DMA channel ID.
- Refer to dma.txt and fsl-mxs-dma.txt for details.
-- dma-names: Must be "rx-tx".
-
-Examples:
-
-i2c0: i2c@80058000 {
- #address-cells = <1>;
- #size-cells = <0>;
- compatible = "fsl,imx28-i2c";
- reg = <0x80058000 2000>;
- interrupts = <111>;
- clock-frequency = <100000>;
- dmas = <&dma_apbx 6>;
- dma-names = "rx-tx";
-};
diff --git a/Documentation/devicetree/bindings/i2c/i2c-mxs.yaml b/Documentation/devicetree/bindings/i2c/i2c-mxs.yaml
new file mode 100644
index 0000000..d3134ed
--- /dev/null
+++ b/Documentation/devicetree/bindings/i2c/i2c-mxs.yaml
@@ -0,0 +1,51 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/i2c/i2c-mxs.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Freescale MXS Inter IC (I2C) Controller
+
+maintainers:
+ - Shawn Guo <shawn.guo@linaro.org>
+
+properties:
+ compatible:
+ enum:
+ - fsl,imx23-i2c
+ - fsl,imx28-i2c
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+ clock-frequency:
+ enum: [ 100000, 400000 ]
+
+ dmas:
+ maxItems: 1
+
+ dma-names:
+ const: rx-tx
+
+required:
+ - compatible
+ - reg
+ - interrupts
+ - dmas
+ - dma-names
+
+additionalProperties: false
+
+examples:
+ - |
+ i2c@80058000 {
+ compatible = "fsl,imx28-i2c";
+ reg = <0x80058000 2000>;
+ interrupts = <111>;
+ clock-frequency = <100000>;
+ dmas = <&dma_apbx 6>;
+ dma-names = "rx-tx";
+ };
diff --git a/Documentation/devicetree/bindings/i2c/i2c-pxa.txt b/Documentation/devicetree/bindings/i2c/i2c-pxa.txt
deleted file mode 100644
index c30783c..0000000
--- a/Documentation/devicetree/bindings/i2c/i2c-pxa.txt
+++ /dev/null
@@ -1,31 +0,0 @@
-* Marvell MMP I2C controller
-
-Required properties :
-
- - reg : Offset and length of the register set for the device
- - compatible : should be "mrvl,mmp-twsi" where mmp is the name of a
- compatible processor, e.g. pxa168, pxa910, mmp2, mmp3.
- For the pxa2xx/pxa3xx, an additional node "mrvl,pxa-i2c" is required
- as shown in the example below.
- For the Armada 3700, the compatible should be "marvell,armada-3700-i2c".
-
-Recommended properties :
-
- - interrupts : the interrupt number
- - mrvl,i2c-polling : Disable interrupt of i2c controller. Polling
- status register of i2c controller instead.
- - mrvl,i2c-fast-mode : Enable fast mode of i2c controller.
-
-Examples:
- twsi1: i2c@d4011000 {
- compatible = "mrvl,mmp-twsi";
- reg = <0xd4011000 0x1000>;
- interrupts = <7>;
- mrvl,i2c-fast-mode;
- };
-
- twsi2: i2c@d4025000 {
- compatible = "mrvl,mmp-twsi";
- reg = <0xd4025000 0x1000>;
- interrupts = <58>;
- };
diff --git a/Documentation/devicetree/bindings/i2c/i2c-pxa.yaml b/Documentation/devicetree/bindings/i2c/i2c-pxa.yaml
new file mode 100644
index 0000000..da6e8bd
--- /dev/null
+++ b/Documentation/devicetree/bindings/i2c/i2c-pxa.yaml
@@ -0,0 +1,74 @@
+# SPDX-License-Identifier: GPL-2.0-only
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/i2c/i2c-pxa.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Marvell MMP I2C controller bindings
+
+maintainers:
+ - Rob Herring <robh+dt@kernel.org>
+
+allOf:
+ - $ref: /schemas/i2c/i2c-controller.yaml#
+ - if:
+ not:
+ required:
+ - mrvl,i2c-polling
+ then:
+ required:
+ - interrupts
+
+properties:
+ compatible:
+ enum:
+ - mrvl,mmp-twsi
+ - mrvl,pxa-i2c
+ - marvell,armada-3700-i2c
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+ clocks:
+ minItems: 1
+
+ resets:
+ minItems: 1
+
+ mrvl,i2c-polling:
+ $ref: /schemas/types.yaml#/definitions/flag
+ description: |
+ Disable interrupt of i2c controller. Polling status register of i2c
+ controller instead.
+
+ mrvl,i2c-fast-mode:
+ $ref: /schemas/types.yaml#/definitions/flag
+ description: Enable fast mode of i2c controller.
+
+unevaluatedProperties: false
+
+required:
+ - compatible
+ - reg
+ - interrupts
+ - clocks
+ - '#address-cells'
+ - '#size-cells'
+
+examples:
+ - |
+ #include <dt-bindings/clock/marvell,mmp2.h>
+ i2c@d4011000 {
+ compatible = "mrvl,mmp-twsi";
+ reg = <0xd4011000 0x1000>;
+ interrupts = <7>;
+ clocks = <&soc_clocks MMP2_CLK_TWSI1>;
+ mrvl,i2c-fast-mode;
+ #address-cells = <1>;
+ #size-cells = <0>;
+ };
+
+...
diff --git a/Documentation/devicetree/bindings/i2c/i2c.txt b/Documentation/devicetree/bindings/i2c/i2c.txt
index 438ae12..a21c359 100644
--- a/Documentation/devicetree/bindings/i2c/i2c.txt
+++ b/Documentation/devicetree/bindings/i2c/i2c.txt
@@ -72,6 +72,16 @@
this information to adapt power management to keep the arbitration awake
all the time, for example. Can not be combined with 'single-master'.
+- pinctrl
+ add extra pinctrl to configure SCL/SDA pins to GPIO function for bus
+ recovery, call it "gpio" or "recovery" (deprecated) state
+
+- scl-gpios
+ specify the gpio related to SCL pin. Used for GPIO bus recovery.
+
+- sda-gpios
+ specify the gpio related to SDA pin. Optional for GPIO bus recovery.
+
- single-master
states that there is no other master active on this bus. The OS can use
this information to detect a stalled bus more reliably, for example.
diff --git a/Documentation/devicetree/bindings/i2c/marvell,mv64xxx-i2c.yaml b/Documentation/devicetree/bindings/i2c/marvell,mv64xxx-i2c.yaml
index 2ceb05b..5b5ae40 100644
--- a/Documentation/devicetree/bindings/i2c/marvell,mv64xxx-i2c.yaml
+++ b/Documentation/devicetree/bindings/i2c/marvell,mv64xxx-i2c.yaml
@@ -27,6 +27,9 @@
- const: allwinner,sun50i-a64-i2c
- const: allwinner,sun6i-a31-i2c
- items:
+ - const: allwinner,sun50i-a100-i2c
+ - const: allwinner,sun6i-a31-i2c
+ - items:
- const: allwinner,sun50i-h6-i2c
- const: allwinner,sun6i-a31-i2c
diff --git a/Documentation/devicetree/bindings/i2c/nvidia,tegra20-i2c.txt b/Documentation/devicetree/bindings/i2c/nvidia,tegra20-i2c.txt
index 18c0de3..3f2f990 100644
--- a/Documentation/devicetree/bindings/i2c/nvidia,tegra20-i2c.txt
+++ b/Documentation/devicetree/bindings/i2c/nvidia,tegra20-i2c.txt
@@ -35,12 +35,12 @@
Due to above changes, Tegra114 I2C driver makes incompatible with
previous hardware driver. Hence, tegra114 I2C controller is compatible
with "nvidia,tegra114-i2c".
- nvidia,tegra210-i2c-vi: Tegra210 has one I2C controller that is part of the
- host1x domain and typically used for camera use-cases. This VI I2C
- controller is mostly compatible with the programming model of the
- regular I2C controllers with a few exceptions. The I2C registers start
- at an offset of 0xc00 (instead of 0), registers are 16 bytes apart
- (rather than 4) and the controller does not support slave mode.
+ nvidia,tegra210-i2c-vi: Tegra210 has one I2C controller that is on host1x bus
+ and is part of VE power domain and typically used for camera use-cases.
+ This VI I2C controller is mostly compatible with the programming model
+ of the regular I2C controllers with a few exceptions. The I2C registers
+ start at an offset of 0xc00 (instead of 0), registers are 16 bytes
+ apart (rather than 4) and the controller does not support slave mode.
- reg: Should contain I2C controller registers physical address and length.
- interrupts: Should contain I2C controller interrupts.
- address-cells: Address cells for I2C device address.
@@ -53,10 +53,17 @@
- fast-clk
Tegra114:
- div-clk
+ Tegra210:
+ - div-clk
+ - slow (only for nvidia,tegra210-i2c-vi compatible node)
- resets: Must contain an entry for each entry in reset-names.
See ../reset/reset.txt for details.
- reset-names: Must include the following entries:
- i2c
+- power-domains: Only for nvidia,tegra210-i2c-vi compatible node and must
+ include venc powergate node as vi i2c is part of VE power domain.
+ tegra210-i2c-vi:
+ - pd_venc
- dmas: Must contain an entry for each entry in clock-names.
See ../dma/dma.txt for details.
- dma-names: Must include the following entries:
diff --git a/Documentation/devicetree/bindings/i2c/renesas,i2c.txt b/Documentation/devicetree/bindings/i2c/renesas,i2c.txt
index a03f9f5..96d869a 100644
--- a/Documentation/devicetree/bindings/i2c/renesas,i2c.txt
+++ b/Documentation/devicetree/bindings/i2c/renesas,i2c.txt
@@ -10,6 +10,7 @@
"renesas,i2c-r8a774a1" if the device is a part of a R8A774A1 SoC.
"renesas,i2c-r8a774b1" if the device is a part of a R8A774B1 SoC.
"renesas,i2c-r8a774c0" if the device is a part of a R8A774C0 SoC.
+ "renesas,i2c-r8a774e1" if the device is a part of a R8A774E1 SoC.
"renesas,i2c-r8a7778" if the device is a part of a R8A7778 SoC.
"renesas,i2c-r8a7779" if the device is a part of a R8A7779 SoC.
"renesas,i2c-r8a7790" if the device is a part of a R8A7790 SoC.
diff --git a/Documentation/devicetree/bindings/i2c/renesas,iic.txt b/Documentation/devicetree/bindings/i2c/renesas,iic.txt
index 89facb0..93d4128 100644
--- a/Documentation/devicetree/bindings/i2c/renesas,iic.txt
+++ b/Documentation/devicetree/bindings/i2c/renesas,iic.txt
@@ -11,6 +11,7 @@
- "renesas,iic-r8a774a1" (RZ/G2M)
- "renesas,iic-r8a774b1" (RZ/G2N)
- "renesas,iic-r8a774c0" (RZ/G2E)
+ - "renesas,iic-r8a774e1" (RZ/G2H)
- "renesas,iic-r8a7790" (R-Car H2)
- "renesas,iic-r8a7791" (R-Car M2-W)
- "renesas,iic-r8a7792" (R-Car V2H)
diff --git a/Documentation/devicetree/bindings/iio/accel/adi,adxl345.yaml b/Documentation/devicetree/bindings/iio/accel/adi,adxl345.yaml
index d124eba..fd4eaa3 100644
--- a/Documentation/devicetree/bindings/iio/accel/adi,adxl345.yaml
+++ b/Documentation/devicetree/bindings/iio/accel/adi,adxl345.yaml
@@ -12,8 +12,8 @@
description: |
Analog Devices ADXL345/ADXL375 3-Axis Digital Accelerometers that supports
both I2C & SPI interfaces.
- http://www.analog.com/en/products/mems/accelerometers/adxl345.html
- http://www.analog.com/en/products/sensors-mems/accelerometers/adxl375.html
+ https://www.analog.com/en/products/mems/accelerometers/adxl345.html
+ https://www.analog.com/en/products/sensors-mems/accelerometers/adxl375.html
properties:
compatible:
diff --git a/Documentation/devicetree/bindings/iio/accel/kionix,kxsd9.txt b/Documentation/devicetree/bindings/iio/accel/kionix,kxsd9.txt
deleted file mode 100644
index b25bf3a..0000000
--- a/Documentation/devicetree/bindings/iio/accel/kionix,kxsd9.txt
+++ /dev/null
@@ -1,22 +0,0 @@
-Kionix KXSD9 Accelerometer device tree bindings
-
-Required properties:
- - compatible: should be set to "kionix,kxsd9"
- - reg: i2c slave address
-
-Optional properties:
- - vdd-supply: The input supply for VDD
- - iovdd-supply: The input supply for IOVDD
- - interrupts: The movement detection interrupt
- - mount-matrix: See mount-matrix.txt
-
-Example:
-
-kxsd9@18 {
- compatible = "kionix,kxsd9";
- reg = <0x18>;
- interrupt-parent = <&foo>;
- interrupts = <57 IRQ_TYPE_EDGE_FALLING>;
- iovdd-supply = <&bar>;
- vdd-supply = <&baz>;
-};
diff --git a/Documentation/devicetree/bindings/iio/accel/kionix,kxsd9.yaml b/Documentation/devicetree/bindings/iio/accel/kionix,kxsd9.yaml
new file mode 100644
index 0000000..d61ab4f
--- /dev/null
+++ b/Documentation/devicetree/bindings/iio/accel/kionix,kxsd9.yaml
@@ -0,0 +1,65 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iio/accel/kionix,kxsd9.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Kionix KXSD9 Accelerometer
+
+maintainers:
+ - Jonathan Cameron <jic23@kernel.org>
+
+description: |
+ 3 axis 12 bit accelerometer with +-8G range on all axes. Also has a
+ 12 bit auxiliary ADC channel. Interface is either SPI or I2C.
+
+properties:
+ compatible:
+ const: kionix,kxsd9
+
+ reg:
+ maxItems: 1
+
+ vdd-supply: true
+ iovdd-supply: true
+
+ interrupts:
+ maxItems: 1
+
+ mount-matrix:
+ description: an optional 3x3 mounting rotation matrix.
+
+required:
+ - compatible
+ - reg
+
+examples:
+ - |
+ # include <dt-bindings/interrupt-controller/irq.h>
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ accel@18 {
+ compatible = "kionix,kxsd9";
+ reg = <0x18>;
+ iovdd-supply = <&iovdd>;
+ vdd-supply = <&vdd>;
+ interrupts = <57 IRQ_TYPE_EDGE_FALLING>;
+ mount-matrix = "-0.984807753012208", "0", "-0.173648177666930",
+ "0", "-1", "0",
+ "-0.173648177666930", "0", "0.984807753012208";
+ };
+ };
+ - |
+ # include <dt-bindings/interrupt-controller/irq.h>
+ spi {
+ #address-cells = <1>;
+ #size-cells = <0>;
+ accel@0 {
+ compatible = "kionix,kxsd9";
+ reg = <0>;
+ spi-max-frequency = <10000000>;
+ };
+ };
+...
diff --git a/Documentation/devicetree/bindings/iio/adc/ingenic,adc.txt b/Documentation/devicetree/bindings/iio/adc/ingenic,adc.txt
deleted file mode 100644
index cd9048c..0000000
--- a/Documentation/devicetree/bindings/iio/adc/ingenic,adc.txt
+++ /dev/null
@@ -1,49 +0,0 @@
-* Ingenic JZ47xx ADC controller IIO bindings
-
-Required properties:
-
-- compatible: Should be one of:
- * ingenic,jz4725b-adc
- * ingenic,jz4740-adc
- * ingenic,jz4770-adc
-- reg: ADC controller registers location and length.
-- clocks: phandle to the SoC's ADC clock.
-- clock-names: Must be set to "adc".
-- #io-channel-cells: Must be set to <1> to indicate channels are selected
- by index.
-
-ADC clients must use the format described in iio-bindings.txt, giving
-a phandle and IIO specifier pair ("io-channels") to the ADC controller.
-
-Example:
-
-#include <dt-bindings/iio/adc/ingenic,adc.h>
-
-adc: adc@10070000 {
- compatible = "ingenic,jz4740-adc";
- #io-channel-cells = <1>;
-
- reg = <0x10070000 0x30>;
-
- clocks = <&cgu JZ4740_CLK_ADC>;
- clock-names = "adc";
-
- interrupt-parent = <&intc>;
- interrupts = <18>;
-};
-
-adc-keys {
- ...
- compatible = "adc-keys";
- io-channels = <&adc INGENIC_ADC_AUX>;
- io-channel-names = "buttons";
- ...
-};
-
-battery {
- ...
- compatible = "ingenic,jz4740-battery";
- io-channels = <&adc INGENIC_ADC_BATTERY>;
- io-channel-names = "battery";
- ...
-};
diff --git a/Documentation/devicetree/bindings/iio/adc/ingenic,adc.yaml b/Documentation/devicetree/bindings/iio/adc/ingenic,adc.yaml
new file mode 100644
index 0000000..9f414db
--- /dev/null
+++ b/Documentation/devicetree/bindings/iio/adc/ingenic,adc.yaml
@@ -0,0 +1,71 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+# Copyright 2019-2020 Artur Rojek
+%YAML 1.2
+---
+$id: "http://devicetree.org/schemas/iio/adc/ingenic,adc.yaml#"
+$schema: "http://devicetree.org/meta-schemas/core.yaml#"
+
+title: Ingenic JZ47xx ADC controller IIO bindings
+
+maintainers:
+ - Artur Rojek <contact@artur-rojek.eu>
+
+description: >
+ Industrial I/O subsystem bindings for ADC controller found in
+ Ingenic JZ47xx SoCs.
+
+ ADC clients must use the format described in iio-bindings.txt, giving
+ a phandle and IIO specifier pair ("io-channels") to the ADC controller.
+
+properties:
+ compatible:
+ enum:
+ - ingenic,jz4725b-adc
+ - ingenic,jz4740-adc
+ - ingenic,jz4770-adc
+
+ '#io-channel-cells':
+ const: 1
+ description:
+ Must be set to <1> to indicate channels are selected by index.
+
+ reg:
+ maxItems: 1
+
+ clocks:
+ maxItems: 1
+
+ clock-names:
+ items:
+ - const: adc
+
+ interrupts:
+ maxItems: 1
+
+required:
+ - compatible
+ - '#io-channel-cells'
+ - reg
+ - clocks
+ - clock-names
+ - interrupts
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/clock/jz4740-cgu.h>
+ #include <dt-bindings/iio/adc/ingenic,adc.h>
+
+ adc@10070000 {
+ compatible = "ingenic,jz4740-adc";
+ #io-channel-cells = <1>;
+
+ reg = <0x10070000 0x30>;
+
+ clocks = <&cgu JZ4740_CLK_ADC>;
+ clock-names = "adc";
+
+ interrupt-parent = <&intc>;
+ interrupts = <18>;
+ };
diff --git a/Documentation/devicetree/bindings/iio/adc/qcom,spmi-vadc.txt b/Documentation/devicetree/bindings/iio/adc/qcom,spmi-vadc.txt
deleted file mode 100644
index c878768..0000000
--- a/Documentation/devicetree/bindings/iio/adc/qcom,spmi-vadc.txt
+++ /dev/null
@@ -1,173 +0,0 @@
-Qualcomm's SPMI PMIC ADC
-
-- SPMI PMIC voltage ADC (VADC) provides interface to clients to read
- voltage. The VADC is a 15-bit sigma-delta ADC.
-- SPMI PMIC5 voltage ADC (ADC) provides interface to clients to read
- voltage. The VADC is a 16-bit sigma-delta ADC.
-
-VADC node:
-
-- compatible:
- Usage: required
- Value type: <string>
- Definition: Should contain "qcom,spmi-vadc".
- Should contain "qcom,spmi-adc5" for PMIC5 ADC driver.
- Should contain "qcom,spmi-adc-rev2" for PMIC rev2 ADC driver.
- Should contain "qcom,pms405-adc" for PMS405 PMIC
-
-- reg:
- Usage: required
- Value type: <prop-encoded-array>
- Definition: VADC base address in the SPMI PMIC register map.
-
-- #address-cells:
- Usage: required
- Value type: <u32>
- Definition: Must be one. Child node 'reg' property should define ADC
- channel number.
-
-- #size-cells:
- Usage: required
- Value type: <u32>
- Definition: Must be zero.
-
-- #io-channel-cells:
- Usage: required
- Value type: <u32>
- Definition: Must be one. For details about IIO bindings see:
- Documentation/devicetree/bindings/iio/iio-bindings.txt
-
-- interrupts:
- Usage: optional
- Value type: <prop-encoded-array>
- Definition: End of conversion interrupt.
-
-Channel node properties:
-
-- reg:
- Usage: required
- Value type: <u32>
- Definition: ADC channel number.
- See include/dt-bindings/iio/qcom,spmi-vadc.h
-
-- label:
- Usage: required for "qcom,spmi-adc5" and "qcom,spmi-adc-rev2"
- Value type: <empty>
- Definition: ADC input of the platform as seen in the schematics.
- For thermistor inputs connected to generic AMUX or GPIO inputs
- these can vary across platform for the same pins. Hence select
- the platform schematics name for this channel.
-
-- qcom,decimation:
- Usage: optional
- Value type: <u32>
- Definition: This parameter is used to decrease ADC sampling rate.
- Quicker measurements can be made by reducing decimation ratio.
- - For compatible property "qcom,spmi-vadc", valid values are
- 512, 1024, 2048, 4096. If property is not found, default value
- of 512 will be used.
- - For compatible property "qcom,spmi-adc5", valid values are 250, 420
- and 840. If property is not found, default value of 840 is used.
- - For compatible property "qcom,spmi-adc-rev2", valid values are 256,
- 512 and 1024. If property is not present, default value is 1024.
-
-- qcom,pre-scaling:
- Usage: optional
- Value type: <u32 array>
- Definition: Used for scaling the channel input signal before the signal is
- fed to VADC. The configuration for this node is to know the
- pre-determined ratio and use it for post scaling. Select one from
- the following options.
- <1 1>, <1 3>, <1 4>, <1 6>, <1 20>, <1 8>, <10 81>, <1 10>
- If property is not found default value depending on chip will be used.
-
-- qcom,ratiometric:
- Usage: optional
- Value type: <empty>
- Definition: Channel calibration type.
- - For compatible property "qcom,spmi-vadc", if this property is
- specified VADC will use the VDD reference (1.8V) and GND for
- channel calibration. If property is not found, channel will be
- calibrated with 0.625V and 1.25V reference channels, also
- known as absolute calibration.
- - For compatible property "qcom,spmi-adc5" and "qcom,spmi-adc-rev2",
- if this property is specified VADC will use the VDD reference
- (1.875V) and GND for channel calibration. If property is not found,
- channel will be calibrated with 0V and 1.25V reference channels,
- also known as absolute calibration.
-
-- qcom,hw-settle-time:
- Usage: optional
- Value type: <u32>
- Definition: Time between AMUX getting configured and the ADC starting
- conversion. The 'hw_settle_time' is an index used from valid values
- and programmed in hardware to achieve the hardware settling delay.
- - For compatible property "qcom,spmi-vadc" and "qcom,spmi-adc-rev2",
- Delay = 100us * (hw_settle_time) for hw_settle_time < 11,
- and 2ms * (hw_settle_time - 10) otherwise.
- Valid values are: 0, 100, 200, 300, 400, 500, 600, 700, 800,
- 900 us and 1, 2, 4, 6, 8, 10 ms.
- If property is not found, channel will use 0us.
- - For compatible property "qcom,spmi-adc5", delay = 15us for
- value 0, 100us * (value) for values < 11,
- and 2ms * (value - 10) otherwise.
- Valid values are: 15, 100, 200, 300, 400, 500, 600, 700, 800,
- 900 us and 1, 2, 4, 6, 8, 10 ms
- Certain controller digital versions have valid values of
- 15, 100, 200, 300, 400, 500, 600, 700, 1, 2, 4, 8, 16, 32, 64, 128 ms
- If property is not found, channel will use 15us.
-
-- qcom,avg-samples:
- Usage: optional
- Value type: <u32>
- Definition: Number of samples to be used for measurement.
- Averaging provides the option to obtain a single measurement
- from the ADC that is an average of multiple samples. The value
- selected is 2^(value).
- - For compatible property "qcom,spmi-vadc", valid values
- are: 1, 2, 4, 8, 16, 32, 64, 128, 256, 512
- If property is not found, 1 sample will be used.
- - For compatible property "qcom,spmi-adc5" and "qcom,spmi-adc-rev2",
- valid values are: 1, 2, 4, 8, 16
- If property is not found, 1 sample will be used.
-
-NOTE:
-
-For compatible property "qcom,spmi-vadc" following channels, also known as
-reference point channels, are used for result calibration and their channel
-configuration nodes should be defined:
-VADC_REF_625MV and/or VADC_SPARE1(based on PMIC version) VADC_REF_1250MV,
-VADC_GND_REF and VADC_VDD_VADC.
-
-Example:
-
-#include <dt-bindings/iio/qcom,spmi-vadc.h>
-#include <linux/irq.h>
-/* ... */
-
- /* VADC node */
- pmic_vadc: vadc@3100 {
- compatible = "qcom,spmi-vadc";
- reg = <0x3100>;
- interrupts = <0x0 0x31 0x0 IRQ_TYPE_EDGE_RISING>;
- #address-cells = <1>;
- #size-cells = <0>;
- #io-channel-cells = <1>;
- io-channel-ranges;
-
- /* Channel node */
- adc-chan@VADC_LR_MUX10_USB_ID {
- reg = <VADC_LR_MUX10_USB_ID>;
- qcom,decimation = <512>;
- qcom,ratiometric;
- qcom,hw-settle-time = <200>;
- qcom,avg-samples = <1>;
- qcom,pre-scaling = <1 3>;
- };
- };
-
- /* IIO client node */
- usb {
- io-channels = <&pmic_vadc VADC_LR_MUX10_USB_ID>;
- io-channel-names = "vadc";
- };
diff --git a/Documentation/devicetree/bindings/iio/adc/qcom,spmi-vadc.yaml b/Documentation/devicetree/bindings/iio/adc/qcom,spmi-vadc.yaml
new file mode 100644
index 0000000..e6263b6
--- /dev/null
+++ b/Documentation/devicetree/bindings/iio/adc/qcom,spmi-vadc.yaml
@@ -0,0 +1,278 @@
+# SPDX-License-Identifier: GPL-2.0-only
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iio/adc/qcom,spmi-vadc.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Qualcomm's SPMI PMIC ADC
+
+maintainers:
+ - Andy Gross <agross@kernel.org>
+ - Bjorn Andersson <bjorn.andersson@linaro.org>
+
+description: |
+ SPMI PMIC voltage ADC (VADC) provides interface to clients to read
+ voltage. The VADC is a 15-bit sigma-delta ADC.
+ SPMI PMIC5/PMIC7 voltage ADC (ADC) provides interface to clients to read
+ voltage. The VADC is a 16-bit sigma-delta ADC.
+
+properties:
+ compatible:
+ oneOf:
+ - items:
+ - const: qcom,pms405-adc
+ - const: qcom,spmi-adc-rev2
+
+ - items:
+ - enum:
+ - qcom,spmi-vadc
+ - qcom,spmi-adc5
+ - qcom,spmi-adc-rev2
+ - qcom,spmi-adc7
+
+ reg:
+ description: VADC base address in the SPMI PMIC register map
+ maxItems: 1
+
+ '#address-cells':
+ const: 1
+
+ '#size-cells':
+ const: 0
+
+ '#io-channel-cells':
+ const: 1
+
+ interrupts:
+ maxItems: 1
+ description:
+ End of conversion interrupt.
+
+required:
+ - compatible
+ - reg
+ - '#address-cells'
+ - '#size-cells'
+ - '#io-channel-cells'
+
+patternProperties:
+ "^.*@[0-9a-f]+$":
+ type: object
+ description: |
+ Represents the external channels which are connected to the ADC.
+ For compatible property "qcom,spmi-vadc" following channels, also known as
+ reference point channels, are used for result calibration and their channel
+ configuration nodes should be defined:
+ VADC_REF_625MV and/or VADC_SPARE1(based on PMIC version) VADC_REF_1250MV,
+ VADC_GND_REF and VADC_VDD_VADC.
+
+ properties:
+ reg:
+ description: |
+ ADC channel number.
+ See include/dt-bindings/iio/qcom,spmi-vadc.h
+ For PMIC7 ADC, the channel numbers are specified separately per PMIC
+ in the PMIC-specific files in include/dt-bindings/iio/.
+
+ label:
+ $ref: /schemas/types.yaml#/definitions/string
+ description: |
+ ADC input of the platform as seen in the schematics.
+ For thermistor inputs connected to generic AMUX or GPIO inputs
+ these can vary across platform for the same pins. Hence select
+ the platform schematics name for this channel.
+
+ qcom,decimation:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description: |
+ This parameter is used to decrease ADC sampling rate.
+ Quicker measurements can be made by reducing decimation ratio.
+
+ qcom,pre-scaling:
+ description: |
+ Used for scaling the channel input signal before the signal is
+ fed to VADC. The configuration for this node is to know the
+ pre-determined ratio and use it for post scaling. It is a pair of
+ integers, denoting the numerator and denominator of the fraction by which
+ input signal is multiplied. For example, <1 3> indicates the signal is scaled
+ down to 1/3 of its value before ADC measurement.
+ If property is not found default value depending on chip will be used.
+ allOf:
+ - $ref: /schemas/types.yaml#/definitions/uint32-array
+ oneOf:
+ - items:
+ - const: 1
+ - enum: [ 1, 3, 4, 6, 20, 8, 10 ]
+
+ - items:
+ - const: 10
+ - const: 81
+
+ qcom,ratiometric:
+ description: |
+ Channel calibration type.
+ - For compatible property "qcom,spmi-vadc", if this property is
+ specified VADC will use the VDD reference (1.8V) and GND for
+ channel calibration. If property is not found, channel will be
+ calibrated with 0.625V and 1.25V reference channels, also
+ known as absolute calibration.
+ - For compatible property "qcom,spmi-adc5", "qcom,spmi-adc7" and
+ "qcom,spmi-adc-rev2", if this property is specified VADC will use
+ the VDD reference (1.875V) and GND for channel calibration. If
+ property is not found, channel will be calibrated with 0V and 1.25V
+ reference channels, also known as absolute calibration.
+ type: boolean
+
+ qcom,hw-settle-time:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description: |
+ Time between AMUX getting configured and the ADC starting
+ conversion. The 'hw_settle_time' is an index used from valid values
+ and programmed in hardware to achieve the hardware settling delay.
+
+ qcom,avg-samples:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description: |
+ Number of samples to be used for measurement.
+ Averaging provides the option to obtain a single measurement
+ from the ADC that is an average of multiple samples. The value
+ selected is 2^(value).
+
+ required:
+ - reg
+
+allOf:
+ - if:
+ properties:
+ compatible:
+ contains:
+ const: qcom,spmi-vadc
+
+ then:
+ patternProperties:
+ "^.*@[0-9a-f]+$":
+ properties:
+ qcom,decimation:
+ enum: [ 512, 1024, 2048, 4096 ]
+ default: 512
+
+ qcom,hw-settle-time:
+ enum: [ 0, 100, 200, 300, 400, 500, 600, 700, 800, 900, 1, 2,
+ 4, 6, 8, 10 ]
+ default: 0
+
+ qcom,avg-samples:
+ enum: [ 1, 2, 4, 8, 16, 32, 64, 128, 256, 512 ]
+ default: 1
+
+ - if:
+ properties:
+ compatible:
+ contains:
+ const: qcom,spmi-adc-rev2
+
+ then:
+ patternProperties:
+ "^.*@[0-9a-f]+$":
+ properties:
+ qcom,decimation:
+ enum: [ 256, 512, 1024 ]
+ default: 1024
+
+ qcom,hw-settle-time:
+ enum: [ 0, 100, 200, 300, 400, 500, 600, 700, 800, 900, 1, 2,
+ 4, 6, 8, 10 ]
+ default: 0
+
+ qcom,avg-samples:
+ enum: [ 1, 2, 4, 8, 16 ]
+ default: 1
+
+ - if:
+ properties:
+ compatible:
+ contains:
+ const: qcom,spmi-adc5
+
+ then:
+ patternProperties:
+ "^.*@[0-9a-f]+$":
+ properties:
+ qcom,decimation:
+ enum: [ 250, 420, 840 ]
+ default: 840
+
+ qcom,hw-settle-time:
+ enum: [ 15, 100, 200, 300, 400, 500, 600, 700, 800, 900, 1, 2,
+ 4, 6, 8, 10, 16, 32, 64, 128 ]
+ default: 15
+
+ qcom,avg-samples:
+ enum: [ 1, 2, 4, 8, 16 ]
+ default: 1
+
+ - if:
+ properties:
+ compatible:
+ contains:
+ const: qcom,spmi-adc7
+
+ then:
+ patternProperties:
+ "^.*@[0-9a-f]+$":
+ properties:
+ qcom,decimation:
+ enum: [ 85, 340, 1360 ]
+ default: 1360
+
+ qcom,hw-settle-time:
+ enum: [ 15, 100, 200, 300, 400, 500, 600, 700, 1000, 2000, 4000,
+ 8000, 16000, 32000, 64000, 128000 ]
+ default: 15
+
+ qcom,avg-samples:
+ enum: [ 1, 2, 4, 8, 16 ]
+ default: 1
+
+examples:
+ - |
+ spmi_bus {
+ #address-cells = <1>;
+ #size-cells = <0>;
+ /* VADC node */
+ pmic_vadc: adc@3100 {
+ compatible = "qcom,spmi-vadc";
+ reg = <0x3100>;
+ interrupts = <0x0 0x31 0x0 0x1>;
+ #address-cells = <1>;
+ #size-cells = <0>;
+ #io-channel-cells = <1>;
+ io-channel-ranges;
+
+ /* Channel node */
+ adc-chan@39 {
+ reg = <0x39>;
+ qcom,decimation = <512>;
+ qcom,ratiometric;
+ qcom,hw-settle-time = <200>;
+ qcom,avg-samples = <1>;
+ qcom,pre-scaling = <1 3>;
+ };
+
+ adc-chan@9 {
+ reg = <0x9>;
+ };
+
+ adc-chan@a {
+ reg = <0xa>;
+ };
+
+ adc-chan@e {
+ reg = <0xe>;
+ };
+
+ adc-chan@f {
+ reg = <0xf>;
+ };
+ };
+ };
diff --git a/Documentation/devicetree/bindings/iio/adc/ti,ads8688.yaml b/Documentation/devicetree/bindings/iio/adc/ti,ads8688.yaml
new file mode 100644
index 0000000..97fe6cb
--- /dev/null
+++ b/Documentation/devicetree/bindings/iio/adc/ti,ads8688.yaml
@@ -0,0 +1,45 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iio/adc/ti,ads8688.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Texas Instruments' ADS8684 and ADS8688 ADC chip
+
+maintainers:
+ - Sean Nyekjaer <sean@geanix.com>
+
+description: |
+ SPI 16bit ADCs with 4/8 channels.
+
+properties:
+ compatible:
+ enum:
+ - ti,ads8684
+ - ti,ads8688
+
+ reg:
+ maxItems: 1
+
+ vref-supply:
+ description: Optional external reference. If not supplied, assume
+ REFSEL input tied low to enable the internal reference.
+
+required:
+ - compatible
+ - reg
+
+examples:
+ - |
+ spi {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ adc@0 {
+ compatible = "ti,ads8688";
+ reg = <0>;
+ vref-supply = <&vdd_supply>;
+ spi-max-frequency = <1000000>;
+ };
+ };
+...
diff --git a/Documentation/devicetree/bindings/iio/adc/ti-ads8688.txt b/Documentation/devicetree/bindings/iio/adc/ti-ads8688.txt
deleted file mode 100644
index a02337d..0000000
--- a/Documentation/devicetree/bindings/iio/adc/ti-ads8688.txt
+++ /dev/null
@@ -1,20 +0,0 @@
-* Texas Instruments' ADS8684 and ADS8688 ADC chip
-
-Required properties:
- - compatible: Should be "ti,ads8684" or "ti,ads8688"
- - reg: spi chip select number for the device
-
-Recommended properties:
- - spi-max-frequency: Definition as per
- Documentation/devicetree/bindings/spi/spi-bus.txt
-
-Optional properties:
- - vref-supply: The regulator supply for ADC reference voltage
-
-Example:
-adc@0 {
- compatible = "ti,ads8688";
- reg = <0>;
- vref-supply = <&vdd_supply>;
- spi-max-frequency = <1000000>;
-};
diff --git a/Documentation/devicetree/bindings/iio/chemical/sensirion,scd30.yaml b/Documentation/devicetree/bindings/iio/chemical/sensirion,scd30.yaml
new file mode 100644
index 0000000..40d8734
--- /dev/null
+++ b/Documentation/devicetree/bindings/iio/chemical/sensirion,scd30.yaml
@@ -0,0 +1,68 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iio/chemical/sensirion,scd30.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Sensirion SCD30 carbon dioxide sensor
+
+maintainers:
+ - Tomasz Duszynski <tomasz.duszynski@octakon.com>
+
+description: |
+ Air quality sensor capable of measuring co2 concentration, temperature
+ and relative humidity.
+
+properties:
+ compatible:
+ enum:
+ - sensirion,scd30
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+ vdd-supply: true
+
+ sensirion,sel-gpios:
+ description: GPIO connected to the SEL line
+ maxItems: 1
+
+ sensirion,pwm-gpios:
+ description: GPIO connected to the PWM line
+ maxItems: 1
+
+required:
+ - compatible
+
+additionalProperties: false
+
+examples:
+ - |
+ # include <dt-bindings/interrupt-controller/irq.h>
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ co2-sensor@61 {
+ compatible = "sensirion,scd30";
+ reg = <0x61>;
+ vdd-supply = <&vdd>;
+ interrupt-parent = <&gpio0>;
+ interrupts = <0 IRQ_TYPE_LEVEL_HIGH>;
+ };
+ };
+ - |
+ # include <dt-bindings/interrupt-controller/irq.h>
+ serial {
+ co2-sensor {
+ compatible = "sensirion,scd30";
+ vdd-supply = <&vdd>;
+ interrupt-parent = <&gpio0>;
+ interrupts = <0 IRQ_TYPE_LEVEL_HIGH>;
+ };
+ };
+
+...
diff --git a/Documentation/devicetree/bindings/iio/dac/ti,dac7612.txt b/Documentation/devicetree/bindings/iio/dac/ti,dac7612.txt
index 639c94e..17af395 100644
--- a/Documentation/devicetree/bindings/iio/dac/ti,dac7612.txt
+++ b/Documentation/devicetree/bindings/iio/dac/ti,dac7612.txt
@@ -6,7 +6,7 @@
The internal DACs are loaded when the LOADDACS pin is pulled down.
-http://www.ti.com/lit/ds/sbas106/sbas106.pdf
+https://www.ti.com/lit/ds/sbas106/sbas106.pdf
Required Properties:
- compatible: Should be one of:
diff --git a/Documentation/devicetree/bindings/iio/iio-bindings.txt b/Documentation/devicetree/bindings/iio/iio-bindings.txt
index af33267..aa63cac 100644
--- a/Documentation/devicetree/bindings/iio/iio-bindings.txt
+++ b/Documentation/devicetree/bindings/iio/iio-bindings.txt
@@ -9,7 +9,7 @@
output on a device. The length of an IIO specifier is defined by the
value of a #io-channel-cells property in the IIO provider node.
-[1] http://marc.info/?l=linux-iio&m=135902119507483&w=2
+[1] https://marc.info/?l=linux-iio&m=135902119507483&w=2
==IIO providers==
diff --git a/Documentation/devicetree/bindings/iio/imu/bosch,bmi160.yaml b/Documentation/devicetree/bindings/iio/imu/bosch,bmi160.yaml
index 0d0ef84..33d8e9f 100644
--- a/Documentation/devicetree/bindings/iio/imu/bosch,bmi160.yaml
+++ b/Documentation/devicetree/bindings/iio/imu/bosch,bmi160.yaml
@@ -37,6 +37,15 @@
set if the specified interrupt pin should be configured as
open drain. If not set, defaults to push-pull.
+ vdd-supply:
+ description: provide VDD power to the sensor.
+
+ vddio-supply:
+ description: provide VDD IO power to the sensor.
+
+ mount-matrix:
+ description: an optional 3x3 mounting rotation matrix
+
required:
- compatible
- reg
@@ -52,9 +61,14 @@
bmi160@68 {
compatible = "bosch,bmi160";
reg = <0x68>;
+ vdd-supply = <&pm8916_l17>;
+ vddio-supply = <&pm8916_l6>;
interrupt-parent = <&gpio4>;
interrupts = <12 IRQ_TYPE_EDGE_RISING>;
interrupt-names = "INT1";
+ mount-matrix = "0", "1", "0",
+ "-1", "0", "0",
+ "0", "0", "1";
};
};
- |
diff --git a/Documentation/devicetree/bindings/iio/imu/invensense,icm42600.yaml b/Documentation/devicetree/bindings/iio/imu/invensense,icm42600.yaml
new file mode 100644
index 0000000..abd8d25
--- /dev/null
+++ b/Documentation/devicetree/bindings/iio/imu/invensense,icm42600.yaml
@@ -0,0 +1,90 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iio/imu/invensense,icm42600.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: InvenSense ICM-426xx Inertial Measurement Unit
+
+maintainers:
+ - Jean-Baptiste Maneyrol <jmaneyrol@invensense.com>
+
+description: |
+ 6-axis MotionTracking device that combines a 3-axis gyroscope and a 3-axis
+ accelerometer.
+
+ It has a configurable host interface that supports I3C, I2C and SPI serial
+ communication, features a 2kB FIFO and 2 programmable interrupts with
+ ultra-low-power wake-on-motion support to minimize system power consumption.
+
+ Other industry-leading features include InvenSense on-chip APEX Motion
+ Processing engine for gesture recognition, activity classification, and
+ pedometer, along with programmable digital filters, and an embedded
+ temperature sensor.
+
+ https://invensense.tdk.com/wp-content/uploads/2020/03/DS-000292-ICM-42605-v1.4.pdf
+
+properties:
+ compatible:
+ enum:
+ - invensense,icm42600
+ - invensense,icm42602
+ - invensense,icm42605
+ - invensense,icm42622
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+ drive-open-drain:
+ type: boolean
+
+ vdd-supply:
+ description: Regulator that provides power to the sensor
+
+ vddio-supply:
+ description: Regulator that provides power to the bus
+
+required:
+ - compatible
+ - reg
+ - interrupts
+
+examples:
+ - |
+ #include <dt-bindings/gpio/gpio.h>
+ #include <dt-bindings/interrupt-controller/irq.h>
+ i2c0 {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ icm42605@68 {
+ compatible = "invensense,icm42605";
+ reg = <0x68>;
+ interrupt-parent = <&gpio2>;
+ interrupts = <7 IRQ_TYPE_EDGE_FALLING>;
+ vdd-supply = <&vdd>;
+ vddio-supply = <&vddio>;
+ };
+ };
+ - |
+ #include <dt-bindings/gpio/gpio.h>
+ #include <dt-bindings/interrupt-controller/irq.h>
+ spi0 {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ icm42602@0 {
+ compatible = "invensense,icm42602";
+ reg = <0>;
+ spi-max-frequency = <24000000>;
+ spi-cpha;
+ spi-cpol;
+ interrupt-parent = <&gpio1>;
+ interrupts = <2 IRQ_TYPE_EDGE_FALLING>;
+ vdd-supply = <&vdd>;
+ vddio-supply = <&vddio>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/iio/light/apds9300.txt b/Documentation/devicetree/bindings/iio/light/apds9300.txt
index aa199e0..3aa6db3 100644
--- a/Documentation/devicetree/bindings/iio/light/apds9300.txt
+++ b/Documentation/devicetree/bindings/iio/light/apds9300.txt
@@ -1,6 +1,6 @@
* Avago APDS9300 ambient light sensor
-http://www.avagotech.com/docs/AV02-1077EN
+https://www.avagotech.com/docs/AV02-1077EN
Required properties:
diff --git a/Documentation/devicetree/bindings/iio/light/apds9960.txt b/Documentation/devicetree/bindings/iio/light/apds9960.txt
index 3af325a..c53ddb8 100644
--- a/Documentation/devicetree/bindings/iio/light/apds9960.txt
+++ b/Documentation/devicetree/bindings/iio/light/apds9960.txt
@@ -1,6 +1,6 @@
* Avago APDS9960 gesture/RGB/ALS/proximity sensor
-http://www.avagotech.com/docs/AV02-4191EN
+https://www.avagotech.com/docs/AV02-4191EN
Required properties:
diff --git a/Documentation/devicetree/bindings/iio/light/opt3001.txt b/Documentation/devicetree/bindings/iio/light/opt3001.txt
index 47b13eb..9e6f299 100644
--- a/Documentation/devicetree/bindings/iio/light/opt3001.txt
+++ b/Documentation/devicetree/bindings/iio/light/opt3001.txt
@@ -6,7 +6,7 @@
requires the use of interrupts. Without interrupts, only the simple reading
of the current light value is supported through the IIO API.
-http://www.ti.com/product/opt3001
+https://www.ti.com/product/opt3001
Required properties:
- compatible: should be "ti,opt3001"
diff --git a/Documentation/devicetree/bindings/iio/light/vl6180.txt b/Documentation/devicetree/bindings/iio/light/vl6180.txt
index 2c52952..fb9137d 100644
--- a/Documentation/devicetree/bindings/iio/light/vl6180.txt
+++ b/Documentation/devicetree/bindings/iio/light/vl6180.txt
@@ -1,6 +1,6 @@
STMicro VL6180 - ALS, range and proximity sensor
-Link to datasheet: http://www.st.com/resource/en/datasheet/vl6180x.pdf
+Link to datasheet: https://www.st.com/resource/en/datasheet/vl6180x.pdf
Required properties:
diff --git a/Documentation/devicetree/bindings/iio/magnetometer/ak8975.txt b/Documentation/devicetree/bindings/iio/magnetometer/ak8975.txt
deleted file mode 100644
index aa67ceb..0000000
--- a/Documentation/devicetree/bindings/iio/magnetometer/ak8975.txt
+++ /dev/null
@@ -1,30 +0,0 @@
-* AsahiKASEI AK8975 magnetometer sensor
-
-Required properties:
-
- - compatible : should be "asahi-kasei,ak8975"
- - reg : the I2C address of the magnetometer
-
-Optional properties:
-
- - gpios : should be device tree identifier of the magnetometer DRDY pin
- - vdd-supply: an optional regulator that needs to be on to provide VDD
- - mount-matrix: an optional 3x3 mounting rotation matrix
-
-Example:
-
-ak8975@c {
- compatible = "asahi-kasei,ak8975";
- reg = <0x0c>;
- gpios = <&gpj0 7 0>;
- vdd-supply = <&ldo_3v3_gnss>;
- mount-matrix = "-0.984807753012208", /* x0 */
- "0", /* y0 */
- "-0.173648177666930", /* z0 */
- "0", /* x1 */
- "-1", /* y1 */
- "0", /* z1 */
- "-0.173648177666930", /* x2 */
- "0", /* y2 */
- "0.984807753012208"; /* z2 */
-};
diff --git a/Documentation/devicetree/bindings/iio/magnetometer/asahi-kasei,ak8975.yaml b/Documentation/devicetree/bindings/iio/magnetometer/asahi-kasei,ak8975.yaml
new file mode 100644
index 0000000..f4393bf
--- /dev/null
+++ b/Documentation/devicetree/bindings/iio/magnetometer/asahi-kasei,ak8975.yaml
@@ -0,0 +1,83 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iio/magnetometer/asahi-kasei,ak8975.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: AsahiKASEI AK8975 magnetometer sensor
+
+maintainers:
+ - Jonathan Albrieux <jonathan.albrieux@gmail.com>
+
+properties:
+ compatible:
+ oneOf:
+ - enum:
+ - asahi-kasei,ak8975
+ - asahi-kasei,ak8963
+ - asahi-kasei,ak09911
+ - asahi-kasei,ak09912
+ - enum:
+ - ak8975
+ - ak8963
+ - ak09911
+ - ak09912
+ deprecated: true
+
+ reg:
+ maxItems: 1
+
+ gpios:
+ maxItems: 1
+ description: |
+ AK8975 has a "Data ready" pin (DRDY) which informs that data
+ is ready to be read and is possible to listen on it. If used,
+ this should be active high. Prefer interrupt over this.
+
+ interrupts:
+ maxItems: 1
+ description: interrupt for DRDY pin. Triggered on rising edge.
+
+ vdd-supply:
+ description: |
+ an optional regulator that needs to be on to provide VDD power to
+ the sensor.
+
+ mount-matrix:
+ description: an optional 3x3 mounting rotation matrix.
+
+ reset-gpios:
+ description: |
+ an optional pin needed for AK09911 to set the reset state. This should
+ be usually active low
+
+required:
+ - compatible
+ - reg
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/irq.h>
+ #include <dt-bindings/gpio/gpio.h>
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ magnetometer@c {
+ compatible = "asahi-kasei,ak8975";
+ reg = <0x0c>;
+ interrupt-parent = <&gpio6>;
+ interrupts = <15 IRQ_TYPE_EDGE_RISING>;
+ vdd-supply = <&ldo_3v3_gnss>;
+ reset-gpios = <&msmgpio 111 GPIO_ACTIVE_LOW>;
+ mount-matrix = "-0.984807753012208", /* x0 */
+ "0", /* y0 */
+ "-0.173648177666930", /* z0 */
+ "0", /* x1 */
+ "-1", /* y1 */
+ "0", /* z1 */
+ "-0.173648177666930", /* x2 */
+ "0", /* y2 */
+ "0.984807753012208"; /* z2 */
+ };
+ };
diff --git a/Documentation/devicetree/bindings/iio/magnetometer/bmc150_magn.txt b/Documentation/devicetree/bindings/iio/magnetometer/bmc150_magn.txt
index fd5fca9..22912e4 100644
--- a/Documentation/devicetree/bindings/iio/magnetometer/bmc150_magn.txt
+++ b/Documentation/devicetree/bindings/iio/magnetometer/bmc150_magn.txt
@@ -4,7 +4,11 @@
Required properties:
- - compatible : should be "bosch,bmc150_magn"
+ - compatible : should be one of:
+ "bosch,bmc150_magn"
+ "bosch,bmc156_magn"
+ "bosch,bmm150"
+ "bosch,bmm150_magn" (DEPRECATED, use bosch,bmm150)
- reg : the I2C address of the magnetometer
Optional properties:
diff --git a/Documentation/devicetree/bindings/iio/multiplexer/io-channel-mux.txt b/Documentation/devicetree/bindings/iio/multiplexer/io-channel-mux.txt
index c827940..89647d7 100644
--- a/Documentation/devicetree/bindings/iio/multiplexer/io-channel-mux.txt
+++ b/Documentation/devicetree/bindings/iio/multiplexer/io-channel-mux.txt
@@ -21,7 +21,7 @@
Example:
mux: mux-controller {
- compatible = "mux-gpio";
+ compatible = "gpio-mux";
#mux-control-cells = <0>;
mux-gpios = <&pioA 0 GPIO_ACTIVE_HIGH>,
diff --git a/Documentation/devicetree/bindings/iio/potentiometer/mcp41010.txt b/Documentation/devicetree/bindings/iio/potentiometer/mcp41010.txt
index 566711b..4f245e8 100644
--- a/Documentation/devicetree/bindings/iio/potentiometer/mcp41010.txt
+++ b/Documentation/devicetree/bindings/iio/potentiometer/mcp41010.txt
@@ -1,7 +1,7 @@
* Microchip MCP41010/41050/41100/42010/42050/42100 Digital Potentiometer
Datasheet publicly available at:
-http://ww1.microchip.com/downloads/en/devicedoc/11195c.pdf
+https://ww1.microchip.com/downloads/en/devicedoc/11195c.pdf
The node for this driver must be a child node of a SPI controller, hence
all mandatory properties described in
diff --git a/Documentation/devicetree/bindings/iio/potentiostat/lmp91000.txt b/Documentation/devicetree/bindings/iio/potentiostat/lmp91000.txt
index e6d0c2e..f3ab02b 100644
--- a/Documentation/devicetree/bindings/iio/potentiostat/lmp91000.txt
+++ b/Documentation/devicetree/bindings/iio/potentiostat/lmp91000.txt
@@ -1,7 +1,7 @@
* Texas Instruments LMP91000 series of potentiostats
-LMP91000: http://www.ti.com/lit/ds/symlink/lmp91000.pdf
-LMP91002: http://www.ti.com/lit/ds/symlink/lmp91002.pdf
+LMP91000: https://www.ti.com/lit/ds/symlink/lmp91000.pdf
+LMP91002: https://www.ti.com/lit/ds/symlink/lmp91002.pdf
Required properties:
diff --git a/Documentation/devicetree/bindings/iio/pressure/asc,dlhl60d.yaml b/Documentation/devicetree/bindings/iio/pressure/asc,dlhl60d.yaml
index 64c18f1..be2be4b 100644
--- a/Documentation/devicetree/bindings/iio/pressure/asc,dlhl60d.yaml
+++ b/Documentation/devicetree/bindings/iio/pressure/asc,dlhl60d.yaml
@@ -13,7 +13,7 @@
Bindings for the All Sensors DLH series pressure sensors.
Specifications about the sensors can be found at:
- http://www.allsensors.com/cad/DS-0355_Rev_B.PDF
+ https://www.allsensors.com/cad/DS-0355_Rev_B.PDF
properties:
compatible:
diff --git a/Documentation/devicetree/bindings/iio/proximity/devantech-srf04.yaml b/Documentation/devicetree/bindings/iio/proximity/devantech-srf04.yaml
index f86f8b2..ce79527 100644
--- a/Documentation/devicetree/bindings/iio/proximity/devantech-srf04.yaml
+++ b/Documentation/devicetree/bindings/iio/proximity/devantech-srf04.yaml
@@ -17,9 +17,9 @@
until it is received once again
Specifications about the devices can be found at:
- http://www.robot-electronics.co.uk/htm/srf04tech.htm
+ https://www.robot-electronics.co.uk/htm/srf04tech.htm
- http://www.maxbotix.com/documents/LV-MaxSonar-EZ_Datasheet.pdf
+ https://www.maxbotix.com/documents/LV-MaxSonar-EZ_Datasheet.pdf
properties:
compatible:
diff --git a/Documentation/devicetree/bindings/input/imx-keypad.txt b/Documentation/devicetree/bindings/input/imx-keypad.txt
deleted file mode 100644
index 2ebaf7d..0000000
--- a/Documentation/devicetree/bindings/input/imx-keypad.txt
+++ /dev/null
@@ -1,53 +0,0 @@
-* Freescale i.MX Keypad Port(KPP) device tree bindings
-
-The KPP is designed to interface with a keypad matrix with 2-point contact
-or 3-point contact keys. The KPP is designed to simplify the software task
-of scanning a keypad matrix. The KPP is capable of detecting, debouncing,
-and decoding one or multiple keys pressed simultaneously on a keypad.
-
-Required SoC Specific Properties:
-- compatible: Should be "fsl,<soc>-kpp".
-
-- reg: Physical base address of the KPP and length of memory mapped
- region.
-
-- interrupts: The KPP interrupt number to the CPU(s).
-
-- clocks: The clock provided by the SoC to the KPP. Some SoCs use dummy
-clock(The clock for the KPP is provided by the SoCs automatically).
-
-Required Board Specific Properties:
-- pinctrl-names: The definition can be found at
-pinctrl/pinctrl-bindings.txt.
-
-- pinctrl-0: The definition can be found at
-pinctrl/pinctrl-bindings.txt.
-
-- linux,keymap: The definition can be found at
-bindings/input/matrix-keymap.txt.
-
-Example:
-kpp: kpp@73f94000 {
- compatible = "fsl,imx51-kpp", "fsl,imx21-kpp";
- reg = <0x73f94000 0x4000>;
- interrupts = <60>;
- clocks = <&clks 0>;
- pinctrl-names = "default";
- pinctrl-0 = <&pinctrl_kpp_1>;
- linux,keymap = <0x00000067 /* KEY_UP */
- 0x0001006c /* KEY_DOWN */
- 0x00020072 /* KEY_VOLUMEDOWN */
- 0x00030066 /* KEY_HOME */
- 0x0100006a /* KEY_RIGHT */
- 0x01010069 /* KEY_LEFT */
- 0x0102001c /* KEY_ENTER */
- 0x01030073 /* KEY_VOLUMEUP */
- 0x02000040 /* KEY_F6 */
- 0x02010042 /* KEY_F8 */
- 0x02020043 /* KEY_F9 */
- 0x02030044 /* KEY_F10 */
- 0x0300003b /* KEY_F1 */
- 0x0301003c /* KEY_F2 */
- 0x0302003d /* KEY_F3 */
- 0x03030074>; /* KEY_POWER */
-};
diff --git a/Documentation/devicetree/bindings/input/imx-keypad.yaml b/Documentation/devicetree/bindings/input/imx-keypad.yaml
new file mode 100644
index 0000000..7432c6e
--- /dev/null
+++ b/Documentation/devicetree/bindings/input/imx-keypad.yaml
@@ -0,0 +1,85 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/input/imx-keypad.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Freescale i.MX Keypad Port(KPP) device tree bindings
+
+maintainers:
+ - Liu Ying <gnuiyl@gmail.com>
+
+allOf:
+ - $ref: "/schemas/input/matrix-keymap.yaml#"
+
+description: |
+ The KPP is designed to interface with a keypad matrix with 2-point contact
+ or 3-point contact keys. The KPP is designed to simplify the software task
+ of scanning a keypad matrix. The KPP is capable of detecting, debouncing,
+ and decoding one or multiple keys pressed simultaneously on a keypad.
+
+properties:
+ compatible:
+ oneOf:
+ - const: fsl,imx21-kpp
+ - items:
+ - enum:
+ - fsl,imx25-kpp
+ - fsl,imx27-kpp
+ - fsl,imx31-kpp
+ - fsl,imx35-kpp
+ - fsl,imx51-kpp
+ - fsl,imx53-kpp
+ - fsl,imx50-kpp
+ - fsl,imx6q-kpp
+ - fsl,imx6sx-kpp
+ - fsl,imx6sl-kpp
+ - fsl,imx6sll-kpp
+ - fsl,imx6ul-kpp
+ - fsl,imx7d-kpp
+ - const: fsl,imx21-kpp
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+ clocks:
+ maxItems: 1
+
+required:
+ - compatible
+ - reg
+ - interrupts
+ - clocks
+ - linux,keymap
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ keypad@73f94000 {
+ compatible = "fsl,imx51-kpp", "fsl,imx21-kpp";
+ reg = <0x73f94000 0x4000>;
+ interrupts = <60>;
+ clocks = <&clks 0>;
+ pinctrl-names = "default";
+ pinctrl-0 = <&pinctrl_kpp_1>;
+ linux,keymap = <0x00000067 /* KEY_UP */
+ 0x0001006c /* KEY_DOWN */
+ 0x00020072 /* KEY_VOLUMEDOWN */
+ 0x00030066 /* KEY_HOME */
+ 0x0100006a /* KEY_RIGHT */
+ 0x01010069 /* KEY_LEFT */
+ 0x0102001c /* KEY_ENTER */
+ 0x01030073 /* KEY_VOLUMEUP */
+ 0x02000040 /* KEY_F6 */
+ 0x02010042 /* KEY_F8 */
+ 0x02020043 /* KEY_F9 */
+ 0x02030044 /* KEY_F10 */
+ 0x0300003b /* KEY_F1 */
+ 0x0301003c /* KEY_F2 */
+ 0x0302003d /* KEY_F3 */
+ 0x03030074>; /* KEY_POWER */
+ };
diff --git a/Documentation/devicetree/bindings/input/matrix-keymap.txt b/Documentation/devicetree/bindings/input/matrix-keymap.txt
index c54919f..79f6d01 100644
--- a/Documentation/devicetree/bindings/input/matrix-keymap.txt
+++ b/Documentation/devicetree/bindings/input/matrix-keymap.txt
@@ -1,27 +1 @@
-A simple common binding for matrix-connected key boards. Currently targeted at
-defining the keys in the scope of linux key codes since that is a stable and
-standardized interface at this time.
-
-Required properties:
-- linux,keymap: an array of packed 1-cell entries containing the equivalent
- of row, column and linux key-code. The 32-bit big endian cell is packed
- as:
- row << 24 | column << 16 | key-code
-
-Optional properties:
-Properties for the number of rows and columns are optional because some
-drivers will use fixed values for these.
-- keypad,num-rows: Number of row lines connected to the keypad controller.
-- keypad,num-columns: Number of column lines connected to the keypad
- controller.
-
-Some users of this binding might choose to specify secondary keymaps for
-cases where there is a modifier key such as a Fn key. Proposed names
-for said properties are "linux,fn-keymap" or with another descriptive
-word for the modifier other from "Fn".
-
-Example:
- linux,keymap = < 0x00030012
- 0x0102003a >;
- keypad,num-rows = <2>;
- keypad,num-columns = <8>;
+This file has been moved to matrix-keymap.yaml
diff --git a/Documentation/devicetree/bindings/input/matrix-keymap.yaml b/Documentation/devicetree/bindings/input/matrix-keymap.yaml
new file mode 100644
index 0000000..c3bf091
--- /dev/null
+++ b/Documentation/devicetree/bindings/input/matrix-keymap.yaml
@@ -0,0 +1,46 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/input/matrix-keymap.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Common key matrices binding for matrix-connected key boards
+
+maintainers:
+ - Olof Johansson <olof@lixom.net>
+
+description: |
+ A simple common binding for matrix-connected key boards. Currently targeted at
+ defining the keys in the scope of linux key codes since that is a stable and
+ standardized interface at this time.
+
+ Some users of this binding might choose to specify secondary keymaps for
+ cases where there is a modifier key such as a Fn key. Proposed names
+ for said properties are "linux,fn-keymap" or with another descriptive
+ word for the modifier other from "Fn".
+
+properties:
+ linux,keymap:
+ $ref: '/schemas/types.yaml#/definitions/uint32-array'
+ description: |
+ An array of packed 1-cell entries containing the equivalent of row,
+ column and linux key-code. The 32-bit big endian cell is packed as:
+ row << 24 | column << 16 | key-code
+
+ keypad,num-rows:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description: Number of row lines connected to the keypad controller.
+
+ keypad,num-columns:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description: Number of column lines connected to the keypad controller.
+
+examples:
+ - |
+ keypad {
+ /* ... */
+ linux,keymap = < 0x00030012
+ 0x0102003a >;
+ keypad,num-rows = <2>;
+ keypad,num-columns = <8>;
+ };
diff --git a/Documentation/devicetree/bindings/input/touchscreen/eeti,exc3000.yaml b/Documentation/devicetree/bindings/input/touchscreen/eeti,exc3000.yaml
new file mode 100644
index 0000000..007adbc
--- /dev/null
+++ b/Documentation/devicetree/bindings/input/touchscreen/eeti,exc3000.yaml
@@ -0,0 +1,58 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/input/touchscreen/eeti,exc3000.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: EETI EXC3000 series touchscreen controller
+
+maintainers:
+ - Dmitry Torokhov <dmitry.torokhov@gmail.com>
+
+allOf:
+ - $ref: touchscreen.yaml#
+
+properties:
+ compatible:
+ enum:
+ - eeti,exc3000
+ - eeti,exc80h60
+ - eeti,exc80h84
+ reg:
+ const: 0x2a
+ interrupts:
+ maxItems: 1
+ reset-gpios:
+ maxItems: 1
+ touchscreen-size-x: true
+ touchscreen-size-y: true
+ touchscreen-inverted-x: true
+ touchscreen-inverted-y: true
+ touchscreen-swapped-x-y: true
+
+required:
+ - compatible
+ - reg
+ - interrupts
+ - touchscreen-size-x
+ - touchscreen-size-y
+
+additionalProperties: false
+
+examples:
+ - |
+ #include "dt-bindings/interrupt-controller/irq.h"
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+ touchscreen@2a {
+ compatible = "eeti,exc3000";
+ reg = <0x2a>;
+ interrupt-parent = <&gpio1>;
+ interrupts = <9 IRQ_TYPE_LEVEL_LOW>;
+ touchscreen-size-x = <4096>;
+ touchscreen-size-y = <4096>;
+ touchscreen-inverted-x;
+ touchscreen-swapped-x-y;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/input/touchscreen/exc3000.txt b/Documentation/devicetree/bindings/input/touchscreen/exc3000.txt
deleted file mode 100644
index 68291b9..0000000
--- a/Documentation/devicetree/bindings/input/touchscreen/exc3000.txt
+++ /dev/null
@@ -1,26 +0,0 @@
-* EETI EXC3000 Multiple Touch Controller
-
-Required properties:
-- compatible: must be "eeti,exc3000"
-- reg: i2c slave address
-- interrupts: touch controller interrupt
-- touchscreen-size-x: See touchscreen.txt
-- touchscreen-size-y: See touchscreen.txt
-
-Optional properties:
-- touchscreen-inverted-x: See touchscreen.txt
-- touchscreen-inverted-y: See touchscreen.txt
-- touchscreen-swapped-x-y: See touchscreen.txt
-
-Example:
-
- touchscreen@2a {
- compatible = "eeti,exc3000";
- reg = <0x2a>;
- interrupt-parent = <&gpio1>;
- interrupts = <9 IRQ_TYPE_LEVEL_LOW>;
- touchscreen-size-x = <4096>;
- touchscreen-size-y = <4096>;
- touchscreen-inverted-x;
- touchscreen-swapped-x-y;
- };
diff --git a/Documentation/devicetree/bindings/interrupt-controller/brcm,l2-intc.txt b/Documentation/devicetree/bindings/interrupt-controller/brcm,l2-intc.txt
index d514ec0..021cf82 100644
--- a/Documentation/devicetree/bindings/interrupt-controller/brcm,l2-intc.txt
+++ b/Documentation/devicetree/bindings/interrupt-controller/brcm,l2-intc.txt
@@ -2,7 +2,10 @@
Required properties:
-- compatible: should be "brcm,l2-intc" for latched interrupt controllers
+- compatible: should be one of:
+ "brcm,hif-spi-l2-intc" or
+ "brcm,upg-aux-aon-l2-intc" or
+ "brcm,l2-intc" for latched interrupt controllers
should be "brcm,bcm7271-l2-intc" for level interrupt controllers
- reg: specifies the base physical address and size of the registers
- interrupt-controller: identifies the node as an interrupt controller
diff --git a/Documentation/devicetree/bindings/interrupt-controller/csky,mpintc.txt b/Documentation/devicetree/bindings/interrupt-controller/csky,mpintc.txt
index e134053..e6bbcae 100644
--- a/Documentation/devicetree/bindings/interrupt-controller/csky,mpintc.txt
+++ b/Documentation/devicetree/bindings/interrupt-controller/csky,mpintc.txt
@@ -10,7 +10,7 @@
16-31 : private irq, and we use 16 as the co-processor timer.
31-1024: common irq for soc ip.
-Interrupt triger mode: (Defined in dt-bindings/interrupt-controller/irq.h)
+Interrupt trigger mode: (Defined in dt-bindings/interrupt-controller/irq.h)
IRQ_TYPE_LEVEL_HIGH (default)
IRQ_TYPE_LEVEL_LOW
IRQ_TYPE_EDGE_RISING
diff --git a/Documentation/devicetree/bindings/interrupt-controller/loongson,htvec.yaml b/Documentation/devicetree/bindings/interrupt-controller/loongson,htvec.yaml
index e865cd8..87a7455 100644
--- a/Documentation/devicetree/bindings/interrupt-controller/loongson,htvec.yaml
+++ b/Documentation/devicetree/bindings/interrupt-controller/loongson,htvec.yaml
@@ -22,8 +22,8 @@
interrupts:
minItems: 1
- maxItems: 4
- description: Four parent interrupts that receive chained interrupts.
+ maxItems: 8
+ description: Eight parent interrupts that receive chained interrupts.
interrupt-controller: true
diff --git a/Documentation/devicetree/bindings/interrupt-controller/loongson,liointc.yaml b/Documentation/devicetree/bindings/interrupt-controller/loongson,liointc.yaml
index b1db21e..03fc4f5 100644
--- a/Documentation/devicetree/bindings/interrupt-controller/loongson,liointc.yaml
+++ b/Documentation/devicetree/bindings/interrupt-controller/loongson,liointc.yaml
@@ -51,8 +51,8 @@
description: |
This property points how the children interrupts will be mapped into CPU
interrupt lines. Each cell refers to a parent interrupt line from 0 to 3
- and each bit in the cell refers to a children interrupt fron 0 to 31.
- If a CPU interrupt line didn't connected with liointc, then keep it's
+ and each bit in the cell refers to a child interrupt from 0 to 31.
+ If a CPU interrupt line didn't connect with liointc, then keep its
cell with zero.
$ref: /schemas/types.yaml#/definitions/uint32-array
minItems: 4
diff --git a/Documentation/devicetree/bindings/interrupt-controller/mips-gic.txt b/Documentation/devicetree/bindings/interrupt-controller/mips-gic.txt
deleted file mode 100644
index 1735953..0000000
--- a/Documentation/devicetree/bindings/interrupt-controller/mips-gic.txt
+++ /dev/null
@@ -1,67 +0,0 @@
-MIPS Global Interrupt Controller (GIC)
-
-The MIPS GIC routes external interrupts to individual VPEs and IRQ pins.
-It also supports local (per-processor) interrupts and software-generated
-interrupts which can be used as IPIs. The GIC also includes a free-running
-global timer, per-CPU count/compare timers, and a watchdog.
-
-Required properties:
-- compatible : Should be "mti,gic".
-- interrupt-controller : Identifies the node as an interrupt controller
-- #interrupt-cells : Specifies the number of cells needed to encode an
- interrupt specifier. Should be 3.
- - The first cell is the type of interrupt, local or shared.
- See <include/dt-bindings/interrupt-controller/mips-gic.h>.
- - The second cell is the GIC interrupt number.
- - The third cell encodes the interrupt flags.
- See <include/dt-bindings/interrupt-controller/irq.h> for a list of valid
- flags.
-
-Optional properties:
-- reg : Base address and length of the GIC registers. If not present,
- the base address reported by the hardware GCR_GIC_BASE will be used.
-- mti,reserved-cpu-vectors : Specifies the list of CPU interrupt vectors
- to which the GIC may not route interrupts. Valid values are 2 - 7.
- This property is ignored if the CPU is started in EIC mode.
-- mti,reserved-ipi-vectors : Specifies the range of GIC interrupts that are
- reserved for IPIs.
- It accepts 2 values, the 1st is the starting interrupt and the 2nd is the size
- of the reserved range.
- If not specified, the driver will allocate the last 2 * number of VPEs in the
- system.
-
-Required properties for timer sub-node:
-- compatible : Should be "mti,gic-timer".
-- interrupts : Interrupt for the GIC local timer.
-
-Optional properties for timer sub-node:
-- clocks : GIC timer operating clock.
-- clock-frequency : Clock frequency at which the GIC timers operate.
-
-Note that one of clocks or clock-frequency must be specified.
-
-Example:
-
- gic: interrupt-controller@1bdc0000 {
- compatible = "mti,gic";
- reg = <0x1bdc0000 0x20000>;
-
- interrupt-controller;
- #interrupt-cells = <3>;
-
- mti,reserved-cpu-vectors = <7>;
- mti,reserved-ipi-vectors = <40 8>;
-
- timer {
- compatible = "mti,gic-timer";
- interrupts = <GIC_LOCAL 1 IRQ_TYPE_NONE>;
- clock-frequency = <50000000>;
- };
- };
-
- uart@18101400 {
- ...
- interrupt-parent = <&gic>;
- interrupts = <GIC_SHARED 24 IRQ_TYPE_LEVEL_HIGH>;
- ...
- };
diff --git a/Documentation/devicetree/bindings/interrupt-controller/mrvl,intc.txt b/Documentation/devicetree/bindings/interrupt-controller/mrvl,intc.txt
deleted file mode 100644
index a0ed027..0000000
--- a/Documentation/devicetree/bindings/interrupt-controller/mrvl,intc.txt
+++ /dev/null
@@ -1,64 +0,0 @@
-* Marvell MMP Interrupt controller
-
-Required properties:
-- compatible : Should be
- "mrvl,mmp-intc" on Marvel MMP,
- "mrvl,mmp2-intc" along with "mrvl,mmp2-mux-intc" on MMP2 or
- "marvell,mmp3-intc" with "mrvl,mmp2-mux-intc" on MMP3
-- reg : Address and length of the register set of the interrupt controller.
- If the interrupt controller is intc, address and length means the range
- of the whole interrupt controller. The "marvell,mmp3-intc" controller
- also has a secondary range for the second CPU core. If the interrupt
- controller is mux-intc, address and length means one register. Since
- address of mux-intc is in the range of intc. mux-intc is secondary
- interrupt controller.
-- reg-names : Name of the register set of the interrupt controller. It's
- only required in mux-intc interrupt controller.
-- interrupts : Should be the port interrupt shared by mux interrupts. It's
- only required in mux-intc interrupt controller.
-- interrupt-controller : Identifies the node as an interrupt controller.
-- #interrupt-cells : Specifies the number of cells needed to encode an
- interrupt source.
-- mrvl,intc-nr-irqs : Specifies the number of interrupts in the interrupt
- controller.
-- mrvl,clr-mfp-irq : Specifies the interrupt that needs to clear MFP edge
- detection first.
-
-Example:
- intc: interrupt-controller@d4282000 {
- compatible = "mrvl,mmp2-intc";
- interrupt-controller;
- #interrupt-cells = <1>;
- reg = <0xd4282000 0x1000>;
- mrvl,intc-nr-irqs = <64>;
- };
-
- intcmux4@d4282150 {
- compatible = "mrvl,mmp2-mux-intc";
- interrupts = <4>;
- interrupt-controller;
- #interrupt-cells = <1>;
- reg = <0x150 0x4>, <0x168 0x4>;
- reg-names = "mux status", "mux mask";
- mrvl,intc-nr-irqs = <2>;
- };
-
-* Marvell Orion Interrupt controller
-
-Required properties
-- compatible : Should be "marvell,orion-intc".
-- #interrupt-cells: Specifies the number of cells needed to encode an
- interrupt source. Supported value is <1>.
-- interrupt-controller : Declare this node to be an interrupt controller.
-- reg : Interrupt mask address. A list of 4 byte ranges, one per controller.
- One entry in the list represents 32 interrupts.
-
-Example:
-
- intc: interrupt-controller {
- compatible = "marvell,orion-intc", "marvell,intc";
- interrupt-controller;
- #interrupt-cells = <1>;
- reg = <0xfed20204 0x04>,
- <0xfed20214 0x04>;
- };
diff --git a/Documentation/devicetree/bindings/interrupt-controller/mrvl,intc.yaml b/Documentation/devicetree/bindings/interrupt-controller/mrvl,intc.yaml
new file mode 100644
index 0000000..372ccbf
--- /dev/null
+++ b/Documentation/devicetree/bindings/interrupt-controller/mrvl,intc.yaml
@@ -0,0 +1,134 @@
+# SPDX-License-Identifier: GPL-2.0-only
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/interrupt-controller/mrvl,intc.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Marvell MMP/Orion Interrupt controller bindings
+
+maintainers:
+ - Thomas Gleixner <tglx@linutronix.de>
+ - Jason Cooper <jason@lakedaemon.net>
+ - Marc Zyngier <maz@kernel.org>
+ - Rob Herring <robh+dt@kernel.org>
+
+allOf:
+ - if:
+ properties:
+ compatible:
+ not:
+ contains:
+ const: marvell,orion-intc
+ then:
+ required:
+ - mrvl,intc-nr-irqs
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - mrvl,mmp-intc
+ - mrvl,mmp2-intc
+ then:
+ properties:
+ reg:
+ maxItems: 1
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - marvell,mmp3-intc
+ - mrvl,mmp2-mux-intc
+ then:
+ properties:
+ reg:
+ minItems: 2
+ - if:
+ properties:
+ compatible:
+ contains:
+ const: mrvl,mmp2-mux-intc
+ then:
+ properties:
+ interrupts:
+ maxItems: 1
+ reg-names:
+ items:
+ - const: 'mux status'
+ - const: 'mux mask'
+ required:
+ - interrupts
+ else:
+ properties:
+ interrupts: false
+
+properties:
+ '#interrupt-cells':
+ const: 1
+
+ compatible:
+ enum:
+ - mrvl,mmp-intc
+ - mrvl,mmp2-intc
+ - marvell,mmp3-intc
+ - marvell,orion-intc
+ - mrvl,mmp2-mux-intc
+
+ reg:
+ minItems: 1
+ maxItems: 2
+
+ reg-names: true
+
+ interrupts: true
+
+ interrupt-controller: true
+
+ mrvl,intc-nr-irqs:
+ description: |
+ Specifies the number of interrupts in the interrupt controller.
+ $ref: /schemas/types.yaml#/definitions/uint32
+
+ mrvl,clr-mfp-irq:
+ description: |
+ Specifies the interrupt that needs to clear MFP edge detection first.
+ $ref: /schemas/types.yaml#/definitions/uint32
+
+required:
+ - '#interrupt-cells'
+ - compatible
+ - reg
+ - interrupt-controller
+
+additionalProperties: false
+
+examples:
+ - |
+ interrupt-controller@d4282000 {
+ compatible = "mrvl,mmp2-intc";
+ interrupt-controller;
+ #interrupt-cells = <1>;
+ reg = <0xd4282000 0x1000>;
+ mrvl,intc-nr-irqs = <64>;
+ };
+
+ interrupt-controller@d4282150 {
+ compatible = "mrvl,mmp2-mux-intc";
+ interrupts = <4>;
+ interrupt-controller;
+ #interrupt-cells = <1>;
+ reg = <0x150 0x4>, <0x168 0x4>;
+ reg-names = "mux status", "mux mask";
+ mrvl,intc-nr-irqs = <2>;
+ };
+ - |
+ interrupt-controller@fed20204 {
+ compatible = "marvell,orion-intc";
+ interrupt-controller;
+ #interrupt-cells = <1>;
+ reg = <0xfed20204 0x04>,
+ <0xfed20214 0x04>;
+ };
+
+...
diff --git a/Documentation/devicetree/bindings/interrupt-controller/mti,gic.yaml b/Documentation/devicetree/bindings/interrupt-controller/mti,gic.yaml
new file mode 100644
index 0000000..9f0eb3a
--- /dev/null
+++ b/Documentation/devicetree/bindings/interrupt-controller/mti,gic.yaml
@@ -0,0 +1,148 @@
+# SPDX-License-Identifier: GPL-2.0-only
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/interrupt-controller/mti,gic.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: MIPS Global Interrupt Controller
+
+maintainers:
+ - Paul Burton <paulburton@kernel.org>
+ - Thomas Bogendoerfer <tsbogend@alpha.franken.de>
+
+description: |
+ The MIPS GIC routes external interrupts to individual VPEs and IRQ pins.
+ It also supports local (per-processor) interrupts and software-generated
+ interrupts which can be used as IPIs. The GIC also includes a free-running
+ global timer, per-CPU count/compare timers, and a watchdog.
+
+properties:
+ compatible:
+ const: mti,gic
+
+ "#interrupt-cells":
+ const: 3
+ description: |
+ The 1st cell is the type of interrupt: local or shared defined in the
+ file 'dt-bindings/interrupt-controller/mips-gic.h'. The 2nd cell is the
+ GIC interrupt number. The 3d cell encodes the interrupt flags setting up
+ the IRQ trigger modes, which are defined in the file
+ 'dt-bindings/interrupt-controller/irq.h'.
+
+ reg:
+ description: |
+ Base address and length of the GIC registers space. If not present,
+ the base address reported by the hardware GCR_GIC_BASE will be used.
+ maxItems: 1
+
+ interrupt-controller: true
+
+ mti,reserved-cpu-vectors:
+ description: |
+ Specifies the list of CPU interrupt vectors to which the GIC may not
+ route interrupts. This property is ignored if the CPU is started in EIC
+ mode.
+ allOf:
+ - $ref: /schemas/types.yaml#definitions/uint32-array
+ - minItems: 1
+ maxItems: 6
+ uniqueItems: true
+ items:
+ minimum: 2
+ maximum: 7
+
+ mti,reserved-ipi-vectors:
+ description: |
+ Specifies the range of GIC interrupts that are reserved for IPIs.
+ It accepts two values: the 1st is the starting interrupt and the 2nd is
+ the size of the reserved range. If not specified, the driver will
+ allocate the last (2 * number of VPEs in the system).
+ allOf:
+ - $ref: /schemas/types.yaml#definitions/uint32-array
+ - items:
+ - minimum: 0
+ maximum: 254
+ - minimum: 2
+ maximum: 254
+
+ timer:
+ type: object
+ description: |
+ MIPS GIC includes a free-running global timer, per-CPU count/compare
+ timers, and a watchdog. Currently only the GIC Timer is supported.
+ properties:
+ compatible:
+ const: mti,gic-timer
+
+ interrupts:
+ description: |
+ Interrupt for the GIC local timer, so normally it's suppose to be of
+ <GIC_LOCAL X IRQ_TYPE_NONE> format.
+ maxItems: 1
+
+ clocks:
+ maxItems: 1
+
+ clock-frequency: true
+
+ required:
+ - compatible
+ - interrupts
+
+ oneOf:
+ - required:
+ - clocks
+ - required:
+ - clock-frequency
+
+ additionalProperties: false
+
+unevaluatedProperties: false
+
+required:
+ - compatible
+ - "#interrupt-cells"
+ - interrupt-controller
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/mips-gic.h>
+ #include <dt-bindings/interrupt-controller/irq.h>
+
+ interrupt-controller@1bdc0000 {
+ compatible = "mti,gic";
+ reg = <0x1bdc0000 0x20000>;
+ interrupt-controller;
+ #interrupt-cells = <3>;
+ mti,reserved-cpu-vectors = <7>;
+ mti,reserved-ipi-vectors = <40 8>;
+
+ timer {
+ compatible = "mti,gic-timer";
+ interrupts = <GIC_LOCAL 1 IRQ_TYPE_NONE>;
+ clock-frequency = <50000000>;
+ };
+ };
+ - |
+ #include <dt-bindings/interrupt-controller/mips-gic.h>
+ #include <dt-bindings/interrupt-controller/irq.h>
+
+ interrupt-controller@1bdc0000 {
+ compatible = "mti,gic";
+ reg = <0x1bdc0000 0x20000>;
+ interrupt-controller;
+ #interrupt-cells = <3>;
+
+ timer {
+ compatible = "mti,gic-timer";
+ interrupts = <GIC_LOCAL 1 IRQ_TYPE_NONE>;
+ clocks = <&cpu_pll>;
+ };
+ };
+ - |
+ interrupt-controller {
+ compatible = "mti,gic";
+ interrupt-controller;
+ #interrupt-cells = <3>;
+ };
+...
diff --git a/Documentation/devicetree/bindings/interrupt-controller/renesas,rza1-irqc.txt b/Documentation/devicetree/bindings/interrupt-controller/renesas,rza1-irqc.txt
deleted file mode 100644
index 727b7e4..0000000
--- a/Documentation/devicetree/bindings/interrupt-controller/renesas,rza1-irqc.txt
+++ /dev/null
@@ -1,43 +0,0 @@
-DT bindings for the Renesas RZ/A1 Interrupt Controller
-
-The RZ/A1 Interrupt Controller is a front-end for the GIC found on Renesas
-RZ/A1 and RZ/A2 SoCs:
- - IRQ sense select for 8 external interrupts, 1:1-mapped to 8 GIC SPI
- interrupts,
- - NMI edge select.
-
-Required properties:
- - compatible: Must be "renesas,<soctype>-irqc", and "renesas,rza1-irqc" as
- fallback.
- Examples with soctypes are:
- - "renesas,r7s72100-irqc" (RZ/A1H)
- - "renesas,r7s9210-irqc" (RZ/A2M)
- - #interrupt-cells: Must be 2 (an interrupt index and flags, as defined
- in interrupts.txt in this directory)
- - #address-cells: Must be zero
- - interrupt-controller: Marks the device as an interrupt controller
- - reg: Base address and length of the memory resource used by the interrupt
- controller
- - interrupt-map: Specifies the mapping from external interrupts to GIC
- interrupts
- - interrupt-map-mask: Must be <7 0>
-
-Example:
-
- irqc: interrupt-controller@fcfef800 {
- compatible = "renesas,r7s72100-irqc", "renesas,rza1-irqc";
- #interrupt-cells = <2>;
- #address-cells = <0>;
- interrupt-controller;
- reg = <0xfcfef800 0x6>;
- interrupt-map =
- <0 0 &gic GIC_SPI 0 IRQ_TYPE_LEVEL_HIGH>,
- <1 0 &gic GIC_SPI 1 IRQ_TYPE_LEVEL_HIGH>,
- <2 0 &gic GIC_SPI 2 IRQ_TYPE_LEVEL_HIGH>,
- <3 0 &gic GIC_SPI 3 IRQ_TYPE_LEVEL_HIGH>,
- <4 0 &gic GIC_SPI 4 IRQ_TYPE_LEVEL_HIGH>,
- <5 0 &gic GIC_SPI 5 IRQ_TYPE_LEVEL_HIGH>,
- <6 0 &gic GIC_SPI 6 IRQ_TYPE_LEVEL_HIGH>,
- <7 0 &gic GIC_SPI 7 IRQ_TYPE_LEVEL_HIGH>;
- interrupt-map-mask = <7 0>;
- };
diff --git a/Documentation/devicetree/bindings/interrupt-controller/renesas,rza1-irqc.yaml b/Documentation/devicetree/bindings/interrupt-controller/renesas,rza1-irqc.yaml
new file mode 100644
index 0000000..755cdfa
--- /dev/null
+++ b/Documentation/devicetree/bindings/interrupt-controller/renesas,rza1-irqc.yaml
@@ -0,0 +1,80 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/interrupt-controller/renesas,rza1-irqc.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Renesas RZ/A1 Interrupt Controller
+
+maintainers:
+ - Chris Brandt <chris.brandt@renesas.com>
+ - Geert Uytterhoeven <geert+renesas@glider.be>
+
+description: |
+ The RZ/A1 Interrupt Controller is a front-end for the GIC found on Renesas RZ/A1 and
+ RZ/A2 SoCs:
+ - IRQ sense select for 8 external interrupts, 1:1-mapped to 8 GIC SPI interrupts,
+ - NMI edge select.
+
+allOf:
+ - $ref: /schemas/interrupt-controller.yaml#
+
+properties:
+ compatible:
+ items:
+ - enum:
+ - renesas,r7s72100-irqc # RZ/A1H
+ - renesas,r7s9210-irqc # RZ/A2M
+ - const: renesas,rza1-irqc
+
+ '#interrupt-cells':
+ const: 2
+
+ '#address-cells':
+ const: 0
+
+ interrupt-controller: true
+
+ reg:
+ maxItems: 1
+
+ interrupt-map:
+ maxItems: 8
+ description: Specifies the mapping from external interrupts to GIC interrupts.
+
+ interrupt-map-mask:
+ items:
+ - const: 7
+ - const: 0
+
+required:
+ - compatible
+ - '#interrupt-cells'
+ - '#address-cells'
+ - interrupt-controller
+ - reg
+ - interrupt-map
+ - interrupt-map-mask
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+ irqc: interrupt-controller@fcfef800 {
+ compatible = "renesas,r7s72100-irqc", "renesas,rza1-irqc";
+ #interrupt-cells = <2>;
+ #address-cells = <0>;
+ interrupt-controller;
+ reg = <0xfcfef800 0x6>;
+ interrupt-map =
+ <0 0 &gic GIC_SPI 0 IRQ_TYPE_LEVEL_HIGH>,
+ <1 0 &gic GIC_SPI 1 IRQ_TYPE_LEVEL_HIGH>,
+ <2 0 &gic GIC_SPI 2 IRQ_TYPE_LEVEL_HIGH>,
+ <3 0 &gic GIC_SPI 3 IRQ_TYPE_LEVEL_HIGH>,
+ <4 0 &gic GIC_SPI 4 IRQ_TYPE_LEVEL_HIGH>,
+ <5 0 &gic GIC_SPI 5 IRQ_TYPE_LEVEL_HIGH>,
+ <6 0 &gic GIC_SPI 6 IRQ_TYPE_LEVEL_HIGH>,
+ <7 0 &gic GIC_SPI 7 IRQ_TYPE_LEVEL_HIGH>;
+ interrupt-map-mask = <7 0>;
+ };
diff --git a/Documentation/devicetree/bindings/interrupt-controller/ti,sci-intr.txt b/Documentation/devicetree/bindings/interrupt-controller/ti,sci-intr.txt
index 1a8718f..178fca0 100644
--- a/Documentation/devicetree/bindings/interrupt-controller/ti,sci-intr.txt
+++ b/Documentation/devicetree/bindings/interrupt-controller/ti,sci-intr.txt
@@ -55,7 +55,7 @@
corresponds to a range of host irqs.
For more details on TISCI IRQ resource management refer:
-http://downloads.ti.com/tisci/esd/latest/2_tisci_msgs/rm/rm_irq.html
+https://downloads.ti.com/tisci/esd/latest/2_tisci_msgs/rm/rm_irq.html
Example:
--------
diff --git a/Documentation/devicetree/bindings/iommu/arm,smmu.yaml b/Documentation/devicetree/bindings/iommu/arm,smmu.yaml
index d7ceb4c..503160a 100644
--- a/Documentation/devicetree/bindings/iommu/arm,smmu.yaml
+++ b/Documentation/devicetree/bindings/iommu/arm,smmu.yaml
@@ -37,7 +37,18 @@
- enum:
- qcom,sc7180-smmu-500
- qcom,sdm845-smmu-500
+ - qcom,sm8150-smmu-500
+ - qcom,sm8250-smmu-500
- const: arm,mmu-500
+ - description: Marvell SoCs implementing "arm,mmu-500"
+ items:
+ - const: marvell,ap806-smmu-500
+ - const: arm,mmu-500
+ - description: NVIDIA SoCs that program two ARM MMU-500s identically
+ items:
+ - enum:
+ - nvidia,tegra194-smmu
+ - const: nvidia,smmu-500
- items:
- const: arm,mmu-500
- const: arm,smmu-v2
@@ -55,7 +66,8 @@
- cavium,smmu-v2
reg:
- maxItems: 1
+ minItems: 1
+ maxItems: 2
'#global-interrupts':
description: The number of global interrupts exposed by the device.
@@ -138,6 +150,23 @@
additionalProperties: false
+allOf:
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - nvidia,tegra194-smmu
+ then:
+ properties:
+ reg:
+ minItems: 2
+ maxItems: 2
+ else:
+ properties:
+ reg:
+ maxItems: 1
+
examples:
- |+
/* SMMU with stream matching or stream indexing */
diff --git a/Documentation/devicetree/bindings/iommu/mediatek,iommu.txt b/Documentation/devicetree/bindings/iommu/mediatek,iommu.txt
index ce59a50..c1ccd85 100644
--- a/Documentation/devicetree/bindings/iommu/mediatek,iommu.txt
+++ b/Documentation/devicetree/bindings/iommu/mediatek,iommu.txt
@@ -58,6 +58,7 @@
- compatible : must be one of the following string:
"mediatek,mt2701-m4u" for mt2701 which uses generation one m4u HW.
"mediatek,mt2712-m4u" for mt2712 which uses generation two m4u HW.
+ "mediatek,mt6779-m4u" for mt6779 which uses generation two m4u HW.
"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.
@@ -78,6 +79,7 @@
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,
+ dt-binding/memory/mt6779-larb-port.h for mt6779,
dt-binding/memory/mt8173-larb-port.h for mt8173, and
dt-binding/memory/mt8183-larb-port.h for mt8183.
diff --git a/Documentation/devicetree/bindings/iommu/renesas,ipmmu-vmsa.yaml b/Documentation/devicetree/bindings/iommu/renesas,ipmmu-vmsa.yaml
index 39675cf..6bfa090 100644
--- a/Documentation/devicetree/bindings/iommu/renesas,ipmmu-vmsa.yaml
+++ b/Documentation/devicetree/bindings/iommu/renesas,ipmmu-vmsa.yaml
@@ -32,9 +32,11 @@
- enum:
- renesas,ipmmu-r8a774a1 # RZ/G2M
- renesas,ipmmu-r8a774b1 # RZ/G2N
+ - renesas,ipmmu-r8a774e1 # RZ/G2H
- renesas,ipmmu-r8a774c0 # RZ/G2E
- renesas,ipmmu-r8a7795 # R-Car H3
- renesas,ipmmu-r8a7796 # R-Car M3-W
+ - renesas,ipmmu-r8a77961 # R-Car M3-W+
- renesas,ipmmu-r8a77965 # R-Car M3-N
- renesas,ipmmu-r8a77970 # R-Car V3M
- renesas,ipmmu-r8a77980 # R-Car V3H
diff --git a/Documentation/devicetree/bindings/leds/backlight/gpio-backlight.txt b/Documentation/devicetree/bindings/leds/backlight/gpio-backlight.txt
deleted file mode 100644
index 321be66..0000000
--- a/Documentation/devicetree/bindings/leds/backlight/gpio-backlight.txt
+++ /dev/null
@@ -1,16 +0,0 @@
-gpio-backlight bindings
-
-Required properties:
- - compatible: "gpio-backlight"
- - gpios: describes the gpio that is used for enabling/disabling the backlight.
- refer to bindings/gpio/gpio.txt for more details.
-
-Optional properties:
- - default-on: enable the backlight at boot.
-
-Example:
- backlight {
- compatible = "gpio-backlight";
- gpios = <&gpio3 4 GPIO_ACTIVE_HIGH>;
- default-on;
- };
diff --git a/Documentation/devicetree/bindings/leds/backlight/gpio-backlight.yaml b/Documentation/devicetree/bindings/leds/backlight/gpio-backlight.yaml
new file mode 100644
index 0000000..75cc569
--- /dev/null
+++ b/Documentation/devicetree/bindings/leds/backlight/gpio-backlight.yaml
@@ -0,0 +1,41 @@
+# SPDX-License-Identifier: GPL-2.0-only
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/leds/backlight/gpio-backlight.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: gpio-backlight bindings
+
+maintainers:
+ - Lee Jones <lee.jones@linaro.org>
+ - Daniel Thompson <daniel.thompson@linaro.org>
+ - Jingoo Han <jingoohan1@gmail.com>
+
+properties:
+ compatible:
+ const: gpio-backlight
+
+ gpios:
+ description: The gpio that is used for enabling/disabling the backlight.
+ maxItems: 1
+
+ default-on:
+ description: enable the backlight at boot.
+ type: boolean
+
+required:
+ - compatible
+ - gpios
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/gpio/gpio.h>
+ backlight {
+ compatible = "gpio-backlight";
+ gpios = <&gpio3 4 GPIO_ACTIVE_HIGH>;
+ default-on;
+ };
+
+...
diff --git a/Documentation/devicetree/bindings/leds/backlight/led-backlight.txt b/Documentation/devicetree/bindings/leds/backlight/led-backlight.txt
deleted file mode 100644
index 4c7dfbe..0000000
--- a/Documentation/devicetree/bindings/leds/backlight/led-backlight.txt
+++ /dev/null
@@ -1,28 +0,0 @@
-led-backlight bindings
-
-This binding is used to describe a basic backlight device made of LEDs.
-It can also be used to describe a backlight device controlled by the output of
-a LED driver.
-
-Required properties:
- - compatible: "led-backlight"
- - leds: a list of LEDs
-
-Optional properties:
- - brightness-levels: Array of distinct brightness levels. The levels must be
- in the range accepted by the underlying LED devices.
- This is used to translate a backlight brightness level
- into a LED brightness level. If it is not provided, the
- identity mapping is used.
-
- - default-brightness-level: The default brightness level.
-
-Example:
-
- backlight {
- compatible = "led-backlight";
-
- leds = <&led1>, <&led2>;
- brightness-levels = <0 4 8 16 32 64 128 255>;
- default-brightness-level = <6>;
- };
diff --git a/Documentation/devicetree/bindings/leds/backlight/led-backlight.yaml b/Documentation/devicetree/bindings/leds/backlight/led-backlight.yaml
new file mode 100644
index 0000000..625082b
--- /dev/null
+++ b/Documentation/devicetree/bindings/leds/backlight/led-backlight.yaml
@@ -0,0 +1,57 @@
+# SPDX-License-Identifier: GPL-2.0-only
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/leds/backlight/led-backlight.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: led-backlight bindings
+
+maintainers:
+ - Lee Jones <lee.jones@linaro.org>
+ - Daniel Thompson <daniel.thompson@linaro.org>
+ - Jingoo Han <jingoohan1@gmail.com>
+
+description:
+ This binding is used to describe a basic backlight device made of LEDs. It
+ can also be used to describe a backlight device controlled by the output of
+ a LED driver.
+
+properties:
+ compatible:
+ const: led-backlight
+
+ leds:
+ description: A list of LED nodes
+ $ref: /schemas/types.yaml#/definitions/phandle-array
+
+ brightness-levels:
+ description:
+ Array of distinct brightness levels. The levels must be in the range
+ accepted by the underlying LED devices. This is used to translate a
+ backlight brightness level into a LED brightness level. If it is not
+ provided, the identity mapping is used.
+ $ref: /schemas/types.yaml#/definitions/uint32-array
+
+ default-brightness-level:
+ description:
+ The default brightness level (index into the array defined by the
+ "brightness-levels" property).
+ $ref: /schemas/types.yaml#/definitions/uint32
+
+required:
+ - compatible
+ - leds
+
+additionalProperties: false
+
+examples:
+ - |
+ backlight {
+ compatible = "led-backlight";
+
+ leds = <&led1>, <&led2>;
+ brightness-levels = <0 4 8 16 32 64 128 255>;
+ default-brightness-level = <6>;
+ };
+
+...
diff --git a/Documentation/devicetree/bindings/leds/backlight/pwm-backlight.txt b/Documentation/devicetree/bindings/leds/backlight/pwm-backlight.txt
deleted file mode 100644
index 64fa2fb..0000000
--- a/Documentation/devicetree/bindings/leds/backlight/pwm-backlight.txt
+++ /dev/null
@@ -1,61 +0,0 @@
-pwm-backlight bindings
-
-Required properties:
- - compatible: "pwm-backlight"
- - pwms: OF device-tree PWM specification (see PWM binding[0])
- - power-supply: regulator for supply voltage
-
-Optional properties:
- - pwm-names: a list of names for the PWM devices specified in the
- "pwms" property (see PWM binding[0])
- - enable-gpios: contains a single GPIO specifier for the GPIO which enables
- and disables the backlight (see GPIO binding[1])
- - post-pwm-on-delay-ms: Delay in ms between setting an initial (non-zero) PWM
- and enabling the backlight using GPIO.
- - pwm-off-delay-ms: Delay in ms between disabling the backlight using GPIO
- and setting PWM value to 0.
- - brightness-levels: Array of distinct brightness levels. Typically these
- are in the range from 0 to 255, but any range starting at
- 0 will do. The actual brightness level (PWM duty cycle)
- will be interpolated from these values. 0 means a 0% duty
- cycle (darkest/off), while the last value in the array
- represents a 100% duty cycle (brightest).
- - default-brightness-level: The default brightness level (index into the
- array defined by the "brightness-levels" property).
- - num-interpolated-steps: Number of interpolated steps between each value
- of brightness-levels table. This way a high
- resolution pwm duty cycle can be used without
- having to list out every possible value in the
- brightness-level array.
-
-[0]: Documentation/devicetree/bindings/pwm/pwm.txt
-[1]: Documentation/devicetree/bindings/gpio/gpio.txt
-
-Example:
-
- backlight {
- compatible = "pwm-backlight";
- pwms = <&pwm 0 5000000>;
-
- brightness-levels = <0 4 8 16 32 64 128 255>;
- default-brightness-level = <6>;
-
- power-supply = <&vdd_bl_reg>;
- enable-gpios = <&gpio 58 0>;
- post-pwm-on-delay-ms = <10>;
- pwm-off-delay-ms = <10>;
- };
-
-Example using num-interpolation-steps:
-
- backlight {
- compatible = "pwm-backlight";
- pwms = <&pwm 0 5000000>;
-
- brightness-levels = <0 2048 4096 8192 16384 65535>;
- num-interpolated-steps = <2048>;
- default-brightness-level = <4096>;
-
- power-supply = <&vdd_bl_reg>;
- enable-gpios = <&gpio 58 0>;
- };
diff --git a/Documentation/devicetree/bindings/leds/backlight/pwm-backlight.yaml b/Documentation/devicetree/bindings/leds/backlight/pwm-backlight.yaml
new file mode 100644
index 0000000..fcb8429
--- /dev/null
+++ b/Documentation/devicetree/bindings/leds/backlight/pwm-backlight.yaml
@@ -0,0 +1,104 @@
+# SPDX-License-Identifier: GPL-2.0-only
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/leds/backlight/pwm-backlight.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: pwm-backlight bindings
+
+maintainers:
+ - Lee Jones <lee.jones@linaro.org>
+ - Daniel Thompson <daniel.thompson@linaro.org>
+ - Jingoo Han <jingoohan1@gmail.com>
+
+properties:
+ compatible:
+ const: pwm-backlight
+
+ pwms:
+ maxItems: 1
+
+ pwm-names: true
+
+ power-supply:
+ description: regulator for supply voltage
+
+ enable-gpios:
+ description:
+ Contains a single GPIO specifier for the GPIO which enables and disables
+ the backlight.
+ maxItems: 1
+
+ post-pwm-on-delay-ms:
+ description:
+ Delay in ms between setting an initial (non-zero) PWM and enabling the
+ backlight using GPIO.
+
+ pwm-off-delay-ms:
+ description:
+ Delay in ms between disabling the backlight using GPIO and setting PWM
+ value to 0.
+
+ brightness-levels:
+ description:
+ Array of distinct brightness levels. Typically these are in the range
+ from 0 to 255, but any range starting at 0 will do. The actual brightness
+ level (PWM duty cycle) will be interpolated from these values. 0 means a
+ 0% duty cycle (darkest/off), while the last value in the array represents
+ a 100% duty cycle (brightest).
+ $ref: /schemas/types.yaml#/definitions/uint32-array
+
+ default-brightness-level:
+ description:
+ The default brightness level (index into the array defined by the
+ "brightness-levels" property).
+ $ref: /schemas/types.yaml#/definitions/uint32
+
+ num-interpolated-steps:
+ description:
+ Number of interpolated steps between each value of brightness-levels
+ table. This way a high resolution pwm duty cycle can be used without
+ having to list out every possible value in the brightness-level array.
+ $ref: /schemas/types.yaml#/definitions/uint32
+
+dependencies:
+ default-brightness-level: [brightness-levels]
+ num-interpolated-steps: [brightness-levels]
+
+required:
+ - compatible
+ - pwms
+ - power-supply
+
+additionalProperties: false
+
+examples:
+ - |
+ backlight {
+ compatible = "pwm-backlight";
+ pwms = <&pwm 0 5000000>;
+
+ brightness-levels = <0 4 8 16 32 64 128 255>;
+ default-brightness-level = <6>;
+
+ power-supply = <&vdd_bl_reg>;
+ enable-gpios = <&gpio 58 0>;
+ post-pwm-on-delay-ms = <10>;
+ pwm-off-delay-ms = <10>;
+ };
+
+ - |
+ // Example using num-interpolation-steps:
+ backlight {
+ compatible = "pwm-backlight";
+ pwms = <&pwm 0 5000000>;
+
+ brightness-levels = <0 2048 4096 8192 16384 65535>;
+ num-interpolated-steps = <2048>;
+ default-brightness-level = <4096>;
+
+ power-supply = <&vdd_bl_reg>;
+ enable-gpios = <&gpio 58 0>;
+ };
+
+...
diff --git a/Documentation/devicetree/bindings/leds/cznic,turris-omnia-leds.yaml b/Documentation/devicetree/bindings/leds/cznic,turris-omnia-leds.yaml
new file mode 100644
index 0000000..24ad144
--- /dev/null
+++ b/Documentation/devicetree/bindings/leds/cznic,turris-omnia-leds.yaml
@@ -0,0 +1,90 @@
+# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/leds/cznic,turris-omnia-leds.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: CZ.NIC's Turris Omnia LEDs driver
+
+maintainers:
+ - Marek Behún <marek.behun@nic.cz>
+
+description:
+ This module adds support for the RGB LEDs found on the front panel of the
+ Turris Omnia router. There are 12 RGB LEDs that are controlled by a
+ microcontroller that communicates via the I2C bus. Each LED is described
+ as a subnode of this I2C device.
+
+properties:
+ compatible:
+ const: cznic,turris-omnia-leds
+
+ reg:
+ description: I2C slave address of the microcontroller.
+ maxItems: 1
+
+ "#address-cells":
+ const: 1
+
+ "#size-cells":
+ const: 0
+
+patternProperties:
+ "^multi-led[0-9a-f]$":
+ type: object
+ allOf:
+ - $ref: leds-class-multicolor.yaml#
+ description:
+ This node represents one of the RGB LED devices on Turris Omnia.
+ No subnodes need to be added for subchannels since this controller only
+ supports RGB LEDs.
+
+ properties:
+ reg:
+ minimum: 0
+ maximum: 11
+ description:
+ This property identifies one of the LEDs on the front panel of the
+ Turris Omnia router.
+
+ required:
+ - reg
+
+additionalProperties: false
+
+examples:
+ - |
+
+ #include <dt-bindings/leds/common.h>
+
+ i2c0 {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ led-controller@2b {
+ compatible = "cznic,turris-omnia-leds";
+ reg = <0x2b>;
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ multi-led@0 {
+ /*
+ * No subnodes are needed, this controller only supports RGB
+ * LEDs.
+ */
+ reg = <0>;
+ color = <LED_COLOR_ID_MULTI>;
+ function = LED_FUNCTION_POWER;
+ linux,default-trigger = "heartbeat";
+ };
+
+ multi-led@a {
+ reg = <0xa>;
+ color = <LED_COLOR_ID_MULTI>;
+ function = LED_FUNCTION_INDICATOR;
+ function-enumerator = <1>;
+ };
+ };
+ };
+
+...
diff --git a/Documentation/devicetree/bindings/leds/leds-class-multicolor.yaml b/Documentation/devicetree/bindings/leds/leds-class-multicolor.yaml
new file mode 100644
index 0000000..b55e1f1
--- /dev/null
+++ b/Documentation/devicetree/bindings/leds/leds-class-multicolor.yaml
@@ -0,0 +1,37 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/leds/leds-class-multicolor.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Common properties for the multicolor LED class.
+
+maintainers:
+ - Dan Murphy <dmurphy@ti.com>
+
+description: |
+ Bindings for multi color LEDs show how to describe current outputs of
+ either integrated multi-color LED elements (like RGB, RGBW, RGBWA-UV
+ etc.) or standalone LEDs, to achieve logically grouped multi-color LED
+ modules. This is achieved by adding multi-led nodes layer to the
+ monochrome LED bindings.
+ The nodes and properties defined in this document are unique to the multicolor
+ LED class. Common LED nodes and properties are inherited from the common.txt
+ within this documentation directory.
+
+patternProperties:
+ "^multi-led@([0-9a-f])$":
+ type: object
+ description: Represents the LEDs that are to be grouped.
+ properties:
+ color:
+ const: 8 # LED_COLOR_ID_MULTI
+ description: |
+ For multicolor LED support this property should be defined as
+ LED_COLOR_ID_MULTI which can be found in include/linux/leds/common.h.
+
+ $ref: "common.yaml#"
+
+ required:
+ - color
+...
diff --git a/Documentation/devicetree/bindings/leds/leds-lm3532.txt b/Documentation/devicetree/bindings/leds/leds-lm3532.txt
index 5379321..097490a 100644
--- a/Documentation/devicetree/bindings/leds/leds-lm3532.txt
+++ b/Documentation/devicetree/bindings/leds/leds-lm3532.txt
@@ -102,4 +102,4 @@
};
For more product information please see the links below:
-http://www.ti.com/product/LM3532
+https://www.ti.com/product/LM3532
diff --git a/Documentation/devicetree/bindings/leds/leds-lm3601x.txt b/Documentation/devicetree/bindings/leds/leds-lm3601x.txt
index 095dafb..17e9400 100644
--- a/Documentation/devicetree/bindings/leds/leds-lm3601x.txt
+++ b/Documentation/devicetree/bindings/leds/leds-lm3601x.txt
@@ -47,5 +47,5 @@
}
For more product information please see the links below:
-http://www.ti.com/product/LM36010
-http://www.ti.com/product/LM36011
+https://www.ti.com/product/LM36010
+https://www.ti.com/product/LM36011
diff --git a/Documentation/devicetree/bindings/leds/leds-lm36274.txt b/Documentation/devicetree/bindings/leds/leds-lm36274.txt
index 39c230d..de6f493 100644
--- a/Documentation/devicetree/bindings/leds/leds-lm36274.txt
+++ b/Documentation/devicetree/bindings/leds/leds-lm36274.txt
@@ -82,4 +82,4 @@
};
For more product information please see the link below:
-http://www.ti.com/lit/ds/symlink/lm36274.pdf
+https://www.ti.com/lit/ds/symlink/lm36274.pdf
diff --git a/Documentation/devicetree/bindings/leds/leds-lm3692x.txt b/Documentation/devicetree/bindings/leds/leds-lm3692x.txt
index 501468a..b1103d9 100644
--- a/Documentation/devicetree/bindings/leds/leds-lm3692x.txt
+++ b/Documentation/devicetree/bindings/leds/leds-lm3692x.txt
@@ -62,4 +62,4 @@
}
For more product information please see the link below:
-http://www.ti.com/lit/ds/snvsa29/snvsa29.pdf
+https://www.ti.com/lit/ds/snvsa29/snvsa29.pdf
diff --git a/Documentation/devicetree/bindings/leds/leds-lm3697.txt b/Documentation/devicetree/bindings/leds/leds-lm3697.txt
index 63992d7..221b37b 100644
--- a/Documentation/devicetree/bindings/leds/leds-lm3697.txt
+++ b/Documentation/devicetree/bindings/leds/leds-lm3697.txt
@@ -70,4 +70,4 @@
}
For more product information please see the link below:
-http://www.ti.com/lit/ds/symlink/lm3697.pdf
+https://www.ti.com/lit/ds/symlink/lm3697.pdf
diff --git a/Documentation/devicetree/bindings/leds/leds-lp55xx.txt b/Documentation/devicetree/bindings/leds/leds-lp55xx.txt
deleted file mode 100644
index 1b66a41..0000000
--- a/Documentation/devicetree/bindings/leds/leds-lp55xx.txt
+++ /dev/null
@@ -1,228 +0,0 @@
-Binding for TI/National Semiconductor LP55xx Led Drivers
-
-Required properties:
-- compatible: one of
- national,lp5521
- national,lp5523
- ti,lp55231
- ti,lp5562
- ti,lp8501
-
-- reg: I2C slave address
-- clock-mode: Input clock mode, (0: automode, 1: internal, 2: external)
-
-Each child has own specific current settings
-- led-cur: Current setting at each led channel (mA x10, 0 if led is not connected)
-- max-cur: Maximun current at each led channel.
-
-Optional properties:
-- enable-gpio: GPIO attached to the chip's enable pin
-- label: Used for naming LEDs
-- pwr-sel: LP8501 specific property. Power selection for output channels.
- 0: D1~9 are connected to VDD
- 1: D1~6 with VDD, D7~9 with VOUT
- 2: D1~6 with VOUT, D7~9 with VDD
- 3: D1~9 are connected to VOUT
-
-Alternatively, each child can have a specific channel name and trigger:
-- chan-name (optional): name of channel
-- linux,default-trigger (optional): see
- Documentation/devicetree/bindings/leds/common.txt
-
-example 1) LP5521
-3 LED channels, external clock used. Channel names are 'lp5521_pri:channel0',
-'lp5521_pri:channel1' and 'lp5521_pri:channel2', with a heartbeat trigger
-on channel 0.
-
-lp5521@32 {
- compatible = "national,lp5521";
- reg = <0x32>;
- label = "lp5521_pri";
- clock-mode = /bits/ 8 <2>;
-
- chan0 {
- led-cur = /bits/ 8 <0x2f>;
- max-cur = /bits/ 8 <0x5f>;
- linux,default-trigger = "heartbeat";
- };
-
- chan1 {
- led-cur = /bits/ 8 <0x2f>;
- max-cur = /bits/ 8 <0x5f>;
- };
-
- chan2 {
- led-cur = /bits/ 8 <0x2f>;
- max-cur = /bits/ 8 <0x5f>;
- };
-};
-
-example 2) LP5523
-9 LED channels with specific name. Internal clock used.
-The I2C slave address is configurable with ASEL1 and ASEL0 pins.
-Available addresses are 32/33/34/35h.
-
-ASEL1 ASEL0 Address
--------------------------
- GND GND 32h
- GND VEN 33h
- VEN GND 34h
- VEN VEN 35h
-
-lp5523@32 {
- compatible = "national,lp5523";
- reg = <0x32>;
- clock-mode = /bits/ 8 <1>;
-
- chan0 {
- chan-name = "d1";
- led-cur = /bits/ 8 <0x14>;
- max-cur = /bits/ 8 <0x20>;
- };
-
- chan1 {
- chan-name = "d2";
- led-cur = /bits/ 8 <0x14>;
- max-cur = /bits/ 8 <0x20>;
- };
-
- chan2 {
- chan-name = "d3";
- led-cur = /bits/ 8 <0x14>;
- max-cur = /bits/ 8 <0x20>;
- };
-
- chan3 {
- chan-name = "d4";
- led-cur = /bits/ 8 <0x14>;
- max-cur = /bits/ 8 <0x20>;
- };
-
- chan4 {
- chan-name = "d5";
- led-cur = /bits/ 8 <0x14>;
- max-cur = /bits/ 8 <0x20>;
- };
-
- chan5 {
- chan-name = "d6";
- led-cur = /bits/ 8 <0x14>;
- max-cur = /bits/ 8 <0x20>;
- };
-
- chan6 {
- chan-name = "d7";
- led-cur = /bits/ 8 <0x14>;
- max-cur = /bits/ 8 <0x20>;
- };
-
- chan7 {
- chan-name = "d8";
- led-cur = /bits/ 8 <0x14>;
- max-cur = /bits/ 8 <0x20>;
- };
-
- chan8 {
- chan-name = "d9";
- led-cur = /bits/ 8 <0x14>;
- max-cur = /bits/ 8 <0x20>;
- };
-};
-
-example 3) LP5562
-4 channels are defined.
-
-lp5562@30 {
- compatible = "ti,lp5562";
- reg = <0x30>;
- clock-mode = /bits/8 <2>;
-
- chan0 {
- chan-name = "R";
- led-cur = /bits/ 8 <0x20>;
- max-cur = /bits/ 8 <0x60>;
- };
-
- chan1 {
- chan-name = "G";
- led-cur = /bits/ 8 <0x20>;
- max-cur = /bits/ 8 <0x60>;
- };
-
- chan2 {
- chan-name = "B";
- led-cur = /bits/ 8 <0x20>;
- max-cur = /bits/ 8 <0x60>;
- };
-
- chan3 {
- chan-name = "W";
- led-cur = /bits/ 8 <0x20>;
- max-cur = /bits/ 8 <0x60>;
- };
-};
-
-example 4) LP8501
-9 channels are defined. The 'pwr-sel' is LP8501 specific property.
-Others are same as LP5523.
-
-lp8501@32 {
- compatible = "ti,lp8501";
- reg = <0x32>;
- clock-mode = /bits/ 8 <2>;
- pwr-sel = /bits/ 8 <3>; /* D1~9 connected to VOUT */
-
- chan0 {
- chan-name = "d1";
- led-cur = /bits/ 8 <0x14>;
- max-cur = /bits/ 8 <0x20>;
- };
-
- chan1 {
- chan-name = "d2";
- led-cur = /bits/ 8 <0x14>;
- max-cur = /bits/ 8 <0x20>;
- };
-
- chan2 {
- chan-name = "d3";
- led-cur = /bits/ 8 <0x14>;
- max-cur = /bits/ 8 <0x20>;
- };
-
- chan3 {
- chan-name = "d4";
- led-cur = /bits/ 8 <0x14>;
- max-cur = /bits/ 8 <0x20>;
- };
-
- chan4 {
- chan-name = "d5";
- led-cur = /bits/ 8 <0x14>;
- max-cur = /bits/ 8 <0x20>;
- };
-
- chan5 {
- chan-name = "d6";
- led-cur = /bits/ 8 <0x14>;
- max-cur = /bits/ 8 <0x20>;
- };
-
- chan6 {
- chan-name = "d7";
- led-cur = /bits/ 8 <0x14>;
- max-cur = /bits/ 8 <0x20>;
- };
-
- chan7 {
- chan-name = "d8";
- led-cur = /bits/ 8 <0x14>;
- max-cur = /bits/ 8 <0x20>;
- };
-
- chan8 {
- chan-name = "d9";
- led-cur = /bits/ 8 <0x14>;
- max-cur = /bits/ 8 <0x20>;
- };
-};
diff --git a/Documentation/devicetree/bindings/leds/leds-lp55xx.yaml b/Documentation/devicetree/bindings/leds/leds-lp55xx.yaml
new file mode 100644
index 0000000..b1bb3fe
--- /dev/null
+++ b/Documentation/devicetree/bindings/leds/leds-lp55xx.yaml
@@ -0,0 +1,220 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/leds/leds-lp55xx.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: TI/National Semiconductor LP55xx and LP8501 LED Drivers
+
+maintainers:
+ - Jacek Anaszewski <jacek.anaszewski@gmail.com>
+ - Pavel Machek <pavel@ucw.cz>
+
+description: |
+ Bindings for the TI/National Semiconductor LP55xx and LP8501 multi channel
+ LED Drivers.
+
+ For more product information please see the link below:
+ https://www.ti.com/lit/gpn/lp5521
+ https://www.ti.com/lit/gpn/lp5523
+ https://www.ti.com/lit/gpn/lp55231
+ https://www.ti.com/lit/gpn/lp5562
+ https://www.ti.com/lit/gpn/lp8501
+
+properties:
+ compatible:
+ enum:
+ - national,lp5521
+ - national,lp5523
+ - ti,lp55231
+ - ti,lp5562
+ - ti,lp8501
+
+ reg:
+ maxItems: 1
+ description: I2C slave address
+
+ clock-mode:
+ $ref: /schemas/types.yaml#definitions/uint8
+ description: |
+ Input clock mode
+ enum:
+ - 0 # automode
+ - 1 # internal
+ - 2 # external
+
+ enable-gpio:
+ maxItems: 1
+ description: |
+ GPIO attached to the chip's enable pin
+
+ pwr-sel:
+ $ref: /schemas/types.yaml#definitions/uint8
+ description: |
+ LP8501 specific property. Power selection for output channels.
+ enum:
+ - 0 # D1~9 are connected to VDD
+ - 1 # D1~6 with VDD, D7~9 with VOUT
+ - 2 # D1~6 with VOUT, D7~9 with VDD
+ - 3 # D1~9 are connected to VOUT
+
+patternProperties:
+ "(^led@[0-9a-f]$|led)":
+ type: object
+ $ref: common.yaml#
+ properties:
+ led-cur:
+ $ref: /schemas/types.yaml#definitions/uint8
+ description: |
+ Current setting at each LED channel (mA x10, 0 if LED is not connected)
+ minimum: 0
+ maximum: 255
+
+ max-cur:
+ $ref: /schemas/types.yaml#definitions/uint8
+ description: Maximun current at each LED channel.
+
+ reg:
+ description: |
+ Output channel for the LED. This is zero based channel identifier and
+ the data sheet is a one based channel identifier.
+ reg value to output to LED output number
+ enum:
+ - 0 # LED output D1
+ - 1 # LED output D2
+ - 2 # LED output D3
+ - 3 # LED output D4
+ - 4 # LED output D5
+ - 5 # LED output D6
+ - 6 # LED output D7
+ - 7 # LED output D8
+ - 8 # LED output D9
+
+ chan-name:
+ $ref: /schemas/types.yaml#definitions/string
+ description: name of channel
+
+required:
+ - compatible
+ - reg
+
+examples:
+ - |
+ #include <dt-bindings/leds/common.h>
+
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ led-controller@32 {
+ #address-cells = <1>;
+ #size-cells = <0>;
+ compatible = "ti,lp8501";
+ reg = <0x32>;
+ clock-mode = /bits/ 8 <2>;
+ pwr-sel = /bits/ 8 <3>; /* D1~9 connected to VOUT */
+
+ led@0 {
+ reg = <0>;
+ chan-name = "d1";
+ led-cur = /bits/ 8 <0x14>;
+ max-cur = /bits/ 8 <0x20>;
+ };
+
+ led@1 {
+ reg = <1>;
+ chan-name = "d2";
+ led-cur = /bits/ 8 <0x14>;
+ max-cur = /bits/ 8 <0x20>;
+ };
+
+ led@2 {
+ reg = <2>;
+ chan-name = "d3";
+ led-cur = /bits/ 8 <0x14>;
+ max-cur = /bits/ 8 <0x20>;
+ };
+
+ led@3 {
+ reg = <3>;
+ chan-name = "d4";
+ led-cur = /bits/ 8 <0x14>;
+ max-cur = /bits/ 8 <0x20>;
+ };
+
+ led@4 {
+ reg = <4>;
+ chan-name = "d5";
+ led-cur = /bits/ 8 <0x14>;
+ max-cur = /bits/ 8 <0x20>;
+ };
+
+ led@5 {
+ reg = <5>;
+ chan-name = "d6";
+ led-cur = /bits/ 8 <0x14>;
+ max-cur = /bits/ 8 <0x20>;
+ };
+
+ led@6 {
+ reg = <6>;
+ chan-name = "d7";
+ led-cur = /bits/ 8 <0x14>;
+ max-cur = /bits/ 8 <0x20>;
+ };
+
+ led@7 {
+ reg = <7>;
+ chan-name = "d8";
+ led-cur = /bits/ 8 <0x14>;
+ max-cur = /bits/ 8 <0x20>;
+ };
+
+ led@8 {
+ reg = <8>;
+ chan-name = "d9";
+ led-cur = /bits/ 8 <0x14>;
+ max-cur = /bits/ 8 <0x20>;
+ };
+ };
+
+ led-controller@33 {
+ #address-cells = <1>;
+ #size-cells = <0>;
+ compatible = "national,lp5523";
+ reg = <0x33>;
+ clock-mode = /bits/ 8 <0>;
+
+ multi-led@2 {
+ #address-cells = <1>;
+ #size-cells = <0>;
+ reg = <0x2>;
+ color = <LED_COLOR_ID_MULTI>;
+ function = LED_FUNCTION_STANDBY;
+ linux,default-trigger = "heartbeat";
+
+ led@0 {
+ led-cur = /bits/ 8 <50>;
+ max-cur = /bits/ 8 <100>;
+ reg = <0x0>;
+ color = <LED_COLOR_ID_GREEN>;
+ };
+
+ led@1 {
+ led-cur = /bits/ 8 <50>;
+ max-cur = /bits/ 8 <100>;
+ reg = <0x1>;
+ color = <LED_COLOR_ID_BLUE>;
+ };
+
+ led@6 {
+ led-cur = /bits/ 8 <50>;
+ max-cur = /bits/ 8 <100>;
+ reg = <0x6>;
+ color = <LED_COLOR_ID_RED>;
+ };
+ };
+ };
+ };
+
+...
diff --git a/Documentation/devicetree/bindings/leds/leds-lp8860.txt b/Documentation/devicetree/bindings/leds/leds-lp8860.txt
index 9863220..8bb2574 100644
--- a/Documentation/devicetree/bindings/leds/leds-lp8860.txt
+++ b/Documentation/devicetree/bindings/leds/leds-lp8860.txt
@@ -47,4 +47,4 @@
}
For more product information please see the link below:
-http://www.ti.com/product/lp8860-q1
+https://www.ti.com/product/lp8860-q1
diff --git a/Documentation/devicetree/bindings/leds/leds-pca955x.txt b/Documentation/devicetree/bindings/leds/leds-pca955x.txt
index 7984efb..7a5830f 100644
--- a/Documentation/devicetree/bindings/leds/leds-pca955x.txt
+++ b/Documentation/devicetree/bindings/leds/leds-pca955x.txt
@@ -26,9 +26,9 @@
from 0 to 15 for the pca9552
from 0 to 3 for the pca9553
- type: (optional) either
- PCA9532_TYPE_NONE
- PCA9532_TYPE_LED
- PCA9532_TYPE_GPIO
+ PCA955X_TYPE_NONE
+ PCA955X_TYPE_LED
+ PCA955X_TYPE_GPIO
see dt-bindings/leds/leds-pca955x.h (default to LED)
- label : (optional)
see Documentation/devicetree/bindings/leds/common.txt
diff --git a/Documentation/devicetree/bindings/mailbox/mtk-gce.txt b/Documentation/devicetree/bindings/mailbox/mtk-gce.txt
index 0b5b2a6..cf48cd8 100644
--- a/Documentation/devicetree/bindings/mailbox/mtk-gce.txt
+++ b/Documentation/devicetree/bindings/mailbox/mtk-gce.txt
@@ -9,7 +9,8 @@
mailbox.txt for generic information about mailbox device-tree bindings.
Required properties:
-- compatible: can be "mediatek,mt8173-gce" or "mediatek,mt8183-gce"
+- compatible: can be "mediatek,mt8173-gce", "mediatek,mt8183-gce" or
+ "mediatek,mt6779-gce".
- reg: Address range of the GCE unit
- interrupts: The interrupt signal from the GCE block
- clock: Clocks according to the common clock binding
@@ -34,8 +35,9 @@
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'
-or 'dt-binding/gce/mt8183-gce.h'. Such as sub-system ids, thread priority, event ids.
+Some vaules of properties are defined in 'dt-bindings/gce/mt8173-gce.h',
+'dt-binding/gce/mt8183-gce.h' or 'dt-bindings/gce/mt6779-gce.h'. Such as
+sub-system ids, thread priority, event ids.
Example:
diff --git a/Documentation/devicetree/bindings/mailbox/qcom,apcs-kpss-global.yaml b/Documentation/devicetree/bindings/mailbox/qcom,apcs-kpss-global.yaml
index 12eff94..8f810fc 100644
--- a/Documentation/devicetree/bindings/mailbox/qcom,apcs-kpss-global.yaml
+++ b/Documentation/devicetree/bindings/mailbox/qcom,apcs-kpss-global.yaml
@@ -18,10 +18,12 @@
enum:
- qcom,ipq8074-apcs-apps-global
- qcom,msm8916-apcs-kpss-global
+ - qcom,msm8994-apcs-kpss-global
- qcom,msm8996-apcs-hmss-global
- qcom,msm8998-apcs-hmss-global
- qcom,qcs404-apcs-apps-global
- qcom,sc7180-apss-shared
+ - qcom,sdm660-apcs-hmss-global
- qcom,sdm845-apss-shared
- qcom,sm8150-apss-shared
diff --git a/Documentation/devicetree/bindings/mailbox/xlnx,zynqmp-ipi-mailbox.txt b/Documentation/devicetree/bindings/mailbox/xlnx,zynqmp-ipi-mailbox.txt
index 4438432..ad76edc 100644
--- a/Documentation/devicetree/bindings/mailbox/xlnx,zynqmp-ipi-mailbox.txt
+++ b/Documentation/devicetree/bindings/mailbox/xlnx,zynqmp-ipi-mailbox.txt
@@ -87,7 +87,7 @@
ranges;
/* APU<->RPU0 IPI mailbox controller */
- ipi_mailbox_rpu0: mailbox@ff90400 {
+ ipi_mailbox_rpu0: mailbox@ff990400 {
reg = <0xff990400 0x20>,
<0xff990420 0x20>,
<0xff990080 0x20>,
diff --git a/Documentation/devicetree/bindings/media/allwinner,sun4i-a10-video-engine.yaml b/Documentation/devicetree/bindings/media/allwinner,sun4i-a10-video-engine.yaml
index 526593c..4cc1a67 100644
--- a/Documentation/devicetree/bindings/media/allwinner,sun4i-a10-video-engine.yaml
+++ b/Documentation/devicetree/bindings/media/allwinner,sun4i-a10-video-engine.yaml
@@ -47,6 +47,9 @@
$ref: /schemas/types.yaml#/definitions/phandle-array
description: Phandle to the device SRAM
+ iommus:
+ maxItems: 1
+
memory-region:
description:
CMA pool to use for buffers allocation instead of the default
diff --git a/Documentation/devicetree/bindings/media/i2c/adv7180.txt b/Documentation/devicetree/bindings/media/i2c/adv7180.txt
deleted file mode 100644
index 552b6a8..0000000
--- a/Documentation/devicetree/bindings/media/i2c/adv7180.txt
+++ /dev/null
@@ -1,49 +0,0 @@
-* Analog Devices ADV7180 analog video decoder family
-
-The adv7180 family devices are used to capture analog video to different
-digital interfaces like MIPI CSI-2 or parallel video.
-
-Required Properties :
-- compatible : value must be one of
- "adi,adv7180"
- "adi,adv7180cp"
- "adi,adv7180st"
- "adi,adv7182"
- "adi,adv7280"
- "adi,adv7280-m"
- "adi,adv7281"
- "adi,adv7281-m"
- "adi,adv7281-ma"
- "adi,adv7282"
- "adi,adv7282-m"
-
-Device nodes of "adi,adv7180cp" and "adi,adv7180st" must contain one
-'port' child node per device input and output port, in accordance with the
-video interface bindings defined in
-Documentation/devicetree/bindings/media/video-interfaces.txt. The port
-nodes are numbered as follows.
-
- Port adv7180cp adv7180st
--------------------------------------------------------------------
- Input 0-2 0-5
- Output 3 6
-
-The digital output port node must contain at least one endpoint.
-
-Optional Properties :
-- powerdown-gpios: reference to the GPIO connected to the powerdown pin,
- if any.
-
-
-Example:
-
- i2c0@1c22000 {
- ...
- ...
- adv7180@21 {
- compatible = "adi,adv7180";
- reg = <0x21>;
- };
- ...
- };
-
diff --git a/Documentation/devicetree/bindings/media/i2c/adv7180.yaml b/Documentation/devicetree/bindings/media/i2c/adv7180.yaml
new file mode 100644
index 0000000..e0084b2
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/i2c/adv7180.yaml
@@ -0,0 +1,184 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/media/i2c/adv7180.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Analog Devices ADV7180 analog video decoder family
+
+maintainers:
+ - Lars-Peter Clausen <lars@metafoo.de>
+
+description:
+ The adv7180 family devices are used to capture analog video to different
+ digital interfaces like MIPI CSI-2 or parallel video.
+
+properties:
+ compatible:
+ items:
+ - enum:
+ - adi,adv7180
+ - adi,adv7180cp
+ - adi,adv7180st
+ - adi,adv7182
+ - adi,adv7280
+ - adi,adv7280-m
+ - adi,adv7281
+ - adi,adv7281-m
+ - adi,adv7281-ma
+ - adi,adv7282
+ - adi,adv7282-m
+
+ reg:
+ maxItems: 1
+
+ powerdown-gpios:
+ maxItems: 1
+
+ port:
+ type: object
+ description:
+ A node containing a single endpoint as doucmented in
+ Documentation/devicetree/bindings/media/video-interfaces.txt
+
+ ports:
+ type: object
+ description:
+ A node containing input and output port nodes with endpoint definitions
+ as documented in
+ Documentation/devicetree/bindings/media/video-interfaces.txt
+
+additionalProperties: false
+
+required:
+ - compatible
+ - reg
+
+allOf:
+ - if:
+ properties:
+ compatible:
+ items:
+ - enum:
+ - adi,adv7180
+ - adi,adv7182
+ - adi,adv7280
+ - adi,adv7280-m
+ - adi,adv7281
+ - adi,adv7281-m
+ - adi,adv7281-ma
+ - adi,adv7282
+ - adi,adv7282-m
+ then:
+ required:
+ - port
+
+ - if:
+ properties:
+ compatible:
+ contains:
+ const: adi,adv7180cp
+ then:
+ properties:
+ ports:
+ properties:
+ '#address-cells':
+ const: 1
+ '#size-cells':
+ const: 0
+ port@3:
+ type: object
+ description: Output port
+
+ patternProperties:
+ "^port@[0-2]$":
+ type: object
+ description: Input port
+
+ required:
+ - port@3
+
+ additionalProperties: false
+
+ required:
+ - ports
+
+ - if:
+ properties:
+ compatible:
+ contains:
+ const: adi,adv7180st
+ then:
+ properties:
+ ports:
+ properties:
+ '#address-cells':
+ const: 1
+ '#size-cells':
+ const: 0
+ port@6:
+ type: object
+ description: Output port
+
+ patternProperties:
+ "^port@[0-5]$":
+ type: object
+ description: Input port
+
+ required:
+ - port@6
+
+ additionalProperties: false
+
+ required:
+ - ports
+
+examples:
+ - |
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ composite-in@20 {
+ compatible = "adi,adv7180";
+ reg = <0x20>;
+
+ port {
+ adv7180: endpoint {
+ bus-width = <8>;
+ remote-endpoint = <&vin1ep>;
+ };
+ };
+ };
+
+ };
+
+ - |
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ composite-in@20 {
+ compatible = "adi,adv7180cp";
+ reg = <0x20>;
+
+ ports {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ port@0 {
+ reg = <0>;
+ adv7180_in: endpoint {
+ remote-endpoint = <&composite_con_in>;
+ };
+ };
+
+ port@3 {
+ reg = <3>;
+ adv7180_out: endpoint {
+ remote-endpoint = <&vin4_in>;
+ };
+ };
+ };
+ };
+ };
diff --git a/Documentation/devicetree/bindings/media/i2c/chrontel,ch7322.yaml b/Documentation/devicetree/bindings/media/i2c/chrontel,ch7322.yaml
new file mode 100644
index 0000000..daa2869
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/i2c/chrontel,ch7322.yaml
@@ -0,0 +1,67 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: "http://devicetree.org/schemas/media/i2c/chrontel,ch7322.yaml#"
+$schema: "http://devicetree.org/meta-schemas/core.yaml#"
+
+title: Chrontel HDMI-CEC Controller
+
+maintainers:
+ - Jeff Chase <jnchase@google.com>
+
+description:
+ The Chrontel CH7322 is a discrete HDMI-CEC controller. It is
+ programmable through I2C and drives a single CEC line.
+
+properties:
+ compatible:
+ const: chrontel,ch7322
+
+ reg:
+ description: I2C device address
+ maxItems: 1
+
+ clocks:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+ reset-gpios:
+ description:
+ Reference to the GPIO connected to the RESET pin, if any. This
+ pin is active-low.
+ maxItems: 1
+
+ standby-gpios:
+ description:
+ Reference to the GPIO connected to the OE pin, if any. When low
+ the device will respond to power status requests with "standby"
+ if in auto mode.
+ maxItems: 1
+
+ # see ../cec.txt
+ hdmi-phandle:
+ description: phandle to the HDMI controller
+
+required:
+ - compatible
+ - reg
+ - interrupts
+
+examples:
+ - |
+ #include <dt-bindings/gpio/gpio.h>
+ #include <dt-bindings/interrupt-controller/irq.h>
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+ ch7322@75 {
+ compatible = "chrontel,ch7322";
+ reg = <0x75>;
+ interrupts = <47 IRQ_TYPE_EDGE_RISING>;
+ standby-gpios = <&gpio 16 GPIO_ACTIVE_LOW>;
+ reset-gpios = <&gpio 15 GPIO_ACTIVE_LOW>;
+ hdmi-phandle = <&hdmi>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/media/i2c/dongwoon,dw9768.yaml b/Documentation/devicetree/bindings/media/i2c/dongwoon,dw9768.yaml
new file mode 100644
index 0000000..cb96e95
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/i2c/dongwoon,dw9768.yaml
@@ -0,0 +1,100 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+# Copyright (c) 2020 MediaTek Inc.
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/media/i2c/dongwoon,dw9768.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Dongwoon Anatech DW9768 Voice Coil Motor (VCM) Lens Device Tree Bindings
+
+maintainers:
+ - Dongchun Zhu <dongchun.zhu@mediatek.com>
+
+description: |-
+ The Dongwoon DW9768 is a single 10-bit digital-to-analog (DAC) converter
+ with 100 mA output current sink capability. VCM current is controlled with
+ a linear mode driver. The DAC is controlled via a 2-wire (I2C-compatible)
+ serial interface that operates at clock rates up to 1MHz. This chip
+ integrates Advanced Actuator Control (AAC) technology and is intended for
+ driving voice coil lenses in camera modules.
+
+properties:
+ compatible:
+ enum:
+ - dongwoon,dw9768 # for DW9768 VCM
+ - giantec,gt9769 # for GT9769 VCM
+
+ reg:
+ maxItems: 1
+
+ vin-supply:
+ description:
+ Definition of the regulator used as Digital I/O voltage supply.
+
+ vdd-supply:
+ description:
+ Definition of the regulator used as Digital core voltage supply.
+
+ dongwoon,aac-mode:
+ description:
+ Indication of AAC mode select.
+ allOf:
+ - $ref: "/schemas/types.yaml#/definitions/uint32"
+ - enum:
+ - 1 # AAC2 mode(operation time# 0.48 x Tvib)
+ - 2 # AAC3 mode(operation time# 0.70 x Tvib)
+ - 3 # AAC4 mode(operation time# 0.75 x Tvib)
+ - 5 # AAC8 mode(operation time# 1.13 x Tvib)
+ default: 2
+
+ dongwoon,aac-timing:
+ description:
+ Number of AAC Timing count that controlled by one 6-bit period of
+ vibration register AACT[5:0], the unit of which is 100 us.
+ allOf:
+ - $ref: "/schemas/types.yaml#/definitions/uint32"
+ - default: 0x20
+ minimum: 0x00
+ maximum: 0x3f
+
+ dongwoon,clock-presc:
+ description:
+ Indication of VCM internal clock dividing rate select, as one multiple
+ factor to calculate VCM ring periodic time Tvib.
+ allOf:
+ - $ref: "/schemas/types.yaml#/definitions/uint32"
+ - enum:
+ - 0 # Dividing Rate - 2
+ - 1 # Dividing Rate - 1
+ - 2 # Dividing Rate - 1/2
+ - 3 # Dividing Rate - 1/4
+ - 4 # Dividing Rate - 8
+ - 5 # Dividing Rate - 4
+ default: 1
+
+required:
+ - compatible
+ - reg
+ - vin-supply
+ - vdd-supply
+
+additionalProperties: false
+
+examples:
+ - |
+
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ dw9768: camera-lens@c {
+ compatible = "dongwoon,dw9768";
+ reg = <0x0c>;
+
+ vin-supply = <&mt6358_vcamio_reg>;
+ vdd-supply = <&mt6358_vcama2_reg>;
+ dongwoon,aac-timing = <0x39>;
+ };
+ };
+
+...
diff --git a/Documentation/devicetree/bindings/media/i2c/imi,rdacm2x-gmsl.yaml b/Documentation/devicetree/bindings/media/i2c/imi,rdacm2x-gmsl.yaml
new file mode 100644
index 0000000..5ad4b8c
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/i2c/imi,rdacm2x-gmsl.yaml
@@ -0,0 +1,159 @@
+# SPDX-License-Identifier: GPL-2.0 OR BSD-2-Clause
+# Copyright (C) 2019 Renesas Electronics Corp.
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/media/i2c/imi,rdacm2x-gmsl.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: IMI D&D RDACM20 and RDACM21 Automotive Camera Platforms
+
+maintainers:
+ - Jacopo Mondi <jacopo+renesas@jmondi.org>
+ - Kieran Bingham <kieran.bingham+renesas@ideasonboard.com>
+ - Laurent Pinchart <laurent.pinchart+renesas@ideasonboard.com>
+ - Niklas Söderlund <niklas.soderlund+renesas@ragnatech.se>
+
+description: -|
+ The IMI D&D RDACM20 and RDACM21 are GMSL-compatible camera designed for
+ automotive applications.
+
+ The RDACM20 camera module encloses a Maxim Integrated MAX9271 GMSL serializer,
+ coupled with an OV10635 image sensor and an embedded MCU. Both the MCU and
+ the image sensor are connected to the serializer local I2C bus and are
+ accessible by the host SoC by direct addressing.
+
+ The RDACM21 camera module encloses the same serializer, coupled with an
+ OV10640 image sensor and an OV490 ISP. Only the OV490 ISP is interfaced to
+ the serializer local I2C bus while the image sensor is not accessible from
+ the host SoC.
+
+ They both connect to a remote GMSL endpoint through a coaxial cable.
+
+ IMI RDACM20
+ +---------------+ +--------------------------------+
+ | GMSL | <- Video Stream | <- Video--------\ |
+ | |< === GMSL Link ====== >|MAX9271<- I2C bus-> <-->OV10635 |
+ | de-serializer | <- I2C messages -> | \<-->MCU |
+ +---------------+ +--------------------------------+
+
+ IMI RDACM21
+ +---------------+ +--------------------------------+
+ | GMSL | <- Video Stream | <- Video--------\ |
+ | |< === GMSL Link ====== >|MAX9271<- I2C bus-> <-->OV490 |
+ | | <- I2C messages -> | | |
+ | de-serializer | | OV10640 <-------| |
+ +---------------+ +--------------------------------+
+
+ Both camera modules serialize video data generated by the embedded camera
+ sensor on the GMSL serial channel to a remote GMSL de-serializer. They also
+ receive and transmit I2C messages encapsulated and transmitted on the GMSL
+ bidirectional control channel.
+
+ All I2C traffic received on the GMSL link not directed to the serializer is
+ propagated on the local I2C bus to the remote device there connected. All the
+ I2C traffic generated on the local I2C bus not directed to the serializer is
+ propagated to the remote de-serializer encapsulated in the GMSL control
+ channel.
+
+ The RDACM20 and RDACM21 DT node should be a direct child of the GMSL
+ deserializer's I2C bus corresponding to the GMSL link that the camera is
+ attached to.
+
+properties:
+ '#address-cells':
+ const: 1
+
+ '#size-cells':
+ const: 0
+
+ compatible:
+ enum:
+ - imi,rdacm20
+ - imi,rdacm21
+
+ reg:
+ description: -|
+ I2C device addresses, the first to be assigned to the serializer, the
+ following ones to be assigned to the remote devices.
+
+ For RDACM20 the second entry of the property is assigned to the
+ OV10635 image sensor and the optional third one to the embedded MCU.
+
+ For RDACM21 the second entry is assigned to the OV490 ISP and the optional
+ third one ignored.
+
+ minItems: 2
+ maxItems: 3
+
+ port:
+ type: object
+ additionalProperties: false
+ description: -|
+ Connection to the remote GMSL endpoint are modelled using the OF graph
+ bindings in accordance with the video interface bindings defined in
+ Documentation/devicetree/bindings/media/video-interfaces.txt.
+
+ The device node contains a single "port" child node with a single
+ "endpoint" sub-device.
+
+ properties:
+ endpoint:
+ type: object
+ additionalProperties: false
+
+ properties:
+ remote-endpoint:
+ description: -|
+ phandle to the remote GMSL endpoint sub-node in the remote node
+ port.
+ maxItems: 1
+
+ required:
+ - remote-endpoint
+
+ required:
+ - endpoint
+
+required:
+ - compatible
+ - reg
+ - port
+
+examples:
+ - |
+ i2c@e66d8000 {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ reg = <0 0xe66d8000>;
+
+ camera@31 {
+ compatible = "imi,rdacm20";
+ reg = <0x31>, <0x41>, <0x51>;
+
+ port {
+ rdacm20_out0: endpoint {
+ remote-endpoint = <&max9286_in0>;
+ };
+ };
+ };
+ };
+
+ - |
+ i2c@e66d8000 {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ reg = <0 0xe66d8000>;
+
+ camera@31 {
+ compatible = "imi,rdacm21";
+ reg = <0x31>, <0x41>;
+
+ port {
+ rdacm21_out0: endpoint {
+ remote-endpoint = <&max9286_in0>;
+ };
+ };
+ };
+ };
diff --git a/Documentation/devicetree/bindings/media/i2c/imx274.txt b/Documentation/devicetree/bindings/media/i2c/imx274.txt
index 80f2e89..0727079 100644
--- a/Documentation/devicetree/bindings/media/i2c/imx274.txt
+++ b/Documentation/devicetree/bindings/media/i2c/imx274.txt
@@ -13,6 +13,11 @@
Optional Properties:
- reset-gpios: Sensor reset GPIO
+- clocks: Reference to the input clock.
+- clock-names: Should be "inck".
+- VANA-supply: Sensor 2.8v analog supply.
+- VDIG-supply: Sensor 1.8v digital core supply.
+- VDDL-supply: Sensor digital IO 1.2v supply.
The imx274 device node should contain one 'port' child node with
an 'endpoint' subnode. For further reading on port node refer to
diff --git a/Documentation/devicetree/bindings/media/i2c/maxim,max9286.yaml b/Documentation/devicetree/bindings/media/i2c/maxim,max9286.yaml
new file mode 100644
index 0000000..e7b5431
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/i2c/maxim,max9286.yaml
@@ -0,0 +1,366 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+# Copyright (C) 2019 Renesas Electronics Corp.
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/media/i2c/maxim,max9286.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Maxim Integrated Quad GMSL Deserializer
+
+maintainers:
+ - Jacopo Mondi <jacopo+renesas@jmondi.org>
+ - Kieran Bingham <kieran.bingham+renesas@ideasonboard.com>
+ - Laurent Pinchart <laurent.pinchart+renesas@ideasonboard.com>
+ - Niklas Söderlund <niklas.soderlund+renesas@ragnatech.se>
+
+description: |
+ The MAX9286 deserializer receives video data on up to 4 Gigabit Multimedia
+ Serial Links (GMSL) and outputs them on a CSI-2 D-PHY port using up to 4 data
+ lanes.
+
+ In addition to video data, the GMSL links carry a bidirectional control
+ channel that encapsulates I2C messages. The MAX9286 forwards all I2C traffic
+ not addressed to itself to the other side of the links, where a GMSL
+ serializer will output it on a local I2C bus. In the other direction all I2C
+ traffic received over GMSL by the MAX9286 is output on the local I2C bus.
+
+properties:
+ '#address-cells':
+ const: 1
+
+ '#size-cells':
+ const: 0
+
+ compatible:
+ const: maxim,max9286
+
+ reg:
+ description: I2C device address
+ maxItems: 1
+
+ poc-supply:
+ description: Regulator providing Power over Coax to the cameras
+ maxItems: 1
+
+ enable-gpios:
+ description: GPIO connected to the \#PWDN pin with inverted polarity
+ maxItems: 1
+
+ gpio-controller: true
+
+ '#gpio-cells':
+ const: 2
+
+ ports:
+ type: object
+ description: |
+ The connections to the MAX9286 GMSL and its endpoint nodes are modelled
+ using the OF graph bindings in accordance with the video interface
+ bindings defined in
+ Documentation/devicetree/bindings/media/video-interfaces.txt.
+
+ The following table lists the port number corresponding to each device
+ port.
+
+ Port Description
+ ----------------------------------------
+ Port 0 GMSL Input 0
+ Port 1 GMSL Input 1
+ Port 2 GMSL Input 2
+ Port 3 GMSL Input 3
+ Port 4 CSI-2 Output
+
+ properties:
+ '#address-cells':
+ const: 1
+
+ '#size-cells':
+ const: 0
+
+ port@[0-3]:
+ type: object
+ properties:
+ reg:
+ enum: [ 0, 1, 2, 3 ]
+
+ endpoint:
+ type: object
+
+ properties:
+ remote-endpoint:
+ description: |
+ phandle to the remote GMSL source endpoint subnode in the
+ remote node port.
+
+ required:
+ - remote-endpoint
+
+ required:
+ - reg
+ - endpoint
+
+ additionalProperties: false
+
+ port@4:
+ type: object
+ properties:
+ reg:
+ const: 4
+
+ endpoint:
+ type: object
+
+ properties:
+ remote-endpoint:
+ description: phandle to the remote CSI-2 sink endpoint.
+
+ data-lanes:
+ description: array of physical CSI-2 data lane indexes.
+
+ required:
+ - remote-endpoint
+ - data-lanes
+
+ required:
+ - reg
+ - endpoint
+
+ additionalProperties: false
+
+ required:
+ - port@4
+
+ i2c-mux:
+ type: object
+ description: |
+ Each GMSL link is modelled as a child bus of an i2c bus
+ multiplexer/switch, in accordance with bindings described in
+ Documentation/devicetree/bindings/i2c/i2c-mux.txt.
+
+ properties:
+ '#address-cells':
+ const: 1
+
+ '#size-cells':
+ const: 0
+
+ patternProperties:
+ "^i2c@[0-3]$":
+ type: object
+ description: |
+ Child node of the i2c bus multiplexer which represents a GMSL link.
+ Each serializer device on the GMSL link remote end is represented with
+ an i2c-mux child node. The MAX9286 chip supports up to 4 GMSL
+ channels.
+
+ properties:
+ '#address-cells':
+ const: 1
+
+ '#size-cells':
+ const: 0
+
+ reg:
+ description: The index of the GMSL channel.
+ maxItems: 1
+
+ patternProperties:
+ "^camera@[a-f0-9]+$":
+ type: object
+ description: |
+ The remote camera device, composed by a GMSL serializer and a
+ connected video source.
+
+ properties:
+ compatible:
+ description: The remote device compatible string.
+
+ reg:
+ minItems: 2
+ maxItems: 3
+ description: |
+ The I2C addresses to be assigned to the remote devices through
+ address reprogramming. The number of entries depends on the
+ requirements of the currently connected remote device.
+
+ port:
+ type: object
+
+ properties:
+ endpoint:
+ type: object
+
+ properties:
+ remote-endpoint:
+ description: phandle to the MAX9286 sink endpoint.
+
+ required:
+ - remote-endpoint
+
+ additionalProperties: false
+
+ required:
+ - endpoint
+
+ additionalProperties: false
+
+ required:
+ - compatible
+ - reg
+ - port
+
+ additionalProperties: false
+
+ additionalProperties: false
+
+ additionalProperties: false
+
+required:
+ - compatible
+ - reg
+ - ports
+ - i2c-mux
+ - gpio-controller
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/gpio/gpio.h>
+
+ i2c@e66d8000 {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ reg = <0 0xe66d8000>;
+
+ gmsl-deserializer@2c {
+ compatible = "maxim,max9286";
+ reg = <0x2c>;
+ poc-supply = <&camera_poc_12v>;
+ enable-gpios = <&gpio 13 GPIO_ACTIVE_HIGH>;
+
+ gpio-controller;
+ #gpio-cells = <2>;
+
+ ports {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ port@0 {
+ reg = <0>;
+
+ max9286_in0: endpoint {
+ remote-endpoint = <&rdacm20_out0>;
+ };
+ };
+
+ port@1 {
+ reg = <1>;
+
+ max9286_in1: endpoint {
+ remote-endpoint = <&rdacm20_out1>;
+ };
+ };
+
+ port@2 {
+ reg = <2>;
+
+ max9286_in2: endpoint {
+ remote-endpoint = <&rdacm20_out2>;
+ };
+ };
+
+ port@3 {
+ reg = <3>;
+
+ max9286_in3: endpoint {
+ remote-endpoint = <&rdacm20_out3>;
+ };
+ };
+
+ port@4 {
+ reg = <4>;
+
+ max9286_out: endpoint {
+ data-lanes = <1 2 3 4>;
+ remote-endpoint = <&csi40_in>;
+ };
+ };
+ };
+
+ i2c-mux {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ i2c@0 {
+ #address-cells = <1>;
+ #size-cells = <0>;
+ reg = <0>;
+
+ camera@51 {
+ compatible = "imi,rdacm20";
+ reg = <0x51>, <0x61>;
+
+ port {
+ rdacm20_out0: endpoint {
+ remote-endpoint = <&max9286_in0>;
+ };
+ };
+
+ };
+ };
+
+ i2c@1 {
+ #address-cells = <1>;
+ #size-cells = <0>;
+ reg = <1>;
+
+ camera@52 {
+ compatible = "imi,rdacm20";
+ reg = <0x52>, <0x62>;
+
+ port {
+ rdacm20_out1: endpoint {
+ remote-endpoint = <&max9286_in1>;
+ };
+ };
+ };
+ };
+
+ i2c@2 {
+ #address-cells = <1>;
+ #size-cells = <0>;
+ reg = <2>;
+
+ camera@53 {
+ compatible = "imi,rdacm20";
+ reg = <0x53>, <0x63>;
+
+ port {
+ rdacm20_out2: endpoint {
+ remote-endpoint = <&max9286_in2>;
+ };
+ };
+ };
+ };
+
+ i2c@3 {
+ #address-cells = <1>;
+ #size-cells = <0>;
+ reg = <3>;
+
+ camera@54 {
+ compatible = "imi,rdacm20";
+ reg = <0x54>, <0x64>;
+
+ port {
+ rdacm20_out3: endpoint {
+ remote-endpoint = <&max9286_in3>;
+ };
+ };
+ };
+ };
+ };
+ };
+ };
diff --git a/Documentation/devicetree/bindings/media/renesas,fcp.txt b/Documentation/devicetree/bindings/media/renesas,fcp.txt
deleted file mode 100644
index 79c3739..0000000
--- a/Documentation/devicetree/bindings/media/renesas,fcp.txt
+++ /dev/null
@@ -1,34 +0,0 @@
-Renesas R-Car Frame Compression Processor (FCP)
------------------------------------------------
-
-The FCP is a companion module of video processing modules in the Renesas R-Car
-Gen3 and RZ/G2 SoCs. It provides data compression and decompression, data
-caching, and conversion of AXI transactions in order to reduce the memory
-bandwidth.
-
-There are three types of FCP: FCP for Codec (FCPC), FCP for VSP (FCPV) and FCP
-for FDP (FCPF). Their configuration and behaviour depend on the module they
-are paired with. These DT bindings currently support the FCPV and FCPF.
-
- - compatible: Must be one or more of the following
-
- - "renesas,fcpv" for generic compatible 'FCP for VSP'
- - "renesas,fcpf" for generic compatible 'FCP for FDP'
-
- - reg: the register base and size for the device registers
- - clocks: Reference to the functional clock
-
-Optional properties:
- - power-domains : power-domain property defined with a power domain specifier
- to respective power domain.
-
-
-Device node example
--------------------
-
- fcpvd1: fcp@fea2f000 {
- compatible = "renesas,fcpv";
- reg = <0 0xfea2f000 0 0x200>;
- clocks = <&cpg CPG_MOD 602>;
- power-domains = <&sysc R8A7795_PD_A3VP>;
- };
diff --git a/Documentation/devicetree/bindings/media/renesas,fcp.yaml b/Documentation/devicetree/bindings/media/renesas,fcp.yaml
new file mode 100644
index 0000000..43f2fed
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/renesas,fcp.yaml
@@ -0,0 +1,66 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/media/renesas,fcp.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Renesas R-Car Frame Compression Processor (FCP)
+
+maintainers:
+ - Laurent Pinchart <laurent.pinchart@ideasonboard.com>
+
+description: |
+ The FCP is a companion module of video processing modules in the Renesas
+ R-Car Gen3 and RZ/G2 SoCs. It provides data compression and decompression,
+ data caching, and conversion of AXI transactions in order to reduce the
+ memory bandwidth.
+
+ There are three types of FCP: FCP for Codec (FCPC), FCP for VSP (FCPV) and
+ FCP for FDP (FCPF). Their configuration and behaviour depend on the module
+ they are paired with. These DT bindings currently support the FCPV and FCPF.
+
+properties:
+ compatible:
+ enum:
+ - renesas,fcpv # FCP for VSP
+ - renesas,fcpf # FCP for FDP
+
+ reg:
+ maxItems: 1
+
+ clocks:
+ maxItems: 1
+
+ iommus:
+ maxItems: 1
+
+ power-domains:
+ maxItems: 1
+
+ resets:
+ maxItems: 1
+
+required:
+ - compatible
+ - reg
+ - clocks
+ - power-domains
+ - resets
+
+additionalProperties: false
+
+examples:
+ # R8A7795 (R-Car H3) FCP for VSP-D1
+ - |
+ #include <dt-bindings/clock/renesas-cpg-mssr.h>
+ #include <dt-bindings/power/r8a7795-sysc.h>
+
+ fcp@fea2f000 {
+ compatible = "renesas,fcpv";
+ reg = <0xfea2f000 0x200>;
+ clocks = <&cpg CPG_MOD 602>;
+ power-domains = <&sysc R8A7795_PD_ALWAYS_ON>;
+ resets = <&cpg 602>;
+ iommus = <&ipmmu_vi0 9>;
+ };
+...
diff --git a/Documentation/devicetree/bindings/media/renesas,fdp1.txt b/Documentation/devicetree/bindings/media/renesas,fdp1.txt
deleted file mode 100644
index 8dd1007..0000000
--- a/Documentation/devicetree/bindings/media/renesas,fdp1.txt
+++ /dev/null
@@ -1,37 +0,0 @@
-Renesas R-Car Fine Display Processor (FDP1)
--------------------------------------------
-
-The FDP1 is a de-interlacing module which converts interlaced video to
-progressive video. It is capable of performing pixel format conversion between
-YCbCr/YUV formats and RGB formats. Only YCbCr/YUV formats are supported as
-an input to the module.
-
-Required properties:
-
- - compatible: must be "renesas,fdp1"
- - reg: the register base and size for the device registers
- - interrupts : interrupt specifier for the FDP1 instance
- - clocks: reference to the functional clock
-
-Optional properties:
-
- - power-domains: reference to the power domain that the FDP1 belongs to, if
- any.
- - renesas,fcp: a phandle referencing the FCP that handles memory accesses
- for the FDP1. Not needed on Gen2, mandatory on Gen3.
-
-Please refer to the binding documentation for the clock and/or power domain
-providers for more details.
-
-
-Device node example
--------------------
-
- fdp1@fe940000 {
- compatible = "renesas,fdp1";
- reg = <0 0xfe940000 0 0x2400>;
- interrupts = <GIC_SPI 262 IRQ_TYPE_LEVEL_HIGH>;
- clocks = <&cpg CPG_MOD 119>;
- power-domains = <&sysc R8A7795_PD_A3VP>;
- renesas,fcp = <&fcpf0>;
- };
diff --git a/Documentation/devicetree/bindings/media/renesas,fdp1.yaml b/Documentation/devicetree/bindings/media/renesas,fdp1.yaml
new file mode 100644
index 0000000..2a27a72
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/renesas,fdp1.yaml
@@ -0,0 +1,69 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/media/renesas,fdp1.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Renesas R-Car Fine Display Processor (FDP1)
+
+maintainers:
+ - Laurent Pinchart <laurent.pinchart@ideasonboard.com>
+
+description:
+ The FDP1 is a de-interlacing module which converts interlaced video to
+ progressive video. It is capable of performing pixel format conversion
+ between YCbCr/YUV formats and RGB formats. Only YCbCr/YUV formats are
+ supported as an input to the module.
+
+properties:
+ compatible:
+ enum:
+ - renesas,fdp1
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+ clocks:
+ maxItems: 1
+
+ power-domains:
+ maxItems: 1
+
+ resets:
+ maxItems: 1
+
+ renesas,fcp:
+ $ref: /schemas/types.yaml#/definitions/phandle
+ description:
+ A phandle referencing the FCP that handles memory accesses for the FDP1.
+ Not allowed on R-Car Gen2, mandatory on R-Car Gen3.
+
+required:
+ - compatible
+ - reg
+ - interrupts
+ - clocks
+ - power-domains
+ - resets
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/clock/renesas-cpg-mssr.h>
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+ #include <dt-bindings/power/r8a7795-sysc.h>
+
+ fdp1@fe940000 {
+ compatible = "renesas,fdp1";
+ reg = <0xfe940000 0x2400>;
+ interrupts = <GIC_SPI 262 IRQ_TYPE_LEVEL_HIGH>;
+ clocks = <&cpg CPG_MOD 119>;
+ power-domains = <&sysc R8A7795_PD_A3VP>;
+ resets = <&cpg 119>;
+ renesas,fcp = <&fcpf0>;
+ };
+...
diff --git a/Documentation/devicetree/bindings/media/renesas,vsp1.txt b/Documentation/devicetree/bindings/media/renesas,vsp1.txt
deleted file mode 100644
index cd5a955..0000000
--- a/Documentation/devicetree/bindings/media/renesas,vsp1.txt
+++ /dev/null
@@ -1,30 +0,0 @@
-* Renesas VSP Video Processing Engine
-
-The VSP is a video processing engine that supports up-/down-scaling, alpha
-blending, color space conversion and various other image processing features.
-It can be found in the Renesas R-Car Gen2, R-Car Gen3, RZ/G1, and RZ/G2 SoCs.
-
-Required properties:
-
- - compatible: Must contain one of the following values
- - "renesas,vsp1" for the R-Car Gen2 and RZ/G1 VSP1
- - "renesas,vsp2" for the R-Car Gen3 and RZ/G2 VSP2
-
- - reg: Base address and length of the registers block for the VSP.
- - interrupts: VSP interrupt specifier.
- - clocks: A phandle + clock-specifier pair for the VSP functional clock.
-
-Optional properties:
-
- - renesas,fcp: A phandle referencing the FCP that handles memory accesses
- for the VSP. Not needed on Gen2, mandatory on Gen3.
-
-
-Example: R8A7790 (R-Car H2) VSP1-S node
-
- vsp@fe928000 {
- compatible = "renesas,vsp1";
- reg = <0 0xfe928000 0 0x8000>;
- interrupts = <0 267 IRQ_TYPE_LEVEL_HIGH>;
- clocks = <&mstp1_clks R8A7790_CLK_VSP1_S>;
- };
diff --git a/Documentation/devicetree/bindings/media/renesas,vsp1.yaml b/Documentation/devicetree/bindings/media/renesas,vsp1.yaml
new file mode 100644
index 0000000..990e9c1
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/renesas,vsp1.yaml
@@ -0,0 +1,97 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/media/renesas,vsp1.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Renesas VSP Video Processing Engine
+
+maintainers:
+ - Laurent Pinchart <laurent.pinchart@ideasonboard.com>
+
+description:
+ The VSP is a video processing engine that supports up-/down-scaling, alpha
+ blending, color space conversion and various other image processing features.
+ It can be found in the Renesas R-Car Gen2, R-Car Gen3, RZ/G1, and RZ/G2 SoCs.
+
+properties:
+ compatible:
+ enum:
+ - renesas,vsp1 # R-Car Gen2 and RZ/G1
+ - renesas,vsp2 # R-Car Gen3 and RZ/G2
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+ clocks:
+ maxItems: 1
+
+ power-domains:
+ maxItems: 1
+
+ resets:
+ maxItems: 1
+
+ renesas,fcp:
+ $ref: /schemas/types.yaml#/definitions/phandle
+ description:
+ A phandle referencing the FCP that handles memory accesses for the VSP.
+
+required:
+ - compatible
+ - reg
+ - interrupts
+ - clocks
+ - power-domains
+ - resets
+
+additionalProperties: false
+
+if:
+ properties:
+ compatible:
+ items:
+ - const: renesas,vsp1
+then:
+ properties:
+ renesas,fcp: false
+else:
+ required:
+ - renesas,fcp
+
+examples:
+ # R8A7790 (R-Car H2) VSP1-S
+ - |
+ #include <dt-bindings/clock/renesas-cpg-mssr.h>
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+ #include <dt-bindings/power/r8a7790-sysc.h>
+
+ vsp@fe928000 {
+ compatible = "renesas,vsp1";
+ reg = <0xfe928000 0x8000>;
+ interrupts = <GIC_SPI 267 IRQ_TYPE_LEVEL_HIGH>;
+ clocks = <&cpg CPG_MOD 131>;
+ power-domains = <&sysc R8A7790_PD_ALWAYS_ON>;
+ resets = <&cpg 131>;
+ };
+
+ # R8A77951 (R-Car H3) VSP2-BC
+ - |
+ #include <dt-bindings/clock/renesas-cpg-mssr.h>
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+ #include <dt-bindings/power/r8a7795-sysc.h>
+
+ vsp@fe920000 {
+ compatible = "renesas,vsp2";
+ reg = <0xfe920000 0x8000>;
+ interrupts = <GIC_SPI 465 IRQ_TYPE_LEVEL_HIGH>;
+ clocks = <&cpg CPG_MOD 624>;
+ power-domains = <&sysc R8A7795_PD_A3VP>;
+ resets = <&cpg 624>;
+
+ renesas,fcp = <&fcpvb1>;
+ };
+...
diff --git a/Documentation/devicetree/bindings/media/xilinx/video.txt b/Documentation/devicetree/bindings/media/xilinx/video.txt
index 68ac210..d0335ca 100644
--- a/Documentation/devicetree/bindings/media/xilinx/video.txt
+++ b/Documentation/devicetree/bindings/media/xilinx/video.txt
@@ -32,4 +32,4 @@
defaults to "mono".
-[UG934] http://www.xilinx.com/support/documentation/ip_documentation/axi_videoip/v1_0/ug934_axi_videoIP.pdf
+[UG934] https://www.xilinx.com/support/documentation/ip_documentation/axi_videoip/v1_0/ug934_axi_videoIP.pdf
diff --git a/Documentation/devicetree/bindings/media/xilinx/xlnx,csi2rxss.yaml b/Documentation/devicetree/bindings/media/xilinx/xlnx,csi2rxss.yaml
new file mode 100644
index 0000000..7b9407c
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/xilinx/xlnx,csi2rxss.yaml
@@ -0,0 +1,237 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/media/xilinx/xlnx,csi2rxss.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Xilinx MIPI CSI-2 Receiver Subsystem
+
+maintainers:
+ - Vishal Sagar <vishal.sagar@xilinx.com>
+
+description: |
+ The Xilinx MIPI CSI-2 Receiver Subsystem is used to capture MIPI CSI-2
+ traffic from compliant camera sensors and send the output as AXI4 Stream
+ video data for image processing.
+ The subsystem consists of a MIPI D-PHY in slave mode which captures the
+ data packets. This is passed along the MIPI CSI-2 Rx IP which extracts the
+ packet data. The optional Video Format Bridge (VFB) converts this data to
+ AXI4 Stream video data.
+ For more details, please refer to PG232 Xilinx MIPI CSI-2 Receiver Subsystem.
+ Please note that this bindings includes only the MIPI CSI-2 Rx controller
+ and Video Format Bridge and not D-PHY.
+
+properties:
+ compatible:
+ items:
+ - enum:
+ - xlnx,mipi-csi2-rx-subsystem-5.0
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+ clocks:
+ description: List of clock specifiers
+ items:
+ - description: AXI Lite clock
+ - description: Video clock
+
+ clock-names:
+ items:
+ - const: lite_aclk
+ - const: video_aclk
+
+ xlnx,csi-pxl-format:
+ description: |
+ This denotes the CSI Data type selected in hw design.
+ Packets other than this data type (except for RAW8 and
+ User defined data types) will be filtered out.
+ Possible values are as below -
+ 0x1e - YUV4228B
+ 0x1f - YUV42210B
+ 0x20 - RGB444
+ 0x21 - RGB555
+ 0x22 - RGB565
+ 0x23 - RGB666
+ 0x24 - RGB888
+ 0x28 - RAW6
+ 0x29 - RAW7
+ 0x2a - RAW8
+ 0x2b - RAW10
+ 0x2c - RAW12
+ 0x2d - RAW14
+ 0x2e - RAW16
+ 0x2f - RAW20
+ allOf:
+ - $ref: /schemas/types.yaml#/definitions/uint32
+ - anyOf:
+ - minimum: 0x1e
+ - maximum: 0x24
+ - minimum: 0x28
+ - maximum: 0x2f
+
+ xlnx,vfb:
+ type: boolean
+ description: Present when Video Format Bridge is enabled in IP configuration
+
+ xlnx,en-csi-v2-0:
+ type: boolean
+ description: Present if CSI v2 is enabled in IP configuration.
+
+ xlnx,en-vcx:
+ type: boolean
+ description: |
+ When present, there are maximum 16 virtual channels, else only 4.
+
+ xlnx,en-active-lanes:
+ type: boolean
+ description: |
+ Present if the number of active lanes can be re-configured at
+ runtime in the Protocol Configuration Register. Otherwise all lanes,
+ as set in IP configuration, are always active.
+
+ video-reset-gpios:
+ description: Optional specifier for a GPIO that asserts video_aresetn.
+ maxItems: 1
+
+ ports:
+ type: object
+
+ properties:
+ port@0:
+ type: object
+ description: |
+ Input / sink port node, single endpoint describing the
+ CSI-2 transmitter.
+
+ properties:
+ reg:
+ const: 0
+
+ endpoint:
+ type: object
+
+ properties:
+
+ data-lanes:
+ description: |
+ This is required only in the sink port 0 endpoint which
+ connects to MIPI CSI-2 source like sensor.
+ The possible values are -
+ 1 - For 1 lane enabled in IP.
+ 1 2 - For 2 lanes enabled in IP.
+ 1 2 3 - For 3 lanes enabled in IP.
+ 1 2 3 4 - For 4 lanes enabled in IP.
+ items:
+ - const: 1
+ - const: 2
+ - const: 3
+ - const: 4
+
+ remote-endpoint: true
+
+ required:
+ - data-lanes
+ - remote-endpoint
+
+ additionalProperties: false
+
+ additionalProperties: false
+
+ port@1:
+ type: object
+ description: |
+ Output / source port node, endpoint describing modules
+ connected the CSI-2 receiver.
+
+ properties:
+
+ reg:
+ const: 1
+
+ endpoint:
+ type: object
+
+ properties:
+
+ remote-endpoint: true
+
+ required:
+ - remote-endpoint
+
+ additionalProperties: false
+
+ additionalProperties: false
+
+required:
+ - compatible
+ - reg
+ - interrupts
+ - clocks
+ - clock-names
+ - ports
+
+allOf:
+ - if:
+ required:
+ - xlnx,vfb
+ then:
+ required:
+ - xlnx,csi-pxl-format
+ else:
+ properties:
+ xlnx,csi-pxl-format: false
+
+ - if:
+ not:
+ required:
+ - xlnx,en-csi-v2-0
+ then:
+ properties:
+ xlnx,en-vcx: false
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/gpio/gpio.h>
+ xcsi2rxss_1: csi2rx@a0020000 {
+ compatible = "xlnx,mipi-csi2-rx-subsystem-5.0";
+ reg = <0xa0020000 0x10000>;
+ interrupt-parent = <&gic>;
+ interrupts = <0 95 4>;
+ xlnx,csi-pxl-format = <0x2a>;
+ xlnx,vfb;
+ xlnx,en-active-lanes;
+ xlnx,en-csi-v2-0;
+ xlnx,en-vcx;
+ clock-names = "lite_aclk", "video_aclk";
+ clocks = <&misc_clk_0>, <&misc_clk_1>;
+ video-reset-gpios = <&gpio 86 GPIO_ACTIVE_LOW>;
+
+ ports {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ port@0 {
+ /* Sink port */
+ reg = <0>;
+ csiss_in: endpoint {
+ data-lanes = <1 2 3 4>;
+ /* MIPI CSI-2 Camera handle */
+ remote-endpoint = <&camera_out>;
+ };
+ };
+ port@1 {
+ /* Source port */
+ reg = <1>;
+ csiss_out: endpoint {
+ remote-endpoint = <&vproc_in>;
+ };
+ };
+ };
+ };
+...
diff --git a/Documentation/devicetree/bindings/memory-controllers/fsl/mmdc.txt b/Documentation/devicetree/bindings/memory-controllers/fsl/mmdc.txt
deleted file mode 100644
index bcc36c5..0000000
--- a/Documentation/devicetree/bindings/memory-controllers/fsl/mmdc.txt
+++ /dev/null
@@ -1,35 +0,0 @@
-Freescale Multi Mode DDR controller (MMDC)
-
-Required properties :
-- compatible : should be one of following:
- for i.MX6Q/i.MX6DL:
- - "fsl,imx6q-mmdc";
- for i.MX6QP:
- - "fsl,imx6qp-mmdc", "fsl,imx6q-mmdc";
- for i.MX6SL:
- - "fsl,imx6sl-mmdc", "fsl,imx6q-mmdc";
- for i.MX6SLL:
- - "fsl,imx6sll-mmdc", "fsl,imx6q-mmdc";
- for i.MX6SX:
- - "fsl,imx6sx-mmdc", "fsl,imx6q-mmdc";
- for i.MX6UL/i.MX6ULL/i.MX6ULZ:
- - "fsl,imx6ul-mmdc", "fsl,imx6q-mmdc";
- for i.MX7ULP:
- - "fsl,imx7ulp-mmdc", "fsl,imx6q-mmdc";
-- reg : address and size of MMDC DDR controller registers
-
-Optional properties :
-- clocks : the clock provided by the SoC to access the MMDC registers
-
-Example :
- mmdc0: memory-controller@21b0000 { /* MMDC0 */
- compatible = "fsl,imx6q-mmdc";
- reg = <0x021b0000 0x4000>;
- clocks = <&clks IMX6QDL_CLK_MMDC_P0_IPG>;
- };
-
- mmdc1: memory-controller@21b4000 { /* MMDC1 */
- compatible = "fsl,imx6q-mmdc";
- reg = <0x021b4000 0x4000>;
- status = "disabled";
- };
diff --git a/Documentation/devicetree/bindings/memory-controllers/fsl/mmdc.yaml b/Documentation/devicetree/bindings/memory-controllers/fsl/mmdc.yaml
new file mode 100644
index 0000000..dee5131
--- /dev/null
+++ b/Documentation/devicetree/bindings/memory-controllers/fsl/mmdc.yaml
@@ -0,0 +1,49 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/memory-controllers/fsl/mmdc.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Freescale Multi Mode DDR controller (MMDC)
+
+maintainers:
+ - Anson Huang <Anson.Huang@nxp.com>
+
+properties:
+ compatible:
+ oneOf:
+ - const: fsl,imx6q-mmdc
+ - items:
+ - enum:
+ - fsl,imx6qp-mmdc
+ - fsl,imx6sl-mmdc
+ - fsl,imx6sll-mmdc
+ - fsl,imx6sx-mmdc
+ - fsl,imx6ul-mmdc
+ - fsl,imx7ulp-mmdc
+ - const: fsl,imx6q-mmdc
+
+ reg:
+ maxItems: 1
+
+ clocks:
+ maxItems: 1
+
+required:
+ - compatible
+ - reg
+
+examples:
+ - |
+ #include <dt-bindings/clock/imx6qdl-clock.h>
+
+ memory-controller@21b0000 {
+ compatible = "fsl,imx6q-mmdc";
+ reg = <0x021b0000 0x4000>;
+ clocks = <&clks IMX6QDL_CLK_MMDC_P0_IPG>;
+ };
+
+ memory-controller@21b4000 {
+ compatible = "fsl,imx6q-mmdc";
+ reg = <0x021b4000 0x4000>;
+ };
diff --git a/Documentation/devicetree/bindings/memory-controllers/mediatek,smi-common.txt b/Documentation/devicetree/bindings/memory-controllers/mediatek,smi-common.txt
index b478ade..b645736 100644
--- a/Documentation/devicetree/bindings/memory-controllers/mediatek,smi-common.txt
+++ b/Documentation/devicetree/bindings/memory-controllers/mediatek,smi-common.txt
@@ -5,7 +5,7 @@
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.
+generation 2: mt2712, mt6779, 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
@@ -18,6 +18,7 @@
- compatible : must be one of :
"mediatek,mt2701-smi-common"
"mediatek,mt2712-smi-common"
+ "mediatek,mt6779-smi-common"
"mediatek,mt7623-smi-common", "mediatek,mt2701-smi-common"
"mediatek,mt8173-smi-common"
"mediatek,mt8183-smi-common"
@@ -35,7 +36,7 @@
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.
+ Here is the list which has this GALS: mt6779 and 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 4b369b3..8f19dfe 100644
--- a/Documentation/devicetree/bindings/memory-controllers/mediatek,smi-larb.txt
+++ b/Documentation/devicetree/bindings/memory-controllers/mediatek,smi-larb.txt
@@ -6,6 +6,7 @@
- compatible : must be one of :
"mediatek,mt2701-smi-larb"
"mediatek,mt2712-smi-larb"
+ "mediatek,mt6779-smi-larb"
"mediatek,mt7623-smi-larb", "mediatek,mt2701-smi-larb"
"mediatek,mt8173-smi-larb"
"mediatek,mt8183-smi-larb"
@@ -21,7 +22,7 @@
- "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:
+Required property for mt2701, mt2712, mt6779 and mt7623:
- mediatek,larb-id :the hardware id of this larb.
Example:
diff --git a/Documentation/devicetree/bindings/memory-controllers/renesas,rpc-if.yaml b/Documentation/devicetree/bindings/memory-controllers/renesas,rpc-if.yaml
new file mode 100644
index 0000000..6600056
--- /dev/null
+++ b/Documentation/devicetree/bindings/memory-controllers/renesas,rpc-if.yaml
@@ -0,0 +1,88 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/memory-controllers/renesas,rpc-if.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Renesas Reduced Pin Count Interface (RPC-IF)
+
+maintainers:
+ - Sergei Shtylyov <sergei.shtylyov@gmail.com>
+
+description: |
+ Renesas RPC-IF allows a SPI flash or HyperFlash connected to the SoC to
+ be accessed via the external address space read mode or the manual mode.
+
+ The flash chip itself should be represented by a subnode of the RPC-IF node.
+ The flash interface is selected based on the "compatible" property of this
+ subnode:
+ - if it contains "jedec,spi-nor", then SPI is used;
+ - if it contains "cfi-flash", then HyperFlash is used.
+
+allOf:
+ - $ref: "/schemas/spi/spi-controller.yaml#"
+
+properties:
+ compatible:
+ items:
+ - enum:
+ - renesas,r8a77970-rpc-if # R-Car V3M
+ - renesas,r8a77980-rpc-if # R-Car V3H
+ - renesas,r8a77995-rpc-if # R-Car D3
+ - const: renesas,rcar-gen3-rpc-if # a generic R-Car gen3 device
+
+ reg:
+ items:
+ - description: RPC-IF registers
+ - description: direct mapping read mode area
+ - description: write buffer area
+
+ reg-names:
+ items:
+ - const: regs
+ - const: dirmap
+ - const: wbuf
+
+ clocks:
+ maxItems: 1
+
+ power-domains:
+ maxItems: 1
+
+ resets:
+ maxItems: 1
+
+patternProperties:
+ "flash@[0-9a-f]+$":
+ type: object
+ properties:
+ compatible:
+ enum:
+ - cfi-flash
+ - jedec,spi-nor
+
+examples:
+ - |
+ #include <dt-bindings/clock/renesas-cpg-mssr.h>
+ #include <dt-bindings/power/r8a77995-sysc.h>
+
+ spi@ee200000 {
+ compatible = "renesas,r8a77995-rpc-if", "renesas,rcar-gen3-rpc-if";
+ reg = <0xee200000 0x200>,
+ <0x08000000 0x4000000>,
+ <0xee208000 0x100>;
+ reg-names = "regs", "dirmap", "wbuf";
+ clocks = <&cpg CPG_MOD 917>;
+ power-domains = <&sysc R8A77995_PD_ALWAYS_ON>;
+ resets = <&cpg 917>;
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ flash@0 {
+ compatible = "jedec,spi-nor";
+ reg = <0>;
+ spi-max-frequency = <40000000>;
+ spi-tx-bus-width = <1>;
+ spi-rx-bus-width = <1>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/memory-controllers/st,stm32-fmc2-ebi.yaml b/Documentation/devicetree/bindings/memory-controllers/st,stm32-fmc2-ebi.yaml
new file mode 100644
index 0000000..70eaf73
--- /dev/null
+++ b/Documentation/devicetree/bindings/memory-controllers/st,stm32-fmc2-ebi.yaml
@@ -0,0 +1,252 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/memory-controllers/st,stm32-fmc2-ebi.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: STMicroelectronics Flexible Memory Controller 2 (FMC2) Bindings
+
+description: |
+ The FMC2 functional block makes the interface with: synchronous and
+ asynchronous static devices (such as PSNOR, PSRAM or other memory-mapped
+ peripherals) and NAND flash memories.
+ Its main purposes are:
+ - to translate AXI transactions into the appropriate external device
+ protocol
+ - to meet the access time requirements of the external devices
+ All external devices share the addresses, data and control signals with the
+ controller. Each external device is accessed by means of a unique Chip
+ Select. The FMC2 performs only one access at a time to an external device.
+
+maintainers:
+ - Christophe Kerello <christophe.kerello@st.com>
+
+properties:
+ compatible:
+ const: st,stm32mp1-fmc2-ebi
+
+ reg:
+ maxItems: 1
+
+ clocks:
+ maxItems: 1
+
+ resets:
+ maxItems: 1
+
+ "#address-cells":
+ const: 2
+
+ "#size-cells":
+ const: 1
+
+ ranges:
+ description: |
+ Reflects the memory layout with four integer values per bank. Format:
+ <bank-number> 0 <address of the bank> <size>
+
+patternProperties:
+ "^.*@[0-4],[a-f0-9]+$":
+ type: object
+
+ properties:
+ reg:
+ description: Bank number, base address and size of the device.
+
+ st,fmc2-ebi-cs-transaction-type:
+ description: |
+ Select one of the transactions type supported
+ 0: Asynchronous mode 1 SRAM/FRAM.
+ 1: Asynchronous mode 1 PSRAM.
+ 2: Asynchronous mode A SRAM/FRAM.
+ 3: Asynchronous mode A PSRAM.
+ 4: Asynchronous mode 2 NOR.
+ 5: Asynchronous mode B NOR.
+ 6: Asynchronous mode C NOR.
+ 7: Asynchronous mode D NOR.
+ 8: Synchronous read synchronous write PSRAM.
+ 9: Synchronous read asynchronous write PSRAM.
+ 10: Synchronous read synchronous write NOR.
+ 11: Synchronous read asynchronous write NOR.
+ $ref: /schemas/types.yaml#/definitions/uint32
+ minimum: 0
+ maximum: 11
+
+ st,fmc2-ebi-cs-cclk-enable:
+ description: Continuous clock enable (first bank must be configured
+ in synchronous mode). The FMC_CLK is generated continuously
+ during asynchronous and synchronous access. By default, the
+ FMC_CLK is only generated during synchronous access.
+ $ref: /schemas/types.yaml#/definitions/flag
+
+ st,fmc2-ebi-cs-mux-enable:
+ description: Address/Data multiplexed on databus (valid only with
+ NOR and PSRAM transactions type). By default, Address/Data
+ are not multiplexed.
+ $ref: /schemas/types.yaml#/definitions/flag
+
+ st,fmc2-ebi-cs-buswidth:
+ description: Data bus width
+ $ref: /schemas/types.yaml#/definitions/uint32
+ enum: [ 8, 16 ]
+ default: 16
+
+ st,fmc2-ebi-cs-waitpol-high:
+ description: Wait signal polarity (NWAIT signal active high).
+ By default, NWAIT is active low.
+ $ref: /schemas/types.yaml#/definitions/flag
+
+ st,fmc2-ebi-cs-waitcfg-enable:
+ description: The NWAIT signal indicates wheither the data from the
+ device are valid or if a wait state must be inserted when accessing
+ the device in synchronous mode. By default, the NWAIT signal is
+ active one data cycle before wait state.
+ $ref: /schemas/types.yaml#/definitions/flag
+
+ st,fmc2-ebi-cs-wait-enable:
+ description: The NWAIT signal is enabled (its level is taken into
+ account after the programmed latency period to insert wait states
+ if asserted). By default, the NWAIT signal is disabled.
+ $ref: /schemas/types.yaml#/definitions/flag
+
+ st,fmc2-ebi-cs-asyncwait-enable:
+ description: The NWAIT signal is taken into account during asynchronous
+ transactions. By default, the NWAIT signal is not taken into account
+ during asynchronous transactions.
+ $ref: /schemas/types.yaml#/definitions/flag
+
+ st,fmc2-ebi-cs-cpsize:
+ description: CRAM page size. The controller splits the burst access
+ when the memory page is reached. By default, no burst split when
+ crossing page boundary.
+ $ref: /schemas/types.yaml#/definitions/uint32
+ enum: [ 0, 128, 256, 512, 1024 ]
+ default: 0
+
+ st,fmc2-ebi-cs-byte-lane-setup-ns:
+ description: This property configures the byte lane setup timing
+ defined in nanoseconds from NBLx low to Chip Select NEx low.
+
+ st,fmc2-ebi-cs-address-setup-ns:
+ description: This property defines the duration of the address setup
+ phase in nanoseconds used for asynchronous read/write transactions.
+
+ st,fmc2-ebi-cs-address-hold-ns:
+ description: This property defines the duration of the address hold
+ phase in nanoseconds used for asynchronous multiplexed read/write
+ transactions.
+
+ st,fmc2-ebi-cs-data-setup-ns:
+ description: This property defines the duration of the data setup phase
+ in nanoseconds used for asynchronous read/write transactions.
+
+ st,fmc2-ebi-cs-bus-turnaround-ns:
+ description: This property defines the delay in nanoseconds between the
+ end of current read/write transaction and the next transaction.
+
+ st,fmc2-ebi-cs-data-hold-ns:
+ description: This property defines the duration of the data hold phase
+ in nanoseconds used for asynchronous read/write transactions.
+
+ st,fmc2-ebi-cs-clk-period-ns:
+ description: This property defines the FMC_CLK output signal period in
+ nanoseconds.
+
+ st,fmc2-ebi-cs-data-latency-ns:
+ description: This property defines the data latency before reading or
+ writing the first data in nanoseconds.
+
+ st,fmc2_ebi-cs-write-address-setup-ns:
+ description: This property defines the duration of the address setup
+ phase in nanoseconds used for asynchronous write transactions.
+
+ st,fmc2-ebi-cs-write-address-hold-ns:
+ description: This property defines the duration of the address hold
+ phase in nanoseconds used for asynchronous multiplexed write
+ transactions.
+
+ st,fmc2-ebi-cs-write-data-setup-ns:
+ description: This property defines the duration of the data setup
+ phase in nanoseconds used for asynchronous write transactions.
+
+ st,fmc2-ebi-cs-write-bus-turnaround-ns:
+ description: This property defines the delay between the end of current
+ write transaction and the next transaction in nanoseconds.
+
+ st,fmc2-ebi-cs-write-data-hold-ns:
+ description: This property defines the duration of the data hold phase
+ in nanoseconds used for asynchronous write transactions.
+
+ st,fmc2-ebi-cs-max-low-pulse-ns:
+ description: This property defines the maximum chip select low pulse
+ duration in nanoseconds for synchronous transactions. When this timing
+ reaches 0, the controller splits the current access, toggles NE to
+ allow device refresh and restarts a new access.
+
+ required:
+ - reg
+
+required:
+ - "#address-cells"
+ - "#size-cells"
+ - compatible
+ - reg
+ - clocks
+ - ranges
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+ #include <dt-bindings/clock/stm32mp1-clks.h>
+ #include <dt-bindings/reset/stm32mp1-resets.h>
+ memory-controller@58002000 {
+ #address-cells = <2>;
+ #size-cells = <1>;
+ compatible = "st,stm32mp1-fmc2-ebi";
+ reg = <0x58002000 0x1000>;
+ clocks = <&rcc FMC_K>;
+ resets = <&rcc FMC_R>;
+
+ ranges = <0 0 0x60000000 0x04000000>, /* EBI CS 1 */
+ <1 0 0x64000000 0x04000000>, /* EBI CS 2 */
+ <2 0 0x68000000 0x04000000>, /* EBI CS 3 */
+ <3 0 0x6c000000 0x04000000>, /* EBI CS 4 */
+ <4 0 0x80000000 0x10000000>; /* NAND */
+
+ psram@0,0 {
+ compatible = "mtd-ram";
+ reg = <0 0x00000000 0x100000>;
+ bank-width = <2>;
+
+ st,fmc2-ebi-cs-transaction-type = <1>;
+ st,fmc2-ebi-cs-address-setup-ns = <60>;
+ st,fmc2-ebi-cs-data-setup-ns = <30>;
+ st,fmc2-ebi-cs-bus-turnaround-ns = <5>;
+ };
+
+ nand-controller@4,0 {
+ #address-cells = <1>;
+ #size-cells = <0>;
+ compatible = "st,stm32mp1-fmc2-nfc";
+ reg = <4 0x00000000 0x1000>,
+ <4 0x08010000 0x1000>,
+ <4 0x08020000 0x1000>,
+ <4 0x01000000 0x1000>,
+ <4 0x09010000 0x1000>,
+ <4 0x09020000 0x1000>;
+ interrupts = <GIC_SPI 48 IRQ_TYPE_LEVEL_HIGH>;
+ dmas = <&mdma1 20 0x2 0x12000a02 0x0 0x0>,
+ <&mdma1 20 0x2 0x12000a08 0x0 0x0>,
+ <&mdma1 21 0x2 0x12000a0a 0x0 0x0>;
+ dma-names = "tx", "rx", "ecc";
+
+ nand@0 {
+ reg = <0>;
+ nand-on-flash-bbt;
+ #address-cells = <1>;
+ #size-cells = <1>;
+ };
+ };
+ };
+
+...
diff --git a/Documentation/devicetree/bindings/mfd/aspeed-lpc.txt b/Documentation/devicetree/bindings/mfd/aspeed-lpc.txt
index 8644607..a92acf1 100644
--- a/Documentation/devicetree/bindings/mfd/aspeed-lpc.txt
+++ b/Documentation/devicetree/bindings/mfd/aspeed-lpc.txt
@@ -37,7 +37,7 @@
[0] http://www.intel.com/design/chipsets/industry/25128901.pdf
[1] https://www.renesas.com/en-sg/doc/products/mpumcu/001/rej09b0078_h8s2168.pdf?key=7c88837454702128622bee53acbda8f4
-[2] http://www.intel.com/content/dam/www/public/us/en/documents/product-briefs/ipmi-second-gen-interface-spec-v2-rev1-1.pdf
+[2] https://www.intel.com/content/dam/www/public/us/en/documents/product-briefs/ipmi-second-gen-interface-spec-v2-rev1-1.pdf
[3] https://en.wikipedia.org/wiki/Super_I/O
Required properties
diff --git a/Documentation/devicetree/bindings/mfd/atmel-tcb.txt b/Documentation/devicetree/bindings/mfd/atmel-tcb.txt
deleted file mode 100644
index c4a83e3..0000000
--- a/Documentation/devicetree/bindings/mfd/atmel-tcb.txt
+++ /dev/null
@@ -1,56 +0,0 @@
-* Device tree bindings for Atmel Timer Counter Blocks
-- compatible: Should be "atmel,<chip>-tcb", "simple-mfd", "syscon".
- <chip> can be "at91rm9200" or "at91sam9x5"
-- reg: Should contain registers location and length
-- #address-cells: has to be 1
-- #size-cells: has to be 0
-- interrupts: Should contain all interrupts for the TC block
- Note that you can specify several interrupt cells if the TC
- block has one interrupt per channel.
-- clock-names: tuple listing input clock names.
- Required elements: "t0_clk", "slow_clk"
- Optional elements: "t1_clk", "t2_clk"
-- clocks: phandles to input clocks.
-
-The TCB can expose multiple subdevices:
- * a timer
- - compatible: Should be "atmel,tcb-timer"
- - reg: Should contain the TCB channels to be used. If the
- counter width is 16 bits (at91rm9200-tcb), two consecutive
- channels are needed. Else, only one channel will be used.
-
-Examples:
-
-One interrupt per TC block:
- tcb0: timer@fff7c000 {
- compatible = "atmel,at91rm9200-tcb", "simple-mfd", "syscon";
- #address-cells = <1>;
- #size-cells = <0>;
- reg = <0xfff7c000 0x100>;
- interrupts = <18 4>;
- clocks = <&tcb0_clk>, <&clk32k>;
- clock-names = "t0_clk", "slow_clk";
-
- timer@0 {
- compatible = "atmel,tcb-timer";
- reg = <0>, <1>;
- };
-
- timer@2 {
- compatible = "atmel,tcb-timer";
- reg = <2>;
- };
- };
-
-One interrupt per TC channel in a TC block:
- tcb1: timer@fffdc000 {
- compatible = "atmel,at91rm9200-tcb", "simple-mfd", "syscon";
- #address-cells = <1>;
- #size-cells = <0>;
- reg = <0xfffdc000 0x100>;
- interrupts = <26 4>, <27 4>, <28 4>;
- clocks = <&tcb1_clk>, <&clk32k>;
- clock-names = "t0_clk", "slow_clk";
- };
-
-
diff --git a/Documentation/devicetree/bindings/mfd/da9062.txt b/Documentation/devicetree/bindings/mfd/da9062.txt
index 857af98..bab0d0e 100644
--- a/Documentation/devicetree/bindings/mfd/da9062.txt
+++ b/Documentation/devicetree/bindings/mfd/da9062.txt
@@ -1,8 +1,8 @@
* Dialog DA9062 Power Management Integrated Circuit (PMIC)
Product information for the DA9062 and DA9061 devices can be found here:
-- http://www.dialog-semiconductor.com/products/da9062
-- http://www.dialog-semiconductor.com/products/da9061
+- https://www.dialog-semiconductor.com/products/da9062
+- https://www.dialog-semiconductor.com/products/da9061
The DA9062 PMIC consists of:
diff --git a/Documentation/devicetree/bindings/mfd/syscon.yaml b/Documentation/devicetree/bindings/mfd/syscon.yaml
index 19bdaf7..049ec2f 100644
--- a/Documentation/devicetree/bindings/mfd/syscon.yaml
+++ b/Documentation/devicetree/bindings/mfd/syscon.yaml
@@ -38,12 +38,15 @@
- allwinner,sun8i-h3-system-controller
- allwinner,sun8i-v3s-system-controller
- allwinner,sun50i-a64-system-controller
+ - microchip,sparx5-cpu-syscon
+ - mstar,msc313-pmsleep
- const: syscon
- contains:
const: syscon
- additionalItems: true
+ minItems: 2
+ maxItems: 4 # Should be enough
reg:
maxItems: 1
diff --git a/Documentation/devicetree/bindings/mfd/ti,j721e-system-controller.yaml b/Documentation/devicetree/bindings/mfd/ti,j721e-system-controller.yaml
new file mode 100644
index 0000000..03d0a23
--- /dev/null
+++ b/Documentation/devicetree/bindings/mfd/ti,j721e-system-controller.yaml
@@ -0,0 +1,74 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+# Copyright (C) 2020 Texas Instruments Incorporated - http://www.ti.com/
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/mfd/ti,j721e-system-controller.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: TI J721e System Controller Registers R/W Device Tree Bindings
+
+description: |
+ This represents the Control Module registers (CTRL_MMR0) on the SoC.
+ System controller node represents a register region containing a set
+ of miscellaneous registers. The registers are not cohesive enough to
+ represent as any specific type of device. The typical use-case is
+ for some other node's driver, or platform-specific code, to acquire
+ a reference to the syscon node (e.g. by phandle, node path, or
+ search using a specific compatible value), interrogate the node (or
+ associated OS driver) to determine the location of the registers,
+ and access the registers directly.
+
+maintainers:
+ - Kishon Vijay Abraham I <kishon@ti.com>
+ - Roger Quadros <rogerq@ti.com
+
+properties:
+ compatible:
+ anyOf:
+ - items:
+ - enum:
+ - ti,j721e-system-controller
+ - const: syscon
+ - const: simple-mfd
+
+ "#address-cells":
+ const: 1
+
+ "#size-cells":
+ const: 1
+
+ ranges: true
+
+# Optional children
+
+ "^serdes-ln-ctrl@[0-9a-f]+$":
+ type: object
+ description: |
+ This is the SERDES lane control mux. It should follow the bindings
+ specified in
+ Documentation/devicetree/bindings/mux/reg-mux.txt
+
+required:
+ - compatible
+ - reg
+ - "#address-cells"
+ - "#size-cells"
+ - ranges
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ scm_conf: scm-conf@100000 {
+ compatible = "ti,j721e-system-controller", "syscon", "simple-mfd";
+ reg = <0x00100000 0x1c000>;
+ #address-cells = <1>;
+ #size-cells = <1>;
+ ranges;
+
+ serdes_ln_ctrl: serdes-ln-ctrl@4080 {
+ compatible = "mmio-mux";
+ reg = <0x00004080 0x50>;
+ };
+ };
+...
diff --git a/Documentation/devicetree/bindings/mips/ingenic/devices.yaml b/Documentation/devicetree/bindings/mips/ingenic/devices.yaml
index d117503..83c86cb 100644
--- a/Documentation/devicetree/bindings/mips/ingenic/devices.yaml
+++ b/Documentation/devicetree/bindings/mips/ingenic/devices.yaml
@@ -8,7 +8,8 @@
maintainers:
- 周琰杰 (Zhou Yanjie) <zhouyanjie@wanyeetech.com>
-description: |
+
+description:
Devices with a Ingenic XBurst CPU shall have the following properties.
properties:
@@ -22,6 +23,11 @@
- const: qi,lb60
- const: ingenic,jz4740
+ - description: YLM RetroMini RS-90
+ items:
+ - const: ylm,rs90
+ - const: ingenic,jz4725b
+
- description: Game Consoles Worldwide GCW Zero
items:
- const: gcw,zero
@@ -32,8 +38,13 @@
- const: img,ci20
- const: ingenic,jz4780
- - description: YSH & ATIL General Board CU Neo
+ - description: YSH & ATIL General Board, CU1000 Module with Neo Backplane
items:
- const: yna,cu1000-neo
- - const: ingenic,x1000
+ - const: ingenic,x1000e
+
+ - description: YSH & ATIL General Board, CU1830 Module with Neo Backplane
+ items:
+ - const: yna,cu1830-neo
+ - const: ingenic,x1830
...
diff --git a/Documentation/devicetree/bindings/mips/ingenic/ingenic,cpu.yaml b/Documentation/devicetree/bindings/mips/ingenic/ingenic,cpu.yaml
new file mode 100644
index 0000000..16fa03d
--- /dev/null
+++ b/Documentation/devicetree/bindings/mips/ingenic/ingenic,cpu.yaml
@@ -0,0 +1,67 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/mips/ingenic/ingenic,cpu.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Bindings for Ingenic XBurst family CPUs
+
+maintainers:
+ - 周琰杰 (Zhou Yanjie) <zhouyanjie@wanyeetech.com>
+
+description:
+ Ingenic XBurst family CPUs shall have the following properties.
+
+properties:
+ compatible:
+ oneOf:
+
+ - description: Ingenic XBurst®1 CPU Cores
+ enum:
+ - ingenic,xburst-mxu1.0
+ - ingenic,xburst-fpu1.0-mxu1.1
+ - ingenic,xburst-fpu2.0-mxu2.0
+
+ - description: Ingenic XBurst®2 CPU Cores
+ enum:
+ - ingenic,xburst2-fpu2.1-mxu2.1-smt
+
+ reg:
+ maxItems: 1
+
+ clocks:
+ maxItems: 1
+
+required:
+ - device_type
+ - compatible
+ - reg
+ - clocks
+
+examples:
+ - |
+ #include <dt-bindings/clock/jz4780-cgu.h>
+
+ cpus {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ cpu0: cpu@0 {
+ device_type = "cpu";
+ compatible = "ingenic,xburst-fpu1.0-mxu1.1";
+ reg = <0>;
+
+ clocks = <&cgu JZ4780_CLK_CPU>;
+ clock-names = "cpu";
+ };
+
+ cpu1: cpu@1 {
+ device_type = "cpu";
+ compatible = "ingenic,xburst-fpu1.0-mxu1.1";
+ reg = <1>;
+
+ clocks = <&cgu JZ4780_CLK_CORE1>;
+ clock-names = "cpu";
+ };
+ };
+...
diff --git a/Documentation/devicetree/bindings/mips/loongson/devices.yaml b/Documentation/devicetree/bindings/mips/loongson/devices.yaml
index 74ed4e3..d25e80a 100644
--- a/Documentation/devicetree/bindings/mips/loongson/devices.yaml
+++ b/Documentation/devicetree/bindings/mips/loongson/devices.yaml
@@ -17,11 +17,23 @@
compatible:
oneOf:
- - description: Generic Loongson3 Quad Core + RS780E
+ - description: Classic Loongson64 Quad Core + LS7A
items:
- - const: loongson,loongson3-4core-rs780e
+ - const: loongson,loongson64c-4core-ls7a
- - description: Generic Loongson3 Octa Core + RS780E
+ - description: Classic Loongson64 Quad Core + RS780E
items:
- - const: loongson,loongson3-8core-rs780e
+ - const: loongson,loongson64c-4core-rs780e
+
+ - description: Classic Loongson64 Octa Core + RS780E
+ items:
+ - const: loongson,loongson64c-8core-rs780e
+
+ - description: Generic Loongson64 Quad Core + LS7A
+ items:
+ - const: loongson,loongson64g-4core-ls7a
+
+ - description: Virtual Loongson64 Quad Core + VirtIO
+ items:
+ - const: loongson,loongson64v-4core-virtio
...
diff --git a/Documentation/devicetree/bindings/misc/fsl,qoriq-mc.txt b/Documentation/devicetree/bindings/misc/fsl,qoriq-mc.txt
index 9134e9b..7b486d4 100644
--- a/Documentation/devicetree/bindings/misc/fsl,qoriq-mc.txt
+++ b/Documentation/devicetree/bindings/misc/fsl,qoriq-mc.txt
@@ -10,7 +10,7 @@
etc.
For an overview of the DPAA2 architecture and fsl-mc bus see:
-Documentation/networking/device_drivers/freescale/dpaa2/overview.rst
+Documentation/networking/device_drivers/ethernet/freescale/dpaa2/overview.rst
As described in the above overview, all DPAA2 objects in a DPRC share the
same hardware "isolation context" and a 10-bit value called an ICID
@@ -28,6 +28,16 @@
For arm-smmu binding, see:
Documentation/devicetree/bindings/iommu/arm,smmu.yaml.
+The MSI writes are accompanied by sideband data which is derived from the ICID.
+The msi-map property is used to associate the devices with both the ITS
+controller and the sideband data which accompanies the writes.
+
+For generic MSI bindings, see
+Documentation/devicetree/bindings/interrupt-controller/msi.txt.
+
+For GICv3 and GIC ITS bindings, see:
+Documentation/devicetree/bindings/interrupt-controller/arm,gic-v3.yaml.
+
Required properties:
- compatible
@@ -49,11 +59,6 @@
region may not be present in some scenarios, such
as in the device tree presented to a virtual machine.
- - msi-parent
- Value type: <phandle>
- Definition: Must be present and point to the MSI controller node
- handling message interrupts for the MC.
-
- ranges
Value type: <prop-encoded-array>
Definition: A standard property. Defines the mapping between the child
@@ -119,6 +124,28 @@
associated with the listed IOMMU, with the iommu-specifier
(i - icid-base + iommu-base).
+- msi-map: Maps an ICID to a GIC ITS and associated msi-specifier
+ data.
+
+ The property is an arbitrary number of tuples of
+ (icid-base,gic-its,msi-base,length).
+
+ Any ICID in the interval [icid-base, icid-base + length) is
+ associated with the listed GIC ITS, with the msi-specifier
+ (i - icid-base + msi-base).
+
+Deprecated properties:
+
+ - msi-parent
+ Value type: <phandle>
+ Definition: Describes the MSI controller node handling message
+ interrupts for the MC. When there is no translation
+ between the ICID and deviceID this property can be used
+ to describe the MSI controller used by the devices on the
+ mc-bus.
+ The use of this property for mc-bus is deprecated. Please
+ use msi-map.
+
Example:
smmu: iommu@5000000 {
@@ -128,13 +155,24 @@
...
};
+ gic: interrupt-controller@6000000 {
+ compatible = "arm,gic-v3";
+ ...
+ }
+ its: gic-its@6020000 {
+ compatible = "arm,gic-v3-its";
+ msi-controller;
+ ...
+ };
+
fsl_mc: fsl-mc@80c000000 {
compatible = "fsl,qoriq-mc";
reg = <0x00000008 0x0c000000 0 0x40>, /* MC portal base */
<0x00000000 0x08340000 0 0x40000>; /* MC control reg */
- msi-parent = <&its>;
/* define map for ICIDs 23-64 */
iommu-map = <23 &smmu 23 41>;
+ /* define msi map for ICIDs 23-64 */
+ msi-map = <23 &its 23 41>;
#address-cells = <3>;
#size-cells = <1>;
diff --git a/Documentation/devicetree/bindings/misc/olpc,xo1.75-ec.txt b/Documentation/devicetree/bindings/misc/olpc,xo1.75-ec.txt
deleted file mode 100644
index 8c4d649..0000000
--- a/Documentation/devicetree/bindings/misc/olpc,xo1.75-ec.txt
+++ /dev/null
@@ -1,23 +0,0 @@
-OLPC XO-1.75 Embedded Controller
-
-Required properties:
-- compatible: Should be "olpc,xo1.75-ec".
-- cmd-gpios: gpio specifier of the CMD pin
-
-The embedded controller requires the SPI controller driver to signal readiness
-to receive a transfer (that is, when TX FIFO contains the response data) by
-strobing the ACK pin with the ready signal. See the "ready-gpios" property of the
-SSP binding as documented in:
-<Documentation/devicetree/bindings/spi/spi-pxa2xx.txt>.
-
-Example:
- &ssp3 {
- spi-slave;
- ready-gpios = <&gpio 125 GPIO_ACTIVE_HIGH>;
-
- slave {
- compatible = "olpc,xo1.75-ec";
- spi-cpha;
- cmd-gpios = <&gpio 155 GPIO_ACTIVE_HIGH>;
- };
- };
diff --git a/Documentation/devicetree/bindings/misc/olpc,xo1.75-ec.yaml b/Documentation/devicetree/bindings/misc/olpc,xo1.75-ec.yaml
new file mode 100644
index 0000000..e75d77b
--- /dev/null
+++ b/Documentation/devicetree/bindings/misc/olpc,xo1.75-ec.yaml
@@ -0,0 +1,52 @@
+# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
+# Copyright (C) 2019,2020 Lubomir Rintel <lkundrak@v3.sk>
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/misc/olpc,xo1.75-ec.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: OLPC XO-1.75 Embedded Controller bindings
+
+description: |
+ This binding describes the Embedded Controller acting as a SPI bus master
+ on a OLPC XO-1.75 laptop computer.
+
+ The embedded controller requires the SPI controller driver to signal
+ readiness to receive a transfer (that is, when TX FIFO contains the
+ response data) by strobing the ACK pin with the ready signal. See the
+ "ready-gpios" property of the SSP binding as documented in:
+ <Documentation/devicetree/bindings/spi/marvell,mmp2-ssp.yaml>.
+
+maintainers:
+ - Lubomir Rintel <lkundrak@v3.sk>
+
+properties:
+ compatible:
+ const: olpc,xo1.75-ec
+
+ cmd-gpios:
+ description: GPIO uspecifier of the CMD pin
+ maxItems: 1
+
+required:
+ - compatible
+ - cmd-gpios
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/gpio/gpio.h>
+
+ spi {
+ spi-slave;
+ ready-gpios = <&gpio 125 GPIO_ACTIVE_HIGH>;
+
+ slave {
+ compatible = "olpc,xo1.75-ec";
+ spi-cpha;
+ cmd-gpios = <&gpio 155 GPIO_ACTIVE_HIGH>;
+ };
+ };
+
+...
diff --git a/Documentation/devicetree/bindings/mmc/arasan,sdhci.txt b/Documentation/devicetree/bindings/mmc/arasan,sdhci.txt
deleted file mode 100644
index f29bf7d..0000000
--- a/Documentation/devicetree/bindings/mmc/arasan,sdhci.txt
+++ /dev/null
@@ -1,192 +0,0 @@
-Device Tree Bindings for the Arasan SDHCI Controller
-
- The bindings follow the mmc[1], clock[2], interrupt[3] and phy[4] bindings.
- Only deviations are documented here.
-
- [1] Documentation/devicetree/bindings/mmc/mmc.txt
- [2] Documentation/devicetree/bindings/clock/clock-bindings.txt
- [3] Documentation/devicetree/bindings/interrupt-controller/interrupts.txt
- [4] Documentation/devicetree/bindings/phy/phy-bindings.txt
-
-Required Properties:
- - compatible: Compatibility string. One of:
- - "arasan,sdhci-8.9a": generic Arasan SDHCI 8.9a PHY
- - "arasan,sdhci-4.9a": generic Arasan SDHCI 4.9a PHY
- - "arasan,sdhci-5.1": generic Arasan SDHCI 5.1 PHY
- - "rockchip,rk3399-sdhci-5.1", "arasan,sdhci-5.1": rk3399 eMMC PHY
- For this device it is strongly suggested to include arasan,soc-ctl-syscon.
- - "xlnx,zynqmp-8.9a": ZynqMP SDHCI 8.9a PHY
- For this device it is strongly suggested to include clock-output-names and
- #clock-cells.
- - "xlnx,versal-8.9a": Versal SDHCI 8.9a PHY
- For this device it is strongly suggested to include clock-output-names and
- #clock-cells.
- - "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.
- - "intel,lgm-sdhci-5.1-sdxc", "arasan,sdhci-5.1": Intel LGM SDXC PHY
- For this device it is strongly suggested to include arasan,soc-ctl-syscon.
- - "intel,keembay-sdhci-5.1-emmc", "arasan,sdhci-5.1": Intel Keem Bay eMMC
- For this device it is strongly suggested to include arasan,soc-ctl-syscon.
- - "intel,keembay-sdhci-5.1-sd": Intel Keem Bay SD controller
- For this device it is strongly suggested to include arasan,soc-ctl-syscon.
- - "intel,keembay-sdhci-5.1-sdio": Intel Keem Bay SDIO controller
- For this device it is strongly suggested to include arasan,soc-ctl-syscon.
-
- [5] Documentation/devicetree/bindings/mmc/sdhci-am654.txt
-
- - reg: From mmc bindings: Register location and length.
- - clocks: From clock bindings: Handles to clock inputs.
- - clock-names: From clock bindings: Tuple including "clk_xin" and "clk_ahb"
- - interrupts: Interrupt specifier
-
-Required Properties for "arasan,sdhci-5.1":
- - phys: From PHY bindings: Phandle for the Generic PHY for arasan.
- - phy-names: MUST be "phy_arasan".
-
-Optional Properties:
- - arasan,soc-ctl-syscon: A phandle to a syscon device (see ../mfd/syscon.txt)
- used to access core corecfg registers. Offsets of registers in this
- syscon are determined based on the main compatible string for the device.
- - clock-output-names: If specified, this will be the name of the card clock
- which will be exposed by this device. Required if #clock-cells is
- specified.
- - #clock-cells: If specified this should be the value <0> or <1>. With this
- property in place we will export one or two clocks representing the Card
- Clock. These clocks are expected to be consumed by our PHY.
- - xlnx,fails-without-test-cd: when present, the controller doesn't work when
- the CD line is not connected properly, and the line is not connected
- properly. Test mode can be used to force the controller to function.
- - xlnx,int-clock-stable-broken: when present, the controller always reports
- that the internal clock is stable even when it is not.
-
- - xlnx,mio-bank: When specified, this will indicate the MIO bank number in
- which the command and data lines are configured. If not specified, driver
- will assume this as 0.
-
-Example:
- sdhci@e0100000 {
- compatible = "arasan,sdhci-8.9a";
- reg = <0xe0100000 0x1000>;
- clock-names = "clk_xin", "clk_ahb";
- clocks = <&clkc 21>, <&clkc 32>;
- interrupt-parent = <&gic>;
- interrupts = <0 24 4>;
- } ;
-
- sdhci@e2800000 {
- compatible = "arasan,sdhci-5.1";
- reg = <0xe2800000 0x1000>;
- clock-names = "clk_xin", "clk_ahb";
- clocks = <&cru 8>, <&cru 18>;
- interrupt-parent = <&gic>;
- interrupts = <0 24 4>;
- phys = <&emmc_phy>;
- phy-names = "phy_arasan";
- } ;
-
- sdhci: sdhci@fe330000 {
- compatible = "rockchip,rk3399-sdhci-5.1", "arasan,sdhci-5.1";
- reg = <0x0 0xfe330000 0x0 0x10000>;
- interrupts = <GIC_SPI 11 IRQ_TYPE_LEVEL_HIGH>;
- clocks = <&cru SCLK_EMMC>, <&cru ACLK_EMMC>;
- clock-names = "clk_xin", "clk_ahb";
- arasan,soc-ctl-syscon = <&grf>;
- assigned-clocks = <&cru SCLK_EMMC>;
- assigned-clock-rates = <200000000>;
- clock-output-names = "emmc_cardclock";
- phys = <&emmc_phy>;
- phy-names = "phy_arasan";
- #clock-cells = <0>;
- };
-
- sdhci: mmc@ff160000 {
- compatible = "xlnx,zynqmp-8.9a", "arasan,sdhci-8.9a";
- interrupt-parent = <&gic>;
- interrupts = <0 48 4>;
- reg = <0x0 0xff160000 0x0 0x1000>;
- clocks = <&clk200>, <&clk200>;
- clock-names = "clk_xin", "clk_ahb";
- clock-output-names = "clk_out_sd0", "clk_in_sd0";
- #clock-cells = <1>;
- clk-phase-sd-hs = <63>, <72>;
- };
-
- sdhci: mmc@f1040000 {
- compatible = "xlnx,versal-8.9a", "arasan,sdhci-8.9a";
- interrupt-parent = <&gic>;
- interrupts = <0 126 4>;
- reg = <0x0 0xf1040000 0x0 0x10000>;
- clocks = <&clk200>, <&clk200>;
- clock-names = "clk_xin", "clk_ahb";
- clock-output-names = "clk_out_sd0", "clk_in_sd0";
- #clock-cells = <1>;
- clk-phase-sd-hs = <132>, <60>;
- };
-
- 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>;
- };
-
- sdxc: sdhci@ec600000 {
- compatible = "arasan,sdhci-5.1", "intel,lgm-sdhci-5.1-sdxc";
- reg = <0xec600000 0x300>;
- interrupt-parent = <&ioapic1>;
- interrupts = <43 1>;
- clocks = <&cgu0 LGM_CLK_SDIO>, <&cgu0 LGM_CLK_NGI>,
- <&cgu0 LGM_GCLK_SDXC>;
- clock-names = "clk_xin", "clk_ahb", "gate";
- clock-output-names = "sdxc_cardclock";
- #clock-cells = <0>;
- phys = <&sdxc_phy>;
- phy-names = "phy_arasan";
- arasan,soc-ctl-syscon = <&sysconf>;
- };
-
- mmc: mmc@33000000 {
- compatible = "intel,keembay-sdhci-5.1-emmc", "arasan,sdhci-5.1";
- interrupts = <GIC_SPI 82 IRQ_TYPE_LEVEL_HIGH>;
- reg = <0x0 0x33000000 0x0 0x300>;
- clock-names = "clk_xin", "clk_ahb";
- clocks = <&scmi_clk KEEM_BAY_PSS_AUX_EMMC>,
- <&scmi_clk KEEM_BAY_PSS_EMMC>;
- phys = <&emmc_phy>;
- phy-names = "phy_arasan";
- assigned-clocks = <&scmi_clk KEEM_BAY_PSS_AUX_EMMC>;
- assigned-clock-rates = <200000000>;
- clock-output-names = "emmc_cardclock";
- #clock-cells = <0>;
- arasan,soc-ctl-syscon = <&mmc_phy_syscon>;
- };
-
- sd0: mmc@31000000 {
- compatible = "intel,keembay-sdhci-5.1-sd";
- interrupts = <GIC_SPI 83 IRQ_TYPE_LEVEL_HIGH>;
- reg = <0x0 0x31000000 0x0 0x300>;
- clock-names = "clk_xin", "clk_ahb";
- clocks = <&scmi_clk KEEM_BAY_PSS_AUX_SD0>,
- <&scmi_clk KEEM_BAY_PSS_SD0>;
- arasan,soc-ctl-syscon = <&sd0_phy_syscon>;
- };
-
- sd1: mmc@32000000 {
- compatible = "intel,keembay-sdhci-5.1-sdio";
- interrupts = <GIC_SPI 84 IRQ_TYPE_LEVEL_HIGH>;
- reg = <0x0 0x32000000 0x0 0x300>;
- clock-names = "clk_xin", "clk_ahb";
- clocks = <&scmi_clk KEEM_BAY_PSS_AUX_SD1>,
- <&scmi_clk KEEM_BAY_PSS_SD1>;
- arasan,soc-ctl-syscon = <&sd1_phy_syscon>;
- };
diff --git a/Documentation/devicetree/bindings/mmc/arasan,sdhci.yaml b/Documentation/devicetree/bindings/mmc/arasan,sdhci.yaml
new file mode 100644
index 0000000..5887c91
--- /dev/null
+++ b/Documentation/devicetree/bindings/mmc/arasan,sdhci.yaml
@@ -0,0 +1,299 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: "http://devicetree.org/schemas/mmc/arasan,sdhci.yaml#"
+$schema: "http://devicetree.org/meta-schemas/core.yaml#"
+
+title: Device Tree Bindings for the Arasan SDHCI Controller
+
+maintainers:
+ - Adrian Hunter <adrian.hunter@intel.com>
+
+allOf:
+ - $ref: "mmc-controller.yaml#"
+ - if:
+ properties:
+ compatible:
+ contains:
+ const: arasan,sdhci-5.1
+ then:
+ required:
+ - phys
+ - phy-names
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - xlnx,zynqmp-8.9a
+ - xlnx,versal-8.9a
+ then:
+ properties:
+ clock-output-names:
+ items:
+ - const: clk_out_sd0
+ - const: clk_in_sd0
+
+properties:
+ compatible:
+ oneOf:
+ - const: arasan,sdhci-8.9a # generic Arasan SDHCI 8.9a PHY
+ - const: arasan,sdhci-4.9a # generic Arasan SDHCI 4.9a PHY
+ - const: arasan,sdhci-5.1 # generic Arasan SDHCI 5.1 PHY
+ - items:
+ - const: rockchip,rk3399-sdhci-5.1 # rk3399 eMMC PHY
+ - const: arasan,sdhci-5.1
+ description:
+ For this device it is strongly suggested to include
+ arasan,soc-ctl-syscon.
+ - items:
+ - const: xlnx,zynqmp-8.9a # ZynqMP SDHCI 8.9a PHY
+ - const: arasan,sdhci-8.9a
+ description:
+ For this device it is strongly suggested to include
+ clock-output-names and '#clock-cells'.
+ - items:
+ - const: xlnx,versal-8.9a # Versal SDHCI 8.9a PHY
+ - const: arasan,sdhci-8.9a
+ description:
+ For this device it is strongly suggested to include
+ clock-output-names and '#clock-cells'.
+ - items:
+ - const: intel,lgm-sdhci-5.1-emmc # Intel LGM eMMC PHY
+ - const: arasan,sdhci-5.1
+ description:
+ For this device it is strongly suggested to include
+ arasan,soc-ctl-syscon.
+ - items:
+ - const: intel,lgm-sdhci-5.1-sdxc # Intel LGM SDXC PHY
+ - const: arasan,sdhci-5.1
+ description:
+ For this device it is strongly suggested to include
+ arasan,soc-ctl-syscon.
+ - items:
+ - const: intel,keembay-sdhci-5.1-emmc # Intel Keem Bay eMMC PHY
+ - const: arasan,sdhci-5.1
+ description:
+ For this device it is strongly suggested to include
+ arasan,soc-ctl-syscon.
+ - const: intel,keembay-sdhci-5.1-sd # Intel Keem Bay SD controller
+ description:
+ For this device it is strongly suggested to include
+ arasan,soc-ctl-syscon.
+ - const: intel,keembay-sdhci-5.1-sdio # Intel Keem Bay SDIO controller
+ description:
+ For this device it is strongly suggested to include
+ arasan,soc-ctl-syscon.
+
+ reg:
+ maxItems: 1
+
+ clocks:
+ minItems: 2
+ maxItems: 3
+
+ clock-names:
+ minItems: 2
+ items:
+ - const: clk_xin
+ - const: clk_ahb
+ - const: gate
+
+ interrupts:
+ maxItems: 1
+
+ phys:
+ maxItems: 1
+
+ phy-names:
+ const: phy_arasan
+
+ arasan,soc-ctl-syscon:
+ $ref: /schemas/types.yaml#/definitions/phandle
+ description:
+ A phandle to a syscon device (see ../mfd/syscon.txt) used to access
+ core corecfg registers. Offsets of registers in this syscon are
+ determined based on the main compatible string for the device.
+
+ clock-output-names:
+ minItems: 1
+ maxItems: 2
+ description:
+ Name of the card clock which will be exposed by this device.
+
+ '#clock-cells':
+ enum: [0, 1]
+ description:
+ With this property in place we will export one or two clocks
+ representing the Card Clock. These clocks are expected to be
+ consumed by our PHY.
+
+ xlnx,fails-without-test-cd:
+ $ref: /schemas/types.yaml#/definitions/flag
+ description:
+ When present, the controller doesn't work when the CD line is not
+ connected properly, and the line is not connected properly.
+ Test mode can be used to force the controller to function.
+
+ xlnx,int-clock-stable-broken:
+ $ref: /schemas/types.yaml#/definitions/flag
+ description:
+ When present, the controller always reports that the internal clock
+ is stable even when it is not.
+
+ xlnx,mio-bank:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ enum: [0, 2]
+ default: 0
+ description:
+ The MIO bank number in which the command and data lines are configured.
+
+dependencies:
+ clock-output-names: [ '#clock-cells' ]
+ '#clock-cells': [ clock-output-names ]
+
+required:
+ - compatible
+ - reg
+ - interrupts
+ - clocks
+ - clock-names
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ mmc@e0100000 {
+ compatible = "arasan,sdhci-8.9a";
+ reg = <0xe0100000 0x1000>;
+ clock-names = "clk_xin", "clk_ahb";
+ clocks = <&clkc 21>, <&clkc 32>;
+ interrupt-parent = <&gic>;
+ interrupts = <0 24 4>;
+ };
+
+ - |
+ mmc@e2800000 {
+ compatible = "arasan,sdhci-5.1";
+ reg = <0xe2800000 0x1000>;
+ clock-names = "clk_xin", "clk_ahb";
+ clocks = <&cru 8>, <&cru 18>;
+ interrupt-parent = <&gic>;
+ interrupts = <0 24 4>;
+ phys = <&emmc_phy>;
+ phy-names = "phy_arasan";
+ };
+
+ - |
+ #include <dt-bindings/clock/rk3399-cru.h>
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+ #include <dt-bindings/interrupt-controller/irq.h>
+ mmc@fe330000 {
+ compatible = "rockchip,rk3399-sdhci-5.1", "arasan,sdhci-5.1";
+ reg = <0xfe330000 0x10000>;
+ interrupts = <GIC_SPI 11 IRQ_TYPE_LEVEL_HIGH>;
+ clocks = <&cru SCLK_EMMC>, <&cru ACLK_EMMC>;
+ clock-names = "clk_xin", "clk_ahb";
+ arasan,soc-ctl-syscon = <&grf>;
+ assigned-clocks = <&cru SCLK_EMMC>;
+ assigned-clock-rates = <200000000>;
+ clock-output-names = "emmc_cardclock";
+ phys = <&emmc_phy>;
+ phy-names = "phy_arasan";
+ #clock-cells = <0>;
+ };
+
+ - |
+ mmc@ff160000 {
+ compatible = "xlnx,zynqmp-8.9a", "arasan,sdhci-8.9a";
+ interrupt-parent = <&gic>;
+ interrupts = <0 48 4>;
+ reg = <0xff160000 0x1000>;
+ clocks = <&clk200>, <&clk200>;
+ clock-names = "clk_xin", "clk_ahb";
+ clock-output-names = "clk_out_sd0", "clk_in_sd0";
+ #clock-cells = <1>;
+ clk-phase-sd-hs = <63>, <72>;
+ };
+
+ - |
+ mmc@f1040000 {
+ compatible = "xlnx,versal-8.9a", "arasan,sdhci-8.9a";
+ interrupt-parent = <&gic>;
+ interrupts = <0 126 4>;
+ reg = <0xf1040000 0x10000>;
+ clocks = <&clk200>, <&clk200>;
+ clock-names = "clk_xin", "clk_ahb";
+ clock-output-names = "clk_out_sd0", "clk_in_sd0";
+ #clock-cells = <1>;
+ clk-phase-sd-hs = <132>, <60>;
+ };
+
+ - |
+ #define LGM_CLK_EMMC5
+ #define LGM_CLK_NGI
+ #define LGM_GCLK_EMMC
+ mmc@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>;
+ };
+
+ - |
+ #define LGM_CLK_SDIO
+ #define LGM_GCLK_SDXC
+ mmc@ec600000 {
+ compatible = "intel,lgm-sdhci-5.1-sdxc", "arasan,sdhci-5.1";
+ reg = <0xec600000 0x300>;
+ interrupt-parent = <&ioapic1>;
+ interrupts = <43 1>;
+ clocks = <&cgu0 LGM_CLK_SDIO>, <&cgu0 LGM_CLK_NGI>,
+ <&cgu0 LGM_GCLK_SDXC>;
+ clock-names = "clk_xin", "clk_ahb", "gate";
+ clock-output-names = "sdxc_cardclock";
+ #clock-cells = <0>;
+ phys = <&sdxc_phy>;
+ phy-names = "phy_arasan";
+ arasan,soc-ctl-syscon = <&sysconf>;
+ };
+
+ - |
+ #define KEEM_BAY_PSS_AUX_EMMC
+ #define KEEM_BAY_PSS_EMMC
+ mmc@33000000 {
+ compatible = "intel,keembay-sdhci-5.1-emmc", "arasan,sdhci-5.1";
+ interrupts = <GIC_SPI 82 IRQ_TYPE_LEVEL_HIGH>;
+ reg = <0x33000000 0x300>;
+ clock-names = "clk_xin", "clk_ahb";
+ clocks = <&scmi_clk KEEM_BAY_PSS_AUX_EMMC>,
+ <&scmi_clk KEEM_BAY_PSS_EMMC>;
+ phys = <&emmc_phy>;
+ phy-names = "phy_arasan";
+ assigned-clocks = <&scmi_clk KEEM_BAY_PSS_AUX_EMMC>;
+ assigned-clock-rates = <200000000>;
+ clock-output-names = "emmc_cardclock";
+ #clock-cells = <0>;
+ arasan,soc-ctl-syscon = <&mmc_phy_syscon>;
+ };
+
+ - |
+ #define KEEM_BAY_PSS_AUX_SD0
+ #define KEEM_BAY_PSS_SD0
+ mmc@31000000 {
+ compatible = "intel,keembay-sdhci-5.1-sd";
+ interrupts = <GIC_SPI 83 IRQ_TYPE_LEVEL_HIGH>;
+ reg = <0x31000000 0x300>;
+ clock-names = "clk_xin", "clk_ahb";
+ clocks = <&scmi_clk KEEM_BAY_PSS_AUX_SD0>,
+ <&scmi_clk KEEM_BAY_PSS_SD0>;
+ arasan,soc-ctl-syscon = <&sd0_phy_syscon>;
+ };
diff --git a/Documentation/devicetree/bindings/mmc/fsl-imx-esdhc.txt b/Documentation/devicetree/bindings/mmc/fsl-imx-esdhc.txt
deleted file mode 100644
index de1b8bd..0000000
--- a/Documentation/devicetree/bindings/mmc/fsl-imx-esdhc.txt
+++ /dev/null
@@ -1,67 +0,0 @@
-* Freescale Enhanced Secure Digital Host Controller (eSDHC) for i.MX
-
-The Enhanced Secure Digital Host Controller on Freescale i.MX family
-provides an interface for MMC, SD, and SDIO types of memory cards.
-
-This file documents differences between the core properties described
-by mmc.txt and the properties used by the sdhci-esdhc-imx driver.
-
-Required properties:
-- compatible : Should be "fsl,<chip>-esdhc", the supported chips include
- "fsl,imx25-esdhc"
- "fsl,imx35-esdhc"
- "fsl,imx51-esdhc"
- "fsl,imx53-esdhc"
- "fsl,imx6q-usdhc"
- "fsl,imx6sl-usdhc"
- "fsl,imx6sx-usdhc"
- "fsl,imx6ull-usdhc"
- "fsl,imx7d-usdhc"
- "fsl,imx7ulp-usdhc"
- "fsl,imx8mq-usdhc"
- "fsl,imx8mm-usdhc"
- "fsl,imx8mn-usdhc"
- "fsl,imx8mp-usdhc"
- "fsl,imx8qm-usdhc"
- "fsl,imx8qxp-usdhc"
-
-Optional properties:
-- fsl,wp-controller : Indicate to use controller internal write protection
-- fsl,delay-line : Specify the number of delay cells for override mode.
- This is used to set the clock delay for DLL(Delay Line) on override mode
- to select a proper data sampling window in case the clock quality is not good
- due to signal path is too long on the board. Please refer to eSDHC/uSDHC
- chapter, DLL (Delay Line) section in RM for details.
-- voltage-ranges : Specify the voltage range in case there are software
- transparent level shifters on the outputs of the controller. Two cells are
- required, first cell specifies minimum slot voltage (mV), second cell
- specifies maximum slot voltage (mV). Several ranges could be specified.
-- fsl,tuning-start-tap: Specify the start dealy cell point when send first CMD19
- in tuning procedure.
-- fsl,tuning-step: Specify the increasing delay cell steps in tuning procedure.
- The uSDHC use one delay cell as default increasing step to do tuning process.
- This property allows user to change the tuning step to more than one delay
- cells which is useful for some special boards or cards when the default
- tuning step can't find the proper delay window within limited tuning retries.
-- fsl,strobe-dll-delay-target: Specify the strobe dll control slave delay target.
- This delay target programming host controller loopback read clock, and this
- property allows user to change the delay target for the strobe input read clock.
- If not use this property, driver default set the delay target to value 7.
- Only eMMC HS400 mode need to take care of this property.
-
-Examples:
-
-esdhc@70004000 {
- compatible = "fsl,imx51-esdhc";
- reg = <0x70004000 0x4000>;
- interrupts = <1>;
- fsl,wp-controller;
-};
-
-esdhc@70008000 {
- compatible = "fsl,imx51-esdhc";
- reg = <0x70008000 0x4000>;
- interrupts = <2>;
- cd-gpios = <&gpio1 6 0>; /* GPIO1_6 */
- wp-gpios = <&gpio1 5 0>; /* GPIO1_5 */
-};
diff --git a/Documentation/devicetree/bindings/mmc/fsl-imx-esdhc.yaml b/Documentation/devicetree/bindings/mmc/fsl-imx-esdhc.yaml
new file mode 100644
index 0000000..75dc116
--- /dev/null
+++ b/Documentation/devicetree/bindings/mmc/fsl-imx-esdhc.yaml
@@ -0,0 +1,124 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/mmc/fsl-imx-esdhc.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Freescale Enhanced Secure Digital Host Controller (eSDHC) for i.MX
+
+maintainers:
+ - Shawn Guo <shawn.guo@linaro.org>
+
+allOf:
+ - $ref: "mmc-controller.yaml"
+
+description: |
+ The Enhanced Secure Digital Host Controller on Freescale i.MX family
+ provides an interface for MMC, SD, and SDIO types of memory cards.
+
+ This file documents differences between the core properties described
+ by mmc.txt and the properties used by the sdhci-esdhc-imx driver.
+
+properties:
+ compatible:
+ enum:
+ - fsl,imx25-esdhc
+ - fsl,imx35-esdhc
+ - fsl,imx51-esdhc
+ - fsl,imx53-esdhc
+ - fsl,imx6q-usdhc
+ - fsl,imx6sl-usdhc
+ - fsl,imx6sx-usdhc
+ - fsl,imx6ull-usdhc
+ - fsl,imx7d-usdhc
+ - fsl,imx7ulp-usdhc
+ - fsl,imx8mq-usdhc
+ - fsl,imx8mm-usdhc
+ - fsl,imx8mn-usdhc
+ - fsl,imx8mp-usdhc
+ - fsl,imx8qm-usdhc
+ - fsl,imx8qxp-usdhc
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+ fsl,wp-controller:
+ description: |
+ boolean, if present, indicate to use controller internal write protection.
+ type: boolean
+
+ fsl,delay-line:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description: |
+ Specify the number of delay cells for override mode.
+ This is used to set the clock delay for DLL(Delay Line) on override mode
+ to select a proper data sampling window in case the clock quality is not good
+ due to signal path is too long on the board. Please refer to eSDHC/uSDHC
+ chapter, DLL (Delay Line) section in RM for details.
+ default: 0
+
+ voltage-ranges:
+ $ref: '/schemas/types.yaml#/definitions/uint32-matrix'
+ description: |
+ Specify the voltage range in case there are software transparent level
+ shifters on the outputs of the controller. Two cells are required, first
+ cell specifies minimum slot voltage (mV), second cell specifies maximum
+ slot voltage (mV).
+ items:
+ items:
+ - description: value for minimum slot voltage
+ - description: value for maximum slot voltage
+ maxItems: 1
+
+ fsl,tuning-start-tap:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description: |
+ Specify the start delay cell point when send first CMD19 in tuning procedure.
+ default: 0
+
+ fsl,tuning-step:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description: |
+ Specify the increasing delay cell steps in tuning procedure.
+ The uSDHC use one delay cell as default increasing step to do tuning process.
+ This property allows user to change the tuning step to more than one delay
+ cells which is useful for some special boards or cards when the default
+ tuning step can't find the proper delay window within limited tuning retries.
+ default: 0
+
+ fsl,strobe-dll-delay-target:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description: |
+ Specify the strobe dll control slave delay target.
+ This delay target programming host controller loopback read clock, and this
+ property allows user to change the delay target for the strobe input read clock.
+ If not use this property, driver default set the delay target to value 7.
+ Only eMMC HS400 mode need to take care of this property.
+ default: 0
+
+required:
+ - compatible
+ - reg
+ - interrupts
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ mmc@70004000 {
+ compatible = "fsl,imx51-esdhc";
+ reg = <0x70004000 0x4000>;
+ interrupts = <1>;
+ fsl,wp-controller;
+ };
+
+ mmc@70008000 {
+ compatible = "fsl,imx51-esdhc";
+ reg = <0x70008000 0x4000>;
+ interrupts = <2>;
+ cd-gpios = <&gpio1 6 0>; /* GPIO1_6 */
+ wp-gpios = <&gpio1 5 0>; /* GPIO1_5 */
+ };
diff --git a/Documentation/devicetree/bindings/mmc/fsl-imx-mmc.txt b/Documentation/devicetree/bindings/mmc/fsl-imx-mmc.txt
deleted file mode 100644
index 184ccff..0000000
--- a/Documentation/devicetree/bindings/mmc/fsl-imx-mmc.txt
+++ /dev/null
@@ -1,23 +0,0 @@
-* Freescale Secure Digital Host Controller for i.MX2/3 series
-
-This file documents differences to the properties defined in mmc.txt.
-
-Required properties:
-- compatible : Should be "fsl,<chip>-mmc", chip can be imx21 or imx31
-
-Optional properties:
-- dmas: One DMA phandle with arguments as defined by the devicetree bindings
- of the used DMA controller.
-- dma-names: Has to be "rx-tx".
-
-Example:
-
-sdhci1: sdhci@10014000 {
- compatible = "fsl,imx27-mmc", "fsl,imx21-mmc";
- reg = <0x10014000 0x1000>;
- interrupts = <11>;
- dmas = <&dma 7>;
- dma-names = "rx-tx";
- bus-width = <4>;
- cd-gpios = <&gpio3 29>;
-};
diff --git a/Documentation/devicetree/bindings/mmc/fsl-imx-mmc.yaml b/Documentation/devicetree/bindings/mmc/fsl-imx-mmc.yaml
new file mode 100644
index 0000000..ffa1627
--- /dev/null
+++ b/Documentation/devicetree/bindings/mmc/fsl-imx-mmc.yaml
@@ -0,0 +1,53 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/mmc/fsl-imx-mmc.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Freescale Secure Digital Host Controller for i.MX2/3 series
+
+maintainers:
+ - Markus Pargmann <mpa@pengutronix.de>
+
+allOf:
+ - $ref: "mmc-controller.yaml"
+
+properties:
+ compatible:
+ oneOf:
+ - const: fsl,imx21-mmc
+ - const: fsl,imx31-mmc
+ - items:
+ - const: fsl,imx27-mmc
+ - const: fsl,imx21-mmc
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+ dmas:
+ maxItems: 1
+
+ dma-names:
+ const: rx-tx
+
+required:
+ - compatible
+ - reg
+ - interrupts
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ mmc@10014000 {
+ compatible = "fsl,imx27-mmc", "fsl,imx21-mmc";
+ reg = <0x10014000 0x1000>;
+ interrupts = <11>;
+ dmas = <&dma 7>;
+ dma-names = "rx-tx";
+ bus-width = <4>;
+ cd-gpios = <&gpio3 29>;
+ };
diff --git a/Documentation/devicetree/bindings/mmc/mmc-controller.yaml b/Documentation/devicetree/bindings/mmc/mmc-controller.yaml
index 4931fab..b96da0c 100644
--- a/Documentation/devicetree/bindings/mmc/mmc-controller.yaml
+++ b/Documentation/devicetree/bindings/mmc/mmc-controller.yaml
@@ -169,6 +169,11 @@
description:
Full power cycle of the card is supported.
+ full-pwr-cycle-in-suspend:
+ $ref: /schemas/types.yaml#/definitions/flag
+ description:
+ Full power cycle of the card in suspend is supported.
+
mmc-ddr-1_2v:
$ref: /schemas/types.yaml#/definitions/flag
description:
diff --git a/Documentation/devicetree/bindings/mmc/mmc-pwrseq-emmc.txt b/Documentation/devicetree/bindings/mmc/mmc-pwrseq-emmc.txt
deleted file mode 100644
index 3d965d5..0000000
--- a/Documentation/devicetree/bindings/mmc/mmc-pwrseq-emmc.txt
+++ /dev/null
@@ -1,25 +0,0 @@
-* The simple eMMC hardware reset provider
-
-The purpose of this driver is to perform standard eMMC hw reset
-procedure, as described by Jedec 4.4 specification. This procedure is
-performed just after MMC core enabled power to the given mmc host (to
-fix possible issues if bootloader has left eMMC card in initialized or
-unknown state), and before performing complete system reboot (also in
-case of emergency reboot call). The latter is needed on boards, which
-doesn't have hardware reset logic connected to emmc card and (limited or
-broken) ROM bootloaders are unable to read second stage from the emmc
-card if the card is left in unknown or already initialized state.
-
-Required properties:
-- compatible : contains "mmc-pwrseq-emmc".
-- reset-gpios : contains a GPIO specifier. The reset GPIO is asserted
- and then deasserted to perform eMMC card reset. To perform
- reset procedure as described in Jedec 4.4 specification, the
- gpio line should be defined as GPIO_ACTIVE_LOW.
-
-Example:
-
- sdhci0_pwrseq {
- compatible = "mmc-pwrseq-emmc";
- reset-gpios = <&gpio1 12 GPIO_ACTIVE_LOW>;
- }
diff --git a/Documentation/devicetree/bindings/mmc/mmc-pwrseq-emmc.yaml b/Documentation/devicetree/bindings/mmc/mmc-pwrseq-emmc.yaml
new file mode 100644
index 0000000..77f746f
--- /dev/null
+++ b/Documentation/devicetree/bindings/mmc/mmc-pwrseq-emmc.yaml
@@ -0,0 +1,46 @@
+# SPDX-License-Identifier: GPL-2.0
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/mmc/mmc-pwrseq-emmc.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Simple eMMC hardware reset provider binding
+
+maintainers:
+ - Ulf Hansson <ulf.hansson@linaro.org>
+
+description:
+ The purpose of this driver is to perform standard eMMC hw reset
+ procedure, as described by Jedec 4.4 specification. This procedure is
+ performed just after MMC core enabled power to the given mmc host (to
+ fix possible issues if bootloader has left eMMC card in initialized or
+ unknown state), and before performing complete system reboot (also in
+ case of emergency reboot call). The latter is needed on boards, which
+ doesn't have hardware reset logic connected to emmc card and (limited or
+ broken) ROM bootloaders are unable to read second stage from the emmc
+ card if the card is left in unknown or already initialized state.
+
+properties:
+ compatible:
+ const: mmc-pwrseq-emmc
+
+ reset-gpios:
+ minItems: 1
+ description:
+ contains a GPIO specifier. The reset GPIO is asserted
+ and then deasserted to perform eMMC card reset. To perform
+ reset procedure as described in Jedec 4.4 specification, the
+ gpio line should be defined as GPIO_ACTIVE_LOW.
+
+required:
+ - compatible
+ - reset-gpios
+
+examples:
+ - |
+ #include <dt-bindings/gpio/gpio.h>
+ sdhci0_pwrseq {
+ compatible = "mmc-pwrseq-emmc";
+ reset-gpios = <&gpio1 12 GPIO_ACTIVE_LOW>;
+ };
+...
diff --git a/Documentation/devicetree/bindings/mmc/mmc-pwrseq-sd8787.txt b/Documentation/devicetree/bindings/mmc/mmc-pwrseq-sd8787.txt
deleted file mode 100644
index 22e9340..0000000
--- a/Documentation/devicetree/bindings/mmc/mmc-pwrseq-sd8787.txt
+++ /dev/null
@@ -1,16 +0,0 @@
-* Marvell SD8787 power sequence provider
-
-Required properties:
-- compatible: must be "mmc-pwrseq-sd8787".
-- powerdown-gpios: contains a power down GPIO specifier with the
- default active state
-- reset-gpios: contains a reset GPIO specifier with the default
- active state
-
-Example:
-
- wifi_pwrseq: wifi_pwrseq {
- compatible = "mmc-pwrseq-sd8787";
- powerdown-gpios = <&twl_gpio 0 GPIO_ACTIVE_LOW>;
- reset-gpios = <&twl_gpio 1 GPIO_ACTIVE_LOW>;
- }
diff --git a/Documentation/devicetree/bindings/mmc/mmc-pwrseq-sd8787.yaml b/Documentation/devicetree/bindings/mmc/mmc-pwrseq-sd8787.yaml
new file mode 100644
index 0000000..a68820d3
--- /dev/null
+++ b/Documentation/devicetree/bindings/mmc/mmc-pwrseq-sd8787.yaml
@@ -0,0 +1,39 @@
+# SPDX-License-Identifier: GPL-2.0
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/mmc/mmc-pwrseq-sd8787.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Marvell SD8787 power sequence provider binding
+
+maintainers:
+ - Ulf Hansson <ulf.hansson@linaro.org>
+
+properties:
+ compatible:
+ const: mmc-pwrseq-sd8787
+
+ powerdown-gpios:
+ minItems: 1
+ description:
+ contains a power down GPIO specifier with the default active state
+
+ reset-gpios:
+ minItems: 1
+ description:
+ contains a reset GPIO specifier with the default active state
+
+required:
+ - compatible
+ - powerdown-gpios
+ - reset-gpios
+
+examples:
+ - |
+ #include <dt-bindings/gpio/gpio.h>
+ wifi_pwrseq: wifi_pwrseq {
+ compatible = "mmc-pwrseq-sd8787";
+ powerdown-gpios = <&twl_gpio 0 GPIO_ACTIVE_LOW>;
+ reset-gpios = <&twl_gpio 1 GPIO_ACTIVE_LOW>;
+ };
+...
diff --git a/Documentation/devicetree/bindings/mmc/mmc-pwrseq-simple.txt b/Documentation/devicetree/bindings/mmc/mmc-pwrseq-simple.txt
deleted file mode 100644
index 9029b45..0000000
--- a/Documentation/devicetree/bindings/mmc/mmc-pwrseq-simple.txt
+++ /dev/null
@@ -1,31 +0,0 @@
-* The simple MMC power sequence provider
-
-The purpose of the simple MMC power sequence provider is to supports a set of
-common properties between various SOC designs. It thus enables us to use the
-same provider for several SOC designs.
-
-Required properties:
-- compatible : contains "mmc-pwrseq-simple".
-
-Optional properties:
-- reset-gpios : contains a list of GPIO specifiers. The reset GPIOs are asserted
- at initialization and prior we start the power up procedure of the card.
- They will be de-asserted right after the power has been provided to the
- card.
-- clocks : Must contain an entry for the entry in clock-names.
- See ../clocks/clock-bindings.txt for details.
-- clock-names : Must include the following entry:
- "ext_clock" (External clock provided to the card).
-- post-power-on-delay-ms : Delay in ms after powering the card and
- de-asserting the reset-gpios (if any)
-- power-off-delay-us : Delay in us after asserting the reset-gpios (if any)
- during power off of the card.
-
-Example:
-
- sdhci0_pwrseq {
- compatible = "mmc-pwrseq-simple";
- reset-gpios = <&gpio1 12 GPIO_ACTIVE_LOW>;
- clocks = <&clk_32768_ck>;
- clock-names = "ext_clock";
- }
diff --git a/Documentation/devicetree/bindings/mmc/mmc-pwrseq-simple.yaml b/Documentation/devicetree/bindings/mmc/mmc-pwrseq-simple.yaml
new file mode 100644
index 0000000..449215444
--- /dev/null
+++ b/Documentation/devicetree/bindings/mmc/mmc-pwrseq-simple.yaml
@@ -0,0 +1,62 @@
+# SPDX-License-Identifier: GPL-2.0
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/mmc/mmc-pwrseq-simple.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Simple MMC power sequence provider binding
+
+maintainers:
+ - Ulf Hansson <ulf.hansson@linaro.org>
+
+description:
+ The purpose of the simple MMC power sequence provider is to supports a set
+ of common properties between various SOC designs. It thus enables us to use
+ the same provider for several SOC designs.
+
+properties:
+ compatible:
+ const: mmc-pwrseq-simple
+
+ reset-gpios:
+ minItems: 1
+ description:
+ contains a list of GPIO specifiers. The reset GPIOs are asserted
+ at initialization and prior we start the power up procedure of the card.
+ They will be de-asserted right after the power has been provided to the
+ card.
+
+ clocks:
+ minItems: 1
+ description: Handle for the entry in clock-names.
+
+ clock-names:
+ items:
+ - const: ext_clock
+ description: External clock provided to the card.
+
+ post-power-on-delay-ms:
+ description:
+ Delay in ms after powering the card and de-asserting the
+ reset-gpios (if any).
+ $ref: /schemas/types.yaml#/definitions/uint32
+
+ power-off-delay-us:
+ description:
+ Delay in us after asserting the reset-gpios (if any)
+ during power off of the card.
+ $ref: /schemas/types.yaml#/definitions/uint32
+
+required:
+ - compatible
+
+examples:
+ - |
+ #include <dt-bindings/gpio/gpio.h>
+ sdhci0_pwrseq {
+ compatible = "mmc-pwrseq-simple";
+ reset-gpios = <&gpio1 12 GPIO_ACTIVE_LOW>;
+ clocks = <&clk_32768_ck>;
+ clock-names = "ext_clock";
+ };
+...
diff --git a/Documentation/devicetree/bindings/mmc/mtk-sd.txt b/Documentation/devicetree/bindings/mmc/mtk-sd.txt
index 8a532f4..0c9cf6a 100644
--- a/Documentation/devicetree/bindings/mmc/mtk-sd.txt
+++ b/Documentation/devicetree/bindings/mmc/mtk-sd.txt
@@ -12,6 +12,7 @@
"mediatek,mt8173-mmc": for mmc host ip compatible with mt8173
"mediatek,mt8183-mmc": for mmc host ip compatible with mt8183
"mediatek,mt8516-mmc": for mmc host ip compatible with mt8516
+ "mediatek,mt6779-mmc": for mmc host ip compatible with mt6779
"mediatek,mt2701-mmc": for mmc host ip compatible with mt2701
"mediatek,mt2712-mmc": for mmc host ip compatible with mt2712
"mediatek,mt7622-mmc": for MT7622 SoC
diff --git a/Documentation/devicetree/bindings/mmc/mxs-mmc.txt b/Documentation/devicetree/bindings/mmc/mxs-mmc.txt
deleted file mode 100644
index 515addc..0000000
--- a/Documentation/devicetree/bindings/mmc/mxs-mmc.txt
+++ /dev/null
@@ -1,27 +0,0 @@
-* Freescale MXS MMC controller
-
-The Freescale MXS Synchronous Serial Ports (SSP) can act as a MMC controller
-to support MMC, SD, and SDIO types of memory cards.
-
-This file documents differences between the core properties in mmc.txt
-and the properties used by the mxsmmc driver.
-
-Required properties:
-- compatible: Should be "fsl,<chip>-mmc". The supported chips include
- imx23 and imx28.
-- interrupts: Should contain ERROR interrupt number
-- dmas: DMA specifier, consisting of a phandle to DMA controller node
- and SSP DMA channel ID.
- Refer to dma.txt and fsl-mxs-dma.txt for details.
-- dma-names: Must be "rx-tx".
-
-Examples:
-
-ssp0: ssp@80010000 {
- compatible = "fsl,imx28-mmc";
- reg = <0x80010000 2000>;
- interrupts = <96>;
- dmas = <&dma_apbh 0>;
- dma-names = "rx-tx";
- bus-width = <8>;
-};
diff --git a/Documentation/devicetree/bindings/mmc/mxs-mmc.yaml b/Documentation/devicetree/bindings/mmc/mxs-mmc.yaml
new file mode 100644
index 0000000..1cccc04
--- /dev/null
+++ b/Documentation/devicetree/bindings/mmc/mxs-mmc.yaml
@@ -0,0 +1,58 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/mmc/mxs-mmc.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Freescale MXS MMC controller
+
+maintainers:
+ - Shawn Guo <shawn.guo@linaro.org>
+
+description: |
+ The Freescale MXS Synchronous Serial Ports (SSP) can act as a MMC controller
+ to support MMC, SD, and SDIO types of memory cards.
+
+ This file documents differences between the core properties in mmc.txt
+ and the properties used by the mxsmmc driver.
+
+allOf:
+ - $ref: "mmc-controller.yaml"
+
+properties:
+ compatible:
+ enum:
+ - fsl,imx23-mmc
+ - fsl,imx28-mmc
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+ dmas:
+ maxItems: 1
+
+ dma-names:
+ const: rx-tx
+
+required:
+ - compatible
+ - reg
+ - interrupts
+ - dmas
+ - dma-names
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ mmc@80010000 {
+ compatible = "fsl,imx28-mmc";
+ reg = <0x80010000 2000>;
+ interrupts = <96>;
+ dmas = <&dma_apbh 0>;
+ dma-names = "rx-tx";
+ bus-width = <8>;
+ };
diff --git a/Documentation/devicetree/bindings/mmc/renesas,sdhi.txt b/Documentation/devicetree/bindings/mmc/renesas,sdhi.txt
deleted file mode 100644
index 0ca9a62..0000000
--- a/Documentation/devicetree/bindings/mmc/renesas,sdhi.txt
+++ /dev/null
@@ -1,114 +0,0 @@
-* Renesas SDHI SD/MMC controller
-
-Required properties:
-- compatible: should contain one or more of the following:
- "renesas,sdhi-sh73a0" - SDHI IP on SH73A0 SoC
- "renesas,sdhi-r7s72100" - SDHI IP on R7S72100 SoC
- "renesas,sdhi-r7s9210" - SDHI IP on R7S9210 SoC
- "renesas,sdhi-r8a73a4" - SDHI IP on R8A73A4 SoC
- "renesas,sdhi-r8a7740" - SDHI IP on R8A7740 SoC
- "renesas,sdhi-r8a7742" - SDHI IP on R8A7742 SoC
- "renesas,sdhi-r8a7743" - SDHI IP on R8A7743 SoC
- "renesas,sdhi-r8a7744" - SDHI IP on R8A7744 SoC
- "renesas,sdhi-r8a7745" - SDHI IP on R8A7745 SoC
- "renesas,sdhi-r8a774a1" - SDHI IP on R8A774A1 SoC
- "renesas,sdhi-r8a774b1" - SDHI IP on R8A774B1 SoC
- "renesas,sdhi-r8a774c0" - SDHI IP on R8A774C0 SoC
- "renesas,sdhi-r8a77470" - SDHI IP on R8A77470 SoC
- "renesas,sdhi-mmc-r8a77470" - SDHI/MMC IP on R8A77470 SoC
- "renesas,sdhi-r8a7778" - SDHI IP on R8A7778 SoC
- "renesas,sdhi-r8a7779" - SDHI IP on R8A7779 SoC
- "renesas,sdhi-r8a7790" - SDHI IP on R8A7790 SoC
- "renesas,sdhi-r8a7791" - SDHI IP on R8A7791 SoC
- "renesas,sdhi-r8a7792" - SDHI IP on R8A7792 SoC
- "renesas,sdhi-r8a7793" - SDHI IP on R8A7793 SoC
- "renesas,sdhi-r8a7794" - SDHI IP on R8A7794 SoC
- "renesas,sdhi-r8a7795" - SDHI IP on R8A7795 SoC
- "renesas,sdhi-r8a7796" - SDHI IP on R8A77960 SoC
- "renesas,sdhi-r8a77961" - SDHI IP on R8A77961 SoC
- "renesas,sdhi-r8a77965" - SDHI IP on R8A77965 SoC
- "renesas,sdhi-r8a77970" - SDHI IP on R8A77970 SoC
- "renesas,sdhi-r8a77980" - SDHI IP on R8A77980 SoC
- "renesas,sdhi-r8a77990" - SDHI IP on R8A77990 SoC
- "renesas,sdhi-r8a77995" - SDHI IP on R8A77995 SoC
- "renesas,sdhi-shmobile" - a generic sh-mobile SDHI controller
- "renesas,rcar-gen1-sdhi" - a generic R-Car Gen1 SDHI controller
- "renesas,rcar-gen2-sdhi" - a generic R-Car Gen2 and RZ/G1 SDHI
- (not SDHI/MMC) controller
- "renesas,rcar-gen3-sdhi" - a generic R-Car Gen3 or RZ/G2
- SDHI controller
-
-
- When compatible with the generic version, nodes must list
- the SoC-specific version corresponding to the platform
- first followed by the generic version.
-
-- clocks: Most controllers only have 1 clock source per channel. However, on
- some variations of this controller, the internal card detection
- logic that exists in this controller is sectioned off to be run by a
- separate second clock source to allow the main core clock to be turned
- off to save power.
- If 2 clocks are specified by the hardware, you must name them as
- "core" and "cd". If the controller only has 1 clock, naming is not
- required.
- Devices which have more than 1 clock are listed below:
- 2: R7S72100, R7S9210
-
-Optional properties:
-- pinctrl-names: should be "default", "state_uhs"
-- pinctrl-0: should contain default/high speed pin ctrl
-- pinctrl-1: should contain uhs mode pin ctrl
-
-Example: R8A7790 (R-Car H2) SDHI controller nodes
-
- sdhi0: sd@ee100000 {
- compatible = "renesas,sdhi-r8a7790", "renesas,rcar-gen2-sdhi";
- reg = <0 0xee100000 0 0x328>;
- interrupts = <GIC_SPI 165 IRQ_TYPE_LEVEL_HIGH>;
- clocks = <&cpg CPG_MOD 314>;
- dmas = <&dmac0 0xcd>, <&dmac0 0xce>,
- <&dmac1 0xcd>, <&dmac1 0xce>;
- dma-names = "tx", "rx", "tx", "rx";
- max-frequency = <195000000>;
- power-domains = <&sysc R8A7790_PD_ALWAYS_ON>;
- resets = <&cpg 314>;
- };
-
- sdhi1: sd@ee120000 {
- compatible = "renesas,sdhi-r8a7790", "renesas,rcar-gen2-sdhi";
- reg = <0 0xee120000 0 0x328>;
- interrupts = <GIC_SPI 166 IRQ_TYPE_LEVEL_HIGH>;
- clocks = <&cpg CPG_MOD 313>;
- dmas = <&dmac0 0xc9>, <&dmac0 0xca>,
- <&dmac1 0xc9>, <&dmac1 0xca>;
- dma-names = "tx", "rx", "tx", "rx";
- max-frequency = <195000000>;
- power-domains = <&sysc R8A7790_PD_ALWAYS_ON>;
- resets = <&cpg 313>;
- };
-
- sdhi2: sd@ee140000 {
- compatible = "renesas,sdhi-r8a7790", "renesas,rcar-gen2-sdhi";
- reg = <0 0xee140000 0 0x100>;
- interrupts = <GIC_SPI 167 IRQ_TYPE_LEVEL_HIGH>;
- clocks = <&cpg CPG_MOD 312>;
- dmas = <&dmac0 0xc1>, <&dmac0 0xc2>,
- <&dmac1 0xc1>, <&dmac1 0xc2>;
- dma-names = "tx", "rx", "tx", "rx";
- max-frequency = <97500000>;
- power-domains = <&sysc R8A7790_PD_ALWAYS_ON>;
- resets = <&cpg 312>;
- };
-
- sdhi3: sd@ee160000 {
- compatible = "renesas,sdhi-r8a7790", "renesas,rcar-gen2-sdhi";
- reg = <0 0xee160000 0 0x100>;
- interrupts = <GIC_SPI 168 IRQ_TYPE_LEVEL_HIGH>;
- clocks = <&cpg CPG_MOD 311>;
- dmas = <&dmac0 0xd3>, <&dmac0 0xd4>,
- <&dmac1 0xd3>, <&dmac1 0xd4>;
- dma-names = "tx", "rx", "tx", "rx";
- max-frequency = <97500000>;
- power-domains = <&sysc R8A7790_PD_ALWAYS_ON>;
- resets = <&cpg 311>;
- };
diff --git a/Documentation/devicetree/bindings/mmc/renesas,sdhi.yaml b/Documentation/devicetree/bindings/mmc/renesas,sdhi.yaml
new file mode 100644
index 0000000..e5dbc20
--- /dev/null
+++ b/Documentation/devicetree/bindings/mmc/renesas,sdhi.yaml
@@ -0,0 +1,191 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: "http://devicetree.org/schemas/mmc/renesas,sdhi.yaml#"
+$schema: "http://devicetree.org/meta-schemas/core.yaml#"
+
+title: Renesas SDHI SD/MMC controller
+
+maintainers:
+ - Wolfram Sang <wsa+renesas@sang-engineering.com>
+
+allOf:
+ - $ref: "mmc-controller.yaml"
+
+properties:
+ compatible:
+ oneOf:
+ - items:
+ - const: renesas,sdhi-sh73a0 # R-Mobile APE6
+ - items:
+ - const: renesas,sdhi-r7s72100 # RZ/A1H
+ - items:
+ - const: renesas,sdhi-r7s9210 # SH-Mobile AG5
+ - items:
+ - const: renesas,sdhi-r8a73a4 # R-Mobile APE6
+ - items:
+ - const: renesas,sdhi-r8a7740 # R-Mobile A1
+ - items:
+ - enum:
+ - renesas,sdhi-r8a7778 # R-Car M1
+ - renesas,sdhi-r8a7779 # R-Car H1
+ - const: renesas,rcar-gen1-sdhi # R-Car Gen1
+ - items:
+ - enum:
+ - renesas,sdhi-r8a7742 # RZ/G1H
+ - renesas,sdhi-r8a7743 # RZ/G1M
+ - renesas,sdhi-r8a7744 # RZ/G1N
+ - renesas,sdhi-r8a7745 # RZ/G1E
+ - renesas,sdhi-r8a77470 # RZ/G1C
+ - renesas,sdhi-r8a7790 # R-Car H2
+ - renesas,sdhi-r8a7791 # R-Car M2-W
+ - renesas,sdhi-r8a7792 # R-Car V2H
+ - renesas,sdhi-r8a7793 # R-Car M2-N
+ - renesas,sdhi-r8a7794 # R-Car E2
+ - const: renesas,rcar-gen2-sdhi # R-Car Gen2 and RZ/G1
+ - items:
+ - const: renesas,sdhi-mmc-r8a77470 # RZ/G1C (SDHI/MMC IP)
+ - items:
+ - enum:
+ - renesas,sdhi-r8a774a1 # RZ/G2M
+ - renesas,sdhi-r8a774b1 # RZ/G2N
+ - renesas,sdhi-r8a774c0 # RZ/G2E
+ - renesas,sdhi-r8a7795 # R-Car H3
+ - renesas,sdhi-r8a7796 # R-Car M3-W
+ - renesas,sdhi-r8a77961 # R-Car M3-W+
+ - renesas,sdhi-r8a77965 # R-Car M3-N
+ - renesas,sdhi-r8a77970 # R-Car V3M
+ - renesas,sdhi-r8a77980 # R-Car V3H
+ - renesas,sdhi-r8a77990 # R-Car E3
+ - renesas,sdhi-r8a77995 # R-Car D3
+ - const: renesas,rcar-gen3-sdhi # R-Car Gen3 or RZ/G2
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ minItems: 1
+ maxItems: 3
+
+ clocks:
+ minItems: 1
+ maxItems: 2
+
+ clock-names:
+ minItems: 1
+ maxItems: 2
+ items:
+ - const: core
+ - const: cd
+
+ dmas:
+ minItems: 4
+ maxItems: 4
+
+ dma-names:
+ minItems: 4
+ maxItems: 4
+ items:
+ enum:
+ - tx
+ - rx
+
+ power-domains:
+ maxItems: 1
+
+ resets:
+ maxItems: 1
+
+ pinctrl-0:
+ minItems: 1
+ maxItems: 2
+
+ pinctrl-1:
+ maxItems: 1
+
+ pinctrl-names:
+ minItems: 1
+ maxItems: 2
+ items:
+ - const: default
+ - const: state_uhs
+
+ max-frequency: true
+
+required:
+ - compatible
+ - reg
+ - interrupts
+ - clocks
+ - power-domains
+
+if:
+ properties:
+ compatible:
+ items:
+ enum:
+ - renesas,sdhi-r7s72100
+ - renesas,sdhi-r7s9210
+then:
+ required:
+ - clock-names
+ description:
+ The internal card detection logic that exists in these controllers is
+ sectioned off to be run by a separate second clock source to allow
+ the main core clock to be turned off to save power.
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/clock/r8a7790-cpg-mssr.h>
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+ #include <dt-bindings/power/r8a7790-sysc.h>
+
+ sdhi0: mmc@ee100000 {
+ compatible = "renesas,sdhi-r8a7790", "renesas,rcar-gen2-sdhi";
+ reg = <0xee100000 0x328>;
+ interrupts = <GIC_SPI 165 IRQ_TYPE_LEVEL_HIGH>;
+ clocks = <&cpg CPG_MOD 314>;
+ dmas = <&dmac0 0xcd>, <&dmac0 0xce>, <&dmac1 0xcd>, <&dmac1 0xce>;
+ dma-names = "tx", "rx", "tx", "rx";
+ max-frequency = <195000000>;
+ power-domains = <&sysc R8A7790_PD_ALWAYS_ON>;
+ resets = <&cpg 314>;
+ };
+
+ sdhi1: mmc@ee120000 {
+ compatible = "renesas,sdhi-r8a7790", "renesas,rcar-gen2-sdhi";
+ reg = <0xee120000 0x328>;
+ interrupts = <GIC_SPI 166 IRQ_TYPE_LEVEL_HIGH>;
+ clocks = <&cpg CPG_MOD 313>;
+ dmas = <&dmac0 0xc9>, <&dmac0 0xca>, <&dmac1 0xc9>, <&dmac1 0xca>;
+ dma-names = "tx", "rx", "tx", "rx";
+ max-frequency = <195000000>;
+ power-domains = <&sysc R8A7790_PD_ALWAYS_ON>;
+ resets = <&cpg 313>;
+ };
+
+ sdhi2: mmc@ee140000 {
+ compatible = "renesas,sdhi-r8a7790", "renesas,rcar-gen2-sdhi";
+ reg = <0xee140000 0x100>;
+ interrupts = <GIC_SPI 167 IRQ_TYPE_LEVEL_HIGH>;
+ clocks = <&cpg CPG_MOD 312>;
+ dmas = <&dmac0 0xc1>, <&dmac0 0xc2>, <&dmac1 0xc1>, <&dmac1 0xc2>;
+ dma-names = "tx", "rx", "tx", "rx";
+ max-frequency = <97500000>;
+ power-domains = <&sysc R8A7790_PD_ALWAYS_ON>;
+ resets = <&cpg 312>;
+ };
+
+ sdhi3: mmc@ee160000 {
+ compatible = "renesas,sdhi-r8a7790", "renesas,rcar-gen2-sdhi";
+ reg = <0xee160000 0x100>;
+ interrupts = <GIC_SPI 168 IRQ_TYPE_LEVEL_HIGH>;
+ clocks = <&cpg CPG_MOD 311>;
+ dmas = <&dmac0 0xd3>, <&dmac0 0xd4>, <&dmac1 0xd3>, <&dmac1 0xd4>;
+ dma-names = "tx", "rx", "tx", "rx";
+ max-frequency = <97500000>;
+ power-domains = <&sysc R8A7790_PD_ALWAYS_ON>;
+ resets = <&cpg 311>;
+ };
diff --git a/Documentation/devicetree/bindings/mmc/sdhci-am654.txt b/Documentation/devicetree/bindings/mmc/sdhci-am654.txt
index c6ccecb..6d202f4 100644
--- a/Documentation/devicetree/bindings/mmc/sdhci-am654.txt
+++ b/Documentation/devicetree/bindings/mmc/sdhci-am654.txt
@@ -39,6 +39,7 @@
Valid values are 33, 40, 50, 66 and 100 ohms.
Optional Properties:
- ti,strobe-sel: strobe select delay for HS400 speed mode. Default value: 0x0.
+ - ti,clkbuf-sel: Clock Delay Buffer Select
Example:
diff --git a/Documentation/devicetree/bindings/mmc/sdhci-msm.txt b/Documentation/devicetree/bindings/mmc/sdhci-msm.txt
index b8e1d2b..3b602fd 100644
--- a/Documentation/devicetree/bindings/mmc/sdhci-msm.txt
+++ b/Documentation/devicetree/bindings/mmc/sdhci-msm.txt
@@ -54,6 +54,21 @@
- qcom,dll-config: Chipset and Platform specific value. Use this field to
specify the DLL_CONFIG register value as per Hardware Programming Guide.
+Optional Properties:
+* Following bus parameters are required for interconnect bandwidth scaling:
+- interconnects: Pairs of phandles and interconnect provider specifier
+ to denote the edge source and destination ports of
+ the interconnect path.
+
+- interconnect-names: For sdhc, we have two main paths.
+ 1. Data path : sdhc to ddr
+ 2. Config path : cpu to sdhc
+ For Data interconnect path the name supposed to be
+ is "sdhc-ddr" and for config interconnect path it is
+ "cpu-sdhc".
+ Please refer to Documentation/devicetree/bindings/
+ interconnect/ for more details.
+
Example:
sdhc_1: sdhci@f9824900 {
@@ -71,6 +86,9 @@
clocks = <&gcc GCC_SDCC1_APPS_CLK>, <&gcc GCC_SDCC1_AHB_CLK>;
clock-names = "core", "iface";
+ interconnects = <&qnoc MASTER_SDCC_ID &qnoc SLAVE_DDR_ID>,
+ <&qnoc MASTER_CPU_ID &qnoc SLAVE_SDCC_ID>;
+ interconnect-names = "sdhc-ddr","cpu-sdhc";
qcom,dll-config = <0x000f642c>;
qcom,ddr-config = <0x80040868>;
diff --git a/Documentation/devicetree/bindings/mtd/davinci-nand.txt b/Documentation/devicetree/bindings/mtd/davinci-nand.txt
index cfb18ab..edebeae 100644
--- a/Documentation/devicetree/bindings/mtd/davinci-nand.txt
+++ b/Documentation/devicetree/bindings/mtd/davinci-nand.txt
@@ -4,8 +4,8 @@
NAND interface contains.
Documentation:
-Davinci DM646x - http://www.ti.com/lit/ug/sprueq7c/sprueq7c.pdf
-Kestone - http://www.ti.com/lit/ug/sprugz3a/sprugz3a.pdf
+Davinci DM646x - https://www.ti.com/lit/ug/sprueq7c/sprueq7c.pdf
+Kestone - https://www.ti.com/lit/ug/sprugz3a/sprugz3a.pdf
Required properties:
diff --git a/Documentation/devicetree/bindings/mtd/fsl-upm-nand.txt b/Documentation/devicetree/bindings/mtd/fsl-upm-nand.txt
index fce4894..25f07c1 100644
--- a/Documentation/devicetree/bindings/mtd/fsl-upm-nand.txt
+++ b/Documentation/devicetree/bindings/mtd/fsl-upm-nand.txt
@@ -7,14 +7,16 @@
- fsl,upm-cmd-offset : UPM pattern offset for the command latch.
Optional properties:
-- fsl,upm-wait-flags : add chip-dependent short delays after running the
- UPM pattern (0x1), after writing a data byte (0x2) or after
- writing out a buffer (0x4).
- fsl,upm-addr-line-cs-offsets : address offsets for multi-chip support.
The corresponding address lines are used to select the chip.
- gpios : may specify optional GPIOs connected to the Ready-Not-Busy pins
(R/B#). For multi-chip devices, "n" GPIO definitions are required
according to the number of chips.
+
+Deprecated properties:
+- fsl,upm-wait-flags : add chip-dependent short delays after running the
+ UPM pattern (0x1), after writing a data byte (0x2) or after
+ writing out a buffer (0x4).
- chip-delay : chip dependent delay for transferring data from array to
read registers (tR). Required if property "gpios" is not used
(R/B# pins not connected).
@@ -52,8 +54,6 @@
fsl,upm-cmd-offset = <0x08>;
/* Multi-chip NAND device */
fsl,upm-addr-line-cs-offsets = <0x0 0x200>;
- fsl,upm-wait-flags = <0x5>;
- chip-delay = <25>; // in micro-seconds
nand@0 {
#address-cells = <1>;
diff --git a/Documentation/devicetree/bindings/mtd/gpmi-nand.txt b/Documentation/devicetree/bindings/mtd/gpmi-nand.txt
deleted file mode 100644
index 3935883..0000000
--- a/Documentation/devicetree/bindings/mtd/gpmi-nand.txt
+++ /dev/null
@@ -1,75 +0,0 @@
-* Freescale General-Purpose Media Interface (GPMI)
-
-The GPMI nand controller provides an interface to control the
-NAND flash chips.
-
-Required properties:
- - compatible : should be "fsl,<chip>-gpmi-nand", chip can be:
- * imx23
- * imx28
- * imx6q
- * imx6sx
- * imx7d
- - reg : should contain registers location and length for gpmi and bch.
- - reg-names: Should contain the reg names "gpmi-nand" and "bch"
- - interrupts : BCH interrupt number.
- - interrupt-names : Should be "bch".
- - dmas: DMA specifier, consisting of a phandle to DMA controller node
- and GPMI DMA channel ID.
- Refer to dma.txt and fsl-mxs-dma.txt for details.
- - dma-names: Must be "rx-tx".
- - clocks : clocks phandle and clock specifier corresponding to each clock
- specified in clock-names.
- - clock-names : The "gpmi_io" clock is always required. Which clocks are
- exactly required depends on chip:
- * imx23/imx28 : "gpmi_io"
- * imx6q/sx : "gpmi_io", "gpmi_apb", "gpmi_bch", "gpmi_bch_apb", "per1_bch"
- * imx7d : "gpmi_io", "gpmi_bch_apb"
-
-Optional properties:
- - nand-on-flash-bbt: boolean to enable on flash bbt option if not
- present false
- - fsl,use-minimum-ecc: Protect this NAND flash with the minimum ECC
- strength required. The required ECC strength is
- automatically discoverable for some flash
- (e.g., according to the ONFI standard).
- However, note that if this strength is not
- discoverable or this property is not enabled,
- the software may chooses an implementation-defined
- ECC scheme.
- - fsl,no-blockmark-swap: Don't swap the bad block marker from the OOB
- area with the byte in the data area but rely on the
- flash based BBT for identifying bad blocks.
- NOTE: this is only valid in conjunction with
- 'nand-on-flash-bbt'.
- WARNING: on i.MX28 blockmark swapping cannot be
- disabled for the BootROM in the FCB. Thus,
- partitions written from Linux with this feature
- turned on may not be accessible by the BootROM
- code.
- - nand-ecc-strength: integer representing the number of bits to correct
- per ECC step. Needs to be a multiple of 2.
- - nand-ecc-step-size: integer representing the number of data bytes
- that are covered by a single ECC step. The driver
- supports 512 and 1024.
-
-The device tree may optionally contain sub-nodes describing partitions of the
-address space. See partition.txt for more detail.
-
-Examples:
-
-gpmi-nand@8000c000 {
- compatible = "fsl,imx28-gpmi-nand";
- #address-cells = <1>;
- #size-cells = <1>;
- reg = <0x8000c000 2000>, <0x8000a000 2000>;
- reg-names = "gpmi-nand", "bch";
- interrupts = <41>;
- interrupt-names = "bch";
- dmas = <&dma_apbh 4>;
- dma-names = "rx-tx";
-
- partition@0 {
- ...
- };
-};
diff --git a/Documentation/devicetree/bindings/mtd/gpmi-nand.yaml b/Documentation/devicetree/bindings/mtd/gpmi-nand.yaml
new file mode 100644
index 0000000..354cb63
--- /dev/null
+++ b/Documentation/devicetree/bindings/mtd/gpmi-nand.yaml
@@ -0,0 +1,118 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/mtd/gpmi-nand.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Freescale General-Purpose Media Interface (GPMI) binding
+
+maintainers:
+ - Han Xu <han.xu@nxp.com>
+
+allOf:
+ - $ref: "nand-controller.yaml"
+
+description: |
+ The GPMI nand controller provides an interface to control the NAND
+ flash chips. The device tree may optionally contain sub-nodes
+ describing partitions of the address space. See partition.txt for
+ more detail.
+
+properties:
+ compatible:
+ enum:
+ - fsl,imx23-gpmi-nand
+ - fsl,imx28-gpmi-nand
+ - fsl,imx6q-gpmi-nand
+ - fsl,imx6sx-gpmi-nand
+ - fsl,imx7d-gpmi-nand
+
+ reg:
+ items:
+ - description: Address and length of gpmi block.
+ - description: Address and length of bch block.
+
+ reg-names:
+ items:
+ - const: gpmi-nand
+ - const: bch
+
+ interrupts:
+ maxItems: 1
+
+ interrupt-names:
+ const: bch
+
+ dmas:
+ maxItems: 1
+
+ dma-names:
+ const: rx-tx
+
+ clocks:
+ minItems: 1
+ maxItems: 5
+ items:
+ - description: SoC gpmi io clock
+ - description: SoC gpmi apb clock
+ - description: SoC gpmi bch clock
+ - description: SoC gpmi bch apb clock
+ - description: SoC per1 bch clock
+
+ clock-names:
+ minItems: 1
+ maxItems: 5
+ items:
+ - const: gpmi_io
+ - const: gpmi_apb
+ - const: gpmi_bch
+ - const: gpmi_bch_apb
+ - const: per1_bch
+
+ fsl,use-minimum-ecc:
+ type: boolean
+ description: |
+ Protect this NAND flash with the minimum ECC strength required.
+ The required ECC strength is automatically discoverable for some
+ flash (e.g., according to the ONFI standard). However, note that
+ if this strength is not discoverable or this property is not enabled,
+ the software may chooses an implementation-defined ECC scheme.
+
+ fsl,no-blockmark-swap:
+ type: boolean
+ description: |
+ Don't swap the bad block marker from the OOB area with the byte in
+ the data area but rely on the flash based BBT for identifying bad blocks.
+ NOTE: this is only valid in conjunction with 'nand-on-flash-bbt'.
+ WARNING: on i.MX28 blockmark swapping cannot be disabled for the BootROM
+ in the FCB. Thus, partitions written from Linux with this feature turned
+ on may not be accessible by the BootROM code.
+
+required:
+ - compatible
+ - reg
+ - reg-names
+ - interrupts
+ - interrupt-names
+ - clocks
+ - clock-names
+ - dmas
+ - dma-names
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ nand-controller@8000c000 {
+ #address-cells = <1>;
+ #size-cells = <0>;
+ compatible = "fsl,imx28-gpmi-nand";
+ reg = <0x8000c000 0x2000>, <0x8000a000 0x2000>;
+ reg-names = "gpmi-nand", "bch";
+ interrupts = <41>;
+ interrupt-names = "bch";
+ clocks = <&clks 50>;
+ clock-names = "gpmi_io";
+ dmas = <&dma_apbh 4>;
+ dma-names = "rx-tx";
+ };
diff --git a/Documentation/devicetree/bindings/mtd/mxc-nand.txt b/Documentation/devicetree/bindings/mtd/mxc-nand.txt
deleted file mode 100644
index 2857c62..0000000
--- a/Documentation/devicetree/bindings/mtd/mxc-nand.txt
+++ /dev/null
@@ -1,19 +0,0 @@
-* Freescale's mxc_nand
-
-Required properties:
-- compatible: "fsl,imxXX-nand"
-- reg: address range of the nfc block
-- interrupts: irq to be used
-- nand-bus-width: see nand-controller.yaml
-- nand-ecc-mode: see nand-controller.yaml
-- nand-on-flash-bbt: see nand-controller.yaml
-
-Example:
-
- nand@d8000000 {
- compatible = "fsl,imx27-nand";
- reg = <0xd8000000 0x1000>;
- interrupts = <29>;
- nand-bus-width = <8>;
- nand-ecc-mode = "hw";
- };
diff --git a/Documentation/devicetree/bindings/mtd/mxc-nand.yaml b/Documentation/devicetree/bindings/mtd/mxc-nand.yaml
new file mode 100644
index 0000000..ee4d1d0
--- /dev/null
+++ b/Documentation/devicetree/bindings/mtd/mxc-nand.yaml
@@ -0,0 +1,42 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/mtd/mxc-nand.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Freescale's mxc_nand binding
+
+maintainers:
+ - Uwe Kleine-König <u.kleine-koenig@pengutronix.de>
+
+allOf:
+ - $ref: "nand-controller.yaml"
+
+properties:
+ compatible:
+ const: fsl,imx27-nand
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+required:
+ - compatible
+ - reg
+ - interrupts
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ nand-controller@d8000000 {
+ #address-cells = <1>;
+ #size-cells = <0>;
+ compatible = "fsl,imx27-nand";
+ reg = <0xd8000000 0x1000>;
+ interrupts = <29>;
+ nand-bus-width = <8>;
+ nand-ecc-mode = "hw";
+ };
diff --git a/Documentation/devicetree/bindings/mtd/nand-controller.yaml b/Documentation/devicetree/bindings/mtd/nand-controller.yaml
index cde7c4d..40fc5b0 100644
--- a/Documentation/devicetree/bindings/mtd/nand-controller.yaml
+++ b/Documentation/devicetree/bindings/mtd/nand-controller.yaml
@@ -114,6 +114,13 @@
description:
Contains the native Ready/Busy IDs.
+ rb-gpios:
+ description:
+ Contains one or more GPIO descriptor (the numper of descriptor
+ depends on the number of R/B pins exposed by the flash) for the
+ Ready/Busy pins. Active state refers to the NAND ready state and
+ should be set to GPIOD_ACTIVE_HIGH unless the signal is inverted.
+
required:
- reg
diff --git a/Documentation/devicetree/bindings/mtd/st,stm32-fmc2-nand.yaml b/Documentation/devicetree/bindings/mtd/st,stm32-fmc2-nand.yaml
index b059267..6ae7de1 100644
--- a/Documentation/devicetree/bindings/mtd/st,stm32-fmc2-nand.yaml
+++ b/Documentation/devicetree/bindings/mtd/st,stm32-fmc2-nand.yaml
@@ -9,32 +9,19 @@
maintainers:
- Christophe Kerello <christophe.kerello@st.com>
-allOf:
- - $ref: "nand-controller.yaml#"
-
properties:
compatible:
- const: st,stm32mp15-fmc2
+ enum:
+ - st,stm32mp15-fmc2
+ - st,stm32mp1-fmc2-nfc
reg:
- items:
- - description: Registers
- - description: Chip select 0 data
- - description: Chip select 0 command
- - description: Chip select 0 address space
- - description: Chip select 1 data
- - description: Chip select 1 command
- - description: Chip select 1 address space
+ minItems: 6
+ maxItems: 7
interrupts:
maxItems: 1
- clocks:
- maxItems: 1
-
- resets:
- maxItems: 1
-
dmas:
items:
- description: tx DMA channel
@@ -57,11 +44,55 @@
nand-ecc-strength:
enum: [1, 4 ,8 ]
+allOf:
+ - $ref: "nand-controller.yaml#"
+
+ - if:
+ properties:
+ compatible:
+ contains:
+ const: st,stm32mp15-fmc2
+ then:
+ properties:
+ reg:
+ items:
+ - description: Registers
+ - description: Chip select 0 data
+ - description: Chip select 0 command
+ - description: Chip select 0 address space
+ - description: Chip select 1 data
+ - description: Chip select 1 command
+ - description: Chip select 1 address space
+
+ clocks:
+ maxItems: 1
+
+ resets:
+ maxItems: 1
+
+ required:
+ - clocks
+
+ - if:
+ properties:
+ compatible:
+ contains:
+ const: st,stm32mp1-fmc2-nfc
+ then:
+ properties:
+ reg:
+ items:
+ - description: Chip select 0 data
+ - description: Chip select 0 command
+ - description: Chip select 0 address space
+ - description: Chip select 1 data
+ - description: Chip select 1 command
+ - description: Chip select 1 address space
+
required:
- compatible
- reg
- interrupts
- - clocks
examples:
- |
@@ -77,13 +108,13 @@
<0x81000000 0x1000>,
<0x89010000 0x1000>,
<0x89020000 0x1000>;
- interrupts = <GIC_SPI 48 IRQ_TYPE_LEVEL_HIGH>;
- dmas = <&mdma1 20 0x10 0x12000a02 0x0 0x0>,
- <&mdma1 20 0x10 0x12000a08 0x0 0x0>,
- <&mdma1 21 0x10 0x12000a0a 0x0 0x0>;
- dma-names = "tx", "rx", "ecc";
- clocks = <&rcc FMC_K>;
- resets = <&rcc FMC_R>;
+ interrupts = <GIC_SPI 48 IRQ_TYPE_LEVEL_HIGH>;
+ dmas = <&mdma1 20 0x2 0x12000a02 0x0 0x0>,
+ <&mdma1 20 0x2 0x12000a08 0x0 0x0>,
+ <&mdma1 21 0x2 0x12000a0a 0x0 0x0>;
+ dma-names = "tx", "rx", "ecc";
+ clocks = <&rcc FMC_K>;
+ resets = <&rcc FMC_R>;
#address-cells = <1>;
#size-cells = <0>;
diff --git a/Documentation/devicetree/bindings/net/amlogic,meson-dwmac.yaml b/Documentation/devicetree/bindings/net/amlogic,meson-dwmac.yaml
index 64c20c9..85fefe3 100644
--- a/Documentation/devicetree/bindings/net/amlogic,meson-dwmac.yaml
+++ b/Documentation/devicetree/bindings/net/amlogic,meson-dwmac.yaml
@@ -22,6 +22,7 @@
- amlogic,meson8m2-dwmac
- amlogic,meson-gxbb-dwmac
- amlogic,meson-axg-dwmac
+ - amlogic,meson-g12a-dwmac
required:
- compatible
@@ -36,6 +37,7 @@
- amlogic,meson8m2-dwmac
- amlogic,meson-gxbb-dwmac
- amlogic,meson-axg-dwmac
+ - amlogic,meson-g12a-dwmac
then:
properties:
@@ -95,6 +97,7 @@
- amlogic,meson8m2-dwmac
- amlogic,meson-gxbb-dwmac
- amlogic,meson-axg-dwmac
+ - amlogic,meson-g12a-dwmac
contains:
enum:
- snps,dwmac-3.70a
diff --git a/Documentation/devicetree/bindings/net/dsa/dsa.txt b/Documentation/devicetree/bindings/net/dsa/dsa.txt
index f66bb7e..bf7328a 100644
--- a/Documentation/devicetree/bindings/net/dsa/dsa.txt
+++ b/Documentation/devicetree/bindings/net/dsa/dsa.txt
@@ -1,257 +1,4 @@
Distributed Switch Architecture Device Tree Bindings
----------------------------------------------------
-Switches are true Linux devices and can be probed by any means. Once
-probed, they register to the DSA framework, passing a node
-pointer. This node is expected to fulfil the following binding, and
-may contain additional properties as required by the device it is
-embedded within.
-
-Required properties:
-
-- ports : A container for child nodes representing switch ports.
-
-Optional properties:
-
-- dsa,member : A two element list indicates which DSA cluster, and position
- within the cluster a switch takes. <0 0> is cluster 0,
- switch 0. <0 1> is cluster 0, switch 1. <1 0> is cluster 1,
- switch 0. A switch not part of any cluster (single device
- hanging off a CPU port) must not specify this property
-
-The ports container has the following properties
-
-Required properties:
-
-- #address-cells : Must be 1
-- #size-cells : Must be 0
-
-Each port children node must have the following mandatory properties:
-- reg : Describes the port address in the switch
-
-An uplink/downlink port between switches in the cluster has the following
-mandatory property:
-
-- link : Should be a list of phandles to other switch's DSA
- port. This port is used as the outgoing port
- towards the phandle ports. The full routing
- information must be given, not just the one hop
- routes to neighbouring switches.
-
-A CPU port has the following mandatory property:
-
-- ethernet : Should be a phandle to a valid Ethernet device node.
- This host device is what the switch port is
- connected to.
-
-A user port has the following optional property:
-
-- label : Describes the label associated with this port, which
- will become the netdev name.
-
-Port child nodes may also contain the following optional standardised
-properties, described in binding documents:
-
-- phy-handle : Phandle to a PHY on an MDIO bus. See
- Documentation/devicetree/bindings/net/ethernet.txt
- for details.
-
-- phy-mode : See
- Documentation/devicetree/bindings/net/ethernet.txt
- for details.
-
-- fixed-link : Fixed-link subnode describing a link to a non-MDIO
- managed entity. See
- Documentation/devicetree/bindings/net/fixed-link.txt
- for details.
-
-The MAC address will be determined using the optional properties
-defined in ethernet.txt.
-
-Example
-
-The following example shows three switches on three MDIO busses,
-linked into one DSA cluster.
-
-&mdio1 {
- #address-cells = <1>;
- #size-cells = <0>;
-
- switch0: switch0@0 {
- compatible = "marvell,mv88e6085";
- reg = <0>;
-
- dsa,member = <0 0>;
-
- ports {
- #address-cells = <1>;
- #size-cells = <0>;
- port@0 {
- reg = <0>;
- label = "lan0";
- };
-
- port@1 {
- reg = <1>;
- label = "lan1";
- local-mac-address = [00 00 00 00 00 00];
- };
-
- port@2 {
- reg = <2>;
- label = "lan2";
- };
-
- switch0port5: port@5 {
- reg = <5>;
- phy-mode = "rgmii-txid";
- link = <&switch1port6
- &switch2port9>;
- fixed-link {
- speed = <1000>;
- full-duplex;
- };
- };
-
- port@6 {
- reg = <6>;
- ethernet = <&fec1>;
- fixed-link {
- speed = <100>;
- full-duplex;
- };
- };
- };
- };
-};
-
-&mdio2 {
- #address-cells = <1>;
- #size-cells = <0>;
-
- switch1: switch1@0 {
- compatible = "marvell,mv88e6085";
- reg = <0>;
-
- dsa,member = <0 1>;
-
- ports {
- #address-cells = <1>;
- #size-cells = <0>;
- port@0 {
- reg = <0>;
- label = "lan3";
- phy-handle = <&switch1phy0>;
- };
-
- port@1 {
- reg = <1>;
- label = "lan4";
- phy-handle = <&switch1phy1>;
- };
-
- port@2 {
- reg = <2>;
- label = "lan5";
- phy-handle = <&switch1phy2>;
- };
-
- switch1port5: port@5 {
- reg = <5>;
- link = <&switch2port9>;
- phy-mode = "rgmii-txid";
- fixed-link {
- speed = <1000>;
- full-duplex;
- };
- };
-
- switch1port6: port@6 {
- reg = <6>;
- phy-mode = "rgmii-txid";
- link = <&switch0port5>;
- fixed-link {
- speed = <1000>;
- full-duplex;
- };
- };
- };
- mdio-bus {
- #address-cells = <1>;
- #size-cells = <0>;
- switch1phy0: switch1phy0@0 {
- reg = <0>;
- };
- switch1phy1: switch1phy0@1 {
- reg = <1>;
- };
- switch1phy2: switch1phy0@2 {
- reg = <2>;
- };
- };
- };
-};
-
-&mdio4 {
- #address-cells = <1>;
- #size-cells = <0>;
-
- switch2: switch2@0 {
- compatible = "marvell,mv88e6085";
- reg = <0>;
-
- dsa,member = <0 2>;
-
- ports {
- #address-cells = <1>;
- #size-cells = <0>;
- port@0 {
- reg = <0>;
- label = "lan6";
- };
-
- port@1 {
- reg = <1>;
- label = "lan7";
- };
-
- port@2 {
- reg = <2>;
- label = "lan8";
- };
-
- port@3 {
- reg = <3>;
- label = "optical3";
- fixed-link {
- speed = <1000>;
- full-duplex;
- link-gpios = <&gpio6 2
- GPIO_ACTIVE_HIGH>;
- };
- };
-
- port@4 {
- reg = <4>;
- label = "optical4";
- fixed-link {
- speed = <1000>;
- full-duplex;
- link-gpios = <&gpio6 3
- GPIO_ACTIVE_HIGH>;
- };
- };
-
- switch2port9: port@9 {
- reg = <9>;
- phy-mode = "rgmii-txid";
- link = <&switch1port5
- &switch0port5>;
- fixed-link {
- speed = <1000>;
- full-duplex;
- };
- };
- };
- };
-};
+See Documentation/devicetree/bindings/net/dsa/dsa.yaml for the documenation.
diff --git a/Documentation/devicetree/bindings/net/dsa/dsa.yaml b/Documentation/devicetree/bindings/net/dsa/dsa.yaml
new file mode 100644
index 0000000..faea214
--- /dev/null
+++ b/Documentation/devicetree/bindings/net/dsa/dsa.yaml
@@ -0,0 +1,92 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/net/dsa/dsa.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Ethernet Switch Device Tree Bindings
+
+maintainers:
+ - Andrew Lunn <andrew@lunn.ch>
+ - Florian Fainelli <f.fainelli@gmail.com>
+ - Vivien Didelot <vivien.didelot@gmail.com>
+
+description:
+ This binding represents Ethernet Switches which have a dedicated CPU
+ port. That port is usually connected to an Ethernet Controller of the
+ SoC. Such setups are typical for embedded devices.
+
+select: false
+
+properties:
+ $nodename:
+ pattern: "^switch(@.*)?$"
+
+ dsa,member:
+ minItems: 2
+ maxItems: 2
+ description:
+ A two element list indicates which DSA cluster, and position within the
+ cluster a switch takes. <0 0> is cluster 0, switch 0. <0 1> is cluster 0,
+ switch 1. <1 0> is cluster 1, switch 0. A switch not part of any cluster
+ (single device hanging off a CPU port) must not specify this property
+ $ref: /schemas/types.yaml#/definitions/uint32-array
+
+patternProperties:
+ "^(ethernet-)?ports$":
+ type: object
+ properties:
+ '#address-cells':
+ const: 1
+ '#size-cells':
+ const: 0
+
+ patternProperties:
+ "^(ethernet-)?port@[0-9]+$":
+ type: object
+ description: Ethernet switch ports
+
+ properties:
+ reg:
+ description: Port number
+
+ label:
+ description:
+ Describes the label associated with this port, which will become
+ the netdev name
+ $ref: /schemas/types.yaml#definitions/string
+
+ link:
+ description:
+ Should be a list of phandles to other switch's DSA port. This
+ port is used as the outgoing port towards the phandle ports. The
+ full routing information must be given, not just the one hop
+ routes to neighbouring switches
+ $ref: /schemas/types.yaml#definitions/phandle-array
+
+ ethernet:
+ description:
+ Should be a phandle to a valid Ethernet device node. This host
+ device is what the switch port is connected to
+ $ref: /schemas/types.yaml#definitions/phandle
+
+ phy-handle: true
+
+ phy-mode: true
+
+ fixed-link: true
+
+ mac-address: true
+
+ required:
+ - reg
+
+ additionalProperties: false
+
+oneOf:
+ - required:
+ - ports
+ - required:
+ - ethernet-ports
+
+...
diff --git a/Documentation/devicetree/bindings/net/dsa/ocelot.txt b/Documentation/devicetree/bindings/net/dsa/ocelot.txt
index 66a129f..7a271d0 100644
--- a/Documentation/devicetree/bindings/net/dsa/ocelot.txt
+++ b/Documentation/devicetree/bindings/net/dsa/ocelot.txt
@@ -4,10 +4,15 @@
Felix
-----
-The VSC9959 core is currently the only switch supported by the driver, and is
-found in the NXP LS1028A. It is a PCI device, part of the larger ENETC root
-complex. As a result, the ethernet-switch node is a sub-node of the PCIe root
-complex node and its "reg" property conforms to the parent node bindings:
+Currently the switches supported by the felix driver are:
+
+- VSC9959 (Felix)
+- VSC9953 (Seville)
+
+The VSC9959 switch is found in the NXP LS1028A. It is a PCI device, part of the
+larger ENETC root complex. As a result, the ethernet-switch node is a sub-node
+of the PCIe root complex node and its "reg" property conforms to the parent
+node bindings:
* reg: Specifies PCIe Device Number and Function Number of the endpoint device,
in this case for the Ethernet L2Switch it is PF5 (of device 0, bus 0).
@@ -114,3 +119,95 @@
};
};
};
+
+The VSC9953 switch is found inside NXP T1040. It is a platform device with the
+following required properties:
+
+- compatible:
+ Must be "mscc,vsc9953-switch".
+
+Supported PHY interface types (appropriate SerDes protocol setting changes are
+needed in the RCW binary):
+
+* phy_mode = "internal": on ports 8 and 9
+* phy_mode = "sgmii": on ports 0, 1, 2, 3, 4, 5, 6, 7
+* phy_mode = "qsgmii": on ports 0, 1, 2, 3, 4, 5, 6, 7
+
+Example:
+
+&soc {
+ ethernet-switch@800000 {
+ #address-cells = <0x1>;
+ #size-cells = <0x0>;
+ compatible = "mscc,vsc9953-switch";
+ little-endian;
+ reg = <0x800000 0x290000>;
+
+ ports {
+ #address-cells = <0x1>;
+ #size-cells = <0x0>;
+
+ port@0 {
+ reg = <0x0>;
+ label = "swp0";
+ };
+
+ port@1 {
+ reg = <0x1>;
+ label = "swp1";
+ };
+
+ port@2 {
+ reg = <0x2>;
+ label = "swp2";
+ };
+
+ port@3 {
+ reg = <0x3>;
+ label = "swp3";
+ };
+
+ port@4 {
+ reg = <0x4>;
+ label = "swp4";
+ };
+
+ port@5 {
+ reg = <0x5>;
+ label = "swp5";
+ };
+
+ port@6 {
+ reg = <0x6>;
+ label = "swp6";
+ };
+
+ port@7 {
+ reg = <0x7>;
+ label = "swp7";
+ };
+
+ port@8 {
+ reg = <0x8>;
+ phy-mode = "internal";
+ ethernet = <&enet0>;
+
+ fixed-link {
+ speed = <2500>;
+ full-duplex;
+ };
+ };
+
+ port@9 {
+ reg = <0x9>;
+ phy-mode = "internal";
+ status = "disabled";
+
+ fixed-link {
+ speed = <2500>;
+ full-duplex;
+ };
+ };
+ };
+ };
+};
diff --git a/Documentation/devicetree/bindings/net/ethernet-phy.yaml b/Documentation/devicetree/bindings/net/ethernet-phy.yaml
index 9b1f114..a9e547a 100644
--- a/Documentation/devicetree/bindings/net/ethernet-phy.yaml
+++ b/Documentation/devicetree/bindings/net/ethernet-phy.yaml
@@ -162,6 +162,18 @@
description:
Specifies a reference to a node representing a SFP cage.
+ rx-internal-delay-ps:
+ description: |
+ RGMII Receive PHY Clock Delay defined in pico seconds. This is used for
+ PHY's that have configurable RX internal delays. If this property is
+ present then the PHY applies the RX delay.
+
+ tx-internal-delay-ps:
+ description: |
+ RGMII Transmit PHY Clock Delay defined in pico seconds. This is used for
+ PHY's that have configurable TX internal delays. If this property is
+ present then the PHY applies the TX delay.
+
required:
- reg
diff --git a/Documentation/devicetree/bindings/net/mdio.yaml b/Documentation/devicetree/bindings/net/mdio.yaml
index d6a3bf8..26afb55 100644
--- a/Documentation/devicetree/bindings/net/mdio.yaml
+++ b/Documentation/devicetree/bindings/net/mdio.yaml
@@ -39,6 +39,13 @@
and must therefore be appropriately determined based on all devices
requirements (maximum value of all per-device RESET pulse widths).
+ reset-post-delay-us:
+ description:
+ Delay after reset deassert in microseconds. It applies to all MDIO
+ devices and it's determined by how fast all devices are ready for
+ communication. This delay happens just before e.g. Ethernet PHY
+ type ID auto detection.
+
clock-frequency:
description:
Desired MDIO bus clock frequency in Hz. Values greater than IEEE 802.3
diff --git a/Documentation/devicetree/bindings/net/mediatek-bluetooth.txt b/Documentation/devicetree/bindings/net/mediatek-bluetooth.txt
index 219bcbd..9ef5bac 100644
--- a/Documentation/devicetree/bindings/net/mediatek-bluetooth.txt
+++ b/Documentation/devicetree/bindings/net/mediatek-bluetooth.txt
@@ -3,7 +3,7 @@
This device is a serial attached device to BTIF device and thus it must be a
child node of the serial node with BTIF. The dt-bindings details for BTIF
-device can be known via Documentation/devicetree/bindings/serial/8250.txt.
+device can be known via Documentation/devicetree/bindings/serial/8250.yaml.
Required properties:
diff --git a/Documentation/devicetree/bindings/net/mscc-phy-vsc8531.txt b/Documentation/devicetree/bindings/net/mscc-phy-vsc8531.txt
index 5ff37c6..87a27d7 100644
--- a/Documentation/devicetree/bindings/net/mscc-phy-vsc8531.txt
+++ b/Documentation/devicetree/bindings/net/mscc-phy-vsc8531.txt
@@ -31,6 +31,8 @@
VSC8531_LINK_100_ACTIVITY (2),
VSC8531_LINK_ACTIVITY (0) and
VSC8531_DUPLEX_COLLISION (8).
+- load-save-gpios : GPIO used for the load/save operation of the PTP
+ hardware clock (PHC).
Table: 1 - Edge rate change
@@ -67,4 +69,5 @@
vsc8531,edge-slowdown = <7>;
vsc8531,led-0-mode = <LINK_1000_ACTIVITY>;
vsc8531,led-1-mode = <LINK_100_ACTIVITY>;
+ load-save-gpios = <&gpio 10 GPIO_ACTIVE_HIGH>;
};
diff --git a/Documentation/devicetree/bindings/net/realtek-bluetooth.yaml b/Documentation/devicetree/bindings/net/realtek-bluetooth.yaml
index f15a5e5..c488f24ed 100644
--- a/Documentation/devicetree/bindings/net/realtek-bluetooth.yaml
+++ b/Documentation/devicetree/bindings/net/realtek-bluetooth.yaml
@@ -44,7 +44,7 @@
uart1 {
pinctrl-names = "default";
pinctrl-0 = <&uart1_pins>, <&uart1_rts_cts_pins>;
- uart-has-rtscts = <1>;
+ uart-has-rtscts;
bluetooth {
compatible = "realtek,rtl8723bs-bt";
diff --git a/Documentation/devicetree/bindings/net/ti,dp83867.yaml b/Documentation/devicetree/bindings/net/ti,dp83867.yaml
index 554dcd7..c6716ac 100644
--- a/Documentation/devicetree/bindings/net/ti,dp83867.yaml
+++ b/Documentation/devicetree/bindings/net/ti,dp83867.yaml
@@ -24,7 +24,7 @@
IEEE 802.3 Standard Media Independent Interface (MII), the IEEE 802.3 Gigabit
Media Independent Interface (GMII) or Reduced GMII (RGMII).
- Specifications about the charger can be found at:
+ Specifications about the Ethernet PHY can be found at:
https://www.ti.com/lit/gpn/dp83867ir
properties:
diff --git a/Documentation/devicetree/bindings/net/ti,dp83869.yaml b/Documentation/devicetree/bindings/net/ti,dp83869.yaml
index 5b69ef0..cf40b46 100644
--- a/Documentation/devicetree/bindings/net/ti,dp83869.yaml
+++ b/Documentation/devicetree/bindings/net/ti,dp83869.yaml
@@ -8,7 +8,7 @@
title: TI DP83869 ethernet PHY
allOf:
- - $ref: "ethernet-controller.yaml#"
+ - $ref: "ethernet-phy.yaml#"
maintainers:
- Dan Murphy <dmurphy@ti.com>
@@ -24,7 +24,7 @@
conversions. The DP83869HM can also support Bridge Conversion from RGMII to
SGMII and SGMII to RGMII.
- Specifications about the charger can be found at:
+ Specifications about the Ethernet PHY can be found at:
http://www.ti.com/lit/ds/symlink/dp83869hm.pdf
properties:
@@ -64,6 +64,18 @@
Operational mode for the PHY. If this is not set then the operational
mode is set by the straps. see dt-bindings/net/ti-dp83869.h for values
+ rx-internal-delay-ps:
+ description: Delay is in pico seconds
+ enum: [ 250, 500, 750, 1000, 1250, 1500, 1750, 2000, 2250, 2500, 2750, 3000,
+ 3250, 3500, 3750, 4000 ]
+ default: 2000
+
+ tx-internal-delay-ps:
+ description: Delay is in pico seconds
+ enum: [ 250, 500, 750, 1000, 1250, 1500, 1750, 2000, 2250, 2500, 2750, 3000,
+ 3250, 3500, 3750, 4000 ]
+ default: 2000
+
required:
- reg
@@ -80,5 +92,7 @@
ti,op-mode = <DP83869_RGMII_COPPER_ETHERNET>;
ti,max-output-impedance = "true";
ti,clk-output-sel = <DP83869_CLK_O_SEL_CHN_A_RCLK>;
+ rx-internal-delay-ps = <2000>;
+ tx-internal-delay-ps = <2000>;
};
};
diff --git a/drivers/staging/wilc1000/microchip,wilc1000.yaml b/Documentation/devicetree/bindings/net/wireless/microchip,wilc1000.yaml
similarity index 100%
rename from drivers/staging/wilc1000/microchip,wilc1000.yaml
rename to Documentation/devicetree/bindings/net/wireless/microchip,wilc1000.yaml
diff --git a/Documentation/devicetree/bindings/nvmem/allwinner,sun4i-a10-sid.yaml b/Documentation/devicetree/bindings/nvmem/allwinner,sun4i-a10-sid.yaml
index daf1321..6687ab7 100644
--- a/Documentation/devicetree/bindings/nvmem/allwinner,sun4i-a10-sid.yaml
+++ b/Documentation/devicetree/bindings/nvmem/allwinner,sun4i-a10-sid.yaml
@@ -15,14 +15,17 @@
properties:
compatible:
- enum:
- - allwinner,sun4i-a10-sid
- - allwinner,sun7i-a20-sid
- - allwinner,sun8i-a83t-sid
- - allwinner,sun8i-h3-sid
- - allwinner,sun50i-a64-sid
- - allwinner,sun50i-h5-sid
- - allwinner,sun50i-h6-sid
+ oneOf:
+ - const: allwinner,sun4i-a10-sid
+ - const: allwinner,sun7i-a20-sid
+ - const: allwinner,sun8i-a83t-sid
+ - const: allwinner,sun8i-h3-sid
+ - const: allwinner,sun50i-a64-sid
+ - items:
+ - const: allwinner,sun50i-a100-sid
+ - const: allwinner,sun50i-a64-sid
+ - const: allwinner,sun50i-h5-sid
+ - const: allwinner,sun50i-h6-sid
reg:
maxItems: 1
diff --git a/Documentation/devicetree/bindings/nvmem/qcom,qfprom.yaml b/Documentation/devicetree/bindings/nvmem/qcom,qfprom.yaml
new file mode 100644
index 0000000..d10a0cf
--- /dev/null
+++ b/Documentation/devicetree/bindings/nvmem/qcom,qfprom.yaml
@@ -0,0 +1,96 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/nvmem/qcom,qfprom.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Qualcomm Technologies Inc, QFPROM Efuse bindings
+
+maintainers:
+ - Srinivas Kandagatla <srinivas.kandagatla@linaro.org>
+
+allOf:
+ - $ref: "nvmem.yaml#"
+
+properties:
+ compatible:
+ const: qcom,qfprom
+
+ reg:
+ # If the QFPROM is read-only OS image then only the corrected region
+ # needs to be provided. If the QFPROM is writable then all 4 regions
+ # must be provided.
+ oneOf:
+ - items:
+ - description: The corrected region.
+ - items:
+ - description: The corrected region.
+ - description: The raw region.
+ - description: The config region.
+ - description: The security control region.
+
+ # Clock must be provided if QFPROM is writable from the OS image.
+ clocks:
+ maxItems: 1
+ clock-names:
+ const: core
+
+ # Supply reference must be provided if QFPROM is writable from the OS image.
+ vcc-supply:
+ description: Our power supply.
+
+ # Needed if any child nodes are present.
+ "#address-cells":
+ const: 1
+ "#size-cells":
+ const: 1
+
+required:
+ - compatible
+ - reg
+
+examples:
+ - |
+ #include <dt-bindings/clock/qcom,gcc-sc7180.h>
+
+ soc {
+ #address-cells = <2>;
+ #size-cells = <2>;
+
+ efuse@784000 {
+ compatible = "qcom,qfprom";
+ reg = <0 0x00784000 0 0x8ff>,
+ <0 0x00780000 0 0x7a0>,
+ <0 0x00782000 0 0x100>,
+ <0 0x00786000 0 0x1fff>;
+ clocks = <&gcc GCC_SEC_CTRL_CLK_SRC>;
+ clock-names = "core";
+ #address-cells = <1>;
+ #size-cells = <1>;
+
+ vcc-supply = <&vreg_l11a_1p8>;
+
+ hstx-trim-primary@25b {
+ reg = <0x25b 0x1>;
+ bits = <1 3>;
+ };
+ };
+ };
+
+ - |
+ soc {
+ #address-cells = <2>;
+ #size-cells = <2>;
+
+ efuse@784000 {
+ compatible = "qcom,qfprom";
+ reg = <0 0x00784000 0 0x8ff>;
+ #address-cells = <1>;
+ #size-cells = <1>;
+
+ hstx-trim-primary@1eb {
+ reg = <0x1eb 0x1>;
+ bits = <1 4>;
+ };
+ };
+ };
diff --git a/Documentation/devicetree/bindings/nvmem/qfprom.txt b/Documentation/devicetree/bindings/nvmem/qfprom.txt
deleted file mode 100644
index 26fe878..0000000
--- a/Documentation/devicetree/bindings/nvmem/qfprom.txt
+++ /dev/null
@@ -1,35 +0,0 @@
-= Qualcomm QFPROM device tree bindings =
-
-This binding is intended to represent QFPROM which is found in most QCOM SOCs.
-
-Required properties:
-- compatible: should be "qcom,qfprom"
-- reg: Should contain registers location and length
-
-= Data cells =
-Are child nodes of qfprom, bindings of which as described in
-bindings/nvmem/nvmem.txt
-
-Example:
-
- qfprom: qfprom@700000 {
- compatible = "qcom,qfprom";
- reg = <0x00700000 0x8000>;
- ...
- /* Data cells */
- tsens_calibration: calib@404 {
- reg = <0x4404 0x10>;
- };
- };
-
-
-= Data consumers =
-Are device nodes which consume nvmem data cells.
-
-For example:
-
- tsens {
- ...
- nvmem-cells = <&tsens_calibration>;
- nvmem-cell-names = "calibration";
- };
diff --git a/Documentation/devicetree/bindings/pci/cdns,cdns-pcie-host.yaml b/Documentation/devicetree/bindings/pci/cdns,cdns-pcie-host.yaml
index 84a8f09..6d67067 100644
--- a/Documentation/devicetree/bindings/pci/cdns,cdns-pcie-host.yaml
+++ b/Documentation/devicetree/bindings/pci/cdns,cdns-pcie-host.yaml
@@ -18,13 +18,12 @@
const: cdns,cdns-pcie-host
reg:
- maxItems: 3
+ maxItems: 2
reg-names:
items:
- const: reg
- const: cfg
- - const: mem
msi-parent: true
@@ -49,9 +48,8 @@
device-id = <0x0200>;
reg = <0x0 0xfb000000 0x0 0x01000000>,
- <0x0 0x41000000 0x0 0x00001000>,
- <0x0 0x40000000 0x0 0x04000000>;
- reg-names = "reg", "cfg", "mem";
+ <0x0 0x41000000 0x0 0x00001000>;
+ reg-names = "reg", "cfg";
ranges = <0x02000000 0x0 0x42000000 0x0 0x42000000 0x0 0x1000000>,
<0x01000000 0x0 0x43000000 0x0 0x43000000 0x0 0x0010000>;
diff --git a/Documentation/devicetree/bindings/pci/nvidia,tegra20-pcie.txt b/Documentation/devicetree/bindings/pci/nvidia,tegra20-pcie.txt
index 7939bca..d099f34 100644
--- a/Documentation/devicetree/bindings/pci/nvidia,tegra20-pcie.txt
+++ b/Documentation/devicetree/bindings/pci/nvidia,tegra20-pcie.txt
@@ -112,28 +112,16 @@
- Required:
- avddio-pex-supply: Power supply for analog PCIe logic. Must supply 1.05 V.
- dvddio-pex-supply: Power supply for digital PCIe I/O. Must supply 1.05 V.
- - avdd-pex-pll-supply: Power supply for dedicated (internal) PCIe PLL. Must
- supply 1.05 V.
- hvdd-pex-supply: High-voltage supply for PCIe I/O and PCIe output clocks.
Must supply 3.3 V.
- - hvdd-pex-pll-e-supply: High-voltage supply for PLLE (shared with USB3).
- Must supply 3.3 V.
- vddio-pex-ctl-supply: Power supply for PCIe control I/O partition. Must
supply 2.8-3.3 V.
- - avdd-pll-erefe-supply: Power supply for PLLE (shared with USB3). Must
- supply 1.05 V.
Power supplies for Tegra210:
- Required:
- - avdd-pll-uerefe-supply: Power supply for PLLE (shared with USB3). Must
- supply 1.05 V.
- hvddio-pex-supply: High-voltage supply for PCIe I/O and PCIe output
clocks. Must supply 1.8 V.
- dvddio-pex-supply: Power supply for digital PCIe I/O. Must supply 1.05 V.
- - dvdd-pex-pll-supply: Power supply for dedicated (internal) PCIe PLL. Must
- supply 1.05 V.
- - hvdd-pex-pll-e-supply: High-voltage supply for PLLE (shared with USB3).
- Must supply 3.3 V.
- vddio-pex-ctl-supply: Power supply for PCIe control I/O partition. Must
supply 1.8 V.
diff --git a/Documentation/devicetree/bindings/pci/pci.txt b/Documentation/devicetree/bindings/pci/pci.txt
index 29bcbd8..6a8f287 100644
--- a/Documentation/devicetree/bindings/pci/pci.txt
+++ b/Documentation/devicetree/bindings/pci/pci.txt
@@ -1,12 +1,12 @@
PCI bus bridges have standardized Device Tree bindings:
PCI Bus Binding to: IEEE Std 1275-1994
-http://www.devicetree.org/open-firmware/bindings/pci/pci2_1.pdf
+https://www.devicetree.org/open-firmware/bindings/pci/pci2_1.pdf
And for the interrupt mapping part:
Open Firmware Recommended Practice: Interrupt Mapping
-http://www.devicetree.org/open-firmware/practice/imap/imap0_9d.pdf
+https://www.devicetree.org/open-firmware/practice/imap/imap0_9d.pdf
Additionally to the properties specified in the above standards a host bridge
driver implementation may support the following properties:
diff --git a/Documentation/devicetree/bindings/pci/qcom,pcie.txt b/Documentation/devicetree/bindings/pci/qcom,pcie.txt
index 981b4de..02bc81b 100644
--- a/Documentation/devicetree/bindings/pci/qcom,pcie.txt
+++ b/Documentation/devicetree/bindings/pci/qcom,pcie.txt
@@ -5,6 +5,7 @@
Value type: <stringlist>
Definition: Value should contain
- "qcom,pcie-ipq8064" for ipq8064
+ - "qcom,pcie-ipq8064-v2" for ipq8064 rev 2 or ipq8065
- "qcom,pcie-apq8064" for apq8064
- "qcom,pcie-apq8084" for apq8084
- "qcom,pcie-msm8996" for msm8996 or apq8096
@@ -90,6 +91,8 @@
Definition: Should contain the following entries
- "core" Clocks the pcie hw block
- "phy" Clocks the pcie PHY block
+ - "aux" Clocks the pcie AUX block
+ - "ref" Clocks the pcie ref block
- clock-names:
Usage: required for apq8084/ipq4019
Value type: <stringlist>
@@ -177,6 +180,7 @@
- "pwr" PWR reset
- "ahb" AHB reset
- "phy_ahb" PHY AHB reset
+ - "ext" EXT reset
- reset-names:
Usage: required for ipq8074
@@ -277,14 +281,17 @@
<0 0 0 4 &intc 0 39 IRQ_TYPE_LEVEL_HIGH>; /* int_d */
clocks = <&gcc PCIE_A_CLK>,
<&gcc PCIE_H_CLK>,
- <&gcc PCIE_PHY_CLK>;
- clock-names = "core", "iface", "phy";
+ <&gcc PCIE_PHY_CLK>,
+ <&gcc PCIE_AUX_CLK>,
+ <&gcc PCIE_ALT_REF_CLK>;
+ clock-names = "core", "iface", "phy", "aux", "ref";
resets = <&gcc PCIE_ACLK_RESET>,
<&gcc PCIE_HCLK_RESET>,
<&gcc PCIE_POR_RESET>,
<&gcc PCIE_PCI_RESET>,
- <&gcc PCIE_PHY_RESET>;
- reset-names = "axi", "ahb", "por", "pci", "phy";
+ <&gcc PCIE_PHY_RESET>,
+ <&gcc PCIE_EXT_RESET>;
+ reset-names = "axi", "ahb", "por", "pci", "phy", "ext";
pinctrl-0 = <&pcie_pins_default>;
pinctrl-names = "default";
};
diff --git a/Documentation/devicetree/bindings/pci/ti,j721e-pci-ep.yaml b/Documentation/devicetree/bindings/pci/ti,j721e-pci-ep.yaml
new file mode 100644
index 0000000..cfe25cf
--- /dev/null
+++ b/Documentation/devicetree/bindings/pci/ti,j721e-pci-ep.yaml
@@ -0,0 +1,94 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+# Copyright (C) 2020 Texas Instruments Incorporated - http://www.ti.com/
+%YAML 1.2
+---
+$id: "http://devicetree.org/schemas/pci/ti,j721e-pci-ep.yaml#"
+$schema: "http://devicetree.org/meta-schemas/core.yaml#"
+
+title: TI J721E PCI EP (PCIe Wrapper)
+
+maintainers:
+ - Kishon Vijay Abraham I <kishon@ti.com>
+
+allOf:
+ - $ref: "cdns-pcie-ep.yaml#"
+
+properties:
+ compatible:
+ enum:
+ - ti,j721e-pcie-ep
+
+ reg:
+ maxItems: 4
+
+ reg-names:
+ items:
+ - const: intd_cfg
+ - const: user_cfg
+ - const: reg
+ - const: mem
+
+ ti,syscon-pcie-ctrl:
+ description: Phandle to the SYSCON entry required for configuring PCIe mode
+ and link speed.
+ allOf:
+ - $ref: /schemas/types.yaml#/definitions/phandle
+
+ power-domains:
+ maxItems: 1
+
+ clocks:
+ maxItems: 1
+ description: clock-specifier to represent input to the PCIe
+
+ clock-names:
+ items:
+ - const: fck
+
+ dma-coherent:
+ description: Indicates that the PCIe IP block can ensure the coherency
+
+required:
+ - compatible
+ - reg
+ - reg-names
+ - ti,syscon-pcie-ctrl
+ - max-link-speed
+ - num-lanes
+ - power-domains
+ - clocks
+ - clock-names
+ - cdns,max-outbound-regions
+ - dma-coherent
+ - max-functions
+ - phys
+ - phy-names
+
+examples:
+ - |
+ #include <dt-bindings/soc/ti,sci_pm_domain.h>
+
+ bus {
+ #address-cells = <2>;
+ #size-cells = <2>;
+
+ pcie0_ep: pcie-ep@d000000 {
+ compatible = "ti,j721e-pcie-ep";
+ reg = <0x00 0x02900000 0x00 0x1000>,
+ <0x00 0x02907000 0x00 0x400>,
+ <0x00 0x0d000000 0x00 0x00800000>,
+ <0x00 0x10000000 0x00 0x08000000>;
+ reg-names = "intd_cfg", "user_cfg", "reg", "mem";
+ ti,syscon-pcie-ctrl = <&pcie0_ctrl>;
+ max-link-speed = <3>;
+ num-lanes = <2>;
+ power-domains = <&k3_pds 239 TI_SCI_PD_EXCLUSIVE>;
+ clocks = <&k3_clks 239 1>;
+ clock-names = "fck";
+ cdns,max-outbound-regions = <16>;
+ max-functions = /bits/ 8 <6>;
+ dma-coherent;
+ phys = <&serdes0_pcie_link>;
+ phy-names = "pcie-phy";
+ };
+ };
diff --git a/Documentation/devicetree/bindings/pci/ti,j721e-pci-host.yaml b/Documentation/devicetree/bindings/pci/ti,j721e-pci-host.yaml
new file mode 100644
index 0000000..d7b60487
--- /dev/null
+++ b/Documentation/devicetree/bindings/pci/ti,j721e-pci-host.yaml
@@ -0,0 +1,113 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+# Copyright (C) 2019 Texas Instruments Incorporated - http://www.ti.com/
+%YAML 1.2
+---
+$id: "http://devicetree.org/schemas/pci/ti,j721e-pci-host.yaml#"
+$schema: "http://devicetree.org/meta-schemas/core.yaml#"
+
+title: TI J721E PCI Host (PCIe Wrapper)
+
+maintainers:
+ - Kishon Vijay Abraham I <kishon@ti.com>
+
+allOf:
+ - $ref: "cdns-pcie-host.yaml#"
+
+properties:
+ compatible:
+ enum:
+ - ti,j721e-pcie-host
+
+ reg:
+ maxItems: 4
+
+ reg-names:
+ items:
+ - const: intd_cfg
+ - const: user_cfg
+ - const: reg
+ - const: cfg
+
+ ti,syscon-pcie-ctrl:
+ description: Phandle to the SYSCON entry required for configuring PCIe mode
+ and link speed.
+ allOf:
+ - $ref: /schemas/types.yaml#/definitions/phandle
+
+ power-domains:
+ maxItems: 1
+
+ clocks:
+ maxItems: 1
+ description: clock-specifier to represent input to the PCIe
+
+ clock-names:
+ items:
+ - const: fck
+
+ vendor-id:
+ const: 0x104c
+
+ device-id:
+ const: 0xb00d
+
+ msi-map: true
+
+required:
+ - compatible
+ - reg
+ - reg-names
+ - ti,syscon-pcie-ctrl
+ - max-link-speed
+ - num-lanes
+ - power-domains
+ - clocks
+ - clock-names
+ - vendor-id
+ - device-id
+ - msi-map
+ - dma-coherent
+ - dma-ranges
+ - ranges
+ - reset-gpios
+ - phys
+ - phy-names
+
+examples:
+ - |
+ #include <dt-bindings/soc/ti,sci_pm_domain.h>
+ #include <dt-bindings/gpio/gpio.h>
+
+ bus {
+ #address-cells = <2>;
+ #size-cells = <2>;
+
+ pcie0_rc: pcie@2900000 {
+ compatible = "ti,j721e-pcie-host";
+ reg = <0x00 0x02900000 0x00 0x1000>,
+ <0x00 0x02907000 0x00 0x400>,
+ <0x00 0x0d000000 0x00 0x00800000>,
+ <0x00 0x10000000 0x00 0x00001000>;
+ reg-names = "intd_cfg", "user_cfg", "reg", "cfg";
+ ti,syscon-pcie-ctrl = <&pcie0_ctrl>;
+ max-link-speed = <3>;
+ num-lanes = <2>;
+ power-domains = <&k3_pds 239 TI_SCI_PD_EXCLUSIVE>;
+ clocks = <&k3_clks 239 1>;
+ clock-names = "fck";
+ device_type = "pci";
+ #address-cells = <3>;
+ #size-cells = <2>;
+ bus-range = <0x0 0xf>;
+ vendor-id = <0x104c>;
+ device-id = <0xb00d>;
+ msi-map = <0x0 &gic_its 0x0 0x10000>;
+ dma-coherent;
+ reset-gpios = <&exp1 6 GPIO_ACTIVE_HIGH>;
+ phys = <&serdes0_pcie_link>;
+ phy-names = "pcie-phy";
+ ranges = <0x01000000 0x0 0x10001000 0x00 0x10001000 0x0 0x0010000>,
+ <0x02000000 0x0 0x10011000 0x00 0x10011000 0x0 0x7fef000>;
+ dma-ranges = <0x02000000 0x0 0x0 0x0 0x0 0x10000 0x0>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/pci/xilinx-versal-cpm.yaml b/Documentation/devicetree/bindings/pci/xilinx-versal-cpm.yaml
new file mode 100644
index 0000000..a2bbc0e
--- /dev/null
+++ b/Documentation/devicetree/bindings/pci/xilinx-versal-cpm.yaml
@@ -0,0 +1,99 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/pci/xilinx-versal-cpm.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: CPM Host Controller device tree for Xilinx Versal SoCs
+
+maintainers:
+ - Bharat Kumar Gogada <bharat.kumar.gogada@xilinx.com>
+
+allOf:
+ - $ref: /schemas/pci/pci-bus.yaml#
+
+properties:
+ compatible:
+ const: xlnx,versal-cpm-host-1.00
+
+ reg:
+ items:
+ - description: Configuration space region and bridge registers.
+ - description: CPM system level control and status registers.
+
+ reg-names:
+ items:
+ - const: cfg
+ - const: cpm_slcr
+
+ interrupts:
+ maxItems: 1
+
+ msi-map:
+ description:
+ Maps a Requester ID to an MSI controller and associated MSI sideband data.
+
+ ranges:
+ maxItems: 2
+
+ "#interrupt-cells":
+ const: 1
+
+ interrupt-controller:
+ description: Interrupt controller node for handling legacy PCI interrupts.
+ type: object
+ properties:
+ "#address-cells":
+ const: 0
+ "#interrupt-cells":
+ const: 1
+ "interrupt-controller": true
+ additionalProperties: false
+
+required:
+ - reg
+ - reg-names
+ - "#interrupt-cells"
+ - interrupts
+ - interrupt-parent
+ - interrupt-map
+ - interrupt-map-mask
+ - bus-range
+ - msi-map
+ - interrupt-controller
+
+unevaluatedProperties: false
+
+examples:
+ - |
+
+ versal {
+ #address-cells = <2>;
+ #size-cells = <2>;
+ cpm_pcie: pcie@fca10000 {
+ compatible = "xlnx,versal-cpm-host-1.00";
+ device_type = "pci";
+ #address-cells = <3>;
+ #interrupt-cells = <1>;
+ #size-cells = <2>;
+ interrupts = <0 72 4>;
+ interrupt-parent = <&gic>;
+ interrupt-map-mask = <0 0 0 7>;
+ interrupt-map = <0 0 0 1 &pcie_intc_0 0>,
+ <0 0 0 2 &pcie_intc_0 1>,
+ <0 0 0 3 &pcie_intc_0 2>,
+ <0 0 0 4 &pcie_intc_0 3>;
+ bus-range = <0x00 0xff>;
+ ranges = <0x02000000 0x0 0xe0000000 0x0 0xe0000000 0x0 0x10000000>,
+ <0x43000000 0x80 0x00000000 0x80 0x00000000 0x0 0x80000000>;
+ msi-map = <0x0 &its_gic 0x0 0x10000>;
+ reg = <0x6 0x00000000 0x0 0x10000000>,
+ <0x0 0xfca10000 0x0 0x1000>;
+ reg-names = "cfg", "cpm_slcr";
+ pcie_intc_0: interrupt-controller {
+ #address-cells = <0>;
+ #interrupt-cells = <1>;
+ interrupt-controller;
+ };
+ };
+ };
diff --git a/Documentation/devicetree/bindings/phy/brcm,bcm63xx-usbh-phy.yaml b/Documentation/devicetree/bindings/phy/brcm,bcm63xx-usbh-phy.yaml
new file mode 100644
index 0000000..9a2e779
--- /dev/null
+++ b/Documentation/devicetree/bindings/phy/brcm,bcm63xx-usbh-phy.yaml
@@ -0,0 +1,79 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: "http://devicetree.org/schemas/phy/brcm,bcm63xx-usbh-phy.yaml#"
+$schema: "http://devicetree.org/meta-schemas/core.yaml#"
+
+title: BCM63xx USBH PHY
+
+maintainers:
+ - Álvaro Fernández Rojas <noltari@gmail.com>
+
+properties:
+ compatible:
+ enum:
+ - brcm,bcm6318-usbh-phy
+ - brcm,bcm6328-usbh-phy
+ - brcm,bcm6358-usbh-phy
+ - brcm,bcm6362-usbh-phy
+ - brcm,bcm6368-usbh-phy
+ - brcm,bcm63268-usbh-phy
+
+ reg:
+ maxItems: 1
+
+ clocks:
+ minItems: 1
+ maxItems: 2
+
+ clock-names:
+ minItems: 1
+ maxItems: 2
+ items:
+ - const: usbh
+ - const: usb_ref
+
+ resets:
+ maxItems: 1
+
+ "#phy-cells":
+ const: 1
+
+additionalProperties: false
+
+required:
+ - compatible
+ - reg
+ - clocks
+ - clock-names
+ - resets
+ - "#phy-cells"
+
+if:
+ properties:
+ compatible:
+ enum:
+ - brcm,bcm6318-usbh-phy
+ - brcm,bcm6328-usbh-phy
+ - brcm,bcm6362-usbh-phy
+ - brcm,bcm63268-usbh-phy
+then:
+ properties:
+ power-domains:
+ maxItems: 1
+ required:
+ - power-domains
+else:
+ properties:
+ power-domains: false
+
+examples:
+ - |
+ usbh: usb-phy@10001700 {
+ compatible = "brcm,bcm6368-usbh-phy";
+ reg = <0x10001700 0x38>;
+ clocks = <&periph_clk 15>;
+ clock-names = "usbh";
+ resets = <&periph_rst 12>;
+ #phy-cells = <1>;
+ };
diff --git a/Documentation/devicetree/bindings/phy/phy-armada38x-comphy.txt b/Documentation/devicetree/bindings/phy/phy-armada38x-comphy.txt
index ad49e5c..8b5a7a2 100644
--- a/Documentation/devicetree/bindings/phy/phy-armada38x-comphy.txt
+++ b/Documentation/devicetree/bindings/phy/phy-armada38x-comphy.txt
@@ -12,6 +12,13 @@
- #address-cells: should be 1.
- #size-cells: should be 0.
+Optional properties:
+
+- reg-names: must be "comphy" as the first name, and "conf".
+- reg: must contain the comphy register location and length as the first
+ pair, followed by an optional configuration register address and
+ length pair.
+
A sub-node is required for each comphy lane provided by the comphy.
Required properties (child nodes):
@@ -24,7 +31,8 @@
comphy: phy@18300 {
compatible = "marvell,armada-380-comphy";
- reg = <0x18300 0x100>;
+ reg-names = "comphy", "conf";
+ reg = <0x18300 0x100>, <0x18460 4>;
#address-cells = <1>;
#size-cells = <0>;
diff --git a/Documentation/devicetree/bindings/phy/qcom,ipq806x-usb-phy-hs.yaml b/Documentation/devicetree/bindings/phy/qcom,ipq806x-usb-phy-hs.yaml
new file mode 100644
index 0000000..23887ebe
--- /dev/null
+++ b/Documentation/devicetree/bindings/phy/qcom,ipq806x-usb-phy-hs.yaml
@@ -0,0 +1,55 @@
+# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/phy/qcom,ipq806x-usb-phy-hs.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Qualcomm ipq806x usb DWC3 HS PHY CONTROLLER
+
+maintainers:
+ - Ansuel Smith <ansuelsmth@gmail.com>
+
+description:
+ DWC3 PHY nodes are defined to describe on-chip Synopsis Physical layer
+ controllers used in ipq806x. Each DWC3 PHY controller should have its
+ own node.
+
+properties:
+ compatible:
+ const: qcom,ipq806x-usb-phy-hs
+
+ "#phy-cells":
+ const: 0
+
+ reg:
+ maxItems: 1
+
+ clocks:
+ minItems: 1
+ maxItems: 2
+
+ clock-names:
+ minItems: 1
+ maxItems: 2
+ items:
+ - const: ref
+ - const: xo
+
+required:
+ - compatible
+ - "#phy-cells"
+ - reg
+ - clocks
+ - clock-names
+
+examples:
+ - |
+ #include <dt-bindings/clock/qcom,gcc-ipq806x.h>
+
+ hs_phy_0: phy@110f8800 {
+ compatible = "qcom,ipq806x-usb-phy-hs";
+ reg = <0x110f8800 0x30>;
+ clocks = <&gcc USB30_0_UTMI_CLK>;
+ clock-names = "ref";
+ #phy-cells = <0>;
+ };
diff --git a/Documentation/devicetree/bindings/phy/qcom,ipq806x-usb-phy-ss.yaml b/Documentation/devicetree/bindings/phy/qcom,ipq806x-usb-phy-ss.yaml
new file mode 100644
index 0000000..fa30c24b
--- /dev/null
+++ b/Documentation/devicetree/bindings/phy/qcom,ipq806x-usb-phy-ss.yaml
@@ -0,0 +1,73 @@
+# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/phy/qcom,ipq806x-usb-phy-ss.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Qualcomm ipq806x usb DWC3 SS PHY CONTROLLER
+
+maintainers:
+ - Ansuel Smith <ansuelsmth@gmail.com>
+
+description:
+ DWC3 PHY nodes are defined to describe on-chip Synopsis Physical layer
+ controllers used in ipq806x. Each DWC3 PHY controller should have its
+ own node.
+
+properties:
+ compatible:
+ const: qcom,ipq806x-usb-phy-ss
+
+ "#phy-cells":
+ const: 0
+
+ reg:
+ maxItems: 1
+
+ clocks:
+ minItems: 1
+ maxItems: 2
+
+ clock-names:
+ minItems: 1
+ maxItems: 2
+ items:
+ - const: ref
+ - const: xo
+
+ qcom,rx-eq:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description: Override value for rx_eq.
+ default: 4
+ maximum: 7
+
+ qcom,tx-deamp-3_5db:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description: Override value for transmit preemphasis.
+ default: 23
+ maximum: 63
+
+ qcom,mpll:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description: Override value for mpll.
+ default: 0
+ maximum: 7
+
+required:
+ - compatible
+ - "#phy-cells"
+ - reg
+ - clocks
+ - clock-names
+
+examples:
+ - |
+ #include <dt-bindings/clock/qcom,gcc-ipq806x.h>
+
+ ss_phy_0: phy@110f8830 {
+ compatible = "qcom,ipq806x-usb-phy-ss";
+ reg = <0x110f8830 0x30>;
+ clocks = <&gcc USB30_0_MASTER_CLK>;
+ clock-names = "ref";
+ #phy-cells = <0>;
+ };
diff --git a/Documentation/devicetree/bindings/phy/qcom,qmp-phy.yaml b/Documentation/devicetree/bindings/phy/qcom,qmp-phy.yaml
index f80f889..e4cd4a1 100644
--- a/Documentation/devicetree/bindings/phy/qcom,qmp-phy.yaml
+++ b/Documentation/devicetree/bindings/phy/qcom,qmp-phy.yaml
@@ -18,6 +18,7 @@
compatible:
enum:
- qcom,ipq8074-qmp-pcie-phy
+ - qcom,ipq8074-qmp-usb3-phy
- qcom,msm8996-qmp-pcie-phy
- qcom,msm8996-qmp-ufs-phy
- qcom,msm8996-qmp-usb3-phy
@@ -161,6 +162,7 @@
compatible:
contains:
enum:
+ - qcom,ipq8074-qmp-usb3-phy
- qcom,msm8996-qmp-usb3-phy
- qcom,msm8998-qmp-pcie-phy
- qcom,msm8998-qmp-usb3-phy
diff --git a/Documentation/devicetree/bindings/phy/qcom,qusb2-phy.yaml b/Documentation/devicetree/bindings/phy/qcom,qusb2-phy.yaml
index b5a6195..9ba62dc 100644
--- a/Documentation/devicetree/bindings/phy/qcom,qusb2-phy.yaml
+++ b/Documentation/devicetree/bindings/phy/qcom,qusb2-phy.yaml
@@ -18,6 +18,7 @@
oneOf:
- items:
- enum:
+ - qcom,ipq8074-qusb2-phy
- qcom,msm8996-qusb2-phy
- qcom,msm8998-qusb2-phy
- items:
diff --git a/Documentation/devicetree/bindings/phy/renesas,usb2-phy.yaml b/Documentation/devicetree/bindings/phy/renesas,usb2-phy.yaml
index 440f09f..829e8c7 100644
--- a/Documentation/devicetree/bindings/phy/renesas,usb2-phy.yaml
+++ b/Documentation/devicetree/bindings/phy/renesas,usb2-phy.yaml
@@ -21,6 +21,7 @@
- renesas,usb2-phy-r8a774a1 # RZ/G2M
- renesas,usb2-phy-r8a774b1 # RZ/G2N
- renesas,usb2-phy-r8a774c0 # RZ/G2E
+ - renesas,usb2-phy-r8a774e1 # RZ/G2H
- renesas,usb2-phy-r8a7795 # R-Car H3
- renesas,usb2-phy-r8a7796 # R-Car M3-W
- renesas,usb2-phy-r8a77961 # R-Car M3-W+
diff --git a/Documentation/devicetree/bindings/phy/renesas,usb3-phy.yaml b/Documentation/devicetree/bindings/phy/renesas,usb3-phy.yaml
index 68cf9dd..f3ef738 100644
--- a/Documentation/devicetree/bindings/phy/renesas,usb3-phy.yaml
+++ b/Documentation/devicetree/bindings/phy/renesas,usb3-phy.yaml
@@ -15,6 +15,7 @@
- enum:
- renesas,r8a774a1-usb3-phy # RZ/G2M
- renesas,r8a774b1-usb3-phy # RZ/G2N
+ - renesas,r8a774e1-usb3-phy # RZ/G2H
- renesas,r8a7795-usb3-phy # R-Car H3
- renesas,r8a7796-usb3-phy # R-Car M3-W
- renesas,r8a77961-usb3-phy # R-Car M3-W+
diff --git a/Documentation/devicetree/bindings/phy/samsung,ufs-phy.yaml b/Documentation/devicetree/bindings/phy/samsung,ufs-phy.yaml
new file mode 100644
index 0000000..636cc50
--- /dev/null
+++ b/Documentation/devicetree/bindings/phy/samsung,ufs-phy.yaml
@@ -0,0 +1,75 @@
+# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/phy/samsung,ufs-phy.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Samsung SoC series UFS PHY Device Tree Bindings
+
+maintainers:
+ - Alim Akhtar <alim.akhtar@samsung.com>
+
+properties:
+ "#phy-cells":
+ const: 0
+
+ compatible:
+ enum:
+ - samsung,exynos7-ufs-phy
+
+ reg:
+ maxItems: 1
+
+ reg-names:
+ items:
+ - const: phy-pma
+
+ clocks:
+ items:
+ - description: PLL reference clock
+ - description: symbol clock for input symbol ( rx0-ch0 symbol clock)
+ - description: symbol clock for input symbol ( rx1-ch1 symbol clock)
+ - description: symbol clock for output symbol ( tx0 symbol clock)
+
+ clock-names:
+ items:
+ - const: ref_clk
+ - const: rx1_symbol_clk
+ - const: rx0_symbol_clk
+ - const: tx0_symbol_clk
+
+ samsung,pmu-syscon:
+ $ref: '/schemas/types.yaml#/definitions/phandle'
+ description: phandle for PMU system controller interface, used to
+ control pmu registers bits for ufs m-phy
+
+required:
+ - "#phy-cells"
+ - compatible
+ - reg
+ - reg-names
+ - clocks
+ - clock-names
+ - samsung,pmu-syscon
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/clock/exynos7-clk.h>
+
+ ufs_phy: ufs-phy@15571800 {
+ compatible = "samsung,exynos7-ufs-phy";
+ reg = <0x15571800 0x240>;
+ reg-names = "phy-pma";
+ samsung,pmu-syscon = <&pmu_system_controller>;
+ #phy-cells = <0>;
+ clocks = <&clock_fsys1 SCLK_COMBO_PHY_EMBEDDED_26M>,
+ <&clock_fsys1 PHYCLK_UFS20_RX1_SYMBOL_USER>,
+ <&clock_fsys1 PHYCLK_UFS20_RX0_SYMBOL_USER>,
+ <&clock_fsys1 PHYCLK_UFS20_TX0_SYMBOL_USER>;
+ clock-names = "ref_clk", "rx1_symbol_clk",
+ "rx0_symbol_clk", "tx0_symbol_clk";
+
+ };
+...
diff --git a/Documentation/devicetree/bindings/phy/socionext,uniphier-usb3hs-phy.yaml b/Documentation/devicetree/bindings/phy/socionext,uniphier-usb3hs-phy.yaml
index f88d362..c871d46 100644
--- a/Documentation/devicetree/bindings/phy/socionext,uniphier-usb3hs-phy.yaml
+++ b/Documentation/devicetree/bindings/phy/socionext,uniphier-usb3hs-phy.yaml
@@ -31,12 +31,16 @@
clocks:
minItems: 1
- maxItems: 2
+ maxItems: 3
clock-names:
oneOf:
- const: link # for PXs2
- - items: # for PXs3
+ - items: # for PXs3 with phy-ext
+ - const: link
+ - const: phy
+ - const: phy-ext
+ - items: # for others
- const: link
- const: phy
diff --git a/Documentation/devicetree/bindings/phy/ti,phy-gmii-sel.yaml b/Documentation/devicetree/bindings/phy/ti,phy-gmii-sel.yaml
new file mode 100644
index 0000000..bcec422d
--- /dev/null
+++ b/Documentation/devicetree/bindings/phy/ti,phy-gmii-sel.yaml
@@ -0,0 +1,104 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+# Copyright (C) 2020 Texas Instruments Incorporated - http://www.ti.com/
+%YAML 1.2
+---
+$id: "http://devicetree.org/schemas/phy/ti,phy-gmii-sel.yaml#"
+$schema: "http://devicetree.org/meta-schemas/core.yaml#"
+
+title: CPSW Port's Interface Mode Selection PHY Tree Bindings
+
+maintainers:
+ - Kishon Vijay Abraham I <kishon@ti.com>
+
+description: |
+ TI am335x/am437x/dra7(am5)/dm814x CPSW3G Ethernet Subsystem supports
+ two 10/100/1000 Ethernet ports with selectable G/MII, RMII, and RGMII interfaces.
+ The interface mode is selected by configuring the MII mode selection register(s)
+ (GMII_SEL) in the System Control Module chapter (SCM). GMII_SEL register(s) and
+ bit fields placement in SCM are different between SoCs while fields meaning
+ is the same.
+ +--------------+
+ +-------------------------------+ |SCM |
+ | CPSW | | +---------+ |
+ | +--------------------------------+gmii_sel | |
+ | | | | +---------+ |
+ | +----v---+ +--------+ | +--------------+
+ | |Port 1..<--+-->GMII/MII<------->
+ | | | | | | |
+ | +--------+ | +--------+ |
+ | | |
+ | | +--------+ |
+ | | | RMII <------->
+ | +--> | |
+ | | +--------+ |
+ | | |
+ | | +--------+ |
+ | | | RGMII <------->
+ | +--> | |
+ | +--------+ |
+ +-------------------------------+
+
+ CPSW Port's Interface Mode Selection PHY describes MII interface mode between
+ CPSW Port and Ethernet PHY which depends on Eth PHY and board configuration.
+ |
+ CPSW Port's Interface Mode Selection PHY device should defined as child device
+ of SCM node (scm_conf) and can be attached to each CPSW port node using standard
+ PHY bindings.
+
+properties:
+ compatible:
+ enum:
+ - ti,am3352-phy-gmii-sel
+ - ti,dra7xx-phy-gmii-sel
+ - ti,am43xx-phy-gmii-sel
+ - ti,dm814-phy-gmii-sel
+ - ti,am654-phy-gmii-sel
+
+ reg:
+ description: Address and length of the register set for the device
+
+ '#phy-cells': true
+
+allOf:
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - ti,dra7xx-phy-gmii-sel
+ - ti,dm814-phy-gmii-sel
+ - ti,am654-phy-gmii-sel
+ then:
+ properties:
+ '#phy-cells':
+ const: 1
+ description: CPSW port number (starting from 1)
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - ti,am3352-phy-gmii-sel
+ - ti,am43xx-phy-gmii-sel
+ then:
+ properties:
+ '#phy-cells':
+ const: 2
+ description: |
+ - CPSW port number (starting from 1)
+ - RMII refclk mode
+
+required:
+ - compatible
+ - reg
+ - '#phy-cells'
+
+additionalProperties: false
+
+examples:
+ - |
+ phy_gmii_sel: phy-gmii-sel@650 {
+ compatible = "ti,am3352-phy-gmii-sel";
+ reg = <0x650 0x4>;
+ #phy-cells = <2>;
+ };
diff --git a/Documentation/devicetree/bindings/phy/ti-phy-gmii-sel.txt b/Documentation/devicetree/bindings/phy/ti-phy-gmii-sel.txt
deleted file mode 100644
index 83b78c1..0000000
--- a/Documentation/devicetree/bindings/phy/ti-phy-gmii-sel.txt
+++ /dev/null
@@ -1,69 +0,0 @@
-CPSW Port's Interface Mode Selection PHY Tree Bindings
------------------------------------------------
-
-TI am335x/am437x/dra7(am5)/dm814x CPSW3G Ethernet Subsystem supports
-two 10/100/1000 Ethernet ports with selectable G/MII, RMII, and RGMII interfaces.
-The interface mode is selected by configuring the MII mode selection register(s)
-(GMII_SEL) in the System Control Module chapter (SCM). GMII_SEL register(s) and
-bit fields placement in SCM are different between SoCs while fields meaning
-is the same.
- +--------------+
- +-------------------------------+ |SCM |
- | CPSW | | +---------+ |
- | +--------------------------------+gmii_sel | |
- | | | | +---------+ |
- | +----v---+ +--------+ | +--------------+
- | |Port 1..<--+-->GMII/MII<------->
- | | | | | | |
- | +--------+ | +--------+ |
- | | |
- | | +--------+ |
- | | | RMII <------->
- | +--> | |
- | | +--------+ |
- | | |
- | | +--------+ |
- | | | RGMII <------->
- | +--> | |
- | +--------+ |
- +-------------------------------+
-
-CPSW Port's Interface Mode Selection PHY describes MII interface mode between
-CPSW Port and Ethernet PHY which depends on Eth PHY and board configuration.
-
-CPSW Port's Interface Mode Selection PHY device should defined as child device
-of SCM node (scm_conf) and can be attached to each CPSW port node using standard
-PHY bindings (See phy/phy-bindings.txt).
-
-Required properties:
-- compatible : Should be "ti,am3352-phy-gmii-sel" for am335x platform
- "ti,dra7xx-phy-gmii-sel" for dra7xx/am57xx platform
- "ti,am43xx-phy-gmii-sel" for am43xx platform
- "ti,dm814-phy-gmii-sel" for dm814x platform
- "ti,am654-phy-gmii-sel" for AM654x/J721E platform
-- reg : Address and length of the register set for the device
-- #phy-cells : must be 2.
- cell 1 - CPSW port number (starting from 1)
- cell 2 - RMII refclk mode
-
-Examples:
- phy_gmii_sel: phy-gmii-sel {
- compatible = "ti,am3352-phy-gmii-sel";
- reg = <0x650 0x4>;
- #phy-cells = <2>;
- };
-
- mac: ethernet@4a100000 {
- compatible = "ti,am335x-cpsw","ti,cpsw";
- ...
-
- cpsw_emac0: slave@4a100200 {
- ...
- phys = <&phy_gmii_sel 1 1>;
- };
-
- cpsw_emac1: slave@4a100300 {
- ...
- phys = <&phy_gmii_sel 2 1>;
- };
- };
diff --git a/Documentation/devicetree/bindings/phy/xlnx,zynqmp-psgtr.yaml b/Documentation/devicetree/bindings/phy/xlnx,zynqmp-psgtr.yaml
new file mode 100644
index 0000000..04d5654
--- /dev/null
+++ b/Documentation/devicetree/bindings/phy/xlnx,zynqmp-psgtr.yaml
@@ -0,0 +1,105 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/phy/xlnx,zynqmp-psgtr.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Xilinx ZynqMP Gigabit Transceiver PHY Device Tree Bindings
+
+maintainers:
+ - Laurent Pinchart <laurent.pinchart@ideasonboard.com>
+
+description: |
+ This binding describes the Xilinx ZynqMP Gigabit Transceiver (GTR) PHY. The
+ GTR provides four lanes and is used by USB, SATA, PCIE, Display port and
+ Ethernet SGMII controllers.
+
+properties:
+ "#phy-cells":
+ const: 4
+ description: |
+ The cells contain the following arguments.
+
+ - description: The GTR lane
+ minimum: 0
+ maximum: 3
+ - description: The PHY type
+ enum:
+ - PHY_TYPE_DP
+ - PHY_TYPE_PCIE
+ - PHY_TYPE_SATA
+ - PHY_TYPE_SGMII
+ - PHY_TYPE_USB
+ - description: The PHY instance
+ minimum: 0
+ maximum: 1 # for DP, SATA or USB
+ maximum: 3 # for PCIE or SGMII
+ - description: The reference clock number
+ minimum: 0
+ maximum: 3
+
+ compatible:
+ enum:
+ - xlnx,zynqmp-psgtr-v1.1
+ - xlnx,zynqmp-psgtr
+
+ clocks:
+ minItems: 1
+ maxItems: 4
+ description: |
+ Clock for each PS_MGTREFCLK[0-3] reference clock input. Unconnected
+ inputs shall not have an entry.
+
+ clock-names:
+ minItems: 1
+ maxItems: 4
+ items:
+ pattern: "^ref[0-3]$"
+
+ reg:
+ items:
+ - description: SERDES registers block
+ - description: SIOU registers block
+
+ reg-names:
+ items:
+ - const: serdes
+ - const: siou
+
+ xlnx,tx-termination-fix:
+ description: |
+ Include this for fixing functional issue with the TX termination
+ resistance in GT, which can be out of spec for the XCZU9EG silicon
+ version.
+ type: boolean
+
+required:
+ - "#phy-cells"
+ - compatible
+ - reg
+ - reg-names
+
+if:
+ properties:
+ compatible:
+ const: xlnx,zynqmp-psgtr-v1.1
+
+then:
+ properties:
+ xlnx,tx-termination-fix: false
+
+additionalProperties: false
+
+examples:
+ - |
+ phy: phy@fd400000 {
+ compatible = "xlnx,zynqmp-psgtr-v1.1";
+ reg = <0xfd400000 0x40000>,
+ <0xfd3d0000 0x1000>;
+ reg-names = "serdes", "siou";
+ clocks = <&refclks 3>, <&refclks 2>, <&refclks 0>;
+ clock-names = "ref1", "ref2", "ref3";
+ #phy-cells = <4>;
+ };
+
+...
diff --git a/Documentation/devicetree/bindings/pinctrl/ingenic,pinctrl.txt b/Documentation/devicetree/bindings/pinctrl/ingenic,pinctrl.txt
deleted file mode 100644
index d9b2100..0000000
--- a/Documentation/devicetree/bindings/pinctrl/ingenic,pinctrl.txt
+++ /dev/null
@@ -1,81 +0,0 @@
-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 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, the x1000 and the x1830
-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:
---------------------
-
- - 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"
- - "ingenic,x1830-pinctrl"
- - reg: Address range of the pinctrl registers.
-
-
-Required properties for sub-nodes (GPIO chips):
------------------------------------------------
-
- - compatible: Must contain one of:
- - "ingenic,jz4740-gpio"
- - "ingenic,jz4760-gpio"
- - "ingenic,jz4770-gpio"
- - "ingenic,jz4780-gpio"
- - "ingenic,x1000-gpio"
- - "ingenic,x1830-gpio"
- - reg: The GPIO bank number.
- - interrupt-controller: Marks the device node as an interrupt controller.
- - interrupts: Interrupt specifier for the controllers interrupt.
- - #interrupt-cells: Should be 2. Refer to
- ../interrupt-controller/interrupts.txt for more details.
- - gpio-controller: Marks the device node as a GPIO controller.
- - #gpio-cells: Should be 2. The first cell is the GPIO number and the second
- cell specifies GPIO flags, as defined in <dt-bindings/gpio/gpio.h>. Only the
- GPIO_ACTIVE_HIGH and GPIO_ACTIVE_LOW flags are supported.
- - gpio-ranges: Range of pins managed by the GPIO controller. Refer to
- ../gpio/gpio.txt for more details.
-
-
-Example:
---------
-
-pinctrl: pin-controller@10010000 {
- compatible = "ingenic,jz4740-pinctrl";
- reg = <0x10010000 0x400>;
- #address-cells = <1>;
- #size-cells = <0>;
-
- gpa: gpio@0 {
- compatible = "ingenic,jz4740-gpio";
- reg = <0>;
-
- gpio-controller;
- gpio-ranges = <&pinctrl 0 0 32>;
- #gpio-cells = <2>;
-
- interrupt-controller;
- #interrupt-cells = <2>;
-
- interrupt-parent = <&intc>;
- interrupts = <28>;
- };
-};
diff --git a/Documentation/devicetree/bindings/pinctrl/ingenic,pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/ingenic,pinctrl.yaml
new file mode 100644
index 0000000..18163fb
--- /dev/null
+++ b/Documentation/devicetree/bindings/pinctrl/ingenic,pinctrl.yaml
@@ -0,0 +1,176 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/pinctrl/ingenic,pinctrl.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Ingenic SoCs pin controller devicetree bindings
+
+description: >
+ 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 Ingenic 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, the X1000 and the X1830
+ 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.
+
+maintainers:
+ - Paul Cercueil <paul@crapouillou.net>
+
+properties:
+ nodename:
+ pattern: "^pinctrl@[0-9a-f]+$"
+
+ compatible:
+ oneOf:
+ - enum:
+ - ingenic,jz4740-pinctrl
+ - ingenic,jz4725b-pinctrl
+ - ingenic,jz4760-pinctrl
+ - ingenic,jz4770-pinctrl
+ - ingenic,jz4780-pinctrl
+ - ingenic,x1000-pinctrl
+ - ingenic,x1500-pinctrl
+ - ingenic,x1830-pinctrl
+ - items:
+ - const: ingenic,jz4760b-pinctrl
+ - const: ingenic,jz4760-pinctrl
+ - items:
+ - const: ingenic,x1000e-pinctrl
+ - const: ingenic,x1000-pinctrl
+
+ reg:
+ maxItems: 1
+
+ "#address-cells":
+ const: 1
+
+ "#size-cells":
+ const: 0
+
+patternProperties:
+ "^gpio@[0-9]$":
+ type: object
+ properties:
+ compatible:
+ enum:
+ - ingenic,jz4740-gpio
+ - ingenic,jz4725b-gpio
+ - ingenic,jz4760-gpio
+ - ingenic,jz4770-gpio
+ - ingenic,jz4780-gpio
+ - ingenic,x1000-gpio
+ - ingenic,x1500-gpio
+ - ingenic,x1830-gpio
+
+ reg:
+ items:
+ - description: The GPIO bank number
+
+ gpio-controller: true
+
+ "#gpio-cells":
+ const: 2
+
+ gpio-ranges:
+ maxItems: 1
+
+ interrupt-controller: true
+
+ "#interrupt-cells":
+ const: 2
+ description:
+ Refer to ../interrupt-controller/interrupts.txt for more details.
+
+ interrupts:
+ maxItems: 1
+
+ required:
+ - compatible
+ - reg
+ - gpio-controller
+ - "#gpio-cells"
+ - interrupts
+ - interrupt-controller
+ - "#interrupt-cells"
+
+ additionalProperties: false
+
+required:
+ - compatible
+ - reg
+ - "#address-cells"
+ - "#size-cells"
+
+additionalProperties:
+ anyOf:
+ - type: object
+ allOf:
+ - $ref: pincfg-node.yaml#
+ - $ref: pinmux-node.yaml#
+
+ properties:
+ phandle: true
+ function: true
+ groups: true
+ pins: true
+ bias-disable: true
+ bias-pull-up: true
+ bias-pull-down: true
+ output-low: true
+ output-high: true
+ additionalProperties: false
+
+ - type: object
+ properties:
+ phandle: true
+ additionalProperties:
+ type: object
+ allOf:
+ - $ref: pincfg-node.yaml#
+ - $ref: pinmux-node.yaml#
+
+ properties:
+ phandle: true
+ function: true
+ groups: true
+ pins: true
+ bias-disable: true
+ bias-pull-up: true
+ bias-pull-down: true
+ output-low: true
+ output-high: true
+ additionalProperties: false
+
+examples:
+ - |
+ pin-controller@10010000 {
+ compatible = "ingenic,jz4770-pinctrl";
+ reg = <0x10010000 0x600>;
+
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ gpio@0 {
+ compatible = "ingenic,jz4770-gpio";
+ reg = <0>;
+
+ gpio-controller;
+ gpio-ranges = <&pinctrl 0 0 32>;
+ #gpio-cells = <2>;
+
+ interrupt-controller;
+ #interrupt-cells = <2>;
+
+ interrupt-parent = <&intc>;
+ interrupts = <17>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/pinctrl/mediatek,mt6779-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/mediatek,mt6779-pinctrl.yaml
new file mode 100644
index 0000000..152c151
--- /dev/null
+++ b/Documentation/devicetree/bindings/pinctrl/mediatek,mt6779-pinctrl.yaml
@@ -0,0 +1,202 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/pinctrl/mediatek,mt6779-pinctrl.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Mediatek MT6779 Pin Controller Device Tree Bindings
+
+maintainers:
+ - Andy Teng <andy.teng@mediatek.com>
+
+description: |+
+ The pin controller node should be the child of a syscon node with the
+ required property:
+ - compatible: "syscon"
+
+properties:
+ compatible:
+ const: mediatek,mt6779-pinctrl
+
+ reg:
+ minItems: 9
+ maxItems: 9
+
+ reg-names:
+ items:
+ - const: "gpio"
+ - const: "iocfg_rm"
+ - const: "iocfg_br"
+ - const: "iocfg_lm"
+ - const: "iocfg_lb"
+ - const: "iocfg_rt"
+ - const: "iocfg_lt"
+ - const: "iocfg_tl"
+ - const: "eint"
+
+ gpio-controller: true
+
+ "#gpio-cells":
+ const: 2
+ description: |
+ Number of cells in GPIO specifier. Since the generic GPIO
+ binding is used, the amount of cells must be specified as 2. See the below
+ mentioned gpio binding representation for description of particular cells.
+
+ gpio-ranges:
+ minItems: 1
+ maxItems: 5
+ description: |
+ GPIO valid number range.
+
+ interrupt-controller: true
+
+ interrupts:
+ maxItems: 1
+ description: |
+ Specifies the summary IRQ.
+
+ "#interrupt-cells":
+ const: 2
+
+required:
+ - compatible
+ - reg
+ - reg-names
+ - gpio-controller
+ - "#gpio-cells"
+ - gpio-ranges
+ - interrupt-controller
+ - interrupts
+ - "#interrupt-cells"
+
+patternProperties:
+ '-[0-9]*$':
+ type: object
+ patternProperties:
+ '-pins*$':
+ type: object
+ description: |
+ A pinctrl node should contain at least one subnodes representing the
+ pinctrl groups available on the machine. Each subnode will list the
+ pins it needs, and how they should be configured, with regard to muxer
+ configuration, pullups, drive strength, input enable/disable and input schmitt.
+ $ref: "/schemas/pinctrl/pincfg-node.yaml"
+
+ properties:
+ pinmux:
+ description:
+ integer array, represents gpio pin number and mux setting.
+ Supported pin number and mux varies for different SoCs, and are defined
+ as macros in boot/dts/<soc>-pinfunc.h directly.
+
+ bias-disable: true
+
+ bias-pull-up: true
+
+ bias-pull-down: true
+
+ input-enable: true
+
+ input-disable: true
+
+ output-low: true
+
+ output-high: true
+
+ input-schmitt-enable: true
+
+ input-schmitt-disable: true
+
+ mediatek,pull-up-adv:
+ description: |
+ Pull up setings for 2 pull resistors, R0 and R1. User can
+ configure those special pins. Valid arguments are described as below:
+ 0: (R1, R0) = (0, 0) which means R1 disabled and R0 disabled.
+ 1: (R1, R0) = (0, 1) which means R1 disabled and R0 enabled.
+ 2: (R1, R0) = (1, 0) which means R1 enabled and R0 disabled.
+ 3: (R1, R0) = (1, 1) which means R1 enabled and R0 enabled.
+ $ref: /schemas/types.yaml#/definitions/uint32
+ enum: [0, 1, 2, 3]
+
+ mediatek,pull-down-adv:
+ description: |
+ Pull down settings for 2 pull resistors, R0 and R1. User can
+ configure those special pins. Valid arguments are described as below:
+ 0: (R1, R0) = (0, 0) which means R1 disabled and R0 disabled.
+ 1: (R1, R0) = (0, 1) which means R1 disabled and R0 enabled.
+ 2: (R1, R0) = (1, 0) which means R1 enabled and R0 disabled.
+ 3: (R1, R0) = (1, 1) which means R1 enabled and R0 enabled.
+ $ref: /schemas/types.yaml#/definitions/uint32
+ enum: [0, 1, 2, 3]
+
+ required:
+ - pinmux
+
+ additionalProperties: false
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/irq.h>
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+ #include <dt-bindings/pinctrl/mt6779-pinfunc.h>
+
+ soc {
+ #address-cells = <2>;
+ #size-cells = <2>;
+
+ pio: pinctrl@10005000 {
+ compatible = "mediatek,mt6779-pinctrl";
+ reg = <0 0x10005000 0 0x1000>,
+ <0 0x11c20000 0 0x1000>,
+ <0 0x11d10000 0 0x1000>,
+ <0 0x11e20000 0 0x1000>,
+ <0 0x11e70000 0 0x1000>,
+ <0 0x11ea0000 0 0x1000>,
+ <0 0x11f20000 0 0x1000>,
+ <0 0x11f30000 0 0x1000>,
+ <0 0x1000b000 0 0x1000>;
+ reg-names = "gpio", "iocfg_rm",
+ "iocfg_br", "iocfg_lm",
+ "iocfg_lb", "iocfg_rt",
+ "iocfg_lt", "iocfg_tl",
+ "eint";
+ gpio-controller;
+ #gpio-cells = <2>;
+ gpio-ranges = <&pio 0 0 210>;
+ interrupt-controller;
+ #interrupt-cells = <2>;
+ interrupts = <GIC_SPI 204 IRQ_TYPE_LEVEL_HIGH>;
+
+ mmc0_pins_default: mmc0-0 {
+ cmd-dat-pins {
+ pinmux = <PINMUX_GPIO168__FUNC_MSDC0_DAT0>,
+ <PINMUX_GPIO172__FUNC_MSDC0_DAT1>,
+ <PINMUX_GPIO169__FUNC_MSDC0_DAT2>,
+ <PINMUX_GPIO177__FUNC_MSDC0_DAT3>,
+ <PINMUX_GPIO170__FUNC_MSDC0_DAT4>,
+ <PINMUX_GPIO173__FUNC_MSDC0_DAT5>,
+ <PINMUX_GPIO171__FUNC_MSDC0_DAT6>,
+ <PINMUX_GPIO174__FUNC_MSDC0_DAT7>,
+ <PINMUX_GPIO167__FUNC_MSDC0_CMD>;
+ input-enable;
+ mediatek,pull-up-adv = <1>;
+ };
+ clk-pins {
+ pinmux = <PINMUX_GPIO176__FUNC_MSDC0_CLK>;
+ mediatek,pull-down-adv = <2>;
+ };
+ rst-pins {
+ pinmux = <PINMUX_GPIO178__FUNC_MSDC0_RSTB>;
+ mediatek,pull-up-adv = <0>;
+ };
+ };
+ };
+
+ mmc0 {
+ pinctrl-0 = <&mmc0_pins_default>;
+ pinctrl-names = "default";
+ };
+ };
diff --git a/Documentation/devicetree/bindings/pinctrl/qcom,ipq4019-pinctrl.txt b/Documentation/devicetree/bindings/pinctrl/qcom,ipq4019-pinctrl.txt
index 84be0f2..0861afe 100644
--- a/Documentation/devicetree/bindings/pinctrl/qcom,ipq4019-pinctrl.txt
+++ b/Documentation/devicetree/bindings/pinctrl/qcom,ipq4019-pinctrl.txt
@@ -44,7 +44,8 @@
The following generic properties as defined in pinctrl-bindings.txt are valid
to specify in a pin configuration subnode:
- pins, function, bias-disable, bias-pull-down, bias-pull-up, drive-strength.
+ pins, function, bias-disable, bias-pull-down, bias-pull-up, drive-open-drain,
+ drive-strength.
Non-empty subnodes must specify the 'pins' property.
Note that not all properties are valid for all pins.
diff --git a/Documentation/devicetree/bindings/pinctrl/qcom,pmic-gpio.txt b/Documentation/devicetree/bindings/pinctrl/qcom,pmic-gpio.txt
index 7be5de8..c3d1914 100644
--- a/Documentation/devicetree/bindings/pinctrl/qcom,pmic-gpio.txt
+++ b/Documentation/devicetree/bindings/pinctrl/qcom,pmic-gpio.txt
@@ -23,6 +23,8 @@
"qcom,pmi8994-gpio"
"qcom,pmi8998-gpio"
"qcom,pms405-gpio"
+ "qcom,pm660-gpio"
+ "qcom,pm660l-gpio"
"qcom,pm8150-gpio"
"qcom,pm8150b-gpio"
"qcom,pm6150-gpio"
diff --git a/Documentation/devicetree/bindings/pinctrl/renesas,pfc-pinctrl.txt b/Documentation/devicetree/bindings/pinctrl/renesas,pfc-pinctrl.txt
index b686131..d75476e 100644
--- a/Documentation/devicetree/bindings/pinctrl/renesas,pfc-pinctrl.txt
+++ b/Documentation/devicetree/bindings/pinctrl/renesas,pfc-pinctrl.txt
@@ -21,6 +21,7 @@
- "renesas,pfc-r8a774a1": for R8A774A1 (RZ/G2M) compatible pin-controller.
- "renesas,pfc-r8a774b1": for R8A774B1 (RZ/G2N) compatible pin-controller.
- "renesas,pfc-r8a774c0": for R8A774C0 (RZ/G2E) compatible pin-controller.
+ - "renesas,pfc-r8a774e1": for R8A774E1 (RZ/G2H) compatible pin-controller.
- "renesas,pfc-r8a7778": for R8A7778 (R-Car M1) compatible pin-controller.
- "renesas,pfc-r8a7779": for R8A7779 (R-Car H1) compatible pin-controller.
- "renesas,pfc-r8a7790": for R8A7790 (R-Car H2) compatible pin-controller.
@@ -114,7 +115,7 @@
[flags]>
On other mach-shmobile platforms GPIO is handled by the gpio-rcar driver.
-Please refer to Documentation/devicetree/bindings/gpio/renesas,gpio-rcar.txt
+Please refer to Documentation/devicetree/bindings/gpio/renesas,rcar-gpio.yaml
for documentation of the GPIO device tree bindings on those platforms.
diff --git a/Documentation/devicetree/bindings/pinctrl/renesas,rza2-pinctrl.txt b/Documentation/devicetree/bindings/pinctrl/renesas,rza2-pinctrl.txt
deleted file mode 100644
index a63ccd4..0000000
--- a/Documentation/devicetree/bindings/pinctrl/renesas,rza2-pinctrl.txt
+++ /dev/null
@@ -1,87 +0,0 @@
-Renesas RZ/A2 combined Pin and GPIO controller
-
-The Renesas SoCs of the RZ/A2 series feature a combined Pin and GPIO controller.
-Pin multiplexing and GPIO configuration is performed on a per-pin basis.
-Each port features up to 8 pins, each of them configurable for GPIO
-function (port mode) or in alternate function mode.
-Up to 8 different alternate function modes exist for each single pin.
-
-Pin controller node
--------------------
-
-Required properties:
- - compatible: shall be:
- - "renesas,r7s9210-pinctrl": for RZ/A2M
- - reg
- Address base and length of the memory area where the pin controller
- hardware is mapped to.
- - gpio-controller
- This pin controller also controls pins as GPIO
- - #gpio-cells
- Must be 2
- - gpio-ranges
- Expresses the total number of GPIO ports/pins in this SoC
-
-Example: Pin controller node for RZ/A2M SoC (r7s9210)
-
- pinctrl: pin-controller@fcffe000 {
- compatible = "renesas,r7s9210-pinctrl";
- reg = <0xfcffe000 0x1000>;
-
- gpio-controller;
- #gpio-cells = <2>;
- gpio-ranges = <&pinctrl 0 0 176>;
- };
-
-Sub-nodes
----------
-
-The child nodes of the pin controller designate pins to be used for
-specific peripheral functions or as GPIO.
-
-- Pin multiplexing sub-nodes:
- A pin multiplexing sub-node describes how to configure a set of
- (or a single) pin in some desired alternate function mode.
- The values for the pinmux properties are a combination of port name, pin
- number and the desired function index. Use the RZA2_PINMUX macro located
- in include/dt-bindings/pinctrl/r7s9210-pinctrl.h to easily define these.
- For assigning GPIO pins, use the macro RZA2_PIN also in r7s9210-pinctrl.h
- to express the desired port pin.
-
- Required properties:
- - pinmux:
- integer array representing pin number and pin multiplexing configuration.
- When a pin has to be configured in alternate function mode, use this
- property to identify the pin by its global index, and provide its
- alternate function configuration number along with it.
- When multiple pins are required to be configured as part of the same
- alternate function they shall be specified as members of the same
- argument list of a single "pinmux" property.
- Helper macros to ease assembling the pin index from its position
- (port where it sits on and pin number) and alternate function identifier
- are provided by the pin controller header file at:
- <dt-bindings/pinctrl/r7s9210-pinctrl.h>
- Integers values in "pinmux" argument list are assembled as:
- ((PORT * 8 + PIN) | MUX_FUNC << 16)
-
- Example: Board specific pins configuration
-
- &pinctrl {
- /* Serial Console */
- scif4_pins: serial4 {
- pinmux = <RZA2_PINMUX(PORT9, 0, 4)>, /* TxD4 */
- <RZA2_PINMUX(PORT9, 1, 4)>; /* RxD4 */
- };
- };
-
- Example: Assigning a GPIO:
-
- leds {
- status = "okay";
- compatible = "gpio-leds";
-
- led0 {
- /* P6_0 */
- gpios = <&pinctrl RZA2_PIN(PORT6, 0) GPIO_ACTIVE_HIGH>;
- };
- };
diff --git a/Documentation/devicetree/bindings/pinctrl/renesas,rza2-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/renesas,rza2-pinctrl.yaml
new file mode 100644
index 0000000..b7911a9
--- /dev/null
+++ b/Documentation/devicetree/bindings/pinctrl/renesas,rza2-pinctrl.yaml
@@ -0,0 +1,100 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/pinctrl/renesas,rza2-pinctrl.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Renesas RZ/A2 combined Pin and GPIO controller
+
+maintainers:
+ - Chris Brandt <chris.brandt@renesas.com>
+ - Geert Uytterhoeven <geert+renesas@glider.be>
+
+description:
+ The Renesas SoCs of the RZ/A2 series feature a combined Pin and GPIO
+ controller.
+ Pin multiplexing and GPIO configuration is performed on a per-pin basis.
+ Each port features up to 8 pins, each of them configurable for GPIO function
+ (port mode) or in alternate function mode.
+ Up to 8 different alternate function modes exist for each single pin.
+
+properties:
+ compatible:
+ const: "renesas,r7s9210-pinctrl" # RZ/A2M
+
+ reg:
+ maxItems: 1
+
+ gpio-controller: true
+
+ '#gpio-cells':
+ const: 2
+ description:
+ The first cell contains the global GPIO port index, constructed using the
+ RZA2_PIN() helper macro in r7s9210-pinctrl.h.
+ E.g. "RZA2_PIN(PORT6, 0)" for P6_0.
+
+ gpio-ranges:
+ maxItems: 1
+
+patternProperties:
+ "^.*$":
+ if:
+ type: object
+ then:
+ allOf:
+ - $ref: pincfg-node.yaml#
+ - $ref: pinmux-node.yaml#
+ description:
+ The child nodes of the pin controller designate pins to be used for
+ specific peripheral functions or as GPIO.
+
+ A pin multiplexing sub-node describes how to configure a set of
+ (or a single) pin in some desired alternate function mode.
+ The values for the pinmux properties are a combination of port name,
+ pin number and the desired function index. Use the RZA2_PINMUX macro
+ located in include/dt-bindings/pinctrl/r7s9210-pinctrl.h to easily
+ define these.
+ For assigning GPIO pins, use the macro RZA2_PIN also in
+ to express the desired port pin.
+
+ properties:
+ phandle: true
+
+ pinmux:
+ description:
+ Values are constructed from GPIO port number, pin number, and
+ alternate function configuration number using the RZA2_PINMUX()
+ helper macro in r7s9210-pinctrl.h.
+
+ required:
+ - pinmux
+
+ additionalProperties: false
+
+required:
+ - compatible
+ - reg
+ - gpio-controller
+ - '#gpio-cells'
+ - gpio-ranges
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/pinctrl/r7s9210-pinctrl.h>
+ pinctrl: pin-controller@fcffe000 {
+ compatible = "renesas,r7s9210-pinctrl";
+ reg = <0xfcffe000 0x1000>;
+
+ gpio-controller;
+ #gpio-cells = <2>;
+ gpio-ranges = <&pinctrl 0 0 176>;
+
+ /* Serial Console */
+ scif4_pins: serial4 {
+ pinmux = <RZA2_PINMUX(PORT9, 0, 4)>, /* TxD4 */
+ <RZA2_PINMUX(PORT9, 1, 4)>; /* RxD4 */
+ };
+ };
diff --git a/Documentation/devicetree/bindings/power/mti,mips-cpc.txt b/Documentation/devicetree/bindings/power/mti,mips-cpc.txt
deleted file mode 100644
index c6b8251..0000000
--- a/Documentation/devicetree/bindings/power/mti,mips-cpc.txt
+++ /dev/null
@@ -1,8 +0,0 @@
-Binding for MIPS Cluster Power Controller (CPC).
-
-This binding allows a system to specify where the CPC registers are
-located.
-
-Required properties:
-compatible : Should be "mti,mips-cpc".
-regs: Should describe the address & size of the CPC register region.
diff --git a/Documentation/devicetree/bindings/power/mti,mips-cpc.yaml b/Documentation/devicetree/bindings/power/mti,mips-cpc.yaml
new file mode 100644
index 0000000..ccdeaec
--- /dev/null
+++ b/Documentation/devicetree/bindings/power/mti,mips-cpc.yaml
@@ -0,0 +1,35 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/power/mti,mips-cpc.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: MIPS Cluster Power Controller
+
+description: |
+ Defines a location of the MIPS Cluster Power Controller registers.
+
+maintainers:
+ - Paul Burton <paulburton@kernel.org>
+
+properties:
+ compatible:
+ const: mti,mips-cpc
+
+ reg:
+ description: |
+ Base address and size of an unoccupied memory region, which will be
+ used to map the MIPS CPC registers block.
+ maxItems: 1
+
+required:
+ - compatible
+ - reg
+
+examples:
+ - |
+ cpc@1bde0000 {
+ compatible = "mti,mips-cpc";
+ reg = <0x1bde0000 0x8000>;
+ };
+...
diff --git a/Documentation/devicetree/bindings/power/renesas,rcar-sysc.yaml b/Documentation/devicetree/bindings/power/renesas,rcar-sysc.yaml
index 55b6ab2..ec2aaee 100644
--- a/Documentation/devicetree/bindings/power/renesas,rcar-sysc.yaml
+++ b/Documentation/devicetree/bindings/power/renesas,rcar-sysc.yaml
@@ -25,6 +25,7 @@
- renesas,r8a774a1-sysc # RZ/G2M
- renesas,r8a774b1-sysc # RZ/G2N
- renesas,r8a774c0-sysc # RZ/G2E
+ - renesas,r8a774e1-sysc # RZ/G2H
- renesas,r8a7779-sysc # R-Car H1
- renesas,r8a7790-sysc # R-Car H2
- renesas,r8a7791-sysc # R-Car M2-W
diff --git a/Documentation/devicetree/bindings/power/supply/battery.txt b/Documentation/devicetree/bindings/power/supply/battery.txt
index 5e29595..a9f80cc 100644
--- a/Documentation/devicetree/bindings/power/supply/battery.txt
+++ b/Documentation/devicetree/bindings/power/supply/battery.txt
@@ -1,87 +1,3 @@
-Battery Characteristics
-
-The devicetree battery node provides static battery characteristics.
-In smart batteries, these are typically stored in non-volatile memory
-on a fuel gauge chip. The battery node should be used where there is
-no appropriate non-volatile memory, or it is unprogrammed/incorrect.
-
-Upstream dts files should not include battery nodes, unless the battery
-represented cannot easily be replaced in the system by one of a
-different type. This prevents unpredictable, potentially harmful,
-behavior should a replacement that changes the battery type occur
-without a corresponding update to the dtb.
+The contents of this file has been moved to battery.yaml
Please note that not all charger drivers respect all of the properties.
-
-Required Properties:
- - compatible: Must be "simple-battery"
-
-Optional Properties:
- - over-voltage-threshold-microvolt: battery over-voltage limit
- - re-charge-voltage-microvolt: limit to automatically start charging again
- - voltage-min-design-microvolt: drained battery voltage
- - voltage-max-design-microvolt: fully charged battery voltage
- - energy-full-design-microwatt-hours: battery design energy
- - charge-full-design-microamp-hours: battery design capacity
- - trickle-charge-current-microamp: current for trickle-charge phase
- - precharge-current-microamp: current for pre-charge phase
- - precharge-upper-limit-microvolt: limit when to change to constant charging
- - charge-term-current-microamp: current for charge termination phase
- - constant-charge-current-max-microamp: maximum constant input current
- - constant-charge-voltage-max-microvolt: maximum constant input voltage
- - factory-internal-resistance-micro-ohms: battery factory internal resistance
- - ocv-capacity-table-0: An array providing the open circuit voltage (OCV)
- of the battery and corresponding battery capacity percent, which is used
- to look up battery capacity according to current OCV value. And the open
- circuit voltage unit is microvolt.
- - ocv-capacity-table-1: Same as ocv-capacity-table-0
- ......
- - ocv-capacity-table-n: Same as ocv-capacity-table-0
- - ocv-capacity-celsius: An array containing the temperature in degree Celsius,
- for each of the battery capacity lookup table. The first temperature value
- specifies the OCV table 0, and the second temperature value specifies the
- OCV table 1, and so on.
- - resistance-temp-table: An array providing the temperature in degree Celsius
- and corresponding battery internal resistance percent, which is used to look
- up the resistance percent according to current temperature to get a accurate
- batterty internal resistance in different temperatures.
-
-Battery properties are named, where possible, for the corresponding
-elements in enum power_supply_property, defined in
-https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/include/linux/power_supply.h
-
-Batteries must be referenced by chargers and/or fuel-gauges
-using a phandle. The phandle's property should be named
-"monitored-battery".
-
-Example:
-
- bat: battery {
- compatible = "simple-battery";
- voltage-min-design-microvolt = <3200000>;
- voltage-max-design-microvolt = <4200000>;
- energy-full-design-microwatt-hours = <5290000>;
- charge-full-design-microamp-hours = <1430000>;
- precharge-current-microamp = <256000>;
- charge-term-current-microamp = <128000>;
- constant-charge-current-max-microamp = <900000>;
- constant-charge-voltage-max-microvolt = <4200000>;
- factory-internal-resistance-micro-ohms = <250000>;
- ocv-capacity-celsius = <(-10) 0 10>;
- ocv-capacity-table-0 = <4185000 100>, <4113000 95>, <4066000 90>, ...;
- ocv-capacity-table-1 = <4200000 100>, <4185000 95>, <4113000 90>, ...;
- ocv-capacity-table-2 = <4250000 100>, <4200000 95>, <4185000 90>, ...;
- resistance-temp-table = <20 100>, <10 90>, <0 80>, <(-10) 60>;
- };
-
- charger: charger@11 {
- ....
- monitored-battery = <&bat>;
- ...
- };
-
- fuel_gauge: fuel-gauge@22 {
- ....
- monitored-battery = <&bat>;
- ...
- };
diff --git a/Documentation/devicetree/bindings/power/supply/battery.yaml b/Documentation/devicetree/bindings/power/supply/battery.yaml
new file mode 100644
index 0000000..932b736
--- /dev/null
+++ b/Documentation/devicetree/bindings/power/supply/battery.yaml
@@ -0,0 +1,144 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/power/supply/battery.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Battery Characteristics
+
+maintainers:
+ - Sebastian Reichel <sre@kernel.org>
+
+description: |
+ The devicetree battery node provides static battery characteristics.
+ In smart batteries, these are typically stored in non-volatile memory
+ on a fuel gauge chip. The battery node should be used where there is
+ no appropriate non-volatile memory, or it is unprogrammed/incorrect.
+
+ Upstream dts files should not include battery nodes, unless the battery
+ represented cannot easily be replaced in the system by one of a
+ different type. This prevents unpredictable, potentially harmful,
+ behavior should a replacement that changes the battery type occur
+ without a corresponding update to the dtb.
+
+ Battery properties are named, where possible, for the corresponding elements
+ in enum power_supply_property, defined in include/linux/power_supply.h
+
+ Batteries must be referenced by chargers and/or fuel-gauges using a phandle.
+ The phandle's property should be named "monitored-battery".
+
+properties:
+ compatible:
+ const: simple-battery
+
+ over-voltage-threshold-microvolt:
+ description: battery over-voltage limit
+
+ re-charge-voltage-microvolt:
+ description: limit to automatically start charging again
+
+ voltage-min-design-microvolt:
+ description: drained battery voltage
+
+ voltage-max-design-microvolt:
+ description: fully charged battery voltage
+
+ energy-full-design-microwatt-hours:
+ description: battery design energy
+
+ charge-full-design-microamp-hours:
+ description: battery design capacity
+
+ trickle-charge-current-microamp:
+ description: current for trickle-charge phase
+
+ precharge-current-microamp:
+ description: current for pre-charge phase
+
+ precharge-upper-limit-microvolt:
+ description: limit when to change to constant charging
+
+ charge-term-current-microamp:
+ description: current for charge termination phase
+
+ constant-charge-current-max-microamp:
+ description: maximum constant input current
+
+ constant-charge-voltage-max-microvolt:
+ description: maximum constant input voltage
+
+ factory-internal-resistance-micro-ohms:
+ description: battery factory internal resistance
+
+ resistance-temp-table:
+ description: |
+ An array providing the temperature in degree Celsius
+ and corresponding battery internal resistance percent, which is used to
+ look up the resistance percent according to current temperature to get an
+ accurate batterty internal resistance in different temperatures.
+
+ ocv-capacity-celsius:
+ description: |
+ An array containing the temperature in degree Celsius,
+ for each of the battery capacity lookup table.
+
+required:
+ - compatible
+
+patternProperties:
+ '^ocv-capacity-table-[0-9]+$':
+ $ref: /schemas/types.yaml#/definitions/uint32-matrix
+ description: |
+ An array providing the open circuit voltage (OCV)
+ of the battery and corresponding battery capacity percent, which is used
+ to look up battery capacity according to current OCV value. And the open
+ circuit voltage unit is microvolt.
+ maxItems: 100
+ items:
+ items:
+ - description: open circuit voltage (OCV) in microvolts
+ - description: battery capacity percent
+ maximum: 100
+
+additionalProperties: false
+
+examples:
+ - |
+ power {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ battery: battery {
+ compatible = "simple-battery";
+ over-voltage-threshold-microvolt = <4500000>;
+ re-charge-voltage-microvolt = <250000>;
+ voltage-min-design-microvolt = <3200000>;
+ voltage-max-design-microvolt = <4200000>;
+ energy-full-design-microwatt-hours = <5290000>;
+ charge-full-design-microamp-hours = <1430000>;
+ precharge-current-microamp = <256000>;
+ precharge-upper-limit-microvolt = <2500000>;
+ charge-term-current-microamp = <128000>;
+ constant-charge-current-max-microamp = <900000>;
+ constant-charge-voltage-max-microvolt = <4200000>;
+ factory-internal-resistance-micro-ohms = <250000>;
+ ocv-capacity-celsius = <(-10) 0 10>;
+ /* table for -10 degree Celsius */
+ ocv-capacity-table-0 = <4185000 100>, <4113000 95>, <4066000 90>;
+ /* table for 0 degree Celsius */
+ ocv-capacity-table-1 = <4200000 100>, <4185000 95>, <4113000 90>;
+ /* table for 10 degree Celsius */
+ ocv-capacity-table-2 = <4250000 100>, <4200000 95>, <4185000 90>;
+ resistance-temp-table = <20 100>, <10 90>, <0 80>, <(-10) 60>;
+ };
+
+ charger@11 {
+ reg = <0x11>;
+ monitored-battery = <&battery>;
+ };
+
+ fuel-gauge@22 {
+ reg = <0x22>;
+ monitored-battery = <&battery>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/power/supply/bq2515x.yaml b/Documentation/devicetree/bindings/power/supply/bq2515x.yaml
new file mode 100644
index 0000000..75a5677
--- /dev/null
+++ b/Documentation/devicetree/bindings/power/supply/bq2515x.yaml
@@ -0,0 +1,93 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+# Copyright (C) 2020 Texas Instruments Incorporated
+%YAML 1.2
+---
+$id: "http://devicetree.org/schemas/power/supply/bq2515x.yaml#"
+$schema: "http://devicetree.org/meta-schemas/core.yaml#"
+
+title: TI bq2515x 500-mA Linear charger family
+
+maintainers:
+ - Dan Murphy <dmurphy@ti.com>
+ - Ricardo Rivera-Matos <r-rivera-matos@ti.com>
+
+description: |
+ The BQ2515x family is a highly integrated battery charge management IC that
+ integrates the most common functions for wearable devices, namely a charger,
+ an output voltage rail, ADC for battery and system monitoring, and
+ push-button controller.
+
+ Specifications about the charger can be found at:
+ http://www.ti.com/lit/ds/symlink/bq25150.pdf
+ http://www.ti.com/lit/ds/symlink/bq25155.pdf
+
+properties:
+ compatible:
+ enum:
+ - ti,bq25150
+ - ti,bq25155
+
+ reg:
+ maxItems: 1
+ description: I2C address of the charger.
+
+ ac-detect-gpios:
+ description: |
+ GPIO used for connecting the bq2515x device PG (AC Detect)
+ pin.
+ maxItems: 1
+
+ reset-gpios:
+ description: GPIO used for hardware reset.
+ maxItems: 1
+
+ powerdown-gpios:
+ description: GPIO used for low power mode of IC.
+ maxItems: 1
+
+ charge-enable-gpios:
+ description: GPIO used to turn on and off charging.
+ maxItems: 1
+
+ input-current-limit-microamp:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description: Maximum input current in micro Amps.
+ minimum: 50000
+ maximum: 500000
+
+ monitored-battery:
+ $ref: /schemas/types.yaml#/definitions/phandle
+ description: phandle to the battery node being monitored
+
+required:
+ - compatible
+ - reg
+ - monitored-battery
+
+additionalProperties: false
+
+examples:
+ - |
+ bat: battery {
+ compatible = "simple-battery";
+ constant-charge-current-max-microamp = <50000>;
+ precharge-current-microamp = <2500>;
+ constant-charge-voltage-max-microvolt = <4000000>;
+ };
+ #include <dt-bindings/gpio/gpio.h>
+ i2c0 {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ bq25150: charger@6b {
+ compatible = "ti,bq25150";
+ reg = <0x6b>;
+ monitored-battery = <&bat>;
+ input-current-limit-microamp = <100000>;
+
+ ac-detect-gpios = <&gpio1 28 GPIO_ACTIVE_HIGH>;
+ reset-gpios = <&gpio0 14 GPIO_ACTIVE_HIGH>;
+ powerdown-gpios = <&gpio0 15 GPIO_ACTIVE_HIGH>;
+ charge-enable-gpios = <&gpio0 13 GPIO_ACTIVE_LOW>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/power/supply/bq25890.txt b/Documentation/devicetree/bindings/power/supply/bq25890.txt
index dc9c8f7..3b4c69a 100644
--- a/Documentation/devicetree/bindings/power/supply/bq25890.txt
+++ b/Documentation/devicetree/bindings/power/supply/bq25890.txt
@@ -10,6 +10,7 @@
* "ti,bq25895"
* "ti,bq25896"
- reg: integer, i2c address of the device.
+- interrupts: interrupt line;
- ti,battery-regulation-voltage: integer, maximum charging voltage (in uV);
- ti,charge-current: integer, maximum charging current (in uA);
- ti,termination-current: integer, charge will be terminated when current in
@@ -36,17 +37,20 @@
Example:
bq25890 {
- compatible = "ti,bq25890";
- reg = <0x6a>;
+ compatible = "ti,bq25890";
+ reg = <0x6a>;
- ti,battery-regulation-voltage = <4200000>;
- ti,charge-current = <1000000>;
- ti,termination-current = <50000>;
- ti,precharge-current = <128000>;
- ti,minimum-sys-voltage = <3600000>;
- ti,boost-voltage = <5000000>;
- ti,boost-max-current = <1000000>;
+ interrupt-parent = <&gpio1>;
+ interrupts = <16 IRQ_TYPE_EDGE_FALLING>;
- ti,use-ilim-pin;
- ti,thermal-regulation-threshold = <120>;
+ ti,battery-regulation-voltage = <4200000>;
+ ti,charge-current = <1000000>;
+ ti,termination-current = <50000>;
+ ti,precharge-current = <128000>;
+ ti,minimum-sys-voltage = <3600000>;
+ ti,boost-voltage = <5000000>;
+ ti,boost-max-current = <1000000>;
+
+ ti,use-ilim-pin;
+ ti,thermal-regulation-threshold = <120>;
};
diff --git a/Documentation/devicetree/bindings/power/supply/bq27xxx.yaml b/Documentation/devicetree/bindings/power/supply/bq27xxx.yaml
index 03d1020..82f6827 100644
--- a/Documentation/devicetree/bindings/power/supply/bq27xxx.yaml
+++ b/Documentation/devicetree/bindings/power/supply/bq27xxx.yaml
@@ -49,6 +49,8 @@
- ti,bq27426
- ti,bq27441
- ti,bq27621
+ - ti,bq27z561
+ - ti,bq28z610
reg:
maxItems: 1
diff --git a/Documentation/devicetree/bindings/power/supply/gpio-charger.txt b/Documentation/devicetree/bindings/power/supply/gpio-charger.txt
deleted file mode 100644
index 0fb33b2..0000000
--- a/Documentation/devicetree/bindings/power/supply/gpio-charger.txt
+++ /dev/null
@@ -1,31 +0,0 @@
-gpio-charger
-
-Required properties :
- - compatible : "gpio-charger"
- - gpios : GPIO indicating the charger presence.
- See GPIO binding in bindings/gpio/gpio.txt .
- - charger-type : power supply type, one of
- unknown
- battery
- ups
- mains
- usb-sdp (USB standard downstream port)
- usb-dcp (USB dedicated charging port)
- usb-cdp (USB charging downstream port)
- usb-aca (USB accessory charger adapter)
-
-Optional properties:
- - charge-status-gpios: GPIO indicating whether a battery is charging.
-
-Example:
-
- usb_charger: charger {
- compatible = "gpio-charger";
- charger-type = "usb-sdp";
- gpios = <&gpd 28 GPIO_ACTIVE_LOW>;
- charge-status-gpios = <&gpc 27 GPIO_ACTIVE_LOW>;
- };
-
- battery {
- power-supplies = <&usb_charger>;
- };
diff --git a/Documentation/devicetree/bindings/power/supply/gpio-charger.yaml b/Documentation/devicetree/bindings/power/supply/gpio-charger.yaml
new file mode 100644
index 0000000..30eabbb
--- /dev/null
+++ b/Documentation/devicetree/bindings/power/supply/gpio-charger.yaml
@@ -0,0 +1,63 @@
+# SPDX-License-Identifier: GPL-2.0
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/power/supply/gpio-charger.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: simple battery chargers only communicating through GPIOs
+
+maintainers:
+ - Sebastian Reichel <sre@kernel.org>
+
+description:
+ This binding is for all chargers, which are working more or less
+ autonomously, only providing some status GPIOs and possibly some
+ GPIOs for limited control over the charging process.
+
+properties:
+ compatible:
+ const: gpio-charger
+
+ charger-type:
+ enum:
+ - unknown
+ - battery
+ - ups
+ - mains
+ - usb-sdp # USB standard downstream port
+ - usb-dcp # USB dedicated charging port
+ - usb-cdp # USB charging downstream port
+ - usb-aca # USB accessory charger adapter
+ description:
+ Type of the charger, e.g. "mains" for a wall charger.
+
+ gpios:
+ maxItems: 1
+ description: GPIO indicating the charger presence
+
+ charge-status-gpios:
+ maxItems: 1
+ description: GPIO indicating the charging status
+
+required:
+ - compatible
+
+anyOf:
+ - required:
+ - gpios
+ - required:
+ - charge-status-gpios
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/gpio/gpio.h>
+
+ charger {
+ compatible = "gpio-charger";
+ charger-type = "usb-sdp";
+
+ gpios = <&gpd 28 GPIO_ACTIVE_LOW>;
+ charge-status-gpios = <&gpc 27 GPIO_ACTIVE_LOW>;
+ };
diff --git a/Documentation/devicetree/bindings/property-units.txt b/Documentation/devicetree/bindings/property-units.txt
index c80a110..218f99f 100644
--- a/Documentation/devicetree/bindings/property-units.txt
+++ b/Documentation/devicetree/bindings/property-units.txt
@@ -17,6 +17,7 @@
-ms : millisecond
-us : microsecond
-ns : nanosecond
+-ps : picosecond
Distance
----------------------------------------
diff --git a/Documentation/devicetree/bindings/pwm/pwm-samsung.yaml b/Documentation/devicetree/bindings/pwm/pwm-samsung.yaml
index fc799b0..188679c 100644
--- a/Documentation/devicetree/bindings/pwm/pwm-samsung.yaml
+++ b/Documentation/devicetree/bindings/pwm/pwm-samsung.yaml
@@ -18,9 +18,6 @@
Be aware that the clocksource driver supports only uniprocessor systems.
-allOf:
- - $ref: pwm.yaml#
-
properties:
compatible:
enum:
@@ -63,7 +60,8 @@
interrupts:
description:
- One interrupt per timer, starting at timer 0.
+ One interrupt per timer, starting at timer 0. Necessary only for SoCs which
+ use PWM clocksource.
minItems: 1
maxItems: 5
@@ -88,12 +86,27 @@
- clocks
- clock-names
- compatible
- - interrupts
- "#pwm-cells"
- reg
additionalProperties: false
+allOf:
+ - $ref: pwm.yaml#
+
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - samsung,s3c2410-pwm
+ - samsung,s3c6400-pwm
+ - samsung,s5p6440-pwm
+ - samsung,s5pc100-pwm
+ then:
+ required:
+ - interrupts
+
examples:
- |
pwm@7f006000 {
diff --git a/Documentation/devicetree/bindings/regulator/da9211.txt b/Documentation/devicetree/bindings/regulator/da9211.txt
index 27717e8..eb87144 100644
--- a/Documentation/devicetree/bindings/regulator/da9211.txt
+++ b/Documentation/devicetree/bindings/regulator/da9211.txt
@@ -15,6 +15,8 @@
Optional properties:
- enable-gpios: platform gpio for control of BUCKA/BUCKB.
- Any optional property defined in regulator.txt
+ - regulator-initial-mode and regulator-allowed-modes may be specified using
+ mode values from dt-bindings/regulator/dlg,da9211-regulator.h
Example 1) DA9211
pmic: da9211@68 {
@@ -30,6 +32,8 @@
regulator-min-microamp = <2000000>;
regulator-max-microamp = <5000000>;
enable-gpios = <&gpio 27 0>;
+ regulator-allowed-modes = <DA9211_BUCK_MODE_SYNC
+ DA9211_BUCK_MODE_AUTO>;
};
};
};
diff --git a/Documentation/devicetree/bindings/regulator/google,cros-ec-regulator.yaml b/Documentation/devicetree/bindings/regulator/google,cros-ec-regulator.yaml
new file mode 100644
index 0000000..c9453d7
--- /dev/null
+++ b/Documentation/devicetree/bindings/regulator/google,cros-ec-regulator.yaml
@@ -0,0 +1,51 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/regulator/google,cros-ec-regulator.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: ChromeOS EC controlled voltage regulators
+
+maintainers:
+ - Pi-Hsun Shih <pihsun@chromium.org>
+
+description:
+ Any property defined as part of the core regulator binding, defined in
+ regulator.yaml, can also be used.
+
+allOf:
+ - $ref: "regulator.yaml#"
+
+properties:
+ compatible:
+ const: google,cros-ec-regulator
+
+ reg:
+ maxItems: 1
+ description: Identifier for the voltage regulator to ChromeOS EC.
+
+required:
+ - compatible
+ - reg
+
+examples:
+ - |
+ spi0 {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ cros_ec: ec@0 {
+ compatible = "google,cros-ec-spi";
+ reg = <0>;
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ regulator@0 {
+ compatible = "google,cros-ec-regulator";
+ regulator-min-microvolt = <1800000>;
+ regulator-max-microvolt = <3300000>;
+ reg = <0>;
+ };
+ };
+ };
+...
diff --git a/Documentation/devicetree/bindings/regulator/lp872x.txt b/Documentation/devicetree/bindings/regulator/lp872x.txt
index ca58a68..ab895cd 100644
--- a/Documentation/devicetree/bindings/regulator/lp872x.txt
+++ b/Documentation/devicetree/bindings/regulator/lp872x.txt
@@ -37,8 +37,8 @@
(Documentation/devicetree/bindings/regulator/regulator.txt)
Datasheet
- - LP8720: http://www.ti.com/lit/ds/symlink/lp8720.pdf
- - LP8725: http://www.ti.com/lit/ds/symlink/lp8725.pdf
+ - LP8720: https://www.ti.com/lit/ds/symlink/lp8720.pdf
+ - LP8725: https://www.ti.com/lit/ds/symlink/lp8725.pdf
Example 1) LP8720
diff --git a/Documentation/devicetree/bindings/regulator/mt6397-regulator.txt b/Documentation/devicetree/bindings/regulator/mt6397-regulator.txt
index 01141fb..c080086 100644
--- a/Documentation/devicetree/bindings/regulator/mt6397-regulator.txt
+++ b/Documentation/devicetree/bindings/regulator/mt6397-regulator.txt
@@ -16,6 +16,9 @@
ldo_vemc3v3, ldo_vgp1, ldo_vgp2, ldo_vgp3, ldo_vgp4, ldo_vgp5, ldo_vgp6,
ldo_vibr
+BUCK regulators can set regulator-initial-mode and regulator-allowed-modes to
+values specified in dt-bindings/regulator/mediatek,mt6397-regulator.h
+
Example:
pmic {
compatible = "mediatek,mt6397";
diff --git a/Documentation/devicetree/bindings/regulator/nxp,pca9450-regulator.yaml b/Documentation/devicetree/bindings/regulator/nxp,pca9450-regulator.yaml
new file mode 100644
index 0000000..c2b0a8b
--- /dev/null
+++ b/Documentation/devicetree/bindings/regulator/nxp,pca9450-regulator.yaml
@@ -0,0 +1,190 @@
+# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/regulator/nxp,pca9450-regulator.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: NXP PCA9450A/B/C Power Management Integrated Circuit regulators
+
+maintainers:
+ - Robin Gong <yibin.gong@nxp.com>
+
+description: |
+ Regulator nodes should be named to BUCK_<number> and LDO_<number>. The
+ definition for each of these nodes is defined using the standard
+ binding for regulators at
+ Documentation/devicetree/bindings/regulator/regulator.txt.
+ Datasheet is available at
+ https://www.nxp.com/docs/en/data-sheet/PCA9450DS.pdf
+
+#The valid names for PCA9450 regulator nodes are:
+#BUCK1, BUCK2, BUCK3, BUCK4, BUCK5, BUCK6,
+#LDO1, LDO2, LDO3, LDO4, LDO5
+#Note: Buck3 removed on PCA9450B and connect with Buck1 on PCA9450C.
+
+properties:
+ compatible:
+ enum:
+ - nxp,pca9450a
+ - nxp,pca9450b
+ - nxp,pca9450c
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+ regulators:
+ type: object
+ description: |
+ list of regulators provided by this controller
+
+ patternProperties:
+ "^LDO[1-5]$":
+ type: object
+ $ref: regulator.yaml#
+ description:
+ Properties for single LDO regulator.
+
+ properties:
+ regulator-name:
+ pattern: "^LDO[1-5]$"
+ description:
+ should be "LDO1", ..., "LDO5"
+
+ unevaluatedProperties: false
+
+ "^BUCK[1-6]$":
+ type: object
+ $ref: regulator.yaml#
+ description:
+ Properties for single BUCK regulator.
+
+ properties:
+ regulator-name:
+ pattern: "^BUCK[1-6]$"
+ description:
+ should be "BUCK1", ..., "BUCK6"
+
+ nxp,dvs-run-voltage:
+ $ref: "/schemas/types.yaml#/definitions/uint32"
+ minimum: 600000
+ maximum: 2187500
+ description:
+ PMIC default "RUN" state voltage in uV. Only Buck1~3 have such
+ dvs(dynamic voltage scaling) property.
+
+ nxp,dvs-standby-voltage:
+ $ref: "/schemas/types.yaml#/definitions/uint32"
+ minimum: 600000
+ maximum: 2187500
+ description:
+ PMIC default "STANDBY" state voltage in uV. Only Buck1~3 have such
+ dvs(dynamic voltage scaling) property.
+
+ unevaluatedProperties: false
+
+ additionalProperties: false
+
+required:
+ - compatible
+ - reg
+ - interrupts
+ - regulators
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/irq.h>
+
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+ pmic: pmic@25 {
+ compatible = "nxp,pca9450b";
+ reg = <0x25>;
+ pinctrl-0 = <&pinctrl_pmic>;
+ interrupt-parent = <&gpio1>;
+ interrupts = <3 IRQ_TYPE_LEVEL_LOW>;
+
+ regulators {
+ buck1: BUCK1 {
+ regulator-name = "BUCK1";
+ regulator-min-microvolt = <600000>;
+ regulator-max-microvolt = <2187500>;
+ regulator-boot-on;
+ regulator-always-on;
+ regulator-ramp-delay = <3125>;
+ };
+ buck2: BUCK2 {
+ regulator-name = "BUCK2";
+ regulator-min-microvolt = <600000>;
+ regulator-max-microvolt = <2187500>;
+ regulator-boot-on;
+ regulator-always-on;
+ regulator-ramp-delay = <3125>;
+ nxp,dvs-run-voltage = <950000>;
+ nxp,dvs-standby-voltage = <850000>;
+ };
+ buck4: BUCK4 {
+ regulator-name = "BUCK4";
+ regulator-min-microvolt = <600000>;
+ regulator-max-microvolt = <3400000>;
+ regulator-boot-on;
+ regulator-always-on;
+ };
+ buck5: BUCK5 {
+ regulator-name = "BUCK5";
+ regulator-min-microvolt = <600000>;
+ regulator-max-microvolt = <3400000>;
+ regulator-boot-on;
+ regulator-always-on;
+ };
+ buck6: BUCK6 {
+ regulator-name = "BUCK6";
+ regulator-min-microvolt = <600000>;
+ regulator-max-microvolt = <3400000>;
+ regulator-boot-on;
+ regulator-always-on;
+ };
+
+ ldo1: LDO1 {
+ regulator-name = "LDO1";
+ regulator-min-microvolt = <1600000>;
+ regulator-max-microvolt = <3300000>;
+ regulator-boot-on;
+ regulator-always-on;
+ };
+ ldo2: LDO2 {
+ regulator-name = "LDO2";
+ regulator-min-microvolt = <800000>;
+ regulator-max-microvolt = <1150000>;
+ regulator-boot-on;
+ regulator-always-on;
+ };
+ ldo3: LDO3 {
+ regulator-name = "LDO3";
+ regulator-min-microvolt = <800000>;
+ regulator-max-microvolt = <3300000>;
+ regulator-boot-on;
+ regulator-always-on;
+ };
+ ldo4: LDO4 {
+ regulator-name = "LDO4";
+ regulator-min-microvolt = <800000>;
+ regulator-max-microvolt = <3300000>;
+ regulator-boot-on;
+ regulator-always-on;
+ };
+ ldo5: LDO5 {
+ regulator-name = "LDO5";
+ regulator-min-microvolt = <1800000>;
+ regulator-max-microvolt = <3300000>;
+ regulator-boot-on;
+ regulator-always-on;
+ };
+ };
+ };
+ };
diff --git a/Documentation/devicetree/bindings/regulator/onnn,fan53880.yaml b/Documentation/devicetree/bindings/regulator/onnn,fan53880.yaml
new file mode 100644
index 0000000..eb61e04
--- /dev/null
+++ b/Documentation/devicetree/bindings/regulator/onnn,fan53880.yaml
@@ -0,0 +1,85 @@
+# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/regulator/onnn,fan53880.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Onsemi FAN53880 PMIC
+
+maintainers:
+ - Christoph Fritz <chf.fritz@googlemail.com>
+
+description: |
+ The FAN53880 is an I2C porgrammable power management IC (PMIC)
+ that contains a BUCK (step-down converter), four low dropouts (LDO)
+ and one BOOST (step-up converter) output. It is designed for mobile
+ power applications.
+
+properties:
+ $nodename:
+ pattern: "pmic@[0-9a-f]{1,2}"
+ compatible:
+ enum:
+ - onnn,fan53880
+
+ reg:
+ maxItems: 1
+
+ VIN12-supply:
+ description: Input supply phandle(s) for LDO1 and LDO2
+
+ VIN3-supply:
+ description: Input supply phandle(s) for LDO3
+
+ VIN4-supply:
+ description: Input supply phandle(s) for LDO4
+
+ PVIN-supply:
+ description: Input supply phandle(s) for BUCK and BOOST
+
+ regulators:
+ type: object
+ $ref: regulator.yaml#
+ description: |
+ list of regulators provided by this controller, must be named
+ after their hardware counterparts LDO[1-4], BUCK and BOOST
+
+ patternProperties:
+ "^LDO[1-4]$":
+ type: object
+ $ref: regulator.yaml#
+
+ "^BUCK|BOOST$":
+ type: object
+ $ref: regulator.yaml#
+
+ additionalProperties: false
+
+required:
+ - compatible
+ - reg
+ - regulators
+
+additionalProperties: false
+
+examples:
+ - |
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ pmic@35 {
+ compatible = "onnn,fan53880";
+ reg = <0x35>;
+
+ PVIN-supply = <&fixreg_example_vcc>;
+
+ regulators {
+ BUCK {
+ regulator-min-microvolt = <1200000>;
+ regulator-max-microvolt = <1200000>;
+ };
+ };
+ };
+ };
+...
diff --git a/Documentation/devicetree/bindings/regulator/qcom,smd-rpm-regulator.txt b/Documentation/devicetree/bindings/regulator/qcom,smd-rpm-regulator.txt
deleted file mode 100644
index dea4384..0000000
--- a/Documentation/devicetree/bindings/regulator/qcom,smd-rpm-regulator.txt
+++ /dev/null
@@ -1,320 +0,0 @@
-QCOM SMD RPM REGULATOR
-
-The Qualcomm RPM over SMD regulator is modelled as a subdevice of the RPM.
-Because SMD is used as the communication transport mechanism, the RPM resides as
-a subnode of the SMD. As such, the SMD-RPM regulator requires that the SMD and
-RPM nodes be present.
-
-Please refer to Documentation/devicetree/bindings/soc/qcom/qcom,smd.txt for
-information pertaining to the SMD node.
-
-Please refer to Documentation/devicetree/bindings/soc/qcom/qcom,smd-rpm.txt for
-information regarding the RPM node.
-
-== Regulator
-
-Regulator nodes are identified by their compatible:
-
-- compatible:
- Usage: required
- Value type: <string>
- Definition: must be one of:
- "qcom,rpm-pm8841-regulators"
- "qcom,rpm-pm8916-regulators"
- "qcom,rpm-pm8941-regulators"
- "qcom,rpm-pm8950-regulators"
- "qcom,rpm-pm8994-regulators"
- "qcom,rpm-pm8998-regulators"
- "qcom,rpm-pma8084-regulators"
- "qcom,rpm-pmi8994-regulators"
- "qcom,rpm-pmi8998-regulators"
- "qcom,rpm-pms405-regulators"
-
-- vdd_s1-supply:
-- vdd_s2-supply:
-- vdd_s3-supply:
-- vdd_s4-supply:
-- vdd_s5-supply:
-- vdd_s6-supply:
-- vdd_s7-supply:
-- vdd_s8-supply:
- Usage: optional (pm8841 only)
- Value type: <phandle>
- Definition: reference to regulator supplying the input pin, as
- described in the data sheet
-
-- vdd_s1-supply:
-- vdd_s2-supply:
-- vdd_s3-supply:
-- vdd_s4-supply:
-- vdd_l1_l2_l3-supply:
-- vdd_l4_l5_l6-supply:
-- vdd_l7-supply:
-- vdd_l8_l9_l10_l11_l12_l13_l14_l15_l16_l17_l18-supply:
- Usage: optional (pm8916 only)
- Value type: <phandle>
- Definition: reference to regulator supplying the input pin, as
- described in the data sheet
-
-- vdd_s1-supply:
-- vdd_s2-supply:
-- vdd_s3-supply:
-- vdd_s4-supply:
-- vdd_s4-supply:
-- vdd_s5-supply:
-- vdd_s6-supply:
-- vdd_l1_l19-supply:
-- vdd_l2_l23-supply:
-- vdd_l3-supply:
-- vdd_l4_l5_l6_l7_l16-supply:
-- vdd_l8_l11_l12_l17_l22-supply:
-- vdd_l9_l10_l13_l14_l15_l18-supply:
-- vdd_l20-supply:
-- vdd_l21-supply:
- Usage: optional (pm8950 only)
- Value type: <phandle>
- Definition: reference to regulator supplying the input pin, as
- described in the data sheet
-
-- vdd_s1-supply:
-- vdd_s2-supply:
-- vdd_s3-supply:
-- vdd_l1_l3-supply:
-- vdd_l2_lvs1_2_3-supply:
-- vdd_l4_l11-supply:
-- vdd_l5_l7-supply:
-- vdd_l6_l12_l14_l15-supply:
-- vdd_l8_l16_l18_l19-supply:
-- vdd_l9_l10_l17_l22-supply:
-- vdd_l13_l20_l23_l24-supply:
-- vdd_l21-supply:
-- vin_5vs-supply:
- Usage: optional (pm8941 only)
- Value type: <phandle>
- Definition: reference to regulator supplying the input pin, as
- described in the data sheet
-
-- vdd_s1-supply:
-- vdd_s2-supply:
-- vdd_s3-supply:
-- vdd_s4-supply:
-- vdd_s5-supply:
-- vdd_s6-supply:
-- vdd_s7-supply:
-- vdd_s8-supply:
-- vdd_s9-supply:
-- vdd_s10-supply:
-- vdd_s11-supply:
-- vdd_s12-supply:
-- vdd_l1-supply:
-- vdd_l2_l26_l28-supply:
-- vdd_l3_l11-supply:
-- vdd_l4_l27_l31-supply:
-- vdd_l5_l7-supply:
-- vdd_l6_l12_l32-supply:
-- vdd_l5_l7-supply:
-- vdd_l8_l16_l30-supply:
-- vdd_l9_l10_l18_l22-supply:
-- vdd_l9_l10_l18_l22-supply:
-- vdd_l3_l11-supply:
-- vdd_l6_l12_l32-supply:
-- vdd_l13_l19_l23_l24-supply:
-- vdd_l14_l15-supply:
-- vdd_l14_l15-supply:
-- vdd_l8_l16_l30-supply:
-- vdd_l17_l29-supply:
-- vdd_l9_l10_l18_l22-supply:
-- vdd_l13_l19_l23_l24-supply:
-- vdd_l20_l21-supply:
-- vdd_l20_l21-supply:
-- vdd_l9_l10_l18_l22-supply:
-- vdd_l13_l19_l23_l24-supply:
-- vdd_l13_l19_l23_l24-supply:
-- vdd_l25-supply:
-- vdd_l2_l26_l28-supply:
-- vdd_l4_l27_l31-supply:
-- vdd_l2_l26_l28-supply:
-- vdd_l17_l29-supply:
-- vdd_l8_l16_l30-supply:
-- vdd_l4_l27_l31-supply:
-- vdd_l6_l12_l32-supply:
-- vdd_lvs1_2-supply:
- Usage: optional (pm8994 only)
- Value type: <phandle>
- Definition: reference to regulator supplying the input pin, as
- described in the data sheet
-
-- vdd_s1-supply:
-- vdd_s2-supply:
-- vdd_s3-supply:
-- vdd_bst_byp-supply:
- Usage: optional (pmi8994 only)
- Value type: <phandle>
- Definition: reference to regulator supplying the input pin, as
- described in the data sheet
-
-- vdd_s1-supply:
-- vdd_s2-supply:
-- vdd_s3-supply:
-- vdd_s4-supply:
-- vdd_s5-supply:
-- vdd_s6-supply:
-- vdd_s7-supply:
-- vdd_s8-supply:
-- vdd_s9-supply:
-- vdd_s10-supply:
-- vdd_s11-supply:
-- vdd_s12-supply:
-- vdd_s13-supply:
-- vdd_l1_l27-supply:
-- vdd_l20_l24-supply:
-- vdd_l26-supply:
-- vdd_l2_l8_l17-supply:
-- vdd_l3_l11-supply:
-- vdd_l4_l5-supply:
-- vdd_l6-supply:
-- vdd_l7_l12_l14_l15-supply:
-- vdd_l9-supply:
-- vdd_l10_l23_l25-supply:
-- vdd_l13_l19_l21-supply:
-- vdd_l16_l28-supply:
-- vdd_l18_l22-supply:
-- vdd_lvs1_lvs2-supply:
- Usage: optional (pmi8998 only)
- Value type: <phandle>
- Definition: reference to regulator supplying the input pin, as
- described in the data sheet
-
-- vdd_s1-supply:
-- vdd_s2-supply:
-- vdd_s3-supply:
-- vdd_s4-supply:
-- vdd_s5-supply:
-- vdd_s6-supply:
-- vdd_s7-supply:
-- vdd_s8-supply:
-- vdd_s9-supply:
-- vdd_s10-supply:
-- vdd_s11-supply:
-- vdd_s12-supply:
-- vdd_l1_l11-supply:
-- vdd_l2_l3_l4_l27-supply:
-- vdd_l5_l7-supply:
-- vdd_l6_l12_l14_l15_l26-supply:
-- vdd_l8-supply:
-- vdd_l9_l10_l13_l20_l23_l24-supply:
-- vdd_l16_l25-supply:
-- vdd_l17-supply:
-- vdd_l18-supply:
-- vdd_l19-supply:
-- vdd_l21-supply:
-- vdd_l22-supply:
- Usage: optional (pma8084 only)
- Value type: <phandle>
- Definition: reference to regulator supplying the input pin, as
- described in the data sheet
-
-- vdd_bob-supply:
- Usage: optional (pmi8998 only)
- Value type: <phandle>
- Definition: reference to regulator supplying the input pin, as
- described in the data sheet
-
-- vdd_s1-supply:
-- vdd_s2-supply:
-- vdd_s3-supply:
-- vdd_s4-supply:
-- vdd_s5-supply:
-- vdd_l1_l2-supply:
-- vdd_l3_l8-supply:
-- vdd_l4-supply:
-- vdd_l5_l6-supply:
-- vdd_l7-supply:
-- vdd_l3_l8-supply:
-- vdd_l9-supply:
-- vdd_l10_l11_l12_l13-supply:
- Usage: optional (pms405 only)
- Value type: <phandle>
- Definition: reference to regulator supplying the input pin, as
- described in the data sheet
-
-The regulator node houses sub-nodes for each regulator within the device. Each
-sub-node is identified using the node's name, with valid values listed for each
-of the pmics below.
-
-pm8841:
- s1, s2, s3, s4, s5, s6, s7, s8
-
-pm8916:
- s1, s2, s3, s4, l1, l2, l3, l4, l5, l6, l7, l8, l9, l10, l11, l12, l13,
- l14, l15, l16, l17, l18
-
-pm8941:
- s1, s2, s3, s4, l1, l2, l3, l4, l5, l6, l7, l8, l9, l10, l11, l12, l13,
- l14, l15, l16, l17, l18, l19, l20, l21, l22, l23, l24, lvs1, lvs2,
- lvs3, 5vs1, 5vs2
-
-pm8994:
- s1, s2, s3, s4, s5, s6, s7, s8, s9, s10, s11, s12, l1, l2, l3, l4, l5,
- l6, l7, l8, l9, l10, l11, l12, l13, l14, l15, l16, l17, l18, l19, l20,
- l21, l22, l23, l24, l25, l26, l27, l28, l29, l30, l31, l32, lvs1, lvs2
-
-pm8998:
- s1, s2, s3, s4, s5, s6, s7, s8, s9, s10, s11, s12, s13, l1, l2, l3, l4,
- l5, l6, l7, l8, l9, l10, l11, l12, l13, l14, l15, l16, l17, l18, l19,
- l20, l21, l22, l23, l24, l25, l26, l27, l28, lvs1, lvs2
-
-pma8084:
- s1, s2, s3, s4, s5, s6, s7, s8, s9, s10, s11, s12, l1, l2, l3, l4, l5,
- l6, l7, l8, l9, l10, l11, l12, l13, l14, l15, l16, l17, l18, l19, l20,
- l21, l22, l23, l24, l25, l26, l27, lvs1, lvs2, lvs3, lvs4, 5vs1
-
-pmi8994:
- s1, s2, s3, boost-bypass
-
-pmi8998:
- bob
-
-pms405:
- s1, s2, s3, s4, s5, l1, l2, l3, l4, l5, l6, l7, l8, l9, l10, l11, l12,
- l13
-
-The content of each sub-node is defined by the standard binding for regulators -
-see regulator.txt.
-
-= EXAMPLE
-
- smd {
- compatible = "qcom,smd";
-
- rpm {
- interrupts = <0 168 1>;
- qcom,ipc = <&apcs 8 0>;
- qcom,smd-edge = <15>;
-
- rpm_requests {
- compatible = "qcom,rpm-msm8974";
- qcom,smd-channels = "rpm_requests";
-
- pm8941-regulators {
- compatible = "qcom,rpm-pm8941-regulators";
- vdd_l13_l20_l23_l24-supply = <&pm8941_boost>;
-
- pm8941_s3: s3 {
- regulator-min-microvolt = <1800000>;
- regulator-max-microvolt = <1800000>;
- };
-
- pm8941_boost: s4 {
- regulator-min-microvolt = <5000000>;
- regulator-max-microvolt = <5000000>;
- };
-
- pm8941_l20: l20 {
- regulator-min-microvolt = <2950000>;
- regulator-max-microvolt = <2950000>;
- };
- };
- };
- };
- };
diff --git a/Documentation/devicetree/bindings/regulator/qcom,smd-rpm-regulator.yaml b/Documentation/devicetree/bindings/regulator/qcom,smd-rpm-regulator.yaml
new file mode 100644
index 0000000..d202220
--- /dev/null
+++ b/Documentation/devicetree/bindings/regulator/qcom,smd-rpm-regulator.yaml
@@ -0,0 +1,108 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/regulator/qcom,smd-rpm-regulator.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: QCOM SMD RPM REGULATOR
+
+description:
+ The Qualcomm RPM over SMD regulator is modelled as a subdevice of the RPM.
+ Because SMD is used as the communication transport mechanism, the RPM
+ resides as a subnode of the SMD. As such, the SMD-RPM regulator requires
+ that the SMD and RPM nodes be present.
+
+ Please refer to Documentation/devicetree/bindings/soc/qcom/qcom,smd.txt for
+ information pertaining to the SMD node.
+
+ Please refer to Documentation/devicetree/bindings/soc/qcom/qcom,smd-rpm.yaml
+ for information regarding the RPM node.
+
+ The regulator node houses sub-nodes for each regulator within the device.
+ Each sub-node is identified using the node's name, with valid values listed
+ for each of the pmics below.
+
+ For mp5496, s2
+
+ For pm8841, s1, s2, s3, s4, s5, s6, s7, s8
+
+ For pm8916, s1, s2, s3, s4, l1, l2, l3, l4, l5, l6, l7, l8, l9, l10, l11,
+ l12, l13, l14, l15, l16, l17, l18
+
+ For pm8941, s1, s2, s3, s4, l1, l2, l3, l4, l5, l6, l7, l8, l9, l10, l11,
+ l12, l13, l14, l15, l16, l17, l18, l19, l20, l21, l22, l23, l24, lvs1, lvs2,
+ lvs3, 5vs1, 5vs2
+
+ For pm8994, s1, s2, s3, s4, s5, s6, s7, s8, s9, s10, s11, s12, l1, l2, l3,
+ l4, l5, l6, l7, l8, l9, l10, l11, l12, l13, l14, l15, l16, l17, l18, l19,
+ l20, l21, l22, l23, l24, l25, l26, l27, l28, l29, l30, l31, l32, lvs1, lvs2
+
+ For pm8998, s1, s2, s3, s4, s5, s6, s7, s8, s9, s10, s11, s12, s13, l1, l2,
+ l3, l4, l5, l6, l7, l8, l9, l10, l11, l12, l13, l14, l15, l16, l17, l18, l19,
+ l20, l21, l22, l23, l24, l25, l26, l27, l28, lvs1, lvs2
+
+ For pma8084, s1, s2, s3, s4, s5, s6, s7, s8, s9, s10, s11, s12, l1, l2, l3,
+ l4, l5, l6, l7, l8, l9, l10, l11, l12, l13, l14, l15, l16, l17, l18, l19,
+ l20, l21, l22, l23, l24, l25, l26, l27, lvs1, lvs2, lvs3, lvs4, 5vs1
+
+ For pmi8994, s1, s2, s3, boost-bypass
+
+ For pmi8998, bob
+
+ For pms405, s1, s2, s3, s4, s5, l1, l2, l3, l4, l5, l6, l7, l8, l9, l10, l11,
+ l12, l13
+
+maintainers:
+ - Kathiravan T <kathirav@codeaurora.org>
+
+properties:
+ compatible:
+ enum:
+ - qcom,rpm-mp5496-regulators
+ - qcom,rpm-pm8841-regulators
+ - qcom,rpm-pm8916-regulators
+ - qcom,rpm-pm8941-regulators
+ - qcom,rpm-pm8950-regulators
+ - qcom,rpm-pm8994-regulators
+ - qcom,rpm-pm8998-regulators
+ - qcom,rpm-pma8084-regulators
+ - qcom,rpm-pmi8994-regulators
+ - qcom,rpm-pmi8998-regulators
+ - qcom,rpm-pms405-regulators
+
+patternProperties:
+ ".*-supply$":
+ description: Input supply phandle(s) for this node
+
+ "^((s|l|lvs|5vs)[0-9]*)|(boost-bypass)|(bob)$":
+ description: List of regulators and its properties
+ allOf:
+ - $ref: regulator.yaml#
+
+additionalProperties: false
+
+required:
+ - compatible
+
+examples:
+ - |
+ pm8941-regulators {
+ compatible = "qcom,rpm-pm8941-regulators";
+ vdd_l13_l20_l23_l24-supply = <&pm8941_boost>;
+
+ pm8941_s3: s3 {
+ regulator-min-microvolt = <1800000>;
+ regulator-max-microvolt = <1800000>;
+ };
+
+ pm8941_boost: s4 {
+ regulator-min-microvolt = <5000000>;
+ regulator-max-microvolt = <5000000>;
+ };
+
+ pm8941_l20: l20 {
+ regulator-min-microvolt = <2950000>;
+ regulator-max-microvolt = <2950000>;
+ };
+ };
+...
diff --git a/Documentation/devicetree/bindings/regulator/qcom,usb-vbus-regulator.yaml b/Documentation/devicetree/bindings/regulator/qcom,usb-vbus-regulator.yaml
new file mode 100644
index 0000000..12ed98c
--- /dev/null
+++ b/Documentation/devicetree/bindings/regulator/qcom,usb-vbus-regulator.yaml
@@ -0,0 +1,41 @@
+# SPDX-License-Identifier: GPL-2.0
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/regulator/qcom,usb-vbus-regulator.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: The Qualcomm PMIC VBUS output regulator driver
+
+maintainers:
+ - Wesley Cheng <wcheng@codeaurora.org>
+
+description: |
+ This regulator driver controls the VBUS output by the Qualcomm PMIC. This
+ regulator will be enabled in situations where the device is required to
+ provide power to the connected peripheral.
+
+properties:
+ compatible:
+ enum:
+ - qcom,pm8150b-vbus-reg
+
+ reg:
+ maxItems: 1
+ description: VBUS output base address
+
+required:
+ - compatible
+
+additionalProperties: false
+
+examples:
+ - |
+ pm8150b {
+ #address-cells = <1>;
+ #size-cells = <0>;
+ pm8150b_vbus: dcdc@1100 {
+ compatible = "qcom,pm8150b-vbus-reg";
+ reg = <0x1100>;
+ };
+ };
+...
diff --git a/Documentation/devicetree/bindings/regulator/qcom-labibb-regulator.yaml b/Documentation/devicetree/bindings/regulator/qcom-labibb-regulator.yaml
new file mode 100644
index 0000000..085cbd1
--- /dev/null
+++ b/Documentation/devicetree/bindings/regulator/qcom-labibb-regulator.yaml
@@ -0,0 +1,70 @@
+# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/regulator/qcom-labibb-regulator.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Qualcomm's LAB(LCD AMOLED Boost)/IBB(Inverting Buck Boost) Regulator
+
+maintainers:
+ - Sumit Semwal <sumit.semwal@linaro.org>
+
+description:
+ LAB can be used as a positive boost power supply and IBB can be used as a
+ negative boost power supply for display panels. Currently implemented for
+ pmi8998.
+
+properties:
+ compatible:
+ const: qcom,pmi8998-lab-ibb
+
+ lab:
+ type: object
+
+ properties:
+
+ interrupts:
+ maxItems: 1
+ description:
+ Short-circuit interrupt for lab.
+
+ required:
+ - interrupts
+
+ ibb:
+ type: object
+
+ properties:
+
+ interrupts:
+ maxItems: 1
+ description:
+ Short-circuit interrupt for lab.
+
+ required:
+ - interrupts
+
+required:
+ - compatible
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/irq.h>
+
+ labibb {
+ compatible = "qcom,pmi8998-lab-ibb";
+
+ lab {
+ interrupts = <0x3 0x0 IRQ_TYPE_EDGE_RISING>;
+ interrupt-names = "sc-err";
+ };
+
+ ibb {
+ interrupts = <0x3 0x2 IRQ_TYPE_EDGE_RISING>;
+ interrupt-names = "sc-err";
+ };
+ };
+
+...
diff --git a/Documentation/devicetree/bindings/regulator/silergy,sy8827n.yaml b/Documentation/devicetree/bindings/regulator/silergy,sy8827n.yaml
new file mode 100644
index 0000000..15983cd
--- /dev/null
+++ b/Documentation/devicetree/bindings/regulator/silergy,sy8827n.yaml
@@ -0,0 +1,45 @@
+# SPDX-License-Identifier: GPL-2.0
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/regulator/silergy,sy8827n.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: silergy sy8827n PMIC
+
+maintainers:
+ - Jisheng Zhang <jszhang@kernel.org>
+
+properties:
+ compatible:
+ enum:
+ - silergy,sy8827n
+
+ reg:
+ maxItems: 1
+
+ enable-gpios:
+ description: GPIO to enable/disable the regulator.
+ maxItems: 1
+
+ silergy,vsel-state-high:
+ type: boolean
+ description:
+ Indicates if the VSEL pin is set to high.
+ If this property is missing, assume the VSEL pin is set to low.
+
+required:
+ - compatible
+ - reg
+
+examples:
+ - |
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+ regulator@60 {
+ compatible = "silergy,sy8827n";
+ reg = <0x60>;
+ };
+ };
+
+...
diff --git a/Documentation/devicetree/bindings/remoteproc/qcom,pil-info.yaml b/Documentation/devicetree/bindings/remoteproc/qcom,pil-info.yaml
new file mode 100644
index 0000000..87c5231
--- /dev/null
+++ b/Documentation/devicetree/bindings/remoteproc/qcom,pil-info.yaml
@@ -0,0 +1,44 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/remoteproc/qcom,pil-info.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Qualcomm peripheral image loader relocation info binding
+
+maintainers:
+ - Bjorn Andersson <bjorn.andersson@linaro.org>
+
+description:
+ The Qualcomm peripheral image loader relocation memory region, in IMEM, is
+ used for communicating remoteproc relocation information to post mortem
+ debugging tools.
+
+properties:
+ compatible:
+ const: qcom,pil-reloc-info
+
+ reg:
+ maxItems: 1
+
+required:
+ - compatible
+ - reg
+
+examples:
+ - |
+ imem@146bf000 {
+ compatible = "syscon", "simple-mfd";
+ reg = <0x146bf000 0x1000>;
+
+ #address-cells = <1>;
+ #size-cells = <1>;
+
+ ranges = <0 0x146bf000 0x1000>;
+
+ pil-reloc@94c {
+ compatible = "qcom,pil-reloc-info";
+ reg = <0x94c 0xc8>;
+ };
+ };
+...
diff --git a/Documentation/devicetree/bindings/remoteproc/ti,k3-dsp-rproc.yaml b/Documentation/devicetree/bindings/remoteproc/ti,k3-dsp-rproc.yaml
new file mode 100644
index 0000000..24b0c50
--- /dev/null
+++ b/Documentation/devicetree/bindings/remoteproc/ti,k3-dsp-rproc.yaml
@@ -0,0 +1,184 @@
+# SPDX-License-Identifier: (GPL-2.0-only or BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/remoteproc/ti,k3-dsp-rproc.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: TI K3 DSP devices
+
+maintainers:
+ - Suman Anna <s-anna@ti.com>
+
+description: |
+ The TI K3 family of SoCs usually have one or more TI DSP Core sub-systems
+ that are used to offload some of the processor-intensive tasks or algorithms,
+ for achieving various system level goals.
+
+ These processor sub-systems usually contain additional sub-modules like
+ L1 and/or L2 caches/SRAMs, an Interrupt Controller, an external memory
+ controller, a dedicated local power/sleep controller etc. The DSP processor
+ cores in the K3 SoCs are usually either a TMS320C66x CorePac processor or a
+ TMS320C71x CorePac processor.
+
+ Each DSP Core sub-system is represented as a single DT node. Each node has a
+ number of required or optional properties that enable the OS running on the
+ host processor (Arm CorePac) to perform the device management of the remote
+ processor and to communicate with the remote processor.
+
+allOf:
+ - $ref: /schemas/arm/keystone/ti,k3-sci-common.yaml#
+
+properties:
+ compatible:
+ enum:
+ - ti,j721e-c66-dsp
+ - ti,j721e-c71-dsp
+ description:
+ Use "ti,j721e-c66-dsp" for C66x DSPs on K3 J721E SoCs
+ Use "ti,j721e-c71-dsp" for C71x DSPs on K3 J721E SoCs
+
+ resets:
+ description: |
+ Should contain the phandle to the reset controller node managing the
+ local resets for this device, and a reset specifier.
+ maxItems: 1
+
+ firmware-name:
+ description: |
+ Should contain the name of the default firmware image
+ file located on the firmware search path
+
+ mboxes:
+ description: |
+ OMAP Mailbox specifier denoting the sub-mailbox, to be used for
+ communication with the remote processor. This property should match
+ with the sub-mailbox node used in the firmware image.
+ maxItems: 1
+
+ memory-region:
+ minItems: 2
+ maxItems: 8
+ description: |
+ phandle to the reserved memory nodes to be associated with the remoteproc
+ device. There should be at least two reserved memory nodes defined. The
+ reserved memory nodes should be carveout nodes, and should be defined as
+ per the bindings in
+ Documentation/devicetree/bindings/reserved-memory/reserved-memory.txt
+ items:
+ - description: region used for dynamic DMA allocations like vrings and
+ vring buffers
+ - description: region reserved for firmware image sections
+ additionalItems: true
+
+# Optional properties:
+# --------------------
+
+ sram:
+ $ref: /schemas/types.yaml#/definitions/phandle-array
+ minItems: 1
+ maxItems: 4
+ description: |
+ phandles to one or more reserved on-chip SRAM regions. The regions
+ should be defined as child nodes of the respective SRAM node, and
+ should be defined as per the generic bindings in,
+ Documentation/devicetree/bindings/sram/sram.yaml
+
+if:
+ properties:
+ compatible:
+ enum:
+ - ti,j721e-c66-dsp
+then:
+ properties:
+ reg:
+ items:
+ - description: Address and Size of the L2 SRAM internal memory region
+ - description: Address and Size of the L1 PRAM internal memory region
+ - description: Address and Size of the L1 DRAM internal memory region
+ reg-names:
+ items:
+ - const: l2sram
+ - const: l1pram
+ - const: l1dram
+else:
+ if:
+ properties:
+ compatible:
+ enum:
+ - ti,j721e-c71-dsp
+ then:
+ properties:
+ reg:
+ items:
+ - description: Address and Size of the L2 SRAM internal memory region
+ - description: Address and Size of the L1 DRAM internal memory region
+ reg-names:
+ items:
+ - const: l2sram
+ - const: l1dram
+
+required:
+ - compatible
+ - reg
+ - reg-names
+ - ti,sci
+ - ti,sci-dev-id
+ - ti,sci-proc-ids
+ - resets
+ - firmware-name
+ - mboxes
+ - memory-region
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ / {
+ model = "Texas Instruments K3 J721E SoC";
+ compatible = "ti,j721e";
+ #address-cells = <2>;
+ #size-cells = <2>;
+
+ bus@100000 {
+ compatible = "simple-bus";
+ #address-cells = <2>;
+ #size-cells = <2>;
+ ranges = <0x00 0x00100000 0x00 0x00100000 0x00 0x00020000>, /* ctrl mmr */
+ <0x00 0x64800000 0x00 0x64800000 0x00 0x00800000>, /* C71_0 */
+ <0x4d 0x80800000 0x4d 0x80800000 0x00 0x00800000>, /* C66_0 */
+ <0x4d 0x81800000 0x4d 0x81800000 0x00 0x00800000>; /* C66_1 */
+
+ /* J721E C66_0 DSP node */
+ dsp@4d80800000 {
+ compatible = "ti,j721e-c66-dsp";
+ reg = <0x4d 0x80800000 0x00 0x00048000>,
+ <0x4d 0x80e00000 0x00 0x00008000>,
+ <0x4d 0x80f00000 0x00 0x00008000>;
+ reg-names = "l2sram", "l1pram", "l1dram";
+ ti,sci = <&dmsc>;
+ ti,sci-dev-id = <142>;
+ ti,sci-proc-ids = <0x03 0xFF>;
+ resets = <&k3_reset 142 1>;
+ firmware-name = "j7-c66_0-fw";
+ memory-region = <&c66_0_dma_memory_region>,
+ <&c66_0_memory_region>;
+ mboxes = <&mailbox0_cluster3 &mbox_c66_0>;
+ };
+
+ /* J721E C71_0 DSP node */
+ c71_0: dsp@64800000 {
+ compatible = "ti,j721e-c71-dsp";
+ reg = <0x00 0x64800000 0x00 0x00080000>,
+ <0x00 0x64e00000 0x00 0x0000c000>;
+ reg-names = "l2sram", "l1dram";
+ ti,sci = <&dmsc>;
+ ti,sci-dev-id = <15>;
+ ti,sci-proc-ids = <0x30 0xFF>;
+ resets = <&k3_reset 15 1>;
+ firmware-name = "j7-c71_0-fw";
+ memory-region = <&c71_0_dma_memory_region>,
+ <&c71_0_memory_region>;
+ mboxes = <&mailbox0_cluster4 &mbox_c71_0>;
+ };
+ };
+ };
diff --git a/Documentation/devicetree/bindings/reset/fsl,imx-src.txt b/Documentation/devicetree/bindings/reset/fsl,imx-src.txt
deleted file mode 100644
index 6ed79e6..0000000
--- a/Documentation/devicetree/bindings/reset/fsl,imx-src.txt
+++ /dev/null
@@ -1,49 +0,0 @@
-Freescale i.MX System Reset Controller
-======================================
-
-Please also refer to reset.txt in this directory for common reset
-controller binding usage.
-
-Required properties:
-- compatible: Should be "fsl,<chip>-src"
-- reg: should be register base and length as documented in the
- datasheet
-- interrupts: Should contain SRC interrupt and CPU WDOG interrupt,
- in this order.
-- #reset-cells: 1, see below
-
-example:
-
-src: src@20d8000 {
- compatible = "fsl,imx6q-src";
- reg = <0x020d8000 0x4000>;
- interrupts = <0 91 0x04 0 96 0x04>;
- #reset-cells = <1>;
-};
-
-Specifying reset lines connected to IP modules
-==============================================
-
-The system reset controller can be used to reset the GPU, VPU,
-IPU, and OpenVG IP modules on i.MX5 and i.MX6 ICs. Those device
-nodes should specify the reset line on the SRC in their resets
-property, containing a phandle to the SRC device node and a
-RESET_INDEX specifying which module to reset, as described in
-reset.txt
-
-example:
-
- ipu1: ipu@2400000 {
- resets = <&src 2>;
- };
- ipu2: ipu@2800000 {
- resets = <&src 4>;
- };
-
-The following RESET_INDEX values are valid for i.MX5:
-GPU_RESET 0
-VPU_RESET 1
-IPU1_RESET 2
-OPEN_VG_RESET 3
-The following additional RESET_INDEX value is valid for i.MX6:
-IPU2_RESET 4
diff --git a/Documentation/devicetree/bindings/reset/fsl,imx-src.yaml b/Documentation/devicetree/bindings/reset/fsl,imx-src.yaml
new file mode 100644
index 0000000..27c5e34
--- /dev/null
+++ b/Documentation/devicetree/bindings/reset/fsl,imx-src.yaml
@@ -0,0 +1,82 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/reset/fsl,imx-src.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Freescale i.MX System Reset Controller
+
+maintainers:
+ - Philipp Zabel <p.zabel@pengutronix.de>
+
+description: |
+ The system reset controller can be used to reset the GPU, VPU,
+ IPU, and OpenVG IP modules on i.MX5 and i.MX6 ICs. Those device
+ nodes should specify the reset line on the SRC in their resets
+ property, containing a phandle to the SRC device node and a
+ RESET_INDEX specifying which module to reset, as described in
+ reset.txt
+
+ The following RESET_INDEX values are valid for i.MX5:
+ GPU_RESET 0
+ VPU_RESET 1
+ IPU1_RESET 2
+ OPEN_VG_RESET 3
+ The following additional RESET_INDEX value is valid for i.MX6:
+ IPU2_RESET 4
+
+properties:
+ compatible:
+ oneOf:
+ - const: "fsl,imx51-src"
+ - items:
+ - const: "fsl,imx50-src"
+ - const: "fsl,imx51-src"
+ - items:
+ - const: "fsl,imx53-src"
+ - const: "fsl,imx51-src"
+ - items:
+ - const: "fsl,imx6q-src"
+ - const: "fsl,imx51-src"
+ - items:
+ - const: "fsl,imx6sx-src"
+ - const: "fsl,imx51-src"
+ - items:
+ - const: "fsl,imx6sl-src"
+ - const: "fsl,imx51-src"
+ - items:
+ - const: "fsl,imx6ul-src"
+ - const: "fsl,imx51-src"
+ - items:
+ - const: "fsl,imx6sll-src"
+ - const: "fsl,imx51-src"
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ items:
+ - description: SRC interrupt
+ - description: CPU WDOG interrupts out of SRC
+ minItems: 1
+ maxItems: 2
+
+ '#reset-cells':
+ const: 1
+
+required:
+ - compatible
+ - reg
+ - interrupts
+ - '#reset-cells'
+
+additionalProperties: false
+
+examples:
+ - |
+ reset-controller@73fd0000 {
+ compatible = "fsl,imx51-src";
+ reg = <0x73fd0000 0x4000>;
+ interrupts = <75>;
+ #reset-cells = <1>;
+ };
diff --git a/Documentation/devicetree/bindings/reset/fsl,imx7-src.txt b/Documentation/devicetree/bindings/reset/fsl,imx7-src.txt
deleted file mode 100644
index e10502d..0000000
--- a/Documentation/devicetree/bindings/reset/fsl,imx7-src.txt
+++ /dev/null
@@ -1,56 +0,0 @@
-Freescale i.MX7 System Reset Controller
-======================================
-
-Please also refer to reset.txt in this directory for common reset
-controller binding usage.
-
-Required properties:
-- 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"
- - For i.MX8MN SoCs should be "fsl,imx8mn-src", "fsl,imx8mq-src", "syscon"
- - For i.MX8MP SoCs should be "fsl,imx8mp-src", "syscon"
-- reg: should be register base and length as documented in the
- datasheet
-- interrupts: Should contain SRC interrupt
-- #reset-cells: 1, see below
-
-example:
-
-src: reset-controller@30390000 {
- compatible = "fsl,imx7d-src", "syscon";
- reg = <0x30390000 0x2000>;
- interrupts = <GIC_SPI 89 IRQ_TYPE_LEVEL_HIGH>;
- #reset-cells = <1>;
-};
-
-
-Specifying reset lines connected to IP modules
-==============================================
-
-The system reset controller can be used to reset various set of
-peripherals. Device nodes that need access to reset lines should
-specify them as a reset phandle in their corresponding node as
-specified in reset.txt.
-
-Example:
-
- pcie: pcie@33800000 {
-
- ...
-
- resets = <&src IMX7_RESET_PCIEPHY>,
- <&src IMX7_RESET_PCIE_CTRL_APPS_EN>;
- reset-names = "pciephy", "apps";
-
- ...
- };
-
-
-For list of all valid reset indices see
-<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 and
-<dt-bindings/reset/imx8mq-reset.h> for i.MX8MN and
-<dt-bindings/reset/imx8mp-reset.h> for i.MX8MP
diff --git a/Documentation/devicetree/bindings/reset/fsl,imx7-src.yaml b/Documentation/devicetree/bindings/reset/fsl,imx7-src.yaml
new file mode 100644
index 0000000..b1a71c1
--- /dev/null
+++ b/Documentation/devicetree/bindings/reset/fsl,imx7-src.yaml
@@ -0,0 +1,58 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/reset/fsl,imx7-src.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Freescale i.MX7 System Reset Controller
+
+maintainers:
+ - Andrey Smirnov <andrew.smirnov@gmail.com>
+
+description: |
+ The system reset controller can be used to reset various set of
+ peripherals. Device nodes that need access to reset lines should
+ specify them as a reset phandle in their corresponding node as
+ specified in reset.txt.
+
+ For list of all valid reset indices see
+ <dt-bindings/reset/imx7-reset.h> for i.MX7,
+ <dt-bindings/reset/imx8mq-reset.h> for i.MX8MQ, i.MX8MM and i.MX8MN,
+ <dt-bindings/reset/imx8mp-reset.h> for i.MX8MP.
+
+properties:
+ compatible:
+ items:
+ - enum:
+ - fsl,imx7d-src
+ - fsl,imx8mq-src
+ - fsl,imx8mp-src
+ - const: syscon
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+ '#reset-cells':
+ const: 1
+
+required:
+ - compatible
+ - reg
+ - interrupts
+ - '#reset-cells'
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+
+ reset-controller@30390000 {
+ compatible = "fsl,imx7d-src", "syscon";
+ reg = <0x30390000 0x2000>;
+ interrupts = <GIC_SPI 89 IRQ_TYPE_LEVEL_HIGH>;
+ #reset-cells = <1>;
+ };
diff --git a/Documentation/devicetree/bindings/reset/renesas,rst.yaml b/Documentation/devicetree/bindings/reset/renesas,rst.yaml
index 4c2b429..2849ce4 100644
--- a/Documentation/devicetree/bindings/reset/renesas,rst.yaml
+++ b/Documentation/devicetree/bindings/reset/renesas,rst.yaml
@@ -31,6 +31,7 @@
- renesas,r8a774a1-rst # RZ/G2M
- renesas,r8a774b1-rst # RZ/G2N
- renesas,r8a774c0-rst # RZ/G2E
+ - renesas,r8a774e1-rst # RZ/G2H
- renesas,r8a7778-reset-wdt # R-Car M1A
- renesas,r8a7779-reset-wdt # R-Car H1
- renesas,r8a7790-rst # R-Car H2
diff --git a/Documentation/devicetree/bindings/reset/socionext,uniphier-reset.yaml b/Documentation/devicetree/bindings/reset/socionext,uniphier-reset.yaml
new file mode 100644
index 0000000..4c9b0eb
--- /dev/null
+++ b/Documentation/devicetree/bindings/reset/socionext,uniphier-reset.yaml
@@ -0,0 +1,112 @@
+# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/reset/socionext,uniphier-reset.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: UniPhier reset controller
+
+maintainers:
+ - Masahiro Yamada <yamada.masahiro@socionext.com>
+
+properties:
+ compatible:
+ oneOf:
+ - description: System reset
+ enum:
+ - socionext,uniphier-ld4-reset
+ - socionext,uniphier-pro4-reset
+ - socionext,uniphier-sld8-reset
+ - socionext,uniphier-pro5-reset
+ - socionext,uniphier-pxs2-reset
+ - socionext,uniphier-ld6b-reset
+ - socionext,uniphier-ld11-reset
+ - socionext,uniphier-ld20-reset
+ - socionext,uniphier-pxs3-reset
+ - description: Media I/O (MIO) reset, SD reset
+ enum:
+ - socionext,uniphier-ld4-mio-reset
+ - socionext,uniphier-pro4-mio-reset
+ - socionext,uniphier-sld8-mio-reset
+ - socionext,uniphier-pro5-sd-reset
+ - socionext,uniphier-pxs2-sd-reset
+ - socionext,uniphier-ld11-mio-reset
+ - socionext,uniphier-ld11-sd-reset
+ - socionext,uniphier-ld20-sd-reset
+ - socionext,uniphier-pxs3-sd-reset
+ - description: Peripheral reset
+ enum:
+ - socionext,uniphier-ld4-peri-reset
+ - socionext,uniphier-pro4-peri-reset
+ - socionext,uniphier-sld8-peri-reset
+ - socionext,uniphier-pro5-peri-reset
+ - socionext,uniphier-pxs2-peri-reset
+ - socionext,uniphier-ld11-peri-reset
+ - socionext,uniphier-ld20-peri-reset
+ - socionext,uniphier-pxs3-peri-reset
+ - description: Analog signal amplifier reset
+ enum:
+ - socionext,uniphier-ld11-adamv-reset
+ - socionext,uniphier-ld20-adamv-reset
+
+ "#reset-cells":
+ const: 1
+
+additionalProperties: false
+
+required:
+ - compatible
+ - "#reset-cells"
+
+examples:
+ - |
+ sysctrl@61840000 {
+ compatible = "socionext,uniphier-sysctrl", "simple-mfd", "syscon";
+ reg = <0x61840000 0x4000>;
+
+ reset {
+ compatible = "socionext,uniphier-ld11-reset";
+ #reset-cells = <1>;
+ };
+
+ // other nodes ...
+ };
+
+ - |
+ mioctrl@59810000 {
+ compatible = "socionext,uniphier-mioctrl", "simple-mfd", "syscon";
+ reg = <0x59810000 0x800>;
+
+ reset {
+ compatible = "socionext,uniphier-ld11-mio-reset";
+ #reset-cells = <1>;
+ };
+
+ // other nodes ...
+ };
+
+ - |
+ perictrl@59820000 {
+ compatible = "socionext,uniphier-perictrl", "simple-mfd", "syscon";
+ reg = <0x59820000 0x200>;
+
+ reset {
+ compatible = "socionext,uniphier-ld11-peri-reset";
+ #reset-cells = <1>;
+ };
+
+ // other nodes ...
+ };
+
+ - |
+ adamv@57920000 {
+ compatible = "socionext,uniphier-ld11-adamv", "simple-mfd", "syscon";
+ reg = <0x57920000 0x1000>;
+
+ reset {
+ compatible = "socionext,uniphier-ld11-adamv-reset";
+ #reset-cells = <1>;
+ };
+
+ // other nodes ...
+ };
diff --git a/Documentation/devicetree/bindings/reset/uniphier-reset.txt b/Documentation/devicetree/bindings/reset/uniphier-reset.txt
index e320a8c..88e06e5 100644
--- a/Documentation/devicetree/bindings/reset/uniphier-reset.txt
+++ b/Documentation/devicetree/bindings/reset/uniphier-reset.txt
@@ -1,123 +1,4 @@
-UniPhier reset controller
-
-
-System reset
-------------
-
-Required properties:
-- compatible: should be one of the following:
- "socionext,uniphier-ld4-reset" - for LD4 SoC
- "socionext,uniphier-pro4-reset" - for Pro4 SoC
- "socionext,uniphier-sld8-reset" - for sLD8 SoC
- "socionext,uniphier-pro5-reset" - for Pro5 SoC
- "socionext,uniphier-pxs2-reset" - for PXs2/LD6b SoC
- "socionext,uniphier-ld11-reset" - for LD11 SoC
- "socionext,uniphier-ld20-reset" - for LD20 SoC
- "socionext,uniphier-pxs3-reset" - for PXs3 SoC
-- #reset-cells: should be 1.
-
-Example:
-
- sysctrl@61840000 {
- compatible = "socionext,uniphier-ld11-sysctrl",
- "simple-mfd", "syscon";
- reg = <0x61840000 0x4000>;
-
- reset {
- compatible = "socionext,uniphier-ld11-reset";
- #reset-cells = <1>;
- };
-
- other nodes ...
- };
-
-
-Media I/O (MIO) reset, SD reset
--------------------------------
-
-Required properties:
-- compatible: should be one of the following:
- "socionext,uniphier-ld4-mio-reset" - for LD4 SoC
- "socionext,uniphier-pro4-mio-reset" - for Pro4 SoC
- "socionext,uniphier-sld8-mio-reset" - for sLD8 SoC
- "socionext,uniphier-pro5-sd-reset" - for Pro5 SoC
- "socionext,uniphier-pxs2-sd-reset" - for PXs2/LD6b SoC
- "socionext,uniphier-ld11-mio-reset" - for LD11 SoC (MIO)
- "socionext,uniphier-ld11-sd-reset" - for LD11 SoC (SD)
- "socionext,uniphier-ld20-sd-reset" - for LD20 SoC
- "socionext,uniphier-pxs3-sd-reset" - for PXs3 SoC
-- #reset-cells: should be 1.
-
-Example:
-
- mioctrl@59810000 {
- compatible = "socionext,uniphier-ld11-mioctrl",
- "simple-mfd", "syscon";
- reg = <0x59810000 0x800>;
-
- reset {
- compatible = "socionext,uniphier-ld11-mio-reset";
- #reset-cells = <1>;
- };
-
- other nodes ...
- };
-
-
-Peripheral reset
-----------------
-
-Required properties:
-- compatible: should be one of the following:
- "socionext,uniphier-ld4-peri-reset" - for LD4 SoC
- "socionext,uniphier-pro4-peri-reset" - for Pro4 SoC
- "socionext,uniphier-sld8-peri-reset" - for sLD8 SoC
- "socionext,uniphier-pro5-peri-reset" - for Pro5 SoC
- "socionext,uniphier-pxs2-peri-reset" - for PXs2/LD6b SoC
- "socionext,uniphier-ld11-peri-reset" - for LD11 SoC
- "socionext,uniphier-ld20-peri-reset" - for LD20 SoC
- "socionext,uniphier-pxs3-peri-reset" - for PXs3 SoC
-- #reset-cells: should be 1.
-
-Example:
-
- perictrl@59820000 {
- compatible = "socionext,uniphier-ld11-perictrl",
- "simple-mfd", "syscon";
- reg = <0x59820000 0x200>;
-
- reset {
- compatible = "socionext,uniphier-ld11-peri-reset";
- #reset-cells = <1>;
- };
-
- other nodes ...
- };
-
-
-Analog signal amplifier reset
------------------------------
-
-Required properties:
-- compatible: should be one of the following:
- "socionext,uniphier-ld11-adamv-reset" - for LD11 SoC
- "socionext,uniphier-ld20-adamv-reset" - for LD20 SoC
-- #reset-cells: should be 1.
-
-Example:
-
- adamv@57920000 {
- compatible = "socionext,uniphier-ld11-adamv",
- "simple-mfd", "syscon";
- reg = <0x57920000 0x1000>;
-
- adamv_rst: reset {
- compatible = "socionext,uniphier-ld11-adamv-reset";
- #reset-cells = <1>;
- };
-
- other nodes ...
- };
+UniPhier glue reset controller
Peripheral core reset in glue layer
diff --git a/Documentation/devicetree/bindings/rng/imx-rng.txt b/Documentation/devicetree/bindings/rng/imx-rng.txt
index 405c2b0..659d4ef 100644
--- a/Documentation/devicetree/bindings/rng/imx-rng.txt
+++ b/Documentation/devicetree/bindings/rng/imx-rng.txt
@@ -5,6 +5,9 @@
"fsl,imx21-rnga"
"fsl,imx31-rnga" (backward compatible with "fsl,imx21-rnga")
"fsl,imx25-rngb"
+ "fsl,imx6sl-rngb" (backward compatible with "fsl,imx25-rngb")
+ "fsl,imx6sll-rngb" (backward compatible with "fsl,imx25-rngb")
+ "fsl,imx6ull-rngb" (backward compatible with "fsl,imx25-rngb")
"fsl,imx35-rngc"
- reg : offset and length of the register set of this block
- interrupts : the interrupt number for the RNG block
diff --git a/Documentation/devicetree/bindings/rng/ingenic,rng.yaml b/Documentation/devicetree/bindings/rng/ingenic,rng.yaml
new file mode 100644
index 0000000..b2e4a6a
--- /dev/null
+++ b/Documentation/devicetree/bindings/rng/ingenic,rng.yaml
@@ -0,0 +1,36 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/rng/ingenic,rng.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Bindings for RNG in Ingenic SoCs
+
+maintainers:
+ - 周琰杰 (Zhou Yanjie) <zhouyanjie@wanyeetech.com>
+
+description:
+ The Random Number Generator in Ingenic SoCs.
+
+properties:
+ compatible:
+ enum:
+ - ingenic,jz4780-rng
+ - ingenic,x1000-rng
+
+ reg:
+ maxItems: 1
+
+required:
+ - compatible
+ - reg
+
+additionalProperties: false
+
+examples:
+ - |
+ rng: rng@d8 {
+ compatible = "ingenic,jz4780-rng";
+ reg = <0xd8 0x8>;
+ };
+...
diff --git a/Documentation/devicetree/bindings/rng/silex-insight,ba431-rng.yaml b/Documentation/devicetree/bindings/rng/silex-insight,ba431-rng.yaml
new file mode 100644
index 0000000..48ab82a
--- /dev/null
+++ b/Documentation/devicetree/bindings/rng/silex-insight,ba431-rng.yaml
@@ -0,0 +1,36 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/rng/silex-insight,ba431-rng.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Silex Insight BA431 RNG bindings
+
+description: |
+ The BA431 hardware random number generator is an IP that is FIPS-140-2/3
+ certified.
+
+maintainers:
+ - Olivier Sobrie <olivier.sobrie@silexinsight.com>
+
+properties:
+ compatible:
+ const: silex-insight,ba431-rng
+
+ reg:
+ maxItems: 1
+
+required:
+ - compatible
+ - reg
+
+additionalProperties: false
+
+examples:
+ - |
+ rng@42800000 {
+ compatible = "silex-insight,ba431-rng";
+ reg = <0x42800000 0x1000>;
+ };
+
+...
diff --git a/Documentation/devicetree/bindings/rtc/atmel,at91sam9-rtc.txt b/Documentation/devicetree/bindings/rtc/atmel,at91sam9-rtc.txt
index 6ae79d1..3f0e2a5 100644
--- a/Documentation/devicetree/bindings/rtc/atmel,at91sam9-rtc.txt
+++ b/Documentation/devicetree/bindings/rtc/atmel,at91sam9-rtc.txt
@@ -1,7 +1,9 @@
Atmel AT91SAM9260 Real Time Timer
Required properties:
-- compatible: should be: "atmel,at91sam9260-rtt"
+- compatible: should be one of the following:
+ - "atmel,at91sam9260-rtt"
+ - "microchip,sam9x60-rtt", "atmel,at91sam9260-rtt"
- reg: should encode the memory region of the RTT controller
- interrupts: rtt alarm/event interrupt
- clocks: should contain the 32 KHz slow clk that will drive the RTT block.
diff --git a/Documentation/devicetree/bindings/rtc/imxdi-rtc.txt b/Documentation/devicetree/bindings/rtc/imxdi-rtc.txt
deleted file mode 100644
index c797bc9..0000000
--- a/Documentation/devicetree/bindings/rtc/imxdi-rtc.txt
+++ /dev/null
@@ -1,20 +0,0 @@
-* i.MX25 Real Time Clock controller
-
-Required properties:
-- compatible: should be: "fsl,imx25-rtc"
-- reg: physical base address of the controller and length of memory mapped
- region.
-- clocks: should contain the phandle for the rtc clock
-- interrupts: rtc alarm interrupt
-
-Optional properties:
-- interrupts: dryice security violation interrupt (second entry)
-
-Example:
-
-rtc@53ffc000 {
- compatible = "fsl,imx25-rtc";
- reg = <0x53ffc000 0x4000>;
- clocks = <&clks 81>;
- interrupts = <25 56>;
-};
diff --git a/Documentation/devicetree/bindings/rtc/imxdi-rtc.yaml b/Documentation/devicetree/bindings/rtc/imxdi-rtc.yaml
new file mode 100644
index 0000000..06bd737
--- /dev/null
+++ b/Documentation/devicetree/bindings/rtc/imxdi-rtc.yaml
@@ -0,0 +1,44 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/rtc/imxdi-rtc.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: i.MX25 Real Time Clock controller
+
+maintainers:
+ - Roland Stigge <stigge@antcom.de>
+
+properties:
+ compatible:
+ const: fsl,imx25-rtc
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ items:
+ - description: rtc alarm interrupt
+ - description: dryice security violation interrupt
+ minItems: 1
+ maxItems: 2
+
+ clocks:
+ maxItems: 1
+
+required:
+ - compatible
+ - reg
+ - interrupts
+ - clocks
+
+additionalProperties: false
+
+examples:
+ - |
+ rtc@53ffc000 {
+ compatible = "fsl,imx25-rtc";
+ reg = <0x53ffc000 0x4000>;
+ clocks = <&clks 81>;
+ interrupts = <25>, <56>;
+ };
diff --git a/Documentation/devicetree/bindings/rtc/sa1100-rtc.txt b/Documentation/devicetree/bindings/rtc/sa1100-rtc.txt
deleted file mode 100644
index 968ac82..0000000
--- a/Documentation/devicetree/bindings/rtc/sa1100-rtc.txt
+++ /dev/null
@@ -1,17 +0,0 @@
-* Marvell Real Time Clock controller
-
-Required properties:
-- compatible: should be "mrvl,sa1100-rtc"
-- reg: physical base address of the controller and length of memory mapped
- region.
-- interrupts: Should be two. The first interrupt number is the rtc alarm
- interrupt and the second interrupt number is the rtc hz interrupt.
-- interrupt-names: Assign name of irq resource.
-
-Example:
- rtc: rtc@d4010000 {
- compatible = "mrvl,mmp-rtc";
- reg = <0xd4010000 0x1000>;
- interrupts = <5>, <6>;
- interrupt-names = "rtc 1Hz", "rtc alarm";
- };
diff --git a/Documentation/devicetree/bindings/rtc/sa1100-rtc.yaml b/Documentation/devicetree/bindings/rtc/sa1100-rtc.yaml
new file mode 100644
index 0000000..482e5af
--- /dev/null
+++ b/Documentation/devicetree/bindings/rtc/sa1100-rtc.yaml
@@ -0,0 +1,57 @@
+# SPDX-License-Identifier: GPL-2.0-only
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/rtc/sa1100-rtc.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Marvell Real Time Clock controller bindings
+
+allOf:
+ - $ref: rtc.yaml#
+
+maintainers:
+ - Alessandro Zummo <a.zummo@towertech.it>
+ - Alexandre Belloni <alexandre.belloni@bootlin.com>
+ - Rob Herring <robh+dt@kernel.org>
+
+properties:
+ compatible:
+ enum:
+ - mrvl,sa1100-rtc
+ - mrvl,mmp-rtc
+
+ reg:
+ maxItems: 1
+
+ clocks:
+ maxItems: 1
+
+ resets:
+ maxItems: 1
+
+ interrupts:
+ minItems: 2
+
+ interrupt-names:
+ items:
+ - const: 'rtc 1Hz'
+ - const: 'rtc alarm'
+
+required:
+ - compatible
+ - reg
+ - interrupts
+ - interrupt-names
+
+additionalProperties: false
+
+examples:
+ - |
+ rtc: rtc@d4010000 {
+ compatible = "mrvl,mmp-rtc";
+ reg = <0xd4010000 0x1000>;
+ interrupts = <5>, <6>;
+ interrupt-names = "rtc 1Hz", "rtc alarm";
+ };
+
+...
diff --git a/Documentation/devicetree/bindings/rtc/trivial-rtc.yaml b/Documentation/devicetree/bindings/rtc/trivial-rtc.yaml
index 18cb456..c7d14de 100644
--- a/Documentation/devicetree/bindings/rtc/trivial-rtc.yaml
+++ b/Documentation/devicetree/bindings/rtc/trivial-rtc.yaml
@@ -52,6 +52,8 @@
- nxp,pcf2127
# Real-time clock
- nxp,pcf2129
+ # Real-time clock
+ - nxp,pca2129
# Real-time Clock Module
- pericom,pt7c4338
# I2C bus SERIAL INTERFACE REAL-TIME CLOCK IC
diff --git a/Documentation/devicetree/bindings/serial/st,stm32-uart.yaml b/Documentation/devicetree/bindings/serial/st,stm32-uart.yaml
index 75b8521..06d5f25 100644
--- a/Documentation/devicetree/bindings/serial/st,stm32-uart.yaml
+++ b/Documentation/devicetree/bindings/serial/st,stm32-uart.yaml
@@ -35,9 +35,11 @@
description: label associated with this uart
st,hw-flow-ctrl:
- description: enable hardware flow control
+ description: enable hardware flow control (deprecated)
$ref: /schemas/types.yaml#/definitions/flag
+ uart-has-rtscts: true
+
dmas:
minItems: 1
maxItems: 2
diff --git a/Documentation/devicetree/bindings/soc/microchip/atmel,at91rm9200-tcb.yaml b/Documentation/devicetree/bindings/soc/microchip/atmel,at91rm9200-tcb.yaml
new file mode 100644
index 0000000..3cd0b70
--- /dev/null
+++ b/Documentation/devicetree/bindings/soc/microchip/atmel,at91rm9200-tcb.yaml
@@ -0,0 +1,181 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: "http://devicetree.org/schemas/soc/microchip/atmel,at91rm9200-tcb.yaml#"
+$schema: "http://devicetree.org/meta-schemas/core.yaml#"
+
+title: Atmel Timer Counter Block
+
+maintainers:
+ - Alexandre Belloni <alexandre.belloni@bootlin.com>
+
+description: |
+ The Atmel (now Microchip) SoCs have timers named Timer Counter Block. Each
+ timer has three channels with two counters each.
+
+properties:
+ compatible:
+ items:
+ - enum:
+ - atmel,at91rm9200-tcb
+ - atmel,at91sam9x5-tcb
+ - atmel,sama5d2-tcb
+ - const: simple-mfd
+ - const: syscon
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ description:
+ List of interrupts. One interrupt per TCB channel if available or one
+ interrupt for the TC block
+ minItems: 1
+ maxItems: 3
+
+ clock-names:
+ description:
+ List of clock names. Always includes t0_clk and slow clk. Also includes
+ t1_clk and t2_clk if a clock per channel is available.
+ minItems: 2
+ maxItems: 4
+
+ clocks:
+ minItems: 2
+ maxItems: 4
+
+ '#address-cells':
+ const: 1
+
+ '#size-cells':
+ const: 0
+
+patternProperties:
+ "^timer@[0-2]$":
+ description: The timer block channels that are used as timers or counters.
+ type: object
+ properties:
+ compatible:
+ items:
+ - enum:
+ - atmel,tcb-timer
+ - microchip,tcb-capture
+ reg:
+ description:
+ List of channels to use for this particular timer. In Microchip TCB capture
+ mode channels are registered as a counter devices, for the qdec mode TCB0's
+ channel <0> and <1> are required.
+
+ minItems: 1
+ maxItems: 3
+
+ required:
+ - compatible
+ - reg
+
+allOf:
+ - if:
+ properties:
+ compatible:
+ contains:
+ const: atmel,sama5d2-tcb
+ then:
+ properties:
+ clocks:
+ minItems: 3
+ maxItems: 3
+ clock-names:
+ items:
+ - const: t0_clk
+ - const: gclk
+ - const: slow_clk
+ else:
+ properties:
+ clocks:
+ minItems: 2
+ maxItems: 4
+ clock-names:
+ oneOf:
+ - items:
+ - const: t0_clk
+ - const: slow_clk
+ - items:
+ - const: t0_clk
+ - const: t1_clk
+ - const: t2_clk
+ - const: slow_clk
+
+required:
+ - compatible
+ - reg
+ - interrupts
+ - clocks
+ - clock-names
+ - '#address-cells'
+ - '#size-cells'
+
+additionalProperties: false
+
+examples:
+ - |
+ /* One interrupt per TC block: */
+ tcb0: timer@fff7c000 {
+ compatible = "atmel,at91rm9200-tcb", "simple-mfd", "syscon";
+ #address-cells = <1>;
+ #size-cells = <0>;
+ reg = <0xfff7c000 0x100>;
+ interrupts = <18 4>;
+ clocks = <&tcb0_clk>, <&clk32k>;
+ clock-names = "t0_clk", "slow_clk";
+
+ timer@0 {
+ compatible = "atmel,tcb-timer";
+ reg = <0>, <1>;
+ };
+
+ timer@2 {
+ compatible = "atmel,tcb-timer";
+ reg = <2>;
+ };
+ };
+
+ /* One interrupt per TC channel in a TC block: */
+ tcb1: timer@fffdc000 {
+ compatible = "atmel,at91rm9200-tcb", "simple-mfd", "syscon";
+ #address-cells = <1>;
+ #size-cells = <0>;
+ reg = <0xfffdc000 0x100>;
+ interrupts = <26 4>, <27 4>, <28 4>;
+ clocks = <&tcb1_clk>, <&clk32k>;
+ clock-names = "t0_clk", "slow_clk";
+
+ timer@0 {
+ compatible = "atmel,tcb-timer";
+ reg = <0>;
+ };
+
+ timer@1 {
+ compatible = "atmel,tcb-timer";
+ reg = <1>;
+ };
+ };
+ /* TCB0 Capture with QDEC: */
+ timer@f800c000 {
+ compatible = "atmel,at91rm9200-tcb", "simple-mfd", "syscon";
+ #address-cells = <1>;
+ #size-cells = <0>;
+ reg = <0xfff7c000 0x100>;
+ interrupts = <18 4>;
+ clocks = <&tcb0_clk>, <&clk32k>;
+ clock-names = "t0_clk", "slow_clk";
+
+ timer@0 {
+ compatible = "microchip,tcb-capture";
+ reg = <0>, <1>;
+ };
+
+ timer@2 {
+ compatible = "atmel,tcb-timer";
+ reg = <2>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/soc/qcom/qcom,smd-rpm.txt b/Documentation/devicetree/bindings/soc/qcom/qcom,smd-rpm.txt
deleted file mode 100644
index 616fddc..0000000
--- a/Documentation/devicetree/bindings/soc/qcom/qcom,smd-rpm.txt
+++ /dev/null
@@ -1,62 +0,0 @@
-Qualcomm Resource Power Manager (RPM) over SMD
-
-This driver is used to interface with the Resource Power Manager (RPM) found in
-various Qualcomm platforms. The RPM allows each component in the system to vote
-for state of the system resources, such as clocks, regulators and bus
-frequencies.
-
-The SMD information for the RPM edge should be filled out. See qcom,smd.txt for
-the required edge properties. All SMD related properties will reside within the
-RPM node itself.
-
-= SUBDEVICES
-
-The RPM exposes resources to its subnodes. The rpm_requests node must be
-present and this subnode may contain children that designate regulator
-resources.
-
-- compatible:
- Usage: required
- Value type: <string>
- Definition: must be one of:
- "qcom,rpm-apq8084"
- "qcom,rpm-msm8916"
- "qcom,rpm-msm8974"
- "qcom,rpm-msm8976"
- "qcom,rpm-msm8998"
- "qcom,rpm-sdm660"
- "qcom,rpm-qcs404"
-
-- qcom,smd-channels:
- Usage: required
- Value type: <string>
- Definition: must be "rpm_requests"
-
-Refer to Documentation/devicetree/bindings/regulator/qcom,smd-rpm-regulator.txt
-for information on the regulator subnodes that can exist under the rpm_requests.
-
-Example:
-
- soc {
- apcs: syscon@f9011000 {
- compatible = "syscon";
- reg = <0xf9011000 0x1000>;
- };
- };
-
- smd {
- compatible = "qcom,smd";
-
- rpm {
- interrupts = <0 168 1>;
- qcom,ipc = <&apcs 8 0>;
- qcom,smd-edge = <15>;
-
- rpm_requests {
- compatible = "qcom,rpm-msm8974";
- qcom,smd-channels = "rpm_requests";
-
- ...
- };
- };
- };
diff --git a/Documentation/devicetree/bindings/soc/qcom/qcom,smd-rpm.yaml b/Documentation/devicetree/bindings/soc/qcom/qcom,smd-rpm.yaml
new file mode 100644
index 0000000..468d658
--- /dev/null
+++ b/Documentation/devicetree/bindings/soc/qcom/qcom,smd-rpm.yaml
@@ -0,0 +1,87 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: "http://devicetree.org/schemas/soc/qcom/qcom,smd-rpm.yaml#"
+$schema: "http://devicetree.org/meta-schemas/core.yaml#"
+
+title: Qualcomm Resource Power Manager (RPM) over SMD
+
+description: |
+ This driver is used to interface with the Resource Power Manager (RPM) found
+ in various Qualcomm platforms. The RPM allows each component in the system
+ to vote for state of the system resources, such as clocks, regulators and bus
+ frequencies.
+
+ The SMD information for the RPM edge should be filled out. See qcom,smd.txt
+ for the required edge properties. All SMD related properties will reside
+ within the RPM node itself.
+
+ The RPM exposes resources to its subnodes. The rpm_requests node must be
+ present and this subnode may contain children that designate regulator
+ resources.
+
+ Refer to Documentation/devicetree/bindings/regulator/qcom,smd-rpm-regulator.txt
+ for information on the regulator subnodes that can exist under the
+ rpm_requests.
+
+maintainers:
+ - Kathiravan T <kathirav@codeaurora.org>
+
+properties:
+ compatible:
+ enum:
+ - qcom,rpm-apq8084
+ - qcom,rpm-ipq6018
+ - qcom,rpm-msm8916
+ - qcom,rpm-msm8974
+ - qcom,rpm-msm8976
+ - qcom,rpm-msm8996
+ - qcom,rpm-msm8998
+ - qcom,rpm-sdm660
+ - qcom,rpm-qcs404
+
+ qcom,smd-channels:
+ $ref: /schemas/types.yaml#/definitions/string-array
+ description: Channel name used for the RPM communication
+ items:
+ - const: rpm_requests
+
+if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - qcom,rpm-apq8084
+ - qcom,rpm-msm8916
+ - qcom,rpm-msm8974
+then:
+ required:
+ - qcom,smd-channels
+
+required:
+ - compatible
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+ #include <dt-bindings/interrupt-controller/irq.h>
+
+ smd {
+ compatible = "qcom,smd";
+
+ rpm {
+ interrupts = <GIC_SPI 168 IRQ_TYPE_EDGE_RISING>;
+ qcom,ipc = <&apcs 8 0>;
+ qcom,smd-edge = <15>;
+
+ rpm_requests {
+ compatible = "qcom,rpm-msm8974";
+ qcom,smd-channels = "rpm_requests";
+
+ /* Regulator nodes to follow */
+ };
+ };
+ };
+...
diff --git a/Documentation/devicetree/bindings/soc/ti/k3-ringacc.txt b/Documentation/devicetree/bindings/soc/ti/k3-ringacc.txt
deleted file mode 100644
index 59758cc..0000000
--- a/Documentation/devicetree/bindings/soc/ti/k3-ringacc.txt
+++ /dev/null
@@ -1,59 +0,0 @@
-* Texas Instruments K3 NavigatorSS Ring Accelerator
-
-The Ring Accelerator (RA) is a machine which converts read/write accesses
-from/to a constant address into corresponding read/write accesses from/to a
-circular data structure in memory. The RA eliminates the need for each DMA
-controller which needs to access ring elements from having to know the current
-state of the ring (base address, current offset). The DMA controller
-performs a read or write access to a specific address range (which maps to the
-source interface on the RA) and the RA replaces the address for the transaction
-with a new address which corresponds to the head or tail element of the ring
-(head for reads, tail for writes).
-
-The Ring Accelerator is a hardware module that is responsible for accelerating
-management of the packet queues. The K3 SoCs can have more than one RA instances
-
-Required properties:
-- compatible : Must be "ti,am654-navss-ringacc";
-- reg : Should contain register location and length of the following
- named register regions.
-- reg-names : should be
- "rt" - The RA Ring Real-time Control/Status Registers
- "fifos" - The RA Queues Registers
- "proxy_gcfg" - The RA Proxy Global Config Registers
- "proxy_target" - The RA Proxy Datapath Registers
-- ti,num-rings : Number of rings supported by RA
-- ti,sci-rm-range-gp-rings : TI-SCI RM subtype for GP ring range
-- ti,sci : phandle on TI-SCI compatible System controller node
-- ti,sci-dev-id : TI-SCI device id of the ring accelerator
-- msi-parent : phandle for "ti,sci-inta" interrupt controller
-
-Optional properties:
- -- ti,dma-ring-reset-quirk : enable ringacc / udma ring state interoperability
- issue software w/a
-
-Example:
-
-ringacc: ringacc@3c000000 {
- compatible = "ti,am654-navss-ringacc";
- reg = <0x0 0x3c000000 0x0 0x400000>,
- <0x0 0x38000000 0x0 0x400000>,
- <0x0 0x31120000 0x0 0x100>,
- <0x0 0x33000000 0x0 0x40000>;
- reg-names = "rt", "fifos",
- "proxy_gcfg", "proxy_target";
- ti,num-rings = <818>;
- ti,sci-rm-range-gp-rings = <0x2>; /* GP ring range */
- ti,dma-ring-reset-quirk;
- ti,sci = <&dmsc>;
- ti,sci-dev-id = <187>;
- msi-parent = <&inta_main_udmass>;
-};
-
-client:
-
-dma_ipx: dma_ipx@<addr> {
- ...
- ti,ringacc = <&ringacc>;
- ...
-}
diff --git a/Documentation/devicetree/bindings/soc/ti/k3-ringacc.yaml b/Documentation/devicetree/bindings/soc/ti/k3-ringacc.yaml
new file mode 100644
index 0000000..ae33fc9
--- /dev/null
+++ b/Documentation/devicetree/bindings/soc/ti/k3-ringacc.yaml
@@ -0,0 +1,102 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+# Copyright (C) 2020 Texas Instruments Incorporated - http://www.ti.com/
+%YAML 1.2
+---
+$id: "http://devicetree.org/schemas/soc/ti/k3-ringacc.yaml#"
+$schema: "http://devicetree.org/meta-schemas/core.yaml#"
+
+title: Texas Instruments K3 NavigatorSS Ring Accelerator
+
+maintainers:
+ - Santosh Shilimkar <ssantosh@kernel.org>
+ - Grygorii Strashko <grygorii.strashko@ti.com>
+
+description: |
+ The Ring Accelerator (RA) is a machine which converts read/write accesses
+ from/to a constant address into corresponding read/write accesses from/to a
+ circular data structure in memory. The RA eliminates the need for each DMA
+ controller which needs to access ring elements from having to know the current
+ state of the ring (base address, current offset). The DMA controller
+ performs a read or write access to a specific address range (which maps to the
+ source interface on the RA) and the RA replaces the address for the transaction
+ with a new address which corresponds to the head or tail element of the ring
+ (head for reads, tail for writes).
+
+ The Ring Accelerator is a hardware module that is responsible for accelerating
+ management of the packet queues. The K3 SoCs can have more than one RA instances
+
+properties:
+ compatible:
+ items:
+ - const: ti,am654-navss-ringacc
+
+ reg:
+ items:
+ - description: real time registers regions
+ - description: fifos registers regions
+ - description: proxy gcfg registers regions
+ - description: proxy target registers regions
+
+ reg-names:
+ items:
+ - const: rt
+ - const: fifos
+ - const: proxy_gcfg
+ - const: proxy_target
+
+ msi-parent: true
+
+ ti,num-rings:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description: Number of rings supported by RA
+
+ ti,sci-rm-range-gp-rings:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description: TI-SCI RM subtype for GP ring range
+
+ ti,sci:
+ $ref: /schemas/types.yaml#definitions/phandle-array
+ description: phandle on TI-SCI compatible System controller node
+
+ ti,sci-dev-id:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description: TI-SCI device id of the ring accelerator
+
+ ti,dma-ring-reset-quirk:
+ $ref: /schemas/types.yaml#definitions/flag
+ description: |
+ enable ringacc/udma ring state interoperability issue software w/a
+
+required:
+ - compatible
+ - reg
+ - reg-names
+ - msi-parent
+ - ti,num-rings
+ - ti,sci-rm-range-gp-rings
+ - ti,sci
+ - ti,sci-dev-id
+
+additionalProperties: false
+
+examples:
+ - |
+ bus {
+ #address-cells = <2>;
+ #size-cells = <2>;
+
+ ringacc: ringacc@3c000000 {
+ compatible = "ti,am654-navss-ringacc";
+ reg = <0x0 0x3c000000 0x0 0x400000>,
+ <0x0 0x38000000 0x0 0x400000>,
+ <0x0 0x31120000 0x0 0x100>,
+ <0x0 0x33000000 0x0 0x40000>;
+ reg-names = "rt", "fifos", "proxy_gcfg", "proxy_target";
+ ti,num-rings = <818>;
+ ti,sci-rm-range-gp-rings = <0x2>; /* GP ring range */
+ ti,dma-ring-reset-quirk;
+ ti,sci = <&dmsc>;
+ ti,sci-dev-id = <187>;
+ msi-parent = <&inta_main_udmass>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/sound/adi,adau1977.txt b/Documentation/devicetree/bindings/sound/adi,adau1977.txt
index 9225472..37f8aad 100644
--- a/Documentation/devicetree/bindings/sound/adi,adau1977.txt
+++ b/Documentation/devicetree/bindings/sound/adi,adau1977.txt
@@ -1,9 +1,9 @@
Analog Devices ADAU1977/ADAU1978/ADAU1979
Datasheets:
-http://www.analog.com/media/en/technical-documentation/data-sheets/ADAU1977.pdf
-http://www.analog.com/media/en/technical-documentation/data-sheets/ADAU1978.pdf
-http://www.analog.com/media/en/technical-documentation/data-sheets/ADAU1979.pdf
+https://www.analog.com/media/en/technical-documentation/data-sheets/ADAU1977.pdf
+https://www.analog.com/media/en/technical-documentation/data-sheets/ADAU1978.pdf
+https://www.analog.com/media/en/technical-documentation/data-sheets/ADAU1979.pdf
This driver supports both the I2C and SPI bus.
diff --git a/Documentation/devicetree/bindings/sound/ak4613.txt b/Documentation/devicetree/bindings/sound/ak4613.txt
deleted file mode 100644
index 49a2e74..0000000
--- a/Documentation/devicetree/bindings/sound/ak4613.txt
+++ /dev/null
@@ -1,27 +0,0 @@
-AK4613 I2C transmitter
-
-This device supports I2C mode only.
-
-Required properties:
-
-- compatible : "asahi-kasei,ak4613"
-- reg : The chip select number on the I2C bus
-
-Optional properties:
-- asahi-kasei,in1-single-end : Boolean. Indicate input / output pins are single-ended.
-- asahi-kasei,in2-single-end rather than differential.
-- asahi-kasei,out1-single-end
-- asahi-kasei,out2-single-end
-- asahi-kasei,out3-single-end
-- asahi-kasei,out4-single-end
-- asahi-kasei,out5-single-end
-- asahi-kasei,out6-single-end
-
-Example:
-
-&i2c {
- ak4613: ak4613@10 {
- compatible = "asahi-kasei,ak4613";
- reg = <0x10>;
- };
-};
diff --git a/Documentation/devicetree/bindings/sound/ak4613.yaml b/Documentation/devicetree/bindings/sound/ak4613.yaml
new file mode 100644
index 0000000..ef4055e
--- /dev/null
+++ b/Documentation/devicetree/bindings/sound/ak4613.yaml
@@ -0,0 +1,49 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/sound/ak4613.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: AK4613 I2C transmitter Device Tree Bindings
+
+maintainers:
+ - Kuninori Morimoto <kuninori.morimoto.gx@renesas.com>
+
+properties:
+ compatible:
+ const: asahi-kasei,ak4613
+
+ reg:
+ maxItems: 1
+
+ clocks:
+ maxItems: 1
+
+ "#sound-dai-cells":
+ const: 0
+
+patternProperties:
+ "^asahi-kasei,in[1-2]-single-end$":
+ description: Input Pin 1 - 2.
+ $ref: /schemas/types.yaml#/definitions/flag
+
+ "^asahi-kasei,out[1-6]-single-end$":
+ description: Output Pin 1 - 6.
+ $ref: /schemas/types.yaml#/definitions/flag
+
+required:
+ - compatible
+ - reg
+
+additionalProperties: false
+
+examples:
+ - |
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+ ak4613: codec@10 {
+ compatible = "asahi-kasei,ak4613";
+ reg = <0x10>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/sound/ak4642.txt b/Documentation/devicetree/bindings/sound/ak4642.txt
deleted file mode 100644
index 58e48ee..0000000
--- a/Documentation/devicetree/bindings/sound/ak4642.txt
+++ /dev/null
@@ -1,37 +0,0 @@
-AK4642 I2C transmitter
-
-This device supports I2C mode only.
-
-Required properties:
-
- - compatible : "asahi-kasei,ak4642" or "asahi-kasei,ak4643" or "asahi-kasei,ak4648"
- - reg : The chip select number on the I2C bus
-
-Optional properties:
-
- - #clock-cells : common clock binding; shall be set to 0
- - clocks : common clock binding; MCKI clock
- - clock-frequency : common clock binding; frequency of MCKO
- - clock-output-names : common clock binding; MCKO clock name
-
-Example 1:
-
-&i2c {
- ak4648: ak4648@12 {
- compatible = "asahi-kasei,ak4642";
- reg = <0x12>;
- };
-};
-
-Example 2:
-
-&i2c {
- ak4643: codec@12 {
- compatible = "asahi-kasei,ak4643";
- reg = <0x12>;
- #clock-cells = <0>;
- clocks = <&audio_clock>;
- clock-frequency = <12288000>;
- clock-output-names = "ak4643_mcko";
- };
-};
diff --git a/Documentation/devicetree/bindings/sound/ak4642.yaml b/Documentation/devicetree/bindings/sound/ak4642.yaml
new file mode 100644
index 0000000..6cd213b
--- /dev/null
+++ b/Documentation/devicetree/bindings/sound/ak4642.yaml
@@ -0,0 +1,58 @@
+# SPDX-License-Identifier: GPL-2.0
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/sound/ak4642.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: AK4642 I2C transmitter Device Tree Bindings
+
+maintainers:
+ - Kuninori Morimoto <kuninori.morimoto.gx@renesas.com>
+
+properties:
+ compatible:
+ enum:
+ - asahi-kasei,ak4642
+ - asahi-kasei,ak4643
+ - asahi-kasei,ak4648
+
+ reg:
+ maxItems: 1
+
+ "#clock-cells":
+ const: 0
+ "#sound-dai-cells":
+ const: 0
+
+ clocks:
+ maxItems: 1
+
+ clock-frequency:
+ description: common clock binding; frequency of MCKO
+ $ref: /schemas/types.yaml#/definitions/uint32
+
+ clock-output-names:
+ description: common clock name
+ $ref: /schemas/types.yaml#/definitions/string
+
+required:
+ - compatible
+ - reg
+
+additionalProperties: false
+
+examples:
+ - |
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+ ak4643: codec@12 {
+ compatible = "asahi-kasei,ak4643";
+ #sound-dai-cells = <0>;
+ reg = <0x12>;
+ #clock-cells = <0>;
+ clocks = <&audio_clock>;
+ clock-frequency = <12288000>;
+ clock-output-names = "ak4643_mcko";
+ };
+ };
diff --git a/Documentation/devicetree/bindings/sound/audio-graph-card.txt b/Documentation/devicetree/bindings/sound/audio-graph-card.txt
index 2696826..d5f6919 100644
--- a/Documentation/devicetree/bindings/sound/audio-graph-card.txt
+++ b/Documentation/devicetree/bindings/sound/audio-graph-card.txt
@@ -5,7 +5,7 @@
see ${LINUX}/Documentation/devicetree/bindings/graph.txt
Basically, Audio Graph Card property is same as Simple Card.
-see ${LINUX}/Documentation/devicetree/bindings/sound/simple-card.txt
+see ${LINUX}/Documentation/devicetree/bindings/sound/simple-card.yaml
Below are same as Simple-Card.
diff --git a/Documentation/devicetree/bindings/sound/everest,es8316.txt b/Documentation/devicetree/bindings/sound/everest,es8316.txt
deleted file mode 100644
index 1bf03c5..0000000
--- a/Documentation/devicetree/bindings/sound/everest,es8316.txt
+++ /dev/null
@@ -1,23 +0,0 @@
-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/everest,es8316.yaml b/Documentation/devicetree/bindings/sound/everest,es8316.yaml
new file mode 100644
index 0000000..3b752bb
--- /dev/null
+++ b/Documentation/devicetree/bindings/sound/everest,es8316.yaml
@@ -0,0 +1,50 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/sound/everest,es8316.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Everest ES8316 audio CODEC
+
+maintainers:
+ - Daniel Drake <drake@endlessm.com>
+ - Katsuhiro Suzuki <katsuhiro@katsuster.net>
+
+properties:
+ compatible:
+ const: everest,es8316
+
+ reg:
+ maxItems: 1
+
+ clocks:
+ items:
+ - description: clock for master clock (MCLK)
+
+ clock-names:
+ items:
+ - const: mclk
+
+ "#sound-dai-cells":
+ const: 0
+
+required:
+ - compatible
+ - reg
+ - "#sound-dai-cells"
+
+additionalProperties: false
+
+examples:
+ - |
+ i2c0 {
+ #address-cells = <1>;
+ #size-cells = <0>;
+ es8316: codec@11 {
+ compatible = "everest,es8316";
+ reg = <0x11>;
+ clocks = <&clks 10>;
+ clock-names = "mclk";
+ #sound-dai-cells = <0>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/sound/fsl,spdif.txt b/Documentation/devicetree/bindings/sound/fsl,spdif.txt
index 8b324f8..e1365b0 100644
--- a/Documentation/devicetree/bindings/sound/fsl,spdif.txt
+++ b/Documentation/devicetree/bindings/sound/fsl,spdif.txt
@@ -6,7 +6,11 @@
Required properties:
- - compatible : Compatible list, must contain "fsl,imx35-spdif".
+ - compatible : Compatible list, should contain one of the following
+ compatibles:
+ "fsl,imx35-spdif",
+ "fsl,vf610-spdif",
+ "fsl,imx6sx-spdif",
- reg : Offset and length of the register set for the device.
diff --git a/Documentation/devicetree/bindings/sound/fsl-asoc-card.txt b/Documentation/devicetree/bindings/sound/fsl-asoc-card.txt
index c60a573..63ebf52 100644
--- a/Documentation/devicetree/bindings/sound/fsl-asoc-card.txt
+++ b/Documentation/devicetree/bindings/sound/fsl-asoc-card.txt
@@ -34,6 +34,10 @@
"fsl,imx-audio-wm8960"
+ "fsl,imx-audio-mqs"
+
+ "fsl,imx-audio-wm8524"
+
Required properties:
- compatible : Contains one of entries in the compatible list.
@@ -44,6 +48,11 @@
- audio-codec : The phandle of an audio codec
+Optional properties:
+
+ - audio-asrc : The phandle of ASRC. It can be absent if there's no
+ need to add ASRC support via DPCM.
+
- audio-routing : A list of the connections between audio components.
Each entry is a pair of strings, the first being the
connection's sink, the second being the connection's
@@ -60,10 +69,13 @@
coexisting in order to support the old bindings
of wm8962 and sgtl5000.
-Optional properties:
-
- - audio-asrc : The phandle of ASRC. It can be absent if there's no
- need to add ASRC support via DPCM.
+ - hp-det-gpio : The GPIO that detect headphones are plugged in
+ - mic-det-gpio : The GPIO that detect microphones are plugged in
+ - bitclock-master : Indicates dai-link bit clock master; for details see simple-card.yaml.
+ - frame-master : Indicates dai-link frame master; for details see simple-card.yaml.
+ - dai-format : audio format, for details see simple-card.yaml.
+ - frame-inversion : dai-link uses frame clock inversion, for details see simple-card.yaml.
+ - bitclock-inversion : dai-link uses bit clock inversion, for details see simple-card.yaml.
Optional unless SSI is selected as a CPU DAI:
diff --git a/Documentation/devicetree/bindings/sound/intel,keembay-i2s.yaml b/Documentation/devicetree/bindings/sound/intel,keembay-i2s.yaml
new file mode 100644
index 0000000..2e0bbc1c
--- /dev/null
+++ b/Documentation/devicetree/bindings/sound/intel,keembay-i2s.yaml
@@ -0,0 +1,70 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+# Copyright 2020 Intel Corporation
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/sound/intel,keembay-i2s.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Intel KeemBay I2S Device Tree Bindings
+
+maintainers:
+ - Sia, Jee Heng <jee.heng.sia@intel.com>
+
+description: |
+ Intel KeemBay I2S
+
+properties:
+ compatible:
+ enum:
+ - intel,keembay-i2s
+
+ "#sound-dai-cells":
+ const: 0
+
+ reg:
+ items:
+ - description: I2S registers
+ - description: I2S gen configuration
+
+ reg-names:
+ items:
+ - const: i2s-regs
+ - const: i2s_gen_cfg
+
+ interrupts:
+ maxItems: 1
+
+ clocks:
+ items:
+ - description: Bus Clock
+ - description: Module Clock
+
+ clock-names:
+ items:
+ - const: osc
+ - const: apb_clk
+
+required:
+ - compatible
+ - "#sound-dai-cells"
+ - reg
+ - clocks
+ - clock-names
+ - interrupts
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+ #include <dt-bindings/interrupt-controller/irq.h>
+ #define KEEM_BAY_PSS_AUX_I2S3
+ #define KEEM_BAY_PSS_I2S3
+ i2s3: i2s@20140000 {
+ compatible = "intel,keembay-i2s";
+ #sound-dai-cells = <0>;
+ reg = <0x20140000 0x200>, /* I2S registers */
+ <0x202a00a4 0x4>; /* I2S gen configuration */
+ reg-names = "i2s-regs", "i2s_gen_cfg";
+ interrupts = <GIC_SPI 120 IRQ_TYPE_LEVEL_HIGH>;
+ clock-names = "osc", "apb_clk";
+ clocks = <&scmi_clk KEEM_BAY_PSS_AUX_I2S3>, <&scmi_clk KEEM_BAY_PSS_I2S3>;
+ };
diff --git a/Documentation/devicetree/bindings/sound/max98357a.txt b/Documentation/devicetree/bindings/sound/max98357a.txt
index 4bce14c..75db84d 100644
--- a/Documentation/devicetree/bindings/sound/max98357a.txt
+++ b/Documentation/devicetree/bindings/sound/max98357a.txt
@@ -1,9 +1,10 @@
-Maxim MAX98357A audio DAC
+Maxim MAX98357A/MAX98360A audio DAC
-This node models the Maxim MAX98357A DAC.
+This node models the Maxim MAX98357A/MAX98360A DAC.
Required properties:
-- compatible : "maxim,max98357a"
+- compatible : "maxim,max98357a" for MAX98357A.
+ "maxim,max98360a" for MAX98360A.
Optional properties:
- sdmode-gpios : GPIO specifier for the chip's SD_MODE pin.
@@ -20,3 +21,8 @@
compatible = "maxim,max98357a";
sdmode-gpios = <&qcom_pinmux 25 0>;
};
+
+max98360a {
+ compatible = "maxim,max98360a";
+ sdmode-gpios = <&qcom_pinmux 25 0>;
+};
diff --git a/Documentation/devicetree/bindings/sound/maxim,max98390.yaml b/Documentation/devicetree/bindings/sound/maxim,max98390.yaml
new file mode 100644
index 0000000..e5ac352
--- /dev/null
+++ b/Documentation/devicetree/bindings/sound/maxim,max98390.yaml
@@ -0,0 +1,51 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/sound/maxim,max98390.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Maxim Integrated MAX98390 Speaker Amplifier with Integrated Dynamic Speaker Management
+
+maintainers:
+ - Steve Lee <steves.lee@maximintegrated.com>
+
+properties:
+ compatible:
+ const: maxim,max98390
+
+ reg:
+ maxItems: 1
+ description: I2C address of the device.
+
+ maxim,temperature_calib:
+ allOf:
+ - $ref: /schemas/types.yaml#/definitions/uint32
+ description: The calculated temperature data was measured while doing the calibration.
+ minimum: 0
+ maximum: 65535
+
+ maxim,r0_calib:
+ allOf:
+ - $ref: /schemas/types.yaml#/definitions/uint32
+ description: This is r0 calibration data which was measured in factory mode.
+ minimum: 1
+ maximum: 8388607
+
+required:
+ - compatible
+ - reg
+
+additionalProperties: false
+
+examples:
+ - |
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+ max98390: amplifier@38 {
+ compatible = "maxim,max98390";
+ reg = <0x38>;
+ maxim,temperature_calib = <1024>;
+ maxim,r0_calib = <100232>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/sound/mt6358.txt b/Documentation/devicetree/bindings/sound/mt6358.txt
index 5465730..59a73ff 100644
--- a/Documentation/devicetree/bindings/sound/mt6358.txt
+++ b/Documentation/devicetree/bindings/sound/mt6358.txt
@@ -10,9 +10,15 @@
- compatible : "mediatek,mt6358-sound".
- Avdd-supply : power source of AVDD
+Optional properties:
+- mediatek,dmic-mode : Indicates how many data pins are used to transmit two
+ channels of PDM signal. 0 means two wires, 1 means one wire. Default
+ value is 0.
+
Example:
mt6358_snd {
compatible = "mediatek,mt6358-sound";
Avdd-supply = <&mt6358_vaud28_reg>;
+ mediatek,dmic-mode = <0>;
};
diff --git a/Documentation/devicetree/bindings/sound/mt8183-da7219-max98357.txt b/Documentation/devicetree/bindings/sound/mt8183-da7219-max98357.txt
index 92ac86f..6787ce8 100644
--- a/Documentation/devicetree/bindings/sound/mt8183-da7219-max98357.txt
+++ b/Documentation/devicetree/bindings/sound/mt8183-da7219-max98357.txt
@@ -1,15 +1,20 @@
-MT8183 with MT6358, DA7219 and MAX98357 CODECS
+MT8183 with MT6358, DA7219, MAX98357, and RT1015 CODECS
Required properties:
-- compatible : "mediatek,mt8183_da7219_max98357"
+- compatible : "mediatek,mt8183_da7219_max98357" for MAX98357A codec
+ "mediatek,mt8183_da7219_rt1015" for RT1015 codec
- mediatek,headset-codec: the phandles of da7219 codecs
- mediatek,platform: the phandle of MT8183 ASoC platform
+Optional properties:
+- mediatek,hdmi-codec: the phandles of HDMI codec
+
Example:
sound {
compatible = "mediatek,mt8183_da7219_max98357";
mediatek,headset-codec = <&da7219>;
+ mediatek,hdmi-codec = <&it6505dptx>;
mediatek,platform = <&afe>;
};
diff --git a/Documentation/devicetree/bindings/sound/mt8183-mt6358-ts3a227-max98357.txt b/Documentation/devicetree/bindings/sound/mt8183-mt6358-ts3a227-max98357.txt
index decaa01..235eac8 100644
--- a/Documentation/devicetree/bindings/sound/mt8183-mt6358-ts3a227-max98357.txt
+++ b/Documentation/devicetree/bindings/sound/mt8183-mt6358-ts3a227-max98357.txt
@@ -1,13 +1,16 @@
-MT8183 with MT6358, TS3A227 and MAX98357 CODECS
+MT8183 with MT6358, TS3A227, MAX98357, and RT1015 CODECS
Required properties:
-- compatible : "mediatek,mt8183_mt6358_ts3a227_max98357"
+- compatible : "mediatek,mt8183_mt6358_ts3a227_max98357" for MAX98357A codec
+ "mediatek,mt8183_mt6358_ts3a227_max98357b" for MAX98357B codec
+ "mediatek,mt8183_mt6358_ts3a227_rt1015" for RT1015 codec
- mediatek,platform: the phandle of MT8183 ASoC platform
Optional properties:
- mediatek,headset-codec: the phandles of ts3a227 codecs
- mediatek,ec-codec: the phandle of EC codecs.
See google,cros-ec-codec.txt for more details.
+- mediatek,hdmi-codec: the phandles of HDMI codec
Example:
@@ -15,6 +18,7 @@
compatible = "mediatek,mt8183_mt6358_ts3a227_max98357";
mediatek,headset-codec = <&ts3a227>;
mediatek,ec-codec = <&ec_codec>;
+ mediatek,hdmi-codec = <&it6505dptx>;
mediatek,platform = <&afe>;
};
diff --git a/Documentation/devicetree/bindings/sound/nvidia,tegra186-dspk.yaml b/Documentation/devicetree/bindings/sound/nvidia,tegra186-dspk.yaml
new file mode 100644
index 0000000..e620c77
--- /dev/null
+++ b/Documentation/devicetree/bindings/sound/nvidia,tegra186-dspk.yaml
@@ -0,0 +1,83 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/sound/nvidia,tegra186-dspk.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Tegra186 DSPK Controller Device Tree Bindings
+
+description: |
+ The Digital Speaker Controller (DSPK) can be viewed as a Pulse
+ Density Modulation (PDM) transmitter that up-samples the input to
+ the desired sampling rate by interpolation and then converts the
+ over sampled Pulse Code Modulation (PCM) input to the desired 1-bit
+ output via Delta Sigma Modulation (DSM).
+
+maintainers:
+ - Jon Hunter <jonathanh@nvidia.com>
+ - Sameer Pujar <spujar@nvidia.com>
+
+properties:
+ $nodename:
+ pattern: "^dspk@[0-9a-f]*$"
+
+ compatible:
+ oneOf:
+ - const: nvidia,tegra186-dspk
+ - items:
+ - const: nvidia,tegra194-dspk
+ - const: nvidia,tegra186-dspk
+
+ reg:
+ maxItems: 1
+
+ clocks:
+ maxItems: 1
+
+ clock-names:
+ const: dspk
+
+ assigned-clocks:
+ maxItems: 1
+
+ assigned-clock-parents:
+ maxItems: 1
+
+ assigned-clock-rates:
+ maxItems: 1
+
+ sound-name-prefix:
+ pattern: "^DSPK[1-9]$"
+ allOf:
+ - $ref: /schemas/types.yaml#/definitions/string
+ description:
+ Used as prefix for sink/source names of the component. Must be a
+ unique string among multiple instances of the same component.
+ The name can be "DSPK1" or "DSPKx", where x depends on the maximum
+ available instances on a Tegra SoC.
+
+required:
+ - compatible
+ - reg
+ - clocks
+ - clock-names
+ - assigned-clocks
+ - assigned-clock-parents
+ - sound-name-prefix
+
+examples:
+ - |
+ #include<dt-bindings/clock/tegra186-clock.h>
+
+ dspk@2905000 {
+ compatible = "nvidia,tegra186-dspk";
+ reg = <0x2905000 0x100>;
+ clocks = <&bpmp TEGRA186_CLK_DSPK1>;
+ clock-names = "dspk";
+ assigned-clocks = <&bpmp TEGRA186_CLK_DSPK1>;
+ assigned-clock-parents = <&bpmp TEGRA186_CLK_PLL_A_OUT0>;
+ assigned-clock-rates = <12288000>;
+ sound-name-prefix = "DSPK1";
+ };
+
+...
diff --git a/Documentation/devicetree/bindings/sound/nvidia,tegra210-admaif.yaml b/Documentation/devicetree/bindings/sound/nvidia,tegra210-admaif.yaml
new file mode 100644
index 0000000..41c77f4
--- /dev/null
+++ b/Documentation/devicetree/bindings/sound/nvidia,tegra210-admaif.yaml
@@ -0,0 +1,111 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/sound/nvidia,tegra210-admaif.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Tegra210 ADMAIF Device Tree Bindings
+
+description: |
+ ADMAIF is the interface between ADMA and AHUB. Each ADMA channel
+ that sends/receives data to/from AHUB must interface through an
+ ADMAIF channel. ADMA channel sending data to AHUB pairs with ADMAIF
+ Tx channel and ADMA channel receiving data from AHUB pairs with
+ ADMAIF Rx channel.
+
+maintainers:
+ - Jon Hunter <jonathanh@nvidia.com>
+ - Sameer Pujar <spujar@nvidia.com>
+
+properties:
+ $nodename:
+ pattern: "^admaif@[0-9a-f]*$"
+
+ compatible:
+ oneOf:
+ - enum:
+ - nvidia,tegra210-admaif
+ - nvidia,tegra186-admaif
+ - items:
+ - const: nvidia,tegra194-admaif
+ - const: nvidia,tegra186-admaif
+
+ reg:
+ maxItems: 1
+
+ dmas: true
+
+ dma-names: true
+
+if:
+ properties:
+ compatible:
+ contains:
+ const: nvidia,tegra210-admaif
+
+then:
+ properties:
+ dmas:
+ description:
+ DMA channel specifiers, equally divided for Tx and Rx.
+ minItems: 1
+ maxItems: 20
+ dma-names:
+ items:
+ pattern: "^[rt]x(10|[1-9])$"
+ description:
+ Should be "rx1", "rx2" ... "rx10" for DMA Rx channel
+ Should be "tx1", "tx2" ... "tx10" for DMA Tx channel
+ minItems: 1
+ maxItems: 20
+
+else:
+ properties:
+ dmas:
+ description:
+ DMA channel specifiers, equally divided for Tx and Rx.
+ minItems: 1
+ maxItems: 40
+ dma-names:
+ items:
+ pattern: "^[rt]x(1[0-9]|[1-9]|20)$"
+ description:
+ Should be "rx1", "rx2" ... "rx20" for DMA Rx channel
+ Should be "tx1", "tx2" ... "tx20" for DMA Tx channel
+ minItems: 1
+ maxItems: 40
+
+required:
+ - compatible
+ - reg
+ - dmas
+ - dma-names
+
+examples:
+ - |
+ admaif@702d0000 {
+ compatible = "nvidia,tegra210-admaif";
+ reg = <0x702d0000 0x800>;
+ dmas = <&adma 1>, <&adma 1>,
+ <&adma 2>, <&adma 2>,
+ <&adma 3>, <&adma 3>,
+ <&adma 4>, <&adma 4>,
+ <&adma 5>, <&adma 5>,
+ <&adma 6>, <&adma 6>,
+ <&adma 7>, <&adma 7>,
+ <&adma 8>, <&adma 8>,
+ <&adma 9>, <&adma 9>,
+ <&adma 10>, <&adma 10>;
+ dma-names = "rx1", "tx1",
+ "rx2", "tx2",
+ "rx3", "tx3",
+ "rx4", "tx4",
+ "rx5", "tx5",
+ "rx6", "tx6",
+ "rx7", "tx7",
+ "rx8", "tx8",
+ "rx9", "tx9",
+ "rx10", "tx10";
+ };
+
+...
diff --git a/Documentation/devicetree/bindings/sound/nvidia,tegra210-ahub.yaml b/Documentation/devicetree/bindings/sound/nvidia,tegra210-ahub.yaml
new file mode 100644
index 0000000..44ee9d8
--- /dev/null
+++ b/Documentation/devicetree/bindings/sound/nvidia,tegra210-ahub.yaml
@@ -0,0 +1,136 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/sound/nvidia,tegra210-ahub.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Tegra210 AHUB Device Tree Bindings
+
+description: |
+ The Audio Hub (AHUB) comprises a collection of hardware accelerators
+ for audio pre-processing, post-processing and a programmable full
+ crossbar for routing audio data across these accelerators. It has
+ external interfaces such as I2S, DMIC, DSPK. It interfaces with ADMA
+ engine through ADMAIF.
+
+maintainers:
+ - Jon Hunter <jonathanh@nvidia.com>
+ - Sameer Pujar <spujar@nvidia.com>
+
+properties:
+ $nodename:
+ pattern: "^ahub@[0-9a-f]*$"
+
+ compatible:
+ oneOf:
+ - enum:
+ - nvidia,tegra210-ahub
+ - nvidia,tegra186-ahub
+ - items:
+ - const: nvidia,tegra194-ahub
+ - const: nvidia,tegra186-ahub
+
+ reg:
+ maxItems: 1
+
+ clocks:
+ maxItems: 1
+
+ clock-names:
+ const: ahub
+
+ assigned-clocks:
+ maxItems: 1
+
+ assigned-clock-parents:
+ maxItems: 1
+
+ assigned-clock-rates:
+ maxItems: 1
+
+ "#address-cells":
+ const: 1
+
+ "#size-cells":
+ const: 1
+
+ ranges: true
+
+required:
+ - compatible
+ - reg
+ - clocks
+ - clock-names
+ - assigned-clocks
+ - assigned-clock-parents
+ - "#address-cells"
+ - "#size-cells"
+ - ranges
+
+examples:
+ - |
+ #include<dt-bindings/clock/tegra210-car.h>
+
+ ahub@702d0800 {
+ compatible = "nvidia,tegra210-ahub";
+ reg = <0x702d0800 0x800>;
+ clocks = <&tegra_car TEGRA210_CLK_D_AUDIO>;
+ clock-names = "ahub";
+ assigned-clocks = <&tegra_car TEGRA210_CLK_D_AUDIO>;
+ assigned-clock-parents = <&tegra_car TEGRA210_CLK_PLL_A_OUT0>;
+ #address-cells = <1>;
+ #size-cells = <1>;
+ ranges = <0x702d0000 0x702d0000 0x0000e400>;
+
+ // All AHUB child nodes below
+ admaif@702d0000 {
+ compatible = "nvidia,tegra210-admaif";
+ reg = <0x702d0000 0x800>;
+ dmas = <&adma 1>, <&adma 1>,
+ <&adma 2>, <&adma 2>,
+ <&adma 3>, <&adma 3>,
+ <&adma 4>, <&adma 4>,
+ <&adma 5>, <&adma 5>,
+ <&adma 6>, <&adma 6>,
+ <&adma 7>, <&adma 7>,
+ <&adma 8>, <&adma 8>,
+ <&adma 9>, <&adma 9>,
+ <&adma 10>, <&adma 10>;
+ dma-names = "rx1", "tx1",
+ "rx2", "tx2",
+ "rx3", "tx3",
+ "rx4", "tx4",
+ "rx5", "tx5",
+ "rx6", "tx6",
+ "rx7", "tx7",
+ "rx8", "tx8",
+ "rx9", "tx9",
+ "rx10", "tx10";
+ };
+
+ i2s@702d1000 {
+ compatible = "nvidia,tegra210-i2s";
+ reg = <0x702d1000 0x100>;
+ clocks = <&tegra_car TEGRA210_CLK_I2S0>;
+ clock-names = "i2s";
+ assigned-clocks = <&tegra_car TEGRA210_CLK_I2S0>;
+ assigned-clock-parents = <&tegra_car TEGRA210_CLK_PLL_A_OUT0>;
+ assigned-clock-rates = <1536000>;
+ sound-name-prefix = "I2S1";
+ };
+
+ dmic@702d4000 {
+ compatible = "nvidia,tegra210-dmic";
+ reg = <0x702d4000 0x100>;
+ clocks = <&tegra_car TEGRA210_CLK_DMIC1>;
+ clock-names = "dmic";
+ assigned-clocks = <&tegra_car TEGRA210_CLK_DMIC1>;
+ assigned-clock-parents = <&tegra_car TEGRA210_CLK_PLL_A_OUT0>;
+ assigned-clock-rates = <3072000>;
+ sound-name-prefix = "DMIC1";
+ };
+
+ // More child nodes to follow
+ };
+
+...
diff --git a/Documentation/devicetree/bindings/sound/nvidia,tegra210-dmic.yaml b/Documentation/devicetree/bindings/sound/nvidia,tegra210-dmic.yaml
new file mode 100644
index 0000000..1c14e83
--- /dev/null
+++ b/Documentation/devicetree/bindings/sound/nvidia,tegra210-dmic.yaml
@@ -0,0 +1,83 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/sound/nvidia,tegra210-dmic.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Tegra210 DMIC Controller Device Tree Bindings
+
+description: |
+ The Digital MIC (DMIC) Controller is used to interface with Pulse
+ Density Modulation (PDM) input devices. It converts PDM signals to
+ Pulse Coded Modulation (PCM) signals. DMIC can be viewed as a PDM
+ receiver.
+
+maintainers:
+ - Jon Hunter <jonathanh@nvidia.com>
+ - Sameer Pujar <spujar@nvidia.com>
+
+properties:
+ $nodename:
+ pattern: "^dmic@[0-9a-f]*$"
+
+ compatible:
+ oneOf:
+ - const: nvidia,tegra210-dmic
+ - items:
+ - enum:
+ - nvidia,tegra194-dmic
+ - nvidia,tegra186-dmic
+ - const: nvidia,tegra210-dmic
+
+ reg:
+ maxItems: 1
+
+ clocks:
+ maxItems: 1
+
+ clock-names:
+ const: dmic
+
+ assigned-clocks:
+ maxItems: 1
+
+ assigned-clock-parents:
+ maxItems: 1
+
+ assigned-clock-rates:
+ maxItems: 1
+
+ sound-name-prefix:
+ pattern: "^DMIC[1-9]$"
+ allOf:
+ - $ref: /schemas/types.yaml#/definitions/string
+ description:
+ used as prefix for sink/source names of the component. Must be a
+ unique string among multiple instances of the same component.
+ The name can be "DMIC1" or "DMIC2" ... "DMICx", where x depends
+ on the maximum available instances on a Tegra SoC.
+
+required:
+ - compatible
+ - reg
+ - clocks
+ - clock-names
+ - assigned-clocks
+ - assigned-clock-parents
+
+examples:
+ - |
+ #include<dt-bindings/clock/tegra210-car.h>
+
+ dmic@702d4000 {
+ compatible = "nvidia,tegra210-dmic";
+ reg = <0x702d4000 0x100>;
+ clocks = <&tegra_car TEGRA210_CLK_DMIC1>;
+ clock-names = "dmic";
+ assigned-clocks = <&tegra_car TEGRA210_CLK_DMIC1>;
+ assigned-clock-parents = <&tegra_car TEGRA210_CLK_PLL_A_OUT0>;
+ assigned-clock-rates = <3072000>;
+ sound-name-prefix = "DMIC1";
+ };
+
+...
diff --git a/Documentation/devicetree/bindings/sound/nvidia,tegra210-i2s.yaml b/Documentation/devicetree/bindings/sound/nvidia,tegra210-i2s.yaml
new file mode 100644
index 0000000..7957970
--- /dev/null
+++ b/Documentation/devicetree/bindings/sound/nvidia,tegra210-i2s.yaml
@@ -0,0 +1,101 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/sound/nvidia,tegra210-i2s.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Tegra210 I2S Controller Device Tree Bindings
+
+description: |
+ The Inter-IC Sound (I2S) controller implements full-duplex,
+ bi-directional and single direction point-to-point serial
+ interfaces. It can interface with I2S compatible devices.
+ I2S controller can operate both in master and slave mode.
+
+maintainers:
+ - Jon Hunter <jonathanh@nvidia.com>
+ - Sameer Pujar <spujar@nvidia.com>
+
+properties:
+ $nodename:
+ pattern: "^i2s@[0-9a-f]*$"
+
+ compatible:
+ oneOf:
+ - const: nvidia,tegra210-i2s
+ - items:
+ - enum:
+ - nvidia,tegra194-i2s
+ - nvidia,tegra186-i2s
+ - const: nvidia,tegra210-i2s
+
+ reg:
+ maxItems: 1
+
+ clocks:
+ minItems: 1
+ maxItems: 2
+ items:
+ - description: I2S bit clock
+ - description:
+ Sync input clock, which can act as clock source to other I/O
+ modules in AHUB. The Tegra I2S driver sets this clock rate as
+ per bit clock rate. I/O module which wants to use this clock
+ as source, can mention this clock as parent in the DT bindings.
+ This is an optional clock entry, since it is only required when
+ some other I/O wants to reference from a particular I2Sx
+ instance.
+
+ clock-names:
+ minItems: 1
+ maxItems: 2
+ items:
+ - const: i2s
+ - const: sync_input
+
+ assigned-clocks:
+ minItems: 1
+ maxItems: 2
+
+ assigned-clock-parents:
+ minItems: 1
+ maxItems: 2
+
+ assigned-clock-rates:
+ minItems: 1
+ maxItems: 2
+
+ sound-name-prefix:
+ pattern: "^I2S[1-9]$"
+ allOf:
+ - $ref: /schemas/types.yaml#/definitions/string
+ description:
+ Used as prefix for sink/source names of the component. Must be a
+ unique string among multiple instances of the same component.
+ The name can be "I2S1" or "I2S2" ... "I2Sx", where x depends
+ on the maximum available instances on a Tegra SoC.
+
+required:
+ - compatible
+ - reg
+ - clocks
+ - clock-names
+ - assigned-clocks
+ - assigned-clock-parents
+
+examples:
+ - |
+ #include<dt-bindings/clock/tegra210-car.h>
+
+ i2s@702d1000 {
+ compatible = "nvidia,tegra210-i2s";
+ reg = <0x702d1000 0x100>;
+ clocks = <&tegra_car TEGRA210_CLK_I2S0>;
+ clock-names = "i2s";
+ assigned-clocks = <&tegra_car TEGRA210_CLK_I2S0>;
+ assigned-clock-parents = <&tegra_car TEGRA210_CLK_PLL_A_OUT0>;
+ assigned-clock-rates = <1536000>;
+ sound-name-prefix = "I2S1";
+ };
+
+...
diff --git a/Documentation/devicetree/bindings/sound/qcom,q6asm.txt b/Documentation/devicetree/bindings/sound/qcom,q6asm.txt
index 6b9a88d..8c4883be 100644
--- a/Documentation/devicetree/bindings/sound/qcom,q6asm.txt
+++ b/Documentation/devicetree/bindings/sound/qcom,q6asm.txt
@@ -39,9 +39,9 @@
Usage: Required for Compress offload dais
Value type: <u32>
Definition: Specifies the direction of the dai stream
- 0 for both tx and rx
- 1 for only tx (Capture/Encode)
- 2 for only rx (Playback/Decode)
+ Q6ASM_DAI_TX_RX (0) for both tx and rx
+ Q6ASM_DAI_TX (1) for only tx (Capture/Encode)
+ Q6ASM_DAI_RX (2) for only rx (Playback/Decode)
- is-compress-dai:
Usage: Required for Compress offload dais
@@ -50,6 +50,7 @@
= EXAMPLE
+#include <dt-bindings/sound/qcom,q6asm.h>
apr-service@7 {
compatible = "qcom,q6asm";
@@ -62,7 +63,7 @@
dai@0 {
reg = <0>;
- direction = <2>;
+ direction = <Q6ASM_DAI_RX>;
is-compress-dai;
};
};
diff --git a/Documentation/devicetree/bindings/sound/renesas,fsi.yaml b/Documentation/devicetree/bindings/sound/renesas,fsi.yaml
index 8a4406b..0dd3f73 100644
--- a/Documentation/devicetree/bindings/sound/renesas,fsi.yaml
+++ b/Documentation/devicetree/bindings/sound/renesas,fsi.yaml
@@ -43,30 +43,19 @@
'#sound-dai-cells':
const: 1
- fsia,spdif-connection:
+patternProperties:
+ "^fsi(a|b),spdif-connection$":
$ref: /schemas/types.yaml#/definitions/flag
description: FSI is connected by S/PDIF
- fsia,stream-mode-support:
+ "^fsi(a|b),stream-mode-support$":
$ref: /schemas/types.yaml#/definitions/flag
description: FSI supports 16bit stream mode
- fsia,use-internal-clock:
+ "^fsi(a|b),use-internal-clock$":
$ref: /schemas/types.yaml#/definitions/flag
description: FSI uses internal clock when master mode
- fsib,spdif-connection:
- $ref: /schemas/types.yaml#/definitions/flag
- description: same as fsia
-
- fsib,stream-mode-support:
- $ref: /schemas/types.yaml#/definitions/flag
- description: same as fsia
-
- fsib,use-internal-clock:
- $ref: /schemas/types.yaml#/definitions/flag
- description: same as fsia
-
required:
- compatible
- reg
diff --git a/Documentation/devicetree/bindings/sound/renesas,rsnd.txt b/Documentation/devicetree/bindings/sound/renesas,rsnd.txt
index 1596f0d..b39743d 100644
--- a/Documentation/devicetree/bindings/sound/renesas,rsnd.txt
+++ b/Documentation/devicetree/bindings/sound/renesas,rsnd.txt
@@ -271,6 +271,7 @@
- "renesas,rcar_sound-r8a774a1" (RZ/G2M)
- "renesas,rcar_sound-r8a774b1" (RZ/G2N)
- "renesas,rcar_sound-r8a774c0" (RZ/G2E)
+ - "renesas,rcar_sound-r8a774e1" (RZ/G2H)
- "renesas,rcar_sound-r8a7778" (R-Car M1A)
- "renesas,rcar_sound-r8a7779" (R-Car H1)
- "renesas,rcar_sound-r8a7790" (R-Car H2)
diff --git a/Documentation/devicetree/bindings/sound/rockchip,rk3328-codec.txt b/Documentation/devicetree/bindings/sound/rockchip,rk3328-codec.txt
deleted file mode 100644
index 1ecd75d..0000000
--- a/Documentation/devicetree/bindings/sound/rockchip,rk3328-codec.txt
+++ /dev/null
@@ -1,28 +0,0 @@
-* Rockchip Rk3328 internal codec
-
-Required properties:
-
-- compatible: "rockchip,rk3328-codec"
-- reg: physical base address of the controller and length of memory mapped
- region.
-- rockchip,grf: the phandle of the syscon node for GRF register.
-- clocks: a list of phandle + clock-specifer pairs, one for each entry in clock-names.
-- clock-names: should be "pclk".
-- spk-depop-time-ms: speak depop time msec.
-
-Optional properties:
-
-- mute-gpios: GPIO specifier for external line driver control (typically the
- dedicated GPIO_MUTE pin)
-
-Example for rk3328 internal codec:
-
-codec: codec@ff410000 {
- compatible = "rockchip,rk3328-codec";
- reg = <0x0 0xff410000 0x0 0x1000>;
- rockchip,grf = <&grf>;
- clocks = <&cru PCLK_ACODEC>;
- clock-names = "pclk";
- mute-gpios = <&grf_gpio 0 GPIO_ACTIVE_LOW>;
- spk-depop-time-ms = 100;
-};
diff --git a/Documentation/devicetree/bindings/sound/rockchip,rk3328-codec.yaml b/Documentation/devicetree/bindings/sound/rockchip,rk3328-codec.yaml
new file mode 100644
index 0000000..5b85ad5
--- /dev/null
+++ b/Documentation/devicetree/bindings/sound/rockchip,rk3328-codec.yaml
@@ -0,0 +1,69 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/sound/rockchip,rk3328-codec.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Rockchip rk3328 internal codec
+
+maintainers:
+ - Heiko Stuebner <heiko@sntech.de>
+
+properties:
+ compatible:
+ const: rockchip,rk3328-codec
+
+ reg:
+ maxItems: 1
+
+ clocks:
+ items:
+ - description: clock for audio codec
+ - description: clock for I2S master clock
+
+ clock-names:
+ items:
+ - const: pclk
+ - const: mclk
+
+ rockchip,grf:
+ $ref: /schemas/types.yaml#/definitions/phandle
+ description:
+ The phandle of the syscon node for the GRF register.
+
+ spk-depop-time-ms:
+ default: 200
+ description:
+ Speaker depop time in msec.
+
+ mute-gpios:
+ maxItems: 1
+ description:
+ GPIO specifier for external line driver control (typically the
+ dedicated GPIO_MUTE pin)
+
+ "#sound-dai-cells":
+ const: 0
+
+required:
+ - compatible
+ - reg
+ - clocks
+ - clock-names
+ - rockchip,grf
+ - "#sound-dai-cells"
+
+examples:
+ - |
+ #include <dt-bindings/gpio/gpio.h>
+ #include <dt-bindings/clock/rk3328-cru.h>
+ codec: codec@ff410000 {
+ compatible = "rockchip,rk3328-codec";
+ reg = <0xff410000 0x1000>;
+ clocks = <&cru PCLK_ACODECPHY>, <&cru SCLK_I2S1>;
+ clock-names = "pclk", "mclk";
+ rockchip,grf = <&grf>;
+ mute-gpios = <&grf_gpio 0 GPIO_ACTIVE_LOW>;
+ spk-depop-time-ms = <100>;
+ #sound-dai-cells = <0>;
+ };
diff --git a/Documentation/devicetree/bindings/sound/rohm,bd28623.txt b/Documentation/devicetree/bindings/sound/rohm,bd28623.txt
deleted file mode 100644
index d84557c..0000000
--- a/Documentation/devicetree/bindings/sound/rohm,bd28623.txt
+++ /dev/null
@@ -1,29 +0,0 @@
-ROHM BD28623MUV Class D speaker amplifier for digital input
-
-This codec does not have any control buses such as I2C, it detect format and
-rate of I2S signal automatically. It has two signals that can be connected
-to GPIOs: reset and mute.
-
-Required properties:
-- compatible : should be "rohm,bd28623"
-- #sound-dai-cells: should be 0.
-- VCCA-supply : regulator phandle for the VCCA supply
-- VCCP1-supply : regulator phandle for the VCCP1 supply
-- VCCP2-supply : regulator phandle for the VCCP2 supply
-
-Optional properties:
-- reset-gpios : GPIO specifier for the active low reset line
-- mute-gpios : GPIO specifier for the active low mute line
-
-Example:
-
- codec {
- compatible = "rohm,bd28623";
- #sound-dai-cells = <0>;
-
- VCCA-supply = <&vcc_reg>;
- VCCP1-supply = <&vcc_reg>;
- VCCP2-supply = <&vcc_reg>;
- reset-gpios = <&gpio 0 GPIO_ACTIVE_LOW>;
- mute-gpios = <&gpio 1 GPIO_ACTIVE_LOW>;
- };
diff --git a/Documentation/devicetree/bindings/sound/rohm,bd28623.yaml b/Documentation/devicetree/bindings/sound/rohm,bd28623.yaml
new file mode 100644
index 0000000..859ce64
--- /dev/null
+++ b/Documentation/devicetree/bindings/sound/rohm,bd28623.yaml
@@ -0,0 +1,67 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/sound/rohm,bd28623.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: ROHM BD28623MUV Class D speaker amplifier for digital input
+
+description:
+ This codec does not have any control buses such as I2C, it detect
+ format and rate of I2S signal automatically. It has two signals
+ that can be connected to GPIOs reset and mute.
+
+maintainers:
+ - Katsuhiro Suzuki <katsuhiro@katsuster.net>
+
+properties:
+ compatible:
+ const: rohm,bd28623
+
+ "#sound-dai-cells":
+ const: 0
+
+ VCCA-supply:
+ description:
+ regulator phandle for the VCCA (for analog) power supply
+
+ VCCP1-supply:
+ description:
+ regulator phandle for the VCCP1 (for ch1) power supply
+
+ VCCP2-supply:
+ description:
+ regulator phandle for the VCCP2 (for ch2) power supply
+
+ reset-gpios:
+ maxItems: 1
+ description:
+ GPIO specifier for the active low reset line
+
+ mute-gpios:
+ maxItems: 1
+ description:
+ GPIO specifier for the active low mute line
+
+required:
+ - compatible
+ - VCCA-supply
+ - VCCP1-supply
+ - VCCP2-supply
+ - "#sound-dai-cells"
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/gpio/gpio.h>
+ codec {
+ compatible = "rohm,bd28623";
+ #sound-dai-cells = <0>;
+
+ VCCA-supply = <&vcc_reg>;
+ VCCP1-supply = <&vcc_reg>;
+ VCCP2-supply = <&vcc_reg>;
+ reset-gpios = <&gpio 0 GPIO_ACTIVE_LOW>;
+ mute-gpios = <&gpio 1 GPIO_ACTIVE_LOW>;
+ };
diff --git a/Documentation/devicetree/bindings/sound/samsung,aries-wm8994.yaml b/Documentation/devicetree/bindings/sound/samsung,aries-wm8994.yaml
new file mode 100644
index 0000000..902a0b6
--- /dev/null
+++ b/Documentation/devicetree/bindings/sound/samsung,aries-wm8994.yaml
@@ -0,0 +1,147 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/sound/samsung,aries-wm8994.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Samsung Aries audio complex with WM8994 codec
+
+maintainers:
+ - Jonathan Bakker <xc-racer2@live.ca>
+
+properties:
+ compatible:
+ oneOf:
+ - const: samsung,aries-wm8994
+ description: With FM radio and modem master
+
+ - const: samsung,fascinate4g-wm8994
+ description: Without FM radio and modem slave
+
+ model:
+ $ref: /schemas/types.yaml#/definitions/string
+ description: The user-visible name of this sound complex.
+
+ cpu:
+ type: object
+ properties:
+ sound-dai:
+ minItems: 2
+ maxItems: 2
+ $ref: /schemas/types.yaml#/definitions/phandle-array
+ description: |
+ phandles to the I2S controller and bluetooth codec,
+ in that order
+
+ codec:
+ type: object
+ properties:
+ sound-dai:
+ $ref: /schemas/types.yaml#/definitions/phandle-array
+ description: phandle to the WM8994 CODEC
+
+ samsung,audio-routing:
+ $ref: /schemas/types.yaml#/definitions/non-unique-string-array
+ description: |
+ List of the connections between audio
+ components; each entry is a pair of strings, the first being the
+ connection's sink, the second being the connection's source;
+ valid names for sources and sinks are the WM8994's pins (as
+ documented in its binding), and the jacks on the board -
+ For samsung,aries-wm8994: HP, SPK, RCV, LINE, Main Mic, Headset Mic,
+ or FM In
+ For samsung,fascinate4g-wm8994: HP, SPK, RCV, LINE, Main Mic,
+ or HeadsetMic
+
+ extcon:
+ description: Extcon phandle for dock detection
+
+ main-micbias-supply:
+ description: Supply for the micbias on the main mic
+
+ headset-micbias-supply:
+ description: Supply for the micbias on the headset mic
+
+ earpath-sel-gpios:
+ description: GPIO for switching between tv-out and mic paths
+
+ headset-detect-gpios:
+ description: GPIO for detection of headset insertion
+
+ headset-key-gpios:
+ description: GPIO for detection of headset key press
+
+ io-channels:
+ maxItems: 1
+ description: IO channel to read micbias voltage for headset detection
+
+ io-channel-names:
+ const: headset-detect
+
+required:
+ - compatible
+ - model
+ - cpu
+ - codec
+ - samsung,audio-routing
+ - extcon
+ - main-micbias-supply
+ - headset-micbias-supply
+ - earpath-sel-gpios
+ - headset-detect-gpios
+ - headset-key-gpios
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/gpio/gpio.h>
+
+ sound {
+ compatible = "samsung,fascinate4g-wm8994";
+
+ model = "Fascinate4G";
+
+ extcon = <&fsa9480>;
+
+ main-micbias-supply = <&main_micbias_reg>;
+ headset-micbias-supply = <&headset_micbias_reg>;
+
+ earpath-sel-gpios = <&gpj2 6 GPIO_ACTIVE_HIGH>;
+
+ io-channels = <&adc 3>;
+ io-channel-names = "headset-detect";
+ headset-detect-gpios = <&gph0 6 GPIO_ACTIVE_HIGH>;
+ headset-key-gpios = <&gph3 6 GPIO_ACTIVE_HIGH>;
+
+ samsung,audio-routing =
+ "HP", "HPOUT1L",
+ "HP", "HPOUT1R",
+
+ "SPK", "SPKOUTLN",
+ "SPK", "SPKOUTLP",
+
+ "RCV", "HPOUT2N",
+ "RCV", "HPOUT2P",
+
+ "LINE", "LINEOUT2N",
+ "LINE", "LINEOUT2P",
+
+ "IN1LP", "Main Mic",
+ "IN1LN", "Main Mic",
+
+ "IN1RP", "Headset Mic",
+ "IN1RN", "Headset Mic";
+
+ pinctrl-names = "default";
+ pinctrl-0 = <&headset_det &earpath_sel>;
+
+ cpu {
+ sound-dai = <&i2s0>, <&bt_codec>;
+ };
+
+ codec {
+ sound-dai = <&wm8994>;
+ };
+ };
+
diff --git a/Documentation/devicetree/bindings/sound/samsung,midas-audio.yaml b/Documentation/devicetree/bindings/sound/samsung,midas-audio.yaml
new file mode 100644
index 0000000..1c755de
--- /dev/null
+++ b/Documentation/devicetree/bindings/sound/samsung,midas-audio.yaml
@@ -0,0 +1,108 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/sound/samsung,midas-audio.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Samsung Midas audio complex with WM1811 codec
+
+maintainers:
+ - Sylwester Nawrocki <s.nawrocki@samsung.com>
+
+properties:
+ compatible:
+ const: samsung,midas-audio
+
+ model:
+ $ref: /schemas/types.yaml#/definitions/string
+ description: The user-visible name of this sound complex.
+
+ cpu:
+ type: object
+ properties:
+ sound-dai:
+ $ref: /schemas/types.yaml#/definitions/phandle
+ description: phandle to the I2S controller
+ required:
+ - sound-dai
+
+ codec:
+ type: object
+ properties:
+ sound-dai:
+ $ref: /schemas/types.yaml#/definitions/phandle
+ description: phandle to the WM1811 CODEC
+ required:
+ - sound-dai
+
+ samsung,audio-routing:
+ $ref: /schemas/types.yaml#/definitions/non-unique-string-array
+ description: |
+ List of the connections between audio components; each entry is
+ a pair of strings, the first being the connection's sink, the second
+ being the connection's source; valid names for sources and sinks are
+ the WM1811's pins (as documented in its binding), and the jacks
+ on the board: HP, SPK, Main Mic, Sub Mic, Headset Mic.
+
+ mic-bias-supply:
+ description: Supply for the micbias on the Main microphone
+
+ submic-bias-supply:
+ description: Supply for the micbias on the Sub microphone
+
+ fm-sel-gpios:
+ description: GPIO pin for FM selection
+
+ lineout-sel-gpios:
+ description: GPIO pin for line out selection
+
+required:
+ - compatible
+ - model
+ - cpu
+ - codec
+ - samsung,audio-routing
+ - mic-bias-supply
+ - submic-bias-supply
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/gpio/gpio.h>
+
+ sound {
+ compatible = "samsung,midas-audio";
+ model = "Midas";
+
+ fm-sel-gpios = <&gpaa0 3 GPIO_ACTIVE_HIGH>;
+
+ mic-bias-supply = <&mic_bias_reg>;
+ submic-bias-supply = <&submic_bias_reg>;
+
+ samsung,audio-routing =
+ "HP", "HPOUT1L",
+ "HP", "HPOUT1R",
+
+ "SPK", "SPKOUTLN",
+ "SPK", "SPKOUTLP",
+ "SPK", "SPKOUTRN",
+ "SPK", "SPKOUTRP",
+
+ "RCV", "HPOUT2N",
+ "RCV", "HPOUT2P",
+
+ "IN1LP", "Main Mic",
+ "IN1LN", "Main Mic",
+ "IN1RP", "Sub Mic",
+ "IN1LP", "Sub Mic";
+
+ cpu {
+ sound-dai = <&i2s0>;
+ };
+
+ codec {
+ sound-dai = <&wm1811>;
+ };
+
+ };
diff --git a/Documentation/devicetree/bindings/sound/sgtl5000.txt b/Documentation/devicetree/bindings/sound/sgtl5000.txt
deleted file mode 100644
index 9d9ff51..0000000
--- a/Documentation/devicetree/bindings/sound/sgtl5000.txt
+++ /dev/null
@@ -1,60 +0,0 @@
-* Freescale SGTL5000 Stereo Codec
-
-Required properties:
-- compatible : "fsl,sgtl5000".
-
-- reg : the I2C address of the device
-
-- #sound-dai-cells: must be equal to 0
-
-- clocks : the clock provider of SYS_MCLK
-
-- VDDA-supply : the regulator provider of VDDA
-
-- VDDIO-supply: the regulator provider of VDDIO
-
-Optional properties:
-
-- VDDD-supply : the regulator provider of VDDD
-
-- micbias-resistor-k-ohms : the bias resistor to be used in kOhms
- The resistor can take values of 2k, 4k or 8k.
- If set to 0 it will be off.
- If this node is not mentioned or if the value is unknown, then
- micbias resistor is set to 4K.
-
-- micbias-voltage-m-volts : the bias voltage to be used in mVolts
- The voltage can take values from 1.25V to 3V by 250mV steps
- If this node is not mentioned or the value is unknown, then
- the value is set to 1.25V.
-
-- lrclk-strength: the LRCLK pad strength. Possible values are:
-0, 1, 2 and 3 as per the table below:
-
-VDDIO 1.8V 2.5V 3.3V
-0 = Disable
-1 = 1.66 mA 2.87 mA 4.02 mA
-2 = 3.33 mA 5.74 mA 8.03 mA
-3 = 4.99 mA 8.61 mA 12.05 mA
-
-- sclk-strength: the SCLK pad strength. Possible values are:
-0, 1, 2 and 3 as per the table below:
-
-VDDIO 1.8V 2.5V 3.3V
-0 = Disable
-1 = 1.66 mA 2.87 mA 4.02 mA
-2 = 3.33 mA 5.74 mA 8.03 mA
-3 = 4.99 mA 8.61 mA 12.05 mA
-
-Example:
-
-sgtl5000: codec@a {
- compatible = "fsl,sgtl5000";
- reg = <0x0a>;
- #sound-dai-cells = <0>;
- clocks = <&clks 150>;
- micbias-resistor-k-ohms = <2>;
- micbias-voltage-m-volts = <2250>;
- VDDA-supply = <®_3p3v>;
- VDDIO-supply = <®_3p3v>;
-};
diff --git a/Documentation/devicetree/bindings/sound/sgtl5000.yaml b/Documentation/devicetree/bindings/sound/sgtl5000.yaml
new file mode 100644
index 0000000..4f29b63
--- /dev/null
+++ b/Documentation/devicetree/bindings/sound/sgtl5000.yaml
@@ -0,0 +1,103 @@
+# SPDX-License-Identifier: GPL-2.0-only
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/sound/sgtl5000.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Freescale SGTL5000 Stereo Codec
+
+maintainers:
+ - Fabio Estevam <festevam@gmail.com>
+
+properties:
+ compatible:
+ const: fsl,sgtl5000
+
+ reg:
+ maxItems: 1
+
+ "#sound-dai-cells":
+ const: 0
+
+ clocks:
+ items:
+ - description: the clock provider of SYS_MCLK
+
+ VDDA-supply:
+ description: the regulator provider of VDDA
+
+ VDDIO-supply:
+ description: the regulator provider of VDDIO
+
+ VDDD-supply:
+ description: the regulator provider of VDDD
+
+ micbias-resistor-k-ohms:
+ description: The bias resistor to be used in kOhms. The resistor can take
+ values of 2k, 4k or 8k. If set to 0 it will be off. If this node is not
+ mentioned or if the value is unknown, then micbias resistor is set to
+ 4k.
+ $ref: "/schemas/types.yaml#/definitions/uint32"
+ enum: [ 0, 2, 4, 8 ]
+
+ micbias-voltage-m-volts:
+ description: The bias voltage to be used in mVolts. The voltage can take
+ values from 1.25V to 3V by 250mV steps. If this node is not mentioned
+ or the value is unknown, then the value is set to 1.25V.
+ $ref: "/schemas/types.yaml#/definitions/uint32"
+ enum: [ 1250, 1500, 1750, 2000, 2250, 2500, 2750, 3000 ]
+
+ lrclk-strength:
+ description: |
+ The LRCLK pad strength. Possible values are: 0, 1, 2 and 3 as per the
+ table below:
+
+ VDDIO 1.8V 2.5V 3.3V
+ 0 = Disable
+ 1 = 1.66 mA 2.87 mA 4.02 mA
+ 2 = 3.33 mA 5.74 mA 8.03 mA
+ 3 = 4.99 mA 8.61 mA 12.05 mA
+ $ref: "/schemas/types.yaml#/definitions/uint32"
+ enum: [ 0, 1, 2, 3 ]
+
+ sclk-strength:
+ description: |
+ The SCLK pad strength. Possible values are: 0, 1, 2 and 3 as per the
+ table below:
+
+ VDDIO 1.8V 2.5V 3.3V
+ 0 = Disable
+ 1 = 1.66 mA 2.87 mA 4.02 mA
+ 2 = 3.33 mA 5.74 mA 8.03 mA
+ 3 = 4.99 mA 8.61 mA 12.05 mA
+ $ref: "/schemas/types.yaml#/definitions/uint32"
+ enum: [ 0, 1, 2, 3 ]
+
+required:
+ - compatible
+ - reg
+ - "#sound-dai-cells"
+ - clocks
+ - VDDA-supply
+ - VDDIO-supply
+
+additionalProperties: false
+
+examples:
+ - |
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ codec@a {
+ compatible = "fsl,sgtl5000";
+ reg = <0x0a>;
+ #sound-dai-cells = <0>;
+ clocks = <&clks 150>;
+ micbias-resistor-k-ohms = <2>;
+ micbias-voltage-m-volts = <2250>;
+ VDDA-supply = <®_3p3v>;
+ VDDIO-supply = <®_3p3v>;
+ };
+ };
+...
diff --git a/Documentation/devicetree/bindings/sound/simple-card.yaml b/Documentation/devicetree/bindings/sound/simple-card.yaml
index 8132d0c..35e6690 100644
--- a/Documentation/devicetree/bindings/sound/simple-card.yaml
+++ b/Documentation/devicetree/bindings/sound/simple-card.yaml
@@ -378,6 +378,8 @@
- |
sound {
compatible = "simple-audio-card";
+ #address-cells = <1>;
+ #size-cells = <0>;
simple-audio-card,name = "rsnd-ak4643";
simple-audio-card,format = "left_j";
@@ -391,10 +393,12 @@
"ak4642 Playback", "DAI1 Playback";
dpcmcpu: simple-audio-card,cpu@0 {
+ reg = <0>;
sound-dai = <&rcar_sound 0>;
};
simple-audio-card,cpu@1 {
+ reg = <1>;
sound-dai = <&rcar_sound 1>;
};
@@ -418,6 +422,8 @@
- |
sound {
compatible = "simple-audio-card";
+ #address-cells = <1>;
+ #size-cells = <0>;
simple-audio-card,routing =
"pcm3168a Playback", "DAI1 Playback",
@@ -426,6 +432,7 @@
"pcm3168a Playback", "DAI4 Playback";
simple-audio-card,dai-link@0 {
+ reg = <0>;
format = "left_j";
bitclock-master = <&sndcpu0>;
frame-master = <&sndcpu0>;
@@ -439,22 +446,23 @@
};
simple-audio-card,dai-link@1 {
+ reg = <1>;
format = "i2s";
bitclock-master = <&sndcpu1>;
frame-master = <&sndcpu1>;
convert-channels = <8>; /* TDM Split */
- sndcpu1: cpu@0 {
+ sndcpu1: cpu0 {
sound-dai = <&rcar_sound 1>;
};
- cpu@1 {
+ cpu1 {
sound-dai = <&rcar_sound 2>;
};
- cpu@2 {
+ cpu2 {
sound-dai = <&rcar_sound 3>;
};
- cpu@3 {
+ cpu3 {
sound-dai = <&rcar_sound 4>;
};
codec {
@@ -466,6 +474,7 @@
};
simple-audio-card,dai-link@2 {
+ reg = <2>;
format = "i2s";
bitclock-master = <&sndcpu2>;
frame-master = <&sndcpu2>;
diff --git a/Documentation/devicetree/bindings/sound/socionext,uniphier-aio.yaml b/Documentation/devicetree/bindings/sound/socionext,uniphier-aio.yaml
new file mode 100644
index 0000000..4987eb9
--- /dev/null
+++ b/Documentation/devicetree/bindings/sound/socionext,uniphier-aio.yaml
@@ -0,0 +1,81 @@
+# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/sound/socionext,uniphier-aio.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: UniPhier AIO audio system
+
+maintainers:
+ - <alsa-devel@alsa-project.org>
+
+properties:
+ compatible:
+ enum:
+ - socionext,uniphier-ld11-aio
+ - socionext,uniphier-ld20-aio
+ - socionext,uniphier-pxs2-aio
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+ clock-names:
+ const: aio
+
+ clocks:
+ maxItems: 1
+
+ reset-names:
+ const: aio
+
+ resets:
+ maxItems: 1
+
+ socionext,syscon:
+ description: |
+ Specifies a phandle to soc-glue, which is used for changing mode of S/PDIF
+ signal pin to output from Hi-Z. This property is optional if you use I2S
+ signal pins only.
+ $ref: "/schemas/types.yaml#/definitions/phandle"
+
+ "#sound-dai-cells":
+ const: 1
+
+patternProperties:
+ "^port@[0-9]$":
+ type: object
+ properties:
+ endpoint: true
+ required:
+ - endpoint
+
+additionalProperties: false
+
+required:
+ - compatible
+ - reg
+ - interrupts
+ - clock-names
+ - clocks
+ - reset-names
+ - resets
+ - "#sound-dai-cells"
+
+examples:
+ - |
+ audio@56000000 {
+ compatible = "socionext,uniphier-ld20-aio";
+ reg = <0x56000000 0x80000>;
+ interrupts = <0 144 4>;
+ pinctrl-names = "default";
+ pinctrl-0 = <&pinctrl_aout>;
+ clock-names = "aio";
+ clocks = <&sys_clk 40>;
+ reset-names = "aio";
+ resets = <&sys_rst 40>;
+ #sound-dai-cells = <1>;
+ socionext,syscon = <&soc_glue>;
+ };
diff --git a/Documentation/devicetree/bindings/sound/socionext,uniphier-evea.yaml b/Documentation/devicetree/bindings/sound/socionext,uniphier-evea.yaml
new file mode 100644
index 0000000..228168f
--- /dev/null
+++ b/Documentation/devicetree/bindings/sound/socionext,uniphier-evea.yaml
@@ -0,0 +1,70 @@
+# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/sound/socionext,uniphier-evea.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: UniPhier EVEA SoC-internal sound codec
+
+maintainers:
+ - <alsa-devel@alsa-project.org>
+
+properties:
+ compatible:
+ const: socionext,uniphier-evea
+
+ reg:
+ maxItems: 1
+
+ clock-names:
+ items:
+ - const: evea
+ - const: exiv
+
+ clocks:
+ minItems: 2
+ maxItems: 2
+
+ reset-names:
+ items:
+ - const: evea
+ - const: exiv
+ - const: adamv
+
+ resets:
+ minItems: 3
+ maxItems: 3
+
+ "#sound-dai-cells":
+ const: 1
+
+patternProperties:
+ "^port@[0-9]$":
+ type: object
+ properties:
+ endpoint: true
+ required:
+ - endpoint
+
+additionalProperties: false
+
+required:
+ - compatible
+ - reg
+ - clock-names
+ - clocks
+ - reset-names
+ - resets
+ - "#sound-dai-cells"
+
+examples:
+ - |
+ codec@57900000 {
+ compatible = "socionext,uniphier-evea";
+ reg = <0x57900000 0x1000>;
+ clock-names = "evea", "exiv";
+ clocks = <&sys_clk 41>, <&sys_clk 42>;
+ reset-names = "evea", "exiv", "adamv";
+ resets = <&sys_rst 41>, <&sys_rst 42>, <&adamv_rst 0>;
+ #sound-dai-cells = <1>;
+ };
diff --git a/Documentation/devicetree/bindings/sound/st,sti-asoc-card.txt b/Documentation/devicetree/bindings/sound/st,sti-asoc-card.txt
index 4d51f3f..a6ffcde 100644
--- a/Documentation/devicetree/bindings/sound/st,sti-asoc-card.txt
+++ b/Documentation/devicetree/bindings/sound/st,sti-asoc-card.txt
@@ -5,7 +5,7 @@
sti sound drivers allows to expose sti SoC audio interface through the
generic ASoC simple card. For details about sound card declaration please refer to
-Documentation/devicetree/bindings/sound/simple-card.txt.
+Documentation/devicetree/bindings/sound/simple-card.yaml.
1) sti-uniperiph-dai: audio dai device.
---------------------------------------
diff --git a/Documentation/devicetree/bindings/sound/tas2552.txt b/Documentation/devicetree/bindings/sound/tas2552.txt
index 2d71eb0..a7eecad 100644
--- a/Documentation/devicetree/bindings/sound/tas2552.txt
+++ b/Documentation/devicetree/bindings/sound/tas2552.txt
@@ -33,4 +33,4 @@
};
For more product information please see the link below:
-http://www.ti.com/product/TAS2552
+https://www.ti.com/product/TAS2552
diff --git a/Documentation/devicetree/bindings/sound/tas2562.txt b/Documentation/devicetree/bindings/sound/tas2562.txt
index 94796b5..dc6d736 100644
--- a/Documentation/devicetree/bindings/sound/tas2562.txt
+++ b/Documentation/devicetree/bindings/sound/tas2562.txt
@@ -11,12 +11,14 @@
- compatible: - Should contain "ti,tas2562", "ti,tas2563".
- reg: - The i2c address. Should be 0x4c, 0x4d, 0x4e or 0x4f.
- ti,imon-slot-no:- TDM TX current sense time slot.
+ - ti,vmon-slot-no:- TDM TX voltage sense time slot. This slot must always be
+ greater then ti,imon-slot-no.
Optional properties:
- interrupt-parent: phandle to the interrupt controller which provides
the interrupt.
- interrupts: (GPIO) interrupt to which the chip is connected.
-- shut-down: GPIO used to control the state of the device.
+- shut-down-gpio: GPIO used to control the state of the device.
Examples:
tas2562@4c {
@@ -28,7 +30,8 @@
interrupt-parent = <&gpio1>;
interrupts = <14>;
- shut-down = <&gpio1 15 0>;
+ shut-down-gpio = <&gpio1 15 0>;
ti,imon-slot-no = <0>;
+ ti,vmon-slot-no = <1>;
};
diff --git a/Documentation/devicetree/bindings/sound/tas2562.yaml b/Documentation/devicetree/bindings/sound/tas2562.yaml
new file mode 100644
index 0000000..8d75a79
--- /dev/null
+++ b/Documentation/devicetree/bindings/sound/tas2562.yaml
@@ -0,0 +1,69 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+# Copyright (C) 2019 Texas Instruments Incorporated
+%YAML 1.2
+---
+$id: "http://devicetree.org/schemas/sound/tas2562.yaml#"
+$schema: "http://devicetree.org/meta-schemas/core.yaml#"
+
+title: Texas Instruments TAS2562 Smart PA
+
+maintainers:
+ - Dan Murphy <dmurphy@ti.com>
+
+description: |
+ The TAS2562 is a mono, digital input Class-D audio amplifier optimized for
+ efficiently driving high peak power into small loudspeakers.
+ Integrated speaker voltage and current sense provides for
+ real time monitoring of loudspeaker behavior.
+
+properties:
+ compatible:
+ enum:
+ - ti,tas2562
+ - ti,tas2563
+
+ reg:
+ maxItems: 1
+ description: |
+ I2C address of the device can be one of these 0x4c, 0x4d, 0x4e or 0x4f
+
+ shut-down-gpios:
+ description: GPIO used to control the state of the device.
+ deprecated: true
+
+ shutdown-gpios:
+ description: GPIO used to control the state of the device.
+
+ interrupts:
+ maxItems: 1
+
+ ti,imon-slot-no:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description: TDM TX current sense time slot.
+
+ '#sound-dai-cells':
+ const: 1
+
+required:
+ - compatible
+ - reg
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/gpio/gpio.h>
+ i2c0 {
+ #address-cells = <1>;
+ #size-cells = <0>;
+ codec: codec@4c {
+ compatible = "ti,tas2562";
+ reg = <0x4c>;
+ #sound-dai-cells = <1>;
+ interrupt-parent = <&gpio1>;
+ interrupts = <14>;
+ shutdown-gpios = <&gpio1 15 0>;
+ ti,imon-slot-no = <0>;
+ };
+ };
+
diff --git a/Documentation/devicetree/bindings/sound/tas2770.txt b/Documentation/devicetree/bindings/sound/tas2770.txt
deleted file mode 100644
index ede6bb3..0000000
--- a/Documentation/devicetree/bindings/sound/tas2770.txt
+++ /dev/null
@@ -1,37 +0,0 @@
-Texas Instruments TAS2770 Smart PA
-
-The TAS2770 is a mono, digital input Class-D audio amplifier optimized for
-efficiently driving high peak power into small loudspeakers.
-Integrated speaker voltage and current sense provides for
-real time monitoring of loudspeaker behavior.
-
-Required properties:
-
- - compatible: - Should contain "ti,tas2770".
- - reg: - The i2c address. Should contain <0x4c>, <0x4d>,<0x4e>, or <0x4f>.
- - #address-cells - Should be <1>.
- - #size-cells - Should be <0>.
- - ti,asi-format: - Sets TDM RX capture edge. 0->Rising; 1->Falling.
- - ti,imon-slot-no:- TDM TX current sense time slot.
- - ti,vmon-slot-no:- TDM TX voltage sense time slot.
-
-Optional properties:
-
-- interrupt-parent: the phandle to the interrupt controller which provides
- the interrupt.
-- interrupts: interrupt specification for data-ready.
-
-Examples:
-
- tas2770@4c {
- compatible = "ti,tas2770";
- reg = <0x4c>;
- #address-cells = <1>;
- #size-cells = <0>;
- interrupt-parent = <&msm_gpio>;
- interrupts = <97 0>;
- ti,asi-format = <0>;
- ti,imon-slot-no = <0>;
- ti,vmon-slot-no = <2>;
- };
-
diff --git a/Documentation/devicetree/bindings/sound/tas2770.yaml b/Documentation/devicetree/bindings/sound/tas2770.yaml
new file mode 100644
index 0000000..8192450
--- /dev/null
+++ b/Documentation/devicetree/bindings/sound/tas2770.yaml
@@ -0,0 +1,76 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+# Copyright (C) 2019-20 Texas Instruments Incorporated
+%YAML 1.2
+---
+$id: "http://devicetree.org/schemas/sound/tas2770.yaml#"
+$schema: "http://devicetree.org/meta-schemas/core.yaml#"
+
+title: Texas Instruments TAS2770 Smart PA
+
+maintainers:
+ - Shi Fu <shifu0704@thundersoft.com>
+
+description: |
+ The TAS2770 is a mono, digital input Class-D audio amplifier optimized for
+ efficiently driving high peak power into small loudspeakers.
+ Integrated speaker voltage and current sense provides for
+ real time monitoring of loudspeaker behavior.
+
+properties:
+ compatible:
+ enum:
+ - ti,tas2770
+
+ reg:
+ maxItems: 1
+ description: |
+ I2C address of the device can be one of these 0x4c, 0x4d, 0x4e or 0x4f
+
+ reset-gpio:
+ description: GPIO used to reset the device.
+
+ interrupts:
+ maxItems: 1
+
+ ti,imon-slot-no:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description: TDM TX current sense time slot.
+
+ ti,vmon-slot-no:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description: TDM TX voltage sense time slot.
+
+ ti,asi-format:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description: Sets TDM RX capture edge.
+ enum:
+ - 0 # Rising edge
+ - 1 # Falling edge
+
+ '#sound-dai-cells':
+ const: 1
+
+required:
+ - compatible
+ - reg
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/gpio/gpio.h>
+ i2c0 {
+ #address-cells = <1>;
+ #size-cells = <0>;
+ codec: codec@4c {
+ compatible = "ti,tas2770";
+ reg = <0x4c>;
+ #sound-dai-cells = <1>;
+ interrupt-parent = <&gpio1>;
+ interrupts = <14>;
+ reset-gpio = <&gpio1 15 0>;
+ ti,imon-slot-no = <0>;
+ ti,vmon-slot-no = <2>;
+ };
+ };
+
diff --git a/Documentation/devicetree/bindings/sound/tas5720.txt b/Documentation/devicetree/bindings/sound/tas5720.txt
index 7481653f..df99ca9 100644
--- a/Documentation/devicetree/bindings/sound/tas5720.txt
+++ b/Documentation/devicetree/bindings/sound/tas5720.txt
@@ -4,9 +4,9 @@
serial bus is also used for periodic codec fault checking/reporting during
audio playback. For more product information please see the links below:
-http://www.ti.com/product/TAS5720L
-http://www.ti.com/product/TAS5720M
-http://www.ti.com/product/TAS5722L
+https://www.ti.com/product/TAS5720L
+https://www.ti.com/product/TAS5720M
+https://www.ti.com/product/TAS5722L
Required properties:
diff --git a/Documentation/devicetree/bindings/sound/ti,j721e-cpb-audio.yaml b/Documentation/devicetree/bindings/sound/ti,j721e-cpb-audio.yaml
new file mode 100644
index 0000000..6f2be65
--- /dev/null
+++ b/Documentation/devicetree/bindings/sound/ti,j721e-cpb-audio.yaml
@@ -0,0 +1,95 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/sound/ti,j721e-cpb-audio.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Texas Instruments J721e Common Processor Board Audio Support
+
+maintainers:
+ - Peter Ujfalusi <peter.ujfalusi@ti.com>
+
+description: |
+ The audio support on the board is using pcm3168a codec connected to McASP10
+ serializers in parallel setup.
+ The pcm3168a SCKI clock is sourced from j721e AUDIO_REFCLK2 pin.
+ In order to support 48KHz and 44.1KHz family of sampling rates the parent
+ clock for AUDIO_REFCLK2 needs to be changed between PLL4 (for 48KHz) and
+ PLL15 (for 44.1KHz). The same PLLs are used for McASP10's AUXCLK clock via
+ different HSDIVIDER.
+
+ Clocking setup for 48KHz family:
+ PLL4 ---> PLL4_HSDIV0 ---> MCASP10_AUXCLK ---> McASP10.auxclk
+ |-> PLL4_HSDIV2 ---> AUDIO_REFCLK2 ---> pcm3168a.SCKI
+
+ Clocking setup for 44.1KHz family:
+ PLL15 ---> PLL15_HSDIV0 ---> MCASP10_AUXCLK ---> McASP10.auxclk
+ |-> PLL15_HSDIV2 ---> AUDIO_REFCLK2 ---> pcm3168a.SCKI
+
+properties:
+ compatible:
+ items:
+ - const: ti,j721e-cpb-audio
+
+ model:
+ $ref: /schemas/types.yaml#/definitions/string
+ description: User specified audio sound card name
+
+ ti,cpb-mcasp:
+ description: phandle to McASP used on CPB
+ allOf:
+ - $ref: /schemas/types.yaml#/definitions/phandle
+
+ ti,cpb-codec:
+ description: phandle to the pcm3168a codec used on the CPB
+ allOf:
+ - $ref: /schemas/types.yaml#/definitions/phandle
+
+ clocks:
+ items:
+ - description: AUXCLK clock for McASP used by CPB audio
+ - description: Parent for CPB_McASP auxclk (for 48KHz)
+ - description: Parent for CPB_McASP auxclk (for 44.1KHz)
+ - description: SCKI clock for the pcm3168a codec on CPB
+ - description: Parent for CPB_SCKI clock (for 48KHz)
+ - description: Parent for CPB_SCKI clock (for 44.1KHz)
+
+ clock-names:
+ items:
+ - const: cpb-mcasp-auxclk
+ - const: cpb-mcasp-auxclk-48000
+ - const: cpb-mcasp-auxclk-44100
+ - const: cpb-codec-scki
+ - const: cpb-codec-scki-48000
+ - const: cpb-codec-scki-44100
+
+required:
+ - compatible
+ - model
+ - ti,cpb-mcasp
+ - ti,cpb-codec
+ - clocks
+ - clock-names
+
+additionalProperties: false
+
+examples:
+ - |+
+ sound {
+ compatible = "ti,j721e-cpb-audio";
+ model = "j721e-cpb";
+
+ status = "okay";
+
+ ti,cpb-mcasp = <&mcasp10>;
+ ti,cpb-codec = <&pcm3168a_1>;
+
+ clocks = <&k3_clks 184 1>,
+ <&k3_clks 184 2>, <&k3_clks 184 4>,
+ <&k3_clks 157 371>,
+ <&k3_clks 157 400>, <&k3_clks 157 401>;
+ clock-names = "cpb-mcasp-auxclk",
+ "cpb-mcasp-auxclk-48000", "cpb-mcasp-auxclk-44100",
+ "cpb-codec-scki",
+ "cpb-codec-scki-48000", "cpb-codec-scki-44100";
+ };
diff --git a/Documentation/devicetree/bindings/sound/ti,j721e-cpb-ivi-audio.yaml b/Documentation/devicetree/bindings/sound/ti,j721e-cpb-ivi-audio.yaml
new file mode 100644
index 0000000..e0b8847
--- /dev/null
+++ b/Documentation/devicetree/bindings/sound/ti,j721e-cpb-ivi-audio.yaml
@@ -0,0 +1,150 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/sound/ti,j721e-cpb-ivi-audio.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Texas Instruments J721e Common Processor Board Audio Support
+
+maintainers:
+ - Peter Ujfalusi <peter.ujfalusi@ti.com>
+
+description: |
+ The Infotainment board plugs into the Common Processor Board, the support of the
+ extension board is extending the CPB audio support, decribed in:
+ sound/ti,j721e-cpb-audio.txt
+
+ The audio support on the Infotainment Expansion Board consists of McASP0
+ connected to two pcm3168a codecs with dedicated set of serializers to each.
+ The SCKI for pcm3168a is sourced from j721e AUDIO_REFCLK0 pin.
+
+ In order to support 48KHz and 44.1KHz family of sampling rates the parent clock
+ for AUDIO_REFCLK0 needs to be changed between PLL4 (for 48KHz) and PLL15 (for
+ 44.1KHz). The same PLLs are used for McASP0's AUXCLK clock via different
+ HSDIVIDER.
+
+ Note: the same PLL4 and PLL15 is used by the audio support on the CPB!
+
+ Clocking setup for 48KHz family:
+ PLL4 ---> PLL4_HSDIV0 ---> MCASP10_AUXCLK ---> McASP10.auxclk
+ | |-> MCASP0_AUXCLK ---> McASP0.auxclk
+ |
+ |-> PLL4_HSDIV2 ---> AUDIO_REFCLK2 ---> pcm3168a.SCKI
+ |-> AUDIO_REFCLK0 ---> pcm3168a_a/b.SCKI
+
+ Clocking setup for 44.1KHz family:
+ PLL15 ---> PLL15_HSDIV0 ---> MCASP10_AUXCLK ---> McASP10.auxclk
+ | |-> MCASP0_AUXCLK ---> McASP0.auxclk
+ |
+ |-> PLL15_HSDIV2 ---> AUDIO_REFCLK2 ---> pcm3168a.SCKI
+ |-> AUDIO_REFCLK0 ---> pcm3168a_a/b.SCKI
+
+properties:
+ compatible:
+ items:
+ - const: ti,j721e-cpb-ivi-audio
+
+ model:
+ $ref: /schemas/types.yaml#/definitions/string
+ description: User specified audio sound card name
+
+ ti,cpb-mcasp:
+ description: phandle to McASP used on CPB
+ allOf:
+ - $ref: /schemas/types.yaml#/definitions/phandle
+
+ ti,cpb-codec:
+ description: phandle to the pcm3168a codec used on the CPB
+ allOf:
+ - $ref: /schemas/types.yaml#/definitions/phandle
+
+ ti,ivi-mcasp:
+ description: phandle to McASP used on IVI
+ allOf:
+ - $ref: /schemas/types.yaml#/definitions/phandle
+
+ ti,ivi-codec-a:
+ description: phandle to the pcm3168a-A codec on the expansion board
+ allOf:
+ - $ref: /schemas/types.yaml#/definitions/phandle
+
+ ti,ivi-codec-b:
+ description: phandle to the pcm3168a-B codec on the expansion board
+ allOf:
+ - $ref: /schemas/types.yaml#/definitions/phandle
+
+ clocks:
+ items:
+ - description: AUXCLK clock for McASP used by CPB audio
+ - description: Parent for CPB_McASP auxclk (for 48KHz)
+ - description: Parent for CPB_McASP auxclk (for 44.1KHz)
+ - description: SCKI clock for the pcm3168a codec on CPB
+ - description: Parent for CPB_SCKI clock (for 48KHz)
+ - description: Parent for CPB_SCKI clock (for 44.1KHz)
+ - description: AUXCLK clock for McASP used by IVI audio
+ - description: Parent for IVI_McASP auxclk (for 48KHz)
+ - description: Parent for IVI_McASP auxclk (for 44.1KHz)
+ - description: SCKI clock for the pcm3168a codec on IVI
+ - description: Parent for IVI_SCKI clock (for 48KHz)
+ - description: Parent for IVI_SCKI clock (for 44.1KHz)
+
+ clock-names:
+ items:
+ - const: cpb-mcasp-auxclk
+ - const: cpb-mcasp-auxclk-48000
+ - const: cpb-mcasp-auxclk-44100
+ - const: cpb-codec-scki
+ - const: cpb-codec-scki-48000
+ - const: cpb-codec-scki-44100
+ - const: ivi-mcasp-auxclk
+ - const: ivi-mcasp-auxclk-48000
+ - const: ivi-mcasp-auxclk-44100
+ - const: ivi-codec-scki
+ - const: ivi-codec-scki-48000
+ - const: ivi-codec-scki-44100
+
+required:
+ - compatible
+ - model
+ - ti,cpb-mcasp
+ - ti,cpb-codec
+ - ti,ivi-mcasp
+ - ti,ivi-codec-a
+ - ti,ivi-codec-b
+ - clocks
+ - clock-names
+
+additionalProperties: false
+
+examples:
+ - |+
+ sound {
+ compatible = "ti,j721e-cpb-ivi-audio";
+ model = "j721e-cpb-ivi";
+
+ status = "okay";
+
+ ti,cpb-mcasp = <&mcasp10>;
+ ti,cpb-codec = <&pcm3168a_1>;
+
+ ti,ivi-mcasp = <&mcasp0>;
+ ti,ivi-codec-a = <&pcm3168a_a>;
+ ti,ivi-codec-b = <&pcm3168a_b>;
+
+ clocks = <&k3_clks 184 1>,
+ <&k3_clks 184 2>, <&k3_clks 184 4>,
+ <&k3_clks 157 371>,
+ <&k3_clks 157 400>, <&k3_clks 157 401>,
+ <&k3_clks 174 1>,
+ <&k3_clks 174 2>, <&k3_clks 174 4>,
+ <&k3_clks 157 301>,
+ <&k3_clks 157 330>, <&k3_clks 157 331>;
+ clock-names = "cpb-mcasp-auxclk",
+ "cpb-mcasp-auxclk-48000", "cpb-mcasp-auxclk-44100",
+ "cpb-codec-scki",
+ "cpb-codec-scki-48000", "cpb-codec-scki-44100",
+ "ivi-mcasp-auxclk",
+ "ivi-mcasp-auxclk-48000", "ivi-mcasp-auxclk-44100",
+ "ivi-codec-scki",
+ "ivi-codec-scki-48000", "ivi-codec-scki-44100";
+ };
diff --git a/Documentation/devicetree/bindings/sound/ti,tas6424.txt b/Documentation/devicetree/bindings/sound/ti,tas6424.txt
index eacb54f..00940c4 100644
--- a/Documentation/devicetree/bindings/sound/ti,tas6424.txt
+++ b/Documentation/devicetree/bindings/sound/ti,tas6424.txt
@@ -19,4 +19,4 @@
};
For more product information please see the link below:
-http://www.ti.com/product/TAS6424-Q1
+https://www.ti.com/product/TAS6424-Q1
diff --git a/Documentation/devicetree/bindings/sound/tlv320adcx140.yaml b/Documentation/devicetree/bindings/sound/tlv320adcx140.yaml
index 2e6ac5d..e84d4a2 100644
--- a/Documentation/devicetree/bindings/sound/tlv320adcx140.yaml
+++ b/Documentation/devicetree/bindings/sound/tlv320adcx140.yaml
@@ -18,9 +18,9 @@
microphone bias or supply voltage generation.
Specifications can be found at:
- http://www.ti.com/lit/ds/symlink/tlv320adc3140.pdf
- http://www.ti.com/lit/ds/symlink/tlv320adc5140.pdf
- http://www.ti.com/lit/ds/symlink/tlv320adc6140.pdf
+ https://www.ti.com/lit/ds/symlink/tlv320adc3140.pdf
+ https://www.ti.com/lit/ds/symlink/tlv320adc5140.pdf
+ https://www.ti.com/lit/ds/symlink/tlv320adc6140.pdf
properties:
compatible:
@@ -108,6 +108,32 @@
maximum: 7
default: [0, 0, 0, 0]
+patternProperties:
+ '^ti,gpo-config-[1-4]$':
+ $ref: /schemas/types.yaml#/definitions/uint32-array
+ description: |
+ Defines the configuration and output driver for the general purpose
+ output pins (GPO). These values are pairs, the first value is for the
+ configuration type and the second value is for the output drive type.
+ The array is defined as <GPO_CFG GPO_DRV>
+
+ GPO output configuration can be one of the following:
+
+ 0 - (default) disabled
+ 1 - GPOX is configured as a general-purpose output (GPO)
+ 2 - GPOX is configured as a device interrupt output (IRQ)
+ 3 - GPOX is configured as a secondary ASI output (SDOUT2)
+ 4 - GPOX is configured as a PDM clock output (PDMCLK)
+
+ GPO output drive configuration for the GPO pins can be one of the following:
+
+ 0d - (default) Hi-Z output
+ 1d - Drive active low and active high
+ 2d - Drive active low and weak high
+ 3d - Drive active low and Hi-Z
+ 4d - Drive weak low and active high
+ 5d - Drive Hi-Z and active high
+
required:
- compatible
- reg
@@ -124,6 +150,8 @@
ti,mic-bias-source = <6>;
ti,pdm-edge-select = <0 1 0 1>;
ti,gpi-config = <4 5 6 7>;
+ ti,gpo-config-1 = <0 0>;
+ ti,gpo-config-2 = <0 0>;
reset-gpios = <&gpio0 14 GPIO_ACTIVE_HIGH>;
};
};
diff --git a/Documentation/devicetree/bindings/sound/uniphier,aio.txt b/Documentation/devicetree/bindings/sound/uniphier,aio.txt
deleted file mode 100644
index 4ce68ed..0000000
--- a/Documentation/devicetree/bindings/sound/uniphier,aio.txt
+++ /dev/null
@@ -1,45 +0,0 @@
-Socionext UniPhier SoC audio driver
-
-The Socionext UniPhier audio subsystem consists of I2S and S/PDIF blocks in
-the same register space.
-
-Required properties:
-- compatible : should be one of the following:
- "socionext,uniphier-ld11-aio"
- "socionext,uniphier-ld20-aio"
- "socionext,uniphier-pxs2-aio"
-- reg : offset and length of the register set for the device.
-- interrupts : should contain I2S or S/PDIF interrupt.
-- pinctrl-names : should be "default".
-- pinctrl-0 : defined I2S signal pins for an external codec chip.
-- clock-names : should include following entries:
- "aio"
-- clocks : a list of phandle, should contain an entry for each
- entry in clock-names.
-- reset-names : should include following entries:
- "aio"
-- resets : a list of phandle, should contain an entry for each
- entry in reset-names.
-- #sound-dai-cells: should be 1.
-
-Optional properties:
-- socionext,syscon: a phandle, should contain soc-glue.
- The soc-glue is used for changing mode of S/PDIF signal pin
- to Output from Hi-Z. This property is optional if you use
- I2S signal pins only.
-
-Example:
- audio {
- compatible = "socionext,uniphier-ld20-aio";
- reg = <0x56000000 0x80000>;
- interrupts = <0 144 4>;
- pinctrl-names = "default";
- pinctrl-0 = <&pinctrl_aout>;
- clock-names = "aio";
- clocks = <&sys_clk 40>;
- reset-names = "aio";
- resets = <&sys_rst 40>;
- #sound-dai-cells = <1>;
-
- socionext,syscon = <&sg>;
- };
diff --git a/Documentation/devicetree/bindings/sound/uniphier,evea.txt b/Documentation/devicetree/bindings/sound/uniphier,evea.txt
deleted file mode 100644
index 3f31b23..0000000
--- a/Documentation/devicetree/bindings/sound/uniphier,evea.txt
+++ /dev/null
@@ -1,26 +0,0 @@
-Socionext EVEA - UniPhier SoC internal codec driver
-
-Required properties:
-- compatible : should be "socionext,uniphier-evea".
-- reg : offset and length of the register set for the device.
-- clock-names : should include following entries:
- "evea", "exiv"
-- clocks : a list of phandle, should contain an entry for each
- entries in clock-names.
-- reset-names : should include following entries:
- "evea", "exiv", "adamv"
-- resets : a list of phandle, should contain reset entries of
- reset-names.
-- #sound-dai-cells: should be 1.
-
-Example:
-
- codec {
- compatible = "socionext,uniphier-evea";
- reg = <0x57900000 0x1000>;
- clock-names = "evea", "exiv";
- clocks = <&sys_clk 41>, <&sys_clk 42>;
- reset-names = "evea", "exiv", "adamv";
- resets = <&sys_rst 41>, <&sys_rst 42>, <&adamv_rst 0>;
- #sound-dai-cells = <1>;
- };
diff --git a/Documentation/devicetree/bindings/sound/wm8960.txt b/Documentation/devicetree/bindings/sound/wm8960.txt
index 6d29ac37..85d3b28 100644
--- a/Documentation/devicetree/bindings/sound/wm8960.txt
+++ b/Documentation/devicetree/bindings/sound/wm8960.txt
@@ -21,6 +21,17 @@
enabled and disabled together with HP_L and HP_R pins in response to jack
detect events.
+ - wlf,hp-cfg: A list of headphone jack detect configuration register values.
+ The list must be 3 entries long.
+ hp-cfg[0]: HPSEL[1:0] of R48 (Additional Control 4).
+ hp-cfg[1]: {HPSWEN:HPSWPOL} of R24 (Additional Control 2).
+ hp-cfg[2]: {TOCLKSEL:TOEN} of R23 (Additional Control 1).
+
+ - wlf,gpio-cfg: A list of GPIO configuration register values.
+ The list must be 2 entries long.
+ gpio-cfg[0]: ALRCGPIO of R9 (Audio interface)
+ gpio-cfg[1]: {GPIOPOL:GPIOSEL[2:0]} of R48 (Additional Control 4).
+
Example:
wm8960: codec@1a {
diff --git a/Documentation/devicetree/bindings/sound/wm8994.txt b/Documentation/devicetree/bindings/sound/wm8994.txt
index 367b58c..8fa9475 100644
--- a/Documentation/devicetree/bindings/sound/wm8994.txt
+++ b/Documentation/devicetree/bindings/sound/wm8994.txt
@@ -68,6 +68,29 @@
- wlf,csnaddr-pd : If present enable the internal pull-down resistor on
the CS/ADDR pin.
+Pins on the device (for linking into audio routes):
+
+ * IN1LN
+ * IN1LP
+ * IN2LN
+ * IN2LP:VXRN
+ * IN1RN
+ * IN1RP
+ * IN2RN
+ * IN2RP:VXRP
+ * SPKOUTLP
+ * SPKOUTLN
+ * SPKOUTRP
+ * SPKOUTRN
+ * HPOUT1L
+ * HPOUT1R
+ * HPOUT2P
+ * HPOUT2N
+ * LINEOUT1P
+ * LINEOUT1N
+ * LINEOUT2P
+ * LINEOUT2N
+
Example:
wm8994: codec@1a {
diff --git a/Documentation/devicetree/bindings/spi/amlogic,meson-gx-spicc.yaml b/Documentation/devicetree/bindings/spi/amlogic,meson-gx-spicc.yaml
index 9147df2..38efb50 100644
--- a/Documentation/devicetree/bindings/spi/amlogic,meson-gx-spicc.yaml
+++ b/Documentation/devicetree/bindings/spi/amlogic,meson-gx-spicc.yaml
@@ -34,12 +34,15 @@
maxItems: 1
clocks:
- maxItems: 1
+ minItems: 1
+ maxItems: 2
+ items:
+ - description: controller register bus clock
+ - description: baud rate generator and delay control clock
clock-names:
- description: input clock for the baud rate generator
- items:
- - const: core
+ minItems: 1
+ maxItems: 2
if:
properties:
@@ -51,17 +54,22 @@
then:
properties:
clocks:
- contains:
- items:
- - description: controller register bus clock
- - description: baud rate generator and delay control clock
+ minItems: 2
clock-names:
- minItems: 2
items:
- const: core
- const: pclk
+else:
+ properties:
+ clocks:
+ maxItems: 1
+
+ clock-names:
+ items:
+ - const: core
+
required:
- compatible
- reg
diff --git a/Documentation/devicetree/bindings/spi/brcm,bcm2835-spi.txt b/Documentation/devicetree/bindings/spi/brcm,bcm2835-spi.txt
index f11f295..3d55dd6 100644
--- a/Documentation/devicetree/bindings/spi/brcm,bcm2835-spi.txt
+++ b/Documentation/devicetree/bindings/spi/brcm,bcm2835-spi.txt
@@ -5,7 +5,8 @@
auxiliary block. This binding applies to the SPI0 controller.
Required properties:
-- compatible: Should be "brcm,bcm2835-spi".
+- compatible: Should be one of "brcm,bcm2835-spi" for BCM2835/2836/2837 or
+ "brcm,bcm2711-spi" for BCM2711 or "brcm,bcm7211-spi" for BCM7211.
- reg: Should contain register location and length.
- interrupts: Should contain interrupt.
- clocks: The clock feeding the SPI controller.
diff --git a/Documentation/devicetree/bindings/spi/fsl-imx-cspi.txt b/Documentation/devicetree/bindings/spi/fsl-imx-cspi.txt
deleted file mode 100644
index 33bc58f..0000000
--- a/Documentation/devicetree/bindings/spi/fsl-imx-cspi.txt
+++ /dev/null
@@ -1,56 +0,0 @@
-* Freescale (Enhanced) Configurable Serial Peripheral Interface
- (CSPI/eCSPI) for i.MX
-
-Required properties:
-- compatible :
- - "fsl,imx1-cspi" for SPI compatible with the one integrated on i.MX1
- - "fsl,imx21-cspi" for SPI compatible with the one integrated on i.MX21
- - "fsl,imx27-cspi" for SPI compatible with the one integrated on i.MX27
- - "fsl,imx31-cspi" for SPI compatible with the one integrated on i.MX31
- - "fsl,imx35-cspi" for SPI compatible with the one integrated on i.MX35
- - "fsl,imx51-ecspi" for SPI compatible with the one integrated on i.MX51
- - "fsl,imx53-ecspi" for SPI compatible with the one integrated on i.MX53 and later Soc
- - "fsl,imx8mq-ecspi" for SPI compatible with the one integrated on i.MX8MQ
- - "fsl,imx8mm-ecspi" for SPI compatible with the one integrated on i.MX8MM
- - "fsl,imx8mn-ecspi" for SPI compatible with the one integrated on i.MX8MN
- - "fsl,imx8mp-ecspi" for SPI compatible with the one integrated on i.MX8MP
-- reg : Offset and length of the register set for the device
-- interrupts : Should contain CSPI/eCSPI interrupt
-- clocks : Clock specifiers for both ipg and per clocks.
-- clock-names : Clock names should include both "ipg" and "per"
-See the clock consumer binding,
- Documentation/devicetree/bindings/clock/clock-bindings.txt
-
-Recommended properties:
-- cs-gpios : GPIOs to use as chip selects, see spi-bus.txt. While the native chip
-select lines can be used, they appear to always generate a pulse between each
-word of a transfer. Most use cases will require GPIO based chip selects to
-generate a valid transaction.
-
-Optional properties:
-- num-cs : Number of total chip selects, see spi-bus.txt.
-- dmas: DMA specifiers for tx and rx dma. See the DMA client binding,
-Documentation/devicetree/bindings/dma/dma.txt.
-- dma-names: DMA request names, if present, should include "tx" and "rx".
-- fsl,spi-rdy-drctl: Integer, representing the value of DRCTL, the register
-controlling the SPI_READY handling. Note that to enable the DRCTL consideration,
-the SPI_READY mode-flag needs to be set too.
-Valid values are: 0 (disabled), 1 (edge-triggered burst) and 2 (level-triggered burst).
-
-Obsolete properties:
-- fsl,spi-num-chipselects : Contains the number of the chipselect
-
-Example:
-
-ecspi@70010000 {
- #address-cells = <1>;
- #size-cells = <0>;
- compatible = "fsl,imx51-ecspi";
- reg = <0x70010000 0x4000>;
- interrupts = <36>;
- cs-gpios = <&gpio3 24 0>, /* GPIO3_24 */
- <&gpio3 25 0>; /* GPIO3_25 */
- dmas = <&sdma 3 7 1>, <&sdma 4 7 2>;
- dma-names = "rx", "tx";
- fsl,spi-rdy-drctl = <1>;
-};
diff --git a/Documentation/devicetree/bindings/spi/fsl-imx-cspi.yaml b/Documentation/devicetree/bindings/spi/fsl-imx-cspi.yaml
new file mode 100644
index 0000000..6e44c9c
--- /dev/null
+++ b/Documentation/devicetree/bindings/spi/fsl-imx-cspi.yaml
@@ -0,0 +1,97 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/spi/fsl-imx-cspi.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Freescale (Enhanced) Configurable Serial Peripheral Interface (CSPI/eCSPI) for i.MX
+
+maintainers:
+ - Shawn Guo <shawn.guo@linaro.org>
+
+allOf:
+ - $ref: "/schemas/spi/spi-controller.yaml#"
+
+properties:
+ compatible:
+ oneOf:
+ - const: fsl,imx1-cspi
+ - const: fsl,imx21-cspi
+ - const: fsl,imx27-cspi
+ - const: fsl,imx31-cspi
+ - const: fsl,imx35-cspi
+ - const: fsl,imx51-ecspi
+ - const: fsl,imx53-ecspi
+ - items:
+ - enum:
+ - fsl,imx50-ecspi
+ - fsl,imx6q-ecspi
+ - fsl,imx6sx-ecspi
+ - fsl,imx6sl-ecspi
+ - fsl,imx6sll-ecspi
+ - fsl,imx6ul-ecspi
+ - fsl,imx7d-ecspi
+ - fsl,imx8mq-ecspi
+ - fsl,imx8mm-ecspi
+ - fsl,imx8mn-ecspi
+ - fsl,imx8mp-ecspi
+ - const: fsl,imx51-ecspi
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+ clocks:
+ items:
+ - description: SoC SPI ipg clock
+ - description: SoC SPI per clock
+
+ clock-names:
+ items:
+ - const: ipg
+ - const: per
+
+ dmas:
+ items:
+ - description: DMA controller phandle and request line for RX
+ - description: DMA controller phandle and request line for TX
+
+ dma-names:
+ items:
+ - const: rx
+ - const: tx
+
+ fsl,spi-rdy-drctl:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description: |
+ Integer, representing the value of DRCTL, the register controlling
+ the SPI_READY handling. Note that to enable the DRCTL consideration,
+ the SPI_READY mode-flag needs to be set too.
+ Valid values are: 0 (disabled), 1 (edge-triggered burst) and 2 (level-triggered burst).
+ enum: [0, 1, 2]
+
+required:
+ - compatible
+ - reg
+ - interrupts
+ - clocks
+ - clock-names
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/clock/imx5-clock.h>
+
+ spi@70010000 {
+ #address-cells = <1>;
+ #size-cells = <0>;
+ compatible = "fsl,imx51-ecspi";
+ reg = <0x70010000 0x4000>;
+ interrupts = <36>;
+ clocks = <&clks IMX5_CLK_ECSPI1_IPG_GATE>,
+ <&clks IMX5_CLK_ECSPI1_PER_GATE>;
+ clock-names = "ipg", "per";
+ };
diff --git a/Documentation/devicetree/bindings/spi/mxs-spi.txt b/Documentation/devicetree/bindings/spi/mxs-spi.txt
deleted file mode 100644
index 3499b73..0000000
--- a/Documentation/devicetree/bindings/spi/mxs-spi.txt
+++ /dev/null
@@ -1,26 +0,0 @@
-* Freescale MX233/MX28 SSP/SPI
-
-Required properties:
-- compatible: Should be "fsl,<soc>-spi", where soc is "imx23" or "imx28"
-- reg: Offset and length of the register set for the device
-- interrupts: Should contain SSP ERROR interrupt
-- dmas: DMA specifier, consisting of a phandle to DMA controller node
- and SSP DMA channel ID.
- Refer to dma.txt and fsl-mxs-dma.txt for details.
-- dma-names: Must be "rx-tx".
-
-Optional properties:
-- clock-frequency : Input clock frequency to the SPI block in Hz.
- Default is 160000000 Hz.
-
-Example:
-
-ssp0: ssp@80010000 {
- #address-cells = <1>;
- #size-cells = <0>;
- compatible = "fsl,imx28-spi";
- reg = <0x80010000 0x2000>;
- interrupts = <96>;
- dmas = <&dma_apbh 0>;
- dma-names = "rx-tx";
-};
diff --git a/Documentation/devicetree/bindings/spi/mxs-spi.yaml b/Documentation/devicetree/bindings/spi/mxs-spi.yaml
new file mode 100644
index 0000000..51f8c66
--- /dev/null
+++ b/Documentation/devicetree/bindings/spi/mxs-spi.yaml
@@ -0,0 +1,56 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/spi/mxs-spi.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Freescale MX233/MX28 SSP/SPI
+
+maintainers:
+ - Marek Vasut <marex@denx.de>
+
+allOf:
+ - $ref: "/schemas/spi/spi-controller.yaml#"
+
+properties:
+ compatible:
+ enum:
+ - fsl,imx23-spi
+ - fsl,imx28-spi
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+ dmas:
+ maxItems: 1
+
+ dma-names:
+ const: rx-tx
+
+ clock-frequency:
+ description: input clock frequency to the SPI block in Hz.
+ default: 160000000
+
+required:
+ - compatible
+ - reg
+ - interrupts
+ - dmas
+ - dma-names
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ spi@80010000 {
+ #address-cells = <1>;
+ #size-cells = <0>;
+ compatible = "fsl,imx28-spi";
+ reg = <0x80010000 0x2000>;
+ interrupts = <96>;
+ dmas = <&dma_apbh 0>;
+ dma-names = "rx-tx";
+ };
diff --git a/Documentation/devicetree/bindings/spi/qcom,spi-geni-qcom.txt b/Documentation/devicetree/bindings/spi/qcom,spi-geni-qcom.txt
index 790311a..c8c1e91 100644
--- a/Documentation/devicetree/bindings/spi/qcom,spi-geni-qcom.txt
+++ b/Documentation/devicetree/bindings/spi/qcom,spi-geni-qcom.txt
@@ -19,7 +19,7 @@
SPI Controller nodes must be child of GENI based Qualcomm Universal
Peripharal. Please refer GENI based QUP wrapper controller node bindings
-described in Documentation/devicetree/bindings/soc/qcom/qcom,geni-se.txt.
+described in Documentation/devicetree/bindings/soc/qcom/qcom,geni-se.yaml.
SPI slave nodes must be children of the SPI master node and conform to SPI bus
binding as described in Documentation/devicetree/bindings/spi/spi-bus.txt.
diff --git a/Documentation/devicetree/bindings/spi/renesas,sh-msiof.yaml b/Documentation/devicetree/bindings/spi/renesas,sh-msiof.yaml
index e84edcf..9f7b118 100644
--- a/Documentation/devicetree/bindings/spi/renesas,sh-msiof.yaml
+++ b/Documentation/devicetree/bindings/spi/renesas,sh-msiof.yaml
@@ -21,6 +21,7 @@
# device
- items:
- enum:
+ - renesas,msiof-r8a7742 # RZ/G1H
- renesas,msiof-r8a7743 # RZ/G1M
- renesas,msiof-r8a7744 # RZ/G1N
- renesas,msiof-r8a7745 # RZ/G1E
@@ -37,6 +38,7 @@
- renesas,msiof-r8a774a1 # RZ/G2M
- renesas,msiof-r8a774b1 # RZ/G2N
- renesas,msiof-r8a774c0 # RZ/G2E
+ - renesas,msiof-r8a774e1 # RZ/G2H
- renesas,msiof-r8a7795 # R-Car H3
- renesas,msiof-r8a7796 # R-Car M3-W
- renesas,msiof-r8a77965 # R-Car M3-N
diff --git a/Documentation/devicetree/bindings/spi/spi-davinci.txt b/Documentation/devicetree/bindings/spi/spi-davinci.txt
index 9f5b4c7..e2198a38 100644
--- a/Documentation/devicetree/bindings/spi/spi-davinci.txt
+++ b/Documentation/devicetree/bindings/spi/spi-davinci.txt
@@ -1,8 +1,8 @@
Davinci SPI controller device bindings
Links on DM:
-Keystone 2 - http://www.ti.com/lit/ug/sprugp2a/sprugp2a.pdf
-dm644x - http://www.ti.com/lit/ug/sprue32a/sprue32a.pdf
+Keystone 2 - https://www.ti.com/lit/ug/sprugp2a/sprugp2a.pdf
+dm644x - https://www.ti.com/lit/ug/sprue32a/sprue32a.pdf
OMAP-L138/da830 - http://www.ti.com/lit/ug/spruh77a/spruh77a.pdf
Required properties:
diff --git a/Documentation/devicetree/bindings/spi/spi-fsl-lpspi.txt b/Documentation/devicetree/bindings/spi/spi-fsl-lpspi.txt
deleted file mode 100644
index e71b81a..0000000
--- a/Documentation/devicetree/bindings/spi/spi-fsl-lpspi.txt
+++ /dev/null
@@ -1,29 +0,0 @@
-* Freescale Low Power SPI (LPSPI) for i.MX
-
-Required properties:
-- compatible :
- - "fsl,imx7ulp-spi" for LPSPI compatible with the one integrated on i.MX7ULP soc
- - "fsl,imx8qxp-spi" for LPSPI compatible with the one integrated on i.MX8QXP soc
-- reg : address and length of the lpspi master registers
-- interrupt-parent : core interrupt controller
-- interrupts : lpspi interrupt
-- clocks : lpspi clock specifier. Its number and order need to correspond to the
- value in clock-names.
-- clock-names : Corresponding to per clock and ipg clock in "clocks"
- respectively. In i.MX7ULP, it only has per clk, so use CLK_DUMMY
- to fill the "ipg" blank.
-- spi-slave : spi slave mode support. In slave mode, add this attribute without
- value. In master mode, remove it.
-
-Examples:
-
-lpspi2: lpspi@40290000 {
- compatible = "fsl,imx7ulp-spi";
- reg = <0x40290000 0x10000>;
- interrupt-parent = <&intc>;
- interrupts = <GIC_SPI 28 IRQ_TYPE_LEVEL_HIGH>;
- clocks = <&clks IMX7ULP_CLK_LPSPI2>,
- <&clks IMX7ULP_CLK_DUMMY>;
- clock-names = "per", "ipg";
- spi-slave;
-};
diff --git a/Documentation/devicetree/bindings/spi/spi-fsl-lpspi.yaml b/Documentation/devicetree/bindings/spi/spi-fsl-lpspi.yaml
new file mode 100644
index 0000000..22882e7
--- /dev/null
+++ b/Documentation/devicetree/bindings/spi/spi-fsl-lpspi.yaml
@@ -0,0 +1,67 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/spi/spi-fsl-lpspi.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Freescale Low Power SPI (LPSPI) for i.MX
+
+maintainers:
+ - Anson Huang <Anson.Huang@nxp.com>
+
+allOf:
+ - $ref: "/schemas/spi/spi-controller.yaml#"
+
+properties:
+ compatible:
+ enum:
+ - fsl,imx7ulp-spi
+ - fsl,imx8qxp-spi
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+ clocks:
+ items:
+ - description: SoC SPI per clock
+ - description: SoC SPI ipg clock
+
+ clock-names:
+ items:
+ - const: per
+ - const: ipg
+
+ fsl,spi-only-use-cs1-sel:
+ description:
+ spi common code does not support use of CS signals discontinuously.
+ i.MX8DXL-EVK board only uses CS1 without using CS0. Therefore, add
+ this property to re-config the chipselect value in the LPSPI driver.
+
+required:
+ - compatible
+ - reg
+ - interrupts
+ - clocks
+ - clock-names
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/clock/imx7ulp-clock.h>
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+
+ spi@40290000 {
+ compatible = "fsl,imx7ulp-spi";
+ reg = <0x40290000 0x10000>;
+ interrupt-parent = <&intc>;
+ interrupts = <GIC_SPI 28 IRQ_TYPE_LEVEL_HIGH>;
+ clocks = <&clks IMX7ULP_CLK_LPSPI2>,
+ <&clks IMX7ULP_CLK_DUMMY>;
+ clock-names = "per", "ipg";
+ spi-slave;
+ fsl,spi-only-use-cs1-sel;
+ };
diff --git a/Documentation/devicetree/bindings/spi/spi-lantiq-ssc.txt b/Documentation/devicetree/bindings/spi/spi-lantiq-ssc.txt
index ce3230c..76a3dd3 100644
--- a/Documentation/devicetree/bindings/spi/spi-lantiq-ssc.txt
+++ b/Documentation/devicetree/bindings/spi/spi-lantiq-ssc.txt
@@ -1,11 +1,17 @@
Lantiq Synchronous Serial Controller (SSC) SPI master driver
Required properties:
-- compatible: "lantiq,ase-spi", "lantiq,falcon-spi", "lantiq,xrx100-spi"
+- compatible: "lantiq,ase-spi", "lantiq,falcon-spi", "lantiq,xrx100-spi",
+ "intel,lgm-spi"
- #address-cells: see spi-bus.txt
- #size-cells: see spi-bus.txt
- reg: address and length of the spi master registers
-- interrupts: should contain the "spi_rx", "spi_tx" and "spi_err" interrupt.
+- interrupts:
+ For compatible "intel,lgm-ssc" - the common interrupt number for
+ all of tx rx & err interrupts.
+ or
+ For rest of the compatibles, should contain the "spi_rx", "spi_tx" and
+ "spi_err" interrupt.
Optional properties:
@@ -27,3 +33,14 @@
num-cs = <6>;
base-cs = <1>;
};
+
+ssc0: spi@e0800000 {
+ compatible = "intel,lgm-spi";
+ reg = <0xe0800000 0x400>;
+ interrupt-parent = <&ioapic1>;
+ interrupts = <35 1>;
+ #address-cells = <1>;
+ #size-cells = <0>;
+ clocks = <&cgu0 LGM_CLK_NGI>, <&cgu0 LGM_GCLK_SSC0>;
+ clock-names = "freq", "gate";
+};
diff --git a/Documentation/devicetree/bindings/spi/spi-mt65xx.txt b/Documentation/devicetree/bindings/spi/spi-mt65xx.txt
index 3a8079e..9e43721 100644
--- a/Documentation/devicetree/bindings/spi/spi-mt65xx.txt
+++ b/Documentation/devicetree/bindings/spi/spi-mt65xx.txt
@@ -11,6 +11,7 @@
- mediatek,mt8135-spi: for mt8135 platforms
- mediatek,mt8173-spi: for mt8173 platforms
- mediatek,mt8183-spi: for mt8183 platforms
+ - "mediatek,mt8192-spi", "mediatek,mt6765-spi": for mt8192 platforms
- "mediatek,mt8516-spi", "mediatek,mt2712-spi": for mt8516 platforms
- #address-cells: should be 1.
diff --git a/Documentation/devicetree/bindings/thermal/allwinner,sun8i-a83t-ths.yaml b/Documentation/devicetree/bindings/thermal/allwinner,sun8i-a83t-ths.yaml
index 8736926..44ba676 100644
--- a/Documentation/devicetree/bindings/thermal/allwinner,sun8i-a83t-ths.yaml
+++ b/Documentation/devicetree/bindings/thermal/allwinner,sun8i-a83t-ths.yaml
@@ -50,7 +50,7 @@
nvmem-cell-names:
const: calibration
- # See ./thermal.txt for details
+ # See Documentation/devicetree/bindings/thermal/thermal-sensor.yaml for details
"#thermal-sensor-cells":
enum:
- 0
diff --git a/Documentation/devicetree/bindings/thermal/amazon,al-thermal.txt b/Documentation/devicetree/bindings/thermal/amazon,al-thermal.txt
index 703979d..12fc4ef 100644
--- a/Documentation/devicetree/bindings/thermal/amazon,al-thermal.txt
+++ b/Documentation/devicetree/bindings/thermal/amazon,al-thermal.txt
@@ -6,7 +6,7 @@
Required properties:
- compatible: "amazon,al-thermal".
- reg: The physical base address and length of the sensor's registers.
-- #thermal-sensor-cells: Must be 1. See ./thermal.txt for a description.
+- #thermal-sensor-cells: Must be 1. See Documentation/devicetree/bindings/thermal/thermal-sensor.yaml for a description.
Example:
thermal: thermal {
diff --git a/Documentation/devicetree/bindings/thermal/brcm,avs-ro-thermal.yaml b/Documentation/devicetree/bindings/thermal/brcm,avs-ro-thermal.yaml
index f3e68ed..1ab5070 100644
--- a/Documentation/devicetree/bindings/thermal/brcm,avs-ro-thermal.yaml
+++ b/Documentation/devicetree/bindings/thermal/brcm,avs-ro-thermal.yaml
@@ -23,7 +23,7 @@
compatible:
const: brcm,bcm2711-thermal
- # See ./thermal.txt for details
+ # See Documentation/devicetree/bindings/thermal/thermal-sensor.yaml for details
"#thermal-sensor-cells":
const: 0
diff --git a/Documentation/devicetree/bindings/thermal/brcm,bcm2835-thermal.txt b/Documentation/devicetree/bindings/thermal/brcm,bcm2835-thermal.txt
index da8c5b7..a3e9ec5 100644
--- a/Documentation/devicetree/bindings/thermal/brcm,bcm2835-thermal.txt
+++ b/Documentation/devicetree/bindings/thermal/brcm,bcm2835-thermal.txt
@@ -7,7 +7,7 @@
"brcm,bcm2836-thermal" or "brcm,bcm2837-thermal"
reg: Address range of the thermal registers.
clocks: Phandle of the clock used by the thermal sensor.
-#thermal-sensor-cells: should be 0 (see thermal.txt)
+#thermal-sensor-cells: should be 0 (see Documentation/devicetree/bindings/thermal/thermal-sensor.yaml)
Example:
diff --git a/Documentation/devicetree/bindings/thermal/hisilicon-thermal.txt b/Documentation/devicetree/bindings/thermal/hisilicon-thermal.txt
index cef716a..4b19d80e 100644
--- a/Documentation/devicetree/bindings/thermal/hisilicon-thermal.txt
+++ b/Documentation/devicetree/bindings/thermal/hisilicon-thermal.txt
@@ -9,7 +9,7 @@
by /SOCTHERM/tsensor.
- clock-names: Input clock name, should be 'thermal_clk'.
- clocks: phandles for clock specified in "clock-names" property.
-- #thermal-sensor-cells: Should be 1. See ./thermal.txt for a description.
+- #thermal-sensor-cells: Should be 1. See Documentation/devicetree/bindings/thermal/thermal-sensor.yaml for a description.
Example :
diff --git a/Documentation/devicetree/bindings/thermal/max77620_thermal.txt b/Documentation/devicetree/bindings/thermal/max77620_thermal.txt
index 323a3b3..82ed5d4 100644
--- a/Documentation/devicetree/bindings/thermal/max77620_thermal.txt
+++ b/Documentation/devicetree/bindings/thermal/max77620_thermal.txt
@@ -8,12 +8,12 @@
Required properties:
-------------------
-#thermal-sensor-cells: Please refer <devicetree/bindings/thermal/thermal.txt>
- for more details.
+#thermal-sensor-cells: For more details, please refer to
+ <devicetree/bindings/thermal/thermal-sensor.yaml>
The value must be 0.
For more details, please refer generic thermal DT binding document
-<devicetree/bindings/thermal/thermal.txt>.
+<devicetree/bindings/thermal/thermal*.yaml>.
Please refer <devicetree/bindings/mfd/max77620.txt> for mfd DT binding
document for the MAX77620.
diff --git a/Documentation/devicetree/bindings/thermal/mediatek-thermal.txt b/Documentation/devicetree/bindings/thermal/mediatek-thermal.txt
index f8d7831..1e249c42 100644
--- a/Documentation/devicetree/bindings/thermal/mediatek-thermal.txt
+++ b/Documentation/devicetree/bindings/thermal/mediatek-thermal.txt
@@ -23,7 +23,7 @@
- resets: Reference to the reset controller controlling the thermal controller.
- mediatek,auxadc: A phandle to the AUXADC which the thermal controller uses
- mediatek,apmixedsys: A phandle to the APMIXEDSYS controller.
-- #thermal-sensor-cells : Should be 0. See ./thermal.txt for a description.
+- #thermal-sensor-cells : Should be 0. See Documentation/devicetree/bindings/thermal/thermal-sensor.yaml for a description.
Optional properties:
- nvmem-cells: A phandle to the calibration data provided by a nvmem device. If
diff --git a/Documentation/devicetree/bindings/thermal/nvidia,tegra124-soctherm.txt b/Documentation/devicetree/bindings/thermal/nvidia,tegra124-soctherm.txt
index f02f385..db880e7 100644
--- a/Documentation/devicetree/bindings/thermal/nvidia,tegra124-soctherm.txt
+++ b/Documentation/devicetree/bindings/thermal/nvidia,tegra124-soctherm.txt
@@ -28,9 +28,10 @@
See ../reset/reset.txt for details.
- reset-names : Must include the following entries:
- soctherm
-- #thermal-sensor-cells : Should be 1. See ./thermal.txt for a description
- of this property. See <dt-bindings/thermal/tegra124-soctherm.h> for a
- list of valid values when referring to thermal sensors.
+- #thermal-sensor-cells : Should be 1. For a description of this property, see
+ Documentation/devicetree/bindings/thermal/thermal-sensor.yaml.
+ See <dt-bindings/thermal/tegra124-soctherm.h> for a list of valid values
+ when referring to thermal sensors.
- throttle-cfgs: A sub-node which is a container of configuration for each
hardware throttle events. These events can be set as cooling devices.
* throttle events: Sub-nodes must be named as "light" or "heavy".
@@ -62,7 +63,8 @@
TEGRA_SOCTHERM_THROT_LEVEL_MED (75%),
TEGRA_SOCTHERM_THROT_LEVEL_HIGH (85%).
- #cooling-cells: Should be 1. This cooling device only support on/off state.
- See ./thermal.txt for a description of this property.
+ For a description of this property see:
+ Documentation/devicetree/bindings/thermal/thermal-cooling-devices.yaml
Optional properties: The following properties are T210 specific and
valid only for OCx throttle events.
diff --git a/Documentation/devicetree/bindings/thermal/nvidia,tegra186-bpmp-thermal.txt b/Documentation/devicetree/bindings/thermal/nvidia,tegra186-bpmp-thermal.txt
index e17c07b..fc87f6a 100644
--- a/Documentation/devicetree/bindings/thermal/nvidia,tegra186-bpmp-thermal.txt
+++ b/Documentation/devicetree/bindings/thermal/nvidia,tegra186-bpmp-thermal.txt
@@ -8,7 +8,7 @@
The BPMP thermal node must be located directly inside the main BPMP node. See
../firmware/nvidia,tegra186-bpmp.txt for details of the BPMP binding.
-This node represents a thermal sensor. See thermal.txt for details of the
+This node represents a thermal sensor. See Documentation/devicetree/bindings/thermal/thermal-sensor.yaml for details of the
core thermal binding.
Required properties:
diff --git a/Documentation/devicetree/bindings/thermal/qcom-spmi-temp-alarm.txt b/Documentation/devicetree/bindings/thermal/qcom-spmi-temp-alarm.txt
index 0273a92..2d5b2ad 100644
--- a/Documentation/devicetree/bindings/thermal/qcom-spmi-temp-alarm.txt
+++ b/Documentation/devicetree/bindings/thermal/qcom-spmi-temp-alarm.txt
@@ -8,7 +8,7 @@
- compatible: Should contain "qcom,spmi-temp-alarm".
- reg: Specifies the SPMI address.
- interrupts: PMIC temperature alarm interrupt.
-- #thermal-sensor-cells: Should be 0. See thermal.txt for a description.
+- #thermal-sensor-cells: Should be 0. See Documentation/devicetree/bindings/thermal/thermal-sensor.yaml for a description.
Optional properties:
- io-channels: Should contain IIO channel specifier for the ADC channel,
diff --git a/Documentation/devicetree/bindings/thermal/qcom-tsens.yaml b/Documentation/devicetree/bindings/thermal/qcom-tsens.yaml
index d7be931..95462e0 100644
--- a/Documentation/devicetree/bindings/thermal/qcom-tsens.yaml
+++ b/Documentation/devicetree/bindings/thermal/qcom-tsens.yaml
@@ -8,7 +8,7 @@
title: QCOM SoC Temperature Sensor (TSENS)
maintainers:
- - Amit Kucheria <amit.kucheria@linaro.org>
+ - Amit Kucheria <amitk@kernel.org>
description: |
QCOM SoCs have TSENS IP to allow temperature measurement. There are currently
@@ -23,6 +23,7 @@
items:
- enum:
- qcom,msm8916-tsens
+ - qcom,msm8939-tsens
- qcom,msm8974-tsens
- const: qcom,tsens-v0_1
@@ -40,6 +41,8 @@
- qcom,msm8998-tsens
- qcom,sc7180-tsens
- qcom,sdm845-tsens
+ - qcom,sm8150-tsens
+ - qcom,sm8250-tsens
- const: qcom,tsens-v2
reg:
diff --git a/Documentation/devicetree/bindings/thermal/qoriq-thermal.txt b/Documentation/devicetree/bindings/thermal/qoriq-thermal.txt
deleted file mode 100644
index 28f2cba..0000000
--- a/Documentation/devicetree/bindings/thermal/qoriq-thermal.txt
+++ /dev/null
@@ -1,71 +0,0 @@
-* Thermal Monitoring Unit (TMU) on Freescale QorIQ SoCs
-
-Required properties:
-- compatible : Must include "fsl,qoriq-tmu" or "fsl,imx8mq-tmu". The
- version of the device is determined by the TMU IP Block Revision
- Register (IPBRR0) at offset 0x0BF8.
- Table of correspondences between IPBRR0 values and example chips:
- Value Device
- ---------- -----
- 0x01900102 T1040
-- reg : Address range of TMU registers.
-- interrupts : Contains the interrupt for TMU.
-- fsl,tmu-range : The values to be programmed into TTRnCR, as specified by
- the SoC reference manual. The first cell is TTR0CR, the second is
- TTR1CR, etc.
-- fsl,tmu-calibration : A list of cell pairs containing temperature
- calibration data, as specified by the SoC reference manual.
- The first cell of each pair is the value to be written to TTCFGR,
- and the second is the value to be written to TSCFGR.
-- #thermal-sensor-cells : Must be 1. The sensor specifier is the monitoring
- site ID, and represents the "n" in TRITSRn and TRATSRn.
-
-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:
-
-tmu@f0000 {
- compatible = "fsl,qoriq-tmu";
- reg = <0xf0000 0x1000>;
- interrupts = <18 2 0 0>;
- fsl,tmu-range = <0x000a0000 0x00090026 0x0008004a 0x0001006a>;
- fsl,tmu-calibration = <0x00000000 0x00000025
- 0x00000001 0x00000028
- 0x00000002 0x0000002d
- 0x00000003 0x00000031
- 0x00000004 0x00000036
- 0x00000005 0x0000003a
- 0x00000006 0x00000040
- 0x00000007 0x00000044
- 0x00000008 0x0000004a
- 0x00000009 0x0000004f
- 0x0000000a 0x00000054
-
- 0x00010000 0x0000000d
- 0x00010001 0x00000013
- 0x00010002 0x00000019
- 0x00010003 0x0000001f
- 0x00010004 0x00000025
- 0x00010005 0x0000002d
- 0x00010006 0x00000033
- 0x00010007 0x00000043
- 0x00010008 0x0000004b
- 0x00010009 0x00000053
-
- 0x00020000 0x00000010
- 0x00020001 0x00000017
- 0x00020002 0x0000001f
- 0x00020003 0x00000029
- 0x00020004 0x00000031
- 0x00020005 0x0000003c
- 0x00020006 0x00000042
- 0x00020007 0x0000004d
- 0x00020008 0x00000056
-
- 0x00030000 0x00000012
- 0x00030001 0x0000001d>;
- #thermal-sensor-cells = <1>;
-};
diff --git a/Documentation/devicetree/bindings/thermal/qoriq-thermal.yaml b/Documentation/devicetree/bindings/thermal/qoriq-thermal.yaml
new file mode 100644
index 0000000..f09e872
--- /dev/null
+++ b/Documentation/devicetree/bindings/thermal/qoriq-thermal.yaml
@@ -0,0 +1,114 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/thermal/qoriq-thermal.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Thermal Monitoring Unit (TMU) on Freescale QorIQ SoCs
+
+maintainers:
+ - Anson Huang <Anson.Huang@nxp.com>
+
+properties:
+ compatible:
+ description: |
+ The version of the device is determined by the TMU IP Block Revision
+ Register (IPBRR0) at offset 0x0BF8.
+ Table of correspondences between IPBRR0 values and example chips:
+ Value Device
+ ---------- -----
+ 0x01900102 T1040
+ enum:
+ - fsl,qoriq-tmu
+ - fsl,imx8mq-tmu
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+ fsl,tmu-range:
+ $ref: '/schemas/types.yaml#/definitions/uint32-array'
+ description: |
+ The values to be programmed into TTRnCR, as specified by the SoC
+ reference manual. The first cell is TTR0CR, the second is TTR1CR, etc.
+ maxItems: 4
+
+ fsl,tmu-calibration:
+ $ref: '/schemas/types.yaml#/definitions/uint32-matrix'
+ description: |
+ A list of cell pairs containing temperature calibration data, as
+ specified by the SoC reference manual. The first cell of each pair
+ is the value to be written to TTCFGR, and the second is the value
+ to be written to TSCFGR.
+ items:
+ items:
+ - description: value for TTCFGR
+ - description: value for TSCFGR
+ minItems: 1
+ maxItems: 64
+
+ little-endian:
+ description: |
+ boolean, if present, the TMU registers are little endian. If absent,
+ the default is big endian.
+ type: boolean
+
+ clocks:
+ maxItems: 1
+
+ "#thermal-sensor-cells":
+ const: 1
+
+required:
+ - compatible
+ - reg
+ - interrupts
+ - fsl,tmu-range
+ - fsl,tmu-calibration
+ - '#thermal-sensor-cells'
+
+additionalProperties: false
+
+examples:
+ - |
+ tmu@f0000 {
+ compatible = "fsl,qoriq-tmu";
+ reg = <0xf0000 0x1000>;
+ interrupts = <18 2 0 0>;
+ fsl,tmu-range = <0x000a0000 0x00090026 0x0008004a 0x0001006a>;
+ fsl,tmu-calibration = <0x00000000 0x00000025>,
+ <0x00000001 0x00000028>,
+ <0x00000002 0x0000002d>,
+ <0x00000003 0x00000031>,
+ <0x00000004 0x00000036>,
+ <0x00000005 0x0000003a>,
+ <0x00000006 0x00000040>,
+ <0x00000007 0x00000044>,
+ <0x00000008 0x0000004a>,
+ <0x00000009 0x0000004f>,
+ <0x0000000a 0x00000054>,
+ <0x00010000 0x0000000d>,
+ <0x00010001 0x00000013>,
+ <0x00010002 0x00000019>,
+ <0x00010003 0x0000001f>,
+ <0x00010004 0x00000025>,
+ <0x00010005 0x0000002d>,
+ <0x00010006 0x00000033>,
+ <0x00010007 0x00000043>,
+ <0x00010008 0x0000004b>,
+ <0x00010009 0x00000053>,
+ <0x00020000 0x00000010>,
+ <0x00020001 0x00000017>,
+ <0x00020002 0x0000001f>,
+ <0x00020003 0x00000029>,
+ <0x00020004 0x00000031>,
+ <0x00020005 0x0000003c>,
+ <0x00020006 0x00000042>,
+ <0x00020007 0x0000004d>,
+ <0x00020008 0x00000056>,
+ <0x00030000 0x00000012>,
+ <0x00030001 0x0000001d>;
+ #thermal-sensor-cells = <1>;
+ };
diff --git a/Documentation/devicetree/bindings/thermal/rockchip-thermal.txt b/Documentation/devicetree/bindings/thermal/rockchip-thermal.txt
index c6aac9b..7f94669 100644
--- a/Documentation/devicetree/bindings/thermal/rockchip-thermal.txt
+++ b/Documentation/devicetree/bindings/thermal/rockchip-thermal.txt
@@ -24,7 +24,7 @@
- pinctrl-1 : The "default" pinctrl state, it will be set after reset the
TSADC controller.
- pinctrl-2 : The "sleep" pinctrl state, it will be in for suspend.
-- #thermal-sensor-cells : Should be 1. See ./thermal.txt for a description.
+- #thermal-sensor-cells : Should be 1. See Documentation/devicetree/bindings/thermal/thermal-sensor.yaml for a description.
Optional properties:
- rockchip,hw-tshut-temp : The hardware-controlled shutdown temperature value.
diff --git a/Documentation/devicetree/bindings/thermal/tango-thermal.txt b/Documentation/devicetree/bindings/thermal/tango-thermal.txt
index 212198d..2c918d7 100644
--- a/Documentation/devicetree/bindings/thermal/tango-thermal.txt
+++ b/Documentation/devicetree/bindings/thermal/tango-thermal.txt
@@ -4,7 +4,7 @@
(in the CPU, video decoder, and PCIe controller).
Required properties:
-- #thermal-sensor-cells: Should be 0 (see thermal.txt)
+- #thermal-sensor-cells: Should be 0 (see Documentation/devicetree/bindings/thermal/thermal-sensor.yaml)
- compatible: "sigma,smp8758-thermal"
- reg: Address range of the thermal registers
diff --git a/Documentation/devicetree/bindings/thermal/thermal-generic-adc.txt b/Documentation/devicetree/bindings/thermal/thermal-generic-adc.txt
index 691a09d..e136946 100644
--- a/Documentation/devicetree/bindings/thermal/thermal-generic-adc.txt
+++ b/Documentation/devicetree/bindings/thermal/thermal-generic-adc.txt
@@ -8,7 +8,7 @@
Required properties:
===================
- compatible: Must be "generic-adc-thermal".
-- #thermal-sensor-cells: Should be 1. See ./thermal.txt for a description
+- #thermal-sensor-cells: Should be 1. See Documentation/devicetree/bindings/thermal/thermal-sensor.yaml for a description
of this property.
Optional properties:
===================
diff --git a/Documentation/devicetree/bindings/thermal/thermal-sensor.yaml b/Documentation/devicetree/bindings/thermal/thermal-sensor.yaml
index fcd25a0..727d045 100644
--- a/Documentation/devicetree/bindings/thermal/thermal-sensor.yaml
+++ b/Documentation/devicetree/bindings/thermal/thermal-sensor.yaml
@@ -41,7 +41,7 @@
#include <dt-bindings/interrupt-controller/arm-gic.h>
// Example 1: SDM845 TSENS
- soc: soc@0 {
+ soc: soc {
#address-cells = <2>;
#size-cells = <2>;
diff --git a/Documentation/devicetree/bindings/thermal/thermal-zones.yaml b/Documentation/devicetree/bindings/thermal/thermal-zones.yaml
index b8515d3..3ec9cc8 100644
--- a/Documentation/devicetree/bindings/thermal/thermal-zones.yaml
+++ b/Documentation/devicetree/bindings/thermal/thermal-zones.yaml
@@ -224,7 +224,7 @@
#include <dt-bindings/thermal/thermal.h>
// Example 1: SDM845 TSENS
- soc: soc@0 {
+ soc {
#address-cells = <2>;
#size-cells = <2>;
diff --git a/Documentation/devicetree/bindings/thermal/thermal.txt b/Documentation/devicetree/bindings/thermal/thermal.txt
deleted file mode 100644
index f78bec1..0000000
--- a/Documentation/devicetree/bindings/thermal/thermal.txt
+++ /dev/null
@@ -1,586 +0,0 @@
-* Thermal Framework Device Tree descriptor
-
-This file describes a generic binding to provide a way of
-defining hardware thermal structure using device tree.
-A thermal structure includes thermal zones and their components,
-such as trip points, polling intervals, sensors and cooling devices
-binding descriptors.
-
-The target of device tree thermal descriptors is to describe only
-the hardware thermal aspects. The thermal device tree bindings are
-not about how the system must control or which algorithm or policy
-must be taken in place.
-
-There are five types of nodes involved to describe thermal bindings:
-- thermal sensors: devices which may be used to take temperature
- measurements.
-- cooling devices: devices which may be used to dissipate heat.
-- trip points: describe key temperatures at which cooling is recommended. The
- set of points should be chosen based on hardware limits.
-- cooling maps: used to describe links between trip points and cooling devices;
-- thermal zones: used to describe thermal data within the hardware;
-
-The following is a description of each of these node types.
-
-* Thermal sensor devices
-
-Thermal sensor devices are nodes providing temperature sensing capabilities on
-thermal zones. Typical devices are I2C ADC converters and bandgaps. These are
-nodes providing temperature data to thermal zones. Thermal sensor devices may
-control one or more internal sensors.
-
-Required property:
-- #thermal-sensor-cells: Used to provide sensor device specific information
- Type: unsigned while referring to it. Typically 0 on thermal sensor
- Size: one cell nodes with only one sensor, and at least 1 on nodes
- with several internal sensors, in order
- to identify uniquely the sensor instances within
- the IC. See thermal zone binding for more details
- on how consumers refer to sensor devices.
-
-* Cooling device nodes
-
-Cooling devices are nodes providing control on power dissipation. There
-are essentially two ways to provide control on power dissipation. First
-is by means of regulating device performance, which is known as passive
-cooling. A typical passive cooling is a CPU that has dynamic voltage and
-frequency scaling (DVFS), and uses lower frequencies as cooling states.
-Second is by means of activating devices in order to remove
-the dissipated heat, which is known as active cooling, e.g. regulating
-fan speeds. In both cases, cooling devices shall have a way to determine
-the state of cooling in which the device is.
-
-Any cooling device has a range of cooling states (i.e. different levels
-of heat dissipation). For example a fan's cooling states correspond to
-the different fan speeds possible. Cooling states are referred to by
-single unsigned integers, where larger numbers mean greater heat
-dissipation. The precise set of cooling states associated with a device
-should be defined in a particular device's binding.
-For more examples of cooling devices, refer to the example sections below.
-
-Required properties:
-- #cooling-cells: Used to provide cooling device specific information
- Type: unsigned while referring to it. Must be at least 2, in order
- Size: one cell to specify minimum and maximum cooling state used
- in the reference. The first cell is the minimum
- cooling state requested and the second cell is
- the maximum cooling state requested in the reference.
- See Cooling device maps section below for more details
- on how consumers refer to cooling devices.
-
-* Trip points
-
-The trip node is a node to describe a point in the temperature domain
-in which the system takes an action. This node describes just the point,
-not the action.
-
-Required properties:
-- temperature: An integer indicating the trip temperature level,
- Type: signed in millicelsius.
- Size: one cell
-
-- hysteresis: A low hysteresis value on temperature property (above).
- Type: unsigned This is a relative value, in millicelsius.
- Size: one cell
-
-- type: a string containing the trip type. Expected values are:
- "active": A trip point to enable active cooling
- "passive": A trip point to enable passive cooling
- "hot": A trip point to notify emergency
- "critical": Hardware not reliable.
- Type: string
-
-* Cooling device maps
-
-The cooling device maps node is a node to describe how cooling devices
-get assigned to trip points of the zone. The cooling devices are expected
-to be loaded in the target system.
-
-Required properties:
-- cooling-device: A list of phandles of cooling devices with their specifiers,
- Type: phandle + referring to which cooling devices are used in this
- cooling specifier binding. In the cooling specifier, the first cell
- is the minimum cooling state and the second cell
- is the maximum cooling state used in this map.
-- trip: A phandle of a trip point node within the same thermal
- Type: phandle of zone.
- trip point node
-
-Optional property:
-- contribution: The cooling contribution to the thermal zone of the
- Type: unsigned referred cooling device at the referred trip point.
- Size: one cell The contribution is a ratio of the sum
- of all cooling contributions within a thermal zone.
-
-Note: Using the THERMAL_NO_LIMIT (-1UL) constant in the cooling-device phandle
-limit specifier means:
-(i) - minimum state allowed for minimum cooling state used in the reference.
-(ii) - maximum state allowed for maximum cooling state used in the reference.
-Refer to include/dt-bindings/thermal/thermal.h for definition of this constant.
-
-* Thermal zone nodes
-
-The thermal zone node is the node containing all the required info
-for describing a thermal zone, including its cooling device bindings. The
-thermal zone node must contain, apart from its own properties, one sub-node
-containing trip nodes and one sub-node containing all the zone cooling maps.
-
-Required properties:
-- polling-delay: The maximum number of milliseconds to wait between polls
- Type: unsigned when checking this thermal zone.
- Size: one cell
-
-- polling-delay-passive: The maximum number of milliseconds to wait
- Type: unsigned between polls when performing passive cooling.
- Size: one cell
-
-- thermal-sensors: A list of thermal sensor phandles and sensor specifier
- Type: list of used while monitoring the thermal zone.
- phandles + sensor
- specifier
-
-- trips: A sub-node which is a container of only trip point nodes
- Type: sub-node required to describe the thermal zone.
-
-Optional property:
-- cooling-maps: A sub-node which is a container of only cooling device
- Type: sub-node map nodes, used to describe the relation between trips
- and cooling devices.
-
-- coefficients: An array of integers (one signed cell) containing
- Type: array coefficients to compose a linear relation between
- Elem size: one cell the sensors listed in the thermal-sensors property.
- Elem type: signed Coefficients defaults to 1, in case this property
- is not specified. A simple linear polynomial is used:
- Z = c0 * x0 + c1 * x1 + ... + c(n-1) * x(n-1) + cn.
-
- The coefficients are ordered and they match with sensors
- by means of sensor ID. Additional coefficients are
- interpreted as constant offset.
-
-- sustainable-power: An estimate of the sustainable power (in mW) that the
- Type: unsigned thermal zone can dissipate at the desired
- Size: one cell control temperature. For reference, the
- sustainable power of a 4'' phone is typically
- 2000mW, while on a 10'' tablet is around
- 4500mW.
-
-Note: The delay properties are bound to the maximum dT/dt (temperature
-derivative over time) in two situations for a thermal zone:
-(i) - when passive cooling is activated (polling-delay-passive); and
-(ii) - when the zone just needs to be monitored (polling-delay) or
-when active cooling is activated.
-
-The maximum dT/dt is highly bound to hardware power consumption and dissipation
-capability. The delays should be chosen to account for said max dT/dt,
-such that a device does not cross several trip boundaries unexpectedly
-between polls. Choosing the right polling delays shall avoid having the
-device in temperature ranges that may damage the silicon structures and
-reduce silicon lifetime.
-
-* The thermal-zones node
-
-The "thermal-zones" node is a container for all thermal zone nodes. It shall
-contain only sub-nodes describing thermal zones as in the section
-"Thermal zone nodes". The "thermal-zones" node appears under "/".
-
-* Examples
-
-Below are several examples on how to use thermal data descriptors
-using device tree bindings:
-
-(a) - CPU thermal zone
-
-The CPU thermal zone example below describes how to setup one thermal zone
-using one single sensor as temperature source and many cooling devices and
-power dissipation control sources.
-
-#include <dt-bindings/thermal/thermal.h>
-
-cpus {
- /*
- * Here is an example of describing a cooling device for a DVFS
- * capable CPU. The CPU node describes its four OPPs.
- * The cooling states possible are 0..3, and they are
- * used as OPP indexes. The minimum cooling state is 0, which means
- * all four OPPs can be available to the system. The maximum
- * cooling state is 3, which means only the lowest OPPs (198MHz@0.85V)
- * can be available in the system.
- */
- cpu0: cpu@0 {
- ...
- operating-points = <
- /* kHz uV */
- 970000 1200000
- 792000 1100000
- 396000 950000
- 198000 850000
- >;
- #cooling-cells = <2>; /* min followed by max */
- };
- ...
-};
-
-&i2c1 {
- ...
- /*
- * A simple fan controller which supports 10 speeds of operation
- * (represented as 0-9).
- */
- fan0: fan@48 {
- ...
- #cooling-cells = <2>; /* min followed by max */
- };
-};
-
-ocp {
- ...
- /*
- * A simple IC with a single bandgap temperature sensor.
- */
- bandgap0: bandgap@0000ed00 {
- ...
- #thermal-sensor-cells = <0>;
- };
-};
-
-thermal-zones {
- cpu_thermal: cpu-thermal {
- polling-delay-passive = <250>; /* milliseconds */
- polling-delay = <1000>; /* milliseconds */
-
- thermal-sensors = <&bandgap0>;
-
- trips {
- cpu_alert0: cpu-alert0 {
- temperature = <90000>; /* millicelsius */
- hysteresis = <2000>; /* millicelsius */
- type = "active";
- };
- cpu_alert1: cpu-alert1 {
- temperature = <100000>; /* millicelsius */
- hysteresis = <2000>; /* millicelsius */
- type = "passive";
- };
- cpu_crit: cpu-crit {
- temperature = <125000>; /* millicelsius */
- hysteresis = <2000>; /* millicelsius */
- type = "critical";
- };
- };
-
- cooling-maps {
- map0 {
- trip = <&cpu_alert0>;
- cooling-device = <&fan0 THERMAL_NO_LIMIT 4>;
- };
- map1 {
- trip = <&cpu_alert1>;
- cooling-device = <&fan0 5 THERMAL_NO_LIMIT>, <&cpu0 THERMAL_NO_LIMIT THERMAL_NO_LIMIT>;
- };
- };
- };
-};
-
-In the example above, the ADC sensor (bandgap0) at address 0x0000ED00 is
-used to monitor the zone 'cpu-thermal' using its sole sensor. A fan
-device (fan0) is controlled via I2C bus 1, at address 0x48, and has ten
-different cooling states 0-9. It is used to remove the heat out of
-the thermal zone 'cpu-thermal' using its cooling states
-from its minimum to 4, when it reaches trip point 'cpu_alert0'
-at 90C, as an example of active cooling. The same cooling device is used at
-'cpu_alert1', but from 5 to its maximum state. The cpu@0 device is also
-linked to the same thermal zone, 'cpu-thermal', as a passive cooling device,
-using all its cooling states at trip point 'cpu_alert1',
-which is a trip point at 100C. On the thermal zone 'cpu-thermal', at the
-temperature of 125C, represented by the trip point 'cpu_crit', the silicon
-is not reliable anymore.
-
-(b) - IC with several internal sensors
-
-The example below describes how to deploy several thermal zones based off a
-single sensor IC, assuming it has several internal sensors. This is a common
-case on SoC designs with several internal IPs that may need different thermal
-requirements, and thus may have their own sensor to monitor or detect internal
-hotspots in their silicon.
-
-#include <dt-bindings/thermal/thermal.h>
-
-ocp {
- ...
- /*
- * A simple IC with several bandgap temperature sensors.
- */
- bandgap0: bandgap@0000ed00 {
- ...
- #thermal-sensor-cells = <1>;
- };
-};
-
-thermal-zones {
- cpu_thermal: cpu-thermal {
- polling-delay-passive = <250>; /* milliseconds */
- polling-delay = <1000>; /* milliseconds */
-
- /* sensor ID */
- thermal-sensors = <&bandgap0 0>;
-
- trips {
- /* each zone within the SoC may have its own trips */
- cpu_alert: cpu-alert {
- temperature = <100000>; /* millicelsius */
- hysteresis = <2000>; /* millicelsius */
- type = "passive";
- };
- cpu_crit: cpu-crit {
- temperature = <125000>; /* millicelsius */
- hysteresis = <2000>; /* millicelsius */
- type = "critical";
- };
- };
-
- cooling-maps {
- /* each zone within the SoC may have its own cooling */
- ...
- };
- };
-
- gpu_thermal: gpu-thermal {
- polling-delay-passive = <120>; /* milliseconds */
- polling-delay = <1000>; /* milliseconds */
-
- /* sensor ID */
- thermal-sensors = <&bandgap0 1>;
-
- trips {
- /* each zone within the SoC may have its own trips */
- gpu_alert: gpu-alert {
- temperature = <90000>; /* millicelsius */
- hysteresis = <2000>; /* millicelsius */
- type = "passive";
- };
- gpu_crit: gpu-crit {
- temperature = <105000>; /* millicelsius */
- hysteresis = <2000>; /* millicelsius */
- type = "critical";
- };
- };
-
- cooling-maps {
- /* each zone within the SoC may have its own cooling */
- ...
- };
- };
-
- dsp_thermal: dsp-thermal {
- polling-delay-passive = <50>; /* milliseconds */
- polling-delay = <1000>; /* milliseconds */
-
- /* sensor ID */
- thermal-sensors = <&bandgap0 2>;
-
- trips {
- /* each zone within the SoC may have its own trips */
- dsp_alert: dsp-alert {
- temperature = <90000>; /* millicelsius */
- hysteresis = <2000>; /* millicelsius */
- type = "passive";
- };
- dsp_crit: gpu-crit {
- temperature = <135000>; /* millicelsius */
- hysteresis = <2000>; /* millicelsius */
- type = "critical";
- };
- };
-
- cooling-maps {
- /* each zone within the SoC may have its own cooling */
- ...
- };
- };
-};
-
-In the example above, there is one bandgap IC which has the capability to
-monitor three sensors. The hardware has been designed so that sensors are
-placed on different places in the DIE to monitor different temperature
-hotspots: one for CPU thermal zone, one for GPU thermal zone and the
-other to monitor a DSP thermal zone.
-
-Thus, there is a need to assign each sensor provided by the bandgap IC
-to different thermal zones. This is achieved by means of using the
-#thermal-sensor-cells property and using the first cell of the sensor
-specifier as sensor ID. In the example, then, <bandgap 0> is used to
-monitor CPU thermal zone, <bandgap 1> is used to monitor GPU thermal
-zone and <bandgap 2> is used to monitor DSP thermal zone. Each zone
-may be uncorrelated, having its own dT/dt requirements, trips
-and cooling maps.
-
-
-(c) - Several sensors within one single thermal zone
-
-The example below illustrates how to use more than one sensor within
-one thermal zone.
-
-#include <dt-bindings/thermal/thermal.h>
-
-&i2c1 {
- ...
- /*
- * A simple IC with a single temperature sensor.
- */
- adc: sensor@49 {
- ...
- #thermal-sensor-cells = <0>;
- };
-};
-
-ocp {
- ...
- /*
- * A simple IC with a single bandgap temperature sensor.
- */
- bandgap0: bandgap@0000ed00 {
- ...
- #thermal-sensor-cells = <0>;
- };
-};
-
-thermal-zones {
- cpu_thermal: cpu-thermal {
- polling-delay-passive = <250>; /* milliseconds */
- polling-delay = <1000>; /* milliseconds */
-
- thermal-sensors = <&bandgap0>, /* cpu */
- <&adc>; /* pcb north */
-
- /* hotspot = 100 * bandgap - 120 * adc + 484 */
- coefficients = <100 -120 484>;
-
- trips {
- ...
- };
-
- cooling-maps {
- ...
- };
- };
-};
-
-In some cases, there is a need to use more than one sensor to extrapolate
-a thermal hotspot in the silicon. The above example illustrates this situation.
-For instance, it may be the case that a sensor external to CPU IP may be placed
-close to CPU hotspot and together with internal CPU sensor, it is used
-to determine the hotspot. Assuming this is the case for the above example,
-the hypothetical extrapolation rule would be:
- hotspot = 100 * bandgap - 120 * adc + 484
-
-In other context, the same idea can be used to add fixed offset. For instance,
-consider the hotspot extrapolation rule below:
- hotspot = 1 * adc + 6000
-
-In the above equation, the hotspot is always 6C higher than what is read
-from the ADC sensor. The binding would be then:
- thermal-sensors = <&adc>;
-
- /* hotspot = 1 * adc + 6000 */
- coefficients = <1 6000>;
-
-(d) - Board thermal
-
-The board thermal example below illustrates how to setup one thermal zone
-with many sensors and many cooling devices.
-
-#include <dt-bindings/thermal/thermal.h>
-
-&i2c1 {
- ...
- /*
- * An IC with several temperature sensor.
- */
- adc_dummy: sensor@50 {
- ...
- #thermal-sensor-cells = <1>; /* sensor internal ID */
- };
-};
-
-thermal-zones {
- batt-thermal {
- polling-delay-passive = <500>; /* milliseconds */
- polling-delay = <2500>; /* milliseconds */
-
- /* sensor ID */
- thermal-sensors = <&adc_dummy 4>;
-
- trips {
- ...
- };
-
- cooling-maps {
- ...
- };
- };
-
- board_thermal: board-thermal {
- polling-delay-passive = <1000>; /* milliseconds */
- polling-delay = <2500>; /* milliseconds */
-
- /* sensor ID */
- thermal-sensors = <&adc_dummy 0>, /* pcb top edge */
- <&adc_dummy 1>, /* lcd */
- <&adc_dummy 2>; /* back cover */
- /*
- * An array of coefficients describing the sensor
- * linear relation. E.g.:
- * z = c1*x1 + c2*x2 + c3*x3
- */
- coefficients = <1200 -345 890>;
-
- sustainable-power = <2500>;
-
- trips {
- /* Trips are based on resulting linear equation */
- cpu_trip: cpu-trip {
- temperature = <60000>; /* millicelsius */
- hysteresis = <2000>; /* millicelsius */
- type = "passive";
- };
- gpu_trip: gpu-trip {
- temperature = <55000>; /* millicelsius */
- hysteresis = <2000>; /* millicelsius */
- type = "passive";
- }
- lcd_trip: lcp-trip {
- temperature = <53000>; /* millicelsius */
- hysteresis = <2000>; /* millicelsius */
- type = "passive";
- };
- crit_trip: crit-trip {
- temperature = <68000>; /* millicelsius */
- hysteresis = <2000>; /* millicelsius */
- type = "critical";
- };
- };
-
- cooling-maps {
- map0 {
- trip = <&cpu_trip>;
- cooling-device = <&cpu0 0 2>;
- contribution = <55>;
- };
- map1 {
- trip = <&gpu_trip>;
- cooling-device = <&gpu0 0 2>;
- contribution = <20>;
- };
- map2 {
- trip = <&lcd_trip>;
- cooling-device = <&lcd0 5 10>;
- contribution = <15>;
- };
- };
- };
-};
-
-The above example is a mix of previous examples, a sensor IP with several internal
-sensors used to monitor different zones, one of them is composed by several sensors and
-with different cooling devices.
diff --git a/Documentation/devicetree/bindings/thermal/ti,am654-thermal.yaml b/Documentation/devicetree/bindings/thermal/ti,am654-thermal.yaml
index 25b9209..ea14de8 100644
--- a/Documentation/devicetree/bindings/thermal/ti,am654-thermal.yaml
+++ b/Documentation/devicetree/bindings/thermal/ti,am654-thermal.yaml
@@ -35,7 +35,7 @@
#include <dt-bindings/soc/ti,sci_pm_domain.h>
vtm: thermal@42050000 {
compatible = "ti,am654-vtm";
- reg = <0x0 0x42050000 0x0 0x25c>;
+ reg = <0x42050000 0x25c>;
power-domains = <&k3_pds 80 TI_SCI_PD_EXCLUSIVE>;
#thermal-sensor-cells = <1>;
};
diff --git a/Documentation/devicetree/bindings/timer/csky,mptimer.txt b/Documentation/devicetree/bindings/timer/csky,mptimer.txt
index 15cfec0..f5c7e99 100644
--- a/Documentation/devicetree/bindings/timer/csky,mptimer.txt
+++ b/Documentation/devicetree/bindings/timer/csky,mptimer.txt
@@ -8,7 +8,7 @@
- PTIM_CTLR "cr<0, 14>" Control reg to start reset timer.
- PTIM_TSR "cr<1, 14>" Interrupt cleanup status reg.
- PTIM_CCVR "cr<3, 14>" Current counter value reg.
- - PTIM_LVR "cr<6, 14>" Window value reg to triger next event.
+ - PTIM_LVR "cr<6, 14>" Window value reg to trigger next event.
==============================
timer node bindings definition
diff --git a/Documentation/devicetree/bindings/timer/ingenic,sysost.yaml b/Documentation/devicetree/bindings/timer/ingenic,sysost.yaml
new file mode 100644
index 0000000..df3eb76
--- /dev/null
+++ b/Documentation/devicetree/bindings/timer/ingenic,sysost.yaml
@@ -0,0 +1,63 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/timer/ingenic,sysost.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Bindings for SYSOST in Ingenic XBurst family SoCs
+
+maintainers:
+ - 周琰杰 (Zhou Yanjie) <zhouyanjie@wanyeetech.com>
+
+description:
+ The SYSOST in an Ingenic SoC provides one 64bit timer for clocksource
+ and one or more 32bit timers for clockevent.
+
+properties:
+ "#clock-cells":
+ const: 1
+
+ compatible:
+ enum:
+ - ingenic,x1000-ost
+ - ingenic,x2000-ost
+
+ reg:
+ maxItems: 1
+
+ clocks:
+ maxItems: 1
+
+ clock-names:
+ const: ost
+
+ interrupts:
+ maxItems: 1
+
+required:
+ - "#clock-cells"
+ - compatible
+ - reg
+ - clocks
+ - clock-names
+ - interrupts
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/clock/x1000-cgu.h>
+
+ ost: timer@12000000 {
+ compatible = "ingenic,x1000-ost";
+ reg = <0x12000000 0x3c>;
+
+ #clock-cells = <1>;
+
+ clocks = <&cgu X1000_CLK_OST>;
+ clock-names = "ost";
+
+ interrupt-parent = <&cpuintc>;
+ interrupts = <3>;
+ };
+...
diff --git a/Documentation/devicetree/bindings/timer/ingenic,tcu.yaml b/Documentation/devicetree/bindings/timer/ingenic,tcu.yaml
index 03893e6..371fb02 100644
--- a/Documentation/devicetree/bindings/timer/ingenic,tcu.yaml
+++ b/Documentation/devicetree/bindings/timer/ingenic,tcu.yaml
@@ -116,7 +116,9 @@
- ingenic,jz4740-watchdog
- ingenic,jz4780-watchdog
- items:
- - const: ingenic,jz4770-watchdog
+ - enum:
+ - ingenic,jz4770-watchdog
+ - ingenic,jz4725b-watchdog
- const: ingenic,jz4740-watchdog
reg:
@@ -142,6 +144,7 @@
oneOf:
- enum:
- ingenic,jz4740-pwm
+ - ingenic,jz4725b-pwm
- items:
- enum:
- ingenic,jz4770-pwm
diff --git a/Documentation/devicetree/bindings/timer/mrvl,mmp-timer.txt b/Documentation/devicetree/bindings/timer/mrvl,mmp-timer.txt
deleted file mode 100644
index b8f02c6..0000000
--- a/Documentation/devicetree/bindings/timer/mrvl,mmp-timer.txt
+++ /dev/null
@@ -1,17 +0,0 @@
-* Marvell MMP Timer controller
-
-Required properties:
-- compatible : Should be "mrvl,mmp-timer".
-- reg : Address and length of the register set of timer controller.
-- interrupts : Should be the interrupt number.
-
-Optional properties:
-- clocks : Should contain a single entry describing the clock input.
-
-Example:
- timer0: timer@d4014000 {
- compatible = "mrvl,mmp-timer";
- reg = <0xd4014000 0x100>;
- interrupts = <13>;
- clocks = <&coreclk 2>;
- };
diff --git a/Documentation/devicetree/bindings/timer/mrvl,mmp-timer.yaml b/Documentation/devicetree/bindings/timer/mrvl,mmp-timer.yaml
new file mode 100644
index 0000000..1fbc260
--- /dev/null
+++ b/Documentation/devicetree/bindings/timer/mrvl,mmp-timer.yaml
@@ -0,0 +1,46 @@
+# SPDX-License-Identifier: GPL-2.0-only
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/timer/mrvl,mmp-timer.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Marvell MMP Timer bindings
+
+maintainers:
+ - Daniel Lezcano <daniel.lezcano@linaro.org>
+ - Thomas Gleixner <tglx@linutronix.de>
+ - Rob Herring <robh+dt@kernel.org>
+
+properties:
+ $nodename:
+ pattern: '^timer@[a-f0-9]+$'
+
+ compatible:
+ const: mrvl,mmp-timer
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+ clocks:
+ maxItems: 1
+
+required:
+ - compatible
+ - reg
+ - interrupts
+
+additionalProperties: false
+
+examples:
+ - |
+ timer@d4014000 {
+ compatible = "mrvl,mmp-timer";
+ reg = <0xd4014000 0x100>;
+ interrupts = <13>;
+ clocks = <&coreclk 2>;
+ };
+
+...
diff --git a/Documentation/devicetree/bindings/timer/ti,keystone-timer.txt b/Documentation/devicetree/bindings/timer/ti,keystone-timer.txt
index 5fbe361..d3905a5 100644
--- a/Documentation/devicetree/bindings/timer/ti,keystone-timer.txt
+++ b/Documentation/devicetree/bindings/timer/ti,keystone-timer.txt
@@ -10,7 +10,7 @@
when the counter reaches preset counter values.
Documentation:
-http://www.ti.com/lit/ug/sprugv5a/sprugv5a.pdf
+https://www.ti.com/lit/ug/sprugv5a/sprugv5a.pdf
Required properties:
diff --git a/Documentation/devicetree/bindings/trivial-devices.yaml b/Documentation/devicetree/bindings/trivial-devices.yaml
index 4165352..b7e94fe 100644
--- a/Documentation/devicetree/bindings/trivial-devices.yaml
+++ b/Documentation/devicetree/bindings/trivial-devices.yaml
@@ -80,8 +80,6 @@
- fsl,mpl3115
# MPR121: Proximity Capacitive Touch Sensor Controller
- fsl,mpr121
- # SGTL5000: Ultra Low-Power Audio Codec
- - fsl,sgtl5000
# G751: Digital Temperature Sensor and Thermal Watchdog with Two-Wire Interface
- gmt,g751
# Infineon IR38064 Voltage Regulator
diff --git a/Documentation/devicetree/bindings/usb/aspeed,usb-vhub.yaml b/Documentation/devicetree/bindings/usb/aspeed,usb-vhub.yaml
index e4e83d3..8b019ac 100644
--- a/Documentation/devicetree/bindings/usb/aspeed,usb-vhub.yaml
+++ b/Documentation/devicetree/bindings/usb/aspeed,usb-vhub.yaml
@@ -127,8 +127,8 @@
#address-cells = <1>;
#size-cells = <0>;
- string@0409 {
- reg = <0x0409>;
+ string@409 {
+ reg = <0x409>;
manufacturer = "ASPEED";
product = "USB Virtual Hub";
serial-number = "0000";
diff --git a/Documentation/devicetree/bindings/usb/brcm,bdc.txt b/Documentation/devicetree/bindings/usb/brcm,bdc.txt
index 63e63af..c9f52b9 100644
--- a/Documentation/devicetree/bindings/usb/brcm,bdc.txt
+++ b/Documentation/devicetree/bindings/usb/brcm,bdc.txt
@@ -4,7 +4,7 @@
Required properties:
- compatible: must be one of:
- "brcm,bdc-v0.16"
+ "brcm,bdc-udc-v2"
"brcm,bdc"
- reg: the base register address and length
- interrupts: the interrupt line for this controller
@@ -21,7 +21,7 @@
Example:
bdc@f0b02000 {
- compatible = "brcm,bdc-v0.16";
+ compatible = "brcm,bdc-udc-v2";
reg = <0xf0b02000 0xfc4>;
interrupts = <0x0 0x60 0x0>;
phys = <&usbphy_0 0x0>;
diff --git a/Documentation/devicetree/bindings/usb/dwc2.yaml b/Documentation/devicetree/bindings/usb/dwc2.yaml
index 9352a8e..4ff632d 100644
--- a/Documentation/devicetree/bindings/usb/dwc2.yaml
+++ b/Documentation/devicetree/bindings/usb/dwc2.yaml
@@ -44,7 +44,9 @@
- const: st,stm32f4x9-hsotg
- const: st,stm32f7-hsotg
- const: st,stm32mp15-fsotg
- - const: st,stm32mp15-hsotg
+ - items:
+ - const: st,stm32mp15-hsotg
+ - const: snps,dwc2
- const: samsung,s3c6400-hsotg
reg:
@@ -93,7 +95,7 @@
vusb_a-supply:
description: phandle to voltage regulator of analog section.
- vusb33d-supply:
+ usb33d-supply:
description: reference to the VBUS and ID sensing comparators supply, in
order to perform OTG operation, used on STM32MP15 SoCs.
diff --git a/Documentation/devicetree/bindings/usb/ingenic,jz4770-phy.yaml b/Documentation/devicetree/bindings/usb/ingenic,jz4770-phy.yaml
index a81b0b1..2d61166 100644
--- a/Documentation/devicetree/bindings/usb/ingenic,jz4770-phy.yaml
+++ b/Documentation/devicetree/bindings/usb/ingenic,jz4770-phy.yaml
@@ -4,10 +4,11 @@
$id: http://devicetree.org/schemas/usb/ingenic,jz4770-phy.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#
-title: Ingenic JZ4770 USB PHY devicetree bindings
+title: Ingenic SoCs USB PHY devicetree bindings
maintainers:
- Paul Cercueil <paul@crapouillou.net>
+ - 周琰杰 (Zhou Yanjie) <zhouyanjie@wanyeetech.com>
properties:
$nodename:
@@ -16,6 +17,9 @@
compatible:
enum:
- ingenic,jz4770-phy
+ - ingenic,jz4780-phy
+ - ingenic,x1000-phy
+ - ingenic,x1830-phy
reg:
maxItems: 1
diff --git a/Documentation/devicetree/bindings/usb/renesas,usb-xhci.yaml b/Documentation/devicetree/bindings/usb/renesas,usb-xhci.yaml
new file mode 100644
index 0000000..add9f7b
--- /dev/null
+++ b/Documentation/devicetree/bindings/usb/renesas,usb-xhci.yaml
@@ -0,0 +1,86 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/usb/renesas,usb-xhci.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Renesas USB xHCI controllers
+
+maintainers:
+ - Lad Prabhakar <prabhakar.mahadev-lad.rj@bp.renesas.com>
+ - Yoshihiro Shimoda <yoshihiro.shimoda.uh@renesas.com>
+
+allOf:
+ - $ref: "usb-hcd.yaml"
+
+properties:
+ compatible:
+ oneOf:
+ - items:
+ - enum:
+ - renesas,xhci-r8a7742 # RZ/G1H
+ - renesas,xhci-r8a7743 # RZ/G1M
+ - renesas,xhci-r8a7744 # RZ/G1N
+ - renesas,xhci-r8a7790 # R-Car H2
+ - renesas,xhci-r8a7791 # R-Car M2-W
+ - renesas,xhci-r8a7793 # R-Car M2-N
+ - const: renesas,rcar-gen2-xhci # R-Car Gen2 and RZ/G1
+ - items:
+ - enum:
+ - renesas,xhci-r8a774a1 # RZ/G2M
+ - renesas,xhci-r8a774b1 # RZ/G2N
+ - renesas,xhci-r8a774c0 # RZ/G2E
+ - renesas,xhci-r8a7795 # R-Car H3
+ - renesas,xhci-r8a7796 # R-Car M3-W
+ - renesas,xhci-r8a77961 # R-Car M3-W+
+ - renesas,xhci-r8a77965 # R-Car M3-N
+ - renesas,xhci-r8a77990 # R-Car E3
+ - const: renesas,rcar-gen3-xhci # R-Car Gen3 and RZ/G2
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+ clocks:
+ maxItems: 1
+
+ phys:
+ maxItems: 1
+
+ phy-names:
+ maxItems: 1
+ items:
+ - const: usb
+
+ power-domains:
+ maxItems: 1
+
+ resets:
+ maxItems: 1
+
+required:
+ - compatible
+ - reg
+ - interrupts
+ - clocks
+ - power-domains
+ - resets
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/clock/r8a7795-cpg-mssr.h>
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+ #include <dt-bindings/power/r8a7795-sysc.h>
+
+ xhci0: usb@ee000000 {
+ compatible = "renesas,xhci-r8a7795", "renesas,rcar-gen3-xhci";
+ reg = <0xee000000 0xc00>;
+ interrupts = <GIC_SPI 102 IRQ_TYPE_LEVEL_HIGH>;
+ clocks = <&cpg CPG_MOD 328>;
+ power-domains = <&sysc R8A7795_PD_ALWAYS_ON>;
+ resets = <&cpg 328>;
+ };
diff --git a/Documentation/devicetree/bindings/usb/ti,keystone-dwc3.yaml b/Documentation/devicetree/bindings/usb/ti,keystone-dwc3.yaml
index f127535..804b9b4 100644
--- a/Documentation/devicetree/bindings/usb/ti,keystone-dwc3.yaml
+++ b/Documentation/devicetree/bindings/usb/ti,keystone-dwc3.yaml
@@ -11,22 +11,36 @@
properties:
compatible:
- oneOf:
- - const: "ti,keystone-dwc3"
- - const: "ti,am654-dwc3"
+ items:
+ - enum:
+ - ti,keystone-dwc3
+ - ti,am654-dwc3
reg:
maxItems: 1
- description: Address and length of the register set for the USB subsystem on
- the SOC.
+
+ '#address-cells':
+ const: 1
+
+ '#size-cells':
+ const: 1
+
+ ranges: true
interrupts:
maxItems: 1
- description: The irq number of this device that is used to interrupt the MPU.
-
clocks:
- description: Clock ID for USB functional clock.
+ minItems: 1
+ maxItems: 2
+
+ assigned-clocks:
+ minItems: 1
+ maxItems: 2
+
+ assigned-clock-parents:
+ minItems: 1
+ maxItems: 2
power-domains:
description: Should contain a phandle to a PM domain provider node
@@ -42,33 +56,42 @@
phy-names:
items:
- - const: "usb3-phy"
+ - const: usb3-phy
- dwc3:
+ dma-coherent: true
+
+ dma-ranges: true
+
+patternProperties:
+ "usb@[a-f0-9]+$":
+ type: object
description: This is the node representing the DWC3 controller instance
Documentation/devicetree/bindings/usb/dwc3.txt
required:
- compatible
- reg
+ - "#address-cells"
+ - "#size-cells"
+ - ranges
- interrupts
- - clocks
+
+additionalProperties: false
examples:
- |
#include <dt-bindings/interrupt-controller/arm-gic.h>
- usb: usb@2680000 {
+ dwc3@2680000 {
compatible = "ti,keystone-dwc3";
#address-cells = <1>;
#size-cells = <1>;
reg = <0x2680000 0x10000>;
clocks = <&clkusb>;
- clock-names = "usb";
interrupts = <GIC_SPI 393 IRQ_TYPE_EDGE_RISING>;
ranges;
- dwc3@2690000 {
+ usb@2690000 {
compatible = "synopsys,dwc3";
reg = <0x2690000 0x70000>;
interrupts = <GIC_SPI 393 IRQ_TYPE_EDGE_RISING>;
diff --git a/Documentation/devicetree/bindings/usb/usb-xhci.txt b/Documentation/devicetree/bindings/usb/usb-xhci.txt
index b120dd6..0c5cff8 100644
--- a/Documentation/devicetree/bindings/usb/usb-xhci.txt
+++ b/Documentation/devicetree/bindings/usb/usb-xhci.txt
@@ -7,24 +7,6 @@
- "marvell,armada3700-xhci" for Armada 37xx SoCs
- "marvell,armada-375-xhci" for Armada 375 SoCs
- "marvell,armada-380-xhci" for Armada 38x SoCs
- - "renesas,xhci-r8a7742" for r8a7742 SoC
- - "renesas,xhci-r8a7743" for r8a7743 SoC
- - "renesas,xhci-r8a7744" for r8a7744 SoC
- - "renesas,xhci-r8a774a1" for r8a774a1 SoC
- - "renesas,xhci-r8a774b1" for r8a774b1 SoC
- - "renesas,xhci-r8a774c0" for r8a774c0 SoC
- - "renesas,xhci-r8a7790" for r8a7790 SoC
- - "renesas,xhci-r8a7791" for r8a7791 SoC
- - "renesas,xhci-r8a7793" for r8a7793 SoC
- - "renesas,xhci-r8a7795" for r8a7795 SoC
- - "renesas,xhci-r8a7796" for r8a77960 SoC
- - "renesas,xhci-r8a77961" for r8a77961 SoC
- - "renesas,xhci-r8a77965" for r8a77965 SoC
- - "renesas,xhci-r8a77990" for r8a77990 SoC
- - "renesas,rcar-gen2-xhci" for a generic R-Car Gen2 or RZ/G1 compatible
- device
- - "renesas,rcar-gen3-xhci" for a generic R-Car Gen3 or RZ/G2 compatible
- device
- "brcm,bcm7445-xhci" for Broadcom STB SoCs with XHCI
- "xhci-platform" (deprecated)
diff --git a/Documentation/devicetree/bindings/vendor-prefixes.yaml b/Documentation/devicetree/bindings/vendor-prefixes.yaml
index 9aeab66..f3d8478 100644
--- a/Documentation/devicetree/bindings/vendor-prefixes.yaml
+++ b/Documentation/devicetree/bindings/vendor-prefixes.yaml
@@ -20,13 +20,17 @@
"^(keypad|m25p|max8952|max8997|max8998|mpmc),.*": true
"^(pinctrl-single|#pinctrl-single|PowerPC),.*": true
"^(pl022|pxa-mmc|rcar_sound|rotary-encoder|s5m8767|sdhci),.*": true
- "^(simple-audio-card|simple-graph-card|st-plgpio|st-spics|ts),.*": true
+ "^(simple-audio-card|st-plgpio|st-spics|ts),.*": true
# Keep list in alphabetical order.
+ "^70mai,.*":
+ description: 70mai Co., Ltd.
"^abilis,.*":
description: Abilis Systems
"^abracon,.*":
description: Abracon Corporation
+ "^acer,.*":
+ description: Acer Inc.
"^acme,.*":
description: Acme Systems srl
"^actions,.*":
@@ -469,6 +473,8 @@
description: ILI Technology Corporation (ILITEK)
"^img,.*":
description: Imagination Technologies Ltd.
+ "^imi,.*":
+ description: Integrated Micro-Electronics Inc.
"^incircuit,.*":
description: In-Circuit GmbH
"^inet-tek,.*":
@@ -680,6 +686,8 @@
description: Microsemi Corporation
"^msi,.*":
description: Micro-Star International Co. Ltd.
+ "^mstar,.*":
+ description: MStar Semiconductor, Inc. (acquired by MediaTek Inc.)
"^mti,.*":
description: Imagination Technologies Ltd. (formerly MIPS Technologies Inc.)
"^multi-inno,.*":
@@ -984,6 +992,8 @@
description: Spreadtrum Communications Inc.
"^sst,.*":
description: Silicon Storage Technology, Inc.
+ "^sstar,.*":
+ description: Xiamen Xingchen(SigmaStar) Technology Co., Ltd. (formerly part of MStar Semiconductor, Inc.)
"^st,.*":
description: STMicroelectronics
"^starry,.*":
@@ -1032,6 +1042,8 @@
description: Three Five Corp
"^thine,.*":
description: THine Electronics, Inc.
+ "^thingyjp,.*":
+ description: thingy.jp
"^ti,.*":
description: Texas Instruments
"^tianma,.*":
@@ -1157,6 +1169,8 @@
description: Xiaomi Technology Co., Ltd.
"^xillybus,.*":
description: Xillybus Ltd.
+ "^xingbangda,.*":
+ description: Shenzhen Xingbangda Display Technology Co., Ltd
"^xinpeng,.*":
description: Shenzhen Xinpeng Technology Co., Ltd
"^xlnx,.*":
@@ -1167,6 +1181,8 @@
description: Shenzhen Xunlong Software CO.,Limited
"^xylon,.*":
description: Xylon
+ "^ylm,.*":
+ description: Shenzhen Yangliming Electronic Technology Co., Ltd.
"^yna,.*":
description: YSH & ATIL
"^yones-toptech,.*":
diff --git a/Documentation/devicetree/bindings/virtio/mmio.txt b/Documentation/devicetree/bindings/virtio/mmio.txt
index 21af30f..0a575f3 100644
--- a/Documentation/devicetree/bindings/virtio/mmio.txt
+++ b/Documentation/devicetree/bindings/virtio/mmio.txt
@@ -1,6 +1,6 @@
* virtio memory mapped device
-See http://ozlabs.org/~rusty/virtio-spec/ for more details.
+See https://ozlabs.org/~rusty/virtio-spec/ for more details.
Required properties:
diff --git a/Documentation/devicetree/bindings/watchdog/davinci-wdt.txt b/Documentation/devicetree/bindings/watchdog/davinci-wdt.txt
index e60b9a1..aa10b8e 100644
--- a/Documentation/devicetree/bindings/watchdog/davinci-wdt.txt
+++ b/Documentation/devicetree/bindings/watchdog/davinci-wdt.txt
@@ -11,8 +11,8 @@
See clock-bindings.txt
Documentation:
-Davinci DM646x - http://www.ti.com/lit/ug/spruer5b/spruer5b.pdf
-Keystone - http://www.ti.com/lit/ug/sprugv5a/sprugv5a.pdf
+Davinci DM646x - https://www.ti.com/lit/ug/spruer5b/spruer5b.pdf
+Keystone - https://www.ti.com/lit/ug/sprugv5a/sprugv5a.pdf
Examples:
diff --git a/Documentation/devicetree/bindings/watchdog/dw_wdt.txt b/Documentation/devicetree/bindings/watchdog/dw_wdt.txt
deleted file mode 100644
index eb09144..0000000
--- a/Documentation/devicetree/bindings/watchdog/dw_wdt.txt
+++ /dev/null
@@ -1,24 +0,0 @@
-Synopsys Designware Watchdog Timer
-
-Required Properties:
-
-- compatible : Should contain "snps,dw-wdt"
-- reg : Base address and size of the watchdog timer registers.
-- clocks : phandle + clock-specifier for the clock that drives the
- watchdog timer.
-
-Optional Properties:
-
-- interrupts : The interrupt used for the watchdog timeout warning.
-- resets : phandle pointing to the system reset controller with
- line index for the watchdog.
-
-Example:
-
- watchdog0: wd@ffd02000 {
- compatible = "snps,dw-wdt";
- reg = <0xffd02000 0x1000>;
- interrupts = <0 171 4>;
- clocks = <&per_base_clk>;
- resets = <&rst WDT0_RESET>;
- };
diff --git a/Documentation/devicetree/bindings/watchdog/qcom-wdt.txt b/Documentation/devicetree/bindings/watchdog/qcom-wdt.txt
deleted file mode 100644
index 41aeaa2f..0000000
--- a/Documentation/devicetree/bindings/watchdog/qcom-wdt.txt
+++ /dev/null
@@ -1,28 +0,0 @@
-Qualcomm Krait Processor Sub-system (KPSS) Watchdog
----------------------------------------------------
-
-Required properties :
-- compatible : shall contain only one of the following:
-
- "qcom,kpss-wdt-msm8960"
- "qcom,kpss-wdt-apq8064"
- "qcom,kpss-wdt-ipq8064"
- "qcom,kpss-wdt-ipq4019"
- "qcom,kpss-timer"
- "qcom,scss-timer"
- "qcom,kpss-wdt"
-
-- reg : shall contain base register location and length
-- clocks : shall contain the input clock
-
-Optional properties :
-- timeout-sec : shall contain the default watchdog timeout in seconds,
- if unset, the default timeout is 30 seconds
-
-Example:
- watchdog@208a038 {
- compatible = "qcom,kpss-wdt-ipq8064";
- reg = <0x0208a038 0x40>;
- clocks = <&sleep_clk>;
- timeout-sec = <10>;
- };
diff --git a/Documentation/devicetree/bindings/watchdog/qcom-wdt.yaml b/Documentation/devicetree/bindings/watchdog/qcom-wdt.yaml
new file mode 100644
index 0000000..0709ddf
--- /dev/null
+++ b/Documentation/devicetree/bindings/watchdog/qcom-wdt.yaml
@@ -0,0 +1,48 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/watchdog/qcom-wdt.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Qualcomm Krait Processor Sub-system (KPSS) Watchdog timer
+
+maintainers:
+ - Sai Prakash Ranjan <saiprakash.ranjan@codeaurora.org>
+
+allOf:
+ - $ref: watchdog.yaml#
+
+properties:
+ compatible:
+ enum:
+ - qcom,apss-wdt-qcs404
+ - qcom,apss-wdt-sc7180
+ - qcom,apss-wdt-sdm845
+ - qcom,apss-wdt-sm8150
+ - qcom,kpss-timer
+ - qcom,kpss-wdt
+ - qcom,kpss-wdt-apq8064
+ - qcom,kpss-wdt-ipq4019
+ - qcom,kpss-wdt-ipq8064
+ - qcom,kpss-wdt-msm8960
+ - qcom,scss-timer
+
+ reg:
+ maxItems: 1
+
+ clocks:
+ maxItems: 1
+
+required:
+ - compatible
+ - reg
+ - clocks
+
+examples:
+ - |
+ watchdog@208a038 {
+ compatible = "qcom,kpss-wdt-ipq8064";
+ reg = <0x0208a038 0x40>;
+ clocks = <&sleep_clk>;
+ timeout-sec = <10>;
+ };
diff --git a/Documentation/devicetree/bindings/watchdog/renesas,wdt.yaml b/Documentation/devicetree/bindings/watchdog/renesas,wdt.yaml
index 572f4c9..6933005 100644
--- a/Documentation/devicetree/bindings/watchdog/renesas,wdt.yaml
+++ b/Documentation/devicetree/bindings/watchdog/renesas,wdt.yaml
@@ -41,6 +41,7 @@
- renesas,r8a774a1-wdt # RZ/G2M
- renesas,r8a774b1-wdt # RZ/G2N
- renesas,r8a774c0-wdt # RZ/G2E
+ - renesas,r8a774e1-wdt # RZ/G2H
- renesas,r8a7795-wdt # R-Car H3
- renesas,r8a7796-wdt # R-Car M3-W
- renesas,r8a77961-wdt # R-Car M3-W+
diff --git a/Documentation/devicetree/bindings/watchdog/snps,dw-wdt.yaml b/Documentation/devicetree/bindings/watchdog/snps,dw-wdt.yaml
new file mode 100644
index 0000000..d9fc7bb
--- /dev/null
+++ b/Documentation/devicetree/bindings/watchdog/snps,dw-wdt.yaml
@@ -0,0 +1,90 @@
+# SPDX-License-Identifier: GPL-2.0-only
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/watchdog/snps,dw-wdt.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Synopsys Designware Watchdog Timer
+
+allOf:
+ - $ref: "watchdog.yaml#"
+
+maintainers:
+ - Jamie Iles <jamie@jamieiles.com>
+
+properties:
+ compatible:
+ const: snps,dw-wdt
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ description: DW Watchdog pre-timeout interrupt
+ maxItems: 1
+
+ clocks:
+ minItems: 1
+ items:
+ - description: Watchdog timer reference clock
+ - description: APB3 interface clock
+
+ clock-names:
+ minItems: 1
+ items:
+ - const: tclk
+ - const: pclk
+
+ resets:
+ description: Phandle to the DW Watchdog reset lane
+ maxItems: 1
+
+ snps,watchdog-tops:
+ $ref: /schemas/types.yaml#/definitions/uint32-array
+ description: |
+ DW APB Watchdog custom timer intervals - Timeout Period ranges (TOPs).
+ Each TOP is a number loaded into the watchdog counter at the moment of
+ the timer restart. The counter decrementing happens each tick of the
+ reference clock. Therefore the TOPs array is equivalent to an array of
+ the timer expiration intervals supported by the DW APB Watchdog. Note
+ DW APB Watchdog IP-core might be synthesized with fixed TOP values,
+ in which case this property is unnecessary with default TOPs utilized.
+ default: [0x0001000 0x0002000 0x0004000 0x0008000
+ 0x0010000 0x0020000 0x0040000 0x0080000
+ 0x0100000 0x0200000 0x0400000 0x0800000
+ 0x1000000 0x2000000 0x4000000 0x8000000]
+ minItems: 16
+ maxItems: 16
+
+unevaluatedProperties: false
+
+required:
+ - compatible
+ - reg
+ - clocks
+
+examples:
+ - |
+ watchdog@ffd02000 {
+ compatible = "snps,dw-wdt";
+ reg = <0xffd02000 0x1000>;
+ interrupts = <0 171 4>;
+ clocks = <&per_base_clk>;
+ resets = <&wdt_rst>;
+ };
+
+ - |
+ watchdog@ffd02000 {
+ compatible = "snps,dw-wdt";
+ reg = <0xffd02000 0x1000>;
+ interrupts = <0 171 4>;
+ clocks = <&per_base_clk>;
+ clock-names = "tclk";
+ snps,watchdog-tops = <0x000000FF 0x000001FF 0x000003FF
+ 0x000007FF 0x0000FFFF 0x0001FFFF
+ 0x0003FFFF 0x0007FFFF 0x000FFFFF
+ 0x001FFFFF 0x003FFFFF 0x007FFFFF
+ 0x00FFFFFF 0x01FFFFFF 0x03FFFFFF
+ 0x07FFFFFF>;
+ };
+...
diff --git a/Documentation/devicetree/booting-without-of.rst b/Documentation/devicetree/booting-without-of.rst
new file mode 100644
index 0000000..e943335
--- /dev/null
+++ b/Documentation/devicetree/booting-without-of.rst
@@ -0,0 +1,1585 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+==================================================
+Booting the Linux/ppc kernel without Open Firmware
+==================================================
+
+Copyright (c) 2005 Benjamin Herrenschmidt <benh at kernel.crashing.org>,
+IBM Corp.
+
+Copyright (c) 2005 Becky Bruce <becky.bruce at freescale.com>,
+Freescale Semiconductor, FSL SOC and 32-bit additions
+
+Copyright (c) 2006 MontaVista Software, Inc.
+Flash chip node definition
+
+.. Table of Contents
+
+ I - Introduction
+ 1) Entry point for arch/arm
+ 2) Entry point for arch/powerpc
+ 3) Entry point for arch/x86
+ 4) Entry point for arch/mips/bmips
+ 5) Entry point for arch/sh
+
+ II - The DT block format
+ 1) Header
+ 2) Device tree generalities
+ 3) Device tree "structure" block
+ 4) Device tree "strings" block
+
+ III - Required content of the device tree
+ 1) Note about cells and address representation
+ 2) Note about "compatible" properties
+ 3) Note about "name" properties
+ 4) Note about node and property names and character set
+ 5) Required nodes and properties
+ a) The root node
+ b) The /cpus node
+ c) The /cpus/* nodes
+ d) the /memory node(s)
+ e) The /chosen node
+ f) the /soc<SOCname> node
+
+ IV - "dtc", the device tree compiler
+
+ V - Recommendations for a bootloader
+
+ VI - System-on-a-chip devices and nodes
+ 1) Defining child nodes of an SOC
+ 2) Representing devices without a current OF specification
+
+ VII - Specifying interrupt information for devices
+ 1) interrupts property
+ 2) interrupt-parent property
+ 3) OpenPIC Interrupt Controllers
+ 4) ISA Interrupt Controllers
+
+ VIII - Specifying device power management information (sleep property)
+
+ IX - Specifying dma bus information
+
+ Appendix A - Sample SOC node for MPC8540
+
+
+Revision Information
+====================
+
+ May 18, 2005: Rev 0.1
+ - Initial draft, no chapter III yet.
+
+ May 19, 2005: Rev 0.2
+ - Add chapter III and bits & pieces here or
+ clarifies the fact that a lot of things are
+ optional, the kernel only requires a very
+ small device tree, though it is encouraged
+ to provide an as complete one as possible.
+
+ May 24, 2005: Rev 0.3
+ - Precise that DT block has to be in RAM
+ - Misc fixes
+ - Define version 3 and new format version 16
+ for the DT block (version 16 needs kernel
+ patches, will be fwd separately).
+ String block now has a size, and full path
+ is replaced by unit name for more
+ compactness.
+ linux,phandle is made optional, only nodes
+ that are referenced by other nodes need it.
+ "name" property is now automatically
+ deduced from the unit name
+
+ June 1, 2005: Rev 0.4
+ - Correct confusion between OF_DT_END and
+ OF_DT_END_NODE in structure definition.
+ - Change version 16 format to always align
+ property data to 4 bytes. Since tokens are
+ already aligned, that means no specific
+ required alignment between property size
+ and property data. The old style variable
+ alignment would make it impossible to do
+ "simple" insertion of properties using
+ memmove (thanks Milton for
+ noticing). Updated kernel patch as well
+ - Correct a few more alignment constraints
+ - Add a chapter about the device-tree
+ compiler and the textural representation of
+ the tree that can be "compiled" by dtc.
+
+ November 21, 2005: Rev 0.5
+ - Additions/generalizations for 32-bit
+ - Changed to reflect the new arch/powerpc
+ structure
+ - Added chapter VI
+
+
+ ToDo:
+ - Add some definitions of interrupt tree (simple/complex)
+ - Add some definitions for PCI host bridges
+ - Add some common address format examples
+ - Add definitions for standard properties and "compatible"
+ names for cells that are not already defined by the existing
+ OF spec.
+ - Compare FSL SOC use of PCI to standard and make sure no new
+ node definition required.
+ - Add more information about node definitions for SOC devices
+ that currently have no standard, like the FSL CPM.
+
+
+I - Introduction
+================
+
+During the development of the Linux/ppc64 kernel, and more
+specifically, the addition of new platform types outside of the old
+IBM pSeries/iSeries pair, it was decided to enforce some strict rules
+regarding the kernel entry and bootloader <-> kernel interfaces, in
+order to avoid the degeneration that had become the ppc32 kernel entry
+point and the way a new platform should be added to the kernel. The
+legacy iSeries platform breaks those rules as it predates this scheme,
+but no new board support will be accepted in the main tree that
+doesn't follow them properly. In addition, since the advent of the
+arch/powerpc merged architecture for ppc32 and ppc64, new 32-bit
+platforms and 32-bit platforms which move into arch/powerpc will be
+required to use these rules as well.
+
+The main requirement that will be defined in more detail below is
+the presence of a device-tree whose format is defined after Open
+Firmware specification. However, in order to make life easier
+to embedded board vendors, the kernel doesn't require the device-tree
+to represent every device in the system and only requires some nodes
+and properties to be present. This will be described in detail in
+section III, but, for example, the kernel does not require you to
+create a node for every PCI device in the system. It is a requirement
+to have a node for PCI host bridges in order to provide interrupt
+routing information and memory/IO ranges, among others. It is also
+recommended to define nodes for on chip devices and other buses that
+don't specifically fit in an existing OF specification. This creates a
+great flexibility in the way the kernel can then probe those and match
+drivers to device, without having to hard code all sorts of tables. It
+also makes it more flexible for board vendors to do minor hardware
+upgrades without significantly impacting the kernel code or cluttering
+it with special cases.
+
+
+1) Entry point for arch/arm
+---------------------------
+
+ There is one single entry point to the kernel, at the start
+ of the kernel image. That entry point supports two calling
+ conventions. A summary of the interface is described here. A full
+ description of the boot requirements is documented in
+ Documentation/arm/booting.rst
+
+ a) ATAGS interface. Minimal information is passed from firmware
+ to the kernel with a tagged list of predefined parameters.
+
+ r0 : 0
+
+ r1 : Machine type number
+
+ r2 : Physical address of tagged list in system RAM
+
+ b) Entry with a flattened device-tree block. Firmware loads the
+ physical address of the flattened device tree block (dtb) into r2,
+ r1 is not used, but it is considered good practice to use a valid
+ machine number as described in Documentation/arm/booting.rst.
+
+ r0 : 0
+
+ r1 : Valid machine type number. When using a device tree,
+ a single machine type number will often be assigned to
+ represent a class or family of SoCs.
+
+ r2 : physical pointer to the device-tree block
+ (defined in chapter II) in RAM. Device tree can be located
+ anywhere in system RAM, but it should be aligned on a 64 bit
+ boundary.
+
+ The kernel will differentiate between ATAGS and device tree booting by
+ reading the memory pointed to by r2 and looking for either the flattened
+ device tree block magic value (0xd00dfeed) or the ATAG_CORE value at
+ offset 0x4 from r2 (0x54410001).
+
+2) Entry point for arch/powerpc
+-------------------------------
+
+ There is one single entry point to the kernel, at the start
+ of the kernel image. That entry point supports two calling
+ conventions:
+
+ a) Boot from Open Firmware. If your firmware is compatible
+ with Open Firmware (IEEE 1275) or provides an OF compatible
+ client interface API (support for "interpret" callback of
+ forth words isn't required), you can enter the kernel with:
+
+ r5 : OF callback pointer as defined by IEEE 1275
+ bindings to powerpc. Only the 32-bit client interface
+ is currently supported
+
+ r3, r4 : address & length of an initrd if any or 0
+
+ The MMU is either on or off; the kernel will run the
+ trampoline located in arch/powerpc/kernel/prom_init.c to
+ extract the device-tree and other information from open
+ firmware and build a flattened device-tree as described
+ in b). prom_init() will then re-enter the kernel using
+ the second method. This trampoline code runs in the
+ context of the firmware, which is supposed to handle all
+ exceptions during that time.
+
+ b) Direct entry with a flattened device-tree block. This entry
+ point is called by a) after the OF trampoline and can also be
+ called directly by a bootloader that does not support the Open
+ Firmware client interface. It is also used by "kexec" to
+ implement "hot" booting of a new kernel from a previous
+ running one. This method is what I will describe in more
+ details in this document, as method a) is simply standard Open
+ Firmware, and thus should be implemented according to the
+ various standard documents defining it and its binding to the
+ PowerPC platform. The entry point definition then becomes:
+
+ r3 : physical pointer to the device-tree block
+ (defined in chapter II) in RAM
+
+ r4 : physical pointer to the kernel itself. This is
+ used by the assembly code to properly disable the MMU
+ in case you are entering the kernel with MMU enabled
+ and a non-1:1 mapping.
+
+ r5 : NULL (as to differentiate with method a)
+
+ Note about SMP entry: Either your firmware puts your other
+ CPUs in some sleep loop or spin loop in ROM where you can get
+ them out via a soft reset or some other means, in which case
+ you don't need to care, or you'll have to enter the kernel
+ with all CPUs. The way to do that with method b) will be
+ described in a later revision of this document.
+
+ Board supports (platforms) are not exclusive config options. An
+ arbitrary set of board supports can be built in a single kernel
+ image. The kernel will "know" what set of functions to use for a
+ given platform based on the content of the device-tree. Thus, you
+ should:
+
+ a) add your platform support as a _boolean_ option in
+ arch/powerpc/Kconfig, following the example of PPC_PSERIES,
+ PPC_PMAC and PPC_MAPLE. The later is probably a good
+ example of a board support to start from.
+
+ b) create your main platform file as
+ "arch/powerpc/platforms/myplatform/myboard_setup.c" and add it
+ to the Makefile under the condition of your ``CONFIG_``
+ option. This file will define a structure of type "ppc_md"
+ containing the various callbacks that the generic code will
+ use to get to your platform specific code
+
+ A kernel image may support multiple platforms, but only if the
+ platforms feature the same core architecture. A single kernel build
+ cannot support both configurations with Book E and configurations
+ with classic Powerpc architectures.
+
+3) Entry point for arch/x86
+---------------------------
+
+ There is one single 32bit entry point to the kernel at code32_start,
+ the decompressor (the real mode entry point goes to the same 32bit
+ entry point once it switched into protected mode). That entry point
+ supports one calling convention which is documented in
+ Documentation/x86/boot.rst
+ The physical pointer to the device-tree block (defined in chapter II)
+ is passed via setup_data which requires at least boot protocol 2.09.
+ The type filed is defined as::
+
+ #define SETUP_DTB 2
+
+ This device-tree is used as an extension to the "boot page". As such it
+ does not parse / consider data which is already covered by the boot
+ page. This includes memory size, reserved ranges, command line arguments
+ or initrd address. It simply holds information which can not be retrieved
+ otherwise like interrupt routing or a list of devices behind an I2C bus.
+
+4) Entry point for arch/mips/bmips
+----------------------------------
+
+ Some bootloaders only support a single entry point, at the start of the
+ kernel image. Other bootloaders will jump to the ELF start address.
+ Both schemes are supported; CONFIG_BOOT_RAW=y and CONFIG_NO_EXCEPT_FILL=y,
+ so the first instruction immediately jumps to kernel_entry().
+
+ Similar to the arch/arm case (b), a DT-aware bootloader is expected to
+ set up the following registers:
+
+ a0 : 0
+
+ a1 : 0xffffffff
+
+ a2 : Physical pointer to the device tree block (defined in chapter
+ II) in RAM. The device tree can be located anywhere in the first
+ 512MB of the physical address space (0x00000000 - 0x1fffffff),
+ aligned on a 64 bit boundary.
+
+ Legacy bootloaders do not use this convention, and they do not pass in a
+ DT block. In this case, Linux will look for a builtin DTB, selected via
+ CONFIG_DT_*.
+
+ This convention is defined for 32-bit systems only, as there are not
+ currently any 64-bit BMIPS implementations.
+
+5) Entry point for arch/sh
+--------------------------
+
+ Device-tree-compatible SH bootloaders are expected to provide the physical
+ address of the device tree blob in r4. Since legacy bootloaders did not
+ guarantee any particular initial register state, kernels built to
+ inter-operate with old bootloaders must either use a builtin DTB or
+ select a legacy board option (something other than CONFIG_SH_DEVICE_TREE)
+ that does not use device tree. Support for the latter is being phased out
+ in favor of device tree.
+
+
+II - The DT block format
+========================
+
+
+This chapter defines the actual format of the flattened device-tree
+passed to the kernel. The actual content of it and kernel requirements
+are described later. You can find example of code manipulating that
+format in various places, including arch/powerpc/kernel/prom_init.c
+which will generate a flattened device-tree from the Open Firmware
+representation, or the fs2dt utility which is part of the kexec tools
+which will generate one from a filesystem representation. It is
+expected that a bootloader like uboot provides a bit more support,
+that will be discussed later as well.
+
+Note: The block has to be in main memory. It has to be accessible in
+both real mode and virtual mode with no mapping other than main
+memory. If you are writing a simple flash bootloader, it should copy
+the block to RAM before passing it to the kernel.
+
+
+1) Header
+---------
+
+ The kernel is passed the physical address pointing to an area of memory
+ that is roughly described in include/linux/of_fdt.h by the structure
+ boot_param_header:::
+
+ struct boot_param_header {
+ u32 magic; /* magic word OF_DT_HEADER */
+ u32 totalsize; /* total size of DT block */
+ u32 off_dt_struct; /* offset to structure */
+ u32 off_dt_strings; /* offset to strings */
+ u32 off_mem_rsvmap; /* offset to memory reserve map
+ */
+ u32 version; /* format version */
+ u32 last_comp_version; /* last compatible version */
+
+ /* version 2 fields below */
+ u32 boot_cpuid_phys; /* Which physical CPU id we're
+ booting on */
+ /* version 3 fields below */
+ u32 size_dt_strings; /* size of the strings block */
+
+ /* version 17 fields below */
+ u32 size_dt_struct; /* size of the DT structure block */
+ };
+
+ Along with the constants::
+
+ /* Definitions used by the flattened device tree */
+ #define OF_DT_HEADER 0xd00dfeed /* 4: version,
+ 4: total size */
+ #define OF_DT_BEGIN_NODE 0x1 /* Start node: full name
+ */
+ #define OF_DT_END_NODE 0x2 /* End node */
+ #define OF_DT_PROP 0x3 /* Property: name off,
+ size, content */
+ #define OF_DT_END 0x9
+
+ All values in this header are in big endian format, the various
+ fields in this header are defined more precisely below. All
+ "offset" values are in bytes from the start of the header; that is
+ from the physical base address of the device tree block.
+
+ - magic
+
+ This is a magic value that "marks" the beginning of the
+ device-tree block header. It contains the value 0xd00dfeed and is
+ defined by the constant OF_DT_HEADER
+
+ - totalsize
+
+ This is the total size of the DT block including the header. The
+ "DT" block should enclose all data structures defined in this
+ chapter (who are pointed to by offsets in this header). That is,
+ the device-tree structure, strings, and the memory reserve map.
+
+ - off_dt_struct
+
+ This is an offset from the beginning of the header to the start
+ of the "structure" part the device tree. (see 2) device tree)
+
+ - off_dt_strings
+
+ This is an offset from the beginning of the header to the start
+ of the "strings" part of the device-tree
+
+ - off_mem_rsvmap
+
+ This is an offset from the beginning of the header to the start
+ of the reserved memory map. This map is a list of pairs of 64-
+ bit integers. Each pair is a physical address and a size. The
+ list is terminated by an entry of size 0. This map provides the
+ kernel with a list of physical memory areas that are "reserved"
+ and thus not to be used for memory allocations, especially during
+ early initialization. The kernel needs to allocate memory during
+ boot for things like un-flattening the device-tree, allocating an
+ MMU hash table, etc... Those allocations must be done in such a
+ way to avoid overriding critical things like, on Open Firmware
+ capable machines, the RTAS instance, or on some pSeries, the TCE
+ tables used for the iommu. Typically, the reserve map should
+ contain **at least** this DT block itself (header,total_size). If
+ you are passing an initrd to the kernel, you should reserve it as
+ well. You do not need to reserve the kernel image itself. The map
+ should be 64-bit aligned.
+
+ - version
+
+ This is the version of this structure. Version 1 stops
+ here. Version 2 adds an additional field boot_cpuid_phys.
+ Version 3 adds the size of the strings block, allowing the kernel
+ to reallocate it easily at boot and free up the unused flattened
+ structure after expansion. Version 16 introduces a new more
+ "compact" format for the tree itself that is however not backward
+ compatible. Version 17 adds an additional field, size_dt_struct,
+ allowing it to be reallocated or moved more easily (this is
+ particularly useful for bootloaders which need to make
+ adjustments to a device tree based on probed information). You
+ should always generate a structure of the highest version defined
+ at the time of your implementation. Currently that is version 17,
+ unless you explicitly aim at being backward compatible.
+
+ - last_comp_version
+
+ Last compatible version. This indicates down to what version of
+ the DT block you are backward compatible. For example, version 2
+ is backward compatible with version 1 (that is, a kernel build
+ for version 1 will be able to boot with a version 2 format). You
+ should put a 1 in this field if you generate a device tree of
+ version 1 to 3, or 16 if you generate a tree of version 16 or 17
+ using the new unit name format.
+
+ - boot_cpuid_phys
+
+ This field only exist on version 2 headers. It indicate which
+ physical CPU ID is calling the kernel entry point. This is used,
+ among others, by kexec. If you are on an SMP system, this value
+ should match the content of the "reg" property of the CPU node in
+ the device-tree corresponding to the CPU calling the kernel entry
+ point (see further chapters for more information on the required
+ device-tree contents)
+
+ - size_dt_strings
+
+ This field only exists on version 3 and later headers. It
+ gives the size of the "strings" section of the device tree (which
+ starts at the offset given by off_dt_strings).
+
+ - size_dt_struct
+
+ This field only exists on version 17 and later headers. It gives
+ the size of the "structure" section of the device tree (which
+ starts at the offset given by off_dt_struct).
+
+ So the typical layout of a DT block (though the various parts don't
+ need to be in that order) looks like this (addresses go from top to
+ bottom)::
+
+
+ ------------------------------
+ base -> | struct boot_param_header |
+ ------------------------------
+ | (alignment gap) (*) |
+ ------------------------------
+ | memory reserve map |
+ ------------------------------
+ | (alignment gap) |
+ ------------------------------
+ | |
+ | device-tree structure |
+ | |
+ ------------------------------
+ | (alignment gap) |
+ ------------------------------
+ | |
+ | device-tree strings |
+ | |
+ -----> ------------------------------
+ |
+ |
+ --- (base + totalsize)
+
+ (*) The alignment gaps are not necessarily present; their presence
+ and size are dependent on the various alignment requirements of
+ the individual data blocks.
+
+
+2) Device tree generalities
+---------------------------
+
+This device-tree itself is separated in two different blocks, a
+structure block and a strings block. Both need to be aligned to a 4
+byte boundary.
+
+First, let's quickly describe the device-tree concept before detailing
+the storage format. This chapter does _not_ describe the detail of the
+required types of nodes & properties for the kernel, this is done
+later in chapter III.
+
+The device-tree layout is strongly inherited from the definition of
+the Open Firmware IEEE 1275 device-tree. It's basically a tree of
+nodes, each node having two or more named properties. A property can
+have a value or not.
+
+It is a tree, so each node has one and only one parent except for the
+root node who has no parent.
+
+A node has 2 names. The actual node name is generally contained in a
+property of type "name" in the node property list whose value is a
+zero terminated string and is mandatory for version 1 to 3 of the
+format definition (as it is in Open Firmware). Version 16 makes it
+optional as it can generate it from the unit name defined below.
+
+There is also a "unit name" that is used to differentiate nodes with
+the same name at the same level, it is usually made of the node
+names, the "@" sign, and a "unit address", which definition is
+specific to the bus type the node sits on.
+
+The unit name doesn't exist as a property per-se but is included in
+the device-tree structure. It is typically used to represent "path" in
+the device-tree. More details about the actual format of these will be
+below.
+
+The kernel generic code does not make any formal use of the
+unit address (though some board support code may do) so the only real
+requirement here for the unit address is to ensure uniqueness of
+the node unit name at a given level of the tree. Nodes with no notion
+of address and no possible sibling of the same name (like /memory or
+/cpus) may omit the unit address in the context of this specification,
+or use the "@0" default unit address. The unit name is used to define
+a node "full path", which is the concatenation of all parent node
+unit names separated with "/".
+
+The root node doesn't have a defined name, and isn't required to have
+a name property either if you are using version 3 or earlier of the
+format. It also has no unit address (no @ symbol followed by a unit
+address). The root node unit name is thus an empty string. The full
+path to the root node is "/".
+
+Every node which actually represents an actual device (that is, a node
+which isn't only a virtual "container" for more nodes, like "/cpus"
+is) is also required to have a "compatible" property indicating the
+specific hardware and an optional list of devices it is fully
+backwards compatible with.
+
+Finally, every node that can be referenced from a property in another
+node is required to have either a "phandle" or a "linux,phandle"
+property. Real Open Firmware implementations provide a unique
+"phandle" value for every node that the "prom_init()" trampoline code
+turns into "linux,phandle" properties. However, this is made optional
+if the flattened device tree is used directly. An example of a node
+referencing another node via "phandle" is when laying out the
+interrupt tree which will be described in a further version of this
+document.
+
+The "phandle" property is a 32-bit value that uniquely
+identifies a node. You are free to use whatever values or system of
+values, internal pointers, or whatever to generate these, the only
+requirement is that every node for which you provide that property has
+a unique value for it.
+
+Here is an example of a simple device-tree. In this example, an "o"
+designates a node followed by the node unit name. Properties are
+presented with their name followed by their content. "content"
+represents an ASCII string (zero terminated) value, while <content>
+represents a 32-bit value, specified in decimal or hexadecimal (the
+latter prefixed 0x). The various nodes in this example will be
+discussed in a later chapter. At this point, it is only meant to give
+you a idea of what a device-tree looks like. I have purposefully kept
+the "name" and "linux,phandle" properties which aren't necessary in
+order to give you a better idea of what the tree looks like in
+practice::
+
+ / o device-tree
+ |- name = "device-tree"
+ |- model = "MyBoardName"
+ |- compatible = "MyBoardFamilyName"
+ |- #address-cells = <2>
+ |- #size-cells = <2>
+ |- linux,phandle = <0>
+ |
+ o cpus
+ | | - name = "cpus"
+ | | - linux,phandle = <1>
+ | | - #address-cells = <1>
+ | | - #size-cells = <0>
+ | |
+ | o PowerPC,970@0
+ | |- name = "PowerPC,970"
+ | |- device_type = "cpu"
+ | |- reg = <0>
+ | |- clock-frequency = <0x5f5e1000>
+ | |- 64-bit
+ | |- linux,phandle = <2>
+ |
+ o memory@0
+ | |- name = "memory"
+ | |- device_type = "memory"
+ | |- reg = <0x00000000 0x00000000 0x00000000 0x20000000>
+ | |- linux,phandle = <3>
+ |
+ o chosen
+ |- name = "chosen"
+ |- bootargs = "root=/dev/sda2"
+ |- linux,phandle = <4>
+
+This tree is almost a minimal tree. It pretty much contains the
+minimal set of required nodes and properties to boot a linux kernel;
+that is, some basic model information at the root, the CPUs, and the
+physical memory layout. It also includes misc information passed
+through /chosen, like in this example, the platform type (mandatory)
+and the kernel command line arguments (optional).
+
+The /cpus/PowerPC,970@0/64-bit property is an example of a
+property without a value. All other properties have a value. The
+significance of the #address-cells and #size-cells properties will be
+explained in chapter IV which defines precisely the required nodes and
+properties and their content.
+
+
+3) Device tree "structure" block
+--------------------------------
+
+The structure of the device tree is a linearized tree structure. The
+"OF_DT_BEGIN_NODE" token starts a new node, and the "OF_DT_END_NODE"
+ends that node definition. Child nodes are simply defined before
+"OF_DT_END_NODE" (that is nodes within the node). A 'token' is a 32
+bit value. The tree has to be "finished" with a OF_DT_END token
+
+Here's the basic structure of a single node:
+
+ * token OF_DT_BEGIN_NODE (that is 0x00000001)
+ * for version 1 to 3, this is the node full path as a zero
+ terminated string, starting with "/". For version 16 and later,
+ this is the node unit name only (or an empty string for the
+ root node)
+ * [align gap to next 4 bytes boundary]
+ * for each property:
+
+ * token OF_DT_PROP (that is 0x00000003)
+ * 32-bit value of property value size in bytes (or 0 if no
+ value)
+ * 32-bit value of offset in string block of property name
+ * property value data if any
+ * [align gap to next 4 bytes boundary]
+
+ * [child nodes if any]
+ * token OF_DT_END_NODE (that is 0x00000002)
+
+So the node content can be summarized as a start token, a full path,
+a list of properties, a list of child nodes, and an end token. Every
+child node is a full node structure itself as defined above.
+
+NOTE: The above definition requires that all property definitions for
+a particular node MUST precede any subnode definitions for that node.
+Although the structure would not be ambiguous if properties and
+subnodes were intermingled, the kernel parser requires that the
+properties come first (up until at least 2.6.22). Any tools
+manipulating a flattened tree must take care to preserve this
+constraint.
+
+4) Device tree "strings" block
+------------------------------
+
+In order to save space, property names, which are generally redundant,
+are stored separately in the "strings" block. This block is simply the
+whole bunch of zero terminated strings for all property names
+concatenated together. The device-tree property definitions in the
+structure block will contain offset values from the beginning of the
+strings block.
+
+
+III - Required content of the device tree
+=========================================
+
+.. Warning::
+
+ All ``linux,*`` properties defined in this document apply only
+ to a flattened device-tree. If your platform uses a real
+ implementation of Open Firmware or an implementation compatible with
+ the Open Firmware client interface, those properties will be created
+ by the trampoline code in the kernel's prom_init() file. For example,
+ that's where you'll have to add code to detect your board model and
+ set the platform number. However, when using the flattened device-tree
+ entry point, there is no prom_init() pass, and thus you have to
+ provide those properties yourself.
+
+
+1) Note about cells and address representation
+----------------------------------------------
+
+The general rule is documented in the various Open Firmware
+documentations. If you choose to describe a bus with the device-tree
+and there exist an OF bus binding, then you should follow the
+specification. However, the kernel does not require every single
+device or bus to be described by the device tree.
+
+In general, the format of an address for a device is defined by the
+parent bus type, based on the #address-cells and #size-cells
+properties. Note that the parent's parent definitions of #address-cells
+and #size-cells are not inherited so every node with children must specify
+them. The kernel requires the root node to have those properties defining
+addresses format for devices directly mapped on the processor bus.
+
+Those 2 properties define 'cells' for representing an address and a
+size. A "cell" is a 32-bit number. For example, if both contain 2
+like the example tree given above, then an address and a size are both
+composed of 2 cells, and each is a 64-bit number (cells are
+concatenated and expected to be in big endian format). Another example
+is the way Apple firmware defines them, with 2 cells for an address
+and one cell for a size. Most 32-bit implementations should define
+#address-cells and #size-cells to 1, which represents a 32-bit value.
+Some 32-bit processors allow for physical addresses greater than 32
+bits; these processors should define #address-cells as 2.
+
+"reg" properties are always a tuple of the type "address size" where
+the number of cells of address and size is specified by the bus
+#address-cells and #size-cells. When a bus supports various address
+spaces and other flags relative to a given address allocation (like
+prefetchable, etc...) those flags are usually added to the top level
+bits of the physical address. For example, a PCI physical address is
+made of 3 cells, the bottom two containing the actual address itself
+while the top cell contains address space indication, flags, and pci
+bus & device numbers.
+
+For buses that support dynamic allocation, it's the accepted practice
+to then not provide the address in "reg" (keep it 0) though while
+providing a flag indicating the address is dynamically allocated, and
+then, to provide a separate "assigned-addresses" property that
+contains the fully allocated addresses. See the PCI OF bindings for
+details.
+
+In general, a simple bus with no address space bits and no dynamic
+allocation is preferred if it reflects your hardware, as the existing
+kernel address parsing functions will work out of the box. If you
+define a bus type with a more complex address format, including things
+like address space bits, you'll have to add a bus translator to the
+prom_parse.c file of the recent kernels for your bus type.
+
+The "reg" property only defines addresses and sizes (if #size-cells is
+non-0) within a given bus. In order to translate addresses upward
+(that is into parent bus addresses, and possibly into CPU physical
+addresses), all buses must contain a "ranges" property. If the
+"ranges" property is missing at a given level, it's assumed that
+translation isn't possible, i.e., the registers are not visible on the
+parent bus. The format of the "ranges" property for a bus is a list
+of::
+
+ bus address, parent bus address, size
+
+"bus address" is in the format of the bus this bus node is defining,
+that is, for a PCI bridge, it would be a PCI address. Thus, (bus
+address, size) defines a range of addresses for child devices. "parent
+bus address" is in the format of the parent bus of this bus. For
+example, for a PCI host controller, that would be a CPU address. For a
+PCI<->ISA bridge, that would be a PCI address. It defines the base
+address in the parent bus where the beginning of that range is mapped.
+
+For new 64-bit board support, I recommend either the 2/2 format or
+Apple's 2/1 format which is slightly more compact since sizes usually
+fit in a single 32-bit word. New 32-bit board support should use a
+1/1 format, unless the processor supports physical addresses greater
+than 32-bits, in which case a 2/1 format is recommended.
+
+Alternatively, the "ranges" property may be empty, indicating that the
+registers are visible on the parent bus using an identity mapping
+translation. In other words, the parent bus address space is the same
+as the child bus address space.
+
+2) Note about "compatible" properties
+-------------------------------------
+
+These properties are optional, but recommended in devices and the root
+node. The format of a "compatible" property is a list of concatenated
+zero terminated strings. They allow a device to express its
+compatibility with a family of similar devices, in some cases,
+allowing a single driver to match against several devices regardless
+of their actual names.
+
+3) Note about "name" properties
+-------------------------------
+
+While earlier users of Open Firmware like OldWorld macintoshes tended
+to use the actual device name for the "name" property, it's nowadays
+considered a good practice to use a name that is closer to the device
+class (often equal to device_type). For example, nowadays, Ethernet
+controllers are named "ethernet", an additional "model" property
+defining precisely the chip type/model, and "compatible" property
+defining the family in case a single driver can driver more than one
+of these chips. However, the kernel doesn't generally put any
+restriction on the "name" property; it is simply considered good
+practice to follow the standard and its evolutions as closely as
+possible.
+
+Note also that the new format version 16 makes the "name" property
+optional. If it's absent for a node, then the node's unit name is then
+used to reconstruct the name. That is, the part of the unit name
+before the "@" sign is used (or the entire unit name if no "@" sign
+is present).
+
+4) Note about node and property names and character set
+-------------------------------------------------------
+
+While Open Firmware provides more flexible usage of 8859-1, this
+specification enforces more strict rules. Nodes and properties should
+be comprised only of ASCII characters 'a' to 'z', '0' to
+'9', ',', '.', '_', '+', '#', '?', and '-'. Node names additionally
+allow uppercase characters 'A' to 'Z' (property names should be
+lowercase. The fact that vendors like Apple don't respect this rule is
+irrelevant here). Additionally, node and property names should always
+begin with a character in the range 'a' to 'z' (or 'A' to 'Z' for node
+names).
+
+The maximum number of characters for both nodes and property names
+is 31. In the case of node names, this is only the leftmost part of
+a unit name (the pure "name" property), it doesn't include the unit
+address which can extend beyond that limit.
+
+
+5) Required nodes and properties
+--------------------------------
+ These are all that are currently required. However, it is strongly
+ recommended that you expose PCI host bridges as documented in the
+ PCI binding to Open Firmware, and your interrupt tree as documented
+ in OF interrupt tree specification.
+
+ a) The root node
+
+ The root node requires some properties to be present:
+
+ - model : this is your board name/model
+ - #address-cells : address representation for "root" devices
+ - #size-cells: the size representation for "root" devices
+ - compatible : the board "family" generally finds its way here,
+ for example, if you have 2 board models with a similar layout,
+ that typically get driven by the same platform code in the
+ kernel, you would specify the exact board model in the
+ compatible property followed by an entry that represents the SoC
+ model.
+
+ The root node is also generally where you add additional properties
+ specific to your board like the serial number if any, that sort of
+ thing. It is recommended that if you add any "custom" property whose
+ name may clash with standard defined ones, you prefix them with your
+ vendor name and a comma.
+
+ Additional properties for the root node:
+
+ - serial-number : a string representing the device's serial number
+
+ b) The /cpus node
+
+ This node is the parent of all individual CPU nodes. It doesn't
+ have any specific requirements, though it's generally good practice
+ to have at least::
+
+ #address-cells = <00000001>
+ #size-cells = <00000000>
+
+ This defines that the "address" for a CPU is a single cell, and has
+ no meaningful size. This is not necessary but the kernel will assume
+ that format when reading the "reg" properties of a CPU node, see
+ below
+
+ c) The ``/cpus/*`` nodes
+
+ So under /cpus, you are supposed to create a node for every CPU on
+ the machine. There is no specific restriction on the name of the
+ CPU, though it's common to call it <architecture>,<core>. For
+ example, Apple uses PowerPC,G5 while IBM uses PowerPC,970FX.
+ However, the Generic Names convention suggests that it would be
+ better to simply use 'cpu' for each cpu node and use the compatible
+ property to identify the specific cpu core.
+
+ Required properties:
+
+ - device_type : has to be "cpu"
+ - reg : This is the physical CPU number, it's a single 32-bit cell
+ and is also used as-is as the unit number for constructing the
+ unit name in the full path. For example, with 2 CPUs, you would
+ have the full path::
+
+ /cpus/PowerPC,970FX@0
+ /cpus/PowerPC,970FX@1
+
+ (unit addresses do not require leading zeroes)
+ - d-cache-block-size : one cell, L1 data cache block size in bytes [#]_
+ - i-cache-block-size : one cell, L1 instruction cache block size in
+ bytes
+ - d-cache-size : one cell, size of L1 data cache in bytes
+ - i-cache-size : one cell, size of L1 instruction cache in bytes
+
+ .. [#] The cache "block" size is the size on which the cache management
+ instructions operate. Historically, this document used the cache
+ "line" size here which is incorrect. The kernel will prefer the cache
+ block size and will fallback to cache line size for backward
+ compatibility.
+
+ Recommended properties:
+
+ - timebase-frequency : a cell indicating the frequency of the
+ timebase in Hz. This is not directly used by the generic code,
+ but you are welcome to copy/paste the pSeries code for setting
+ the kernel timebase/decrementer calibration based on this
+ value.
+ - clock-frequency : a cell indicating the CPU core clock frequency
+ in Hz. A new property will be defined for 64-bit values, but if
+ your frequency is < 4Ghz, one cell is enough. Here as well as
+ for the above, the common code doesn't use that property, but
+ you are welcome to re-use the pSeries or Maple one. A future
+ kernel version might provide a common function for this.
+ - d-cache-line-size : one cell, L1 data cache line size in bytes
+ if different from the block size
+ - i-cache-line-size : one cell, L1 instruction cache line size in
+ bytes if different from the block size
+
+ You are welcome to add any property you find relevant to your board,
+ like some information about the mechanism used to soft-reset the
+ CPUs. For example, Apple puts the GPIO number for CPU soft reset
+ lines in there as a "soft-reset" property since they start secondary
+ CPUs by soft-resetting them.
+
+
+ d) the /memory node(s)
+
+ To define the physical memory layout of your board, you should
+ create one or more memory node(s). You can either create a single
+ node with all memory ranges in its reg property, or you can create
+ several nodes, as you wish. The unit address (@ part) used for the
+ full path is the address of the first range of memory defined by a
+ given node. If you use a single memory node, this will typically be
+ @0.
+
+ Required properties:
+
+ - device_type : has to be "memory"
+ - reg : This property contains all the physical memory ranges of
+ your board. It's a list of addresses/sizes concatenated
+ together, with the number of cells of each defined by the
+ #address-cells and #size-cells of the root node. For example,
+ with both of these properties being 2 like in the example given
+ earlier, a 970 based machine with 6Gb of RAM could typically
+ have a "reg" property here that looks like::
+
+ 00000000 00000000 00000000 80000000
+ 00000001 00000000 00000001 00000000
+
+ That is a range starting at 0 of 0x80000000 bytes and a range
+ starting at 0x100000000 and of 0x100000000 bytes. You can see
+ that there is no memory covering the IO hole between 2Gb and
+ 4Gb. Some vendors prefer splitting those ranges into smaller
+ segments, but the kernel doesn't care.
+
+ Additional properties:
+
+ - hotpluggable : The presence of this property provides an explicit
+ hint to the operating system that this memory may potentially be
+ removed later. The kernel can take this into consideration when
+ doing nonmovable allocations and when laying out memory zones.
+
+ e) The /chosen node
+
+ This node is a bit "special". Normally, that's where Open Firmware
+ puts some variable environment information, like the arguments, or
+ the default input/output devices.
+
+ This specification makes a few of these mandatory, but also defines
+ some linux-specific properties that would be normally constructed by
+ the prom_init() trampoline when booting with an OF client interface,
+ but that you have to provide yourself when using the flattened format.
+
+ Recommended properties:
+
+ - bootargs : This zero-terminated string is passed as the kernel
+ command line
+ - linux,stdout-path : This is the full path to your standard
+ console device if any. Typically, if you have serial devices on
+ your board, you may want to put the full path to the one set as
+ the default console in the firmware here, for the kernel to pick
+ it up as its own default console.
+
+ Note that u-boot creates and fills in the chosen node for platforms
+ that use it.
+
+ (Note: a practice that is now obsolete was to include a property
+ under /chosen called interrupt-controller which had a phandle value
+ that pointed to the main interrupt controller)
+
+ f) the /soc<SOCname> node
+
+ This node is used to represent a system-on-a-chip (SoC) and must be
+ present if the processor is a SoC. The top-level soc node contains
+ information that is global to all devices on the SoC. The node name
+ should contain a unit address for the SoC, which is the base address
+ of the memory-mapped register set for the SoC. The name of an SoC
+ node should start with "soc", and the remainder of the name should
+ represent the part number for the soc. For example, the MPC8540's
+ soc node would be called "soc8540".
+
+ Required properties:
+
+ - ranges : Should be defined as specified in 1) to describe the
+ translation of SoC addresses for memory mapped SoC registers.
+ - bus-frequency: Contains the bus frequency for the SoC node.
+ Typically, the value of this field is filled in by the boot
+ loader.
+ - compatible : Exact model of the SoC
+
+
+ Recommended properties:
+
+ - reg : This property defines the address and size of the
+ memory-mapped registers that are used for the SOC node itself.
+ It does not include the child device registers - these will be
+ defined inside each child node. The address specified in the
+ "reg" property should match the unit address of the SOC node.
+ - #address-cells : Address representation for "soc" devices. The
+ format of this field may vary depending on whether or not the
+ device registers are memory mapped. For memory mapped
+ registers, this field represents the number of cells needed to
+ represent the address of the registers. For SOCs that do not
+ use MMIO, a special address format should be defined that
+ contains enough cells to represent the required information.
+ See 1) above for more details on defining #address-cells.
+ - #size-cells : Size representation for "soc" devices
+ - #interrupt-cells : Defines the width of cells used to represent
+ interrupts. Typically this value is <2>, which includes a
+ 32-bit number that represents the interrupt number, and a
+ 32-bit number that represents the interrupt sense and level.
+ This field is only needed if the SOC contains an interrupt
+ controller.
+
+ The SOC node may contain child nodes for each SOC device that the
+ platform uses. Nodes should not be created for devices which exist
+ on the SOC but are not used by a particular platform. See chapter VI
+ for more information on how to specify devices that are part of a SOC.
+
+ Example SOC node for the MPC8540::
+
+ soc8540@e0000000 {
+ #address-cells = <1>;
+ #size-cells = <1>;
+ #interrupt-cells = <2>;
+ device_type = "soc";
+ ranges = <0x00000000 0xe0000000 0x00100000>
+ reg = <0xe0000000 0x00003000>;
+ bus-frequency = <0>;
+ }
+
+
+
+IV - "dtc", the device tree compiler
+====================================
+
+
+dtc source code can be found at
+<http://git.jdl.com/gitweb/?p=dtc.git>
+
+.. Warning::
+
+ This version is still in early development stage; the
+ resulting device-tree "blobs" have not yet been validated with the
+ kernel. The current generated block lacks a useful reserve map (it will
+ be fixed to generate an empty one, it's up to the bootloader to fill
+ it up) among others. The error handling needs work, bugs are lurking,
+ etc...
+
+dtc basically takes a device-tree in a given format and outputs a
+device-tree in another format. The currently supported formats are:
+
+Input formats
+-------------
+
+ - "dtb": "blob" format, that is a flattened device-tree block
+ with
+ header all in a binary blob.
+ - "dts": "source" format. This is a text file containing a
+ "source" for a device-tree. The format is defined later in this
+ chapter.
+ - "fs" format. This is a representation equivalent to the
+ output of /proc/device-tree, that is nodes are directories and
+ properties are files
+
+Output formats
+--------------
+
+ - "dtb": "blob" format
+ - "dts": "source" format
+ - "asm": assembly language file. This is a file that can be
+ sourced by gas to generate a device-tree "blob". That file can
+ then simply be added to your Makefile. Additionally, the
+ assembly file exports some symbols that can be used.
+
+
+The syntax of the dtc tool is::
+
+ dtc [-I <input-format>] [-O <output-format>]
+ [-o output-filename] [-V output_version] input_filename
+
+
+The "output_version" defines what version of the "blob" format will be
+generated. Supported versions are 1,2,3 and 16. The default is
+currently version 3 but that may change in the future to version 16.
+
+Additionally, dtc performs various sanity checks on the tree, like the
+uniqueness of linux, phandle properties, validity of strings, etc...
+
+The format of the .dts "source" file is "C" like, supports C and C++
+style comments::
+
+ / {
+ }
+
+The above is the "device-tree" definition. It's the only statement
+supported currently at the toplevel.
+
+::
+
+ / {
+ property1 = "string_value"; /* define a property containing a 0
+ * terminated string
+ */
+
+ property2 = <0x1234abcd>; /* define a property containing a
+ * numerical 32-bit value (hexadecimal)
+ */
+
+ property3 = <0x12345678 0x12345678 0xdeadbeef>;
+ /* define a property containing 3
+ * numerical 32-bit values (cells) in
+ * hexadecimal
+ */
+ property4 = [0x0a 0x0b 0x0c 0x0d 0xde 0xea 0xad 0xbe 0xef];
+ /* define a property whose content is
+ * an arbitrary array of bytes
+ */
+
+ childnode@address { /* define a child node named "childnode"
+ * whose unit name is "childnode at
+ * address"
+ */
+
+ childprop = "hello\n"; /* define a property "childprop" of
+ * childnode (in this case, a string)
+ */
+ };
+ };
+
+Nodes can contain other nodes etc... thus defining the hierarchical
+structure of the tree.
+
+Strings support common escape sequences from C: "\n", "\t", "\r",
+"\(octal value)", "\x(hex value)".
+
+It is also suggested that you pipe your source file through cpp (gcc
+preprocessor) so you can use #include's, #define for constants, etc...
+
+Finally, various options are planned but not yet implemented, like
+automatic generation of phandles, labels (exported to the asm file so
+you can point to a property content and change it easily from whatever
+you link the device-tree with), label or path instead of numeric value
+in some cells to "point" to a node (replaced by a phandle at compile
+time), export of reserve map address to the asm file, ability to
+specify reserve map content at compile time, etc...
+
+We may provide a .h include file with common definitions of that
+proves useful for some properties (like building PCI properties or
+interrupt maps) though it may be better to add a notion of struct
+definitions to the compiler...
+
+
+V - Recommendations for a bootloader
+====================================
+
+
+Here are some various ideas/recommendations that have been proposed
+while all this has been defined and implemented.
+
+ - The bootloader may want to be able to use the device-tree itself
+ and may want to manipulate it (to add/edit some properties,
+ like physical memory size or kernel arguments). At this point, 2
+ choices can be made. Either the bootloader works directly on the
+ flattened format, or the bootloader has its own internal tree
+ representation with pointers (similar to the kernel one) and
+ re-flattens the tree when booting the kernel. The former is a bit
+ more difficult to edit/modify, the later requires probably a bit
+ more code to handle the tree structure. Note that the structure
+ format has been designed so it's relatively easy to "insert"
+ properties or nodes or delete them by just memmoving things
+ around. It contains no internal offsets or pointers for this
+ purpose.
+
+ - An example of code for iterating nodes & retrieving properties
+ directly from the flattened tree format can be found in the kernel
+ file drivers/of/fdt.c. Look at the of_scan_flat_dt() function,
+ its usage in early_init_devtree(), and the corresponding various
+ early_init_dt_scan_*() callbacks. That code can be re-used in a
+ GPL bootloader, and as the author of that code, I would be happy
+ to discuss possible free licensing to any vendor who wishes to
+ integrate all or part of this code into a non-GPL bootloader.
+ (reference needed; who is 'I' here? ---gcl Jan 31, 2011)
+
+
+
+VI - System-on-a-chip devices and nodes
+=======================================
+
+Many companies are now starting to develop system-on-a-chip
+processors, where the processor core (CPU) and many peripheral devices
+exist on a single piece of silicon. For these SOCs, an SOC node
+should be used that defines child nodes for the devices that make
+up the SOC. While platforms are not required to use this model in
+order to boot the kernel, it is highly encouraged that all SOC
+implementations define as complete a flat-device-tree as possible to
+describe the devices on the SOC. This will allow for the
+genericization of much of the kernel code.
+
+
+1) Defining child nodes of an SOC
+---------------------------------
+
+Each device that is part of an SOC may have its own node entry inside
+the SOC node. For each device that is included in the SOC, the unit
+address property represents the address offset for this device's
+memory-mapped registers in the parent's address space. The parent's
+address space is defined by the "ranges" property in the top-level soc
+node. The "reg" property for each node that exists directly under the
+SOC node should contain the address mapping from the child address space
+to the parent SOC address space and the size of the device's
+memory-mapped register file.
+
+For many devices that may exist inside an SOC, there are predefined
+specifications for the format of the device tree node. All SOC child
+nodes should follow these specifications, except where noted in this
+document.
+
+See appendix A for an example partial SOC node definition for the
+MPC8540.
+
+
+2) Representing devices without a current OF specification
+----------------------------------------------------------
+
+Currently, there are many devices on SoCs that do not have a standard
+representation defined as part of the Open Firmware specifications,
+mainly because the boards that contain these SoCs are not currently
+booted using Open Firmware. Binding documentation for new devices
+should be added to the Documentation/devicetree/bindings directory.
+That directory will expand as device tree support is added to more and
+more SoCs.
+
+
+VII - Specifying interrupt information for devices
+===================================================
+
+The device tree represents the buses and devices of a hardware
+system in a form similar to the physical bus topology of the
+hardware.
+
+In addition, a logical 'interrupt tree' exists which represents the
+hierarchy and routing of interrupts in the hardware.
+
+The interrupt tree model is fully described in the
+document "Open Firmware Recommended Practice: Interrupt
+Mapping Version 0.9". The document is available at:
+<http://www.devicetree.org/open-firmware/practice/>
+
+1) interrupts property
+----------------------
+
+Devices that generate interrupts to a single interrupt controller
+should use the conventional OF representation described in the
+OF interrupt mapping documentation.
+
+Each device which generates interrupts must have an 'interrupt'
+property. The interrupt property value is an arbitrary number of
+of 'interrupt specifier' values which describe the interrupt or
+interrupts for the device.
+
+The encoding of an interrupt specifier is determined by the
+interrupt domain in which the device is located in the
+interrupt tree. The root of an interrupt domain specifies in
+its #interrupt-cells property the number of 32-bit cells
+required to encode an interrupt specifier. See the OF interrupt
+mapping documentation for a detailed description of domains.
+
+For example, the binding for the OpenPIC interrupt controller
+specifies an #interrupt-cells value of 2 to encode the interrupt
+number and level/sense information. All interrupt children in an
+OpenPIC interrupt domain use 2 cells per interrupt in their interrupts
+property.
+
+The PCI bus binding specifies a #interrupt-cells value of 1 to encode
+which interrupt pin (INTA,INTB,INTC,INTD) is used.
+
+2) interrupt-parent property
+----------------------------
+
+The interrupt-parent property is specified to define an explicit
+link between a device node and its interrupt parent in
+the interrupt tree. The value of interrupt-parent is the
+phandle of the parent node.
+
+If the interrupt-parent property is not defined for a node, its
+interrupt parent is assumed to be an ancestor in the node's
+*device tree* hierarchy.
+
+3) OpenPIC Interrupt Controllers
+--------------------------------
+
+OpenPIC interrupt controllers require 2 cells to encode
+interrupt information. The first cell defines the interrupt
+number. The second cell defines the sense and level
+information.
+
+Sense and level information should be encoded as follows:
+
+ == ========================================
+ 0 low to high edge sensitive type enabled
+ 1 active low level sensitive type enabled
+ 2 active high level sensitive type enabled
+ 3 high to low edge sensitive type enabled
+ == ========================================
+
+4) ISA Interrupt Controllers
+----------------------------
+
+ISA PIC interrupt controllers require 2 cells to encode
+interrupt information. The first cell defines the interrupt
+number. The second cell defines the sense and level
+information.
+
+ISA PIC interrupt controllers should adhere to the ISA PIC
+encodings listed below:
+
+ == ========================================
+ 0 active low level sensitive type enabled
+ 1 active high level sensitive type enabled
+ 2 high to low edge sensitive type enabled
+ 3 low to high edge sensitive type enabled
+ == ========================================
+
+VIII - Specifying Device Power Management Information (sleep property)
+======================================================================
+
+Devices on SOCs often have mechanisms for placing devices into low-power
+states that are decoupled from the devices' own register blocks. Sometimes,
+this information is more complicated than a cell-index property can
+reasonably describe. Thus, each device controlled in such a manner
+may contain a "sleep" property which describes these connections.
+
+The sleep property consists of one or more sleep resources, each of
+which consists of a phandle to a sleep controller, followed by a
+controller-specific sleep specifier of zero or more cells.
+
+The semantics of what type of low power modes are possible are defined
+by the sleep controller. Some examples of the types of low power modes
+that may be supported are:
+
+ - Dynamic: The device may be disabled or enabled at any time.
+ - System Suspend: The device may request to be disabled or remain
+ awake during system suspend, but will not be disabled until then.
+ - Permanent: The device is disabled permanently (until the next hard
+ reset).
+
+Some devices may share a clock domain with each other, such that they should
+only be suspended when none of the devices are in use. Where reasonable,
+such nodes should be placed on a virtual bus, where the bus has the sleep
+property. If the clock domain is shared among devices that cannot be
+reasonably grouped in this manner, then create a virtual sleep controller
+(similar to an interrupt nexus, except that defining a standardized
+sleep-map should wait until its necessity is demonstrated).
+
+IX - Specifying dma bus information
+===================================
+
+Some devices may have DMA memory range shifted relatively to the beginning of
+RAM, or even placed outside of kernel RAM. For example, the Keystone 2 SoC
+worked in LPAE mode with 4G memory has:
+- RAM range: [0x8 0000 0000, 0x8 FFFF FFFF]
+- DMA range: [ 0x8000 0000, 0xFFFF FFFF]
+and DMA range is aliased into first 2G of RAM in HW.
+
+In such cases, DMA addresses translation should be performed between CPU phys
+and DMA addresses. The "dma-ranges" property is intended to be used
+for describing the configuration of such system in DT.
+
+In addition, each DMA master device on the DMA bus may or may not support
+coherent DMA operations. The "dma-coherent" property is intended to be used
+for identifying devices supported coherent DMA operations in DT.
+
+* DMA Bus master
+
+Optional property:
+
+- dma-ranges: <prop-encoded-array> encoded as arbitrary number of triplets of
+ (child-bus-address, parent-bus-address, length). Each triplet specified
+ describes a contiguous DMA address range.
+ The dma-ranges property is used to describe the direct memory access (DMA)
+ structure of a memory-mapped bus whose device tree parent can be accessed
+ from DMA operations originating from the bus. It provides a means of
+ defining a mapping or translation between the physical address space of
+ the bus and the physical address space of the parent of the bus.
+ (for more information see the Devicetree Specification)
+
+* DMA Bus child
+
+Optional property:
+
+- dma-ranges: <empty> value. if present - It means that DMA addresses
+ translation has to be enabled for this device.
+- dma-coherent: Present if dma operations are coherent
+
+Example::
+
+ soc {
+ compatible = "ti,keystone","simple-bus";
+ ranges = <0x0 0x0 0x0 0xc0000000>;
+ dma-ranges = <0x80000000 0x8 0x00000000 0x80000000>;
+
+ [...]
+
+ usb: usb@2680000 {
+ compatible = "ti,keystone-dwc3";
+
+ [...]
+ dma-coherent;
+ };
+ };
+
+Appendix A - Sample SOC node for MPC8540
+========================================
+
+::
+
+ soc@e0000000 {
+ #address-cells = <1>;
+ #size-cells = <1>;
+ compatible = "fsl,mpc8540-ccsr", "simple-bus";
+ device_type = "soc";
+ ranges = <0x00000000 0xe0000000 0x00100000>
+ bus-frequency = <0>;
+ interrupt-parent = <&pic>;
+
+ ethernet@24000 {
+ #address-cells = <1>;
+ #size-cells = <1>;
+ device_type = "network";
+ model = "TSEC";
+ compatible = "gianfar", "simple-bus";
+ reg = <0x24000 0x1000>;
+ local-mac-address = [ 0x00 0xE0 0x0C 0x00 0x73 0x00 ];
+ interrupts = <0x29 2 0x30 2 0x34 2>;
+ phy-handle = <&phy0>;
+ sleep = <&pmc 0x00000080>;
+ ranges;
+
+ mdio@24520 {
+ reg = <0x24520 0x20>;
+ compatible = "fsl,gianfar-mdio";
+
+ phy0: ethernet-phy@0 {
+ interrupts = <5 1>;
+ reg = <0>;
+ };
+
+ phy1: ethernet-phy@1 {
+ interrupts = <5 1>;
+ reg = <1>;
+ };
+
+ phy3: ethernet-phy@3 {
+ interrupts = <7 1>;
+ reg = <3>;
+ };
+ };
+ };
+
+ ethernet@25000 {
+ device_type = "network";
+ model = "TSEC";
+ compatible = "gianfar";
+ reg = <0x25000 0x1000>;
+ local-mac-address = [ 0x00 0xE0 0x0C 0x00 0x73 0x01 ];
+ interrupts = <0x13 2 0x14 2 0x18 2>;
+ phy-handle = <&phy1>;
+ sleep = <&pmc 0x00000040>;
+ };
+
+ ethernet@26000 {
+ device_type = "network";
+ model = "FEC";
+ compatible = "gianfar";
+ reg = <0x26000 0x1000>;
+ local-mac-address = [ 0x00 0xE0 0x0C 0x00 0x73 0x02 ];
+ interrupts = <0x41 2>;
+ phy-handle = <&phy3>;
+ sleep = <&pmc 0x00000020>;
+ };
+
+ serial@4500 {
+ #address-cells = <1>;
+ #size-cells = <1>;
+ compatible = "fsl,mpc8540-duart", "simple-bus";
+ sleep = <&pmc 0x00000002>;
+ ranges;
+
+ serial@4500 {
+ device_type = "serial";
+ compatible = "ns16550";
+ reg = <0x4500 0x100>;
+ clock-frequency = <0>;
+ interrupts = <0x42 2>;
+ };
+
+ serial@4600 {
+ device_type = "serial";
+ compatible = "ns16550";
+ reg = <0x4600 0x100>;
+ clock-frequency = <0>;
+ interrupts = <0x42 2>;
+ };
+ };
+
+ pic: pic@40000 {
+ interrupt-controller;
+ #address-cells = <0>;
+ #interrupt-cells = <2>;
+ reg = <0x40000 0x40000>;
+ compatible = "chrp,open-pic";
+ device_type = "open-pic";
+ };
+
+ i2c@3000 {
+ interrupts = <0x43 2>;
+ reg = <0x3000 0x100>;
+ compatible = "fsl-i2c";
+ dfsrr;
+ sleep = <&pmc 0x00000004>;
+ };
+
+ pmc: power@e0070 {
+ compatible = "fsl,mpc8540-pmc", "fsl,mpc8548-pmc";
+ reg = <0xe0070 0x20>;
+ };
+ };
diff --git a/Documentation/devicetree/booting-without-of.txt b/Documentation/devicetree/booting-without-of.txt
deleted file mode 100644
index 4660cce..0000000
--- a/Documentation/devicetree/booting-without-of.txt
+++ /dev/null
@@ -1,1553 +0,0 @@
- Booting the Linux/ppc kernel without Open Firmware
- --------------------------------------------------
-
-(c) 2005 Benjamin Herrenschmidt <benh at kernel.crashing.org>,
- IBM Corp.
-(c) 2005 Becky Bruce <becky.bruce at freescale.com>,
- Freescale Semiconductor, FSL SOC and 32-bit additions
-(c) 2006 MontaVista Software, Inc.
- Flash chip node definition
-
-Table of Contents
-=================
-
- I - Introduction
- 1) Entry point for arch/arm
- 2) Entry point for arch/powerpc
- 3) Entry point for arch/x86
- 4) Entry point for arch/mips/bmips
- 5) Entry point for arch/sh
-
- II - The DT block format
- 1) Header
- 2) Device tree generalities
- 3) Device tree "structure" block
- 4) Device tree "strings" block
-
- III - Required content of the device tree
- 1) Note about cells and address representation
- 2) Note about "compatible" properties
- 3) Note about "name" properties
- 4) Note about node and property names and character set
- 5) Required nodes and properties
- a) The root node
- b) The /cpus node
- c) The /cpus/* nodes
- d) the /memory node(s)
- e) The /chosen node
- f) the /soc<SOCname> node
-
- IV - "dtc", the device tree compiler
-
- V - Recommendations for a bootloader
-
- VI - System-on-a-chip devices and nodes
- 1) Defining child nodes of an SOC
- 2) Representing devices without a current OF specification
-
- VII - Specifying interrupt information for devices
- 1) interrupts property
- 2) interrupt-parent property
- 3) OpenPIC Interrupt Controllers
- 4) ISA Interrupt Controllers
-
- VIII - Specifying device power management information (sleep property)
-
- IX - Specifying dma bus information
-
- Appendix A - Sample SOC node for MPC8540
-
-
-Revision Information
-====================
-
- May 18, 2005: Rev 0.1 - Initial draft, no chapter III yet.
-
- May 19, 2005: Rev 0.2 - Add chapter III and bits & pieces here or
- clarifies the fact that a lot of things are
- optional, the kernel only requires a very
- small device tree, though it is encouraged
- to provide an as complete one as possible.
-
- May 24, 2005: Rev 0.3 - Precise that DT block has to be in RAM
- - Misc fixes
- - Define version 3 and new format version 16
- for the DT block (version 16 needs kernel
- patches, will be fwd separately).
- String block now has a size, and full path
- is replaced by unit name for more
- compactness.
- linux,phandle is made optional, only nodes
- that are referenced by other nodes need it.
- "name" property is now automatically
- deduced from the unit name
-
- June 1, 2005: Rev 0.4 - Correct confusion between OF_DT_END and
- OF_DT_END_NODE in structure definition.
- - Change version 16 format to always align
- property data to 4 bytes. Since tokens are
- already aligned, that means no specific
- required alignment between property size
- and property data. The old style variable
- alignment would make it impossible to do
- "simple" insertion of properties using
- memmove (thanks Milton for
- noticing). Updated kernel patch as well
- - Correct a few more alignment constraints
- - Add a chapter about the device-tree
- compiler and the textural representation of
- the tree that can be "compiled" by dtc.
-
- November 21, 2005: Rev 0.5
- - Additions/generalizations for 32-bit
- - Changed to reflect the new arch/powerpc
- structure
- - Added chapter VI
-
-
- ToDo:
- - Add some definitions of interrupt tree (simple/complex)
- - Add some definitions for PCI host bridges
- - Add some common address format examples
- - Add definitions for standard properties and "compatible"
- names for cells that are not already defined by the existing
- OF spec.
- - Compare FSL SOC use of PCI to standard and make sure no new
- node definition required.
- - Add more information about node definitions for SOC devices
- that currently have no standard, like the FSL CPM.
-
-
-I - Introduction
-================
-
-During the development of the Linux/ppc64 kernel, and more
-specifically, the addition of new platform types outside of the old
-IBM pSeries/iSeries pair, it was decided to enforce some strict rules
-regarding the kernel entry and bootloader <-> kernel interfaces, in
-order to avoid the degeneration that had become the ppc32 kernel entry
-point and the way a new platform should be added to the kernel. The
-legacy iSeries platform breaks those rules as it predates this scheme,
-but no new board support will be accepted in the main tree that
-doesn't follow them properly. In addition, since the advent of the
-arch/powerpc merged architecture for ppc32 and ppc64, new 32-bit
-platforms and 32-bit platforms which move into arch/powerpc will be
-required to use these rules as well.
-
-The main requirement that will be defined in more detail below is
-the presence of a device-tree whose format is defined after Open
-Firmware specification. However, in order to make life easier
-to embedded board vendors, the kernel doesn't require the device-tree
-to represent every device in the system and only requires some nodes
-and properties to be present. This will be described in detail in
-section III, but, for example, the kernel does not require you to
-create a node for every PCI device in the system. It is a requirement
-to have a node for PCI host bridges in order to provide interrupt
-routing information and memory/IO ranges, among others. It is also
-recommended to define nodes for on chip devices and other buses that
-don't specifically fit in an existing OF specification. This creates a
-great flexibility in the way the kernel can then probe those and match
-drivers to device, without having to hard code all sorts of tables. It
-also makes it more flexible for board vendors to do minor hardware
-upgrades without significantly impacting the kernel code or cluttering
-it with special cases.
-
-
-1) Entry point for arch/arm
----------------------------
-
- There is one single entry point to the kernel, at the start
- of the kernel image. That entry point supports two calling
- conventions. A summary of the interface is described here. A full
- description of the boot requirements is documented in
- Documentation/arm/booting.rst
-
- a) ATAGS interface. Minimal information is passed from firmware
- to the kernel with a tagged list of predefined parameters.
-
- r0 : 0
-
- r1 : Machine type number
-
- r2 : Physical address of tagged list in system RAM
-
- b) Entry with a flattened device-tree block. Firmware loads the
- physical address of the flattened device tree block (dtb) into r2,
- r1 is not used, but it is considered good practice to use a valid
- machine number as described in Documentation/arm/booting.rst.
-
- r0 : 0
-
- r1 : Valid machine type number. When using a device tree,
- a single machine type number will often be assigned to
- represent a class or family of SoCs.
-
- r2 : physical pointer to the device-tree block
- (defined in chapter II) in RAM. Device tree can be located
- anywhere in system RAM, but it should be aligned on a 64 bit
- boundary.
-
- The kernel will differentiate between ATAGS and device tree booting by
- reading the memory pointed to by r2 and looking for either the flattened
- device tree block magic value (0xd00dfeed) or the ATAG_CORE value at
- offset 0x4 from r2 (0x54410001).
-
-2) Entry point for arch/powerpc
--------------------------------
-
- There is one single entry point to the kernel, at the start
- of the kernel image. That entry point supports two calling
- conventions:
-
- a) Boot from Open Firmware. If your firmware is compatible
- with Open Firmware (IEEE 1275) or provides an OF compatible
- client interface API (support for "interpret" callback of
- forth words isn't required), you can enter the kernel with:
-
- r5 : OF callback pointer as defined by IEEE 1275
- bindings to powerpc. Only the 32-bit client interface
- is currently supported
-
- r3, r4 : address & length of an initrd if any or 0
-
- The MMU is either on or off; the kernel will run the
- trampoline located in arch/powerpc/kernel/prom_init.c to
- extract the device-tree and other information from open
- firmware and build a flattened device-tree as described
- in b). prom_init() will then re-enter the kernel using
- the second method. This trampoline code runs in the
- context of the firmware, which is supposed to handle all
- exceptions during that time.
-
- b) Direct entry with a flattened device-tree block. This entry
- point is called by a) after the OF trampoline and can also be
- called directly by a bootloader that does not support the Open
- Firmware client interface. It is also used by "kexec" to
- implement "hot" booting of a new kernel from a previous
- running one. This method is what I will describe in more
- details in this document, as method a) is simply standard Open
- Firmware, and thus should be implemented according to the
- various standard documents defining it and its binding to the
- PowerPC platform. The entry point definition then becomes:
-
- r3 : physical pointer to the device-tree block
- (defined in chapter II) in RAM
-
- r4 : physical pointer to the kernel itself. This is
- used by the assembly code to properly disable the MMU
- in case you are entering the kernel with MMU enabled
- and a non-1:1 mapping.
-
- r5 : NULL (as to differentiate with method a)
-
- Note about SMP entry: Either your firmware puts your other
- CPUs in some sleep loop or spin loop in ROM where you can get
- them out via a soft reset or some other means, in which case
- you don't need to care, or you'll have to enter the kernel
- with all CPUs. The way to do that with method b) will be
- described in a later revision of this document.
-
- Board supports (platforms) are not exclusive config options. An
- arbitrary set of board supports can be built in a single kernel
- image. The kernel will "know" what set of functions to use for a
- given platform based on the content of the device-tree. Thus, you
- should:
-
- a) add your platform support as a _boolean_ option in
- arch/powerpc/Kconfig, following the example of PPC_PSERIES,
- PPC_PMAC and PPC_MAPLE. The later is probably a good
- example of a board support to start from.
-
- b) create your main platform file as
- "arch/powerpc/platforms/myplatform/myboard_setup.c" and add it
- to the Makefile under the condition of your CONFIG_
- option. This file will define a structure of type "ppc_md"
- containing the various callbacks that the generic code will
- use to get to your platform specific code
-
- A kernel image may support multiple platforms, but only if the
- platforms feature the same core architecture. A single kernel build
- cannot support both configurations with Book E and configurations
- with classic Powerpc architectures.
-
-3) Entry point for arch/x86
--------------------------------
-
- There is one single 32bit entry point to the kernel at code32_start,
- the decompressor (the real mode entry point goes to the same 32bit
- entry point once it switched into protected mode). That entry point
- supports one calling convention which is documented in
- Documentation/x86/boot.rst
- The physical pointer to the device-tree block (defined in chapter II)
- is passed via setup_data which requires at least boot protocol 2.09.
- The type filed is defined as
-
- #define SETUP_DTB 2
-
- This device-tree is used as an extension to the "boot page". As such it
- does not parse / consider data which is already covered by the boot
- page. This includes memory size, reserved ranges, command line arguments
- or initrd address. It simply holds information which can not be retrieved
- otherwise like interrupt routing or a list of devices behind an I2C bus.
-
-4) Entry point for arch/mips/bmips
-----------------------------------
-
- Some bootloaders only support a single entry point, at the start of the
- kernel image. Other bootloaders will jump to the ELF start address.
- Both schemes are supported; CONFIG_BOOT_RAW=y and CONFIG_NO_EXCEPT_FILL=y,
- so the first instruction immediately jumps to kernel_entry().
-
- Similar to the arch/arm case (b), a DT-aware bootloader is expected to
- set up the following registers:
-
- a0 : 0
-
- a1 : 0xffffffff
-
- a2 : Physical pointer to the device tree block (defined in chapter
- II) in RAM. The device tree can be located anywhere in the first
- 512MB of the physical address space (0x00000000 - 0x1fffffff),
- aligned on a 64 bit boundary.
-
- Legacy bootloaders do not use this convention, and they do not pass in a
- DT block. In this case, Linux will look for a builtin DTB, selected via
- CONFIG_DT_*.
-
- This convention is defined for 32-bit systems only, as there are not
- currently any 64-bit BMIPS implementations.
-
-5) Entry point for arch/sh
---------------------------
-
- Device-tree-compatible SH bootloaders are expected to provide the physical
- address of the device tree blob in r4. Since legacy bootloaders did not
- guarantee any particular initial register state, kernels built to
- inter-operate with old bootloaders must either use a builtin DTB or
- select a legacy board option (something other than CONFIG_SH_DEVICE_TREE)
- that does not use device tree. Support for the latter is being phased out
- in favor of device tree.
-
-
-II - The DT block format
-========================
-
-
-This chapter defines the actual format of the flattened device-tree
-passed to the kernel. The actual content of it and kernel requirements
-are described later. You can find example of code manipulating that
-format in various places, including arch/powerpc/kernel/prom_init.c
-which will generate a flattened device-tree from the Open Firmware
-representation, or the fs2dt utility which is part of the kexec tools
-which will generate one from a filesystem representation. It is
-expected that a bootloader like uboot provides a bit more support,
-that will be discussed later as well.
-
-Note: The block has to be in main memory. It has to be accessible in
-both real mode and virtual mode with no mapping other than main
-memory. If you are writing a simple flash bootloader, it should copy
-the block to RAM before passing it to the kernel.
-
-
-1) Header
----------
-
- The kernel is passed the physical address pointing to an area of memory
- that is roughly described in include/linux/of_fdt.h by the structure
- boot_param_header:
-
-struct boot_param_header {
- u32 magic; /* magic word OF_DT_HEADER */
- u32 totalsize; /* total size of DT block */
- u32 off_dt_struct; /* offset to structure */
- u32 off_dt_strings; /* offset to strings */
- u32 off_mem_rsvmap; /* offset to memory reserve map
- */
- u32 version; /* format version */
- u32 last_comp_version; /* last compatible version */
-
- /* version 2 fields below */
- u32 boot_cpuid_phys; /* Which physical CPU id we're
- booting on */
- /* version 3 fields below */
- u32 size_dt_strings; /* size of the strings block */
-
- /* version 17 fields below */
- u32 size_dt_struct; /* size of the DT structure block */
-};
-
- Along with the constants:
-
-/* Definitions used by the flattened device tree */
-#define OF_DT_HEADER 0xd00dfeed /* 4: version,
- 4: total size */
-#define OF_DT_BEGIN_NODE 0x1 /* Start node: full name
- */
-#define OF_DT_END_NODE 0x2 /* End node */
-#define OF_DT_PROP 0x3 /* Property: name off,
- size, content */
-#define OF_DT_END 0x9
-
- All values in this header are in big endian format, the various
- fields in this header are defined more precisely below. All
- "offset" values are in bytes from the start of the header; that is
- from the physical base address of the device tree block.
-
- - magic
-
- This is a magic value that "marks" the beginning of the
- device-tree block header. It contains the value 0xd00dfeed and is
- defined by the constant OF_DT_HEADER
-
- - totalsize
-
- This is the total size of the DT block including the header. The
- "DT" block should enclose all data structures defined in this
- chapter (who are pointed to by offsets in this header). That is,
- the device-tree structure, strings, and the memory reserve map.
-
- - off_dt_struct
-
- This is an offset from the beginning of the header to the start
- of the "structure" part the device tree. (see 2) device tree)
-
- - off_dt_strings
-
- This is an offset from the beginning of the header to the start
- of the "strings" part of the device-tree
-
- - off_mem_rsvmap
-
- This is an offset from the beginning of the header to the start
- of the reserved memory map. This map is a list of pairs of 64-
- bit integers. Each pair is a physical address and a size. The
- list is terminated by an entry of size 0. This map provides the
- kernel with a list of physical memory areas that are "reserved"
- and thus not to be used for memory allocations, especially during
- early initialization. The kernel needs to allocate memory during
- boot for things like un-flattening the device-tree, allocating an
- MMU hash table, etc... Those allocations must be done in such a
- way to avoid overriding critical things like, on Open Firmware
- capable machines, the RTAS instance, or on some pSeries, the TCE
- tables used for the iommu. Typically, the reserve map should
- contain _at least_ this DT block itself (header,total_size). If
- you are passing an initrd to the kernel, you should reserve it as
- well. You do not need to reserve the kernel image itself. The map
- should be 64-bit aligned.
-
- - version
-
- This is the version of this structure. Version 1 stops
- here. Version 2 adds an additional field boot_cpuid_phys.
- Version 3 adds the size of the strings block, allowing the kernel
- to reallocate it easily at boot and free up the unused flattened
- structure after expansion. Version 16 introduces a new more
- "compact" format for the tree itself that is however not backward
- compatible. Version 17 adds an additional field, size_dt_struct,
- allowing it to be reallocated or moved more easily (this is
- particularly useful for bootloaders which need to make
- adjustments to a device tree based on probed information). You
- should always generate a structure of the highest version defined
- at the time of your implementation. Currently that is version 17,
- unless you explicitly aim at being backward compatible.
-
- - last_comp_version
-
- Last compatible version. This indicates down to what version of
- the DT block you are backward compatible. For example, version 2
- is backward compatible with version 1 (that is, a kernel build
- for version 1 will be able to boot with a version 2 format). You
- should put a 1 in this field if you generate a device tree of
- version 1 to 3, or 16 if you generate a tree of version 16 or 17
- using the new unit name format.
-
- - boot_cpuid_phys
-
- This field only exist on version 2 headers. It indicate which
- physical CPU ID is calling the kernel entry point. This is used,
- among others, by kexec. If you are on an SMP system, this value
- should match the content of the "reg" property of the CPU node in
- the device-tree corresponding to the CPU calling the kernel entry
- point (see further chapters for more information on the required
- device-tree contents)
-
- - size_dt_strings
-
- This field only exists on version 3 and later headers. It
- gives the size of the "strings" section of the device tree (which
- starts at the offset given by off_dt_strings).
-
- - size_dt_struct
-
- This field only exists on version 17 and later headers. It gives
- the size of the "structure" section of the device tree (which
- starts at the offset given by off_dt_struct).
-
- So the typical layout of a DT block (though the various parts don't
- need to be in that order) looks like this (addresses go from top to
- bottom):
-
-
- ------------------------------
- base -> | struct boot_param_header |
- ------------------------------
- | (alignment gap) (*) |
- ------------------------------
- | memory reserve map |
- ------------------------------
- | (alignment gap) |
- ------------------------------
- | |
- | device-tree structure |
- | |
- ------------------------------
- | (alignment gap) |
- ------------------------------
- | |
- | device-tree strings |
- | |
- -----> ------------------------------
- |
- |
- --- (base + totalsize)
-
- (*) The alignment gaps are not necessarily present; their presence
- and size are dependent on the various alignment requirements of
- the individual data blocks.
-
-
-2) Device tree generalities
----------------------------
-
-This device-tree itself is separated in two different blocks, a
-structure block and a strings block. Both need to be aligned to a 4
-byte boundary.
-
-First, let's quickly describe the device-tree concept before detailing
-the storage format. This chapter does _not_ describe the detail of the
-required types of nodes & properties for the kernel, this is done
-later in chapter III.
-
-The device-tree layout is strongly inherited from the definition of
-the Open Firmware IEEE 1275 device-tree. It's basically a tree of
-nodes, each node having two or more named properties. A property can
-have a value or not.
-
-It is a tree, so each node has one and only one parent except for the
-root node who has no parent.
-
-A node has 2 names. The actual node name is generally contained in a
-property of type "name" in the node property list whose value is a
-zero terminated string and is mandatory for version 1 to 3 of the
-format definition (as it is in Open Firmware). Version 16 makes it
-optional as it can generate it from the unit name defined below.
-
-There is also a "unit name" that is used to differentiate nodes with
-the same name at the same level, it is usually made of the node
-names, the "@" sign, and a "unit address", which definition is
-specific to the bus type the node sits on.
-
-The unit name doesn't exist as a property per-se but is included in
-the device-tree structure. It is typically used to represent "path" in
-the device-tree. More details about the actual format of these will be
-below.
-
-The kernel generic code does not make any formal use of the
-unit address (though some board support code may do) so the only real
-requirement here for the unit address is to ensure uniqueness of
-the node unit name at a given level of the tree. Nodes with no notion
-of address and no possible sibling of the same name (like /memory or
-/cpus) may omit the unit address in the context of this specification,
-or use the "@0" default unit address. The unit name is used to define
-a node "full path", which is the concatenation of all parent node
-unit names separated with "/".
-
-The root node doesn't have a defined name, and isn't required to have
-a name property either if you are using version 3 or earlier of the
-format. It also has no unit address (no @ symbol followed by a unit
-address). The root node unit name is thus an empty string. The full
-path to the root node is "/".
-
-Every node which actually represents an actual device (that is, a node
-which isn't only a virtual "container" for more nodes, like "/cpus"
-is) is also required to have a "compatible" property indicating the
-specific hardware and an optional list of devices it is fully
-backwards compatible with.
-
-Finally, every node that can be referenced from a property in another
-node is required to have either a "phandle" or a "linux,phandle"
-property. Real Open Firmware implementations provide a unique
-"phandle" value for every node that the "prom_init()" trampoline code
-turns into "linux,phandle" properties. However, this is made optional
-if the flattened device tree is used directly. An example of a node
-referencing another node via "phandle" is when laying out the
-interrupt tree which will be described in a further version of this
-document.
-
-The "phandle" property is a 32-bit value that uniquely
-identifies a node. You are free to use whatever values or system of
-values, internal pointers, or whatever to generate these, the only
-requirement is that every node for which you provide that property has
-a unique value for it.
-
-Here is an example of a simple device-tree. In this example, an "o"
-designates a node followed by the node unit name. Properties are
-presented with their name followed by their content. "content"
-represents an ASCII string (zero terminated) value, while <content>
-represents a 32-bit value, specified in decimal or hexadecimal (the
-latter prefixed 0x). The various nodes in this example will be
-discussed in a later chapter. At this point, it is only meant to give
-you a idea of what a device-tree looks like. I have purposefully kept
-the "name" and "linux,phandle" properties which aren't necessary in
-order to give you a better idea of what the tree looks like in
-practice.
-
- / o device-tree
- |- name = "device-tree"
- |- model = "MyBoardName"
- |- compatible = "MyBoardFamilyName"
- |- #address-cells = <2>
- |- #size-cells = <2>
- |- linux,phandle = <0>
- |
- o cpus
- | | - name = "cpus"
- | | - linux,phandle = <1>
- | | - #address-cells = <1>
- | | - #size-cells = <0>
- | |
- | o PowerPC,970@0
- | |- name = "PowerPC,970"
- | |- device_type = "cpu"
- | |- reg = <0>
- | |- clock-frequency = <0x5f5e1000>
- | |- 64-bit
- | |- linux,phandle = <2>
- |
- o memory@0
- | |- name = "memory"
- | |- device_type = "memory"
- | |- reg = <0x00000000 0x00000000 0x00000000 0x20000000>
- | |- linux,phandle = <3>
- |
- o chosen
- |- name = "chosen"
- |- bootargs = "root=/dev/sda2"
- |- linux,phandle = <4>
-
-This tree is almost a minimal tree. It pretty much contains the
-minimal set of required nodes and properties to boot a linux kernel;
-that is, some basic model information at the root, the CPUs, and the
-physical memory layout. It also includes misc information passed
-through /chosen, like in this example, the platform type (mandatory)
-and the kernel command line arguments (optional).
-
-The /cpus/PowerPC,970@0/64-bit property is an example of a
-property without a value. All other properties have a value. The
-significance of the #address-cells and #size-cells properties will be
-explained in chapter IV which defines precisely the required nodes and
-properties and their content.
-
-
-3) Device tree "structure" block
-
-The structure of the device tree is a linearized tree structure. The
-"OF_DT_BEGIN_NODE" token starts a new node, and the "OF_DT_END_NODE"
-ends that node definition. Child nodes are simply defined before
-"OF_DT_END_NODE" (that is nodes within the node). A 'token' is a 32
-bit value. The tree has to be "finished" with a OF_DT_END token
-
-Here's the basic structure of a single node:
-
- * token OF_DT_BEGIN_NODE (that is 0x00000001)
- * for version 1 to 3, this is the node full path as a zero
- terminated string, starting with "/". For version 16 and later,
- this is the node unit name only (or an empty string for the
- root node)
- * [align gap to next 4 bytes boundary]
- * for each property:
- * token OF_DT_PROP (that is 0x00000003)
- * 32-bit value of property value size in bytes (or 0 if no
- value)
- * 32-bit value of offset in string block of property name
- * property value data if any
- * [align gap to next 4 bytes boundary]
- * [child nodes if any]
- * token OF_DT_END_NODE (that is 0x00000002)
-
-So the node content can be summarized as a start token, a full path,
-a list of properties, a list of child nodes, and an end token. Every
-child node is a full node structure itself as defined above.
-
-NOTE: The above definition requires that all property definitions for
-a particular node MUST precede any subnode definitions for that node.
-Although the structure would not be ambiguous if properties and
-subnodes were intermingled, the kernel parser requires that the
-properties come first (up until at least 2.6.22). Any tools
-manipulating a flattened tree must take care to preserve this
-constraint.
-
-4) Device tree "strings" block
-
-In order to save space, property names, which are generally redundant,
-are stored separately in the "strings" block. This block is simply the
-whole bunch of zero terminated strings for all property names
-concatenated together. The device-tree property definitions in the
-structure block will contain offset values from the beginning of the
-strings block.
-
-
-III - Required content of the device tree
-=========================================
-
-WARNING: All "linux,*" properties defined in this document apply only
-to a flattened device-tree. If your platform uses a real
-implementation of Open Firmware or an implementation compatible with
-the Open Firmware client interface, those properties will be created
-by the trampoline code in the kernel's prom_init() file. For example,
-that's where you'll have to add code to detect your board model and
-set the platform number. However, when using the flattened device-tree
-entry point, there is no prom_init() pass, and thus you have to
-provide those properties yourself.
-
-
-1) Note about cells and address representation
-----------------------------------------------
-
-The general rule is documented in the various Open Firmware
-documentations. If you choose to describe a bus with the device-tree
-and there exist an OF bus binding, then you should follow the
-specification. However, the kernel does not require every single
-device or bus to be described by the device tree.
-
-In general, the format of an address for a device is defined by the
-parent bus type, based on the #address-cells and #size-cells
-properties. Note that the parent's parent definitions of #address-cells
-and #size-cells are not inherited so every node with children must specify
-them. The kernel requires the root node to have those properties defining
-addresses format for devices directly mapped on the processor bus.
-
-Those 2 properties define 'cells' for representing an address and a
-size. A "cell" is a 32-bit number. For example, if both contain 2
-like the example tree given above, then an address and a size are both
-composed of 2 cells, and each is a 64-bit number (cells are
-concatenated and expected to be in big endian format). Another example
-is the way Apple firmware defines them, with 2 cells for an address
-and one cell for a size. Most 32-bit implementations should define
-#address-cells and #size-cells to 1, which represents a 32-bit value.
-Some 32-bit processors allow for physical addresses greater than 32
-bits; these processors should define #address-cells as 2.
-
-"reg" properties are always a tuple of the type "address size" where
-the number of cells of address and size is specified by the bus
-#address-cells and #size-cells. When a bus supports various address
-spaces and other flags relative to a given address allocation (like
-prefetchable, etc...) those flags are usually added to the top level
-bits of the physical address. For example, a PCI physical address is
-made of 3 cells, the bottom two containing the actual address itself
-while the top cell contains address space indication, flags, and pci
-bus & device numbers.
-
-For buses that support dynamic allocation, it's the accepted practice
-to then not provide the address in "reg" (keep it 0) though while
-providing a flag indicating the address is dynamically allocated, and
-then, to provide a separate "assigned-addresses" property that
-contains the fully allocated addresses. See the PCI OF bindings for
-details.
-
-In general, a simple bus with no address space bits and no dynamic
-allocation is preferred if it reflects your hardware, as the existing
-kernel address parsing functions will work out of the box. If you
-define a bus type with a more complex address format, including things
-like address space bits, you'll have to add a bus translator to the
-prom_parse.c file of the recent kernels for your bus type.
-
-The "reg" property only defines addresses and sizes (if #size-cells is
-non-0) within a given bus. In order to translate addresses upward
-(that is into parent bus addresses, and possibly into CPU physical
-addresses), all buses must contain a "ranges" property. If the
-"ranges" property is missing at a given level, it's assumed that
-translation isn't possible, i.e., the registers are not visible on the
-parent bus. The format of the "ranges" property for a bus is a list
-of:
-
- bus address, parent bus address, size
-
-"bus address" is in the format of the bus this bus node is defining,
-that is, for a PCI bridge, it would be a PCI address. Thus, (bus
-address, size) defines a range of addresses for child devices. "parent
-bus address" is in the format of the parent bus of this bus. For
-example, for a PCI host controller, that would be a CPU address. For a
-PCI<->ISA bridge, that would be a PCI address. It defines the base
-address in the parent bus where the beginning of that range is mapped.
-
-For new 64-bit board support, I recommend either the 2/2 format or
-Apple's 2/1 format which is slightly more compact since sizes usually
-fit in a single 32-bit word. New 32-bit board support should use a
-1/1 format, unless the processor supports physical addresses greater
-than 32-bits, in which case a 2/1 format is recommended.
-
-Alternatively, the "ranges" property may be empty, indicating that the
-registers are visible on the parent bus using an identity mapping
-translation. In other words, the parent bus address space is the same
-as the child bus address space.
-
-2) Note about "compatible" properties
--------------------------------------
-
-These properties are optional, but recommended in devices and the root
-node. The format of a "compatible" property is a list of concatenated
-zero terminated strings. They allow a device to express its
-compatibility with a family of similar devices, in some cases,
-allowing a single driver to match against several devices regardless
-of their actual names.
-
-3) Note about "name" properties
--------------------------------
-
-While earlier users of Open Firmware like OldWorld macintoshes tended
-to use the actual device name for the "name" property, it's nowadays
-considered a good practice to use a name that is closer to the device
-class (often equal to device_type). For example, nowadays, Ethernet
-controllers are named "ethernet", an additional "model" property
-defining precisely the chip type/model, and "compatible" property
-defining the family in case a single driver can driver more than one
-of these chips. However, the kernel doesn't generally put any
-restriction on the "name" property; it is simply considered good
-practice to follow the standard and its evolutions as closely as
-possible.
-
-Note also that the new format version 16 makes the "name" property
-optional. If it's absent for a node, then the node's unit name is then
-used to reconstruct the name. That is, the part of the unit name
-before the "@" sign is used (or the entire unit name if no "@" sign
-is present).
-
-4) Note about node and property names and character set
--------------------------------------------------------
-
-While Open Firmware provides more flexible usage of 8859-1, this
-specification enforces more strict rules. Nodes and properties should
-be comprised only of ASCII characters 'a' to 'z', '0' to
-'9', ',', '.', '_', '+', '#', '?', and '-'. Node names additionally
-allow uppercase characters 'A' to 'Z' (property names should be
-lowercase. The fact that vendors like Apple don't respect this rule is
-irrelevant here). Additionally, node and property names should always
-begin with a character in the range 'a' to 'z' (or 'A' to 'Z' for node
-names).
-
-The maximum number of characters for both nodes and property names
-is 31. In the case of node names, this is only the leftmost part of
-a unit name (the pure "name" property), it doesn't include the unit
-address which can extend beyond that limit.
-
-
-5) Required nodes and properties
---------------------------------
- These are all that are currently required. However, it is strongly
- recommended that you expose PCI host bridges as documented in the
- PCI binding to Open Firmware, and your interrupt tree as documented
- in OF interrupt tree specification.
-
- a) The root node
-
- The root node requires some properties to be present:
-
- - model : this is your board name/model
- - #address-cells : address representation for "root" devices
- - #size-cells: the size representation for "root" devices
- - compatible : the board "family" generally finds its way here,
- for example, if you have 2 board models with a similar layout,
- that typically get driven by the same platform code in the
- kernel, you would specify the exact board model in the
- compatible property followed by an entry that represents the SoC
- model.
-
- The root node is also generally where you add additional properties
- specific to your board like the serial number if any, that sort of
- thing. It is recommended that if you add any "custom" property whose
- name may clash with standard defined ones, you prefix them with your
- vendor name and a comma.
-
- Additional properties for the root node:
-
- - serial-number : a string representing the device's serial number
-
- b) The /cpus node
-
- This node is the parent of all individual CPU nodes. It doesn't
- have any specific requirements, though it's generally good practice
- to have at least:
-
- #address-cells = <00000001>
- #size-cells = <00000000>
-
- This defines that the "address" for a CPU is a single cell, and has
- no meaningful size. This is not necessary but the kernel will assume
- that format when reading the "reg" properties of a CPU node, see
- below
-
- c) The /cpus/* nodes
-
- So under /cpus, you are supposed to create a node for every CPU on
- the machine. There is no specific restriction on the name of the
- CPU, though it's common to call it <architecture>,<core>. For
- example, Apple uses PowerPC,G5 while IBM uses PowerPC,970FX.
- However, the Generic Names convention suggests that it would be
- better to simply use 'cpu' for each cpu node and use the compatible
- property to identify the specific cpu core.
-
- Required properties:
-
- - device_type : has to be "cpu"
- - reg : This is the physical CPU number, it's a single 32-bit cell
- and is also used as-is as the unit number for constructing the
- unit name in the full path. For example, with 2 CPUs, you would
- have the full path:
- /cpus/PowerPC,970FX@0
- /cpus/PowerPC,970FX@1
- (unit addresses do not require leading zeroes)
- - d-cache-block-size : one cell, L1 data cache block size in bytes (*)
- - i-cache-block-size : one cell, L1 instruction cache block size in
- bytes
- - d-cache-size : one cell, size of L1 data cache in bytes
- - i-cache-size : one cell, size of L1 instruction cache in bytes
-
-(*) The cache "block" size is the size on which the cache management
-instructions operate. Historically, this document used the cache
-"line" size here which is incorrect. The kernel will prefer the cache
-block size and will fallback to cache line size for backward
-compatibility.
-
- Recommended properties:
-
- - timebase-frequency : a cell indicating the frequency of the
- timebase in Hz. This is not directly used by the generic code,
- but you are welcome to copy/paste the pSeries code for setting
- the kernel timebase/decrementer calibration based on this
- value.
- - clock-frequency : a cell indicating the CPU core clock frequency
- in Hz. A new property will be defined for 64-bit values, but if
- your frequency is < 4Ghz, one cell is enough. Here as well as
- for the above, the common code doesn't use that property, but
- you are welcome to re-use the pSeries or Maple one. A future
- kernel version might provide a common function for this.
- - d-cache-line-size : one cell, L1 data cache line size in bytes
- if different from the block size
- - i-cache-line-size : one cell, L1 instruction cache line size in
- bytes if different from the block size
-
- You are welcome to add any property you find relevant to your board,
- like some information about the mechanism used to soft-reset the
- CPUs. For example, Apple puts the GPIO number for CPU soft reset
- lines in there as a "soft-reset" property since they start secondary
- CPUs by soft-resetting them.
-
-
- d) the /memory node(s)
-
- To define the physical memory layout of your board, you should
- create one or more memory node(s). You can either create a single
- node with all memory ranges in its reg property, or you can create
- several nodes, as you wish. The unit address (@ part) used for the
- full path is the address of the first range of memory defined by a
- given node. If you use a single memory node, this will typically be
- @0.
-
- Required properties:
-
- - device_type : has to be "memory"
- - reg : This property contains all the physical memory ranges of
- your board. It's a list of addresses/sizes concatenated
- together, with the number of cells of each defined by the
- #address-cells and #size-cells of the root node. For example,
- with both of these properties being 2 like in the example given
- earlier, a 970 based machine with 6Gb of RAM could typically
- have a "reg" property here that looks like:
-
- 00000000 00000000 00000000 80000000
- 00000001 00000000 00000001 00000000
-
- That is a range starting at 0 of 0x80000000 bytes and a range
- starting at 0x100000000 and of 0x100000000 bytes. You can see
- that there is no memory covering the IO hole between 2Gb and
- 4Gb. Some vendors prefer splitting those ranges into smaller
- segments, but the kernel doesn't care.
-
- Additional properties:
-
- - hotpluggable : The presence of this property provides an explicit
- hint to the operating system that this memory may potentially be
- removed later. The kernel can take this into consideration when
- doing nonmovable allocations and when laying out memory zones.
-
- e) The /chosen node
-
- This node is a bit "special". Normally, that's where Open Firmware
- puts some variable environment information, like the arguments, or
- the default input/output devices.
-
- This specification makes a few of these mandatory, but also defines
- some linux-specific properties that would be normally constructed by
- the prom_init() trampoline when booting with an OF client interface,
- but that you have to provide yourself when using the flattened format.
-
- Recommended properties:
-
- - bootargs : This zero-terminated string is passed as the kernel
- command line
- - linux,stdout-path : This is the full path to your standard
- console device if any. Typically, if you have serial devices on
- your board, you may want to put the full path to the one set as
- the default console in the firmware here, for the kernel to pick
- it up as its own default console.
-
- Note that u-boot creates and fills in the chosen node for platforms
- that use it.
-
- (Note: a practice that is now obsolete was to include a property
- under /chosen called interrupt-controller which had a phandle value
- that pointed to the main interrupt controller)
-
- f) the /soc<SOCname> node
-
- This node is used to represent a system-on-a-chip (SoC) and must be
- present if the processor is a SoC. The top-level soc node contains
- information that is global to all devices on the SoC. The node name
- should contain a unit address for the SoC, which is the base address
- of the memory-mapped register set for the SoC. The name of an SoC
- node should start with "soc", and the remainder of the name should
- represent the part number for the soc. For example, the MPC8540's
- soc node would be called "soc8540".
-
- Required properties:
-
- - ranges : Should be defined as specified in 1) to describe the
- translation of SoC addresses for memory mapped SoC registers.
- - bus-frequency: Contains the bus frequency for the SoC node.
- Typically, the value of this field is filled in by the boot
- loader.
- - compatible : Exact model of the SoC
-
-
- Recommended properties:
-
- - reg : This property defines the address and size of the
- memory-mapped registers that are used for the SOC node itself.
- It does not include the child device registers - these will be
- defined inside each child node. The address specified in the
- "reg" property should match the unit address of the SOC node.
- - #address-cells : Address representation for "soc" devices. The
- format of this field may vary depending on whether or not the
- device registers are memory mapped. For memory mapped
- registers, this field represents the number of cells needed to
- represent the address of the registers. For SOCs that do not
- use MMIO, a special address format should be defined that
- contains enough cells to represent the required information.
- See 1) above for more details on defining #address-cells.
- - #size-cells : Size representation for "soc" devices
- - #interrupt-cells : Defines the width of cells used to represent
- interrupts. Typically this value is <2>, which includes a
- 32-bit number that represents the interrupt number, and a
- 32-bit number that represents the interrupt sense and level.
- This field is only needed if the SOC contains an interrupt
- controller.
-
- The SOC node may contain child nodes for each SOC device that the
- platform uses. Nodes should not be created for devices which exist
- on the SOC but are not used by a particular platform. See chapter VI
- for more information on how to specify devices that are part of a SOC.
-
- Example SOC node for the MPC8540:
-
- soc8540@e0000000 {
- #address-cells = <1>;
- #size-cells = <1>;
- #interrupt-cells = <2>;
- device_type = "soc";
- ranges = <0x00000000 0xe0000000 0x00100000>
- reg = <0xe0000000 0x00003000>;
- bus-frequency = <0>;
- }
-
-
-
-IV - "dtc", the device tree compiler
-====================================
-
-
-dtc source code can be found at
-<http://git.jdl.com/gitweb/?p=dtc.git>
-
-WARNING: This version is still in early development stage; the
-resulting device-tree "blobs" have not yet been validated with the
-kernel. The current generated block lacks a useful reserve map (it will
-be fixed to generate an empty one, it's up to the bootloader to fill
-it up) among others. The error handling needs work, bugs are lurking,
-etc...
-
-dtc basically takes a device-tree in a given format and outputs a
-device-tree in another format. The currently supported formats are:
-
- Input formats:
- -------------
-
- - "dtb": "blob" format, that is a flattened device-tree block
- with
- header all in a binary blob.
- - "dts": "source" format. This is a text file containing a
- "source" for a device-tree. The format is defined later in this
- chapter.
- - "fs" format. This is a representation equivalent to the
- output of /proc/device-tree, that is nodes are directories and
- properties are files
-
- Output formats:
- ---------------
-
- - "dtb": "blob" format
- - "dts": "source" format
- - "asm": assembly language file. This is a file that can be
- sourced by gas to generate a device-tree "blob". That file can
- then simply be added to your Makefile. Additionally, the
- assembly file exports some symbols that can be used.
-
-
-The syntax of the dtc tool is
-
- dtc [-I <input-format>] [-O <output-format>]
- [-o output-filename] [-V output_version] input_filename
-
-
-The "output_version" defines what version of the "blob" format will be
-generated. Supported versions are 1,2,3 and 16. The default is
-currently version 3 but that may change in the future to version 16.
-
-Additionally, dtc performs various sanity checks on the tree, like the
-uniqueness of linux, phandle properties, validity of strings, etc...
-
-The format of the .dts "source" file is "C" like, supports C and C++
-style comments.
-
-/ {
-}
-
-The above is the "device-tree" definition. It's the only statement
-supported currently at the toplevel.
-
-/ {
- property1 = "string_value"; /* define a property containing a 0
- * terminated string
- */
-
- property2 = <0x1234abcd>; /* define a property containing a
- * numerical 32-bit value (hexadecimal)
- */
-
- property3 = <0x12345678 0x12345678 0xdeadbeef>;
- /* define a property containing 3
- * numerical 32-bit values (cells) in
- * hexadecimal
- */
- property4 = [0x0a 0x0b 0x0c 0x0d 0xde 0xea 0xad 0xbe 0xef];
- /* define a property whose content is
- * an arbitrary array of bytes
- */
-
- childnode@address { /* define a child node named "childnode"
- * whose unit name is "childnode at
- * address"
- */
-
- childprop = "hello\n"; /* define a property "childprop" of
- * childnode (in this case, a string)
- */
- };
-};
-
-Nodes can contain other nodes etc... thus defining the hierarchical
-structure of the tree.
-
-Strings support common escape sequences from C: "\n", "\t", "\r",
-"\(octal value)", "\x(hex value)".
-
-It is also suggested that you pipe your source file through cpp (gcc
-preprocessor) so you can use #include's, #define for constants, etc...
-
-Finally, various options are planned but not yet implemented, like
-automatic generation of phandles, labels (exported to the asm file so
-you can point to a property content and change it easily from whatever
-you link the device-tree with), label or path instead of numeric value
-in some cells to "point" to a node (replaced by a phandle at compile
-time), export of reserve map address to the asm file, ability to
-specify reserve map content at compile time, etc...
-
-We may provide a .h include file with common definitions of that
-proves useful for some properties (like building PCI properties or
-interrupt maps) though it may be better to add a notion of struct
-definitions to the compiler...
-
-
-V - Recommendations for a bootloader
-====================================
-
-
-Here are some various ideas/recommendations that have been proposed
-while all this has been defined and implemented.
-
- - The bootloader may want to be able to use the device-tree itself
- and may want to manipulate it (to add/edit some properties,
- like physical memory size or kernel arguments). At this point, 2
- choices can be made. Either the bootloader works directly on the
- flattened format, or the bootloader has its own internal tree
- representation with pointers (similar to the kernel one) and
- re-flattens the tree when booting the kernel. The former is a bit
- more difficult to edit/modify, the later requires probably a bit
- more code to handle the tree structure. Note that the structure
- format has been designed so it's relatively easy to "insert"
- properties or nodes or delete them by just memmoving things
- around. It contains no internal offsets or pointers for this
- purpose.
-
- - An example of code for iterating nodes & retrieving properties
- directly from the flattened tree format can be found in the kernel
- file drivers/of/fdt.c. Look at the of_scan_flat_dt() function,
- its usage in early_init_devtree(), and the corresponding various
- early_init_dt_scan_*() callbacks. That code can be re-used in a
- GPL bootloader, and as the author of that code, I would be happy
- to discuss possible free licensing to any vendor who wishes to
- integrate all or part of this code into a non-GPL bootloader.
- (reference needed; who is 'I' here? ---gcl Jan 31, 2011)
-
-
-
-VI - System-on-a-chip devices and nodes
-=======================================
-
-Many companies are now starting to develop system-on-a-chip
-processors, where the processor core (CPU) and many peripheral devices
-exist on a single piece of silicon. For these SOCs, an SOC node
-should be used that defines child nodes for the devices that make
-up the SOC. While platforms are not required to use this model in
-order to boot the kernel, it is highly encouraged that all SOC
-implementations define as complete a flat-device-tree as possible to
-describe the devices on the SOC. This will allow for the
-genericization of much of the kernel code.
-
-
-1) Defining child nodes of an SOC
----------------------------------
-
-Each device that is part of an SOC may have its own node entry inside
-the SOC node. For each device that is included in the SOC, the unit
-address property represents the address offset for this device's
-memory-mapped registers in the parent's address space. The parent's
-address space is defined by the "ranges" property in the top-level soc
-node. The "reg" property for each node that exists directly under the
-SOC node should contain the address mapping from the child address space
-to the parent SOC address space and the size of the device's
-memory-mapped register file.
-
-For many devices that may exist inside an SOC, there are predefined
-specifications for the format of the device tree node. All SOC child
-nodes should follow these specifications, except where noted in this
-document.
-
-See appendix A for an example partial SOC node definition for the
-MPC8540.
-
-
-2) Representing devices without a current OF specification
-----------------------------------------------------------
-
-Currently, there are many devices on SoCs that do not have a standard
-representation defined as part of the Open Firmware specifications,
-mainly because the boards that contain these SoCs are not currently
-booted using Open Firmware. Binding documentation for new devices
-should be added to the Documentation/devicetree/bindings directory.
-That directory will expand as device tree support is added to more and
-more SoCs.
-
-
-VII - Specifying interrupt information for devices
-===================================================
-
-The device tree represents the buses and devices of a hardware
-system in a form similar to the physical bus topology of the
-hardware.
-
-In addition, a logical 'interrupt tree' exists which represents the
-hierarchy and routing of interrupts in the hardware.
-
-The interrupt tree model is fully described in the
-document "Open Firmware Recommended Practice: Interrupt
-Mapping Version 0.9". The document is available at:
-<http://www.devicetree.org/open-firmware/practice/>
-
-1) interrupts property
-----------------------
-
-Devices that generate interrupts to a single interrupt controller
-should use the conventional OF representation described in the
-OF interrupt mapping documentation.
-
-Each device which generates interrupts must have an 'interrupt'
-property. The interrupt property value is an arbitrary number of
-of 'interrupt specifier' values which describe the interrupt or
-interrupts for the device.
-
-The encoding of an interrupt specifier is determined by the
-interrupt domain in which the device is located in the
-interrupt tree. The root of an interrupt domain specifies in
-its #interrupt-cells property the number of 32-bit cells
-required to encode an interrupt specifier. See the OF interrupt
-mapping documentation for a detailed description of domains.
-
-For example, the binding for the OpenPIC interrupt controller
-specifies an #interrupt-cells value of 2 to encode the interrupt
-number and level/sense information. All interrupt children in an
-OpenPIC interrupt domain use 2 cells per interrupt in their interrupts
-property.
-
-The PCI bus binding specifies a #interrupt-cells value of 1 to encode
-which interrupt pin (INTA,INTB,INTC,INTD) is used.
-
-2) interrupt-parent property
-----------------------------
-
-The interrupt-parent property is specified to define an explicit
-link between a device node and its interrupt parent in
-the interrupt tree. The value of interrupt-parent is the
-phandle of the parent node.
-
-If the interrupt-parent property is not defined for a node, its
-interrupt parent is assumed to be an ancestor in the node's
-_device tree_ hierarchy.
-
-3) OpenPIC Interrupt Controllers
---------------------------------
-
-OpenPIC interrupt controllers require 2 cells to encode
-interrupt information. The first cell defines the interrupt
-number. The second cell defines the sense and level
-information.
-
-Sense and level information should be encoded as follows:
-
- 0 = low to high edge sensitive type enabled
- 1 = active low level sensitive type enabled
- 2 = active high level sensitive type enabled
- 3 = high to low edge sensitive type enabled
-
-4) ISA Interrupt Controllers
-----------------------------
-
-ISA PIC interrupt controllers require 2 cells to encode
-interrupt information. The first cell defines the interrupt
-number. The second cell defines the sense and level
-information.
-
-ISA PIC interrupt controllers should adhere to the ISA PIC
-encodings listed below:
-
- 0 = active low level sensitive type enabled
- 1 = active high level sensitive type enabled
- 2 = high to low edge sensitive type enabled
- 3 = low to high edge sensitive type enabled
-
-VIII - Specifying Device Power Management Information (sleep property)
-===================================================================
-
-Devices on SOCs often have mechanisms for placing devices into low-power
-states that are decoupled from the devices' own register blocks. Sometimes,
-this information is more complicated than a cell-index property can
-reasonably describe. Thus, each device controlled in such a manner
-may contain a "sleep" property which describes these connections.
-
-The sleep property consists of one or more sleep resources, each of
-which consists of a phandle to a sleep controller, followed by a
-controller-specific sleep specifier of zero or more cells.
-
-The semantics of what type of low power modes are possible are defined
-by the sleep controller. Some examples of the types of low power modes
-that may be supported are:
-
- - Dynamic: The device may be disabled or enabled at any time.
- - System Suspend: The device may request to be disabled or remain
- awake during system suspend, but will not be disabled until then.
- - Permanent: The device is disabled permanently (until the next hard
- reset).
-
-Some devices may share a clock domain with each other, such that they should
-only be suspended when none of the devices are in use. Where reasonable,
-such nodes should be placed on a virtual bus, where the bus has the sleep
-property. If the clock domain is shared among devices that cannot be
-reasonably grouped in this manner, then create a virtual sleep controller
-(similar to an interrupt nexus, except that defining a standardized
-sleep-map should wait until its necessity is demonstrated).
-
-IX - Specifying dma bus information
-
-Some devices may have DMA memory range shifted relatively to the beginning of
-RAM, or even placed outside of kernel RAM. For example, the Keystone 2 SoC
-worked in LPAE mode with 4G memory has:
-- RAM range: [0x8 0000 0000, 0x8 FFFF FFFF]
-- DMA range: [ 0x8000 0000, 0xFFFF FFFF]
-and DMA range is aliased into first 2G of RAM in HW.
-
-In such cases, DMA addresses translation should be performed between CPU phys
-and DMA addresses. The "dma-ranges" property is intended to be used
-for describing the configuration of such system in DT.
-
-In addition, each DMA master device on the DMA bus may or may not support
-coherent DMA operations. The "dma-coherent" property is intended to be used
-for identifying devices supported coherent DMA operations in DT.
-
-* DMA Bus master
-Optional property:
-- dma-ranges: <prop-encoded-array> encoded as arbitrary number of triplets of
- (child-bus-address, parent-bus-address, length). Each triplet specified
- describes a contiguous DMA address range.
- The dma-ranges property is used to describe the direct memory access (DMA)
- structure of a memory-mapped bus whose device tree parent can be accessed
- from DMA operations originating from the bus. It provides a means of
- defining a mapping or translation between the physical address space of
- the bus and the physical address space of the parent of the bus.
- (for more information see the Devicetree Specification)
-
-* DMA Bus child
-Optional property:
-- dma-ranges: <empty> value. if present - It means that DMA addresses
- translation has to be enabled for this device.
-- dma-coherent: Present if dma operations are coherent
-
-Example:
-soc {
- compatible = "ti,keystone","simple-bus";
- ranges = <0x0 0x0 0x0 0xc0000000>;
- dma-ranges = <0x80000000 0x8 0x00000000 0x80000000>;
-
- [...]
-
- usb: usb@2680000 {
- compatible = "ti,keystone-dwc3";
-
- [...]
- dma-coherent;
- };
-};
-
-Appendix A - Sample SOC node for MPC8540
-========================================
-
- soc@e0000000 {
- #address-cells = <1>;
- #size-cells = <1>;
- compatible = "fsl,mpc8540-ccsr", "simple-bus";
- device_type = "soc";
- ranges = <0x00000000 0xe0000000 0x00100000>
- bus-frequency = <0>;
- interrupt-parent = <&pic>;
-
- ethernet@24000 {
- #address-cells = <1>;
- #size-cells = <1>;
- device_type = "network";
- model = "TSEC";
- compatible = "gianfar", "simple-bus";
- reg = <0x24000 0x1000>;
- local-mac-address = [ 0x00 0xE0 0x0C 0x00 0x73 0x00 ];
- interrupts = <0x29 2 0x30 2 0x34 2>;
- phy-handle = <&phy0>;
- sleep = <&pmc 0x00000080>;
- ranges;
-
- mdio@24520 {
- reg = <0x24520 0x20>;
- compatible = "fsl,gianfar-mdio";
-
- phy0: ethernet-phy@0 {
- interrupts = <5 1>;
- reg = <0>;
- };
-
- phy1: ethernet-phy@1 {
- interrupts = <5 1>;
- reg = <1>;
- };
-
- phy3: ethernet-phy@3 {
- interrupts = <7 1>;
- reg = <3>;
- };
- };
- };
-
- ethernet@25000 {
- device_type = "network";
- model = "TSEC";
- compatible = "gianfar";
- reg = <0x25000 0x1000>;
- local-mac-address = [ 0x00 0xE0 0x0C 0x00 0x73 0x01 ];
- interrupts = <0x13 2 0x14 2 0x18 2>;
- phy-handle = <&phy1>;
- sleep = <&pmc 0x00000040>;
- };
-
- ethernet@26000 {
- device_type = "network";
- model = "FEC";
- compatible = "gianfar";
- reg = <0x26000 0x1000>;
- local-mac-address = [ 0x00 0xE0 0x0C 0x00 0x73 0x02 ];
- interrupts = <0x41 2>;
- phy-handle = <&phy3>;
- sleep = <&pmc 0x00000020>;
- };
-
- serial@4500 {
- #address-cells = <1>;
- #size-cells = <1>;
- compatible = "fsl,mpc8540-duart", "simple-bus";
- sleep = <&pmc 0x00000002>;
- ranges;
-
- serial@4500 {
- device_type = "serial";
- compatible = "ns16550";
- reg = <0x4500 0x100>;
- clock-frequency = <0>;
- interrupts = <0x42 2>;
- };
-
- serial@4600 {
- device_type = "serial";
- compatible = "ns16550";
- reg = <0x4600 0x100>;
- clock-frequency = <0>;
- interrupts = <0x42 2>;
- };
- };
-
- pic: pic@40000 {
- interrupt-controller;
- #address-cells = <0>;
- #interrupt-cells = <2>;
- reg = <0x40000 0x40000>;
- compatible = "chrp,open-pic";
- device_type = "open-pic";
- };
-
- i2c@3000 {
- interrupts = <0x43 2>;
- reg = <0x3000 0x100>;
- compatible = "fsl-i2c";
- dfsrr;
- sleep = <&pmc 0x00000004>;
- };
-
- pmc: power@e0070 {
- compatible = "fsl,mpc8540-pmc", "fsl,mpc8548-pmc";
- reg = <0xe0070 0x20>;
- };
- };
diff --git a/Documentation/devicetree/index.rst b/Documentation/devicetree/index.rst
index 5402676..d2a96e1 100644
--- a/Documentation/devicetree/index.rst
+++ b/Documentation/devicetree/index.rst
@@ -15,3 +15,4 @@
overlay-notes
bindings/index
+ booting-without-of
diff --git a/Documentation/devicetree/writing-schema.rst b/Documentation/devicetree/writing-schema.rst
index 220cf46..8c74a99 100644
--- a/Documentation/devicetree/writing-schema.rst
+++ b/Documentation/devicetree/writing-schema.rst
@@ -1,4 +1,4 @@
-:orphan:
+.. SPDX-License-Identifier: GPL-2.0
Writing DeviceTree Bindings in json-schema
==========================================
@@ -124,9 +124,12 @@
libyaml and its headers be installed on the host system. For some distributions
that involves installing the development package, such as:
-Debian:
+Debian::
+
apt-get install libyaml-dev
-Fedora:
+
+Fedora::
+
dnf -y install libyaml-devel
Running checks
diff --git a/Documentation/dontdiff b/Documentation/dontdiff
index ef9519c..e361fc9 100644
--- a/Documentation/dontdiff
+++ b/Documentation/dontdiff
@@ -55,6 +55,7 @@
*.ver
*.xml
*.xz
+*.zst
*_MODULES
*_vga16.c
*~
diff --git a/Documentation/driver-api/connector.rst b/Documentation/driver-api/connector.rst
index c100c74..23d06819 100644
--- a/Documentation/driver-api/connector.rst
+++ b/Documentation/driver-api/connector.rst
@@ -26,7 +26,7 @@
easier way::
int cn_add_callback(struct cb_id *id, char *name, void (*callback) (struct cn_msg *, struct netlink_skb_parms *));
- void cn_netlink_send_multi(struct cn_msg *msg, u16 len, u32 portid, u32 __group, int gfp_mask);
+ void cn_netlink_send_mult(struct cn_msg *msg, u16 len, u32 portid, u32 __group, int gfp_mask);
void cn_netlink_send(struct cn_msg *msg, u32 portid, u32 __group, int gfp_mask);
struct cb_id
@@ -48,7 +48,8 @@
__u32 seq;
__u32 ack;
- __u32 len; /* Length of the following data */
+ __u16 len; /* Length of the following data */
+ __u16 flags;
__u8 data[0];
};
diff --git a/Documentation/driver-api/device-io.rst b/Documentation/driver-api/device-io.rst
index 0e38937..7649638 100644
--- a/Documentation/driver-api/device-io.rst
+++ b/Documentation/driver-api/device-io.rst
@@ -36,14 +36,14 @@
This address should not be used directly. Instead, to get an address
suitable for passing to the accessor functions described below, you
-should call :c:func:`ioremap()`. An address suitable for accessing
+should call ioremap(). An address suitable for accessing
the device will be returned to you.
After you've finished using the device (say, in your module's exit
-routine), call :c:func:`iounmap()` in order to return the address
+routine), call iounmap() in order to return the address
space to the kernel. Most architectures allocate new address space each
-time you call :c:func:`ioremap()`, and they can run out unless you
-call :c:func:`iounmap()`.
+time you call ioremap(), and they can run out unless you
+call iounmap().
Accessing the device
--------------------
@@ -60,8 +60,8 @@
writeb(), writew(), writel() and writeq().
Some devices (such as framebuffers) would like to use larger transfers than
-8 bytes at a time. For these devices, the :c:func:`memcpy_toio()`,
-:c:func:`memcpy_fromio()` and :c:func:`memset_io()` functions are
+8 bytes at a time. For these devices, the memcpy_toio(),
+memcpy_fromio() and memset_io() functions are
provided. Do not use memset or memcpy on IO addresses; they are not
guaranteed to copy data in order.
@@ -135,15 +135,15 @@
Accesses to this space are provided through a set of functions which
allow 8-bit, 16-bit and 32-bit accesses; also known as byte, word and
-long. These functions are :c:func:`inb()`, :c:func:`inw()`,
-:c:func:`inl()`, :c:func:`outb()`, :c:func:`outw()` and
-:c:func:`outl()`.
+long. These functions are inb(), inw(),
+inl(), outb(), outw() and
+outl().
Some variants are provided for these functions. Some devices require
that accesses to their ports are slowed down. This functionality is
provided by appending a ``_p`` to the end of the function.
-There are also equivalents to memcpy. The :c:func:`ins()` and
-:c:func:`outs()` functions copy bytes, words or longs to the given
+There are also equivalents to memcpy. The ins() and
+outs() functions copy bytes, words or longs to the given
port.
Public Functions Provided
diff --git a/Documentation/driver-api/dma-buf.rst b/Documentation/driver-api/dma-buf.rst
index 63dec76..100bfd2 100644
--- a/Documentation/driver-api/dma-buf.rst
+++ b/Documentation/driver-api/dma-buf.rst
@@ -100,11 +100,11 @@
.. kernel-doc:: drivers/dma-buf/dma-buf.c
:doc: cpu access
-Fence Poll Support
-~~~~~~~~~~~~~~~~~~
+Implicit Fence Poll Support
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. kernel-doc:: drivers/dma-buf/dma-buf.c
- :doc: fence polling
+ :doc: implicit fence polling
Kernel Functions and Structures Reference
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -133,6 +133,18 @@
.. kernel-doc:: drivers/dma-buf/dma-fence.c
:doc: DMA fences overview
+DMA Fence Cross-Driver Contract
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. kernel-doc:: drivers/dma-buf/dma-fence.c
+ :doc: fence cross-driver contract
+
+DMA Fence Signalling Annotations
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. kernel-doc:: drivers/dma-buf/dma-fence.c
+ :doc: fence signalling annotation
+
DMA Fences Functions Reference
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -166,3 +178,73 @@
.. kernel-doc:: include/linux/sync_file.h
:internal:
+Indefinite DMA Fences
+~~~~~~~~~~~~~~~~~~~~
+
+At various times &dma_fence with an indefinite time until dma_fence_wait()
+finishes have been proposed. Examples include:
+
+* Future fences, used in HWC1 to signal when a buffer isn't used by the display
+ any longer, and created with the screen update that makes the buffer visible.
+ The time this fence completes is entirely under userspace's control.
+
+* Proxy fences, proposed to handle &drm_syncobj for which the fence has not yet
+ been set. Used to asynchronously delay command submission.
+
+* Userspace fences or gpu futexes, fine-grained locking within a command buffer
+ that userspace uses for synchronization across engines or with the CPU, which
+ are then imported as a DMA fence for integration into existing winsys
+ protocols.
+
+* Long-running compute command buffers, while still using traditional end of
+ batch DMA fences for memory management instead of context preemption DMA
+ fences which get reattached when the compute job is rescheduled.
+
+Common to all these schemes is that userspace controls the dependencies of these
+fences and controls when they fire. Mixing indefinite fences with normal
+in-kernel DMA fences does not work, even when a fallback timeout is included to
+protect against malicious userspace:
+
+* Only the kernel knows about all DMA fence dependencies, userspace is not aware
+ of dependencies injected due to memory management or scheduler decisions.
+
+* Only userspace knows about all dependencies in indefinite fences and when
+ exactly they will complete, the kernel has no visibility.
+
+Furthermore the kernel has to be able to hold up userspace command submission
+for memory management needs, which means we must support indefinite fences being
+dependent upon DMA fences. If the kernel also support indefinite fences in the
+kernel like a DMA fence, like any of the above proposal would, there is the
+potential for deadlocks.
+
+.. kernel-render:: DOT
+ :alt: Indefinite Fencing Dependency Cycle
+ :caption: Indefinite Fencing Dependency Cycle
+
+ digraph "Fencing Cycle" {
+ node [shape=box bgcolor=grey style=filled]
+ kernel [label="Kernel DMA Fences"]
+ userspace [label="userspace controlled fences"]
+ kernel -> userspace [label="memory management"]
+ userspace -> kernel [label="Future fence, fence proxy, ..."]
+
+ { rank=same; kernel userspace }
+ }
+
+This means that the kernel might accidentally create deadlocks
+through memory management dependencies which userspace is unaware of, which
+randomly hangs workloads until the timeout kicks in. Workloads, which from
+userspace's perspective, do not contain a deadlock. In such a mixed fencing
+architecture there is no single entity with knowledge of all dependencies.
+Thefore preventing such deadlocks from within the kernel is not possible.
+
+The only solution to avoid dependencies loops is by not allowing indefinite
+fences in the kernel. This means:
+
+* No future fences, proxy fences or userspace fences imported as DMA fences,
+ with or without a timeout.
+
+* No DMA fences that signal end of batchbuffer for command submission where
+ userspace is allowed to use userspace fencing or long running compute
+ workloads. This also means no implicit fencing for shared buffers in these
+ cases.
diff --git a/Documentation/driver-api/dmaengine/client.rst b/Documentation/driver-api/dmaengine/client.rst
index 2104830..09a3f66 100644
--- a/Documentation/driver-api/dmaengine/client.rst
+++ b/Documentation/driver-api/dmaengine/client.rst
@@ -5,7 +5,7 @@
Vinod Koul <vinod dot koul at intel.com>
.. note:: For DMA Engine usage in async_tx please see:
- ``Documentation/crypto/async-tx-api.txt``
+ ``Documentation/crypto/async-tx-api.rst``
Below is a guide to device driver writers on how to use the Slave-DMA API of the
@@ -86,7 +86,9 @@
- interleaved_dma: This is common to Slave as well as M2M clients. For slave
address of devices' fifo could be already known to the driver.
Various types of operations could be expressed by setting
- appropriate values to the 'dma_interleaved_template' members.
+ appropriate values to the 'dma_interleaved_template' members. Cyclic
+ interleaved DMA transfers are also possible if supported by the channel by
+ setting the DMA_PREP_REPEAT transfer flag.
A non-NULL return of this transfer API represents a "descriptor" for
the given transaction.
diff --git a/Documentation/driver-api/dmaengine/provider.rst b/Documentation/driver-api/dmaengine/provider.rst
index 56e5833..ddb0a81 100644
--- a/Documentation/driver-api/dmaengine/provider.rst
+++ b/Documentation/driver-api/dmaengine/provider.rst
@@ -95,7 +95,7 @@
ensure that it stayed compatible.
For more information on the Async TX API, please look the relevant
-documentation file in Documentation/crypto/async-tx-api.txt.
+documentation file in Documentation/crypto/async-tx-api.rst.
DMAEngine APIs
==============
@@ -239,6 +239,43 @@
want to transfer a portion of uncompressed data directly to the
display to print it
+- DMA_COMPLETION_NO_ORDER
+
+ - The device does not support in order completion.
+
+ - The driver should return DMA_OUT_OF_ORDER for device_tx_status if
+ the device is setting this capability.
+
+ - All cookie tracking and checking API should be treated as invalid if
+ the device exports this capability.
+
+ - At this point, this is incompatible with polling option for dmatest.
+
+ - If this cap is set, the user is recommended to provide an unique
+ identifier for each descriptor sent to the DMA device in order to
+ properly track the completion.
+
+- DMA_REPEAT
+
+ - The device supports repeated transfers. A repeated transfer, indicated by
+ the DMA_PREP_REPEAT transfer flag, is similar to a cyclic transfer in that
+ it gets automatically repeated when it ends, but can additionally be
+ replaced by the client.
+
+ - This feature is limited to interleaved transfers, this flag should thus not
+ be set if the DMA_INTERLEAVE flag isn't set. This limitation is based on
+ the current needs of DMA clients, support for additional transfer types
+ should be added in the future if and when the need arises.
+
+- DMA_LOAD_EOT
+
+ - The device supports replacing repeated transfers at end of transfer (EOT)
+ by queuing a new transfer with the DMA_PREP_LOAD_EOT flag set.
+
+ - Support for replacing a currently running transfer at another point (such
+ as end of burst instead of end of transfer) will be added in the future
+ based on DMA clients needs, if and when the need arises.
+
These various types will also affect how the source and destination
addresses change over time.
@@ -399,6 +436,9 @@
- In the case of a cyclic transfer, it should only take into
account the current period.
+ - Should return DMA_OUT_OF_ORDER if the device does not support in order
+ completion and is completing the operation out of order.
+
- This function can be called in an interrupt context.
- device_config
@@ -488,7 +528,7 @@
DMA_CTRL_ACK
- If clear, the descriptor cannot be reused by provider until the
- client acknowledges receipt, i.e. has has a chance to establish any
+ client acknowledges receipt, i.e. has a chance to establish any
dependency chains
- This can be acked by invoking async_tx_ack()
@@ -531,6 +571,34 @@
writes for which the descriptor should be in different format from
normal data descriptors.
+- DMA_PREP_REPEAT
+
+ - If set, the transfer will be automatically repeated when it ends until a
+ new transfer is queued on the same channel with the DMA_PREP_LOAD_EOT flag.
+ If the next transfer to be queued on the channel does not have the
+ DMA_PREP_LOAD_EOT flag set, the current transfer will be repeated until the
+ client terminates all transfers.
+
+ - This flag is only supported if the channel reports the DMA_REPEAT
+ capability.
+
+- DMA_PREP_LOAD_EOT
+
+ - If set, the transfer will replace the transfer currently being executed at
+ the end of the transfer.
+
+ - This is the default behaviour for non-repeated transfers, specifying
+ DMA_PREP_LOAD_EOT for non-repeated transfers will thus make no difference.
+
+ - When using repeated transfers, DMA clients will usually need to set the
+ DMA_PREP_LOAD_EOT flag on all transfers, otherwise the channel will keep
+ repeating the last repeated transfer and ignore the new transfers being
+ queued. Failure to set DMA_PREP_LOAD_EOT will appear as if the channel was
+ stuck on the previous transfer.
+
+ - This flag is only supported if the channel reports the DMA_LOAD_EOT
+ capability.
+
General Design Notes
====================
diff --git a/Documentation/driver-api/driver-model/devres.rst b/Documentation/driver-api/driver-model/devres.rst
index e0b58c3..eaaaafc 100644
--- a/Documentation/driver-api/driver-model/devres.rst
+++ b/Documentation/driver-api/driver-model/devres.rst
@@ -342,7 +342,8 @@
MDIO
devm_mdiobus_alloc()
devm_mdiobus_alloc_size()
- devm_mdiobus_free()
+ devm_mdiobus_register()
+ devm_of_mdiobus_register()
MEM
devm_free_pages()
diff --git a/Documentation/driver-api/driver-model/driver.rst b/Documentation/driver-api/driver-model/driver.rst
index 7d5040f..06f818b 100644
--- a/Documentation/driver-api/driver-model/driver.rst
+++ b/Documentation/driver-api/driver-model/driver.rst
@@ -228,8 +228,6 @@
not restricted to that. Use it whenever it makes sense to take an action after
all the consumers of a device have probed::
-::
-
int (*remove) (struct device *dev);
remove is called to unbind a driver from a device. This may be
diff --git a/Documentation/driver-api/driver-model/platform.rst b/Documentation/driver-api/driver-model/platform.rst
index 334dd40..1fe5c6c 100644
--- a/Documentation/driver-api/driver-model/platform.rst
+++ b/Documentation/driver-api/driver-model/platform.rst
@@ -108,7 +108,7 @@
Embedded systems frequently need one or more clocks for platform devices,
which are normally kept off until they're actively needed (to save power).
-System setup also associates those clocks with the device, so that that
+System setup also associates those clocks with the device, so that
calls to clk_get(&pdev->dev, clock_name) return them as needed.
diff --git a/Documentation/driver-api/early-userspace/early_userspace_support.rst b/Documentation/driver-api/early-userspace/early_userspace_support.rst
index 3deefb3..8a58c61 100644
--- a/Documentation/driver-api/early-userspace/early_userspace_support.rst
+++ b/Documentation/driver-api/early-userspace/early_userspace_support.rst
@@ -92,7 +92,7 @@
https://www.kernel.org/pub/linux/libs/klibc/
For active users, you are better off using the klibc git
-repository, at http://git.kernel.org/?p=libs/klibc/klibc.git
+repository, at https://git.kernel.org/?p=libs/klibc/klibc.git
The standalone klibc distribution currently provides three components,
in addition to the klibc library:
@@ -122,7 +122,7 @@
custom initramfs images that meet your needs exactly.
For questions and help, you can sign up for the early userspace
-mailing list at http://www.zytor.com/mailman/listinfo/klibc
+mailing list at https://www.zytor.com/mailman/listinfo/klibc
How does it work?
=================
diff --git a/Documentation/driver-api/firmware/built-in-fw.rst b/Documentation/driver-api/firmware/built-in-fw.rst
index 396cdf5..bc1c961 100644
--- a/Documentation/driver-api/firmware/built-in-fw.rst
+++ b/Documentation/driver-api/firmware/built-in-fw.rst
@@ -28,6 +28,6 @@
* Some firmware files may be really large in size. The remote-proc subsystem
is an example subsystem which deals with these sorts of firmware
* The firmware may need to be scraped out from some device specific location
- dynamically, an example is calibration data for for some WiFi chipsets. This
+ dynamically, an example is calibration data for some WiFi chipsets. This
calibration data can be unique per sold device.
diff --git a/Documentation/driver-api/firmware/direct-fs-lookup.rst b/Documentation/driver-api/firmware/direct-fs-lookup.rst
index 82b4d58..e04353d 100644
--- a/Documentation/driver-api/firmware/direct-fs-lookup.rst
+++ b/Documentation/driver-api/firmware/direct-fs-lookup.rst
@@ -24,7 +24,7 @@
however note that using initrd does not suffice to address the same race.
There are circumstances that justify not wanting to include firmware into
-initramfs, such as dealing with large firmware firmware files for the
+initramfs, such as dealing with large firmware files for the
remote-proc subsystem. For such cases using a userspace fallback mechanism
is currently the only viable solution as only userspace can know for sure
when the real rootfs is ready and mounted.
diff --git a/Documentation/driver-api/firmware/firmware_cache.rst b/Documentation/driver-api/firmware/firmware_cache.rst
index c2e69d9..417b9e8 100644
--- a/Documentation/driver-api/firmware/firmware_cache.rst
+++ b/Documentation/driver-api/firmware/firmware_cache.rst
@@ -27,7 +27,7 @@
uses all synchronous call except :c:func:`request_firmware_into_buf`.
* If an asynchronous call is used the firmware cache is only set up for a
- device if if the second argument (uevent) to request_firmware_nowait() is
+ device if the second argument (uevent) to request_firmware_nowait() is
true. When uevent is true it requests that a kobject uevent be sent to
userspace for the firmware request through the sysfs fallback mechanism
if the firmware file is not found.
diff --git a/Documentation/driver-api/firmware/request_firmware.rst b/Documentation/driver-api/firmware/request_firmware.rst
index cd07646..0d6ea03 100644
--- a/Documentation/driver-api/firmware/request_firmware.rst
+++ b/Documentation/driver-api/firmware/request_firmware.rst
@@ -76,5 +76,5 @@
the driver has the firmware image accessible in fw_entry->{data,size}.
If something went wrong request_firmware() returns non-zero and fw_entry
is set to NULL. Once your driver is done with processing the firmware it
-can call call release_firmware(fw_entry) to release the firmware image
+can call release_firmware(fw_entry) to release the firmware image
and any related resource.
diff --git a/Documentation/driver-api/generic-counter.rst b/Documentation/driver-api/generic-counter.rst
index e622f8f..b02c52c 100644
--- a/Documentation/driver-api/generic-counter.rst
+++ b/Documentation/driver-api/generic-counter.rst
@@ -262,7 +262,7 @@
Counter Counts may be allocated via counter_count structures, and
respective Counter Signal associations (Synapses) made via
counter_synapse structures. Associated counter_synapse structures are
-stored as an array and set to the the synapses array member of the
+stored as an array and set to the synapses array member of the
respective counter_count structure. These counter_count structures are
set to the counts array member of an allocated counter_device structure
before the Counter is registered to the system.
diff --git a/Documentation/driver-api/gpio/drivers-on-gpio.rst b/Documentation/driver-api/gpio/drivers-on-gpio.rst
index 820b403..41ec3cc 100644
--- a/Documentation/driver-api/gpio/drivers-on-gpio.rst
+++ b/Documentation/driver-api/gpio/drivers-on-gpio.rst
@@ -89,6 +89,13 @@
Consumer Electronics Control bus using only GPIO. It is used to communicate
with devices on the HDMI bus.
+- gpio-charger: drivers/power/supply/gpio-charger.c is used if you need to do
+ battery charging and all you have to go by to check the presence of the
+ AC charger or more complex tasks such as indicating charging status using
+ nothing but GPIO lines, this driver provides that and also a clearly defined
+ way to pass the charging parameters from hardware descriptions such as the
+ device tree.
+
Apart from this there are special GPIO drivers in subsystems like MMC/SD to
read card detect and write protect GPIO lines, and in the TTY serial subsystem
to emulate MCTRL (modem control) signals CTS/RTS by using two GPIO lines. The
diff --git a/Documentation/driver-api/i3c/protocol.rst b/Documentation/driver-api/i3c/protocol.rst
index dae3b6d..02653de 100644
--- a/Documentation/driver-api/i3c/protocol.rst
+++ b/Documentation/driver-api/i3c/protocol.rst
@@ -14,7 +14,7 @@
This document is just a brief introduction to the I3C protocol and the concepts
it brings to the table. If you need more information, please refer to the MIPI
I3C specification (can be downloaded here
-http://resources.mipi.org/mipi-i3c-v1-download).
+https://resources.mipi.org/mipi-i3c-v1-download).
Introduction
============
diff --git a/Documentation/driver-api/iio/buffers.rst b/Documentation/driver-api/iio/buffers.rst
index e9036ef9..dd64c9c 100644
--- a/Documentation/driver-api/iio/buffers.rst
+++ b/Documentation/driver-api/iio/buffers.rst
@@ -88,7 +88,7 @@
The driver implementing the accelerometer described above will have the
following channel definition::
- struct struct iio_chan_spec accel_channels[] = {
+ struct iio_chan_spec accel_channels[] = {
{
.type = IIO_ACCEL,
.modified = 1,
diff --git a/Documentation/driver-api/index.rst b/Documentation/driver-api/index.rst
index 6567187..902b93b 100644
--- a/Documentation/driver-api/index.rst
+++ b/Documentation/driver-api/index.rst
@@ -48,6 +48,7 @@
scsi
libata
target
+ mailbox
mtdnand
miscellaneous
mei/index
@@ -95,6 +96,7 @@
phy/index
pti_intel_mid
pwm
+ pldmfw/index
rfkill
serial/index
sm501
diff --git a/Documentation/driver-api/ipmi.rst b/Documentation/driver-api/ipmi.rst
index 5ef1047..bc281f1 100644
--- a/Documentation/driver-api/ipmi.rst
+++ b/Documentation/driver-api/ipmi.rst
@@ -18,7 +18,7 @@
This document describes how to use the IPMI driver for Linux. If you
are not familiar with IPMI itself, see the web site at
-http://www.intel.com/design/servers/ipmi/index.htm. IPMI is a big
+https://www.intel.com/design/servers/ipmi/index.htm. IPMI is a big
subject and I can't cover it all here!
Configuration
@@ -516,6 +516,7 @@
slave_addrs=<addr1>,<addr2>,...
tryacpi=[0|1] trydmi=[0|1]
[dbg_probe=1]
+ alerts_broken
The addresses are normal I2C addresses. The adapter is the string
name of the adapter, as shown in /sys/class/i2c-adapter/i2c-<n>/name.
@@ -537,6 +538,9 @@
usually 0x20 and the driver defaults to that, but in case it's not, it
can be specified when the driver starts up.
+alerts_broken does not enable SMBus alert for SSIF. Otherwise SMBus
+alert will be enabled on supported hardware.
+
Discovering the IPMI compliant BMC on the SMBus can cause devices on
the I2C bus to fail. The SMBus driver writes a "Get Device ID" IPMI
message as a block write to the I2C bus and waits for a response.
diff --git a/Documentation/mailbox.txt b/Documentation/driver-api/mailbox.rst
similarity index 100%
rename from Documentation/mailbox.txt
rename to Documentation/driver-api/mailbox.rst
diff --git a/Documentation/driver-api/media/drivers/pvrusb2.rst b/Documentation/driver-api/media/drivers/pvrusb2.rst
index 83bfaa5..cbd9359 100644
--- a/Documentation/driver-api/media/drivers/pvrusb2.rst
+++ b/Documentation/driver-api/media/drivers/pvrusb2.rst
@@ -20,7 +20,7 @@
here.
More information on this driver can be found at:
-http://www.isely.net/pvrusb2.html
+https://www.isely.net/pvrusb2.html
This driver has a strong separation of layers. They are very
diff --git a/Documentation/driver-api/media/drivers/tuners.rst b/Documentation/driver-api/media/drivers/tuners.rst
index 7509be8..d792414 100644
--- a/Documentation/driver-api/media/drivers/tuners.rst
+++ b/Documentation/driver-api/media/drivers/tuners.rst
@@ -18,7 +18,7 @@
Tuner Manufacturers
-------------------
-- SAMSUNG Tuner identification: (e.g. TCPM9091PD27)
+- Samsung Tuner identification: (e.g. TCPM9091PD27)
.. code-block:: none
diff --git a/Documentation/driver-api/media/v4l2-subdev.rst b/Documentation/driver-api/media/v4l2-subdev.rst
index 6e71f67..bc7e1fc 100644
--- a/Documentation/driver-api/media/v4l2-subdev.rst
+++ b/Documentation/driver-api/media/v4l2-subdev.rst
@@ -451,7 +451,7 @@
"module_foo", "chipid", 0x36, NULL);
This loads the given module (can be ``NULL`` if no module needs to be loaded)
-and calls :c:func:`i2c_new_device` with the given ``i2c_adapter`` and
+and calls :c:func:`i2c_new_client_device` with the given ``i2c_adapter`` and
chip/address arguments. If all goes well, then it registers the subdev with
the v4l2_device.
diff --git a/Documentation/driver-api/memory-devices/ti-gpmc.rst b/Documentation/driver-api/memory-devices/ti-gpmc.rst
index 33efcb8..b1bb868 100644
--- a/Documentation/driver-api/memory-devices/ti-gpmc.rst
+++ b/Documentation/driver-api/memory-devices/ti-gpmc.rst
@@ -14,7 +14,7 @@
* Pseudo-SRAM devices
GPMC is found on Texas Instruments SoC's (OMAP based)
-IP details: http://www.ti.com/lit/pdf/spruh73 section 7.1
+IP details: https://www.ti.com/lit/pdf/spruh73 section 7.1
GPMC generic timing calculation:
diff --git a/Documentation/driver-api/mmc/mmc-tools.rst b/Documentation/driver-api/mmc/mmc-tools.rst
index 5440609..a231e96 100644
--- a/Documentation/driver-api/mmc/mmc-tools.rst
+++ b/Documentation/driver-api/mmc/mmc-tools.rst
@@ -5,7 +5,7 @@
There is one MMC test tools called mmc-utils, which is maintained by Chris Ball,
you can find it at the below public git repository:
- http://git.kernel.org/cgit/linux/kernel/git/cjb/mmc-utils.git/
+ https://git.kernel.org/cgit/linux/kernel/git/cjb/mmc-utils.git/
Functions
=========
diff --git a/Documentation/driver-api/ntb.rst b/Documentation/driver-api/ntb.rst
index 87d1372da..11577c2 100644
--- a/Documentation/driver-api/ntb.rst
+++ b/Documentation/driver-api/ntb.rst
@@ -9,7 +9,7 @@
scratchpad and message registers. Scratchpad registers are read-and-writable
registers that are accessible from either side of the device, so that peers can
exchange a small amount of information at a fixed address. Message registers can
-be utilized for the same purpose. Additionally they are provided with with
+be utilized for the same purpose. Additionally they are provided with
special status bits to make sure the information isn't rewritten by another
peer. Doorbell registers provide a way for peers to send interrupt events.
Memory windows allow translated read and write access to the peer memory.
diff --git a/Documentation/driver-api/nvdimm/firmware-activate.rst b/Documentation/driver-api/nvdimm/firmware-activate.rst
new file mode 100644
index 0000000..7ee7dec
--- /dev/null
+++ b/Documentation/driver-api/nvdimm/firmware-activate.rst
@@ -0,0 +1,86 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+==================================
+NVDIMM Runtime Firmware Activation
+==================================
+
+Some persistent memory devices run a firmware locally on the device /
+"DIMM" to perform tasks like media management, capacity provisioning,
+and health monitoring. The process of updating that firmware typically
+involves a reboot because it has implications for in-flight memory
+transactions. However, reboots are disruptive and at least the Intel
+persistent memory platform implementation, described by the Intel ACPI
+DSM specification [1], has added support for activating firmware at
+runtime.
+
+A native sysfs interface is implemented in libnvdimm to allow platform
+to advertise and control their local runtime firmware activation
+capability.
+
+The libnvdimm bus object, ndbusX, implements an ndbusX/firmware/activate
+attribute that shows the state of the firmware activation as one of 'idle',
+'armed', 'overflow', and 'busy'.
+
+- idle:
+ No devices are set / armed to activate firmware
+
+- armed:
+ At least one device is armed
+
+- busy:
+ In the busy state armed devices are in the process of transitioning
+ back to idle and completing an activation cycle.
+
+- overflow:
+ If the platform has a concept of incremental work needed to perform
+ the activation it could be the case that too many DIMMs are armed for
+ activation. In that scenario the potential for firmware activation to
+ timeout is indicated by the 'overflow' state.
+
+The 'ndbusX/firmware/activate' property can be written with a value of
+either 'live', or 'quiesce'. A value of 'quiesce' triggers the kernel to
+run firmware activation from within the equivalent of the hibernation
+'freeze' state where drivers and applications are notified to stop their
+modifications of system memory. A value of 'live' attempts
+firmware activation without this hibernation cycle. The
+'ndbusX/firmware/activate' property will be elided completely if no
+firmware activation capability is detected.
+
+Another property 'ndbusX/firmware/capability' indicates a value of
+'live' or 'quiesce', where 'live' indicates that the firmware
+does not require or inflict any quiesce period on the system to update
+firmware. A capability value of 'quiesce' indicates that firmware does
+expect and injects a quiet period for the memory controller, but 'live'
+may still be written to 'ndbusX/firmware/activate' as an override to
+assume the risk of racing firmware update with in-flight device and
+application activity. The 'ndbusX/firmware/capability' property will be
+elided completely if no firmware activation capability is detected.
+
+The libnvdimm memory-device / DIMM object, nmemX, implements
+'nmemX/firmware/activate' and 'nmemX/firmware/result' attributes to
+communicate the per-device firmware activation state. Similar to the
+'ndbusX/firmware/activate' attribute, the 'nmemX/firmware/activate'
+attribute indicates 'idle', 'armed', or 'busy'. The state transitions
+from 'armed' to 'idle' when the system is prepared to activate firmware,
+firmware staged + state set to armed, and 'ndbusX/firmware/activate' is
+triggered. After that activation event the nmemX/firmware/result
+attribute reflects the state of the last activation as one of:
+
+- none:
+ No runtime activation triggered since the last time the device was reset
+
+- success:
+ The last runtime activation completed successfully.
+
+- fail:
+ The last runtime activation failed for device-specific reasons.
+
+- not_staged:
+ The last runtime activation failed due to a sequencing error of the
+ firmware image not being staged.
+
+- need_reset:
+ Runtime firmware activation failed, but the firmware can still be
+ activated via the legacy method of power-cycling the system.
+
+[1]: https://docs.pmem.io/persistent-memory/
diff --git a/Documentation/driver-api/nvdimm/nvdimm.rst b/Documentation/driver-api/nvdimm/nvdimm.rst
index 79c0fd3..ef6d59e 100644
--- a/Documentation/driver-api/nvdimm/nvdimm.rst
+++ b/Documentation/driver-api/nvdimm/nvdimm.rst
@@ -73,7 +73,7 @@
process address space.
DSM:
- Device Specific Method: ACPI method to to control specific
+ Device Specific Method: ACPI method to control specific
device - in this case the firmware.
DCR:
@@ -113,13 +113,13 @@
--------------------
ACPI 6:
- http://www.uefi.org/sites/default/files/resources/ACPI_6.0.pdf
+ https://www.uefi.org/sites/default/files/resources/ACPI_6.0.pdf
NVDIMM Namespace:
- http://pmem.io/documents/NVDIMM_Namespace_Spec.pdf
+ https://pmem.io/documents/NVDIMM_Namespace_Spec.pdf
DSM Interface Example:
- http://pmem.io/documents/NVDIMM_DSM_Interface_Example.pdf
+ https://pmem.io/documents/NVDIMM_DSM_Interface_Example.pdf
Driver Writer's Guide:
- http://pmem.io/documents/NVDIMM_Driver_Writers_Guide.pdf
+ https://pmem.io/documents/NVDIMM_Driver_Writers_Guide.pdf
Git Trees
---------
@@ -778,7 +778,7 @@
2. The term originated to describe the sub-devices that can be created
within a NVME controller (see the nvme specification:
- http://www.nvmexpress.org/specifications/), and NFIT namespaces are
+ https://www.nvmexpress.org/specifications/), and NFIT namespaces are
meant to parallel the capabilities and configurability of
NVME-namespaces.
@@ -786,7 +786,7 @@
LIBNVDIMM/LIBNDCTL: Block Translation Table "btt"
-------------------------------------------------
-A BTT (design document: http://pmem.io/2014/09/23/btt.html) is a stacked
+A BTT (design document: https://pmem.io/2014/09/23/btt.html) is a stacked
block device driver that fronts either the whole block device or a
partition of a block device emitted by either a PMEM or BLK NAMESPACE.
diff --git a/Documentation/driver-api/nvdimm/security.rst b/Documentation/driver-api/nvdimm/security.rst
index ad9dea0..7aab715 100644
--- a/Documentation/driver-api/nvdimm/security.rst
+++ b/Documentation/driver-api/nvdimm/security.rst
@@ -138,6 +138,6 @@
This command is only available when the master security is enabled, indicated
by the extended security status.
-[1]: http://pmem.io/documents/NVDIMM_DSM_Interface-V1.8.pdf
+[1]: https://pmem.io/documents/NVDIMM_DSM_Interface-V1.8.pdf
[2]: http://www.t13.org/documents/UploadedDocuments/docs2006/e05179r4-ACS-SecurityClarifications.pdf
diff --git a/Documentation/driver-api/pldmfw/driver-ops.rst b/Documentation/driver-api/pldmfw/driver-ops.rst
new file mode 100644
index 0000000..f065478
--- /dev/null
+++ b/Documentation/driver-api/pldmfw/driver-ops.rst
@@ -0,0 +1,56 @@
+.. SPDX-License-Identifier: GPL-2.0-only
+
+=========================
+Driver-specific callbacks
+=========================
+
+The ``pldmfw`` module relies on the device driver for implementing device
+specific behavior using the following operations.
+
+``.match_record``
+-----------------
+
+The ``.match_record`` operation is used to determine whether a given PLDM
+record matches the device being updated. This requires comparing the record
+descriptors in the record with information from the device. Many record
+descriptors are defined by the PLDM standard, but it is also allowed for
+devices to implement their own descriptors.
+
+The ``.match_record`` operation should return true if a given record matches
+the device.
+
+``.send_package_data``
+----------------------
+
+The ``.send_package_data`` operation is used to send the device-specific
+package data in a record to the device firmware. If the matching record
+provides package data, ``pldmfw`` will call the ``.send_package_data``
+function with a pointer to the package data and with the package data
+length. The device driver should send this data to firmware.
+
+``.send_component_table``
+-------------------------
+
+The ``.send_component_table`` operation is used to forward component
+information to the device. It is called once for each applicable component,
+that is, for each component indicated by the matching record. The
+device driver should send the component information to the device firmware,
+and wait for a response. The provided transfer flag indicates whether this
+is the first, last, or a middle component, and is expected to be forwarded
+to firmware as part of the component table information. The driver should an
+error in the case when the firmware indicates that the component cannot be
+updated, or return zero if the component can be updated.
+
+``.flash_component``
+--------------------
+
+The ``.flash_component`` operation is used to inform the device driver to
+flash a given component. The driver must perform any steps necessary to send
+the component data to the device.
+
+``.finalize_update``
+--------------------
+
+The ``.finalize_update`` operation is used by the ``pldmfw`` library in
+order to allow the device driver to perform any remaining device specific
+logic needed to finish the update.
diff --git a/Documentation/driver-api/pldmfw/file-format.rst b/Documentation/driver-api/pldmfw/file-format.rst
new file mode 100644
index 0000000..b7a9ceb
--- /dev/null
+++ b/Documentation/driver-api/pldmfw/file-format.rst
@@ -0,0 +1,203 @@
+.. SPDX-License-Identifier: GPL-2.0-only
+
+==================================
+PLDM Firmware file format overview
+==================================
+
+A PLDM firmware package is a binary file which contains a header that
+describes the contents of the firmware package. This includes an initial
+package header, one or more firmware records, and one or more components
+describing the actual flash contents to program.
+
+This diagram provides an overview of the file format::
+
+ overall file layout
+ +----------------------+
+ | |
+ | Package Header |
+ | |
+ +----------------------+
+ | |
+ | Device Records |
+ | |
+ +----------------------+
+ | |
+ | Component Info |
+ | |
+ +----------------------+
+ | |
+ | Package Header CRC |
+ | |
+ +----------------------+
+ | |
+ | Component Image 1 |
+ | |
+ +----------------------+
+ | |
+ | Component Image 2 |
+ | |
+ +----------------------+
+ | |
+ | ... |
+ | |
+ +----------------------+
+ | |
+ | Component Image N |
+ | |
+ +----------------------+
+
+Package Header
+==============
+
+The package header begins with the UUID of the PLDM file format, and
+contains information about the version of the format that the file uses. It
+also includes the total header size, a release date, the size of the
+component bitmap, and an overall package version.
+
+The following diagram provides an overview of the package header::
+
+ header layout
+ +-------------------------+
+ | PLDM UUID |
+ +-------------------------+
+ | Format Revision |
+ +-------------------------+
+ | Header Size |
+ +-------------------------+
+ | Release Date |
+ +-------------------------+
+ | Component Bitmap Length |
+ +-------------------------+
+ | Package Version Info |
+ +-------------------------+
+
+Device Records
+==============
+
+The device firmware records area starts with a count indicating the total
+number of records in the file, followed by each record. A single device
+record describes what device matches this record. All valid PLDM firmware
+files must contain at least one record, but optionally may contain more than
+one record if they support multiple devices.
+
+Each record will identify the device it supports via TLVs that describe the
+device, such as the PCI device and vendor information. It will also indicate
+which set of components that are used by this device. It is possible that
+only subset of provided components will be used by a given record. A record
+may also optionally contain device-specific package data that will be used
+by the device firmware during the update process.
+
+The following diagram provides an overview of the device record area::
+
+ area layout
+ +---------------+
+ | |
+ | Record Count |
+ | |
+ +---------------+
+ | |
+ | Record 1 |
+ | |
+ +---------------+
+ | |
+ | Record 2 |
+ | |
+ +---------------+
+ | |
+ | ... |
+ | |
+ +---------------+
+ | |
+ | Record N |
+ | |
+ +---------------+
+
+ record layout
+ +-----------------------+
+ | Record Length |
+ +-----------------------+
+ | Descriptor Count |
+ +-----------------------+
+ | Option Flags |
+ +-----------------------+
+ | Version Settings |
+ +-----------------------+
+ | Package Data Length |
+ +-----------------------+
+ | Applicable Components |
+ +-----------------------+
+ | Version String |
+ +-----------------------+
+ | Descriptor TLVs |
+ +-----------------------+
+ | Package Data |
+ +-----------------------+
+
+Component Info
+==============
+
+The component information area begins with a count of the number of
+components. Following this count is a description for each component. The
+component information points to the location in the file where the component
+data is stored, and includes version data used to identify the version of
+the component.
+
+The following diagram provides an overview of the component area::
+
+ area layout
+ +-----------------+
+ | |
+ | Component Count |
+ | |
+ +-----------------+
+ | |
+ | Component 1 |
+ | |
+ +-----------------+
+ | |
+ | Component 2 |
+ | |
+ +-----------------+
+ | |
+ | ... |
+ | |
+ +-----------------+
+ | |
+ | Component N |
+ | |
+ +-----------------+
+
+ component layout
+ +------------------------+
+ | Classification |
+ +------------------------+
+ | Component Identifier |
+ +------------------------+
+ | Comparison Stamp |
+ +------------------------+
+ | Component Options |
+ +------------------------+
+ | Activation Method |
+ +------------------------+
+ | Location Offset |
+ +------------------------+
+ | Component Size |
+ +------------------------+
+ | Component Version Info |
+ +------------------------+
+ | Package Data |
+ +------------------------+
+
+
+Package Header CRC
+==================
+
+Following the component information is a short 4-byte CRC calculated over
+the contents of all of the header information.
+
+Component Images
+================
+
+The component images follow the package header information in the PLDM
+firmware file. Each of these is simply a binary chunk with its start and
+size defined by the matching component structure in the component info area.
diff --git a/Documentation/driver-api/pldmfw/index.rst b/Documentation/driver-api/pldmfw/index.rst
new file mode 100644
index 0000000..ad2c33e
--- /dev/null
+++ b/Documentation/driver-api/pldmfw/index.rst
@@ -0,0 +1,72 @@
+.. SPDX-License-Identifier: GPL-2.0-only
+
+==================================
+PLDM Firmware Flash Update Library
+==================================
+
+``pldmfw`` implements functionality for updating the flash on a device using
+the PLDM for Firmware Update standard
+<https://www.dmtf.org/documents/pmci/pldm-firmware-update-specification-100>.
+
+.. toctree::
+ :maxdepth: 1
+
+ file-format
+ driver-ops
+
+==================================
+Overview of the ``pldmfw`` library
+==================================
+
+The ``pldmfw`` library is intended to be used by device drivers for
+implementing device flash update based on firmware files following the PLDM
+firwmare file format.
+
+It is implemented using an ops table that allows device drivers to provide
+the underlying device specific functionality.
+
+``pldmfw`` implements logic to parse the packed binary format of the PLDM
+firmware file into data structures, and then uses the provided function
+operations to determine if the firmware file is a match for the device. If
+so, it sends the record and component data to the firmware using the device
+specific implementations provided by device drivers. Once the device
+firmware indicates that the update may be performed, the firmware data is
+sent to the device for programming.
+
+Parsing the PLDM file
+=====================
+
+The PLDM file format uses packed binary data, with most multi-byte fields
+stored in the Little Endian format. Several pieces of data are variable
+length, including version strings and the number of records and components.
+Due to this, it is not straight forward to index the record, record
+descriptors, or components.
+
+To avoid proliferating access to the packed binary data, the ``pldmfw``
+library parses and extracts this data into simpler structures for ease of
+access.
+
+In order to safely process the firmware file, care is taken to avoid
+unaligned access of multi-byte fields, and to properly convert from Little
+Endian to CPU host format. Additionally the records, descriptors, and
+components are stored in linked lists.
+
+Performing a flash update
+=========================
+
+To perform a flash update, the ``pldmfw`` module performs the following
+steps
+
+1. Parse the firmware file for record and component information
+2. Scan through the records and determine if the device matches any record
+ in the file. The first matched record will be used.
+3. If the matching record provides package data, send this package data to
+ the device.
+4. For each component that the record indicates, send the component data to
+ the device. For each component, the firmware may respond with an
+ indication of whether the update is suitable or not. If any component is
+ not suitable, the update is canceled.
+5. For each component, send the binary data to the device firmware for
+ updating.
+6. After all components are programmed, perform any final device-specific
+ actions to finalize the update.
diff --git a/Documentation/driver-api/ptp.rst b/Documentation/driver-api/ptp.rst
index a15192e..664838a 100644
--- a/Documentation/driver-api/ptp.rst
+++ b/Documentation/driver-api/ptp.rst
@@ -23,6 +23,7 @@
+ Ancillary clock features
- Time stamp external events
- Period output signals configurable from user space
+ - Low Pass Filter (LPF) access from user space
- Synchronization of the Linux system time via the PPS subsystem
PTP hardware clock kernel API
@@ -94,3 +95,14 @@
- Auxiliary Slave/Master Mode Snapshot (optional interrupt)
- Target Time (optional interrupt)
+
+ * Renesas (IDT) ClockMatrix™
+
+ - Up to 4 independent PHC channels
+ - Integrated low pass filter (LPF), access via .adjPhase (compliant to ITU-T G.8273.2)
+ - Programmable output periodic signals
+ - Programmable inputs can time stamp external triggers
+ - Driver and/or hardware configuration through firmware (idtcm.bin)
+ - LPF settings (bandwidth, phase limiting, automatic holdover, physical layer assist (per ITU-T G.8273.2))
+ - Programmable output PTP clocks, any frequency up to 1GHz (to other PHY/MAC time stampers, refclk to ASSPs/SoCs/FPGAs)
+ - Lock to GNSS input, automatic switching between GNSS and user-space PHC control (optional)
diff --git a/Documentation/driver-api/rapidio/rapidio.rst b/Documentation/driver-api/rapidio/rapidio.rst
index fb8942d..74c552a 100644
--- a/Documentation/driver-api/rapidio/rapidio.rst
+++ b/Documentation/driver-api/rapidio/rapidio.rst
@@ -356,7 +356,7 @@
http://www.rapidio.org/education/technology_comparisons/
[3] RapidIO support for Linux.
- http://lwn.net/Articles/139118/
+ https://lwn.net/Articles/139118/
[4] Matt Porter. RapidIO for Linux. Ottawa Linux Symposium, 2005
- http://www.kernel.org/doc/ols/2005/ols2005v2-pages-43-56.pdf
+ https://www.kernel.org/doc/ols/2005/ols2005v2-pages-43-56.pdf
diff --git a/Documentation/driver-api/serial/n_gsm.rst b/Documentation/driver-api/serial/n_gsm.rst
index 286e7ff..87dfcd5 100644
--- a/Documentation/driver-api/serial/n_gsm.rst
+++ b/Documentation/driver-api/serial/n_gsm.rst
@@ -5,7 +5,7 @@
This line discipline implements the GSM 07.10 multiplexing protocol
detailed in the following 3GPP document:
- http://www.3gpp.org/ftp/Specs/archive/07_series/07.10/0710-720.zip
+ https://www.3gpp.org/ftp/Specs/archive/07_series/07.10/0710-720.zip
This document give some hints on how to use this driver with GPRS and 3G
modems connected to a physical serial port.
diff --git a/Documentation/driver-api/soundwire/stream.rst b/Documentation/driver-api/soundwire/stream.rst
index 1b38607..8858cea 100644
--- a/Documentation/driver-api/soundwire/stream.rst
+++ b/Documentation/driver-api/soundwire/stream.rst
@@ -293,6 +293,10 @@
int sdw_alloc_stream(char * stream_name);
+The SoundWire core provides a sdw_startup_stream() helper function,
+typically called during a dailink .startup() callback, which performs
+stream allocation and sets the stream pointer for all DAIs
+connected to a stream.
SDW_STREAM_CONFIGURED
~~~~~~~~~~~~~~~~~~~~~
@@ -509,7 +513,12 @@
void sdw_release_stream(struct sdw_stream_runtime * stream);
-Not Supported
+The SoundWire core provides a sdw_shutdown_stream() helper function,
+typically called during a dailink .shutdown() callback, which clears
+the stream pointer for all DAIS connected to a stream and releases the
+memory allocated for the stream.
+
+ Not Supported
=============
1. A single port with multiple channels supported cannot be used between two
diff --git a/Documentation/driver-api/thermal/cpu-idle-cooling.rst b/Documentation/driver-api/thermal/cpu-idle-cooling.rst
index b9f34ce..c2a7ca6 100644
--- a/Documentation/driver-api/thermal/cpu-idle-cooling.rst
+++ b/Documentation/driver-api/thermal/cpu-idle-cooling.rst
@@ -1,3 +1,5 @@
+.. SPDX-License-Identifier: GPL-2.0
+
================
CPU Idle Cooling
================
@@ -48,7 +50,7 @@
dynamic leakage for this period (modulo the energy needed to enter
this state). So the sustainable power with idle cycles has a linear
relation with the OPP’s sustainable power and can be computed with a
-coefficient similar to:
+coefficient similar to::
Power(IdleCycle) = Coef x Power(OPP)
@@ -139,7 +141,7 @@
--------------------
When we reach the thermal trip point, we have to sustain a specified
-power for a specific temperature but at this time we consume:
+power for a specific temperature but at this time we consume::
Power = Capacitance x Voltage^2 x Frequency x Utilisation
@@ -148,7 +150,7 @@
fixed value, ‘Voltage’ and the ‘Frequency’ are fixed artificially
because we don’t want to change the OPP. We can group the
‘Capacitance’ and the ‘Utilisation’ into a single term which is the
-‘Dynamic Power Coefficient (Cdyn)’ Simplifying the above, we have:
+‘Dynamic Power Coefficient (Cdyn)’ Simplifying the above, we have::
Pdyn = Cdyn x Voltage^2 x Frequency
@@ -157,7 +159,7 @@
tree. So with the idle injection mechanism, we want an average power
(Ptarget) resulting in an amount of time running at full power on a
specific OPP and idle another amount of time. That could be put in a
-equation:
+equation::
P(opp)target = ((Trunning x (P(opp)running) + (Tidle x P(opp)idle)) /
(Trunning + Tidle)
@@ -168,7 +170,7 @@
At this point if we know the running period for the CPU, that gives us
the idle injection we need. Alternatively if we have the idle
-injection duration, we can compute the running duration with:
+injection duration, we can compute the running duration with::
Trunning = Tidle / ((P(opp)running / P(opp)target) - 1)
@@ -191,7 +193,7 @@
target residency, otherwise we end up consuming more energy and
potentially invert the mitigation effect
-So the final equation is:
+So the final equation is::
Trunning = (Tidle - Twakeup ) x
(((P(opp)dyn + P(opp)static ) - P(opp)target) / P(opp)target )
diff --git a/Documentation/driver-api/thermal/nouveau_thermal.rst b/Documentation/driver-api/thermal/nouveau_thermal.rst
index 37255fd..79ece26 100644
--- a/Documentation/driver-api/thermal/nouveau_thermal.rst
+++ b/Documentation/driver-api/thermal/nouveau_thermal.rst
@@ -93,4 +93,4 @@
inquiries, please ping mupuf on IRC (#nouveau, freenode).
Bug reports should be filled on Freedesktop's bug tracker. Please follow
-http://nouveau.freedesktop.org/wiki/Bugs
+https://nouveau.freedesktop.org/wiki/Bugs
diff --git a/Documentation/driver-api/uio-howto.rst b/Documentation/driver-api/uio-howto.rst
index 84091cd..907ffa3 100644
--- a/Documentation/driver-api/uio-howto.rst
+++ b/Documentation/driver-api/uio-howto.rst
@@ -274,7 +274,7 @@
region, it will show up in the corresponding sysfs node.
- ``int memtype``: Required if the mapping is used. Set this to
- ``UIO_MEM_PHYS`` if you you have physical memory on your card to be
+ ``UIO_MEM_PHYS`` if you have physical memory on your card to be
mapped. Use ``UIO_MEM_LOGICAL`` for logical memory (e.g. allocated
with :c:func:`__get_free_pages()` but not kmalloc()). There's also
``UIO_MEM_VIRTUAL`` for virtual memory.
diff --git a/Documentation/driver-api/usb/URB.rst b/Documentation/driver-api/usb/URB.rst
index 61a54da..1e4abc8 100644
--- a/Documentation/driver-api/usb/URB.rst
+++ b/Documentation/driver-api/usb/URB.rst
@@ -240,7 +240,7 @@
======================================
Besides the fields present on a bulk transfer, for ISO, you also
-also have to set ``urb->interval`` to say how often to make transfers; it's
+have to set ``urb->interval`` to say how often to make transfers; it's
often one per frame (which is once every microframe for highspeed devices).
The actual interval used will be a power of two that's no bigger than what
you specify. You can use the :c:func:`usb_fill_int_urb` macro to fill
diff --git a/Documentation/driver-api/usb/dma.rst b/Documentation/driver-api/usb/dma.rst
index 59d5aee..2b3dbd3 100644
--- a/Documentation/driver-api/usb/dma.rst
+++ b/Documentation/driver-api/usb/dma.rst
@@ -10,7 +10,7 @@
The big picture is that USB drivers can continue to ignore most DMA issues,
though they still must provide DMA-ready buffers (see
-``Documentation/DMA-API-HOWTO.txt``). That's how they've worked through
+:doc:`/core-api/dma-api-howto`). That's how they've worked through
the 2.4 (and earlier) kernels, or they can now be DMA-aware.
DMA-aware usb drivers:
@@ -60,7 +60,7 @@
force a consistent memory access ordering by using memory barriers. It's
not using a streaming DMA mapping, so it's good for small transfers on
systems where the I/O would otherwise thrash an IOMMU mapping. (See
- ``Documentation/DMA-API-HOWTO.txt`` for definitions of "coherent" and
+ :doc:`/core-api/dma-api-howto` for definitions of "coherent" and
"streaming" DMA mappings.)
Asking for 1/Nth of a page (as well as asking for N pages) is reasonably
@@ -91,7 +91,7 @@
Existing buffers aren't usable for DMA without first being mapped into the
DMA address space of the device. However, most buffers passed to your
driver can safely be used with such DMA mapping. (See the first section
-of Documentation/DMA-API-HOWTO.txt, titled "What memory is DMA-able?")
+of :doc:`/core-api/dma-api-howto`, titled "What memory is DMA-able?")
- When you're using scatterlists, you can map everything at once. On some
systems, this kicks in an IOMMU and turns the scatterlists into single
diff --git a/Documentation/driver-api/usb/writing_usb_driver.rst b/Documentation/driver-api/usb/writing_usb_driver.rst
index 0b3d9ff..2176297 100644
--- a/Documentation/driver-api/usb/writing_usb_driver.rst
+++ b/Documentation/driver-api/usb/writing_usb_driver.rst
@@ -318,6 +318,6 @@
https://lore.kernel.org/linux-usb/
Programming Guide for Linux USB Device Drivers:
-http://lmu.web.psi.ch/docu/manuals/software_manuals/linux_sl/usb_linux_programming_guide.pdf
+https://lmu.web.psi.ch/docu/manuals/software_manuals/linux_sl/usb_linux_programming_guide.pdf
-USB Home Page: http://www.usb.org
+USB Home Page: https://www.usb.org
diff --git a/Documentation/driver-api/xillybus.rst b/Documentation/driver-api/xillybus.rst
index 2446ee3..a3ab832c 100644
--- a/Documentation/driver-api/xillybus.rst
+++ b/Documentation/driver-api/xillybus.rst
@@ -273,7 +273,7 @@
XILLYMSG_OPCODE_RELEASEBUF message channel 0 and sending an interrupt if
necessary). The host responds by making the data available for reading through
the character device. When all data has been read, the host writes on the
-the FPGA's buffer control register, allowing the buffer's overwriting. Flow
+FPGA's buffer control register, allowing the buffer's overwriting. Flow
control mechanisms exist on both sides to prevent underflows and overflows.
This is not good enough for creating a TCP/IP-like stream: If the data flow
diff --git a/Documentation/fault-injection/fault-injection.rst b/Documentation/fault-injection/fault-injection.rst
index f51bb21..f850ad0 100644
--- a/Documentation/fault-injection/fault-injection.rst
+++ b/Documentation/fault-injection/fault-injection.rst
@@ -24,7 +24,7 @@
injects disk IO errors on devices permitted by setting
/sys/block/<device>/make-it-fail or
- /sys/block/<device>/<partition>/make-it-fail. (generic_make_request())
+ /sys/block/<device>/<partition>/make-it-fail. (submit_bio_noacct())
- fail_mmc_request
diff --git a/Documentation/fb/ep93xx-fb.rst b/Documentation/fb/ep93xx-fb.rst
index 6f77679..1dd67f4 100644
--- a/Documentation/fb/ep93xx-fb.rst
+++ b/Documentation/fb/ep93xx-fb.rst
@@ -127,7 +127,7 @@
the VIDSCRNPAGE (framebuffer physical offset) to be tied low. There is
an unofficial errata for this bug at::
- http://marc.info/?l=linux-arm-kernel&m=110061245502000&w=2
+ https://marc.info/?l=linux-arm-kernel&m=110061245502000&w=2
By default the EP93xx framebuffer driver checks if the allocated physical
address has bit 27 set. If it does, then the memory is freed and an
diff --git a/Documentation/fb/modedb.rst b/Documentation/fb/modedb.rst
index 624d08f..4d2411e 100644
--- a/Documentation/fb/modedb.rst
+++ b/Documentation/fb/modedb.rst
@@ -152,7 +152,7 @@
video=<driver>:<xres>x<yres>[-<bpp>][@refresh]
where <driver> is a name from the table below. Valid default modes can be
-found in linux/drivers/video/modedb.c. Check your driver's documentation.
+found in drivers/video/fbdev/core/modedb.c. Check your driver's documentation.
There may be more modes::
Drivers that support modedb boot options
diff --git a/Documentation/features/core/cBPF-JIT/arch-support.txt b/Documentation/features/core/cBPF-JIT/arch-support.txt
index 8620c38..3999356 100644
--- a/Documentation/features/core/cBPF-JIT/arch-support.txt
+++ b/Documentation/features/core/cBPF-JIT/arch-support.txt
@@ -28,7 +28,6 @@
| sh: | TODO |
| sparc: | ok |
| um: | TODO |
- | unicore32: | TODO |
| x86: | TODO |
| xtensa: | TODO |
-----------------------
diff --git a/Documentation/features/core/eBPF-JIT/arch-support.txt b/Documentation/features/core/eBPF-JIT/arch-support.txt
index 9ed964f..79409bf 100644
--- a/Documentation/features/core/eBPF-JIT/arch-support.txt
+++ b/Documentation/features/core/eBPF-JIT/arch-support.txt
@@ -28,7 +28,6 @@
| sh: | TODO |
| sparc: | ok |
| um: | TODO |
- | unicore32: | TODO |
| x86: | ok |
| xtensa: | TODO |
-----------------------
diff --git a/Documentation/features/core/generic-idle-thread/arch-support.txt b/Documentation/features/core/generic-idle-thread/arch-support.txt
index 365df2c..9ea60e4 100644
--- a/Documentation/features/core/generic-idle-thread/arch-support.txt
+++ b/Documentation/features/core/generic-idle-thread/arch-support.txt
@@ -28,7 +28,6 @@
| sh: | ok |
| sparc: | ok |
| um: | TODO |
- | unicore32: | TODO |
| x86: | ok |
| xtensa: | ok |
-----------------------
diff --git a/Documentation/features/core/jump-labels/arch-support.txt b/Documentation/features/core/jump-labels/arch-support.txt
index 632a1c7..894d969 100644
--- a/Documentation/features/core/jump-labels/arch-support.txt
+++ b/Documentation/features/core/jump-labels/arch-support.txt
@@ -23,12 +23,11 @@
| openrisc: | TODO |
| parisc: | ok |
| powerpc: | ok |
- | riscv: | TODO |
+ | riscv: | ok |
| s390: | ok |
| sh: | TODO |
| sparc: | ok |
| um: | TODO |
- | unicore32: | TODO |
| x86: | ok |
| xtensa: | ok |
-----------------------
diff --git a/Documentation/features/core/tracehook/arch-support.txt b/Documentation/features/core/tracehook/arch-support.txt
index 9646670..cd3510e 100644
--- a/Documentation/features/core/tracehook/arch-support.txt
+++ b/Documentation/features/core/tracehook/arch-support.txt
@@ -28,7 +28,6 @@
| sh: | ok |
| sparc: | ok |
| um: | TODO |
- | unicore32: | TODO |
| x86: | ok |
| xtensa: | ok |
-----------------------
diff --git a/Documentation/features/debug/KASAN/arch-support.txt b/Documentation/features/debug/KASAN/arch-support.txt
index 6ff3854..c3fe9b2 100644
--- a/Documentation/features/debug/KASAN/arch-support.txt
+++ b/Documentation/features/debug/KASAN/arch-support.txt
@@ -28,7 +28,6 @@
| sh: | TODO |
| sparc: | TODO |
| um: | TODO |
- | unicore32: | TODO |
| x86: | ok |
| xtensa: | ok |
-----------------------
diff --git a/Documentation/features/debug/debug-vm-pgtable/arch-support.txt b/Documentation/features/debug/debug-vm-pgtable/arch-support.txt
index c527d05..53da483 100644
--- a/Documentation/features/debug/debug-vm-pgtable/arch-support.txt
+++ b/Documentation/features/debug/debug-vm-pgtable/arch-support.txt
@@ -23,12 +23,11 @@
| openrisc: | TODO |
| parisc: | TODO |
| powerpc: | ok |
- | riscv: | TODO |
+ | riscv: | ok |
| s390: | ok |
| sh: | TODO |
| sparc: | TODO |
| um: | TODO |
- | unicore32: | TODO |
| x86: | ok |
| xtensa: | TODO |
-----------------------
diff --git a/Documentation/features/debug/gcov-profile-all/arch-support.txt b/Documentation/features/debug/gcov-profile-all/arch-support.txt
index 210256f..7563a49 100644
--- a/Documentation/features/debug/gcov-profile-all/arch-support.txt
+++ b/Documentation/features/debug/gcov-profile-all/arch-support.txt
@@ -28,7 +28,6 @@
| sh: | ok |
| sparc: | TODO |
| um: | TODO |
- | unicore32: | TODO |
| x86: | ok |
| xtensa: | TODO |
-----------------------
diff --git a/Documentation/features/debug/kcov/arch-support.txt b/Documentation/features/debug/kcov/arch-support.txt
new file mode 100644
index 0000000..ab0ee1c9
--- /dev/null
+++ b/Documentation/features/debug/kcov/arch-support.txt
@@ -0,0 +1,33 @@
+#
+# Feature name: kcov
+# Kconfig: ARCH_HAS_KCOV
+# description: arch supports kcov for coverage-guided fuzzing
+#
+ -----------------------
+ | arch |status|
+ -----------------------
+ | alpha: | TODO |
+ | arc: | TODO |
+ | arm: | ok |
+ | arm64: | ok |
+ | c6x: | TODO |
+ | csky: | TODO |
+ | h8300: | TODO |
+ | hexagon: | TODO |
+ | ia64: | TODO |
+ | m68k: | TODO |
+ | microblaze: | TODO |
+ | mips: | ok |
+ | nds32: | TODO |
+ | nios2: | TODO |
+ | openrisc: | TODO |
+ | parisc: | TODO |
+ | powerpc: | ok |
+ | riscv: | ok |
+ | s390: | ok |
+ | sh: | TODO |
+ | sparc: | TODO |
+ | um: | ok |
+ | x86: | ok |
+ | xtensa: | TODO |
+ -----------------------
diff --git a/Documentation/features/debug/kgdb/arch-support.txt b/Documentation/features/debug/kgdb/arch-support.txt
index 38c40cf..bc45bac 100644
--- a/Documentation/features/debug/kgdb/arch-support.txt
+++ b/Documentation/features/debug/kgdb/arch-support.txt
@@ -23,12 +23,11 @@
| openrisc: | TODO |
| parisc: | ok |
| powerpc: | ok |
- | riscv: | TODO |
+ | riscv: | ok |
| s390: | TODO |
| sh: | ok |
| sparc: | ok |
| um: | TODO |
- | unicore32: | TODO |
| x86: | ok |
| xtensa: | TODO |
-----------------------
diff --git a/Documentation/features/debug/kmemleak/arch-support.txt b/Documentation/features/debug/kmemleak/arch-support.txt
new file mode 100644
index 0000000..2db7680
--- /dev/null
+++ b/Documentation/features/debug/kmemleak/arch-support.txt
@@ -0,0 +1,33 @@
+#
+# Feature name: kmemleak
+# Kconfig: HAVE_DEBUG_KMEMLEAK
+# description: arch supports the kernel memory leak detector
+#
+ -----------------------
+ | arch |status|
+ -----------------------
+ | alpha: | TODO |
+ | arc: | ok |
+ | arm: | ok |
+ | arm64: | ok |
+ | c6x: | TODO |
+ | csky: | TODO |
+ | h8300: | TODO |
+ | hexagon: | TODO |
+ | ia64: | TODO |
+ | m68k: | TODO |
+ | microblaze: | ok |
+ | mips: | ok |
+ | nds32: | ok |
+ | nios2: | TODO |
+ | openrisc: | TODO |
+ | parisc: | TODO |
+ | powerpc: | ok |
+ | riscv: | ok |
+ | s390: | ok |
+ | sh: | ok |
+ | sparc: | ok |
+ | um: | ok |
+ | x86: | ok |
+ | xtensa: | ok |
+ -----------------------
diff --git a/Documentation/features/debug/kprobes-on-ftrace/arch-support.txt b/Documentation/features/debug/kprobes-on-ftrace/arch-support.txt
index 97cd7aa..6225cfe 100644
--- a/Documentation/features/debug/kprobes-on-ftrace/arch-support.txt
+++ b/Documentation/features/debug/kprobes-on-ftrace/arch-support.txt
@@ -28,7 +28,6 @@
| sh: | TODO |
| sparc: | TODO |
| um: | TODO |
- | unicore32: | TODO |
| x86: | ok |
| xtensa: | TODO |
-----------------------
diff --git a/Documentation/features/debug/kprobes/arch-support.txt b/Documentation/features/debug/kprobes/arch-support.txt
index 8b316c6..371f0ac 100644
--- a/Documentation/features/debug/kprobes/arch-support.txt
+++ b/Documentation/features/debug/kprobes/arch-support.txt
@@ -28,7 +28,6 @@
| sh: | ok |
| sparc: | ok |
| um: | TODO |
- | unicore32: | TODO |
| x86: | ok |
| xtensa: | TODO |
-----------------------
diff --git a/Documentation/features/debug/kretprobes/arch-support.txt b/Documentation/features/debug/kretprobes/arch-support.txt
index b805aad..38e9525 100644
--- a/Documentation/features/debug/kretprobes/arch-support.txt
+++ b/Documentation/features/debug/kretprobes/arch-support.txt
@@ -28,7 +28,6 @@
| sh: | ok |
| sparc: | ok |
| um: | TODO |
- | unicore32: | TODO |
| x86: | ok |
| xtensa: | TODO |
-----------------------
diff --git a/Documentation/features/debug/optprobes/arch-support.txt b/Documentation/features/debug/optprobes/arch-support.txt
index fb297a8..7f4a20e6 100644
--- a/Documentation/features/debug/optprobes/arch-support.txt
+++ b/Documentation/features/debug/optprobes/arch-support.txt
@@ -28,7 +28,6 @@
| sh: | TODO |
| sparc: | TODO |
| um: | TODO |
- | unicore32: | TODO |
| x86: | ok |
| xtensa: | TODO |
-----------------------
diff --git a/Documentation/features/debug/stackprotector/arch-support.txt b/Documentation/features/debug/stackprotector/arch-support.txt
index 12410f6..3329559 100644
--- a/Documentation/features/debug/stackprotector/arch-support.txt
+++ b/Documentation/features/debug/stackprotector/arch-support.txt
@@ -23,12 +23,11 @@
| openrisc: | TODO |
| parisc: | TODO |
| powerpc: | ok |
- | riscv: | TODO |
+ | riscv: | ok |
| s390: | TODO |
| sh: | ok |
| sparc: | TODO |
| um: | TODO |
- | unicore32: | TODO |
| x86: | ok |
| xtensa: | ok |
-----------------------
diff --git a/Documentation/features/debug/uprobes/arch-support.txt b/Documentation/features/debug/uprobes/arch-support.txt
index be8acbb..43cac6e 100644
--- a/Documentation/features/debug/uprobes/arch-support.txt
+++ b/Documentation/features/debug/uprobes/arch-support.txt
@@ -28,7 +28,6 @@
| sh: | TODO |
| sparc: | ok |
| um: | TODO |
- | unicore32: | TODO |
| x86: | ok |
| xtensa: | TODO |
-----------------------
diff --git a/Documentation/features/debug/user-ret-profiler/arch-support.txt b/Documentation/features/debug/user-ret-profiler/arch-support.txt
index 6bfa36b..d636ed0 100644
--- a/Documentation/features/debug/user-ret-profiler/arch-support.txt
+++ b/Documentation/features/debug/user-ret-profiler/arch-support.txt
@@ -28,7 +28,6 @@
| sh: | TODO |
| sparc: | TODO |
| um: | TODO |
- | unicore32: | TODO |
| x86: | ok |
| xtensa: | TODO |
-----------------------
diff --git a/Documentation/features/io/dma-contiguous/arch-support.txt b/Documentation/features/io/dma-contiguous/arch-support.txt
index 895c3b0..dfc93d0 100644
--- a/Documentation/features/io/dma-contiguous/arch-support.txt
+++ b/Documentation/features/io/dma-contiguous/arch-support.txt
@@ -28,7 +28,6 @@
| sh: | TODO |
| sparc: | TODO |
| um: | TODO |
- | unicore32: | TODO |
| x86: | ok |
| xtensa: | ok |
-----------------------
diff --git a/Documentation/features/locking/cmpxchg-local/arch-support.txt b/Documentation/features/locking/cmpxchg-local/arch-support.txt
index 242ff5a..1815c7f 100644
--- a/Documentation/features/locking/cmpxchg-local/arch-support.txt
+++ b/Documentation/features/locking/cmpxchg-local/arch-support.txt
@@ -28,7 +28,6 @@
| sh: | TODO |
| sparc: | TODO |
| um: | TODO |
- | unicore32: | TODO |
| x86: | ok |
| xtensa: | TODO |
-----------------------
diff --git a/Documentation/features/locking/lockdep/arch-support.txt b/Documentation/features/locking/lockdep/arch-support.txt
index 98cb9d8..940b0bd 100644
--- a/Documentation/features/locking/lockdep/arch-support.txt
+++ b/Documentation/features/locking/lockdep/arch-support.txt
@@ -23,12 +23,11 @@
| openrisc: | ok |
| parisc: | TODO |
| powerpc: | ok |
- | riscv: | TODO |
+ | riscv: | ok |
| s390: | ok |
| sh: | ok |
| sparc: | ok |
| um: | ok |
- | unicore32: | ok |
| x86: | ok |
| xtensa: | ok |
-----------------------
diff --git a/Documentation/features/locking/queued-rwlocks/arch-support.txt b/Documentation/features/locking/queued-rwlocks/arch-support.txt
index ee92274..5c6bcfc 100644
--- a/Documentation/features/locking/queued-rwlocks/arch-support.txt
+++ b/Documentation/features/locking/queued-rwlocks/arch-support.txt
@@ -28,7 +28,6 @@
| sh: | TODO |
| sparc: | ok |
| um: | TODO |
- | unicore32: | TODO |
| x86: | ok |
| xtensa: | ok |
-----------------------
diff --git a/Documentation/features/locking/queued-spinlocks/arch-support.txt b/Documentation/features/locking/queued-spinlocks/arch-support.txt
index c52116c..b55e420 100644
--- a/Documentation/features/locking/queued-spinlocks/arch-support.txt
+++ b/Documentation/features/locking/queued-spinlocks/arch-support.txt
@@ -28,7 +28,6 @@
| sh: | TODO |
| sparc: | ok |
| um: | TODO |
- | unicore32: | TODO |
| x86: | ok |
| xtensa: | ok |
-----------------------
diff --git a/Documentation/features/perf/kprobes-event/arch-support.txt b/Documentation/features/perf/kprobes-event/arch-support.txt
index 518f352..04c17c2 100644
--- a/Documentation/features/perf/kprobes-event/arch-support.txt
+++ b/Documentation/features/perf/kprobes-event/arch-support.txt
@@ -28,7 +28,6 @@
| sh: | ok |
| sparc: | ok |
| um: | TODO |
- | unicore32: | TODO |
| x86: | ok |
| xtensa: | TODO |
-----------------------
diff --git a/Documentation/features/perf/perf-regs/arch-support.txt b/Documentation/features/perf/perf-regs/arch-support.txt
index c22cd6f..e7450fbb 100644
--- a/Documentation/features/perf/perf-regs/arch-support.txt
+++ b/Documentation/features/perf/perf-regs/arch-support.txt
@@ -28,7 +28,6 @@
| sh: | TODO |
| sparc: | TODO |
| um: | TODO |
- | unicore32: | TODO |
| x86: | ok |
| xtensa: | TODO |
-----------------------
diff --git a/Documentation/features/perf/perf-stackdump/arch-support.txt b/Documentation/features/perf/perf-stackdump/arch-support.txt
index 527fe4d..98e79d1 100644
--- a/Documentation/features/perf/perf-stackdump/arch-support.txt
+++ b/Documentation/features/perf/perf-stackdump/arch-support.txt
@@ -28,7 +28,6 @@
| sh: | TODO |
| sparc: | TODO |
| um: | TODO |
- | unicore32: | TODO |
| x86: | ok |
| xtensa: | TODO |
-----------------------
diff --git a/Documentation/features/sched/membarrier-sync-core/arch-support.txt b/Documentation/features/sched/membarrier-sync-core/arch-support.txt
index 8a521a6..47e6903 100644
--- a/Documentation/features/sched/membarrier-sync-core/arch-support.txt
+++ b/Documentation/features/sched/membarrier-sync-core/arch-support.txt
@@ -5,7 +5,7 @@
#
# Architecture requirements
#
-# * arm/arm64
+# * arm/arm64/powerpc
#
# Rely on implicit context synchronization as a result of exception return
# when returning from IPI handler, and when returning to user-space.
@@ -45,13 +45,12 @@
| nios2: | TODO |
| openrisc: | TODO |
| parisc: | TODO |
- | powerpc: | TODO |
+ | powerpc: | ok |
| riscv: | TODO |
| s390: | TODO |
| sh: | TODO |
| sparc: | TODO |
| um: | TODO |
- | unicore32: | TODO |
| x86: | ok |
| xtensa: | TODO |
-----------------------
diff --git a/Documentation/features/sched/numa-balancing/arch-support.txt b/Documentation/features/sched/numa-balancing/arch-support.txt
index 3508236..964457a 100644
--- a/Documentation/features/sched/numa-balancing/arch-support.txt
+++ b/Documentation/features/sched/numa-balancing/arch-support.txt
@@ -28,7 +28,6 @@
| sh: | .. |
| sparc: | TODO |
| um: | .. |
- | unicore32: | .. |
| x86: | ok |
| xtensa: | .. |
-----------------------
diff --git a/Documentation/features/seccomp/seccomp-filter/arch-support.txt b/Documentation/features/seccomp/seccomp-filter/arch-support.txt
index c7b837f..c688aba 100644
--- a/Documentation/features/seccomp/seccomp-filter/arch-support.txt
+++ b/Documentation/features/seccomp/seccomp-filter/arch-support.txt
@@ -28,7 +28,6 @@
| sh: | TODO |
| sparc: | TODO |
| um: | ok |
- | unicore32: | TODO |
| x86: | ok |
- | xtensa: | TODO |
+ | xtensa: | ok |
-----------------------
diff --git a/Documentation/features/time/arch-tick-broadcast/arch-support.txt b/Documentation/features/time/arch-tick-broadcast/arch-support.txt
index 593536f7..4d11cbb 100644
--- a/Documentation/features/time/arch-tick-broadcast/arch-support.txt
+++ b/Documentation/features/time/arch-tick-broadcast/arch-support.txt
@@ -28,7 +28,6 @@
| sh: | ok |
| sparc: | TODO |
| um: | TODO |
- | unicore32: | TODO |
| x86: | TODO |
| xtensa: | TODO |
-----------------------
diff --git a/Documentation/features/time/clockevents/arch-support.txt b/Documentation/features/time/clockevents/arch-support.txt
index 7a27157..8287b6a 100644
--- a/Documentation/features/time/clockevents/arch-support.txt
+++ b/Documentation/features/time/clockevents/arch-support.txt
@@ -28,7 +28,6 @@
| sh: | ok |
| sparc: | ok |
| um: | ok |
- | unicore32: | ok |
| x86: | ok |
| xtensa: | ok |
-----------------------
diff --git a/Documentation/features/time/context-tracking/arch-support.txt b/Documentation/features/time/context-tracking/arch-support.txt
index 048bfb6..266c81e 100644
--- a/Documentation/features/time/context-tracking/arch-support.txt
+++ b/Documentation/features/time/context-tracking/arch-support.txt
@@ -23,12 +23,11 @@
| openrisc: | TODO |
| parisc: | TODO |
| powerpc: | ok |
- | riscv: | TODO |
+ | riscv: | ok |
| s390: | TODO |
| sh: | TODO |
| sparc: | ok |
| um: | TODO |
- | unicore32: | TODO |
| x86: | ok |
| xtensa: | TODO |
-----------------------
diff --git a/Documentation/features/time/irq-time-acct/arch-support.txt b/Documentation/features/time/irq-time-acct/arch-support.txt
index a14bbad..d9082b9 100644
--- a/Documentation/features/time/irq-time-acct/arch-support.txt
+++ b/Documentation/features/time/irq-time-acct/arch-support.txt
@@ -28,7 +28,6 @@
| sh: | TODO |
| sparc: | .. |
| um: | TODO |
- | unicore32: | TODO |
| x86: | ok |
| xtensa: | ok |
-----------------------
diff --git a/Documentation/features/time/modern-timekeeping/arch-support.txt b/Documentation/features/time/modern-timekeeping/arch-support.txt
index 1d46da1..a84c3b9 100644
--- a/Documentation/features/time/modern-timekeeping/arch-support.txt
+++ b/Documentation/features/time/modern-timekeeping/arch-support.txt
@@ -28,7 +28,6 @@
| sh: | ok |
| sparc: | ok |
| um: | ok |
- | unicore32: | ok |
| x86: | ok |
| xtensa: | ok |
-----------------------
diff --git a/Documentation/features/time/virt-cpuacct/arch-support.txt b/Documentation/features/time/virt-cpuacct/arch-support.txt
index fb0d0ca..56b372d 100644
--- a/Documentation/features/time/virt-cpuacct/arch-support.txt
+++ b/Documentation/features/time/virt-cpuacct/arch-support.txt
@@ -28,7 +28,6 @@
| sh: | TODO |
| sparc: | ok |
| um: | TODO |
- | unicore32: | TODO |
| x86: | ok |
| xtensa: | TODO |
-----------------------
diff --git a/Documentation/features/vm/ELF-ASLR/arch-support.txt b/Documentation/features/vm/ELF-ASLR/arch-support.txt
index adc2587..eccda07 100644
--- a/Documentation/features/vm/ELF-ASLR/arch-support.txt
+++ b/Documentation/features/vm/ELF-ASLR/arch-support.txt
@@ -28,7 +28,6 @@
| sh: | TODO |
| sparc: | TODO |
| um: | TODO |
- | unicore32: | TODO |
| x86: | ok |
| xtensa: | TODO |
-----------------------
diff --git a/Documentation/features/vm/PG_uncached/arch-support.txt b/Documentation/features/vm/PG_uncached/arch-support.txt
index f05588f..c74e3f8 100644
--- a/Documentation/features/vm/PG_uncached/arch-support.txt
+++ b/Documentation/features/vm/PG_uncached/arch-support.txt
@@ -28,7 +28,6 @@
| sh: | TODO |
| sparc: | TODO |
| um: | TODO |
- | unicore32: | TODO |
| x86: | ok |
| xtensa: | TODO |
-----------------------
diff --git a/Documentation/features/vm/THP/arch-support.txt b/Documentation/features/vm/THP/arch-support.txt
index cdfe892..1c0b95f 100644
--- a/Documentation/features/vm/THP/arch-support.txt
+++ b/Documentation/features/vm/THP/arch-support.txt
@@ -28,7 +28,6 @@
| sh: | .. |
| sparc: | ok |
| um: | .. |
- | unicore32: | .. |
| x86: | ok |
| xtensa: | .. |
-----------------------
diff --git a/Documentation/features/vm/TLB/arch-support.txt b/Documentation/features/vm/TLB/arch-support.txt
index 2bdd3b6..30f75a7 100644
--- a/Documentation/features/vm/TLB/arch-support.txt
+++ b/Documentation/features/vm/TLB/arch-support.txt
@@ -28,7 +28,6 @@
| sh: | TODO |
| sparc: | TODO |
| um: | .. |
- | unicore32: | .. |
| x86: | ok |
| xtensa: | TODO |
-----------------------
diff --git a/Documentation/features/vm/huge-vmap/arch-support.txt b/Documentation/features/vm/huge-vmap/arch-support.txt
index 8525f19..c5ff3a4 100644
--- a/Documentation/features/vm/huge-vmap/arch-support.txt
+++ b/Documentation/features/vm/huge-vmap/arch-support.txt
@@ -28,7 +28,6 @@
| sh: | TODO |
| sparc: | TODO |
| um: | TODO |
- | unicore32: | TODO |
| x86: | ok |
| xtensa: | TODO |
-----------------------
diff --git a/Documentation/features/vm/ioremap_prot/arch-support.txt b/Documentation/features/vm/ioremap_prot/arch-support.txt
index 3a6b87d..1cb7406 100644
--- a/Documentation/features/vm/ioremap_prot/arch-support.txt
+++ b/Documentation/features/vm/ioremap_prot/arch-support.txt
@@ -28,7 +28,6 @@
| sh: | ok |
| sparc: | TODO |
| um: | TODO |
- | unicore32: | TODO |
| x86: | ok |
| xtensa: | TODO |
-----------------------
diff --git a/Documentation/features/vm/pte_special/arch-support.txt b/Documentation/features/vm/pte_special/arch-support.txt
index 2e017387..13d0e1e 100644
--- a/Documentation/features/vm/pte_special/arch-support.txt
+++ b/Documentation/features/vm/pte_special/arch-support.txt
@@ -28,7 +28,6 @@
| sh: | ok |
| sparc: | ok |
| um: | TODO |
- | unicore32: | TODO |
| x86: | ok |
| xtensa: | TODO |
-----------------------
diff --git a/Documentation/filesystems/9p.rst b/Documentation/filesystems/9p.rst
index 2995279..7b5964b 100644
--- a/Documentation/filesystems/9p.rst
+++ b/Documentation/filesystems/9p.rst
@@ -18,7 +18,7 @@
The best detailed explanation of the Linux implementation and applications of
the 9p client is available in the form of a USENIX paper:
- http://www.usenix.org/events/usenix05/tech/freenix/hensbergen.html
+ https://www.usenix.org/events/usenix05/tech/freenix/hensbergen.html
Other applications are described in the following papers:
diff --git a/Documentation/filesystems/afs.rst b/Documentation/filesystems/afs.rst
index cada946..0abb155 100644
--- a/Documentation/filesystems/afs.rst
+++ b/Documentation/filesystems/afs.rst
@@ -190,7 +190,7 @@
Secure operations are initiated by acquiring a key using the klog program. A
very primitive klog program is available at:
- http://people.redhat.com/~dhowells/rxrpc/klog.c
+ https://people.redhat.com/~dhowells/rxrpc/klog.c
This should be compiled by::
diff --git a/Documentation/filesystems/autofs-mount-control.rst b/Documentation/filesystems/autofs-mount-control.rst
index 2903aed..bf4b511 100644
--- a/Documentation/filesystems/autofs-mount-control.rst
+++ b/Documentation/filesystems/autofs-mount-control.rst
@@ -391,7 +391,7 @@
set to an autofs mount type. The call returns 1 if this is a mount point
and sets out.devid field to the device number of the mount and out.magic
field to the relevant super block magic number (described below) or 0 if
-it isn't a mountpoint. In both cases the the device number (as returned
+it isn't a mountpoint. In both cases the device number (as returned
by new_encode_dev()) is returned in out.devid field.
If supplied with a file descriptor we're looking for a specific mount,
@@ -399,12 +399,12 @@
the descriptor corresponds to is considered a mountpoint if it is itself
a mountpoint or contains a mount, such as a multi-mount without a root
mount. In this case we return 1 if the descriptor corresponds to a mount
-point and and also returns the super magic of the covering mount if there
+point and also returns the super magic of the covering mount if there
is one or 0 if it isn't a mountpoint.
If a path is supplied (and the ioctlfd field is set to -1) then the path
is looked up and is checked to see if it is the root of a mount. If a
type is also given we are looking for a particular autofs mount and if
-a match isn't found a fail is returned. If the the located path is the
+a match isn't found a fail is returned. If the located path is the
root of a mount 1 is returned along with the super magic of the mount
or 0 otherwise.
diff --git a/Documentation/filesystems/caching/cachefiles.rst b/Documentation/filesystems/caching/cachefiles.rst
index 65d3db4..e58bc1f 100644
--- a/Documentation/filesystems/caching/cachefiles.rst
+++ b/Documentation/filesystems/caching/cachefiles.rst
@@ -348,7 +348,7 @@
There are policy source files available in:
- http://people.redhat.com/~dhowells/fscache/cachefilesd-0.8.tar.bz2
+ https://people.redhat.com/~dhowells/fscache/cachefilesd-0.8.tar.bz2
and later versions. In that tarball, see the files::
diff --git a/Documentation/filesystems/caching/operations.rst b/Documentation/filesystems/caching/operations.rst
index f7ddcc0..9983e16 100644
--- a/Documentation/filesystems/caching/operations.rst
+++ b/Documentation/filesystems/caching/operations.rst
@@ -27,7 +27,7 @@
fscache_operation structs, though these are usually embedded into some other
structure.
-This facility is available to and expected to be be used by the cache backends,
+This facility is available to and expected to be used by the cache backends,
and FS-Cache will create operations and pass them off to the appropriate cache
backend for completion.
diff --git a/Documentation/filesystems/coda.rst b/Documentation/filesystems/coda.rst
index 84c860c..bdde7e4 100644
--- a/Documentation/filesystems/coda.rst
+++ b/Documentation/filesystems/coda.rst
@@ -524,7 +524,7 @@
Description
This call is made to determine the ViceFid and filetype of
- a directory entry. The directory entry requested carries name name
+ a directory entry. The directory entry requested carries name 'name'
and Venus will search the directory identified by cfs_lookup_in.VFid.
The result may indicate that the name does not exist, or that
difficulty was encountered in finding it (e.g. due to disconnection).
@@ -886,7 +886,7 @@
none
Description
- Remove the directory with name name from the directory
+ Remove the directory with name 'name' from the directory
identified by VFid.
.. Note:: The attributes of the parent directory should be returned since
diff --git a/Documentation/filesystems/configfs.rst b/Documentation/filesystems/configfs.rst
index f894195..1d3d6f4 100644
--- a/Documentation/filesystems/configfs.rst
+++ b/Documentation/filesystems/configfs.rst
@@ -226,7 +226,7 @@
If an attribute is readable and provides a ->show method, that method will
be called whenever userspace asks for a read(2) on the attribute. If an
attribute is writable and provides a ->store method, that method will be
-be called whenever userspace asks for a write(2) on the attribute.
+called whenever userspace asks for a write(2) on the attribute.
struct configfs_bin_attribute
=============================
diff --git a/Documentation/filesystems/dax.txt b/Documentation/filesystems/dax.txt
index 8e26707..8fdb78f 100644
--- a/Documentation/filesystems/dax.txt
+++ b/Documentation/filesystems/dax.txt
@@ -25,7 +25,7 @@
Currently 3 filesystems support DAX: ext2, ext4 and xfs. Enabling DAX on them
is different.
-Enabling DAX on ext4 and ext2
+Enabling DAX on ext2
-----------------------------
When mounting the filesystem, use the "-o dax" option on the command line or
@@ -33,8 +33,8 @@
within the filesystem. It is equivalent to the '-o dax=always' behavior below.
-Enabling DAX on xfs
--------------------
+Enabling DAX on xfs and ext4
+----------------------------
Summary
-------
diff --git a/Documentation/filesystems/debugfs.rst b/Documentation/filesystems/debugfs.rst
index 1da7a4b..728ab57 100644
--- a/Documentation/filesystems/debugfs.rst
+++ b/Documentation/filesystems/debugfs.rst
@@ -185,13 +185,17 @@
If you want to dump an u32 array in debugfs, you can create file with::
+ struct debugfs_u32_array {
+ u32 *array;
+ u32 n_elements;
+ };
+
void debugfs_create_u32_array(const char *name, umode_t mode,
struct dentry *parent,
- u32 *array, u32 elements);
+ struct debugfs_u32_array *array);
-The "array" argument provides data, and the "elements" argument is
-the number of elements in the array. Note: Once array is created its
-size can not be changed.
+The "array" argument wraps a pointer to the array's data and the number
+of its elements. Note: Once array is created its size can not be changed.
There is a helper function to create device related seq_file::
diff --git a/Documentation/filesystems/directory-locking.rst b/Documentation/filesystems/directory-locking.rst
index de12016..504ba94 100644
--- a/Documentation/filesystems/directory-locking.rst
+++ b/Documentation/filesystems/directory-locking.rst
@@ -28,7 +28,7 @@
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
+NB: we might get away with locking the source (and target in exchange
case) shared.
5) link creation. Locking rules:
@@ -56,7 +56,7 @@
* 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 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.
diff --git a/Documentation/filesystems/dlmfs.rst b/Documentation/filesystems/dlmfs.rst
index 68daaa7..28dd41a 100644
--- a/Documentation/filesystems/dlmfs.rst
+++ b/Documentation/filesystems/dlmfs.rst
@@ -12,7 +12,7 @@
:Project web page: http://ocfs2.wiki.kernel.org
:Tools web page: https://github.com/markfasheh/ocfs2-tools
-:OCFS2 mailing lists: http://oss.oracle.com/projects/ocfs2/mailman/
+:OCFS2 mailing lists: https://oss.oracle.com/projects/ocfs2/mailman/
All code copyright 2005 Oracle except when otherwise noted.
diff --git a/Documentation/filesystems/ext4/verity.rst b/Documentation/filesystems/ext4/verity.rst
index 3e4c0ee..e99ff3f 100644
--- a/Documentation/filesystems/ext4/verity.rst
+++ b/Documentation/filesystems/ext4/verity.rst
@@ -39,3 +39,6 @@
Verity files cannot have blocks allocated past the end of the verity
metadata.
+
+Verity and DAX are not compatible and attempts to set both of these flags
+on a file will fail.
diff --git a/Documentation/filesystems/f2fs.rst b/Documentation/filesystems/f2fs.rst
index 099d45a..ec8d997 100644
--- a/Documentation/filesystems/f2fs.rst
+++ b/Documentation/filesystems/f2fs.rst
@@ -101,164 +101,172 @@
=============
-====================== ============================================================
-background_gc=%s Turn on/off cleaning operations, namely garbage
- collection, triggered in background when I/O subsystem is
- idle. If background_gc=on, it will turn on the garbage
- collection and if background_gc=off, garbage collection
- will be turned off. If background_gc=sync, it will turn
- on synchronous garbage collection running in background.
- Default value for this option is on. So garbage
- collection is on by default.
-disable_roll_forward Disable the roll-forward recovery routine
-norecovery Disable the roll-forward recovery routine, mounted read-
- only (i.e., -o ro,disable_roll_forward)
-discard/nodiscard Enable/disable real-time discard in f2fs, if discard is
- enabled, f2fs will issue discard/TRIM commands when a
- segment is cleaned.
-no_heap Disable heap-style segment allocation which finds free
- segments for data from the beginning of main area, while
- for node from the end of main area.
-nouser_xattr Disable Extended User Attributes. Note: xattr is enabled
- by default if CONFIG_F2FS_FS_XATTR is selected.
-noacl Disable POSIX Access Control List. Note: acl is enabled
- by default if CONFIG_F2FS_FS_POSIX_ACL is selected.
-active_logs=%u Support configuring the number of active logs. In the
- current design, f2fs supports only 2, 4, and 6 logs.
- Default number is 6.
-disable_ext_identify Disable the extension list configured by mkfs, so f2fs
- does not aware of cold files such as media files.
-inline_xattr Enable the inline xattrs feature.
-noinline_xattr Disable the inline xattrs feature.
-inline_xattr_size=%u Support configuring inline xattr size, it depends on
- flexible inline xattr feature.
-inline_data Enable the inline data feature: New created small(<~3.4k)
- files can be written into inode block.
-inline_dentry Enable the inline dir feature: data in new created
- directory entries can be written into inode block. The
- space of inode block which is used to store inline
- dentries is limited to ~3.4k.
-noinline_dentry Disable the inline dentry feature.
-flush_merge Merge concurrent cache_flush commands as much as possible
- to eliminate redundant command issues. If the underlying
- device handles the cache_flush command relatively slowly,
- recommend to enable this option.
-nobarrier This option can be used if underlying storage guarantees
- its cached data should be written to the novolatile area.
- If this option is set, no cache_flush commands are issued
- but f2fs still guarantees the write ordering of all the
- data writes.
-fastboot This option is used when a system wants to reduce mount
- time as much as possible, even though normal performance
- can be sacrificed.
-extent_cache Enable an extent cache based on rb-tree, it can cache
- as many as extent which map between contiguous logical
- address and physical address per inode, resulting in
- increasing the cache hit ratio. Set by default.
-noextent_cache Disable an extent cache based on rb-tree explicitly, see
- the above extent_cache mount option.
-noinline_data Disable the inline data feature, inline data feature is
- 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
- enabled with fault_injection option, fault type value
- is shown below, it supports single or combined type.
+======================== ============================================================
+background_gc=%s Turn on/off cleaning operations, namely garbage
+ collection, triggered in background when I/O subsystem is
+ idle. If background_gc=on, it will turn on the garbage
+ collection and if background_gc=off, garbage collection
+ will be turned off. If background_gc=sync, it will turn
+ on synchronous garbage collection running in background.
+ Default value for this option is on. So garbage
+ collection is on by default.
+disable_roll_forward Disable the roll-forward recovery routine
+norecovery Disable the roll-forward recovery routine, mounted read-
+ only (i.e., -o ro,disable_roll_forward)
+discard/nodiscard Enable/disable real-time discard in f2fs, if discard is
+ enabled, f2fs will issue discard/TRIM commands when a
+ segment is cleaned.
+no_heap Disable heap-style segment allocation which finds free
+ segments for data from the beginning of main area, while
+ for node from the end of main area.
+nouser_xattr Disable Extended User Attributes. Note: xattr is enabled
+ by default if CONFIG_F2FS_FS_XATTR is selected.
+noacl Disable POSIX Access Control List. Note: acl is enabled
+ by default if CONFIG_F2FS_FS_POSIX_ACL is selected.
+active_logs=%u Support configuring the number of active logs. In the
+ current design, f2fs supports only 2, 4, and 6 logs.
+ Default number is 6.
+disable_ext_identify Disable the extension list configured by mkfs, so f2fs
+ does not aware of cold files such as media files.
+inline_xattr Enable the inline xattrs feature.
+noinline_xattr Disable the inline xattrs feature.
+inline_xattr_size=%u Support configuring inline xattr size, it depends on
+ flexible inline xattr feature.
+inline_data Enable the inline data feature: New created small(<~3.4k)
+ files can be written into inode block.
+inline_dentry Enable the inline dir feature: data in new created
+ directory entries can be written into inode block. The
+ space of inode block which is used to store inline
+ dentries is limited to ~3.4k.
+noinline_dentry Disable the inline dentry feature.
+flush_merge Merge concurrent cache_flush commands as much as possible
+ to eliminate redundant command issues. If the underlying
+ device handles the cache_flush command relatively slowly,
+ recommend to enable this option.
+nobarrier This option can be used if underlying storage guarantees
+ its cached data should be written to the novolatile area.
+ If this option is set, no cache_flush commands are issued
+ but f2fs still guarantees the write ordering of all the
+ data writes.
+fastboot This option is used when a system wants to reduce mount
+ time as much as possible, even though normal performance
+ can be sacrificed.
+extent_cache Enable an extent cache based on rb-tree, it can cache
+ as many as extent which map between contiguous logical
+ address and physical address per inode, resulting in
+ increasing the cache hit ratio. Set by default.
+noextent_cache Disable an extent cache based on rb-tree explicitly, see
+ the above extent_cache mount option.
+noinline_data Disable the inline data feature, inline data feature is
+ 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
+ enabled with fault_injection option, fault type value
+ is shown below, it supports single or combined type.
- =================== ===========
- Type_Name Type_Value
- =================== ===========
- FAULT_KMALLOC 0x000000001
- FAULT_KVMALLOC 0x000000002
- FAULT_PAGE_ALLOC 0x000000004
- FAULT_PAGE_GET 0x000000008
- FAULT_ALLOC_BIO 0x000000010
- FAULT_ALLOC_NID 0x000000020
- FAULT_ORPHAN 0x000000040
- FAULT_BLOCK 0x000000080
- FAULT_DIR_DEPTH 0x000000100
- FAULT_EVICT_INODE 0x000000200
- FAULT_TRUNCATE 0x000000400
- FAULT_READ_IO 0x000000800
- FAULT_CHECKPOINT 0x000001000
- FAULT_DISCARD 0x000002000
- FAULT_WRITE_IO 0x000004000
- =================== ===========
-mode=%s Control block allocation mode which supports "adaptive"
- and "lfs". In "lfs" mode, there should be no random
- writes towards main area.
-io_bits=%u Set the bit size of write IO requests. It should be set
- with "mode=lfs".
-usrquota Enable plain user disk quota accounting.
-grpquota Enable plain group disk quota accounting.
-prjquota Enable plain project quota accounting.
-usrjquota=<file> Appoint specified file and type during mount, so that quota
-grpjquota=<file> information can be properly updated during recovery flow,
-prjjquota=<file> <quota file>: must be in root directory;
-jqfmt=<quota type> <quota type>: [vfsold,vfsv0,vfsv1].
-offusrjquota Turn off user journelled quota.
-offgrpjquota Turn off group journelled quota.
-offprjjquota Turn off project journelled quota.
-quota Enable plain user disk quota accounting.
-noquota Disable all plain disk quota option.
-whint_mode=%s Control which write hints are passed down to block
- layer. This supports "off", "user-based", and
- "fs-based". In "off" mode (default), f2fs does not pass
- down hints. In "user-based" mode, f2fs tries to pass
- down hints given by users. And in "fs-based" mode, f2fs
- passes down hints with its policy.
-alloc_mode=%s Adjust block allocation policy, which supports "reuse"
- and "default".
-fsync_mode=%s Control the policy of fsync. Currently supports "posix",
- "strict", and "nobarrier". In "posix" mode, which is
- default, fsync will follow POSIX semantics and does a
- light operation to improve the filesystem performance.
- In "strict" mode, fsync will be heavy and behaves in line
- with xfs, ext4 and btrfs, where xfstest generic/342 will
- pass, but the performance will regress. "nobarrier" is
- based on "posix", but doesn't issue flush command for
- non-atomic files likewise "nobarrier" mount option.
+ =================== ===========
+ Type_Name Type_Value
+ =================== ===========
+ FAULT_KMALLOC 0x000000001
+ FAULT_KVMALLOC 0x000000002
+ FAULT_PAGE_ALLOC 0x000000004
+ FAULT_PAGE_GET 0x000000008
+ FAULT_ALLOC_BIO 0x000000010
+ FAULT_ALLOC_NID 0x000000020
+ FAULT_ORPHAN 0x000000040
+ FAULT_BLOCK 0x000000080
+ FAULT_DIR_DEPTH 0x000000100
+ FAULT_EVICT_INODE 0x000000200
+ FAULT_TRUNCATE 0x000000400
+ FAULT_READ_IO 0x000000800
+ FAULT_CHECKPOINT 0x000001000
+ FAULT_DISCARD 0x000002000
+ FAULT_WRITE_IO 0x000004000
+ =================== ===========
+mode=%s Control block allocation mode which supports "adaptive"
+ and "lfs". In "lfs" mode, there should be no random
+ writes towards main area.
+io_bits=%u Set the bit size of write IO requests. It should be set
+ with "mode=lfs".
+usrquota Enable plain user disk quota accounting.
+grpquota Enable plain group disk quota accounting.
+prjquota Enable plain project quota accounting.
+usrjquota=<file> Appoint specified file and type during mount, so that quota
+grpjquota=<file> information can be properly updated during recovery flow,
+prjjquota=<file> <quota file>: must be in root directory;
+jqfmt=<quota type> <quota type>: [vfsold,vfsv0,vfsv1].
+offusrjquota Turn off user journelled quota.
+offgrpjquota Turn off group journelled quota.
+offprjjquota Turn off project journelled quota.
+quota Enable plain user disk quota accounting.
+noquota Disable all plain disk quota option.
+whint_mode=%s Control which write hints are passed down to block
+ layer. This supports "off", "user-based", and
+ "fs-based". In "off" mode (default), f2fs does not pass
+ down hints. In "user-based" mode, f2fs tries to pass
+ down hints given by users. And in "fs-based" mode, f2fs
+ passes down hints with its policy.
+alloc_mode=%s Adjust block allocation policy, which supports "reuse"
+ and "default".
+fsync_mode=%s Control the policy of fsync. Currently supports "posix",
+ "strict", and "nobarrier". In "posix" mode, which is
+ default, fsync will follow POSIX semantics and does a
+ light operation to improve the filesystem performance.
+ In "strict" mode, fsync will be heavy and behaves in line
+ with xfs, ext4 and btrfs, where xfstest generic/342 will
+ pass, but the performance will regress. "nobarrier" is
+ based on "posix", but doesn't issue flush command for
+ non-atomic files likewise "nobarrier" mount option.
test_dummy_encryption
test_dummy_encryption=%s
- Enable dummy encryption, which provides a fake fscrypt
- context. The fake fscrypt context is used by xfstests.
- The argument may be either "v1" or "v2", in order to
- select the corresponding fscrypt policy version.
-checkpoint=%s[:%u[%]] Set to "disable" to turn off checkpointing. Set to "enable"
- to reenable checkpointing. Is enabled by default. While
- disabled, any unmounting or unexpected shutdowns will cause
- the filesystem contents to appear as they did when the
- filesystem was mounted with that option.
- While mounting with checkpoint=disabled, the filesystem must
- run garbage collection to ensure that all available space can
- be used. If this takes too much time, the mount may return
- EAGAIN. You may optionally add a value to indicate how much
- of the disk you would be willing to temporarily give up to
- avoid additional garbage collection. This can be given as a
- number of blocks, or as a percent. For instance, mounting
- with checkpoint=disable:100% would always succeed, but it may
- hide up to all remaining free space. The actual space that
- would be unusable can be viewed at /sys/fs/f2fs/<disk>/unusable
- This space is reclaimed once checkpoint=enable.
-compress_algorithm=%s Control compress algorithm, currently f2fs supports "lzo",
- "lz4", "zstd" and "lzo-rle" algorithm.
-compress_log_size=%u Support configuring compress cluster size, the size will
- be 4KB * (1 << %u), 16KB is minimum size, also it's
- default size.
-compress_extension=%s Support adding specified extension, so that f2fs can enable
- compression on those corresponding files, e.g. if all files
- with '.ext' has high compression rate, we can set the '.ext'
- on compression extension list and enable compression on
- these file by default rather than to enable it via ioctl.
- For other files, we can still enable compression via ioctl.
-====================== ============================================================
+ Enable dummy encryption, which provides a fake fscrypt
+ context. The fake fscrypt context is used by xfstests.
+ The argument may be either "v1" or "v2", in order to
+ select the corresponding fscrypt policy version.
+checkpoint=%s[:%u[%]] Set to "disable" to turn off checkpointing. Set to "enable"
+ to reenable checkpointing. Is enabled by default. While
+ disabled, any unmounting or unexpected shutdowns will cause
+ the filesystem contents to appear as they did when the
+ filesystem was mounted with that option.
+ While mounting with checkpoint=disabled, the filesystem must
+ run garbage collection to ensure that all available space can
+ be used. If this takes too much time, the mount may return
+ EAGAIN. You may optionally add a value to indicate how much
+ of the disk you would be willing to temporarily give up to
+ avoid additional garbage collection. This can be given as a
+ number of blocks, or as a percent. For instance, mounting
+ with checkpoint=disable:100% would always succeed, but it may
+ hide up to all remaining free space. The actual space that
+ would be unusable can be viewed at /sys/fs/f2fs/<disk>/unusable
+ This space is reclaimed once checkpoint=enable.
+compress_algorithm=%s Control compress algorithm, currently f2fs supports "lzo",
+ "lz4", "zstd" and "lzo-rle" algorithm.
+compress_log_size=%u Support configuring compress cluster size, the size will
+ be 4KB * (1 << %u), 16KB is minimum size, also it's
+ default size.
+compress_extension=%s Support adding specified extension, so that f2fs can enable
+ compression on those corresponding files, e.g. if all files
+ with '.ext' has high compression rate, we can set the '.ext'
+ on compression extension list and enable compression on
+ these file by default rather than to enable it via ioctl.
+ For other files, we can still enable compression via ioctl.
+ Note that, there is one reserved special extension '*', it
+ can be set to enable compression for all files.
+inlinecrypt When possible, encrypt/decrypt the contents of encrypted
+ files using the blk-crypto framework rather than
+ filesystem-layer encryption. This allows the use of
+ inline encryption hardware. The on-disk format is
+ unaffected. For more details, see
+ Documentation/block/inline-encryption.rst.
+======================== ============================================================
Debugfs Entries
===============
@@ -737,8 +745,8 @@
- In order to eliminate write amplification during overwrite, F2FS only
support compression on write-once file, data can be compressed only when
- all logical blocks in file are valid and cluster compress ratio is lower
- than specified threshold.
+ all logical blocks in cluster contain valid data and compress ratio of
+ cluster data is lower than specified threshold.
- To enable compression on regular inode, there are three ways:
diff --git a/Documentation/filesystems/fscrypt.rst b/Documentation/filesystems/fscrypt.rst
index f517af8..423c5a0 100644
--- a/Documentation/filesystems/fscrypt.rst
+++ b/Documentation/filesystems/fscrypt.rst
@@ -1158,7 +1158,7 @@
were to be added to or removed from anything other than an empty
directory.) These structs are defined as follows::
- #define FS_KEY_DERIVATION_NONCE_SIZE 16
+ #define FSCRYPT_FILE_NONCE_SIZE 16
#define FSCRYPT_KEY_DESCRIPTOR_SIZE 8
struct fscrypt_context_v1 {
@@ -1167,7 +1167,7 @@
u8 filenames_encryption_mode;
u8 flags;
u8 master_key_descriptor[FSCRYPT_KEY_DESCRIPTOR_SIZE];
- u8 nonce[FS_KEY_DERIVATION_NONCE_SIZE];
+ u8 nonce[FSCRYPT_FILE_NONCE_SIZE];
};
#define FSCRYPT_KEY_IDENTIFIER_SIZE 16
@@ -1178,7 +1178,7 @@
u8 flags;
u8 __reserved[4];
u8 master_key_identifier[FSCRYPT_KEY_IDENTIFIER_SIZE];
- u8 nonce[FS_KEY_DERIVATION_NONCE_SIZE];
+ u8 nonce[FSCRYPT_FILE_NONCE_SIZE];
};
The context structs contain the same information as the corresponding
@@ -1204,6 +1204,18 @@
buffers regardless of encryption. Other filesystems, such as ext4 and
F2FS, have to allocate bounce pages specially for encryption.
+Fscrypt is also able to use inline encryption hardware instead of the
+kernel crypto API for en/decryption of file contents. When possible,
+and if directed to do so (by specifying the 'inlinecrypt' mount option
+for an ext4/F2FS filesystem), it adds encryption contexts to bios and
+uses blk-crypto to perform the en/decryption instead of making use of
+the above read/write path changes. Of course, even if directed to
+make use of inline encryption, fscrypt will only be able to do so if
+either hardware inline encryption support is available for the
+selected encryption algorithm or CONFIG_BLK_INLINE_ENCRYPTION_FALLBACK
+is selected. If neither is the case, fscrypt will fall back to using
+the above mentioned read/write path changes for en/decryption.
+
Filename hashing and encoding
-----------------------------
@@ -1250,11 +1262,14 @@
To test fscrypt, use xfstests, which is Linux's de facto standard
filesystem test suite. First, run all the tests in the "encrypt"
-group on the relevant filesystem(s). For example, to test ext4 and
+group on the relevant filesystem(s). One can also run the tests
+with the 'inlinecrypt' mount option to test the implementation for
+inline encryption support. For example, to test ext4 and
f2fs encryption using `kvm-xfstests
<https://github.com/tytso/xfstests-bld/blob/master/Documentation/kvm-quickstart.md>`_::
kvm-xfstests -c ext4,f2fs -g encrypt
+ kvm-xfstests -c ext4,f2fs -g encrypt -m inlinecrypt
UBIFS encryption can also be tested this way, but it should be done in
a separate command, and it takes some time for kvm-xfstests to set up
@@ -1276,6 +1291,7 @@
kvm-xfstests, use the "encrypt" filesystem configuration::
kvm-xfstests -c ext4/encrypt,f2fs/encrypt -g auto
+ kvm-xfstests -c ext4/encrypt,f2fs/encrypt -g auto -m inlinecrypt
Because this runs many more tests than "-g encrypt" does, it takes
much longer to run; so also consider using `gce-xfstests
@@ -1283,3 +1299,4 @@
instead of kvm-xfstests::
gce-xfstests -c ext4/encrypt,f2fs/encrypt -g auto
+ gce-xfstests -c ext4/encrypt,f2fs/encrypt -g auto -m inlinecrypt
diff --git a/Documentation/filesystems/fsverity.rst b/Documentation/filesystems/fsverity.rst
index a95536b..6c8944f 100644
--- a/Documentation/filesystems/fsverity.rst
+++ b/Documentation/filesystems/fsverity.rst
@@ -659,7 +659,7 @@
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
+ - Rebuilding 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.
diff --git a/Documentation/filesystems/hfs.rst b/Documentation/filesystems/hfs.rst
index ab17a00..776015c 100644
--- a/Documentation/filesystems/hfs.rst
+++ b/Documentation/filesystems/hfs.rst
@@ -76,7 +76,7 @@
The hfsutils package from Robert Leslie contains a program called
hformat that can be used to create HFS filesystem. See
-<http://www.mars.org/home/rob/proj/hfs/> for details.
+<https://www.mars.org/home/rob/proj/hfs/> for details.
Credits
diff --git a/Documentation/filesystems/hpfs.rst b/Documentation/filesystems/hpfs.rst
index 0db1522..7e0dd2f 100644
--- a/Documentation/filesystems/hpfs.rst
+++ b/Documentation/filesystems/hpfs.rst
@@ -7,7 +7,7 @@
1998-2004, Mikulas Patocka
:email: mikulas@artax.karlin.mff.cuni.cz
-:homepage: http://artax.karlin.mff.cuni.cz/~mikulas/vyplody/hpfs/index-e.cgi
+:homepage: https://artax.karlin.mff.cuni.cz/~mikulas/vyplody/hpfs/index-e.cgi
Credits
=======
diff --git a/Documentation/filesystems/journalling.rst b/Documentation/filesystems/journalling.rst
index 58ce6b3..7e2be2f 100644
--- a/Documentation/filesystems/journalling.rst
+++ b/Documentation/filesystems/journalling.rst
@@ -10,27 +10,27 @@
The journalling layer is easy to use. You need to first of all create a
journal_t data structure. There are two calls to do this dependent on
how you decide to allocate the physical media on which the journal
-resides. The :c:func:`jbd2_journal_init_inode` call is for journals stored in
-filesystem inodes, or the :c:func:`jbd2_journal_init_dev` call can be used
+resides. The jbd2_journal_init_inode() call is for journals stored in
+filesystem inodes, or the jbd2_journal_init_dev() call can be used
for journal stored on a raw device (in a continuous range of blocks). A
journal_t is a typedef for a struct pointer, so when you are finally
-finished make sure you call :c:func:`jbd2_journal_destroy` on it to free up
+finished make sure you call jbd2_journal_destroy() on it to free up
any used kernel memory.
Once you have got your journal_t object you need to 'mount' or load the
journal file. The journalling layer expects the space for the journal
was already allocated and initialized properly by the userspace tools.
-When loading the journal you must call :c:func:`jbd2_journal_load` to process
+When loading the journal you must call jbd2_journal_load() to process
journal contents. If the client file system detects the journal contents
does not need to be processed (or even need not have valid contents), it
-may call :c:func:`jbd2_journal_wipe` to clear the journal contents before
-calling :c:func:`jbd2_journal_load`.
+may call jbd2_journal_wipe() to clear the journal contents before
+calling jbd2_journal_load().
Note that jbd2_journal_wipe(..,0) calls
-:c:func:`jbd2_journal_skip_recovery` for you if it detects any outstanding
-transactions in the journal and similarly :c:func:`jbd2_journal_load` will
-call :c:func:`jbd2_journal_recover` if necessary. I would advise reading
-:c:func:`ext4_load_journal` in fs/ext4/super.c for examples on this stage.
+jbd2_journal_skip_recovery() for you if it detects any outstanding
+transactions in the journal and similarly jbd2_journal_load() will
+call jbd2_journal_recover() if necessary. I would advise reading
+ext4_load_journal() in fs/ext4/super.c for examples on this stage.
Now you can go ahead and start modifying the underlying filesystem.
Almost.
@@ -39,57 +39,57 @@
by wrapping them into transactions. Additionally you also need to wrap
the modification of each of the buffers with calls to the journal layer,
so it knows what the modifications you are actually making are. To do
-this use :c:func:`jbd2_journal_start` which returns a transaction handle.
+this use jbd2_journal_start() which returns a transaction handle.
-:c:func:`jbd2_journal_start` and its counterpart :c:func:`jbd2_journal_stop`,
+jbd2_journal_start() and its counterpart jbd2_journal_stop(),
which indicates the end of a transaction are nestable calls, so you can
reenter a transaction if necessary, but remember you must call
-:c:func:`jbd2_journal_stop` the same number of times as
-:c:func:`jbd2_journal_start` before the transaction is completed (or more
+jbd2_journal_stop() the same number of times as
+jbd2_journal_start() before the transaction is completed (or more
accurately leaves the update phase). Ext4/VFS makes use of this feature to
simplify handling of inode dirtying, quota support, etc.
Inside each transaction you need to wrap the modifications to the
individual buffers (blocks). Before you start to modify a buffer you
-need to call :c:func:`jbd2_journal_get_create_access()` /
-:c:func:`jbd2_journal_get_write_access()` /
-:c:func:`jbd2_journal_get_undo_access()` as appropriate, this allows the
+need to call jbd2_journal_get_create_access() /
+jbd2_journal_get_write_access() /
+jbd2_journal_get_undo_access() as appropriate, this allows the
journalling layer to copy the unmodified
data if it needs to. After all the buffer may be part of a previously
uncommitted transaction. At this point you are at last ready to modify a
buffer, and once you are have done so you need to call
-:c:func:`jbd2_journal_dirty_metadata`. Or if you've asked for access to a
+jbd2_journal_dirty_metadata(). Or if you've asked for access to a
buffer you now know is now longer required to be pushed back on the
-device you can call :c:func:`jbd2_journal_forget` in much the same way as you
-might have used :c:func:`bforget` in the past.
+device you can call jbd2_journal_forget() in much the same way as you
+might have used bforget() in the past.
-A :c:func:`jbd2_journal_flush` may be called at any time to commit and
+A jbd2_journal_flush() may be called at any time to commit and
checkpoint all your transactions.
-Then at umount time , in your :c:func:`put_super` you can then call
-:c:func:`jbd2_journal_destroy` to clean up your in-core journal object.
+Then at umount time , in your put_super() you can then call
+jbd2_journal_destroy() to clean up your in-core journal object.
Unfortunately there a couple of ways the journal layer can cause a
deadlock. The first thing to note is that each task can only have a
single outstanding transaction at any one time, remember nothing commits
-until the outermost :c:func:`jbd2_journal_stop`. This means you must complete
+until the outermost jbd2_journal_stop(). This means you must complete
the transaction at the end of each file/inode/address etc. operation you
perform, so that the journalling system isn't re-entered on another
journal. Since transactions can't be nested/batched across differing
journals, and another filesystem other than yours (say ext4) may be
modified in a later syscall.
-The second case to bear in mind is that :c:func:`jbd2_journal_start` can block
+The second case to bear in mind is that jbd2_journal_start() can block
if there isn't enough space in the journal for your transaction (based
on the passed nblocks param) - when it blocks it merely(!) needs to wait
for transactions to complete and be committed from other tasks, so
-essentially we are waiting for :c:func:`jbd2_journal_stop`. So to avoid
-deadlocks you must treat :c:func:`jbd2_journal_start` /
-:c:func:`jbd2_journal_stop` as if they were semaphores and include them in
+essentially we are waiting for jbd2_journal_stop(). So to avoid
+deadlocks you must treat jbd2_journal_start() /
+jbd2_journal_stop() as if they were semaphores and include them in
your semaphore ordering rules to prevent
-deadlocks. Note that :c:func:`jbd2_journal_extend` has similar blocking
-behaviour to :c:func:`jbd2_journal_start` so you can deadlock here just as
-easily as on :c:func:`jbd2_journal_start`.
+deadlocks. Note that jbd2_journal_extend() has similar blocking
+behaviour to jbd2_journal_start() so you can deadlock here just as
+easily as on jbd2_journal_start().
Try to reserve the right number of blocks the first time. ;-). This will
be the maximum number of blocks you are going to touch in this
@@ -116,8 +116,8 @@
that need processing when the transaction commits.
JBD2 also provides a way to block all transaction updates via
-:c:func:`jbd2_journal_lock_updates()` /
-:c:func:`jbd2_journal_unlock_updates()`. Ext4 uses this when it wants a
+jbd2_journal_lock_updates() /
+jbd2_journal_unlock_updates(). Ext4 uses this when it wants a
window with a clean and stable fs for a moment. E.g.
::
diff --git a/Documentation/filesystems/locking.rst b/Documentation/filesystems/locking.rst
index 318605d..64f94a1 100644
--- a/Documentation/filesystems/locking.rst
+++ b/Documentation/filesystems/locking.rst
@@ -433,15 +433,15 @@
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
lm_breaker_owns_lease: no no no
-========== ============= ================= =========
+====================== ============= ================= =========
buffer_head
===========
@@ -467,7 +467,6 @@
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 *);
@@ -483,14 +482,13 @@
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
+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
@@ -616,9 +614,9 @@
locking rules:
-============= ======== ===========================
+============= ========= ===========================
ops mmap_lock PageLocked(page)
-============= ======== ===========================
+============= ========= ===========================
open: yes
close: yes
fault: yes can return with page locked
@@ -626,7 +624,7 @@
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
diff --git a/Documentation/filesystems/mount_api.rst b/Documentation/filesystems/mount_api.rst
index dea22d6..29c169c 100644
--- a/Documentation/filesystems/mount_api.rst
+++ b/Documentation/filesystems/mount_api.rst
@@ -213,7 +213,7 @@
void (*free)(struct fs_context *fc);
int (*dup)(struct fs_context *fc, struct fs_context *src_fc);
int (*parse_param)(struct fs_context *fc,
- struct struct fs_parameter *param);
+ struct fs_parameter *param);
int (*parse_monolithic)(struct fs_context *fc, void *data);
int (*get_tree)(struct fs_context *fc);
int (*reconfigure)(struct fs_context *fc);
@@ -247,7 +247,7 @@
* ::
int (*parse_param)(struct fs_context *fc,
- struct struct fs_parameter *param);
+ struct fs_parameter *param);
Called when a parameter is being added to the filesystem context. param
points to the key name and maybe a value object. VFS-specific options
diff --git a/Documentation/filesystems/nfs/rpc-server-gss.rst b/Documentation/filesystems/nfs/rpc-server-gss.rst
index 8127545..abed4a2 100644
--- a/Documentation/filesystems/nfs/rpc-server-gss.rst
+++ b/Documentation/filesystems/nfs/rpc-server-gss.rst
@@ -10,12 +10,12 @@
RPCGSS is specified in a few IETF documents:
- - RFC2203 v1: http://tools.ietf.org/rfc/rfc2203.txt
- - RFC5403 v2: http://tools.ietf.org/rfc/rfc5403.txt
+ - RFC2203 v1: https://tools.ietf.org/rfc/rfc2203.txt
+ - RFC5403 v2: https://tools.ietf.org/rfc/rfc5403.txt
and there is a 3rd version being proposed:
- - http://tools.ietf.org/id/draft-williams-rpcsecgssv3.txt
+ - https://tools.ietf.org/id/draft-williams-rpcsecgssv3.txt
(At draft n. 02 at the time of writing)
Background
diff --git a/Documentation/filesystems/ocfs2.rst b/Documentation/filesystems/ocfs2.rst
index 412386b..42ca9a3 100644
--- a/Documentation/filesystems/ocfs2.rst
+++ b/Documentation/filesystems/ocfs2.rst
@@ -14,7 +14,7 @@
Project web page: http://ocfs2.wiki.kernel.org
Tools git tree: https://github.com/markfasheh/ocfs2-tools
-OCFS2 mailing lists: http://oss.oracle.com/projects/ocfs2/mailman/
+OCFS2 mailing lists: https://oss.oracle.com/projects/ocfs2/mailman/
All code copyright 2005 Oracle except when otherwise noted.
diff --git a/Documentation/filesystems/omfs.rst b/Documentation/filesystems/omfs.rst
index 4c8bb30..a104c25 100644
--- a/Documentation/filesystems/omfs.rst
+++ b/Documentation/filesystems/omfs.rst
@@ -24,7 +24,7 @@
Various utilities, including mkomfs and omfsck, are included with
omfsprogs, available at:
- http://bobcopeland.com/karma/
+ https://bobcopeland.com/karma/
Instructions are included in its README.
diff --git a/Documentation/filesystems/overlayfs.rst b/Documentation/filesystems/overlayfs.rst
index 660dbaf..8ea83a5 100644
--- a/Documentation/filesystems/overlayfs.rst
+++ b/Documentation/filesystems/overlayfs.rst
@@ -328,7 +328,7 @@
Multiple lower layers
---------------------
-Multiple lower layers can now be given using the the colon (":") as a
+Multiple lower layers can now be given using the colon (":") as a
separator character between the directory names. For example:
mount -t overlay overlay -olowerdir=/lower1:/lower2:/lower3 /merged
@@ -560,8 +560,8 @@
verified on mount time to check that upper file handles are not stale.
This verification may cause significant overhead in some cases.
-Note: the mount options index=off,nfs_export=on are conflicting and will
-result in an error.
+Note: the mount options index=off,nfs_export=on are conflicting for a
+read-write mount and will result in an error.
Testsuite
diff --git a/Documentation/filesystems/path-lookup.rst b/Documentation/filesystems/path-lookup.rst
index f46b05e..c482e16 100644
--- a/Documentation/filesystems/path-lookup.rst
+++ b/Documentation/filesystems/path-lookup.rst
@@ -43,15 +43,15 @@
non-"``/``" characters. These form two kinds of paths. Those that
start with slashes are "absolute" and start from the filesystem root.
The others are "relative" and start from the current directory, or
-from some other location specified by a file descriptor given to a
-"``XXXat``" system call such as `openat() <openat_>`_.
+from some other location specified by a file descriptor given to
+"``*at()``" system calls such as `openat() <openat_>`_.
.. _execveat: http://man7.org/linux/man-pages/man2/execveat.2.html
It is tempting to describe the second kind as starting with a
component, but that isn't always accurate: a pathname can lack both
slashes and components, it can be empty, in other words. This is
-generally forbidden in POSIX, but some of those "xxx``at``" system calls
+generally forbidden in POSIX, but some of those "``*at()``" system calls
in Linux permit it when the ``AT_EMPTY_PATH`` flag is given. For
example, if you have an open file descriptor on an executable file you
can execute it by calling `execveat() <execveat_>`_ passing
@@ -69,17 +69,17 @@
exist, it could be "``.``" or "``..``" which are handled quite differently
from other components.
-.. _POSIX: http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap04.html#tag_04_12
+.. _POSIX: https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap04.html#tag_04_12
If a pathname ends with a slash, such as "``/tmp/foo/``" it might be
tempting to consider that to have an empty final component. In many
ways that would lead to correct results, but not always. In
particular, ``mkdir()`` and ``rmdir()`` each create or remove a directory named
by the final component, and they are required to work with pathnames
-ending in "``/``". According to POSIX_
+ending in "``/``". According to POSIX_:
- A pathname that contains at least one non- <slash> character and
- that ends with one or more trailing <slash> characters shall not
+ A pathname that contains at least one non-<slash> character and
+ that ends with one or more trailing <slash> characters shall not
be resolved successfully unless the last pathname component before
the trailing <slash> characters names an existing directory or a
directory entry that is to be created for a directory immediately
@@ -229,7 +229,7 @@
it might end up continuing the search down the wrong chain,
and so miss out on part of the correct chain.
-The name-lookup process (``d_lookup()``) does _not_ try to prevent this
+The name-lookup process (``d_lookup()``) does *not* try to prevent this
from happening, but only to detect when it happens.
``rename_lock`` is a seqlock that is updated whenever any dentry is
renamed. If ``d_lookup`` finds that a rename happened while it
@@ -376,7 +376,7 @@
Bringing it together with ``struct nameidata``
----------------------------------------------
-.. _First edition Unix: http://minnie.tuhs.org/cgi-bin/utree.pl?file=V1/u2.s
+.. _First edition Unix: https://minnie.tuhs.org/cgi-bin/utree.pl?file=V1/u2.s
Throughout the process of walking a path, the current status is stored
in a ``struct nameidata``, "namei" being the traditional name - dating
@@ -398,7 +398,7 @@
``struct qstr last``
~~~~~~~~~~~~~~~~~~~~
-This is a string together with a length (i.e. _not_ ``nul`` terminated)
+This is a string together with a length (i.e. *not* ``nul`` terminated)
that is the "next" component in the pathname.
``int last_type``
@@ -655,8 +655,8 @@
clearly seen in functions like ``filename_lookup()``,
``filename_parentat()``, ``filename_mountpoint()``,
``do_filp_open()``, and ``do_file_open_root()``. These five
-correspond roughly to the four ``path_``* functions we met earlier,
-each of which calls ``link_path_walk()``. The ``path_*`` functions are
+correspond roughly to the four ``path_*()`` functions we met earlier,
+each of which calls ``link_path_walk()``. The ``path_*()`` functions are
called using different mode flags until a mode is found which works.
They are first called with ``LOOKUP_RCU`` set to request "RCU-walk". If
that fails with the error ``ECHILD`` they are called again with no
@@ -720,7 +720,7 @@
variables, then ``read_seqcount_retry()`` is called to confirm the two
are consistent, and only then is ``->d_compare()`` called. When
standard filename comparison is used, ``dentry_cmp()`` is called
-instead. Notably it does _not_ use ``read_seqcount_retry()``, but
+instead. Notably it does *not* use ``read_seqcount_retry()``, but
instead has a large comment explaining why the consistency guarantee
isn't necessary. A subsequent ``read_seqcount_retry()`` will be
sufficient to catch any problem that could occur at this point.
@@ -928,7 +928,7 @@
sedate approach.
The emphasis here is "try quickly and check". It should probably be
-"try quickly _and carefully,_ then check". The fact that checking is
+"try quickly *and carefully*, then check". The fact that checking is
needed is a reminder that the system is dynamic and only a limited
number of things are safe at all. The most likely cause of errors in
this whole process is assuming something is safe when in reality it
@@ -1265,7 +1265,7 @@
and looking up a symlink on the way to some other destination can
update the atime on that symlink.
-.. _clearest statement: http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap04.html#tag_04_08
+.. _clearest statement: https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap04.html#tag_04_08
It is not clear why this is the case; POSIX has little to say on the
subject. The `clearest statement`_ is that, if a particular implementation
@@ -1365,7 +1365,7 @@
resolution of "..". Magic-links are also blocked.
``LOOKUP_IN_ROOT`` resolves all path components as though the starting point
-were the filesystem root. ``nd_jump_root()`` brings the resolution back to to
+were the filesystem root. ``nd_jump_root()`` brings the resolution back to
the starting point, and ".." at the starting point will act as a no-op. As with
``LOOKUP_BENEATH``, ``rename_lock`` and ``mount_lock`` are used to detect
attacks against ".." resolution. Magic-links are also blocked.
diff --git a/Documentation/filesystems/proc.rst b/Documentation/filesystems/proc.rst
index 996f3cfe..533c79e 100644
--- a/Documentation/filesystems/proc.rst
+++ b/Documentation/filesystems/proc.rst
@@ -123,10 +123,10 @@
The directory /proc contains (among other things) one subdirectory for each
process running on the system, which is named after the process ID (PID).
-The link self points to the process reading the file system. Each process
+The link 'self' points to the process reading the file system. Each process
subdirectory has the entries listed in Table 1-1.
-Note that an open a file descriptor to /proc/<pid> or to any of its
+Note that an open file descriptor to /proc/<pid> or to any of its
contained files or subdirectories does not prevent <pid> being reused
for some other process in the event that <pid> exits. Operations on
open /proc/<pid> file descriptors corresponding to dead processes
@@ -220,7 +220,7 @@
The statm file contains more detailed information about the process
memory usage. Its seven fields are explained in Table 1-3. The stat file
-contains details information about the process itself. Its fields are
+contains detailed information about the process itself. Its fields are
explained in Table 1-4.
(for SMP CONFIG users)
@@ -545,7 +545,7 @@
hg huge page advise flag
nh no huge page advise flag
mg mergable advise flag
- bt - arm64 BTI guarded page
+ bt arm64 BTI guarded page
== =======================================
Note that there is no guarantee that every flag and associated mnemonic will
@@ -782,7 +782,7 @@
For this case the APIC will generate the interrupt with a IRQ vector
of 0xff. This might also be generated by chipset bugs.
-RES, CAL, TLB]
+RES, CAL, TLB
rescheduling, call and TLB flush interrupts are
sent from one CPU to another per the needs of the OS. Typically,
their statistics are used by kernel developers and interested users to
@@ -794,7 +794,7 @@
i386 and x86_64 platforms support the new IRQ vector displays.
Of some interest is the introduction of the /proc/irq directory to 2.4.
-It could be used to set IRQ to CPU affinity, this means that you can "hook" an
+It could be used to set IRQ to CPU affinity. This means that you can "hook" an
IRQ to only one CPU, or to exclude a CPU of handling IRQs. The contents of the
irq subdir is one subdir for each IRQ, and two files; default_smp_affinity and
prof_cpu_mask.
@@ -808,7 +808,7 @@
smp_affinity
smp_affinity is a bitmask, in which you can specify which CPUs can handle the
-IRQ, you can set it by doing::
+IRQ. You can set it by doing::
> echo 1 > /proc/irq/10/smp_affinity
@@ -821,7 +821,7 @@
ffffffff
There is an alternate interface, smp_affinity_list which allows specifying
-a cpu range instead of a bitmask::
+a CPU range instead of a bitmask::
> cat /proc/irq/0/smp_affinity_list
1024-1031
@@ -835,7 +835,7 @@
include information about any possible driver locality preference.
prof_cpu_mask specifies which CPUs are to be profiled by the system wide
-profiler. Default value is ffffffff (all cpus if there are only 32 of them).
+profiler. Default value is ffffffff (all CPUs if there are only 32 of them).
The way IRQs are routed is handled by the IO-APIC, and it's Round Robin
between all the CPUs which are allowed to handle it. As usual the kernel has
@@ -897,7 +897,7 @@
Fragmentation avoidance in the kernel works by grouping pages of different
migrate types into the same contiguous regions of memory called page blocks.
-A page block is typically the size of the default hugepage size e.g. 2MB on
+A page block is typically the size of the default hugepage size, e.g. 2MB on
X86-64. By keeping pages grouped based on their ability to move, the kernel
can reclaim pages within a page block to satisfy a high-order allocation.
@@ -965,7 +965,7 @@
ShmemPmdMapped: 0 kB
MemTotal
- Total usable ram (i.e. physical ram minus a few reserved
+ Total usable RAM (i.e. physical RAM minus a few reserved
bits and the kernel binary code)
MemFree
The sum of LowFree+HighFree
@@ -996,7 +996,7 @@
Memory which has been less recently used. It is more
eligible to be reclaimed for other purposes
HighTotal, HighFree
- Highmem is all memory above ~860MB of physical memory
+ Highmem is all memory above ~860MB of physical memory.
Highmem areas are for use by userspace programs, or
for the pagecache. The kernel must use tricks to access
this memory, making it slower to access than lowmem.
@@ -1078,7 +1078,7 @@
using 1G. This 1G is memory which has been "committed" to
by the VM and can be used at any time by the allocating
application. With strict overcommit enabled on the system
- (mode 2 in 'vm.overcommit_memory'),allocations which would
+ (mode 2 in 'vm.overcommit_memory'), allocations which would
exceed the CommitLimit (detailed above) will not be permitted.
This is useful if one needs to guarantee that processes will
not fail due to lack of memory once that memory has been
@@ -1099,7 +1099,7 @@
Provides information about vmalloced/vmaped areas. One line per area,
containing the virtual address range of the area, size in bytes,
caller information of the creator, and optional information depending
-on the kind of area :
+on the kind of area:
========== ===================================================
pages=nr number of pages
@@ -1144,21 +1144,21 @@
softirqs
~~~~~~~~
-Provides counts of softirq handlers serviced since boot time, for each cpu.
+Provides counts of softirq handlers serviced since boot time, for each CPU.
::
> cat /proc/softirqs
- CPU0 CPU1 CPU2 CPU3
+ CPU0 CPU1 CPU2 CPU3
HI: 0 0 0 0
- TIMER: 27166 27120 27097 27034
+ TIMER: 27166 27120 27097 27034
NET_TX: 0 0 0 17
NET_RX: 42 0 0 39
- BLOCK: 0 0 107 1121
- TASKLET: 0 0 0 290
- SCHED: 27035 26983 26971 26746
- HRTIMER: 0 0 0 0
- RCU: 1678 1769 2178 2250
+ BLOCK: 0 0 107 1121
+ TASKLET: 0 0 0 290
+ SCHED: 27035 26983 26971 26746
+ HRTIMER: 0 0 0 0
+ RCU: 1678 1769 2178 2250
1.3 IDE devices in /proc/ide
@@ -1169,7 +1169,7 @@
file drivers and a link for each IDE device, pointing to the device directory
in the controller specific subtree.
-The file drivers contains general information about the drivers used for the
+The file 'drivers' contains general information about the drivers used for the
IDE devices::
> cat /proc/ide/drivers
@@ -1409,7 +1409,7 @@
-------------------------
Information about the available and actually used tty's can be found in the
-directory /proc/tty.You'll find entries for drivers and line disciplines in
+directory /proc/tty. You'll find entries for drivers and line disciplines in
this directory, as shown in Table 1-11.
@@ -1471,9 +1471,9 @@
- iowait: In a word, iowait stands for waiting for I/O to complete. But there
are several problems:
- 1. Cpu will not wait for I/O to complete, iowait is the time that a task is
- waiting for I/O to complete. When cpu goes into idle state for
- outstanding task io, another task will be scheduled on this CPU.
+ 1. CPU will not wait for I/O to complete, iowait is the time that a task is
+ waiting for I/O to complete. When CPU goes into idle state for
+ outstanding task I/O, another task will be scheduled on this CPU.
2. In a multi-core CPU, the task waiting for I/O to complete is not running
on any CPU, so the iowait of each CPU is difficult to calculate.
3. The value of iowait field in /proc/stat will decrease in certain
@@ -1529,8 +1529,8 @@
mb_groups details of multiblock allocator buddy cache of free blocks
============== ==========================================================
-2.0 /proc/consoles
-------------------
+1.10 /proc/consoles
+-------------------
Shows registered system console lines.
To see which character device lines are currently used for the system console
@@ -1590,10 +1590,9 @@
everything works the way you want it to. You may have no alternative but to
reboot the machine once an error has been made.
-To change a value, simply echo the new value into the file. An example is
-given below in the section on the file system data. You need to be root to do
-this. You can create your own boot script to perform this every time your
-system boots.
+To change a value, simply echo the new value into the file.
+You need to be root to do this. You can create your own boot script
+to perform this every time your system boots.
The files in /proc/sys can be used to fine tune and monitor miscellaneous and
general things in the operation of the Linux kernel. Since some of the files
@@ -1624,8 +1623,8 @@
3.1 /proc/<pid>/oom_adj & /proc/<pid>/oom_score_adj- Adjust the oom-killer score
--------------------------------------------------------------------------------
-These file can be used to adjust the badness heuristic used to select which
-process gets killed in out of memory conditions.
+These files can be used to adjust the badness heuristic used to select which
+process gets killed in out of memory (oom) conditions.
The badness heuristic assigns a value to each candidate task ranging from 0
(never kill) to 1000 (always kill) to determine which process is targeted. The
@@ -1634,9 +1633,6 @@
For example, if a task is using all allowed memory, its badness score will be
1000. If it is using half of its allowed memory, its score will be 500.
-There is an additional factor included in the badness score: the current memory
-and swap usage is discounted by 3% for root processes.
-
The amount of "allowed" memory depends on the context in which the oom killer
was called. If it is due to the memory assigned to the allocating task's cpuset
being exhausted, the allowed memory represents the set of mems assigned to that
@@ -1672,24 +1668,22 @@
value set by a CAP_SYS_RESOURCE process. To reduce the value any lower
requires CAP_SYS_RESOURCE.
-Caveat: when a parent task is selected, the oom killer will sacrifice any first
-generation children with separate address spaces instead, if possible. This
-avoids servers and important system daemons from being killed and loses the
-minimal amount of work.
-
3.2 /proc/<pid>/oom_score - Display current oom-killer score
-------------------------------------------------------------
-This file can be used to check the current score used by the oom-killer is for
+This file can be used to check the current score used by the oom-killer for
any given <pid>. Use it together with /proc/<pid>/oom_score_adj to tune which
process should be killed in an out-of-memory situation.
+Please note that the exported value includes oom_score_adj so it is
+effectively in range [0,2000].
+
3.3 /proc/<pid>/io - Display the IO accounting fields
-------------------------------------------------------
-This file contains IO statistics for each running process
+This file contains IO statistics for each running process.
Example
~~~~~~~
@@ -1720,7 +1714,7 @@
is simply the sum of bytes which this process passed to read() and pread().
It includes things like tty IO and it is unaffected by whether or not actual
physical disk IO was required (the read might have been satisfied from
-pagecache)
+pagecache).
wchar
@@ -1878,7 +1872,7 @@
3.6 /proc/<pid>/comm & /proc/<pid>/task/<tid>/comm
--------------------------------------------------------
-These files provide a method to access a tasks comm value. It also allows for
+These files provide a method to access a task's comm value. It also allows for
a task to set its own or one of its thread siblings comm value. The comm value
is limited in size compared to the cmdline value, so writing anything longer
then the kernel's TASK_COMM_LEN (currently 16 chars) will result in a truncated
@@ -1891,21 +1885,21 @@
of a task pointed by <pid>/<tid> pair. The format is a space separated
stream of pids.
-Note the "first level" here -- if a child has own children they will
-not be listed here, one needs to read /proc/<children-pid>/task/<tid>/children
+Note the "first level" here -- if a child has its own children they will
+not be listed here; one needs to read /proc/<children-pid>/task/<tid>/children
to obtain the descendants.
Since this interface is intended to be fast and cheap it doesn't
guarantee to provide precise results and some children might be
skipped, especially if they've exited right after we printed their
-pids, so one need to either stop or freeze processes being inspected
+pids, so one needs to either stop or freeze processes being inspected
if precise results are needed.
3.8 /proc/<pid>/fdinfo/<fd> - Information about opened file
---------------------------------------------------------------
This file provides information associated with an opened file. The regular
-files have at least three fields -- 'pos', 'flags' and mnt_id. The 'pos'
+files have at least three fields -- 'pos', 'flags' and 'mnt_id'. The 'pos'
represents the current offset of the opened file in decimal form [see lseek(2)
for details], 'flags' denotes the octal O_xxx mask the file has been
created with [see open(2) for details] and 'mnt_id' represents mount ID of
@@ -1976,7 +1970,7 @@
flags: 02000000
inotify wd:3 ino:9e7e sdev:800013 mask:800afce ignored_mask:0 fhandle-bytes:8 fhandle-type:1 f_handle:7e9e0000640d1b6d
-where 'wd' is a watch descriptor in decimal form, ie a target file
+where 'wd' is a watch descriptor in decimal form, i.e. a target file
descriptor number, 'ino' and 'sdev' are inode and device where the
target file resides and the 'mask' is the mask of events, all in hex
form [see inotify(7) for more details].
@@ -2003,10 +1997,10 @@
where fanotify 'flags' and 'event-flags' are values used in fanotify_init
call, 'mnt_id' is the mount point identifier, 'mflags' is the value of
flags associated with mark which are tracked separately from events
-mask. 'ino', 'sdev' are target inode and device, 'mask' is the events
+mask. 'ino' and 'sdev' are target inode and device, 'mask' is the events
mask and 'ignored_mask' is the mask of events which are to be ignored.
-All in hex format. Incorporation of 'mflags', 'mask' and 'ignored_mask'
-does provide information about flags and mask used in fanotify_mark
+All are in hex format. Incorporation of 'mflags', 'mask' and 'ignored_mask'
+provide information about flags and mask used in fanotify_mark
call [see fsnotify manpage for details].
While the first three lines are mandatory and always printed, the rest is
@@ -2029,7 +2023,7 @@
where 'clockid' is the clock type and 'ticks' is the number of the timer expirations
that have occurred [see timerfd_create(2) for details]. 'settime flags' are
flags in octal form been used to setup the timer [see timerfd_settime(2) for
-details]. 'it_value' is remaining time until the timer exiration.
+details]. 'it_value' is remaining time until the timer expiration.
'it_interval' is the interval for the timer. Note the timer might be set up
with TIMER_ABSTIME option which will be shown in 'settime flags', but 'it_value'
still exhibits timer's remaining time.
@@ -2059,13 +2053,13 @@
3.10 /proc/<pid>/timerslack_ns - Task timerslack value
---------------------------------------------------------
This file provides the value of the task's timerslack value in nanoseconds.
-This value specifies a amount of time that normal timers may be deferred
+This value specifies an amount of time that normal timers may be deferred
in order to coalesce timers and avoid unnecessary wakeups.
-This allows a task's interactivity vs power consumption trade off to be
+This allows a task's interactivity vs power consumption tradeoff to be
adjusted.
-Writing 0 to the file will set the tasks timerslack to the default value.
+Writing 0 to the file will set the task's timerslack to the default value.
Valid values are from 0 - ULLONG_MAX
@@ -2105,10 +2099,10 @@
Description
~~~~~~~~~~~
-x86 specific entries:
+x86 specific entries
~~~~~~~~~~~~~~~~~~~~~
-AVX512_elapsed_ms:
+AVX512_elapsed_ms
^^^^^^^^^^^^^^^^^^
If AVX512 is supported on the machine, this entry shows the milliseconds
@@ -2134,8 +2128,8 @@
the task is unlikely an AVX512 user, but depends on the workload and the
scheduling scenario, it also could be a false negative mentioned above.
-Configuring procfs
-------------------
+Chapter 4: Configuring procfs
+=============================
4.1 Mount options
---------------------
@@ -2178,47 +2172,45 @@
subset=pid hides all top level files and directories in the procfs that
are not related to tasks.
-5 Filesystem behavior
-----------------------------
+Chapter 5: Filesystem behavior
+==============================
Originally, before the advent of pid namepsace, procfs was a global file
system. It means that there was only one procfs instance in the system.
When pid namespace was added, a separate procfs instance was mounted in
each pid namespace. So, procfs mount options are global among all
-mountpoints within the same namespace.
+mountpoints within the same namespace::
-::
+ # grep ^proc /proc/mounts
+ proc /proc proc rw,relatime,hidepid=2 0 0
-# grep ^proc /proc/mounts
-proc /proc proc rw,relatime,hidepid=2 0 0
+ # strace -e mount mount -o hidepid=1 -t proc proc /tmp/proc
+ mount("proc", "/tmp/proc", "proc", 0, "hidepid=1") = 0
+ +++ exited with 0 +++
-# strace -e mount mount -o hidepid=1 -t proc proc /tmp/proc
-mount("proc", "/tmp/proc", "proc", 0, "hidepid=1") = 0
-+++ exited with 0 +++
-
-# grep ^proc /proc/mounts
-proc /proc proc rw,relatime,hidepid=2 0 0
-proc /tmp/proc proc rw,relatime,hidepid=2 0 0
+ # grep ^proc /proc/mounts
+ proc /proc proc rw,relatime,hidepid=2 0 0
+ proc /tmp/proc proc rw,relatime,hidepid=2 0 0
and only after remounting procfs mount options will change at all
-mountpoints.
+mountpoints::
-# mount -o remount,hidepid=1 -t proc proc /tmp/proc
+ # mount -o remount,hidepid=1 -t proc proc /tmp/proc
-# grep ^proc /proc/mounts
-proc /proc proc rw,relatime,hidepid=1 0 0
-proc /tmp/proc proc rw,relatime,hidepid=1 0 0
+ # grep ^proc /proc/mounts
+ proc /proc proc rw,relatime,hidepid=1 0 0
+ proc /tmp/proc proc rw,relatime,hidepid=1 0 0
This behavior is different from the behavior of other filesystems.
The new procfs behavior is more like other filesystems. Each procfs mount
creates a new procfs instance. Mount options affect own procfs instance.
It means that it became possible to have several procfs instances
-displaying tasks with different filtering options in one pid namespace.
+displaying tasks with different filtering options in one pid namespace::
-# mount -o hidepid=invisible -t proc proc /proc
-# mount -o hidepid=noaccess -t proc proc /tmp/proc
-# grep ^proc /proc/mounts
-proc /proc proc rw,relatime,hidepid=invisible 0 0
-proc /tmp/proc proc rw,relatime,hidepid=noaccess 0 0
+ # mount -o hidepid=invisible -t proc proc /proc
+ # mount -o hidepid=noaccess -t proc proc /tmp/proc
+ # grep ^proc /proc/mounts
+ proc /proc proc rw,relatime,hidepid=invisible 0 0
+ proc /tmp/proc proc rw,relatime,hidepid=noaccess 0 0
diff --git a/Documentation/filesystems/quota.rst b/Documentation/filesystems/quota.rst
index a30cdd4..abd4303 100644
--- a/Documentation/filesystems/quota.rst
+++ b/Documentation/filesystems/quota.rst
@@ -18,7 +18,7 @@
filesystem.
For more details about quota design, see the documentation in quota-tools package
-(http://sourceforge.net/projects/linuxquota).
+(https://sourceforge.net/projects/linuxquota).
Quota netlink interface
=======================
@@ -31,11 +31,11 @@
and processed accordingly.
The interface uses generic netlink framework (see
-http://lwn.net/Articles/208755/ and http://people.suug.ch/~tgr/libnl/ for more
-details about this layer). The name of the quota generic netlink interface
-is "VFS_DQUOT". Definitions of constants below are in <linux/quota.h>.
-Since the quota netlink protocol is not namespace aware, quota netlink messages
-are sent only in initial network namespace.
+https://lwn.net/Articles/208755/ and http://www.infradead.org/~tgr/libnl/ for
+more details about this layer). The name of the quota generic netlink interface
+is "VFS_DQUOT". Definitions of constants below are in <linux/quota.h>. Since
+the quota netlink protocol is not namespace aware, quota netlink messages are
+sent only in initial network namespace.
Currently, the interface supports only one message type QUOTA_NL_C_WARNING.
This command is used to send a notification about any of the above mentioned
diff --git a/Documentation/filesystems/ramfs-rootfs-initramfs.rst b/Documentation/filesystems/ramfs-rootfs-initramfs.rst
index 3fddacc..4598b0d 100644
--- a/Documentation/filesystems/ramfs-rootfs-initramfs.rst
+++ b/Documentation/filesystems/ramfs-rootfs-initramfs.rst
@@ -246,15 +246,15 @@
you need to get a minimal root filesystem up and running, here are some
references:
-- http://www.tldp.org/HOWTO/Bootdisk-HOWTO/
-- http://www.tldp.org/HOWTO/From-PowerUp-To-Bash-Prompt-HOWTO.html
+- https://www.tldp.org/HOWTO/Bootdisk-HOWTO/
+- https://www.tldp.org/HOWTO/From-PowerUp-To-Bash-Prompt-HOWTO.html
- http://www.linuxfromscratch.org/lfs/view/stable/
-The "klibc" package (http://www.kernel.org/pub/linux/libs/klibc) is
+The "klibc" package (https://www.kernel.org/pub/linux/libs/klibc) is
designed to be a tiny C library to statically link early userspace
code against, along with some related utilities. It is BSD licensed.
-I use uClibc (http://www.uclibc.org) and busybox (http://www.busybox.net)
+I use uClibc (https://www.uclibc.org) and busybox (https://www.busybox.net)
myself. These are LGPL and GPL, respectively. (A self-contained initramfs
package is planned for the busybox 1.3 release.)
diff --git a/Documentation/filesystems/sysfs-pci.rst b/Documentation/filesystems/sysfs-pci.rst
index a265f3e..742fbd2 100644
--- a/Documentation/filesystems/sysfs-pci.rst
+++ b/Documentation/filesystems/sysfs-pci.rst
@@ -63,7 +63,7 @@
binary - file contains binary data
cpumask - file contains a cpumask type
-.. [1] rw for RESOURCE_IO (I/O port) regions only
+.. [1] rw for IORESOURCE_IO (I/O port) regions only
The read only files are informational, writes to them will be ignored, with
the exception of the 'rom' file. Writable files can be used to perform
diff --git a/Documentation/filesystems/sysfs-tagging.rst b/Documentation/filesystems/sysfs-tagging.rst
index 8888a05..83647e1 100644
--- a/Documentation/filesystems/sysfs-tagging.rst
+++ b/Documentation/filesystems/sysfs-tagging.rst
@@ -15,7 +15,7 @@
namespaces to see the same interface that is currently presented in
sysfs, sysfs now has tagging directory support.
-By using the network namespace pointers as tags to separate out the
+By using the network namespace pointers as tags to separate out
the sysfs directory entries we ensure that we don't have conflicts
in the directories and applications only see a limited set of
the network devices.
diff --git a/Documentation/filesystems/tmpfs.rst b/Documentation/filesystems/tmpfs.rst
index 4e95929..c44f8b1 100644
--- a/Documentation/filesystems/tmpfs.rst
+++ b/Documentation/filesystems/tmpfs.rst
@@ -150,6 +150,22 @@
parameters with chmod(1), chown(1) and chgrp(1) on a mounted filesystem.
+tmpfs has a mount option to select whether it will wrap at 32- or 64-bit inode
+numbers:
+
+======= ========================
+inode64 Use 64-bit inode numbers
+inode32 Use 32-bit inode numbers
+======= ========================
+
+On a 32-bit kernel, inode32 is implicit, and inode64 is refused at mount time.
+On a 64-bit kernel, CONFIG_TMPFS_INODE64 sets the default. inode64 avoids the
+possibility of multiple files with the same inode number on a single device;
+but risks glibc failing with EOVERFLOW once 33-bit inode numbers are reached -
+if a long-lived tmpfs is accessed by 32-bit applications so ancient that
+opening a file larger than 2GiB fails with EINVAL.
+
+
So 'mount -t tmpfs -o size=10G,nr_inodes=10k,mode=700 tmpfs /mytmpfs'
will give you tmpfs instance on /mytmpfs which can allocate 10GB
RAM/SWAP in 10240 inodes and it is only accessible by root.
@@ -161,3 +177,5 @@
Hugh Dickins, 4 June 2007
:Updated:
KOSAKI Motohiro, 16 Mar 2010
+:Updated:
+ Chris Down, 13 July 2020
diff --git a/Documentation/filesystems/ubifs-authentication.rst b/Documentation/filesystems/ubifs-authentication.rst
index 16efd72..1f39c8c 100644
--- a/Documentation/filesystems/ubifs-authentication.rst
+++ b/Documentation/filesystems/ubifs-authentication.rst
@@ -433,9 +433,9 @@
References
==========
-[CRYPTSETUP2] http://www.saout.de/pipermail/dm-crypt/2017-November/005745.html
+[CRYPTSETUP2] https://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/
+[DMC-CBC-ATTACK] https://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
diff --git a/Documentation/filesystems/udf.rst b/Documentation/filesystems/udf.rst
index d9badbf..f9489dd 100644
--- a/Documentation/filesystems/udf.rst
+++ b/Documentation/filesystems/udf.rst
@@ -72,4 +72,4 @@
Documentation on UDF and ECMA 167 is available FREE from:
- http://www.osta.org/
- - http://www.ecma-international.org/
+ - https://www.ecma-international.org/
diff --git a/Documentation/filesystems/vfs.rst b/Documentation/filesystems/vfs.rst
index ed17771..ca52c82 100644
--- a/Documentation/filesystems/vfs.rst
+++ b/Documentation/filesystems/vfs.rst
@@ -392,7 +392,7 @@
``set``
Called by the VFS to set the value of a particular extended
attribute. When the new value is NULL, called to remove a
- particular extended attribute. This method is called by the the
+ particular extended attribute. This method is called by the
setxattr(2) and removexattr(2) system calls.
When none of the xattr handlers of a filesystem match the specified
@@ -652,7 +652,7 @@
PG_Writeback is cleared.
Writeback makes use of a writeback_control structure to direct the
-operations. This gives the the writepage and writepages operations some
+operations. This gives the writepage and writepages operations some
information about the nature of and reason for the writeback request,
and the constraints under which it is being done. It is also used to
return information back to the caller about the result of a writepage or
@@ -766,9 +766,9 @@
``writepages``
called by the VM to write out pages associated with the
- address_space object. If wbc->sync_mode is WBC_SYNC_ALL, then
+ address_space object. If wbc->sync_mode is WB_SYNC_ALL, then
the writeback_control will specify a range of pages that must be
- written out. If it is WBC_SYNC_NONE, then a nr_to_write is
+ written out. If it is WB_SYNC_NONE, then a nr_to_write is
given and that many pages should be written if possible. If no
->writepages is given, then mpage_writepages is used instead.
This will choose pages from the address space that are tagged as
@@ -1116,7 +1116,7 @@
before any bytes were remapped. The remap_flags parameter
accepts REMAP_FILE_* flags. If REMAP_FILE_DEDUP is set then the
implementation must only remap if the requested file ranges have
- identical contents. If REMAP_CAN_SHORTEN is set, the caller is
+ identical contents. If REMAP_FILE_CAN_SHORTEN is set, the caller is
ok with the implementation shortening the request length to
satisfy alignment or EOF requirements (or any other reason).
@@ -1431,13 +1431,13 @@
version.)
Creating Linux virtual filesystems. 2002
- <http://lwn.net/Articles/13325/>
+ <https://lwn.net/Articles/13325/>
The Linux Virtual File-system Layer by Neil Brown. 1999
<http://www.cse.unsw.edu.au/~neilb/oss/linux-commentary/vfs.html>
A tour of the Linux VFS by Michael K. Johnson. 1996
- <http://www.tldp.org/LDP/khg/HyperNews/get/fs/vfstour.html>
+ <https://www.tldp.org/LDP/khg/HyperNews/get/fs/vfstour.html>
A small trail through the Linux kernel by Andries Brouwer. 2001
- <http://www.win.tue.nl/~aeb/linux/vfs/trail.html>
+ <https://www.win.tue.nl/~aeb/linux/vfs/trail.html>
diff --git a/Documentation/filesystems/zonefs.rst b/Documentation/filesystems/zonefs.rst
index 71d845c..6c18bc8 100644
--- a/Documentation/filesystems/zonefs.rst
+++ b/Documentation/filesystems/zonefs.rst
@@ -110,14 +110,14 @@
increasing zone start sector on the device.
All read and write operations to zone files are not allowed beyond the file
-maximum size, that is, beyond the zone size. Any access exceeding the zone
-size is failed with the -EFBIG error.
+maximum size, that is, beyond the zone capacity. Any access exceeding the zone
+capacity is failed with the -EFBIG error.
Creating, deleting, renaming or modifying any attribute of files and
sub-directories is not allowed.
The number of blocks of a file as reported by stat() and fstat() indicates the
-size of the file zone, or in other words, the maximum file size.
+capacity of the zone file, or in other words, the maximum file size.
Conventional zone files
-----------------------
@@ -156,8 +156,8 @@
Truncating sequential zone files is allowed only down to 0, in which case, the
zone is reset to rewind the file zone write pointer position to the start of
-the zone, or up to the zone size, in which case the file's zone is transitioned
-to the FULL state (finish zone operation).
+the zone, or up to the zone capacity, in which case the file's zone is
+transitioned to the FULL state (finish zone operation).
Format options
--------------
@@ -324,7 +324,7 @@
is defined as invalib by the ZBC and ZAC standards, making it impossible to
discover the amount of data that has been written to the zone. In the case of a
read-only zone discovered at run-time, as indicated in the previous section.
-the size of the zone file is left unchanged from its last updated value.
+The size of the zone file is left unchanged from its last updated value.
Zonefs User Space Tools
=======================
@@ -401,8 +401,9 @@
# ls -l /mnt/seq/0
-rw-r----- 1 root root 0 Nov 25 13:49 /mnt/seq/0
-Since files are statically mapped to zones on the disk, the number of blocks of
-a file as reported by stat() and fstat() indicates the size of the file zone::
+Since files are statically mapped to zones on the disk, the number of blocks
+of a file as reported by stat() and fstat() indicates the capacity of the file
+zone::
# stat /mnt/seq/0
File: /mnt/seq/0
@@ -416,5 +417,6 @@
The number of blocks of the file ("Blocks") in units of 512B blocks gives the
maximum file size of 524288 * 512 B = 256 MB, corresponding to the device zone
-size in this example. Of note is that the "IO block" field always indicates the
-minimum I/O size for writes and corresponds to the device physical sector size.
+capacity in this example. Of note is that the "IO block" field always
+indicates the minimum I/O size for writes and corresponds to the device
+physical sector size.
diff --git a/Documentation/firmware-guide/acpi/DSD-properties-rules.rst b/Documentation/firmware-guide/acpi/DSD-properties-rules.rst
index 4306f29..8b2d8d0 100644
--- a/Documentation/firmware-guide/acpi/DSD-properties-rules.rst
+++ b/Documentation/firmware-guide/acpi/DSD-properties-rules.rst
@@ -96,5 +96,5 @@
References
==========
-.. [1] http://www.uefi.org/sites/default/files/resources/_DSD-device-properties-UUID.pdf
-.. [2] http://www.uefi.org/sites/default/files/resources/_DSD-hierarchical-data-extension-UUID-v1.1.pdf
+.. [1] https://www.uefi.org/sites/default/files/resources/_DSD-device-properties-UUID.pdf
+.. [2] https://www.uefi.org/sites/default/files/resources/_DSD-hierarchical-data-extension-UUID-v1.1.pdf
diff --git a/Documentation/firmware-guide/acpi/dsd/data-node-references.rst b/Documentation/firmware-guide/acpi/dsd/data-node-references.rst
index febccbc..9b17dc7 100644
--- a/Documentation/firmware-guide/acpi/dsd/data-node-references.rst
+++ b/Documentation/firmware-guide/acpi/dsd/data-node-references.rst
@@ -85,9 +85,9 @@
==========
[1] Hierarchical Data Extension UUID For _DSD.
-<http://www.uefi.org/sites/default/files/resources/_DSD-hierarchical-data-extension-UUID-v1.1.pdf>,
+<https://www.uefi.org/sites/default/files/resources/_DSD-hierarchical-data-extension-UUID-v1.1.pdf>,
referenced 2018-07-17.
[2] Device Properties UUID For _DSD.
-<http://www.uefi.org/sites/default/files/resources/_DSD-device-properties-UUID.pdf>,
+<https://www.uefi.org/sites/default/files/resources/_DSD-device-properties-UUID.pdf>,
referenced 2016-10-04.
diff --git a/Documentation/firmware-guide/acpi/dsd/graph.rst b/Documentation/firmware-guide/acpi/dsd/graph.rst
index 1a6ce7a..7072db80 100644
--- a/Documentation/firmware-guide/acpi/dsd/graph.rst
+++ b/Documentation/firmware-guide/acpi/dsd/graph.rst
@@ -154,23 +154,23 @@
==========
[1] _DSD (Device Specific Data) Implementation Guide.
- http://www.uefi.org/sites/default/files/resources/_DSD-implementation-guide-toplevel-1_1.htm,
+ https://www.uefi.org/sites/default/files/resources/_DSD-implementation-guide-toplevel-1_1.htm,
referenced 2016-10-03.
-[2] Devicetree. http://www.devicetree.org, referenced 2016-10-03.
+[2] Devicetree. https://www.devicetree.org, referenced 2016-10-03.
[3] Documentation/devicetree/bindings/graph.txt
[4] Device Properties UUID For _DSD.
- http://www.uefi.org/sites/default/files/resources/_DSD-device-properties-UUID.pdf,
+ https://www.uefi.org/sites/default/files/resources/_DSD-device-properties-UUID.pdf,
referenced 2016-10-04.
[5] Hierarchical Data Extension UUID For _DSD.
- http://www.uefi.org/sites/default/files/resources/_DSD-hierarchical-data-extension-UUID-v1.1.pdf,
+ https://www.uefi.org/sites/default/files/resources/_DSD-hierarchical-data-extension-UUID-v1.1.pdf,
referenced 2016-10-04.
[6] Advanced Configuration and Power Interface Specification.
- http://www.uefi.org/sites/default/files/resources/ACPI_6_1.pdf,
+ https://www.uefi.org/sites/default/files/resources/ACPI_6_1.pdf,
referenced 2016-10-04.
[7] _DSD Device Properties Usage Rules.
diff --git a/Documentation/firmware-guide/acpi/dsd/leds.rst b/Documentation/firmware-guide/acpi/dsd/leds.rst
index 946efe2..aba1e9a 100644
--- a/Documentation/firmware-guide/acpi/dsd/leds.rst
+++ b/Documentation/firmware-guide/acpi/dsd/leds.rst
@@ -90,7 +90,7 @@
References
==========
-[1] Device tree. <URL:http://www.devicetree.org>, referenced 2019-02-21.
+[1] Device tree. <URL:https://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>,
@@ -101,11 +101,11 @@
[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>,
+ <URL:https://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>,
+ <URL:https://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/lpit.rst b/Documentation/firmware-guide/acpi/lpit.rst
index aca928f..37922a9 100644
--- a/Documentation/firmware-guide/acpi/lpit.rst
+++ b/Documentation/firmware-guide/acpi/lpit.rst
@@ -7,7 +7,7 @@
To enumerate platform Low Power Idle states, Intel platforms are using
“Low Power Idle Table” (LPIT). More details about this table can be
downloaded from:
-http://www.uefi.org/sites/default/files/resources/Intel_ACPI_Low_Power_S0_Idle.pdf
+https://www.uefi.org/sites/default/files/resources/Intel_ACPI_Low_Power_S0_Idle.pdf
Residencies for each low power state can be read via FFH
(Function fixed hardware) or a memory mapped interface.
diff --git a/Documentation/fpga/dfl.rst b/Documentation/fpga/dfl.rst
index 978c4af..0404fe6 100644
--- a/Documentation/fpga/dfl.rst
+++ b/Documentation/fpga/dfl.rst
@@ -8,7 +8,7 @@
- Xiao Guangrong <guangrong.xiao@linux.intel.com>
- Wu Hao <hao.wu@intel.com>
-The Device Feature List (DFL) FPGA framework (and drivers according to this
+The Device Feature List (DFL) FPGA framework (and drivers according to
this framework) hides the very details of low layer hardwares and provides
unified interfaces to userspace. Applications could use these interfaces to
configure, enumerate, open and access FPGA accelerators on platforms which
@@ -89,6 +89,8 @@
- 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)
+- Get number of irqs of FME global error (DFL_FPGA_FME_ERR_GET_IRQ_NUM)
+- Set interrupt trigger for FME error (DFL_FPGA_FME_ERR_SET_IRQ)
More functions are exposed through sysfs
(/sys/class/fpga_region/regionX/dfl-fme.n/):
@@ -149,6 +151,10 @@
- Map DMA buffer (DFL_FPGA_PORT_DMA_MAP)
- Unmap DMA buffer (DFL_FPGA_PORT_DMA_UNMAP)
- Reset AFU (DFL_FPGA_PORT_RESET)
+- Get number of irqs of port error (DFL_FPGA_PORT_ERR_GET_IRQ_NUM)
+- Set interrupt trigger for port error (DFL_FPGA_PORT_ERR_SET_IRQ)
+- Get number of irqs of UINT (DFL_FPGA_PORT_UINT_GET_IRQ_NUM)
+- Set interrupt trigger for UINT (DFL_FPGA_PORT_UINT_SET_IRQ)
DFL_FPGA_PORT_RESET:
reset the FPGA Port and its AFU. Userspace can do Port
@@ -462,6 +468,19 @@
The current driver does not support sampling. So "perf record" is unsupported.
+Interrupt support
+=================
+Some FME and AFU private features are able to generate interrupts. As mentioned
+above, users could call ioctl (DFL_FPGA_*_GET_IRQ_NUM) to know whether or how
+many interrupts are supported for this private feature. Drivers also implement
+an eventfd based interrupt handling mechanism for users to get notified when
+interrupt happens. Users could set eventfds to driver via
+ioctl (DFL_FPGA_*_SET_IRQ), and then poll/select on these eventfds waiting for
+notification.
+In Current DFL, 3 sub features (Port error, FME global error and AFU interrupt)
+support interrupts.
+
+
Add new FIUs support
====================
It's possible that developers made some new function blocks (FIUs) under this
diff --git a/Documentation/gpu/amdgpu.rst b/Documentation/gpu/amdgpu.rst
index 4cc7432..1711235 100644
--- a/Documentation/gpu/amdgpu.rst
+++ b/Documentation/gpu/amdgpu.rst
@@ -197,11 +197,14 @@
.. kernel-doc:: drivers/gpu/drm/amd/amdgpu/amdgpu_pm.c
:doc: pp_power_profile_mode
-busy_percent
-~~~~~~~~~~~~
+*_busy_percent
+~~~~~~~~~~~~~~
.. kernel-doc:: drivers/gpu/drm/amd/amdgpu/amdgpu_pm.c
- :doc: busy_percent
+ :doc: gpu_busy_percent
+
+.. kernel-doc:: drivers/gpu/drm/amd/amdgpu/amdgpu_pm.c
+ :doc: mem_busy_percent
GPU Product Information
=======================
diff --git a/Documentation/gpu/backlight.rst b/Documentation/gpu/backlight.rst
new file mode 100644
index 0000000..9ebfc9d
--- /dev/null
+++ b/Documentation/gpu/backlight.rst
@@ -0,0 +1,12 @@
+=================
+Backlight support
+=================
+
+.. kernel-doc:: drivers/video/backlight/backlight.c
+ :doc: overview
+
+.. kernel-doc:: include/linux/backlight.h
+ :internal:
+
+.. kernel-doc:: drivers/video/backlight/backlight.c
+ :export:
diff --git a/Documentation/gpu/drm-kms-helpers.rst b/Documentation/gpu/drm-kms-helpers.rst
index ee73045..b89ddd0 100644
--- a/Documentation/gpu/drm-kms-helpers.rst
+++ b/Documentation/gpu/drm-kms-helpers.rst
@@ -411,15 +411,3 @@
.. kernel-doc:: drivers/gpu/drm/drm_crtc_helper.c
:export:
-
-SHMEM GEM Helper Reference
-==========================
-
-.. kernel-doc:: drivers/gpu/drm/drm_gem_shmem_helper.c
- :doc: overview
-
-.. kernel-doc:: include/drm/drm_gem_shmem_helper.h
- :internal:
-
-.. kernel-doc:: drivers/gpu/drm/drm_gem_shmem_helper.c
- :export:
diff --git a/Documentation/gpu/drm-kms.rst b/Documentation/gpu/drm-kms.rst
index 397314d..3c5ae4f 100644
--- a/Documentation/gpu/drm-kms.rst
+++ b/Documentation/gpu/drm-kms.rst
@@ -460,6 +460,12 @@
.. kernel-doc:: drivers/gpu/drm/drm_connector.c
:doc: HDMI connector properties
+Standard CRTC Properties
+------------------------
+
+.. kernel-doc:: drivers/gpu/drm/drm_crtc.c
+ :doc: standard CRTC properties
+
Plane Composition Properties
----------------------------
@@ -537,3 +543,18 @@
.. kernel-doc:: drivers/gpu/drm/drm_vblank.c
:export:
+
+Vertical Blank Work
+===================
+
+.. kernel-doc:: drivers/gpu/drm/drm_vblank_work.c
+ :doc: vblank works
+
+Vertical Blank Work Functions Reference
+---------------------------------------
+
+.. kernel-doc:: include/drm/drm_vblank_work.h
+ :internal:
+
+.. kernel-doc:: drivers/gpu/drm/drm_vblank_work.c
+ :export:
diff --git a/Documentation/gpu/drm-mm.rst b/Documentation/gpu/drm-mm.rst
index 1839762..9abee15 100644
--- a/Documentation/gpu/drm-mm.rst
+++ b/Documentation/gpu/drm-mm.rst
@@ -179,10 +179,7 @@
All GEM objects are reference-counted by the GEM core. References can be
acquired and release by calling drm_gem_object_get() and drm_gem_object_put()
-respectively. The caller must hold the :c:type:`struct drm_device <drm_device>`
-struct_mutex lock when calling drm_gem_object_get(). As a convenience, GEM
-provides drm_gem_object_put_unlocked() functions that can be called without
-holding the lock.
+respectively.
When the last reference to a GEM object is released the GEM core calls
the :c:type:`struct drm_driver <drm_driver>` gem_free_object_unlocked
@@ -314,7 +311,7 @@
a pointer on drm_gem_cma_get_unmapped_area().
More detailed information about get_unmapped_area can be found in
-Documentation/nommu-mmap.txt
+Documentation/admin-guide/mm/nommu-mmap.rst
Memory Coherency
----------------
@@ -373,6 +370,18 @@
.. kernel-doc:: drivers/gpu/drm/drm_gem_cma_helper.c
:export:
+GEM SHMEM Helper Function Reference
+-----------------------------------
+
+.. kernel-doc:: drivers/gpu/drm/drm_gem_shmem_helper.c
+ :doc: overview
+
+.. kernel-doc:: include/drm/drm_gem_shmem_helper.h
+ :internal:
+
+.. kernel-doc:: drivers/gpu/drm/drm_gem_shmem_helper.c
+ :export:
+
GEM VRAM Helper Functions Reference
-----------------------------------
diff --git a/Documentation/gpu/drm-uapi.rst b/Documentation/gpu/drm-uapi.rst
index 56fec6e..496d8fc 100644
--- a/Documentation/gpu/drm-uapi.rst
+++ b/Documentation/gpu/drm-uapi.rst
@@ -195,7 +195,7 @@
EPERM/EACCES:
Returned for an operation that is valid, but needs more privileges.
E.g. root-only or much more common, DRM master-only operations return
- this when when called by unpriviledged clients. There's no clear
+ this when called by unpriviledged clients. There's no clear
difference between EACCES and EPERM.
ENODEV:
diff --git a/Documentation/gpu/index.rst b/Documentation/gpu/index.rst
index 1fcf8e8..c9a51e3 100644
--- a/Documentation/gpu/index.rst
+++ b/Documentation/gpu/index.rst
@@ -12,6 +12,7 @@
drm-uapi
drm-client
drivers
+ backlight
vga-switcheroo
vgaarbiter
todo
diff --git a/Documentation/gpu/komeda-kms.rst b/Documentation/gpu/komeda-kms.rst
index b08da1c..eb693c8 100644
--- a/Documentation/gpu/komeda-kms.rst
+++ b/Documentation/gpu/komeda-kms.rst
@@ -41,7 +41,7 @@
frame. its output frame can be fed into post image processor for showing it on
the monitor or fed into wb_layer and written to memory at the same time.
user can also insert a scaler between compositor and wb_layer to down scale
-the display frame first and and then write to memory.
+the display frame first and then write to memory.
Writeback Layer (wb_layer)
--------------------------
diff --git a/Documentation/gpu/todo.rst b/Documentation/gpu/todo.rst
index 658b52f..7969f10 100644
--- a/Documentation/gpu/todo.rst
+++ b/Documentation/gpu/todo.rst
@@ -157,8 +157,8 @@
reliably take that lock any more. Instead state needs to be protected with
suitable subordinate locks or some cleanup work pushed to a worker thread. For
performance-critical drivers it might also be better to go with a more
-fine-grained per-buffer object and per-context lockings scheme. Currently only the
-``msm`` driver still use ``struct_mutex``.
+fine-grained per-buffer object and per-context lockings scheme. Currently only
+the ``msm`` and `i915` drivers use ``struct_mutex``.
Contact: Daniel Vetter, respective driver maintainers
@@ -305,7 +305,7 @@
drm_modeset_lock_all_ctx() with DRM_MODESET_LOCK_ALL_BEGIN() and
DRM_MODESET_LOCK_ALL_END() instead.
-This should also be done for all places where drm_modest_lock_all() is still
+This should also be done for all places where drm_modeset_lock_all() is still
used.
As a reference, take a look at the conversions already completed in drm core.
@@ -327,26 +327,6 @@
Level: Intermediate (mostly because it is a huge tasks without good partial
milestones, not technically itself that challenging)
-Convert direct mode.vrefresh accesses to use drm_mode_vrefresh()
-----------------------------------------------------------------
-
-drm_display_mode.vrefresh isn't guaranteed to be populated. As such, using it
-is risky and has been known to cause div-by-zero bugs. Fortunately, drm core
-has helper which will use mode.vrefresh if it's !0 and will calculate it from
-the timings when it's 0.
-
-Use simple search/replace, or (more fun) cocci to replace instances of direct
-vrefresh access with a call to the helper. Check out
-https://lists.freedesktop.org/archives/dri-devel/2019-January/205186.html for
-inspiration.
-
-Once all instances of vrefresh have been converted, remove vrefresh from
-drm_display_mode to avoid future use.
-
-Contact: Sean Paul
-
-Level: Starter
-
connector register/unregister fixes
-----------------------------------
@@ -392,6 +372,38 @@
Level: Intermediate
+Consolidate custom driver modeset properties
+--------------------------------------------
+
+Before atomic modeset took place, many drivers where creating their own
+properties. Among other things, atomic brought the requirement that custom,
+driver specific properties should not be used.
+
+For this task, we aim to introduce core helpers or reuse the existing ones
+if available:
+
+A quick, unconfirmed, examples list.
+
+Introduce core helpers:
+- audio (amdgpu, intel, gma500, radeon)
+- brightness, contrast, etc (armada, nouveau) - overlay only (?)
+- broadcast rgb (gma500, intel)
+- colorkey (armada, nouveau, rcar) - overlay only (?)
+- dither (amdgpu, nouveau, radeon) - varies across drivers
+- underscan family (amdgpu, radeon, nouveau)
+
+Already in core:
+- colorspace (sti)
+- tv format names, enhancements (gma500, intel)
+- tv overscan, margins, etc. (gma500, intel)
+- zorder (omapdrm) - same as zpos (?)
+
+
+Contact: Emil Velikov, respective driver maintainers
+
+Level: Intermediate
+
+
Core refactorings
=================
diff --git a/Documentation/gpu/vgaarbiter.rst b/Documentation/gpu/vgaarbiter.rst
index 0b41b05..339ed5f 100644
--- a/Documentation/gpu/vgaarbiter.rst
+++ b/Documentation/gpu/vgaarbiter.rst
@@ -185,7 +185,7 @@
implementation of the user space side [3]. Now (2009) Tiago Vignatti and Dave
Airlie finally put this work in shape and queued to Jesse Barnes' PCI tree.
-0) http://cgit.freedesktop.org/xorg/xserver/commit/?id=4b42448a2388d40f257774fbffdccaea87bd0347
-1) http://lists.freedesktop.org/archives/xorg/2005-March/006663.html
-2) http://lists.freedesktop.org/archives/xorg/2005-March/006745.html
-3) http://lists.freedesktop.org/archives/xorg/2007-October/029507.html
+0) https://cgit.freedesktop.org/xorg/xserver/commit/?id=4b42448a2388d40f257774fbffdccaea87bd0347
+1) https://lists.freedesktop.org/archives/xorg/2005-March/006663.html
+2) https://lists.freedesktop.org/archives/xorg/2005-March/006745.html
+3) https://lists.freedesktop.org/archives/xorg/2007-October/029507.html
diff --git a/Documentation/hid/hiddev.rst b/Documentation/hid/hiddev.rst
index 209e6ba..9b28a97 100644
--- a/Documentation/hid/hiddev.rst
+++ b/Documentation/hid/hiddev.rst
@@ -65,7 +65,7 @@
==============
This description should be read in conjunction with the HID
-specification, freely available from http://www.usb.org, and
+specification, freely available from https://www.usb.org, and
conveniently linked of http://www.linux-usb.org.
The hiddev API uses a read() interface, and a set of ioctl() calls.
diff --git a/Documentation/hid/intel-ish-hid.rst b/Documentation/hid/intel-ish-hid.rst
index cccbf4b..d4785cf 100644
--- a/Documentation/hid/intel-ish-hid.rst
+++ b/Documentation/hid/intel-ish-hid.rst
@@ -235,7 +235,7 @@
To ease in implantation and allow independent driver handle each client
this transport layer takes advantage of Linux Bus driver model. Each
-client is registered as device on the the transport bus (ishtp bus).
+client is registered as device on the transport bus (ishtp bus).
Enumeration sequence of messages:
diff --git a/Documentation/hwmon/acpi_power_meter.rst b/Documentation/hwmon/acpi_power_meter.rst
index 4a0941a..8628c11 100644
--- a/Documentation/hwmon/acpi_power_meter.rst
+++ b/Documentation/hwmon/acpi_power_meter.rst
@@ -9,7 +9,7 @@
Prefix: 'power_meter'
- Datasheet: http://acpi.info/, section 10.4.
+ Datasheet: https://uefi.org/specifications, section 10.4.
Author: Darrick J. Wong
diff --git a/Documentation/hwmon/adc128d818.rst b/Documentation/hwmon/adc128d818.rst
index 6753468..d248802 100644
--- a/Documentation/hwmon/adc128d818.rst
+++ b/Documentation/hwmon/adc128d818.rst
@@ -9,7 +9,7 @@
Addresses scanned: I2C 0x1d, 0x1e, 0x1f, 0x2d, 0x2e, 0x2f
- Datasheet: Publicly available at the TI website http://www.ti.com/
+ Datasheet: Publicly available at the TI website https://www.ti.com/
Author: Guenter Roeck
diff --git a/Documentation/hwmon/adm1026.rst b/Documentation/hwmon/adm1026.rst
index 35d63e6..66f996f 100644
--- a/Documentation/hwmon/adm1026.rst
+++ b/Documentation/hwmon/adm1026.rst
@@ -10,7 +10,7 @@
Datasheet: Publicly available at the Analog Devices website
- http://www.onsemi.com/PowerSolutions/product.do?id=ADM1026
+ https://www.onsemi.com/PowerSolutions/product.do?id=ADM1026
Authors:
- Philip Pokorny <ppokorny@penguincomputing.com> for Penguin Computing
diff --git a/Documentation/hwmon/adm1031.rst b/Documentation/hwmon/adm1031.rst
index a677c3a..be74ec1 100644
--- a/Documentation/hwmon/adm1031.rst
+++ b/Documentation/hwmon/adm1031.rst
@@ -10,7 +10,7 @@
Datasheet: Publicly available at the Analog Devices website
- http://www.analog.com/en/prod/0%2C2877%2CADM1030%2C00.html
+ https://www.analog.com/en/prod/0%2C2877%2CADM1030%2C00.html
* Analog Devices ADM1031
@@ -20,7 +20,7 @@
Datasheet: Publicly available at the Analog Devices website
- http://www.analog.com/en/prod/0%2C2877%2CADM1031%2C00.html
+ https://www.analog.com/en/prod/0%2C2877%2CADM1031%2C00.html
Authors:
- Alexandre d'Alton <alex@alexdalton.org>
diff --git a/Documentation/hwmon/adm1275.rst b/Documentation/hwmon/adm1275.rst
index 49966ed..ce6528f 100644
--- a/Documentation/hwmon/adm1275.rst
+++ b/Documentation/hwmon/adm1275.rst
@@ -49,7 +49,7 @@
Addresses scanned: -
- Datasheet: http://www.analog.com/media/en/technical-documentation/data-sheets/ADM1293_1294.pdf
+ Datasheet: https://www.analog.com/media/en/technical-documentation/data-sheets/ADM1293_1294.pdf
Author: Guenter Roeck <linux@roeck-us.net>
diff --git a/Documentation/hwmon/adt7410.rst b/Documentation/hwmon/adt7410.rst
index 24caaa8..3f5a435 100644
--- a/Documentation/hwmon/adt7410.rst
+++ b/Documentation/hwmon/adt7410.rst
@@ -11,7 +11,7 @@
Datasheet: Publicly available at the Analog Devices website
- http://www.analog.com/static/imported-files/data_sheets/ADT7410.pdf
+ https://www.analog.com/static/imported-files/data_sheets/ADT7410.pdf
* Analog Devices ADT7420
Prefix: 'adt7420'
@@ -20,7 +20,7 @@
Datasheet: Publicly available at the Analog Devices website
- http://www.analog.com/static/imported-files/data_sheets/ADT7420.pdf
+ https://www.analog.com/static/imported-files/data_sheets/ADT7420.pdf
* Analog Devices ADT7310
@@ -30,7 +30,7 @@
Datasheet: Publicly available at the Analog Devices website
- http://www.analog.com/static/imported-files/data_sheets/ADT7310.pdf
+ https://www.analog.com/static/imported-files/data_sheets/ADT7310.pdf
* Analog Devices ADT7320
@@ -40,7 +40,7 @@
Datasheet: Publicly available at the Analog Devices website
- http://www.analog.com/static/imported-files/data_sheets/ADT7320.pdf
+ https://www.analog.com/static/imported-files/data_sheets/ADT7320.pdf
Author: Hartmut Knaack <knaack.h@gmx.de>
diff --git a/Documentation/hwmon/corsair-cpro.rst b/Documentation/hwmon/corsair-cpro.rst
new file mode 100644
index 0000000..751f954
--- /dev/null
+++ b/Documentation/hwmon/corsair-cpro.rst
@@ -0,0 +1,41 @@
+.. SPDX-License-Identifier: GPL-2.0-or-later
+
+Kernel driver corsair-cpro
+==========================
+
+Supported devices:
+
+ * Corsair Commander Pro
+ * Corsair Commander Pro (1000D)
+
+Author: Marius Zachmann
+
+Description
+-----------
+
+This driver implements the sysfs interface for the Corsair Commander Pro.
+The Corsair Commander Pro is a USB device with 6 fan connectors,
+4 temperature sensor connectors and 2 Corsair LED connectors.
+It can read the voltage levels on the SATA power connector.
+
+Usage Notes
+-----------
+
+Since it is a USB device, hotswapping is possible. The device is autodetected.
+
+Sysfs entries
+-------------
+
+======================= =====================================================================
+in0_input Voltage on SATA 12v
+in1_input Voltage on SATA 5v
+in2_input Voltage on SATA 3.3v
+temp[1-4]_input Temperature on connected temperature sensors
+fan[1-6]_input Connected fan rpm.
+fan[1-6]_label Shows fan type as detected by the device.
+fan[1-6]_target Sets fan speed target rpm.
+ When reading, it reports the last value if it was set by the driver.
+ Otherwise returns an error.
+pwm[1-6] Sets the fan speed. Values from 0-255. Can only be read if pwm
+ was set directly.
+======================= =====================================================================
diff --git a/Documentation/hwmon/emc1403.rst b/Documentation/hwmon/emc1403.rst
index 3a4913b..0de9616 100644
--- a/Documentation/hwmon/emc1403.rst
+++ b/Documentation/hwmon/emc1403.rst
@@ -12,7 +12,7 @@
Datasheets:
- http://ww1.microchip.com/downloads/en/DeviceDoc/1412.pdf
- - http://ww1.microchip.com/downloads/en/DeviceDoc/1402.pdf
+ - https://ww1.microchip.com/downloads/en/DeviceDoc/1402.pdf
* SMSC / Microchip EMC1403, EMC1404, EMC1413, EMC1414
@@ -33,7 +33,7 @@
Datasheet:
- - http://ww1.microchip.com/downloads/en/DeviceDoc/1422.pdf
+ - https://ww1.microchip.com/downloads/en/DeviceDoc/1422.pdf
* SMSC / Microchip EMC1423, EMC1424
@@ -43,7 +43,7 @@
Datasheet:
- - http://ww1.microchip.com/downloads/en/DeviceDoc/1423_1424.pdf
+ - https://ww1.microchip.com/downloads/en/DeviceDoc/1423_1424.pdf
Author:
Kalhan Trisal <kalhan.trisal@intel.com
diff --git a/Documentation/hwmon/f71882fg.rst b/Documentation/hwmon/f71882fg.rst
index 5c0b7b0..38e30fb 100644
--- a/Documentation/hwmon/f71882fg.rst
+++ b/Documentation/hwmon/f71882fg.rst
@@ -145,7 +145,7 @@
properly.
Note that the lowest numbered temperature zone trip point corresponds to
-to the border between the highest and one but highest temperature zones, and
+the border between the highest and one but highest temperature zones, and
vica versa. So the temperature zone trip points 1-4 (or 1-2) go from high temp
to low temp! This is how things are implemented in the IC, and the driver
mimics this.
diff --git a/Documentation/hwmon/ina209.rst b/Documentation/hwmon/ina209.rst
index 6432207..1622561 100644
--- a/Documentation/hwmon/ina209.rst
+++ b/Documentation/hwmon/ina209.rst
@@ -10,7 +10,7 @@
Addresses scanned: -
Datasheet:
- http://www.ti.com/lit/gpn/ina209
+ https://www.ti.com/lit/gpn/ina209
Author:
- Paul Hays <Paul.Hays@cattail.ca>
diff --git a/Documentation/hwmon/ina2xx.rst b/Documentation/hwmon/ina2xx.rst
index ed81f54..f78a5cd 100644
--- a/Documentation/hwmon/ina2xx.rst
+++ b/Documentation/hwmon/ina2xx.rst
@@ -11,7 +11,7 @@
Datasheet: Publicly available at the Texas Instruments website
- http://www.ti.com/
+ https://www.ti.com/
* Texas Instruments INA220
@@ -21,7 +21,7 @@
Datasheet: Publicly available at the Texas Instruments website
- http://www.ti.com/
+ https://www.ti.com/
* Texas Instruments INA226
@@ -31,7 +31,7 @@
Datasheet: Publicly available at the Texas Instruments website
- http://www.ti.com/
+ https://www.ti.com/
* Texas Instruments INA230
@@ -41,7 +41,7 @@
Datasheet: Publicly available at the Texas Instruments website
- http://www.ti.com/
+ https://www.ti.com/
* Texas Instruments INA231
@@ -51,7 +51,7 @@
Datasheet: Publicly available at the Texas Instruments website
- http://www.ti.com/
+ https://www.ti.com/
Author: Lothar Felten <lothar.felten@gmail.com>
diff --git a/Documentation/hwmon/ina3221.rst b/Documentation/hwmon/ina3221.rst
index 297f732..8c12c54 100644
--- a/Documentation/hwmon/ina3221.rst
+++ b/Documentation/hwmon/ina3221.rst
@@ -11,7 +11,7 @@
Datasheet: Publicly available at the Texas Instruments website
- http://www.ti.com/
+ https://www.ti.com/
Author: Andrew F. Davis <afd@ti.com>
diff --git a/Documentation/hwmon/index.rst b/Documentation/hwmon/index.rst
index 55ff4b7..750d3a97 100644
--- a/Documentation/hwmon/index.rst
+++ b/Documentation/hwmon/index.rst
@@ -47,6 +47,7 @@
bel-pfe
bt1-pvt
coretemp
+ corsair-cpro
da9052
da9055
dell-smm-hwmon
diff --git a/Documentation/hwmon/jc42.rst b/Documentation/hwmon/jc42.rst
index 5b14b49..19d1051 100644
--- a/Documentation/hwmon/jc42.rst
+++ b/Documentation/hwmon/jc42.rst
@@ -7,7 +7,7 @@
Datasheets:
- http://www.analog.com/static/imported-files/data_sheets/ADT7408.pdf
+ https://www.analog.com/static/imported-files/data_sheets/ADT7408.pdf
* Atmel AT30TS00, AT30TS002A/B, AT30TSE004A
@@ -39,37 +39,37 @@
Datasheets:
- http://ww1.microchip.com/downloads/en/DeviceDoc/22203C.pdf
+ https://ww1.microchip.com/downloads/en/DeviceDoc/22203C.pdf
- http://ww1.microchip.com/downloads/en/DeviceDoc/21977b.pdf
+ https://ww1.microchip.com/downloads/en/DeviceDoc/21977b.pdf
- http://ww1.microchip.com/downloads/en/DeviceDoc/25095A.pdf
+ https://ww1.microchip.com/downloads/en/DeviceDoc/25095A.pdf
- http://ww1.microchip.com/downloads/en/DeviceDoc/21996a.pdf
+ https://ww1.microchip.com/downloads/en/DeviceDoc/21996a.pdf
- http://ww1.microchip.com/downloads/en/DeviceDoc/22153c.pdf
+ https://ww1.microchip.com/downloads/en/DeviceDoc/22153c.pdf
- http://ww1.microchip.com/downloads/en/DeviceDoc/22327A.pdf
+ https://ww1.microchip.com/downloads/en/DeviceDoc/22327A.pdf
* NXP Semiconductors SE97, SE97B, SE98, SE98A
Datasheets:
- http://www.nxp.com/documents/data_sheet/SE97.pdf
+ https://www.nxp.com/documents/data_sheet/SE97.pdf
- http://www.nxp.com/documents/data_sheet/SE97B.pdf
+ https://www.nxp.com/documents/data_sheet/SE97B.pdf
- http://www.nxp.com/documents/data_sheet/SE98.pdf
+ https://www.nxp.com/documents/data_sheet/SE98.pdf
- http://www.nxp.com/documents/data_sheet/SE98A.pdf
+ https://www.nxp.com/documents/data_sheet/SE98A.pdf
* ON Semiconductor CAT34TS02, CAT6095
Datasheet:
- http://www.onsemi.com/pub_link/Collateral/CAT34TS02-D.PDF
+ https://www.onsemi.com/pub_link/Collateral/CAT34TS02-D.PDF
- http://www.onsemi.com/pub/Collateral/CAT6095-D.PDF
+ https://www.onsemi.com/pub/Collateral/CAT6095-D.PDF
* ST Microelectronics STTS424, STTS424E02, STTS2002, STTS2004, STTS3000
diff --git a/Documentation/hwmon/k8temp.rst b/Documentation/hwmon/k8temp.rst
index fe91095..ab25a73 100644
--- a/Documentation/hwmon/k8temp.rst
+++ b/Documentation/hwmon/k8temp.rst
@@ -9,7 +9,7 @@
Addresses scanned: PCI space
- Datasheet: http://www.amd.com/system/files/TechDocs/32559.pdf
+ Datasheet: https://www.amd.com/system/files/TechDocs/32559.pdf
Author: Rudolf Marek
diff --git a/Documentation/hwmon/lm25066.rst b/Documentation/hwmon/lm25066.rst
index 30e6e77..9f1d7e4 100644
--- a/Documentation/hwmon/lm25066.rst
+++ b/Documentation/hwmon/lm25066.rst
@@ -11,9 +11,9 @@
Datasheets:
- http://www.ti.com/lit/gpn/lm25056
+ https://www.ti.com/lit/gpn/lm25056
- http://www.ti.com/lit/gpn/lm25056a
+ https://www.ti.com/lit/gpn/lm25056a
* National Semiconductor LM25066
@@ -55,7 +55,7 @@
Datasheet:
- http://www.ti.com/product/LM5066I
+ https://www.ti.com/product/LM5066I
Author: Guenter Roeck <linux@roeck-us.net>
diff --git a/Documentation/hwmon/lm63.rst b/Documentation/hwmon/lm63.rst
index f478132..9e27367 100644
--- a/Documentation/hwmon/lm63.rst
+++ b/Documentation/hwmon/lm63.rst
@@ -39,7 +39,7 @@
Thanks go to Tyan and especially Alex Buckingham for setting up a remote
access to their S4882 test platform for this driver.
- http://www.tyan.com/
+ https://www.tyan.com/
Description
-----------
diff --git a/Documentation/hwmon/lm70.rst b/Documentation/hwmon/lm70.rst
index f259bc1..6ddc5b6 100644
--- a/Documentation/hwmon/lm70.rst
+++ b/Documentation/hwmon/lm70.rst
@@ -13,15 +13,15 @@
* Texas Instruments TMP122/TMP124
- Information: http://www.ti.com/product/tmp122
+ Information: https://www.ti.com/product/tmp122
* National Semiconductor LM71
- Datasheet: http://www.ti.com/product/LM71
+ Datasheet: https://www.ti.com/product/LM71
* National Semiconductor LM74
- Datasheet: http://www.ti.com/product/LM74
+ Datasheet: https://www.ti.com/product/LM74
Author:
diff --git a/Documentation/hwmon/lm73.rst b/Documentation/hwmon/lm73.rst
index 1d6a468..74e909b 100644
--- a/Documentation/hwmon/lm73.rst
+++ b/Documentation/hwmon/lm73.rst
@@ -11,7 +11,7 @@
Datasheet: Publicly available at the Texas Instruments website
- http://www.ti.com/product/lm73
+ https://www.ti.com/product/lm73
Author: Guillaume Ligneul <guillaume.ligneul@gmail.com>
diff --git a/Documentation/hwmon/lm75.rst b/Documentation/hwmon/lm75.rst
index e749f827..81257d5 100644
--- a/Documentation/hwmon/lm75.rst
+++ b/Documentation/hwmon/lm75.rst
@@ -31,7 +31,7 @@
Datasheet: Publicly available at the Maxim website
- http://www.maximintegrated.com/
+ https://www.maximintegrated.com/
* Maxim MAX6625, MAX6626, MAX31725, MAX31726
@@ -71,7 +71,7 @@
Datasheet: Publicly available at the Analog Devices website
- http://www.analog.com/adt75
+ https://www.analog.com/adt75
* ST Microelectronics STDS75
@@ -101,23 +101,23 @@
Datasheet: Publicly available at the Texas Instruments website
- http://www.ti.com/product/tmp100
+ https://www.ti.com/product/tmp100
- http://www.ti.com/product/tmp101
+ https://www.ti.com/product/tmp101
- http://www.ti.com/product/tmp105
+ https://www.ti.com/product/tmp105
- http://www.ti.com/product/tmp112
+ https://www.ti.com/product/tmp112
- http://www.ti.com/product/tmp75
+ https://www.ti.com/product/tmp75
- http://www.ti.com/product/tmp75b
+ https://www.ti.com/product/tmp75b
- http://www.ti.com/product/tmp75c
+ https://www.ti.com/product/tmp75c
- http://www.ti.com/product/tmp175
+ https://www.ti.com/product/tmp175
- http://www.ti.com/product/tmp275
+ https://www.ti.com/product/tmp275
* NXP LM75B, PCT2075
@@ -127,9 +127,9 @@
Datasheet: Publicly available at the NXP website
- http://www.nxp.com/documents/data_sheet/LM75B.pdf
+ https://www.nxp.com/documents/data_sheet/LM75B.pdf
- http://www.nxp.com/docs/en/data-sheet/PCT2075.pdf
+ https://www.nxp.com/docs/en/data-sheet/PCT2075.pdf
Author: Frodo Looijaard <frodol@dds.nl>
diff --git a/Documentation/hwmon/lm85.rst b/Documentation/hwmon/lm85.rst
index faa92f5..55e1d9c 100644
--- a/Documentation/hwmon/lm85.rst
+++ b/Documentation/hwmon/lm85.rst
@@ -17,7 +17,7 @@
Addresses scanned: I2C 0x2c, 0x2d, 0x2e
- Datasheet: http://www.ti.com/lit/ds/symlink/lm96000.pdf
+ Datasheet: https://www.ti.com/lit/ds/symlink/lm96000.pdf
* Analog Devices ADM1027
@@ -25,7 +25,7 @@
Addresses scanned: I2C 0x2c, 0x2d, 0x2e
- Datasheet: http://www.onsemi.com/PowerSolutions/product.do?id=ADM1027
+ Datasheet: https://www.onsemi.com/PowerSolutions/product.do?id=ADM1027
* Analog Devices ADT7463
@@ -33,7 +33,7 @@
Addresses scanned: I2C 0x2c, 0x2d, 0x2e
- Datasheet: http://www.onsemi.com/PowerSolutions/product.do?id=ADT7463
+ Datasheet: https://www.onsemi.com/PowerSolutions/product.do?id=ADT7463
* Analog Devices ADT7468
@@ -41,7 +41,7 @@
Addresses scanned: I2C 0x2c, 0x2d, 0x2e
- Datasheet: http://www.onsemi.com/PowerSolutions/product.do?id=ADT7468
+ Datasheet: https://www.onsemi.com/PowerSolutions/product.do?id=ADT7468
* SMSC EMC6D100, SMSC EMC6D101
diff --git a/Documentation/hwmon/lm87.rst b/Documentation/hwmon/lm87.rst
index 72fcb57..b8fec56 100644
--- a/Documentation/hwmon/lm87.rst
+++ b/Documentation/hwmon/lm87.rst
@@ -17,7 +17,7 @@
Addresses scanned: I2C 0x2c - 0x2e
- Datasheet: http://www.analog.com/en/prod/0,2877,ADM1024,00.html
+ Datasheet: https://www.analog.com/en/prod/0,2877,ADM1024,00.html
Authors:
diff --git a/Documentation/hwmon/lm90.rst b/Documentation/hwmon/lm90.rst
index 78dfc01..3da8c6e 100644
--- a/Documentation/hwmon/lm90.rst
+++ b/Documentation/hwmon/lm90.rst
@@ -51,7 +51,7 @@
Datasheet: Publicly available at the ON Semiconductor website
- http://www.onsemi.com/PowerSolutions/product.do?id=ADM1032
+ https://www.onsemi.com/PowerSolutions/product.do?id=ADM1032
* Analog Devices ADT7461
@@ -61,7 +61,7 @@
Datasheet: Publicly available at the ON Semiconductor website
- http://www.onsemi.com/PowerSolutions/product.do?id=ADT7461
+ https://www.onsemi.com/PowerSolutions/product.do?id=ADT7461
* Analog Devices ADT7461A
@@ -71,7 +71,7 @@
Datasheet: Publicly available at the ON Semiconductor website
- http://www.onsemi.com/PowerSolutions/product.do?id=ADT7461A
+ https://www.onsemi.com/PowerSolutions/product.do?id=ADT7461A
* ON Semiconductor NCT1008
@@ -81,7 +81,7 @@
Datasheet: Publicly available at the ON Semiconductor website
- http://www.onsemi.com/PowerSolutions/product.do?id=NCT1008
+ https://www.onsemi.com/PowerSolutions/product.do?id=NCT1008
* Maxim MAX6646
@@ -263,7 +263,7 @@
Datasheet: Publicly available at TI website
- http://www.ti.com/litv/pdf/sbos686
+ https://www.ti.com/litv/pdf/sbos686
Author: Jean Delvare <jdelvare@suse.de>
diff --git a/Documentation/hwmon/lm93.rst b/Documentation/hwmon/lm93.rst
index 49d199b..369e158 100644
--- a/Documentation/hwmon/lm93.rst
+++ b/Documentation/hwmon/lm93.rst
@@ -133,7 +133,7 @@
four signals are measured within 4 seconds.
Smart tach mode is enabled by the driver by writing 1 or 2 (associating the
-the fan tachometer with a pwm) to the sysfs file fan<n>_smart_tach. A zero
+fan tachometer with a pwm) to the sysfs file fan<n>_smart_tach. A zero
will disable the function for that fan. Note that Smart tach mode cannot be
enabled if the PWM output frequency is 22500 Hz (see below).
diff --git a/Documentation/hwmon/lm95234.rst b/Documentation/hwmon/lm95234.rst
index e4c14be..a44e8f5 100644
--- a/Documentation/hwmon/lm95234.rst
+++ b/Documentation/hwmon/lm95234.rst
@@ -9,7 +9,7 @@
Datasheet: Publicly available at the Texas Instruments website
- http://www.ti.com/product/lm95233
+ https://www.ti.com/product/lm95233
* National Semiconductor / Texas Instruments LM95234
@@ -17,7 +17,7 @@
Datasheet: Publicly available at the Texas Instruments website
- http://www.ti.com/product/lm95234
+ https://www.ti.com/product/lm95234
Author: Guenter Roeck <linux@roeck-us.net>
diff --git a/Documentation/hwmon/lm95245.rst b/Documentation/hwmon/lm95245.rst
index 566d1dc..836d9a3 100644
--- a/Documentation/hwmon/lm95245.rst
+++ b/Documentation/hwmon/lm95245.rst
@@ -9,7 +9,7 @@
Datasheet: Publicly available at the TI website
- http://www.ti.com/lit/ds/symlink/lm95235.pdf
+ https://www.ti.com/lit/ds/symlink/lm95235.pdf
* TI / National Semiconductor LM95245
@@ -17,7 +17,7 @@
Datasheet: Publicly available at the TI website
- http://www.ti.com/lit/ds/symlink/lm95245.pdf
+ https://www.ti.com/lit/ds/symlink/lm95245.pdf
Author: Alexander Stein <alexander.stein@systec-electronic.com>
diff --git a/Documentation/hwmon/ltc2978.rst b/Documentation/hwmon/ltc2978.rst
index bc5270e..b99a639 100644
--- a/Documentation/hwmon/ltc2978.rst
+++ b/Documentation/hwmon/ltc2978.rst
@@ -179,7 +179,7 @@
Addresses scanned: -
- Datasheet: http://www.analog.com/ltm4680
+ Datasheet: https://www.analog.com/ltm4680
* Analog Devices LTM4686
@@ -187,7 +187,7 @@
Addresses scanned: -
- Datasheet: http://www.analog.com/ltm4686
+ Datasheet: https://www.analog.com/ltm4686
* Analog Devices LTM4700
@@ -195,7 +195,7 @@
Addresses scanned: -
- Datasheet: http://www.analog.com/ltm4700
+ Datasheet: https://www.analog.com/ltm4700
diff --git a/Documentation/hwmon/max20730.rst b/Documentation/hwmon/max20730.rst
index cea7ae5..cb0c95b 100644
--- a/Documentation/hwmon/max20730.rst
+++ b/Documentation/hwmon/max20730.rst
@@ -5,6 +5,14 @@
Supported chips:
+ * Maxim MAX20710
+
+ Prefix: 'max20710'
+
+ Addresses scanned: -
+
+ Datasheet: https://datasheets.maximintegrated.com/en/ds/MAX20710.pdf
+
* Maxim MAX20730
Prefix: 'max20730'
@@ -35,7 +43,7 @@
Description
-----------
-This driver implements support for Maxim MAX20730, MAX20734, and MAX20743
+This driver implements support for Maxim MAX20710, MAX20730, MAX20734, and MAX20743
Integrated, Step-Down Switching Regulators with PMBus support.
The driver is a client driver to the core PMBus driver.
diff --git a/Documentation/hwmon/max20751.rst b/Documentation/hwmon/max20751.rst
index fe701e0..f9febef 100644
--- a/Documentation/hwmon/max20751.rst
+++ b/Documentation/hwmon/max20751.rst
@@ -9,9 +9,9 @@
Addresses scanned: -
- Datasheet: http://datasheets.maximintegrated.com/en/ds/MAX20751.pdf
+ Datasheet: https://datasheets.maximintegrated.com/en/ds/MAX20751.pdf
- Application note: http://pdfserv.maximintegrated.com/en/an/AN5941.pdf
+ Application note: https://pdfserv.maximintegrated.com/en/an/AN5941.pdf
Author: Guenter Roeck <linux@roeck-us.net>
diff --git a/Documentation/hwmon/max31790.rst b/Documentation/hwmon/max31790.rst
index 84c62a1..f301385d 100644
--- a/Documentation/hwmon/max31790.rst
+++ b/Documentation/hwmon/max31790.rst
@@ -9,7 +9,7 @@
Addresses scanned: -
- Datasheet: http://pdfserv.maximintegrated.com/en/ds/MAX31790.pdf
+ Datasheet: https://pdfserv.maximintegrated.com/en/ds/MAX31790.pdf
Author: Il Han <corone.il.han@gmail.com>
diff --git a/Documentation/hwmon/max34440.rst b/Documentation/hwmon/max34440.rst
index 5744df1..162d289 100644
--- a/Documentation/hwmon/max34440.rst
+++ b/Documentation/hwmon/max34440.rst
@@ -9,7 +9,7 @@
Addresses scanned: -
- Datasheet: http://datasheets.maximintegrated.com/en/ds/MAX34440.pdf
+ Datasheet: https://datasheets.maximintegrated.com/en/ds/MAX34440.pdf
* Maxim MAX34441
@@ -19,7 +19,7 @@
Addresses scanned: -
- Datasheet: http://datasheets.maximintegrated.com/en/ds/MAX34441.pdf
+ Datasheet: https://datasheets.maximintegrated.com/en/ds/MAX34441.pdf
* Maxim MAX34446
@@ -29,7 +29,7 @@
Addresses scanned: -
- Datasheet: http://datasheets.maximintegrated.com/en/ds/MAX34446.pdf
+ Datasheet: https://datasheets.maximintegrated.com/en/ds/MAX34446.pdf
* Maxim MAX34451
@@ -39,7 +39,7 @@
Addresses scanned: -
- Datasheet: http://datasheets.maximintegrated.com/en/ds/MAX34451.pdf
+ Datasheet: https://datasheets.maximintegrated.com/en/ds/MAX34451.pdf
* Maxim MAX34460
@@ -49,7 +49,7 @@
Addresses scanned: -
- Datasheet: http://datasheets.maximintegrated.com/en/ds/MAX34460.pdf
+ Datasheet: https://datasheets.maximintegrated.com/en/ds/MAX34460.pdf
* Maxim MAX34461
@@ -59,7 +59,7 @@
Addresses scanned: -
- Datasheet: http://datasheets.maximintegrated.com/en/ds/MAX34461.pdf
+ Datasheet: https://datasheets.maximintegrated.com/en/ds/MAX34461.pdf
Author: Guenter Roeck <linux@roeck-us.net>
diff --git a/Documentation/hwmon/nct6775.rst b/Documentation/hwmon/nct6775.rst
index 1d0315c..5ba8276 100644
--- a/Documentation/hwmon/nct6775.rst
+++ b/Documentation/hwmon/nct6775.rst
@@ -276,5 +276,5 @@
will not reflect a usable value. It often reports unreasonably high
temperatures, and in some cases the reported temperature declines if the actual
temperature increases (similar to the raw PECI temperature value - see PECI
-specification for details). CPUTIN should therefore be be ignored on ASUS
+specification for details). CPUTIN should therefore be ignored on ASUS
boards. The CPU temperature on ASUS boards is reported from PECI 0.
diff --git a/Documentation/hwmon/pmbus.rst b/Documentation/hwmon/pmbus.rst
index 2658dde..66b3e89 100644
--- a/Documentation/hwmon/pmbus.rst
+++ b/Documentation/hwmon/pmbus.rst
@@ -21,11 +21,11 @@
Datasheets:
- http://www.onsemi.com/pub_link/Collateral/ADP4000-D.PDF
+ https://www.onsemi.com/pub_link/Collateral/ADP4000-D.PDF
- http://www.onsemi.com/pub_link/Collateral/NCP4200-D.PDF
+ https://www.onsemi.com/pub_link/Collateral/NCP4200-D.PDF
- http://www.onsemi.com/pub_link/Collateral/JUNE%202009-%20REV.%200.PDF
+ https://www.onsemi.com/pub_link/Collateral/JUNE%202009-%20REV.%200.PDF
* Lineage Power
@@ -53,15 +53,15 @@
Datasheets:
- http://www.ti.com/lit/gpn/tps40400
+ https://www.ti.com/lit/gpn/tps40400
- http://www.ti.com/lit/gpn/tps544b20
+ https://www.ti.com/lit/gpn/tps544b20
- http://www.ti.com/lit/gpn/tps544b25
+ https://www.ti.com/lit/gpn/tps544b25
- http://www.ti.com/lit/gpn/tps544c20
+ https://www.ti.com/lit/gpn/tps544c20
- http://www.ti.com/lit/gpn/tps544c25
+ https://www.ti.com/lit/gpn/tps544c25
* Maxim MAX20796
diff --git a/Documentation/hwmon/sht21.rst b/Documentation/hwmon/sht21.rst
index f1f5da0..1bccc8e 100644
--- a/Documentation/hwmon/sht21.rst
+++ b/Documentation/hwmon/sht21.rst
@@ -11,7 +11,7 @@
Datasheet: Publicly available at the Sensirion website
- http://www.sensirion.com/file/datasheet_sht21
+ https://www.sensirion.com/file/datasheet_sht21
@@ -23,7 +23,7 @@
Datasheet: Publicly available at the Sensirion website
- http://www.sensirion.com/file/datasheet_sht25
+ https://www.sensirion.com/file/datasheet_sht25
diff --git a/Documentation/hwmon/shtc1.rst b/Documentation/hwmon/shtc1.rst
index 08380f2..f38c4c9 100644
--- a/Documentation/hwmon/shtc1.rst
+++ b/Documentation/hwmon/shtc1.rst
@@ -9,7 +9,7 @@
Addresses scanned: none
- Datasheet: http://www.sensirion.com/file/datasheet_shtc1
+ Datasheet: https://www.sensirion.com/file/datasheet_shtc1
@@ -19,7 +19,7 @@
Addresses scanned: none
- Datasheet: http://www.sensirion.com/file/datasheet_shtw1
+ Datasheet: https://www.sensirion.com/file/datasheet_shtw1
@@ -29,7 +29,7 @@
Addresses scanned: none
- Datasheet: http://www.sensirion.com/file/datasheet_shtc3
+ Datasheet: https://www.sensirion.com/file/datasheet_shtc3
diff --git a/Documentation/hwmon/sparx5-temp.rst b/Documentation/hwmon/sparx5-temp.rst
new file mode 100644
index 0000000..0140809
--- /dev/null
+++ b/Documentation/hwmon/sparx5-temp.rst
@@ -0,0 +1,33 @@
+.. SPDX-License-Identifier: GPL-2.0-only
+
+Microchip SparX-5 SoC
+=====================
+
+Supported chips:
+
+ * VSC7546, VSC7549, VSC755, VSC7556, and VSC7558 (Sparx5 series)
+
+ Prefix: 'sparx5-temp'
+
+ Addresses scanned: -
+
+ Datasheet: Provided by Microchip upon request and under NDA
+
+Author: Lars Povlsen <lars.povlsen@microchip.com>
+
+Description
+-----------
+
+The Sparx5 SoC contains a temperature sensor based on the MR74060
+Moortec IP.
+
+The sensor has a range of -40°C to +125°C and an accuracy of +/-5°C.
+
+Sysfs entries
+-------------
+
+The following attributes are supported.
+
+======================= ========================================================
+temp1_input Die temperature (in millidegree Celsius.)
+======================= ========================================================
diff --git a/Documentation/hwmon/thmc50.rst b/Documentation/hwmon/thmc50.rst
index cfff388..090f040 100644
--- a/Documentation/hwmon/thmc50.rst
+++ b/Documentation/hwmon/thmc50.rst
@@ -17,7 +17,7 @@
Addresses scanned: I2C 0x2c - 0x2e
- Datasheet: http://www.ti.com/
+ Datasheet: https://www.ti.com/
Author: Krzysztof Helt <krzysztof.h1@wp.pl>
diff --git a/Documentation/hwmon/tmp103.rst b/Documentation/hwmon/tmp103.rst
index 205de61..e195a7d 100644
--- a/Documentation/hwmon/tmp103.rst
+++ b/Documentation/hwmon/tmp103.rst
@@ -9,7 +9,7 @@
Addresses scanned: none
- Product info and datasheet: http://www.ti.com/product/tmp103
+ Product info and datasheet: https://www.ti.com/product/tmp103
Author:
diff --git a/Documentation/hwmon/tmp108.rst b/Documentation/hwmon/tmp108.rst
index 5f4266a..6df7cf1 100644
--- a/Documentation/hwmon/tmp108.rst
+++ b/Documentation/hwmon/tmp108.rst
@@ -9,7 +9,7 @@
Addresses scanned: none
- Datasheet: http://www.ti.com/product/tmp108
+ Datasheet: https://www.ti.com/product/tmp108
Author:
diff --git a/Documentation/hwmon/tmp401.rst b/Documentation/hwmon/tmp401.rst
index 6a05a07..14bf1fb 100644
--- a/Documentation/hwmon/tmp401.rst
+++ b/Documentation/hwmon/tmp401.rst
@@ -47,7 +47,7 @@
Prefix: 'tmp461'
- Datasheet: http://www.ti.com/product/tmp461
+ Datasheet: https://www.ti.com/product/tmp461
diff --git a/Documentation/hwmon/tmp421.rst b/Documentation/hwmon/tmp421.rst
index 1ba926a..ddcd515 100644
--- a/Documentation/hwmon/tmp421.rst
+++ b/Documentation/hwmon/tmp421.rst
@@ -33,7 +33,7 @@
Addresses scanned: I2C 0x2a, 0x4c, 0x4d, 0x4e and 0x4f
- Datasheet: http://www.ti.com/product/tmp441
+ Datasheet: https://www.ti.com/product/tmp441
* Texas Instruments TMP442
@@ -41,7 +41,7 @@
Addresses scanned: I2C 0x4c and 0x4d
- Datasheet: http://www.ti.com/product/tmp442
+ Datasheet: https://www.ti.com/product/tmp442
Authors:
diff --git a/Documentation/hwmon/tmp513.rst b/Documentation/hwmon/tmp513.rst
index 6c8fae4..f2dfc16 100644
--- a/Documentation/hwmon/tmp513.rst
+++ b/Documentation/hwmon/tmp513.rst
@@ -9,13 +9,13 @@
Prefix: 'tmp512'
- Datasheet: http://www.ti.com/lit/ds/symlink/tmp512.pdf
+ Datasheet: https://www.ti.com/lit/ds/symlink/tmp512.pdf
* Texas Instruments TMP513
Prefix: 'tmp513'
- Datasheet: http://www.ti.com/lit/ds/symlink/tmp513.pdf
+ Datasheet: https://www.ti.com/lit/ds/symlink/tmp513.pdf
Authors:
diff --git a/Documentation/hwmon/tps40422.rst b/Documentation/hwmon/tps40422.rst
index 8fe3e1c..32a62cc 100644
--- a/Documentation/hwmon/tps40422.rst
+++ b/Documentation/hwmon/tps40422.rst
@@ -9,7 +9,7 @@
Addresses scanned: -
- Datasheet: http://www.ti.com/lit/gpn/tps40422
+ Datasheet: https://www.ti.com/lit/gpn/tps40422
Author: Zhu Laiwen <richard.zhu@nsn.com>
diff --git a/Documentation/hwmon/tps53679.rst b/Documentation/hwmon/tps53679.rst
index be94cab..c7c589e 100644
--- a/Documentation/hwmon/tps53679.rst
+++ b/Documentation/hwmon/tps53679.rst
@@ -9,7 +9,7 @@
Addresses scanned: -
- Datasheet: http://www.ti.com/lit/gpn/tps53647
+ Datasheet: https://www.ti.com/lit/gpn/tps53647
* Texas Instruments TPS53667
@@ -17,7 +17,7 @@
Addresses scanned: -
- Datasheet: http://www.ti.com/lit/gpn/TPS53667
+ Datasheet: https://www.ti.com/lit/gpn/TPS53667
* Texas Instruments TPS53679
@@ -25,7 +25,7 @@
Addresses scanned: -
- Datasheet: http://www.ti.com/lit/gpn/TPS53679 (short version)
+ Datasheet: https://www.ti.com/lit/gpn/TPS53679 (short version)
* Texas Instruments TPS53681
@@ -33,7 +33,7 @@
Addresses scanned: -
- Datasheet: http://www.ti.com/lit/gpn/TPS53681
+ Datasheet: https://www.ti.com/lit/gpn/TPS53681
* Texas Instruments TPS53688
diff --git a/Documentation/hwmon/w83627ehf.rst b/Documentation/hwmon/w83627ehf.rst
index 74d19ef..7bb557c 100644
--- a/Documentation/hwmon/w83627ehf.rst
+++ b/Documentation/hwmon/w83627ehf.rst
@@ -96,7 +96,7 @@
in tempX_label.
Temperatures are measured in degrees Celsius and measurement resolution is 1
-degC for temp1 and and 0.5 degC for temp2 and temp3. For temp4 and higher,
+degC for temp1 and 0.5 degC for temp2 and temp3. For temp4 and higher,
resolution is 1 degC for W83667HG-B and 0.0 degC for NCT6775F and NCT6776F.
An alarm is triggered when the temperature gets higher than high limit;
it stays on until the temperature falls below the hysteresis value.
diff --git a/Documentation/hwmon/w83781d.rst b/Documentation/hwmon/w83781d.rst
index f36d33d..c2dcb68 100644
--- a/Documentation/hwmon/w83781d.rst
+++ b/Documentation/hwmon/w83781d.rst
@@ -17,7 +17,7 @@
Addresses scanned: I2C 0x28 - 0x2f, ISA 0x290 (8 I/O ports)
- Datasheet: http://www.winbond.com
+ Datasheet: https://www.winbond.com
* Winbond W83783S
diff --git a/Documentation/hwmon/w83l786ng.rst b/Documentation/hwmon/w83l786ng.rst
index 2b77761..06234de 100644
--- a/Documentation/hwmon/w83l786ng.rst
+++ b/Documentation/hwmon/w83l786ng.rst
@@ -36,7 +36,7 @@
degC for temp1 and temp2.
Fan rotation speeds are reported in RPM (rotations per minute). Fan readings
-readings can be divided by a programmable divider (1, 2, 4, 8, 16, 32, 64
+can be divided by a programmable divider (1, 2, 4, 8, 16, 32, 64
or 128 for fan 1/2) to give the readings more range or accuracy.
Voltage sensors (also known as IN sensors) report their values in millivolts.
diff --git a/Documentation/i2c/busses/i2c-i801.rst b/Documentation/i2c/busses/i2c-i801.rst
index b83da0e..faf3233 100644
--- a/Documentation/i2c/busses/i2c-i801.rst
+++ b/Documentation/i2c/busses/i2c-i801.rst
@@ -43,6 +43,7 @@
* Intel Elkhart Lake (PCH)
* Intel Tiger Lake (PCH)
* Intel Jasper Lake (SOC)
+ * Intel Emmitsburg (PCH)
Datasheets: Publicly available at the Intel website
diff --git a/Documentation/i2c/dev-interface.rst b/Documentation/i2c/dev-interface.rst
index bdb247f..73ad348 100644
--- a/Documentation/i2c/dev-interface.rst
+++ b/Documentation/i2c/dev-interface.rst
@@ -159,6 +159,8 @@
__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_block_process_call(int file, __u8 command, __u8 length,
+ __u8 *values);
__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);
diff --git a/Documentation/i2c/index.rst b/Documentation/i2c/index.rst
index fee4744..8a2ad38 100644
--- a/Documentation/i2c/index.rst
+++ b/Documentation/i2c/index.rst
@@ -62,7 +62,6 @@
.. toctree::
:maxdepth: 1
- upgrading-clients
old-module-parameters
.. only:: subproject and html
diff --git a/Documentation/i2c/slave-eeprom-backend.rst b/Documentation/i2c/slave-eeprom-backend.rst
index 0b8cd83..38d951f 100644
--- a/Documentation/i2c/slave-eeprom-backend.rst
+++ b/Documentation/i2c/slave-eeprom-backend.rst
@@ -1,14 +1,26 @@
==============================
-Linux I2C slave eeprom backend
+Linux I2C slave EEPROM backend
==============================
-by Wolfram Sang <wsa@sang-engineering.com> in 2014-15
+by Wolfram Sang <wsa@sang-engineering.com> in 2014-20
-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::
+This backend simulates an EEPROM on the connected I2C bus. Its memory contents
+can be accessed from userspace via this file located in sysfs::
/sys/bus/i2c/devices/<device-directory>/slave-eeprom
+The following types are available: 24c02, 24c32, 24c64, and 24c512. Read-only
+variants are also supported. The name needed for instantiating has the form
+'slave-<type>[ro]'. Examples follow:
+
+24c02, read/write, address 0x64:
+ # echo slave-24c02 0x1064 > /sys/bus/i2c/devices/i2c-1/new_device
+
+24c512, read-only, address 0x42:
+ # echo slave-24c512ro 0x1042 > /sys/bus/i2c/devices/i2c-1/new_device
+
+You can also preload data during boot if a device-property named
+'firmware-name' contains a valid filename (DT or ACPI only).
+
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/smbus-protocol.rst b/Documentation/i2c/smbus-protocol.rst
index c2e2963..64689d1 100644
--- a/Documentation/i2c/smbus-protocol.rst
+++ b/Documentation/i2c/smbus-protocol.rst
@@ -57,7 +57,7 @@
This sends a single bit to the device, at the place of the Rd/Wr bit::
- A Addr Rd/Wr [A] P
+ S Addr Rd/Wr [A] P
Functionality flag: I2C_FUNC_SMBUS_QUICK
diff --git a/Documentation/i2c/upgrading-clients.rst b/Documentation/i2c/upgrading-clients.rst
deleted file mode 100644
index 27d2903..0000000
--- a/Documentation/i2c/upgrading-clients.rst
+++ /dev/null
@@ -1,285 +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/ia64/efirtc.rst b/Documentation/ia64/efirtc.rst
index 2f7ff50..fd83284 100644
--- a/Documentation/ia64/efirtc.rst
+++ b/Documentation/ia64/efirtc.rst
@@ -113,7 +113,7 @@
Read the current state of the alarm::
- ioctl(d, RTC_WKLAM_RD, &wkt)
+ ioctl(d, RTC_WKALM_RD, &wkt)
Set the alarm or change its status::
diff --git a/Documentation/index.rst b/Documentation/index.rst
index 71eca31..5771974 100644
--- a/Documentation/index.rst
+++ b/Documentation/index.rst
@@ -182,6 +182,20 @@
filesystems/ext4/index
+Other documentation
+-------------------
+
+There are several unsorted documents that don't seem to fit on other parts
+of the documentation body, or may require some adjustments and/or conversion
+to ReStructured Text format, or are simply too old.
+
+.. toctree::
+ :maxdepth: 2
+
+ staging/index
+ watch_queue
+
+
Translations
------------
diff --git a/Documentation/input/uinput.rst b/Documentation/input/uinput.rst
index b8e90b6..10c62e6 100644
--- a/Documentation/input/uinput.rst
+++ b/Documentation/input/uinput.rst
@@ -99,7 +99,7 @@
/*
* Give userspace some time to read the events before we destroy the
- * device with UI_DEV_DESTOY.
+ * device with UI_DEV_DESTROY.
*/
sleep(1);
@@ -164,7 +164,7 @@
/*
* Give userspace some time to read the events before we destroy the
- * device with UI_DEV_DESTOY.
+ * device with UI_DEV_DESTROY.
*/
sleep(1);
@@ -233,7 +233,7 @@
/*
* Give userspace some time to read the events before we destroy the
- * device with UI_DEV_DESTOY.
+ * device with UI_DEV_DESTROY.
*/
sleep(1);
diff --git a/Documentation/kbuild/Kconfig.recursion-issue-02 b/Documentation/kbuild/Kconfig.recursion-issue-02
index b9fd56c..df245fd 100644
--- a/Documentation/kbuild/Kconfig.recursion-issue-02
+++ b/Documentation/kbuild/Kconfig.recursion-issue-02
@@ -42,7 +42,7 @@
# "select FW_LOADER" [0], in the end the simple alternative solution to this
# problem consisted on matching semantics with newly introduced features.
#
-# [0] http://lkml.kernel.org/r/1432241149-8762-1-git-send-email-mcgrof@do-not-panic.com
+# [0] https://lkml.kernel.org/r/1432241149-8762-1-git-send-email-mcgrof@do-not-panic.com
mainmenu "Simple example to demo cumulative kconfig recursive dependency implication"
diff --git a/Documentation/kbuild/kconfig-language.rst b/Documentation/kbuild/kconfig-language.rst
index a1601ec..1cf1aeb 100644
--- a/Documentation/kbuild/kconfig-language.rst
+++ b/Documentation/kbuild/kconfig-language.rst
@@ -540,8 +540,8 @@
If you need to expose a compiler capability to makefiles and/or C source files,
`CC_HAS_` is the recommended prefix for the config option::
- config CC_HAS_STACKPROTECTOR_NONE
- def_bool $(cc-option,-fno-stack-protector)
+ config CC_HAS_ASM_GOTO
+ def_bool $(success,$(srctree)/scripts/gcc-goto.sh $(CC))
Build as module only
~~~~~~~~~~~~~~~~~~~~
@@ -681,17 +681,17 @@
find dead code / features (always inactive), 114 dead features were found in
Linux using this methodology [1]_ (Section 8: Threats to validity).
-Confirming this could prove useful as Kconfig stands as one of the the leading
+Confirming this could prove useful as Kconfig stands as one of the leading
industrial variability modeling languages [1]_ [2]_. Its study would help
evaluate practical uses of such languages, their use was only theoretical
and real world requirements were not well understood. As it stands though
only reverse engineering techniques have been used to deduce semantics from
variability modeling languages such as Kconfig [3]_.
-.. [0] http://www.eng.uwaterloo.ca/~shshe/kconfig_semantics.pdf
-.. [1] http://gsd.uwaterloo.ca/sites/default/files/vm-2013-berger.pdf
-.. [2] http://gsd.uwaterloo.ca/sites/default/files/ase241-berger_0.pdf
-.. [3] http://gsd.uwaterloo.ca/sites/default/files/icse2011.pdf
+.. [0] https://www.eng.uwaterloo.ca/~shshe/kconfig_semantics.pdf
+.. [1] https://gsd.uwaterloo.ca/sites/default/files/vm-2013-berger.pdf
+.. [2] https://gsd.uwaterloo.ca/sites/default/files/ase241-berger_0.pdf
+.. [3] https://gsd.uwaterloo.ca/sites/default/files/icse2011.pdf
Full SAT solver for Kconfig
~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -710,10 +710,10 @@
existing projects to not only help advise how to integrate this work upstream
but also help maintain it long term. Interested developers should visit:
-http://kernelnewbies.org/KernelProjects/kconfig-sat
+https://kernelnewbies.org/KernelProjects/kconfig-sat
-.. [4] http://www.cs.cornell.edu/~sabhar/chapters/SATSolvers-KR-Handbook.pdf
-.. [5] http://gsd.uwaterloo.ca/sites/default/files/vm-2013-berger.pdf
+.. [4] https://www.cs.cornell.edu/~sabhar/chapters/SATSolvers-KR-Handbook.pdf
+.. [5] https://gsd.uwaterloo.ca/sites/default/files/vm-2013-berger.pdf
.. [6] https://cados.cs.fau.de
.. [7] https://vamos.cs.fau.de
.. [8] https://undertaker.cs.fau.de
diff --git a/Documentation/kbuild/llvm.rst b/Documentation/kbuild/llvm.rst
index c776b6e..2aac50b 100644
--- a/Documentation/kbuild/llvm.rst
+++ b/Documentation/kbuild/llvm.rst
@@ -76,7 +76,7 @@
Getting LLVM
-------------
-- http://releases.llvm.org/download.html
+- https://releases.llvm.org/download.html
- https://github.com/llvm/llvm-project
- https://llvm.org/docs/GettingStarted.html
- https://llvm.org/docs/CMake.html
diff --git a/Documentation/kbuild/makefiles.rst b/Documentation/kbuild/makefiles.rst
index 6515ebc..b81b891 100644
--- a/Documentation/kbuild/makefiles.rst
+++ b/Documentation/kbuild/makefiles.rst
@@ -368,6 +368,14 @@
subdir-ccflags-y := -Werror
+ ccflags-remove-y, asflags-remove-y
+ These flags are used to remove particular flags for the compiler,
+ assembler invocations.
+
+ Example::
+
+ ccflags-remove-$(CONFIG_MCOUNT) += -pg
+
CFLAGS_$@, AFLAGS_$@
CFLAGS_$@ and AFLAGS_$@ only apply to commands in current
kbuild makefile.
@@ -375,6 +383,9 @@
$(CFLAGS_$@) specifies per-file options for $(CC). The $@
part has a literal value which specifies the file that it is for.
+ CFLAGS_$@ has the higher priority than ccflags-remove-y; CFLAGS_$@
+ can re-add compiler flags that were removed by ccflags-remove-y.
+
Example::
# drivers/scsi/Makefile
@@ -387,6 +398,9 @@
$(AFLAGS_$@) is a similar feature for source files in assembly
languages.
+ AFLAGS_$@ has the higher priority than asflags-remove-y; AFLAGS_$@
+ can re-add assembler flags that were removed by asflags-remove-y.
+
Example::
# arch/arm/kernel/Makefile
@@ -735,6 +749,10 @@
hostprogs := lxdialog
always-y := $(hostprogs)
+ Kbuild provides the following shorthand for this:
+
+ hostprogs-always-y := lxdialog
+
This will tell kbuild to build lxdialog even if not referenced in
any rule.
@@ -817,7 +835,32 @@
5.4 When userspace programs are actually built
----------------------------------------------
- Same as "When host programs are actually built".
+ Kbuild builds userspace programs only when told to do so.
+ There are two ways to do this.
+
+ (1) Add it as the prerequisite of another file
+
+ Example::
+
+ #net/bpfilter/Makefile
+ userprogs := bpfilter_umh
+ $(obj)/bpfilter_umh_blob.o: $(obj)/bpfilter_umh
+
+ $(obj)/bpfilter_umh is built before $(obj)/bpfilter_umh_blob.o
+
+ (2) Use always-y
+
+ Example::
+
+ userprogs := binderfs_example
+ always-y := $(userprogs)
+
+ Kbuild provides the following shorthand for this:
+
+ userprogs-always-y := binderfs_example
+
+ This will tell Kbuild to build binderfs_example when it visits this
+ Makefile.
6 Kbuild clean infrastructure
=============================
diff --git a/Documentation/kbuild/modules.rst b/Documentation/kbuild/modules.rst
index a45cccf..85ccc87 100644
--- a/Documentation/kbuild/modules.rst
+++ b/Documentation/kbuild/modules.rst
@@ -182,7 +182,8 @@
8123_pci.c
8123_bin.o_shipped <= Binary blob
---- 3.1 Shared Makefile
+3.1 Shared Makefile
+-------------------
An external module always includes a wrapper makefile that
supports building the module using "make" with no arguments.
@@ -470,9 +471,9 @@
The syntax of the Module.symvers file is::
- <CRC> <Symbol> <Module> <Export Type> <Namespace>
+ <CRC> <Symbol> <Module> <Export Type> <Namespace>
- 0xe1cc2a05 usb_stor_suspend drivers/usb/storage/usb-storage EXPORT_SYMBOL_GPL USB_STORAGE
+ 0xe1cc2a05 usb_stor_suspend drivers/usb/storage/usb-storage EXPORT_SYMBOL_GPL USB_STORAGE
The fields are separated by tabs and values may be empty (e.g.
if no namespace is defined for an exported symbol).
diff --git a/Documentation/kbuild/reproducible-builds.rst b/Documentation/kbuild/reproducible-builds.rst
index 5033938..3b25655 100644
--- a/Documentation/kbuild/reproducible-builds.rst
+++ b/Documentation/kbuild/reproducible-builds.rst
@@ -101,7 +101,7 @@
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
+``scripts/gcc-plugins/randomize_layout_seed.h`` so the same value
is used in rebuilds.
Debug info conflicts
diff --git a/Documentation/kprobes.txt b/Documentation/kprobes.txt
deleted file mode 100644
index 8baab88..0000000
--- a/Documentation/kprobes.txt
+++ /dev/null
@@ -1,801 +0,0 @@
-=======================
-Kernel Probes (Kprobes)
-=======================
-
-:Author: Jim Keniston <jkenisto@us.ibm.com>
-:Author: Prasanna S Panchamukhi <prasanna.panchamukhi@gmail.com>
-:Author: Masami Hiramatsu <mhiramat@redhat.com>
-
-.. CONTENTS
-
- 1. Concepts: Kprobes, and Return Probes
- 2. Architectures Supported
- 3. Configuring Kprobes
- 4. API Reference
- 5. Kprobes Features and Limitations
- 6. Probe Overhead
- 7. TODO
- 8. Kprobes Example
- 9. Kretprobes Example
- 10. Deprecated Features
- Appendix A: The kprobes debugfs interface
- Appendix B: The kprobes sysctl interface
-
-Concepts: Kprobes and Return Probes
-=========================================
-
-Kprobes enables you to dynamically break into any kernel routine and
-collect debugging and performance information non-disruptively. You
-can trap at almost any kernel code address [1]_, specifying a handler
-routine to be invoked when the breakpoint is hit.
-
-.. [1] some parts of the kernel code can not be trapped, see
- :ref:`kprobes_blacklist`)
-
-There are currently two types of probes: kprobes, and kretprobes
-(also called return probes). A kprobe can be inserted on virtually
-any instruction in the kernel. A return probe fires when a specified
-function returns.
-
-In the typical case, Kprobes-based instrumentation is packaged as
-a kernel module. The module's init function installs ("registers")
-one or more probes, and the exit function unregisters them. A
-registration function such as register_kprobe() specifies where
-the probe is to be inserted and what handler is to be called when
-the probe is hit.
-
-There are also ``register_/unregister_*probes()`` functions for batch
-registration/unregistration of a group of ``*probes``. These functions
-can speed up unregistration process when you have to unregister
-a lot of probes at once.
-
-The next four subsections explain how the different types of
-probes work and how jump optimization works. They explain certain
-things that you'll need to know in order to make the best use of
-Kprobes -- e.g., the difference between a pre_handler and
-a post_handler, and how to use the maxactive and nmissed fields of
-a kretprobe. But if you're in a hurry to start using Kprobes, you
-can skip ahead to :ref:`kprobes_archs_supported`.
-
-How Does a Kprobe Work?
------------------------
-
-When a kprobe is registered, Kprobes makes a copy of the probed
-instruction and replaces the first byte(s) of the probed instruction
-with a breakpoint instruction (e.g., int3 on i386 and x86_64).
-
-When a CPU hits the breakpoint instruction, a trap occurs, the CPU's
-registers are saved, and control passes to Kprobes via the
-notifier_call_chain mechanism. Kprobes executes the "pre_handler"
-associated with the kprobe, passing the handler the addresses of the
-kprobe struct and the saved registers.
-
-Next, Kprobes single-steps its copy of the probed instruction.
-(It would be simpler to single-step the actual instruction in place,
-but then Kprobes would have to temporarily remove the breakpoint
-instruction. This would open a small time window when another CPU
-could sail right past the probepoint.)
-
-After the instruction is single-stepped, Kprobes executes the
-"post_handler," if any, that is associated with the kprobe.
-Execution then continues with the instruction following the probepoint.
-
-Changing Execution Path
------------------------
-
-Since kprobes can probe into a running kernel code, it can change the
-register set, including instruction pointer. This operation requires
-maximum care, such as keeping the stack frame, recovering the execution
-path etc. Since it operates on a running kernel and needs deep knowledge
-of computer architecture and concurrent computing, you can easily shoot
-your foot.
-
-If you change the instruction pointer (and set up other related
-registers) in pre_handler, you must return !0 so that kprobes stops
-single stepping and just returns to the given address.
-This also means post_handler should not be called anymore.
-
-Note that this operation may be harder on some architectures which use
-TOC (Table of Contents) for function call, since you have to setup a new
-TOC for your function in your module, and recover the old one after
-returning from it.
-
-Return Probes
--------------
-
-How Does a Return Probe Work?
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-When you call register_kretprobe(), Kprobes establishes a kprobe at
-the entry to the function. When the probed function is called and this
-probe is hit, Kprobes saves a copy of the return address, and replaces
-the return address with the address of a "trampoline." The trampoline
-is an arbitrary piece of code -- typically just a nop instruction.
-At boot time, Kprobes registers a kprobe at the trampoline.
-
-When the probed function executes its return instruction, control
-passes to the trampoline and that probe is hit. Kprobes' trampoline
-handler calls the user-specified return handler associated with the
-kretprobe, then sets the saved instruction pointer to the saved return
-address, and that's where execution resumes upon return from the trap.
-
-While the probed function is executing, its return address is
-stored in an object of type kretprobe_instance. Before calling
-register_kretprobe(), the user sets the maxactive field of the
-kretprobe struct to specify how many instances of the specified
-function can be probed simultaneously. register_kretprobe()
-pre-allocates the indicated number of kretprobe_instance objects.
-
-For example, if the function is non-recursive and is called with a
-spinlock held, maxactive = 1 should be enough. If the function is
-non-recursive and can never relinquish the CPU (e.g., via a semaphore
-or preemption), NR_CPUS should be enough. If maxactive <= 0, it is
-set to a default value. If CONFIG_PREEMPT is enabled, the default
-is max(10, 2*NR_CPUS). Otherwise, the default is NR_CPUS.
-
-It's not a disaster if you set maxactive too low; you'll just miss
-some probes. In the kretprobe struct, the nmissed field is set to
-zero when the return probe is registered, and is incremented every
-time the probed function is entered but there is no kretprobe_instance
-object available for establishing the return probe.
-
-Kretprobe entry-handler
-^^^^^^^^^^^^^^^^^^^^^^^
-
-Kretprobes also provides an optional user-specified handler which runs
-on function entry. This handler is specified by setting the entry_handler
-field of the kretprobe struct. Whenever the kprobe placed by kretprobe at the
-function entry is hit, the user-defined entry_handler, if any, is invoked.
-If the entry_handler returns 0 (success) then a corresponding return handler
-is guaranteed to be called upon function return. If the entry_handler
-returns a non-zero error then Kprobes leaves the return address as is, and
-the kretprobe has no further effect for that particular function instance.
-
-Multiple entry and return handler invocations are matched using the unique
-kretprobe_instance object associated with them. Additionally, a user
-may also specify per return-instance private data to be part of each
-kretprobe_instance object. This is especially useful when sharing private
-data between corresponding user entry and return handlers. The size of each
-private data object can be specified at kretprobe registration time by
-setting the data_size field of the kretprobe struct. This data can be
-accessed through the data field of each kretprobe_instance object.
-
-In case probed function is entered but there is no kretprobe_instance
-object available, then in addition to incrementing the nmissed count,
-the user entry_handler invocation is also skipped.
-
-.. _kprobes_jump_optimization:
-
-How Does Jump Optimization Work?
---------------------------------
-
-If your kernel is built with CONFIG_OPTPROBES=y (currently this flag
-is automatically set 'y' on x86/x86-64, non-preemptive kernel) and
-the "debug.kprobes_optimization" kernel parameter is set to 1 (see
-sysctl(8)), Kprobes tries to reduce probe-hit overhead by using a jump
-instruction instead of a breakpoint instruction at each probepoint.
-
-Init a Kprobe
-^^^^^^^^^^^^^
-
-When a probe is registered, before attempting this optimization,
-Kprobes inserts an ordinary, breakpoint-based kprobe at the specified
-address. So, even if it's not possible to optimize this particular
-probepoint, there'll be a probe there.
-
-Safety Check
-^^^^^^^^^^^^
-
-Before optimizing a probe, Kprobes performs the following safety checks:
-
-- Kprobes verifies that the region that will be replaced by the jump
- instruction (the "optimized region") lies entirely within one function.
- (A jump instruction is multiple bytes, and so may overlay multiple
- instructions.)
-
-- Kprobes analyzes the entire function and verifies that there is no
- jump into the optimized region. Specifically:
-
- - the function contains no indirect jump;
- - the function contains no instruction that causes an exception (since
- the fixup code triggered by the exception could jump back into the
- optimized region -- Kprobes checks the exception tables to verify this);
- - there is no near jump to the optimized region (other than to the first
- byte).
-
-- For each instruction in the optimized region, Kprobes verifies that
- the instruction can be executed out of line.
-
-Preparing Detour Buffer
-^^^^^^^^^^^^^^^^^^^^^^^
-
-Next, Kprobes prepares a "detour" buffer, which contains the following
-instruction sequence:
-
-- code to push the CPU's registers (emulating a breakpoint trap)
-- a call to the trampoline code which calls user's probe handlers.
-- code to restore registers
-- the instructions from the optimized region
-- a jump back to the original execution path.
-
-Pre-optimization
-^^^^^^^^^^^^^^^^
-
-After preparing the detour buffer, Kprobes verifies that none of the
-following situations exist:
-
-- The probe has a post_handler.
-- Other instructions in the optimized region are probed.
-- The probe is disabled.
-
-In any of the above cases, Kprobes won't start optimizing the probe.
-Since these are temporary situations, Kprobes tries to start
-optimizing it again if the situation is changed.
-
-If the kprobe can be optimized, Kprobes enqueues the kprobe to an
-optimizing list, and kicks the kprobe-optimizer workqueue to optimize
-it. If the to-be-optimized probepoint is hit before being optimized,
-Kprobes returns control to the original instruction path by setting
-the CPU's instruction pointer to the copied code in the detour buffer
--- thus at least avoiding the single-step.
-
-Optimization
-^^^^^^^^^^^^
-
-The Kprobe-optimizer doesn't insert the jump instruction immediately;
-rather, it calls synchronize_rcu() for safety first, because it's
-possible for a CPU to be interrupted in the middle of executing the
-optimized region [3]_. As you know, synchronize_rcu() can ensure
-that all interruptions that were active when synchronize_rcu()
-was called are done, but only if CONFIG_PREEMPT=n. So, this version
-of kprobe optimization supports only kernels with CONFIG_PREEMPT=n [4]_.
-
-After that, the Kprobe-optimizer calls stop_machine() to replace
-the optimized region with a jump instruction to the detour buffer,
-using text_poke_smp().
-
-Unoptimization
-^^^^^^^^^^^^^^
-
-When an optimized kprobe is unregistered, disabled, or blocked by
-another kprobe, it will be unoptimized. If this happens before
-the optimization is complete, the kprobe is just dequeued from the
-optimized list. If the optimization has been done, the jump is
-replaced with the original code (except for an int3 breakpoint in
-the first byte) by using text_poke_smp().
-
-.. [3] Please imagine that the 2nd instruction is interrupted and then
- the optimizer replaces the 2nd instruction with the jump *address*
- while the interrupt handler is running. When the interrupt
- returns to original address, there is no valid instruction,
- and it causes an unexpected result.
-
-.. [4] This optimization-safety checking may be replaced with the
- stop-machine method that ksplice uses for supporting a CONFIG_PREEMPT=y
- kernel.
-
-NOTE for geeks:
-The jump optimization changes the kprobe's pre_handler behavior.
-Without optimization, the pre_handler can change the kernel's execution
-path by changing regs->ip and returning 1. However, when the probe
-is optimized, that modification is ignored. Thus, if you want to
-tweak the kernel's execution path, you need to suppress optimization,
-using one of the following techniques:
-
-- Specify an empty function for the kprobe's post_handler.
-
-or
-
-- Execute 'sysctl -w debug.kprobes_optimization=n'
-
-.. _kprobes_blacklist:
-
-Blacklist
----------
-
-Kprobes can probe most of the kernel except itself. This means
-that there are some functions where kprobes cannot probe. Probing
-(trapping) such functions can cause a recursive trap (e.g. double
-fault) or the nested probe handler may never be called.
-Kprobes manages such functions as a blacklist.
-If you want to add a function into the blacklist, you just need
-to (1) include linux/kprobes.h and (2) use NOKPROBE_SYMBOL() macro
-to specify a blacklisted function.
-Kprobes checks the given probe address against the blacklist and
-rejects registering it, if the given address is in the blacklist.
-
-.. _kprobes_archs_supported:
-
-Architectures Supported
-=======================
-
-Kprobes and return probes are implemented on the following
-architectures:
-
-- i386 (Supports jump optimization)
-- x86_64 (AMD-64, EM64T) (Supports jump optimization)
-- ppc64
-- ia64 (Does not support probes on instruction slot1.)
-- sparc64 (Return probes not yet implemented.)
-- arm
-- ppc
-- mips
-- s390
-- parisc
-
-Configuring Kprobes
-===================
-
-When configuring the kernel using make menuconfig/xconfig/oldconfig,
-ensure that CONFIG_KPROBES is set to "y". Under "General setup", look
-for "Kprobes".
-
-So that you can load and unload Kprobes-based instrumentation modules,
-make sure "Loadable module support" (CONFIG_MODULES) and "Module
-unloading" (CONFIG_MODULE_UNLOAD) are set to "y".
-
-Also make sure that CONFIG_KALLSYMS and perhaps even CONFIG_KALLSYMS_ALL
-are set to "y", since kallsyms_lookup_name() is used by the in-kernel
-kprobe address resolution code.
-
-If you need to insert a probe in the middle of a function, you may find
-it useful to "Compile the kernel with debug info" (CONFIG_DEBUG_INFO),
-so you can use "objdump -d -l vmlinux" to see the source-to-object
-code mapping.
-
-API Reference
-=============
-
-The Kprobes API includes a "register" function and an "unregister"
-function for each type of probe. The API also includes "register_*probes"
-and "unregister_*probes" functions for (un)registering arrays of probes.
-Here are terse, mini-man-page specifications for these functions and
-the associated probe handlers that you'll write. See the files in the
-samples/kprobes/ sub-directory for examples.
-
-register_kprobe
----------------
-
-::
-
- #include <linux/kprobes.h>
- int register_kprobe(struct kprobe *kp);
-
-Sets a breakpoint at the address kp->addr. When the breakpoint is
-hit, Kprobes calls kp->pre_handler. After the probed instruction
-is single-stepped, Kprobe calls kp->post_handler. If a fault
-occurs during execution of kp->pre_handler or kp->post_handler,
-or during single-stepping of the probed instruction, Kprobes calls
-kp->fault_handler. Any or all handlers can be NULL. If kp->flags
-is set KPROBE_FLAG_DISABLED, that kp will be registered but disabled,
-so, its handlers aren't hit until calling enable_kprobe(kp).
-
-.. note::
-
- 1. With the introduction of the "symbol_name" field to struct kprobe,
- the probepoint address resolution will now be taken care of by the kernel.
- The following will now work::
-
- kp.symbol_name = "symbol_name";
-
- (64-bit powerpc intricacies such as function descriptors are handled
- transparently)
-
- 2. Use the "offset" field of struct kprobe if the offset into the symbol
- to install a probepoint is known. This field is used to calculate the
- probepoint.
-
- 3. Specify either the kprobe "symbol_name" OR the "addr". If both are
- specified, kprobe registration will fail with -EINVAL.
-
- 4. With CISC architectures (such as i386 and x86_64), the kprobes code
- does not validate if the kprobe.addr is at an instruction boundary.
- Use "offset" with caution.
-
-register_kprobe() returns 0 on success, or a negative errno otherwise.
-
-User's pre-handler (kp->pre_handler)::
-
- #include <linux/kprobes.h>
- #include <linux/ptrace.h>
- int pre_handler(struct kprobe *p, struct pt_regs *regs);
-
-Called with p pointing to the kprobe associated with the breakpoint,
-and regs pointing to the struct containing the registers saved when
-the breakpoint was hit. Return 0 here unless you're a Kprobes geek.
-
-User's post-handler (kp->post_handler)::
-
- #include <linux/kprobes.h>
- #include <linux/ptrace.h>
- void post_handler(struct kprobe *p, struct pt_regs *regs,
- unsigned long flags);
-
-p and regs are as described for the pre_handler. flags always seems
-to be zero.
-
-User's fault-handler (kp->fault_handler)::
-
- #include <linux/kprobes.h>
- #include <linux/ptrace.h>
- int fault_handler(struct kprobe *p, struct pt_regs *regs, int trapnr);
-
-p and regs are as described for the pre_handler. trapnr is the
-architecture-specific trap number associated with the fault (e.g.,
-on i386, 13 for a general protection fault or 14 for a page fault).
-Returns 1 if it successfully handled the exception.
-
-register_kretprobe
-------------------
-
-::
-
- #include <linux/kprobes.h>
- int register_kretprobe(struct kretprobe *rp);
-
-Establishes a return probe for the function whose address is
-rp->kp.addr. When that function returns, Kprobes calls rp->handler.
-You must set rp->maxactive appropriately before you call
-register_kretprobe(); see "How Does a Return Probe Work?" for details.
-
-register_kretprobe() returns 0 on success, or a negative errno
-otherwise.
-
-User's return-probe handler (rp->handler)::
-
- #include <linux/kprobes.h>
- #include <linux/ptrace.h>
- int kretprobe_handler(struct kretprobe_instance *ri,
- struct pt_regs *regs);
-
-regs is as described for kprobe.pre_handler. ri points to the
-kretprobe_instance object, of which the following fields may be
-of interest:
-
-- ret_addr: the return address
-- rp: points to the corresponding kretprobe object
-- task: points to the corresponding task struct
-- data: points to per return-instance private data; see "Kretprobe
- entry-handler" for details.
-
-The regs_return_value(regs) macro provides a simple abstraction to
-extract the return value from the appropriate register as defined by
-the architecture's ABI.
-
-The handler's return value is currently ignored.
-
-unregister_*probe
-------------------
-
-::
-
- #include <linux/kprobes.h>
- void unregister_kprobe(struct kprobe *kp);
- void unregister_kretprobe(struct kretprobe *rp);
-
-Removes the specified probe. The unregister function can be called
-at any time after the probe has been registered.
-
-.. note::
-
- If the functions find an incorrect probe (ex. an unregistered probe),
- they clear the addr field of the probe.
-
-register_*probes
-----------------
-
-::
-
- #include <linux/kprobes.h>
- int register_kprobes(struct kprobe **kps, int num);
- int register_kretprobes(struct kretprobe **rps, int num);
-
-Registers each of the num probes in the specified array. If any
-error occurs during registration, all probes in the array, up to
-the bad probe, are safely unregistered before the register_*probes
-function returns.
-
-- kps/rps: an array of pointers to ``*probe`` data structures
-- num: the number of the array entries.
-
-.. note::
-
- You have to allocate(or define) an array of pointers and set all
- of the array entries before using these functions.
-
-unregister_*probes
-------------------
-
-::
-
- #include <linux/kprobes.h>
- void unregister_kprobes(struct kprobe **kps, int num);
- void unregister_kretprobes(struct kretprobe **rps, int num);
-
-Removes each of the num probes in the specified array at once.
-
-.. note::
-
- If the functions find some incorrect probes (ex. unregistered
- probes) in the specified array, they clear the addr field of those
- incorrect probes. However, other probes in the array are
- unregistered correctly.
-
-disable_*probe
---------------
-
-::
-
- #include <linux/kprobes.h>
- int disable_kprobe(struct kprobe *kp);
- int disable_kretprobe(struct kretprobe *rp);
-
-Temporarily disables the specified ``*probe``. You can enable it again by using
-enable_*probe(). You must specify the probe which has been registered.
-
-enable_*probe
--------------
-
-::
-
- #include <linux/kprobes.h>
- int enable_kprobe(struct kprobe *kp);
- int enable_kretprobe(struct kretprobe *rp);
-
-Enables ``*probe`` which has been disabled by disable_*probe(). You must specify
-the probe which has been registered.
-
-Kprobes Features and Limitations
-================================
-
-Kprobes allows multiple probes at the same address. Also,
-a probepoint for which there is a post_handler cannot be optimized.
-So if you install a kprobe with a post_handler, at an optimized
-probepoint, the probepoint will be unoptimized automatically.
-
-In general, you can install a probe anywhere in the kernel.
-In particular, you can probe interrupt handlers. Known exceptions
-are discussed in this section.
-
-The register_*probe functions will return -EINVAL if you attempt
-to install a probe in the code that implements Kprobes (mostly
-kernel/kprobes.c and ``arch/*/kernel/kprobes.c``, but also functions such
-as do_page_fault and notifier_call_chain).
-
-If you install a probe in an inline-able function, Kprobes makes
-no attempt to chase down all inline instances of the function and
-install probes there. gcc may inline a function without being asked,
-so keep this in mind if you're not seeing the probe hits you expect.
-
-A probe handler can modify the environment of the probed function
--- e.g., by modifying kernel data structures, or by modifying the
-contents of the pt_regs struct (which are restored to the registers
-upon return from the breakpoint). So Kprobes can be used, for example,
-to install a bug fix or to inject faults for testing. Kprobes, of
-course, has no way to distinguish the deliberately injected faults
-from the accidental ones. Don't drink and probe.
-
-Kprobes makes no attempt to prevent probe handlers from stepping on
-each other -- e.g., probing printk() and then calling printk() from a
-probe handler. If a probe handler hits a probe, that second probe's
-handlers won't be run in that instance, and the kprobe.nmissed member
-of the second probe will be incremented.
-
-As of Linux v2.6.15-rc1, multiple handlers (or multiple instances of
-the same handler) may run concurrently on different CPUs.
-
-Kprobes does not use mutexes or allocate memory except during
-registration and unregistration.
-
-Probe handlers are run with preemption disabled or interrupt disabled,
-which depends on the architecture and optimization state. (e.g.,
-kretprobe handlers and optimized kprobe handlers run without interrupt
-disabled on x86/x86-64). In any case, your handler should not yield
-the CPU (e.g., by attempting to acquire a semaphore, or waiting I/O).
-
-Since a return probe is implemented by replacing the return
-address with the trampoline's address, stack backtraces and calls
-to __builtin_return_address() will typically yield the trampoline's
-address instead of the real return address for kretprobed functions.
-(As far as we can tell, __builtin_return_address() is used only
-for instrumentation and error reporting.)
-
-If the number of times a function is called does not match the number
-of times it returns, registering a return probe on that function may
-produce undesirable results. In such a case, a line:
-kretprobe BUG!: Processing kretprobe d000000000041aa8 @ c00000000004f48c
-gets printed. With this information, one will be able to correlate the
-exact instance of the kretprobe that caused the problem. We have the
-do_exit() case covered. do_execve() and do_fork() are not an issue.
-We're unaware of other specific cases where this could be a problem.
-
-If, upon entry to or exit from a function, the CPU is running on
-a stack other than that of the current task, registering a return
-probe on that function may produce undesirable results. For this
-reason, Kprobes doesn't support return probes (or kprobes)
-on the x86_64 version of __switch_to(); the registration functions
-return -EINVAL.
-
-On x86/x86-64, since the Jump Optimization of Kprobes modifies
-instructions widely, there are some limitations to optimization. To
-explain it, we introduce some terminology. Imagine a 3-instruction
-sequence consisting of a two 2-byte instructions and one 3-byte
-instruction.
-
-::
-
- IA
- |
- [-2][-1][0][1][2][3][4][5][6][7]
- [ins1][ins2][ ins3 ]
- [<- DCR ->]
- [<- JTPR ->]
-
- ins1: 1st Instruction
- ins2: 2nd Instruction
- ins3: 3rd Instruction
- IA: Insertion Address
- JTPR: Jump Target Prohibition Region
- DCR: Detoured Code Region
-
-The instructions in DCR are copied to the out-of-line buffer
-of the kprobe, because the bytes in DCR are replaced by
-a 5-byte jump instruction. So there are several limitations.
-
-a) The instructions in DCR must be relocatable.
-b) The instructions in DCR must not include a call instruction.
-c) JTPR must not be targeted by any jump or call instruction.
-d) DCR must not straddle the border between functions.
-
-Anyway, these limitations are checked by the in-kernel instruction
-decoder, so you don't need to worry about that.
-
-Probe Overhead
-==============
-
-On a typical CPU in use in 2005, a kprobe hit takes 0.5 to 1.0
-microseconds to process. Specifically, a benchmark that hits the same
-probepoint repeatedly, firing a simple handler each time, reports 1-2
-million hits per second, depending on the architecture. A return-probe
-hit typically takes 50-75% longer than a kprobe hit.
-When you have a return probe set on a function, adding a kprobe at
-the entry to that function adds essentially no overhead.
-
-Here are sample overhead figures (in usec) for different architectures::
-
- k = kprobe; r = return probe; kr = kprobe + return probe
- on same function
-
- i386: Intel Pentium M, 1495 MHz, 2957.31 bogomips
- k = 0.57 usec; r = 0.92; kr = 0.99
-
- x86_64: AMD Opteron 246, 1994 MHz, 3971.48 bogomips
- k = 0.49 usec; r = 0.80; kr = 0.82
-
- ppc64: POWER5 (gr), 1656 MHz (SMT disabled, 1 virtual CPU per physical CPU)
- k = 0.77 usec; r = 1.26; kr = 1.45
-
-Optimized Probe Overhead
-------------------------
-
-Typically, an optimized kprobe hit takes 0.07 to 0.1 microseconds to
-process. Here are sample overhead figures (in usec) for x86 architectures::
-
- k = unoptimized kprobe, b = boosted (single-step skipped), o = optimized kprobe,
- r = unoptimized kretprobe, rb = boosted kretprobe, ro = optimized kretprobe.
-
- i386: Intel(R) Xeon(R) E5410, 2.33GHz, 4656.90 bogomips
- k = 0.80 usec; b = 0.33; o = 0.05; r = 1.10; rb = 0.61; ro = 0.33
-
- x86-64: Intel(R) Xeon(R) E5410, 2.33GHz, 4656.90 bogomips
- k = 0.99 usec; b = 0.43; o = 0.06; r = 1.24; rb = 0.68; ro = 0.30
-
-TODO
-====
-
-a. SystemTap (http://sourceware.org/systemtap): Provides a simplified
- programming interface for probe-based instrumentation. Try it out.
-b. Kernel return probes for sparc64.
-c. Support for other architectures.
-d. User-space probes.
-e. Watchpoint probes (which fire on data references).
-
-Kprobes Example
-===============
-
-See samples/kprobes/kprobe_example.c
-
-Kretprobes Example
-==================
-
-See samples/kprobes/kretprobe_example.c
-
-For additional information on Kprobes, refer to the following URLs:
-
-- http://www-106.ibm.com/developerworks/library/l-kprobes.html?ca=dgr-lnxw42Kprobe
-- http://www.redhat.com/magazine/005mar05/features/kprobes/
-- http://www-users.cs.umn.edu/~boutcher/kprobes/
-- http://www.linuxsymposium.org/2006/linuxsymposium_procv2.pdf (pages 101-115)
-
-Deprecated Features
-===================
-
-Jprobes is now a deprecated feature. People who are depending on it should
-migrate to other tracing features or use older kernels. Please consider to
-migrate your tool to one of the following options:
-
-- Use trace-event to trace target function with arguments.
-
- trace-event is a low-overhead (and almost no visible overhead if it
- is off) statically defined event interface. You can define new events
- and trace it via ftrace or any other tracing tools.
-
- See the following urls:
-
- - https://lwn.net/Articles/379903/
- - https://lwn.net/Articles/381064/
- - https://lwn.net/Articles/383362/
-
-- Use ftrace dynamic events (kprobe event) with perf-probe.
-
- If you build your kernel with debug info (CONFIG_DEBUG_INFO=y), you can
- find which register/stack is assigned to which local variable or arguments
- by using perf-probe and set up new event to trace it.
-
- See following documents:
-
- - Documentation/trace/kprobetrace.rst
- - Documentation/trace/events.rst
- - tools/perf/Documentation/perf-probe.txt
-
-
-The kprobes debugfs interface
-=============================
-
-
-With recent kernels (> 2.6.20) the list of registered kprobes is visible
-under the /sys/kernel/debug/kprobes/ directory (assuming debugfs is mounted at //sys/kernel/debug).
-
-/sys/kernel/debug/kprobes/list: Lists all registered probes on the system::
-
- c015d71a k vfs_read+0x0
- c03dedc5 r tcp_v4_rcv+0x0
-
-The first column provides the kernel address where the probe is inserted.
-The second column identifies the type of probe (k - kprobe and r - kretprobe)
-while the third column specifies the symbol+offset of the probe.
-If the probed function belongs to a module, the module name is also
-specified. Following columns show probe status. If the probe is on
-a virtual address that is no longer valid (module init sections, module
-virtual addresses that correspond to modules that've been unloaded),
-such probes are marked with [GONE]. If the probe is temporarily disabled,
-such probes are marked with [DISABLED]. If the probe is optimized, it is
-marked with [OPTIMIZED]. If the probe is ftrace-based, it is marked with
-[FTRACE].
-
-/sys/kernel/debug/kprobes/enabled: Turn kprobes ON/OFF forcibly.
-
-Provides a knob to globally and forcibly turn registered kprobes ON or OFF.
-By default, all kprobes are enabled. By echoing "0" to this file, all
-registered probes will be disarmed, till such time a "1" is echoed to this
-file. Note that this knob just disarms and arms all kprobes and doesn't
-change each probe's disabling state. This means that disabled kprobes (marked
-[DISABLED]) will be not enabled if you turn ON all kprobes by this knob.
-
-
-The kprobes sysctl interface
-============================
-
-/proc/sys/debug/kprobes-optimization: Turn kprobes optimization ON/OFF.
-
-When CONFIG_OPTPROBES=y, this sysctl interface appears and it provides
-a knob to globally and forcibly turn jump optimization (see section
-:ref:`kprobes_jump_optimization`) ON or OFF. By default, jump optimization
-is allowed (ON). If you echo "0" to this file or set
-"debug.kprobes_optimization" to 0 via sysctl, all optimized probes will be
-unoptimized, and any new probes registered after that will not be optimized.
-
-Note that this knob *changes* the optimized state. This means that optimized
-probes (marked [OPTIMIZED]) will be unoptimized ([OPTIMIZED] tag will be
-removed). If the knob is turned on, they will be optimized again.
-
diff --git a/Documentation/leds/index.rst b/Documentation/leds/index.rst
index 060f4e4..bc70c6aa 100644
--- a/Documentation/leds/index.rst
+++ b/Documentation/leds/index.rst
@@ -9,6 +9,7 @@
leds-class
leds-class-flash
+ leds-class-multicolor
ledtrig-oneshot
ledtrig-transient
ledtrig-usbport
diff --git a/Documentation/leds/leds-class-multicolor.rst b/Documentation/leds/leds-class-multicolor.rst
new file mode 100644
index 0000000..c57b98b
--- /dev/null
+++ b/Documentation/leds/leds-class-multicolor.rst
@@ -0,0 +1,86 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+====================================
+Multicolor LED handling under Linux
+====================================
+
+Description
+===========
+The multicolor class groups monochrome LEDs and allows controlling two
+aspects of the final combined color: hue and lightness. The former is
+controlled via the multi_intensity array file and the latter is controlled
+via brightness file.
+
+Multicolor Class Control
+========================
+The multicolor class presents files that groups the colors as indexes in an
+array. These files are children under the LED parent node created by the
+led_class framework. The led_class framework is documented in led-class.rst
+within this documentation directory.
+
+Each colored LED will be indexed under the multi_* files. The order of the
+colors will be arbitrary. The multi_index file can be read to determine the
+color name to indexed value.
+
+The multi_index file is an array that contains the string list of the colors as
+they are defined in each multi_* array file.
+
+The multi_intensity is an array that can be read or written to for the
+individual color intensities. All elements within this array must be written in
+order for the color LED intensities to be updated.
+
+Directory Layout Example
+========================
+root:/sys/class/leds/multicolor:status# ls -lR
+-rw-r--r-- 1 root root 4096 Oct 19 16:16 brightness
+-r--r--r-- 1 root root 4096 Oct 19 16:16 max_brightness
+-r--r--r-- 1 root root 4096 Oct 19 16:16 multi_index
+-rw-r--r-- 1 root root 4096 Oct 19 16:16 multi_intensity
+
+Multicolor Class Brightness Control
+===================================
+The brightness level for each LED is calculated based on the color LED
+intensity setting divided by the global max_brightness setting multiplied by
+the requested brightness.
+
+led_brightness = brightness * multi_intensity/max_brightness
+
+Example:
+A user first writes the multi_intensity file with the brightness levels
+for each LED that are necessary to achieve a certain color output from a
+multicolor LED group.
+
+cat /sys/class/leds/multicolor:status/multi_index
+green blue red
+
+echo 43 226 138 > /sys/class/leds/multicolor:status/multi_intensity
+
+red -
+ intensity = 138
+ max_brightness = 255
+green -
+ intensity = 43
+ max_brightness = 255
+blue -
+ intensity = 226
+ max_brightness = 255
+
+The user can control the brightness of that multicolor LED group by writing the
+global 'brightness' control. Assuming a max_brightness of 255 the user
+may want to dim the LED color group to half. The user would write a value of
+128 to the global brightness file then the values written to each LED will be
+adjusted base on this value.
+
+cat /sys/class/leds/multicolor:status/max_brightness
+255
+echo 128 > /sys/class/leds/multicolor:status/brightness
+
+adjusted_red_value = 128 * 138/255 = 69
+adjusted_green_value = 128 * 43/255 = 21
+adjusted_blue_value = 128 * 226/255 = 113
+
+Reading the global brightness file will return the current brightness value of
+the color LED group.
+
+cat /sys/class/leds/multicolor:status/brightness
+128
diff --git a/Documentation/leds/ledtrig-transient.rst b/Documentation/leds/ledtrig-transient.rst
index d921dc8..eedfa16 100644
--- a/Documentation/leds/ledtrig-transient.rst
+++ b/Documentation/leds/ledtrig-transient.rst
@@ -157,7 +157,7 @@
echo 1 > activate - start timer = duration to run once
echo none > trigger
-This trigger is intended to be used for for the following example use cases:
+This trigger is intended to be used for the following example use cases:
- Control of vibrate (phones, tablets etc.) hardware by user space app.
- Use of LED by user space app as activity indicator.
diff --git a/Documentation/litmus-tests/README b/Documentation/litmus-tests/README
new file mode 100644
index 0000000..7f5c6c3
--- /dev/null
+++ b/Documentation/litmus-tests/README
@@ -0,0 +1,35 @@
+============
+LITMUS TESTS
+============
+
+Each subdirectory contains litmus tests that are typical to describe the
+semantics of respective kernel APIs.
+For more information about how to "run" a litmus test or how to generate
+a kernel test module based on a litmus test, please see
+tools/memory-model/README.
+
+
+atomic (/atomic derectory)
+--------------------------
+
+Atomic-RMW+mb__after_atomic-is-stronger-than-acquire.litmus
+ Test that an atomic RMW followed by a smp_mb__after_atomic() is
+ stronger than a normal acquire: both the read and write parts of
+ the RMW are ordered before the subsequential memory accesses.
+
+Atomic-RMW-ops-are-atomic-WRT-atomic_set.litmus
+ Test that atomic_set() cannot break the atomicity of atomic RMWs.
+ NOTE: Require herd7 7.56 or later which supports "(void)expr".
+
+
+RCU (/rcu directory)
+--------------------
+
+MP+onceassign+derefonce.litmus (under tools/memory-model/litmus-tests/)
+ Demonstrates the use of rcu_assign_pointer() and rcu_dereference() to
+ ensure that an RCU reader will not see pre-initialization garbage.
+
+RCU+sync+read.litmus
+RCU+sync+free.litmus
+ Both the above litmus tests demonstrate the RCU grace period guarantee
+ that an RCU read-side critical section can never span a grace period.
diff --git a/Documentation/litmus-tests/atomic/Atomic-RMW+mb__after_atomic-is-stronger-than-acquire.litmus b/Documentation/litmus-tests/atomic/Atomic-RMW+mb__after_atomic-is-stronger-than-acquire.litmus
new file mode 100644
index 0000000..9a8e31a
--- /dev/null
+++ b/Documentation/litmus-tests/atomic/Atomic-RMW+mb__after_atomic-is-stronger-than-acquire.litmus
@@ -0,0 +1,32 @@
+C Atomic-RMW+mb__after_atomic-is-stronger-than-acquire
+
+(*
+ * Result: Never
+ *
+ * Test that an atomic RMW followed by a smp_mb__after_atomic() is
+ * stronger than a normal acquire: both the read and write parts of
+ * the RMW are ordered before the subsequential memory accesses.
+ *)
+
+{
+}
+
+P0(int *x, atomic_t *y)
+{
+ int r0;
+ int r1;
+
+ r0 = READ_ONCE(*x);
+ smp_rmb();
+ r1 = atomic_read(y);
+}
+
+P1(int *x, atomic_t *y)
+{
+ atomic_inc(y);
+ smp_mb__after_atomic();
+ WRITE_ONCE(*x, 1);
+}
+
+exists
+(0:r0=1 /\ 0:r1=0)
diff --git a/Documentation/litmus-tests/atomic/Atomic-RMW-ops-are-atomic-WRT-atomic_set.litmus b/Documentation/litmus-tests/atomic/Atomic-RMW-ops-are-atomic-WRT-atomic_set.litmus
new file mode 100644
index 0000000..ffd4d3e
--- /dev/null
+++ b/Documentation/litmus-tests/atomic/Atomic-RMW-ops-are-atomic-WRT-atomic_set.litmus
@@ -0,0 +1,25 @@
+C Atomic-RMW-ops-are-atomic-WRT-atomic_set
+
+(*
+ * Result: Never
+ *
+ * Test that atomic_set() cannot break the atomicity of atomic RMWs.
+ * NOTE: This requires herd7 7.56 or later which supports "(void)expr".
+ *)
+
+{
+ atomic_t v = ATOMIC_INIT(1);
+}
+
+P0(atomic_t *v)
+{
+ (void)atomic_add_unless(v, 1, 0);
+}
+
+P1(atomic_t *v)
+{
+ atomic_set(v, 0);
+}
+
+exists
+(v=2)
diff --git a/Documentation/litmus-tests/rcu/RCU+sync+free.litmus b/Documentation/litmus-tests/rcu/RCU+sync+free.litmus
new file mode 100644
index 0000000..4ee67e1
--- /dev/null
+++ b/Documentation/litmus-tests/rcu/RCU+sync+free.litmus
@@ -0,0 +1,42 @@
+C RCU+sync+free
+
+(*
+ * Result: Never
+ *
+ * This litmus test demonstrates that an RCU reader can never see a write that
+ * follows a grace period, if it did not see writes that precede that grace
+ * period.
+ *
+ * This is a typical pattern of RCU usage, where the write before the grace
+ * period assigns a pointer, and the writes following the grace period destroy
+ * the object that the pointer used to point to.
+ *
+ * This is one implication of the RCU grace-period guarantee, which says (among
+ * other things) that an RCU read-side critical section cannot span a grace period.
+ *)
+
+{
+int x = 1;
+int *y = &x;
+int z = 1;
+}
+
+P0(int *x, int *z, int **y)
+{
+ int *r0;
+ int r1;
+
+ rcu_read_lock();
+ r0 = rcu_dereference(*y);
+ r1 = READ_ONCE(*r0);
+ rcu_read_unlock();
+}
+
+P1(int *x, int *z, int **y)
+{
+ rcu_assign_pointer(*y, z);
+ synchronize_rcu();
+ WRITE_ONCE(*x, 0);
+}
+
+exists (0:r0=x /\ 0:r1=0)
diff --git a/Documentation/litmus-tests/rcu/RCU+sync+read.litmus b/Documentation/litmus-tests/rcu/RCU+sync+read.litmus
new file mode 100644
index 0000000..f341767
--- /dev/null
+++ b/Documentation/litmus-tests/rcu/RCU+sync+read.litmus
@@ -0,0 +1,37 @@
+C RCU+sync+read
+
+(*
+ * Result: Never
+ *
+ * This litmus test demonstrates that after a grace period, an RCU updater always
+ * sees all stores done in prior RCU read-side critical sections. Such
+ * read-side critical sections would have ended before the grace period ended.
+ *
+ * This is one implication of the RCU grace-period guarantee, which says (among
+ * other things) that an RCU read-side critical section cannot span a grace period.
+ *)
+
+{
+int x = 0;
+int y = 0;
+}
+
+P0(int *x, int *y)
+{
+ rcu_read_lock();
+ WRITE_ONCE(*x, 1);
+ WRITE_ONCE(*y, 1);
+ rcu_read_unlock();
+}
+
+P1(int *x, int *y)
+{
+ int r0;
+ int r1;
+
+ r0 = READ_ONCE(*x);
+ synchronize_rcu();
+ r1 = READ_ONCE(*y);
+}
+
+exists (1:r0=1 /\ 1:r1=0)
diff --git a/Documentation/locking/index.rst b/Documentation/locking/index.rst
index d785878..7003bd5 100644
--- a/Documentation/locking/index.rst
+++ b/Documentation/locking/index.rst
@@ -14,6 +14,7 @@
mutex-design
rt-mutex-design
rt-mutex
+ seqlock
spinlocks
ww-mutex-design
preempt-locking
diff --git a/Documentation/locking/locktorture.rst b/Documentation/locking/locktorture.rst
index 8012a74..dfaf9fc 100644
--- a/Documentation/locking/locktorture.rst
+++ b/Documentation/locking/locktorture.rst
@@ -166,4 +166,4 @@
two are self-explanatory, while the last indicates that while there
were no locking failures, CPU-hotplug problems were detected.
-Also see: Documentation/RCU/torture.txt
+Also see: Documentation/RCU/torture.rst
diff --git a/Documentation/locking/locktypes.rst b/Documentation/locking/locktypes.rst
index 1b577a8..4cefed8 100644
--- a/Documentation/locking/locktypes.rst
+++ b/Documentation/locking/locktypes.rst
@@ -10,7 +10,7 @@
============
The kernel provides a variety of locking primitives which can be divided
-into two categories:
+into three categories:
- Sleeping locks
- CPU local locks
diff --git a/Documentation/locking/mutex-design.rst b/Documentation/locking/mutex-design.rst
index 4d8236b..78540cd7 100644
--- a/Documentation/locking/mutex-design.rst
+++ b/Documentation/locking/mutex-design.rst
@@ -18,7 +18,7 @@
of advantages, including simpler interfaces, and at that time smaller
code (see Disadvantages).
-[1] http://lwn.net/Articles/164802/
+[1] https://lwn.net/Articles/164802/
Implementation
--------------
@@ -28,7 +28,7 @@
(->owner) to keep track of the lock state during its lifetime. Field owner
actually contains `struct task_struct *` to the current lock owner and it is
therefore NULL if not currently owned. Since task_struct pointers are aligned
-at at least L1_CACHE_BYTES, low bits (3) are used to store extra state (e.g.,
+to at least L1_CACHE_BYTES, low bits (3) are used to store extra state (e.g.,
if waiter list is non-empty). In its most basic form it also includes a
wait-queue and a spinlock that serializes access to it. Furthermore,
CONFIG_MUTEX_SPIN_ON_OWNER=y systems use a spinner MCS lock (->osq), described
diff --git a/Documentation/locking/seqlock.rst b/Documentation/locking/seqlock.rst
new file mode 100644
index 0000000..62c5ad9
--- /dev/null
+++ b/Documentation/locking/seqlock.rst
@@ -0,0 +1,222 @@
+======================================
+Sequence counters and sequential locks
+======================================
+
+Introduction
+============
+
+Sequence counters are a reader-writer consistency mechanism with
+lockless readers (read-only retry loops), and no writer starvation. They
+are used for data that's rarely written to (e.g. system time), where the
+reader wants a consistent set of information and is willing to retry if
+that information changes.
+
+A data set is consistent when the sequence count at the beginning of the
+read side critical section is even and the same sequence count value is
+read again at the end of the critical section. The data in the set must
+be copied out inside the read side critical section. If the sequence
+count has changed between the start and the end of the critical section,
+the reader must retry.
+
+Writers increment the sequence count at the start and the end of their
+critical section. After starting the critical section the sequence count
+is odd and indicates to the readers that an update is in progress. At
+the end of the write side critical section the sequence count becomes
+even again which lets readers make progress.
+
+A sequence counter write side critical section must never be preempted
+or interrupted by read side sections. Otherwise the reader will spin for
+the entire scheduler tick due to the odd sequence count value and the
+interrupted writer. If that reader belongs to a real-time scheduling
+class, it can spin forever and the kernel will livelock.
+
+This mechanism cannot be used if the protected data contains pointers,
+as the writer can invalidate a pointer that the reader is following.
+
+
+.. _seqcount_t:
+
+Sequence counters (``seqcount_t``)
+==================================
+
+This is the the raw counting mechanism, which does not protect against
+multiple writers. Write side critical sections must thus be serialized
+by an external lock.
+
+If the write serialization primitive is not implicitly disabling
+preemption, preemption must be explicitly disabled before entering the
+write side section. If the read section can be invoked from hardirq or
+softirq contexts, interrupts or bottom halves must also be respectively
+disabled before entering the write section.
+
+If it's desired to automatically handle the sequence counter
+requirements of writer serialization and non-preemptibility, use
+:ref:`seqlock_t` instead.
+
+Initialization::
+
+ /* dynamic */
+ seqcount_t foo_seqcount;
+ seqcount_init(&foo_seqcount);
+
+ /* static */
+ static seqcount_t foo_seqcount = SEQCNT_ZERO(foo_seqcount);
+
+ /* C99 struct init */
+ struct {
+ .seq = SEQCNT_ZERO(foo.seq),
+ } foo;
+
+Write path::
+
+ /* Serialized context with disabled preemption */
+
+ write_seqcount_begin(&foo_seqcount);
+
+ /* ... [[write-side critical section]] ... */
+
+ write_seqcount_end(&foo_seqcount);
+
+Read path::
+
+ do {
+ seq = read_seqcount_begin(&foo_seqcount);
+
+ /* ... [[read-side critical section]] ... */
+
+ } while (read_seqcount_retry(&foo_seqcount, seq));
+
+
+.. _seqcount_locktype_t:
+
+Sequence counters with associated locks (``seqcount_LOCKTYPE_t``)
+-----------------------------------------------------------------
+
+As discussed at :ref:`seqcount_t`, sequence count write side critical
+sections must be serialized and non-preemptible. This variant of
+sequence counters associate the lock used for writer serialization at
+initialization time, which enables lockdep to validate that the write
+side critical sections are properly serialized.
+
+This lock association is a NOOP if lockdep is disabled and has neither
+storage nor runtime overhead. If lockdep is enabled, the lock pointer is
+stored in struct seqcount and lockdep's "lock is held" assertions are
+injected at the beginning of the write side critical section to validate
+that it is properly protected.
+
+For lock types which do not implicitly disable preemption, preemption
+protection is enforced in the write side function.
+
+The following sequence counters with associated locks are defined:
+
+ - ``seqcount_spinlock_t``
+ - ``seqcount_raw_spinlock_t``
+ - ``seqcount_rwlock_t``
+ - ``seqcount_mutex_t``
+ - ``seqcount_ww_mutex_t``
+
+The plain seqcount read and write APIs branch out to the specific
+seqcount_LOCKTYPE_t implementation at compile-time. This avoids kernel
+API explosion per each new seqcount LOCKTYPE.
+
+Initialization (replace "LOCKTYPE" with one of the supported locks)::
+
+ /* dynamic */
+ seqcount_LOCKTYPE_t foo_seqcount;
+ seqcount_LOCKTYPE_init(&foo_seqcount, &lock);
+
+ /* static */
+ static seqcount_LOCKTYPE_t foo_seqcount =
+ SEQCNT_LOCKTYPE_ZERO(foo_seqcount, &lock);
+
+ /* C99 struct init */
+ struct {
+ .seq = SEQCNT_LOCKTYPE_ZERO(foo.seq, &lock),
+ } foo;
+
+Write path: same as in :ref:`seqcount_t`, while running from a context
+with the associated LOCKTYPE lock acquired.
+
+Read path: same as in :ref:`seqcount_t`.
+
+.. _seqlock_t:
+
+Sequential locks (``seqlock_t``)
+================================
+
+This contains the :ref:`seqcount_t` mechanism earlier discussed, plus an
+embedded spinlock for writer serialization and non-preemptibility.
+
+If the read side section can be invoked from hardirq or softirq context,
+use the write side function variants which disable interrupts or bottom
+halves respectively.
+
+Initialization::
+
+ /* dynamic */
+ seqlock_t foo_seqlock;
+ seqlock_init(&foo_seqlock);
+
+ /* static */
+ static DEFINE_SEQLOCK(foo_seqlock);
+
+ /* C99 struct init */
+ struct {
+ .seql = __SEQLOCK_UNLOCKED(foo.seql)
+ } foo;
+
+Write path::
+
+ write_seqlock(&foo_seqlock);
+
+ /* ... [[write-side critical section]] ... */
+
+ write_sequnlock(&foo_seqlock);
+
+Read path, three categories:
+
+1. Normal Sequence readers which never block a writer but they must
+ retry if a writer is in progress by detecting change in the sequence
+ number. Writers do not wait for a sequence reader::
+
+ do {
+ seq = read_seqbegin(&foo_seqlock);
+
+ /* ... [[read-side critical section]] ... */
+
+ } while (read_seqretry(&foo_seqlock, seq));
+
+2. Locking readers which will wait if a writer or another locking reader
+ is in progress. A locking reader in progress will also block a writer
+ from entering its critical section. This read lock is
+ exclusive. Unlike rwlock_t, only one locking reader can acquire it::
+
+ read_seqlock_excl(&foo_seqlock);
+
+ /* ... [[read-side critical section]] ... */
+
+ read_sequnlock_excl(&foo_seqlock);
+
+3. Conditional lockless reader (as in 1), or locking reader (as in 2),
+ according to a passed marker. This is used to avoid lockless readers
+ starvation (too much retry loops) in case of a sharp spike in write
+ activity. First, a lockless read is tried (even marker passed). If
+ that trial fails (odd sequence counter is returned, which is used as
+ the next iteration marker), the lockless read is transformed to a
+ full locking read and no retry loop is necessary::
+
+ /* marker; even initialization */
+ int seq = 0;
+ do {
+ read_seqbegin_or_lock(&foo_seqlock, &seq);
+
+ /* ... [[read-side critical section]] ... */
+
+ } while (need_seqretry(&foo_seqlock, seq));
+ done_seqretry(&foo_seqlock, seq);
+
+
+API documentation
+=================
+
+.. kernel-doc:: include/linux/seqlock.h
diff --git a/Documentation/locking/ww-mutex-design.rst b/Documentation/locking/ww-mutex-design.rst
index 1846c19..54d9c17 100644
--- a/Documentation/locking/ww-mutex-design.rst
+++ b/Documentation/locking/ww-mutex-design.rst
@@ -49,7 +49,7 @@
compared to Wait-Die, but is, on the other hand, associated with more work than
Wait-Die when recovering from a backoff. Wound-Wait is also a preemptive
algorithm in that transactions are wounded by other transactions, and that
-requires a reliable way to pick up up the wounded condition and preempt the
+requires a reliable way to pick up the wounded condition and preempt the
running transaction. Note that this is not the same as process preemption. A
Wound-Wait transaction is considered preempted when it dies (returning
-EDEADLK) following a wound.
diff --git a/Documentation/maintainer/maintainer-entry-profile.rst b/Documentation/maintainer/maintainer-entry-profile.rst
index 77e43c8..227f427 100644
--- a/Documentation/maintainer/maintainer-entry-profile.rst
+++ b/Documentation/maintainer/maintainer-entry-profile.rst
@@ -31,7 +31,7 @@
- What branch should contributors submit against?
- Links to any other Maintainer Entry Profiles? For example a
device-driver may point to an entry for its parent subsystem. This makes
- the contributor aware of obligations a maintainer may have have for
+ the contributor aware of obligations a maintainer may have for
other maintainers in the submission chain.
diff --git a/Documentation/memory-barriers.txt b/Documentation/memory-barriers.txt
index eaabc31..9618633 100644
--- a/Documentation/memory-barriers.txt
+++ b/Documentation/memory-barriers.txt
@@ -553,12 +553,12 @@
DATA DEPENDENCY BARRIERS (HISTORICAL)
-------------------------------------
-As of v4.15 of the Linux kernel, an smp_read_barrier_depends() was
-added to READ_ONCE(), which means that about the only people who
-need to pay attention to this section are those working on DEC Alpha
-architecture-specific code and those working on READ_ONCE() itself.
-For those who need it, and for those who are interested in the history,
-here is the story of data-dependency barriers.
+As of v4.15 of the Linux kernel, an smp_mb() was added to READ_ONCE() for
+DEC Alpha, which means that about the only people who need to pay attention
+to this section are those working on DEC Alpha architecture-specific code
+and those working on READ_ONCE() itself. For those who need it, and for
+those who are interested in the history, here is the story of
+data-dependency barriers.
The usage requirements of data dependency barriers are a little subtle, and
it's not always obvious that they're needed. To illustrate, consider the
@@ -1935,6 +1935,20 @@
relaxed I/O accessors and the Documentation/DMA-API.txt file for more
information on consistent memory.
+ (*) pmem_wmb();
+
+ This is for use with persistent memory to ensure that stores for which
+ modifications are written to persistent storage reached a platform
+ durability domain.
+
+ For example, after a non-temporal write to pmem region, we use pmem_wmb()
+ to ensure that stores have reached a platform durability domain. This ensures
+ that stores have updated persistent storage before any data access or
+ data transfer caused by subsequent instructions is initiated. This is
+ in addition to the ordering done by wmb().
+
+ For load from persistent memory, existing read memory barriers are sufficient
+ to ensure read ordering.
===============================
IMPLICIT KERNEL MEMORY BARRIERS
@@ -2708,144 +2722,6 @@
the use of any special device communication instructions the CPU may have.
-CACHE COHERENCY
----------------
-
-Life isn't quite as simple as it may appear above, however: for while the
-caches are expected to be coherent, there's no guarantee that that coherency
-will be ordered. This means that while changes made on one CPU will
-eventually become visible on all CPUs, there's no guarantee that they will
-become apparent in the same order on those other CPUs.
-
-
-Consider dealing with a system that has a pair of CPUs (1 & 2), each of which
-has a pair of parallel data caches (CPU 1 has A/B, and CPU 2 has C/D):
-
- :
- : +--------+
- : +---------+ | |
- +--------+ : +--->| Cache A |<------->| |
- | | : | +---------+ | |
- | CPU 1 |<---+ | |
- | | : | +---------+ | |
- +--------+ : +--->| Cache B |<------->| |
- : +---------+ | |
- : | Memory |
- : +---------+ | System |
- +--------+ : +--->| Cache C |<------->| |
- | | : | +---------+ | |
- | CPU 2 |<---+ | |
- | | : | +---------+ | |
- +--------+ : +--->| Cache D |<------->| |
- : +---------+ | |
- : +--------+
- :
-
-Imagine the system has the following properties:
-
- (*) an odd-numbered cache line may be in cache A, cache C or it may still be
- resident in memory;
-
- (*) an even-numbered cache line may be in cache B, cache D or it may still be
- resident in memory;
-
- (*) while the CPU core is interrogating one cache, the other cache may be
- making use of the bus to access the rest of the system - perhaps to
- displace a dirty cacheline or to do a speculative load;
-
- (*) each cache has a queue of operations that need to be applied to that cache
- to maintain coherency with the rest of the system;
-
- (*) the coherency queue is not flushed by normal loads to lines already
- present in the cache, even though the contents of the queue may
- potentially affect those loads.
-
-Imagine, then, that two writes are made on the first CPU, with a write barrier
-between them to guarantee that they will appear to reach that CPU's caches in
-the requisite order:
-
- CPU 1 CPU 2 COMMENT
- =============== =============== =======================================
- u == 0, v == 1 and p == &u, q == &u
- v = 2;
- smp_wmb(); Make sure change to v is visible before
- change to p
- <A:modify v=2> v is now in cache A exclusively
- p = &v;
- <B:modify p=&v> p is now in cache B exclusively
-
-The write memory barrier forces the other CPUs in the system to perceive that
-the local CPU's caches have apparently been updated in the correct order. But
-now imagine that the second CPU wants to read those values:
-
- CPU 1 CPU 2 COMMENT
- =============== =============== =======================================
- ...
- q = p;
- x = *q;
-
-The above pair of reads may then fail to happen in the expected order, as the
-cacheline holding p may get updated in one of the second CPU's caches while
-the update to the cacheline holding v is delayed in the other of the second
-CPU's caches by some other cache event:
-
- CPU 1 CPU 2 COMMENT
- =============== =============== =======================================
- u == 0, v == 1 and p == &u, q == &u
- v = 2;
- smp_wmb();
- <A:modify v=2> <C:busy>
- <C:queue v=2>
- p = &v; q = p;
- <D:request p>
- <B:modify p=&v> <D:commit p=&v>
- <D:read p>
- x = *q;
- <C:read *q> Reads from v before v updated in cache
- <C:unbusy>
- <C:commit v=2>
-
-Basically, while both cachelines will be updated on CPU 2 eventually, there's
-no guarantee that, without intervention, the order of update will be the same
-as that committed on CPU 1.
-
-
-To intervene, we need to interpolate a data dependency barrier or a read
-barrier between the loads (which as of v4.15 is supplied unconditionally
-by the READ_ONCE() macro). This will force the cache to commit its
-coherency queue before processing any further requests:
-
- CPU 1 CPU 2 COMMENT
- =============== =============== =======================================
- u == 0, v == 1 and p == &u, q == &u
- v = 2;
- smp_wmb();
- <A:modify v=2> <C:busy>
- <C:queue v=2>
- p = &v; q = p;
- <D:request p>
- <B:modify p=&v> <D:commit p=&v>
- <D:read p>
- smp_read_barrier_depends()
- <C:unbusy>
- <C:commit v=2>
- x = *q;
- <C:read *q> Reads from v after v updated in cache
-
-
-This sort of problem can be encountered on DEC Alpha processors as they have a
-split cache that improves performance by making better use of the data bus.
-While most CPUs do imply a data dependency barrier on the read when a memory
-access depends on a read, not all do, so it may not be relied on.
-
-Other CPUs may also have split caches, but must coordinate between the various
-cachelets for normal memory accesses. The semantics of the Alpha removes the
-need for hardware coordination in the absence of memory barriers, which
-permitted Alpha to sport higher CPU clock rates back in the day. However,
-please note that (again, as of v4.15) smp_read_barrier_depends() should not
-be used except in Alpha arch-specific code and within the READ_ONCE() macro.
-
-
CACHE COHERENCY VS DMA
----------------------
@@ -3009,10 +2885,8 @@
changes vs new data occur in the right order.
The Alpha defines the Linux kernel's memory model, although as of v4.15
-the Linux kernel's addition of smp_read_barrier_depends() to READ_ONCE()
-greatly reduced Alpha's impact on the memory model.
-
-See the subsection on "Cache Coherency" above.
+the Linux kernel's addition of smp_mb() to READ_ONCE() on Alpha greatly
+reduced its impact on the memory model.
VIRTUAL MACHINE GUESTS
diff --git a/Documentation/mips/ingenic-tcu.rst b/Documentation/mips/ingenic-tcu.rst
index c5a646b..2ce4cb1 100644
--- a/Documentation/mips/ingenic-tcu.rst
+++ b/Documentation/mips/ingenic-tcu.rst
@@ -5,7 +5,7 @@
===============================================
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
+hardware block. It features up to eight channels, that can be used as
counters, timers, or PWM.
- JZ4725B, JZ4750, JZ4755 only have six TCU channels. The other SoCs all
@@ -68,4 +68,4 @@
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/timer/ingenic,tcu.txt.
+have a look at Documentation/devicetree/bindings/timer/ingenic,tcu.yaml.
diff --git a/Documentation/misc-devices/ad525x_dpot.rst b/Documentation/misc-devices/ad525x_dpot.rst
new file mode 100644
index 0000000..6483ec2
--- /dev/null
+++ b/Documentation/misc-devices/ad525x_dpot.rst
@@ -0,0 +1,57 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+=============================
+AD525x Digital Potentiometers
+=============================
+
+The ad525x_dpot driver exports a simple sysfs interface. This allows you to
+work with the immediate resistance settings as well as update the saved startup
+settings. Access to the factory programmed tolerance is also provided, but
+interpretation of this settings is required by the end application according to
+the specific part in use.
+
+Files
+=====
+
+Each dpot device will have a set of eeprom, rdac, and tolerance files. How
+many depends on the actual part you have, as will the range of allowed values.
+
+The eeprom files are used to program the startup value of the device.
+
+The rdac files are used to program the immediate value of the device.
+
+The tolerance files are the read-only factory programmed tolerance settings
+and may vary greatly on a part-by-part basis. For exact interpretation of
+this field, please consult the datasheet for your part. This is presented
+as a hex file for easier parsing.
+
+Example
+=======
+
+Locate the device in your sysfs tree. This is probably easiest by going into
+the common i2c directory and locating the device by the i2c slave address::
+
+ # ls /sys/bus/i2c/devices/
+ 0-0022 0-0027 0-002f
+
+So assuming the device in question is on the first i2c bus and has the slave
+address of 0x2f, we descend (unrelated sysfs entries have been trimmed)::
+
+ # ls /sys/bus/i2c/devices/0-002f/
+ eeprom0 rdac0 tolerance0
+
+You can use simple reads/writes to access these files::
+
+ # cd /sys/bus/i2c/devices/0-002f/
+
+ # cat eeprom0
+ 0
+ # echo 10 > eeprom0
+ # cat eeprom0
+ 10
+
+ # cat rdac0
+ 5
+ # echo 3 > rdac0
+ # cat rdac0
+ 3
diff --git a/Documentation/misc-devices/ad525x_dpot.txt b/Documentation/misc-devices/ad525x_dpot.txt
deleted file mode 100644
index 0c9413b..0000000
--- a/Documentation/misc-devices/ad525x_dpot.txt
+++ /dev/null
@@ -1,57 +0,0 @@
----------------------------------
- AD525x Digital Potentiometers
----------------------------------
-
-The ad525x_dpot driver exports a simple sysfs interface. This allows you to
-work with the immediate resistance settings as well as update the saved startup
-settings. Access to the factory programmed tolerance is also provided, but
-interpretation of this settings is required by the end application according to
-the specific part in use.
-
----------
- Files
----------
-
-Each dpot device will have a set of eeprom, rdac, and tolerance files. How
-many depends on the actual part you have, as will the range of allowed values.
-
-The eeprom files are used to program the startup value of the device.
-
-The rdac files are used to program the immediate value of the device.
-
-The tolerance files are the read-only factory programmed tolerance settings
-and may vary greatly on a part-by-part basis. For exact interpretation of
-this field, please consult the datasheet for your part. This is presented
-as a hex file for easier parsing.
-
------------
- Example
------------
-
-Locate the device in your sysfs tree. This is probably easiest by going into
-the common i2c directory and locating the device by the i2c slave address.
-
- # ls /sys/bus/i2c/devices/
- 0-0022 0-0027 0-002f
-
-So assuming the device in question is on the first i2c bus and has the slave
-address of 0x2f, we descend (unrelated sysfs entries have been trimmed).
-
- # ls /sys/bus/i2c/devices/0-002f/
- eeprom0 rdac0 tolerance0
-
-You can use simple reads/writes to access these files:
-
- # cd /sys/bus/i2c/devices/0-002f/
-
- # cat eeprom0
- 0
- # echo 10 > eeprom0
- # cat eeprom0
- 10
-
- # cat rdac0
- 5
- # echo 3 > rdac0
- # cat rdac0
- 3
diff --git a/Documentation/misc-devices/apds990x.rst b/Documentation/misc-devices/apds990x.rst
new file mode 100644
index 0000000..e2f7557
--- /dev/null
+++ b/Documentation/misc-devices/apds990x.rst
@@ -0,0 +1,128 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+======================
+Kernel driver apds990x
+======================
+
+Supported chips:
+Avago APDS990X
+
+Data sheet:
+Not freely available
+
+Author:
+Samu Onkalo <samu.p.onkalo@nokia.com>
+
+Description
+-----------
+
+APDS990x is a combined ambient light and proximity sensor. ALS and proximity
+functionality are highly connected. ALS measurement path must be running
+while the proximity functionality is enabled.
+
+ALS produces raw measurement values for two channels: Clear channel
+(infrared + visible light) and IR only. However, threshold comparisons happen
+using clear channel only. Lux value and the threshold level on the HW
+might vary quite much depending the spectrum of the light source.
+
+Driver makes necessary conversions to both directions so that user handles
+only lux values. Lux value is calculated using information from the both
+channels. HW threshold level is calculated from the given lux value to match
+with current type of the lightning. Sometimes inaccuracy of the estimations
+lead to false interrupt, but that doesn't harm.
+
+ALS contains 4 different gain steps. Driver automatically
+selects suitable gain step. After each measurement, reliability of the results
+is estimated and new measurement is triggered if necessary.
+
+Platform data can provide tuned values to the conversion formulas if
+values are known. Otherwise plain sensor default values are used.
+
+Proximity side is little bit simpler. There is no need for complex conversions.
+It produces directly usable values.
+
+Driver controls chip operational state using pm_runtime framework.
+Voltage regulators are controlled based on chip operational state.
+
+SYSFS
+-----
+
+
+chip_id
+ RO - shows detected chip type and version
+
+power_state
+ RW - enable / disable chip. Uses counting logic
+
+ 1 enables the chip
+ 0 disables the chip
+lux0_input
+ RO - measured lux value
+
+ sysfs_notify called when threshold interrupt occurs
+
+lux0_sensor_range
+ RO - lux0_input max value.
+
+ Actually never reaches since sensor tends
+ to saturate much before that. Real max value varies depending
+ on the light spectrum etc.
+
+lux0_rate
+ RW - measurement rate in Hz
+
+lux0_rate_avail
+ RO - supported measurement rates
+
+lux0_calibscale
+ RW - calibration value.
+
+ Set to neutral value by default.
+ Output results are multiplied with calibscale / calibscale_default
+ value.
+
+lux0_calibscale_default
+ RO - neutral calibration value
+
+lux0_thresh_above_value
+ RW - HI level threshold value.
+
+ All results above the value
+ trigs an interrupt. 65535 (i.e. sensor_range) disables the above
+ interrupt.
+
+lux0_thresh_below_value
+ RW - LO level threshold value.
+
+ All results below the value
+ trigs an interrupt. 0 disables the below interrupt.
+
+prox0_raw
+ RO - measured proximity value
+
+ sysfs_notify called when threshold interrupt occurs
+
+prox0_sensor_range
+ RO - prox0_raw max value (1023)
+
+prox0_raw_en
+ RW - enable / disable proximity - uses counting logic
+
+ - 1 enables the proximity
+ - 0 disables the proximity
+
+prox0_reporting_mode
+ RW - trigger / periodic.
+
+ In "trigger" mode the driver tells two possible
+ values: 0 or prox0_sensor_range value. 0 means no proximity,
+ 1023 means proximity. This causes minimal number of interrupts.
+ In "periodic" mode the driver reports all values above
+ prox0_thresh_above. This causes more interrupts, but it can give
+ _rough_ estimate about the distance.
+
+prox0_reporting_mode_avail
+ RO - accepted values to prox0_reporting_mode (trigger, periodic)
+
+prox0_thresh_above_value
+ RW - threshold level which trigs proximity events.
diff --git a/Documentation/misc-devices/apds990x.txt b/Documentation/misc-devices/apds990x.txt
deleted file mode 100644
index 454d95d..0000000
--- a/Documentation/misc-devices/apds990x.txt
+++ /dev/null
@@ -1,111 +0,0 @@
-Kernel driver apds990x
-======================
-
-Supported chips:
-Avago APDS990X
-
-Data sheet:
-Not freely available
-
-Author:
-Samu Onkalo <samu.p.onkalo@nokia.com>
-
-Description
------------
-
-APDS990x is a combined ambient light and proximity sensor. ALS and proximity
-functionality are highly connected. ALS measurement path must be running
-while the proximity functionality is enabled.
-
-ALS produces raw measurement values for two channels: Clear channel
-(infrared + visible light) and IR only. However, threshold comparisons happen
-using clear channel only. Lux value and the threshold level on the HW
-might vary quite much depending the spectrum of the light source.
-
-Driver makes necessary conversions to both directions so that user handles
-only lux values. Lux value is calculated using information from the both
-channels. HW threshold level is calculated from the given lux value to match
-with current type of the lightning. Sometimes inaccuracy of the estimations
-lead to false interrupt, but that doesn't harm.
-
-ALS contains 4 different gain steps. Driver automatically
-selects suitable gain step. After each measurement, reliability of the results
-is estimated and new measurement is triggered if necessary.
-
-Platform data can provide tuned values to the conversion formulas if
-values are known. Otherwise plain sensor default values are used.
-
-Proximity side is little bit simpler. There is no need for complex conversions.
-It produces directly usable values.
-
-Driver controls chip operational state using pm_runtime framework.
-Voltage regulators are controlled based on chip operational state.
-
-SYSFS
------
-
-
-chip_id
- RO - shows detected chip type and version
-
-power_state
- RW - enable / disable chip. Uses counting logic
- 1 enables the chip
- 0 disables the chip
-lux0_input
- RO - measured lux value
- sysfs_notify called when threshold interrupt occurs
-
-lux0_sensor_range
- RO - lux0_input max value. Actually never reaches since sensor tends
- to saturate much before that. Real max value varies depending
- on the light spectrum etc.
-
-lux0_rate
- RW - measurement rate in Hz
-
-lux0_rate_avail
- RO - supported measurement rates
-
-lux0_calibscale
- RW - calibration value. Set to neutral value by default.
- Output results are multiplied with calibscale / calibscale_default
- value.
-
-lux0_calibscale_default
- RO - neutral calibration value
-
-lux0_thresh_above_value
- RW - HI level threshold value. All results above the value
- trigs an interrupt. 65535 (i.e. sensor_range) disables the above
- interrupt.
-
-lux0_thresh_below_value
- RW - LO level threshold value. All results below the value
- trigs an interrupt. 0 disables the below interrupt.
-
-prox0_raw
- RO - measured proximity value
- sysfs_notify called when threshold interrupt occurs
-
-prox0_sensor_range
- RO - prox0_raw max value (1023)
-
-prox0_raw_en
- RW - enable / disable proximity - uses counting logic
- 1 enables the proximity
- 0 disables the proximity
-
-prox0_reporting_mode
- RW - trigger / periodic. In "trigger" mode the driver tells two possible
- values: 0 or prox0_sensor_range value. 0 means no proximity,
- 1023 means proximity. This causes minimal number of interrupts.
- In "periodic" mode the driver reports all values above
- prox0_thresh_above. This causes more interrupts, but it can give
- _rough_ estimate about the distance.
-
-prox0_reporting_mode_avail
- RO - accepted values to prox0_reporting_mode (trigger, periodic)
-
-prox0_thresh_above_value
- RW - threshold level which trigs proximity events.
diff --git a/Documentation/misc-devices/bh1770glc.rst b/Documentation/misc-devices/bh1770glc.rst
new file mode 100644
index 0000000..ea5ca58
--- /dev/null
+++ b/Documentation/misc-devices/bh1770glc.rst
@@ -0,0 +1,135 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+=======================
+Kernel driver bh1770glc
+=======================
+
+Supported chips:
+
+- ROHM BH1770GLC
+- OSRAM SFH7770
+
+Data sheet:
+Not freely available
+
+Author:
+Samu Onkalo <samu.p.onkalo@nokia.com>
+
+Description
+-----------
+BH1770GLC and SFH7770 are combined ambient light and proximity sensors.
+ALS and proximity parts operates on their own, but they shares common I2C
+interface and interrupt logic. In principle they can run on their own,
+but ALS side results are used to estimate reliability of the proximity sensor.
+
+ALS produces 16 bit lux values. The chip contains interrupt logic to produce
+low and high threshold interrupts.
+
+Proximity part contains IR-led driver up to 3 IR leds. The chip measures
+amount of reflected IR light and produces proximity result. Resolution is
+8 bit. Driver supports only one channel. Driver uses ALS results to estimate
+reliability of the proximity results. Thus ALS is always running while
+proximity detection is needed.
+
+Driver uses threshold interrupts to avoid need for polling the values.
+Proximity low interrupt doesn't exists in the chip. This is simulated
+by using a delayed work. As long as there is proximity threshold above
+interrupts the delayed work is pushed forward. So, when proximity level goes
+below the threshold value, there is no interrupt and the delayed work will
+finally run. This is handled as no proximity indication.
+
+Chip state is controlled via runtime pm framework when enabled in config.
+
+Calibscale factor is used to hide differences between the chips. By default
+value set to neutral state meaning factor of 1.00. To get proper values,
+calibrated source of light is needed as a reference. Calibscale factor is set
+so that measurement produces about the expected lux value.
+
+SYSFS
+-----
+
+chip_id
+ RO - shows detected chip type and version
+
+power_state
+ RW - enable / disable chip
+
+ Uses counting logic
+
+ - 1 enables the chip
+ - 0 disables the chip
+
+lux0_input
+ RO - measured lux value
+
+ sysfs_notify called when threshold interrupt occurs
+
+lux0_sensor_range
+ RO - lux0_input max value
+
+lux0_rate
+ RW - measurement rate in Hz
+
+lux0_rate_avail
+ RO - supported measurement rates
+
+lux0_thresh_above_value
+ RW - HI level threshold value
+
+ All results above the value
+ trigs an interrupt. 65535 (i.e. sensor_range) disables the above
+ interrupt.
+
+lux0_thresh_below_value
+ RW - LO level threshold value
+
+ All results below the value
+ trigs an interrupt. 0 disables the below interrupt.
+
+lux0_calibscale
+ RW - calibration value
+
+ Set to neutral value by default.
+ Output results are multiplied with calibscale / calibscale_default
+ value.
+
+lux0_calibscale_default
+ RO - neutral calibration value
+
+prox0_raw
+ RO - measured proximity value
+
+ sysfs_notify called when threshold interrupt occurs
+
+prox0_sensor_range
+ RO - prox0_raw max value
+
+prox0_raw_en
+ RW - enable / disable proximity
+
+ Uses counting logic
+
+ - 1 enables the proximity
+ - 0 disables the proximity
+
+prox0_thresh_above_count
+ RW - number of proximity interrupts needed before triggering the event
+
+prox0_rate_above
+ RW - Measurement rate (in Hz) when the level is above threshold
+ i.e. when proximity on has been reported.
+
+prox0_rate_below
+ RW - Measurement rate (in Hz) when the level is below threshold
+ i.e. when proximity off has been reported.
+
+prox0_rate_avail
+ RO - Supported proximity measurement rates in Hz
+
+prox0_thresh_above0_value
+ RW - threshold level which trigs proximity events.
+
+ Filtered by persistence filter (prox0_thresh_above_count)
+
+prox0_thresh_above1_value
+ RW - threshold level which trigs event immediately
diff --git a/Documentation/misc-devices/bh1770glc.txt b/Documentation/misc-devices/bh1770glc.txt
deleted file mode 100644
index 7d64c01..0000000
--- a/Documentation/misc-devices/bh1770glc.txt
+++ /dev/null
@@ -1,116 +0,0 @@
-Kernel driver bh1770glc
-=======================
-
-Supported chips:
-ROHM BH1770GLC
-OSRAM SFH7770
-
-Data sheet:
-Not freely available
-
-Author:
-Samu Onkalo <samu.p.onkalo@nokia.com>
-
-Description
------------
-BH1770GLC and SFH7770 are combined ambient light and proximity sensors.
-ALS and proximity parts operates on their own, but they shares common I2C
-interface and interrupt logic. In principle they can run on their own,
-but ALS side results are used to estimate reliability of the proximity sensor.
-
-ALS produces 16 bit lux values. The chip contains interrupt logic to produce
-low and high threshold interrupts.
-
-Proximity part contains IR-led driver up to 3 IR leds. The chip measures
-amount of reflected IR light and produces proximity result. Resolution is
-8 bit. Driver supports only one channel. Driver uses ALS results to estimate
-reliability of the proximity results. Thus ALS is always running while
-proximity detection is needed.
-
-Driver uses threshold interrupts to avoid need for polling the values.
-Proximity low interrupt doesn't exists in the chip. This is simulated
-by using a delayed work. As long as there is proximity threshold above
-interrupts the delayed work is pushed forward. So, when proximity level goes
-below the threshold value, there is no interrupt and the delayed work will
-finally run. This is handled as no proximity indication.
-
-Chip state is controlled via runtime pm framework when enabled in config.
-
-Calibscale factor is used to hide differences between the chips. By default
-value set to neutral state meaning factor of 1.00. To get proper values,
-calibrated source of light is needed as a reference. Calibscale factor is set
-so that measurement produces about the expected lux value.
-
-SYSFS
------
-
-chip_id
- RO - shows detected chip type and version
-
-power_state
- RW - enable / disable chip. Uses counting logic
- 1 enables the chip
- 0 disables the chip
-
-lux0_input
- RO - measured lux value
- sysfs_notify called when threshold interrupt occurs
-
-lux0_sensor_range
- RO - lux0_input max value
-
-lux0_rate
- RW - measurement rate in Hz
-
-lux0_rate_avail
- RO - supported measurement rates
-
-lux0_thresh_above_value
- RW - HI level threshold value. All results above the value
- trigs an interrupt. 65535 (i.e. sensor_range) disables the above
- interrupt.
-
-lux0_thresh_below_value
- RW - LO level threshold value. All results below the value
- trigs an interrupt. 0 disables the below interrupt.
-
-lux0_calibscale
- RW - calibration value. Set to neutral value by default.
- Output results are multiplied with calibscale / calibscale_default
- value.
-
-lux0_calibscale_default
- RO - neutral calibration value
-
-prox0_raw
- RO - measured proximity value
- sysfs_notify called when threshold interrupt occurs
-
-prox0_sensor_range
- RO - prox0_raw max value
-
-prox0_raw_en
- RW - enable / disable proximity - uses counting logic
- 1 enables the proximity
- 0 disables the proximity
-
-prox0_thresh_above_count
- RW - number of proximity interrupts needed before triggering the event
-
-prox0_rate_above
- RW - Measurement rate (in Hz) when the level is above threshold
- i.e. when proximity on has been reported.
-
-prox0_rate_below
- RW - Measurement rate (in Hz) when the level is below threshold
- i.e. when proximity off has been reported.
-
-prox0_rate_avail
- RO - Supported proximity measurement rates in Hz
-
-prox0_thresh_above0_value
- RW - threshold level which trigs proximity events.
- Filtered by persistence filter (prox0_thresh_above_count)
-
-prox0_thresh_above1_value
- RW - threshold level which trigs event immediately
diff --git a/Documentation/misc-devices/c2port.rst b/Documentation/misc-devices/c2port.rst
new file mode 100644
index 0000000..7e4f6a7
--- /dev/null
+++ b/Documentation/misc-devices/c2port.rst
@@ -0,0 +1,94 @@
+.. SPDX-License-Identifier: GPL-2.0
+.. include:: <isonum.txt>
+
+===============
+C2 port support
+===============
+
+(C) Copyright 2007 Rodolfo Giometti <giometti@enneenne.com>
+
+This program is free software; you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+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.
+
+
+
+Overview
+--------
+
+This driver implements the support for Linux of Silicon Labs (Silabs)
+C2 Interface used for in-system programming of micro controllers.
+
+By using this driver you can reprogram the in-system flash without EC2
+or EC3 debug adapter. This solution is also useful in those systems
+where the micro controller is connected via special GPIOs pins.
+
+References
+----------
+
+The C2 Interface main references are at (https://www.silabs.com)
+Silicon Laboratories site], see:
+
+- AN127: FLASH Programming via the C2 Interface at
+ https://www.silabs.com/Support Documents/TechnicalDocs/an127.pdf
+
+- C2 Specification at
+ https://www.silabs.com/pages/DownloadDoc.aspx?FILEURL=Support%20Documents/TechnicalDocs/an127.pdf&src=SearchResults
+
+however it implements a two wire serial communication protocol (bit
+banging) designed to enable in-system programming, debugging, and
+boundary-scan testing on low pin-count Silicon Labs devices. Currently
+this code supports only flash programming but extensions are easy to
+add.
+
+Using the driver
+----------------
+
+Once the driver is loaded you can use sysfs support to get C2port's
+info or read/write in-system flash::
+
+ # ls /sys/class/c2port/c2port0/
+ access flash_block_size flash_erase rev_id
+ dev_id flash_blocks_num flash_size subsystem/
+ flash_access flash_data reset uevent
+
+Initially the C2port access is disabled since you hardware may have
+such lines multiplexed with other devices so, to get access to the
+C2port, you need the command::
+
+ # echo 1 > /sys/class/c2port/c2port0/access
+
+after that you should read the device ID and revision ID of the
+connected micro controller::
+
+ # cat /sys/class/c2port/c2port0/dev_id
+ 8
+ # cat /sys/class/c2port/c2port0/rev_id
+ 1
+
+However, for security reasons, the in-system flash access in not
+enabled yet, to do so you need the command::
+
+ # echo 1 > /sys/class/c2port/c2port0/flash_access
+
+After that you can read the whole flash::
+
+ # cat /sys/class/c2port/c2port0/flash_data > image
+
+erase it::
+
+ # echo 1 > /sys/class/c2port/c2port0/flash_erase
+
+and write it::
+
+ # cat image > /sys/class/c2port/c2port0/flash_data
+
+after writing you have to reset the device to execute the new code::
+
+ # echo 1 > /sys/class/c2port/c2port0/reset
diff --git a/Documentation/misc-devices/c2port.txt b/Documentation/misc-devices/c2port.txt
deleted file mode 100644
index 31351b1..0000000
--- a/Documentation/misc-devices/c2port.txt
+++ /dev/null
@@ -1,90 +0,0 @@
- C2 port support
- ---------------
-
-(C) Copyright 2007 Rodolfo Giometti <giometti@enneenne.com>
-
-This program is free software; you can redistribute it and/or modify
-it under the terms of the GNU General Public License as published by
-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.
-
-
-
-Overview
---------
-
-This driver implements the support for Linux of Silicon Labs (Silabs)
-C2 Interface used for in-system programming of micro controllers.
-
-By using this driver you can reprogram the in-system flash without EC2
-or EC3 debug adapter. This solution is also useful in those systems
-where the micro controller is connected via special GPIOs pins.
-
-References
-----------
-
-The C2 Interface main references are at (https://www.silabs.com)
-Silicon Laboratories site], see:
-
-- AN127: FLASH Programming via the C2 Interface at
-https://www.silabs.com/Support Documents/TechnicalDocs/an127.pdf
-
-- C2 Specification at
-https://www.silabs.com/pages/DownloadDoc.aspx?FILEURL=Support%20Documents/TechnicalDocs/an127.pdf&src=SearchResults
-
-however it implements a two wire serial communication protocol (bit
-banging) designed to enable in-system programming, debugging, and
-boundary-scan testing on low pin-count Silicon Labs devices. Currently
-this code supports only flash programming but extensions are easy to
-add.
-
-Using the driver
-----------------
-
-Once the driver is loaded you can use sysfs support to get C2port's
-info or read/write in-system flash.
-
-# ls /sys/class/c2port/c2port0/
-access flash_block_size flash_erase rev_id
-dev_id flash_blocks_num flash_size subsystem/
-flash_access flash_data reset uevent
-
-Initially the C2port access is disabled since you hardware may have
-such lines multiplexed with other devices so, to get access to the
-C2port, you need the command:
-
-# echo 1 > /sys/class/c2port/c2port0/access
-
-after that you should read the device ID and revision ID of the
-connected micro controller:
-
-# cat /sys/class/c2port/c2port0/dev_id
-8
-# cat /sys/class/c2port/c2port0/rev_id
-1
-
-However, for security reasons, the in-system flash access in not
-enabled yet, to do so you need the command:
-
-# echo 1 > /sys/class/c2port/c2port0/flash_access
-
-After that you can read the whole flash:
-
-# cat /sys/class/c2port/c2port0/flash_data > image
-
-erase it:
-
-# echo 1 > /sys/class/c2port/c2port0/flash_erase
-
-and write it:
-
-# cat image > /sys/class/c2port/c2port0/flash_data
-
-after writing you have to reset the device to execute the new code:
-
-# echo 1 > /sys/class/c2port/c2port0/reset
diff --git a/Documentation/misc-devices/index.rst b/Documentation/misc-devices/index.rst
index 1ecc05f..46072ce 100644
--- a/Documentation/misc-devices/index.rst
+++ b/Documentation/misc-devices/index.rst
@@ -14,12 +14,18 @@
.. toctree::
:maxdepth: 2
+ ad525x_dpot
+ apds990x
+ bh1770glc
eeprom
+ c2port
ibmvmc
ics932s401
isl29003
lis3lv02d
max6875
mic/index
+ pci-endpoint-test
+ spear-pcie-gadget
uacce
xilinx_sdfec
diff --git a/Documentation/misc-devices/pci-endpoint-test.rst b/Documentation/misc-devices/pci-endpoint-test.rst
new file mode 100644
index 0000000..4cf3f44
--- /dev/null
+++ b/Documentation/misc-devices/pci-endpoint-test.rst
@@ -0,0 +1,56 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+=====================================
+Driver for PCI Endpoint Test Function
+=====================================
+
+This driver should be used as a host side driver if the root complex is
+connected to a configurable PCI endpoint running ``pci_epf_test`` function
+driver configured according to [1]_.
+
+The "pci_endpoint_test" driver can be used to perform the following tests.
+
+The PCI driver for the test device performs the following tests:
+
+ #) verifying addresses programmed in BAR
+ #) raise legacy IRQ
+ #) raise MSI IRQ
+ #) raise MSI-X IRQ
+ #) read data
+ #) write data
+ #) copy data
+
+This misc driver creates /dev/pci-endpoint-test.<num> for every
+``pci_epf_test`` function connected to the root complex and "ioctls"
+should be used to perform the above tests.
+
+ioctl
+-----
+
+ PCITEST_BAR:
+ Tests the BAR. The number of the BAR to be tested
+ should be passed as argument.
+ PCITEST_LEGACY_IRQ:
+ Tests legacy IRQ
+ PCITEST_MSI:
+ Tests message signalled interrupts. The MSI number
+ to be tested should be passed as argument.
+ PCITEST_MSIX:
+ Tests message signalled interrupts. The MSI-X number
+ to be tested should be passed as argument.
+ PCITEST_SET_IRQTYPE:
+ Changes driver IRQ type configuration. The IRQ type
+ should be passed as argument (0: Legacy, 1:MSI, 2:MSI-X).
+ PCITEST_GET_IRQTYPE:
+ Gets driver IRQ type configuration.
+ PCITEST_WRITE:
+ Perform write tests. The size of the buffer should be passed
+ as argument.
+ PCITEST_READ:
+ Perform read tests. The size of the buffer should be passed
+ as argument.
+ PCITEST_COPY:
+ Perform read tests. The size of the buffer should be passed
+ as argument.
+
+.. [1] Documentation/PCI/endpoint/function/binding/pci-test.rst
diff --git a/Documentation/misc-devices/pci-endpoint-test.txt b/Documentation/misc-devices/pci-endpoint-test.txt
deleted file mode 100644
index 58ccca4..0000000
--- a/Documentation/misc-devices/pci-endpoint-test.txt
+++ /dev/null
@@ -1,41 +0,0 @@
-Driver for PCI Endpoint Test Function
-
-This driver should be used as a host side driver if the root complex is
-connected to a configurable PCI endpoint running *pci_epf_test* function
-driver configured according to [1].
-
-The "pci_endpoint_test" driver can be used to perform the following tests.
-
-The PCI driver for the test device performs the following tests
- *) verifying addresses programmed in BAR
- *) raise legacy IRQ
- *) raise MSI IRQ
- *) raise MSI-X IRQ
- *) read data
- *) write data
- *) copy data
-
-This misc driver creates /dev/pci-endpoint-test.<num> for every
-*pci_epf_test* function connected to the root complex and "ioctls"
-should be used to perform the above tests.
-
-ioctl
------
- PCITEST_BAR: Tests the BAR. The number of the BAR to be tested
- should be passed as argument.
- PCITEST_LEGACY_IRQ: Tests legacy IRQ
- PCITEST_MSI: Tests message signalled interrupts. The MSI number
- to be tested should be passed as argument.
- PCITEST_MSIX: Tests message signalled interrupts. The MSI-X number
- to be tested should be passed as argument.
- PCITEST_SET_IRQTYPE: Changes driver IRQ type configuration. The IRQ type
- should be passed as argument (0: Legacy, 1:MSI, 2:MSI-X).
- PCITEST_GET_IRQTYPE: Gets driver IRQ type configuration.
- PCITEST_WRITE: Perform write tests. The size of the buffer should be passed
- as argument.
- PCITEST_READ: Perform read tests. The size of the buffer should be passed
- as argument.
- PCITEST_COPY: Perform read tests. The size of the buffer should be passed
- as argument.
-
-[1] -> Documentation/PCI/endpoint/function/binding/pci-test.txt
diff --git a/Documentation/misc-devices/spear-pcie-gadget.rst b/Documentation/misc-devices/spear-pcie-gadget.rst
new file mode 100644
index 0000000..09b9d6c
--- /dev/null
+++ b/Documentation/misc-devices/spear-pcie-gadget.rst
@@ -0,0 +1,170 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+========================
+Spear PCIe Gadget Driver
+========================
+
+Author
+======
+Pratyush Anand (pratyush.anand@gmail.com)
+
+Location
+========
+driver/misc/spear13xx_pcie_gadget.c
+
+Supported Chip:
+===============
+SPEAr1300
+SPEAr1310
+
+Menuconfig option:
+==================
+Device Drivers
+ Misc devices
+ PCIe gadget support for SPEAr13XX platform
+
+purpose
+=======
+This driver has several nodes which can be read/written by configfs interface.
+Its main purpose is to configure selected dual mode PCIe controller as device
+and then program its various registers to configure it as a particular device
+type. This driver can be used to show spear's PCIe device capability.
+
+Description of different nodes:
+===============================
+
+read behavior of nodes:
+-----------------------
+
+=============== ==============================================================
+link gives ltssm status.
+int_type type of supported interrupt
+no_of_msi zero if MSI is not enabled by host. A positive value is the
+ number of MSI vector granted.
+vendor_id returns programmed vendor id (hex)
+device_id returns programmed device id(hex)
+bar0_size: returns size of bar0 in hex.
+bar0_address returns address of bar0 mapped area in hex.
+bar0_rw_offset returns offset of bar0 for which bar0_data will return value.
+bar0_data returns data at bar0_rw_offset.
+=============== ==============================================================
+
+write behavior of nodes:
+------------------------
+
+=============== ================================================================
+link write UP to enable ltsmm DOWN to disable
+int_type write interrupt type to be configured and (int_type could be
+ INTA, MSI or NO_INT). Select MSI only when you have programmed
+ no_of_msi node.
+no_of_msi number of MSI vector needed.
+inta write 1 to assert INTA and 0 to de-assert.
+send_msi write MSI vector to be sent.
+vendor_id write vendor id(hex) to be programmed.
+device_id write device id(hex) to be programmed.
+bar0_size write size of bar0 in hex. default bar0 size is 1000 (hex)
+ bytes.
+bar0_address write address of bar0 mapped area in hex. (default mapping of
+ bar0 is SYSRAM1(E0800000). Always program bar size before bar
+ address. Kernel might modify bar size and address for alignment,
+ so read back bar size and address after writing to cross check.
+bar0_rw_offset write offset of bar0 for which bar0_data will write value.
+bar0_data write data to be written at bar0_rw_offset.
+=============== ================================================================
+
+Node programming example
+========================
+
+Program all PCIe registers in such a way that when this device is connected
+to the PCIe host, then host sees this device as 1MB RAM.
+
+::
+
+ #mount -t configfs none /Config
+
+For nth PCIe Device Controller::
+
+ # cd /config/pcie_gadget.n/
+
+Now you have all the nodes in this directory.
+program vendor id as 0x104a::
+
+ # echo 104A >> vendor_id
+
+program device id as 0xCD80::
+
+ # echo CD80 >> device_id
+
+program BAR0 size as 1MB::
+
+ # echo 100000 >> bar0_size
+
+check for programmed bar0 size::
+
+ # cat bar0_size
+
+Program BAR0 Address as DDR (0x2100000). This is the physical address of
+memory, which is to be made visible to PCIe host. Similarly any other peripheral
+can also be made visible to PCIe host. E.g., if you program base address of UART
+as BAR0 address then when this device will be connected to a host, it will be
+visible as UART.
+
+::
+
+ # echo 2100000 >> bar0_address
+
+program interrupt type : INTA::
+
+ # echo INTA >> int_type
+
+go for link up now::
+
+ # echo UP >> link
+
+It will have to be insured that, once link up is done on gadget, then only host
+is initialized and start to search PCIe devices on its port.
+
+::
+
+ /*wait till link is up*/
+ # cat link
+
+Wait till it returns UP.
+
+To assert INTA::
+
+ # echo 1 >> inta
+
+To de-assert INTA::
+
+ # echo 0 >> inta
+
+if MSI is to be used as interrupt, program no of msi vector needed (say4)::
+
+ # echo 4 >> no_of_msi
+
+select MSI as interrupt type::
+
+ # echo MSI >> int_type
+
+go for link up now::
+
+ # echo UP >> link
+
+wait till link is up::
+
+ # cat link
+
+An application can repetitively read this node till link is found UP. It can
+sleep between two read.
+
+wait till msi is enabled::
+
+ # cat no_of_msi
+
+Should return 4 (number of requested MSI vector)
+
+to send msi vector 2::
+
+ # echo 2 >> send_msi
+ # cd -
diff --git a/Documentation/misc-devices/spear-pcie-gadget.txt b/Documentation/misc-devices/spear-pcie-gadget.txt
deleted file mode 100644
index 89b88de..0000000
--- a/Documentation/misc-devices/spear-pcie-gadget.txt
+++ /dev/null
@@ -1,130 +0,0 @@
-Spear PCIe Gadget Driver:
-
-Author
-=============
-Pratyush Anand (pratyush.anand@gmail.com)
-
-Location
-============
-driver/misc/spear13xx_pcie_gadget.c
-
-Supported Chip:
-===================
-SPEAr1300
-SPEAr1310
-
-Menuconfig option:
-==========================
-Device Drivers
- Misc devices
- PCIe gadget support for SPEAr13XX platform
-purpose
-===========
-This driver has several nodes which can be read/written by configfs interface.
-Its main purpose is to configure selected dual mode PCIe controller as device
-and then program its various registers to configure it as a particular device
-type. This driver can be used to show spear's PCIe device capability.
-
-Description of different nodes:
-=================================
-
-read behavior of nodes:
-------------------------------
-link :gives ltssm status.
-int_type :type of supported interrupt
-no_of_msi :zero if MSI is not enabled by host. A positive value is the
- number of MSI vector granted.
-vendor_id :returns programmed vendor id (hex)
-device_id :returns programmed device id(hex)
-bar0_size: :returns size of bar0 in hex.
-bar0_address :returns address of bar0 mapped area in hex.
-bar0_rw_offset :returns offset of bar0 for which bar0_data will return value.
-bar0_data :returns data at bar0_rw_offset.
-
-write behavior of nodes:
-------------------------------
-link :write UP to enable ltsmm DOWN to disable
-int_type :write interrupt type to be configured and (int_type could be
- INTA, MSI or NO_INT). Select MSI only when you have programmed
- no_of_msi node.
-no_of_msi :number of MSI vector needed.
-inta :write 1 to assert INTA and 0 to de-assert.
-send_msi :write MSI vector to be sent.
-vendor_id :write vendor id(hex) to be programmed.
-device_id :write device id(hex) to be programmed.
-bar0_size :write size of bar0 in hex. default bar0 size is 1000 (hex)
- bytes.
-bar0_address :write address of bar0 mapped area in hex. (default mapping of
- bar0 is SYSRAM1(E0800000). Always program bar size before bar
- address. Kernel might modify bar size and address for alignment, so
- read back bar size and address after writing to cross check.
-bar0_rw_offset :write offset of bar0 for which bar0_data will write value.
-bar0_data :write data to be written at bar0_rw_offset.
-
-Node programming example
-===========================
-Program all PCIe registers in such a way that when this device is connected
-to the PCIe host, then host sees this device as 1MB RAM.
-#mount -t configfs none /Config
-For nth PCIe Device Controller
-# cd /config/pcie_gadget.n/
-Now you have all the nodes in this directory.
-program vendor id as 0x104a
-# echo 104A >> vendor_id
-
-program device id as 0xCD80
-# echo CD80 >> device_id
-
-program BAR0 size as 1MB
-# echo 100000 >> bar0_size
-
-check for programmed bar0 size
-# cat bar0_size
-
-Program BAR0 Address as DDR (0x2100000). This is the physical address of
-memory, which is to be made visible to PCIe host. Similarly any other peripheral
-can also be made visible to PCIe host. E.g., if you program base address of UART
-as BAR0 address then when this device will be connected to a host, it will be
-visible as UART.
-# echo 2100000 >> bar0_address
-
-program interrupt type : INTA
-# echo INTA >> int_type
-
-go for link up now.
-# echo UP >> link
-
-It will have to be insured that, once link up is done on gadget, then only host
-is initialized and start to search PCIe devices on its port.
-
-/*wait till link is up*/
-# cat link
-wait till it returns UP.
-
-To assert INTA
-# echo 1 >> inta
-
-To de-assert INTA
-# echo 0 >> inta
-
-if MSI is to be used as interrupt, program no of msi vector needed (say4)
-# echo 4 >> no_of_msi
-
-select MSI as interrupt type
-# echo MSI >> int_type
-
-go for link up now
-# echo UP >> link
-
-wait till link is up
-# cat link
-An application can repetitively read this node till link is found UP. It can
-sleep between two read.
-
-wait till msi is enabled
-# cat no_of_msi
-Should return 4 (number of requested MSI vector)
-
-to send msi vector 2
-# echo 2 >> send_msi
-#cd -
diff --git a/Documentation/misc-devices/xilinx_sdfec.rst b/Documentation/misc-devices/xilinx_sdfec.rst
index 7a47075..8c8a289 100644
--- a/Documentation/misc-devices/xilinx_sdfec.rst
+++ b/Documentation/misc-devices/xilinx_sdfec.rst
@@ -78,7 +78,7 @@
- open: Implements restriction that only a single file descriptor can be open per SD-FEC instance at any time
- release: Allows another file descriptor to be open, that is after current file descriptor is closed
- poll: Provides a method to monitor for SD-FEC Error events
- - unlocked_ioctl: Provides the the following ioctl commands that allows the application configure the SD-FEC core:
+ - unlocked_ioctl: Provides the following ioctl commands that allows the application configure the SD-FEC core:
- :c:macro:`XSDFEC_START_DEV`
- :c:macro:`XSDFEC_STOP_DEV`
diff --git a/Documentation/networking/arcnet.rst b/Documentation/networking/arcnet.rst
index e93d982..82fce60 100644
--- a/Documentation/networking/arcnet.rst
+++ b/Documentation/networking/arcnet.rst
@@ -434,7 +434,7 @@
ifconfig arc0 insight
route add insight arc0
route add freedom arc0 /* I would use the subnet here (like I said
- to to in "single protocol" above),
+ to in "single protocol" above),
but the rest of the subnet
unfortunately lies across the PPP
link on freedom, which confuses
diff --git a/Documentation/networking/ax25.rst b/Documentation/networking/ax25.rst
index 824afd7..f060cfb 100644
--- a/Documentation/networking/ax25.rst
+++ b/Documentation/networking/ax25.rst
@@ -6,7 +6,7 @@
To use the amateur radio protocols within Linux you will need to get a
suitable copy of the AX.25 Utilities. More detailed information about
-AX.25, NET/ROM and ROSE, associated programs and and utilities can be
+AX.25, NET/ROM and ROSE, associated programs and utilities can be
found on http://www.linux-ax25.org.
There is an active mailing list for discussing Linux amateur radio matters
diff --git a/Documentation/networking/bareudp.rst b/Documentation/networking/bareudp.rst
index 465a8b2..b9d04ee 100644
--- a/Documentation/networking/bareudp.rst
+++ b/Documentation/networking/bareudp.rst
@@ -8,9 +8,8 @@
leverage the UDP based load balancing capability of different networks.
MPLSoUDP (__ https://tools.ietf.org/html/rfc7510) is one among them.
-The Bareudp tunnel module provides a generic L3 encapsulation tunnelling
-support for tunnelling different L3 protocols like MPLS, IP, NSH etc. inside
-a UDP tunnel.
+The Bareudp tunnel module provides a generic L3 encapsulation support for
+tunnelling different L3 protocols like MPLS, IP, NSH etc. inside a UDP tunnel.
Special Handling
----------------
@@ -26,7 +25,7 @@
1) Device creation & deletion
- a) ip link add dev bareudp0 type bareudp dstport 6635 ethertype 0x8847.
+ a) ip link add dev bareudp0 type bareudp dstport 6635 ethertype mpls_uc
This creates a bareudp tunnel device which tunnels L3 traffic with ethertype
0x8847 (MPLS traffic). The destination port of the UDP header will be set to
@@ -34,14 +33,21 @@
b) ip link delete bareudp0
-2) Device creation with multiple proto mode enabled
+2) Device creation with multiproto mode enabled
-There are two ways to create a bareudp device for MPLS & IP with multiproto mode
-enabled.
+The multiproto mode allows bareudp tunnels to handle several protocols of the
+same family. It is currently only available for IP and MPLS. This mode has to
+be enabled explicitly with the "multiproto" flag.
- a) ip link add dev bareudp0 type bareudp dstport 6635 ethertype 0x8847 multiproto
+ a) ip link add dev bareudp0 type bareudp dstport 6635 ethertype ipv4 multiproto
- b) ip link add dev bareudp0 type bareudp dstport 6635 ethertype mpls
+ For an IPv4 tunnel the multiproto mode allows the tunnel to also handle
+ IPv6.
+
+ b) ip link add dev bareudp0 type bareudp dstport 6635 ethertype mpls_uc multiproto
+
+ For MPLS, the multiproto mode allows the tunnel to handle both unicast
+ and multicast MPLS packets.
3) Device Usage
diff --git a/Documentation/networking/batman-adv.rst b/Documentation/networking/batman-adv.rst
index 1802094..74821d2 100644
--- a/Documentation/networking/batman-adv.rst
+++ b/Documentation/networking/batman-adv.rst
@@ -73,7 +73,7 @@
will also increase the overhead.
Information about the current state can be accessed via the batadv generic
-netlink family. batctl provides human readable version via its debug tables
+netlink family. batctl provides a human readable version via its debug tables
subcommands.
@@ -115,8 +115,8 @@
$ dmesg | grep batman-adv
When investigating problems with your mesh network, it is sometimes necessary to
-see more detail debug messages. This must be enabled when compiling the
-batman-adv module. When building batman-adv as part of kernel, use "make
+see more detailed debug messages. This must be enabled when compiling the
+batman-adv module. When building batman-adv as part of the kernel, use "make
menuconfig" and enable the option ``B.A.T.M.A.N. debugging``
(``CONFIG_BATMAN_ADV_DEBUG=y``).
@@ -160,7 +160,7 @@
#batman on irc.freenode.org
Mailing-list:
b.a.t.m.a.n@open-mesh.org (optional subscription at
- https://lists.open-mesh.org/mm/listinfo/b.a.t.m.a.n)
+ https://lists.open-mesh.org/mailman3/postorius/lists/b.a.t.m.a.n.lists.open-mesh.org/)
You can also contact the Authors:
diff --git a/Documentation/networking/can_ucan_protocol.rst b/Documentation/networking/can_ucan_protocol.rst
index 4cef88d..638ac1e 100644
--- a/Documentation/networking/can_ucan_protocol.rst
+++ b/Documentation/networking/can_ucan_protocol.rst
@@ -144,7 +144,7 @@
*Host2Dev; mandatory*
-Setup bittiming by sending the the structure
+Setup bittiming by sending the structure
``ucan_ctl_payload_t.cmd_set_bittiming`` (see ``struct bittiming`` for
details)
@@ -232,7 +232,7 @@
zero
The CAN device has sent a message to the CAN bus. It answers with a
-list of of tuples <echo-ids, flags>.
+list of tuples <echo-ids, flags>.
The echo-id identifies the frame from (echos the id from a previous
UCAN_OUT_TX message). The flag indicates the result of the
diff --git a/Documentation/networking/dccp.rst b/Documentation/networking/dccp.rst
index dde16be..91e5c33 100644
--- a/Documentation/networking/dccp.rst
+++ b/Documentation/networking/dccp.rst
@@ -192,6 +192,9 @@
Works as in udp(7): returns in the ``int`` argument pointer the size of
the next pending datagram in bytes, or 0 when no datagram is pending.
+SIOCOUTQ
+ Returns the number of unsent data bytes in the socket send queue as ``int``
+ into the buffer specified by the argument pointer.
Other tunables
==============
diff --git a/Documentation/networking/device_drivers/3com/vortex.rst b/Documentation/networking/device_drivers/3com/vortex.rst
deleted file mode 100644
index 800add5..0000000
--- a/Documentation/networking/device_drivers/3com/vortex.rst
+++ /dev/null
@@ -1,461 +0,0 @@
-.. SPDX-License-Identifier: GPL-2.0
-
-=========================
-3Com Vortex device driver
-=========================
-
-Documentation/networking/device_drivers/3com/vortex.rst
-
-Andrew Morton
-
-30 April 2000
-
-
-This document describes the usage and errata of the 3Com "Vortex" device
-driver for Linux, 3c59x.c.
-
-The driver was written by Donald Becker <becker@scyld.com>
-
-Don is no longer the prime maintainer of this version of the driver.
-Please report problems to one or more of:
-
-- Andrew Morton
-- Netdev mailing list <netdev@vger.kernel.org>
-- Linux kernel mailing list <linux-kernel@vger.kernel.org>
-
-Please note the 'Reporting and Diagnosing Problems' section at the end
-of this file.
-
-
-Since kernel 2.3.99-pre6, this driver incorporates the support for the
-3c575-series Cardbus cards which used to be handled by 3c575_cb.c.
-
-This driver supports the following hardware:
-
- - 3c590 Vortex 10Mbps
- - 3c592 EISA 10Mbps Demon/Vortex
- - 3c597 EISA Fast Demon/Vortex
- - 3c595 Vortex 100baseTx
- - 3c595 Vortex 100baseT4
- - 3c595 Vortex 100base-MII
- - 3c900 Boomerang 10baseT
- - 3c900 Boomerang 10Mbps Combo
- - 3c900 Cyclone 10Mbps TPO
- - 3c900 Cyclone 10Mbps Combo
- - 3c900 Cyclone 10Mbps TPC
- - 3c900B-FL Cyclone 10base-FL
- - 3c905 Boomerang 100baseTx
- - 3c905 Boomerang 100baseT4
- - 3c905B Cyclone 100baseTx
- - 3c905B Cyclone 10/100/BNC
- - 3c905B-FX Cyclone 100baseFx
- - 3c905C Tornado
- - 3c920B-EMB-WNM (ATI Radeon 9100 IGP)
- - 3c980 Cyclone
- - 3c980C Python-T
- - 3cSOHO100-TX Hurricane
- - 3c555 Laptop Hurricane
- - 3c556 Laptop Tornado
- - 3c556B Laptop Hurricane
- - 3c575 [Megahertz] 10/100 LAN CardBus
- - 3c575 Boomerang CardBus
- - 3CCFE575BT Cyclone CardBus
- - 3CCFE575CT Tornado CardBus
- - 3CCFE656 Cyclone CardBus
- - 3CCFEM656B Cyclone+Winmodem CardBus
- - 3CXFEM656C Tornado+Winmodem CardBus
- - 3c450 HomePNA Tornado
- - 3c920 Tornado
- - 3c982 Hydra Dual Port A
- - 3c982 Hydra Dual Port B
- - 3c905B-T4
- - 3c920B-EMB-WNM Tornado
-
-Module parameters
-=================
-
-There are several parameters which may be provided to the driver when
-its module is loaded. These are usually placed in ``/etc/modprobe.d/*.conf``
-configuration files. Example::
-
- options 3c59x debug=3 rx_copybreak=300
-
-If you are using the PCMCIA tools (cardmgr) then the options may be
-placed in /etc/pcmcia/config.opts::
-
- module "3c59x" opts "debug=3 rx_copybreak=300"
-
-
-The supported parameters are:
-
-debug=N
-
- Where N is a number from 0 to 7. Anything above 3 produces a lot
- of output in your system logs. debug=1 is default.
-
-options=N1,N2,N3,...
-
- Each number in the list provides an option to the corresponding
- network card. So if you have two 3c905's and you wish to provide
- them with option 0x204 you would use::
-
- options=0x204,0x204
-
- The individual options are composed of a number of bitfields which
- have the following meanings:
-
- Possible media type settings
-
- == =================================
- 0 10baseT
- 1 10Mbs AUI
- 2 undefined
- 3 10base2 (BNC)
- 4 100base-TX
- 5 100base-FX
- 6 MII (Media Independent Interface)
- 7 Use default setting from EEPROM
- 8 Autonegotiate
- 9 External MII
- 10 Use default setting from EEPROM
- == =================================
-
- When generating a value for the 'options' setting, the above media
- selection values may be OR'ed (or added to) the following:
-
- ====== =============================================
- 0x8000 Set driver debugging level to 7
- 0x4000 Set driver debugging level to 2
- 0x0400 Enable Wake-on-LAN
- 0x0200 Force full duplex mode.
- 0x0010 Bus-master enable bit (Old Vortex cards only)
- ====== =============================================
-
- For example::
-
- insmod 3c59x options=0x204
-
- will force full-duplex 100base-TX, rather than allowing the usual
- autonegotiation.
-
-global_options=N
-
- Sets the ``options`` parameter for all 3c59x NICs in the machine.
- Entries in the ``options`` array above will override any setting of
- this.
-
-full_duplex=N1,N2,N3...
-
- Similar to bit 9 of 'options'. Forces the corresponding card into
- full-duplex mode. Please use this in preference to the ``options``
- parameter.
-
- In fact, please don't use this at all! You're better off getting
- autonegotiation working properly.
-
-global_full_duplex=N1
-
- Sets full duplex mode for all 3c59x NICs in the machine. Entries
- in the ``full_duplex`` array above will override any setting of this.
-
-flow_ctrl=N1,N2,N3...
-
- Use 802.3x MAC-layer flow control. The 3com cards only support the
- PAUSE command, which means that they will stop sending packets for a
- short period if they receive a PAUSE frame from the link partner.
-
- The driver only allows flow control on a link which is operating in
- full duplex mode.
-
- This feature does not appear to work on the 3c905 - only 3c905B and
- 3c905C have been tested.
-
- The 3com cards appear to only respond to PAUSE frames which are
- sent to the reserved destination address of 01:80:c2:00:00:01. They
- do not honour PAUSE frames which are sent to the station MAC address.
-
-rx_copybreak=M
-
- The driver preallocates 32 full-sized (1536 byte) network buffers
- for receiving. When a packet arrives, the driver has to decide
- whether to leave the packet in its full-sized buffer, or to allocate
- a smaller buffer and copy the packet across into it.
-
- This is a speed/space tradeoff.
-
- The value of rx_copybreak is used to decide when to make the copy.
- If the packet size is less than rx_copybreak, the packet is copied.
- The default value for rx_copybreak is 200 bytes.
-
-max_interrupt_work=N
-
- The driver's interrupt service routine can handle many receive and
- transmit packets in a single invocation. It does this in a loop.
- The value of max_interrupt_work governs how many times the interrupt
- service routine will loop. The default value is 32 loops. If this
- is exceeded the interrupt service routine gives up and generates a
- warning message "eth0: Too much work in interrupt".
-
-hw_checksums=N1,N2,N3,...
-
- Recent 3com NICs are able to generate IPv4, TCP and UDP checksums
- in hardware. Linux has used the Rx checksumming for a long time.
- The "zero copy" patch which is planned for the 2.4 kernel series
- allows you to make use of the NIC's DMA scatter/gather and transmit
- checksumming as well.
-
- The driver is set up so that, when the zerocopy patch is applied,
- all Tornado and Cyclone devices will use S/G and Tx checksums.
-
- This module parameter has been provided so you can override this
- decision. If you think that Tx checksums are causing a problem, you
- may disable the feature with ``hw_checksums=0``.
-
- If you think your NIC should be performing Tx checksumming and the
- driver isn't enabling it, you can force the use of hardware Tx
- checksumming with ``hw_checksums=1``.
-
- The driver drops a message in the logfiles to indicate whether or
- not it is using hardware scatter/gather and hardware Tx checksums.
-
- Scatter/gather and hardware checksums provide considerable
- performance improvement for the sendfile() system call, but a small
- decrease in throughput for send(). There is no effect upon receive
- efficiency.
-
-compaq_ioaddr=N,
-compaq_irq=N,
-compaq_device_id=N
-
- "Variables to work-around the Compaq PCI BIOS32 problem"....
-
-watchdog=N
-
- Sets the time duration (in milliseconds) after which the kernel
- decides that the transmitter has become stuck and needs to be reset.
- This is mainly for debugging purposes, although it may be advantageous
- to increase this value on LANs which have very high collision rates.
- The default value is 5000 (5.0 seconds).
-
-enable_wol=N1,N2,N3,...
-
- Enable Wake-on-LAN support for the relevant interface. Donald
- Becker's ``ether-wake`` application may be used to wake suspended
- machines.
-
- Also enables the NIC's power management support.
-
-global_enable_wol=N
-
- Sets enable_wol mode for all 3c59x NICs in the machine. Entries in
- the ``enable_wol`` array above will override any setting of this.
-
-Media selection
----------------
-
-A number of the older NICs such as the 3c590 and 3c900 series have
-10base2 and AUI interfaces.
-
-Prior to January, 2001 this driver would autoeselect the 10base2 or AUI
-port if it didn't detect activity on the 10baseT port. It would then
-get stuck on the 10base2 port and a driver reload was necessary to
-switch back to 10baseT. This behaviour could not be prevented with a
-module option override.
-
-Later (current) versions of the driver _do_ support locking of the
-media type. So if you load the driver module with
-
- modprobe 3c59x options=0
-
-it will permanently select the 10baseT port. Automatic selection of
-other media types does not occur.
-
-
-Transmit error, Tx status register 82
--------------------------------------
-
-This is a common error which is almost always caused by another host on
-the same network being in full-duplex mode, while this host is in
-half-duplex mode. You need to find that other host and make it run in
-half-duplex mode or fix this host to run in full-duplex mode.
-
-As a last resort, you can force the 3c59x driver into full-duplex mode
-with
-
- options 3c59x full_duplex=1
-
-but this has to be viewed as a workaround for broken network gear and
-should only really be used for equipment which cannot autonegotiate.
-
-
-Additional resources
---------------------
-
-Details of the device driver implementation are at the top of the source file.
-
-Additional documentation is available at Don Becker's Linux Drivers site:
-
- http://www.scyld.com/vortex.html
-
-Donald Becker's driver development site:
-
- http://www.scyld.com/network.html
-
-Donald's vortex-diag program is useful for inspecting the NIC's state:
-
- http://www.scyld.com/ethercard_diag.html
-
-Donald's mii-diag program may be used for inspecting and manipulating
-the NIC's Media Independent Interface subsystem:
-
- http://www.scyld.com/ethercard_diag.html#mii-diag
-
-Donald's wake-on-LAN page:
-
- http://www.scyld.com/wakeonlan.html
-
-3Com's DOS-based application for setting up the NICs EEPROMs:
-
- ftp://ftp.3com.com/pub/nic/3c90x/3c90xx2.exe
-
-
-Autonegotiation notes
----------------------
-
- The driver uses a one-minute heartbeat for adapting to changes in
- the external LAN environment if link is up and 5 seconds if link is down.
- This means that when, for example, a machine is unplugged from a hubbed
- 10baseT LAN plugged into a switched 100baseT LAN, the throughput
- will be quite dreadful for up to sixty seconds. Be patient.
-
- Cisco interoperability note from Walter Wong <wcw+@CMU.EDU>:
-
- On a side note, adding HAS_NWAY seems to share a problem with the
- Cisco 6509 switch. Specifically, you need to change the spanning
- tree parameter for the port the machine is plugged into to 'portfast'
- mode. Otherwise, the negotiation fails. This has been an issue
- we've noticed for a while but haven't had the time to track down.
-
- Cisco switches (Jeff Busch <jbusch@deja.com>)
-
- My "standard config" for ports to which PC's/servers connect directly::
-
- interface FastEthernet0/N
- description machinename
- load-interval 30
- spanning-tree portfast
-
- If autonegotiation is a problem, you may need to specify "speed
- 100" and "duplex full" as well (or "speed 10" and "duplex half").
-
- WARNING: DO NOT hook up hubs/switches/bridges to these
- specially-configured ports! The switch will become very confused.
-
-
-Reporting and diagnosing problems
----------------------------------
-
-Maintainers find that accurate and complete problem reports are
-invaluable in resolving driver problems. We are frequently not able to
-reproduce problems and must rely on your patience and efforts to get to
-the bottom of the problem.
-
-If you believe you have a driver problem here are some of the
-steps you should take:
-
-- Is it really a driver problem?
-
- Eliminate some variables: try different cards, different
- computers, different cables, different ports on the switch/hub,
- different versions of the kernel or of the driver, etc.
-
-- OK, it's a driver problem.
-
- You need to generate a report. Typically this is an email to the
- maintainer and/or netdev@vger.kernel.org. The maintainer's
- email address will be in the driver source or in the MAINTAINERS file.
-
-- The contents of your report will vary a lot depending upon the
- problem. If it's a kernel crash then you should refer to the
- admin-guide/reporting-bugs.rst file.
-
- But for most problems it is useful to provide the following:
-
- - Kernel version, driver version
-
- - A copy of the banner message which the driver generates when
- it is initialised. For example:
-
- eth0: 3Com PCI 3c905C Tornado at 0xa400, 00:50:da:6a:88:f0, IRQ 19
- 8K byte-wide RAM 5:3 Rx:Tx split, autoselect/Autonegotiate interface.
- MII transceiver found at address 24, status 782d.
- Enabling bus-master transmits and whole-frame receives.
-
- NOTE: You must provide the ``debug=2`` modprobe option to generate
- a full detection message. Please do this::
-
- modprobe 3c59x debug=2
-
- - If it is a PCI device, the relevant output from 'lspci -vx', eg::
-
- 00:09.0 Ethernet controller: 3Com Corporation 3c905C-TX [Fast Etherlink] (rev 74)
- Subsystem: 3Com Corporation: Unknown device 9200
- Flags: bus master, medium devsel, latency 32, IRQ 19
- I/O ports at a400 [size=128]
- Memory at db000000 (32-bit, non-prefetchable) [size=128]
- Expansion ROM at <unassigned> [disabled] [size=128K]
- Capabilities: [dc] Power Management version 2
- 00: b7 10 00 92 07 00 10 02 74 00 00 02 08 20 00 00
- 10: 01 a4 00 00 00 00 00 db 00 00 00 00 00 00 00 00
- 20: 00 00 00 00 00 00 00 00 00 00 00 00 b7 10 00 10
- 30: 00 00 00 00 dc 00 00 00 00 00 00 00 05 01 0a 0a
-
- - A description of the environment: 10baseT? 100baseT?
- full/half duplex? switched or hubbed?
-
- - Any additional module parameters which you may be providing to the driver.
-
- - Any kernel logs which are produced. The more the merrier.
- If this is a large file and you are sending your report to a
- mailing list, mention that you have the logfile, but don't send
- it. If you're reporting direct to the maintainer then just send
- it.
-
- To ensure that all kernel logs are available, add the
- following line to /etc/syslog.conf::
-
- kern.* /var/log/messages
-
- Then restart syslogd with::
-
- /etc/rc.d/init.d/syslog restart
-
- (The above may vary, depending upon which Linux distribution you use).
-
- - If your problem is reproducible then that's great. Try the
- following:
-
- 1) Increase the debug level. Usually this is done via:
-
- a) modprobe driver debug=7
- b) In /etc/modprobe.d/driver.conf:
- options driver debug=7
-
- 2) Recreate the problem with the higher debug level,
- send all logs to the maintainer.
-
- 3) Download you card's diagnostic tool from Donald
- Becker's website <http://www.scyld.com/ethercard_diag.html>.
- Download mii-diag.c as well. Build these.
-
- a) Run 'vortex-diag -aaee' and 'mii-diag -v' when the card is
- working correctly. Save the output.
-
- b) Run the above commands when the card is malfunctioning. Send
- both sets of output.
-
-Finally, please be patient and be prepared to do some work. You may
-end up working on this problem for a week or more as the maintainer
-asks more questions, asks for more tests, asks for patches to be
-applied, etc. At the end of it all, the problem may even remain
-unresolved.
diff --git a/Documentation/networking/cops.rst b/Documentation/networking/device_drivers/appletalk/cops.rst
similarity index 100%
rename from Documentation/networking/cops.rst
rename to Documentation/networking/device_drivers/appletalk/cops.rst
diff --git a/Documentation/networking/device_drivers/appletalk/index.rst b/Documentation/networking/device_drivers/appletalk/index.rst
new file mode 100644
index 0000000..de7507f
--- /dev/null
+++ b/Documentation/networking/device_drivers/appletalk/index.rst
@@ -0,0 +1,19 @@
+.. SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+
+AppleTalk Device Drivers
+========================
+
+Contents:
+
+.. toctree::
+ :maxdepth: 2
+
+ cops
+ ltpc
+
+.. only:: subproject and html
+
+ Indices
+ =======
+
+ * :ref:`genindex`
diff --git a/Documentation/networking/ltpc.rst b/Documentation/networking/device_drivers/appletalk/ltpc.rst
similarity index 100%
rename from Documentation/networking/ltpc.rst
rename to Documentation/networking/device_drivers/appletalk/ltpc.rst
diff --git a/Documentation/networking/cxacru-cf.py b/Documentation/networking/device_drivers/atm/cxacru-cf.py
similarity index 100%
rename from Documentation/networking/cxacru-cf.py
rename to Documentation/networking/device_drivers/atm/cxacru-cf.py
diff --git a/Documentation/networking/cxacru.rst b/Documentation/networking/device_drivers/atm/cxacru.rst
similarity index 100%
rename from Documentation/networking/cxacru.rst
rename to Documentation/networking/device_drivers/atm/cxacru.rst
diff --git a/Documentation/networking/fore200e.rst b/Documentation/networking/device_drivers/atm/fore200e.rst
similarity index 100%
rename from Documentation/networking/fore200e.rst
rename to Documentation/networking/device_drivers/atm/fore200e.rst
diff --git a/Documentation/networking/device_drivers/atm/index.rst b/Documentation/networking/device_drivers/atm/index.rst
new file mode 100644
index 0000000..7b593f0
--- /dev/null
+++ b/Documentation/networking/device_drivers/atm/index.rst
@@ -0,0 +1,20 @@
+.. SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+
+Asynchronous Transfer Mode (ATM) Device Drivers
+===============================================
+
+Contents:
+
+.. toctree::
+ :maxdepth: 2
+
+ cxacru
+ fore200e
+ iphase
+
+.. only:: subproject and html
+
+ Indices
+ =======
+
+ * :ref:`genindex`
diff --git a/Documentation/networking/iphase.rst b/Documentation/networking/device_drivers/atm/iphase.rst
similarity index 100%
rename from Documentation/networking/iphase.rst
rename to Documentation/networking/device_drivers/atm/iphase.rst
diff --git a/Documentation/networking/device_drivers/cable/index.rst b/Documentation/networking/device_drivers/cable/index.rst
new file mode 100644
index 0000000..cce3c43
--- /dev/null
+++ b/Documentation/networking/device_drivers/cable/index.rst
@@ -0,0 +1,18 @@
+.. SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+
+Cable Modem Device Drivers
+==========================
+
+Contents:
+
+.. toctree::
+ :maxdepth: 2
+
+ sb1000
+
+.. only:: subproject and html
+
+ Indices
+ =======
+
+ * :ref:`genindex`
diff --git a/Documentation/networking/device_drivers/sb1000.rst b/Documentation/networking/device_drivers/cable/sb1000.rst
similarity index 100%
rename from Documentation/networking/device_drivers/sb1000.rst
rename to Documentation/networking/device_drivers/cable/sb1000.rst
diff --git a/Documentation/networking/device_drivers/cellular/index.rst b/Documentation/networking/device_drivers/cellular/index.rst
new file mode 100644
index 0000000..fc1812d
--- /dev/null
+++ b/Documentation/networking/device_drivers/cellular/index.rst
@@ -0,0 +1,18 @@
+.. SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+
+Cellular Modem Device Drivers
+=============================
+
+Contents:
+
+.. toctree::
+ :maxdepth: 2
+
+ qualcomm/rmnet
+
+.. only:: subproject and html
+
+ Indices
+ =======
+
+ * :ref:`genindex`
diff --git a/Documentation/networking/device_drivers/qualcomm/rmnet.rst b/Documentation/networking/device_drivers/cellular/qualcomm/rmnet.rst
similarity index 100%
rename from Documentation/networking/device_drivers/qualcomm/rmnet.rst
rename to Documentation/networking/device_drivers/cellular/qualcomm/rmnet.rst
diff --git a/Documentation/networking/device_drivers/3com/3c509.rst b/Documentation/networking/device_drivers/ethernet/3com/3c509.rst
similarity index 100%
rename from Documentation/networking/device_drivers/3com/3c509.rst
rename to Documentation/networking/device_drivers/ethernet/3com/3c509.rst
diff --git a/Documentation/networking/device_drivers/ethernet/3com/vortex.rst b/Documentation/networking/device_drivers/ethernet/3com/vortex.rst
new file mode 100644
index 0000000..eab10fc
--- /dev/null
+++ b/Documentation/networking/device_drivers/ethernet/3com/vortex.rst
@@ -0,0 +1,459 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+=========================
+3Com Vortex device driver
+=========================
+
+Andrew Morton
+
+30 April 2000
+
+
+This document describes the usage and errata of the 3Com "Vortex" device
+driver for Linux, 3c59x.c.
+
+The driver was written by Donald Becker <becker@scyld.com>
+
+Don is no longer the prime maintainer of this version of the driver.
+Please report problems to one or more of:
+
+- Andrew Morton
+- Netdev mailing list <netdev@vger.kernel.org>
+- Linux kernel mailing list <linux-kernel@vger.kernel.org>
+
+Please note the 'Reporting and Diagnosing Problems' section at the end
+of this file.
+
+
+Since kernel 2.3.99-pre6, this driver incorporates the support for the
+3c575-series Cardbus cards which used to be handled by 3c575_cb.c.
+
+This driver supports the following hardware:
+
+ - 3c590 Vortex 10Mbps
+ - 3c592 EISA 10Mbps Demon/Vortex
+ - 3c597 EISA Fast Demon/Vortex
+ - 3c595 Vortex 100baseTx
+ - 3c595 Vortex 100baseT4
+ - 3c595 Vortex 100base-MII
+ - 3c900 Boomerang 10baseT
+ - 3c900 Boomerang 10Mbps Combo
+ - 3c900 Cyclone 10Mbps TPO
+ - 3c900 Cyclone 10Mbps Combo
+ - 3c900 Cyclone 10Mbps TPC
+ - 3c900B-FL Cyclone 10base-FL
+ - 3c905 Boomerang 100baseTx
+ - 3c905 Boomerang 100baseT4
+ - 3c905B Cyclone 100baseTx
+ - 3c905B Cyclone 10/100/BNC
+ - 3c905B-FX Cyclone 100baseFx
+ - 3c905C Tornado
+ - 3c920B-EMB-WNM (ATI Radeon 9100 IGP)
+ - 3c980 Cyclone
+ - 3c980C Python-T
+ - 3cSOHO100-TX Hurricane
+ - 3c555 Laptop Hurricane
+ - 3c556 Laptop Tornado
+ - 3c556B Laptop Hurricane
+ - 3c575 [Megahertz] 10/100 LAN CardBus
+ - 3c575 Boomerang CardBus
+ - 3CCFE575BT Cyclone CardBus
+ - 3CCFE575CT Tornado CardBus
+ - 3CCFE656 Cyclone CardBus
+ - 3CCFEM656B Cyclone+Winmodem CardBus
+ - 3CXFEM656C Tornado+Winmodem CardBus
+ - 3c450 HomePNA Tornado
+ - 3c920 Tornado
+ - 3c982 Hydra Dual Port A
+ - 3c982 Hydra Dual Port B
+ - 3c905B-T4
+ - 3c920B-EMB-WNM Tornado
+
+Module parameters
+=================
+
+There are several parameters which may be provided to the driver when
+its module is loaded. These are usually placed in ``/etc/modprobe.d/*.conf``
+configuration files. Example::
+
+ options 3c59x debug=3 rx_copybreak=300
+
+If you are using the PCMCIA tools (cardmgr) then the options may be
+placed in /etc/pcmcia/config.opts::
+
+ module "3c59x" opts "debug=3 rx_copybreak=300"
+
+
+The supported parameters are:
+
+debug=N
+
+ Where N is a number from 0 to 7. Anything above 3 produces a lot
+ of output in your system logs. debug=1 is default.
+
+options=N1,N2,N3,...
+
+ Each number in the list provides an option to the corresponding
+ network card. So if you have two 3c905's and you wish to provide
+ them with option 0x204 you would use::
+
+ options=0x204,0x204
+
+ The individual options are composed of a number of bitfields which
+ have the following meanings:
+
+ Possible media type settings
+
+ == =================================
+ 0 10baseT
+ 1 10Mbs AUI
+ 2 undefined
+ 3 10base2 (BNC)
+ 4 100base-TX
+ 5 100base-FX
+ 6 MII (Media Independent Interface)
+ 7 Use default setting from EEPROM
+ 8 Autonegotiate
+ 9 External MII
+ 10 Use default setting from EEPROM
+ == =================================
+
+ When generating a value for the 'options' setting, the above media
+ selection values may be OR'ed (or added to) the following:
+
+ ====== =============================================
+ 0x8000 Set driver debugging level to 7
+ 0x4000 Set driver debugging level to 2
+ 0x0400 Enable Wake-on-LAN
+ 0x0200 Force full duplex mode.
+ 0x0010 Bus-master enable bit (Old Vortex cards only)
+ ====== =============================================
+
+ For example::
+
+ insmod 3c59x options=0x204
+
+ will force full-duplex 100base-TX, rather than allowing the usual
+ autonegotiation.
+
+global_options=N
+
+ Sets the ``options`` parameter for all 3c59x NICs in the machine.
+ Entries in the ``options`` array above will override any setting of
+ this.
+
+full_duplex=N1,N2,N3...
+
+ Similar to bit 9 of 'options'. Forces the corresponding card into
+ full-duplex mode. Please use this in preference to the ``options``
+ parameter.
+
+ In fact, please don't use this at all! You're better off getting
+ autonegotiation working properly.
+
+global_full_duplex=N1
+
+ Sets full duplex mode for all 3c59x NICs in the machine. Entries
+ in the ``full_duplex`` array above will override any setting of this.
+
+flow_ctrl=N1,N2,N3...
+
+ Use 802.3x MAC-layer flow control. The 3com cards only support the
+ PAUSE command, which means that they will stop sending packets for a
+ short period if they receive a PAUSE frame from the link partner.
+
+ The driver only allows flow control on a link which is operating in
+ full duplex mode.
+
+ This feature does not appear to work on the 3c905 - only 3c905B and
+ 3c905C have been tested.
+
+ The 3com cards appear to only respond to PAUSE frames which are
+ sent to the reserved destination address of 01:80:c2:00:00:01. They
+ do not honour PAUSE frames which are sent to the station MAC address.
+
+rx_copybreak=M
+
+ The driver preallocates 32 full-sized (1536 byte) network buffers
+ for receiving. When a packet arrives, the driver has to decide
+ whether to leave the packet in its full-sized buffer, or to allocate
+ a smaller buffer and copy the packet across into it.
+
+ This is a speed/space tradeoff.
+
+ The value of rx_copybreak is used to decide when to make the copy.
+ If the packet size is less than rx_copybreak, the packet is copied.
+ The default value for rx_copybreak is 200 bytes.
+
+max_interrupt_work=N
+
+ The driver's interrupt service routine can handle many receive and
+ transmit packets in a single invocation. It does this in a loop.
+ The value of max_interrupt_work governs how many times the interrupt
+ service routine will loop. The default value is 32 loops. If this
+ is exceeded the interrupt service routine gives up and generates a
+ warning message "eth0: Too much work in interrupt".
+
+hw_checksums=N1,N2,N3,...
+
+ Recent 3com NICs are able to generate IPv4, TCP and UDP checksums
+ in hardware. Linux has used the Rx checksumming for a long time.
+ The "zero copy" patch which is planned for the 2.4 kernel series
+ allows you to make use of the NIC's DMA scatter/gather and transmit
+ checksumming as well.
+
+ The driver is set up so that, when the zerocopy patch is applied,
+ all Tornado and Cyclone devices will use S/G and Tx checksums.
+
+ This module parameter has been provided so you can override this
+ decision. If you think that Tx checksums are causing a problem, you
+ may disable the feature with ``hw_checksums=0``.
+
+ If you think your NIC should be performing Tx checksumming and the
+ driver isn't enabling it, you can force the use of hardware Tx
+ checksumming with ``hw_checksums=1``.
+
+ The driver drops a message in the logfiles to indicate whether or
+ not it is using hardware scatter/gather and hardware Tx checksums.
+
+ Scatter/gather and hardware checksums provide considerable
+ performance improvement for the sendfile() system call, but a small
+ decrease in throughput for send(). There is no effect upon receive
+ efficiency.
+
+compaq_ioaddr=N,
+compaq_irq=N,
+compaq_device_id=N
+
+ "Variables to work-around the Compaq PCI BIOS32 problem"....
+
+watchdog=N
+
+ Sets the time duration (in milliseconds) after which the kernel
+ decides that the transmitter has become stuck and needs to be reset.
+ This is mainly for debugging purposes, although it may be advantageous
+ to increase this value on LANs which have very high collision rates.
+ The default value is 5000 (5.0 seconds).
+
+enable_wol=N1,N2,N3,...
+
+ Enable Wake-on-LAN support for the relevant interface. Donald
+ Becker's ``ether-wake`` application may be used to wake suspended
+ machines.
+
+ Also enables the NIC's power management support.
+
+global_enable_wol=N
+
+ Sets enable_wol mode for all 3c59x NICs in the machine. Entries in
+ the ``enable_wol`` array above will override any setting of this.
+
+Media selection
+---------------
+
+A number of the older NICs such as the 3c590 and 3c900 series have
+10base2 and AUI interfaces.
+
+Prior to January, 2001 this driver would autoeselect the 10base2 or AUI
+port if it didn't detect activity on the 10baseT port. It would then
+get stuck on the 10base2 port and a driver reload was necessary to
+switch back to 10baseT. This behaviour could not be prevented with a
+module option override.
+
+Later (current) versions of the driver _do_ support locking of the
+media type. So if you load the driver module with
+
+ modprobe 3c59x options=0
+
+it will permanently select the 10baseT port. Automatic selection of
+other media types does not occur.
+
+
+Transmit error, Tx status register 82
+-------------------------------------
+
+This is a common error which is almost always caused by another host on
+the same network being in full-duplex mode, while this host is in
+half-duplex mode. You need to find that other host and make it run in
+half-duplex mode or fix this host to run in full-duplex mode.
+
+As a last resort, you can force the 3c59x driver into full-duplex mode
+with
+
+ options 3c59x full_duplex=1
+
+but this has to be viewed as a workaround for broken network gear and
+should only really be used for equipment which cannot autonegotiate.
+
+
+Additional resources
+--------------------
+
+Details of the device driver implementation are at the top of the source file.
+
+Additional documentation is available at Don Becker's Linux Drivers site:
+
+ http://www.scyld.com/vortex.html
+
+Donald Becker's driver development site:
+
+ http://www.scyld.com/network.html
+
+Donald's vortex-diag program is useful for inspecting the NIC's state:
+
+ http://www.scyld.com/ethercard_diag.html
+
+Donald's mii-diag program may be used for inspecting and manipulating
+the NIC's Media Independent Interface subsystem:
+
+ http://www.scyld.com/ethercard_diag.html#mii-diag
+
+Donald's wake-on-LAN page:
+
+ http://www.scyld.com/wakeonlan.html
+
+3Com's DOS-based application for setting up the NICs EEPROMs:
+
+ ftp://ftp.3com.com/pub/nic/3c90x/3c90xx2.exe
+
+
+Autonegotiation notes
+---------------------
+
+ The driver uses a one-minute heartbeat for adapting to changes in
+ the external LAN environment if link is up and 5 seconds if link is down.
+ This means that when, for example, a machine is unplugged from a hubbed
+ 10baseT LAN plugged into a switched 100baseT LAN, the throughput
+ will be quite dreadful for up to sixty seconds. Be patient.
+
+ Cisco interoperability note from Walter Wong <wcw+@CMU.EDU>:
+
+ On a side note, adding HAS_NWAY seems to share a problem with the
+ Cisco 6509 switch. Specifically, you need to change the spanning
+ tree parameter for the port the machine is plugged into to 'portfast'
+ mode. Otherwise, the negotiation fails. This has been an issue
+ we've noticed for a while but haven't had the time to track down.
+
+ Cisco switches (Jeff Busch <jbusch@deja.com>)
+
+ My "standard config" for ports to which PC's/servers connect directly::
+
+ interface FastEthernet0/N
+ description machinename
+ load-interval 30
+ spanning-tree portfast
+
+ If autonegotiation is a problem, you may need to specify "speed
+ 100" and "duplex full" as well (or "speed 10" and "duplex half").
+
+ WARNING: DO NOT hook up hubs/switches/bridges to these
+ specially-configured ports! The switch will become very confused.
+
+
+Reporting and diagnosing problems
+---------------------------------
+
+Maintainers find that accurate and complete problem reports are
+invaluable in resolving driver problems. We are frequently not able to
+reproduce problems and must rely on your patience and efforts to get to
+the bottom of the problem.
+
+If you believe you have a driver problem here are some of the
+steps you should take:
+
+- Is it really a driver problem?
+
+ Eliminate some variables: try different cards, different
+ computers, different cables, different ports on the switch/hub,
+ different versions of the kernel or of the driver, etc.
+
+- OK, it's a driver problem.
+
+ You need to generate a report. Typically this is an email to the
+ maintainer and/or netdev@vger.kernel.org. The maintainer's
+ email address will be in the driver source or in the MAINTAINERS file.
+
+- The contents of your report will vary a lot depending upon the
+ problem. If it's a kernel crash then you should refer to the
+ admin-guide/reporting-bugs.rst file.
+
+ But for most problems it is useful to provide the following:
+
+ - Kernel version, driver version
+
+ - A copy of the banner message which the driver generates when
+ it is initialised. For example:
+
+ eth0: 3Com PCI 3c905C Tornado at 0xa400, 00:50:da:6a:88:f0, IRQ 19
+ 8K byte-wide RAM 5:3 Rx:Tx split, autoselect/Autonegotiate interface.
+ MII transceiver found at address 24, status 782d.
+ Enabling bus-master transmits and whole-frame receives.
+
+ NOTE: You must provide the ``debug=2`` modprobe option to generate
+ a full detection message. Please do this::
+
+ modprobe 3c59x debug=2
+
+ - If it is a PCI device, the relevant output from 'lspci -vx', eg::
+
+ 00:09.0 Ethernet controller: 3Com Corporation 3c905C-TX [Fast Etherlink] (rev 74)
+ Subsystem: 3Com Corporation: Unknown device 9200
+ Flags: bus master, medium devsel, latency 32, IRQ 19
+ I/O ports at a400 [size=128]
+ Memory at db000000 (32-bit, non-prefetchable) [size=128]
+ Expansion ROM at <unassigned> [disabled] [size=128K]
+ Capabilities: [dc] Power Management version 2
+ 00: b7 10 00 92 07 00 10 02 74 00 00 02 08 20 00 00
+ 10: 01 a4 00 00 00 00 00 db 00 00 00 00 00 00 00 00
+ 20: 00 00 00 00 00 00 00 00 00 00 00 00 b7 10 00 10
+ 30: 00 00 00 00 dc 00 00 00 00 00 00 00 05 01 0a 0a
+
+ - A description of the environment: 10baseT? 100baseT?
+ full/half duplex? switched or hubbed?
+
+ - Any additional module parameters which you may be providing to the driver.
+
+ - Any kernel logs which are produced. The more the merrier.
+ If this is a large file and you are sending your report to a
+ mailing list, mention that you have the logfile, but don't send
+ it. If you're reporting direct to the maintainer then just send
+ it.
+
+ To ensure that all kernel logs are available, add the
+ following line to /etc/syslog.conf::
+
+ kern.* /var/log/messages
+
+ Then restart syslogd with::
+
+ /etc/rc.d/init.d/syslog restart
+
+ (The above may vary, depending upon which Linux distribution you use).
+
+ - If your problem is reproducible then that's great. Try the
+ following:
+
+ 1) Increase the debug level. Usually this is done via:
+
+ a) modprobe driver debug=7
+ b) In /etc/modprobe.d/driver.conf:
+ options driver debug=7
+
+ 2) Recreate the problem with the higher debug level,
+ send all logs to the maintainer.
+
+ 3) Download you card's diagnostic tool from Donald
+ Becker's website <http://www.scyld.com/ethercard_diag.html>.
+ Download mii-diag.c as well. Build these.
+
+ a) Run 'vortex-diag -aaee' and 'mii-diag -v' when the card is
+ working correctly. Save the output.
+
+ b) Run the above commands when the card is malfunctioning. Send
+ both sets of output.
+
+Finally, please be patient and be prepared to do some work. You may
+end up working on this problem for a week or more as the maintainer
+asks more questions, asks for more tests, asks for patches to be
+applied, etc. At the end of it all, the problem may even remain
+unresolved.
diff --git a/Documentation/networking/altera_tse.rst b/Documentation/networking/device_drivers/ethernet/altera/altera_tse.rst
similarity index 100%
rename from Documentation/networking/altera_tse.rst
rename to Documentation/networking/device_drivers/ethernet/altera/altera_tse.rst
diff --git a/Documentation/networking/device_drivers/amazon/ena.rst b/Documentation/networking/device_drivers/ethernet/amazon/ena.rst
similarity index 100%
rename from Documentation/networking/device_drivers/amazon/ena.rst
rename to Documentation/networking/device_drivers/ethernet/amazon/ena.rst
diff --git a/Documentation/networking/device_drivers/aquantia/atlantic.rst b/Documentation/networking/device_drivers/ethernet/aquantia/atlantic.rst
similarity index 100%
rename from Documentation/networking/device_drivers/aquantia/atlantic.rst
rename to Documentation/networking/device_drivers/ethernet/aquantia/atlantic.rst
diff --git a/Documentation/networking/device_drivers/chelsio/cxgb.rst b/Documentation/networking/device_drivers/ethernet/chelsio/cxgb.rst
similarity index 100%
rename from Documentation/networking/device_drivers/chelsio/cxgb.rst
rename to Documentation/networking/device_drivers/ethernet/chelsio/cxgb.rst
diff --git a/Documentation/networking/device_drivers/cirrus/cs89x0.rst b/Documentation/networking/device_drivers/ethernet/cirrus/cs89x0.rst
similarity index 100%
rename from Documentation/networking/device_drivers/cirrus/cs89x0.rst
rename to Documentation/networking/device_drivers/ethernet/cirrus/cs89x0.rst
diff --git a/Documentation/networking/device_drivers/davicom/dm9000.rst b/Documentation/networking/device_drivers/ethernet/davicom/dm9000.rst
similarity index 100%
rename from Documentation/networking/device_drivers/davicom/dm9000.rst
rename to Documentation/networking/device_drivers/ethernet/davicom/dm9000.rst
diff --git a/Documentation/networking/device_drivers/dec/de4x5.rst b/Documentation/networking/device_drivers/ethernet/dec/de4x5.rst
similarity index 100%
rename from Documentation/networking/device_drivers/dec/de4x5.rst
rename to Documentation/networking/device_drivers/ethernet/dec/de4x5.rst
diff --git a/Documentation/networking/device_drivers/dec/dmfe.rst b/Documentation/networking/device_drivers/ethernet/dec/dmfe.rst
similarity index 100%
rename from Documentation/networking/device_drivers/dec/dmfe.rst
rename to Documentation/networking/device_drivers/ethernet/dec/dmfe.rst
diff --git a/Documentation/networking/device_drivers/dlink/dl2k.rst b/Documentation/networking/device_drivers/ethernet/dlink/dl2k.rst
similarity index 100%
rename from Documentation/networking/device_drivers/dlink/dl2k.rst
rename to Documentation/networking/device_drivers/ethernet/dlink/dl2k.rst
diff --git a/Documentation/networking/device_drivers/freescale/dpaa.rst b/Documentation/networking/device_drivers/ethernet/freescale/dpaa.rst
similarity index 100%
rename from Documentation/networking/device_drivers/freescale/dpaa.rst
rename to Documentation/networking/device_drivers/ethernet/freescale/dpaa.rst
diff --git a/Documentation/networking/device_drivers/ethernet/freescale/dpaa2/dpio-driver.rst b/Documentation/networking/device_drivers/ethernet/freescale/dpaa2/dpio-driver.rst
new file mode 100644
index 0000000..c50fd46
--- /dev/null
+++ b/Documentation/networking/device_drivers/ethernet/freescale/dpaa2/dpio-driver.rst
@@ -0,0 +1,160 @@
+.. include:: <isonum.txt>
+
+DPAA2 DPIO (Data Path I/O) Overview
+===================================
+
+:Copyright: |copy| 2016-2018 NXP
+
+This document provides an overview of the Freescale DPAA2 DPIO
+drivers
+
+Introduction
+============
+
+A DPAA2 DPIO (Data Path I/O) is a hardware object that provides
+interfaces to enqueue and dequeue frames to/from network interfaces
+and other accelerators. A DPIO also provides hardware buffer
+pool management for network interfaces.
+
+This document provides an overview the Linux DPIO driver, its
+subcomponents, and its APIs.
+
+See
+Documentation/networking/device_drivers/ethernet/freescale/dpaa2/overview.rst
+for a general overview of DPAA2 and the general DPAA2 driver architecture
+in Linux.
+
+Driver Overview
+---------------
+
+The DPIO driver is bound to DPIO objects discovered on the fsl-mc bus and
+provides services that:
+
+ A. allow other drivers, such as the Ethernet driver, to enqueue and dequeue
+ frames for their respective objects
+ B. allow drivers to register callbacks for data availability notifications
+ when data becomes available on a queue or channel
+ C. allow drivers to manage hardware buffer pools
+
+The Linux DPIO driver consists of 3 primary components--
+ DPIO object driver-- fsl-mc driver that manages the DPIO object
+
+ DPIO service-- provides APIs to other Linux drivers for services
+
+ QBman portal interface-- sends portal commands, gets responses::
+
+ fsl-mc other
+ bus drivers
+ | |
+ +---+----+ +------+-----+
+ |DPIO obj| |DPIO service|
+ | driver |---| (DPIO) |
+ +--------+ +------+-----+
+ |
+ +------+-----+
+ | QBman |
+ | portal i/f |
+ +------------+
+ |
+ hardware
+
+
+The diagram below shows how the DPIO driver components fit with the other
+DPAA2 Linux driver components::
+
+ +------------+
+ | OS Network |
+ | Stack |
+ +------------+ +------------+
+ | Allocator |. . . . . . . | Ethernet |
+ |(DPMCP,DPBP)| | (DPNI) |
+ +-.----------+ +---+---+----+
+ . . ^ |
+ . . <data avail, | |<enqueue,
+ . . tx confirm> | | dequeue>
+ +-------------+ . | |
+ | DPRC driver | . +--------+ +------------+
+ | (DPRC) | . . |DPIO obj| |DPIO service|
+ +----------+--+ | driver |-| (DPIO) |
+ | +--------+ +------+-----+
+ |<dev add/remove> +------|-----+
+ | | QBman |
+ +----+--------------+ | portal i/f |
+ | MC-bus driver | +------------+
+ | | |
+ | /soc/fsl-mc | |
+ +-------------------+ |
+ |
+ =========================================|=========|========================
+ +-+--DPIO---|-----------+
+ | | |
+ | QBman Portal |
+ +-----------------------+
+
+ ============================================================================
+
+
+DPIO Object Driver (dpio-driver.c)
+----------------------------------
+
+ The dpio-driver component registers with the fsl-mc bus to handle objects of
+ type "dpio". The implementation of probe() handles basic initialization
+ of the DPIO including mapping of the DPIO regions (the QBman SW portal)
+ and initializing interrupts and registering irq handlers. The dpio-driver
+ registers the probed DPIO with dpio-service.
+
+DPIO service (dpio-service.c, dpaa2-io.h)
+------------------------------------------
+
+ The dpio service component provides queuing, notification, and buffers
+ management services to DPAA2 drivers, such as the Ethernet driver. A system
+ will typically allocate 1 DPIO object per CPU to allow queuing operations
+ to happen simultaneously across all CPUs.
+
+ Notification handling
+ dpaa2_io_service_register()
+
+ dpaa2_io_service_deregister()
+
+ dpaa2_io_service_rearm()
+
+ Queuing
+ dpaa2_io_service_pull_fq()
+
+ dpaa2_io_service_pull_channel()
+
+ dpaa2_io_service_enqueue_fq()
+
+ dpaa2_io_service_enqueue_qd()
+
+ dpaa2_io_store_create()
+
+ dpaa2_io_store_destroy()
+
+ dpaa2_io_store_next()
+
+ Buffer pool management
+ dpaa2_io_service_release()
+
+ dpaa2_io_service_acquire()
+
+QBman portal interface (qbman-portal.c)
+---------------------------------------
+
+ The qbman-portal component provides APIs to do the low level hardware
+ bit twiddling for operations such as:
+
+ - initializing Qman software portals
+ - building and sending portal commands
+ - portal interrupt configuration and processing
+
+ The qbman-portal APIs are not public to other drivers, and are
+ only used by dpio-service.
+
+Other (dpaa2-fd.h, dpaa2-global.h)
+----------------------------------
+
+ Frame descriptor and scatter-gather definitions and the APIs used to
+ manipulate them are defined in dpaa2-fd.h.
+
+ Dequeue result struct and parsing APIs are defined in dpaa2-global.h.
diff --git a/Documentation/networking/device_drivers/ethernet/freescale/dpaa2/ethernet-driver.rst b/Documentation/networking/device_drivers/ethernet/freescale/dpaa2/ethernet-driver.rst
new file mode 100644
index 0000000..682f398
--- /dev/null
+++ b/Documentation/networking/device_drivers/ethernet/freescale/dpaa2/ethernet-driver.rst
@@ -0,0 +1,186 @@
+.. SPDX-License-Identifier: GPL-2.0
+.. include:: <isonum.txt>
+
+===============================
+DPAA2 Ethernet driver
+===============================
+
+:Copyright: |copy| 2017-2018 NXP
+
+This file provides documentation for the Freescale DPAA2 Ethernet driver.
+
+Supported Platforms
+===================
+This driver provides networking support for Freescale DPAA2 SoCs, e.g.
+LS2080A, LS2088A, LS1088A.
+
+
+Architecture Overview
+=====================
+Unlike regular NICs, in the DPAA2 architecture there is no single hardware block
+representing network interfaces; instead, several separate hardware resources
+concur to provide the networking functionality:
+
+- network interfaces
+- queues, channels
+- buffer pools
+- MAC/PHY
+
+All hardware resources are allocated and configured through the Management
+Complex (MC) portals. MC abstracts most of these resources as DPAA2 objects
+and exposes ABIs through which they can be configured and controlled. A few
+hardware resources, like queues, do not have a corresponding MC object and
+are treated as internal resources of other objects.
+
+For a more detailed description of the DPAA2 architecture and its object
+abstractions see
+*Documentation/networking/device_drivers/ethernet/freescale/dpaa2/overview.rst*.
+
+Each Linux net device is built on top of a Datapath Network Interface (DPNI)
+object and uses Buffer Pools (DPBPs), I/O Portals (DPIOs) and Concentrators
+(DPCONs).
+
+Configuration interface::
+
+ -----------------------
+ | DPAA2 Ethernet Driver |
+ -----------------------
+ . . .
+ . . .
+ . . . . . . . . . . . .
+ . . .
+ . . .
+ ---------- ---------- -----------
+ | DPBP API | | DPNI API | | DPCON API |
+ ---------- ---------- -----------
+ . . . software
+ ======= . ========== . ============ . ===================
+ . . . hardware
+ ------------------------------------------
+ | MC hardware portals |
+ ------------------------------------------
+ . . .
+ . . .
+ ------ ------ -------
+ | DPBP | | DPNI | | DPCON |
+ ------ ------ -------
+
+The DPNIs are network interfaces without a direct one-on-one mapping to PHYs.
+DPBPs represent hardware buffer pools. Packet I/O is performed in the context
+of DPCON objects, using DPIO portals for managing and communicating with the
+hardware resources.
+
+Datapath (I/O) interface::
+
+ -----------------------------------------------
+ | DPAA2 Ethernet Driver |
+ -----------------------------------------------
+ | ^ ^ | |
+ | | | | |
+ enqueue| dequeue| data | dequeue| seed |
+ (Tx) | (Rx, TxC)| avail.| request| buffers|
+ | | notify| | |
+ | | | | |
+ V | | V V
+ -----------------------------------------------
+ | DPIO Driver |
+ -----------------------------------------------
+ | | | | | software
+ | | | | | ================
+ | | | | | hardware
+ -----------------------------------------------
+ | I/O hardware portals |
+ -----------------------------------------------
+ | ^ ^ | |
+ | | | | |
+ | | | V |
+ V | ================ V
+ ---------------------- | -------------
+ queues ---------------------- | | Buffer pool |
+ ---------------------- | -------------
+ =======================
+ Channel
+
+Datapath I/O (DPIO) portals provide enqueue and dequeue services, data
+availability notifications and buffer pool management. DPIOs are shared between
+all DPAA2 objects (and implicitly all DPAA2 kernel drivers) that work with data
+frames, but must be affine to the CPUs for the purpose of traffic distribution.
+
+Frames are transmitted and received through hardware frame queues, which can be
+grouped in channels for the purpose of hardware scheduling. The Ethernet driver
+enqueues TX frames on egress queues and after transmission is complete a TX
+confirmation frame is sent back to the CPU.
+
+When frames are available on ingress queues, a data availability notification
+is sent to the CPU; notifications are raised per channel, so even if multiple
+queues in the same channel have available frames, only one notification is sent.
+After a channel fires a notification, is must be explicitly rearmed.
+
+Each network interface can have multiple Rx, Tx and confirmation queues affined
+to CPUs, and one channel (DPCON) for each CPU that services at least one queue.
+DPCONs are used to distribute ingress traffic to different CPUs via the cores'
+affine DPIOs.
+
+The role of hardware buffer pools is storage of ingress frame data. Each network
+interface has a privately owned buffer pool which it seeds with kernel allocated
+buffers.
+
+
+DPNIs are decoupled from PHYs; a DPNI can be connected to a PHY through a DPMAC
+object or to another DPNI through an internal link, but the connection is
+managed by MC and completely transparent to the Ethernet driver.
+
+::
+
+ --------- --------- ---------
+ | eth if1 | | eth if2 | | eth ifn |
+ --------- --------- ---------
+ . . .
+ . . .
+ . . .
+ ---------------------------
+ | DPAA2 Ethernet Driver |
+ ---------------------------
+ . . .
+ . . .
+ . . .
+ ------ ------ ------ -------
+ | DPNI | | DPNI | | DPNI | | DPMAC |----+
+ ------ ------ ------ ------- |
+ | | | | |
+ | | | | -----
+ =========== ================== | PHY |
+ -----
+
+Creating a Network Interface
+============================
+A net device is created for each DPNI object probed on the MC bus. Each DPNI has
+a number of properties which determine the network interface configuration
+options and associated hardware resources.
+
+DPNI objects (and the other DPAA2 objects needed for a network interface) can be
+added to a container on the MC bus in one of two ways: statically, through a
+Datapath Layout Binary file (DPL) that is parsed by MC at boot time; or created
+dynamically at runtime, via the DPAA2 objects APIs.
+
+
+Features & Offloads
+===================
+Hardware checksum offloading is supported for TCP and UDP over IPv4/6 frames.
+The checksum offloads can be independently configured on RX and TX through
+ethtool.
+
+Hardware offload of unicast and multicast MAC filtering is supported on the
+ingress path and permanently enabled.
+
+Scatter-gather frames are supported on both RX and TX paths. On TX, SG support
+is configurable via ethtool; on RX it is always enabled.
+
+The DPAA2 hardware can process jumbo Ethernet frames of up to 10K bytes.
+
+The Ethernet driver defines a static flow hashing scheme that distributes
+traffic based on a 5-tuple key: src IP, dst IP, IP proto, L4 src port,
+L4 dst port. No user configuration is supported for now.
+
+Hardware specific statistics for the network interface as well as some
+non-standard driver stats can be consulted through ethtool -S option.
diff --git a/Documentation/networking/device_drivers/freescale/dpaa2/index.rst b/Documentation/networking/device_drivers/ethernet/freescale/dpaa2/index.rst
similarity index 100%
rename from Documentation/networking/device_drivers/freescale/dpaa2/index.rst
rename to Documentation/networking/device_drivers/ethernet/freescale/dpaa2/index.rst
diff --git a/Documentation/networking/device_drivers/freescale/dpaa2/mac-phy-support.rst b/Documentation/networking/device_drivers/ethernet/freescale/dpaa2/mac-phy-support.rst
similarity index 100%
rename from Documentation/networking/device_drivers/freescale/dpaa2/mac-phy-support.rst
rename to Documentation/networking/device_drivers/ethernet/freescale/dpaa2/mac-phy-support.rst
diff --git a/Documentation/networking/device_drivers/freescale/dpaa2/overview.rst b/Documentation/networking/device_drivers/ethernet/freescale/dpaa2/overview.rst
similarity index 100%
rename from Documentation/networking/device_drivers/freescale/dpaa2/overview.rst
rename to Documentation/networking/device_drivers/ethernet/freescale/dpaa2/overview.rst
diff --git a/Documentation/networking/device_drivers/freescale/gianfar.rst b/Documentation/networking/device_drivers/ethernet/freescale/gianfar.rst
similarity index 100%
rename from Documentation/networking/device_drivers/freescale/gianfar.rst
rename to Documentation/networking/device_drivers/ethernet/freescale/gianfar.rst
diff --git a/Documentation/networking/device_drivers/google/gve.rst b/Documentation/networking/device_drivers/ethernet/google/gve.rst
similarity index 100%
rename from Documentation/networking/device_drivers/google/gve.rst
rename to Documentation/networking/device_drivers/ethernet/google/gve.rst
diff --git a/Documentation/networking/hinic.rst b/Documentation/networking/device_drivers/ethernet/huawei/hinic.rst
similarity index 100%
rename from Documentation/networking/hinic.rst
rename to Documentation/networking/device_drivers/ethernet/huawei/hinic.rst
diff --git a/Documentation/networking/device_drivers/ethernet/index.rst b/Documentation/networking/device_drivers/ethernet/index.rst
new file mode 100644
index 0000000..cbb75a18
--- /dev/null
+++ b/Documentation/networking/device_drivers/ethernet/index.rst
@@ -0,0 +1,60 @@
+.. SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+
+Ethernet Device Drivers
+=======================
+
+Device drivers for Ethernet and Ethernet-based virtual function devices.
+
+Contents:
+
+.. toctree::
+ :maxdepth: 2
+
+ 3com/3c509
+ 3com/vortex
+ amazon/ena
+ altera/altera_tse
+ aquantia/atlantic
+ chelsio/cxgb
+ cirrus/cs89x0
+ dlink/dl2k
+ davicom/dm9000
+ dec/de4x5
+ dec/dmfe
+ freescale/dpaa
+ freescale/dpaa2/index
+ freescale/gianfar
+ google/gve
+ huawei/hinic
+ intel/e100
+ intel/e1000
+ intel/e1000e
+ intel/fm10k
+ intel/igb
+ intel/igbvf
+ intel/ixgb
+ intel/ixgbe
+ intel/ixgbevf
+ intel/i40e
+ intel/iavf
+ intel/ice
+ marvell/octeontx2
+ mellanox/mlx5
+ microsoft/netvsc
+ neterion/s2io
+ neterion/vxge
+ netronome/nfp
+ pensando/ionic
+ smsc/smc9
+ stmicro/stmmac
+ ti/cpsw
+ ti/cpsw_switchdev
+ ti/tlan
+ toshiba/spider_net
+
+.. only:: subproject and html
+
+ Indices
+ =======
+
+ * :ref:`genindex`
diff --git a/Documentation/networking/device_drivers/ethernet/intel/e100.rst b/Documentation/networking/device_drivers/ethernet/intel/e100.rst
new file mode 100644
index 0000000..3d4a9ba
--- /dev/null
+++ b/Documentation/networking/device_drivers/ethernet/intel/e100.rst
@@ -0,0 +1,188 @@
+.. SPDX-License-Identifier: GPL-2.0+
+
+=============================================================
+Linux Base Driver for the Intel(R) PRO/100 Family of Adapters
+=============================================================
+
+June 1, 2018
+
+Contents
+========
+
+- In This Release
+- Identifying Your Adapter
+- Building and Installation
+- Driver Configuration Parameters
+- Additional Configurations
+- Known Issues
+- Support
+
+
+In This Release
+===============
+
+This file describes the Linux Base Driver for the Intel(R) PRO/100 Family of
+Adapters. This driver includes support for Itanium(R)2-based systems.
+
+For questions related to hardware requirements, refer to the documentation
+supplied with your Intel PRO/100 adapter.
+
+The following features are now available in supported kernels:
+ - Native VLANs
+ - Channel Bonding (teaming)
+ - SNMP
+
+Channel Bonding documentation can be found in the Linux kernel source:
+/Documentation/networking/bonding.rst
+
+
+Identifying Your Adapter
+========================
+
+For information on how to identify your adapter, and for the latest Intel
+network drivers, refer to the Intel Support website:
+https://www.intel.com/support
+
+Driver Configuration Parameters
+===============================
+
+The default value for each parameter is generally the recommended setting,
+unless otherwise noted.
+
+Rx Descriptors:
+ Number of receive descriptors. A receive descriptor is a data
+ structure that describes a receive buffer and its attributes to the network
+ controller. The data in the descriptor is used by the controller to write
+ data from the controller to host memory. In the 3.x.x driver the valid range
+ for this parameter is 64-256. The default value is 256. This parameter can be
+ changed using the command::
+
+ ethtool -G eth? rx n
+
+ Where n is the number of desired Rx descriptors.
+
+Tx Descriptors:
+ Number of transmit descriptors. A transmit descriptor is a data
+ structure that describes a transmit buffer and its attributes to the network
+ controller. The data in the descriptor is used by the controller to read
+ data from the host memory to the controller. In the 3.x.x driver the valid
+ range for this parameter is 64-256. The default value is 128. This parameter
+ can be changed using the command::
+
+ ethtool -G eth? tx n
+
+ Where n is the number of desired Tx descriptors.
+
+Speed/Duplex:
+ The driver auto-negotiates the link speed and duplex settings by
+ default. The ethtool utility can be used as follows to force speed/duplex.::
+
+ ethtool -s eth? autoneg off speed {10|100} duplex {full|half}
+
+ NOTE: setting the speed/duplex to incorrect values will cause the link to
+ fail.
+
+Event Log Message Level:
+ The driver uses the message level flag to log events
+ to syslog. The message level can be set at driver load time. It can also be
+ set using the command::
+
+ ethtool -s eth? msglvl n
+
+
+Additional Configurations
+=========================
+
+Configuring the Driver on Different Distributions
+-------------------------------------------------
+
+Configuring a network driver to load properly when the system is started
+is distribution dependent. Typically, the configuration process involves
+adding an alias line to `/etc/modprobe.d/*.conf` as well as editing other
+system startup scripts and/or configuration files. Many popular Linux
+distributions ship with tools to make these changes for you. To learn
+the proper way to configure a network device for your system, refer to
+your distribution documentation. If during this process you are asked
+for the driver or module name, the name for the Linux Base Driver for
+the Intel PRO/100 Family of Adapters is e100.
+
+As an example, if you install the e100 driver for two PRO/100 adapters
+(eth0 and eth1), add the following to a configuration file in
+/etc/modprobe.d/::
+
+ alias eth0 e100
+ alias eth1 e100
+
+Viewing Link Messages
+---------------------
+
+In order to see link messages and other Intel driver information on your
+console, you must set the dmesg level up to six. This can be done by
+entering the following on the command line before loading the e100
+driver::
+
+ dmesg -n 6
+
+If you wish to see all messages issued by the driver, including debug
+messages, set the dmesg level to eight.
+
+NOTE: This setting is not saved across reboots.
+
+ethtool
+-------
+
+The driver utilizes the ethtool interface for driver configuration and
+diagnostics, as well as displaying statistical information. The ethtool
+version 1.6 or later is required for this functionality.
+
+The latest release of ethtool can be found from
+https://www.kernel.org/pub/software/network/ethtool/
+
+Enabling Wake on LAN (WoL)
+--------------------------
+WoL is provided through the ethtool utility. For instructions on
+enabling WoL with ethtool, refer to the ethtool man page. WoL will be
+enabled on the system during the next shut down or reboot. For this
+driver version, in order to enable WoL, the e100 driver must be loaded
+when shutting down or rebooting the system.
+
+NAPI
+----
+
+NAPI (Rx polling mode) is supported in the e100 driver.
+
+See https://wiki.linuxfoundation.org/networking/napi for more
+information on NAPI.
+
+Multiple Interfaces on Same Ethernet Broadcast Network
+------------------------------------------------------
+
+Due to the default ARP behavior on Linux, it is not possible to have one
+system on two IP networks in the same Ethernet broadcast domain
+(non-partitioned switch) behave as expected. All Ethernet interfaces
+will respond to IP traffic for any IP address assigned to the system.
+This results in unbalanced receive traffic.
+
+If you have multiple interfaces in a server, either turn on ARP
+filtering by
+
+(1) entering::
+
+ echo 1 > /proc/sys/net/ipv4/conf/all/arp_filter
+
+ (this only works if your kernel's version is higher than 2.4.5), or
+
+(2) installing the interfaces in separate broadcast domains (either
+ in different switches or in a switch partitioned to VLANs).
+
+
+Support
+=======
+For general information, go to the Intel support website at:
+https://www.intel.com/support/
+
+or the Intel Wired Networking project hosted by Sourceforge at:
+http://sourceforge.net/projects/e1000
+If an issue is identified with the released source code on a supported kernel
+with a supported adapter, email the specific information related to the issue
+to e1000-devel@lists.sf.net.
diff --git a/Documentation/networking/device_drivers/intel/e1000.rst b/Documentation/networking/device_drivers/ethernet/intel/e1000.rst
similarity index 100%
rename from Documentation/networking/device_drivers/intel/e1000.rst
rename to Documentation/networking/device_drivers/ethernet/intel/e1000.rst
diff --git a/Documentation/networking/device_drivers/intel/e1000e.rst b/Documentation/networking/device_drivers/ethernet/intel/e1000e.rst
similarity index 100%
rename from Documentation/networking/device_drivers/intel/e1000e.rst
rename to Documentation/networking/device_drivers/ethernet/intel/e1000e.rst
diff --git a/Documentation/networking/device_drivers/ethernet/intel/fm10k.rst b/Documentation/networking/device_drivers/ethernet/intel/fm10k.rst
new file mode 100644
index 0000000..9258ef6
--- /dev/null
+++ b/Documentation/networking/device_drivers/ethernet/intel/fm10k.rst
@@ -0,0 +1,142 @@
+.. SPDX-License-Identifier: GPL-2.0+
+
+=============================================================
+Linux Base Driver for Intel(R) Ethernet Multi-host Controller
+=============================================================
+
+August 20, 2018
+Copyright(c) 2015-2018 Intel Corporation.
+
+Contents
+========
+- Identifying Your Adapter
+- Additional Configurations
+- Performance Tuning
+- Known Issues
+- Support
+
+Identifying Your Adapter
+========================
+The driver in this release is compatible with devices based on the Intel(R)
+Ethernet Multi-host Controller.
+
+For information on how to identify your adapter, and for the latest Intel
+network drivers, refer to the Intel Support website:
+https://www.intel.com/support
+
+
+Flow Control
+------------
+The Intel(R) Ethernet Switch Host Interface Driver does not support Flow
+Control. It will not send pause frames. This may result in dropped frames.
+
+
+Virtual Functions (VFs)
+-----------------------
+Use sysfs to enable VFs.
+Valid Range: 0-64
+
+For example::
+
+ echo $num_vf_enabled > /sys/class/net/$dev/device/sriov_numvfs //enable VFs
+ echo 0 > /sys/class/net/$dev/device/sriov_numvfs //disable VFs
+
+NOTE: Neither the device nor the driver control how VFs are mapped into config
+space. Bus layout will vary by operating system. On operating systems that
+support it, you can check sysfs to find the mapping.
+
+NOTE: When SR-IOV mode is enabled, hardware VLAN filtering and VLAN tag
+stripping/insertion will remain enabled. Please remove the old VLAN filter
+before the new VLAN filter is added. For example::
+
+ ip link set eth0 vf 0 vlan 100 // set vlan 100 for VF 0
+ ip link set eth0 vf 0 vlan 0 // Delete vlan 100
+ ip link set eth0 vf 0 vlan 200 // set a new vlan 200 for VF 0
+
+
+Additional Features and Configurations
+======================================
+
+Jumbo Frames
+------------
+Jumbo Frames support is enabled by changing the Maximum Transmission Unit (MTU)
+to a value larger than the default value of 1500.
+
+Use the ifconfig command to increase the MTU size. For example, enter the
+following where <x> is the interface number::
+
+ ifconfig eth<x> mtu 9000 up
+
+Alternatively, you can use the ip command as follows::
+
+ ip link set mtu 9000 dev eth<x>
+ ip link set up dev eth<x>
+
+This setting is not saved across reboots. The setting change can be made
+permanent by adding 'MTU=9000' to the file:
+
+- For RHEL: /etc/sysconfig/network-scripts/ifcfg-eth<x>
+- For SLES: /etc/sysconfig/network/<config_file>
+
+NOTE: The maximum MTU setting for Jumbo Frames is 15342. This value coincides
+with the maximum Jumbo Frames size of 15364 bytes.
+
+NOTE: This driver will attempt to use multiple page sized buffers to receive
+each jumbo packet. This should help to avoid buffer starvation issues when
+allocating receive packets.
+
+
+Generic Receive Offload, aka GRO
+--------------------------------
+The driver supports the in-kernel software implementation of GRO. GRO has
+shown that by coalescing Rx traffic into larger chunks of data, CPU
+utilization can be significantly reduced when under large Rx load. GRO is an
+evolution of the previously-used LRO interface. GRO is able to coalesce
+other protocols besides TCP. It's also safe to use with configurations that
+are problematic for LRO, namely bridging and iSCSI.
+
+
+
+Supported ethtool Commands and Options for Filtering
+----------------------------------------------------
+-n --show-nfc
+ Retrieves the receive network flow classification configurations.
+
+rx-flow-hash tcp4|udp4|ah4|esp4|sctp4|tcp6|udp6|ah6|esp6|sctp6
+ Retrieves the hash options for the specified network traffic type.
+
+-N --config-nfc
+ Configures the receive network flow classification.
+
+rx-flow-hash tcp4|udp4|ah4|esp4|sctp4|tcp6|udp6|ah6|esp6|sctp6 m|v|t|s|d|f|n|r
+ Configures the hash options for the specified network traffic type.
+
+- udp4: UDP over IPv4
+- udp6: UDP over IPv6
+- f Hash on bytes 0 and 1 of the Layer 4 header of the rx packet.
+- n Hash on bytes 2 and 3 of the Layer 4 header of the rx packet.
+
+
+Known Issues/Troubleshooting
+============================
+
+Enabling SR-IOV in a 64-bit Microsoft Windows Server 2012/R2 guest OS under Linux KVM
+-------------------------------------------------------------------------------------
+KVM Hypervisor/VMM supports direct assignment of a PCIe device to a VM. This
+includes traditional PCIe devices, as well as SR-IOV-capable devices based on
+the Intel Ethernet Controller XL710.
+
+
+Support
+=======
+For general information, go to the Intel support website at:
+
+https://www.intel.com/support/
+
+or the Intel Wired Networking project hosted by Sourceforge at:
+
+https://sourceforge.net/projects/e1000
+
+If an issue is identified with the released source code on a supported kernel
+with a supported adapter, email the specific information related to the issue
+to e1000-devel@lists.sf.net.
diff --git a/Documentation/networking/device_drivers/intel/i40e.rst b/Documentation/networking/device_drivers/ethernet/intel/i40e.rst
similarity index 100%
rename from Documentation/networking/device_drivers/intel/i40e.rst
rename to Documentation/networking/device_drivers/ethernet/intel/i40e.rst
diff --git a/Documentation/networking/device_drivers/ethernet/intel/iavf.rst b/Documentation/networking/device_drivers/ethernet/intel/iavf.rst
new file mode 100644
index 0000000..52e037b
--- /dev/null
+++ b/Documentation/networking/device_drivers/ethernet/intel/iavf.rst
@@ -0,0 +1,331 @@
+.. SPDX-License-Identifier: GPL-2.0+
+
+=================================================================
+Linux Base Driver for Intel(R) Ethernet Adaptive Virtual Function
+=================================================================
+
+Intel Ethernet Adaptive Virtual Function Linux driver.
+Copyright(c) 2013-2018 Intel Corporation.
+
+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.
+
+The iavf driver supports the below mentioned virtual function devices and
+can only be activated on kernels running the i40e or newer Physical Function
+(PF) driver compiled with CONFIG_PCI_IOV. The iavf driver requires
+CONFIG_PCI_MSI to be enabled.
+
+The guest OS loading the iavf driver must support MSI-X interrupts.
+
+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
+ * Intel(R) XXV710 Virtual Function
+ * Intel(R) Ethernet Adaptive Virtual Function
+
+For the best performance, make sure the latest NVM/FW is installed on your
+device.
+
+For information on how to identify your adapter, and for the latest NVM/FW
+images and Intel network drivers, refer to the Intel Support website:
+https://www.intel.com/support
+
+
+Additional Features and Configurations
+======================================
+
+Viewing Link Messages
+---------------------
+Link messages will not be displayed to the console if the distribution is
+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
+
+NOTE:
+ This setting is not saved across reboots.
+
+ethtool
+-------
+The driver utilizes the ethtool interface for driver configuration and
+diagnostics, as well as displaying statistical information. The latest ethtool
+version is required for this functionality. Download it at:
+https://www.kernel.org/pub/software/network/ethtool/
+
+Setting VLAN Tag Stripping
+--------------------------
+If you have applications that require Virtual Functions (VFs) to receive
+packets with VLAN tags, you can disable VLAN tag stripping for the VF. The
+Physical Function (PF) processes requests issued from the VF to enable or
+disable VLAN tag stripping. Note that if the PF has assigned a VLAN to a VF,
+then requests from that VF to set VLAN tag stripping will be ignored.
+
+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
+
+or alternatively::
+
+ # ethtool --offload <if_name> rxvlan on/off
+
+Adaptive Virtual Function
+-------------------------
+Adaptive Virtual Function (AVF) allows the virtual function driver, or VF, to
+adapt to changing feature sets of the physical function driver (PF) with which
+it is associated. This allows system administrators to update a PF without
+having to update all the VFs associated with it. All AVFs have a single common
+device ID and branding string.
+
+AVFs have a minimum set of features known as "base mode," but may provide
+additional features depending on what features are available in the PF with
+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
+- 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)
+
+IEEE 802.1ad (QinQ) Support
+---------------------------
+The IEEE 802.1ad standard, informally known as QinQ, allows for multiple VLAN
+IDs within a single Ethernet frame. VLAN IDs are sometimes referred to as
+"tags," and multiple VLAN IDs are thus referred to as a "tag stack." Tag stacks
+allow L2 tunneling and the ability to segregate traffic within a particular
+VLAN ID, among other uses.
+
+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
+
+Where "24" and "371" are example VLAN IDs.
+
+NOTES:
+ Receive checksum offloads, cloud filters, and VLAN acceleration are not
+ supported for 802.1ad (QinQ) packets.
+
+Application Device Queues (ADq)
+-------------------------------
+Application Device Queues (ADq) allows you to dedicate one or more queues to a
+specific application. This can reduce latency for the specified application,
+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.
+
+Example: Sets up two tcs, tc0 and tc1, with 16 queues each and max tx rate set
+to 1Gbit for tc0 and 3Gbit for tc1.
+
+::
+
+ 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)
+
+queues: for each tc, <num queues>@<offset> (e.g. queues 16@0 16@16 assigns
+16 queues to tc0 at offset 0 and 16 queues to tc1 at offset 16. Max total
+number of queues for all tcs is 64 or number of cores, whichever is lower.)
+
+hw 1 mode channel: ‘channel’ with ‘hw’ set to 1 is a new new hardware
+offload mode in mqprio that makes full use of the mqprio options, the
+TCs, the queue configurations, and the QoS parameters.
+
+shaper bw_rlimit: for each tc, sets minimum and maximum bandwidth rates.
+Totals must be equal or less than port speed.
+
+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
+
+3. Apply TCs to ingress (RX) flow of interface::
+
+ # tc qdisc add dev <interface> ingress
+
+NOTES:
+ - 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
+ - You must have iproute2 latest version
+ - 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
+ - If another driver (for example, DPDK) has set cloud filters, you cannot
+ 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
+ encapsulated packet, outer headers are ignored. Therefore, inner headers are
+ matched.
+ - If a TC filter on a PF matches traffic over a VF (on the PF), that traffic
+ will be routed to the appropriate queue of the PF, and will not be passed on
+ the VF. Such traffic will end up getting dropped higher up in the TCP/IP
+ stack as it does not match PF address data.
+ - If traffic matches multiple TC filters that point to different TCs, that
+ traffic will be duplicated and sent to all matching TC queues. The hardware
+ switch mirrors the packet to a VSI list when multiple filters are matched.
+
+
+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
+Virtual Machine (VM) running on a separate host if the Virtual Function
+(VF, or Virtual NIC) is not in trusted mode and spoof checking is enabled
+on the VF. Note that this situation can occur in any combination of client,
+host, and guest operating system. For information on how to set the VF to
+trusted mode, refer to the section "VLAN Tag Packet Steering" in this
+readme document. For information on setting spoof checking, refer to the
+section "MAC and VLAN anti-spoofing feature" in this readme document.
+
+Do not unload port driver if VF with active VM is bound to it
+-------------------------------------------------------------
+Do not unload a port's driver if a Virtual Function (VF) with an active Virtual
+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>
+
+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.
+
+MAC address of Virtual Function changes unexpectedly
+----------------------------------------------------
+If a Virtual Function's MAC address is not assigned in the host, then the VF
+(virtual function) driver will use a random MAC address. This random MAC
+address may change each time the VF driver is reloaded. You can assign a static
+MAC address in the host machine. This static MAC address will survive
+a VF driver reload.
+
+Driver Buffer Overflow Fix
+--------------------------
+The fix to resolve CVE-2016-8105, referenced in Intel SA-00069
+https://www.intel.com/content/www/us/en/security-center/advisory/intel-sa-00069.html
+is included in this and future versions of the driver.
+
+Multiple Interfaces on Same Ethernet Broadcast Network
+------------------------------------------------------
+Due to the default ARP behavior on Linux, it is not possible to have one system
+on two IP networks in the same Ethernet broadcast domain (non-partitioned
+switch) behave as expected. All Ethernet interfaces will respond to IP traffic
+for any IP address assigned to the system. This results in unbalanced receive
+traffic.
+
+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
+
+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
+
+Another alternative is to install the interfaces in separate broadcast domains
+(either in different switches or in a switch partitioned to VLANs).
+
+Rx Page Allocation Errors
+-------------------------
+'Page allocation failure. order:0' errors may occur under stress.
+This is caused by the way the Linux kernel reports this stressed condition.
+
+
+Support
+=======
+For general information, go to the Intel support website at:
+
+https://support.intel.com
+
+or the Intel Wired Networking project hosted by Sourceforge at:
+
+https://sourceforge.net/projects/e1000
+
+If an issue is identified with the released source code on the supported kernel
+with a supported adapter, email the specific information related to the issue
+to e1000-devel@lists.sf.net
diff --git a/Documentation/networking/device_drivers/intel/ice.rst b/Documentation/networking/device_drivers/ethernet/intel/ice.rst
similarity index 100%
rename from Documentation/networking/device_drivers/intel/ice.rst
rename to Documentation/networking/device_drivers/ethernet/intel/ice.rst
diff --git a/Documentation/networking/device_drivers/ethernet/intel/igb.rst b/Documentation/networking/device_drivers/ethernet/intel/igb.rst
new file mode 100644
index 0000000..d46289e
--- /dev/null
+++ b/Documentation/networking/device_drivers/ethernet/intel/igb.rst
@@ -0,0 +1,213 @@
+.. SPDX-License-Identifier: GPL-2.0+
+
+==========================================================
+Linux Base Driver for Intel(R) Ethernet Network Connection
+==========================================================
+
+Intel Gigabit Linux driver.
+Copyright(c) 1999-2018 Intel Corporation.
+
+Contents
+========
+
+- Identifying Your Adapter
+- Command Line Parameters
+- Additional Configurations
+- Support
+
+
+Identifying Your Adapter
+========================
+For information on how to identify your adapter, and for the latest Intel
+network drivers, refer to the Intel Support website:
+https://www.intel.com/support
+
+
+Command Line Parameters
+========================
+If the driver is built as a module, the following optional parameters are used
+by entering them on the command line with the modprobe command using this
+syntax::
+
+ modprobe igb [<option>=<VAL1>,<VAL2>,...]
+
+There needs to be a <VAL#> for each network port in the system supported by
+this driver. The values will be applied to each instance, in function order.
+For example::
+
+ modprobe igb max_vfs=2,4
+
+In this case, there are two network ports supported by igb in the system.
+
+NOTE: A descriptor describes a data buffer and attributes related to the data
+buffer. This information is accessed by the hardware.
+
+max_vfs
+-------
+:Valid Range: 0-7
+
+This parameter adds support for SR-IOV. It causes the driver to spawn up to
+max_vfs worth of virtual functions. If the value is greater than 0 it will
+also force the VMDq parameter to be 1 or more.
+
+The parameters for the driver are referenced by position. Thus, if you have a
+dual port adapter, or more than one adapter in your system, and want N virtual
+functions per port, you must specify a number for each port with each parameter
+separated by a comma. For example::
+
+ modprobe igb max_vfs=4
+
+This will spawn 4 VFs on the first port.
+
+::
+
+ modprobe igb max_vfs=2,4
+
+This will spawn 2 VFs on the first port and 4 VFs on the second port.
+
+NOTE: Caution must be used in loading the driver with these parameters.
+Depending on your system configuration, number of slots, etc., it is impossible
+to predict in all cases where the positions would be on the command line.
+
+NOTE: Neither the device nor the driver control how VFs are mapped into config
+space. Bus layout will vary by operating system. On operating systems that
+support it, you can check sysfs to find the mapping.
+
+NOTE: When either SR-IOV mode or VMDq mode is enabled, hardware VLAN filtering
+and VLAN tag stripping/insertion will remain enabled. Please remove the old
+VLAN filter before the new VLAN filter is added. For example::
+
+ ip link set eth0 vf 0 vlan 100 // set vlan 100 for VF 0
+ ip link set eth0 vf 0 vlan 0 // Delete vlan 100
+ ip link set eth0 vf 0 vlan 200 // set a new vlan 200 for VF 0
+
+Debug
+-----
+:Valid Range: 0-16 (0=none,...,16=all)
+:Default Value: 0
+
+This parameter adjusts the level debug messages displayed in the system logs.
+
+
+Additional Features and Configurations
+======================================
+
+Jumbo Frames
+------------
+Jumbo Frames support is enabled by changing the Maximum Transmission Unit (MTU)
+to a value larger than the default value of 1500.
+
+Use the ifconfig command to increase the MTU size. For example, enter the
+following where <x> is the interface number::
+
+ ifconfig eth<x> mtu 9000 up
+
+Alternatively, you can use the ip command as follows::
+
+ ip link set mtu 9000 dev eth<x>
+ ip link set up dev eth<x>
+
+This setting is not saved across reboots. The setting change can be made
+permanent by adding 'MTU=9000' to the file:
+
+- For RHEL: /etc/sysconfig/network-scripts/ifcfg-eth<x>
+- For SLES: /etc/sysconfig/network/<config_file>
+
+NOTE: The maximum MTU setting for Jumbo Frames is 9216. This value coincides
+with the maximum Jumbo Frames size of 9234 bytes.
+
+NOTE: Using Jumbo frames at 10 or 100 Mbps is not supported and may result in
+poor performance or loss of link.
+
+
+ethtool
+-------
+The driver utilizes the ethtool interface for driver configuration and
+diagnostics, as well as displaying statistical information. The latest ethtool
+version is required for this functionality. Download it at:
+
+https://www.kernel.org/pub/software/network/ethtool/
+
+
+Enabling Wake on LAN (WoL)
+--------------------------
+WoL is configured through the ethtool utility.
+
+WoL will be enabled on the system during the next shut down or reboot. For
+this driver version, in order to enable WoL, the igb driver must be loaded
+prior to shutting down or suspending the system.
+
+NOTE: Wake on LAN is only supported on port A of multi-port devices. Also
+Wake On LAN is not supported for the following device:
+- Intel(R) Gigabit VT Quad Port Server Adapter
+
+
+Multiqueue
+----------
+In this mode, a separate MSI-X vector is allocated for each queue and one for
+"other" interrupts such as link status change and errors. All interrupts are
+throttled via interrupt moderation. Interrupt moderation must be used to avoid
+interrupt storms while the driver is processing one interrupt. The moderation
+value should be at least as large as the expected time for the driver to
+process an interrupt. Multiqueue is off by default.
+
+REQUIREMENTS: MSI-X support is required for Multiqueue. If MSI-X is not found,
+the system will fallback to MSI or to Legacy interrupts. This driver supports
+receive multiqueue on all kernels that support MSI-X.
+
+NOTE: On some kernels a reboot is required to switch between single queue mode
+and multiqueue mode or vice-versa.
+
+
+MAC and VLAN anti-spoofing feature
+----------------------------------
+When a malicious driver attempts to send a spoofed packet, it is dropped by the
+hardware and not transmitted.
+
+An interrupt is sent to the PF driver notifying it of the spoof attempt. When a
+spoofed packet is detected, the PF driver will send the following message to
+the system log (displayed by the "dmesg" command):
+Spoof event(s) detected on VF(n), where n = the VF that attempted to do the
+spoofing
+
+
+Setting MAC Address, VLAN and Rate Limit Using IProute2 Tool
+------------------------------------------------------------
+You can set a MAC address of a Virtual Function (VF), a default VLAN and the
+rate limit using the IProute2 tool. Download the latest version of the
+IProute2 tool from Sourceforge if your version does not have all the features
+you require.
+
+Credit Based Shaper (Qav Mode)
+------------------------------
+When enabling the CBS qdisc in the hardware offload mode, traffic shaping using
+the CBS (described in the IEEE 802.1Q-2018 Section 8.6.8.2 and discussed in the
+Annex L) algorithm will run in the i210 controller, so it's more accurate and
+uses less CPU.
+
+When using offloaded CBS, and the traffic rate obeys the configured rate
+(doesn't go above it), CBS should have little to no effect in the latency.
+
+The offloaded version of the algorithm has some limits, caused by how the idle
+slope is expressed in the adapter's registers. It can only represent idle slopes
+in 16.38431 kbps units, which means that if a idle slope of 2576kbps is
+requested, the controller will be configured to use a idle slope of ~2589 kbps,
+because the driver rounds the value up. For more details, see the comments on
+:c:func:`igb_config_tx_modes()`.
+
+NOTE: This feature is exclusive to i210 models.
+
+
+Support
+=======
+For general information, go to the Intel support website at:
+
+https://www.intel.com/support/
+
+or the Intel Wired Networking project hosted by Sourceforge at:
+
+https://sourceforge.net/projects/e1000
+
+If an issue is identified with the released source code on a supported kernel
+with a supported adapter, email the specific information related to the issue
+to e1000-devel@lists.sf.net.
diff --git a/Documentation/networking/device_drivers/ethernet/intel/igbvf.rst b/Documentation/networking/device_drivers/ethernet/intel/igbvf.rst
new file mode 100644
index 0000000..40fa210
--- /dev/null
+++ b/Documentation/networking/device_drivers/ethernet/intel/igbvf.rst
@@ -0,0 +1,65 @@
+.. SPDX-License-Identifier: GPL-2.0+
+
+===========================================================
+Linux Base Virtual Function Driver for Intel(R) 1G Ethernet
+===========================================================
+
+Intel Gigabit Virtual Function Linux driver.
+Copyright(c) 1999-2018 Intel Corporation.
+
+Contents
+========
+- Identifying Your Adapter
+- Additional Configurations
+- Support
+
+This driver supports Intel 82576-based virtual function devices-based virtual
+function devices that can only be activated on kernels that support SR-IOV.
+
+SR-IOV requires the correct platform and OS support.
+
+The guest OS loading this driver must support MSI-X interrupts.
+
+For questions related to hardware requirements, refer to the documentation
+supplied with your Intel adapter. All hardware requirements listed apply to use
+with Linux.
+
+Driver information can be obtained using ethtool, lspci, and ifconfig.
+Instructions on updating ethtool can be found in the section Additional
+Configurations later in this document.
+
+NOTE: There is a limit of a total of 32 shared VLANs to 1 or more VFs.
+
+
+Identifying Your Adapter
+========================
+For information on how to identify your adapter, and for the latest Intel
+network drivers, refer to the Intel Support website:
+https://www.intel.com/support
+
+
+Additional Features and Configurations
+======================================
+
+ethtool
+-------
+The driver utilizes the ethtool interface for driver configuration and
+diagnostics, as well as displaying statistical information. The latest ethtool
+version is required for this functionality. Download it at:
+
+https://www.kernel.org/pub/software/network/ethtool/
+
+
+Support
+=======
+For general information, go to the Intel support website at:
+
+https://www.intel.com/support/
+
+or the Intel Wired Networking project hosted by Sourceforge at:
+
+https://sourceforge.net/projects/e1000
+
+If an issue is identified with the released source code on a supported kernel
+with a supported adapter, email the specific information related to the issue
+to e1000-devel@lists.sf.net.
diff --git a/Documentation/networking/device_drivers/ethernet/intel/ixgb.rst b/Documentation/networking/device_drivers/ethernet/intel/ixgb.rst
new file mode 100644
index 0000000..c6a233e
--- /dev/null
+++ b/Documentation/networking/device_drivers/ethernet/intel/ixgb.rst
@@ -0,0 +1,468 @@
+.. SPDX-License-Identifier: GPL-2.0+
+
+=====================================================================
+Linux Base Driver for 10 Gigabit Intel(R) Ethernet Network Connection
+=====================================================================
+
+October 1, 2018
+
+
+Contents
+========
+
+- In This Release
+- Identifying Your Adapter
+- Command Line Parameters
+- Improving Performance
+- Additional Configurations
+- Known Issues/Troubleshooting
+- Support
+
+
+
+In This Release
+===============
+
+This file describes the ixgb Linux Base Driver for the 10 Gigabit Intel(R)
+Network Connection. This driver includes support for Itanium(R)2-based
+systems.
+
+For questions related to hardware requirements, refer to the documentation
+supplied with your 10 Gigabit adapter. All hardware requirements listed apply
+to use with Linux.
+
+The following features are available in this kernel:
+ - Native VLANs
+ - Channel Bonding (teaming)
+ - SNMP
+
+Channel Bonding documentation can be found in the Linux kernel source:
+/Documentation/networking/bonding.rst
+
+The driver information previously displayed in the /proc filesystem is not
+supported in this release. Alternatively, you can use ethtool (version 1.6
+or later), lspci, and iproute2 to obtain the same information.
+
+Instructions on updating ethtool can be found in the section "Additional
+Configurations" later in this document.
+
+
+Identifying Your Adapter
+========================
+
+The following Intel network adapters are compatible with the drivers in this
+release:
+
++------------+------------------------------+----------------------------------+
+| Controller | Adapter Name | Physical Layer |
++============+==============================+==================================+
+| 82597EX | Intel(R) PRO/10GbE LR/SR/CX4 | - 10G Base-LR (fiber) |
+| | Server Adapters | - 10G Base-SR (fiber) |
+| | | - 10G Base-CX4 (copper) |
++------------+------------------------------+----------------------------------+
+
+For more information on how to identify your adapter, go to the Adapter &
+Driver ID Guide at:
+
+ https://support.intel.com
+
+
+Command Line Parameters
+=======================
+
+If the driver is built as a module, the following optional parameters are
+used by entering them on the command line with the modprobe command using
+this syntax::
+
+ modprobe ixgb [<option>=<VAL1>,<VAL2>,...]
+
+For example, with two 10GbE PCI adapters, entering::
+
+ modprobe ixgb TxDescriptors=80,128
+
+loads the ixgb driver with 80 TX resources for the first adapter and 128 TX
+resources for the second adapter.
+
+The default value for each parameter is generally the recommended setting,
+unless otherwise noted.
+
+Copybreak
+---------
+:Valid Range: 0-XXXX
+:Default Value: 256
+
+ This is the maximum size of packet that is copied to a new buffer on
+ receive.
+
+Debug
+-----
+:Valid Range: 0-16 (0=none,...,16=all)
+:Default Value: 0
+
+ This parameter adjusts the level of debug messages displayed in the
+ system logs.
+
+FlowControl
+-----------
+:Valid Range: 0-3 (0=none, 1=Rx only, 2=Tx only, 3=Rx&Tx)
+:Default Value: 1 if no EEPROM, otherwise read from EEPROM
+
+ This parameter controls the automatic generation(Tx) and response(Rx) to
+ Ethernet PAUSE frames. There are hardware bugs associated with enabling
+ Tx flow control so beware.
+
+RxDescriptors
+-------------
+:Valid Range: 64-4096
+:Default Value: 1024
+
+ This value is the number of receive descriptors allocated by the driver.
+ Increasing this value allows the driver to buffer more incoming packets.
+ Each descriptor is 16 bytes. A receive buffer is also allocated for
+ each descriptor and can be either 2048, 4056, 8192, or 16384 bytes,
+ depending on the MTU setting. When the MTU size is 1500 or less, the
+ receive buffer size is 2048 bytes. When the MTU is greater than 1500 the
+ receive buffer size will be either 4056, 8192, or 16384 bytes. The
+ maximum MTU size is 16114.
+
+TxDescriptors
+-------------
+:Valid Range: 64-4096
+:Default Value: 256
+
+ This value is the number of transmit descriptors allocated by the driver.
+ Increasing this value allows the driver to queue more transmits. Each
+ descriptor is 16 bytes.
+
+RxIntDelay
+----------
+:Valid Range: 0-65535 (0=off)
+:Default Value: 72
+
+ This value delays the generation of receive interrupts in units of
+ 0.8192 microseconds. Receive interrupt reduction can improve CPU
+ efficiency if properly tuned for specific network traffic. Increasing
+ this value adds extra latency to frame reception and can end up
+ decreasing the throughput of TCP traffic. If the system is reporting
+ dropped receives, this value may be set too high, causing the driver to
+ run out of available receive descriptors.
+
+TxIntDelay
+----------
+:Valid Range: 0-65535 (0=off)
+:Default Value: 32
+
+ This value delays the generation of transmit interrupts in units of
+ 0.8192 microseconds. Transmit interrupt reduction can improve CPU
+ efficiency if properly tuned for specific network traffic. Increasing
+ this value adds extra latency to frame transmission and can end up
+ decreasing the throughput of TCP traffic. If this value is set too high,
+ it will cause the driver to run out of available transmit descriptors.
+
+XsumRX
+------
+:Valid Range: 0-1
+:Default Value: 1
+
+ A value of '1' indicates that the driver should enable IP checksum
+ offload for received packets (both UDP and TCP) to the adapter hardware.
+
+RxFCHighThresh
+--------------
+:Valid Range: 1,536-262,136 (0x600 - 0x3FFF8, 8 byte granularity)
+:Default Value: 196,608 (0x30000)
+
+ Receive Flow control high threshold (when we send a pause frame)
+
+RxFCLowThresh
+-------------
+:Valid Range: 64-262,136 (0x40 - 0x3FFF8, 8 byte granularity)
+:Default Value: 163,840 (0x28000)
+
+ Receive Flow control low threshold (when we send a resume frame)
+
+FCReqTimeout
+------------
+:Valid Range: 1-65535
+:Default Value: 65535
+
+ Flow control request timeout (how long to pause the link partner's tx)
+
+IntDelayEnable
+--------------
+:Value Range: 0,1
+:Default Value: 1
+
+ Interrupt Delay, 0 disables transmit interrupt delay and 1 enables it.
+
+
+Improving Performance
+=====================
+
+With the 10 Gigabit server adapters, the default Linux configuration will
+very likely limit the total available throughput artificially. There is a set
+of configuration changes that, when applied together, will increase the ability
+of Linux to transmit and receive data. The following enhancements were
+originally acquired from settings published at https://www.spec.org/web99/ for
+various submitted results using Linux.
+
+NOTE:
+ These changes are only suggestions, and serve as a starting point for
+ tuning your network performance.
+
+The changes are made in three major ways, listed in order of greatest effect:
+
+- Use ip link to modify the mtu (maximum transmission unit) and the txqueuelen
+ parameter.
+- Use sysctl to modify /proc parameters (essentially kernel tuning)
+- Use setpci to modify the MMRBC field in PCI-X configuration space to increase
+ transmit burst lengths on the bus.
+
+NOTE:
+ setpci modifies the adapter's configuration registers to allow it to read
+ up to 4k bytes at a time (for transmits). However, for some systems the
+ behavior after modifying this register may be undefined (possibly errors of
+ some kind). A power-cycle, hard reset or explicitly setting the e6 register
+ back to 22 (setpci -d 8086:1a48 e6.b=22) may be required to get back to a
+ stable configuration.
+
+- COPY these lines and paste them into ixgb_perf.sh:
+
+::
+
+ #!/bin/bash
+ echo "configuring network performance , edit this file to change the interface
+ or device ID of 10GbE card"
+ # set mmrbc to 4k reads, modify only Intel 10GbE device IDs
+ # replace 1a48 with appropriate 10GbE device's ID installed on the system,
+ # if needed.
+ setpci -d 8086:1a48 e6.b=2e
+ # set the MTU (max transmission unit) - it requires your switch and clients
+ # to change as well.
+ # set the txqueuelen
+ # your ixgb adapter should be loaded as eth1 for this to work, change if needed
+ ip li set dev eth1 mtu 9000 txqueuelen 1000 up
+ # call the sysctl utility to modify /proc/sys entries
+ sysctl -p ./sysctl_ixgb.conf
+
+- COPY these lines and paste them into sysctl_ixgb.conf:
+
+::
+
+ # some of the defaults may be different for your kernel
+ # call this file with sysctl -p <this file>
+ # these are just suggested values that worked well to increase throughput in
+ # several network benchmark tests, your mileage may vary
+
+ ### IPV4 specific settings
+ # turn TCP timestamp support off, default 1, reduces CPU use
+ net.ipv4.tcp_timestamps = 0
+ # turn SACK support off, default on
+ # on systems with a VERY fast bus -> memory interface this is the big gainer
+ net.ipv4.tcp_sack = 0
+ # set min/default/max TCP read buffer, default 4096 87380 174760
+ net.ipv4.tcp_rmem = 10000000 10000000 10000000
+ # set min/pressure/max TCP write buffer, default 4096 16384 131072
+ net.ipv4.tcp_wmem = 10000000 10000000 10000000
+ # set min/pressure/max TCP buffer space, default 31744 32256 32768
+ net.ipv4.tcp_mem = 10000000 10000000 10000000
+
+ ### CORE settings (mostly for socket and UDP effect)
+ # set maximum receive socket buffer size, default 131071
+ net.core.rmem_max = 524287
+ # set maximum send socket buffer size, default 131071
+ net.core.wmem_max = 524287
+ # set default receive socket buffer size, default 65535
+ net.core.rmem_default = 524287
+ # set default send socket buffer size, default 65535
+ net.core.wmem_default = 524287
+ # set maximum amount of option memory buffers, default 10240
+ net.core.optmem_max = 524287
+ # set number of unprocessed input packets before kernel starts dropping them; default 300
+ net.core.netdev_max_backlog = 300000
+
+Edit the ixgb_perf.sh script if necessary to change eth1 to whatever interface
+your ixgb driver is using and/or replace '1a48' with appropriate 10GbE device's
+ID installed on the system.
+
+NOTE:
+ Unless these scripts are added to the boot process, these changes will
+ only last only until the next system reboot.
+
+
+Resolving Slow UDP Traffic
+--------------------------
+If your server does not seem to be able to receive UDP traffic as fast as it
+can receive TCP traffic, it could be because Linux, by default, does not set
+the network stack buffers as large as they need to be to support high UDP
+transfer rates. One way to alleviate this problem is to allow more memory to
+be used by the IP stack to store incoming data.
+
+For instance, use the commands::
+
+ sysctl -w net.core.rmem_max=262143
+
+and::
+
+ sysctl -w net.core.rmem_default=262143
+
+to increase the read buffer memory max and default to 262143 (256k - 1) from
+defaults of max=131071 (128k - 1) and default=65535 (64k - 1). These variables
+will increase the amount of memory used by the network stack for receives, and
+can be increased significantly more if necessary for your application.
+
+
+Additional Configurations
+=========================
+
+Configuring the Driver on Different Distributions
+-------------------------------------------------
+Configuring a network driver to load properly when the system is started is
+distribution dependent. Typically, the configuration process involves adding
+an alias line to /etc/modprobe.conf as well as editing other system startup
+scripts and/or configuration files. Many popular Linux distributions ship
+with tools to make these changes for you. To learn the proper way to
+configure a network device for your system, refer to your distribution
+documentation. If during this process you are asked for the driver or module
+name, the name for the Linux Base Driver for the Intel 10GbE Family of
+Adapters is ixgb.
+
+Viewing Link Messages
+---------------------
+Link messages will not be displayed to the console if the distribution is
+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
+
+NOTE: This setting is not saved across reboots.
+
+Jumbo Frames
+------------
+The driver supports Jumbo Frames for all adapters. Jumbo Frames support is
+enabled by changing the MTU to a value larger than the default of 1500.
+The maximum value for the MTU is 16114. Use the ip command to
+increase the MTU size. For example::
+
+ ip li set dev ethx mtu 9000
+
+The maximum MTU setting for Jumbo Frames is 16114. This value coincides
+with the maximum Jumbo Frames size of 16128.
+
+Ethtool
+-------
+The driver utilizes the ethtool interface for driver configuration and
+diagnostics, as well as displaying statistical information. The ethtool
+version 1.6 or later is required for this functionality.
+
+The latest release of ethtool can be found from
+https://www.kernel.org/pub/software/network/ethtool/
+
+NOTE:
+ The ethtool version 1.6 only supports a limited set of ethtool options.
+ Support for a more complete ethtool feature set can be enabled by
+ upgrading to the latest version.
+
+NAPI
+----
+NAPI (Rx polling mode) is supported in the ixgb driver.
+
+See https://wiki.linuxfoundation.org/networking/napi for more information on
+NAPI.
+
+
+Known Issues/Troubleshooting
+============================
+
+NOTE:
+ After installing the driver, if your Intel Network Connection is not
+ working, verify in the "In This Release" section of the readme that you have
+ installed the correct driver.
+
+Cable Interoperability Issue with Fujitsu XENPAK Module in SmartBits Chassis
+----------------------------------------------------------------------------
+Excessive CRC errors may be observed if the Intel(R) PRO/10GbE CX4
+Server adapter is connected to a Fujitsu XENPAK CX4 module in a SmartBits
+chassis using 15 m/24AWG cable assemblies manufactured by Fujitsu or Leoni.
+The CRC errors may be received either by the Intel(R) PRO/10GbE CX4
+Server adapter or the SmartBits. If this situation occurs using a different
+cable assembly may resolve the issue.
+
+Cable Interoperability Issues with HP Procurve 3400cl Switch Port
+-----------------------------------------------------------------
+Excessive CRC errors may be observed if the Intel(R) PRO/10GbE CX4 Server
+adapter is connected to an HP Procurve 3400cl switch port using short cables
+(1 m or shorter). If this situation occurs, using a longer cable may resolve
+the issue.
+
+Excessive CRC errors may be observed using Fujitsu 24AWG cable assemblies that
+Are 10 m or longer or where using a Leoni 15 m/24AWG cable assembly. The CRC
+errors may be received either by the CX4 Server adapter or at the switch. If
+this situation occurs, using a different cable assembly may resolve the issue.
+
+Jumbo Frames System Requirement
+-------------------------------
+Memory allocation failures have been observed on Linux systems with 64 MB
+of RAM or less that are running Jumbo Frames. If you are using Jumbo
+Frames, your system may require more than the advertised minimum
+requirement of 64 MB of system memory.
+
+Performance Degradation with Jumbo Frames
+-----------------------------------------
+Degradation in throughput performance may be observed in some Jumbo frames
+environments. If this is observed, increasing the application's socket buffer
+size and/or increasing the /proc/sys/net/ipv4/tcp_*mem entry values may help.
+See the specific application manual and /usr/src/linux*/Documentation/
+networking/ip-sysctl.txt for more details.
+
+Allocating Rx Buffers when Using Jumbo Frames
+---------------------------------------------
+Allocating Rx buffers when using Jumbo Frames on 2.6.x kernels may fail if
+the available memory is heavily fragmented. This issue may be seen with PCI-X
+adapters or with packet split disabled. This can be reduced or eliminated
+by changing the amount of available memory for receive buffer allocation, by
+increasing /proc/sys/vm/min_free_kbytes.
+
+Multiple Interfaces on Same Ethernet Broadcast Network
+------------------------------------------------------
+Due to the default ARP behavior on Linux, it is not possible to have
+one system on two IP networks in the same Ethernet broadcast domain
+(non-partitioned switch) behave as expected. All Ethernet interfaces
+will respond to IP traffic for any IP address assigned to the system.
+This results in unbalanced receive traffic.
+
+If you have multiple interfaces in a server, do either of the following:
+
+ - Turn on ARP filtering by entering::
+
+ echo 1 > /proc/sys/net/ipv4/conf/all/arp_filter
+
+ - Install the interfaces in separate broadcast domains - either in
+ different switches or in a switch partitioned to VLANs.
+
+UDP Stress Test Dropped Packet Issue
+--------------------------------------
+Under small packets UDP stress test with 10GbE driver, the Linux system
+may drop UDP packets due to the fullness of socket buffers. You may want
+to change the driver's Flow Control variables to the minimum value for
+controlling packet reception.
+
+Tx Hangs Possible Under Stress
+------------------------------
+Under stress conditions, if TX hangs occur, turning off TSO
+"ethtool -K eth0 tso off" may resolve the problem.
+
+
+Support
+=======
+For general information, go to the Intel support website at:
+
+https://www.intel.com/support/
+
+or the Intel Wired Networking project hosted by Sourceforge at:
+
+https://sourceforge.net/projects/e1000
+
+If an issue is identified with the released source code on a supported kernel
+with a supported adapter, email the specific information related to the issue
+to e1000-devel@lists.sf.net
diff --git a/Documentation/networking/device_drivers/intel/ixgbe.rst b/Documentation/networking/device_drivers/ethernet/intel/ixgbe.rst
similarity index 100%
rename from Documentation/networking/device_drivers/intel/ixgbe.rst
rename to Documentation/networking/device_drivers/ethernet/intel/ixgbe.rst
diff --git a/Documentation/networking/device_drivers/intel/ixgbevf.rst b/Documentation/networking/device_drivers/ethernet/intel/ixgbevf.rst
similarity index 100%
rename from Documentation/networking/device_drivers/intel/ixgbevf.rst
rename to Documentation/networking/device_drivers/ethernet/intel/ixgbevf.rst
diff --git a/Documentation/networking/device_drivers/marvell/octeontx2.rst b/Documentation/networking/device_drivers/ethernet/marvell/octeontx2.rst
similarity index 100%
rename from Documentation/networking/device_drivers/marvell/octeontx2.rst
rename to Documentation/networking/device_drivers/ethernet/marvell/octeontx2.rst
diff --git a/Documentation/networking/device_drivers/mellanox/mlx5.rst b/Documentation/networking/device_drivers/ethernet/mellanox/mlx5.rst
similarity index 100%
rename from Documentation/networking/device_drivers/mellanox/mlx5.rst
rename to Documentation/networking/device_drivers/ethernet/mellanox/mlx5.rst
diff --git a/Documentation/networking/device_drivers/microsoft/netvsc.rst b/Documentation/networking/device_drivers/ethernet/microsoft/netvsc.rst
similarity index 100%
rename from Documentation/networking/device_drivers/microsoft/netvsc.rst
rename to Documentation/networking/device_drivers/ethernet/microsoft/netvsc.rst
diff --git a/Documentation/networking/device_drivers/neterion/s2io.rst b/Documentation/networking/device_drivers/ethernet/neterion/s2io.rst
similarity index 100%
rename from Documentation/networking/device_drivers/neterion/s2io.rst
rename to Documentation/networking/device_drivers/ethernet/neterion/s2io.rst
diff --git a/Documentation/networking/device_drivers/neterion/vxge.rst b/Documentation/networking/device_drivers/ethernet/neterion/vxge.rst
similarity index 100%
rename from Documentation/networking/device_drivers/neterion/vxge.rst
rename to Documentation/networking/device_drivers/ethernet/neterion/vxge.rst
diff --git a/Documentation/networking/device_drivers/netronome/nfp.rst b/Documentation/networking/device_drivers/ethernet/netronome/nfp.rst
similarity index 100%
rename from Documentation/networking/device_drivers/netronome/nfp.rst
rename to Documentation/networking/device_drivers/ethernet/netronome/nfp.rst
diff --git a/Documentation/networking/device_drivers/pensando/ionic.rst b/Documentation/networking/device_drivers/ethernet/pensando/ionic.rst
similarity index 100%
rename from Documentation/networking/device_drivers/pensando/ionic.rst
rename to Documentation/networking/device_drivers/ethernet/pensando/ionic.rst
diff --git a/Documentation/networking/device_drivers/smsc/smc9.rst b/Documentation/networking/device_drivers/ethernet/smsc/smc9.rst
similarity index 100%
rename from Documentation/networking/device_drivers/smsc/smc9.rst
rename to Documentation/networking/device_drivers/ethernet/smsc/smc9.rst
diff --git a/Documentation/networking/device_drivers/stmicro/stmmac.rst b/Documentation/networking/device_drivers/ethernet/stmicro/stmmac.rst
similarity index 100%
rename from Documentation/networking/device_drivers/stmicro/stmmac.rst
rename to Documentation/networking/device_drivers/ethernet/stmicro/stmmac.rst
diff --git a/Documentation/networking/device_drivers/ti/cpsw.rst b/Documentation/networking/device_drivers/ethernet/ti/cpsw.rst
similarity index 100%
rename from Documentation/networking/device_drivers/ti/cpsw.rst
rename to Documentation/networking/device_drivers/ethernet/ti/cpsw.rst
diff --git a/Documentation/networking/device_drivers/ti/cpsw_switchdev.rst b/Documentation/networking/device_drivers/ethernet/ti/cpsw_switchdev.rst
similarity index 100%
rename from Documentation/networking/device_drivers/ti/cpsw_switchdev.rst
rename to Documentation/networking/device_drivers/ethernet/ti/cpsw_switchdev.rst
diff --git a/Documentation/networking/device_drivers/ti/tlan.rst b/Documentation/networking/device_drivers/ethernet/ti/tlan.rst
similarity index 100%
rename from Documentation/networking/device_drivers/ti/tlan.rst
rename to Documentation/networking/device_drivers/ethernet/ti/tlan.rst
diff --git a/Documentation/networking/device_drivers/toshiba/spider_net.rst b/Documentation/networking/device_drivers/ethernet/toshiba/spider_net.rst
similarity index 100%
rename from Documentation/networking/device_drivers/toshiba/spider_net.rst
rename to Documentation/networking/device_drivers/ethernet/toshiba/spider_net.rst
diff --git a/Documentation/networking/defza.rst b/Documentation/networking/device_drivers/fddi/defza.rst
similarity index 100%
rename from Documentation/networking/defza.rst
rename to Documentation/networking/device_drivers/fddi/defza.rst
diff --git a/Documentation/networking/device_drivers/fddi/index.rst b/Documentation/networking/device_drivers/fddi/index.rst
new file mode 100644
index 0000000..0b75294
--- /dev/null
+++ b/Documentation/networking/device_drivers/fddi/index.rst
@@ -0,0 +1,19 @@
+.. SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+
+Fiber Distributed Data Interface (FDDI) Device Drivers
+======================================================
+
+Contents:
+
+.. toctree::
+ :maxdepth: 2
+
+ defza
+ skfp
+
+.. only:: subproject and html
+
+ Indices
+ =======
+
+ * :ref:`genindex`
diff --git a/Documentation/networking/skfp.rst b/Documentation/networking/device_drivers/fddi/skfp.rst
similarity index 100%
rename from Documentation/networking/skfp.rst
rename to Documentation/networking/device_drivers/fddi/skfp.rst
diff --git a/Documentation/networking/device_drivers/freescale/dpaa2/dpio-driver.rst b/Documentation/networking/device_drivers/freescale/dpaa2/dpio-driver.rst
deleted file mode 100644
index 17dbee1..0000000
--- a/Documentation/networking/device_drivers/freescale/dpaa2/dpio-driver.rst
+++ /dev/null
@@ -1,158 +0,0 @@
-.. include:: <isonum.txt>
-
-DPAA2 DPIO (Data Path I/O) Overview
-===================================
-
-:Copyright: |copy| 2016-2018 NXP
-
-This document provides an overview of the Freescale DPAA2 DPIO
-drivers
-
-Introduction
-============
-
-A DPAA2 DPIO (Data Path I/O) is a hardware object that provides
-interfaces to enqueue and dequeue frames to/from network interfaces
-and other accelerators. A DPIO also provides hardware buffer
-pool management for network interfaces.
-
-This document provides an overview the Linux DPIO driver, its
-subcomponents, and its APIs.
-
-See Documentation/networking/device_drivers/freescale/dpaa2/overview.rst for
-a general overview of DPAA2 and the general DPAA2 driver architecture in Linux.
-
-Driver Overview
----------------
-
-The DPIO driver is bound to DPIO objects discovered on the fsl-mc bus and
-provides services that:
-
- A. allow other drivers, such as the Ethernet driver, to enqueue and dequeue
- frames for their respective objects
- B. allow drivers to register callbacks for data availability notifications
- when data becomes available on a queue or channel
- C. allow drivers to manage hardware buffer pools
-
-The Linux DPIO driver consists of 3 primary components--
- DPIO object driver-- fsl-mc driver that manages the DPIO object
-
- DPIO service-- provides APIs to other Linux drivers for services
-
- QBman portal interface-- sends portal commands, gets responses::
-
- fsl-mc other
- bus drivers
- | |
- +---+----+ +------+-----+
- |DPIO obj| |DPIO service|
- | driver |---| (DPIO) |
- +--------+ +------+-----+
- |
- +------+-----+
- | QBman |
- | portal i/f |
- +------------+
- |
- hardware
-
-
-The diagram below shows how the DPIO driver components fit with the other
-DPAA2 Linux driver components::
-
- +------------+
- | OS Network |
- | Stack |
- +------------+ +------------+
- | Allocator |. . . . . . . | Ethernet |
- |(DPMCP,DPBP)| | (DPNI) |
- +-.----------+ +---+---+----+
- . . ^ |
- . . <data avail, | |<enqueue,
- . . tx confirm> | | dequeue>
- +-------------+ . | |
- | DPRC driver | . +--------+ +------------+
- | (DPRC) | . . |DPIO obj| |DPIO service|
- +----------+--+ | driver |-| (DPIO) |
- | +--------+ +------+-----+
- |<dev add/remove> +------|-----+
- | | QBman |
- +----+--------------+ | portal i/f |
- | MC-bus driver | +------------+
- | | |
- | /soc/fsl-mc | |
- +-------------------+ |
- |
- =========================================|=========|========================
- +-+--DPIO---|-----------+
- | | |
- | QBman Portal |
- +-----------------------+
-
- ============================================================================
-
-
-DPIO Object Driver (dpio-driver.c)
-----------------------------------
-
- The dpio-driver component registers with the fsl-mc bus to handle objects of
- type "dpio". The implementation of probe() handles basic initialization
- of the DPIO including mapping of the DPIO regions (the QBman SW portal)
- and initializing interrupts and registering irq handlers. The dpio-driver
- registers the probed DPIO with dpio-service.
-
-DPIO service (dpio-service.c, dpaa2-io.h)
-------------------------------------------
-
- The dpio service component provides queuing, notification, and buffers
- management services to DPAA2 drivers, such as the Ethernet driver. A system
- will typically allocate 1 DPIO object per CPU to allow queuing operations
- to happen simultaneously across all CPUs.
-
- Notification handling
- dpaa2_io_service_register()
-
- dpaa2_io_service_deregister()
-
- dpaa2_io_service_rearm()
-
- Queuing
- dpaa2_io_service_pull_fq()
-
- dpaa2_io_service_pull_channel()
-
- dpaa2_io_service_enqueue_fq()
-
- dpaa2_io_service_enqueue_qd()
-
- dpaa2_io_store_create()
-
- dpaa2_io_store_destroy()
-
- dpaa2_io_store_next()
-
- Buffer pool management
- dpaa2_io_service_release()
-
- dpaa2_io_service_acquire()
-
-QBman portal interface (qbman-portal.c)
----------------------------------------
-
- The qbman-portal component provides APIs to do the low level hardware
- bit twiddling for operations such as:
-
- - initializing Qman software portals
- - building and sending portal commands
- - portal interrupt configuration and processing
-
- The qbman-portal APIs are not public to other drivers, and are
- only used by dpio-service.
-
-Other (dpaa2-fd.h, dpaa2-global.h)
-----------------------------------
-
- Frame descriptor and scatter-gather definitions and the APIs used to
- manipulate them are defined in dpaa2-fd.h.
-
- Dequeue result struct and parsing APIs are defined in dpaa2-global.h.
diff --git a/Documentation/networking/device_drivers/freescale/dpaa2/ethernet-driver.rst b/Documentation/networking/device_drivers/freescale/dpaa2/ethernet-driver.rst
deleted file mode 100644
index cb4c9a0..0000000
--- a/Documentation/networking/device_drivers/freescale/dpaa2/ethernet-driver.rst
+++ /dev/null
@@ -1,185 +0,0 @@
-.. SPDX-License-Identifier: GPL-2.0
-.. include:: <isonum.txt>
-
-===============================
-DPAA2 Ethernet driver
-===============================
-
-:Copyright: |copy| 2017-2018 NXP
-
-This file provides documentation for the Freescale DPAA2 Ethernet driver.
-
-Supported Platforms
-===================
-This driver provides networking support for Freescale DPAA2 SoCs, e.g.
-LS2080A, LS2088A, LS1088A.
-
-
-Architecture Overview
-=====================
-Unlike regular NICs, in the DPAA2 architecture there is no single hardware block
-representing network interfaces; instead, several separate hardware resources
-concur to provide the networking functionality:
-
-- network interfaces
-- queues, channels
-- buffer pools
-- MAC/PHY
-
-All hardware resources are allocated and configured through the Management
-Complex (MC) portals. MC abstracts most of these resources as DPAA2 objects
-and exposes ABIs through which they can be configured and controlled. A few
-hardware resources, like queues, do not have a corresponding MC object and
-are treated as internal resources of other objects.
-
-For a more detailed description of the DPAA2 architecture and its object
-abstractions see *Documentation/networking/device_drivers/freescale/dpaa2/overview.rst*.
-
-Each Linux net device is built on top of a Datapath Network Interface (DPNI)
-object and uses Buffer Pools (DPBPs), I/O Portals (DPIOs) and Concentrators
-(DPCONs).
-
-Configuration interface::
-
- -----------------------
- | DPAA2 Ethernet Driver |
- -----------------------
- . . .
- . . .
- . . . . . . . . . . . .
- . . .
- . . .
- ---------- ---------- -----------
- | DPBP API | | DPNI API | | DPCON API |
- ---------- ---------- -----------
- . . . software
- ======= . ========== . ============ . ===================
- . . . hardware
- ------------------------------------------
- | MC hardware portals |
- ------------------------------------------
- . . .
- . . .
- ------ ------ -------
- | DPBP | | DPNI | | DPCON |
- ------ ------ -------
-
-The DPNIs are network interfaces without a direct one-on-one mapping to PHYs.
-DPBPs represent hardware buffer pools. Packet I/O is performed in the context
-of DPCON objects, using DPIO portals for managing and communicating with the
-hardware resources.
-
-Datapath (I/O) interface::
-
- -----------------------------------------------
- | DPAA2 Ethernet Driver |
- -----------------------------------------------
- | ^ ^ | |
- | | | | |
- enqueue| dequeue| data | dequeue| seed |
- (Tx) | (Rx, TxC)| avail.| request| buffers|
- | | notify| | |
- | | | | |
- V | | V V
- -----------------------------------------------
- | DPIO Driver |
- -----------------------------------------------
- | | | | | software
- | | | | | ================
- | | | | | hardware
- -----------------------------------------------
- | I/O hardware portals |
- -----------------------------------------------
- | ^ ^ | |
- | | | | |
- | | | V |
- V | ================ V
- ---------------------- | -------------
- queues ---------------------- | | Buffer pool |
- ---------------------- | -------------
- =======================
- Channel
-
-Datapath I/O (DPIO) portals provide enqueue and dequeue services, data
-availability notifications and buffer pool management. DPIOs are shared between
-all DPAA2 objects (and implicitly all DPAA2 kernel drivers) that work with data
-frames, but must be affine to the CPUs for the purpose of traffic distribution.
-
-Frames are transmitted and received through hardware frame queues, which can be
-grouped in channels for the purpose of hardware scheduling. The Ethernet driver
-enqueues TX frames on egress queues and after transmission is complete a TX
-confirmation frame is sent back to the CPU.
-
-When frames are available on ingress queues, a data availability notification
-is sent to the CPU; notifications are raised per channel, so even if multiple
-queues in the same channel have available frames, only one notification is sent.
-After a channel fires a notification, is must be explicitly rearmed.
-
-Each network interface can have multiple Rx, Tx and confirmation queues affined
-to CPUs, and one channel (DPCON) for each CPU that services at least one queue.
-DPCONs are used to distribute ingress traffic to different CPUs via the cores'
-affine DPIOs.
-
-The role of hardware buffer pools is storage of ingress frame data. Each network
-interface has a privately owned buffer pool which it seeds with kernel allocated
-buffers.
-
-
-DPNIs are decoupled from PHYs; a DPNI can be connected to a PHY through a DPMAC
-object or to another DPNI through an internal link, but the connection is
-managed by MC and completely transparent to the Ethernet driver.
-
-::
-
- --------- --------- ---------
- | eth if1 | | eth if2 | | eth ifn |
- --------- --------- ---------
- . . .
- . . .
- . . .
- ---------------------------
- | DPAA2 Ethernet Driver |
- ---------------------------
- . . .
- . . .
- . . .
- ------ ------ ------ -------
- | DPNI | | DPNI | | DPNI | | DPMAC |----+
- ------ ------ ------ ------- |
- | | | | |
- | | | | -----
- =========== ================== | PHY |
- -----
-
-Creating a Network Interface
-============================
-A net device is created for each DPNI object probed on the MC bus. Each DPNI has
-a number of properties which determine the network interface configuration
-options and associated hardware resources.
-
-DPNI objects (and the other DPAA2 objects needed for a network interface) can be
-added to a container on the MC bus in one of two ways: statically, through a
-Datapath Layout Binary file (DPL) that is parsed by MC at boot time; or created
-dynamically at runtime, via the DPAA2 objects APIs.
-
-
-Features & Offloads
-===================
-Hardware checksum offloading is supported for TCP and UDP over IPv4/6 frames.
-The checksum offloads can be independently configured on RX and TX through
-ethtool.
-
-Hardware offload of unicast and multicast MAC filtering is supported on the
-ingress path and permanently enabled.
-
-Scatter-gather frames are supported on both RX and TX paths. On TX, SG support
-is configurable via ethtool; on RX it is always enabled.
-
-The DPAA2 hardware can process jumbo Ethernet frames of up to 10K bytes.
-
-The Ethernet driver defines a static flow hashing scheme that distributes
-traffic based on a 5-tuple key: src IP, dst IP, IP proto, L4 src port,
-L4 dst port. No user configuration is supported for now.
-
-Hardware specific statistics for the network interface as well as some
-non-standard driver stats can be consulted through ethtool -S option.
diff --git a/Documentation/networking/baycom.rst b/Documentation/networking/device_drivers/hamradio/baycom.rst
similarity index 100%
rename from Documentation/networking/baycom.rst
rename to Documentation/networking/device_drivers/hamradio/baycom.rst
diff --git a/Documentation/networking/device_drivers/hamradio/index.rst b/Documentation/networking/device_drivers/hamradio/index.rst
new file mode 100644
index 0000000..7e73173
--- /dev/null
+++ b/Documentation/networking/device_drivers/hamradio/index.rst
@@ -0,0 +1,19 @@
+.. SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+
+Amateur Radio Device Drivers
+============================
+
+Contents:
+
+.. toctree::
+ :maxdepth: 2
+
+ baycom
+ z8530drv
+
+.. only:: subproject and html
+
+ Indices
+ =======
+
+ * :ref:`genindex`
diff --git a/Documentation/networking/z8530drv.rst b/Documentation/networking/device_drivers/hamradio/z8530drv.rst
similarity index 100%
rename from Documentation/networking/z8530drv.rst
rename to Documentation/networking/device_drivers/hamradio/z8530drv.rst
diff --git a/Documentation/networking/device_drivers/index.rst b/Documentation/networking/device_drivers/index.rst
index e18dad1..a3113ff 100644
--- a/Documentation/networking/device_drivers/index.rst
+++ b/Documentation/networking/device_drivers/index.rst
@@ -1,56 +1,22 @@
.. SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
-Vendor Device Drivers
-=====================
+Hardware Device Drivers
+=======================
Contents:
.. toctree::
:maxdepth: 2
- freescale/dpaa2/index
- intel/e100
- intel/e1000
- intel/e1000e
- intel/fm10k
- intel/igb
- intel/igbvf
- intel/ixgb
- intel/ixgbe
- intel/ixgbevf
- intel/i40e
- intel/iavf
- intel/ice
- google/gve
- marvell/octeontx2
- mellanox/mlx5
- netronome/nfp
- pensando/ionic
- stmicro/stmmac
- 3com/3c509
- 3com/vortex
- amazon/ena
- aquantia/atlantic
- chelsio/cxgb
- cirrus/cs89x0
- davicom/dm9000
- dec/de4x5
- dec/dmfe
- dlink/dl2k
- freescale/dpaa
- freescale/gianfar
- intel/ipw2100
- intel/ipw2200
- microsoft/netvsc
- neterion/s2io
- neterion/vxge
- qualcomm/rmnet
- sb1000
- smsc/smc9
- ti/cpsw_switchdev
- ti/cpsw
- ti/tlan
- toshiba/spider_net
+ appletalk/index
+ atm/index
+ cable/index
+ cellular/index
+ ethernet/index
+ fddi/index
+ hamradio/index
+ wan/index
+ wifi/index
.. only:: subproject and html
diff --git a/Documentation/networking/device_drivers/intel/e100.rst b/Documentation/networking/device_drivers/intel/e100.rst
deleted file mode 100644
index 3ac21e7..0000000
--- a/Documentation/networking/device_drivers/intel/e100.rst
+++ /dev/null
@@ -1,188 +0,0 @@
-.. SPDX-License-Identifier: GPL-2.0+
-
-=============================================================
-Linux Base Driver for the Intel(R) PRO/100 Family of Adapters
-=============================================================
-
-June 1, 2018
-
-Contents
-========
-
-- In This Release
-- Identifying Your Adapter
-- Building and Installation
-- Driver Configuration Parameters
-- Additional Configurations
-- Known Issues
-- Support
-
-
-In This Release
-===============
-
-This file describes the Linux Base Driver for the Intel(R) PRO/100 Family of
-Adapters. This driver includes support for Itanium(R)2-based systems.
-
-For questions related to hardware requirements, refer to the documentation
-supplied with your Intel PRO/100 adapter.
-
-The following features are now available in supported kernels:
- - Native VLANs
- - Channel Bonding (teaming)
- - SNMP
-
-Channel Bonding documentation can be found in the Linux kernel source:
-/Documentation/networking/bonding.rst
-
-
-Identifying Your Adapter
-========================
-
-For information on how to identify your adapter, and for the latest Intel
-network drivers, refer to the Intel Support website:
-http://www.intel.com/support
-
-Driver Configuration Parameters
-===============================
-
-The default value for each parameter is generally the recommended setting,
-unless otherwise noted.
-
-Rx Descriptors:
- Number of receive descriptors. A receive descriptor is a data
- structure that describes a receive buffer and its attributes to the network
- controller. The data in the descriptor is used by the controller to write
- data from the controller to host memory. In the 3.x.x driver the valid range
- for this parameter is 64-256. The default value is 256. This parameter can be
- changed using the command::
-
- ethtool -G eth? rx n
-
- Where n is the number of desired Rx descriptors.
-
-Tx Descriptors:
- Number of transmit descriptors. A transmit descriptor is a data
- structure that describes a transmit buffer and its attributes to the network
- controller. The data in the descriptor is used by the controller to read
- data from the host memory to the controller. In the 3.x.x driver the valid
- range for this parameter is 64-256. The default value is 128. This parameter
- can be changed using the command::
-
- ethtool -G eth? tx n
-
- Where n is the number of desired Tx descriptors.
-
-Speed/Duplex:
- The driver auto-negotiates the link speed and duplex settings by
- default. The ethtool utility can be used as follows to force speed/duplex.::
-
- ethtool -s eth? autoneg off speed {10|100} duplex {full|half}
-
- NOTE: setting the speed/duplex to incorrect values will cause the link to
- fail.
-
-Event Log Message Level:
- The driver uses the message level flag to log events
- to syslog. The message level can be set at driver load time. It can also be
- set using the command::
-
- ethtool -s eth? msglvl n
-
-
-Additional Configurations
-=========================
-
-Configuring the Driver on Different Distributions
--------------------------------------------------
-
-Configuring a network driver to load properly when the system is started
-is distribution dependent. Typically, the configuration process involves
-adding an alias line to `/etc/modprobe.d/*.conf` as well as editing other
-system startup scripts and/or configuration files. Many popular Linux
-distributions ship with tools to make these changes for you. To learn
-the proper way to configure a network device for your system, refer to
-your distribution documentation. If during this process you are asked
-for the driver or module name, the name for the Linux Base Driver for
-the Intel PRO/100 Family of Adapters is e100.
-
-As an example, if you install the e100 driver for two PRO/100 adapters
-(eth0 and eth1), add the following to a configuration file in
-/etc/modprobe.d/::
-
- alias eth0 e100
- alias eth1 e100
-
-Viewing Link Messages
----------------------
-
-In order to see link messages and other Intel driver information on your
-console, you must set the dmesg level up to six. This can be done by
-entering the following on the command line before loading the e100
-driver::
-
- dmesg -n 6
-
-If you wish to see all messages issued by the driver, including debug
-messages, set the dmesg level to eight.
-
-NOTE: This setting is not saved across reboots.
-
-ethtool
--------
-
-The driver utilizes the ethtool interface for driver configuration and
-diagnostics, as well as displaying statistical information. The ethtool
-version 1.6 or later is required for this functionality.
-
-The latest release of ethtool can be found from
-https://www.kernel.org/pub/software/network/ethtool/
-
-Enabling Wake on LAN (WoL)
---------------------------
-WoL is provided through the ethtool utility. For instructions on
-enabling WoL with ethtool, refer to the ethtool man page. WoL will be
-enabled on the system during the next shut down or reboot. For this
-driver version, in order to enable WoL, the e100 driver must be loaded
-when shutting down or rebooting the system.
-
-NAPI
-----
-
-NAPI (Rx polling mode) is supported in the e100 driver.
-
-See https://wiki.linuxfoundation.org/networking/napi for more
-information on NAPI.
-
-Multiple Interfaces on Same Ethernet Broadcast Network
-------------------------------------------------------
-
-Due to the default ARP behavior on Linux, it is not possible to have one
-system on two IP networks in the same Ethernet broadcast domain
-(non-partitioned switch) behave as expected. All Ethernet interfaces
-will respond to IP traffic for any IP address assigned to the system.
-This results in unbalanced receive traffic.
-
-If you have multiple interfaces in a server, either turn on ARP
-filtering by
-
-(1) entering::
-
- echo 1 > /proc/sys/net/ipv4/conf/all/arp_filter
-
- (this only works if your kernel's version is higher than 2.4.5), or
-
-(2) installing the interfaces in separate broadcast domains (either
- in different switches or in a switch partitioned to VLANs).
-
-
-Support
-=======
-For general information, go to the Intel support website at:
-http://www.intel.com/support/
-
-or the Intel Wired Networking project hosted by Sourceforge at:
-http://sourceforge.net/projects/e1000
-If an issue is identified with the released source code on a supported kernel
-with a supported adapter, email the specific information related to the issue
-to e1000-devel@lists.sf.net.
diff --git a/Documentation/networking/device_drivers/intel/fm10k.rst b/Documentation/networking/device_drivers/intel/fm10k.rst
deleted file mode 100644
index 4d279e6..0000000
--- a/Documentation/networking/device_drivers/intel/fm10k.rst
+++ /dev/null
@@ -1,142 +0,0 @@
-.. SPDX-License-Identifier: GPL-2.0+
-
-=============================================================
-Linux Base Driver for Intel(R) Ethernet Multi-host Controller
-=============================================================
-
-August 20, 2018
-Copyright(c) 2015-2018 Intel Corporation.
-
-Contents
-========
-- Identifying Your Adapter
-- Additional Configurations
-- Performance Tuning
-- Known Issues
-- Support
-
-Identifying Your Adapter
-========================
-The driver in this release is compatible with devices based on the Intel(R)
-Ethernet Multi-host Controller.
-
-For information on how to identify your adapter, and for the latest Intel
-network drivers, refer to the Intel Support website:
-http://www.intel.com/support
-
-
-Flow Control
-------------
-The Intel(R) Ethernet Switch Host Interface Driver does not support Flow
-Control. It will not send pause frames. This may result in dropped frames.
-
-
-Virtual Functions (VFs)
------------------------
-Use sysfs to enable VFs.
-Valid Range: 0-64
-
-For example::
-
- echo $num_vf_enabled > /sys/class/net/$dev/device/sriov_numvfs //enable VFs
- echo 0 > /sys/class/net/$dev/device/sriov_numvfs //disable VFs
-
-NOTE: Neither the device nor the driver control how VFs are mapped into config
-space. Bus layout will vary by operating system. On operating systems that
-support it, you can check sysfs to find the mapping.
-
-NOTE: When SR-IOV mode is enabled, hardware VLAN filtering and VLAN tag
-stripping/insertion will remain enabled. Please remove the old VLAN filter
-before the new VLAN filter is added. For example::
-
- ip link set eth0 vf 0 vlan 100 // set vlan 100 for VF 0
- ip link set eth0 vf 0 vlan 0 // Delete vlan 100
- ip link set eth0 vf 0 vlan 200 // set a new vlan 200 for VF 0
-
-
-Additional Features and Configurations
-======================================
-
-Jumbo Frames
-------------
-Jumbo Frames support is enabled by changing the Maximum Transmission Unit (MTU)
-to a value larger than the default value of 1500.
-
-Use the ifconfig command to increase the MTU size. For example, enter the
-following where <x> is the interface number::
-
- ifconfig eth<x> mtu 9000 up
-
-Alternatively, you can use the ip command as follows::
-
- ip link set mtu 9000 dev eth<x>
- ip link set up dev eth<x>
-
-This setting is not saved across reboots. The setting change can be made
-permanent by adding 'MTU=9000' to the file:
-
-- For RHEL: /etc/sysconfig/network-scripts/ifcfg-eth<x>
-- For SLES: /etc/sysconfig/network/<config_file>
-
-NOTE: The maximum MTU setting for Jumbo Frames is 15342. This value coincides
-with the maximum Jumbo Frames size of 15364 bytes.
-
-NOTE: This driver will attempt to use multiple page sized buffers to receive
-each jumbo packet. This should help to avoid buffer starvation issues when
-allocating receive packets.
-
-
-Generic Receive Offload, aka GRO
---------------------------------
-The driver supports the in-kernel software implementation of GRO. GRO has
-shown that by coalescing Rx traffic into larger chunks of data, CPU
-utilization can be significantly reduced when under large Rx load. GRO is an
-evolution of the previously-used LRO interface. GRO is able to coalesce
-other protocols besides TCP. It's also safe to use with configurations that
-are problematic for LRO, namely bridging and iSCSI.
-
-
-
-Supported ethtool Commands and Options for Filtering
-----------------------------------------------------
--n --show-nfc
- Retrieves the receive network flow classification configurations.
-
-rx-flow-hash tcp4|udp4|ah4|esp4|sctp4|tcp6|udp6|ah6|esp6|sctp6
- Retrieves the hash options for the specified network traffic type.
-
--N --config-nfc
- Configures the receive network flow classification.
-
-rx-flow-hash tcp4|udp4|ah4|esp4|sctp4|tcp6|udp6|ah6|esp6|sctp6 m|v|t|s|d|f|n|r
- Configures the hash options for the specified network traffic type.
-
-- udp4: UDP over IPv4
-- udp6: UDP over IPv6
-- f Hash on bytes 0 and 1 of the Layer 4 header of the rx packet.
-- n Hash on bytes 2 and 3 of the Layer 4 header of the rx packet.
-
-
-Known Issues/Troubleshooting
-============================
-
-Enabling SR-IOV in a 64-bit Microsoft Windows Server 2012/R2 guest OS under Linux KVM
--------------------------------------------------------------------------------------
-KVM Hypervisor/VMM supports direct assignment of a PCIe device to a VM. This
-includes traditional PCIe devices, as well as SR-IOV-capable devices based on
-the Intel Ethernet Controller XL710.
-
-
-Support
-=======
-For general information, go to the Intel support website at:
-
-https://www.intel.com/support/
-
-or the Intel Wired Networking project hosted by Sourceforge at:
-
-https://sourceforge.net/projects/e1000
-
-If an issue is identified with the released source code on a supported kernel
-with a supported adapter, email the specific information related to the issue
-to e1000-devel@lists.sf.net.
diff --git a/Documentation/networking/device_drivers/intel/iavf.rst b/Documentation/networking/device_drivers/intel/iavf.rst
deleted file mode 100644
index 84ac7e7..0000000
--- a/Documentation/networking/device_drivers/intel/iavf.rst
+++ /dev/null
@@ -1,331 +0,0 @@
-.. SPDX-License-Identifier: GPL-2.0+
-
-=================================================================
-Linux Base Driver for Intel(R) Ethernet Adaptive Virtual Function
-=================================================================
-
-Intel Ethernet Adaptive Virtual Function Linux driver.
-Copyright(c) 2013-2018 Intel Corporation.
-
-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.
-
-The iavf driver supports the below mentioned virtual function devices and
-can only be activated on kernels running the i40e or newer Physical Function
-(PF) driver compiled with CONFIG_PCI_IOV. The iavf driver requires
-CONFIG_PCI_MSI to be enabled.
-
-The guest OS loading the iavf driver must support MSI-X interrupts.
-
-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
- * Intel(R) XXV710 Virtual Function
- * Intel(R) Ethernet Adaptive Virtual Function
-
-For the best performance, make sure the latest NVM/FW is installed on your
-device.
-
-For information on how to identify your adapter, and for the latest NVM/FW
-images and Intel network drivers, refer to the Intel Support website:
-http://www.intel.com/support
-
-
-Additional Features and Configurations
-======================================
-
-Viewing Link Messages
----------------------
-Link messages will not be displayed to the console if the distribution is
-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
-
-NOTE:
- This setting is not saved across reboots.
-
-ethtool
--------
-The driver utilizes the ethtool interface for driver configuration and
-diagnostics, as well as displaying statistical information. The latest ethtool
-version is required for this functionality. Download it at:
-https://www.kernel.org/pub/software/network/ethtool/
-
-Setting VLAN Tag Stripping
---------------------------
-If you have applications that require Virtual Functions (VFs) to receive
-packets with VLAN tags, you can disable VLAN tag stripping for the VF. The
-Physical Function (PF) processes requests issued from the VF to enable or
-disable VLAN tag stripping. Note that if the PF has assigned a VLAN to a VF,
-then requests from that VF to set VLAN tag stripping will be ignored.
-
-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
-
-or alternatively::
-
- # ethtool --offload <if_name> rxvlan on/off
-
-Adaptive Virtual Function
--------------------------
-Adaptive Virtual Function (AVF) allows the virtual function driver, or VF, to
-adapt to changing feature sets of the physical function driver (PF) with which
-it is associated. This allows system administrators to update a PF without
-having to update all the VFs associated with it. All AVFs have a single common
-device ID and branding string.
-
-AVFs have a minimum set of features known as "base mode," but may provide
-additional features depending on what features are available in the PF with
-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
-- 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)
-
-IEEE 802.1ad (QinQ) Support
----------------------------
-The IEEE 802.1ad standard, informally known as QinQ, allows for multiple VLAN
-IDs within a single Ethernet frame. VLAN IDs are sometimes referred to as
-"tags," and multiple VLAN IDs are thus referred to as a "tag stack." Tag stacks
-allow L2 tunneling and the ability to segregate traffic within a particular
-VLAN ID, among other uses.
-
-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
-
-Where "24" and "371" are example VLAN IDs.
-
-NOTES:
- Receive checksum offloads, cloud filters, and VLAN acceleration are not
- supported for 802.1ad (QinQ) packets.
-
-Application Device Queues (ADq)
--------------------------------
-Application Device Queues (ADq) allows you to dedicate one or more queues to a
-specific application. This can reduce latency for the specified application,
-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.
-
-Example: Sets up two tcs, tc0 and tc1, with 16 queues each and max tx rate set
-to 1Gbit for tc0 and 3Gbit for tc1.
-
-::
-
- 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)
-
-queues: for each tc, <num queues>@<offset> (e.g. queues 16@0 16@16 assigns
-16 queues to tc0 at offset 0 and 16 queues to tc1 at offset 16. Max total
-number of queues for all tcs is 64 or number of cores, whichever is lower.)
-
-hw 1 mode channel: ‘channel’ with ‘hw’ set to 1 is a new new hardware
-offload mode in mqprio that makes full use of the mqprio options, the
-TCs, the queue configurations, and the QoS parameters.
-
-shaper bw_rlimit: for each tc, sets minimum and maximum bandwidth rates.
-Totals must be equal or less than port speed.
-
-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
-
-3. Apply TCs to ingress (RX) flow of interface::
-
- # tc qdisc add dev <interface> ingress
-
-NOTES:
- - 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
- - You must have iproute2 latest version
- - 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
- - If another driver (for example, DPDK) has set cloud filters, you cannot
- 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
- encapsulated packet, outer headers are ignored. Therefore, inner headers are
- matched.
- - If a TC filter on a PF matches traffic over a VF (on the PF), that traffic
- will be routed to the appropriate queue of the PF, and will not be passed on
- the VF. Such traffic will end up getting dropped higher up in the TCP/IP
- stack as it does not match PF address data.
- - If traffic matches multiple TC filters that point to different TCs, that
- traffic will be duplicated and sent to all matching TC queues. The hardware
- switch mirrors the packet to a VSI list when multiple filters are matched.
-
-
-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
-Virtual Machine (VM) running on a separate host if the Virtual Function
-(VF, or Virtual NIC) is not in trusted mode and spoof checking is enabled
-on the VF. Note that this situation can occur in any combination of client,
-host, and guest operating system. For information on how to set the VF to
-trusted mode, refer to the section "VLAN Tag Packet Steering" in this
-readme document. For information on setting spoof checking, refer to the
-section "MAC and VLAN anti-spoofing feature" in this readme document.
-
-Do not unload port driver if VF with active VM is bound to it
--------------------------------------------------------------
-Do not unload a port's driver if a Virtual Function (VF) with an active Virtual
-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>
-
-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.
-
-MAC address of Virtual Function changes unexpectedly
-----------------------------------------------------
-If a Virtual Function's MAC address is not assigned in the host, then the VF
-(virtual function) driver will use a random MAC address. This random MAC
-address may change each time the VF driver is reloaded. You can assign a static
-MAC address in the host machine. This static MAC address will survive
-a VF driver reload.
-
-Driver Buffer Overflow Fix
---------------------------
-The fix to resolve CVE-2016-8105, referenced in Intel SA-00069
-https://www.intel.com/content/www/us/en/security-center/advisory/intel-sa-00069.html
-is included in this and future versions of the driver.
-
-Multiple Interfaces on Same Ethernet Broadcast Network
-------------------------------------------------------
-Due to the default ARP behavior on Linux, it is not possible to have one system
-on two IP networks in the same Ethernet broadcast domain (non-partitioned
-switch) behave as expected. All Ethernet interfaces will respond to IP traffic
-for any IP address assigned to the system. This results in unbalanced receive
-traffic.
-
-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
-
-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
-
-Another alternative is to install the interfaces in separate broadcast domains
-(either in different switches or in a switch partitioned to VLANs).
-
-Rx Page Allocation Errors
--------------------------
-'Page allocation failure. order:0' errors may occur under stress.
-This is caused by the way the Linux kernel reports this stressed condition.
-
-
-Support
-=======
-For general information, go to the Intel support website at:
-
-https://support.intel.com
-
-or the Intel Wired Networking project hosted by Sourceforge at:
-
-https://sourceforge.net/projects/e1000
-
-If an issue is identified with the released source code on the supported kernel
-with a supported adapter, email the specific information related to the issue
-to e1000-devel@lists.sf.net
diff --git a/Documentation/networking/device_drivers/intel/igb.rst b/Documentation/networking/device_drivers/intel/igb.rst
deleted file mode 100644
index 87e560f..0000000
--- a/Documentation/networking/device_drivers/intel/igb.rst
+++ /dev/null
@@ -1,213 +0,0 @@
-.. SPDX-License-Identifier: GPL-2.0+
-
-==========================================================
-Linux Base Driver for Intel(R) Ethernet Network Connection
-==========================================================
-
-Intel Gigabit Linux driver.
-Copyright(c) 1999-2018 Intel Corporation.
-
-Contents
-========
-
-- Identifying Your Adapter
-- Command Line Parameters
-- Additional Configurations
-- Support
-
-
-Identifying Your Adapter
-========================
-For information on how to identify your adapter, and for the latest Intel
-network drivers, refer to the Intel Support website:
-http://www.intel.com/support
-
-
-Command Line Parameters
-========================
-If the driver is built as a module, the following optional parameters are used
-by entering them on the command line with the modprobe command using this
-syntax::
-
- modprobe igb [<option>=<VAL1>,<VAL2>,...]
-
-There needs to be a <VAL#> for each network port in the system supported by
-this driver. The values will be applied to each instance, in function order.
-For example::
-
- modprobe igb max_vfs=2,4
-
-In this case, there are two network ports supported by igb in the system.
-
-NOTE: A descriptor describes a data buffer and attributes related to the data
-buffer. This information is accessed by the hardware.
-
-max_vfs
--------
-:Valid Range: 0-7
-
-This parameter adds support for SR-IOV. It causes the driver to spawn up to
-max_vfs worth of virtual functions. If the value is greater than 0 it will
-also force the VMDq parameter to be 1 or more.
-
-The parameters for the driver are referenced by position. Thus, if you have a
-dual port adapter, or more than one adapter in your system, and want N virtual
-functions per port, you must specify a number for each port with each parameter
-separated by a comma. For example::
-
- modprobe igb max_vfs=4
-
-This will spawn 4 VFs on the first port.
-
-::
-
- modprobe igb max_vfs=2,4
-
-This will spawn 2 VFs on the first port and 4 VFs on the second port.
-
-NOTE: Caution must be used in loading the driver with these parameters.
-Depending on your system configuration, number of slots, etc., it is impossible
-to predict in all cases where the positions would be on the command line.
-
-NOTE: Neither the device nor the driver control how VFs are mapped into config
-space. Bus layout will vary by operating system. On operating systems that
-support it, you can check sysfs to find the mapping.
-
-NOTE: When either SR-IOV mode or VMDq mode is enabled, hardware VLAN filtering
-and VLAN tag stripping/insertion will remain enabled. Please remove the old
-VLAN filter before the new VLAN filter is added. For example::
-
- ip link set eth0 vf 0 vlan 100 // set vlan 100 for VF 0
- ip link set eth0 vf 0 vlan 0 // Delete vlan 100
- ip link set eth0 vf 0 vlan 200 // set a new vlan 200 for VF 0
-
-Debug
------
-:Valid Range: 0-16 (0=none,...,16=all)
-:Default Value: 0
-
-This parameter adjusts the level debug messages displayed in the system logs.
-
-
-Additional Features and Configurations
-======================================
-
-Jumbo Frames
-------------
-Jumbo Frames support is enabled by changing the Maximum Transmission Unit (MTU)
-to a value larger than the default value of 1500.
-
-Use the ifconfig command to increase the MTU size. For example, enter the
-following where <x> is the interface number::
-
- ifconfig eth<x> mtu 9000 up
-
-Alternatively, you can use the ip command as follows::
-
- ip link set mtu 9000 dev eth<x>
- ip link set up dev eth<x>
-
-This setting is not saved across reboots. The setting change can be made
-permanent by adding 'MTU=9000' to the file:
-
-- For RHEL: /etc/sysconfig/network-scripts/ifcfg-eth<x>
-- For SLES: /etc/sysconfig/network/<config_file>
-
-NOTE: The maximum MTU setting for Jumbo Frames is 9216. This value coincides
-with the maximum Jumbo Frames size of 9234 bytes.
-
-NOTE: Using Jumbo frames at 10 or 100 Mbps is not supported and may result in
-poor performance or loss of link.
-
-
-ethtool
--------
-The driver utilizes the ethtool interface for driver configuration and
-diagnostics, as well as displaying statistical information. The latest ethtool
-version is required for this functionality. Download it at:
-
-https://www.kernel.org/pub/software/network/ethtool/
-
-
-Enabling Wake on LAN (WoL)
---------------------------
-WoL is configured through the ethtool utility.
-
-WoL will be enabled on the system during the next shut down or reboot. For
-this driver version, in order to enable WoL, the igb driver must be loaded
-prior to shutting down or suspending the system.
-
-NOTE: Wake on LAN is only supported on port A of multi-port devices. Also
-Wake On LAN is not supported for the following device:
-- Intel(R) Gigabit VT Quad Port Server Adapter
-
-
-Multiqueue
-----------
-In this mode, a separate MSI-X vector is allocated for each queue and one for
-"other" interrupts such as link status change and errors. All interrupts are
-throttled via interrupt moderation. Interrupt moderation must be used to avoid
-interrupt storms while the driver is processing one interrupt. The moderation
-value should be at least as large as the expected time for the driver to
-process an interrupt. Multiqueue is off by default.
-
-REQUIREMENTS: MSI-X support is required for Multiqueue. If MSI-X is not found,
-the system will fallback to MSI or to Legacy interrupts. This driver supports
-receive multiqueue on all kernels that support MSI-X.
-
-NOTE: On some kernels a reboot is required to switch between single queue mode
-and multiqueue mode or vice-versa.
-
-
-MAC and VLAN anti-spoofing feature
-----------------------------------
-When a malicious driver attempts to send a spoofed packet, it is dropped by the
-hardware and not transmitted.
-
-An interrupt is sent to the PF driver notifying it of the spoof attempt. When a
-spoofed packet is detected, the PF driver will send the following message to
-the system log (displayed by the "dmesg" command):
-Spoof event(s) detected on VF(n), where n = the VF that attempted to do the
-spoofing
-
-
-Setting MAC Address, VLAN and Rate Limit Using IProute2 Tool
-------------------------------------------------------------
-You can set a MAC address of a Virtual Function (VF), a default VLAN and the
-rate limit using the IProute2 tool. Download the latest version of the
-IProute2 tool from Sourceforge if your version does not have all the features
-you require.
-
-Credit Based Shaper (Qav Mode)
-------------------------------
-When enabling the CBS qdisc in the hardware offload mode, traffic shaping using
-the CBS (described in the IEEE 802.1Q-2018 Section 8.6.8.2 and discussed in the
-Annex L) algorithm will run in the i210 controller, so it's more accurate and
-uses less CPU.
-
-When using offloaded CBS, and the traffic rate obeys the configured rate
-(doesn't go above it), CBS should have little to no effect in the latency.
-
-The offloaded version of the algorithm has some limits, caused by how the idle
-slope is expressed in the adapter's registers. It can only represent idle slopes
-in 16.38431 kbps units, which means that if a idle slope of 2576kbps is
-requested, the controller will be configured to use a idle slope of ~2589 kbps,
-because the driver rounds the value up. For more details, see the comments on
-:c:func:`igb_config_tx_modes()`.
-
-NOTE: This feature is exclusive to i210 models.
-
-
-Support
-=======
-For general information, go to the Intel support website at:
-
-https://www.intel.com/support/
-
-or the Intel Wired Networking project hosted by Sourceforge at:
-
-https://sourceforge.net/projects/e1000
-
-If an issue is identified with the released source code on a supported kernel
-with a supported adapter, email the specific information related to the issue
-to e1000-devel@lists.sf.net.
diff --git a/Documentation/networking/device_drivers/intel/igbvf.rst b/Documentation/networking/device_drivers/intel/igbvf.rst
deleted file mode 100644
index 557fc02..0000000
--- a/Documentation/networking/device_drivers/intel/igbvf.rst
+++ /dev/null
@@ -1,65 +0,0 @@
-.. SPDX-License-Identifier: GPL-2.0+
-
-===========================================================
-Linux Base Virtual Function Driver for Intel(R) 1G Ethernet
-===========================================================
-
-Intel Gigabit Virtual Function Linux driver.
-Copyright(c) 1999-2018 Intel Corporation.
-
-Contents
-========
-- Identifying Your Adapter
-- Additional Configurations
-- Support
-
-This driver supports Intel 82576-based virtual function devices-based virtual
-function devices that can only be activated on kernels that support SR-IOV.
-
-SR-IOV requires the correct platform and OS support.
-
-The guest OS loading this driver must support MSI-X interrupts.
-
-For questions related to hardware requirements, refer to the documentation
-supplied with your Intel adapter. All hardware requirements listed apply to use
-with Linux.
-
-Driver information can be obtained using ethtool, lspci, and ifconfig.
-Instructions on updating ethtool can be found in the section Additional
-Configurations later in this document.
-
-NOTE: There is a limit of a total of 32 shared VLANs to 1 or more VFs.
-
-
-Identifying Your Adapter
-========================
-For information on how to identify your adapter, and for the latest Intel
-network drivers, refer to the Intel Support website:
-http://www.intel.com/support
-
-
-Additional Features and Configurations
-======================================
-
-ethtool
--------
-The driver utilizes the ethtool interface for driver configuration and
-diagnostics, as well as displaying statistical information. The latest ethtool
-version is required for this functionality. Download it at:
-
-https://www.kernel.org/pub/software/network/ethtool/
-
-
-Support
-=======
-For general information, go to the Intel support website at:
-
-https://www.intel.com/support/
-
-or the Intel Wired Networking project hosted by Sourceforge at:
-
-https://sourceforge.net/projects/e1000
-
-If an issue is identified with the released source code on a supported kernel
-with a supported adapter, email the specific information related to the issue
-to e1000-devel@lists.sf.net.
diff --git a/Documentation/networking/device_drivers/intel/ipw2100.rst b/Documentation/networking/device_drivers/intel/ipw2100.rst
deleted file mode 100644
index d54ad52..0000000
--- a/Documentation/networking/device_drivers/intel/ipw2100.rst
+++ /dev/null
@@ -1,323 +0,0 @@
-.. SPDX-License-Identifier: GPL-2.0
-.. include:: <isonum.txt>
-
-===========================================
-Intel(R) PRO/Wireless 2100 Driver for Linux
-===========================================
-
-Support for:
-
-- Intel(R) PRO/Wireless 2100 Network Connection
-
-Copyright |copy| 2003-2006, Intel Corporation
-
-README.ipw2100
-
-:Version: git-1.1.5
-:Date: January 25, 2006
-
-.. Index
-
- 0. IMPORTANT INFORMATION BEFORE USING THIS DRIVER
- 1. Introduction
- 2. Release git-1.1.5 Current Features
- 3. Command Line Parameters
- 4. Sysfs Helper Files
- 5. Radio Kill Switch
- 6. Dynamic Firmware
- 7. Power Management
- 8. Support
- 9. License
-
-
-0. IMPORTANT INFORMATION BEFORE USING THIS DRIVER
-=================================================
-
-Important Notice FOR ALL USERS OR DISTRIBUTORS!!!!
-
-Intel wireless LAN adapters are engineered, manufactured, tested, and
-quality checked to ensure that they meet all necessary local and
-governmental regulatory agency requirements for the regions that they
-are designated and/or marked to ship into. Since wireless LANs are
-generally unlicensed devices that share spectrum with radars,
-satellites, and other licensed and unlicensed devices, it is sometimes
-necessary to dynamically detect, avoid, and limit usage to avoid
-interference with these devices. In many instances Intel is required to
-provide test data to prove regional and local compliance to regional and
-governmental regulations before certification or approval to use the
-product is granted. Intel's wireless LAN's EEPROM, firmware, and
-software driver are designed to carefully control parameters that affect
-radio operation and to ensure electromagnetic compliance (EMC). These
-parameters include, without limitation, RF power, spectrum usage,
-channel scanning, and human exposure.
-
-For these reasons Intel cannot permit any manipulation by third parties
-of the software provided in binary format with the wireless WLAN
-adapters (e.g., the EEPROM and firmware). Furthermore, if you use any
-patches, utilities, or code with the Intel wireless LAN adapters that
-have been manipulated by an unauthorized party (i.e., patches,
-utilities, or code (including open source code modifications) which have
-not been validated by Intel), (i) you will be solely responsible for
-ensuring the regulatory compliance of the products, (ii) Intel will bear
-no liability, under any theory of liability for any issues associated
-with the modified products, including without limitation, claims under
-the warranty and/or issues arising from regulatory non-compliance, and
-(iii) Intel will not provide or be required to assist in providing
-support to any third parties for such modified products.
-
-Note: Many regulatory agencies consider Wireless LAN adapters to be
-modules, and accordingly, condition system-level regulatory approval
-upon receipt and review of test data documenting that the antennas and
-system configuration do not cause the EMC and radio operation to be
-non-compliant.
-
-The drivers available for download from SourceForge are provided as a
-part of a development project. Conformance to local regulatory
-requirements is the responsibility of the individual developer. As
-such, if you are interested in deploying or shipping a driver as part of
-solution intended to be used for purposes other than development, please
-obtain a tested driver from Intel Customer Support at:
-
-http://www.intel.com/support/wireless/sb/CS-006408.htm
-
-1. Introduction
-===============
-
-This document provides a brief overview of the features supported by the
-IPW2100 driver project. The main project website, where the latest
-development version of the driver can be found, is:
-
- http://ipw2100.sourceforge.net
-
-There you can find the not only the latest releases, but also information about
-potential fixes and patches, as well as links to the development mailing list
-for the driver project.
-
-
-2. Release git-1.1.5 Current Supported Features
-===============================================
-
-- Managed (BSS) and Ad-Hoc (IBSS)
-- WEP (shared key and open)
-- Wireless Tools support
-- 802.1x (tested with XSupplicant 1.0.1)
-
-Enabled (but not supported) features:
-- Monitor/RFMon mode
-- WPA/WPA2
-
-The distinction between officially supported and enabled is a reflection
-on the amount of validation and interoperability testing that has been
-performed on a given feature.
-
-
-3. Command Line Parameters
-==========================
-
-If the driver is built as a module, the following optional parameters are used
-by entering them on the command line with the modprobe command using this
-syntax::
-
- modprobe ipw2100 [<option>=<VAL1><,VAL2>...]
-
-For example, to disable the radio on driver loading, enter:
-
- modprobe ipw2100 disable=1
-
-The ipw2100 driver supports the following module parameters:
-
-========= ============== ============ ==============================
-Name Value Example Meaning
-========= ============== ============ ==============================
-debug 0x0-0xffffffff debug=1024 Debug level set to 1024
-mode 0,1,2 mode=1 AdHoc
-channel int channel=3 Only valid in AdHoc or Monitor
-associate boolean associate=0 Do NOT auto associate
-disable boolean disable=1 Do not power the HW
-========= ============== ============ ==============================
-
-
-4. Sysfs Helper Files
-=====================
-
-There are several ways to control the behavior of the driver. Many of the
-general capabilities are exposed through the Wireless Tools (iwconfig). There
-are a few capabilities that are exposed through entries in the Linux Sysfs.
-
-
-**Driver Level**
-
-For the driver level files, look in /sys/bus/pci/drivers/ipw2100/
-
- debug_level
- This controls the same global as the 'debug' module parameter. For
- information on the various debugging levels available, run the 'dvals'
- script found in the driver source directory.
-
- .. note::
-
- 'debug_level' is only enabled if CONFIG_IPW2100_DEBUG is turn on.
-
-**Device Level**
-
-For the device level files look in::
-
- /sys/bus/pci/drivers/ipw2100/{PCI-ID}/
-
-For example::
-
- /sys/bus/pci/drivers/ipw2100/0000:02:01.0
-
-For the device level files, see /sys/bus/pci/drivers/ipw2100:
-
- rf_kill
- read
-
- == =========================================
- 0 RF kill not enabled (radio on)
- 1 SW based RF kill active (radio off)
- 2 HW based RF kill active (radio off)
- 3 Both HW and SW RF kill active (radio off)
- == =========================================
-
- write
-
- == ==================================================
- 0 If SW based RF kill active, turn the radio back on
- 1 If radio is on, activate SW based RF kill
- == ==================================================
-
- .. note::
-
- If you enable the SW based RF kill and then toggle the HW
- based RF kill from ON -> OFF -> ON, the radio will NOT come back on
-
-
-5. Radio Kill Switch
-====================
-
-Most laptops provide the ability for the user to physically disable the radio.
-Some vendors have implemented this as a physical switch that requires no
-software to turn the radio off and on. On other laptops, however, the switch
-is controlled through a button being pressed and a software driver then making
-calls to turn the radio off and on. This is referred to as a "software based
-RF kill switch"
-
-See the Sysfs helper file 'rf_kill' for determining the state of the RF switch
-on your system.
-
-
-6. Dynamic Firmware
-===================
-
-As the firmware is licensed under a restricted use license, it can not be
-included within the kernel sources. To enable the IPW2100 you will need a
-firmware image to load into the wireless NIC's processors.
-
-You can obtain these images from <http://ipw2100.sf.net/firmware.php>.
-
-See INSTALL for instructions on installing the firmware.
-
-
-7. Power Management
-===================
-
-The IPW2100 supports the configuration of the Power Save Protocol
-through a private wireless extension interface. The IPW2100 supports
-the following different modes:
-
- === ===========================================================
- off No power management. Radio is always on.
- on Automatic power management
- 1-5 Different levels of power management. The higher the
- number the greater the power savings, but with an impact to
- packet latencies.
- === ===========================================================
-
-Power management works by powering down the radio after a certain
-interval of time has passed where no packets are passed through the
-radio. Once powered down, the radio remains in that state for a given
-period of time. For higher power savings, the interval between last
-packet processed to sleep is shorter and the sleep period is longer.
-
-When the radio is asleep, the access point sending data to the station
-must buffer packets at the AP until the station wakes up and requests
-any buffered packets. If you have an AP that does not correctly support
-the PSP protocol you may experience packet loss or very poor performance
-while power management is enabled. If this is the case, you will need
-to try and find a firmware update for your AP, or disable power
-management (via ``iwconfig eth1 power off``)
-
-To configure the power level on the IPW2100 you use a combination of
-iwconfig and iwpriv. iwconfig is used to turn power management on, off,
-and set it to auto.
-
- ========================= ====================================
- iwconfig eth1 power off Disables radio power down
- iwconfig eth1 power on Enables radio power management to
- last set level (defaults to AUTO)
- iwpriv eth1 set_power 0 Sets power level to AUTO and enables
- power management if not previously
- enabled.
- iwpriv eth1 set_power 1-5 Set the power level as specified,
- enabling power management if not
- previously enabled.
- ========================= ====================================
-
-You can view the current power level setting via::
-
- iwpriv eth1 get_power
-
-It will return the current period or timeout that is configured as a string
-in the form of xxxx/yyyy (z) where xxxx is the timeout interval (amount of
-time after packet processing), yyyy is the period to sleep (amount of time to
-wait before powering the radio and querying the access point for buffered
-packets), and z is the 'power level'. If power management is turned off the
-xxxx/yyyy will be replaced with 'off' -- the level reported will be the active
-level if `iwconfig eth1 power on` is invoked.
-
-
-8. Support
-==========
-
-For general development information and support,
-go to:
-
- http://ipw2100.sf.net/
-
-The ipw2100 1.1.0 driver and firmware can be downloaded from:
-
- http://support.intel.com
-
-For installation support on the ipw2100 1.1.0 driver on Linux kernels
-2.6.8 or greater, email support is available from:
-
- http://supportmail.intel.com
-
-9. License
-==========
-
- Copyright |copy| 2003 - 2006 Intel Corporation. All rights reserved.
-
- This program is free software; you can redistribute it and/or modify it
- under the terms of the GNU General Public License (version 2) as
- published by the Free Software Foundation.
-
- This program is distributed in the hope that it will be useful, but WITHOUT
- ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
- FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
- more details.
-
- 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., 59
- Temple Place - Suite 330, Boston, MA 02111-1307, USA.
-
- The full GNU General Public License is included in this distribution in the
- file called LICENSE.
-
- License Contact Information:
-
- James P. Ketrenos <ipw2100-admin@linux.intel.com>
-
- Intel Corporation, 5200 N.E. Elam Young Parkway, Hillsboro, OR 97124-6497
-
diff --git a/Documentation/networking/device_drivers/intel/ixgb.rst b/Documentation/networking/device_drivers/intel/ixgb.rst
deleted file mode 100644
index ab624f1..0000000
--- a/Documentation/networking/device_drivers/intel/ixgb.rst
+++ /dev/null
@@ -1,468 +0,0 @@
-.. SPDX-License-Identifier: GPL-2.0+
-
-=====================================================================
-Linux Base Driver for 10 Gigabit Intel(R) Ethernet Network Connection
-=====================================================================
-
-October 1, 2018
-
-
-Contents
-========
-
-- In This Release
-- Identifying Your Adapter
-- Command Line Parameters
-- Improving Performance
-- Additional Configurations
-- Known Issues/Troubleshooting
-- Support
-
-
-
-In This Release
-===============
-
-This file describes the ixgb Linux Base Driver for the 10 Gigabit Intel(R)
-Network Connection. This driver includes support for Itanium(R)2-based
-systems.
-
-For questions related to hardware requirements, refer to the documentation
-supplied with your 10 Gigabit adapter. All hardware requirements listed apply
-to use with Linux.
-
-The following features are available in this kernel:
- - Native VLANs
- - Channel Bonding (teaming)
- - SNMP
-
-Channel Bonding documentation can be found in the Linux kernel source:
-/Documentation/networking/bonding.rst
-
-The driver information previously displayed in the /proc filesystem is not
-supported in this release. Alternatively, you can use ethtool (version 1.6
-or later), lspci, and iproute2 to obtain the same information.
-
-Instructions on updating ethtool can be found in the section "Additional
-Configurations" later in this document.
-
-
-Identifying Your Adapter
-========================
-
-The following Intel network adapters are compatible with the drivers in this
-release:
-
-+------------+------------------------------+----------------------------------+
-| Controller | Adapter Name | Physical Layer |
-+============+==============================+==================================+
-| 82597EX | Intel(R) PRO/10GbE LR/SR/CX4 | - 10G Base-LR (fiber) |
-| | Server Adapters | - 10G Base-SR (fiber) |
-| | | - 10G Base-CX4 (copper) |
-+------------+------------------------------+----------------------------------+
-
-For more information on how to identify your adapter, go to the Adapter &
-Driver ID Guide at:
-
- https://support.intel.com
-
-
-Command Line Parameters
-=======================
-
-If the driver is built as a module, the following optional parameters are
-used by entering them on the command line with the modprobe command using
-this syntax::
-
- modprobe ixgb [<option>=<VAL1>,<VAL2>,...]
-
-For example, with two 10GbE PCI adapters, entering::
-
- modprobe ixgb TxDescriptors=80,128
-
-loads the ixgb driver with 80 TX resources for the first adapter and 128 TX
-resources for the second adapter.
-
-The default value for each parameter is generally the recommended setting,
-unless otherwise noted.
-
-Copybreak
----------
-:Valid Range: 0-XXXX
-:Default Value: 256
-
- This is the maximum size of packet that is copied to a new buffer on
- receive.
-
-Debug
------
-:Valid Range: 0-16 (0=none,...,16=all)
-:Default Value: 0
-
- This parameter adjusts the level of debug messages displayed in the
- system logs.
-
-FlowControl
------------
-:Valid Range: 0-3 (0=none, 1=Rx only, 2=Tx only, 3=Rx&Tx)
-:Default Value: 1 if no EEPROM, otherwise read from EEPROM
-
- This parameter controls the automatic generation(Tx) and response(Rx) to
- Ethernet PAUSE frames. There are hardware bugs associated with enabling
- Tx flow control so beware.
-
-RxDescriptors
--------------
-:Valid Range: 64-4096
-:Default Value: 1024
-
- This value is the number of receive descriptors allocated by the driver.
- Increasing this value allows the driver to buffer more incoming packets.
- Each descriptor is 16 bytes. A receive buffer is also allocated for
- each descriptor and can be either 2048, 4056, 8192, or 16384 bytes,
- depending on the MTU setting. When the MTU size is 1500 or less, the
- receive buffer size is 2048 bytes. When the MTU is greater than 1500 the
- receive buffer size will be either 4056, 8192, or 16384 bytes. The
- maximum MTU size is 16114.
-
-TxDescriptors
--------------
-:Valid Range: 64-4096
-:Default Value: 256
-
- This value is the number of transmit descriptors allocated by the driver.
- Increasing this value allows the driver to queue more transmits. Each
- descriptor is 16 bytes.
-
-RxIntDelay
-----------
-:Valid Range: 0-65535 (0=off)
-:Default Value: 72
-
- This value delays the generation of receive interrupts in units of
- 0.8192 microseconds. Receive interrupt reduction can improve CPU
- efficiency if properly tuned for specific network traffic. Increasing
- this value adds extra latency to frame reception and can end up
- decreasing the throughput of TCP traffic. If the system is reporting
- dropped receives, this value may be set too high, causing the driver to
- run out of available receive descriptors.
-
-TxIntDelay
-----------
-:Valid Range: 0-65535 (0=off)
-:Default Value: 32
-
- This value delays the generation of transmit interrupts in units of
- 0.8192 microseconds. Transmit interrupt reduction can improve CPU
- efficiency if properly tuned for specific network traffic. Increasing
- this value adds extra latency to frame transmission and can end up
- decreasing the throughput of TCP traffic. If this value is set too high,
- it will cause the driver to run out of available transmit descriptors.
-
-XsumRX
-------
-:Valid Range: 0-1
-:Default Value: 1
-
- A value of '1' indicates that the driver should enable IP checksum
- offload for received packets (both UDP and TCP) to the adapter hardware.
-
-RxFCHighThresh
---------------
-:Valid Range: 1,536-262,136 (0x600 - 0x3FFF8, 8 byte granularity)
-:Default Value: 196,608 (0x30000)
-
- Receive Flow control high threshold (when we send a pause frame)
-
-RxFCLowThresh
--------------
-:Valid Range: 64-262,136 (0x40 - 0x3FFF8, 8 byte granularity)
-:Default Value: 163,840 (0x28000)
-
- Receive Flow control low threshold (when we send a resume frame)
-
-FCReqTimeout
-------------
-:Valid Range: 1-65535
-:Default Value: 65535
-
- Flow control request timeout (how long to pause the link partner's tx)
-
-IntDelayEnable
---------------
-:Value Range: 0,1
-:Default Value: 1
-
- Interrupt Delay, 0 disables transmit interrupt delay and 1 enables it.
-
-
-Improving Performance
-=====================
-
-With the 10 Gigabit server adapters, the default Linux configuration will
-very likely limit the total available throughput artificially. There is a set
-of configuration changes that, when applied together, will increase the ability
-of Linux to transmit and receive data. The following enhancements were
-originally acquired from settings published at http://www.spec.org/web99/ for
-various submitted results using Linux.
-
-NOTE:
- These changes are only suggestions, and serve as a starting point for
- tuning your network performance.
-
-The changes are made in three major ways, listed in order of greatest effect:
-
-- Use ip link to modify the mtu (maximum transmission unit) and the txqueuelen
- parameter.
-- Use sysctl to modify /proc parameters (essentially kernel tuning)
-- Use setpci to modify the MMRBC field in PCI-X configuration space to increase
- transmit burst lengths on the bus.
-
-NOTE:
- setpci modifies the adapter's configuration registers to allow it to read
- up to 4k bytes at a time (for transmits). However, for some systems the
- behavior after modifying this register may be undefined (possibly errors of
- some kind). A power-cycle, hard reset or explicitly setting the e6 register
- back to 22 (setpci -d 8086:1a48 e6.b=22) may be required to get back to a
- stable configuration.
-
-- COPY these lines and paste them into ixgb_perf.sh:
-
-::
-
- #!/bin/bash
- echo "configuring network performance , edit this file to change the interface
- or device ID of 10GbE card"
- # set mmrbc to 4k reads, modify only Intel 10GbE device IDs
- # replace 1a48 with appropriate 10GbE device's ID installed on the system,
- # if needed.
- setpci -d 8086:1a48 e6.b=2e
- # set the MTU (max transmission unit) - it requires your switch and clients
- # to change as well.
- # set the txqueuelen
- # your ixgb adapter should be loaded as eth1 for this to work, change if needed
- ip li set dev eth1 mtu 9000 txqueuelen 1000 up
- # call the sysctl utility to modify /proc/sys entries
- sysctl -p ./sysctl_ixgb.conf
-
-- COPY these lines and paste them into sysctl_ixgb.conf:
-
-::
-
- # some of the defaults may be different for your kernel
- # call this file with sysctl -p <this file>
- # these are just suggested values that worked well to increase throughput in
- # several network benchmark tests, your mileage may vary
-
- ### IPV4 specific settings
- # turn TCP timestamp support off, default 1, reduces CPU use
- net.ipv4.tcp_timestamps = 0
- # turn SACK support off, default on
- # on systems with a VERY fast bus -> memory interface this is the big gainer
- net.ipv4.tcp_sack = 0
- # set min/default/max TCP read buffer, default 4096 87380 174760
- net.ipv4.tcp_rmem = 10000000 10000000 10000000
- # set min/pressure/max TCP write buffer, default 4096 16384 131072
- net.ipv4.tcp_wmem = 10000000 10000000 10000000
- # set min/pressure/max TCP buffer space, default 31744 32256 32768
- net.ipv4.tcp_mem = 10000000 10000000 10000000
-
- ### CORE settings (mostly for socket and UDP effect)
- # set maximum receive socket buffer size, default 131071
- net.core.rmem_max = 524287
- # set maximum send socket buffer size, default 131071
- net.core.wmem_max = 524287
- # set default receive socket buffer size, default 65535
- net.core.rmem_default = 524287
- # set default send socket buffer size, default 65535
- net.core.wmem_default = 524287
- # set maximum amount of option memory buffers, default 10240
- net.core.optmem_max = 524287
- # set number of unprocessed input packets before kernel starts dropping them; default 300
- net.core.netdev_max_backlog = 300000
-
-Edit the ixgb_perf.sh script if necessary to change eth1 to whatever interface
-your ixgb driver is using and/or replace '1a48' with appropriate 10GbE device's
-ID installed on the system.
-
-NOTE:
- Unless these scripts are added to the boot process, these changes will
- only last only until the next system reboot.
-
-
-Resolving Slow UDP Traffic
---------------------------
-If your server does not seem to be able to receive UDP traffic as fast as it
-can receive TCP traffic, it could be because Linux, by default, does not set
-the network stack buffers as large as they need to be to support high UDP
-transfer rates. One way to alleviate this problem is to allow more memory to
-be used by the IP stack to store incoming data.
-
-For instance, use the commands::
-
- sysctl -w net.core.rmem_max=262143
-
-and::
-
- sysctl -w net.core.rmem_default=262143
-
-to increase the read buffer memory max and default to 262143 (256k - 1) from
-defaults of max=131071 (128k - 1) and default=65535 (64k - 1). These variables
-will increase the amount of memory used by the network stack for receives, and
-can be increased significantly more if necessary for your application.
-
-
-Additional Configurations
-=========================
-
-Configuring the Driver on Different Distributions
--------------------------------------------------
-Configuring a network driver to load properly when the system is started is
-distribution dependent. Typically, the configuration process involves adding
-an alias line to /etc/modprobe.conf as well as editing other system startup
-scripts and/or configuration files. Many popular Linux distributions ship
-with tools to make these changes for you. To learn the proper way to
-configure a network device for your system, refer to your distribution
-documentation. If during this process you are asked for the driver or module
-name, the name for the Linux Base Driver for the Intel 10GbE Family of
-Adapters is ixgb.
-
-Viewing Link Messages
----------------------
-Link messages will not be displayed to the console if the distribution is
-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
-
-NOTE: This setting is not saved across reboots.
-
-Jumbo Frames
-------------
-The driver supports Jumbo Frames for all adapters. Jumbo Frames support is
-enabled by changing the MTU to a value larger than the default of 1500.
-The maximum value for the MTU is 16114. Use the ip command to
-increase the MTU size. For example::
-
- ip li set dev ethx mtu 9000
-
-The maximum MTU setting for Jumbo Frames is 16114. This value coincides
-with the maximum Jumbo Frames size of 16128.
-
-Ethtool
--------
-The driver utilizes the ethtool interface for driver configuration and
-diagnostics, as well as displaying statistical information. The ethtool
-version 1.6 or later is required for this functionality.
-
-The latest release of ethtool can be found from
-https://www.kernel.org/pub/software/network/ethtool/
-
-NOTE:
- The ethtool version 1.6 only supports a limited set of ethtool options.
- Support for a more complete ethtool feature set can be enabled by
- upgrading to the latest version.
-
-NAPI
-----
-NAPI (Rx polling mode) is supported in the ixgb driver.
-
-See https://wiki.linuxfoundation.org/networking/napi for more information on
-NAPI.
-
-
-Known Issues/Troubleshooting
-============================
-
-NOTE:
- After installing the driver, if your Intel Network Connection is not
- working, verify in the "In This Release" section of the readme that you have
- installed the correct driver.
-
-Cable Interoperability Issue with Fujitsu XENPAK Module in SmartBits Chassis
-----------------------------------------------------------------------------
-Excessive CRC errors may be observed if the Intel(R) PRO/10GbE CX4
-Server adapter is connected to a Fujitsu XENPAK CX4 module in a SmartBits
-chassis using 15 m/24AWG cable assemblies manufactured by Fujitsu or Leoni.
-The CRC errors may be received either by the Intel(R) PRO/10GbE CX4
-Server adapter or the SmartBits. If this situation occurs using a different
-cable assembly may resolve the issue.
-
-Cable Interoperability Issues with HP Procurve 3400cl Switch Port
------------------------------------------------------------------
-Excessive CRC errors may be observed if the Intel(R) PRO/10GbE CX4 Server
-adapter is connected to an HP Procurve 3400cl switch port using short cables
-(1 m or shorter). If this situation occurs, using a longer cable may resolve
-the issue.
-
-Excessive CRC errors may be observed using Fujitsu 24AWG cable assemblies that
-Are 10 m or longer or where using a Leoni 15 m/24AWG cable assembly. The CRC
-errors may be received either by the CX4 Server adapter or at the switch. If
-this situation occurs, using a different cable assembly may resolve the issue.
-
-Jumbo Frames System Requirement
--------------------------------
-Memory allocation failures have been observed on Linux systems with 64 MB
-of RAM or less that are running Jumbo Frames. If you are using Jumbo
-Frames, your system may require more than the advertised minimum
-requirement of 64 MB of system memory.
-
-Performance Degradation with Jumbo Frames
------------------------------------------
-Degradation in throughput performance may be observed in some Jumbo frames
-environments. If this is observed, increasing the application's socket buffer
-size and/or increasing the /proc/sys/net/ipv4/tcp_*mem entry values may help.
-See the specific application manual and /usr/src/linux*/Documentation/
-networking/ip-sysctl.txt for more details.
-
-Allocating Rx Buffers when Using Jumbo Frames
----------------------------------------------
-Allocating Rx buffers when using Jumbo Frames on 2.6.x kernels may fail if
-the available memory is heavily fragmented. This issue may be seen with PCI-X
-adapters or with packet split disabled. This can be reduced or eliminated
-by changing the amount of available memory for receive buffer allocation, by
-increasing /proc/sys/vm/min_free_kbytes.
-
-Multiple Interfaces on Same Ethernet Broadcast Network
-------------------------------------------------------
-Due to the default ARP behavior on Linux, it is not possible to have
-one system on two IP networks in the same Ethernet broadcast domain
-(non-partitioned switch) behave as expected. All Ethernet interfaces
-will respond to IP traffic for any IP address assigned to the system.
-This results in unbalanced receive traffic.
-
-If you have multiple interfaces in a server, do either of the following:
-
- - Turn on ARP filtering by entering::
-
- echo 1 > /proc/sys/net/ipv4/conf/all/arp_filter
-
- - Install the interfaces in separate broadcast domains - either in
- different switches or in a switch partitioned to VLANs.
-
-UDP Stress Test Dropped Packet Issue
---------------------------------------
-Under small packets UDP stress test with 10GbE driver, the Linux system
-may drop UDP packets due to the fullness of socket buffers. You may want
-to change the driver's Flow Control variables to the minimum value for
-controlling packet reception.
-
-Tx Hangs Possible Under Stress
-------------------------------
-Under stress conditions, if TX hangs occur, turning off TSO
-"ethtool -K eth0 tso off" may resolve the problem.
-
-
-Support
-=======
-For general information, go to the Intel support website at:
-
-https://www.intel.com/support/
-
-or the Intel Wired Networking project hosted by Sourceforge at:
-
-https://sourceforge.net/projects/e1000
-
-If an issue is identified with the released source code on a supported kernel
-with a supported adapter, email the specific information related to the issue
-to e1000-devel@lists.sf.net
diff --git a/Documentation/networking/device_drivers/wan/index.rst b/Documentation/networking/device_drivers/wan/index.rst
new file mode 100644
index 0000000..9d9ae94
--- /dev/null
+++ b/Documentation/networking/device_drivers/wan/index.rst
@@ -0,0 +1,18 @@
+.. SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+
+Classic WAN Device Drivers
+==========================
+
+Contents:
+
+.. toctree::
+ :maxdepth: 2
+
+ z8530book
+
+.. only:: subproject and html
+
+ Indices
+ =======
+
+ * :ref:`genindex`
diff --git a/Documentation/networking/z8530book.rst b/Documentation/networking/device_drivers/wan/z8530book.rst
similarity index 100%
rename from Documentation/networking/z8530book.rst
rename to Documentation/networking/device_drivers/wan/z8530book.rst
diff --git a/Documentation/networking/device_drivers/wifi/index.rst b/Documentation/networking/device_drivers/wifi/index.rst
new file mode 100644
index 0000000..bf91a87
--- /dev/null
+++ b/Documentation/networking/device_drivers/wifi/index.rst
@@ -0,0 +1,20 @@
+.. SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+
+Wi-Fi Device Drivers
+====================
+
+Contents:
+
+.. toctree::
+ :maxdepth: 2
+
+ intel/ipw2100
+ intel/ipw2200
+ ray_cs
+
+.. only:: subproject and html
+
+ Indices
+ =======
+
+ * :ref:`genindex`
diff --git a/Documentation/networking/device_drivers/wifi/intel/ipw2100.rst b/Documentation/networking/device_drivers/wifi/intel/ipw2100.rst
new file mode 100644
index 0000000..883e963
--- /dev/null
+++ b/Documentation/networking/device_drivers/wifi/intel/ipw2100.rst
@@ -0,0 +1,323 @@
+.. SPDX-License-Identifier: GPL-2.0
+.. include:: <isonum.txt>
+
+===========================================
+Intel(R) PRO/Wireless 2100 Driver for Linux
+===========================================
+
+Support for:
+
+- Intel(R) PRO/Wireless 2100 Network Connection
+
+Copyright |copy| 2003-2006, Intel Corporation
+
+README.ipw2100
+
+:Version: git-1.1.5
+:Date: January 25, 2006
+
+.. Index
+
+ 0. IMPORTANT INFORMATION BEFORE USING THIS DRIVER
+ 1. Introduction
+ 2. Release git-1.1.5 Current Features
+ 3. Command Line Parameters
+ 4. Sysfs Helper Files
+ 5. Radio Kill Switch
+ 6. Dynamic Firmware
+ 7. Power Management
+ 8. Support
+ 9. License
+
+
+0. IMPORTANT INFORMATION BEFORE USING THIS DRIVER
+=================================================
+
+Important Notice FOR ALL USERS OR DISTRIBUTORS!!!!
+
+Intel wireless LAN adapters are engineered, manufactured, tested, and
+quality checked to ensure that they meet all necessary local and
+governmental regulatory agency requirements for the regions that they
+are designated and/or marked to ship into. Since wireless LANs are
+generally unlicensed devices that share spectrum with radars,
+satellites, and other licensed and unlicensed devices, it is sometimes
+necessary to dynamically detect, avoid, and limit usage to avoid
+interference with these devices. In many instances Intel is required to
+provide test data to prove regional and local compliance to regional and
+governmental regulations before certification or approval to use the
+product is granted. Intel's wireless LAN's EEPROM, firmware, and
+software driver are designed to carefully control parameters that affect
+radio operation and to ensure electromagnetic compliance (EMC). These
+parameters include, without limitation, RF power, spectrum usage,
+channel scanning, and human exposure.
+
+For these reasons Intel cannot permit any manipulation by third parties
+of the software provided in binary format with the wireless WLAN
+adapters (e.g., the EEPROM and firmware). Furthermore, if you use any
+patches, utilities, or code with the Intel wireless LAN adapters that
+have been manipulated by an unauthorized party (i.e., patches,
+utilities, or code (including open source code modifications) which have
+not been validated by Intel), (i) you will be solely responsible for
+ensuring the regulatory compliance of the products, (ii) Intel will bear
+no liability, under any theory of liability for any issues associated
+with the modified products, including without limitation, claims under
+the warranty and/or issues arising from regulatory non-compliance, and
+(iii) Intel will not provide or be required to assist in providing
+support to any third parties for such modified products.
+
+Note: Many regulatory agencies consider Wireless LAN adapters to be
+modules, and accordingly, condition system-level regulatory approval
+upon receipt and review of test data documenting that the antennas and
+system configuration do not cause the EMC and radio operation to be
+non-compliant.
+
+The drivers available for download from SourceForge are provided as a
+part of a development project. Conformance to local regulatory
+requirements is the responsibility of the individual developer. As
+such, if you are interested in deploying or shipping a driver as part of
+solution intended to be used for purposes other than development, please
+obtain a tested driver from Intel Customer Support at:
+
+https://www.intel.com/support/wireless/sb/CS-006408.htm
+
+1. Introduction
+===============
+
+This document provides a brief overview of the features supported by the
+IPW2100 driver project. The main project website, where the latest
+development version of the driver can be found, is:
+
+ http://ipw2100.sourceforge.net
+
+There you can find the not only the latest releases, but also information about
+potential fixes and patches, as well as links to the development mailing list
+for the driver project.
+
+
+2. Release git-1.1.5 Current Supported Features
+===============================================
+
+- Managed (BSS) and Ad-Hoc (IBSS)
+- WEP (shared key and open)
+- Wireless Tools support
+- 802.1x (tested with XSupplicant 1.0.1)
+
+Enabled (but not supported) features:
+- Monitor/RFMon mode
+- WPA/WPA2
+
+The distinction between officially supported and enabled is a reflection
+on the amount of validation and interoperability testing that has been
+performed on a given feature.
+
+
+3. Command Line Parameters
+==========================
+
+If the driver is built as a module, the following optional parameters are used
+by entering them on the command line with the modprobe command using this
+syntax::
+
+ modprobe ipw2100 [<option>=<VAL1><,VAL2>...]
+
+For example, to disable the radio on driver loading, enter:
+
+ modprobe ipw2100 disable=1
+
+The ipw2100 driver supports the following module parameters:
+
+========= ============== ============ ==============================
+Name Value Example Meaning
+========= ============== ============ ==============================
+debug 0x0-0xffffffff debug=1024 Debug level set to 1024
+mode 0,1,2 mode=1 AdHoc
+channel int channel=3 Only valid in AdHoc or Monitor
+associate boolean associate=0 Do NOT auto associate
+disable boolean disable=1 Do not power the HW
+========= ============== ============ ==============================
+
+
+4. Sysfs Helper Files
+=====================
+
+There are several ways to control the behavior of the driver. Many of the
+general capabilities are exposed through the Wireless Tools (iwconfig). There
+are a few capabilities that are exposed through entries in the Linux Sysfs.
+
+
+**Driver Level**
+
+For the driver level files, look in /sys/bus/pci/drivers/ipw2100/
+
+ debug_level
+ This controls the same global as the 'debug' module parameter. For
+ information on the various debugging levels available, run the 'dvals'
+ script found in the driver source directory.
+
+ .. note::
+
+ 'debug_level' is only enabled if CONFIG_IPW2100_DEBUG is turn on.
+
+**Device Level**
+
+For the device level files look in::
+
+ /sys/bus/pci/drivers/ipw2100/{PCI-ID}/
+
+For example::
+
+ /sys/bus/pci/drivers/ipw2100/0000:02:01.0
+
+For the device level files, see /sys/bus/pci/drivers/ipw2100:
+
+ rf_kill
+ read
+
+ == =========================================
+ 0 RF kill not enabled (radio on)
+ 1 SW based RF kill active (radio off)
+ 2 HW based RF kill active (radio off)
+ 3 Both HW and SW RF kill active (radio off)
+ == =========================================
+
+ write
+
+ == ==================================================
+ 0 If SW based RF kill active, turn the radio back on
+ 1 If radio is on, activate SW based RF kill
+ == ==================================================
+
+ .. note::
+
+ If you enable the SW based RF kill and then toggle the HW
+ based RF kill from ON -> OFF -> ON, the radio will NOT come back on
+
+
+5. Radio Kill Switch
+====================
+
+Most laptops provide the ability for the user to physically disable the radio.
+Some vendors have implemented this as a physical switch that requires no
+software to turn the radio off and on. On other laptops, however, the switch
+is controlled through a button being pressed and a software driver then making
+calls to turn the radio off and on. This is referred to as a "software based
+RF kill switch"
+
+See the Sysfs helper file 'rf_kill' for determining the state of the RF switch
+on your system.
+
+
+6. Dynamic Firmware
+===================
+
+As the firmware is licensed under a restricted use license, it can not be
+included within the kernel sources. To enable the IPW2100 you will need a
+firmware image to load into the wireless NIC's processors.
+
+You can obtain these images from <http://ipw2100.sf.net/firmware.php>.
+
+See INSTALL for instructions on installing the firmware.
+
+
+7. Power Management
+===================
+
+The IPW2100 supports the configuration of the Power Save Protocol
+through a private wireless extension interface. The IPW2100 supports
+the following different modes:
+
+ === ===========================================================
+ off No power management. Radio is always on.
+ on Automatic power management
+ 1-5 Different levels of power management. The higher the
+ number the greater the power savings, but with an impact to
+ packet latencies.
+ === ===========================================================
+
+Power management works by powering down the radio after a certain
+interval of time has passed where no packets are passed through the
+radio. Once powered down, the radio remains in that state for a given
+period of time. For higher power savings, the interval between last
+packet processed to sleep is shorter and the sleep period is longer.
+
+When the radio is asleep, the access point sending data to the station
+must buffer packets at the AP until the station wakes up and requests
+any buffered packets. If you have an AP that does not correctly support
+the PSP protocol you may experience packet loss or very poor performance
+while power management is enabled. If this is the case, you will need
+to try and find a firmware update for your AP, or disable power
+management (via ``iwconfig eth1 power off``)
+
+To configure the power level on the IPW2100 you use a combination of
+iwconfig and iwpriv. iwconfig is used to turn power management on, off,
+and set it to auto.
+
+ ========================= ====================================
+ iwconfig eth1 power off Disables radio power down
+ iwconfig eth1 power on Enables radio power management to
+ last set level (defaults to AUTO)
+ iwpriv eth1 set_power 0 Sets power level to AUTO and enables
+ power management if not previously
+ enabled.
+ iwpriv eth1 set_power 1-5 Set the power level as specified,
+ enabling power management if not
+ previously enabled.
+ ========================= ====================================
+
+You can view the current power level setting via::
+
+ iwpriv eth1 get_power
+
+It will return the current period or timeout that is configured as a string
+in the form of xxxx/yyyy (z) where xxxx is the timeout interval (amount of
+time after packet processing), yyyy is the period to sleep (amount of time to
+wait before powering the radio and querying the access point for buffered
+packets), and z is the 'power level'. If power management is turned off the
+xxxx/yyyy will be replaced with 'off' -- the level reported will be the active
+level if `iwconfig eth1 power on` is invoked.
+
+
+8. Support
+==========
+
+For general development information and support,
+go to:
+
+ http://ipw2100.sf.net/
+
+The ipw2100 1.1.0 driver and firmware can be downloaded from:
+
+ http://support.intel.com
+
+For installation support on the ipw2100 1.1.0 driver on Linux kernels
+2.6.8 or greater, email support is available from:
+
+ http://supportmail.intel.com
+
+9. License
+==========
+
+ Copyright |copy| 2003 - 2006 Intel Corporation. All rights reserved.
+
+ This program is free software; you can redistribute it and/or modify it
+ under the terms of the GNU General Public License (version 2) as
+ published by the Free Software Foundation.
+
+ This program is distributed in the hope that it will be useful, but WITHOUT
+ ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
+ more details.
+
+ 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., 59
+ Temple Place - Suite 330, Boston, MA 02111-1307, USA.
+
+ The full GNU General Public License is included in this distribution in the
+ file called LICENSE.
+
+ License Contact Information:
+
+ James P. Ketrenos <ipw2100-admin@linux.intel.com>
+
+ Intel Corporation, 5200 N.E. Elam Young Parkway, Hillsboro, OR 97124-6497
+
diff --git a/Documentation/networking/device_drivers/intel/ipw2200.rst b/Documentation/networking/device_drivers/wifi/intel/ipw2200.rst
similarity index 100%
rename from Documentation/networking/device_drivers/intel/ipw2200.rst
rename to Documentation/networking/device_drivers/wifi/intel/ipw2200.rst
diff --git a/Documentation/networking/ray_cs.rst b/Documentation/networking/device_drivers/wifi/ray_cs.rst
similarity index 100%
rename from Documentation/networking/ray_cs.rst
rename to Documentation/networking/device_drivers/wifi/ray_cs.rst
diff --git a/Documentation/networking/devlink/devlink-info.rst b/Documentation/networking/devlink/devlink-info.rst
index 3fe1140..7572bf6 100644
--- a/Documentation/networking/devlink/devlink-info.rst
+++ b/Documentation/networking/devlink/devlink-info.rst
@@ -44,9 +44,11 @@
reported for two ports of the same device or on two hosts of
a multi-host device should be identical.
- .. note:: ``devlink-info`` API should be extended with a new field
- if devices want to report board/product serial number (often
- reported in PCI *Vital Product Data* capability).
+ * - ``board.serial_number``
+ - Board serial number of the device.
+
+ This is usually the serial number of the board, often available in
+ PCI *Vital Product Data*.
* - ``fixed``
- Group for hardware identifiers, and versions of components
@@ -201,10 +203,6 @@
The following extensions could be useful:
- - product serial number - NIC boards often get labeled with a board serial
- number rather than ASIC serial number; it'd be useful to add board serial
- numbers to the API if they can be retrieved from the device;
-
- on-disk firmware file names - drivers list the file names of firmware they
may need to load onto devices via the ``MODULE_FIRMWARE()`` macro. These,
however, are per module, rather than per device. It'd be useful to list
diff --git a/Documentation/networking/devlink/devlink-trap.rst b/Documentation/networking/devlink/devlink-trap.rst
index 1e3f3ff..7a79835 100644
--- a/Documentation/networking/devlink/devlink-trap.rst
+++ b/Documentation/networking/devlink/devlink-trap.rst
@@ -405,6 +405,10 @@
- ``control``
- Traps packets logged during processing of flow action trap (e.g., via
tc's trap action)
+ * - ``early_drop``
+ - ``drop``
+ - Traps packets dropped due to the RED (Random Early Detection) algorithm
+ (i.e., early drops)
Driver-specific Packet Traps
============================
@@ -486,6 +490,10 @@
- Contains packet traps for packets that should be locally delivered after
routing, but do not match more specific packet traps (e.g.,
``ipv4_bgp``)
+ * - ``external_delivery``
+ - Contains packet traps for packets that should be routed through an
+ external interface (e.g., management interface) that does not belong to
+ the same device (e.g., switch ASIC) as the ingress interface
* - ``ipv6``
- Contains packet traps for various IPv6 control packets (e.g., Router
Advertisements)
diff --git a/Documentation/networking/devlink/ice.rst b/Documentation/networking/devlink/ice.rst
index 72ea8d2..237848d 100644
--- a/Documentation/networking/devlink/ice.rst
+++ b/Documentation/networking/devlink/ice.rst
@@ -84,8 +84,20 @@
Regions
=======
-The ``ice`` driver enables access to the contents of the Non Volatile Memory
-flash chip via the ``nvm-flash`` region.
+The ``ice`` driver implements the following regions for accessing internal
+device data.
+
+.. list-table:: regions implemented
+ :widths: 15 85
+
+ * - Name
+ - Description
+ * - ``nvm-flash``
+ - The contents of the entire flash chip, sometimes referred to as
+ the device's Non Volatile Memory.
+ * - ``device-caps``
+ - The contents of the device firmware's capabilities buffer. Useful to
+ determine the current state and configuration of the device.
Users can request an immediate capture of a snapshot via the
``DEVLINK_CMD_REGION_NEW``
@@ -105,3 +117,42 @@
0000000000000000 0014 95dc 0014 9514 0035 1670 0034 db30
$ devlink region delete pci/0000:01:00.0/nvm-flash snapshot 1
+
+ $ devlink region new pci/0000:01:00.0/device-caps snapshot 1
+ $ devlink region dump pci/0000:01:00.0/device-caps snapshot 1
+ 0000000000000000 01 00 01 00 00 00 00 00 01 00 00 00 00 00 00 00
+ 0000000000000010 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
+ 0000000000000020 02 00 02 01 32 03 00 00 0a 00 00 00 25 00 00 00
+ 0000000000000030 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
+ 0000000000000040 04 00 01 00 01 00 00 00 00 00 00 00 00 00 00 00
+ 0000000000000050 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
+ 0000000000000060 05 00 01 00 03 00 00 00 00 00 00 00 00 00 00 00
+ 0000000000000070 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
+ 0000000000000080 06 00 01 00 01 00 00 00 00 00 00 00 00 00 00 00
+ 0000000000000090 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
+ 00000000000000a0 08 00 01 00 00 00 00 00 00 00 00 00 00 00 00 00
+ 00000000000000b0 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
+ 00000000000000c0 12 00 01 00 01 00 00 00 01 00 01 00 00 00 00 00
+ 00000000000000d0 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
+ 00000000000000e0 13 00 01 00 00 01 00 00 00 00 00 00 00 00 00 00
+ 00000000000000f0 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
+ 0000000000000100 14 00 01 00 01 00 00 00 00 00 00 00 00 00 00 00
+ 0000000000000110 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
+ 0000000000000120 15 00 01 00 01 00 00 00 00 00 00 00 00 00 00 00
+ 0000000000000130 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
+ 0000000000000140 16 00 01 00 01 00 00 00 00 00 00 00 00 00 00 00
+ 0000000000000150 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
+ 0000000000000160 17 00 01 00 06 00 00 00 00 00 00 00 00 00 00 00
+ 0000000000000170 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
+ 0000000000000180 18 00 01 00 01 00 00 00 01 00 00 00 08 00 00 00
+ 0000000000000190 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
+ 00000000000001a0 22 00 01 00 01 00 00 00 00 00 00 00 00 00 00 00
+ 00000000000001b0 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
+ 00000000000001c0 40 00 01 00 00 08 00 00 08 00 00 00 00 00 00 00
+ 00000000000001d0 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
+ 00000000000001e0 41 00 01 00 00 08 00 00 00 00 00 00 00 00 00 00
+ 00000000000001f0 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
+ 0000000000000200 42 00 01 00 00 08 00 00 00 00 00 00 00 00 00 00
+ 0000000000000210 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
+
+ $ devlink region delete pci/0000:01:00.0/device-caps snapshot 1
diff --git a/Documentation/networking/dsa/dsa.rst b/Documentation/networking/dsa/dsa.rst
index 563d56c..a8d15dd 100644
--- a/Documentation/networking/dsa/dsa.rst
+++ b/Documentation/networking/dsa/dsa.rst
@@ -95,7 +95,7 @@
Networking stack hooks
----------------------
-When a master netdev is used with DSA, a small hook is placed in in the
+When a master netdev is used with DSA, a small hook is placed in the
networking stack is in order to have the DSA subsystem process the Ethernet
switch specific tagging protocol. DSA accomplishes this by registering a
specific (and fake) Ethernet type (later becoming ``skb->protocol``) with the
diff --git a/Documentation/networking/ethtool-netlink.rst b/Documentation/networking/ethtool-netlink.rst
index 82470c3..d53bcb3 100644
--- a/Documentation/networking/ethtool-netlink.rst
+++ b/Documentation/networking/ethtool-netlink.rst
@@ -443,10 +443,11 @@
LINKSTATE_GET
=============
-Requests link state information. At the moment, only link up/down flag (as
-provided by ``ETHTOOL_GLINK`` ioctl command) is provided but some future
-extensions are planned (e.g. link down reason). This request does not have any
-attributes.
+Requests link state information. Link up/down flag (as provided by
+``ETHTOOL_GLINK`` ioctl command) is provided. Optionally, extended state might
+be provided as well. In general, extended state describes reasons for why a port
+is down, or why it operates in some non-obvious mode. This request does not have
+any attributes.
Request contents:
@@ -461,16 +462,135 @@
``ETHTOOL_A_LINKSTATE_LINK`` bool link state (up/down)
``ETHTOOL_A_LINKSTATE_SQI`` u32 Current Signal Quality Index
``ETHTOOL_A_LINKSTATE_SQI_MAX`` u32 Max support SQI value
+ ``ETHTOOL_A_LINKSTATE_EXT_STATE`` u8 link extended state
+ ``ETHTOOL_A_LINKSTATE_EXT_SUBSTATE`` u8 link extended substate
==================================== ====== ============================
For most NIC drivers, the value of ``ETHTOOL_A_LINKSTATE_LINK`` returns
carrier flag provided by ``netif_carrier_ok()`` but there are drivers which
define their own handler.
+``ETHTOOL_A_LINKSTATE_EXT_STATE`` and ``ETHTOOL_A_LINKSTATE_EXT_SUBSTATE`` are
+optional values. ethtool core can provide either both
+``ETHTOOL_A_LINKSTATE_EXT_STATE`` and ``ETHTOOL_A_LINKSTATE_EXT_SUBSTATE``,
+or only ``ETHTOOL_A_LINKSTATE_EXT_STATE``, or none of them.
+
``LINKSTATE_GET`` allows dump requests (kernel returns reply messages for all
devices supporting the request).
+Link extended states:
+
+ ================================================ ============================================
+ ``ETHTOOL_LINK_EXT_STATE_AUTONEG`` States relating to the autonegotiation or
+ issues therein
+
+ ``ETHTOOL_LINK_EXT_STATE_LINK_TRAINING_FAILURE`` Failure during link training
+
+ ``ETHTOOL_LINK_EXT_STATE_LINK_LOGICAL_MISMATCH`` Logical mismatch in physical coding sublayer
+ or forward error correction sublayer
+
+ ``ETHTOOL_LINK_EXT_STATE_BAD_SIGNAL_INTEGRITY`` Signal integrity issues
+
+ ``ETHTOOL_LINK_EXT_STATE_NO_CABLE`` No cable connected
+
+ ``ETHTOOL_LINK_EXT_STATE_CABLE_ISSUE`` Failure is related to cable,
+ e.g., unsupported cable
+
+ ``ETHTOOL_LINK_EXT_STATE_EEPROM_ISSUE`` Failure is related to EEPROM, e.g., failure
+ during reading or parsing the data
+
+ ``ETHTOOL_LINK_EXT_STATE_CALIBRATION_FAILURE`` Failure during calibration algorithm
+
+ ``ETHTOOL_LINK_EXT_STATE_POWER_BUDGET_EXCEEDED`` The hardware is not able to provide the
+ power required from cable or module
+
+ ``ETHTOOL_LINK_EXT_STATE_OVERHEAT`` The module is overheated
+ ================================================ ============================================
+
+Link extended substates:
+
+ Autoneg substates:
+
+ =============================================================== ================================
+ ``ETHTOOL_LINK_EXT_SUBSTATE_AN_NO_PARTNER_DETECTED`` Peer side is down
+
+ ``ETHTOOL_LINK_EXT_SUBSTATE_AN_ACK_NOT_RECEIVED`` Ack not received from peer side
+
+ ``ETHTOOL_LINK_EXT_SUBSTATE_AN_NEXT_PAGE_EXCHANGE_FAILED`` Next page exchange failed
+
+ ``ETHTOOL_LINK_EXT_SUBSTATE_AN_NO_PARTNER_DETECTED_FORCE_MODE`` Peer side is down during force
+ mode or there is no agreement of
+ speed
+
+ ``ETHTOOL_LINK_EXT_SUBSTATE_AN_FEC_MISMATCH_DURING_OVERRIDE`` Forward error correction modes
+ in both sides are mismatched
+
+ ``ETHTOOL_LINK_EXT_SUBSTATE_AN_NO_HCD`` No Highest Common Denominator
+ =============================================================== ================================
+
+ Link training substates:
+
+ =========================================================================== ====================
+ ``ETHTOOL_LINK_EXT_SUBSTATE_LT_KR_FRAME_LOCK_NOT_ACQUIRED`` Frames were not
+ recognized, the
+ lock failed
+
+ ``ETHTOOL_LINK_EXT_SUBSTATE_LT_KR_LINK_INHIBIT_TIMEOUT`` The lock did not
+ occur before
+ timeout
+
+ ``ETHTOOL_LINK_EXT_SUBSTATE_LT_KR_LINK_PARTNER_DID_NOT_SET_RECEIVER_READY`` Peer side did not
+ send ready signal
+ after training
+ process
+
+ ``ETHTOOL_LINK_EXT_SUBSTATE_LT_REMOTE_FAULT`` Remote side is not
+ ready yet
+ =========================================================================== ====================
+
+ Link logical mismatch substates:
+
+ ================================================================ ===============================
+ ``ETHTOOL_LINK_EXT_SUBSTATE_LLM_PCS_DID_NOT_ACQUIRE_BLOCK_LOCK`` Physical coding sublayer was
+ not locked in first phase -
+ block lock
+
+ ``ETHTOOL_LINK_EXT_SUBSTATE_LLM_PCS_DID_NOT_ACQUIRE_AM_LOCK`` Physical coding sublayer was
+ not locked in second phase -
+ alignment markers lock
+
+ ``ETHTOOL_LINK_EXT_SUBSTATE_LLM_PCS_DID_NOT_GET_ALIGN_STATUS`` Physical coding sublayer did
+ not get align status
+
+ ``ETHTOOL_LINK_EXT_SUBSTATE_LLM_FC_FEC_IS_NOT_LOCKED`` FC forward error correction is
+ not locked
+
+ ``ETHTOOL_LINK_EXT_SUBSTATE_LLM_RS_FEC_IS_NOT_LOCKED`` RS forward error correction is
+ not locked
+ ================================================================ ===============================
+
+ Bad signal integrity substates:
+
+ ================================================================= =============================
+ ``ETHTOOL_LINK_EXT_SUBSTATE_BSI_LARGE_NUMBER_OF_PHYSICAL_ERRORS`` Large number of physical
+ errors
+
+ ``ETHTOOL_LINK_EXT_SUBSTATE_BSI_UNSUPPORTED_RATE`` The system attempted to
+ operate the cable at a rate
+ that is not formally
+ supported, which led to
+ signal integrity issues
+ ================================================================= =============================
+
+ Cable issue substates:
+
+ =================================================== ============================================
+ ``ETHTOOL_LINK_EXT_SUBSTATE_CI_UNSUPPORTED_CABLE`` Unsupported cable
+
+ ``ETHTOOL_LINK_EXT_SUBSTATE_CI_CABLE_TEST_FAILURE`` Cable test failure
+ =================================================== ============================================
+
DEBUG_GET
=========
@@ -1110,6 +1230,42 @@
| | | ``ETHTOOL_A_CABLE_AMPLITUDE_mV`` | s16 | Reflection amplitude |
+-+-+-----------------------------------------+--------+----------------------+
+TUNNEL_INFO
+===========
+
+Gets information about the tunnel state NIC is aware of.
+
+Request contents:
+
+ ===================================== ====== ==========================
+ ``ETHTOOL_A_TUNNEL_INFO_HEADER`` nested request header
+ ===================================== ====== ==========================
+
+Kernel response contents:
+
+ +---------------------------------------------+--------+---------------------+
+ | ``ETHTOOL_A_TUNNEL_INFO_HEADER`` | nested | reply header |
+ +---------------------------------------------+--------+---------------------+
+ | ``ETHTOOL_A_TUNNEL_INFO_UDP_PORTS`` | nested | all UDP port tables |
+ +-+-------------------------------------------+--------+---------------------+
+ | | ``ETHTOOL_A_TUNNEL_UDP_TABLE`` | nested | one UDP port table |
+ +-+-+-----------------------------------------+--------+---------------------+
+ | | | ``ETHTOOL_A_TUNNEL_UDP_TABLE_SIZE`` | u32 | max size of the |
+ | | | | | table |
+ +-+-+-----------------------------------------+--------+---------------------+
+ | | | ``ETHTOOL_A_TUNNEL_UDP_TABLE_TYPES`` | bitset | tunnel types which |
+ | | | | | table can hold |
+ +-+-+-----------------------------------------+--------+---------------------+
+ | | | ``ETHTOOL_A_TUNNEL_UDP_TABLE_ENTRY`` | nested | offloaded UDP port |
+ +-+-+-+---------------------------------------+--------+---------------------+
+ | | | | ``ETHTOOL_A_TUNNEL_UDP_ENTRY_PORT`` | be16 | UDP port |
+ +-+-+-+---------------------------------------+--------+---------------------+
+ | | | | ``ETHTOOL_A_TUNNEL_UDP_ENTRY_TYPE`` | u32 | tunnel type |
+ +-+-+-+---------------------------------------+--------+---------------------+
+
+For UDP tunnel table empty ``ETHTOOL_A_TUNNEL_UDP_TABLE_TYPES`` indicates that
+the table contains static entries, hard-coded by the NIC.
+
Request translation
===================
diff --git a/Documentation/networking/filter.rst b/Documentation/networking/filter.rst
index a1d3e19..debb59e 100644
--- a/Documentation/networking/filter.rst
+++ b/Documentation/networking/filter.rst
@@ -1,5 +1,7 @@
.. SPDX-License-Identifier: GPL-2.0
+.. _networking-filter:
+
=======================================================
Linux Socket Filtering aka Berkeley Packet Filter (BPF)
=======================================================
diff --git a/Documentation/networking/ieee802154.rst b/Documentation/networking/ieee802154.rst
index 36ca823..6f4bf84 100644
--- a/Documentation/networking/ieee802154.rst
+++ b/Documentation/networking/ieee802154.rst
@@ -30,8 +30,8 @@
The address family, socket addresses etc. are defined in the
include/net/af_ieee802154.h header or in the special header
-in the userspace package (see either http://wpan.cakelab.org/ or the
-git tree at https://github.com/linux-wpan/wpan-tools).
+in the userspace package (see either https://linux-wpan.org/wpan-tools.html
+or the git tree at https://github.com/linux-wpan/wpan-tools).
6LoWPAN Linux implementation
============================
diff --git a/Documentation/networking/index.rst b/Documentation/networking/index.rst
index 0186e27..c29496f 100644
--- a/Documentation/networking/index.rst
+++ b/Documentation/networking/index.rst
@@ -20,7 +20,6 @@
ieee802154
j1939
kapi
- z8530book
msg_zerocopy
failover
net_dim
@@ -39,36 +38,28 @@
nfc
6lowpan
6pack
- altera_tse
arcnet-hardware
arcnet
atm
ax25
- baycom
bonding
cdc_mbim
- cops
- cxacru
dccp
dctcp
decnet
- defza
dns_resolver
driver
eql
fib_trie
filter
- fore200e
framerelay
generic-hdlc
generic_netlink
gen_stats
gtp
- hinic
ila
ipddp
ip_dynaddr
- iphase
ipsec
ip-sysctl
ipv6
@@ -77,7 +68,6 @@
kcm
l2tp
lapb-module
- ltpc
mac80211-injection
mpls-sysctl
multiqueue
@@ -97,14 +87,12 @@
ppp_generic
proc_net_tcp
radiotap-headers
- ray_cs
rds
regulatory
rxrpc
sctp
secid
seg6-sysctl
- skfp
strparser
switchdev
tc-actions-env-rules
@@ -122,7 +110,6 @@
xfrm_proc
xfrm_sync
xfrm_sysctl
- z8530drv
.. only:: subproject and html
diff --git a/Documentation/networking/ip-sysctl.rst b/Documentation/networking/ip-sysctl.rst
index b72f89d..837d51f 100644
--- a/Documentation/networking/ip-sysctl.rst
+++ b/Documentation/networking/ip-sysctl.rst
@@ -741,7 +741,7 @@
Default: 0x1
- Note that that additional client or server features are only
+ Note that additional client or server features are only
effective if the basic support (0x1 and 0x2) are enabled respectively.
tcp_fastopen_blackhole_timeout_sec - INTEGER
diff --git a/Documentation/networking/ipvs-sysctl.rst b/Documentation/networking/ipvs-sysctl.rst
index be36c46..2afccc6 100644
--- a/Documentation/networking/ipvs-sysctl.rst
+++ b/Documentation/networking/ipvs-sysctl.rst
@@ -114,7 +114,7 @@
modes (when there is no enough available memory, the strategy
is enabled and the variable is automatically set to 2,
otherwise the strategy is disabled and the variable is set to
- 1), and 3 means that that the strategy is always enabled.
+ 1), and 3 means that the strategy is always enabled.
drop_packet - INTEGER
- 0 - disabled (default)
diff --git a/Documentation/networking/rxrpc.rst b/Documentation/networking/rxrpc.rst
index 68552b9..39c2249 100644
--- a/Documentation/networking/rxrpc.rst
+++ b/Documentation/networking/rxrpc.rst
@@ -186,7 +186,7 @@
time [tunable] after the last connection using it discarded, in case a new
connection is made that could use it.
- (#) A client-side connection is only shared between calls if they have have
+ (#) A client-side connection is only shared between calls if they have
the same key struct describing their security (and assuming the calls
would otherwise share the connection). Non-secured calls would also be
able to share connections with each other.
diff --git a/Documentation/networking/timestamping.rst b/Documentation/networking/timestamping.rst
index 1adead6..03f7bea 100644
--- a/Documentation/networking/timestamping.rst
+++ b/Documentation/networking/timestamping.rst
@@ -589,3 +589,168 @@
this would occur at a later time in the processing pipeline than other
software time stamping and therefore could lead to unexpected deltas
between time stamps.
+
+3.2 Special considerations for stacked PTP Hardware Clocks
+----------------------------------------------------------
+
+There are situations when there may be more than one PHC (PTP Hardware Clock)
+in the data path of a packet. The kernel has no explicit mechanism to allow the
+user to select which PHC to use for timestamping Ethernet frames. Instead, the
+assumption is that the outermost PHC is always the most preferable, and that
+kernel drivers collaborate towards achieving that goal. Currently there are 3
+cases of stacked PHCs, detailed below:
+
+3.2.1 DSA (Distributed Switch Architecture) switches
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+These are Ethernet switches which have one of their ports connected to an
+(otherwise completely unaware) host Ethernet interface, and perform the role of
+a port multiplier with optional forwarding acceleration features. Each DSA
+switch port is visible to the user as a standalone (virtual) network interface,
+and its network I/O is performed, under the hood, indirectly through the host
+interface (redirecting to the host port on TX, and intercepting frames on RX).
+
+When a DSA switch is attached to a host port, PTP synchronization has to
+suffer, since the switch's variable queuing delay introduces a path delay
+jitter between the host port and its PTP partner. For this reason, some DSA
+switches include a timestamping clock of their own, and have the ability to
+perform network timestamping on their own MAC, such that path delays only
+measure wire and PHY propagation latencies. Timestamping DSA switches are
+supported in Linux and expose the same ABI as any other network interface (save
+for the fact that the DSA interfaces are in fact virtual in terms of network
+I/O, they do have their own PHC). It is typical, but not mandatory, for all
+interfaces of a DSA switch to share the same PHC.
+
+By design, PTP timestamping with a DSA switch does not need any special
+handling in the driver for the host port it is attached to. However, when the
+host port also supports PTP timestamping, DSA will take care of intercepting
+the ``.ndo_do_ioctl`` calls towards the host port, and block attempts to enable
+hardware timestamping on it. This is because the SO_TIMESTAMPING API does not
+allow the delivery of multiple hardware timestamps for the same packet, so
+anybody else except for the DSA switch port must be prevented from doing so.
+
+In code, DSA provides for most of the infrastructure for timestamping already,
+in generic code: a BPF classifier (``ptp_classify_raw``) is used to identify
+PTP event messages (any other packets, including PTP general messages, are not
+timestamped), and provides two hooks to drivers:
+
+- ``.port_txtstamp()``: The driver is passed a clone of the timestampable skb
+ to be transmitted, before actually transmitting it. Typically, a switch will
+ have a PTP TX timestamp register (or sometimes a FIFO) where the timestamp
+ becomes available. There may be an IRQ that is raised upon this timestamp's
+ availability, or the driver might have to poll after invoking
+ ``dev_queue_xmit()`` towards the host interface. Either way, in the
+ ``.port_txtstamp()`` method, the driver only needs to save the clone for
+ later use (when the timestamp becomes available). Each skb is annotated with
+ a pointer to its clone, in ``DSA_SKB_CB(skb)->clone``, to ease the driver's
+ job of keeping track of which clone belongs to which skb.
+
+- ``.port_rxtstamp()``: The original (and only) timestampable skb is provided
+ to the driver, for it to annotate it with a timestamp, if that is immediately
+ available, or defer to later. On reception, timestamps might either be
+ available in-band (through metadata in the DSA header, or attached in other
+ ways to the packet), or out-of-band (through another RX timestamping FIFO).
+ Deferral on RX is typically necessary when retrieving the timestamp needs a
+ sleepable context. In that case, it is the responsibility of the DSA driver
+ to call ``netif_rx_ni()`` on the freshly timestamped skb.
+
+3.2.2 Ethernet PHYs
+^^^^^^^^^^^^^^^^^^^
+
+These are devices that typically fulfill a Layer 1 role in the network stack,
+hence they do not have a representation in terms of a network interface as DSA
+switches do. However, PHYs may be able to detect and timestamp PTP packets, for
+performance reasons: timestamps taken as close as possible to the wire have the
+potential to yield a more stable and precise synchronization.
+
+A PHY driver that supports PTP timestamping must create a ``struct
+mii_timestamper`` and add a pointer to it in ``phydev->mii_ts``. The presence
+of this pointer will be checked by the networking stack.
+
+Since PHYs do not have network interface representations, the timestamping and
+ethtool ioctl operations for them need to be mediated by their respective MAC
+driver. Therefore, as opposed to DSA switches, modifications need to be done
+to each individual MAC driver for PHY timestamping support. This entails:
+
+- Checking, in ``.ndo_do_ioctl``, whether ``phy_has_hwtstamp(netdev->phydev)``
+ is true or not. If it is, then the MAC driver should not process this request
+ but instead pass it on to the PHY using ``phy_mii_ioctl()``.
+
+- On RX, special intervention may or may not be needed, depending on the
+ function used to deliver skb's up the network stack. In the case of plain
+ ``netif_rx()`` and similar, MAC drivers must check whether
+ ``skb_defer_rx_timestamp(skb)`` is necessary or not - and if it is, don't
+ call ``netif_rx()`` at all. If ``CONFIG_NETWORK_PHY_TIMESTAMPING`` is
+ enabled, and ``skb->dev->phydev->mii_ts`` exists, its ``.rxtstamp()`` hook
+ will be called now, to determine, using logic very similar to DSA, whether
+ deferral for RX timestamping is necessary. Again like DSA, it becomes the
+ responsibility of the PHY driver to send the packet up the stack when the
+ timestamp is available.
+
+ For other skb receive functions, such as ``napi_gro_receive`` and
+ ``netif_receive_skb``, the stack automatically checks whether
+ ``skb_defer_rx_timestamp()`` is necessary, so this check is not needed inside
+ the driver.
+
+- On TX, again, special intervention might or might not be needed. The
+ function that calls the ``mii_ts->txtstamp()`` hook is named
+ ``skb_clone_tx_timestamp()``. This function can either be called directly
+ (case in which explicit MAC driver support is indeed needed), but the
+ function also piggybacks from the ``skb_tx_timestamp()`` call, which many MAC
+ drivers already perform for software timestamping purposes. Therefore, if a
+ MAC supports software timestamping, it does not need to do anything further
+ at this stage.
+
+3.2.3 MII bus snooping devices
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+These perform the same role as timestamping Ethernet PHYs, save for the fact
+that they are discrete devices and can therefore be used in conjunction with
+any PHY even if it doesn't support timestamping. In Linux, they are
+discoverable and attachable to a ``struct phy_device`` through Device Tree, and
+for the rest, they use the same mii_ts infrastructure as those. See
+Documentation/devicetree/bindings/ptp/timestamper.txt for more details.
+
+3.2.4 Other caveats for MAC drivers
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Stacked PHCs, especially DSA (but not only) - since that doesn't require any
+modification to MAC drivers, so it is more difficult to ensure correctness of
+all possible code paths - is that they uncover bugs which were impossible to
+trigger before the existence of stacked PTP clocks. One example has to do with
+this line of code, already presented earlier::
+
+ skb_shinfo(skb)->tx_flags |= SKBTX_IN_PROGRESS;
+
+Any TX timestamping logic, be it a plain MAC driver, a DSA switch driver, a PHY
+driver or a MII bus snooping device driver, should set this flag.
+But a MAC driver that is unaware of PHC stacking might get tripped up by
+somebody other than itself setting this flag, and deliver a duplicate
+timestamp.
+For example, a typical driver design for TX timestamping might be to split the
+transmission part into 2 portions:
+
+1. "TX": checks whether PTP timestamping has been previously enabled through
+ the ``.ndo_do_ioctl`` ("``priv->hwtstamp_tx_enabled == true``") and the
+ current skb requires a TX timestamp ("``skb_shinfo(skb)->tx_flags &
+ SKBTX_HW_TSTAMP``"). If this is true, it sets the
+ "``skb_shinfo(skb)->tx_flags |= SKBTX_IN_PROGRESS``" flag. Note: as
+ described above, in the case of a stacked PHC system, this condition should
+ never trigger, as this MAC is certainly not the outermost PHC. But this is
+ not where the typical issue is. Transmission proceeds with this packet.
+
+2. "TX confirmation": Transmission has finished. The driver checks whether it
+ is necessary to collect any TX timestamp for it. Here is where the typical
+ issues are: the MAC driver takes a shortcut and only checks whether
+ "``skb_shinfo(skb)->tx_flags & SKBTX_IN_PROGRESS``" was set. With a stacked
+ PHC system, this is incorrect because this MAC driver is not the only entity
+ in the TX data path who could have enabled SKBTX_IN_PROGRESS in the first
+ place.
+
+The correct solution for this problem is for MAC drivers to have a compound
+check in their "TX confirmation" portion, not only for
+"``skb_shinfo(skb)->tx_flags & SKBTX_IN_PROGRESS``", but also for
+"``priv->hwtstamp_tx_enabled == true``". Because the rest of the system ensures
+that PTP timestamping is not enabled for anything other than the outermost PHC,
+this enhanced check will avoid delivering a duplicated TX timestamp to user
+space.
diff --git a/Documentation/networking/tls-offload.rst b/Documentation/networking/tls-offload.rst
index f914e81..37773da 100644
--- a/Documentation/networking/tls-offload.rst
+++ b/Documentation/networking/tls-offload.rst
@@ -428,6 +428,24 @@
which were part of a TLS stream.
* ``rx_tls_decrypted_bytes`` - number of TLS payload bytes in RX packets
which were successfully decrypted.
+ * ``rx_tls_ctx`` - number of TLS RX HW offload contexts added to device for
+ decryption.
+ * ``rx_tls_del`` - number of TLS RX HW offload contexts deleted from device
+ (connection has finished).
+ * ``rx_tls_resync_req_pkt`` - number of received TLS packets with a resync
+ request.
+ * ``rx_tls_resync_req_start`` - number of times the TLS async resync request
+ was started.
+ * ``rx_tls_resync_req_end`` - number of times the TLS async resync request
+ properly ended with providing the HW tracked tcp-seq.
+ * ``rx_tls_resync_req_skip`` - number of times the TLS async resync request
+ procedure was started by not properly ended.
+ * ``rx_tls_resync_res_ok`` - number of times the TLS resync response call to
+ the driver was successfully handled.
+ * ``rx_tls_resync_res_skip`` - number of times the TLS resync response call to
+ the driver was terminated unsuccessfully.
+ * ``rx_tls_err`` - number of RX packets which were part of a TLS stream
+ but were not decrypted due to unexpected error in the state machine.
* ``tx_tls_encrypted_packets`` - number of TX packets passed to the device
for encryption of their TLS payload.
* ``tx_tls_encrypted_bytes`` - number of TLS payload bytes in TX packets
diff --git a/Documentation/openrisc/openrisc_port.rst b/Documentation/openrisc/openrisc_port.rst
index 4b2c437..657ac4a 100644
--- a/Documentation/openrisc/openrisc_port.rst
+++ b/Documentation/openrisc/openrisc_port.rst
@@ -8,7 +8,7 @@
For information about OpenRISC processors and ongoing development:
======= =============================
- website http://openrisc.io
+ website https://openrisc.io
email openrisc@lists.librecores.org
======= =============================
diff --git a/Documentation/power/energy-model.rst b/Documentation/power/energy-model.rst
index 90a345d..a6fb986a 100644
--- a/Documentation/power/energy-model.rst
+++ b/Documentation/power/energy-model.rst
@@ -1,15 +1,17 @@
-====================
-Energy Model of CPUs
-====================
+.. SPDX-License-Identifier: GPL-2.0
+
+=======================
+Energy Model of devices
+=======================
1. Overview
-----------
The Energy Model (EM) framework serves as an interface between drivers knowing
-the power consumed by CPUs at various performance levels, and the kernel
+the power consumed by devices at various performance levels, and the kernel
subsystems willing to use that information to make energy-aware decisions.
-The source of the information about the power consumed by CPUs can vary greatly
+The source of the information about the power consumed by devices can vary greatly
from one platform to another. These power costs can be estimated using
devicetree data in some cases. In others, the firmware will know better.
Alternatively, userspace might be best positioned. And so on. In order to avoid
@@ -25,7 +27,7 @@
+---------------+ +-----------------+ +---------------+
| Thermal (IPA) | | Scheduler (EAS) | | Other |
+---------------+ +-----------------+ +---------------+
- | | em_pd_energy() |
+ | | em_cpu_energy() |
| | em_cpu_get() |
+---------+ | +---------+
| | |
@@ -35,7 +37,7 @@
| Framework |
+---------------------+
^ ^ ^
- | | | em_register_perf_domain()
+ | | | em_dev_register_perf_domain()
+----------+ | +---------+
| | |
+---------------+ +---------------+ +--------------+
@@ -47,12 +49,12 @@
| Device Tree | | Firmware | | ? |
+--------------+ +---------------+ +--------------+
-The EM framework manages power cost tables per 'performance domain' in the
-system. A performance domain is a group of CPUs whose performance is scaled
-together. Performance domains generally have a 1-to-1 mapping with CPUFreq
-policies. All CPUs in a performance domain are required to have the same
-micro-architecture. CPUs in different performance domains can have different
-micro-architectures.
+In case of CPU devices the EM framework manages power cost tables per
+'performance domain' in the system. A performance domain is a group of CPUs
+whose performance is scaled together. Performance domains generally have a
+1-to-1 mapping with CPUFreq policies. All CPUs in a performance domain are
+required to have the same micro-architecture. CPUs in different performance
+domains can have different micro-architectures.
2. Core APIs
@@ -70,14 +72,16 @@
Drivers are expected to register performance domains into the EM framework by
calling the following API::
- int em_register_perf_domain(cpumask_t *span, unsigned int nr_states,
- struct em_data_callback *cb);
+ int em_dev_register_perf_domain(struct device *dev, unsigned int nr_states,
+ struct em_data_callback *cb, cpumask_t *cpus);
-Drivers must specify the CPUs of the performance domains using the cpumask
-argument, and provide a callback function returning <frequency, power> tuples
-for each capacity state. The callback function provided by the driver is free
+Drivers must provide a callback function returning <frequency, power> tuples
+for each performance state. The callback function provided by the driver is free
to fetch data from any relevant location (DT, firmware, ...), and by any mean
-deemed necessary. See Section 3. for an example of driver implementing this
+deemed necessary. Only for CPU devices, drivers must specify the CPUs of the
+performance domains using cpumask. For other devices than CPUs the last
+argument must be set to NULL.
+See Section 3. for an example of driver implementing this
callback, and kernel/power/energy_model.c for further documentation on this
API.
@@ -85,13 +89,20 @@
2.3 Accessing performance domains
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+There are two API functions which provide the access to the energy model:
+em_cpu_get() which takes CPU id as an argument and em_pd_get() with device
+pointer as an argument. It depends on the subsystem which interface it is
+going to use, but in case of CPU devices both functions return the same
+performance domain.
+
Subsystems interested in the energy model of a CPU can retrieve it using the
em_cpu_get() API. The energy model tables are allocated once upon creation of
the performance domains, and kept in memory untouched.
The energy consumed by a performance domain can be estimated using the
-em_pd_energy() API. The estimation is performed assuming that the schedutil
-CPUfreq governor is in use.
+em_cpu_energy() API. The estimation is performed assuming that the schedutil
+CPUfreq governor is in use in case of CPU device. Currently this calculation is
+not provided for other type of devices.
More details about the above APIs can be found in include/linux/energy_model.h.
@@ -106,42 +117,46 @@
-> drivers/cpufreq/foo_cpufreq.c
- 01 static int est_power(unsigned long *mW, unsigned long *KHz, int cpu)
- 02 {
- 03 long freq, power;
- 04
- 05 /* Use the 'foo' protocol to ceil the frequency */
- 06 freq = foo_get_freq_ceil(cpu, *KHz);
- 07 if (freq < 0);
- 08 return freq;
- 09
- 10 /* Estimate the power cost for the CPU at the relevant freq. */
- 11 power = foo_estimate_power(cpu, freq);
- 12 if (power < 0);
- 13 return power;
- 14
- 15 /* Return the values to the EM framework */
- 16 *mW = power;
- 17 *KHz = freq;
- 18
- 19 return 0;
- 20 }
- 21
- 22 static int foo_cpufreq_init(struct cpufreq_policy *policy)
- 23 {
- 24 struct em_data_callback em_cb = EM_DATA_CB(est_power);
- 25 int nr_opp, ret;
- 26
- 27 /* Do the actual CPUFreq init work ... */
- 28 ret = do_foo_cpufreq_init(policy);
- 29 if (ret)
- 30 return ret;
- 31
- 32 /* Find the number of OPPs for this policy */
- 33 nr_opp = foo_get_nr_opp(policy);
- 34
- 35 /* And register the new performance domain */
- 36 em_register_perf_domain(policy->cpus, nr_opp, &em_cb);
- 37
- 38 return 0;
- 39 }
+ 01 static int est_power(unsigned long *mW, unsigned long *KHz,
+ 02 struct device *dev)
+ 03 {
+ 04 long freq, power;
+ 05
+ 06 /* Use the 'foo' protocol to ceil the frequency */
+ 07 freq = foo_get_freq_ceil(dev, *KHz);
+ 08 if (freq < 0);
+ 09 return freq;
+ 10
+ 11 /* Estimate the power cost for the dev at the relevant freq. */
+ 12 power = foo_estimate_power(dev, freq);
+ 13 if (power < 0);
+ 14 return power;
+ 15
+ 16 /* Return the values to the EM framework */
+ 17 *mW = power;
+ 18 *KHz = freq;
+ 19
+ 20 return 0;
+ 21 }
+ 22
+ 23 static int foo_cpufreq_init(struct cpufreq_policy *policy)
+ 24 {
+ 25 struct em_data_callback em_cb = EM_DATA_CB(est_power);
+ 26 struct device *cpu_dev;
+ 27 int nr_opp, ret;
+ 28
+ 29 cpu_dev = get_cpu_device(cpumask_first(policy->cpus));
+ 30
+ 31 /* Do the actual CPUFreq init work ... */
+ 32 ret = do_foo_cpufreq_init(policy);
+ 33 if (ret)
+ 34 return ret;
+ 35
+ 36 /* Find the number of OPPs for this policy */
+ 37 nr_opp = foo_get_nr_opp(policy);
+ 38
+ 39 /* And register the new performance domain */
+ 40 em_dev_register_perf_domain(cpu_dev, nr_opp, &em_cb, policy->cpus);
+ 41
+ 42 return 0;
+ 43 }
diff --git a/Documentation/power/powercap/powercap.rst b/Documentation/power/powercap/powercap.rst
index 7ae3b44..e75d125 100644
--- a/Documentation/power/powercap/powercap.rst
+++ b/Documentation/power/powercap/powercap.rst
@@ -167,11 +167,13 @@
package-0
---------
-The Intel RAPL technology allows two constraints, short term and long term,
-with two different time windows to be applied to each power zone. Thus for
-each zone there are 2 attributes representing the constraint names, 2 power
-limits and 2 attributes representing the sizes of the time windows. Such that,
-constraint_j_* attributes correspond to the jth constraint (j = 0,1).
+Depending on different power zones, the Intel RAPL technology allows
+one or multiple constraints like short term, long term and peak power,
+with different time windows to be applied to each power zone.
+All the zones contain attributes representing the constraint names,
+power limits and the sizes of the time windows. Note that time window
+is not applicable to peak power. Here, constraint_j_* attributes
+correspond to the jth constraint (j = 0,1,2).
For example::
@@ -181,6 +183,9 @@
constraint_1_name
constraint_1_power_limit_uw
constraint_1_time_window_us
+ constraint_2_name
+ constraint_2_power_limit_uw
+ constraint_2_time_window_us
Power Zone Attributes
=====================
diff --git a/Documentation/powerpc/cpu_families.rst b/Documentation/powerpc/cpu_families.rst
index 1e063c5..9b84e04 100644
--- a/Documentation/powerpc/cpu_families.rst
+++ b/Documentation/powerpc/cpu_families.rst
@@ -9,7 +9,9 @@
Book3S (aka sPAPR)
------------------
-- Hash MMU
+- Hash MMU (except 603 and e300)
+- Software loaded TLB (603 and e300)
+- Selectable Software loaded TLB in addition to hash MMU (755, 7450, e600)
- Mix of 32 & 64 bit::
+--------------+ +----------------+
@@ -24,9 +26,9 @@
| |
| |
v v
- +--------------+ +----------------+ +-------+
- | 604 | | 750 (G3) | ---> | 750CX |
- +--------------+ +----------------+ +-------+
+ +--------------+ +-----+ +----------------+ +-------+
+ | 604 | | 755 | <--- | 750 (G3) | ---> | 750CX |
+ +--------------+ +-----+ +----------------+ +-------+
| | |
| | |
v v v
diff --git a/Documentation/powerpc/index.rst b/Documentation/powerpc/index.rst
index afe2d5e..748bf48 100644
--- a/Documentation/powerpc/index.rst
+++ b/Documentation/powerpc/index.rst
@@ -31,6 +31,7 @@
transactional_memory
ultravisor
vas-api
+ vcpudispatch_stats
.. only:: subproject and html
diff --git a/Documentation/powerpc/mpc52xx.rst b/Documentation/powerpc/mpc52xx.rst
index 8676ac6..3026070 100644
--- a/Documentation/powerpc/mpc52xx.rst
+++ b/Documentation/powerpc/mpc52xx.rst
@@ -2,7 +2,7 @@
Linux 2.6.x on MPC52xx family
=============================
-For the latest info, go to http://www.246tNt.com/mpc52xx/
+For the latest info, go to https://www.246tNt.com/mpc52xx/
To compile/use :
diff --git a/Documentation/powerpc/papr_hcalls.rst b/Documentation/powerpc/papr_hcalls.rst
index 3493631..48fcf12 100644
--- a/Documentation/powerpc/papr_hcalls.rst
+++ b/Documentation/powerpc/papr_hcalls.rst
@@ -220,13 +220,51 @@
**H_SCM_HEALTH**
| Input: drcIndex
-| Out: *health-bitmap, health-bit-valid-bitmap*
+| Out: *health-bitmap (r4), health-bit-valid-bitmap (r5)*
| Return Value: *H_Success, H_Parameter, H_Hardware*
Given a DRC Index return the info on predictive failure and overall health of
-the NVDIMM. The asserted bits in the health-bitmap indicate a single predictive
-failure and health-bit-valid-bitmap indicate which bits in health-bitmap are
-valid.
+the PMEM device. The asserted bits in the health-bitmap indicate one or more states
+(described in table below) of the PMEM device and health-bit-valid-bitmap indicate
+which bits in health-bitmap are valid. The bits are reported in
+reverse bit ordering for example a value of 0xC400000000000000
+indicates bits 0, 1, and 5 are valid.
+
+Health Bitmap Flags:
+
++------+-----------------------------------------------------------------------+
+| Bit | Definition |
++======+=======================================================================+
+| 00 | PMEM device is unable to persist memory contents. |
+| | If the system is powered down, nothing will be saved. |
++------+-----------------------------------------------------------------------+
+| 01 | PMEM device failed to persist memory contents. Either contents were |
+| | not saved successfully on power down or were not restored properly on |
+| | power up. |
++------+-----------------------------------------------------------------------+
+| 02 | PMEM device contents are persisted from previous IPL. The data from |
+| | the last boot were successfully restored. |
++------+-----------------------------------------------------------------------+
+| 03 | PMEM device contents are not persisted from previous IPL. There was no|
+| | data to restore from the last boot. |
++------+-----------------------------------------------------------------------+
+| 04 | PMEM device memory life remaining is critically low |
++------+-----------------------------------------------------------------------+
+| 05 | PMEM device will be garded off next IPL due to failure |
++------+-----------------------------------------------------------------------+
+| 06 | PMEM device contents cannot persist due to current platform health |
+| | status. A hardware failure may prevent data from being saved or |
+| | restored. |
++------+-----------------------------------------------------------------------+
+| 07 | PMEM device is unable to persist memory contents in certain conditions|
++------+-----------------------------------------------------------------------+
+| 08 | PMEM device is encrypted |
++------+-----------------------------------------------------------------------+
+| 09 | PMEM device has successfully completed a requested erase or secure |
+| | erase procedure. |
++------+-----------------------------------------------------------------------+
+|10:63 | Reserved / Unused |
++------+-----------------------------------------------------------------------+
**H_SCM_PERFORMANCE_STATS**
diff --git a/Documentation/powerpc/syscall64-abi.rst b/Documentation/powerpc/syscall64-abi.rst
index e49f69f..46caaad 100644
--- a/Documentation/powerpc/syscall64-abi.rst
+++ b/Documentation/powerpc/syscall64-abi.rst
@@ -5,6 +5,15 @@
syscall
=======
+Invocation
+----------
+The syscall is made with the sc instruction, and returns with execution
+continuing at the instruction following the sc instruction.
+
+If PPC_FEATURE2_SCV appears in the AT_HWCAP2 ELF auxiliary vector, the
+scv 0 instruction is an alternative that may provide better performance,
+with some differences to calling sequence.
+
syscall calling sequence\ [1]_ matches the Power Architecture 64-bit ELF ABI
specification C function calling sequence, including register preservation
rules, with the following differences.
@@ -12,16 +21,23 @@
.. [1] Some syscalls (typically low-level management functions) may have
different calling sequences (e.g., rt_sigreturn).
-Parameters and return value
----------------------------
+Parameters
+----------
The system call number is specified in r0.
There is a maximum of 6 integer parameters to a syscall, passed in r3-r8.
-Both a return value and a return error code are returned. cr0.SO is the return
-error code, and r3 is the return value or error code. When cr0.SO is clear,
-the syscall succeeded and r3 is the return value. When cr0.SO is set, the
-syscall failed and r3 is the error code that generally corresponds to errno.
+Return value
+------------
+- For the sc instruction, both a value and an error condition are returned.
+ cr0.SO is the error condition, and r3 is the return value. When cr0.SO is
+ clear, the syscall succeeded and r3 is the return value. When cr0.SO is set,
+ the syscall failed and r3 is the error value (that normally corresponds to
+ errno).
+
+- For the scv 0 instruction, the return value indicates failure if it is
+ -4095..-1 (i.e., it is >= -MAX_ERRNO (-4095) as an unsigned comparison),
+ in which case the error value is the negated return value.
Stack
-----
@@ -34,22 +50,23 @@
following differences:
=========== ============= ========================================
+--- For the sc instruction, differences with the ELF ABI ---
r0 Volatile (System call number.)
r3 Volatile (Parameter 1, and return value.)
r4-r8 Volatile (Parameters 2-6.)
-cr0 Volatile (cr0.SO is the return error condition)
+cr0 Volatile (cr0.SO is the return error condition.)
cr1, cr5-7 Nonvolatile
lr Nonvolatile
+
+--- For the scv 0 instruction, differences with the ELF ABI ---
+r0 Volatile (System call number.)
+r3 Volatile (Parameter 1, and return value.)
+r4-r8 Volatile (Parameters 2-6.)
=========== ============= ========================================
All floating point and vector data registers as well as control and status
registers are nonvolatile.
-Invocation
-----------
-The syscall is performed with the sc instruction, and returns with execution
-continuing at the instruction following the sc instruction.
-
Transactional Memory
--------------------
Syscall behavior can change if the processor is in transactional or suspended
@@ -75,6 +92,7 @@
returning to the caller. This case is not well defined or supported, so this
behavior should not be relied upon.
+scv 0 syscalls will always behave as PPC_FEATURE2_HTM_NOSC.
vsyscall
========
diff --git a/Documentation/powerpc/ultravisor.rst b/Documentation/powerpc/ultravisor.rst
index df136c8..ba6b1bf 100644
--- a/Documentation/powerpc/ultravisor.rst
+++ b/Documentation/powerpc/ultravisor.rst
@@ -895,6 +895,7 @@
One of the following values:
* H_SUCCESS on success.
+ * H_STATE if the VM is not in a position to switch to secure.
Description
~~~~~~~~~~~
@@ -933,6 +934,8 @@
* H_UNSUPPORTED if called from the wrong context (e.g.
from an SVM or before an H_SVM_INIT_START
hypercall).
+ * H_STATE if the hypervisor could not successfully
+ transition the VM to Secure VM.
Description
~~~~~~~~~~~
diff --git a/Documentation/powerpc/vas-api.rst b/Documentation/powerpc/vas-api.rst
index 1217c2f..90c50ed 100644
--- a/Documentation/powerpc/vas-api.rst
+++ b/Documentation/powerpc/vas-api.rst
@@ -43,7 +43,7 @@
should use the mmap() system call to map the hardware address of engine's
request queue into the application's virtual address space.
-The application can then submit one or more requests to the the engine by
+The application can then submit one or more requests to the engine by
using copy/paste instructions and pasting the CRBs to the virtual address
(aka paste_address) returned by mmap(). User space can close the
established connection or send window by closing the file descriptior
@@ -87,6 +87,7 @@
the vas_id field in the VAS_TX_WIN_OPEN ioctl as detailed below.
A userspace library libnxz is available here but still in development:
+
https://github.com/abalib/power-gzip
Applications that use inflate / deflate calls can link with libnxz
@@ -110,6 +111,7 @@
a connection with NX co-processor engine:
::
+
struct vas_tx_win_open_attr {
__u32 version;
__s16 vas_id; /* specific instance of vas or -1
@@ -119,8 +121,10 @@
__u64 reserved2[6];
};
- version: The version field must be currently set to 1.
- vas_id: If '-1' is passed, kernel will make a best-effort attempt
+ version:
+ The version field must be currently set to 1.
+ vas_id:
+ If '-1' is passed, kernel will make a best-effort attempt
to assign an optimal instance of NX for the process. To
select the specific VAS instance, refer
"Discovery of available VAS engines" section below.
@@ -129,7 +133,8 @@
and must be set to 0.
The attributes attr for the VAS_TX_WIN_OPEN ioctl are defined as
- follows:
+ follows::
+
#define VAS_MAGIC 'v'
#define VAS_TX_WIN_OPEN _IOW(VAS_MAGIC, 1,
struct vas_tx_win_open_attr)
@@ -141,6 +146,8 @@
returns -1 and sets the errno variable to indicate the error.
Error conditions:
+
+ ====== ================================================
EINVAL fd does not refer to a valid VAS device.
EINVAL Invalid vas ID
EINVAL version is not set with proper value
@@ -149,6 +156,7 @@
ENOSPC System has too many active windows (connections)
opened
EINVAL reserved fields are not set to 0.
+ ====== ================================================
See the ioctl(2) man page for more details, error codes and
restrictions.
@@ -158,11 +166,13 @@
The mmap() system call for a NX-GZIP device fd returns a paste_address
that the application can use to copy/paste its CRB to the hardware engines.
+
::
paste_addr = mmap(addr, size, prot, flags, fd, offset);
Only restrictions on mmap for a NX-GZIP device fd are:
+
* size should be PAGE_SIZE
* offset parameter should be 0ULL
@@ -170,10 +180,12 @@
In addition to the error conditions listed on the mmap(2) man
page, can also fail with one of the following error codes:
+ ====== =============================================
EINVAL fd is not associated with an open window
(i.e mmap() does not follow a successful call
to the VAS_TX_WIN_OPEN ioctl).
EINVAL offset field is not 0ULL.
+ ====== =============================================
Discovery of available VAS engines
==================================
@@ -210,10 +222,10 @@
address or any request buffer, raises an interrupt on the CPU to handle the
fault. Page fault can happen if an application passes invalid addresses or
request buffers are not in memory. The operating system handles the fault by
-updating CSB with the following data:
+updating CSB with the following data::
csb.flags = CSB_V;
- csb.cc = CSB_CC_TRANSLATION;
+ csb.cc = CSB_CC_FAULT_ADDRESS;
csb.ce = CSB_CE_TERMINATION;
csb.address = fault_address;
@@ -223,7 +235,7 @@
If the OS can not update CSB due to invalid CSB address, sends SEGV signal
to the process who opened the send window on which the original request was
-issued. This signal returns with the following siginfo struct:
+issued. This signal returns with the following siginfo struct::
siginfo.si_signo = SIGSEGV;
siginfo.si_errno = EFAULT;
@@ -248,6 +260,7 @@
==============
::
+
int use_nx_gzip()
{
int rc, fd;
diff --git a/Documentation/powerpc/vcpudispatch_stats.rst b/Documentation/powerpc/vcpudispatch_stats.rst
new file mode 100644
index 0000000..5704657
--- /dev/null
+++ b/Documentation/powerpc/vcpudispatch_stats.rst
@@ -0,0 +1,75 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+========================
+VCPU Dispatch Statistics
+========================
+
+For Shared Processor LPARs, the POWER Hypervisor maintains a relatively
+static mapping of the LPAR processors (vcpus) to physical processor
+chips (representing the "home" node) and tries to always dispatch vcpus
+on their associated physical processor chip. However, under certain
+scenarios, vcpus may be dispatched on a different processor chip (away
+from its home node).
+
+/proc/powerpc/vcpudispatch_stats can be used to obtain statistics
+related to the vcpu dispatch behavior. Writing '1' to this file enables
+collecting the statistics, while writing '0' disables the statistics.
+By default, the DTLB log for each vcpu is processed 50 times a second so
+as not to miss any entries. This processing frequency can be changed
+through /proc/powerpc/vcpudispatch_stats_freq.
+
+The statistics themselves are available by reading the procfs file
+/proc/powerpc/vcpudispatch_stats. Each line in the output corresponds to
+a vcpu as represented by the first field, followed by 8 numbers.
+
+The first number corresponds to:
+
+1. total vcpu dispatches since the beginning of statistics collection
+
+The next 4 numbers represent vcpu dispatch dispersions:
+
+2. number of times this vcpu was dispatched on the same processor as last
+ time
+3. number of times this vcpu was dispatched on a different processor core
+ as last time, but within the same chip
+4. number of times this vcpu was dispatched on a different chip
+5. number of times this vcpu was dispatches on a different socket/drawer
+ (next numa boundary)
+
+The final 3 numbers represent statistics in relation to the home node of
+the vcpu:
+
+6. number of times this vcpu was dispatched in its home node (chip)
+7. number of times this vcpu was dispatched in a different node
+8. number of times this vcpu was dispatched in a node further away (numa
+ distance)
+
+An example output::
+
+ $ sudo cat /proc/powerpc/vcpudispatch_stats
+ cpu0 6839 4126 2683 30 0 6821 18 0
+ cpu1 2515 1274 1229 12 0 2509 6 0
+ cpu2 2317 1198 1109 10 0 2312 5 0
+ cpu3 2259 1165 1088 6 0 2256 3 0
+ cpu4 2205 1143 1056 6 0 2202 3 0
+ cpu5 2165 1121 1038 6 0 2162 3 0
+ cpu6 2183 1127 1050 6 0 2180 3 0
+ cpu7 2193 1133 1052 8 0 2187 6 0
+ cpu8 2165 1115 1032 18 0 2156 9 0
+ cpu9 2301 1252 1033 16 0 2293 8 0
+ cpu10 2197 1138 1041 18 0 2187 10 0
+ cpu11 2273 1185 1062 26 0 2260 13 0
+ cpu12 2186 1125 1043 18 0 2177 9 0
+ cpu13 2161 1115 1030 16 0 2153 8 0
+ cpu14 2206 1153 1033 20 0 2196 10 0
+ cpu15 2163 1115 1032 16 0 2155 8 0
+
+In the output above, for vcpu0, there have been 6839 dispatches since
+statistics were enabled. 4126 of those dispatches were on the same
+physical cpu as the last time. 2683 were on a different core, but within
+the same chip, while 30 dispatches were on a different chip compared to
+its last dispatch.
+
+Also, out of the total of 6839 dispatches, we see that there have been
+6821 dispatches on the vcpu's home node, while 18 dispatches were
+outside its home node, on a neighbouring chip.
diff --git a/Documentation/powerpc/vcpudispatch_stats.txt b/Documentation/powerpc/vcpudispatch_stats.txt
deleted file mode 100644
index e21476b..0000000
--- a/Documentation/powerpc/vcpudispatch_stats.txt
+++ /dev/null
@@ -1,68 +0,0 @@
-VCPU Dispatch Statistics:
-=========================
-
-For Shared Processor LPARs, the POWER Hypervisor maintains a relatively
-static mapping of the LPAR processors (vcpus) to physical processor
-chips (representing the "home" node) and tries to always dispatch vcpus
-on their associated physical processor chip. However, under certain
-scenarios, vcpus may be dispatched on a different processor chip (away
-from its home node).
-
-/proc/powerpc/vcpudispatch_stats can be used to obtain statistics
-related to the vcpu dispatch behavior. Writing '1' to this file enables
-collecting the statistics, while writing '0' disables the statistics.
-By default, the DTLB log for each vcpu is processed 50 times a second so
-as not to miss any entries. This processing frequency can be changed
-through /proc/powerpc/vcpudispatch_stats_freq.
-
-The statistics themselves are available by reading the procfs file
-/proc/powerpc/vcpudispatch_stats. Each line in the output corresponds to
-a vcpu as represented by the first field, followed by 8 numbers.
-
-The first number corresponds to:
-1. total vcpu dispatches since the beginning of statistics collection
-
-The next 4 numbers represent vcpu dispatch dispersions:
-2. number of times this vcpu was dispatched on the same processor as last
- time
-3. number of times this vcpu was dispatched on a different processor core
- as last time, but within the same chip
-4. number of times this vcpu was dispatched on a different chip
-5. number of times this vcpu was dispatches on a different socket/drawer
-(next numa boundary)
-
-The final 3 numbers represent statistics in relation to the home node of
-the vcpu:
-6. number of times this vcpu was dispatched in its home node (chip)
-7. number of times this vcpu was dispatched in a different node
-8. number of times this vcpu was dispatched in a node further away (numa
-distance)
-
-An example output:
- $ sudo cat /proc/powerpc/vcpudispatch_stats
- cpu0 6839 4126 2683 30 0 6821 18 0
- cpu1 2515 1274 1229 12 0 2509 6 0
- cpu2 2317 1198 1109 10 0 2312 5 0
- cpu3 2259 1165 1088 6 0 2256 3 0
- cpu4 2205 1143 1056 6 0 2202 3 0
- cpu5 2165 1121 1038 6 0 2162 3 0
- cpu6 2183 1127 1050 6 0 2180 3 0
- cpu7 2193 1133 1052 8 0 2187 6 0
- cpu8 2165 1115 1032 18 0 2156 9 0
- cpu9 2301 1252 1033 16 0 2293 8 0
- cpu10 2197 1138 1041 18 0 2187 10 0
- cpu11 2273 1185 1062 26 0 2260 13 0
- cpu12 2186 1125 1043 18 0 2177 9 0
- cpu13 2161 1115 1030 16 0 2153 8 0
- cpu14 2206 1153 1033 20 0 2196 10 0
- cpu15 2163 1115 1032 16 0 2155 8 0
-
-In the output above, for vcpu0, there have been 6839 dispatches since
-statistics were enabled. 4126 of those dispatches were on the same
-physical cpu as the last time. 2683 were on a different core, but within
-the same chip, while 30 dispatches were on a different chip compared to
-its last dispatch.
-
-Also, out of the total of 6839 dispatches, we see that there have been
-6821 dispatches on the vcpu's home node, while 18 dispatches were
-outside its home node, on a neighbouring chip.
diff --git a/Documentation/process/2.Process.rst b/Documentation/process/2.Process.rst
index b21b5b24..4ae1e0f 100644
--- a/Documentation/process/2.Process.rst
+++ b/Documentation/process/2.Process.rst
@@ -113,7 +113,7 @@
5.2 kernel's history looked like this (all dates in 2019):
============== ===============================
- September 15 5.2 stable release
+ July 7 5.2 stable release
July 14 5.2.1
July 21 5.2.2
July 26 5.2.3
@@ -295,7 +295,7 @@
The current -mm patch is available in the "mmotm" (-mm of the moment)
directory at:
- http://www.ozlabs.org/~akpm/mmotm/
+ https://www.ozlabs.org/~akpm/mmotm/
Use of the MMOTM tree is likely to be a frustrating experience, though;
there is a definite chance that it will not even compile.
@@ -306,7 +306,7 @@
Linux-next trees are announced on the linux-kernel and linux-next mailing
lists when they are assembled; they can be downloaded from:
- http://www.kernel.org/pub/linux/kernel/next/
+ https://www.kernel.org/pub/linux/kernel/next/
Linux-next has become an integral part of the kernel development process;
all patches merged during a given merge window should really have found
@@ -365,21 +365,21 @@
Git is now packaged by almost all Linux distributions. There is a home
page at:
- http://git-scm.com/
+ https://git-scm.com/
That page has pointers to documentation and tutorials.
Among the kernel developers who do not use git, the most popular choice is
almost certainly Mercurial:
- http://www.selenic.com/mercurial/
+ https://www.selenic.com/mercurial/
Mercurial shares many features with git, but it provides an interface which
many find easier to use.
The other tool worth knowing about is Quilt:
- http://savannah.nongnu.org/projects/quilt/
+ https://savannah.nongnu.org/projects/quilt/
Quilt is a patch management system, rather than a source code management
system. It does not track history over time; it is, instead, oriented
@@ -494,7 +494,7 @@
with others on getting things fixed up (this can require
persistence!) but that's fine - it's a part of kernel development.
-(http://lwn.net/Articles/283982/).
+(https://lwn.net/Articles/283982/).
In the absence of obvious problems to fix, developers are advised to look
at the current lists of regressions and open bugs in general. There is
diff --git a/Documentation/process/4.Coding.rst b/Documentation/process/4.Coding.rst
index 13dd893..c27e59d 100644
--- a/Documentation/process/4.Coding.rst
+++ b/Documentation/process/4.Coding.rst
@@ -210,7 +210,7 @@
progress at all. Is it two steps forwards, one step back, or one
step forward and two steps back?
-(http://lwn.net/Articles/243460/).
+(https://lwn.net/Articles/243460/).
An especially unwelcome type of regression is any sort of change to the
user-space ABI. Once an interface has been exported to user space, it must
@@ -323,7 +323,7 @@
Blackfin development board handy, you can still perform the compilation
step. A large set of cross compilers for x86 systems can be found at
- http://www.kernel.org/pub/tools/crosstool/
+ https://www.kernel.org/pub/tools/crosstool/
Some time spent installing and using these compilers will help avoid
embarrassment later.
diff --git a/Documentation/process/botching-up-ioctls.rst b/Documentation/process/botching-up-ioctls.rst
index 2d4829b..ba4667a 100644
--- a/Documentation/process/botching-up-ioctls.rst
+++ b/Documentation/process/botching-up-ioctls.rst
@@ -2,7 +2,7 @@
(How to avoid) Botching up ioctls
=================================
-From: http://blog.ffwll.ch/2013/11/botching-up-ioctls.html
+From: https://blog.ffwll.ch/2013/11/botching-up-ioctls.html
By: Daniel Vetter, Copyright © 2013 Intel Corporation
diff --git a/Documentation/process/changes.rst b/Documentation/process/changes.rst
index 5cfb54c..ee74176 100644
--- a/Documentation/process/changes.rst
+++ b/Documentation/process/changes.rst
@@ -29,7 +29,7 @@
====================== =============== ========================================
Program Minimal version Command to check the version
====================== =============== ========================================
-GNU C 4.8 gcc --version
+GNU C 4.9 gcc --version
GNU make 3.81 make --version
binutils 2.23 ld -v
flex 2.5.35 flex --version
@@ -129,7 +129,7 @@
---------------------
DevFS has been obsoleted in favour of udev
-(http://www.kernel.org/pub/linux/utils/kernel/hotplug/)
+(https://www.kernel.org/pub/linux/utils/kernel/hotplug/)
32-bit UID support is now in place. Have fun!
@@ -421,7 +421,7 @@
udev
----
-- <http://www.freedesktop.org/software/systemd/man/udev.html>
+- <https://www.freedesktop.org/software/systemd/man/udev.html>
FUSE
----
@@ -474,4 +474,4 @@
Sphinx
------
-- <http://www.sphinx-doc.org/>
+- <https://www.sphinx-doc.org/>
diff --git a/Documentation/process/clang-format.rst b/Documentation/process/clang-format.rst
index 6710c07..82676e5 100644
--- a/Documentation/process/clang-format.rst
+++ b/Documentation/process/clang-format.rst
@@ -32,7 +32,7 @@
your repositories. Otherwise, you can either download pre-built
LLVM/clang binaries or build the source code from:
- http://releases.llvm.org/download.html
+ https://releases.llvm.org/download.html
See more information about the tool at:
diff --git a/Documentation/process/coding-style.rst b/Documentation/process/coding-style.rst
index 2657a55..9822722 100644
--- a/Documentation/process/coding-style.rst
+++ b/Documentation/process/coding-style.rst
@@ -319,6 +319,26 @@
problem, which is called the function-growth-hormone-imbalance syndrome.
See chapter 6 (Functions).
+For symbol names and documentation, avoid introducing new usage of
+'master / slave' (or 'slave' independent of 'master') and 'blacklist /
+whitelist'.
+
+Recommended replacements for 'master / slave' are:
+ '{primary,main} / {secondary,replica,subordinate}'
+ '{initiator,requester} / {target,responder}'
+ '{controller,host} / {device,worker,proxy}'
+ 'leader / follower'
+ 'director / performer'
+
+Recommended replacements for 'blacklist/whitelist' are:
+ 'denylist / allowlist'
+ 'blocklist / passlist'
+
+Exceptions for introducing new usage is to maintain a userspace ABI/API,
+or when updating code for an existing (as of 2020) hardware or protocol
+specification that mandates those terms. For new specifications
+translate specification usage of the terminology to the kernel coding
+standard where possible.
5) Typedefs
-----------
@@ -1129,7 +1149,7 @@
ISBN 0-201-61586-X.
GNU manuals - where in compliance with K&R and this text - for cpp, gcc,
-gcc internals and indent, all available from http://www.gnu.org/manual/
+gcc internals and indent, all available from https://www.gnu.org/manual/
WG14 is the international standardization working group for the programming
language C, URL: http://www.open-std.org/JTC1/SC22/WG14/
diff --git a/Documentation/process/deprecated.rst b/Documentation/process/deprecated.rst
index 652e2aa..4a9aa4f 100644
--- a/Documentation/process/deprecated.rst
+++ b/Documentation/process/deprecated.rst
@@ -51,6 +51,24 @@
"unreachable" conditions. (For example, see commits like `this one
<https://git.kernel.org/linus/d4689846881d160a4d12a514e991a740bcb5d65a>`_.)
+uninitialized_var()
+-------------------
+For any compiler warnings about uninitialized variables, just add
+an initializer. Using the uninitialized_var() macro (or similar
+warning-silencing tricks) is dangerous as it papers over `real bugs
+<https://lore.kernel.org/lkml/20200603174714.192027-1-glider@google.com/>`_
+(or can in the future), and suppresses unrelated compiler warnings
+(e.g. "unused variable"). If the compiler thinks it is uninitialized,
+either simply initialize the variable or make compiler changes. Keep in
+mind that in most cases, if an initialization is obviously redundant,
+the compiler's dead-store elimination pass will make sure there are no
+needless variable writes.
+
+As Linus has said, this macro
+`must <https://lore.kernel.org/lkml/CA+55aFw+Vbj0i=1TGqCR5vQkCzWJ0QxK6CernOU6eedsudAixw@mail.gmail.com/>`_
+`be <https://lore.kernel.org/lkml/CA+55aFwgbgqhbp1fkxvRKEpzyR5J8n1vKT1VZdz9knmPuXhOeg@mail.gmail.com/>`_
+`removed <https://lore.kernel.org/lkml/CA+55aFz2500WfbKXAx8s67wrm9=yVJu65TpLgN_ybYNv0VEOKA@mail.gmail.com/>`_.
+
open-coded arithmetic in allocator arguments
--------------------------------------------
Dynamic size calculations (especially multiplication) should not be
@@ -85,6 +103,11 @@
header = kzalloc(struct_size(header, item, count), GFP_KERNEL);
+.. note:: If you are using struct_size() on a structure containing a zero-length
+ or a one-element array as a trailing array member, please refactor such
+ array usage and switch to a `flexible array member
+ <#zero-length-and-one-element-arrays>`_ instead.
+
See array_size(), array3_size(), and struct_size(),
for more details as well as the related check_add_overflow() and
check_mul_overflow() family of functions.
@@ -200,3 +223,116 @@
* continue;
* goto <label>;
* return [expression];
+
+Zero-length and one-element arrays
+----------------------------------
+There is a regular need in the kernel to provide a way to declare having
+a dynamically sized set of trailing elements in a structure. Kernel code
+should always use `"flexible array members" <https://en.wikipedia.org/wiki/Flexible_array_member>`_
+for these cases. The older style of one-element or zero-length arrays should
+no longer be used.
+
+In older C code, dynamically sized trailing elements were done by specifying
+a one-element array at the end of a structure::
+
+ struct something {
+ size_t count;
+ struct foo items[1];
+ };
+
+This led to fragile size calculations via sizeof() (which would need to
+remove the size of the single trailing element to get a correct size of
+the "header"). A `GNU C extension <https://gcc.gnu.org/onlinedocs/gcc/Zero-Length.html>`_
+was introduced to allow for zero-length arrays, to avoid these kinds of
+size problems::
+
+ struct something {
+ size_t count;
+ struct foo items[0];
+ };
+
+But this led to other problems, and didn't solve some problems shared by
+both styles, like not being able to detect when such an array is accidentally
+being used _not_ at the end of a structure (which could happen directly, or
+when such a struct was in unions, structs of structs, etc).
+
+C99 introduced "flexible array members", which lacks a numeric size for
+the array declaration entirely::
+
+ struct something {
+ size_t count;
+ struct foo items[];
+ };
+
+This is the way the kernel expects dynamically sized trailing elements
+to be declared. It allows the compiler to generate errors when the
+flexible array does not occur last in the structure, which helps to prevent
+some kind of `undefined behavior
+<https://git.kernel.org/linus/76497732932f15e7323dc805e8ea8dc11bb587cf>`_
+bugs from being inadvertently introduced to the codebase. It also allows
+the compiler to correctly analyze array sizes (via sizeof(),
+`CONFIG_FORTIFY_SOURCE`, and `CONFIG_UBSAN_BOUNDS`). For instance,
+there is no mechanism that warns us that the following application of the
+sizeof() operator to a zero-length array always results in zero::
+
+ struct something {
+ size_t count;
+ struct foo items[0];
+ };
+
+ struct something *instance;
+
+ instance = kmalloc(struct_size(instance, items, count), GFP_KERNEL);
+ instance->count = count;
+
+ size = sizeof(instance->items) * instance->count;
+ memcpy(instance->items, source, size);
+
+At the last line of code above, ``size`` turns out to be ``zero``, when one might
+have thought it represents the total size in bytes of the dynamic memory recently
+allocated for the trailing array ``items``. Here are a couple examples of this
+issue: `link 1
+<https://git.kernel.org/linus/f2cd32a443da694ac4e28fbf4ac6f9d5cc63a539>`_,
+`link 2
+<https://git.kernel.org/linus/ab91c2a89f86be2898cee208d492816ec238b2cf>`_.
+Instead, `flexible array members have incomplete type, and so the sizeof()
+operator may not be applied <https://gcc.gnu.org/onlinedocs/gcc/Zero-Length.html>`_,
+so any misuse of such operators will be immediately noticed at build time.
+
+With respect to one-element arrays, one has to be acutely aware that `such arrays
+occupy at least as much space as a single object of the type
+<https://gcc.gnu.org/onlinedocs/gcc/Zero-Length.html>`_,
+hence they contribute to the size of the enclosing structure. This is prone
+to error every time people want to calculate the total size of dynamic memory
+to allocate for a structure containing an array of this kind as a member::
+
+ struct something {
+ size_t count;
+ struct foo items[1];
+ };
+
+ struct something *instance;
+
+ instance = kmalloc(struct_size(instance, items, count - 1), GFP_KERNEL);
+ instance->count = count;
+
+ size = sizeof(instance->items) * instance->count;
+ memcpy(instance->items, source, size);
+
+In the example above, we had to remember to calculate ``count - 1`` when using
+the struct_size() helper, otherwise we would have --unintentionally-- allocated
+memory for one too many ``items`` objects. The cleanest and least error-prone way
+to implement this is through the use of a `flexible array member`::
+
+ struct something {
+ size_t count;
+ struct foo items[];
+ };
+
+ struct something *instance;
+
+ instance = kmalloc(struct_size(instance, items, count), GFP_KERNEL);
+ instance->count = count;
+
+ size = sizeof(instance->items[0]) * instance->count;
+ memcpy(instance->items, source, size);
diff --git a/Documentation/process/howto.rst b/Documentation/process/howto.rst
index 70791e1..20c9e07 100644
--- a/Documentation/process/howto.rst
+++ b/Documentation/process/howto.rst
@@ -597,7 +597,7 @@
ChangeLog section of the document:
"The Perfect Patch"
- http://www.ozlabs.org/~akpm/stuff/tpp.txt
+ https://www.ozlabs.org/~akpm/stuff/tpp.txt
All of these things are sometimes very hard to do. It can take years to
diff --git a/Documentation/process/index.rst b/Documentation/process/index.rst
index f07c925..dd231ff 100644
--- a/Documentation/process/index.rst
+++ b/Documentation/process/index.rst
@@ -32,7 +32,7 @@
kernel-enforcement-statement
kernel-driver-statement
-Other guides to the community that are of interest to most developers are:
+Other guides to the community that are of interest to most developers are:
.. toctree::
:maxdepth: 1
@@ -61,7 +61,7 @@
botching-up-ioctls
clang-format
../riscv/patch-acceptance
- unaligned-memory-access
+ ../core-api/unaligned-memory-access
.. only:: subproject and html
diff --git a/Documentation/process/kernel-docs.rst b/Documentation/process/kernel-docs.rst
index 9d6d0ac..64786e5 100644
--- a/Documentation/process/kernel-docs.rst
+++ b/Documentation/process/kernel-docs.rst
@@ -98,7 +98,7 @@
* Title: **Linux Device Drivers, Third Edition**
:Author: Jonathan Corbet, Alessandro Rubini, Greg Kroah-Hartman
- :URL: http://lwn.net/Kernel/LDD3/
+ :URL: https://lwn.net/Kernel/LDD3/
:Date: 2005
:Description: A 600-page book covering the (2.6.10) driver
programming API and kernel hacking in general. Available under the
@@ -129,7 +129,7 @@
* Title: **Linux Kernel Module Programming Guide**
:Author: Ori Pomerantz.
- :URL: http://tldp.org/LDP/lkmpg/2.6/html/index.html
+ :URL: https://tldp.org/LDP/lkmpg/2.6/html/index.html
:Date: 2001
:Keywords: modules, GPL book, /proc, ioctls, system calls,
interrupt handlers .
@@ -244,7 +244,7 @@
* Title: **I/O Event Handling Under Linux**
:Author: Richard Gooch.
- :URL: http://web.mit.edu/~yandros/doc/io-events.html
+ :URL: https://web.mit.edu/~yandros/doc/io-events.html
:Date: 1999
:Keywords: IO, I/O, select(2), poll(2), FDs, aio_read(2), readiness
event queues.
@@ -295,7 +295,7 @@
* Title: **Design and Implementation of the Second Extended Filesystem**
:Author: Rémy Card, Theodore Ts'o, Stephen Tweedie.
- :URL: http://web.mit.edu/tytso/www/linux/ext2intro.html
+ :URL: https://web.mit.edu/tytso/www/linux/ext2intro.html
:Date: 1998
:Keywords: ext2, linux fs history, inode, directory, link, devices,
VFS, physical structure, performance, benchmarks, ext2fs library,
@@ -322,7 +322,7 @@
* Title: **Linux Kernel Hackers' Guide**
:Author: Michael K. Johnson.
- :URL: http://www.tldp.org/LDP/khg/HyperNews/get/khg.html
+ :URL: https://www.tldp.org/LDP/khg/HyperNews/get/khg.html
:Date: 1997
:Keywords: device drivers, files, VFS, kernel interface, character vs
block devices, hardware interrupts, scsi, DMA, access to user memory,
@@ -375,7 +375,7 @@
* Title: **Dissecting Interrupts and Browsing DMA**
:Author: Alessandro Rubini and Georg v. Zezschwitz.
- :URL: http://www.linuxjournal.com/article.php?sid=1222
+ :URL: https://www.linuxjournal.com/article.php?sid=1222
:Date: 1996
:Keywords: interrupts, irqs, DMA, bottom halves, task queues.
:Description: Linux Journal Kernel Korner article.
@@ -391,7 +391,7 @@
* Title: **Device Drivers Concluded**
:Author: Georg v. Zezschwitz.
- :URL: http://www.linuxjournal.com/article.php?sid=1287
+ :URL: https://www.linuxjournal.com/article.php?sid=1287
:Date: 1996
:Keywords: address spaces, pages, pagination, page management,
demand loading, swapping, memory protection, memory mapping, mmap,
@@ -405,7 +405,7 @@
* Title: **Network Buffers And Memory Management**
:Author: Alan Cox.
- :URL: http://www.linuxjournal.com/article.php?sid=1312
+ :URL: https://www.linuxjournal.com/article.php?sid=1312
:Date: 1996
:Keywords: sk_buffs, network devices, protocol/link layer
variables, network devices flags, transmit, receive,
@@ -418,7 +418,7 @@
* Title: **Analysis of the Ext2fs structure**
:Author: Louis-Dominique Dubeau.
- :URL: http://teaching.csse.uwa.edu.au/units/CITS2002/fs-ext2/
+ :URL: https://teaching.csse.uwa.edu.au/units/CITS2002/fs-ext2/
:Date: 1994
:Keywords: ext2, filesystem, ext2fs.
:Description: Description of ext2's blocks, directories, inodes,
@@ -480,7 +480,7 @@
:ISBN: 0-596-00590-3
:Notes: Further information in
http://www.oreilly.com/catalog/linuxdrive3/
- PDF format, URL: http://lwn.net/Kernel/LDD3/
+ PDF format, URL: https://lwn.net/Kernel/LDD3/
* Title: **Linux Kernel Internals**
@@ -561,7 +561,7 @@
* Name: **Linux Weekly News**
- :URL: http://lwn.net
+ :URL: https://lwn.net
:Keywords: latest kernel news.
:Description: The title says it all. There's a fixed kernel section
summarizing developers' work, bug fixes, new features and versions
@@ -570,7 +570,7 @@
* Name: **The home page of Linux-MM**
:Author: The Linux-MM team.
- :URL: http://linux-mm.org/
+ :URL: https://linux-mm.org/
:Keywords: memory management, Linux-MM, mm patches, TODO, docs,
mailing list.
:Description: Site devoted to Linux Memory Management development.
@@ -579,7 +579,7 @@
* Name: **Kernel Newbies IRC Channel and Website**
- :URL: http://www.kernelnewbies.org
+ :URL: https://www.kernelnewbies.org
:Keywords: IRC, newbies, channel, asking doubts.
:Description: #kernelnewbies on irc.oftc.net.
#kernelnewbies is an IRC network dedicated to the 'newbie'
@@ -605,4 +605,4 @@
Document last updated on Tue 2016-Sep-20
This document is based on:
- http://www.dit.upm.es/~jmseyas/linux/kernel/hackers-docs.html
+ https://www.dit.upm.es/~jmseyas/linux/kernel/hackers-docs.html
diff --git a/Documentation/process/maintainer-pgp-guide.rst b/Documentation/process/maintainer-pgp-guide.rst
index 17db11b..8f8f1fe 100644
--- a/Documentation/process/maintainer-pgp-guide.rst
+++ b/Documentation/process/maintainer-pgp-guide.rst
@@ -462,7 +462,7 @@
.. _`Nitrokey Start`: https://shop.nitrokey.com/shop/product/nitrokey-start-6
.. _`Nitrokey Pro 2`: https://shop.nitrokey.com/shop/product/nitrokey-pro-2-3
.. _`Yubikey 5`: https://www.yubico.com/products/yubikey-5-overview/
-.. _Gnuk: http://www.fsij.org/doc-gnuk/
+.. _Gnuk: https://www.fsij.org/doc-gnuk/
.. _`LWN has a good review`: https://lwn.net/Articles/736231/
.. _`qualify for a free Nitrokey Start`: https://www.kernel.org/nitrokey-digital-tokens-for-kernel-developers.html
diff --git a/Documentation/process/submitting-drivers.rst b/Documentation/process/submitting-drivers.rst
index 1acaa14..74b35bf 100644
--- a/Documentation/process/submitting-drivers.rst
+++ b/Documentation/process/submitting-drivers.rst
@@ -5,8 +5,8 @@
This document is intended to explain how to submit device drivers to the
various kernel trees. Note that if you are interested in video card drivers
-you should probably talk to XFree86 (http://www.xfree86.org/) and/or X.Org
-(http://x.org/) instead.
+you should probably talk to XFree86 (https://www.xfree86.org/) and/or X.Org
+(https://x.org/) instead.
.. note::
@@ -25,7 +25,7 @@
Major and minor numbers for block and character devices are allocated
by the Linux assigned name and number authority (currently this is
-Torben Mathiasen). The site is http://www.lanana.org/. This
+Torben Mathiasen). The site is https://www.lanana.org/. This
also deals with allocating numbers for devices that are not going to
be submitted to the mainstream kernel.
See :ref:`Documentation/admin-guide/devices.rst <admin_devices>`
@@ -155,30 +155,30 @@
where *country_code* == your country code, such as
**us**, **uk**, **fr**, etc.
- http://git.kernel.org/?p=linux/kernel/git/torvalds/linux.git
+ https://git.kernel.org/?p=linux/kernel/git/torvalds/linux.git
Linux kernel mailing list:
linux-kernel@vger.kernel.org
[mail majordomo@vger.kernel.org to subscribe]
Linux Device Drivers, Third Edition (covers 2.6.10):
- http://lwn.net/Kernel/LDD3/ (free version)
+ https://lwn.net/Kernel/LDD3/ (free version)
LWN.net:
- Weekly summary of kernel development activity - http://lwn.net/
+ Weekly summary of kernel development activity - https://lwn.net/
2.6 API changes:
- http://lwn.net/Articles/2.6-kernel-api/
+ https://lwn.net/Articles/2.6-kernel-api/
Porting drivers from prior kernels to 2.6:
- http://lwn.net/Articles/driver-porting/
+ https://lwn.net/Articles/driver-porting/
KernelNewbies:
Documentation and assistance for new kernel programmers
- http://kernelnewbies.org/
+ https://kernelnewbies.org/
Linux USB project:
http://www.linux-usb.org/
@@ -187,7 +187,7 @@
http://www.fenrus.org/how-to-not-write-a-device-driver-paper.pdf
Kernel Janitor:
- http://kernelnewbies.org/KernelJanitors
+ https://kernelnewbies.org/KernelJanitors
GIT, Fast Version Control System:
- http://git-scm.com/
+ https://git-scm.com/
diff --git a/Documentation/process/submitting-patches.rst b/Documentation/process/submitting-patches.rst
index 1699b7f..5219bf3 100644
--- a/Documentation/process/submitting-patches.rst
+++ b/Documentation/process/submitting-patches.rst
@@ -94,7 +94,7 @@
very important if you want your patch accepted.
If you're using ``git``, ``git rebase -i`` can help you with this process. If
-you're not using ``git``, ``quilt`` <http://savannah.nongnu.org/projects/quilt>
+you're not using ``git``, ``quilt`` <https://savannah.nongnu.org/projects/quilt>
is another popular alternative.
.. _describe_changes:
@@ -196,6 +196,11 @@
[pretty]
fixes = Fixes: %h (\"%s\")
+An example call::
+
+ $ git log -1 --pretty=fixes 54a4f0239f2e
+ Fixes: 54a4f0239f2e ("KVM: MMU: make kvm_mmu_zap_page() return the number of pages it actually freed")
+
.. _split_changes:
3) Separate your changes
@@ -892,7 +897,7 @@
----------
Andrew Morton, "The perfect patch" (tpp).
- <http://www.ozlabs.org/~akpm/stuff/tpp.txt>
+ <https://www.ozlabs.org/~akpm/stuff/tpp.txt>
Jeff Garzik, "Linux kernel patch submission format".
<https://web.archive.org/web/20180829112450/http://linux.yyz.us/patch-format.html>
diff --git a/Documentation/remoteproc.txt b/Documentation/remoteproc.txt
deleted file mode 100644
index 2be1147..0000000
--- a/Documentation/remoteproc.txt
+++ /dev/null
@@ -1,359 +0,0 @@
-==========================
-Remote Processor Framework
-==========================
-
-Introduction
-============
-
-Modern SoCs typically have heterogeneous remote processor devices in asymmetric
-multiprocessing (AMP) configurations, which may be running different instances
-of operating system, whether it's Linux or any other flavor of real-time OS.
-
-OMAP4, for example, has dual Cortex-A9, dual Cortex-M3 and a C64x+ DSP.
-In a typical configuration, the dual cortex-A9 is running Linux in a SMP
-configuration, and each of the other three cores (two M3 cores and a DSP)
-is running its own instance of RTOS in an AMP configuration.
-
-The remoteproc framework allows different platforms/architectures to
-control (power on, load firmware, power off) those remote processors while
-abstracting the hardware differences, so the entire driver doesn't need to be
-duplicated. In addition, this framework also adds rpmsg virtio devices
-for remote processors that supports this kind of communication. This way,
-platform-specific remoteproc drivers only need to provide a few low-level
-handlers, and then all rpmsg drivers will then just work
-(for more information about the virtio-based rpmsg bus and its drivers,
-please read Documentation/rpmsg.txt).
-Registration of other types of virtio devices is now also possible. Firmwares
-just need to publish what kind of virtio devices do they support, and then
-remoteproc will add those devices. This makes it possible to reuse the
-existing virtio drivers with remote processor backends at a minimal development
-cost.
-
-User API
-========
-
-::
-
- int rproc_boot(struct rproc *rproc)
-
-Boot a remote processor (i.e. load its firmware, power it on, ...).
-
-If the remote processor is already powered on, this function immediately
-returns (successfully).
-
-Returns 0 on success, and an appropriate error value otherwise.
-Note: to use this function you should already have a valid rproc
-handle. There are several ways to achieve that cleanly (devres, pdata,
-the way remoteproc_rpmsg.c does this, or, if this becomes prevalent, we
-might also consider using dev_archdata for this).
-
-::
-
- void rproc_shutdown(struct rproc *rproc)
-
-Power off a remote processor (previously booted with rproc_boot()).
-In case @rproc is still being used by an additional user(s), then
-this function will just decrement the power refcount and exit,
-without really powering off the device.
-
-Every call to rproc_boot() must (eventually) be accompanied by a call
-to rproc_shutdown(). Calling rproc_shutdown() redundantly is a bug.
-
-.. note::
-
- we're not decrementing the rproc's refcount, only the power refcount.
- which means that the @rproc handle stays valid even after
- rproc_shutdown() returns, and users can still use it with a subsequent
- rproc_boot(), if needed.
-
-::
-
- struct rproc *rproc_get_by_phandle(phandle phandle)
-
-Find an rproc handle using a device tree phandle. Returns the rproc
-handle on success, and NULL on failure. This function increments
-the remote processor's refcount, so always use rproc_put() to
-decrement it back once rproc isn't needed anymore.
-
-Typical usage
-=============
-
-::
-
- #include <linux/remoteproc.h>
-
- /* in case we were given a valid 'rproc' handle */
- int dummy_rproc_example(struct rproc *my_rproc)
- {
- int ret;
-
- /* let's power on and boot our remote processor */
- ret = rproc_boot(my_rproc);
- if (ret) {
- /*
- * something went wrong. handle it and leave.
- */
- }
-
- /*
- * our remote processor is now powered on... give it some work
- */
-
- /* let's shut it down now */
- rproc_shutdown(my_rproc);
- }
-
-API for implementors
-====================
-
-::
-
- struct rproc *rproc_alloc(struct device *dev, const char *name,
- const struct rproc_ops *ops,
- const char *firmware, int len)
-
-Allocate a new remote processor handle, but don't register
-it yet. Required parameters are the underlying device, the
-name of this remote processor, platform-specific ops handlers,
-the name of the firmware to boot this rproc with, and the
-length of private data needed by the allocating rproc driver (in bytes).
-
-This function should be used by rproc implementations during
-initialization of the remote processor.
-
-After creating an rproc handle using this function, and when ready,
-implementations should then call rproc_add() to complete
-the registration of the remote processor.
-
-On success, the new rproc is returned, and on failure, NULL.
-
-.. note::
-
- **never** directly deallocate @rproc, even if it was not registered
- yet. Instead, when you need to unroll rproc_alloc(), use rproc_free().
-
-::
-
- void rproc_free(struct rproc *rproc)
-
-Free an rproc handle that was allocated by rproc_alloc.
-
-This function essentially unrolls rproc_alloc(), by decrementing the
-rproc's refcount. It doesn't directly free rproc; that would happen
-only if there are no other references to rproc and its refcount now
-dropped to zero.
-
-::
-
- int rproc_add(struct rproc *rproc)
-
-Register @rproc with the remoteproc framework, after it has been
-allocated with rproc_alloc().
-
-This is called by the platform-specific rproc implementation, whenever
-a new remote processor device is probed.
-
-Returns 0 on success and an appropriate error code otherwise.
-Note: this function initiates an asynchronous firmware loading
-context, which will look for virtio devices supported by the rproc's
-firmware.
-
-If found, those virtio devices will be created and added, so as a result
-of registering this remote processor, additional virtio drivers might get
-probed.
-
-::
-
- int rproc_del(struct rproc *rproc)
-
-Unroll rproc_add().
-
-This function should be called when the platform specific rproc
-implementation decides to remove the rproc device. it should
-_only_ be called if a previous invocation of rproc_add()
-has completed successfully.
-
-After rproc_del() returns, @rproc is still valid, and its
-last refcount should be decremented by calling rproc_free().
-
-Returns 0 on success and -EINVAL if @rproc isn't valid.
-
-::
-
- void rproc_report_crash(struct rproc *rproc, enum rproc_crash_type type)
-
-Report a crash in a remoteproc
-
-This function must be called every time a crash is detected by the
-platform specific rproc implementation. This should not be called from a
-non-remoteproc driver. This function can be called from atomic/interrupt
-context.
-
-Implementation callbacks
-========================
-
-These callbacks should be provided by platform-specific remoteproc
-drivers::
-
- /**
- * struct rproc_ops - platform-specific device handlers
- * @start: power on the device and boot it
- * @stop: power off the device
- * @kick: kick a virtqueue (virtqueue id given as a parameter)
- */
- struct rproc_ops {
- int (*start)(struct rproc *rproc);
- int (*stop)(struct rproc *rproc);
- void (*kick)(struct rproc *rproc, int vqid);
- };
-
-Every remoteproc implementation should at least provide the ->start and ->stop
-handlers. If rpmsg/virtio functionality is also desired, then the ->kick handler
-should be provided as well.
-
-The ->start() handler takes an rproc handle and should then power on the
-device and boot it (use rproc->priv to access platform-specific private data).
-The boot address, in case needed, can be found in rproc->bootaddr (remoteproc
-core puts there the ELF entry point).
-On success, 0 should be returned, and on failure, an appropriate error code.
-
-The ->stop() handler takes an rproc handle and powers the device down.
-On success, 0 is returned, and on failure, an appropriate error code.
-
-The ->kick() handler takes an rproc handle, and an index of a virtqueue
-where new message was placed in. Implementations should interrupt the remote
-processor and let it know it has pending messages. Notifying remote processors
-the exact virtqueue index to look in is optional: it is easy (and not
-too expensive) to go through the existing virtqueues and look for new buffers
-in the used rings.
-
-Binary Firmware Structure
-=========================
-
-At this point remoteproc supports ELF32 and ELF64 firmware binaries. However,
-it is quite expected that other platforms/devices which we'd want to
-support with this framework will be based on different binary formats.
-
-When those use cases show up, we will have to decouple the binary format
-from the framework core, so we can support several binary formats without
-duplicating common code.
-
-When the firmware is parsed, its various segments are loaded to memory
-according to the specified device address (might be a physical address
-if the remote processor is accessing memory directly).
-
-In addition to the standard ELF segments, most remote processors would
-also include a special section which we call "the resource table".
-
-The resource table contains system resources that the remote processor
-requires before it should be powered on, such as allocation of physically
-contiguous memory, or iommu mapping of certain on-chip peripherals.
-Remotecore will only power up the device after all the resource table's
-requirement are met.
-
-In addition to system resources, the resource table may also contain
-resource entries that publish the existence of supported features
-or configurations by the remote processor, such as trace buffers and
-supported virtio devices (and their configurations).
-
-The resource table begins with this header::
-
- /**
- * struct resource_table - firmware resource table header
- * @ver: version number
- * @num: number of resource entries
- * @reserved: reserved (must be zero)
- * @offset: array of offsets pointing at the various resource entries
- *
- * The header of the resource table, as expressed by this structure,
- * contains a version number (should we need to change this format in the
- * future), the number of available resource entries, and their offsets
- * in the table.
- */
- struct resource_table {
- u32 ver;
- u32 num;
- u32 reserved[2];
- u32 offset[0];
- } __packed;
-
-Immediately following this header are the resource entries themselves,
-each of which begins with the following resource entry header::
-
- /**
- * struct fw_rsc_hdr - firmware resource entry header
- * @type: resource type
- * @data: resource data
- *
- * Every resource entry begins with a 'struct fw_rsc_hdr' header providing
- * its @type. The content of the entry itself will immediately follow
- * this header, and it should be parsed according to the resource type.
- */
- struct fw_rsc_hdr {
- u32 type;
- u8 data[0];
- } __packed;
-
-Some resources entries are mere announcements, where the host is informed
-of specific remoteproc configuration. Other entries require the host to
-do something (e.g. allocate a system resource). Sometimes a negotiation
-is expected, where the firmware requests a resource, and once allocated,
-the host should provide back its details (e.g. address of an allocated
-memory region).
-
-Here are the various resource types that are currently supported::
-
- /**
- * enum fw_resource_type - types of resource entries
- *
- * @RSC_CARVEOUT: request for allocation of a physically contiguous
- * memory region.
- * @RSC_DEVMEM: request to iommu_map a memory-based peripheral.
- * @RSC_TRACE: announces the availability of a trace buffer into which
- * the remote processor will be writing logs.
- * @RSC_VDEV: declare support for a virtio device, and serve as its
- * virtio header.
- * @RSC_LAST: just keep this one at the end
- * @RSC_VENDOR_START: start of the vendor specific resource types range
- * @RSC_VENDOR_END: end of the vendor specific resource types range
- *
- * Please note that these values are used as indices to the rproc_handle_rsc
- * lookup table, so please keep them sane. Moreover, @RSC_LAST is used to
- * check the validity of an index before the lookup table is accessed, so
- * please update it as needed.
- */
- enum fw_resource_type {
- RSC_CARVEOUT = 0,
- RSC_DEVMEM = 1,
- RSC_TRACE = 2,
- RSC_VDEV = 3,
- RSC_LAST = 4,
- RSC_VENDOR_START = 128,
- RSC_VENDOR_END = 512,
- };
-
-For more details regarding a specific resource type, please see its
-dedicated structure in include/linux/remoteproc.h.
-
-We also expect that platform-specific resource entries will show up
-at some point. When that happens, we could easily add a new RSC_PLATFORM
-type, and hand those resources to the platform-specific rproc driver to handle.
-
-Virtio and remoteproc
-=====================
-
-The firmware should provide remoteproc information about virtio devices
-that it supports, and their configurations: a RSC_VDEV resource entry
-should specify the virtio device id (as in virtio_ids.h), virtio features,
-virtio config space, vrings information, etc.
-
-When a new remote processor is registered, the remoteproc framework
-will look for its resource table and will register the virtio devices
-it supports. A firmware may support any number of virtio devices, and
-of any type (a single remote processor can also easily support several
-rpmsg virtio devices this way, if desired).
-
-Of course, RSC_VDEV resource entries are only good enough for static
-allocation of virtio devices. Dynamic allocations will also be made possible
-using the rpmsg bus (similar to how we already do dynamic allocations of
-rpmsg channels; read more about it in rpmsg.txt).
diff --git a/Documentation/rpmsg.txt b/Documentation/rpmsg.txt
deleted file mode 100644
index 24b7a9e..0000000
--- a/Documentation/rpmsg.txt
+++ /dev/null
@@ -1,341 +0,0 @@
-============================================
-Remote Processor Messaging (rpmsg) Framework
-============================================
-
-.. note::
-
- This document describes the rpmsg bus and how to write rpmsg drivers.
- To learn how to add rpmsg support for new platforms, check out remoteproc.txt
- (also a resident of Documentation/).
-
-Introduction
-============
-
-Modern SoCs typically employ heterogeneous remote processor devices in
-asymmetric multiprocessing (AMP) configurations, which may be running
-different instances of operating system, whether it's Linux or any other
-flavor of real-time OS.
-
-OMAP4, for example, has dual Cortex-A9, dual Cortex-M3 and a C64x+ DSP.
-Typically, the dual cortex-A9 is running Linux in a SMP configuration,
-and each of the other three cores (two M3 cores and a DSP) is running
-its own instance of RTOS in an AMP configuration.
-
-Typically AMP remote processors employ dedicated DSP codecs and multimedia
-hardware accelerators, and therefore are often used to offload CPU-intensive
-multimedia tasks from the main application processor.
-
-These remote processors could also be used to control latency-sensitive
-sensors, drive random hardware blocks, or just perform background tasks
-while the main CPU is idling.
-
-Users of those remote processors can either be userland apps (e.g. multimedia
-frameworks talking with remote OMX components) or kernel drivers (controlling
-hardware accessible only by the remote processor, reserving kernel-controlled
-resources on behalf of the remote processor, etc..).
-
-Rpmsg is a virtio-based messaging bus that allows kernel drivers to communicate
-with remote processors available on the system. In turn, drivers could then
-expose appropriate user space interfaces, if needed.
-
-When writing a driver that exposes rpmsg communication to userland, please
-keep in mind that remote processors might have direct access to the
-system's physical memory and other sensitive hardware resources (e.g. on
-OMAP4, remote cores and hardware accelerators may have direct access to the
-physical memory, gpio banks, dma controllers, i2c bus, gptimers, mailbox
-devices, hwspinlocks, etc..). Moreover, those remote processors might be
-running RTOS where every task can access the entire memory/devices exposed
-to the processor. To minimize the risks of rogue (or buggy) userland code
-exploiting remote bugs, and by that taking over the system, it is often
-desired to limit userland to specific rpmsg channels (see definition below)
-it can send messages on, and if possible, minimize how much control
-it has over the content of the messages.
-
-Every rpmsg device is a communication channel with a remote processor (thus
-rpmsg devices are called channels). Channels are identified by a textual name
-and have a local ("source") rpmsg address, and remote ("destination") rpmsg
-address.
-
-When a driver starts listening on a channel, its rx callback is bound with
-a unique rpmsg local address (a 32-bit integer). This way when inbound messages
-arrive, the rpmsg core dispatches them to the appropriate driver according
-to their destination address (this is done by invoking the driver's rx handler
-with the payload of the inbound message).
-
-
-User API
-========
-
-::
-
- int rpmsg_send(struct rpmsg_channel *rpdev, void *data, int len);
-
-sends a message across to the remote processor on a given channel.
-The caller should specify the channel, the data it wants to send,
-and its length (in bytes). The message will be sent on the specified
-channel, i.e. its source and destination address fields will be
-set to the channel's src and dst addresses.
-
-In case there are no TX buffers available, the function will block until
-one becomes available (i.e. until the remote processor consumes
-a tx buffer and puts it back on virtio's used descriptor ring),
-or a timeout of 15 seconds elapses. When the latter happens,
--ERESTARTSYS is returned.
-
-The function can only be called from a process context (for now).
-Returns 0 on success and an appropriate error value on failure.
-
-::
-
- int rpmsg_sendto(struct rpmsg_channel *rpdev, void *data, int len, u32 dst);
-
-sends a message across to the remote processor on a given channel,
-to a destination address provided by the caller.
-
-The caller should specify the channel, the data it wants to send,
-its length (in bytes), and an explicit destination address.
-
-The message will then be sent to the remote processor to which the
-channel belongs, using the channel's src address, and the user-provided
-dst address (thus the channel's dst address will be ignored).
-
-In case there are no TX buffers available, the function will block until
-one becomes available (i.e. until the remote processor consumes
-a tx buffer and puts it back on virtio's used descriptor ring),
-or a timeout of 15 seconds elapses. When the latter happens,
--ERESTARTSYS is returned.
-
-The function can only be called from a process context (for now).
-Returns 0 on success and an appropriate error value on failure.
-
-::
-
- int rpmsg_send_offchannel(struct rpmsg_channel *rpdev, u32 src, u32 dst,
- void *data, int len);
-
-
-sends a message across to the remote processor, using the src and dst
-addresses provided by the user.
-
-The caller should specify the channel, the data it wants to send,
-its length (in bytes), and explicit source and destination addresses.
-The message will then be sent to the remote processor to which the
-channel belongs, but the channel's src and dst addresses will be
-ignored (and the user-provided addresses will be used instead).
-
-In case there are no TX buffers available, the function will block until
-one becomes available (i.e. until the remote processor consumes
-a tx buffer and puts it back on virtio's used descriptor ring),
-or a timeout of 15 seconds elapses. When the latter happens,
--ERESTARTSYS is returned.
-
-The function can only be called from a process context (for now).
-Returns 0 on success and an appropriate error value on failure.
-
-::
-
- int rpmsg_trysend(struct rpmsg_channel *rpdev, void *data, int len);
-
-sends a message across to the remote processor on a given channel.
-The caller should specify the channel, the data it wants to send,
-and its length (in bytes). The message will be sent on the specified
-channel, i.e. its source and destination address fields will be
-set to the channel's src and dst addresses.
-
-In case there are no TX buffers available, the function will immediately
-return -ENOMEM without waiting until one becomes available.
-
-The function can only be called from a process context (for now).
-Returns 0 on success and an appropriate error value on failure.
-
-::
-
- int rpmsg_trysendto(struct rpmsg_channel *rpdev, void *data, int len, u32 dst)
-
-
-sends a message across to the remote processor on a given channel,
-to a destination address provided by the user.
-
-The user should specify the channel, the data it wants to send,
-its length (in bytes), and an explicit destination address.
-
-The message will then be sent to the remote processor to which the
-channel belongs, using the channel's src address, and the user-provided
-dst address (thus the channel's dst address will be ignored).
-
-In case there are no TX buffers available, the function will immediately
-return -ENOMEM without waiting until one becomes available.
-
-The function can only be called from a process context (for now).
-Returns 0 on success and an appropriate error value on failure.
-
-::
-
- int rpmsg_trysend_offchannel(struct rpmsg_channel *rpdev, u32 src, u32 dst,
- void *data, int len);
-
-
-sends a message across to the remote processor, using source and
-destination addresses provided by the user.
-
-The user should specify the channel, the data it wants to send,
-its length (in bytes), and explicit source and destination addresses.
-The message will then be sent to the remote processor to which the
-channel belongs, but the channel's src and dst addresses will be
-ignored (and the user-provided addresses will be used instead).
-
-In case there are no TX buffers available, the function will immediately
-return -ENOMEM without waiting until one becomes available.
-
-The function can only be called from a process context (for now).
-Returns 0 on success and an appropriate error value on failure.
-
-::
-
- struct rpmsg_endpoint *rpmsg_create_ept(struct rpmsg_channel *rpdev,
- void (*cb)(struct rpmsg_channel *, void *, int, void *, u32),
- void *priv, u32 addr);
-
-every rpmsg address in the system is bound to an rx callback (so when
-inbound messages arrive, they are dispatched by the rpmsg bus using the
-appropriate callback handler) by means of an rpmsg_endpoint struct.
-
-This function allows drivers to create such an endpoint, and by that,
-bind a callback, and possibly some private data too, to an rpmsg address
-(either one that is known in advance, or one that will be dynamically
-assigned for them).
-
-Simple rpmsg drivers need not call rpmsg_create_ept, because an endpoint
-is already created for them when they are probed by the rpmsg bus
-(using the rx callback they provide when they registered to the rpmsg bus).
-
-So things should just work for simple drivers: they already have an
-endpoint, their rx callback is bound to their rpmsg address, and when
-relevant inbound messages arrive (i.e. messages which their dst address
-equals to the src address of their rpmsg channel), the driver's handler
-is invoked to process it.
-
-That said, more complicated drivers might do need to allocate
-additional rpmsg addresses, and bind them to different rx callbacks.
-To accomplish that, those drivers need to call this function.
-Drivers should provide their channel (so the new endpoint would bind
-to the same remote processor their channel belongs to), an rx callback
-function, an optional private data (which is provided back when the
-rx callback is invoked), and an address they want to bind with the
-callback. If addr is RPMSG_ADDR_ANY, then rpmsg_create_ept will
-dynamically assign them an available rpmsg address (drivers should have
-a very good reason why not to always use RPMSG_ADDR_ANY here).
-
-Returns a pointer to the endpoint on success, or NULL on error.
-
-::
-
- void rpmsg_destroy_ept(struct rpmsg_endpoint *ept);
-
-
-destroys an existing rpmsg endpoint. user should provide a pointer
-to an rpmsg endpoint that was previously created with rpmsg_create_ept().
-
-::
-
- int register_rpmsg_driver(struct rpmsg_driver *rpdrv);
-
-
-registers an rpmsg driver with the rpmsg bus. user should provide
-a pointer to an rpmsg_driver struct, which contains the driver's
-->probe() and ->remove() functions, an rx callback, and an id_table
-specifying the names of the channels this driver is interested to
-be probed with.
-
-::
-
- void unregister_rpmsg_driver(struct rpmsg_driver *rpdrv);
-
-
-unregisters an rpmsg driver from the rpmsg bus. user should provide
-a pointer to a previously-registered rpmsg_driver struct.
-Returns 0 on success, and an appropriate error value on failure.
-
-
-Typical usage
-=============
-
-The following is a simple rpmsg driver, that sends an "hello!" message
-on probe(), and whenever it receives an incoming message, it dumps its
-content to the console.
-
-::
-
- #include <linux/kernel.h>
- #include <linux/module.h>
- #include <linux/rpmsg.h>
-
- static void rpmsg_sample_cb(struct rpmsg_channel *rpdev, void *data, int len,
- void *priv, u32 src)
- {
- print_hex_dump(KERN_INFO, "incoming message:", DUMP_PREFIX_NONE,
- 16, 1, data, len, true);
- }
-
- static int rpmsg_sample_probe(struct rpmsg_channel *rpdev)
- {
- int err;
-
- dev_info(&rpdev->dev, "chnl: 0x%x -> 0x%x\n", rpdev->src, rpdev->dst);
-
- /* send a message on our channel */
- err = rpmsg_send(rpdev, "hello!", 6);
- if (err) {
- pr_err("rpmsg_send failed: %d\n", err);
- return err;
- }
-
- return 0;
- }
-
- static void rpmsg_sample_remove(struct rpmsg_channel *rpdev)
- {
- dev_info(&rpdev->dev, "rpmsg sample client driver is removed\n");
- }
-
- static struct rpmsg_device_id rpmsg_driver_sample_id_table[] = {
- { .name = "rpmsg-client-sample" },
- { },
- };
- MODULE_DEVICE_TABLE(rpmsg, rpmsg_driver_sample_id_table);
-
- static struct rpmsg_driver rpmsg_sample_client = {
- .drv.name = KBUILD_MODNAME,
- .id_table = rpmsg_driver_sample_id_table,
- .probe = rpmsg_sample_probe,
- .callback = rpmsg_sample_cb,
- .remove = rpmsg_sample_remove,
- };
- module_rpmsg_driver(rpmsg_sample_client);
-
-.. note::
-
- a similar sample which can be built and loaded can be found
- in samples/rpmsg/.
-
-Allocations of rpmsg channels
-=============================
-
-At this point we only support dynamic allocations of rpmsg channels.
-
-This is possible only with remote processors that have the VIRTIO_RPMSG_F_NS
-virtio device feature set. This feature bit means that the remote
-processor supports dynamic name service announcement messages.
-
-When this feature is enabled, creation of rpmsg devices (i.e. channels)
-is completely dynamic: the remote processor announces the existence of a
-remote rpmsg service by sending a name service message (which contains
-the name and rpmsg addr of the remote service, see struct rpmsg_ns_msg).
-
-This message is then handled by the rpmsg bus, which in turn dynamically
-creates and registers an rpmsg channel (which represents the remote service).
-If/when a relevant rpmsg driver is registered, it will be immediately probed
-by the bus, and can then start sending messages to the remote service.
-
-The plan is also to add static creation of rpmsg channels via the virtio
-config space, but it's not implemented yet.
diff --git a/Documentation/s390/monreader.rst b/Documentation/s390/monreader.rst
index 1e85757..21cdfb6 100644
--- a/Documentation/s390/monreader.rst
+++ b/Documentation/s390/monreader.rst
@@ -146,7 +146,7 @@
See "Appendix A: `*MONITOR`" in the "z/VM Performance" document for a description
of the monitor control element layout. The layout of the monitor records can
-be found here (z/VM 5.1): http://www.vm.ibm.com/pubs/mon510/index.html
+be found here (z/VM 5.1): https://www.vm.ibm.com/pubs/mon510/index.html
The layout of the data stream provided by the monreader device is as follows::
diff --git a/Documentation/s390/s390dbf.rst b/Documentation/s390/s390dbf.rst
index cdb3684..af8bdc3 100644
--- a/Documentation/s390/s390dbf.rst
+++ b/Documentation/s390/s390dbf.rst
@@ -67,7 +67,7 @@
The content of the directories are files which represent different views
to the debug log. Each component can decide which views should be
used through registering them with the function :c:func:`debug_register_view()`.
-Predefined views for hex/ascii, sprintf and raw binary data are provided.
+Predefined views for hex/ascii and sprintf data are provided.
It is also possible to define other views. The content of
a view can be inspected simply by reading the corresponding debugfs file.
@@ -119,8 +119,6 @@
extern struct debug_view debug_hex_ascii_view;
- extern struct debug_view debug_raw_view;
-
extern struct debug_view debug_sprintf_view;
Examples
@@ -129,7 +127,7 @@
.. code-block:: c
/*
- * hex_ascii- + raw-view Example
+ * hex_ascii-view Example
*/
#include <linux/init.h>
@@ -143,7 +141,6 @@
debug_info = debug_register("test", 1, 4, 4 );
debug_register_view(debug_info, &debug_hex_ascii_view);
- debug_register_view(debug_info, &debug_raw_view);
debug_text_event(debug_info, 4 , "one ");
debug_int_exception(debug_info, 4, 4711);
@@ -201,7 +198,7 @@
Example::
> ls /sys/kernel/debug/s390dbf/dasd
- flush hex_ascii level pages raw
+ flush hex_ascii level pages
> cat /sys/kernel/debug/s390dbf/dasd/hex_ascii | sort -k2,2 -s
00 00974733272:680099 2 - 02 0006ad7e 07 ea 4a 90 | ....
00 00974733272:682210 2 - 02 0006ade6 46 52 45 45 | FREE
@@ -298,10 +295,9 @@
Predefined Views
----------------
-There are three predefined views: hex_ascii, raw and sprintf.
+There are two predefined views: hex_ascii and sprintf.
The hex_ascii view shows the data field in hex and ascii representation
(e.g. ``45 43 4b 44 | ECKD``).
-The raw view returns a bytestream as the debug areas are stored in memory.
The sprintf view formats the debug entries in the same way as the sprintf
function would do. The sprintf event/exception functions write to the
@@ -334,11 +330,6 @@
- Return Address to caller
- data field
-The format of the raw view is:
-
-- Header as described in debug.h
-- datafield
-
A typical line of the hex_ascii view will look like the following (first line
is only for explanation and will not be displayed when 'cating' the view)::
diff --git a/Documentation/s390/vfio-ap.rst b/Documentation/s390/vfio-ap.rst
index 367e27e..e154365 100644
--- a/Documentation/s390/vfio-ap.rst
+++ b/Documentation/s390/vfio-ap.rst
@@ -361,7 +361,7 @@
assign_domain / unassign_domain:
Write-only attributes for assigning/unassigning an AP usage domain to/from
the mediated matrix device. To assign/unassign a domain, the domain
- number of the the usage domain is echoed to the respective attribute
+ number of the usage domain is echoed to the respective attribute
file.
matrix:
A read-only file for displaying the APQNs derived from the cross product
diff --git a/Documentation/scheduler/index.rst b/Documentation/scheduler/index.rst
index 69074e5..88900aa 100644
--- a/Documentation/scheduler/index.rst
+++ b/Documentation/scheduler/index.rst
@@ -12,6 +12,7 @@
sched-deadline
sched-design-CFS
sched-domains
+ sched-capacity
sched-energy
sched-nice-design
sched-rt-group
diff --git a/Documentation/scheduler/sched-capacity.rst b/Documentation/scheduler/sched-capacity.rst
new file mode 100644
index 0000000..00bf0d0
--- /dev/null
+++ b/Documentation/scheduler/sched-capacity.rst
@@ -0,0 +1,439 @@
+=========================
+Capacity Aware Scheduling
+=========================
+
+1. CPU Capacity
+===============
+
+1.1 Introduction
+----------------
+
+Conventional, homogeneous SMP platforms are composed of purely identical
+CPUs. Heterogeneous platforms on the other hand are composed of CPUs with
+different performance characteristics - on such platforms, not all CPUs can be
+considered equal.
+
+CPU capacity is a measure of the performance a CPU can reach, normalized against
+the most performant CPU in the system. Heterogeneous systems are also called
+asymmetric CPU capacity systems, as they contain CPUs of different capacities.
+
+Disparity in maximum attainable performance (IOW in maximum CPU capacity) stems
+from two factors:
+
+- not all CPUs may have the same microarchitecture (µarch).
+- with Dynamic Voltage and Frequency Scaling (DVFS), not all CPUs may be
+ physically able to attain the higher Operating Performance Points (OPP).
+
+Arm big.LITTLE systems are an example of both. The big CPUs are more
+performance-oriented than the LITTLE ones (more pipeline stages, bigger caches,
+smarter predictors, etc), and can usually reach higher OPPs than the LITTLE ones
+can.
+
+CPU performance is usually expressed in Millions of Instructions Per Second
+(MIPS), which can also be expressed as a given amount of instructions attainable
+per Hz, leading to::
+
+ capacity(cpu) = work_per_hz(cpu) * max_freq(cpu)
+
+1.2 Scheduler terms
+-------------------
+
+Two different capacity values are used within the scheduler. A CPU's
+``capacity_orig`` is its maximum attainable capacity, i.e. its maximum
+attainable performance level. A CPU's ``capacity`` is its ``capacity_orig`` to
+which some loss of available performance (e.g. time spent handling IRQs) is
+subtracted.
+
+Note that a CPU's ``capacity`` is solely intended to be used by the CFS class,
+while ``capacity_orig`` is class-agnostic. The rest of this document will use
+the term ``capacity`` interchangeably with ``capacity_orig`` for the sake of
+brevity.
+
+1.3 Platform examples
+---------------------
+
+1.3.1 Identical OPPs
+~~~~~~~~~~~~~~~~~~~~
+
+Consider an hypothetical dual-core asymmetric CPU capacity system where
+
+- work_per_hz(CPU0) = W
+- work_per_hz(CPU1) = W/2
+- all CPUs are running at the same fixed frequency
+
+By the above definition of capacity:
+
+- capacity(CPU0) = C
+- capacity(CPU1) = C/2
+
+To draw the parallel with Arm big.LITTLE, CPU0 would be a big while CPU1 would
+be a LITTLE.
+
+With a workload that periodically does a fixed amount of work, you will get an
+execution trace like so::
+
+ CPU0 work ^
+ | ____ ____ ____
+ | | | | | | |
+ +----+----+----+----+----+----+----+----+----+----+-> time
+
+ CPU1 work ^
+ | _________ _________ ____
+ | | | | | |
+ +----+----+----+----+----+----+----+----+----+----+-> time
+
+CPU0 has the highest capacity in the system (C), and completes a fixed amount of
+work W in T units of time. On the other hand, CPU1 has half the capacity of
+CPU0, and thus only completes W/2 in T.
+
+1.3.2 Different max OPPs
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+Usually, CPUs of different capacity values also have different maximum
+OPPs. Consider the same CPUs as above (i.e. same work_per_hz()) with:
+
+- max_freq(CPU0) = F
+- max_freq(CPU1) = 2/3 * F
+
+This yields:
+
+- capacity(CPU0) = C
+- capacity(CPU1) = C/3
+
+Executing the same workload as described in 1.3.1, which each CPU running at its
+maximum frequency results in::
+
+ CPU0 work ^
+ | ____ ____ ____
+ | | | | | | |
+ +----+----+----+----+----+----+----+----+----+----+-> time
+
+ workload on CPU1
+ CPU1 work ^
+ | ______________ ______________ ____
+ | | | | | |
+ +----+----+----+----+----+----+----+----+----+----+-> time
+
+1.4 Representation caveat
+-------------------------
+
+It should be noted that having a *single* value to represent differences in CPU
+performance is somewhat of a contentious point. The relative performance
+difference between two different µarchs could be X% on integer operations, Y% on
+floating point operations, Z% on branches, and so on. Still, results using this
+simple approach have been satisfactory for now.
+
+2. Task utilization
+===================
+
+2.1 Introduction
+----------------
+
+Capacity aware scheduling requires an expression of a task's requirements with
+regards to CPU capacity. Each scheduler class can express this differently, and
+while task utilization is specific to CFS, it is convenient to describe it here
+in order to introduce more generic concepts.
+
+Task utilization is a percentage meant to represent the throughput requirements
+of a task. A simple approximation of it is the task's duty cycle, i.e.::
+
+ task_util(p) = duty_cycle(p)
+
+On an SMP system with fixed frequencies, 100% utilization suggests the task is a
+busy loop. Conversely, 10% utilization hints it is a small periodic task that
+spends more time sleeping than executing. Variable CPU frequencies and
+asymmetric CPU capacities complexify this somewhat; the following sections will
+expand on these.
+
+2.2 Frequency invariance
+------------------------
+
+One issue that needs to be taken into account is that a workload's duty cycle is
+directly impacted by the current OPP the CPU is running at. Consider running a
+periodic workload at a given frequency F::
+
+ CPU work ^
+ | ____ ____ ____
+ | | | | | | |
+ +----+----+----+----+----+----+----+----+----+----+-> time
+
+This yields duty_cycle(p) == 25%.
+
+Now, consider running the *same* workload at frequency F/2::
+
+ CPU work ^
+ | _________ _________ ____
+ | | | | | |
+ +----+----+----+----+----+----+----+----+----+----+-> time
+
+This yields duty_cycle(p) == 50%, despite the task having the exact same
+behaviour (i.e. executing the same amount of work) in both executions.
+
+The task utilization signal can be made frequency invariant using the following
+formula::
+
+ task_util_freq_inv(p) = duty_cycle(p) * (curr_frequency(cpu) / max_frequency(cpu))
+
+Applying this formula to the two examples above yields a frequency invariant
+task utilization of 25%.
+
+2.3 CPU invariance
+------------------
+
+CPU capacity has a similar effect on task utilization in that running an
+identical workload on CPUs of different capacity values will yield different
+duty cycles.
+
+Consider the system described in 1.3.2., i.e.::
+
+- capacity(CPU0) = C
+- capacity(CPU1) = C/3
+
+Executing a given periodic workload on each CPU at their maximum frequency would
+result in::
+
+ CPU0 work ^
+ | ____ ____ ____
+ | | | | | | |
+ +----+----+----+----+----+----+----+----+----+----+-> time
+
+ CPU1 work ^
+ | ______________ ______________ ____
+ | | | | | |
+ +----+----+----+----+----+----+----+----+----+----+-> time
+
+IOW,
+
+- duty_cycle(p) == 25% if p runs on CPU0 at its maximum frequency
+- duty_cycle(p) == 75% if p runs on CPU1 at its maximum frequency
+
+The task utilization signal can be made CPU invariant using the following
+formula::
+
+ task_util_cpu_inv(p) = duty_cycle(p) * (capacity(cpu) / max_capacity)
+
+with ``max_capacity`` being the highest CPU capacity value in the
+system. Applying this formula to the above example above yields a CPU
+invariant task utilization of 25%.
+
+2.4 Invariant task utilization
+------------------------------
+
+Both frequency and CPU invariance need to be applied to task utilization in
+order to obtain a truly invariant signal. The pseudo-formula for a task
+utilization that is both CPU and frequency invariant is thus, for a given
+task p::
+
+ curr_frequency(cpu) capacity(cpu)
+ task_util_inv(p) = duty_cycle(p) * ------------------- * -------------
+ max_frequency(cpu) max_capacity
+
+In other words, invariant task utilization describes the behaviour of a task as
+if it were running on the highest-capacity CPU in the system, running at its
+maximum frequency.
+
+Any mention of task utilization in the following sections will imply its
+invariant form.
+
+2.5 Utilization estimation
+--------------------------
+
+Without a crystal ball, task behaviour (and thus task utilization) cannot
+accurately be predicted the moment a task first becomes runnable. The CFS class
+maintains a handful of CPU and task signals based on the Per-Entity Load
+Tracking (PELT) mechanism, one of those yielding an *average* utilization (as
+opposed to instantaneous).
+
+This means that while the capacity aware scheduling criteria will be written
+considering a "true" task utilization (using a crystal ball), the implementation
+will only ever be able to use an estimator thereof.
+
+3. Capacity aware scheduling requirements
+=========================================
+
+3.1 CPU capacity
+----------------
+
+Linux cannot currently figure out CPU capacity on its own, this information thus
+needs to be handed to it. Architectures must define arch_scale_cpu_capacity()
+for that purpose.
+
+The arm and arm64 architectures directly map this to the arch_topology driver
+CPU scaling data, which is derived from the capacity-dmips-mhz CPU binding; see
+Documentation/devicetree/bindings/arm/cpu-capacity.txt.
+
+3.2 Frequency invariance
+------------------------
+
+As stated in 2.2, capacity-aware scheduling requires a frequency-invariant task
+utilization. Architectures must define arch_scale_freq_capacity(cpu) for that
+purpose.
+
+Implementing this function requires figuring out at which frequency each CPU
+have been running at. One way to implement this is to leverage hardware counters
+whose increment rate scale with a CPU's current frequency (APERF/MPERF on x86,
+AMU on arm64). Another is to directly hook into cpufreq frequency transitions,
+when the kernel is aware of the switched-to frequency (also employed by
+arm/arm64).
+
+4. Scheduler topology
+=====================
+
+During the construction of the sched domains, the scheduler will figure out
+whether the system exhibits asymmetric CPU capacities. Should that be the
+case:
+
+- The sched_asym_cpucapacity static key will be enabled.
+- The SD_ASYM_CPUCAPACITY flag will be set at the lowest sched_domain level that
+ spans all unique CPU capacity values.
+
+The sched_asym_cpucapacity static key is intended to guard sections of code that
+cater to asymmetric CPU capacity systems. Do note however that said key is
+*system-wide*. Imagine the following setup using cpusets::
+
+ capacity C/2 C
+ ________ ________
+ / \ / \
+ CPUs 0 1 2 3 4 5 6 7
+ \__/ \______________/
+ cpusets cs0 cs1
+
+Which could be created via:
+
+.. code-block:: sh
+
+ mkdir /sys/fs/cgroup/cpuset/cs0
+ echo 0-1 > /sys/fs/cgroup/cpuset/cs0/cpuset.cpus
+ echo 0 > /sys/fs/cgroup/cpuset/cs0/cpuset.mems
+
+ mkdir /sys/fs/cgroup/cpuset/cs1
+ echo 2-7 > /sys/fs/cgroup/cpuset/cs1/cpuset.cpus
+ echo 0 > /sys/fs/cgroup/cpuset/cs1/cpuset.mems
+
+ echo 0 > /sys/fs/cgroup/cpuset/cpuset.sched_load_balance
+
+Since there *is* CPU capacity asymmetry in the system, the
+sched_asym_cpucapacity static key will be enabled. However, the sched_domain
+hierarchy of CPUs 0-1 spans a single capacity value: SD_ASYM_CPUCAPACITY isn't
+set in that hierarchy, it describes an SMP island and should be treated as such.
+
+Therefore, the 'canonical' pattern for protecting codepaths that cater to
+asymmetric CPU capacities is to:
+
+- Check the sched_asym_cpucapacity static key
+- If it is enabled, then also check for the presence of SD_ASYM_CPUCAPACITY in
+ the sched_domain hierarchy (if relevant, i.e. the codepath targets a specific
+ CPU or group thereof)
+
+5. Capacity aware scheduling implementation
+===========================================
+
+5.1 CFS
+-------
+
+5.1.1 Capacity fitness
+~~~~~~~~~~~~~~~~~~~~~~
+
+The main capacity scheduling criterion of CFS is::
+
+ task_util(p) < capacity(task_cpu(p))
+
+This is commonly called the capacity fitness criterion, i.e. CFS must ensure a
+task "fits" on its CPU. If it is violated, the task will need to achieve more
+work than what its CPU can provide: it will be CPU-bound.
+
+Furthermore, uclamp lets userspace specify a minimum and a maximum utilization
+value for a task, either via sched_setattr() or via the cgroup interface (see
+Documentation/admin-guide/cgroup-v2.rst). As its name imply, this can be used to
+clamp task_util() in the previous criterion.
+
+5.1.2 Wakeup CPU selection
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+CFS task wakeup CPU selection follows the capacity fitness criterion described
+above. On top of that, uclamp is used to clamp the task utilization values,
+which lets userspace have more leverage over the CPU selection of CFS
+tasks. IOW, CFS wakeup CPU selection searches for a CPU that satisfies::
+
+ clamp(task_util(p), task_uclamp_min(p), task_uclamp_max(p)) < capacity(cpu)
+
+By using uclamp, userspace can e.g. allow a busy loop (100% utilization) to run
+on any CPU by giving it a low uclamp.max value. Conversely, it can force a small
+periodic task (e.g. 10% utilization) to run on the highest-performance CPUs by
+giving it a high uclamp.min value.
+
+.. note::
+
+ Wakeup CPU selection in CFS can be eclipsed by Energy Aware Scheduling
+ (EAS), which is described in Documentation/scheduling/sched-energy.rst.
+
+5.1.3 Load balancing
+~~~~~~~~~~~~~~~~~~~~
+
+A pathological case in the wakeup CPU selection occurs when a task rarely
+sleeps, if at all - it thus rarely wakes up, if at all. Consider::
+
+ w == wakeup event
+
+ capacity(CPU0) = C
+ capacity(CPU1) = C / 3
+
+ workload on CPU0
+ CPU work ^
+ | _________ _________ ____
+ | | | | | |
+ +----+----+----+----+----+----+----+----+----+----+-> time
+ w w w
+
+ workload on CPU1
+ CPU work ^
+ | ____________________________________________
+ | |
+ +----+----+----+----+----+----+----+----+----+----+->
+ w
+
+This workload should run on CPU0, but if the task either:
+
+- was improperly scheduled from the start (inaccurate initial
+ utilization estimation)
+- was properly scheduled from the start, but suddenly needs more
+ processing power
+
+then it might become CPU-bound, IOW ``task_util(p) > capacity(task_cpu(p))``;
+the CPU capacity scheduling criterion is violated, and there may not be any more
+wakeup event to fix this up via wakeup CPU selection.
+
+Tasks that are in this situation are dubbed "misfit" tasks, and the mechanism
+put in place to handle this shares the same name. Misfit task migration
+leverages the CFS load balancer, more specifically the active load balance part
+(which caters to migrating currently running tasks). When load balance happens,
+a misfit active load balance will be triggered if a misfit task can be migrated
+to a CPU with more capacity than its current one.
+
+5.2 RT
+------
+
+5.2.1 Wakeup CPU selection
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+RT task wakeup CPU selection searches for a CPU that satisfies::
+
+ task_uclamp_min(p) <= capacity(task_cpu(cpu))
+
+while still following the usual priority constraints. If none of the candidate
+CPUs can satisfy this capacity criterion, then strict priority based scheduling
+is followed and CPU capacities are ignored.
+
+5.3 DL
+------
+
+5.3.1 Wakeup CPU selection
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+DL task wakeup CPU selection searches for a CPU that satisfies::
+
+ task_bandwidth(p) < capacity(task_cpu(p))
+
+while still respecting the usual bandwidth and deadline constraints. If
+none of the candidate CPUs can satisfy this capacity criterion, then the
+task will remain on its current CPU.
diff --git a/Documentation/scheduler/sched-energy.rst b/Documentation/scheduler/sched-energy.rst
index 9580c57..78f8507 100644
--- a/Documentation/scheduler/sched-energy.rst
+++ b/Documentation/scheduler/sched-energy.rst
@@ -331,16 +331,8 @@
looking for the presence of the SD_ASYM_CPUCAPACITY flag when the scheduling
domains are built.
-The flag is set/cleared automatically by the scheduler topology code whenever
-there are CPUs with different capacities in a root domain. The capacities of
-CPUs are provided by arch-specific code through the arch_scale_cpu_capacity()
-callback. As an example, arm and arm64 share an implementation of this callback
-which uses a combination of CPUFreq data and device-tree bindings to compute the
-capacity of CPUs (see drivers/base/arch_topology.c for more details).
-
-So, in order to use EAS on your platform your architecture must implement the
-arch_scale_cpu_capacity() callback, and some of the CPUs must have a lower
-capacity than others.
+See Documentation/sched/sched-capacity.rst for requirements to be met for this
+flag to be set in the sched_domain hierarchy.
Please note that EAS is not fundamentally incompatible with SMP, but no
significant savings on SMP platforms have been observed yet. This restriction
diff --git a/Documentation/scsi/advansys.rst b/Documentation/scsi/advansys.rst
index e0367e1..7ea12b1 100644
--- a/Documentation/scsi/advansys.rst
+++ b/Documentation/scsi/advansys.rst
@@ -125,7 +125,7 @@
c. klogd is started with the appropriate -c parameter
(e.g. klogd -c 8)
- This will cause printk() messages to be be displayed on the
+ This will cause printk() messages to be displayed on the
current console. Refer to the klogd(8) and syslogd(8) man pages
for details.
diff --git a/Documentation/scsi/scsi-parameters.rst b/Documentation/scsi/scsi-parameters.rst
index 9aba897..e5f68b43 100644
--- a/Documentation/scsi/scsi-parameters.rst
+++ b/Documentation/scsi/scsi-parameters.rst
@@ -94,7 +94,7 @@
(/proc/sys/dev/scsi/logging_level).
There is also a nice 'scsi_logging_level' script in the
S390-tools package, available for download at
- http://www-128.ibm.com/developerworks/linux/linux390/s390-tools-1.5.4.html
+ https://github.com/ibm-s390-tools/s390-tools/blob/master/scripts/scsi_logging_level
scsi_mod.scan= [SCSI] sync (default) scans SCSI busses as they are
discovered. async scans them in kernel threads,
diff --git a/Documentation/security/credentials.rst b/Documentation/security/credentials.rst
index 282e79f..d938720 100644
--- a/Documentation/security/credentials.rst
+++ b/Documentation/security/credentials.rst
@@ -453,9 +453,9 @@
When replacing the group list, the new list must be sorted before it
is added to the credential, as a binary search is used to test for
-membership. In practice, this means :c:func:`groups_sort` should be
-called before :c:func:`set_groups` or :c:func:`set_current_groups`.
-:c:func:`groups_sort)` must not be called on a ``struct group_list`` which
+membership. In practice, this means groups_sort() should be
+called before set_groups() or set_current_groups().
+groups_sort() must not be called on a ``struct group_list`` which
is shared as it may permute elements as part of the sorting process
even if the array is already sorted.
@@ -548,6 +548,10 @@
contents of the cred struct pointed to, barring the exceptions listed above
(see the Task Credentials section).
+To avoid "confused deputy" privilege escalation attacks, access control checks
+during subsequent operations on an opened file should use these credentials
+instead of "current"'s credentials, as the file may have been passed to a more
+privileged process.
Overriding the VFS's Use of Credentials
=======================================
diff --git a/Documentation/security/keys/core.rst b/Documentation/security/keys/core.rst
index cdc42cc..aa00816 100644
--- a/Documentation/security/keys/core.rst
+++ b/Documentation/security/keys/core.rst
@@ -912,7 +912,7 @@
One application of restricted keyrings is to verify X.509 certificate
chains or individual certificate signatures using the asymmetric key type.
- See Documentation/crypto/asymmetric-keys.txt for specific restrictions
+ See Documentation/crypto/asymmetric-keys.rst for specific restrictions
applicable to the asymmetric key type.
diff --git a/Documentation/security/keys/trusted-encrypted.rst b/Documentation/security/keys/trusted-encrypted.rst
index 50ac8bc..9483a74 100644
--- a/Documentation/security/keys/trusted-encrypted.rst
+++ b/Documentation/security/keys/trusted-encrypted.rst
@@ -200,7 +200,7 @@
24717c64 5972dcb82ab2dde83376d82b2e3c09ffc
Other uses for trusted and encrypted keys, such as for disk and file encryption
-are anticipated. In particular the new format 'ecryptfs' has been defined in
+are anticipated. In particular the new format 'ecryptfs' has been defined
in order to use encrypted keys to mount an eCryptfs filesystem. More details
about the usage can be found in the file
``Documentation/security/keys/ecryptfs.rst``.
diff --git a/Documentation/sh/index.rst b/Documentation/sh/index.rst
index bc8db7b..b5933fd 100644
--- a/Documentation/sh/index.rst
+++ b/Documentation/sh/index.rst
@@ -4,6 +4,12 @@
:Author: Paul Mundt
+.. toctree::
+ :maxdepth: 1
+
+ new-machine
+ register-banks
+
Memory Management
=================
@@ -16,18 +22,6 @@
.. kernel-doc:: arch/sh/kernel/cpu/sh4/sq.c
:export:
-SH-5
-----
-
-TLB Interfaces
-~~~~~~~~~~~~~~
-
-.. kernel-doc:: arch/sh/mm/tlb-sh5.c
- :internal:
-
-.. kernel-doc:: arch/sh/include/asm/tlb_64.h
- :internal:
-
Machine Specific Interfaces
===========================
diff --git a/Documentation/sh/new-machine.rst b/Documentation/sh/new-machine.rst
new file mode 100644
index 0000000..e501c52
--- /dev/null
+++ b/Documentation/sh/new-machine.rst
@@ -0,0 +1,277 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+=============================
+Adding a new board to LinuxSH
+=============================
+
+ Paul Mundt <lethal@linux-sh.org>
+
+This document attempts to outline what steps are necessary to add support
+for new boards to the LinuxSH port under the new 2.5 and 2.6 kernels. This
+also attempts to outline some of the noticeable changes between the 2.4
+and the 2.5/2.6 SH backend.
+
+1. New Directory Structure
+==========================
+
+The first thing to note is the new directory structure. Under 2.4, most
+of the board-specific code (with the exception of stboards) ended up
+in arch/sh/kernel/ directly, with board-specific headers ending up in
+include/asm-sh/. For the new kernel, things are broken out by board type,
+companion chip type, and CPU type. Looking at a tree view of this directory
+hierarchy looks like the following:
+
+Board-specific code::
+
+ .
+ |-- arch
+ | `-- sh
+ | `-- boards
+ | |-- adx
+ | | `-- board-specific files
+ | |-- bigsur
+ | | `-- board-specific files
+ | |
+ | ... more boards here ...
+ |
+ `-- include
+ `-- asm-sh
+ |-- adx
+ | `-- board-specific headers
+ |-- bigsur
+ | `-- board-specific headers
+ |
+ .. more boards here ...
+
+Next, for companion chips::
+
+ .
+ `-- arch
+ `-- sh
+ `-- cchips
+ `-- hd6446x
+ `-- hd64461
+ `-- cchip-specific files
+
+... and so on. Headers for the companion chips are treated the same way as
+board-specific headers. Thus, include/asm-sh/hd64461 is home to all of the
+hd64461-specific headers.
+
+Finally, CPU family support is also abstracted::
+
+ .
+ |-- arch
+ | `-- sh
+ | |-- kernel
+ | | `-- cpu
+ | | |-- sh2
+ | | | `-- SH-2 generic files
+ | | |-- sh3
+ | | | `-- SH-3 generic files
+ | | `-- sh4
+ | | `-- SH-4 generic files
+ | `-- mm
+ | `-- This is also broken out per CPU family, so each family can
+ | have their own set of cache/tlb functions.
+ |
+ `-- include
+ `-- asm-sh
+ |-- cpu-sh2
+ | `-- SH-2 specific headers
+ |-- cpu-sh3
+ | `-- SH-3 specific headers
+ `-- cpu-sh4
+ `-- SH-4 specific headers
+
+It should be noted that CPU subtypes are _not_ abstracted. Thus, these still
+need to be dealt with by the CPU family specific code.
+
+2. Adding a New Board
+=====================
+
+The first thing to determine is whether the board you are adding will be
+isolated, or whether it will be part of a family of boards that can mostly
+share the same board-specific code with minor differences.
+
+In the first case, this is just a matter of making a directory for your
+board in arch/sh/boards/ and adding rules to hook your board in with the
+build system (more on this in the next section). However, for board families
+it makes more sense to have a common top-level arch/sh/boards/ directory
+and then populate that with sub-directories for each member of the family.
+Both the Solution Engine and the hp6xx boards are an example of this.
+
+After you have setup your new arch/sh/boards/ directory, remember that you
+should also add a directory in include/asm-sh for headers localized to this
+board (if there are going to be more than one). In order to interoperate
+seamlessly with the build system, it's best to have this directory the same
+as the arch/sh/boards/ directory name, though if your board is again part of
+a family, the build system has ways of dealing with this (via incdir-y
+overloading), and you can feel free to name the directory after the family
+member itself.
+
+There are a few things that each board is required to have, both in the
+arch/sh/boards and the include/asm-sh/ hierarchy. In order to better
+explain this, we use some examples for adding an imaginary board. For
+setup code, we're required at the very least to provide definitions for
+get_system_type() and platform_setup(). For our imaginary board, this
+might look something like::
+
+ /*
+ * arch/sh/boards/vapor/setup.c - Setup code for imaginary board
+ */
+ #include <linux/init.h>
+
+ const char *get_system_type(void)
+ {
+ return "FooTech Vaporboard";
+ }
+
+ int __init platform_setup(void)
+ {
+ /*
+ * If our hardware actually existed, we would do real
+ * setup here. Though it's also sane to leave this empty
+ * if there's no real init work that has to be done for
+ * this board.
+ */
+
+ /* Start-up imaginary PCI ... */
+
+ /* And whatever else ... */
+
+ return 0;
+ }
+
+Our new imaginary board will also have to tie into the machvec in order for it
+to be of any use.
+
+machvec functions fall into a number of categories:
+
+ - I/O functions to IO memory (inb etc) and PCI/main memory (readb etc).
+ - I/O mapping functions (ioport_map, ioport_unmap, etc).
+ - a 'heartbeat' function.
+ - PCI and IRQ initialization routines.
+ - Consistent allocators (for boards that need special allocators,
+ particularly for allocating out of some board-specific SRAM for DMA
+ handles).
+
+There are machvec functions added and removed over time, so always be sure to
+consult include/asm-sh/machvec.h for the current state of the machvec.
+
+The kernel will automatically wrap in generic routines for undefined function
+pointers in the machvec at boot time, as machvec functions are referenced
+unconditionally throughout most of the tree. Some boards have incredibly
+sparse machvecs (such as the dreamcast and sh03), whereas others must define
+virtually everything (rts7751r2d).
+
+Adding a new machine is relatively trivial (using vapor as an example):
+
+If the board-specific definitions are quite minimalistic, as is the case for
+the vast majority of boards, simply having a single board-specific header is
+sufficient.
+
+ - add a new file include/asm-sh/vapor.h which contains prototypes for
+ any machine specific IO functions prefixed with the machine name, for
+ example vapor_inb. These will be needed when filling out the machine
+ vector.
+
+ Note that these prototypes are generated automatically by setting
+ __IO_PREFIX to something sensible. A typical example would be::
+
+ #define __IO_PREFIX vapor
+ #include <asm/io_generic.h>
+
+ somewhere in the board-specific header. Any boards being ported that still
+ have a legacy io.h should remove it entirely and switch to the new model.
+
+ - Add machine vector definitions to the board's setup.c. At a bare minimum,
+ this must be defined as something like::
+
+ struct sh_machine_vector mv_vapor __initmv = {
+ .mv_name = "vapor",
+ };
+ ALIAS_MV(vapor)
+
+ - finally add a file arch/sh/boards/vapor/io.c, which contains definitions of
+ the machine specific io functions (if there are enough to warrant it).
+
+3. Hooking into the Build System
+================================
+
+Now that we have the corresponding directories setup, and all of the
+board-specific code is in place, it's time to look at how to get the
+whole mess to fit into the build system.
+
+Large portions of the build system are now entirely dynamic, and merely
+require the proper entry here and there in order to get things done.
+
+The first thing to do is to add an entry to arch/sh/Kconfig, under the
+"System type" menu::
+
+ config SH_VAPOR
+ bool "Vapor"
+ help
+ select Vapor if configuring for a FooTech Vaporboard.
+
+next, this has to be added into arch/sh/Makefile. All boards require a
+machdir-y entry in order to be built. This entry needs to be the name of
+the board directory as it appears in arch/sh/boards, even if it is in a
+sub-directory (in which case, all parent directories below arch/sh/boards/
+need to be listed). For our new board, this entry can look like::
+
+ machdir-$(CONFIG_SH_VAPOR) += vapor
+
+provided that we've placed everything in the arch/sh/boards/vapor/ directory.
+
+Next, the build system assumes that your include/asm-sh directory will also
+be named the same. If this is not the case (as is the case with multiple
+boards belonging to a common family), then the directory name needs to be
+implicitly appended to incdir-y. The existing code manages this for the
+Solution Engine and hp6xx boards, so see these for an example.
+
+Once that is taken care of, it's time to add an entry for the mach type.
+This is done by adding an entry to the end of the arch/sh/tools/mach-types
+list. The method for doing this is self explanatory, and so we won't waste
+space restating it here. After this is done, you will be able to use
+implicit checks for your board if you need this somewhere throughout the
+common code, such as::
+
+ /* Make sure we're on the FooTech Vaporboard */
+ if (!mach_is_vapor())
+ return -ENODEV;
+
+also note that the mach_is_boardname() check will be implicitly forced to
+lowercase, regardless of the fact that the mach-types entries are all
+uppercase. You can read the script if you really care, but it's pretty ugly,
+so you probably don't want to do that.
+
+Now all that's left to do is providing a defconfig for your new board. This
+way, other people who end up with this board can simply use this config
+for reference instead of trying to guess what settings are supposed to be
+used on it.
+
+Also, as soon as you have copied over a sample .config for your new board
+(assume arch/sh/configs/vapor_defconfig), you can also use this directly as a
+build target, and it will be implicitly listed as such in the help text.
+
+Looking at the 'make help' output, you should now see something like:
+
+Architecture specific targets (sh):
+
+ ======================= =============================================
+ zImage Compressed kernel image (arch/sh/boot/zImage)
+ adx_defconfig Build for adx
+ cqreek_defconfig Build for cqreek
+ dreamcast_defconfig Build for dreamcast
+ ...
+ vapor_defconfig Build for vapor
+ ======================= =============================================
+
+which then allows you to do::
+
+ $ make ARCH=sh CROSS_COMPILE=sh4-linux- vapor_defconfig vmlinux
+
+which will in turn copy the defconfig for this board, run it through
+oldconfig (prompting you for any new options since the time of creation),
+and start you on your way to having a functional kernel for your new
+board.
diff --git a/Documentation/sh/new-machine.txt b/Documentation/sh/new-machine.txt
deleted file mode 100644
index e0961a66..0000000
--- a/Documentation/sh/new-machine.txt
+++ /dev/null
@@ -1,270 +0,0 @@
-
- Adding a new board to LinuxSH
- ================================
-
- Paul Mundt <lethal@linux-sh.org>
-
-This document attempts to outline what steps are necessary to add support
-for new boards to the LinuxSH port under the new 2.5 and 2.6 kernels. This
-also attempts to outline some of the noticeable changes between the 2.4
-and the 2.5/2.6 SH backend.
-
-1. New Directory Structure
-==========================
-
-The first thing to note is the new directory structure. Under 2.4, most
-of the board-specific code (with the exception of stboards) ended up
-in arch/sh/kernel/ directly, with board-specific headers ending up in
-include/asm-sh/. For the new kernel, things are broken out by board type,
-companion chip type, and CPU type. Looking at a tree view of this directory
-hierarchy looks like the following:
-
-Board-specific code:
-
-.
-|-- arch
-| `-- sh
-| `-- boards
-| |-- adx
-| | `-- board-specific files
-| |-- bigsur
-| | `-- board-specific files
-| |
-| ... more boards here ...
-|
-`-- include
- `-- asm-sh
- |-- adx
- | `-- board-specific headers
- |-- bigsur
- | `-- board-specific headers
- |
- .. more boards here ...
-
-Next, for companion chips:
-.
-`-- arch
- `-- sh
- `-- cchips
- `-- hd6446x
- `-- hd64461
- `-- cchip-specific files
-
-... and so on. Headers for the companion chips are treated the same way as
-board-specific headers. Thus, include/asm-sh/hd64461 is home to all of the
-hd64461-specific headers.
-
-Finally, CPU family support is also abstracted:
-.
-|-- arch
-| `-- sh
-| |-- kernel
-| | `-- cpu
-| | |-- sh2
-| | | `-- SH-2 generic files
-| | |-- sh3
-| | | `-- SH-3 generic files
-| | `-- sh4
-| | `-- SH-4 generic files
-| `-- mm
-| `-- This is also broken out per CPU family, so each family can
-| have their own set of cache/tlb functions.
-|
-`-- include
- `-- asm-sh
- |-- cpu-sh2
- | `-- SH-2 specific headers
- |-- cpu-sh3
- | `-- SH-3 specific headers
- `-- cpu-sh4
- `-- SH-4 specific headers
-
-It should be noted that CPU subtypes are _not_ abstracted. Thus, these still
-need to be dealt with by the CPU family specific code.
-
-2. Adding a New Board
-=====================
-
-The first thing to determine is whether the board you are adding will be
-isolated, or whether it will be part of a family of boards that can mostly
-share the same board-specific code with minor differences.
-
-In the first case, this is just a matter of making a directory for your
-board in arch/sh/boards/ and adding rules to hook your board in with the
-build system (more on this in the next section). However, for board families
-it makes more sense to have a common top-level arch/sh/boards/ directory
-and then populate that with sub-directories for each member of the family.
-Both the Solution Engine and the hp6xx boards are an example of this.
-
-After you have setup your new arch/sh/boards/ directory, remember that you
-should also add a directory in include/asm-sh for headers localized to this
-board (if there are going to be more than one). In order to interoperate
-seamlessly with the build system, it's best to have this directory the same
-as the arch/sh/boards/ directory name, though if your board is again part of
-a family, the build system has ways of dealing with this (via incdir-y
-overloading), and you can feel free to name the directory after the family
-member itself.
-
-There are a few things that each board is required to have, both in the
-arch/sh/boards and the include/asm-sh/ hierarchy. In order to better
-explain this, we use some examples for adding an imaginary board. For
-setup code, we're required at the very least to provide definitions for
-get_system_type() and platform_setup(). For our imaginary board, this
-might look something like:
-
-/*
- * arch/sh/boards/vapor/setup.c - Setup code for imaginary board
- */
-#include <linux/init.h>
-
-const char *get_system_type(void)
-{
- return "FooTech Vaporboard";
-}
-
-int __init platform_setup(void)
-{
- /*
- * If our hardware actually existed, we would do real
- * setup here. Though it's also sane to leave this empty
- * if there's no real init work that has to be done for
- * this board.
- */
-
- /* Start-up imaginary PCI ... */
-
- /* And whatever else ... */
-
- return 0;
-}
-
-Our new imaginary board will also have to tie into the machvec in order for it
-to be of any use.
-
-machvec functions fall into a number of categories:
-
- - I/O functions to IO memory (inb etc) and PCI/main memory (readb etc).
- - I/O mapping functions (ioport_map, ioport_unmap, etc).
- - a 'heartbeat' function.
- - PCI and IRQ initialization routines.
- - Consistent allocators (for boards that need special allocators,
- particularly for allocating out of some board-specific SRAM for DMA
- handles).
-
-There are machvec functions added and removed over time, so always be sure to
-consult include/asm-sh/machvec.h for the current state of the machvec.
-
-The kernel will automatically wrap in generic routines for undefined function
-pointers in the machvec at boot time, as machvec functions are referenced
-unconditionally throughout most of the tree. Some boards have incredibly
-sparse machvecs (such as the dreamcast and sh03), whereas others must define
-virtually everything (rts7751r2d).
-
-Adding a new machine is relatively trivial (using vapor as an example):
-
-If the board-specific definitions are quite minimalistic, as is the case for
-the vast majority of boards, simply having a single board-specific header is
-sufficient.
-
- - add a new file include/asm-sh/vapor.h which contains prototypes for
- any machine specific IO functions prefixed with the machine name, for
- example vapor_inb. These will be needed when filling out the machine
- vector.
-
- Note that these prototypes are generated automatically by setting
- __IO_PREFIX to something sensible. A typical example would be:
-
- #define __IO_PREFIX vapor
- #include <asm/io_generic.h>
-
- somewhere in the board-specific header. Any boards being ported that still
- have a legacy io.h should remove it entirely and switch to the new model.
-
- - Add machine vector definitions to the board's setup.c. At a bare minimum,
- this must be defined as something like:
-
- struct sh_machine_vector mv_vapor __initmv = {
- .mv_name = "vapor",
- };
- ALIAS_MV(vapor)
-
- - finally add a file arch/sh/boards/vapor/io.c, which contains definitions of
- the machine specific io functions (if there are enough to warrant it).
-
-3. Hooking into the Build System
-================================
-
-Now that we have the corresponding directories setup, and all of the
-board-specific code is in place, it's time to look at how to get the
-whole mess to fit into the build system.
-
-Large portions of the build system are now entirely dynamic, and merely
-require the proper entry here and there in order to get things done.
-
-The first thing to do is to add an entry to arch/sh/Kconfig, under the
-"System type" menu:
-
-config SH_VAPOR
- bool "Vapor"
- help
- select Vapor if configuring for a FooTech Vaporboard.
-
-next, this has to be added into arch/sh/Makefile. All boards require a
-machdir-y entry in order to be built. This entry needs to be the name of
-the board directory as it appears in arch/sh/boards, even if it is in a
-sub-directory (in which case, all parent directories below arch/sh/boards/
-need to be listed). For our new board, this entry can look like:
-
-machdir-$(CONFIG_SH_VAPOR) += vapor
-
-provided that we've placed everything in the arch/sh/boards/vapor/ directory.
-
-Next, the build system assumes that your include/asm-sh directory will also
-be named the same. If this is not the case (as is the case with multiple
-boards belonging to a common family), then the directory name needs to be
-implicitly appended to incdir-y. The existing code manages this for the
-Solution Engine and hp6xx boards, so see these for an example.
-
-Once that is taken care of, it's time to add an entry for the mach type.
-This is done by adding an entry to the end of the arch/sh/tools/mach-types
-list. The method for doing this is self explanatory, and so we won't waste
-space restating it here. After this is done, you will be able to use
-implicit checks for your board if you need this somewhere throughout the
-common code, such as:
-
- /* Make sure we're on the FooTech Vaporboard */
- if (!mach_is_vapor())
- return -ENODEV;
-
-also note that the mach_is_boardname() check will be implicitly forced to
-lowercase, regardless of the fact that the mach-types entries are all
-uppercase. You can read the script if you really care, but it's pretty ugly,
-so you probably don't want to do that.
-
-Now all that's left to do is providing a defconfig for your new board. This
-way, other people who end up with this board can simply use this config
-for reference instead of trying to guess what settings are supposed to be
-used on it.
-
-Also, as soon as you have copied over a sample .config for your new board
-(assume arch/sh/configs/vapor_defconfig), you can also use this directly as a
-build target, and it will be implicitly listed as such in the help text.
-
-Looking at the 'make help' output, you should now see something like:
-
-Architecture specific targets (sh):
- zImage - Compressed kernel image (arch/sh/boot/zImage)
- adx_defconfig - Build for adx
- cqreek_defconfig - Build for cqreek
- dreamcast_defconfig - Build for dreamcast
-...
- vapor_defconfig - Build for vapor
-
-which then allows you to do:
-
-$ make ARCH=sh CROSS_COMPILE=sh4-linux- vapor_defconfig vmlinux
-
-which will in turn copy the defconfig for this board, run it through
-oldconfig (prompting you for any new options since the time of creation),
-and start you on your way to having a functional kernel for your new
-board.
diff --git a/Documentation/sh/register-banks.rst b/Documentation/sh/register-banks.rst
new file mode 100644
index 0000000..2bef5c8f
--- /dev/null
+++ b/Documentation/sh/register-banks.rst
@@ -0,0 +1,40 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+==========================================
+Notes on register bank usage in the kernel
+==========================================
+
+Introduction
+------------
+
+The SH-3 and SH-4 CPU families traditionally include a single partial register
+bank (selected by SR.RB, only r0 ... r7 are banked), whereas other families
+may have more full-featured banking or simply no such capabilities at all.
+
+SR.RB banking
+-------------
+
+In the case of this type of banking, banked registers are mapped directly to
+r0 ... r7 if SR.RB is set to the bank we are interested in, otherwise ldc/stc
+can still be used to reference the banked registers (as r0_bank ... r7_bank)
+when in the context of another bank. The developer must keep the SR.RB value
+in mind when writing code that utilizes these banked registers, for obvious
+reasons. Userspace is also not able to poke at the bank1 values, so these can
+be used rather effectively as scratch registers by the kernel.
+
+Presently the kernel uses several of these registers.
+
+ - r0_bank, r1_bank (referenced as k0 and k1, used for scratch
+ registers when doing exception handling).
+
+ - r2_bank (used to track the EXPEVT/INTEVT code)
+
+ - Used by do_IRQ() and friends for doing irq mapping based off
+ of the interrupt exception vector jump table offset
+
+ - r6_bank (global interrupt mask)
+
+ - The SR.IMASK interrupt handler makes use of this to set the
+ interrupt priority level (used by local_irq_enable())
+
+ - r7_bank (current)
diff --git a/Documentation/sh/register-banks.txt b/Documentation/sh/register-banks.txt
deleted file mode 100644
index a6719f2..0000000
--- a/Documentation/sh/register-banks.txt
+++ /dev/null
@@ -1,33 +0,0 @@
- Notes on register bank usage in the kernel
- ==========================================
-
-Introduction
-------------
-
-The SH-3 and SH-4 CPU families traditionally include a single partial register
-bank (selected by SR.RB, only r0 ... r7 are banked), whereas other families
-may have more full-featured banking or simply no such capabilities at all.
-
-SR.RB banking
--------------
-
-In the case of this type of banking, banked registers are mapped directly to
-r0 ... r7 if SR.RB is set to the bank we are interested in, otherwise ldc/stc
-can still be used to reference the banked registers (as r0_bank ... r7_bank)
-when in the context of another bank. The developer must keep the SR.RB value
-in mind when writing code that utilizes these banked registers, for obvious
-reasons. Userspace is also not able to poke at the bank1 values, so these can
-be used rather effectively as scratch registers by the kernel.
-
-Presently the kernel uses several of these registers.
-
- - r0_bank, r1_bank (referenced as k0 and k1, used for scratch
- registers when doing exception handling).
- - r2_bank (used to track the EXPEVT/INTEVT code)
- - Used by do_IRQ() and friends for doing irq mapping based off
- of the interrupt exception vector jump table offset
- - r6_bank (global interrupt mask)
- - The SR.IMASK interrupt handler makes use of this to set the
- interrupt priority level (used by local_irq_enable())
- - r7_bank (current)
-
diff --git a/Documentation/sound/alsa-configuration.rst b/Documentation/sound/alsa-configuration.rst
index 72f97d4..c755b1c 100644
--- a/Documentation/sound/alsa-configuration.rst
+++ b/Documentation/sound/alsa-configuration.rst
@@ -309,7 +309,7 @@
This module supports all ADB PCM channels, ac97 mixer, SPDIF, hardware
EQ, mpu401, gameport. A3D and wavetable support are still in development.
Development and reverse engineering work is being coordinated at
-http://savannah.nongnu.org/projects/openvortex/
+https://savannah.nongnu.org/projects/openvortex/
SPDIF output has a copy of the AC97 codec output, unless you use the
``spdif`` pcm device, which allows raw data passthru.
The hardware EQ hardware and SPDIF is only present in the Vortex2 and
@@ -1575,7 +1575,7 @@
about this driver. Note that it has been discontinued, but the
Voyetra Turtle Beach knowledge base entry for it is still available
at
-http://www.turtlebeach.com
+https://www.turtlebeach.com
Module snd-msnd-pinnacle
------------------------
@@ -2703,4 +2703,4 @@
ALSA Developers ML
mailto:alsa-devel@alsa-project.org
alsa-info.sh script
- http://www.alsa-project.org/alsa-info.sh
+ https://www.alsa-project.org/alsa-info.sh
diff --git a/Documentation/sound/cards/audigy-mixer.rst b/Documentation/sound/cards/audigy-mixer.rst
index 8621323..998f76e 100644
--- a/Documentation/sound/cards/audigy-mixer.rst
+++ b/Documentation/sound/cards/audigy-mixer.rst
@@ -331,7 +331,7 @@
Execution and Audio Data Sequencing (Jan. 14, 1999)
-US Patents (http://www.uspto.gov/)
+US Patents (https://www.uspto.gov/)
----------------------------------
US 5925841
diff --git a/Documentation/sound/cards/sb-live-mixer.rst b/Documentation/sound/cards/sb-live-mixer.rst
index bcb62fc..eccb0f0 100644
--- a/Documentation/sound/cards/sb-live-mixer.rst
+++ b/Documentation/sound/cards/sb-live-mixer.rst
@@ -336,7 +336,7 @@
Execution and Audio Data Sequencing (Jan. 14, 1999)
-US Patents (http://www.uspto.gov/)
+US Patents (https://www.uspto.gov/)
----------------------------------
US 5925841
diff --git a/Documentation/sound/designs/compress-offload.rst b/Documentation/sound/designs/compress-offload.rst
index ad4bfbd..935f325 100644
--- a/Documentation/sound/designs/compress-offload.rst
+++ b/Documentation/sound/designs/compress-offload.rst
@@ -151,6 +151,57 @@
- Addition of encoding options when required (derived from OpenMAX IL)
- Addition of rateControlSupported (missing in OpenMAX AL)
+State Machine
+=============
+
+The compressed audio stream state machine is described below ::
+
+ +----------+
+ | |
+ | OPEN |
+ | |
+ +----------+
+ |
+ |
+ | compr_set_params()
+ |
+ v
+ compr_free() +----------+
+ +------------------------------------| |
+ | | SETUP |
+ | +-------------------------| |<-------------------------+
+ | | compr_write() +----------+ |
+ | | ^ |
+ | | | compr_drain_notify() |
+ | | | or |
+ | | | compr_stop() |
+ | | | |
+ | | +----------+ |
+ | | | | |
+ | | | DRAIN | |
+ | | | | |
+ | | +----------+ |
+ | | ^ |
+ | | | |
+ | | | compr_drain() |
+ | | | |
+ | v | |
+ | +----------+ +----------+ |
+ | | | compr_start() | | compr_stop() |
+ | | PREPARE |------------------->| RUNNING |--------------------------+
+ | | | | | |
+ | +----------+ +----------+ |
+ | | | ^ |
+ | |compr_free() | | |
+ | | compr_pause() | | compr_resume() |
+ | | | | |
+ | v v | |
+ | +----------+ +----------+ |
+ | | | | | compr_stop() |
+ +--->| FREE | | PAUSE |---------------------------+
+ | | | |
+ +----------+ +----------+
+
Gapless Playback
================
@@ -199,6 +250,38 @@
(note: order for partial_drain and write for next track can be reversed as well)
+Gapless Playback SM
+===================
+
+For Gapless, we move from running state to partial drain and back, along
+with setting of meta_data and signalling for next track ::
+
+
+ +----------+
+ compr_drain_notify() | |
+ +------------------------>| RUNNING |
+ | | |
+ | +----------+
+ | |
+ | |
+ | | compr_next_track()
+ | |
+ | V
+ | +----------+
+ | | |
+ | |NEXT_TRACK|
+ | | |
+ | +----------+
+ | |
+ | |
+ | | compr_partial_drain()
+ | |
+ | V
+ | +----------+
+ | | |
+ +------------------------ | PARTIAL_ |
+ | DRAIN |
+ +----------+
Not supported
=============
diff --git a/Documentation/sound/designs/procfile.rst b/Documentation/sound/designs/procfile.rst
index 29a4668..e9f7e0c 100644
--- a/Documentation/sound/designs/procfile.rst
+++ b/Documentation/sound/designs/procfile.rst
@@ -91,7 +91,7 @@
``card*/pcm*/xrun_debug``
This file appears when ``CONFIG_SND_DEBUG=y`` and
- ``CONFIG_PCM_XRUN_DEBUG=y``.
+ ``CONFIG_SND_PCM_XRUN_DEBUG=y``.
This shows the status of xrun (= buffer overrun/xrun) and
invalid PCM position debug/check of ALSA PCM middle layer.
It takes an integer value, can be changed by writing to this
diff --git a/Documentation/sound/hd-audio/notes.rst b/Documentation/sound/hd-audio/notes.rst
index 0f3109d..cf4d7158 100644
--- a/Documentation/sound/hd-audio/notes.rst
+++ b/Documentation/sound/hd-audio/notes.rst
@@ -42,7 +42,7 @@
HD-audio specification at first. The specification is found on
Intel's web page, for example:
-* http://www.intel.com/standards/hdaudio/
+* https://www.intel.com/standards/hdaudio/
HD-Audio Controller
@@ -728,7 +728,7 @@
The script can be fetched directly from the following URL, too:
-* http://www.alsa-project.org/alsa-info.sh
+* https://www.alsa-project.org/alsa-info.sh
Run this script as root, and it will gather the important information
such as the module lists, module parameters, proc file contents
@@ -818,7 +818,7 @@
The hda-analyzer:
-* http://git.alsa-project.org/?p=alsa.git;a=tree;f=hda-analyzer
+* https://git.alsa-project.org/?p=alsa.git;a=tree;f=hda-analyzer
is a part of alsa.git repository in alsa-project.org:
diff --git a/Documentation/sound/kernel-api/alsa-driver-api.rst b/Documentation/sound/kernel-api/alsa-driver-api.rst
index 14cd138..c8cc651 100644
--- a/Documentation/sound/kernel-api/alsa-driver-api.rst
+++ b/Documentation/sound/kernel-api/alsa-driver-api.rst
@@ -99,7 +99,7 @@
.. kernel-doc:: include/sound/soc.h
.. kernel-doc:: sound/soc/soc-core.c
.. kernel-doc:: sound/soc/soc-devres.c
-.. kernel-doc:: sound/soc/soc-io.c
+.. kernel-doc:: sound/soc/soc-component.c
.. kernel-doc:: sound/soc/soc-pcm.c
.. kernel-doc:: sound/soc/soc-ops.c
.. kernel-doc:: sound/soc/soc-compress.c
diff --git a/Documentation/sound/kernel-api/writing-an-alsa-driver.rst b/Documentation/sound/kernel-api/writing-an-alsa-driver.rst
index fa49688..aa9d5ab 100644
--- a/Documentation/sound/kernel-api/writing-an-alsa-driver.rst
+++ b/Documentation/sound/kernel-api/writing-an-alsa-driver.rst
@@ -3579,7 +3579,7 @@
``SNDRV_DMA_TYPE_DEV`` type. For the continuous buffer unrelated to the
bus can be pre-allocated with ``SNDRV_DMA_TYPE_CONTINUOUS`` type.
You can pass NULL to the device pointer in that case, which is the
-default mode implying to allocate with ``GFP_KRENEL`` flag.
+default mode implying to allocate with ``GFP_KERNEL`` flag.
If you need a different GFP flag, you can pass it by encoding the flag
into the device pointer via a special macro
:c:func:`snd_dma_continuous_data()`.
diff --git a/Documentation/sound/soc/dai.rst b/Documentation/sound/soc/dai.rst
index 2e99183..009b07e 100644
--- a/Documentation/sound/soc/dai.rst
+++ b/Documentation/sound/soc/dai.rst
@@ -17,7 +17,7 @@
frame is 21uS long and is divided into 13 time slots.
The AC97 specification can be found at :
-http://www.intel.com/p/en_US/business/design
+https://www.intel.com/p/en_US/business/design
I2S
diff --git a/Documentation/speculation.txt b/Documentation/speculation.txt
deleted file mode 100644
index 50d7ea85..0000000
--- a/Documentation/speculation.txt
+++ /dev/null
@@ -1,90 +0,0 @@
-This document explains potential effects of speculation, and how undesirable
-effects can be mitigated portably using common APIs.
-
-===========
-Speculation
-===========
-
-To improve performance and minimize average latencies, many contemporary CPUs
-employ speculative execution techniques such as branch prediction, performing
-work which may be discarded at a later stage.
-
-Typically speculative execution cannot be observed from architectural state,
-such as the contents of registers. However, in some cases it is possible to
-observe its impact on microarchitectural state, such as the presence or
-absence of data in caches. Such state may form side-channels which can be
-observed to extract secret information.
-
-For example, in the presence of branch prediction, it is possible for bounds
-checks to be ignored by code which is speculatively executed. Consider the
-following code::
-
- int load_array(int *array, unsigned int index)
- {
- if (index >= MAX_ARRAY_ELEMS)
- return 0;
- else
- return array[index];
- }
-
-Which, on arm64, may be compiled to an assembly sequence such as::
-
- CMP <index>, #MAX_ARRAY_ELEMS
- B.LT less
- MOV <returnval>, #0
- RET
- less:
- LDR <returnval>, [<array>, <index>]
- RET
-
-It is possible that a CPU mis-predicts the conditional branch, and
-speculatively loads array[index], even if index >= MAX_ARRAY_ELEMS. This
-value will subsequently be discarded, but the speculated load may affect
-microarchitectural state which can be subsequently measured.
-
-More complex sequences involving multiple dependent memory accesses may
-result in sensitive information being leaked. Consider the following
-code, building on the prior example::
-
- int load_dependent_arrays(int *arr1, int *arr2, int index)
- {
- int val1, val2,
-
- val1 = load_array(arr1, index);
- val2 = load_array(arr2, val1);
-
- return val2;
- }
-
-Under speculation, the first call to load_array() may return the value
-of an out-of-bounds address, while the second call will influence
-microarchitectural state dependent on this value. This may provide an
-arbitrary read primitive.
-
-====================================
-Mitigating speculation side-channels
-====================================
-
-The kernel provides a generic API to ensure that bounds checks are
-respected even under speculation. Architectures which are affected by
-speculation-based side-channels are expected to implement these
-primitives.
-
-The array_index_nospec() helper in <linux/nospec.h> can be used to
-prevent information from being leaked via side-channels.
-
-A call to array_index_nospec(index, size) returns a sanitized index
-value that is bounded to [0, size) even under cpu speculation
-conditions.
-
-This can be used to protect the earlier load_array() example::
-
- int load_array(int *array, unsigned int index)
- {
- if (index >= MAX_ARRAY_ELEMS)
- return 0;
- else {
- index = array_index_nospec(index, MAX_ARRAY_ELEMS);
- return array[index];
- }
- }
diff --git a/Documentation/sphinx/parse-headers.pl b/Documentation/sphinx/parse-headers.pl
index c518050..00a69ac 100755
--- a/Documentation/sphinx/parse-headers.pl
+++ b/Documentation/sphinx/parse-headers.pl
@@ -393,7 +393,7 @@
Copyright (c) 2016 by Mauro Carvalho Chehab <mchehab+samsung@kernel.org>.
-License GPLv2: GNU GPL version 2 <http://gnu.org/licenses/gpl.html>.
+License GPLv2: GNU GPL version 2 <https://gnu.org/licenses/gpl.html>.
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.
diff --git a/Documentation/spi/spi-sc18is602.rst b/Documentation/spi/spi-sc18is602.rst
index 2a31dc7..4ab9ca3 100644
--- a/Documentation/spi/spi-sc18is602.rst
+++ b/Documentation/spi/spi-sc18is602.rst
@@ -6,7 +6,7 @@
* NXP SI18IS602/602B/603
- Datasheet: http://www.nxp.com/documents/data_sheet/SC18IS602_602B_603.pdf
+ Datasheet: https://www.nxp.com/documents/data_sheet/SC18IS602_602B_603.pdf
Author:
Guenter Roeck <linux@roeck-us.net>
diff --git a/Documentation/crc32.txt b/Documentation/staging/crc32.rst
similarity index 100%
rename from Documentation/crc32.txt
rename to Documentation/staging/crc32.rst
diff --git a/Documentation/staging/index.rst b/Documentation/staging/index.rst
new file mode 100644
index 0000000..abd0d18
--- /dev/null
+++ b/Documentation/staging/index.rst
@@ -0,0 +1,58 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+Unsorted Documentation
+======================
+
+.. toctree::
+ :maxdepth: 2
+
+ crc32
+ lzo
+ remoteproc
+ rpmsg
+ speculation
+ static-keys
+ tee
+ xz
+
+Atomic Types
+============
+
+.. raw:: latex
+
+ \footnotesize
+
+.. include:: ../atomic_t.txt
+ :literal:
+
+.. raw:: latex
+
+ \normalsize
+
+Atomic bitops
+=============
+
+.. raw:: latex
+
+ \footnotesize
+
+.. include:: ../atomic_bitops.txt
+ :literal:
+
+.. raw:: latex
+
+ \normalsize
+
+Memory Barriers
+===============
+
+.. raw:: latex
+
+ \footnotesize
+
+.. include:: ../memory-barriers.txt
+ :literal:
+
+.. raw:: latex
+
+ \normalsize
diff --git a/Documentation/lzo.txt b/Documentation/staging/lzo.rst
similarity index 100%
rename from Documentation/lzo.txt
rename to Documentation/staging/lzo.rst
diff --git a/Documentation/staging/remoteproc.rst b/Documentation/staging/remoteproc.rst
new file mode 100644
index 0000000..9cccd3d
--- /dev/null
+++ b/Documentation/staging/remoteproc.rst
@@ -0,0 +1,359 @@
+==========================
+Remote Processor Framework
+==========================
+
+Introduction
+============
+
+Modern SoCs typically have heterogeneous remote processor devices in asymmetric
+multiprocessing (AMP) configurations, which may be running different instances
+of operating system, whether it's Linux or any other flavor of real-time OS.
+
+OMAP4, for example, has dual Cortex-A9, dual Cortex-M3 and a C64x+ DSP.
+In a typical configuration, the dual cortex-A9 is running Linux in a SMP
+configuration, and each of the other three cores (two M3 cores and a DSP)
+is running its own instance of RTOS in an AMP configuration.
+
+The remoteproc framework allows different platforms/architectures to
+control (power on, load firmware, power off) those remote processors while
+abstracting the hardware differences, so the entire driver doesn't need to be
+duplicated. In addition, this framework also adds rpmsg virtio devices
+for remote processors that supports this kind of communication. This way,
+platform-specific remoteproc drivers only need to provide a few low-level
+handlers, and then all rpmsg drivers will then just work
+(for more information about the virtio-based rpmsg bus and its drivers,
+please read Documentation/staging/rpmsg.rst).
+Registration of other types of virtio devices is now also possible. Firmwares
+just need to publish what kind of virtio devices do they support, and then
+remoteproc will add those devices. This makes it possible to reuse the
+existing virtio drivers with remote processor backends at a minimal development
+cost.
+
+User API
+========
+
+::
+
+ int rproc_boot(struct rproc *rproc)
+
+Boot a remote processor (i.e. load its firmware, power it on, ...).
+
+If the remote processor is already powered on, this function immediately
+returns (successfully).
+
+Returns 0 on success, and an appropriate error value otherwise.
+Note: to use this function you should already have a valid rproc
+handle. There are several ways to achieve that cleanly (devres, pdata,
+the way remoteproc_rpmsg.c does this, or, if this becomes prevalent, we
+might also consider using dev_archdata for this).
+
+::
+
+ void rproc_shutdown(struct rproc *rproc)
+
+Power off a remote processor (previously booted with rproc_boot()).
+In case @rproc is still being used by an additional user(s), then
+this function will just decrement the power refcount and exit,
+without really powering off the device.
+
+Every call to rproc_boot() must (eventually) be accompanied by a call
+to rproc_shutdown(). Calling rproc_shutdown() redundantly is a bug.
+
+.. note::
+
+ we're not decrementing the rproc's refcount, only the power refcount.
+ which means that the @rproc handle stays valid even after
+ rproc_shutdown() returns, and users can still use it with a subsequent
+ rproc_boot(), if needed.
+
+::
+
+ struct rproc *rproc_get_by_phandle(phandle phandle)
+
+Find an rproc handle using a device tree phandle. Returns the rproc
+handle on success, and NULL on failure. This function increments
+the remote processor's refcount, so always use rproc_put() to
+decrement it back once rproc isn't needed anymore.
+
+Typical usage
+=============
+
+::
+
+ #include <linux/remoteproc.h>
+
+ /* in case we were given a valid 'rproc' handle */
+ int dummy_rproc_example(struct rproc *my_rproc)
+ {
+ int ret;
+
+ /* let's power on and boot our remote processor */
+ ret = rproc_boot(my_rproc);
+ if (ret) {
+ /*
+ * something went wrong. handle it and leave.
+ */
+ }
+
+ /*
+ * our remote processor is now powered on... give it some work
+ */
+
+ /* let's shut it down now */
+ rproc_shutdown(my_rproc);
+ }
+
+API for implementors
+====================
+
+::
+
+ struct rproc *rproc_alloc(struct device *dev, const char *name,
+ const struct rproc_ops *ops,
+ const char *firmware, int len)
+
+Allocate a new remote processor handle, but don't register
+it yet. Required parameters are the underlying device, the
+name of this remote processor, platform-specific ops handlers,
+the name of the firmware to boot this rproc with, and the
+length of private data needed by the allocating rproc driver (in bytes).
+
+This function should be used by rproc implementations during
+initialization of the remote processor.
+
+After creating an rproc handle using this function, and when ready,
+implementations should then call rproc_add() to complete
+the registration of the remote processor.
+
+On success, the new rproc is returned, and on failure, NULL.
+
+.. note::
+
+ **never** directly deallocate @rproc, even if it was not registered
+ yet. Instead, when you need to unroll rproc_alloc(), use rproc_free().
+
+::
+
+ void rproc_free(struct rproc *rproc)
+
+Free an rproc handle that was allocated by rproc_alloc.
+
+This function essentially unrolls rproc_alloc(), by decrementing the
+rproc's refcount. It doesn't directly free rproc; that would happen
+only if there are no other references to rproc and its refcount now
+dropped to zero.
+
+::
+
+ int rproc_add(struct rproc *rproc)
+
+Register @rproc with the remoteproc framework, after it has been
+allocated with rproc_alloc().
+
+This is called by the platform-specific rproc implementation, whenever
+a new remote processor device is probed.
+
+Returns 0 on success and an appropriate error code otherwise.
+Note: this function initiates an asynchronous firmware loading
+context, which will look for virtio devices supported by the rproc's
+firmware.
+
+If found, those virtio devices will be created and added, so as a result
+of registering this remote processor, additional virtio drivers might get
+probed.
+
+::
+
+ int rproc_del(struct rproc *rproc)
+
+Unroll rproc_add().
+
+This function should be called when the platform specific rproc
+implementation decides to remove the rproc device. it should
+_only_ be called if a previous invocation of rproc_add()
+has completed successfully.
+
+After rproc_del() returns, @rproc is still valid, and its
+last refcount should be decremented by calling rproc_free().
+
+Returns 0 on success and -EINVAL if @rproc isn't valid.
+
+::
+
+ void rproc_report_crash(struct rproc *rproc, enum rproc_crash_type type)
+
+Report a crash in a remoteproc
+
+This function must be called every time a crash is detected by the
+platform specific rproc implementation. This should not be called from a
+non-remoteproc driver. This function can be called from atomic/interrupt
+context.
+
+Implementation callbacks
+========================
+
+These callbacks should be provided by platform-specific remoteproc
+drivers::
+
+ /**
+ * struct rproc_ops - platform-specific device handlers
+ * @start: power on the device and boot it
+ * @stop: power off the device
+ * @kick: kick a virtqueue (virtqueue id given as a parameter)
+ */
+ struct rproc_ops {
+ int (*start)(struct rproc *rproc);
+ int (*stop)(struct rproc *rproc);
+ void (*kick)(struct rproc *rproc, int vqid);
+ };
+
+Every remoteproc implementation should at least provide the ->start and ->stop
+handlers. If rpmsg/virtio functionality is also desired, then the ->kick handler
+should be provided as well.
+
+The ->start() handler takes an rproc handle and should then power on the
+device and boot it (use rproc->priv to access platform-specific private data).
+The boot address, in case needed, can be found in rproc->bootaddr (remoteproc
+core puts there the ELF entry point).
+On success, 0 should be returned, and on failure, an appropriate error code.
+
+The ->stop() handler takes an rproc handle and powers the device down.
+On success, 0 is returned, and on failure, an appropriate error code.
+
+The ->kick() handler takes an rproc handle, and an index of a virtqueue
+where new message was placed in. Implementations should interrupt the remote
+processor and let it know it has pending messages. Notifying remote processors
+the exact virtqueue index to look in is optional: it is easy (and not
+too expensive) to go through the existing virtqueues and look for new buffers
+in the used rings.
+
+Binary Firmware Structure
+=========================
+
+At this point remoteproc supports ELF32 and ELF64 firmware binaries. However,
+it is quite expected that other platforms/devices which we'd want to
+support with this framework will be based on different binary formats.
+
+When those use cases show up, we will have to decouple the binary format
+from the framework core, so we can support several binary formats without
+duplicating common code.
+
+When the firmware is parsed, its various segments are loaded to memory
+according to the specified device address (might be a physical address
+if the remote processor is accessing memory directly).
+
+In addition to the standard ELF segments, most remote processors would
+also include a special section which we call "the resource table".
+
+The resource table contains system resources that the remote processor
+requires before it should be powered on, such as allocation of physically
+contiguous memory, or iommu mapping of certain on-chip peripherals.
+Remotecore will only power up the device after all the resource table's
+requirement are met.
+
+In addition to system resources, the resource table may also contain
+resource entries that publish the existence of supported features
+or configurations by the remote processor, such as trace buffers and
+supported virtio devices (and their configurations).
+
+The resource table begins with this header::
+
+ /**
+ * struct resource_table - firmware resource table header
+ * @ver: version number
+ * @num: number of resource entries
+ * @reserved: reserved (must be zero)
+ * @offset: array of offsets pointing at the various resource entries
+ *
+ * The header of the resource table, as expressed by this structure,
+ * contains a version number (should we need to change this format in the
+ * future), the number of available resource entries, and their offsets
+ * in the table.
+ */
+ struct resource_table {
+ u32 ver;
+ u32 num;
+ u32 reserved[2];
+ u32 offset[0];
+ } __packed;
+
+Immediately following this header are the resource entries themselves,
+each of which begins with the following resource entry header::
+
+ /**
+ * struct fw_rsc_hdr - firmware resource entry header
+ * @type: resource type
+ * @data: resource data
+ *
+ * Every resource entry begins with a 'struct fw_rsc_hdr' header providing
+ * its @type. The content of the entry itself will immediately follow
+ * this header, and it should be parsed according to the resource type.
+ */
+ struct fw_rsc_hdr {
+ u32 type;
+ u8 data[0];
+ } __packed;
+
+Some resources entries are mere announcements, where the host is informed
+of specific remoteproc configuration. Other entries require the host to
+do something (e.g. allocate a system resource). Sometimes a negotiation
+is expected, where the firmware requests a resource, and once allocated,
+the host should provide back its details (e.g. address of an allocated
+memory region).
+
+Here are the various resource types that are currently supported::
+
+ /**
+ * enum fw_resource_type - types of resource entries
+ *
+ * @RSC_CARVEOUT: request for allocation of a physically contiguous
+ * memory region.
+ * @RSC_DEVMEM: request to iommu_map a memory-based peripheral.
+ * @RSC_TRACE: announces the availability of a trace buffer into which
+ * the remote processor will be writing logs.
+ * @RSC_VDEV: declare support for a virtio device, and serve as its
+ * virtio header.
+ * @RSC_LAST: just keep this one at the end
+ * @RSC_VENDOR_START: start of the vendor specific resource types range
+ * @RSC_VENDOR_END: end of the vendor specific resource types range
+ *
+ * Please note that these values are used as indices to the rproc_handle_rsc
+ * lookup table, so please keep them sane. Moreover, @RSC_LAST is used to
+ * check the validity of an index before the lookup table is accessed, so
+ * please update it as needed.
+ */
+ enum fw_resource_type {
+ RSC_CARVEOUT = 0,
+ RSC_DEVMEM = 1,
+ RSC_TRACE = 2,
+ RSC_VDEV = 3,
+ RSC_LAST = 4,
+ RSC_VENDOR_START = 128,
+ RSC_VENDOR_END = 512,
+ };
+
+For more details regarding a specific resource type, please see its
+dedicated structure in include/linux/remoteproc.h.
+
+We also expect that platform-specific resource entries will show up
+at some point. When that happens, we could easily add a new RSC_PLATFORM
+type, and hand those resources to the platform-specific rproc driver to handle.
+
+Virtio and remoteproc
+=====================
+
+The firmware should provide remoteproc information about virtio devices
+that it supports, and their configurations: a RSC_VDEV resource entry
+should specify the virtio device id (as in virtio_ids.h), virtio features,
+virtio config space, vrings information, etc.
+
+When a new remote processor is registered, the remoteproc framework
+will look for its resource table and will register the virtio devices
+it supports. A firmware may support any number of virtio devices, and
+of any type (a single remote processor can also easily support several
+rpmsg virtio devices this way, if desired).
+
+Of course, RSC_VDEV resource entries are only good enough for static
+allocation of virtio devices. Dynamic allocations will also be made possible
+using the rpmsg bus (similar to how we already do dynamic allocations of
+rpmsg channels; read more about it in rpmsg.txt).
diff --git a/Documentation/staging/rpmsg.rst b/Documentation/staging/rpmsg.rst
new file mode 100644
index 0000000..1ce353c
--- /dev/null
+++ b/Documentation/staging/rpmsg.rst
@@ -0,0 +1,341 @@
+============================================
+Remote Processor Messaging (rpmsg) Framework
+============================================
+
+.. note::
+
+ This document describes the rpmsg bus and how to write rpmsg drivers.
+ To learn how to add rpmsg support for new platforms, check out remoteproc.txt
+ (also a resident of Documentation/).
+
+Introduction
+============
+
+Modern SoCs typically employ heterogeneous remote processor devices in
+asymmetric multiprocessing (AMP) configurations, which may be running
+different instances of operating system, whether it's Linux or any other
+flavor of real-time OS.
+
+OMAP4, for example, has dual Cortex-A9, dual Cortex-M3 and a C64x+ DSP.
+Typically, the dual cortex-A9 is running Linux in a SMP configuration,
+and each of the other three cores (two M3 cores and a DSP) is running
+its own instance of RTOS in an AMP configuration.
+
+Typically AMP remote processors employ dedicated DSP codecs and multimedia
+hardware accelerators, and therefore are often used to offload CPU-intensive
+multimedia tasks from the main application processor.
+
+These remote processors could also be used to control latency-sensitive
+sensors, drive random hardware blocks, or just perform background tasks
+while the main CPU is idling.
+
+Users of those remote processors can either be userland apps (e.g. multimedia
+frameworks talking with remote OMX components) or kernel drivers (controlling
+hardware accessible only by the remote processor, reserving kernel-controlled
+resources on behalf of the remote processor, etc..).
+
+Rpmsg is a virtio-based messaging bus that allows kernel drivers to communicate
+with remote processors available on the system. In turn, drivers could then
+expose appropriate user space interfaces, if needed.
+
+When writing a driver that exposes rpmsg communication to userland, please
+keep in mind that remote processors might have direct access to the
+system's physical memory and other sensitive hardware resources (e.g. on
+OMAP4, remote cores and hardware accelerators may have direct access to the
+physical memory, gpio banks, dma controllers, i2c bus, gptimers, mailbox
+devices, hwspinlocks, etc..). Moreover, those remote processors might be
+running RTOS where every task can access the entire memory/devices exposed
+to the processor. To minimize the risks of rogue (or buggy) userland code
+exploiting remote bugs, and by that taking over the system, it is often
+desired to limit userland to specific rpmsg channels (see definition below)
+it can send messages on, and if possible, minimize how much control
+it has over the content of the messages.
+
+Every rpmsg device is a communication channel with a remote processor (thus
+rpmsg devices are called channels). Channels are identified by a textual name
+and have a local ("source") rpmsg address, and remote ("destination") rpmsg
+address.
+
+When a driver starts listening on a channel, its rx callback is bound with
+a unique rpmsg local address (a 32-bit integer). This way when inbound messages
+arrive, the rpmsg core dispatches them to the appropriate driver according
+to their destination address (this is done by invoking the driver's rx handler
+with the payload of the inbound message).
+
+
+User API
+========
+
+::
+
+ int rpmsg_send(struct rpmsg_channel *rpdev, void *data, int len);
+
+sends a message across to the remote processor on a given channel.
+The caller should specify the channel, the data it wants to send,
+and its length (in bytes). The message will be sent on the specified
+channel, i.e. its source and destination address fields will be
+set to the channel's src and dst addresses.
+
+In case there are no TX buffers available, the function will block until
+one becomes available (i.e. until the remote processor consumes
+a tx buffer and puts it back on virtio's used descriptor ring),
+or a timeout of 15 seconds elapses. When the latter happens,
+-ERESTARTSYS is returned.
+
+The function can only be called from a process context (for now).
+Returns 0 on success and an appropriate error value on failure.
+
+::
+
+ int rpmsg_sendto(struct rpmsg_channel *rpdev, void *data, int len, u32 dst);
+
+sends a message across to the remote processor on a given channel,
+to a destination address provided by the caller.
+
+The caller should specify the channel, the data it wants to send,
+its length (in bytes), and an explicit destination address.
+
+The message will then be sent to the remote processor to which the
+channel belongs, using the channel's src address, and the user-provided
+dst address (thus the channel's dst address will be ignored).
+
+In case there are no TX buffers available, the function will block until
+one becomes available (i.e. until the remote processor consumes
+a tx buffer and puts it back on virtio's used descriptor ring),
+or a timeout of 15 seconds elapses. When the latter happens,
+-ERESTARTSYS is returned.
+
+The function can only be called from a process context (for now).
+Returns 0 on success and an appropriate error value on failure.
+
+::
+
+ int rpmsg_send_offchannel(struct rpmsg_channel *rpdev, u32 src, u32 dst,
+ void *data, int len);
+
+
+sends a message across to the remote processor, using the src and dst
+addresses provided by the user.
+
+The caller should specify the channel, the data it wants to send,
+its length (in bytes), and explicit source and destination addresses.
+The message will then be sent to the remote processor to which the
+channel belongs, but the channel's src and dst addresses will be
+ignored (and the user-provided addresses will be used instead).
+
+In case there are no TX buffers available, the function will block until
+one becomes available (i.e. until the remote processor consumes
+a tx buffer and puts it back on virtio's used descriptor ring),
+or a timeout of 15 seconds elapses. When the latter happens,
+-ERESTARTSYS is returned.
+
+The function can only be called from a process context (for now).
+Returns 0 on success and an appropriate error value on failure.
+
+::
+
+ int rpmsg_trysend(struct rpmsg_channel *rpdev, void *data, int len);
+
+sends a message across to the remote processor on a given channel.
+The caller should specify the channel, the data it wants to send,
+and its length (in bytes). The message will be sent on the specified
+channel, i.e. its source and destination address fields will be
+set to the channel's src and dst addresses.
+
+In case there are no TX buffers available, the function will immediately
+return -ENOMEM without waiting until one becomes available.
+
+The function can only be called from a process context (for now).
+Returns 0 on success and an appropriate error value on failure.
+
+::
+
+ int rpmsg_trysendto(struct rpmsg_channel *rpdev, void *data, int len, u32 dst)
+
+
+sends a message across to the remote processor on a given channel,
+to a destination address provided by the user.
+
+The user should specify the channel, the data it wants to send,
+its length (in bytes), and an explicit destination address.
+
+The message will then be sent to the remote processor to which the
+channel belongs, using the channel's src address, and the user-provided
+dst address (thus the channel's dst address will be ignored).
+
+In case there are no TX buffers available, the function will immediately
+return -ENOMEM without waiting until one becomes available.
+
+The function can only be called from a process context (for now).
+Returns 0 on success and an appropriate error value on failure.
+
+::
+
+ int rpmsg_trysend_offchannel(struct rpmsg_channel *rpdev, u32 src, u32 dst,
+ void *data, int len);
+
+
+sends a message across to the remote processor, using source and
+destination addresses provided by the user.
+
+The user should specify the channel, the data it wants to send,
+its length (in bytes), and explicit source and destination addresses.
+The message will then be sent to the remote processor to which the
+channel belongs, but the channel's src and dst addresses will be
+ignored (and the user-provided addresses will be used instead).
+
+In case there are no TX buffers available, the function will immediately
+return -ENOMEM without waiting until one becomes available.
+
+The function can only be called from a process context (for now).
+Returns 0 on success and an appropriate error value on failure.
+
+::
+
+ struct rpmsg_endpoint *rpmsg_create_ept(struct rpmsg_device *rpdev,
+ rpmsg_rx_cb_t cb, void *priv,
+ struct rpmsg_channel_info chinfo);
+
+every rpmsg address in the system is bound to an rx callback (so when
+inbound messages arrive, they are dispatched by the rpmsg bus using the
+appropriate callback handler) by means of an rpmsg_endpoint struct.
+
+This function allows drivers to create such an endpoint, and by that,
+bind a callback, and possibly some private data too, to an rpmsg address
+(either one that is known in advance, or one that will be dynamically
+assigned for them).
+
+Simple rpmsg drivers need not call rpmsg_create_ept, because an endpoint
+is already created for them when they are probed by the rpmsg bus
+(using the rx callback they provide when they registered to the rpmsg bus).
+
+So things should just work for simple drivers: they already have an
+endpoint, their rx callback is bound to their rpmsg address, and when
+relevant inbound messages arrive (i.e. messages which their dst address
+equals to the src address of their rpmsg channel), the driver's handler
+is invoked to process it.
+
+That said, more complicated drivers might do need to allocate
+additional rpmsg addresses, and bind them to different rx callbacks.
+To accomplish that, those drivers need to call this function.
+Drivers should provide their channel (so the new endpoint would bind
+to the same remote processor their channel belongs to), an rx callback
+function, an optional private data (which is provided back when the
+rx callback is invoked), and an address they want to bind with the
+callback. If addr is RPMSG_ADDR_ANY, then rpmsg_create_ept will
+dynamically assign them an available rpmsg address (drivers should have
+a very good reason why not to always use RPMSG_ADDR_ANY here).
+
+Returns a pointer to the endpoint on success, or NULL on error.
+
+::
+
+ void rpmsg_destroy_ept(struct rpmsg_endpoint *ept);
+
+
+destroys an existing rpmsg endpoint. user should provide a pointer
+to an rpmsg endpoint that was previously created with rpmsg_create_ept().
+
+::
+
+ int register_rpmsg_driver(struct rpmsg_driver *rpdrv);
+
+
+registers an rpmsg driver with the rpmsg bus. user should provide
+a pointer to an rpmsg_driver struct, which contains the driver's
+->probe() and ->remove() functions, an rx callback, and an id_table
+specifying the names of the channels this driver is interested to
+be probed with.
+
+::
+
+ void unregister_rpmsg_driver(struct rpmsg_driver *rpdrv);
+
+
+unregisters an rpmsg driver from the rpmsg bus. user should provide
+a pointer to a previously-registered rpmsg_driver struct.
+Returns 0 on success, and an appropriate error value on failure.
+
+
+Typical usage
+=============
+
+The following is a simple rpmsg driver, that sends an "hello!" message
+on probe(), and whenever it receives an incoming message, it dumps its
+content to the console.
+
+::
+
+ #include <linux/kernel.h>
+ #include <linux/module.h>
+ #include <linux/rpmsg.h>
+
+ static void rpmsg_sample_cb(struct rpmsg_channel *rpdev, void *data, int len,
+ void *priv, u32 src)
+ {
+ print_hex_dump(KERN_INFO, "incoming message:", DUMP_PREFIX_NONE,
+ 16, 1, data, len, true);
+ }
+
+ static int rpmsg_sample_probe(struct rpmsg_channel *rpdev)
+ {
+ int err;
+
+ dev_info(&rpdev->dev, "chnl: 0x%x -> 0x%x\n", rpdev->src, rpdev->dst);
+
+ /* send a message on our channel */
+ err = rpmsg_send(rpdev, "hello!", 6);
+ if (err) {
+ pr_err("rpmsg_send failed: %d\n", err);
+ return err;
+ }
+
+ return 0;
+ }
+
+ static void rpmsg_sample_remove(struct rpmsg_channel *rpdev)
+ {
+ dev_info(&rpdev->dev, "rpmsg sample client driver is removed\n");
+ }
+
+ static struct rpmsg_device_id rpmsg_driver_sample_id_table[] = {
+ { .name = "rpmsg-client-sample" },
+ { },
+ };
+ MODULE_DEVICE_TABLE(rpmsg, rpmsg_driver_sample_id_table);
+
+ static struct rpmsg_driver rpmsg_sample_client = {
+ .drv.name = KBUILD_MODNAME,
+ .id_table = rpmsg_driver_sample_id_table,
+ .probe = rpmsg_sample_probe,
+ .callback = rpmsg_sample_cb,
+ .remove = rpmsg_sample_remove,
+ };
+ module_rpmsg_driver(rpmsg_sample_client);
+
+.. note::
+
+ a similar sample which can be built and loaded can be found
+ in samples/rpmsg/.
+
+Allocations of rpmsg channels
+=============================
+
+At this point we only support dynamic allocations of rpmsg channels.
+
+This is possible only with remote processors that have the VIRTIO_RPMSG_F_NS
+virtio device feature set. This feature bit means that the remote
+processor supports dynamic name service announcement messages.
+
+When this feature is enabled, creation of rpmsg devices (i.e. channels)
+is completely dynamic: the remote processor announces the existence of a
+remote rpmsg service by sending a name service message (which contains
+the name and rpmsg addr of the remote service, see struct rpmsg_ns_msg).
+
+This message is then handled by the rpmsg bus, which in turn dynamically
+creates and registers an rpmsg channel (which represents the remote service).
+If/when a relevant rpmsg driver is registered, it will be immediately probed
+by the bus, and can then start sending messages to the remote service.
+
+The plan is also to add static creation of rpmsg channels via the virtio
+config space, but it's not implemented yet.
diff --git a/Documentation/staging/speculation.rst b/Documentation/staging/speculation.rst
new file mode 100644
index 0000000..8045d99
--- /dev/null
+++ b/Documentation/staging/speculation.rst
@@ -0,0 +1,92 @@
+===========
+Speculation
+===========
+
+This document explains potential effects of speculation, and how undesirable
+effects can be mitigated portably using common APIs.
+
+------------------------------------------------------------------------------
+
+To improve performance and minimize average latencies, many contemporary CPUs
+employ speculative execution techniques such as branch prediction, performing
+work which may be discarded at a later stage.
+
+Typically speculative execution cannot be observed from architectural state,
+such as the contents of registers. However, in some cases it is possible to
+observe its impact on microarchitectural state, such as the presence or
+absence of data in caches. Such state may form side-channels which can be
+observed to extract secret information.
+
+For example, in the presence of branch prediction, it is possible for bounds
+checks to be ignored by code which is speculatively executed. Consider the
+following code::
+
+ int load_array(int *array, unsigned int index)
+ {
+ if (index >= MAX_ARRAY_ELEMS)
+ return 0;
+ else
+ return array[index];
+ }
+
+Which, on arm64, may be compiled to an assembly sequence such as::
+
+ CMP <index>, #MAX_ARRAY_ELEMS
+ B.LT less
+ MOV <returnval>, #0
+ RET
+ less:
+ LDR <returnval>, [<array>, <index>]
+ RET
+
+It is possible that a CPU mis-predicts the conditional branch, and
+speculatively loads array[index], even if index >= MAX_ARRAY_ELEMS. This
+value will subsequently be discarded, but the speculated load may affect
+microarchitectural state which can be subsequently measured.
+
+More complex sequences involving multiple dependent memory accesses may
+result in sensitive information being leaked. Consider the following
+code, building on the prior example::
+
+ int load_dependent_arrays(int *arr1, int *arr2, int index)
+ {
+ int val1, val2,
+
+ val1 = load_array(arr1, index);
+ val2 = load_array(arr2, val1);
+
+ return val2;
+ }
+
+Under speculation, the first call to load_array() may return the value
+of an out-of-bounds address, while the second call will influence
+microarchitectural state dependent on this value. This may provide an
+arbitrary read primitive.
+
+====================================
+Mitigating speculation side-channels
+====================================
+
+The kernel provides a generic API to ensure that bounds checks are
+respected even under speculation. Architectures which are affected by
+speculation-based side-channels are expected to implement these
+primitives.
+
+The array_index_nospec() helper in <linux/nospec.h> can be used to
+prevent information from being leaked via side-channels.
+
+A call to array_index_nospec(index, size) returns a sanitized index
+value that is bounded to [0, size) even under cpu speculation
+conditions.
+
+This can be used to protect the earlier load_array() example::
+
+ int load_array(int *array, unsigned int index)
+ {
+ if (index >= MAX_ARRAY_ELEMS)
+ return 0;
+ else {
+ index = array_index_nospec(index, MAX_ARRAY_ELEMS);
+ return array[index];
+ }
+ }
diff --git a/Documentation/static-keys.txt b/Documentation/staging/static-keys.rst
similarity index 100%
rename from Documentation/static-keys.txt
rename to Documentation/staging/static-keys.rst
diff --git a/Documentation/staging/tee.rst b/Documentation/staging/tee.rst
new file mode 100644
index 0000000..4d4b5f8
--- /dev/null
+++ b/Documentation/staging/tee.rst
@@ -0,0 +1,281 @@
+=============
+TEE subsystem
+=============
+
+This document describes the TEE subsystem in Linux.
+
+A TEE (Trusted Execution Environment) is a trusted OS running in some
+secure environment, for example, TrustZone on ARM CPUs, or a separate
+secure co-processor etc. A TEE driver handles the details needed to
+communicate with the TEE.
+
+This subsystem deals with:
+
+- Registration of TEE drivers
+
+- Managing shared memory between Linux and the TEE
+
+- Providing a generic API to the TEE
+
+The TEE interface
+=================
+
+include/uapi/linux/tee.h defines the generic interface to a TEE.
+
+User space (the client) connects to the driver by opening /dev/tee[0-9]* or
+/dev/teepriv[0-9]*.
+
+- TEE_IOC_SHM_ALLOC allocates shared memory and returns a file descriptor
+ which user space can mmap. When user space doesn't need the file
+ descriptor any more, it should be closed. When shared memory isn't needed
+ any longer it should be unmapped with munmap() to allow the reuse of
+ memory.
+
+- TEE_IOC_VERSION lets user space know which TEE this driver handles and
+ its capabilities.
+
+- TEE_IOC_OPEN_SESSION opens a new session to a Trusted Application.
+
+- TEE_IOC_INVOKE invokes a function in a Trusted Application.
+
+- TEE_IOC_CANCEL may cancel an ongoing TEE_IOC_OPEN_SESSION or TEE_IOC_INVOKE.
+
+- TEE_IOC_CLOSE_SESSION closes a session to a Trusted Application.
+
+There are two classes of clients, normal clients and supplicants. The latter is
+a helper process for the TEE to access resources in Linux, for example file
+system access. A normal client opens /dev/tee[0-9]* and a supplicant opens
+/dev/teepriv[0-9].
+
+Much of the communication between clients and the TEE is opaque to the
+driver. The main job for the driver is to receive requests from the
+clients, forward them to the TEE and send back the results. In the case of
+supplicants the communication goes in the other direction, the TEE sends
+requests to the supplicant which then sends back the result.
+
+The TEE kernel interface
+========================
+
+Kernel provides a TEE bus infrastructure where a Trusted Application is
+represented as a device identified via Universally Unique Identifier (UUID) and
+client drivers register a table of supported device UUIDs.
+
+TEE bus infrastructure registers following APIs:
+
+match():
+ iterates over the client driver UUID table to find a corresponding
+ match for device UUID. If a match is found, then this particular device is
+ probed via corresponding probe API registered by the client driver. This
+ process happens whenever a device or a client driver is registered with TEE
+ bus.
+
+uevent():
+ notifies user-space (udev) whenever a new device is registered on
+ TEE bus for auto-loading of modularized client drivers.
+
+TEE bus device enumeration is specific to underlying TEE implementation, so it
+is left open for TEE drivers to provide corresponding implementation.
+
+Then TEE client driver can talk to a matched Trusted Application using APIs
+listed in include/linux/tee_drv.h.
+
+TEE client driver example
+-------------------------
+
+Suppose a TEE client driver needs to communicate with a Trusted Application
+having UUID: ``ac6a4085-0e82-4c33-bf98-8eb8e118b6c2``, so driver registration
+snippet would look like::
+
+ static const struct tee_client_device_id client_id_table[] = {
+ {UUID_INIT(0xac6a4085, 0x0e82, 0x4c33,
+ 0xbf, 0x98, 0x8e, 0xb8, 0xe1, 0x18, 0xb6, 0xc2)},
+ {}
+ };
+
+ MODULE_DEVICE_TABLE(tee, client_id_table);
+
+ static struct tee_client_driver client_driver = {
+ .id_table = client_id_table,
+ .driver = {
+ .name = DRIVER_NAME,
+ .bus = &tee_bus_type,
+ .probe = client_probe,
+ .remove = client_remove,
+ },
+ };
+
+ static int __init client_init(void)
+ {
+ return driver_register(&client_driver.driver);
+ }
+
+ static void __exit client_exit(void)
+ {
+ driver_unregister(&client_driver.driver);
+ }
+
+ module_init(client_init);
+ module_exit(client_exit);
+
+OP-TEE driver
+=============
+
+The OP-TEE driver handles OP-TEE [1] based TEEs. Currently it is only the ARM
+TrustZone based OP-TEE solution that is supported.
+
+Lowest level of communication with OP-TEE builds on ARM SMC Calling
+Convention (SMCCC) [2], which is the foundation for OP-TEE's SMC interface
+[3] used internally by the driver. Stacked on top of that is OP-TEE Message
+Protocol [4].
+
+OP-TEE SMC interface provides the basic functions required by SMCCC and some
+additional functions specific for OP-TEE. The most interesting functions are:
+
+- OPTEE_SMC_FUNCID_CALLS_UID (part of SMCCC) returns the version information
+ which is then returned by TEE_IOC_VERSION
+
+- OPTEE_SMC_CALL_GET_OS_UUID returns the particular OP-TEE implementation, used
+ to tell, for instance, a TrustZone OP-TEE apart from an OP-TEE running on a
+ separate secure co-processor.
+
+- OPTEE_SMC_CALL_WITH_ARG drives the OP-TEE message protocol
+
+- OPTEE_SMC_GET_SHM_CONFIG lets the driver and OP-TEE agree on which memory
+ range to used for shared memory between Linux and OP-TEE.
+
+The GlobalPlatform TEE Client API [5] is implemented on top of the generic
+TEE API.
+
+Picture of the relationship between the different components in the
+OP-TEE architecture::
+
+ User space Kernel Secure world
+ ~~~~~~~~~~ ~~~~~~ ~~~~~~~~~~~~
+ +--------+ +-------------+
+ | Client | | Trusted |
+ +--------+ | Application |
+ /\ +-------------+
+ || +----------+ /\
+ || |tee- | ||
+ || |supplicant| \/
+ || +----------+ +-------------+
+ \/ /\ | TEE Internal|
+ +-------+ || | API |
+ + TEE | || +--------+--------+ +-------------+
+ | Client| || | TEE | OP-TEE | | OP-TEE |
+ | API | \/ | subsys | driver | | Trusted OS |
+ +-------+----------------+----+-------+----+-----------+-------------+
+ | Generic TEE API | | OP-TEE MSG |
+ | IOCTL (TEE_IOC_*) | | SMCCC (OPTEE_SMC_CALL_*) |
+ +-----------------------------+ +------------------------------+
+
+RPC (Remote Procedure Call) are requests from secure world to kernel driver
+or tee-supplicant. An RPC is identified by a special range of SMCCC return
+values from OPTEE_SMC_CALL_WITH_ARG. RPC messages which are intended for the
+kernel are handled by the kernel driver. Other RPC messages will be forwarded to
+tee-supplicant without further involvement of the driver, except switching
+shared memory buffer representation.
+
+OP-TEE device enumeration
+-------------------------
+
+OP-TEE provides a pseudo Trusted Application: drivers/tee/optee/device.c in
+order to support device enumeration. In other words, OP-TEE driver invokes this
+application to retrieve a list of Trusted Applications which can be registered
+as devices on the TEE bus.
+
+AMD-TEE driver
+==============
+
+The AMD-TEE driver handles the communication with AMD's TEE environment. The
+TEE environment is provided by AMD Secure Processor.
+
+The AMD Secure Processor (formerly called Platform Security Processor or PSP)
+is a dedicated processor that features ARM TrustZone technology, along with a
+software-based Trusted Execution Environment (TEE) designed to enable
+third-party Trusted Applications. This feature is currently enabled only for
+APUs.
+
+The following picture shows a high level overview of AMD-TEE::
+
+ |
+ x86 |
+ |
+ User space (Kernel space) | AMD Secure Processor (PSP)
+ ~~~~~~~~~~ ~~~~~~~~~~~~~~ | ~~~~~~~~~~~~~~~~~~~~~~~~~~
+ |
+ +--------+ | +-------------+
+ | Client | | | Trusted |
+ +--------+ | | Application |
+ /\ | +-------------+
+ || | /\
+ || | ||
+ || | \/
+ || | +----------+
+ || | | TEE |
+ || | | Internal |
+ \/ | | API |
+ +---------+ +-----------+---------+ +----------+
+ | TEE | | TEE | AMD-TEE | | AMD-TEE |
+ | Client | | subsystem | driver | | Trusted |
+ | API | | | | | OS |
+ +---------+-----------+----+------+---------+---------+----------+
+ | Generic TEE API | | ASP | Mailbox |
+ | IOCTL (TEE_IOC_*) | | driver | Register Protocol |
+ +--------------------------+ +---------+--------------------+
+
+At the lowest level (in x86), the AMD Secure Processor (ASP) driver uses the
+CPU to PSP mailbox regsister to submit commands to the PSP. The format of the
+command buffer is opaque to the ASP driver. It's role is to submit commands to
+the secure processor and return results to AMD-TEE driver. The interface
+between AMD-TEE driver and AMD Secure Processor driver can be found in [6].
+
+The AMD-TEE driver packages the command buffer payload for processing in TEE.
+The command buffer format for the different TEE commands can be found in [7].
+
+The TEE commands supported by AMD-TEE Trusted OS are:
+
+* TEE_CMD_ID_LOAD_TA - loads a Trusted Application (TA) binary into
+ TEE environment.
+* TEE_CMD_ID_UNLOAD_TA - unloads TA binary from TEE environment.
+* TEE_CMD_ID_OPEN_SESSION - opens a session with a loaded TA.
+* TEE_CMD_ID_CLOSE_SESSION - closes session with loaded TA
+* TEE_CMD_ID_INVOKE_CMD - invokes a command with loaded TA
+* TEE_CMD_ID_MAP_SHARED_MEM - maps shared memory
+* TEE_CMD_ID_UNMAP_SHARED_MEM - unmaps shared memory
+
+AMD-TEE Trusted OS is the firmware running on AMD Secure Processor.
+
+The AMD-TEE driver registers itself with TEE subsystem and implements the
+following driver function callbacks:
+
+* get_version - returns the driver implementation id and capability.
+* open - sets up the driver context data structure.
+* release - frees up driver resources.
+* open_session - loads the TA binary and opens session with loaded TA.
+* close_session - closes session with loaded TA and unloads it.
+* invoke_func - invokes a command with loaded TA.
+
+cancel_req driver callback is not supported by AMD-TEE.
+
+The GlobalPlatform TEE Client API [5] can be used by the user space (client) to
+talk to AMD's TEE. AMD's TEE provides a secure environment for loading, opening
+a session, invoking commands and clossing session with TA.
+
+References
+==========
+
+[1] https://github.com/OP-TEE/optee_os
+
+[2] http://infocenter.arm.com/help/topic/com.arm.doc.den0028a/index.html
+
+[3] drivers/tee/optee/optee_smc.h
+
+[4] drivers/tee/optee/optee_msg.h
+
+[5] http://www.globalplatform.org/specificationsdevice.asp look for
+ "TEE Client API Specification v1.0" and click download.
+
+[6] include/linux/psp-tee.h
+
+[7] drivers/tee/amdtee/amdtee_if.h
diff --git a/Documentation/xz.txt b/Documentation/staging/xz.rst
similarity index 100%
rename from Documentation/xz.txt
rename to Documentation/staging/xz.rst
diff --git a/Documentation/tee.txt b/Documentation/tee.txt
deleted file mode 100644
index c8fad81..0000000
--- a/Documentation/tee.txt
+++ /dev/null
@@ -1,208 +0,0 @@
-=============
-TEE subsystem
-=============
-
-This document describes the TEE subsystem in Linux.
-
-A TEE (Trusted Execution Environment) is a trusted OS running in some
-secure environment, for example, TrustZone on ARM CPUs, or a separate
-secure co-processor etc. A TEE driver handles the details needed to
-communicate with the TEE.
-
-This subsystem deals with:
-
-- Registration of TEE drivers
-
-- Managing shared memory between Linux and the TEE
-
-- Providing a generic API to the TEE
-
-The TEE interface
-=================
-
-include/uapi/linux/tee.h defines the generic interface to a TEE.
-
-User space (the client) connects to the driver by opening /dev/tee[0-9]* or
-/dev/teepriv[0-9]*.
-
-- TEE_IOC_SHM_ALLOC allocates shared memory and returns a file descriptor
- which user space can mmap. When user space doesn't need the file
- descriptor any more, it should be closed. When shared memory isn't needed
- any longer it should be unmapped with munmap() to allow the reuse of
- memory.
-
-- TEE_IOC_VERSION lets user space know which TEE this driver handles and
- its capabilities.
-
-- TEE_IOC_OPEN_SESSION opens a new session to a Trusted Application.
-
-- TEE_IOC_INVOKE invokes a function in a Trusted Application.
-
-- TEE_IOC_CANCEL may cancel an ongoing TEE_IOC_OPEN_SESSION or TEE_IOC_INVOKE.
-
-- TEE_IOC_CLOSE_SESSION closes a session to a Trusted Application.
-
-There are two classes of clients, normal clients and supplicants. The latter is
-a helper process for the TEE to access resources in Linux, for example file
-system access. A normal client opens /dev/tee[0-9]* and a supplicant opens
-/dev/teepriv[0-9].
-
-Much of the communication between clients and the TEE is opaque to the
-driver. The main job for the driver is to receive requests from the
-clients, forward them to the TEE and send back the results. In the case of
-supplicants the communication goes in the other direction, the TEE sends
-requests to the supplicant which then sends back the result.
-
-OP-TEE driver
-=============
-
-The OP-TEE driver handles OP-TEE [1] based TEEs. Currently it is only the ARM
-TrustZone based OP-TEE solution that is supported.
-
-Lowest level of communication with OP-TEE builds on ARM SMC Calling
-Convention (SMCCC) [2], which is the foundation for OP-TEE's SMC interface
-[3] used internally by the driver. Stacked on top of that is OP-TEE Message
-Protocol [4].
-
-OP-TEE SMC interface provides the basic functions required by SMCCC and some
-additional functions specific for OP-TEE. The most interesting functions are:
-
-- OPTEE_SMC_FUNCID_CALLS_UID (part of SMCCC) returns the version information
- which is then returned by TEE_IOC_VERSION
-
-- OPTEE_SMC_CALL_GET_OS_UUID returns the particular OP-TEE implementation, used
- to tell, for instance, a TrustZone OP-TEE apart from an OP-TEE running on a
- separate secure co-processor.
-
-- OPTEE_SMC_CALL_WITH_ARG drives the OP-TEE message protocol
-
-- OPTEE_SMC_GET_SHM_CONFIG lets the driver and OP-TEE agree on which memory
- range to used for shared memory between Linux and OP-TEE.
-
-The GlobalPlatform TEE Client API [5] is implemented on top of the generic
-TEE API.
-
-Picture of the relationship between the different components in the
-OP-TEE architecture::
-
- User space Kernel Secure world
- ~~~~~~~~~~ ~~~~~~ ~~~~~~~~~~~~
- +--------+ +-------------+
- | Client | | Trusted |
- +--------+ | Application |
- /\ +-------------+
- || +----------+ /\
- || |tee- | ||
- || |supplicant| \/
- || +----------+ +-------------+
- \/ /\ | TEE Internal|
- +-------+ || | API |
- + TEE | || +--------+--------+ +-------------+
- | Client| || | TEE | OP-TEE | | OP-TEE |
- | API | \/ | subsys | driver | | Trusted OS |
- +-------+----------------+----+-------+----+-----------+-------------+
- | Generic TEE API | | OP-TEE MSG |
- | IOCTL (TEE_IOC_*) | | SMCCC (OPTEE_SMC_CALL_*) |
- +-----------------------------+ +------------------------------+
-
-RPC (Remote Procedure Call) are requests from secure world to kernel driver
-or tee-supplicant. An RPC is identified by a special range of SMCCC return
-values from OPTEE_SMC_CALL_WITH_ARG. RPC messages which are intended for the
-kernel are handled by the kernel driver. Other RPC messages will be forwarded to
-tee-supplicant without further involvement of the driver, except switching
-shared memory buffer representation.
-
-AMD-TEE driver
-==============
-
-The AMD-TEE driver handles the communication with AMD's TEE environment. The
-TEE environment is provided by AMD Secure Processor.
-
-The AMD Secure Processor (formerly called Platform Security Processor or PSP)
-is a dedicated processor that features ARM TrustZone technology, along with a
-software-based Trusted Execution Environment (TEE) designed to enable
-third-party Trusted Applications. This feature is currently enabled only for
-APUs.
-
-The following picture shows a high level overview of AMD-TEE::
-
- |
- x86 |
- |
- User space (Kernel space) | AMD Secure Processor (PSP)
- ~~~~~~~~~~ ~~~~~~~~~~~~~~ | ~~~~~~~~~~~~~~~~~~~~~~~~~~
- |
- +--------+ | +-------------+
- | Client | | | Trusted |
- +--------+ | | Application |
- /\ | +-------------+
- || | /\
- || | ||
- || | \/
- || | +----------+
- || | | TEE |
- || | | Internal |
- \/ | | API |
- +---------+ +-----------+---------+ +----------+
- | TEE | | TEE | AMD-TEE | | AMD-TEE |
- | Client | | subsystem | driver | | Trusted |
- | API | | | | | OS |
- +---------+-----------+----+------+---------+---------+----------+
- | Generic TEE API | | ASP | Mailbox |
- | IOCTL (TEE_IOC_*) | | driver | Register Protocol |
- +--------------------------+ +---------+--------------------+
-
-At the lowest level (in x86), the AMD Secure Processor (ASP) driver uses the
-CPU to PSP mailbox regsister to submit commands to the PSP. The format of the
-command buffer is opaque to the ASP driver. It's role is to submit commands to
-the secure processor and return results to AMD-TEE driver. The interface
-between AMD-TEE driver and AMD Secure Processor driver can be found in [6].
-
-The AMD-TEE driver packages the command buffer payload for processing in TEE.
-The command buffer format for the different TEE commands can be found in [7].
-
-The TEE commands supported by AMD-TEE Trusted OS are:
-* TEE_CMD_ID_LOAD_TA - loads a Trusted Application (TA) binary into
- TEE environment.
-* TEE_CMD_ID_UNLOAD_TA - unloads TA binary from TEE environment.
-* TEE_CMD_ID_OPEN_SESSION - opens a session with a loaded TA.
-* TEE_CMD_ID_CLOSE_SESSION - closes session with loaded TA
-* TEE_CMD_ID_INVOKE_CMD - invokes a command with loaded TA
-* TEE_CMD_ID_MAP_SHARED_MEM - maps shared memory
-* TEE_CMD_ID_UNMAP_SHARED_MEM - unmaps shared memory
-
-AMD-TEE Trusted OS is the firmware running on AMD Secure Processor.
-
-The AMD-TEE driver registers itself with TEE subsystem and implements the
-following driver function callbacks:
-
-* get_version - returns the driver implementation id and capability.
-* open - sets up the driver context data structure.
-* release - frees up driver resources.
-* open_session - loads the TA binary and opens session with loaded TA.
-* close_session - closes session with loaded TA and unloads it.
-* invoke_func - invokes a command with loaded TA.
-
-cancel_req driver callback is not supported by AMD-TEE.
-
-The GlobalPlatform TEE Client API [5] can be used by the user space (client) to
-talk to AMD's TEE. AMD's TEE provides a secure environment for loading, opening
-a session, invoking commands and clossing session with TA.
-
-References
-==========
-
-[1] https://github.com/OP-TEE/optee_os
-
-[2] http://infocenter.arm.com/help/topic/com.arm.doc.den0028a/index.html
-
-[3] drivers/tee/optee/optee_smc.h
-
-[4] drivers/tee/optee/optee_msg.h
-
-[5] http://www.globalplatform.org/specificationsdevice.asp look for
- "TEE Client API Specification v1.0" and click download.
-
-[6] include/linux/psp-tee.h
-
-[7] drivers/tee/amdtee/amdtee_if.h
diff --git a/Documentation/timers/no_hz.rst b/Documentation/timers/no_hz.rst
index 065db21..c4c70e1 100644
--- a/Documentation/timers/no_hz.rst
+++ b/Documentation/timers/no_hz.rst
@@ -171,8 +171,6 @@
slightly differently than those for non-adaptive-tick CPUs.
This might in turn perturb load-balancing of real-time tasks.
-6. The LB_BIAS scheduler feature is disabled by adaptive ticks.
-
Although improvements are expected over time, adaptive ticks is quite
useful for many types of real-time and compute-intensive applications.
However, the drawbacks listed above mean that adaptive ticks should not
diff --git a/Documentation/trace/ftrace.rst b/Documentation/trace/ftrace.rst
index 430a162..87cf5c0 100644
--- a/Documentation/trace/ftrace.rst
+++ b/Documentation/trace/ftrace.rst
@@ -34,7 +34,7 @@
can be enabled via the tracefs file system to see what is
going on in certain parts of the kernel.
-See events.txt for more information.
+See events.rst for more information.
Implementation Details
@@ -376,11 +376,11 @@
kprobe_events:
- Enable dynamic trace points. See kprobetrace.txt.
+ Enable dynamic trace points. See kprobetrace.rst.
kprobe_profile:
- Dynamic trace points stats. See kprobetrace.txt.
+ Dynamic trace points stats. See kprobetrace.rst.
max_graph_depth:
@@ -561,14 +561,14 @@
trace_marker_raw:
- This is similar to trace_marker above, but is meant for for binary data
+ This is similar to trace_marker above, but is meant for binary data
to be written to it, where a tool can be used to parse the data
from trace_pipe_raw.
uprobe_events:
Add dynamic tracepoints in programs.
- See uprobetracer.txt
+ See uprobetracer.rst
uprobe_profile:
@@ -589,19 +589,19 @@
files at various levels that can enable the tracepoints
when a "1" is written to them.
- See events.txt for more information.
+ See events.rst for more information.
set_event:
By echoing in the event into this file, will enable that event.
- See events.txt for more information.
+ See events.rst for more information.
available_events:
A list of events that can be enabled in tracing.
- See events.txt for more information.
+ See events.rst for more information.
timestamp_mode:
@@ -1394,7 +1394,7 @@
=> x86_64_start_reservations
=> x86_64_start_kernel
-Here we see that that we had a latency of 16 microseconds (which is
+Here we see that we had a latency of 16 microseconds (which is
very good). The _raw_spin_lock_irq in run_timer_softirq disabled
interrupts. The difference between the 16 and the displayed
timestamp 25us occurred because the clock was incremented
@@ -1453,7 +1453,7 @@
=> __blk_run_queue_uncond
=> __blk_run_queue
=> blk_queue_bio
- => generic_make_request
+ => submit_bio_noacct
=> submit_bio
=> submit_bh
=> __ext3_get_inode_loc
@@ -1738,7 +1738,7 @@
=> __blk_run_queue_uncond
=> __blk_run_queue
=> blk_queue_bio
- => generic_make_request
+ => submit_bio_noacct
=> submit_bio
=> submit_bh
=> ext3_bread
diff --git a/Documentation/trace/histogram-design.rst b/Documentation/trace/histogram-design.rst
index eef8400..088c8cc 100644
--- a/Documentation/trace/histogram-design.rst
+++ b/Documentation/trace/histogram-design.rst
@@ -780,7 +780,7 @@
Moving on to the sched_switch trigger hist_debug output, in addition
to the unused wakeup_lat variable, we see a new section displaying
variable references. Variable references are displayed in a separate
-section because in addition to to being logically separate from
+section because in addition to being logically separate from
variables and values, they actually live in a separate hist_data
array, var_refs[].
@@ -863,7 +863,7 @@
The onmatch() action below basically says that whenever we have a
sched_switch event, if we have a matching sched_waking event, in this
case if we have a pid in the sched_waking histogram that matches the
-the next_pid field on this sched_switch event, we retrieve the
+next_pid field on this sched_switch event, we retrieve the
variables specified in the wakeup_latency() trace action, and use
them to generate a new wakeup_latency event into the trace stream.
diff --git a/Documentation/trace/index.rst b/Documentation/trace/index.rst
index fa9e1c7..f634b36 100644
--- a/Documentation/trace/index.rst
+++ b/Documentation/trace/index.rst
@@ -9,6 +9,7 @@
tracepoint-analysis
ftrace
ftrace-uses
+ kprobes
kprobetrace
uprobetracer
tracepoints
@@ -19,9 +20,11 @@
events-msr
mmiotrace
histogram
+ histogram-design
boottime-trace
hwlat_detector
intel_th
+ ring-buffer-design
stm
sys-t
coresight/index
diff --git a/Documentation/trace/intel_th.rst b/Documentation/trace/intel_th.rst
index 70b7126..b31818d 100644
--- a/Documentation/trace/intel_th.rst
+++ b/Documentation/trace/intel_th.rst
@@ -58,7 +58,7 @@
For each Intel TH device in the system a bus of its own is
created and assigned an id number that reflects the order in which TH
-devices were emumerated. All TH subdevices (devices on intel_th bus)
+devices were enumerated. All TH subdevices (devices on intel_th bus)
begin with this id: 0-gth, 0-msc0, 0-msc1, 0-pti, 0-sth, which is
followed by device's name and an optional index.
diff --git a/Documentation/trace/kprobes.rst b/Documentation/trace/kprobes.rst
new file mode 100644
index 0000000..b757b6d
--- /dev/null
+++ b/Documentation/trace/kprobes.rst
@@ -0,0 +1,803 @@
+=======================
+Kernel Probes (Kprobes)
+=======================
+
+:Author: Jim Keniston <jkenisto@us.ibm.com>
+:Author: Prasanna S Panchamukhi <prasanna.panchamukhi@gmail.com>
+:Author: Masami Hiramatsu <mhiramat@redhat.com>
+
+.. CONTENTS
+
+ 1. Concepts: Kprobes, and Return Probes
+ 2. Architectures Supported
+ 3. Configuring Kprobes
+ 4. API Reference
+ 5. Kprobes Features and Limitations
+ 6. Probe Overhead
+ 7. TODO
+ 8. Kprobes Example
+ 9. Kretprobes Example
+ 10. Deprecated Features
+ Appendix A: The kprobes debugfs interface
+ Appendix B: The kprobes sysctl interface
+ Appendix C: References
+
+Concepts: Kprobes and Return Probes
+=========================================
+
+Kprobes enables you to dynamically break into any kernel routine and
+collect debugging and performance information non-disruptively. You
+can trap at almost any kernel code address [1]_, specifying a handler
+routine to be invoked when the breakpoint is hit.
+
+.. [1] some parts of the kernel code can not be trapped, see
+ :ref:`kprobes_blacklist`)
+
+There are currently two types of probes: kprobes, and kretprobes
+(also called return probes). A kprobe can be inserted on virtually
+any instruction in the kernel. A return probe fires when a specified
+function returns.
+
+In the typical case, Kprobes-based instrumentation is packaged as
+a kernel module. The module's init function installs ("registers")
+one or more probes, and the exit function unregisters them. A
+registration function such as register_kprobe() specifies where
+the probe is to be inserted and what handler is to be called when
+the probe is hit.
+
+There are also ``register_/unregister_*probes()`` functions for batch
+registration/unregistration of a group of ``*probes``. These functions
+can speed up unregistration process when you have to unregister
+a lot of probes at once.
+
+The next four subsections explain how the different types of
+probes work and how jump optimization works. They explain certain
+things that you'll need to know in order to make the best use of
+Kprobes -- e.g., the difference between a pre_handler and
+a post_handler, and how to use the maxactive and nmissed fields of
+a kretprobe. But if you're in a hurry to start using Kprobes, you
+can skip ahead to :ref:`kprobes_archs_supported`.
+
+How Does a Kprobe Work?
+-----------------------
+
+When a kprobe is registered, Kprobes makes a copy of the probed
+instruction and replaces the first byte(s) of the probed instruction
+with a breakpoint instruction (e.g., int3 on i386 and x86_64).
+
+When a CPU hits the breakpoint instruction, a trap occurs, the CPU's
+registers are saved, and control passes to Kprobes via the
+notifier_call_chain mechanism. Kprobes executes the "pre_handler"
+associated with the kprobe, passing the handler the addresses of the
+kprobe struct and the saved registers.
+
+Next, Kprobes single-steps its copy of the probed instruction.
+(It would be simpler to single-step the actual instruction in place,
+but then Kprobes would have to temporarily remove the breakpoint
+instruction. This would open a small time window when another CPU
+could sail right past the probepoint.)
+
+After the instruction is single-stepped, Kprobes executes the
+"post_handler," if any, that is associated with the kprobe.
+Execution then continues with the instruction following the probepoint.
+
+Changing Execution Path
+-----------------------
+
+Since kprobes can probe into a running kernel code, it can change the
+register set, including instruction pointer. This operation requires
+maximum care, such as keeping the stack frame, recovering the execution
+path etc. Since it operates on a running kernel and needs deep knowledge
+of computer architecture and concurrent computing, you can easily shoot
+your foot.
+
+If you change the instruction pointer (and set up other related
+registers) in pre_handler, you must return !0 so that kprobes stops
+single stepping and just returns to the given address.
+This also means post_handler should not be called anymore.
+
+Note that this operation may be harder on some architectures which use
+TOC (Table of Contents) for function call, since you have to setup a new
+TOC for your function in your module, and recover the old one after
+returning from it.
+
+Return Probes
+-------------
+
+How Does a Return Probe Work?
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+When you call register_kretprobe(), Kprobes establishes a kprobe at
+the entry to the function. When the probed function is called and this
+probe is hit, Kprobes saves a copy of the return address, and replaces
+the return address with the address of a "trampoline." The trampoline
+is an arbitrary piece of code -- typically just a nop instruction.
+At boot time, Kprobes registers a kprobe at the trampoline.
+
+When the probed function executes its return instruction, control
+passes to the trampoline and that probe is hit. Kprobes' trampoline
+handler calls the user-specified return handler associated with the
+kretprobe, then sets the saved instruction pointer to the saved return
+address, and that's where execution resumes upon return from the trap.
+
+While the probed function is executing, its return address is
+stored in an object of type kretprobe_instance. Before calling
+register_kretprobe(), the user sets the maxactive field of the
+kretprobe struct to specify how many instances of the specified
+function can be probed simultaneously. register_kretprobe()
+pre-allocates the indicated number of kretprobe_instance objects.
+
+For example, if the function is non-recursive and is called with a
+spinlock held, maxactive = 1 should be enough. If the function is
+non-recursive and can never relinquish the CPU (e.g., via a semaphore
+or preemption), NR_CPUS should be enough. If maxactive <= 0, it is
+set to a default value. If CONFIG_PREEMPT is enabled, the default
+is max(10, 2*NR_CPUS). Otherwise, the default is NR_CPUS.
+
+It's not a disaster if you set maxactive too low; you'll just miss
+some probes. In the kretprobe struct, the nmissed field is set to
+zero when the return probe is registered, and is incremented every
+time the probed function is entered but there is no kretprobe_instance
+object available for establishing the return probe.
+
+Kretprobe entry-handler
+^^^^^^^^^^^^^^^^^^^^^^^
+
+Kretprobes also provides an optional user-specified handler which runs
+on function entry. This handler is specified by setting the entry_handler
+field of the kretprobe struct. Whenever the kprobe placed by kretprobe at the
+function entry is hit, the user-defined entry_handler, if any, is invoked.
+If the entry_handler returns 0 (success) then a corresponding return handler
+is guaranteed to be called upon function return. If the entry_handler
+returns a non-zero error then Kprobes leaves the return address as is, and
+the kretprobe has no further effect for that particular function instance.
+
+Multiple entry and return handler invocations are matched using the unique
+kretprobe_instance object associated with them. Additionally, a user
+may also specify per return-instance private data to be part of each
+kretprobe_instance object. This is especially useful when sharing private
+data between corresponding user entry and return handlers. The size of each
+private data object can be specified at kretprobe registration time by
+setting the data_size field of the kretprobe struct. This data can be
+accessed through the data field of each kretprobe_instance object.
+
+In case probed function is entered but there is no kretprobe_instance
+object available, then in addition to incrementing the nmissed count,
+the user entry_handler invocation is also skipped.
+
+.. _kprobes_jump_optimization:
+
+How Does Jump Optimization Work?
+--------------------------------
+
+If your kernel is built with CONFIG_OPTPROBES=y (currently this flag
+is automatically set 'y' on x86/x86-64, non-preemptive kernel) and
+the "debug.kprobes_optimization" kernel parameter is set to 1 (see
+sysctl(8)), Kprobes tries to reduce probe-hit overhead by using a jump
+instruction instead of a breakpoint instruction at each probepoint.
+
+Init a Kprobe
+^^^^^^^^^^^^^
+
+When a probe is registered, before attempting this optimization,
+Kprobes inserts an ordinary, breakpoint-based kprobe at the specified
+address. So, even if it's not possible to optimize this particular
+probepoint, there'll be a probe there.
+
+Safety Check
+^^^^^^^^^^^^
+
+Before optimizing a probe, Kprobes performs the following safety checks:
+
+- Kprobes verifies that the region that will be replaced by the jump
+ instruction (the "optimized region") lies entirely within one function.
+ (A jump instruction is multiple bytes, and so may overlay multiple
+ instructions.)
+
+- Kprobes analyzes the entire function and verifies that there is no
+ jump into the optimized region. Specifically:
+
+ - the function contains no indirect jump;
+ - the function contains no instruction that causes an exception (since
+ the fixup code triggered by the exception could jump back into the
+ optimized region -- Kprobes checks the exception tables to verify this);
+ - there is no near jump to the optimized region (other than to the first
+ byte).
+
+- For each instruction in the optimized region, Kprobes verifies that
+ the instruction can be executed out of line.
+
+Preparing Detour Buffer
+^^^^^^^^^^^^^^^^^^^^^^^
+
+Next, Kprobes prepares a "detour" buffer, which contains the following
+instruction sequence:
+
+- code to push the CPU's registers (emulating a breakpoint trap)
+- a call to the trampoline code which calls user's probe handlers.
+- code to restore registers
+- the instructions from the optimized region
+- a jump back to the original execution path.
+
+Pre-optimization
+^^^^^^^^^^^^^^^^
+
+After preparing the detour buffer, Kprobes verifies that none of the
+following situations exist:
+
+- The probe has a post_handler.
+- Other instructions in the optimized region are probed.
+- The probe is disabled.
+
+In any of the above cases, Kprobes won't start optimizing the probe.
+Since these are temporary situations, Kprobes tries to start
+optimizing it again if the situation is changed.
+
+If the kprobe can be optimized, Kprobes enqueues the kprobe to an
+optimizing list, and kicks the kprobe-optimizer workqueue to optimize
+it. If the to-be-optimized probepoint is hit before being optimized,
+Kprobes returns control to the original instruction path by setting
+the CPU's instruction pointer to the copied code in the detour buffer
+-- thus at least avoiding the single-step.
+
+Optimization
+^^^^^^^^^^^^
+
+The Kprobe-optimizer doesn't insert the jump instruction immediately;
+rather, it calls synchronize_rcu() for safety first, because it's
+possible for a CPU to be interrupted in the middle of executing the
+optimized region [3]_. As you know, synchronize_rcu() can ensure
+that all interruptions that were active when synchronize_rcu()
+was called are done, but only if CONFIG_PREEMPT=n. So, this version
+of kprobe optimization supports only kernels with CONFIG_PREEMPT=n [4]_.
+
+After that, the Kprobe-optimizer calls stop_machine() to replace
+the optimized region with a jump instruction to the detour buffer,
+using text_poke_smp().
+
+Unoptimization
+^^^^^^^^^^^^^^
+
+When an optimized kprobe is unregistered, disabled, or blocked by
+another kprobe, it will be unoptimized. If this happens before
+the optimization is complete, the kprobe is just dequeued from the
+optimized list. If the optimization has been done, the jump is
+replaced with the original code (except for an int3 breakpoint in
+the first byte) by using text_poke_smp().
+
+.. [3] Please imagine that the 2nd instruction is interrupted and then
+ the optimizer replaces the 2nd instruction with the jump *address*
+ while the interrupt handler is running. When the interrupt
+ returns to original address, there is no valid instruction,
+ and it causes an unexpected result.
+
+.. [4] This optimization-safety checking may be replaced with the
+ stop-machine method that ksplice uses for supporting a CONFIG_PREEMPT=y
+ kernel.
+
+NOTE for geeks:
+The jump optimization changes the kprobe's pre_handler behavior.
+Without optimization, the pre_handler can change the kernel's execution
+path by changing regs->ip and returning 1. However, when the probe
+is optimized, that modification is ignored. Thus, if you want to
+tweak the kernel's execution path, you need to suppress optimization,
+using one of the following techniques:
+
+- Specify an empty function for the kprobe's post_handler.
+
+or
+
+- Execute 'sysctl -w debug.kprobes_optimization=n'
+
+.. _kprobes_blacklist:
+
+Blacklist
+---------
+
+Kprobes can probe most of the kernel except itself. This means
+that there are some functions where kprobes cannot probe. Probing
+(trapping) such functions can cause a recursive trap (e.g. double
+fault) or the nested probe handler may never be called.
+Kprobes manages such functions as a blacklist.
+If you want to add a function into the blacklist, you just need
+to (1) include linux/kprobes.h and (2) use NOKPROBE_SYMBOL() macro
+to specify a blacklisted function.
+Kprobes checks the given probe address against the blacklist and
+rejects registering it, if the given address is in the blacklist.
+
+.. _kprobes_archs_supported:
+
+Architectures Supported
+=======================
+
+Kprobes and return probes are implemented on the following
+architectures:
+
+- i386 (Supports jump optimization)
+- x86_64 (AMD-64, EM64T) (Supports jump optimization)
+- ppc64
+- ia64 (Does not support probes on instruction slot1.)
+- sparc64 (Return probes not yet implemented.)
+- arm
+- ppc
+- mips
+- s390
+- parisc
+
+Configuring Kprobes
+===================
+
+When configuring the kernel using make menuconfig/xconfig/oldconfig,
+ensure that CONFIG_KPROBES is set to "y". Under "General setup", look
+for "Kprobes".
+
+So that you can load and unload Kprobes-based instrumentation modules,
+make sure "Loadable module support" (CONFIG_MODULES) and "Module
+unloading" (CONFIG_MODULE_UNLOAD) are set to "y".
+
+Also make sure that CONFIG_KALLSYMS and perhaps even CONFIG_KALLSYMS_ALL
+are set to "y", since kallsyms_lookup_name() is used by the in-kernel
+kprobe address resolution code.
+
+If you need to insert a probe in the middle of a function, you may find
+it useful to "Compile the kernel with debug info" (CONFIG_DEBUG_INFO),
+so you can use "objdump -d -l vmlinux" to see the source-to-object
+code mapping.
+
+API Reference
+=============
+
+The Kprobes API includes a "register" function and an "unregister"
+function for each type of probe. The API also includes "register_*probes"
+and "unregister_*probes" functions for (un)registering arrays of probes.
+Here are terse, mini-man-page specifications for these functions and
+the associated probe handlers that you'll write. See the files in the
+samples/kprobes/ sub-directory for examples.
+
+register_kprobe
+---------------
+
+::
+
+ #include <linux/kprobes.h>
+ int register_kprobe(struct kprobe *kp);
+
+Sets a breakpoint at the address kp->addr. When the breakpoint is
+hit, Kprobes calls kp->pre_handler. After the probed instruction
+is single-stepped, Kprobe calls kp->post_handler. If a fault
+occurs during execution of kp->pre_handler or kp->post_handler,
+or during single-stepping of the probed instruction, Kprobes calls
+kp->fault_handler. Any or all handlers can be NULL. If kp->flags
+is set KPROBE_FLAG_DISABLED, that kp will be registered but disabled,
+so, its handlers aren't hit until calling enable_kprobe(kp).
+
+.. note::
+
+ 1. With the introduction of the "symbol_name" field to struct kprobe,
+ the probepoint address resolution will now be taken care of by the kernel.
+ The following will now work::
+
+ kp.symbol_name = "symbol_name";
+
+ (64-bit powerpc intricacies such as function descriptors are handled
+ transparently)
+
+ 2. Use the "offset" field of struct kprobe if the offset into the symbol
+ to install a probepoint is known. This field is used to calculate the
+ probepoint.
+
+ 3. Specify either the kprobe "symbol_name" OR the "addr". If both are
+ specified, kprobe registration will fail with -EINVAL.
+
+ 4. With CISC architectures (such as i386 and x86_64), the kprobes code
+ does not validate if the kprobe.addr is at an instruction boundary.
+ Use "offset" with caution.
+
+register_kprobe() returns 0 on success, or a negative errno otherwise.
+
+User's pre-handler (kp->pre_handler)::
+
+ #include <linux/kprobes.h>
+ #include <linux/ptrace.h>
+ int pre_handler(struct kprobe *p, struct pt_regs *regs);
+
+Called with p pointing to the kprobe associated with the breakpoint,
+and regs pointing to the struct containing the registers saved when
+the breakpoint was hit. Return 0 here unless you're a Kprobes geek.
+
+User's post-handler (kp->post_handler)::
+
+ #include <linux/kprobes.h>
+ #include <linux/ptrace.h>
+ void post_handler(struct kprobe *p, struct pt_regs *regs,
+ unsigned long flags);
+
+p and regs are as described for the pre_handler. flags always seems
+to be zero.
+
+User's fault-handler (kp->fault_handler)::
+
+ #include <linux/kprobes.h>
+ #include <linux/ptrace.h>
+ int fault_handler(struct kprobe *p, struct pt_regs *regs, int trapnr);
+
+p and regs are as described for the pre_handler. trapnr is the
+architecture-specific trap number associated with the fault (e.g.,
+on i386, 13 for a general protection fault or 14 for a page fault).
+Returns 1 if it successfully handled the exception.
+
+register_kretprobe
+------------------
+
+::
+
+ #include <linux/kprobes.h>
+ int register_kretprobe(struct kretprobe *rp);
+
+Establishes a return probe for the function whose address is
+rp->kp.addr. When that function returns, Kprobes calls rp->handler.
+You must set rp->maxactive appropriately before you call
+register_kretprobe(); see "How Does a Return Probe Work?" for details.
+
+register_kretprobe() returns 0 on success, or a negative errno
+otherwise.
+
+User's return-probe handler (rp->handler)::
+
+ #include <linux/kprobes.h>
+ #include <linux/ptrace.h>
+ int kretprobe_handler(struct kretprobe_instance *ri,
+ struct pt_regs *regs);
+
+regs is as described for kprobe.pre_handler. ri points to the
+kretprobe_instance object, of which the following fields may be
+of interest:
+
+- ret_addr: the return address
+- rp: points to the corresponding kretprobe object
+- task: points to the corresponding task struct
+- data: points to per return-instance private data; see "Kretprobe
+ entry-handler" for details.
+
+The regs_return_value(regs) macro provides a simple abstraction to
+extract the return value from the appropriate register as defined by
+the architecture's ABI.
+
+The handler's return value is currently ignored.
+
+unregister_*probe
+------------------
+
+::
+
+ #include <linux/kprobes.h>
+ void unregister_kprobe(struct kprobe *kp);
+ void unregister_kretprobe(struct kretprobe *rp);
+
+Removes the specified probe. The unregister function can be called
+at any time after the probe has been registered.
+
+.. note::
+
+ If the functions find an incorrect probe (ex. an unregistered probe),
+ they clear the addr field of the probe.
+
+register_*probes
+----------------
+
+::
+
+ #include <linux/kprobes.h>
+ int register_kprobes(struct kprobe **kps, int num);
+ int register_kretprobes(struct kretprobe **rps, int num);
+
+Registers each of the num probes in the specified array. If any
+error occurs during registration, all probes in the array, up to
+the bad probe, are safely unregistered before the register_*probes
+function returns.
+
+- kps/rps: an array of pointers to ``*probe`` data structures
+- num: the number of the array entries.
+
+.. note::
+
+ You have to allocate(or define) an array of pointers and set all
+ of the array entries before using these functions.
+
+unregister_*probes
+------------------
+
+::
+
+ #include <linux/kprobes.h>
+ void unregister_kprobes(struct kprobe **kps, int num);
+ void unregister_kretprobes(struct kretprobe **rps, int num);
+
+Removes each of the num probes in the specified array at once.
+
+.. note::
+
+ If the functions find some incorrect probes (ex. unregistered
+ probes) in the specified array, they clear the addr field of those
+ incorrect probes. However, other probes in the array are
+ unregistered correctly.
+
+disable_*probe
+--------------
+
+::
+
+ #include <linux/kprobes.h>
+ int disable_kprobe(struct kprobe *kp);
+ int disable_kretprobe(struct kretprobe *rp);
+
+Temporarily disables the specified ``*probe``. You can enable it again by using
+enable_*probe(). You must specify the probe which has been registered.
+
+enable_*probe
+-------------
+
+::
+
+ #include <linux/kprobes.h>
+ int enable_kprobe(struct kprobe *kp);
+ int enable_kretprobe(struct kretprobe *rp);
+
+Enables ``*probe`` which has been disabled by disable_*probe(). You must specify
+the probe which has been registered.
+
+Kprobes Features and Limitations
+================================
+
+Kprobes allows multiple probes at the same address. Also,
+a probepoint for which there is a post_handler cannot be optimized.
+So if you install a kprobe with a post_handler, at an optimized
+probepoint, the probepoint will be unoptimized automatically.
+
+In general, you can install a probe anywhere in the kernel.
+In particular, you can probe interrupt handlers. Known exceptions
+are discussed in this section.
+
+The register_*probe functions will return -EINVAL if you attempt
+to install a probe in the code that implements Kprobes (mostly
+kernel/kprobes.c and ``arch/*/kernel/kprobes.c``, but also functions such
+as do_page_fault and notifier_call_chain).
+
+If you install a probe in an inline-able function, Kprobes makes
+no attempt to chase down all inline instances of the function and
+install probes there. gcc may inline a function without being asked,
+so keep this in mind if you're not seeing the probe hits you expect.
+
+A probe handler can modify the environment of the probed function
+-- e.g., by modifying kernel data structures, or by modifying the
+contents of the pt_regs struct (which are restored to the registers
+upon return from the breakpoint). So Kprobes can be used, for example,
+to install a bug fix or to inject faults for testing. Kprobes, of
+course, has no way to distinguish the deliberately injected faults
+from the accidental ones. Don't drink and probe.
+
+Kprobes makes no attempt to prevent probe handlers from stepping on
+each other -- e.g., probing printk() and then calling printk() from a
+probe handler. If a probe handler hits a probe, that second probe's
+handlers won't be run in that instance, and the kprobe.nmissed member
+of the second probe will be incremented.
+
+As of Linux v2.6.15-rc1, multiple handlers (or multiple instances of
+the same handler) may run concurrently on different CPUs.
+
+Kprobes does not use mutexes or allocate memory except during
+registration and unregistration.
+
+Probe handlers are run with preemption disabled or interrupt disabled,
+which depends on the architecture and optimization state. (e.g.,
+kretprobe handlers and optimized kprobe handlers run without interrupt
+disabled on x86/x86-64). In any case, your handler should not yield
+the CPU (e.g., by attempting to acquire a semaphore, or waiting I/O).
+
+Since a return probe is implemented by replacing the return
+address with the trampoline's address, stack backtraces and calls
+to __builtin_return_address() will typically yield the trampoline's
+address instead of the real return address for kretprobed functions.
+(As far as we can tell, __builtin_return_address() is used only
+for instrumentation and error reporting.)
+
+If the number of times a function is called does not match the number
+of times it returns, registering a return probe on that function may
+produce undesirable results. In such a case, a line:
+kretprobe BUG!: Processing kretprobe d000000000041aa8 @ c00000000004f48c
+gets printed. With this information, one will be able to correlate the
+exact instance of the kretprobe that caused the problem. We have the
+do_exit() case covered. do_execve() and do_fork() are not an issue.
+We're unaware of other specific cases where this could be a problem.
+
+If, upon entry to or exit from a function, the CPU is running on
+a stack other than that of the current task, registering a return
+probe on that function may produce undesirable results. For this
+reason, Kprobes doesn't support return probes (or kprobes)
+on the x86_64 version of __switch_to(); the registration functions
+return -EINVAL.
+
+On x86/x86-64, since the Jump Optimization of Kprobes modifies
+instructions widely, there are some limitations to optimization. To
+explain it, we introduce some terminology. Imagine a 3-instruction
+sequence consisting of a two 2-byte instructions and one 3-byte
+instruction.
+
+::
+
+ IA
+ |
+ [-2][-1][0][1][2][3][4][5][6][7]
+ [ins1][ins2][ ins3 ]
+ [<- DCR ->]
+ [<- JTPR ->]
+
+ ins1: 1st Instruction
+ ins2: 2nd Instruction
+ ins3: 3rd Instruction
+ IA: Insertion Address
+ JTPR: Jump Target Prohibition Region
+ DCR: Detoured Code Region
+
+The instructions in DCR are copied to the out-of-line buffer
+of the kprobe, because the bytes in DCR are replaced by
+a 5-byte jump instruction. So there are several limitations.
+
+a) The instructions in DCR must be relocatable.
+b) The instructions in DCR must not include a call instruction.
+c) JTPR must not be targeted by any jump or call instruction.
+d) DCR must not straddle the border between functions.
+
+Anyway, these limitations are checked by the in-kernel instruction
+decoder, so you don't need to worry about that.
+
+Probe Overhead
+==============
+
+On a typical CPU in use in 2005, a kprobe hit takes 0.5 to 1.0
+microseconds to process. Specifically, a benchmark that hits the same
+probepoint repeatedly, firing a simple handler each time, reports 1-2
+million hits per second, depending on the architecture. A return-probe
+hit typically takes 50-75% longer than a kprobe hit.
+When you have a return probe set on a function, adding a kprobe at
+the entry to that function adds essentially no overhead.
+
+Here are sample overhead figures (in usec) for different architectures::
+
+ k = kprobe; r = return probe; kr = kprobe + return probe
+ on same function
+
+ i386: Intel Pentium M, 1495 MHz, 2957.31 bogomips
+ k = 0.57 usec; r = 0.92; kr = 0.99
+
+ x86_64: AMD Opteron 246, 1994 MHz, 3971.48 bogomips
+ k = 0.49 usec; r = 0.80; kr = 0.82
+
+ ppc64: POWER5 (gr), 1656 MHz (SMT disabled, 1 virtual CPU per physical CPU)
+ k = 0.77 usec; r = 1.26; kr = 1.45
+
+Optimized Probe Overhead
+------------------------
+
+Typically, an optimized kprobe hit takes 0.07 to 0.1 microseconds to
+process. Here are sample overhead figures (in usec) for x86 architectures::
+
+ k = unoptimized kprobe, b = boosted (single-step skipped), o = optimized kprobe,
+ r = unoptimized kretprobe, rb = boosted kretprobe, ro = optimized kretprobe.
+
+ i386: Intel(R) Xeon(R) E5410, 2.33GHz, 4656.90 bogomips
+ k = 0.80 usec; b = 0.33; o = 0.05; r = 1.10; rb = 0.61; ro = 0.33
+
+ x86-64: Intel(R) Xeon(R) E5410, 2.33GHz, 4656.90 bogomips
+ k = 0.99 usec; b = 0.43; o = 0.06; r = 1.24; rb = 0.68; ro = 0.30
+
+TODO
+====
+
+a. SystemTap (http://sourceware.org/systemtap): Provides a simplified
+ programming interface for probe-based instrumentation. Try it out.
+b. Kernel return probes for sparc64.
+c. Support for other architectures.
+d. User-space probes.
+e. Watchpoint probes (which fire on data references).
+
+Kprobes Example
+===============
+
+See samples/kprobes/kprobe_example.c
+
+Kretprobes Example
+==================
+
+See samples/kprobes/kretprobe_example.c
+
+Deprecated Features
+===================
+
+Jprobes is now a deprecated feature. People who are depending on it should
+migrate to other tracing features or use older kernels. Please consider to
+migrate your tool to one of the following options:
+
+- Use trace-event to trace target function with arguments.
+
+ trace-event is a low-overhead (and almost no visible overhead if it
+ is off) statically defined event interface. You can define new events
+ and trace it via ftrace or any other tracing tools.
+
+ See the following urls:
+
+ - https://lwn.net/Articles/379903/
+ - https://lwn.net/Articles/381064/
+ - https://lwn.net/Articles/383362/
+
+- Use ftrace dynamic events (kprobe event) with perf-probe.
+
+ If you build your kernel with debug info (CONFIG_DEBUG_INFO=y), you can
+ find which register/stack is assigned to which local variable or arguments
+ by using perf-probe and set up new event to trace it.
+
+ See following documents:
+
+ - Documentation/trace/kprobetrace.rst
+ - Documentation/trace/events.rst
+ - tools/perf/Documentation/perf-probe.txt
+
+
+The kprobes debugfs interface
+=============================
+
+
+With recent kernels (> 2.6.20) the list of registered kprobes is visible
+under the /sys/kernel/debug/kprobes/ directory (assuming debugfs is mounted at //sys/kernel/debug).
+
+/sys/kernel/debug/kprobes/list: Lists all registered probes on the system::
+
+ c015d71a k vfs_read+0x0
+ c03dedc5 r tcp_v4_rcv+0x0
+
+The first column provides the kernel address where the probe is inserted.
+The second column identifies the type of probe (k - kprobe and r - kretprobe)
+while the third column specifies the symbol+offset of the probe.
+If the probed function belongs to a module, the module name is also
+specified. Following columns show probe status. If the probe is on
+a virtual address that is no longer valid (module init sections, module
+virtual addresses that correspond to modules that've been unloaded),
+such probes are marked with [GONE]. If the probe is temporarily disabled,
+such probes are marked with [DISABLED]. If the probe is optimized, it is
+marked with [OPTIMIZED]. If the probe is ftrace-based, it is marked with
+[FTRACE].
+
+/sys/kernel/debug/kprobes/enabled: Turn kprobes ON/OFF forcibly.
+
+Provides a knob to globally and forcibly turn registered kprobes ON or OFF.
+By default, all kprobes are enabled. By echoing "0" to this file, all
+registered probes will be disarmed, till such time a "1" is echoed to this
+file. Note that this knob just disarms and arms all kprobes and doesn't
+change each probe's disabling state. This means that disabled kprobes (marked
+[DISABLED]) will be not enabled if you turn ON all kprobes by this knob.
+
+
+The kprobes sysctl interface
+============================
+
+/proc/sys/debug/kprobes-optimization: Turn kprobes optimization ON/OFF.
+
+When CONFIG_OPTPROBES=y, this sysctl interface appears and it provides
+a knob to globally and forcibly turn jump optimization (see section
+:ref:`kprobes_jump_optimization`) ON or OFF. By default, jump optimization
+is allowed (ON). If you echo "0" to this file or set
+"debug.kprobes_optimization" to 0 via sysctl, all optimized probes will be
+unoptimized, and any new probes registered after that will not be optimized.
+
+Note that this knob *changes* the optimized state. This means that optimized
+probes (marked [OPTIMIZED]) will be unoptimized ([OPTIMIZED] tag will be
+removed). If the knob is turned on, they will be optimized again.
+
+References
+==========
+
+For additional information on Kprobes, refer to the following URLs:
+
+- https://www.ibm.com/developerworks/library/l-kprobes/index.html
+- https://www.kernel.org/doc/ols/2006/ols2006v2-pages-109-124.pdf
+
diff --git a/Documentation/trace/kprobetrace.rst b/Documentation/trace/kprobetrace.rst
index cc4c5fc..c170916 100644
--- a/Documentation/trace/kprobetrace.rst
+++ b/Documentation/trace/kprobetrace.rst
@@ -40,7 +40,7 @@
MEMADDR : Address where the probe is inserted.
MAXACTIVE : Maximum number of instances of the specified function that
can be probed simultaneously, or 0 for the default value
- as defined in Documentation/kprobes.txt section 1.3.1.
+ as defined in Documentation/staging/kprobes.rst section 1.3.1.
FETCHARGS : Arguments. Each probe can have up to 128 args.
%REG : Fetch register REG
diff --git a/Documentation/trace/ring-buffer-design.rst b/Documentation/trace/ring-buffer-design.rst
new file mode 100644
index 0000000..9c8d22a
--- /dev/null
+++ b/Documentation/trace/ring-buffer-design.rst
@@ -0,0 +1,1007 @@
+.. This file is dual-licensed: you can use it either under the terms
+.. of the GPL 2.0 or the GFDL 1.2 license, at your option. Note that this
+.. dual licensing only applies to this file, and not this project as a
+.. whole.
+..
+.. a) This file is free software; you can redistribute it and/or
+.. modify it under the terms of the GNU General Public License as
+.. published by the Free Software Foundation version 2 of
+.. the License.
+..
+.. This file is distributed in the hope that it will be useful,
+.. but WITHOUT ANY WARRANTY; without even the implied warranty of
+.. MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+.. GNU General Public License for more details.
+..
+.. Or, alternatively,
+..
+.. b) Permission is granted to copy, distribute and/or modify this
+.. document under the terms of the GNU Free Documentation License,
+.. Version 1.2 version published by the Free Software
+.. Foundation, with no Invariant Sections, no Front-Cover Texts
+.. and no Back-Cover Texts. A copy of the license is included at
+.. Documentation/userspace-api/media/fdl-appendix.rst.
+..
+.. TODO: replace it to GPL-2.0 OR GFDL-1.2 WITH no-invariant-sections
+
+===========================
+Lockless Ring Buffer Design
+===========================
+
+Copyright 2009 Red Hat Inc.
+
+:Author: Steven Rostedt <srostedt@redhat.com>
+:License: The GNU Free Documentation License, Version 1.2
+ (dual licensed under the GPL v2)
+:Reviewers: Mathieu Desnoyers, Huang Ying, Hidetoshi Seto,
+ and Frederic Weisbecker.
+
+
+Written for: 2.6.31
+
+Terminology used in this Document
+---------------------------------
+
+tail
+ - where new writes happen in the ring buffer.
+
+head
+ - where new reads happen in the ring buffer.
+
+producer
+ - the task that writes into the ring buffer (same as writer)
+
+writer
+ - same as producer
+
+consumer
+ - the task that reads from the buffer (same as reader)
+
+reader
+ - same as consumer.
+
+reader_page
+ - A page outside the ring buffer used solely (for the most part)
+ by the reader.
+
+head_page
+ - a pointer to the page that the reader will use next
+
+tail_page
+ - a pointer to the page that will be written to next
+
+commit_page
+ - a pointer to the page with the last finished non-nested write.
+
+cmpxchg
+ - hardware-assisted atomic transaction that performs the following::
+
+ A = B if previous A == C
+
+ R = cmpxchg(A, C, B) is saying that we replace A with B if and only
+ if current A is equal to C, and we put the old (current)
+ A into R
+
+ R gets the previous A regardless if A is updated with B or not.
+
+ To see if the update was successful a compare of ``R == C``
+ may be used.
+
+The Generic Ring Buffer
+-----------------------
+
+The ring buffer can be used in either an overwrite mode or in
+producer/consumer mode.
+
+Producer/consumer mode is where if the producer were to fill up the
+buffer before the consumer could free up anything, the producer
+will stop writing to the buffer. This will lose most recent events.
+
+Overwrite mode is where if the producer were to fill up the buffer
+before the consumer could free up anything, the producer will
+overwrite the older data. This will lose the oldest events.
+
+No two writers can write at the same time (on the same per-cpu buffer),
+but a writer may interrupt another writer, but it must finish writing
+before the previous writer may continue. This is very important to the
+algorithm. The writers act like a "stack". The way interrupts works
+enforces this behavior::
+
+
+ writer1 start
+ <preempted> writer2 start
+ <preempted> writer3 start
+ writer3 finishes
+ writer2 finishes
+ writer1 finishes
+
+This is very much like a writer being preempted by an interrupt and
+the interrupt doing a write as well.
+
+Readers can happen at any time. But no two readers may run at the
+same time, nor can a reader preempt/interrupt another reader. A reader
+cannot preempt/interrupt a writer, but it may read/consume from the
+buffer at the same time as a writer is writing, but the reader must be
+on another processor to do so. A reader may read on its own processor
+and can be preempted by a writer.
+
+A writer can preempt a reader, but a reader cannot preempt a writer.
+But a reader can read the buffer at the same time (on another processor)
+as a writer.
+
+The ring buffer is made up of a list of pages held together by a linked list.
+
+At initialization a reader page is allocated for the reader that is not
+part of the ring buffer.
+
+The head_page, tail_page and commit_page are all initialized to point
+to the same page.
+
+The reader page is initialized to have its next pointer pointing to
+the head page, and its previous pointer pointing to a page before
+the head page.
+
+The reader has its own page to use. At start up time, this page is
+allocated but is not attached to the list. When the reader wants
+to read from the buffer, if its page is empty (like it is on start-up),
+it will swap its page with the head_page. The old reader page will
+become part of the ring buffer and the head_page will be removed.
+The page after the inserted page (old reader_page) will become the
+new head page.
+
+Once the new page is given to the reader, the reader could do what
+it wants with it, as long as a writer has left that page.
+
+A sample of how the reader page is swapped: Note this does not
+show the head page in the buffer, it is for demonstrating a swap
+only.
+
+::
+
+ +------+
+ |reader| RING BUFFER
+ |page |
+ +------+
+ +---+ +---+ +---+
+ | |-->| |-->| |
+ | |<--| |<--| |
+ +---+ +---+ +---+
+ ^ | ^ |
+ | +-------------+ |
+ +-----------------+
+
+
+ +------+
+ |reader| RING BUFFER
+ |page |-------------------+
+ +------+ v
+ | +---+ +---+ +---+
+ | | |-->| |-->| |
+ | | |<--| |<--| |<-+
+ | +---+ +---+ +---+ |
+ | ^ | ^ | |
+ | | +-------------+ | |
+ | +-----------------+ |
+ +------------------------------------+
+
+ +------+
+ |reader| RING BUFFER
+ |page |-------------------+
+ +------+ <---------------+ v
+ | ^ +---+ +---+ +---+
+ | | | |-->| |-->| |
+ | | | | | |<--| |<-+
+ | | +---+ +---+ +---+ |
+ | | | ^ | |
+ | | +-------------+ | |
+ | +-----------------------------+ |
+ +------------------------------------+
+
+ +------+
+ |buffer| RING BUFFER
+ |page |-------------------+
+ +------+ <---------------+ v
+ | ^ +---+ +---+ +---+
+ | | | | | |-->| |
+ | | New | | | |<--| |<-+
+ | | Reader +---+ +---+ +---+ |
+ | | page ----^ | |
+ | | | |
+ | +-----------------------------+ |
+ +------------------------------------+
+
+
+
+It is possible that the page swapped is the commit page and the tail page,
+if what is in the ring buffer is less than what is held in a buffer page.
+
+::
+
+ reader page commit page tail page
+ | | |
+ v | |
+ +---+ | |
+ | |<----------+ |
+ | |<------------------------+
+ | |------+
+ +---+ |
+ |
+ v
+ +---+ +---+ +---+ +---+
+ <---| |--->| |--->| |--->| |--->
+ --->| |<---| |<---| |<---| |<---
+ +---+ +---+ +---+ +---+
+
+This case is still valid for this algorithm.
+When the writer leaves the page, it simply goes into the ring buffer
+since the reader page still points to the next location in the ring
+buffer.
+
+
+The main pointers:
+
+ reader page
+ - The page used solely by the reader and is not part
+ of the ring buffer (may be swapped in)
+
+ head page
+ - the next page in the ring buffer that will be swapped
+ with the reader page.
+
+ tail page
+ - the page where the next write will take place.
+
+ commit page
+ - the page that last finished a write.
+
+The commit page only is updated by the outermost writer in the
+writer stack. A writer that preempts another writer will not move the
+commit page.
+
+When data is written into the ring buffer, a position is reserved
+in the ring buffer and passed back to the writer. When the writer
+is finished writing data into that position, it commits the write.
+
+Another write (or a read) may take place at anytime during this
+transaction. If another write happens it must finish before continuing
+with the previous write.
+
+
+ Write reserve::
+
+ Buffer page
+ +---------+
+ |written |
+ +---------+ <--- given back to writer (current commit)
+ |reserved |
+ +---------+ <--- tail pointer
+ | empty |
+ +---------+
+
+ Write commit::
+
+ Buffer page
+ +---------+
+ |written |
+ +---------+
+ |written |
+ +---------+ <--- next position for write (current commit)
+ | empty |
+ +---------+
+
+
+ If a write happens after the first reserve::
+
+ Buffer page
+ +---------+
+ |written |
+ +---------+ <-- current commit
+ |reserved |
+ +---------+ <--- given back to second writer
+ |reserved |
+ +---------+ <--- tail pointer
+
+ After second writer commits::
+
+
+ Buffer page
+ +---------+
+ |written |
+ +---------+ <--(last full commit)
+ |reserved |
+ +---------+
+ |pending |
+ |commit |
+ +---------+ <--- tail pointer
+
+ When the first writer commits::
+
+ Buffer page
+ +---------+
+ |written |
+ +---------+
+ |written |
+ +---------+
+ |written |
+ +---------+ <--(last full commit and tail pointer)
+
+
+The commit pointer points to the last write location that was
+committed without preempting another write. When a write that
+preempted another write is committed, it only becomes a pending commit
+and will not be a full commit until all writes have been committed.
+
+The commit page points to the page that has the last full commit.
+The tail page points to the page with the last write (before
+committing).
+
+The tail page is always equal to or after the commit page. It may
+be several pages ahead. If the tail page catches up to the commit
+page then no more writes may take place (regardless of the mode
+of the ring buffer: overwrite and produce/consumer).
+
+The order of pages is::
+
+ head page
+ commit page
+ tail page
+
+Possible scenario::
+
+ tail page
+ head page commit page |
+ | | |
+ v v v
+ +---+ +---+ +---+ +---+
+ <---| |--->| |--->| |--->| |--->
+ --->| |<---| |<---| |<---| |<---
+ +---+ +---+ +---+ +---+
+
+There is a special case that the head page is after either the commit page
+and possibly the tail page. That is when the commit (and tail) page has been
+swapped with the reader page. This is because the head page is always
+part of the ring buffer, but the reader page is not. Whenever there
+has been less than a full page that has been committed inside the ring buffer,
+and a reader swaps out a page, it will be swapping out the commit page.
+
+::
+
+ reader page commit page tail page
+ | | |
+ v | |
+ +---+ | |
+ | |<----------+ |
+ | |<------------------------+
+ | |------+
+ +---+ |
+ |
+ v
+ +---+ +---+ +---+ +---+
+ <---| |--->| |--->| |--->| |--->
+ --->| |<---| |<---| |<---| |<---
+ +---+ +---+ +---+ +---+
+ ^
+ |
+ head page
+
+
+In this case, the head page will not move when the tail and commit
+move back into the ring buffer.
+
+The reader cannot swap a page into the ring buffer if the commit page
+is still on that page. If the read meets the last commit (real commit
+not pending or reserved), then there is nothing more to read.
+The buffer is considered empty until another full commit finishes.
+
+When the tail meets the head page, if the buffer is in overwrite mode,
+the head page will be pushed ahead one. If the buffer is in producer/consumer
+mode, the write will fail.
+
+Overwrite mode::
+
+ tail page
+ |
+ v
+ +---+ +---+ +---+ +---+
+ <---| |--->| |--->| |--->| |--->
+ --->| |<---| |<---| |<---| |<---
+ +---+ +---+ +---+ +---+
+ ^
+ |
+ head page
+
+
+ tail page
+ |
+ v
+ +---+ +---+ +---+ +---+
+ <---| |--->| |--->| |--->| |--->
+ --->| |<---| |<---| |<---| |<---
+ +---+ +---+ +---+ +---+
+ ^
+ |
+ head page
+
+
+ tail page
+ |
+ v
+ +---+ +---+ +---+ +---+
+ <---| |--->| |--->| |--->| |--->
+ --->| |<---| |<---| |<---| |<---
+ +---+ +---+ +---+ +---+
+ ^
+ |
+ head page
+
+Note, the reader page will still point to the previous head page.
+But when a swap takes place, it will use the most recent head page.
+
+
+Making the Ring Buffer Lockless:
+--------------------------------
+
+The main idea behind the lockless algorithm is to combine the moving
+of the head_page pointer with the swapping of pages with the reader.
+State flags are placed inside the pointer to the page. To do this,
+each page must be aligned in memory by 4 bytes. This will allow the 2
+least significant bits of the address to be used as flags, since
+they will always be zero for the address. To get the address,
+simply mask out the flags::
+
+ MASK = ~3
+
+ address & MASK
+
+Two flags will be kept by these two bits:
+
+ HEADER
+ - the page being pointed to is a head page
+
+ UPDATE
+ - the page being pointed to is being updated by a writer
+ and was or is about to be a head page.
+
+::
+
+ reader page
+ |
+ v
+ +---+
+ | |------+
+ +---+ |
+ |
+ v
+ +---+ +---+ +---+ +---+
+ <---| |--->| |-H->| |--->| |--->
+ --->| |<---| |<---| |<---| |<---
+ +---+ +---+ +---+ +---+
+
+
+The above pointer "-H->" would have the HEADER flag set. That is
+the next page is the next page to be swapped out by the reader.
+This pointer means the next page is the head page.
+
+When the tail page meets the head pointer, it will use cmpxchg to
+change the pointer to the UPDATE state::
+
+
+ tail page
+ |
+ v
+ +---+ +---+ +---+ +---+
+ <---| |--->| |-H->| |--->| |--->
+ --->| |<---| |<---| |<---| |<---
+ +---+ +---+ +---+ +---+
+
+ tail page
+ |
+ v
+ +---+ +---+ +---+ +---+
+ <---| |--->| |-U->| |--->| |--->
+ --->| |<---| |<---| |<---| |<---
+ +---+ +---+ +---+ +---+
+
+"-U->" represents a pointer in the UPDATE state.
+
+Any access to the reader will need to take some sort of lock to serialize
+the readers. But the writers will never take a lock to write to the
+ring buffer. This means we only need to worry about a single reader,
+and writes only preempt in "stack" formation.
+
+When the reader tries to swap the page with the ring buffer, it
+will also use cmpxchg. If the flag bit in the pointer to the
+head page does not have the HEADER flag set, the compare will fail
+and the reader will need to look for the new head page and try again.
+Note, the flags UPDATE and HEADER are never set at the same time.
+
+The reader swaps the reader page as follows::
+
+ +------+
+ |reader| RING BUFFER
+ |page |
+ +------+
+ +---+ +---+ +---+
+ | |--->| |--->| |
+ | |<---| |<---| |
+ +---+ +---+ +---+
+ ^ | ^ |
+ | +---------------+ |
+ +-----H-------------+
+
+The reader sets the reader page next pointer as HEADER to the page after
+the head page::
+
+
+ +------+
+ |reader| RING BUFFER
+ |page |-------H-----------+
+ +------+ v
+ | +---+ +---+ +---+
+ | | |--->| |--->| |
+ | | |<---| |<---| |<-+
+ | +---+ +---+ +---+ |
+ | ^ | ^ | |
+ | | +---------------+ | |
+ | +-----H-------------+ |
+ +--------------------------------------+
+
+It does a cmpxchg with the pointer to the previous head page to make it
+point to the reader page. Note that the new pointer does not have the HEADER
+flag set. This action atomically moves the head page forward::
+
+ +------+
+ |reader| RING BUFFER
+ |page |-------H-----------+
+ +------+ v
+ | ^ +---+ +---+ +---+
+ | | | |-->| |-->| |
+ | | | |<--| |<--| |<-+
+ | | +---+ +---+ +---+ |
+ | | | ^ | |
+ | | +-------------+ | |
+ | +-----------------------------+ |
+ +------------------------------------+
+
+After the new head page is set, the previous pointer of the head page is
+updated to the reader page::
+
+ +------+
+ |reader| RING BUFFER
+ |page |-------H-----------+
+ +------+ <---------------+ v
+ | ^ +---+ +---+ +---+
+ | | | |-->| |-->| |
+ | | | | | |<--| |<-+
+ | | +---+ +---+ +---+ |
+ | | | ^ | |
+ | | +-------------+ | |
+ | +-----------------------------+ |
+ +------------------------------------+
+
+ +------+
+ |buffer| RING BUFFER
+ |page |-------H-----------+ <--- New head page
+ +------+ <---------------+ v
+ | ^ +---+ +---+ +---+
+ | | | | | |-->| |
+ | | New | | | |<--| |<-+
+ | | Reader +---+ +---+ +---+ |
+ | | page ----^ | |
+ | | | |
+ | +-----------------------------+ |
+ +------------------------------------+
+
+Another important point: The page that the reader page points back to
+by its previous pointer (the one that now points to the new head page)
+never points back to the reader page. That is because the reader page is
+not part of the ring buffer. Traversing the ring buffer via the next pointers
+will always stay in the ring buffer. Traversing the ring buffer via the
+prev pointers may not.
+
+Note, the way to determine a reader page is simply by examining the previous
+pointer of the page. If the next pointer of the previous page does not
+point back to the original page, then the original page is a reader page::
+
+
+ +--------+
+ | reader | next +----+
+ | page |-------->| |<====== (buffer page)
+ +--------+ +----+
+ | | ^
+ | v | next
+ prev | +----+
+ +------------->| |
+ +----+
+
+The way the head page moves forward:
+
+When the tail page meets the head page and the buffer is in overwrite mode
+and more writes take place, the head page must be moved forward before the
+writer may move the tail page. The way this is done is that the writer
+performs a cmpxchg to convert the pointer to the head page from the HEADER
+flag to have the UPDATE flag set. Once this is done, the reader will
+not be able to swap the head page from the buffer, nor will it be able to
+move the head page, until the writer is finished with the move.
+
+This eliminates any races that the reader can have on the writer. The reader
+must spin, and this is why the reader cannot preempt the writer::
+
+ tail page
+ |
+ v
+ +---+ +---+ +---+ +---+
+ <---| |--->| |-H->| |--->| |--->
+ --->| |<---| |<---| |<---| |<---
+ +---+ +---+ +---+ +---+
+
+ tail page
+ |
+ v
+ +---+ +---+ +---+ +---+
+ <---| |--->| |-U->| |--->| |--->
+ --->| |<---| |<---| |<---| |<---
+ +---+ +---+ +---+ +---+
+
+The following page will be made into the new head page::
+
+ tail page
+ |
+ v
+ +---+ +---+ +---+ +---+
+ <---| |--->| |-U->| |-H->| |--->
+ --->| |<---| |<---| |<---| |<---
+ +---+ +---+ +---+ +---+
+
+After the new head page has been set, we can set the old head page
+pointer back to NORMAL::
+
+ tail page
+ |
+ v
+ +---+ +---+ +---+ +---+
+ <---| |--->| |--->| |-H->| |--->
+ --->| |<---| |<---| |<---| |<---
+ +---+ +---+ +---+ +---+
+
+After the head page has been moved, the tail page may now move forward::
+
+ tail page
+ |
+ v
+ +---+ +---+ +---+ +---+
+ <---| |--->| |--->| |-H->| |--->
+ --->| |<---| |<---| |<---| |<---
+ +---+ +---+ +---+ +---+
+
+
+The above are the trivial updates. Now for the more complex scenarios.
+
+
+As stated before, if enough writes preempt the first write, the
+tail page may make it all the way around the buffer and meet the commit
+page. At this time, we must start dropping writes (usually with some kind
+of warning to the user). But what happens if the commit was still on the
+reader page? The commit page is not part of the ring buffer. The tail page
+must account for this::
+
+
+ reader page commit page
+ | |
+ v |
+ +---+ |
+ | |<----------+
+ | |
+ | |------+
+ +---+ |
+ |
+ v
+ +---+ +---+ +---+ +---+
+ <---| |--->| |-H->| |--->| |--->
+ --->| |<---| |<---| |<---| |<---
+ +---+ +---+ +---+ +---+
+ ^
+ |
+ tail page
+
+If the tail page were to simply push the head page forward, the commit when
+leaving the reader page would not be pointing to the correct page.
+
+The solution to this is to test if the commit page is on the reader page
+before pushing the head page. If it is, then it can be assumed that the
+tail page wrapped the buffer, and we must drop new writes.
+
+This is not a race condition, because the commit page can only be moved
+by the outermost writer (the writer that was preempted).
+This means that the commit will not move while a writer is moving the
+tail page. The reader cannot swap the reader page if it is also being
+used as the commit page. The reader can simply check that the commit
+is off the reader page. Once the commit page leaves the reader page
+it will never go back on it unless a reader does another swap with the
+buffer page that is also the commit page.
+
+
+Nested writes
+-------------
+
+In the pushing forward of the tail page we must first push forward
+the head page if the head page is the next page. If the head page
+is not the next page, the tail page is simply updated with a cmpxchg.
+
+Only writers move the tail page. This must be done atomically to protect
+against nested writers::
+
+ temp_page = tail_page
+ next_page = temp_page->next
+ cmpxchg(tail_page, temp_page, next_page)
+
+The above will update the tail page if it is still pointing to the expected
+page. If this fails, a nested write pushed it forward, the current write
+does not need to push it::
+
+
+ temp page
+ |
+ v
+ tail page
+ |
+ v
+ +---+ +---+ +---+ +---+
+ <---| |--->| |--->| |--->| |--->
+ --->| |<---| |<---| |<---| |<---
+ +---+ +---+ +---+ +---+
+
+Nested write comes in and moves the tail page forward::
+
+ tail page (moved by nested writer)
+ temp page |
+ | |
+ v v
+ +---+ +---+ +---+ +---+
+ <---| |--->| |--->| |--->| |--->
+ --->| |<---| |<---| |<---| |<---
+ +---+ +---+ +---+ +---+
+
+The above would fail the cmpxchg, but since the tail page has already
+been moved forward, the writer will just try again to reserve storage
+on the new tail page.
+
+But the moving of the head page is a bit more complex::
+
+ tail page
+ |
+ v
+ +---+ +---+ +---+ +---+
+ <---| |--->| |-H->| |--->| |--->
+ --->| |<---| |<---| |<---| |<---
+ +---+ +---+ +---+ +---+
+
+The write converts the head page pointer to UPDATE::
+
+ tail page
+ |
+ v
+ +---+ +---+ +---+ +---+
+ <---| |--->| |-U->| |--->| |--->
+ --->| |<---| |<---| |<---| |<---
+ +---+ +---+ +---+ +---+
+
+But if a nested writer preempts here, it will see that the next
+page is a head page, but it is also nested. It will detect that
+it is nested and will save that information. The detection is the
+fact that it sees the UPDATE flag instead of a HEADER or NORMAL
+pointer.
+
+The nested writer will set the new head page pointer::
+
+ tail page
+ |
+ v
+ +---+ +---+ +---+ +---+
+ <---| |--->| |-U->| |-H->| |--->
+ --->| |<---| |<---| |<---| |<---
+ +---+ +---+ +---+ +---+
+
+But it will not reset the update back to normal. Only the writer
+that converted a pointer from HEAD to UPDATE will convert it back
+to NORMAL::
+
+ tail page
+ |
+ v
+ +---+ +---+ +---+ +---+
+ <---| |--->| |-U->| |-H->| |--->
+ --->| |<---| |<---| |<---| |<---
+ +---+ +---+ +---+ +---+
+
+After the nested writer finishes, the outermost writer will convert
+the UPDATE pointer to NORMAL::
+
+
+ tail page
+ |
+ v
+ +---+ +---+ +---+ +---+
+ <---| |--->| |--->| |-H->| |--->
+ --->| |<---| |<---| |<---| |<---
+ +---+ +---+ +---+ +---+
+
+
+It can be even more complex if several nested writes came in and moved
+the tail page ahead several pages::
+
+
+ (first writer)
+
+ tail page
+ |
+ v
+ +---+ +---+ +---+ +---+
+ <---| |--->| |-H->| |--->| |--->
+ --->| |<---| |<---| |<---| |<---
+ +---+ +---+ +---+ +---+
+
+The write converts the head page pointer to UPDATE::
+
+ tail page
+ |
+ v
+ +---+ +---+ +---+ +---+
+ <---| |--->| |-U->| |--->| |--->
+ --->| |<---| |<---| |<---| |<---
+ +---+ +---+ +---+ +---+
+
+Next writer comes in, and sees the update and sets up the new
+head page::
+
+ (second writer)
+
+ tail page
+ |
+ v
+ +---+ +---+ +---+ +---+
+ <---| |--->| |-U->| |-H->| |--->
+ --->| |<---| |<---| |<---| |<---
+ +---+ +---+ +---+ +---+
+
+The nested writer moves the tail page forward. But does not set the old
+update page to NORMAL because it is not the outermost writer::
+
+ tail page
+ |
+ v
+ +---+ +---+ +---+ +---+
+ <---| |--->| |-U->| |-H->| |--->
+ --->| |<---| |<---| |<---| |<---
+ +---+ +---+ +---+ +---+
+
+Another writer preempts and sees the page after the tail page is a head page.
+It changes it from HEAD to UPDATE::
+
+ (third writer)
+
+ tail page
+ |
+ v
+ +---+ +---+ +---+ +---+
+ <---| |--->| |-U->| |-U->| |--->
+ --->| |<---| |<---| |<---| |<---
+ +---+ +---+ +---+ +---+
+
+The writer will move the head page forward::
+
+
+ (third writer)
+
+ tail page
+ |
+ v
+ +---+ +---+ +---+ +---+
+ <---| |--->| |-U->| |-U->| |-H->
+ --->| |<---| |<---| |<---| |<---
+ +---+ +---+ +---+ +---+
+
+But now that the third writer did change the HEAD flag to UPDATE it
+will convert it to normal::
+
+
+ (third writer)
+
+ tail page
+ |
+ v
+ +---+ +---+ +---+ +---+
+ <---| |--->| |-U->| |--->| |-H->
+ --->| |<---| |<---| |<---| |<---
+ +---+ +---+ +---+ +---+
+
+
+Then it will move the tail page, and return back to the second writer::
+
+
+ (second writer)
+
+ tail page
+ |
+ v
+ +---+ +---+ +---+ +---+
+ <---| |--->| |-U->| |--->| |-H->
+ --->| |<---| |<---| |<---| |<---
+ +---+ +---+ +---+ +---+
+
+
+The second writer will fail to move the tail page because it was already
+moved, so it will try again and add its data to the new tail page.
+It will return to the first writer::
+
+
+ (first writer)
+
+ tail page
+ |
+ v
+ +---+ +---+ +---+ +---+
+ <---| |--->| |-U->| |--->| |-H->
+ --->| |<---| |<---| |<---| |<---
+ +---+ +---+ +---+ +---+
+
+The first writer cannot know atomically if the tail page moved
+while it updates the HEAD page. It will then update the head page to
+what it thinks is the new head page::
+
+
+ (first writer)
+
+ tail page
+ |
+ v
+ +---+ +---+ +---+ +---+
+ <---| |--->| |-U->| |-H->| |-H->
+ --->| |<---| |<---| |<---| |<---
+ +---+ +---+ +---+ +---+
+
+Since the cmpxchg returns the old value of the pointer the first writer
+will see it succeeded in updating the pointer from NORMAL to HEAD.
+But as we can see, this is not good enough. It must also check to see
+if the tail page is either where it use to be or on the next page::
+
+
+ (first writer)
+
+ A B tail page
+ | | |
+ v v v
+ +---+ +---+ +---+ +---+
+ <---| |--->| |-U->| |-H->| |-H->
+ --->| |<---| |<---| |<---| |<---
+ +---+ +---+ +---+ +---+
+
+If tail page != A and tail page != B, then it must reset the pointer
+back to NORMAL. The fact that it only needs to worry about nested
+writers means that it only needs to check this after setting the HEAD page::
+
+
+ (first writer)
+
+ A B tail page
+ | | |
+ v v v
+ +---+ +---+ +---+ +---+
+ <---| |--->| |-U->| |--->| |-H->
+ --->| |<---| |<---| |<---| |<---
+ +---+ +---+ +---+ +---+
+
+Now the writer can update the head page. This is also why the head page must
+remain in UPDATE and only reset by the outermost writer. This prevents
+the reader from seeing the incorrect head page::
+
+
+ (first writer)
+
+ A B tail page
+ | | |
+ v v v
+ +---+ +---+ +---+ +---+
+ <---| |--->| |--->| |--->| |-H->
+ --->| |<---| |<---| |<---| |<---
+ +---+ +---+ +---+ +---+
diff --git a/Documentation/trace/ring-buffer-design.txt b/Documentation/trace/ring-buffer-design.txt
deleted file mode 100644
index 2d53c6f..0000000
--- a/Documentation/trace/ring-buffer-design.txt
+++ /dev/null
@@ -1,955 +0,0 @@
- Lockless Ring Buffer Design
- ===========================
-
-Copyright 2009 Red Hat Inc.
- Author: Steven Rostedt <srostedt@redhat.com>
- License: The GNU Free Documentation License, Version 1.2
- (dual licensed under the GPL v2)
-Reviewers: Mathieu Desnoyers, Huang Ying, Hidetoshi Seto,
- and Frederic Weisbecker.
-
-
-Written for: 2.6.31
-
-Terminology used in this Document
----------------------------------
-
-tail - where new writes happen in the ring buffer.
-
-head - where new reads happen in the ring buffer.
-
-producer - the task that writes into the ring buffer (same as writer)
-
-writer - same as producer
-
-consumer - the task that reads from the buffer (same as reader)
-
-reader - same as consumer.
-
-reader_page - A page outside the ring buffer used solely (for the most part)
- by the reader.
-
-head_page - a pointer to the page that the reader will use next
-
-tail_page - a pointer to the page that will be written to next
-
-commit_page - a pointer to the page with the last finished non-nested write.
-
-cmpxchg - hardware-assisted atomic transaction that performs the following:
-
- A = B if previous A == C
-
- R = cmpxchg(A, C, B) is saying that we replace A with B if and only if
- current A is equal to C, and we put the old (current) A into R
-
- R gets the previous A regardless if A is updated with B or not.
-
- To see if the update was successful a compare of R == C may be used.
-
-The Generic Ring Buffer
------------------------
-
-The ring buffer can be used in either an overwrite mode or in
-producer/consumer mode.
-
-Producer/consumer mode is where if the producer were to fill up the
-buffer before the consumer could free up anything, the producer
-will stop writing to the buffer. This will lose most recent events.
-
-Overwrite mode is where if the producer were to fill up the buffer
-before the consumer could free up anything, the producer will
-overwrite the older data. This will lose the oldest events.
-
-No two writers can write at the same time (on the same per-cpu buffer),
-but a writer may interrupt another writer, but it must finish writing
-before the previous writer may continue. This is very important to the
-algorithm. The writers act like a "stack". The way interrupts works
-enforces this behavior.
-
-
- writer1 start
- <preempted> writer2 start
- <preempted> writer3 start
- writer3 finishes
- writer2 finishes
- writer1 finishes
-
-This is very much like a writer being preempted by an interrupt and
-the interrupt doing a write as well.
-
-Readers can happen at any time. But no two readers may run at the
-same time, nor can a reader preempt/interrupt another reader. A reader
-cannot preempt/interrupt a writer, but it may read/consume from the
-buffer at the same time as a writer is writing, but the reader must be
-on another processor to do so. A reader may read on its own processor
-and can be preempted by a writer.
-
-A writer can preempt a reader, but a reader cannot preempt a writer.
-But a reader can read the buffer at the same time (on another processor)
-as a writer.
-
-The ring buffer is made up of a list of pages held together by a linked list.
-
-At initialization a reader page is allocated for the reader that is not
-part of the ring buffer.
-
-The head_page, tail_page and commit_page are all initialized to point
-to the same page.
-
-The reader page is initialized to have its next pointer pointing to
-the head page, and its previous pointer pointing to a page before
-the head page.
-
-The reader has its own page to use. At start up time, this page is
-allocated but is not attached to the list. When the reader wants
-to read from the buffer, if its page is empty (like it is on start-up),
-it will swap its page with the head_page. The old reader page will
-become part of the ring buffer and the head_page will be removed.
-The page after the inserted page (old reader_page) will become the
-new head page.
-
-Once the new page is given to the reader, the reader could do what
-it wants with it, as long as a writer has left that page.
-
-A sample of how the reader page is swapped: Note this does not
-show the head page in the buffer, it is for demonstrating a swap
-only.
-
- +------+
- |reader| RING BUFFER
- |page |
- +------+
- +---+ +---+ +---+
- | |-->| |-->| |
- | |<--| |<--| |
- +---+ +---+ +---+
- ^ | ^ |
- | +-------------+ |
- +-----------------+
-
-
- +------+
- |reader| RING BUFFER
- |page |-------------------+
- +------+ v
- | +---+ +---+ +---+
- | | |-->| |-->| |
- | | |<--| |<--| |<-+
- | +---+ +---+ +---+ |
- | ^ | ^ | |
- | | +-------------+ | |
- | +-----------------+ |
- +------------------------------------+
-
- +------+
- |reader| RING BUFFER
- |page |-------------------+
- +------+ <---------------+ v
- | ^ +---+ +---+ +---+
- | | | |-->| |-->| |
- | | | | | |<--| |<-+
- | | +---+ +---+ +---+ |
- | | | ^ | |
- | | +-------------+ | |
- | +-----------------------------+ |
- +------------------------------------+
-
- +------+
- |buffer| RING BUFFER
- |page |-------------------+
- +------+ <---------------+ v
- | ^ +---+ +---+ +---+
- | | | | | |-->| |
- | | New | | | |<--| |<-+
- | | Reader +---+ +---+ +---+ |
- | | page ----^ | |
- | | | |
- | +-----------------------------+ |
- +------------------------------------+
-
-
-
-It is possible that the page swapped is the commit page and the tail page,
-if what is in the ring buffer is less than what is held in a buffer page.
-
-
- reader page commit page tail page
- | | |
- v | |
- +---+ | |
- | |<----------+ |
- | |<------------------------+
- | |------+
- +---+ |
- |
- v
- +---+ +---+ +---+ +---+
-<---| |--->| |--->| |--->| |--->
---->| |<---| |<---| |<---| |<---
- +---+ +---+ +---+ +---+
-
-This case is still valid for this algorithm.
-When the writer leaves the page, it simply goes into the ring buffer
-since the reader page still points to the next location in the ring
-buffer.
-
-
-The main pointers:
-
- reader page - The page used solely by the reader and is not part
- of the ring buffer (may be swapped in)
-
- head page - the next page in the ring buffer that will be swapped
- with the reader page.
-
- tail page - the page where the next write will take place.
-
- commit page - the page that last finished a write.
-
-The commit page only is updated by the outermost writer in the
-writer stack. A writer that preempts another writer will not move the
-commit page.
-
-When data is written into the ring buffer, a position is reserved
-in the ring buffer and passed back to the writer. When the writer
-is finished writing data into that position, it commits the write.
-
-Another write (or a read) may take place at anytime during this
-transaction. If another write happens it must finish before continuing
-with the previous write.
-
-
- Write reserve:
-
- Buffer page
- +---------+
- |written |
- +---------+ <--- given back to writer (current commit)
- |reserved |
- +---------+ <--- tail pointer
- | empty |
- +---------+
-
- Write commit:
-
- Buffer page
- +---------+
- |written |
- +---------+
- |written |
- +---------+ <--- next position for write (current commit)
- | empty |
- +---------+
-
-
- If a write happens after the first reserve:
-
- Buffer page
- +---------+
- |written |
- +---------+ <-- current commit
- |reserved |
- +---------+ <--- given back to second writer
- |reserved |
- +---------+ <--- tail pointer
-
- After second writer commits:
-
-
- Buffer page
- +---------+
- |written |
- +---------+ <--(last full commit)
- |reserved |
- +---------+
- |pending |
- |commit |
- +---------+ <--- tail pointer
-
- When the first writer commits:
-
- Buffer page
- +---------+
- |written |
- +---------+
- |written |
- +---------+
- |written |
- +---------+ <--(last full commit and tail pointer)
-
-
-The commit pointer points to the last write location that was
-committed without preempting another write. When a write that
-preempted another write is committed, it only becomes a pending commit
-and will not be a full commit until all writes have been committed.
-
-The commit page points to the page that has the last full commit.
-The tail page points to the page with the last write (before
-committing).
-
-The tail page is always equal to or after the commit page. It may
-be several pages ahead. If the tail page catches up to the commit
-page then no more writes may take place (regardless of the mode
-of the ring buffer: overwrite and produce/consumer).
-
-The order of pages is:
-
- head page
- commit page
- tail page
-
-Possible scenario:
- tail page
- head page commit page |
- | | |
- v v v
- +---+ +---+ +---+ +---+
-<---| |--->| |--->| |--->| |--->
---->| |<---| |<---| |<---| |<---
- +---+ +---+ +---+ +---+
-
-There is a special case that the head page is after either the commit page
-and possibly the tail page. That is when the commit (and tail) page has been
-swapped with the reader page. This is because the head page is always
-part of the ring buffer, but the reader page is not. Whenever there
-has been less than a full page that has been committed inside the ring buffer,
-and a reader swaps out a page, it will be swapping out the commit page.
-
-
- reader page commit page tail page
- | | |
- v | |
- +---+ | |
- | |<----------+ |
- | |<------------------------+
- | |------+
- +---+ |
- |
- v
- +---+ +---+ +---+ +---+
-<---| |--->| |--->| |--->| |--->
---->| |<---| |<---| |<---| |<---
- +---+ +---+ +---+ +---+
- ^
- |
- head page
-
-
-In this case, the head page will not move when the tail and commit
-move back into the ring buffer.
-
-The reader cannot swap a page into the ring buffer if the commit page
-is still on that page. If the read meets the last commit (real commit
-not pending or reserved), then there is nothing more to read.
-The buffer is considered empty until another full commit finishes.
-
-When the tail meets the head page, if the buffer is in overwrite mode,
-the head page will be pushed ahead one. If the buffer is in producer/consumer
-mode, the write will fail.
-
-Overwrite mode:
-
- tail page
- |
- v
- +---+ +---+ +---+ +---+
-<---| |--->| |--->| |--->| |--->
---->| |<---| |<---| |<---| |<---
- +---+ +---+ +---+ +---+
- ^
- |
- head page
-
-
- tail page
- |
- v
- +---+ +---+ +---+ +---+
-<---| |--->| |--->| |--->| |--->
---->| |<---| |<---| |<---| |<---
- +---+ +---+ +---+ +---+
- ^
- |
- head page
-
-
- tail page
- |
- v
- +---+ +---+ +---+ +---+
-<---| |--->| |--->| |--->| |--->
---->| |<---| |<---| |<---| |<---
- +---+ +---+ +---+ +---+
- ^
- |
- head page
-
-Note, the reader page will still point to the previous head page.
-But when a swap takes place, it will use the most recent head page.
-
-
-Making the Ring Buffer Lockless:
---------------------------------
-
-The main idea behind the lockless algorithm is to combine the moving
-of the head_page pointer with the swapping of pages with the reader.
-State flags are placed inside the pointer to the page. To do this,
-each page must be aligned in memory by 4 bytes. This will allow the 2
-least significant bits of the address to be used as flags, since
-they will always be zero for the address. To get the address,
-simply mask out the flags.
-
- MASK = ~3
-
- address & MASK
-
-Two flags will be kept by these two bits:
-
- HEADER - the page being pointed to is a head page
-
- UPDATE - the page being pointed to is being updated by a writer
- and was or is about to be a head page.
-
-
- reader page
- |
- v
- +---+
- | |------+
- +---+ |
- |
- v
- +---+ +---+ +---+ +---+
-<---| |--->| |-H->| |--->| |--->
---->| |<---| |<---| |<---| |<---
- +---+ +---+ +---+ +---+
-
-
-The above pointer "-H->" would have the HEADER flag set. That is
-the next page is the next page to be swapped out by the reader.
-This pointer means the next page is the head page.
-
-When the tail page meets the head pointer, it will use cmpxchg to
-change the pointer to the UPDATE state:
-
-
- tail page
- |
- v
- +---+ +---+ +---+ +---+
-<---| |--->| |-H->| |--->| |--->
---->| |<---| |<---| |<---| |<---
- +---+ +---+ +---+ +---+
-
- tail page
- |
- v
- +---+ +---+ +---+ +---+
-<---| |--->| |-U->| |--->| |--->
---->| |<---| |<---| |<---| |<---
- +---+ +---+ +---+ +---+
-
-"-U->" represents a pointer in the UPDATE state.
-
-Any access to the reader will need to take some sort of lock to serialize
-the readers. But the writers will never take a lock to write to the
-ring buffer. This means we only need to worry about a single reader,
-and writes only preempt in "stack" formation.
-
-When the reader tries to swap the page with the ring buffer, it
-will also use cmpxchg. If the flag bit in the pointer to the
-head page does not have the HEADER flag set, the compare will fail
-and the reader will need to look for the new head page and try again.
-Note, the flags UPDATE and HEADER are never set at the same time.
-
-The reader swaps the reader page as follows:
-
- +------+
- |reader| RING BUFFER
- |page |
- +------+
- +---+ +---+ +---+
- | |--->| |--->| |
- | |<---| |<---| |
- +---+ +---+ +---+
- ^ | ^ |
- | +---------------+ |
- +-----H-------------+
-
-The reader sets the reader page next pointer as HEADER to the page after
-the head page.
-
-
- +------+
- |reader| RING BUFFER
- |page |-------H-----------+
- +------+ v
- | +---+ +---+ +---+
- | | |--->| |--->| |
- | | |<---| |<---| |<-+
- | +---+ +---+ +---+ |
- | ^ | ^ | |
- | | +---------------+ | |
- | +-----H-------------+ |
- +--------------------------------------+
-
-It does a cmpxchg with the pointer to the previous head page to make it
-point to the reader page. Note that the new pointer does not have the HEADER
-flag set. This action atomically moves the head page forward.
-
- +------+
- |reader| RING BUFFER
- |page |-------H-----------+
- +------+ v
- | ^ +---+ +---+ +---+
- | | | |-->| |-->| |
- | | | |<--| |<--| |<-+
- | | +---+ +---+ +---+ |
- | | | ^ | |
- | | +-------------+ | |
- | +-----------------------------+ |
- +------------------------------------+
-
-After the new head page is set, the previous pointer of the head page is
-updated to the reader page.
-
- +------+
- |reader| RING BUFFER
- |page |-------H-----------+
- +------+ <---------------+ v
- | ^ +---+ +---+ +---+
- | | | |-->| |-->| |
- | | | | | |<--| |<-+
- | | +---+ +---+ +---+ |
- | | | ^ | |
- | | +-------------+ | |
- | +-----------------------------+ |
- +------------------------------------+
-
- +------+
- |buffer| RING BUFFER
- |page |-------H-----------+ <--- New head page
- +------+ <---------------+ v
- | ^ +---+ +---+ +---+
- | | | | | |-->| |
- | | New | | | |<--| |<-+
- | | Reader +---+ +---+ +---+ |
- | | page ----^ | |
- | | | |
- | +-----------------------------+ |
- +------------------------------------+
-
-Another important point: The page that the reader page points back to
-by its previous pointer (the one that now points to the new head page)
-never points back to the reader page. That is because the reader page is
-not part of the ring buffer. Traversing the ring buffer via the next pointers
-will always stay in the ring buffer. Traversing the ring buffer via the
-prev pointers may not.
-
-Note, the way to determine a reader page is simply by examining the previous
-pointer of the page. If the next pointer of the previous page does not
-point back to the original page, then the original page is a reader page:
-
-
- +--------+
- | reader | next +----+
- | page |-------->| |<====== (buffer page)
- +--------+ +----+
- | | ^
- | v | next
- prev | +----+
- +------------->| |
- +----+
-
-The way the head page moves forward:
-
-When the tail page meets the head page and the buffer is in overwrite mode
-and more writes take place, the head page must be moved forward before the
-writer may move the tail page. The way this is done is that the writer
-performs a cmpxchg to convert the pointer to the head page from the HEADER
-flag to have the UPDATE flag set. Once this is done, the reader will
-not be able to swap the head page from the buffer, nor will it be able to
-move the head page, until the writer is finished with the move.
-
-This eliminates any races that the reader can have on the writer. The reader
-must spin, and this is why the reader cannot preempt the writer.
-
- tail page
- |
- v
- +---+ +---+ +---+ +---+
-<---| |--->| |-H->| |--->| |--->
---->| |<---| |<---| |<---| |<---
- +---+ +---+ +---+ +---+
-
- tail page
- |
- v
- +---+ +---+ +---+ +---+
-<---| |--->| |-U->| |--->| |--->
---->| |<---| |<---| |<---| |<---
- +---+ +---+ +---+ +---+
-
-The following page will be made into the new head page.
-
- tail page
- |
- v
- +---+ +---+ +---+ +---+
-<---| |--->| |-U->| |-H->| |--->
---->| |<---| |<---| |<---| |<---
- +---+ +---+ +---+ +---+
-
-After the new head page has been set, we can set the old head page
-pointer back to NORMAL.
-
- tail page
- |
- v
- +---+ +---+ +---+ +---+
-<---| |--->| |--->| |-H->| |--->
---->| |<---| |<---| |<---| |<---
- +---+ +---+ +---+ +---+
-
-After the head page has been moved, the tail page may now move forward.
-
- tail page
- |
- v
- +---+ +---+ +---+ +---+
-<---| |--->| |--->| |-H->| |--->
---->| |<---| |<---| |<---| |<---
- +---+ +---+ +---+ +---+
-
-
-The above are the trivial updates. Now for the more complex scenarios.
-
-
-As stated before, if enough writes preempt the first write, the
-tail page may make it all the way around the buffer and meet the commit
-page. At this time, we must start dropping writes (usually with some kind
-of warning to the user). But what happens if the commit was still on the
-reader page? The commit page is not part of the ring buffer. The tail page
-must account for this.
-
-
- reader page commit page
- | |
- v |
- +---+ |
- | |<----------+
- | |
- | |------+
- +---+ |
- |
- v
- +---+ +---+ +---+ +---+
-<---| |--->| |-H->| |--->| |--->
---->| |<---| |<---| |<---| |<---
- +---+ +---+ +---+ +---+
- ^
- |
- tail page
-
-If the tail page were to simply push the head page forward, the commit when
-leaving the reader page would not be pointing to the correct page.
-
-The solution to this is to test if the commit page is on the reader page
-before pushing the head page. If it is, then it can be assumed that the
-tail page wrapped the buffer, and we must drop new writes.
-
-This is not a race condition, because the commit page can only be moved
-by the outermost writer (the writer that was preempted).
-This means that the commit will not move while a writer is moving the
-tail page. The reader cannot swap the reader page if it is also being
-used as the commit page. The reader can simply check that the commit
-is off the reader page. Once the commit page leaves the reader page
-it will never go back on it unless a reader does another swap with the
-buffer page that is also the commit page.
-
-
-Nested writes
--------------
-
-In the pushing forward of the tail page we must first push forward
-the head page if the head page is the next page. If the head page
-is not the next page, the tail page is simply updated with a cmpxchg.
-
-Only writers move the tail page. This must be done atomically to protect
-against nested writers.
-
- temp_page = tail_page
- next_page = temp_page->next
- cmpxchg(tail_page, temp_page, next_page)
-
-The above will update the tail page if it is still pointing to the expected
-page. If this fails, a nested write pushed it forward, the current write
-does not need to push it.
-
-
- temp page
- |
- v
- tail page
- |
- v
- +---+ +---+ +---+ +---+
-<---| |--->| |--->| |--->| |--->
---->| |<---| |<---| |<---| |<---
- +---+ +---+ +---+ +---+
-
-Nested write comes in and moves the tail page forward:
-
- tail page (moved by nested writer)
- temp page |
- | |
- v v
- +---+ +---+ +---+ +---+
-<---| |--->| |--->| |--->| |--->
---->| |<---| |<---| |<---| |<---
- +---+ +---+ +---+ +---+
-
-The above would fail the cmpxchg, but since the tail page has already
-been moved forward, the writer will just try again to reserve storage
-on the new tail page.
-
-But the moving of the head page is a bit more complex.
-
- tail page
- |
- v
- +---+ +---+ +---+ +---+
-<---| |--->| |-H->| |--->| |--->
---->| |<---| |<---| |<---| |<---
- +---+ +---+ +---+ +---+
-
-The write converts the head page pointer to UPDATE.
-
- tail page
- |
- v
- +---+ +---+ +---+ +---+
-<---| |--->| |-U->| |--->| |--->
---->| |<---| |<---| |<---| |<---
- +---+ +---+ +---+ +---+
-
-But if a nested writer preempts here, it will see that the next
-page is a head page, but it is also nested. It will detect that
-it is nested and will save that information. The detection is the
-fact that it sees the UPDATE flag instead of a HEADER or NORMAL
-pointer.
-
-The nested writer will set the new head page pointer.
-
- tail page
- |
- v
- +---+ +---+ +---+ +---+
-<---| |--->| |-U->| |-H->| |--->
---->| |<---| |<---| |<---| |<---
- +---+ +---+ +---+ +---+
-
-But it will not reset the update back to normal. Only the writer
-that converted a pointer from HEAD to UPDATE will convert it back
-to NORMAL.
-
- tail page
- |
- v
- +---+ +---+ +---+ +---+
-<---| |--->| |-U->| |-H->| |--->
---->| |<---| |<---| |<---| |<---
- +---+ +---+ +---+ +---+
-
-After the nested writer finishes, the outermost writer will convert
-the UPDATE pointer to NORMAL.
-
-
- tail page
- |
- v
- +---+ +---+ +---+ +---+
-<---| |--->| |--->| |-H->| |--->
---->| |<---| |<---| |<---| |<---
- +---+ +---+ +---+ +---+
-
-
-It can be even more complex if several nested writes came in and moved
-the tail page ahead several pages:
-
-
-(first writer)
-
- tail page
- |
- v
- +---+ +---+ +---+ +---+
-<---| |--->| |-H->| |--->| |--->
---->| |<---| |<---| |<---| |<---
- +---+ +---+ +---+ +---+
-
-The write converts the head page pointer to UPDATE.
-
- tail page
- |
- v
- +---+ +---+ +---+ +---+
-<---| |--->| |-U->| |--->| |--->
---->| |<---| |<---| |<---| |<---
- +---+ +---+ +---+ +---+
-
-Next writer comes in, and sees the update and sets up the new
-head page.
-
-(second writer)
-
- tail page
- |
- v
- +---+ +---+ +---+ +---+
-<---| |--->| |-U->| |-H->| |--->
---->| |<---| |<---| |<---| |<---
- +---+ +---+ +---+ +---+
-
-The nested writer moves the tail page forward. But does not set the old
-update page to NORMAL because it is not the outermost writer.
-
- tail page
- |
- v
- +---+ +---+ +---+ +---+
-<---| |--->| |-U->| |-H->| |--->
---->| |<---| |<---| |<---| |<---
- +---+ +---+ +---+ +---+
-
-Another writer preempts and sees the page after the tail page is a head page.
-It changes it from HEAD to UPDATE.
-
-(third writer)
-
- tail page
- |
- v
- +---+ +---+ +---+ +---+
-<---| |--->| |-U->| |-U->| |--->
---->| |<---| |<---| |<---| |<---
- +---+ +---+ +---+ +---+
-
-The writer will move the head page forward:
-
-
-(third writer)
-
- tail page
- |
- v
- +---+ +---+ +---+ +---+
-<---| |--->| |-U->| |-U->| |-H->
---->| |<---| |<---| |<---| |<---
- +---+ +---+ +---+ +---+
-
-But now that the third writer did change the HEAD flag to UPDATE it
-will convert it to normal:
-
-
-(third writer)
-
- tail page
- |
- v
- +---+ +---+ +---+ +---+
-<---| |--->| |-U->| |--->| |-H->
---->| |<---| |<---| |<---| |<---
- +---+ +---+ +---+ +---+
-
-
-Then it will move the tail page, and return back to the second writer.
-
-
-(second writer)
-
- tail page
- |
- v
- +---+ +---+ +---+ +---+
-<---| |--->| |-U->| |--->| |-H->
---->| |<---| |<---| |<---| |<---
- +---+ +---+ +---+ +---+
-
-
-The second writer will fail to move the tail page because it was already
-moved, so it will try again and add its data to the new tail page.
-It will return to the first writer.
-
-
-(first writer)
-
- tail page
- |
- v
- +---+ +---+ +---+ +---+
-<---| |--->| |-U->| |--->| |-H->
---->| |<---| |<---| |<---| |<---
- +---+ +---+ +---+ +---+
-
-The first writer cannot know atomically if the tail page moved
-while it updates the HEAD page. It will then update the head page to
-what it thinks is the new head page.
-
-
-(first writer)
-
- tail page
- |
- v
- +---+ +---+ +---+ +---+
-<---| |--->| |-U->| |-H->| |-H->
---->| |<---| |<---| |<---| |<---
- +---+ +---+ +---+ +---+
-
-Since the cmpxchg returns the old value of the pointer the first writer
-will see it succeeded in updating the pointer from NORMAL to HEAD.
-But as we can see, this is not good enough. It must also check to see
-if the tail page is either where it use to be or on the next page:
-
-
-(first writer)
-
- A B tail page
- | | |
- v v v
- +---+ +---+ +---+ +---+
-<---| |--->| |-U->| |-H->| |-H->
---->| |<---| |<---| |<---| |<---
- +---+ +---+ +---+ +---+
-
-If tail page != A and tail page != B, then it must reset the pointer
-back to NORMAL. The fact that it only needs to worry about nested
-writers means that it only needs to check this after setting the HEAD page.
-
-
-(first writer)
-
- A B tail page
- | | |
- v v v
- +---+ +---+ +---+ +---+
-<---| |--->| |-U->| |--->| |-H->
---->| |<---| |<---| |<---| |<---
- +---+ +---+ +---+ +---+
-
-Now the writer can update the head page. This is also why the head page must
-remain in UPDATE and only reset by the outermost writer. This prevents
-the reader from seeing the incorrect head page.
-
-
-(first writer)
-
- A B tail page
- | | |
- v v v
- +---+ +---+ +---+ +---+
-<---| |--->| |--->| |--->| |-H->
---->| |<---| |<---| |<---| |<---
- +---+ +---+ +---+ +---+
-
diff --git a/Documentation/trace/stm.rst b/Documentation/trace/stm.rst
index 99f9996..1ed49dd 100644
--- a/Documentation/trace/stm.rst
+++ b/Documentation/trace/stm.rst
@@ -33,8 +33,8 @@
have a name (string identifier) and a range of masters and channels
associated with it, located in "stp-policy" subsystem directory in
configfs. The topmost directory's name (the policy) is formatted as
-the STM device name to which this policy applies and and arbitrary
-string identifier separated by a stop. From the examle above, a rule
+the STM device name to which this policy applies and an arbitrary
+string identifier separated by a stop. From the example above, a rule
may look like this::
$ ls /config/stp-policy/dummy_stm.my-policy/user
diff --git a/Documentation/translations/it_IT/core-api/index.rst b/Documentation/translations/it_IT/core-api/index.rst
new file mode 100644
index 0000000..cc4c432
--- /dev/null
+++ b/Documentation/translations/it_IT/core-api/index.rst
@@ -0,0 +1,18 @@
+===============================
+Documentazione dell'API di base
+===============================
+
+Utilità di base
+===============
+
+.. toctree::
+ :maxdepth: 1
+
+ symbol-namespaces
+
+.. only:: subproject and html
+
+ Indices
+ =======
+
+ * :ref:`genindex`
diff --git a/Documentation/translations/it_IT/core-api/symbol-namespaces.rst b/Documentation/translations/it_IT/core-api/symbol-namespaces.rst
new file mode 100644
index 0000000..aa851a5
--- /dev/null
+++ b/Documentation/translations/it_IT/core-api/symbol-namespaces.rst
@@ -0,0 +1,166 @@
+.. include:: ../disclaimer-ita.rst
+
+:Original: :doc:`../../../core-api/symbol-namespaces`
+:Translator: Federico Vaga <federico.vaga@vaga.pv.it>
+
+===========================
+Spazio dei nomi dei simboli
+===========================
+
+Questo documento descrive come usare lo spazio dei nomi dei simboli
+per strutturare quello che viene esportato internamente al kernel
+grazie alle macro della famiglia EXPORT_SYMBOL().
+
+1. Introduzione
+===============
+
+Lo spazio dei nomi dei simboli è stato introdotto come mezzo per strutturare
+l'API esposta internamente al kernel. Permette ai manutentori di un
+sottosistema di organizzare i simboli esportati in diversi spazi di
+nomi. Questo meccanismo è utile per la documentazione (pensate ad
+esempio allo spazio dei nomi SUBSYSTEM_DEBUG) così come per limitare
+la disponibilità di un gruppo di simboli in altre parti del kernel. Ad
+oggi, i moduli che usano simboli esportati da uno spazio di nomi
+devono prima importare detto spazio. Altrimenti il kernel, a seconda
+della configurazione, potrebbe rifiutare di caricare il modulo o
+avvisare l'utente di un'importazione mancante.
+
+2. Come definire uno spazio dei nomi dei simboli
+================================================
+
+I simboli possono essere esportati in spazi dei nomi usando diversi
+meccanismi. Tutti questi meccanismi cambiano il modo in cui
+EXPORT_SYMBOL e simili vengono guidati verso la creazione di voci in ksymtab.
+
+2.1 Usare le macro EXPORT_SYMBOL
+================================
+
+In aggiunta alle macro EXPORT_SYMBOL() e EXPORT_SYMBOL_GPL(), che permettono
+di esportare simboli del kernel nella rispettiva tabella, ci sono
+varianti che permettono di esportare simboli all'interno di uno spazio dei
+nomi: EXPORT_SYMBOL_NS() ed EXPORT_SYMBOL_NS_GPL(). Queste macro richiedono un
+argomento aggiuntivo: lo spazio dei nomi.
+Tenete presente che per via dell'espansione delle macro questo argomento deve
+essere un simbolo di preprocessore. Per esempio per esportare il
+simbolo `usb_stor_suspend` nello spazio dei nomi `USB_STORAGE` usate::
+
+ EXPORT_SYMBOL_NS(usb_stor_suspend, USB_STORAGE);
+
+Di conseguenza, nella tabella dei simboli del kernel ci sarà una voce
+rappresentata dalla struttura `kernel_symbol` che avrà il campo
+`namespace` (spazio dei nomi) impostato. Un simbolo esportato senza uno spazio
+dei nomi avrà questo campo impostato a `NULL`. Non esiste uno spazio dei nomi
+di base. Il programma `modpost` e il codice in kernel/module.c usano lo spazio
+dei nomi, rispettivamente, durante la compilazione e durante il caricamento
+di un modulo.
+
+2.2 Usare il simbolo di preprocessore DEFAULT_SYMBOL_NAMESPACE
+==============================================================
+
+Definire lo spazio dei nomi per tutti i simboli di un sottosistema può essere
+logorante e di difficile manutenzione. Perciò è stato fornito un simbolo
+di preprocessore di base (DEFAULT_SYMBOL_NAMESPACE), che, se impostato,
+diventa lo spazio dei simboli di base per tutti gli usi di EXPORT_SYMBOL()
+ed EXPORT_SYMBOL_GPL() che non specificano esplicitamente uno spazio dei nomi.
+
+Ci sono molti modi per specificare questo simbolo di preprocessore e il loro
+uso dipende dalle preferenze del manutentore di un sottosistema. La prima
+possibilità è quella di definire il simbolo nel `Makefile` del sottosistema.
+Per esempio per esportare tutti i simboli definiti in usb-common nello spazio
+dei nomi USB_COMMON, si può aggiungere la seguente linea in
+drivers/usb/common/Makefile::
+
+ ccflags-y += -DDEFAULT_SYMBOL_NAMESPACE=USB_COMMON
+
+Questo cambierà tutte le macro EXPORT_SYMBOL() ed EXPORT_SYMBOL_GPL(). Invece,
+un simbolo esportato con EXPORT_SYMBOL_NS() non verrà cambiato e il simbolo
+verrà esportato nello spazio dei nomi indicato.
+
+Una seconda possibilità è quella di definire il simbolo di preprocessore
+direttamente nei file da compilare. L'esempio precedente diventerebbe::
+
+ #undef DEFAULT_SYMBOL_NAMESPACE
+ #define DEFAULT_SYMBOL_NAMESPACE USB_COMMON
+
+Questo va messo prima di un qualsiasi uso di EXPORT_SYMBOL.
+
+3. Come usare i simboli esportati attraverso uno spazio dei nomi
+================================================================
+
+Per usare i simboli esportati da uno spazio dei nomi, i moduli del
+kernel devono esplicitamente importare il relativo spazio dei nomi; altrimenti
+il kernel potrebbe rifiutarsi di caricare il modulo. Il codice del
+modulo deve usare la macro MODULE_IMPORT_NS per importare lo spazio
+dei nomi che contiene i simboli desiderati. Per esempio un modulo che
+usa il simbolo usb_stor_suspend deve importare lo spazio dei nomi
+USB_STORAGE usando la seguente dichiarazione::
+
+ MODULE_IMPORT_NS(USB_STORAGE);
+
+Questo creerà un'etichetta `modinfo` per ogni spazio dei nomi
+importato. Un risvolto di questo fatto è che gli spazi dei
+nomi importati da un modulo possono essere ispezionati tramite
+modinfo::
+
+ $ modinfo drivers/usb/storage/ums-karma.ko
+ [...]
+ import_ns: USB_STORAGE
+ [...]
+
+
+Si consiglia di posizionare la dichiarazione MODULE_IMPORT_NS() vicino
+ai metadati del modulo come MODULE_AUTHOR() o MODULE_LICENSE(). Fate
+riferimento alla sezione 5. per creare automaticamente le importazioni
+mancanti.
+
+4. Caricare moduli che usano simboli provenienti da spazi dei nomi
+==================================================================
+
+Quando un modulo viene caricato (per esempio usando `insmod`), il kernel
+verificherà la disponibilità di ogni simbolo usato e se lo spazio dei nomi
+che potrebbe contenerli è stato importato. Il comportamento di base del kernel
+è di rifiutarsi di caricare quei moduli che non importano tutti gli spazi dei
+nomi necessari. L'errore verrà annotato e il caricamento fallirà con l'errore
+EINVAL. Per caricare i moduli che non soddisfano questo requisito esiste
+un'opzione di configurazione: impostare
+MODULE_ALLOW_MISSING_NAMESPACE_IMPORTS=y caricherà i moduli comunque ma
+emetterà un avviso.
+
+5. Creare automaticamente la dichiarazione MODULE_IMPORT_NS
+===========================================================
+
+La mancanza di un'importazione può essere individuata facilmente al momento
+della compilazione. Infatti, modpost emetterà un avviso se il modulo usa
+un simbolo da uno spazio dei nomi che non è stato importato.
+La dichiarazione MODULE_IMPORT_NS() viene solitamente aggiunta in un posto
+ben definito (assieme agli altri metadati del modulo). Per facilitare
+la vita di chi scrive moduli (e i manutentori di sottosistemi), esistono uno
+script e un target make per correggere le importazioni mancanti. Questo può
+essere fatto con::
+
+ $ make nsdeps
+
+Lo scenario tipico di chi scrive un modulo potrebbe essere::
+
+ - scrivere codice che dipende da un simbolo appartenente ad uno spazio
+ dei nomi non importato
+ - eseguire `make`
+ - aver notato un avviso da modpost che parla di un'importazione
+ mancante
+ - eseguire `make nsdeps` per aggiungere import nel posto giusto
+
+Per i manutentori di sottosistemi che vogliono aggiungere uno spazio dei nomi,
+l'approccio è simile. Di nuovo, eseguendo `make nsdeps` aggiungerà le
+importazioni mancanti nei moduli inclusi nel kernel::
+
+ - spostare o aggiungere simboli ad uno spazio dei nomi (per esempio
+ usando EXPORT_SYMBOL_NS())
+ - eseguire `make` (preferibilmente con allmodconfig per coprire tutti
+ i moduli del kernel)
+ - aver notato un avviso da modpost che parla di un'importazione
+ mancante
+ - eseguire `make nsdeps` per aggiungere import nel posto giusto
+
+Potete anche eseguire nsdeps per moduli esterni. Solitamente si usa così::
+
+ $ make -C <path_to_kernel_src> M=$PWD nsdeps
diff --git a/Documentation/translations/it_IT/index.rst b/Documentation/translations/it_IT/index.rst
index 409eaac..bb8fa73 100644
--- a/Documentation/translations/it_IT/index.rst
+++ b/Documentation/translations/it_IT/index.rst
@@ -121,9 +121,10 @@
(o almeno ci proviamo — probabilmente *non* tutto quello che è davvero
necessario).
-.. warning::
+.. toctree::
+ :maxdepth: 2
- TODO ancora da tradurre
+ core-api/index
Documentazione specifica per architettura
-----------------------------------------
diff --git a/Documentation/translations/it_IT/kernel-hacking/hacking.rst b/Documentation/translations/it_IT/kernel-hacking/hacking.rst
index e9a2e92..6aab27a 100644
--- a/Documentation/translations/it_IT/kernel-hacking/hacking.rst
+++ b/Documentation/translations/it_IT/kernel-hacking/hacking.rst
@@ -634,7 +634,7 @@
Questa è una variate di `EXPORT_SYMBOL()` che permette di specificare uno
spazio dei nomi. Lo spazio dei nomi è documentato in
-:doc:`../../../core-api/symbol-namespaces`
+:doc:`../core-api/symbol-namespaces`
:c:func:`EXPORT_SYMBOL_NS_GPL()`
--------------------------------
@@ -643,7 +643,7 @@
Questa è una variate di `EXPORT_SYMBOL_GPL()` che permette di specificare uno
spazio dei nomi. Lo spazio dei nomi è documentato in
-:doc:`../../../core-api/symbol-namespaces`
+:doc:`../core-api/symbol-namespaces`
Procedure e convenzioni
=======================
diff --git a/Documentation/translations/it_IT/process/coding-style.rst b/Documentation/translations/it_IT/process/coding-style.rst
index 6f4f858..a346f1f 100644
--- a/Documentation/translations/it_IT/process/coding-style.rst
+++ b/Documentation/translations/it_IT/process/coding-style.rst
@@ -1097,7 +1097,7 @@
Se avete una variabile o funzione che potrebbe non essere usata in alcune
configurazioni, e quindi il compilatore potrebbe avvisarvi circa la definizione
-inutilizzata, marcate questa definizione come __maybe_used piuttosto che
+inutilizzata, marcate questa definizione come __maybe_unused piuttosto che
racchiuderla in una direttiva condizionale del preprocessore. (Comunque,
se una variabile o funzione è *sempre* inutilizzata, rimuovetela).
diff --git a/Documentation/translations/ko_KR/memory-barriers.txt b/Documentation/translations/ko_KR/memory-barriers.txt
index 34d041d..9dcc7c9 100644
--- a/Documentation/translations/ko_KR/memory-barriers.txt
+++ b/Documentation/translations/ko_KR/memory-barriers.txt
@@ -570,14 +570,14 @@
[*] 버스 마스터링 DMA 와 일관성에 대해서는 다음을 참고하시기 바랍니다:
Documentation/driver-api/pci/pci.rst
- Documentation/DMA-API-HOWTO.txt
- Documentation/DMA-API.txt
+ Documentation/core-api/dma-api-howto.rst
+ Documentation/core-api/dma-api.rst
데이터 의존성 배리어 (역사적)
-----------------------------
-리눅스 커널 v4.15 기준으로, smp_read_barrier_depends() 가 READ_ONCE() 에
+리눅스 커널 v4.15 기준으로, smp_mb() 가 DEC Alpha 용 READ_ONCE() 코드에
추가되었는데, 이는 이 섹션에 주의를 기울여야 하는 사람들은 DEC Alpha 아키텍쳐
전용 코드를 만드는 사람들과 READ_ONCE() 자체를 만드는 사람들 뿐임을 의미합니다.
그런 분들을 위해, 그리고 역사에 관심 있는 분들을 위해, 여기 데이터 의존성
@@ -1907,7 +1907,7 @@
writel_relaxed() 와 같은 완화된 I/O 접근자들에 대한 자세한 내용을 위해서는
"커널 I/O 배리어의 효과" 섹션을, consistent memory 에 대한 자세한 내용을
- 위해선 Documentation/DMA-API.txt 문서를 참고하세요.
+ 위해선 Documentation/core-api/dma-api.rst 문서를 참고하세요.
=========================
@@ -2664,144 +2664,6 @@
수도 있습니다.
-캐시 일관성
------------
-
-하지만 삶은 앞에서 이야기한 것처럼 단순하지 않습니다: 캐시들은 일관적일 것으로
-기대되지만, 그 일관성이 순서에도 적용될 거라는 보장은 없습니다. 한 CPU 에서
-만들어진 변경 사항은 최종적으로는 시스템의 모든 CPU 에게 보여지게 되지만, 다른
-CPU 들에게도 같은 순서로 보이게 될 거라는 보장은 없다는 뜻입니다.
-
-
-두개의 CPU (1 & 2) 가 달려 있고, 각 CPU 에 두개의 데이터 캐시(CPU 1 은 A/B 를,
-CPU 2 는 C/D 를 갖습니다)가 병렬로 연결되어 있는 시스템을 다룬다고 생각해
-봅시다:
-
- :
- : +--------+
- : +---------+ | |
- +--------+ : +--->| Cache A |<------->| |
- | | : | +---------+ | |
- | CPU 1 |<---+ | |
- | | : | +---------+ | |
- +--------+ : +--->| Cache B |<------->| |
- : +---------+ | |
- : | Memory |
- : +---------+ | System |
- +--------+ : +--->| Cache C |<------->| |
- | | : | +---------+ | |
- | CPU 2 |<---+ | |
- | | : | +---------+ | |
- +--------+ : +--->| Cache D |<------->| |
- : +---------+ | |
- : +--------+
- :
-
-이 시스템이 다음과 같은 특성을 갖는다 생각해 봅시다:
-
- (*) 홀수번 캐시라인은 캐시 A, 캐시 C 또는 메모리에 위치할 수 있음;
-
- (*) 짝수번 캐시라인은 캐시 B, 캐시 D 또는 메모리에 위치할 수 있음;
-
- (*) CPU 코어가 한개의 캐시에 접근하는 동안, 다른 캐시는 - 더티 캐시라인을
- 메모리에 내리거나 추측성 로드를 하거나 하기 위해 - 시스템의 다른 부분에
- 액세스 하기 위해 버스를 사용할 수 있음;
-
- (*) 각 캐시는 시스템의 나머지 부분들과 일관성을 맞추기 위해 해당 캐시에
- 적용되어야 할 오퍼레이션들의 큐를 가짐;
-
- (*) 이 일관성 큐는 캐시에 이미 존재하는 라인에 가해지는 평범한 로드에 의해서는
- 비워지지 않는데, 큐의 오퍼레이션들이 이 로드의 결과에 영향을 끼칠 수 있다
- 할지라도 그러함.
-
-이제, 첫번째 CPU 에서 두개의 쓰기 오퍼레이션을 만드는데, 해당 CPU 의 캐시에
-요청된 순서로 오퍼레이션이 도달됨을 보장하기 위해 두 오퍼레이션 사이에 쓰기
-배리어를 사용하는 상황을 상상해 봅시다:
-
- CPU 1 CPU 2 COMMENT
- =============== =============== =======================================
- u == 0, v == 1 and p == &u, q == &u
- v = 2;
- smp_wmb(); v 의 변경이 p 의 변경 전에 보일 것을
- 분명히 함
- <A:modify v=2> v 는 이제 캐시 A 에 독점적으로 존재함
- p = &v;
- <B:modify p=&v> p 는 이제 캐시 B 에 독점적으로 존재함
-
-여기서의 쓰기 메모리 배리어는 CPU 1 의 캐시가 올바른 순서로 업데이트 된 것으로
-시스템의 다른 CPU 들이 인지하게 만듭니다. 하지만, 이제 두번째 CPU 가 그 값들을
-읽으려 하는 상황을 생각해 봅시다:
-
- CPU 1 CPU 2 COMMENT
- =============== =============== =======================================
- ...
- q = p;
- x = *q;
-
-위의 두개의 읽기 오퍼레이션은 예상된 순서로 일어나지 못할 수 있는데, 두번째 CPU
-의 한 캐시에 다른 캐시 이벤트가 발생해 v 를 담고 있는 캐시라인의 해당 캐시에의
-업데이트가 지연되는 사이, p 를 담고 있는 캐시라인은 두번째 CPU 의 다른 캐시에
-업데이트 되어버렸을 수 있기 때문입니다.
-
- CPU 1 CPU 2 COMMENT
- =============== =============== =======================================
- u == 0, v == 1 and p == &u, q == &u
- v = 2;
- smp_wmb();
- <A:modify v=2> <C:busy>
- <C:queue v=2>
- p = &v; q = p;
- <D:request p>
- <B:modify p=&v> <D:commit p=&v>
- <D:read p>
- x = *q;
- <C:read *q> 캐시에 업데이트 되기 전의 v 를 읽음
- <C:unbusy>
- <C:commit v=2>
-
-기본적으로, 두개의 캐시라인 모두 CPU 2 에 최종적으로는 업데이트 될 것이지만,
-별도의 개입 없이는, 업데이트의 순서가 CPU 1 에서 만들어진 순서와 동일할
-것이라는 보장이 없습니다.
-
-
-여기에 개입하기 위해선, 데이터 의존성 배리어나 읽기 배리어를 로드 오퍼레이션들
-사이에 넣어야 합니다 (v4.15 부터는 READ_ONCE() 매크로에 의해 무조건적으로
-그렇게 됩니다). 이렇게 함으로써 캐시가 다음 요청을 처리하기 전에 일관성 큐를
-처리하도록 강제하게 됩니다.
-
- CPU 1 CPU 2 COMMENT
- =============== =============== =======================================
- u == 0, v == 1 and p == &u, q == &u
- v = 2;
- smp_wmb();
- <A:modify v=2> <C:busy>
- <C:queue v=2>
- p = &v; q = p;
- <D:request p>
- <B:modify p=&v> <D:commit p=&v>
- <D:read p>
- smp_read_barrier_depends()
- <C:unbusy>
- <C:commit v=2>
- x = *q;
- <C:read *q> 캐시에 업데이트 된 v 를 읽음
-
-
-이런 부류의 문제는 DEC Alpha 계열 프로세서들에서 발견될 수 있는데, 이들은
-데이터 버스를 좀 더 잘 사용해 성능을 개선할 수 있는, 분할된 캐시를 가지고 있기
-때문입니다. 대부분의 CPU 는 하나의 읽기 오퍼레이션의 메모리 액세스가 다른 읽기
-오퍼레이션에 의존적이라면 데이터 의존성 배리어를 내포시킵니다만, 모두가 그런건
-아니기 때문에 이점에 의존해선 안됩니다.
-
-다른 CPU 들도 분할된 캐시를 가지고 있을 수 있지만, 그런 CPU 들은 평범한 메모리
-액세스를 위해서도 이 분할된 캐시들 사이의 조정을 해야만 합니다. Alpha 는 가장
-약한 메모리 순서 시맨틱 (semantic) 을 선택함으로써 메모리 배리어가 명시적으로
-사용되지 않았을 때에는 그런 조정이 필요하지 않게 했으며, 이는 Alpha 가 당시에
-더 높은 CPU 클락 속도를 가질 수 있게 했습니다. 하지만, (다시 말하건대, v4.15
-이후부터는) Alpha 아키텍쳐 전용 코드와 READ_ONCE() 매크로 내부에서를 제외하고는
-smp_read_barrier_depends() 가 사용되지 않아야 함을 알아두시기 바랍니다.
-
-
캐시 일관성 VS DMA
------------------
@@ -2962,10 +2824,8 @@
데이터의 발견을 올바른 순서로 일어나게 하기 때문입니다.
리눅스 커널의 메모리 배리어 모델은 Alpha 에 기초해서 정의되었습니다만, v4.15
-부터는 리눅스 커널이 READ_ONCE() 내에 smp_read_barrier_depends() 를 추가해서
-Alpha 의 메모리 모델로의 영향력이 크게 줄어들긴 했습니다.
-
-위의 "캐시 일관성" 서브섹션을 참고하세요.
+부터는 Alpha 용 READ_ONCE() 코드 내에 smp_mb() 가 추가되어서 메모리 모델로의
+Alpha 의 영향력이 크게 줄어들었습니다.
가상 머신 게스트
diff --git a/Documentation/translations/zh_CN/admin-guide/clearing-warn-once.rst b/Documentation/translations/zh_CN/admin-guide/clearing-warn-once.rst
new file mode 100644
index 0000000..659264d
--- /dev/null
+++ b/Documentation/translations/zh_CN/admin-guide/clearing-warn-once.rst
@@ -0,0 +1,9 @@
+清除 WARN_ONCE
+--------------
+
+WARN_ONCE / WARN_ON_ONCE / printk_once 仅仅打印一次消息.
+
+echo 1 > /sys/kernel/debug/clear_warn_once
+
+可以清除这种状态并且再次允许打印一次告警信息，这对于运行测试集后重现问题
+很有用。
diff --git a/Documentation/translations/zh_CN/admin-guide/cpu-load.rst b/Documentation/translations/zh_CN/admin-guide/cpu-load.rst
new file mode 100644
index 0000000..c972731
--- /dev/null
+++ b/Documentation/translations/zh_CN/admin-guide/cpu-load.rst
@@ -0,0 +1,105 @@
+========
+CPU 负载
+========
+
+Linux通过``/proc/stat``和``/proc/uptime``导出各种信息，用户空间工具
+如top(1)使用这些信息计算系统花费在某个特定状态的平均时间。
+例如：
+
+ $ iostat
+ Linux 2.6.18.3-exp (linmac) 02/20/2007
+
+ avg-cpu: %user %nice %system %iowait %steal %idle
+ 10.01 0.00 2.92 5.44 0.00 81.63
+
+ ...
+
+这里系统认为在默认采样周期內有10.01%的时间工作在用户空间，2.92%的时
+间用在系统空间，总体上有81.63%的时间是空闲的。
+
+大多数情况下``/proc/stat``的信息几乎真实反映了系统信息，然而，由于内
+核采集这些数据的方式/时间的特点，有时这些信息根本不可靠。
+
+那么这些信息是如何被搜集的呢？每当时间中断触发时，内核查看此刻运行的
+进程类型，并增加与此类型/状态进程对应的计数器的值。这种方法的问题是
+在两次时间中断之间系统（进程）能够在多种状态之间切换多次，而计数器只
+增加最后一种状态下的计数。
+
+举例
+---
+
+假设系统有一个进程以如下方式周期性地占用cpu::
+
+ 两个时钟中断之间的时间线
+ |-----------------------|
+ ^ ^
+ |_ 开始运行 |
+ |_ 开始睡眠
+ （很快会被唤醒）
+
+在上面的情况下，根据``/proc/stat``的信息（由于当系统处于空闲状态时，
+时间中断经常会发生）系统的负载将会是0
+
+大家能够想象内核的这种行为会发生在许多情况下，这将导致``/proc/stat``
+中存在相当古怪的信息::
+
+ /* gcc -o hog smallhog.c */
+ #include <time.h>
+ #include <limits.h>
+ #include <signal.h>
+ #include <sys/time.h>
+ #define HIST 10
+
+ static volatile sig_atomic_t stop;
+
+ static void sighandler (int signr)
+ {
+ (void) signr;
+ stop = 1;
+ }
+ static unsigned long hog (unsigned long niters)
+ {
+ stop = 0;
+ while (!stop && --niters);
+ return niters;
+ }
+ int main (void)
+ {
+ int i;
+ struct itimerval it = { .it_interval = { .tv_sec = 0, .tv_usec = 1 },
+ .it_value = { .tv_sec = 0, .tv_usec = 1 } };
+ sigset_t set;
+ unsigned long v[HIST];
+ double tmp = 0.0;
+ unsigned long n;
+ signal (SIGALRM, &sighandler);
+ setitimer (ITIMER_REAL, &it, NULL);
+
+ hog (ULONG_MAX);
+ for (i = 0; i < HIST; ++i) v[i] = ULONG_MAX - hog (ULONG_MAX);
+ for (i = 0; i < HIST; ++i) tmp += v[i];
+ tmp /= HIST;
+ n = tmp - (tmp / 3.0);
+
+ sigemptyset (&set);
+ sigaddset (&set, SIGALRM);
+
+ for (;;) {
+ hog (n);
+ sigwait (&set, &i);
+ }
+ return 0;
+ }
+
+
+参考
+---
+
+- http://lkml.org/lkml/2007/2/12/6
+- Documentation/filesystems/proc.rst (1.8)
+
+
+谢谢
+---
+
+Con Kolivas, Pavel Machek
diff --git a/Documentation/translations/zh_CN/admin-guide/index.rst b/Documentation/translations/zh_CN/admin-guide/index.rst
new file mode 100644
index 0000000..ed5ab7e
--- /dev/null
+++ b/Documentation/translations/zh_CN/admin-guide/index.rst
@@ -0,0 +1,125 @@
+.. include:: ../disclaimer-zh_CN.rst
+
+:Original: :doc:`../../../admin-guide/index`
+:Translator: Alex Shi <alex.shi@linux.alibaba.com>
+
+
+Linux 内核用户和管理员指南
+==========================
+
+下面是一组随时间添加到内核中的面向用户的文档的集合。到目前为止，还没有一个
+整体的顺序或组织 - 这些材料不是一个单一的，连贯的文件！幸运的话，情况会随着
+时间的推移而迅速改善。
+
+这个初始部分包含总体信息，包括描述内核的README， 关于内核参数的文档等。
+
+Todolist:
+
+ README
+ kernel-parameters
+ devices
+ sysctl/index
+
+本节介绍CPU漏洞及其缓解措施。
+
+Todolist:
+
+ hw-vuln/index
+
+下面的一组文档，针对的是试图跟踪问题和bug的用户。
+
+Todolist:
+
+ reporting-bugs
+ security-bugs
+ bug-hunting
+ bug-bisect
+ tainted-kernels
+ ramoops
+ dynamic-debug-howto
+ init
+ kdump/index
+ perf/index
+
+这是应用程序开发人员感兴趣的章节的开始。可以在这里找到涵盖内核ABI各个
+方面的文档。
+
+Todolist:
+
+ sysfs-rules
+
+本手册的其余部分包括各种指南，介绍如何根据您的喜好配置内核的特定行为。
+
+
+.. toctree::
+ :maxdepth: 1
+
+ clearing-warn-once
+ cpu-load
+
+Todolist:
+
+ acpi/index
+ aoe/index
+ auxdisplay/index
+ bcache
+ binderfs
+ binfmt-misc
+ blockdev/index
+ bootconfig
+ braille-console
+ btmrvl
+ cgroup-v1/index
+ cgroup-v2
+ cifs/index
+ cputopology
+ dell_rbu
+ device-mapper/index
+ edid
+ efi-stub
+ ext4
+ nfs/index
+ gpio/index
+ highuid
+ hw_random
+ initrd
+ iostats
+ java
+ jfs
+ kernel-per-CPU-kthreads
+ laptops/index
+ lcd-panel-cgram
+ ldm
+ lockup-watchdogs
+ LSM/index
+ md
+ media/index
+ mm/index
+ module-signing
+ mono
+ namespaces/index
+ numastat
+ parport
+ perf-security
+ pm/index
+ pnp
+ rapidio
+ ras
+ rtc
+ serial-console
+ svga
+ sysrq
+ thunderbolt
+ ufs
+ unicode
+ vga-softcursor
+ video-output
+ wimax/index
+ xfs
+
+.. only:: subproject and html
+
+ Indices
+ =======
+
+ * :ref:`genindex`
diff --git a/Documentation/translations/zh_CN/arm/Booting b/Documentation/translations/zh_CN/arm/Booting
index 562e9a29..c3d26ce 100644
--- a/Documentation/translations/zh_CN/arm/Booting
+++ b/Documentation/translations/zh_CN/arm/Booting
@@ -124,7 +124,7 @@
bootloader 必须以 64bit 地址对齐的形式加载一个设备树映像(dtb)到系统
RAM 中，并用启动数据初始化它。dtb 格式在文档
-Documentation/devicetree/booting-without-of.txt 中。内核将会在
+Documentation/devicetree/booting-without-of.rst 中。内核将会在
dtb 物理地址处查找 dtb 魔数值（0xd00dfeed），以确定 dtb 是否已经代替
标签列表被传递进来。
diff --git a/Documentation/translations/zh_CN/filesystems/sysfs.txt b/Documentation/translations/zh_CN/filesystems/sysfs.txt
index fcf6200..9481e3e 100644
--- a/Documentation/translations/zh_CN/filesystems/sysfs.txt
+++ b/Documentation/translations/zh_CN/filesystems/sysfs.txt
@@ -213,10 +213,12 @@
- 缓冲区应总是 PAGE_SIZE 大小。对于i386，这个值为4096。
-- show() 方法应该返回写入缓冲区的字节数，也就是 snprintf()的
+- show() 方法应该返回写入缓冲区的字节数，也就是 scnprintf()的
返回值。
-- show() 应始终使用 snprintf()。
+- show() 方法在将格式化返回值返回用户空间的时候，禁止使用snprintf()。
+ 如果可以保证不会发生缓冲区溢出，可以使用sprintf()，否则必须使用
+ scnprintf()。
- store() 应返回缓冲区的已用字节数。如果整个缓存都已填满，只需返回
count 参数。
diff --git a/Documentation/translations/zh_CN/index.rst b/Documentation/translations/zh_CN/index.rst
index 76850a5..85643e4 100644
--- a/Documentation/translations/zh_CN/index.rst
+++ b/Documentation/translations/zh_CN/index.rst
@@ -10,9 +10,13 @@
人员做出贡献。 与任何大型社区一样，知道如何完成任务将使得更改合并的过程变得更
加容易。
+翻译计划:
+内核中文文档欢迎任何翻译投稿，特别是关于内核用户和管理员指南部分。
+
.. toctree::
:maxdepth: 2
+ admin-guide/index
process/index
filesystems/index
diff --git a/Documentation/translations/zh_CN/process/2.Process.rst b/Documentation/translations/zh_CN/process/2.Process.rst
index ceb733b..ebe2e02 100644
--- a/Documentation/translations/zh_CN/process/2.Process.rst
+++ b/Documentation/translations/zh_CN/process/2.Process.rst
@@ -212,7 +212,7 @@
当前-mm 补丁可在“mmotm”（-mm of the moment）目录中找到，地址：
- http://www.ozlabs.org/~akpm/mmotm/
+ https://www.ozlabs.org/~akpm/mmotm/
然而，使用mmotm树可能是一种令人沮丧的体验；它甚至可能无法编译。
@@ -220,7 +220,7 @@
linux-next 是下一个合并窗口关闭后主线的快照。linux-next树在Linux-kernel 和
Linux-next 邮件列表中发布，可从以下位置下载：
- http://www.kernel.org/pub/linux/kernel/next/
+ https://www.kernel.org/pub/linux/kernel/next/
Linux-next 已经成为内核开发过程中不可或缺的一部分；在一个给定的合并窗口中合并
的所有补丁都应该在合并窗口打开之前的一段时间内找到进入Linux-next 的方法。
@@ -260,7 +260,7 @@
现在几乎所有的Linux发行版都打包了Git。主页位于：
- http://git-scm.com/
+ https://git-scm.com/
那个页面有指向文档和教程的指针。
@@ -272,7 +272,7 @@
另一个值得了解的工具是quilt:
- http://savannah.nongnu.org/projects/quilt
+ https://savannah.nongnu.org/projects/quilt
Quilt 是一个补丁管理系统，而不是源代码管理系统。它不会随着时间的推移跟踪历史；
相反，它面向根据不断发展的代码库跟踪一组特定的更改。一些主要的子系统维护人员
diff --git a/Documentation/translations/zh_CN/process/4.Coding.rst b/Documentation/translations/zh_CN/process/4.Coding.rst
index b82b1dd..959a06b 100644
--- a/Documentation/translations/zh_CN/process/4.Coding.rst
+++ b/Documentation/translations/zh_CN/process/4.Coding.rst
@@ -224,7 +224,7 @@
或Blackfin开发板，您仍然可以执行编译步骤。可以在以下位置找到一组用于x86系统的
大型交叉编译器：
- http://www.kernel.org/pub/tools/crosstool/
+ https://www.kernel.org/pub/tools/crosstool/
花一些时间安装和使用这些编译器将有助于避免以后的尴尬。
diff --git a/Documentation/translations/zh_CN/process/7.AdvancedTopics.rst b/Documentation/translations/zh_CN/process/7.AdvancedTopics.rst
index 956815e..2f0ef75 100644
--- a/Documentation/translations/zh_CN/process/7.AdvancedTopics.rst
+++ b/Documentation/translations/zh_CN/process/7.AdvancedTopics.rst
@@ -25,9 +25,9 @@
将是Git如何特别适合内核开发过程。想要加快Git的开发人员可以在以下网站上找到
更多信息：
- http://git-scm.com/
+ https://git-scm.com/
- http://www.kernel.org/pub/software/scm/git/docs/user-manual.html
+ https://www.kernel.org/pub/software/scm/git/docs/user-manual.html
在尝试使用它使补丁可供其他人使用之前，第一要务是阅读上述站点，对Git的工作
方式有一个扎实的了解。使用Git的开发人员应该能够获得主线存储库的副本，探索
@@ -42,7 +42,7 @@
如果您有一个可以访问Internet的系统，那么使用git守护进程设置这样的服务器相
对简单。否则，免费的公共托管网站（例如github）开始出现在网络上。成熟的开发
人员可以在kernel.org上获得一个帐户，但这些帐户并不容易找到；有关更多信息，
-请参阅 http://kernel.org/faq/
+请参阅 https://kernel.org/faq/
正常的Git工作流程涉及到许多分支的使用。每一条开发线都可以分为单独的“主题
分支”，并独立维护。Git的分支机构很便宜，没有理由不免费使用它们。而且，在
diff --git a/Documentation/translations/zh_CN/process/8.Conclusion.rst b/Documentation/translations/zh_CN/process/8.Conclusion.rst
index 2bbd761..90cec3d 100644
--- a/Documentation/translations/zh_CN/process/8.Conclusion.rst
+++ b/Documentation/translations/zh_CN/process/8.Conclusion.rst
@@ -17,16 +17,16 @@
记录的；“make htmldocs”或“make pdfdocs”可用于以HTML或PDF格式生成这些文档（
尽管某些发行版提供的tex版本会遇到内部限制，无法正确处理文档）。
-不同的网站在各个细节层次上讨论内核开发。您的作者想谦虚地建议用 http://lwn.net/
+不同的网站在各个细节层次上讨论内核开发。您的作者想谦虚地建议用 https://lwn.net/
作为来源；有关许多特定内核主题的信息可以通过以下网址的lwn内核索引找到：
http://lwn.net/kernel/index/
除此之外，内核开发人员的一个宝贵资源是：
- http://kernelnewbies.org/
+ https://kernelnewbies.org/
-当然，我们不应该忘记 http://kernel.org/ 这是内核发布信息的最终位置。
+当然，我们不应该忘记 https://kernel.org/ 这是内核发布信息的最终位置。
关于内核开发有很多书：
@@ -42,9 +42,9 @@
有关git的文档，请访问：
- http://www.kernel.org/pub/software/scm/git/docs/
+ https://www.kernel.org/pub/software/scm/git/docs/
- http://www.kernel.org/pub/software/scm/git/docs/user-manual.html
+ https://www.kernel.org/pub/software/scm/git/docs/user-manual.html
结论
====
diff --git a/Documentation/translations/zh_CN/process/coding-style.rst b/Documentation/translations/zh_CN/process/coding-style.rst
index eae10bc..406d43a 100644
--- a/Documentation/translations/zh_CN/process/coding-style.rst
+++ b/Documentation/translations/zh_CN/process/coding-style.rst
@@ -946,7 +946,7 @@
ISBN 0-201-61586-X.
GNU 手册 - 遵循 K&R 标准和此文本 - cpp, gcc, gcc internals and indent,
-都可以从 http://www.gnu.org/manual/ 找到
+都可以从 https://www.gnu.org/manual/ 找到
WG14 是 C 语言的国际标准化工作组，URL: http://www.open-std.org/JTC1/SC22/WG14/
diff --git a/Documentation/translations/zh_CN/process/howto.rst b/Documentation/translations/zh_CN/process/howto.rst
index a8e6ab8..ee3dee4 100644
--- a/Documentation/translations/zh_CN/process/howto.rst
+++ b/Documentation/translations/zh_CN/process/howto.rst
@@ -69,7 +69,7 @@
邮件组里的人并不是律师，不要期望他们的话有法律效力。
对于GPL的常见问题和解答，请访问以下链接：
- http://www.gnu.org/licenses/gpl-faq.html
+ https://www.gnu.org/licenses/gpl-faq.html
文档
@@ -109,7 +109,7 @@
其他关于如何正确地生成补丁的优秀文档包括：
"The Perfect Patch"
- http://www.ozlabs.org/~akpm/stuff/tpp.txt
+ https://www.ozlabs.org/~akpm/stuff/tpp.txt
"Linux kernel patch submission format"
@@ -163,7 +163,7 @@
------------------
如果你对Linux内核开发一无所知，你应该访问“Linux内核新手”计划：
- http://kernelnewbies.org
+ https://kernelnewbies.org
它拥有一个可以问各种最基本的内核开发问题的邮件列表（在提问之前一定要记得
查找已往的邮件，确认是否有人已经回答过相同的问题）。它还拥有一个可以获得
@@ -176,7 +176,7 @@
如果你想加入内核开发社区并协助完成一些任务，却找不到从哪里开始，可以访问
“Linux内核房管员”计划：
- http://kernelnewbies.org/KernelJanitors
+ https://kernelnewbies.org/KernelJanitors
这是极佳的起点。它提供一个相对简单的任务列表，列出内核代码中需要被重新
整理或者改正的地方。通过和负责这个计划的开发者们一同工作，你会学到将补丁
@@ -212,7 +212,7 @@
- 每当一个新版本的内核被发布，为期两周的集成窗口将被打开。在这段时间里
维护者可以向Linus提交大段的修改，通常这些修改已经被放到-mm内核中几个
星期了。提交大量修改的首选方式是使用git工具（内核的代码版本管理工具
- ，更多的信息可以在 http://git-scm.com/ 获取），不过使用普通补丁也是
+ ，更多的信息可以在 https://git-scm.com/ 获取），不过使用普通补丁也是
可以的。
- 两个星期以后-rc1版本内核发布。之后只有不包含可能影响整个内核稳定性的
新功能的补丁才可能被接受。请注意一个全新的驱动程序（或者文件系统）有
@@ -472,7 +472,7 @@
想了解它具体应该看起来像什么，请查阅以下文档中的“ChangeLog”章节：
“The Perfect Patch”
- http://www.ozlabs.org/~akpm/stuff/tpp.txt
+ https://www.ozlabs.org/~akpm/stuff/tpp.txt
这些事情有时候做起来很难。要在任何方面都做到完美可能需要好几年时间。这是
diff --git a/Documentation/translations/zh_CN/process/submitting-drivers.rst b/Documentation/translations/zh_CN/process/submitting-drivers.rst
index d99885c..98341e7 100644
--- a/Documentation/translations/zh_CN/process/submitting-drivers.rst
+++ b/Documentation/translations/zh_CN/process/submitting-drivers.rst
@@ -19,8 +19,8 @@
=============================
这篇文档将会解释如何向不同的内核源码树提交设备驱动程序。请注意，如果你感
-兴趣的是显卡驱动程序，你也许应该访问 XFree86 项目(http://www.xfree86.org/)
-和／或 X.org 项目 (http://x.org)。
+兴趣的是显卡驱动程序，你也许应该访问 XFree86 项目(https://www.xfree86.org/)
+和／或 X.org 项目 (https://x.org)。
另请参阅 Documentation/translations/zh_CN/process/submitting-patches.rst 文档。
@@ -29,7 +29,7 @@
----------
块设备和字符设备的主设备号与从设备号是由 Linux 命名编号分配权威 LANANA（
-现在是 Torben Mathiasen）负责分配。申请的网址是 http://www.lanana.org/。
+现在是 Torben Mathiasen）负责分配。申请的网址是 https://www.lanana.org/。
即使不准备提交到主流内核的设备驱动也需要在这里分配设备号。有关详细信息，
请参阅 Documentation/admin-guide/devices.rst。
@@ -133,22 +133,22 @@
[可通过向majordomo@vger.kernel.org发邮件来订阅]
Linux 设备驱动程序，第三版（探讨 2.6.10 版内核）：
- http://lwn.net/Kernel/LDD3/ （免费版）
+ https://lwn.net/Kernel/LDD3/ （免费版）
LWN.net:
- 每周内核开发活动摘要 - http://lwn.net/
+ 每周内核开发活动摘要 - https://lwn.net/
2.6 版中 API 的变更：
- http://lwn.net/Articles/2.6-kernel-api/
+ https://lwn.net/Articles/2.6-kernel-api/
将旧版内核的驱动程序移植到 2.6 版：
- http://lwn.net/Articles/driver-porting/
+ https://lwn.net/Articles/driver-porting/
内核新手(KernelNewbies):
为新的内核开发者提供文档和帮助
- http://kernelnewbies.org/
+ https://kernelnewbies.org/
Linux USB项目：
http://www.linux-usb.org/
@@ -157,4 +157,4 @@
http://www.fenrus.org/how-to-not-write-a-device-driver-paper.pdf
内核清洁工 (Kernel Janitor):
- http://kernelnewbies.org/KernelJanitors
+ https://kernelnewbies.org/KernelJanitors
diff --git a/Documentation/translations/zh_CN/process/submitting-patches.rst b/Documentation/translations/zh_CN/process/submitting-patches.rst
index 1bb4271..2e7dbaa 100644
--- a/Documentation/translations/zh_CN/process/submitting-patches.rst
+++ b/Documentation/translations/zh_CN/process/submitting-patches.rst
@@ -91,7 +91,7 @@
:ref:`cn_split_changes`
如果你用 ``git`` , ``git rebase -i`` 可以帮助你这一点。如果你不用 ``git``,
-``quilt`` <http://savannah.nongnu.org/projects/quilt> 另外一个流行的选择。
+``quilt`` <https://savannah.nongnu.org/projects/quilt> 另外一个流行的选择。
.. _cn_describe_changes:
@@ -649,7 +649,7 @@
--------
Andrew Morton, "The perfect patch" (tpp).
- <http://www.ozlabs.org/~akpm/stuff/tpp.txt>
+ <https://www.ozlabs.org/~akpm/stuff/tpp.txt>
Jeff Garzik, "Linux kernel patch submission format".
<https://web.archive.org/web/20180829112450/http://linux.yyz.us/patch-format.html>
diff --git a/Documentation/translations/zh_CN/process/volatile-considered-harmful.rst b/Documentation/translations/zh_CN/process/volatile-considered-harmful.rst
index 48b32ce..ded3b5d 100644
--- a/Documentation/translations/zh_CN/process/volatile-considered-harmful.rst
+++ b/Documentation/translations/zh_CN/process/volatile-considered-harmful.rst
@@ -94,8 +94,8 @@
注释
----
-[1] http://lwn.net/Articles/233481/
-[2] http://lwn.net/Articles/233482/
+[1] https://lwn.net/Articles/233481/
+[2] https://lwn.net/Articles/233482/
致谢
----
diff --git a/Documentation/usb/gadget_hid.rst b/Documentation/usb/gadget_hid.rst
index 098d563..e623416 100644
--- a/Documentation/usb/gadget_hid.rst
+++ b/Documentation/usb/gadget_hid.rst
@@ -11,7 +11,7 @@
/dev/hidgX character devices.
For more details about HID, see the developer page on
-http://www.usb.org/developers/hidpage/
+https://www.usb.org/developers/hidpage/
Configuration
=============
diff --git a/Documentation/usb/gadget_multi.rst b/Documentation/usb/gadget_multi.rst
index 9806b55..3a22c1b 100644
--- a/Documentation/usb/gadget_multi.rst
+++ b/Documentation/usb/gadget_multi.rst
@@ -142,7 +142,7 @@
=========
[1] Remote Network Driver Interface Specification,
-[[http://msdn.microsoft.com/en-us/library/ee484414.aspx]].
+[[https://msdn.microsoft.com/en-us/library/ee484414.aspx]].
[2] Communications Device Class Abstract Control Model, spec for this
and other USB classes can be found at
@@ -150,9 +150,9 @@
[3] CDC Ethernet Control Model.
-[4] [[http://msdn.microsoft.com/en-us/library/ff537109(v=VS.85).aspx]]
+[4] [[https://msdn.microsoft.com/en-us/library/ff537109(v=VS.85).aspx]]
-[5] [[http://msdn.microsoft.com/en-us/library/ff539234(v=VS.85).aspx]]
+[5] [[https://msdn.microsoft.com/en-us/library/ff539234(v=VS.85).aspx]]
[6] To put it in some other nice words, Windows failed to respond to
any user input.
@@ -160,6 +160,6 @@
[7] You may find [[http://www.cygnal.org/ubb/Forum9/HTML/001050.html]]
useful.
-[8] http://www.nirsoft.net/utils/usb_devices_view.html
+[8] https://www.nirsoft.net/utils/usb_devices_view.html
-[9] [[http://msdn.microsoft.com/en-us/library/ff570620.aspx]]
+[9] [[https://msdn.microsoft.com/en-us/library/ff570620.aspx]]
diff --git a/Documentation/usb/linux.inf b/Documentation/usb/linux.inf
index 4ffa715b0..c569ac6 100644
--- a/Documentation/usb/linux.inf
+++ b/Documentation/usb/linux.inf
@@ -1,5 +1,5 @@
; Based on template INF file found at
-; <http://msdn.microsoft.com/en-us/library/ff570620.aspx>
+; <https://msdn.microsoft.com/en-us/library/ff570620.aspx>
; which was:
; Copyright (c) Microsoft Corporation
; and released under the MLPL as found at:
diff --git a/Documentation/userspace-api/ioctl/ioctl-number.rst b/Documentation/userspace-api/ioctl/ioctl-number.rst
index 59472cd..2a19883 100644
--- a/Documentation/userspace-api/ioctl/ioctl-number.rst
+++ b/Documentation/userspace-api/ioctl/ioctl-number.rst
@@ -339,6 +339,7 @@
0xB4 00-0F linux/gpio.h <mailto:linux-gpio@vger.kernel.org>
0xB5 00-0F uapi/linux/rpmsg.h <mailto:linux-remoteproc@vger.kernel.org>
0xB6 all linux/fpga-dfl.h
+0xB7 all uapi/linux/remoteproc_cdev.h <mailto:linux-remoteproc@vger.kernel.org>
0xC0 00-0F linux/usb/iowarrior.h
0xCA 00-0F uapi/misc/cxl.h
0xCA 10-2F uapi/misc/ocxl.h
diff --git a/Documentation/userspace-api/media/cec/cec-ioc-adap-g-caps.rst b/Documentation/userspace-api/media/cec/cec-ioc-adap-g-caps.rst
index 94e46a1..436a882 100644
--- a/Documentation/userspace-api/media/cec/cec-ioc-adap-g-caps.rst
+++ b/Documentation/userspace-api/media/cec/cec-ioc-adap-g-caps.rst
@@ -58,6 +58,9 @@
- The name of this CEC adapter. The combination ``driver`` and
``name`` must be unique.
* - __u32
+ - ``available_log_addrs``
+ - The maximum number of logical addresses that can be configured.
+ * - __u32
- ``capabilities``
- The capabilities of the CEC adapter, see
:ref:`cec-capabilities`.
diff --git a/Documentation/userspace-api/media/conf_nitpick.py b/Documentation/userspace-api/media/conf_nitpick.py
index d0c50d7..0a8e236 100644
--- a/Documentation/userspace-api/media/conf_nitpick.py
+++ b/Documentation/userspace-api/media/conf_nitpick.py
@@ -27,7 +27,7 @@
("c:func", "copy_to_user"),
("c:func", "determine_valid_ioctls"),
("c:func", "ERR_PTR"),
- ("c:func", "i2c_new_device"),
+ ("c:func", "i2c_new_client_device"),
("c:func", "ioctl"),
("c:func", "IS_ERR"),
("c:func", "KERNEL_VERSION"),
diff --git a/Documentation/userspace-api/media/dvb/fe-get-info.rst b/Documentation/userspace-api/media/dvb/fe-get-info.rst
index 80d9f81..6b3ffd3 100644
--- a/Documentation/userspace-api/media/dvb/fe-get-info.rst
+++ b/Documentation/userspace-api/media/dvb/fe-get-info.rst
@@ -34,8 +34,7 @@
File descriptor returned by :ref:`open() <frontend_f_open>`.
``argp``
- pointer to struct struct
- :c:type:`dvb_frontend_info`
+ pointer to struct :c:type:`dvb_frontend_info`
Description
diff --git a/Documentation/userspace-api/media/v4l/buffer.rst b/Documentation/userspace-api/media/v4l/buffer.rst
index 951ae1e..57e752a 100644
--- a/Documentation/userspace-api/media/v4l/buffer.rst
+++ b/Documentation/userspace-api/media/v4l/buffer.rst
@@ -23,8 +23,8 @@
:ref:`VIDIOC_QBUF <VIDIOC_QBUF>` and
:ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl. In the multi-planar API,
some plane-specific members of struct :c:type:`v4l2_buffer`,
-such as pointers and sizes for each plane, are stored in struct
-struct :c:type:`v4l2_plane` instead. In that case, struct
+such as pointers and sizes for each plane, are stored in
+struct :c:type:`v4l2_plane` instead. In that case,
struct :c:type:`v4l2_buffer` contains an array of plane structures.
Dequeued video buffers come with timestamps. The driver decides at which
@@ -577,7 +577,10 @@
applications shall use this flag if the data captured in the
buffer is not going to be touched by the CPU, instead the buffer
will, probably, be passed on to a DMA-capable hardware unit for
- further processing or output.
+ further processing or output. This flag is ignored unless the
+ queue is used for :ref:`memory mapping <mmap>` streaming I/O and
+ reports :ref:`V4L2_BUF_CAP_SUPPORTS_MMAP_CACHE_HINTS
+ <V4L2-BUF-CAP-SUPPORTS-MMAP-CACHE-HINTS>` capability.
* .. _`V4L2-BUF-FLAG-NO-CACHE-CLEAN`:
- ``V4L2_BUF_FLAG_NO_CACHE_CLEAN``
@@ -585,7 +588,10 @@
- Caches do not have to be cleaned for this buffer. Typically
applications shall use this flag for output buffers if the data in
this buffer has not been created by the CPU but by some
- DMA-capable unit, in which case caches have not been used.
+ DMA-capable unit, in which case caches have not been used. This flag
+ is ignored unless the queue is used for :ref:`memory mapping <mmap>`
+ streaming I/O and reports :ref:`V4L2_BUF_CAP_SUPPORTS_MMAP_CACHE_HINTS
+ <V4L2-BUF-CAP-SUPPORTS-MMAP-CACHE-HINTS>` capability.
* .. _`V4L2-BUF-FLAG-M2M-HOLD-CAPTURE-BUF`:
- ``V4L2_BUF_FLAG_M2M_HOLD_CAPTURE_BUF``
@@ -681,6 +687,36 @@
\normalsize
+.. _memory-flags:
+
+Memory Consistency Flags
+========================
+
+.. tabularcolumns:: |p{7.0cm}|p{2.2cm}|p{8.3cm}|
+
+.. cssclass:: longtable
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 3 1 4
+
+ * .. _`V4L2-FLAG-MEMORY-NON-CONSISTENT`:
+
+ - ``V4L2_FLAG_MEMORY_NON_CONSISTENT``
+ - 0x00000001
+ - A buffer is allocated either in consistent (it will be automatically
+ coherent between the CPU and the bus) or non-consistent memory. The
+ latter can provide performance gains, for instance the CPU cache
+ sync/flush operations can be avoided if the buffer is accessed by the
+ corresponding device only and the CPU does not read/write to/from that
+ buffer. However, this requires extra care from the driver -- it must
+ guarantee memory consistency by issuing a cache flush/sync when
+ consistency is needed. If this flag is set V4L2 will attempt to
+ allocate the buffer in non-consistent memory. The flag takes effect
+ only if the buffer is used for :ref:`memory mapping <mmap>` I/O and the
+ queue reports the :ref:`V4L2_BUF_CAP_SUPPORTS_MMAP_CACHE_HINTS
+ <V4L2-BUF-CAP-SUPPORTS-MMAP-CACHE-HINTS>` capability.
.. c:type:: v4l2_memory
diff --git a/Documentation/userspace-api/media/v4l/colorspaces-details.rst b/Documentation/userspace-api/media/v4l/colorspaces-details.rst
index 79ed6f4..300c5d2 100644
--- a/Documentation/userspace-api/media/v4l/colorspaces-details.rst
+++ b/Documentation/userspace-api/media/v4l/colorspaces-details.rst
@@ -767,8 +767,8 @@
information. So if something other than sRGB is used, then the driver
will have to set that information explicitly. Effectively
``V4L2_COLORSPACE_JPEG`` can be considered to be an abbreviation for
- ``V4L2_COLORSPACE_SRGB``, ``V4L2_YCBCR_ENC_601`` and
- ``V4L2_QUANTIZATION_FULL_RANGE``.
+ ``V4L2_COLORSPACE_SRGB``, ``V4L2_XFER_FUNC_SRGB``, ``V4L2_YCBCR_ENC_601``
+ and ``V4L2_QUANTIZATION_FULL_RANGE``.
***************************************
Detailed Transfer Function Descriptions
diff --git a/Documentation/userspace-api/media/v4l/dev-decoder.rst b/Documentation/userspace-api/media/v4l/dev-decoder.rst
index 606b549..3d4138a 100644
--- a/Documentation/userspace-api/media/v4l/dev-decoder.rst
+++ b/Documentation/userspace-api/media/v4l/dev-decoder.rst
@@ -247,7 +247,7 @@
Initialization
==============
-1. Set the coded format on ``OUTPUT`` via :c:func:`VIDIOC_S_FMT`
+1. Set the coded format on ``OUTPUT`` via :c:func:`VIDIOC_S_FMT`.
* **Required fields:**
@@ -803,7 +803,7 @@
* 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`
+2. Restart the ``OUTPUT`` queue via :c:func:`VIDIOC_STREAMON`.
* **Required fields:**
@@ -906,7 +906,9 @@
* visible resolution (selection rectangles),
-* the minimum number of buffers needed for decoding.
+* the minimum number of buffers needed for decoding,
+
+* bit-depth of the bitstream has been changed.
Whenever that happens, the decoder must proceed as follows:
@@ -1059,7 +1061,7 @@
``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
+ Although not mandatory, the availability of decoder commands may be queried
using :c:func:`VIDIOC_TRY_DECODER_CMD`.
End of Stream
diff --git a/Documentation/userspace-api/media/v4l/dev-encoder.rst b/Documentation/userspace-api/media/v4l/dev-encoder.rst
new file mode 100644
index 0000000..fb44f20
--- /dev/null
+++ b/Documentation/userspace-api/media/v4l/dev-encoder.rst
@@ -0,0 +1,753 @@
+.. This file is dual-licensed: you can use it either under the terms
+.. of the GPL 2.0 or the GFDL 1.1+ license, at your option. Note that this
+.. dual licensing only applies to this file, and not this project as a
+.. whole.
+..
+.. a) This file is free software; you can redistribute it and/or
+.. modify it under the terms of the GNU General Public License as
+.. published by the Free Software Foundation version 2 of
+.. the License.
+..
+.. This file is distributed in the hope that it will be useful,
+.. but WITHOUT ANY WARRANTY; without even the implied warranty of
+.. MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+.. GNU General Public License for more details.
+..
+.. Or, alternatively,
+..
+.. b) Permission is granted to copy, distribute and/or modify this
+.. document under the terms of the GNU Free Documentation License,
+.. Version 1.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/userspace-api/media/fdl-appendix.rst.
+..
+.. TODO: replace it to GPL-2.0 OR GFDL-1.1-or-later WITH no-invariant-sections
+
+.. _encoder:
+
+*************************************************
+Memory-to-Memory Stateful Video Encoder Interface
+*************************************************
+
+A stateful video encoder takes raw video frames in display order and encodes
+them into a bytestream. It generates complete chunks of the bytestream, including
+all metadata, headers, etc. The resulting bytestream does not require any
+further post-processing by the client.
+
+Performing software stream processing, header generation etc. in the driver
+in order to support this interface is strongly discouraged. In case such
+operations are needed, use of the Stateless Video Encoder 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 encoder 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.
+
+Glossary
+========
+
+Refer to :ref:`decoder-glossary`.
+
+State Machine
+=============
+
+.. kernel-render:: DOT
+ :alt: DOT digraph of encoder state machine
+ :caption: Encoder State Machine
+
+ digraph encoder_state_machine {
+ node [shape = doublecircle, label="Encoding"] Encoding;
+
+ node [shape = circle, label="Initialization"] Initialization;
+ node [shape = circle, label="Stopped"] Stopped;
+ node [shape = circle, label="Drain"] Drain;
+ node [shape = circle, label="Reset"] Reset;
+
+ node [shape = point]; qi
+ qi -> Initialization [ label = "open()" ];
+
+ Initialization -> Encoding [ label = "Both queues streaming" ];
+
+ Encoding -> Drain [ label = "V4L2_ENC_CMD_STOP" ];
+ Encoding -> Reset [ label = "VIDIOC_STREAMOFF(CAPTURE)" ];
+ Encoding -> Stopped [ label = "VIDIOC_STREAMOFF(OUTPUT)" ];
+ Encoding -> Encoding;
+
+ Drain -> Stopped [ label = "All CAPTURE\nbuffers dequeued\nor\nVIDIOC_STREAMOFF(OUTPUT)" ];
+ Drain -> Reset [ label = "VIDIOC_STREAMOFF(CAPTURE)" ];
+
+ Reset -> Encoding [ label = "VIDIOC_STREAMON(CAPTURE)" ];
+ Reset -> Initialization [ label = "VIDIOC_REQBUFS(OUTPUT, 0)" ];
+
+ Stopped -> Encoding [ label = "V4L2_ENC_CMD_START\nor\nVIDIOC_STREAMON(OUTPUT)" ];
+ Stopped -> Reset [ label = "VIDIOC_STREAMOFF(CAPTURE)" ];
+ }
+
+Querying Capabilities
+=====================
+
+1. To enumerate the set of coded formats supported by the encoder, the
+ client may call :c:func:`VIDIOC_ENUM_FMT` on ``CAPTURE``.
+
+ * The full set of supported formats will be returned, regardless of the
+ format set on ``OUTPUT``.
+
+2. To enumerate the set of supported raw formats, the client may call
+ :c:func:`VIDIOC_ENUM_FMT` on ``OUTPUT``.
+
+ * Only the formats supported for the format currently active on ``CAPTURE``
+ will be returned.
+
+ * In order to enumerate raw formats supported by a given coded format,
+ the client must first set that coded format on ``CAPTURE`` and then
+ enumerate the formats on ``OUTPUT``.
+
+3. The client may use :c:func:`VIDIOC_ENUM_FRAMESIZES` to detect supported
+ resolutions for a given format, passing the 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
+ encoder for the 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
+ encoder for the given raw pixel format and coded format currently set on
+ ``CAPTURE``.
+
+4. The client may use :c:func:`VIDIOC_ENUM_FRAMEINTERVALS` to detect supported
+ frame intervals for a given format and resolution, passing the desired pixel
+ format in :c:type:`v4l2_frmsizeenum` ``pixel_format`` and the resolution
+ in :c:type:`v4l2_frmsizeenum` ``width`` and :c:type:`v4l2_frmsizeenum`
+ ``height``.
+
+ * Values returned by :c:func:`VIDIOC_ENUM_FRAMEINTERVALS` for a coded pixel
+ format and coded resolution will include all possible frame intervals
+ supported by the encoder for the given coded pixel format and resolution.
+
+ * Values returned by :c:func:`VIDIOC_ENUM_FRAMEINTERVALS` for a raw pixel
+ format and resolution will include all possible frame intervals supported
+ by the encoder for the given raw pixel format and resolution and for the
+ coded format, coded resolution and coded frame interval currently set on
+ ``CAPTURE``.
+
+ * Support for :c:func:`VIDIOC_ENUM_FRAMEINTERVALS` is optional. If it is
+ not implemented, then there are no special restrictions other than the
+ limits of the codec itself.
+
+5. Supported profiles and levels for the coded format currently set on
+ ``CAPTURE``, if applicable, may be queried using their respective controls
+ via :c:func:`VIDIOC_QUERYCTRL`.
+
+6. Any additional encoder capabilities may be discovered by querying
+ their respective controls.
+
+Initialization
+==============
+
+1. Set the coded format on the ``CAPTURE`` queue via :c:func:`VIDIOC_S_FMT`.
+
+ * **Required fields:**
+
+ ``type``
+ a ``V4L2_BUF_TYPE_*`` enum appropriate for ``CAPTURE``.
+
+ ``pixelformat``
+ the coded format to be produced.
+
+ ``sizeimage``
+ desired size of ``CAPTURE`` buffers; the encoder may adjust it to
+ match hardware requirements.
+
+ ``width``, ``height``
+ ignored (read-only).
+
+ other fields
+ follow standard semantics.
+
+ * **Return fields:**
+
+ ``sizeimage``
+ adjusted size of ``CAPTURE`` buffers.
+
+ ``width``, ``height``
+ the coded size selected by the encoder based on current state, e.g.
+ ``OUTPUT`` format, selection rectangles, etc. (read-only).
+
+ .. important::
+
+ Changing the ``CAPTURE`` format may change the currently set ``OUTPUT``
+ format. How the new ``OUTPUT`` format is determined is up to the encoder
+ and the client must ensure it matches its needs afterwards.
+
+2. **Optional.** Enumerate supported ``OUTPUT`` formats (raw formats for
+ source) for the selected coded format via :c:func:`VIDIOC_ENUM_FMT`.
+
+ * **Required fields:**
+
+ ``type``
+ a ``V4L2_BUF_TYPE_*`` enum appropriate for ``OUTPUT``.
+
+ other fields
+ follow standard semantics.
+
+ * **Return fields:**
+
+ ``pixelformat``
+ raw format supported for the coded format currently selected on
+ the ``CAPTURE`` queue.
+
+ other fields
+ follow standard semantics.
+
+3. Set the raw source format on the ``OUTPUT`` queue via
+ :c:func:`VIDIOC_S_FMT`.
+
+ * **Required fields:**
+
+ ``type``
+ a ``V4L2_BUF_TYPE_*`` enum appropriate for ``OUTPUT``.
+
+ ``pixelformat``
+ raw format of the source.
+
+ ``width``, ``height``
+ source resolution.
+
+ other fields
+ follow standard semantics.
+
+ * **Return fields:**
+
+ ``width``, ``height``
+ may be adjusted to match encoder minimums, maximums and alignment
+ requirements, as required by the currently selected formats, as
+ reported by :c:func:`VIDIOC_ENUM_FRAMESIZES`.
+
+ other fields
+ follow standard semantics.
+
+ * Setting the ``OUTPUT`` format will reset the selection rectangles to their
+ default values, based on the new resolution, as described in the next
+ step.
+
+4. Set the raw frame interval on the ``OUTPUT`` queue via
+ :c:func:`VIDIOC_S_PARM`. This also sets the coded frame interval on the
+ ``CAPTURE`` queue to the same value.
+
+ * ** Required fields:**
+
+ ``type``
+ a ``V4L2_BUF_TYPE_*`` enum appropriate for ``OUTPUT``.
+
+ ``parm.output``
+ set all fields except ``parm.output.timeperframe`` to 0.
+
+ ``parm.output.timeperframe``
+ the desired frame interval; the encoder may adjust it to
+ match hardware requirements.
+
+ * **Return fields:**
+
+ ``parm.output.timeperframe``
+ the adjusted frame interval.
+
+ .. important::
+
+ Changing the ``OUTPUT`` frame interval *also* sets the framerate that
+ the encoder uses to encode the video. So setting the frame interval
+ to 1/24 (or 24 frames per second) will produce a coded video stream
+ that can be played back at that speed. The frame interval for the
+ ``OUTPUT`` queue is just a hint, the application may provide raw
+ frames at a different rate. It can be used by the driver to help
+ schedule multiple encoders running in parallel.
+
+ In the next step the ``CAPTURE`` frame interval can optionally be
+ changed to a different value. This is useful for off-line encoding
+ were the coded frame interval can be different from the rate at
+ which raw frames are supplied.
+
+ .. important::
+
+ ``timeperframe`` deals with *frames*, not fields. So for interlaced
+ formats this is the time per two fields, since a frame consists of
+ a top and a bottom field.
+
+ .. note::
+
+ It is due to historical reasons that changing the ``OUTPUT`` frame
+ interval also changes the coded frame interval on the ``CAPTURE``
+ queue. Ideally these would be independent settings, but that would
+ break the existing API.
+
+5. **Optional** Set the coded frame interval on the ``CAPTURE`` queue via
+ :c:func:`VIDIOC_S_PARM`. This is only necessary if the coded frame
+ interval is different from the raw frame interval, which is typically
+ the case for off-line encoding. Support for this feature is signalled
+ by the :ref:`V4L2_FMT_FLAG_ENC_CAP_FRAME_INTERVAL <fmtdesc-flags>` format flag.
+
+ * ** Required fields:**
+
+ ``type``
+ a ``V4L2_BUF_TYPE_*`` enum appropriate for ``CAPTURE``.
+
+ ``parm.capture``
+ set all fields except ``parm.capture.timeperframe`` to 0.
+
+ ``parm.capture.timeperframe``
+ the desired coded frame interval; the encoder may adjust it to
+ match hardware requirements.
+
+ * **Return fields:**
+
+ ``parm.capture.timeperframe``
+ the adjusted frame interval.
+
+ .. important::
+
+ Changing the ``CAPTURE`` frame interval sets the framerate for the
+ coded video. It does *not* set the rate at which buffers arrive on the
+ ``CAPTURE`` queue, that depends on how fast the encoder is and how
+ fast raw frames are queued on the ``OUTPUT`` queue.
+
+ .. important::
+
+ ``timeperframe`` deals with *frames*, not fields. So for interlaced
+ formats this is the time per two fields, since a frame consists of
+ a top and a bottom field.
+
+ .. note::
+
+ Not all drivers support this functionality, in that case just set
+ the desired coded frame interval for the ``OUTPUT`` queue.
+
+ However, drivers that can schedule multiple encoders based on the
+ ``OUTPUT`` frame interval must support this optional feature.
+
+6. **Optional.** Set the visible resolution for the stream metadata via
+ :c:func:`VIDIOC_S_SELECTION` on the ``OUTPUT`` queue if it is desired
+ to be different than the full OUTPUT resolution.
+
+ * **Required fields:**
+
+ ``type``
+ a ``V4L2_BUF_TYPE_*`` enum appropriate for ``OUTPUT``.
+
+ ``target``
+ set to ``V4L2_SEL_TGT_CROP``.
+
+ ``r.left``, ``r.top``, ``r.width``, ``r.height``
+ visible rectangle; this must fit within the `V4L2_SEL_TGT_CROP_BOUNDS`
+ rectangle and may be subject to adjustment to match codec and
+ hardware constraints.
+
+ * **Return fields:**
+
+ ``r.left``, ``r.top``, ``r.width``, ``r.height``
+ visible rectangle adjusted by the encoder.
+
+ * The following selection targets are supported on ``OUTPUT``:
+
+ ``V4L2_SEL_TGT_CROP_BOUNDS``
+ equal to the full source frame, matching the active ``OUTPUT``
+ format.
+
+ ``V4L2_SEL_TGT_CROP_DEFAULT``
+ equal to ``V4L2_SEL_TGT_CROP_BOUNDS``.
+
+ ``V4L2_SEL_TGT_CROP``
+ rectangle within the source buffer to be encoded into the
+ ``CAPTURE`` stream; defaults to ``V4L2_SEL_TGT_CROP_DEFAULT``.
+
+ .. note::
+
+ A common use case for this selection target is encoding a source
+ video with a resolution that is not a multiple of a macroblock,
+ e.g. the common 1920x1080 resolution may require the source
+ buffers to be aligned to 1920x1088 for codecs with 16x16 macroblock
+ size. To avoid encoding the padding, the client needs to explicitly
+ configure this selection target to 1920x1080.
+
+ .. warning::
+
+ The encoder may adjust the crop/compose rectangles to the nearest
+ supported ones to meet codec and hardware requirements. The client needs
+ to check the adjusted rectangle returned by :c:func:`VIDIOC_S_SELECTION`.
+
+7. Allocate buffers for both ``OUTPUT`` and ``CAPTURE`` via
+ :c:func:`VIDIOC_REQBUFS`. This may be performed in any order.
+
+ * **Required fields:**
+
+ ``count``
+ requested number of buffers to allocate; greater than zero.
+
+ ``type``
+ a ``V4L2_BUF_TYPE_*`` enum appropriate for ``OUTPUT`` or
+ ``CAPTURE``.
+
+ other fields
+ follow 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 OUTPUT buffers (for pipeline
+ depth), the client may query the ``V4L2_CID_MIN_BUFFERS_FOR_OUTPUT``
+ 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` 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``.
+
+ other fields
+ follow standard semantics.
+
+ * **Return fields:**
+
+ ``count``
+ adjusted to the number of allocated buffers.
+
+8. Begin streaming on both ``OUTPUT`` and ``CAPTURE`` queues via
+ :c:func:`VIDIOC_STREAMON`. This may be performed in any order. The actual
+ encoding process starts when both queues start streaming.
+
+.. note::
+
+ If the client stops the ``CAPTURE`` queue during the encode process and then
+ restarts it again, the encoder will begin generating a stream independent
+ from the stream generated before the stop. The exact constraints depend
+ on the coded format, but may include the following implications:
+
+ * encoded frames produced after the restart must not reference any
+ frames produced before the stop, e.g. no long term references for
+ H.264/HEVC,
+
+ * any headers that must be included in a standalone stream must be
+ produced again, e.g. SPS and PPS for H.264/HEVC.
+
+Encoding
+========
+
+This state is reached after the `Initialization` 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 encoded ``CAPTURE`` 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 standard behavior of V4L2 buffer
+queues and memory-to-memory devices. In addition, the order of encoded frames
+dequeued from the ``CAPTURE`` queue may differ from the order of queuing raw
+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 more than one buffer produced on
+ ``CAPTURE`` (for example, if returning an encoded frame allowed the encoder
+ to return a frame that preceded it in display, but succeeded it in the decode
+ order; however, there may be other reasons for this as well),
+
+* a buffer queued to ``OUTPUT`` may result in a buffer being produced on
+ ``CAPTURE`` later into encode 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 encoding results are only
+ available at later time, due to specifics of the encoding process,
+
+* buffers queued to ``OUTPUT`` may not become available to dequeue instantly
+ after being encoded into a corresponding ``CAPTURE`` buffer, e.g. if the
+ encoder needs to use the frame as a reference for encoding further frames.
+
+.. note::
+
+ To allow matching encoded ``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 encoding 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,
+
+ * the encoding order differs from the presentation 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.
+
+.. note::
+
+ To let the client distinguish between frame types (keyframes, intermediate
+ frames; the exact list of types depends on the coded format), the
+ ``CAPTURE`` buffers will have corresponding flag bits set in their
+ :c:type:`v4l2_buffer` struct when dequeued. See the documentation of
+ :c:type:`v4l2_buffer` and each coded pixel format for exact list of flags
+ and their meanings.
+
+Should an encoding error occur, it will be reported to the client with the level
+of details depending on the encoder capabilities. Specifically:
+
+* the ``CAPTURE`` buffer (if any) that contains the results of the failed encode
+ operation will be returned with the ``V4L2_BUF_FLAG_ERROR`` flag set,
+
+* if the encoder is able to precisely report the ``OUTPUT`` buffer(s) that triggered
+ the error, such buffer(s) will be returned with the ``V4L2_BUF_FLAG_ERROR`` flag
+ set.
+
+.. note::
+
+ If a ``CAPTURE`` buffer is too small then it is just returned with the
+ ``V4L2_BUF_FLAG_ERROR`` flag set. More work is needed to detect that this
+ error occurred because the buffer was too small, and to provide support to
+ free existing buffers that were too small.
+
+In case of a fatal failure that does not allow the encoding to continue, any
+further operations on corresponding encoder 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.
+
+Encoding Parameter Changes
+==========================
+
+The client is allowed to use :c:func:`VIDIOC_S_CTRL` to change encoder
+parameters at any time. The availability of parameters is encoder-specific
+and the client must query the encoder to find the set of available controls.
+
+The ability to change each parameter during encoding is encoder-specific, as
+per the standard semantics of the V4L2 control interface. The client may
+attempt to set a control during encoding and if the operation fails with the
+-EBUSY error code, the ``CAPTURE`` queue needs to be stopped for the
+configuration change to be allowed. To do this, it may follow the `Drain`
+sequence to avoid losing the already queued/encoded frames.
+
+The timing of parameter updates is encoder-specific, as per the standard
+semantics of the V4L2 control interface. If the client needs to apply the
+parameters exactly at specific frame, using the Request API
+(:ref:`media-request-api`) should be considered, if supported by the encoder.
+
+Drain
+=====
+
+To ensure that all the queued ``OUTPUT`` buffers have been processed and the
+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 encoded frames for all ``OUTPUT`` buffers queued before the
+sequence was started.
+
+1. Begin the drain sequence by issuing :c:func:`VIDIOC_ENCODER_CMD`.
+
+ * **Required fields:**
+
+ ``cmd``
+ set to ``V4L2_ENC_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_ENCODER_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_ENCODER_CMD` was issued will be processed and encoded as
+ normal. The client must continue to handle both queues independently,
+ similarly to normal encode operation. This includes:
+
+ * 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 an encoded 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_ENC_CMD_STOP`` command are dequeued,
+
+ * dequeuing the ``V4L2_EVENT_EOS`` event, if the client subscribes to it.
+
+ .. note::
+
+ For backwards compatibility, the encoder will signal a ``V4L2_EVENT_EOS``
+ event when the last frame has been encoded and all frames are ready to be
+ dequeued. It is deprecated behavior and the client must not rely on it.
+ The ``V4L2_BUF_FLAG_LAST`` buffer flag should be used instead.
+
+3. Once all ``OUTPUT`` buffers queued before the ``V4L2_ENC_CMD_STOP`` call are
+ dequeued and the last ``CAPTURE`` buffer is dequeued, the encoder is stopped
+ and it will accept, but not process any newly queued ``OUTPUT`` buffers
+ until the client issues any of the following operations:
+
+ * ``V4L2_ENC_CMD_START`` - the encoder 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 encoder will be reset (see the `Reset` sequence)
+ and then resume encoding,
+
+ * a pair of :c:func:`VIDIOC_STREAMOFF` and :c:func:`VIDIOC_STREAMON` on the
+ ``OUTPUT`` queue - the encoder will resume operation normally, however any
+ source frames queued to the ``OUTPUT`` queue between ``V4L2_ENC_CMD_STOP``
+ and :c:func:`VIDIOC_STREAMOFF` will be discarded.
+
+.. 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_ENC_CMD_START`` or
+ ``V4L2_ENC_CMD_STOP`` again while the drain sequence is in progress and they
+ will fail with -EBUSY error code if attempted.
+
+ For reference, handling of various corner cases is described below:
+
+ * In case of no buffer in the ``OUTPUT`` queue at the time the
+ ``V4L2_ENC_CMD_STOP`` command was issued, the drain sequence completes
+ immediately and the encoder returns an empty ``CAPTURE`` buffer with the
+ ``V4L2_BUF_FLAG_LAST`` flag set.
+
+ * In case of no buffer in the ``CAPTURE`` queue at the time the drain
+ sequence completes, the next time the client queues a ``CAPTURE`` buffer
+ it is returned at once as an empty buffer with the ``V4L2_BUF_FLAG_LAST``
+ flag set.
+
+ * If :c:func:`VIDIOC_STREAMOFF` is called on the ``CAPTURE`` queue in the
+ middle of the drain sequence, the drain sequence is canceled and all
+ ``CAPTURE`` buffers are implicitly returned to the client.
+
+ * If :c:func:`VIDIOC_STREAMOFF` is called on the ``OUTPUT`` queue in the
+ middle of the drain sequence, the drain sequence completes immediately and
+ next ``CAPTURE`` buffer will be returned empty with the
+ ``V4L2_BUF_FLAG_LAST`` flag set.
+
+ Although not mandatory, the availability of encoder commands may be queried
+ using :c:func:`VIDIOC_TRY_ENCODER_CMD`.
+
+Reset
+=====
+
+The client may want to request the encoder to reinitialize the encoding, so
+that the following stream data becomes independent from the stream data
+generated before. Depending on the coded format, that may imply that:
+
+* encoded frames produced after the restart must not reference any frames
+ produced before the stop, e.g. no long term references for H.264/HEVC,
+
+* any headers that must be included in a standalone stream must be produced
+ again, e.g. SPS and PPS for H.264/HEVC.
+
+This can be achieved by performing the reset sequence.
+
+1. Perform the `Drain` sequence to ensure all the in-flight encoding finishes
+ and respective buffers are dequeued.
+
+2. Stop streaming on the ``CAPTURE`` queue via :c:func:`VIDIOC_STREAMOFF`. This
+ will return all currently queued ``CAPTURE`` buffers to the client, without
+ valid frame data.
+
+3. Start streaming on the ``CAPTURE`` queue via :c:func:`VIDIOC_STREAMON` and
+ continue with regular encoding sequence. The encoded frames produced into
+ ``CAPTURE`` buffers from now on will contain a standalone stream that can be
+ decoded without the need for frames encoded before the reset sequence,
+ starting at the first ``OUTPUT`` buffer queued after issuing the
+ `V4L2_ENC_CMD_STOP` of the `Drain` sequence.
+
+This sequence may be also used to change encoding parameters for encoders
+without the ability to change the parameters on the fly.
+
+Commit Points
+=============
+
+Setting formats and allocating buffers triggers changes in the behavior of the
+encoder.
+
+1. Setting the format on the ``CAPTURE`` queue may change the set of formats
+ supported/advertised on the ``OUTPUT`` queue. In particular, it also means
+ that the ``OUTPUT`` format may be reset and the client must not rely on the
+ previously set format being preserved.
+
+2. Enumerating formats on the ``OUTPUT`` queue always returns only formats
+ supported for the current ``CAPTURE`` format.
+
+3. Setting the format on the ``OUTPUT`` queue does not change the list of
+ formats available on the ``CAPTURE`` queue. An attempt to set the ``OUTPUT``
+ format that is not supported for the currently selected ``CAPTURE`` format
+ will result in the encoder adjusting the requested ``OUTPUT`` format to a
+ supported one.
+
+4. Enumerating formats on the ``CAPTURE`` queue always returns the full set of
+ supported coded formats, irrespective of the current ``OUTPUT`` format.
+
+5. While buffers are allocated on any of the ``OUTPUT`` or ``CAPTURE`` queues,
+ the client must not change the format on the ``CAPTURE`` 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
+``CAPTURE`` queue and the ``CAPTURE`` queue is the master that governs the
+set of supported formats for the ``OUTPUT`` queue.
diff --git a/Documentation/userspace-api/media/v4l/dev-mem2mem.rst b/Documentation/userspace-api/media/v4l/dev-mem2mem.rst
index 9279d87..40aff9c 100644
--- a/Documentation/userspace-api/media/v4l/dev-mem2mem.rst
+++ b/Documentation/userspace-api/media/v4l/dev-mem2mem.rst
@@ -46,4 +46,5 @@
:maxdepth: 1
dev-decoder
+ dev-encoder
dev-stateless-decoder
diff --git a/Documentation/userspace-api/media/v4l/dev-osd.rst b/Documentation/userspace-api/media/v4l/dev-osd.rst
index 67dc463..ad0c156 100644
--- a/Documentation/userspace-api/media/v4l/dev-osd.rst
+++ b/Documentation/userspace-api/media/v4l/dev-osd.rst
@@ -51,7 +51,7 @@
``base`` field of struct :c:type:`v4l2_framebuffer`.
The framebuffer device ioctl ``FBIOGET_FSCREENINFO`` returns the same
address in the ``smem_start`` field of struct
-struct :c:type:`fb_fix_screeninfo`. The ``FBIOGET_FSCREENINFO``
+:c:type:`fb_fix_screeninfo`. The ``FBIOGET_FSCREENINFO``
ioctl and struct :c:type:`fb_fix_screeninfo` are defined in
the ``linux/fb.h`` header file.
diff --git a/Documentation/userspace-api/media/v4l/dev-sdr.rst b/Documentation/userspace-api/media/v4l/dev-sdr.rst
index c9563bc..4a80319 100644
--- a/Documentation/userspace-api/media/v4l/dev-sdr.rst
+++ b/Documentation/userspace-api/media/v4l/dev-sdr.rst
@@ -78,7 +78,7 @@
``V4L2_BUF_TYPE_SDR_CAPTURE`` or ``V4L2_BUF_TYPE_SDR_OUTPUT`` and use
the struct :c:type:`v4l2_sdr_format` ``sdr`` member
of the ``fmt`` union as needed per the desired operation. Currently
-there is two fields, ``pixelformat`` and ``buffersize``, of struct
+there are two fields, ``pixelformat`` and ``buffersize``, of
struct :c:type:`v4l2_sdr_format` which are used.
Content of the ``pixelformat`` is V4L2 FourCC code of the data format.
The ``buffersize`` field is maximum buffer size in bytes required for
diff --git a/Documentation/userspace-api/media/v4l/hist-v4l2.rst b/Documentation/userspace-api/media/v4l/hist-v4l2.rst
index 7913d01..6dcfe60 100644
--- a/Documentation/userspace-api/media/v4l/hist-v4l2.rst
+++ b/Documentation/userspace-api/media/v4l/hist-v4l2.rst
@@ -43,7 +43,7 @@
1998-09-28: Revamped video standard. Made video controls individually
enumerable.
-1998-10-02: The ``id`` field was removed from struct
+1998-10-02: The ``id`` field was removed from
struct ``video_standard`` and the color subcarrier fields were
renamed. The :ref:`VIDIOC_QUERYSTD` ioctl was
renamed to :ref:`VIDIOC_ENUMSTD`,
@@ -260,7 +260,7 @@
2000-09-18: ``V4L2_BUF_TYPE_VBI`` was added. This may *break
compatibility* as the :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` and
-:ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctls may fail now if the struct
+:ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctls may fail now if the
struct ``v4l2_fmt`` ``type`` field does not contain
``V4L2_BUF_TYPE_VBI``. In the documentation of the struct
:c:type:`v4l2_vbi_format` ``offset`` field the
diff --git a/Documentation/userspace-api/media/v4l/pixfmt-srggb14p.rst b/Documentation/userspace-api/media/v4l/pixfmt-srggb14p.rst
index ec1239a..e2f5a2b 100644
--- a/Documentation/userspace-api/media/v4l/pixfmt-srggb14p.rst
+++ b/Documentation/userspace-api/media/v4l/pixfmt-srggb14p.rst
@@ -69,37 +69,37 @@
B\ :sub:`00low bits 5--0`\ (bits 5--0)
- - R\ :sub:`02low bits 3--0`\ (bits 7--4)
+ - B\ :sub:`02low bits 3--0`\ (bits 7--4)
G\ :sub:`01low bits 5--2`\ (bits 3--0)
- G\ :sub:`03low bits 5--0`\ (bits 7--2)
- R\ :sub:`02low bits 5--4`\ (bits 1--0)
+ B\ :sub:`02low bits 5--4`\ (bits 1--0)
- .. row 2
- start + 7
- - G\ :sub:`00high`
+ - G\ :sub:`10high`
- - R\ :sub:`01high`
+ - R\ :sub:`11high`
- - G\ :sub:`02high`
+ - G\ :sub:`12high`
- - R\ :sub:`03high`
+ - R\ :sub:`13high`
- - R\ :sub:`01low bits 1--0`\ (bits 7--6)
+ - R\ :sub:`11low bits 1--0`\ (bits 7--6)
- G\ :sub:`00low bits 5--0`\ (bits 5--0)
+ G\ :sub:`10low bits 5--0`\ (bits 5--0)
- - G\ :sub:`02low bits 3--0`\ (bits 7--4)
+ - G\ :sub:`12low bits 3--0`\ (bits 7--4)
- R\ :sub:`01low bits 5--2`\ (bits 3--0)
+ R\ :sub:`11low bits 5--2`\ (bits 3--0)
- - R\ :sub:`03low bits 5--0`\ (bits 7--2)
+ - R\ :sub:`13low bits 5--0`\ (bits 7--2)
- G\ :sub:`02low bits 5--4`\ (bits 1--0)
+ G\ :sub:`12low bits 5--4`\ (bits 1--0)
- .. row 3
@@ -117,13 +117,13 @@
B\ :sub:`20low bits 5--0`\ (bits 5--0)
- - R\ :sub:`22low bits 3--0`\ (bits 7--4)
+ - B\ :sub:`22low bits 3--0`\ (bits 7--4)
G\ :sub:`21low bits 5--2`\ (bits 3--0)
- G\ :sub:`23low bits 5--0`\ (bits 7--2)
- R\ :sub:`22low bits 5--4`\ (bits 1--0)
+ B\ :sub:`22low bits 5--4`\ (bits 1--0)
- .. row 4
diff --git a/Documentation/userspace-api/media/v4l/pixfmt-v4l2.rst b/Documentation/userspace-api/media/v4l/pixfmt-v4l2.rst
index 759420a..e0ee282 100644
--- a/Documentation/userspace-api/media/v4l/pixfmt-v4l2.rst
+++ b/Documentation/userspace-api/media/v4l/pixfmt-v4l2.rst
@@ -44,6 +44,11 @@
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.
+
+ For compressed formats on the CAPTURE side of a stateful mem2mem
+ encoder, the fields must be zero, since the coded size is expected to
+ be calculated internally by the encoder itself, based on the OUTPUT
+ side. For more details see :ref:`encoder` and format descriptions.
* - __u32
- ``pixelformat``
- The pixel format or type of compression, set by the application.
diff --git a/Documentation/userspace-api/media/v4l/v4l2.rst b/Documentation/userspace-api/media/v4l/v4l2.rst
index ab7c97c..35796c4 100644
--- a/Documentation/userspace-api/media/v4l/v4l2.rst
+++ b/Documentation/userspace-api/media/v4l/v4l2.rst
@@ -63,6 +63,7 @@
- Figa, Tomasz <tfiga@chromium.org>
- Documented the memory-to-memory decoder interface.
+ - Documented the memory-to-memory encoder interface.
- H Schimek, Michael <mschimek@gmx.at>
@@ -75,6 +76,7 @@
- Osciak, Pawel <posciak@chromium.org>
- Documented the memory-to-memory decoder interface.
+ - Documented the memory-to-memory encoder interface.
- Osciak, Pawel <pawel@osciak.com>
diff --git a/Documentation/userspace-api/media/v4l/vidioc-create-bufs.rst b/Documentation/userspace-api/media/v4l/vidioc-create-bufs.rst
index e1afc5b..f2a70287 100644
--- a/Documentation/userspace-api/media/v4l/vidioc-create-bufs.rst
+++ b/Documentation/userspace-api/media/v4l/vidioc-create-bufs.rst
@@ -121,7 +121,12 @@
other changes, then set ``count`` to 0, ``memory`` to
``V4L2_MEMORY_MMAP`` and ``format.type`` to the buffer type.
* - __u32
- - ``reserved``\ [7]
+ - ``flags``
+ - Specifies additional buffer management attributes.
+ See :ref:`memory-flags`.
+
+ * - __u32
+ - ``reserved``\ [6]
- A place holder for future extensions. Drivers and applications
must set the array to zero.
diff --git a/Documentation/userspace-api/media/v4l/vidioc-dqevent.rst b/Documentation/userspace-api/media/v4l/vidioc-dqevent.rst
index a9a176d..9412be0 100644
--- a/Documentation/userspace-api/media/v4l/vidioc-dqevent.rst
+++ b/Documentation/userspace-api/media/v4l/vidioc-dqevent.rst
@@ -260,7 +260,7 @@
:ref:`v4l2_queryctrl <v4l2-queryctrl>`.
* - __s32
- ``default_value``
- - The default value value of the control. See struct
+ - The default value of the control. See struct
:ref:`v4l2_queryctrl <v4l2-queryctrl>`.
diff --git a/Documentation/userspace-api/media/v4l/vidioc-encoder-cmd.rst b/Documentation/userspace-api/media/v4l/vidioc-encoder-cmd.rst
index 16269b3..d0eacce 100644
--- a/Documentation/userspace-api/media/v4l/vidioc-encoder-cmd.rst
+++ b/Documentation/userspace-api/media/v4l/vidioc-encoder-cmd.rst
@@ -51,25 +51,26 @@
``VIDIOC_ENCODER_CMD`` or ``VIDIOC_TRY_ENCODER_CMD`` with a pointer to
this structure.
-The ``cmd`` field must contain the command code. The ``flags`` field is
-currently only used by the STOP command and contains one bit: If the
-``V4L2_ENC_CMD_STOP_AT_GOP_END`` flag is set, encoding will continue
-until the end of the current *Group Of Pictures*, otherwise it will stop
-immediately.
+The ``cmd`` field must contain the command code. Some commands use the
+``flags`` field for additional information.
-A :ref:`read() <func-read>` or :ref:`VIDIOC_STREAMON <VIDIOC_STREAMON>`
-call sends an implicit START command to the encoder if it has not been
-started yet. After a STOP command, :ref:`read() <func-read>` calls will read
+After a STOP command, :ref:`read() <func-read>` calls will read
the remaining data buffered by the driver. When the buffer is empty,
:ref:`read() <func-read>` will return zero and the next :ref:`read() <func-read>`
call will restart the encoder.
+A :ref:`read() <func-read>` or :ref:`VIDIOC_STREAMON <VIDIOC_STREAMON>`
+call sends an implicit START command to the encoder if it has not been
+started yet. Applies to both queues of mem2mem encoders.
+
A :ref:`close() <func-close>` or :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>`
call of a streaming file descriptor sends an implicit immediate STOP to
-the encoder, and all buffered data is discarded.
+the encoder, and all buffered data is discarded. Applies to both queues of
+mem2mem encoders.
These ioctls are optional, not all drivers may support them. They were
-introduced in Linux 2.6.21.
+introduced in Linux 2.6.21. They are, however, mandatory for stateful mem2mem
+encoders (as further documented in :ref:`encoder`).
.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
@@ -109,21 +110,24 @@
- 0
- Start the encoder. When the encoder is already running or paused,
this command does nothing. No flags are defined for this command.
+
+ For a device implementing the :ref:`encoder`, once the drain sequence
+ is initiated with the ``V4L2_ENC_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. See :ref:`encoder` for more details.
* - ``V4L2_ENC_CMD_STOP``
- 1
- Stop the encoder. When the ``V4L2_ENC_CMD_STOP_AT_GOP_END`` flag
is set, encoding will continue until the end of the current *Group
Of Pictures*, otherwise encoding will stop immediately. When the
- encoder is already stopped, this command does nothing. mem2mem
- encoders will send a ``V4L2_EVENT_EOS`` event when the last frame
- has been encoded 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.
+ encoder is already stopped, this command does nothing.
+
+ For a device implementing the :ref:`encoder`, the command will initiate
+ the drain sequence as documented in :ref:`encoder`. 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_ENC_CMD_PAUSE``
- 2
- Pause the encoder. When the encoder has not been started yet, the
@@ -152,6 +156,8 @@
- Stop encoding at the end of the current *Group Of Pictures*,
rather than immediately.
+ Does not apply to :ref:`encoder`.
+
Return Value
============
@@ -160,6 +166,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:`encoder` is still in
+ progress. It is not allowed to issue another encoder command until it
+ completes.
+
EINVAL
The ``cmd`` field is invalid.
diff --git a/Documentation/userspace-api/media/v4l/vidioc-enum-fmt.rst b/Documentation/userspace-api/media/v4l/vidioc-enum-fmt.rst
index a53dd3d..05835e0 100644
--- a/Documentation/userspace-api/media/v4l/vidioc-enum-fmt.rst
+++ b/Documentation/userspace-api/media/v4l/vidioc-enum-fmt.rst
@@ -167,17 +167,37 @@
- 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
+ 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.
+ 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. This flag is valid for stateful codecs only.
+ * - ``V4L2_FMT_FLAG_ENC_CAP_FRAME_INTERVAL``
+ - 0x0010
+ - The hardware encoder supports setting the ``CAPTURE`` coded frame
+ interval separately from the ``OUTPUT`` raw frame interval.
+ Setting the ``OUTPUT`` raw frame interval with :ref:`VIDIOC_S_PARM <VIDIOC_G_PARM>`
+ also sets the ``CAPTURE`` coded frame interval to the same value.
+ If this flag is set, then the ``CAPTURE`` coded frame interval can be
+ set to a different value afterwards. This is typically used for
+ offline encoding where the ``OUTPUT`` raw frame interval is used as
+ a hint for reserving hardware encoder resources and the ``CAPTURE`` coded
+ frame interval is the actual frame rate embedded in the encoded video
+ stream.
+
+ 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 encoders only.
Return Value
diff --git a/Documentation/userspace-api/media/v4l/vidioc-g-parm.rst b/Documentation/userspace-api/media/v4l/vidioc-g-parm.rst
index 42e9f6e..59e02ac 100644
--- a/Documentation/userspace-api/media/v4l/vidioc-g-parm.rst
+++ b/Documentation/userspace-api/media/v4l/vidioc-g-parm.rst
@@ -42,12 +42,13 @@
Description
===========
-The current video standard determines a nominal number of frames per
-second. If less than this number of frames is to be captured or output,
-applications can request frame skipping or duplicating on the driver
-side. This is especially useful when using the :ref:`read() <func-read>` or
-:ref:`write() <func-write>`, which are not augmented by timestamps or sequence
-counters, and to avoid unnecessary data copying.
+Applications can request a different frame interval. The capture or
+output device will be reconfigured to support the requested frame
+interval if possible. Optionally drivers may choose to skip or
+repeat frames to achieve the requested frame interval.
+
+For stateful encoders (see :ref:`encoder`) this represents the
+frame interval that is typically embedded in the encoded video stream.
Changing the frame interval shall never change the format. Changing the
format, on the other hand, may change the frame interval.
@@ -57,7 +58,8 @@
section discussing the :ref:`read() <func-read>` function.
To get and set the streaming parameters applications call the
-:ref:`VIDIOC_G_PARM <VIDIOC_G_PARM>` and :ref:`VIDIOC_S_PARM <VIDIOC_G_PARM>` ioctl, respectively. They take a
+:ref:`VIDIOC_G_PARM <VIDIOC_G_PARM>` and
+:ref:`VIDIOC_S_PARM <VIDIOC_G_PARM>` ioctl, respectively. They take a
pointer to a struct :c:type:`v4l2_streamparm` which contains a
union holding separate parameters for input and output devices.
@@ -113,14 +115,21 @@
* - struct :c:type:`v4l2_fract`
- ``timeperframe``
- This is the desired period between successive frames captured by
- the driver, in seconds. The field is intended to skip frames on
- the driver side, saving I/O bandwidth.
+ the driver, in seconds.
+ * - :cspan:`2`
+
+ This will configure the speed at which the video source (e.g. a sensor)
+ generates video frames. If the speed is fixed, then the driver may
+ choose to skip or repeat frames in order to achieve the requested
+ frame rate.
+
+ For stateful encoders (see :ref:`encoder`) this represents the
+ frame interval that is typically embedded in the encoded video stream.
Applications store here the desired frame period, drivers return
- the actual frame period, which must be greater or equal to the
- nominal frame period determined by the current video standard
- (struct :c:type:`v4l2_standard` ``frameperiod``
- field). Changing the video standard (also implicitly by switching
+ the actual frame period.
+
+ Changing the video standard (also implicitly by switching
the video input) may reset this parameter to the nominal frame
period. To reset manually applications can just set this field to
zero.
@@ -173,11 +182,15 @@
:ref:`write() <func-write>` mode (in streaming mode timestamps
can be used to throttle the output), saving I/O bandwidth.
+ For stateful encoders (see :ref:`encoder`) this represents the
+ frame interval that is typically embedded in the encoded video stream
+ and it provides a hint to the encoder of the speed at which raw
+ frames are queued up to the encoder.
+
Applications store here the desired frame period, drivers return
- the actual frame period, which must be greater or equal to the
- nominal frame period determined by the current video standard
- (struct :c:type:`v4l2_standard` ``frameperiod``
- field). Changing the video standard (also implicitly by switching
+ the actual frame period.
+
+ Changing the video standard (also implicitly by switching
the video output) may reset this parameter to the nominal frame
period. To reset manually applications can just set this field to
zero.
@@ -216,8 +229,8 @@
* - ``V4L2_CAP_TIMEPERFRAME``
- 0x1000
- - The frame skipping/repeating controlled by the ``timeperframe``
- field is supported.
+ - The frame period can be modified by setting the ``timeperframe``
+ field.
diff --git a/Documentation/userspace-api/media/v4l/vidioc-querycap.rst b/Documentation/userspace-api/media/v4l/vidioc-querycap.rst
index 666ac4d..9034736 100644
--- a/Documentation/userspace-api/media/v4l/vidioc-querycap.rst
+++ b/Documentation/userspace-api/media/v4l/vidioc-querycap.rst
@@ -168,11 +168,11 @@
- The device supports the :ref:`multi-planar API <planar-apis>`
through the :ref:`Video Output <output>` interface.
* - ``V4L2_CAP_VIDEO_M2M``
- - 0x00004000
+ - 0x00008000
- The device supports the single-planar API through the Video
Memory-To-Memory interface.
* - ``V4L2_CAP_VIDEO_M2M_MPLANE``
- - 0x00008000
+ - 0x00004000
- The device supports the :ref:`multi-planar API <planar-apis>`
through the Video Memory-To-Memory interface.
* - ``V4L2_CAP_VIDEO_OVERLAY``
diff --git a/Documentation/userspace-api/media/v4l/vidioc-reqbufs.rst b/Documentation/userspace-api/media/v4l/vidioc-reqbufs.rst
index b6d5208..75d894d 100644
--- a/Documentation/userspace-api/media/v4l/vidioc-reqbufs.rst
+++ b/Documentation/userspace-api/media/v4l/vidioc-reqbufs.rst
@@ -112,10 +112,17 @@
``V4L2_MEMORY_MMAP`` and ``type`` set to the buffer type. This will
free any previously allocated buffers, so this is typically something
that will be done at the start of the application.
+ * - union {
+ - (anonymous)
+ * - __u32
+ - ``flags``
+ - Specifies additional buffer management attributes.
+ See :ref:`memory-flags`.
* - __u32
- ``reserved``\ [1]
- - A place holder for future extensions. Drivers and applications
- must set the array to zero.
+ - Kept for backwards compatibility. Use ``flags`` instead.
+ * - }
+ -
.. tabularcolumns:: |p{6.1cm}|p{2.2cm}|p{8.7cm}|
@@ -126,6 +133,7 @@
.. _V4L2-BUF-CAP-SUPPORTS-REQUESTS:
.. _V4L2-BUF-CAP-SUPPORTS-ORPHANED-BUFS:
.. _V4L2-BUF-CAP-SUPPORTS-M2M-HOLD-CAPTURE-BUF:
+.. _V4L2-BUF-CAP-SUPPORTS-MMAP-CACHE-HINTS:
.. cssclass:: longtable
@@ -156,6 +164,15 @@
- Only valid for stateless decoders. If set, then userspace can set the
``V4L2_BUF_FLAG_M2M_HOLD_CAPTURE_BUF`` flag to hold off on returning the
capture buffer until the OUTPUT timestamp changes.
+ * - ``V4L2_BUF_CAP_SUPPORTS_MMAP_CACHE_HINTS``
+ - 0x00000040
+ - This capability is set by the driver to indicate that the queue supports
+ cache and memory management hints. However, it's only valid when the
+ queue is used for :ref:`memory mapping <mmap>` streaming I/O. See
+ :ref:`V4L2_FLAG_MEMORY_NON_CONSISTENT <V4L2-FLAG-MEMORY-NON-CONSISTENT>`,
+ :ref:`V4L2_BUF_FLAG_NO_CACHE_INVALIDATE <V4L2-BUF-FLAG-NO-CACHE-INVALIDATE>` and
+ :ref:`V4L2_BUF_FLAG_NO_CACHE_CLEAN <V4L2-BUF-FLAG-NO-CACHE-CLEAN>`.
+
Return Value
============
diff --git
