diff --git a/.clang-format b/.clang-format index a0a96088c74f49a961a80bc0851a84214b0a9f83..badfc1ba440afc1c87f056ee61c8e38105d60022 100644 --- a/.clang-format +++ b/.clang-format @@ -111,6 +111,7 @@ ForEachMacros: - 'css_for_each_descendant_pre' - 'device_for_each_child_node' - 'dma_fence_chain_for_each' + - 'do_for_each_ftrace_op' - 'drm_atomic_crtc_for_each_plane' - 'drm_atomic_crtc_state_for_each_plane' - 'drm_atomic_crtc_state_for_each_plane_state' @@ -136,6 +137,7 @@ ForEachMacros: - 'for_each_active_dev_scope' - 'for_each_active_drhd_unit' - 'for_each_active_iommu' + - 'for_each_aggr_pgid' - 'for_each_available_child_of_node' - 'for_each_bio' - 'for_each_board_func_rsrc' @@ -234,6 +236,7 @@ ForEachMacros: - 'for_each_node_state' - 'for_each_node_with_cpus' - 'for_each_node_with_property' + - 'for_each_nonreserved_multicast_dest_pgid' - 'for_each_of_allnodes' - 'for_each_of_allnodes_from' - 'for_each_of_cpu_node' @@ -256,6 +259,7 @@ ForEachMacros: - 'for_each_pci_dev' - 'for_each_pci_msi_entry' - 'for_each_pcm_streams' + - 'for_each_physmem_range' - 'for_each_populated_zone' - 'for_each_possible_cpu' - 'for_each_present_cpu' @@ -265,6 +269,8 @@ ForEachMacros: - 'for_each_process_thread' - 'for_each_property_of_node' - 'for_each_registered_fb' + - 'for_each_requested_gpio' + - 'for_each_requested_gpio_in_range' - 'for_each_reserved_mem_region' - 'for_each_rtd_codec_dais' - 'for_each_rtd_codec_dais_rollback' @@ -278,12 +284,17 @@ ForEachMacros: - 'for_each_sg' - 'for_each_sg_dma_page' - 'for_each_sg_page' + - 'for_each_sgtable_dma_page' + - 'for_each_sgtable_dma_sg' + - 'for_each_sgtable_page' + - 'for_each_sgtable_sg' - 'for_each_sibling_event' - 'for_each_subelement' - 'for_each_subelement_extid' - 'for_each_subelement_id' - '__for_each_thread' - 'for_each_thread' + - 'for_each_unicast_dest_pgid' - 'for_each_wakeup_source' - 'for_each_zone' - 'for_each_zone_zonelist' @@ -464,6 +475,7 @@ ForEachMacros: - 'v4l2_m2m_for_each_src_buf' - 'v4l2_m2m_for_each_src_buf_safe' - 'virtio_device_for_each_vq' + - 'while_for_each_ftrace_op' - 'xa_for_each' - 'xa_for_each_marked' - 'xa_for_each_range' diff --git a/.gitignore b/.gitignore index d5f4804ed07cd36336a5e80f2a24e45104f902cf..162bd2b67bdf6a28be7a361b8418e4e31d542854 100644 --- a/.gitignore +++ b/.gitignore @@ -44,6 +44,7 @@ *.tab.[ch] *.tar *.xz +*.zst Module.symvers modules.builtin modules.order diff --git a/.mailmap b/.mailmap index db4f2295bd9d792b47eb77aab179a9db0d968454..0894a8b4ba7d3dd6cd5e221a0dce78b1bb58ad16 100644 --- a/.mailmap +++ b/.mailmap @@ -2,37 +2,47 @@ # 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 Adam Oldham Adam Radford -Adrian Bunk Adriana Reus +Adrian Bunk Alan Cox Alan Cox -Aleksey Gorelov Aleksandar Markovic -Alex Shi -Alex Shi +Aleksey Gorelov +Alexander Lobakin +Alexander Lobakin +Alexander Lobakin Alexandre Belloni -Alexei Starovoitov Alexei Starovoitov Alexei Starovoitov +Alexei Starovoitov +Alex Shi +Alex Shi Al Viro Al Viro +Andi Kleen Andi Shyti Andreas Herrmann -Andrey Ryabinin Andrew Morton -Andrew Murray Andrew Murray +Andrew Murray Andrew Vasquez +Andrey Ryabinin Andy Adamson -Antoine Tenart +Antoine Tenart +Antoine Tenart Antonio Ospite Archit Taneja Ard Biesheuvel @@ -40,40 +50,42 @@ Arnaud Patard Arnd Bergmann Axel Dyks Axel Lin -Bart Van Assche Bart Van Assche +Bart Van Assche Ben Gardner Ben M Cahill Björn Steinbrink -Boris Brezillon -Boris Brezillon Boris Brezillon Boris Brezillon +Boris Brezillon +Boris Brezillon Brian Avery Brian King +Changbin Du +Changbin Du Chao Yu Chao Yu -Christoph Hellwig Christophe Ricard +Christoph Hellwig Corey Minyard Damian Hobson-Garcia -Daniel Borkmann -Daniel Borkmann +Daniel Borkmann Daniel Borkmann Daniel Borkmann -Daniel Borkmann +Daniel Borkmann +Daniel Borkmann Daniel Borkmann David Brownell David Woodhouse -Dengcheng Zhu -Dengcheng Zhu Dengcheng Zhu Dengcheng Zhu +Dengcheng Zhu +Dengcheng Zhu Dmitry Eremin-Solenikov -Dmitry Safonov <0x7f454c46@gmail.com> -Dmitry Safonov <0x7f454c46@gmail.com> Dmitry Safonov <0x7f454c46@gmail.com> +Dmitry Safonov <0x7f454c46@gmail.com> +Dmitry Safonov <0x7f454c46@gmail.com> Domen Puncer Douglas Gilbert Ed L. Cashin @@ -84,19 +96,22 @@ Felix Kuhling Felix Moeller Filipe Lautert Franck Bui-Huu -Frank Rowand Frank Rowand Frank Rowand +Frank Rowand Frank Zago Gao Xiang Gao Xiang -Gerald Schaefer Gerald Schaefer +Gerald Schaefer Gerald Schaefer Greg Kroah-Hartman Greg Kroah-Hartman Greg Kroah-Hartman +Greg Kurz Gregory CLEMENT +Gustavo Padovan +Gustavo Padovan Hanjun Guo Heiko Carstens Heiko Carstens @@ -106,34 +121,40 @@ Henrik Rydberg Herbert Xu Jacob Shin Jaegeuk Kim -Jaegeuk Kim Jaegeuk Kim +Jaegeuk Kim Jakub Kicinski James Bottomley James Bottomley James E Wilson -James Hogan James Hogan +James Hogan James Ketrenos Jan Glauber Jan Glauber Jan Glauber Jason Gunthorpe +Jason Gunthorpe Jason Gunthorpe -Javi Merino +Javi Merino Jayachandran C Jayachandran C Jayachandran C Jayachandran C -Jean Tourrilhes +Jean Tourrilhes Jeff Garzik -Jeff Layton Jeff Layton Jeff Layton +Jeff Layton Jens Axboe Jens Osterkamp +Jiri Slaby +Jiri Slaby +Jiri Slaby +Jiri Slaby +Jiri Slaby Johan Hovold Johan Hovold John Paul Adrian Glaubitz @@ -149,30 +170,37 @@ Juha Yrjola Julien Thierry Kamil Konieczny Kay Sievers +Kees Cook +Kees Cook +Kees Cook +Kees Cook Kenneth W Chen +Konstantin Khlebnikov Konstantin Khlebnikov Koushik -Krzysztof Kozlowski Krzysztof Kozlowski +Krzysztof Kozlowski Kuninori Morimoto -Leon Romanovsky -Leon Romanovsky Leonardo Bras Leonid I Ananiev +Leon Romanovsky +Leon Romanovsky +Leon Romanovsky Linas Vepstas -Linus Lüssing Linus Lüssing -Li Yang +Linus Lüssing + Li Yang +Li Yang Lukasz Luba Maciej W. Rozycki -Marc Zyngier Marcin Nowakowski +Marc Zyngier Mark Brown Mark Yao -Martin Kepplinger Martin Kepplinger Martin Kepplinger +Martin Kepplinger Mathieu Othacehe Matthew Wilcox Matthew Wilcox @@ -182,17 +210,17 @@ Matthew Wilcox Matthew Wilcox Matthew Wilcox Matthieu CASTET -Mauro Carvalho Chehab +Matt Ranostay +Matt Ranostay Matthew Ranostay +Matt Ranostay +Matt Redfearn Mauro Carvalho Chehab +Mauro Carvalho Chehab Mauro Carvalho Chehab +Mauro Carvalho Chehab Mauro Carvalho Chehab Mauro Carvalho Chehab -Mauro Carvalho Chehab Mauro Carvalho Chehab -Matt Ranostay Matthew Ranostay -Matt Ranostay -Matt Ranostay -Matt Redfearn Maxime Ripard Maxime Ripard Mayuresh Janorkar @@ -224,13 +252,13 @@ Paolo 'Blaisorblade' Giarrusso Patrick Mochel Paul Burton Paul Burton +Paul E. McKenney Paul E. McKenney Paul E. McKenney -Paul E. McKenney Paul E. McKenney Peter A Jonsson -Peter Oruba Peter Oruba +Peter Oruba Pratyush Anand Praveen BP Punit Agrawal @@ -243,23 +271,23 @@ Ralf Baechle Ralf Wildenhues Randy Dunlap Rémi Denis-Courmont -Ricardo Ribalda Ricardo Ribalda Ricardo Ribalda Ricardo Ribalda Delgado +Ricardo Ribalda Ross Zwisler Rudolf Marek Rui Saraiva Sachin P Sant -Sarangdhar Joshi +Sakari Ailus Sam Ravnborg -Santosh Shilimkar Santosh Shilimkar +Santosh Shilimkar +Sarangdhar Joshi Sascha Hauer S.Çağlar Onur -Sakari Ailus Sean Nyekjaer -Sebastian Reichel Sebastian Reichel +Sebastian Reichel Sedat Dilek Shiraz Hashim Shuah Khan @@ -270,19 +298,23 @@ Simon Arlott Simon Kelley Stéphane Witzmann Stephen Hemminger +Steve Wise +Steve Wise Subash Abhinov Kasiviswanathan Subhash Jadavani Sudeep Holla Sudeep KarkadaNagesha Sumit Semwal +Takashi YOSHII Tejun Heo Thomas Graf Thomas Pedersen Tiezhu Yang Todor Tomov Tony Luck -TripleX Chung TripleX Chung +TripleX Chung Tsuneo Yoshioka +Tycho Andersen Uwe Kleine-König Uwe Kleine-König Uwe Kleine-König @@ -290,22 +322,16 @@ Valdis Kletnieks Vinod Koul Vinod Koul Vinod Koul +Viresh Kumar Viresh Kumar Viresh Kumar -Viresh Kumar Vivien Didelot Vlad Dogaru -Vladimir Davydov Vladimir Davydov -Takashi YOSHII +Vladimir Davydov +WeiXiong Liao Will Deacon -Wolfram Sang Wolfram Sang +Wolfram Sang Yakir Yang Yusuke Goda -Gustavo Padovan -Gustavo Padovan -Changbin Du -Changbin Du -Steve Wise -Steve Wise diff --git a/CREDITS b/CREDITS index 0787b5872906c8a92a63cde3961ed630e2ec93b6..32ee70a7562eec7345e98841473abb438379a4fd 100644 --- a/CREDITS +++ b/CREDITS @@ -34,7 +34,7 @@ S: Romania 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 @@ S: United Kingdom 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 @@ S: USA 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 @@ S: Canada K2P 0X3 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 @@ S: USA 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 @@ S: Haifa, Israel 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 @@ D: Original author of the Linux networking code 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 @@ S: Sweden 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 @@ D: Broadcom B43 driver 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 @@ D: Promise DC4030VL caching HD controller drivers 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 @@ S: USA 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 @@ S: USA 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 @@ S: Germany 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 @@ S: The Netherlands 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 @@ S: Germany 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 @@ S: USA 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 @@ E: kas@fi.muni.cz 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 @@ S: Prague, Czech Republic 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 @@ D: Original author of software suspend 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 @@ S: Finland 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 @@ D: bug fixes, documentation, minor hackery 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 @@ N: David C. Niemi 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 @@ S: USA 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 @@ D: RFC2385 Support for TCP 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 @@ S: United Kingdom 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 @@ S: France 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 @@ S: Germany 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 @@ S: Germany 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 @@ S: Australia 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 @@ S: USA 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 @@ S: France 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 @@ S: Canada K2L 1S2 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 @@ D: The Linux Support Team Erlangen 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 @@ S: USA 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 b5bebf642db697de112be8a4bd3d21b49ab9afb3..1af9c41752135d2eec9523acd6aec54dbd2b582a 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/version +What: /sys/bus/dsa/devices/dsa/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/cdev_major +What: /sys/bus/dsa/devices/dsa/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/errors +What: /sys/bus/dsa/devices/dsa/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/max_batch_size +What: /sys/bus/dsa/devices/dsa/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/max_work_queues_size +What: /sys/bus/dsa/devices/dsa/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/max_engines +What: /sys/bus/dsa/devices/dsa/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/max_groups +What: /sys/bus/dsa/devices/dsa/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/max_tokens +What: /sys/bus/dsa/devices/dsa/max_tokens Date: Oct 25, 2019 KernelVersion: 5.6.0 Contact: dmaengine@vger.kernel.org @@ -50,7 +50,7 @@ Description: The total number of bandwidth tokens supported by this device. implementation, and these resources are allocated by engines to support operations. -What: sys/bus/dsa/devices/dsa/max_transfer_size +What: /sys/bus/dsa/devices/dsa/max_transfer_size Date: Oct 25, 2019 KernelVersion: 5.6.0 Contact: dmaengine@vger.kernel.org @@ -58,57 +58,57 @@ Description: The number of bytes to be read from the source address to perform the operation. The maximum transfer size is dependent on the workqueue the descriptor was submitted to. -What: sys/bus/dsa/devices/dsa/max_work_queues +What: /sys/bus/dsa/devices/dsa/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/numa_node +What: /sys/bus/dsa/devices/dsa/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/op_cap +What: /sys/bus/dsa/devices/dsa/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/state +What: /sys/bus/dsa/devices/dsa/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/group. +What: /sys/bus/dsa/devices/dsa/group. 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/engine. +What: /sys/bus/dsa/devices/dsa/engine. 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/wq. +What: /sys/bus/dsa/devices/dsa/wq. 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/configurable +What: /sys/bus/dsa/devices/dsa/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/token_limit +What: /sys/bus/dsa/devices/dsa/token_limit Date: Oct 25, 2019 KernelVersion: 5.6.0 Contact: dmaengine@vger.kernel.org @@ -116,19 +116,19 @@ Description: The maximum number of bandwidth tokens that may be in use at one time by operations that access low bandwidth memory in the device. -What: sys/bus/dsa/devices/wq./group_id +What: /sys/bus/dsa/devices/wq./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./size +What: /sys/bus/dsa/devices/wq./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./type +What: /sys/bus/dsa/devices/wq./type Date: Oct 25, 2019 KernelVersion: 5.6.0 Contact: dmaengine@vger.kernel.org @@ -136,20 +136,20 @@ Description: The type of this work queue, it can be "kernel" type for work queue usages in the kernel space or "user" type for work queue usages by applications in user space. -What: sys/bus/dsa/devices/wq./cdev_minor +What: /sys/bus/dsa/devices/wq./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./mode +What: /sys/bus/dsa/devices/wq./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./priority +What: /sys/bus/dsa/devices/wq./priority Date: Oct 25, 2019 KernelVersion: 5.6.0 Contact: dmaengine@vger.kernel.org @@ -157,20 +157,20 @@ Description: The priority value of this work queue, it is a vlue relative to 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./state +What: /sys/bus/dsa/devices/wq./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./threshold +What: /sys/bus/dsa/devices/wq./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./group_id +What: /sys/bus/dsa/devices/engine./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 b0d90cc696a83dd66732fa9ceb687b8f73892726..fd9a8045bb0c56477730bbdcf1aed3456a806fbd 100644 --- a/Documentation/ABI/stable/sysfs-driver-mlxreg-io +++ b/Documentation/ABI/stable/sysfs-driver-mlxreg-io @@ -206,3 +206,20 @@ Description: This file exposes the firmware version of burnable voltage 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 +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-turris-mox-rwtm b/Documentation/ABI/testing/debugfs-turris-mox-rwtm new file mode 100644 index 0000000000000000000000000000000000000000..2b3255ee68fd62a37eabb2d9c90637150db822f8 --- /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 +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 f307506eb54ce9a44601ba37ba798314049da762..3c0bb76e3417e7ce402378e849d4ee7858ae019c 100644 --- a/Documentation/ABI/testing/dev-kmsg +++ b/Documentation/ABI/testing/dev-kmsg @@ -56,6 +56,17 @@ Description: The /dev/kmsg character device node provides userspace access seek after the last record available at the time the last SYSLOG_ACTION_CLEAR was issued. + 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 sequence number and the monotonic timestamp in microseconds, diff --git a/Documentation/ABI/testing/sysfs-block b/Documentation/ABI/testing/sysfs-block index ed8c14f161ee3cbc2bb21760ccd1ff9b9ea4bb9a..2322eb748b38774b2936d5411cafa091fef644ab 100644 --- a/Documentation/ABI/testing/sysfs-block +++ b/Documentation/ABI/testing/sysfs-block @@ -273,6 +273,24 @@ Description: device ("host-aware" or "host-managed" zone model). For regular block devices, the value is always 0. +What: /sys/block//queue/max_active_zones +Date: July 2020 +Contact: Niklas Cassel +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//queue/max_open_zones +Date: July 2020 +Contact: Niklas Cassel +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//queue/chunk_sectors Date: September 2016 Contact: Hannes Reinecke 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 e8698afcd952a57d307699e83f197b18682b7c1d..e82fc37be80225bfe386c75c9e2d1c8bdea4f914 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 @@ Description: read only This sysfs interface exposes the number of cores per chip present in the system. +What: /sys/devices/hv_24x7/cpumask +Date: July 2020 +Contact: Linux on PowerPC Developer List +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/ Date: February 2014 Contact: Linux on PowerPC Developer List diff --git a/Documentation/ABI/testing/sysfs-bus-iio-icm42600 b/Documentation/ABI/testing/sysfs-bus-iio-icm42600 new file mode 100644 index 0000000000000000000000000000000000000000..0bf1fd4f5bf1498846ba830f8461b192c461d8a4 --- /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 0000000000000000000000000000000000000000..b9712f390bec4770c64cafe0d23670f214287fdc --- /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 a1cb44dcb90808201f58d18f9006a229a9be8296..e4f76e7eab938cff005f78518b2326833bb9d6b7 100644 --- a/Documentation/ABI/testing/sysfs-bus-nfit +++ b/Documentation/ABI/testing/sysfs-bus-nfit @@ -202,6 +202,25 @@ Description: 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 0000000000000000000000000000000000000000..d64380262be8cffa9bcbce619ae3818210ac8a72 --- /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 0000000000000000000000000000000000000000..0f58701367b66a57201e4a1bf1520cc069cc4122 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-bus-optee-devices @@ -0,0 +1,8 @@ +What: /sys/bus/tee/devices/optee-ta-/ +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 + matches Trusted Application (TA) driver and corresponding TA in secure OS. Drivers + are free to create needed API under optee-ta- directory. diff --git a/Documentation/ABI/testing/sysfs-bus-papr-pmem b/Documentation/ABI/testing/sysfs-bus-papr-pmem index 5b10d036a8d430282f12e5f6fc91b7fb70549c54..c1a67275c43f84623959575a6fddf8fd8e5c3c64 100644 --- a/Documentation/ABI/testing/sysfs-bus-papr-pmem +++ b/Documentation/ABI/testing/sysfs-bus-papr-pmem @@ -25,3 +25,30 @@ Description: 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 , 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 5172a6124b27f8c1e406a610c794611ee5998a90..194ca700e96297823ecb74db46b621e4636c42a4 100644 --- a/Documentation/ABI/testing/sysfs-bus-platform +++ b/Documentation/ABI/testing/sysfs-bus-platform @@ -18,3 +18,13 @@ Description: 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 +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 82e80de78dd00d8f7806637b0c44c2395597259d..dd565c378b4032f18b1e528f6b3c0bdc6e5e0939 100644 --- a/Documentation/ABI/testing/sysfs-bus-thunderbolt +++ b/Documentation/ABI/testing/sysfs-bus-thunderbolt @@ -178,11 +178,18 @@ KernelVersion: 4.13 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 @@ KernelVersion: 4.15 Contact: thunderbolt-software@lists.01.org Description: This contains XDomain service specific settings as bitmask. Format: %x + +What: /sys/bus/thunderbolt/devices/:./device +Date: Oct 2020 +KernelVersion: v5.9 +Contact: Mika Westerberg +Description: Retimer device identifier read from the hardware. + +What: /sys/bus/thunderbolt/devices/:./nvm_authenticate +Date: Oct 2020 +KernelVersion: v5.9 +Contact: Mika Westerberg +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/:./nvm_version +Date: Oct 2020 +KernelVersion: v5.9 +Contact: Mika Westerberg +Description: Holds retimer NVM version number. Format: %x.%x, major.minor. + +What: /sys/bus/thunderbolt/devices/:./vendor +Date: Oct 2020 +KernelVersion: v5.9 +Contact: Mika Westerberg +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 +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 9758eb85ade3ea461787f2707c14eb400df5a660..deefffb3bbe45dba1c855e3525c739363afed0f6 100644 --- a/Documentation/ABI/testing/sysfs-class-devfreq +++ b/Documentation/ABI/testing/sysfs-class-devfreq @@ -108,3 +108,15 @@ Description: 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 +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 0000000000000000000000000000000000000000..64791b65c9a384279aab2d6f7206ef7c721a85af --- /dev/null +++ b/Documentation/ABI/testing/sysfs-class-devlink @@ -0,0 +1,126 @@ +What: /sys/class/devlink/.../ +Date: May 2020 +Contact: Saravana Kannan +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 -- + where is the supplier device name and is + the consumer device name. + +What: /sys/class/devlink/.../auto_remove_on +Date: May 2020 +Contact: Saravana Kannan +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 +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 +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 +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 +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 +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 0000000000000000000000000000000000000000..795a5de12fc139f59245df6f15efd09bd01f1f49 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-class-led-driver-turris-omnia @@ -0,0 +1,14 @@ +What: /sys/class/leds//device/brightness +Date: July 2020 +KernelVersion: 5.9 +Contact: Marek Behún +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 0000000000000000000000000000000000000000..eeeddcbdbbe3373a26328c6407550e6964fa9d22 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-class-led-multicolor @@ -0,0 +1,35 @@ +What: /sys/class/leds//brightness +Date: March 2020 +KernelVersion: 5.9 +Contact: Dan Murphy +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//max_brightness. + +What: /sys/class/leds//multi_index +Date: March 2020 +KernelVersion: 5.9 +Contact: Dan Murphy +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//multi_intensity +Date: March 2020 +KernelVersion: 5.9 +Contact: Dan Murphy +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//max_brightness. diff --git a/Documentation/ABI/testing/sysfs-class-mei b/Documentation/ABI/testing/sysfs-class-mei index e9dc110650ae0f89dbb0a4699e2e4c0bedc8d043..5c52372b43cbd3266c3b3b08eec28daa4ead881d 100644 --- a/Documentation/ABI/testing/sysfs-class-mei +++ b/Documentation/ABI/testing/sysfs-class-mei @@ -90,3 +90,16 @@ Description: Display trc status register content 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 +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 b5b1fa197592eb999241a4d7d0f3cdb6dd918b59..ae1276efa45a2562866893abb49739d5997de474 100644 --- a/Documentation/ABI/testing/sysfs-class-ocxl +++ b/Documentation/ABI/testing/sysfs-class-ocxl @@ -33,3 +33,14 @@ Date: January 2018 Contact: linuxppc-dev@lists.ozlabs.org Description: read/write Give access the global mmio area for the AFU + +What: /sys/class/ocxl//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 216d61a22f1e72cadb1961fc3ad8a774fcb7395d..40213c73bc9c45388085367c062b933adbfce163 100644 --- a/Documentation/ABI/testing/sysfs-class-power +++ b/Documentation/ABI/testing/sysfs-class-power @@ -205,7 +205,8 @@ Description: 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//precharge_current Date: June 2017 diff --git a/Documentation/ABI/testing/sysfs-class-power-wilco b/Documentation/ABI/testing/sysfs-class-power-wilco index da1d6ffe5e3ce8eb0a8287158726fa934f651e65..84fde1d0ada065e1fd972acaea4eef4d8c4b7b73 100644 --- a/Documentation/ABI/testing/sysfs-class-power-wilco +++ b/Documentation/ABI/testing/sysfs-class-power-wilco @@ -14,6 +14,10 @@ Description: 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 0000000000000000000000000000000000000000..1f06d74d1c3ccca76cb67e48c456d269ca3b2435 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-devices-consumer @@ -0,0 +1,8 @@ +What: /sys/devices/.../consumer: +Date: May 2020 +Contact: Saravana Kannan +Description: + The /sys/devices/.../consumer: are symlinks to device + links where this device is the supplier. 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 0000000000000000000000000000000000000000..490ccfd67f125a005cc411bda7496018938691e3 --- /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 +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 ae9af984471a87c1565427bd0cb36ae1cbf04395..a8daceb4a95655b605c37904578b5abcfdcbbfb3 100644 --- a/Documentation/ABI/testing/sysfs-devices-platform-stratix10-rsu +++ b/Documentation/ABI/testing/sysfs-devices-platform-stratix10-rsu @@ -126,3 +126,39 @@ Description: 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 +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 +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 +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 +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 +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 ba3a3fac0ee11002076eb8ebac935016d8b5c185..ea999e292f11140408ae8b3f87b0f32523e7111f 100644 --- a/Documentation/ABI/testing/sysfs-devices-soc +++ b/Documentation/ABI/testing/sysfs-devices-soc @@ -26,6 +26,30 @@ Description: 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 @@ -40,6 +64,12 @@ Description: 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 diff --git a/Documentation/ABI/testing/sysfs-devices-state_synced b/Documentation/ABI/testing/sysfs-devices-state_synced new file mode 100644 index 0000000000000000000000000000000000000000..0c922d7d02fc275853e67ec66f0671198dd6881e --- /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 +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 0000000000000000000000000000000000000000..a919e0db5e902ca572ddde6560663a2ef05ad15d --- /dev/null +++ b/Documentation/ABI/testing/sysfs-devices-supplier @@ -0,0 +1,8 @@ +What: /sys/devices/.../supplier: +Date: May 2020 +Contact: Saravana Kannan +Description: + The /sys/devices/.../supplier: are symlinks to device + links where this device is the consumer. 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 0000000000000000000000000000000000000000..59d073d20db653b9baecbfe141992cfb43400345 --- /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 +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 0000000000000000000000000000000000000000..3d316d54f81c22a83a289a82c11c91cf48e5cb49 --- /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 016724ec26d5a08c971eb981e2e9ded35af378f1..d1a352194d2eaf65d2d8ca435885bbded5424e6a 100644 --- a/Documentation/ABI/testing/sysfs-driver-ufs +++ b/Documentation/ABI/testing/sysfs-driver-ufs @@ -883,3 +883,139 @@ Contact: Subhash Jadavani 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 +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 +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 +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 +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 +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 +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 +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 +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 +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 +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 +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 +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 +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 +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 +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 +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 076659d506f269035449a0dd29521d6d1cc992e7..9b488c0afdfa289dd3cdfa1d3c8b4257bf607cd5 100644 --- a/Documentation/ABI/testing/sysfs-driver-w1_therm +++ b/Documentation/ABI/testing/sysfs-driver-w1_therm @@ -8,7 +8,7 @@ Description: 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 4bb93a06d8abc52bb3cc6e5bc38005c202294d10..7f730c4c8df225ed07335a529678cd05b9248f99 100644 --- a/Documentation/ABI/testing/sysfs-fs-f2fs +++ b/Documentation/ABI/testing/sysfs-fs-f2fs @@ -229,7 +229,9 @@ Date: August 2017 Contact: "Jaegeuk Kim" 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//gc_urgent_sleep_time Date: August 2017 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 0000000000000000000000000000000000000000..57ee866fb165f0c5bacd8cc06735cc5a0ead8de7 --- /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 cd76ba47394bd7ec25e433ef3c3e65abd9d4c162..0000000000000000000000000000000000000000 --- 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 d114ea74b444b76effa32f827e3c16b85b069310..4ca7439fbfc9b07aa1b96e7b208ac5d88f8b4a73 100644 --- a/Documentation/PCI/endpoint/index.rst +++ b/Documentation/PCI/endpoint/index.rst @@ -11,3 +11,5 @@ PCI Endpoint Framework 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 b6d39cdec56ef79781244ef71005e116e6a85eb9..1bbd81ed06c8f7321060e78fcaf748f36efee807 100644 --- a/Documentation/PCI/endpoint/pci-endpoint-cfs.rst +++ b/Documentation/PCI/endpoint/pci-endpoint-cfs.rst @@ -24,7 +24,7 @@ Directory Structure 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 7536be445db888499dbfd7ea527289d14a10fe6b..4f5622a655557d38d259008dbdfbf75be88f5253 100644 --- a/Documentation/PCI/endpoint/pci-endpoint.rst +++ b/Documentation/PCI/endpoint/pci-endpoint.rst @@ -214,7 +214,7 @@ pci-ep-cfs.c can be used as reference for using these APIs. * 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 13beee23cb04fbf330994527a4e8f94128b61783..84ceebb08cac1ac1d4a09d657fdadbfcaadf2554 100644 --- a/Documentation/PCI/pci-error-recovery.rst +++ b/Documentation/PCI/pci-error-recovery.rst @@ -79,7 +79,7 @@ This structure has the form:: 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 @@ This structure has the form:: 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 @@ STEP 4: Slot Reset ------------------ 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 @@ STEP 6: Permanent Failure ------------------------- 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 8c016d8c986232d61971ee655180c9df35739db1..814b40f8360b20915dc25ada04dde069a52d2998 100644 --- a/Documentation/PCI/pci.rst +++ b/Documentation/PCI/pci.rst @@ -17,7 +17,7 @@ PCI device drivers. 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 @@ the PCI device by calling pci_enable_device(). This will: 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 @@ Set the DMA mask size --------------------- .. 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 @@ Many 64-bit "PCI" devices (before PCI-X) and some PCI-X devices are 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 @@ owners if there is one. 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 @@ your driver if they're helpful, or just use plain hex constants. 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 75b8ca007a11c4c9a06b4d579cd704e25eed7535..8f41ad0aa75347f5d75f8d7f949d612126006123 100644 --- a/Documentation/RCU/Design/Requirements/Requirements.rst +++ b/Documentation/RCU/Design/Requirements/Requirements.rst @@ -463,7 +463,7 @@ again without disrupting RCU readers. 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 @@ not work to have these markers in the trampoline itself, because there 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 `__, is to have implicit read-side diff --git a/Documentation/RCU/checklist.rst b/Documentation/RCU/checklist.rst new file mode 100644 index 0000000000000000000000000000000000000000..2efed9926c3f9039d151ceb1bcca96bf381ab543 --- /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 e98ff261a438bd4e0858a943fc469437599cc284..0000000000000000000000000000000000000000 --- 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 81a0a1e5f767e870c3daaeffbd67ca2bbc958071..e703d3dbe60ce572324e4a1616e4d8e4ae01ff2d 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 @@ RCU concepts :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 0000000000000000000000000000000000000000..2a5c79db57dc87f28bb93e6deab72de97e5c6d47 --- /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: [] + scsi_scan_host_selected+0x5a/0x150 + #1: (&eq->sysfs_lock){+.+.}, at: [] + elevator_exit+0x22/0x60 + #2: (&(&q->__queue_lock)->rlock){-.-.}, at: [] + cfq_exit_queue+0x43/0x190 + + stack backtrace: + Pid: 1552, comm: scsi_scan_6 Not tainted 3.0.0-rc5 #17 + Call Trace: + [] lockdep_rcu_dereference+0xbb/0xc0 + [] __cfq_exit_single_io_context+0xe9/0x120 + [] cfq_exit_queue+0x7c/0x190 + [] elevator_exit+0x36/0x60 + [] blk_cleanup_queue+0x4a/0x60 + [] scsi_free_queue+0x9/0x10 + [] __scsi_remove_device+0x84/0xd0 + [] scsi_probe_and_add_lun+0x353/0xb10 + [] ? error_exit+0x29/0xb0 + [] ? _raw_spin_unlock_irqrestore+0x3d/0x80 + [] __scsi_scan_target+0x112/0x680 + [] ? trace_hardirqs_off_thunk+0x3a/0x3c + [] ? error_exit+0x29/0xb0 + [] ? kobject_del+0x40/0x40 + [] scsi_scan_channel+0x86/0xb0 + [] scsi_scan_host_selected+0x140/0x150 + [] do_scsi_scan_host+0x89/0x90 + [] do_scan_async+0x20/0x160 + [] ? do_scsi_scan_host+0x90/0x90 + [] kthread+0xa6/0xb0 + [] kernel_thread_helper+0x4/0x10 + [] ? finish_task_switch+0x80/0x110 + [] ? retint_restore_args+0xe/0xe + [] ? __kthread_init_worker+0x70/0x70 + [] ? 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 b8096316fd116228b5323357b5eb879bb3dc1a45..0000000000000000000000000000000000000000 --- 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: [] -scsi_scan_host_selected+0x5a/0x150 - #1: (&eq->sysfs_lock){+.+.}, at: [] -elevator_exit+0x22/0x60 - #2: (&(&q->__queue_lock)->rlock){-.-.}, at: [] -cfq_exit_queue+0x43/0x190 - -stack backtrace: -Pid: 1552, comm: scsi_scan_6 Not tainted 3.0.0-rc5 #17 -Call Trace: - [] lockdep_rcu_dereference+0xbb/0xc0 - [] __cfq_exit_single_io_context+0xe9/0x120 - [] cfq_exit_queue+0x7c/0x190 - [] elevator_exit+0x36/0x60 - [] blk_cleanup_queue+0x4a/0x60 - [] scsi_free_queue+0x9/0x10 - [] __scsi_remove_device+0x84/0xd0 - [] scsi_probe_and_add_lun+0x353/0xb10 - [] ? error_exit+0x29/0xb0 - [] ? _raw_spin_unlock_irqrestore+0x3d/0x80 - [] __scsi_scan_target+0x112/0x680 - [] ? trace_hardirqs_off_thunk+0x3a/0x3c - [] ? error_exit+0x29/0xb0 - [] ? kobject_del+0x40/0x40 - [] scsi_scan_channel+0x86/0xb0 - [] scsi_scan_host_selected+0x140/0x150 - [] do_scsi_scan_host+0x89/0x90 - [] do_scan_async+0x20/0x160 - [] ? do_scsi_scan_host+0x90/0x90 - [] kthread+0xa6/0xb0 - [] kernel_thread_helper+0x4/0x10 - [] ? finish_task_switch+0x80/0x110 - [] ? retint_restore_args+0xe/0xe - [] ? __kthread_init_worker+0x70/0x70 - [] ? 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 0000000000000000000000000000000000000000..cc860a0c296be1bdb3f57ac79fa10dbe30fd99db --- /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 89db949eeca0d1eb1a9d96db154b84efd616c299..0000000000000000000000000000000000000000 --- 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 0000000000000000000000000000000000000000..a9fc774bc400080ba78bd1fd334f8e6eff12b3f1 --- /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 23f115dc87cf9bb832e94f5373df0b41c07013fd..0000000000000000000000000000000000000000 --- 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 0000000000000000000000000000000000000000..b33aeb14fde343647ef5cdf59d3f9687d2c6b5b7 --- /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 5e6429d66c2425b8b94b6d78fbcdb8f527586657..0000000000000000000000000000000000000000 --- 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 0000000000000000000000000000000000000000..c9ab6af4d3be9a00f4e57c956c6c109a989961c7 --- /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 a360a8796710a2c7e7d5c7571d7562a83c4d86ef..0000000000000000000000000000000000000000 --- 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 0000000000000000000000000000000000000000..a9014771306292f305dc2b3df6f21f9846e85764 --- /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 af712a3c5b6a56f4e311649037c1e78b8f935b06..0000000000000000000000000000000000000000 --- 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 d0a060de397399cafad54e865d4f99ce457da902..d9cd937ebd2d1f2d1721bd10d0871d6cae6a8206 100644 --- a/Documentation/admin-guide/LSM/Yama.rst +++ b/Documentation/admin-guide/LSM/Yama.rst @@ -19,9 +19,10 @@ attach to other running processes (e.g. Firefox, SSH sessions, GPG agent, 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 +`_ +and `arbitrary code injection +`_ 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/blockdev/drbd/index.rst b/Documentation/admin-guide/blockdev/drbd/index.rst index 68ecd5c113e9c07fab68af0a602fb92640c19846..561fd1e3591784a5a45faa726c885bb6fd155cdd 100644 --- a/Documentation/admin-guide/blockdev/drbd/index.rst +++ b/Documentation/admin-guide/blockdev/drbd/index.rst @@ -10,7 +10,7 @@ Description 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 4a8f31cf41398647f6a75254aeb62137a546f4ae..0328438ebe2ce2d5bf8df13912a578816b839b4c 100644 --- a/Documentation/admin-guide/blockdev/floppy.rst +++ b/Documentation/admin-guide/blockdev/floppy.rst @@ -6,7 +6,7 @@ FAQ list: ========= A FAQ list may be found in the fdutils package (see below), and also -at . +at . LILO configuration options (Thinkpad users, read this) @@ -220,11 +220,11 @@ It also contains additional documentation about the floppy driver. 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 d6b3b77a412966c441997ee9efdb54a7360ef983..a22024f9175e70f64898ff3ff4a5d123b3188752 100644 --- a/Documentation/admin-guide/bootconfig.rst +++ b/Documentation/admin-guide/bootconfig.rst @@ -71,6 +71,16 @@ For example,:: 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 @@ For example, following config is NOT allowed.:: 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 2fcb0a9bf790bf665da7ee34a8997bb449d02a38..e69369b7252ea390d79c21294565709cd126296e 100644 --- a/Documentation/admin-guide/cgroup-v1/rdma.rst +++ b/Documentation/admin-guide/cgroup-v1/rdma.rst @@ -114,4 +114,4 @@ Following resources can be accounted by rdma controller. (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 d09471aa74434ba6d2cd07e01afc3ab3a503849d..baa07b30845e270eb5ecd57ee679bb62b82f9d07 100644 --- a/Documentation/admin-guide/cgroup-v2.rst +++ b/Documentation/admin-guide/cgroup-v2.rst @@ -1274,6 +1274,10 @@ PAGE_SIZE multiple when read back. 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 @@ -1320,15 +1324,26 @@ PAGE_SIZE multiple when read back. pgmajfault Number of major page faults incurred - workingset_refault - Number of refaults of previously evicted pages + workingset_refault_anon + Number of refaults of previously evicted anonymous pages. + + workingset_refault_file + Number of refaults of previously evicted file pages. + + workingset_activate_anon + Number of refaulted anonymous pages that were immediately + activated. - workingset_activate - Number of refaulted pages that were immediately activated + workingset_activate_file + Number of refaulted file pages that were immediately activated. - workingset_restore - Number of restored pages which have been detected as an active - workingset before they got reclaimed. + workingset_restore_anon + Number of restored anonymous pages which have been detected as + an active workingset before they got reclaimed. + + workingset_restore_file + Number of restored file pages which have been detected as an + active workingset before they got reclaimed. workingset_nodereclaim Number of times a shadow node has been reclaimed @@ -1483,8 +1498,7 @@ IO Interface Files ~~~~~~~~~~~~~~~~~~ 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 +1698,9 @@ per-cgroup dirty memory states are examined and the more restrictive 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 +2057,7 @@ RDMA ---- 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 084c25f92dcb00fb43e879453e2443a8a2eef0a0..25f11576e7b91120aa2480e6a0d6ccc1f4fe3a7f 100644 --- a/Documentation/admin-guide/cifs/todo.rst +++ b/Documentation/admin-guide/cifs/todo.rst @@ -98,7 +98,7 @@ x) Finish support for SMB3.1.1 compression 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 d3fb67b8a976068cad41b37b2b3592576479f686..7b32d50638039183f7487d1968c39f6fb0adf9d7 100644 --- a/Documentation/admin-guide/cifs/usage.rst +++ b/Documentation/admin-guide/cifs/usage.rst @@ -16,8 +16,7 @@ standard for interoperating between Macs and Windows and major NAS appliances. Please see MS-SMB2 (for detailed SMB2/SMB3/SMB3.1.1 protocol specification) -http://protocolfreedom.org/ and -http://samba.org/samba/PFIF/ +or https://samba.org/samba/PFIF/ for more details. @@ -32,7 +31,7 @@ Build instructions 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 @@ the active sessions and the shares that are mounted. Enabling Kerberos (extended security) works but requires version 1.2 or later of the helper program cifs.upcall to be present and to be configured in the /etc/request-key.conf file. The cifs.upcall helper program is from the Samba -project(http://www.samba.org). NTLM and NTLMv2 and LANMAN support do not +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 322a9c833f2304b1c2fb1c1450f780ae975692c3..993186beea206324474a1a0bd2218c961165e34a 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 . +# along with this program. If not, see . # while(<>) { diff --git a/Documentation/admin-guide/dell_rbu.rst b/Documentation/admin-guide/dell_rbu.rst index 8d70e1fc9f9dc375a5553694d177a8b7018f5f64..2196caf1b939c77a22d7c0f041c21bfac374bfb3 100644 --- a/Documentation/admin-guide/dell_rbu.rst +++ b/Documentation/admin-guide/dell_rbu.rst @@ -26,7 +26,7 @@ Please go to http://support.dell.com register and you can find info on 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-crypt.rst b/Documentation/admin-guide/device-mapper/dm-crypt.rst index 8f4a3f889d43ee50c47b5316c176a81ae106ae13..bc28a9527ee55f87d3d145e9cac97a3896d6e017 100644 --- a/Documentation/admin-guide/device-mapper/dm-crypt.rst +++ b/Documentation/admin-guide/device-mapper/dm-crypt.rst @@ -67,7 +67,7 @@ Parameters:: the value passed in . - Either 'logon' or 'user' kernel key type. + Either 'logon', 'user' or 'encrypted' kernel key type. The kernel keyring key description crypt target should look for @@ -121,6 +121,14 @@ submit_from_crypt_cpus thread because it benefits CFQ to have writes submitted using the same context. +no_read_workqueue + Bypass dm-crypt internal workqueue and process read requests synchronously. + +no_write_workqueue + Bypass dm-crypt internal workqueue and process write requests synchronously. + This option is automatically enabled for host-managed zoned block devices + (e.g. host-managed SMR hard-disks). + integrity:: The device requires additional metadata per-sector stored in per-bio integrity structure. This metadata must by provided diff --git a/Documentation/admin-guide/device-mapper/dm-dust.rst b/Documentation/admin-guide/device-mapper/dm-dust.rst index b6e7e7ead831a723445de2ebf834cc79cf9f6f14..e35ec8cd2f88aeea36cfb08e69847ea587922eda 100644 --- a/Documentation/admin-guide/device-mapper/dm-dust.rst +++ b/Documentation/admin-guide/device-mapper/dm-dust.rst @@ -69,10 +69,11 @@ Create the dm-dust device: $ 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 @@ following message command:: 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 @@ following message command:: 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 @@ following message command:: 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 @@ Single argument message commands:: 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 9edd45593abd52bbb622df47717ceb1be671be8e..3ab4f7756a6e635ce8e18f40c9764ea65f188327 100644 --- a/Documentation/admin-guide/device-mapper/dm-integrity.rst +++ b/Documentation/admin-guide/device-mapper/dm-integrity.rst @@ -45,7 +45,7 @@ To use the target for the first time: 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 @@ interleave_sectors:number 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 695a2ea1d1ae2a3ed7a5309babff0537bce2a5ea..7ef9fe63b3d4873a22c354274ed71447f15ee075 100644 --- a/Documentation/admin-guide/device-mapper/dm-raid.rst +++ b/Documentation/admin-guide/device-mapper/dm-raid.rst @@ -71,7 +71,7 @@ The target is named "raid" and it accepts the following parameters:: ============= =============================================================== 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 553752ea2521103eaad9181064ffd463ea98ab5e..e635041351bc779afe9906780937707969d292be 100644 --- a/Documentation/admin-guide/device-mapper/dm-zoned.rst +++ b/Documentation/admin-guide/device-mapper/dm-zoned.rst @@ -14,7 +14,7 @@ host-aware zoned block devices. 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/verity.rst b/Documentation/admin-guide/device-mapper/verity.rst index bb02caa45289443a2b5ea52f0bd83ee8cf46c50b..66f71f0dab1b36ec9d2e22e8fbde66603864e4bd 100644 --- a/Documentation/admin-guide/device-mapper/verity.rst +++ b/Documentation/admin-guide/device-mapper/verity.rst @@ -83,6 +83,10 @@ restart_on_corruption 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 2a97aaec8b122cd7322744a43413d742a246afa2..63fd4e6a014bcce2c161288fed6eb90a64b2b4d6 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,12 +1657,12 @@ 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 0 = /dev/ubda First user-mode block device - 16 = /dev/udbb Second user-mode block device + 16 = /dev/ubdb Second user-mode block device ... Partitions are handled in the same way as for IDE @@ -1723,7 +1724,7 @@ implementations a kernel presence for caching and easy mounting. For more information about the project, write to 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 1012bd9305e905f9b75cc0539fae1f9fe0531f60..6c04aea8f4cd83652fc8de70cb104f2348a1d456 100644 --- a/Documentation/admin-guide/dynamic-debug-howto.rst +++ b/Documentation/admin-guide/dynamic-debug-howto.rst @@ -70,10 +70,10 @@ statements via:: nullarbor:~ # cat /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 @@ the debug statement callsites with any non-default flags:: nullarbor:~ # awk '$3 != "=_"' /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 ========================== @@ -164,15 +164,18 @@ func 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 +185,7 @@ module 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 +255,8 @@ the syntax described above, but must not exceed 1023 characters. Your 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 f37d0743fd668bccf5a5b95e9134ecbc8b4df09b..d2795ca6821ec33e070a9a724a4f9d13f6df5cbe 100644 --- a/Documentation/admin-guide/ext4.rst +++ b/Documentation/admin-guide/ext4.rst @@ -395,6 +395,13 @@ When mounting an ext4 filesystem, the following option are accepted: 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: @@ -525,21 +532,21 @@ Files in /sys/fs/ext4/: Ioctls ====== -There is some Ext4 specific functionality which can be accessed by applications -through the system call interfaces. The list of all Ext4 specific ioctls are -shown in the table below. +Ext4 implements various ioctls which can be used by applications to access +ext4-specific functionality. An incomplete list of these ioctls is shown in the +table below. This list includes truly ext4-specific ioctls (``EXT4_IOC_*``) as +well as ioctls that may have been ext4-specific originally but are now supported +by some other filesystem(s) too (``FS_IOC_*``). -Table of Ext4 specific ioctls +Table of Ext4 ioctls - EXT4_IOC_GETFLAGS + FS_IOC_GETFLAGS Get additional attributes associated with inode. The ioctl argument is - an integer bitfield, with bit values described in ext4.h. This ioctl is - an alias for FS_IOC_GETFLAGS. + an integer bitfield, with bit values described in ext4.h. - EXT4_IOC_SETFLAGS + FS_IOC_SETFLAGS Set additional attributes associated with inode. The ioctl argument is - an integer bitfield, with bit values described in ext4.h. This ioctl is - an alias for FS_IOC_SETFLAGS. + an integer bitfield, with bit values described in ext4.h. EXT4_IOC_GETVERSION, EXT4_IOC_GETVERSION_OLD Get the inode i_generation number stored for each inode. The @@ -614,7 +621,7 @@ kernel source: 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 47b1b3afac994beb278d4923e262a1da7bad5a23..3b1ce68d245673794269cbfaac99812f58925d72 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 the core through the special register mechanism that is susceptible to MDS attacks. Affected processors --------------------- +------------------- Core models (desktop, mobile, Xeon-E3) that implement RDRAND and/or RDSEED may be affected. @@ -59,7 +59,7 @@ executed on another core or sibling thread using MDS techniques. 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 @@ with the option "srbds=". The option for this is: ============= ============================================================= 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 58c7f9fc2396c147abec1a4e221efbeb0e28e355..ed1cf94ea50c2773b1e0c21250c06ac8d2336fcd 100644 --- a/Documentation/admin-guide/index.rst +++ b/Documentation/admin-guide/index.rst @@ -41,6 +41,7 @@ problems and bugs in particular. 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 e4ee8b2db604fdd913f2366f371f89b0a0c9c370..2baad0bfb09d015f4dc6898ada73a78f28106d03 100644 --- a/Documentation/admin-guide/kdump/vmcoreinfo.rst +++ b/Documentation/admin-guide/kdump/vmcoreinfo.rst @@ -93,6 +93,11 @@ It exists in the sparse memory mapping model, and it is also somewhat 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 @@ KERNELPACMASK 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 fb95fad81c79a065e728202a34a3dabac5653cb4..dca917ac21d939cb853d9d4425a79814f80dd89e 100644 --- a/Documentation/admin-guide/kernel-parameters.txt +++ b/Documentation/admin-guide/kernel-parameters.txt @@ -577,7 +577,7 @@ loops can be debugged more effectively on production systems. - clearcpuid=BITNUM [X86] + clearcpuid=BITNUM[,BITNUM...] [X86] Disable CPUID feature X for the kernel. See arch/x86/include/asm/cpufeatures.h for the valid bit numbers. Note the Linux specific bits are not necessarily @@ -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,24 +1231,23 @@ 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" } + 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 @@ -1401,7 +1424,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 +1811,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 +1819,7 @@ inport.irq= [HW] Inport (ATI XL and Microsoft) busmouse driver Format: - 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 +1837,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 +1922,7 @@ strict regions from userspace. relaxed - iommu= [x86] + iommu= [X86] off force noforce @@ -1909,8 +1932,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 +2076,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 +2367,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 +2809,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 +3102,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 +3185,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 +3952,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 +3964,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 +4063,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 +4291,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 +4454,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 +4690,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 +5168,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 +5805,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 @@ -5734,11 +5828,24 @@ improve timer resolution at the expense of processing more timer interrupts. + xen.event_eoi_delay= [XEN] + How long to delay EOI handling in case of event + storms (jiffies). Default is 10. + + xen.event_loop_timeout= [XEN] + After which time (jiffies) the event handling loop + should start to delay EOI handling. Default is 2. + nopv= [X86,XEN,KVM,HYPER_V,VMWARE] Disables the PV optimizations forcing the guest to run 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: ,,,,,[,[,[,]]] diff --git a/Documentation/admin-guide/laptops/disk-shock-protection.rst b/Documentation/admin-guide/laptops/disk-shock-protection.rst index e97c5f78d8c3277a8a2dc690ed6532d1dd6c6423..22c7ec3e84cfc901abfe03135478b94e1262c40e 100644 --- a/Documentation/admin-guide/laptops/disk-shock-protection.rst +++ b/Documentation/admin-guide/laptops/disk-shock-protection.rst @@ -135,7 +135,7 @@ single project which, although still considered experimental, is fit 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 c6eaaf48f7c1ff63f10823144a8246691d8f66db..190da1234314a85ed7d86b29a4965f0286d33321 100644 --- a/Documentation/admin-guide/laptops/sonypi.rst +++ b/Documentation/admin-guide/laptops/sonypi.rst @@ -151,7 +151,7 @@ Bugs: 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 822907dcc84532eafaf75c00ca3a9df68d7fabc1..5fe1ade88c177170fd6af1364d19b5c396eaef77 100644 --- a/Documentation/admin-guide/laptops/thinkpad-acpi.rst +++ b/Documentation/admin-guide/laptops/thinkpad-acpi.rst @@ -50,6 +50,7 @@ detailed description): - 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 @@ temperatures: 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 @@ For the R51 (source: Thomas Gruber): - 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 @@ http://thinkwiki.org/wiki/Thermal_Sensors#ThinkPad_T43.2C_T43p - 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 @@ The first command ensures the best viewing angle and the latter one turns 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 @@ For more details about which buttons will appear depending on the mode, please 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 d973d469ffc4e49c850729bb4f2e25877d0aaa8c..cc8781b96b4dd150245c0fe243c43f892bf95948 100644 --- a/Documentation/admin-guide/md.rst +++ b/Documentation/admin-guide/md.rst @@ -426,6 +426,10 @@ All md devices contain: 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 c898e3a981c1fb37d7d4c2f64dd59976cd353817..2d660b76caea66d11d42a798840af5c49e66de0b 100644 --- a/Documentation/admin-guide/media/building.rst +++ b/Documentation/admin-guide/media/building.rst @@ -90,7 +90,7 @@ built as modules. 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 @@ functionality. 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 0b8ddc4a3008df984fcf364a0b021c7d9c60137a..56b149d9a527c4916da0582969d9fe46bef26e0a 100644 --- a/Documentation/admin-guide/media/fimc.rst +++ b/Documentation/admin-guide/media/fimc.rst @@ -2,7 +2,7 @@ .. include:: -The Samsung S5P/EXYNOS4 FIMC driver +The Samsung S5P/Exynos4 FIMC driver =================================== Copyright |copy| 2012 - 2013 Samsung Electronics Co., Ltd. @@ -19,7 +19,7 @@ drivers/media/platform/exynos4-is directory. Supported SoCs -------------- -S5PC100 (mem-to-mem only), S5PV210, EXYNOS4210 +S5PC100 (mem-to-mem only), S5PV210, Exynos4210 Supported features ------------------ @@ -45,7 +45,7 @@ Media device interface ~~~~~~~~~~~~~~~~~~~~~~ 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 52e57b773f076c5b846394d0fe683d7663c5ee47..6d7175f96f74c26a13944e467aa959ab584aac34 100644 --- a/Documentation/admin-guide/media/vivid.rst +++ b/Documentation/admin-guide/media/vivid.rst @@ -293,6 +293,15 @@ all configurable using the following module options: - 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 c2531b14bf465bf72c4f30ff18f2851e1691999b..fa0974fbeae7c770d125ff72bc2d67b189ddcbaa 100644 --- a/Documentation/admin-guide/mm/concepts.rst +++ b/Documentation/admin-guide/mm/concepts.rst @@ -35,7 +35,7 @@ physical memory (demand paging) and provides a mechanism for the 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 5026e58826e2d41203ba2ff564de5297c56846b9..015a5f7d785403549dd9abcdc05a7f923cd34878 100644 --- a/Documentation/admin-guide/mm/hugetlbpage.rst +++ b/Documentation/admin-guide/mm/hugetlbpage.rst @@ -101,37 +101,48 @@ be specified in bytes with optional scale suffix [kKmMgG]. The default huge page size may be selected with the "default_hugepagesz=" 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 11db46448354612946e070d10aa9cc78054cb075..cd727cfc1b0404db5e422a41a7dd2b3193d122a9 100644 --- a/Documentation/admin-guide/mm/index.rst +++ b/Documentation/admin-guide/mm/index.rst @@ -31,6 +31,7 @@ the Linux memory management. idle_page_tracking ksm memory-hotplug + nommu-mmap numa_memory_policy numaperf pagemap diff --git a/Documentation/admin-guide/mm/ksm.rst b/Documentation/admin-guide/mm/ksm.rst index 874eb0c77d34b84cb855fc993790e88452c722fb..97d816791acae6c1ae85115466920e799e457240 100644 --- a/Documentation/admin-guide/mm/ksm.rst +++ b/Documentation/admin-guide/mm/ksm.rst @@ -9,7 +9,7 @@ Overview 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 @@ with EAGAIN, but more probably arousing the Out-Of-Memory killer. 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 a80c3c37226eb0244be4d549026b8fa0885fba93..4d69ef1de83033040a682ff2b338db72412b882f 100644 --- a/Documentation/admin-guide/mm/numaperf.rst +++ b/Documentation/admin-guide/mm/numaperf.rst @@ -129,7 +129,7 @@ will create the following directory:: /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/nfs/nfs-client.rst b/Documentation/admin-guide/nfs/nfs-client.rst index c4b777c7584b499f236be315e894f5a693c7262f..6adb6457bc694f42132cc665dc786ed8a93324b3 100644 --- a/Documentation/admin-guide/nfs/nfs-client.rst +++ b/Documentation/admin-guide/nfs/nfs-client.rst @@ -65,8 +65,8 @@ migrated onto another server by means of the special "fs_locations" 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 ef0f3678b1fb8f2d6f882eef20901619c71c0368..f137485f8bdeafc5be6b9fba0591672011363ad9 100644 --- a/Documentation/admin-guide/nfs/nfs-rdma.rst +++ b/Documentation/admin-guide/nfs/nfs-rdma.rst @@ -65,7 +65,7 @@ use with NFS/RDMA. 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 c6772075c80cce62953e559c7bff98379a1040f5..135218f33394557cd292932587637e7f3ef16312 100644 --- a/Documentation/admin-guide/nfs/nfsroot.rst +++ b/Documentation/admin-guide/nfs/nfsroot.rst @@ -264,7 +264,7 @@ They depend on various facilities being available: 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 @@ They depend on various facilities being available: 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 @@ They depend on various facilities being available: 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 b00a2e705cc4d6c95e5d54ba644e7581d9213703..20fe9f5117fe05dcc7571a3f4cdf1e5760bcd713 100644 --- a/Documentation/admin-guide/nfs/pnfs-block-server.rst +++ b/Documentation/admin-guide/nfs/pnfs-block-server.rst @@ -8,7 +8,7 @@ to handling all the metadata access to the NFS export also hands out layouts 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 d2f6ee5580711769f127612e8726cc1e2053a5a4..b2eec22883291be6d2755152b175ed259085e8f0 100644 --- a/Documentation/admin-guide/nfs/pnfs-scsi-server.rst +++ b/Documentation/admin-guide/nfs/pnfs-scsi-server.rst @@ -9,7 +9,7 @@ which in addition to handling all the metadata access to the NFS export, 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 832b0c64023aa9e7d0fb409f0c3276f70ab6c27a..f62f7fe50ebac6c3cad91ed008033f0035a30f87 100644 --- a/Documentation/admin-guide/perf/arm-ccn.rst +++ b/Documentation/admin-guide/perf/arm-ccn.rst @@ -27,7 +27,7 @@ Crosspoint PMU events require "xp" (index), "bus" (bus number) 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 0c74a778496480ac9899b7bce415798cc274c362..368e612145d2e84f12d10d37a7859cab65599967 100644 --- a/Documentation/admin-guide/pm/cpufreq.rst +++ b/Documentation/admin-guide/pm/cpufreq.rst @@ -147,9 +147,9 @@ CPUs in it. 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/cpuidle.rst b/Documentation/admin-guide/pm/cpuidle.rst index a96a423e37791862339b2303b555f5b5a2a6ac99..6ebe163f9dfede66c55043dd80fa323cd3332762 100644 --- a/Documentation/admin-guide/pm/cpuidle.rst +++ b/Documentation/admin-guide/pm/cpuidle.rst @@ -690,7 +690,7 @@ which of the two parameters is added to the kernel command line. In the instruction of the CPUs (which, as a rule, suspends the execution of the program and causes the hardware to attempt to enter the shallowest available idle state) for this purpose, and if ``idle=poll`` is used, idle CPUs will execute a -more or less ``lightweight'' sequence of instructions in a tight loop. [Note +more or less "lightweight" sequence of instructions in a tight loop. [Note that using ``idle=poll`` is somewhat drastic in many cases, as preventing idle CPUs from saving almost any energy at all may not be the only effect of it. For example, on Intel hardware it effectively prevents CPUs from using diff --git a/Documentation/admin-guide/pm/intel-speed-select.rst b/Documentation/admin-guide/pm/intel-speed-select.rst index b2ca601c21c65fd60b9de616ef40bf15676c32a7..219f1359aac7b00dad56b704224333067c8a9b19 100644 --- a/Documentation/admin-guide/pm/intel-speed-select.rst +++ b/Documentation/admin-guide/pm/intel-speed-select.rst @@ -114,7 +114,7 @@ base performance profile (which is performance level 0). 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 @@ To enable Intel(R) SST-TF, execute:: 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 39d80bc29ccd6e11c13ca084d34343b6238456ca..5072e7064d13d5ac8500ee94a97454f82346fd9a 100644 --- a/Documentation/admin-guide/pm/intel_pstate.rst +++ b/Documentation/admin-guide/pm/intel_pstate.rst @@ -54,10 +54,13 @@ registered (see `below `_). Operation Modes =============== -``intel_pstate`` can operate in three different modes: in the active mode with -or without hardware-managed P-states support and in the passive mode. Which of -them will be in effect depends on what kernel command line options are used and -on the capabilities of the processor. +``intel_pstate`` can operate in two different modes, active or passive. In the +active mode, it uses its own internal performance scaling governor algorithm or +allows the hardware to do preformance scaling by itself, while in the passive +mode it responds to requests made by a generic ``CPUFreq`` governor implementing +a certain performance scaling algorithm. Which of them will be in effect +depends on what kernel command line options are used and on the capabilities of +the processor. Active Mode ----------- @@ -120,7 +123,9 @@ Energy-Performance Bias (EPB) knob (otherwise), which means that the processor's internal P-state selection logic is expected to focus entirely on performance. This will override the EPP/EPB setting coming from the ``sysfs`` interface -(see `Energy vs Performance Hints`_ below). +(see `Energy vs Performance Hints`_ below). Moreover, any attempts to change +the EPP/EPB to a value different from 0 ("performance") via ``sysfs`` in this +configuration will be rejected. Also, in this configuration the range of P-states available to the processor's internal P-state selection logic is always restricted to the upper boundary @@ -194,10 +199,11 @@ This is the default operation mode of ``intel_pstate`` for processors without hardware-managed P-states (HWP) support. It is always used if the ``intel_pstate=passive`` argument is passed to the kernel in the command line regardless of whether or not the given processor supports HWP. [Note that the -``intel_pstate=no_hwp`` setting implies ``intel_pstate=passive`` if it is used -without ``intel_pstate=active``.] Like in the active mode without HWP support, -in this mode ``intel_pstate`` may refuse to work with processors that are not -recognized by it. +``intel_pstate=no_hwp`` setting causes the driver to start in the passive mode +if it is not combined with ``intel_pstate=active``.] Like in the active mode +without HWP support, in this mode ``intel_pstate`` may refuse to work with +processors that are not recognized by it if HWP is prevented from being enabled +through the kernel command line. If the driver works in this mode, the ``scaling_driver`` policy attribute in ``sysfs`` for all ``CPUFreq`` policies contains the string "intel_cpufreq". @@ -318,10 +324,9 @@ manuals need to be consulted to get to it too. For this reason, there is a list of supported processors in ``intel_pstate`` and the driver initialization will fail if the detected processor is not in that -list, unless it supports the `HWP feature `_. [The interface to -obtain all of the information listed above is the same for all of the processors -supporting the HWP feature, which is why they all are supported by -``intel_pstate``.] +list, unless it supports the HWP feature. [The interface to obtain all of the +information listed above is the same for all of the processors supporting the +HWP feature, which is why ``intel_pstate`` works with all of them.] User Space Interface in ``sysfs`` @@ -425,11 +430,16 @@ argument is passed to the kernel in the command line. as well as the per-policy ones) are then reset to their default values, possibly depending on the target operation mode.] - That only is supported in some configurations, though (for example, if - the `HWP feature is enabled in the processor `_, - the operation mode of the driver cannot be changed), and if it is not - supported in the current configuration, writes to this attribute will - fail with an appropriate error. +``energy_efficiency`` + This attribute is only present on platforms with CPUs matching the Kaby + Lake or Coffee Lake desktop CPU model. By default, energy-efficiency + optimizations are disabled on these CPU models if HWP is enabled. + Enabling energy-efficiency optimizations may limit maximum operating + frequency with or without the HWP feature. With HWP enabled, the + optimizations are done only in the turbo frequency range. Without it, + they are done in the entire available frequency range. Setting this + attribute to "1" enables the energy-efficiency optimizations and setting + to "0" disables them. Interpretation of Policy Attributes ----------------------------------- @@ -473,8 +483,8 @@ Next, the following policy attributes have special meaning if policy for the time interval between the last two invocations of the driver's utilization update callback by the CPU scheduler for that CPU. -One more policy attribute is present if the `HWP feature is enabled in the -processor `_: +One more policy attribute is present if the HWP feature is enabled in the +processor: ``base_frequency`` Shows the base frequency of the CPU. Any frequency above this will be @@ -515,11 +525,11 @@ on the following rules, regardless of the current operation mode of the driver: 3. The global and per-policy limits can be set independently. -If the `HWP feature is enabled in the processor `_, the -resulting effective values are written into its registers whenever the limits -change in order to request its internal P-state selection logic to always set -P-states within these limits. Otherwise, the limits are taken into account by -scaling governors (in the `passive mode `_) and by the driver +In the `active mode with the HWP feature enabled `_, the +resulting effective values are written into hardware registers whenever the +limits change in order to request its internal P-state selection logic to always +set P-states within these limits. Otherwise, the limits are taken into account +by scaling governors (in the `passive mode `_) and by the driver every time before setting a new P-state for a CPU. Additionally, if the ``intel_pstate=per_cpu_perf_limits`` command line argument @@ -530,12 +540,11 @@ at all and the only way to set the limits is by using the policy attributes. Energy vs Performance Hints --------------------------- -If ``intel_pstate`` works in the `active mode with the HWP feature enabled -`_ in the processor, additional attributes are present -in every ``CPUFreq`` policy directory in ``sysfs``. They are intended to allow -user space to help ``intel_pstate`` to adjust the processor's internal P-state -selection logic by focusing it on performance or on energy-efficiency, or -somewhere between the two extremes: +If the hardware-managed P-states (HWP) is enabled in the processor, additional +attributes, intended to allow user space to help ``intel_pstate`` to adjust the +processor's internal P-state selection logic by focusing it on performance or on +energy-efficiency, or somewhere between the two extremes, are present in every +``CPUFreq`` policy directory in ``sysfs``. They are : ``energy_performance_preference`` Current value of the energy vs performance hint for the given policy @@ -554,7 +563,11 @@ somewhere between the two extremes: 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 the +"/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 @@ -635,12 +648,14 @@ of them have to be prepended with the ``intel_pstate=`` prefix. Do not register ``intel_pstate`` as the scaling driver even if the processor is supported by it. +``active`` + Register ``intel_pstate`` in the `active mode `_ to start + with. + ``passive`` Register ``intel_pstate`` in the `passive mode `_ to start with. - This option implies the ``no_hwp`` one described below. - ``force`` Register ``intel_pstate`` as the scaling driver instead of ``acpi-cpufreq`` even if the latter is preferred on the given system. @@ -655,13 +670,12 @@ of them have to be prepended with the ``intel_pstate=`` prefix. driver is used instead of ``acpi-cpufreq``. ``no_hwp`` - Do not enable the `hardware-managed P-states (HWP) feature - `_ even if it is supported by the processor. + Do not enable the hardware-managed P-states (HWP) feature even if it is + supported by the processor. ``hwp_only`` Register ``intel_pstate`` as the scaling driver only if the - `hardware-managed P-states (HWP) feature `_ is - supported by the processor. + hardware-managed P-states (HWP) feature is supported by the processor. ``support_acpi_ppc`` Take ACPI ``_PPC`` performance limits into account. @@ -708,7 +722,7 @@ core (for the policies with other scaling governors). 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 dcd6c93c7aacb04f14120bf0c972d2be26fb1c25..c32eb786201c131144da81a23dd6e383c0860753 100644 --- a/Documentation/admin-guide/security-bugs.rst +++ b/Documentation/admin-guide/security-bugs.rst @@ -21,11 +21,18 @@ understand and fix the security vulnerability. 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 0000000000000000000000000000000000000000..3782f6a09e97a6a6d5d84f59c9d29ff677761177 --- /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_, where 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-/drivers/char/speakup directory. The + 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-/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-/drivers/char/speakup/genmap newmap.map +>/speakup/keymap + +Remember to substitute your kernel version number for the + 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 2a45119e3331a235cf1ae4c3316cd0b3e3be293c..f48277a0a850222c268f778980d88078fc562ccb 100644 --- a/Documentation/admin-guide/sysctl/fs.rst +++ b/Documentation/admin-guide/sysctl/fs.rst @@ -261,7 +261,7 @@ directories like /tmp. The common method of exploitation of this flaw 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 83acf50254886b49e6d6102d0eaf3fb16e145820..d4b32cc32bb79030d9f685a969c7934ad7312180 100644 --- a/Documentation/admin-guide/sysctl/kernel.rst +++ b/Documentation/admin-guide/sysctl/kernel.rst @@ -164,7 +164,8 @@ core_pattern %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 % both are dropped @@ -235,7 +236,7 @@ This toggle indicates whether unprivileged users are prevented 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 @@ Path for the hotplug policy agent. 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 @@ rate for each task. 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 @@ pty 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 @@ Enables/disables scheduler statistics. Enabling this feature 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 d46d5b7013c6395db41b26c033ebeabdaf4bae29..4b9d2e8e9142ceb13f44dcff38bf6f53dd5b464d 100644 --- a/Documentation/admin-guide/sysctl/vm.rst +++ b/Documentation/admin-guide/sysctl/vm.rst @@ -119,6 +119,21 @@ all zones are compacted such that free memory is available in contiguous 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 @@ trimming of allocations is initiated. The default value is 1. -See Documentation/nommu-mmap.txt for more information. +See Documentation/admin-guide/mm/nommu-mmap.rst for more information. numa_zonelist_order diff --git a/Documentation/admin-guide/tainted-kernels.rst b/Documentation/admin-guide/tainted-kernels.rst index 71e9184a9079c9d9fffda7cbfd0ad775d45353e0..abf804719890cce7db069806bb3b04684cb08514 100644 --- a/Documentation/admin-guide/tainted-kernels.rst +++ b/Documentation/admin-guide/tainted-kernels.rst @@ -38,7 +38,7 @@ either letters or blanks. In above example it looks like this:: 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 @@ this on the machine that had the statements in the logs that were quoted earlier * 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 10c4f0ce2ad001729e337f03ca470a2135ae8cbf..613cb24c76c7cce99e4c0dcd772bdcff540697dd 100644 --- a/Documentation/admin-guide/thunderbolt.rst +++ b/Documentation/admin-guide/thunderbolt.rst @@ -173,8 +173,8 @@ following ``udev`` rule:: 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 @@ for some machines: `Thunderbolt 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 ad911be5b5e93e8d931ce1442b901c148fc013bd..f461d6c33534b6de30e8754abf8b4b08da7c6092 100644 --- a/Documentation/admin-guide/xfs.rst +++ b/Documentation/admin-guide/xfs.rst @@ -133,7 +133,7 @@ When mounting an XFS filesystem, the following options are accepted. 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 2edc509df92abe95547d5523dcefe419edee4e28..99d660fdf73fde73c0b8dfaed574cb69df286f27 100644 --- a/Documentation/arm/arm.rst +++ b/Documentation/arm/arm.rst @@ -184,10 +184,8 @@ Kernel entry (head.S) 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- and - arch/arm/mach- - 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- - 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 4babb6c6ae1e2cf99fcfe20541c1f9d55b0a2eb4..a2263451dc2c4085b328007fd8acb9db523e9032 100644 --- a/Documentation/arm/booting.rst +++ b/Documentation/arm/booting.rst @@ -128,7 +128,7 @@ it. The recommended placement is in the first 16KiB of RAM. The boot loader must load a device tree image (dtb) into system ram at a 64bit aligned address and initialize it with the boot data. The -dtb format is documented in Documentation/devicetree/booting-without-of.txt. +dtb format is documented in Documentation/devicetree/booting-without-of.rst. The kernel will look for the dtb magic value of 0xd00dfeed at the dtb physical address to determine if a dtb has been passed instead of a tagged list. diff --git a/Documentation/arm64/acpi_object_usage.rst b/Documentation/arm64/acpi_object_usage.rst index d51b69dc624df1306075aa35924eb6616cb15634..377e9d224db0f94a68c2b502d8d3f9c52124dc49 100644 --- a/Documentation/arm64/acpi_object_usage.rst +++ b/Documentation/arm64/acpi_object_usage.rst @@ -220,7 +220,7 @@ LPIT Signature Reserved (signature == "LPIT") 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 872dbbc73d4a676a8c9929d3a9eef2e408217e91..47ecb9930ddef06a343da2caa18545768ee21df0 100644 --- a/Documentation/arm64/arm-acpi.rst +++ b/Documentation/arm64/arm-acpi.rst @@ -273,7 +273,7 @@ only use the _DSD Device Properties UUID [5]: - 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 @@ likely be willing to assist in submitting ECRs. 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/index.rst b/Documentation/arm64/index.rst index 09cbb4ed2237769cef9484e77ce07ddfa8a5e335..d9665d83c53ace1235a7b271168eee037a9c3b1a 100644 --- a/Documentation/arm64/index.rst +++ b/Documentation/arm64/index.rst @@ -14,6 +14,7 @@ ARM64 Architecture 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 0000000000000000000000000000000000000000..9c76a97baf28d2ec9c0ae1c5a60d72b45f242e1d --- /dev/null +++ b/Documentation/arm64/perf.rst @@ -0,0 +1,88 @@ +.. SPDX-License-Identifier: GPL-2.0 + +===================== +Perf Event Attributes +===================== + +:Author: Andrew Murray +: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 0d6a7d87d49e0d93c376fd80fedaa1780b87d4c7..0000000000000000000000000000000000000000 --- a/Documentation/arm64/perf.txt +++ /dev/null @@ -1,85 +0,0 @@ -Perf Event Attributes -===================== - -Author: Andrew Murray -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 3f7c3a7e8a2b09a68dc70d6821b23f3b976d719e..d3587805de6432332c5d6e197b5ee266a165a5b3 100644 --- a/Documentation/arm64/silicon-errata.rst +++ b/Documentation/arm64/silicon-errata.rst @@ -125,6 +125,9 @@ stable kernels. | Cavium | ThunderX2 Core | #219 | CAVIUM_TX2_ERRATUM_219 | +----------------+-----------------+-----------------+-----------------------------+ +----------------+-----------------+-----------------+-----------------------------+ +| Marvell | ARM-MMU-500 | #582743 | N/A | ++----------------+-----------------+-----------------+-----------------------------+ ++----------------+-----------------+-----------------+-----------------------------+ | Freescale/NXP | LS2080A/LS1043A | A-008585 | FSL_ERRATUM_A008585 | +----------------+-----------------+-----------------+-----------------------------+ +----------------+-----------------+-----------------+-----------------------------+ diff --git a/Documentation/arm64/sve.rst b/Documentation/arm64/sve.rst index bfd55f468258df5fa933a6597b82d59853343f12..03137154299e5e33772ed52c627881dec082207b 100644 --- a/Documentation/arm64/sve.rst +++ b/Documentation/arm64/sve.rst @@ -494,7 +494,7 @@ Appendix B. ARMv8-A FP/SIMD programmer's model 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 0ab747e0d5acf688a20a922e3ea1ee17c15b0289..0f1fdedf36bbbcaebd7d2af13a33c83456b4ec59 100644 --- a/Documentation/atomic_t.txt +++ b/Documentation/atomic_t.txt @@ -85,21 +85,21 @@ smp_store_release() respectively. Therefore, if you find yourself only using 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); } - P1(atomic_t *v) + P0(atomic_t *v) { - atomic_add_unless(v, 1, 0); + (void)atomic_add_unless(v, 1, 0); } - P2(atomic_t *v) + P1(atomic_t *v) { atomic_set(v, 0); } @@ -233,19 +233,19 @@ as well. Similarly, something like: 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 @@ strictly stronger than ACQUIRE. As illustrated: } 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/biodoc.rst b/Documentation/block/biodoc.rst index b964796ec9c78010db81532ad1880f36d75ed376..1d4d71e391afe6dd338f2bbfb90b54477cae4f5b 100644 --- a/Documentation/block/biodoc.rst +++ b/Documentation/block/biodoc.rst @@ -196,7 +196,7 @@ a virtual address mapping (unlike the earlier scheme of virtual address 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 @@ Now the generic block layer performs partition-remapping early and thus 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 0000000000000000000000000000000000000000..88c56afcb070d348324d4f41ea9c66d1b2c1ca3d --- /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 +`_. 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 `_ + +- `NOOP scheduler `_ + +- `Null block device driver `_ + +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 026addfc69bc9743182cc6a594cf6952c9aa6f02..86dcf7159f9900a1a02c4ec28efc1cdee0ef64ff 100644 --- a/Documentation/block/index.rst +++ b/Documentation/block/index.rst @@ -10,6 +10,7 @@ Block bfq-iosched biodoc biovecs + blk-mq capability cmdline-partition data-integrity diff --git a/Documentation/block/pr.rst b/Documentation/block/pr.rst index 30ea1c2e39eb7b4756e65c07d8e2165b19ed4003..c893d6da8e04692963a2868f8de617aa4a7d1520 100644 --- a/Documentation/block/pr.rst +++ b/Documentation/block/pr.rst @@ -9,7 +9,7 @@ access to block devices to specific initiators in a shared storage 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 6a8513af9201caf358d7446b28cc598bab9174e4..f261a5c84170843c3eba524b0112a416c16f26bd 100644 --- a/Documentation/block/queue-sysfs.rst +++ b/Documentation/block/queue-sysfs.rst @@ -117,6 +117,20 @@ Maximum number of elements in a DMA scatter/gather list with integrity 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 2c752c57c14c62a00efaa4b2795b271afaf8b03b..b208488d0aae85403d526860b02006b4ef4c1757 100644 --- a/Documentation/block/writeback_cache_control.rst +++ b/Documentation/block/writeback_cache_control.rst @@ -47,7 +47,7 @@ the Forced Unit Access is implemented. The REQ_PREFLUSH and REQ_FUA flags 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 12a246fcf6cb99d4b68a7bb50f81422396b9127e..2df7b067ab93f532c4d34b4fdf7142b58f965502 100644 --- a/Documentation/bpf/bpf_design_QA.rst +++ b/Documentation/bpf/bpf_design_QA.rst @@ -246,17 +246,6 @@ program is loaded the kernel will print warning message, so 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 0b3db91dc10029f25e3b7c74f1b471899ee4310e..a26aa1b9b2595adea18387a19e40045928973a7d 100644 --- a/Documentation/bpf/bpf_devel_QA.rst +++ b/Documentation/bpf/bpf_devel_QA.rst @@ -643,5 +643,6 @@ when: .. _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 4d565d202ce36e1b461dd92e1d4b7e4caac63f8e..b5361b8621c92e763cb4d0098055c908b19876e0 100644 --- a/Documentation/bpf/btf.rst +++ b/Documentation/bpf/btf.rst @@ -691,6 +691,42 @@ kernel API, the ``insn_off`` is the instruction offset in the unit of ``struct 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 38b4db8be7a2b920bdf6bd7c85246a40b14bd796..7df2465fd108d7554e1ac86b3b941a2b595c4dd5 100644 --- a/Documentation/bpf/index.rst +++ b/Documentation/bpf/index.rst @@ -5,10 +5,10 @@ BPF Documentation 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. @@ -36,6 +36,12 @@ Two sets of Questions and Answers (Q&A) are maintained. bpf_devel_QA +Helper functions +================ + +* `bpf-helpers(7)`_ maintains a list of helpers available to eBPF programs. + + Program types ============= @@ -48,6 +54,15 @@ Program types bpf_lsm +Map types +========= + +.. toctree:: + :maxdepth: 1 + + map_cgroup_storage + + Testing and debugging BPF ========================= @@ -58,8 +73,17 @@ Testing and debugging BPF 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-helpers(7): https://man7.org/linux/man-pages/man7/bpf-helpers.7.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 0000000000000000000000000000000000000000..cab9543017bfafce70d3b5ca19359c05050ddf01 --- /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 + + 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 + #include + + __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 + + 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 + #include + + __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/ringbuf.rst b/Documentation/bpf/ringbuf.rst index 75f943f0009dfbd513c3ae27aa3d6695fd327d4b..6a615cd62bda2f4e1085cd98285acc5f646d819e 100644 --- a/Documentation/bpf/ringbuf.rst +++ b/Documentation/bpf/ringbuf.rst @@ -182,9 +182,6 @@ in the order of reservations, but only after all previous records where already committed. It is thus possible for slow producers to temporarily hold off submitted records, that were reserved later. -Reservation/commit/consumer protocol is verified by litmus tests in -Documentation/litmus_tests/bpf-rb/_. - One interesting implementation bit, that significantly simplifies (and thus speeds up as well) implementation of both producers and consumers is how data area is mapped twice contiguously back-to-back in the virtual memory. This @@ -200,7 +197,7 @@ a self-pacing notifications of new data being availability. being available after commit only if consumer has already caught up right up to the record being committed. If not, consumer still has to catch up and thus will see new data anyways without needing an extra poll notification. -Benchmarks (see tools/testing/selftests/bpf/benchs/bench_ringbuf.c_) show that +Benchmarks (see tools/testing/selftests/bpf/benchs/bench_ringbufs.c) show that this allows to achieve a very high throughput without having to resort to tricks like "notify only every Nth sample", which are necessary with perf buffer. For extreme cases, when BPF program wants more manual control of diff --git a/Documentation/bus-virt-phys-mapping.txt b/Documentation/bus-virt-phys-mapping.txt deleted file mode 100644 index 4bb07c2f3e7d3fbaa007140f496c332feb75997b..0000000000000000000000000000000000000000 --- 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 - - 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 dde4f7f7fdbf1cb796c09306369a8bddaf5b8f5d..70500b189cc84431e266de9017cd082fd04e5b3f 100644 --- a/Documentation/cdrom/cdrom-standard.rst +++ b/Documentation/cdrom/cdrom-standard.rst @@ -157,7 +157,6 @@ with the kernel as a block device by registering the following general cdrom_release, /∗ release ∗/ NULL, /∗ fsync ∗/ NULL, /∗ fasync ∗/ - cdrom_media_changed, /∗ media change ∗/ NULL /∗ revalidate ∗/ }; @@ -366,19 +365,6 @@ which may or may not be in the drive). If the drive is not a changer, CDS_DRIVE_NOT_READY /* something is wrong, tray is moving? */ CDS_DISC_OK /* a disc is loaded and everything is fine */ -:: - - 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) @@ -571,7 +557,7 @@ phase. Currently, the capabilities are any of:: 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 @@ Description of routines in `cdrom.c` 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 @@ commands can be identified by the underscores in their names. 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 0000000000000000000000000000000000000000..c7bc99cd2e21dcacb1643096ef4fb1d98bdc4863 --- /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 + + 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 b1ae1ac159cf91ebcd8b9a93b857c7299fecc03d..298c9c8bea9a232910c7c36eec32813dc99021e6 100644 --- a/Documentation/core-api/cpu_hotplug.rst +++ b/Documentation/core-api/cpu_hotplug.rst @@ -35,8 +35,8 @@ Command Line Switches 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`` diff --git a/Documentation/core-api/dma-api.rst b/Documentation/core-api/dma-api.rst index f41620439ef349b0592d177052b7d6fa85fcf152..3b3abbbb4b9a6fd6819e47d8768a8e3cb67b3552 100644 --- a/Documentation/core-api/dma-api.rst +++ b/Documentation/core-api/dma-api.rst @@ -5,7 +5,7 @@ Dynamic DMA mapping using the generic device :Author: James E.J. Bottomley 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 @@ -479,7 +479,7 @@ without the _attrs suffixes, except that they pass an optional 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 @@ -492,7 +492,7 @@ for DMA:: #include /* 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 b1ec7b16c21fffc65199a213ea3bbfb4794f84b3..e59a3d35a93dce8aa6812937a8bed496261f7178 100644 --- a/Documentation/core-api/dma-isa-lpc.rst +++ b/Documentation/core-api/dma-isa-lpc.rst @@ -17,7 +17,7 @@ To do ISA style DMA you need to include two headers:: #include 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 a2738050c4f00834283789416cf1b1b0921bc88e..2eb5afdb99314fa152e9cfdcadba293f1054b2ca 100644 --- a/Documentation/core-api/idr.rst +++ b/Documentation/core-api/idr.rst @@ -20,48 +20,48 @@ only ID allocation, and as a result is much more memory-efficient. 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 15ab8611262720da67254faf431a4b8ce1b3366a..69171b1799f21464322ff150a41e3b39e4978b2b 100644 --- a/Documentation/core-api/index.rst +++ b/Documentation/core-api/index.rst @@ -39,6 +39,8 @@ Library functionality that is used throughout the kernel. rbtree generic-radix-tree packing + bus-virt-phys-mapping + this_cpu_ops timekeeping errseq @@ -82,6 +84,7 @@ more memory-management documentation in :doc:`/vm/index`. :maxdepth: 1 memory-allocation + unaligned-memory-access dma-api dma-api-howto dma-attributes diff --git a/Documentation/core-api/kobject.rst b/Documentation/core-api/kobject.rst index e93dc8cf52dd4b1a0d5fd890d54ced8c1cd73f72..2739f8b72575091626f0cb3dc465c9571a0522ba 100644 --- a/Documentation/core-api/kobject.rst +++ b/Documentation/core-api/kobject.rst @@ -6,7 +6,7 @@ Everything you never wanted to know about kobjects, ksets, and ktypes :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 4aa82ddd01b8de8eb3b1462be38b8d57d53adb7e..4446a1ac36ccefd02319a892aa6d5de5a62d8de4 100644 --- a/Documentation/core-api/memory-allocation.rst +++ b/Documentation/core-api/memory-allocation.rst @@ -84,6 +84,50 @@ driver for a device with such restrictions, avoid using these flags. 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 0830e5b0e82119f5ea7255d1847c044f8873d3ac..35175710b43cc9409c7220d160c82773b3d259d5 100644 --- a/Documentation/core-api/padata.rst +++ b/Documentation/core-api/padata.rst @@ -27,22 +27,11 @@ padata_instance structure for overall control of how jobs are to be run:: #include - 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 @@ submitted. 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/printk-basics.rst b/Documentation/core-api/printk-basics.rst index 563a9ce5fe1d878f0c526117226ff0732fd43e3b..965e4281eddde34744f2ff0ca4efdbb134eeef77 100644 --- a/Documentation/core-api/printk-basics.rst +++ b/Documentation/core-api/printk-basics.rst @@ -69,7 +69,7 @@ You can check the current *console_loglevel* with:: 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 8c9aba262b1ea3c082467232169c65167c49b0f9..6d26c5c6ac485cec272e78ae400b7a24dd2ccf4d 100644 --- a/Documentation/core-api/printk-formats.rst +++ b/Documentation/core-api/printk-formats.rst @@ -317,7 +317,7 @@ colon-separators. Leading zeros are always used. 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 @@ The additional ``p``, ``f``, and ``s`` specifiers are used to specify port 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 @@ Time and date %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 0000000000000000000000000000000000000000..15201be0b8114e8030e0614418666decb2054eb0 --- /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 + #include + #include + + 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 , + David S. Miller + + +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 + +Please send any credits updates or corrections to: +Herbert Xu diff --git a/Documentation/crypto/api-intro.txt b/Documentation/crypto/api-intro.txt deleted file mode 100644 index 45d943fcae5b72ade50624a768b9dd8f67555247..0000000000000000000000000000000000000000 --- 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 - #include - #include - - 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 , - David S. Miller - - -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 - -Please send any credits updates or corrections to: -Herbert Xu - diff --git a/Documentation/crypto/asymmetric-keys.rst b/Documentation/crypto/asymmetric-keys.rst new file mode 100644 index 0000000000000000000000000000000000000000..349f44a29392ea1ffc21df1b8e7fc118ca7d044f --- /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:" 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 ":" 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 + +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 + +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 + +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:[: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 8763866b11cfd0f6af865ed67d8ba6db75a48b60..0000000000000000000000000000000000000000 --- 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:" 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 ":" 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 - -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 - -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 - -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:[: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 0000000000000000000000000000000000000000..bfc773991bdc59b7c1c1a9fe7d50d840725b8b35 --- /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_(, 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_ 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_, 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_ 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 7bf1be20d93a4555d55e19c2992904011413f9ee..0000000000000000000000000000000000000000 --- 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_(, 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_ 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_, 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_ 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 0000000000000000000000000000000000000000..45bd9c8babf4b1ee275061bbb8ee7bcc73569b16 --- /dev/null +++ b/Documentation/crypto/descore-readme.rst @@ -0,0 +1,414 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: + +=========================================== +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 16e9e63507551989d726998d1ac769703f4325f2..0000000000000000000000000000000000000000 --- 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 c4ff5d791233921bd82591939c1cdf5fb117e859..21338fa9264252421e3bf0406960986128a7685e 100644 --- a/Documentation/crypto/index.rst +++ b/Documentation/crypto/index.rst @@ -17,9 +17,14 @@ for cryptographic use cases, as well as programming examples. :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 ff86befa61e0e8ed4988706a046b95ea323e8402..52019e9059004aef759ba03e92130ae5a939bca3 100644 --- a/Documentation/crypto/userspace-if.rst +++ b/Documentation/crypto/userspace-if.rst @@ -23,7 +23,7 @@ user space, however. This includes the difference between synchronous 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 @@ Please see [1] for libkcapi which provides an easy-to-use wrapper around 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 70274c3f5f5a0f02faaf890523f8a4784195e750..74c5e6aeeff55511467ced359aae6fbc5abcc4dc 100644 --- a/Documentation/dev-tools/coccinelle.rst +++ b/Documentation/dev-tools/coccinelle.rst @@ -85,7 +85,7 @@ Four basic modes are defined: ``patch``, ``report``, ``context``, and 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 @@ For each semantic patch, a commit message is proposed. It gives a 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 @@ the parallelism, set the J= variable. For example, to run across 4 CPUs:: 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 @@ For example, to check drivers/net/wireless/ one may write:: 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 @@ Debugging Coccinelle SmPL patches 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 @@ instance:: 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 @@ DEBUG_FILE support is only supported when using coccinelle >= 1.0.2. -------------------- 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 @@ variables for .cocciconfig is as follows: - 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 @@ If not using the kernel's coccicheck target, keep the above precedence 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 @@ given to it when options are in conflict. :: 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 patch specific options --------------------------- 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 @@ SmPL patch Coccinelle requirements 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 7bd013596217c58e71c4986d58bd950f34a6b253..9e989baae1547ad51a09796fe28c6ad35e77b372 100644 --- a/Documentation/dev-tools/gcov.rst +++ b/Documentation/dev-tools/gcov.rst @@ -22,7 +22,7 @@ Possible uses: * 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 @@ Note on compilers 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 c652d740735de56ba59c458ecfe856ad274d2311..38fd5681fade4b5a21ecf748d309eb1c5c3c4831 100644 --- a/Documentation/dev-tools/kasan.rst +++ b/Documentation/dev-tools/kasan.rst @@ -13,11 +13,8 @@ KASAN uses compile-time instrumentation to insert validity checks before every 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 @@ function calls GCC directly inserts the code to check the shadow memory. 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 b38379f0619415dc3ad734e552d85a80c374c402..be7a0b0e1f28e7fa8e01f88a571465924dbe6d10 100644 --- a/Documentation/dev-tools/kcsan.rst +++ b/Documentation/dev-tools/kcsan.rst @@ -8,7 +8,8 @@ approach to detect races. KCSAN's primary purpose is to detect `data races`_. 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:: diff --git a/Documentation/dev-tools/kgdb.rst b/Documentation/dev-tools/kgdb.rst index 61293f40bc6e4f98b57532c999817bc740fb6d26..c908ef4d3f0439ca2c0d96b1da5615082d0b39cb 100644 --- a/Documentation/dev-tools/kgdb.rst +++ b/Documentation/dev-tools/kgdb.rst @@ -316,7 +316,7 @@ driver as a loadable kernel module kgdbwait will not do anything. 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 @@ This is a quick example of how to use kdb. ``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 kernel debugger is organized into a number of components: 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 @@ The kernel debugger is organized into a number of components: 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 @@ The kgdboc driver contains logic to configure communications with an 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 @@ that you have a video driver which has a frame buffer console and atomic 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 fce2628839843f1284c9631db4c481749a805361..a41a2d238af233d2802bae7fbc144ec3f96fa04a 100644 --- a/Documentation/dev-tools/kmemleak.rst +++ b/Documentation/dev-tools/kmemleak.rst @@ -8,8 +8,6 @@ with the difference that the orphan objects are not freed but only 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/kunit-tool.rst b/Documentation/dev-tools/kunit/kunit-tool.rst index 949af2da81e5b6b8fa0233646043347d9f5ec424..29ae2fee8123be5aba063e7b60bf82c78532bdc4 100644 --- a/Documentation/dev-tools/kunit/kunit-tool.rst +++ b/Documentation/dev-tools/kunit/kunit-tool.rst @@ -19,13 +19,13 @@ compiles the kernel as a standalone Linux executable that can be run like any 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 @@ However, you most likely want to use it with the following options: - ``--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 bb112cf70624ea0ea480e7aa4406b8f386ccdd73..d23385e3e1592bea6240287f0422bb94da629022 100644 --- a/Documentation/dev-tools/kunit/start.rst +++ b/Documentation/dev-tools/kunit/start.rst @@ -18,7 +18,7 @@ The wrapper can be run with: .. 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 6f4870528226eef2ebb30559536e4552e26540a4..02102be7ff4962ff55f6031ff5b1a9baa9210ee0 100644 --- a/Documentation/dev-tools/sparse.rst +++ b/Documentation/dev-tools/sparse.rst @@ -9,6 +9,8 @@ Sparse is a semantic checker for C programs; it can be used to find a 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 @@ sparse would otherwise report a context imbalance. 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/arm/al,alpine.yaml b/Documentation/devicetree/bindings/arm/al,alpine.yaml deleted file mode 100644 index a70dff277e05f1c7672dd19d10051284d7e57ea2..0000000000000000000000000000000000000000 --- 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 - - Antoine Tenart - -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 0000000000000000000000000000000000000000..a3a4d710bd02a00b1ff94f0fdc2b60aa595dd53a --- /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 + - Talel Shenhar , + - Ronen Krupnik + +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 378229fa8310cb77400de6118c5019f678ee8e80..5eba9f48823ec0d31a12a3dcccde9058ea71ef51 100644 --- a/Documentation/devicetree/bindings/arm/amlogic.yaml +++ b/Documentation/devicetree/bindings/arm/amlogic.yaml @@ -121,6 +121,7 @@ properties: - 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,integrator.yaml b/Documentation/devicetree/bindings/arm/arm,integrator.yaml index 192ded470e32e8df88b254205be616a474c39ca1..f0daf990e0778456c1887f9cd6f0270fee295ba5 100644 --- a/Documentation/devicetree/bindings/arm/arm,integrator.yaml +++ b/Documentation/devicetree/bindings/arm/arm,integrator.yaml @@ -67,9 +67,9 @@ patternProperties: compatible: items: - enum: - - arm,integrator-ap-syscon - - arm,integrator-cp-syscon - - arm,integrator-sp-syscon + - arm,integrator-ap-syscon + - arm,integrator-cp-syscon + - arm,integrator-sp-syscon - const: syscon reg: maxItems: 1 diff --git a/Documentation/devicetree/bindings/arm/arm,realview.yaml b/Documentation/devicetree/bindings/arm/arm,realview.yaml index d6e85d198afe9bc5f97d820125a5de8b3d467047..1d0b4e2bc7d2bf11ba4a7ff719411cc18eac2b75 100644 --- a/Documentation/devicetree/bindings/arm/arm,realview.yaml +++ b/Documentation/devicetree/bindings/arm/arm,realview.yaml @@ -55,20 +55,20 @@ properties: compatible: oneOf: - items: - - const: arm,realview-eb-soc - - const: simple-bus + - const: arm,realview-eb-soc + - const: simple-bus - items: - - const: arm,realview-pb1176-soc - - const: simple-bus + - const: arm,realview-pb1176-soc + - const: simple-bus - items: - - const: arm,realview-pb11mp-soc - - const: simple-bus + - const: arm,realview-pb11mp-soc + - const: simple-bus - items: - - const: arm,realview-pba8-soc - - const: simple-bus + - const: arm,realview-pba8-soc + - const: simple-bus - items: - - const: arm,realview-pbx-soc - - const: simple-bus + - const: arm,realview-pbx-soc + - const: simple-bus patternProperties: "^.*syscon@[0-9a-f]+$": @@ -79,35 +79,35 @@ properties: compatible: oneOf: - items: - - const: arm,realview-eb11mp-revb-syscon - - const: arm,realview-eb-syscon - - const: syscon - - const: simple-mfd + - const: arm,realview-eb11mp-revb-syscon + - const: arm,realview-eb-syscon + - const: syscon + - const: simple-mfd - items: - - const: arm,realview-eb11mp-revc-syscon - - const: arm,realview-eb-syscon - - const: syscon - - const: simple-mfd + - const: arm,realview-eb11mp-revc-syscon + - const: arm,realview-eb-syscon + - const: syscon + - const: simple-mfd - items: - - const: arm,realview-eb-syscon - - const: syscon - - const: simple-mfd + - const: arm,realview-eb-syscon + - const: syscon + - const: simple-mfd - items: - - const: arm,realview-pb1176-syscon - - const: syscon - - const: simple-mfd + - const: arm,realview-pb1176-syscon + - const: syscon + - const: simple-mfd - items: - - const: arm,realview-pb11mp-syscon - - const: syscon - - const: simple-mfd + - const: arm,realview-pb11mp-syscon + - const: syscon + - const: simple-mfd - items: - - const: arm,realview-pba8-syscon - - const: syscon - - const: simple-mfd + - const: arm,realview-pba8-syscon + - const: syscon + - const: simple-mfd - items: - - const: arm,realview-pbx-syscon - - const: syscon - - const: simple-mfd + - const: arm,realview-pbx-syscon + - const: syscon + - const: simple-mfd required: - compatible diff --git a/Documentation/devicetree/bindings/arm/arm,scmi.txt b/Documentation/devicetree/bindings/arm/arm,scmi.txt index 1f293ea24cd85793402cf0b2f72b21db4a460594..55deb68230ebb2af17fe5185b1d93cc9af16bfb5 100644 --- a/Documentation/devicetree/bindings/arm/arm,scmi.txt +++ b/Documentation/devicetree/bindings/arm/arm,scmi.txt @@ -102,7 +102,7 @@ Required sub-node properties: [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 dd04d9d9a1b8e0b06e43d16683feb440ebbff4d5..bcd6c3ec471e68b3892ebc4703d04ff2a870fc26 100644 --- a/Documentation/devicetree/bindings/arm/arm,scpi.txt +++ b/Documentation/devicetree/bindings/arm/arm,scpi.txt @@ -108,7 +108,7 @@ Required properties: [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/arm,vexpress-juno.yaml b/Documentation/devicetree/bindings/arm/arm,vexpress-juno.yaml index a3420c81cf3510b09368d1e9f43b3fc39259e91e..26829a803fda8dddc63d736466480a8bf7e27365 100644 --- a/Documentation/devicetree/bindings/arm/arm,vexpress-juno.yaml +++ b/Documentation/devicetree/bindings/arm/arm,vexpress-juno.yaml @@ -165,10 +165,10 @@ patternProperties: compatible: oneOf: - items: - - enum: - - arm,vexpress,v2m-p1 - - arm,vexpress,v2p-p1 - - const: simple-bus + - enum: + - arm,vexpress,v2m-p1 + - arm,vexpress,v2p-p1 + - const: simple-bus - const: simple-bus motherboard: type: object @@ -186,8 +186,8 @@ patternProperties: compatible: items: - enum: - - arm,vexpress,v2m-p1 - - arm,vexpress,v2p-p1 + - arm,vexpress,v2m-p1 + - arm,vexpress,v2p-p1 - const: simple-bus arm,v2m-memory-map: description: This describes the memory map type. diff --git a/Documentation/devicetree/bindings/arm/bcm/brcm,bcm11351.yaml b/Documentation/devicetree/bindings/arm/bcm/brcm,bcm11351.yaml index b5ef2666e6b29a357bcc59ee9aa0a9c7d3ef6ebd..497600a2ffb9c42e1b6dcfb9538dbf9da6e63554 100644 --- a/Documentation/devicetree/bindings/arm/bcm/brcm,bcm11351.yaml +++ b/Documentation/devicetree/bindings/arm/bcm/brcm,bcm11351.yaml @@ -15,7 +15,7 @@ properties: compatible: items: - enum: - - brcm,bcm28155-ap + - brcm,bcm28155-ap - const: brcm,bcm11351 ... diff --git a/Documentation/devicetree/bindings/arm/bcm/brcm,bcm21664.yaml b/Documentation/devicetree/bindings/arm/bcm/brcm,bcm21664.yaml index aafbd6a277080bb8130ab9938013103ca4670111..e0ee931723dc431d2495229260e151a341171cd0 100644 --- a/Documentation/devicetree/bindings/arm/bcm/brcm,bcm21664.yaml +++ b/Documentation/devicetree/bindings/arm/bcm/brcm,bcm21664.yaml @@ -15,7 +15,7 @@ properties: compatible: items: - enum: - - brcm,bcm21664-garnet + - brcm,bcm21664-garnet - const: brcm,bcm21664 ... diff --git a/Documentation/devicetree/bindings/arm/bcm/brcm,bcm23550.yaml b/Documentation/devicetree/bindings/arm/bcm/brcm,bcm23550.yaml index c4b4efd28a55e8e96cf6bb73ef597b6afb4f762d..40d12ea56e547e11a8980b05fe36bda11f1fa4e4 100644 --- a/Documentation/devicetree/bindings/arm/bcm/brcm,bcm23550.yaml +++ b/Documentation/devicetree/bindings/arm/bcm/brcm,bcm23550.yaml @@ -15,7 +15,7 @@ properties: compatible: items: - enum: - - brcm,bcm23550-sparrow + - brcm,bcm23550-sparrow - const: brcm,bcm23550 ... diff --git a/Documentation/devicetree/bindings/arm/bcm/brcm,cygnus.yaml b/Documentation/devicetree/bindings/arm/bcm/brcm,cygnus.yaml index fe111e72dac3cd5aa5170a7419895329aea4fa46..9ba7b16e1fc4dd3dadca0202fdb8274141894a84 100644 --- a/Documentation/devicetree/bindings/arm/bcm/brcm,cygnus.yaml +++ b/Documentation/devicetree/bindings/arm/bcm/brcm,cygnus.yaml @@ -7,8 +7,8 @@ $schema: http://devicetree.org/meta-schemas/core.yaml# title: Broadcom Cygnus device tree bindings maintainers: - - Ray Jui - - Scott Branden + - Ray Jui + - Scott Branden properties: $nodename: @@ -16,14 +16,14 @@ properties: compatible: items: - enum: - - brcm,bcm11300 - - brcm,bcm11320 - - brcm,bcm11350 - - brcm,bcm11360 - - brcm,bcm58300 - - brcm,bcm58302 - - brcm,bcm58303 - - brcm,bcm58305 + - brcm,bcm11300 + - brcm,bcm11320 + - brcm,bcm11350 + - brcm,bcm11360 + - brcm,bcm58300 + - brcm,bcm58302 + - brcm,bcm58303 + - brcm,bcm58305 - const: brcm,cygnus ... diff --git a/Documentation/devicetree/bindings/arm/bcm/brcm,hr2.yaml b/Documentation/devicetree/bindings/arm/bcm/brcm,hr2.yaml index 1158f49b0b83f9ed5f8febe28b9626809c0743ff..ae614b6722c2b5a313724b39eb38671c618ef81c 100644 --- a/Documentation/devicetree/bindings/arm/bcm/brcm,hr2.yaml +++ b/Documentation/devicetree/bindings/arm/bcm/brcm,hr2.yaml @@ -21,7 +21,7 @@ properties: compatible: items: - enum: - - ubnt,unifi-switch8 + - ubnt,unifi-switch8 - const: brcm,bcm53342 - const: brcm,hr2 diff --git a/Documentation/devicetree/bindings/arm/bcm/brcm,ns2.yaml b/Documentation/devicetree/bindings/arm/bcm/brcm,ns2.yaml index 2451704f87f001a58acaf908ef38ce13d2646c18..0749adf94c28929c64d5cc9ed079d05acd476d9d 100644 --- a/Documentation/devicetree/bindings/arm/bcm/brcm,ns2.yaml +++ b/Documentation/devicetree/bindings/arm/bcm/brcm,ns2.yaml @@ -16,8 +16,8 @@ properties: compatible: items: - enum: - - brcm,ns2-svk - - brcm,ns2-xmc + - brcm,ns2-svk + - brcm,ns2-xmc - const: brcm,ns2 ... diff --git a/Documentation/devicetree/bindings/arm/bcm/brcm,nsp.yaml b/Documentation/devicetree/bindings/arm/bcm/brcm,nsp.yaml index fe364cebf57f401508acf5240685a5469ee327b8..8c2cacb2bb4f12b02f348704c0a3492939eb29e9 100644 --- a/Documentation/devicetree/bindings/arm/bcm/brcm,nsp.yaml +++ b/Documentation/devicetree/bindings/arm/bcm/brcm,nsp.yaml @@ -24,13 +24,13 @@ properties: compatible: items: - enum: - - brcm,bcm58522 - - brcm,bcm58525 - - brcm,bcm58535 - - brcm,bcm58622 - - brcm,bcm58623 - - brcm,bcm58625 - - brcm,bcm88312 + - brcm,bcm58522 + - brcm,bcm58525 + - brcm,bcm58535 + - brcm,bcm58622 + - brcm,bcm58623 + - brcm,bcm58625 + - brcm,bcm88312 - const: brcm,nsp ... diff --git a/Documentation/devicetree/bindings/arm/bcm/brcm,stingray.yaml b/Documentation/devicetree/bindings/arm/bcm/brcm,stingray.yaml index 4ad2b2124ab4698b3e92f99462455e714375095a..c13cb96545a2836008229791e5260610892fbe02 100644 --- a/Documentation/devicetree/bindings/arm/bcm/brcm,stingray.yaml +++ b/Documentation/devicetree/bindings/arm/bcm/brcm,stingray.yaml @@ -16,9 +16,9 @@ properties: compatible: items: - enum: - - brcm,bcm958742k - - brcm,bcm958742t - - brcm,bcm958802a802x + - brcm,bcm958742k + - brcm,bcm958742t + - brcm,bcm958802a802x - const: brcm,stingray ... diff --git a/Documentation/devicetree/bindings/arm/bcm/brcm,vulcan-soc.yaml b/Documentation/devicetree/bindings/arm/bcm/brcm,vulcan-soc.yaml index c5b6f31c20b98c4b443475e1d5b02d0668773fee..ccdf9f99cb2b01a9eb862c1674924f1207e60111 100644 --- a/Documentation/devicetree/bindings/arm/bcm/brcm,vulcan-soc.yaml +++ b/Documentation/devicetree/bindings/arm/bcm/brcm,vulcan-soc.yaml @@ -15,8 +15,8 @@ properties: compatible: items: - enum: - - brcm,vulcan-eval - - cavium,thunderx2-cn9900 + - brcm,vulcan-eval + - cavium,thunderx2-cn9900 - const: brcm,vulcan-soc ... 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 6824b3180ffb72e55d3f6951ae14c2a58af24bf4..0000000000000000000000000000000000000000 --- 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 0000000000000000000000000000000000000000..6834f5e8df5f08a5fe4e8d7f540bf320fbd373b6 --- /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 + - Stefan Wahren + +select: + properties: + compatible: + contains: + const: raspberrypi,bcm2835-firmware + + required: + - compatible + +properties: + compatible: + items: + - const: raspberrypi,bcm2835-firmware + - const: simple-mfd + + 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-mfd"; + mboxes = <&mailbox>; + + firmware_clocks: clocks { + compatible = "raspberrypi,firmware-clocks"; + #clock-cells = <1>; + }; + }; +... diff --git a/Documentation/devicetree/bindings/arm/coresight-cti.yaml b/Documentation/devicetree/bindings/arm/coresight-cti.yaml index 17df5cd12d8de5d21c6391514ae9f464667c0b79..e42ff69d8bfb4d18dc576705c170801b296587de 100644 --- a/Documentation/devicetree/bindings/arm/coresight-cti.yaml +++ b/Documentation/devicetree/bindings/arm/coresight-cti.yaml @@ -82,12 +82,12 @@ properties: compatible: oneOf: - items: - - const: arm,coresight-cti - - const: arm,primecell + - const: arm,coresight-cti + - const: arm,primecell - items: - - const: arm,coresight-cti-v8-arch - - const: arm,coresight-cti - - const: arm,primecell + - const: arm,coresight-cti-v8-arch + - const: arm,coresight-cti + - const: arm,primecell reg: maxItems: 1 @@ -191,16 +191,16 @@ patternProperties: anyOf: - required: - - arm,trig-in-sigs + - arm,trig-in-sigs - required: - - arm,trig-out-sigs + - arm,trig-out-sigs oneOf: - required: - - arm,trig-conn-name + - arm,trig-conn-name - required: - - cpu + - cpu - required: - - arm,cs-dev-assoc + - arm,cs-dev-assoc required: - reg diff --git a/Documentation/devicetree/bindings/arm/coresight.txt b/Documentation/devicetree/bindings/arm/coresight.txt index 846f6daae71b29e0e5f0d65c0f5f16f0ef1a6b9d..d711676b4a51ebaa3caa91e05e363b87b6dd9474 100644 --- a/Documentation/devicetree/bindings/arm/coresight.txt +++ b/Documentation/devicetree/bindings/arm/coresight.txt @@ -108,6 +108,13 @@ its hardware characteristcs. * 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 @@ its hardware characteristcs. * 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/cpus.yaml b/Documentation/devicetree/bindings/arm/cpus.yaml index 40f692c846f0c44e5f7762c26c6ca7b8d1a70118..1222bf1831fab0fd772284483571f3392735e836 100644 --- a/Documentation/devicetree/bindings/arm/cpus.yaml +++ b/Documentation/devicetree/bindings/arm/cpus.yaml @@ -330,8 +330,8 @@ if: - enable-method then: - required: - - secondary-boot-reg + required: + - secondary-boot-reg required: - device_type diff --git a/Documentation/devicetree/bindings/arm/freescale/fsl,scu.txt b/Documentation/devicetree/bindings/arm/freescale/fsl,scu.txt index 10b8459e49f8c22a4ff12c2485b00030dc72df64..6064d98b103144e07e8a4d02853bc3fba5d9b02d 100644 --- a/Documentation/devicetree/bindings/arm/freescale/fsl,scu.txt +++ b/Documentation/devicetree/bindings/arm/freescale/fsl,scu.txt @@ -176,7 +176,7 @@ Required properties: "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 05906e291e38e4f4ce0170b12ce33fafdc821814..6da9d734cdb74108b4b9f352d706f5c76b8403d5 100644 --- a/Documentation/devicetree/bindings/arm/fsl.yaml +++ b/Documentation/devicetree/bindings/arm/fsl.yaml @@ -120,6 +120,8 @@ properties: - 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 @@ properties: - 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,8 +272,9 @@ properties: - 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 - - 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 + - myir,imx6ull-mys-6ulx-eval # MYiR Tech iMX6ULL Evaluation Board + - toradex,colibri-imx6ull-eval # Colibri iMX6ULL Module on Colibri Eval Board + - toradex,colibri-imx6ull-wifi-eval # Colibri iMX6ULL Wi-Fi / BT Module on Colibri Eval Board - const: fsl,imx6ull - description: Kontron N6411 S Board @@ -307,9 +312,12 @@ properties: - toradex,colibri-imx7d # Colibri iMX7 Dual Module - toradex,colibri-imx7d-aster # Colibri iMX7 Dual Module on Aster Carrier Board - toradex,colibri-imx7d-emmc # Colibri iMX7 Dual 1GB (eMMC) Module - - toradex,colibri-imx7d-emmc-aster # Colibri iMX7 Dual 1GB (eMMC) Module on Aster Carrier Board - - toradex,colibri-imx7d-emmc-eval-v3 # Colibri iMX7 Dual 1GB (eMMC) Module on Colibri Evaluation Board V3 - - toradex,colibri-imx7d-eval-v3 # Colibri iMX7 Dual Module on Colibri Evaluation Board V3 + - toradex,colibri-imx7d-emmc-aster # Colibri iMX7 Dual 1GB (eMMC) Module on + # Aster Carrier Board + - toradex,colibri-imx7d-emmc-eval-v3 # Colibri iMX7 Dual 1GB (eMMC) Module on + # Colibri Evaluation Board V3 + - toradex,colibri-imx7d-eval-v3 # Colibri iMX7 Dual Module on + # Colibri Evaluation Board V3 - tq,imx7d-mba7 # i.MX7D TQ MBa7 with TQMa7D SoM - zii,imx7d-rmu2 # ZII RMU2 Board - zii,imx7d-rpu2 # ZII RPU2 Board diff --git a/Documentation/devicetree/bindings/arm/intel,keembay.yaml b/Documentation/devicetree/bindings/arm/intel,keembay.yaml new file mode 100644 index 0000000000000000000000000000000000000000..06a7b05f435f3d7ef629e0afa17d37b41f38a20c --- /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 + - Daniele Alessandrelli + +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 0000000000000000000000000000000000000000..7597bc93a55fa037889da75e9a4dcea168bd5ec8 --- /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 + +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 . + $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 098d932fc9630a49a5c83b16231def0fb521c87e..e31511255d8e3b6aeb3215f996a42c07445d7b02 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 @@ Thermal: -------- 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 f982a8ed93968f18957b88d37d1cb287327532e2..a21f7709596c08cc0c40c3ddeb4525073b618dae 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 @@ It is possible to setup an overheat interrupt by giving at least one 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 abc544dde6920d853f007b8774acd749447b4970..30908963ae26159d96c62f56654df892c4c7576e 100644 --- a/Documentation/devicetree/bindings/arm/mediatek.yaml +++ b/Documentation/devicetree/bindings/arm/mediatek.yaml @@ -114,4 +114,9 @@ properties: - 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/mediatek/mediatek,pericfg.yaml b/Documentation/devicetree/bindings/arm/mediatek/mediatek,pericfg.yaml index e271c4682ebcd66c00e9c244f7c45832144cdc1f..1af30174b2d053670f6c2e27563377276308ac03 100644 --- a/Documentation/devicetree/bindings/arm/mediatek/mediatek,pericfg.yaml +++ b/Documentation/devicetree/bindings/arm/mediatek/mediatek,pericfg.yaml @@ -17,22 +17,22 @@ properties: compatible: oneOf: - items: - - enum: - - mediatek,mt2701-pericfg - - mediatek,mt2712-pericfg - - mediatek,mt6765-pericfg - - mediatek,mt7622-pericfg - - mediatek,mt7629-pericfg - - mediatek,mt8135-pericfg - - mediatek,mt8173-pericfg - - mediatek,mt8183-pericfg - - mediatek,mt8516-pericfg - - const: syscon + - enum: + - mediatek,mt2701-pericfg + - mediatek,mt2712-pericfg + - mediatek,mt6765-pericfg + - mediatek,mt7622-pericfg + - mediatek,mt7629-pericfg + - mediatek,mt8135-pericfg + - mediatek,mt8173-pericfg + - mediatek,mt8183-pericfg + - mediatek,mt8516-pericfg + - const: syscon - items: - # Special case for mt7623 for backward compatibility - - const: mediatek,mt7623-pericfg - - const: mediatek,mt2701-pericfg - - const: syscon + # Special case for mt7623 for backward compatibility + - const: mediatek,mt7623-pericfg + - const: mediatek,mt2701-pericfg + - const: syscon reg: maxItems: 1 diff --git a/Documentation/devicetree/bindings/arm/microchip,sparx5.yaml b/Documentation/devicetree/bindings/arm/microchip,sparx5.yaml new file mode 100644 index 0000000000000000000000000000000000000000..ecf6fa12e6ad26c63ea20e98666caa1112877e89 --- /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 + +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 0000000000000000000000000000000000000000..6816bd68f9cf16a7e04fd6347caebacd47a77633 --- /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 + +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 0000000000000000000000000000000000000000..c2f980b00b0670cdeb9fad851b5abfd53d3fdd3a --- /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 + +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 0000000000000000000000000000000000000000..1043e4be4fcaedb74d8da3ab81f8e65d3d5bfb02 --- /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 + - Jonathan Hunter + - Sumit Gupta + +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 b7d2e921150a8092c5d71446ff82ee8fa6c3ceb9..0d4dabb4a1646ab87eccc0010af855194bd2de93 100644 --- a/Documentation/devicetree/bindings/arm/renesas.yaml +++ b/Documentation/devicetree/bindings/arm/renesas.yaml @@ -118,6 +118,7 @@ properties: 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 @@ properties: - 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 d4a4045092dfe6ff1722945e7a9c557e06d617e6..db2e357967952628d178ec98dfcbb45a0c092491 100644 --- a/Documentation/devicetree/bindings/arm/rockchip.yaml +++ b/Documentation/devicetree/bindings/arm/rockchip.yaml @@ -435,6 +435,12 @@ properties: - 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 cf5db5e273f327cf00300dab7970e38492db5b96..6f1cd0103c74acd3910a09cdf45e27fd342ee4cf 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 @@ properties: - items: - enum: - st,stm32mp157-syscfg + - st,stm32mp151-pwr-mcu + - st,stm32-syscfg + - st,stm32-power-config - const: syscon reg: @@ -27,7 +30,16 @@ properties: 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 87817ff0cd358d876d9fca38def37726b06f8139..efc9118233b4bd956ddee1460a775583c1f1311b 100644 --- a/Documentation/devicetree/bindings/arm/sunxi.yaml +++ b/Documentation/devicetree/bindings/arm/sunxi.yaml @@ -657,6 +657,11 @@ properties: - 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 60b38eb5c61ab276b2d99b516cf9205f540ef5a8..e0b3debaee9e4033717ff347cfc44272be31c264 100644 --- a/Documentation/devicetree/bindings/arm/tegra.yaml +++ b/Documentation/devicetree/bindings/arm/tegra.yaml @@ -34,6 +34,9 @@ properties: - toradex,colibri_t20-iris - const: toradex,colibri_t20 - const: nvidia,tegra20 + - items: + - const: acer,picasso + - const: nvidia,tegra20 - items: - enum: - nvidia,beaver @@ -59,6 +62,13 @@ properties: - toradex,colibri_t30-eval-v3 - 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 @@ -101,3 +111,11 @@ properties: - 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/baikal,bt1-apb.yaml b/Documentation/devicetree/bindings/bus/baikal,bt1-apb.yaml index 68b0131a31d0fca76858ff538c008cabd86e290a..37ba3337f944a1cea91ada2dceb58c6b6838305d 100644 --- a/Documentation/devicetree/bindings/bus/baikal,bt1-apb.yaml +++ b/Documentation/devicetree/bindings/bus/baikal,bt1-apb.yaml @@ -19,7 +19,7 @@ description: | reported to the APB terminator (APB Errors Handler Block). allOf: - - $ref: /schemas/simple-bus.yaml# + - $ref: /schemas/simple-bus.yaml# properties: compatible: diff --git a/Documentation/devicetree/bindings/bus/baikal,bt1-axi.yaml b/Documentation/devicetree/bindings/bus/baikal,bt1-axi.yaml index 29e1aaea132bb7194623f3432b52308310e6f173..0bee4694578a14abeab3cf7be467eed734fa3b1d 100644 --- a/Documentation/devicetree/bindings/bus/baikal,bt1-axi.yaml +++ b/Documentation/devicetree/bindings/bus/baikal,bt1-axi.yaml @@ -23,7 +23,7 @@ description: | accessible by means of the Baikal-T1 System Controller. allOf: - - $ref: /schemas/simple-bus.yaml# + - $ref: /schemas/simple-bus.yaml# properties: compatible: 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 0000000000000000000000000000000000000000..9cc2d5f1beef89e17ad8884805a29e471137e6ee --- /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 + +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/clock/brcm,bcm2711-dvp.yaml b/Documentation/devicetree/bindings/clock/brcm,bcm2711-dvp.yaml new file mode 100644 index 0000000000000000000000000000000000000000..08543ecbe35b294c07d2c6b48d1681244b083d76 --- /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 + +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 3041657e2f96e83520c6f13bc843db4fbf9f7dc1..3e7ca5530775349371d8fb5543ef517f52f37901 100644 --- a/Documentation/devicetree/bindings/clock/brcm,bcm63xx-clocks.txt +++ b/Documentation/devicetree/bindings/clock/brcm,bcm63xx-clocks.txt @@ -3,6 +3,8 @@ Gated Clock Controller Bindings for MIPS based BCM63XX SoCs 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 8a55fdcf96eeab11c4976c51c11587824d191086..f2ea53832ac63eac9f34b5db49ff3995d23e6522 100644 --- a/Documentation/devicetree/bindings/clock/clock-bindings.txt +++ b/Documentation/devicetree/bindings/clock/clock-bindings.txt @@ -9,7 +9,7 @@ specifier is an array of zero, one or more cells identifying the clock 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 bcff681a4bd0b5c0abbe534b2540517fea49b62c..0000000000000000000000000000000000000000 --- 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 0000000000000000000000000000000000000000..28c6461b9a9a18c29bcdbf6aa58097b9bde07823 --- /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 + +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 + + /* 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 = ; + idt,voltage-microvolts = <1800000>; + idt,slew-percent = <80>; + }; + + OUT4 { + idt,drive-mode = ; + }; + }; + }; + + /* Consumer referencing the 5P49V5923 pin OUT1 */ + consumer { + /* ... */ + clocks = <&vc5 1>; + /* ... */ + }; + +... diff --git a/Documentation/devicetree/bindings/clock/imx23-clock.yaml b/Documentation/devicetree/bindings/clock/imx23-clock.yaml index 66cb238a1040cd497aebba9490b6d3c5e301ded4..ad21899981af8869f41eb56233295494054215e0 100644 --- a/Documentation/devicetree/bindings/clock/imx23-clock.yaml +++ b/Documentation/devicetree/bindings/clock/imx23-clock.yaml @@ -7,7 +7,7 @@ $schema: http://devicetree.org/meta-schemas/core.yaml# title: Clock bindings for Freescale i.MX23 maintainers: - - Shawn Guo + - Shawn Guo description: | The clock consumer should specify the desired clock by having the clock diff --git a/Documentation/devicetree/bindings/clock/imx28-clock.yaml b/Documentation/devicetree/bindings/clock/imx28-clock.yaml index 72328d5ca09acd92d97fb700c96e14158253f0e3..f1af1108129eec4c5ed3718a8f44c169298d251f 100644 --- a/Documentation/devicetree/bindings/clock/imx28-clock.yaml +++ b/Documentation/devicetree/bindings/clock/imx28-clock.yaml @@ -7,7 +7,7 @@ $schema: http://devicetree.org/meta-schemas/core.yaml# title: Clock bindings for Freescale i.MX28 maintainers: - - Shawn Guo + - Shawn Guo 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 bd871da6fc7c6716c39e3978b248ad7c9cde2063..3e20ccaf81318314cc49c42a070740d27aad5bc0 100644 --- a/Documentation/devicetree/bindings/clock/imx35-clock.yaml +++ b/Documentation/devicetree/bindings/clock/imx35-clock.yaml @@ -130,7 +130,7 @@ examples: #clock-cells = <1>; }; - esdhc@53fb4000 { + mmc@53fb4000 { compatible = "fsl,imx35-esdhc"; reg = <0x53fb4000 0x4000>; interrupts = <7>; diff --git a/Documentation/devicetree/bindings/clock/imx7ulp-clock.txt b/Documentation/devicetree/bindings/clock/imx7ulp-clock.txt deleted file mode 100644 index 93d89adb7afe7b946b471b8f5e3b8986d2877924..0000000000000000000000000000000000000000 --- 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 - -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 = ; - 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 0000000000000000000000000000000000000000..7caf5cee919970733aa97afb4ee5c486857180fd --- /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 + +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 + #include + + 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 = ; + 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 0000000000000000000000000000000000000000..ee8efb4ed5999eb639a1d37306fcc8e7c6067808 --- /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 + +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 + #include + + 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 = ; + 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 33f3010f48c3b9d16f03a521ce21ac12f9fd3563..1d5e9bcce4c82d6e55b10fb691f1a6cf46717cf7 100644 --- a/Documentation/devicetree/bindings/clock/imx8qxp-lpcg.yaml +++ b/Documentation/devicetree/bindings/clock/imx8qxp-lpcg.yaml @@ -62,7 +62,7 @@ examples: }; mmc@5b010000 { - compatible = "fsl,imx8qxp-usdhc", "fsl,imx7d-usdhc"; + compatible = "fsl,imx8qxp-usdhc"; interrupts = ; reg = <0x5b010000 0x10000>; clocks = <&conn_lpcg IMX_CONN_LPCG_SDHC0_IPG_CLK>, diff --git a/Documentation/devicetree/bindings/clock/ingenic,cgu.yaml b/Documentation/devicetree/bindings/clock/ingenic,cgu.yaml index a952d5811823283785aef2313a8b5a6d722b7807..5dd7ea8a78e4bafb38d4e5419df9469db9d49582 100644 --- a/Documentation/devicetree/bindings/clock/ingenic,cgu.yaml +++ b/Documentation/devicetree/bindings/clock/ingenic,cgu.yaml @@ -47,12 +47,12 @@ properties: compatible: items: - enum: - - ingenic,jz4740-cgu - - ingenic,jz4725b-cgu - - ingenic,jz4770-cgu - - ingenic,jz4780-cgu - - ingenic,x1000-cgu - - ingenic,x1830-cgu + - ingenic,jz4740-cgu + - ingenic,jz4725b-cgu + - ingenic,jz4770-cgu + - ingenic,jz4780-cgu + - ingenic,x1000-cgu + - ingenic,x1830-cgu - const: simple-mfd minItems: 1 @@ -68,8 +68,8 @@ properties: items: - const: ext - enum: - - rtc - - osc32k # Different name, same clock + - rtc + - osc32k # Different name, same clock assigned-clocks: minItems: 1 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 0000000000000000000000000000000000000000..39559a0a598ad0289b2a667df22cf5981c72b303 --- /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 + +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 20d2638b4cd2397bbf2786a634ff640bd5638e4c..db3d0ea6bc7a91fd776aa40b4976d2c7c472ad8b 100644 --- a/Documentation/devicetree/bindings/clock/qcom,a53pll.yaml +++ b/Documentation/devicetree/bindings/clock/qcom,a53pll.yaml @@ -15,7 +15,9 @@ description: properties: compatible: - const: qcom,msm8916-a53pll + enum: + - qcom,ipq6018-a53pll + - qcom,msm8916-a53pll reg: maxItems: 1 @@ -23,6 +25,14 @@ properties: '#clock-cells': const: 0 + clocks: + items: + - description: board XO clock + + clock-names: + items: + - const: xo + required: - compatible - reg @@ -38,3 +48,12 @@ examples: 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 0000000000000000000000000000000000000000..df943c4c32345f3b080e6465fd69f28a3980f419 --- /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 + +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 + #include + 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,mmcc.yaml b/Documentation/devicetree/bindings/clock/qcom,mmcc.yaml index 1b16a863b3556ca955e2fa435d8f81cfe0b53a14..af32dee14fc67e0da20fc15163b629188b10d284 100644 --- a/Documentation/devicetree/bindings/clock/qcom,mmcc.yaml +++ b/Documentation/devicetree/bindings/clock/qcom,mmcc.yaml @@ -65,7 +65,7 @@ properties: protected-clocks: description: - Protected clock specifier list as per common clock binding + Protected clock specifier list as per common clock binding vdd-gfx-supply: description: 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 0000000000000000000000000000000000000000..a20cb10636dd45bb731c0b11e5bead0804eca35a --- /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 + +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 90a1349bc7135dc99138fb1575d81dc5b5291bee..b44a0622fb3ace2eb25782ce23c67889550bcbc4 100644 --- a/Documentation/devicetree/bindings/clock/qcom,rpmcc.txt +++ b/Documentation/devicetree/bindings/clock/qcom,rpmcc.txt @@ -13,13 +13,17 @@ Required properties : "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 fe08461fce051bfb79910037f196f68c89d8055c..0000000000000000000000000000000000000000 --- 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 - -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 - #include - 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 0000000000000000000000000000000000000000..c54172fbf29fdd1a417151ed97084a9b6355aad3 --- /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 + +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 + #include + #include + 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 + #include + #include + 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 8a0c576ba8b3c2fad3b3080a85b4a2282c2710ab..0000000000000000000000000000000000000000 --- 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 - -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 - #include - 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 0000000000000000000000000000000000000000..9185d101737e4d30c0a13955c98dcfc4d2629ff5 --- /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 + +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 + 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 c745bd60719ab7bb56f88bc0ef97ea7f44995934..e13aee8ab61ad47b1654b1e8079da81b24b19192 100644 --- a/Documentation/devicetree/bindings/clock/renesas,cpg-mssr.yaml +++ b/Documentation/devicetree/bindings/clock/renesas,cpg-mssr.yaml @@ -33,6 +33,7 @@ properties: - 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 ece92393e80d464832f07e0c1fb798b672ec5e89..0000000000000000000000000000000000000000 --- 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 2c03302f86edfb836755ef7c747f81d0fca438f1..0000000000000000000000000000000000000000 --- 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 7cc4c0330b534660d97758ce9a7e8f304670db8a..0000000000000000000000000000000000000000 --- 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 8c81547c29f568e8196537111891c19820b288f3..0000000000000000000000000000000000000000 --- 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 8ff3e2774ed8d1d0fd46cbf5895346f62252c5b0..0000000000000000000000000000000000000000 --- 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 a8978ec94831fc6beb8787b0b12fd88b70920dcd..0000000000000000000000000000000000000000 --- 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 8cb47c39ba53922e100bff2efd10420ed5af626a..bf3a9ec1924168a8a569e4d26b31cff5d8917903 100644 --- a/Documentation/devicetree/bindings/clock/rockchip,rk3288-cru.txt +++ b/Documentation/devicetree/bindings/clock/rockchip,rk3288-cru.txt @@ -4,9 +4,15 @@ The RK3288 clock controller generates and supplies clock to various 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 ea1a9dbc63b6a4e7e5acc9e4868754213fb509aa..a4f28ec86f3555d091a5618427af1e2e9d8ba365 100644 --- a/Documentation/devicetree/bindings/clock/silabs,si514.txt +++ b/Documentation/devicetree/bindings/clock/silabs,si514.txt @@ -6,7 +6,7 @@ found in the datasheet[2]. [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 f00191cad8cdf4f3b8f4d2f6330521cf6173cc8d..8fe6f80afadee1dd54d47f3bf8ac35ea27913dd4 100644 --- a/Documentation/devicetree/bindings/clock/silabs,si5351.txt +++ b/Documentation/devicetree/bindings/clock/silabs,si5351.txt @@ -2,7 +2,7 @@ Binding for Silicon Labs Si5351a/b/c programmable i2c clock generator. 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 c09f21e1d98f01aed334211936f04972d3acaf8c..901935e929d2fd0a608d1ee38000c3d9c2af926c 100644 --- a/Documentation/devicetree/bindings/clock/silabs,si570.txt +++ b/Documentation/devicetree/bindings/clock/silabs,si570.txt @@ -7,9 +7,9 @@ found in the data sheets[2][3]. [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/sprd,sc9863a-clk.yaml b/Documentation/devicetree/bindings/clock/sprd,sc9863a-clk.yaml index 29813873cfbcae7afa4fe84f258ac96078ab1ffc..c6d091518650ca6eecbf605d3238c91391afb8d9 100644 --- a/Documentation/devicetree/bindings/clock/sprd,sc9863a-clk.yaml +++ b/Documentation/devicetree/bindings/clock/sprd,sc9863a-clk.yaml @@ -16,7 +16,7 @@ properties: "#clock-cells": const: 1 - compatible : + compatible: enum: - sprd,sc9863a-ap-clk - sprd,sc9863a-aon-clk diff --git a/Documentation/devicetree/bindings/clock/ti,cdce706.txt b/Documentation/devicetree/bindings/clock/ti,cdce706.txt index 959d96632f5d20496285cadcb0da4d1253145b0c..21c3ff76478875d632c2fa3f3bfa7f056085fa92 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 26544c85202af9406c9ce77815660768b4a3b5b2..df42ab72718ff29fd7aee97ae53c823b8d207d34 100644 --- a/Documentation/devicetree/bindings/clock/ti,cdce925.txt +++ b/Documentation/devicetree/bindings/clock/ti,cdce925.txt @@ -4,10 +4,10 @@ Reference 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 332aed8f4597a86240e498f03933497028a66029..56f4423743838fcba50511a12cedd7e301bb3194 100644 --- a/Documentation/devicetree/bindings/cpufreq/cpufreq-dt.txt +++ b/Documentation/devicetree/bindings/cpufreq/cpufreq-dt.txt @@ -18,7 +18,8 @@ Optional properties: 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 0551c78619de807b99908d76eaf76cd6831ee3a5..ea4994b35207d9757997d80de6a05bd73a300828 100644 --- a/Documentation/devicetree/bindings/cpufreq/cpufreq-mediatek.txt +++ b/Documentation/devicetree/bindings/cpufreq/cpufreq-mediatek.txt @@ -21,8 +21,8 @@ Optional properties: 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 daeca6ae6b769b1084058ce0922d92f6bbc40076..52a24b82fd8643fd8eb72cd37d6d2a9fca2aa8ce 100644 --- a/Documentation/devicetree/bindings/cpufreq/nvidia,tegra20-cpufreq.txt +++ b/Documentation/devicetree/bindings/cpufreq/nvidia,tegra20-cpufreq.txt @@ -5,7 +5,7 @@ Required properties: - 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/allwinner,sun4i-a10-crypto.yaml b/Documentation/devicetree/bindings/crypto/allwinner,sun4i-a10-crypto.yaml index fc823572bcff2dd2139e06478650a0d491c8303b..90c6d039b91b091535d28f1b71e45d72eda5dc20 100644 --- a/Documentation/devicetree/bindings/crypto/allwinner,sun4i-a10-crypto.yaml +++ b/Documentation/devicetree/bindings/crypto/allwinner,sun4i-a10-crypto.yaml @@ -23,8 +23,7 @@ properties: - items: - const: allwinner,sun7i-a20-crypto - const: allwinner,sun4i-a10-crypto - - items: - - const: allwinner,sun8i-a33-crypto + - const: allwinner,sun8i-a33-crypto reg: maxItems: 1 @@ -59,7 +58,9 @@ if: properties: compatible: contains: - const: allwinner,sun6i-a31-crypto + enum: + - allwinner,sun6i-a31-crypto + - allwinner,sun8i-a33-crypto then: required: diff --git a/Documentation/devicetree/bindings/crypto/ti,sa2ul.yaml b/Documentation/devicetree/bindings/crypto/ti,sa2ul.yaml new file mode 100644 index 0000000000000000000000000000000000000000..1465c9ebaf938c6d2ea2288e7b0f697dd6f7bba7 --- /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 + +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 + + main_crypto: crypto@4e00000 { + compatible = "ti,j721-sa2ul"; + reg = <0x4e00000 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 0ec68141f85a7c05aa04b10c277b3ad02af43942..a10d1f6d85c64ef5443aca1b64ec88425b0e8eff 100644 --- a/Documentation/devicetree/bindings/devfreq/rk3399_dmc.txt +++ b/Documentation/devicetree/bindings/devfreq/rk3399_dmc.txt @@ -18,6 +18,8 @@ Optional properties: 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 1dee641e3ea168b724a56f4e6f5ca3a423874acb..c040eef5651820d1aef3579382b2cc297740ab96 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 @@ properties: - 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 26649b4c4dd8de41ab16a6f76f8e73dcac2525a1..0000000000000000000000000000000000000000 --- 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 0000000000000000000000000000000000000000..5c1024bbc1b30c61d8f0b58e85e69187e7a1cc5f --- /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 + +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 + + 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 0000000000000000000000000000000000000000..3c643b227a70cae4aeac9f3b9e4b9e3f7f009299 --- /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 + +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 + + 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 0000000000000000000000000000000000000000..f54b4e4808f075180d7326063fe2dbbaadf87436 --- /dev/null +++ b/Documentation/devicetree/bindings/display/brcm,bcm2835-hdmi.yaml @@ -0,0 +1,79 @@ +# 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 + +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: + $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 + #include + + 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 0000000000000000000000000000000000000000..02410f8d6d4985f0a3dc8d4b9515da2ef5914c16 --- /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 + +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 0000000000000000000000000000000000000000..e60791db1fa12dbe992812244ede905208607033 --- /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 + +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 0000000000000000000000000000000000000000..bb186197e471eb4ff7d8c76e2af48975f6f270fe --- /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 + +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 0000000000000000000000000000000000000000..8a73780f573d355b9b91110b3058406ceb821fe1 --- /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 + +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 0000000000000000000000000000000000000000..0dcf0c3973759b5bb571dcfa876772e20f388137 --- /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 + +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 0000000000000000000000000000000000000000..d900cc57b4ec9f787aab97da2c443a19148cd16f --- /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 + +properties: + compatible: + const: brcm,bcm2835-vec + + reg: + maxItems: 1 + + clocks: + maxItems: 1 + + interrupts: + maxItems: 1 + +required: + - compatible + - reg + - clocks + - interrupts + +additionalProperties: false + +examples: + - | + #include + + 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 8aff2d68fc33a66752edbbdf3a2a5de7992c86cb..04099f5bea3f08e44a7ba042c59897a6917ccfe7 100644 --- a/Documentation/devicetree/bindings/display/bridge/nwl-dsi.yaml +++ b/Documentation/devicetree/bindings/display/bridge/nwl-dsi.yaml @@ -162,13 +162,13 @@ required: additionalProperties: false examples: - - | + - | + #include + #include + #include + #include - #include - #include - #include - - mipi_dsi: mipi_dsi@30a00000 { + mipi_dsi: mipi_dsi@30a00000 { #address-cells = <1>; #size-cells = <0>; compatible = "fsl,imx8mq-nwl-dsi"; @@ -191,12 +191,12 @@ examples: 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>; }; @@ -223,4 +223,4 @@ examples: }; }; }; - }; + }; 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 c62ce2494ed9e57732e58a128d6a7b4f1dc20f08..0000000000000000000000000000000000000000 --- 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 0000000000000000000000000000000000000000..baaf2a2a6fed37b3d3156576ab1cec14406ec9c8 --- /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 + +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 + #include + + 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 + #include + + 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/simple-bridge.yaml b/Documentation/devicetree/bindings/display/bridge/simple-bridge.yaml index 0880cbf217d5e2624ffe41f0b9c5ff8293fa596a..3ddb35fcf0a2cd6483946f973fab45b7cfafdc0d 100644 --- a/Documentation/devicetree/bindings/display/bridge/simple-bridge.yaml +++ b/Documentation/devicetree/bindings/display/bridge/simple-bridge.yaml @@ -18,16 +18,16 @@ properties: compatible: oneOf: - items: - - enum: - - ti,ths8134a - - ti,ths8134b - - const: ti,ths8134 + - enum: + - ti,ths8134a + - ti,ths8134b + - const: ti,ths8134 - enum: - - adi,adv7123 - - dumb-vga-dac - - ti,opa362 - - ti,ths8134 - - ti,ths8135 + - adi,adv7123 + - dumb-vga-dac + - ti,opa362 + - ti,ths8134 + - ti,ths8135 ports: type: object 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 8ec4a7f2623a30f9a51465577fbd05c14b8bc341..0000000000000000000000000000000000000000 --- 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 0000000000000000000000000000000000000000..f8622bd0f61ee62d232af4e5417f30e8fb564d61 --- /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 + +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 + #include + #include + + 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 + #include + #include + + 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 5ff4f64ef8e85a961892da76f06f317650429822..0000000000000000000000000000000000000000 --- 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 0000000000000000000000000000000000000000..605831c1e8366eb045b04460cfeaaa4ecec04b87 --- /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 + - Jyri Sarha + +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 + + 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 883bcb2604c7cd0c60de98f150bc159235f62d6b..0000000000000000000000000000000000000000 --- 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 - -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 0000000000000000000000000000000000000000..eebe88fed999e9f269a9a1a732d1e5c61f3c5940 --- /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 + +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 + + 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 207e42e9eba0e1b17a0d0fcc6a7cf32b8209b4c9..0000000000000000000000000000000000000000 --- 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 0000000000000000000000000000000000000000..71cb9220fa593e500df65b09c67e50d4611b91ac --- /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 + +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 aeb07c4bd7039d3a6e71fa7f7af65cf520d92abc..0000000000000000000000000000000000000000 --- 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 0000000000000000000000000000000000000000..14d7128af592a98fadd532d2266dec3f81a0641c --- /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 + +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 c727f298e7ad087de6108f32a72a9ae06f519e8b..0000000000000000000000000000000000000000 --- 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 0000000000000000000000000000000000000000..5782c4bb3252ba43bde59e1b514d8b83210b3b4f --- /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 + +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/dsi-controller.yaml b/Documentation/devicetree/bindings/display/dsi-controller.yaml index 85b71b1fd28a28b4bc32e45ec49df508e3efdcc2..a02039e3aca0e31d786c91dbec6c6b5dd620b97a 100644 --- a/Documentation/devicetree/bindings/display/dsi-controller.yaml +++ b/Documentation/devicetree/bindings/display/dsi-controller.yaml @@ -55,11 +55,11 @@ patternProperties: clock-master: type: boolean description: - Should be enabled if the host is being used in conjunction with - another DSI host to drive the same peripheral. Hardware supporting - such a configuration generally requires the data on both the busses - to be driven by the same clock. Only the DSI host instance - controlling this clock should contain this property. + Should be enabled if the host is being used in conjunction with + another DSI host to drive the same peripheral. Hardware supporting + such a configuration generally requires the data on both the busses + to be driven by the same clock. Only the DSI host instance + controlling this clock should contain this property. enforce-video-mode: type: boolean diff --git a/Documentation/devicetree/bindings/display/ilitek,ili9486.yaml b/Documentation/devicetree/bindings/display/ilitek,ili9486.yaml index 66e93e563653a1efc37629ac7c5e7ff0b96fa779..aecff34f505d706328562fac15555268ab4262d2 100644 --- a/Documentation/devicetree/bindings/display/ilitek,ili9486.yaml +++ b/Documentation/devicetree/bindings/display/ilitek,ili9486.yaml @@ -21,9 +21,9 @@ properties: items: - enum: # Waveshare 3.5" 320x480 Color TFT LCD - - waveshare,rpi-lcd-35 + - waveshare,rpi-lcd-35 # Ozzmaker 3.5" 320x480 Color TFT LCD - - ozzmaker,piscreen + - ozzmaker,piscreen - const: ilitek,ili9486 spi-max-frequency: diff --git a/Documentation/devicetree/bindings/display/ingenic,ipu.yaml b/Documentation/devicetree/bindings/display/ingenic,ipu.yaml new file mode 100644 index 0000000000000000000000000000000000000000..12064a8e7a92a09de004d31a8abd1abd2794bc3b --- /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 + +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 + 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 01e3261defb6a97a3bbaf41604b6693e74b18b2f..0000000000000000000000000000000000000000 --- 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 0000000000000000000000000000000000000000..768050f30dbaf1287bc2fd8ae32574670cfd8e4b --- /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 + +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 + 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 + 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 af95586c898f93efdba931d94f840d00111e5703..7884fd7a85c12feec6c73ba69ef0c84734ce3002 100644 --- a/Documentation/devicetree/bindings/display/msm/dsi.txt +++ b/Documentation/devicetree/bindings/display/msm/dsi.txt @@ -87,6 +87,7 @@ Required properties: * "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/gmu.yaml b/Documentation/devicetree/bindings/display/msm/gmu.yaml index 0b8736a9384eb82a612a8ec51e720618bf51fab5..53056dd025977901629378467eea46661ef929e0 100644 --- a/Documentation/devicetree/bindings/display/msm/gmu.yaml +++ b/Documentation/devicetree/bindings/display/msm/gmu.yaml @@ -38,10 +38,10 @@ properties: clocks: items: - - description: GMU clock - - description: GPU CX clock - - description: GPU AXI clock - - description: GPU MEMNOC clock + - description: GMU clock + - description: GPU CX clock + - description: GPU AXI clock + - description: GPU MEMNOC clock clock-names: items: @@ -52,8 +52,8 @@ properties: interrupts: items: - - description: GMU HFI interrupt - - description: GMU interrupt + - description: GMU HFI interrupt + - description: GMU interrupt interrupt-names: @@ -62,14 +62,14 @@ properties: - const: gmu power-domains: - items: - - description: CX power domain - - description: GX power domain + items: + - description: CX power domain + - description: GX power domain power-domain-names: - items: - - const: cx - - const: gx + items: + - const: cx + - const: gx iommus: maxItems: 1 @@ -90,13 +90,13 @@ required: - operating-points-v2 examples: - - | - #include - #include - #include - #include + - | + #include + #include + #include + #include - gmu: gmu@506a000 { + gmu: gmu@506a000 { compatible="qcom,adreno-gmu-630.2", "qcom,adreno-gmu"; reg = <0x506a000 0x30000>, @@ -120,4 +120,4 @@ examples: iommus = <&adreno_smmu 5>; operating-points-v2 = <&gmu_opp_table>; - }; + }; diff --git a/Documentation/devicetree/bindings/display/msm/gpu.txt b/Documentation/devicetree/bindings/display/msm/gpu.txt index fd779cd6994d8e6a1410282ae61c8060c940c8b8..1af0ff102b5073a272824fe2858759668a768722 100644 --- a/Documentation/devicetree/bindings/display/msm/gpu.txt +++ b/Documentation/devicetree/bindings/display/msm/gpu.txt @@ -112,6 +112,34 @@ Example a6xx (with GMU): 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 = ; + opp-peak-kBps = <5412000>; + }; + + opp-355000000 { + opp-hz = /bits/ 64 <355000000>; + opp-level = ; + opp-peak-kBps = <3072000>; + }; + + opp-267000000 { + opp-hz = /bits/ 64 <267000000>; + opp-level = ; + opp-peak-kBps = <3072000>; + }; + + opp-180000000 { + opp-hz = /bits/ 64 <180000000>; + opp-level = ; + opp-peak-kBps = <1804000>; + }; + }; + qcom,gmu = <&gmu>; zap-shader { diff --git a/Documentation/devicetree/bindings/display/panel/asus,z00t-tm5p5-nt35596.yaml b/Documentation/devicetree/bindings/display/panel/asus,z00t-tm5p5-nt35596.yaml index 083d2b9d0c69a19ed2432008d62a2e187b6c7011..75a09df68ba00b0cdfc5a5064cdd809cb7849a05 100644 --- a/Documentation/devicetree/bindings/display/panel/asus,z00t-tm5p5-nt35596.yaml +++ b/Documentation/devicetree/bindings/display/panel/asus,z00t-tm5p5-nt35596.yaml @@ -24,9 +24,9 @@ properties: reg: true reset-gpios: true vdd-supply: - description: core voltage supply + description: core voltage supply vddio-supply: - description: vddio supply + description: vddio supply required: - compatible diff --git a/Documentation/devicetree/bindings/display/panel/boe,tv101wum-nl6.yaml b/Documentation/devicetree/bindings/display/panel/boe,tv101wum-nl6.yaml index 7f5df585101731a4edd7869849ea4125802ba437..38bc1d1b511eb30ae9fcc3de3510be8e05039411 100644 --- a/Documentation/devicetree/bindings/display/panel/boe,tv101wum-nl6.yaml +++ b/Documentation/devicetree/bindings/display/panel/boe,tv101wum-nl6.yaml @@ -48,12 +48,12 @@ properties: port: true required: - - compatible - - reg - - enable-gpios - - pp1800-supply - - avdd-supply - - avee-supply + - compatible + - reg + - enable-gpios + - pp1800-supply + - avdd-supply + - avee-supply additionalProperties: false diff --git a/Documentation/devicetree/bindings/display/panel/elida,kd35t133.yaml b/Documentation/devicetree/bindings/display/panel/elida,kd35t133.yaml index aa761f697b7ae52305d58a2cef70668719dc0e24..7adb83e2e8d940e92e84ea9252fb1e75123dcbc5 100644 --- a/Documentation/devicetree/bindings/display/panel/elida,kd35t133.yaml +++ b/Documentation/devicetree/bindings/display/panel/elida,kd35t133.yaml @@ -19,9 +19,9 @@ properties: backlight: true reset-gpios: true iovcc-supply: - description: regulator that supplies the iovcc voltage + description: regulator that supplies the iovcc voltage vdd-supply: - description: regulator that supplies the vdd voltage + description: regulator that supplies the vdd voltage required: - compatible diff --git a/Documentation/devicetree/bindings/display/panel/feixin,k101-im2ba02.yaml b/Documentation/devicetree/bindings/display/panel/feixin,k101-im2ba02.yaml index 927f1eea18d26296d9c3836ed0123f3181e999bc..81adb82f061d2c1183202e2e9445b56e01bf126b 100644 --- a/Documentation/devicetree/bindings/display/panel/feixin,k101-im2ba02.yaml +++ b/Documentation/devicetree/bindings/display/panel/feixin,k101-im2ba02.yaml @@ -19,11 +19,11 @@ properties: backlight: true reset-gpios: true avdd-supply: - description: regulator that supplies the AVDD voltage + description: regulator that supplies the AVDD voltage dvdd-supply: - description: regulator that supplies the DVDD voltage + description: regulator that supplies the DVDD voltage cvdd-supply: - description: regulator that supplies the CVDD voltage + description: regulator that supplies the CVDD voltage required: - compatible diff --git a/Documentation/devicetree/bindings/display/panel/ilitek,ili9322.yaml b/Documentation/devicetree/bindings/display/panel/ilitek,ili9322.yaml index 177d48c5bd972b061eb9a489374e3ce22aa7d43e..e89c1ea62ffa9f7a5db74b5e54a6aa9857efeb19 100644 --- a/Documentation/devicetree/bindings/display/panel/ilitek,ili9322.yaml +++ b/Documentation/devicetree/bindings/display/panel/ilitek,ili9322.yaml @@ -25,8 +25,7 @@ properties: compatible: items: - enum: - - dlink,dir-685-panel - + - dlink,dir-685-panel - const: ilitek,ili9322 reset-gpios: true diff --git a/Documentation/devicetree/bindings/display/panel/ilitek,ili9881c.yaml b/Documentation/devicetree/bindings/display/panel/ilitek,ili9881c.yaml index a39332276bab2875c45e93a5661e2c83afb8515d..76a9068a85dde1bad2a69c36781706f9ccbdafb8 100644 --- a/Documentation/devicetree/bindings/display/panel/ilitek,ili9881c.yaml +++ b/Documentation/devicetree/bindings/display/panel/ilitek,ili9881c.yaml @@ -13,8 +13,7 @@ properties: compatible: items: - enum: - - bananapi,lhr050h41 - + - bananapi,lhr050h41 - const: ilitek,ili9881c backlight: true 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 3ab8c7412cf65b8e41fd3921ace3a1b66300f781..0000000000000000000000000000000000000000 --- 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/leadtek,ltk050h3146w.yaml b/Documentation/devicetree/bindings/display/panel/leadtek,ltk050h3146w.yaml index a372bdc5bde18b738c1fc4148f7063292cac4636..3715882b63b6ace22e609371b63c70d161342197 100644 --- a/Documentation/devicetree/bindings/display/panel/leadtek,ltk050h3146w.yaml +++ b/Documentation/devicetree/bindings/display/panel/leadtek,ltk050h3146w.yaml @@ -21,9 +21,9 @@ properties: backlight: true reset-gpios: true iovcc-supply: - description: regulator that supplies the iovcc voltage + description: regulator that supplies the iovcc voltage vci-supply: - description: regulator that supplies the vci voltage + description: regulator that supplies the vci voltage required: - compatible diff --git a/Documentation/devicetree/bindings/display/panel/leadtek,ltk500hd1829.yaml b/Documentation/devicetree/bindings/display/panel/leadtek,ltk500hd1829.yaml index b900973b5f7b7622fba9ccd3f4b5720a61e159cf..c5944b4d636c54e65a9807bc93a88d5defa42d0a 100644 --- a/Documentation/devicetree/bindings/display/panel/leadtek,ltk500hd1829.yaml +++ b/Documentation/devicetree/bindings/display/panel/leadtek,ltk500hd1829.yaml @@ -19,9 +19,9 @@ properties: backlight: true reset-gpios: true iovcc-supply: - description: regulator that supplies the iovcc voltage + description: regulator that supplies the iovcc voltage vcc-supply: - description: regulator that supplies the vcc voltage + description: regulator that supplies the vcc voltage required: - compatible diff --git a/Documentation/devicetree/bindings/display/panel/novatek,nt35510.yaml b/Documentation/devicetree/bindings/display/panel/novatek,nt35510.yaml index 73d2ff3baaff16d5df0d5a9b8a039b834ea4c758..bc92928c805b9a10900552fce47c06a4d26c5a54 100644 --- a/Documentation/devicetree/bindings/display/panel/novatek,nt35510.yaml +++ b/Documentation/devicetree/bindings/display/panel/novatek,nt35510.yaml @@ -25,9 +25,9 @@ properties: reg: true reset-gpios: true vdd-supply: - description: regulator that supplies the vdd voltage + description: regulator that supplies the vdd voltage vddi-supply: - description: regulator that supplies the vddi voltage + description: regulator that supplies the vddi voltage backlight: true required: 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 dce48eb9db57ead8f5dfcab067e744c824690e24..0000000000000000000000000000000000000000 --- 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 0000000000000000000000000000000000000000..4a36aa64c716c9556d5a472c87ea875b0f7185db --- /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 + - Sebastian Reichel + +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 + + 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 16778ce782fc2bde3bef74bfddc741281eeee159..c0dd9fa29f1d215f6e9856ff2f234b65615975b1 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 @@ properties: - 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 d6cca1479633ab01b015b6be26b897ed87a9f2ab..6deeeed59e59f01d749ccd7acc1e47f9f30873b5 100644 --- a/Documentation/devicetree/bindings/display/panel/panel-simple.yaml +++ b/Documentation/devicetree/bindings/display/panel/panel-simple.yaml @@ -81,6 +81,10 @@ properties: - 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 @@ properties: - 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 @@ properties: - 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/panel-timing.yaml b/Documentation/devicetree/bindings/display/panel/panel-timing.yaml index 182c19cb7fdd8e6a259b3da4d183ee8c9b5dbf99..9bf592dc3033aa3efc90e9ddb721ebca5200c846 100644 --- a/Documentation/devicetree/bindings/display/panel/panel-timing.yaml +++ b/Documentation/devicetree/bindings/display/panel/panel-timing.yaml @@ -59,7 +59,7 @@ description: | properties: clock-frequency: - description: Panel clock in Hz + description: Panel clock in Hz hactive: $ref: /schemas/types.yaml#/definitions/uint32 @@ -200,15 +200,15 @@ properties: description: Enable double clock mode required: - - clock-frequency - - hactive - - vactive - - hfront-porch - - hback-porch - - hsync-len - - vfront-porch - - vback-porch - - vsync-len + - clock-frequency + - hactive + - vactive + - hfront-porch + - hback-porch + - hsync-len + - vfront-porch + - vback-porch + - vsync-len additionalProperties: false diff --git a/Documentation/devicetree/bindings/display/panel/raydium,rm68200.yaml b/Documentation/devicetree/bindings/display/panel/raydium,rm68200.yaml index a35ba16fc000e49114debfa1924ec95bc17cdfa1..39477793d289f373d85e86469bb01b9978a08bbd 100644 --- a/Documentation/devicetree/bindings/display/panel/raydium,rm68200.yaml +++ b/Documentation/devicetree/bindings/display/panel/raydium,rm68200.yaml @@ -10,8 +10,8 @@ maintainers: - Philippe CORNU description: | - The Raydium Semiconductor Corporation RM68200 is a 5.5" 720x1280 TFT LCD - panel connected using a MIPI-DSI video interface. + The Raydium Semiconductor Corporation RM68200 is a 5.5" 720x1280 TFT LCD + panel connected using a MIPI-DSI video interface. allOf: - $ref: panel-common.yaml# 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 a372c5d8469565d1ed80793e9a32a63f6efe4b05..0000000000000000000000000000000000000000 --- 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 0000000000000000000000000000000000000000..d5733ef30954952b199dc64e9658c86c7dcb038b --- /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 + +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 + + 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,s6e88a0-ams452ef01.yaml b/Documentation/devicetree/bindings/display/panel/samsung,s6e88a0-ams452ef01.yaml index 7a685d0428b3f7ff9578c499adda32b7b1fd3f56..44ce98f68705cf919d08251680f4e03734a58c27 100644 --- a/Documentation/devicetree/bindings/display/panel/samsung,s6e88a0-ams452ef01.yaml +++ b/Documentation/devicetree/bindings/display/panel/samsung,s6e88a0-ams452ef01.yaml @@ -18,9 +18,9 @@ properties: reg: true reset-gpios: true vdd3-supply: - description: core voltage supply + description: core voltage supply vci-supply: - description: voltage supply for analog circuits + description: voltage supply for analog circuits required: - compatible 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 9e766c5f86daf970cf7715a2d655b9fcebb1d35d..0000000000000000000000000000000000000000 --- 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 0000000000000000000000000000000000000000..ca959451557e08fc1e45802f9048f94eb48550de --- /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 + +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 f522bb8e47e1c7dc39dd7e8e21d6387bbc492df2..0000000000000000000000000000000000000000 --- 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 0000000000000000000000000000000000000000..a679d3647dbd40abccbd062df405c080af3cf8cb --- /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 + +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/panel/visionox,rm69299.yaml b/Documentation/devicetree/bindings/display/panel/visionox,rm69299.yaml index b36f39f6b23323a344b2d0f91696b04e9ed30c5e..076b057b4af54a33ec57d264071a69ebb18c21ed 100644 --- a/Documentation/devicetree/bindings/display/panel/visionox,rm69299.yaml +++ b/Documentation/devicetree/bindings/display/panel/visionox,rm69299.yaml @@ -7,7 +7,7 @@ $schema: http://devicetree.org/meta-schemas/core.yaml# title: Visionox model RM69299 Panels Device Tree Bindings. maintainers: - - Harigovindan P + - Harigovindan P description: | This binding is for display panels using a Visionox RM692999 panel. diff --git a/Documentation/devicetree/bindings/display/simple-framebuffer.yaml b/Documentation/devicetree/bindings/display/simple-framebuffer.yaml index 1db608c9eef59a0ad754554aea36d692fbe15fed..eaf8c54fcf506442e6ee90539b86981d448563fe 100644 --- a/Documentation/devicetree/bindings/display/simple-framebuffer.yaml +++ b/Documentation/devicetree/bindings/display/simple-framebuffer.yaml @@ -152,28 +152,28 @@ additionalProperties: false examples: - | - aliases { - display0 = &lcdc0; + / { + compatible = "foo"; + model = "foo"; + #address-cells = <1>; + #size-cells = <1>; + + 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>; + }; + }; }; - 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>; - }; - }; - - lcdc0: lcdc { }; - ... diff --git a/Documentation/devicetree/bindings/display/st,stm32-dsi.yaml b/Documentation/devicetree/bindings/display/st,stm32-dsi.yaml index 3be76d15bf6c732cfd4cbae99b273893d902b76f..69cc7e8bf15a1ac1bb617483a0f9c51b7796c83e 100644 --- a/Documentation/devicetree/bindings/display/st,stm32-dsi.yaml +++ b/Documentation/devicetree/bindings/display/st,stm32-dsi.yaml @@ -45,7 +45,7 @@ properties: phy-dsi-supply: description: - Phandle of the regulator that provides the supply voltage. + Phandle of the regulator that provides the supply voltage. ports: type: object @@ -147,4 +147,3 @@ examples: ... - diff --git a/Documentation/devicetree/bindings/display/ti/ti,j721e-dss.yaml b/Documentation/devicetree/bindings/display/ti/ti,j721e-dss.yaml index bbd76591c180bdc581c09f21f97e892658d61431..173730d56334d64c6978597d382b76ccbd64c0d1 100644 --- a/Documentation/devicetree/bindings/display/ti/ti,j721e-dss.yaml +++ b/Documentation/devicetree/bindings/display/ti/ti,j721e-dss.yaml @@ -78,7 +78,7 @@ properties: - const: vp4 interrupts: - items: + items: - description: common_m DSS Master common - description: common_s0 DSS Shared common 0 - description: common_s1 DSS Shared common 1 diff --git a/Documentation/devicetree/bindings/display/tilcdc/tilcdc.txt b/Documentation/devicetree/bindings/display/tilcdc/tilcdc.txt index aac617acb64f5ff391be254d078d1b8bbe3aa895..8b2a713956470ae9129ee8cfcfb50a0bebe1fc2a 100644 --- a/Documentation/devicetree/bindings/display/tilcdc/tilcdc.txt +++ b/Documentation/devicetree/bindings/display/tilcdc/tilcdc.txt @@ -46,7 +46,7 @@ Optional nodes: 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 0000000000000000000000000000000000000000..7b9d468c3e52cd1226fd9cc9197b314c1cc1b250 --- /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 + +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 + #include + + display@fd4a0000 { + compatible = "xlnx,zynqmp-dpsub-1.7"; + reg = <0xfd4a0000 0x1000>, + <0xfd4aa000 0x1000>, + <0xfd4ab000 0x1000>, + <0xfd4ac000 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 2c7fd1941abbbc8e9be9d65ece4f10a275b47c83..315e90122afaf1866b42af88bf69aaf41279b74e 100644 --- a/Documentation/devicetree/bindings/dma/arm-pl330.txt +++ b/Documentation/devicetree/bindings/dma/arm-pl330.txt @@ -16,6 +16,7 @@ Optional properties: - 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 03e9bb12b75f71c84389efb4ca873af2af6786ef..0000000000000000000000000000000000000000 --- 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 = , - , - , - ; - #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 0000000000000000000000000000000000000000..256d62af2c64b9eef49b724f031aa1b12d6ad21a --- /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 + +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 + dma: dma-controller@e0260000 { + compatible = "actions,s900-dma"; + reg = <0xe0260000 0x1000>; + interrupts = , + , + , + ; + #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 b842dfd96a8978da9effaf7e1f4637460e592b67..13f1a46be40dce8027016b8697e7670b8d834889 100644 --- a/Documentation/devicetree/bindings/dma/renesas,rcar-dmac.yaml +++ b/Documentation/devicetree/bindings/dma/renesas,rcar-dmac.yaml @@ -23,6 +23,7 @@ properties: - 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 9ca6d8ddf23208c84a305b66b7f8b340dffa7496..ab287c652b2cc9f02d608b367739461880530b75 100644 --- a/Documentation/devicetree/bindings/dma/renesas,usb-dmac.yaml +++ b/Documentation/devicetree/bindings/dma/renesas,usb-dmac.yaml @@ -16,6 +16,7 @@ properties: 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 @@ properties: - 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 0000000000000000000000000000000000000000..20870f5c14dd0a68c54ad3566f8fc75a47777bb0 --- /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 + - Andy Shevchenko + +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 0bedceed1963548a938db67e7a1ce66b85f63cac..0000000000000000000000000000000000000000 --- 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 0000000000000000000000000000000000000000..2a595b18ff6c72158c7c9a6804c1e897a5dc613b --- /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 + +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 + + dma: dma-controller@fd4c0000 { + compatible = "xlnx,zynqmp-dpdma"; + reg = <0xfd4c0000 0x1000>; + interrupts = ; + interrupt-parent = <&gic>; + clocks = <&dpdma_clk>; + clock-names = "axi_clk"; + #dma-cells = <1>; + }; + +... diff --git a/Documentation/devicetree/bindings/dsp/fsl,dsp.yaml b/Documentation/devicetree/bindings/dsp/fsl,dsp.yaml index 3bbe9521c0bc8d102f49729ba6d4712df1eee3f5..4cc0112301536201e48fc8b6b6f39d068997037e 100644 --- a/Documentation/devicetree/bindings/dsp/fsl,dsp.yaml +++ b/Documentation/devicetree/bindings/dsp/fsl,dsp.yaml @@ -56,8 +56,8 @@ properties: memory-region: description: - phandle to a node describing reserved memory (System RAM memory) - used by DSP (see bindings/reserved-memory/reserved-memory.txt) + phandle to a node describing reserved memory (System RAM memory) + used by DSP (see bindings/reserved-memory/reserved-memory.txt) maxItems: 1 required: diff --git a/Documentation/devicetree/bindings/example-schema.yaml b/Documentation/devicetree/bindings/example-schema.yaml index c9534d2164a22dce12fe63f76947239d051e4a63..822975dbeafad6354767178cd56662d4d8cc4666 100644 --- a/Documentation/devicetree/bindings/example-schema.yaml +++ b/Documentation/devicetree/bindings/example-schema.yaml @@ -177,10 +177,10 @@ properties: dependencies: # 'vendor,bool-property' is only allowed when 'vendor,string-array-property' # is present - vendor,bool-property: [ vendor,string-array-property ] + vendor,bool-property: [ 'vendor,string-array-property' ] # Expressing 2 properties in both orders means all of the set of properties # must be present or none of them. - vendor,string-array-property: [ vendor,bool-property ] + vendor,string-array-property: [ 'vendor,bool-property' ] required: - compatible diff --git a/Documentation/devicetree/bindings/firmware/qcom,scm.txt b/Documentation/devicetree/bindings/firmware/qcom,scm.txt index 354b448fc0c3790ef588b20a0902393eef734930..78456437df5f70a925439196561d3bb629a97170 100644 --- a/Documentation/devicetree/bindings/firmware/qcom,scm.txt +++ b/Documentation/devicetree/bindings/firmware/qcom,scm.txt @@ -11,10 +11,12 @@ Required properties: * "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 8ab19d1d3f9a8c9df78be5be02c173462f613b09..e811cf8250199b14205787cfdedf8cd6e4aa4df2 100644 --- a/Documentation/devicetree/bindings/fpga/fpga-region.txt +++ b/Documentation/devicetree/bindings/fpga/fpga-region.txt @@ -493,4 +493,4 @@ FPGA Bridges that exist on the FPGA fabric prior to the partial reconfiguration. -- [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 cfa4ed42b62f9bad7d4a5dd56f69b2eca94f4639..5ef659c1394d72f29f441bb75771e783ccae7c9b 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 @@ Required properties: - 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 @@ Example for full FPGA configuration: 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/fsi/ibm,fsi2spi.yaml b/Documentation/devicetree/bindings/fsi/ibm,fsi2spi.yaml index 893d81e54caa85db48d077ac8b4f249c1ae64886..b26d4b4be743f4fbb0e32ef92240f1cb70a838b0 100644 --- a/Documentation/devicetree/bindings/fsi/ibm,fsi2spi.yaml +++ b/Documentation/devicetree/bindings/fsi/ibm,fsi2spi.yaml @@ -7,7 +7,7 @@ $schema: http://devicetree.org/meta-schemas/core.yaml# title: IBM FSI-attached SPI controllers maintainers: - - Eddie James + - Eddie James description: | This binding describes an FSI CFAM engine called the FSI2SPI. Therefore this diff --git a/Documentation/devicetree/bindings/fuse/nvidia,tegra20-fuse.txt b/Documentation/devicetree/bindings/fuse/nvidia,tegra20-fuse.txt index 41372d441131aa66071a13357413d752d1025138..2aaf661c04eee342a056e704205e937372544f45 100644 --- a/Documentation/devicetree/bindings/fuse/nvidia,tegra20-fuse.txt +++ b/Documentation/devicetree/bindings/fuse/nvidia,tegra20-fuse.txt @@ -4,8 +4,9 @@ Required properties: - 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,-efuse", plus one of the above, where - 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/brcm,xgs-iproc-gpio.yaml b/Documentation/devicetree/bindings/gpio/brcm,xgs-iproc-gpio.yaml index 4f2cbd8307a7532499dca1afbf0aeee1351b50b9..c213cb9ddb9f0df6f73477ebddfef10753a7a8ce 100644 --- a/Documentation/devicetree/bindings/gpio/brcm,xgs-iproc-gpio.yaml +++ b/Documentation/devicetree/bindings/gpio/brcm,xgs-iproc-gpio.yaml @@ -19,10 +19,8 @@ properties: reg: items: - - description: the I/O address containing the GPIO controller - registers. - - description: the I/O address containing the Chip Common A interrupt - registers. + - description: the I/O address containing the GPIO controller registers. + - description: the I/O address containing the Chip Common A interrupt registers. gpio-controller: true diff --git a/Documentation/devicetree/bindings/gpio/gpio-mxs.yaml b/Documentation/devicetree/bindings/gpio/gpio-mxs.yaml index ccf5b50e798b936a70161208c589c62bfb866ed4..dfa1133f8c5e4eb223b3c4e68cff066a0d52d822 100644 --- a/Documentation/devicetree/bindings/gpio/gpio-mxs.yaml +++ b/Documentation/devicetree/bindings/gpio/gpio-mxs.yaml @@ -7,7 +7,7 @@ $schema: http://devicetree.org/meta-schemas/core.yaml# title: Freescale MXS GPIO controller maintainers: - - Shawn Guo + - Shawn Guo - Anson Huang description: | diff --git a/Documentation/devicetree/bindings/gpio/gpio-pca953x.txt b/Documentation/devicetree/bindings/gpio/gpio-pca953x.txt index dab537c20def4ce15dfa4c2200d34f775b257fde..3126c3817e2ab750b26e9a8ecc517da868f77ab1 100644 --- a/Documentation/devicetree/bindings/gpio/gpio-pca953x.txt +++ b/Documentation/devicetree/bindings/gpio/gpio-pca953x.txt @@ -19,6 +19,7 @@ Required properties: 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 0000000000000000000000000000000000000000..338c5312a1067db14451c2dc360e1bdb1cf1e1f0 --- /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 + +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 4fa4eb5507cdf8469f08183b8e934816e71570bb..f693e82b4c0f1b73e49206c059c690763cc1c879 100644 --- a/Documentation/devicetree/bindings/gpio/gpio-zynq.txt +++ b/Documentation/devicetree/bindings/gpio/gpio-zynq.txt @@ -6,7 +6,9 @@ Required properties: - 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/mrvl-gpio.txt b/Documentation/devicetree/bindings/gpio/mrvl-gpio.txt deleted file mode 100644 index 30fd2201b3d4cfc8fbc3fe7b1f7a39854c1d3d7e..0000000000000000000000000000000000000000 --- 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 0000000000000000000000000000000000000000..4db3b8a3332c28dd18c11dce9ba0cc7b774feb2f --- /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 + - Bartosz Golaszewski + - Rob Herring + +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 + 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 + 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/gpio/renesas,rcar-gpio.yaml b/Documentation/devicetree/bindings/gpio/renesas,rcar-gpio.yaml index 397d9383d15a9b32e0c7a9f29bd1b6c21c5d0bb4..3ad229307bd5543d0585ecc5f1ade89d9911bcd7 100644 --- a/Documentation/devicetree/bindings/gpio/renesas,rcar-gpio.yaml +++ b/Documentation/devicetree/bindings/gpio/renesas,rcar-gpio.yaml @@ -13,39 +13,39 @@ properties: compatible: oneOf: - items: - - enum: - - renesas,gpio-r8a7778 # R-Car M1 - - renesas,gpio-r8a7779 # R-Car H1 - - const: renesas,rcar-gen1-gpio # R-Car Gen1 + - enum: + - renesas,gpio-r8a7778 # R-Car M1 + - renesas,gpio-r8a7779 # R-Car H1 + - const: renesas,rcar-gen1-gpio # R-Car Gen1 - items: - - enum: - - renesas,gpio-r8a7742 # RZ/G1H - - renesas,gpio-r8a7743 # RZ/G1M - - renesas,gpio-r8a7744 # RZ/G1N - - renesas,gpio-r8a7745 # RZ/G1E - - renesas,gpio-r8a77470 # RZ/G1C - - renesas,gpio-r8a7790 # R-Car H2 - - renesas,gpio-r8a7791 # R-Car M2-W - - renesas,gpio-r8a7792 # R-Car V2H - - renesas,gpio-r8a7793 # R-Car M2-N - - renesas,gpio-r8a7794 # R-Car E2 - - const: renesas,rcar-gen2-gpio # R-Car Gen2 or RZ/G1 + - enum: + - renesas,gpio-r8a7742 # RZ/G1H + - renesas,gpio-r8a7743 # RZ/G1M + - renesas,gpio-r8a7744 # RZ/G1N + - renesas,gpio-r8a7745 # RZ/G1E + - renesas,gpio-r8a77470 # RZ/G1C + - renesas,gpio-r8a7790 # R-Car H2 + - renesas,gpio-r8a7791 # R-Car M2-W + - renesas,gpio-r8a7792 # R-Car V2H + - renesas,gpio-r8a7793 # R-Car M2-N + - renesas,gpio-r8a7794 # R-Car E2 + - const: renesas,rcar-gen2-gpio # R-Car Gen2 or RZ/G1 - items: - - enum: - - renesas,gpio-r8a774a1 # RZ/G2M - - renesas,gpio-r8a774b1 # RZ/G2N - - renesas,gpio-r8a774c0 # RZ/G2E - - renesas,gpio-r8a7795 # R-Car H3 - - renesas,gpio-r8a7796 # R-Car M3-W - - renesas,gpio-r8a77961 # R-Car M3-W+ - - renesas,gpio-r8a77965 # R-Car M3-N - - renesas,gpio-r8a77970 # R-Car V3M - - renesas,gpio-r8a77980 # R-Car V3H - - renesas,gpio-r8a77990 # R-Car E3 - - renesas,gpio-r8a77995 # R-Car D3 - - const: renesas,rcar-gen3-gpio # R-Car Gen3 or RZ/G2 + - enum: + - renesas,gpio-r8a774a1 # RZ/G2M + - renesas,gpio-r8a774b1 # RZ/G2N + - renesas,gpio-r8a774c0 # RZ/G2E + - renesas,gpio-r8a7795 # R-Car H3 + - renesas,gpio-r8a7796 # R-Car M3-W + - renesas,gpio-r8a77961 # R-Car M3-W+ + - renesas,gpio-r8a77965 # R-Car M3-N + - renesas,gpio-r8a77970 # R-Car V3M + - renesas,gpio-r8a77980 # R-Car V3H + - renesas,gpio-r8a77990 # R-Car E3 + - renesas,gpio-r8a77995 # R-Car D3 + - const: renesas,rcar-gen3-gpio # R-Car Gen3 or RZ/G2 reg: maxItems: 1 diff --git a/Documentation/devicetree/bindings/gpio/sgpio-aspeed.txt b/Documentation/devicetree/bindings/gpio/sgpio-aspeed.txt index d4d83916c09dd97a11bfa3f5afa815efade7b861..be329ea4794f88dd5f48d60c5c53c6e35e8c09af 100644 --- a/Documentation/devicetree/bindings/gpio/sgpio-aspeed.txt +++ b/Documentation/devicetree/bindings/gpio/sgpio-aspeed.txt @@ -20,8 +20,9 @@ Required properties: - gpio-controller : Marks the device node as a GPIO controller - interrupts : Interrupt specifier, see interrupt-controller/interrupts.txt - interrupt-controller : Mark the GPIO controller as an interrupt-controller -- ngpios : number of GPIO lines, see gpio.txt - (should be multiple of 8, up to 80 pins) +- ngpios : number of *hardware* GPIO lines, see gpio.txt. This will expose + 2 software GPIOs per hardware GPIO: one for hardware input, one for hardware + output. Up to 80 pins, must be a multiple of 8. - clocks : A phandle to the APB clock for SGPM clock division - bus-frequency : SGPM CLK frequency diff --git a/Documentation/devicetree/bindings/gpu/nvidia,gk20a.txt b/Documentation/devicetree/bindings/gpu/nvidia,gk20a.txt index f32bbba4d3bca902242049fabd1a2d92eca36cc5..662a3c8a7d29b9a79e6aaa9e823f9a0c98efc4f8 100644 --- a/Documentation/devicetree/bindings/gpu/nvidia,gk20a.txt +++ b/Documentation/devicetree/bindings/gpu/nvidia,gk20a.txt @@ -6,6 +6,7 @@ Required properties: - 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 @@ Required properties: 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 @@ Example for GP10B: 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 = , + ; + 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/gpu/vivante,gc.yaml b/Documentation/devicetree/bindings/gpu/vivante,gc.yaml index e1ac6ff5a230c516b03f038cf3dc4c5b001f8bc3..4843df1ddbb66a7463513e6c933fdb9f0269b92f 100644 --- a/Documentation/devicetree/bindings/gpu/vivante,gc.yaml +++ b/Documentation/devicetree/bindings/gpu/vivante,gc.yaml @@ -26,7 +26,8 @@ properties: - description: AXI/master interface clock - description: GPU core clock - description: Shader clock (only required if GPU has feature PIPE_3D) - - description: AHB/slave interface clock (only required if GPU can gate slave interface independently) + - description: AHB/slave interface clock (only required if GPU can gate + slave interface independently) minItems: 1 maxItems: 4 diff --git a/Documentation/devicetree/bindings/hwlock/qcom-hwspinlock.txt b/Documentation/devicetree/bindings/hwlock/qcom-hwspinlock.txt deleted file mode 100644 index 4563f524556b351717e05ea4c09cd3fe6e89778e..0000000000000000000000000000000000000000 --- 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: - Definition: must be one of: - "qcom,sfpb-mutex", - "qcom,tcsr-mutex" - -- syscon: - Usage: required - Value type: - 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: - 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 0000000000000000000000000000000000000000..1c7149f7d171a1e6a6a7b64d05f7e57299507065 --- /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 + +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/adi,axi-fan-control.yaml b/Documentation/devicetree/bindings/hwmon/adi,axi-fan-control.yaml index af35b77053dfdd1a251ab28dc40b2eb4c5922d99..7898b9dba5a5898ced66a36fbd03c240d801fb5d 100644 --- a/Documentation/devicetree/bindings/hwmon/adi,axi-fan-control.yaml +++ b/Documentation/devicetree/bindings/hwmon/adi,axi-fan-control.yaml @@ -19,7 +19,7 @@ description: |+ properties: compatible: enum: - - adi,axi-fan-control-1.00.a + - adi,axi-fan-control-1.00.a reg: maxItems: 1 diff --git a/Documentation/devicetree/bindings/hwmon/gpio-fan.txt b/Documentation/devicetree/bindings/hwmon/gpio-fan.txt index 2becdcfdc840c60e6d02ffe0f3893c00eb80321d..f4cfa350f6a1448f88805158b0e03512cf45a95e 100644 --- a/Documentation/devicetree/bindings/hwmon/gpio-fan.txt +++ b/Documentation/devicetree/bindings/hwmon/gpio-fan.txt @@ -12,7 +12,8 @@ Optional properties: - 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 c76a7ac47c3426361d02ced15f3458c709bc4a3e..398dcb9657514e5729006e6bed45656ac7daaeac 100644 --- a/Documentation/devicetree/bindings/hwmon/lm90.txt +++ b/Documentation/devicetree/bindings/hwmon/lm90.txt @@ -34,8 +34,8 @@ Optional properties: 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 for the +- #thermal-sensor-cells: should be set to 1. See thermal/thermal-sensor.yaml + for details. See 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 0000000000000000000000000000000000000000..76be625d56460d8150f84cd3091a84e500c9afc1 --- /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 + +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 90b2fa3f7752c448d4aec8bd4b4bb368de639a21..c17e5d3ee3f1455ed9e8f139393043941a1e5db8 100644 --- a/Documentation/devicetree/bindings/hwmon/ti,tmp513.yaml +++ b/Documentation/devicetree/bindings/hwmon/ti,tmp513.yaml @@ -18,8 +18,8 @@ description: | 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 da6129090a8eb65ca244647a5783952484cf2bce..78ffcab2428cfc5304593b2360715c41116d5a8c 100644 --- a/Documentation/devicetree/bindings/i2c/i2c-gpio.yaml +++ b/Documentation/devicetree/bindings/i2c/i2c-gpio.yaml @@ -52,15 +52,15 @@ properties: 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 f0c072ff9eca33f622aaa9e36fb7ea93bfd9b3ad..0000000000000000000000000000000000000000 --- 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 = ; - 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 0000000000000000000000000000000000000000..ac0bc5dd64d67a438c8f3a262dae26f73512ad1a --- /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 + +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 + #include + + lpi2c7@40a50000 { + compatible = "fsl,imx7ulp-lpi2c"; + reg = <0x40A50000 0x10000>; + interrupt-parent = <&intc>; + interrupts = ; + 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 b967544590e804c413063cfbd4c1d56bee6f486b..0000000000000000000000000000000000000000 --- 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 0000000000000000000000000000000000000000..810536953177fb344824ff35f7d501930dff5bb0 --- /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 + +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 + #include + #include + #include + + 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 88b71c1b32c92c7239ae425a6e93fbaf7d1bb4fd..7f0194fdd0cc022b6abc096f54f5810c65942367 100644 --- a/Documentation/devicetree/bindings/i2c/i2c-mt65xx.txt +++ b/Documentation/devicetree/bindings/i2c/i2c-mt65xx.txt @@ -14,6 +14,7 @@ Required properties: "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 4e1c8ac01eba54da7685cbbaf69109e1ff69634a..0000000000000000000000000000000000000000 --- 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,-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 0000000000000000000000000000000000000000..21ae7bce038ec2b212de6de5c0445aa0edb0120e --- /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 + +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 c30783c0eca03a42c61b93e0d106a20de0ed92fd..0000000000000000000000000000000000000000 --- 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 0000000000000000000000000000000000000000..015885dd02d32e8493419fa436380b41729695b7 --- /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 + +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 + 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 438ae123107e7752a5fa5c58affc7b35fab1b423..a21c359b9f0266f808972dc68680beb229b9353b 100644 --- a/Documentation/devicetree/bindings/i2c/i2c.txt +++ b/Documentation/devicetree/bindings/i2c/i2c.txt @@ -72,6 +72,16 @@ wants to support one of the below features, it should adapt these bindings. 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 2ceb05ba2df5eac4aef00ed8d9921cc4e02c7dfe..5b5ae402f97abf3a72f94621c70308eb6e275683 100644 --- a/Documentation/devicetree/bindings/i2c/marvell,mv64xxx-i2c.yaml +++ b/Documentation/devicetree/bindings/i2c/marvell,mv64xxx-i2c.yaml @@ -26,6 +26,9 @@ properties: - items: - 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 18c0de362451c8db9f2021edcb9dc7f35d7fb82b..3f2f990c2e62ed503eef50a3552ac8e3d431db1d 100644 --- a/Documentation/devicetree/bindings/i2c/nvidia,tegra20-i2c.txt +++ b/Documentation/devicetree/bindings/i2c/nvidia,tegra20-i2c.txt @@ -35,12 +35,12 @@ Required properties: 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 @@ Required properties: - 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 a03f9f5cb378e000167470dae536b58104028ff6..96d869ac38390f0319d1659103926c9f489d616d 100644 --- a/Documentation/devicetree/bindings/i2c/renesas,i2c.txt +++ b/Documentation/devicetree/bindings/i2c/renesas,i2c.txt @@ -10,6 +10,7 @@ Required properties: "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 89facb09337a12fb5c7f2da7e9f28dc24354a356..93d412832e66b68286b3dd422338fab9f21ad7fe 100644 --- a/Documentation/devicetree/bindings/i2c/renesas,iic.txt +++ b/Documentation/devicetree/bindings/i2c/renesas,iic.txt @@ -11,6 +11,7 @@ Required properties: - "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 d124eba1ce54fb3025547024c8266637d5ed035c..fd4eaa3d0ab4127a7396e6f955a287d3b9ab6ae1 100644 --- a/Documentation/devicetree/bindings/iio/accel/adi,adxl345.yaml +++ b/Documentation/devicetree/bindings/iio/accel/adi,adxl345.yaml @@ -12,8 +12,8 @@ maintainers: 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 b25bf3a77e0fd3b08b5a810d504d2fe762df0b8c..0000000000000000000000000000000000000000 --- 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 0000000000000000000000000000000000000000..d61ab4fa3d71e5a9af5744ac70379175ae367358 --- /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 + +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 + 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 + 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/adi,ad7606.yaml b/Documentation/devicetree/bindings/iio/adc/adi,ad7606.yaml index 5117ad68a58405e0c0290827c5dd1306b8e8423b..cbb8819d706930ed0f9dbd3a0f5011f0ef80feea 100644 --- a/Documentation/devicetree/bindings/iio/adc/adi,ad7606.yaml +++ b/Documentation/devicetree/bindings/iio/adc/adi,ad7606.yaml @@ -53,10 +53,10 @@ properties: standby-gpios: description: - Must be the device tree identifier of the STBY pin. This pin is used - to place the AD7606 into one of two power-down modes, Standby mode or - Shutdown mode. As the line is active low, it should be marked - GPIO_ACTIVE_LOW. + Must be the device tree identifier of the STBY pin. This pin is used + to place the AD7606 into one of two power-down modes, Standby mode or + Shutdown mode. As the line is active low, it should be marked + GPIO_ACTIVE_LOW. maxItems: 1 adi,first-data-gpios: 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 cd9048cf9dcf9276d0f0d756a10467e27e16cdca..0000000000000000000000000000000000000000 --- 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 - -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 0000000000000000000000000000000000000000..9f414dbdae863454d02361fb642ab8d70b141618 --- /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 + +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 + #include + + 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/maxim,max1238.yaml b/Documentation/devicetree/bindings/iio/adc/maxim,max1238.yaml index a0ebb46801406f1e277d1ac23672d2bac48f7d01..cccd3033a55ba7300da00987bbd93945a5d2886d 100644 --- a/Documentation/devicetree/bindings/iio/adc/maxim,max1238.yaml +++ b/Documentation/devicetree/bindings/iio/adc/maxim,max1238.yaml @@ -10,7 +10,7 @@ maintainers: - Jonathan Cameron description: | - Family of simple ADCs with i2c inteface and internal references. + Family of simple ADCs with i2c inteface and internal references. properties: compatible: 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 c8787688122af921211a48d997c4935c2faabe5d..0000000000000000000000000000000000000000 --- 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: - 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: - Definition: VADC base address in the SPMI PMIC register map. - -- #address-cells: - Usage: required - Value type: - Definition: Must be one. Child node 'reg' property should define ADC - channel number. - -- #size-cells: - Usage: required - Value type: - Definition: Must be zero. - -- #io-channel-cells: - Usage: required - Value type: - Definition: Must be one. For details about IIO bindings see: - Documentation/devicetree/bindings/iio/iio-bindings.txt - -- interrupts: - Usage: optional - Value type: - Definition: End of conversion interrupt. - -Channel node properties: - -- reg: - Usage: required - Value type: - 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: - 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: - 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: - 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: - 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: - 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: - 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 -#include -/* ... */ - - /* 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 = ; - 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 0000000000000000000000000000000000000000..0ca992465a218f8bf2dc0803f08dca562eac2771 --- /dev/null +++ b/Documentation/devicetree/bindings/iio/adc/qcom,spmi-vadc.yaml @@ -0,0 +1,276 @@ +# 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 + - Bjorn Andersson + +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. + $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/rockchip-saradc.yaml b/Documentation/devicetree/bindings/iio/adc/rockchip-saradc.yaml index bcff82a423bcdcaf4c694e0d108c02e967ddb570..1bb76197787b6bfd97c748fdf1068e3ef184828e 100644 --- a/Documentation/devicetree/bindings/iio/adc/rockchip-saradc.yaml +++ b/Documentation/devicetree/bindings/iio/adc/rockchip-saradc.yaml @@ -17,10 +17,10 @@ properties: - const: rockchip,rk3399-saradc - items: - enum: - - rockchip,px30-saradc - - rockchip,rk3308-saradc - - rockchip,rk3328-saradc - - rockchip,rv1108-saradc + - rockchip,px30-saradc + - rockchip,rk3308-saradc + - rockchip,rk3328-saradc + - rockchip,rv1108-saradc - const: rockchip,rk3399-saradc reg: 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 0000000000000000000000000000000000000000..97fe6cbb2efab66b5b0180820207ca8624774a4e --- /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 + +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 a02337d7efa447f46265dbd4a460e8c760ea45f5..0000000000000000000000000000000000000000 --- 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/amplifiers/adi,hmc425a.yaml b/Documentation/devicetree/bindings/iio/amplifiers/adi,hmc425a.yaml index 1c6d49685e9f833ba74a7ed0d0d9da48360dbcfb..5342360e96b12ff02d248c637ef67f138e8bb44e 100644 --- a/Documentation/devicetree/bindings/iio/amplifiers/adi,hmc425a.yaml +++ b/Documentation/devicetree/bindings/iio/amplifiers/adi,hmc425a.yaml @@ -7,8 +7,8 @@ $schema: http://devicetree.org/meta-schemas/core.yaml# title: HMC425A 6-bit Digital Step Attenuator maintainers: -- Michael Hennerich -- Beniamin Bia + - Michael Hennerich + - Beniamin Bia description: | Digital Step Attenuator IIO device with gpio interface. diff --git a/Documentation/devicetree/bindings/iio/chemical/atlas,sensor.yaml b/Documentation/devicetree/bindings/iio/chemical/atlas,sensor.yaml index 69e8931e0ae8cb23e1b3663337333a6f1698c978..9a89b34bdd8ff9413198d5eab18112b6ba4f0b13 100644 --- a/Documentation/devicetree/bindings/iio/chemical/atlas,sensor.yaml +++ b/Documentation/devicetree/bindings/iio/chemical/atlas,sensor.yaml @@ -31,10 +31,10 @@ properties: - atlas,co2-ezo reg: - maxItems: 1 + maxItems: 1 interrupts: - maxItems: 1 + maxItems: 1 required: - compatible 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 0000000000000000000000000000000000000000..40d87346ff4cffab5b51b24b4d2d4c8e344acafa --- /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 + +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 + 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 + 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/adi,ad5770r.yaml b/Documentation/devicetree/bindings/iio/dac/adi,ad5770r.yaml index 58d81ca434605be574fecf06d75324c0e0bddb7c..82424e06be27d6755fb2bfac88019dedb3ef7f38 100644 --- a/Documentation/devicetree/bindings/iio/dac/adi,ad5770r.yaml +++ b/Documentation/devicetree/bindings/iio/dac/adi,ad5770r.yaml @@ -61,17 +61,17 @@ properties: const: 0 adi,range-microamp: - description: Output range of the channel. - oneOf: - - items: - - const: 0 - - const: 300000 - - items: - - const: -60000 - - const: 0 - - items: - - const: -60000 - - const: 300000 + description: Output range of the channel. + oneOf: + - items: + - const: 0 + - const: 300000 + - items: + - const: -60000 + - const: 0 + - items: + - const: -60000 + - const: 300000 channel@1: description: Represents an external channel which are @@ -84,10 +84,10 @@ properties: const: 1 adi,range-microamp: - description: Output range of the channel. - items: - - const: 0 - - enum: [ 140000, 250000 ] + description: Output range of the channel. + items: + - const: 0 + - enum: [140000, 250000] channel@2: description: Represents an external channel which are @@ -100,10 +100,10 @@ properties: const: 2 adi,range-microamp: - description: Output range of the channel. - items: - - const: 0 - - enum: [ 55000, 150000 ] + description: Output range of the channel. + items: + - const: 0 + - enum: [55000, 150000] patternProperties: "^channel@([3-5])$": @@ -116,19 +116,19 @@ patternProperties: maximum: 5 adi,range-microamp: - description: Output range of the channel. - items: - - const: 0 - - enum: [ 45000, 100000 ] + description: Output range of the channel. + items: + - const: 0 + - enum: [45000, 100000] required: -- reg -- channel@0 -- channel@1 -- channel@2 -- channel@3 -- channel@4 -- channel@5 + - reg + - channel@0 + - channel@1 + - channel@2 + - channel@3 + - channel@4 + - channel@5 examples: - | diff --git a/Documentation/devicetree/bindings/iio/dac/ti,dac7612.txt b/Documentation/devicetree/bindings/iio/dac/ti,dac7612.txt index 639c94ed83e994460935b533057cedd13a810b65..17af395b99d9fef436c793690fca382c48febce5 100644 --- a/Documentation/devicetree/bindings/iio/dac/ti,dac7612.txt +++ b/Documentation/devicetree/bindings/iio/dac/ti,dac7612.txt @@ -6,7 +6,7 @@ Is is programmable through an SPI interface. 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 af33267727f4e121839c94e244b9ef26f19310a2..aa63cac7323ecca359bc3b5e5dafa5f15fc79334 100644 --- a/Documentation/devicetree/bindings/iio/iio-bindings.txt +++ b/Documentation/devicetree/bindings/iio/iio-bindings.txt @@ -9,7 +9,7 @@ specifier is an array of one or more cells identifying the IIO 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 0d0ef84e22b997ba46f2bfb450919088c4389bb1..33d8e9fd14b7553c30a53cd853978125638fd985 100644 --- a/Documentation/devicetree/bindings/iio/imu/bosch,bmi160.yaml +++ b/Documentation/devicetree/bindings/iio/imu/bosch,bmi160.yaml @@ -37,6 +37,15 @@ properties: 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 @@ examples: 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 0000000000000000000000000000000000000000..abd8d25e1136a44d35beefbadeca29b823651062 --- /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 + +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 + #include + 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 + #include + 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 aa199e09a493f179ecee2cf55a45054203c5a9a7..3aa6db3ee99d272d536a73d5279bbbd5ef3468e2 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 3af325ad194b9137da740ace14d9fc9188ddc4fa..c53ddb81c4aa64b9eb392ae819ac341fb6f34bea 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 47b13eb8f4ecb02835295522860ed0643f707a51..9e6f2998e75154a58020840a4ae34a56e660f99a 100644 --- a/Documentation/devicetree/bindings/iio/light/opt3001.txt +++ b/Documentation/devicetree/bindings/iio/light/opt3001.txt @@ -6,7 +6,7 @@ the optional generation of IIO events on rising/falling light threshold changes 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/vishay,vcnl4000.yaml b/Documentation/devicetree/bindings/iio/light/vishay,vcnl4000.yaml index da8f2e872535b263dd5af2b7d340ff06de37640c..58887a4f9c15272ed9b0509c314fd7cc630399b6 100644 --- a/Documentation/devicetree/bindings/iio/light/vishay,vcnl4000.yaml +++ b/Documentation/devicetree/bindings/iio/light/vishay,vcnl4000.yaml @@ -36,15 +36,15 @@ required: additionalProperties: false examples: -- | - i2c { - #address-cells = <1>; - #size-cells = <0>; - - light-sensor@51 { - compatible = "vishay,vcnl4200"; - reg = <0x51>; - proximity-near-level = <220>; - }; - }; + - | + i2c { + #address-cells = <1>; + #size-cells = <0>; + + light-sensor@51 { + compatible = "vishay,vcnl4200"; + reg = <0x51>; + proximity-near-level = <220>; + }; + }; ... diff --git a/Documentation/devicetree/bindings/iio/light/vl6180.txt b/Documentation/devicetree/bindings/iio/light/vl6180.txt index 2c52952715a0e279596067b14554c0462e3a2e9b..fb9137d85df972a67eecf1ac98fbe867b924a74b 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 aa67ceb0d4e046cc0f228baa10f12de33f2f6484..0000000000000000000000000000000000000000 --- 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 0000000000000000000000000000000000000000..f0b336ac39c9ac6655a1352777cc37a48bb39cde --- /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 + +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 + #include + 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 fd5fca90fb39614c97861e61f99429b8935cda31..22912e43b60c0f6a26b88a00c7eca37a9d8993a8 100644 --- a/Documentation/devicetree/bindings/iio/magnetometer/bmc150_magn.txt +++ b/Documentation/devicetree/bindings/iio/magnetometer/bmc150_magn.txt @@ -4,7 +4,11 @@ http://ae-bst.resource.bosch.com/media/products/dokumente/bmc150/BST-BMC150-DS00 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/potentiometer/mcp41010.txt b/Documentation/devicetree/bindings/iio/potentiometer/mcp41010.txt index 566711b9950cf8c0d55d74569ed719c8a673e0f4..4f245e8469fdb00f21accbde3ea7142c76b9354e 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 e6d0c2eb345c4cbf4fca7022549325ffa0a727d5..f3ab02b0dd415f1ec8e472bfdca6eb1770e1717a 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 64c18f1693f008ce21e374501e431efc5846c358..be2be4b556dbbd3b520d95374b0875edc57160e7 100644 --- a/Documentation/devicetree/bindings/iio/pressure/asc,dlhl60d.yaml +++ b/Documentation/devicetree/bindings/iio/pressure/asc,dlhl60d.yaml @@ -13,7 +13,7 @@ description: | 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 f86f8b23ef18fd3d9daaeef35096f2c09074cfe0..ce795279839ef951ae70dc69a3ae7a5ef3f6031e 100644 --- a/Documentation/devicetree/bindings/iio/proximity/devantech-srf04.yaml +++ b/Documentation/devicetree/bindings/iio/proximity/devantech-srf04.yaml @@ -17,9 +17,9 @@ description: | 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/iio/proximity/vishay,vcnl3020.yaml b/Documentation/devicetree/bindings/iio/proximity/vishay,vcnl3020.yaml index 4190253336ec1910c53f6e2b7c31de52059ddaea..51dba64037f695fcf81711e84f06961c8de532d4 100644 --- a/Documentation/devicetree/bindings/iio/proximity/vishay,vcnl3020.yaml +++ b/Documentation/devicetree/bindings/iio/proximity/vishay,vcnl3020.yaml @@ -39,8 +39,8 @@ properties: description: The driver current for the LED used in proximity sensing. enum: [0, 10000, 20000, 30000, 40000, 50000, 60000, 70000, 80000, 90000, - 100000, 110000, 120000, 130000, 140000, 150000, 160000, 170000, - 180000, 190000, 200000] + 100000, 110000, 120000, 130000, 140000, 150000, 160000, 170000, + 180000, 190000, 200000] default: 20000 required: diff --git a/Documentation/devicetree/bindings/iio/temperature/adi,ltc2983.yaml b/Documentation/devicetree/bindings/iio/temperature/adi,ltc2983.yaml index 40ccbe7b5c1365281dd88bf183f0533e18cd129a..0f79d9a01c490549ebd1a08e4e3e0aaa306070bc 100644 --- a/Documentation/devicetree/bindings/iio/temperature/adi,ltc2983.yaml +++ b/Documentation/devicetree/bindings/iio/temperature/adi,ltc2983.yaml @@ -307,7 +307,7 @@ patternProperties: mode. $ref: /schemas/types.yaml#/definitions/uint32 enum: [0, 250, 500, 1000, 5000, 10000, 25000, 50000, 100000, 250000, - 500000, 1000000] + 500000, 1000000] adi,custom-thermistor: description: diff --git a/Documentation/devicetree/bindings/input/imx-keypad.txt b/Documentation/devicetree/bindings/input/imx-keypad.txt deleted file mode 100644 index 2ebaf7d26843c7038421d650b321eeb14b0a7d23..0000000000000000000000000000000000000000 --- 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,-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 0000000000000000000000000000000000000000..f21db81206b4632345f9e23027e773cfd7d08b1b --- /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 + +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 c54919fad17e6fc6f8ef771f7132b6de175bd9a7..79f6d01aecaac11a523cc35255bafdc594d70be7 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 0000000000000000000000000000000000000000..c3bf09156783a29db6eb796c9020bda091215f72 --- /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 + +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/cypress,cy8ctma140.yaml b/Documentation/devicetree/bindings/input/touchscreen/cypress,cy8ctma140.yaml index 8c73e52643124df645da10bc6a1cd65fbef3b430..3225c8d1fdaf002c35ea43bd3b6a0d68967672bc 100644 --- a/Documentation/devicetree/bindings/input/touchscreen/cypress,cy8ctma140.yaml +++ b/Documentation/devicetree/bindings/input/touchscreen/cypress,cy8ctma140.yaml @@ -51,7 +51,7 @@ required: - touchscreen-max-pressure examples: -- | + - | #include i2c { #address-cells = <1>; diff --git a/Documentation/devicetree/bindings/input/touchscreen/edt-ft5x06.yaml b/Documentation/devicetree/bindings/input/touchscreen/edt-ft5x06.yaml index 024b262a2ef795ae425fd868fbcba9cacc1dcd5f..4ce109476a0eee0feb2a0941e9971cff9d24ba35 100644 --- a/Documentation/devicetree/bindings/input/touchscreen/edt-ft5x06.yaml +++ b/Documentation/devicetree/bindings/input/touchscreen/edt-ft5x06.yaml @@ -20,11 +20,11 @@ maintainers: allOf: - $ref: touchscreen.yaml# - if: - properties: - compatible: - contains: - enum: - - evervision,ev-ft5726 + properties: + compatible: + contains: + enum: + - evervision,ev-ft5726 then: properties: 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 0000000000000000000000000000000000000000..007adbc89c143c6fb124fb04c934383b9a1a475a --- /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 + +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 68291b94fec2d69393c121236bc45137e74c4449..0000000000000000000000000000000000000000 --- 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/input/touchscreen/goodix.yaml b/Documentation/devicetree/bindings/input/touchscreen/goodix.yaml index e81cfa56f25ac306110475089b1f7e523f462484..da5b0d87e16d08aefec0c59826ff2253b6852c2e 100644 --- a/Documentation/devicetree/bindings/input/touchscreen/goodix.yaml +++ b/Documentation/devicetree/bindings/input/touchscreen/goodix.yaml @@ -35,9 +35,8 @@ properties: maxItems: 1 irq-gpios: - description: GPIO pin used for IRQ. - The driver uses the interrupt gpio pin as - output to reset the device. + description: GPIO pin used for IRQ. The driver uses the interrupt gpio pin + as output to reset the device. maxItems: 1 reset-gpios: diff --git a/Documentation/devicetree/bindings/input/touchscreen/touchscreen.yaml b/Documentation/devicetree/bindings/input/touchscreen/touchscreen.yaml index d7dac16a39606efe52683b67e8e6a2ecef106d5a..36dc7b56a453b032a649c932ba4a03fb7cbb6094 100644 --- a/Documentation/devicetree/bindings/input/touchscreen/touchscreen.yaml +++ b/Documentation/devicetree/bindings/input/touchscreen/touchscreen.yaml @@ -33,8 +33,8 @@ properties: $ref: /schemas/types.yaml#/definitions/uint32 touchscreen-min-pressure: - description: minimum pressure on the touchscreen to be achieved in order for the - touchscreen driver to report a touch event. + description: minimum pressure on the touchscreen to be achieved in order + for the touchscreen driver to report a touch event. $ref: /schemas/types.yaml#/definitions/uint32 touchscreen-fuzz-x: @@ -46,13 +46,13 @@ properties: $ref: /schemas/types.yaml#/definitions/uint32 touchscreen-fuzz-pressure: - description: pressure noise value of the absolute input device (arbitrary range - dependent on the controller) + description: pressure noise value of the absolute input device (arbitrary + range dependent on the controller) $ref: /schemas/types.yaml#/definitions/uint32 touchscreen-average-samples: - description: Number of data samples which are averaged for each read (valid values - dependent on the controller) + description: Number of data samples which are averaged for each read (valid + values dependent on the controller) $ref: /schemas/types.yaml#/definitions/uint32 touchscreen-inverted-x: diff --git a/Documentation/devicetree/bindings/interconnect/fsl,imx8m-noc.yaml b/Documentation/devicetree/bindings/interconnect/fsl,imx8m-noc.yaml index ff09550ad959e60c7189fcc184b4cc791fd8cd88..a8873739d61a143ec276373af36f9963244c05e5 100644 --- a/Documentation/devicetree/bindings/interconnect/fsl,imx8m-noc.yaml +++ b/Documentation/devicetree/bindings/interconnect/fsl,imx8m-noc.yaml @@ -25,17 +25,17 @@ properties: compatible: oneOf: - items: - - enum: - - fsl,imx8mn-nic - - fsl,imx8mm-nic - - fsl,imx8mq-nic - - const: fsl,imx8m-nic + - enum: + - fsl,imx8mn-nic + - fsl,imx8mm-nic + - fsl,imx8mq-nic + - const: fsl,imx8m-nic - items: - - enum: - - fsl,imx8mn-noc - - fsl,imx8mm-noc - - fsl,imx8mq-noc - - const: fsl,imx8m-noc + - enum: + - fsl,imx8mn-noc + - fsl,imx8mm-noc + - fsl,imx8mq-noc + - const: fsl,imx8m-noc - const: fsl,imx8m-nic reg: diff --git a/Documentation/devicetree/bindings/interconnect/qcom,sc7180.yaml b/Documentation/devicetree/bindings/interconnect/qcom,sc7180.yaml index d01bac80d4167f56f2b266d3f86e5bd7b0877554..8659048f92a7c64cbb30c7c9c72045894a7d5c89 100644 --- a/Documentation/devicetree/bindings/interconnect/qcom,sc7180.yaml +++ b/Documentation/devicetree/bindings/interconnect/qcom,sc7180.yaml @@ -4,7 +4,7 @@ $id: http://devicetree.org/schemas/interconnect/qcom,sc7180.yaml# $schema: http://devicetree.org/meta-schemas/core.yaml# -title: Qualcomm SC7180 Network-On-Chip Interconnect +title: Qualcomm SC7180 Network-On-Chip Interconnect maintainers: - Odelu Kukatla diff --git a/Documentation/devicetree/bindings/interconnect/qcom,sdm845.yaml b/Documentation/devicetree/bindings/interconnect/qcom,sdm845.yaml index 74536747b51d833956b5adb10f2902401c1d6708..dab17c0716ced8cc414094577eecc67ece6d3f6a 100644 --- a/Documentation/devicetree/bindings/interconnect/qcom,sdm845.yaml +++ b/Documentation/devicetree/bindings/interconnect/qcom,sdm845.yaml @@ -4,7 +4,7 @@ $id: http://devicetree.org/schemas/interconnect/qcom,sdm845.yaml# $schema: http://devicetree.org/meta-schemas/core.yaml# -title: Qualcomm SDM845 Network-On-Chip Interconnect +title: Qualcomm SDM845 Network-On-Chip Interconnect maintainers: - Georgi Djakov diff --git a/Documentation/devicetree/bindings/interrupt-controller/arm,gic.yaml b/Documentation/devicetree/bindings/interrupt-controller/arm,gic.yaml index 96f8803ff4e6a288a52a9a314ca543df00912836..06889963dfb776d5132029a31a393715a8e77976 100644 --- a/Documentation/devicetree/bindings/interrupt-controller/arm,gic.yaml +++ b/Documentation/devicetree/bindings/interrupt-controller/arm,gic.yaml @@ -42,8 +42,8 @@ properties: - items: - const: arm,gic-400 - enum: - - arm,cortex-a15-gic - - arm,cortex-a7-gic + - arm,cortex-a15-gic + - arm,cortex-a7-gic - items: - const: arm,arm1176jzf-devchip-gic diff --git a/Documentation/devicetree/bindings/interrupt-controller/brcm,l2-intc.txt b/Documentation/devicetree/bindings/interrupt-controller/brcm,l2-intc.txt index d514ec060a4a7199569d5b9141bd5324aab2e2f5..021cf822395cc5c9960f273d79ae17ca66e1dd5e 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 @@ Broadcom Generic Level 2 Interrupt Controller 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/ingenic,intc.yaml b/Documentation/devicetree/bindings/interrupt-controller/ingenic,intc.yaml index 28b27e1a6e9d1cc045426a10c0d63e79fe6cf194..02a3cf470518aef6ee5ffdfc5f6ed67603b5508b 100644 --- a/Documentation/devicetree/bindings/interrupt-controller/ingenic,intc.yaml +++ b/Documentation/devicetree/bindings/interrupt-controller/ingenic,intc.yaml @@ -16,20 +16,20 @@ properties: compatible: oneOf: - enum: - - ingenic,jz4740-intc - - ingenic,jz4760-intc - - ingenic,jz4780-intc + - ingenic,jz4740-intc + - ingenic,jz4760-intc + - ingenic,jz4780-intc - items: - - enum: - - ingenic,jz4775-intc - - ingenic,jz4770-intc - - const: ingenic,jz4760-intc + - enum: + - ingenic,jz4775-intc + - ingenic,jz4770-intc + - const: ingenic,jz4760-intc - items: - - const: ingenic,x1000-intc - - const: ingenic,jz4780-intc + - const: ingenic,x1000-intc + - const: ingenic,jz4780-intc - items: - - const: ingenic,jz4725b-intc - - const: ingenic,jz4740-intc + - const: ingenic,jz4725b-intc + - const: ingenic,jz4740-intc "#interrupt-cells": const: 1 diff --git a/Documentation/devicetree/bindings/interrupt-controller/loongson,htvec.yaml b/Documentation/devicetree/bindings/interrupt-controller/loongson,htvec.yaml index e865cd8f96a9de7ad7cd67c06bcb42997947d815..87a74558204f99170984dc92f2dc278205b72834 100644 --- a/Documentation/devicetree/bindings/interrupt-controller/loongson,htvec.yaml +++ b/Documentation/devicetree/bindings/interrupt-controller/loongson,htvec.yaml @@ -22,8 +22,8 @@ properties: 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 b1db21ed44e9a6b9ea52e600d063ef7a17a8f5ee..03fc4f5b4b395aa17b5fb9bd9927ca5f38bfbd78 100644 --- a/Documentation/devicetree/bindings/interrupt-controller/loongson,liointc.yaml +++ b/Documentation/devicetree/bindings/interrupt-controller/loongson,liointc.yaml @@ -51,8 +51,8 @@ properties: 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 173595305e2667e4098b8e977b2a603782f406a8..0000000000000000000000000000000000000000 --- 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 . - - The second cell is the GIC interrupt number. - - The third cell encodes the interrupt flags. - See 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 = ; - clock-frequency = <50000000>; - }; - }; - - uart@18101400 { - ... - interrupt-parent = <&gic>; - interrupts = ; - ... - }; 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 a0ed02725a9d7778852380fae7c67579f86d5196..0000000000000000000000000000000000000000 --- 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 0000000000000000000000000000000000000000..372ccbfae7716f590d9a2b57ecbeeec445611a9f --- /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 + - Jason Cooper + - Marc Zyngier + - Rob Herring + +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 0000000000000000000000000000000000000000..ce6aaff152149d6828bef4b20f0854a4ad35ca11 --- /dev/null +++ b/Documentation/devicetree/bindings/interrupt-controller/mti,gic.yaml @@ -0,0 +1,146 @@ +# 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 + - Thomas Bogendoerfer + +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. + $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). + $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 + 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 + #include + + 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 = ; + clock-frequency = <50000000>; + }; + }; + - | + #include + #include + + interrupt-controller@1bdc0000 { + compatible = "mti,gic"; + reg = <0x1bdc0000 0x20000>; + interrupt-controller; + #interrupt-cells = <3>; + + timer { + compatible = "mti,gic-timer"; + interrupts = ; + 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 727b7e4cd6e01110f46a34eaca05b1c7fa33d6e0..0000000000000000000000000000000000000000 --- 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,-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 0000000000000000000000000000000000000000..755cdfabfcd06c859bbee44d26e0fb3f67256d59 --- /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 + - Geert Uytterhoeven + +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 + 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-inta.txt b/Documentation/devicetree/bindings/interrupt-controller/ti,sci-inta.txt deleted file mode 100644 index 7841cb099e139446042d440e995019be75d1a7ef..0000000000000000000000000000000000000000 --- a/Documentation/devicetree/bindings/interrupt-controller/ti,sci-inta.txt +++ /dev/null @@ -1,66 +0,0 @@ -Texas Instruments K3 Interrupt Aggregator -========================================= - -The Interrupt Aggregator (INTA) provides a centralized machine -which handles the termination of system events to that they can -be coherently processed by the host(s) in the system. A maximum -of 64 events can be mapped to a single interrupt. - - - Interrupt Aggregator - +-----------------------------------------+ - | Intmap VINT | - | +--------------+ +------------+ | - m ------>| | vint | bit | | 0 |.....|63| vint0 | - . | +--------------+ +------------+ | +------+ - . | . . | | HOST | -Globalevents ------>| . . |------>| IRQ | - . | . . | | CTRL | - . | . . | +------+ - n ------>| +--------------+ +------------+ | - | | vint | bit | | 0 |.....|63| vintx | - | +--------------+ +------------+ | - | | - +-----------------------------------------+ - -Configuration of these Intmap registers that maps global events to vint is done -by a system controller (like the Device Memory and Security Controller on K3 -AM654 SoC). Driver should request the system controller to get the range -of global events and vints assigned to the requesting host. Management -of these requested resources should be handled by driver and requests -system controller to map specific global event to vint, bit pair. - -Communication between the host processor running an OS and the system -controller happens through a protocol called TI System Control Interface -(TISCI protocol). For more details refer: -Documentation/devicetree/bindings/arm/keystone/ti,sci.txt - -TISCI Interrupt Aggregator Node: -------------------------------- -- compatible: Must be "ti,sci-inta". -- reg: Should contain registers location and length. -- interrupt-controller: Identifies the node as an interrupt controller -- msi-controller: Identifies the node as an MSI controller. -- interrupt-parent: phandle of irq parent. -- ti,sci: Phandle to TI-SCI compatible System controller node. -- ti,sci-dev-id: TISCI device ID of the Interrupt Aggregator. -- ti,sci-rm-range-vint: Array of TISCI subtype ids representing vints(inta - outputs) range within this INTA, assigned to the - requesting host context. -- ti,sci-rm-range-global-event: Array of TISCI subtype ids representing the - global events range reaching this IA and are assigned - to the requesting host context. - -Example: --------- -main_udmass_inta: interrupt-controller@33d00000 { - compatible = "ti,sci-inta"; - reg = <0x0 0x33d00000 0x0 0x100000>; - interrupt-controller; - msi-controller; - interrupt-parent = <&main_navss_intr>; - ti,sci = <&dmsc>; - ti,sci-dev-id = <179>; - ti,sci-rm-range-vint = <0x0>; - ti,sci-rm-range-global-event = <0x1>; -}; diff --git a/Documentation/devicetree/bindings/interrupt-controller/ti,sci-inta.yaml b/Documentation/devicetree/bindings/interrupt-controller/ti,sci-inta.yaml new file mode 100644 index 0000000000000000000000000000000000000000..c7cd05656a3e9cf38ac5b66f833ce42d74561502 --- /dev/null +++ b/Documentation/devicetree/bindings/interrupt-controller/ti,sci-inta.yaml @@ -0,0 +1,98 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/interrupt-controller/ti,sci-inta.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Texas Instruments K3 Interrupt Aggregator + +maintainers: + - Lokesh Vutla + +allOf: + - $ref: /schemas/arm/keystone/ti,k3-sci-common.yaml# + +description: | + The Interrupt Aggregator (INTA) provides a centralized machine + which handles the termination of system events to that they can + be coherently processed by the host(s) in the system. A maximum + of 64 events can be mapped to a single interrupt. + + Interrupt Aggregator + +-----------------------------------------+ + | Intmap VINT | + | +--------------+ +------------+ | + m ------>| | vint | bit | | 0 |.....|63| vint0 | + . | +--------------+ +------------+ | +------+ + . | . . | | HOST | + Globalevents ------>| . . |----->| IRQ | + . | . . | | CTRL | + . | . . | +------+ + n ------>| +--------------+ +------------+ | + | | vint | bit | | 0 |.....|63| vintx | + | +--------------+ +------------+ | + | | + +-----------------------------------------+ + + Configuration of these Intmap registers that maps global events to vint is + done by a system controller (like the Device Memory and Security Controller + on AM654 SoC). Driver should request the system controller to get the range + of global events and vints assigned to the requesting host. Management + of these requested resources should be handled by driver and requests + system controller to map specific global event to vint, bit pair. + + Communication between the host processor running an OS and the system + controller happens through a protocol called TI System Control Interface + (TISCI protocol). + +properties: + compatible: + const: ti,sci-inta + + reg: + maxItems: 1 + + interrupt-controller: true + + msi-controller: true + + ti,interrupt-ranges: + $ref: /schemas/types.yaml#/definitions/uint32-matrix + description: | + Interrupt ranges that converts the INTA output hw irq numbers + to parents's input interrupt numbers. + items: + items: + - description: | + "output_irq" specifies the base for inta output irq + - description: | + "parent's input irq" specifies the base for parent irq + - description: | + "limit" specifies the limit for translation + +required: + - compatible + - reg + - interrupt-controller + - msi-controller + - ti,sci + - ti,sci-dev-id + - ti,interrupt-ranges + +examples: + - | + bus { + #address-cells = <2>; + #size-cells = <2>; + + main_udmass_inta: msi-controller@33d00000 { + compatible = "ti,sci-inta"; + reg = <0x0 0x33d00000 0x0 0x100000>; + interrupt-controller; + msi-controller; + interrupt-parent = <&main_navss_intr>; + ti,sci = <&dmsc>; + ti,sci-dev-id = <179>; + ti,interrupt-ranges = <0 0 256>; + }; + }; diff --git a/Documentation/devicetree/bindings/interrupt-controller/ti,sci-intr.txt b/Documentation/devicetree/bindings/interrupt-controller/ti,sci-intr.txt deleted file mode 100644 index 1a8718f8855d6cf947462c9c4b90273bb99e5e58..0000000000000000000000000000000000000000 --- a/Documentation/devicetree/bindings/interrupt-controller/ti,sci-intr.txt +++ /dev/null @@ -1,82 +0,0 @@ -Texas Instruments K3 Interrupt Router -===================================== - -The Interrupt Router (INTR) module provides a mechanism to mux M -interrupt inputs to N interrupt outputs, where all M inputs are selectable -to be driven per N output. An Interrupt Router can either handle edge triggered -or level triggered interrupts and that is fixed in hardware. - - Interrupt Router - +----------------------+ - | Inputs Outputs | - +-------+ | +------+ +-----+ | - | GPIO |----------->| | irq0 | | 0 | | Host IRQ - +-------+ | +------+ +-----+ | controller - | . . | +-------+ - +-------+ | . . |----->| IRQ | - | INTA |----------->| . . | +-------+ - +-------+ | . +-----+ | - | +------+ | N | | - | | irqM | +-----+ | - | +------+ | - | | - +----------------------+ - -There is one register per output (MUXCNTL_N) that controls the selection. -Configuration of these MUXCNTL_N registers is done by a system controller -(like the Device Memory and Security Controller on K3 AM654 SoC). System -controller will keep track of the used and unused registers within the Router. -Driver should request the system controller to get the range of GIC IRQs -assigned to the requesting hosts. It is the drivers responsibility to keep -track of Host IRQs. - -Communication between the host processor running an OS and the system -controller happens through a protocol called TI System Control Interface -(TISCI protocol). For more details refer: -Documentation/devicetree/bindings/arm/keystone/ti,sci.txt - -TISCI Interrupt Router Node: ----------------------------- -Required Properties: -- compatible: Must be "ti,sci-intr". -- ti,intr-trigger-type: Should be one of the following: - 1: If intr supports edge triggered interrupts. - 4: If intr supports level triggered interrupts. -- interrupt-controller: Identifies the node as an interrupt controller -- #interrupt-cells: Specifies the number of cells needed to encode an - interrupt source. The value should be 2. - First cell should contain the TISCI device ID of source - Second cell should contain the interrupt source offset - within the device. -- ti,sci: Phandle to TI-SCI compatible System controller node. -- ti,sci-dst-id: TISCI device ID of the destination IRQ controller. -- ti,sci-rm-range-girq: Array of TISCI subtype ids representing the host irqs - assigned to this interrupt router. Each subtype id - 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 - -Example: --------- -The following example demonstrates both interrupt router node and the consumer -node(main gpio) on the AM654 SoC: - -main_intr: interrupt-controller0 { - compatible = "ti,sci-intr"; - ti,intr-trigger-type = <1>; - interrupt-controller; - interrupt-parent = <&gic500>; - #interrupt-cells = <2>; - ti,sci = <&dmsc>; - ti,sci-dst-id = <56>; - ti,sci-rm-range-girq = <0x1>; -}; - -main_gpio0: gpio@600000 { - ... - interrupt-parent = <&main_intr>; - interrupts = <57 256>, <57 257>, <57 258>, - <57 259>, <57 260>, <57 261>; - ... -}; diff --git a/Documentation/devicetree/bindings/interrupt-controller/ti,sci-intr.yaml b/Documentation/devicetree/bindings/interrupt-controller/ti,sci-intr.yaml new file mode 100644 index 0000000000000000000000000000000000000000..cff6a956afb44e287e9be0d9b15b693e4c6fdaa2 --- /dev/null +++ b/Documentation/devicetree/bindings/interrupt-controller/ti,sci-intr.yaml @@ -0,0 +1,102 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/interrupt-controller/ti,sci-intr.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Texas Instruments K3 Interrupt Router + +maintainers: + - Lokesh Vutla + +allOf: + - $ref: /schemas/arm/keystone/ti,k3-sci-common.yaml# + +description: | + The Interrupt Router (INTR) module provides a mechanism to mux M + interrupt inputs to N interrupt outputs, where all M inputs are selectable + to be driven per N output. An Interrupt Router can either handle edge + triggered or level triggered interrupts and that is fixed in hardware. + + Interrupt Router + +----------------------+ + | Inputs Outputs | + +-------+ | +------+ +-----+ | + | GPIO |----------->| | irq0 | | 0 | | Host IRQ + +-------+ | +------+ +-----+ | controller + | . . | +-------+ + +-------+ | . . |----->| IRQ | + | INTA |----------->| . . | +-------+ + +-------+ | . +-----+ | + | +------+ | N | | + | | irqM | +-----+ | + | +------+ | + | | + +----------------------+ + + There is one register per output (MUXCNTL_N) that controls the selection. + Configuration of these MUXCNTL_N registers is done by a system controller + (like the Device Memory and Security Controller on K3 AM654 SoC). System + controller will keep track of the used and unused registers within the Router. + Driver should request the system controller to get the range of GIC IRQs + assigned to the requesting hosts. It is the drivers responsibility to keep + track of Host IRQs. + + Communication between the host processor running an OS and the system + controller happens through a protocol called TI System Control Interface + (TISCI protocol). + +properties: + compatible: + const: ti,sci-intr + + ti,intr-trigger-type: + $ref: /schemas/types.yaml#/definitions/uint32 + enum: [1, 4] + description: | + Should be one of the following. + 1 = If intr supports edge triggered interrupts. + 4 = If intr supports level triggered interrupts. + + interrupt-controller: true + + '#interrupt-cells': + const: 1 + description: | + The 1st cell should contain interrupt router input hw number. + + ti,interrupt-ranges: + $ref: /schemas/types.yaml#/definitions/uint32-matrix + description: | + Interrupt ranges that converts the INTR output hw irq numbers + to parents's input interrupt numbers. + items: + items: + - description: | + "output_irq" specifies the base for intr output irq + - description: | + "parent's input irq" specifies the base for parent irq + - description: | + "limit" specifies the limit for translation + +required: + - compatible + - ti,intr-trigger-type + - interrupt-controller + - '#interrupt-cells' + - ti,sci + - ti,sci-dev-id + - ti,interrupt-ranges + +examples: + - | + main_gpio_intr: interrupt-controller0 { + compatible = "ti,sci-intr"; + ti,intr-trigger-type = <1>; + interrupt-controller; + interrupt-parent = <&gic500>; + #interrupt-cells = <1>; + ti,sci = <&dmsc>; + ti,sci-dev-id = <131>; + ti,interrupt-ranges = <0 360 32>; + }; diff --git a/Documentation/devicetree/bindings/iommu/arm,smmu.yaml b/Documentation/devicetree/bindings/iommu/arm,smmu.yaml index d7ceb4c34423b82079cea8a22757d38f593e7c12..503160a7b9a0956e4325587e5230aa40fc714bb0 100644 --- a/Documentation/devicetree/bindings/iommu/arm,smmu.yaml +++ b/Documentation/devicetree/bindings/iommu/arm,smmu.yaml @@ -37,7 +37,18 @@ properties: - 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 @@ properties: - 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 @@ required: 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 ce59a505f5a4c21ea288688b4d967e061274bc83..c1ccd8582eb2227155b34751b7002a51199c061f 100644 --- a/Documentation/devicetree/bindings/iommu/mediatek,iommu.txt +++ b/Documentation/devicetree/bindings/iommu/mediatek,iommu.txt @@ -58,6 +58,7 @@ Required properties: - 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 @@ Required properties: 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 39675cf4ed71c70fcf43569be451d69dfa59f1db..6bfa090fd73a98297056769c028a0d12b1f748fb 100644 --- a/Documentation/devicetree/bindings/iommu/renesas,ipmmu-vmsa.yaml +++ b/Documentation/devicetree/bindings/iommu/renesas,ipmmu-vmsa.yaml @@ -32,9 +32,11 @@ properties: - 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 321be6640533e9ee2d0ff024788f2800343f50d1..0000000000000000000000000000000000000000 --- 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 0000000000000000000000000000000000000000..75cc569b9c558f07473c4ccdc32de09f6f734acf --- /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 + - Daniel Thompson + - Jingoo Han + +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 + 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 4c7dfbe7f67ad943e428b1f18011eba7f3110ef2..0000000000000000000000000000000000000000 --- 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 0000000000000000000000000000000000000000..625082bf3892852ce175b018713459bd8ff3b83a --- /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 + - Daniel Thompson + - Jingoo Han + +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 64fa2fbd98c9e6a48fc9031423acffbe96e766a1..0000000000000000000000000000000000000000 --- 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 0000000000000000000000000000000000000000..fcb8429f3088cd6d7baf130d8ca4fb408e8ccb05 --- /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 + - Daniel Thompson + - Jingoo Han + +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/backlight/qcom-wled.yaml b/Documentation/devicetree/bindings/leds/backlight/qcom-wled.yaml index 32e0896c6bc13d917fa40c7425dda1d4f789683f..47938e3729877cf0d86b1341d6a96333365ee197 100644 --- a/Documentation/devicetree/bindings/leds/backlight/qcom-wled.yaml +++ b/Documentation/devicetree/bindings/leds/backlight/qcom-wled.yaml @@ -79,7 +79,8 @@ properties: description: | kHz; switching frequency. $ref: /schemas/types.yaml#/definitions/uint32 - enum: [ 600, 640, 685, 738, 800, 872, 960, 1066, 1200, 1371, 1600, 1920, 2400, 3200, 4800, 9600 ] + enum: [ 600, 640, 685, 738, 800, 872, 960, 1066, 1200, 1371, 1600, 1920, + 2400, 3200, 4800, 9600 ] qcom,ovp: description: | 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 0000000000000000000000000000000000000000..fe7fa25877fd20741551573b6d653664abd0a86c --- /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 + +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-b]$": + 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 + + 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 = ; + function = LED_FUNCTION_POWER; + linux,default-trigger = "heartbeat"; + }; + + multi-led@a { + reg = <0xa>; + color = ; + 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 0000000000000000000000000000000000000000..b55e1f1308a45e4e7ae4dcd3cc215137e44df400 --- /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 + +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 53793213dd52edb5b52b68a4c4bc4cebd7f026a5..097490a5ff91206ce8c8f0fe0a093a043f089416 100644 --- a/Documentation/devicetree/bindings/leds/leds-lm3532.txt +++ b/Documentation/devicetree/bindings/leds/leds-lm3532.txt @@ -102,4 +102,4 @@ led-controller@38 { }; 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 095dafb6ec7fba8f3f7913752f48c329c6ff2e57..17e940025dc26213314f5cfd54aa8e5bb09f86b7 100644 --- a/Documentation/devicetree/bindings/leds/leds-lm3601x.txt +++ b/Documentation/devicetree/bindings/leds/leds-lm3601x.txt @@ -47,5 +47,5 @@ led-controller@64 { } 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 39c230d59a4d8767e989f835b4a0daa266b56c56..de6f4931fb319bbf6731ceeee47968a133d27022 100644 --- a/Documentation/devicetree/bindings/leds/leds-lm36274.txt +++ b/Documentation/devicetree/bindings/leds/leds-lm36274.txt @@ -82,4 +82,4 @@ lm36274@11 { }; 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 501468aa4d38ecbb5dea68fda04fafba47beb4c1..b1103d961d6caadef60fdfb5a54fd50f9f3c0307 100644 --- a/Documentation/devicetree/bindings/leds/leds-lm3692x.txt +++ b/Documentation/devicetree/bindings/leds/leds-lm3692x.txt @@ -62,4 +62,4 @@ led-controller@36 { } 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 63992d732959e49dba82a4994e39d753ee752313..221b37b6049b43408291add49d4d7b848728b2df 100644 --- a/Documentation/devicetree/bindings/leds/leds-lm3697.txt +++ b/Documentation/devicetree/bindings/leds/leds-lm3697.txt @@ -70,4 +70,4 @@ led-controller@36 { } 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 1b66a413fb9dfed9c6bb2c94d5cc02b1e7e26532..0000000000000000000000000000000000000000 --- 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 0000000000000000000000000000000000000000..b1bb3feb0f4dabcde977fb797dde71551d06890d --- /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 + - Pavel Machek + +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 + + 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 = ; + function = LED_FUNCTION_STANDBY; + linux,default-trigger = "heartbeat"; + + led@0 { + led-cur = /bits/ 8 <50>; + max-cur = /bits/ 8 <100>; + reg = <0x0>; + color = ; + }; + + led@1 { + led-cur = /bits/ 8 <50>; + max-cur = /bits/ 8 <100>; + reg = <0x1>; + color = ; + }; + + led@6 { + led-cur = /bits/ 8 <50>; + max-cur = /bits/ 8 <100>; + reg = <0x6>; + color = ; + }; + }; + }; + }; + +... diff --git a/Documentation/devicetree/bindings/leds/leds-lp8860.txt b/Documentation/devicetree/bindings/leds/leds-lp8860.txt index 9863220db4ba6f8611c742269c806e09cc14b622..8bb25749a3da3ccc5fc9d66e23eb9631de476198 100644 --- a/Documentation/devicetree/bindings/leds/leds-lp8860.txt +++ b/Documentation/devicetree/bindings/leds/leds-lp8860.txt @@ -47,4 +47,4 @@ led-controller@2d { } 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 7984efb767b411ac6814bd139513e53d48fa7ff3..7a5830f8d5aba84d285e5756c0fc1debe9bfd76d 100644 --- a/Documentation/devicetree/bindings/leds/leds-pca955x.txt +++ b/Documentation/devicetree/bindings/leds/leds-pca955x.txt @@ -26,9 +26,9 @@ LED sub-node properties: 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/fsl,mu.yaml b/Documentation/devicetree/bindings/mailbox/fsl,mu.yaml index 3b35eb5ac3f90fd9d40f096bf23e71bb5ef00f95..8a3470b64d061179b1a4f6fca63d71bbdefb3538 100644 --- a/Documentation/devicetree/bindings/mailbox/fsl,mu.yaml +++ b/Documentation/devicetree/bindings/mailbox/fsl,mu.yaml @@ -29,12 +29,12 @@ properties: - const: fsl,imx8-mu-scu - items: - enum: - - fsl,imx7s-mu - - fsl,imx8mq-mu - - fsl,imx8mm-mu - - fsl,imx8mn-mu - - fsl,imx8mp-mu - - fsl,imx8qxp-mu + - fsl,imx7s-mu + - fsl,imx8mq-mu + - fsl,imx8mm-mu + - fsl,imx8mn-mu + - fsl,imx8mp-mu + - fsl,imx8qxp-mu - const: fsl,imx6sx-mu - description: To communicate with i.MX8 SCU with fast IPC items: diff --git a/Documentation/devicetree/bindings/mailbox/mtk-gce.txt b/Documentation/devicetree/bindings/mailbox/mtk-gce.txt index 0b5b2a6bcc4885c9070a5256964e506109fa5c36..cf48cd806e0022a793663cd8d13fde504168ea02 100644 --- a/Documentation/devicetree/bindings/mailbox/mtk-gce.txt +++ b/Documentation/devicetree/bindings/mailbox/mtk-gce.txt @@ -9,7 +9,8 @@ CMDQ driver uses mailbox framework for communication. Please refer to 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: A