diff --git a/.mailmap b/.mailmap index db4f2295bd9d..a96f1b38fa58 100644 --- a/.mailmap +++ b/.mailmap @@ -18,6 +18,9 @@ Aleksey Gorelov Aleksandar Markovic Alex Shi Alex Shi +Alexander Lobakin +Alexander Lobakin +Alexander Lobakin Alexandre Belloni Alexei Starovoitov Alexei Starovoitov @@ -134,6 +137,11 @@ 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 @@ -151,6 +159,7 @@ Kamil Konieczny Kay Sievers Kenneth W Chen Konstantin Khlebnikov +Konstantin Khlebnikov Koushik Krzysztof Kozlowski Krzysztof Kozlowski diff --git a/CREDITS b/CREDITS index 0787b5872906..32ee70a7562e 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/testing/sysfs-driver-w1_therm b/Documentation/ABI/testing/sysfs-driver-w1_therm index 076659d506f2..9b488c0afdfa 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/PCI/endpoint/function/binding/pci-test.rst b/Documentation/PCI/endpoint/function/binding/pci-test.rst new file mode 100644 index 000000000000..57ee866fb165 --- /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 cd76ba47394b..000000000000 --- 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 d114ea74b444..4ca7439fbfc9 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 b6d39cdec56e..1bbd81ed06c8 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 7536be445db8..4f5622a65555 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 13beee23cb04..9fa49a6ece85 100644 --- a/Documentation/PCI/pci-error-recovery.rst +++ b/Documentation/PCI/pci-error-recovery.rst @@ -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. diff --git a/Documentation/PCI/pci.rst b/Documentation/PCI/pci.rst index 8c016d8c9862..c35b187d5479 100644 --- a/Documentation/PCI/pci.rst +++ b/Documentation/PCI/pci.rst @@ -209,7 +209,7 @@ 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. @@ -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 diff --git a/Documentation/admin-guide/LSM/Yama.rst b/Documentation/admin-guide/LSM/Yama.rst index d0a060de3973..d9cd937ebd2d 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 68ecd5c113e9..561fd1e35917 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 4a8f31cf4139..0328438ebe2c 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/cgroup-v1/rdma.rst b/Documentation/admin-guide/cgroup-v1/rdma.rst index 2fcb0a9bf790..e69369b7252e 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 a789755c311d..fa4018afa5a4 100644 --- a/Documentation/admin-guide/cgroup-v2.rst +++ b/Documentation/admin-guide/cgroup-v2.rst @@ -1683,9 +1683,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 @@ -2042,7 +2042,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 084c25f92dcb..25f11576e7b9 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 d3fb67b8a976..7b32d5063803 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 322a9c833f23..993186beea20 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 8d70e1fc9f9d..2196caf1b939 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-integrity.rst b/Documentation/admin-guide/device-mapper/dm-integrity.rst index 9edd45593abd..3ab4f7756a6e 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 695a2ea1d1ae..7ef9fe63b3d4 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 553752ea2521..e635041351bc 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/devices.txt b/Documentation/admin-guide/devices.txt index 2a97aaec8b12..d336f3f73a4c 100644 --- a/Documentation/admin-guide/devices.txt +++ b/Documentation/admin-guide/devices.txt @@ -375,8 +375,9 @@ 239 = /dev/uhid User-space I/O driver support for HID subsystem 240 = /dev/userio Serio driver testing device 241 = /dev/vhost-vsock Host kernel driver for virtio vsock + 242 = /dev/rfkill Turning off radio transmissions (rfkill) - 242-254 Reserved for local use + 243-254 Reserved for local use 255 Reserved for MISC_DYNAMIC_MINOR 11 char Raw keyboard device (Linux/SPARC only) @@ -1442,7 +1443,7 @@ ... The driver and documentation may be obtained from - http://www.winradio.com/ + https://www.winradio.com/ 82 block I2O hard disk 0 = /dev/i2o/hdag 33rd I2O hard disk, whole disk @@ -1656,7 +1657,7 @@ dynamically, so there is no fixed mapping from subdevice pathnames to minor numbers. - See http://www.comedi.org/ for information about the Comedi + See https://www.comedi.org/ for information about the Comedi project. 98 block User-mode virtual block device @@ -1723,7 +1724,7 @@ implementations a kernel presence for caching and easy mounting. For more information about the project, write to 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/ext4.rst b/Documentation/admin-guide/ext4.rst index 2162d7909970..a683976fad6d 100644 --- a/Documentation/admin-guide/ext4.rst +++ b/Documentation/admin-guide/ext4.rst @@ -618,7 +618,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 47b1b3afac99..3b1ce68d2456 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 58c7f9fc2396..ed1cf94ea50c 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/kernel-parameters.txt b/Documentation/admin-guide/kernel-parameters.txt index ad929b807b26..ff5018b39ed0 100644 --- a/Documentation/admin-guide/kernel-parameters.txt +++ b/Documentation/admin-guide/kernel-parameters.txt @@ -1212,26 +1212,28 @@ Format: {"off" | "on" | "skip[mbr]"} efi= [EFI] - Format: { "old_map", "nochunk", "noruntime", "debug", - "nosoftreserve", "disable_early_pci_dma", - "no_disable_early_pci_dma" } - old_map [X86-64]: switch to the old ioremap-based EFI - runtime services mapping. [Needs CONFIG_X86_UV=y] + Format: { "debug", "disable_early_pci_dma", + "nochunk", "noruntime", "nosoftreserve", + "novamap", "no_disable_early_pci_dma", + "old_map" } + debug: enable misc debug output. + disable_early_pci_dma: disable the busmaster bit on all + PCI bridges while in the EFI boot stub. nochunk: disable reading files in "chunks" in the EFI boot stub, as chunking can cause problems with some firmware implementations. noruntime : disable EFI runtime services support - debug: enable misc debug output nosoftreserve: The EFI_MEMORY_SP (Specific Purpose) attribute may cause the kernel to reserve the memory range for a memory mapping driver to claim. Specify efi=nosoftreserve to disable this reservation and treat the memory by its base type (i.e. EFI_CONVENTIONAL_MEMORY / "System RAM"). - disable_early_pci_dma: Disable the busmaster bit on all - PCI bridges while in the EFI boot stub + novamap: do not call SetVirtualAddressMap(). no_disable_early_pci_dma: Leave the busmaster bit set on all PCI bridges while in the EFI boot stub + old_map [X86-64]: switch to the old ioremap-based EFI + runtime services mapping. [Needs CONFIG_X86_UV=y] efi_no_storage_paranoia [EFI; X86] Using this parameter you can use more than 50% of @@ -2791,7 +2793,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 diff --git a/Documentation/admin-guide/laptops/disk-shock-protection.rst b/Documentation/admin-guide/laptops/disk-shock-protection.rst index e97c5f78d8c3..22c7ec3e84cf 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 c6eaaf48f7c1..190da1234314 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 fb0d346bf31a..5e477869df18 100644 --- a/Documentation/admin-guide/laptops/thinkpad-acpi.rst +++ b/Documentation/admin-guide/laptops/thinkpad-acpi.rst @@ -905,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: @@ -926,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 @@ -936,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 diff --git a/Documentation/admin-guide/media/building.rst b/Documentation/admin-guide/media/building.rst index c898e3a981c1..2d660b76caea 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/mm/concepts.rst b/Documentation/admin-guide/mm/concepts.rst index c2531b14bf46..fa0974fbeae7 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 5026e58826e2..015a5f7d7854 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 11db46448354..cd727cfc1b04 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 874eb0c77d34..97d816791aca 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 a80c3c37226e..4d69ef1de830 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 c4b777c7584b..6adb6457bc69 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 ef0f3678b1fb..f137485f8bde 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 c6772075c80c..135218f33394 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 b00a2e705cc4..20fe9f5117fe 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 d2f6ee558071..b2eec2288329 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 832b0c64023a..f62f7fe50eba 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/intel-speed-select.rst b/Documentation/admin-guide/pm/intel-speed-select.rst index b2ca601c21c6..219f1359aac7 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 40d481cca368..9db924904d2c 100644 --- a/Documentation/admin-guide/pm/intel_pstate.rst +++ b/Documentation/admin-guide/pm/intel_pstate.rst @@ -723,7 +723,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 dcd6c93c7aac..c32eb786201c 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/sysctl/fs.rst b/Documentation/admin-guide/sysctl/fs.rst index 2a45119e3331..f48277a0a850 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 55bf6b4de4ec..2ae9669eb22c 100644 --- a/Documentation/admin-guide/sysctl/kernel.rst +++ b/Documentation/admin-guide/sysctl/kernel.rst @@ -235,7 +235,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 +335,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 +646,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 +996,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 ================== diff --git a/Documentation/admin-guide/sysctl/vm.rst b/Documentation/admin-guide/sysctl/vm.rst index d46d5b7013c6..d997cc3c26d0 100644 --- a/Documentation/admin-guide/sysctl/vm.rst +++ b/Documentation/admin-guide/sysctl/vm.rst @@ -583,7 +583,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 71e9184a9079..abf804719890 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/xfs.rst b/Documentation/admin-guide/xfs.rst index ad911be5b5e9..f461d6c33534 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/booting.rst b/Documentation/arm/booting.rst index 4babb6c6ae1e..a2263451dc2c 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 d51b69dc624d..377e9d224db0 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 872dbbc73d4a..47ecb9930dde 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 09cbb4ed2237..d9665d83c53a 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.txt b/Documentation/arm64/perf.rst similarity index 95% rename from Documentation/arm64/perf.txt rename to Documentation/arm64/perf.rst index 0d6a7d87d49e..9c76a97baf28 100644 --- a/Documentation/arm64/perf.txt +++ b/Documentation/arm64/perf.rst @@ -1,8 +1,11 @@ +.. SPDX-License-Identifier: GPL-2.0 + +===================== Perf Event Attributes ===================== -Author: Andrew Murray -Date: 2019-03-06 +:Author: Andrew Murray +:Date: 2019-03-06 exclude_user ------------ diff --git a/Documentation/arm64/sve.rst b/Documentation/arm64/sve.rst index bfd55f468258..03137154299e 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/block/biodoc.rst b/Documentation/block/biodoc.rst index afda5e30a82e..1d4d71e391af 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. diff --git a/Documentation/block/blk-mq.rst b/Documentation/block/blk-mq.rst new file mode 100644 index 000000000000..88c56afcb070 --- /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 026addfc69bc..86dcf7159f99 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 30ea1c2e39eb..c893d6da8e04 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/bpf/bpf_devel_QA.rst b/Documentation/bpf/bpf_devel_QA.rst index 0b3db91dc100..a26aa1b9b259 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/index.rst b/Documentation/bpf/index.rst index 38b4db8be7a2..0f60b95e83c4 100644 --- a/Documentation/bpf/index.rst +++ b/Documentation/bpf/index.rst @@ -58,6 +58,14 @@ Testing and debugging BPF s390 +Other +===== + +.. toctree:: + :maxdepth: 1 + + ringbuf + .. Links: .. _Documentation/networking/filter.rst: ../networking/filter.txt .. _man-pages: https://www.kernel.org/doc/man-pages/ diff --git a/Documentation/bus-virt-phys-mapping.txt b/Documentation/core-api/bus-virt-phys-mapping.rst similarity index 99% rename from Documentation/bus-virt-phys-mapping.txt rename to Documentation/core-api/bus-virt-phys-mapping.rst index 4bb07c2f3e7d..c7bc99cd2e21 100644 --- a/Documentation/bus-virt-phys-mapping.txt +++ b/Documentation/core-api/bus-virt-phys-mapping.rst @@ -8,7 +8,7 @@ How to access I/O mapped memory from within device drivers 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 + (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 diff --git a/Documentation/core-api/cpu_hotplug.rst b/Documentation/core-api/cpu_hotplug.rst index 4a50ab7817f7..f64668759b6a 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 f41620439ef3..3b3abbbb4b9a 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 b1ec7b16c21f..e59a3d35a93d 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/index.rst b/Documentation/core-api/index.rst index 15ab86112627..69171b1799f2 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 e93dc8cf52dd..2739f8b72575 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 4aa82ddd01b8..4446a1ac36cc 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/printk-basics.rst b/Documentation/core-api/printk-basics.rst index 563a9ce5fe1d..965e4281eddd 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 1beac4719e43..6d26c5c6ac48 100644 --- a/Documentation/core-api/printk-formats.rst +++ b/Documentation/core-api/printk-formats.rst @@ -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.txt b/Documentation/crypto/api-intro.rst similarity index 70% rename from Documentation/crypto/api-intro.txt rename to Documentation/crypto/api-intro.rst index 40137f93e04f..15201be0b811 100644 --- a/Documentation/crypto/api-intro.txt +++ b/Documentation/crypto/api-intro.rst @@ -1,7 +1,11 @@ +.. SPDX-License-Identifier: GPL-2.0 - Scatterlist Cryptographic API - -INTRODUCTION +============================= +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 @@ -13,22 +17,23 @@ so that processing can be applied to paged skb's without the need for linearization. -DETAILS +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 +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: +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. @@ -44,21 +49,21 @@ 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: +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); @@ -67,18 +72,19 @@ Here's an example of how to use the API: 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 +Developer Notes +=============== Transforms may only be allocated in user context, and cryptographic methods may only be called from softirq and user contexts. For @@ -91,7 +97,8 @@ size (typically 8 bytes). This prevents having to do any copying across non-aligned page fragment boundaries. -ADDING NEW ALGORITHMS +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 @@ -119,132 +126,137 @@ Also check the TODO list at the web site listed below to see what people might already be working on. -BUGS +Bugs +==== Send bug reports to: -linux-crypto@vger.kernel.org -Cc: Herbert Xu , + linux-crypto@vger.kernel.org + +Cc: + Herbert Xu , David S. Miller -FURTHER INFORMATION +Further Information +=================== For further patches and various updates, including the current TODO list, see: http://gondor.apana.org.au/~herbert/crypto/ -AUTHORS +Authors +======= -James Morris -David S. Miller -Herbert Xu +- James Morris +- David S. Miller +- Herbert Xu -CREDITS +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 + - 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 + - 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 + - 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) + - 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 - + - Jean-Francois Dive + DES algorithm contributors: - Raimar Falke - Gisle Sælensminde - Niels Möller + - Raimar Falke + - Gisle Sælensminde + - Niels Möller Blowfish algorithm contributors: - Herbert Valerio Riedel - Kyle McMartin + - Herbert Valerio Riedel + - Kyle McMartin Twofish algorithm contributors: - Werner Koch - Marc Mutz + - Werner Koch + - Marc Mutz SHA256/384/512 algorithm contributors: - Andrew McDonald - Kyle McMartin - Herbert Valerio Riedel - + - 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) + - 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). + - Kartikey Mahendra Bhatt (original developers unknown, FSF copyright). TEA/XTEA algorithm contributors: - Aaron Grothe - Michael Ringe + - Aaron Grothe + - Michael Ringe Khazad algorithm contributors: - Aaron Grothe + - Aaron Grothe Whirlpool algorithm contributors: - Aaron Grothe - Jean-Luc Cooke + - Aaron Grothe + - Jean-Luc Cooke Anubis algorithm contributors: - Aaron Grothe + - Aaron Grothe Tiger algorithm contributors: - Aaron Grothe + - Aaron Grothe VIA PadLock contributors: - Michal Ludvig + - Michal Ludvig Camellia algorithm contributors: - NTT(Nippon Telegraph and Telephone Corporation) (Camellia) + - 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.txt b/Documentation/crypto/asymmetric-keys.rst similarity index 91% rename from Documentation/crypto/asymmetric-keys.txt rename to Documentation/crypto/asymmetric-keys.rst index 8763866b11cf..349f44a29392 100644 --- a/Documentation/crypto/asymmetric-keys.txt +++ b/Documentation/crypto/asymmetric-keys.rst @@ -1,8 +1,10 @@ - ============================================= - ASYMMETRIC / PUBLIC-KEY CRYPTOGRAPHY KEY TYPE - ============================================= +.. SPDX-License-Identifier: GPL-2.0 -Contents: +============================================= +Asymmetric / Public-key Cryptography Key Type +============================================= + +.. Contents: - Overview. - Key identification. @@ -13,8 +15,7 @@ Contents: - Keyring link restrictions. -======== -OVERVIEW +Overview ======== The "asymmetric" key type is designed to be a container for the keys used in @@ -42,8 +43,7 @@ key, or it may interpret it as a reference to a key held somewhere else in the system (for example, a TPM). -================== -KEY IDENTIFICATION +Key Identification ================== If a key is added with an empty name, the instantiation data parsers are given @@ -57,49 +57,48 @@ 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 + 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: + after the "id:" match the tail. For instance:: keyctl search @s asymmetric id:5acc2142 - will match a key with fingerprint: + 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 + 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: + 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: +displayed, along with the subtype:: 1a39e171 I----- 1 perm 3f010000 0 0 asymmetric modsign.0: DSA 5acc2142 [] -========================= -ACCESSING ASYMMETRIC KEYS +Accessing Asymmetric Keys ========================= For general access to asymmetric keys from within the kernel, the following -inclusion is required: +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: +algorithms:: enum pkey_algo -digest algorithms used by those: +digest algorithms used by those:: enum pkey_hash_algo -and key identifier representations: +and key identifier representations:: enum pkey_id_type @@ -110,25 +109,25 @@ PGP-specific metadata, whereas X.509 has arbitrary certificate identifiers. The operations defined upon a key are: - (1) Signature verification. + 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 +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. +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. +transferred the relevant bits to the structure pointed to by sig:: struct public_key_signature { u8 *digest; @@ -159,8 +158,7 @@ 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 Key Subtypes ======================= Asymmetric keys have a subtype that defines the set of operations that can be @@ -171,11 +169,11 @@ 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: +The subtype definition structure can be found in:: #include -and looks like the following: +and looks like the following:: struct asymmetric_key_subtype { struct module *owner; @@ -198,39 +196,37 @@ the subtype. Currently, the name is only used for print statements. There are a number of operations defined by the subtype: - (1) describe(). + 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(). + 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(). + 3) query(). Mandatory. This is a function for querying the capabilities of a key. - (4) eds_op(). + 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(). + 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 +Instantiation Data Parsers ========================== The asymmetric key type doesn't generally want to store or to deal with a raw @@ -254,11 +250,11 @@ Examples of blob formats for which parsers could be implemented include: During key instantiation each parser in the list is tried until one doesn't return -EBADMSG. -The parser definition structure can be found in: +The parser definition structure can be found in:: #include -and looks like the following: +and looks like the following:: struct asymmetric_key_parser { struct module *owner; @@ -273,7 +269,7 @@ the parser. There is currently only a single operation defined by the parser, and it is mandatory: - (1) parse(). + 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 @@ -282,7 +278,7 @@ mandatory: 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]. + Documentation/security/keys/core.rst]:: struct key_preparsed_payload { char *description; @@ -321,7 +317,7 @@ mandatory: 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: +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); @@ -330,8 +326,7 @@ Parsers may not have the same name. The names are otherwise only used for displaying in debugging messages. -========================= -KEYRING LINK RESTRICTIONS +Keyring Link Restrictions ========================= Keyrings created from userspace using add_key can be configured to check the @@ -340,7 +335,7 @@ allowed to link. Several restriction methods are available: - (1) Restrict using the kernel builtin trusted keyring + 1) Restrict using the kernel builtin trusted keyring - Option string used with KEYCTL_RESTRICT_KEYRING: - "builtin_trusted" @@ -350,7 +345,7 @@ Several restriction methods are available: 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 + 2) Restrict using the kernel builtin and secondary trusted keyrings - Option string used with KEYCTL_RESTRICT_KEYRING: - "builtin_and_secondary_trusted" @@ -361,7 +356,7 @@ Several restriction methods are available: kernel parameter also affects which keys are used for signature verification. - (3) Restrict using a separate key or keyring + 3) Restrict using a separate key or keyring - Option string used with KEYCTL_RESTRICT_KEYRING: - "key_or_keyring:[:chain]" @@ -378,7 +373,7 @@ Several restriction methods are available: 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: + certificate chain to be validated:: # Create and populate a keyring for root certificates root_id=`keyctl add keyring root-certs "" @s` @@ -400,7 +395,7 @@ Several restriction methods are available: 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: + 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` diff --git a/Documentation/crypto/async-tx-api.txt b/Documentation/crypto/async-tx-api.rst similarity index 55% rename from Documentation/crypto/async-tx-api.txt rename to Documentation/crypto/async-tx-api.rst index 7bf1be20d93a..bfc773991bdc 100644 --- a/Documentation/crypto/async-tx-api.txt +++ b/Documentation/crypto/async-tx-api.rst @@ -1,27 +1,32 @@ - Asynchronous Transfers/Transforms API +.. SPDX-License-Identifier: GPL-2.0 -1 INTRODUCTION +===================================== +Asynchronous Transfers/Transforms API +===================================== -2 GENEALOGY +.. Contents -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 + 1. INTRODUCTION -4 DMAENGINE DRIVER DEVELOPER NOTES -4.1 Conformance points -4.2 "My application needs exclusive control of hardware channels" + 2 GENEALOGY -5 SOURCE + 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" -1 INTRODUCTION + 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 @@ -31,7 +36,8 @@ 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 +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 @@ -39,40 +45,52 @@ 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 + +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 +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 +3. dmaengine extensions to support multiple clients and operation types beyond 'memcpy' -3 USAGE +3. Usage +======== -3.1 General format of the API: -struct dma_async_tx_descriptor * -async_(, struct async_submit ctl *submit) +3.1 General format of the API +----------------------------- -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 +:: + + 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 +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 +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 +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 +2data (raid6_2data_recov) recover 2 raid6 data blocks from the given sources +======== ==================================================================== + +3.3 Descriptor management +------------------------- -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 @@ -82,12 +100,15 @@ 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 + +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. 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 @@ -98,12 +119,15 @@ 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 + +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 +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 @@ -111,83 +135,95 @@ of an operation. 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 +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 +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: +3.7 Example +----------- + Perform a xor->copy->xor operation where each operation depends on the -result from the previous operation: +result from the previous operation:: -void callback(void *param) -{ - struct completion *cmp = param; + void callback(void *param) + { + struct completion *cmp = param; - complete(cmp); -} + 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; + 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) + 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); + 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); + 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(); + async_tx_issue_pending_all(); - wait_for_completion(&cmp); -} + 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. Driver Development Notes +=========================== + +4.1 Conformance points +---------------------- -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 + +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); +The interface is:: -Where dma_filter_fn is defined as: -typedef bool (*dma_filter_fn)(struct dma_chan *chan, void *filter_param); + 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 @@ -207,19 +243,28 @@ 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 + +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 +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 +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 +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.txt b/Documentation/crypto/descore-readme.rst similarity index 81% rename from Documentation/crypto/descore-readme.txt rename to Documentation/crypto/descore-readme.rst index 16e9e6350755..45bd9c8babf4 100644 --- a/Documentation/crypto/descore-readme.txt +++ b/Documentation/crypto/descore-readme.rst @@ -1,8 +1,20 @@ -Below is the original README file from the descore.shar package. +.. 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 (C) 1992 Dana L. How + +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 @@ -20,13 +32,12 @@ 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' <<== +.. 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. @@ -36,7 +47,7 @@ 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 +(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, @@ -47,11 +58,13 @@ 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) + + - 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 @@ -63,15 +76,20 @@ this code (byte-order independent): 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) + + - 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% @@ -79,10 +97,15 @@ kerberos des replacement from australia (version 1.95): 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) + + - 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 @@ -91,48 +114,60 @@ kerberos des replacement from australia (version 1.95): 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!) + + - 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 + 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) +``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 + - 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, @@ -142,10 +177,10 @@ 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' +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 +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. @@ -167,12 +202,13 @@ 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' +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 @@ -184,8 +220,8 @@ perhaps some will still regard the result as a mess! 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. +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 @@ -195,40 +231,46 @@ 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,' +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 +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 + 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 + + ``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 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. @@ -236,15 +278,18 @@ 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. + + - 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 + 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, @@ -253,25 +298,31 @@ 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. +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):: -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: +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. @@ -288,7 +339,7 @@ datatypes: must be long-aligned. DesQuickInit() - call this before using any other routine with `Quick' in its name. + 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 @@ -298,6 +349,7 @@ DesMethod(m, k) 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, @@ -308,19 +360,26 @@ DesMethod(m, k) 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 *). + 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 @@ -329,15 +388,17 @@ Des{Small|Quick}{Fips|Core}{Encrypt|Decrypt}(d, m, s) 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. +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(). @@ -347,6 +408,7 @@ 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 c4ff5d791233..21338fa92642 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/dev-tools/coccinelle.rst b/Documentation/dev-tools/coccinelle.rst index 70274c3f5f5a..6c791af1c859 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 --------------------------------------------- @@ -183,7 +183,7 @@ To check only newly edited code, use the value 2 for the C flag, i.e.:: make C=2 CHECK="scripts/coccicheck" -In these modes, which works on a file basis, there is no information +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 +198,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 +211,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 +229,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 +237,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 +260,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 +290,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 +317,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 +327,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 7bd013596217..9e989baae154 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/kgdb.rst b/Documentation/dev-tools/kgdb.rst index 61293f40bc6e..0e52e966a153 100644 --- a/Documentation/dev-tools/kgdb.rst +++ b/Documentation/dev-tools/kgdb.rst @@ -872,7 +872,7 @@ 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 diff --git a/Documentation/dev-tools/kmemleak.rst b/Documentation/dev-tools/kmemleak.rst index fce262883984..a41a2d238af2 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/sparse.rst b/Documentation/dev-tools/sparse.rst index 6f4870528226..02102be7ff49 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/booting-without-of.txt b/Documentation/devicetree/booting-without-of.rst similarity index 90% rename from Documentation/devicetree/booting-without-of.txt rename to Documentation/devicetree/booting-without-of.rst index 4660ccee35a3..e9433350a20f 100644 --- a/Documentation/devicetree/booting-without-of.txt +++ b/Documentation/devicetree/booting-without-of.rst @@ -1,15 +1,19 @@ - Booting the Linux/ppc kernel without Open Firmware - -------------------------------------------------- +.. SPDX-License-Identifier: GPL-2.0 -(c) 2005 Benjamin Herrenschmidt , - IBM Corp. -(c) 2005 Becky Bruce , - Freescale Semiconductor, FSL SOC and 32-bit additions -(c) 2006 MontaVista Software, Inc. - Flash chip node definition +================================================== +Booting the Linux/ppc kernel without Open Firmware +================================================== -Table of Contents -================= +Copyright (c) 2005 Benjamin Herrenschmidt , +IBM Corp. + +Copyright (c) 2005 Becky Bruce , +Freescale Semiconductor, FSL SOC and 32-bit additions + +Copyright (c) 2006 MontaVista Software, Inc. +Flash chip node definition + +.. Table of Contents I - Introduction 1) Entry point for arch/arm @@ -61,15 +65,18 @@ Table of Contents Revision Information ==================== - May 18, 2005: Rev 0.1 - Initial draft, no chapter III yet. + May 18, 2005: Rev 0.1 + - Initial draft, no chapter III yet. - May 19, 2005: Rev 0.2 - Add chapter III and bits & pieces here or + May 19, 2005: Rev 0.2 + - Add chapter III and bits & pieces here or clarifies the fact that a lot of things are optional, the kernel only requires a very small device tree, though it is encouraged to provide an as complete one as possible. - May 24, 2005: Rev 0.3 - Precise that DT block has to be in RAM + May 24, 2005: Rev 0.3 + - Precise that DT block has to be in RAM - Misc fixes - Define version 3 and new format version 16 for the DT block (version 16 needs kernel @@ -82,7 +89,8 @@ Revision Information "name" property is now automatically deduced from the unit name - June 1, 2005: Rev 0.4 - Correct confusion between OF_DT_END and + June 1, 2005: Rev 0.4 + - Correct confusion between OF_DT_END and OF_DT_END_NODE in structure definition. - Change version 16 format to always align property data to 4 bytes. Since tokens are @@ -115,7 +123,7 @@ Revision Information - Compare FSL SOC use of PCI to standard and make sure no new node definition required. - Add more information about node definitions for SOC devices - that currently have no standard, like the FSL CPM. + that currently have no standard, like the FSL CPM. I - Introduction @@ -260,7 +268,7 @@ it with special cases. b) create your main platform file as "arch/powerpc/platforms/myplatform/myboard_setup.c" and add it - to the Makefile under the condition of your CONFIG_ + to the Makefile under the condition of your ``CONFIG_`` option. This file will define a structure of type "ppc_md" containing the various callbacks that the generic code will use to get to your platform specific code @@ -271,7 +279,7 @@ it with special cases. with classic Powerpc architectures. 3) Entry point for arch/x86 -------------------------------- +--------------------------- There is one single 32bit entry point to the kernel at code32_start, the decompressor (the real mode entry point goes to the same 32bit @@ -280,9 +288,9 @@ it with special cases. Documentation/x86/boot.rst The physical pointer to the device-tree block (defined in chapter II) is passed via setup_data which requires at least boot protocol 2.09. - The type filed is defined as + The type filed is defined as:: - #define SETUP_DTB 2 + #define SETUP_DTB 2 This device-tree is used as an extension to the "boot page". As such it does not parse / consider data which is already covered by the boot @@ -354,9 +362,9 @@ the block to RAM before passing it to the kernel. The kernel is passed the physical address pointing to an area of memory that is roughly described in include/linux/of_fdt.h by the structure - boot_param_header: + boot_param_header::: -struct boot_param_header { + struct boot_param_header { u32 magic; /* magic word OF_DT_HEADER */ u32 totalsize; /* total size of DT block */ u32 off_dt_struct; /* offset to structure */ @@ -374,19 +382,19 @@ struct boot_param_header { /* version 17 fields below */ u32 size_dt_struct; /* size of the DT structure block */ -}; + }; - Along with the constants: + Along with the constants:: -/* Definitions used by the flattened device tree */ -#define OF_DT_HEADER 0xd00dfeed /* 4: version, - 4: total size */ -#define OF_DT_BEGIN_NODE 0x1 /* Start node: full name - */ -#define OF_DT_END_NODE 0x2 /* End node */ -#define OF_DT_PROP 0x3 /* Property: name off, - size, content */ -#define OF_DT_END 0x9 + /* Definitions used by the flattened device tree */ + #define OF_DT_HEADER 0xd00dfeed /* 4: version, + 4: total size */ + #define OF_DT_BEGIN_NODE 0x1 /* Start node: full name + */ + #define OF_DT_END_NODE 0x2 /* End node */ + #define OF_DT_PROP 0x3 /* Property: name off, + size, content */ + #define OF_DT_END 0x9 All values in this header are in big endian format, the various fields in this header are defined more precisely below. All @@ -430,7 +438,7 @@ struct boot_param_header { way to avoid overriding critical things like, on Open Firmware capable machines, the RTAS instance, or on some pSeries, the TCE tables used for the iommu. Typically, the reserve map should - contain _at least_ this DT block itself (header,total_size). If + contain **at least** this DT block itself (header,total_size). If you are passing an initrd to the kernel, you should reserve it as well. You do not need to reserve the kernel image itself. The map should be 64-bit aligned. @@ -485,7 +493,7 @@ struct boot_param_header { So the typical layout of a DT block (though the various parts don't need to be in that order) looks like this (addresses go from top to - bottom): + bottom):: ------------------------------ @@ -511,9 +519,9 @@ struct boot_param_header { | --- (base + totalsize) - (*) The alignment gaps are not necessarily present; their presence - and size are dependent on the various alignment requirements of - the individual data blocks. + (*) The alignment gaps are not necessarily present; their presence + and size are dependent on the various alignment requirements of + the individual data blocks. 2) Device tree generalities @@ -600,7 +608,7 @@ discussed in a later chapter. At this point, it is only meant to give you a idea of what a device-tree looks like. I have purposefully kept the "name" and "linux,phandle" properties which aren't necessary in order to give you a better idea of what the tree looks like in -practice. +practice:: / o device-tree |- name = "device-tree" @@ -650,6 +658,7 @@ properties and their content. 3) Device tree "structure" block +-------------------------------- The structure of the device tree is a linearized tree structure. The "OF_DT_BEGIN_NODE" token starts a new node, and the "OF_DT_END_NODE" @@ -666,12 +675,14 @@ Here's the basic structure of a single node: root node) * [align gap to next 4 bytes boundary] * for each property: + * token OF_DT_PROP (that is 0x00000003) * 32-bit value of property value size in bytes (or 0 if no value) * 32-bit value of offset in string block of property name * property value data if any * [align gap to next 4 bytes boundary] + * [child nodes if any] * token OF_DT_END_NODE (that is 0x00000002) @@ -688,6 +699,7 @@ manipulating a flattened tree must take care to preserve this constraint. 4) Device tree "strings" block +------------------------------ In order to save space, property names, which are generally redundant, are stored separately in the "strings" block. This block is simply the @@ -700,15 +712,17 @@ strings block. III - Required content of the device tree ========================================= -WARNING: All "linux,*" properties defined in this document apply only -to a flattened device-tree. If your platform uses a real -implementation of Open Firmware or an implementation compatible with -the Open Firmware client interface, those properties will be created -by the trampoline code in the kernel's prom_init() file. For example, -that's where you'll have to add code to detect your board model and -set the platform number. However, when using the flattened device-tree -entry point, there is no prom_init() pass, and thus you have to -provide those properties yourself. +.. Warning:: + + All ``linux,*`` properties defined in this document apply only + to a flattened device-tree. If your platform uses a real + implementation of Open Firmware or an implementation compatible with + the Open Firmware client interface, those properties will be created + by the trampoline code in the kernel's prom_init() file. For example, + that's where you'll have to add code to detect your board model and + set the platform number. However, when using the flattened device-tree + entry point, there is no prom_init() pass, and thus you have to + provide those properties yourself. 1) Note about cells and address representation @@ -769,7 +783,7 @@ addresses), all buses must contain a "ranges" property. If the "ranges" property is missing at a given level, it's assumed that translation isn't possible, i.e., the registers are not visible on the parent bus. The format of the "ranges" property for a bus is a list -of: +of:: bus address, parent bus address, size @@ -877,7 +891,7 @@ address which can extend beyond that limit. This node is the parent of all individual CPU nodes. It doesn't have any specific requirements, though it's generally good practice - to have at least: + to have at least:: #address-cells = <00000001> #size-cells = <00000000> @@ -887,7 +901,7 @@ address which can extend beyond that limit. that format when reading the "reg" properties of a CPU node, see below - c) The /cpus/* nodes + c) The ``/cpus/*`` nodes So under /cpus, you are supposed to create a node for every CPU on the machine. There is no specific restriction on the name of the @@ -903,21 +917,23 @@ address which can extend beyond that limit. - reg : This is the physical CPU number, it's a single 32-bit cell and is also used as-is as the unit number for constructing the unit name in the full path. For example, with 2 CPUs, you would - have the full path: + have the full path:: + /cpus/PowerPC,970FX@0 /cpus/PowerPC,970FX@1 + (unit addresses do not require leading zeroes) - - d-cache-block-size : one cell, L1 data cache block size in bytes (*) + - d-cache-block-size : one cell, L1 data cache block size in bytes [#]_ - i-cache-block-size : one cell, L1 instruction cache block size in bytes - d-cache-size : one cell, size of L1 data cache in bytes - i-cache-size : one cell, size of L1 instruction cache in bytes -(*) The cache "block" size is the size on which the cache management -instructions operate. Historically, this document used the cache -"line" size here which is incorrect. The kernel will prefer the cache -block size and will fallback to cache line size for backward -compatibility. + .. [#] The cache "block" size is the size on which the cache management + instructions operate. Historically, this document used the cache + "line" size here which is incorrect. The kernel will prefer the cache + block size and will fallback to cache line size for backward + compatibility. Recommended properties: @@ -963,10 +979,10 @@ compatibility. #address-cells and #size-cells of the root node. For example, with both of these properties being 2 like in the example given earlier, a 970 based machine with 6Gb of RAM could typically - have a "reg" property here that looks like: + have a "reg" property here that looks like:: - 00000000 00000000 00000000 80000000 - 00000001 00000000 00000001 00000000 + 00000000 00000000 00000000 80000000 + 00000001 00000000 00000001 00000000 That is a range starting at 0 of 0x80000000 bytes and a range starting at 0x100000000 and of 0x100000000 bytes. You can see @@ -1047,18 +1063,18 @@ compatibility. See 1) above for more details on defining #address-cells. - #size-cells : Size representation for "soc" devices - #interrupt-cells : Defines the width of cells used to represent - interrupts. Typically this value is <2>, which includes a - 32-bit number that represents the interrupt number, and a - 32-bit number that represents the interrupt sense and level. - This field is only needed if the SOC contains an interrupt - controller. + interrupts. Typically this value is <2>, which includes a + 32-bit number that represents the interrupt number, and a + 32-bit number that represents the interrupt sense and level. + This field is only needed if the SOC contains an interrupt + controller. The SOC node may contain child nodes for each SOC device that the platform uses. Nodes should not be created for devices which exist on the SOC but are not used by a particular platform. See chapter VI for more information on how to specify devices that are part of a SOC. - Example SOC node for the MPC8540: + Example SOC node for the MPC8540:: soc8540@e0000000 { #address-cells = <1>; @@ -1079,31 +1095,33 @@ IV - "dtc", the device tree compiler dtc source code can be found at -WARNING: This version is still in early development stage; the -resulting device-tree "blobs" have not yet been validated with the -kernel. The current generated block lacks a useful reserve map (it will -be fixed to generate an empty one, it's up to the bootloader to fill -it up) among others. The error handling needs work, bugs are lurking, -etc... +.. Warning:: + + This version is still in early development stage; the + resulting device-tree "blobs" have not yet been validated with the + kernel. The current generated block lacks a useful reserve map (it will + be fixed to generate an empty one, it's up to the bootloader to fill + it up) among others. The error handling needs work, bugs are lurking, + etc... dtc basically takes a device-tree in a given format and outputs a device-tree in another format. The currently supported formats are: - Input formats: - ------------- +Input formats +------------- - "dtb": "blob" format, that is a flattened device-tree block with - header all in a binary blob. + header all in a binary blob. - "dts": "source" format. This is a text file containing a "source" for a device-tree. The format is defined later in this - chapter. + chapter. - "fs" format. This is a representation equivalent to the - output of /proc/device-tree, that is nodes are directories and - properties are files + output of /proc/device-tree, that is nodes are directories and + properties are files - Output formats: - --------------- +Output formats +-------------- - "dtb": "blob" format - "dts": "source" format @@ -1113,7 +1131,7 @@ device-tree in another format. The currently supported formats are: assembly file exports some symbols that can be used. -The syntax of the dtc tool is +The syntax of the dtc tool is:: dtc [-I ] [-O ] [-o output-filename] [-V output_version] input_filename @@ -1127,43 +1145,45 @@ Additionally, dtc performs various sanity checks on the tree, like the uniqueness of linux, phandle properties, validity of strings, etc... The format of the .dts "source" file is "C" like, supports C and C++ -style comments. +style comments:: -/ { -} + / { + } The above is the "device-tree" definition. It's the only statement supported currently at the toplevel. -/ { - property1 = "string_value"; /* define a property containing a 0 - * terminated string - */ +:: - property2 = <0x1234abcd>; /* define a property containing a - * numerical 32-bit value (hexadecimal) - */ + / { + property1 = "string_value"; /* define a property containing a 0 + * terminated string + */ - property3 = <0x12345678 0x12345678 0xdeadbeef>; - /* define a property containing 3 - * numerical 32-bit values (cells) in - * hexadecimal - */ - property4 = [0x0a 0x0b 0x0c 0x0d 0xde 0xea 0xad 0xbe 0xef]; - /* define a property whose content is - * an arbitrary array of bytes - */ + property2 = <0x1234abcd>; /* define a property containing a + * numerical 32-bit value (hexadecimal) + */ - childnode@address { /* define a child node named "childnode" - * whose unit name is "childnode at - * address" - */ + property3 = <0x12345678 0x12345678 0xdeadbeef>; + /* define a property containing 3 + * numerical 32-bit values (cells) in + * hexadecimal + */ + property4 = [0x0a 0x0b 0x0c 0x0d 0xde 0xea 0xad 0xbe 0xef]; + /* define a property whose content is + * an arbitrary array of bytes + */ - childprop = "hello\n"; /* define a property "childprop" of - * childnode (in this case, a string) - */ - }; -}; + childnode@address { /* define a child node named "childnode" + * whose unit name is "childnode at + * address" + */ + + childprop = "hello\n"; /* define a property "childprop" of + * childnode (in this case, a string) + */ + }; + }; Nodes can contain other nodes etc... thus defining the hierarchical structure of the tree. @@ -1322,7 +1342,7 @@ phandle of the parent node. If the interrupt-parent property is not defined for a node, its interrupt parent is assumed to be an ancestor in the node's -_device tree_ hierarchy. +*device tree* hierarchy. 3) OpenPIC Interrupt Controllers -------------------------------- @@ -1334,10 +1354,12 @@ information. Sense and level information should be encoded as follows: - 0 = low to high edge sensitive type enabled - 1 = active low level sensitive type enabled - 2 = active high level sensitive type enabled - 3 = high to low edge sensitive type enabled + == ======================================== + 0 low to high edge sensitive type enabled + 1 active low level sensitive type enabled + 2 active high level sensitive type enabled + 3 high to low edge sensitive type enabled + == ======================================== 4) ISA Interrupt Controllers ---------------------------- @@ -1350,13 +1372,15 @@ information. ISA PIC interrupt controllers should adhere to the ISA PIC encodings listed below: - 0 = active low level sensitive type enabled - 1 = active high level sensitive type enabled - 2 = high to low edge sensitive type enabled - 3 = low to high edge sensitive type enabled + == ======================================== + 0 active low level sensitive type enabled + 1 active high level sensitive type enabled + 2 high to low edge sensitive type enabled + 3 low to high edge sensitive type enabled + == ======================================== VIII - Specifying Device Power Management Information (sleep property) -=================================================================== +====================================================================== Devices on SOCs often have mechanisms for placing devices into low-power states that are decoupled from the devices' own register blocks. Sometimes, @@ -1387,6 +1411,7 @@ reasonably grouped in this manner, then create a virtual sleep controller sleep-map should wait until its necessity is demonstrated). IX - Specifying dma bus information +=================================== Some devices may have DMA memory range shifted relatively to the beginning of RAM, or even placed outside of kernel RAM. For example, the Keystone 2 SoC @@ -1404,25 +1429,30 @@ coherent DMA operations. The "dma-coherent" property is intended to be used for identifying devices supported coherent DMA operations in DT. * DMA Bus master + Optional property: + - dma-ranges: encoded as arbitrary number of triplets of - (child-bus-address, parent-bus-address, length). Each triplet specified - describes a contiguous DMA address range. - The dma-ranges property is used to describe the direct memory access (DMA) - structure of a memory-mapped bus whose device tree parent can be accessed - from DMA operations originating from the bus. It provides a means of - defining a mapping or translation between the physical address space of - the bus and the physical address space of the parent of the bus. - (for more information see the Devicetree Specification) + (child-bus-address, parent-bus-address, length). Each triplet specified + describes a contiguous DMA address range. + The dma-ranges property is used to describe the direct memory access (DMA) + structure of a memory-mapped bus whose device tree parent can be accessed + from DMA operations originating from the bus. It provides a means of + defining a mapping or translation between the physical address space of + the bus and the physical address space of the parent of the bus. + (for more information see the Devicetree Specification) * DMA Bus child + Optional property: + - dma-ranges: value. if present - It means that DMA addresses - translation has to be enabled for this device. + translation has to be enabled for this device. - dma-coherent: Present if dma operations are coherent -Example: -soc { +Example:: + + soc { compatible = "ti,keystone","simple-bus"; ranges = <0x0 0x0 0x0 0xc0000000>; dma-ranges = <0x80000000 0x8 0x00000000 0x80000000>; @@ -1435,11 +1465,13 @@ soc { [...] dma-coherent; }; -}; + }; Appendix A - Sample SOC node for MPC8540 ======================================== +:: + soc@e0000000 { #address-cells = <1>; #size-cells = <1>; diff --git a/Documentation/devicetree/index.rst b/Documentation/devicetree/index.rst index 54026763916d..d2a96e1af23e 100644 --- a/Documentation/devicetree/index.rst +++ b/Documentation/devicetree/index.rst @@ -15,3 +15,4 @@ Open Firmware and Device Tree overlay-notes bindings/index + booting-without-of diff --git a/Documentation/driver-api/connector.rst b/Documentation/driver-api/connector.rst index c100c7482289..23d068191fb1 100644 --- a/Documentation/driver-api/connector.rst +++ b/Documentation/driver-api/connector.rst @@ -26,7 +26,7 @@ netlink based networking for inter-process communication in a significantly easier way:: int cn_add_callback(struct cb_id *id, char *name, void (*callback) (struct cn_msg *, struct netlink_skb_parms *)); - void cn_netlink_send_multi(struct cn_msg *msg, u16 len, u32 portid, u32 __group, int gfp_mask); + void cn_netlink_send_mult(struct cn_msg *msg, u16 len, u32 portid, u32 __group, int gfp_mask); void cn_netlink_send(struct cn_msg *msg, u32 portid, u32 __group, int gfp_mask); struct cb_id @@ -48,7 +48,8 @@ be dereferenced to `struct cn_msg *`:: __u32 seq; __u32 ack; - __u32 len; /* Length of the following data */ + __u16 len; /* Length of the following data */ + __u16 flags; __u8 data[0]; }; diff --git a/Documentation/driver-api/device-io.rst b/Documentation/driver-api/device-io.rst index 0e389378f71d..764963876d08 100644 --- a/Documentation/driver-api/device-io.rst +++ b/Documentation/driver-api/device-io.rst @@ -36,14 +36,14 @@ are starting with one. Physical addresses are of type unsigned long. This address should not be used directly. Instead, to get an address suitable for passing to the accessor functions described below, you -should call :c:func:`ioremap()`. An address suitable for accessing +should call ioremap(). An address suitable for accessing the device will be returned to you. After you've finished using the device (say, in your module's exit -routine), call :c:func:`iounmap()` in order to return the address +routine), call iounmap() in order to return the address space to the kernel. Most architectures allocate new address space each -time you call :c:func:`ioremap()`, and they can run out unless you -call :c:func:`iounmap()`. +time you call ioremap(), and they can run out unless you +call iounmap(). Accessing the device -------------------- @@ -60,8 +60,8 @@ readb_relaxed(), readw_relaxed(), readl_relaxed(), readq_relaxed(), writeb(), writew(), writel() and writeq(). Some devices (such as framebuffers) would like to use larger transfers than -8 bytes at a time. For these devices, the :c:func:`memcpy_toio()`, -:c:func:`memcpy_fromio()` and :c:func:`memset_io()` functions are +8 bytes at a time. For these devices, the memcpy_toio(), +memcpy_fromio() and memset_io() functions are provided. Do not use memset or memcpy on IO addresses; they are not guaranteed to copy data in order. @@ -135,15 +135,15 @@ Accessing Port Space Accesses to this space are provided through a set of functions which allow 8-bit, 16-bit and 32-bit accesses; also known as byte, word and -long. These functions are :c:func:`inb()`, :c:func:`inw()`, -:c:func:`inl()`, :c:func:`outb()`, :c:func:`outw()` and -:c:func:`outl()`. +long. These functions are inb(), inw(), +inl(), outb(), outw() and +outl(). Some variants are provided for these functions. Some devices require that accesses to their ports are slowed down. This functionality is provided by appending a ``_p`` to the end of the function. -There are also equivalents to memcpy. The :c:func:`ins()` and -:c:func:`outs()` functions copy bytes, words or longs to the given +There are also equivalents to memcpy. The ins() and +outs() functions copy bytes, words or longs to the given port. Public Functions Provided diff --git a/Documentation/driver-api/dmaengine/client.rst b/Documentation/driver-api/dmaengine/client.rst index 2104830a99ae..b0f32cfc38c2 100644 --- a/Documentation/driver-api/dmaengine/client.rst +++ b/Documentation/driver-api/dmaengine/client.rst @@ -5,7 +5,7 @@ DMA Engine API Guide Vinod Koul .. note:: For DMA Engine usage in async_tx please see: - ``Documentation/crypto/async-tx-api.txt`` + ``Documentation/crypto/async-tx-api.rst`` Below is a guide to device driver writers on how to use the Slave-DMA API of the diff --git a/Documentation/driver-api/dmaengine/provider.rst b/Documentation/driver-api/dmaengine/provider.rst index 56e5833e8a07..954422c2b704 100644 --- a/Documentation/driver-api/dmaengine/provider.rst +++ b/Documentation/driver-api/dmaengine/provider.rst @@ -95,7 +95,7 @@ accommodates that API in some cases, and made some design choices to ensure that it stayed compatible. For more information on the Async TX API, please look the relevant -documentation file in Documentation/crypto/async-tx-api.txt. +documentation file in Documentation/crypto/async-tx-api.rst. DMAEngine APIs ============== diff --git a/Documentation/driver-api/driver-model/driver.rst b/Documentation/driver-api/driver-model/driver.rst index 7d5040f6a3d8..06f818b1d622 100644 --- a/Documentation/driver-api/driver-model/driver.rst +++ b/Documentation/driver-api/driver-model/driver.rst @@ -228,8 +228,6 @@ over management of devices from the bootloader, the usage of sync_state() is not restricted to that. Use it whenever it makes sense to take an action after all the consumers of a device have probed:: -:: - int (*remove) (struct device *dev); remove is called to unbind a driver from a device. This may be diff --git a/Documentation/driver-api/early-userspace/early_userspace_support.rst b/Documentation/driver-api/early-userspace/early_userspace_support.rst index 3deefb34046b..8a58c61932ff 100644 --- a/Documentation/driver-api/early-userspace/early_userspace_support.rst +++ b/Documentation/driver-api/early-userspace/early_userspace_support.rst @@ -92,7 +92,7 @@ You can obtain somewhat infrequent snapshots of klibc from https://www.kernel.org/pub/linux/libs/klibc/ For active users, you are better off using the klibc git -repository, at http://git.kernel.org/?p=libs/klibc/klibc.git +repository, at https://git.kernel.org/?p=libs/klibc/klibc.git The standalone klibc distribution currently provides three components, in addition to the klibc library: @@ -122,7 +122,7 @@ and a number of other utilities, so you can replace kinit and build custom initramfs images that meet your needs exactly. For questions and help, you can sign up for the early userspace -mailing list at http://www.zytor.com/mailman/listinfo/klibc +mailing list at https://www.zytor.com/mailman/listinfo/klibc How does it work? ================= diff --git a/Documentation/driver-api/i3c/protocol.rst b/Documentation/driver-api/i3c/protocol.rst index dae3b6d32c6b..02653defa011 100644 --- a/Documentation/driver-api/i3c/protocol.rst +++ b/Documentation/driver-api/i3c/protocol.rst @@ -14,7 +14,7 @@ collisions are prevented, ...) please have a look at the I3C specification. This document is just a brief introduction to the I3C protocol and the concepts it brings to the table. If you need more information, please refer to the MIPI I3C specification (can be downloaded here -http://resources.mipi.org/mipi-i3c-v1-download). +https://resources.mipi.org/mipi-i3c-v1-download). Introduction ============ diff --git a/Documentation/driver-api/index.rst b/Documentation/driver-api/index.rst index 6567187e7687..3eb0085d5e42 100644 --- a/Documentation/driver-api/index.rst +++ b/Documentation/driver-api/index.rst @@ -48,6 +48,7 @@ available subsections can be seen below. scsi libata target + mailbox mtdnand miscellaneous mei/index diff --git a/Documentation/driver-api/ipmi.rst b/Documentation/driver-api/ipmi.rst index 5ef1047e2e66..292f587fccdd 100644 --- a/Documentation/driver-api/ipmi.rst +++ b/Documentation/driver-api/ipmi.rst @@ -18,7 +18,7 @@ management software that can use the IPMI system. This document describes how to use the IPMI driver for Linux. If you are not familiar with IPMI itself, see the web site at -http://www.intel.com/design/servers/ipmi/index.htm. IPMI is a big +https://www.intel.com/design/servers/ipmi/index.htm. IPMI is a big subject and I can't cover it all here! Configuration diff --git a/Documentation/mailbox.txt b/Documentation/driver-api/mailbox.rst similarity index 100% rename from Documentation/mailbox.txt rename to Documentation/driver-api/mailbox.rst diff --git a/Documentation/driver-api/memory-devices/ti-gpmc.rst b/Documentation/driver-api/memory-devices/ti-gpmc.rst index 33efcb81f080..b1bb86871ad7 100644 --- a/Documentation/driver-api/memory-devices/ti-gpmc.rst +++ b/Documentation/driver-api/memory-devices/ti-gpmc.rst @@ -14,7 +14,7 @@ memory devices like * Pseudo-SRAM devices GPMC is found on Texas Instruments SoC's (OMAP based) -IP details: http://www.ti.com/lit/pdf/spruh73 section 7.1 +IP details: https://www.ti.com/lit/pdf/spruh73 section 7.1 GPMC generic timing calculation: diff --git a/Documentation/driver-api/mmc/mmc-tools.rst b/Documentation/driver-api/mmc/mmc-tools.rst index 54406093768b..a231e9644351 100644 --- a/Documentation/driver-api/mmc/mmc-tools.rst +++ b/Documentation/driver-api/mmc/mmc-tools.rst @@ -5,7 +5,7 @@ MMC tools introduction There is one MMC test tools called mmc-utils, which is maintained by Chris Ball, you can find it at the below public git repository: - http://git.kernel.org/cgit/linux/kernel/git/cjb/mmc-utils.git/ + https://git.kernel.org/cgit/linux/kernel/git/cjb/mmc-utils.git/ Functions ========= diff --git a/Documentation/driver-api/ntb.rst b/Documentation/driver-api/ntb.rst index 87d1372da879..11577c2105c5 100644 --- a/Documentation/driver-api/ntb.rst +++ b/Documentation/driver-api/ntb.rst @@ -9,7 +9,7 @@ registers and memory translation windows, as well as non common features like scratchpad and message registers. Scratchpad registers are read-and-writable registers that are accessible from either side of the device, so that peers can exchange a small amount of information at a fixed address. Message registers can -be utilized for the same purpose. Additionally they are provided with with +be utilized for the same purpose. Additionally they are provided with special status bits to make sure the information isn't rewritten by another peer. Doorbell registers provide a way for peers to send interrupt events. Memory windows allow translated read and write access to the peer memory. diff --git a/Documentation/driver-api/nvdimm/nvdimm.rst b/Documentation/driver-api/nvdimm/nvdimm.rst index 79c0fd39f2af..ef6d59e0978e 100644 --- a/Documentation/driver-api/nvdimm/nvdimm.rst +++ b/Documentation/driver-api/nvdimm/nvdimm.rst @@ -73,7 +73,7 @@ DAX: process address space. DSM: - Device Specific Method: ACPI method to to control specific + Device Specific Method: ACPI method to control specific device - in this case the firmware. DCR: @@ -113,13 +113,13 @@ Supporting Documents -------------------- ACPI 6: - http://www.uefi.org/sites/default/files/resources/ACPI_6.0.pdf + https://www.uefi.org/sites/default/files/resources/ACPI_6.0.pdf NVDIMM Namespace: - http://pmem.io/documents/NVDIMM_Namespace_Spec.pdf + https://pmem.io/documents/NVDIMM_Namespace_Spec.pdf DSM Interface Example: - http://pmem.io/documents/NVDIMM_DSM_Interface_Example.pdf + https://pmem.io/documents/NVDIMM_DSM_Interface_Example.pdf Driver Writer's Guide: - http://pmem.io/documents/NVDIMM_Driver_Writers_Guide.pdf + https://pmem.io/documents/NVDIMM_Driver_Writers_Guide.pdf Git Trees --------- @@ -778,7 +778,7 @@ Why the Term "namespace"? 2. The term originated to describe the sub-devices that can be created within a NVME controller (see the nvme specification: - http://www.nvmexpress.org/specifications/), and NFIT namespaces are + https://www.nvmexpress.org/specifications/), and NFIT namespaces are meant to parallel the capabilities and configurability of NVME-namespaces. @@ -786,7 +786,7 @@ Why the Term "namespace"? LIBNVDIMM/LIBNDCTL: Block Translation Table "btt" ------------------------------------------------- -A BTT (design document: http://pmem.io/2014/09/23/btt.html) is a stacked +A BTT (design document: https://pmem.io/2014/09/23/btt.html) is a stacked block device driver that fronts either the whole block device or a partition of a block device emitted by either a PMEM or BLK NAMESPACE. diff --git a/Documentation/driver-api/nvdimm/security.rst b/Documentation/driver-api/nvdimm/security.rst index ad9dea099b34..7aab71524116 100644 --- a/Documentation/driver-api/nvdimm/security.rst +++ b/Documentation/driver-api/nvdimm/security.rst @@ -138,6 +138,6 @@ another encrypted-key. This command is only available when the master security is enabled, indicated by the extended security status. -[1]: http://pmem.io/documents/NVDIMM_DSM_Interface-V1.8.pdf +[1]: https://pmem.io/documents/NVDIMM_DSM_Interface-V1.8.pdf [2]: http://www.t13.org/documents/UploadedDocuments/docs2006/e05179r4-ACS-SecurityClarifications.pdf diff --git a/Documentation/driver-api/rapidio/rapidio.rst b/Documentation/driver-api/rapidio/rapidio.rst index fb8942d3ba85..74c552ad3eb8 100644 --- a/Documentation/driver-api/rapidio/rapidio.rst +++ b/Documentation/driver-api/rapidio/rapidio.rst @@ -356,7 +356,7 @@ NOTE: http://www.rapidio.org/education/technology_comparisons/ [3] RapidIO support for Linux. - http://lwn.net/Articles/139118/ + https://lwn.net/Articles/139118/ [4] Matt Porter. RapidIO for Linux. Ottawa Linux Symposium, 2005 - http://www.kernel.org/doc/ols/2005/ols2005v2-pages-43-56.pdf + https://www.kernel.org/doc/ols/2005/ols2005v2-pages-43-56.pdf diff --git a/Documentation/driver-api/thermal/cpu-idle-cooling.rst b/Documentation/driver-api/thermal/cpu-idle-cooling.rst index b9f34ceb2a38..c2a7ca676853 100644 --- a/Documentation/driver-api/thermal/cpu-idle-cooling.rst +++ b/Documentation/driver-api/thermal/cpu-idle-cooling.rst @@ -1,3 +1,5 @@ +.. SPDX-License-Identifier: GPL-2.0 + ================ CPU Idle Cooling ================ @@ -48,7 +50,7 @@ idle state target residency, we lead to dropping the static and the dynamic leakage for this period (modulo the energy needed to enter this state). So the sustainable power with idle cycles has a linear relation with the OPP’s sustainable power and can be computed with a -coefficient similar to: +coefficient similar to:: Power(IdleCycle) = Coef x Power(OPP) @@ -139,7 +141,7 @@ Power considerations -------------------- When we reach the thermal trip point, we have to sustain a specified -power for a specific temperature but at this time we consume: +power for a specific temperature but at this time we consume:: Power = Capacitance x Voltage^2 x Frequency x Utilisation @@ -148,7 +150,7 @@ wrong in the system setup). The ‘Capacitance’ and ‘Utilisation’ are a fixed value, ‘Voltage’ and the ‘Frequency’ are fixed artificially because we don’t want to change the OPP. We can group the ‘Capacitance’ and the ‘Utilisation’ into a single term which is the -‘Dynamic Power Coefficient (Cdyn)’ Simplifying the above, we have: +‘Dynamic Power Coefficient (Cdyn)’ Simplifying the above, we have:: Pdyn = Cdyn x Voltage^2 x Frequency @@ -157,7 +159,7 @@ in order to target the sustainable power defined in the device tree. So with the idle injection mechanism, we want an average power (Ptarget) resulting in an amount of time running at full power on a specific OPP and idle another amount of time. That could be put in a -equation: +equation:: P(opp)target = ((Trunning x (P(opp)running) + (Tidle x P(opp)idle)) / (Trunning + Tidle) @@ -168,7 +170,7 @@ equation: At this point if we know the running period for the CPU, that gives us the idle injection we need. Alternatively if we have the idle -injection duration, we can compute the running duration with: +injection duration, we can compute the running duration with:: Trunning = Tidle / ((P(opp)running / P(opp)target) - 1) @@ -191,7 +193,7 @@ However, in this demonstration we ignore three aspects: target residency, otherwise we end up consuming more energy and potentially invert the mitigation effect -So the final equation is: +So the final equation is:: Trunning = (Tidle - Twakeup ) x (((P(opp)dyn + P(opp)static ) - P(opp)target) / P(opp)target ) diff --git a/Documentation/driver-api/thermal/nouveau_thermal.rst b/Documentation/driver-api/thermal/nouveau_thermal.rst index 37255fd6735d..79ece266cf6d 100644 --- a/Documentation/driver-api/thermal/nouveau_thermal.rst +++ b/Documentation/driver-api/thermal/nouveau_thermal.rst @@ -93,4 +93,4 @@ Thermal management on Nouveau is new and may not work on all cards. If you have inquiries, please ping mupuf on IRC (#nouveau, freenode). Bug reports should be filled on Freedesktop's bug tracker. Please follow -http://nouveau.freedesktop.org/wiki/Bugs +https://nouveau.freedesktop.org/wiki/Bugs diff --git a/Documentation/driver-api/usb/dma.rst b/Documentation/driver-api/usb/dma.rst index 59d5aee89e37..2b3dbd3265b4 100644 --- a/Documentation/driver-api/usb/dma.rst +++ b/Documentation/driver-api/usb/dma.rst @@ -10,7 +10,7 @@ API overview The big picture is that USB drivers can continue to ignore most DMA issues, though they still must provide DMA-ready buffers (see -``Documentation/DMA-API-HOWTO.txt``). That's how they've worked through +:doc:`/core-api/dma-api-howto`). That's how they've worked through the 2.4 (and earlier) kernels, or they can now be DMA-aware. DMA-aware usb drivers: @@ -60,7 +60,7 @@ and effects like cache-trashing can impose subtle penalties. force a consistent memory access ordering by using memory barriers. It's not using a streaming DMA mapping, so it's good for small transfers on systems where the I/O would otherwise thrash an IOMMU mapping. (See - ``Documentation/DMA-API-HOWTO.txt`` for definitions of "coherent" and + :doc:`/core-api/dma-api-howto` for definitions of "coherent" and "streaming" DMA mappings.) Asking for 1/Nth of a page (as well as asking for N pages) is reasonably @@ -91,7 +91,7 @@ Working with existing buffers Existing buffers aren't usable for DMA without first being mapped into the DMA address space of the device. However, most buffers passed to your driver can safely be used with such DMA mapping. (See the first section -of Documentation/DMA-API-HOWTO.txt, titled "What memory is DMA-able?") +of :doc:`/core-api/dma-api-howto`, titled "What memory is DMA-able?") - When you're using scatterlists, you can map everything at once. On some systems, this kicks in an IOMMU and turns the scatterlists into single diff --git a/Documentation/driver-api/usb/writing_usb_driver.rst b/Documentation/driver-api/usb/writing_usb_driver.rst index 0b3d9ff221bb..2176297e5765 100644 --- a/Documentation/driver-api/usb/writing_usb_driver.rst +++ b/Documentation/driver-api/usb/writing_usb_driver.rst @@ -318,6 +318,6 @@ linux-usb Mailing List Archives: https://lore.kernel.org/linux-usb/ Programming Guide for Linux USB Device Drivers: -http://lmu.web.psi.ch/docu/manuals/software_manuals/linux_sl/usb_linux_programming_guide.pdf +https://lmu.web.psi.ch/docu/manuals/software_manuals/linux_sl/usb_linux_programming_guide.pdf -USB Home Page: http://www.usb.org +USB Home Page: https://www.usb.org diff --git a/Documentation/fb/modedb.rst b/Documentation/fb/modedb.rst index 624d08fd2856..4d2411e32ebb 100644 --- a/Documentation/fb/modedb.rst +++ b/Documentation/fb/modedb.rst @@ -152,7 +152,7 @@ To specify a video mode at bootup, use the following boot options:: video=:x[-][@refresh] where is a name from the table below. Valid default modes can be -found in linux/drivers/video/modedb.c. Check your driver's documentation. +found in drivers/video/fbdev/core/modedb.c. Check your driver's documentation. There may be more modes:: Drivers that support modedb boot options diff --git a/Documentation/features/debug/kcov/arch-support.txt b/Documentation/features/debug/kcov/arch-support.txt new file mode 100644 index 000000000000..ab0ee1c933c2 --- /dev/null +++ b/Documentation/features/debug/kcov/arch-support.txt @@ -0,0 +1,33 @@ +# +# Feature name: kcov +# Kconfig: ARCH_HAS_KCOV +# description: arch supports kcov for coverage-guided fuzzing +# + ----------------------- + | arch |status| + ----------------------- + | alpha: | TODO | + | arc: | TODO | + | arm: | ok | + | arm64: | ok | + | c6x: | TODO | + | csky: | TODO | + | h8300: | TODO | + | hexagon: | TODO | + | ia64: | TODO | + | m68k: | TODO | + | microblaze: | TODO | + | mips: | ok | + | nds32: | TODO | + | nios2: | TODO | + | openrisc: | TODO | + | parisc: | TODO | + | powerpc: | ok | + | riscv: | ok | + | s390: | ok | + | sh: | TODO | + | sparc: | TODO | + | um: | ok | + | x86: | ok | + | xtensa: | TODO | + ----------------------- diff --git a/Documentation/features/debug/kgdb/arch-support.txt b/Documentation/features/debug/kgdb/arch-support.txt index 4b0a1d0d6ba4..bc45bac20442 100644 --- a/Documentation/features/debug/kgdb/arch-support.txt +++ b/Documentation/features/debug/kgdb/arch-support.txt @@ -23,7 +23,7 @@ | openrisc: | TODO | | parisc: | ok | | powerpc: | ok | - | riscv: | TODO | + | riscv: | ok | | s390: | TODO | | sh: | ok | | sparc: | ok | diff --git a/Documentation/features/debug/kmemleak/arch-support.txt b/Documentation/features/debug/kmemleak/arch-support.txt new file mode 100644 index 000000000000..b7e4f3608838 --- /dev/null +++ b/Documentation/features/debug/kmemleak/arch-support.txt @@ -0,0 +1,33 @@ +# +# Feature name: kmemleak +# Kconfig: HAVE_DEBUG_KMEMLEAK +# description: arch supports the kernel memory leak detector +# + ----------------------- + | arch |status| + ----------------------- + | alpha: | TODO | + | arc: | ok | + | arm: | ok | + | arm64: | ok | + | c6x: | TODO | + | csky: | TODO | + | h8300: | TODO | + | hexagon: | TODO | + | ia64: | TODO | + | m68k: | TODO | + | microblaze: | ok | + | mips: | ok | + | nds32: | ok | + | nios2: | TODO | + | openrisc: | TODO | + | parisc: | TODO | + | powerpc: | ok | + | riscv: | TODO | + | s390: | ok | + | sh: | ok | + | sparc: | ok | + | um: | ok | + | x86: | ok | + | xtensa: | ok | + ----------------------- diff --git a/Documentation/filesystems/9p.rst b/Documentation/filesystems/9p.rst index 2995279ddc24..7b5964bc8865 100644 --- a/Documentation/filesystems/9p.rst +++ b/Documentation/filesystems/9p.rst @@ -18,7 +18,7 @@ and Maya Gokhale. Additional development by Greg Watson The best detailed explanation of the Linux implementation and applications of the 9p client is available in the form of a USENIX paper: - http://www.usenix.org/events/usenix05/tech/freenix/hensbergen.html + https://www.usenix.org/events/usenix05/tech/freenix/hensbergen.html Other applications are described in the following papers: diff --git a/Documentation/filesystems/afs.rst b/Documentation/filesystems/afs.rst index cada9464d6bd..0abb155ac666 100644 --- a/Documentation/filesystems/afs.rst +++ b/Documentation/filesystems/afs.rst @@ -190,7 +190,7 @@ Security Secure operations are initiated by acquiring a key using the klog program. A very primitive klog program is available at: - http://people.redhat.com/~dhowells/rxrpc/klog.c + https://people.redhat.com/~dhowells/rxrpc/klog.c This should be compiled by:: diff --git a/Documentation/filesystems/autofs-mount-control.rst b/Documentation/filesystems/autofs-mount-control.rst index 2903aed92316..bf4b511cdbe8 100644 --- a/Documentation/filesystems/autofs-mount-control.rst +++ b/Documentation/filesystems/autofs-mount-control.rst @@ -391,7 +391,7 @@ variation uses the path and optionally in.type field of struct args_ismountpoint set to an autofs mount type. The call returns 1 if this is a mount point and sets out.devid field to the device number of the mount and out.magic field to the relevant super block magic number (described below) or 0 if -it isn't a mountpoint. In both cases the the device number (as returned +it isn't a mountpoint. In both cases the device number (as returned by new_encode_dev()) is returned in out.devid field. If supplied with a file descriptor we're looking for a specific mount, @@ -399,12 +399,12 @@ not necessarily at the top of the mounted stack. In this case the path the descriptor corresponds to is considered a mountpoint if it is itself a mountpoint or contains a mount, such as a multi-mount without a root mount. In this case we return 1 if the descriptor corresponds to a mount -point and and also returns the super magic of the covering mount if there +point and also returns the super magic of the covering mount if there is one or 0 if it isn't a mountpoint. If a path is supplied (and the ioctlfd field is set to -1) then the path is looked up and is checked to see if it is the root of a mount. If a type is also given we are looking for a particular autofs mount and if -a match isn't found a fail is returned. If the the located path is the +a match isn't found a fail is returned. If the located path is the root of a mount 1 is returned along with the super magic of the mount or 0 otherwise. diff --git a/Documentation/filesystems/caching/cachefiles.rst b/Documentation/filesystems/caching/cachefiles.rst index 65d3db476765..e58bc1fd312a 100644 --- a/Documentation/filesystems/caching/cachefiles.rst +++ b/Documentation/filesystems/caching/cachefiles.rst @@ -348,7 +348,7 @@ data cached therein; nor is it permitted to create new files in the cache. There are policy source files available in: - http://people.redhat.com/~dhowells/fscache/cachefilesd-0.8.tar.bz2 + https://people.redhat.com/~dhowells/fscache/cachefilesd-0.8.tar.bz2 and later versions. In that tarball, see the files:: diff --git a/Documentation/filesystems/caching/operations.rst b/Documentation/filesystems/caching/operations.rst index f7ddcc028939..9983e1675447 100644 --- a/Documentation/filesystems/caching/operations.rst +++ b/Documentation/filesystems/caching/operations.rst @@ -27,7 +27,7 @@ data storage and retrieval routines. Its operations are represented by fscache_operation structs, though these are usually embedded into some other structure. -This facility is available to and expected to be be used by the cache backends, +This facility is available to and expected to be used by the cache backends, and FS-Cache will create operations and pass them off to the appropriate cache backend for completion. diff --git a/Documentation/filesystems/coda.rst b/Documentation/filesystems/coda.rst index 84c860c89887..bdde7e4e010b 100644 --- a/Documentation/filesystems/coda.rst +++ b/Documentation/filesystems/coda.rst @@ -524,7 +524,7 @@ kernel support. Description This call is made to determine the ViceFid and filetype of - a directory entry. The directory entry requested carries name name + a directory entry. The directory entry requested carries name 'name' and Venus will search the directory identified by cfs_lookup_in.VFid. The result may indicate that the name does not exist, or that difficulty was encountered in finding it (e.g. due to disconnection). @@ -886,7 +886,7 @@ kernel support. none Description - Remove the directory with name name from the directory + Remove the directory with name 'name' from the directory identified by VFid. .. Note:: The attributes of the parent directory should be returned since diff --git a/Documentation/filesystems/configfs.rst b/Documentation/filesystems/configfs.rst index f8941954c667..1d3d6f4a82a9 100644 --- a/Documentation/filesystems/configfs.rst +++ b/Documentation/filesystems/configfs.rst @@ -226,7 +226,7 @@ filename. configfs_attribute->ca_mode specifies the file permissions. If an attribute is readable and provides a ->show method, that method will be called whenever userspace asks for a read(2) on the attribute. If an attribute is writable and provides a ->store method, that method will be -be called whenever userspace asks for a write(2) on the attribute. +called whenever userspace asks for a write(2) on the attribute. struct configfs_bin_attribute ============================= diff --git a/Documentation/filesystems/directory-locking.rst b/Documentation/filesystems/directory-locking.rst index de12016ee419..504ba940c36c 100644 --- a/Documentation/filesystems/directory-locking.rst +++ b/Documentation/filesystems/directory-locking.rst @@ -28,7 +28,7 @@ RENAME_EXCHANGE in flags argument) lock both. In any case, if the target already exists, lock it. If the source is a non-directory, lock it. If we need to lock both, lock them in inode pointer order. Then call the method. All locks are exclusive. -NB: we might get away with locking the the source (and target in exchange +NB: we might get away with locking the source (and target in exchange case) shared. 5) link creation. Locking rules: @@ -56,7 +56,7 @@ rules: * call the method. All ->i_rwsem are taken exclusive. Again, we might get away with locking -the the source (and target in exchange case) shared. +the source (and target in exchange case) shared. The rules above obviously guarantee that all directories that are going to be read, modified or removed by method will be locked by caller. diff --git a/Documentation/filesystems/f2fs.rst b/Documentation/filesystems/f2fs.rst index 8b4fac44f4e1..a11d329542f9 100644 --- a/Documentation/filesystems/f2fs.rst +++ b/Documentation/filesystems/f2fs.rst @@ -101,171 +101,170 @@ Mount Options ============= -====================== ============================================================ -background_gc=%s Turn on/off cleaning operations, namely garbage - collection, triggered in background when I/O subsystem is - idle. If background_gc=on, it will turn on the garbage - collection and if background_gc=off, garbage collection - will be turned off. If background_gc=sync, it will turn - on synchronous garbage collection running in background. - Default value for this option is on. So garbage - collection is on by default. -disable_roll_forward Disable the roll-forward recovery routine -norecovery Disable the roll-forward recovery routine, mounted read- - only (i.e., -o ro,disable_roll_forward) -discard/nodiscard Enable/disable real-time discard in f2fs, if discard is - enabled, f2fs will issue discard/TRIM commands when a - segment is cleaned. -no_heap Disable heap-style segment allocation which finds free - segments for data from the beginning of main area, while - for node from the end of main area. -nouser_xattr Disable Extended User Attributes. Note: xattr is enabled - by default if CONFIG_F2FS_FS_XATTR is selected. -noacl Disable POSIX Access Control List. Note: acl is enabled - by default if CONFIG_F2FS_FS_POSIX_ACL is selected. -active_logs=%u Support configuring the number of active logs. In the - current design, f2fs supports only 2, 4, and 6 logs. - Default number is 6. -disable_ext_identify Disable the extension list configured by mkfs, so f2fs - does not aware of cold files such as media files. -inline_xattr Enable the inline xattrs feature. -noinline_xattr Disable the inline xattrs feature. -inline_xattr_size=%u Support configuring inline xattr size, it depends on - flexible inline xattr feature. -inline_data Enable the inline data feature: New created small(<~3.4k) - files can be written into inode block. -inline_dentry Enable the inline dir feature: data in new created - directory entries can be written into inode block. The - space of inode block which is used to store inline - dentries is limited to ~3.4k. -noinline_dentry Disable the inline dentry feature. -flush_merge Merge concurrent cache_flush commands as much as possible - to eliminate redundant command issues. If the underlying - device handles the cache_flush command relatively slowly, - recommend to enable this option. -nobarrier This option can be used if underlying storage guarantees - its cached data should be written to the novolatile area. - If this option is set, no cache_flush commands are issued - but f2fs still guarantees the write ordering of all the - data writes. -fastboot This option is used when a system wants to reduce mount - time as much as possible, even though normal performance - can be sacrificed. -extent_cache Enable an extent cache based on rb-tree, it can cache - as many as extent which map between contiguous logical - address and physical address per inode, resulting in - increasing the cache hit ratio. Set by default. -noextent_cache Disable an extent cache based on rb-tree explicitly, see - the above extent_cache mount option. -noinline_data Disable the inline data feature, inline data feature is - enabled by default. -data_flush Enable data flushing before checkpoint in order to - persist data of regular and symlink. -reserve_root=%d Support configuring reserved space which is used for - allocation from a privileged user with specified uid or - gid, unit: 4KB, the default limit is 0.2% of user blocks. -resuid=%d The user ID which may use the reserved blocks. -resgid=%d The group ID which may use the reserved blocks. -fault_injection=%d Enable fault injection in all supported types with - specified injection rate. -fault_type=%d Support configuring fault injection type, should be - enabled with fault_injection option, fault type value - is shown below, it supports single or combined type. +======================== ============================================================ +background_gc=%s Turn on/off cleaning operations, namely garbage + collection, triggered in background when I/O subsystem is + idle. If background_gc=on, it will turn on the garbage + collection and if background_gc=off, garbage collection + will be turned off. If background_gc=sync, it will turn + on synchronous garbage collection running in background. + Default value for this option is on. So garbage + collection is on by default. +disable_roll_forward Disable the roll-forward recovery routine +norecovery Disable the roll-forward recovery routine, mounted read- + only (i.e., -o ro,disable_roll_forward) +discard/nodiscard Enable/disable real-time discard in f2fs, if discard is + enabled, f2fs will issue discard/TRIM commands when a + segment is cleaned. +no_heap Disable heap-style segment allocation which finds free + segments for data from the beginning of main area, while + for node from the end of main area. +nouser_xattr Disable Extended User Attributes. Note: xattr is enabled + by default if CONFIG_F2FS_FS_XATTR is selected. +noacl Disable POSIX Access Control List. Note: acl is enabled + by default if CONFIG_F2FS_FS_POSIX_ACL is selected. +active_logs=%u Support configuring the number of active logs. In the + current design, f2fs supports only 2, 4, and 6 logs. + Default number is 6. +disable_ext_identify Disable the extension list configured by mkfs, so f2fs + does not aware of cold files such as media files. +inline_xattr Enable the inline xattrs feature. +noinline_xattr Disable the inline xattrs feature. +inline_xattr_size=%u Support configuring inline xattr size, it depends on + flexible inline xattr feature. +inline_data Enable the inline data feature: New created small(<~3.4k) + files can be written into inode block. +inline_dentry Enable the inline dir feature: data in new created + directory entries can be written into inode block. The + space of inode block which is used to store inline + dentries is limited to ~3.4k. +noinline_dentry Disable the inline dentry feature. +flush_merge Merge concurrent cache_flush commands as much as possible + to eliminate redundant command issues. If the underlying + device handles the cache_flush command relatively slowly, + recommend to enable this option. +nobarrier This option can be used if underlying storage guarantees + its cached data should be written to the novolatile area. + If this option is set, no cache_flush commands are issued + but f2fs still guarantees the write ordering of all the + data writes. +fastboot This option is used when a system wants to reduce mount + time as much as possible, even though normal performance + can be sacrificed. +extent_cache Enable an extent cache based on rb-tree, it can cache + as many as extent which map between contiguous logical + address and physical address per inode, resulting in + increasing the cache hit ratio. Set by default. +noextent_cache Disable an extent cache based on rb-tree explicitly, see + the above extent_cache mount option. +noinline_data Disable the inline data feature, inline data feature is + enabled by default. +data_flush Enable data flushing before checkpoint in order to + persist data of regular and symlink. +reserve_root=%d Support configuring reserved space which is used for + allocation from a privileged user with specified uid or + gid, unit: 4KB, the default limit is 0.2% of user blocks. +resuid=%d The user ID which may use the reserved blocks. +resgid=%d The group ID which may use the reserved blocks. +fault_injection=%d Enable fault injection in all supported types with + specified injection rate. +fault_type=%d Support configuring fault injection type, should be + enabled with fault_injection option, fault type value + is shown below, it supports single or combined type. - =================== =========== - Type_Name Type_Value - =================== =========== - FAULT_KMALLOC 0x000000001 - FAULT_KVMALLOC 0x000000002 - FAULT_PAGE_ALLOC 0x000000004 - FAULT_PAGE_GET 0x000000008 - FAULT_ALLOC_BIO 0x000000010 - FAULT_ALLOC_NID 0x000000020 - FAULT_ORPHAN 0x000000040 - FAULT_BLOCK 0x000000080 - FAULT_DIR_DEPTH 0x000000100 - FAULT_EVICT_INODE 0x000000200 - FAULT_TRUNCATE 0x000000400 - FAULT_READ_IO 0x000000800 - FAULT_CHECKPOINT 0x000001000 - FAULT_DISCARD 0x000002000 - FAULT_WRITE_IO 0x000004000 - =================== =========== -mode=%s Control block allocation mode which supports "adaptive" - and "lfs". In "lfs" mode, there should be no random - writes towards main area. -io_bits=%u Set the bit size of write IO requests. It should be set - with "mode=lfs". -usrquota Enable plain user disk quota accounting. -grpquota Enable plain group disk quota accounting. -prjquota Enable plain project quota accounting. -usrjquota= Appoint specified file and type during mount, so that quota -grpjquota= information can be properly updated during recovery flow, -prjjquota= : must be in root directory; -jqfmt= : [vfsold,vfsv0,vfsv1]. -offusrjquota Turn off user journelled quota. -offgrpjquota Turn off group journelled quota. -offprjjquota Turn off project journelled quota. -quota Enable plain user disk quota accounting. -noquota Disable all plain disk quota option. -whint_mode=%s Control which write hints are passed down to block - layer. This supports "off", "user-based", and - "fs-based". In "off" mode (default), f2fs does not pass - down hints. In "user-based" mode, f2fs tries to pass - down hints given by users. And in "fs-based" mode, f2fs - passes down hints with its policy. -alloc_mode=%s Adjust block allocation policy, which supports "reuse" - and "default". -fsync_mode=%s Control the policy of fsync. Currently supports "posix", - "strict", and "nobarrier". In "posix" mode, which is - default, fsync will follow POSIX semantics and does a - light operation to improve the filesystem performance. - In "strict" mode, fsync will be heavy and behaves in line - with xfs, ext4 and btrfs, where xfstest generic/342 will - pass, but the performance will regress. "nobarrier" is - based on "posix", but doesn't issue flush command for - non-atomic files likewise "nobarrier" mount option. + =================== =========== + Type_Name Type_Value + =================== =========== + FAULT_KMALLOC 0x000000001 + FAULT_KVMALLOC 0x000000002 + FAULT_PAGE_ALLOC 0x000000004 + FAULT_PAGE_GET 0x000000008 + FAULT_ALLOC_BIO 0x000000010 + FAULT_ALLOC_NID 0x000000020 + FAULT_ORPHAN 0x000000040 + FAULT_BLOCK 0x000000080 + FAULT_DIR_DEPTH 0x000000100 + FAULT_EVICT_INODE 0x000000200 + FAULT_TRUNCATE 0x000000400 + FAULT_READ_IO 0x000000800 + FAULT_CHECKPOINT 0x000001000 + FAULT_DISCARD 0x000002000 + FAULT_WRITE_IO 0x000004000 + =================== =========== +mode=%s Control block allocation mode which supports "adaptive" + and "lfs". In "lfs" mode, there should be no random + writes towards main area. +io_bits=%u Set the bit size of write IO requests. It should be set + with "mode=lfs". +usrquota Enable plain user disk quota accounting. +grpquota Enable plain group disk quota accounting. +prjquota Enable plain project quota accounting. +usrjquota= Appoint specified file and type during mount, so that quota +grpjquota= information can be properly updated during recovery flow, +prjjquota= : must be in root directory; +jqfmt= : [vfsold,vfsv0,vfsv1]. +offusrjquota Turn off user journelled quota. +offgrpjquota Turn off group journelled quota. +offprjjquota Turn off project journelled quota. +quota Enable plain user disk quota accounting. +noquota Disable all plain disk quota option. +whint_mode=%s Control which write hints are passed down to block + layer. This supports "off", "user-based", and + "fs-based". In "off" mode (default), f2fs does not pass + down hints. In "user-based" mode, f2fs tries to pass + down hints given by users. And in "fs-based" mode, f2fs + passes down hints with its policy. +alloc_mode=%s Adjust block allocation policy, which supports "reuse" + and "default". +fsync_mode=%s Control the policy of fsync. Currently supports "posix", + "strict", and "nobarrier". In "posix" mode, which is + default, fsync will follow POSIX semantics and does a + light operation to improve the filesystem performance. + In "strict" mode, fsync will be heavy and behaves in line + with xfs, ext4 and btrfs, where xfstest generic/342 will + pass, but the performance will regress. "nobarrier" is + based on "posix", but doesn't issue flush command for + non-atomic files likewise "nobarrier" mount option. test_dummy_encryption test_dummy_encryption=%s - Enable dummy encryption, which provides a fake fscrypt - context. The fake fscrypt context is used by xfstests. - The argument may be either "v1" or "v2", in order to - select the corresponding fscrypt policy version. -checkpoint=%s[:%u[%]] Set to "disable" to turn off checkpointing. Set to "enable" - to reenable checkpointing. Is enabled by default. While - disabled, any unmounting or unexpected shutdowns will cause - the filesystem contents to appear as they did when the - filesystem was mounted with that option. - While mounting with checkpoint=disabled, the filesystem must - run garbage collection to ensure that all available space can - be used. If this takes too much time, the mount may return - EAGAIN. You may optionally add a value to indicate how much - of the disk you would be willing to temporarily give up to - avoid additional garbage collection. This can be given as a - number of blocks, or as a percent. For instance, mounting - with checkpoint=disable:100% would always succeed, but it may - hide up to all remaining free space. The actual space that - would be unusable can be viewed at /sys/fs/f2fs//unusable - This space is reclaimed once checkpoint=enable. -compress_algorithm=%s Control compress algorithm, currently f2fs supports "lzo", - "lz4", "zstd" and "lzo-rle" algorithm. -compress_log_size=%u Support configuring compress cluster size, the size will - be 4KB * (1 << %u), 16KB is minimum size, also it's - default size. -compress_extension=%s Support adding specified extension, so that f2fs can enable - compression on those corresponding files, e.g. if all files - with '.ext' has high compression rate, we can set the '.ext' - on compression extension list and enable compression on - these file by default rather than to enable it via ioctl. - For other files, we can still enable compression via ioctl. -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. -====================== ============================================================ + Enable dummy encryption, which provides a fake fscrypt + context. The fake fscrypt context is used by xfstests. + The argument may be either "v1" or "v2", in order to + select the corresponding fscrypt policy version. +checkpoint=%s[:%u[%]] Set to "disable" to turn off checkpointing. Set to "enable" + to reenable checkpointing. Is enabled by default. While + disabled, any unmounting or unexpected shutdowns will cause + the filesystem contents to appear as they did when the + filesystem was mounted with that option. + While mounting with checkpoint=disabled, the filesystem must + run garbage collection to ensure that all available space can + be used. If this takes too much time, the mount may return + EAGAIN. You may optionally add a value to indicate how much + of the disk you would be willing to temporarily give up to + avoid additional garbage collection. This can be given as a + number of blocks, or as a percent. For instance, mounting + with checkpoint=disable:100% would always succeed, but it may + hide up to all remaining free space. The actual space that + would be unusable can be viewed at /sys/fs/f2fs//unusable + This space is reclaimed once checkpoint=enable. +compress_algorithm=%s Control compress algorithm, currently f2fs supports "lzo", + "lz4", "zstd" and "lzo-rle" algorithm. +compress_log_size=%u Support configuring compress cluster size, the size will + be 4KB * (1 << %u), 16KB is minimum size, also it's + default size. +compress_extension=%s Support adding specified extension, so that f2fs can enable + compression on those corresponding files, e.g. if all files + with '.ext' has high compression rate, we can set the '.ext' + on compression extension list and enable compression on + these file by default rather than to enable it via ioctl. + For other files, we can still enable compression via ioctl. +inlinecrypt When possible, encrypt/decrypt the contents of encrypted + files using the blk-crypto framework rather than + filesystem-layer encryption. This allows the use of + inline encryption hardware. The on-disk format is + unaffected. For more details, see + Documentation/block/inline-encryption.rst. +======================== ============================================================ Debugfs Entries =============== diff --git a/Documentation/filesystems/fsverity.rst b/Documentation/filesystems/fsverity.rst index a95536b6443c..6c8944f6f0f7 100644 --- a/Documentation/filesystems/fsverity.rst +++ b/Documentation/filesystems/fsverity.rst @@ -659,7 +659,7 @@ weren't already directly answered in other parts of this document. retrofit existing filesystems with new consistency mechanisms. Data journalling is available on ext4, but is very slow. - - Rebuilding the the Merkle tree after every write, which would be + - Rebuilding the Merkle tree after every write, which would be extremely inefficient. Alternatively, a different authenticated dictionary structure such as an "authenticated skiplist" could be used. However, this would be far more complex. diff --git a/Documentation/filesystems/hfs.rst b/Documentation/filesystems/hfs.rst index ab17a005e9b1..776015c80e3f 100644 --- a/Documentation/filesystems/hfs.rst +++ b/Documentation/filesystems/hfs.rst @@ -76,7 +76,7 @@ Creating HFS filesystems The hfsutils package from Robert Leslie contains a program called hformat that can be used to create HFS filesystem. See - for details. + for details. Credits diff --git a/Documentation/filesystems/hpfs.rst b/Documentation/filesystems/hpfs.rst index 0db152278572..7e0dd2f4373e 100644 --- a/Documentation/filesystems/hpfs.rst +++ b/Documentation/filesystems/hpfs.rst @@ -7,7 +7,7 @@ Read/Write HPFS 2.09 1998-2004, Mikulas Patocka :email: mikulas@artax.karlin.mff.cuni.cz -:homepage: http://artax.karlin.mff.cuni.cz/~mikulas/vyplody/hpfs/index-e.cgi +:homepage: https://artax.karlin.mff.cuni.cz/~mikulas/vyplody/hpfs/index-e.cgi Credits ======= diff --git a/Documentation/filesystems/locking.rst b/Documentation/filesystems/locking.rst index 17bea12538c3..64f94a18d97e 100644 --- a/Documentation/filesystems/locking.rst +++ b/Documentation/filesystems/locking.rst @@ -433,15 +433,15 @@ prototypes:: locking rules: -========== ============= ================= ========= +====================== ============= ================= ========= ops inode->i_lock blocked_lock_lock may block -========== ============= ================= ========= +====================== ============= ================= ========= lm_notify: yes yes no lm_grant: no no no lm_break: yes no no lm_change yes no no lm_breaker_owns_lease: no no no -========== ============= ================= ========= +====================== ============= ================= ========= buffer_head =========== @@ -614,9 +614,9 @@ prototypes:: locking rules: -============= ======== =========================== +============= ========= =========================== ops mmap_lock PageLocked(page) -============= ======== =========================== +============= ========= =========================== open: yes close: yes fault: yes can return with page locked @@ -624,7 +624,7 @@ map_pages: yes page_mkwrite: yes can return with page locked pfn_mkwrite: yes access: yes -============= ======== =========================== +============= ========= =========================== ->fault() is called when a previously not present pte is about to be faulted in. The filesystem must find and return the page associated diff --git a/Documentation/filesystems/mount_api.rst b/Documentation/filesystems/mount_api.rst index dea22d64f060..29c169c68961 100644 --- a/Documentation/filesystems/mount_api.rst +++ b/Documentation/filesystems/mount_api.rst @@ -213,7 +213,7 @@ The filesystem context points to a table of operations:: void (*free)(struct fs_context *fc); int (*dup)(struct fs_context *fc, struct fs_context *src_fc); int (*parse_param)(struct fs_context *fc, - struct struct fs_parameter *param); + struct fs_parameter *param); int (*parse_monolithic)(struct fs_context *fc, void *data); int (*get_tree)(struct fs_context *fc); int (*reconfigure)(struct fs_context *fc); @@ -247,7 +247,7 @@ manage the filesystem context. They are as follows: * :: int (*parse_param)(struct fs_context *fc, - struct struct fs_parameter *param); + struct fs_parameter *param); Called when a parameter is being added to the filesystem context. param points to the key name and maybe a value object. VFS-specific options diff --git a/Documentation/filesystems/nfs/rpc-server-gss.rst b/Documentation/filesystems/nfs/rpc-server-gss.rst index 812754576845..abed4a2b1b82 100644 --- a/Documentation/filesystems/nfs/rpc-server-gss.rst +++ b/Documentation/filesystems/nfs/rpc-server-gss.rst @@ -10,12 +10,12 @@ purposes of authentication.) RPCGSS is specified in a few IETF documents: - - RFC2203 v1: http://tools.ietf.org/rfc/rfc2203.txt - - RFC5403 v2: http://tools.ietf.org/rfc/rfc5403.txt + - RFC2203 v1: https://tools.ietf.org/rfc/rfc2203.txt + - RFC5403 v2: https://tools.ietf.org/rfc/rfc5403.txt and there is a 3rd version being proposed: - - http://tools.ietf.org/id/draft-williams-rpcsecgssv3.txt + - https://tools.ietf.org/id/draft-williams-rpcsecgssv3.txt (At draft n. 02 at the time of writing) Background diff --git a/Documentation/filesystems/omfs.rst b/Documentation/filesystems/omfs.rst index 4c8bb3074169..a104c25b7a2f 100644 --- a/Documentation/filesystems/omfs.rst +++ b/Documentation/filesystems/omfs.rst @@ -24,7 +24,7 @@ More information is available at: Various utilities, including mkomfs and omfsck, are included with omfsprogs, available at: - http://bobcopeland.com/karma/ + https://bobcopeland.com/karma/ Instructions are included in its README. diff --git a/Documentation/filesystems/overlayfs.rst b/Documentation/filesystems/overlayfs.rst index fcda5d6ba9ac..8ea83a51c266 100644 --- a/Documentation/filesystems/overlayfs.rst +++ b/Documentation/filesystems/overlayfs.rst @@ -328,7 +328,7 @@ the time of copy (on-demand vs. up-front). Multiple lower layers --------------------- -Multiple lower layers can now be given using the the colon (":") as a +Multiple lower layers can now be given using the colon (":") as a separator character between the directory names. For example: mount -t overlay overlay -olowerdir=/lower1:/lower2:/lower3 /merged diff --git a/Documentation/filesystems/path-lookup.rst b/Documentation/filesystems/path-lookup.rst index f46b05e9b96c..c482e1619e77 100644 --- a/Documentation/filesystems/path-lookup.rst +++ b/Documentation/filesystems/path-lookup.rst @@ -43,15 +43,15 @@ characters, and "components" that are sequences of one or more non-"``/``" characters. These form two kinds of paths. Those that start with slashes are "absolute" and start from the filesystem root. The others are "relative" and start from the current directory, or -from some other location specified by a file descriptor given to a -"``XXXat``" system call such as `openat() `_. +from some other location specified by a file descriptor given to +"``*at()``" system calls such as `openat() `_. .. _execveat: http://man7.org/linux/man-pages/man2/execveat.2.html It is tempting to describe the second kind as starting with a component, but that isn't always accurate: a pathname can lack both slashes and components, it can be empty, in other words. This is -generally forbidden in POSIX, but some of those "xxx``at``" system calls +generally forbidden in POSIX, but some of those "``*at()``" system calls in Linux permit it when the ``AT_EMPTY_PATH`` flag is given. For example, if you have an open file descriptor on an executable file you can execute it by calling `execveat() `_ passing @@ -69,17 +69,17 @@ pathname that is just slashes have a final component. If it does exist, it could be "``.``" or "``..``" which are handled quite differently from other components. -.. _POSIX: http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap04.html#tag_04_12 +.. _POSIX: https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap04.html#tag_04_12 If a pathname ends with a slash, such as "``/tmp/foo/``" it might be tempting to consider that to have an empty final component. In many ways that would lead to correct results, but not always. In particular, ``mkdir()`` and ``rmdir()`` each create or remove a directory named by the final component, and they are required to work with pathnames -ending in "``/``". According to POSIX_ +ending in "``/``". According to POSIX_: - A pathname that contains at least one non- <slash> character and - that ends with one or more trailing <slash> characters shall not + A pathname that contains at least one non- character and + that ends with one or more trailing characters shall not be resolved successfully unless the last pathname component before the trailing characters names an existing directory or a directory entry that is to be created for a directory immediately @@ -229,7 +229,7 @@ happened to be looking at a dentry that was moved in this way, it might end up continuing the search down the wrong chain, and so miss out on part of the correct chain. -The name-lookup process (``d_lookup()``) does _not_ try to prevent this +The name-lookup process (``d_lookup()``) does *not* try to prevent this from happening, but only to detect when it happens. ``rename_lock`` is a seqlock that is updated whenever any dentry is renamed. If ``d_lookup`` finds that a rename happened while it @@ -376,7 +376,7 @@ table, and the mount point hash table. Bringing it together with ``struct nameidata`` ---------------------------------------------- -.. _First edition Unix: http://minnie.tuhs.org/cgi-bin/utree.pl?file=V1/u2.s +.. _First edition Unix: https://minnie.tuhs.org/cgi-bin/utree.pl?file=V1/u2.s Throughout the process of walking a path, the current status is stored in a ``struct nameidata``, "namei" being the traditional name - dating @@ -398,7 +398,7 @@ held. ``struct qstr last`` ~~~~~~~~~~~~~~~~~~~~ -This is a string together with a length (i.e. _not_ ``nul`` terminated) +This is a string together with a length (i.e. *not* ``nul`` terminated) that is the "next" component in the pathname. ``int last_type`` @@ -655,8 +655,8 @@ This pattern of "try RCU-walk, if that fails try REF-walk" can be clearly seen in functions like ``filename_lookup()``, ``filename_parentat()``, ``filename_mountpoint()``, ``do_filp_open()``, and ``do_file_open_root()``. These five -correspond roughly to the four ``path_``* functions we met earlier, -each of which calls ``link_path_walk()``. The ``path_*`` functions are +correspond roughly to the four ``path_*()`` functions we met earlier, +each of which calls ``link_path_walk()``. The ``path_*()`` functions are called using different mode flags until a mode is found which works. They are first called with ``LOOKUP_RCU`` set to request "RCU-walk". If that fails with the error ``ECHILD`` they are called again with no @@ -720,7 +720,7 @@ against a dentry. The length and name pointer are copied into local variables, then ``read_seqcount_retry()`` is called to confirm the two are consistent, and only then is ``->d_compare()`` called. When standard filename comparison is used, ``dentry_cmp()`` is called -instead. Notably it does _not_ use ``read_seqcount_retry()``, but +instead. Notably it does *not* use ``read_seqcount_retry()``, but instead has a large comment explaining why the consistency guarantee isn't necessary. A subsequent ``read_seqcount_retry()`` will be sufficient to catch any problem that could occur at this point. @@ -928,7 +928,7 @@ if anything goes wrong it is much safer to just abort and try a more sedate approach. The emphasis here is "try quickly and check". It should probably be -"try quickly _and carefully,_ then check". The fact that checking is +"try quickly *and carefully*, then check". The fact that checking is needed is a reminder that the system is dynamic and only a limited number of things are safe at all. The most likely cause of errors in this whole process is assuming something is safe when in reality it @@ -1265,7 +1265,7 @@ Symlinks are different it seems. Both reading a symlink (with ``readlink()``) and looking up a symlink on the way to some other destination can update the atime on that symlink. -.. _clearest statement: http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap04.html#tag_04_08 +.. _clearest statement: https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap04.html#tag_04_08 It is not clear why this is the case; POSIX has little to say on the subject. The `clearest statement`_ is that, if a particular implementation @@ -1365,7 +1365,7 @@ as well as blocking ".." if it would jump outside the starting point. resolution of "..". Magic-links are also blocked. ``LOOKUP_IN_ROOT`` resolves all path components as though the starting point -were the filesystem root. ``nd_jump_root()`` brings the resolution back to to +were the filesystem root. ``nd_jump_root()`` brings the resolution back to the starting point, and ".." at the starting point will act as a no-op. As with ``LOOKUP_BENEATH``, ``rename_lock`` and ``mount_lock`` are used to detect attacks against ".." resolution. Magic-links are also blocked. diff --git a/Documentation/filesystems/proc.rst b/Documentation/filesystems/proc.rst index 996f3cfe7030..e024a9efffd8 100644 --- a/Documentation/filesystems/proc.rst +++ b/Documentation/filesystems/proc.rst @@ -123,10 +123,10 @@ show you how you can use /proc/sys to change settings. The directory /proc contains (among other things) one subdirectory for each process running on the system, which is named after the process ID (PID). -The link self points to the process reading the file system. Each process +The link 'self' points to the process reading the file system. Each process subdirectory has the entries listed in Table 1-1. -Note that an open a file descriptor to /proc/ or to any of its +Note that an open file descriptor to /proc/ or to any of its contained files or subdirectories does not prevent being reused for some other process in the event that exits. Operations on open /proc/ file descriptors corresponding to dead processes @@ -220,7 +220,7 @@ file /proc/PID/status. It fields are described in table 1-2. The statm file contains more detailed information about the process memory usage. Its seven fields are explained in Table 1-3. The stat file -contains details information about the process itself. Its fields are +contains detailed information about the process itself. Its fields are explained in Table 1-4. (for SMP CONFIG users) @@ -545,7 +545,7 @@ encoded manner. The codes are the following: hg huge page advise flag nh no huge page advise flag mg mergable advise flag - bt - arm64 BTI guarded page + bt arm64 BTI guarded page == ======================================= Note that there is no guarantee that every flag and associated mnemonic will @@ -782,7 +782,7 @@ SPU For this case the APIC will generate the interrupt with a IRQ vector of 0xff. This might also be generated by chipset bugs. -RES, CAL, TLB] +RES, CAL, TLB rescheduling, call and TLB flush interrupts are sent from one CPU to another per the needs of the OS. Typically, their statistics are used by kernel developers and interested users to @@ -794,7 +794,7 @@ suppressed when the system is a uniprocessor. As of this writing, only i386 and x86_64 platforms support the new IRQ vector displays. Of some interest is the introduction of the /proc/irq directory to 2.4. -It could be used to set IRQ to CPU affinity, this means that you can "hook" an +It could be used to set IRQ to CPU affinity. This means that you can "hook" an IRQ to only one CPU, or to exclude a CPU of handling IRQs. The contents of the irq subdir is one subdir for each IRQ, and two files; default_smp_affinity and prof_cpu_mask. @@ -808,7 +808,7 @@ For example:: smp_affinity smp_affinity is a bitmask, in which you can specify which CPUs can handle the -IRQ, you can set it by doing:: +IRQ. You can set it by doing:: > echo 1 > /proc/irq/10/smp_affinity @@ -821,7 +821,7 @@ The contents of each smp_affinity file is the same by default:: ffffffff There is an alternate interface, smp_affinity_list which allows specifying -a cpu range instead of a bitmask:: +a CPU range instead of a bitmask:: > cat /proc/irq/0/smp_affinity_list 1024-1031 @@ -835,7 +835,7 @@ reports itself as being attached. This hardware locality information does not include information about any possible driver locality preference. prof_cpu_mask specifies which CPUs are to be profiled by the system wide -profiler. Default value is ffffffff (all cpus if there are only 32 of them). +profiler. Default value is ffffffff (all CPUs if there are only 32 of them). The way IRQs are routed is handled by the IO-APIC, and it's Round Robin between all the CPUs which are allowed to handle it. As usual the kernel has @@ -897,7 +897,7 @@ pagetypeinfo:: Fragmentation avoidance in the kernel works by grouping pages of different migrate types into the same contiguous regions of memory called page blocks. -A page block is typically the size of the default hugepage size e.g. 2MB on +A page block is typically the size of the default hugepage size, e.g. 2MB on X86-64. By keeping pages grouped based on their ability to move, the kernel can reclaim pages within a page block to satisfy a high-order allocation. @@ -965,7 +965,7 @@ varies by architecture and compile options. The following is from a ShmemPmdMapped: 0 kB MemTotal - Total usable ram (i.e. physical ram minus a few reserved + Total usable RAM (i.e. physical RAM minus a few reserved bits and the kernel binary code) MemFree The sum of LowFree+HighFree @@ -996,7 +996,7 @@ Inactive Memory which has been less recently used. It is more eligible to be reclaimed for other purposes HighTotal, HighFree - Highmem is all memory above ~860MB of physical memory + Highmem is all memory above ~860MB of physical memory. Highmem areas are for use by userspace programs, or for the pagecache. The kernel must use tricks to access this memory, making it slower to access than lowmem. @@ -1078,7 +1078,7 @@ Committed_AS using 1G. This 1G is memory which has been "committed" to by the VM and can be used at any time by the allocating application. With strict overcommit enabled on the system - (mode 2 in 'vm.overcommit_memory'),allocations which would + (mode 2 in 'vm.overcommit_memory'), allocations which would exceed the CommitLimit (detailed above) will not be permitted. This is useful if one needs to guarantee that processes will not fail due to lack of memory once that memory has been @@ -1099,7 +1099,7 @@ vmallocinfo Provides information about vmalloced/vmaped areas. One line per area, containing the virtual address range of the area, size in bytes, caller information of the creator, and optional information depending -on the kind of area : +on the kind of area: ========== =================================================== pages=nr number of pages @@ -1144,21 +1144,21 @@ on the kind of area : softirqs ~~~~~~~~ -Provides counts of softirq handlers serviced since boot time, for each cpu. +Provides counts of softirq handlers serviced since boot time, for each CPU. :: > cat /proc/softirqs - CPU0 CPU1 CPU2 CPU3 + CPU0 CPU1 CPU2 CPU3 HI: 0 0 0 0 - TIMER: 27166 27120 27097 27034 + TIMER: 27166 27120 27097 27034 NET_TX: 0 0 0 17 NET_RX: 42 0 0 39 - BLOCK: 0 0 107 1121 - TASKLET: 0 0 0 290 - SCHED: 27035 26983 26971 26746 - HRTIMER: 0 0 0 0 - RCU: 1678 1769 2178 2250 + BLOCK: 0 0 107 1121 + TASKLET: 0 0 0 290 + SCHED: 27035 26983 26971 26746 + HRTIMER: 0 0 0 0 + RCU: 1678 1769 2178 2250 1.3 IDE devices in /proc/ide @@ -1169,7 +1169,7 @@ the kernel is aware. There is one subdirectory for each IDE controller, the file drivers and a link for each IDE device, pointing to the device directory in the controller specific subtree. -The file drivers contains general information about the drivers used for the +The file 'drivers' contains general information about the drivers used for the IDE devices:: > cat /proc/ide/drivers @@ -1409,7 +1409,7 @@ These directories contain the four files shown in Table 1-10. ------------------------- Information about the available and actually used tty's can be found in the -directory /proc/tty.You'll find entries for drivers and line disciplines in +directory /proc/tty. You'll find entries for drivers and line disciplines in this directory, as shown in Table 1-11. @@ -1471,9 +1471,9 @@ second). The meanings of the columns are as follows, from left to right: - iowait: In a word, iowait stands for waiting for I/O to complete. But there are several problems: - 1. Cpu will not wait for I/O to complete, iowait is the time that a task is - waiting for I/O to complete. When cpu goes into idle state for - outstanding task io, another task will be scheduled on this CPU. + 1. CPU will not wait for I/O to complete, iowait is the time that a task is + waiting for I/O to complete. When CPU goes into idle state for + outstanding task I/O, another task will be scheduled on this CPU. 2. In a multi-core CPU, the task waiting for I/O to complete is not running on any CPU, so the iowait of each CPU is difficult to calculate. 3. The value of iowait field in /proc/stat will decrease in certain @@ -1529,8 +1529,8 @@ in Table 1-12, below. mb_groups details of multiblock allocator buddy cache of free blocks ============== ========================================================== -2.0 /proc/consoles ------------------- +1.10 /proc/consoles +------------------- Shows registered system console lines. To see which character device lines are currently used for the system console @@ -1590,10 +1590,9 @@ production system. Set up a development machine and test to make sure that everything works the way you want it to. You may have no alternative but to reboot the machine once an error has been made. -To change a value, simply echo the new value into the file. An example is -given below in the section on the file system data. You need to be root to do -this. You can create your own boot script to perform this every time your -system boots. +To change a value, simply echo the new value into the file. +You need to be root to do this. You can create your own boot script +to perform this every time your system boots. The files in /proc/sys can be used to fine tune and monitor miscellaneous and general things in the operation of the Linux kernel. Since some of the files @@ -1624,8 +1623,8 @@ Chapter 3: Per-process Parameters 3.1 /proc//oom_adj & /proc//oom_score_adj- Adjust the oom-killer score -------------------------------------------------------------------------------- -These file can be used to adjust the badness heuristic used to select which -process gets killed in out of memory conditions. +These files can be used to adjust the badness heuristic used to select which +process gets killed in out of memory (oom) conditions. The badness heuristic assigns a value to each candidate task ranging from 0 (never kill) to 1000 (always kill) to determine which process is targeted. The @@ -1681,7 +1680,7 @@ minimal amount of work. 3.2 /proc//oom_score - Display current oom-killer score ------------------------------------------------------------- -This file can be used to check the current score used by the oom-killer is for +This file can be used to check the current score used by the oom-killer for any given . Use it together with /proc//oom_score_adj to tune which process should be killed in an out-of-memory situation. @@ -1689,7 +1688,7 @@ process should be killed in an out-of-memory situation. 3.3 /proc//io - Display the IO accounting fields ------------------------------------------------------- -This file contains IO statistics for each running process +This file contains IO statistics for each running process. Example ~~~~~~~ @@ -1720,7 +1719,7 @@ The number of bytes which this task has caused to be read from storage. This is simply the sum of bytes which this process passed to read() and pread(). It includes things like tty IO and it is unaffected by whether or not actual physical disk IO was required (the read might have been satisfied from -pagecache) +pagecache). wchar @@ -1878,7 +1877,7 @@ For more information on mount propagation see: 3.6 /proc//comm & /proc//task//comm -------------------------------------------------------- -These files provide a method to access a tasks comm value. It also allows for +These files provide a method to access a task's comm value. It also allows for a task to set its own or one of its thread siblings comm value. The comm value is limited in size compared to the cmdline value, so writing anything longer then the kernel's TASK_COMM_LEN (currently 16 chars) will result in a truncated @@ -1891,21 +1890,21 @@ This file provides a fast way to retrieve first level children pids of a task pointed by / pair. The format is a space separated stream of pids. -Note the "first level" here -- if a child has own children they will -not be listed here, one needs to read /proc//task//children +Note the "first level" here -- if a child has its own children they will +not be listed here; one needs to read /proc//task//children to obtain the descendants. Since this interface is intended to be fast and cheap it doesn't guarantee to provide precise results and some children might be skipped, especially if they've exited right after we printed their -pids, so one need to either stop or freeze processes being inspected +pids, so one needs to either stop or freeze processes being inspected if precise results are needed. 3.8 /proc//fdinfo/ - Information about opened file --------------------------------------------------------------- This file provides information associated with an opened file. The regular -files have at least three fields -- 'pos', 'flags' and mnt_id. The 'pos' +files have at least three fields -- 'pos', 'flags' and 'mnt_id'. The 'pos' represents the current offset of the opened file in decimal form [see lseek(2) for details], 'flags' denotes the octal O_xxx mask the file has been created with [see open(2) for details] and 'mnt_id' represents mount ID of @@ -1976,7 +1975,7 @@ For inotify files the format is the following:: flags: 02000000 inotify wd:3 ino:9e7e sdev:800013 mask:800afce ignored_mask:0 fhandle-bytes:8 fhandle-type:1 f_handle:7e9e0000640d1b6d -where 'wd' is a watch descriptor in decimal form, ie a target file +where 'wd' is a watch descriptor in decimal form, i.e. a target file descriptor number, 'ino' and 'sdev' are inode and device where the target file resides and the 'mask' is the mask of events, all in hex form [see inotify(7) for more details]. @@ -2003,10 +2002,10 @@ For fanotify files the format is:: where fanotify 'flags' and 'event-flags' are values used in fanotify_init call, 'mnt_id' is the mount point identifier, 'mflags' is the value of flags associated with mark which are tracked separately from events -mask. 'ino', 'sdev' are target inode and device, 'mask' is the events +mask. 'ino' and 'sdev' are target inode and device, 'mask' is the events mask and 'ignored_mask' is the mask of events which are to be ignored. -All in hex format. Incorporation of 'mflags', 'mask' and 'ignored_mask' -does provide information about flags and mask used in fanotify_mark +All are in hex format. Incorporation of 'mflags', 'mask' and 'ignored_mask' +provide information about flags and mask used in fanotify_mark call [see fsnotify manpage for details]. While the first three lines are mandatory and always printed, the rest is @@ -2029,7 +2028,7 @@ Timerfd files where 'clockid' is the clock type and 'ticks' is the number of the timer expirations that have occurred [see timerfd_create(2) for details]. 'settime flags' are flags in octal form been used to setup the timer [see timerfd_settime(2) for -details]. 'it_value' is remaining time until the timer exiration. +details]. 'it_value' is remaining time until the timer expiration. 'it_interval' is the interval for the timer. Note the timer might be set up with TIMER_ABSTIME option which will be shown in 'settime flags', but 'it_value' still exhibits timer's remaining time. @@ -2059,13 +2058,13 @@ are actually shared. 3.10 /proc//timerslack_ns - Task timerslack value --------------------------------------------------------- This file provides the value of the task's timerslack value in nanoseconds. -This value specifies a amount of time that normal timers may be deferred +This value specifies an amount of time that normal timers may be deferred in order to coalesce timers and avoid unnecessary wakeups. -This allows a task's interactivity vs power consumption trade off to be +This allows a task's interactivity vs power consumption tradeoff to be adjusted. -Writing 0 to the file will set the tasks timerslack to the default value. +Writing 0 to the file will set the task's timerslack to the default value. Valid values are from 0 - ULLONG_MAX @@ -2105,10 +2104,10 @@ Example Description ~~~~~~~~~~~ -x86 specific entries: +x86 specific entries ~~~~~~~~~~~~~~~~~~~~~ -AVX512_elapsed_ms: +AVX512_elapsed_ms ^^^^^^^^^^^^^^^^^^ If AVX512 is supported on the machine, this entry shows the milliseconds @@ -2134,8 +2133,8 @@ AVX512_elapsed_ms: the task is unlikely an AVX512 user, but depends on the workload and the scheduling scenario, it also could be a false negative mentioned above. -Configuring procfs ------------------- +Chapter 4: Configuring procfs +============================= 4.1 Mount options --------------------- @@ -2178,47 +2177,45 @@ information about processes information, just add identd to this group. subset=pid hides all top level files and directories in the procfs that are not related to tasks. -5 Filesystem behavior ----------------------------- +Chapter 5: Filesystem behavior +============================== Originally, before the advent of pid namepsace, procfs was a global file system. It means that there was only one procfs instance in the system. When pid namespace was added, a separate procfs instance was mounted in each pid namespace. So, procfs mount options are global among all -mountpoints within the same namespace. +mountpoints within the same namespace:: -:: + # grep ^proc /proc/mounts + proc /proc proc rw,relatime,hidepid=2 0 0 -# grep ^proc /proc/mounts -proc /proc proc rw,relatime,hidepid=2 0 0 + # strace -e mount mount -o hidepid=1 -t proc proc /tmp/proc + mount("proc", "/tmp/proc", "proc", 0, "hidepid=1") = 0 + +++ exited with 0 +++ -# strace -e mount mount -o hidepid=1 -t proc proc /tmp/proc -mount("proc", "/tmp/proc", "proc", 0, "hidepid=1") = 0 -+++ exited with 0 +++ - -# grep ^proc /proc/mounts -proc /proc proc rw,relatime,hidepid=2 0 0 -proc /tmp/proc proc rw,relatime,hidepid=2 0 0 + # grep ^proc /proc/mounts + proc /proc proc rw,relatime,hidepid=2 0 0 + proc /tmp/proc proc rw,relatime,hidepid=2 0 0 and only after remounting procfs mount options will change at all -mountpoints. +mountpoints:: -# mount -o remount,hidepid=1 -t proc proc /tmp/proc + # mount -o remount,hidepid=1 -t proc proc /tmp/proc -# grep ^proc /proc/mounts -proc /proc proc rw,relatime,hidepid=1 0 0 -proc /tmp/proc proc rw,relatime,hidepid=1 0 0 + # grep ^proc /proc/mounts + proc /proc proc rw,relatime,hidepid=1 0 0 + proc /tmp/proc proc rw,relatime,hidepid=1 0 0 This behavior is different from the behavior of other filesystems. The new procfs behavior is more like other filesystems. Each procfs mount creates a new procfs instance. Mount options affect own procfs instance. It means that it became possible to have several procfs instances -displaying tasks with different filtering options in one pid namespace. +displaying tasks with different filtering options in one pid namespace:: -# mount -o hidepid=invisible -t proc proc /proc -# mount -o hidepid=noaccess -t proc proc /tmp/proc -# grep ^proc /proc/mounts -proc /proc proc rw,relatime,hidepid=invisible 0 0 -proc /tmp/proc proc rw,relatime,hidepid=noaccess 0 0 + # mount -o hidepid=invisible -t proc proc /proc + # mount -o hidepid=noaccess -t proc proc /tmp/proc + # grep ^proc /proc/mounts + proc /proc proc rw,relatime,hidepid=invisible 0 0 + proc /tmp/proc proc rw,relatime,hidepid=noaccess 0 0 diff --git a/Documentation/filesystems/ramfs-rootfs-initramfs.rst b/Documentation/filesystems/ramfs-rootfs-initramfs.rst index 3fddacc6bf14..4598b0d90b60 100644 --- a/Documentation/filesystems/ramfs-rootfs-initramfs.rst +++ b/Documentation/filesystems/ramfs-rootfs-initramfs.rst @@ -246,15 +246,15 @@ If you don't already understand what shared libraries, devices, and paths you need to get a minimal root filesystem up and running, here are some references: -- http://www.tldp.org/HOWTO/Bootdisk-HOWTO/ -- http://www.tldp.org/HOWTO/From-PowerUp-To-Bash-Prompt-HOWTO.html +- https://www.tldp.org/HOWTO/Bootdisk-HOWTO/ +- https://www.tldp.org/HOWTO/From-PowerUp-To-Bash-Prompt-HOWTO.html - http://www.linuxfromscratch.org/lfs/view/stable/ -The "klibc" package (http://www.kernel.org/pub/linux/libs/klibc) is +The "klibc" package (https://www.kernel.org/pub/linux/libs/klibc) is designed to be a tiny C library to statically link early userspace code against, along with some related utilities. It is BSD licensed. -I use uClibc (http://www.uclibc.org) and busybox (http://www.busybox.net) +I use uClibc (https://www.uclibc.org) and busybox (https://www.busybox.net) myself. These are LGPL and GPL, respectively. (A self-contained initramfs package is planned for the busybox 1.3 release.) diff --git a/Documentation/filesystems/sysfs-pci.rst b/Documentation/filesystems/sysfs-pci.rst index a265f3e2cc80..742fbd21dc1f 100644 --- a/Documentation/filesystems/sysfs-pci.rst +++ b/Documentation/filesystems/sysfs-pci.rst @@ -63,7 +63,7 @@ files, each with their own function. binary - file contains binary data cpumask - file contains a cpumask type -.. [1] rw for RESOURCE_IO (I/O port) regions only +.. [1] rw for IORESOURCE_IO (I/O port) regions only The read only files are informational, writes to them will be ignored, with the exception of the 'rom' file. Writable files can be used to perform diff --git a/Documentation/filesystems/sysfs-tagging.rst b/Documentation/filesystems/sysfs-tagging.rst index 8888a05c398e..83647e10c207 100644 --- a/Documentation/filesystems/sysfs-tagging.rst +++ b/Documentation/filesystems/sysfs-tagging.rst @@ -15,7 +15,7 @@ To avoid that problem and allow existing applications in network namespaces to see the same interface that is currently presented in sysfs, sysfs now has tagging directory support. -By using the network namespace pointers as tags to separate out the +By using the network namespace pointers as tags to separate out the sysfs directory entries we ensure that we don't have conflicts in the directories and applications only see a limited set of the network devices. diff --git a/Documentation/filesystems/ubifs-authentication.rst b/Documentation/filesystems/ubifs-authentication.rst index 16efd729bf7c..1f39c8cea702 100644 --- a/Documentation/filesystems/ubifs-authentication.rst +++ b/Documentation/filesystems/ubifs-authentication.rst @@ -433,9 +433,9 @@ will then have to be provided beforehand in the normal way. References ========== -[CRYPTSETUP2] http://www.saout.de/pipermail/dm-crypt/2017-November/005745.html +[CRYPTSETUP2] https://www.saout.de/pipermail/dm-crypt/2017-November/005745.html -[DMC-CBC-ATTACK] http://www.jakoblell.com/blog/2013/12/22/practical-malleability-attack-against-cbc-encrypted-luks-partitions/ +[DMC-CBC-ATTACK] https://www.jakoblell.com/blog/2013/12/22/practical-malleability-attack-against-cbc-encrypted-luks-partitions/ [DM-INTEGRITY] https://www.kernel.org/doc/Documentation/device-mapper/dm-integrity.rst diff --git a/Documentation/filesystems/vfs.rst b/Documentation/filesystems/vfs.rst index ed17771c212b..ca52c82e5bb5 100644 --- a/Documentation/filesystems/vfs.rst +++ b/Documentation/filesystems/vfs.rst @@ -392,7 +392,7 @@ Extended attributes are name:value pairs. ``set`` Called by the VFS to set the value of a particular extended attribute. When the new value is NULL, called to remove a - particular extended attribute. This method is called by the the + particular extended attribute. This method is called by the setxattr(2) and removexattr(2) system calls. When none of the xattr handlers of a filesystem match the specified @@ -652,7 +652,7 @@ at any point after PG_Dirty is clear. Once it is known to be safe, PG_Writeback is cleared. Writeback makes use of a writeback_control structure to direct the -operations. This gives the the writepage and writepages operations some +operations. This gives the writepage and writepages operations some information about the nature of and reason for the writeback request, and the constraints under which it is being done. It is also used to return information back to the caller about the result of a writepage or @@ -766,9 +766,9 @@ cache in your filesystem. The following members are defined: ``writepages`` called by the VM to write out pages associated with the - address_space object. If wbc->sync_mode is WBC_SYNC_ALL, then + address_space object. If wbc->sync_mode is WB_SYNC_ALL, then the writeback_control will specify a range of pages that must be - written out. If it is WBC_SYNC_NONE, then a nr_to_write is + written out. If it is WB_SYNC_NONE, then a nr_to_write is given and that many pages should be written if possible. If no ->writepages is given, then mpage_writepages is used instead. This will choose pages from the address space that are tagged as @@ -1116,7 +1116,7 @@ otherwise noted. before any bytes were remapped. The remap_flags parameter accepts REMAP_FILE_* flags. If REMAP_FILE_DEDUP is set then the implementation must only remap if the requested file ranges have - identical contents. If REMAP_CAN_SHORTEN is set, the caller is + identical contents. If REMAP_FILE_CAN_SHORTEN is set, the caller is ok with the implementation shortening the request length to satisfy alignment or EOF requirements (or any other reason). @@ -1431,13 +1431,13 @@ Resources version.) Creating Linux virtual filesystems. 2002 - + The Linux Virtual File-system Layer by Neil Brown. 1999 A tour of the Linux VFS by Michael K. Johnson. 1996 - + A small trail through the Linux kernel by Andries Brouwer. 2001 - + diff --git a/Documentation/fpga/dfl.rst b/Documentation/fpga/dfl.rst index 978c4af416a4..cae96aa15671 100644 --- a/Documentation/fpga/dfl.rst +++ b/Documentation/fpga/dfl.rst @@ -8,7 +8,7 @@ Authors: - Xiao Guangrong - Wu Hao -The Device Feature List (DFL) FPGA framework (and drivers according to this +The Device Feature List (DFL) FPGA framework (and drivers according to this framework) hides the very details of low layer hardwares and provides unified interfaces to userspace. Applications could use these interfaces to configure, enumerate, open and access FPGA accelerators on platforms which diff --git a/Documentation/gpu/drm-mm.rst b/Documentation/gpu/drm-mm.rst index 1839762044be..49d321eb7964 100644 --- a/Documentation/gpu/drm-mm.rst +++ b/Documentation/gpu/drm-mm.rst @@ -314,7 +314,7 @@ To use drm_gem_cma_get_unmapped_area(), drivers must fill the struct a pointer on drm_gem_cma_get_unmapped_area(). More detailed information about get_unmapped_area can be found in -Documentation/nommu-mmap.txt +Documentation/admin-guide/mm/nommu-mmap.rst Memory Coherency ---------------- diff --git a/Documentation/gpu/drm-uapi.rst b/Documentation/gpu/drm-uapi.rst index 56fec6ed1ad8..496d8fcd4da0 100644 --- a/Documentation/gpu/drm-uapi.rst +++ b/Documentation/gpu/drm-uapi.rst @@ -195,7 +195,7 @@ ENOSPC: EPERM/EACCES: Returned for an operation that is valid, but needs more privileges. E.g. root-only or much more common, DRM master-only operations return - this when when called by unpriviledged clients. There's no clear + this when called by unpriviledged clients. There's no clear difference between EACCES and EPERM. ENODEV: diff --git a/Documentation/gpu/komeda-kms.rst b/Documentation/gpu/komeda-kms.rst index b08da1cffecc..eb693c857e2d 100644 --- a/Documentation/gpu/komeda-kms.rst +++ b/Documentation/gpu/komeda-kms.rst @@ -41,7 +41,7 @@ Compositor blends multiple layers or pixel data flows into one single display frame. its output frame can be fed into post image processor for showing it on the monitor or fed into wb_layer and written to memory at the same time. user can also insert a scaler between compositor and wb_layer to down scale -the display frame first and and then write to memory. +the display frame first and then write to memory. Writeback Layer (wb_layer) -------------------------- diff --git a/Documentation/hid/hiddev.rst b/Documentation/hid/hiddev.rst index 209e6ba4e019..9b28a97c03e6 100644 --- a/Documentation/hid/hiddev.rst +++ b/Documentation/hid/hiddev.rst @@ -65,7 +65,7 @@ The HIDDEV API ============== This description should be read in conjunction with the HID -specification, freely available from http://www.usb.org, and +specification, freely available from https://www.usb.org, and conveniently linked of http://www.linux-usb.org. The hiddev API uses a read() interface, and a set of ioctl() calls. diff --git a/Documentation/hid/intel-ish-hid.rst b/Documentation/hid/intel-ish-hid.rst index cccbf4be17d7..d4785cf6eefd 100644 --- a/Documentation/hid/intel-ish-hid.rst +++ b/Documentation/hid/intel-ish-hid.rst @@ -235,7 +235,7 @@ There can be multiple sensor clients and clients for calibration function. To ease in implantation and allow independent driver handle each client this transport layer takes advantage of Linux Bus driver model. Each -client is registered as device on the the transport bus (ishtp bus). +client is registered as device on the transport bus (ishtp bus). Enumeration sequence of messages: diff --git a/Documentation/i2c/upgrading-clients.rst b/Documentation/i2c/upgrading-clients.rst index 27d29032c138..1708090d7b8f 100644 --- a/Documentation/i2c/upgrading-clients.rst +++ b/Documentation/i2c/upgrading-clients.rst @@ -8,7 +8,7 @@ Introduction ------------ This guide outlines how to alter existing Linux 2.6 client drivers from -the old to the new new binding methods. +the old to the new binding methods. Example old-style driver diff --git a/Documentation/ia64/efirtc.rst b/Documentation/ia64/efirtc.rst index 2f7ff5026308..fd8328408301 100644 --- a/Documentation/ia64/efirtc.rst +++ b/Documentation/ia64/efirtc.rst @@ -113,7 +113,7 @@ We have added 2 new ioctl()s that are specific to the EFI driver: Read the current state of the alarm:: - ioctl(d, RTC_WKLAM_RD, &wkt) + ioctl(d, RTC_WKALM_RD, &wkt) Set the alarm or change its status:: diff --git a/Documentation/index.rst b/Documentation/index.rst index 71eca3171574..57719744774c 100644 --- a/Documentation/index.rst +++ b/Documentation/index.rst @@ -182,6 +182,20 @@ subprojects. filesystems/ext4/index +Other documentation +------------------- + +There are several unsorted documents that don't seem to fit on other parts +of the documentation body, or may require some adjustments and/or conversion +to ReStructured Text format, or are simply too old. + +.. toctree:: + :maxdepth: 2 + + staging/index + watch_queue + + Translations ------------ diff --git a/Documentation/kbuild/kconfig-language.rst b/Documentation/kbuild/kconfig-language.rst index a1601ec3317b..39881b719782 100644 --- a/Documentation/kbuild/kconfig-language.rst +++ b/Documentation/kbuild/kconfig-language.rst @@ -681,7 +681,7 @@ translate Kconfig logic into boolean formulas and run a SAT solver on this to find dead code / features (always inactive), 114 dead features were found in Linux using this methodology [1]_ (Section 8: Threats to validity). -Confirming this could prove useful as Kconfig stands as one of the the leading +Confirming this could prove useful as Kconfig stands as one of the leading industrial variability modeling languages [1]_ [2]_. Its study would help evaluate practical uses of such languages, their use was only theoretical and real world requirements were not well understood. As it stands though diff --git a/Documentation/leds/ledtrig-transient.rst b/Documentation/leds/ledtrig-transient.rst index d921dc830cd0..eedfa1626e8a 100644 --- a/Documentation/leds/ledtrig-transient.rst +++ b/Documentation/leds/ledtrig-transient.rst @@ -157,7 +157,7 @@ repeat the following step as needed:: echo 1 > activate - start timer = duration to run once echo none > trigger -This trigger is intended to be used for for the following example use cases: +This trigger is intended to be used for the following example use cases: - Control of vibrate (phones, tablets etc.) hardware by user space app. - Use of LED by user space app as activity indicator. diff --git a/Documentation/locking/mutex-design.rst b/Documentation/locking/mutex-design.rst index 8f3e9a5141f9..78540cd7f54b 100644 --- a/Documentation/locking/mutex-design.rst +++ b/Documentation/locking/mutex-design.rst @@ -28,7 +28,7 @@ and implemented in kernel/locking/mutex.c. These locks use an atomic variable (->owner) to keep track of the lock state during its lifetime. Field owner actually contains `struct task_struct *` to the current lock owner and it is therefore NULL if not currently owned. Since task_struct pointers are aligned -at at least L1_CACHE_BYTES, low bits (3) are used to store extra state (e.g., +to at least L1_CACHE_BYTES, low bits (3) are used to store extra state (e.g., if waiter list is non-empty). In its most basic form it also includes a wait-queue and a spinlock that serializes access to it. Furthermore, CONFIG_MUTEX_SPIN_ON_OWNER=y systems use a spinner MCS lock (->osq), described diff --git a/Documentation/locking/ww-mutex-design.rst b/Documentation/locking/ww-mutex-design.rst index 1846c199da23..54d9c17bb66b 100644 --- a/Documentation/locking/ww-mutex-design.rst +++ b/Documentation/locking/ww-mutex-design.rst @@ -49,7 +49,7 @@ However, the Wound-Wait algorithm is typically stated to generate fewer backoffs compared to Wait-Die, but is, on the other hand, associated with more work than Wait-Die when recovering from a backoff. Wound-Wait is also a preemptive algorithm in that transactions are wounded by other transactions, and that -requires a reliable way to pick up up the wounded condition and preempt the +requires a reliable way to pick up the wounded condition and preempt the running transaction. Note that this is not the same as process preemption. A Wound-Wait transaction is considered preempted when it dies (returning -EDEADLK) following a wound. diff --git a/Documentation/maintainer/maintainer-entry-profile.rst b/Documentation/maintainer/maintainer-entry-profile.rst index 77e43c8b24b4..227f427118e8 100644 --- a/Documentation/maintainer/maintainer-entry-profile.rst +++ b/Documentation/maintainer/maintainer-entry-profile.rst @@ -31,7 +31,7 @@ Example questions to consider: - What branch should contributors submit against? - Links to any other Maintainer Entry Profiles? For example a device-driver may point to an entry for its parent subsystem. This makes - the contributor aware of obligations a maintainer may have have for + the contributor aware of obligations a maintainer may have for other maintainers in the submission chain. diff --git a/Documentation/mips/ingenic-tcu.rst b/Documentation/mips/ingenic-tcu.rst index 2b75760619b4..2ce4cb1314dc 100644 --- a/Documentation/mips/ingenic-tcu.rst +++ b/Documentation/mips/ingenic-tcu.rst @@ -5,7 +5,7 @@ Ingenic JZ47xx SoCs Timer/Counter Unit hardware =============================================== The Timer/Counter Unit (TCU) in Ingenic JZ47xx SoCs is a multi-function -hardware block. It features up to to eight channels, that can be used as +hardware block. It features up to eight channels, that can be used as counters, timers, or PWM. - JZ4725B, JZ4750, JZ4755 only have six TCU channels. The other SoCs all diff --git a/Documentation/misc-devices/ad525x_dpot.txt b/Documentation/misc-devices/ad525x_dpot.rst similarity index 85% rename from Documentation/misc-devices/ad525x_dpot.txt rename to Documentation/misc-devices/ad525x_dpot.rst index 0c9413b1cbf3..6483ec254520 100644 --- a/Documentation/misc-devices/ad525x_dpot.txt +++ b/Documentation/misc-devices/ad525x_dpot.rst @@ -1,6 +1,8 @@ ---------------------------------- - AD525x Digital Potentiometers ---------------------------------- +.. SPDX-License-Identifier: GPL-2.0 + +============================= +AD525x Digital Potentiometers +============================= The ad525x_dpot driver exports a simple sysfs interface. This allows you to work with the immediate resistance settings as well as update the saved startup @@ -8,9 +10,8 @@ settings. Access to the factory programmed tolerance is also provided, but interpretation of this settings is required by the end application according to the specific part in use. ---------- - Files ---------- +Files +===== Each dpot device will have a set of eeprom, rdac, and tolerance files. How many depends on the actual part you have, as will the range of allowed values. @@ -24,23 +25,22 @@ and may vary greatly on a part-by-part basis. For exact interpretation of this field, please consult the datasheet for your part. This is presented as a hex file for easier parsing. ------------ - Example ------------ +Example +======= Locate the device in your sysfs tree. This is probably easiest by going into -the common i2c directory and locating the device by the i2c slave address. +the common i2c directory and locating the device by the i2c slave address:: # ls /sys/bus/i2c/devices/ 0-0022 0-0027 0-002f So assuming the device in question is on the first i2c bus and has the slave -address of 0x2f, we descend (unrelated sysfs entries have been trimmed). +address of 0x2f, we descend (unrelated sysfs entries have been trimmed):: # ls /sys/bus/i2c/devices/0-002f/ eeprom0 rdac0 tolerance0 -You can use simple reads/writes to access these files: +You can use simple reads/writes to access these files:: # cd /sys/bus/i2c/devices/0-002f/ diff --git a/Documentation/misc-devices/apds990x.txt b/Documentation/misc-devices/apds990x.rst similarity index 86% rename from Documentation/misc-devices/apds990x.txt rename to Documentation/misc-devices/apds990x.rst index 454d95d623b3..e2f75577f731 100644 --- a/Documentation/misc-devices/apds990x.txt +++ b/Documentation/misc-devices/apds990x.rst @@ -1,3 +1,6 @@ +.. SPDX-License-Identifier: GPL-2.0 + +====================== Kernel driver apds990x ====================== @@ -50,14 +53,18 @@ chip_id power_state RW - enable / disable chip. Uses counting logic + 1 enables the chip 0 disables the chip lux0_input RO - measured lux value + sysfs_notify called when threshold interrupt occurs lux0_sensor_range - RO - lux0_input max value. Actually never reaches since sensor tends + RO - lux0_input max value. + + Actually never reaches since sensor tends to saturate much before that. Real max value varies depending on the light spectrum etc. @@ -68,7 +75,9 @@ lux0_rate_avail RO - supported measurement rates lux0_calibscale - RW - calibration value. Set to neutral value by default. + RW - calibration value. + + Set to neutral value by default. Output results are multiplied with calibscale / calibscale_default value. @@ -76,16 +85,21 @@ lux0_calibscale_default RO - neutral calibration value lux0_thresh_above_value - RW - HI level threshold value. All results above the value + RW - HI level threshold value. + + All results above the value trigs an interrupt. 65535 (i.e. sensor_range) disables the above interrupt. lux0_thresh_below_value - RW - LO level threshold value. All results below the value + RW - LO level threshold value. + + All results below the value trigs an interrupt. 0 disables the below interrupt. prox0_raw RO - measured proximity value + sysfs_notify called when threshold interrupt occurs prox0_sensor_range @@ -93,11 +107,14 @@ prox0_sensor_range prox0_raw_en RW - enable / disable proximity - uses counting logic - 1 enables the proximity - 0 disables the proximity + + - 1 enables the proximity + - 0 disables the proximity prox0_reporting_mode - RW - trigger / periodic. In "trigger" mode the driver tells two possible + RW - trigger / periodic. + + In "trigger" mode the driver tells two possible values: 0 or prox0_sensor_range value. 0 means no proximity, 1023 means proximity. This causes minimal number of interrupts. In "periodic" mode the driver reports all values above diff --git a/Documentation/misc-devices/bh1770glc.txt b/Documentation/misc-devices/bh1770glc.rst similarity index 83% rename from Documentation/misc-devices/bh1770glc.txt rename to Documentation/misc-devices/bh1770glc.rst index 7d64c014dc70..ea5ca58bb958 100644 --- a/Documentation/misc-devices/bh1770glc.txt +++ b/Documentation/misc-devices/bh1770glc.rst @@ -1,9 +1,13 @@ +.. SPDX-License-Identifier: GPL-2.0 + +======================= Kernel driver bh1770glc ======================= Supported chips: -ROHM BH1770GLC -OSRAM SFH7770 + +- ROHM BH1770GLC +- OSRAM SFH7770 Data sheet: Not freely available @@ -48,12 +52,16 @@ chip_id RO - shows detected chip type and version power_state - RW - enable / disable chip. Uses counting logic - 1 enables the chip - 0 disables the chip + RW - enable / disable chip + + Uses counting logic + + - 1 enables the chip + - 0 disables the chip lux0_input RO - measured lux value + sysfs_notify called when threshold interrupt occurs lux0_sensor_range @@ -66,16 +74,22 @@ lux0_rate_avail RO - supported measurement rates lux0_thresh_above_value - RW - HI level threshold value. All results above the value + RW - HI level threshold value + + All results above the value trigs an interrupt. 65535 (i.e. sensor_range) disables the above interrupt. lux0_thresh_below_value - RW - LO level threshold value. All results below the value + RW - LO level threshold value + + All results below the value trigs an interrupt. 0 disables the below interrupt. lux0_calibscale - RW - calibration value. Set to neutral value by default. + RW - calibration value + + Set to neutral value by default. Output results are multiplied with calibscale / calibscale_default value. @@ -84,32 +98,37 @@ lux0_calibscale_default prox0_raw RO - measured proximity value + sysfs_notify called when threshold interrupt occurs prox0_sensor_range RO - prox0_raw max value prox0_raw_en - RW - enable / disable proximity - uses counting logic - 1 enables the proximity - 0 disables the proximity + RW - enable / disable proximity + + Uses counting logic + + - 1 enables the proximity + - 0 disables the proximity prox0_thresh_above_count RW - number of proximity interrupts needed before triggering the event prox0_rate_above RW - Measurement rate (in Hz) when the level is above threshold - i.e. when proximity on has been reported. + i.e. when proximity on has been reported. prox0_rate_below RW - Measurement rate (in Hz) when the level is below threshold - i.e. when proximity off has been reported. + i.e. when proximity off has been reported. prox0_rate_avail RO - Supported proximity measurement rates in Hz prox0_thresh_above0_value RW - threshold level which trigs proximity events. + Filtered by persistence filter (prox0_thresh_above_count) prox0_thresh_above1_value diff --git a/Documentation/misc-devices/c2port.txt b/Documentation/misc-devices/c2port.rst similarity index 61% rename from Documentation/misc-devices/c2port.txt rename to Documentation/misc-devices/c2port.rst index 31351b1a5a1f..7e4f6a79418a 100644 --- a/Documentation/misc-devices/c2port.txt +++ b/Documentation/misc-devices/c2port.rst @@ -1,5 +1,9 @@ - C2 port support - --------------- +.. SPDX-License-Identifier: GPL-2.0 +.. include:: + +=============== +C2 port support +=============== (C) Copyright 2007 Rodolfo Giometti @@ -32,10 +36,10 @@ The C2 Interface main references are at (https://www.silabs.com) Silicon Laboratories site], see: - AN127: FLASH Programming via the C2 Interface at -https://www.silabs.com/Support Documents/TechnicalDocs/an127.pdf + https://www.silabs.com/Support Documents/TechnicalDocs/an127.pdf - C2 Specification at -https://www.silabs.com/pages/DownloadDoc.aspx?FILEURL=Support%20Documents/TechnicalDocs/an127.pdf&src=SearchResults + https://www.silabs.com/pages/DownloadDoc.aspx?FILEURL=Support%20Documents/TechnicalDocs/an127.pdf&src=SearchResults however it implements a two wire serial communication protocol (bit banging) designed to enable in-system programming, debugging, and @@ -47,44 +51,44 @@ Using the driver ---------------- Once the driver is loaded you can use sysfs support to get C2port's -info or read/write in-system flash. +info or read/write in-system flash:: -# ls /sys/class/c2port/c2port0/ -access flash_block_size flash_erase rev_id -dev_id flash_blocks_num flash_size subsystem/ -flash_access flash_data reset uevent + # ls /sys/class/c2port/c2port0/ + access flash_block_size flash_erase rev_id + dev_id flash_blocks_num flash_size subsystem/ + flash_access flash_data reset uevent Initially the C2port access is disabled since you hardware may have such lines multiplexed with other devices so, to get access to the -C2port, you need the command: +C2port, you need the command:: -# echo 1 > /sys/class/c2port/c2port0/access + # echo 1 > /sys/class/c2port/c2port0/access after that you should read the device ID and revision ID of the -connected micro controller: +connected micro controller:: -# cat /sys/class/c2port/c2port0/dev_id -8 -# cat /sys/class/c2port/c2port0/rev_id -1 + # cat /sys/class/c2port/c2port0/dev_id + 8 + # cat /sys/class/c2port/c2port0/rev_id + 1 However, for security reasons, the in-system flash access in not -enabled yet, to do so you need the command: +enabled yet, to do so you need the command:: -# echo 1 > /sys/class/c2port/c2port0/flash_access + # echo 1 > /sys/class/c2port/c2port0/flash_access -After that you can read the whole flash: +After that you can read the whole flash:: -# cat /sys/class/c2port/c2port0/flash_data > image + # cat /sys/class/c2port/c2port0/flash_data > image -erase it: +erase it:: -# echo 1 > /sys/class/c2port/c2port0/flash_erase + # echo 1 > /sys/class/c2port/c2port0/flash_erase -and write it: +and write it:: -# cat image > /sys/class/c2port/c2port0/flash_data + # cat image > /sys/class/c2port/c2port0/flash_data -after writing you have to reset the device to execute the new code: +after writing you have to reset the device to execute the new code:: -# echo 1 > /sys/class/c2port/c2port0/reset + # echo 1 > /sys/class/c2port/c2port0/reset diff --git a/Documentation/misc-devices/index.rst b/Documentation/misc-devices/index.rst index 1ecc05fbe6f4..46072ce3d7ef 100644 --- a/Documentation/misc-devices/index.rst +++ b/Documentation/misc-devices/index.rst @@ -14,12 +14,18 @@ fit into other categories. .. toctree:: :maxdepth: 2 + ad525x_dpot + apds990x + bh1770glc eeprom + c2port ibmvmc ics932s401 isl29003 lis3lv02d max6875 mic/index + pci-endpoint-test + spear-pcie-gadget uacce xilinx_sdfec diff --git a/Documentation/misc-devices/pci-endpoint-test.rst b/Documentation/misc-devices/pci-endpoint-test.rst new file mode 100644 index 000000000000..4cf3f4433be7 --- /dev/null +++ b/Documentation/misc-devices/pci-endpoint-test.rst @@ -0,0 +1,56 @@ +.. SPDX-License-Identifier: GPL-2.0 + +===================================== +Driver for PCI Endpoint Test Function +===================================== + +This driver should be used as a host side driver if the root complex is +connected to a configurable PCI endpoint running ``pci_epf_test`` function +driver configured according to [1]_. + +The "pci_endpoint_test" driver can be used to perform the following tests. + +The PCI driver for the test device performs the following tests: + + #) verifying addresses programmed in BAR + #) raise legacy IRQ + #) raise MSI IRQ + #) raise MSI-X IRQ + #) read data + #) write data + #) copy data + +This misc driver creates /dev/pci-endpoint-test. for every +``pci_epf_test`` function connected to the root complex and "ioctls" +should be used to perform the above tests. + +ioctl +----- + + PCITEST_BAR: + Tests the BAR. The number of the BAR to be tested + should be passed as argument. + PCITEST_LEGACY_IRQ: + Tests legacy IRQ + PCITEST_MSI: + Tests message signalled interrupts. The MSI number + to be tested should be passed as argument. + PCITEST_MSIX: + Tests message signalled interrupts. The MSI-X number + to be tested should be passed as argument. + PCITEST_SET_IRQTYPE: + Changes driver IRQ type configuration. The IRQ type + should be passed as argument (0: Legacy, 1:MSI, 2:MSI-X). + PCITEST_GET_IRQTYPE: + Gets driver IRQ type configuration. + PCITEST_WRITE: + Perform write tests. The size of the buffer should be passed + as argument. + PCITEST_READ: + Perform read tests. The size of the buffer should be passed + as argument. + PCITEST_COPY: + Perform read tests. The size of the buffer should be passed + as argument. + +.. [1] Documentation/PCI/endpoint/function/binding/pci-test.rst diff --git a/Documentation/misc-devices/pci-endpoint-test.txt b/Documentation/misc-devices/pci-endpoint-test.txt deleted file mode 100644 index 58ccca4416b1..000000000000 --- a/Documentation/misc-devices/pci-endpoint-test.txt +++ /dev/null @@ -1,41 +0,0 @@ -Driver for PCI Endpoint Test Function - -This driver should be used as a host side driver if the root complex is -connected to a configurable PCI endpoint running *pci_epf_test* function -driver configured according to [1]. - -The "pci_endpoint_test" driver can be used to perform the following tests. - -The PCI driver for the test device performs the following tests - *) verifying addresses programmed in BAR - *) raise legacy IRQ - *) raise MSI IRQ - *) raise MSI-X IRQ - *) read data - *) write data - *) copy data - -This misc driver creates /dev/pci-endpoint-test. for every -*pci_epf_test* function connected to the root complex and "ioctls" -should be used to perform the above tests. - -ioctl ------ - PCITEST_BAR: Tests the BAR. The number of the BAR to be tested - should be passed as argument. - PCITEST_LEGACY_IRQ: Tests legacy IRQ - PCITEST_MSI: Tests message signalled interrupts. The MSI number - to be tested should be passed as argument. - PCITEST_MSIX: Tests message signalled interrupts. The MSI-X number - to be tested should be passed as argument. - PCITEST_SET_IRQTYPE: Changes driver IRQ type configuration. The IRQ type - should be passed as argument (0: Legacy, 1:MSI, 2:MSI-X). - PCITEST_GET_IRQTYPE: Gets driver IRQ type configuration. - PCITEST_WRITE: Perform write tests. The size of the buffer should be passed - as argument. - PCITEST_READ: Perform read tests. The size of the buffer should be passed - as argument. - PCITEST_COPY: Perform read tests. The size of the buffer should be passed - as argument. - -[1] -> Documentation/PCI/endpoint/function/binding/pci-test.txt diff --git a/Documentation/misc-devices/spear-pcie-gadget.rst b/Documentation/misc-devices/spear-pcie-gadget.rst new file mode 100644 index 000000000000..09b9d6c7ac15 --- /dev/null +++ b/Documentation/misc-devices/spear-pcie-gadget.rst @@ -0,0 +1,170 @@ +.. SPDX-License-Identifier: GPL-2.0 + +======================== +Spear PCIe Gadget Driver +======================== + +Author +====== +Pratyush Anand (pratyush.anand@gmail.com) + +Location +======== +driver/misc/spear13xx_pcie_gadget.c + +Supported Chip: +=============== +SPEAr1300 +SPEAr1310 + +Menuconfig option: +================== +Device Drivers + Misc devices + PCIe gadget support for SPEAr13XX platform + +purpose +======= +This driver has several nodes which can be read/written by configfs interface. +Its main purpose is to configure selected dual mode PCIe controller as device +and then program its various registers to configure it as a particular device +type. This driver can be used to show spear's PCIe device capability. + +Description of different nodes: +=============================== + +read behavior of nodes: +----------------------- + +=============== ============================================================== +link gives ltssm status. +int_type type of supported interrupt +no_of_msi zero if MSI is not enabled by host. A positive value is the + number of MSI vector granted. +vendor_id returns programmed vendor id (hex) +device_id returns programmed device id(hex) +bar0_size: returns size of bar0 in hex. +bar0_address returns address of bar0 mapped area in hex. +bar0_rw_offset returns offset of bar0 for which bar0_data will return value. +bar0_data returns data at bar0_rw_offset. +=============== ============================================================== + +write behavior of nodes: +------------------------ + +=============== ================================================================ +link write UP to enable ltsmm DOWN to disable +int_type write interrupt type to be configured and (int_type could be + INTA, MSI or NO_INT). Select MSI only when you have programmed + no_of_msi node. +no_of_msi number of MSI vector needed. +inta write 1 to assert INTA and 0 to de-assert. +send_msi write MSI vector to be sent. +vendor_id write vendor id(hex) to be programmed. +device_id write device id(hex) to be programmed. +bar0_size write size of bar0 in hex. default bar0 size is 1000 (hex) + bytes. +bar0_address write address of bar0 mapped area in hex. (default mapping of + bar0 is SYSRAM1(E0800000). Always program bar size before bar + address. Kernel might modify bar size and address for alignment, + so read back bar size and address after writing to cross check. +bar0_rw_offset write offset of bar0 for which bar0_data will write value. +bar0_data write data to be written at bar0_rw_offset. +=============== ================================================================ + +Node programming example +======================== + +Program all PCIe registers in such a way that when this device is connected +to the PCIe host, then host sees this device as 1MB RAM. + +:: + + #mount -t configfs none /Config + +For nth PCIe Device Controller:: + + # cd /config/pcie_gadget.n/ + +Now you have all the nodes in this directory. +program vendor id as 0x104a:: + + # echo 104A >> vendor_id + +program device id as 0xCD80:: + + # echo CD80 >> device_id + +program BAR0 size as 1MB:: + + # echo 100000 >> bar0_size + +check for programmed bar0 size:: + + # cat bar0_size + +Program BAR0 Address as DDR (0x2100000). This is the physical address of +memory, which is to be made visible to PCIe host. Similarly any other peripheral +can also be made visible to PCIe host. E.g., if you program base address of UART +as BAR0 address then when this device will be connected to a host, it will be +visible as UART. + +:: + + # echo 2100000 >> bar0_address + +program interrupt type : INTA:: + + # echo INTA >> int_type + +go for link up now:: + + # echo UP >> link + +It will have to be insured that, once link up is done on gadget, then only host +is initialized and start to search PCIe devices on its port. + +:: + + /*wait till link is up*/ + # cat link + +Wait till it returns UP. + +To assert INTA:: + + # echo 1 >> inta + +To de-assert INTA:: + + # echo 0 >> inta + +if MSI is to be used as interrupt, program no of msi vector needed (say4):: + + # echo 4 >> no_of_msi + +select MSI as interrupt type:: + + # echo MSI >> int_type + +go for link up now:: + + # echo UP >> link + +wait till link is up:: + + # cat link + +An application can repetitively read this node till link is found UP. It can +sleep between two read. + +wait till msi is enabled:: + + # cat no_of_msi + +Should return 4 (number of requested MSI vector) + +to send msi vector 2:: + + # echo 2 >> send_msi + # cd - diff --git a/Documentation/misc-devices/spear-pcie-gadget.txt b/Documentation/misc-devices/spear-pcie-gadget.txt deleted file mode 100644 index 89b88dee4143..000000000000 --- a/Documentation/misc-devices/spear-pcie-gadget.txt +++ /dev/null @@ -1,130 +0,0 @@ -Spear PCIe Gadget Driver: - -Author -============= -Pratyush Anand (pratyush.anand@gmail.com) - -Location -============ -driver/misc/spear13xx_pcie_gadget.c - -Supported Chip: -=================== -SPEAr1300 -SPEAr1310 - -Menuconfig option: -========================== -Device Drivers - Misc devices - PCIe gadget support for SPEAr13XX platform -purpose -=========== -This driver has several nodes which can be read/written by configfs interface. -Its main purpose is to configure selected dual mode PCIe controller as device -and then program its various registers to configure it as a particular device -type. This driver can be used to show spear's PCIe device capability. - -Description of different nodes: -================================= - -read behavior of nodes: ------------------------------- -link :gives ltssm status. -int_type :type of supported interrupt -no_of_msi :zero if MSI is not enabled by host. A positive value is the - number of MSI vector granted. -vendor_id :returns programmed vendor id (hex) -device_id :returns programmed device id(hex) -bar0_size: :returns size of bar0 in hex. -bar0_address :returns address of bar0 mapped area in hex. -bar0_rw_offset :returns offset of bar0 for which bar0_data will return value. -bar0_data :returns data at bar0_rw_offset. - -write behavior of nodes: ------------------------------- -link :write UP to enable ltsmm DOWN to disable -int_type :write interrupt type to be configured and (int_type could be - INTA, MSI or NO_INT). Select MSI only when you have programmed - no_of_msi node. -no_of_msi :number of MSI vector needed. -inta :write 1 to assert INTA and 0 to de-assert. -send_msi :write MSI vector to be sent. -vendor_id :write vendor id(hex) to be programmed. -device_id :write device id(hex) to be programmed. -bar0_size :write size of bar0 in hex. default bar0 size is 1000 (hex) - bytes. -bar0_address :write address of bar0 mapped area in hex. (default mapping of - bar0 is SYSRAM1(E0800000). Always program bar size before bar - address. Kernel might modify bar size and address for alignment, so - read back bar size and address after writing to cross check. -bar0_rw_offset :write offset of bar0 for which bar0_data will write value. -bar0_data :write data to be written at bar0_rw_offset. - -Node programming example -=========================== -Program all PCIe registers in such a way that when this device is connected -to the PCIe host, then host sees this device as 1MB RAM. -#mount -t configfs none /Config -For nth PCIe Device Controller -# cd /config/pcie_gadget.n/ -Now you have all the nodes in this directory. -program vendor id as 0x104a -# echo 104A >> vendor_id - -program device id as 0xCD80 -# echo CD80 >> device_id - -program BAR0 size as 1MB -# echo 100000 >> bar0_size - -check for programmed bar0 size -# cat bar0_size - -Program BAR0 Address as DDR (0x2100000). This is the physical address of -memory, which is to be made visible to PCIe host. Similarly any other peripheral -can also be made visible to PCIe host. E.g., if you program base address of UART -as BAR0 address then when this device will be connected to a host, it will be -visible as UART. -# echo 2100000 >> bar0_address - -program interrupt type : INTA -# echo INTA >> int_type - -go for link up now. -# echo UP >> link - -It will have to be insured that, once link up is done on gadget, then only host -is initialized and start to search PCIe devices on its port. - -/*wait till link is up*/ -# cat link -wait till it returns UP. - -To assert INTA -# echo 1 >> inta - -To de-assert INTA -# echo 0 >> inta - -if MSI is to be used as interrupt, program no of msi vector needed (say4) -# echo 4 >> no_of_msi - -select MSI as interrupt type -# echo MSI >> int_type - -go for link up now -# echo UP >> link - -wait till link is up -# cat link -An application can repetitively read this node till link is found UP. It can -sleep between two read. - -wait till msi is enabled -# cat no_of_msi -Should return 4 (number of requested MSI vector) - -to send msi vector 2 -# echo 2 >> send_msi -#cd - diff --git a/Documentation/misc-devices/xilinx_sdfec.rst b/Documentation/misc-devices/xilinx_sdfec.rst index 7a47075c171c..8c8a289d69a3 100644 --- a/Documentation/misc-devices/xilinx_sdfec.rst +++ b/Documentation/misc-devices/xilinx_sdfec.rst @@ -78,7 +78,7 @@ application interfaces: - open: Implements restriction that only a single file descriptor can be open per SD-FEC instance at any time - release: Allows another file descriptor to be open, that is after current file descriptor is closed - poll: Provides a method to monitor for SD-FEC Error events - - unlocked_ioctl: Provides the the following ioctl commands that allows the application configure the SD-FEC core: + - unlocked_ioctl: Provides the following ioctl commands that allows the application configure the SD-FEC core: - :c:macro:`XSDFEC_START_DEV` - :c:macro:`XSDFEC_STOP_DEV` diff --git a/Documentation/openrisc/openrisc_port.rst b/Documentation/openrisc/openrisc_port.rst index 4b2c437942a0..657ac4af7be6 100644 --- a/Documentation/openrisc/openrisc_port.rst +++ b/Documentation/openrisc/openrisc_port.rst @@ -8,7 +8,7 @@ target architecture, specifically, is the 32-bit OpenRISC 1000 family (or1k). For information about OpenRISC processors and ongoing development: ======= ============================= - website http://openrisc.io + website https://openrisc.io email openrisc@lists.librecores.org ======= ============================= diff --git a/Documentation/powerpc/index.rst b/Documentation/powerpc/index.rst index afe2d5e54db6..748bf483b1c2 100644 --- a/Documentation/powerpc/index.rst +++ b/Documentation/powerpc/index.rst @@ -31,6 +31,7 @@ powerpc transactional_memory ultravisor vas-api + vcpudispatch_stats .. only:: subproject and html diff --git a/Documentation/powerpc/vas-api.rst b/Documentation/powerpc/vas-api.rst index 788dc8375a0e..90c50ed839f3 100644 --- a/Documentation/powerpc/vas-api.rst +++ b/Documentation/powerpc/vas-api.rst @@ -43,7 +43,7 @@ engine for this process. Once a connection is established, the application should use the mmap() system call to map the hardware address of engine's request queue into the application's virtual address space. -The application can then submit one or more requests to the the engine by +The application can then submit one or more requests to the engine by using copy/paste instructions and pasting the CRBs to the virtual address (aka paste_address) returned by mmap(). User space can close the established connection or send window by closing the file descriptior @@ -87,6 +87,7 @@ Applications may chose a specific instance of the NX co-processor using the vas_id field in the VAS_TX_WIN_OPEN ioctl as detailed below. A userspace library libnxz is available here but still in development: + https://github.com/abalib/power-gzip Applications that use inflate / deflate calls can link with libnxz @@ -110,6 +111,7 @@ Applications should use the VAS_TX_WIN_OPEN ioctl as follows to establish a connection with NX co-processor engine: :: + struct vas_tx_win_open_attr { __u32 version; __s16 vas_id; /* specific instance of vas or -1 @@ -119,8 +121,10 @@ a connection with NX co-processor engine: __u64 reserved2[6]; }; - version: The version field must be currently set to 1. - vas_id: If '-1' is passed, kernel will make a best-effort attempt + version: + The version field must be currently set to 1. + vas_id: + If '-1' is passed, kernel will make a best-effort attempt to assign an optimal instance of NX for the process. To select the specific VAS instance, refer "Discovery of available VAS engines" section below. @@ -129,7 +133,8 @@ a connection with NX co-processor engine: and must be set to 0. The attributes attr for the VAS_TX_WIN_OPEN ioctl are defined as - follows: + follows:: + #define VAS_MAGIC 'v' #define VAS_TX_WIN_OPEN _IOW(VAS_MAGIC, 1, struct vas_tx_win_open_attr) @@ -141,6 +146,8 @@ a connection with NX co-processor engine: returns -1 and sets the errno variable to indicate the error. Error conditions: + + ====== ================================================ EINVAL fd does not refer to a valid VAS device. EINVAL Invalid vas ID EINVAL version is not set with proper value @@ -149,6 +156,7 @@ a connection with NX co-processor engine: ENOSPC System has too many active windows (connections) opened EINVAL reserved fields are not set to 0. + ====== ================================================ See the ioctl(2) man page for more details, error codes and restrictions. @@ -158,11 +166,13 @@ mmap() NX-GZIP device The mmap() system call for a NX-GZIP device fd returns a paste_address that the application can use to copy/paste its CRB to the hardware engines. + :: paste_addr = mmap(addr, size, prot, flags, fd, offset); Only restrictions on mmap for a NX-GZIP device fd are: + * size should be PAGE_SIZE * offset parameter should be 0ULL @@ -170,10 +180,12 @@ that the application can use to copy/paste its CRB to the hardware engines. In addition to the error conditions listed on the mmap(2) man page, can also fail with one of the following error codes: + ====== ============================================= EINVAL fd is not associated with an open window (i.e mmap() does not follow a successful call to the VAS_TX_WIN_OPEN ioctl). EINVAL offset field is not 0ULL. + ====== ============================================= Discovery of available VAS engines ================================== @@ -210,7 +222,7 @@ In case if NX encounters translation error (called NX page fault) on CSB address or any request buffer, raises an interrupt on the CPU to handle the fault. Page fault can happen if an application passes invalid addresses or request buffers are not in memory. The operating system handles the fault by -updating CSB with the following data: +updating CSB with the following data:: csb.flags = CSB_V; csb.cc = CSB_CC_FAULT_ADDRESS; @@ -223,7 +235,7 @@ the application can resend this request to NX. If the OS can not update CSB due to invalid CSB address, sends SEGV signal to the process who opened the send window on which the original request was -issued. This signal returns with the following siginfo struct: +issued. This signal returns with the following siginfo struct:: siginfo.si_signo = SIGSEGV; siginfo.si_errno = EFAULT; @@ -248,6 +260,7 @@ Simple example ============== :: + int use_nx_gzip() { int rc, fd; diff --git a/Documentation/powerpc/vcpudispatch_stats.txt b/Documentation/powerpc/vcpudispatch_stats.rst similarity index 94% rename from Documentation/powerpc/vcpudispatch_stats.txt rename to Documentation/powerpc/vcpudispatch_stats.rst index e21476bfd78c..5704657a5987 100644 --- a/Documentation/powerpc/vcpudispatch_stats.txt +++ b/Documentation/powerpc/vcpudispatch_stats.rst @@ -1,5 +1,8 @@ -VCPU Dispatch Statistics: -========================= +.. SPDX-License-Identifier: GPL-2.0 + +======================== +VCPU Dispatch Statistics +======================== For Shared Processor LPARs, the POWER Hypervisor maintains a relatively static mapping of the LPAR processors (vcpus) to physical processor @@ -20,25 +23,29 @@ The statistics themselves are available by reading the procfs file a vcpu as represented by the first field, followed by 8 numbers. The first number corresponds to: + 1. total vcpu dispatches since the beginning of statistics collection The next 4 numbers represent vcpu dispatch dispersions: + 2. number of times this vcpu was dispatched on the same processor as last time 3. number of times this vcpu was dispatched on a different processor core as last time, but within the same chip 4. number of times this vcpu was dispatched on a different chip 5. number of times this vcpu was dispatches on a different socket/drawer -(next numa boundary) + (next numa boundary) The final 3 numbers represent statistics in relation to the home node of the vcpu: + 6. number of times this vcpu was dispatched in its home node (chip) 7. number of times this vcpu was dispatched in a different node 8. number of times this vcpu was dispatched in a node further away (numa -distance) + distance) + +An example output:: -An example output: $ sudo cat /proc/powerpc/vcpudispatch_stats cpu0 6839 4126 2683 30 0 6821 18 0 cpu1 2515 1274 1229 12 0 2509 6 0 diff --git a/Documentation/process/2.Process.rst b/Documentation/process/2.Process.rst index b21b5b245d13..3588f48841eb 100644 --- a/Documentation/process/2.Process.rst +++ b/Documentation/process/2.Process.rst @@ -295,7 +295,7 @@ mainline get there via -mm. The current -mm patch is available in the "mmotm" (-mm of the moment) directory at: - http://www.ozlabs.org/~akpm/mmotm/ + https://www.ozlabs.org/~akpm/mmotm/ Use of the MMOTM tree is likely to be a frustrating experience, though; there is a definite chance that it will not even compile. @@ -306,7 +306,7 @@ the mainline is expected to look like after the next merge window closes. Linux-next trees are announced on the linux-kernel and linux-next mailing lists when they are assembled; they can be downloaded from: - http://www.kernel.org/pub/linux/kernel/next/ + https://www.kernel.org/pub/linux/kernel/next/ Linux-next has become an integral part of the kernel development process; all patches merged during a given merge window should really have found @@ -365,21 +365,21 @@ to keep up with what other developers (and the mainline) are doing. Git is now packaged by almost all Linux distributions. There is a home page at: - http://git-scm.com/ + https://git-scm.com/ That page has pointers to documentation and tutorials. Among the kernel developers who do not use git, the most popular choice is almost certainly Mercurial: - http://www.selenic.com/mercurial/ + https://www.selenic.com/mercurial/ Mercurial shares many features with git, but it provides an interface which many find easier to use. The other tool worth knowing about is Quilt: - http://savannah.nongnu.org/projects/quilt/ + https://savannah.nongnu.org/projects/quilt/ Quilt is a patch management system, rather than a source code management system. It does not track history over time; it is, instead, oriented @@ -494,7 +494,7 @@ Andrew Morton gives this advice for aspiring kernel developers with others on getting things fixed up (this can require persistence!) but that's fine - it's a part of kernel development. -(http://lwn.net/Articles/283982/). +(https://lwn.net/Articles/283982/). In the absence of obvious problems to fix, developers are advised to look at the current lists of regressions and open bugs in general. There is diff --git a/Documentation/process/4.Coding.rst b/Documentation/process/4.Coding.rst index 13dd893c9f88..c27e59d2f702 100644 --- a/Documentation/process/4.Coding.rst +++ b/Documentation/process/4.Coding.rst @@ -210,7 +210,7 @@ breaks? The best answer to this question was expressed by Linus in July, progress at all. Is it two steps forwards, one step back, or one step forward and two steps back? -(http://lwn.net/Articles/243460/). +(https://lwn.net/Articles/243460/). An especially unwelcome type of regression is any sort of change to the user-space ABI. Once an interface has been exported to user space, it must @@ -323,7 +323,7 @@ other architectures. If you do not happen to have an S/390 system or a Blackfin development board handy, you can still perform the compilation step. A large set of cross compilers for x86 systems can be found at - http://www.kernel.org/pub/tools/crosstool/ + https://www.kernel.org/pub/tools/crosstool/ Some time spent installing and using these compilers will help avoid embarrassment later. diff --git a/Documentation/process/botching-up-ioctls.rst b/Documentation/process/botching-up-ioctls.rst index 2d4829b2fb09..ba4667ab396b 100644 --- a/Documentation/process/botching-up-ioctls.rst +++ b/Documentation/process/botching-up-ioctls.rst @@ -2,7 +2,7 @@ (How to avoid) Botching up ioctls ================================= -From: http://blog.ffwll.ch/2013/11/botching-up-ioctls.html +From: https://blog.ffwll.ch/2013/11/botching-up-ioctls.html By: Daniel Vetter, Copyright © 2013 Intel Corporation diff --git a/Documentation/process/changes.rst b/Documentation/process/changes.rst index 8f68e728ae6b..ee741763a3fc 100644 --- a/Documentation/process/changes.rst +++ b/Documentation/process/changes.rst @@ -129,7 +129,7 @@ Architectural changes --------------------- DevFS has been obsoleted in favour of udev -(http://www.kernel.org/pub/linux/utils/kernel/hotplug/) +(https://www.kernel.org/pub/linux/utils/kernel/hotplug/) 32-bit UID support is now in place. Have fun! @@ -421,7 +421,7 @@ Intel P6 microcode udev ---- -- +- FUSE ---- @@ -474,4 +474,4 @@ Kernel documentation Sphinx ------ -- +- diff --git a/Documentation/process/clang-format.rst b/Documentation/process/clang-format.rst index 6710c0707721..82676e5a7c6e 100644 --- a/Documentation/process/clang-format.rst +++ b/Documentation/process/clang-format.rst @@ -32,7 +32,7 @@ Linux distributions for a long time. Search for ``clang-format`` in your repositories. Otherwise, you can either download pre-built LLVM/clang binaries or build the source code from: - http://releases.llvm.org/download.html + https://releases.llvm.org/download.html See more information about the tool at: diff --git a/Documentation/process/coding-style.rst b/Documentation/process/coding-style.rst index 1bee6f8affdb..98227226c4e5 100644 --- a/Documentation/process/coding-style.rst +++ b/Documentation/process/coding-style.rst @@ -1149,7 +1149,7 @@ Addison-Wesley, Inc., 1999. ISBN 0-201-61586-X. GNU manuals - where in compliance with K&R and this text - for cpp, gcc, -gcc internals and indent, all available from http://www.gnu.org/manual/ +gcc internals and indent, all available from https://www.gnu.org/manual/ WG14 is the international standardization working group for the programming language C, URL: http://www.open-std.org/JTC1/SC22/WG14/ diff --git a/Documentation/process/deprecated.rst b/Documentation/process/deprecated.rst index 943a926ecbbb..4a9aa4f0681e 100644 --- a/Documentation/process/deprecated.rst +++ b/Documentation/process/deprecated.rst @@ -103,6 +103,11 @@ Instead, use the helper:: header = kzalloc(struct_size(header, item, count), GFP_KERNEL); +.. note:: If you are using struct_size() on a structure containing a zero-length + or a one-element array as a trailing array member, please refactor such + array usage and switch to a `flexible array member + <#zero-length-and-one-element-arrays>`_ instead. + See array_size(), array3_size(), and struct_size(), for more details as well as the related check_add_overflow() and check_mul_overflow() family of functions. @@ -218,3 +223,116 @@ All switch/case blocks must end in one of: * continue; * goto